PHP Manual

# Manual de PHP

2026-06-23
por:
¿Quieres ayudarnos a traducir? Ponte en contacto con: seros[arroba]php.net
Traduciendo desde Dic-2009. Estado: 80% completo y al día.
Lista de encargados del mantenimiento y traducción por número de ficheros:
1. Pedro Antonio Gil Rodríguez 2. Andrés García 3. Yago Ferrer 4. Jesús Ruiz-Ayúcar Vázquez 5. Juan Pablo Berdejo 6. Alexander Garzon 7. Jesús Ruiz García 8. Marta Regina Cano Jiménez 9. Leonardo Boshell 10. Francisco José Naranjo Abad 11. Jesús Rafael Cova Huerta 12. Jorge Eduardo Olaya P. 13. Edwin Cartagena Hdez. 14. Jesús Díez 15. Diego Agulló Falcó 16. Ernesto Mediavilla del Río 17. Carlos Hernández Afan de Ribera 18. Waldo Malqui Silva 19. Braian Iván Monnier 20. José Mercedes Venegas Acevedo
y muchos más...

# Copyright

Copyright © 1997 - 2026 por el PHP Documentation Group. Este material puede ser distribuido solamente sujeto a los términos y condiciones establecidos por la licencia de Creative Commons Attribution 3.0 o superior. Una copia de la Licencia de Commons Attribution 3.0 está distribuida con este manual. La versión más reciente está disponible en » http://creativecommons.org/licenses/by/3.0/.

# Manual de PHP

# Acerca de este manual

PHP, que significa PHP: Preprocesador de Hipertexto, es un lenguaje de programación de propósito general, de código abierto y ampliamente utilizado, especialmente adecuado para el desarrollo web y que se puede incrustar en HTML. Su sintaxis se basa en C, Java y Perl, y es fácil de aprender. El objetivo principal del lenguaje es permitir a los desarrolladores web escribir páginas web dinámicas rápidamente, pero se puede hacer mucho más con PHP.

Este manual consiste principalmente en una referencia de funciones, aunque también contiene una referencia del lenguaje, explicaciones de algunas de las características importantes de PHP, y otra información suplementaria.

Este manual incluye información sobre las dos versiones principales más recientes de PHP (versiones 7 y 8). No se incluye información sobre extensiones que ya no forman parte de estas versiones de PHP ni sobre cambios en funciones de versiones anteriores. Los archivos de versiones antiguas del manual, que documentan lanzamientos previos de PHP, están disponibles en la sección "Más documentación" en la » página de "Documentación" del sitio web de PHP.

Este manual se puede descargar en diferentes formatos en » https://www.php.net/download-docs.php. Puede encontrarse más información sobre cómo se desarrolla este manual en el apéndice "Acerca de este manual". Si está interesado en la Historia de PHP, visite el apéndice correspondiente.

# Autores y Contribuyentes

Destacamos a las personas más activas en el prólogo del manual pero hay muchos más contribuyentes que nos ayudan actualmente en nuestro trabajo o que han proporcionado ayuda preciosa al proyecto en el pasado. Hay muchos desconocidos que nos han ayudado mediante sus notas concernientes a las páginas del manual que son continuamente incluidas en el manual, trabajo del cual estamos muy agradecidos. La lista proporcionada a continuación está ordenada alfabéticamente.

# Autores y Editores

Los siguientes contribuyentes han tenido un impacto enorme al añadir contenido al manual: Mehdi Achour, Bill Abt, Jouni Ahto, Alexander Aulbach, Stig Bakken, George Peter Banyard, Christoph M. Becker, Daniel Beckham, Friedhelm Betz, Nilgün Belma Bugüner, Jesus M. Castagnetto, Ron Chmara, Sean Coates, John Coggeshall, Simone Cortesi, Peter Cowburn, Antony Dovgal, Daniel Egeberg, Markus Fischer, Wez Furlong, Sara Golemon, Rui Hirokawa, Brad House, Pierre-Alain Joye, Etienne Kneuss, Moriyoshi Koizumi, Rasmus Lerdorf, Andrew Lindeman, Nuno Lopes, Hannes Magnusson, Stanislav Malyshev, Justin Martin, Rafael Martinez, Rick McGuire, Moacir de Oliveira Miranda Júnior, Kalle Sommer Nielsen, Yasuo Ohgaki, Philip Olson, Richard Quadling, Derick Rethans, Rob Richards, Georg Richter, Sander Roobol, Egon Schmid, Thomas Schoefbeck, Sascha Schumann, Dan Scott, Damien Seguy, Masahiro Takagi, Yoshinari Takaoka, Yannick Torres, Jakub Vrana, Michael Wallner, Lars Torben Wilson, Jim Winstead, Jeroen van Wolffelaar y Andrei Zmievski.

Los siguientes contribuyentes han ayudado enormemente en la edición del manual: Stig Bakken, Peter Cowburn, Gabor Hojtsy, Hartmut Holzgraefe, Philip Olson y Egon Schmid.

# Mantenimiento de las notas de usuarios

Los mantenimientos actualmente más activos son: Daniel Brown, Nuno Lopes, Felipe Pena, Thiago Pojda y Maciek Sokolewicz.

Estas personas también han desplegado enormes esfuerzos en el mantenimiento de las notas de usuarios: Mehdi Achour, Daniel Beckham, Friedhelm Betz, Victor Boivie, Jesus M. Castagnetto, Nicolas Chaillan, Ron Chmara, Sean Coates, James Cox, Vincent Gevers, Sara Golemon, Zak Greant, Szabolcs Heilig, Oliver Hinckel, Hartmut Holzgraefe, Etienne Kneuss, Rasmus Lerdorf, Matthew Li, Andrew Lindeman, Aidan Lister, Hannes Magnusson, Maxim Maletsky, Bobby Matthis, James Moore, Philip Olson, Sebastian Picklum, Derick Rethans, Sander Roobol, Damien Seguy, Jason Sheets, Tom Sommer, Jani Taskinen, Yasuo Ohgaki, Jakub Vrana, Lars Torben Wilson, Jim Winstead, Jared Wyles y Jeroen van Wolffelaar.

# Conceptos básicos

# ¿Qué es PHP y qué puede hacer?

# ¿Qué es PHP?

PHP (oficialmente, este sigle es un acrónimo recursivo para PHP Hypertext Preprocessor) es un lenguaje de scripts generalista y Open Source, especialmente concebido para el desarrollo de aplicaciones web. Puede ser integrado fácilmente al HTML.

Bien... pero ¿qué significa esto? Un ejemplo:

Ejemplo #1 Ejemplo de introducción

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

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

    </body>
    </html>

En lugar de utilizar toneladas de comandos para mostrar HTML (como en C o en Perl), las páginas PHP contienen fragmentos HTML con código que hace "algo" (en este caso, mostrará "Hola, soy un script PHP!"). El código PHP está incluido entre una etiqueta de inicio `<?php` y una etiqueta de fin `?>` que permiten al servidor web pasar al modo PHP.

Lo que distingue a PHP de los lenguajes de script como JavaScript, es que el código se ejecuta en el servidor, generando así el HTML, que será luego enviado al cliente. El cliente solo recibe el resultado del script, sin ningún medio de acceso al código que produjo dicho resultado. Se puede configurar el servidor web para que analice todos los ficheros HTML como ficheros PHP. Así, no hay manera de distinguir las páginas que son producidas dinámicamente de las páginas estáticas. Un servidor web puede incluso ser configurado para procesar todos los ficheros HTML con PHP, y no hay manera para los usuarios de saber que PHP está siendo utilizado.

La gran ventaja de PHP es que es extremadamente simple para los principiantes, pero ofrece funcionalidades avanzadas para los expertos. No tema leer la larga lista de funcionalidades PHP. Con PHP, casi todo el mundo puede comenzar rápidamente y escribir scripts simples en poco tiempo.

Aunque el desarrollo de PHP está orientado hacia la programación para sitios web, se puede hacer mucho más con PHP. Lea la sección ¿Qué puede hacer PHP? o el tutorial de introducción para pasar directamente al aprendizaje de la programación web.

# ¿Qué puede hacer PHP?

Todo. PHP está principalmente concebido para servir como lenguaje de script del lado del servidor, por lo que puede hacer todo lo que cualquier otro programa CGI puede hacer, como recolectar datos de formularios, generar contenido dinámico, o gestionar cookies. Pero PHP puede hacer mucho más.

Hay dos ámbitos diferentes donde PHP puede destacar.

- Lenguaje de script del lado del servidor. Este es el uso más tradicional, y también el principal objetivo de PHP. Tres componentes son necesarios para explotarlo: un analizador PHP (CGI o módulo del servidor), un servidor web y un navegador web. Se debe ejecutar el servidor web en correlación con PHP. Se puede acceder al programa PHP con la ayuda del navegador web. Todo esto puede funcionar en una máquina local solo para experimentar la programación PHP. Vea la sección de instalación para más información.
- Lenguaje de programación en línea de comandos. Un script PHP puede ser ejecutado en línea de comandos, sin la ayuda del servidor web y de un navegador. Solo se necesita el ejecutable PHP. Este uso es ideal para los scripts que se ejecutan regularmente con un cron en Unix o Linux o un gestor de tareas (en Windows). Estos scripts también pueden ser utilizados para realizar operaciones en ficheros de texto. Vea la sección sobre el uso de PHP en línea de comandos para más información.

PHP es utilizable en la mayoría de los sistemas operativos, como Linux, muchas variantes Unix (incluyendo HP-UX, Solaris y OpenBSD), Microsoft Windows, macOS, RISC OS y otros más. PHP también soporta la mayoría de los servidores web actuales como Apache, IIS y muchos otros. Y esto incluye todos los servidores web que pueden utilizar el binario PHP FastCGI, como lighttpd y nginx. PHP funciona como módulo, o como procesador CGI.

Con PHP, los desarrolladores tienen la opción del sistema operativo y del servidor web. Además, también tienen la opción de utilizar la programación procedimental u orientada a objetos (OOP), o incluso una mezcla de ambas.

Con PHP, no se limita a la producción de código HTML. Las capacidades de PHP incluyen la creación de tipos de ficheros ricos, como imágenes o ficheros PDF, el cifrado de datos y el envío de correos electrónicos. También puede generar fácilmente cualquier texto, como JSON o XML. PHP puede generar automáticamente estos ficheros y guardarlos en el sistema de ficheros en lugar de imprimirlos, formando así una caché del lado del servidor para contenido dinámico.

Una de las fortalezas más significativas de PHP es que soporta enormemente bases de datos. Escribir una página web que utilice una base de datos se vuelve extremadamente simple, utilizando una de las extensiones específicas para bases de datos (i.e., para mysql), o utilizando una clase de abstracción como PDO, o una conexión a cualquier base de datos que soporte la conexión estándar abierta a través de la extensión ODBC. Otras bases de datos pueden utilizar la extensión cURL o sockets como CouchDB.

PHP soporta numerosos protocolos como LDAP, IMAP, SNMP, NNTP, POP3, HTTP, COM (en Windows) y muchos otros. También puede abrir sockets de red, e interactuar con cualquier otro protocolo. PHP soporta el formato complejo WDDX, que permite la comunicación entre todos los lenguajes web. En términos de interconexión, PHP también soporta los objetos Java, y los utiliza de manera transparente como objetos integrados.

PHP posee funcionalidades útiles en el tratamiento de texto, incluyendo las expresiones regulares compatibles con Perl (PCRE), así como un gran número de extensiones y utilidades para analizar y acceder a documentos XML. PHP estandariza todas las extensiones XML sobre la sólida base de libxml2, y extiende el conjunto de funcionalidades añadiendo soporte para SimpleXML, XMLReader y XMLWriter.

Muchas otras extensiones existen, categorizadas alfabéticamente y por categoría. Y finalmente, existen extensiones PECL que pueden (o no) estar documentadas en el manual PHP, como » XDebug.

Esta página no es lo suficientemente grande para listar todas las potentes funcionalidades de PHP. Lea la sección sobre la instalación de PHP y estudie la lista de funciones para obtener más detalles sobre todas estas tecnologías.

# Un tutorial sencillo

## Tabla de contenidos

- Su primera página habilitada para PHP
- Algo útil
- Tratar con formularios
- ¿Qué sigue?

Aquí nos gustaría mostrar los aspectos más básicos de PHP en un tutorial breve y sencillo. Este texto solo trata sobre la creación de páginas web dinámicas con PHP, aunque PHP no solo es capaz de crear páginas web. Consulte la sección titulada ¿Qué puede hacer PHP para obtener más información.

Las páginas web habilitadas para PHP se tratan exactamente igual que las páginas HTML regulares y puede crearlas y editarlas de la misma manera que normalmente crea páginas HTML regulares.

# Su primera página habilitada para PHP

Este tutorial asume que PHP ya está instalado. Las instrucciones de instalación se pueden encontrar en la » página de descargas.

Cree un fichero llamado hello.php con el siguiente contenido:

Ejemplo #1 Nuestro primer script PHP: hello.php

    <?php

    echo "Hello World!";

    ?>

Usando su terminal, navegue hasta el directorio que contiene este fichero y inicie un servidor de desarrollo con el siguiente comando:

    php -S localhost:8000

Utilice su navegador para acceder al fichero con la URL de su servidor web, terminando con la referencia al fichero `/hello.php`. Según el comando anterior ejecutado, la URL será `http://localhost:8000/hello.php`. Si todo está configurado correctamente, este fichero será analizado por PHP y verá la salida "Hello World!" mostrada en su navegador.

PHP puede incrustarse dentro de una página web HTML normal. Esto significa que dentro de su documento HTML puede escribir las sentencias PHP, como se demuestra en el siguiente ejemplo:

    <!DOCTYPE html>
    <html>
        <head>
            <title>Prueba de PHP</title>
        </head>
        <body>
            <?php echo '<p>Hello World</p>'; ?>
        </body>
    </html>

Esto producirá la siguiente salida:

    <!DOCTYPE html>
    <html>
        <head>
            <title>Prueba de PHP</title>
        </head>
        <body>
            <p>Hello World</p>
        </body>
    </html>

Este programa es extremadamente simple y realmente no necesitaba usar PHP para crear una página como esta. Todo lo que hace es mostrar: `Hello World` usando la sentencia echo de PHP. Observe que el fichero no necesita ser ejecutable ni especial de ninguna manera. El servidor descubre que este fichero necesita ser interpretado por PHP porque usó la extensión ".php", que el servidor está configurado para pasar a PHP. Piense en esto como un fichero HTML normal que por casualidad tiene un conjunto de etiquetas especiales disponibles que hacen muchas cosas interesantes.

El objetivo del ejemplo es mostrar el formato especial de las etiquetas PHP. En este ejemplo usamos `<?php` para indicar el inicio de una etiqueta PHP. Luego pusimos la sentencia PHP y salimos del modo PHP añadiendo la etiqueta de cierre, `?>`. Puede entrar y salir del modo PHP en un fichero HTML como este donde quiera. Para más detalles, lea la sección del manual sobre la sintaxis básica de PHP.

> Nota: Una nota sobre los saltos de línea

> Los saltos de línea tienen poco significado en HTML, sin embargo sigue siendo una buena idea hacer que su HTML se vea bien y limpio poniendo saltos de línea. Un salto de línea que sigue inmediatamente después de un cierre `?>` será eliminado por PHP. Esto puede ser extremadamente útil cuando está poniendo muchos bloques de PHP o ficheros incluidos que contienen PHP y que no deberían mostrar nada. Al mismo tiempo puede ser un poco confuso. Puede poner un espacio después del cierre `?>` para forzar que se muestre un espacio y un salto de línea, o puede poner un salto de línea explícito en el último echo/print desde dentro de su bloque PHP.

> Nota: Una nota sobre los editores de texto

> Hay muchos editores de texto y Entornos de Desarrollo Integrados (IDE) que puede usar para crear, editar y gestionar ficheros PHP. Una lista parcial de estas herramientas se mantiene en » Lista de editores PHP. Si desea recomendar un editor, por favor visite la página anterior y pídale al responsable de la página que añada el editor a la lista. Tener un editor con resaltado de sintaxis puede ser útil.

> Nota: Una nota sobre los procesadores de texto

> Los procesadores de texto como StarOffice Writer, Microsoft Word y Abiword no son óptimos para editar ficheros PHP. Si desea usar uno para este script de prueba, debe asegurarse de guardar el fichero como texto plano o PHP no podrá leer y ejecutar el script.

Ahora que ha creado con éxito un script PHP funcional, es hora de crear ¡el script PHP más famoso! Haga una llamada a la función phpinfo() y verá mucha información útil sobre su sistema y configuración, como las variables predefinidas disponibles, los módulos PHP cargados y las configuraciones. Tómese su tiempo y revise esta información importante.

Ejemplo #2 Obtener información del sistema desde PHP

    <?php

    phpinfo();

    ?>

# Algo útil

Ahora hagamos algo más útil. Vamos a comprobar qué tipo de navegador está usando el visitante. Para ello, comprobamos la cadena del agente de usuario que el navegador envía como parte de la petición HTTP. Esta información se almacena en una variable. Las variables siempre comienzan con un signo de dólar en PHP. La variable que nos interesa ahora es $_SERVER['HTTP_USER_AGENT'].

> Nota:

> $_SERVER es una variable especial reservada de PHP que contiene toda la información del servidor web. Se la conoce como superglobal. Consulte la página relacionada del manual sobre superglobals para obtener más información.

Para mostrar esta variable, puede hacer simplemente:

Ejemplo #1 Mostrar una variable (elemento de array)

    <?php

    echo $_SERVER['HTTP_USER_AGENT'];

    ?>

Una salida de ejemplo de este script podría ser:

    Mozilla/5.0 (Linux) Firefox/112.0

Hay muchos tipos de variables disponibles en PHP. En el ejemplo anterior imprimimos un elemento de un array variable. Los arrays pueden ser muy útiles.

$_SERVER es solo una variable que PHP hace automáticamente disponible. Puede ver una lista en la sección Variables Reservadas del manual o puede obtener una lista completa de ellas mirando la salida de la función phpinfo() usada en el ejemplo de la sección anterior.

Puede poner múltiples sentencias PHP dentro de una etiqueta PHP y crear pequeños bloques de código que hacen más que un simple echo. Por ejemplo, si quiere comprobar si se está usando Firefox puede hacer esto:

Ejemplo #2 Ejemplo usando estructuras de control y funciones

    <?php

    if (str_contains($_SERVER['HTTP_USER_AGENT'], 'Firefox')) {
        echo 'Está usando Firefox.';
    }

    ?>

Una salida de ejemplo de este script podría ser:

    Está usando Firefox.

Aquí introducimos un par de conceptos nuevos. Tenemos una sentencia if. Si está familiarizado con la sintaxis básica usada por el lenguaje C, esto debería parecerle lógico. De lo contrario, debería leer un libro introductorio de PHP o los primeros capítulos, o leer la parte de Referencia del Lenguaje del manual.

El segundo concepto que introdujimos fue la llamada a la función str_contains(). str_contains() es una función integrada en PHP que determina si una cadena dada contiene otra cadena. En este caso estamos buscando `'Firefox'` (la llamada aguja) dentro de $_SERVER['HTTP_USER_AGENT'] (la llamada pajar). Si la aguja se encuentra dentro del pajar, la función devuelve true. De lo contrario, devuelve `false`. Si devuelve `true`, la expresión if se evalúa como `true` y se ejecuta el código dentro de sus {llaves}. De lo contrario, el código no se ejecuta. Siéntase libre de crear ejemplos similares, con if, else, y otras funciones como strtoupper() y strlen(). Cada página relacionada del manual contiene ejemplos también. Si no está seguro de cómo usar funciones, querrá leer tanto la página del manual sobre cómo leer una definición de función como la sección sobre funciones de PHP.

Podemos llevar esto un paso más allá y mostrar cómo puede entrar y salir del modo PHP incluso en medio de un bloque PHP:

Ejemplo #3 Mezclar ambos modos HTML y PHP

    <?php
    if (str_contains($_SERVER['HTTP_USER_AGENT'], 'Firefox')) {
        ?>
        <h3>str_contains() devolvió true</h3>
        <p>Está usando Firefox</p>
        <?php
    } else {
        ?>
        <h3>str_contains() devolvió false</h3>
        <p>No está usando Firefox</p>
        <?php
    }
    ?>

Una salida de ejemplo de este script podría ser:

    <h3>str_contains() devolvió true</h3>
    <p>Está usando Firefox</p>

En lugar de usar una sentencia echo de PHP para mostrar algo, salimos del modo PHP y enviamos directamente HTML. El punto importante y potente a notar aquí es que el flujo lógico del script permanece intacto. Solo uno de los bloques HTML terminará siendo enviado al espectador dependiendo del resultado de str_contains(). En otras palabras, depende de si la cadena `Firefox` fue encontrada o no.

# Tratar con formularios

Una de las características más poderosas de PHP es la forma en que maneja los formularios HTML. El concepto básico que es importante entender es que cualquier elemento de formulario estará automáticamente disponible para sus scripts PHP. Por favor, lea la sección del manual sobre Variables desde fuentes externas para obtener más información y ejemplos sobre el uso de formularios con PHP. Aquí hay un ejemplo de formulario HTML:

Ejemplo #1 Un formulario HTML sencillo

    <form action="action.php" method="post">
        <label for="name">Su nombre:</label>
        <input name="name" id="name" type="text">

        <label for="age">Su edad:</label>
        <input name="age" id="age" type="number">

        <button type="submit">Enviar</button>
    </form>

No hay nada especial en este formulario. Es un formulario HTML directo sin ninguna etiqueta especial. Cuando el usuario rellena este formulario y pulsa el botón de enviar, se invoca la página action.php. En este fichero escribiría algo como esto:

Ejemplo #2 Mostrar datos de nuestro formulario

    Hola <?php echo htmlspecialchars($_POST['name']); ?>.
    Tiene <?php echo (int) $_POST['age']; ?> años.

Una salida de ejemplo de este script podría ser:

    Hola Joe. Tiene 22 años.

Aparte de las partes htmlspecialchars() y `(int)`, debería ser obvio lo que hace esto. htmlspecialchars() asegura que cualquier carácter que sea especial en HTML se codifique correctamente para que la gente no pueda inyectar etiquetas HTML o Javascript en su página. Para el campo de edad, ya que sabemos que es un número, podemos simplemente convertirlo a un int que automáticamente eliminará cualquier carácter adicional. También puede hacer que PHP haga esto automáticamente por usted usando la extensión filter. Las variables $_POST['name'] y $_POST['age'] son establecidas automáticamente por PHP. Anteriormente usamos la superglobal $_SERVER; arriba acabamos de introducir la superglobal $_POST que contiene todos los datos POST. Observe cómo el método de nuestro formulario es POST. Si hubiéramos usado el método GET entonces nuestra información del formulario viviría en la superglobal $_GET en su lugar. También puede usar la superglobal $_REQUEST si no le importa la fuente de sus datos de petición. Contiene la información combinada de los datos GET, POST y COOKIE.

# ¿Qué sigue?

Con sus nuevos conocimientos debería ser capaz de entender la mayoría del manual.

En particular puede que quiera explorar las siguientes características:

- Leer y escribir ficheros con las funciones del sistema de ficheros
- Manejo de subidas de ficheros
- Obtener páginas y ficheros remotos con Curl
- Almacenar y analizar datos en una base de datos con PDO (SQLite puede usarse sin ejecutar un servidor de base de datos)
- Persistir datos entre peticiones con Sesiones

Hay un tesoro de bibliotecas y » marcos de referencia para cada ocasión en el repositorio » Packagist, todos instalables mediante el gestor de paquetes Composer.

Para obtener ayuda y consejos de la comunidad, consulte la » página de ayuda.

Para una variedad de podcasts, presentaciones y otros vídeos, consulte el » PeerTube de la comunidad.

Otros recursos de la comunidad que le ayudarán incluyen "listas increíbles" (directorios curados de enlaces) y "mapas de ruta para desarrolladores" (listas de temas relacionados).

Cuando se quede atascado sin saber por dónde empezar, intente dividir su proyecto o problema en partes más pequeñas, lo que le permitirá ver más fácilmente qué ya sabe hacer y qué necesita aprender. La lista puede ser tan detallada como necesite. Por ejemplo, construir un blog podría desglosarse en las siguientes partes:

- Listar y ver páginas
  - Leer registros (páginas) de una base de datos
- Crear páginas
  - Manejar el envío del formulario
  - Escribir registros (páginas) en una base de datos
- Acceso de administrador
  - Leer registros (usuarios) de una base de datos
  - Manejar contraseñas
  - Persistir datos (inicio de sesión de usuario) entre peticiones/páginas (sesiones)

Si no hay nada en particular que quiera construir, puede intentar buscar ejercicios de codificación como katas, desafíos y "code golf". Incluso cuando no están específicamente dirigidos a PHP, la mayoría deberían poder completarse y probablemente desafiarán sus conocimientos y pensamiento.

- Introducción — ¿Qué es PHP y qué puede hacer?
- Un tutorial sencillo
  - Su primera página habilitada para PHP
  - Algo útil
  - Tratar con formularios
  - ¿Qué sigue?

# Instalación y configuración

# Consideraciones generales sobre la instalación

Antes de instalar PHP, es necesario saber qué se desea hacer con PHP. Existen dos casos de uso que se describen en la sección ¿Qué puede hacer PHP?:

- Sitios Web y aplicaciones Web (script lado-servidor)
- Scripts en línea de comandos

Para la primera tarea, que es con diferencia la más común, se necesitan tres cosas: PHP en sí, un servidor Web y un navegador. Probablemente ya se dispone de un navegador y, dependiendo del sistema operativo, también puede disponer de un servidor Web (i.e. Apache en Linux y macOS o IIS en Windows). También es posible alquilar un espacio a una empresa. De esta manera, no será necesario configurar PHP, sino únicamente escribir los scripts, cargarlos en el servidor y ver el resultado en el navegador.

Si se instala PHP y el servidor por uno mismo, se tienen dos opciones. O bien como un módulo del servidor Web (a través de una interfaz directa llamada SAPI). Los servidores que soportan esta solución incluyen, entre otros, Apache y Microsoft Internet Information Server. Si PHP no soporta la interfaz de módulo del servidor Web, siempre es posible utilizarlo como procesador CGI o FastCGI. Esto significa que se debe configurar el servidor para que utilice el ejecutable CGI de PHP, para que procese los ficheros PHP en el servidor.

Si también se desea utilizar PHP en línea de comandos (escribir scripts de generación de imágenes fuera de línea, por ejemplo, o bien procesar textos en función de la información proporcionada), se necesitará un ejecutable PHP. Para más detalles, lea la sección escribir aplicaciones PHP en línea de comandos. En este caso, no se necesitará un servidor Web ni un navegador.

A partir de ahora, esta sección describe la instalación de PHP con un servidor Web en Unix y Windows, ya sea como módulo o como ejecutables CGI.

El código fuente y los ejecutables compilados para ciertos sistemas operativos (incluyendo Windows) están disponibles en » https://www.php.net/downloads.php.

# Instalación en sistemas Unix

## Tabla de contenidos

- Instalación desde paquetes en Debian GNU/Linux y distribuciones similares
- Instalación a partir de paquetes en distribuciones GNU/Linux que utilizan DNF
- Instalación desde paquetes o puertos en OpenBSD
- Instalación desde las fuentes en sistemas Unix y macOS
- CGI y configuraciones de línea de comandos
- Apache 2.x en sistemas Unix
- Nginx 1.4.x en sistemas Unix
- Lighttpd 1.4 en sistemas Unix
- Servidor Web LiteSpeed/Servidor Web OpenLiteSpeed en sistemas Unix
- Instalación en Solaris

La mayoría de los sistemas operativos y distribuciones Unix (y Linux) ofrecen una versión empaquetada de PHP y extensiones disponibles a través de su sistema de gestión de paquetes. Hay secciones con información básica sobre la instalación de PHP usando estos sistemas.

Para algunas distribuciones, también existen repositorios de paquetes de terceros que suelen incluir una mayor variedad de versiones y extensiones disponibles.

PHP también puede ser instalado como un componente de ciertos servidores de aplicaciones de terceros .

Por último, PHP siempre puede instalarse desde las distribuciones fuente, lo que ofrece la mayor flexibilidad a la hora de elegir qué características, extensiones y APIs de servidor habilitar. Hay secciones que contienen información sobre la compilación y configuración configuración de PHP para su uso con diferentes APIs de servidor en particular.

## Instalación desde paquetes en Debian GNU/Linux y distribuciones similares

Aunque PHP puede ser instalado desde el código fuente, también está disponible a través de paquetes provenientes de » Debian GNU/Linux. Esto también es cierto para otras distribuciones basadas en Debian, tales como Ubuntu, Kali Linux y Linux Mint.

Advertencia

Las versiones provenientes de terceros son consideradas no oficiales y no son directamente soportadas por el proyecto PHP. Cualquier bug encontrado debe ser reportado al proveedor de estas versiones no oficiales, a menos que pueda ser reproducido utilizando las versiones provenientes de » la zona de descargas oficial.

Los paquetes pueden ser instalados utilizando la comando apt o la comando aptitude. Esta página de manual utiliza estos dos comandos de manera intercambiable.

### Uso de APT

En primer lugar, tenga en cuenta que otros paquetes pueden ser deseables, como `libapache-mod-php` para la integración con Apache 2, y `php-pear` para PEAR.

Luego, antes de instalar un paquete, es prudente asegurarse de que la lista de paquetes esté actualizada. Generalmente, esto se hace utilizando el comando apt update.

Ejemplo #1 Ejemplo de instalación en Debian con Apache 2

    # apt install php-common libapache2-mod-php php-cli

APT instalará y activará automáticamente el módulo PHP para Apache 2, así como todas sus dependencias. Apache deberá ser reiniciado para que los cambios sean efectivos. Por ejemplo:

Ejemplo #2 Detener y reiniciar Apache una vez instalado PHP

    # /etc/init.d/apache2 stop
    # /etc/init.d/apache2 start

### Un mejor control de la configuración

En el ejemplo anterior, PHP fue instalado con solo los componentes principales. Es probable que se necesiten módulos adicionales, tales como MySQL, cURL, GD, etc. También pueden ser instalados a través del comando apt.

Ejemplo #3 Métodos para listar los paquetes PHP adicionales

    # apt-cache search php
    # apt search php | grep -i mysql
    # aptitude search php

La lista de paquetes incluirá un gran número de paquetes que incluyen los componentes básicos de PHP, tales como `php-cgi`, `php-cli`, y `php-dev`, así como numerosas extensiones PHP. Durante la instalación de las extensiones, se instalarán automáticamente paquetes adicionales si es necesario para satisfacer las dependencias de estos paquetes.

Ejemplo #4 Instalar PHP con MySQL y cURL

    # apt install php-mysql php-curl

APT agregará automáticamente las líneas correctas a los ficheros relacionados con php.ini, como /etc/php/7.4/php.ini, /etc/php/7.4/conf.d/*.ini, etc., y según la extensión, agregará entradas similares a `extension=foo.so`. Además, reiniciar el servidor web (Apache, por ejemplo) es necesario para que estos cambios sean efectivos.

### Problemas comunes

- Si los scripts PHP no son interpretados por el servidor web, es probable que PHP no haya sido añadido a los ficheros de configuración del servidor web, es decir, en Debian, /etc/apache2/apache2.conf o equivalente. Consulte el manual de Debian para más detalles.
- Si una extensión ha sido aparentemente instalada pero sus funciones no están definidas, asegúrese de que las líneas adecuadas han sido insertadas en los ficheros .ini y/o que el servidor web ha sido reiniciado después de la instalación.

## Instalación a partir de paquetes en distribuciones GNU/Linux que utilizan DNF

Aunque PHP puede ser instalado desde el código fuente, también está disponible a través de paquetes en sistemas que usan DNF, como Red Hat Enterprise Linux OpenSUSE, Fedora, CentOS, Rocky Linux y Oracle Enterprise Linux.

Advertencia

Las versiones provenientes de terceros son consideradas no oficiales y no son directamente soportadas por el proyecto PHP. Cualquier bug encontrado debe ser reportado al proveedor de estas versiones no oficiales, a menos que pueda ser reproducido utilizando las versiones provenientes de » la zona de descargas oficial.

Los paquetes pueden instalarse mediante el comando dnf.

### Instalación de paquetes

Para empezar, es importante señalar que se pueden desear otros paquetes vinculados, como `php-pear` para » PEAR, o `php-mysqlnd` para la extensión MySQL.

Entonces, antes de instalar un paquete, conviene asegurarse de que la lista de paquetes está actualizada. Normalmente, esto se hace ejecutando el comando dnf update.

Ejemplo #1 Ejemplo de instalación DNF

    # dnf install php php-common

DNF instalará automáticamente la configuración de PHP para el servidor web, pero puede ser necesario reiniciarlo para que los cambios surtan efecto. Por ejemplo :

Ejemplo #2 Reiniciar Apache una vez instalado PHP

    # sudo systemctl restart httpd

### Mejor control de la configuración

En la última sección, PHP ha sido instalado sólo con los módulos básicos. Es muy probable que se requieran módulos adicionales, tales como MySQL, cURL, GD, etc. También se pueden instalar mediante la función dnf.

Ejemplo #3 Métodos para listar paquetes PHP adicionales

    # dnf search php

La lista de paquetes incluirá un gran número de paquetes incluyendo componentes básicos de PHP, como `php-cli`, `php-fpm` y `php-devel`, así como numerosas extensiones de PHP. Cuando se instalan extensiones, los paquetes adicionales se instalarán automáticamente si es necesario para satisfacer las dependencias de estos paquetes.

Ejemplo #4 Instalación de PHP con MySQL, GD

    # dnf install php-mysqlnd php-gd

DNF añadirá automáticamente las líneas apropiadas a los distintos archivos vinculados a php.ini, como /etc/php/8.3/php.ini, /etc/php/8.3/conf.d/*.ini, etc. y dependiendo de la extensión añadirá entradas similares a `extension=foo.so`. Sin embargo, es necesario reiniciar el servidor web (como Apache) para que estos cambios surtan efecto.

## Instalación desde paquetes o puertos en OpenBSD

Esta sección contiene las notas específicas para la instalación de PHP en » OpenBSD.

### Uso de paquetes binarios

Este método es el método recomendado para instalar PHP en OpenBSD. También es el método más simple. El paquete core ha sido separado de los módulos y cada uno de ellos puede ser instalado y eliminado independientemente de los otros. Los ficheros necesarios están en el CD de OpenBSD o en el sitio FTP.

El paquete principal que debe ser instalado es php, que contiene el motor base (además de fpm, gettext e iconv) y podría estar disponible en varias versiones. Luego, eche un vistazo a los paquetes de módulos, como php-mysqli o php-imap. Debe utilizar el comando phpxs para activar y desactivar estos módulos en su php.ini.

Ejemplo #1 Ejemplo de instalación de PHP en OpenBSD con Ports

    # pkg_add php
    # pkg_add php-apache
    # pkg_add php-mysqli
      (instalar las bibliotecas PEAR)
    # pkg_add pear

    Siga las instrucciones mostradas con cada paquete!

      (para eliminar paquetes)
    # pkg_delete php
    # pkg_delete php-apache
    # pkg_delete php-mysqli
    # pkg_delete pear

Lea la página de manual Unix » packages(7) para más detalles sobre los paquetes binarios de OpenBSD.

### Uso de puertos

También es posible compilar PHP utilizando » el árbol de puertos. Este método es recomendado para usuarios experimentados de OpenBSD. El puerto PHP está dividido en core y extensiones. El directorio extensiones genera los subpaquetes de todos los módulos PHP. Si no desea crear estos módulos, puede utilizar el comando en línea no_* FLAVOR. Por ejemplo, para no compilar el módulo imap, utilice FLAVOR con el valor no_imap.

### Problemas comunes

- Apache y Nginx ya no son el servidor por defecto en OpenBSD, pero pueden ser fácilmente encontrados en los puertos y los paquetes. El nuevo servidor por defecto también se llama 'httpd'.
- La instalación por defecto de Apache funciona en un » contexto chroot(2), que limitará el acceso de los scripts PHP al directorio /var/www. Por lo tanto, debe crear un directorio /var/www/tmp para que las sesiones PHP sean almacenadas, o utilizar otra solución de almacenamiento. Además, los sockets de bases de datos deben ser colocados en este directorio, o utilizar la interfaz localhost. Si utiliza funciones de red con ficheros como /etc, por ejemplo /etc/resolv.conf, y /etc/services, deberá hacerlos accesibles también en /var/www/etc. El paquete OpenBSD PEAR instala automáticamente los directorios correctos.
- El paquete OpenBSD para la extensión » gd requiere Xorg. A menos que ya esté incluido después de la instalación añadiendo el conjunto de ficheros xbase.tgz, esto puede ser añadido posteriormente (ver » OpenBSD FAQ#4).

## Instalación desde las fuentes en sistemas Unix y macOS

Software requerido para la compilación:

- » GNU make
- Un compilador C (a partir de PHP 8.0.0, se requiere compatibilidad con C99; a partir de PHP 8.4.0, se requiere compatibilidad con C11)
- Un servidor web
- Cualquier componente específico de un módulo (como las bibliotecas GD, PDF, etc.)

Cuando la compilación se realiza directamente desde las fuentes de Git o después de modificaciones personalizadas, pueden ser necesarias estas herramientas adicionales:

- » autoconf:
  - PHP 7.3 y más reciente: 2.68+
  - PHP 7.2: 2.64+
  - PHP 7.1 y más antiguo: 2.59+
- » re2c:
  - PHP 8.3 y más reciente: 1.0.3+
  - PHP 8.2 y más antiguo: 0.13.4+
- » bison:
  - PHP 7.4 y más reciente: 3.0.0+
  - PHP 7.3 y más antiguo: 2.4+ (incluido Bison 3.x)

Para obtener pasos más detallados para compilar PHP desde el código fuente, véase el fichero » README.md en el archivo tarball de origen.

La configuración y el proceso inicial de compilación de PHP están controlados por el uso de las opciones de línea de comandos del script configure. Una lista de las opciones disponibles con breves explicaciones puede mostrarse ejecutando ./configure --help. Este manual documenta las diferentes opciones por separado. Las opciones básicas están disponibles en el apéndice, mientras que las diferentes opciones específicas de las extensiones están descritas en las páginas de referencia.

Después de que el script de configuración se haya ejecutado, PHP puede ser compilado usando el comando make. El capítulo de preguntas frecuentes sobre la instalación contiene más información sobre cómo manejar los problemas de compilación.

> Nota: Algunos sistemas Unix (como OpenBSD y SELinux) pueden prohibir el mapeo de páginas tanto en escritura como en ejecución por razones de seguridad, lo cual se llama » PaX MPROTECT o » protección contra las violaciones W^X. Este tipo de mapeo de memoria es necesario para el soporte JIT de PCRE, por lo tanto PHP debe ser compilado sin el soporte JIT de PCRE, o el binario debe ser incluido en la lista blanca por cualquier medio proporcionado por el sistema.

> Nota: La compilación cruzada para ARM con la cadena de herramientas de Android no es actualmente soportada.

## CGI y configuraciones de línea de comandos

Por defecto, PHP se construye como un programa CLI y CGI, que puede ser utilizado para el procesamiento de CGI. Si está ejecutando un servidor web PHP tiene soporte para los módulos, por lo general debe irse por esta solución por razones de rendimiento. Sin embargo, la versión CGI permite a los usuarios ejecutar diferentes páginas con PHP bajo diferentes identificadores de usuarios.

Advertencia

Un servidor desplegado en modo CGI se expone a varias vulnerabilidades posibles. Por favor, lea nuestra sección sobre la seguridad en modo CGI para aprender cómo protegerse contra estos ataques.

### Pruebas

Si has construido PHP como un programa CGI, puede probar su construcción escribiendo make test. Siempre es una buena idea probar su construcción. De esta manera usted puede encontrar un problema al principio con PHP en la plataforma, en lugar de tener que luchar con él más adelante.

### Utilización de variables

Algunos servidores suministrando variables de entorno no se definen en las actuales » especificación CGI/1.1. Sólo las siguientes variables no se definen: 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 y SERVER_SOFTWARE. Todo lo demás debe ser tratado como "extensiones de proveedor".

## Apache 2.x en sistemas Unix

Esta sección contiene las notas y consejos de instalación de PHP con el servidor Apache 2.x en sistemas Unix.

Advertencia

No se recomienda el uso de PHP en un entorno thread MPM, con Apache 2. Utilice el modo prefork MPM, que es el MPM por defecto para Apache 2.0 y 2.2. Para saber por qué, lea la entrada de la FAQ correspondiente a la utilización de Apache 2 en un entorno thread MPM.

La » Documentación Apache es la mejor fuente de información sobre el servidor Apache 2.x. La mayoría de la información sobre las opciones de instalación de Apache puede encontrarse allí.

La versión más reciente del servidor HTTP Apache puede obtenerse desde la » página de descarga de Apache, y una versión adaptada de PHP desde los enlaces anteriores. Esta guía cubre únicamente las bases de funcionamiento de Apache 2.x con PHP. Para más información, leer la » documentación Apache. Los números de versión se omiten aquí, para asegurarse de que las instrucciones no sean incorrectas. En los ejemplos a continuación, 'NN' deberá ser reemplazado por la versión específica de Apache a utilizar.

Actualmente hay 2 versiones de Apache 2.x - 2.4 y 2.2. Hay varias razones para elegir una sobre la otra; sin embargo, la versión 2.4 es actualmente la última versión disponible y también la que recomendamos. Sin embargo, las instrucciones contenidas en esta guía deberían funcionar para la versión 2.4 así como para la versión 2.2. Nota: Apache httpd 2.2 está oficialmente en Fin de Vida, no habrá más desarrollo ni parches para esta versión.

1. Descargue el servidor HTTP Apache desde el sitio anterior y descomprímalo :

       tar -xzf httpd-2.x.NN.tar.gz

2. De la misma manera, descargue y descomprima las fuentes de PHP :

       tar -xzf php-NN.tar.gz

3. Compile e instale Apache. Consulte la documentación sobre la instalación de Apache para más detalles sobre la compilación de este software.

       cd httpd-2_x_NN
       ./configure --enable-so
       make
       make install

4. Ahora que se tiene Apache 2.x.NN disponible bajo /usr/local/apache2, configúrelo con soporte para la carga de módulos, así como el MPM prefork estándar. Para probar la instalación, utilice el procedimiento normal para iniciar el servidor Apache, es decir:

       /usr/local/apache2/bin/apachectl start

   y deténgalo para continuar con la configuración de PHP :

       /usr/local/apache2/bin/apachectl stop

5. Ahora, configure y compile PHP. Será en este momento cuando se podrá personalizar PHP con las diversas opciones disponibles, como la lista de extensiones a activar. Ejecute ./configure --help para obtener la lista de opciones disponibles. En nuestro ejemplo, realizaremos una configuración simple, con Apache 2 y soporte MySQL.

   Si se ha construido Apache desde las fuentes, tal como se describe anteriormente, el siguiente ejemplo debería ser correcto en cuanto a las rutas hacia apxs, pero si se ha instalado Apache de otra manera, se deberán tener en cuenta las especificidades y ajustar las rutas apxs en consecuencia. Tenga en cuenta que, según las distribuciones, podría ser necesario renombrar apxs a apxs2.

       cd ../php-NN
       ./configure --with-apxs2=/usr/local/apache2/bin/apxs --with-pdo-mysql
       make
       make install

   Si se decide modificar las opciones de configuración después de la instalación, se deberán ejecutar nuevamente las etapas configure, make y make install. Entonces solo se necesitará reiniciar Apache para que el nuevo módulo surta efecto. Una recompilación de Apache no es necesaria.

   Tenga en cuenta que, salvo indicaciones contrarias, make install también instalará » PEAR, así como diversas herramientas PHP como phpize, PHP CLI y mucho más.

6. Configurar el archivo php.ini

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

   Se debe editar el archivo `.ini` para definir las opciones PHP. Si se prefiere colocar php.ini en otro directorio, utilice la opción `--with-config-file-path=/some/path` en la etapa 5.

   Si se elige el archivo php.ini-production, asegúrese de leer la lista de modificaciones correspondiente ya que puede afectar considerablemente la forma en que PHP funcionará.

7. Edite el archivo httpd.conf para cargar el módulo PHP. La ruta especificada a la derecha de la cadena LoadModule, debe corresponder a la ruta del sistema del módulo PHP. make install anterior debería haber realizado esta operación por usted, pero una simple verificación permitirá asegurarse.

   Para PHP 8:

       LoadModule php_module modules/libphp.so

   Para PHP 7:

       LoadModule php7_module modules/libphp5.so

8. Indique a Apache que analice ciertas extensiones como scripts PHP. Por ejemplo, deje que Apache pase a PHP los archivos cuya extensión es `.php`. En lugar de utilizar solo la directiva `AddType` de Apache, se desea evitar cualquier riesgo potencialmente peligroso, cuando se descarga y crea un archivo como exploit.php.jpg, de ejecución PHP. Utilizando este ejemplo, se puede tener cualquier extensión analizada por PHP. Se ha añadido `.php` para el ejemplo.

       <FilesMatch \.php$>
           SetHandler application/x-httpd-php
       </FilesMatch>

   O, si se desea permitir que los archivos `.php`, `.php2`, `.php3`, `.php4`, `.php5`, `.php6`, y `.phtml` sean analizados por PHP, pero nada más, se utilizará esto :

       <FilesMatch "\.ph(p[2-6]?|tml)$">
           SetHandler application/x-httpd-php
       </FilesMatch>

   Y para permitir que los archivos `.phps` sean manejados por el filtro del código fuente de PHP, y así, ser mostrados como código fuente con coloración sintáctica, utilice esto :

       <FilesMatch "\.phps$">
           SetHandler application/x-httpd-php-source
       </FilesMatch>

   `mod_rewrite` puede ser utilizado para permitir que cualquier archivo `.php` sea mostrado como código fuente con coloración sintáctica, sin necesidad de renombrarlo o copiarlo con una extensión `.phps`. :

       RewriteEngine On
       RewriteRule (.*\.php)s$ $1 [H=application/x-httpd-php-source]

   El filtro de código fuente PHP no debería estar activo en sistemas de producción, ya que puede exponer código confidencial o información sensible contenida en el código fuente.

9. Utilice el procedimiento normal para iniciar el servidor Apache, es decir:

       /usr/local/apache2/bin/apachectl start

   O

       service httpd restart

Si se han seguido los pasos anteriores, ahora se tiene un servidor web Apache2 funcional con soporte PHP como módulo `SAPI`. Por supuesto, hay una multitud de otras opciones de configuración disponibles con Apache y PHP. Para más información, introduzca el comando ./configure --help en el árbol de fuentes correspondiente.

Apache puede ser compilado en modo multithread, seleccionando el MPM worker, en lugar del estándar MPM prefork. Esto se hace añadiendo la siguiente opción al argumento de ./configure, en la etapa 3 anterior:

    --with-mpm=worker

Esto no debería emprenderse sin ser consciente de las consecuencias, y teniendo al menos una justa comprensión de lo que implica. La documentación de Apache sobre » MPM-Modules proporcionará información importante que permitirá tomar la decisión.

> Nota:

> La FAQ Apache MultiViews trata sobre el uso de MultiViews con PHP.

> Nota:

> Para compilar una versión multithread de Apache, el sistema de destino debe soportar threads. En este caso, PHP también debe ser construido con Zend Thread Safety (ZTS). Bajo esta configuración, no todas las extensiones estarán disponibles. Recomendamos compilar Apache con el prefork MPM-Module.

## Nginx 1.4.x en sistemas Unix

Esta documentación cubre la instalación y configuración de PHP con PHP-FPM para el servidor HTTP Nginx 1.4.x.

Este guía asume que se ha compilado Nginx a partir de las fuentes y por lo tanto todos los binarios y ficheros de configuración se encuentran en `/usr/local/nginx`. Si no es el caso y se ha obtenido Nginx por otros medios, por favor refiérase al » Wiki de Nginx para adaptar este manual a su configuración.

Este guía cubre las bases de la configuración del servidor Nginx para servir una aplicación PHP en el puerto 80. Se recomienda estudiar las documentaciones de Nginx y PHP-FPM para optimizar su instalación.

Tenga en cuenta que a lo largo de esta documentación, los números de versión han sido reemplazados por una "x" para asegurar que esta última permanezca correcta en el futuro. Recuerde reemplazarlos por su número de versión.

1. Se recomienda consultar la » documentación de Nginx para instalarla en su sistema.

2. Recuperar y descomprimir las fuentes de PHP:

       tar zxf php-x.x.x

3. Configurar y compilar PHP. Este será el momento en el que se podrá personalizar PHP con diversas opciones, como las extensiones a activar. Ejecutar ./configure --help para obtener una lista de las opciones disponibles. En nuestro ejemplo, se realizará una configuración simple con soporte PHP-FPM y MySQLi.

       cd ../php-x.x.x
       ./configure --enable-fpm --with-mysqli
       make
       sudo make install

4. Recuperar y mover los ficheros de configuración en los directorios correctos

       cp php.ini-development /usr/local/php/php.ini
       cp /usr/local/etc/php-fpm.d/www.conf.default /usr/local/etc/php-fpm.d/www.conf
       cp sapi/fpm/php-fpm /usr/local/bin

5. Es importante que se impida que Nginx pase las peticiones al backend PHP-FPM si el fichero no existe, evitando así las vulnerabilidades por inyecciones arbitrarias de scripts.

   Esto se puede realizar definiendo la directiva de configuración cgi.fix_pathinfo al valor `0` en su php.ini.

   Editar php.ini:

       vim /usr/local/php/php.ini

   Encontrar la directiva `cgi.fix_pathinfo=` y modificarla como sigue:

       cgi.fix_pathinfo=0

6. El fichero php-fpm.conf debe ser modificado para especificar que php-fpm debe ser ejecutado con el usuario www-data y el grupo www-data antes de iniciar el servicio:

       vim /usr/local/etc/php-fpm.d/www.conf

   Encontrar y modificar lo siguiente:

       ; Usuario/grupo Unix de los procesos
       ; Nota: el usuario es obligatorio. Si no se define el grupo, se usará el grupo
       ;       por defecto del usuario.
       user = www-data
       group = www-data

   El servicio php-fpm puede ahora ser iniciado:

       /usr/local/bin/php-fpm

   Este guía no va a configurar php-fpm más allá de esto; si está interesado en la configuración avanzada de php-fpm, por favor consulte la documentación.

7. Nginx debe ahora ser configurado para soportar el análisis de las aplicaciones PHP:

       vim /usr/local/nginx/conf/nginx.conf

   Modificar el bloque por defecto para que pueda servir ficheros .php:

       location / {
           root   html;
           index  index.php index.html index.htm;
       }

   La siguiente etapa asegura que los ficheros .php sean pasados al backend PHP-FPM; Bajo el bloque comentado por defecto y entre:

       location ~* \.php$ {
           fastcgi_index   index.php;
           fastcgi_pass    127.0.0.1:9000;
           include         fastcgi_params;
           fastcgi_param   SCRIPT_FILENAME    $document_root$fastcgi_script_name;
           fastcgi_param   SCRIPT_NAME        $fastcgi_script_name;
       }

   Reiniciar Nginx.

       sudo /usr/local/nginx/sbin/nginx -s stop
       sudo /usr/local/nginx/sbin/nginx

8. Crear un fichero de prueba

       rm /usr/local/nginx/html/index.html
       echo "<?php phpinfo(); ?>" >> /usr/local/nginx/html/index.php

   Ahora, navegue a http://localhost. El phpinfo() debería ser mostrado.

Siguiendo estos diferentes pasos, se debería ejecutar un servidor web Nginx con soporte de PHP como módulo `FPM` `SAPI`. Por supuesto, hay muchas más opciones de configuración disponibles para Nginx y PHP. Para más información, escriba ./configure --help en la fuente correspondiente.

## Lighttpd 1.4 en sistemas Unix

Esta sección contiene información específica sobre la instalación de PHP con Lighttpd 1.4 en sistemas Unix.

Consulte » Lighttpd para una instalación correcta de Lighttpd antes de continuar.

FastCGI es el SAPI preferido para conectar PHP y Lighttpd. FastCGI activa automáticamente php-cgi.

### Llamada de PHP por Lighttpd

Para configurar Lighttpd para que se conecte a PHP y llame al proceso FastCGI, se debe editar el fichero lighttpd.conf. Una conexión por sockets es la solución preferida para sistemas locales.

Ejemplo #1 Porción del fichero lighttpd.conf

    server.modules += ( "mod_fastcgi" )

    fastcgi.server = ( ".php" =>
      ((
        "socket" => "/tmp/php.socket",
        "bin-path" => "/usr/local/bin/php-cgi",
        "bin-environment" => (
          "PHP_FCGI_CHILDREN" => "16",
          "PHP_FCGI_MAX_REQUESTS" => "10000"
        ),
        "min-procs" => 1,
        "max-procs" => 1,
        "idle-timeout" => 20
      ))
    )

La directiva bin-path permite a lighttpd llamar al proceso FastCGI dinámicamente. PHP llamará a los hijos según la variable de entorno PHP_FCGI_CHILDREN. La directiva `bin-environment` define el entorno para los procesos llamados. PHP terminará un proceso hijo cuando el número de solicitudes especificado por PHP_FCGI_MAX_REQUESTS haya sido alcanzado. Las directivas `min-procs` y `max-procs` pueden generalmente ser ignoradas con PHP. PHP gestiona sus propios hijos y caches opcode como APC que comparte únicamente los hijos gestionados por PHP. Si `min-procs` se establece en algo superior a 1, el número total de respuestas PHP será multiplicado por PHP_FCGI_CHILDREN (2 min-procs * 16 hijos, da 32 respuestas).

### Llamada con spawn-fcgi

Lighttpd proporciona un programa llamado spawn-fcgi para facilitar las llamadas a los procesos FastCGI.

### Llamada de php-cgi

Es posible llamar a los procesos sin spawn-fcgi, con un mínimo de configuración. La variable de entorno PHP_FCGI_CHILDREN controla el número de hijos que PHP llama para gestionar las solicitudes. La variable de entorno PHP_FCGI_MAX_REQUESTS determina la duración de vida, en número de solicitudes, de cada hijo. A continuación se muestra un script bash simple que ayuda a las llamadas a los gestores PHP.

Ejemplo #2 Llamada a los gestores FastCGI

    #!/bin/sh

    # Ubicación del binario php-cgi
    PHP=/usr/local/bin/php-cgi

    # Ubicación del fichero PID
    PHP_PID=/tmp/php.pid

    # Enlace a una dirección
    #FCGI_BIND_ADDRESS=10.0.1.1:10000
    # Enlace a un socket de dominio
    FCGI_BIND_ADDRESS=/tmp/php.sock

    PHP_FCGI_CHILDREN=16
    PHP_FCGI_MAX_REQUESTS=10000

    env -i PHP_FCGI_CHILDREN=$PHP_FCGI_CHILDREN \
           PHP_FCGI_MAX_REQUESTS=$PHP_FCGI_MAX_REQUESTS \
           $PHP -b $FCGI_BIND_ADDRESS &

    echo $! > "$PHP_PID"

### Conexión a instancias FCGI remotas

Las instancias FastCGI pueden ser llamadas en múltiples máquinas remotas para distribuir las aplicaciones.

Ejemplo #3 Conexión a instancias remotas de php-fastcgi

    fastcgi.server = ( ".php" =>
       (( "host" => "10.0.0.2", "port" => 1030 ),
        ( "host" => "10.0.0.3", "port" => 1030 ))
    )

## Servidor Web LiteSpeed/Servidor Web OpenLiteSpeed en sistemas Unix

LiteSpeed PHP es una compilación optimizada de PHP construida para funcionar con los productos LiteSpeed a través de la API LiteSpeed. LSPHP funciona como su propio proceso y tiene su propio binario autónomo, que puede ser utilizado como un simple binario en línea de comandos para ejecutar scripts PHP desde la línea de comandos.

LSAPI es una API altamente optimizada que permite la comunicación entre LiteSpeed y motores web de terceros. Su protocolo es similar a FCGI, pero es más eficiente.

Esta documentación cubrirá la instalación y configuración de PHP con LSAPI para un servidor Web LiteSpeed y un servidor Web OpenLiteSpeed.

Se asumirá que LSWS o OLS está instalado con sus rutas y flags por omisión. El directorio de instalación por omisión para ambos servidores Web es /usr/local/lsws y ambos pueden ser ejecutados desde el subdirectorio bin.

Tenga en cuenta que a lo largo de esta documentación, los números de versión han sido reemplazados por un `x` para garantizar que esta documentación permanezca correcta en el futuro, reemplácelos, si es necesario, por los números de versión correspondientes.

1. Para obtener e instalar LiteSpeed Web Server o OpenLiteSpeed Web Server, visite la » página de instalación de la documentación de LiteSpeed Web Server o la » página de instalación. de la documentación OpenLiteSpeed

2. Descargue y descomprima el código fuente de PHP:

       mkdir /home/php
       cd /home/php
       wget http://us1.php.net/get/php-x.x.x.tar.gz/from/this/mirror
       tar -zxvf php-x.x.x.tar.gz
       cd php-x.x.x

3. Configure y construya PHP. Aquí es donde PHP puede ser personalizado con diversas opciones, tales como las extensiones que serán activadas. Ejecute ./configure --help para obtener una lista de las opciones disponibles. En el ejemplo, se utilizarán las opciones de configuración recomendadas por omisión para LiteSpeed Web Server:

       ./configure ... '--with-litespeed'
       make
       sudo make install

4. Verificar la instalación de LSPHP

   Una de las formas más simples de verificar si la instalación de PHP ha tenido éxito es ejecutar el siguiente código:

       cd /usr/local/lsws/fcgi-bin/
       ./lsphp5 -v

   Esto debería devolver información sobre la nueva versión de PHP:

       PHP 5.6.17 (litespeed) (built: Mar 22 2016 11:34:19)
       Copyright (c) 1997-2014 The PHP Group
       Zend Engine v2.6.0, Copyright (c) 1998-2015 Zend Technologies

   Observe el `litespeed` entre paréntesis. Esto significa que el binario PHP ha sido construido con soporte LSAPI.

Después de seguir los pasos anteriores, LiteSpeed / OpenLiteSpeed Web Server debería ahora funcionar con soporte de PHP como una extensión SAPI. Existen muchas otras opciones de configuración disponibles para LSWS / OLS y PHP. Para más información, consulte la documentación de LiteSpeed en » PHP.

Uso de LSPHP desde la línea de comandos:

El modo de línea de comandos LSPHP (LSAPI + PHP) se utiliza para procesar scripts PHP en ejecución en un servidor remoto que no necesariamente tiene un servidor web en ejecución. Se utiliza para procesar scripts PHP residentes en un servidor web local (separado). Esta configuración es adecuada para la escalabilidad del servicio ya que el procesamiento PHP se descarga a un servidor remoto.

Iniciar lsphp desde la línea de comandos en un servidor remoto: LSPHP es un ejecutable y puede ser iniciado manualmente y ligado a direcciones IPv4, IPv6 o direcciones de socket de dominio Unix con la opción de línea de comandos -b socket_address

Ejemplos:

Hacer que LSPHP se ligue al puerto 3000 en todas las direcciones IPv4 e IPv6:

    /path/to/lsphp -b [::]:3000

Hacer que LSPHP se ligue al puerto 3000 en todas las direcciones IPv4:

    /path/to/lsphp -b *:3000

Hacer que LSPHP se ligue a la dirección 192.168.0.2:3000:

    /path/to/lsphp -b 192.168.0.2:3000

Hacer que LSPHP acepte las solicitudes en el socket de dominio Unix `/tmp/lsphp_manual.sock`:

    /path/to/lsphp -b /tmp/lsphp_manual.sock

Las variables de entorno pueden ser añadidas antes del ejecutable LSPHP:

    PHP_LSAPI_MAX_REQUESTS=500 PHP_LSAPI_CHILDREN=35 /path/to/lsphp -b IP_address:port

Hoy en día, LiteSpeed PHP puede ser utilizado con LiteSpeed Web Server, OpenLiteSpeed Web Server y Apache mod_lsapi. Para los pasos de configuración del lado del servidor, visite las páginas de documentación para » LiteSpeed Web Server y » OpenLiteSpeed.

LSPHP también puede ser instalado de varias otras maneras.

CentOS: En CentOS, LSPHP puede ser instalado desde el depósito LiteSpeed o el depósito Remi utilizando » RPM.

Debian: En Debian, LSPHP puede ser instalado desde el depósito LiteSpeed utilizando » apt.

cPanel: Ver la » página de documentación respectiva sobre cómo instalar LSPHP con cPanel y LSWS/OLS utilizando EasyApache 4.

Plesk: Plesk puede ser utilizado con LSPHP en CentOS, CloudLinux, Debian y Ubuntu, para más detalles sobre esto, visite la » página de documentación respectiva.

## Instalación en Solaris

Esta sección contiene las notas y consejos de instalación de PHP en las distribuciones Solaris.

### Software necesario

La instalación Solaris generalmente omite los compiladores C y sus utilidades. Lea esta FAQ para saber por qué las versiones GNU de algunas de estas herramientas son necesarias.

Para descomprimir la distribución PHP, se necesita

- tar
- gzip o
- bzip2

Para compilar PHP, se necesita

- gcc (recomendado, otros compiladores C también pueden funcionar)
- make
- GNU sed

Para construir las extensiones adicionales o modificar el código de PHP, también se puede necesitar

- re2c
- bison
- m4
- autoconf
- automake

Además, también se deberán instalar (y tal vez compilar) todas las bibliotecas necesarias para las extensiones como MySQL, Oracle, etc.

### Uso de paquetes

La instalación Solaris puede simplificarse utilizando pkgadd para instalar la mayoría de los componentes. El sistema de paquetes de imágenes (IPS) para Solaris 11 Express también contiene los componentes necesarios para la instalación utilizando el comando pkg.

# Instalación en un sistema macOS

## Tabla de contenidos

- Instalación en macOS utilizando paquetes de terceros
- Compilar PHP en macOS
- Uso de PHP integrado anterior a macOS Monterey

PHP estaba incluido con macOS en las versiones 10 y 11, pero ya no está incluido desde la versión macOS 12 (Monterey). La instalación en las versiones recientes requiere ya sea el uso de paquetes provenientes de fuentes de terceros, ya sea la compilación a partir del código fuente.

## Instalación en macOS utilizando paquetes de terceros

Existen algunas versiones pre-empaquetadas y pre-compiladas de PHP para macOS. Esto puede ser útil para configurar una instalación estándar, pero si se necesita acceder a funcionalidades específicas (como un servidor seguro, o un controlador de bases de datos exóticas), será necesario compilar PHP y/o el servidor web por cuenta propia. Si no se está familiarizado con la compilación y la configuración de aplicaciones, es recomendable verificar si alguien más ha creado un paquete que contenga las funcionalidades deseadas.

Una manera sencilla de instalar PHP en macOS es utilizando el gestor de paquetes » Homebrew.

1. Instalar homebrew, siguiendo las instrucciones en el sitio web.

2. brew install php

Los siguientes recursos alternativos ofrecen la posibilidad de instalar paquetes y binarios precompilados para PHP en macOS:

- » MacPorts
- » Fink

## Compilar PHP en macOS

Consulte el guía de instalación en Unix para compilar PHP en macOS.

## Uso de PHP integrado anterior a macOS Monterey

PHP está integrado con macOS desde macOS X (10.0.0) y anterior a macOS Monterey (12.0.0). Activar PHP con el servidor Web por defecto requiere descomentar algunas líneas en el fichero de configuración de Apache httpd.conf mientras que el modo CGI y/o CLI están activados por defecto (acceso simple a través del terminal).

La activación de PHP siguiendo estas instrucciones permite configurar rápidamente un entorno local de desarrollo. Se recomienda encarecidamente siempre actualizar PHP a su versión más reciente. Como la mayoría de los programas, las nuevas versiones se crean para corregir errores y añadir funcionalidades y es el caso de PHP. Consulte la documentación de la instalación de macOS para más detalles. Las siguientes instrucciones están destinadas al principiante, proporcionando solo los detalles suficientes para configurar una configuración por defecto para trabajar. Se recomienda encarecidamente a todos los usuarios compilar e instalar una versión reciente del paquete.

El tipo de instalación estándar utiliza mod_php, y activa el mod_php integrado en macOS para el servidor Web Apache (el servidor Web por defecto que es accesible a través de las preferencias del sistema), en algunos pasos:

1. Encuentre y abra el fichero de configuración de Apache. Por defecto, será: /private/etc/apache2/httpd.conf Utilizar el programa `Finder` o `Spotlight` para encontrar este fichero puede resultar difícil, sabiendo que, por defecto, pertenece al usuario `root`.

   > Nota: Una forma de abrirlo es utilizar un editor de texto Unix en un terminal, por ejemplo, `nano`, y sabiendo que el fichero es propiedad del usuario `root`, deberá utilizar el comando `sudo` para abrirlo (como `root`); además, deberá introducir el siguiente comando en su `Terminal` (se le pedirá su contraseña): `sudo nano /private/etc/apache2/httpd.conf` Algunos comandos de nano: `^w` (búsqueda), `^o` (guardar), y `^x` (salida) donde `^` representa la tecla Ctrl.

   > Nota: Las versiones de Mac OS X anteriores a 10.5 proporcionan versiones antiguas de PHP y Apache. Además, el fichero de configuración de Apache en las máquinas originales puede ser /etc/httpd/httpd.conf.

2. Con un editor de texto, descomente las líneas (borrando el carácter #) que se parecen a las siguientes líneas (estas 2 líneas no se encuentran en el mismo lugar):

       # LoadModule php5_module libexec/httpd/libphp5.so

       # AddModule mod_php5.c

   Tenga en cuenta la ruta. En el futuro, cuando compile PHP, los ficheros anteriores deben ser reemplazados o comentados.

3. Asegúrese de que las extensiones deseadas sean analizadas por PHP (ejemplos: .php, .html y .inc)

   Sabiendo que este comportamiento ya ha sido activado en su fichero httpd.conf (desde Mac Panther), una vez activado PHP, los ficheros .php serán automáticamente analizados por PHP.

       <IfModule mod_php5.c>
           # Si php está activado, respetamos los ficheros .php y .phps.
           AddType application/x-httpd-php .php
           AddType application/x-httpd-php-source .phps

           # Como la mayoría de los usuarios querrá que index.php funcione,
           # también activamos automáticamente index.php
           <IfModule mod_dir.c>
               DirectoryIndex index.html index.php
           </IfModule>
       </IfModule>

   > Nota:

   > Antes de OS X 10.5 (Leopard), PHP 4 se entregaba por defecto en lugar de PHP 5. Por lo tanto, las instrucciones anteriores diferirán solo cambiando 5 por 4.

4. Asegúrese de que DirectoryIndex cargue el fichero index por defecto. Esto también se define en el fichero httpd.conf. Normalmente, los ficheros index.php y index.html se utilizan. Por defecto, index.php está activado porque también está en la verificación de PHP anterior. Ajuste según sea necesario.
5. Defina la ruta hacia el fichero php.ini o utilice la ruta por defecto. La ruta por defecto en macOS es /usr/local/php/php.ini y una llamada a la función phpinfo() revelará esta información. Si no se utiliza ningún fichero php.ini, PHP utilizará todos los valores por defecto. Consulte la FAQ sobre "encontrar el fichero php.ini".
6. Encuentre y defina el `DocumentRoot` Este es el directorio principal para todos los ficheros Web. Los ficheros en este directorio serán servidos por el servidor Web, y por lo tanto, los ficheros PHP serán analizados por PHP antes de enviarlos al navegador. La ruta por defecto es /Library/WebServer/Documents pero puede definirse a cualquier valor en el fichero httpd.conf. Además, el directorio DocumentRoot para los diferentes usuarios es /Users/yourusername/Sites
7. Cree un fichero phpinfo().

   La función phpinfo() muestra la información sobre PHP. Cree un fichero en el DocumentRoot con el siguiente código PHP:

       <?php phpinfo(); ?>

8. Reinicie Apache y cargue el fichero PHP que acabamos de crear.

   Para reiniciar, ejecute el comando `sudo apachectl graceful` en un terminal o detenga/inicie la opción "Personal Web Server" en las preferencias del sistema de macOS. Por defecto, la carga de ficheros locales en el navegador se realiza a través de URL como esta: http://localhost/info.php o, si está utilizando el DocumentRoot de un directorio de usuario, la URL será: http://localhost/~yourusername/info.php

CLI (o CGI en versiones anteriores) se llama php y normalmente reside en /usr/bin/php. Abra un terminal, lea la sección sobre la línea de comandos del manual de PHP, y ejecute el comando `php -v` para verificar la versión de PHP de este binario. Una llamada a la función phpinfo() también puede revelar esta información.

# Instalación en sistemas Windows

## Tabla de contenidos

- Configuración recomendada en sistemas Windows
- Instalación manual de los binarios precompilados
- Apache 2.x en Microsoft Windows
- Instalación con IIS para Windows
- Herramientas de terceros para la instalación de PHP
- Construir a partir de las fuentes
- Ejecución de PHP en línea de comandos en sistemas Windows

Las versiones oficiales de PHP en Windows son recomendadas para uso en producción, pero PHP también puede ser compilado desde el código fuente.

PHP también se puede instalar en Azure App Services (también conocido como Microsoft Azure, Windows Azure o (Windows) Azure Web Apps).

La sección de instalación de las preguntas frecuentes abarca problemas comunes de instalación y configuración que podrían encontrarse.

## Configuración recomendada en sistemas Windows

### OpCache

Se recomienda encarecidamente activar OpCache. Esta extensión está incluida con PHP para Windows. Compila y optimiza los scripts PHP y los almacena en caché en memoria para que no se compilen cada vez que se carga la página.

Definir el php.ini a :

Ejemplo #1 Configuración recomendada para OpCache

    opcache.enable=On
    opcache.enable_cli=On

Y reiniciar el servidor web. Para más información, leer : Configuración de OpCache

### WinCache

Se recomienda utilizar WinCache al usar IIS, especialmente en un entorno de alojamiento web compartido o al usar almacenamiento de ficheros en red (NAS). Todas las aplicaciones PHP se benefician automáticamente de la funcionalidad de caché de ficheros de WinCache. Las operaciones del sistema de ficheros se almacenan en caché en memoria. WinCache también puede almacenar en caché en memoria objetos del usuario y compartirlos entre los procesos php.exe o php-cgi.exe (compartir objetos entre las peticiones). Muchas aplicaciones web importantes tienen un complemento o una extensión o una opción de configuración para usar el caché de objetos del usuario de WinCache. Si se requiere un alto rendimiento, utilice el caché de objetos en las aplicaciones. Ver : » https://pecl.php.net/package/WinCache para descargar una DLL WinCache (o WINCACHE_*.tgz) en el directorio de extensiones PHP (extension_dir en el fichero php.ini). Definir el php.ini a :

Ejemplo #2 Configuración recomendada para WinCache

    extension=php_wincache.dll
    wincache.fcenabled=1
    wincache.ocenabled=1 ; removed as of wincache 2.0.0.0

Para más información, leer : Configuración de WinCache

## Instalación manual de los binarios precompilados

### Requisitos de instalación

PHP solo está disponible para sistemas de 32 bits x86 o 64 bits x64, y actualmente no funciona en Windows RT o Windows sobre ARM. A partir de la versión 8.3.0, PHP requiere Windows 8 o Windows Server 2012. Las versiones posteriores a 7.2.0 requerían Windows 2008 R2 o Windows 7. Las versiones anteriores a 7.2.0 soportaban Windows 2008 y Vista.

PHP requiere el runtime Visual C (CRT). Muchas otras aplicaciones también lo exigen, por lo que es probable que ya esté instalado, pero si no está presente, el Microsoft Visual C++ Redistributable para Visual Studio 2022 es adecuado para todas las versiones de PHP y puede ser » descargado desde Microsoft.

El CRT x86 debe ser descargado para ser utilizado con las compilaciones PHP x86 y el CRT x64 para las compilaciones PHP x64. Si el CRT ya está instalado, el instalador mostrará un mensaje indicando que ya estaba instalado y no realizará ningún cambio. El instalador CRT soporta las opciones de línea de comandos /quiet y /norestart, por lo que la instalación puede ser scriptada.

### Dónde descargar los binarios PHP

Las compilaciones de Windows pueden ser descargadas desde » el sitio web PHP Windows. Todas las compilaciones están optimizadas (PGO), y las versiones QA y GA están cuidadosamente probadas.

### Extensiones PECL precompiladas

Las versiones preconstruidas de Windows de las extensiones PECL se distribuyen como ficheros DLL en la página PECL de la extensión.

Los binarios no están disponibles para las extensiones que utilizan características específicas de otros sistemas, como Unix, o dependen de bibliotecas que no están disponibles en Windows.

### Tipos de compilación

Existen cuatro tipos de compilaciones PHP:

- Thread-Safe (TS) - para servidores web de proceso único, como Apache con mod_php

- Non-Thread-Safe (NTS) - para IIS y otros servidores web FastCGI (Apache con mod_fastcgi) y recomendado para scripts en línea de comandos

- x86 - para sistemas de 32 bits.

- x64 - para sistemas de 64 bits.

## Apache 2.x en Microsoft Windows

Esta sección contiene notas y sugerencias específicas de Apache 2.x instaladas con PHP en sistemas Microsoft Windows.

> Nota:

> Se debe leer primero el manual de instalación PHP en Windows

Se recomienda consultar la » Documentación de Apache para obtener un conocimiento básico del servidor Apache 2.x. También considere leer las » notas específicas para Windows para Apache 2.x antes de seguir leyendo.

Descargue la versión más reciente de » Apache 2.x y una versión adecuada de PHP. Siga los pasos del manual de instalación y regrese para continuar con la integración de PHP y Apache.

Hay tres formas de configurar PHP para que funcione con Apache 2.x en Windows. PHP se puede ejecutar como controlador, como CGI o bajo FastCGI

> Nota: Recuerde que al añadir valores que representan una ruta en la configuración de Apache bajo Windows, todos los backslash, como c:\directorio\archivo.ext, deben ser convertidos a slashes, como c:/directorio/archivo.ext. Un slash final puede también ser necesario para los directorios.

### Instalación como un controlador de Apache

> Nota: Cuando se utiliza apache2handler SAPI, se debe utilizar la versión Thread Safe (TS) de PHP.

Para cargar el módulo PHP en Apache 2.x las siguientes líneas en el fichero de configuración httpd.conf de Apache deben ser añadidas:

Ejemplo #1 PHP y Apache 2.x como controlador

    # antes de PHP 8.0.0 el nombre del módulo era php7_module
    LoadModule php_module "c:/php/php8apache2_4.dll"
    <FilesMatch \.php$>
        SetHandler application/x-httpd-php
    </FilesMatch>
    # configurar la ruta a php.ini
    PHPIniDir "C:/php"

> Nota: La ruta real de PHP debe sustituirse por C:/php/ en los ejemplos anteriores. Asegúrese que el fichero al que hace referencia en la directiva `LoadModule` está en la ubicación especificada, y utilize php7apache2_4.dll para PHP 7, o php8apache2_4.dll para PHP 8.

### Ejecución de PHP como CGI

Se recomienda consultar la » documentación de Apache CGI para una comprensión más completa de la ejecución de CGI en Apache.

Para ejecutar PHP como CGI, deberá colocar los ficheros php-cgi en un directorio designado como directorio CGI utilizando la directiva ScriptAlias.

Será necesario colocar una línea `#!` en los ficheros PHP, que apunte a la ubicación del binario PHP:

Ejemplo #2 PHP y Apache 2.x como CGI

    #!C:/php/php.exe
    <?php
      phpinfo();
    ?>

Advertencia

Un servidor desplegado en modo CGI se expone a varias vulnerabilidades posibles. Por favor, lea nuestra sección sobre la seguridad en modo CGI para aprender cómo protegerse contra estos ataques.

### Ejecutando PHP bajo FastCGI

Ejecutar PHP bajo FastCGI tiene una serie de ventajas con respecto a ejecutarlo bajo CGI. Configurarlo de esta manera es bastante sencillo:

Descargue `mod_fcgid` desde » https://www.apachelounge.com. Los binarios de Win32 están disponibles para descargar desde ese sitio. Instale el módulo de acuerdo con las instrucciones que lo acompañarán.

Configure su servidor web como se muestra a continuación, teniendo cuidado de ajustar cualquier ruta que reflejen la forma en que ha instalado las cosas en su sistema particular:

Ejemplo #3 Configurar Apache para ejecutar PHP como FastCGI

    LoadModule fcgid_module modules/mod_fcgid.so
    # ¿Dónde está el fichero php.ini?
    FcgidInitialEnv PHPRC        "c:/php"
    <FilesMatch \.php$>
        SetHandler fcgid-script
    </FilesMatch>
    FcgidWrapper "c:/php/php-cgi.exe" .php

Los archivos con una extensión .php ahora serán ejecutados por el contenedor PHP FastCGI.

## Instalación con IIS para Windows

### Instalar IIS

Los Servicios de Información de Internet (Internet Information Services - IIS) están integrados en Windows. En Windows Server, el rol IIS puede ser añadido a través del Administrador del Servidor. El módulo CGI debe ser incluido. En los escritorios Windows, IIS debe ser añadido a través del Panel de Control. La documentación de Microsoft proporciona » instrucciones detalladas para habilitar IIS. Para el desarrollo, » IIS/Express también puede ser utilizado.

> Nota: La versión No-Thread Safe (NTS) de PHP debe ser instalada cuando se utiliza el gestor FastCGI con IIS.

### Configurar PHP con IIS

En el Administrador de IIS, instale el módulo FastCGI y añada una correspondencia de gestor para `.php` al camino de php-cgi.exe (no php.exe)

El comando APPCMD puede ser utilizado para crear scripts de configuración de IIS.

### Ejemplo de script batch

Ejemplo #1 Línea de comandos para configurar IIS y PHP

    @echo off

    REM descargar el archivo .ZIP de la versión de PHP desde http://windows.php.net/downloads/

    REM ruta del directorio en el que el archivo .ZIP de PHP ha sido descomprimido (sin \ final)
    set phppath=c:\php

    REM Elimina los gestores PHP actuales
    %windir%\system32\inetsrv\appcmd clear config /section:system.webServer/fastCGI
    REM La siguiente comanda generará un mensaje de error si PHP no está instalado. Esto puede ser ignorado.
    %windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /-[name='PHP_via_FastCGI']

    REM Configura el gestor PHP
    %windir%\system32\inetsrv\appcmd set config /section:system.webServer/fastCGI /+[fullPath='%phppath%\php-cgi.exe']
    %windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /+[name='PHP_via_FastCGI',path='*.php',verb='*',modules='FastCgiModule',scriptProcessor='%phppath%\php-cgi.exe',resourceType='Unspecified']
    %windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /accessPolicy:Read,Script

    REM Configura las variables FastCGI
    %windir%\system32\inetsrv\appcmd set config -section:system.webServer/fastCgi /[fullPath='%phppath%\php-cgi.exe'].instanceMaxRequests:10000
    %windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='%phppath%\php-cgi.exe'].environmentVariables.[name='PHP_FCGI_MAX_REQUESTS',value='10000']"
    %windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='%phppath%\php-cgi.exe'].environmentVariables.[name='PHPRC',value='%phppath%\php.ini']"

## Herramientas de terceros para la instalación de PHP

Advertencia

Las versiones provenientes de terceros son consideradas no oficiales y no son directamente soportadas por el proyecto PHP. Cualquier bug encontrado debe ser reportado al proveedor de estas versiones no oficiales, a menos que pueda ser reproducido utilizando las versiones provenientes de » la zona de descargas oficial.

» XAMPP, » WampServer, y » Bitnami configuran asimismo aplicaciones PHP para su uso con Apache en Windows.

## Construir a partir de las fuentes

Ver las » instrucciones de construcción paso a paso para compilar con Visual Studio.

## Ejecución de PHP en línea de comandos en sistemas Windows

Esta sección contiene notas y consejos específicos para la ejecución de PHP en línea de comandos en Windows.

> Nota:

> ¡Leer primero los pasos de instalación manual!

Tener PHP ejecutándose desde la línea de comandos puede realizarse sin hacer modificaciones en Windows.

    C:\php\php.exe -f "C:\PHP Scripts\script.php" -- -arg1 -arg2 -arg3

Pero hay algunos pasos fáciles de seguir para simplificar esto. Algunos de estos pasos ya deberían haberse tomado, pero se repiten aquí para proporcionar una secuencia completa paso a paso.

> Nota:

> Las dos variables de sistema preexistentes PATH y PATHEXT son importantes en Windows, y se debe tener cuidado de no sobrescribirlas, solo añadirlas.

- Añadir la ubicación del ejecutable PHP (php.exe, php-win.exe o php-cli.exe según la versión de PHP y las preferencias de visualización) a la variable de entorno PATH. Leer más sobre cómo añadir el directorio PHP apropiado a la variable de entorno PATH en la entrada FAQ correspondiente.

- Añadir la extensión `.PHP` a la variable de entorno PATHEXT. Esto puede hacerse al mismo tiempo que se añade la variable de entorno PATH. Siga los mismos pasos descritos en la FAQ pero modifique la variable de entorno PATHEXT en lugar de la variable de entorno PATH.

  > Nota:

  > La posición en la que se coloca `.PHP` determinará qué script o programa se ejecuta cuando hay nombres de ficheros correspondientes. Por ejemplo, colocar `.PHP` antes de `.BAT` hará que se ejecute el script, en lugar del fichero batch, si hay un fichero batch con el mismo nombre.

- Asociar la extensión `.PHP` con un tipo de fichero. Esto se hace ejecutando el siguiente comando:

      assoc .php=phpfile

- Asociar el tipo de fichero `phpfile` con el ejecutable PHP apropiado. Esto se hace ejecutando el siguiente comando:

      ftype phpfile="C:\php\php.exe" -f "%1" -- %~2

Siguiendo estos pasos, los scripts PHP podrán ser ejecutados desde cualquier directorio sin necesidad de escribir el ejecutable PHP o la extensión `.PHP` y todos los argumentos serán proporcionados al script para su procesamiento.

El ejemplo a continuación detalla algunos de los cambios de registro que pueden hacerse manualmente.

Ejemplo #1 Cambios de registro

    Windows Registry Editor Version 5.00

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\.php]
    @="phpfile"
    "Content Type"="application/php"

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile]
    @="PHP Script"
    "EditFlags"=dword:00000000
    "BrowserFlags"=dword:00000008
    "AlwaysShowExt"=""

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\DefaultIcon]
    @="C:\\php\\php-win.exe,0"

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell]
    @="Open"

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell\Open]
    @="&Open"

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell\Open\command]
    @="\"C:\\php\\php.exe\" -f \"%1\" -- %~2"

Con estos cambios, el mismo comando puede escribirse como sigue:

    "C:\PHP Scripts\script" -arg1 -arg2 -arg3

o, si la ruta `"C:\PHP Scripts"` está en la variable de entorno PATH:

    script -arg1 -arg2 -arg3

> Nota:

> Hay un pequeño problema si la intención es utilizar esta técnica y utilizar los scripts PHP como filtro en línea de comandos, como en el ejemplo a continuación:

>     dir | "C:\PHP Scripts\script" -arg1 -arg2 -arg3

> o

>     dir | script -arg1 -arg2 -arg3

> El script puede simplemente bloquearse y no mostrar nada. Para que esto funcione, se debe realizar otro cambio de registro:

>     Windows Registry Editor Version 5.00

>     [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\policies\Explorer]
>     "InheritConsoleHandles"=dword:00000001

> Más información sobre este problema puede encontrarse en este » artículo de la base de conocimientos de Microsoft: 321788. A partir de Windows 10, este ajuste parece estar invertido, haciendo que la instalación por defecto de Windows 10 soporte automáticamente los manejadores de consola heredados. Este » post del foro de Microsoft proporciona la explicación.

# Instalación en las plataformas de Nube Informática

## Tabla de contenidos

- Azure App services
- Amazon EC2
- DigitalOcean

PHP instalará en la nube. A la nube de PHP!

## Azure App services

PHP es frecuentemente utilizado en Azure App Services (alias Microsoft Azure, Windows Azure, Azure Web Apps).

Azure App Services gestiona los pools de servidores Web Windows para alojar su aplicación Web, como alternativa a la gestión de su propio servidor Web en sus propias VM de cálculo Azure u otros servidores.

PHP ya está activado para su sitio web automático Azure App Services. En el portal de Azure, seleccione su sitio Web, y puede elegir la versión de PHP a utilizar. Es posible que desee elegir una versión más reciente que la predeterminada.

Como tal, PHP y las extensiones se ejecutan en Azure App Services de la misma manera que lo harían en otros servidores Windows. Sin embargo, la interfaz de gestión para Azure app services es diferente:

- Portal de Azure: crear, modificar y eliminar los sitios Web. » Portal de Azure

- Tablero de Kudu: si el sitio Web tiene la URL `nombre_del_sitio.azurewebsites.net`, el tablero de Kudu es `https://nombre_del_sitio.scm.azurewebsites.net/`. El tablero ofrece acceso a las funcionalidades de depuración, a la gestión de los ficheros y a las extensiones del sitio. Las extensiones de sitio son un mecanismo de Azure para agregar programas adicionales, como versiones preliminares de PHP, a un sitio Web.

- No se puede utilizar el gestor de servicios de Internet, el gestor de servidor o RDP.

También existe un SDK PHP, que permitirá utilizar los numerosos servicios de Azure desde su código PHP. Ver » Azure SDK para PHP.

Para más información, ver » Centro de desarrolladores de PHP de Azure

### WinCache

WinCache está activado por omisión en Azure App Services y se recomienda dejarlo activado. Si instala su propia versión de PHP, debe activar WinCache.

### Build personalizada de PHP

Puede cargar su propia versión de PHP en su D:\Home (C:\ no es accesible en escritura). Luego, en el portal de Azure, defina SCRIPT_PROCESSOR para .php en la ruta de acceso absoluta al fichero php-cgi.exe en su build personalizada.

## Amazon EC2

PHP se instala en la » plataforma de nube EC2.

Vea también el » AWS SDK for PHP.

## DigitalOcean

DigitalOcean ofrece las siguientes plataformas para instalar PHP y ejecutar una aplicación web en su infraestructura de alojamiento en la nube.

- » Cloudways: Despliegue en un clic de las principales aplicaciones PHP: WordPress, Magento, Drupal, Laravel y más.

- » Droplet: Máquinas virtuales para instalar PHP y otros programas. » Instalación de una pila LAMP en un servidor Linux .

- » Plataforma de aplicaciones: Gestione infraestructuras para crear, implantar y escalar aplicaciones rápidamente. Aprenda a » ejecutar aplicaciones PHP en la App .

- » Funciones: Plataforma sin servidor que permite a los desarrolladores ejecutar código sin aprovisionar ni gestionar servidores. PHP es compatible de forma nativa. Aprenda a » crear funciones sin servidor en PHP .

# FastCGI Process Manager (FPM)

## Tabla de contenidos

- Instalación
- Configuration

FPM (FastCGI Process Manager, gestor de procesos FastCGI) es una alternativa a la implementación PHP FastCGI con funcionalidades adicionales útiles para sitios muy altamente cargados.

Estas funcionalidades incluyen :

- Gestión avanzada de procesos con parada/arranque suave (graceful) ;

- Pools que permiten iniciar trabajadores con diferentes uid/gid/chroot/entorno, escuchando en diferentes puertos y utilizando diferentes php.ini (reemplaza el modo seguro) ;

- Registro configurable stdout y stderr ;

- Reinicio de emergencia en caso de destrucción accidental del caché opcode ;

- Soporte de carga acelerada ;

- "slowlog" - registro de scripts (no solo sus nombres, sino también su backtrace PHP, utilizando ptrace o equivalente para leer el proceso remoto) que se ejecutan anormalmente lento ;

- fastcgi_finish_request() - función especial para terminar la petición y volcar todas las datos mientras se continúa ejecutando una tarea consumidora (conversión de video por ejemplo) ;

- Nacimiento de procesos hijos dinámicos/bajo demanda/estáticos ;

- Información de estado básica y extendida (similar a mod_status de Apache) con diferentes formatos soportados como json, xml y openmetrics ;

- Fichero de configuración basado en php.ini

## Instalación

### Compilar desde las fuentes

Para activar FPM en la construcción de PHP es necesario añadir la línea `--enable-fpm` a la línea de configuración.

Existen múltiples opciones de configuración para FPM (todas opcionales):

- `--with-fpm-user` - el usuario FPM (por omisión - nobody).

- `--with-fpm-group` - el grupo FPM (por omisión - nobody).

- `--with-fpm-systemd` - Activa la integración de systemd (por omisión - no).

- `--with-fpm-acl` - Utilizar POSIX Access Control Lists (por omisión - no).

- `--with-fpm-apparmor` - Activa la integración de AppArmor (por omisión - no).

- `--with-fpm-selinux` - Activa la integración SELinux (por omisión - no).

### Historial de cambios

Versión | Descripción
--- | ---
8.2.0 | La opción `--with-fpm-selinux` ha sido añadida.
8.0.0 | La opción `--with-fpm-apparmor` ha sido añadida.

## Configuration

FPM uses php.ini syntax for its configuration file - php-fpm.conf, and pool configuration files.

### List of global php-fpm.conf directives

`pid` string

  Path to PID file. Default value: none.

`error_log` string

  Path to error log file. Default value: `#INSTALL_PREFIX#/log/php-fpm.log`. If it's set to "syslog", log is sent to syslogd instead of being written in a local file.

`log_level` string

  Error log level. Possible values: alert, error, warning, notice, debug. Default value: notice.

`log_limit` int

  Log limit for the logged lines which allows to log messages longer than 1024 characters without wrapping. Default value: 1024. Available as of PHP 7.3.0.

`log_buffering` bool

  Experimental logging without extra buffering. Default value: yes. Available as of PHP 7.3.0.

`syslog.facility` string

  used to specify what type of program is logging the message. Default value: daemon.

`syslog.ident` string

  Prepended to every message. If you have multiple FPM instances running on the same server, you can change the default value which must suit common needs. Default value: php-fpm.

`emergency_restart_threshold` int

  If this number of child processes exit with SIGSEGV or SIGBUS within the time interval set by `emergency_restart_interval`, then FPM will restart. A value of 0 means 'Off'. Default value: 0 (Off).

`emergency_restart_interval` mixed

  Interval of time used by `emergency_restart_interval` to determine when a graceful restart will be initiated. This can be useful to work around accidental corruptions in an accelerator's shared memory. Available Units: s(econds), m(inutes), h(ours), or d(ays). Default Unit: seconds. Default value: 0 (Off).

`process_control_timeout` mixed

  Time limit for child processes to wait for a reaction on signals from master. Available units: s(econds), m(inutes), h(ours), or d(ays) Default Unit: seconds. Default value: 0.

`process.max` int

  The maximum number of processes FPM will fork. This has been design to control the global number of processes when using dynamic PM within a lot of pools. Use it with caution. Default value: 0.

`process.priority` int

  Specify the nice(2) priority to apply to the master process (only if set). The value can vary from -19 (highest priority) to 20 (lower priority). Default value: not set.

`daemonize` bool

  Send FPM to background. Set to 'no' to keep FPM in foreground for debugging. Default value: yes.

`rlimit_files` int

  Set open file descriptor rlimit for the master process. Default value: system defined value.

`rlimit_core` int

  Set max core size rlimit for the master process. Default value: 0.

`events.mechanism` string

  Specify the event mechanism FPM will use. The following is available: epoll, kqueue (*BSD), port (Solaris), poll, select. Default value: not set (auto detection preferring epoll and kqueue).

`systemd_interval` int

  When FPM is build with systemd integration, specify the interval, in second, between health report notification to systemd. Set to 0 to disable. Default value: 10.

### List of pool directives

With FPM you can run several pools of processes with different setting. These are settings that can be tweaked per pool.

`listen` string

  The address on which to accept FastCGI requests. Valid syntaxes are: 'ip.add.re.ss:port', 'port', '/path/to/unix/socket'. This option is mandatory for each pool.

`listen.backlog` int

  Set listen(2) backlog. A value of `-1` means maximum on BSD systems. Default value: `-1` (FreeBSD or OpenBSD) or `511` (Linux and other platforms).

`listen.allowed_clients` string

  List of IPv4 or IPv6 addresses of FastCGI clients which are allowed to connect. Equivalent to the FCGI_WEB_SERVER_ADDRS environment variable in the original PHP FastCGI (5.2.2+). Makes sense only with a tcp listening socket. Each address must be separated by a comma. If this value is left blank, connections will be accepted from any ip address. Default value: not set (any ip address accepted).

`listen.owner` string

  Set permissions for unix socket, if one is used. In Linux, read/write permissions must be set in order to allow connections from a web server. Many BSD-derived systems allow connections regardless of permissions. Default values: user and group are set as the running user, mode is set to 0660.

`listen.group` string

  See `listen.owner`.

`listen.mode` string

  See `listen.owner`.

`listen.acl_users` string

  When POSIX Access Control Lists are supported you can set them using this option. When set, `listen.owner` and `listen.group` are ignored. Value is a comma separated list of user names.

`listen.acl_groups` string

  See `listen.acl_users`. Value is a comma separated list of group names.

`listen.setfib` int

  Set the associated the route table (FIB). FreeBSD only. Default Value: `-1`. Since PHP 8.2.0.

`user` string

  Unix user of FPM processes. This option is mandatory.

`group` string

  Unix group of FPM processes. If not set, the default user's group is used.

`pm` string

  Choose how the process manager will control the number of child processes. Possible values: `static`, `ondemand`, `dynamic`. This option is mandatory.

  `static` - the number of child processes is fixed (`pm.max_children`).

  `ondemand` - los procesos se generan bajo demanda (cuando se solicita, a diferencia de dinámico, donde `pm.start_servers` se inician cuando se inicia el servicio). `dynamic` - el número de procesos hijos se establece dinámicamente en función de las siguientes directivas: `pm.max_children`, `pm.start_servers`, `pm.min_spare_servers`, `pm.max_spare_servers`.
`pm.max_children` int
  El número de procesos hijos que se crearán cuando `pm` se establece en `static` y el número máximo de procesos hijos que se crearán cuando `pm` se establece en `dynamic` o `ondemand`. Esta opción es obligatoria.

  Esta opción establece el límite en el número de solicitudes simultáneas que se atenderán. Equivalente a la directiva ApacheMaxClients con mpm_prefork y a la variable de entorno PHP_FCGI_CHILDREN en el PHP FastCGI original.

`pm.start_servers` int

  The number of child processes created on startup. Used only when `pm` is set to `dynamic`. Default Value: (min_spare_servers + max_spare_servers) / 2.

`pm.min_spare_servers` int

  The desired minimum number of idle server processes. Used only when `pm` is set to `dynamic`. Also mandatory in this case.

`pm.max_spare_servers` int

  The desired maximum number of idle server processes. Used only when `pm` is set to `dynamic`. Also mandatory in this case.

`pm.max_spawn_rate` int

  The number of rate to spawn child processes at once. Used only when `pm` is set to `dynamic`. Default value: 32

`pm.process_idle_timeout` mixed

  The number of seconds after which an idle process will be killed. Used only when `pm` is set to `ondemand`. Available units: s(econds)(default), m(inutes), h(ours), or d(ays). Default value: 10s.

`pm.max_requests` int

  The number of requests each child process should execute before respawning. This can be useful to work around memory leaks in 3rd party libraries. For endless request processing specify '0'. Equivalent to PHP_FCGI_MAX_REQUESTS. Default value: 0.

`pm.status_listen` string

  The address on which to accept FastCGI status request. This creates a new invisible pool that can handle requests independently. This is useful if the main pool is busy with long running requests because it is still possible to get the FPM status page before finishing the long running requests. The syntax is the same as for listen directive. Default value: none.

`pm.status_path` string

  The URI to view the FPM status page. This value must start with a leading slash (/). If this value is not set, no URI will be recognized as a status page. Default value: none.

`ping.path` string

  The ping URI to call the monitoring page of FPM. If this value is not set, no URI will be recognized as a ping page. This could be used to test from outside that FPM is alive and responding. Please note that the value must start with a leading slash (/).

`ping.response` string

  This directive may be used to customize the response to a ping request. The response is formatted as text/plain with a 200 response code. Default value: pong.

`process.priority` int

  Specify the nice(2) priority to apply to the worker process (only if set). The value can vary from -19 (highest priority) to 20 (lower priority). Default value: not set.

`process.dumpable` bool

  Set the process dumpable flag (PR_SET_DUMPABLE prctl) even if the process user or group is different than the master process user. It allows to create process core dump and ptrace the process for the pool user. Default Value: no. Since PHP 7.0.29, 7.1.17 and 7.2.5.

`prefix` string

  Specify prefix for path evaluation

`request_terminate_timeout` mixed

  The timeout for serving a single request after which the worker process will be killed. This option should be used when the 'max_execution_time' ini option does not stop script execution for some reason. A value of '0' means 'Off'. Available units: s(econds)(default), m(inutes), h(ours), or d(ays). Default value: 0.

`request_terminate_timeout_track_finished` bool

  The timeout set by request_terminate_timeout is not engaged after a fastcgi_finish_request or when application has finished and internal shutdown functions are being called. This directive will enable timeout limit to be applied unconditionally even in such cases. Default value: no. Since PHP 7.3.0.

`request_slowlog_timeout` mixed

  The timeout for serving a single request after which a PHP backtrace will be dumped to the 'slowlog' file. A value of '0' means 'Off'. Available units: s(econds)(default), m(inutes), h(ours), or d(ays). Default value: 0.

`request_slowlog_trace_depth` int

  The depth of slowlog log stack trace. Default value: 20. Since PHP 7.2.0.

`slowlog` string

  The log file for slow requests. Default value: `#INSTALL_PREFIX#/log/php-fpm.log.slow`.

`rlimit_files` int

  Set open file descriptor rlimit for child processes in this pool. Default value: system defined value.

`rlimit_core` int

  Set max core size rlimit for child processes in this pool. Possible Values: 'unlimited' or an integer greater or equal to 0. Default value: system defined value.

`chroot` string

  Chroot to this directory at the start. This value must be defined as an absolute path. When this value is not set, chroot is not used.

`chdir` string

  Chdir to this directory at the start. This value must be an absolute path. Default value: current directory or / when chroot.

`catch_workers_output` bool

  Redirect worker stdout and stderr into main error log. If not set, stdout and stderr will be redirected to /dev/null according to FastCGI specs. Default value: no.

`decorate_workers_output` bool

  Enable the output decoration for workers output when catch_workers_output is enabled. Default value: yes. Available as of PHP 7.3.0.

`clear_env` bool

  Clear environment in FPM workers. Prevents arbitrary environment variables from reaching FPM worker processes by clearing the environment in workers before env vars specified in this pool configuration are added. Default value: Yes.

`security.limit_extensions` string

  Limits the extensions of the main script FPM will allow to parse. This can prevent configuration mistakes on the web server side. You should only limit FPM to .php extensions to prevent malicious users to use other extensions to execute php code. Default value: .php .phar

`apparmor_hat` string

  If AppArmor is enabled, it allows to change a hat. Default value: not set

`access.log` string

  The access log file. Default value: not set

`access.format` string

  The access log format. Default value: `"%R - %u %t \"%m %r\" %s"`:

  Valid options
  Placeholder | Description
  --- | ---
  `%%` | The `%` character
  `%C` | %CPU used by the request. It can accept the following format: `%{user}C` for user CPU only, `%{system}C` for system CPU only, `%{total}C` for user + system CPU (default)
  `%d` | Time taken to serve the request. It can accept the following formats for precision: `%{seconds}d` (default), `%{milliseconds}d`, `%{microseconds}d`
  `%{name}e` | An environment variable (same as $_ENV or $_SERVER). A variable name must be specified within curly brackets to specify the name of the env variable. For example, server specifics like `%{REQUEST_METHOD}e` or `%{SERVER_PROTOCOL}e`, HTTP headers like `%{HTTP_HOST}e` or `%{HTTP_USER_AGENT}e`
  `%f` | Script filename
  `%l` | `Content-Length` of the request (for HTTP POST request only)
  `%m` | Request HTTP method
  `%M` | Peak of memory allocated by PHP. It can accept the following format: `%{bytes}M` (default), `%{kilobytes}M` `%{kilo}M`, `%{megabytes}M`, `%{mega}M`
  `%n` | Pool name
  `%{name}o` | Output header. The header name must be specified within curly brackets. For example: `%{Content-Type}o`, `%{X-Powered-By}o`, `%{Transfer-Encoding}o`
  `%p` | PID of the child that serviced the request
  `%P` | PID of the parent of the child that serviced the request
  `%q` | Query string
  `%Q` | The `'?'` character, or glue between `%q` and `%r`, if query string exists
  `%r` | Request URI without the query string, see `%q` and `%Q`
  `%R` | Remote IP address
  `%s` | Status (response code)
  `%t` | Server time the request was received. It can accept a `strftime(3)` format: `%d/%b/%Y:%H:%M:%S %z` (default) The `strftime(3)` format must be encapsulated in a `%{<strftime_format>}t` tag, e.g. for a ISO8601 formatted timestring, use: `%{%Y-%m-%dT%H:%M:%S%z}t`
  `%T` | Time the log was written (when the request finished). It can accept a `strftime(3)` format: `%d/%b/%Y:%H:%M:%S %z` (default). The `strftime(3)` format must be encapsulated in a `%{<strftime_format>}T` tag, e.g. for a ISO8601 formatted timestring, use: `%{%Y-%m-%dT%H:%M:%S%z}T`
  `%u` | Basic access authentication user, if specified in `Authorization` header

`access.suppress_path` array

  A list of request_uri values which should be filtered from the access log. Default value: not set. Since PHP 8.2.0.

It's possible to pass additional environment variables and update PHP settings of a certain pool. To do this, you need to add the following options to the pool configuration file.

Ejemplo #1 Passing environment variables and PHP settings to a pool

    env[HOSTNAME] = $HOSTNAME
    env[PATH] = /usr/local/bin:/usr/bin:/bin
    env[TMP] = /tmp
    env[TMPDIR] = /tmp
    env[TEMP] = /tmp

    php_admin_value[sendmail_path] = /usr/sbin/sendmail -t -i -f www@my.domain.com
    php_flag[display_errors] = off
    php_admin_value[error_log] = /var/log/fpm-php.www.log
    php_admin_flag[log_errors] = on
    php_admin_value[memory_limit] = 32M

PHP settings passed with `php_value` or `php_flag` will overwrite their previous value. Please note that defining disable_functions will not overwrite previously defined php.ini values, but will append the new value instead.

Settings defined with `php_admin_value` and `php_admin_flag` cannot be overridden with ini_set().

PHP settings can be set in the webserver configuration.

Ejemplo #2 set PHP settings in nginx.conf

    set $php_value "pcre.backtrack_limit=424242";
    set $php_value "$php_value \n pcre.recursion_limit=99999";
    fastcgi_param  PHP_VALUE $php_value;

    fastcgi_param  PHP_ADMIN_VALUE "open_basedir=/var/www/htdocs";

Precaución

Because these settings are passed to php-fpm as fastcgi headers, php-fpm should not be bound to a worldwide accessible address. Otherwise, anyone could alter the PHP configuration options. See also listen.allowed_clients.

> Nota: Pools are not a security mechanism, because they do not provide full separation; e.g. all pools would use a single OPcache instance.

# Instalación de extensiones PECL

## Tabla de contenidos

- Introducción a las instalaciones PECL
- Descarga de extensiones PECL
- Instalación de una extensión PHP en Windows
- Compilación de extensiones PECL compartidas con el comando pecl
- Compilación de extensiones PECL compartidas con phpize
- php-config
- Compilación de extensiones PECL estáticamente en PHP

## Introducción a las instalaciones PECL

> Nota: El instalador de Extensiones para PHP (PHP Installer for Extensions - PIE) es una nueva herramienta que reemplazará PECL. Recomendamos usar PIE para instalar extensiones. Más información en » https://github.com/php/pie

» PECL es un repositorio de extensiones PHP que están disponibles a través del sistema de empaquetado » PEAR. Esta sección del manual está destinada a demostrar cómo obtener e instalar extensiones PECL.

Estas instrucciones asumen que `/path/to/php/src/dir/` es la ruta a la distribución del código fuente de PHP y que `extname` es el nombre de la extensión PECL. Ajuste según corresponda. Estas instrucciones también asumen familiaridad con el » comando pear. La información en el manual de PEAR para el comando pear también se aplica al comando pecl.

Una extensión compartida debe ser compilada, instalada y cargada para ser útil. Los métodos descritos a continuación proporcionan varias instrucciones sobre cómo compilar e instalar las extensiones, pero no las cargan automáticamente. Las extensiones pueden cargarse añadiendo una directiva extension al fichero php.ini o mediante el uso de la función dl().

Al compilar módulos PHP, es importante tener versiones conocidas y buenas de las herramientas requeridas (autoconf, automake, libtool, etc.). Consulte las » Instrucciones de Git Anónimo para obtener detalles sobre las herramientas requeridas y las versiones necesarias.

## Descarga de extensiones PECL

> Nota: El instalador de Extensiones para PHP (PHP Installer for Extensions - PIE) es una nueva herramienta que reemplazará PECL. Recomendamos usar PIE para instalar extensiones. Más información en » https://github.com/php/pie

Hay varias opciones para descargar extensiones PECL, como:

- El comando pecl install extname descarga el código de la extensión automáticamente, por lo que en este caso no es necesaria una descarga separada.
- » https://pecl.php.net/ El sitio web de PECL contiene información sobre las diferentes extensiones que ofrece el Equipo de Desarrollo de PHP. La información disponible aquí incluye: registro de cambios, notas de la versión, requisitos y otros detalles similares.
- pecl download extname Las extensiones PECL que tienen versiones publicadas en el sitio web de PECL están disponibles para descarga e instalación usando el » comando pecl. También pueden especificarse revisiones específicas.
- git Muchas extensiones PECL residen en GitHub.
- SVN Algunas extensiones PECL también residen en SVN. Una vista basada en web puede verse en » https://svn.php.net/pecl/. Para descargar directamente desde SVN, puede usarse la siguiente secuencia de comandos:

      $ svn checkout https://svn.php.net/repository/pecl/extname/trunk extname

- Descargas para Windows El proyecto PHP compila y ofrece DLLs de Windows para la mayoría de las extensiones PECL en la página del paquete.

## Instalación de una extensión PHP en Windows

Hay dos formas de cargar una extensión PHP en Windows: compilarla en PHP o cargar la DLL. Cargar una extensión precompilada es la forma más fácil y preferida.

Para cargar una extensión, debe estar disponible como un fichero .dll en el sistema. Todas las extensiones son compiladas automáticamente y periódicamente por el Grupo PHP (consulte la siguiente sección para la descarga).

Para compilar una extensión en PHP, consulte la documentación de compilación desde el código fuente.

Para compilar una extensión independiente (también conocida como un fichero DLL), consulte la documentación de compilación desde el código fuente. Si el fichero DLL no está disponible ni con la distribución de PHP ni en PECL, puede ser necesario compilarlo antes de que la extensión pueda usarse.

### ¿Dónde encontrar una extensión?

Las extensiones PHP suelen llamarse php_*.dll (donde el asterisco representa el nombre de la extensión), y se encuentran en la carpeta PHP\ext.

PHP incluye las extensiones más útiles para la mayoría de los desarrolladores. Se llaman extensiones incluidas.

Sin embargo, si las extensiones incluidas no proporcionan la funcionalidad necesaria, aún puede encontrarse una extensión que lo haga en » PECL. La Biblioteca de Extensiones de la Comunidad PHP (PECL) es un repositorio para Extensiones PHP, que proporciona un directorio de todas las extensiones conocidas y ofrece instalaciones para descargar y desarrollar extensiones PHP.

Si una extensión ha sido desarrollada para usos particulares, puede estar alojada en PECL para que otros con las mismas necesidades puedan beneficiarse de ella. Un buen efecto secundario es que es una buena oportunidad para recibir comentarios, (con suerte) agradecimientos, informes de errores e incluso correcciones/parches. Antes de enviar una extensión para alojarla en PECL, lea » PECL submit.

### ¿Qué extensión descargar?

Muchas veces, habrá varias versiones de cada DLL disponibles:

- Diferentes números de versión (al menos los dos primeros números deben coincidir)
- Diferentes configuraciones de seguridad de hilos
- Diferentes arquitecturas de procesador (x86, x64, ...)
- Diferentes configuraciones de depuración
- `etc.`

Tenga en cuenta que la configuración de la extensión debe coincidir con todas las configuraciones de el ejecutable de PHP que se está utilizando. El siguiente script PHP informará todo sobre la configuración de PHP:

Ejemplo #1 Llamada a phpinfo()

    <?php
    phpinfo();
    ?>

O desde la línea de comandos, ejecute:

    drive:\path\to\php\executable\php.exe -i

### Carga de una extensión

La forma más común de cargar una extensión PHP es incluirla en el fichero de configuración php.ini. Tenga en cuenta que muchas extensiones ya están presentes en el php.ini y que solo es necesario eliminar el punto y coma para activarlas.

Tenga en cuenta que, a partir de PHP 7.2.0, puede usarse el nombre de la extensión en lugar del nombre del fichero de la extensión. Al ser independiente del sistema operativo y más fácil, especialmente para los recién llegados, se convierte en la forma recomendada de especificar las extensiones a cargar. Los nombres de fichero siguen siendo compatibles con versiones anteriores.

    ;extension=php_extname.dll

    extension=php_extname.dll

    ; A partir de PHP 7.2.0, se prefiere:
    extension=extname
    zend_extension=another_extension

Sin embargo, algunos servidores web son confusos porque no usan el php.ini ubicado junto al ejecutable de PHP. Para averiguar dónde reside el php.ini real, busque su ruta en phpinfo():

    Configuration File (php.ini) Path  C:\WINDOWS

    Loaded Configuration File   C:\Program Files\PHP\8.2\php.ini

Después de activar una extensión, guarde php.ini, reinicie el servidor web y verifique phpinfo() nuevamente. La nueva extensión debería tener ahora su propia sección.

### Resolución de problemas

Si la extensión no aparece en phpinfo(), deben revisarse los registros para saber de dónde proviene el problema.

Si PHP se está utilizando desde la línea de comandos (CLI), el error de carga de la extensión puede leerse directamente en la pantalla.

Si PHP se está utilizando con un servidor web, la ubicación y el formato de los registros varían según el software. Lea la documentación del servidor web para localizar los registros, ya que no tiene nada que ver con PHP en sí.

Los problemas comunes son la ubicación de la DLL y las DLLs de las que depende, el valor de la configuración "extension_dir" dentro de php.ini y las incompatibilidades en la configuración de compilación.

Si el problema radica en una incompatibilidad en la configuración de compilación, probablemente la DLL descargada no es la correcta. Intente descargar la extensión nuevamente con la configuración adecuada. Nuevamente, phpinfo() puede ser de gran ayuda.

## Compilación de extensiones PECL compartidas con el comando pecl

PECL facilita la creación de extensiones PHP compartidas. Usando el » comando pecl, haga lo siguiente:

    $ pecl install extname

Esto descargará el código fuente de extname, lo compilará e instalará extname.so en el extension_dir. extname.so luego puede cargarse a través de php.ini.

Por omisión, el comando pecl no instalará paquetes que estén marcados con el estado `alpha` o `beta`. Si no hay paquetes `stable` disponibles, puede instalarse un paquete `beta` usando el siguiente comando:

    $ pecl install extname-beta

También puede instalarse una versión específica usando esta variante:

    $ pecl install extname-0.1

> Nota:

> Después de habilitar la extensión en php.ini, es necesario reiniciar el servicio web para que los cambios surtan efecto.

## Compilación de extensiones PECL compartidas con phpize

A veces, usar el instalador pecl no es una opción. Esto podría deberse a que hay un firewall o porque la extensión que se está instalando no está disponible como un paquete compatible con PECL, como extensiones no publicadas de git. Si es necesario compilar dicha extensión, se pueden usar las herramientas de compilación de bajo nivel para realizar la compilación manualmente.

El comando phpize se utiliza para preparar el entorno de compilación para una extensión PHP. En el siguiente ejemplo, los fuentes de una extensión están en un directorio llamado extname:

    $ cd extname
    $ phpize
    $ ./configure
    $ make
    # make install

Una instalación exitosa habrá creado extname.so y lo habrá colocado en el directorio de extensiones de PHP extensions directory. El php.ini deberá ajustarse y se deberá añadir una línea `extension=extname.so` antes de que la extensión pueda usarse.

Si el sistema no tiene el comando phpize, y se usan paquetes precompilados (como RPMs), asegúrese de instalar también la versión de desarrollo adecuada del paquete PHP, ya que a menudo incluyen el comando phpize junto con los ficheros de cabecera adecuados para compilar PHP y sus extensiones.

Ejecute phpize --help para mostrar información adicional de uso.

## php-config

php-config es un script de shell simple para obtener información sobre la configuración instalada de PHP.

Cuando las extensiones se están compilando, si hay varias versiones de PHP instaladas, la instalación para la cual se va a compilar puede especificarse usando la opción --with-php-config durante la configuración, estableciendo la ruta del script respectivo php-config.

La lista de opciones de línea de comandos proporcionadas por el script php-config puede consultarse en cualquier momento ejecutando php-config con el modificador -h:

    Usage: /usr/local/bin/php-config [OPTION]
    Options:
      --prefix            [...]
      --includes          [...]
      --ldflags           [...]
      --libs              [...]
      --extension-dir     [...]
      --include-dir       [...]
      --php-binary        [...]
      --php-sapis         [...]
      --configure-options [...]
      --version           [...]
      --vernum            [...]

Opciones de línea de comandos
Opción | Descripción
--- | ---
--prefix | Prefijo del directorio donde está instalado PHP, p. ej. /usr/local
--includes | Lista de opciones `-I` con todos los ficheros de inclusión
--ldflags | `LD` flags con los que se compiló PHP
--libs | Bibliotecas adicionales con las que se compiló PHP
--extension-dir | Directorio donde se buscan las extensiones por omisión
--include-dir | Prefijo del directorio donde se instalan los ficheros de cabecera por omisión
--php-binary | Ruta completa al binario CLI o CGI de php
--php-sapis | Mostrar todos los módulos SAPI disponibles
--configure-options | Opciones de configuración para recrear la configuración de la instalación actual de PHP
--version | Versión de PHP
--vernum | Versión de PHP como entero

## Compilación de extensiones PECL estáticamente en PHP

Puede ser necesario compilar una extensión PECL estáticamente en el binario de PHP. Para hacerlo, el código fuente de la extensión deberá colocarse bajo el directorio /path/to/php/src/dir/ext/, y el sistema de compilación de PHP deberá regenerar su script de configuración.

    $ cd /path/to/php/src/dir/ext
    $ pecl download extname
    $ gzip -d < extname.tgz | tar -xvf -
    $ mv extname-x.x.x extname

Esto dará como resultado el siguiente directorio:

    /path/to/php/src/dir/ext/extname

Desde aquí, PHP necesita ser forzado a reconstruir el script de configuración, y luego puede ser compilado normalmente:

    $ cd /path/to/php/src/dir
    $ rm configure
    $ ./buildconf --force
    $ ./configure --help
    $ ./configure --with-extname --enable-someotherext --with-foobar
    $ make
    $ make install

> Nota: Para ejecutar el script buildconf, se necesitarán autoconf `2.68` y automake `1.4+`. Versiones más recientes de autoconf pueden funcionar pero no están soportadas.

Si se usa --enable-extname o --with-extname depende de la extensión. Normalmente, una extensión que no requiere bibliotecas externas usa --enable. Para estar seguro, ejecute lo siguiente después de buildconf:

    $ ./configure --help | grep extname

# Instalación de Composer y paquetes de terceros

## Introducción a Composer

» Composer es un administrador de dependencias para PHP, lo cual hace posible definir el uso de paquetes de código de terceros en un proyecto, facilitando su instalación y actualización. El cual se beneficia de la característica integrada de autocarga de clases de PHP, repositorios de paquetes de PHP como » Packagist, y convenciones comunes de diseño y codificación del proyecto.

Por ejemplo, si una aplicación o sitio web en PHP necesita trabajar con valores UUID, el » paquete `ramsey/uuid` de Ben Ramsey el cual implementa los tipos de UUID ampliamente conocidos y utilizados, y definidos en » RFC 4122 podrían ser utilizados.

Brevemente, esto se hace creando un archivo `composer.json` en el proyecto, y usando Composer para instalar la última versión del paquete, e incluyendo el script de autocarga de Composer para hacerlo disponible al código. La » documentación "Basic Usage" (Uso básico) de Composer profundiza en esto.

Ejemplo #1 `composer.json` el cual incluye un solo paquete.

    {
        "require": {
            "ramsey/uuid": "^4.7"
        }
    }

# Instalación de PIE y extensiones de terceros

## Introducción a PIE

» PIE es un instalador para PHP que permite instalar extensiones PHP de terceros, que luego pueden ser fácilmente instaladas y actualizadas. Aprovecha el repositorio de extensiones PHP de » Packagist para encontrar el código fuente para compilar la extensión, o un binario de Windows para descargar, si existe. Si descarga el código fuente, también sabe cómo compilarlo e instalarlo.

Tras » instalar los requisitos y PIE en sí, puede instalar la extensión MongoDB ejecutando el siguiente comando en la línea de comandos.

Ejemplo #1 Instalación de la extensión MongoDB con PIE

    pie install mongodb/mongodb-extension

La documentación de » "Uso de PIE" profundiza más en este tema.

# Configuración en tiempo de ejecución

## Tabla de contenidos

- El fichero de configuración
- Ficheros .user.ini
- Dónde una directiva de configuración puede ser modificada
- Cómo modificar la configuración

## El fichero de configuración

El fichero de configuración (php.ini) es leído por PHP al inicio. Si se ha compilado PHP como módulo, el fichero solo se lee una vez, al inicio del servidor web. Para las versiones CGI y CLI el fichero es leído en cada invocación.

El php.ini se busca en estos lugares (y en este orden) :

- El lugar específico del módulo SAPI (la directiva `PHPIniDir` de Apache 2, la opción de la línea de comandos `-c` en CGI y en CLI)
- La variable de entorno PHPRC.
- El lugar donde se encuentra el fichero `php.ini` puede ser definido para diferentes versiones de PHP. La raíz de las claves de registro depende de la arquitectura de 32 o 64 bits del SO y de PHP. Para un SO y PHP de 32 bits o un SO y PHP de 64 bits, utilizar `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]` para PHP de 32 bits en un SO de 64 bits, utilizar `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]` en su lugar. Para una instalación con la misma arquitectura, las siguientes claves de registro se buscan en este orden : `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z]`, `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y]` y `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x]`, donde x, y y z significan las versiones mayores, menores y normales. Para una arquitectura de 32 bits de PHP en un SO de 64 bits, las siguientes claves de registro se buscan en este orden : `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y.z]`, `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y]` y `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x]`, donde x, y y z significan las versiones mayores, menores y normales. Si hay un valor para `IniFilePath` en estas claves, el primero encontrado será utilizado como el lugar donde se encuentra el fichero `php.ini` (solo en Windows).
- `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]` o `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]`, valor de `IniFilePath` (solo en Windows).
- El directorio de trabajo actual (excepto para CLI)
- El directorio del servidor web (para los módulos SAPI), o el directorio que contiene PHP (de otro modo en Windows)
- El directorio Windows (C:\windows o C:\winnt) (para Windows), o la opción de compilación `--with-config-file-path` durante la compilación

Si el fichero php-SAPI.ini existe (donde SAPI utiliza SAPI, por lo que el nombre del fichero es e.g. php-cli.ini o php-apache.ini), se utilizará en lugar de php.ini. El nombre SAPI puede ser determinado utilizando la función php_sapi_name().

> Nota:

> El servidor web Apache cambia este directorio al directorio root al inicio, lo que hace que PHP intente leer php.ini desde el sistema de ficheros raíz si existe.

Las variables de entorno pueden ser referenciadas en los valores de configuración de php.ini como se ilustra a continuación. A partir de PHP 8.3.0, un valor de repliegue puede ser especificado, que será utilizado cuando la variable referenciada no esté definida.

Ejemplo #1 Variables de entorno en php.ini

    ; PHP_MEMORY_LIMIT se toma desde el entorno
    memory_limit = ${PHP_MEMORY_LIMIT}
    ; Si PHP_MAX_EXECUTION_TIME no está definido, tomará el valor de repliegue 30.
    max_execution_time = ${PHP_MAX_EXECUTION_TIME:-30}

Las directivas php.ini están directamente documentadas, por extensiones, en las páginas respectivas del manual de estas extensiones. La lista de directivas internas está disponible en el anexo. Es probable que no todas las directivas PHP estén documentadas en el manual. Para una lista completa de las directivas disponibles en su versión de PHP, lea los comentarios de su propio fichero php.ini. También se puede encontrar la » última versión del php.ini en Git.

Ejemplo #2 Extracto del php.ini

    ; todo texto en una línea, situado después de un punto y coma ";" es ignorado
    [php] ; los marcadores de sección (texto entre corchetes) también son ignorados
    ; Los valores booleanos pueden ser especificados así :
    ;    true, on, yes
    ; o false, off, no, none
    register_globals = off
    track_errors = yes

    ; se pueden colocar las cadenas de caracteres entre comillas
    include_path = ".:/usr/local/lib/php"

    ; Las barras invertidas se tratan como cualquier carácter
    include_path = ".;c:\php\lib"

Es posible referirse a variables .ini desde ficheros .ini. Por ejemplo : `open_basedir = ${open_basedir} ":/new/dir"`.

### Leer un directorio

Es posible configurar PHP para leer los ficheros .ini presentes en un directorio. después de la lectura de php.ini. Esto se ajusta durante la compilación con el argumento --with-config-file-scan-dir. El directorio a leer puede ser modificado durante la ejecución por la definición de la variable de entorno PHP_INI_SCAN_DIR.

Es posible leer varios directorios separándolos con un separador de ruta específico de la plataforma (`;` para Windows, NetWare y RISC OS; `:` para todas las otras plataformas; el valor utilizado por PHP es disponible en la constante `PATH_SEPARATOR`). Si se proporciona un directorio vacío en PHP_INI_SCAN_DIR, PHP también leerá el directorio proporcionado durante la compilación a través de --with-config-file-scan-dir.

En cada directorio, PHP leerá todos los ficheros que terminen por `.ini` en orden alfabético. Una lista de los ficheros que han sido cargados y en qué orden está disponible llamando a la función php_ini_scanned_files(), o ejecutando PHP con la opción --ini.

    Suponiendo que PHP está configurado con --with-config-file-scan-dir=/etc/php.d,
    y que el separador de ruta es :...

    $ php
      PHP cargará todos los ficheros presentes en /etc/php.d/*.ini como fichero
      de configuración.

    $ PHP_INI_SCAN_DIR=/usr/local/etc/php.d php
      PHP cargará todos los ficheros presentes en /usr/local/etc/php.d/*.ini
      como fichero de configuración.

    $ PHP_INI_SCAN_DIR=:/usr/local/etc/php.d php
      PHP cargará todos los ficheros presentes en /etc/php.d/*.ini, luego
      /usr/local/etc/php.d/*.ini como fichero de configuración.

    $ PHP_INI_SCAN_DIR=/usr/local/etc/php.d: php
      PHP cargará todos los ficheros presentes en /usr/local/etc/php.d/*.ini, luego en
      /etc/php.d/*.ini como fichero de configuración.

## Ficheros .user.ini

PHP incluye el soporte para ficheros INI de configuración por directorio. Estos ficheros son analizados solo por el SAPI CGI/FastCGI. Esta funcionalidad hace obsoleta la extensión PECL `htscanner`. Si se ejecuta PHP como módulo Apache, el uso de los ficheros .htaccess produce el mismo efecto.

Además del fichero php.ini principal, PHP analiza los ficheros INI contenidos en cada directorio, comenzando por el directorio desde el cual el fichero PHP actual es llamado, y recorre los directorios hasta el directorio raíz actual (tal como se define por la variable $_SERVER['DOCUMENT_ROOT']). En el caso de que el fichero PHP esté fuera de la raíz web, solo su directorio será escaneado.

Solo las configuraciones INI con los modos `INI_PERDIR` y `INI_USER` serán reconocidas en los ficheros INI .user.ini-style.

Dos nuevas directivas INI, user_ini.filename y user_ini.cache_ttl controlan el uso de los ficheros INI definidos por el usuario.

user_ini.filename define el nombre del fichero buscado por PHP en cada directorio ; si esta directiva está definida a una cadena vacía, PHP no analizará nada en absoluto. Por defecto, vale `.user.ini`.

user_ini.cache_ttl controla la duración entre 2 relecturas de los ficheros INI definidos por el usuario. Por defecto, vale 300 segundos (5 minutos).

## Dónde una directiva de configuración puede ser modificada

Estos modos determinan cuándo y dónde una directiva PHP puede o no puede ser modificada, y cada directiva del manual está dirigida por uno de estos modos. Por ejemplo, algunas directivas pueden ser modificadas en un script PHP con la función ini_set(), mientras que otras necesitan ser modificadas en los ficheros php.ini o httpd.conf.

Por ejemplo, la directiva output_buffering tiene el modo `INI_PERDIR` por lo que no puede ser modificada con la función ini_set(). Por otro lado, la directiva display_errors tiene el modo `INI_ALL`, y puede ser modificada en cualquier lugar, incluyendo con la función ini_set().

Constantes de modo INI
`INI_USER` (int)
  La entrada puede ser definida en scripts de usuario (como con ini_set()) o en el registro Windows. La entrada puede ser definida en .user.ini
`INI_PERDIR` (int)
  La entrada puede ser definida en php.ini, .htaccess, httpd.conf o .user.ini
`INI_SYSTEM` (int)
  La entrada puede ser definida en php.ini o httpd.conf
`INI_ALL` (int)
  La entrada puede ser definida en cualquier lugar

## Cómo modificar la configuración

### Ejecutar PHP como módulo Apache

Cuando se utiliza el módulo Apache, también se pueden cambiar los parámetros de configuración utilizando las directivas en los ficheros de configuración de Apache (httpd.conf) y en los ficheros .htaccess. Se necesitarán los privilegios "AllowOverride Options" o "AllowOverride All".

Hay muchas directivas Apache que permiten modificar la configuración de PHP desde los ficheros de configuración de Apache. Para una lista de las directivas que son `INI_ALL`, `INI_PERDIR` o `INI_SYSTEM` consulte el anexo Lista de directivas del php.ini.

`php_value` `nombre` `valor`

  Modifica el valor de la directiva especificada. Esta instrucción solo es utilizable con las directivas PHP de tipo `INI_ALL` y `INI_PERDIR`. Para anular un valor que hubiera sido modificado previamente, utilice el valor `none`.

  > Nota: No utilice `php_value` para configurar valores booleanos. `php_flag` (ver más abajo) debe ser utilizada.

`php_flag` `nombre` `on|off`

  Esta instrucción se utiliza para activar o desactivar una opción. Esta instrucción solo es utilizable con las directivas PHP de tipo `INI_ALL` y `INI_PERDIR`.

`php_admin_value` `nombre` `valor`

  Esta instrucción asigna un valor a la variable especificada. Esta instrucción NO puede ser utilizada en un fichero .htaccess. Cualquier directiva de PHP configurada con el tipo `php_admin_value` no puede ser modificada utilizando el fichero .htaccess o la función ini_set(). Para anular un valor que hubiera sido modificado previamente, utilice la valor `none`.

`php_admin_flag` `name` `on|off`

  Esta directiva se utiliza para activar o desactivar una opción. Esta instrucción NO puede ser utilizada en un fichero .htaccess. Cualquier directiva de PHP configurada con el tipo `php_admin_flag` no puede ser modificada utilizando el fichero .htaccess o por la función ini_set().

Ejemplo #1 Ejemplo de configuración Apache

    <IfModule mod_php5.c>
      php_value include_path ".:/usr/local/lib/php"
      php_admin_flag engine on
    </IfModule>
    <IfModule mod_php4.c>
      php_value include_path ".:/usr/local/lib/php"
      php_admin_flag engine on
    </IfModule>

Precaución

Las constantes PHP no existen fuera de PHP. Por ejemplo, en el fichero httpd.conf, no se pueden utilizar constantes PHP como `E_ALL` o `E_NOTICE` para especificar el nivel de informe de errores, ya que estas constantes no tienen significado para Apache, y serán reemplazadas por 0. Utilice los valores numéricos en su lugar. Las constantes pueden ser utilizadas en el php.ini

### Modificar la configuración de PHP a través del registro de Windows

Cuando se utiliza PHP en Windows, la configuración puede ser modificada directorio por directorio utilizando el registro de Windows. Los valores de configuración se almacenan con la clave de registro `HKLM\SOFTWARE\PHP\Per Directory Values`, en las subclaves correspondientes a los nombres de directorio. Por ejemplo, el valor de una opción en el directorio `c:\inetpub\wwwroot` se almacenará en la clave `HKLM\SOFTWARE\PHP\Per Directory Values\c\inetpub\wwwroot`. El valor de esta opción será utilizado para todos los scripts que funcionen en este directorio o sus subdirectorios. Los valores bajo la clave deben tener el nombre de una dirección de configuración PHP, y el valor correspondiente. Las constantes PHP no son utilizables : hay que poner el valor entero. Sin embargo, solo los valores de las configuraciones en `INI_USER` pueden ser fijados de esta manera, los de `INI_PERDIR` no pueden serlo, ya que estos valores de configuración son releídos en cada solicitud.

### Otras interfaces de configuración de PHP

Según la forma en que se ejecute PHP, se pueden cambiar algunos valores durante la ejecución de los scripts utilizando ini_set(). Consulte la documentación de la función ini_set() para más información.

Si está interesado en una lista completa de las opciones configuradas en su sistema con sus valores actuales, puede ejecutar la función phpinfo() y consultar la página resultante. También se puede acceder individualmente a las directivas de configuración durante la ejecución de los scripts utilizando la función ini_get() o la función get_cfg_var().

- Consideraciones generales sobre la instalación
- Instalación en sistemas Unix
  - Instalación desde paquetes en Debian GNU/Linux y distribuciones similares
  - Instalación a partir de paquetes en distribuciones GNU/Linux que utilizan DNF
  - Instalación desde paquetes o puertos en OpenBSD
  - Instalación desde las fuentes en sistemas Unix y macOS
  - CGI y configuraciones de línea de comandos
  - Apache 2.x en sistemas Unix
  - Nginx 1.4.x en sistemas Unix
  - Lighttpd 1.4 en sistemas Unix
  - Servidor Web LiteSpeed/Servidor Web OpenLiteSpeed en sistemas Unix
  - Instalación en Solaris
- Instalación en un sistema macOS
  - Instalación en macOS utilizando paquetes de terceros
  - Compilar PHP en macOS
  - Uso de PHP integrado anterior a macOS Monterey
- Instalación en sistemas Windows
  - Configuración recomendada en sistemas Windows
  - Instalación manual de los binarios precompilados
  - Apache 2.x en Microsoft Windows
  - Instalación con IIS para Windows
  - Herramientas de terceros para la instalación de PHP
  - Construir a partir de las fuentes
  - Ejecución de PHP en línea de comandos en sistemas Windows
- Instalación en las plataformas de Nube Informática
  - Azure App services
  - Amazon EC2
  - DigitalOcean
- FastCGI Process Manager (FPM)
  - Instalación
  - Configuration
- Instalación de extensiones PECL
  - Introducción a las instalaciones PECL
  - Descarga de extensiones PECL
  - Instalación de una extensión PHP en Windows
  - Compilación de extensiones PECL compartidas con el comando pecl
  - Compilación de extensiones PECL compartidas con phpize
  - php-config
  - Compilación de extensiones PECL estáticamente en PHP
- Introducción a Composer
- Introducción a PIE
- Configuración en tiempo de ejecución
  - El fichero de configuración
  - Ficheros .user.ini
  - Dónde una directiva de configuración puede ser modificada
  - Cómo modificar la configuración

# Referencia del lenguaje

# La sintaxis básica

## Tabla de contenidos

- Etiquetas PHP
- Escape desde HTML
- Separación de instrucciones
- Comentarios

## Etiquetas PHP

Cuando PHP procesa un fichero, reconoce las etiquetas de apertura y de cierre, `<?php` y `?>`, para definir los límites de la ejecución del código PHP. El contenido fuera de las etiquetas es ignorado por el analizador PHP, permitiendo a PHP integrarse de manera transparente en diversos tipos de documentos.

Un carácter de espacio (espacio, tabulación, o nueva línea) debe seguir `<?php` para asegurar una separación correcta de los tokens. Omitir este espacio en blanco resultará en un error de sintaxis.

PHP incluye también la etiqueta corta echo `<?=`, que es un atajo para `<?php echo`.

Ejemplo #1 Etiquetas de apertura y cierre PHP

    1.  <?php echo 'Si se desea integrar código PHP en documentos XHTML o XML, utilice estas etiquetas'; ?>

    2.  Se puede utilizar la etiqueta corta para <?= 'escribir este texto' ?>.
        Es equivalente a <?php echo 'escribir este texto' ?>.

    3.  <? echo 'este código está entre etiquetas cortas'; ?>
        El siguiente código <?= 'texto' ?> es un atajo para <? echo 'texto' ?>

Las etiquetas cortas (tercer ejemplo) están disponibles por omisión, pero pueden ser desactivadas a través de la opción short_open_tag del fichero de configuración php.ini, o están desactivadas por omisión si PHP es compilado con la opción --disable-short-tags.

> Nota:

> Como las etiquetas cortas pueden ser desactivadas, se recomienda utilizar solo las etiquetas normales (`<?php ?>` y `<?= ?>`) para maximizar la compatibilidad.

Si un fichero termina con código PHP, es preferible no colocar la etiqueta de cierre al final del fichero. Esto permite evitar olvidar un espacio o una nueva línea después de la etiqueta de cierre de PHP, lo cual causaría efectos no deseados ya que PHP comenzará a mostrar la salida, lo cual no es a menudo el caso deseado.

Ejemplo #2 Fichero que contiene solo código PHP

    <?php
    echo "Hola mundo\n";

    // ... más código

    echo "Última instrucción\n";

    // el script termina aquí, sin la etiqueta de cierre PHP

## Escape desde HTML

Todo lo que se encuentra fuera de un par de etiquetas de apertura/cierre es ignorado por el analizador PHP, lo que permite tener ficheros PHP mezclando contenidos. Esto permite a PHP estar contenido en documentos HTML, para crear por ejemplo plantillas.

Ejemplo #1 Integrar PHP en HTML

    <p>Esto será ignorado por PHP y mostrado en el navegador.</p>
    <?php echo 'Mientras que esto será analizado por PHP.'; ?>
    <p>Esto también será ignorado por PHP y mostrado en el navegador.</p>

Esto funciona como se espera porque cuando el intérprete PHP encuentra la etiqueta de cierre ?>, simplemente comienza a mostrar lo que encuentra (a excepción de la nueva línea que es inmediatamente seguida: ver la instrucción de separación) hasta que encuentre otra etiqueta de apertura incluso si PHP se encuentra en medio de una instrucción condicional, en cuyo caso, el intérprete determinará la condición a tener en cuenta antes de tomar una decisión sobre lo que debe ser mostrado. Ver el siguiente ejemplo.

Uso de estructuras con condiciones

Ejemplo #2 Escape avanzado usando condiciones

    <?php if ($expression == true): ?>
      Esto será mostrado si la expresión es verdadera.
    <?php else: ?>
      De lo contrario, esto será mostrado.
    <?php endif; ?>

En este ejemplo, PHP ignorará los bloques donde la condición no se cumpla, incluso si están fuera de las etiquetas de apertura/cierre de PHP. PHP los ignorará según la condición ya que el intérprete PHP pasará los bloques que contienen lo que no se cumple por la condición.

Para mostrar grandes bloques de texto, es más eficiente salir del modo de análisis de PHP en lugar de enviar el texto a través de la función echo o print.

> Nota:

> Si PHP está integrado en un documento XML o XHTML, la etiqueta PHP estándar `<?php ?>` debe ser utilizada para mantener la conformidad con los estándares.

## Separación de instrucciones

Al igual que en C o en Perl, PHP requiere que las instrucciones sean terminadas por un punto y coma al final de cada instrucción. La etiqueta de cierre de un bloque de código PHP implica automáticamente un punto y coma; por lo tanto, no es necesario utilizar un punto y coma para terminar la última línea de un bloque PHP. La etiqueta de cierre de un bloque incluye el carácter de nueva línea seguido inmediatamente si uno está presente.

Ejemplo #1 Ejemplo que muestra que la etiqueta de cierre incluye la nueva línea que sigue

    <?php echo "Algún texto"; ?>
    Sin nueva línea
    <?= "Pero nueva línea ahora" ?>

El ejemplo anterior mostrará:

    Algún textoSin nueva línea
    Pero nueva línea ahora

Ejemplo #2 Ejemplos de entrada y salida del analizador PHP

    <?php
        echo 'Esto es una prueba\n';
    ?>

    <?php echo 'Esto es una prueba\n' ?>

    <?php echo 'Omitimos la última etiqueta de cierre\n';

> Nota:

> La etiqueta de cierre de un bloque PHP al final de un fichero es opcional, y a veces es útil omitirla cuando se utiliza la función include o la función require, ya que los espacios no deseados no aparecerán al final de los ficheros, y así, siempre se podrán agregar encabezados a la respuesta más tarde. Esto es útil también si se desea utilizar la visualización del búfer y no se desea ver espacios en blanco añadidos al final de las partes generadas por los ficheros incluidos.

## Comentarios

PHP soporta los comentarios de tipo C, C++ y Shell Unix (también llamado estilo Perl). Por ejemplo :

Ejemplo #1 Comentarios

    <?php
        echo 'Esto es una prueba\n'; // Esto es un comentario de una sola línea, estilo c++
        /* Esto es un comentario de
           varias líneas */
        echo 'Esto es otra prueba\n';
        echo 'Y una prueba final\n'; # Esto es un comentario de una sola línea estilo shell
    ?>

Los comentarios de una sola línea solo comentan hasta el final de la línea del bloque PHP actual. Esto significa que el código HTML después de `// ... ?>` o después de `# ... ?>` SERÁ mostrado: ?> terminará el modo PHP y volverá al modo HTML, y `//` o `#` no influirá en ello.

Ejemplo #2 Los comentarios van hasta el final de la línea

    <h1>Esto es un ejemplo <?php # echo 'simple';?></h1>
    <p>La línea anterior mostrará 'Esto es un ejemplo'.</p>

Los comentarios estilo 'C' comentan hasta que se encuentre el primer `*/`. Se debe tener cuidado con los comentarios estilo 'C' anidados en grandes bloques cuando se comentan.

    <?php
     /*
        echo 'Esto es una prueba'; /* Este comentario causará un problema */
     */
    ?>

# Los tipos

## Tabla de contenidos

- Introducción
- Sistema de tipos
- NULL
- Booleano
- Los enteros
- Números de punto flotante
- Cadenas
- Strings numéricos
- Arrays
- Los objetos
- Las enumeraciones
- Recursos
- Callables
- Mixed
- Void
- Never
- Tipos de clases relativas
- Tipo singleton
- Iterables
- Declaraciones de tipo
- Manipulación de tipos

## Introducción

En PHP, cada expresión tiene uno de los siguientes tipos integrados según su valor:

- null
- bool
- int
- float (número de punto flotante)
- string
- array
- object
- callable
- resource

PHP es un lenguaje de tipado dinámico, lo que significa que, por omisión, no es necesario especificar el tipo de una variable, ya que esto se determinará en tiempo de ejecución. Sin embargo, es posible tipar estáticamente ciertos aspectos del lenguaje utilizando las declaraciones de tipo. Los diferentes tipos soportados por el sistema de tipos de PHP están disponibles en la página del sistema de tipos.

Los tipos limitan el tipo de operaciones que pueden realizarse sobre ellos. Sin embargo, si una expresión/variable se utiliza en una operación que su tipo no soporta, PHP intentará manipular el tipo en un tipo compatible con la operación. Este proceso depende del contexto en el que se utiliza el valor. Para más información, consulte la sección sobre la manipulación de tipos.

Sugerencia

Las tablas de comparación de tipos pueden ser también útiles, ya que se presentan diversos ejemplos de comparación entre valores de diferentes tipos.

> Nota: Es posible forzar la evaluación de una expresión a un cierto tipo utilizando un type casting. Una variable también puede ser convertida en el lugar utilizando la función settype().

Para verificar el tipo y el valor de una expresión, utilice la función var_dump(). Para recuperar el tipo de una expresión, utilice la función get_debug_type(). Sin embargo, para verificar si una expresión es de un cierto tipo, utilice mejor las funciones `is_type`.

Ejemplo #1 Tipos Diferentes

    <?php
    $a_bool = TRUE;   // un booleano
    $a_str  = "foo";  // un string
    $a_str2 = 'foo';  // un string
    $an_int = 12;     // un integer

    echo gettype($a_bool); // muestra:  boolean
    echo gettype($a_str);  // muestra:  string

    // Si es un integer, incrementa en 4
    if (is_int($an_int)) {
        $an_int += 4;
    }

    // Si $a_bool es un string, se muestra
    if (is_string($a_bool)) {
        echo "String: $a_bool";
    }
    ?>

Resultado del ejemplo anterior en PHP 8:

    bool
    string
    int(16)

> Nota: Anterior a PHP 8.0.0, cuando la función get_debug_type() no está disponible, la función gettype() puede ser utilizada en su lugar. Sin embargo, no utiliza los nombres de tipo canónicos.

## Sistema de tipos

PHP utiliza un sistema de tipos nominal con una fuerte relación de subtipado comportamental. La relación de subtipado se verifica en la compilación, mientras que la verificación de tipos se verifica dinámicamente en el momento de la ejecución.

El sistema de tipos de PHP soporta varios tipos atómicos que pueden ser compuestos juntos para crear tipos más complejos. Algunos de estos tipos pueden ser escritos en forma de declaración de tipo.

### Tipos atómicos

Algunos tipos atómicos son tipos que están estrechamente integrados en el lenguaje y no pueden ser reproducidos con tipos definidos por el usuario.

La lista de tipos básicos es la siguiente:

- Tipos integrados
  - Tipos escalares:
    - tipo bool
    - tipo int
    - tipo float
    - tipo string
  - tipo array
  - tipo object
  - tipo resource
  - tipo never
  - tipo void
  - Tipos de clases relativas: self, parent, y static
  - Tipos singleton
    - false
    - true
  - Tipos unitarios
    - null
- Tipos definidos por el usuario (generalmente llamados clases-tipos)
  - Interfaces
  - Clases
  - Enumeraciones
- tipo callable

#### Tipos escalares

Un valor se considera escalar si es de tipo int, float, string o bool.

#### Tipos definidos por el usuario

Es posible definir tipos personalizados con interfaces, clases y enumeraciones. Estos se consideran tipos definidos por el usuario, o tipos de clase. Por ejemplo, una clase llamada `Elephant` puede ser definida, luego objetos de tipo `Elephant` pueden ser instanciados, y una función puede requerir un argumento de tipo `Elephant`.

### Tipos compuestos

Es posible combinar varios tipos atómicos en tipos compuestos. PHP permite combinar los tipos de la siguiente manera:

- Intersección de clases-tipos (interfaces y nombres de clases).
- Unión de tipos.

#### Intersección de tipos

Un tipo de intersección acepta valores que satisfacen varias declaraciones de tipo de clase, en lugar de una sola. Los tipos individuales que forman el tipo de intersección están unidos por el símbolo `&`. Por lo tanto, un tipo de intersección compuesto por los tipos `T`, `U` y `V` se escribe `T&U&V`.

#### Tipos de unión

Un tipo de unión acepta valores de varios tipos diferentes, en lugar de uno solo. Los tipos individuales que forman el tipo de unión están unidos por el símbolo `|`. Por lo tanto, un tipo de unión compuesto por los tipos `T`, `U` y `V` se escribe `T|U|V`. Si uno de los tipos es un tipo de intersección, debe ser puesto entre paréntesis para ser escrito en DNF. `T|(X&Y)`.

### Alias de tipo

PHP soporta dos alias de tipo: mixed y iterable que corresponde al tipo tipo de unión de `object|resource|array|string|float|int|bool|null` y `Traversable|array` respectivamente.

> Nota: PHP no soporta alias de tipo definidos por el usuario.

## NULL

El tipo null es el tipo unidad de PHP, es decir, que solo tiene un valor: `null`.

Las variables no definidas y unset() tendrán el valor `null`.

### Sintaxis

Solo hay un valor de tipo null, y es la constante insensible a mayúsculas y minúsculas `null`.

    <?php
    $var = NULL;
    ?>

### Conversión a `null`

Advertencia

Esta funcionalidad está OBSOLETA a partir de PHP 7.2.0, y ELIMINADA a partir de PHP 8.0.0. Depender de esta funcionalidad está altamente desaconsejado.

Convertir una variable a null utilizando la sintaxis `(unset) $var` no borrará la variable, ni sobrescribirá su valor. Solo devolverá el valor `null`.

### Ver también

- is_null()
- unset()

## Booleano

El tipo bool solo posee dos valores y se utiliza para expresar un valor de verdad. Puede ser `true` o `false`.

### Sintaxis

Para especificar un bool literal, utilice la constante `true` o `false`. Ambas son insensibles a mayúsculas y minúsculas.

    <?php

    $foo = true; // asigna el valor TRUE a $foo

    var_dump($foo); // bool(true)
    ?>

Típicamente, el resultado de un operador que devuelve un bool, pasado luego a una estructura de control.

    <?php

    $action = "show_version";
    $show_separators = true;

    // == es un operador que prueba
    // la igualdad y devuelve un booleano
    if ($action == "show_version") {
        echo "La versión es 1.23";
    }

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

    // ...en su lugar, se puede utilizar, con el mismo significado:
    if ($show_separators) {
        echo "<hr>\n";
    }
    ?>

### Conversión en booleano

Para convertir explícitamente un valor en bool, utilice el cast `(bool)`. Generalmente, esto no es necesario porque cuando un valor se utiliza en un contexto lógico, se interpretará automáticamente como un valor de tipo bool. Para más información, ver la página Type Juggling.

Al convertir en bool, los siguientes valores son considerados como `false`:

- el booleano `false`, en sí mismo
- el entero `0` (cero)
- los números de punto flotante `0.0` y `-0.0` (cero)
- la cadena vacía `""`, y la cadena `"0"`
- un array sin elementos
- el tipo unidad NULL (incluyendo variables no definidas)
- los objetos internos que sobrecargan su comportamiento de casting en booleano. Por ejemplo, los objetos GMP que representan el valor `0`.

Todos los demás valores son considerados como `true` (incluyendo los recursos y `NAN`).

Advertencia

`-1` es considerado como `true`, como todos los números diferentes de cero (negativos o positivos) !

Ejemplo #1 Conversión en booleano

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

## Los enteros

Un int es un número perteneciente al conjunto ℤ = {..., -2, -1, 0, 1, 2, ...}.

### Ver también

- Los números de coma flotante
- Las precisiones arbitrarias / BCMath
- Los enteros de longitud arbitraria / GMP

### Sintaxis

Los ints pueden ser especificados en notación decimal (base 10), hexadecimal (base 16), octal (base 8), o binaria (base 2). El operador de negación puede ser utilizado para designar un int negativo.

Para utilizar la notación octal, preceda el número de un `0` (cero). A partir de PHP 8.1.0, la notación octal puede ser precedida con `0o` o `0O`. Para utilizar la notación hexadecimal, preceda el número de `0x`. Para utilizar la notación binaria, preceda el número de `0b`.

A partir de PHP 7.4.0, los enteros literales pueden contener underscores (`_`) entre los dígitos, para una mejor legibilidad de los literales. Estos underscores son eliminados por el escáner de PHP.

Ejemplo #1 Los enteros literales

    <?php
    $a = 1234; // un número decimal
    $a = 0123; // un número octal (equivalente a 83 en decimal)
    $a = 0o123; // un número octal (a partir de PHP 8.1.0)
    $a = 0x1A; // un número hexadecimal (equivalente a 26 en decimal)
    $a = 0b11111111; // un número binario (equivalente a 255 en decimal)
    $a = 1_234_567; // un número decimal (a partir de PHP 7.4.0)
    ?>

Formalmente, la estructura de un int literal es a partir de PHP 8.1.0 (anteriormente, los prefijos octales `0o` o `0O` no estaban permitidos, y antes de PHP 7.4.0, los underscores no estaban permitidos.

    decimal     : [1-9][0-9]*(_[0-9]+)*
                | 0

    hexadecimal : 0[xX][0-9a-fA-F]+(_[0-9a-fA-F]+)*

    octal       : 0[oO]?[0-7]+(_[0-7]+)*

    binary      : 0[bB][01]+(_[01]+)*

    integer     : decimal
                | hexadecimal
                | octal
                | binary

El tamaño de un int es dependiente de la plataforma, sin embargo, un valor máximo de aproximadamente 2 mil millones es habitual (esto corresponde a 32 bits con signo). Las plataformas de 64 bits tienen habitualmente un valor máximo de aproximadamente 9E18. PHP no soporta los ints sin signo. El tamaño de un int puede ser determinado utilizando la constante `PHP_INT_SIZE`, el valor máximo, utilizando la constante `PHP_INT_MAX`, y el valor mínimo utilizando la constante `PHP_INT_MIN`.

### Desbordamiento de entero

Si PHP encuentra un número superior al máximo de un int, será interpretado como un float. De la misma manera, una operación que resulte en un número fuera del rango del tipo int devolverá un float.

Ejemplo #2 Desbordamiento de entero en un sistema de 32 bits

    <?php

    $large_number = 50000000000000000000;
    var_dump($large_number);         // float(5.0E+19)
    var_dump(PHP_INT_MAX + 1);       // sistema de 32 bits: float(2147483648)
                                     // sistema de 64 bits: float(9.2233720368548E+18)
    ?>

### División de entero

No hay operador de división de int en PHP, para lograr esto utilizar la función intdiv(). `1/2` produce el float (`0.5`). El valor puede ser convertido en un int para redondear hacia cero, o utilizando la función round() para tener un control más fino sobre cómo se realiza el redondeo.

Ejemplo #3 División

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

### Conversión en entero

Para convertir explícitamente un valor a int, utilice la conversión `(int)`. Sin embargo, en la mayoría de los casos no es necesaria la conversión, ya que un valor se convertirá automáticamente si un operador, función o estructura de control requiere un argumento int. Un valor puede también ser convertido en un int utilizando la función intval().

Si un resource es convertido a un int, entonces el resultado será el identificador único del resource asignado por PHP en la ejecución.

Ver también el transtipado.

#### Desde un booléen

`false` corresponde a `0` (cero), y `true` corresponde a `1` (uno).

#### Desde un número de coma flotante

Al convertir un float en int, el número es redondeado hacia cero. A partir de PHP 8.1.0, se emite una notificación de deprecación al realizar la conversión implícita de un float no integral en int perdiendo precisión.

Ejemplo #4 Conversión desde números flotantes

    <?php

    function foo($value): int {
      return $value;
    }

    var_dump(foo(8.1)); // "Deprecated: Implicit conversion from float 8.1 to int loses precision" a partir de PHP 8.1.0
    var_dump(foo(8.1)); // Antes de PHP 8.1.0
    var_dump(foo(8.0)); // 8 en ambos casos

    var_dump((int) 8.1); // 8 en ambos casos
    var_dump(intval(8.1)); // 8 en ambos casos
    ?>

Si el número de coma flotante está más allá de los límites de los ints (habitualmente, `+/- 2.15e+9 = 2^31` en plataformas de 32 bits y `+/- 9.22e+18 = 2^63` en plataformas de 64 bits), el resultado será indefinido, ya que el float no tiene suficiente precisión para dar un resultado int exacto. ¡No se emite ninguna alerta cuando ocurre este comportamiento!

> Nota:

> `NaN`, `Infinity` y `-Inf` son siempre igual a cero al convertir en int.

Advertencia

Nunca convierta una fracción desconocida en un int, esto puede generar resultados inesperados.

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

Ver también la sección sobre las alertas concernientes a la precisión de los números de coma flotante.

#### Desde cadenas de caracteres

Si una cadena es numérica o numérica de cabeza entonces será transformada en su valor entero correspondiente, de lo contrario será convertida a cero (`0`).

#### Desde NULL

`null` es siempre convertido en cero (`0`).

#### Desde otros tipos

Precaución

El comportamiento de la conversión en int es indefinido desde otros tipos. No reportar ningún comportamiento observado, sabiendo que pueden cambiar sin previo aviso.

## Números de punto flotante

Los números de punto flotante (también conocidos como "floats", "doubles" o "números reales") pueden ser especificados utilizando las siguientes sintaxis:

    <?php
    $a = 1.234;
    $b = 1.2e3;
    $c = 7E-10;
    $d = 1_234.567; // a partir de PHP 7.4.0
    ?>

Formalmente a partir de PHP 7.4.0 (anteriormente, los guiones bajos no estaban permitidos):

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

El tamaño de un float depende de la plataforma, sin embargo, un número máximo de aproximadamente 1.8e308 con una precisión de 14 dígitos es un valor común (formato de 64 bits IEEE).

Advertencia

# Precisión de los números de punto flotante

Los números de punto flotante tienen una precisión limitada. Aunque dependen del sistema, PHP utiliza el formato de precisión decimal IEEE 754, que dará un error relativo máximo del orden de 1.11e-16 (debido a los redondeos). Las operaciones aritméticas no elementales pueden dar errores más grandes y, por supuesto, los errores deben ser tenidos en cuenta cuando se realizan múltiples operaciones.

Asimismo, los números racionales exactamente representables como números de punto flotante en base 10, como `0.1` o `0.7`, no tienen una representación exacta como números de punto flotante en base 2, utilizada internamente, y esto independientemente del tamaño de la mantisa. Por lo tanto, no pueden ser convertidos sin una pequeña pérdida de precisión. Esto puede llevar a resultados confusos: por ejemplo, `floor((0.1+0.7)*10)` normalmente devolverá `7` en lugar del `8` esperado, ya que la representación interna será algo como `7.9999999999999991118...`.

Por lo tanto, nunca se debe confiar en los últimos dígitos de un número de punto flotante, y tampoco se debe comparar la igualdad de 2 números de punto flotante directamente. Si se necesita una mayor precisión, las funciones matemáticas de precisión arbitraria y las funciones gmp están disponibles.

Para una explicación "simple", ver el » guía relativa a los números de punto flotante.

### Convertir a un número de punto flotante

#### Desde cadenas de caracteres

Si una cadena es numérica o numérica de cabeza entonces será transformada en su valor de punto flotante correspondiente, de lo contrario será convertida a cero(`0`).

#### Desde otros tipos

Para los valores de otros tipos, la conversión se realiza convirtiendo el valor primero en int y luego en float. Ver conversión a entero para más información.

> Nota:

> Como algunos tipos tienen un comportamiento indefinido al convertirse en int, esto también es el caso al convertirse en float.

### Comparación de números de punto flotante

Como se mencionó anteriormente, la prueba de igualdad de valores de números de punto flotante es problemática, debido a la forma en que se representan internamente. Sin embargo, existen formas de realizar esta comparación.

Para probar la igualdad de valores de números de punto flotante, se utiliza un límite superior del error relativo al redondeo. Este valor es conocido como el epsilon de la máquina, o unit roundoff, y es la diferencia más pequeña aceptable en los cálculos.

$a y $b son iguales en 5 números después de la coma.

Ejemplo #1 Comparación de números de punto flotante

    <?php
    $a = 1.23456789;
    $b = 1.23456780;
    $epsilon = 0.00001;

    if( abs($a - $b) < $epsilon) {
        echo "true";
    }
    ?>

### NaN

Algunas operaciones numéricas pueden dar como resultado un valor representado por la constante `NAN`. Este resultado representa un valor indefinido o no representable en cálculos con números de punto flotante. Cualquier comparación, incluso estricta de este valor con otro valor, incluyendo esta constante misma, excepto si es igual a `true`, dará un valor de `false`.

Debido a que `NAN` representa cualquier número de valores diferentes, `NAN` no debe ser comparado con otros valores, incluyendo esta constante misma, y en su lugar, debe ser verificado utilizando la función is_nan().

## Cadenas

Un string es una serie de caracteres, donde un caracter es lo mismo que un octeto. Esto significa que PHP solo admite un conjunto de 256 caracteres, y por lo tanto no ofrece soporte nativo para Unicode. Ver los detalles del tipo string.

> Nota: En las versiones de 32 bits, un string puede ser tan grande como 2 Go (2147483647 octetos maximo)

### Sintaxis

Un string literal puede especificarse de cuatro maneras diferentes:

- entre comillas simples
- entre comillas dobles
- sintaxis heredoc
- sintaxis nowdoc

#### Entre comillas simples

La manera más simple de especificar un string es encerrarlo entre comillas simples (el caracter `'`).

Para especificar una comilla simple literal, escápela con un backslash (`\`). Para especificar un backslash literal, duplíquelo (`\\`). Todas las demás ocurrencias del backslash serán tratadas como un backslash literal: esto significa que otras secuencias de escape que usted podría conocer, tales como `\r` o `\n`, serán salidas literalmente como se especifica en lugar de tener un significado especial.

> Nota: A diferencia de las comillas dobles y sintaxis heredoc, las variables y las secuencias de escape para caracteres especiales no serán extendidas cuando se encuentren en strings entre comillas simples.

Ejemplo #1 Variantes de sintaxis

    <?php
    echo 'esto es un string simple', PHP_EOL;

    echo 'Usted puede también tener nuevas líneas integradas
    en los strings de esta manera, ya que
    es aceptable hacerlo.', PHP_EOL;

    // Muestra: Arnold dijo una vez: "Volveré"
    echo 'Arnold dijo una vez: "Volveré"', PHP_EOL;

    // Muestra: ¿Usted ha borrado C:\*.*?
    echo '¿Usted ha borrado C:\\*.* ?', PHP_EOL;

    // Muestra: ¿Usted ha borrado C:\*.*?
    echo '¿Usted ha borrado C:\*.* ?', PHP_EOL;

    // Muestra: Esto no se extenderá: \n una nueva línea
    echo 'Esto no se\'extenderá: \n una nueva línea', PHP_EOL;

    // Muestra: Las variables no $se\'extienden $tampoco
    echo 'Las variables no $se\'extienden $tampoco', PHP_EOL;
    ?>

#### Entre comillas dobles

Si el string está encerrado entre comillas dobles (`"`), PHP interpretará las siguientes secuencias de escape para caracteres especiales:

Caracteres escapados
Secuencia | Significado
--- | ---
`\n` | retorno de carro (LF o 0x0A (10) en ASCII)
`\r` | retorno de carro (CR o 0x0D (13) en ASCII)
`\t` | tabulación horizontal (HT o 0x09 (9) en ASCII)
`\v` | tabulación vertical (VT o 0x0B (11) en ASCII)
`\e` | escape (ESC o 0x1B (27) en ASCII)
`\f` | avance de formulario (FF o 0x0C (12) en ASCII)
`\\` | backslash
`\$` | signo de dólar
`\"` | comilla doble
`\[0-7]{1,3}` | Octal: la secuencia de caracteres correspondiente a la expresión regular `[0-7]{1,3}` es un caracter en notación octal (por ejemplo, `"\101" === "A"`), que desborda silenciosamente para adaptarse a un octeto (por ejemplo, `"\400" === "\000"`)
`\x[0-9A-Fa-f]{1,2}` | Hexadecimal: la secuencia de caracteres correspondiente a la expresión regular `[0-9A-Fa-f]{1,2}` es un caracter en notación hexadecimal (por ejemplo, `"\x41" === "A"`)
`\u{[0-9A-Fa-f]+}` | Unicode: la secuencia de caracteres correspondiente a la expresión regular `[0-9A-Fa-f]+` es un punto de código Unicode, que será salido en el string bajo la representación UTF-8 de este punto de código. Las llaves son requeridas en la secuencia. Por ejemplo, `"\u{41}" === "A"`

Como para los strings entre comillas simples, escapar cualquier otro caracter también resultará en la impresión del backslash.

La característica más importante de los strings entre comillas dobles es el hecho de que los nombres de variables serán extendidos. Ver la interpolación de strings para más detalles.

#### Heredoc

Una tercera manera de delimitar los strings es la sintaxis heredoc: `<<<`. Después de este operador, se proporciona un identificador, luego una nueva línea. El string mismo sigue, luego el mismo identificador nuevamente para cerrar la cita.

El identificador de cierre puede estar indentado con espacios o tabulaciones, en cuyo caso la indentación será eliminada de todas las líneas en el string doc. Antes de PHP 7.3.0, el identificador de cierre debe comenzar en la primera columna de la línea.

Además, el identificador de cierre debe seguir las mismas reglas de nombramiento que cualquier otro etiqueta en PHP: debe contener solo caracteres alfanuméricos y guiones bajos, y debe comenzar con un carácter no numérico o un guión bajo.

Ejemplo #2 Ejemplo básico de Heredoc a partir de PHP 7.3.0

    <?php
    // sin indentación
    echo <<<END
          a
         b
        c
    \n
    END;

    // 4 espacios de indentación
    echo <<<END
          a
         b
        c
        END;

Resultado del ejemplo anterior en PHP 7.3:

          a
         b
        c

      a
     b
    c

Si el identificador de cierre está indentado más que cualquier línea del cuerpo, entonces se levantará un ParseError:

Ejemplo #3 El identificador de cierre no debe estar indentado más que cualquier línea del cuerpo

    <?php
    echo <<<END
      a
     b
    c
       END;

Resultado del ejemplo anterior en PHP 7.3:

    Parse error: Invalid body indentation level (expecting an indentation level of at least 3) in example.php on line 4

Si el identificador de cierre está indentado, las tabulaciones también pueden ser utilizadas, sin embargo, las tabulaciones y los espacios no deben mezclarse en cuanto a la indentación del identificador de cierre y la indentación del cuerpo (hasta el identificador de cierre). En cualquiera de estos casos, se levantará un ParseError. Estas restricciones de espacio han sido incluidas porque mezclar espacios y tabulaciones para la indentación perjudica la legibilidad.

Ejemplo #4 Indentación diferente para el cuerpo (espacios) identificador de cierre

    <?php
    // Todo el código siguiente no funciona.

    // indentación diferente para el cuerpo (espacios) marcador de fin (tabulaciones)
    {
        echo <<<END
            a
            END;
    }

    // mezcla de espacios y tabulaciones en el cuerpo
    {
        echo <<<END
                a
            END;
    }

    // mezcla de espacios y tabulaciones en el marcador de fin
    {
        echo <<<END
                a
            END;
    }

Resultado del ejemplo anterior en PHP 7.3:

    Parse error: Invalid indentation - tabs and spaces cannot be mixed in example.php line 8

El identificador de cierre para el string del cuerpo no es requerido para ser seguido de un punto y coma o un salto de línea. Por ejemplo, el siguiente código es permitido a partir de PHP 7.3.0:

Ejemplo #5 Continuación de una expresión después de un identificador de cierre

    <?php
    $values = [<<<END
    a
      b
        c
    END, 'd e f'];
    var_dump($values);

Resultado del ejemplo anterior en PHP 7.3:

    array(2) {
      [0] =>
      string(11) "a
      b
        c"
      [1] =>
      string(5) "d e f"
    }

Advertencia

Si el identificador de cierre ha sido encontrado al principio de una línea, entonces no importa si formaba parte de otra palabra, puede ser considerado como el identificador de cierre y provocar un ParseError.

Ejemplo #6 El identificador de cierre en el cuerpo del string tiende a provocar un ParseError

    <?php
    $values = [<<<END
    a
    b
    END ING
    END, 'd e f'];

Resultado del ejemplo anterior en PHP 7.3:

    Parse error: syntax error, unexpected identifier "ING", expecting "]" in example.php on line 5

Para evitar este problema, es seguro seguir la regla simple: no elegir una palabra que aparezca en el cuerpo del texto como identificador de cierre.

Advertencia

Antes de PHP 7.3.0, es muy importante señalar que la línea que contiene el identificador de cierre no debe contener ningún otro carácter, excepto un punto y coma (`;`). Esto significa principalmente que el identificador no puede estar indentado, y no debe haber espacios o tabulaciones antes o después del punto y coma. También es importante darse cuenta de que el primer carácter antes del identificador de cierre debe ser un salto de línea tal como se define en el sistema operativo local. Es `\n` en los sistemas UNIX, incluyendo macOS. El delimitador de cierre también debe ser seguido de un salto de línea.

Si esta regla se viola y el identificador de cierre no está "limpio", no será considerado como un identificador de cierre, y PHP continuará buscando uno. Si un identificador de cierre adecuado no se encuentra antes del final del archivo actual, se producirá un error de análisis en la última línea.

Ejemplo #7 Ejemplo inválido, antes de PHP 7.3.0

    <?php
    class foo {
        public $bar = <<<EOT
    bar
        EOT;
    }
    // El identificador no debe estar indentado
    ?>

Ejemplo #8 Ejemplo válido, incluso antes de PHP 7.3.0

    <?php
    class foo {
        public $bar = <<<EOT
    bar
    EOT;
    }
    ?>

Los heredocs que contienen variables no pueden ser utilizados para inicializar propiedades de clase.

El texto heredoc se comporta exactamente como un string entre comillas dobles, sin las comillas. Esto significa que las comillas en un heredoc no necesitan ser escapadas, pero los códigos de escape mencionados anteriormente pueden seguir siendo utilizados. Las variables son desarrolladas, pero debe tenerse el mismo cuidado al expresar variables complejas dentro de un heredoc que para los strings.

Ejemplo #9 Ejemplo de cita de string heredoc

    <?php
    $str = <<<EOD
    Ejemplo de string
    que se extiende sobre múltiples líneas
    usando la sintaxis heredoc.
    EOD;

    /* Ejemplo más complejo, con variables. */
    class foo
    {
        var $foo;
        var $bar;

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

    $foo = new foo();
    $name = 'MyName';

    echo <<<EOT
    Mi nombre es "$name". Estoy imprimiendo $foo->foo.
    Ahora, estoy imprimiendo {$foo->bar[1]}.
    Esto debería imprimir una 'A' mayúscula: \x41
    EOT;
    ?>

El ejemplo anterior mostrará:

    Mi nombre es "MyName". Estoy imprimiendo Foo.
    Ahora, estoy imprimiendo Bar2.
    Esto debería imprimir una 'A' mayúscula: A

También es posible utilizar la sintaxis heredoc para pasar datos a los argumentos de función:

Ejemplo #10 Heredoc en ejemplos de argumentos

    <?php
    var_dump(array(<<<EOD
    foobar!
    EOD
    ));
    ?>

Es posible inicializar variables estáticas y propiedades/constantes de clase utilizando la sintaxis heredoc:

Ejemplo #11 Uso de Heredoc para inicializar valores estáticos

    <?php
    // Variables estáticas
    function foo()
    {
        static $bar = <<<LABEL
    Nada aquí...
    LABEL;
    }

    // Propiedades/constantes de clase
    class foo
    {
        const BAR = <<<FOOBAR
    Ejemplo de constante
    FOOBAR;

        public $baz = <<<FOOBAR
    Ejemplo de propiedad
    FOOBAR;
    }
    ?>

El identificador de apertura del Heredoc puede eventualmente ser encerrado entre comillas dobles:

Ejemplo #12 Uso de comillas dobles en el Heredoc

    <?php
    echo <<<"FOOBAR"
    ¡Hola mundo!
    FOOBAR;
    ?>

#### Nowdoc

Los nowdocs son para los strings entre comillas simples lo que los heredocs son para los strings entre comillas dobles. Un nowdoc se especifica de manera similar a un heredoc, pero ninguna interpolación de string es realizada dentro de un nowdoc. La construcción es ideal para integrar código PHP o otros bloques de texto voluminosos sin necesidad de escapar. Comparte algunas características con la construcción SGML `<![CDATA[ ]]>`, en el sentido de que declara un bloque de texto que no está destinado a ser analizado.

Un nowdoc es identificado por la misma secuencia `<<<` utilizada para los heredocs, pero el identificador que sigue está encerrado entre comillas simples, por ejemplo `<<<'EOT'`. Todas las reglas para los identificadores heredoc se aplican también a los identificadores nowdoc, en particular aquellas concernientes a la apariencia del identificador de cierre.

Ejemplo #13 Ejemplo de cita de string nowdoc

    <?php
    echo <<<'EOD'
    Ejemplo de string que se extiende sobre múltiples líneas
    usando la sintaxis nowdoc. Las barras invertidas son siempre tratadas literalmente,
    es decir \\ y \'.
    EOD;

El ejemplo anterior mostrará:

    Ejemplo de string que se extiende sobre múltiples líneas
    usando la sintaxis nowdoc. Las barras invertidas son siempre tratadas literalmente,
    es decir \\ y \'.

Ejemplo #14 Ejemplo de cita de string nowdoc con variables

    <?php
    class foo
    {
        public $foo;
        public $bar;

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

    $foo = new foo();
    $name = 'MyName';

    echo <<<'EOT'
    Mi nombre es "$name". Estoy imprimiendo $foo->foo.
    Ahora, estoy imprimiendo {$foo->bar[1]}.
    Esto no debería imprimir una 'A' mayúscula: \x41
    EOT;
    ?>

El ejemplo anterior mostrará:

    Mi nombre es "$name". Estoy imprimiendo $foo->foo.
    Ahora, estoy imprimiendo {$foo->bar[1]}.
    Esto no debería imprimir una 'A' mayúscula: \x41

Ejemplo #15 Ejemplo de datos estáticos

    <?php
    class foo {
        public $bar = <<<'EOT'
    bar
    EOT;
    }
    ?>

#### Interpolación de strings

Cuando un string es especificado entre comillas dobles o con heredoc, las variables pueden ser sustituidas dentro.

Existen dos tipos de sintaxis: una básica y una avanzada. La sintaxis básica es la más común y práctica. Ofrece un medio para incorporar una variable, un valor array o una propiedad objeto en un string con un mínimo de esfuerzo.

##### Sintaxis básica

Si un signo de dólar (`$`) es encontrado, los caracteres que lo siguen y que pueden ser utilizados en un nombre de variable serán interpretados como tales y sustituidos.

Ejemplo #16 Interpolación de strings

    <?php
    $juice = "manzana";

    echo "Él bebió un poco de $juice jugo." . PHP_EOL;

    ?>

El ejemplo anterior mostrará:

    Él bebió un poco de manzana jugo.

Formalmente, la estructura para la sintaxis de sustitución de variable básica es la siguiente:

    string-variable::
         variable-name   (offset-or-property)?
       | ${   expression   }

    offset-or-property::
         offset-in-string
       | property-in-string

    offset-in-string::
         [   name   ]
       | [   variable-name   ]
       | [   integer-literal   ]

    property-in-string::
         ->  name

    variable-name::
         $   name

    name::
         [a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*

Advertencia

La sintaxis `${ expression }` está deprecada desde PHP 8.2.0, ya que puede ser interpretada como variables de variables:

    <?php
    const foo = 'bar';
    $foo = 'foo';
    $bar = 'bar';
    var_dump("${foo}");
    var_dump("${(foo)}");
    ?>

Resultado del ejemplo anterior en PHP 8.2:

    Deprecated: Usar ${var} en strings está deprecado, use {$var} en su lugar en el archivo en la línea 6

    Deprecated: Usar ${expr} (variables de variables) en strings está deprecado, use {${expr}} en su lugar en el archivo en la línea 9
    string(3) "foo"
    string(3) "bar"

El ejemplo anterior mostrará:

    string(3) "foo"
    string(3) "bar"

La sintaxis de interpolación de string avanzada debería ser utilizada en su lugar.

> Nota: Si no es posible formar un nombre válido, el signo de dólar tal cual en el string:

>     <?php
>     echo "Ninguna interpolación $  ha ocurrido\n";
>     echo "Ninguna interpolación $\n ha ocurrido\n";
>     echo "Ninguna interpolación $2 ha ocurrido\n";
>     ?>

> El ejemplo anterior mostrará:

>     Ninguna interpolación $  ha ocurrido
>     Ninguna interpolación $
>      ha ocurrido
>     Ninguna interpolación $2 ha ocurrido

Ejemplo #17 Interpolación del valor de la primera dimensión de un array o propiedad

    <?php
    $juices = array("manzana", "naranja", "string_key" => "violet");

    echo "Él bebió un poco de $juices[0] jugo.";
    echo PHP_EOL;
    echo "Él bebió un poco de $juices[1] jugo.";
    echo PHP_EOL;
    echo "Él bebió un poco de $juices[string_key] jugo.";
    echo PHP_EOL;

    class A {
        public $s = "string";
    }

    $o = new A();

    echo "Valor del objeto: $o->s.";
    ?>

El ejemplo anterior mostrará:

    Él bebió un poco de manzana jugo.
    Él bebió un poco de naranja jugo.
    Él bebió un poco de violet jugo.
    Valor del objeto: string.

> Nota: La clave del array debe ser no citada, y por lo tanto no es posible referenciar una constante como clave con la sintaxis básica. Utilice la sintaxis avanzada en su lugar.

Desde PHP 7.1.0, los índices numéricos negativos también son soportados.

Ejemplo #18 Índices numéricos negativos

    <?php
    $string = 'string';
    echo "El carácter en el índice -2 es $string[-2].", PHP_EOL;
    $string[-3] = 'o';
    echo "Cambiar el carácter en el índice -3 a o da $string.", PHP_EOL;
    ?>

El ejemplo anterior mostrará:

    El carácter en el índice -2 es n.
    Cambiar el carácter en el índice -3 a o da strong.

Para todo lo que es más complejo, la sintaxis avanzada debe ser utilizada.

##### Sintaxis avanzada (sintaxis de llaves)

La sintaxis avanzada permite la interpolación de variables con accesorios arbitrarios.

Cualquier variable escalar, elemento de array o propiedad de objeto (estática o no) con una representación string puede ser incluida mediante esta sintaxis. La expresión es escrita de la misma manera que aparecería fuera de la string, luego encerrada entre `{` y `}`. Dado que `{` no puede ser escapado, esta sintaxis solo será reconocida cuando el `$` siga inmediatamente al `{`. Utilice `{\$` para obtener un `{$`. Aquí hay algunos ejemplos para aclarar:

Ejemplo #19 Sintaxis con llaves

    <?php
    const DATA_KEY = 'const-key';
    $great = 'fantástico';
    $arr = [
        '1',
        '2',
        '3',
        [41, 42, 43],
        'key' => 'Valor indexado',
        'const-key' => 'Clave con un signo menos',
        'foo' => ['foo1', 'foo2', 'foo3']
    ];

    // No funcionará, mostrará: Esto es { fantástico}
    echo "Esto es { $great}" . PHP_EOL;

    // Funciona, mostrará: Esto es fantástico
    echo "Esto es {$great}" . PHP_EOL;

    // Para mostrar llaves en la salida:
    echo "Esto es {{$great}}" . PHP_EOL;

    class Square {
        public $width;

        public function __construct(int $width) { $this->width = $width; }
    }

    $square = new Square(5);

    // Funciona
    echo "Este cuadrado mide {$square->width}00 centímetros de ancho." . PHP_EOL;

    // Funciona, las claves entre comillas solo funcionan con la sintaxis de llaves
    echo "Esto funciona: {$arr['key']}" . PHP_EOL;

    // Funciona
    echo "Esto funciona: {$arr[3][2]}" . PHP_EOL;

    echo "Esto funciona: {$arr[DATA_KEY]}" . PHP_EOL;

    // Al utilizar arrays multidimensionales, siempre use llaves alrededor de los arrays
    // cuando estén dentro de strings
    echo "Esto funciona: {$arr['foo'][2]}" . PHP_EOL;

    echo "Esto funciona: {$obj->values[3]->name}" . PHP_EOL;

    echo "Esto funciona: {$obj->$staticProp}" . PHP_EOL;

    // No funcionará, mostrará: C:\directory\{fantástico}.txt
    echo "C:\directory\{$great}.txt" . PHP_EOL;

    // Funciona, mostrará: C:\directory\fantástico.txt
    echo "C:\\directory\\{$great}.txt" . PHP_EOL;
    ?>

> Nota: Como esta sintaxis permite expresiones arbitrarias, es posible utilizar variables de variables en la sintaxis avanzada.

#### Acceso y modificación de string por carácter

Los caracteres en los strings pueden ser accedidos y modificados especificando el offset basado en cero del carácter deseado después del string utilizando corchetes array, como en $str[42]. Piense en un string como un array de caracteres para este propósito. Las funciones substr() y substr_replace() pueden ser utilizadas cuando se desea extraer o reemplazar más de un carácter.

> Nota: Desde PHP 7.1.0, los offsets de string negativos también son soportados. Estos especifican el offset desde el final del string. Anteriormente, los offsets negativos emitían `E_NOTICE` para la lectura (produciendo un string vacío) y `E_WARNING` para la escritura (dejando el string intacto).

> Nota: Antes de PHP 8.0.0, los strings también podían ser accedidos utilizando llaves, como en $str{42}, para el mismo propósito. Esta sintaxis de llaves fue deprecada desde PHP 7.4.0 y ya no es soportada desde PHP 8.0.0.

Advertencia

Escribir en un offset fuera de alcance llena el string con espacios. Los tipos no enteros son convertidos a entero. Un tipo de offset ilegal emite `E_WARNING`. Solo el primer carácter de un string asignado es utilizado. Desde PHP 7.1.0, asignar un string vacío genera un error fatal. Anteriormente, esto asignaba un octeto NULL.

Advertencia

Internamente, los strings PHP son arrays de octetos. En consecuencia, acceder o modificar un string utilizando corchetes de array no es seguro para multi-octetos, y solo debe hacerse con strings en codificación de un solo octeto como ISO-8859-1.

> Nota: Desde PHP 7.1.0, aplicar el operador de índice vacío a un string vacío genera un error fatal. Anteriormente, el string vacío era silenciosamente convertido a array.

Ejemplo #20 Algunos ejemplos de strings

    <?php
    // Obtener el primer carácter de un string
    $str = 'Esto es una prueba.';
    $first = $str[0];
    var_dump($first);

    // Obtener el tercer carácter de un string
    $third = $str[2];
    var_dump($third);

    // Obtener el último carácter de un string.
    $str = 'Esto sigue siendo una prueba.';
    $last = $str[strlen($str)-1];
    var_dump($last);

    // Modificar el último carácter de un string
    $str = 'Mire el mar';
    $str[strlen($str)-1] = 'e';
    var_dump($str);
    ?>

Los offsets de string deben ser enteros o strings que parezcan enteros, de lo contrario se emitirá una advertencia.

Ejemplo #21 Ejemplo de offsets de string ilegales

    <?php
    $str = 'abc';

    foreach ($keys as $keyToTry) {
        var_dump(isset($str[$keyToTry]));

        try {
            var_dump($str[$keyToTry]);
        } catch (TypeError $e) {
            echo $e->getMessage(), PHP_EOL;
        }

        echo PHP_EOL;
    }
    ?>

El ejemplo anterior mostrará:

    bool(true)
    string(1) "b"

    bool(false)
    Cannot access offset of type string on string

    bool(false)
    Cannot access offset of type string on string

    bool(false)

    Warning: Illegal string offset "1x" in Standard input code on line 10
    string(1) "b"

> Nota:

> Acceder a variables de otros tipos (excepto arrays u objetos que implementen las interfaces apropiadas) utilizando `[]` o `{}` devuelve silenciosamente `null`.

> Nota:

> Los caracteres en literales de string pueden ser accedidos utilizando `[]` o `{}`.

> Nota:

> Acceder a caracteres en literales de string utilizando la sintaxis `{}` fue deprecada en PHP 7.4. Esto fue eliminado en PHP 8.0.

### Funciones y operadores útiles

Los strings pueden ser concatenados utilizando el operador '.' (punto). Tenga en cuenta que el operador '+' (suma) no funcionará para esto. Consulte los operadores de string para más información.

Existen varias funciones útiles para la manipulación de strings.

Consulte la sección de funciones de string para funciones generales, y la sección de funciones de expresiones regulares compatibles con Perl para funcionalidades avanzadas de búsqueda y reemplazo.

También existen funciones para strings de URL, y funciones para cifrar/descifrar strings (Sodium y Hash).

Finalmente, consulte también las funciones de tipo de carácter.

### Conversión a string

Un valor puede ser convertido a string utilizando el cast `(string)` o la función strval(). La conversión a string es realizada automáticamente en el contexto de una expresión donde un string es necesario. Esto ocurre al utilizar las funciones echo o print, o cuando una variable es comparada con un string. Las secciones sobre Tipos y Type Juggling aclararán lo siguiente. Ver también la función settype().

Un valor bool `true` es convertido al string `"1"`. El bool `false` es convertido a `""` (el string vacío). Esto permite una conversión de ida y vuelta entre los valores bool y string.

Un int o float es convertido a un string representando el número textualmente (incluyendo la parte exponencial para los float). Los números de punto flotante pueden ser convertidos utilizando la notación exponencial (`4.1E+6`).

> Nota:

> A partir de PHP 8.0.0, el carácter de la coma decimal es siempre un punto ("`.`"). Antes de PHP 8.0.0, el carácter de la coma decimal está definido en la localización del script (categoría LC_NUMERIC). Consulte la función setlocale().

Los arrays siempre son convertidos al string `"Array"`; por lo tanto, echo y print no pueden por sí solos mostrar el contenido de un array. Para mostrar un solo elemento, utilice una construcción como `echo $arr['foo']`. Consulte a continuación consejos para visualizar todo el contenido.

Para convertir objetos a strings, el método mágico __toString debe ser utilizado.

Los recursos siempre son convertidos a strings con la estructura `"Resource id #1"`, donde `1` es el número de recurso asignado al recurso por PHP en tiempo de ejecución. Aunque la estructura exacta de este string no debe ser considerada como confiable y está sujeta a cambios, siempre será única para un recurso dado durante la duración de ejecución de un script (es decir, una solicitud web o un proceso CLI) y no será reutilizada. Para obtener el tipo de un recurso, utilice la función get_resource_type().

`null` siempre es convertido a un string vacío.

Como se indicó anteriormente, convertir directamente un array, un objeto o un recurso a string no proporciona información útil sobre el valor más allá de su tipo. Consulte las funciones print_r() y var_dump() para medios más eficaces de inspeccionar el contenido de estos tipos.

La mayoría de los valores PHP también pueden ser convertidos a strings para un almacenamiento permanente. Este método se denomina serialización y es realizado por la función serialize().

### Detalles del tipo string

El string en PHP está implementado como un array de octetos y un entero indicando la longitud del búfer. No tiene ninguna información sobre cómo estos octetos se traducen en caracteres, dejando esta tarea al programador. No hay limitaciones sobre los valores de los que el string puede estar compuesto; en particular, los octetos de valor `0` («octetos NUL») son permitidos en cualquier parte del string (aunque algunas funciones, dichas en este manual de no ser «seguras para binarios», pueden pasar los strings a bibliotecas que ignoran los datos después de un octeto NUL.)

Esta naturaleza del tipo string explica por qué no hay un tipo «octeto» distinto en PHP - los strings toman este rol. Las funciones que no devuelven datos textuales - por ejemplo, datos arbitrarios leídos desde un socket de red - devolverán strings de todos modos.

Dado que PHP no dicta una codificación específica para los strings, uno podría preguntarse cómo los literales de string están codificados. Por ejemplo, el string `"á"` ¿es equivalente a `"\xE1"` (ISO-8859-1), `"\xC3\xA1"` (UTF-8, forma C), `"\x61\xCC\x81"` (UTF-8, forma D) o cualquier otra representación posible? La respuesta es que el string será codificado de la manera en que está codificado en el archivo de script. Por lo tanto, si el script está escrito en ISO-8859-1, el string será codificado en ISO-8859-1 y viceversa. Sin embargo, esto no se aplica si Zend Multibyte está activado; en este caso, el script puede estar escrito en una codificación arbitraria (que es explícitamente declarada o detectada) y luego convertido a una cierta codificación interna, que luego será la codificación utilizada para los literales de string. Tenga en cuenta que hay ciertas restricciones sobre la codificación del script (o sobre la codificación interna, si Zend Multibyte está activado) - esto significa casi siempre que esta codificación debe ser un superconjunto compatible con ASCII, como UTF-8 o ISO-8859-1. Tenga en cuenta, sin embargo, que las codificaciones dependientes del estado donde las mismas valores de octeto pueden ser utilizados en estados de desplazamiento iniciales y no iniciales pueden causar problemas.

Por supuesto, para ser útiles, las funciones que operan sobre texto pueden necesitar hacer ciertas suposiciones sobre cómo el string está codificado. Desafortunadamente, hay muchas variaciones en este sentido en las funciones de PHP:

- Algunas funciones asumen que el string está codificado en un (todo) conjunto de codificación de un octeto, pero no necesitan interpretar estos octetos como caracteres específicos. Este es el caso, por ejemplo, de substr(), strpos(), strlen() o strcmp(). Otra forma de pensar en estas funciones es que operan sobre búferes de memoria, es decir, que trabajan con octetos y desplazamientos de octetos.
- Otras funciones reciben la codificación del string, asumiendo posiblemente un valor predeterminado si no se proporciona información de este tipo. Este es el caso de htmlentities() y la mayoría de las funciones en la extensión mbstring.
- Otras utilizan la localización actual (ver setlocale()), pero funcionan octeto por octeto.
- Finalmente, pueden simplemente asumir que el string utiliza una codificación específica, generalmente UTF-8. Este es el caso de la mayoría de las funciones en la extensión intl y en la extensión PCRE (en este último caso, solo cuando se utiliza el modificador `u`).

En última instancia, esto significa que escribir programas correctos que utilicen Unicode depende de evitar cuidadosamente las funciones que no funcionarán y que probablemente corromperán los datos, y de utilizar en su lugar las funciones que se comportan correctamente, generalmente provenientes de las extensiones intl y mbstring. Sin embargo, utilizar funciones capaces de manejar codificaciones Unicode es solo el comienzo. Independientemente de las funciones que el lenguaje proporciona, es esencial conocer la especificación Unicode. Por ejemplo, un programa que asume que solo hay mayúsculas y minúsculas hace una suposición errónea.

## Strings numéricos

Un string PHP se considera numérico si puede ser interpretado como un int o un float.

Formalmente a partir de PHP 8.0.0:

    WHITESPACES      \s*
    LNUM             [0-9]+
    DNUM             ([0-9]*[\.]{LNUM}) | ({LNUM}[\.][0-9]*)
    EXPONENT_DNUM    (({LNUM} | {DNUM}) [eE][+-]? {LNUM})
    INT_NUM_STRING   {WHITESPACES} [+-]? {LNUM} {WHITESPACES}
    FLOAT_NUM_STRING {WHITESPACES} [+-]? ({DNUM} | {EXPONENT_DNUM}) {WHITESPACES}
    NUM_STRING       ({INT_NUM_STRING} | {FLOAT_NUM_STRING})

PHP también dispone de un concepto de strings iniciando numéricamente. Se trata simplemente de un string que comienza como un string numérico seguido de cualquier carácter.

> Nota:

> Cualquier string que contenga la letra `E` (insensible a mayúsculas y minúsculas) delimitada por números será considerada como un número expresado en notación científica. Esto puede producir resultados inesperados.

> Ejemplo #1 Scientific Notation Comparisons

>     <?php
>     var_dump("0D1" == "000"); // false, "0D1" no es notación científica
>     var_dump("0E1" == "000"); // true, "0E1" es 0 * (10 ^ 1), o 0
>     var_dump("2E1" == "020"); // true, "2E1" es 2 * (10 ^ 1), o 20
>     ?>

### Strings utilizados en contextos numéricos

Cuando una string debe ser evaluada como un número (por ejemplo, operaciones aritméticas, declaración de tipo int, etc.), se siguen los siguientes pasos para determinar el resultado:

1. Si el string es numérico, se resuelve en int si el string es un string numérico entero y entra dentro de los límites del tipo int (tales como definidas por `PHP_INT_MAX`), de lo contrario se resuelve en un float.
2. Si el contexto permite los strings iniciando numéricamente y el string es uno de ellos, se resuelve en int si la parte inicial del string es un string numérico entero y entra dentro de los límites del tipo int (tales como definidas por `PHP_INT_MAX`), de lo contrario se resuelve en un float. Además, se genera un error de nivel `E_WARNING`.
3. Si la string no es numérica, se lanza una TypeError.

### Comportamiento anterior a PHP 8.0.0

Antes de PHP 8.0.0, un string se consideraba numérico solo si tenía espacios en blanco al inicio del string, si tenía espacios en blanco al final del string, el string se consideraba como un string iniciando numéricamente.

Antes de PHP 8.0.0, cuando un string se utilizaba en un contexto numérico, seguía los mismos pasos que los anteriores, con las siguientes diferencias:

- El uso de un string iniciando numéricamente generaba un error de tipo `E_NOTICE` en lugar de `E_WARNING`.
- Si el string no era numérico, se generaba un `E_WARNING` y se devolvía el valor `0`.

Anterior a PHP 7.1.0, ni `E_NOTICE` ni `E_WARNING` se generaban.

    <?php
    $foo = 1 + "10.5";                // $foo es float (11.5)
    $foo = 1 + "-1.3e3";              // $foo es float (-1299)
    $foo = 1 + "bob-1.3e3";           // TypeError a partir de PHP 8.0.0, $foo era integer (1) anteriormente
    $foo = 1 + "bob3";                // TypeError a partir de PHP 8.0.0, $foo era integer (1) anteriormente
    $foo = 1 + "10 Small Pigs";       // $foo es integer (11) y se genera un E_WARNING en PHP 8.0.0, E_NOTICE anteriormente
    $foo = 4 + "10.2 Little Piggies"; // $foo es float (14.2) y se genera un E_WARNING en PHP 8.0.0, E_NOTICE anteriormente
    $foo = "10.0 pigs " + 1;          // $foo es float (11) y se genera un E_WARNING en PHP 8.0.0, E_NOTICE anteriormente
    $foo = "10.0 pigs " + 1.0;        // $foo es float (11) y se genera un E_WARNING en PHP 8.0.0, E_NOTICE anteriormente
    ?>

## Arrays

Para obtener una lista de todas las funciones de arrays, vea el capítulo funciones de arrays en la documentación.

Un array en PHP es en realidad un mapa ordenado. Un mapa es un tipo que asocia valores a claves. Este tipo está optimizado para varios usos diferentes; puede ser tratado como un array, lista (vector), tabla hash (una implementación de un mapa), diccionario, colección, pila, cola, y probablemente más. Como los valores array pueden ser otros arrays, también son posibles árboles y arrays multidimensionales.

La explicación de esas estructuras de datos está fuera del alcance de este manual, pero al menos se proporciona un ejemplo para cada una de ellas. Para más información, consulte la considerable literatura que existe sobre este amplio tema.

### Sintaxis

#### Especificación con array()

Un array puede ser creado usando la construcción del lenguaje array(). Acepta cualquier número de pares `clave => valor` separados por comas como argumentos.

    array(
        clave  => valor,
        clave2 => valor2,
        clave3 => valor3,
        ...
    )

La coma después del último elemento del array es opcional y puede ser omitida. Esto se suele hacer para arrays de una sola línea, es decir, `array(1, 2)` es preferido sobre `array(1, 2, )`. Para arrays de múltiples líneas, por otro lado, la coma final es comúnmente usada, ya que permite una adición más fácil de nuevos elementos al final.

> Nota:

> Existe una sintaxis corta para arrays que reemplaza `array()` con `[]`.

Ejemplo #1 Un array simple

    <?php
    $array1 = array(
        "foo" => "bar",
        "bar" => "foo",
    );

    // Usando la sintaxis corta de array
    $array2 = [
        "foo" => "bar",
        "bar" => "foo",
    ];

    var_dump($array1, $array2);
    ?>

La clave puede ser un int o un string. El valor puede ser de cualquier tipo.

Además, se producirán las siguientes conversiones de clave:

- Strings que contienen ints decimales válidos, a menos que el número esté precedido por un signo `+`, serán convertidos al tipo int. Por ejemplo, la clave `"8"` se almacenará realmente bajo `8`. Por otro lado, `"08"` no será convertido, ya que no es un entero decimal válido.
- Los floats también se convierten a ints, lo que significa que la parte fraccionaria será truncada. Por ejemplo, la clave `8.7` se almacenará realmente bajo `8`.
- Los bools se convierten a ints también, es decir, la clave `true` se almacenará realmente bajo `1` y la clave `false` bajo `0`.
- Null se convertirá en una cadena vacía, es decir, la clave `null` se almacenará realmente bajo `""`.
- Los arrays y objects no pueden ser usados como claves. Hacerlo resultará en una advertencia: `Illegal offset type`.

Si múltiples elementos en la declaración del array usan la misma clave, solo el último será usado, ya que todos los demás son sobrescritos.

Ejemplo #2 Ejemplo de conversión de tipos y sobrescritura

    <?php
    $array = array(
        1    => "a",
        "1"  => "b",
        1.5  => "c",
        true => "d",
    );
    var_dump($array);
    ?>

El ejemplo anterior mostrará:

    array(1) {
      [1]=>
      string(1) "d"
    }

Como todas las claves en el ejemplo anterior se convierten a `1`, el valor será sobrescrito en cada nuevo elemento y el último valor asignado `"d"` es el único que queda.

Los arrays de PHP pueden contener claves int y string al mismo tiempo ya que PHP no distingue entre arrays indexados y asociativos.

Ejemplo #3 Claves int y string mezcladas

    <?php
    $array = array(
        "foo" => "bar",
        "bar" => "foo",
        100   => -100,
        -100  => 100,
    );
    var_dump($array);
    ?>

El ejemplo anterior mostrará:

    array(4) {
      ["foo"]=>
      string(3) "bar"
      ["bar"]=>
      string(3) "foo"
      [100]=>
      int(-100)
      [-100]=>
      int(100)
    }

La clave es opcional. Si no se especifica, PHP usará el incremento de la clave int más grande usada previamente.

Ejemplo #4 Arrays indexados sin clave

    <?php
    $array = array("foo", "bar", "hello", "world");
    var_dump($array);
    ?>

El ejemplo anterior mostrará:

    array(4) {
      [0]=>
      string(3) "foo"
      [1]=>
      string(3) "bar"
      [2]=>
      string(5) "hello"
      [3]=>
      string(5) "world"
    }

Es posible especificar la clave solo para algunos elementos y omitirla para otros:

Ejemplo #5 Claves no en todos los elementos

    <?php
    $array = array(
             "a",
             "b",
        6 => "c",
             "d",
    );
    var_dump($array);
    ?>

El ejemplo anterior mostrará:

    array(4) {
      [0]=>
      string(1) "a"
      [1]=>
      string(1) "b"
      [6]=>
      string(1) "c"
      [7]=>
      string(1) "d"
    }

Como puede ver, el último valor `"d"` fue asignado a la clave `7`. Esto es porque la clave entera más grande antes de eso era `6`.

Ejemplo #6 Ejemplo complejo de conversión de tipos y sobrescritura

Este ejemplo incluye todas las variaciones de conversión de tipos de claves y sobrescritura de elementos.

    <?php
    $array = array(
        1    => 'a',
        '1'  => 'b', // el valor "a" será sobrescrito por "b"
        1.5  => 'c', // el valor "b" será sobrescrito por "c"
        -1 => 'd',
        '01'  => 'e', // como esto no es una cadena entera no sobrescribirá la clave para 1
        '1.5' => 'f', // como esto no es una cadena entera no sobrescribirá la clave para 1
        true => 'g', // el valor "c" será sobrescrito por "g"
        false => 'h',
        '' => 'i',
        null => 'j', // el valor "i" será sobrescrito por "j"
        'k', // el valor "k" se asigna a la clave 2. Esto es porque la clave entera más grande antes de eso era 1
        2 => 'l', // el valor "k" será sobrescrito por "l"
    );

    var_dump($array);
    ?>

El ejemplo anterior mostrará:

    array(7) {
      [1]=>
      string(1) "g"
      [-1]=>
      string(1) "d"
      ["01"]=>
      string(1) "e"
      ["1.5"]=>
      string(1) "f"
      [0]=>
      string(1) "h"
      [""]=>
      string(1) "j"
      [2]=>
      string(1) "l"
    }

Ejemplo #7 Ejemplo de índice negativo

Al asignar una clave entera negativa `n`, PHP se asegurará de asignar la siguiente clave a `n+1`.

    <?php
    $array = [];

    $array[-5] = 1;
    $array[] = 2;

    var_dump($array);
    ?>

El ejemplo anterior mostrará:

    array(2) {
      [-5]=>
      int(1)
      [-4]=>
      int(2)
    }

Advertencia

Antes de PHP 8.3.0, asignar una clave entera negativa `n` asignaría la siguiente clave a `0`, el ejemplo anterior produciría por lo tanto:

    array(2) {
      [-5]=>
      int(1)
      [0]=>
      int(2)
    }

#### Acceso a elementos de array con sintaxis de corchetes

Los elementos de array pueden ser accedidos usando la sintaxis `array[clave]`.

Ejemplo #8 Acceso a elementos de array

    <?php
    $array = array(
        "foo" => "bar",
        42    => 24,
        "multi" => array(
             "dimensional" => array(
                 "array" => "foo"
             )
        )
    );

    var_dump($array["foo"]);
    var_dump($array[42]);
    var_dump($array["multi"]["dimensional"]["array"]);
    ?>

El ejemplo anterior mostrará:

    string(3) "bar"
    int(24)
    string(3) "foo"

> Nota:

> Antes de PHP 8.0.0, los corchetes y las llaves podían usarse indistintamente para acceder a elementos de array (por ejemplo, `$array[42]` y `$array{42}` harían lo mismo en el ejemplo anterior). La sintaxis de llaves fue deprecada a partir de PHP 7.4.0 y ya no es soportada a partir de PHP 8.0.0.

Ejemplo #9 Desreferenciación de array

    <?php
    function getArray() {
        return array(1, 2, 3);
    }

    $secondElement = getArray()[1];

    var_dump($secondElement);
    ?>

> Nota:

> Intentar acceder a una clave de array que no ha sido definida es lo mismo que acceder a cualquier otra variable no definida: se emitirá un mensaje de error de nivel `E_WARNING` (nivel `E_NOTICE` antes de PHP 8.0.0) y el resultado será `null`.

> Nota:

> Desreferenciar un valor escalar que no es un string produce `null`. Antes de PHP 7.4.0, esto no emitía un mensaje de error. A partir de PHP 7.4.0, esto emite `E_NOTICE`; a partir de PHP 8.0.0, esto emite `E_WARNING`.

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

Un array existente puede ser modificado asignando valores explícitamente en él.

Esto se hace asignando valores al array, especificando la clave entre corchetes. La clave también puede ser omitida, resultando en un par de corchetes vacíos (`[]`).

    $arr[clave] = valor;
    $arr[] = valor;
    // clave puede ser un int o string
    // valor puede ser cualquier valor de cualquier tipo

Si $arr no existe aún o está establecido a `null` o `false`, será creado, por lo que esto es también una forma alternativa de crear un array. Sin embargo, esta práctica está desaconsejada porque si $arr ya contiene algún valor (por ejemplo, string de una variable de petición) entonces este valor permanecerá en su lugar y `[]` podría en realidad representar el operador de acceso a string. Siempre es mejor inicializar una variable mediante una asignación directa.

> Nota: A partir de PHP 7.1.0, aplicar el operador de índice vacío en un string lanza un error fatal. Anteriormente, el string se convertía silenciosamente a un array.

> Nota: A partir de PHP 8.1.0, crear un nuevo array a partir de un valor `false` está deprecado. Crear un nuevo array a partir de `null` y valores no definidos sigue estando permitido.

Para cambiar un cierto valor, asigne un nuevo valor a ese elemento usando su clave. Para eliminar un par clave/valor, llame a la función unset() sobre él.

Ejemplo #10 Uso de corchetes con arrays

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

    $arr[] = 56;    // Esto es lo mismo que $arr[13] = 56;
                    // en este punto del script

    $arr["x"] = 42; // Esto añade un nuevo elemento al
                    // array con clave "x"

    unset($arr[5]); // Esto elimina el elemento del array

    var_dump($arr);

    unset($arr);    // Esto elimina todo el array

    var_dump($arr);
    ?>

> Nota: Si no se especifica ninguna clave, la clave será el índice entero máximo existente + `1`. Si el array no tiene índices enteros positivos, la clave será `0`. A partir de PHP 8.3.0, también puede ser un entero negativo.

> Tenga en cuenta que el índice entero máximo usado para esto no necesita existir actualmente en el array. Solo necesita haber existido en el array en algún momento desde la última vez que el array fue reindexado. El siguiente ejemplo lo ilustra:

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

>     // Ahora eliminar cada elemento, pero dejar el array en sí intacto:
>     foreach ($array as $i => $value) {
>         unset($array[$i]);
>     }
>     print_r($array);

>     // Añadir un elemento (note que la nueva clave es 5, en lugar de 0).
>     $array[] = 6;
>     print_r($array);

>     // Reindexar:
>     $array = array_values($array);
>     $array[] = 7;
>     print_r($array);
>     ?>

> El ejemplo anterior mostrará:

>     Array
>     (
>         [0] => 1
>         [1] => 2
>         [2] => 3
>         [3] => 4
>         [4] => 5
>     )
>     Array
>     (
>     )
>     Array
>     (
>         [5] => 6
>     )
>     Array
>     (
>         [0] => 6
>         [1] => 7
>     )

#### Desestructuración de arrays

Los arrays pueden ser desestructurados usando la construcción de lenguaje `[]` (a partir de PHP 7.1.0) o list(). Estas construcciones pueden ser usadas para desestructurar un array en variables distintas.

Ejemplo #11 Desestructuración de array

    <?php
    $source_array = ['foo', 'bar', 'baz'];

    [$foo, $bar, $baz] = $source_array;

    echo $foo, PHP_EOL;    // imprime "foo"
    echo $bar, PHP_EOL;    // imprime "bar"
    echo $baz, PHP_EOL;    // imprime "baz"
    ?>

La desestructuración de arrays puede ser usada en `foreach` para desestructurar un array multidimensional mientras se itera sobre él.

Ejemplo #12 Desestructuración de array en foreach

    <?php
    $source_array = [
        [1, 'John'],
        [2, 'Jane'],
    ];

    foreach ($source_array as [$id, $name]) {
        echo "{$id}: '{$name}'\n";
    }
    ?>

Los elementos del array serán ignorados si la variable no está proporcionada. La desestructuración de array siempre comienza en el índice `0`.

Ejemplo #13 Ignorar elementos

    <?php
    $source_array = ['foo', 'bar', 'baz'];

    // Asignar el elemento en el índice 2 a la variable $baz
    [, , $baz] = $source_array;

    echo $baz;    // imprime "baz"
    ?>

A partir de PHP 7.1.0, los arrays asociativos también pueden ser desestructurados. Esto también permite una selección más fácil del elemento correcto en arrays indexados numéricamente, ya que el índice puede ser especificado explícitamente.

Ejemplo #14 Desestructuración de arrays asociativos

    <?php
    $source_array = ['foo' => 1, 'bar' => 2, 'baz' => 3];

    // Asignar el elemento en el índice 'baz' a la variable $three
    ['baz' => $three] = $source_array;

    echo $three, PHP_EOL;  // imprime 3

    $source_array = ['foo', 'bar', 'baz'];

    // Asignar el elemento en el índice 2 a la variable $baz
    [2 => $baz] = $source_array;

    echo $baz, PHP_EOL;    // imprime "baz"
    ?>

La desestructuración de arrays puede ser usada para intercambiar fácilmente dos variables.

Ejemplo #15 Intercambio de dos variables

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

    [$b, $a] = [$a, $b];

    echo $a, PHP_EOL;    // imprime 2
    echo $b, PHP_EOL;    // imprime 1
    ?>

> Nota:

> El operador de propagación (`...`) no está soportado en asignaciones.

> Nota:

> Intentar acceder a una clave de array que no ha sido definida es lo mismo que acceder a cualquier otra variable no definida: se emitirá un mensaje de error de nivel `E_WARNING` (nivel `E_NOTICE` antes de PHP 8.0.0) y el resultado será `null`.

> Nota:

> Desestructurar un valor escalar asigna `null` a todas las variables.

### Funciones útiles

Hay bastantes funciones útiles para trabajar con arrays. Vea la sección de funciones de array.

> Nota:

> La función unset() permite eliminar claves de un array. Tenga en cuenta que el array no será reindexado. Si se desea un comportamiento de "eliminar y desplazar", el array puede ser reindexado usando la función array_values().

> Ejemplo #16 Eliminación de elementos intermedios

>     <?php
>     $a = array(1 => 'one', 2 => 'two', 3 => 'three');

>     /* producirá un array que habría sido definido como
>        $a = array(1 => 'one', 3 => 'three');
>        y NO
>        $a = array(1 => 'one', 2 =>'three');
>     */
>     unset($a[2]);
>     var_dump($a);

>     $b = array_values($a);
>     // Ahora $b es array(0 => 'one', 1 =>'three')
>     var_dump($b);
>     ?>

La estructura de control `foreach` existe específicamente para arrays. Proporciona una forma fácil de recorrer un array.

### Lo que se debe y no se debe hacer con arrays

#### ¿Por qué `$foo[bar]` está mal?

Siempre use comillas alrededor de un índice de array literal de cadena. Por ejemplo, `$foo['bar']` es correcto, mientras que `$foo[bar]` no lo es. Pero ¿por qué? Es común encontrar este tipo de sintaxis en scripts antiguos:

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

Esto está mal, pero funciona. La razón es que este código tiene una constante no definida (`bar`) en lugar de un string (`'bar'` - note las comillas). Funciona porque PHP convierte automáticamente una cadena desnuda (una string sin comillas que no corresponde a ningún símbolo conocido) en un string que contiene la string desnuda. Por ejemplo, si no hay una constante definida llamada `bar`, entonces PHP sustituirá la string `'bar'` y la usará.

Advertencia

La retrocompatibilidad para tratar una constante no definida como cadena desnuda emite un error de nivel `E_NOTICE`. Esto ha sido deprecado a partir de PHP 7.2.0, y emite un error de nivel `E_WARNING`. A partir de PHP 8.0.0, ha sido eliminado y lanza una excepción Error.

Esto no significa que siempre deba poner comillas a la clave. No ponga comillas a claves que son constantes o variables, ya que esto evitará que PHP las interprete.

Ejemplo #17 Comillas en claves

    <?php
    error_reporting(E_ALL);
    ini_set('display_errors', true);
    ini_set('html_errors', false);

    // Array simple:
    $array = array(1, 2);
    $count = count($array);

    for ($i = 0; $i < $count; $i++) {
        echo "\nComprobando $i: \n";
        echo "Incorrecto: " . $array['$i'] . "\n";
        echo "Correcto: " . $array[$i] . "\n";
        echo "Incorrecto: {$array['$i']}\n";
        echo "Correcto: {$array[$i]}\n";
    }
    ?>

El ejemplo anterior mostrará:

    Comprobando 0:
    Notice: Undefined index:  $i in /path/to/script.html on line 9
    Incorrecto:
    Correcto: 1
    Notice: Undefined index:  $i in /path/to/script.html on line 11
    Incorrecto:
    Correcto: 1

    Comprobando 1:
    Notice: Undefined index:  $i in /path/to/script.html on line 9
    Incorrecto:
    Correcto: 2
    Notice: Undefined index:  $i in /path/to/script.html on line 11
    Incorrecto:
    Correcto: 2

Más ejemplos para demostrar este comportamiento:

Ejemplo #18 Más ejemplos

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

    $arr = array('fruit' => 'apple', 'veggie' => 'carrot');

    // Correcto
    echo $arr['fruit'], PHP_EOL;  // apple
    echo $arr['veggie'], PHP_EOL; // carrot

    // Incorrecto. Esto no funciona y lanza un error de PHP debido a
    // una constante no definida llamada fruit
    //
    // Error: Undefined constant "fruit"
    try {
        echo $arr[fruit];
    } catch (Error $e) {
        echo get_class($e), ': ', $e->getMessage(), PHP_EOL;
    }

    // Esto define una constante para demostrar lo que está pasando. El valor 'veggie'
    // es asignado a una constante llamada fruit.
    define('fruit', 'veggie');

    // Note la diferencia ahora
    echo $arr['fruit'], PHP_EOL;  // apple
    echo $arr[fruit], PHP_EOL;    // carrot

    // Lo siguiente está bien, ya que está dentro de una cadena. Las constantes no se buscan
    // dentro de cadenas, por lo que no ocurre ningún error aquí
    echo "Hello $arr[fruit]", PHP_EOL;      // Hello apple

    // Con una excepción: las llaves que rodean arrays dentro de cadenas permiten que las constantes
    // sean interpretadas
    echo "Hello {$arr[fruit]}", PHP_EOL;    // Hello carrot
    echo "Hello {$arr['fruit']}", PHP_EOL;  // Hello apple

    // La concatenación es otra opción
    echo "Hello " . $arr['fruit'], PHP_EOL; // Hello apple
    ?>

    <?php
    // Esto no funcionará, y resultará en un error de análisis, como:
    // Parse error: parse error, expecting T_STRING' or T_VARIABLE' or T_NUM_STRING'
    // Esto, por supuesto, también se aplica al usar superglobals en cadenas
    print "Hello $arr['fruit']";
    print "Hello $_GET['foo']";
    ?>

Como se indica en la sección de sintaxis, lo que está dentro de los corchetes ('`[`' y '`]`') debe ser una expresión. Esto significa que el código como este funciona:

    <?php
    echo $arr[somefunc($bar)];
    ?>

Este es un ejemplo de uso del valor de retorno de una función como índice del array. PHP también conoce las constantes:

    <?php
    $error_descriptions[E_ERROR]   = "Ha ocurrido un error fatal";
    $error_descriptions[E_WARNING] = "PHP emitió una advertencia";
    $error_descriptions[E_NOTICE]  = "Esto es solo un aviso informal";
    ?>

Tenga en cuenta que `E_ERROR` también es un identificador válido, al igual que `bar` en el primer ejemplo. Pero el último ejemplo es en realidad lo mismo que escribir:

    <?php
    $error_descriptions[1] = "Ha ocurrido un error fatal";
    $error_descriptions[2] = "PHP emitió una advertencia";
    $error_descriptions[8] = "Esto es solo un aviso informal";
    ?>

porque `E_ERROR` es igual a `1`, etc.

##### Entonces, ¿por qué está mal?

En algún momento en el futuro, el equipo de PHP podría querer añadir otra constante o palabra clave, o una constante en otro código podría interferir. Por ejemplo, ya está mal usar las palabras `empty` y `default` de esta manera, ya que son palabras clave reservadas.

> Nota: Para reiterar, dentro de una string entre comillas dobles, es válido no rodear los índices de array con comillas, por lo que `"$foo[bar]"` es válido. Consulte los ejemplos anteriores para más detalles, así como la sección sobre análisis de variables en cadenas.

### Conversión a array

Para cualquiera de los tipos int, float, string, bool y resource, convertir un valor a un array resulta en un array con un solo elemento con índice cero y el valor del escalar que fue convertido. En otras palabras, `(array) $scalarValue` es exactamente lo mismo que `array($scalarValue)`.

Si un object es convertido a un array, el resultado es un array cuyos elementos son las propiedades del object. Las claves son los nombres de las variables miembro, con algunas excepciones notables: las propiedades enteras son inaccesibles; las variables privadas tienen el nombre de la clase antepuesto al nombre de la variable; las variables protegidas tienen un '*' antepuesto al nombre de la variable. Estos valores antepuestos tienen bytes `NUL` a ambos lados. Las propiedades tipadas no inicializadas se descartan silenciosamente.

Ejemplo #19 Conversión a un array

    <?php

    class A {
        private $B;
        protected $C;
        public $D;
        function __construct()
        {
            $this->{1} = null;
        }
    }

    var_export((array) new A());
    ?>

El ejemplo anterior mostrará:

    array (
      '' . "\0" . 'A' . "\0" . 'B' => NULL,
      '' . "\0" . '*' . "\0" . 'C' => NULL,
      'D' => NULL,
      1 => NULL,
    )

Estos `NUL` pueden resultar en algún comportamiento inesperado:

Ejemplo #20 Conversión de un objeto a un array

    <?php

    class A {
        private $A; // Esto se convertirá en '\0A\0A'
    }

    class B extends A {
        private $A; // Esto se convertirá en '\0B\0A'
        public $AA; // Esto se convertirá en 'AA'
    }

    var_dump((array) new B());
    ?>

El ejemplo anterior mostrará:

    array(3) {
      ["BA"]=>
      NULL
      ["AA"]=>
      NULL
      ["AA"]=>
      NULL
    }

Lo anterior parecerá tener dos claves llamadas 'AA', aunque una de ellas en realidad se llama '\0A\0A'.

Convertir `null` a un array resulta en un array vacío.

### Comparación

Es posible comparar arrays con la función array_diff() y con operadores de array.

### Desempaquetado de arrays

Un array precedido por `...` será expandido en su lugar durante la definición del array. Solo arrays y objetos que implementan Traversable pueden ser expandidos. El desempaquetado de arrays con `...` está disponible a partir de PHP 7.4.0. Esto también se llama el operador de propagación.

Es posible expandir múltiples veces, y añadir elementos normales antes o después del operador `...`:

Ejemplo #21 Desempaquetado de array simple

    <?php
    // Usando sintaxis corta de array.
    // También funciona con la sintaxis array().
    $arr1 = [1, 2, 3];
    $arr2 = [...$arr1]; // [1, 2, 3]
    $arr3 = [0, ...$arr1]; // [0, 1, 2, 3]
    $arr4 = [...$arr1, ...$arr2, 111]; // [1, 2, 3, 1, 2, 3, 111]
    $arr5 = [...$arr1, ...$arr1]; // [1, 2, 3, 1, 2, 3]

    function getArr() {
      return ['a', 'b'];
    }
    $arr6 = [...getArr(), 'c' => 'd']; // ['a', 'b', 'c' => 'd']

    var_dump($arr1, $arr2, $arr3, $arr4, $arr5, $arr6);
    ?>

Desempaquetar un array con el operador `...` sigue la semántica de la función array_merge(). Es decir, las claves de cadena posteriores sobrescriben las anteriores y las claves enteras se renumeran:

Ejemplo #22 Desempaquetado de array con clave duplicada

    <?php
    // clave de cadena
    $arr1 = ["a" => 1];
    $arr2 = ["a" => 2];
    $arr3 = ["a" => 0, ...$arr1, ...$arr2];
    var_dump($arr3); // ["a" => 2]

    // clave entera
    $arr4 = [1, 2, 3];
    $arr5 = [4, 5, 6];
    $arr6 = [...$arr4, ...$arr5];
    var_dump($arr6); // [1, 2, 3, 4, 5, 6]
    // Que es [0 => 1, 1 => 2, 2 => 3, 3 => 4, 4 => 5, 5 => 6]
    // donde las claves enteras originales no se han conservado.
    ?>

> Nota:

> Las claves que no son ni enteros ni cadenas lanzan un TypeError. Tales claves solo pueden ser generadas por un objeto Traversable.

> Nota:

> Antes de PHP 8.1, el desempaquetado de un array que tiene una clave de cadena no está soportado:

>     <?php

>     $arr1 = [1, 2, 3];
>     $arr2 = ['a' => 4];
>     $arr3 = [...$arr1, ...$arr2];
>     // Fatal error: Uncaught Error: Cannot unpack array with string keys in example.php:5

>     $arr4 = [1, 2, 3];
>     $arr5 = [4, 5];
>     $arr6 = [...$arr4, ...$arr5]; // funciona. [1, 2, 3, 4, 5]
>     ?>

### Ejemplos

El tipo array en PHP es muy versátil. Aquí hay algunos ejemplos:

Ejemplo #23 Versatilidad de los arrays

    <?php
    // Esto:
    $a = array( 'color' => 'red',
                'taste' => 'sweet',
                'shape' => 'round',
                'name'  => 'apple',
                4        // la clave será 0
              );

    $b = array('a', 'b', 'c');

    var_dump($a, $b);

    // ...es completamente equivalente a esto:
    $a = array();
    $a['color'] = 'red';
    $a['taste'] = 'sweet';
    $a['shape'] = 'round';
    $a['name']  = 'apple';
    $a[]        = 4;        // la clave será 0

    $b = array();
    $b[] = 'a';
    $b[] = 'b';
    $b[] = 'c';

    // Después de que el código anterior se ejecute, $a será el array
    // array('color' => 'red', 'taste' => 'sweet', 'shape' => 'round',
    // 'name' => 'apple', 0 => 4), y $b será el array
    // array(0 => 'a', 1 => 'b', 2 => 'c'), o simplemente array('a', 'b', 'c').

    var_dump($a, $b);
    ?>

Ejemplo #24 Uso de array()

    <?php
    // Array como (propiedad-)mapa
    $map = array( 'version'    => 4,
                  'OS'         => 'Linux',
                  'lang'       => 'english',
                  'short_tags' => true
                );
    var_dump($map);

    // claves estrictamente numéricas
    // esto es lo mismo que array(0 => 7, 1 => 8, ...)
    $array = array( 7,
                    8,
                    0,
                    156,
                    -10
                  );
    var_dump($array);

    $switching = array(         10, // clave = 0
                        5    =>  6,
                        3    =>  7,
                        'a'  =>  4,
                                11, // clave = 6 (el máximo de los índices enteros era 5)
                        '8'  =>  2, // clave = 8 (¡entero!)
                        '02' => 77, // clave = '02'
                        0    => 12  // el valor 10 será sobrescrito por 12
                      );
    var_dump($switching);

    // array vacío
    $empty = array();
    var_dump($empty);
    ?>

Ejemplo #25 Colección

    <?php
    $colors = array('red', 'blue', 'green', 'yellow');

    foreach ($colors as $color) {
        echo "¿Te gusta $color?\n";
    }

    ?>

El ejemplo anterior mostrará:

    ¿Te gusta red?
    ¿Te gusta blue?
    ¿Te gusta green?
    ¿Te gusta yellow?

Cambiar los valores del array directamente es posible pasándolos por referencia.

Ejemplo #26 Cambiar elemento en el bucle

    <?php
    $colors = array('red', 'blue', 'green', 'yellow');

    foreach ($colors as &$color) {
        $color = mb_strtoupper($color);
    }
    unset($color); /* asegúrese de que las escrituras siguientes a
    $color no modificarán el último elemento del array */

    print_r($colors);
    ?>

El ejemplo anterior mostrará:

    Array
    (
        [0] => RED
        [1] => BLUE
        [2] => GREEN
        [3] => YELLOW
    )

Este ejemplo crea un array basado en uno.

Ejemplo #27 Índice basado en uno

    <?php
    $firstquarter = array(1 => 'January', 'February', 'March');
    print_r($firstquarter);
    ?>

El ejemplo anterior mostrará:

    Array
    (
        [1] => January
        [2] => February
        [3] => March
    )

Ejemplo #28 Llenar un array

    <?php
    // llenar un array con todos los elementos de un directorio
    $handle = opendir('.');
    while (false !== ($file = readdir($handle))) {
        $files[] = $file;
    }
    closedir($handle);

    var_dump($files);
    ?>

Los arrays están ordenados. El orden puede ser cambiado usando varias funciones de ordenación. Vea la sección de funciones de array para más información. La función count() puede ser usada para contar el número de elementos en un array.

Ejemplo #29 Ordenar un array

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

Debido a que el valor de un array puede ser cualquier cosa, también puede ser otro array. Esto permite la creación de arrays recursivos y multidimensionales.

Ejemplo #30 Arrays recursivos y multidimensionales

    <?php
    $fruits = array ( "fruits"  => array ( "a" => "orange",
                                           "b" => "banana",
                                           "c" => "apple"
                                         ),
                      "numbers" => array ( 1,
                                           2,
                                           3,
                                           4,
                                           5,
                                           6
                                         ),
                      "holes"   => array (      "first",
                                           5 => "second",
                                                "third"
                                         )
                    );
    var_dump($fruits);

    // Algunos ejemplos para direccionar valores en el array anterior
    echo $fruits["holes"][5];    // imprime "second"
    echo $fruits["fruits"]["a"]; // imprime "orange"
    unset($fruits["holes"][0]);  // elimina "first"

    // Crear un nuevo array multidimensional
    $juices["apple"]["green"] = "good";
    var_dump($juices);
    ?>

La asignación de array siempre implica una copia de valores. Use el operador de referencia para copiar un array por referencia.

Ejemplo #31 Copiado de arrays

    <?php
    $arr1 = array(2, 3);
    $arr2 = $arr1;
    $arr2[] = 4; // $arr2 es cambiado,
                 // $arr1 sigue siendo array(2, 3)

    $arr3 = &$arr1;
    $arr3[] = 4; // ahora $arr1 y $arr3 son iguales

    var_dump($arr1, $arr2, $arr3);
    ?>

## Los objetos

### Inicialización de los objetos

Para crear un nuevo object, utilice la palabra clave `new` para instanciar una clase:

Ejemplo #1 Construcción de objeto

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

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

Para una discusión completa, ver el capítulo sobre las clases y los objetos.

### Conversión en un objeto

Si un object es convertido en un object, no será modificado. Si un valor de cualquier otro tipo es convertido en un object, se creará una nueva instancia de la clase interna stdClass. Si el valor es `null`, la nueva instancia estará vacía. Un array se convierte en object con las propiedades nombradas en relación con las claves con sus valores correspondientes. Note que en este caso, antes de PHP 7.2.0 las claves numéricas fueron inaccesibles a menos que fueran iteradas.

Ejemplo #2 Conversión en un objeto

    <?php
    $obj = (object) array('1' => 'foo');
    var_dump(isset($obj->{'1'})); // muestra 'bool(true)'

    // Deprecado desde PHP 8.1
    var_dump(key($obj)); // muestra 'string(1) "1"'
    ?>

Para cualquier otro tipo, un miembro llamado `scalar` contendrá el valor.

Ejemplo #3 Conversión `(object)`

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

## Las enumeraciones

(PHP 8 >= 8.1.0)

### Las enumeraciones básicas

Las enumeraciones constituyen una capa restrictiva sobre las clases y las constantes de clase. Permiten definir un conjunto cerrado de valores posibles para un tipo.

    <?php
    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    function do_stuff(Suit $s)
    {
        // ...
    }

    do_stuff(Suit::Spades);
    ?>

Para una descripción completa, ver el capítulo sobre las enumeraciones.

### Conversión

Si una enum es convertida en object, no es modificada. Si una enum es convertida en array, un array con una sola clave `name` (para las Pure enums) o un array con las claves `name` y `value` (para las Backed enums) es creado. Todos los otros tipos de conversión resultarán en un error.

## Recursos

Un valor tipo resource 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 resource correspondientes.

Vea también la función get_resource_type().

### Conversión a recurso

Dado que las variables resource contienen gestores especiales a archivos abiertos, conexiones con bases de datos, áreas de pintura de imágenes y cosas por el estilo, la conversión a tipo resource carece de sentido.

### Liberación de recursos

Gracias al sistema de conteo de referencias introducido con el Motor Zend, un valor de tipo resource sin más referencias es detectado automáticamente, y es liberado por el recolector de basura. Por esta razón, rara vez se necesita liberar la memoria manualmente.

> Nota: Los enlaces persistentes con bases de datos son una excepción a esta regla. Ellos no son destruidos por el recolector de basura. Vea también la sección sobre conexiones persistentes para más información.

## Callables

Un callable es una referencia a una función o método que se pasa a otra función como argumento. Se representa con la declaración de tipo callable.

    <?php
    function foo(callable $callback) {
        $callback();
    }
    ?>

Algunas funciones aceptan funciones de retrollamada como parámetro, por ejemplo array_map(), usort(), o preg_replace_callback().

### Creación de callables

Un callable es un tipo que representa algo que se puede invocar. Los callables se pueden pasar como argumentos a funciones o métodos que esperan un parámetro de retrollamada o se pueden invocar directamente. El tipo callable no se puede usar como declaración de tipo para propiedades de clase. En su lugar, use una declaración de tipo Closure.

Los callables se pueden crear de varias maneras diferentes:

- Un objeto Closure
- Un string conteniendo el nombre de una función o método
- Un array conteniendo un nombre de clase o un object en el índice 0 y el nombre del método en el índice 1
- Un object implementando el método mágico __invoke()

Un objeto Closure puede ser creado usando la sintaxis de funciones anónimas, sintaxis de funciones de flecha, sintaxis callable de primera clase, o el método Closure::fromCallable().

> Nota: La sintaxis callable de primera clase solo está disponible a partir de PHP 8.1.0.

Ejemplo #1 Ejemplo de callback usando una Closure

    <?php
    // Usando sintaxis de función anónima
    $double1 = function ($a) {
        return $a * 2;
    };

    // Usando sintaxis de callable de primera clase
    function double_function($a) {
        return $a * 2;
    }
    $double2 = double_function(...);

    // Usando sintaxis de función de flecha
    $double3 = fn($a) => $a * 2;

    // Usando Closure::fromCallable
    $double4 = Closure::fromCallable('double_function');

    // Utilizar clousure como función de devolución de retrollamada
    // para duplicar el tamaño de cada elemento en nuestro rango
    $new_numbers = array_map($double1, range(1, 5));
    print implode(' ', $new_numbers) . PHP_EOL;

    $new_numbers = array_map($double2, range(1, 5));
    print implode(' ', $new_numbers) . PHP_EOL;

    $new_numbers = array_map($double3, range(1, 5));
    print implode(' ', $new_numbers) . PHP_EOL;

    $new_numbers = array_map($double4, range(1, 5));
    print implode(' ', $new_numbers);

    ?>

Resultado del ejemplo anterior en PHP 8.1:

    2 4 6 8 10
    2 4 6 8 10
    2 4 6 8 10
    2 4 6 8 10

Un callable también puede ser un string que contenga el nombre de una función o método estático. Cualquier función interna o definida por el usuario puede ser usada, excepto las construcciones del lenguaje como: array(), echo, empty(), eval(), isset(), list(), print, o unset().

Un método de clase estático puede ser usado sin instanciar un object de esa clase, ya sea creando un array con el nombre de la clase en el índice 0 y el nombre del método en el índice 1, o usando la sintaxis especial con el operador de resolución de ámbito `::`, como en `'ClassName::methodName'`.

Un método de un object instanciado puede ser un callable cuando se pasa como un array con el object en el índice 0 y el nombre del método en el índice 1.

La principal diferencia entre un objeto Closure y el tipo callable es que un objeto Closure es independiente del ámbito y siempre se puede invocar, mientras que un tipo callable puede depender del ámbito y puede que no se pueda invocar directamente. Closure es la forma preferida de crear callables.

> Nota: Mientras que los objetos Closure están vinculados al ámbito donde se crean, los callables que hacen referencia a métodos de clase como strings o arrays se resuelven en el ámbito donde se llaman. Para crear un callable a partir de un método privado o protegido, que luego se pueda invocar desde fuera del ámbito de la clase, use Closure::fromCallable() o la sintaxis callable de primera clase.

PHP permite la creación de callables que pueden ser usados como argumento de retrollamada pero que no pueden ser llamados directamente. Estos son callables dependientes del contexto que hacen referencia a un método de clase en la jerarquía de herencia de una clase, por ejemplo `'parent::method'` o `["static", "method"]`.

> Nota: A partir de PHP 8.2.0, los callables dependientes del contexto están obsoletos. Elimine la dependencia del contexto reemplazando `'parent::method'` con `parent::class . '::method'` o use la sintaxis callable de primera clase.

Ejemplo #2 Invocando varios tipos de callables con call_user_func()

    <?php

    // Un ejemplo de función de retrollamada
    function my_callback_function() {
        echo '¡hola mundo!', PHP_EOL;
    }

    // Un ejemplo de método de retrollamada
    class MyClass {
        static function myCallbackMethod() {
            echo '¡Hola Mundo!', PHP_EOL;
        }
    }

    // Tipo 1: Función de retrollamada simple
    call_user_func('my_callback_function');

    // Tipo 2: Llamada a un método estático de clase
    call_user_func(['MyClass', 'myCallbackMethod']);

    // Tipo 3: Llamada a un método de objeto
    $obj = new MyClass();
    call_user_func([$obj, 'myCallbackMethod']);

    // Tipo 4: Llamada a un método estático de clase
    call_user_func('MyClass::myCallbackMethod');

    // Type 5: Llamada a un método estático de clase usando la palabla clave ::class
    call_user_func([MyClass::class, 'myCallbackMethod']);

    // Tipo 6: Llamada a un método estático de clase relativo
    class A {
        public static function who() {
            echo 'A', PHP_EOL;
        }
    }

    class B extends A {
        public static function who() {
            echo 'B', PHP_EOL;
        }
    }

    call_user_func(['B', 'parent::who']); // obsoleto a partir de PHP 8.2.0

    // Tipo 7: Los objetos que implementan __invoke pueden ser utilizados como callables
    class C {
        public function __invoke($name) {
            echo 'Hola ', $name;
        }
    }

    $c = new C();
    call_user_func($c, 'PHP!');
    ?>

El ejemplo anterior mostrará:

    ¡hola mundo!
    ¡Hola Mundo!
    ¡Hola Mundo!
    ¡Hola Mundo!
    ¡Hola Mundo!

    Deprecated: Callables of the form ["B", "parent::who"] are deprecated in script on line 41
    A
    Hola PHP!

> Nota: Las devoluciónes de llamada registradas con funciones como call_user_func() y call_user_func_array() no serán llamadas si una excepción no es interceptada cuando ha sido lanzada en una función de devolución de llamada anterior.

## Mixed

El tipo mixed acepta todos los valores. Es equivalente al tipo union `object|resource|array|string|float|int|bool|null`. Disponible a partir de PHP 8.0.0.

mixed es, en el lenguaje de la teoría de tipos, el tipo superior. Esto significa que todos los demás tipos son subtipos de este tipo.

## Void

void es un tipo de declaración de retorno que indica que la función no devuelve ningún valor, pero la función aún puede terminar. Por lo tanto, no puede formar parte de una declaración de tipo unión. Disponible a partir de PHP 7.1.0.

> Nota: Incluso si una función tiene un tipo de retorno void, seguirá devolviendo un valor; este valor siempre es `null`.

### Descartar un valor con `(void)`

La sintaxis `(void)` puede usarse para descartar explícitamente el resultado de una expresión. Esto es útil para indicar que ignorar un valor de retorno es intencional, especialmente al llamar a una función o método marcado con el atributo NoDiscard.

A diferencia de otros moldes, `(void)` no convierte el valor a otro tipo ni produce un valor. Es una sentencia y no puede usarse como parte de una expresión.

Ejemplo #1 Descartar un valor de retorno

    <?php
    #[\NoDiscard]
    function process(): bool {
        return true;
    }

    (void) process(); // Descartar explícitamente el valor de retorno
    ?>

## Never

never es únicamente un tipo de retorno que indica que la función no se termina. Esto significa que llama a exit(), lanza una excepción, o es un bucle infinito. Por lo tanto, no puede formar parte de una declaración de type union Disponible a partir de PHP 8.1.0.

never es, en el lenguaje de la teoría de tipos, el tipo vacío. Esto significa que es el subtipo de todos los otros tipos y que puede reemplazar cualquier otro tipo de retorno durante la herencia.

## Tipos de clases relativas

Estas declaraciones de tipos solo pueden ser utilizadas dentro de las clases.

### self

El valor debe ser un `instanceof` de la misma clase en la que se utiliza la declaración de tipo.

### parent

El valor debe ser un `instanceof` de un padre de la clase en la que se utiliza la declaración de tipo.

### static

static es un tipo de retorno únicamente que exige que el valor devuelto sea un `instanceof` de la misma clase en la que se llama el método.

## Tipo singleton

Los tipos singleton son aquellos que solo aceptan un único valor. PHP soporta dos tipos singleton: false desde PHP 8.0.0 y true desde PHP 8.2.0.

Advertencia

Antes de PHP 8.2.0, el tipo false solo podía ser utilizado en el contexto de un tipo union.

> Nota: No es posible definir tipos singleton personalizados. Considere el uso de una enumeración en su lugar.

## Iterables

Un Iterable es un alias de tipo integrado durante la compilación para `array|Traversable`. Desde su introducción en PHP 7.1.0 y antes de PHP 8.2.0, iterable era un pseudo-tipo integrado que actuaba como el alias de tipo mencionado anteriormente y puede ser utilizado como una declaración de tipo. Un tipo iterable puede ser utilizado en un ciclo `foreach` y con yield from en un generador.

> Nota:

> Las funciones que declaran un tipo de retorno iterable también pueden ser generadores.

> Ejemplo #1 Ejemplo de tipo de retorno iterable de un generador

>     <?php

>     function gen(): iterable {
>         yield 1;
>         yield 2;
>         yield 3;
>     }

>     foreach(gen() as $value) {
>         echo $value, "\n";
>     }
>     ?>

## Declaraciones de tipo

Las declaraciones de tipos pueden ser añadidas a los argumentos de las funciones, valores de retorno, a partir de PHP 7.4.0, las propiedades de clase, y a partir de PHP 8.3.0, las constantes de clase. Aseguran que el valor es del tipo especificado en el momento de la llamada, de lo contrario se lanza un TypeError.

Cada tipo soportado por PHP, con la excepción del tipo resource, puede ser utilizado en una declaración de tipo por el usuario. Esta página contiene un registro de cambios de la disponibilidad de los diferentes tipos y la documentación sobre su uso en las declaraciones de tipo.

> Nota:

> Cuando una clase implementa un método de interfaz o reimplementa un método que ya ha sido definido por una clase padre, debe ser compatible con la definición mencionada. Un método es compatible si sigue las reglas de variance.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Añadido soporte para las constantes tipadas de clase, interfaz, trait y enum.
8.2.0 | Añadido soporte de tipo DNF (Forma Normal Disyuntiva).
8.2.0 | Añadido soporte del tipo true.
8.2.0 | Los tipos null y false pueden ahora ser utilizados de manera autónoma.
8.1.0 | Se ha añadido soporte para los tipos de intersección.
8.1.0 | El retorno por referencia desde una función void ahora está desaconsejado.
8.1.0 | Se ha añadido soporte para el tipo de retorno únicamente never.
8.0.0 | Añadido soporte de mixed
8.0.0 | Se ha añadido soporte para el tipo de retorno únicamente static.
8.0.0 | Se ha añadido soporte para los tipos de unión.
7.4.0 | Añadido soporte para el tipado de propiedades de clase.
7.2.0 | Añadido soporte para object.
7.1.0 | Añadido soporte para iterable.
7.1.0 | Añadido soporte para void.
7.1.0 | Se ha añadido soporte para los tipos nullable.

### Notas de uso de los tipos atómicos

Los tipos atómicos tienen un comportamiento directo con algunas advertencias menores que se describen en esta sección.

#### Tipos escalares

Advertencia

Los alias para los tipos escalares (bool, int, float, string) no son soportados. En su lugar, son tratados como nombres de clase o interfaz. Por ejemplo, utilizar `boolean` como una declaración de tipo requiere que el valor sea una `instanceof` de la clase o interfaz `boolean`, en lugar de tipo bool:

    <?php
        function test(boolean $param) {}
        test(true);
    ?>

Resultado del ejemplo anterior en PHP 8:

    Warning: "boolean" will be interpreted as a class name. Did you mean "bool"? Write "\boolean" to suppress this warning in /in/9YrUX on line 2

    Fatal error: Uncaught TypeError: test(): Argument #1 ($param) must be of type boolean, bool given, called in - on line 3 and defined in -:2
    Stack trace:
    #0 -(3): test(true)
    #1 {main}
      thrown in - on line 2

#### void

> Nota:

> El retorno por referencia desde una función void está obsoleto a partir de PHP 8.1.0, ya que tal función es contradictoria. Anteriormente, ya emitía los siguientes `E_NOTICE` cuando se llamaba: Only variable references should be returned by reference.

>     <?php
>     function &test(): void {}
>     ?>

#### Tipos Callable

Este tipo no puede ser utilizado como declaración de tipo de propiedad de clase.

> Nota: No es posible especificar la firma de la función.

#### Declaraciones de tipo sobre los parámetros de referencia

Si un parámetro pasado por referencia a una declaración de tipo, el tipo de la variable solo se verifica a la entrada de la función, al inicio de la llamada, pero no cuando la función es llamada nuevamente. Esto significa que una función puede modificar el tipo de la variable pasada por referencia.

Ejemplo #1 Parámetro tipado pasado por referencia

    <?php
    function array_baz(array &$param)
    {
        $param = 1;
    }
    $var = [];
    array_baz($var);
    var_dump($var);
    array_baz($var);
    ?>

Resultado del ejemplo anterior es similar a:

    int(1)

    Fatal error: Uncaught TypeError: array_baz(): Argument #1 ($param) must be of type array, int given, called in - on line 9 and defined in -:2
    Stack trace:
    #0 -(9): array_baz(1)
    #1 {main}
      thrown in - on line 2

### Notas de uso de los tipos compuestos

Las declaraciones de tipo compuesto están sujetas a algunas restricciones y realizarán un control de redundancia en el momento de la compilación para evitar errores simples.

Precaución

Anterior a PHP 8.2.0 y la introducción de los tipos DNF, no era posible combinar las intersecciones de tipo con las uniones de tipo.

#### Tipos de uniones

Advertencia

No es posible combinar los dos tipos de singleton false y true juntos en una unión de tipo. Utilice en su lugar bool.

Precaución

Anterior a PHP 8.2.0, como false y null no podían ser utilizados como tipos autónomos, una unión de tipo compuesta únicamente de estos tipos no estaba permitida. Esto incluye los tipos siguientes: false, `false|null` y `?false`.

##### Azúcar sintáctico de tipo nullable

Una declaración de tipo de base única puede ser marcada como valor NULL anteponiendo el tipo de un signo de interrogación (`?`). Así `?T` y `T|null` son idénticos.

> Nota: Esta sintaxis es soportada a partir de PHP 7.1.0, y es anterior a la soporte generalizado de los tipos de unión.

> Nota:

> También es posible obtener argumentos nullable haciendo de `null` el valor por defecto. Esto no es recomendado, ya que si el valor por defecto es modificado en una clase hija, se desencadenará una violación de compatibilidad de tipo ya que el tipo null deberá ser añadido a la declaración de tipo. Este comportamiento también está obsoleto a partir de PHP 8.4.

> Ejemplo #2 Forma antigua de hacer los argumentos nullable

>     <?php
>     class C {}

>     function f(C $c = null) {
>         var_dump($c);
>     }

>     f(new C);
>     f(null);
>     ?>

> El ejemplo anterior mostrará:

>     object(C)#1 (0) {
>     }
>     NULL

#### Tipos duplicados y redundantes

Para detectar errores simples en las declaraciones de tipo compuesto, los tipos redundantes que pueden ser detectados sin realizar una carga de clase resultarán en un error de compilación. Esto incluye:

- Cada tipo resuelto por nombre solo puede ocurrir una vez. Los tipos como `int|string|INT` o `Countable&Traversable&COUNTABLE` generan un error.
- El uso de mixed o never resulta en un error.
- Para los tipos de uniones:
  - Si bool es utilizado, false o true no puede ser utilizado adicionalmente.
  - Si object es utilizado, los tipos de clase no pueden ser utilizados adicionalmente.
  - Si iterable es utilizado, array y Traversable no pueden ser utilizados adicionalmente.
- Para los tipos de intersecciones:
  - El uso de un tipo que no es un tipo de clase genera un error.
  - El uso de self, parent o static resulta en un error.
- Para los tipos DNF:
  - Si un tipo más genérico es utilizado, el más restrictivo es redundante.
  - Uso de dos tipos de intersección idénticos.

> Nota: Esto no garantiza que el tipo sea « mínimo », ya que esto requeriría cargar todos los tipos de clase utilizados.

Por ejemplo, si `A` y `B` son alias de clase, entonces `A|B` sigue siendo una unión de tipo legal, aunque sea posible reducir a `A` o `B`. Asimismo, si la clase `B extends A {}`, entonces `A|B` también es una unión de tipo legal, aunque podría ser reducida al tipo `A` únicamente.

    <?php
    function foo(): int|INT {} // No autorizado
    function foo(): bool|false {} // No autorizado
    function foo(): int&Traversable {} // No autorizado
    function foo(): self&Traversable {} // No autorizado

    use A as B;
    function foo(): A|B {} // No autorizado ("use" forma parte de la resolución de nombres)
    function foo(): A&B {} // No autorizado ("use" forma parte de la resolución de nombres)

    class_alias('X', 'Y');
    function foo(): X|Y {} // Autorizado (la redundancia solo se conoce en tiempo de ejecución)
    function foo(): X&Y {} // Autorizado (la redundancia solo se conoce en tiempo de ejecución)
    ?>

### Ejemplos

Ejemplo #3 Declaración de tipo de clase de base

    <?php
    class C {}
    class D extends C {}

    // Esta no extiende C.
    class E {}

    function f(C $c) {
        echo get_class($c)."\n";
    }

    f(new C);
    f(new D);
    f(new E);
    ?>

Resultado del ejemplo anterior en PHP 8:

    C
    D

    Fatal error: Uncaught TypeError: f(): Argument #1 ($c) must be of type C, E given, called in /in/gLonb on line 14 and defined in /in/gLonb:8
    Stack trace:
    #0 -(14): f(Object(E))
    #1 {main}
      thrown in - on line 8

Ejemplo #4 Declaración de tipo de interfaz de base

    <?php
    interface I { public function f(); }
    class C implements I { public function f() {} }

    // Esta no implementa I.
    class E {}

    function f(I $i) {
        echo get_class($i)."\n";
    }

    f(new C);
    f(new E);
    ?>

Resultado del ejemplo anterior en PHP 8:

    C

    Fatal error: Uncaught TypeError: f(): Argument #1 ($i) must be of type I, E given, called in - on line 13 and defined in -:8
    Stack trace:
    #0 -(13): f(Object(E))
    #1 {main}
      thrown in - on line 8

Ejemplo #5 Declaración de tipo de retorno de base

    <?php
    function sum($a, $b): float {
        return $a + $b;
    }

    // Note que un float será devuelto.
    var_dump(sum(1, 2));
    ?>

El ejemplo anterior mostrará:

    float(3)

Ejemplo #6 Retorno de un objeto

    <?php
    class C {}

    function getC(): C {
        return new C;
    }

    var_dump(getC());
    ?>

El ejemplo anterior mostrará:

    object(C)#1 (0) {
    }

Ejemplo #7 Declaración de tipo de argumento nullable

    <?php
    class C {}

    function f(?C $c) {
        var_dump($c);
    }

    f(new C);
    f(null);
    ?>

El ejemplo anterior mostrará:

    object(C)#1 (0) {
    }
    NULL

Ejemplo #8 Declaración de tipo de retorno nullable

    <?php
    function get_item(): ?string {
        if (isset($_GET['item'])) {
            return $_GET['item'];
        } else {
            return null;
        }
    }
    ?>

Ejemplo #9 Declaración de tipo para las propiedades de clase

    <?php
    class User {
        public static string $foo = 'foo';

        public int $id;
        public string $username;

        public function __construct(int $id, string $username) {
            $this->id = $id;
            $this->username = $username;
        }
    }
    ?>

### Tipado estricto

Por defecto, PHP convertirá los valores de un tipo incorrecto al tipo escalar esperado siempre que sea posible. Por ejemplo, una función, que espera como parámetro una string, a la que se pasa un int recibirá una variable de tipo string.

Es posible activar el modo de tipado estricto archivo por archivo. En el modo estricto, solo una variable que coincida exactamente con el tipo esperado en la declaración será aceptada, de lo contrario se lanzará un TypeError. La única excepción a esta regla es que un valor de tipo int puede pasar una declaración de tipo float.

Advertencia

Las llamadas a funciones desde funciones internas no serán afectadas por la declaración `strict_types`.

Para activar el modo estricto, se utiliza la expresión `declare` con la declaración `strict_types`:

> Nota:

> El tipado estricto se aplica a las llamadas de función realizadas desde dentro de un archivo cuyo tipado estricto está activo, y no a las funciones declaradas en ese archivo. Si un archivo cuyo tipado estricto no está activado realiza una llamada a una función que ha sido definida en un archivo cuyo tipo estricto está activo, la preferencia del llamante (modo coercitivo) será respetada y el valor será forzado.

> Nota:

> El tipado estricto solo está definido para las declaraciones de tipo escalar.

Ejemplo #10 Tipado estricto para los valores de argumentos

    <?php
    declare(strict_types=1);

    function sum(int $a, int $b) {
        return $a + $b;
    }

    var_dump(sum(1, 2));
    var_dump(sum(1.5, 2.5));
    ?>

Resultado del ejemplo anterior en PHP 8:

    int(3)

    Fatal error: Uncaught TypeError: sum(): Argument #1 ($a) must be of type int, float given, called in - on line 9 and defined in -:4
    Stack trace:
    #0 -(9): sum(1.5, 2.5)
    #1 {main}
      thrown in - on line 4

Ejemplo #11 Tipado coercitivo para los valores de argumentos

    <?php
    function sum(int $a, int $b) {
        return $a + $b;
    }

    var_dump(sum(1, 2));

    // Estos serán forzados a enteros: ¡note la salida a continuación!
    var_dump(sum(1.5, 2.5));
    ?>

El ejemplo anterior mostrará:

    int(3)
    int(3)

Ejemplo #12 Tipado estricto para los valores de retorno

    <?php
    declare(strict_types=1);

    function sum($a, $b): int {
        return $a + $b;
    }

    var_dump(sum(1, 2));
    var_dump(sum(1, 2.5));
    ?>

El ejemplo anterior mostrará:

    int(3)

    Fatal error: Uncaught TypeError: sum(): Return value must be of type int, float returned in -:5
    Stack trace:
    #0 -(9): sum(1, 2.5)
    #1 {main}
      thrown in - on line 5

## Manipulación de tipos

PHP no requiere una definición explícita de tipo en la declaración de variables. En este caso, el tipo de una variable se determina por el valor que almacena. Es decir, si se asigna un string a la variable $var, entonces $var será de tipo string. Si posteriormente se asigna un valor de tipo int a $var, pasará a ser de tipo int.

PHP puede intentar convertir automáticamente el tipo de un valor a otro en ciertos contextos. Los diferentes contextos que existen son:

- Numérico
- Cadena
- Lógico
- Entero y cadena
- Comparativo
- Función

> Nota: Cuando un valor necesita ser interpretado como un tipo diferente, el valor en sí no cambia de tipo.

Para forzar a que una variable sea evaluada como un tipo determinado, consulte la sección sobre moldeado de tipos. Para cambiar el tipo de una variable, consulte la función settype().

### Contextos numéricos

Este es el contexto cuando se utiliza un operador aritmético.

En este contexto, si alguno de los operandos es de tipo float (o no puede interpretarse como un int), ambos operandos se interpretarán como floats, y el resultado también será un float. De lo contrario, los operandos se interpretarán como ints, y el resultado también será un int. A partir de PHP 8.0.0, si uno de los operandos no puede interpretarse, se lanzará un TypeError.

### Contextos de cadena

Este es el contexto cuando se utiliza echo, print, interpolación de cadena, o el operador de concatenación de cadena.

En este contexto, el valor se interpretará como string. Si el valor no puede interpretarse, se lanzará un TypeError. Antes de PHP 7.4.0, se generaba un `E_RECOVERABLE_ERROR`.

### Contextos lógicos

Este es el contexto cuando se utilizan sentencias condicionales, el operador ternario, o un operador lógico.

En este contexto, el valor se interpretará como bool.

### Contextos entero y cadena

Este es el contexto cuando se utilizan operadores a nivel de bits.

En este contexto, si todos los operandos son de tipo string, el resultado también será un string. De lo contrario, los operandos se interpretarán como ints, y el resultado también será un int. A partir de PHP 8.0.0, si uno de los operandos no puede interpretarse, se lanzará un TypeError.

### Contextos comparativos

Este es el contexto cuando se utiliza un operador de comparación.

Las conversiones de tipo que ocurren en este contexto se explican en la tabla de Comparación con diversos tipos tabla.

### Contextos de función

Este es el contexto cuando un valor se pasa a un parámetro tipado, propiedad o se devuelve desde una función que declara un tipo de retorno.

En este contexto, el valor debe ser de ese tipo. Existen dos excepciones: la primera es: si el valor es de tipo int y el tipo declarado es float, entonces el entero se convierte en un número de punto flotante. La segunda es: si el tipo declarado es un tipo escalar , el valor es convertible a un tipo escalar y el modo de tipado coercitivo está activo (por omisión), el valor puede convertirse en un valor escalar aceptado. Consulte a continuación para obtener una descripción de este comportamiento.

Advertencia

Las funciones internas convierten automáticamente `null` a tipos escalares; este comportamiento está DEPRECADO a partir de PHP 8.1.0.

#### Tipado coercitivo con declaraciones de tipo simples

- Declaración de tipo bool: el valor se interpreta como bool.
- Declaración de tipo int: el valor se interpreta como int si la conversión está bien definida. Por ejemplo, la cadena es numérica.
- Declaración de tipo float: el valor se interpreta como float si la conversión está bien definida. Por ejemplo, la cadena es numérica.
- Declaración de tipo string: el valor se interpreta como string.

#### Tipado coercitivo con tipos de unión

Cuando `strict_types` no está habilitado, las declaraciones de tipo escalar están sujetas a conversiones implícitas limitadas. Si el tipo exacto del valor no es parte de la unión, entonces el tipo objetivo se elige en el siguiente orden de preferencia:

1. int
2. float
3. string
4. bool

Si el tipo existe en la unión y el valor puede ser coercionado al tipo bajo la semántica de verificación de tipos existente de PHP, entonces se elige el tipo. De lo contrario, se prueba con el siguiente tipo.
Precaución

Como excepción, si el valor es una cadena y tanto int como float son parte de la unión, el tipo preferido se determina por la semántica de cadena numérica existente. Por ejemplo, para `"42"` se elige int, mientras que para `"42.0"` se elige float.

> Nota:

> Los tipos que no forman parte de la lista de preferencias anterior no son objetivos elegibles para coerción implícita. En particular, no ocurren coerciones implícitas a los tipos null, false y true.

Ejemplo #1 Ejemplo de tipos siendo coercionados a un tipo parte de la unión

    <?php
    // int|string
    42    --> 42          // tipo exacto
    "42"  --> "42"        // tipo exacto
    new ObjectWithToString --> "Resultado de __toString()"
                          // objeto nunca compatible con int, retrocede a string
    42.0  --> 42          // float compatible con int
    42.1  --> 42          // float compatible con int
    1e100 --> "1.0E+100"  // float demasiado grande para int, retrocede a string
    INF   --> "INF"       // float demasiado grande para int, retrocede a string
    true  --> 1           // bool compatible con int
    []    --> TypeError   // array no compatible con int o string

    // int|float|bool
    "45"    --> 45        // cadena numérica int
    "45.0"  --> 45.0      // cadena numérica float

    "45X"   --> true      // no es cadena numérica, retrocede a bool
    ""      --> false     // no es cadena numérica, retrocede a bool
    "X"     --> true      // no es cadena numérica, retrocede a bool
    []      --> TypeError // array no compatible con int, float o bool
    ?>

### Moldeado de tipos

El moldeado de tipos convierte el valor a un tipo elegido escribiendo el tipo entre paréntesis antes del valor a convertir.

Ejemplo #2 Moldeado de tipos

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

    var_dump($bar);
    ?>

Los moldeados permitidos son:

- `(int)` - moldear a int
- `(bool)` - moldear a bool
- `(float)` - moldear a float
- `(string)` - moldear a string
- `(array)` - moldear a array
- `(object)` - moldear a object
- `(unset)` - moldear a NULL

El moldeado `(void)` también está disponible a partir de PHP 8.5.0, pero no es una conversión de valor. Se utiliza como una sentencia para descartar explícitamente el resultado de una expresión.

Advertencia

`(integer)` es un alias del moldeado `(int)`. `(boolean)` es un alias del moldeado `(bool)`. `(binary)` es un alias del moldeado `(string)`. `(double)` y `(real)` son alias del moldeado `(float)`. Estos moldeados no utilizan el nombre canónico del tipo y están deprecados a partir de PHP 8.5.0.

Advertencia

El alias de moldeado `(real)` fue deprecado a partir de PHP 7.4.0 y eliminado a partir de PHP 8.0.0.

Advertencia

El moldeado `(unset)` fue deprecado a partir de PHP 7.2.0. Tenga en cuenta que el moldeado `(unset)` es igual a asignar el valor NULL a la variable o llamada. El moldeado `(unset)` fue eliminado a partir de PHP 8.0.0.

Precaución

El moldeado `(binary)` y el prefijo `b` existen para soporte futuro. Actualmente `(binary)` y `(string)` son idénticos, sin embargo esto puede cambiar y no debe ser utilizado como dependencia.

> Nota:

> Los espacios en blanco se ignoran dentro de los paréntesis de un moldeado. Por lo tanto, los siguientes dos moldeados son equivalentes:

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

Moldeando literales strings y variables a strings binarios:

    <?php
    $binary = (binary) $string;
    $binary = b"cadena binaria";
    ?>

En lugar de moldear una variable a un string, también es posible encerrar la variable entre comillas dobles.

Ejemplo #3 Diferentes mecanismos de moldeado

    <?php
    $foo = 10;            // $foo es un entero
    $str = "$foo";        // $str es una cadena
    $fst = (string) $foo; // $fst también es una cadena

    // Esto imprime que "son iguales"
    if ($fst === $str) {
        echo "son iguales", PHP_EOL;
    }
    ?>

Puede que no sea obvio exactamente qué ocurrirá al moldear entre ciertos tipos. Para más información, consulte estas secciones:

- Conversión a booleano
- Conversión a entero
- Conversión a float
- Conversión a cadena
- Conversión a array
- Conversión a objeto
- Conversión a recurso
- Conversión a NULL
- Descartar un valor con `(void)`
- Las tablas de comparación de tipos

> Nota: Dado que PHP soporta indexación en strings mediante offsets utilizando la misma sintaxis que el indexado en array, el siguiente ejemplo se cumple para todas las versiones de PHP:

> Ejemplo #4 Usando offset de array con una cadena

>     <?php
>     $a    = 'car'; // $a es una cadena
>     $a[0] = 'b';   // $a sigue siendo una cadena
>     echo $a;       // bar
>     ?>

> Consulte la sección titulada Acceso a cadena por carácter para más información.

# Variables

## Tabla de contenidos

- Conceptos básicos
- Variables Predefinidas
- Ámbito de las variables
- Variables variables
- Variables desde fuentes externas

## Conceptos básicos

En PHP las variables se representan con 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.

Un nombre de variable válido tiene que empezar con una letra (`A-Z`, `a-z`, o los bytes del 128 al 255) o un carácter de subrayado (underscore), seguido de cualquier número de letras, números y caracteres de subrayado. Como expresión regular se podría expresar como: `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`

> Nota: PHP no soporta Unicode en el nombre de las variables, sin embargo, algunas codificaciones de caracteres (como UTF-8) codifican caracteres de tal manera que todos los bytes de un carácter multibyte están dentro del rango permitido, convirtiéndolo así en un nombre de variable válido.

> Nota: `$this` es una variable especial que no puede ser asignada. Antes de PHP 7.1.0, era posible la asignación indirecta (por ejemplo, mediante el uso de variables variables).

Sugerencia

Eche un vistazo a Guía de entorno de usuario para nombres.

Ejemplo #1 Valid variable names

    <?php
    $var = 'Roberto';
    $Var = 'Juan';
    echo "$var, $Var";      // Imprime "Roberto, Juan"

    $_4site = 'aún no';     // Válido; comienza con un carácter de subrayado
    $täyte = 'mansikka';    // Válido; 'ä' es ASCII (Extendido) 228

Ejemplo #2 Invalid variable names

    <?php
    $4site = 'aún no';     // Inválido; comienza con un número

PHP acepta una secuencia de bytes como nombre de variable. Los nombres de variables que no siguen las reglas de nombres mencionadas anteriormente solo pueden accederse de forma dinámica en tiempo de ejecución. Consulte variables variables para obtener información sobre cómo acceder a ellas.

Ejemplo #3 Cómo acceder a nombres de variables con caracteres no válidos

    <?php
    ${'invalid-name'} = 'bar';
    $name = 'invalid-name';
    echo ${'invalid-name'}, " ", $$name;

El ejemplo anterior mostrará:

    bar bar

Por omisión, las variables siempre se asignan por valor. Esto significa que cuando se asigna una expresión a una variable, el valor completo de la expresión original se copia en la variable de destino. Esto quiere decir que, por ejemplo, después de 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 el capítulo sobre Expresiones.

PHP también 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.

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

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

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

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

    <?php
    // Tenga en cuenta la falta de & que indica un retorno por referencia en la declaración de la función.
    // Es decir, la función no retorna una referencia, por lo que el resultado no puede asignarse por referencia.
    function test()
    {
       $original = 25;
       return $original;
    }

    // Nota: Se emite un aviso, pero el valor sin referencia es asignado
    $result1 = &test();        // Inválido porque test() no devuelve una variable por referencia.
    var_dump($result1);

    // Esta función está definida como retornando una referencia, pero no retorna una variable
    function &test2()
    {
        return 26;             // Inválido porque el valor retornado no es una referencia a una variable.
    }

    // Nota: El valor sin referencia es asignado
    $result2 = &test2();
    var_dump($result2);

No es necesario inicializar variables en PHP, sin embargo, es una muy buena práctica. El acceso a una variable no definida generará un `E_WARNING` (en versiones anteriores a PHP 8.0.0, `E_NOTICE`). Una variable no definida tiene un valor predeterminado de `null`. Se puede utilizar la construcción del lenguaje isset() para detectar si una variable ya se ha inicializado.

Ejemplo #4 Valores predeterminados en variables sin inicializar

    <?php
    // Una variable no definida Y no referenciada (sin contexto de uso).
    var_dump($variable_indefinida);

El ejemplo anterior mostrará:

    Warning: Undefined variable $unset_var in ...
    NULL

PHP permite la autovivificación de array (creación automática de un nuevo array) a partir de una variable no definida. Añadidiendo un elemento a una variable no definida creará un nuevo array y no producirá ninguna advertencia.

Ejemplo #5 Autovivification de un array a partir de una variable no definida

    <?php
    $unset_array[] = 'valor'; // No producirá ninguna advertencia.
    var_dump($unset_array);

Advertencia

Depender del valor predeterminado de una variable sin inicializar es problemático al incluir un archivo en otro que use el mismo nombre de variable.

Una variable puede ser destruida, utilizando la construcción del lenguaje unset().

Para información con funciones relativas a variables, mira la Referencia de funciones de variables.

## Variables Predefinidas

PHP proporciona una gran cantidad de variables predefinidas. PHP ofrece un conjunto adicional de arrays predefinidas que contienen variables del servidor web (cuando es aplicable), el entorno y entradas del usuario. Estos arrays están automáticamente disponibles en cualquier entorno. Por esa razón, a veces son conocidas como "superglobales". (No existe mecanismo en PHP para crear superglobales definidas por el usuario). Referencia de la lista de superglobales para más detalles.

> Nota: Variables variables

> Las superglobales no pueden ser usadas como variables variables en el interior de funciones o métodos de clase.

Si ciertas variables no son definidas en variables_order, los arrays de PHP predefinidos asociados a estas, estarán vacíos.

## Ámbito de las variables

El ámbito de una variable es el contexto en el cual la variable está definida. PHP tiene un ámbito de función y un ámbito global. Cualquier variable difinida fuera de una función está limitada al ámbito global. Cuando se incluye un archivo, el código contenido hereda el ámbito de la variable de la línea en la cual se incluye el archivo.

Ejemplo #1 Ejemplo de una variable de ámbito global

    <?php
    $a = 1;
    include 'b.inc'; // La variable $a estará disponible en el interior de b.inc

Cualquier variable declarada dentro de una función o una funcíón anónima está limitada al ámbito del cuerpo de dicha función. Sin embargo, las funciones de flecha vinculan las variables desde el ámbito padre haciendo que estén disponibles dentro de la función. Si se incluye un archivo dentro de una función, las variables contenidas en el archivo llamado estarán disponibles como si se hubieran definido dentro de la función que realiza la llamada.

Ejemplo #2 Ejemplo de una variable de ámbito local

    <?php
    $a = 1; // ámbito global

    function test()
    {
        var_dump($a); // La variable $a no está definida ya que se refiere a una versión local de $a
    }

    test();

El ejemplo anterior producirá un `E_WARNING` por una variable no definida (o un `E_NOTICE` antes de PHP 8.0.0). Esto se debe a la expresión echo hace referencia a una versión local de la variable $a, a la cual no se le ha asignado un valor dentro de 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 podría cambiar variables globales sin darse cuenta. En PHP, las variables globales deben ser declaradas globales dentro de la función si van a ser utilizadas dentro de dicha función.

### La palabra clave `global`

La palabra clave `global` se usa para vincular una variable desde el ámbito global a un ámbito local. La palabra clave puede ser usada con una lista de variables o con una sola variable. Una variable local será creada haciendo referendia a una variable global con el mismo nombre. Si no existe la variable global, la variable será creada en el ámbito global y asignado el valor `null`.

Ejemplo #3 Uso de `global`

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

    function Suma()
    {
        global $a, $b;

        $b = $a + $b;
    }

    Suma();
    echo $b;

El ejemplo anterior mostrará:

    3

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

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

Ejemplo #4 Uso de $GLOBALS en lugar de global

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

    function Suma()
    {
        $GLOBALS['b'] = $GLOBALS['a'] + $GLOBALS['b'];
    }

    Suma();
    echo $b;

El array $GLOBALS es un array asociativo con el nombre de la variable global como clave y los contenidos de dicha variable como el valor del elemento del array. $GLOBALS existe en cualquier ámbito, esto ocurre ya que $GLOBALS es una superglobal. Aquí hay un ejemplo que demuestra el poder de las superglobales:

Ejemplo #5 Ejemplo que demuestra las superglobales y el ámbito

    <?php
    function test_superglobal()
    {
        echo $_POST['name'];
    }

> Nota: Utilizar una clave `global` fuera de una función no es un error. Esta puede ser utilizada aún si el fichero está incluido desde el interior de una función.

### Uso de variables `static`

Otra característica importante del ámbito de las variables es la variable estática. 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:

Ejemplo #6 Ejemplo que demuestra la necesidad de variables estáticas

    <?php
    function test()
    {
        $a = 0;
        echo $a . PHP_EOL;
        $a++;
    }

    test();
    test();
    test();

Esta función tiene poca utilidad ya que cada vez que es llamada asigna a $a el valor `0` e imprime un `0`. La sentencia $a++, que incrementa la variable, no sirve para nada, ya que en cuanto la función finaliza, 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:

Ejemplo #7 Ejemplo del uso de variables estáticas

    <?php
    function test()
    {
        static $a = 0;
        echo $a . PHP_EOL;
        $a++;
    }

    test();
    test();
    test();

Ahora, $a se inicializa únicamente en la primera llamada a la función, y cada vez que la función `test()` es llamada, imprimirá el valor de $a y lo incrementa.

Las variables estáticas también proporcionan una forma de manejar funciones recursivas. La siguiente función cuenta recursivamente hasta 10, usando la variable estática $count para saber cuándo parar:

Ejemplo #8 Variables estáticas con funciones recursivas

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

        $count++;
        echo $count . PHP_EOL;
        if ($count < 10) {
            test();
        }
        $count--;
    }

    test();

Antes de PHP 8.3.0, las variables estáticas solo podían ser inicializadas usando expresiones constantes. A partir de PHP 8.3.0, expresiones dinámicas (por ejemplo, llamadas a funciones) también están permitidas:

Ejemplo #9 Declarando variables estáticas

    <?php
    function foo(){
        static $int = 0;          // correcto
        static $int = 1+2;        // correcto
        static $int = sqrt(121);  // correcto a partir de PHP 8.3.0

        $int++;
        echo $int;
    }

Las variables estáticas dentro de funiones anónimas también persisten solo dentro de esa instancia específica de la función. Si la función anónima es recreada en cada llamada, la variable estática será reinicializada.

Ejemplo #10 Variables estáticas en funciones anónimas

    <?php
    function exampleFunction($input) {
        $result = (static function () use ($input) {
            static $counter = 0;
            $counter++;
            return "Entrada: $input, Contador: $counter\n";
        });

        return $result();
    }

    // Las llamadas a exampleFunction recrearán la función anónima, por tanto
    // la variable estática no retendrá su valor.
    echo exampleFunction('A'); // Devolverá: Entrada: A, Contador: 1
    echo exampleFunction('B'); // Devolverá: Entrada: B, Contador: 1

A partir de PHP 8.1.0, cuando un método que usa variables estáticas es heredado (pero no sobrescrito), el método heredado compartirá ahora las variables estáticas con el método padre. Esto significa que las variables estáticas en los métodos ahora se comportan de la misma manera que las propiedades estáticas.

A partir de PHP 8.3.0, las variables estáticas pueden ser inicializadas con expresiones arbitrarias. Esto significa que las llamadas a métodos, por ejemplo, pueden ser usadas para inicializar variables estáticas.

Ejemplo #11 Uso de variables estáticas en métodos heredados

    <?php
    class Foo {
        public static function counter() {
            static $counter = 0;
            $counter++;
            return $counter;
        }
    }
    class Bar extends Foo {}
    var_dump(Foo::counter()); // int(1)
    var_dump(Foo::counter()); // int(2)
    var_dump(Bar::counter()); // int(3), antes de PHP 8.1.0 int(1)
    var_dump(Bar::counter()); // int(4), antes de PHP 8.1.0 int(2)

### Referencias con variables `global` y `static`

PHP 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;
        $new = new stdClass;
        $obj = &$new;
    }

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

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

El ejemplo anterior mostrará:

    NULL
    object(stdClass)#1 (0) {
    }

Un comportamiento similar se aplica a `static`. Las referencias no son almacenadas estáticamente.

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

        echo 'Objeto estático: ';
        var_dump($obj);
        if (!isset($obj)) {
            $new = new stdClass;
            // Asignar una referencia a la variable estática
            $obj = &$new;
        }
        if (!isset($obj->property)) {
            $obj->property = 1;
        } else {
            $obj->property++;
        }
        return $obj;
    }

    function &get_instance_noref() {
        static $obj;

        echo 'Objeto estático: ';
        var_dump($obj);
        if (!isset($obj)) {
            $new = new stdClass;
            // Asignar el objeto a la variable estática
            $obj = $new;
        }
        if (!isset($obj->property)) {
            $obj->property = 1;
        } else {
            $obj->property++;
        }
        return $obj;
    }

    $obj1 = get_instance_ref();
    $aun_obj1 = get_instance_ref();
    echo "\n";
    $obj2 = get_instance_noref();
    $aun_obj2 = get_instance_noref();

El ejemplo anterior mostrará:

    Objeto estático: NULL
    Objeto estático: NULL

    Objeto estático: NULL
    Objeto estático: object(stdClass)#3 (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 `&obtener_instancia_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 definir y usar dinámicamente. Una variable normal se establece con una sentencia como:

    <?php
    $a = 'hola';
    var_dump($a);

Una variable variable toma el valor de una variable y lo trata como el nombre de una variable. En el ejemplo anterior, hola, se puede usar como el nombre de una variable utilizando dos signos de dólar. Es decir:

    <?php
    $a = 'hola';
    $$a = 'mundo';
    var_dump($hola);

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

    <?php
    $a = 'hola';
    $$a = 'mundo';
    echo "$a ${$a}";

produce el mismo resultado que:

    <?php
    $a = 'hola';
    $$a = 'mundo';
    echo "$a $hola";

esto quiere decir que ambas producen el resultado: hola mundo.

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

También se puede acceder a las propiedades de una clase usando el nombre de propiedad variable. Este será resuelto dentro del ámbito del cual se hizo la llamada. Por ejemplo, en la expresión $foo->$bar, se buscará $bar en el ámibto local y se empleará su valor será como el nombre de la propiedad de $foo. Esto también es cierto si $bar es un acceso a un array.

También se pueden usar llaves para delimitar de forma clara el nombre de la propiedad. Son muy útila al acceder a valores dentro una propiedad que contiene un array, cuando el nombre de la propiedad está compuesto de múltiples partes, o cuando el nombre de la propiedad contiene caracteres que de otro modo no son válidos (p.ej. desde json_decode() o SimpleXML).

Ejemplo #1 Ejemplo de propiedad variable

    <?php
    class foo {
        var $bar = 'Soy bar.';
        var $arr = array('Soy A.', 'Soy B.', 'Soy C.');
        var $r   = 'Soy r.';
    }

    $foo = new foo();
    $bar = 'bar';
    $baz = array('foo', 'bar', 'baz', 'quux');
    echo $foo->$bar . "\n";
    echo $foo->{$baz[1]} . "\n";

    $start = 'b';
    $end   = 'ar';
    echo $foo->{$start . $end} . "\n";

    $arr = 'arr';
    echo $foo->{$arr[1]} . "\n";
    echo $foo->{$arr}[1] . "\n";

El ejemplo anterior mostrará:

Soy bar.
Soy bar.
Soy bar.
Soy r.
Soy B.
Advertencia

Por favor tenga en cuenta que las variables variables no pueden usarse con los Arrays superglobales de PHP al interior de funciones o métodos de clase. La variable `$this` es también una variable especial que no puede ser referenciada dinámicamente.

## Variables desde fuentes externas

### Formularios HTML (GET y POST)

Cuando se envía un formulario a un script de PHP, la información de dicho formulario pasa a estar automáticamente disponible en el script. Existen algunas formas de acceder a esta información, por ejemplo:

Ejemplo #1 Un formulario HTML sencillo

    <form action="foo.php" method="post">
        Nombre usuario: <input type="text" name="username" /><br />
        Email:  <input type="text" name="email" /><br />
        <input type="submit" name="submit" value="¡Enviarme!" />
    </form>

Solamente existen dos maneras de acceder a datos desde formularios HTML. Los métodos disponibles actualmente se enumeran a continuación:

Ejemplo #2 Acceso a datos de un formulario HTML sencillo con POST

    <?php
    echo $_POST['username'];
    echo $_REQUEST['username'];

Usar un formulario con 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']. Véase también $_REQUEST.

> Nota:

> Puntos y espacios en nombres de variables son convertidos a guiones bajos. Por ejemplo `<input name="a.b" />` se convierte en `$_REQUEST["a_b"]`.

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

Ejemplo #3 Variables de formulario más complejas

    <?php
    if ($_POST) {
        echo '<pre>';
        echo htmlspecialchars(print_r($_POST, true));
        echo '</pre>';
    }
    ?>
    <form action="" method="post">
        Nombre:  <input type="text" name="personal[nombre]" /><br />
        Email:   <input type="text" name="personal[email]" /><br />
        Cerveza: <br />
        <select multiple name="cerveza[]">
            <option value="warthog">Warthog</option>
            <option value="guinness">Guinness</option>
            <option value="stuttgarter">Stuttgarter Schwabenbräu</option>
        </select><br />
        <input type="submit" value="¡enviarme!" />
    </form>

> Nota: Si una variable externa comienza con una sintaxis de array válida, Los caracteres finales se ignoran en silencio. Por ejemplo, `<input name="foo[bar]baz">` se convierte en `$_REQUEST['foo']['bar']`.

#### Nombres de variables tipo IMAGE SUBMIT

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

    <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. Éstas contienen las coordenadas del clic 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 » RFC 6265. 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 están disponibles en el array de datos de la cookies apropiada, tal como $_COOKIE y $_REQUEST. Véase la página de setcookie() del manual para más detalles y ejemplos.

> Nota: A partir de PHP 7.2.34, 7.3.23 y 7.4.11, respectivamente, los nombres de las cookies entrantes ya no son con url-decoded por razones de seguridad.

Si se quieren asignar múltiples valores a una sola cookie, basta con asignarlo como un array. Por ejemplo:

    <?php
    setcookie("MiCookie[foo]", 'Prueba 1', time()+3600);
    setcookie("MiCookie[bar]", 'Prueba 2', time()+3600);

Esto creará dos cookies separadas aunque MiCookie será un array simple en el script. Si se quiere definir una sola cookie con valores múltiples, considere el uso de la función serialize() o explode() primero en el valor.

Nótese que una cookie reemplazará a una cookie anterior que tuviese el mismo nombre en el navegador a menos que la ruta o el dominio fuesen diferentes. Así, para una aplicación de carrito de compras se podría querer mantener un contador e ir pasándolo. Es decir:

Ejemplo #4 Un ejemplo de setcookie()

    <?php
    if (isset($_COOKIE['count'])) {
        $count = $_COOKIE['count'] + 1;
    } else {
        $count = 1;
    }
    setcookie('conteo', $count, time()+3600);
    setcookie("Carrito[$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. Sin embargo, hay que notar que el punto no es un carácter válido en el nombre de una variable PHP. Para conocer la razón, considere el siguiente ejemplo:

    <?php
    $varname.ext;  /* nombre de variable inválido */

Lo que el intérprete vé es el nombre de una variable $varname, seguido por el operador de concatenación, y seguido por la cadena pura (es decir, una cadena sin entrecomillar que no coincide con ninguna palabra clave o reservada conocida) 'ext'. Obviamente, no se pretendía que fuese éste 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).

### Determinación de los tipos de variables

Dado que PHP determina los tipos de las variables y los convierte (generalmente) según lo que 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.

Dado que HTTP es un protocolo de texto, la mayoría, si no todo, el contenido que llega en arrays superglobales, como $_POST y $_GET, permanecerá como cadenas de texto. PHP no intentará convertir los valores a un tipo específico. En el ejemplo siguiente, $_GET["var1"] contendrá la cadena "null" y $_GET["var2"], la cadena "123".

    /index.php?var1=null&var2=123

### Historial de cambios

Versión | Descripción
--- | ---
7.2.34, 7.3.23, 7.4.11 | Los nombres de las cookies entrantes ya no son con url-decoded por razones de seguridad.

# Constantes

## Tabla de contenidos

- Sintaxis
- Constantes predefinidas
- Constantes mágicas

Una constante es un identificador (nombre) para un valor simple. Como su nombre sugiere, ese valor no puede cambiar durante la ejecución del script (excepto las constantes mágicas, que en realidad no son constantes). Las constantes distinguen entre mayúsculas y minúsculas. Por convención, los identificadores de constantes se escriben siempre en mayúsculas.

> Nota:

> Antes de PHP 8.0.0, las constantes definidas con la función define() podían no distinguir entre mayúsculas y minúsculas.

El nombre de una constante sigue las mismas reglas que cualquier etiqueta en PHP. Un nombre de constante válido comienza con una letra o guion bajo, seguido de cualquier cantidad de letras, números o guiones bajos. Como expresión regular, se expresaría así: `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`

Es posible definir constantes con define() usando nombres reservados o incluso inválidos, cuyo valor solo puede obtenerse con la función constant(). Sin embargo, no se recomienda hacerlo.

Sugerencia

Eche un vistazo a Guía de entorno de usuario para nombres.

Ejemplo #1 Nombres de constantes válidos e inválidos

    <?php

    // Nombres de constantes válidos
    define("FOO",     "something");
    define("FOO2",    "something else");
    define("FOO_BAR", "something more");

    // Nombres de constantes inválidos
    define("2FOO",    "something");

    // Esto es válido, pero debe evitarse:
    // PHP podría algún día proporcionar una constante mágica
    // que rompa el script
    define("__FOO__", "something");

> Nota: Para estos propósitos, una letra es a-z, A-Z y los caracteres ASCII del 128 al 255 (0x80-0xff).

Al igual que las superglobals, el ámbito de una constante es global. Las constantes pueden ser accedidas desde cualquier lugar del script sin importar el ámbito. Para más información sobre el ámbito, consulte la sección del manual sobre ámbito de las variables.

> Nota: A partir de PHP 7.1.0, las constantes de clase pueden declarar una visibilidad protected o private, haciéndolas disponibles únicamente en el ámbito jerárquico de la clase en la que se definen.

## Sintaxis

Las constantes pueden definirse usando la palabra clave `const` o usando la función define(). Mientras que define() permite definir una constante con una expresión arbitraria, la palabra clave `const` tiene restricciones como se describe en el siguiente párrafo. Una vez definida, una constante no puede ser modificada ni eliminada.

Al usar la palabra clave `const`, solo se aceptan expresiones escalares (bool, int, float y string) y arrays constantes que contengan únicamente expresiones escalares. Es posible definir constantes como resource, pero debe evitarse, ya que puede causar resultados inesperados.

El valor de una constante se obtiene simplemente especificando su nombre. A diferencia de las variables, una constante no va precedida de un signo `$`. También es posible usar la función constant() para leer el valor de una constante si su nombre se obtiene dinámicamente. Use get_defined_constants() para obtener una lista de todas las constantes definidas.

> Nota: Las constantes y las variables (globales) se encuentran en espacios de nombres diferentes. Esto implica que, por ejemplo, `true` y $TRUE son generalmente diferentes.

Si se usa una constante no definida, se lanza un Error. Antes de PHP 8.0.0, las constantes no definidas se interpretaban como una cadena (string) sin comillas, es decir (CONSTANT vs "CONSTANT"). Este comportamiento está obsoleto desde PHP 7.2.0, y se emite un error de nivel `E_WARNING` cuando ocurre. Antes de PHP 7.2.0, se emitía un error de nivel E_NOTICE. Consulte también la entrada del manual sobre por qué $foo[bar] es incorrecto (a menos que `bar` sea una constante). Esto no se aplica a las constantes (totalmente) cualificadas, que siempre lanzarán un Error si no están definidas.

> Nota: Para comprobar si una constante está definida, use la función defined().

Estas son las diferencias entre constantes y variables:

- Las constantes no llevan el signo de dólar (`$`) delante;
- Las constantes pueden definirse y accederse desde cualquier lugar sin importar las reglas de ámbito de las variables;
- Las constantes no pueden redefinirse ni eliminarse una vez establecidas; y
- Las constantes solo pueden evaluarse a valores escalares o arrays.

Ejemplo #1 Definición de constantes

    <?php
    define("CONSTANT", "Hello world.");
    echo CONSTANT; // muestra "Hello world."
    echo Constant; // Lanza un Error: Undefined constant "Constant"
                   // Antes de PHP 8.0.0, muestra "Constant" y emite una advertencia.

Ejemplo #2 Definición de constantes usando la palabra clave `const`

    <?php
    // Valor escalar simple
    const CONSTANT = 'Hello World';

    echo CONSTANT . "\n";

    // Expresión escalar
    const ANOTHER_CONST = CONSTANT . '; Goodbye World';
    echo ANOTHER_CONST . "\n";

    const ANIMALS = array('dog', 'cat', 'bird');
    echo ANIMALS[1] . "\n"; // muestra "cat"

    // Arrays constantes
    define('ANIMALS_DEF', array(
        'dog',
        'cat',
        'bird'
    ));
    echo ANIMALS_DEF[1] . "\n"; // muestra "cat"

> Nota:

> A diferencia de la definición de constantes con define(), las constantes definidas con la palabra clave `const` deben declararse en el ámbito de nivel superior porque se definen en tiempo de compilación. Esto significa que no pueden declararse dentro de funciones, bucles, instrucciones `if` o bloques `try`/`catch`.

### Ver también

- Constantes de clase

## Constantes predefinidas

PHP proporciona un gran número de constantes predefinidas a cualquier script que ejecuta. Muchas de estas constantes, sin embargo, son creadas por diversas extensiones, y solo estarán presentes cuando esas extensiones estén disponibles, ya sea mediante carga dinámica o porque se han compilado con PHP.

## Constantes mágicas

Existen varias constantes mágicas que cambian dependiendo de dónde se utilicen. Por ejemplo, el valor de `__LINE__` depende de la línea en la que se use en el script. Todas estas constantes "mágicas" se resuelven en tiempo de compilación, a diferencia de las constantes regulares, que se resuelven en tiempo de ejecución. Estas constantes especiales no distinguen entre mayúsculas y minúsculas y son las siguientes:

Constantes mágicas de PHP
Nombre | Descripción
--- | ---
`__LINE__` | El número de línea actual del archivo.
`__FILE__` | La ruta completa y el nombre del archivo con los enlaces simbólicos resueltos. Si se usa dentro de un include, se devuelve el nombre del archivo incluido.
`__DIR__` | El directorio del archivo. Si se usa dentro de un include, se devuelve el directorio del archivo incluido. Es equivalente a `dirname(__FILE__)`. El nombre del directorio no incluye la barra final a menos que sea el directorio raíz.
`__FUNCTION__` | El nombre de la función, o `{closure}` para las funciones anónimas.
`__CLASS__` | El nombre de la clase. El nombre de la clase incluye el espacio de nombres en el que fue declarada (p. ej. `Foo\Bar`). Cuando se usa en un método de trait, `__CLASS__` es el nombre de la clase en la que se utiliza el trait.
`__TRAIT__` | El nombre del trait. El nombre del trait incluye el espacio de nombres en el que fue declarado (p. ej. `Foo\Bar`).
`__METHOD__` | El nombre del método de la clase.
`__PROPERTY__` | Solo es válido dentro de un hook de propiedad. Es igual al nombre de la propiedad.
`__NAMESPACE__` | El nombre del espacio de nombres actual.
`ClassName::class` | El nombre completo cualificado de la clase.

### Ver también

- ::class
- get_class()
- get_object_vars()
- file_exists()
- function_exists()

# Expresiones

La expresiones son los bloques de construcción más importantes de PHP. En PHP casi todo lo que se escribe es una expresión. La manera más simple y acertada de definir lo que es 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 se escribe `$a = 5`, se está asignando `5` a $a. `5`, obviamente, tiene el valor 5, o en otras palabras `5` es una expresión con el valor de 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, por lo que si se escribe `$b = $a`, se espera que esto se comporte tal como si se escribiera `$b = 5`. En otras palabras, $a es también una expresión con el valor 5. Si todo funciona bien, esto es exactamente lo que sucederá.

Un ejemplo de expresiones algo más complejo son las funciones. Por ejemplo, considere la siguiente función:

    <?php

    function foo ()
    {
        return 5;
    }

    ?>

Asumiendo que está familiarizado con el concepto de función (si no lo está, échele una ojeada al capítulo sobre funciones), asumirá que escribir `$c = foo()` es esencialmente igual que escribir `$c = 5`. Y está en lo cierto. Las funciones son expresiones con el valor de sus valores devueltos. Ya que `foo()` devuelve 5, el valor de la expresión '`foo()`' es 5. Normalmente las funciones no sólo devuelven un valor estático, sino que computan algo.

Por supuesto, los valores en PHP no tienen que ser enteros, y con frecuencia no lo son. PHP soporta cuatro tipos de valores escalares: valores enteros (integer), valores de coma (punto) flotante (float), valores de cadena (string) y valores booleanos (boolean) - (valores escalares son aquellos que no se pueden descomponer en piezas más pequeñas, a diferencia de las matrices, por ejemplo). PHP también soporta dos tipos compuestos (no escalares): matrices (arrays) y objetos. Cada uno de estos tipos de valores pueden ser asignados a variables o devueltos desde funciones.

PHP lleva las expresiones mucho más allá, de la misma manera que lo hacen otros lenguajes. PHP es un lenguaje orientado a expresiones, en el sentido de que casi todo es una expresión. Considere el ejemplo que ya hemos tratado, `$a = 5`. Es fácil de ver que aquí hay dos valores involucrados, el valor de la constante entera `5`, y el valor de $a que ha sido actualizado a 5 también. Aunque la verdad es que existe aquí un valor adicional involucrado, que es el valor de la asignación misma. La asignación evalúa al valor asignado, en este caso 5. En la práctica, esto significa que `$a = 5`, sin importar lo que haga, es una expresión con el valor 5. De este modo, escribir algo como `$b = ($a = 5)` es igual que escribir `$a = 5; $b = 5;` (el punto y coma marca el final de una sentencia). Ya que las asignaciones se analizan de derecha a izquierda, también se puede escribir `$b = $a = 5`.

Otro buen ejemplo de orientación a expresiones es el pre- y post-incremento y decremento. Los usuarios de PHP y de otros muchos lenguajes pueden estar familiarizados con la notación `variable++` y `variable--`. Éstos son los operadores de incremento y decremento. En PHP, al igual que en C, hay dos tipos de incrementos - pre-incremento y post-incremento. Ambos esencialmente incrementan la variable, y el efecto sobre la variable es idéntico. La diferencia está con el valor de la expresión de incremento. Pre-incremento, que se escribre `++$variable`, evalúa al valor incrementado (PHP incrementa la variable antes de leer su valor, de ahí el nombre de 'pre-incremento'). Post-incremento, que se escribe `$variable++` evalúa el valor original de $variable, antes de que sea incrementado (PHP incrementa la variable después de leer su valor, de ahí el nombre de 'post-incremento').

Un tipo de expresiones muy comunes son las expresiones de comparación. Estas expresiones evalúan si algo es `false` (falso) o `true` (verdadero). PHP soporta > (mayor que), >= (mayor o igual que), == (igual), != (distinto), < (menor que) y <= (menor o igual que). El lenguaje también soporta un conjunto de operadores de equivalencia estricta: === (igual y del mismo tipo) y !== (diferente o de distinto tipo). Estas expresiones se usan mayormente dentro de ejecuciones condicionales, tales como la sentencia `if`.

El último ejemplo de expresiones que trataremos aquí es una combinación de expresiones operador-asignación. Ya sabe que si quiere incrementar $a en 1, puede simplemente escribir `$a++` o `++$a`. Pero si lo que quiere es añadirle más de uno, por ejemplo 3, podría escribir `$a++` varias veces, pero esto, obviamente, no es una manera muy eficiente o cómoda. Una práctica mucho más común es escribir `$a = $a + 3`. `$a + 3` evalúa al valor de $a más 3, y se vuelve a asignar a $a, lo que resulta en incrementar $a en 3. En PHP, como en otros lenguajes como C, se puede escribir esto de una manera más abreviada, lo que con el tiempo se podría convertir en una forma más clara y rápida de entenderlo. Añadir 3 al valor actual de $a puede ser escrito `$a += 3`. Esto significa exactamente "toma el valor de $a, añádele 3 y asígnalo de nuevo 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`, al igual que el valor de una asignación normal, es el valor asignado. Observe que NO es 3, sino el valor combinado de $a más 3 (éste es el valor que es asignado a $a). Se puede usar cualquier operador compuesto de dos partes en este modo de operador-asignación, por ejemplo `$a -= 5` (restar 5 del valor de $a), `$b *= 7` (multiplicar el valor de $b por 7), etc.

Existe una expresión más que le puede parecer rara si no la ha visto en otros lenguajes, el operador condicional ternario:

    <?php
    $primero ? $segundo : $tercero
    ?>

Si el valor de la primera subexpresión es `true` (no es cero), se evalúa la segunda subexpresión, y ése será el resultado de la expresión condicional. Si no, se evalúa la tercera subexpresión, y ése será el valor.

El siguiente ejemplo debería ayudarle 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 la variable $a y $b */
    $c = $a++;          /* post-incremento, asignar el valor original de $a
                           (5) a $c */
    print "a = {$a}; b = {$b}; c = {$c}" . PHP_EOL;

    $e = $d = ++$b;     /* pre-incremento, asignar el valor incrementado de
                           $b (6) a $d y $e */
    print "b = {$b}; d = {$d}; e = {$e}" . PHP_EOL;

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

    $f = double($d++);  /* asignar el doble del valor de $d antes
                           del incremento, 2*6 = 12, a $f */
    print "d = {$d}; f = {$f}" . PHP_EOL;

    $g = double(++$e);  /* asignar el doble del valor de $e después
                           del incremento, 2*7 = 14, a $g */
    print "e = {$e}; g = {$g}" . PHP_EOL;

    $h = $g += 10;      /* primero, $g es incrementado en 10 y finaliza con el
                           valor 24. El valor de la asignación (24) es
                           asignado después a $h, y $h finaliza también con el
                           valor 24. */
    print "g = {$g}; h = {$h}" . PHP_EOL;
    ?>

Algunas expresiones pueden considerarse como sentencias. En este caso, una sentencia 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 sentencia en sí. Sin embargo, `$b = $a = 5;` es una sentencia válida.

Lo último que vale la pena mencionar es el valor verdadero de las expresiones. En muchos casos, principalmente en ejecuciones condicionales y bucles, no interesa saber el valor específico de la expresión, sino sólo si el valor significa `true` o `false`. Las constantes `true` y `false` (insensible a mayúsculas-minúsculas) son los dos valores booleanos posibles. Cuando es necesario, una expresión es convertida automáticamente al tipo boolean. Véase la sección sobre conversión de tipos para más detalles.

PHP proporciona una implementación completa y potente de expresiones, y documentarla por completo va más allá del ámbito de este manual. Los ejemplos de arriba deberían darle una buena idea de lo que son las expresiones y cómo construir expresiones útiles. Durante el resto de este manual se escribirá expr para indicar cualquier expresión de PHP válida.

# Los operadores

## Tabla de contenidos

- Prioridad de los operadores
- Aritmética
- Incremento y decremento
- Asignación
- Bitwise
- Comparación
- Control de errores
- Ejecución
- Lógica
- String
- Arrays
- Tipo
- Funcional

Un operador es algo que toma uno o más valores (o expresiones, en la jerga de la programación) y que produce otro valor (por lo tanto, la construcción misma se convierte en una expresión).

Los operadores pueden ser agrupados según el número de valores que aceptan. El operador unario opera solo sobre un valor, por ejemplo `!` (el operador de negación) o `++` (el operador de incremento). Los operadores binarios toman dos valores, como los tan conocidos operadores aritméticos `+` (más) y `-` (menos), y la mayoría de los operadores PHP entran en esta categoría. Finalmente, hay un único operador ternario, `? :`, que acepta tres valores; Esto se suele denominar simplemente "operador ternario" (aunque quizá podría llamarse más apropiadamente "operador condicional").

Una lista completa de los operadores de PHP se encuentra en la sección precedencia de los operadores. Esta sección también explica la precedencia de los operadores y la asociatividad, que indican exactamente cómo se evalúan las expresiones que contienen varios operadores diferentes.

## La prioridad de los operadores

La prioridad de los operadores especifica el orden en el que deben ser analizadas las valores. Por ejemplo, en la expresión `1 + 5 * 3`, el resultado es `16` y no `18`, ya que la multiplicación ("*") tiene una prioridad superior a la suma ("+"). Las parentesis pueden ser utilizados para forzar la prioridad, si es necesario. Por ejemplo: `(1 + 5) * 3` dará `18`.

Cuando los operadores tienen una prioridad igual, su asociatividad decide la forma en que los operadores son agrupados. Por ejemplo, "-" es una asociatividad por la izquierda, así `1 - 2 - 3` es agrupado de esta manera `(1 - 2) - 3` y será evaluado a `-4`. Por otro lado, "=" es una asociatividad por la derecha, así, `$a = $b = $c` es agrupado de esta manera `$a = ($b = $c)`.

Los operadores, cuya prioridad es igual, que no son asociativos, no pueden ser utilizados entre ellos, por ejemplo, `1 < 2 > 1` está prohibido en PHP. La expresión `1 <= 1 == 1` por el contrario, está permitida, ya que el operador `==` tiene una precedencia inferior al operador `<=`.

La asociatividad tiene sentido únicamente para los operadores binarios (y ternarios). Los operadores unitarios son prefijos o sufijos, por lo que esta noción no es aplicable. Por ejemplo `!!$a` puede ser agrupado únicamente de la siguiente manera `!(!$a)`.

El uso de parentesis, incluso cuando no son necesarios, permite mejorar la legibilidad del código realizando agrupamientos explícitos en lugar de imaginar la prioridad de los operadores y sus asociatividades.

La tabla siguiente lista los operadores por orden de prioridad, con la prioridad más alta en la parte superior. Los operadores en la misma línea tienen una prioridad equivalente (por lo tanto, la asociatividad decide el agrupamiento).

Prioridad de los operadores
Asociatividad | Operadores | Información adicional
--- | --- | ---
(n/a) | `clone` `new` | clone y new
derecha | `**` | aritmética
(n/a) | `+` `-` `++` `--` `~` `(int)` `(float)` `(string)` `(array)` `(object)` `(bool)` `@` | aritmética (unario `+` y `-`), incremento/decremento a nivel de bits, conversión de tipo y control de errores
izquierda | `instanceof` | tipo
(n/a) | `!` | lógico
izquierda | `*` `/` `%` | aritmética
izquierda | `+` `-` `.` | aritmética (binario `+` y `-`), array y string (`.` anterior a PHP 8.0.0)
izquierda | `<<` `>>` | bitwise
izquierda | `.` | string (a partir de PHP 8.0.0)
izquierda | `|>` | pipe
no asociativo | `<` `<=` `>` `>=` | comparación
no asociativo | `==` `!=` `===` `!==` `<>` `<=>` | comparación
izquierda | `&` | bitwise y referencias
izquierda | `^` | bitwise
izquierda | `|` | bitwise
izquierda | `&&` | lógico
izquierda | `||` | lógico
derecha | `??` | coalescencia nula
no asociativo | `? :` | ternario (izquierda--asociativo anterior a PHP 8.0.0)
derecha | `=` `+=` `-=` `*=` `**=` `/=` `.=` `%=` `&=` `|=` `^=` `<<=` `>>=` `??=` | asignación
(n/a) | `yield from` | yield from
(n/a) | `yield` | yield
(n/a) | `print` | print
izquierda | `and` | lógico
izquierda | `xor` | lógico
izquierda | `or` | lógico
(n/a) | `throw` | throw

> Nota: Los operadores unarios que comparten la fila con los operadores de conversión (`~`, `@`, y `+`/`-` unarios) tienen mayor prioridad que `instanceof`, mientras que `!` tiene menor prioridad. En consecuencia, `(int) $x instanceof Foo` se agrupa como `((int) $x) instanceof Foo`, mientras que `!$x instanceof Foo` se agrupa como `!($x instanceof Foo)`.

Ejemplo #1 Asociatividad

    <?php
    $a = 3 * 3 % 5; // (3 * 3) % 5 = 4
    // La asociatividad de los operadores ternarios difiere de C/C++
    var_dump($a);

    $a = 1;
    $b = 2;
    $a = $b += 3; // $a = ($b += 3) -> $a = 5, $b = 5
    var_dump($a, $b);
    ?>

El operador ternario requiere específicamente el uso de parentesis para levantar la ambigüedad de la prioridad.

Ejemplo #2 Precedencia explícita

    <?php
    $a = true ? 0 : (true ? 1 : 2);
    var_dump($a);

    // Esto ya no está permitido a partir de PHP 8
    // $a = true ? 0 : true ? 1 : 2;
    ?>

La prioridad y la asociatividad del operador determinan únicamente la forma en que las expresiones son agrupadas; no especifican el orden de la evaluación. PHP no especifica (de manera general) el orden en que una expresión es evaluada y el código que asume un orden específico de evaluación no debería existir, ya que el comportamiento puede cambiar entre las diferentes versiones de PHP o según el código circundante.

Ejemplo #3 Orden de evaluación indefinido

    <?php
    $a = 1;
    echo $a + $a++; // puede mostrar 2 o 3

    $i = 1;
    $array[$i] = $i++; // puede definir el índice 1 o 2
    ?>

Ejemplo #4 Precedencia de `+`, `-` y `.`

    <?php
    $x = 4;

    // Esta línea puede causar una salida inesperada :
    echo "x menos uno es igual a" . $x-1 . ", en todo caso espero\n";

    // la precedencia deseada puede ser reforzada utilizando parentesis. :
    echo "x menos uno es igual a" . ($x-1) . ", en todo caso espero\n";

    // Esto no está permitido, y levanta una TypeError :
    echo ("x menos uno es igual a" . $x) - 1 . ", en todo caso espero\n";
    ?>

El ejemplo anterior mostrará:

    -1, en todo caso espero
    -1, en todo caso espero
    Fatal error: Uncaught TypeError: Unsupported operand types: string - int

Ejemplo #5 Antes de PHP 8, `+`, `-` y `.` tenían la misma precedencia

    <?php
    $x = 4;
    // Esta línea puede causar una salida inesperada :
    echo "x menos uno es igual a" . $x-1 . ", en todo caso espero\n";

    // porque es evaluada como la línea siguiente (anterior a PHP 8.0.0) :
    echo (("x menos uno es igual a" . $x) - 1) . ", en todo caso espero\n";

    // la precedencia deseada puede ser reforzada utilizando parentesis. :
    echo "x menos uno es igual a" . ($x-1) . ", en todo caso espero\n";

    ?>

El ejemplo anterior mostrará:

    -1, en todo caso espero
    -1, en todo caso espero
    x menos uno es igual 3, en todo caso espero

> Nota:

> Aunque `=` tiene prioridad sobre la mayoría de los operadores, PHP ejecutará expresiones como: `if (!$a = foo())`. En esta situación, el resultado de `foo()` será colocado en la variable $a.

> Esto es posible porque el lado izquierdo de una asignación debe ser una variable, por lo que la asignación se agrupa con esa variable en lugar de con el operador prefijo circundante de mayor prioridad. Lo mismo se aplica a los demás operadores prefijos que toman una expresión como operando, como `clone`, los operadores de conversión, `@` y `~`: por ejemplo, `clone $a = $b` se agrupa como `clone ($a = $b)`, no como `(clone $a) = $b`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | La concatenación de strings (`.`) ahora tiene una precedencia más baja que la suma/resta aritmética (`+` y `-`) y los desplazamientos bit a bit izquierda/derecha (`<<` y `>>`); anteriormente, esto tenía la misma precedencia que `+` y `-`, y una precedencia más alta que `<<` y `>>`.
8.0.0 | El operador ternario (`? :`) ahora es no asociativo; anteriormente, era asociativo por la izquierda.
7.4.0 | Dependencia de la precedencia de la concatenación de strings (`.`) relativo a la suma/resta aritmética (`+` o `-`) o los desplazamientos bit a bit izquierda/derecha (`<<` o `>>`), es decir, su uso conjunto en una expresión sin parentesis, está obsoleto.
7.4.0 | Dependencia de la asociatividad por la izquierda del operador ternario (`? :`), es decir, la imbricación de múltiples operadores ternarios que no están entre parentesis, está obsoleta.

## Los operadores aritméticos

¿Recuerda las operaciones elementales aprendidas en la escuela? Los operadores aritméticos funcionan de la misma manera.

Operaciones elementales
Ejemplo | Nombre | Resultado
--- | --- | ---
`+$a` | Identidad | Conversión de $a a int o float, según lo más apropiado.
`-$a` | Negación | Opuesto de $a.
`$a + $b` | Adición | Suma de $a y $b.
`$a - $b` | Sustracción | Diferencia de $a y $b.
`$a * $b` | Multiplicación | Producto de $a y $b.
`$a / $b` | División | Cociente de $a y $b.
`$a % $b` | Módulo | Resto de $a dividido por $b.
`$a ** $b` | Exponenciación | Resultado de elevar $a a la potencia $b.

El operador de división `/` devuelve un valor float a menos que ambos operandos sean de tipo int (o strings numéricos que se convierten en int) y que el numerador sea un múltiplo del divisor, en cuyo caso se devolverá un valor entero. Para la división entera, ver intdiv().

Los operandos del módulo se convierten en int antes de la ejecución. Para el módulo en números decimales, ver fmod().

El resultado de la operación módulo `%` tiene el mismo signo que el primer operando, por lo que el resultado de `$a % $b` tendrá el signo de $a. Por ejemplo:

Ejemplo #1 El Operador Módulo

    <?php

    var_dump(5 % 3);
    var_dump(5 % -3);
    var_dump(-5 % 3);
    var_dump(-5 % -3);

    ?>

El ejemplo anterior mostrará:

    int(2)
    int(2)
    int(-2)
    int(-2)

### Ver también

- Las funciones matemáticas

## Operadores de incremento y decremento

PHP soporta los operadores de pre- y post- incremento y decremento. Estos operadores unaires permiten aumentar o disminuir la valor de un.

Operadores de incremento y decremento
Ejemplo | Nombre | Resultado
--- | --- | ---
++$a | Pre-incrementa | Incrementa $a en 1, luego retorna $a.
$a++ | Post-incrementa | Retorna $a, luego incrementa $a en 1.
--$a | Pre-decrementa | Decrementa $a en 1, luego retorna $a.
$a-- | Post-decrementa | Retorna $a, luego decrementa $a en 1.

A continuación, se presenta un ejemplo simple:

Ejemplo #1 Ejemplos de incremento/decremento

    <?php
    echo 'Post-incremento:', PHP_EOL;
    $a = 5;
    var_dump($a++);
    var_dump($a);
    echo 'Pre-incremento:', PHP_EOL;
    $a = 5;
    var_dump(++$a);
    var_dump($a);
    echo 'Post-decremento:', PHP_EOL;
    $a = 5;
    var_dump($a--);
    var_dump($a);
    echo 'Pre-decremento:';
    $a = 5;
    var_dump(--$a);
    var_dump($a);
    ?>

El ejemplo anterior mostrará:

    Post-incremento:
    int(5)
    int(6)
    Pre-incremento:
    int(6)
    int(6)
    Post-decremento:
    int(5)
    int(4)
    Pre-decremento:
    int(4)
    int(4)

Advertencia

Los operadores de incremento y decremento no tienen ningún efecto sobre los valores de tipo bool. Un `E_WARNING` es emitido a partir de PHP 8.3.0, ya que esto convertirá implícitamente el valor en int en el futuro.

El operador de decremento no tiene ningún efecto sobre los valores de tipo null. Un `E_WARNING` es emitido a partir de PHP 8.3.0, ya que esto convertirá implícitamente el valor en int en el futuro.

El operador de decremento no tiene ningún efecto sobre los strings no- numéricos. Un `E_WARNING` es emitido a partir de PHP 8.3.0, ya que una TypeError será levantada en el futuro.

> Nota:

> Los objetos internos que soportan la sobrecarga de la adición y/o la sustracción pueden ser incrementados y/o decrementados asimismo. Un objeto interno de este tipo es GMP.

### Funcionalidad de incremento de strings PERL

Advertencia

Esta funcionalidad es deprecada de manera suave a partir de PHP 8.3.0. La función str_increment() debe ser utilizada en su lugar.

Es posible incrementar un string no numérico en PHP. El string debe ser un string ASCII alfanumérico. Esto incrementa las letras hasta la siguiente letra, y cuando se alcanza la letra `Z`, el incremento se reporta al valor a la izquierda. Por ejemplo, `$a = 'Z'; $a++;` transforma $a en `'AA'`.

Ejemplo #2 Ejemplo de incremento de string PERL

    <?php
    echo '== Strings alfabéticos ==' . PHP_EOL;
    $s = 'W';
    for ($n=0; $n<6; $n++) {
        echo ++$s . PHP_EOL;
    }
    // Los strings alfanuméricos se comportan de manera diferente
    echo '== Caracteres digitales ==' . PHP_EOL;
    $d = 'A8';
    for ($n=0; $n<6; $n++) {
        echo ++$d . PHP_EOL;
    }
    $d = 'A08';
    for ($n=0; $n<6; $n++) {
        echo ++$d . PHP_EOL;
    }
    ?>

El ejemplo anterior mostrará:

    == Strings alfabéticos ==
    X
    Y
    Z
    AA
    AB
    AC
    == Strings alfanuméricos ==
    A9
    B0
    B1
    B2
    B3
    B4
    A09
    A10
    A11
    A12
    A13
    A14

Advertencia

Si el string alfanumérico puede ser interpretado como un string numérico, será convertido en int o en float. Esto es particularmente problemático con los strings que se asemejan a números de punto flotante escritos en notación exponencial. La función str_increment() no sufre de estas conversiones de tipo implícitas.

Ejemplo #3 Conversión de string alfanumérico a flotante

    <?php
    $s = "5d9";
    var_dump(++$s);
    var_dump(++$s);
    ?>

El ejemplo anterior mostrará:

    string(3) "5e0"
    float(6)

Esto se debe a que el valor `"5e0"` es interpretado como un float y convertido en el valor `5.0` antes de ser incrementado.

## Los operadores de asignación

El operador de asignación más simple es el signo "=". El primer reflejo es pensar que este signo significa "igual a". No es el caso. Significa que el operando de la izquierda se ve asignado el valor de la expresión que está a la derecha del signo igual.

El valor de una expresión de asignación es el valor asignado. Por ejemplo, el valor de la expresión '`$a = 3`' es el valor 3. Esto permite utilizar trucos tales como:

Ejemplo #1 Asignaciones anidadas

    <?php
    $a = ($b = 4) + 5;
    // $a ahora es igual a 9, y $b vale 4.
    var_dump($a);
    ?>

Además del simple operador de asignación, existen "operadores combinados" para todos los operadores aritméticos, la unión de arrays y para los operadores sobre los strings. Esto permite utilizar el valor de una variable en una expresión y asignar el resultado de esta expresión a esta variable. Por ejemplo:

Ejemplo #2 Asignaciones Combinadas

    <?php
    $a = 3;
    $a += 5; // asigna el valor 8 a la variable $a corresponde a la instrucción '$a = $a + 5';
    $b = "Hola ";
    $b .= " a todos!";  // asigna el valor "Hola a todos!" a
                              //  la variable $b
                              //  idéntico a $b = $b." a todos!";

    var_dump($a, $b);
    ?>

Se puede observar que la asignación copia el contenido de la variable original en la nueva variable (asignación por valor), lo que hace que los cambios de valor de una variable no modificarán el valor de la otra. Esto puede ser importante al copiar un gran array durante un bucle.

Una excepción al comportamiento de asignación por valor en PHP es el tipo object, estos son asignados por referencia. La copia de objeto debe ser explícitamente solicitada gracias al mot-clé clone.

### Asignación por referencia

La asignación por referencia también es soportada, mediante la sintaxis "$var = &$othervar;". La asignación por referencia significa que las dos variables apuntan al mismo contenedor de datos, nada es copiado en ningún lugar.

Ejemplo #3 Asignación por referencia

    <?php
    $a = 3;
    $b = &$a; // $b es una referencia a $a

    print "$a\n"; // muestra 3
    print "$b\n"; // muestra 3

    $a = 4; // cambia $a

    print "$a\n"; // muestra 4
    print "$b\n"; // muestra 4 también, porque $b es una referencia a $a, que ha sido
                  // cambiada
    ?>

El operador new devuelve una referencia automáticamente, por lo tanto, asignar el resultado de new por referencia es un error

Ejemplo #4 Nuevo operador por referencia

    <?php
    class C {}

    $o = &new C;
    ?>

El ejemplo anterior mostrará:

    Parse error: syntax error, unexpected token ";", expecting "("

Más información sobre las referencias y sus usos posibles pueden ser encontrados en la sección del manual Las referencias explicadas.

### Los operadores de asignación aritméticos

Ejemplo | Equivalente | Operación
--- | --- | ---
$a += $b | $a = $a + $b | Adición
$a -= $b | $a = $a - $b | Sustracción
$a *= $b | $a = $a * $b | Multiplicación
$a /= $b | $a = $a / $b | División
$a %= $b | $a = $a % $b | Módulo
$a **= $b | $a = $a ** $b | Exponenciación

### Operadores de asignación bits a bits

Ejemplo | Equivalente | Operación
--- | --- | ---
$a &= $b | $a = $a & $b | Operador And
$a |= $b | $a = $a | $b | Operador Or
$a ^= $b | $a = $a ^ $b | Operador Xor
$a <<= $b | $a = $a << $b | Desplazamiento a la izquierda
$a >>= $b | $a = $a >> $b | Desplazamiento a la derecha

### Otros operadores de asignación

Ejemplo | Equivalente | Operación
--- | --- | ---
$a .= $b | $a = $a . $b | Concatenación de un string
$a ??= $b | $a = $a ?? $b | Operador de coalescencia nul

### Ver también

- los operadores aritméticos
- los operadores bits a bits
- los operadores de coalescencia nul

## Operadores a nivel de bits

Los operadores a nivel de bits permiten manipular los bits en un entero.

Los operadores a nivel de bits
Ejemplo | Nombre | Resultado
--- | --- | ---
`$a & $b` | And (Y) | Los bits posicionados a 1 en $a Y en $b son posicionados a 1.
`$a | $b` | Or (O) | Los bits posicionados a 1 en $a O $b son posicionados a 1.
`$a ^ $b` | Xor (o exclusivo) | Los bits posicionados a 1 en $a O en $b pero no en los dos son posicionados a 1.
`~ $a` | Not (No) | Los bits que están posicionados a 1 en $a son posicionados a 0, y viceversa.
`$a << $b` | Desplazamiento a la izquierda | Desplaza los bits de $a, $b veces a la izquierda (cada desplazamiento equivale a una multiplicación por 2).
`$a >> $b` | Desplazamiento a la derecha | Desplaza los bits de $a, $b veces a la derecha (cada desplazamiento equivale a una división por 2).

El desplazamiento de bits en PHP es aritmético. Los bits que son desplazados fuera del entero se pierden. Los desplazamientos a la izquierda hacen aparecer ceros a la derecha, mientras que el bit de signo es desplazado a la izquierda, lo que significa que el signo del entero no es preservado. Los desplazamientos a la derecha desplazan también el bit de signo a la derecha, lo que significa que el signo es preservado.

Utilícense paréntesis para asegurarse de que la precedencia deseada sea aplicada correctamente. Por ejemplo, `$a & $b == true` aplica primero la igualdad, y luego el AND lógico, mientras que `($a & $b) == true` aplica primero el AND lógico, y luego la igualdad.

Si los dos operandos para los operadores `&`, `|` y `^` son strings, entonces la operación será realizada sobre los valores ASCII de los caracteres y el resultado será un string. En todos los otros casos, los dos operandos serán convertidos en entero y el resultado será un entero.

Si el operando para el operador `~` es un string, la operación será realizada sobre los caracteres ASCII que componen el string y el resultado será un string. De lo contrario, el operando y el resultado serán tratados como enteros.

Los operandos y el resultado de los operadores `<<` y `>>` son tratados como enteros.

El informe de errores de PHP utiliza campos de bits, que son una ilustración de la extinción de bits. Para mostrar los errores, excepto las notificaciones, las instrucciones del php.ini son : `E_ALL & ~E_NOTICE`

         Esto se comprende comparando con E_ALL :
         00000000000000000111011111111111
         Luego, apagando el valor de E_NOTICE...
         00000000000000000000000000001000
         ... y invirtiéndolo a través de ~:
         11111111111111111111111111110111
         Finalmente, se utiliza el AND lógico (&) para leer los bits activados
         en las dos valores :
         00000000000000000111011111110111

Otro medio de llegar a este resultado es utilizar el OU exclusivo (`^`), que busca los bits que están activados solo en una de las dos valores, exclusivamente : `E_ALL ^ E_NOTICE`

error_reporting también puede ser utilizado para ilustrar la activación de bits. Para mostrar únicamente los errores y los errores recuperables, se utiliza : `E_ERROR | E_RECOVERABLE_ERROR`

         Este enfoque combina E_ERROR
         00000000000000000000000000000001
         y E_RECOVERABLE_ERROR
         00000000000000000001000000000000
         Con el operador OR (|) para asegurarse de
         que los bits están activados en una de las dos valores :
         00000000000000000001000000000001

Ejemplo #1 Operaciones sobre bits y enteros

    <?php
    /*
     * Ignórese esta parte,
     * es solo formato para clarificar los resultados
     */

    $format = '(%1$2d = %1$04b) = (%2$2d = %2$04b)'
            . ' %3$s (%4$2d = %4$04b)' . "\n";

    echo <<<EOH
     ---------     ---------  -- ---------
     resultado       valor        prueba
     ---------     ---------  -- ---------
    EOH;

    /*
     * Aquí están los ejemplos
     */

    $values = array(0, 1, 2, 4, 8);
    $test = 1 + 4;

    echo "\n AND a nivel de bits \n";
    foreach ($values as $value) {
        $result = $value & $test;
        printf($format, $result, $value, '&', $test);
    }

    echo "\n OR inclusivo a nivel de bits \n";
    foreach ($values as $value) {
        $result = $value | $test;
        printf($format, $result, $value, '|', $test);
    }

    echo "\n OR exclusivo a nivel de bits (XOR) \n";
    foreach ($values as $value) {
        $result = $value ^ $test;
        printf($format, $result, $value, '^', $test);
    }
    ?>

El ejemplo anterior mostrará:

    ---------     ---------  -- ---------
     resultado       valor        prueba
     ---------     ---------  -- ---------
     AND a nivel de bits
    ( 0 = 0000) = ( 0 = 0000) & ( 5 = 0101)
    ( 1 = 0001) = ( 1 = 0001) & ( 5 = 0101)
    ( 0 = 0000) = ( 2 = 0010) & ( 5 = 0101)
    ( 4 = 0100) = ( 4 = 0100) & ( 5 = 0101)
    ( 0 = 0000) = ( 8 = 1000) & ( 5 = 0101)

     OR inclusivo a nivel de bits
    ( 5 = 0101) = ( 0 = 0000) | ( 5 = 0101)
    ( 5 = 0101) = ( 1 = 0001) | ( 5 = 0101)
    ( 7 = 0111) = ( 2 = 0010) | ( 5 = 0101)
    ( 5 = 0101) = ( 4 = 0100) | ( 5 = 0101)
    (13 = 1101) = ( 8 = 1000) | ( 5 = 0101)

     OR exclusivo a nivel de bits (XOR)
    ( 5 = 0101) = ( 0 = 0000) ^ ( 5 = 0101)
    ( 4 = 0100) = ( 1 = 0001) ^ ( 5 = 0101)
    ( 7 = 0111) = ( 2 = 0010) ^ ( 5 = 0101)
    ( 1 = 0001) = ( 4 = 0100) ^ ( 5 = 0101)
    (13 = 1101) = ( 8 = 1000) ^ ( 5 = 0101)

Ejemplo #2 Operación sobre bits y strings

    <?php
    echo 12 ^ 9, PHP_EOL; // Muestra '5'

    echo "12" ^ "9", PHP_EOL; // Muestra el carácter de borrado (ascii 8)
                     // ('1' (ascii 49)) ^ ('9' (ascii 57)) = #8

    echo "hallo" ^ "hello", PHP_EOL; // Muestra los valores ASCII #0 #4 #0 #0 #0
                            // 'a' ^ 'e' = #4

    echo 2 ^ "3", PHP_EOL; // Muestra 1
                  // 2 ^ ((int) "3") == 1

    echo "2" ^ 3, PHP_EOL; // Muestra 1
                  // ((int) "2") ^ 3 == 1
    ?>

Ejemplo #3 Desplazamiento de bits sobre enteros

    <?php
    /*
     * Aquí están algunos ejemplos
     */

    echo "\n--- Desplazamientos a la derecha sobre enteros positivos ---\n";

    $val = 4;
    $places = 1;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'copia del bit de signo ahora a la izquierda');

    $val = 4;
    $places = 2;
    $res = $val >> $places;
    p($res, $val, '>>', $places);

    $val = 4;
    $places = 3;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'bits salieron por la derecha');

    $val = 4;
    $places = 4;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'mismo resultado que arriba: no hay desplazamiento más allá de 0');

    echo "\n--- Desplazamientos a la derecha sobre enteros negativos ---\n";

    $val = -4;
    $places = 1;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'copia del bit de signo ahora a la izquierda');

    $val = -4;
    $places = 2;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'bits salieron por la derecha');

    $val = -4;
    $places = 3;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'mismo resultado que arriba: no hay desplazamiento más allá de -1');

    echo "\n--- Desplazamientos a la izquierda sobre enteros positivos ---\n";

    $val = 4;
    $places = 1;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'complemento de ceros a la derecha');

    $val = 4;
    $places = (PHP_INT_SIZE * 8) - 4;
    $res = $val << $places;
    p($res, $val, '<<', $places);

    $val = 4;
    $places = (PHP_INT_SIZE * 8) - 3;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'el bit de signo salió');

    $val = 4;
    $places = (PHP_INT_SIZE * 8) - 2;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'bits salieron a la izquierda');

    echo "\n--- Desplazamientos a la izquierda sobre enteros negativos ---\n";

    $val = -4;
    $places = 1;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'complemento de ceros a la derecha');

    $val = -4;
    $places = (PHP_INT_SIZE * 8) - 3;
    $res = $val << $places;
    p($res, $val, '<<', $places);

    $val = -4;
    $places = (PHP_INT_SIZE * 8) - 2;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'bits salieron a la izquierda, incluyendo el bit de signo');

    /*
     * Ignórese esta sección
     * Contiene código para el formato de este ejemplo
     */

    function p($res, $val, $op, $places, $note = '') {
        $format = '%0' . (PHP_INT_SIZE * 8) . "b\n";

        printf("Expresión : %d = %d %s %d\n", $res, $val, $op, $places);

        echo " Decimal :\n";
        printf("  val=%d\n", $val);
        printf("  res=%d\n", $res);

        echo " Binario :\n";
        printf('  val=' . $format, $val);
        printf('  res=' . $format, $res);

        if ($note) {
            echo " Nota : $note\n";
        }

        echo "\n\n";
    }
    ?>

Resultado del ejemplo anterior en una máquina de 32 bits:

    --- Desplazamientos a la derecha sobre enteros positivos ---
    Expresión : 2 = 4 >> 1
     Decimal :
      val=4
      res=2
     Binario :
      val=00000000000000000000000000000100
      res=00000000000000000000000000000010
     Nota : copia del bit de signo ahora a la izquierda

    Expresión : 1 = 4 >> 2
     Decimal :
      val=4
      res=1
     Binario :
      val=00000000000000000000000000000100
      res=00000000000000000000000000000001

    Expresión : 0 = 4 >> 3
     Decimal :
      val=4
      res=0
     Binario :
      val=00000000000000000000000000000100
      res=00000000000000000000000000000000
     Nota : bits salieron por la derecha

    Expresión : 0 = 4 >> 4
     Decimal :
      val=4
      res=0
     Binario :
      val=00000000000000000000000000000100
      res=00000000000000000000000000000000
     Nota : mismo resultado que arriba: no hay desplazamiento más allá de 0

    --- Desplazamientos a la derecha sobre enteros negativos ---
    Expresión : -2 = -4 >> 1
     Decimal :
      val=-4
      res=-2
     Binario :
      val=11111111111111111111111111111100
      res=11111111111111111111111111111110
     Nota : copia del bit de signo a la izquierda

    Expresión : -1 = -4 >> 2
     Decimal :
      val=-4
      res=-1
     Binario :
      val=11111111111111111111111111111100
      res=11111111111111111111111111111111
     Nota : bits salieron por la derecha

    Expresión : -1 = -4 >> 3
     Decimal :
      val=-4
      res=-1
     Binario :
      val=11111111111111111111111111111100
      res=11111111111111111111111111111111
     Nota : mismo resultado que arriba: no hay desplazamiento más allá de -1

    --- Desplazamientos a la izquierda sobre enteros positivos ---
    Expresión : 8 = 4 << 1
     Decimal :
      val=4
      res=8
     Binario :
      val=00000000000000000000000000000100
      res=00000000000000000000000000001000
     Nota : complemento de ceros a la derecha

    Expresión : 1073741824 = 4 << 28
     Decimal :
      val=4
      res=1073741824
     Binario :
      val=00000000000000000000000000000100
      res=01000000000000000000000000000000

    Expresión : -2147483648 = 4 << 29
     Decimal :
      val=4
      res=-2147483648
     Binario :
      val=00000000000000000000000000000100
      res=10000000000000000000000000000000
     Nota : el bit de signo salió

    Expresión : 0 = 4 << 30
     Decimal :
      val=4
      res=0
     Binario :
      val=00000000000000000000000000000100
      res=00000000000000000000000000000000
     Nota : bits salieron a la izquierda

    --- Desplazamientos a la izquierda sobre enteros negativos ---
    Expresión : -8 = -4 << 1
     Decimal :
      val=-4
      res=-8
     Binario :
      val=11111111111111111111111111111100
      res=11111111111111111111111111111000
     Nota : complemento de ceros a la derecha

    Expresión : -2147483648 = -4 << 29
     Decimal :
      val=-4
      res=-2147483648
     Binario :
      val=11111111111111111111111111111100
      res=10000000000000000000000000000000

    Expresión : 0 = -4 << 30
     Decimal :
      val=-4
      res=0
     Binario :
      val=11111111111111111111111111111100
      res=00000000000000000000000000000000
     Nota : bits salieron a la izquierda, incluyendo el bit de signo

Resultado del ejemplo anterior en una máquina de 64 bits:

    --- Desplazamientos a la derecha sobre enteros positivos ---
    Expresión : 2 = 4 >> 1
     Decimal :
      val=4
      res=2
     Binario :
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000010
     Nota : copia del bit de signo ahora a la izquierda

    Expresión : 1 = 4 >> 2
     Decimal :
      val=4
      res=1
     Binario :
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000001

    Expresión : 0 = 4 >> 3
     Decimal :
      val=4
      res=0
     Binario :
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000000
     Nota : bits salieron por la derecha

    Expresión : 0 = 4 >> 4
     Decimal :
      val=4
      res=0
     Binario :
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000000
     Nota : mismo resultado que arriba: no hay desplazamiento más allá de 0

    --- Desplazamientos a la derecha sobre enteros negativos ---
    Expresión : -2 = -4 >> 1
     Decimal :
      val=-4
      res=-2
     Binario :
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1111111111111111111111111111111111111111111111111111111111111110
     Nota : copia del bit de signo ahora a la izquierda

    Expresión : -1 = -4 >> 2
     Decimal :
      val=-4
      res=-1
     Binario :
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1111111111111111111111111111111111111111111111111111111111111111
     Nota : bits salieron por la derecha

    Expresión : -1 = -4 >> 3
     Decimal :
      val=-4
      res=-1
     Binario :
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1111111111111111111111111111111111111111111111111111111111111111
     Nota : mismo resultado que arriba: no hay desplazamiento más allá de -1

    --- Desplazamiento a la izquierda sobre enteros negativos ---
    Expresión : 8 = 4 << 1
     Decimal :
      val=4
      res=8
     Binario :
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000001000
     Nota : complemento de ceros a la derecha

    Expresión : 4611686018427387904 = 4 << 60
     Decimal :
      val=4
      res=4611686018427387904
     Binario :
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0100000000000000000000000000000000000000000000000000000000000000

    Expresión : -9223372036854775808 = 4 << 61
     Decimal :
      val=4
      res=-9223372036854775808
     Binario :
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=1000000000000000000000000000000000000000000000000000000000000000
     Nota : el bit de signo salió

    Expresión : 0 = 4 << 62
     Decimal :
      val=4
      res=0
     Binario :
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000000
     Nota : bits salieron a la izquierda

    --- Desplazamiento a la izquierda sobre enteros negativos ---
    Expresión : -8 = -4 << 1
     Decimal :
      val=-4
      res=-8
     Binario :
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1111111111111111111111111111111111111111111111111111111111111000
     Nota : complemento de ceros a la derecha

    Expresión : -9223372036854775808 = -4 << 61
     Decimal :
      val=-4
      res=-9223372036854775808
     Binario :
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1000000000000000000000000000000000000000000000000000000000000000

    Expresión : 0 = -4 << 62
     Decimal :
      val=-4
      res=0
     Binario :
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=0000000000000000000000000000000000000000000000000000000000000000
     Nota : bits salieron a la izquierda, incluyendo el bit de signo

Advertencia

Úsense las funciones de la extensión gmp para las manipulaciones sobre bits, cuando los enteros exceden `PHP_INT_MAX`.

### Ver también

- pack()
- unpack()
- gmp_and()
- gmp_or()
- gmp_xor()
- gmp_testbit()
- gmp_clrbit()

## Operadores de comparación

Los operadores de comparación, como su nombre indica, permiten comparar dos valores. También se debe estar interesado por las tablas de comparaciones de tipos, ya que muestran ejemplos de muchos tipos de comparaciones.

Operadores de comparación
Ejemplo | Nombre | Resultado
--- | --- | ---
$a == $b | Igual | `true` si $a es igual a $b después del transtipado.
$a === $b | Idéntico | `true` si $a es igual a $b y son del mismo tipo.
$a != $b | Diferente | `true` si $a es diferente de $b después del transtipado.
$a <> $b | Diferente | `true` si $a es diferente de $b después del transtipado.
$a !== $b | Diferente | `true` si $a es diferente de $b o bien si no son del mismo tipo.
$a < $b | Menor que | `true` si $a es estrictamente menor que $b.
$a > $b | Mayor | `true` si $a es estrictamente mayor que $b.
$a <= $b | Menor o igual | `true` si $a es menor o igual a $b.
$a >= $b | Mayor o igual | `true` si $a es mayor o igual a $b.
$a <=> $b | Combinado | Un int menor, igual o mayor a cero cuando $a es menor, igual, o mayor a $b respectivamente.

Si los dos operandos son strings numéricos, o si un operando es un número y el otro es un string numérico, entonces la comparación se efectuará numéricamente. Estas reglas también se aplican a la instrucción switch. La conversión de tipo no interviene cuando la comparación es `===` o `!==` ya que esto implica tanto una comparación de tipo como de valor.

Advertencia

Antes de PHP 8.0.0, si un string es comparado a un número o a un string numérico, entonces el string será convertido en un número antes de efectuar la comparación. Esto puede llevar a resultados sorprendentes como se puede ver en el siguiente ejemplo:

    <?php
    var_dump(0 == "a");
    var_dump("1" == "01");
    var_dump("10" == "1e1");
    var_dump(100 == "1e2");

    switch ("a") {
    case 0:
        echo "0";
        break;
    case "a":
        echo "a";
        break;
    }
    ?>

Resultado del ejemplo anterior en PHP 7:

    bool(true)
    bool(true)
    bool(true)
    bool(true)
    0

Resultado del ejemplo anterior en PHP 8:

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    a

Ejemplo #1 Operadores de comparación

    <?php
    // Enteros
    echo 1 <=> 1, ' '; // 0
    echo 1 <=> 2, ' '; // -1
    echo 2 <=> 1, ' '; // 1

    // Números flotantes
    echo 1.5 <=> 1.5, ' '; // 0
    echo 1.5 <=> 2.5, ' '; // -1
    echo 2.5 <=> 1.5, ' '; // 1

    // Strings
    echo "a" <=> "a", ' '; // 0
    echo "a" <=> "b", ' '; // -1
    echo "b" <=> "a", ' '; // 1

    echo "a" <=> "aa", ' '; // -1
    echo "zz" <=> "aa", ' '; // 1

    // Arrays
    echo [] <=> [], ' '; // 0
    echo [1, 2, 3] <=> [1, 2, 3], ' '; // 0
    echo [1, 2, 3] <=> [], ' '; // 1
    echo [1, 2, 3] <=> [1, 2, 1], ' '; // 1
    echo [1, 2, 3] <=> [1, 2, 4], ' '; // -1

    // Objetos
    $a = (object) ["a" => "b"];
    $b = (object) ["a" => "b"];
    echo $a <=> $b, ' '; // 0

    $a = (object) ["a" => "b"];
    $b = (object) ["a" => "c"];
    echo $a <=> $b, ' '; // -1

    $a = (object) ["a" => "c"];
    $b = (object) ["a" => "b"];
    echo $a <=> $b, ' '; // 1

    // No solo las valores son comparados; las claves deben coincidir
    $a = (object) ["a" => "b"];
    $b = (object) ["b" => "b"];
    echo $a <=> $b, ' '; // 1

    ?>

Para los diferentes tipos, la comparación se realiza siguiendo la tabla siguiente (en orden).

Comparación con múltiples tipos
Tipo del operando 1 | Tipo del operando 2 | Resultado
--- | --- | ---
null o string | string | Convierte `null` en "", comparación numérica o léxica
bool o null | Cualquier cosa | Convierte en bool, `false` < `true`
object | object | Las clases internas pueden definir su propio método de comparación; diferentes clases son incomparables; entre objetos de la misma clase ver Comparación de objetos
string, resource, int o float | string, resource, int o float | Transforma los strings y los recursos en números
array | array | El array con menos miembros es menor, si la clave del operando 1 no es encontrada en el operando 2, entonces los arrays son incomparables, de lo contrario la comparación se realiza valor por valor (ver el siguiente ejemplo)
object | Cualquier cosa | El object es siempre mayor
array | Cualquier cosa | El array es siempre mayor

Ejemplo #2 Comparación Booléen/null

    <?php
    // Booléen y null siempre son comparados como booléans
    var_dump(1 == TRUE);  // TRUE - idéntico a (bool) 1 == TRUE
    var_dump(0 == FALSE); // TRUE - idéntico a (bool) 0 == FALSE
    var_dump(100 < TRUE); // FALSE - idéntico a (bool) 100 < TRUE
    var_dump(-10 < FALSE);// FALSE - idéntico a (bool) -10 < FALSE
    var_dump(min(-100, -10, NULL, 10, 100)); // NULL - (bool) NULL < (bool) -100 es idéntico a FALSE < TRUE
    ?>

Ejemplo #3 Transcripción de las comparaciones estándar de arrays

    <?php
    // Los arrays son comparados de esta manera con los operadores estándar de comparación y el operador combinado
    function standard_array_compare($op1, $op2)
    {
       if (count($op1) < count($op2)) {
          return -1; // $op1 < $op2
       } elseif (count($op1) > count($op2)) {
          return 1; // $op1 > $op2
       }
       foreach ($op1 as $key => $val) {
          if (!array_key_exists($key, $op2)) {
             return 1;
          } elseif ($val < $op2[$key]) {
             return -1;
          } elseif ($val > $op2[$key]) {
             return 1;
          }
       }
       return 0; // $op1 == $op2
    }
    ?>

Advertencia

# Comparación de números de punto flotante

Debido a la forma en que los floats son representados internamente, no se debe probar la igualdad entre dos números de tipo float.

Ver la documentación de float para más información.

> Nota: Tenga en cuenta que la manipulación de tipos no siempre es evidente al comparar valores de diferentes tipos, en particular al comparar ints con bools o ints con strings. Por lo tanto, generalmente se recomienda utilizar los operadores de comparación `===` y `!==` en lugar de `==` y `!=` en la mayoría de los casos.

### Valores incomparables

Mientras que las comparaciones de identidad (`===` y `!==`) pueden ser aplicadas a valores arbitrarios, los otros operadores de comparación solo deben ser aplicados a valores comparables. El resultado de la comparación de valores incomparables es indefinido, y no debe ser utilizado.

### Ver también

- strcasecmp()
- strcmp()
- operador de arrays
- Tipos

### El operador ternario

Otro operador condicional es el operador ternario ("?:").

Ejemplo #4 Asignación de un valor por defecto

    <?php
    // Ejemplo de uso para el operador ternario
    $action = (empty($_POST['action'])) ? 'default' : $_POST['action'];

    // La línea anterior es idéntica a la siguiente condición:
    if (empty($_POST['action'])) {
       $action = 'default';
    } else {
       $action = $_POST['action'];
    }
    ?>

La expresión `(expr1) ? (expr2) : (expr3)` se evalúa a expr2 si expr1 se evalúa a `true`, y expr3 si expr1 se evalúa a `false`.

Es posible omitir la parte central del operador ternario. La expresión `expr1 ?: expr3` evalúa el resultado de expr1 si expr1 vale `true`, y expr3 en caso contrario. expr1 solo se evalúa una vez en este caso.

> Nota: Tenga en cuenta que el operador ternario es una expresión, y no se evalúa como una variable, sino como el resultado de la expresión. Es importante saberlo si se desea devolver una variable por referencia. La instrucción `return $var == 42 ? $a : $b;` en una función devuelta por referencia no funcionará y se emitirá una alerta.

> Nota:

> Se recomienda no "apilar" las expresiones ternarias. El comportamiento de PHP al utilizar varios operadores ternarios que no están entre paréntesis en una única expresión es no evidente en comparación con otros lenguajes. Anteriormente a PHP 8.0.0, el operador ternario se evaluaba de izquierda a derecha, en lugar de derecha a izquierda como la mayoría de los otros lenguajes de programación. Dependiendo de la asociatividad a la izquierda es obsoleto a partir de PHP 7.4.0. A partir de PHP 8.0.0, el operador ternario no es asociativo.

> Ejemplo #5 Comportamiento de PHP

>     <?php
>     // A primera vista, lo siguiente debería devolver 'true'
>     echo (true ? 'true' : false ? 't' : 'f');

>     // sin embargo, la expresión anterior devolverá 't' antes de PHP 8.0.0
>     // porque el operador ternario es de izquierda a derecha

>     // la siguiente expresión es una versión más evidente del mismo código
>     echo ((true ? 'true' : false) ? 't' : 'f');

>     // aquí, se puede observar que la primera expresión se evalúa a 'true',
>     // lo que hace que se evalúe a (bool)true, lo que devuelve la rama
>     // 'verdadera' de la segunda expresión ternaria.
>     ?>

> Nota:

> La combinación de ternario corto (`?:`), sin embargo, es estable y se comporta de manera razonable. Esto evaluará el primer argumento que evalúa a un valor no-falsy. Tenga en cuenta que los valores indefinidos siempre emitirán un aviso.

> Ejemplo #6 Combinación de ternario corto

>     <?php
>     echo 0 ?: 1 ?: 2 ?: 3, PHP_EOL; //1
>     echo 0 ?: 0 ?: 2 ?: 3, PHP_EOL; //2
>     echo 0 ?: 0 ?: 0 ?: 3, PHP_EOL; //3
>     ?>

### Operador de fusión Null

Otro operador corto útil es el operador "??" (o fusión null).

Ejemplo #7 Asignar un valor por defecto

    <?php
    // Ejemplo de uso para: Operador de fusión Null
    $action = $_POST['action'] ?? 'default';

    // el código anterior es equivalente a la siguiente estructura if/else
    if (isset($_POST['action'])) {
        $action = $_POST['action'];
    } else {
        $action = 'default';
    }
    ?>

La expresión `(expr1) ?? (expr2)` devuelve expr2 si expr1 es `null`, y expr1 en los otros casos.

En particular, este operador no emite una notificación o advertencia si la parte izquierda no existe, exactamente como isset(). Esto es especialmente útil para las claves de los arrays.

> Nota: Tenga en cuenta que el operador de fusión null es una expresión, y que no se evalúa como una variable, sino como el resultado de una expresión. Es importante saberlo si se desea devolver una variable por referencia. La expresión `return $foo ?? $bar;` es un retorno por referencia que no funciona y emite una advertencia.

> Nota:

> El operador de fusión null tiene una precedencia baja. Esto significa que al mezclarlo con otros operadores (como la concatenación de strings o los operadores aritméticos) se requerirán paréntesis.

>     <?php
>     // Emite una advertencia de que $name es indefinida.
>     print 'Mr. ' . $name ?? 'Anonymous';

>     // Imprime "Mr. Anonymous"
>     print 'Mr. ' . ($name ?? 'Anonymous');
>     ?>

> Nota:

> Tenga en cuenta que el operador de fusión null permite una imbricación simple:

> Ejemplo #8 Imbricación de la operación de fusión null

>     <?php

>     $foo = null;
>     $bar = null;
>     $baz = 1;
>     $qux = 2;

>     echo $foo ?? $bar ?? $baz ?? $qux; // salida 1

>     ?>

## Operador de control de errores

PHP soporta un operador de control de errores: el arroba (`@`). Cuando este operador se añade como prefijo a una expresión PHP, los diagnósticos de errores que pueden ser generados por esta expresión serán ignorados.

Si un gestor de errores personalizado es definido con set_error_handler(), será llamado aún si el diagnóstico ha sido ignorado.

Advertencia

Anterior a PHP 8.0.0, la función error_reporting() llamada en el gestor de errores personalizado siempre retornaba `0` si el error fue ignorado con el operador `@`. A partir de 8.0.0, retorna el valor de esta expresión (bit a bit): `E_ERROR | E_CORE_ERROR | E_COMPILE_ERROR | E_USER_ERROR | E_RECOVERABLE_ERROR | E_PARSE`.

Todos los mensajes de error generados por la expresión están disponibles en el elemento `"message"` del array retornado por la función error_get_last(). El resultado de la función cambiará con cada error, por lo tanto, es conveniente verificarlo frecuentemente.

Ejemplo #1 Error de fichero intencional

    <?php
    $mon_fichier = @file ('non_persistent_file') or
        die ("Imposible abrir el fichero: El error es: '" . error_get_last()['message'] . "'");
    ?>

Ejemplo #2 La expresión de eliminación

    <?php
    // Esto funciona con cualquier expresión, no solo con funciones
      $value = @$cache[$key];
    // la línea anterior no mostrará una alerta si la clave $key del array no existe
    ?>

> Nota: El operador `@` solo funciona con las expresiones. La regla general es: si es posible tomar el valor de algo, entonces se puede preponer el operador `@` a este. Por ejemplo, puede ser prepuesto a variables, llamadas de funciones, ciertas llamadas a construcciones de lenguaje (por ejemplo, include), etc. No puede ser prepuesto a definiciones de funciones o clases o estructuras condicionales como `if` y `foreach`, etc.

Advertencia

Anterior a PHP 8.0.0, era posible que el operador `@` desactivara los errores críticos que terminaban la ejecución del script. Por ejemplo, preponer `@` a una llamada de una función que no existe, que esté indisponible o mal escrita, causaba que el script terminara sin ninguna indicación de por qué.

### Ver también

- error_reporting()
- Gestión de Errores y Funciones de Logging

## Operador de ejecución

PHP soporta un operador de ejecución: comillas invertidas (````). Téngase en cuenta que no se trata de comillas simples. PHP intenta ejecutar el contenido de estas comillas invertidas como un comando shell. El resultado será devuelto (es decir: no será simplemente enviado a la salida estándar, puede ser asignado a una variable). Utilizar las comillas invertidas equivale a utilizar la función shell_exec().

Ejemplo #1 Operador de comillas invertidas

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

> Nota:

> Este operador está desactivado cuando la función shell_exec() está desactivada.

> Nota:

> A diferencia de otros lenguajes, las comillas invertidas no tienen un significado especial en una cadena rodeada de comillas dobles.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | El operador de comillas invertidas como alias para shell_exec() ha quedado obsoleto.

### Ver también

- Las funciones de ejecución del sistema
- popen()
- proc_open()
- Utilizar PHP desde la línea de comandos

## Los operadores lógicos

Los operadores lógicos
Ejemplo | Nombre | Resultado
--- | --- | ---
$a and $b | And (Y) | `true` si $a Y $b valen `true`.
$a or $b | Or (O) | `true` si $a O $b valen `true`.
$a xor $b | XOR | `true` si $a O $b es `true`, pero no ambos a la vez.
! $a | Not (No) | `true` si $a no es `true`.
$a && $b | And (Y) | `true` si $a Y $b son `true`.
$a || $b | Or (O) | `true` si $a O $b es `true`.

La razón por la cual existen dos tipos de "Y" y de "O" es que tienen diferentes prioridades. Ver el párrafo precedencia de operadores.

Ejemplo #1 Ilustración de los operadores lógicos

    <?php

    // --------------------
    // foo() nunca será llamada, ya que estos operadores se anulan

    $a = (false && foo());
    $b = (true  || foo());
    $c = (false and foo());
    $d = (true  or  foo());

    // --------------------
    // "||" tiene una precedencia superior a "or"

    // El resultado de la expresión (false || true) es asignado a $e
    // Actúa como: ($e = (false || true))
    $e = false || true;

    // La constante false es asignada a $f antes de que aparezca la operación "or"
    // Actúa como: (($f = false) or true)
    $f = false or true;

    var_dump($e, $f);

    // --------------------
    // "&&" tiene una precedencia superior a "and"

    // El resultado de la expresión (true && false) es asignado a $g
    // Actúa como: ($g = (true && false))
    $g = true && false;

    // La constante true es asignada a $h antes de que aparezca la operación "and"
    // Actúa como: (($h = true) and false)
    $h = true and false;

    var_dump($g, $h);
    ?>

Resultado del ejemplo anterior es similar a:

    bool(true)
    bool(false)
    bool(false)
    bool(true)

## Operadores de string

Existen dos operadores de string string. El primero es el operador de concatenación ('.'), que devuelve la concatenación de sus dos argumentos. El segundo es el operador de asignación concatenante (`.=`). Ver operadores de asignación para más detalles.

Ejemplo #1 Concatenación de string

    <?php
    $a = "Hello ";
    $b = $a . "World!"; // $b contiene ahora "Hello World!"
    var_dump($b);

    $a = "Hello ";
    $a .= "World!";     // $a contiene ahora "Hello World!"
    var_dump($a);
    ?>

### Ver también

- El tipo string
- Las funciones de string

## Operadores de arrays

Operadores de arrays
Ejemplo | Nombre | Resultado
--- | --- | ---
$a + $b | Unión | Unión de $a y $b.
$a == $b | Igualdad | `true` si $a y $b contienen las mismas pares clave/valor.
$a === $b | Idéntico | `true` si $a y $b contienen las mismas pares clave/valor en el mismo orden y del mismo tipo.
$a != $b | Desigualdad | `true` si $a no es igual a $b.
$a <> $b | Desigualdad | `true` si $a no es igual a $b.
$a !== $b | No idéntico | `true` si $a no es idéntico a $b.

El operador `+` devuelve el array de la izquierda al cual se añaden los elementos del array de la derecha. Para las claves presentes en los 2 arrays, los elementos del array de la izquierda serán utilizados mientras que los elementos correspondientes en el array de la derecha serán ignorados.

Ejemplo #1 El operador de adición a un array

    <?php
    $a = array("a" => "manzana", "b" => "plátano");
    $b = array("a" =>"pera", "b" => "fresa", "c" => "cereza");

    $c = $a + $b; // Unión de $a y $b
    echo "Unión de \$a y \$b : \n";
    var_dump($c);

    $c = $b + $a; // Unión de $b y $a
    echo "Unión de \$b y \$a : \n";
    var_dump($c);

    $a += $b; // Unión de $a += $b es $a y $b
    echo "Unión de \$a += \$b: \n";
    var_dump($a);
    ?>

El ejemplo anterior mostrará:

    Unión de $a y $b :
    array(3) {
      ["a"]=>
      string(7) "manzana"
      ["b"]=>
      string(7) "plátano"
      ["c"]=>
      string(6) "cereza"
    }
    Unión de $b y $a :
    array(3) {
      ["a"]=>
      string(4) "pera"
      ["b"]=>
      string(5) "fresa"
      ["c"]=>
      string(6) "cereza"
    }
    Unión de $a += $b:
    array(3) {
      ["a"]=>
      string(7) "manzana"
      ["b"]=>
      string(7) "plátano"
      ["c"]=>
      string(6) "cereza"
    }

Los elementos de un array son iguales en términos de comparación si tienen la misma clave y el mismo valor.

Ejemplo #2 Comparar arrays

    <?php
    $a = array("manzana", "plátano");
    $b = array(1 => "plátano", "0" => "manzana");

    var_dump($a == $b); // bool(true)
    var_dump($a === $b); // bool(false)
    ?>

### Ver también

- El tipo array
- Las Funciones de Arrays

## Operadores de tipos

`instanceof` se utiliza para determinar si una variable PHP es un objeto instanciado de una cierta clase:

Ejemplo #1 Uso de `instanceof` con clases

    <?php
    class MiClase
    {
    }
    class NoMiClase
    {
    }
    $a = new MiClase;

    var_dump($a instanceof MiClase);
    var_dump($a instanceof NoMiClase);
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(false)

`instanceof` también puede ser utilizado para determinar si una variable es un objeto instanciado de una clase que hereda de una clase padre:

Ejemplo #2 Uso de `instanceof` con clases heredadas

    <?php
    class ClasePadre
    {
    }
    class MiClase extends ClasePadre
    {
    }
    $a = new MiClase;

    var_dump($a instanceof MiClase);
    var_dump($a instanceof ClasePadre);
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(true)

Para verificar si un objeto no es una instancia de una clase, el operador lógico `not` puede ser utilizado.

Ejemplo #3 Uso de `instanceof` para verificar que el objeto no es una instancia de la clase

    <?php
    class MiClase
    {
    }
    $a = new MiClase;
    var_dump(!($a instanceof stdClass));
    ?>

El ejemplo anterior mostrará:

    bool(true)

Y finalmente, `instanceof` puede ser utilizado para determinar si una variable es un objeto instanciado de una clase que implementa una interface:

Ejemplo #4 Uso de `instanceof` para una interface

    <?php
    interface MiInterface
    {
    }
    class MiClase implements MiInterface
    {
    }
    $a = new MiClase;

    var_dump($a instanceof MiClase);
    var_dump($a instanceof MiInterface);
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(true)

Aunque `instanceof` se utiliza habitualmente con un nombre de clase literal, también puede ser utilizado con otro objeto o una cadena representando una variable:

Ejemplo #5 Uso de `instanceof` con otras variables

    <?php
    interface MiInterface
    {
    }
    class MiClase implements MiInterface
    {
    }
    $a = new MiClase;
    $b = new MiClase;
    $c = 'MiClase';
    $d = 'NoMiClase';
    var_dump($a instanceof $b); // $b es un objeto de la clase MiClase
    var_dump($a instanceof $c); // $c es una cadena 'MiClase'
    var_dump($a instanceof $d); // $d es una cadena 'NoMiClase'
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(true)
    bool(false)

instanceof no lanza ningún error si la variable probada no es un objeto, simplemente devolverá `false`. Sin embargo, las constantes no están permitidas.

Ejemplo #6 Uso de `instanceof` para probar otras variables

    <?php
    $a = 1;
    $b = NULL;
    $c = fopen('/tmp/', 'r');
    var_dump($a instanceof stdClass); // $a es un entero
    var_dump($b instanceof stdClass); // $b vale NULL
    var_dump($c instanceof stdClass); // $c es un recurso
    var_dump(FALSE instanceof stdClass);
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(false)
    bool(false)
    PHP Fatal error:  instanceof espera una instancia de objeto, constante dada

A partir de PHP 7.3.0, las constantes están permitidas en el lado izquierdo del operador `instanceof`.

Ejemplo #7 Uso de `instanceof` para probar constantes

    <?php
    var_dump(FALSE instanceof stdClass);
    ?>

Resultado del ejemplo anterior en PHP 7.3:

    bool(false)

A partir de PHP 8.0.0, `instanceof` puede ahora ser utilizado con expresiones arbitrarias. La expresión debe estar entre paréntesis y producir una string.

Ejemplo #8 Uso de `instanceof` con una expresión arbitraria

    <?php

    class ClaseA extends \stdClass {}
    class ClaseB extends \stdClass {}
    class ClaseC extends ClaseB {}
    class ClaseD extends ClaseA {}

    function obtenerAlgunaClase(): string
    {
        return ClaseA::class;
    }

    var_dump(new ClaseA instanceof ('std' . 'Class'));
    var_dump(new ClaseB instanceof ('Class' . 'B'));
    var_dump(new ClaseC instanceof ('Class' . 'A'));
    var_dump(new ClaseD instanceof (obtenerAlgunaClase()));
    ?>

Resultado del ejemplo anterior en PHP 8:

    bool(true)
    bool(true)
    bool(false)
    bool(true)

El operador `instanceof` tiene una variante funcional con la función is_a().

### Ver también

- get_class()
- is_a()

## Operadores funcionales

PHP 8.5 y versiones posteriores admiten un operador que funciona directamente con callables. El operador `|>`, o “pipe”, acepta un callable de un solo parámetro en el lado derecho y le pasa el valor del lado izquierdo, evaluando el resultado del callable. El callable en el lado derecho puede ser cualquier callable válido en PHP: una Closure, un callable de primera clase, un objeto que implemente __invoke(), etc.

Esto significa que las siguientes dos líneas son lógicamente equivalentes.

Ejemplo #1 Usando `|>`

    <?php
    $result = "Hola Mundo" |> strlen(...);
    echo $result, PHP_EOL;

    $result = strlen("Hola Mundo");
    echo $result, PHP_EOL;
    ?>

El ejemplo anterior mostrará:

    10
    10

Para una única llamada, no resulta especialmente útil. Se vuelve útil cuando se encadenan múltiples llamadas. Es decir, los siguientes dos fragmentos de código son lógicamente equivalentes:

Ejemplo #2 Encadenando llamadas |>

    <?php
    $result = "PHP Rocks"
        |> htmlentities(...)
        |> str_split(...)
        |> (fn($x) => array_map(strtoupper(...), $x))
        |> (fn($x) => array_filter($x, fn($v) => $v != 'O'))
    ;
    print_r($result);

    $temp = "PHP Rocks";
    $temp = htmlentities($temp);
    $temp = str_split($temp);
    $temp = array_map(strtoupper(...), $temp);
    $temp = array_filter($temp, fn($v) => $v != 'O');
    $result = $temp;
    print_r($result);
    ?>

El ejemplo anterior mostrará:

    Array
    (
        [0] => P
        [1] => H
        [2] => P
        [3] =>
        [4] => R
        [6] => C
        [7] => K
        [8] => S
    )
    Array
    (
        [0] => P
        [1] => H
        [2] => P
        [3] =>
        [4] => R
        [6] => C
        [7] => K
        [8] => S
    )

El lado izquierdo del operador pipe puede ser cualquier valor o expresión. El lado derecho puede ser cualquier callable válido en PHP que acepte un solo parámetro, o cualquier expresión que se evalúe como tal. Las funciones que requieren más de un parámetro no están permitidas y fallarán como si se llamaran normalmente con argumentos insuficientes. Las funciones que reciben variables por referencia tampoco están permitidas. Si el lado derecho no se evalúa como un callable válido, se lanzará un error.

> Nota:

> Tenga en cuenta que, para evitar ambigüedades de sintaxis, las funciones de flecha DEBEN estar entre paréntesis cuando se utilicen con el operador pipe, como en los ejemplos anteriores. No hacerlo provocará un error fatal.

### Ver también

- Closure

# Estructuras de Control

## Tabla de contenidos

- Introducción
- if
- else
- elseif/else if
- Sintaxis alternativa
- while
- do-while
- for
- foreach
- break
- continue
- switch
- match
- declare
- return
- require
- include
- require_once
- include_once
- goto

## Introducción

Todo script PHP está construido según una serie de sentencias. Una sentencia puede ser una asignación, una llamada de función, un ciclo, una sentencia condicional o incluso una sentencia que no hace nada (una sentencia vacía). Las sentencias generalmente finalizan con un punto y coma. Adicionalmente, las sentencias pueden agruparse en un conjunto de sentencias, encapsulándolas entre corchetes. Un grupo de sentencias es una sentencia por sí misma también. Los diferentes tipos de sentencias son descritos en este capítulo.

### Ver también

Lo siguiente también se considera como construcciones de lenguaje, aunque se hace referencia a ellas bajo funciones en el manual.

- list()
- array()
- echo
- eval()
- print

## if

(PHP 4, PHP 5, PHP 7, PHP 8)

La instrucción `if` es una de las más importantes instrucciones de todos los lenguajes, PHP incluido. Permite la ejecución condicional de una parte de código. Las funcionalidades de la instrucción `if` son las mismas en PHP que en C :

    if (expression)
      commandes

Como se ha visto en el párrafo dedicado a las expressions, expression es convertida en su valor booléen. Si la expression vale `true`, PHP ejecutará la instruction y si vale `false`, la instrucción será ignorada. Más detalles sobre los valores que valen `false` están disponibles en la sección Conversión en booléen.

El siguiente ejemplo muestra la frase a es más grande que b si $a es más grande que $b :

    <?php
    if ($a > $b)
      echo "a es más grande que b";
    ?>

A menudo, se desea que varias instrucciones sean ejecutadas después de un desvío condicional. Por supuesto, no es obligatorio repetir la instrucción condicional `if` tantas veces como instrucciones se tengan que ejecutar. En su lugar, se pueden agrupar todas las instrucciones en un bloque. El siguiente ejemplo muestra a es más grande que b, si $a es más grande que $b, y luego asigna el valor de $a a la variable $b :

    <?php
    if ($a > $b) {
      echo "a es más grande que b";
      $b = $a;
    }
    ?>

Se pueden anidar indefinidamente instrucciones `if` dentro de otras instrucciones `if`, lo que permite una gran flexibilidad en la ejecución de una parte de código según un gran número de condiciones.

## else

(PHP 4, PHP 5, PHP 7, PHP 8)

A menudo, se desea ejecutar una sentencia si una condición se cumple y otra sentencia si esta condición no se cumple. Para esto se utiliza `else`. `else` funciona después de un `if` y ejecuta las sentencias correspondientes en caso de que la expresión del `if` sea `false`. En el siguiente ejemplo, este fragmento de código muestra a es más grande que b si la variable $a es más grande que la variable $b, y a es más pequeño que b en caso contrario:

    <?php
    if ($a > $b) {
      echo "a es más grande que b";
    } else {
      echo "a es más pequeño que b";
    }
    ?>

Las sentencias después del `else` solo se ejecutan si la expresión del `if` es `false`, y si existen expresiones `elseif` - solo si también se evalúan como `false` (ver elseif).

> Nota: Dangling else

> En el caso de sentencias `if`-`else` anidadas, un `else` siempre se asocia con el `if` más cercano.

>     <?php
>     $a = false;
>     $b = true;
>     if ($a)
>         if ($b)
>             echo "b";
>     else
>         echo "c";
>     ?>

> A pesar de la indentación (que no tiene importancia en PHP), el `else` se asocia con el `if ($b)`, por lo que este ejemplo no produce ninguna salida. Aunque apoyarse en este comportamiento es válido, se recomienda evitarlo utilizando llaves para resolver cualquier posible ambigüedad.

## elseif/else if

(PHP 4, PHP 5, PHP 7, PHP 8)

`elseif`, como su nombre indica, es una combinación de `if` y de `else`. Como la expresión `else`, permite ejecutar una instrucción después de un `if` en el caso de que el "primer" `if` sea evaluado como `false`. Sin embargo, a diferencia de la expresión `else`, solo ejecutará la instrucción si la expresión condicional `elseif` es evaluada como `true`. El siguiente ejemplo mostrará a es más grande que b, a es igual a b o a es más pequeño que b :

    <?php
    if ($a > $b) {
        echo "a es más grande que b";
    } elseif ($a == $b) {
        echo "a es igual a b";
    } else {
        echo "a es más pequeño que b";
    }
    ?>

Es posible tener varios `elseif` que se sigan unos a otros, después de un `if` inicial. El primer `elseif` que sea evaluado como `true` será ejecutado. En PHP, es posible escribir `else if` en dos palabras y su comportamiento será idéntico al de `elseif` (en una sola palabra). La semántica de las dos expresiones es ligeramente diferente (al igual que en C), pero al final, el resultado será exactamente el mismo.

La expresión `elseif` es ejecutada solo si el `if` anterior y cualquier otro `elseif` anterior son evaluados como `false`, y que su `elseif` es evaluado como `true`.

> Nota: Téngase en cuenta que `elseif` y `else if` son tratados de la misma manera solo cuando se utilizan llaves, como en el ejemplo anterior. Cuando se utiliza ":" para definir sus condiciones `if`/`elseif`, el uso de `elseif` en una sola palabra se vuelve necesario. PHP fallará con un error de análisis si se utiliza `else if`.

    <?php

    /* Mala práctica: */
    if ($a > $b):
        echo $a." es más grande que ".$b;
    else if ($a == $b): // no compilará
        echo "La línea anterior provoca un error de interpretación";
    endif;

    <?php

    /* Buena práctica: */
    if ($a > $b):
        echo $a." es más grande que ".$b;
    elseif ($a == $b): // Las dos palabras están unidas
        echo $a." igual ".$b;
    else:
        echo $a." es más grande o igual a ".$b;
    endif;

    ?>

## Sintaxis alternativa

(PHP 4, PHP 5, PHP 7, PHP 8)

PHP ofrece otra manera de agrupar instrucciones dentro de un bloque, para las funciones de control `if`, `while`, `for`, `foreach` y `switch`. En cada caso, el principio es reemplazar la llave de apertura por dos puntos (:) y la llave de cierre por, respectivamente, `endif;`, `endwhile;`, `endfor;`, `endforeach;`, o `endswitch;`.

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

En el ejemplo anterior, el bloque HTML "A igual 5" se incluye dentro de un `if` utilizando esta nueva sintaxis. Este código HTML solo se mostrará si la variable $a es igual a 5.

Esta otra sintaxis también funciona con `else` y `elseif`. El siguiente ejemplo muestra una estructura con un `if`, un `elseif` y un `else` utilizando esta otra sintaxis:

    <?php
    if ($a == 5):
        echo "a igual 5";
        echo "...";
    elseif ($a == 6):
        echo "a igual 6";
        echo "!!!";
    else:
        echo "a no vale ni 5 ni 6";
    endif;
    ?>

> Nota:

> No se puede utilizar diferentes sintaxis en el mismo bloque de control.

Advertencia

Cualquier visualización (incluyendo espacios) entre una estructura `switch` y el primer `case` producirá un error de sintaxis. Por ejemplo, esto no es válido:

    <?php switch ($foo): ?>
        <?php case 1: ?>
        // ...
    <?php endswitch; ?>

Mientras que esto es válido, ya que la última nueva línea después de la estructura `switch` se considera parte de la etiqueta de cierre `?>` y, por lo tanto, no se muestra nada entre `switch` y `case`:

    <?php switch ($foo): ?>
    <?php case 1: ?>
        ...
    <?php endswitch; ?>

Ver también while, for, y if para otros ejemplos.

## while

(PHP 4, PHP 5, PHP 7, PHP 8)

La estructura de control `while` es la forma más simple de implementar un bucle en PHP. Esta estructura se comporta de la misma manera que en C. El ejemplo más simple de un bucle `while` es el siguiente :

    while (expression)
        comandos

El significado de un bucle `while` es muy simple. PHP ejecuta la instrucción mientras que la expresión del bucle `while` es evaluada como `true`. El valor de la expresión es verificado al inicio de cada bucle, y, si el valor cambia durante la ejecución de la instrucción, la ejecución no se detendrá hasta el final de la iteración (cada vez que PHP ejecuta la instrucción, se llama una iteración). Si la expresión del `while` es `false` antes de la primera iteración, la instrucción nunca será ejecutada.

Al igual que con el `if`, se pueden agrupar varias instrucciones en el mismo bucle `while` agrupándolas dentro de llaves o utilizando la siguiente sintaxis :

    while (expression):
        comandos
        ...
    endwhile;

Los siguientes ejemplos son idénticos y muestran todos los números de 1 hasta 10 :

    <?php
    /* ejemplo 1 */

    $i = 1;
    while ($i <= 10) {
        echo $i++;  /* El valor mostrado es $i antes del incremento
                       (post-incremento)  */
    }

    /* ejemplo 2 */

    $i = 1;
    while ($i <= 10):
        echo $i;
        $i++;
    endwhile;
    ?>

## do-while

(PHP 4, PHP 5, PHP 7, PHP 8)

Las bucles `do-while` se parecen mucho a las bucles `while`, pero la expresión es evaluada al final de cada iteración en lugar de al principio. La principal diferencia con respecto a la bucle `while` es que la primera iteración de la bucle `do-while` siempre se ejecuta (la expresión solo se evalúa al final de la iteración), lo cual no ocurre cuando se utiliza una bucle `while` (la condición se verifica al inicio de cada iteración, y si resulta `false` desde el principio, la bucle se detendrá de inmediato).

Solo existe una sintaxis posible para las bucles `do-while`:

    <?php
    $i = 0;
    do {
        echo $i;
    } while ($i > 0);
    ?>

La bucle anterior solo se ejecutará una vez, ya que cuando la expresión es evaluada, resulta `false` (ya que la variable $i no es mayor que 0) y la ejecución de la bucle se detiene.

Los usuarios familiarizados con C están acostumbrados a un uso diferente de las bucles `do-while`, que permite detener la ejecución de la bucle en medio de las instrucciones, encapsulando en un `do-while`(0) la función `break`. El siguiente código muestra un uso posible:

    <?php
    do {
        if ($i < 5) {
            echo "i no es suficientemente grande";
            break;
        }
        $i *= $factor;
        if ($i < $minimum_limit) {
            break;
        }
        echo "i es bueno";

        /* ...procesamiento de i... */

    } while (0);
    ?>

Es posible utilizar el operador `goto` en lugar de este truco.

## for

(PHP 4, PHP 5, PHP 7, PHP 8)

Las bucles `for` son las más complejas en PHP. Funcionan como las bucles for del lenguaje C(C++). La sintaxis de las bucles `for` es la siguiente :

    for (expr1; expr2; expr3)
        comandos

La primera expresión (expr1) es evaluada (ejecutada), en cualquier caso al inicio de la bucle.

Al inicio de cada iteración, la expresión expr2 es evaluada. Si la evaluación es `true`, la bucle continúa y los comandos son ejecutados. Si la evaluación es `false`, la ejecución de la bucle se detiene.

Al final de cada iteración, la expresión expr3 es evaluada (ejecutada).

Las expresiones pueden eventualmente ser dejadas vacías o pueden contener varias expresiones separadas por comas. En expr2, todas las expresiones separadas por una coma son evaluadas pero el resultado se obtiene desde la última parte. Si la expresión expr2 es dejada vacía, esto significa que es una bucle infinita (PHP considera implícitamente que vale `true`, como en C). Esto no es realmente muy útil, a menos que se desee terminar la bucle con la instrucción condicional `break` en lugar de la expresión `for`.

Considérese los siguientes ejemplos. Todos muestran los números enteros de 1 a 10 :

    <?php
    /* ejemplo 1 */

    for ($i = 1; $i <= 10; $i++) {
        echo $i;
    }

    /* ejemplo 2 */

    for ($i = 1; ; $i++) {
        if ($i > 10) {
            break;
        }
        echo $i;
    }

    /* ejemplo 3 */

    $i = 1;
    for (; ; ) {
        if ($i > 10) {
            break;
        }
        echo $i;
        $i++;
    }

    /* ejemplo 4 */

    for ($i = 1, $j = 0; $i <= 10; $j += $i, print $i, $i++);
    ?>

Por supuesto, el primer ejemplo es el más simple de todos (o quizás el cuarto), pero también se puede pensar que usar una expresión vacía en una bucle `for` puede ser útil a veces.

PHP también soporta la siguiente sintaxis alternativa para las bucles `for` :

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

Muchas personas tienen la costumbre de iterar a través de arrays, como en el ejemplo a continuación.

    <?php
    /*
     * Este es un array con datos que queremos modificar
     * a lo largo de la bucle
     */
    $people = array(
        array('name' => 'Kalle', 'salt' => 856412),
        array('name' => 'Pierre', 'salt' => 215863)
    );

    for($i = 0; $i < count($people); ++$i) {
        $people[$i]['salt'] = mt_rand(000000, 999999);
    }
    ?>

Este código puede ser lento porque debe calcular el tamaño del array en cada iteración. Dado que el tamaño nunca cambia, puede ser fácilmente optimizado utilizando una variable intermedia para almacenar el tamaño en lugar de llamar repetidamente a la función count() :

    <?php
    $people = array(
        array('name' => 'Kalle', 'salt' => 856412),
        array('name' => 'Pierre', 'salt' => 215863)
    );

    for($i = 0, $size = count($people); $i < $size; ++$i) {
        $people[$i]['salt'] = mt_rand(000000, 999999);
    }
    ?>

## foreach

(PHP 4, PHP 5, PHP 7, PHP 8)

La estructura `foreach` proporciona una forma sencilla de iterar sobre arrays y objetos Traversable. `foreach` generará un error cuando se utilice con una variable que contenga un tipo de dato diferente o con una variable no inicializada.

`foreach` puede obtener opcionalmente la `key` de cada elemento:

    foreach (iterable_expression as $value) {
        statement_list
    }

    foreach (iterable_expression as $key => $value) {
        statement_list
    }

La primera forma recorre el iterable dado por `iterable_expression`. En cada iteración, el valor del elemento actual se asigna a `$value`.

La segunda forma asignará adicionalmente la clave del elemento actual a la variable `$key` en cada iteración.

Tenga en cuenta que `foreach` no modifica el puntero interno del array, que es utilizado por funciones como current() y key().

Es posible personalizar la iteración de objetos.

Ejemplo #1 Usos comunes de `foreach`

    <?php

    /* Ejemplo: solo valor */
    $array = [1, 2, 3, 17];

    foreach ($array as $value) {
        echo "Elemento actual de \$array: $value.\n";
    }

    /* Ejemplo: clave y valor */
    $array = [
        "one" => 1,
        "two" => 2,
        "three" => 3,
        "seventeen" => 17
    ];

    foreach ($array as $key => $value) {
        echo "Clave: $key => Valor: $value\n";
    }

    /* Ejemplo: arrays multidimensionales clave-valor */
    $grid = [];
    $grid[0][0] = "a";
    $grid[0][1] = "b";
    $grid[1][0] = "y";
    $grid[1][1] = "z";

    foreach ($grid as $y => $row) {
        foreach ($row as $x => $value) {
            echo "Valor en posición x=$x y y=$y: $value\n";
        }
    }

    /* Ejemplo: arrays dinámicos */
    foreach (range(1, 5) as $value) {
        echo "$value\n";
    }
    ?>

> Nota:

> `foreach` no admite la capacidad de suprimir mensajes de error utilizando `@`.

### Desempaquetar arrays anidados

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Es posible iterar sobre un array de arrays y desempaquetar el array anidado en variables de bucle utilizando ya sea destructuración de arrays mediante `[]` o utilizando la estructura de lenguaje list() como valor.

> Nota: Tenga en cuenta que destructuración de arrays mediante `[]` solo es posible a partir de PHP 7.1.0

En ambos ejemplos siguientes, `$a` se establecerá con el primer elemento del array anidado y `$b` contendrá el segundo elemento:

    <?php
    $array = [
        [1, 2],
        [3, 4],
    ];

    foreach ($array as [$a, $b]) {
        echo "A: $a; B: $b\n";
    }

    foreach ($array as list($a, $b)) {
        echo "A: $a; B: $b\n";
    }
    ?>

El ejemplo anterior mostrará:

    A: 1; B: 2
    A: 3; B: 4

Cuando se proporcionan menos variables que elementos en el array, los elementos restantes serán ignorados. De manera similar, los elementos pueden omitirse utilizando una coma:

    <?php
    $array = [
        [1, 2, 5],
        [3, 4, 6],
    ];

    foreach ($array as [$a, $b]) {
        // Note que no hay $c aquí.
        echo "$a $b\n";
    }

    foreach ($array as [, , $c]) {
        // Omitiendo $a y $b
        echo "$c\n";
    }
    ?>

El ejemplo anterior mostrará:

    1 2
    3 4
    5
    6

Se generará un aviso si no hay suficientes elementos en el array para llenar el list():

    <?php
    $array = [
        [1, 2],
        [3, 4],
    ];

    foreach ($array as [$a, $b, $c]) {
        echo "A: $a; B: $b; C: $c\n";
    }
    ?>

El ejemplo anterior mostrará:

    Notice: Undefined offset: 2 in example.php on line 7
    A: 1; B: 2; C:

    Notice: Undefined offset: 2 in example.php on line 7
    A: 3; B: 4; C:

### foreach y referencias

Es posible modificar directamente elementos de array dentro de un bucle precediendo `$value` con `&`. En ese caso el valor será asignado por referencia.

    <?php
    $arr = [1, 2, 3, 4];
    foreach ($arr as &$value) {
        $value = $value * 2;
    }
    // $arr es ahora [2, 4, 6, 8]
    unset($value); // romper la referencia con el último elemento
    ?>

Advertencia

La referencia a un `$value` del último elemento del array permanece incluso después del bucle `foreach`. Se recomienda destruir estas referencias utilizando unset(). De lo contrario, ocurrirá el siguiente comportamiento:

    <?php
    $arr = [1, 2, 3, 4];
    foreach ($arr as &$value) {
        $value = $value * 2;
    }
    // $arr es ahora [2, 4, 6, 8]

    // sin un unset($value), $value sigue siendo una referencia al último elemento: $arr[3]

    foreach ($arr as $key => $value) {
        // $arr[3] se actualizará con cada valor de $arr...
        echo "{$key} => {$value} ";
        print_r($arr);
    }
    // ...hasta que finalmente el penúltimo valor se copie sobre el último valor
    ?>

El ejemplo anterior mostrará:

    0 => 2 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 2 )
    1 => 4 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 4 )
    2 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )
    3 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )

Ejemplo #2 Iterar los valores de un array constante por referencia

    <?php
    foreach ([1, 2, 3, 4] as &$value) {
        $value = $value * 2;
    }
    ?>

### Ver también

- array
- Traversable
- iterable
- list()

## break

(PHP 4, PHP 5, PHP 7, PHP 8)

La instrucción `break` permite salir de una estructura `for`, `foreach`, `while`, `do-while` o `switch`.

`break` acepta un argumento numérico opcional que indicará cuántas estructuras anidadas deben ser interrumpidas. El valor por omisión es `1`, solo la estructura anidada inmediata es interrumpida.

    <?php
    $arr = array('un', 'dos', 'tres', 'cuatro', 'stop', 'cinco');
    foreach ($arr as $val) {
        if ($val == 'stop') {
            break;    /* También podría utilizarse 'break 1;' aquí. */
        }
        echo "$val<br />\n";
    }

    /* Uso del argumento opcional. */

    $i = 0;
    while (++$i) {
        switch ($i) {
            case 5:
                echo "At 5<br />\n";
                break 1;  /* Termina únicamente el switch. */
            case 10:
                echo "At 10; quitting<br />\n";
                break 2;  /* Termina el switch y el ciclo while. */
            default:
                break;
        }
    }
    ?>

## continue

(PHP 4, PHP 5, PHP 7, PHP 8)

La instrucción `continue` se utiliza en un bucle para eludir las instrucciones de la iteración actual y continuar la ejecución en la condición de evaluación y, por lo tanto, comenzar la siguiente iteración.

> Nota: En PHP, la estructura switch se considera un bucle por `continue`. `continue` se comporta como `break` (cuando no se pasa ningún argumento) pero emitirá una advertencia, ya que es probable que esto sea un error. Si un `switch` se encuentra dentro de un bucle, `continue 2` continuará en la siguiente iteración del bucle externo.

`continue` acepta un argumento numérico opcional que indicará cuántas estructuras anidadas deben ser eludidas. El valor por omisión es `1`, lo que equivale a ir directamente al final del bucle actual.

    <?php
    $arr = ['zero', 'one', 'two', 'three', 'four', 'five', 'six'];
    foreach ($arr as $key => $value) {
        if (0 === ($key % 2)) { // elude los miembros pares
            continue;
        }
        echo $value . "\n";
    }
    ?>

Los ejemplos anteriores mostrarán:

    one
    three
    five

    <?php
    $i = 0;
    while ($i++ < 5) {
        echo "Outer\n";
        while (1) {
            echo "Middle\n";
            while (1) {
                echo "Inner\n";
                continue 3;
            }
            echo "This never gets output.\n";
        }
        echo "Neither does this.\n";
    }
    ?>

Los ejemplos anteriores mostrarán:

    Outer
    Middle
    Inner
    Outer
    Middle
    Inner
    Outer
    Middle
    Inner
    Outer
    Middle
    Inner
    Outer
    Middle
    Inner

Olvidar el punto y coma después de `continue` puede llevar a confusión. Aquí hay un ejemplo de lo que no se debe hacer:

    <?php
    for ($i = 0; $i < 5; ++$i) {
        if ($i == 2)
            continue
        print "$i\n";
    }
    ?>

Se puede esperar que el resultado sea:

    0
    1
    3
    4

Historial para `continue`
Versión | Descripción
--- | ---
7.3.0 | `continue` dentro de un `switch` que intenta actuar como una declaración `break` para `switch` emitirá `E_WARNING`.

## switch

(PHP 4, PHP 5, PHP 7, PHP 8)

La instrucción `switch` equivale a una serie de instrucciones `if`. En numerosas ocasiones, se necesitará comparar la misma variable (o expresión) con un gran número de valores diferentes, y ejecutar diferentes partes de código según el valor al que sea igual. Esto es exactamente para lo que sirve la instrucción `switch`.

> Nota: Téngase en cuenta que, a diferencia de otros lenguajes, la estructura continue se aplica a las estructuras `switch` y se comporta de la misma manera que `break`. Si se tiene un `switch` dentro de un bucle, y se desea continuar hasta la siguiente iteración del bucle externo, se debe utilizar `continue 2`.

> Nota:

> Téngase en cuenta que switch/case provoca una comparación amplia.

En el siguiente ejemplo, cada bloque de código es equivalente. Uno utiliza una serie de instrucciones `if` y `elseif`, y el otro una instrucción de tipo `switch`. En cada caso, la salida es la misma.

Ejemplo #1 Instrucción `switch`

    <?php
    // Este switch:

    switch ($i) {
        case 0:
            echo "i igual 0";
            break;
        case 1:
            echo "i igual 1";
            break;
        case 2:
            echo "i igual 2";
            break;
    }

    // Equivale a:

    if ($i == 0) {
        echo "i igual 0";
    } elseif ($i == 1) {
        echo "i igual 1";
    } elseif ($i == 2) {
        echo "i igual 2";
    }
    ?>

Es importante entender que la instrucción `switch` ejecuta cada una de las cláusulas en orden. La instrucción `switch` se ejecuta línea por línea. Al principio, no se ejecuta ningún código. Solo cuando se encuentra una instrucción `case` cuya expresión se evalúa a un valor que coincide con el valor de la expresión `switch`, PHP ejecuta entonces las instrucciones correspondientes. PHP continúa ejecutando las instrucciones hasta el final del bloque de instrucciones del `switch`, o bien hasta que encuentra la instrucción `break`. Si no se puede utilizar la instrucción `break` al final de la instrucción `case`, PHP continuará ejecutando todas las instrucciones que siguen. Por ejemplo :

    <?php
    switch ($i) {
        case 0:
            echo "i igual 0";
        case 1:
            echo "i igual 1";
        case 2:
            echo "i igual 2";
    }
    ?>

En este ejemplo, si $i es igual a 0, PHP ejecutará todas las instrucciones que siguen ! Si $i es igual a 1, PHP ejecutará las dos últimas instrucciones. Y solo si $i es igual a 2, se obtendrá el resultado esperado, es decir, la visualización de "i igual 2". Por lo tanto, es importante no olvidar la instrucción `break` (aunque es posible que se omita en ciertas circunstancias).

En un comando `switch`, una condición se evalúa solo una vez, y el resultado se compara con cada `case`. En una estructura `elseif`, las condiciones se evalúan en cada comparación. Si la condición es más complicada que una simple comparación, o bien forma parte de un bucle, `switch` será más rápido.

La lista de comandos de un `case` puede estar vacía, en cuyo caso PHP utilizará la lista de comandos del caso siguiente.

    <?php
    switch ($i) {
        case 0:
        case 1:
        case 2:
            echo "i es menor que 3 pero no es negativo";
            break;
        case 3:
            echo "i igual 3";
    }
    ?>

Un caso especial es `default`. Este caso se utiliza cuando todos los otros casos han fallado. Por ejemplo :

    <?php
    switch ($i) {
        case 0:
            echo "i igual 0";
            break;
        case 1:
            echo "i igual 1";
            break;
        case 2:
            echo "i igual 2";
            break;
        default:
           echo "i no es igual a 2, ni a 1, ni a 0.";
    }
    ?>

> Nota: Varios casos default generarán un error de nivel `E_COMPILE_ERROR`.

> Nota: Técnicamente, el caso `default` puede ser colocado en cualquier posición. Solo se utilizará si ningún otro caso coincide. Sin embargo, por convención, es preferible colocarlo al final.

Si ningún `case` coincide, y no hay un `default`, entonces no se ejecutará ningún código, al igual que si ninguna instrucción `if` fuera verdadera.

Un valor de `case` puede ser dado en forma de expresión. Sin embargo, esta expresión será evaluada sola, y luego comparada de manera aproximada con el valor del `switch`. Esto significa que no puede ser utilizada para evaluaciones complejas del valor del `switch`. Por ejemplo :

    <?php
    $target = 1;
    $start = 3;

    switch ($target) {
        case $start - 1:
            print "A";
            break;
        case $start - 2:
            print "B";
            break;
        case $start - 3:
            print "C";
            break;
        case $start - 4:
            print "D";
            break;
    }

    // Muestra "B"
    ?>

Para comparaciones más complejas, el valor `true` puede ser utilizado como valor de switch. O, alternativamente, bloques `if`-`else` en lugar de `switch`.

    <?php
    $offset = 1;
    $start = 3;

    switch (true) {
        case $start - $offset === 1:
            print "A";
            break;
        case $start - $offset === 2:
            print "B";
            break;
        case $start - $offset === 3:
            print "C";
            break;
        case $start - $offset === 4:
            print "D";
            break;
    }

    // Muestra "B"
    ?>

La sintaxis alternativa para esta estructura de control es la siguiente : (para más información, ver sintaxis alternativas).

    <?php
    switch ($i):
        case 0:
            echo "i igual 0";
            break;
        case 1:
            echo "i igual 1";
            break;
        case 2:
            echo "i igual 2";
            break;
        default:
            echo "i no es igual a 2, ni a 1, ni a 0";
    endswitch;
    ?>

Es posible utilizar un punto y coma en lugar de dos puntos después de un case, como sigue :

    <?php
    switch($beer)
    {
        case 'leffe';
        case 'grimbergen';
        case 'guinness';
            echo 'Buena elección';
            break;
        default;
            echo 'Por favor, haga una elección...';
            break;
    }
    ?>

### Ver también

- match

## match

(PHP 8)

La expresión `match` permite realizar una evaluación basada en el control de identidad de un valor. De manera similar a una instrucción `switch`, una expresión `match` tiene una expresión sujeto que es comparada con varias alternativas. A diferencia de `switch`, se evalúa a un valor, como las expresiones ternarias. A diferencia de `switch`, la comparación es una verificación de identidad (`===`) en lugar de un control de igualdad débil (`==`). Las expresiones Match están disponibles a partir de PHP 8.0.0.

Ejemplo #1 Estructura de una expresión `match`

    <?php
    $return_value = match (subject_expression) {
        single_conditional_expression => return_expression,
        conditional_expression1, conditional_expression2 => return_expression,
    };
    ?>

Ejemplo #2 Uso básico de las expresiones `match`

    <?php
    $food = 'cake';

    $return_value = match ($food) {
        'apple' => 'This food is an apple',
        'bar' => 'This food is a bar',
        'cake' => 'This food is a cake',
    };

    var_dump($return_value);
    ?>

El ejemplo anterior mostrará:

    string(19) "This food is a cake"

Ejemplo #3 Ejemplo de uso de `match` con operadores de comparación

    <?php
    $age = 18;

    $output = match (true) {
        $age < 2 => "Bebé",
        $age < 13 => "Niño",
        $age <= 19 => "Adolescente",
        $age >= 40 => "Adulto",
        $age > 19 => "Adulto joven",
    };

    var_dump($output);
    ?>

El ejemplo anterior mostrará:

    string(12) "Adolescente"

> Nota: El resultado de una expresión `match` no necesita ser utilizado.

> Nota: Cuando una expresión `match` se utiliza como una expresión autónoma, debe ser terminada por un punto y coma `;`.

La expresión `match` es similar a una instrucción `switch` pero presenta algunas diferencias esenciales:

- Una expresión `match` compara los valores de manera estricta (`===`) y no de manera débil como lo hace la instrucción switch.
- Una expresión `match` devuelve un valor.
- Las expresiones `match` no pasan a los casos siguientes como lo hacen las instrucciones `switch`.
- Una expresión `match` debe ser exhaustiva.

Al igual que las instrucciones `switch`, las expresiones `match` se ejecutan brazo por brazo. Al principio, ningún código se ejecuta. Las expresiones condicionales solo se evalúan si todas las expresiones condicionales anteriores no coinciden con la expresión del sujeto. Solo la expresión de retorno correspondiente a la expresión condicional correspondiente será evaluada. Por ejemplo:

    <?php
    $result = match ($x) {
        foo() => 'value',
        $this->bar() => 'value', // $this->bar() no es llamado si foo() === $x
        $this->baz => beep(), // beep() no es llamado a menos que $x === $this->baz
        // etc.
    };
    ?>

Los brazos de la expresión de `match` pueden contener múltiples expresiones separadas por una coma. Se trata de un OU lógico y de una abreviación para múltiples brazos que utilizan la misma expresión como resultado.

    <?php
    $result = match ($x) {
        // Este brazo
        $a, $b, $c => 5,
        // Es equivalente a estos tres brazos:
        $a => 5,
        $b => 5,
        $c => 5,
    };
    ?>

El patrón `default` es un caso particular. Este patrón coincide con todo lo que no ha sido buscado previamente. Por ejemplo:

    <?php
    $expressionResult = match ($condition) {
        1, 2 => foo(),
        3, 4 => bar(),
        default => baz(),
    };
    ?>

> Nota: El uso de múltiples patrones por defecto provocará un error `E_FATAL_ERROR`.

Una expresión `match` debe ser exhaustiva. Si la expresión no es tratada por ningún brazo de `match`, se lanza un error UnhandledMatchError.

Ejemplo #4 Ejemplo de una expresión match no manejada

    <?php
    $condition = 5;

    try {
        match ($condition) {
            1, 2 => foo(),
            3, 4 => bar(),
        };
    } catch (\UnhandledMatchError $e) {
        var_dump($e);
    }
    ?>

El ejemplo anterior mostrará:

    object(UnhandledMatchError)#1 (7) {
      ["message":protected]=>
      string(33) "Unhandled match value of type int"
      ["string":"Error":private]=>
      string(0) ""
      ["code":protected]=>
      int(0)
      ["file":protected]=>
      string(9) "/in/ICgGK"
      ["line":protected]=>
      int(6)
      ["trace":"Error":private]=>
      array(0) {
      }
      ["previous":"Error":private]=>
      NULL
    }

### Uso de expresiones match para manejar controles de no identidad

Es posible utilizar una expresión `match` para tratar los casos condicionales de no identidad utilizando `true` como expresión sujeto.

Ejemplo #5 Uso de una expresión match generalizada para realizar ramificaciones sobre rangos de enteros

    <?php

    $age = 23;

    $result = match (true) {
        $age >= 65 => 'senior',
        $age >= 25 => 'adult',
        $age >= 18 => 'young adult',
        default => 'kid',
    };

    var_dump($result);
    ?>

El ejemplo anterior mostrará:

    string(11) "young adult"

Ejemplo #6 Uso de una expresión match generalizada para realizar ramificaciones sobre el contenido de una cadena de caracteres

    <?php

    $text = 'Bienvenidos a nuestra casa';

    $result = match (true) {
        str_contains($text, 'Welcome'), str_contains($text, 'Hello') => 'en',
        str_contains($text, 'Bienvenidos'), str_contains($text, 'Hola') => 'es',
        // ...
    };

    var_dump($result);
    ?>

El ejemplo anterior mostrará:

    string(2) "es"

## declare

(PHP 4, PHP 5, PHP 7, PHP 8)

El elemento de lenguaje `declare` se utiliza para añadir directivas de ejecución en un bloque de código. La sintaxis de `declare` es similar a la sintaxis de otras funciones de control:

    declare (directive)
        comandos

La expresión `directive` permite controlar la intervención del bloque `declare`. Actualmente, solo tres directivas son reconocidas:

- `ticks`
- `encoding`
- `strict_types`

Como las directivas son gestionadas durante la compilación del fichero, solo los literales pueden ser utilizados como valor de estas directivas. Las variables y constantes no pueden ser utilizadas. Para ilustrar:

    <?php
    // Esto es correcto:
    declare(ticks=1);

    // Esto es incorrecto:
    const TICK_VALUE = 1;
    declare(ticks=TICK_VALUE);
    ?>

La expresión `comandos` del bloque de `declare` será ejecutada. Cómo será ejecutada, y qué efectos tendrá, depende de la directiva utilizada en el bloque `directive`.

La estructura `declare` puede también ser utilizada en el contexto global. Afecta entonces a todo el código que la sigue (incluso si el fichero con `declare` ha sido incluido después, no afecta al fichero padre).

    <?php
    // Estas declaraciones son idénticas.

    // Se puede utilizar esto
    declare(ticks=1) {
        // script entero aquí
    }

    // o esto
    declare(ticks=1);
    // script entero aquí
    ?>

### Ticks

Un tick es un evento que interviene cada N comandos de bajo nivel tickables, ejecutados por el analizador en el bloque de `declare`. El valor de N es especificado por la sintaxis `ticks=N` en la sección `directive` del bloque `declare`.

No todos los comandos son tickables. Típicamente, las expresiones de condición y las expresiones de argumentos no son tickables.

Un evento que interviene en cada tick es especificado con la función register_tick_function(). Consulte el ejemplo a continuación para más detalles. Tenga en cuenta que más de un evento puede intervenir por tick.

Ejemplo #1 Ejemplo de uso de ticks

    <?php

    declare(ticks=1);

    // Una función llamada en cada evento tick
    function tick_handler()
    {
        echo "tick_handler() llamado\n";
    }

    register_tick_function('tick_handler'); // causa un evento tick

    $a = 1; // causa un evento tick

    if ($a > 0) {
        $a += 2; // causa un evento tick
        print $a; // causa un evento tick
    }

    ?>

Ver también register_tick_function() y unregister_tick_function().

### La codificación

La codificación de un script puede ser especificada por script utilizando la directiva `encoding`.

Ejemplo #2 Declaración de una codificación para un script

    <?php
    declare(encoding='ISO-8859-1');
    // el código
    ?>

Precaución

Combinada con los espacios de nombres, la única sintaxis válida para declare es `declare(encoding='...');` donde `...` es el valor de la codificación. `declare(encoding='...') {}` generará un error de interpretación en el caso de los espacios de nombres.

Ver también zend.script_encoding.

## return

(PHP 4, PHP 5, PHP 7, PHP 8)

`return` devuelve el control del programa al módulo llamante. La ejecución se reanuda entonces en la instrucción siguiente a la invocación del módulo.

Si se llama desde una función, el comando `return` termina inmediatamente la función y devuelve el argumento que se le pasa. `return` también interrumpe la ejecución del comando eval() o de scripts.

Si se llama desde el entorno global, la ejecución del script se interrumpe. Si el script actual fue incluido con la estructura include o require, entonces el control se devuelve al script llamante. Además, si el fichero del script actual ha sido incluido a través de la instrucción include, entonces el valor dado a `return` será devuelto como resultado de la llamada include. Si `return` es llamada desde el script principal, entonces la ejecución del script se detiene. Si el script actual es auto_prepend_file o auto_append_file en el fichero php.ini, entonces la ejecución del script se detiene.

Para más información, véase devolver valores.

> Nota: Tenga en cuenta que ya que `return` es una estructura de lenguaje, y no una función, los paréntesis que rodean los argumentos no son necesarios y su uso está desaconsejado.

> Nota: Si no se proporciona ningún parámetro, entonces los paréntesis deben ser omitidos y `null` será devuelto. La llamada de `return` con paréntesis pero sin argumento resultará en una alerta de análisis.

A partir de PHP 7.1.0, las declaraciones de retorno sin argumento en la función generan un `E_COMPILE_ERROR`, excepto si el tipo de retorno es void, en cuyo caso las declaraciones de retorno con un argumento generan este error.

## require

(PHP 4, PHP 5, PHP 7, PHP 8)

`require` es idéntico a include excepto por el hecho de que cuando ocurre un error, produce también una excepción Error (error de nivel `E_COMPILE_ERROR` antes de PHP 8.0.0), mientras que include solo producirá una advertencia (error de nivel `E_WARNING`).

Consulte la documentación de la instrucción include para conocer su funcionamiento.

## include

(PHP 4, PHP 5, PHP 7, PHP 8)

La expresión de lenguaje `include` incluye y ejecuta el fichero especificado en argumento.

Esta documentación también se aplica a la instrucción de lenguaje require.

Los ficheros se incluyen siguiendo la ruta del fichero proporcionada; si no se proporciona ninguna, se verificará el include_path. Si el fichero no se encuentra en el include_path, `include` verificará en el directorio del script llamador y en el directorio de trabajo actual antes de fallar. La instrucción `include` emitirá `E_WARNING` si no puede encontrar el fichero; este comportamiento es diferente de require, que emitirá `E_ERROR`.

Tenga en cuenta que `include` y `require` lanzarán errores de tipo `E_WARNING`, si el fichero no es accesible, antes de lanzar un error de tipo `E_WARNING` o `E_ERROR`, respectivamente.

Si se define una ruta, absoluta (comenzando con una letra de unidad seguida de `\` para Windows, o `/` para Unix/Linux) o relativa (comenzando con `.` o `..`), el include_path será ignorado. Por ejemplo, si un nombre de fichero comienza con `../`, PHP buscará en el directorio padre para encontrar el fichero especificado.

Para más información sobre cómo PHP maneja los ficheros incluidos así como la ruta de inclusión, consulte la documentación relativa al include_path.

Cuando un fichero es incluido, el código que lo compone hereda el ámbito de las variables de la línea donde aparece la inclusión. Todas las variables disponibles en esa línea en el fichero llamador estarán disponibles en el fichero llamado, a partir de ese punto. Sin embargo, todas las funciones y clases definidas en el fichero incluido tienen un ámbito global.

Ejemplo #1 Ejemplo con `include`

    vars.php
    <?php

    $color = 'verde';
    $fruit = 'manzana';

    ?>

    test.php
    <?php

    echo "Una $fruit $color"; // Una

    include 'vars.php';

    echo "Una $fruit $color"; // Una manzana verde

    ?>

Si la inclusión ocurre dentro de una función, el código incluido será considerado como parte de la función. Esto modifica el contexto de las variables accesibles. Una excepción a esta regla: las constantes mágicas son analizadas por el analizador antes de que la inclusión ocurra.

Ejemplo #2 Inclusión de ficheros dentro de una función

    <?php

    function foo()
    {
        global $couleur;

        include 'vars.php';

        echo "Una $fruit $couleur";
    }

    /* vars.php está en el contexto de foo()
     * por lo tanto $fruit no está disponible fuera de
     * esta función. $couleur sí lo está, ya que es
     * una variable global */

    foo();                      // Una pomme verte
    echo "Una $fruit $couleur"; // Una  verte

    ?>

Es importante señalar que cuando un fichero es incluido, los errores de análisis aparecerán en HTML al principio del fichero, y el análisis del fichero padre no será interrumpido. Por esta razón, el código que está en el fichero debe ser colocado entre las etiquetas habituales de PHP.

Si los gestores de inclusión de URL están activados en PHP, puede localizar el fichero con una URL (vía HTTP o bien con un gestor adecuado: ver Protocolos y Envolturas soportados para una lista de protocolos), en lugar de una simple ruta local. Si el servidor remoto interpreta el fichero como código PHP, variables pueden ser transmitidas al servidor remoto vía la URL y el método GET. Esto no es, estrictamente hablando, lo mismo que heredar el contexto de variable. El fichero incluido es en realidad un script ejecutado a distancia, y su resultado es incluido en el código actual.

Ejemplo #3 Utilizar la instrucción `include` vía HTTP

    <?php

    /* Este ejemplo supone que www.example.com está configurado para tratar
     * los ficheros .php y no los ficheros .txt. Además,
     * 'Work' significa aquí que las variables
     * $foo y $bar están disponibles en el fichero incluido
     */

    // No funciona: file.txt no ha sido tratado por www.example.com como PHP
    include 'http://www.example.com/file.txt?foo=1&bar=2';

    // No funciona: el script busca un fichero llamado
    // 'file.php?foo=1&bar=2' en el sistema local
    include 'file.php?foo=1&bar=2';

    // Funciona
    include 'http://www.example.com/file.php?foo=1&bar=2';
    ?>

Advertencia

# Alerta de seguridad

Un fichero remoto puede ser tratado en el servidor remoto (dependiendo de la extensión del fichero y si el servidor remoto ejecuta PHP o no) pero debe producir siempre un script PHP válido porque será tratado en el servidor local. Si el fichero del servidor remoto debe ser tratado en el lugar y mostrado solamente, readfile() es una función mucho más apropiada. De otra manera, debería tener cuidado de asegurar el script remoto para que produzca un código válido y deseado.

Ver también trabajar con ficheros remotos, fopen() y file() para información relacionada.

Manejo del retorno: `include` devuelve `FALSE` en caso de error y emite un aviso. Las inclusiones exitosas, incluyendo si son sobrescritas por el fichero incluido, devuelven `1`. Es posible ejecutar la estructura de lenguaje return dentro de un fichero incluido para determinar el proceso en ese fichero, y volver al script que lo llamó. Además, es posible devolver valores desde ficheros incluidos. Puede tomar el valor desde la llamada al fichero incluido como desee desde una función normal. Esto no es posible, sin embargo, al incluir ficheros remotos, y esto, mientras la salida del fichero remoto no tenga etiquetas PHP de inicio y fin válidas (al igual que para los ficheros locales). Puede declarar las variables necesarias dentro de estas etiquetas y serán introducidas en el lugar donde el fichero fue incluido.

Como `include` es una estructura de lenguaje particular, los paréntesis no son necesarios alrededor del argumento. Tenga cuidado al comparar el valor devuelto.

Ejemplo #4 Comparación del valor devuelto de una inclusión

    <?php
    // No funciona, evaluado como include(('vars.php') == TRUE), es decir include('1')
    if (include('vars.php') == TRUE) {
        echo 'OK';
    }

    // Funciona
    if ((include 'vars.php') == TRUE) {
        echo 'OK';
    }
    ?>

Ejemplo #5 `include` y return

    return.php
    <?php

    $var = 'PHP';

    return $var;

    ?>

    noreturn.php
    <?php

    $var = 'PHP';

    ?>

    testreturns.php
    <?php

    $foo = include 'return.php';

    echo $foo; // muestra 'PHP'

    $bar = include 'noreturn.php';

    echo $bar; // muestra 1

    ?>

`$bar` tiene el valor de `1` ya que la inclusión fue exitosa. Tenga en cuenta la diferencia entre los dos ejemplos anteriores. El primero utiliza el comando return en el fichero incluido, mientras que el segundo no lo hace. Si el fichero no puede ser incluido, `false` es devuelto y un error de nivel `E_WARNING` es enviado.

Si hay funciones definidas en el fichero incluido, pueden ser utilizadas en el fichero principal si están antes del return o después. Si el fichero es incluido dos veces, PHP emitirá un error fatal ya que las funciones ya han sido declaradas. Se recomienda utilizar include_once en lugar de verificar si el fichero ya ha sido incluido y por lo tanto devolver condicionalmente la inclusión del fichero.

Otra forma de incluir un fichero PHP en una variable es capturar la salida utilizando las funciones de control de salida con `include`. Por ejemplo:

Ejemplo #6 Uso del buffer de salida para incluir un fichero PHP en una cadena

    <?php
    $string = get_include_contents('somefile.php');

    function get_include_contents($filename) {
        if (is_file($filename)) {
            ob_start();
            include $filename;
            return ob_get_clean();
        }
        return false;
    }

    ?>

Para incluir automáticamente ficheros en sus scripts, vea también las opciones de configuración auto_prepend_file y auto_append_file del php.ini.

> Nota: Como esto es una estructura del lenguaje, y no una función, no es posible llamarla con las funciones variables o argumentos nombrados.

Ver también require, require_once, include_once, get_included_files(), readfile(), virtual(), y include_path.

## require_once

(PHP 4, PHP 5, PHP 7, PHP 8)

La expresión `require_once` es idéntica a require salvo que PHP verifica si el fichero ya ha sido incluido, y si es el caso, no lo incluye una segunda vez.

Ver la documentación de include_once para más información sobre el comportamiento de `_once`, y lo que lo diferencia de las instrucciones sin `_once`.

## include_once

(PHP 4, PHP 5, PHP 7, PHP 8)

La expresión `include_once` incluye y evalúa el fichero especificado durante la ejecución del script. El comportamiento es similar a include, pero la diferencia es que si el código ya ha sido incluido, no lo será una segunda vez, y include_once devuelve `true`. Como su nombre indica, el fichero será incluido solo una vez.

La estructura `include_once` se utiliza preferentemente cuando el fichero va a ser incluido o evaluado varias veces en un script, o bien cuando se desea asegurar que solo se incluirá una vez, para evitar redefiniciones de funciones o clases.

Véase la estructura include para más detalles sobre su funcionamiento.

## goto

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Imagen proporcionada por » xkcd

El operador `goto` puede ser utilizado para continuar la ejecución del script en otro punto del programa. El destino es especificado por una etiqueta sensible a mayúsculas y minúsculas, seguida de dos puntos, y la instrucción `goto` es luego seguida de esta etiqueta. `goto` no está totalmente sin limitaciones. La etiqueta de destino debe estar en el mismo contexto y fichero, lo que significa que no es posible cambiar de método o función, ni ir a otra función. Asimismo, es imposible entrar en una estructura de bucle o un `switch`. Sin embargo, es posible salir de ellas, y el uso común es entonces utilizar `goto` como un `break`.

Ejemplo #1 Ejemplo con `goto`

    <?php

    goto a;
    echo 'Foo';

    a:
    echo 'Bar';

    ?>

El ejemplo anterior mostrará:

    Bar

Ejemplo #2 Ejemplo de bucle con `goto`

    <?php
    for ($i = 0, $j = 50; $i < 100; $i++) {
        while ($j--) {
            if ($j == 17) {
                goto end;
            }
        }
    }
    echo "i = $i";
    end:
    echo 'j hit 17';

    ?>

El ejemplo anterior mostrará:

    j hit 17

Ejemplo #3 Esto no funcionará

    <?php
    goto loop;
    for ($i = 0, $j = 50; $i < 100; $i++) {
        while ($j--) {
            loop:
        }
    }
    echo "$i = $i";

    ?>

El ejemplo anterior mostrará:

    Fatal error: 'goto' into loop or switch statement is disallowed in
    script on line 2

# Functions

## Tabla de contenidos

- User-defined functions
- Function parameters and arguments
- Returning values
- Variable functions
- Internal (built-in) functions
- Anonymous functions
- Arrow Functions
- First class callable syntax

## User-defined functions

A function is defined using the `function` keyword, a name, a list of parameters (which might be empty) separated by commas (`,`) enclosed in parentheses, followed by the body of the function enclosed in curly braces, such as the following:

Ejemplo #1 Declaring a new function named `foo`

    <?php
    function foo($arg_1, $arg_2, /* ..., */ $arg_n)
    {
        echo "Example function.\n";
        return $retval;
    }

> Nota:

> As of PHP 8.0.0, the list of parameters may have a trailing comma:

>     <?php
>     function foo($arg_1, $arg_2,) { }

Any valid PHP code may appear inside the body of a function, even other functions and class definitions.

Function names follow the same rules as other labels in PHP. A valid function name starts with a letter or underscore, followed by any number of letters, numbers, or underscores. As a regular expression, it would be expressed thus: `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`.

Sugerencia

Eche un vistazo a Guía de entorno de usuario para nombres.

Functions need not be defined before they are referenced, except when a function is conditionally defined as shown in the two examples below.

When a function is defined in a conditional manner such as the two examples shown. Its definition must be processed prior to being called.

Ejemplo #2 Conditional functions

    <?php
    $makefoo = true;

    /* We can't call foo() from here
       since it doesn't exist yet,
       but we can call bar() */
    if (function_exists('foo')) {
        foo();
    } else {
        echo "Function foo does not exist (yet).\n";
    }

    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 #3 Functions within functions

    <?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. */
    if (function_exists('bar')) {
        bar();
    }

    foo();

    /* Now we can call bar(),
       foo()'s processing has
       made it accessible. */

    bar();

All functions and classes in PHP have the global scope - they can be called outside a function even if they were defined inside and vice versa.

PHP does not support function overloading, nor is it possible to undefine or redefine previously-declared functions.

> Nota: Function names are case-insensitive for the ASCII characters `A` to `Z`, though it is usually good form to call functions as they appear in their declaration.

Both variable number of arguments and default arguments are supported in functions. See also the function references for func_num_args(), func_get_arg(), and func_get_args() for more information.

It is possible to call recursive functions in PHP.

Ejemplo #4 Recursive functions

    <?php
    function recursion($a)
    {
        if ($a < 20) {
            echo "$a\n";
            recursion($a + 1);
        }
    }

    recursion(17);

> Nota: Recursive function/method calls with over 100-200 recursion levels can smash the stack and cause a termination of the current script. Especially, infinite recursion is considered a programming error.

## Function parameters and arguments

The function parameters are declared in the function signature. Information may be passed to functions via the argument list, which is a comma-delimited list of expressions. The arguments are evaluated from left to right and the result is assigned to the parameters of the function, before the function is actually called (eager evaluation).

PHP supports passing arguments by value (the default), passing by reference, and default argument values. Variable-length argument lists and Named Arguments are also supported.

> Nota:

> As of PHP 7.3.0, it is possible to have a trailing comma in the argument list for a function calls:

>     <?php
>     $v = foo(
>         $arg_1,
>         $arg_2,
>     );

As of PHP 8.0.0, the list of function parameters may include a trailing comma, which will be ignored. That is particularly useful in cases where the list of parameters is long or contains long variable names, making it convenient to list parameters vertically.

Ejemplo #1 Function parameter list with trailing comma

    <?php
    function takes_many_args(
        $first_arg,
        $second_arg,
        $a_very_long_argument_name,
        $arg_with_default = 5,
        $again = 'a default string', // This trailing comma was not permitted before 8.0.0.
    )
    {
        // ...
    }

### Passing arguments by reference

By default, function arguments are passed by value (so that if the value of the argument within the function is changed, it does not get changed outside of the function). To allow a function to modify its arguments, they must be passed by reference.

To have an argument to a function always passed by reference, prepend an ampersand (&) to the parameter name in the function definition:

Ejemplo #2 Passing function arguments by reference

    <?php
    function add_some_extra(&$string)
    {
        $string .= 'and something extra.';
    }
    $str = 'This is a string, ';
    add_some_extra($str);
    echo $str;    // outputs 'This is a string, and something extra.'

It is an error to pass a constant expression as an argument to a parameter that expects to be passed by reference.

### Default parameter values

A function may define default values for parameters using syntax similar to assigning a variable. The default is used only when the parameter's argument is not passed. Note that passing `null` does not assign the default value.

Ejemplo #3 Use of default parameters in functions

    <?php
    function makecoffee($type = "cappuccino")
    {
        return "Making a cup of $type.\n";
    }
    echo makecoffee();
    echo makecoffee(null);
    echo makecoffee("espresso");

El ejemplo anterior mostrará:

    Making a cup of cappuccino.
    Making a cup of .
    Making a cup of espresso.

Default parameter values may be scalar values, arrays, the special type `null`, and as of PHP 8.1.0, objects using the new ClassName() syntax.

Ejemplo #4 Using non-scalar types as default values

    <?php
    function makecoffee($types = array("cappuccino"), $coffeeMaker = NULL)
    {
        $device = is_null($coffeeMaker) ? "hands" : $coffeeMaker;
        return "Making a cup of ".join(", ", $types)." with $device.\n";
    }
    echo makecoffee();
    echo makecoffee(array("cappuccino", "lavazza"), "teapot");

El ejemplo anterior mostrará:

    Making a cup of cappuccino with hands.
    Making a cup of cappuccino, lavazza with teapot.

Ejemplo #5 Using objects as default values (as of PHP 8.1.0)

    <?php
    class DefaultCoffeeMaker {
        public function brew() {
            return "Making coffee.\n";
        }
    }
    class FancyCoffeeMaker {
        public function brew() {
            return "Crafting a beautiful coffee just for you.\n";
        }
    }
    function makecoffee($coffeeMaker = new DefaultCoffeeMaker)
    {
        return $coffeeMaker->brew();
    }
    echo makecoffee();
    echo makecoffee(new FancyCoffeeMaker);

El ejemplo anterior mostrará:

    Making coffee.
    Crafting a beautiful coffee just for you.

The default value must be a constant expression, not (for example) a variable, a class member or a function call.

Note that any optional parameters should be specified after any required parameters, otherwise they cannot be omitted from calls. Consider the following example:

Ejemplo #6 Incorrect usage of default function parameters

    <?php
    function makeyogurt($container = "bowl", $flavour)
    {
        return "Making a $container of $flavour yogurt.\n";
    }

    echo makeyogurt("raspberry"); // "raspberry" is $container, not $flavour

El ejemplo anterior mostrará:

    Deprecated: makeyogurt(): Optional parameter $container declared before required parameter $flavour is implicitly treated as a required parameter in script on line 2

    Fatal error: Uncaught ArgumentCountError: Too few arguments to function makeyogurt(), 1 passed in script on line 7 and exactly 2 expected in script:2
    Stack trace:
    #0 script(7): makeyogurt('raspberry')
    #1 {main}
      thrown in script on line 2

Now, compare the above with this:

Ejemplo #7 Correct usage of default function parameters

    <?php
    function makeyogurt($flavour, $container = "bowl")
    {
        return "Making a $container of $flavour yogurt.\n";
    }

    echo makeyogurt("raspberry"); // "raspberry" is $flavour

El ejemplo anterior mostrará:

    Making a bowl of raspberry yogurt.

As of PHP 8.0.0, named arguments can be used to skip over multiple optional parameters.

Ejemplo #8 Correct usage of default function parameters

    <?php
    function makeyogurt($container = "bowl", $flavour = "raspberry", $style = "Greek")
    {
        return "Making a $container of $flavour $style yogurt.\n";
    }

    echo makeyogurt(style: "natural");

El ejemplo anterior mostrará:

    Making a bowl of raspberry natural yogurt.

As of PHP 8.0.0, declaring mandatory parameters after optional parameters is deprecated. This can generally be resolved by dropping the default value, since it will never be used. One exception to this rule are parameters of the form `Type $param = null`, where the `null` default makes the type implicitly nullable. This usage is deprecated as of PHP 8.4.0, and an explicit nullable type should be used instead.

Ejemplo #9 Declaring optional parameters after mandatory parameters

    <?php
    function foo($a = [], $b) {}     // Default not used; deprecated as of PHP 8.0.0
    function foo($a, $b) {}          // Functionally equivalent, no deprecation notice

    function bar(A $a = null, $b) {} // As of PHP 8.1.0, $a is implicitly required
                                     // (because it comes before the required one),
                                     // but implicitly nullable (deprecated as of PHP 8.4.0),
                                     // because the default parameter value is null
    function bar(?A $a, $b) {}       // Recommended

> Nota: As of PHP 7.1.0, omitting a parameter which does not specify a default throws an ArgumentCountError; in previous versions it raised a Warning.

> Nota: Parameters that expect the argument by reference may have a default value.

### Variable-length argument lists

PHP has support for variable-length argument lists in user-defined functions by using the `...` token.

Parameter lists may include the `...` token to denote that the function accepts a variable number of arguments. The arguments will be passed into the given variable as an array:

Ejemplo #10 Using `...` to access variable arguments

    <?php
    function sum(...$numbers) {
        $acc = 0;
        foreach ($numbers as $n) {
            $acc += $n;
        }
        return $acc;
    }

    echo sum(1, 2, 3, 4);

El ejemplo anterior mostrará:

    10

`...` can also be used when calling functions to unpack an array or Traversable variable or literal into the argument list:

Ejemplo #11 Using `...` to provide arguments

    <?php
    function add($a, $b) {
        return $a + $b;
    }

    echo add(...[1, 2])."\n";

    $a = [1, 2];
    echo add(...$a);

El ejemplo anterior mostrará:

    3
    3

You may specify normal positional parameters before the `...` token. In this case, only the trailing arguments that don't match a positional argument will be added to the array generated by `...`.

It is also possible to add a type declaration before the `...` token. If this is present, then all arguments captured by `...` must match that parameter type.

Ejemplo #12 Type declared variable arguments

    <?php
    function total_intervals($unit, DateInterval ...$intervals) {
        $time = 0;
        foreach ($intervals as $interval) {
            $time += $interval->$unit;
        }
        return $time;
    }

    $a = new DateInterval('P1D');
    $b = new DateInterval('P2D');
    echo total_intervals('d', $a, $b).' days';

    // This will fail, since null isn't a DateInterval object.
    echo total_intervals('d', null);

El ejemplo anterior mostrará:

    3 days
    Fatal error: Uncaught TypeError: total_intervals(): Argument #2 must be of type DateInterval, null given, called in script on line 15 and defined in script:2
    Stack trace:
    #0 script(15): total_intervals('d', NULL)
    #1 {main}
      thrown in script on line 2

Finally, variable arguments can also be passed by reference by prefixing the `...` with an ampersand (`&`).

### Named Arguments

PHP 8.0.0 introduced named arguments as an extension of the existing positional parameters. Named arguments allow passing arguments to a function based on the parameter name, rather than the parameter position. This makes the meaning of the argument self-documenting, makes the arguments order-independent and allows skipping default values arbitrarily.

Named arguments are passed by prefixing the value with the parameter name followed by a colon. Using reserved keywords as parameter names is allowed. The parameter name must be an identifier, specifying dynamically is not allowed.

Ejemplo #13 Named argument syntax

    <?php
    myFunction(paramName: $value);
    array_foobar(array: $value);

    // NOT supported.
    function_name($variableStoringParamName: $value);

Ejemplo #14 Positional arguments versus named arguments

    <?php
    // Using positional arguments:
    array_fill(0, 100, 50);

    // Using named arguments:
    array_fill(start_index: 0, count: 100, value: 50);

The order in which the named arguments are passed does not matter.

Ejemplo #15 Same example as above with a different order of parameters

    <?php
    array_fill(value: 50, count: 100, start_index: 0);

Named arguments can be combined with positional arguments. In this case, the named arguments must come after the positional arguments. It is also possible to specify only some of the optional arguments of a function, regardless of their order.

Ejemplo #16 Combining named arguments with positional arguments

    <?php
    htmlspecialchars($string, double_encode: false);
    // Same as
    htmlspecialchars($string, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, 'UTF-8', false);

Passing an argument to the same named parameter multiple times results in an Error exception.

Ejemplo #17 Error thrown when passing an argument to the same named parameter multiple times

    <?php
    function foo($param) { ... }

    foo(param: 1, param: 2);
    // Error: Named parameter $param overwrites previous argument

    foo(1, param: 2);
    // Error: Named parameter $param overwrites previous argument

As of PHP 8.1.0, it is possible to use named arguments after unpacking the arguments. A named argument must not override an already unpacked argument.

Ejemplo #18 Use named arguments after unpacking

    <?php
    function foo($a, $b, $c = 3, $d = 4) {
      return $a + $b + $c + $d;
    }

    var_dump(foo(...[1, 2], d: 40)); // 46
    var_dump(foo(...['b' => 2, 'a' => 1], d: 40)); // 46

    var_dump(foo(...[1, 2], b: 20)); // Fatal error. Named parameter $b overwrites previous argument

## Returning values

Values are returned by using the optional return statement. Any type may be returned, including arrays and objects. This causes the function to end its execution immediately and pass control back to the line from which it was called. See return for more information.

> Nota:

> If the return is omitted the value `null` will be returned.

### Use of return

Ejemplo #1 Use of return

    <?php
    function square($num)
    {
        return $num * $num;
    }
    echo square(4);   // outputs '16'.

A function can not return multiple values, but similar results can be obtained by returning an array.

Ejemplo #2 Returning an array to get multiple values

    <?php
    function small_numbers()
    {
        return [0, 1, 2];
    }
    // Array destructuring will collect each member of the array individually
    [$zero, $one, $two] = small_numbers();
    var_dump($zero, $one, $two);

    // Prior to 7.1.0, the only equivalent alternative is using list() construct
    list($zero, $one, $two) = small_numbers();

To return a reference from a function, use the reference operator & in both the function declaration and when assigning the returned value to a variable:

Ejemplo #3 Returning a reference from a function

    <?php
    function &returns_reference()
    {
        return $someref;
    }

    $newref =& returns_reference();

For more information on references, please check out References Explained.

## Variable functions

PHP supports the concept of variable functions. This means that if a variable name has parentheses appended to it, PHP will look for a function with the same name as whatever the variable evaluates to, and will attempt to execute it. Among other things, this can be used to implement callbacks, function tables, and so forth.

Variable functions won't work with language constructs such as echo, print, unset(), isset(), empty(), include, require and the like. Utilize wrapper functions to make use of any of these constructs as variable functions.

Ejemplo #1 Variable function example

    <?php
    function foo() {
        echo "In foo()\n";
    }

    function bar($arg = '')
    {
        echo "In bar(); argument was '$arg'.\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()

Object methods can also be called with the variable functions syntax.

Ejemplo #2 Variable method example

    <?php
    class Foo
    {
        function Variable()
        {
            $name = 'Bar';
            $this->$name(); // This calls the Bar() method
        }

        function Bar()
        {
            echo "This is Bar";
        }
    }

    $foo = new Foo();
    $funcname = "Variable";
    $foo->$funcname();  // This calls $foo->Variable()

When calling static methods, the function call is stronger than the static property operator:

Ejemplo #3 Variable method example with static properties

    <?php
    class Foo
    {
        static $variable = 'static property';
        static function Variable()
        {
            echo "Method Variable called\n";
        }
    }

    echo Foo::$variable ."\n"; // This prints 'static property'. It does need a $variable in this scope.
    $variable = "Variable";
    Foo::$variable();  // This calls $foo->Variable() reading $variable in this scope.

El ejemplo anterior mostrará:

    static property
    Method Variable called

Ejemplo #4 Complex callables

    <?php
    class Foo
    {
        static function bar()
        {
            echo "bar\n";
        }
        function baz()
        {
            echo "baz\n";
        }
    }

    $func = array("Foo", "bar");
    $func(); // prints "bar"
    $func = array(new Foo, "baz");
    $func(); // prints "baz"
    $func = "Foo::bar";
    $func(); // prints "bar"

### Ver también

- is_callable()
- call_user_func()
- function_exists()
- variable variables

## Internal (built-in) functions

PHP comes standard with many functions and constructs. There are also functions that require specific PHP extensions compiled in, otherwise fatal "undefined function" errors will appear. For example, to use image functions such as imagecreatetruecolor(), PHP must be compiled with GD support. Or, to use mysqli_connect(), PHP must be compiled with MySQLi support. There are many core functions that are included in every version of PHP, such as the string and variable functions. A call to phpinfo() or get_loaded_extensions() will show which extensions are loaded into PHP. Also note that many extensions are enabled by default and that the PHP manual is split up by extension. See the configuration, installation, and individual extension chapters, for information on how to set up PHP.

Reading and understanding a function's prototype is explained within the manual section titled how to read a function definition. It's important to realize what a function returns or if a function works directly on a passed in value. For example, str_replace() will return the modified string while usort() works on the actual passed in variable itself. Each manual page also has specific information for each function like information on function parameters, behavior changes, return values for both success and failure, and availability information. Knowing these important (yet often subtle) differences is crucial for writing correct PHP code.

> Nota: If the parameters given to a function are not what it expects, such as passing an array where a string is expected, the return value of the function is undefined. In this case it will likely return `null` but this is just a convention, and cannot be relied upon. As of PHP 8.0.0, a TypeError exception is supposed to be thrown in this case.

> Nota:

> Scalar types for built-in functions are nullable by default in coercive mode. As of PHP 8.1.0, passing `null` to an internal function parameter that is not declared nullable is discouraged and emits a deprecation notice in coercive mode to align with the behavior of user-defined functions, where scalar types need to be marked as nullable explicitly.

> For example, strlen() function expects the parameter `$string` to be a non-nullable string. For historical reasons, PHP allows passing `null` for this parameter in coercive mode, and the parameter is implicitly cast to string, resulting in a `""` value. In contrast, a TypeError is emitted in strict mode.

>     <?php
>     var_dump(strlen(null));
>     // "Deprecated: Passing null to parameter #1 ($string) of type string is deprecated" as of PHP 8.1.0
>     // int(0)

>     var_dump(str_contains("foobar", null));
>     // "Deprecated: Passing null to parameter #2 ($needle) of type string is deprecated" as of PHP 8.1.0
>     // bool(true)

### Ver también

- function_exists()
- the function reference
- get_extension_funcs()
- dl()

## Anonymous functions

Anonymous functions, also known as `closures`, allow the creation of functions which have no specified name. They are most useful as the value of callable parameters, but they have many other uses.

Anonymous functions are implemented using the Closure class.

Ejemplo #1 Anonymous function example

    <?php
    echo preg_replace_callback('~-([a-z])~', function ($match) {
        return strtoupper($match[1]);
    }, 'hello-world');
    // outputs helloWorld

Closures can also be used as the values of variables; PHP automatically converts such expressions into instances of the Closure internal class. Assigning a closure to a variable uses the same syntax as any other assignment, including the trailing semicolon:

Ejemplo #2 Anonymous function variable assignment example

    <?php
    $greet = function($name) {
        printf("Hello %s\r\n", $name);
    };

    $greet('World');
    $greet('PHP');

Closures may also inherit variables from the parent scope. Any such variables must be passed to the `use` language construct. As of PHP 7.1, these variables must not include superglobals, $this, or variables with the same name as a parameter. A return type declaration of the function has to be placed after the `use` clause.

Ejemplo #3 Inheriting variables from the parent scope

    <?php
    $message = 'hello';

    // No "use"
    $example = function () {
        var_dump($message);
    };
    $example();

    // Inherit $message
    $example = function () use ($message) {
        var_dump($message);
    };
    $example();

    // Inherited variable's value is from when the function
    // is defined, not when called
    $message = 'world';
    $example();

    // Reset message
    $message = 'hello';

    // Inherit by-reference
    $example = function () use (&$message) {
        var_dump($message);
    };
    $example();

    // The changed value in the parent scope
    // is reflected inside the function call
    $message = 'world';
    $example();

    // Closures can also accept regular arguments
    $example = function ($arg) use ($message) {
        var_dump($arg . ' ' . $message);
    };
    $example("hello");

    // Return type declaration comes after the use clause
    $example = function () use ($message): string {
        return "hello $message";
    };
    var_dump($example());

Resultado del ejemplo anterior es similar a:

    Notice: Undefined variable: message in /example.php on line 6
    NULL
    string(5) "hello"
    string(5) "hello"
    string(5) "hello"
    string(5) "world"
    string(11) "hello world"
    string(11) "hello world"

As of PHP 8.0.0, the list of scope-inherited variables may include a trailing comma, which will be ignored.

Inheriting variables from the parent scope is not the same as using global variables. Global variables exist in the global scope, which is the same no matter what function is executing. The parent scope of a closure is the function in which the closure was declared (not necessarily the function it was called from). See the following example:

Ejemplo #4 Closures and scoping

    <?php
    // A basic shopping cart which contains a list of added products
    // and the quantity of each product. Includes a method which
    // calculates the total price of the items in the cart using a
    // closure as a callback.
    class Cart
    {
        const PRICE_BUTTER  = 1.00;
        const PRICE_MILK    = 3.00;
        const PRICE_EGGS    = 6.95;

        protected $products = array();

        public function add($product, $quantity)
        {
            $this->products[$product] = $quantity;
        }

        public function getQuantity($product)
        {
            return isset($this->products[$product]) ? $this->products[$product] :
                   FALSE;
        }

        public function getTotal($tax)
        {
            $total = 0.00;

            $callback =
                function ($quantity, $product) use ($tax, &$total)
                {
                    $pricePerItem = constant(__CLASS__ . "::PRICE_" .
                        strtoupper($product));
                    $total += ($pricePerItem * $quantity) * ($tax + 1.0);
                };

            array_walk($this->products, $callback);
            return round($total, 2);
        }
    }

    $my_cart = new Cart;

    // Add some items to the cart
    $my_cart->add('butter', 1);
    $my_cart->add('milk', 3);
    $my_cart->add('eggs', 6);

    // Print the total with a 5% sales tax.
    print $my_cart->getTotal(0.05) . "\n";
    // The result is 54.29

Ejemplo #5 Automatic binding of `$this`

    <?php
    class Test
    {
        public function testing()
        {
            return function() {
                var_dump($this);
            };
        }
    }

    $object = new Test;
    $function = $object->testing();
    $function();

El ejemplo anterior mostrará:

    object(Test)#1 (0) {
    }

When declared in the context of a class, the current class is automatically bound to it, making `$this` available inside of the function's scope. If this automatic binding of the current class is not wanted, then static anonymous functions may be used instead.

### Static anonymous functions

Anonymous functions may be declared statically. This prevents them from having the current class automatically bound to them. Objects may also not be bound to them at runtime.

Ejemplo #6 Attempting to use `$this` inside a static anonymous function

    <?php
    class Foo
    {
        function __construct()
        {
            $func = static function() {
                var_dump($this);
            };
            $func();
        }
    };
    new Foo();

El ejemplo anterior mostrará:

    Fatal error: Uncaught Error: Using $this when not in object context in script:7
    Stack trace:
    #0 script(9): Foo::{closure:Foo::__construct():6}()
    #1 script(12): Foo->__construct()
    #2 {main}
      thrown in script on line 7

Ejemplo #7 Attempting to bind an object to a static anonymous function

    <?php
    $func = static function() {
        // function body
    };
    $func = $func->bindTo(new stdClass);
    $func();

El ejemplo anterior mostrará:

    Warning: Cannot bind an instance to a static closure, this will be an error in PHP 9 in script on line 5

    Fatal error: Uncaught Error: Value of type null is not callable in script:6
    Stack trace:
    #0 {main}
      thrown in script on line 6

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Closures created from magic methods can accept named parameters.
7.1.0 | Anonymous functions may not close over superglobals, $this, or any variable with the same name as a parameter.

### Notas

> Nota: It is possible to use func_num_args(), func_get_arg(), and func_get_args() from within a closure.

## Arrow Functions

Arrow functions were introduced in PHP 7.4 as a more concise syntax for anonymous functions.

Both anonymous functions and arrow functions are implemented using the Closure class.

Arrow functions have the basic form `fn (argument_list) => expr`.

Arrow functions support the same features as anonymous functions, except that using variables from the parent scope is always automatic.

When a variable used in the expression is defined in the parent scope it will be implicitly captured by-value. In the following example, the functions $fn1 and $fn2 behave the same way.

Ejemplo #1 Arrow functions capture variables by value automatically

    <?php
    $y = 1;

    $fn1 = fn($x) => $x + $y;
    // equivalent to using $y by value:
    $fn2 = function ($x) use ($y) {
        return $x + $y;
    };

    var_export($fn1(3));

El ejemplo anterior mostrará:

    4

This also works if the arrow functions are nested:

Ejemplo #2 Arrow functions capture variables by value automatically, even when nested

    <?php
    $z = 1;
    $fn = fn($x) => fn($y) => $x * $y + $z;
    // Outputs 51
    var_export($fn(5)(10));

Similarly to anonymous functions, the arrow function syntax allows arbitrary function signatures, including parameter and return types, default values, variadics, as well as by-reference passing and returning. All of the following are valid examples of arrow functions:

Ejemplo #3 Examples of arrow functions

    <?php
    fn(array $x) => $x;
    static fn($x): int => $x;
    fn($x = 42) => $x;
    fn(&$x) => $x;
    fn&($x) => $x;
    fn($x, ...$rest) => $rest;

Arrow functions use by-value variable binding. This is roughly equivalent to performing a `use($x)` for every variable $x used inside the arrow function. A by-value binding means that it is not possible to modify any values from the outer scope. Anonymous functions can be used instead for by-ref bindings.

Ejemplo #4 Values from the outer scope cannot be modified by arrow functions

    <?php
    $x = 1;
    $fn = fn() => $x++; // Has no effect
    $fn();
    var_export($x);  // Outputs 1

### Historial de cambios

Versión | Descripción
--- | ---
7.4.0 | Arrow functions became available.

### Notas

> Nota: It is possible to use func_num_args(), func_get_arg(), and func_get_args() from within an arrow function.

## First class callable syntax

The first class callable syntax is introduced as of PHP 8.1.0, as a way of creating anonymous functions from callable. It supersedes existing callable syntax using strings and arrays. The advantage of this syntax is that it is accessible to static analysis, and uses the scope at the point where the callable is acquired.

`CallableExpr(...)` syntax is used to create a Closure object from callable. `CallableExpr` accepts any expression that can be directly called in the PHP grammar:

Ejemplo #1 Simple first class callable syntax

    <?php
    class Foo {
       public function method() {}
       public static function staticmethod() {}
       public function __invoke() {}
    }

    $obj = new Foo();
    $classStr = 'Foo';
    $methodStr = 'method';
    $staticmethodStr = 'staticmethod';

    $f1 = strlen(...);
    $f2 = $obj(...);  // invokable object
    $f3 = $obj->method(...);
    $f4 = $obj->$methodStr(...);
    $f5 = Foo::staticmethod(...);
    $f6 = $classStr::$staticmethodStr(...);

    // traditional callable using string, array
    $f7 = 'strlen'(...);
    $f8 = [$obj, 'method'](...);
    $f9 = [Foo::class, 'staticmethod'](...);

> Nota:

> The `...` is part of the syntax, and not an omission.

`CallableExpr(...)` has the same semantics as Closure::fromCallable(). That is, unlike callable using strings and arrays, `CallableExpr(...)` respects the scope at the point where it is created:

Ejemplo #2 Scope comparison of `CallableExpr(...)` and traditional callable

    <?php
    class Foo {
        public function getPrivateMethod() {
            return [$this, 'privateMethod'];
        }

        private function privateMethod() {
            echo __METHOD__, "\n";
        }
    }

    $foo = new Foo;
    $privateMethod = $foo->getPrivateMethod();
    $privateMethod();
    // Fatal error: Call to private method Foo::privateMethod() from global scope
    // This is because call is performed outside from Foo and visibility will be checked from this point.

    <?php
    class Foo1 {
        public function getPrivateMethod() {
            // Uses the scope where the callable is acquired.
            return $this->privateMethod(...); // identical to Closure::fromCallable([$this, 'privateMethod']);
        }

        private function privateMethod() {
            echo __METHOD__, "\n";
        }
    }

    $foo1 = new Foo1;
    $privateMethod = $foo1->getPrivateMethod();
    $privateMethod();  // Foo1::privateMethod

> Nota:

> Object creation by this syntax (e.g `new Foo(...)`) is not supported, because `new Foo()` syntax is not considered a call.

> Nota:

> The first-class callable syntax cannot be combined with the nullsafe operator. Both of the following result in a compile-time error:

>     <?php
>     $obj?->method(...);
>     $obj?->prop->method(...);

# Clases y objetos

## Tabla de contenidos

- Introducción
- Sintaxis básica
- Propiedades
- Hooks de propiedad
- Constantes de clase
- Autocarga de clases
- Constructores y destructores
- Visibilidad
- Herencia
- El operador de resolución de ámbito (::)
- Estático
- Abstracción de clases
- Interfaces
- Traits
- Clases anónimas
- Sobrecarga mágica
- Recorrido de objetos
- Métodos mágicos
- Palabra clave "final"
- Clonación de objetos
- Comparación de objetos
- Late Static Bindings (Resolución estática en tiempo de ejecución)
- Objetos y referencias
- Serialización de objetos
- Covarianza y Contravarianza
- Objetos perezosos
- Modificaciones en POO (Programación orientada a objetos)

## Introducción

PHP incluye un modelo de objetos completo. Algunas de sus características son: visibilidad, clases y métodos abstractos y finales, métodos mágicos adicionales, interfaces, y clonación.

PHP trata los objetos de la misma manera que las referencias o manejadores, lo que significa que cada variable contiene una referencia a un objeto en lugar de una copia de todo el objeto. Véanse los Objetos y referencias

Sugerencia

Eche un vistazo a Guía de entorno de usuario para nombres.

## Sintaxis básica

### class

Una definición de clase básica comienza con la palabra clave `class`, seguida del nombre de la clase. Sigue un par de llaves que contienen la definición de las propiedades y los métodos que pertenecen a la clase.

El nombre de la clase puede ser cualquiera siempre que no sea una palabra reservada en PHP. A partir de PHP 8.4.0, el uso de un solo guion bajo `_` como nombre de clase es obsoleto. Un nombre de clase válido comienza con una letra o un guion bajo, seguido de cualquier número de letras, dígitos o guiones bajos. En términos de expresión regular, esto se expresaría así: `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`.

Una clase puede contener sus propias constantes, variables (llamadas "propiedades"), y funciones (llamadas "métodos").

Ejemplo #1 Definición típica de una clase

    <?php
    class SimpleClass
    {
        // declaración de una propiedad
        public $var = 'un valor por omisión';

        // declaración de los métodos
        public function displayVar() {
            echo $this->var;
        }
    }
    ?>

La pseudo-variable $this está disponible cuando un método es llamado desde un contexto de objeto. $this es el valor del objeto que llama.

Advertencia

Llamar a un método no estático estáticamente lanza una Error. Antes de PHP 8.0.0, esto generaba una notificación de obsolescencia, y $this no estaba definido.

Ejemplo #2 Algunos ejemplos de la pseudo-variable $this

    <?php
    class A
    {
        function foo()
        {
            if (isset($this)) {
                echo '$this está definido (';
                echo get_class($this);
                echo ")\n";
            } else {
                echo "\$this no está definido.\n";
            }
        }
    }

    class B
    {
        function bar()
        {
            A::foo();
        }
    }

    $a = new A();
    $a->foo();

    A::foo();

    $b = new B();
    $b->bar();

    B::bar();
    ?>

Resultado del ejemplo anterior en PHP 7:

    $this está definido (A)

    Deprecated: Non-static method A::foo() should not be called statically in %s  on line 27
    $this no está definido.

    Deprecated: Non-static method A::foo() should not be called statically in %s  on line 20
    $this no está definido.

    Deprecated: Non-static method B::bar() should not be called statically in %s  on line 32

    Deprecated: Non-static method A::foo() should not be called statically in %s  on line 20
    $this no está definido.

Resultado del ejemplo anterior en PHP 8:

    $this está definido (A)

    Fatal error: Uncaught Error: Non-static method A::foo() cannot be called statically in %s :27
    Stack trace:
    #0 {main}
      thrown in %s  on line 27

#### Clases de solo lectura (readonly)

A partir de PHP 8.2.0, una clase puede ser marcada con el modificador readonly. Marcar una clase como readonly añadirá el modificador readonly a cada propiedad declarada, y evitará la creación de propiedades dinámicas. Además, no es posible añadir su soporte utilizando el atributo AllowDynamicProperties. Cualquier intento de hacerlo desencadenará un error de compilación.

    <?php
    #[\AllowDynamicProperties]
    readonly class Foo {
    }

    // Fatal error: Cannot apply #[AllowDynamicProperties] to readonly class Foo
    ?>

Como ni las propiedades no tipadas ni las propiedades estáticas pueden ser marcadas con el modificador `readonly`, las clases readonly no pueden declararlas:

    <?php
    readonly class Foo
    {
        public $bar;
    }

    // Fatal error: Readonly property Foo::$bar must have type
    ?>

    <?php
    readonly class Foo
    {
        public static int $bar;
    }

    // Fatal error: Readonly class Foo cannot declare static properties
    ?>

Una clase readonly puede ser extendida si, y solo si, la clase hija es también una clase readonly.

### La palabra clave `new`

Para crear una instancia de una clase, la palabra clave `new` debe ser utilizada. Un objeto será entonces sistemáticamente creado, a menos que tenga un constructor definido que lance una excepción en caso de error. Las clases deben ser definidas antes de la instanciación (en algunos casos, esto es imprescindible).

Si una variable string que contiene un nombre de clase es utilizada con `new`, una nueva instancia de esa clase será creada. Si la clase está en un espacio de nombres, su nombre completamente calificado debe ser utilizado.

> Nota:

> Si no hay argumentos para pasar al constructor de la clase, los paréntesis después del nombre de la clase pueden ser omitidos.

Ejemplo #3 Creación de una instancia

    <?php

    class SimpleClass {
    }

    $instance = new SimpleClass();
    var_dump($instance);

    // Esto también puede realizarse con una variable:
    $className = 'SimpleClass';
    $instance = new $className(); // new SimpleClass()
    var_dump($instance);
    ?>

A partir de PHP 8.0.0, el uso de `new` con expresiones arbitrarias es soportado. Esto permite instanciaciones más complejas si la expresión produce un string. La expresión debe estar rodeada de paréntesis.

Ejemplo #4 Crear una instancia utilizando una expresión arbitraria

En el ejemplo dado, se muestran varios ejemplos de expresiones arbitrarias válidas que producen un nombre de clase. Esto muestra una llamada de función, una concatenación de cadenas y la constante `::class`.

    <?php

    class ClassA extends \stdClass {}
    class ClassB extends \stdClass {}
    class ClassC extends ClassB {}
    class ClassD extends ClassA {}

    function getSomeClass(): string
    {
        return 'ClassA';
    }

    var_dump(new (getSomeClass()));
    var_dump(new ('Class' . 'B'));
    var_dump(new ('Class' . 'C'));
    var_dump(new (ClassD::class));
    ?>

Resultado del ejemplo anterior en PHP 8:

    object(ClassA)#1 (0) {
    }
    object(ClassB)#1 (0) {
    }
    object(ClassC)#1 (0) {
    }
    object(ClassD)#1 (0) {
    }

En el contexto de la clase, es posible crear un nuevo objeto con `new self` y `new parent`.

Al asignar una instancia ya creada de una clase a una variable, la nueva variable accederá a la misma instancia que el objeto que fue asignado. Este comportamiento es el mismo al pasar una instancia a una función. Una copia de un objeto ya creado puede ser realizada por clonación.

Ejemplo #5 Asignación de un objeto

    <?php
    class SimpleClass {
        public string $var;
    }

    $instance = new SimpleClass();

    $assigned   =  $instance;
    $reference  =& $instance;

    $instance->var = '$assigned tendrá este valor';

    $instance = null; // $instance y $reference se vuelven null

    var_dump($instance);
    var_dump($reference);
    var_dump($assigned);
    ?>

El ejemplo anterior mostrará:

    NULL
    NULL
    object(SimpleClass)#1 (1) {
       ["var"]=>
         string(30) "$assigned tendrá este valor"
    }

Es posible crear una instancia de un objeto de varias maneras diferentes:

Ejemplo #6 Crear nuevos objetos

    <?php

    class Test
    {
        public static function getNew()
        {
            return new static();
        }
    }

    class Child extends Test {}

    $obj1 = new Test(); // Por el nombre de la clase
    $obj2 = new $obj1; // A través de la variable que contiene un objeto
    var_dump($obj1 !== $obj2);

    $obj3 = Test::getNew(); // Por el método de clase
    var_dump($obj3 instanceof Test);

    $obj4 = Child::getNew(); // A través de un método de clase hija
    var_dump($obj4 instanceof Child);

    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(true)
    bool(true)

Es posible acceder a un miembro de un objeto recién creado en una sola expresión:

Ejemplo #7 Acceder a un miembro de un objeto recién creado

    <?php
    echo (new DateTime())->format('Y'), PHP_EOL;

    // los paréntesis alrededor son opcionales desde PHP 8.4.0
    echo new DateTime()->format('Y'), PHP_EOL;
    ?>

Resultado del ejemplo anterior es similar a:

    2025
    2025

> Nota: Anterior a PHP 7.1, los argumentos no son evaluados si no hay función constructora definida.

### Propiedades y métodos

Las propiedades y métodos de clase viven en "espacios de nombres" separados, por lo que es posible tener una propiedad y un método con el mismo nombre. Hacer referencia tanto a una propiedad como a un método tienen la misma notación, y el hecho de que una propiedad será accedida o que un método será llamado, depende solo del contexto, es decir, si el uso es un acceso variable o una llamada de función.

Ejemplo #8 Acceso a propiedad contra llamada de método

    <?php
    class Foo
    {
        public $bar = 'propiedad';

        public function bar() {
            return 'método';
        }
    }

    $obj = new Foo();
    echo $obj->bar, PHP_EOL, $obj->bar(), PHP_EOL;

El ejemplo anterior mostrará:

    propiedad
    método

Esto significa que llamar a una función anónima que ha sido asignada a una propiedad no es posible directamente. En su lugar, la propiedad debe ser primero asignada a una variable. Es posible llamar a este tipo de propiedad directamente poniéndola entre paréntesis.

Ejemplo #9 Llamar a una función anónima almacenada en una propiedad

    <?php
    class Foo
    {
        public $bar;

        public function __construct() {
            $this->bar = function() {
                return 42;
            };
        }
    }

    $obj = new Foo();

    echo ($obj->bar)(), PHP_EOL;

El ejemplo anterior mostrará:

    42

### La palabra clave `extends`

Una clase puede heredar las constantes, métodos y propiedades de otra clase utilizando la palabra clave `extends` en la declaración. No es posible extender múltiples clases: una clase puede heredar solo de una clase base.

Las constantes, métodos y propiedades heredadas pueden ser redefinidas redeclarándolas con el mismo nombre que en la clase padre. Sin embargo, si la clase padre ha definido un método o constante como final, entonces estos no pueden ser redefinidos. Es posible acceder a los métodos o propiedades estáticas redefinidas haciendo referencia a ellos con el operador parent::.

> Nota: A partir de PHP 8.1.0, las constantes pueden ser declaradas como finales.

Ejemplo #10 Herencia simple de una clase

    <?php
    class SimpleClass
    {
        function displayVar()
        {
            echo "Clase padre\n";
        }
    }

    class ExtendClass extends SimpleClass
    {
      // Redefinición del método padre
      function displayVar()
      {
        echo "Clase extendida\n";
        parent::displayVar();
      }
    }

    $extended = new ExtendClass();
    $extended->displayVar();
    ?>

El ejemplo anterior mostrará:

    Clase extendida
    Clase padre

#### Reglas de compatibilidad de firma

Al sobrecargar un método, su firma debe ser compatible con el método padre. De lo contrario, se emite un error fatal, o, anterior a PHP 8.0.0, se genera un error de nivel `E_WARNING`. Una firma es compatible si respeta las reglas de varianza, hace un parámetro obligatorio opcional, y solo si todos los nuevos parámetros son opcionales y suavizan las reglas de visibilidad. Esto es conocido como el Principio de Sustitución de Liskov (Liskov Substitution Principle), o simplemente LSP. El constructor, y los métodos `private` están excluidos de estas reglas de compatibilidad de firmas, y por lo tanto no emitirán un error fatal en caso de firma incompatible.

Ejemplo #11 Métodos hijos compatibles

    <?php
    class Base
    {
        public function foo(int $a) {
            echo "Válido\n";
        }
    }
    class Extend1 extends Base
    {
        function foo(int $a = 5)
        {
            parent::foo($a);
        }
    }
    class Extend2 extends Base
    {
        function foo(int $a, $b = 5)
        {
            parent::foo($a);
        }
    }
    $extended1 = new Extend1();
    $extended1->foo();
    $extended2 = new Extend2();
    $extended2->foo(1);

El ejemplo anterior mostrará:

    Válido
    Válido

Los siguientes ejemplos demuestran que un método hijo que elimina un parámetro, o hace un parámetro opcional obligatorio, no es compatible con el método padre.

Ejemplo #12 Error fatal cuando un método hijo elimina un parámetro

    <?php
    class Base
    {
        public function foo(int $a = 5) {
            echo "Válido\n";
        }
    }
    class Extend extends Base
    {
        function foo()
        {
            parent::foo(1);
        }
    }

Resultado del ejemplo anterior en PHP 8 es similar a:

    Fatal error: Declaration of Extend::foo() must be compatible with Base::foo(int $a = 5) in /in/evtlq on line 13

Ejemplo #13 Error fatal cuando un método hijo hace un parámetro opcional obligatorio

    <?php
    class Base
    {
        public function foo(int $a = 5) {
            echo "Válido\n";
        }
    }
    class Extend extends Base
    {
        function foo(int $a)
        {
            parent::foo($a);
        }
    }

Resultado del ejemplo anterior en PHP 8 es similar a:

    Fatal error: Declaration of Extend::foo(int $a) must be compatible with Base::foo(int $a = 5) in /in/qJXVC on line 13

Advertencia

Renombrar un parámetro de un método en una clase hija no es una incompatibilidad de firma. Sin embargo, esto es desaconsejado ya que resultará en una Error en tiempo de ejecución si los argumentos nombrados son utilizados.

Ejemplo #14 Error al usar argumentos nombrados y cuando los parámetros han sido renombrados en una clase hija

    <?php
    class A {
        public function test($foo, $bar) {}
    }
    class B extends A {
        public function test($a, $b) {}
    }
    $obj = new B;
    // Pasar parámetros según el contrato A::test()
    $obj->test(foo: "foo", bar: "bar"); // ERROR!

Resultado del ejemplo anterior es similar a:

    Fatal error: Uncaught Error: Unknown named parameter $foo in /in/XaaeN:14
    Stack trace:
    #0 {main}
      thrown in /in/XaaeN on line 14

### ::class

La palabra clave `class` también se utiliza para la resolución de nombres de clases. Es posible obtener el nombre completamente calificado de una clase `ClassName` utilizando `ClassName::class`. Esto es particularmente útil con las clases que utilizan espacios de nombres.

Ejemplo #15 Resolución de nombre de clase

    <?php
    namespace NS {
        class ClassName {
        }

        echo ClassName::class;
    }
    ?>

El ejemplo anterior mostrará:

    NS\ClassName

> Nota:

> La resolución del nombre de clase utilizando `::class` es una transformación durante la compilación. Es decir, en el instante en que se crea la cadena del nombre de la clase, aún no se ha producido ninguna carga automática. Por lo tanto, los nombres de clases se extienden incluso si la clase no existe. No se emite ningún error en este caso.

> Ejemplo #16 Resolución de nombre de clase faltante

>     <?php
>     print Does\Not\Exist::class;
>     ?>

> El ejemplo anterior mostrará:

>     Does\Not\Exist

A partir de PHP 8.0.0, `::class` puede ser utilizado en los objetos. Esta resolución ocurre durante la ejecución, y no durante la compilación. Sus efectos son los mismos que llamar get_class() en el objeto.

Ejemplo #17 Resolución del nombre de un objeto

    <?php
    namespace NS {
        class ClassName {
        }

        $c = new ClassName();
        print $c::class;
    }
    ?>

El ejemplo anterior mostrará:

    NS\ClassName

### Métodos y propiedades nullsafe

A partir de PHP 8.0.0, los métodos y propiedades también pueden ser accedidos con el operador "nullsafe": `?->`. El operador nullsafe funciona de manera idéntica al acceso de propiedades o métodos como si fuera arriba, con la excepción de que si el objeto que se está desreferenciando es `null` entonces `null` será devuelto en lugar de lanzar una excepción. Si la desreferencia se hace por una cadena, el resto de la cadena es ignorado.

El efecto es similar a rodear cada acceso con una verificación con is_null() primero, pero más compacto.

Ejemplo #18 Operador nullsafe

    <?php

    // A partir de PHP 8.0.0, esta línea:
    $result = $repository?->getUser(5)?->name;

    // Es equivalente al siguiente bloque de código:
    if (is_null($repository)) {
        $result = null;
    } else {
        $user = $repository->getUser(5);
        if (is_null($user)) {
            $result = null;
        } else {
            $result = $user->name;
        }
    }
    ?>

> Nota:

> El operador nullsafe es mejor utilizado cuando null es considerado un valor válido y potencialmente esperado para una propiedad o valor de retorno de un método. Para indicar un error, lanzar una excepción es preferible.

## Propiedades

Las variables dentro de una clase se denominan propiedades. También pueden encontrarse bajo otros nombres como campos, pero para esta documentación se utilizará propiedad. Se definen utilizando al menos un modificador (como Visibilidad, Estático, o, a partir de PHP 8.1.0, readonly), seguido opcionalmente (excepto para las propiedades `readonly`), a partir de PHP 7.4, de una declaración de tipo, seguida de una declaración clásica de variable. Esta declaración puede incluir una inicialización, pero esta debe ser un valor constante

> Nota:

> Una manera obsoleta de declarar una propiedad de clase es utilizar la palabra clave `var` en lugar de un modificador.

> Nota: Una propiedad declarada sin modificador de Visibilidad será declarada como `public`.

Dentro de los métodos de clases, las propiedades no estáticas pueden ser llamadas utilizando la sintaxis `->` (operador de objeto) : $this->property (donde `property` es el nombre de la propiedad). Las propiedades estáticas pueden ser llamadas utilizando la sintaxis `::` (dos puntos) : self::$property. Consulte la documentación sobre Estático para más información sobre la diferencia entre las propiedades estáticas y no estáticas.

La pseudo-variable $this está disponible dentro de cualquier método, cuando este método es llamado dentro de un objeto. $this es el valor del objeto que llama.

Ejemplo #1 Declaraciones de propiedades

    <?php
    class SimpleClass
    {
       public $var1 = 'hello ' . 'world';
       public $var2 = <<<EOD
    hello world
    EOD;
       public $var3 = 1+2;
       // declaración de propiedad no válida :
       public $var4 = self::myStaticMethod();
       public $var5 = $myVar;

       // Declaraciones válidas de propiedades :
       public $var6 = myConstant;
       public $var7 = [true, false];
       public $var8 = <<<'EOD'
    hello world
    EOD;

       // Sin modificador de visibilidad :
       static $var9;
       readonly int $var10;
    }
    ?>

> Nota:

> Existen diversas funciones que permiten gestionar clases y objetos. Ver la referencia sobre las Funciones Clases/Objetos.

### Declaraciones de tipos

A partir de PHP 7.4.0, las definiciones de propiedades pueden incluir una Declaraciones de tipo, con la excepción del tipo callable.

Ejemplo #2 Ejemplo de propiedades tipadas

    <?php

    class User
    {
        public int $id;
        public ?string $name;

        public function __construct(int $id, ?string $name)
        {
            $this->id = $id;
            $this->name = $name;
        }
    }

    $user = new User(1234, null);

    var_dump($user->id);
    var_dump($user->name);

    ?>

El ejemplo anterior mostrará:

    int(1234)
    NULL

Las propiedades tipadas deben ser inicializadas antes de acceder a ellas, de lo contrario, se emitirá un Error.

Ejemplo #3 Acceso a propiedades

    <?php

    class Shape
    {
        public int $numberOfSides;
        public string $name;

        public function setNumberOfSides(int $numberOfSides): void
        {
            $this->numberOfSides = $numberOfSides;
        }

        public function setName(string $name): void
        {
            $this->name = $name;
        }

        public function getNumberOfSides(): int
        {
            return $this->numberOfSides;
        }

        public function getName(): string
        {
            return $this->name;
        }
    }

    $triangle = new Shape();
    $triangle->setName("triangle");
    $triangle->setNumberofSides(3);
    var_dump($triangle->getName());
    var_dump($triangle->getNumberOfSides());

    $circle = new Shape();
    $circle->setName("circle");
    var_dump($circle->getName());
    var_dump($circle->getNumberOfSides());
    ?>

El ejemplo anterior mostrará:

    string(8) "triangle"
    int(3)
    string(6) "circle"

    Fatal error: Uncaught Error: Typed property Shape::$numberOfSides must not be accessed before initialization

### Propiedades de solo lectura (readonly)

A partir de PHP 8.1.0, una propiedad puede ser declarada con el modificador `readonly`, lo que impide la modificación de la propiedad después de la inicialización. Antes de PHP 8.4.0 una propiedad `readonly` es implícitamente privada-modificable, y solo puede ser escrita desde la misma clase. A partir de PHP 8.4.0, las propiedades `readonly` son implícitamente `protected(set)`, por lo que pueden ser definidas desde clases hijas. Esto puede ser reemplazado explícitamente si se desea.

Ejemplo #4 Ejemplo de propiedades de solo lectura

    <?php

    class Test {
       public readonly string $prop;

       public function __construct(string $prop) {
           // Inicialización legal.
           $this->prop = $prop;
       }
    }

    $test = new Test("foobar");
    // Lectura legal.
    var_dump($test->prop); // string(6) "foobar"

    // Reasignación ilegal. No importa que el valor asignado sea idéntico.
    $test->prop = "foobar";
    // Error: Cannot modify readonly property Test::$prop
    ?>

> Nota:

> El modificador de solo lectura solo puede ser aplicado a propiedades tipadas. Una propiedad de solo lectura sin restricción de tipo puede ser creada utilizando el tipo Mixed.

> Nota:

> Las propiedades estáticas de solo lectura no son soportadas.

Una propiedad de solo lectura solo puede ser inicializada una vez, y solo desde el ámbito en el que fue declarada. Cualquier otra asignación o modificación de la propiedad resultará en una excepción Error.

Ejemplo #5 Inicialización ilegal de propiedades de solo lectura

    <?php
    class Test1 {
        public readonly string $prop;
    }

    $test1 = new Test1;
    // Inicialización ilegal fuera del ámbito privado.
    $test1->prop = "foobar";
    // Error: Cannot initialize readonly property Test1::$prop from global scope
    ?>

> Nota:

> Especificar un valor por defecto explícito a una propiedad de solo lectura no está permitido, ya que una propiedad de solo lectura con un valor por defecto es esencialmente idéntica a una constante, y por lo tanto no particularmente útil.

>     <?php

>     class Test {
>         // Fatal error: Readonly property Test::$prop cannot have default value
>         public readonly int $prop = 42;
>     }
>     ?>

> Nota:

> Las propiedades de solo lectura no pueden ser unset() una vez que han sido inicializadas. Sin embargo, es posible unset una propiedad de solo lectura antes de su inicialización, desde el ámbito donde la propiedad fue declarada.

Las modificaciones no son necesariamente asignaciones simples, todos los ejemplos siguientes resultarán en una excepción Error :

    <?php

    class Test {
        public function __construct(
            public readonly int $i = 0,
            public readonly array $ary = [],
        ) {}
    }

    $test = new Test;
    $test->i += 1;
    $test->i++;
    ++$test->i;
    $test->ary[] = 1;
    $test->ary[0][] = 1;
    unset($test->ary[0]);
    $ref =& $test->i;
    $test->i =& $ref;
    byRef($test->i);
    foreach ($test as &$prop);
    ?>

Sin embargo, las propiedades de solo lectura no excluyen la mutabilidad interna. Los objetos (o recursos) almacenados en las propiedades de solo lectura pueden ser modificados internamente :

    <?php

    class Test {
        public function __construct(public readonly object $obj) {}
    }

    $test = new Test(new stdClass);
    // Mutación interna legal.
    $test->obj->foo = 1;
    // Reasignación ilegal.
    $test->obj = new stdClass;
    ?>

A partir de PHP 8.3.0, las propiedades de solo lectura pueden ser reinicializadas al clonar un objeto utilizando el método __clone().

Ejemplo #6 Propiedades de solo lectura y clonación

    <?php
    class Test1 {
        public readonly ?string $prop;

        public function __clone() {
            $this->prop = null;
        }

        public function setProp(string $prop): void {
            $this->prop = $prop;
        }
    }

    $test1 = new Test1;
    $test1->setProp('foobar');

    $test2 = clone $test1;
    var_dump($test2->prop); // NULL
    ?>

### Propiedades Dinámicas

Al intentar asignar a una propiedad no existente en un object, PHP creará automáticamente una propiedad correspondiente. Esta propiedad creada dinámicamente estará únicamente disponible en esta instancia de clase.

Advertencia

Las propiedades dinámicas están obsoletas a partir de PHP 8.2.0. Se recomienda declarar la propiedad en su lugar. Para manejar nombres de propiedades arbitrarios, la clase debería implementar los métodos mágicos __get() y __set(). Como último recurso, la clase puede ser marcada con el atributo `#[\AllowDynamicProperties]`.

## Hooks de propiedad

Los hooks de propiedad, también conocidos como "métodos de acceso de propiedad" en otros lenguajes, son una forma de interceptar y reemplazar el comportamiento de lectura y escritura de una propiedad. Esta funcionalidad sirve a dos fines:

1. Permite utilizar propiedades directamente, sin necesidad de métodos get y set, dejando la posibilidad de añadir un comportamiento adicional en el futuro. Esto hace que la mayoría de los métodos get/set sean innecesarios, incluso sin usar hooks.
2. Permite definir propiedades que describen un objeto sin almacenar directamente un valor.

Existen dos hooks disponibles en las propiedades no estáticas: `get` y `set`. Permiten reemplazar el comportamiento de lectura y escritura de una propiedad, respectivamente. Los hooks están disponibles para propiedades tipadas y no tipadas.

Un objeto puede ser "backed" o "virtual". Una propiedad "backed" es una propiedad que almacena efectivamente un valor. Cualquier propiedad que no tenga hooks es "backed". Una propiedad virtual es una propiedad que tiene hooks y estos hooks no interactúan con la propiedad misma. En este caso, los hooks son efectivamente los mismos que los métodos, y el objeto no utiliza espacio para almacenar un valor para esta propiedad.

Los hooks de propiedad son incompatibles con las propiedades `readonly`. Si es necesario restringir el acceso a una operación `get` o `set` además de modificar su comportamiento, utilice la visibilidad asimétrica de propiedad.

> Nota: Información de versión
> Los hooks de propiedad fueron introducidos en PHP 8.4.

### Sintaxis básica de los hooks

La sintaxis general para declarar un hook es la siguiente.

Ejemplo #1 Hooks de propiedad (versión completa)

    <?php
    class Example
    {
        private bool $modified = false;

        public string $foo = 'valor por omisión' {
            get {
                if ($this->modified) {
                    return $this->foo . ' (modificado)';
                }
                return $this->foo;
            }
            set(string $value) {
                $this->foo = strtolower($value);
                $this->modified = true;
            }
        }
    }

    $example = new Example();
    $example->foo = 'cambiado';
    print $example->foo;
    ?>

La propiedad $foo termina con `{}`, en lugar de un punto y coma. Esto indica la presencia de hooks. Se definen un hook `get` y un hook `set`, aunque es posible definir solo uno. Ambos hooks tienen un cuerpo, indicado por `{}`, que puede contener código arbitrario.

El hook `set` también permite especificar el tipo y el nombre de un valor entrante, utilizando la misma sintaxis que una método. El tipo debe ser el mismo que el tipo de la propiedad, o contravariante (más amplio) que este. Por ejemplo, una propiedad de tipo string podría tener un hook `set` que acepte un string|Stringable, pero no uno que acepte solo array.

Al menos uno de los hooks hace referencia a `$this->foo`, la propiedad misma. Esto significa que la propiedad será "backed". Cuando se llama a `$example->foo = 'cambiado'`, la cadena proporcionada se convertirá primero en minúsculas y luego se guardará en el valor de respaldo. Al leer la propiedad, el valor previamente guardado puede ser condicionalmente complementado con texto adicional.

Hay varias variantes de sintaxis abreviada para manejar los casos comunes.

Si el hook `get` es una simple expresión, entonces los `{}` pueden ser omitidos y reemplazados por una expresión flecha.

Ejemplo #2 Expresión de propiedad get

Este ejemplo es equivalente al ejemplo anterior.

    <?php
    class Example
    {
        private bool $modified = false;

        public string $foo = 'valor por omisión' {
            get => $this->foo . ($this->modified ? ' (modificado)' : '');

            set(string $value) {
                $this->foo = strtolower($value);
                $this->modified = true;
            }
        }
    }
    ?>

Si el tipo del parámetro del hook `set` es el mismo que el tipo de la propiedad (lo cual es típico), puede ser omitido. En este caso, el valor a definir se nombra automáticamente $value.

Ejemplo #3 Parámetros por omisión de propiedad

Este ejemplo es equivalente al ejemplo anterior.

    <?php
    class Example
    {
        private bool $modified = false;

        public string $foo = 'valor por omisión' {
            get => $this->foo . ($this->modified ? ' (modificado)' : '');

            set {
                $this->foo = strtolower($value);
                $this->modified = true;
            }
        }
    }
    ?>

Si el hook `set` solo define una versión modificada del valor pasado, también puede simplificarse en una expresión flecha. El valor al que se evalúa la expresión se definirá en el valor de respaldo.

Ejemplo #4 Expresión de propiedad set

    <?php
    class Example
    {
        private bool $modified = false;

        public string $foo = 'valor por omisión' {
            get => $this->foo . ($this->modified ? ' (modificado)' : '');
            set => strtolower($value);
        }
    }
    ?>

Este ejemplo no es completamente equivalente al anterior, ya que tampoco modifica `$this->modified`. Si se necesitan múltiples instrucciones en el cuerpo del hook, utilice la versión con llaves.

Una propiedad puede implementar cero, uno o ambos hooks según la situación. Todas las versiones abreviadas son mutuamente independientes. Es decir, utilizar un atajo para obtener una definición larga, o un atajo para definir un tipo explícito, etc., es válido.

En una propiedad "backed", omitir un hook `get` o `set` significa que se utilizará el comportamiento de lectura o escritura por omisión.

> Nota: Los hooks pueden ser definidos al utilizar la promoción de propiedades en el constructor. Sin embargo, en este caso, los valores proporcionados al constructor deben coincidir con el tipo asociado a la propiedad, independientemente de lo que el hook `set` podría permitir. Considere el siguiente ejemplo:

>     <?php
>     class Example
>     {
>         public function __construct(
>             public private(set) DateTimeInterface $created {
>                 set (string|DateTimeInterface $value) {
>                     if (is_string($value)) {
>                         $value = new DateTimeImmutable($value);
>                     }
>                     $this->created = $value;
>                 }
>             },
>         ) {
>         }
>     }

> Internamente, el motor descompone esto de la siguiente manera:

>     <?php
>     class Example
>     {
>         public private(set) DateTimeInterface $created {
>             set (string|DateTimeInterface $value) {
>                 if (is_string($value)) {
>                     $value = new DateTimeImmutable($value);
>                 }
>                 $this->created = $value;
>             }
>         }

>         public function __construct(
>             DateTimeInterface $created,
>         ) {
>             $this->created = $created;
>         }
>     }

> Cualquier intento de definir la propiedad fuera del constructor permitirá un string o un valor de tipo DateTimeInterface, pero el constructor solo permitirá DateTimeInterface. Esto se debe a que el tipo definido para la propiedad (DateTimeInterface) se utiliza como tipo de parámetro en la firma del constructor, independientemente de lo que el hook `set` permita. Si este tipo de comportamiento es necesario desde el constructor, la promoción de propiedades en el constructor no puede ser utilizada.

### Propiedades virtuales

Las propiedades virtuales son propiedades que no tienen un valor de respaldo. Una propiedad es virtual si ni su hook `get` ni su hook `set` hace referencia a la propiedad misma utilizando una sintaxis exacta. Es decir, una propiedad nombrada `$foo` cuyo hook contiene `$this->foo` será respaldada. Pero la siguiente propiedad no es una propiedad respaldada, y generará un error:

Ejemplo #5 Propiedad virtual inválida

    <?php
    class Example
    {
        public string $foo {
            get {
                $temp = __PROPERTY__;
                return $this->$temp; // No se refiere a $this->foo, por lo que no cuenta.
            }
        }
    }
    ?>

Para las propiedades virtuales, si se omite un hook, entonces esa operación no existe y tratar de utilizarla producirá un error. Las propiedades virtuales no ocupan espacio de memoria en un objeto. Las propiedades virtuales son adecuadas para las propiedades "derivadas", tales como las que son la combinación de dos otras propiedades.

Ejemplo #6 Propiedad virtual

    <?php
    class Rectangle
    {
        // Una propiedad virtual.
        public int $area {
            get => $this->h * $this->w;
        }

        public function __construct(public int $h, public int $w) {}
    }

    $s = new Rectangle(4, 5);
    print $s->area; // muestra 20
    $s->area = 30; // Error, ya que no hay operación de definición.
    ?>

Definir tanto un hook `get` como un hook `set` en una propiedad virtual también está permitido.

### Alcance

Todos los hooks funcionan en el alcance del objeto modificado. Esto significa que tienen acceso a todos los métodos públicos, privados o protegidos del objeto, así como a todas las propiedades públicas, privadas o protegidas, incluyendo las propiedades que pueden tener sus propios hooks de propiedad. Acceder a otra propiedad desde un hook no elude los hooks definidos en esa propiedad.

La consecuencia más notable de esto es que los hooks no triviales pueden llamar a un método arbitrariamente complejo si lo desean.

Ejemplo #7 Llamada a un método desde un hook

    <?php
    class Person {
        public string $phone {
            set => $this->sanitizePhone($value);
        }

        private function sanitizePhone(string $value): string {
            $value = ltrim($value, '+');
            $value = ltrim($value, '1');

            if (!preg_match('/\d\d\d\-\d\d\d\-\d\d\d\d/', $value)) {
                throw new \InvalidArgumentException();
            }
            return $value;
        }
    }
    ?>

### Referencias

Debido a que la presencia de hooks intercepta el proceso de lectura y escritura de las propiedades, plantean problemas al adquirir una referencia a una propiedad o con una modificación indirecta, tal como `$this->arrayProp['key'] = 'value';`. Esto se debe a que cualquier intento de modificar el valor por referencia eludiría un hook de definición si existiera uno.

En el caso raro en que sea necesario obtener una referencia a una propiedad para la cual se definen hooks, el hook `get` puede ser prefijado por `&` para que devuelva por referencia. Definir tanto `get` como `&get` en la misma propiedad es un error de sintaxis.

Definir tanto los hooks `&get` como `set` en una propiedad "backed" no está permitido. Como se indicó anteriormente, escribir en el valor devuelto por referencia eludiría el hook `set`. En las propiedades virtuales, no hay un valor común necesario compartido entre los dos hooks, por lo que definir ambos está permitido.

Escribir en un índice de una propiedad de array implica también una referencia implícita. Por esta razón, escribir en una propiedad de array "backed" con hooks definidos está permitido si y solo si define solo un hook `&get`. En una propiedad virtual, escribir en el array devuelto por `get` o `&get` es legal, pero si esto tiene un impacto en el objeto depende de la implementación del hook.

Sobrecargar la propiedad de array completa está permitido, y se comporta de la misma manera que cualquier otra propiedad. Trabajar solo con elementos del array requiere atención especial.

### Herencia

#### Hooks finales

Los hooks también pueden ser declarados final, en cuyo caso no pueden ser reemplazados.

Ejemplo #8 Hooks finales

    <?php
    class User
    {
        public string $username {
            final set => strtolower($value);
        }
    }

    class Manager extends User
    {
        public string $username {
            // Esto está permitido
            get => strtoupper($this->username);

            // Esto NO está permitido, ya que set es final en el padre.
            set => strtoupper($value);
        }
    }
    ?>

Una propiedad también puede ser declarada final. Una propiedad final no puede ser redeclarada por una clase hija de ninguna manera, lo que excluye la modificación de los hooks o la ampliación de su acceso.

Declarar hooks finales en una propiedad que es declarada final es redundante, y será silenciosamente ignorado. Es el mismo comportamiento que para los métodos finales.

Una clase hija puede declarar o cambiar hooks individuales en una propiedad redefiniendo la propiedad y solo los hooks que desea reemplazar. Una clase hija también puede añadir hooks a una propiedad que no los tenía. Esto es esencialmente lo mismo que si los hooks fueran métodos.

Ejemplo #9 Herencia de hook

    <?php
    class Point
    {
        public int $x;
        public int $y;
    }

    class PositivePoint extends Point
    {
        public int $x {
            set {
                if ($value < 0) {
                    throw new \InvalidArgumentException('Demasiado pequeño');
                }
                $this->x = $value;
            }
        }
    }
    ?>

Cada hook reemplaza las implementaciones parentales de manera independiente. Si una clase hija añade hooks, cualquier valor por omisión definido en la propiedad es eliminado, y debe ser redeclarado. Esto es coherente con el funcionamiento de la herencia en las propiedades sin hooks.

#### Acceso a los hooks parentales

Un hook en una clase hija puede acceder a la propiedad de la clase padre utilizando la palabra clave `parent::$prop`, seguida del hook deseado. Por ejemplo, `parent::$propName::get()`. Esto puede ser leído como "acceder a la prop definida en la clase padre, luego ejecutar su operación get" (o set, según el caso).

Si no se accede de esta manera, el hook de la clase padre es ignorado. Este comportamiento es coherente con el funcionamiento de todos los métodos. Esto también proporciona una manera de acceder al almacenamiento de la clase padre, si es necesario. Si no hay un hook en la propiedad padre, su comportamiento por omisión get/set será utilizado. Los hooks no pueden acceder a otro hook que no sea su propio padre en su propia propiedad.

El ejemplo anterior podría ser reescrito de la siguiente manera, lo que permitiría a la clase `Point` añadir su propio hook `set` en el futuro sin problemas (en el ejemplo anterior, un hook añadido a la clase padre sería ignorado en la clase hija).

Ejemplo #10 Acceso a los hooks parentales (set)

    <?php
    class Point
    {
        public int $x;
        public int $y;
    }

    class PositivePoint extends Point
    {
        public int $x {
            set {
                if ($value < 0) {
                    throw new \InvalidArgumentException('Demasiado pequeño');
                }
                parent::$x::set($value);
            }
        }
    }
    ?>

Un ejemplo de reemplazo de solo un hook get podría ser:

Ejemplo #11 Acceso a los hooks parentales (get)

    <?php
    class Strings
    {
        public string $val;
    }

    class CaseFoldingStrings extends Strings
    {
        public bool $uppercase = true;

        public string $val {
            get => $this->uppercase
                ? strtoupper(parent::$val::get())
                : strtolower(parent::$val::get());
        }
    }
    ?>

### Serialización

PHP tiene varias formas diferentes de serializar un objeto, ya sea para consumo público o para fines de depuración. El comportamiento de los hooks varía según el uso. En algunos casos, el valor bruto de respaldo de una propiedad será utilizado, eludiendo cualquier hook. En otros, la propiedad será leída o escrita "a través" del hook, como cualquier otra acción de lectura/escritura normal.

- var_dump(): Utiliza el valor bruto
- serialize(): Utiliza el valor bruto
- unserialize(): Utiliza el valor bruto
- __serialize()/__unserialize(): Lógica propia, utiliza los hooks de recuperación/definición
- Conversión a array: Utiliza el valor bruto
- var_export(): Utiliza el hook de recuperación
- json_encode(): Utiliza el hook de recuperación
- JsonSerializable: Lógica propia, utiliza el hook de recuperación
- get_object_vars(): Utiliza el hook de recuperación
- get_mangled_object_vars(): Utiliza el valor bruto

## Constantes de clase

Es posible definir constantes por clases que permanecen idénticas y no modificables. La visibilidad por omisión de las constantes de clase es `public`.

> Nota:

> Las constantes de clases pueden ser redefinidas por una clase hija. A partir de PHP 8.1.0, las constantes de clases no pueden ser redefinidas por una clase hija si ha sido definida como final.

También es posible para las interfaces tener constantes. Ver la documentación de las interfaces para ejemplos.

Es posible referenciar la clase utilizando una variable. El valor de la variable no puede ser una palabra clave (por ejemplo, `self`, `parent` y `static`).

Tenga en cuenta que las constantes de clase son asignadas una vez por clase, y no para cada instancia de clase.

A partir de PHP 8.3.0, las constantes de clase pueden tener un tipo escalar como `bool`, `int`, `float`, `string`, o incluso `array`. Al utilizar `array`, su contenido solo puede contener otros tipos escalares.

Ejemplo #1 Definición y uso de una constante de clase

    <?php
    class MyClass
    {
      const CONSTANT = 'valor constante';

      function showConstant() {
        echo  self::CONSTANT . "\n";
      }
    }

    echo MyClass::CONSTANT . "\n";

    $classname = "MyClass";
    echo $classname::CONSTANT . "\n";

    $class = new MyClass();
    $class->showConstant();

    echo $class::CONSTANT."\n";
    ?>

La constante especial `::class` permite una resolución de nombre de clase completamente cualificado en el momento de la compilación, esto es útil para las clases en un espacio de nombres:

Ejemplo #2 Ejemplo de uso de ::class

    <?php
    namespace foo {
        class bar {
        }

        echo bar::class; // foo\bar
    }
    ?>

Ejemplo #3 Ejemplo de expresiones para una constante de clase

    <?php
    const ONE = 1;
    class foo {
        const TWO = ONE * 2;
        const THREE = ONE + self::TWO;
        const SENTENCE = 'El valor de THREE es '.self::THREE;
    }
    ?>

Ejemplo #4 Modificador de visibilidad de las constantes de clase, a partir de PHP 7.1

    <?php
    class Foo {
        public const BAR = 'bar';
        private const BAZ = 'baz';
    }
    echo Foo::BAR, PHP_EOL;
    echo Foo::BAZ, PHP_EOL;
    ?>

Resultado del ejemplo anterior en PHP 7.1:

    bar

    Fatal error: Uncaught Error: Cannot access private const Foo::BAZ in …

> Nota:

> A partir de PHP 7.1.0, los modificadores de visibilidad son permitidos en las constantes de clase.

Ejemplo #5 Verificación de varianza de visibilidad de las constantes de clase, a partir de PHP 8.3.0

    <?php

    interface MyInterface
    {
        public const VALUE = 42;
    }

    class MyClass implements MyInterface
    {
        protected const VALUE = 42;
    }
    ?>

Resultado del ejemplo anterior en PHP 8.3:

    Fatal error: Access level to MyClass::VALUE must be public (as in interface MyInterface) …

> Nota: A partir de PHP 8.3.0, la varianza de visibilidad es verificada de manera más estricta. Antes de esta versión, la visibilidad de una constante de clase podía diferir de la de la constante en la interfaz implementada.

Ejemplo #6 Sintaxis de acceso dinámico a las constantes de clase, a partir de PHP 8.3.0

    <?php
    class Foo {
        public const BAR = 'bar';
        private const BAZ = 'baz';
    }

    $name = 'BAR';
    echo Foo::{$name}, PHP_EOL; // bar
    ?>

> Nota:

> A partir de PHP 8.3.0, las constantes de clase pueden ser recuperadas dinámicamente utilizando una variable.

Ejemplo #7 Asignación de tipos a las constantes de clase, a partir de PHP 8.3.0

    <?php

    class MyClass {
        public const bool MY_BOOL = true;
        public const int MY_INT = 1;
        public const float MY_FLOAT = 1.01;
        public const string MY_STRING = 'one';
        public const array MY_ARRAY = [self::MY_BOOL, self::MY_INT, self::MY_FLOAT, self::MY_STRING];
    }

    var_dump(MyClass::MY_BOOL);
    var_dump(MyClass::MY_INT);
    var_dump(MyClass::MY_FLOAT);
    var_dump(MyClass::MY_STRING);
    var_dump(MyClass::MY_ARRAY);
    ?>

Resultado del ejemplo anterior en PHP 8.3:

    bool(true)
    int(1)
    float(1.01)
    string(3) "one"
    array(4) {
      [0]=>
      bool(true)
      [1]=>
      int(1)
      [2]=>
      float(1.01)
      [3]=>
      string(3) "one"
    }

## Autocarga de clases

Muchos desarrolladores que escriben aplicaciones orientadas a objetos crean un fichero fuente por definición de clase. Uno de los mayores inconvenientes de este método es tener que escribir una larga lista de inclusiones de ficheros de clases al inicio de cada script: una inclusión por clase.

La función spl_autoload_register() registra un número cualquiera de cargadores automáticos, lo que permite a las clases y a las interfaces ser automáticamente cargadas si no están definidas actualmente. Al registrar autocargadores, PHP da una última oportunidad de incluir una definición de clase o interfaz, antes de que PHP falle con un error.

Cualquier construcción similar a las clases puede ser autocargada de la misma manera. Esto incluye las clases, interfaces, traits y enumeraciones.

Precaución

Anterior a PHP 8.0.0, era posible utilizar __autoload() para autocargar las clases y las interfaces. Sin embargo, es una alternativa menos flexible a spl_autoload_register() y __autoload() está obsoleto a partir de PHP 7.2.0, y eliminado a partir de PHP 8.0.0.

> Nota:

> spl_autoload_register() puede ser llamada varias veces para registrar varios autocargadores. Lanzar una excepción desde una función de autocarga, interrumpirá este proceso y no permitirá que las funciones de autocarga siguientes sean ejecutadas. Por esta razón, lanzar excepciones desde una función de autocarga es fuertemente desaconsejado.

Ejemplo #1 Ejemplo de autocarga

Este ejemplo intenta cargar las clases `MiClase1` y `MiClase2`, respectivamente desde los ficheros MiClase1.php y MiClase2.php.

    <?php
    spl_autoload_register(function ($class_name) {
        include $class_name . '.php';
    });

    $obj  = new MiClase1();
    $obj2 = new MiClase2();
    ?>

Ejemplo #2 Otro ejemplo de autocarga

Este ejemplo intenta cargar la interfaz `ITest`.

    <?php

    spl_autoload_register(function ($name) {
        var_dump($name);
    });

    class Foo implements ITest {
    }

    /*
    string(5) "ITest"

    Fatal error: Interface 'ITest' not found in ...
    */
    ?>

Ejemplo #3 Uso del autoloader de Composer

» Composer genera un fichero `vendor/autoload.php` configurado para cargar automáticamente los paquetes gestionados por Composer. Al incluir este fichero, estos paquetes pueden ser utilizados sin trabajo adicional.

    <?php
    require __DIR__ . '/vendor/autoload.php';

    $uuid = Ramsey\Uuid\Uuid::uuid7();

    echo "Nuevo UUID generado -> ", $uuid->toString(), "\n";
    ?>

### Ver también

- unserialize()
- unserialize_callback_func
- unserialize_max_depth
- spl_autoload_register()
- spl_autoload()
- __autoload()

## Constructores y destructores

### Constructor

function __construct(mixed `...$values` = ""): void

PHP permite a los desarrolladores declarar constructores para las clases. Las clases que poseen un método constructor llaman a este método cada vez que se crea una nueva instancia del objeto, lo cual es interesante para todas las inicializaciones de las que el objeto necesita antes de ser utilizado.

> Nota: Los constructores padres no son llamados implícitamente si la clase hija define un constructor. Si se desea utilizar un constructor padre, será necesario hacer llamada a parent::__construct() desde el constructor hijo. Si el hijo no define un constructor entonces, puede ser heredado de la clase padre, exactamente de la misma forma que una método lo sería (si no ha sido declarado como privado).

Ejemplo #1 Constructor durante la herencia

    <?php
    class BaseClass {
        function __construct() {
            print "En el constructor de BaseClass\n";
        }
    }

    class SubClass extends BaseClass {
        function __construct() {
            parent::__construct();
            print "En el constructor de SubClass\n";
        }
    }

    class OtherSubClass extends BaseClass {
        // Constructor heredado de BaseClass
    }

    // En el constructor de BaseClass
    $obj = new BaseClass();

    // En el constructor de BaseClass
    // En el constructor de SubClass
    $obj = new SubClass();

    // En el constructor de BaseClass
    $obj = new OtherSubClass();
    ?>

A diferencia de otros métodos, __construct() está excluido de las reglas de compatibilidad de firmas usuales cuando se extiende.

Los constructores son métodos ordinarios que son llamados durante la instanciación de su objeto correspondiente. Por lo tanto, pueden definir un número arbitrario de argumentos, que pueden ser requeridos, tener un tipo, y pueden tener un valor por defecto. Los argumentos de un constructor son llamados colocando los argumentos dentro de paréntesis después del nombre de la clase.

Ejemplo #2 Utilizar los argumentos de un constructor

    <?php
    class Point {
        protected int $x;
        protected int $y;

        public function __construct(int $x, int $y = 0) {
            $this->x = $x;
            $this->y = $y;
        }
    }

    // Pasar ambos parámetros.
    $p1 = new Point(4, 5);
    // Pasar solo el parámetro requerido. $y tomará su valor por defecto de 0.
    $p2 = new Point(4);
    // Con parámetros nombrados (a partir de PHP 8.0):
    $p3 = new Point(y: 5, x: 4);
    ?>

Si una clase no tiene un constructor, o si el constructor no tiene argumentos requeridos, los paréntesis pueden ser omitidos.

#### Estilo antiguo de los constructores

Anterior a PHP 8.0.0, las clases en el espacio de nombres global interpretarán un método que tenga el mismo nombre que la clase como un constructor de estilo antiguo. Esta sintaxis está obsoleta, y resultará en un error `E_DEPRECATED` pero llamará a esta función como un constructor. Si __construct() y un método con el mismo nombre están definidos, __construct() será llamado.

Las clases en espacios de nombres, o cualquier clase a partir de PHP 8.0.0, un método con el mismo nombre que la clase nunca tiene un significado particular.

Siempre utilizar __construct() en nuevo código.

#### Promoción del Constructor

A partir de PHP 8.0.0, los parámetros del constructor pueden ser promovidos para corresponder a una propiedad del objeto. Es muy común que los parámetros de un constructor sean asignados a una propiedad sin realizar operaciones sobre ellos. La promoción del constructor proporciona un atajo para este caso de uso. El ejemplo anterior puede ser reescrito de la siguiente manera.

Ejemplo #3 Utilizando la promoción de propiedad de constructor

    <?php
    class Point {
        public function __construct(protected int $x, protected int $y = 0) {
        }
    }

Cuando un argumento de constructor incluye un modificador, PHP lo interpretará como una propiedad de objeto y un argumento del constructor, y asignará el valor del argumento a la propiedad. El cuerpo del constructor puede estar entonces vacío o puede contener otras declaraciones. Todas las declaraciones adicionales serán ejecutadas después de que el valor del argumento haya sido asignado a su propiedad correspondiente.

Todos los argumentos no necesitan ser promovidos. Es posible mezclar y combinar los argumentos promovidos y no promovidos, en cualquier orden. Los argumentos promovidos no tienen ningún impacto en el código que llama al constructor.

> Nota:

> Utilizar un modificador de visibilidad (`public`, `protected` o `private`) es la manera más probable de aplicar la promoción de propiedad, pero cualquier otro modificador único (como `readonly`) tendrá el mismo efecto.

> Nota:

> Las propiedades de objeto no pueden ser tipadas callable debido a las ambigüedades del motor que esto introduciría. Por lo tanto, los argumentos promovidos, tampoco pueden ser tipados callable. Sin embargo, cualquier otra declaración de tipo está permitida.

> Nota:

> Como las propiedades promovidas son a la vez desucradas a una propiedad y también como el parámetro de una función, todas las restricciones de nombramiento para las propiedades y los parámetros se aplican.

> Nota:

> Los atributos colocados sobre un argumento de constructor promovido serán replicados tanto en la propiedad como en el argumento. Los valores por defecto en un argumento de constructor promovido solo serán replicados en el argumento y no en la propiedad.

#### Novedades en inicializadores

A partir de PHP 8.1.0, los objetos pueden ser utilizados como valor por defecto para los parámetros, variables estáticas, constantes globales y los argumentos de atributos. Los objetos pueden ser ahora pasados a define().

> Nota:

> El uso de un nombre de clase dinámico o no-string o una clase anónima no está permitido. El uso del desempacado de argumentos no está permitido. El uso de expresiones no soportadas como argumento no está permitido.

Ejemplo #4 Uso de new en inicializadores

    <?php

    // Todos permitidos:
    static $x = new Foo;

    const C = new Foo;

    function test($param = new Foo) {}

    #[AnAttribute(new Foo)]
    class Test {
        public function __construct(
            public $prop = new Foo,
        ) {}
    }

    // Todos no permitidos (error de compilación):
    function test(
        $a = new (CLASS_NAME_CONSTANT)(), // nombre de clase dinámico
        $b = new class {}, // clase anónima
        $c = new A(...[]), // desempacado de argumentos
        $d = new B($abc), // expresión de constante no soportada
    ) {}
    ?>

#### Método de creación estático

PHP soporta únicamente un constructor por clase. Sin embargo, en ciertos casos puede ser deseable permitir que un objeto sea construido de manera diferente con entradas diferentes. La forma recomendada de hacer esto es utilizando métodos estáticos como una envolvente del constructor.

Ejemplo #5 Utilizando la creación mediante un método estático

    <?php
    $some_json_string = '{ "id": 1004, "name": "Elephpant" }';
    $some_xml_string = "<animal><id>1005</id><name>Elephpant</name></animal>";

    class Product {

        private ?int $id;
        private ?string $name;

        private function __construct(?int $id = null, ?string $name = null) {
            $this->id = $id;
            $this->name = $name;
        }

        public static function fromBasicData(int $id, string $name): static {
            $new = new static($id, $name);
            return $new;
        }

        public static function fromJson(string $json): static {
            $data = json_decode($json, true);
            return new static($data['id'], $data['name']);
        }

        public static function fromXml(string $xml): static {
            $data = simplexml_load_string($xml);
            $new = new static();
            $new->id = (int) $data->id;
            $new->name = $data->name;
            return $new;
        }
    }

    $p1 = Product::fromBasicData(5, 'Widget');
    $p2 = Product::fromJson($some_json_string);
    $p3 = Product::fromXml($some_xml_string);

    var_dump($p1, $p2, $p3);

El constructor puede ser hecho privado o protegido para evitar su llamada desde el exterior. En este caso, solo un método estático será capaz de instanciar la clase. Puesto que están en la misma definición de clase, tienen acceso a los métodos privados, incluso en una instancia diferente del objeto. Un constructor privado es opcional y puede o no tener sentido dependiendo del caso de uso.

Los tres métodos estáticos públicos demuestran entonces diferentes maneras de instanciar el objeto.

- `fromBasicData()` toma los parámetros exactos que son necesarios, luego crea el objeto llamando al constructor y retornando el resultado.
- `fromJson()` acepta una cadena de caracteres JSON y realiza un preprocesamiento sobre sí mismo para convertirse en el formato deseado por el constructor. Luego retorna el nuevo objeto.
- `fromXml()` acepta una cadena de caracteres XML, realiza un preprocesamiento, luego crea un objeto bruto. El constructor es llamado, pero como todos los parámetros son opcionales el método los ignora. Luego asigna los valores a las propiedades del objeto directamente antes de retornar el resultado.

En los tres casos, la palabra clave `static` es traducida al nombre de la clase de la cual el código se encuentra. En este caso, `Product`.

### Destructor

function __destruct(): void

PHP posee un concepto de destructor similar al de otros lenguajes orientados a objeto, como el C++. El método destructor es llamado tan pronto como ya no hay referencias a un objeto dado, o en cualquier orden durante la secuencia de parada.

Ejemplo #6 Ejemplo con un Destructor

    <?php

    class MyDestructableClass
    {
        function __construct() {
            print "In constructor\n";
        }

        function __destruct() {
            print "Destroying " . __CLASS__ . "\n";
        }
    }

    $obj = new MyDestructableClass();

Al igual que el constructor, el destructor padre no será llamado implícitamente por el motor. Para ejecutar el destructor padre, se debe llamar explícitamente a la función parent::__destruct() en el cuerpo del destructor. Al igual que los constructores, una clase hija puede heredar el destructor del padre si no lo implementa ella misma.

El destructor será llamado incluso si la ejecución del script es detenida utilizando la función exit(). Llamar a la función exit() en un destructor evitará la ejecución de las rutinas de parada restantes.

Si un destructor crea nuevas referencias a su objeto, no será llamado una segunda vez cuando el contador de referencias alcance nuevamente cero o durante la secuencia de parada.

A partir de PHP 8.4.0, cuando la colección de ciclos ocurre durante la ejecución de una fibra, los destructores de los objetos programados para la colección son ejecutados en una fibra distinta, llamada `gc_destructor_fiber`. Si esta fibra es suspendida, una nueva fibra será creada para ejecutar los destructores restantes. La anterior `gc_destructor_fiber` ya no será referenciada por el recolector de basura y podrá ser colectada si no es referenciada en otro lugar. Los objetos cuyo destructor está suspendido no serán colectados hasta que el destructor haya terminado o que la fibra misma sea colectada.

> Nota:

> Los destructores llamados durante la parada del script están en una situación donde los encabezados HTTP ya han sido enviados. La carpeta de trabajo en la fase de parada del script puede ser diferente con ciertas APIs (ej. Apache).

> Nota:

> Intentar lanzar una excepción desde un destructor (llamado al final del script) resulta en un error fatal.

## Visibilidad

La visibilidad de una propiedad, un método o (a partir de PHP 7.1.0) una constante puede ser definida prefijando su declaración con una palabra clave: `public`, `protected`, o `private`. Los elementos declarados como públicos son accesibles en cualquier lugar. El acceso a los elementos protegidos está limitado a la clase misma, y mediante clases heredadas y a las clases padre. A los miembros declarados como privados solo puede acceder la clase que los ha definido.

### Visibilidad de las propiedades

Las propiedades de las clases pueden ser definidas como públicas, privadas o protegidas. Las propiedades declaradas sin utilizar explícitamente una palabra clave de visibilidad serán automáticamente definidas como públicas.

Ejemplo #1 Declaración de propiedades

    <?php
    /**
     * Definición de MyClass
     */
    class MyClass
    {
        public $public = 'Public';
        protected $protected = 'Protected';
        private $private = 'Private';

        function printHello()
        {
            echo $this->public;
            echo $this->protected;
            echo $this->private;
        }
    }

    $obj = new MyClass();
    echo $obj->public; // Funciona
    echo $obj->protected; // Error fatal
    echo $obj->private; // Error fatal
    $obj->printHello(); // Muestra Public, Protected y Private

    /**
     * Definición de MyClass2
     */
    class MyClass2 extends MyClass
    {
        // Se pueden redeclarar las propiedades públicas o protegidas, pero no las privadas
        public $public = 'Public2';
        protected $protected = 'Protected2';

        function printHello()
        {
          echo $this->public;
          echo $this->protected;
          echo $this->private;
        }
    }

    $obj2 = new MyClass2();
    echo $obj2->public; // Funciona
    echo $obj2->protected; // Error fatal
    echo $obj2->private; // Indefinido
    $obj2->printHello(); // Muestra Public2, Protected2 y Undefined (Indefinido)

    ?>

#### Visibilidad Asimétrica de las Propiedades

A partir de PHP 8.4, las propiedades de objeto pueden también tener su visibilidad definida de manera asimétrica, con un campo diferente para la lectura (`get`) y la escritura (`set`). Más precisamente, la visibilidad `set` puede ser especificada separadamente, siempre que no sea más permisiva que la visibilidad por defecto.

Ejemplo #2 Visibilidad Asimétrica de las Propiedades

    <?php
    class Book
    {
        public function __construct(
            public private(set) string $title,
            public protected(set) string $author,
            protected private(set) int $pubYear,
        ) {}
    }

    class SpecialBook extends Book
    {
        public function update(string $author, int $year): void
        {
            $this->author = $author; // OK
            $this->pubYear = $year; // Error Fatal
        }
    }

    $b = new Book('Cómo usar PHP', 'Peter H. Peterson', 2024);

    echo $b->title; // Funciona
    echo $b->author; // Funciona
    echo $b->pubYear; // Error Fatal

    $b->title = 'Cómo no usar PHP'; // Error Fatal
    $b->author = 'Pedro H. Peterson'; // Error Fatal
    $b->pubYear = 2023; // Error Fatal
    ?>

A partir de PHP 8.5, la visibilidad `set` también puede ser aplicada a las propiedades estáticas de las clases.

Ejemplo #3 Visibilidad Asimétrica de Propiedades Estáticas

    <?php
    class Manager
    {
        public private(set) static int $calls = 0;

        public function doAThing(): string
        {
            self::$calls++;
            // Hacer otras cosas.
            return "alguna cadena";
        }
    }

    $m = new Manager();

    $m->doAThing(); // Funciona
    echo Manager::$calls; // Funciona
    Manager::$calls = 5; // Error fatal
    ?>

El ejemplo anterior mostrará:

    1
    Fatal error: Uncaught Error: Cannot modify private(set) property Manager::$calls from global scope in /some/file.php

Hay algunas reservas concernientes a la visibilidad asimétrica:

- Solo las propiedades tipadas pueden tener una visibilidad `set` separada.
- La visibilidad `set` debe ser la misma que `get` o más restrictiva. Es decir, `public protected(set)` y `protected protected(set)` están permitidos, pero `protected public(set)` provocará un error de sintaxis.
- Si una propiedad es `public`, entonces la visibilidad principal puede ser omitida. Es decir, `public private(set)` y `private(set)` tendrán el mismo resultado.
- Una propiedad con una visibilidad `private(set)` es automáticamente `final`, y no puede ser redefinida en una clase hija.
- Obtener una referencia a una propiedad sigue la visibilidad `set`, no `get`. Esto se debe a que una referencia puede ser utilizada para modificar el valor de la propiedad.
- De igual manera, intentar escribir en una propiedad de array implica tanto una operación `get` como una operación `set` internamente, y seguirá por lo tanto la visibilidad `set`, ya que es siempre la más restrictiva.

> Nota: Los espacios no están permitidos en la declaración de visibilidad para la modificación. `private(set)` es correcto. `private( set )` no es correcto y resultará en un error de análisis.

Cuando una clase extiende a otra, la clase hija puede redefinir cualquier propiedad que no sea `final`. Al hacerlo, puede ampliar tanto la visibilidad principal como la visibilidad `set`, siempre que la nueva visibilidad sea la misma o más amplia que la de la clase padre. Sin embargo, tenga en cuenta que si una propiedad `private` es reemplazada, esto no cambia realmente la propiedad de la clase padre, sino que crea una nueva propiedad con un nombre interno diferente.

Ejemplo #4 Herencia de Propiedades Asimétricas

    <?php
    class Book
    {
        protected string $title;
        public protected(set) string $author;
        protected private(set) int $pubYear;
    }

    class SpecialBook extends Book
    {
        public protected(set) string $title; // OK, ya que la lectura es más amplia y la escritura es la misma.
        public string $author; // OK, ya que la lectura es la misma y la escritura es más amplia.
        public protected(set) int $pubYear; // Error Fatal. Las propiedades private(set) son finales.
    }
    ?>

### Visibilidad de los métodos

Los métodos de las clases pueden ser definidos como públicos, privados o protegidos. Los métodos declarados sin utilizar explícitamente una palabra clave de visibilidad serán automáticamente definidos como públicos.

Ejemplo #5 Declaración de métodos

    <?php
    /**
     * Definición de MyClass
     */
    class MyClass
    {
        // Declara un constructor público
        public function __construct() { }

        // Declara un método público
        public function MyPublic() { }

        // Declara un método protegido
        protected function MyProtected() { }

        // Declara un método privado
        private function MyPrivate() { }

        // Este será público
        function Foo()
        {
            $this->MyPublic();
            $this->MyProtected();
            $this->MyPrivate();
        }
    }

    $myclass = new MyClass;
    $myclass->MyPublic(); // Funciona
    $myclass->MyProtected(); // Error fatal
    $myclass->MyPrivate(); // Error fatal
    $myclass->Foo(); // Public, Protected y Private funcionan

    /**
     * Definición de MyClass2
     */
    class MyClass2 extends MyClass
    {
        // Este será público
        function Foo2()
        {
            $this->MyPublic();
            $this->MyProtected();
            $this->MyPrivate(); // Error fatal
        }
    }

    $myclass2 = new MyClass2;
    $myclass2->MyPublic(); // Funciona
    $myclass2->Foo2(); // Public y Protected funcionan, no Private

    class Bar
    {
        public function test() {
            $this->testPrivate();
            $this->testPublic();
        }

        public function testPublic() {
            echo "Bar::testPublic\n";
        }

        private function testPrivate() {
            echo "Bar::testPrivate\n";
        }
    }

    class Foo extends Bar
    {
        public function testPublic() {
            echo "Foo::testPublic\n";
        }

        private function testPrivate() {
            echo "Foo::testPrivate\n";
        }
    }

    $myFoo = new Foo();
    $myFoo->test(); // Bar::testPrivate
                    // Foo::testPublic
    ?>

### Visibilidad de las constantes

A partir de PHP 7.1.0, las constantes de clases pueden ser definidas como públicas, privadas o protegidas. Las constantes declaradas sin una palabra clave de visibilidad explícita son definidas como públicas.

Ejemplo #6 Declaración de constantes a partir de PHP 7.1.0

    <?php
    /**
     * Declaremos MyClass
     */
    class MyClass
    {
        // Declaremos una constante pública
        public const MY_PUBLIC = 'public';

        // Declaremos una constante protegida
        protected const MY_PROTECTED = 'protected';

        // Declaremos una constante privada
        private const MY_PRIVATE = 'private';

        public function foo()
        {
            echo self::MY_PUBLIC;
            echo self::MY_PROTECTED;
            echo self::MY_PRIVATE;
        }
    }

    $myclass = new MyClass();
    MyClass::MY_PUBLIC; // Funciona
    MyClass::MY_PROTECTED; // Error fatal
    MyClass::MY_PRIVATE; // Error fatal
    $myclass->foo(); // Public, Protegida y Privada funcionan

    /**
     * Definir MyClass2
     */
    class MyClass2 extends MyClass
    {
        // Esto es público
        function foo2()
        {
            echo self::MY_PUBLIC;
            echo self::MY_PROTECTED;
            echo self::MY_PRIVATE; // Error fatal
        }
    }

    $myclass2 = new MyClass2;
    echo MyClass2::MY_PUBLIC; // Funciona
    $myclass2->foo2(); // Public y Protegida funcionan, pero no Privada
    ?>

### Visibilidad desde otros objetos

Los objetos de mismos tipos tienen acceso a los miembros privados y protegidos de los otros, incluso si no son la misma instancia. Esto se debe a que los detalles específicos de la implementación ya son conocidos internamente por estos objetos.

Ejemplo #7 Acceso a los miembros privados de un objeto del mismo tipo

    <?php
    class Test
    {
        private $foo;

        public function __construct($foo)
        {
            $this->foo = $foo;
        }

        private function bar()
        {
            echo 'Acceso al método privado.';
        }

        public function baz(Test $other)
        {
            // Podemos modificar la propiedad privada:
            $other->foo = 'Hola';
            var_dump($other->foo);

            // También podemos llamar al método privado:
            $other->bar();
        }
    }

    $test = new Test('test');

    $test->baz(new Test('other'));
    ?>

El ejemplo anterior mostrará:

    string(5) "Hola"
    Acceso al método privado.

## Herencia

La herencia es uno de los grandes principios de la programación orientada a objetos (POO), y PHP la implementa en su modelo de objetos. Este principio afectará la manera en que muchas clases están relacionadas entre sí.

Por ejemplo, cuando una clase es extendida, la clase hija hereda todas las métodos públicos y protegidos, propiedades y constantes de la clase padre. Mientras una clase no sobrescriba estos métodos, conservan su funcionalidad original.

La herencia es muy útil para definir y abstraer ciertas funcionalidades comunes a varias clases, permitiendo al mismo tiempo la implementación de funcionalidades adicionales en las clases hijas, sin tener que reimplementar en su interior todas las funcionalidades comunes.

Los métodos privados de una clase padre no son accesibles para la clase hija. Por consiguiente, las clases hijas pueden reimplementar un método privado por sí mismas sin preocuparse por las reglas normales de herencia. Anterior a PHP 8.0.0, sin embargo, las restricciones `final` y `static` se aplicaban a los métodos privados. A partir de PHP 8.0.0, la única restricción de método privado que se impone es `private final` en los constructores, ya que es una manera común para "desactivar" el constructor cuando se utilizan métodos de fábrica estáticos en su lugar.

La visibilidad de los métodos, propiedades y constantes puede ser relajada, es decir, un método `protected` puede ser marcado como `public`, pero no pueden ser restringidos, por ejemplo, marcar una propiedad `public` como `private`. Una excepción son los constructores, para los cuales la visibilidad puede ser restringida, por ejemplo, un constructor `public` puede ser anotado como `private` en la clase hija.

> Nota:

> A menos que se utilice la autocarga, las clases deben ser conocidas antes de ser utilizadas. Las clases padres deben ser definidas antes de escribir una herencia. Esta regla general se aplica también en el caso de herencia o implementación de interfaces.

> Nota:

> No está permitido redefinir una propiedad de lectura-escritura con una propiedad de solo lectura o viceversa.

>     <?php

>     class A {
>         public int $prop;
>     }
>     class B extends A {
>         // Ilegal: lectura-escritura -> readonly
>         public readonly int $prop;
>     }
>     ?>

Ejemplo #1 Ejemplo de herencia

    <?php

    class Foo
    {
        public function printItem($string)
        {
            echo 'Foo: ' . $string . PHP_EOL;
        }

        public function printPHP()
        {
            echo 'PHP es genial.' . PHP_EOL;
        }
    }

    class Bar extends Foo
    {
        public function printItem($string)
        {
            echo 'Bar: ' . $string . PHP_EOL;
        }
    }

    $foo = new Foo();
    $bar = new Bar();
    $foo->printItem('baz'); // Muestra: 'Foo: baz'
    $foo->printPHP();       // Muestra: 'PHP es genial.'
    $bar->printItem('baz'); // Muestra: 'Bar: baz'
    $bar->printPHP();       // Muestra: 'PHP es genial.'

    ?>

### Compatibilidad de los tipos de retorno con las clases internas

Anterior a PHP 8.1, la mayoría de las clases o métodos internos no declaraban su tipo de retorno, y cualquier tipo de retorno estaba permitido al heredarlos.

A partir de PHP 8.1.0, la mayoría de los métodos internos comenzaron a declarar "provisionalmente" su tipo de retorno, en este caso, el tipo de retorno de los métodos debe ser compatible con la clase padre; en caso contrario, se emite una notificación de deprecación. Tenga en cuenta que la ausencia de una declaración de retorno explícita también se considera un error de firma, y por lo tanto provoca el aviso de deprecación.

Si el tipo de retorno no puede ser declarado para un método de sobrecarga debido a problemas de compatibilidad entre versiones de PHP, un atributo ReturnTypeWillChange puede ser añadido para silenciar el aviso de deprecación.

Ejemplo #2 El método sobrecargado no declara tipo de retorno.

    <?php

    class MyDateTime extends DateTime
    {
        public function modify(string $modifier) { return false; }
    }

    // "Deprecated: Return type of MyDateTime::modify(string $modifier) should either be compatible with DateTime::modify(string $modifier): DateTime|false, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice" A partir de PHP 8.1.0

Ejemplo #3 El método sobrecargado declara un tipo de retorno incorrecto.

    <?php

    class MyDateTime extends DateTime
    {
        public function modify(string $modifier): ?DateTime { return null; }
    }

    // "Deprecated: Return type of MyDateTime::modify(string $modifier): ?DateTime should either be compatible with DateTime::modify(string $modifier): DateTime|false, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice" A partir de PHP 8.1.0

Ejemplo #4 El método sobrecargado declara un tipo de retorno incorrecto sin aviso de deprecación.

    <?php

    class MyDateTime extends DateTime
    {
        /**
         * @return DateTime|false
         */
        #[\ReturnTypeWillChange]
        public function modify(string $modifier) { return false; }
    }

    // No se emite ningún aviso

## El operador de resolución de ámbito (::)

El operador de resolución de ámbito (también llamado Paamayim Nekudotayim) o, en términos más simples, el símbolo "doble dos puntos" (::), proporciona un medio para acceder a los miembros una constante, una propiedad estática, o un método estático de una clase o de una de sus clases padre. Además, las propiedades o métodos estáticos pueden ser sobrecargados vía la ligadura estática tardía.

Cuando se hace referencia a estos elementos fuera de la definición de la clase, se utiliza el nombre de la clase.

Es posible referenciar una clase utilizando una variable. El valor de la variable no puede ser una palabra clave (e.g. `self`, `parent` y `static`).

Paamayim Nekudotayim podría parecer al principio una elección extraña para nombrar un doble dos puntos. Sin embargo, en el momento de la escritura del Zend Engine 0.5 (que hacía funcionar PHP 3), fue el nombre elegido por el equipo Zend. De hecho, esto significa un doble dos puntos... ¡en hebreo!

Ejemplo #1 :: fuera de la definición de la clase

    <?php
    class MyClass {
        const CONST_VALUE = 'Un valor constante';
    }

    $classname = 'MyClass';
    echo $classname::CONST_VALUE;

    echo MyClass::CONST_VALUE;
    ?>

Tres palabras clave especiales, self, parent, y static son utilizadas para acceder a las propiedades o a los métodos desde la definición de la clase.

Ejemplo #2 :: desde la definición de la clase

    <?php
    class MyClass {
        const CONST_VALUE = 'Un valor constante';
    }

    class OtherClass extends MyClass
    {
        public static $my_static = 'variable estática';

        public static function doubleColon() {
            echo parent::CONST_VALUE . "\n";
            echo self::$my_static . "\n";
        }
    }

    $classname = 'OtherClass';
    $classname::doubleColon();

    OtherClass::doubleColon();
    ?>

Cuando una clase que hereda de otra redefine un método de su clase padre, PHP no llamará al método de la clase padre. Es responsabilidad del método derivado llamar al método original en caso de necesidad. Esto también es válido para las definiciones de los constructores y destructores, la sobrecarga, y las definiciones de métodos mágicos.

Ejemplo #3 Llamada a un método padre

    <?php
    class MyClass
    {
        protected function myFunc() {
            echo "MyClass::myFunc()\n";
      }
    }

    class OtherClass extends MyClass
    {
        // Sobrecarga de la definición padre
        public function myFunc() {

          // Pero llamada al método padre
          parent::myFunc();
          echo "OtherClass::myFunc()\n";
      }
    }

    $class = new OtherClass();
    $class->myFunc();
    ?>

Ver también algunos ejemplos de llamadas estáticas.

## Estático

Sugerencia

Esta página describe el uso de la palabra clave `static` que permite definir métodos y propiedades estáticas. `static` también puede ser utilizado para definir variables estáticas, definir funciones anónimas estáticas y para Resoluciones estáticas a la volada. Consulte estas páginas para obtener más información sobre el significado de `static`.

Declarar propiedades o métodos como estáticos permite acceder a ellos sin necesidad de instanciar la clase. Estos pueden ser accedidos estáticamente desde una instancia de objeto.

### Métodos estáticos

Dado que los métodos estáticos pueden ser llamados sin que una instancia de objeto haya sido creada, la pseudo-variable $this no está disponible en los métodos declarados como estáticos.

Advertencia

Llamar a un método no estático estáticamente lanzará una Error.

Anterior a PHP 8.0.0, llamar a un método no estático estáticamente era obsoleto, y generaba un aviso `E_DEPRECATED`.

Ejemplo #1 Ejemplo con un método estático

    <?php
    class Foo
    {
        public static function aStaticMethod() {
            // ...
        }
    }

    Foo::aStaticMethod();
    $classname = 'Foo';
    $classname::aStaticMethod();
    ?>

### Propiedades estáticas

Las propiedades estáticas son accedidas utilizando el operador de resolución de ámbito (`::`) y no pueden ser accedidas a través del operador objeto (`->`).

Es posible referenciar la clase utilizando una variable. El valor de la variable no puede ser una palabra clave (por ejemplo `self`, `parent` y `static`).

Ejemplo #2 Ejemplo con una propiedad estática

    <?php
    class Foo
    {
        public static $my_static = 'foo';

        public function staticValue() {
            return self::$my_static;
        }
    }

    class Bar extends Foo
    {
        public function fooStatic() {
            return parent::$my_static;
        }
    }

    print Foo::$my_static . "\n";

    $foo = new Foo();
    print $foo->staticValue() . "\n";
    print $foo->my_static . "\n";      // "Propiedad" my_static no definida

    print $foo::$my_static . "\n";
    $classname = 'Foo';
    print $classname::$my_static . "\n";

    print Bar::$my_static . "\n";
    $bar = new Bar();
    print $bar->fooStatic() . "\n";
    ?>

Resultado del ejemplo anterior en PHP 8 es similar a:

    foo
    foo
    Notice: Accessing static property Foo::$my_static as non static in /in/V0Rvv on line 23
    Warning: Undefined property: Foo::$my_static in /in/V0Rvv on line 23
    foo
    foo
    foo
    foo

## Abstracción de clases

PHP tiene clases, métodos y propiedades abstractas. Las clases definidas como abstractas no pueden ser instanciadas, y cualquier clase que contenga al menos un método abstracto debe ser también abstracta. Los métodos definidos como abstractos se contentan con declarar la firma del método y con indicar si es público o protegido; no pueden definir la implementación. Las propiedades definidas como abstractas pueden declarar un requisito para el comportamiento de `get` o de `set`, y pueden proporcionar una implementación para una de estas operaciones, pero no para ambas.

Al heredar de una clase abstracta, todos los métodos marcados como abstractos en la declaración de la clase padre deben ser definidos por la clase hija y seguir las reglas habituales de herencia y de compatibilidad de firma.

A partir de PHP 8.4, una clase abstracta puede declarar una propiedad abstracta, pública o protegida. Una propiedad abstracta protegida puede ser satisfecha por una propiedad accesible en lectura/escritura desde un contexto protegido o público.

Una propiedad abstracta puede ser satisfecha ya sea por una propiedad estándar, ya sea por una propiedad con hooks definidos, correspondiente a la operación requerida.

Ejemplo #1 Ejemplo de método abstracto

    <?php

    abstract class AbstractClass
    {
        // Fuerza a las clases hijas a definir este método
        abstract protected function getValue();
        abstract protected function prefixValue($prefix);

        // método común
       public function printOut()
       {
            print $this->getValue() . "\n";
       }
    }

    class ConcreteClass1 extends AbstractClass
    {
         protected function getValue()
         {
           return "ConcreteClass1";
         }

         public function prefixValue($prefix)
         {
           return "{$prefix}ConcreteClass1";
         }
    }

    class ConcreteClass2 extends AbstractClass
    {
         public function getValue()
         {
           return "ConcreteClass2";
         }

         public function prefixValue($prefix)
         {
           return "{$prefix}ConcreteClass2";
         }
    }

    $class1 = new ConcreteClass1();
    $class1->printOut();
    echo $class1->prefixValue('FOO_'), "\n";

    $class2 = new ConcreteClass2();
    $class2->printOut();
    echo $class2->prefixValue('FOO_'), "\n";

    ?>

El ejemplo anterior mostrará:

    ConcreteClass1
    FOO_ConcreteClass1
    ConcreteClass2
    FOO_ConcreteClass2

Ejemplo #2 Ejemplo de método abstracto

    <?php

    abstract class AbstractClass
    {
        // Un método abstracto solo debe definir los argumentos requeridos
        abstract protected function prefixName($name);

    }

    class ConcreteClass extends AbstractClass
    {

        // Una clase hija puede definir argumentos opcionales que no están presentes en la firma del padre
         public function prefixName($name, $separator = ".")
         {
            if ($name == "Pacman") {
                $prefix = "Mr";
            } elseif ($name == "Pacwoman") {
                $prefix = "Mrs";
            } else {
                $prefix = "";
            }

            return "{$prefix}{$separator} {$name}";
        }
    }

    $class = new ConcreteClass();
    echo $class->prefixName("Pacman"), "\n";
    echo $class->prefixName("Pacwoman"), "\n";

    ?>

El ejemplo anterior mostrará:

    Mr. Pacman
    Mrs. Pacwoman

Ejemplo #3 Ejemplo de propiedad abstracta

    <?php

    abstract class A
    {
        // Las clases derivadas deben tener una propiedad públicamente accesible en lectura.
        abstract public string $readable {
            get;
        }

        // Las clases derivadas deben tener una propiedad modificable en escritura, protegida o pública.
         abstract protected string $writeable {
             set;
        }

        // Las clases derivadas deben tener una propiedad simétrica protegida o pública.
         abstract protected string $both {
             get;
             set;
         }
    }

    class C extends A
    {
        // Esto satisface el requisito y también hace que la propiedad sea modificable, lo cual es válido.
        public string $readable;

        // Esto NO satisfaría el requisito, ya que la propiedad no es públicamente accesible en lectura.
        protected string $readable;

        // Esto satisface exactamente el requisito, por lo que es suficiente.
        // La propiedad solo puede ser modificada desde un contexto protegido.
        protected string $writeable {
            set => $value;
        }

        // Esto amplía la visibilidad de protegido a público, lo cual es aceptable.
        public string $both;
    }
    ?>

Una propiedad abstracta en una clase abstracta puede proporcionar implementaciones para cualquier punto de anclaje, pero debe tener `get` o `set` declarados pero no definidos (como en el ejemplo anterior).

Ejemplo #4 Ejemplo de propiedad abstracta con hooks

    <?php

    abstract class A
    {
        // Esto proporciona una implementación por defecto (pero sustituible) para set,
        // y exige que las clases derivadas proporcionen una implementación para get.
        abstract public string $foo {
            get;

            set {
                $this->foo = $value
            };
        }
    }

    ?>

## Interfaces

Las interfaces de objetos permiten crear código que especifica qué métodos y propiedades una clase debe implementar, sin tener que definir cómo se implementan estos métodos o propiedades. Las interfaces comparten un espacio de nombres con las clases, traits y enumeraciones, de modo que no pueden utilizar el mismo nombre.

Las interfaces se definen de la misma manera que una clase, pero utilizando la palabra clave `interface` en lugar de `class`, y sin que ninguno de los métodos tenga su contenido especificado.

Por la naturaleza misma de una interfaz, todos los métodos declarados en una interfaz deben ser públicos.

En la práctica, las interfaces sirven dos roles complementarios:

- Permitir a los desarrolladores crear objetos de clases diferentes que pueden ser utilizados de manera intercambiable, ya que implementan la o las mismas interfaces. Un ejemplo común son varios servicios de acceso a bases de datos, varios gestores de pago o diferentes estrategias de caché. Diferentes implementaciones pueden ser intercambiadas sin necesitar cambios en el código que las utiliza.
- Para permitir que una función o método acepte y opere sobre un argumento que se ajuste a una interfaz, sin preocuparse de qué más puede hacer el objeto o cómo está implementado. Estas interfaces suelen llamarse `Iterable`, `Cacheable`, `Renderable`, etc. para describir el significado de su comportamiento.

Las interfaces pueden definir métodos mágicos para obligar a las clases que las implementan a implementar estos métodos.

> Nota:

> Aunque esto es soportado, incluir los constructores en las interfaces está fuertemente desaconsejado. Hacerlo reduce radicalmente la flexibilidad de los objetos que implementan la interfaz. Además, los constructores no están sujetos a las reglas de herencia, lo que puede causar incoherencias y comportamientos inesperados.

### `implements`

Para implementar una interfaz, se utiliza el operador `implements`. Todos los métodos de la interfaz deben ser implementados en una clase; si no es así, se emitirá un error fatal. Las clases pueden implementar más de una interfaz, separando cada interfaz por una coma.

Advertencia

Una clase que implementa una interfaz puede utilizar nombres diferentes para sus argumentos que la interfaz. Sin embargo, a partir de PHP 8.0, el lenguaje soporta los argumentos nombrados, lo que significa que el llamador puede depender del nombre del argumento en la interfaz. Por esta razón, se recomienda encarecidamente que los desarrolladores utilicen el mismo nombre de argumento que en la interfaz que se implementa.

> Nota:

> Las interfaces pueden ser extendidas como clases, utilizando el operador extends

> Nota:

> La clase que implementa la interfaz debe declarar todos los métodos en la interfaz con una firma compatible. Una clase puede implementar dos interfaces que definan un método con el mismo nombre. En este caso, la implementación debe seguir las reglas de compatibilidad de firmas para todas las interfaces. Así, la covarianza y la contravarianza pueden ser aplicadas.

### Las constantes

Las interfaces pueden contener constantes. Las constantes de interfaces funcionan exactamente como las constantes de clase. Anterior a PHP 8.1.0, no pueden ser redefinidas por una clase/interfaz que las hereda.

### Propiedades

A partir de PHP 8.4.0, las interfaces también pueden declarar propiedades. Si lo hacen, la declaración debe especificar si la propiedad es legible, modificable, o ambas. La declaración de la interfaz se aplica únicamente al acceso en lectura y escritura públicos.

Una clase puede satisfacer una propiedad de interfaz de varias maneras. Puede definir una propiedad pública. Puede definir una propiedad pública virtual que implemente únicamente el crochet correspondiente. O una propiedad de lectura puede ser satisfecha por una propiedad `readonly`. Sin embargo, una propiedad de interfaz que es modificable no puede ser `readonly`.

Ejemplo #1 Ejemplo de propiedades de interfaz

    <?php
    interface I
    {
        // Una clase que implementa esta interfaz DEBE tener una propiedad públicamente legible,
        // pero que esta sea o no modificable públicamente no está restringido.
        public string $readable { get; }

        // Una clase que implementa esta interfaz DEBE tener una propiedad públicamente modificable,
        // pero que esta sea o no legible públicamente no está restringido.
        public string $writeable { set; }

        // Una clase que implementa esta interfaz DEBE tener una propiedad que sea a la vez públicamente
        // legible y públicamente modificable.
        public string $both { get; set; }
    }

    // Esta clase implementa las tres propiedades como propiedades tradicionales, sin crochets.
    // Esto es completamente válido.
    class C1 implements I
    {
        public string $readable;

        public string $writeable;

        public string $both;
    }

    // Esta clase implementa las tres propiedades utilizando únicamente los crochets
    // solicitados. Esto también es completamente válido.
    class C2 implements I
    {
        private string $written = '';
        private string $all = '';

        // Utiliza únicamente un crochet get para crear una propiedad virtual.
        // Esto satisface el requisito "get public".
        // No es modificable, pero esto no es requerido por la interfaz.
        public string $readable { get => strtoupper($this->writeable); }

        // La interfaz requiere únicamente que la propiedad sea modificable,
        // pero incluir operaciones get también es completamente válido.
        // Este ejemplo crea una propiedad virtual, lo cual es aceptable.
        public string $writeable {
            get => $this->written;
            set {
                $this->written = $value;
            }
        }

        // Esta propiedad requiere que la lectura y la escritura sean posibles,
        // por lo que debemos implementar ambas o permitir el comportamiento por defecto.
        public string $both {
            get => $this->all;
            set {
                $this->all = strtoupper($value);
            }
        }
    }
    ?>

### Ejemplos

Ejemplo #2 Ejemplo de interfaz

    <?php

    // Declaración de la interfaz 'Template'
    interface Template
    {
        public function setVariable($name, $var);
        public function getHtml($template);
    }

    // Implementación de la interfaz
    // Esto funcionará
    class WorkingTemplate implements Template
    {
        private $vars = [];

        public function setVariable($name, $var)
        {
            $this->vars[$name] = $var;
        }

        public function getHtml($template)
        {
            foreach($this->vars as $name => $value) {
                $template = str_replace('{' . $name . '}', $value, $template);
            }

            return $template;
        }
    }

    // Esto no funcionará
    // Fatal error: Class BadTemplate contains 1 abstract methods
    // and must therefore be declared abstract (Template::getHtml)
    class BadTemplate implements Template
    {
        private $vars = [];

        public function setVariable($name, $var)
        {
            $this->vars[$name] = $var;
        }
    }
    ?>

Ejemplo #3 Las interfaces extensibles

    <?php
    interface A
    {
        public function foo();
    }

    interface B extends A
    {
        public function baz(Baz $baz);
    }

    // Esto funcionará
    class C implements B
    {
        public function foo()
        {
        }

        public function baz(Baz $baz)
        {
        }
    }

    // Esto no funcionará y resultará en un error fatal
    class D implements B
    {
        public function foo()
        {
        }

        public function baz(Foo $foo)
        {
        }
    }
    ?>

Ejemplo #4 Compatibilidad de la varianza con múltiples interfaces

    <?php
    class Foo {}
    class Bar extends Foo {}

    interface A {
        public function myfunc(Foo $arg): Foo;
    }

    interface B {
        public function myfunc(Bar $arg): Bar;
    }

    class MyClass implements A, B
    {
        public function myfunc(Foo $arg): Bar
        {
            return new Bar();
        }
    }
    ?>

Ejemplo #5 Herencia de múltiples interfaces

    <?php
    interface A
    {
        public function foo();
    }

    interface B
    {
        public function bar();
    }

    interface C extends A, B
    {
        public function baz();
    }

    class D implements C
    {
        public function foo()
        {
        }

        public function bar()
        {
        }

        public function baz()
        {
        }
    }
    ?>

Ejemplo #6 Interfaces con constantes

    <?php
    interface A
    {
        const B = 'Constante de la interfaz';
    }

    // Muestra: Constante de la interfaz
    echo A::B;

    // Sin embargo, esto no funcionará, ya que no está permitido
    // sobrescribir constantes.
    class B implements A
    {
        const B = 'Constante de clase';
    }

    // Muestra: Constante de clase
    // Anterior a PHP 8.1.0, esto no funcionaría, ya que no estaba permitido
    // redefinir constantes.
    echo B::B;
    ?>

Ejemplo #7 Las interfaces con las clases abstractas

    <?php
    interface A
    {
        public function foo(string $s): string;

        public function bar(int $i): int;
    }

    // Una clase abstracta puede implementar solo una parte de una interfaz.
    // Las clases que extienden la clase abstracta deben implementar el resto.
    abstract class B implements A
    {
        public function foo(string $s): string
        {
            return $s . PHP_EOL;
        }
    }

    class C extends B
    {
        public function bar(int $i): int
        {
            return $i * 2;
        }
    }
    ?>

Ejemplo #8 Extendiendo e implementando simultáneamente

    <?php

    class One
    {
        /* ... */
    }

    interface Usable
    {
        /* ... */
    }

    interface Updatable
    {
        /* ... */
    }

    // El orden de las palabras clave aquí es importante. 'extends' debe ir primero.
    class Two extends One implements Usable, Updatable
    {
        /* ... */
    }
    ?>

Una interfaz, con las declaraciones de tipos, proporciona una buena manera de asegurarse de que un objeto particular contiene métodos particulares. Ver el operador instanceof y las declaraciones de tipo.

## Traits

PHP implementa una manera de reutilizar código llamada Traits.

Los traits son un mecanismo de reutilización de código en un lenguaje de herencia simple como PHP. Un trait intenta reducir ciertas limitaciones de la herencia simple, permitiendo al desarrollador reutilizar un cierto número de métodos en clases independientes. La sémantica entre las clases y los traits reduce la complejidad y evita los problemas típicos de la herencia múltiple y los Mixins.

Un trait es similar a una clase, pero solo sirve para agrupar funcionalidades de una manera interesante. No es posible instanciar un Trait en sí mismo. Es un añadido a la herencia tradicional, que permite la composición horizontal de comportamientos, es decir, el uso de métodos de clase sin necesidad de herencia.

Ejemplo #1 Ejemplo de uso de Trait

    <?php

    trait TraitA {
        public function sayHello() {
            echo 'Hello';
        }
    }

    trait TraitB {
        public function sayWorld() {
            echo 'World';
        }
    }

    class MyHelloWorld
    {
        use TraitA, TraitB; // Una clase puede usar múltiples traits

        public function sayHelloWorld() {
            $this->sayHello();
            echo ' ';
            $this->sayWorld();
            echo "!\n";
        }
    }

    $myHelloWorld = new MyHelloWorld();
    $myHelloWorld->sayHelloWorld();

    ?>

El ejemplo anterior mostrará:

    Hello World!

### Precedencia

Un método heredado desde una clase madre es sobrescrito por un método proveniente de un Trait. El orden de precedencia hace que los métodos de la clase actual sobrescriban los métodos provenientes de un Trait, ellos mismos sobrecargando los métodos heredados.

Ejemplo #2 Ejemplo con el orden de precedencia

Un método heredado desde la clase base es sobrescrito por el que proviene del Trait. No es el caso de los métodos reales, escritos en la clase base.

    <?php
    class Base {
        public function sayHello() {
            echo 'Hello ';
        }
    }

    trait SayWorld {
        public function sayHello() {
            parent::sayHello();
            echo 'World!';
        }
    }

    class MyHelloWorld extends Base {
        use SayWorld;
    }

    $o = new MyHelloWorld();
    $o->sayHello();
    ?>

El ejemplo anterior mostrará:

    Hello World!

Ejemplo #3 Otro ejemplo de orden de precedencia

    <?php
    trait HelloWorld {
        public function sayHello() {
            echo 'Hello World!';
        }
    }

    class TheWorldIsNotEnough {
        use HelloWorld;
        public function sayHello() {
            echo 'Hello Universe!';
        }
    }

    $o = new TheWorldIsNotEnough();
    $o->sayHello();
    ?>

El ejemplo anterior mostrará:

    Hello Universe!

### Múltiples Traits

Una clase puede usar múltiples Traits declarándolos con la palabra clave `use`, separados por comas.

Ejemplo #4 Uso de varios Traits

    <?php
    trait Hello {
        public function sayHello() {
            echo 'Hello ';
        }
    }

    trait World {
        public function sayWorld() {
            echo 'World';
        }
    }

    class MyHelloWorld {
        use Hello, World;
        public function sayExclamationMark() {
            echo '!';
        }
    }

    $o = new MyHelloWorld();
    $o->sayHello();
    $o->sayWorld();
    $o->sayExclamationMark();
    ?>

El ejemplo anterior mostrará:

    Hello World!

### Resolución de conflictos

Si dos Traits insertan un método con el mismo nombre, se produce un error fatal si el conflicto no es explícitamente resuelto.

Para resolver un conflicto de nombres entre Traits usados en la misma clase, se debe usar el operador `insteadof` para elegir uno de los métodos en conflicto.

Dado que este principio solo permite excluir métodos, el operador `as` puede ser usado para permitir la inclusión de uno de los métodos conflictivos bajo otro nombre. Se debe tener en cuenta que el operador `as` no renombra el método y no afecta a otros métodos tampoco.

Ejemplo #5 Resolución de conflictos

En este ejemplo, la clase Talker usa los traits A y B. Como A y B tienen métodos conflictivos, se indica que se desea usar la variante de smallTalk desde el trait B, y la variante de bigTalk desde el trait A.

La clase Aliased_Talker usa el operador `as` para poder usar la implementación bigTalk de B bajo un alias adicional `talk`.

    <?php
    trait A {
        public function smallTalk() {
            echo 'a';
        }
        public function bigTalk() {
            echo 'A';
        }
    }

    trait B {
        public function smallTalk() {
            echo 'b';
        }
        public function bigTalk() {
            echo 'B';
        }
    }

    class Talker {
        use A, B {
            B::smallTalk insteadof A;
            A::bigTalk insteadof B;
        }
    }

    class Aliased_Talker {
        use A, B {
            B::smallTalk insteadof A;
            A::bigTalk insteadof B;
            B::bigTalk as talk;
        }
    }
    ?>

### Cambiar la visibilidad de los métodos

Usando la sintaxis `as`, también se puede ajustar la visibilidad del método en la clase que lo usa.

Ejemplo #6 Cambiar la visibilidad de los métodos

    <?php
    trait HelloWorld {
        public function sayHello() {
            echo 'Hello World!';
        }
    }

    // Modificación de la visibilidad del método sayHello
    class MyClass1 {
        use HelloWorld { sayHello as protected; }
    }

    // Uso de un alias al modificar la visibilidad
    // La visibilidad del método sayHello no es modificada
    class MyClass2 {
        use HelloWorld { sayHello as private myPrivateHello; }
    }
    ?>

### Traits Compuestos desde otros Traits

Al igual que las clases pueden usar traits, otros traits también pueden hacerlo. Un trait puede, por lo tanto, usar otros traits y heredar todo o parte de ellos.

Ejemplo #7 Traits Compuestos desde otros Traits

    <?php
    trait Hello {
        public function sayHello() {
            echo 'Hello ';
        }
    }

    trait World {
        public function sayWorld() {
            echo 'World!';
        }
    }

    trait HelloWorld {
        use Hello, World;
    }

    class MyHelloWorld {
        use HelloWorld;
    }

    $o = new MyHelloWorld();
    $o->sayHello();
    $o->sayWorld();
    ?>

El ejemplo anterior mostrará:

    Hello World!

### Métodos abstractos en los Traits

Los traits soportan el uso de métodos abstractos para imponer restricciones a las clases subyacentes. Se soportan los métodos públicos, protegidos, y privados. Anterior a PHP 8.0.0, solo se soportaban los métodos públicos y protegidos abstractos.

Precaución

A partir de PHP 8.0.0, la firma de un método concreto debe seguir las reglas de compatibilidad de firmas. Anteriormente, su firma podía ser diferente.

Ejemplo #8 Obligaciones requeridas por los métodos abstractos

    <?php
    trait Hello {
        public function sayHelloWorld() {
            echo 'Hello'.$this->getWorld();
        }
        abstract public function getWorld();
    }

    class MyHelloWorld {
        private $world;
        use Hello;
        public function getWorld() {
            return $this->world;
        }
        public function setWorld($val) {
            $this->world = $val;
        }
    }
    ?>

### Atributos estáticos en los Traits

Los traits pueden definir variables estáticas, métodos estáticos y propiedades estáticas.

> Nota:

> A partir de PHP 8.1.0, llamar a un método estático o acceder a una propiedad estática directamente en un trait es obsoleto. Los métodos y propiedades estáticas deberían ser accedidos solo en una clase que use el trait.

Ejemplo #9 Variables estáticas

    <?php

    trait Counter
    {
        public function inc()
        {
            static $c = 0;
            $c = $c + 1;
            echo "$c\n";
        }
    }

    class C1
    {
        use Counter;
    }

    class C2
    {
        use Counter;
    }

    $o = new C1();
    $o->inc();
    $p = new C2();
    $p->inc();

    ?>

El ejemplo anterior mostrará:

    1
    1

Ejemplo #10 Métodos estáticos

    <?php

    trait StaticExample
    {
        public static function doSomething()
        {
            return 'Doing something';
        }
    }

    class Example
    {
        use StaticExample;
    }

    echo Example::doSomething();

    ?>

El ejemplo anterior mostrará:

    Doing something

Ejemplo #11 Propiedades estáticas

Precaución

Antes de PHP 8.3.0, las propiedades estáticas definidas en un trait eran compartidas entre todas las clases de la misma jerarquía de herencia que usaban ese trait. A partir de PHP 8.3.0, si una clase hija usa un trait con una propiedad estática, esta será considerada como distinta de la definida en la clase padre.

    <?php

    trait StaticExample
    {
        public static $counter = 1;
    }

    class A
    {
        use T;

        public static function incrementCounter()
        {
            static::$counter++;
        }
    }

    class B extends A
    {
        use T;
    }

    A::incrementCounter();

    echo A::$counter, "\n";
    echo B::$counter, "\n";

    ?>

Resultado del ejemplo anterior en PHP 8.3:

    2
    1

### Propiedades

Los traits también pueden definir propiedades.

Ejemplo #12 Definir propiedades

    <?php

    trait PropertiesTrait
    {
        public $x = 1;
    }

    class PropertiesExample
    {
        use PropertiesTrait;
    }

    $example = new PropertiesExample();
    $example->x;

    ?>

Si un trait define una propiedad, entonces la clase no puede definir una propiedad con el mismo nombre a menos que sea compatible (misma visibilidad, tipo, modificador readonly, valor inicial), de lo contrario se produce un error fatal.

Ejemplo #13 Resolución de conflictos

    <?php
    trait PropertiesTrait {
        public $same = true;
        public $different1 = false;
        public bool $different2;
        public bool $different3;
    }

    class PropertiesExample {
        use PropertiesTrait;
        public $same = true;
        public $different1 = true; // Fatal error
        public string $different2; // Fatal error
        readonly protected bool $different3; // Fatal error
    }
    ?>

### Constantes

Los traits pueden, a partir de PHP 8.2.0, también definir constantes.

Ejemplo #14 Trait definiendo una constante

    <?php
    trait ConstantsTrait {
        public const FLAG_MUTABLE = 1;
        final public const FLAG_IMMUTABLE = 5;
    }

    class ConstantsExample {
        use ConstantsTrait;
    }

    $example = new ConstantsExample;
    echo $example::FLAG_MUTABLE;
    ?>

El ejemplo anterior mostrará:

    1

Si un trait define una constante, entonces una clase no puede definir una constante con el mismo nombre, a menos que sea compatible (misma visibilidad, mismo valor, etc.), de lo contrario se produce un error fatal.

Ejemplo #15 Resolución de conflicto

    <?php
    trait ConstantsTrait {
        public const FLAG_MUTABLE = 1;
        final public const FLAG_IMMUTABLE = 5;
    }

    class ConstantsExample {
        use ConstantsTrait;
        public const FLAG_IMMUTABLE = 5; // Fatal error
    }
    ?>

### Métodos finales

A partir de PHP 8.3.0, el modificador final puede ser aplicado usando el operador `as` a los métodos importados desde los traits. Esto puede ser usado para impedir que las clases hijas sobrecarguen el método. Sin embargo, la clase que usa el trait puede seguir sobrecargando el método.

Ejemplo #16 Definir un método proveniente de un trait como `final`

    <?php

    trait CommonTrait
    {
        public function method()
        {
            echo 'Hello';
        }
    }

    class FinalExampleA
    {
        use CommonTrait {
            CommonTrait::method as final; // El 'final' impide que las clases hijas sobrecarguen el método
        }
    }

    class FinalExampleB extends FinalExampleA
    {
        public function method() {}
    }

    ?>

Resultado del ejemplo anterior es similar a:

    Fatal error: Cannot override final method FinalExampleA::method() in ...

## Clases anónimas

Las clases anónimas son útiles cuando se necesita crear objetos únicos simples.

    <?php

    // Utilizando una clase explícita
    class Logger
    {
        public function log($msg)
        {
            echo $msg;
        }
    }

    $util->setLogger(new Logger());

    // Utilizando una clase anónima
    $util->setLogger(new class {
        public function log($msg)
        {
            echo $msg;
        }
    });

Se les pueden pasar argumentos a través del constructor, pueden extender otras clases, implementar interfaces o utilizar traits como con una clase normal.

    <?php

    class SomeClass {}
    interface SomeInterface {}
    trait SomeTrait {}

    var_dump(new class(10) extends SomeClass implements SomeInterface {
        private $num;

        public function __construct($num)
        {
            $this->num = $num;
        }

        use SomeTrait;
    });

El ejemplo anterior mostrará:

    object(class@anonymous)#1 (1) {
      ["Command line code0x104c5b612":"class@anonymous":private]=>
      int(10)
    }

Anidar una clase anónima dentro de otra clase no da acceso a los métodos o propiedades privadas o protegidas de la clase contenedora. Para utilizar métodos o propiedades protegidas de la clase contenedora, la clase anónima debe extenderla. Para utilizar las propiedades privadas de la clase contenedora en la clase anónima, estas deben ser pasadas a través del constructor.

    <?php

    class Outer
    {
        private $prop = 1;
        protected $prop2 = 2;

        protected function func1()
        {
            return 3;
        }

        public function func2()
        {
            return new class($this->prop) extends Outer {
                private $prop3;

                public function __construct($prop)
                {
                    $this->prop3 = $prop;
                }

                public function func3()
                {
                    return $this->prop2 + $this->prop3 + $this->func1();
                }
            };
        }
    }

    echo (new Outer)->func2()->func3();

El ejemplo anterior mostrará:

    6

Todos los objetos creados por la misma declaración de clase anónima son instancias de la misma clase.

    <?php
    function anonymous_class()
    {
        return new class {};
    }

    if (get_class(anonymous_class()) === get_class(anonymous_class())) {
        echo 'same class';
    } else {
        echo 'different class';
    }

El ejemplo anterior mostrará:

    same class

> Nota:

> Tenga en cuenta que las clases anónimas son asignadas un nombre por el motor, como se ilustra en el siguiente ejemplo. Este nombre debe considerarse como un detalle de implementación, que no debe ser invocado.

>     <?php
>     echo get_class(new class {});

> Resultado del ejemplo anterior es similar a:

>     class@anonymous/in/oNi1A0x7f8636ad2021

### Clases anónimas de solo lectura

A partir de PHP 8.3.0, el modificador `readonly` puede ser aplicado a las clases anónimas.

Ejemplo #1 Definir una clase anónima de solo lectura

    <?php
    // Utilización de una clase anónima
    var_dump(new readonly class('[DEBUG]') {
        public function __construct(private string $prefix)
        {
        }

        public function log($msg)
        {
            echo $this->prefix . ' ' . $msg;
        }
    });

## Sobrecarga mágica

La sobrecarga mágica en PHP permite crear dinámicamente propiedades y métodos. Estas entidades dinámicas son tratadas a través de métodos mágicos establecidos que se pueden posicionar en una clase para diversos tipos de acciones.

Los métodos mágicos de sobrecarga son llamados durante la interacción con propiedades o métodos que no han sido declarados o no son visibles en el contexto actual. El resto de esta sección utiliza los términos de propiedades inaccesibles y de métodos inaccesibles para referirse a esta combinación de declaración y visibilidad.

Todos los métodos mágicos de sobrecarga deben ser definidos como `public`.

> Nota:

> Ninguno de los argumentos de estos métodos mágicos puede ser pasado por referencia.

> Nota:

> La interpretación PHP de la sobrecarga es diferente de la de la mayoría de los lenguajes orientados a objetos. La sobrecarga, habitualmente, proporciona la posibilidad de tener varios métodos con el mismo nombre pero con una cantidad y tipos diferentes de argumentos.

### Sobrecarga de propiedades

public function __set(string `$name`, mixed `$value`): void
public function __get(string `$name`): mixed
public function __isset(string `$name`): bool
public function __unset(string `$name`): void

__set() es solicitada al escribir datos hacia propiedades inaccesibles (protegidas o privadas) o no existentes.

__get() es llamada para leer datos desde propiedades inaccesibles (protegidas o privadas) o no existentes.

__isset() es solicitada cuando isset() o empty() son llamadas sobre propiedades inaccesibles (protegidas o privadas) o no existentes.

__unset() es invocada cuando unset() es llamada sobre propiedades inaccesibles (protegidas o privadas) o no existentes.

El argumento $name es el nombre de la propiedad con la que se interactúa. El argumento del método __set() $value especifica el valor al que la propiedad $name debería ser definida.

La sobrecarga de propiedades solo funciona en contextos de objeto. Estos métodos mágicos no serán lanzados en contexto estático. Por consiguiente, estos métodos no deberían ser declarados como estáticos. Se lanza un aviso si alguno de los métodos mágicos es declarado como `static`.

> Nota:

> El valor devuelto por __set() es ignorado debido a la forma en que PHP trata el operador de asignación. De la misma manera, __get() nunca es llamada durante una asignación encadenada, como esta: ``

>      $a = $obj->b = 8;

> Nota:

> PHP no llamará a un método sobrecargado desde el mismo método sobrecargado. Esto significa, por ejemplo, que escribir `return $this->foo` dentro de __get() devolverá `null` y lanzará un `E_WARNING` si no hay una propiedad `foo` definida, en lugar de llamar a __get() una segunda vez. Sin embargo, los métodos de sobrecarga pueden invocar otros métodos de sobrecarga de manera implícita (por ejemplo, __set() desencadenando __get()).

Ejemplo #1 Ejemplo de sobrecarga de propiedades con los métodos __get(), __set(), __isset() y __unset()

    <?php
    class PropertyTest
    {
        /**  Variable para los datos sobrecargados.  */
        private $data = array();

        /**  La sobrecarga no es utilizada en las propiedades declaradas.  */
        public $declared = 1;

        /**  La sobrecarga solo es lanzada cuando se accede a esta propiedad desde fuera de la clase.  */
        private $hidden = 2;

        public function __set($name, $value)
        {
            echo "Definición de '$name' al valor '$value'\n";
            $this->data[$name] = $value;
        }

        public function __get($name)
        {
            echo "Recuperación de '$name'\n";
            if (array_key_exists($name, $this->data)) {
                return $this->data[$name];
            }

            $trace = debug_backtrace();
            trigger_error(
                'Propiedad no definida vía __get() : ' . $name .
                ' en ' . $trace[0]['file'] .
                ' en la línea ' . $trace[0]['line'],
                E_USER_NOTICE);
            return null;
        }

        public function __isset($name)
        {
            echo "¿Está '$name' definido?\n";
            return isset($this->data[$name]);
        }

        public function __unset($name)
        {
            echo "Borrado de '$name'\n";
            unset($this->data[$name]);
        }

        /**  Este no es un método mágico, necesario aquí solo para el ejemplo.  */
        public function getHidden()
        {
            return $this->hidden;
        }
    }

    $obj = new PropertyTest;

    $obj->a = 1;
    echo $obj->a . "\n\n";

    var_dump(isset($obj->a));
    unset($obj->a);
    var_dump(isset($obj->a));
    echo "\n";

    echo $obj->declared . "\n\n";

    echo "Manipulemos ahora la propiedad privada llamada 'hidden' :\n";
    echo "'hidden' es visible desde la clase, por lo que __get() no es utilizado...\n";
    echo $obj->getHidden() . "\n";
    echo "'hidden' no es visible fuera de la clase, por lo que __get() es utilizado...\n";
    echo $obj->hidden . "\n";
    ?>

El ejemplo anterior mostrará:

    Definición de 'a' a '1'
    Recuperación de 'a'
    1

    ¿Está 'a' definido?
    bool(true)
    Borrado de 'a'
    ¿Está 'a' definido?
    bool(false)

    1

    Manipulemos ahora la propiedad privada llamada 'hidden' :
    'hidden' es visible desde la clase, por lo que __get() no es utilizado...
    2
    'hidden' no es visible fuera de la clase, por lo que __get() es utilizado...
    Recuperación de 'hidden'

    Notice: Propiedad no definida vía __get() : hidden en <file> en la línea 64 en <file> en la línea 28

### Sobrecarga de métodos

public function __call(string `$name`, array `$arguments`): mixed
public static function __callStatic(string `$name`, array `$arguments`): mixed

__call() es llamada cuando se invoca métodos inaccesibles en un contexto de objeto.

__callStatic() es lanzada cuando se invoca métodos inaccesibles en un contexto estático.

El argumento $name es el nombre del método llamado. El argumento $arguments es un array que contiene los parámetros pasados al método $name.

Ejemplo #2 Sobrecarga de métodos con __call() y __callStatic()

    <?php
    class MethodTest
    {
        public function __call($name, $arguments)
        {
            // Nota: el valor de $name es sensible a mayúsculas y minúsculas.
            echo "Llamada al método '$name' "
                 . implode(', ', $arguments). "\n";
        }

        public static function __callStatic($name, $arguments)
        {
            // Nota: el valor de $name es sensible a mayúsculas y minúsculas.
            echo "Llamada al método estático '$name' "
                 . implode(', ', $arguments). "\n";
        }
    }

    $obj = new MethodTest;
    $obj->runTest('en un contexto de objeto');

    MethodTest::runTest('en un contexto static');
    ?>

El ejemplo anterior mostrará:

    Llamada al método 'runTest' en un contexto de objeto
    Llamada al método estático 'runTest' en un contexto static

## Recorrido de objetos

PHP proporciona una manera de definir los objetos de manera que se pueda recorrer una lista de miembros, por ejemplo con una estructura `foreach`. Por omisión, todas las propiedades visibles serán utilizadas para el recorrido.

Ejemplo #1 Recorrido de objeto simple

    <?php
    class MyClass
    {
      public $var1 = 'valor 1';
      public $var2 = 'valor 2';
      public $var3 = 'valor 3';

      protected $protected = 'variable protegida';
      private   $private   = 'variable privada';

      function iterateVisible() {
         echo "MyClass::iterateVisible:\n";
         foreach ($this as $key => $value) {
             print "$key => $value\n";
         }
      }
    }

    $class = new MyClass();

    foreach($class as $key => $value) {
        print "$key => $value\n";
    }
    echo "\n";

    $class->iterateVisible();

El ejemplo anterior mostrará:

    var1 => valor 1
    var2 => valor 2
    var3 => valor 3

    MyClass::iterateVisible:
    var1 => valor 1
    var2 => valor 2
    var3 => valor 3
    protected => variable protegida
    private => variable privada

Como muestra la salida, la iteración `foreach` recorrió todas las propiedades visibles que pudieron ser accedidas.

### Ver también

- Generators
- Iterator
- IteratorAggregate
- SPL Iterators

## Métodos mágicos

Los métodos mágicos son métodos especiales que sobrescriben la acción por omisión de PHP cuando se realizan ciertas acciones sobre un objeto.

Precaución

Todos los métodos que comienzan por `__` están reservados por PHP. Por lo tanto, no se recomienda utilizar un nombre de método de este tipo, excepto cuando se sobrescribe el comportamiento de PHP.

Los siguientes métodos se consideran mágicos: __construct(), __destruct(), __call(), __callStatic(), __get(), __set(), __isset(), __unset(), __serialize(), __unserialize(), __sleep(), __wakeup(), __toString(), __invoke(), __set_state() __clone(), y __debugInfo().

Advertencia

Todos los métodos mágicos, excepto __construct(), __destruct(), y __clone(), deben ser declarados como `public`, de lo contrario se emitirá una `E_WARNING`. Anterior a PHP 8.0.0, no se emitía ningún diagnóstico para los métodos mágicos __sleep(), __wakeup(), __serialize(), __unserialize(), y __set_state().

Advertencia

Si se utilizan declaraciones de tipos en la definición de un método mágico, deben ser idénticas a la firma descrita en este documento. De lo contrario, se emitirá un error fatal. Anterior a PHP 8.0.0, no se emitía ningún diagnóstico. Sin embargo, __construct() y __destruct() no deben declarar un tipo de retorno; de lo contrario, se emitirá un error fatal.

### __serialize() y __unserialize()

public function __serialize(): array
public function __unserialize(array `$data`): void

serialize() verifica si la clase tiene un método con el nombre mágico __serialize(). Si es así, este método será ejecutado antes de cualquier serialización. Debe construir y devolver un array asociativo de pares clave/valor que represente la forma serializada del objeto. Si no se devuelve ningún array, se lanzará una TypeError.

> Nota:

> Si __serialize() y __sleep() están ambas definidas en el mismo objeto, entonces solo __serialize() será llamada. __sleep() será ignorada. Si el objeto implementa la interfaz Serializable, el método `serialize()` de la interfaz será ignorado y __serialize() será utilizada en su lugar.

El uso previsto de __serialize() es definir una representación arbitraria del objeto para serializarlo fácilmente. Los elementos del array pueden corresponder a las propiedades del objeto, pero esto no es requerido.

Inversamente, unserialize() verifica la presencia de una función con el nombre mágico __unserialize(). Si está presente, esta función recibirá el array restaurado devuelto por __serialize(). Puede entonces restaurar las propiedades del objeto desde este array como sea apropiado.

> Nota:

> Si __unserialize() y __wakeup() están ambas definidas en el mismo objeto, entonces solo __unserialize() será llamada. __wakeup() será ignorada.

> Nota:

> Esta funcionalidad está disponible a partir de PHP 7.4.0.

Ejemplo #1 Serialize y unserialize

    <?php
    class Connection
    {
        protected $link;
        private $dsn, $username, $password;

        public function __construct($dsn, $username, $password)
        {
            $this->dsn = $dsn;
            $this->username = $username;
            $this->password = $password;
            $this->connect();
        }

        private function connect()
        {
            $this->link = new PDO($this->dsn, $this->username, $this->password);
        }

        public function __serialize(): array
        {
            return [
              'dsn' => $this->dsn,
              'user' => $this->username,
              'pass' => $this->password,
            ];
        }

        public function __unserialize(array $data): void
        {
            $this->dsn = $data['dsn'];
            $this->username = $data['user'];
            $this->password = $data['pass'];

            $this->connect();
        }
    }?>

### __sleep() y __wakeup()

Advertencia

Este mecanismo de serialización está soft-deprecated a partir de PHP 8.5.0. Se mantiene por compatibilidad con versiones anteriores. Sin embargo, el código nuevo y existente debe migrarse para usar los métodos mágicos __serialize() y __unserialize() en su lugar.

public function __sleep(): array
public function __wakeup(): void

serialize() verifica si la clase tiene un método con el nombre mágico __sleep(). Si es así, este método será ejecutado antes de cualquier serialización. Puede limpiar el objeto, y se supone que devuelve un array con los nombres de todas las variables del objeto que deben ser serializadas. Si el método no devuelve nada, entonces `null` será serializado, y se emitirá una alerta de tipo `E_NOTICE`.

> Nota:

> No es posible para __sleep() devolver nombres de propiedades privadas de las clases padres. Hacerlo resultará en un error de nivel `E_NOTICE`. Utilice __serialize() en su lugar.

> Nota:

> A partir de PHP 8.0.0, devolver un valor que no sea un array desde __sleep() emite una advertencia. Anteriormente se emitía una notificación.

El propósito declarado de __sleep() es validar datos pendientes o realizar operaciones de limpieza. Además, esta función es útil si un objeto muy grande no necesita ser guardado en su totalidad.

Reciprocamente, la función unserialize() verifica la presencia de un método cuyo nombre es el nombre mágico __wakeup(). Si está presente, esta función puede reconstruir cualquier recurso que el objeto pudiera poseer.

El propósito declarado de __wakeup() es restablecer cualquier conexión de base de datos que se haya perdido durante la serialización y realizar tareas de reinicialización.

Ejemplo #2 Uso de sleep() y wakeup()

    <?php
    class Connection
    {
        protected $link;
        private $dsn, $username, $password;

        public function __construct($dsn, $username, $password)
        {
            $this->dsn = $dsn;
            $this->username = $username;
            $this->password = $password;
            $this->connect();
        }

        private function connect()
        {
            $this->link = new PDO($this->dsn, $this->username, $this->password);
        }

        public function __sleep()
        {
            return array('dsn', 'username', 'password');
        }

        public function __wakeup()
        {
            $this->connect();
        }
    }?>

### __toString()

public function __toString(): string

El método __toString() determina cómo el objeto debe reaccionar cuando se trata como una cadena de caracteres. Por ejemplo, lo que `echo $obj;` mostrará.

Advertencia

A partir de PHP 8.0.0, el valor de retorno sigue las semánticas estándar de PHP, lo que significa que el valor será convertido en una string si es posible y si el typing stricte está desactivado.

Un objeto Stringable no será aceptado por una declaración de tipo string si la declaración de tipo estricta está activada. Si se desea tal comportamiento, la declaración de tipo debe aceptar tanto Stringable como string a través de un tipo de unión.

A partir de PHP 8.0.0, cualquier clase que contenga un método __toString() implementa también implícitamente la interfaz Stringable, y por lo tanto pasará las verificaciones de tipos para esta interfaz. Se recomienda implementar explícitamente la interfaz de todos modos.

En PHP 7.4, el valor de retorno debe ser una string, de lo contrario se lanzará un Error.

Anterior a PHP 7.4.0, el valor de retorno debe ser una string, de lo contrario se emitirá una `E_RECOVERABLE_ERROR` fatal.

Advertencia

Era imposible lanzar una excepción desde el método __toString() anterior a PHP 7.4.0. Esto resultaría en un error fatal.

Ejemplo #3 Ejemplo simple

    <?php
    // Declaración de una clase simple
    class ClasseTest
    {
        public $foo;

        public function __construct($foo)
        {
            $this->foo = $foo;
        }

        public function __toString()
        {
            return $this->foo;
        }
    }

    $class = new ClasseTest('Bonjour');
    echo $class;
    ?>

El ejemplo anterior mostrará:

    Bonjour

### __invoke()

function __invoke( `...$values`): mixed

El método __invoke() es llamado cuando un script intenta llamar a un objeto como una función.

Ejemplo #4 Ejemplo con __invoke()

    <?php
    class CallableClass
    {
        public function __invoke($x)
        {
            var_dump($x);
        }
    }
    $obj = new CallableClass;
    $obj(5);
    var_dump(is_callable($obj));
    ?>

El ejemplo anterior mostrará:

    int(5)
    bool(true)

Ejemplo #5 Ejemplo con __invoke()

    <?php
    class Sort
    {
        private $key;

        public function __construct(string $key)
        {
            $this->key = $key;
        }

        public function __invoke(array $a, array $b): int
        {
            return $a[$this->key] <=> $b[$this->key];
        }
    }

    $customers = [
        ['id' => 1, 'first_name' => 'John', 'last_name' => 'Do'],
        ['id' => 3, 'first_name' => 'Alice', 'last_name' => 'Gustav'],
        ['id' => 2, 'first_name' => 'Bob', 'last_name' => 'Filipe']
    ];

    // ordenar los clientes por nombre
    usort($customers, new Sort('first_name'));
    print_r($customers);

    // ordenar los clientes por apellido
    usort($customers, new Sort('last_name'));
    print_r($customers);
    ?>

El ejemplo anterior mostrará:

    Array
    (
        [0] => Array
            (
                [id] => 3
                [first_name] => Alice
                [last_name] => Gustav
            )

        [1] => Array
            (
                [id] => 2
                [first_name] => Bob
                [last_name] => Filipe
            )

        [2] => Array
            (
                [id] => 1
                [first_name] => John
                [last_name] => Do
            )

    )
    Array
    (
        [0] => Array
            (
                [id] => 1
                [first_name] => John
                [last_name] => Do
            )

        [1] => Array
            (
                [id] => 2
                [first_name] => Bob
                [last_name] => Filipe
            )

        [2] => Array
            (
                [id] => 3
                [first_name] => Alice
                [last_name] => Gustav
            )

    )

### __set_state()

static function __set_state(array `$properties`): object

Este método estático es llamado para las clases exportadas por la función var_export().

El único parámetro de este método es un array que contiene las propiedades exportadas en la forma `['property' => value, ...]`.

Ejemplo #6 Uso de __set_state()

    class A
    {
        public $var1;
        public $var2;

        public static function __set_state($an_array)
        {
            $obj = new A;
            $obj->var1 = $an_array['var1'];
            $obj->var2 = $an_array['var2'];
            return $obj;
        }
    }

    $a = new A;
    $a->var1 = 5;
    $a->var2 = 'foo';

    $b = var_export($a, true);
    var_dump($b);
    eval('$c = ' . $b . ';');
    var_dump($c);
    ?>

El ejemplo anterior mostrará:

    string(60) "A::__set_state(array(
       'var1' => 5,
       'var2' => 'foo',
    ))"
    object(A)#2 (2) {
      ["var1"]=>
      int(5)
      ["var2"]=>
      string(3) "foo"
    }

> Nota: Al exportar un objeto, var_export() no verifica si __set_state() está implementada por la clase del objeto, por lo que la reimportación de objetos resultará en una excepción Error, si __set_state() no está implementada. En particular, esto afecta a ciertas clases internas. Es responsabilidad del programador verificar que solo los objetos cuya clase implementa __set_state() serán re-importados.

### __debugInfo()

function __debugInfo(): array

Este método es llamado por var_dump() al procesar un objeto para recuperar las propiedades que deben ser mostradas. Si el método no está definido en un objeto, entonces todas las propiedades públicas, protegidas y privadas serán mostradas.

Ejemplo #7 Uso de __debugInfo()

    <?php
    class C {
        private $prop;

        public function __construct($val) {
            $this->prop = $val;
        }

        public function __debugInfo() {
            return [
                'propSquared' => $this->prop ** 2,
            ];
        }
    }

    var_dump(new C(42));
    ?>

El ejemplo anterior mostrará:

    object(C)#1 (1) {
      ["propSquared"]=>
      int(1764)
    }

## Palabra clave "final"

La palabra clave final impide que las clases hijas redefinan un método, una propiedad o constante prefijando la definición con `final`. Si la clase misma es definida como final, no podrá ser extendida.

Ejemplo #1 Ejemplo de método final

    <?php
    class BaseClass {
       public function test() {
           echo "BaseClass::test() llamada\n";
       }

       final public function moreTesting() {
           echo "BaseClass::moreTesting() llamada\n";
       }
    }

    class ChildClass extends BaseClass {
       public function moreTesting() {
           echo "ChildClass::moreTesting() llamada\n";
       }
    }
    // Resultado: Fatal error: Cannot override final method BaseClass::moreTesting()
    ?>

Ejemplo #2 Ejemplo de clase final

    <?php
    final class BaseClass {
       public function test() {
           echo "BaseClass::test() llamada\n";
       }

       // Como la clase ya es final, la palabra clave final es redundante
       final public function moreTesting() {
           echo "BaseClass::moreTesting() llamada\n";
       }
    }

    class ChildClass extends BaseClass {
    }
    // Resultado: Fatal error: Class ChildClass may not inherit from final class (BaseClass)
    ?>

Ejemplo #3 Ejemplo de propiedad final a partir de PHP 8.4.0

    <?php
    class BaseClass {
       final protected string $test;
    }

    class ChildClass extends BaseClass {
        public string $test;
    }
    // Resultado: Error fatal: Imposible redefinir la propiedad final BaseClass::$test
    ?>

Ejemplo #4 Ejemplo de constantes finales a partir de PHP 8.1.0

    <?php
    class Foo
    {
        final public const X = "foo";
    }

    class Bar extends Foo
    {
        public const X = "bar";
    }

    // Fatal error: Bar::X cannot override final constant Foo::X
    ?>

> Nota: A partir de PHP 8.0.0, los métodos privados no pueden ser declarados finales, con la excepción del constructor.

> Nota: Una propiedad declarada `private(set)` es implícitamente `final`.

## Clonación de objetos

La creación de una copia de un objeto con exactamente las mismas propiedades no siempre es el comportamiento deseado. Un buen ejemplo para ilustrar la necesidad de un constructor de copia: si se tiene un objeto que representa una ventana GTK y el objeto contiene el recurso que representa esa ventana GTK, al crear una copia, se puede desear crear una nueva ventana con las mismas propiedades, pero que el nuevo objeto contenga un recurso que represente la nueva ventana.

Una copia de objeto se crea utilizando la palabra clave `clone` (que invoca al método __clone() del objeto, si ha sido definido).

    $copy_of_object = clone $object;

Cuando un objeto es clonado, PHP realiza una copia superficial de todas las propiedades del objeto. Todas las propiedades que son referencias a otras variables permanecerán como referencias.

function __clone(): void

Una vez realizada la clonación, si se ha definido un método __clone(), el método __clone() del nuevo objeto será llamado, para permitir que cada propiedad que deba ser modificada lo sea.

Ejemplo #1 Ejemplo de duplicación de objetos

    <?php
    class SubObject
    {
      static $instances = 0;
      public $instance;

      public function __construct() {
        $this->instance = ++self::$instances;
      }

      public function __clone() {
        $this->instance = ++self::$instances;
      }
    }

    class MyCloneable
    {
      public $object1;
      public $object2;

      function __clone()
      {
        // Fuerza la copia de this->object, de lo contrario
        // apuntará al mismo objeto.
        $this->object1 = clone $this->object1;
      }
    }

    $obj = new MyCloneable();

    $obj->object1 = new SubObject();
    $obj->object2 = new SubObject();

    $obj2 = clone $obj;

    print "Objeto original :\n";
    print_r($obj);

    print "Objeto clonado :\n";
    print_r($obj2);

    ?>

El ejemplo anterior mostrará:

    Objeto original :
    MyCloneable Object
    (
        [object1] => SubObject Object
            (
                [instance] => 1
            )

        [object2] => SubObject Object
            (
                [instance] => 2
            )

    )
    Objeto clonado :
    MyCloneable Object
    (
        [object1] => SubObject Object
            (
                [instance] => 3
            )

        [object2] => SubObject Object
            (
                [instance] => 2
            )

    )

Es posible acceder a un miembro de un objeto recién clonado en una sola expresión:

Ejemplo #2 Acceso a un miembro de un objeto recién clonado

    <?php
    $dateTime = new DateTime();
    echo (clone $dateTime)->format('Y');
    ?>

Resultado del ejemplo anterior es similar a:

    2016

## Comparación de objetos

Al utilizar el operador de comparación (`==`), los objetos se comparan de manera simple, es decir: dos objetos son iguales si tienen los mismos atributos y valores (los valores se comparan con el operador `==`), y si son instancias de la misma clase.

Al utilizar el operador de identidad (`===`), los objetos son idénticos únicamente si hacen referencia a la misma instancia de la misma clase.

Un ejemplo ilustrará estas reglas.

Ejemplo #1 Ejemplo de comparación de objetos en PHP

    <?php
    function bool2str($bool)
    {
        if ($bool === false) {
                return 'FALSE';
        } else {
                return 'TRUE';
        }
    }

    function compareObjects(&$o1, &$o2)
    {
        echo 'o1 == o2 : '.bool2str($o1 == $o2)."\n";
        echo 'o1 != o2 : '.bool2str($o1 != $o2)."\n";
        echo 'o1 === o2 : '.bool2str($o1 === $o2)."\n";
        echo 'o1 !== o2 : '.bool2str($o1 !== $o2)."\n";
    }

    class Flag
    {
        public $flag;

        function __construct($flag = true) {
            $this->flag = $flag;
        }
    }

    class OtherFlag
    {
        public $flag;

        function __construct($flag = true) {
            $this->flag = $flag;
        }
    }

    $o = new Flag();
    $p = new Flag();
    $q = $o;
    $r = new OtherFlag();

    echo "Dos instancias de la misma clase\n";
    compareObjects($o, $p);

    echo "\nDos referencias al mismo objeto\n";
    compareObjects($o, $q);

    echo "\nInstancias de clases diferentes\n";
    compareObjects($o, $r);
    ?>

El ejemplo anterior mostrará:

    Dos instancias de la misma clase
    o1 == o2 : TRUE
    o1 != o2 : FALSE
    o1 === o2 : FALSE
    o1 !== o2 : TRUE

    Dos referencias al mismo objeto
    o1 == o2 : TRUE
    o1 != o2 : FALSE
    o1 === o2 : TRUE
    o1 !== o2 : FALSE

    Instancias de clases diferentes
    o1 == o2 : FALSE
    o1 != o2 : TRUE
    o1 === o2 : FALSE
    o1 !== o2 : TRUE

> Nota:

> Las extensiones pueden definir sus propias reglas para sus comparaciones de objetos (`==`).

## Late Static Bindings (Resolución estática en tiempo de ejecución)

PHP implementa una funcionalidad llamada late static binding, en español la resolución estática en tiempo de ejecución, que puede ser utilizada para referenciar la clase llamada en un contexto de herencia estática.

Más precisamente, las resoluciones estáticas en tiempo de ejecución funcionan registrando el nombre de la clase en la última "llamada no reenviada". En el caso de las llamadas de métodos estáticos, se trata de la clase explícitamente nombrada (generalmente, la que está a la izquierda del operador `::`) ; en el caso de métodos no estáticos, se trata de la clase del objeto. Una "llamada reenviada" es una llamada estática introducida por `self::`, `parent::`, `static::`, o, subiendo en la jerarquía de clases, forward_static_call(). La función get_called_class() puede ser utilizada para recuperar una cadena que contiene el nombre de la clase llamada, y `static::` introduce su ámbito.

Esta funcionalidad ha sido bautizada como "late static bindings", con un punto de vista interno. "Late binding", literalmente resolución tardía, proviene del hecho de que los elementos `static::` no serán resueltos utilizando la clase donde el método ha sido definido, sino que será calculada utilizando la información en tiempo de ejecución. También se denomina "static binding" ya que puede ser utilizado para (sin estar limitado a) los métodos estáticos.

### Limitaciones de `self::`

Las referencias estáticas a la clase actual, con `self::` o `__CLASS__`, son resueltas utilizando la clase a la que pertenecen las funciones, es decir, donde fueron definidas:

Ejemplo #1 Uso de `self::`

    <?php

    class A
    {
        public static function who()
        {
            echo __CLASS__;
        }

        public static function test()
        {
            self::who();
        }
    }

    class B extends A
    {
        public static function who()
        {
             echo __CLASS__;
        }
    }

    B::test();

    ?>

El ejemplo anterior mostrará:

    A

### Uso de la resolución estática en tiempo de ejecución

La resolución estática en tiempo de ejecución intenta superar esta limitación introduciendo una palabra clave que hace referencia a la clase que ha sido llamada durante la ejecución. Para simplificar, esta palabra clave permite la referencia a `B` desde `test()`, en el ejemplo anterior. Se decidió no introducir una nueva palabra clave, sino más bien utilizar la palabra `static` que ya estaba reservada.

Ejemplo #2 Uso simple de `static::`

    <?php

    class A
    {
        public static function who()
        {
            echo __CLASS__;
        }

        public static function test()
        {
            static::who(); // Aquí, resolución estática en tiempo de ejecución
        }
    }

    class B extends A
    {
        public static function who()
        {
             echo __CLASS__;
        }
    }

    B::test();

    ?>

El ejemplo anterior mostrará:

    B

> Nota:

> En contextos no estáticos, la clase llamada será la del objeto. Como `$this->` intentará llamar a métodos privados desde el mismo ámbito, utilizar `static::` podría dar resultados diferentes. Tenga en cuenta también que `static::` solo puede hacer referencia a propiedades estáticas.

Ejemplo #3 Uso de `static::` en un contexto no estático

    <?php

    class A
    {
        private function foo()
        {
            echo "Success!\n";
        }

        public function test()
        {
            $this->foo();
            static::foo();
        }
    }

    class B extends A
    {
       /* foo() será copiada en B, por lo tanto su ámbito será siempre A
        * y la llamada se realizará sin problemas */
    }

    class C extends A
    {
        private function foo()
        {
            /* El método original es reemplazado; el ámbito es el de C */
        }
    }

    $b = new B();
    $b->test();

    $c = new C();
    try {
        $c->test();
    } catch (Error $e) {
        echo $e->getMessage();
    }

    ?>

El ejemplo anterior mostrará:

    Success!
    Success!
    Success!
    Call to private method C::foo() from scope A

> Nota:

> La resolución de estáticos en tiempo de ejecución se detendrá en una llamada estática completamente resuelta. Por otro lado, las llamadas estáticas utilizando una palabra clave como `parent::` o `self::` reenviarán la información de llamada.

> Ejemplo #4 Llamadas con o sin reenvío

>     <?php

>     class A
>     {
>         public static function foo()
>         {
>             static::who();
>         }

>         public static function who()
>         {
>             echo __CLASS__."\n";
>         }
>     }

>     class B extends A
>     {
>         public static function test()
>         {
>             A::foo();
>             parent::foo();
>             self::foo();
>         }

>         public static function who()
>         {
>             echo __CLASS__."\n";
>         }
>     }
>     class C extends B
>     {
>         public static function who()
>         {
>             echo __CLASS__."\n";
>         }
>     }

>     C::test();

>     ?>

> El ejemplo anterior mostrará:

>     A
>     C
>     C

## Objetos y referencias

Uno de los pilares de la POO de PHP es el hecho de que los "objetos son pasados por referencia por omisión". Esto no es completamente cierto. Esta sección corrige esta generalización con algunos ejemplos.

Una referencia PHP es un alias, que permite a dos variables diferentes representar el mismo valor. En PHP, una variable objeto no contiene más el objeto en sí mismo como valor. Contiene solo un identificador de objeto, que permite a los métodos de acceso de objetos encontrar dicho objeto. Cuando el objeto es utilizado como argumento, devuelto por una función, o asignado a otra variable, las diferentes variables no son alias: contienen copias del identificador, que apuntan al mismo objeto.

Ejemplo #1 Referencias y Objetos

    <?php
    class A {
        public $foo = 1;
    }

    $a = new A;
    $b = $a;     // $a y $b son copias del mismo identificador
                 // ($a) = ($b) = <id>
    $b->foo = 2;
    echo $a->foo."\n";

    $c = new A;
    $d = &$c;    // $c y $d son referencias
                 // ($c,$d) = <id>

    $d->foo = 2;
    echo $c->foo."\n";

    $e = new A;

    function foo($obj) {
        // ($obj) = ($e) = <id>
        $obj->foo = 2;
    }

    foo($e);
    echo $e->foo."\n";

    ?>

El ejemplo anterior mostrará:

    2
    2
    2

## Serializar objetos - objetos en sesión

serialize() devuelve un string que contiene una representación lineal de cualquier valor que puede ser almacenado en PHP. unserialize() puede utilizar este string para recrear el valor original de la variable a partir de su representación lineal. Utilizar serialize para guardar un objeto conservará todas sus variables. Sus métodos no serán conservados, solo el nombre de la clase lo será.

Para poder deserializar (unserialize()) un objeto, la clase del objeto debe estar definida, para permitir su reconstrucción. En otras palabras, si se tiene un objeto de la clase A y se serializa, la representación lineal obtenida hará referencia a la clase A y contendrá todas sus variables. Si se desea poder deserializar esta representación lineal en un lugar donde la clase A no esté definida (en otro fichero, por ejemplo), entonces se deberá redclarar la clase A antes de proceder a la deserialización de su representación lineal. Esto puede hacerse, por ejemplo, incluyendo el fichero de definición de la clase, o utilizando la función spl_autoload_register().

    <?php
    // A.php :

      class A {
          public $one = 1;

          public function show_one() {
              echo $this->one;
          }
      }

    // page1.php :

      include "A.php";

      $a = new A;
      $s = serialize($a);
      // guarda $s en algún lugar donde page2.php pueda encontrarlo
      file_put_contents('store', $s);

    // page2.php :

      // se necesita la definición de la clase
      // para que unserialize() funcione
      include "A.php";

      $s = file_get_contents('store');
      $a = unserialize($s);

      // llamada a show_one() en el objeto $a, muestra 1
      $a->show_one();
    ?>

Si una aplicación serializa objetos, se recomienda encarecidamente, para su uso futuro, que la aplicación incluya las definiciones de las clases de los objetos serializados en cada página. No hacerlo podría resultar en un objeto deserializado sin su definición de clase. PHP asignaría entonces a este objeto una clase de tipo __PHP_Incomplete_Class_Name, que no tiene métodos, y produciría un objeto inútil.

Así, en el ejemplo anterior, si $a se registra en la sesión añadiendo una clave a la variable superglobal $_SESSION, se debería incluir el fichero `A.php` en todas las páginas, y no solo en page1.php y page2.php.

Tenga en cuenta que también se pueden utilizar los eventos de serialización y deserialización en un objeto utilizando los métodos __sleep() y __wakeup(). El uso de __sleep() permite también serializar solo una parte de las propiedades del objeto.

## Covarianza y Contravarianza

A partir de PHP 7.2.0, se introdujo la contravarianza parcial eliminando las restricciones de tipo en los parámetros de un método hijo. A partir de PHP 7.4.0, se añadieron la covarianza y la contravarianza completas.

La covarianza permite a un método hijo devolver un tipo más específico que el tipo de retorno de su método padre. La contravarianza permite que un tipo de parámetro sea menos específico en un método hijo que en el de la clase padre.

Una declaración de tipo se considera más específica en el siguiente caso:

- Un tipo es retirado de un tipo union
- Un tipo es añadido a un tipo de intersección
- Un tipo de clase es transformado en un tipo de clase hijo
- iterable es reemplazado por array o Traversable

Un tipo de clase se considera menos específico si lo contrario es cierto.

### Covarianza

Para ilustrar el funcionamiento de la covarianza, se crea una simple clase padre abstracta, Animal. Animal será extendida por clases hijas, Cat y Dog.

    <?php

    abstract class Animal
    {
        protected string $name;

        public function __construct(string $name)
        {
            $this->name = $name;
        }

        abstract public function speak();
    }

    class Dog extends Animal
    {
        public function speak()
        {
            echo $this->name . " barks";
        }
    }

    class Cat extends Animal
    {
        public function speak()
        {
            echo $this->name . " meows";
        }
    }

Téngase en cuenta que no hay métodos que devuelvan valores en este ejemplo. Se añadirán algunas fábricas y devolverán un nuevo objeto de clase de tipo Animal, Cat, o Dog.

    <?php

    interface AnimalShelter
    {
        public function adopt(string $name): Animal;
    }

    class CatShelter implements AnimalShelter
    {
        public function adopt(string $name): Cat // en lugar de devolver el tipo de clase Animal, puede devolver el tipo de clase Cat
        {
            return new Cat($name);
        }
    }

    class DogShelter implements AnimalShelter
    {
        public function adopt(string $name): Dog // en lugar de devolver el tipo de clase Animal, puede devolver el tipo de clase Dog
        {
            return new Dog($name);
        }
    }

    $kitty = (new CatShelter)->adopt("Ricky");
    $kitty->speak();
    echo "\n";

    $doggy = (new DogShelter)->adopt("Mavrick");
    $doggy->speak();

El ejemplo anterior mostrará:

    Ricky meows
    Mavrick barks

### Contravarianza

Retomando el ejemplo anterior con las clases Animal, Cat y Dog, se incluyen dos clases llamadas Food y AnimalFood, y se añade un método eat(AnimalFood $food) a la clase abstracta Animal.

    <?php

    class Food {}

    class AnimalFood extends Food {}

    abstract class Animal
    {
        protected string $name;

        public function __construct(string $name)
        {
            $this->name = $name;
        }

        public function eat(AnimalFood $food)
        {
            echo $this->name . " eats " . get_class($food);
        }
    }

Para ver el comportamiento de la contravarianza, el método método eat es sobrecargado en la clase Dog para permitir cualquier objeto de tipo Food. La clase Cat permanece sin cambios.

    <?php

    class Dog extends Animal
    {
        public function eat(Food $food) {
            echo $this->name . " eats " . get_class($food);
        }
    }

El siguiente ejemplo muestra el comportamiento de la contravarianza.

    <?php

    $kitty = (new CatShelter)->adopt("Ricky");
    $catFood = new AnimalFood();
    $kitty->eat($catFood);
    echo "\n";

    $doggy = (new DogShelter)->adopt("Mavrick");
    $banana = new Food();
    $doggy->eat($banana);

El ejemplo anterior mostrará:

    Ricky eats AnimalFood
    Mavrick eats Food

Pero, ¿qué sucede si $kitty intenta comer (eat()) la banana ($banana) ?

    $kitty->eat($banana);

El ejemplo anterior mostrará:

    Fatal error: Uncaught TypeError: Argument 1 passed to Animal::eat() must be an instance of AnimalFood, instance of Food given

### Variación de tipo de las propiedades

Por defecto, las propiedades no son ni covariantes ni contravariantes, por lo tanto, son invariantes. En otras palabras, su tipo no puede cambiar en absoluto en una clase hija. La razón es que las operaciones "get" deben ser covariantes, y las operaciones "set" deben ser contravariantes. La única manera para que una propiedad cumpla con estos dos requisitos es ser invariante.

A partir de PHP 8.4.0, con la adición de las propiedades abstractas (en una interfaz o una clase abstracta) y propiedades virtuales, es posible declarar una propiedad que solo tenga una operación "get" o "set". En consecuencia, las propiedades abstractas o las propiedades virtuales que solo requieren la operación "get" pueden ser covariantes. De manera similar, una propiedad abstracta o una propiedad virtual que solo requiere la operación "set" puede ser contravariante.

Sin embargo, una vez que una propiedad tiene tanto una operación "get" como "set", ya no es covariante ni contravariante para una extensión futura. En otras palabras, se vuelve invariante.

Ejemplo #1 Variación del tipo de las propiedades

    <?php
    class Animal {}
    class Dog extends Animal {}
    class Poodle extends Dog {}

    interface PetOwner
    {
        // Solo se requiere la operación "get", por lo tanto, puede ser covariante.
        public Animal $pet { get; }
    }

    class DogOwner implements PetOwner
    {
        // Puede ser un tipo más restrictivo, ya que el lado "get"
        // siempre devuelve un Animal. Sin embargo, como propiedad nativa,
        // los hijos de esta clase ya no pueden cambiar el tipo.
        public Dog $pet;
    }

    class PoodleOwner extends DogOwner
    {
        // ESTO NO ESTÁ PERMITIDO, ya que DogOwner::$pet tiene tanto
        // las operaciones "get" como "set" definidas y requeridas.
        public Poodle $pet;
    }
    ?>

## Objetos perezosos

Un objeto perezoso es un objeto cuya inicialización se retrasa hasta que su estado sea observado o modificado. Algunos ejemplos de uso incluyen componentes de inyección de dependencias que proporcionan servicios perezosos completamente inicializados solo si es necesario, ORMs que proporcionan entidades perezosas que se hidratan desde la base de datos solo cuando se accede a ellas, o un analizador JSON que retrasa el análisis hasta que se accede a los elementos.

Se admiten dos estrategias de objetos perezosos: los objetos fantasma (Ghost) y los proxys virtuales (Virtual Proxies), a continuación denominados "fantasmas perezosos" y "proxys perezosos". En ambas estrategias, el objeto perezoso se adjunta a un inicializador o a una fábrica que se llama automáticamente cuando su estado es observado o modificado por primera vez. Desde el punto de vista de la abstracción, los objetos perezosos son indiscernibles de los no perezosos: pueden ser utilizados sin saber que son perezosos, lo que permite pasarlos y utilizarlos en código que no es consciente de la pereza. Los proxys perezosos también son transparentes, pero hay que tener cuidado cuando se utiliza su identidad, ya que el proxy y su instancia real tienen identidades diferentes.

> Nota: Información de versión
> Los objetos perezosos fueron introducidos en PHP 8.4.

### Creación de objetos perezosos

Es posible crear una instancia perezosa de cualquier clase definida por el usuario o de la clase stdClass (otras clases internas no son admitidas), o reinicializar una instancia de estas clases para que sea perezosa. Los puntos de entrada para crear un objeto perezoso son los métodos ReflectionClass::newLazyGhost() y ReflectionClass::newLazyProxy().

Ambos métodos aceptan una función que se llama cuando el objeto necesita inicialización. El comportamiento esperado de la función varía en función de la estrategia utilizada, como se describe en la documentación de referencia de cada método.

Ejemplo #1 Creación de un fantasma perezoso

    <?php
    class Example
    {
        public function __construct(public int $prop)
        {
            echo __METHOD__, "\n";
        }
    }

    $reflector = new ReflectionClass(Example::class);
    $lazyObject = $reflector->newLazyGhost(function (Example $object) {
        // Inicializa el objeto en el lugar
        $object->__construct(1);
    });

    var_dump($lazyObject);
    var_dump(get_class($lazyObject));

    // Desencadena la inicialización
    var_dump($lazyObject->prop);
    ?>

El ejemplo anterior mostrará:

    lazy ghost object(Example)#3 (0) {
    ["prop"]=>
    uninitialized(int)
    }
    string(7) "Example"
    Example::__construct
    int(1)

Ejemplo #2 Creación de un proxy perezoso

    <?php
    class Example
    {
        public function __construct(public int $prop)
        {
            echo __METHOD__, "\n";
        }
    }

    $reflector = new ReflectionClass(Example::class);
    $lazyObject = $reflector->newLazyProxy(function (Example $object) {
        // Crea y devuelve la instancia real
        return new Example(1);
    });

    var_dump($lazyObject);
    var_dump(get_class($lazyObject));

    // Desencadena la inicialización
    var_dump($lazyObject->prop);
    ?>

El ejemplo anterior mostrará:

    lazy proxy object(Example)#3 (0) {
      ["prop"]=>
      uninitialized(int)
    }
    string(7) "Example"
    Example::__construct
    int(1)

Cualquier acceso a las propiedades de un objeto perezoso desencadena su inicialización (incluyendo a través de ReflectionProperty). Sin embargo, algunas propiedades pueden ser conocidas de antemano y no deberían desencadenar la inicialización cuando se accede a ellas:

Ejemplo #3 Inicialización de las propiedades de manera impaciente

    <?php
    class BlogPost
    {
        public function __construct(
           public int $id,
           public string $title,
           public string $content,
        ) { }
    }

    $reflector = new ReflectionClass(BlogPost::class);

    $post = $reflector->newLazyGhost(function ($post) {
        $data = fetch_from_store($post->id);
        $post->__construct($data['id'], $data['title'], $data['content']);
    });

    // Sin esta línea, la siguiente llamada a ReflectionProperty::setValue() desencadenaría la inicialización.
    $reflector->getProperty('id')->skipLazyInitialization($post);
    $reflector->getProperty('id')->setValue($post, 123);

    // Asimismo, se puede utilizar esto directamente:
    $reflector->getProperty('id')->setRawValueWithoutLazyInitialization($post, 123);

    // El identificador puede ser accedido sin desencadenar la inicialización
    var_dump($post->id);
    ?>

Los métodos ReflectionProperty::skipLazyInitialization() y ReflectionProperty::setRawValueWithoutLazyInitialization() ofrecen formas de evitar la inicialización perezosa al acceder a una propiedad.

### Acerca de las estrategias de objetos perezosos

Los fantasmas perezosos son objetos que se inicializan en el lugar y, una vez inicializados, son indiscernibles de un objeto que nunca fue perezoso. Esta estrategia es adecuada cuando se controla tanto la instanciación como la inicialización del objeto y es inadecuada si alguna de estas operaciones es gestionada por otra parte.

Los proxys perezosos, una vez inicializados, actúan como proxys hacia una instancia real: cualquier operación en un proxy perezoso inicializado es transmitida a la instancia real. La creación de la instancia real puede ser delegada a otra parte, lo que hace que esta estrategia sea útil en los casos en que los fantasmas perezosos son inadecuados. Aunque los proxys perezosos son casi tan transparentes como los fantasmas perezosos, hay que tener cuidado cuando se utiliza su identidad, ya que el proxy y su instancia real tienen identidades distintas.

### Ciclo de vida de los objetos perezosos

Los objetos pueden ser hechos perezosos durante la instanciación utilizando ReflectionClass::newLazyGhost() o ReflectionClass::newLazyProxy(), o después de la instanciación utilizando ReflectionClass::resetAsLazyGhost() o ReflectionClass::resetAsLazyProxy(). Luego, un objeto perezoso puede ser inicializado por una de las siguientes operaciones:

- Interactuar con el objeto de una manera que desencadene la inicialización automática. Ver desencadenantes de inicialización.
- Marcar todas sus propiedades como no perezosas utilizando ReflectionProperty::skipLazyInitialization() o ReflectionProperty::setRawValueWithoutLazyInitialization().
- Llamar explícitamente a ReflectionClass::initializeLazyObject() o ReflectionClass::markLazyObjectAsInitialized().

Como los objetos perezosos se inicializan cuando todas sus propiedades son marcadas como no perezosas, los métodos anteriores no marcarán un objeto como perezoso si ninguna propiedad puede ser marcada como perezosa.

### Desencadenantes de inicialización

Los objetos perezosos están diseñados para ser completamente transparentes para sus consumidores, de modo que las operaciones normales que observan o modifican el estado del objeto desencadenarán automáticamente la inicialización antes de que se realice la operación. Esto incluye, pero no se limita a, las siguientes operaciones:

- Leer o escribir una propiedad
- Probar si una propiedad está definida o definirla.
- Acceder o modificar una propiedad a través de ReflectionProperty::getValue(), ReflectionProperty::getRawValue(), ReflectionProperty::setValue(), o ReflectionProperty::setRawValue().
- Listar las propiedades con ReflectionObject::getProperties(), ReflectionObject::getProperty(), get_object_vars().
- Iterar sobre las propiedades de un objeto que no implementa Iterator o IteratorAggregate utilizando foreach.
- Serializar el objeto con serialize(), json_encode(), etc.
- Clonar el objeto.

Las llamadas a métodos que no acceden al estado del objeto no desencadenarán la inicialización. Asimismo, las interacciones con el objeto que invocan métodos mágicos o funciones de gancho no desencadenarán la inicialización si estos métodos o funciones no acceden al estado del objeto.

#### Operaciones no desencadenantes

Las siguientes operaciones o métodos específicos permiten acceder o modificar objetos perezosos sin desencadenar la inicialización:

- Marcar las propiedades como no perezosas con ReflectionProperty::skipLazyInitialization() o ReflectionProperty::setRawValueWithoutLazyInitialization().
- Recuperar la representación interna de las propiedades utilizando get_mangled_object_vars() o convirtiendo el objeto en un array.
- Utilizando serialize() cuando `ReflectionClass::SKIP_INITIALIZATION_ON_SERIALIZE` está definido, a menos que __serialize() o __sleep() desencadenen la inicialización.
- Llamar a ReflectionObject::__toString().
- Utilizar var_dump() o debug_zval_dump(), a menos que __debugInfo() desencadene la inicialización

### Secuencia de inicialización

Esta sección describe la secuencia de operaciones realizadas cuando se desencadena una inicialización, en función de la estrategia utilizada.

#### Objetos fantasma

- El objeto es marcado como no perezoso.
- Las propiedades no inicializadas con ReflectionProperty::skipLazyInitialization() o ReflectionProperty::setRawValueWithoutLazyInitialization() se establecen en sus valores por defecto, si corresponde. En este punto, el objeto se asemeja a un objeto creado con ReflectionClass::newInstanceWithoutConstructor(), excepto por las propiedades ya inicializadas.
- La función de inicialización es llamada luego con el objeto como primer parámetro. La función debe, pero no está obligada, inicializar el estado del objeto, y debe devolver `null` o ningún valor. El objeto ya no es perezoso en este punto, por lo que la función puede acceder directamente a sus propiedades.

Después de la inicialización, el objeto es indiscernible de un objeto que nunca fue perezoso.

#### Objetos proxy

- El objeto es marcado como no perezoso.
- A diferencia de los objetos fantasma, las propiedades del objeto no se modifican en esta etapa.
- La función fabrica es llamada con el objeto como primer parámetro y debe devolver una instancia no perezosa de una clase compatible (ver ReflectionClass::newLazyProxy()).
- La instancia devuelta es llamada instancia real y se adjunta al proxy.
- Los valores de las propiedades del proxy son descartados como si unset() es llamado.

Después de la inicialización, el acceso a cualquier propiedad en el proxy dará el mismo resultado que el acceso a la propiedad correspondiente en la instancia real; todos los accesos a las propiedades en el proxy son transmitidos a la instancia real, incluyendo las propiedades declaradas, dinámicas, inexistentes, o las propiedades marcadas con ReflectionProperty::skipLazyInitialization() o ReflectionProperty::setRawValueWithoutLazyInitialization().

El objeto proxy en sí mismo no es reemplazado o sustituido por la instancia real.

Aunque la fabrica recibe el proxy como primer parámetro, no se espera que lo modifique (las modificaciones están permitidas pero serán perdidas en la etapa final de inicialización). Sin embargo, el proxy puede ser utilizado para decisiones basadas en los valores de las propiedades inicializadas, la clase, el objeto mismo, o su identidad. Por ejemplo, el inicializador podría utilizar el valor de una propiedad inicializada durante la creación de la instancia real.

#### Comportamiento común

El alcance y el contexto $this de la función de inicialización o de la fabrica permanecen sin cambios, y se aplican las restricciones de visibilidad habituales.

Después de una inicialización exitosa, la función de inicialización o la fabrica ya no es referenciada por el objeto y puede ser liberada si no tiene otras referencias.

Si la inicialización lanza una excepción, el estado del objeto se restaura a su estado pre-inicialización y el objeto es marcado nuevamente como perezoso. En otras palabras, todos los efectos en el objeto mismo son anulados. Otros efectos secundarios, como los efectos en otros objetos, no son anulados. Esto evita la exposición de una instancia parcialmente inicializada en caso de fallo.

### Clonación

Clonar un objeto perezoso desencadena su inicialización antes de que el clon sea creado, resultando en un objeto inicializado.

Para los objetos proxy, el proxy y su instancia real son clonados, y el clon del proxy es devuelto. La método `__clone` es llamada en la instancia real, no en el proxy. El proxy clonado y la instancia real clonada están enlazados como lo están durante la inicialización, por lo que los accesos al clon del proxy son transmitidos al clon de la instancia real.

Este comportamiento garantiza que el clon y el objeto original mantengan estados separados. Las modificaciones realizadas en el objeto original o en el estado de su inicializador después de la clonación no afectan al clon. Clonar tanto el proxy como su instancia real, en lugar de devolver un clon de la instancia real solamente, garantiza que la operación de clonación devuelva sistemáticamente un objeto de la misma clase.

### Destructores

Para los objetos perezosos, el destructor solo es llamado si el objeto ha sido inicializado. Para los proxys, el destructor solo es llamado en la instancia real, si existe.

Los métodos ReflectionClass::resetAsLazyGhost() y ReflectionClass::resetAsLazyProxy() pueden invocar el destructor del objeto reinicializado.

## Modificaciones en POO (Programación orientada a objetos)

Los cambios del modelo de objetos de PHP se recogen aquí. Más información y otras notas pueden encontrarse en la documentación sobre POO en PHP.

Versión | Descripción
--- | ---
8.4.0 | Adición: Soporte para los hooks de propiedad.
8.4.0 | Adición: Soporte de los objetos perezosos.
8.1.0 | Adición: Soporte para el modificador final para las constantes de clase. Además, las constantes de interfaces pueden ser redefinidas por omisión.
8.0.0 | Adición: Soporte del operador nullsafe ?-> para acceder a las propiedades y métodos sobre objetos que pueden ser null.
7.4.0 | Cambio: Es ahora posible lanzar excepciones dentro de __toString().
7.4.0 | Adición: Soporte limitado para la covarianza del tipo de retorno y contravarianza para el tipo de argumento. Soporte completo de varianza está únicamente disponible si el autocargado es utilizado. Dentro de un fichero único solo las referencias no-cíclicas de tipo son posibles.
7.4.0 | Adición: Es ahora posible tipar las propiedades de clase.
7.3.0 | Incompatibilidad: El desempaquetado de argumento de Traversables con claves no-intes ya no es soportado. Este comportamiento no estaba previsto y por consiguiente fue eliminado.
7.3.0 | Incompatibilidad: En versiones anteriores era posible separar las propiedades estáticas asignando una referencia. Esto ha sido eliminado.
7.3.0 | Cambio: El operador instanceof permite ahora literales como primer operando, en este caso el resultado es siempre `false`.
7.2.0 | Obsoleto: El método __autoload() ha sido declarado obsoleto en favor de spl_autoload_register().
7.2.0 | Cambio: El siguiente nombre no puede ser utilizado para nombrar clases, interfaces o traits: `object`.
7.2.0 | Cambio: Una coma colgante puede ahora ser añadida a la sintaxis use agrupada para los espacios de nombres.
7.2.0 | Cambio: Ampliación del tipo de los parámetros. El tipo de los parámetros de los métodos reescritos y de implementación de interfaz puede ahora ser omitido.
7.2.0 | Cambio: Los métodos abstractos pueden ahora ser reescritos cuando una clase abstracta extiende otra clase abstracta.
7.1.0 | Cambio: Los siguientes nombres no pueden ser utilizados para nombrar clases, interfaces o traits: `void` y `iterable`.
7.1.0 | Adición: Es ahora posible definir la visibilidad de las constantes de clase.
7.0.0 | Obsoleto: Llamada estática a métodos que no están declarados como estáticos.
7.0.0 | Obsoleto: Constructor estilo PHP 4. Es decir, los métodos que tienen el mismo nombre que la clase en la que están definidos.
7.0.0 | Adición: Declaración use agrupada: las clases, funciones y constantes que son importadas desde un mismo espacio de nombres pueden ahora ser agrupadas juntas en una sola declaración use.
7.0.0 | Adición: Soporte para las clases anónimas ha sido añadido gracias a `new class`.
7.0.0 | Incompatibilidad: Iterar sobre un no-Traversable object tendrá ahora el mismo comportamiento que iterar sobre los arrays por referencia.
7.0.0 | Cambio: La definición de propiedades (compatibles) en dos traits utilizados ya no provoca un error.
5.6.0 | Adición: El método __debugInfo().
5.5.0 | Adición: La constante mágica ::class.
5.5.0 | Adición: finally para manejar las excepciones.
5.4.0 | Adición: traits.
5.4.0 | Cambio: Si una clase abstracta define una firma para el constructor , esta será ahora aplicada.
5.3.3 | Cambio: Los métodos con el mismo nombre que el último elemento en un espacio de nombres ya no son considerados como un constructor. Este cambio no afecta a las clases sin espacio de nombres.
5.3.0 | Cambio: Las clases que implementan una interfaz con métodos que tienen valores por omisión definidos en sus prototipos ya no están obligadas a respetar los valores por omisión definidos en la interfaz.
5.3.0 | Cambio: Es ahora posible referenciar una clase utilizando una variable (e.g. : `echo $classname::constant;`). El valor de la variable no puede ser una palabra clave (e.g. : `self`, `parent` o `static`).
5.3.0 | Cambio: Un error de nivel `E_WARNING` es emitido si los métodos mágicos de sobrecarga son declarados como estáticos. La visibilidad pública también es requerida.
5.3.0 | Cambio: Anteriormente a 5.3.0, las excepciones lanzadas en la función __autoload() no podían ser tratadas en un bloque catch y resultaban en un error fatal. Ahora, las excepciones lanzadas en la función __autoload pueden ser capturadas en un bloque catch y tratadas. Si una excepción personalizada es lanzada, entonces su clase debe estar disponible. La función __autoload puede ser utilizada recursivamente para autocargar la clase de excepción personalizada.
5.3.0 | Adición: El método __callStatic.
5.3.0 | Adición: heredoc y nowdoc son soportadas para definir las constantes de clases y las propiedades. Nota: Los valores heredoc deben seguir las mismas reglas que los string rodeados de comillas dobles (e.g. sin variables dentro).
5.3.0 | Adición: Resolución Estática Tardía.
5.3.0 | Adición: El método __invoke().
5.2.0 | Cambio: El método __toString() solo era llamado en llamadas a echo o print. Ahora, es llamado en cualquier contexto de string (e.g. en printf() con el modificador `%s`) pero no en otros contextos (e.g. con el modificador `%d`). A partir de PHP 5.2.0, convertir un object sin método __toString en string emite un error `E_RECOVERABLE_ERROR`.
5.1.3 | Cambio: En versiones anteriores de PHP 5, el uso de `var` era considerado obsoleto y emitía un error `E_STRICT`. Ya no es el caso.
5.1.0 | Cambio: El método estático __set_state() es ahora llamado para las clases exportadas vía var_export().
5.1.0 | Adición: Métodos __isset() y __unset().

# Los espacios de nombres

## Tabla de contenidos

- Introducción
- Espacios de nombres
- Subespacio de nombres
- Definición de varios espacios de nombres en el mismo archivo
- Introducción
- Espacios de nombres y lenguaje dinámico
- Comando namespace y __NAMESPACE__
- Importación y alias
- Global
- Retorno al espacio global
- Reglas de resolución de nombres
- Preguntas frecuentes

## Introducción a los espacios de nombres

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

¿Qué son los espacios de nombres? En su definición más amplia, representan un medio para encapsular elementos. Esto puede concebirse como un concepto abstracto, por varias razones. Por ejemplo, en un sistema de archivos, los directorios representan un grupo de archivos asociados y sirven como espacio de nombres para los archivos que contienen. Un ejemplo concreto es que el archivo `foo.txt` puede existir en ambos directorios `/home/greg` y `/home/other`, pero que las dos copias de `foo.txt` no pueden coexistir en el mismo directorio. Además, para acceder al archivo `foo.txt` desde fuera del directorio `/home/greg`, es necesario especificar el nombre del directorio utilizando un separador de directorios, como `/home/greg/foo.txt`. El mismo principio se aplica a los espacios de nombres en el mundo de la programación.

En el mundo de PHP, los espacios de nombres están diseñados para resolver dos problemas que enfrentan los autores de bibliotecas y aplicaciones al reutilizar elementos como clases o bibliotecas de funciones:

1. Colisiones de nombres entre el código que se crea, las clases, funciones o constantes internas de PHP, o las de bibliotecas de terceros.
2. La capacidad de crear alias o acortar nombres como Nombres_Extremadamente_Largos para ayudar a resolver el primer problema y mejorar la legibilidad del código.

Los espacios de nombres de PHP proporcionan un medio para agrupar clases, interfaces, funciones o constantes. Aquí hay un ejemplo de sintaxis de los espacios de nombres de PHP:

Ejemplo #1 Ejemplo de sintaxis de espacios de nombres

    <?php
    namespace mi\nombre; // Ver la sección "Definición de espacios de nombres"

    class MiClase {}
    function mifuncion() {}
    const MICONSTANTE = 1;

    $a = new MiClase;
    print $a::class . "\n";
    $c = new \mi\nombre\MiClase; // Ver la sección "Espacio global"
    print $c::class . "\n";

    $a = strlen('hola'); // Ver "Uso de espacios de nombres: retorno al espacio global
    print $a . "\n";

    $d = namespace\MICONSTANTE; // Ver "El operador namespace y la constante __NAMESPACE__
    print $d . "\n";

    $d = __NAMESPACE__ . '\MICONSTANTE';
    echo constant($d); // Ver "Espacios de nombres y características dinámicas"

> Nota: Los nombres de espacios de nombres no son sensibles a mayúsculas/minúsculas.

> Nota:

> Los espacios de nombres `PHP`, así como los nombres compuestos que comienzan con estos nombres (como `PHP\Classes`) están reservados para el uso interno del lenguaje y no deben usarse en el código del espacio de usuario.

## Definición de espacios de nombres

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Aunque el código PHP válido puede contenerse en un espacio de nombres, solo los siguientes tipos de código pueden verse afectados por los espacios de nombres: las clases (incluyendo las abstractas, los traits y los enums), las interfaces, las funciones y las constantes.

Los espacios de nombres se declaran con la palabra clave `namespace`. Un archivo que contiene un espacio de nombres debe declarar el espacio al principio del archivo, antes de cualquier otro código, con una sola excepción: la palabra clave declare.

Ejemplo #1 Declaración de un espacio de nombres

    <?php
    namespace MonProjet;

    const CONNEXION_OK = 1;
    class Connexion { /* ... */ }
    function connecte() { /* ... */ }

> Nota: Los nombres completamente calificados (es decir, los nombres que comienzan con un backslash) no están autorizados en las declaraciones de espacios de nombres, ya que tales construcciones se interpretan como expresiones de espacio de nombres relativo.

El único elemento autorizado antes de la declaración de espacio de nombres es la instrucción `declare`, para definir la codificación del archivo fuente. Además, ningún código no-PHP puede preceder a la declaración de espacio de nombres, incluyendo espacios:

Ejemplo #2 Error de declaración de un espacio de nombres

    <html>
    <?php
    namespace MonProjet; // error fatal: el espacio de nombres debe ser el primer elemento del script

Además, a diferencia de otras estructuras de PHP, el mismo espacio de nombres puede definirse en varios archivos, lo que permite dividir el contenido de un espacio de nombres en varios archivos.

## Declaración de un subespacio de nombres

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Al igual que con los archivos y los directorios, los espacios de nombres también son capaces de especificar una jerarquía de espacios de nombres. Por lo tanto, un nombre de espacio de nombres puede definirse con sus subniveles:

Ejemplo #1 Declaración de un espacio de nombres con jerarquía

    <?php
    namespace MonProjet\Sous\Niveau;

    const CONNEXION_OK = 1;
    class Connexion { /* ... */ }
    function connecte() { /* ... */  }

En el ejemplo anterior, se crean la constante `MonProjet\Sous\Niveau\CONNEXION_OK`, la clase `MonProjet\Sous\Niveau\Connexion` y la función `MonProjet\Sous\Niveau\connecte`.

## Definición de varios espacios de nombres en el mismo archivo

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

También pueden declararse varios espacios de nombres en el mismo archivo. Hay dos sintaxis autorizadas.

Ejemplo #1 Declaración de varios espacios de nombres, sintaxis de combinación simple

    <?php
    namespace MonProjet;

    const CONNEXION_OK = 1;
    class Connexion { /* ... */ }
    function connecte() { /* ... */  }

    namespace AutreProjet;

    const CONNEXION_OK = 1;
    class Connexion { /* ... */ }
    function connecte() { /* ... */  }

Esta sintaxis no se recomienda para combinar espacios de nombres en un solo archivo. En su lugar, se recomienda utilizar la sintaxis de llaves.

Ejemplo #2 Declaración de varios espacios de nombres, sintaxis de llaves

    <?php
    namespace MonProjet {

    const CONNEXION_OK = 1;
    class Connexion { /* ... */ }
    function connecte() { /* ... */  }
    }

    namespace AutreProjet {

    const CONNEXION_OK = 1;
    class Connexion { /* ... */ }
    function connecte() { /* ... */  }
    }

Se recomienda encarecidamente, como práctica de codificación, no mezclar varios espacios de nombres en el mismo archivo. El uso recomendado es combinar varios scripts PHP en el mismo archivo.

Para combinar varios códigos sin espacios de nombres en código con espacio de nombres, solo se admite la sintaxis de llaves. El código global debe estar encerrado por un espacio de nombres sin nombre, como este:

Ejemplo #3 Declaración de varios espacios de nombres con un espacio sin nombre

    <?php
    namespace MonProjet {

    const CONNEXION_OK = 1;
    class Connexion {
        public static function start() {
            print __METHOD__ . "\n";
        }
    }

    function connecte() {
        print __FUNCTION__ . "\n";
    }
    }

    namespace { // código global
    print strlen("hi") . "\n";
    MonProjet\connecte();
    MonProjet\Connexion::start();
    }

No puede existir ningún código PHP fuera de las llaves del espacio de nombres, excepto para abrir una nueva instrucción declare.

Ejemplo #4 Declaración de varios espacios de nombres con un espacio sin nombre (2)

    <?php
    declare(strict_types=1);
    namespace MonProjet {

    const CONNEXION_OK = 1;
    class Connexion {
        public static function start() {
            print __METHOD__ . "\n";
        }
    }

    function connecte() {
        print __FUNCTION__ . "\n";
    }
    }

    namespace { // código global
    print strlen("hi") . "\n";
    MonProjet\connecte();
    MonProjet\Connexion::start();
    }

## Uso de espacios de nombres: introducción

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Antes de discutir el uso de espacios de nombres, es importante comprender cómo PHP deduce qué espacio de nombres está utilizando su código. Puede hacerse una analogía simple entre los espacios de nombres de PHP y un sistema de archivos. Hay tres formas de acceder a un archivo en un sistema de archivos:

1. Un nombre de archivo relativo, como `foo.txt`. Esto se resuelve en `dossiercourant/foo.txt` donde `dossiercourant` es el directorio de trabajo. Si el directorio actual es `/home/foo`, este nombre se resuelve en `/home/foo/foo.txt`.
2. Una ruta relativa, como `sub-dossier/foo.txt`. Esto se resuelve en `dossiercourant/sub-dossier/foo.txt`.
3. Una ruta absoluta, como `/main/foo.txt`. Esto se resuelve en `/main/foo.txt`.

El mismo principio puede aplicarse a los espacios de nombres de PHP. Por ejemplo, puede hacer referencia a una clase de tres maneras:

1. Un nombre sin calificador, o una clase sin prefijo, como `$a = new foo();` o `foo::methodestatique();`. Si el espacio de nombres actual es `espacedenomscourant`, esto se resuelve en `espacedenomscourant\foo`. Si el espacio de nombres es global, es decir, el espacio de nombres sin nombre, esto se convierte en `foo`. Una advertencia: los nombres sin calificador para funciones y constantes se tomarán del espacio de nombres global, si la función no está definida en el espacio de nombres actual. Ver Uso de espacios de nombres: retorno al espacio de nombres global para funciones y constantes para más detalles.
2. Un nombre calificado, o una clase con prefijo como `$a = new sousespacedenoms\foo();` o `sousespacedenoms\foo::methodestatique();`. Si el espacio de nombres actual es `espacedenomscourant`, esto se convierte en `espacedenomscourant\sousespacedenoms\foo`. Si el código es global, es decir, el espacio de nombres sin nombre, esto se convierte en `sousespacedenoms\foo`.
3. Un nombre absoluto, o un nombre con prefijo con un operador global como `$a = new \espacedenomscourant\foo();` o `\espacedenomscourant\foo::methodestatique();`. Esto siempre hace referencia al nombre literal especificado en el código: `espacedenomscourant\foo`.

Aquí hay un ejemplo de las tres sintaxis, en código real:

file1.php

    <?php
    namespace Foo\Bar\sousespacedenoms;

    const FOO = 1;
    function foo() {}
    class foo
    {
        static function methodestatique() {}
    }

file2.php

    <?php
    namespace Foo\Bar;
    include 'file1.php';

    const FOO = 2;
    function foo() {}
    class foo
    {
        static function methodestatique() {}
    }

    /* nombre no calificado */
    foo(); // Se convierte en Foo\Bar\foo
    foo::methodestatique(); // Se convierte en Foo\Bar\foo, método methodestatique
    echo FOO; // Se convierte en la constante Foo\Bar\FOO

    /* nombre calificado */
    sousespacedenoms\foo(); // Se convierte en la función Foo\Bar\sousespacedenoms\foo
    sousespacedenoms\foo::methodestatique(); // se convierte en la clase Foo\Bar\sousespacedenoms\foo,
                                      // método methodestatique
    echo sousespacedenoms\FOO; // Se convierte en la constante Foo\Bar\sousespacedenoms\FOO

    /* nombre absoluto */
    \Foo\Bar\foo(); // Se convierte en la función Foo\Bar\foo
    \Foo\Bar\foo::methodestatique(); // Se convierte en la clase Foo\Bar\foo, método methodestatique
    echo \Foo\Bar\FOO; // Se convierte en la constante Foo\Bar\FOO

Tenga en cuenta que para acceder a cualquier clase, función o constante global, puede utilizarse un nombre absoluto, como \strlen() o \Exception o \`INI_ALL`.

Ejemplo #1 Acceso a clases, funciones y constantes globales desde un espacio de nombres

    <?php
    namespace Foo;

    function strlen() {}
    const INI_ALL = 3;
    class Exception {}

    print \strlen('hi') . "\n"; // llama a la función global strlen
    print \INI_ALL . "\n"; // acceso a una constante INI_ALL
    $c = new \Exception('error'); // instancia la clase global Exception
    print $c::class . "\n";

## Espacios de nombres y lenguaje dinámico

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

La implementación de espacios de nombres de PHP está influenciada por su naturaleza dinámica como lenguaje de programación. Por lo tanto, para convertir código como el del siguiente ejemplo en un espacio de nombres:

Ejemplo #1 Acceso dinámico a elementos

example1.php:

    <?php
    class classname
    {
        function __construct()
        {
            echo __METHOD__,"\n";
        }
    }
    function funcname()
    {
        echo __FUNCTION__,"\n";
    }
    const constname = "global";

    $a = 'classname';
    $obj = new $a; // muestra classname::__construct
    $b = 'funcname';
    $b(); // muestra funcname
    echo constant('constname'), "\n"; // muestra global

Es necesario utilizar un nombre absoluto (el nombre de la clase, con su prefijo de espacio de nombres). Tenga en cuenta que no hay diferencia entre un nombre absoluto y un nombre calificado en un nombre de clase, función o constante dinámica, lo que hace que el backslash inicial no sea necesario.

Ejemplo #2 Acceso dinámico a espacios de nombres

    <?php
    namespace nomdelespacedenoms;
    class classname
    {
        function __construct()
        {
            echo __METHOD__,"\n";
        }
    }
    function funcname()
    {
        echo __FUNCTION__,"\n";
    }
    const constname = "namespaced";

    /* Tenga en cuenta que si utiliza comillas dobles, "\\nomdelespacedenoms\\classname" debe usarse */
    $a = '\nomdelespacedenoms\classname';
    $obj = new $a; // muestra nomdelespacedenoms\classname::__construct
    $a = 'nomdelespacedenoms\classname';
    $obj = new $a; // también muestra nomdelespacedenoms\classname::__construct
    $b = 'nomdelespacedenoms\funcname';
    $b(); // muestra nomdelespacedenoms\funcname
    $b = '\nomdelespacedenoms\funcname';
    $b(); // también muestra nomdelespacedenoms\funcname
    echo constant('\nomdelespacedenoms\constname'), "\n"; // muestra namespaced
    echo constant('nomdelespacedenoms\constname'), "\n"; // también muestra namespaced

Se recomienda leer la nota sobre la protección de espacios de nombres en cadenas.

## El comando namespace y la constante __NAMESPACE__

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

PHP admite dos medios para acceder de manera abstracta a los elementos en el espacio de nombres actual, a saber, la constante mágica `__NAMESPACE__` y el comando `namespace`.

El valor de `__NAMESPACE__` es una cadena que contiene el nombre del espacio de nombres actual. En el espacio global, sin nombre, contiene una cadena vacía.

Ejemplo #1 Ejemplo con __NAMESPACE__, en un código con espacio de nombres

    <?php
    namespace MonProjet;

    echo '"', __NAMESPACE__, '"'; // muestra "MonProjet"

Ejemplo #2 Ejemplo con __NAMESPACE__, en un código con espacio de nombres global

    <?php
    echo '"', __NAMESPACE__, '"'; // muestra ""

La constante `__NAMESPACE__` es útil para construir dinámicamente nombres, como:

Ejemplo #3 Uso de __NAMESPACE__ para una construcción dinámica de nombres

    <?php
    namespace MonProjet;

    function get($classname)
    {
        $a = __NAMESPACE__ . '\\' . $classname;
        return new $a;
    }

El comando `namespace` también puede usarse para solicitar explícitamente un elemento del espacio de nombres actual, o de un subespacio. Es el equivalente para los espacios de nombres del operador `self` de las clases.

Ejemplo #4 El operador namespace, en un espacio de nombres

    <?php
    namespace MonProjet;

    use blah\blah as mine; // Ver "Uso de espacios de nombres: alias e importación"

    blah\mine(); // llama a la función MonProjet\blah\mine()
    namespace\blah\mine(); // llama a la función MonProjet\blah\mine()

    namespace\func(); // llama a la función MonProjet\func()
    namespace\sub\func(); // llama a la función MonProjet\sub\func()
    namespace\cname::method(); // llama al método estático "method" de la clase MonProjet\cname
    $a = new namespace\sub\cname(); // instancia un objeto de la clase MonProjet\sub\cname
    $b = namespace\CONSTANT; // asigna el valor de la constante MonProjet\CONSTANT a $b

Ejemplo #5 El operador namespace, en el espacio de nombres global

    <?php

    namespace\func(); // llama a la función func()
    namespace\sub\func(); // llama a la función sub\func()
    namespace\cname::method(); // llama al método estático "method" de la clase cname
    $a = new namespace\sub\cname(); // instancia un objeto de la clase sub\cname
    $b = namespace\CONSTANT; // asigna el valor de la constante CONSTANT a $b

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Uso de espacios de nombres: importación y alias

La capacidad de hacer referencia a un nombre absoluto con un alias o importando un espacio de nombres es estratégica. Es un beneficio similar a los enlaces simbólicos en un sistema de archivos.

PHP puede crear alias(/importar) constantes, funciones, clases, interfaces, traits, enumeraciones y espacios de nombres.

Un alias se crea con el operador `use`. Aquí hay un ejemplo que presenta los cinco tipos de importación:

Ejemplo #1 Importación y alias con el operador use

    <?php
    namespace foo;
    use My\Full\Classname as Another;

    // Esto es lo mismo que use My\Full\NSname as NSname
    use My\Full\NSname;

    // importación de una clase global
    use ArrayObject;

    // importación de una función
    use function My\Full\functionName;

    // alias de una función
    use function My\Full\functionName as func;

    // importación de una constante
    use const My\Full\CONSTANT;

    $obj = new namespace\Another; // instancia un objeto de la clase foo\Another
    $obj = new Another; // instancia un objeto de la clase My\Full\Classname
    NSname\subns\func(); // llama a la función My\Full\NSname\subns\func
    $a = new ArrayObject(array(1)); // instancia un objeto de la clase ArrayObject
    // Sin la instrucción "use ArrayObject" habríamos instanciado un objeto de la clase foo\ArrayObject
    func(); // Llama a la función My\Full\functionName
    echo CONSTANT; // muestra el valor de My\Full\CONSTANT

Tenga en cuenta que para los nombres con ruta (los nombres absolutos que contienen separadores de espacios, como `Foo\Bar`, en comparación con los nombres globales, como `FooBar`, que no los contienen), el backslash inicial no es necesario y no se recomienda, ya que los nombres importados deben ser absolutos y no se resuelven relativamente al espacio de nombres actual.

Además, PHP admite atajos prácticos, como las instrucciones use múltiples.

Ejemplo #2 Importación y alias múltiples con el operador use

    <?php
    use My\Full\Classname as Another, My\Full\NSname;

    $obj = new Another; // instancia un objeto de la clase My\Full\Classname
    NSname\subns\func(); // llama a la función My\Full\NSname\subns\func

La importación se realiza durante la compilación, por lo que no afecta a las clases, funciones y constantes dinámicas.

Ejemplo #3 Importación y nombres de espacios dinámicos

    <?php
    use My\Full\Classname as Another, My\Full\NSname;

    $obj = new Another; // instancia un objeto de la clase My\Full\Classname
    $a = 'Another';
    $obj = new $a;      // instancia un objeto de la clase Another

Además, la importación solo afecta a los nombres sin calificación. Los nombres absolutos siguen siendo absolutos y no se modifican por una importación.

Ejemplo #4 Importación y nombres de espacios absolutos

    <?php
    use My\Full\Classname as Another, My\Full\NSname;

    $obj = new Another; // instancia un objeto de la clase My\Full\Classname
    $obj = new \Another; // instancia un objeto de la clase Another
    $obj = new Another\untruc; // instancia un objeto de la clase My\Full\Classname\untruc
    $obj = new \Another\untruc; // instancia un objeto de la clase Another\untruc

### Reglas de contexto para la importación

La palabra clave `use` debe declararse en el contexto más externo de un archivo (el contexto global) o en las declaraciones de espacio de nombres. Esto se debe a que la importación se realiza durante la compilación y no durante la ejecución, por lo que no se pueden apilar los contextos. El ejemplo siguiente muestra usos incorrectos de la palabra clave `use`:

Ejemplo #5 Reglas de importación incorrectas

    <?php
    namespace Languages;

    function toGreenlandic
    {
        use Languages\Danish;
        // ...
    }

> Nota:

> Las reglas de importación se basan en archivos, lo que significa que los archivos incluidos no heredarán PAS las reglas de importación del archivo padre.

### Declaración del grupo `use`

Las clases, funciones y constantes importadas desde el mismo `namespace` pueden agruparse en una sola instrucción `use`.

    <?php

    use some\namespace\ClassA;
    use some\namespace\ClassB;
    use some\namespace\ClassC as C;

    use function some\namespace\fn_a;
    use function some\namespace\fn_b;
    use function some\namespace\fn_c;

    use const some\namespace\ConstA;
    use const some\namespace\ConstB;
    use const some\namespace\ConstC;

    // es equivalente a la siguiente declaración de grupo use
    use some\namespace\{ClassA, ClassB, ClassC as C};
    use function some\namespace\{fn_a, fn_b, fn_c};
    use const some\namespace\{ConstA, ConstB, ConstC};

## Espacio de nombres global

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Sin ninguna definición de espacio de nombres, todas las clases y las funciones se colocan en el espacio de nombres global: como en PHP antes de que los espacios de nombres fueran introducidos. Al prefijar un nombre con un backslash `\`, se puede solicitar el uso del espacio de nombres global, incluso en un contexto de espacio de nombres específico.

Ejemplo #1 Especificación de espacio de nombres global

    <?php
    namespace A\B\C;

    /* Esta función es A\B\C\fopen */
    function fopen() {
         /* ... */
         $f = \fopen(...); // llamada a fopen global
         return $f;
    }

## Uso de espacios de nombres: retorno al espacio global para funciones y constantes

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

En un espacio de nombres, cuando PHP encuentra un nombre sin calificación, ya sea una clase, una función o una constante, lo resuelve con diferentes prioridades. Los nombres de clases siempre se resuelven con el espacio de nombres actual. Para acceder a clases internas o a clases que no están en un espacio de nombres, es necesario representarlas con su nombre absoluto, como:

Ejemplo #1 Acceso a clases globales desde un espacio de nombres

    <?php
    namespace A\B\C;
    class Exception extends \Exception {}

    $a = new Exception('hi'); // $a es un objeto de la clase A\B\C\Exception
    var_dump($a::class);
    $b = new \Exception('hi'); // $b es un objeto de la clase Exception
    var_dump($b::class);

    $c = new ArrayObject; // error fatal, clase A\B\C\ArrayObject no encontrada

Para las funciones y constantes, PHP las buscará en el espacio global si no puede encontrarlas en el espacio de nombres actual.

Ejemplo #2 Acceso a funciones y constantes globales en un espacio de nombres

    <?php
    namespace A\B\C;

    const E_ERROR = 45;
    function strlen($str)
    {
        return \strlen($str) - 1;
    }

    echo E_ERROR, "\n"; // muestra "45"
    echo INI_ALL, "\n"; // muestra "7": acceso al espacio de nombres global INI_ALL

    echo strlen('hi'), "\n"; // muestra "1"
    if (is_array('hi')) { // muestra "no es un array"
        echo "es un array\n";
    } else {
        echo "no es un array\n";
    }

## Reglas de resolución de nombres

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

En el contexto de las reglas de resolución, hay varias definiciones importantes:

Definiciones para espacios de nombres
nombre no calificado

  Esto es un identificador que no contiene un separador de espacio de nombres. Por ejemplo: `Foo`

nombre calificado

  Esto es un identificador que contiene un separador de espacio de nombres. Por ejemplo: `Foo\Bar`

Nombre absoluto

  Esto es un identificador que comienza con un separador de espacio de nombres. Por ejemplo: `\Foo\Bar`. El espacio de nombres `Foo` también es un nombre absoluto.

Nombre Relativo

  Es un identificador que comienza con `namespace`, como `namespace\Foo\Bar`.

Los nombres se resuelven siguiendo las siguientes reglas:

1. Los nombres absolutos siempre se traducen a nombres sin el separador de namespace. Por ejemplo, `\A\B` se traduce a `A\B`.
2. Todos los nombres que no son absolutos se traducen con `namespace` reemplazado por el namespace actual. Si el nombre aparece en el namespace global, el prefijo `namespace\` se elimina. Por ejemplo `namespace\A` en el namespace `X\Y` se traduce a `X\Y\A`. El mismo nombre en el namespace global se traduce a `A`.
3. Para los nombres absolutos, el primer segmento se traduce de acuerdo con la clase/namespace de la tabla de importación. Por ejemplo, si el namespace `A\B\C` se importa como `C`, el nombre `C\D\E` se traduce a `A\B\C\D\E`.
4. Para los nombres absolutos, si ninguna regla de importación se aplica, el namespace actual se prefiere al nombre. Por ejemplo, el nombre `C\D\E` en el namespace `A\B`, se traduce a `A\B\C\D\E`.
5. Para los nombres absolutos, el nombre se traduce en relación con la tabla actual de importación para el tipo de símbolo respectivo. Esto significa que un nombre que se asemeja a una clase se traduce de acuerdo con la tabla de importación de class/namespace, los nombres de funciones utilizando la tabla de importación de funciones, y las constantes utilizando la tabla de importación de constantes. Por ejemplo, después `use A\B\C;` un uso como `new C()` corresponde al nombre `A\B\C()`. De manera similar, después de `use function A\B\foo;` un uso como `foo()` corresponde al nombre `A\B\foo`.
6. Para los nombres relativos, si ninguna regla se aplica, y el nombre hace referencia a una clase, el namespace actual sirve como prefijo. Por ejemplo `new C()` en el namespace `A\B` corresponde al nombre `A\B\C`.
7. Para los nombres relativos, si ninguna regla se aplica, y el nombre hace referencia a una función o constante, y el código está fuera del namespace global, el nombre se resuelve durante la ejecución. Supongamos que el código está en el namespace `A\B`, aquí es cómo se resuelve una llamada a la función `foo()`:
   1. Busca una función en el espacio de nombres actual: `A\B\foo()`.
   2. Intenta encontrar y llamar a la función global `foo()`.

Ejemplo #1 Ejemplos de resolución de espacios de nombres

    <?php
    namespace A;
    use B\D, C\E as F;

    // llamadas de funciones

    foo();      // intenta llamar a la función "foo" en el espacio de nombres "A"
                // luego llama a la función global "foo"

    \foo();     // llama a la función "foo" definida en el espacio de nombres global

    my\foo();   // llama a la función "foo" definida en el espacio de nombres "A\my"

    F();        // intenta llamar a la función "F" definida en el espacio "A"
                // luego intenta llamar a la función global "F"

    // referencias de clases

    new B();    // crea un objeto de la clase "B" definida en el espacio de nombres  "A"
                // si no se encuentra, intenta el autocargado en la clase "A\B"

    new D();    // crea un objeto de la clase "D" definida en el espacio de nombres  "B"
                // si no se encuentra, intenta el autocargado en la clase "B\D"

    new F();    // crea un objeto de la clase "E" definida en el espacio de nombres  "C"
                // si no se encuentra, intenta el autocargado en la clase "C\E"

    new \B();   // crea un objeto de la clase "B" definida en el espacio de nombres global
                // si no se encuentra, intenta el autocargado en la clase "B"

    new \D();   // crea un objeto de la clase "D" definida en el espacio de nombres global
                // si no se encuentra, intenta el autocargado en la clase "D"

    new \F();   // crea un objeto de la clase "F" definida en el espacio de nombres global
                // si no se encuentra, intenta el autocargado en la clase "F"

    // métodos estáticos y funciones de espacio de nombres de otro espacio

    B\foo();    // llama a la función "foo" del espacio de nombres "A\B"

    B::foo();   // llama al método "foo" de la clase "B" definida en el espacio de nombres  "A"
                // si la clase "A\B" no se encuentra, intenta el autocargado en la clase "A\B"

    D::foo();   // llama al método "foo" de la clase "D" definida en el espacio de nombres  "B"
                // si la clase "B\D" no se encuentra, intenta el autocargado en la clase "B\D"

    \B\foo();   // llama a la función "foo" del espacio de nombres "B"

    \B::foo();  // llama al método "foo" de la clase "B" ubicada en el espacio de nombres global
                // si la clase "B" no se encuentra, intenta el autocargado en la clase "B"

    // métodos estáticos y funciones de espacio de nombres del espacio actual

    A\B::foo();   // llama al método "foo" de la clase "B" del espacio de nombres "A\A"
                  // si la clase "A\A\B" no se encuentra, intenta el autocargado en la clase "A\A\B"

    \A\B::foo();  // llama al método "foo" de la clase "B" del espacio de nombres "A"
                  // si la clase "A\B" no se encuentra, intenta el autocargado en la clase "A\B"

## Preguntas frecuentes: lo que debe saber sobre espacios de nombres

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Esta FAQ se divide en dos secciones: las preguntas comunes, y los puntos particulares de la implementación, que pueden ser útiles para la comprensión global.

Primero, las preguntas comunes.

1. Si no utilizo espacios de nombres, ¿debo preocuparme por ellos?
2. ¿Cómo utilizar una clase global o interna desde un espacio de nombres?
3. ¿Cómo utilizar las clases de espacios de nombres, las funciones o las constantes en su propio espacio?
4. ¿Cómo se resuelve un nombre como `\mon\nom` o `\nom`?
5. ¿Cómo se resuelve un nombre como `mon\nom`?
6. ¿Cómo se resuelve un nombre de clase sin calificación, como `nom`?
7. ¿Cómo se resuelve una función sin calificación o una constante de nombre `nom`?

Aquí están los puntos particulares de la implementación, que pueden ser útiles para la comprensión global.

1. Los nombres importados no deben entrar en conflicto con las clases definidas en el mismo archivo
2. Los espacios de nombres anidados están prohibidos
3. Los nombres de espacios de nombres dinámicos deben proteger el backslash
4. Las constantes no definidas referenciadas con un backslash producen un error fatal
5. Imposible reemplazar constantes especiales como `null`, `true` o `false`

### Si no utilizo espacios de nombres, ¿debo preocuparme por ellos?

No, los espacios de nombres no afectan el código existente, de una manera u otra, ni el código que se producirá y que no utiliza espacios de nombres. Puede escribir esto si lo desea:

Ejemplo #1 Acceso a una clase global desde fuera de un espacio de nombres

    <?php
    $a = new \stdClass;
    print $a::class;

Es una funcionalidad equivalente a:

Ejemplo #2 Acceder a clases globales fuera de un espacio de nombres

    <?php
    $a = new stdClass;
    print $a::class;

### ¿Cómo utilizar una clase global o interna desde un espacio de nombres?

Ejemplo #3 Acceso a clases internas desde un espacio de nombres

    <?php
    namespace foo;
    $a = new \stdClass;
    print $a::class . "\n";

    function test(?\ArrayObject $parameter_type_example = null) {}

    $a = \FilesystemIterator::CURRENT_AS_FILEINFO;
    print $a . "\n";

    // extensión de una clase interna o global
    class MyException extends \Exception {}
    print MyException::class . "\n";

### ¿Cómo utilizar las clases de espacios de nombres, las funciones o las constantes en su propio espacio?

Ejemplo #4 Acceso a clases, funciones y constantes internas en un espacio de nombres

    <?php
    namespace foo;

    class MaClasse {}

    // uso de una clase en el espacio de nombres actual, como tipo de parámetro
    function test(?MaClasse $parameter_type_example = null) {}

    // otra manera de usar una clase en el espacio de nombres actual como tipo de parámetro
    function test2(?\foo\MaClasse $parameter_type_example = null) {}

    // extensión de una clase en el espacio de nombres actual
    class Extended extends MaClasse {}
    print Extended::class . "\n";

    // acceso a una función global
    $a = \strlen("test");
    print $a . "\n";

    // acceso a una constante global
    $b = \INI_ALL;
    print $b . "\n";

### ¿Cómo se resuelve un nombre como `\mon\nom` o `\nom`?

Los nombres que comienzan con `\` siempre se resuelven como son, por lo que `\mon\nom` es en realidad `mon\nom`, y `\Exception` es `Exception`.

Ejemplo #5 Nombres de espacios absolutos

    <?php
    namespace foo;
    $a = new \mon\nom(); // instancia la clase "mon\nom"
    echo \strlen('hi'); // llama a la función "strlen"
    $a = \INI_ALL; // $a recibe el valor de la constante "INI_ALL"

### ¿Cómo se resuelve un nombre como `mon\nom`?

Los nombres que contienen un backslash pero no comienzan con un backslash, como `mon\nom` pueden resolverse de dos maneras diferentes.

Si ha habido una instrucción de importación que hace un alias de `mon`, entonces el alias importado se aplica en lugar de `mon`, y el espacio de nombres se convierte en `mon\nom`.

De lo contrario, el espacio de nombres actual se agrega antes del camino de la clase `mon\nom`.

Ejemplo #6 Nombres calificados

    <?php
    namespace foo;
    use blah\blah as foo;

    $a = new mon\nom(); // instancia la clase "foo\mon\nom"
    foo\bar::name(); // llama al método estático "name" en la clase "blah\blah\bar"
    mon\bar(); // llama a la función "foo\mon\bar"
    $a = mon\BAR; // asigna a $a el valor de la constante "foo\mon\BAR"

### ¿Cómo se resuelve un nombre de clase sin calificación, como `nom`?

Los nombres de clases que no contienen backslash como `nom` pueden resolverse de dos maneras diferentes.

Si hay una instrucción de importación que define un alias para `nom`, entonces se aplica el alias.

De lo contrario, se utiliza el espacio de nombres actual y se prefiere a `nom`.

Ejemplo #7 Clases sin calificación

    <?php
    namespace foo;
    use blah\blah as foo;

    $a = new nom(); // instancia la clase "foo\nom"
    foo::nom(); // llama al método estático "nom" en la clase "blah\blah"

### ¿Cómo se resuelve una función sin calificación o una constante de nombre `nom`?

Las funciones y constantes que no tienen backslash en su nombre como `nom` se resuelven de dos maneras diferentes:

Primero, se prefiere el espacio de nombres actual a `nom`.

Luego, si la constante o función `nom` no existe en el espacio de nombres actual, se utiliza la versión global de la constante o la función `nom`.

Ejemplo #8 Funciones y constantes sin espacio de nombres

    <?php
    namespace foo;
    use blah\blah as foo;

    const FOO = 1;

    function mon() {
        print __FUNCTION__ . "\n";
    }
    function foo() {
        print __FUNCTION__ . "\n";
    }
    function sort(&$a)
    {
        \sort($a); // Llamada a la función global "sort"
        $a = array_flip($a);
        return $a;
    }

    mon(); // llama "foo\mon"
    print strlen('hi') . "\n"; // llama a la función global "strlen" ya que "foo\strlen" no existe
    $arr = array(1,3,2);
    $b = sort($arr); // llama a la función "foo\sort"
    var_dump($b);
    foo(); // llama a la función "foo\foo": la importación no se aplica

    $a = FOO; // asigna a $a el valor de la constante "foo\FOO": la importación no se aplica
    print $a;
    $b = INI_ALL; // asigna a $b el valor de la constante "INI_ALL"
    print $b;

### Los nombres importados no deben entrar en conflicto con las clases definidas en el mismo archivo

La siguiente combinación de scripts es válida:

file1.php

    <?php
    namespace mes\trucs;
    class MaClasse {}

another.php

    <?php
    namespace another;
    class untruc {}

file2.php

    <?php
    namespace mes\trucs;
    include 'file1.php';
    include 'another.php';

    use another\untruc as MaClasse;
    $a = new MaClasse; // instancia la clase "untruc" del espacio de nombres another

No hay conflicto de nombres, incluso si la clase `MaClasse` existe en el espacio de nombres `mes\trucs`, ya que la definición de MaClasse está en un archivo separado. Sin embargo, el siguiente ejemplo produce un error fatal debido a un conflicto de nombres, ya que MaClasse se define en el mismo archivo que la instrucción use.

    <?php
    namespace mes\trucs;
    use another\untruc as MaClasse;
    class MaClasse {} // error fatal: MaClasse está en conflicto con la instrucción de importación
    $a = new MaClasse;

### Los espacios de nombres anidados están prohibidos

PHP no permite anidar espacios de nombres.

    <?php
    namespace mes\trucs {
        namespace nested {
            class foo {}
        }
    }

Sin embargo, es fácil simular espacios de nombres anidados, como esto:

    <?php
    namespace mes\trucs\nested {
        class foo {}
    }

### Los nombres de espacios de nombres dinámicos deben proteger el backslash

Es muy importante darse cuenta de que, como los backslash se utilizan como caracteres de escape en las cadenas, siempre deben duplicarse para poder usarlos en una cadena. De lo contrario, existe el riesgo de uso inesperado:

Ejemplo #9 Peligros de usar espacios de nombres en una cadena

    <?php
    $a = "dangereux\nom"; // \n es una nueva línea en una cadena!
    $obj = new $a;

    $a = 'pas\vraiment\dangereux'; // ningún problema aquí
    $obj = new $a;

En una cadena de comillas dobles, la secuencia de escape es mucho más segura de usar, pero aún se recomienda proteger siempre los backslashs en una cadena que contiene un espacio de nombres.

### Constantes no definidas referenciadas con un backslash producen un error fatal

Cualquier constante no definida que no tenga calificador como `FOO` producirá una advertencia: PHP asumía que `FOO` era el valor de la constante. Cualquier constante, calificada parcialmente o totalmente, que contenga un backslash, producirá un error fatal si no está definida.

Ejemplo #10 Constantes no definidas

    <?php
    namespace bar;
    $a = FOO; // produce una advertencia: constante no definida "FOO", que toma el valor de "FOO";
    $a = \FOO; // error fatal, constante de espacio de nombres no definida FOO
    $a = Bar\FOO; // error fatal, constante de espacio de nombres no definida bar\Bar\FOO
    $a = \Bar\FOO; // error fatal, constante de espacio de nombres no definida Bar\FOO

### Imposible reemplazar constantes especiales como `null`, `true` o `false`

Cualquier intento en un espacio de nombres de reemplazar las constantes nativas o especiales, produce un error fatal.

Ejemplo #11 Constantes que no pueden ser redefinidas

    <?php
    namespace bar;
    const NULL = 0; // error fatal;
    const true = 'stupid'; // aún otro error fatal;
    // etc.

# Enumeraciones

## Tabla de contenidos

- Visión general de las enumeraciones
- Enumeraciones básicas
- Enumeraciones respaldadas
- Métodos de enumeración
- Métodos estáticos de enumeración
- Constantes de enumeración
- Traits
- Valores de enumeración en expresiones constantes
- Diferencias con los objetos
- Listado de valores
- Serialización
- Por qué las enumeraciones no son extensibles
- Ejemplos

## Visión general de las enumeraciones

(PHP 8 >= 8.1.0)

Las enumeraciones, o "Enums", permiten a un desarrollador definir un tipo personalizado que se limita a uno de un número discreto de valores posibles. Esto puede ser especialmente útil al definir un modelo de dominio, ya que permite "hacer que los estados no válidos sean irrepresentables".

Las enumeraciones aparecen en muchos lenguajes con una variedad de características diferentes. En PHP, las enumeraciones son un tipo especial de objeto. La enumeración en sí es una clase, y sus posibles casos son todos objetos de instancia única de esa clase. Eso significa que los casos de enumeración son objetos válidos y pueden usarse dondequiera que se pueda usar un objeto, incluyendo comprobaciones de tipo.

El ejemplo más popular de enumeraciones es el tipo booleano integrado, que es un tipo enumerado con valores legales `true` y `false`. Las enumeraciones permiten a los desarrolladores definir sus propias enumeraciones arbitrariamente robustas.

## Enumeraciones básicas

Las enumeraciones son similares a las clases y comparten los mismos espacios de nombres que las clases, interfaces y traits. También son autocargables de la misma manera. Una enumeración define un nuevo tipo, que tiene un número fijo y limitado de valores legales posibles.

    <?php

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

Esta declaración crea un nuevo tipo enumerado llamado `Suit`, que tiene cuatro y solo cuatro valores legales: `Suit::Hearts`, `Suit::Diamonds`, `Suit::Clubs`, y `Suit::Spades`. Las variables pueden ser asignadas a uno de esos valores legales. Una función puede ser comprobada de tipo contra un tipo enumerado, en cuyo caso solo se pueden pasar valores de ese tipo.

    <?php

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    function pick_a_card(Suit $suit)
    {
        var_dump($suit);
    }

    $val = Suit::Diamonds;

    // OK
    pick_a_card($val);

    // OK
    pick_a_card(Suit::Clubs);

    // TypeError: pick_a_card(): Argument #1 ($suit) must be of type Suit, string given
    pick_a_card('Spades');

Una enumeración puede tener cero o más definiciones de `case`, sin máximo. Una enumeración sin casos es sintácticamente válida, aunque bastante inútil.

Para los casos de enumeración, se aplican las mismas reglas sintácticas que a cualquier etiqueta en PHP, ver Constantes.

Por omisión, los casos no están respaldados intrínsecamente por un valor escalar. Es decir, `Suit::Hearts` no es igual a `"0"`. En su lugar, cada caso está respaldado por un objeto singleton de ese nombre. Eso significa que:

    <?php

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    $a = Suit::Spades;
    $b = Suit::Spades;

    if ($a === $b) {
        print "Los palos coinciden usando ===\n";
    }

    if ($a instanceof Suit) {
        print "Los palos coinciden usando instanceof\n";
    }

    if ($a !== 'Spades') {
        print "El palo no coincide con la cadena\n";
    }

También significa que los valores de enumeración nunca son `<` o `>` entre sí, ya que esas comparaciones no tienen significado en los objetos. Esas comparaciones siempre devolverán `false` al trabajar con valores de enumeración.

Este tipo de caso, sin datos relacionados, se denomina "Caso Puro". Una enumeración que contiene solo Casos Puros se denomina Enumeración Pura.

Todos los Casos Puros se implementan como instancias de su tipo de enumeración. El tipo de enumeración está representado internamente como una clase.

Todos los Casos tienen una propiedad de solo lectura, `name`, que es el nombre sensible a mayúsculas y minúsculas del caso en sí.

    <?php

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    print Suit::Spades->name;
    // imprime "Spades"

También es posible usar las funciones defined() y constant() para verificar la existencia o leer un caso de enumeración si el nombre se obtiene dinámicamente. Sin embargo, esto se desaconseja ya que el uso de Enumeraciones respaldadas debería funcionar para la mayoría de los casos de uso.

## Enumeraciones respaldadas

Por omisión, los Casos Enumerados no tienen equivalente escalar. Son simplemente objetos singleton. Sin embargo, hay amplios casos en los que un Caso Enumerado necesita poder hacer un viaje de ida y vuelta a una base de datos o un almacén de datos similar, por lo que tener un equivalente escalar integrado (y por lo tanto trivialmente serializable) definido intrínsecamente es útil.

Para definir un equivalente escalar para una Enumeración, la sintaxis es la siguiente:

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

Un caso que tiene un equivalente escalar se denomina Caso Respaldado, ya que está "respaldado" por un valor más simple. Una enumeración que contiene todos los Casos Respaldados se denomina "Enumeración Respaldada". Una Enumeración Respaldada solo puede contener Casos Respaldados. Una Enumeración Pura solo puede contener Casos Puros.

Una Enumeración Respaldada puede estar respaldada por tipos de `int` o `string`, y una enumeración dada admite solo un tipo a la vez (es decir, no hay unión de `int|string`). Si una enumeración está marcada como que tiene un equivalente escalar, entonces todos los casos deben tener un equivalente escalar único definido explícitamente. No hay equivalentes escalares generados automáticamente (por ejemplo, enteros secuenciales). Los casos respaldados deben ser únicos; dos casos de enumeración respaldados no pueden tener el mismo equivalente escalar. Sin embargo, una constante puede referirse a un caso, creando efectivamente un alias. Ver Constantes de enumeración.

Los valores equivalentes pueden ser una expresión escalar constante. Antes de PHP 8.2.0, los valores equivalentes debían ser literales o expresiones literales. Esto significa que las constantes y expresiones constantes no estaban admitidas. Es decir, `1 + 1` estaba permitido, pero `1 + SOME_CONST` no.

Los Casos Respaldados tienen una propiedad adicional de solo lectura, `value`, que es el valor especificado en la definición.

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    print Suit::Clubs->value;
    // Imprime "C"

Para hacer cumplir la propiedad `value` como de solo lectura, una variable no puede ser asignada como referencia a ella. Es decir, lo siguiente genera un error:

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    $suit = Suit::Clubs;
    $ref = &$suit->value;
    // Error fatal: No se puede modificar indirectamente la propiedad de solo lectura Suit::$value

Las enumeraciones respaldadas implementan una interfaz interna BackedEnum, que expone dos métodos adicionales:

- `from(int|string): self` tomará un escalar y devolverá el Caso de Enumeración correspondiente. Si no se encuentra ninguno, lanzará un ValueError. Esto es principalmente útil en casos donde el escalar de entrada es confiable y un valor de enumeración faltante debería ser considerado un error que detiene la aplicación.
- `tryFrom(int|string): ?self` tomará un escalar y devolverá el Caso de Enumeración correspondiente. Si no se encuentra ninguno, devolverá `null`. Esto es principalmente útil en casos donde el escalar de entrada no es confiable y el llamador quiere implementar su propia lógica de manejo de errores o valores por omisión.

Los métodos `from()` y `tryFrom()` siguen las reglas estándar de tipado débil/fuerte. En modo de tipado débil, pasar un entero o string es admisible y el sistema coercionará el valor en consecuencia. Pasar un float también funcionará y será coercionado. En modo de tipado estricto, pasar un entero a `from()` en una enumeración respaldada por string (o viceversa) resultará en un TypeError, al igual que un float en todas las circunstancias. Todos los demás tipos de parámetros lanzarán un TypeError en ambos modos.

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    function get_stuff_from_database($id) {
        return [
            'suit' => 'S',
        ];
    }

    $record = get_stuff_from_database(42);
    print $record['suit'] . "\n";

    $suit = Suit::tryFrom('A') ?? Suit::Spades;
    // Datos no válidos devuelven null, por lo que se usa Suit::Spades en su lugar.
    print $suit->value . "\n";

    $suit =  Suit::from('X');
    // Datos no válidos lanzan un ValueError: "X" is not a valid backing scalar value for enum Suit
    print $suit->value . "\n";

Definir manualmente un método `from()` o `tryFrom()` en una Enumeración Respaldada resultará en un error fatal.

## Métodos de enumeración

Las enumeraciones (tanto Enumeraciones Puras como Enumeraciones Respaldadas) pueden contener métodos y pueden implementar interfaces. Si una enumeración implementa una interfaz, entonces cualquier comprobación de tipo para esa interfaz también aceptará todos los casos de esa enumeración.

    <?php

    interface Colorful
    {
        public function color(): string;
    }

    enum Suit implements Colorful
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;

        // Cumple con el contrato de la interfaz.
        public function color(): string
        {
            return match ($this) {
                Suit::Hearts, Suit::Diamonds => 'Red',
                Suit::Clubs, Suit::Spades => 'Black',
            };
        }

        // No forma parte de una interfaz; eso está bien.
        public function shape(): string
        {
            return "Rectangle";
        }
    }

    function paint(Colorful $c)
    {
       print $c->color() . "\n";
    }

    paint(Suit::Clubs);  // Funciona

    print Suit::Diamonds->shape(); // imprime "Rectangle"

En este ejemplo, las cuatro instancias de `Suit` tienen dos métodos, `color()` y `shape()`. En cuanto al código de llamada y las comprobaciones de tipo, se comportan exactamente igual que cualquier otra instancia de objeto.

En una Enumeración Respaldada, la declaración de interfaz va después de la declaración del tipo de respaldo.

    <?php

    interface Colorful
    {
        public function color(): string;
    }

    enum Suit: string implements Colorful
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';

        // Cumple con el contrato de la interfaz.
        public function color(): string
        {
            return match ($this) {
                Suit::Hearts, Suit::Diamonds => 'Red',
                Suit::Clubs, Suit::Spades => 'Black',
            };
        }
    }

Dentro de un método, la variable `$this` está definida y se refiere a la instancia del Caso.

Los métodos pueden ser arbitrariamente complejos, pero en la práctica suelen devolver un valor estático o match en `$this` para proporcionar diferentes resultados para diferentes casos.

Tenga en cuenta que en este caso sería una mejor práctica de modelado de datos también definir un tipo de enumeración `SuitColor` con valores Red y Black y devolver eso en su lugar. Sin embargo, eso complicaría este ejemplo.

La jerarquía anterior es lógicamente similar a la siguiente estructura de clase (aunque este no es el código real que se ejecuta):

    <?php

    interface Colorful
    {
        public function color(): string;
    }

    final class Suit implements UnitEnum, Colorful
    {
        public const Hearts = new self('Hearts');
        public const Diamonds = new self('Diamonds');
        public const Clubs = new self('Clubs');
        public const Spades = new self('Spades');

        private function __construct(public readonly string $name) {}

        public function color(): string
        {
            return match ($this) {
                Suit::Hearts, Suit::Diamonds => 'Red',
                Suit::Clubs, Suit::Spades => 'Black',
            };
        }

        public function shape(): string
        {
            return "Rectangle";
        }

        public static function cases(): array
        {
            // Método ilegal, porque definir manualmente un método cases() en una Enumeración no está permitido.
            // Ver también la sección "Listado de valores".
        }
    }

Los métodos pueden ser públicos, privados o protegidos, aunque en la práctica privado y protegido son equivalentes ya que la herencia no está permitida.

## Métodos estáticos de enumeración

Las enumeraciones también pueden tener métodos estáticos. El uso de métodos estáticos en la enumeración en sí es principalmente para constructores alternativos. Por ejemplo:

    <?php

    enum Size
    {
        case Small;
        case Medium;
        case Large;

        public static function fromLength(int $cm): self
        {
            return match (true) {
                $cm < 50 => self::Small,
                $cm < 100 => self::Medium,
                default => self::Large,
            };
        }
    }

    var_dump(Size::fromLength(50));

Los métodos estáticos pueden ser públicos, privados o protegidos, aunque en la práctica privado y protegido son equivalentes ya que la herencia no está permitida.

## Constantes de enumeración

Las enumeraciones pueden incluir constantes, que pueden ser públicas, privadas o protegidas, aunque en la práctica privada y protegida son equivalentes ya que la herencia no está permitida.

Una constante de enumeración puede referirse a un caso de enumeración:

    <?php

    enum Size
    {
        case Small;
        case Medium;
        case Large;

        public const Huge = self::Large;
    }

    var_dump(Size::Huge);

## Traits

Las enumeraciones pueden aprovechar los traits, que se comportarán igual que en las clases. La salvedad es que los traits `use`ados en una enumeración no deben contener propiedades. Solo pueden incluir métodos, métodos estáticos y constantes. Un trait con propiedades resultará en un error fatal.

    <?php

    interface Colorful
    {
        public function color(): string;
    }

    trait Rectangle
    {
        public function shape(): string
        {
            return "Rectangle";
        }
    }

    enum Suit implements Colorful
    {
        use Rectangle;

        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;

        public function color(): string
        {
            return match ($this) {
                Suit::Hearts, Suit::Diamonds => 'Red',
                Suit::Clubs, Suit::Spades => 'Black',
            };
        }
    }

    $suit = Suit::Spades;
    var_dump($suit->color());
    var_dump($suit->shape());

## Valores de enumeración en expresiones constantes

Debido a que los casos están representados como constantes en la enumeración en sí, pueden usarse como valores estáticos en la mayoría de las expresiones constantes: valores por omisión de propiedades, valores por omisión de variables estáticas, valores por omisión de parámetros, valores de constantes globales y de clase. No pueden usarse en otros valores de casos de enumeración, pero las constantes normales pueden referirse a un caso de enumeración.

Sin embargo, las llamadas implícitas a métodos mágicos como ArrayAccess en enumeraciones no están permitidas en definiciones estáticas o constantes, ya que no podemos garantizar absolutamente que el valor resultante sea determinista o que la invocación del método esté libre de efectos secundarios. Las llamadas a funciones, llamadas a métodos y el acceso a propiedades continúan siendo operaciones no válidas en expresiones constantes.

    <?php

    // Esta es una definición de Enumeración completamente legal.
    enum Direction implements ArrayAccess
    {
        case Up;
        case Down;

        public function offsetExists($offset): bool
        {
            return false;
        }

        public function offsetGet($offset): mixed
        {
            return null;
        }

        public function offsetSet($offset, $value): void
        {
            throw new Exception();
        }

        public function offsetUnset($offset): void
        {
            throw new Exception();
        }
    }

    class Foo
    {
        // Esto está permitido.
        const DOWN = Direction::Down;

        // Esto no está permitido, ya que puede no ser determinista.
        const UP = Direction::Up['short'];
        // Error fatal: No se puede usar [] en enumeraciones en expresión constante
    }

    // Esto es completamente legal, porque no es una expresión constante.
    $x = Direction::Up['short'];
    var_dump("\$x is " . var_export($x, true));

    $foo = new Foo();

## Diferencias con los objetos

Aunque las enumeraciones están construidas sobre clases y objetos, no admiten toda la funcionalidad relacionada con objetos. En particular, los casos de enumeración tienen prohibido tener estado.

- Los constructores y destructores están prohibidos.
- La herencia no está admitida. Las enumeraciones no pueden extender ni ser extendidas.
- No se permiten propiedades estáticas u objetuales.
- Clonar un caso de enumeración no está admitido, ya que los casos deben ser instancias singleton.
- Métodos mágicos, excepto los listados a continuación, no están permitidos.
- Las enumeraciones siempre deben declararse antes de ser usadas.

La siguiente funcionalidad de objetos está disponible y se comporta igual que en cualquier otro objeto:

- Métodos públicos, privados y protegidos.
- Métodos estáticos públicos, privados y protegidos.
- Constantes públicas, privadas y protegidas.
- Las enumeraciones pueden implementar cualquier número de interfaces.
- Las enumeraciones y los casos pueden tener atributos adjuntos a ellos. El filtro de destino `TARGET_CLASS` incluye las enumeraciones en sí. El filtro de destino `TARGET_CLASS_CONST` incluye los Casos de Enumeración.
- __call, __callStatic, y __invoke métodos mágicos
- Las constantes `__CLASS__` y `__FUNCTION__` se comportan normalmente

La constante mágica `::class` en un tipo de enumeración se evalúa al nombre del tipo incluyendo cualquier espacio de nombres, exactamente igual que un objeto. La constante mágica `::class` en una instancia de Caso también se evalúa al tipo de enumeración, ya que es una instancia de ese tipo.

Además, los casos de enumeración no pueden ser instanciados directamente con `new`, ni con ReflectionClass::newInstanceWithoutConstructor() en reflexión. Ambos resultarán en un error.

    <?php

    $clovers = new Suit();
    // Error: No se puede instanciar la enumeración Suit

    $horseshoes = (new ReflectionClass(Suit::class))->newInstanceWithoutConstructor()
    // Error: No se puede instanciar la enumeración Suit

## Listado de valores

Tanto las Enumeraciones Puras como las Enumeraciones Respaldadas implementan una interfaz interna llamada UnitEnum. `UnitEnum` incluye un método estático `cases()`. `cases()` devuelve un array compacto de todos los Casos definidos en el orden de declaración.

    <?php

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    var_dump(Suit::cases());

    enum SuitBacked: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    var_dump(SuitBacked::cases());

Definir manualmente un método `cases()` en una Enumeración resultará en un error fatal.

## Serialización

Las enumeraciones se serializan de manera diferente a los objetos. Específicamente, tienen un nuevo código de serialización, `"E"`, que especifica el nombre del caso de enumeración. La rutina de deserialización puede entonces usar eso para establecer una variable al valor singleton existente. Eso asegura que:

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    Suit::Hearts === unserialize(serialize(Suit::Hearts));

    print serialize(Suit::Hearts);
    // E:11:"Suit:Hearts";

Al deserializar, si no se puede encontrar una enumeración y un caso para coincidir con un valor serializado, se emitirá una advertencia y se devolverá `false`.

La opción `allowed_classes` de unserialize() no afecta a las Enumeraciones.

Si una Enumeración Pura se serializa a JSON, se lanzará un error. Si una Enumeración Respaldada se serializa a JSON, estará representada solo por su valor escalar, en el tipo apropiado. El comportamiento de ambas puede ser sobrescrito implementando JsonSerializable.

Para print_r(), la salida de un caso de enumeración es ligeramente diferente de los objetos para minimizar la confusión.

    <?php

    enum Foo
    {
        case Bar;
    }

    enum Baz: int
    {
        case Beep = 5;
    }

    print_r(Foo::Bar);
    print_r(Baz::Beep);

    /* Produce

    Foo Enum (
        [name] => Bar
    )
    Baz Enum:int {
        [name] => Beep
        [value] => 5
    }
    */

## Por qué las enumeraciones no son extensibles

Las clases tienen contratos en sus métodos:

    <?php

    class A {}
    class B extends A {}

    function foo(A $a) {}

    function bar(B $b)
    {
        foo($b);
    }

Este código es seguro en cuanto a tipos, ya que B sigue el contrato de A, y a través de la magia de la co/contravariancia, cualquier expectativa que uno pueda tener de los métodos será preservada, exceptuando las excepciones.

Las enumeraciones tienen contratos en sus casos, no en sus métodos:

    <?php

    enum ErrorCode
    {
        case SOMETHING_BROKE;
    }

    function quux(ErrorCode $errorCode)
    {
        // Cuando se escribe, este código parece cubrir todos los casos
        match ($errorCode) {
            ErrorCode::SOMETHING_BROKE => true,
        };
    }

La sentencia match en la función `quux` puede ser analizada estáticamente para cubrir todos los casos en ErrorCode.

Pero imagina que estuviera permitido extender enumeraciones:

    <?php

    // Código de experimento mental donde las enumeraciones no son finales.
    // Nota: esto no funcionará realmente en PHP.
    enum MoreErrorCode extends ErrorCode
    {
        case PEBKAC;
    }

    function fot(MoreErrorCode $errorCode)
    {
        quux($errorCode);
    }

    fot(MoreErrorCode::PEBKAC);

Bajo las reglas normales de herencia, una clase que extiende a otra pasará la comprobación de tipo.

El problema sería que la sentencia match en `quux()` ya no cubriría todos los casos. Debido a que no sabe acerca de `MoreErrorCode::PEBKAC`, el match lanzará una excepción.

Debido a esto, las enumeraciones son finales y no pueden ser extendidas.

## Ejemplos

Ejemplo #1 Valores limitados básicos

    <?php

    enum SortOrder
    {
        case Asc;
        case Desc;
    }

    function query($fields, $filter, SortOrder $order = SortOrder::Asc)
    {
         /* ... */
    }

La función `query()` ahora puede proceder con la seguridad de que `$order` está garantizado que sea `SortOrder::Asc` o `SortOrder::Desc`. Cualquier otro valor habría resultado en un TypeError, por lo que no se necesita ninguna comprobación o prueba de errores adicional.

Ejemplo #2 Valores exclusivos avanzados

    <?php

    enum UserStatus: string
    {
        case Pending = 'P';
        case Active = 'A';
        case Suspended = 'S';
        case CanceledByUser = 'C';

        public function label(): string
        {
            return match ($this) {
                self::Pending => 'Pending',
                self::Active => 'Active',
                self::Suspended => 'Suspended',
                self::CanceledByUser => 'Canceled by user',
            };
        }
    }

    $status = UserStatus::Suspended;
    var_dump($status->label());

En este ejemplo, el estado de un usuario puede ser uno de, y exclusivamente, `UserStatus::Pending`, `UserStatus::Active`, `UserStatus::Suspended`, o `UserStatus::CanceledByUser`. Una función puede tipar un parámetro contra `UserStatus` y luego solo aceptar esos cuatro valores, punto.

Los cuatro valores tienen un método `label()`, que devuelve un string legible por humanos. Ese string es independiente del string equivalente escalar de "nombre de máquina", que puede usarse en, por ejemplo, un campo de base de datos o un cuadro de selección HTML.

    <?php

    enum UserStatus: string
    {
        case Pending = 'P';
        case Active = 'A';
        case Suspended = 'S';
        case CanceledByUser = 'C';

        public function label(): string
        {
            return match ($this) {
                self::Pending => 'Pending',
                self::Active => 'Active',
                self::Suspended => 'Suspended',
                self::CanceledByUser => 'Canceled by user',
            };
        }
    }

    foreach (UserStatus::cases() as $case) {
        printf(
            "<option value=\"%s\">%s</option>\n",
            htmlentities($case->value),
            htmlentities($case->label())
        );
    }

# Errores

## Tabla de contenidos

- Lo básico
- Errores en PHP 7

## Introducción

Desarfortunadamente, no importa lo cuidadoso que uno sea escribiendo código; los errores son un hecho de la vida. PHP notificará errores, advertencias y avisos para muchos problemas comunes de codificación y de tiempo de ejecución, por lo que saber cómo detectar y manejar estos errores hará la depuración mucho más sencilla.

## Lo básico

PHP notifica errores en respuesta a varias condiciones de error internas. Estas se pueden utilizar para señalar varias condiciones diferentes, mostrándose y/o registrándose si fuera necesario.

Cada error que genera PHP incluye un tipo. Existe una lista de dichos tipos de error, junto con una breve descripción de su comportamiento y sus posibles causas.

### Manejo de errores con PHP

Si no se establece un manejador de errores, PHP manejará cada error que ocurra según su configuración. Los errores que se notifican y los que se ignoran se controla mediante la directiva `error_reporting` de php.ini, o durante la ejecución llamando a error_reporting(). Sin embargo, se recomienda encarecidamente establecer la directiva de configuración, ya que algunos errores pueden ocurrir antes de comenzar la ejecución de un script.

En un entorno de desarrollo debería establecerse siempre `error_reporting` a `E_ALL`, debido a que es necesario reconocer y corregir los problemas generados por PHP. En producción, se podría establecer esta directiva a un nivel de menor verbosidad como `E_ALL & ~E_NOTICE & ~E_DEPRECATED`, aunque en muchos casos `E_ALL` también es apropiado, ya que puede proporcionar advertencias precoces de problemas potenciales.

Lo que PHP hace con estos errores depende de dos directivas más de php.ini. `display_errors` controla si el error es mostrado como parte de la salida del script. Esta debería estar siempre deshabilitada en un entorno de producción, ya que puede incluir información confidencial tal como contraseñas de bases de datos, aunque a menudo es útil habilitarla en desarrollo debido a que asegura la notificación inmediata de problemas.

Además de mostrar errores, PHP puede registrarlos cuando la directiva `log_errors` está habilitada. Esta registrará cualquier error en el fichero o registro del sistema definido por `error_log`. Esta directiva puede ser extremadamente útil en un entorno de producción debido a que se pueden registrar los errores que ocurran y generar informes basados en ellos.

### Manejadores de errores de usuario

Si el manejo de errores predeterminado de PHP es inadecuado, también se pueden manejar muchos tipos de error con un manejador de errores propio mediante set_error_handler(). Mientras que algunos tipos de error no se pueden manejar de esta forma, aquellos que sí se pueden lo hacen de la manera en que su script vea apropiada: por ejemplo, se puede emplear para mostrar al usuario una página de error personalizada y luego notificar más directamente mediante un registro, tal como el envío de un correo electrónico.

## Errores en PHP 7

PHP 7 cambia la mayoría de los errores notificados por PHP. En lugar de notificar errores a través del mecanismo de notificación de errores tradicional de PHP 5, la mayoría de los errores ahora son notificados lanzando excepciones Error.

Al igual que las excepciones normales, las excepciones Error se propagarán hasta alcanzar el primer bloque `catch` coincidente. Si no hay bloques coincidentes, será invocado cualquier manejador de excepciones predeterminado instalado con set_exception_handler(), y si no hubiera ningún manejador de excepciones predeterminado, la excepción será convertida en un error fatal y será manejada como un error tradicional.

Debido a que la jerarquía de Error no hereda de Exception, el código que emplee bloques `catch (Exception $e) { ... }` para manejar excepciones no capturadas en PHP 5 encontrará que estos Errores no son capturados por dichos bloques. Se requiere, por tanto, un bloque `catch (Error $e) { ... }` o un manejador set_exception_handler().

### Jerarquía de Error

- Throwable
  - Error
    - ArithmeticError
      - DivisionByZeroError
    - AssertionError
    - CompileError
      - ParseError
    - TypeError
      - ArgumentCountError
    - ValueError
    - UnhandledMatchError
    - FiberError
    - RequestParseBodyException
  - Exception
    - ...

# Las excepciones

## Tabla de contenidos

- Extender las Excepciones

> Nota: Vea también la clase Exception

PHP tiene un manejo de excepciones similar al que ofrecen otros lenguajes de programación. Una excepción puede ser lanzada ("`throw`") y capturada ("`catch`") en PHP. El código deberá estar rodeado de un bloque `try` para facilitar la captura de una excepción potencial. Cada `try` debe tener al menos un bloque `catch` o `finally` correspondiente.

Si una excepción es lanzada y el ámbito actual de la función no tiene un bloque `catch`, la excepción "subirá" la pila de llamadas de la función llamadora hasta encontrar un bloque `catch` correspondiente. Todos los bloques `finally` encontrados serán ejecutados. Si la pila de llamadas se desenrolla hasta el ámbito global sin encontrar un bloque `catch` correspondiente, el programa será terminado con un error fatal a menos que se haya definido un manejador global de excepciones.

El objeto lanzado debe ser una `instanceof` Throwable. Intentar lanzar un objeto que no lo es resultará en un error fatal emitido por PHP.

A partir de PHP 8.0.0, la palabra clave `throw` es una expresión y puede ser utilizada en cualquier contexto de expresiones. En versiones anteriores era una declaración que debía estar en su propia línea.

## `catch`

Un bloque `catch` define cómo reaccionar ante una excepción que ha sido lanzada. Un bloque `catch` define uno o más tipos de excepciones o errores que puede manejar, y opcionalmente una variable en la que asignar la excepción. (Esta variable era requerida en versiones anteriores a PHP 8.0.0) El primer bloque `catch` que una excepción o error lanzado encuentre y que corresponda al tipo del objeto lanzado manejará el objeto.

Varios bloques `catch` pueden ser utilizados para atrapar diferentes clases de excepciones. La ejecución normal (cuando ninguna excepción es lanzada en el bloque `try`) continúa después del último bloque `catch` definido en la secuencia. Las excepciones pueden ser lanzadas (`throw`) o relanzadas en un bloque `catch`. De lo contrario, la ejecución continuará después del bloque `catch` que haya sido activado.

Cuando una excepción es lanzada, el código siguiente al tratamiento no será ejecutado y PHP intentará encontrar el primer bloque `catch` correspondiente. Si una excepción no es capturada, un error fatal de PHP será enviado con un mensaje "`Uncaught Exception ...`" indicando que la excepción no pudo ser capturada a menos que un manejador de excepciones sea definido con la función set_exception_handler().

A partir de PHP 7.1, un bloque `catch` puede especificar múltiples excepciones a través del carácter pipe (`|`). Esto es útil cuando diferentes excepciones de diferentes jerarquías de clases son tratadas de la misma manera.

A partir de PHP 8.0.0, el nombre de variable para la excepción capturada es opcional. Si no se especifica, el bloque `catch` será siempre ejecutado pero no tendrá acceso al objeto lanzado.

## `finally`

Un bloque `finally` también puede ser especificado después de bloques `catch`. El código dentro del bloque `finally` será siempre ejecutado después de los bloques `try` y `catch`, independientemente de si una excepción ha sido lanzada, antes de continuar con la ejecución normal.

Una interacción notable es entre un bloque `finally` y una declaración `return`. Si una declaración `return` es encontrada dentro de los bloques `try` o `catch`, el bloque `finally` será igualmente ejecutado. Además, la declaración `return` es evaluada cuando es encontrada, pero el resultado será retornado después de que el bloque `finally` sea ejecutado. Adicionalmente, si el bloque `finally` contiene también una declaración `return` el valor del bloque `finally` es retornado.

Otra interacción notable es entre una excepción lanzada en un bloque `try`, y una excepción lanzada en un bloque `finally`. Si una excepción es lanzada en ambos bloques, entonces, la excepción lanzada en el bloque `finally` será la que se propagará, y la excepción lanzada en el bloque `try` será utilizada como excepción previa.

## Manejador global de excepciones

Si una excepción es permitida para subir hasta el ámbito global, puede ser capturada por un manejador de excepciones global si ha sido definido. La función set_exception_handler() puede definir una función que será llamada en lugar de un bloque `catch` si ningún otro bloque es invocado. El efecto es esencialmente idéntico a envolver el programa entero en un bloque `try`-`catch` con esta función como `catch`.

## Notas

> Nota:

> Las funciones internas de PHP utilizan principalmente el Error reporting, solo las extensiones orientadas a objetos utilizan excepciones. Sin embargo, los errores pueden ser fácilmente convertidos en excepciones con ErrorException. Sin embargo, esta técnica solo funciona para errores no fatales.

> Ejemplo #1 Convertir el error reporting en excepciones

>     <?php
>     function exceptions_error_handler($severity, $message, $filename, $lineno) {
>         throw new ErrorException($message, 0, $severity, $filename, $lineno);
>     }

>     set_error_handler('exceptions_error_handler');

Sugerencia

La biblioteca estándar PHP (SPL) proporciona un buen número de excepciones adicionales.

## Ejemplos

Ejemplo #2 Lanzar una excepción

    <?php
    function inverse($x) {
        if (!$x) {
            throw new Exception('División por cero.');
        }
        return 1/$x;
    }

    try {
        echo inverse(5) . "\n";
        echo inverse(0) . "\n";
    } catch (Exception $e) {
        echo 'Excepción recibida: ',  $e->getMessage(), "\n";
    }

    // Continuar la ejecución
    echo "¡Hola mundo!\n";

El ejemplo anterior mostrará:

    0.2
    Excepción recibida: División por cero.
    ¡Hola mundo!

Ejemplo #3 Manejo de la excepción con un bloque `finally`

    <?php
    function inverse($x) {
        if (!$x) {
            throw new Exception('División por cero.');
        }
        return 1/$x;
    }

    try {
        echo inverse(5) . "\n";
    } catch (Exception $e) {
        echo 'Excepción recibida: ',  $e->getMessage(), "\n";
    } finally {
        echo "Primer fin.\n";
    }

    try {
        echo inverse(0) . "\n";
    } catch (Exception $e) {
        echo 'Excepción recibida: ',  $e->getMessage(), "\n";
    } finally {
        echo "Segundo fin.\n";
    }

    // Continuar la ejecución
    echo "¡Hola mundo!\n";

El ejemplo anterior mostrará:

    0.2
    Primer fin.
    Excepción recibida: División por cero.
    Segundo fin.
    ¡Hola mundo!

Ejemplo #4 Interacción entre el bloque `finally` y `return`

    <?php

    function test() {
        try {
            throw new Exception('foo');
        } catch (Exception $e) {
            return 'catch';
        } finally {
            return 'finally';
        }
    }

    echo test();

El ejemplo anterior mostrará:

    finally

Ejemplo #5 Herencia de una excepción

    <?php

    class MyException extends Exception { }

    class Test {
        public function testing() {
            try {
                try {
                    throw new MyException('foo!');
                } catch (MyException $e) {
                    // se relanza
                    throw $e;
                }
            } catch (Exception $e) {
                var_dump($e->getMessage());
            }
        }
    }

    $foo = new Test;
    $foo->testing();

El ejemplo anterior mostrará:

    string(4) "foo!"

Ejemplo #6 Manejo de excepciones de captura múltiple

    <?php

    class MyException extends Exception { }

    class MyOtherException extends Exception { }

    class Test {
        public function testing() {
            try {
                throw new MyException();
            } catch (MyException | MyOtherException $e) {
                var_dump(get_class($e));
            }
        }
    }

    $foo = new Test;
    $foo->testing();

El ejemplo anterior mostrará:

    string(11) "MyException"

Ejemplo #7 Omitir la variable capturada

Solo permitido en PHP 8.0.0 y versiones posteriores.

    <?php

    function test() {
        throw new SpecificException('Oopsie');
    }

    try {
        test();
    } catch (SpecificException) {
        print "Se lanzó una SpecificException, pero no nos importa con los detalles.";
    }

El ejemplo anterior mostrará:

    Se lanzó una SpecificException, pero no nos importa con los detalles.

Ejemplo #8 Throw como expresión

Solo permitido en PHP 8.0.0 y versiones posteriores.

    <?php

    class SpecificException extends Exception {}

    function test() {
        do_something_risky() or throw new Exception('No funcionó');
    }

    function do_something_risky() {
        return false; // Simular un fallo
    }

    try {
        test();
    } catch (Exception $e) {
        print $e->getMessage();
    }

El ejemplo anterior mostrará:

    No funcionó

Ejemplo #9 Excepción en try y en finally

    <?php

    try {
        try {
            throw new Exception(message: 'Third', previous: new Exception('Fourth'));
        } finally {
            throw new Exception(message: 'First', previous: new Exception('Second'));
        }
    } catch (Exception $e) {
        var_dump(
            $e->getMessage(),
            $e->getPrevious()->getMessage(),
            $e->getPrevious()->getPrevious()->getMessage(),
            $e->getPrevious()->getPrevious()->getPrevious()->getMessage(),
        );
    }

El ejemplo anterior mostrará:

    string(5) "First"
    string(6) "Second"
    string(5) "Third"
    string(6) "Fourth"

## Extender las Excepciones

Una clase de excepción definida por el usuario puede ser definida extendiendo la clase Exception integrada. Los miembros y las propiedades a continuación muestran lo que está accesible en la clase hija que deriva de la clase Exception integrada.

Ejemplo #1 La clase de excepción integrada

    <?php
    class Exception implements Throwable
    {
        protected $message = 'Unknown exception';   // Mensaje de excepción
        private   $string;                          // caché de __toString
        protected $code = 0;                        // código de excepción definido por el usuario
        protected $file;                            // nombre de archivo fuente de la excepción
        protected $line;                            // línea fuente de la excepción
        private   $trace;                           // rastro de la pila de ejecución
        private   $previous;                        // excepción previa si excepción anidada

        public function __construct($message = '', $code = 0, ?Throwable $previous = null);

        final private function __clone();           // Inhibe la duplicación de excepciones.

        final public  function getMessage();        // mensaje de la excepción
        final public  function getCode();           // código de la excepción
        final public  function getFile();           // nombre del archivo fuente
        final public  function getLine();           // línea fuente
        final public  function getTrace();          // array de la pila de ejecución
        final public  function getPrevious();       // la excepción previa
        final public  function getTraceAsString();  // rastro en forma de string

        // Puede ser redefinido
        public function __toString();               // string formateado para la visualización
    }

Si una clase extiende la clase Exception integrada y redefine el constructor, se recomienda fuertemente que también llame a parent::__construct() para asegurarse de que todos los datos disponibles han sido correctamente asignados. El método __toString() puede ser redefinido para proporcionar una salida personalizada cuando el objeto es presentado en forma de string.

> Nota:

> Las excepciones no pueden ser clonadas. Intentar clonar una Exception resultará en un error fatal `E_ERROR`.

Ejemplo #2 Extender la clase Exception

    <?php
    /**
     * Define una clase de excepción personalizada.
     */
    class MyException extends Exception
    {
        // Redefinir la excepción para que el mensaje no sea opcional.
        public function __construct($message, $code = 0, ?Throwable $previous = null) {
            // código

            // asegurarse de que todo está correctamente asignado
            parent::__construct($message, $code, $previous);
        }

        // Representación personalizada del objeto en forma de string.
        public function __toString() {
            return __CLASS__ . ": [{$this->code}]: {$this->message}\n";
        }

        public function customFunction() {
            echo "Una función personalizada para este tipo de excepción\n";
        }
    }

    /**
     * Crear una clase para probar la excepción
     */
    class TestException
    {
        public $var;

        const THROW_NONE    = 0;
        const THROW_CUSTOM  = 1;
        const THROW_DEFAULT = 2;

        function __construct($avalue = self::THROW_NONE) {

            switch ($avalue) {
                case self::THROW_CUSTOM:
                    // Lanzar una excepción personalizada
                    throw new MyException('1 no es un parámetro válido', 5);
                    break;

                case self::THROW_DEFAULT:
                    // Lanzar la por defecto.
                    throw new Exception('2 no está permitido como parámetro', 6);
                    break;

                default:
                    // Ninguna excepción, el objeto será creado.
                    $this->var = $avalue;
                    break;
            }
        }
    }

    echo "# Ejemplo 1\n";
    try {
        $o = new TestException(TestException::THROW_CUSTOM);
    } catch (MyException $e) {      // Será capturada
        echo "MyException capturada\n", $e;
        $e->customFunction();
    } catch (Exception $e) {        // Ignorado
        echo "Exception por defecto capturada\n", $e;
    }

    // Continuar la ejecución
    var_dump($o); // Null

    echo "\n\n# Ejemplo 2\n";
    try {
        $o = new TestException(TestException::THROW_DEFAULT);
    } catch (MyException $e) {      // No coincide con este tipo
        echo "MyException capturada\n", $e;
        $e->customFunction();
    } catch (Exception $e) {        // Será capturada
        echo "Exception por defecto capturada\n", $e;
    }

    // Continuar la ejecución
    var_dump($o); // Null

    echo "\n\n# Ejemplo 3\n";
    try {
        $o = new TestException(TestException::THROW_CUSTOM);
    } catch (Exception $e) {        // Será capturada
        echo "Exception por defecto capturada\n", $e;
    }

    // Continuar la ejecución
    var_dump($o); // Null

    echo "\n\n# Ejemplo 4\n";
    try {
        $o = new TestException();
    } catch (Exception $e) {        // Saltado, ninguna excepción
        echo "Exception por defecto capturada\n", $e;
    }

    // Continuar la ejecución
    var_dump($o); // TestException

# Fibers

### Descripción general de Fibers

(PHP 8 >= 8.1.0)

Los Fibers representan funciones de pila completa e interrumpibles. Los Fibers pueden suspenderse desde cualquier lugar en la pila de llamadas, pausando su ejecución dentro del Fiber hasta que se reanude más tarde.

Los Fibers pausan toda la pila de ejecución, por lo que el llamador directo de la función no necesita cambiar la forma en que invoca la función

La ejecución puede interrumpirse en cualquier lugar de la pila de llamadas utilizando Fiber::suspend() (es decir, la llamada a Fiber::suspend() puede estar en una función profundamente anidada o incluso no existir en absoluto)

A diferencia de los Generators sin pila, cada Fiber tiene su propia pila de llamadas, lo que permite que se pausen dentro de llamadas a funciones profundamente anidadas. Una función que declara un punto de interrupción (es decir, que llama a Fiber::suspend()) no necesita cambiar su tipo de retorno, a diferencia de una función que utiliza `yield` y debe devolver una instancia de Generator.

Los Fibers pueden suspenderse en cualquier llamada a función, incluidas aquellas realizadas desde la Máquina Virtual de PHP, como las funciones proporcionadas a array_map() o los métodos llamados por `foreach` en un objeto Iterator.

Una vez suspendido, la ejecución del Fiber puede reanudarse con cualquier valor utilizando Fiber::resume() o lanzando una excepción en el Fiber utilizando Fiber::throw(). El valor se devuelve (o la excepción se lanza) desde Fiber::suspend().

> Nota: Antes de PHP 8.4.0, no se permitía cambiar Fibers durante la ejecución de un destructor de objeto.

Ejemplo #1 Uso básico

    <?php
    $fiber = new Fiber(function (): void {
       $value = Fiber::suspend('fiber');
       echo "Valor utilizado para reanudar el Fiber: ", $value, PHP_EOL;
    });

    $value = $fiber->start();

    echo "Valor del Fiber al suspenderse: ", $value, PHP_EOL;

    $fiber->resume('test');
    ?>

El ejemplo anterior mostrará:

    Valor del Fiber al suspenderse: fiber
    Valor utilizado para reanudar el Fiber: test

# Generators

## Tabla de contenidos

- Resumen sobre los generadores
- Sintaxis de un Generador
- Comparación de los generadores con los objetos Iterator

## Resumen sobre los generadores

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Los generadores proporcionan una manera sencilla de implementar iteradores sin el costo ni la complejidad de desarrollar una clase que implemente la interfaz Iterator.

Un generador ofrece un medio conveniente para proporcionar datos a las bucles `foreach` sin tener que construir un array en memoria de antemano, lo cual podría llevar al programa a exceder un límite de memoria o requerir un tiempo de procesamiento considerable para generarlos. En su lugar, se puede utilizar una función generadora, que es idéntica a una función normal, excepto que en lugar de devolver una sola vez, un generador puede utilizar `yield` tantas veces como sea necesario, para proporcionar los valores a recorrer. Al igual que con los iteradores, el acceso aleatorio a los datos no es posible.

Un ejemplo sencillo de este mecanismo es la reimplementación de la función range() en forma de generador. La función estándar range() debe generar un array que contenga cada valor y devolverlo, lo cual puede llevar a arrays de gran tamaño: por ejemplo, la llamada al código range(0, 1000000) puede consumir significativamente más de 100 MB de memoria.

Como alternativa, se puede implementar un generador `xrange()`, que solo necesitará memoria para la creación de un objeto Iterator, y deberá mantener internamente el estado actual del generador, lo cual resulta en un consumo de memoria inferior a 1 KB.

Ejemplo #1 Implementación de la función range() en forma de generador

    <?php
    function xrange($start, $limit, $step = 1) {
        if ($start <= $limit) {
            if ($step <= 0) {
                throw new LogicException('El paso debe ser positivo');
            }

            for ($i = $start; $i <= $limit; $i += $step) {
                yield $i;
            }
        } else {
            if ($step >= 0) {
                throw new LogicException('El paso debe ser negativo');
            }

            for ($i = $start; $i >= $limit; $i += $step) {
                yield $i;
            }
        }
    }

    /*
     * Es de notar que las funciones range() y xrange() producen el
     * mismo resultado, a continuación.
     */

    echo 'Números impares de un solo dígito desde range():  ';
    foreach (range(1, 9, 2) as $number) {
        echo "$number ";
    }
    echo "\n";

    echo 'Números impares de un solo dígito desde xrange(): ';
    foreach (xrange(1, 9, 2) as $number) {
        echo "$number ";
    }

El ejemplo anterior mostrará:

    Números impares de un solo dígito desde range():  1 3 5 7 9
    Números impares de un solo dígito desde xrange(): 1 3 5 7 9

### Los objetos Generator

Cuando se llama a una función generadora, se devuelve un objeto de la clase interna Generator. Este objeto implementa la interfaz Iterator de la misma manera que lo haría un objeto iterador que solo avanza, y proporciona los métodos que pueden ser llamados para manipular el estado del generador, incluyendo el envío de valores y sus retornos.

## Sintaxis de un Generador

Una función generadora se asemeja a una función normal, excepto que en lugar de devolver un valor, un generador `yield` devuelve tantos valores como sea necesario. Todas las funciones que contienen `yield` son funciones generadoras.

Cuando se llama a una función generadora, devuelve un objeto que se puede recorrer. Cuando se recorre este objeto (por ejemplo, a través de una bucle `foreach`), PHP llamará a los métodos de iteración del objeto cada vez que necesite un valor, luego guardará el estado del generador cuando genere un valor, para que pueda ser reanudado cuando se requiera el siguiente valor.

Cuando no haya más valores para proporcionar, la función generadora puede simplemente devolver, y el código de llamada continuará como si un array no tuviera más valores.

> Nota:

> Un generador puede devolver valores, que pueden ser recuperados utilizando Generator::getReturn().

### La palabra clave yield

La palabra clave yield es el núcleo de una función generadora. En su forma más simple, una instrucción yield se asemeja a una instrucción return, excepto que en lugar de detener la ejecución de la función y devolver, yield proporciona un valor al código que recorre el generador, y pausa la ejecución de la función generadora.

Ejemplo #1 Un ejemplo sencillo de producción de valores

    <?php
    function gen_one_to_three() {
        for ($i = 1; $i <= 3; $i++) {
            // Note que $i se preserva entre cada producción de valor.
            yield $i;
        }
    }

    $generator = gen_one_to_three();
    foreach ($generator as $value) {
        echo "$value\n";
    }

El ejemplo anterior mostrará:

    1
    2
    3

> Nota:

> Internamente, se asociarán claves enteras secuenciales con los valores producidos, de la misma manera que para un array no asociativo.

#### Provisión de valores con claves

PHP también soporta arrays asociativos, y los generadores no son diferentes. Además de proporcionar valores simples, como hemos visto anteriormente, también se pueden proporcionar claves simultáneamente.

La sintaxis para producir un par clave/valor es similar a la utilizada para definir un array asociativo; así:

Ejemplo #2 Producción de un par clave/valor

    <?php
    /*
     * La entrada está compuesta de campos separados por un punto y coma,
     * y el primer campo es un ID para usar como clave.
     */

    $input = <<<'EOF'
    1;PHP;Le gustan los signos de dólar
    2;Python;Le gustan los espacios en blanco
    3;Ruby;Le gustan los bloques
    EOF;

    function input_parser($input) {
        foreach (explode("\n", $input) as $line) {
            $fields = explode(';', $line);
            $id = array_shift($fields);

            yield $id => $fields;
        }
    }

    foreach (input_parser($input) as $id => $fields) {
        echo "$id:\n";
        echo "    $fields[0]\n";
        echo "    $fields[1]\n";
    }

El ejemplo anterior mostrará:

    1:
        PHP
        Le gustan los signos de dólar
    2:
        Python
        Le gustan los espacios en blanco
    3:
        Ruby
        Le gustan los bloques

#### Producción de valores nulos

Yield puede ser llamado sin argumento para proporcionar un valor `null` con una clave automática.

Ejemplo #3 Producción de valores `null`

    <?php
    function gen_three_nulls() {
        foreach (range(1, 3) as $i) {
            yield;
        }
    }

    var_dump(iterator_to_array(gen_three_nulls()));

El ejemplo anterior mostrará:

    array(3) {
      [0]=>
      NULL
      [1]=>
      NULL
      [2]=>
      NULL
    }

#### Producción de valores por referencia

Las funciones generadoras pueden producir valores por referencia. Esto se hace de la misma manera que el retorno por referencia desde funciones : añadiendo un ET comercial (&) al nombre de la función.

Ejemplo #4 Producción de valores por referencia

    <?php
    function &gen_reference() {
        $value = 3;

        while ($value > 0) {
            yield $value;
        }
    }

    /*
     * Note que es posible cambiar $number en el bucle,
     * y, dado que el generador proporciona referencias, $value
     * en gen_reference() también cambia.
     */
    foreach (gen_reference() as &$number) {
        echo (--$number).'... ';
    }

El ejemplo anterior mostrará:

    2... 1... 0...

#### Delegación del generador vía yield from

La delegación del generador permite obtener los valores de otro generador, de un objeto Traversable, o de un array utilizando la palabra clave yield from. El generador externo obtendrá así todos los valores del generador interno, del objeto, o del array mientras no sea inválido, después de lo cual, la ejecución continuará en el generador externo.

Si un generador se utiliza con la expresión yield from, la expresión yield from también devolverá cualquier valor devuelto por el generador interno.

Precaución

# Almacenamiento en un array (e.g. con iterator_to_array())

yield from no reinicia las claves. Preserva las claves devueltas por el objeto Traversable, o array. Por lo tanto, algunos valores pueden compartir una clave común con otros yield o yield from, que, al insertarse en un array, sobrescribirá los valores anteriores con esa clave.

Un caso frecuente en el que esto es importante es iterator_to_array() devolviendo un array con clave por defecto, lo que puede llevar a resultados potencialmente inesperados. iterator_to_array() tiene un segundo parámetro `preserve_keys` que puede ser definido en `false` para recolectar todos los valores ignorando las claves devueltas por el Generator.

Ejemplo #5 yield from con iterator_to_array()

    <?php
    function inner() {
        yield 1; // clave 0
        yield 2; // clave 1
        yield 3; // clave 2
    }
    function gen() {
        yield 0; // clave 0
        yield from inner(); // claves 0-2
        yield 4; // clave 1
    }
    // establece en false el segundo parámetro para obtener un array [0, 1, 2, 3, 4]
    var_dump(iterator_to_array(gen()));

El ejemplo anterior mostrará:

    array(3) {
      [0]=>
      int(1)
      [1]=>
      int(4)
      [2]=>
      int(3)
    }

Ejemplo #6 Uso básico de yield from

    <?php
    function count_to_ten() {
        yield 1;
        yield 2;
        yield from [3, 4];
        yield from new ArrayIterator([5, 6]);
        yield from seven_eight();
        yield 9;
        yield 10;
    }

    function seven_eight() {
        yield 7;
        yield from eight();
    }

    function eight() {
        yield 8;
    }

    foreach (count_to_ten() as $num) {
        echo "$num ";
    }

El ejemplo anterior mostrará:

    1 2 3 4 5 6 7 8 9 10

Ejemplo #7 yield from y los valores devueltos

    <?php
    function count_to_ten() {
        yield 1;
        yield 2;
        yield from [3, 4];
        yield from new ArrayIterator([5, 6]);
        yield from seven_eight();
        return yield from nine_ten();
    }

    function seven_eight() {
        yield 7;
        yield from eight();
    }

    function eight() {
        yield 8;
    }

    function nine_ten() {
        yield 9;
        return 10;
    }

    $gen = count_to_ten();
    foreach ($gen as $num) {
        echo "$num ";
    }
    echo $gen->getReturn();

El ejemplo anterior mostrará:

    1 2 3 4 5 6 7 8 9 10

## Comparación de los generadores con los objetos Iterator

La principal ventaja de los generadores es su simplicidad. Menos código debe ser escrito que cuando se trata de implementar una clase Iterator, y generalmente es más legible. Por ejemplo, la función y la clase siguientes son equivalentes:

    <?php
    function getLinesFromFile($fileName) {
        if (!$fileHandle = fopen($fileName, 'r')) {
            return;
        }

        while (false !== $line = fgets($fileHandle)) {
            yield $line;
        }

        fclose($fileHandle);
    }

    // versus...

    class LineIterator implements Iterator {
        protected $fileHandle;

        protected $line;
        protected $i;

        public function __construct($fileName) {
            if (!$this->fileHandle = fopen($fileName, 'r')) {
                throw new RuntimeException('Imposible abrir el fichero: "' . $fileName . '"');
            }
        }

        public function rewind() {
            fseek($this->fileHandle, 0);
            $this->line = fgets($this->fileHandle);
            $this->i = 0;
        }

        public function valid() {
            return false !== $this->line;
        }

        public function current() {
            return $this->line;
        }

        public function key() {
            return $this->i;
        }

        public function next() {
            if (false !== $this->line) {
                $this->line = fgets($this->fileHandle);
                $this->i++;
            }
        }

        public function __destruct() {
            fclose($this->fileHandle);
        }
    }

Sin embargo, esta flexibilidad tiene un costo: los generadores son iteradores que solo avanzan, y no pueden ser reinicializados una vez que su recorrido haya comenzado. Esto también significa que el mismo generador no puede ser utilizado varias veces: el generador deberá ser reconstruido llamando nuevamente a la función generadora.

### Ver también

- Iteración de Objeto

# Atributos

## Tabla de contenidos

- Descripción general de atributos
- Sintaxis de atributos
- Lectura de atributos con la API de Reflection
- Declaración de clases de atributos

## Descripción general de atributos

(PHP 8)

Los atributos de PHP ofrecen metadatos estructurados y legibles por máquinas para clases, métodos, funciones, parámetros, propiedades y constantes. Pueden ser inspeccionados en tiempo de ejecución a través de la API de Reflection, lo que permite un comportamiento dinámico sin modificar el código. Los atributos proporcionan una forma declarativa de anotar el código con metadatos.

Los atributos permiten desacoplar la implementación de una funcionalidad de su uso. Mientras que las interfaces definen la estructura mediante la imposición de métodos, los atributos proporcionan metadatos en varios elementos, incluidos métodos, funciones, propiedades y constantes. A diferencia de las interfaces, que obligan a implementar métodos, los atributos anotan el código sin alterar su estructura.

Los atributos pueden complementar o reemplazar métodos opcionales de una interfaz al proporcionar metadatos en lugar de una estructura impuesta. Considera una interfaz `ActionHandler` que representa una operación en una aplicación. Algunas implementaciones pueden necesitar un paso de configuración, mientras que otras no. En lugar de obligar a todas las clases que implementan `ActionHandler` a definir un método `setUp()`, un atributo puede indicar los requisitos de configuración. Este enfoque aumenta la flexibilidad, permitiendo que los atributos se apliquen varias veces cuando sea necesario.

Ejemplo #1 Implementación de métodos opcionales de una interfaz mediante atributos

    <?php
    interface ActionHandler
    {
        public function execute();
    }

    #[Attribute]
    class SetUp {}

    class CopyFile implements ActionHandler
    {
        public string $fileName;
        public string $targetDirectory;

        #[SetUp]
        public function fileExists()
        {
            if (!file_exists($this->fileName)) {
                throw new RuntimeException("El archivo no existe");
            }
        }

        #[SetUp]
        public function targetDirectoryExists()
        {
            if (!file_exists($this->targetDirectory)) {
                mkdir($this->targetDirectory);
            } elseif (!is_dir($this->targetDirectory)) {
                throw new RuntimeException("El directorio de destino $this->targetDirectory no es un directorio");
            }
        }

        public function execute()
        {
            copy($this->fileName, $this->targetDirectory . '/' . basename($this->fileName));
        }
    }

    function executeAction(ActionHandler $actionHandler)
    {
        $reflection = new ReflectionObject($actionHandler);

        foreach ($reflection->getMethods() as $method) {
            $attributes = $method->getAttributes(SetUp::class);

            if (count($attributes) > 0) {
                $methodName = $method->getName();

                $actionHandler->$methodName();
            }
        }

        $actionHandler->execute();
    }

    $copyAction = new CopyFile();
    $copyAction->fileName = "/tmp/foo.jpg";
    $copyAction->targetDirectory = "/home/user";

    executeAction($copyAction);

## Sintaxis de atributos

La sintaxis de atributos consta de varios componentes clave. Una declaración de atributo comienza con `#[` y termina con `]`. Dentro de esta, se pueden listar uno o más atributos, separados por comas. El nombre del atributo puede ser no cualificado, cualificado o totalmente cualificado, como se describe en Uso de los espacios de nombres: lo básico. Los argumentos para el atributo son opcionales y se encierran entre paréntesis `()`. Los argumentos solo pueden ser valores literales o expresiones constantes. Se admite la sintaxis de argumentos posicionales y nombrados.

Los nombres de los atributos y sus argumentos se resuelven en una clase, y los argumentos se pasan a su constructor cuando se solicita una instancia del atributo a través de la API de Reflection. Por lo tanto, se recomienda crear una clase para cada atributo.

Ejemplo #1 Sintaxis de atributos

    <?php
    // a.php
    namespace MyExample;

    use Attribute;

    #[Attribute]
    class MyAttribute
    {
        const VALUE = 'value';

        private $value;

        public function __construct($value = null)
        {
            $this->value = $value;
        }
    }

    // b.php

    namespace Another;

    use MyExample\MyAttribute;

    #[MyAttribute]
    #[\MyExample\MyAttribute]
    #[MyAttribute(1234)]
    #[MyAttribute(value: 1234)]
    #[MyAttribute(MyAttribute::VALUE)]
    #[MyAttribute(array("key" => "value"))]
    #[MyAttribute(100 + 200)]
    class Thing
    {
    }

    #[MyAttribute(1234), MyAttribute(5678)]
    class AnotherThing
    {
    }

## Lectura de atributos con la API de Reflection

Para acceder a los atributos de clases, métodos, funciones, parámetros, propiedades y constantes de clase, utiliza el método getAttributes() proporcionado por la API de Reflection. Este método devuelve un array de instancias de ReflectionAttribute. Estas instancias pueden consultarse para obtener el nombre del atributo, los argumentos, y también pueden usarse para instanciar una instancia del atributo representado.

Separar la representación reflejada del atributo de su instancia real proporciona un mayor control sobre la gestión de errores, como clases de atributos faltantes, argumentos mal escritos, o valores ausentes. Los objetos de la clase de atributo se instancian solo después de llamar a ReflectionAttribute::newInstance(), lo que garantiza que la validación de los argumentos se realice en ese momento.

Ejemplo #1 Lectura de atributos con la API de Reflection

    <?php

    #[Attribute]
    class MyAttribute
    {
        public $value;

        public function __construct($value)
        {
            $this->value = $value;
        }
    }

    #[MyAttribute(value: 1234)]
    class Thing
    {
    }

    function dumpAttributeData($reflection) {
        $attributes = $reflection->getAttributes();

        foreach ($attributes as $attribute) {
           var_dump($attribute->getName());
           var_dump($attribute->getArguments());
           var_dump($attribute->newInstance());
        }
    }

    dumpAttributeData(new ReflectionClass(Thing::class));

El ejemplo anterior mostrará:

    string(11) "MyAttribute"
    array(1) {
      ["value"]=>
      int(1234)
    }
    object(MyAttribute)#3 (1) {
      ["value"]=>
      int(1234)
    }

En lugar de iterar sobre todos los atributos en la instancia de reflexión, puedes recuperar solo aquellos de una clase de atributo específica pasando el nombre de la clase de atributo como argumento.

Ejemplo #2 Lectura de atributos específicos utilizando la API de Reflection

    <?php
    #[Attribute]
    class MyAttribute
    {
        public $value;

        public function __construct($value)
        {
            $this->value = $value;
        }
    }

    #[MyAttribute(value: 1234)]
    class Thing
    {
    }

    function dumpMyAttributeData($reflection) {
        $attributes = $reflection->getAttributes(MyAttribute::class);

        foreach ($attributes as $attribute) {
           var_dump($attribute->getName());
           var_dump($attribute->getArguments());
           var_dump($attribute->newInstance());
        }
    }

    dumpMyAttributeData(new ReflectionClass(Thing::class));

## Declaración de clases de atributos

Se recomienda definir una clase separada para cada atributo. En el caso más simple, una clase vacía con la declaración `#[Attribute]` es suficiente. El atributo puede ser importado desde el espacio de nombres global utilizando una declaración `use`.

Ejemplo #1 Clase de atributo simple

    <?php

    namespace Example;

    use Attribute;

    #[Attribute]
    class MyAttribute
    {
    }

Para restringir los tipos de declaraciones a los que se puede aplicar un atributo, pasa una máscara de bits como primer argumento en la declaración `#[Attribute]`

Ejemplo #2 Usar la especificación de destino para restringir dónde se pueden usar los atributos

    <?php

    namespace Example;

    use Attribute;

    #[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION)]
    class MyAttribute
    {
    }

Declarar MyAttribute en otro tipo ahora generará una excepción durante la llamada a ReflectionAttribute::newInstance()

Los siguientes destinos se pueden especificar:

- `Attribute::TARGET_CLASS`
- `Attribute::TARGET_FUNCTION`
- `Attribute::TARGET_METHOD`
- `Attribute::TARGET_PROPERTY`
- `Attribute::TARGET_CLASS_CONSTANT`
- `Attribute::TARGET_PARAMETER`
- `Attribute::TARGET_ALL`

Por defecto, un atributo solo se puede usar una vez por declaración. Para permitir que un atributo sea repetible, especifícalo en la máscara de bits de la declaración `#[Attribute]` utilizando el flag `Attribute::IS_REPEATABLE`

Ejemplo #3 Usar IS_REPEATABLE para permitir que un atributo se use varias veces en una declaración

    <?php

    namespace Example;

    use Attribute;

    #[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION | Attribute::IS_REPEATABLE)]
    class MyAttribute
    {
    }

# Las referencias

## Tabla de contenidos

- ¿Qué es una referencia?
- ¿Qué hacen las referencias?
- Lo que las referencias no son
- Paso por referencia
- Devolver referencias
- Destruir una referencia
- Identificar una referencia

## ¿Qué es una referencia?

En PHP, las referencias son una forma de acceder al contenido de una misma variable utilizando varios nombres. Las referencias no son como los punteros en C: no se pueden realizar operaciones aritméticas de punteros sobre ellas, no son direcciones de memoria, etc. Se puede consultar Lo que las referencias no son para más información. De hecho, las referencias son alias en la tabla de símbolos. Tenga en cuenta que en PHP, el nombre de una variable y su contenido son dos nociones distintas, lo que hace que se puedan dar varios nombres al mismo contenido. Se puede hacer la analogía con los ficheros bajo Unix, y sus nombres: los nombres de las variables son las entradas en un directorio, mientras que el contenido de la variable es el fichero en sí mismo. Las referencias en PHP pueden entonces ser consideradas similares a los enlaces bajo Unix.

## ¿Qué hacen las referencias?

Existen tres principales usos de las referencias: la asignación por referencia, el paso por referencia y el retorno por referencia. Esta sección introducirá estas operaciones, con enlaces a más detalles.

### Asignación por referencia

En este primer caso, las referencias PHP permiten que dos variables referencien el mismo contenido. Por ejemplo:

    <?php
    $a =& $b;

Esta escritura indica que $a y $b apuntan al mismo contenido.

> Nota:

> $a y $b son completamente iguales aquí: no es $a quien apunta a $b, o viceversa. Son $a y $b quienes apuntan al mismo contenido.

> Nota:

> Si se asigna, pasa o devuelve una variable indefinida por referencia, se creará automáticamente.

> Ejemplo #1 Uso de referencias con variables indefinidas

>     <?php

>     function foo(&$var) {}

>     foo($a); // $a es "creada" y asignada a NULL

>     $b = array();
>     foo($b['b']);
>     var_dump(array_key_exists('b', $b)); // bool(true)

>     $c = new stdClass();
>     foo($c->d);
>     var_dump(property_exists($c, 'd')); // bool(true)

La misma sintaxis puede ser utilizada con las funciones que devuelven referencias:

    <?php
    $foo =& find_var($bar);

Utilizar la misma sintaxis con una función que no devuelve por referencia generará un error, al igual que utilizarla con el resultado del operador new. Aunque los objetos se pasan como punteros, esto no es idéntico a las referencias como se explica en la sección los Objetos y referencias.

Advertencia

Si se asigna una referencia a una variable declarada como `global` en una función, la referencia solo será visible dentro de la función. Se puede evitar esto utilizando el array $GLOBALS.

Ejemplo #2 Referenciar variables globales desde funciones

    <?php
    $var1 = "Variable Ejemplo";
    $var2 = "";

    function global_references($use_globals)
    {
        global $var1, $var2;

        if (!$use_globals) {
            $var2 =& $var1; // visible solo en la función
        } else {
            $GLOBALS["var2"] =& $var1; // visible también en el contexto global
        }
    }

    global_references(false);
    echo "var2 está definido como '$var2'\n"; // var2 está definido como ''

    global_references(true);
    echo "var2 está definido como '$var2'\n"; // var2 está definido como 'Variable Ejemplo'

Vea `global $var;` como un atajo para `$var =& $GLOBALS['var'];`. Por lo tanto, asignar otra referencia a `$var` solo modifica la referencia local de la variable.

> Nota:

> Si se asigna un valor a una variable que tiene referencias en una estructura `foreach`, las referencias también serán modificadas.

> Ejemplo #3 Referencias y estructura foreach

>     <?php
>     $ref = 0;
>     $row =& $ref;

>     foreach (array(1, 2, 3) as $row) {
>         // hacer algo
>     }

>     echo $ref; // 3 - el último elemento del array iterado

Aunque no es estrictamente una asignación por referencia, las expresiones creadas con la estructura de lenguaje `array()` pueden también comportarse como tales, prefijando con `&` el elemento del array. Aquí hay un ejemplo:

    <?php
    $a = 1;
    $b = array(2, 3);
    $arr = array(&$a, &$b[0], &$b[1]);
    $arr[0]++;
    $arr[1]++;
    $arr[2]++;
    /* $a == 2, $b == array(3, 4); */
    var_dump($a);
    var_dump($b);

Note que las referencias dentro de los arrays pueden resultar peligrosas. Utilizar una asignación normal (no por referencia) con una referencia a la derecha del operador no transforma la parte izquierda de la asignación en referencia, pero las referencias dentro de los arrays son preservadas. Esto se aplica también a las llamadas de funciones con un array pasado por valor. Ejemplo:

    <?php

    /* Asignación de variables escalares */
    $a = 1;
    $b =& $a;
    $c = $b;
    $c = 7; // $c no es una referencia; no hay cambio en $a o $b
    print "a = {$a}; b = {$b}; c = {$c}\n\n";

    /* Asignación de variables de tipo array */
    $arr = array(1);
    $a =& $arr[0]; // $a y $arr[0] son referencias al mismo valor
    $arr2 = $arr; // NO es una asignación por referencia!
    $arr2[0]++;
    /* $a == 2, $arr == array(2) */
    /* ¡Los contenidos de $arr son cambiados aunque no fuera una referencia! */
    print "a = {$a}\n";
    var_dump($arr);
    var_dump($arr2);

En otras palabras, desde el punto de vista de las referencias, el comportamiento de los arrays está definido elemento por elemento; el comportamiento de cada elemento es independiente del estado de referencia del array que los contiene.

### Paso por referencia

El segundo interés de las referencias es permitir pasar variables por referencia. Esto se realiza haciendo referenciar el mismo contenido por una variable local a una función y por una variable del contexto llamante. Por ejemplo:

    <?php
    function foo(&$var)
    {
        $var++;
    }

    $a = 5;
    foo($a);
    print $a;

Después de la ejecución de esta porción de código, $a vale 6. Esto se debe a que, en la función foo, la variable $var apunta al mismo contenido que $a. Para más información sobre este tema, se puede consultar la sección paso por referencia.

### Retorno por referencia

El tercer interés de las referencias es permitir el retorno de valores por referencia.

## Lo que las referencias no son

Como se ha visto anteriormente, las referencias no son punteros. Esto significa que el script siguiente no hará lo que se espera:

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

    foo($bar);

Aquí, la variable $var en la función foo estará ligada a $bar en el llamante, pero luego estará ligada a $GLOBALS["baz"]. No es posible ligar $bar a otra cosa utilizando el mecanismo de referencias, ya que $bar no es accesible en la función foo (aunque está representada por $var, $var solo hace referencia al valor, y no tiene una ligadura en la tabla de símbolos del llamante). Se puede utilizar el retorno por referencia para referenciar variables seleccionadas por la función.

## Paso por referencia

Se puede pasar una variable por referencia a una función, de manera que esta pueda modificarla. La sintaxis es la siguiente:

    <?php
    function foo(&$var)
    {
        $var++;
    }

    $a = 5;
    foo($a);
    print $a; // $a vale 6 ahora

> Nota: No hay signo de referencia en la llamada de la función, solo en su definición. La definición de la función en sí misma es suficiente para pasar correctamente argumentos por referencia.

Los siguientes datos pueden ser pasados por referencia:

- Una variable, como en `foo($a)`

- Una referencia devuelta por una función:

      <?php
      function foo(&$var)
      {
          $var++;
          print $var;
      }

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

      foo(bar());

  Para más información, ver los detalles en retorno por referencia.

Todas las otras expresiones no deben ser pasadas por referencia, ya que el resultado será indefinido. Por ejemplo, los siguientes pasos por referencia son inválidos:

    <?php

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

    function bar() // Note la ausencia de &
    {
       $a = 5;
       return $a;
    }

    foo(bar());    // Produce una notificación

    foo($a = 5);    // Expresión, no una variable
    foo(5);         // Produce un error fatal

    class Foobar{}

    foo(new Foobar()) // Produce una notificación desde PHP 7.0.7
                      // Notificación: Solo las variables deben ser pasadas por referencia.

## Devolver referencias

Devolver referencias es útil cuando se quiere utilizar una función para determinar a qué variable debe estar ligada una referencia. No utilice no el retorno por referencia para mejorar el rendimiento, el motor es suficientemente robusto para optimizar esto internamente. Devuelva referencias solo cuando haya buenas razones técnicas para hacerlo. Para devolver referencias, utilice esta sintaxis:

    <?php
    class Foo
    {
        public $value = 42;

        public function &getValue()
        {
            return $this->value;
        }
    }

    $obj = new Foo();
    $myValue = &$obj->getValue(); // $myValue es una referencia de $obj->value, que vale 42.
    $obj->value = 2;
    echo $myValue;                // muestra el nuevo valor de $obj->value, es decir, 2.

En este ejemplo, se asigna un valor a la propiedad del objeto devuelta por la función getValue, y no a su copia, como sería el caso si no se hubiera utilizado la sintaxis de referencia.

> Nota: A diferencia del paso de parámetro, aquí, se debe utilizar `&` en ambos lugares, tanto para indicar que se devuelve por referencia (no por copia), como para indicar que también se asigna por referencia (no por copia tampoco) para la variable $myValue.

> Nota: Si se intenta devolver una referencia desde una función con la sintaxis: `return ($this->value);`, esto no funcionará no como se espera, y devolverá el resultado de la expresión, y no de la variable, por referencia. Solo se pueden devolver variables por referencia desde una función, y nada más.

Para utilizar la referencia devuelta, se debe utilizar la asignación por referencia:

    <?php

    function &collector()
    {
        static $collection = array();
        return $collection;
    }

    $collection = &collector();
    // Ahora, la variable $collection es una variable por referencia que referencia el array static dentro de la función

    $collection[] = 'foo';

    print_r(collector());

El ejemplo anterior mostrará:

    Array
    (
        [0] => foo
    )

> Nota: Si la asignación se realiza sin el símbolo `&`, por ejemplo `$collection = collector();`, la variable $collection recibirá una copia del valor, y no la referencia devuelta por la función.

Para pasar la referencia devuelta a otra función que espera una referencia, se puede utilizar la siguiente sintaxis:

    <?php

    function &collector()
    {
      static $collection = array();
      return $collection;
    }

    array_push(collector(), 'foo');

> Nota: Note que `array_push(&collector(), 'foo');` no funcionará, y resultará en un error fatal.

## Destruir una referencia

Cuando se destruye una referencia, solo se rompe el enlace entre el nombre de la variable y su contenido. Esto no significa que el contenido de la variable sea destruido. Por ejemplo:

    <?php
    $a = 1;
    $b =& $a;
    unset($a);
    var_dump($a);
    var_dump($b);

Este ejemplo no destruirá $b, solo $a.

Una vez más, se puede comparar esta acción con la llamada unlink de Unix.

## Identificar una referencia

Muchas sintaxis de PHP están implementadas a través del mecanismo de referencia, y todo lo que se ha visto en cuanto a las ligaduras entre variables se aplica a estas sintaxis. Algunas construcciones, como el paso de argumentos y el retorno por referencia, han sido mencionadas anteriormente. Otras construcciones que utilizan referencias son las siguientes:

### Referencias globales

Cuando se declara una variable como global $var, se crea en realidad una referencia a una variable global. En otras palabras, esto es lo mismo que:

    <?php
    $var =& $GLOBALS["var"];

Esto también significa que destruir la variable $var no resultará en la destrucción de la variable global.

# Variables predefinidas

PHP proporciona variables predefinidas que representan variables externas, variables de entorno integradas y otra información sobre el entorno de ejecución, tales como el número y los valores de los argumentos pasados al script en el entorno CLI.

# Las Superglobales

Las Superglobales — Variables internas siempre disponibles, independientemente del contexto

### Descripción

Varios arrays predefinidos en PHP son "superglobales", lo que significa que están disponibles independientemente del contexto del script. No es necesario utilizar global $variable; antes de acceder a ellas en funciones o métodos.

Las variables superglobales son:

- $GLOBALS
- $_SERVER
- $_GET
- $_POST
- $_FILES
- $_COOKIE
- $_SESSION
- $_REQUEST
- $_ENV

### Notas

> Nota: Disponibilidad de las variables

> Por omisión, todas las superglobales están disponibles, y solo las directivas de configuración pueden hacerlas no disponibles. Para más información, consulte la documentación sobre el orden de las variables.

> Nota: Variables variables

> Las superglobales no pueden ser utilizadas como variables dinámicas en una función o método de una clase.

### Ver también

- El ámbito de las variables
- La directiva variables_order
- La extensión sobre los filtros

# $GLOBALS

(PHP 4, PHP 5, PHP 7, PHP 8)

$GLOBALS — Hace referencia a todas las variables disponibles en un contexto global

### Descripción

Un array asociativo que contiene referencias a todas las variables globales actualmente definidas en el contexto de ejecución global del script. Los nombres de las variables son los índices del array.

### Ejemplos

Ejemplo #1 Ejemplo con $GLOBALS

    <?php

    function test()
    {
        $foo = "variable local";

        echo '$foo en el contexto global : ' . $GLOBALS["foo"] . "\n";
        echo '$foo en el contexto actual : ' . $foo . "\n";
    }

    $foo = "Contenido de ejemplo";
    test();

    ?>

Resultado del ejemplo anterior es similar a:

    $foo en el contexto global : Contenido de ejemplo
    $foo en el contexto actual : variable local

Advertencia

A partir de PHP 8.1.0, el acceso en escritura al array entero $GLOBALS ya no es soportado:

Ejemplo #2 Escribir en el array entero $GLOBALS resultará en un error.

    <?php

    // Genera un error durante la compilación:
    $GLOBALS = [];
    $GLOBALS += [];
    $GLOBALS =& $x;
    $x =& $GLOBALS;
    unset($GLOBALS);
    array_pop($GLOBALS);
    // ...y cualquier otra operación de escritura/lectura-escritura en $GLOBALS

    ?>

### Notas

> Nota: Esto es una 'superglobal', o variable global automática. Esto significa simplemente que esta variable está disponible en todos los contextos del script. No es necesario hacer global $variable; para acceder a ella en las funciones o los métodos.

> Nota: Disponibilidad de las variables

> A diferencia de todas las demás superglobales, $GLOBALS siempre ha estado disponible en PHP.

> Nota:

> A partir de PHP 8.1.0, $GLOBALS es ahora una copia de solo lectura del array de símbolos global. Es decir, las variables globales no pueden ser modificadas a través de su copia. Anteriormente, el array $GLOBALS estaba excluido del comportamiento habitual por valor de los arrays de PHP y las variables globales podían ser modificadas a través de su copia.

>     <?php

>     // Antes de PHP 8.1.0
>     $a = 1;

>     $globals = $GLOBALS; // Copia ostensiblemente por valor
>     $globals['a'] = 2;
>     var_dump($a); // int(2)

>     // A partir de PHP 8.1.0
>     // esto ya no modifica $a. El comportamiento anterior violaba la semántica por valor.
>     $globals = $GLOBALS;
>     $globals['a'] = 1;

>     // Para restaurar el comportamiento anterior, iterar su copia y asignar cada propiedad de vuelta a $GLOBALS.
>     foreach ($globals as $key => $value) {
>         $GLOBALS[$key] = $value;
>     }

>     ?>

# $_SERVER

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_SERVER — Variables de servidor y de ejecución

### Descripción

$_SERVER es un array que contiene información como encabezados, rutas y ubicaciones de script. Las entradas de este array son creadas por el servidor web, por lo que no hay garantía de que cada servidor web proporcione toda esta información; los servidores pueden omitir algunas o proporcionar otras no listadas aquí. Sin embargo, la mayoría de estas variables están contempladas en la especificación » CGI/1.1 y es probable que estén definidas.

> Nota: Cuando PHP se ejecuta en línea de comandos command line, la mayoría de estas entradas no estarán disponibles o no tendrán sentido.

Además de los elementos enumerados a continuación, PHP creará elementos adicionales con valores provenientes de los encabezados de la petición. Estas entradas se nombrarán `HTTP_` seguido del nombre del encabezado, en mayúsculas y con guiones bajos en lugar de guiones. Por ejemplo, el encabezado `Accept-Language` estará disponible como `$_SERVER['HTTP_ACCEPT_LANGUAGE']`.

### Índices

'PHP_SELF'
  El nombre del archivo del script en ejecución, relativo a la raíz web. Por ejemplo, $_SERVER['PHP_SELF'] en el script ubicado en http://example.com/foo/bar.php será /foo/bar.php. La constante __FILE__ contiene la ruta completa y el nombre del archivo (incluido) actual. Si PHP funciona en línea de comandos, esta variable contiene el nombre del script.
'argv'
  Array de argumentos pasados al script. Cuando el script es llamado en línea de comandos, esto da acceso a los argumentos, como en lenguaje C. Cuando el script es llamado con el método GET, este array contendrá la cadena de consulta.
'argc'
  Contiene el número de parámetros de línea de comandos pasados al script (si el script funciona en línea de comandos).
'GATEWAY_INTERFACE'
  Número de revisión de la interfaz CGI del servidor. Por ejemplo `'CGI/1.1'`.
'SERVER_ADDR'
  La dirección IP del servidor bajo el cual el script actual está siendo ejecutado.
'SERVER_NAME'
  El nombre del servidor host que ejecuta el script siguiente. Si el script es ejecutado en un host virtual, esto será el valor definido para ese host virtual.

  > Nota: En Apache 2, `UseCanonicalName = On` y `ServerName` deben ser definidos. De lo contrario, este valor refleja el nombre de host proporcionado por el cliente, que puede ser falsificado. No es seguro confiar en este valor en contextos dependientes de la seguridad.

'SERVER_SOFTWARE'
  Cadena de identificación del servidor, que es dada en los encabezados al responder a las peticiones.
'SERVER_PROTOCOL'
  Nombre y revisión del protocolo de comunicación; por ejemplo `HTTP/1.0`;
'REQUEST_METHOD'
  Método de petición utilizado para acceder a la página; por ejemplo `GET`, `HEAD`, `POST`, `PUT`.

  > Nota:

  > El script PHP termina después de enviar los encabezados (es decir, después de producir cualquier salida sin bufferización de salida) si el método de la petición era `HEAD`.

'REQUEST_TIME'
  El timestamp Unix del inicio de la petición.
'REQUEST_TIME_FLOAT'
  El timestamp del inicio de la petición, con precisión a microsegundos.
'QUERY_STRING'
  La cadena de consulta, si existe, que es utilizada para acceder a la página.
'DOCUMENT_ROOT'
  La raíz bajo la cual el script actual está siendo ejecutado, como se define en la configuración del servidor.
'HTTPS'
  Definido a un valor no vacío si el script fue llamado vía el protocolo HTTPS.
'REMOTE_ADDR'
  La dirección IP del cliente que solicita la página actual.
'REMOTE_HOST'
  El nombre del host que lee el script actual. La resolución DNS inversa se basa en el valor de REMOTE_ADDR.

  > Nota: El servidor web debe estar configurado para crear esta variable. Por ejemplo, en Apache, `HostnameLookups On` debe ser definido dentro de httpd.conf para que exista. Ver también gethostbyaddr().

'REMOTE_PORT'
  El puerto utilizado por la máquina cliente para comunicarse con el servidor web.
'REMOTE_USER'
  El usuario autenticado.
'REDIRECT_REMOTE_USER'
  El usuario autenticado si la petición fue redirigida internamente.
'SCRIPT_FILENAME'

  La ruta absoluta hacia el archivo que contiene el script en ejecución.

  > Nota:

  > Si un script es ejecutado con el CLI, con una ruta relativa, como file.php o ../file.php, $_SERVER['SCRIPT_FILENAME'] contendrá la ruta relativa especificada por el usuario.

'SERVER_ADMIN'
  El valor dado a la directiva SERVER_ADMIN (para Apache), en el archivo de configuración. Si el script es ejecutado por un host virtual, esto será la valor definido por el host virtual.
'SERVER_PORT'
  El puerto de la máquina servidor utilizado para las comunicaciones. Por defecto, es `'80'`. Usando SSL, por ejemplo, será reemplazado por el número de puerto HTTP seguro.

  > Nota: En Apache 2, `UseCanonicalName = On`, así como `UseCanonicalPhysicalPort = On` deben ser definidos para obtener el puerto físico real, de lo contrario este valor puede ser falsificado y puede o no devolver el valor del puerto físico. No es seguro confiar en este valor en contextos dependientes de la seguridad.

'SERVER_SIGNATURE'
  Cadena que contiene el número de versión del servidor y el nombre de host virtual, que son añadidos a las páginas generadas por el servidor, si esta opción está activada.
'PATH_TRANSLATED'
  Ruta en el sistema de archivos (no el document-root) hasta el script actual, una vez que el servidor ha hecho una traducción de ruta virtual a real.

  > Nota: Los usuarios de Apache 2 deben usar `AcceptPathInfo = On` en su httpd.conf para definir PATH_INFO.

'SCRIPT_NAME'
  Contiene el nombre del script actual. Esto sirve cuando las páginas deben llamarse a sí mismas. La constante __FILE__ contiene la ruta completa y el nombre del archivo (incluido) actual.
'REQUEST_URI'
  El URI que fue proporcionado para acceder a esta página. Por ejemplo: '`/index.html`'.
'PHP_AUTH_DIGEST'
  Cuando se utiliza la autenticación HTTP Digest, esta variable es definida en el encabezado `"Authorization"` enviado por el cliente (que debe ser utilizado para realizar la validación apropiada).
'PHP_AUTH_USER'
  Cuando se utiliza la autenticación HTTP, esta variable es definida al usuario proporcionado por el usuario.
'PHP_AUTH_PW'
  Cuando se utiliza la autenticación HTTP, esta variable es definida a la contraseña proporcionada por el usuario.
'AUTH_TYPE'
  Cuando se utiliza la autenticación HTTP, esta variable es definida al tipo de identificación.
'PATH_INFO'
  Contiene la información sobre el nombre de la ruta proporcionada por el cliente respecto al nombre del archivo que ejecuta el script actual, sin la cadena relativa a la consulta si existe. Actualmente, si el script actual es ejecutado vía el URI http://www.example.com/php/path_info.php/some/stuff?foo=bar, entonces la variable $_SERVER['PATH_INFO'] contendrá `/some/stuff`.
'ORIG_PATH_INFO'
  Versión original de 'PATH_INFO' antes de ser analizada por PHP.

### Ejemplos

Ejemplo #1 Ejemplo con $_SERVER

    <?php
    echo $_SERVER['SERVER_NAME'];
    ?>

Resultado del ejemplo anterior es similar a:

    www.example.com

### Notas

> Nota: Esto es una 'superglobal', o variable global automática. Esto significa simplemente que esta variable está disponible en todos los contextos del script. No es necesario hacer global $variable; para acceder a ella en las funciones o los métodos.

### Ver también

- La extensión sobre filtros

# $_GET

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_GET — Variables la cadena de consulta

### Descripción

Un array asociativo de variables pasado al script actual vía parámetros URL (también conocida como cadena de consulta). Tenga en cuenta que el array no solo se rellena para las solicitudes GET, sino para todas las solicitudes con una cadena de consulta.

### Ejemplos

Ejemplo #1 Ejemplo de $_GET

    <?php
    echo '¡Hola ' . htmlspecialchars($_GET["name"]) . '!';
    ?>

Asumiendo que el usuario introdujo `http://example.com/?name=Hannes`

Resultado del ejemplo anterior es similar a:

    ¡Hola Hannes!

### Notas

> Nota: Esto es una 'superglobal', o variable global automática. Esto significa simplemente que esta variable está disponible en todos los contextos del script. No es necesario hacer global $variable; para acceder a ella en las funciones o los métodos.

> Nota:

> Las valores en $_GET son pasados automáticamente vía urldecode().

### Ver también

- Manejo de variables externas
- La extensión filter

# $_POST

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_POST — Datos de formulario de solicitudes HTTP POST

### Descripción

Un array asociativo de variables pasadas al script actual a través del método POST de HTTP cuando se emplea `application/x-www-form-urlencoded` o `multipart/form-data` como Content-Type de HTTP en la petición.

### Ejemplos

Ejemplo #1 Ejemplo de $_POST

    <?php
    echo '¡Hola ' . htmlspecialchars($_POST["name"]) . '!';
    ?>

Asumiendo que el usuario envió una solicitud POST con `name=Hannes` en el cuerpo.

Resultado del ejemplo anterior es similar a:

    ¡Hola Hannes!

### Notas

> Nota: Esto es una 'superglobal', o variable global automática. Esto significa simplemente que esta variable está disponible en todos los contextos del script. No es necesario hacer global $variable; para acceder a ella en las funciones o los métodos.

> Nota: Para leer datos enviados mediante POST con otros tipos de contenido (por ejemplo, `application/json` o `application/xml`), se debe utilizar php://input. A diferencia de $_POST, que solo funciona con `application/x-www-form-urlencoded` y `multipart/form-data`, php://input proporciona acceso directo a los datos sin procesar del cuerpo de la solicitud.

### Ver también

- Manejo de variables externas
- La extensión filter

# $_FILES

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_FILES — Variables de subida de ficheros HTTP

### Descripción

Un array asociativo de elementos subidos al script en curso a través del método POST. La estructura de este array se resume en la sección Subidas con el método POST.

### Notas

> Nota: Esto es una 'superglobal', o variable global automática. Esto significa simplemente que esta variable está disponible en todos los contextos del script. No es necesario hacer global $variable; para acceder a ella en las funciones o los métodos.

### Ver también

- move_uploaded_file() - Mueve un archivo subido a una nueva ubicación
- Manejo de subida de ficheros

# $_REQUEST

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_REQUEST — Variables HTTP Request

### Descripción

Un array asociativo que por defecto contiene el contenido de $_GET, $_POST y $_COOKIE.

### Notas

> Nota: Esto es una 'superglobal', o variable global automática. Esto significa simplemente que esta variable está disponible en todos los contextos del script. No es necesario hacer global $variable; para acceder a ella en las funciones o los métodos.

> Nota:

> Cuando se ejecuta en la línea de comandos , no se incluirán las entradas argv y argc; ya que están presentes en el $_SERVER array.

> Nota:

> Las variables en $_REQUEST se proporcionan al script a través de los mecanismos de entrada GET, POST, y COOKIE y por lo tanto pueden ser manipulados por el usuario remoto y no debe confiar en el contenido. La presencia y el orden de las variables listadas en este array se definen según la directiva de configuración PHP request_order, y variables_order.

### Ver también

- Tratando con variables externas
- La extensión filter

# $_SESSION

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_SESSION — Variables de sesión

### Descripción

Es un array asociativo que contiene variables de sesión disponibles para el script actual. Ver la documentación de Funciones de sesión para más información sobre su uso.

### Notas

> Nota: Esto es una 'superglobal', o variable global automática. Esto significa simplemente que esta variable está disponible en todos los contextos del script. No es necesario hacer global $variable; para acceder a ella en las funciones o los métodos.

### Ver también

- session_start() - Inicia una nueva sesión o reanuda una sesión existente

# $_ENV

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_ENV — Variables de entorno

### Descripción

Una variable tipo array asociativo de variables pasadas al script actual a través del método del entorno.

Estas variables son importadas en el espacio de nombres global de PHP desde el entorno bajo el que está siendo ejecutado el intérprete PHP. Muchas son entregadas por el intérprete de comandos bajo el que PHP está corriendo y diferentes sistemas suelen tener diferentes tipos de intérpretes de comandos, una lista definitiva es imposible. Por favor consulte la documentación de su intérprete de comandos para una lista de las variables de entorno que se definen.

Otras variables de entorno incluyen las variables CGI, colocadas allí independientemente de que PHP esté siendo ejecutado como módulo del servidor o procesador CGI.

### Ejemplos

Ejemplo #1 Ejemplo de $_ENV

    <?php
    echo '¡Mi nombre de usuario es ' . $_ENV["USER"] . '!';
    ?>

Asumiendo que "bjori" ejecuta este script

Resultado del ejemplo anterior es similar a:

    ¡Mi nombre de usuario es bjori!

### Notas

> Nota: Esto es una 'superglobal', o variable global automática. Esto significa simplemente que esta variable está disponible en todos los contextos del script. No es necesario hacer global $variable; para acceder a ella en las funciones o los métodos.

### Ver también

- getenv() - Retorna el valor de una o todas las variables de entorno
- La extensión filter

# $_COOKIE

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_COOKIE — Cookies HTTP

### Descripción

Una variable tipo array asociativo de variables pasadas al script actual a través de Cookies HTTP.

### Ejemplos

Ejemplo #1 Ejemplo de $_COOKIE

    <?php
    echo '¡Hola ' . htmlspecialchars($_COOKIE["nombre"]) . '!';
    ?>

Asumiendo que la cookie "nombre" ha sido definida anteriormente

Resultado del ejemplo anterior es similar a:

    ¡Hola Juan!

### Notas

> Nota: Esto es una 'superglobal', o variable global automática. Esto significa simplemente que esta variable está disponible en todos los contextos del script. No es necesario hacer global $variable; para acceder a ella en las funciones o los métodos.

### Ver también

- setcookie() - Envía una cookie
- Gestión de variables externas
- La extensión filter

# $php_errormsg

(PHP 4, PHP 5, PHP 7)

$php_errormsg — El último mensaje de error

Advertencia

Esta funcionalidad está OBSOLETA a partir de PHP 7.2.0, y ELIMINADA a partir de PHP 8.0.0. Depender de esta funcionalidad está altamente desaconsejado.

Utilice error_get_last() en su lugar.

### Descripción

$php_errormsg es una variable que contiene el texto del último error generado por PHP. Esta variable será únicamente accesible en el mismo contexto de ejecución que el de la línea que generó el error, y únicamente si la directiva de configuración track_errors está activada (se encuentra desactivada por omisión).

Advertencia

Si un gestor de errores definido por el usuario está activo (set_error_handler()), $php_errormsg solo será definido si el gestor de errores devuelve `false`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | La directiva track_errors que hace que $php_errormsg esté disponible ha sido eliminada.
7.2.0 | La directiva track_errors que hace que $php_errormsg esté disponible ha sido marcada como obsoleta.

### Ejemplos

Ejemplo #1 Ejemplo con $php_errormsg

    <?php
    @strpos();
    echo $php_errormsg;
    ?>

Resultado del ejemplo anterior es similar a:

    Wrong parameter count for strpos()

### Ver también

- error_get_last() - Obtener el último error que ocurrió

# $http_response_header

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

$http_response_header — Cabeceras de respuesta HTTP

Advertencia

Esta característica está OBSOLETA a partir de PHP 8.5.0. Depender de esta característica está altamente desaconsejado.

Utilice http_get_last_response_headers() en su lugar.

### Descripción

El $http_response_header array es similar a la función get_headers(). Al utilizar el gestor HTTP, $http_response_header será rellenado con las cabeceras de respuesta HTTP. $http_response_header será creado con un ámbito local.

### Ejemplos

Ejemplo #1 Ejemplo con $http_response_header

    <?php
    function get_contents() {
      file_get_contents("http://example.com");
      var_dump($http_response_header); // La variable es rellenada en el ámbito local
    }
    get_contents();
    var_dump($http_response_header); // Una llamada a get_contents() no rellena la variable fuera del ámbito de la función
    ?>

Resultado del ejemplo anterior es similar a:

    array(9) {
      [0]=>
      string(15) "HTTP/1.1 200 OK"
      [1]=>
      string(35) "Date: Sat, 12 Apr 2008 17:30:38 GMT"
      [2]=>
      string(29) "Server: Apache/2.2.3 (CentOS)"
      [3]=>
      string(44) "Last-Modified: Tue, 15 Nov 2005 13:24:10 GMT"
      [4]=>
      string(27) "ETag: "280100-1b6-80bfd280""
      [5]=>
      string(20) "Accept-Ranges: bytes"
      [6]=>
      string(19) "Content-Length: 438"
      [7]=>
      string(17) "Connection: close"
      [8]=>
      string(38) "Content-Type: text/html; charset=UTF-8"
    }

    Warning: Undefined variable $http_response_header
    NULL

### Ver también

- http_get_last_response_headers() - Obtiene los últimos encabezados de respuesta HTTP
- http_clear_last_response_headers() - Borra los encabezados de respuesta HTTP almacenados

# $argc

(PHP 4, PHP 5, PHP 7, PHP 8)

$argc — El número de argumentos pasados a un script

### Descripción

Contiene el número de argumentos pasados al script actual cuando se ejecuta desde la línea de comandos.

> Nota: El nombre del script es pasado siempre como argumento del script, por lo tanto, el valor mínimo de $argc es `1`.

> Nota: Esta variable sólo está disponible cuando register_argc_argv está activado.

### Ejemplos

Ejemplo #1 Ejemplo de $argc

    <?php
    var_dump($argc);
    ?>

Cuando se ejecuta el ejemplo con: php script.php arg1 arg2 arg3

Resultado del ejemplo anterior es similar a:

    int(4)

### Notas

> Nota:

> Esto también está disponible como $_SERVER['argc'].

### Ver también

- getopt() - Lee las opciones pasadas en la línea de comandos
- $argv

# $argv

(PHP 4, PHP 5, PHP 7, PHP 8)

$argv — Array de argumentos pasados al script

### Descripción

Contiene un array de todos los argumentos pasados al script cuando es llamado desde la línea de comandos.

> Nota: El primer argumento $argv[0] siempre es el nombre que se ha utilizado para ejecutar el script.

> Nota: Esta variable no está disponible cuando register_argc_argv está desactivado.

Advertencia

Para verificar si un script es ejecutado desde la línea de comandos, se recomienda utilizar php_sapi_name() en lugar de verificar si $argv o $_SERVER['argv'] está definido.

### Ejemplos

Ejemplo #1 Ejemplo con $argv

    <?php
    var_dump($argv);
    ?>

Cuando se ejecuta el ejemplo con el comando: php script.php arg1 arg2 arg3

Resultado del ejemplo anterior es similar a:

    array(4) {
      [0]=>
      string(10) "script.php"
      [1]=>
      string(4) "arg1"
      [2]=>
      string(4) "arg2"
      [3]=>
      string(4) "arg3"
    }

### Notas

> Nota:

> También disponible en $_SERVER['argv'].

### Ver también

- getopt() - Lee las opciones pasadas en la línea de comandos
- $argc

## Tabla de contenidos

- Las Superglobales — Variables internas siempre disponibles, independientemente del contexto
- $GLOBALS — Hace referencia a todas las variables disponibles en un contexto global
- $_SERVER — Variables de servidor y de ejecución
- $_GET — Variables la cadena de consulta
- $_POST — Datos de formulario de solicitudes HTTP POST
- $_FILES — Variables de subida de ficheros HTTP
- $_REQUEST — Variables HTTP Request
- $_SESSION — Variables de sesión
- $_ENV — Variables de entorno
- $_COOKIE — Cookies HTTP
- $php_errormsg — El último mensaje de error
- $http_response_header — Cabeceras de respuesta HTTP
- $argc — El número de argumentos pasados a un script
- $argv — Array de argumentos pasados al script

# Excepciones predefinidas

## Tabla de contenidos

- Exception
- ErrorException
- ClosedGeneratorException
- Error
- ArgumentCountError
- ArithmeticError
- AssertionError
- DivisionByZeroError
- CompileError
- ParseError
- TypeError
- ValueError
- UnhandledMatchError
- FiberError
- RequestParseBodyException

Véase también las excepciones SPL.

# Exception

(PHP 5, PHP 7, PHP 8)

## Introducción

Exception es la clase base para todas las excepciones de usuario.

## Sinopsis de la Clase

class Exception implements Throwable {
/* Propiedades */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
public function __construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function getMessage(): string
final public function getPrevious(): ?Throwable
final public function getCode(): int
final public function getFile(): string
final public function getLine(): int
final public function getTrace(): array
final public function getTraceAsString(): string
public function __toString(): string
private function __clone(): void
}

## Propiedades

message

  El mensaje de la excepción

code

  El código de la excepción

file

  El nombre del fichero en el cual la excepción ha sido creada

line

  La línea donde la excepción ha sido creada

previous

  La excepción lanzada previamente

string

  La representación en forma de string de la traza de la pila

trace

  La traza de la pila en forma de array

# Exception::__construct

(PHP 5, PHP 7, PHP 8)

Exception::__construct — Constructor de la excepción

### Descripción

public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)

Construye el objeto Exception.

### Parámetros

`message`

  Mensaje de la excepción a lanzar.

`code`

  El código de la excepción.

`previous`

  La excepción previa utilizada por la serie de excepciones.

> Nota: Llamar al constructor de la clase Exception de una subclase ignora los argumentos por omisión, si las propiedades $code y $message ya están establecidas.

### Notas

> Nota:

> `message` NO es seguro binariamente.

# Exception::getMessage

(PHP 5, PHP 7, PHP 8)

Exception::getMessage — Obtiene el mensaje de Excepción

### Descripción

final public function Exception::getMessage(): string

Devuelve el mensaje de Excepción.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el mensaje de Excepción en formato cadena.

### Ejemplos

Ejemplo #1 Ejemplo de Exception::getMessage()

    <?php
    try {
        throw new Exception("Algún mensaje de error");
    } catch(Exception $e) {
        echo $e->getMessage();
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Algún mensaje de error

### Ver también

- Throwable::getMessage() - Obtiene el mensaje

# Exception::getPrevious

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Exception::getPrevious — Devuelve la Throwable anterior

### Descripción

final public function Exception::getPrevious(): ?Throwable

Devuelve la Throwable anterior (el tercer parámetro de Exception::__construct()).

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la Throwable anterior si está disponible o `null` si no.

### Ejemplos

Ejemplo #1 Ejemplo de Exception::getPrevious()

Recorrer, e imprimir la traza de una excepción.

    <?php
    class MiPropiaExcepción extends Exception {}

    function hacerCosas() {
        try {
            throw new InvalidArgumentException("¡Lo está haciendo mal!", 112);
        } catch(Exception $e) {
            throw new MiPropiaExcepción("Ocurrió algo", 911, $e);
        }
    }

    try {
        hacerCosas();
    } catch(Exception $e) {
        do {
            printf("%s:%d %s (%d) [%s]\n", $e->getFile(), $e->getLine(), $e->getMessage(), $e->getCode(), get_class($e));
        } while($e = $e->getPrevious());
    }
    ?>

Resultado del ejemplo anterior es similar a:

    /home/bjori/ex.php:8 Ocurrió algo (911) [MiPropiaExcepción]
    /home/bjori/ex.php:6 ¡Lo está haciendo mal! (112) [InvalidArgumentException]

### Ver también

- Throwable::getPrevious() - Devuelve el objeto Throwable previo

# Exception::getCode

(PHP 5, PHP 7, PHP 8)

Exception::getCode — Obtiene el código de una excepción

### Descripción

final public function Exception::getCode(): int

Devuelve el código de una excepción.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el código de Excepción en forma de int en Exception pero posiblemente en forma de otros tipos en Exception descendientes (por ejemplo como string en PDOException).

### Ejemplos

Ejemplo #1 Ejemplo de Exception::getCode()

    <?php
    try {
        throw new Exception("Un mensaje de error", 30);
    } catch(Exception $e) {
        echo "El código de excepción es: " . $e->getCode();
    }
    ?>

Resultado del ejemplo anterior es similar a:

    El código de excepción es: 30

### Ver también

- Throwable::getCode() - Obtener el código de la excepción

# Exception::getFile

(PHP 5, PHP 7, PHP 8)

Exception::getFile — Obtiene el fichero en el que se creó la excepción

### Descripción

final public function Exception::getFile(): string

Obtiene el nombre del fichero en el que fue creada la excepción.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el nombre del fichero en donde fue creada la excepción.

### Ejemplos

Ejemplo #1 Ejemplo de Exception::getFile()

    <?php
    try {
        throw new Exception;
    } catch(Exception $e) {
        echo $e->getFile();
    }
    ?>

Resultado del ejemplo anterior es similar a:

    /home/bjori/tmp/ex.php

### Ver también

- Throwable::getFile() - Obtiene el fichero en el que se creó el objeto

# Exception::getLine

(PHP 5, PHP 7, PHP 8)

Exception::getLine — Obtiene la línea en el que se creó la excepción

### Descripción

final public function Exception::getLine(): int

Devuelve el número de la línea donde se creó la excepción.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de la línea donde se creó la excepción.

### Ejemplos

Ejemplo #1 Ejemplo de Exception::getLine()

    <?php
    try {
        throw new Exception("Algún mensaje de error");
    } catch(Exception $e) {
        echo "La excepción se creó en la línea: " . $e->getLine();
    }
    ?>

Resultado del ejemplo anterior es similar a:

    La excepción se creó en la línea: 3

### Ver también

- Throwable::getLine() - Obtiene la línea en la que el objeto fue instanciado

# Exception::getTrace

(PHP 5, PHP 7, PHP 8)

Exception::getTrace — Obtiene la traza de la pila

### Descripción

final public function Exception::getTrace(): array

Devuelve la traza de pila de una excepción.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el seguimiento de pila de una excepción como un array.

### Ejemplos

Ejemplo #1 Ejemplo de Exception::getTrace()

    <?php
    function test() {
     throw new Exception;
    }

    try {
     test();
    } catch(Exception $e) {
     var_dump($e->getTrace());
    }
    ?>

Resultado del ejemplo anterior es similar a:

    array(1) {
      [0]=>
      array(4) {
        ["file"]=>
        string(22) "/home/bjori/tmp/ex.php"
        ["line"]=>
        int(7)
        ["function"]=>
        string(4) "test"
        ["args"]=>
        array(0) {
        }
      }
    }

### Ver también

- Throwable::getTrace() - Obtener la traza de la pila

# Exception::getTraceAsString

(PHP 5, PHP 7, PHP 8)

Exception::getTraceAsString — Obtiene la traza de la pila como una cadena de caracteres

### Descripción

final public function Exception::getTraceAsString(): string

Devuelve la traza de la pila de una excepción como una cadena de caracteres.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la traza de la pila de la excepción como una cadena de caracteres.

### Ejemplos

Ejemplo #1 Ejemplo de Exception::getTraceAsString()

    <?php
    function test() {
        throw new Exception;
    }

    try {
        test();
    } catch(Exception $e) {
        echo $e->getTraceAsString();
    }
    ?>

Resultado del ejemplo anterior es similar a:

    #0 /home/bjori/tmp/ex.php(7): test()
    #1 {main}

### Ver también

- Throwable::getTraceAsString() - Obtener la traza de la pila como un string

# Exception::__toString

(PHP 5, PHP 7, PHP 8)

Exception::__toString — Representación de la excepción en formato cadena

### Descripción

public function Exception::__toString(): string

Devuelve la representación de la excepción en formato string.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la representación de la excepción en formato string.

### Ejemplos

Ejemplo #1 Ejemplo de Exception::__toString()

    <?php
    try {
        throw new Exception("Some error message");
    } catch(Exception $e) {
        echo $e;
    }
    ?>

Resultado del ejemplo anterior es similar a:

    exception 'Exception' with message 'Some error message' in /home/bjori/tmp/ex.php:3
    Stack trace:
    #0 {main}

### Ver también

- Throwable::__toString() - Obtiene un representación de string del objeto lanzado

# Exception::__clone

(PHP 5, PHP 7, PHP 8)

Exception::__clone — Clona la excepción

### Descripción

private function Exception::__clone(): void

Exceptions no se pueden clonar, y el intento de hacerlo lanzará un Error.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

Las Excepciones no se pueden clonar.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Error::__clone() ya no es final.

## Tabla de contenidos

- Exception::__construct — Constructor de la excepción
- Exception::getMessage — Obtiene el mensaje de Excepción
- Exception::getPrevious — Devuelve la Throwable anterior
- Exception::getCode — Obtiene el código de una excepción
- Exception::getFile — Obtiene el fichero en el que se creó la excepción
- Exception::getLine — Obtiene la línea en el que se creó la excepción
- Exception::getTrace — Obtiene la traza de la pila
- Exception::getTraceAsString — Obtiene la traza de la pila como una cadena de caracteres
- Exception::__toString — Representación de la excepción en formato cadena
- Exception::__clone — Clona la excepción

# ErrorException

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## Introducción

Una excepción para los errores.

## Sinopsis de la Clase

class ErrorException extends Exception {
/* Propiedades */
protected int $severity = E_ERROR;
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
public function __construct(
string `$message` = "",
int `$code` = 0,
int `$severity` = `E_ERROR`,
?string `$filename` = `null`,
?int `$line` = `null`,
?Throwable `$previous` = `null`
)
final public function getSeverity(): int
/* Métodos heredados */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propiedades

severity

  La severidad de la excepción

## Ejemplos

Ejemplo #1 Uso de set_error_handler() para cambiar todos los mensajes de error en ErrorException

    <?php

    set_error_handler(function (int $errno, string $errstr, string $errfile, int $errline) {
        if (!(error_reporting() & $errno)) {
            // Este código de error no está incluido en error_reporting.
            return;
        }

        if ($errno === E_DEPRECATED || $errno === E_USER_DEPRECATED) {
            // No lanzar excepción para advertencias de obsolescencia, ya que nuevas o inesperadas
            // obsolescencias podrían romper la aplicación.
            return;
        }

        throw new \ErrorException($errstr, 0, $errno, $errfile, $errline);
    });

    // Deserializar datos corruptos desencadena una advertencia que será convertida en
    // ErrorException por el manejador de errores.
    unserialize('broken data');

    ?>

Resultado del ejemplo anterior es similar a:

    Fatal error: Uncaught ErrorException: unserialize(): Error at offset 0 of 11 bytes in test.php:16
    Stack trace:
    #0 [internal function]: {closure}(2, 'unserialize(): ...', 'test.php', 16)
    #1 test.php(16): unserialize('broken data')
    #2 {main}
      thrown in test.php on line 16

# ErrorException::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ErrorException::__construct — Constructor de la excepción

### Descripción

public function ErrorException::__construct(
string `$message` = "",
int `$code` = 0,
int `$severity` = `E_ERROR`,
?string `$filename` = `null`,
?int `$line` = `null`,
?Throwable `$previous` = `null`
)

Construye el objeto Exception.

### Parámetros

`message`

  Mensaje de la excepción a lanzar.

`code`

  El código de la excepción.

`severity`

  Nivel de la severidad de la excepción.

  > Nota:

  > Aunque la severidad puede ser cuaquier valor de tipo int, se pretende que se empleen las constantes de error.

`filename`

  Nombre del fichero donde se lanzó la excepción.

`line`

  Número de la línea donde se produjo la excepción.

`previous`

  La anterior excepción utilizada para la excepción de encadenamiento.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `filename` y `line` ahora son anulables. Anteriormente, sus valores predeterminados eran `__FILE__` y `__LINE__`, respectivamente.

# ErrorException::getSeverity

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ErrorException::getSeverity — Obtiene la severidad de la excepción

### Descripción

final public function ErrorException::getSeverity(): int

Devuelve la severidad de la excepción.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el nivel de la severidad de la excepción.

### Ejemplos

Ejemplo #1 Ejemplo de ErrorException::getSeverity()

    <?php
    try {
        throw new ErrorException("Mensaje de la excepción", 0, E_USER_ERROR);
    } catch(ErrorException $e) {
        echo "La severidad de la excepción es: " . $e->getSeverity();
        var_dump($e->getSeverity() === E_USER_ERROR);
    }
    ?>

Resultado del ejemplo anterior es similar a:

    La severidad de la excepción es: 256
    bool(true)

## Tabla de contenidos

- ErrorException::__construct — Constructor de la excepción
- ErrorException::getSeverity — Obtiene la severidad de la excepción

# La clase ClosedGeneratorException

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introducción

Una ClosedGeneratorException es lanzada cuando se intenta recuperar un valor de un Generator cerrado.

## Sinopsis de la Clase

class ClosedGeneratorException extends Exception {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Error

(PHP 7, PHP 8)

## Introducción

Error es la clase base para todos los errores de PHP internos.

## Sinopsis de la Clase

class Error implements Throwable {
/* Propiedades */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
public function __construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function getMessage(): string
final public function getPrevious(): ?Throwable
final public function getCode(): int
final public function getFile(): string
final public function getLine(): int
final public function getTrace(): array
final public function getTraceAsString(): string
public function __toString(): string
private function __clone(): void
}

## Propiedades

message

  El mensaje de error

code

  El código de error

file

  El nombre del fichero donde ocurrió el error

line

  La línea donde ocurrió el error

previous

  La excepción lanzada previamente

string

  La representación en cadena del seguimiento de la pila

trace

  El seguimiento de la pila como array

# Error::__construct

(PHP 7, PHP 8)

Error::__construct — Construir el objeto error

### Descripción

public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)

Construye el Error.

### Parámetros

`message`

  El mensaje de error.

`code`

  El código de error.

`previous`

  El objeto Throwable anterior empleado para la cadena de excepciones.

### Notas

> Nota:

> El parámetro `message` NO es seguro a nivel binario.

# Error::getMessage

(PHP 7, PHP 8)

Error::getMessage — Obtener el mensaje de error

### Descripción

final public function Error::getMessage(): string

Devuelve el mensaje de error.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el mensaje de error como una cadena.

### Ejemplos

Ejemplo #1 Ejemplo de Error::getMessage()

    <?php
    try {
        throw new Error("Un mensaje de error");
    } catch(Error $e) {
        echo $e->getMessage();
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Un mensaje de error

### Ver también

- Throwable::getMessage() - Obtiene el mensaje

# Error::getPrevious

(PHP 7, PHP 8)

Error::getPrevious — Devuelve el objeto Throwable anterior

### Descripción

final public function Error::getPrevious(): ?Throwable

Devuelve el objeto Throwable anterior (el tercer parámetro de Error::__construct()).

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el objeto Throwable anterior si está disponible, o `null` en caso contrario.

### Ejemplos

Ejemplo #1 Ejemplo de Error::getPrevious()

Recorrer e imprimir la traza de errores.

    <?php
    class MiErrorPersonalizado extends Error {}

    function hacerCosas() {
        try {
            throw new InvalidArgumentError("¡Lo está haciendo mal!", 112);
        } catch(Error $e) {
            throw new MiErrorPersonalizado("Ocurrió algo", 911, $e);
        }
    }

    try {
        hacerCosas();
    } catch(Error $e) {
        do {
            printf("%s:%d %s (%d) [%s]\n", $e->getFile(), $e->getLine(), $e->getMessage(), $e->getCode(), get_class($e));
        } while($e = $e->getPrevious());
    }
    ?>

Resultado del ejemplo anterior es similar a:

    /home/bjori/ex.php:8 Ocurrió algo (911) [MiErrorPersonalizado]
    /home/bjori/ex.php:6 ¡Lo está haciendo mal! (112) [InvalidArgumentError]

### Ver también

- Throwable::getPrevious() - Devuelve el objeto Throwable previo

# Error::getCode

(PHP 7, PHP 8)

Error::getCode — Obtener el código de error

### Descripción

final public function Error::getCode(): int

Devuelve el código de error.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el código de error como un int

### Ejemplos

Ejemplo #1 Ejemplo de Error::getCode()

    <?php
    try {
        throw new Error("Un mensaje de error", 30);
    } catch(Error $e) {
        echo "El código del Error es: " . $e->getCode();
    }
    ?>

Resultado del ejemplo anterior es similar a:

    El código del Error es: 30

### Ver también

- Throwable::getCode() - Obtener el código de la excepción

# Error::getFile

(PHP 7, PHP 8)

Error::getFile — Obtener el fichero en el que ocurrío el error

### Descripción

final public function Error::getFile(): string

Obtiene el nombre del fichero donde ocurrió el error.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el nombre del fichero el en cual ocurrió el error.

### Ejemplos

Ejemplo #1 Ejemplo de Error::getFile()

    <?php
    try {
        throw new Error;
    } catch(Error $e) {
        echo $e->getFile();
    }
    ?>

Resultado del ejemplo anterior es similar a:

    /home/bjori/tmp/ex.php

### Ver también

- Throwable::getFile() - Obtiene el fichero en el que se creó el objeto

# Error::getLine

(PHP 7, PHP 8)

Error::getLine — Obtener la línea en la que ocurrió el error

### Descripción

final public function Error::getLine(): int

Obtiene el número de línea donde ocurrió el error.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de línea en la que ocurrió el error.

### Ejemplos

Ejemplo #1 Ejemplo de Error::getLine()

    <?php
    try {
        throw new Error("Un mensaje de error");
    } catch(Error $e) {
        echo "El error se ocasionó en la línea: " . $e->getLine();
    }
    ?>

Resultado del ejemplo anterior es similar a:

    El error se ocasionó en la línea: 3

### Ver también

- Throwable::getLine() - Obtiene la línea en la que el objeto fue instanciado

# Error::getTrace

(PHP 7, PHP 8)

Error::getTrace — Obtener la traza de la pila

### Descripción

final public function Error::getTrace(): array

Devuelve la traza de la pila.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la traza de la pila como un array.

### Ejemplos

Ejemplo #1 Ejemplo de Error::getTrace()

    <?php
    function prueba() {
     throw new Error;
    }

    try {
     prueba();
    } catch(Error $e) {
     var_dump($e->getTrace());
    }
    ?>

Resultado del ejemplo anterior es similar a:

    array(1) {
      [0]=>
      array(4) {
        ["file"]=>
        string(22) "/home/bjori/tmp/ex.php"
        ["line"]=>
        int(7)
        ["function"]=>
        string(6) "prueba"
        ["args"]=>
        array(0) {
        }
      }
    }

### Ver también

- Throwable::getTrace() - Obtener la traza de la pila

# Error::getTraceAsString

(PHP 7, PHP 8)

Error::getTraceAsString — Obtener la traza de la pila como un string

### Descripción

final public function Error::getTraceAsString(): string

Devuelve la traza de la pila como un string.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la traza de la pila como un string.

### Ejemplos

Ejemplo #1 Ejemplo de Error::getTraceAsString()

    <?php
    function prueba() {
        throw new Error;
    }

    try {
        prueba();
    } catch(Error $e) {
        echo $e->getTraceAsString();
    }
    ?>

Resultado del ejemplo anterior es similar a:

    #0 /home/bjori/tmp/ex.php(7): prueba()
    #1 {main}

### Ver también

- Throwable::getTraceAsString() - Obtener la traza de la pila como un string

# Error::__toString

(PHP 7, PHP 8)

Error::__toString — Representación de string del error

### Descripción

public function Error::__toString(): string

Devuelve la representación de string del error.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la representación de string del error.

### Ejemplos

Ejemplo #1 Ejemplo de Error::__toString()

    <?php
    try {
        throw new Error("Un mensaje de error");
    } catch(Error $e) {
        echo $e;
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Error: Un mensaje de error in /home/bjori/tmp/ex.php:3
    Stack trace:
    #0 {main}

### Ver también

- Throwable::__toString() - Obtiene un representación de string del objeto lanzado

# Error::__clone

(PHP 7, PHP 8)

Error::__clone — Clonar el error

### Descripción

private function Error::__clone(): void

Un error no se pueden clonar, por lo que este método resulta en un error fatal.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

Los errores no son clonabes.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Error::__clone() ya no es final.

## Tabla de contenidos

- Error::__construct — Construir el objeto error
- Error::getMessage — Obtener el mensaje de error
- Error::getPrevious — Devuelve el objeto Throwable anterior
- Error::getCode — Obtener el código de error
- Error::getFile — Obtener el fichero en el que ocurrío el error
- Error::getLine — Obtener la línea en la que ocurrió el error
- Error::getTrace — Obtener la traza de la pila
- Error::getTraceAsString — Obtener la traza de la pila como un string
- Error::__toString — Representación de string del error
- Error::__clone — Clonar el error

# ArgumentCountError

(PHP 7 >= PHP 7.1.0, PHP 8)

## Introducción

ArgumentCountError es lanzado cuando muy pocos argumentos son pasados a una funcion o método definido por el usuario.

Este error también se produce cuando se pasan demasiados argumentos a una función incorporada función incorporada no variable.

## Sinopsis de la Clase

class ArgumentCountError extends TypeError {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# ArithmeticError

(PHP 7, PHP 8)

## Introducción

Un ArithmeticError es lanzado cuando ocurre un error durante la realización de operaciones matemáticas. Estos errores incluyen el intento de realizar un desplazamiento de bit mediante una cantidad negativa, y cualquier llamada a intdiv() que resulte en un valor fuera de los límites posibles de un int.

## Sinopsis de la Clase

class ArithmeticError extends Error {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# AssertionError

(PHP 7, PHP 8)

## Introducción

Un AssertionError se lanza cuando falla una afirmación realizada mediante assert().

## Sinopsis de la Clase

class AssertionError extends Error {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# DivisionByZeroError

(PHP 7, PHP 8)

## Introducción

Un DivisionByZeroError se lanza al intentar dividir un número por cero.

## Sinopsis de la Clase

class DivisionByZeroError extends ArithmeticError {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# CompileError

(PHP 7 > 7.3.0, PHP 8)

## Introducción

CompileError es lanzado por algunos errores de compilación, que anteriormente emitió un error fatal.

## Sinopsis de la Clase

class CompileError extends Error {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# ParseError

(PHP 7, PHP 8)

## Introducción

Un ParseError se lanza cuando ocurre un error al analizar código de PHP, tal como cuando se llama a eval().

> Nota: ParseError extiende CompileError a partir de PHP 7.3.0. Anteriormente, extendía Error.

## Sinopsis de la Clase

class ParseError extends CompileError {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# TypeError

(PHP 7, PHP 8)

## Introducción

Una TypeError puede ser lanzada cuando:

- El valor que se define para una propiedad de clase no corresponde al tipo declarado de la propiedad correspondiente.
- El tipo del argumento que se pasa a la función no corresponde a la declaración del tipo del parámetro correspondiente.
- Un valor que es devuelto por una función no corresponde al tipo de retorno declarado por la función.

## Sinopsis de la Clase

class TypeError extends Error {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

## Historial de cambios

Versión | Descripción
--- | ---
7.1.0 | En modo estricto, pasar un número incorrecto de argumentos a una función interna de PHP ya no lanza una TypeError genérica. En su lugar, se lanza una ArgumentCountError más específica, que extiende TypeError.

# ValueError

(PHP 8)

## Introducción

Una ValueError se lanza cuando el tipo de un argumento es correcto pero su valor es incorrecto. Por ejemplo, si se pasa un entero negativo cuando la función espera un entero positivo, o si se pasa una cadena o un array vacío cuando la función espera que no esté vacío.

## Sinopsis de la Clase

class ValueError extends Error {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# UnhandledMatchError

(PHP 8)

## Introducción

Una UnhandledMatchError es lanzada cuando el sujeto transmitido a una expresión match no es tratado por ningún brazo de esta misma expresión.

## Sinopsis de la Clase

class UnhandledMatchError extends Error {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# FiberError

(PHP 8 >= 8.1.0)

## Introducción

El error FiberError se lanza cuando se realiza una operación no válida en una fibra (Fiber).

## Sinopsis de la Clase

final class FiberError extends Error {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
public function __construct()
/* Métodos heredados */
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# FiberError::__construct

(PHP 8 >= 8.1.0)

FiberError::__construct — Constructor para evitar la instanciación directa

### Descripción

public function FiberError::__construct()

### Parámetros

Esta función no contiene ningún parámetro.

### Errores/Excepciones

Lanza una excepción Error cuando es llamada.

## Tabla de contenidos

- FiberError::__construct — Constructor para evitar la instanciación directa

# RequestParseBodyException

(PHP 8 >= 8.4.0)

## Introducción

Una RequestParseBodyException es lanzada en request_parse_body() cuando el cuerpo de la petición es inválido, según la cabecera `Content-Type`.

## Sinopsis de la Clase

class RequestParseBodyException extends Exception {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Interfaces y clases predefinidas

## Tabla de contenidos

- Traversable
- Iterator
- IteratorAggregate
- InternalIterator
- Throwable
- Countable
- ArrayAccess
- Serializable
- Closure
- stdClass
- Generator
- Fiber
- WeakReference
- WeakMap
- Stringable
- UnitEnum
- BackedEnum
- SensitiveParameterValue
- __PHP_Incomplete_Class

Véanse también las interfaces de la SPL y las clases reservadas.

# La interfaz Traversable

(PHP 5, PHP 7, PHP 8)

## Introducción

Interfaz para detectar si una clase puede recorrerse mediante `foreach`.

Una interfaz abstracta base no puede ser implementada sola. En su lugar, debe ser implementada con IteratorAggregate o con Iterator.

## Sinopsis de la Interfaz

interface Traversable {
}

Esta interfaz no tiene métodos, su único propósito es ser la base para todas las clases atravesables.

## Historial de cambios

Versión | Descripción
--- | ---
7.4.0 | La interfaz Traversable ahora puede ser implementada por clases abstractas. Las clases que la extiendan deben implementar Iterator o IteratorAggregate.

## Notas

> Nota:

> Las clases internas que implementan esta interfaz pueden ser usadas en una construcción `foreach` y no necesitan implementar IteratorAggregate o Iterator.

> Nota:

> Antes de PHP 7.4.0, esta interfaz interna del motor no podía ser implementada en scripts PHP. Se debe usar IteratorAggregate o Iterator deben usarse en su lugar.

# La interfaz Iterator

(PHP 5, PHP 7, PHP 8)

## Introducción

Interfaz para iteradores externos u objetos que pueden ser iterados internamente por sí mismos.

## Sinopsis de la Interfaz

interface Iterator extends Traversable {
/* Métodos */
public function current(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function valid(): bool
}

## Iteradores Predefinidos

PHP ya ofrece un número de iteradores para muchas de las tareas del día a día. Véase la lista de iteradores SPL.

## Ejemplos

Ejemplo #1 Uso básico

Este ejemplo muestra el orden en el que se llaman a los métodos cuando se emplea un `foreach` con un iterator.

    <?php
    class myIterator implements Iterator {
        private $position = 0;
        private $array = array(
            "firstelement",
            "secondelement",
            "lastelement",
        );

        public function __construct() {
            $this->position = 0;
        }

        public function rewind(): void {
            var_dump(__METHOD__);
            $this->position = 0;
        }

        #[\ReturnTypeWillChange]
        public function current() {
            var_dump(__METHOD__);
            return $this->array[$this->position];
        }

        #[\ReturnTypeWillChange]
        public function key() {
            var_dump(__METHOD__);
            return $this->position;
        }

        public function next(): void {
            var_dump(__METHOD__);
            ++$this->position;
        }

        public function valid(): bool {
            var_dump(__METHOD__);
            return isset($this->array[$this->position]);
        }
    }

    $it = new myIterator;

    foreach($it as $key => $value) {
        var_dump($key, $value);
        echo "\n";
    }
    ?>

Resultado del ejemplo anterior es similar a:

    string(18) "myIterator::rewind"
    string(17) "myIterator::valid"
    string(19) "myIterator::current"
    string(15) "myIterator::key"
    int(0)
    string(12) "firstelement"

    string(16) "myIterator::next"
    string(17) "myIterator::valid"
    string(19) "myIterator::current"
    string(15) "myIterator::key"
    int(1)
    string(13) "secondelement"

    string(16) "myIterator::next"
    string(17) "myIterator::valid"
    string(19) "myIterator::current"
    string(15) "myIterator::key"
    int(2)
    string(11) "lastelement"

    string(16) "myIterator::next"
    string(17) "myIterator::valid"

## Ver también

Véase también iteración de objetos.

# Iterator::current

(PHP 5, PHP 7, PHP 8)

Iterator::current — Devuelve el elemento actual

### Descripción

public function Iterator::current(): mixed

Devuelve el elemento actual.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Puede devolver cualquier tipo.

# Iterator::key

(PHP 5, PHP 7, PHP 8)

Iterator::key — Devuelve la clave del elemento actual

### Descripción

public function Iterator::key(): mixed

Devuelve la clave del elemento actual.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve scalar en caso de éxito, o `null` en caso de error.

### Errores/Excepciones

Muestra un `E_NOTICE` en caso de error.

# Iterator::next

(PHP 5, PHP 7, PHP 8)

Iterator::next — Avanza al siguiente elemento

### Descripción

public function Iterator::next(): void

Avanza la posición actual al siguiente elemento.

> Nota:

> El método es llamado después de cada `foreach` loop.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El valor devuelto es ignorado.

# Iterator::rewind

(PHP 5, PHP 7, PHP 8)

Iterator::rewind — Rebobine la Iterator al primer elemento

### Descripción

public function Iterator::rewind(): void

Rebobina de nuevo al primer elemento de la Iterator.

> Nota:

> Este es el primer método llamado cuando se inicia un `foreach` bucle. No va a ser ejecutado despues `foreach` bucle.

> Como `foreach` siempre llama a rewind() antes de iniciar la iteración, avanzar manualmente la posición del iterador (por ejemplo mediante SplFileObject::seek()) será reiniciado. Para iterar sin rebobinar el iterador, envuélvalo en un NoRewindIterator.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Cualquier valor devuelto se pasa por alto.

# Iterator::valid

(PHP 5, PHP 7, PHP 8)

Iterator::valid — Comprueba si la posición actual es válido

### Descripción

public function Iterator::valid(): bool

Este método se llama después de Iterator::rewind() y Iterator::next() para comprobar si la posición actual es válido.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El valor de retorno se debe fundir a bool y luego evaluar. Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

## Tabla de contenidos

- Iterator::current — Devuelve el elemento actual
- Iterator::key — Devuelve la clave del elemento actual
- Iterator::next — Avanza al siguiente elemento
- Iterator::rewind — Rebobine la Iterator al primer elemento
- Iterator::valid — Comprueba si la posición actual es válido

# La interfaz IteratorAggregate

(PHP 5, PHP 7, PHP 8)

## Introducción

Interfaz para crear un iterador externo.

## Sinopsis de la Interfaz

interface IteratorAggregate extends Traversable {
/* Métodos */
public function getIterator(): Traversable
}

## Ejemplos

Ejemplo #1 Ejemplo simple

    <?php

    class myData implements IteratorAggregate
    {
        public function getIterator(): Traversable
        {
            return new ArrayIterator([
                "clave uno" => "elemento uno",
                "clave dos" => "elemento dos",
                "clave tres" => "elemento tres"
            ]);
        }
    }

    $obj = new myData();

    foreach($obj as $key => $value) {
        var_dump($key, $value);
        echo "\n";
    }

Resultado del ejemplo anterior es similar a:

    string(9) "clave uno"
    string(12) "elemento uno"

    string(9) "clave dos"
    string(12) "elemento dos"

    string(10) "clave tres"
    string(13) "elemento tres"

# IteratorAggregate::getIterator

(PHP 5, PHP 7, PHP 8)

IteratorAggregate::getIterator — Recuperar un Iterator o traversable externo

### Descripción

public function IteratorAggregate::getIterator(): Traversable

Devuelve un iterador o traversable externo.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Una instancia de un objeto que implementa Iterator o Traversable

### Errores/Excepciones

Lanza una Exception en caso de fallo.

## Tabla de contenidos

- IteratorAggregate::getIterator — Recuperar un Iterator o traversable externo

# La clase InternalIterator

(PHP 8)

## Introducción

Clase que facilita la implementación de IteratorAggregate para las clases internas.

## Sinopsis de la Clase

final class InternalIterator implements Iterator {
/* Métodos */
private function __construct()
public function current(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function valid(): bool
}

# InternalIterator::__construct

(PHP 8)

InternalIterator::__construct — Constructor privado para evitar la instanciación directa

### Descripción

private function InternalIterator::__construct()

### Parámetros

Esta función no contiene ningún parámetro.

# InternalIterator::current

(PHP 8)

InternalIterator::current — Devuelve el elemento actual

### Descripción

public function InternalIterator::current(): mixed

Devuelve el elemento actual.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el elemento actual.

# InternalIterator::key

(PHP 8)

InternalIterator::key — Devuelve la clave del elemento actual

### Descripción

public function InternalIterator::key(): mixed

Devuelve la clave del elemento actual.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la clave del elemento actual.

# InternalIterator::next

(PHP 8)

InternalIterator::next — Pasa al elemento siguiente

### Descripción

public function InternalIterator::next(): void

Desplaza la posición actual hacia el elemento siguiente.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

# InternalIterator::rewind

(PHP 8)

InternalIterator::rewind — Reemplaza el iterador en el primer elemento

### Descripción

public function InternalIterator::rewind(): void

Reemplaza el iterador en el primer elemento.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

# InternalIterator::valid

(PHP 8)

InternalIterator::valid — Verifica si la posición actual es válida

### Descripción

public function InternalIterator::valid(): bool

Verifica que la posición actual es válida.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve si la posición actual es válida.

## Tabla de contenidos

- InternalIterator::__construct — Constructor privado para evitar la instanciación directa
- InternalIterator::current — Devuelve el elemento actual
- InternalIterator::key — Devuelve la clave del elemento actual
- InternalIterator::next — Pasa al elemento siguiente
- InternalIterator::rewind — Reemplaza el iterador en el primer elemento
- InternalIterator::valid — Verifica si la posición actual es válida

# Throwable

(PHP 7, PHP 8)

## Introducción

Throwable es la interfaz base para cualquier objeto que pueda ser lanzado mediante una sentencia `throw`, incluyendo Error y Exception.

> Nota:

> Las clases de PHP no pueden implementar la interfaz Throwable directamente, por lo que deben extender en su lugar Exception.

## Sinopsis de la Interfaz

interface Throwable extends Stringable {
/* Métodos */
public function getMessage(): string
public function getCode(): int
public function getFile(): string
public function getLine(): int
public function getTrace(): array
public function getTraceAsString(): string
public function getPrevious(): ?Throwable
public function __toString(): string
/* Métodos heredados */
public function Stringable::__toString(): string
}

## Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Throwable implementa Stringable ahora.

# Throwable::getMessage

(PHP 7, PHP 8)

Throwable::getMessage — Obtiene el mensaje

### Descripción

public function Throwable::getMessage(): string

Devuelve el mensaje asociado al objeto lanzado.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el mensaje asociado al objeto lanzado.

### Ver también

- Exception::getMessage() - Obtiene el mensaje de Excepción

# Throwable::getCode

(PHP 7, PHP 8)

Throwable::getCode — Obtener el código de la excepción

### Descripción

public function Throwable::getCode(): int

Devuelve el código de error asociado al objeto lanzado.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el código de la excepción como un int en Exception, aunque posiblemente como otro tipo en los descendientes de Exception (por ejemplo, como string en PDOException).

### Ver también

- Exception::getCode() - Obtiene el código de una excepción

# Throwable::getFile

(PHP 7, PHP 8)

Throwable::getFile — Obtiene el fichero en el que se creó el objeto

### Descripción

public function Throwable::getFile(): string

Obtiene el nombre del fichero en el que se creó el objeto lanzado.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el nombre del fichero en el que se creó la el objeto lanzado.

### Ver también

- Exception::getFile() - Obtiene el fichero en el que se creó la excepción

# Throwable::getLine

(PHP 7, PHP 8)

Throwable::getLine — Obtiene la línea en la que el objeto fue instanciado

### Descripción

public function Throwable::getLine(): int

Devuelve el número de línea en la que el objeto fue instanciado.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de línea en la que el objeto fue instanciado.

### Ver también

- Exception::getLine() - Obtiene la línea en el que se creó la excepción

# Throwable::getTrace

(PHP 7, PHP 8)

Throwable::getTrace — Obtener la traza de la pila

### Descripción

public function Throwable::getTrace(): array

Devuelve la traza de la pila como un array.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la traza de la pila como un array con el mismo formato que en debug_backtrace().

### Ver también

- Exception::getTrace() - Obtiene la traza de la pila

# Throwable::getTraceAsString

(PHP 7, PHP 8)

Throwable::getTraceAsString — Obtener la traza de la pila como un string

### Descripción

public function Throwable::getTraceAsString(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la traza de la pila como un string.

### Ver también

- Exception::getTraceAsString() - Obtiene la traza de la pila como una cadena de caracteres

# Throwable::getPrevious

(PHP 7, PHP 8)

Throwable::getPrevious — Devuelve el objeto Throwable previo

### Descripción

public function Throwable::getPrevious(): ?Throwable

Devuelve el objeto Throwable previo (por ejemplo, uno proporcionado como tercer parámetro de Exception::__construct()).

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el objeto Throwable anterior si está disponible, o `null` si no lo está.

### Ver también

- Exception::getPrevious() - Devuelve la Throwable anterior

# Throwable::__toString

(PHP 7, PHP 8)

Throwable::__toString — Obtiene un representación de string del objeto lanzado

### Descripción

public function Throwable::__toString(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la representación de string del objeto lanzado.

### Ver también

- Exception::__toString() - Representación de la excepción en formato cadena

## Tabla de contenidos

- Throwable::getMessage — Obtiene el mensaje
- Throwable::getCode — Obtener el código de la excepción
- Throwable::getFile — Obtiene el fichero en el que se creó el objeto
- Throwable::getLine — Obtiene la línea en la que el objeto fue instanciado
- Throwable::getTrace — Obtener la traza de la pila
- Throwable::getTraceAsString — Obtener la traza de la pila como un string
- Throwable::getPrevious — Devuelve el objeto Throwable previo
- Throwable::__toString — Obtiene un representación de string del objeto lanzado

# La interfaz Countable

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## Introducción

Las clases que implementan la interfaz Countable pueden ser utilizadas con la función count().

## Sinopsis de la Interfaz

interface Countable {
/* Métodos */
public function count(): int
}

# Countable::count

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Countable::count — Cuenta el número de elementos de un objeto

### Descripción

public function Countable::count(): int

Este método se ejecuta cuando el `value` para count() es un objeto que implementa Countable.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El número contado, en forma int.

### Ejemplos

Ejemplo #1 Ejemplo con Countable::count()

    <?php

    class Counter implements Countable
    {
        private $count = 0;

        public function count(): int
        {
            return ++$this->count;
        }
    }

    $counter = new Counter;

    for ($i = 0; $i < 10; ++$i) {
        echo "He sido contado " . count($counter) . " veces\n";
    }

    ?>

Resultado del ejemplo anterior es similar a:

    He sido contado 1 veces
    He sido contado 2 veces
    He sido contado 3 veces
    He sido contado 4 veces
    He sido contado 5 veces
    He sido contado 6 veces
    He sido contado 7 veces
    He sido contado 8 veces
    He sido contado 9 veces
    He sido contado 10 veces

## Tabla de contenidos

- Countable::count — Cuenta el número de elementos de un objeto

# La interfaz ArrayAccess

(PHP 5, PHP 7, PHP 8)

## Introducción

Interfaz que permite acceder a los objetos de la misma manera que a los arrays.

## Sinopsis de la Interfaz

interface ArrayAccess {
/* Métodos */
public function offsetExists(mixed `$offset`): bool
public function offsetGet(mixed `$offset`): mixed
public function offsetSet(mixed `$offset`, mixed `$value`): void
public function offsetUnset(mixed `$offset`): void
}

## Ejemplos

Ejemplo #1 Ejemplo básico

    <?php
    class Obj implements ArrayAccess {
        public $container = [
            "one"   => 1,
            "two"   => 2,
            "three" => 3,
        ];

        public function offsetSet($offset, $value): void {
            if (is_null($offset)) {
                $this->container[] = $value;
            } else {
                $this->container[$offset] = $value;
            }
        }

        public function offsetExists($offset): bool {
            return isset($this->container[$offset]);
        }

        public function offsetUnset($offset): void {
            unset($this->container[$offset]);
        }

        public function offsetGet($offset): mixed {
            return isset($this->container[$offset]) ? $this->container[$offset] : null;
        }
    }

    $obj = new Obj;

    var_dump(isset($obj["dos"]));
    var_dump($obj["dos"]);
    unset($obj["dos"]);
    var_dump(isset($obj["dos"]));
    $obj["dos"] = "Un valor";
    var_dump($obj["dos"]);
    $obj[] = 'Añadido 1';
    $obj[] = 'Añadido 2';
    $obj[] = 'Añadido 3';
    print_r($obj);

Resultado del ejemplo anterior es similar a:

    bool(true)
    int(2)
    bool(false)
    string(9) "Un valor"
    Obj Object
    (
        [container] => Array
            (
                [uno] => 1
                [tres] => 3
                [dos] => Un valor
                [0] => Añadido 1
                [1] => Añadido 2
                [2] => Añadido 3
            )

    )

# ArrayAccess::offsetExists

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetExists — Comprobar si existe un índice

### Descripción

public function ArrayAccess::offsetExists(mixed `$offset`): bool

Comprueba si existe o no un índice.

Este método se ejecuta cuando se utilizan las funciones isset() o empty() sobre los objetos que implementan ArrayAccess.

> Nota:

> Cuando se utiliza empty(), ArrayAccess::offsetGet() será invocada para comprobar si está vacío solamente si ArrayAccess::offsetExists() devuelve `true`.

### Parámetros

`offset`

  El índice a comprobar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

> Nota:

> El valor de retorno se debe convertir a bool si no devuelve un valor boleano.

### Ejemplos

Ejemplo #1 Ejemplo de ArrayAccess::offsetExists()

    <?php
    class obj implements ArrayAccess {
        public function offsetSet($offset, $value): void {
            var_dump(__METHOD__);
        }
        public function offsetExists($var): bool {
            var_dump(__METHOD__);
            if ($var == "foobar") {
                return true;
            }
            return false;
        }
        public function offsetUnset($var): void {
            var_dump(__METHOD__);
        }
        #[\ReturnTypeWillChange]
        public function offsetGet($var) {
            var_dump(__METHOD__);
            return "value";
        }
    }

    $obj = new obj;

    echo "Runs obj::offsetExists()\n";
    var_dump(isset($obj["foobar"]));

    echo "\nRuns obj::offsetExists() and obj::offsetGet()\n";
    var_dump(empty($obj["foobar"]));

    echo "\nRuns obj::offsetExists(), *not* obj:offsetGet() as there is nothing to get\n";
    var_dump(empty($obj["foobaz"]));
    ?>

Resultado del ejemplo anterior es similar a:

    Runs obj::offsetExists()
    string(17) "obj::offsetExists"
    bool(true)

    Runs obj::offsetExists() and obj::offsetGet()
    string(17) "obj::offsetExists"
    string(14) "obj::offsetGet"
    bool(false)

    Runs obj::offsetExists(), *not* obj:offsetGet() as there is nothing to get
    string(17) "obj::offsetExists"
    bool(true)

# ArrayAccess::offsetGet

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetGet — Offset para recuperar

### Descripción

public function ArrayAccess::offsetGet(mixed `$offset`): mixed

Devuelve el valor correspondiente a desplazamiento especificado.

Este método se ejecuta para comprobar si el desplazamiento es empty().

### Parámetros

`offset`

  El desplazamiento va a recuperar.

### Valores devueltos

Puede devolver todos los tipos de valor.

### Notas

> Nota:

> Es posible para las implementaciones de este método para devolver por referencia. Esto hace que las modificaciones indirectas a las dimensiones de los arreglos sobrecargados de objetos ArrayAccess posibles.

> Una modificación directa es aquella que reemplaza completamente el valor de la dimensión de el arreglo, como en `$obj[6] = 7`. Una modificación indirecta, por el contrario, sólo una parte los cambios de la dimensión, o los intentos de asignar la dimensión en función de otra variable, como en `$obj[6][7] = 7` o `$var =& $obj[6]`. Con incrementos `++` y disminye con `--` también se aplican de una manera que requiere la modificación indirecta.

> Si bien la modificación directa desencadena una llamada a ArrayAccess::offsetSet(), modificación indirecta provoca una llamada a ArrayAccess::offsetGet(). En ese caso, la aplicación de ArrayAccess::offsetGet() debe ser capaz de volver por la referencia, de lo contrario un `E_NOTICE` mensaje es elevado..

### Ver también

- ArrayAccess::offsetExists() - Comprobar si existe un índice

# ArrayAccess::offsetSet

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetSet — Asignar un valor al índice esepecificado

### Descripción

public function ArrayAccess::offsetSet(mixed `$offset`, mixed `$value`): void

Asigna un valor a un offset determinado.

### Parámetros

`offset`

  El offset al que se asigna el valor.

`value`

  El valor a asignar.

### Valores devueltos

No se retorna ningún valor.

### Notas

> Nota:

> El parámetro `offset` será inicializado a `null` si otro valor no está disponible, como en el siguiente ejemplo.

>     <?php
>     $arrayaccess[] = "primer valor";
>     $arrayaccess[] = "segundo valor";
>     print_r($arrayaccess);
>     ?>

> El ejemplo anterior mostrará:

>     Array
>     (
>         [0] => primer valor
>         [1] => segundo valor
>     )

> Nota:

> Esta función no es invocada al realizar asignaciones por referencias y por tanto en los cambios de dimensiones en arrays sobrecargados con ArrayAccess (indirecto en el sentido de que no se hace cambiando la dimensión directamente, sino cambiando una sub-dimensión o sub-propiedad o asignando la dimensión del array por referencia en otra variable). En su lugar, se llama a ArrayAccess::offsetGet(). La operación tendrá éxito si devuelve el valor por referencia.

# ArrayAccess::offsetUnset

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetUnset — Destruye un offset

### Descripción

public function ArrayAccess::offsetUnset(mixed `$offset`): void

Destruye un offset.

> Nota:

> Este método no será llamado cuando se fuerza un tipo mediante (unset)

### Parámetros

`offset`

  El offset a destruir.

### Valores devueltos

No se retorna ningún valor.

## Tabla de contenidos

- ArrayAccess::offsetExists — Comprobar si existe un índice
- ArrayAccess::offsetGet — Offset para recuperar
- ArrayAccess::offsetSet — Asignar un valor al índice esepecificado
- ArrayAccess::offsetUnset — Destruye un offset

# La interfaz Serializable

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## Introducción

Interfaz que permite personalizar la serialización.

Las clases que implementan esta interfaz ya no soportan __sleep() y __wakeup(). El método de serialización es llamado cada vez que una instancia debe ser serializada. No llama al método __destruct() y no tiene ningún efecto sobre el contenido de este método. Cuando los datos son serializados, la clase es conocida y el método unserialize() apropiado es llamado como constructor en lugar de llamar a __construct(). Si es necesario llamar al constructor estándar, se puede hacer en el método.

Advertencia

A partir de PHP 8.1.0, una clase que implemente Serializable sin también implementar __serialize() y __unserialize() generará una advertencia de deprecación.

## Sinopsis de la Interfaz

interface Serializable {
/* Métodos */
public function serialize(): ?string
public function unserialize(string `$data`): void
}

## Ejemplos

Ejemplo #1 Ejemplo simple

    <?php
    class obj implements Serializable {
        private $data;
        public function __construct() {
            $this->data = "Mis datos privados";
        }
        public function serialize() {
            return serialize($this->data);
        }
        public function unserialize($data) {
            $this->data = unserialize($data);
        }
        public function getData() {
            return $this->data;
        }
    }

    $obj = new obj;
    $ser = serialize($obj);

    var_dump($ser);

    $newobj = unserialize($ser);

    var_dump($newobj->getData());
    ?>

Resultado del ejemplo anterior es similar a:

    Deprecated: obj implements the Serializable interface, which is deprecated. Implement __serialize() and __unserialize() instead (or in addition, if support for old PHP versions is necessary) in script on line 2
    string(38) "C:3:"obj":23:{s:19:"Mis datos privados";}"
    string(19) "Mis datos privados"

# Serializable::serialize

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Serializable::serialize — Representación en formato cadena de un objeto

### Descripción

public function Serializable::serialize(): ?string

Devuelve la representación de un objeto en formato string.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la representación de un objeto o `null`

### Errores/Excepciones

Lanza una Exception cuando de devuelen otros tipos aparte de string y `null`

### Ver también

- __sleep()
- __serialize()

# Serializable::unserialize

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Serializable::unserialize — Construye el objeto

### Descripción

public function Serializable::unserialize(string `$data`): void

Es llamado durante la unserialización del objeto.

> Nota:

> Este método actua como el constructor del objeto. El método __construct() no será llamado después de este método.

### Parámetros

`data`

  La representación en formato string de un objeto.

### Valores devueltos

El valor devuelto por este método es ignorado.

### Ver también

- __wakeup()
- __unserialize()

## Tabla de contenidos

- Serializable::serialize — Representación en formato cadena de un objeto
- Serializable::unserialize — Construye el objeto

# La clase Closure

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Introducción

Clase utilizada para representar las funciones anónimas.

Las funciones anónimas producen objetos de este tipo. Esta clase tiene métodos que permiten un control adicional de la función anónima después de su creación.

Además de los métodos especificados aquí, esta clase también posee un método `__invoke`. Esto es por razones de lógica con la implementación de el método mágico de llamada.

## Sinopsis de la Clase

final class Closure {
/* Métodos */
private function __construct()
public static function bind(Closure `$closure`, ?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure
public function bindTo(?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure
public function call(object `$newThis`, mixed `...$args`): mixed
public static function fromCallable(callable `$callback`): Closure
public static function getCurrent(): Closure
}

## Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | La salida de Closure::__debugInfo() incluye ahora el nombre, la línea y el fichero del cierre.

## Notas

> Nota: Los objetos Closure no pueden ser serializados, ya que los cierres pueden contener variables vinculadas y un contexto de ejecución específico. Intentar serializar un cierre lanzará una Exception.

# Closure::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Closure::__construct — Constructor que anula la instanciación

### Descripción

private function Closure::__construct()

Este método sólo existe para anular la instanciación de la clase Closure. Los objetos de esta clase se crean del modo descrito en la página funciones anónimas.

### Parámetros

Esta función no contiene ningún parámetro.

### Ver también

- Funciones anónimas

# Closure::bind

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

Closure::bind — Duplicar un cierre con un objeto vinculado y ámbito de clase especificados

### Descripción

public static function Closure::bind(Closure `$closure`, ?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure

Este método es una versión estática de Closure::bindTo(). Véase la documentación de ese método para más información.

### Parámetros

`closure`

  La función anónima a vincular.

`newThis`

  El objeto al que la función anónima dada debería ser vinculado, o `null` para que el cierre sea desvinculado.

`newScope`

  El ámbito de clase a la que asociar el cierre, o 'static' para mantener el actual. Si se proporciona un objeto, el tipo del mismo se usará en su lugar. Esto determina la visibilidad de métodos protegidos y privados del objeto vinculado. No se permite pasar (un objeto de) una clase interna a este parámetro.

### Valores devueltos

Devuelve un nuevo objeto Closure object, o `null` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo de Closure::bind()

    <?php
    class A {
        private static $sfoo = 1;
        private $ifoo = 2;
    }
    $cl1 = static function() {
        return A::$sfoo;
    };
    $cl2 = function() {
        return $this->ifoo;
    };

    $bcl1 = Closure::bind($cl1, null, 'A');
    $bcl2 = Closure::bind($cl2, new A(), 'A');
    echo $bcl1(), "\n";
    echo $bcl2(), "\n";
    ?>

Resultado del ejemplo anterior es similar a:

    1
    2

### Ver también

- Funciones anónimas
- Closure::bindTo() - Duplica la cierre con un nuevo objeto vinculado y un nuevo contexto de clase.

# Closure::bindTo

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

Closure::bindTo — Duplica la cierre con un nuevo objeto vinculado y un nuevo contexto de clase.

### Descripción

public function Closure::bindTo(?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure

Crea y devuelve una nueva función anónima con el mismo cuerpo y las mismas variables vinculadas que la original, pero con un objeto vinculado que puede ser diferente, y un nuevo contexto de clase.

El objeto vinculado determina el valor que `$this` tendrá en el cuerpo de la función, y el contexto de clase representa una clase que determina a qué miembros privados y protegidos la función anónima tendrá acceso. En otras palabras, las propiedades que serán visibles serán las mismas que si la función anónima fuera un método de la clase pasada a través del argumento `newScope`.

Las cierres estáticas no pueden tener un objeto vinculado (el valor del argumento `newThis` debería ser `null`), pero este método puede utilizarse para cambiar su ámbito de clase.

Este método verificará que una cierre no estática a la que se le pase un contexto de objeto se vincule a este objeto (y ya no sea no estática), y viceversa. Con este fin, las cierres no estáticas a las que se les pase un contexto de clase pero `null` como contexto de objeto serán convertidas en estáticas, y viceversa.

> Nota:

> Si solo se desea duplicar la función anónima, puede utilizarse el clonado en su lugar.

### Parámetros

`newThis`

  El objeto al que vincular la función anónima, o `null` para una cierre estática.

`newScope`

  El contexto de clase a asociar con la cierre, o 'static' para conservar el contexto actual. Si se pasa un objeto, su tipo será utilizado. Esto determina la visibilidad de los métodos protegidos y privados del objeto vinculado. No está permitido pasar (un objeto de) una clase interna para este argumento.

### Valores devueltos

Devuelve la nueva cierre en forma de objeto Closure, o `null` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo Closure::bindTo()

    <?php

    class A
    {
        private $val;

        public function __construct($val)
        {
            $this->val = $val;
        }

        public function getClosure()
        {
            //Retorna una cierre vinculada a este objeto y contexto
            return function() {
                return $this->val;
            };
        }
    }

    $ob1 = new A(1);
    $ob2 = new A(2);

    $cl = $ob1->getClosure();
    echo $cl(), "\n";
    $cl = $cl->bindTo($ob2);
    echo $cl(), "\n";
    ?>

Resultado del ejemplo anterior es similar a:

    1
    2

### Ver también

- Funciones anónimas
- Closure::bind() - Duplicar un cierre con un objeto vinculado y ámbito de clase especificados

# Closure::call

(PHP 7, PHP 8)

Closure::call — Vincula y llama al cierre

### Descripción

public function Closure::call(object `$newThis`, mixed `...$args`): mixed

Vincula temporalmente el cierre a `newThis`, y lo llama con cualquier parámetro dado.

### Parámetros

`newThis`

  El object a vincular al cierre mientras dure la llamada.

`args`

  Cero o más parámetros, que serán dados como parámetros al cierre.

### Valores devueltos

Devuelve el valor devuelto por el cierre.

### Ejemplos

Ejemplo #1 Ejemplo de Closure::call()

    <?php
    class Valor {
        protected $valor;

        public function __construct($valor) {
            $this->valor = $valor;
        }

        public function getValor() {
            return $this->valor;
        }
    }

    $tres = new Valor(3);
    $cuatro = new Valor(4);

    $cierre = function ($delta) { var_dump($this->getValor() + $delta); };
    $cierre->call($tres, 4);
    $cierre->call($cuatro, 4);
    ?>

El ejemplo anterior mostrará:

    int(7)
    int(8)

# Closure::fromCallable

(PHP 7 >= 7.1.0)

Closure::fromCallable — Convierte un 'callable' en un cierre

### Descripción

public static function Closure::fromCallable(callable `$callback`): Closure

Crea y devuelve una nueva función anónima desde el `callback` dado empleando el ámbito actual. Este método comprueba si `callback` es llamable en el ámbito actual, lanzando un TypeError si no lo es.

> Nota:

> A partir de PHP 8.1.0, Sintaxis de llamada de primera clase tiene la misma semántica que este método.

### Parámetros

`callback`

  El «callable» a convertir.

### Valores devueltos

Devuelve el recién creado Closure o lanza un TypeError si `callback` no es llamable en el ámbito actual.

### Ver también

- Funciones anónimas
- Sintaxis de las llamadas de primera clase

# Closure::getCurrent

(PHP 8 >= 8.5.0)

Closure::getCurrent — Devuelve la closure actualmente en ejecución

### Descripción

public static function Closure::getCurrent(): Closure

Devuelve la closure actualmente en ejecución. Este método es principalmente útil para implementar closures recursivas sin necesidad de capturar una referencia a la variable de la closure usando la palabra clave `use`.

Este método debe ser llamado desde dentro de una closure; llamarlo fuera de un contexto de closure resultará en `Error: Current function is not a closure.`

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la instancia de Closure actualmente en ejecución.

### Errores/Excepciones

Lanza un Error si se llama fuera de un contexto de closure.

### Ejemplos

Ejemplo #1 Ejemplo de Closure::getCurrent()

Uso de Closure::getCurrent() para implementar una función de Fibonacci recursiva:

    <?php
    $fibonacci = function (int $n) {
        if ($n === 0 || $n === 1) {
            return $n;
        }

        $fn = Closure::getCurrent();
        return $fn($n - 1) + $fn($n - 2);
    };

    echo $fibonacci(10); // Muestra: 55
    ?>

Ejemplo #2 Comparación con el enfoque tradicional

Antes de PHP 8.5, implementar closures recursivas requería capturar una referencia a la variable de la closure usando la palabra clave `use`:

    <?php
    // Enfoque tradicional (aún funciona en PHP 8.5)
    $fibonacci = function (int $n) use (&$fibonacci) {
        if ($n === 0) return 0;
        if ($n === 1) return 1;
        return $fibonacci($n - 1) + $fibonacci($n - 2);
    };

    echo $fibonacci(10); // Muestra: 55
    ?>

El enfoque con Closure::getCurrent() elimina la necesidad de declarar la variable con una referencia en la cláusula `use`, lo que hace el código más limpio y menos propenso a errores.

## Tabla de contenidos

- Closure::__construct — Constructor que anula la instanciación
- Closure::bind — Duplicar un cierre con un objeto vinculado y ámbito de clase especificados
- Closure::bindTo — Duplica la cierre con un nuevo objeto vinculado y un nuevo contexto de clase.
- Closure::call — Vincula y llama al cierre
- Closure::fromCallable — Convierte un 'callable' en un cierre
- Closure::getCurrent — Devuelve la closure actualmente en ejecución

# La clase stdClass

(PHP 4, PHP 5, PHP 7, PHP 8)

## Introducción

Una clase genérica vacía con propiedades dinámicas.

Los objetos de esta clase pueden ser instanciados con new operador o creados por conversión a objeto. Varias funciones de PHP también crean instancias de esta clase, por ejemplo json_decode(), mysqli_fetch_object() o PDOStatement::fetchObject().

A pesar de no implementar __get()/__set() métodos mágicos, esta clase permite propiedades dinámicas y no requiere el `#[\AllowDynamicProperties]` atributo.

Esto no es una clase base ya que PHP no tiene el concepto de una clase base universal. Sin embargo, es posible crear una clase personalizada que extienda de stdClass y como resultado herede la funcionalidad de propiedades dinámicas.

## Sinopsis de la Clase

#[\AllowDynamicProperties]
class stdClass {
}

Esta clase no tiene métodos ni propiedades predeterminadas.

## Ejemplos

Ejemplo #1 Creado como resultado de la conversión a objeto

    <?php
    $obj = (object) array('foo' => 'bar');
    var_dump($obj);

El ejemplo anterior mostrará:

    object(stdClass)#1 (1) {
      ["foo"]=>
      string(3) "bar"
    }

Ejemplo #2 Creado como resultado de json_decode()

    <?php
    $json = '{"foo":"bar"}';
    var_dump(json_decode($json));

El ejemplo anterior mostrará:

    object(stdClass)#1 (1) {
      ["foo"]=>
      string(3) "bar"
    }

Ejemplo #3 Declaración de propiedades dinámicas

    <?php
    $obj = new stdClass();
    $obj->foo = 42;
    $obj->{1} = 42;
    var_dump($obj);

El ejemplo anterior mostrará:

    object(stdClass)#1 (2) {
      ["foo"]=>
      int(42)
      ["1"]=>
      int(42)
    }

# La clase Generator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introducción

Los objetos Generator son devueltos desde generadores.

Precaución

Los objetos Generator no pueden ser instanciados mediante new.

## Sinopsis de la Clase

final class Generator implements Iterator {
/* Métodos */
public function current(): mixed
public function getReturn(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function send(mixed `$value`): mixed
public function throw(Throwable `$exception`): mixed
public function valid(): bool
public function __wakeup(): void
}

## Ver también

Véase también iteración de objetos.

# Generator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::current — Obtener el valor producido

### Descripción

public function Generator::current(): mixed

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el valor producido.

# Generator::getReturn

(PHP 7, PHP 8)

Generator::getReturn — Obtener el valor devuelto de un generador

### Descripción

public function Generator::getReturn(): mixed

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el valor devuelto del generador una vez ha finalizado su ejecución.

### Ejemplos

Ejemplo #1 Ejemplo de Generator::getReturn()

    <?php

    $gen = (function() {
        yield 1;
        yield 2;

        return 3;
    })();

    foreach ($gen as $val) {
        echo $val, PHP_EOL;
    }

    echo $gen->getReturn(), PHP_EOL;

El ejemplo anterior mostrará:

    1
    2
    3

# Generator::key

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::key — Obtener la clave generada

### Descripción

public function Generator::key(): mixed

Obtiene la clave del valor generado.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la clave generada.

### Ejemplos

Ejemplo #1 Ejemplo de Generator::key()

    <?php

    function Gen()
    {
        yield 'key' => 'value';
    }

    $gen = Gen();

    echo "{$gen->key()} => {$gen->current()}";

El ejemplo anterior mostrará:

    key => value

# Generator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::next — Continua la ejecución del generador

### Descripción

public function Generator::next(): void

Llamar a Generator::next() tiene el mismo efecto que llamar a Generator::send() con `null` como argumento.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

# Generator::rewind

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::rewind — Ejecuta el generador hasta e incluyendo el primer yield

### Descripción

public function Generator::rewind(): void

Ejecuta el generador hasta e incluyendo el primer `yield`. Si el generador ya está en el primer `yield`, no se realizará ninguna acción. Si el generador ha avanzado más allá de una expresión `yield`, este método lanzará una Exception.

> Nota:

> Se trata del método primero llamado al inicio de un ciclo `foreach`. No se ejecutará después de los ciclos `foreach`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo de Generator::rewind()

    <?php

    function generator(): Generator
    {
        echo "¡Soy un generador!\n";

        for ($i = 1; $i <= 3; $i++) {
            yield $i;
        }
    }

    // Inicializar el generador
    $generator = generator();

    // Devolver el generador al inicio de la primera expresión yield,
    // si no lo está ya
    $generator->rewind(); // ¡Soy un generador!

    // No ocurre nada aquí; el generador ya está reiniciado
    $generator->rewind(); // Sin salida (NULL)

    // Esto devuelve el generador al inicio de la primera expresión yield,
    // si no lo está ya, e itera sobre el generador
    foreach ($generator as $value) {
        // Después de devolver el primer valor, el generador permanece en
        // la primera expresión yield hasta que se reanude la ejecución y avance a la siguiente yield
        echo $value, PHP_EOL; // 1

        break;
    }

    // Reanudar y reiniciar nuevamente. No se produce ningún error ya que el generador no ha avanzado más allá del primer yield
    $generator->rewind();

    echo $generator->current(), PHP_EOL; // 1

    // No se produce ningún error, el generador sigue en la primera yield
    $generator->rewind();

    // Esto hace avanzar el generador a la segunda expresión yield
    $generator->next();

    try {
        // Esto lanzará una excepción,
        // ya que el generador ya ha avanzado a la segunda yield
        $generator->rewind(); // Error fatal: Exception no capturada: No se puede devolver un generador que ya ha sido ejecutado
    } catch (Exception $e) {
        echo $e->getMessage();
    }

    ?>

El ejemplo anterior mostrará:

    ¡Soy un generador!
    1
    1
    No se puede devolver un generador que ya ha sido ejecutado

# Generator::send

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::send — Enviar un valor al generador

### Descripción

public function Generator::send(mixed `$value`): mixed

Envía el valor dado al generador como resultado de la expresión `yield` actual y reanuda la ejecución del generador.

Si el generador no es una expresión `yield` en el momento de invocar a este método, se permitirá avanzar a la primera expresión `yield` antes de enviar el valor. Por tanto, no es necesario «preparar» generadores de PHP con una llamada a Generator::next() (como se hace en Python).

### Parámetros

`value`

  El valor a enviar al generador. Este valor será el valor devuelto de la expresión `yield` en la que está actualmente el generador.

### Valores devueltos

Devuelve el valor producido.

### Ejemplos

Ejemplo #1 Empleo de Generator::send() para inyectar valores

    <?php
    function printer() {
        echo "¡Soy una impresora!".PHP_EOL;
        while (true) {
            $string = yield;
            echo $string.PHP_EOL;
        }
    }

    $printer = printer();
    $printer->send('¡Hola mundo!');
    $printer->send('¡Adiós mundo!');
    ?>

El ejemplo anterior mostrará:

    ¡Soy una impresora!
    ¡Hola mundo!
    ¡Adiós mundo!

# Generator::throw

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::throw — Lanzar una excepción dentro generador

### Descripción

public function Generator::throw(Throwable `$exception`): mixed

Lanza una excepción dentro del generador y reanuda su ejecución. El comportamiento será el mismo que si la expresión `yield` actual fuera reemplazada con una sentencia `throw $exception`.

Si el generador ya está cerrado al invocar a este método, la excepción será lanzada en su lugar en el contexto del invocador.

### Parámetros

`exception`

  La excepción a lanzar dentro del generador.

### Valores devueltos

Devuelve el valor generado.

### Ejemplos

Ejemplo #1 Lanzar una ecepión dentro de un generador

    <?php
    function gen() {
        echo "Foo\n";
        try {
            yield;
        } catch (Exception $e) {
            echo "Excepción: {$e->getMessage()}\n";
        }
        echo "Bar\n";
    }

    $gen = gen();
    $gen->rewind();
    $gen->throw(new Exception('Prueba'));
    ?>

El ejemplo anterior mostrará:

    Foo
    Excepción: Prueba
    Bar

# Generator::valid

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::valid — Verificar si el iterador ha sido cerrado

### Descripción

public function Generator::valid(): bool

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `false` si el iterador ha sido cerrado. De lo contrario devuelve `true`.

# Generator::__wakeup

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::__wakeup — Serialize callback

### Descripción

public function Generator::__wakeup(): void

Lanza una excepción indicando que el generador no puede ser presentado.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

## Tabla de contenidos

- Generator::current — Obtener el valor producido
- Generator::getReturn — Obtener el valor devuelto de un generador
- Generator::key — Obtener la clave generada
- Generator::next — Continua la ejecución del generador
- Generator::rewind — Ejecuta el generador hasta e incluyendo el primer yield
- Generator::send — Enviar un valor al generador
- Generator::throw — Lanzar una excepción dentro generador
- Generator::valid — Verificar si el iterador ha sido cerrado
- Generator::__wakeup — Serialize callback

# La clase Fiber

(PHP 8 >= 8.1.0)

## Introducción

Las fibras representan funciones interrumpibles en toda la pila. Las fibras pueden ser suspendidas en cualquier punto de la pila de llamadas, interrumpiendo la ejecución dentro de la fibra hasta que la fibra sea reanudada posteriormente.

## Sinopsis de la Clase

final class Fiber {
/* Métodos */
public function __construct(callable `$callback`)
public function start(mixed `...$args`): mixed
public function resume(mixed `$value` = `null`): mixed
public function throw(Throwable `$exception`): mixed
public function getReturn(): mixed
public function isStarted(): bool
public function isSuspended(): bool
public function isRunning(): bool
public function isTerminated(): bool
public static function suspend(mixed `$value` = `null`): mixed
public static function getCurrent(): ?Fiber
}

## Ver también

Visión general de las fibras

# Fiber::__construct

(PHP 8 >= 8.1.0)

Fiber::__construct — Crea una nueva instancia de Fibra

### Descripción

public function Fiber::__construct(callable `$callback`)

### Parámetros

`callback`

  El callable a invocar al iniciar la fibra. Los argumentos dados a Fiber::start() serán proporcionados como argumentos a la función dada.

# Fiber::start

(PHP 8 >= 8.1.0)

Fiber::start — Inicia la ejecución de la fibra

### Descripción

public function Fiber::start(mixed `...$args`): mixed

Una lista variádica de argumentos a proporcionar a la función utilizada durante la construcción de la fibra.

Si la fibra ya ha sido iniciada cuando se llama a este método, se emitirá un error FiberError.

### Parámetros

`args`

  Los argumentos a utilizar durante la invocación de la función dada al constructor de la fibra.

### Valores devueltos

El valor proporcionado a la primera llamada a Fiber::suspend() o `null` si la fibra retorna. Si la fibra lanza una excepción antes de suspenderse, será emitida durante la llamada a este método.

# Fiber::resume

(PHP 8 >= 8.1.0)

Fiber::resume — Reanuda la ejecución de la fibra con un valor

### Descripción

public function Fiber::resume(mixed `$value` = `null`): mixed

Reanuda la fibra utilizando el valor dado como resultado de la llamada actual a Fiber::suspend().

Si la fibra no está suspendida al llamar a este método, se lanzará un FiberError.

### Parámetros

`value`

  El valor para reanudar la fibra. Este valor será el valor de retorno de la llamada Fiber::suspend() en curso.

### Valores devueltos

El valor proporcionado a la próxima llamada a Fiber::suspend() o `null` si la fibra retorna. Si la fibra lanza una excepción antes de suspenderse, será lanzada al llamar a este método.

# Fiber::throw

(PHP 8 >= 8.1.0)

Fiber::throw — Reanuda la ejecución de la fibra con una excepción

### Descripción

public function Fiber::throw(Throwable `$exception`): mixed

Reanuda la fibra lanzando la excepción dada desde la llamada Fiber::suspend() en curso.

Si la fibra no está suspendida cuando se llama a este método, se emitirá una excepción FiberError.

### Parámetros

`exception`

  La excepción a lanzar en la fibra desde la llamada Fiber::suspend() en curso.

### Valores devueltos

El valor proporcionado en la próxima llamada a Fiber::suspend() o `null` si la fibra retorna. Si la fibra lanza una excepción antes de suspenderse, será emitida al llamar a este método.

### Ejemplos

    <?php

    $fiber = new Fiber(function () {
       try {
           // Suspende la ejecución de la fibra declarando un punto de interrupción
           Fiber::suspend();
       } catch (Throwable $e) {
           echo $e->getMessage();
       }
    });

    $fiber->start();

    // Reanuda la ejecución de la fibra pasando
    // la Excepción a lanzar en el punto de interrupción
    $fiber->throw(new Exception('Mensaje de una excepción lanzada en el punto de interrupción actual'));

    ?>

Resultado del ejemplo anterior es similar a:

    Mensaje de una excepción lanzada en el punto de interrupción actual

# Fiber::getReturn

(PHP 8 >= 8.1.0)

Fiber::getReturn — Obtiene el valor devuelto por la fibra

### Descripción

public function Fiber::getReturn(): mixed

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el valor devuelto por la fibra callable proporcionada a Fiber::__construct(). Si la fibra no ha devuelto un valor, ya sea porque no ha sido lanzada, porque no ha terminado, o porque ha lanzado una excepción, se emitirá un FiberError.

# Fiber::isStarted

(PHP 8 >= 8.1.0)

Fiber::isStarted — Determina si la fibra ha iniciado

### Descripción

public function Fiber::isStarted(): bool

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` solo después de que la fibra haya sido iniciada; de lo contrario, se devuelve `false`.

# Fiber::isSuspended

(PHP 8 >= 8.1.0)

Fiber::isSuspended — Determina si la fibra está suspendida

### Descripción

public function Fiber::isSuspended(): bool

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si la fibra está actualmente suspendida; de lo contrario, devuelve `false`.

# Fiber::isRunning

(PHP 8 >= 8.1.0)

Fiber::isRunning — Determina si la fibra está en ejecución

### Descripción

public function Fiber::isRunning(): bool

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` solo si la fibra está en ejecución. Una fibra se considera en ejecución después de una llamada a Fiber::start(), Fiber::resume(), o Fiber::throw() que aún no ha retornado. Devuelve `false` si la fibra no está en ejecución.

# Fiber::isTerminated

(PHP 8 >= 8.1.0)

Fiber::isTerminated — Determina si la fibra ha terminado

### Descripción

public function Fiber::isTerminated(): bool

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` solo después de que la fibra haya terminado, ya sea devolviendo o lanzando una excepción; de lo contrario, se devuelve `false`.

# Fiber::suspend

(PHP 8 >= 8.1.0)

Fiber::suspend — Suspende la ejecución de la fibra actual

### Descripción

public static function Fiber::suspend(mixed `$value` = `null`): mixed

Suspende la ejecución de la fibra actual. El valor proporcionado a este método será devuelto por la llamada a Fiber::start(), Fiber::resume(), o Fiber::throw() que hizo cambiar la ejecución a la fibra actual.

Cuando la fibra se reanuda, este método devuelve el valor proporcionado a Fiber::resume(). Si la fibra se reanuda utilizando Fiber::throw(), la excepción dada a este método será emitida al llamar a este método.

Si este método es llamado desde fuera de una fibra, una FiberError será emitida.

### Parámetros

`value`

  El valor a devolver de la llamada a Fiber::start(), Fiber::resume(), o Fiber::throw() que hizo cambiar la ejecución a la fibra actual.

### Valores devueltos

El valor proporcionado a Fiber::resume().

# Fiber::getCurrent

(PHP 8 >= 8.1.0)

Fiber::getCurrent — Obtiene la instancia de Fibra en ejecución

### Descripción

public static function Fiber::getCurrent(): ?Fiber

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la instancia Fiber en ejecución o `null` si este método es llamado desde fuera de una fibra.

## Tabla de contenidos

- Fiber::__construct — Crea una nueva instancia de Fibra
- Fiber::start — Inicia la ejecución de la fibra
- Fiber::resume — Reanuda la ejecución de la fibra con un valor
- Fiber::throw — Reanuda la ejecución de la fibra con una excepción
- Fiber::getReturn — Obtiene el valor devuelto por la fibra
- Fiber::isStarted — Determina si la fibra ha iniciado
- Fiber::isSuspended — Determina si la fibra está suspendida
- Fiber::isRunning — Determina si la fibra está en ejecución
- Fiber::isTerminated — Determina si la fibra ha terminado
- Fiber::suspend — Suspende la ejecución de la fibra actual
- Fiber::getCurrent — Obtiene la instancia de Fibra en ejecución

# La clase WeakReference

(PHP 7 >= 7.4.0, PHP 8)

## Introducción

Las referencias débiles permiten al programador mantener una referencia a un objeto sin impedir su destrucción. Son útiles para implementar estructuras como cachés. Si el objeto original ha sido destruido, `null` será devuelto al llamar al método WeakReference::get(). El objeto original será destruido cuando el contador de referencias llegue a cero; la creación de referencias débiles no incrementa el `contador de referencias` del objeto referenciado.

Las WeakReferences no pueden ser serializadas.

## Sinopsis de la Clase

final class WeakReference {
/* Métodos */
public function __construct()
public static function create(object `$object`): WeakReference
public function get(): ?object
}

## Ejemplo con WeakReference

Ejemplo #1 Uso Simple de WeakReference

    <?php

    $obj = new stdClass();
    $weakref = WeakReference::create($obj);

    var_dump($weakref->get());

    unset($obj);

    var_dump($weakref->get());

    ?>

Resultado del ejemplo anterior es similar a:

    object(stdClass)#1 (0) {
    }
    NULL

## Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | La salida de WeakReference::__debugInfo() incluye ahora el objeto referenciado, o `NULL` si la referencia ya no es válida.

# WeakReference::__construct

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::__construct — Constructor que no permite la instanciación

### Descripción

public function WeakReference::__construct()

Este método existe sólo para no permitir la instanciación de la clase WeakReference. Las referencias débiles deben ser instanciadas con el método factory WeakReference::create().

### Parámetros

Esta función no contiene ningún parámetro.

### Ver también

- WeakReference::create() - Crea una nueva referencia débil

# WeakReference::create

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::create — Crea una nueva referencia débil

### Descripción

public static function WeakReference::create(object `$object`): WeakReference

Crea una nueva WeakReference.

### Parámetros

`object`

  El objeto a ser referenciado débilmente.

### Valores devueltos

Devuelve una nueva WeakReference, o la instancia existente si ya había una WeakReference al mismo objeto.

# WeakReference::get

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::get — Obtiene un objeto débilmente referenciado

### Descripción

public function WeakReference::get(): ?object

Se obtiene un objeto débilmente referenciado. Si el objeto ya ha sido destruido, devuelve `null`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el referenciado object, o `null` si el objeto ha sido destruido.

## Tabla de contenidos

- WeakReference::__construct — Constructor que no permite la instanciación
- WeakReference::create — Crea una nueva referencia débil
- WeakReference::get — Obtiene un objeto débilmente referenciado

# La clase WeakMap

(PHP 8)

## Introducción

Un WeakMap es un array asociativo (o diccionario) que acepta objetos como claves. Sin embargo, a diferencia del similar SplObjectStorage, un objeto en una clave de WeakMap no contribuye al número de referencias del objeto. En otras palabras, si, en un momento dado, la única referencia restante a un objeto es la clave de un WeakMap, el objeto será recolectado y eliminado del WeakMap. Su principal caso de uso es la construcción de cachés de datos derivados de un objeto que no necesitan ser conservados más tiempo que el objeto.

WeakMap implementa ArrayAccess, Traversable (vía IteratorAggregate), y Countable, de modo que, en la mayoría de los casos, puede ser utilizado de la misma manera que un array asociativo.

## Sinopsis de la Clase

final class WeakMap implements ArrayAccess, Countable, IteratorAggregate {
/* Métodos */
public function count(): int
public function getIterator(): Iterator
public function offsetExists(object `$object`): bool
public function offsetGet(object `$object`): mixed
public function offsetSet(object `$object`, mixed `$value`): void
public function offsetUnset(object `$object`): void
}

## Ejemplos

Ejemplo #1 Ejemplo de uso de un Weakmap

    <?php
    $wm = new WeakMap();

    $o = new stdClass;

    class A {
        public function __destruct() {
            echo "Dead!\n";
        }
    }

    $wm[$o] = new A;

    var_dump(count($wm));
    echo "Unsetting...\n";
    unset($o);
    echo "Done\n";
    var_dump(count($wm));

El ejemplo anterior mostrará:

    int(1)
    Unsetting...
    Dead!
    Done
    int(0)

# WeakMap::count

(PHP 8)

WeakMap::count — Cuenta el número de entradas activas en el diccionario

### Descripción

public function WeakMap::count(): int

Cuenta el número de entradas activas en el diccionario.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de entradas activas en el diccionario.

# WeakMap::getIterator

(PHP 8)

WeakMap::getIterator — Recupera un iterador externo

### Descripción

public function WeakMap::getIterator(): Iterator

Devuelve un iterador externo.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Una instancia de un objeto que implementa Iterator o Traversable

### Errores/Excepciones

Lanza un Exception en caso de error.

# WeakMap::offsetExists

(PHP 8)

WeakMap::offsetExists — Verifica si un cierto objeto se encuentra en el diccionario

### Descripción

public function WeakMap::offsetExists(object `$object`): bool

Verifica si el objeto transmitido está referenciado en el diccionario.

### Parámetros

`object`

  Objeto a verificar.

### Valores devueltos

Devuelve `true` si el objeto está contenido en el diccionario, `false` en caso contrario.

# WeakMap::offsetGet

(PHP 8)

WeakMap::offsetGet — Devuelve el valor indicado por un cierto objeto

### Descripción

public function WeakMap::offsetGet(object `$object`): mixed

Devuelve el valor indicado por un cierto objeto.

### Parámetros

`object`

  Un objeto contenido como clave en el diccionario.

### Valores devueltos

Devuelve el valor asociado al objeto pasado como argumento.

### Errores/Excepciones

Lanza una Error en caso de fallo.

# WeakMap::offsetSet

(PHP 8)

WeakMap::offsetSet — Actualiza el diccionario con una nueva pareja clave-valor

### Descripción

public function WeakMap::offsetSet(object `$object`, mixed `$value`): void

Actualiza el diccionario con una nueva pareja clave-valor. Si la clave ya existía, el valor antiguo es reemplazado por el nuevo.

### Parámetros

`object`

  El objeto que sirve de clave a la pareja clave-valor.

`value`

  Los datos arbitrarios que sirven de valor a la pareja clave-valor.

### Valores devueltos

No se retorna ningún valor.

# WeakMap::offsetUnset

(PHP 8)

WeakMap::offsetUnset — Elimina una entrada del diccionario

### Descripción

public function WeakMap::offsetUnset(object `$object`): void

Elimina una entrada del diccionario.

### Parámetros

`object`

  El objeto clave a eliminar del diccionario.

### Valores devueltos

No se retorna ningún valor.

## Tabla de contenidos

- WeakMap::count — Cuenta el número de entradas activas en el diccionario
- WeakMap::getIterator — Recupera un iterador externo
- WeakMap::offsetExists — Verifica si un cierto objeto se encuentra en el diccionario
- WeakMap::offsetGet — Devuelve el valor indicado por un cierto objeto
- WeakMap::offsetSet — Actualiza el diccionario con una nueva pareja clave-valor
- WeakMap::offsetUnset — Elimina una entrada del diccionario

# La interfaz Stringable

(PHP 8)

## Introducción

La interfaz Stringable designa una clase que posee un método __toString(). A diferencia de la mayoría de las interfaces, Stringable está implícitamente presente en cualquier clase para la cual el método mágico __toString() está definido, aunque puede y debe ser declarada explícitamente.

Su valor principal es permitir a las funciones verificar el tipo en comparación con el tipo de unión `string|Stringable` para aceptar ya sea un string primitivo, ya sea un objeto que pueda ser convertido a string.

## Sinopsis de la Interfaz

interface Stringable {
/* Métodos */
public function __toString(): string
}

## Ejemplos de Stringable

Ejemplo #1 Ejemplo simple

Esto utiliza la promoción de propiedades del constructor.

    <?php
    class IPv4Address implements Stringable {
        public function __construct(
            private string $oct1,
            private string $oct2,
            private string $oct3,
            private string $oct4,
        ) {}

        public function __toString(): string {
            return "$this->oct1.$this->oct2.$this->oct3.$this->oct4";
        }
    }

    function showStuff(string|Stringable $value) {
        // Para un Stringable, esto llamará implícitamente a __toString().
        print $value;
    }

    $ip = new IPv4Address('123', '234', '42', '9');

    showStuff($ip);
    ?>

Resultado del ejemplo anterior es similar a:

    123.234.42.9

# Stringable::__toString

(PHP 8)

Stringable::__toString — Devuelve la representación del objeto en forma de string

### Descripción

public function Stringable::__toString(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la representación string del objeto.

### Ver también

- __toString()

## Tabla de contenidos

- Stringable::__toString — Devuelve la representación del objeto en forma de string

# La interfaz UnitEnum

(PHP 8 >= 8.1.0)

## Introducción

La interfaz UnitEnum es automáticamente aplicada a todas las enumeraciones por el motor. No puede ser implementada por clases definidas por el usuario. Las enumeraciones no pueden sobrescribir sus métodos, ya que las implementaciones por omisión son proporcionadas por el motor. Solo está disponible para las verificaciones de tipo.

## Sinopsis de la Interfaz

interface UnitEnum {
/* Métodos */
public static function cases(): array
}

# UnitEnum::cases

(PHP 8 >= 8.1.0)

UnitEnum::cases — Genera una lista de casos sobre una enumeración

### Descripción

public static function UnitEnum::cases(): array

Este método devuelve un array de todos los casos de una enumeración, en el orden de su declaración.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array de todos los casos definidos de esta enumeración, en el orden de la declaración.

### Ejemplos

Ejemplo #1 Uso básico

El siguiente ejemplo ilustra la forma en que los casos de enumeración son devueltos.

    <?php
    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    var_dump(Suit::cases());

El ejemplo anterior mostrará:

    array(4) {
      [0]=>
      enum(Suit::Hearts)
      [1]=>
      enum(Suit::Diamonds)
      [2]=>
      enum(Suit::Clubs)
      [3]=>
      enum(Suit::Spades)
    }

## Tabla de contenidos

- UnitEnum::cases — Genera una lista de casos sobre una enumeración

# La interfaz BackedEnum

(PHP 8 >= 8.1.0)

## Introducción

La interfaz BackedEnum es automáticamente aplicada a las enumeraciones con valor de base por el motor. No puede ser implementada por clases definidas por el usuario. Las enumeraciones no pueden sobreescribir sus métodos, ya que las implementaciones por omisión son proporcionadas por el motor. Solo está disponible para las verificaciones de tipo.

## Sinopsis de la Interfaz

interface BackedEnum extends UnitEnum {
/* Métodos */
public static function from(int|string `$value`): static
public static function tryFrom(int|string `$value`): ?static
/* Métodos heredados */
public static function UnitEnum::cases(): array
}

# BackedEnum::from

(PHP 8 >= 8.1.0)

BackedEnum::from — Convierte un escalar en una instancia de enum

### Descripción

public static function BackedEnum::from(int|string `$value`): static

El método from() traduce un string o un int en un caso Enum correspondiente, si existe. Si no hay un caso correspondiente definido, lanzará un error ValueError.

### Parámetros

`value`

  El valor escalar a hacer coincidir con un caso de enumeración.

### Valores devueltos

Una instancia de caso de esta enumeración.

### Ejemplos

Ejemplo #1 Uso básico

El siguiente ejemplo ilustra la forma en que se devuelven los casos de enumeración.

    <?php
    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    $h = Suit::from('H');

    var_dump($h);

    $b = Suit::from('B');
    ?>

El ejemplo anterior mostrará:

    enum(Suit::Hearts)

    Fatal error: Uncaught ValueError: "B" is not a valid backing value for enum "Suit" in /file.php:15

### Ver también

- UnitEnum::cases() - Genera una lista de casos sobre una enumeración
- BackedEnum::tryFrom() - Asocia un escalar a una instancia de enum o a null

# BackedEnum::tryFrom

(PHP 8 >= 8.1.0)

BackedEnum::tryFrom — Asocia un escalar a una instancia de enum o a null

### Descripción

public static function BackedEnum::tryFrom(int|string `$value`): ?static

El método tryFrom() traduce un string o un int en el caso Enum correspondiente, si existe. Si no hay un caso correspondiente definido, devolverá null.

### Parámetros

`value`

  El valor escalar a hacer corresponder con un caso de enumeración.

### Valores devueltos

Una instancia de caso de esta enumeración, o null si no se ha encontrado.

### Ejemplos

Ejemplo #1 Uso básico

El siguiente ejemplo ilustra la manera en que los casos de enumeración son devueltos.

    <?php
    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    $h = Suit::tryFrom('H');

    var_dump($h);

    $b = Suit::tryFrom('B') ?? Suit::Spades;

    var_dump($b);
    ?>

El ejemplo anterior mostrará:

    enum(Suit::Hearts)
    enum(Suit::Spades)

### Ver también

- UnitEnum::cases() - Genera una lista de casos sobre una enumeración
- BackedEnum::from() - Convierte un escalar en una instancia de enum

## Tabla de contenidos

- BackedEnum::from — Convierte un escalar en una instancia de enum
- BackedEnum::tryFrom — Asocia un escalar a una instancia de enum o a null

# La clase SensitiveParameterValue

(PHP 8 >= 8.2.0)

## Introducción

La clase SensitiveParameterValue permite envolver valores para protegerlos contra una exposición accidental.

Los valores de los parámetros con el atributo SensitiveParameter serán automáticamente envueltos en un objeto SensitiveParameterValue en las trazas de pila.

## Sinopsis de la Clase

final class SensitiveParameterValue {
/* Propiedades */
private readonly mixed $value;
/* Métodos */
public function __construct(mixed `$value`)
public function __debugInfo(): array
public function getValue(): mixed
}

## Propiedades

value

  Valor sensible a proteger contra una exposición accidental.

# SensitiveParameterValue::__construct

(PHP 8 >= 8.2.0)

SensitiveParameterValue::__construct — Construye un nuevo objeto SensitiveParameterValue

### Descripción

public function SensitiveParameterValue::__construct(mixed `$value`)

Construye un objeto SensitiveParameterValue que contiene un valor sensible.

### Parámetros

`value`

  Un valor arbitrario que debe ser almacenado en el objeto SensitiveParameterValue.

# SensitiveParameterValue::__debugInfo

(PHP 8 >= 8.2.0)

SensitiveParameterValue::__debugInfo — Protege el valor sensible contra una exposición accidental

### Descripción

public function SensitiveParameterValue::__debugInfo(): array

Devuelve un array vacío para proteger el valor sensible contra una exposición accidental al utilizar var_dump().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array vacío.

### Ejemplos

Ejemplo #1 Pasar un objeto SensitiveParameterValue a var_dump()

    <?php
    $s = new \SensitiveParameterValue('secret');

    var_dump($s);
    ?>

El ejemplo anterior mostrará:

    object(SensitiveParameterValue)#1 (0) {
    }

# SensitiveParameterValue::getValue

(PHP 8 >= 8.2.0)

SensitiveParameterValue::getValue — Devuelve el valor sensible

### Descripción

public function SensitiveParameterValue::getValue(): mixed

Devuelve el valor sensible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El valor sensible.

### Ejemplos

Ejemplo #1 Ejemplo de SensitiveParameterValue::getValue()

    <?php
    $s = new \SensitiveParameterValue('secret');

    echo "El valor protegido es: ", $s->getValue(), "\n";
    ?>

El ejemplo anterior mostrará:

    El valor protegido es: secret

## Tabla de contenidos

- SensitiveParameterValue::__construct — Construye un nuevo objeto SensitiveParameterValue
- SensitiveParameterValue::__debugInfo — Protege el valor sensible contra una exposición accidental
- SensitiveParameterValue::getValue — Devuelve el valor sensible

# La clase __PHP_Incomplete_Class

(PHP 4 >=4.0.1, PHP 5, PHP 7, PHP 8)

## Introducción

Creada por unserialize() al intentar deserializar una clase no definida o una clase que no está incluida en el `allowed_classes` de unserialize() en el array `options`.

Antes de PHP 7.2.0, usar is_object() en la clase __PHP_Incomplete_Class devolvería `false`. A partir de PHP 7.2.0, se devolverá `true`.

## Sinopsis de la Clase

#[\AllowDynamicProperties]
final class __PHP_Incomplete_Class {
}

Esta clase no tiene propiedades o métodos predeterminados. Cuando es creada por unserialize(), además de todas las propiedades y valores deserializados el objeto tendrá una propiedad `__PHP_Incomplete_Class_Name` que contendrá el nombre de la clase deserializada.

## Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta clase ahora es `final`.

## Ejemplos

Ejemplo #1 Creada por unserialize()

    <?php

    class MyClass
    {
        public string $property = "myValue";
    }

    $myObject = new MyClass;

    $foo = serialize($myObject);

    // deserializa todos los objetos en objetos __PHP_Incomplete_Class
    $disallowed = unserialize($foo, ["allowed_classes" => false]);

    var_dump($disallowed);

    // deserializa todos los objetos en objetos __PHP_Incomplete_Class excepto aquellos de MyClass2 y MyClass3
    $disallowed2 = unserialize($foo, ["allowed_classes" => ["MyClass2", "MyClass3"]]);

    var_dump($disallowed2);

    // deserializa una clase no definida en un objeto __PHP_Incomplete_Class
    $undefinedClass = unserialize('O:16:"MyUndefinedClass":0:{}');

    var_dump($undefinedClass);

El ejemplo anterior mostrará:

    object(__PHP_Incomplete_Class)#2 (2) {
      ["__PHP_Incomplete_Class_Name"]=>
      string(7) "MyClass"
      ["property"]=>
      string(7) "myValue"
    }
    object(__PHP_Incomplete_Class)#3 (2) {
      ["__PHP_Incomplete_Class_Name"]=>
      string(7) "MyClass"
      ["property"]=>
      string(7) "myValue"
    }
    object(__PHP_Incomplete_Class)#4 (1) {
      ["__PHP_Incomplete_Class_Name"]=>
      string(16) "MyUndefinedClass"
    }

# Atributos predefinidos

## Tabla de contenidos

- Attribute
- AllowDynamicProperties
- DelayedTargetValidation
- Deprecated
- NoDiscard
- Override
- ReturnTypeWillChange
- SensitiveParameter

PHP proporciona atributos predefinidos que pueden ser utilizados.

# El atributo Attribute

(PHP 8)

## Introducción

Los atributos ofrecen la capacidad de añadir información de metadatos estructurados y legibles por máquina en las declaraciones del código: Clases, métodos, funciones, argumentos, propiedades y constantes de clase pueden ser el objetivo de un atributo. Los metadatos definidos por los atributos pueden entonces ser inspeccionados en tiempo de ejecución usando las APIs de Reflexión. Los atributos podrían por lo tanto ser considerados como un lenguaje de configuración integrado directamente en el código.

## Sinopsis de la Clase

#[\Attribute]
final class Attribute {
/* Constantes */
const int TARGET_CLASS;
const int TARGET_FUNCTION;
const int TARGET_METHOD;
const int TARGET_PROPERTY;
const int TARGET_CLASS_CONSTANT;
const int TARGET_PARAMETER;
const int TARGET_CONSTANT;
const int TARGET_ALL;
const int IS_REPEATABLE;
/* Propiedades */
public int $flags;
/* Métodos */
public function __construct(int `$flags` = Attribute::TARGET_ALL)
}

## Constantes predefinidas

Attribute::TARGET_CLASS

Attribute::TARGET_FUNCTION

Attribute::TARGET_METHOD

Attribute::TARGET_PROPERTY

Attribute::TARGET_CLASS_CONSTANT

Attribute::TARGET_PARAMETER

Attribute::TARGET_CONSTANT

Attribute::TARGET_ALL

Attribute::IS_REPEATABLE

## Propiedades

flags

## Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | Se ha añadido `Attribute::TARGET_CONSTANT`.

## Ver también

Visión general de los atributos

# Attribute::__construct

(PHP 8)

Attribute::__construct — Construye una nueva instancia de Attribute

### Descripción

public function Attribute::__construct(int `$flags` = `Attribute::TARGET_ALL`)

Construye una nueva instancia de Attribute.

### Parámetros

`flags`

## Tabla de contenidos

- Attribute::__construct — Construye una nueva instancia de Attribute

# El atributo AllowDynamicProperties

(PHP 8 >= 8.2.0)

## Introducción

Este atributo se utiliza para marcar clases que permiten propiedades dinámicas.

> Nota: Aunque los atributos en sí no se heredan, el efecto del atributo `AllowDynamicProperties` sí se hereda. Las clases hijas de una clase marcada con este atributo también permitirán propiedades dinámicas, incluso si no declaran el atributo explícitamente.

## Sinopsis de la Clase

#[\Attribute]
final class AllowDynamicProperties {
/* Métodos */
public function __construct()
}

## Ejemplos

Las propiedades dinámicas están deprecadas a partir de PHP 8.2.0, por lo que usarlas sin marcar la clase con este atributo emitirá un aviso de deprecación.

Ejemplo #1 AllowDynamicProperties con propiedad inexistente

    <?php
    class DefaultBehaviour { }

    #[\AllowDynamicProperties]
    class ClassAllowsDynamicProperties { }

    $o1 = new DefaultBehaviour();
    $o2 = new ClassAllowsDynamicProperties();

    $o1->nonExistingProp = true;
    $o2->nonExistingProp = true;
    ?>

Resultado del ejemplo anterior en PHP 8.2:

    Deprecated: Creation of dynamic property DefaultBehaviour::$nonExistingProp is deprecated in file on line 10

Ejemplo #2 AllowDynamicProperties con propiedad inexistente en clase heredada

    <?php
    class DefaultBehaviour { }

    #[\AllowDynamicProperties]
    class ClassAllowsDynamicProperties { }

    class InheritedClassAllowsDynamicProperties extends ClassAllowsDynamicProperties { }

    $o1 = new DefaultBehaviour();
    $o2 = new InheritedClassAllowsDynamicProperties();

    $o1->nonExistingProp = true;
    $o2->nonExistingProp = true;
    ?>

Resultado del ejemplo anterior en PHP 8.2:

    Deprecated: Creation of dynamic property DefaultBehaviour::$nonExistingProp is deprecated in file on line 12

## Ver también

Visión general de los atributos

# AllowDynamicProperties::__construct

(PHP 8 >= 8.2.0)

AllowDynamicProperties::__construct — Construye una nueva instancia del atributo AllowDynamicProperties

### Descripción

public function AllowDynamicProperties::__construct()

Construye una nueva instancia de AllowDynamicProperties.

### Parámetros

Esta función no contiene ningún parámetro.

## Tabla de contenidos

- AllowDynamicProperties::__construct — Construye una nueva instancia del atributo AllowDynamicProperties

# The DelayedTargetValidation attribute

(PHP 8 >= 8.5.0)

## Introducción

This attribute delays target validation errors for internal attributes from compile time to when the attribute is instantiated via the Reflection API.

When applied to a declaration, any invalid usage of internal attributes on the same target will not trigger a compile time error. Instead, the validation is deferred and performed when the attribute is instantiated via ReflectionAttribute::newInstance().

This is primarily intended for forward compatibility, allowing code to use attributes that may gain additional valid targets in future PHP versions without breaking on older versions.

## Sinopsis de la Clase

#[\Attribute]
final class DelayedTargetValidation {
}

## Ejemplos

Ejemplo #1 Delaying validation of an invalid target

    <?php

    class Base {
        protected function foo(): void {}
    }

    class Child extends Base {

        #[\DelayedTargetValidation]
        #[\Override]
        public const NAME = 'child';

        #[\Override]
        protected function foo(): void {}
    }

On PHP versions where Override is not allowed on class constants, this does not produce a compile time error.

Ejemplo #2 Validation occurs during reflection

    <?php

    $reflection = new ReflectionClassConstant(Child::class, 'NAME');

    foreach ($reflection->getAttributes() as $attribute) {
        $attribute->newInstance(); // May throw if invalid
    }

When any attribute applied to the same target (other than DelayedTargetValidation itself) is instantiated via reflection using ReflectionAttribute::newInstance(), target validation is performed and an exception may be thrown if the attribute is used on an unsupported target.

## Notas

This attribute only affects target validation of internal attributes.

It does not suppress functional validation performed by those attributes. For example, Override will still emit an error if a method does not actually override a parent method.

## Ver también

- Attributes overview
- Override

# El atributo Deprecated

(PHP 8 >= 8.4.0)

## Introducción

Este atributo se utiliza para marcar la funcionalidad como obsoleta. El uso de funcionalidad obsoleta hará que se emita un error `E_USER_DEPRECATED`.

## Sinopsis de la Clase

#[\Attribute]
final class Deprecated {
/* Propiedades */
public readonly ?string $message;
public readonly ?string $since;
/* Métodos */
public function __construct(?string `$message` = null, ?string `$since` = null)
}

## Propiedades

message

  Un mensaje opcional que explica la razón de la deprecación y la posible funcionalidad de reemplazo. Se incluirá en el mensaje de deprecación emitido.

since

  Una cadena opcional que indica desde cuándo la funcionalidad está deprecada. El contenido no es validado por PHP y puede contener un número de versión, una fecha o cualquier otro valor que se considere apropiado. Se incluirá en el mensaje de deprecación emitido.

  La funcionalidad que es parte de PHP utilizará Major.Minor como el valor de since, por ejemplo `'8.4'`.

## Ejemplos

    <?php

    #[\Deprecated(message: "use safe_replacement() instead", since: "1.5")]
    function unsafe_function()
    {
       echo "This is unsafe", PHP_EOL;
    }

    unsafe_function();

    ?>

La salida del ejemplo anterior en PHP 8.4 es similar a:

    Deprecated: Function unsafe_function() is deprecated since 1.5, use safe_replacement() instead in example.php on line 9
    This is unsafe

## Ver también

- Visión general de los atributos
- ReflectionFunctionAbstract::isDeprecated()
- ReflectionClassConstant::isDeprecated()
- `E_USER_DEPRECATED`

# Deprecated::__construct

(PHP 8 >= 8.4.0)

Deprecated::__construct — Construye una nueva instancia del atributo Deprecated

### Descripción

public function Deprecated::__construct(?string `$message` = `null`, ?string `$since` = `null`)

Construye una nueva instancia de Deprecated.

### Parámetros

`message`

  El valor de la propiedad message.

`since`

  El valor de la propiedad since.

## Tabla de contenidos

- Deprecated::__construct — Construye una nueva instancia del atributo Deprecated

# El atributo NoDiscard

(PHP 8 >= 8.5.0)

## Introducción

Este atributo se puede utilizar para indicar que el valor de retorno de una función o de un método no debe ser descartado. Si el valor de retorno no se utiliza de ninguna manera, se emitirá una advertencia.

Esto es útil para funciones en las que no comprobar el valor de retorno es probablemente un error.

Para descartar intencionalmente el valor de retorno de dicha función, utilice la conversión (void) para suprimir la advertencia.

> Nota: Dado que los atributos están diseñados para ser retrocompatibles, `#[\NoDiscard]` se puede añadir a funciones y métodos incluso cuando se soportan PHP 8.4 o versiones anteriores, simplemente no hará nada. En PHP 8.5 y superiores se emitirá una advertencia si el resultado no se utiliza. Para suprimir la advertencia sin usar `(void)`, que no es soportado antes de PHP 8.5, considere usar una variable como `$_`.

> Nota: `#[\NoDiscard]` se aplica a la declaración de función o método específica sobre la que está escrito, y la advertencia se emite en función de la declaración que realmente se llama. Como resultado, añadir `#[\NoDiscard]` a un método de interfaz o a un método abstracto no emite ninguna advertencia, porque el método que se invoca es el método de implementación o de sobrescritura. Del mismo modo, un método que sobrescribe un método `#[\NoDiscard]` no emite la advertencia a menos que esté marcado él mismo con el atributo. Por el contrario, un método importado desde un trait conserva el atributo, porque el método del trait se copia en la clase que lo usa como si estuviera declarado allí.

## Sinopsis de la Clase

#[\Attribute]
final class NoDiscard {
/* Propiedades */
public readonly ?string $message;
/* Métodos */
public function __construct(?string `$message` = null)
}

## Propiedades

message
  Un mensaje opcional que explica por qué el valor de retorno no debe ser descartado.

## Ejemplos

Ejemplo #1 Uso básico

    <?php

    /**
     * Processes all the given items and returns an array with the results of the
     * operation for each item. `null` indicates success and an Exception indicates
     * an error. The keys of the result array match the keys of the $items array.
     *
     * @param array<string> $items
     * @return array<null|Exception>
     */
    #[\NoDiscard("as processing might fail for individual items")]
    function bulk_process(array $items): array {
        $results = [];

        foreach ($items as $key => $item) {
            if (\random_int(0, 9999) < 9999) {
                // Pretend to do something useful with $item,
                // which will succeed in 99.99% of cases.
                echo "Processing {$item}", PHP_EOL;
                $error = null;
            } else {
                $error = new \Exception("Failed to process {$item}.");
            }

            $results[$key] = $error;
        }

        return $results;
    }

    bulk_process($items);

    ?>

La salida del ejemplo anterior en PHP 8.5 es similar a:

    Warning: The return value of function bulk_process() should either be used or intentionally ignored by casting it as (void), as processing might fail for individual items

Ejemplo #2 Descartar intencionalmente el valor de retorno

    <?php

    #[\NoDiscard]
    function some_command(): int {
        return 1;
    }

    // Suprimir la advertencia usando (void) - PHP 8.5+
    (void) some_command();

    // Para compatibilidad con versiones de PHP anteriores a 8.5, usar una variable temporal
    $_ = some_command();

    ?>

## Ver también

- Visión general de los atributos

# NoDiscard::__construct

(PHP 8 >= 8.5.0)

NoDiscard::__construct — Construye una nueva instancia del atributo NoDiscard

### Descripción

public function NoDiscard::__construct(?string `$message` = `null`)

Construye una nueva instancia de NoDiscard.

### Parámetros

`message`
  El valor de la propiedad message.

## Tabla de contenidos

- NoDiscard::__construct — Construye una nueva instancia del atributo NoDiscard

# La clase Override

(PHP 8 >= 8.3.0)

## Introducción

Este atributo se utiliza para indicar que un método o una propiedad está destinado a sobrescribir un método o una propiedad de una clase padre o que implementa un método o una propiedad definido en una interfaz.

Si no existe ningún método o propiedad con el mismo nombre en una clase padre o en una interfaz implementada, se emitirá un error de compilación.

El atributo solo puede ser utilizado con el método __construct(), que está excluido de las verificaciones de firma.

## Sinopsis de la Clase

#[\Attribute]
final class Override {
/* Métodos */
public function __construct()
}

## Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | Override puede ser aplicado a propiedades.

## Ejemplos

Ejemplo #1 Uso con métodos

    <?php

    class Base {
        protected function foo(): void {}
    }

    final class Extended extends Base {
        #[\Override]
        protected function boo(): void {}
    }

    ?>

Resultado del ejemplo anterior en PHP 8.3 es similar a:

    Fatal error: Extended::boo() has #[\Override] attribute, but no matching parent method exists

Ejemplo #2 Uso con propiedades

    <?php

    class Base {
        protected string $foo;
    }

    final class Extended extends Base {
        #[\Override]
        protected string $boo;
    }

    ?>

La salida del ejemplo anterior en PHP 8.5 es similar a:

    Fatal error: Extended::$boo has #[\Override] attribute, but no matching parent property exists

## Ver también

- Visión general de los atributos

# Override::__construct

(PHP 8 >= 8.3.0)

Override::__construct — Construye una nueva instancia del atributo Override

### Descripción

public function Override::__construct()

Construye una nueva instancia de Override.

### Parámetros

Esta función no contiene ningún parámetro.

## Tabla de contenidos

- Override::__construct — Construye una nueva instancia del atributo Override

# El atributo ReturnTypeWillChange

(PHP 8 >= 8.1.0)

## Introducción

La mayoría de los métodos internos no finales requieren ahora que los métodos sobrescritos declaren un tipo de retorno compatible, de lo contrario se emite un aviso de deprecación durante la validación de herencia. Esto introduce una fase de tipo de retorno tentativo: el motor emite un aviso de deprecación en lugar de un error fatal cuando los tipos de retorno son incompatibles, antes de que se vuelvan obligatorios en una versión futura. En caso de que el tipo de retorno no pueda declararse para un método sobrescrito debido a preocupaciones de compatibilidad entre versiones de PHP, se puede añadir un atributo `#[\ReturnTypeWillChange]` para silenciar el aviso de deprecación.

Advertencia

El atributo ReturnTypeWillChange suprime los avisos de deprecación únicamente durante la fase de tipo de retorno tentativo. No tiene efecto al sobrescribir métodos definidos en clases definidas por el usuario. Una vez que los métodos internos adopten tipos estrictos, las discrepancias en las firmas de los métodos sobrescritos provocarán un error fatal y este atributo dejará de tener efecto.

## Sinopsis de la Clase

#[\Attribute]
final class ReturnTypeWillChange {
/* Métodos */
public function __construct()
}

## Ver también

Visión general de los atributos

# ReturnTypeWillChange::__construct

(PHP 8 >= 8.1.0)

ReturnTypeWillChange::__construct — Construye una nueva instancia del atributo ReturnTypeWillChange

### Descripción

public function ReturnTypeWillChange::__construct()

Construye una nueva instancia de ReturnTypeWillChange.

### Parámetros

Esta función no contiene ningún parámetro.

## Tabla de contenidos

- ReturnTypeWillChange::__construct — Construye una nueva instancia del atributo ReturnTypeWillChange

# El atributo SensitiveParameter

(PHP 8 >= 8.2.0)

## Introducción

Este atributo se utiliza para marcar un parámetro que es sensible y cuya valor debe ser censurado si está presente en un rastro de pila.

## Sinopsis de la Clase

#[\Attribute]
final class SensitiveParameter {
/* Métodos */
public function __construct()
}

## Ejemplos

    <?php

    function defaultBehavior(
        string $secret,
        string $normal
    ) {
        throw new Exception('Error!');
    }

    function sensitiveParametersWithAttribute(
        #[\SensitiveParameter]
        string $secret,
        string $normal
    ) {
        throw new Exception('Error!');
    }

    try {
        defaultBehavior('password', 'normal');
    } catch (Exception $e) {
        echo $e, PHP_EOL, PHP_EOL;
    }

    try {
        sensitiveParametersWithAttribute('password', 'normal');
    } catch (Exception $e) {
        echo $e, PHP_EOL, PHP_EOL;
    }

    ?>

Resultado del ejemplo anterior en PHP 8.2 es similar a:

    Exception: Error! in example.php:7
    Stack trace:
    #0 example.php(19): defaultBehavior('password', 'normal')
    #1 {main}

    Exception: Error! in example.php:15
    Stack trace:
    #0 example.php(25): sensitiveParametersWithAttribute(Object(SensitiveParameterValue), 'normal')
    #1 {main}

## Ver también

- Visión general de los atributos
- SensitiveParameterValue

# SensitiveParameter::__construct

(PHP 8 >= 8.2.0)

SensitiveParameter::__construct — Construye una nueva instancia de atributo SensitiveParameter

### Descripción

public function SensitiveParameter::__construct()

Construye una nueva instancia de SensitiveParameter.

### Parámetros

Esta función no contiene ningún parámetro.

## Tabla de contenidos

- SensitiveParameter::__construct — Construye una nueva instancia de atributo SensitiveParameter

# Opciones y parámetros de contexto

PHP ofrece varias opciones y parámetros de contexto que pueden utilizarse con todos los sistemas de ficheros y envolturas de flujos. Un contexto se crea con stream_context_create(). Las opciones se establecen con stream_context_set_option(), y los parámetros con stream_context_set_params().

# Opciones de contexto de los sockets

Opciones de contexto de los sockets — Lista de opciones de contexto de los sockets

### Descripción

Las opciones de contexto de los sockets están disponibles para todos los gestores que funcionan a través de los sockets, como `tcp`, `http` y `ftp`.

### Opciones

`bindto`

  Utilizado para especificar la dirección IP (ya sea IPv4 o IPv6), y/o el número del puerto que PHP utilizará para acceder a la red. La sintaxis es `ip:puerto` para las direcciones IPv4, y `[ip]:puerto` para las direcciones IPv6. El hecho de definir la IP o el puerto a `0` permitirá al sistema elegir el puerto y/o la IP por sí mismo.

  > Nota:

  > Dado que FTP crea 2 sockets de conexión durante una operación normal, el número del puerto no puede ser especificado utilizando esta opción.

`backlog`

  Utilizado para limitar el número de conexiones activas en la lista de espera del socket.

  > Nota:

  > Esto solo es aplicable a la función stream_socket_server().

`ipv6_v6only`

  Sustituye el sistema operativo por defecto en cuanto al mapeo de IPv4 en IPv6.

  > Nota:

  > Esto es importante en particular cuando se intenta escuchar en las direcciones IPv4 por separado mientras existe una ligadura en `[::]`.

  > Esto solo es aplicable a la función stream_socket_server().

`so_reuseport`

  Permite múltiples ligaduras de una misma pareja ip:puerto, incluso desde procesos distintos.

  > Nota:

  > Esto solo es aplicable a la función stream_socket_server().

`so_broadcast`

  Permite enviar y recibir datos hacia/desde direcciones de difusión.

  > Nota:

  > Esto solo es aplicable a la función stream_socket_server().

`tcp_nodelay`

  Poner el valor a `true` definirá `SOL_TCP,NO_DELAY=1` correctamente, lo que desactivará el algoritmo TCP Nagle.

### Historial de cambios

Versión | Descripción
--- | ---
7.1.0 | Adición del parámetro `tcp_nodelay`.
7.0.1 | Adición del parámetro `ipv6_v6only`.

### Ejemplos

Ejemplo #1 Ejemplo de uso del parámetro `bindto`

    <?php
    // Conexión a Internet utilizando la IP '192.168.0.100'
    $opts = array(
        'socket' => array(
            'bindto' => '192.168.0.100:0',
        ),
    );

    // Conexión a Internet utilizando la IP '192.168.0.100' y el puerto '7000'
    $opts = array(
        'socket' => array(
            'bindto' => '192.168.0.100:7000',
        ),
    );

    // Conexión a Internet utilizando la dirección IPv6 '2001:db8::1'
    // y el puerto '7000'
    $opts = array(
        'socket' => array(
            'bindto' => '[2001:db8::1]:7000',
        ),
    );

    // Conexión a Internet utilizando el puerto '7000'
    $opts = array(
        'socket' => array(
            'bindto' => '0:7000',
        ),
    );

    // Creación del contexto...
    $context = stream_context_create($opts);

    // ...y se utiliza para recuperar los datos
    echo file_get_contents('http://www.example.com', false, $context);

    ?>

# Opciones de contexto HTTP

Opciones de contexto HTTP — Lista de opciones de contexto HTTP

### Descripción

Opciones de contexto para los protocolos `http://` y `https://`.

### Opciones

`method` string

  `GET`, `POST`, o cualquier otro método HTTP soportado por el servidor remoto.

  Por omisión, vale `GET`.

`header` array o string

  Encabezados adicionales a enviar durante la petición. Los valores de esta opción sobrescribirán otros valores (como `User-agent:`, `Host:`, y `Authentication:`), incluso al seguir redirecciones `Location:`. Por lo tanto, no se recomienda definir el encabezado `Host:`, si `follow_location` está activado.

  Una cadena debe contener pares `Clave : valor` delimitados por `\r\n`, por ejemplo : `"Content-Type: application/json\r\nConnection: close"`. Un array debe contener una lista de pares `Clave : valor`, por ejemplo : `["Content-Type: application/json", "Connection: close"]`.

`user_agent` string

  Valor a enviar con el encabezado `User-Agent:`. Este valor solo debe ser utilizado si el agente de usuario no está especificado en la opción de contexto `header` anterior.

  Por omisión, se utilizará el valor de la opción de configuración user_agent del archivo php.ini.

`content` string

  Los datos adicionales a enviar después de los encabezados. Típicamente utilizados durante las peticiones POST o PUT.

`proxy` string

  URI de la dirección del proxy (ej. `tcp://proxy.example.com:5100`).

`request_fulluri` bool

  Cuando se define como `true`, la URI completa será utilizada al construir la petición (ej. `GET http://www.example.com/path/to/file.html HTTP/1.0`). Aunque este formato de petición no es estándar, algunos servidores de proxy lo requieren.

  Por omisión, vale `false`.

`follow_location` int

  Sigue las redirecciones `Location`. Debe definirse como `0` para desactivar.

  Por omisión, vale `1`.

`max_redirects` int

  El número máximo de redirecciones a seguir. El valor `1` o inferior significa que ninguna redirección será seguida.

  Por omisión, vale `20`.

`protocol_version` float

  Versión del protocolo HTTP.

  Por omisión, vale `1.1` a partir de PHP 8.0.0; antes de esta versión el valor por omisión era `1.0`.

`timeout` float

  Tiempo máximo de espera para la lectura, en forma de float (ej. `10.5`).

  Por omisión, se utilizará el valor de la opción de configuración default_socket_timeout del archivo php.ini.

`ignore_errors` bool

  Obtiene el contenido incluso al recibir un código de error.

  Por omisión, vale `false`.

### Ejemplos

Ejemplo #1 Obtención de una página y envío de datos POST

    <?php

    $postdata = http_build_query(
        [
            'var1' => 'du contenu',
            'var2' => 'doh',
        ]
    );

    $opts = ['http' =>
        [
            'method'  => 'POST',
            'header'  => 'Content-type: application/x-www-form-urlencoded',
            'content' => $postdata,
        ]
    ];

    $context = stream_context_create($opts);

    $result = file_get_contents('http://example.com/submit.php', false, $context);

    ?>

Ejemplo #2 Ignora las redirecciones pero obtiene los encabezados y el contenido

    <?php

    $url = "http://www.example.org/header.php";

    $opts = ['http' =>
        [
            'method' => 'GET',
            'max_redirects' => '0',
            'ignore_errors' => '1',
        ]
    ];

    $context = stream_context_create($opts);
    $stream = fopen($url, 'r', false, $context);

    // información sobre los encabezados y metadatos del flujo
    var_dump(stream_get_meta_data($stream));

    // datos actuales de $url
    var_dump(stream_get_contents($stream));
    fclose($stream);
    ?>

### Notas

> Nota: Opciones de contexto del flujo subyacente
> Opciones de contexto adicionales pueden ser soportadas por el transporte subyacente. Para los flujos `http://`, consulte las opciones de contexto del transporte `tcp://`. Para los flujos `https://`, consulte las opciones de contexto del transporte `ssl://`.

> Nota: Línea de estado HTTP
> Cuando este manejador de flujo sigue una redirección, `wrapper_data`, devuelto por la función stream_get_meta_data() no debe contener necesariamente la línea de estado HTTP que se aplica a los datos de contenido en el índice `0`.

>     array (
>       'wrapper_data' =>
>       array (
>         0 => 'HTTP/1.0 301 Moved Permanently',
>         1 => 'Cache-Control: no-cache',
>         2 => 'Connection: close',
>         3 => 'Location: http://example.com/foo.jpg',
>         4 => 'HTTP/1.1 200 OK',
>         ...

> La primera petición devuelve una `301` (redirección permanente), por lo tanto, el manejador de flujo sigue automáticamente la redirección para obtener una respuesta `200` (índice = `4`).

### Ver también

- http://
- Opciones de contexto de los sockets
- Opciones de contexto SSL

# Opciones de contexto FTP

Opciones de contexto FTP — Lista de opciones de contexto FTP

### Descripción

Opciones de contexto para los protocolos `ftp://` y `ftps://`.

### Opciones

`overwrite` bool

  Permite sobrescribir los ficheros existentes en el servidor remoto. Solo se aplica en modo de escritura.

  Por omisión, `false`.

`resume_pos` int

  Posición en el fichero a partir de la cual se inicia la transferencia. Solo se aplica en modo de escritura.

  Por omisión, vale `0` (Inicio del fichero).

`proxy` string

  URI de la dirección del proxy FTP. Solo se aplica a las operaciones de lectura de ficheros. Por ejemplo: `tcp://squid.example.com:8000`.

### Notas

> Nota: Opciones de contexto del flujo subyacente
> Opciones de contexto adicionales pueden ser soportadas por el transporte subyacente. Para los flujos `ftp://`, refiérase a las opciones de contexto del transporte `tcp://`. Para los flujos `ftps://`, refiérase a las opciones de contexto del transporte `ssl://`.

### Ver también

- ftp://
- Opciones de contexto de los sockets
- Opciones de contexto SSL

# Opciones de contexto SSL

Opciones de contexto SSL — Lista de opciones de contexto SSL

### Descripción

Opciones de contexto para los protocolos `ssl://` y `tls://`.

### Opciones

`peer_name` string

  Nombre de pares a utilizar. Si este valor no está definido, entonces el nombre será adivinado basándose en el nombre de host utilizado al abrir el flujo.

`verify_peer` bool

  Requiere una verificación del certificado SSL utilizado.

  Por omisión, vale `true`.

`verify_peer_name` bool

  Requiere la verificación del nombre de pares.

  Por omisión, vale `true`.

`allow_self_signed` bool

  Permite los certificados autofirmados. Requiere el parámetro `verify_peer`.

  Por omisión, vale `false`

`cafile` string

  Ubicación del fichero de la autoridad del certificado en el sistema de ficheros local que deberá ser utilizado con la opción de contexto `verify_peer` para identificar el par distante.

`capath` string

  Si `cafile` no está especificado o si el certificado no ha sido encontrado, se realizará una búsqueda en el directorio señalado por `capath` para encontrar un certificado válido. `capath` debe ser un directorio de certificados válido.

`local_cert` string

  Ruta al certificado local, en el sistema de ficheros. Debe ser un fichero codificado PEM que contiene su certificado y su clave privada. Puede, opcionalmente, contener la cadena de certificación del emisor. La clave privada también puede estar contenida en un fichero separado especificado por `local_pk`.

`local_pk` string

  Ruta de acceso al fichero de clave privada local en el sistema de ficheros en el caso de ficheros separados para el certificado (`local_cert`) y la clave privada.

`passphrase` string

  La frase de paso con la que su fichero `local_cert` ha sido codificado.

`verify_depth` int

  Fallará si la cadena de certificación es demasiado profunda.

  Por omisión, no se realiza ninguna verificación.

`ciphers` string

  Define la lista de cifrados. El formato de la cadena está descrito en la página » ciphers(1).

  Por omisión, vale `DEFAULT`.

`capture_peer_cert` bool

  Si se define a `true`, se creará una opción de contexto `peer_certificate` que contendrá el certificado del emisor.

`capture_peer_cert_chain` bool

  Si se define a `true`, se creará una opción de contexto `peer_certificate_chain` que contendrá la cadena de certificación.

`SNI_enabled` bool

  Si vale `true`, la indicación sobre el nombre del servidor estará activada. Activar SNI permite utilizar múltiples certificados en la misma dirección IP.

`disable_compression` bool

  Si se define, la compresión TLS estará desactivada. Esto puede ayudar a mitigar el vector de ataque CRIME.

`peer_fingerprint` string | array

  Se detiene cuando el digest del certificado distante no coincide con el hash especificado.

  Cuando se utiliza una string, la longitud determinará el algoritmo de hachaje utilizado, ya sea "md5" (32) o "sha1" (40).

  Cuando se utiliza un array, la clave indica el nombre del algoritmo de hachaje, y cada valor correspondiente representa el digest esperado.

`security_level` int

  Define el nivel de seguridad. Si no se especifica, se utiliza el nivel de seguridad por omisión. Los niveles de seguridad están descritos en » SSL_CTX_get_security_level(3).

  Disponible a partir de PHP 7.2.0 y OpenSSL 1.1.0.

### Historial de cambios

Versión | Descripción
--- | ---
7.2.0 | Adición de `security_level`. Requiere OpenSSL >= 1.1.0.

### Notas

> Nota: Dado que `ssl://` es un protocolo subyacente para los gestores `https://` y `ftps://`, todas las opciones de contexto aplicadas a `ssl://` también se aplicarán a `https://` y `ftps://`.

> Nota: Para que SNI (Server Name Indication) esté disponible, PHP debe ser compilado con OpenSSL 0.9.8j o superior. Utilice la constante `OPENSSL_TLSEXT_SERVER_NAME` para determinar si SNI es soportado o no.

### Ver también

- Opciones de contexto de los sockets

# Opciones de contexto Phar

Opciones de contexto Phar — Listado de opciones de contexto Phar

### Descripción

Opciones de contexto para `phar://` envoltura.

### Opciones

`comprimir` int

  Uno de Constantes de compresión Phar.

`metadata` mixed

  Metadatos Phar. Ver Phar::setMetadata().

### Ver también

- phar://
- Envoltura de secuencias Phar

# Contexto parámetros

Contexto parámetros — Listado de parámetros de contexto

### Descripción

Estos `parametros` se pueden establecer en un `contexto` usando el la función stream_context_set_params().

### Parámetros

`notification` callable

  Un valor de tipo callable que se llamará cuando se produce un evento en un flujo.

  Véase stream_notification_callback para más detalles.

# Opciones de contexto Zip

Opciones de contexto Zip — Listado de opciones de contexto Zip

### Descripción

Las opciones de contexto Zip están disponibles para las envolturas (wrappers) `zip`.

### Opciones

`password`

  Utilizado para especificar una contraseña a utilizar para los archivos cifrados.

### Historial de cambios

Versión | Descripción
--- | ---
7.2.0, PECL zip 1.14.0 | Adición del parámetro `password`.

### Ejemplos

Ejemplo #1 Ejemplo con una utilización simple del parámetro `password`

    <?php
    // Leer el archivo cifrado
    $opts = array(
        'zip' => array(
            'password' => 'secret',
        ),
    );
    // crear el contexto...
    $context = stream_context_create($opts);

    // ...y utilizarlo para recuperar los datos
    echo file_get_contents('zip://test.zip#test.txt', false, $context);

    ?>

# Opciones de contexto Zlib

Opciones de contexto Zlib — Lista de opciones de contexto Zlib

### Descripción

Las opciones de contexto Zlib están disponibles para las envolturas `zlib`.

### Opciones

`level`

  Permite especificar el nivel de compresión`(0` - `9`).

### Historial de cambios

Versión | Descripción
--- | ---
7.3.0 | `level` ha sido añadido.

## Tabla de contenidos

- Opciones de contexto de los sockets — Lista de opciones de contexto de los sockets
- Opciones de contexto HTTP — Lista de opciones de contexto HTTP
- Opciones de contexto FTP — Lista de opciones de contexto FTP
- Opciones de contexto SSL — Lista de opciones de contexto SSL
- Opciones de contexto Phar — Listado de opciones de contexto Phar
- Contexto parámetros — Listado de parámetros de contexto
- Opciones de contexto Zip — Listado de opciones de contexto Zip
- Opciones de contexto Zlib — Lista de opciones de contexto Zlib

# Protocolos y Envolturas soportados

PHP incorpora de serie envolturas para distintos protocolos tipo URL para trabajar junto con funciones del sistema de ficheros, como fopen(), copy(), file_exists() y filesize(). Además de estas envolturas, se pueden definir por el usuario utilizando la función stream_wrapper_register().

> Nota: La sintaxis de URL que se utiliza para describir una envoltura solo puede ser `scheme://...`. Las sintaxis `scheme:/` y `scheme:` no están soportadas.

# file://

file:// — Acceso al sistema de ficheros local

### Descripción

`file://` es la envoltura por defecto utilizada con PHP y representa el sistema de ficheros local. Cuando se especifica una ruta relativa (una ruta que no comienza con `/`, `\`, `\\`, o una letra de unidad Windows), la ruta proporcionada se aplicará al directorio de trabajo actual. En muchos casos, se trata del directorio en el que se encuentra el script, a menos que haya sido modificado. Con el CLI SAPI, esto por defecto corresponde al directorio desde el cual se llamó al script.

Con ciertas funciones como fopen() y file_get_contents(), `include_path` puede eventualmente ser analizada para encontrar los ficheros, si se proporciona una ruta relativa.

### Uso

- /ruta/al/fichero.ext
- ruta/relativa/al/fichero.ext
- ficheroEnCwd.ext
- C:/ruta/al/ficheroWindows.ext
- C:\ruta\al\ficheroWindows.ext
- \\smbserver\compartido\ruta\al\ficheroWindows.ext
- file:///ruta/al/fichero.ext

### Opciones

Resumen de la envoltura
Atributo | Soportado
--- | ---
Restringido por allow_url_fopen | No
Permite la lectura | Sí
Permite la escritura | Sí
Permite la adición | Sí
Permite simultáneamente la lectura y la escritura | Sí
Soporte de la función stat() | Sí
Soporte de la función unlink() | Sí
Soporte de la función rename() | Sí
Soporte de la función mkdir() | Sí
Soporte de la función rmdir() | Sí

# http://

# https://

http:// -- https:// — Acceso a URLs HTTP(s)

### Descripción

Permite el acceso en modo solo lectura a ficheros accesibles mediante HTTP. Por omisión, se utiliza una solicitud HTTP 1.0 GET. Se envía un encabezado `Host:` con la solicitud, para gestionar los hosts virtuales basados en nombres. Si se ha configurado una versión de navegador con la opción user_agent en su archivo php.ini o mediante el contexto de flujo, también será incluida en su solicitud.

El flujo permite acceder al cuerpo (body) del recurso. Los encabezados se almacenan en la variable $http_response_header.

Si se necesita conocer la URL del recurso desde el cual proviene el documento (tras la ejecución de todas las redirecciones), deberá analizarse la serie de encabezados devueltos por el flujo.

La directiva from será utilizada para el encabezado `From:` si ha sido definida, y no será sobrescrita por los Opciones y parámetros de contexto.

### Uso

- http://example.com
- http://example.com/fichero.php?var1=val1&var2=val2
- http://user:password@example.com
- https://example.com
- https://example.com/fichero.php?var1=val1&var2=val2
- https://user:password@example.com

### Opciones

Resumen de la envoltura
Atributo | Soportado
--- | ---
Restringido por allow_url_fopen | Sí
Permite la lectura | Sí
Permite la escritura | No
Permite la adición | No
Permite la lectura y escritura simultáneamente | N/A
Soporte de la función stat() | No
Soporte de la función unlink() | No
Soporte de la función rename() | No
Soporte de la función mkdir() | No
Soporte de la función rmdir() | No

### Ejemplos

Ejemplo #1 Detecta la última URL tras redirecciones

    <?php
    $url = 'http://www.example.com/redirecting_page.php';

    $fp = fopen($url, 'r');

    $meta_data = stream_get_meta_data($fp);
    foreach ($meta_data['wrapper_data'] as $response) {

        /* ¿Hemos sido redirigidos? */
        if (strtolower(substr($response, 0, 10)) == 'location: ') {

            /* actualización de $url con la ruta tras redirección */
            $url = substr($response, 10);
        }

    }

    ?>

### Notas

> Nota: HTTPS solo es soportado si la extensión openssl está activa.

Las conexiones HTTP son de solo lectura; la escritura de datos o la copia de ficheros a un recurso HTTP no son soportadas.

El envío de solicitudes POST y PUT, por ejemplo, puede realizarse mediante los contextos HTTP.

### Ver también

- Opciones de contexto HTTP
- $http_response_header
- stream_get_meta_data() - Lee los encabezados y metadatos de los flujos

# ftp://

# ftps://

ftp:// -- ftps:// — Acceso a URLs FTP(s)

### Descripción

Permite el acceso en lectura a los ficheros existentes, y la creación de ficheros, mediante FTP. Si el servidor no soporta FTP en modo pasivo, la conexión fallará.

Se pueden abrir ficheros en lectura o en escritura, pero no ambas a la vez. Si el fichero remoto ya existe en el servidor ftp y se intenta abrirlo en escritura sin haber especificado la opción `overwrite` en el contexto, la conexión fallará. Si se deben sobrescribir ficheros existentes utilizando ftp, se debe especificar la opción `overwrite` en el contexto y abrir el fichero en escritura. Alternativamente, se puede utilizar la extensión FTP.

Si se ha definido la directiva from en el fichero php.ini, entonces este valor será enviado como contraseña para los accesos FTP anónimos.

### Uso

- ftp://example.com/pub/fichero.txt
- ftp://user:password@example.com/pub/fichero.txt
- ftps://example.com/pub/fichero.txt
- ftps://user:password@example.com/pub/fichero.txt

### Opciones

Resumen de la envoltura
Atributo | Soportado
--- | ---
Restringido por allow_url_fopen | Sí
Permite la lectura | Sí
Permite la escritura | Sí (nuevos ficheros/ficheros existentes con el parámetro `overwrite`)
Permite el añadido | Sí
Permite la lectura y escritura simultáneamente | No
Soporte de la función stat() | filesize(), filetype(), file_exists(), is_file(), is_dir(), y filemtime() únicamente.
Soporte de la función unlink() | Sí
Soporte de la función rename() | Sí
Soporte de la función mkdir() | Sí
Soporte de la función rmdir() | Sí

### Notas

> Nota:

> FTPS solo es soportado cuando la extensión openssl está activa.

> Si el servidor no soporta SSL, entonces la conexión pasará automáticamente a una conexión ftp no cifrada.

> Nota: El añadido
> El añadido de información a un fichero es posible con el gestor de URL `ftp://`.

### Ver también

- Opciones de contexto FTP

# php://

php:// — Acceso a los diversos flujos I/O

### Descripción

PHP proporciona un número importante de flujos I/O que permiten acceder a los flujos de entrada y salida de PHP mismo, a los descriptores de ficheros de entrada, salida y error estándar, a flujos que representan ficheros temporales en memoria viva o en disco, así como a filtros que pueden manipular otros recursos de ficheros durante la lectura o escritura.

#### php://stdin, php://stdout y php://stderr

php://stdin, php://stdout y php://stderr permiten acceso directo a los flujos de entrada o salida correspondientes del proceso PHP. El flujo hace referencia a una copia del descriptor de fichero, lo que significa que si se abre php://stdin y se cierra más tarde, solo se cierra la copia del descriptor; el flujo realmente referenciado por `STDIN` no se ve afectado. Se recomienda utilizar únicamente las constantes `STDIN`, `STDOUT` y `STDERR` en lugar de abrir manualmente los flujos utilizando estas envolturas.

php://stdin es de solo lectura, mientras que php://stdout y php://stderr son de solo escritura.

#### php://input

php://input es un flujo de solo lectura que permite leer datos sin tratar desde el cuerpo de la petición. php://input no está disponible en las peticiones POST con `enctype="multipart/form-data"` si la opción enable_post_data_reading está activada.

#### php://output

php://output es un flujo de solo escritura, que permite escribir en el mecanismo de buffer de salida de la misma manera que las funciones print y echo.

#### php://fd

php://fd permite acceso directo al descriptor de fichero especificado. Por ejemplo, php://fd/3 corresponde al descriptor de fichero número 3.

#### php://memory y php://temp

php://memory y php://temp son flujos de lectura/escritura que permiten almacenar datos temporales en una envoltura de ficheros. Una diferencia entre estos dos flujos es que php://memory almacenará siempre sus datos en memoria, mientras que php://temp utilizará un fichero temporal una vez que la cantidad de datos almacenados haya superado un límite predefinido (por omisión, 2 Mo). La ubicación de este fichero temporal se determina de la misma manera que para la función sys_get_temp_dir().

El límite de memoria de php://temp puede ser controlado añadiendo `/maxmemory:NN`, donde `NN` es la cantidad máxima de datos a conservar en memoria antes de utilizar un fichero temporal, en bytes.

Precaución

Algunas extensiones PHP pueden requerir un flujo IO estándar, y pueden intentar convertir un flujo dado a un flujo IO estándar. Esta conversión puede fallar para los flujos de memoria, ya que la función C fopencookie() debe estar disponible. Esta función C no está disponible en Windows.

#### php://filter

php://filter es una especie de envoltura prevista para permitir la aplicación de filtros sobre un flujo en el momento de su apertura. Esto es muy práctico con funciones sobre ficheros todas-en-una como las funciones readfile(), file() y file_get_contents(), donde no existe otro mecanismo que permita aplicar un filtro al flujo antes de que el contenido sea leído.

La meta de php://filter toma los parámetros siguientes bajo la forma de componentes de su ruta. Varios filtros encadenados pueden ser especificados en una sola ruta. Consúltese los ejemplos para un uso correcto de estos parámetros.

Parámetros de php://filter
Nombre | Descripción
--- | ---
`resource=<flujo a filtrar>` | Este parámetro es requerido. Especifica el flujo que se desea filtrar.
`read=<lista de filtros a aplicar a la lectura>` | Este parámetro es opcional. Uno o más nombres de filtros pueden ser proporcionados aquí, separados por un carácter pipe (`|`).
`write=<lista de filtros a aplicar a la escritura>` | Este parámetro es opcional. Uno o más nombres de filtros pueden ser proporcionados aquí, separados por un carácter pipe (`|`).
`<lista de filtros a aplicar tanto a la lectura como a la escritura>` | Todos los filtros proporcionados sin ser prefijados por `read=` o `write=` serán aplicados tanto a la lectura como a la escritura.

### Opciones

Resumen de la envoltura (para `php://filter`, consúltese el resumen de la envoltura a filtrar)
Atributo | Soportado
--- | ---
Restringido por allow_url_fopen | No
Restringido por allow_url_include | `php://input`, `php://stdin`, `php://memory` y `php://temp` únicamente.
Permite la lectura | `php://stdin`, `php://input`, `php://fd`, `php://memory` y `php://temp` únicamente.
Permite la escritura | `php://stdout`, `php://stderr`, `php://output`, `php://fd`, `php://memory` y `php://temp` únicamente.
Permite la adición | `php://stdout`, `php://stderr`, `php://output`, `php://fd`, `php://memory` y `php://temp` únicamente. (Equivalente a la escritura)
Permite tanto la lectura como la escritura | `php://fd`, `php://memory` y `php://temp` únicamente.
Soporte de la función stat() | No. Sin embargo, `php://memory` y `php://temp` soportan fstat().
Soporte de la función unlink() | No
Soporte de la función rename() | No
Soporte de la función mkdir() | No
Soporte de la función rmdir() | No
Soporte de la función stream_select() | `php://stdin`, `php://stdout`, `php://stderr`, `php://fd` y `php://temp` únicamente.

### Ejemplos

Ejemplo #1 php://temp/maxmemory

Este parámetro opcional permite configurar el límite de memoria antes de que php://temp comience a utilizar un fichero temporal.

    <?php
    // Define el límite a 5 Mo.
    $fiveMBs = 5 * 1024 * 1024;
    $fp = fopen("php://temp/maxmemory:$fiveMBs", 'r+');

    fputs($fp, "hello\n");

    // Lee lo que acabamos de escribir.
    rewind($fp);
    echo stream_get_contents($fp);
    ?>

Ejemplo #2 php://filter/resource=<flujo a filtrar>

Este parámetro debe ser colocado al final de la especificación de php://filter y debe apuntar al flujo que se desea filtrar.

    <?php
    /* Esto es equivalente a
      readfile("http://www.example.com");
      ya que no se especifica ningún filtro */

    readfile("php://filter/resource=http://www.example.com");
    ?>

Ejemplo #3 php://filter/read=<lista de filtros a aplicar a la lectura>

Este parámetro toma uno o más nombres de filtros separados por un carácter pipe `|`.

    <?php
    /* Esto mostrará el contenido de
      www.example.com completamente en mayúsculas */
    readfile("php://filter/read=string.toupper/resource=http://www.example.com");

    /* Esto hará lo mismo que el anterior,
      pero codificará además el resultado en ROT13 */
    readfile("php://filter/read=string.toupper|string.rot13/resource=http://www.example.com");
    ?>

Ejemplo #4 php://filter/write=<lista de filtros a aplicar a la escritura>

Este parámetro toma uno o más nombres de filtros separados por un carácter pipe `|`.

    <?php
    /* Esto filtrará la cadena "Hello World"
      a través del filtro rot13, y luego escribirá el resultado
      en el fichero example.txt del directorio actual */
    file_put_contents("php://filter/write=string.rot13/resource=example.txt","Hello World");
    ?>

Ejemplo #5 php://memory y php://temp no son reutilizables

php://memory y php://temp no son reutilizables, es decir, después de que los flujos hayan sido cerrados no hay manera de referenciarlos nuevamente.

    <?php
    file_put_contents('php://memory', 'PHP');
    echo file_get_contents('php://memory'); // no muestra nada

Ejemplo #6 php://input para leer datos JSON del cuerpo de la solicitud

Este ejemplo demuestra cómo leer datos JSON sin procesar de solicitudes POST, PUT y PATCH usando php://input.

    <?php
    $input = file_get_contents("php://input");
    $json_array = json_decode(
      json: $input,
      associative: true,
      flags: JSON_THROW_ON_ERROR
    );

    echo "Datos JSON recibidos: ";
    print_r($json_array);
    ?>

# zlib://

# bzip2://

# zip://

zlib:// -- bzip2:// -- zip:// — Flujos de compresión

### Descripción

compress.zlib:// y compress.bzip2://

zlib: funciona como gzopen(), excepto que el flujo puede ser utilizado directamente con fread() y otras funciones del sistema de archivos. Esta notación está obsoleta debido a ambigüedades con nombres de archivos que contienen dos puntos ':'. Utilice en su lugar compress.zlib://.

compress.zlib:// y compress.bzip2:// son equivalentes respectivamente a gzopen() y bzopen(), y funcionan incluso en sistemas que no soportan fopencookie.

La extensión ZIP proporciona el envoltorio zip:. A partir de PHP 7.2.0 y libzip 1.2.0+, se ha añadido el soporte para contraseñas en archivos cifrados, permitiendo que las contraseñas sean proporcionadas por contextos de flujo. Las contraseñas pueden ser definidas en un flujo utilizando la opción de contexto `'password'`.

### Uso

- compress.zlib://file.gz
- compress.bzip2://file.bz2
- zip://archive.zip#dir/file.txt

### Opciones

Resumen de envolturas
Atributo | Soportado
--- | ---
Limitado por allow_url_fopen | No
Permite la lectura | Sí
Permite la escritura | Sí (excepto `zip://`)
Permite la adición | Sí (excepto `zip://`)
Permite la lectura y escritura simultáneamente | No
Soporte de la función stat() | No, utilice el gestor `file://` para obtener información sobre archivos comprimidos.
Soporte de la función unlink() | No, utilice el gestor `file://` para obtener información sobre archivos comprimidos.
Soporte de la función rename() | No
Soporte de la función mkdir() | No
Soporte de la función rmdir() | No

### Ver también

- Opciones de contexto Zlib

# data://

data:// — Datos (RFC 2397)

### Descripción

La envoltura de flujo data: (» RFC 2397).

### Uso

- data://text/plain;base64,

### Opciones

Resumen de la envoltura
Atributo | Soportado
--- | ---
Restringido por allow_url_fopen | Sí
Restringido por allow_url_include | Sí
Permite la lectura | Sí
Permite la escritura | No
Permite la adición | No
Permite la lectura y escritura simultáneamente | No
Soporte de la función stat() | No
Soporte de la función unlink() | No
Soporte de la función rename() | No
Soporte de la función mkdir() | No
Soporte de la función rmdir() | No

### Ejemplos

Ejemplo #1 Mostrar un contenido data://

    <?php
    // Muestra "I love PHP"
    echo file_get_contents('data://text/plain;base64,SSBsb3ZlIFBIUAo=');
    ?>

Ejemplo #2 Obtención del tipo de medio

    <?php
    $fp   = fopen('data://text/plain;base64,', 'r');
    $meta = stream_get_meta_data($fp);

    // Muestra "text/plain"
    echo $meta['mediatype'];
    ?>

# glob://

glob:// — Encuentra nombres de ficheros que coinciden con un patrón dado

### Descripción

La envoltura de flujo glob:.

### Uso

- glob://

### Opciones

Resumen de la envoltura
Atributo | Soportado
--- | ---
Restringido por allow_url_fopen | No
Restringido por allow_url_include | No
Permite la lectura | No
Permite la escritura | No
Permite la adición | No
Permite la lectura y escritura simultáneamente | No
Soporte de la función stat() | No
Soporte de la función unlink() | No
Soporte de la función rename() | No
Soporte de la función mkdir() | No
Soporte de la función rmdir() | No

### Ejemplos

Ejemplo #1 Uso simple

    <?php
    // Recorre todos los ficheros *.php en el directorio ext/spl/examples/ y
    // muestra el nombre del fichero así como su tamaño
    $it = new DirectoryIterator("glob://ext/spl/examples/*.php");
    foreach($it as $f) {
        printf("%s: %.1FK\n", $f->getFilename(), $f->getSize()/1024);
    }
    ?>

    tree.php: 1.0K
    findregex.php: 0.6K
    findfile.php: 0.7K
    dba_dump.php: 0.9K
    nocvsdir.php: 1.1K
    phar_from_dir.php: 1.0K
    ini_groups.php: 0.9K
    directorytree.php: 0.9K
    dba_array.php: 1.1K
    class_tree.php: 1.8K

# phar://

phar:// — Archivo PHP

### Descripción

La envoltura de flujo phar://. Véase envoltura de flujo Phar para una descripción detallada.

### Uso

- phar://

### Opciones

Resumen de la envoltura
Atributo | Soportado
--- | ---
Restringido por allow_url_fopen | No
Restringido por allow_url_include | No
Permite la lectura | Sí
Permite la escritura | Sí
Permite la adición | No
Permite la lectura y escritura simultáneamente | Sí
Soporte de la función stat() | Sí
Soporte de la función unlink() | Sí
Soporte de la función rename() | Sí
Soporte de la función mkdir() | Sí
Soporte de la función rmdir() | Sí

### Ver también

- Opciones de contexto Phar

# ssh2://

ssh2:// — Shell seguro 2

### Descripción

ssh2.shell:// ssh2.exec:// ssh2.tunnel:// ssh2.sftp:// ssh2.scp:// (PECL)

> Nota: Esta envoltura no está activada por omisión
> Para utilizar la envoltura ssh2://, la extensión » SSH2 disponible en » PECL debe ser instalada.

Además de aceptar las identificaciones tradicionales mediante la URI, la envoltura ssh2 reutilizará las conexiones abiertas pasando la recurso de conexión en la parte host de la URL.

### Uso

- ssh2.shell://user:pass@example.com:22/xterm
- ssh2.exec://user:pass@example.com:22/usr/local/bin/somecmd
- ssh2.tunnel://user:pass@example.com:22/192.168.0.1:14
- ssh2.sftp://user:pass@example.com:22/path/to/filename

### Opciones

Resumen de la envoltura
Atributo | ssh2.shell | ssh2.exec | ssh2.tunnel | ssh2.sftp | ssh2.scp
--- | --- | --- | --- | --- | ---
Restringido por allow_url_fopen | Sí | Sí | Sí | Sí | Sí
Permite la lectura | Sí | Sí | Sí | Sí | Sí
Permite la escritura | Sí | Sí | Sí | Sí | No
Permite el añadido | No | No | No | Sí (cuando sea soportado por el servidor) | No
Permite la lectura y escritura simultáneamente | Sí | Sí | Sí | Sí | No
Soporte de la función stat() | No | No | No | Sí | No
Soporte de la función unlink() | No | No | No | Sí | No
Soporte de la función rename() | No | No | No | Sí | No
Soporte de la función mkdir() | No | No | No | Sí | No
Soporte de la función rmdir() | No | No | No | Sí | No

Opciones de contexto
Nombre | Uso | Por omisión
--- | --- | ---
`session` | recurso ssh2 pre-conectado para reutilizar |
`sftp` | recurso sftp pre-asignado para reutilizar |
`methods` | métodos de intercambio de claves, hostkey, cifrado, compresión y MAC a utilizar |
`callbacks` |  |
`username` | Nombre de usuario para la conexión |
`password` | Contraseña a utilizar durante la identificación por contraseña |
`pubkey_file` | Nombre del archivo que contiene la clave pública a utilizar durante la identificación |
`privkey_file` | Nombre del archivo que contiene la clave privada a utilizar durante la identificación |
`env` | Array asociativo de variables de entorno a definir |
`term` | Tipo de emulación de terminal a solicitar durante la asignación de un pty |
`term_width` | Ancho del terminal a solicitar durante la asignación de un pty |
`term_height` | Alto del terminal a solicitar durante la asignación de un pty |
`term_units` | Unidades a utilizar con term_width y term_height | `SSH2_TERM_UNIT_CHARS`

### Ejemplos

Ejemplo #1 Apertura de un flujo desde una conexión activa

    <?php
    $session = ssh2_connect('example.com', 22);
    ssh2_auth_pubkey_file($session, 'username', '/home/username/.ssh/id_rsa.pub',
                                                '/home/username/.ssh/id_rsa', 'secret');
    $stream = fopen("ssh2.tunnel://$session/remote.example.com:1234", 'r');
    ?>

Ejemplo #2 La variable $session debe permanecer disponible

Para utilizar la envoltura ssh2.*://$session, la variable de recurso $session debe ser conservada. El código a continuación no tendrá el efecto deseado:

    <?php
    $session = ssh2_connect('example.com', 22);
    ssh2_auth_pubkey_file($session, 'username', '/home/username/.ssh/id_rsa.pub',
                                                '/home/username/.ssh/id_rsa', 'secret');
    $connection_string = "ssh2.sftp://$session/";
    unset($session);
    $stream = fopen($connection_string . "path/to/file", 'r');
    ?>

La función unset() cierra la sesión, ya que la variable $connection_string no contiene una referencia a la variable $session, sino solo una cadena derivada. Esto también ocurre cuando la función unset() es implícita, durante una salida del ámbito (como en una función).

# rar://

rar:// — RAR

### Descripción

Esta envoltura toma la ruta codificada URL hacia el archivo RAR (relativo o absoluto), luego, opcionalmente, un asterisco (`*`), opcionalmente seguido de un signo de número (`#`), y, siempre opcionalmente, un nombre de entrada codificado URL, tal como se almacena en el archivo. La especificación de un nombre de entrada requiere la presencia del signo de número; la presencia de una barra al inicio del nombre de la entrada es opcional.

Esta envoltura puede abrir tanto ficheros como directorios. Al abrir directorios, el asterisco fuerza a que los nombres de los directorios sean devueltos sin codificar. Si no se especifica, serán devueltos en forma codificada URL - esto permite que la envoltura sea utilizada correctamente con funcionalidades internas como RecursiveDirectoryIterator en presencia de nombres de ficheros que parecen estar codificados URL.

Si el signo de número y el nombre de la entrada no están incluidos, se mostrará la raíz del archivo. Esta visualización es diferente de los directorios regulares en el sentido de que el flujo resultante no contendrá información como la fecha y hora de modificación, ya que la raíz del directorio no se almacena como una entrada individual en el archivo. El uso de esta envoltura con RecursiveDirectoryIterator requiere la presencia del signo de número en la URL al acceder a la raíz, para construir correctamente las URLs de los hijos.

> Nota: Esta envoltura no está activada por defecto
> Para utilizar la envoltura rar://, la extensión » rar disponible en » PECL debe estar instalada.

rar:// está disponible a partir de PECL rar 3.0.0

### Uso

- rar://<nombre de archivo codificado URL>[*][#<nombre de entrada codificado URL>]]

### Opciones

Resumen de la envoltura
Atributo | Soportado
--- | ---
Restringido por allow_url_fopen | No
Restringido por allow_url_include | No
Permite la lectura | Sí
Permite la escritura | No
Permite la adición | No
Permite la lectura y escritura simultáneamente | No
Soporte de la función stat() | Sí
Soporte de la función unlink() | No
Soporte de la función rename() | No
Soporte de la función mkdir() | No
Soporte de la función rmdir() | No

Opciones de contexto
Nombre | Uso | Por omisión
--- | --- | ---
`open_password` | La contraseña utilizada para cifrar los encabezados del archivo, si los hay. WinRAR cifrará todos los ficheros con la misma contraseña que los encabezados cuando esta esté presente, por lo tanto, para archivos con encabezados cifrados, `file_password` será ignorado. |
`file_password` | La contraseña utilizada para cifrar un fichero, si la hay. Si los encabezados también están cifrados, esta opción será ignorada y se privilegiará la contraseña de la opción `open_password`. La razón por la que hay 2 opciones es el deseo de poder cubrir la posibilidad de soportar archivos con diferentes contraseñas para los encabezados y los ficheros. Tenga en cuenta que si el encabezado del archivo no está cifrado, la opción `open_password` será ignorada y esta opción debe ser utilizada en su lugar. |
`volume_callback` | Una función de devolución de llamada para determinar la ruta de los volúmenes faltantes. Consulte el método RarArchive::open() para obtener más información. |

### Ejemplos

Ejemplo #1 Recorrido de un archivo RAR

    <?php

    class MyRecDirIt extends RecursiveDirectoryIterator {
        function current() {
            return rawurldecode($this->getSubPathName()) .
                (is_dir(parent::current())?" [DIR]":"");
        }
    }

    $f = "rar://" . rawurlencode(dirname(__FILE__)) .
        DIRECTORY_SEPARATOR . 'dirs_and_extra_headers.rar#';

    $it = new RecursiveTreeIterator(new MyRecDirIt($f));

    foreach ($it as $s) {
        echo $s, "\n";
    }
    ?>

Resultado del ejemplo anterior es similar a:

    |-allow_everyone_ni [DIR]
    |-file1.txt
    |-file2_אּ.txt
    |-with_streams.txt
    \-אּ [DIR]
      |-אּ\%2Fempty%2E [DIR]
      | \-אּ\%2Fempty%2E\file7.txt
      |-אּ\empty [DIR]
      |-אּ\file3.txt
      |-אּ\file4_אּ.txt
      \-אּ\אּ_2 [DIR]
        |-אּ\אּ_2\file5.txt
        \-אּ\אּ_2\file6_אּ.txt

Ejemplo #2 Apertura de un fichero cifrado (encabezado cifrado)

    <?php
    $stream = fopen("rar://" .
        rawurlencode(dirname(__FILE__)) . DIRECTORY_SEPARATOR .
        'encrypted_headers.rar' . '#encfile1.txt', "r", false,
        stream_context_create(
            array(
                'rar' =>
                    array(
                        'open_password' => 'samplepassword'
                    )
                )
            )
        );
    var_dump(stream_get_contents($stream));
    /* Las fechas de creación y último acceso son opcionales con WinRAR,
     * lo que explica que la mayoría de los ficheros no las tengan */
    var_dump(fstat($stream));
    ?>

Resultado del ejemplo anterior es similar a:

    string(26) "Encrypted file 1 contents."
    Array
    (
        [0] => 0
        [1] => 0
        [2] => 33206
        [3] => 1
        [4] => 0
        [5] => 0
        [6] => 0
        [7] => 26
        [8] => 0
        [9] => 1259550052
        [10] => 0
        [11] => -1
        [12] => -1
        [dev] => 0
        [ino] => 0
        [mode] => 33206
        [nlink] => 1
        [uid] => 0
        [gid] => 0
        [rdev] => 0
        [size] => 26
        [atime] => 0
        [mtime] => 1259550052
        [ctime] => 0
        [blksize] => -1
        [blocks] => -1
    )

# ogg://

ogg:// — Flujos de audio

### Descripción

Los ficheros que se abran para lectura usando la envoltura ogg:// se utilizan como codificaciones de audio comprimido usando el códec `OGG/Vorbis`. De forma similar, los ficheros abiertos para escritura o para añadir contenido usando la envoltura ogg:// se escriben como datos de audio comprimidos. Cuando se use la función stream_get_meta_data() con un fichero `OGG/Vorbis` abierto para lectura, se devolverán diversos detalles del flujo, incluyendo la etiqueta `vendor`, cualquier `comments` que se haya añadido, el número de canales `channels`, el `ratio` de muestreo, y el rango del ratio de codificación descrito por: `bitrate_lower`, `bitrate_upper`, `bitrate_nominal`, y `bitrate_window`.

ogg:// (PECL)

> Nota: Esta envoltura no está habilitada por omisión
> Para usar la envoltura ogg:// es necesario instalar la extensión » OGG/Vorbis disponible en » PECL.

### Uso

- ogg://soundfile.ogg
- ogg:///path/to/soundfile.ogg
- ogg://http://www.example.com/path/to/soundstream.ogg

### Opciones

Resumen de la Envoltura
Atributo | Permitido
--- | ---
Restringido por allow_url_fopen | No
Permite Lecturas | Sí
Permite Escrituras | Sí
Permite Añadir contenido | Sí
Permite Lecturas y Escrituras Simultánea | No
Permite usar la función stat() | No
Permite usar la función unlink() | No
Permite usar la función rename() | No
Permite usar la función mkdir() | No
Permite usar la función rmdir() | No

Opciones de contexto
Nombre | Uso | Valor por omisión | Modo
--- | --- | --- | ---
`pcm_mode` | codificación PCM que se aplicará en las lecturas, de entre: `OGGVORBIS_PCM_U8`, `OGGVORBIS_PCM_S8`, `OGGVORBIS_PCM_U16_BE`, `OGGVORBIS_PCM_S16_BE`, `OGGVORBIS_PCM_U16_LE`, y `OGGVORBIS_PCM_S16_LE`. (8 o 16 bit, con o sin signo, big o little `endian`) | OGGVORBIS_PCM_S16_LE | Lectura
`rate` | Ratio de muestreo en datos de entradas, expresado en Hz | 44100 | Escritura/Adición
`bitrate` | Si es un entero, definirá el bitrate fijo al que se codificará. (de 16000 a 131072) Si es un real, definirá la calidad del bitrate variable a usar. (de -1.0 a 1.0) | 128000 | Escritura/Adición
`channels` | El número de canales de audio a codificar, normalmente 1 (mono), o 2 (estéreo). Puede llegar a 16. | 2 | Escritura/Adición
`comments` | Un array de strings a codificar en la cabecera de la pista. |  | Escritura/Adición

# expect://

expect:// — Flujos de Interacción de Procesos

### Descripción

Los flujos que se hayan abierto con la envoltura expect://, darán acceso a stdin, stdout y stderr (entrada, salida y errores estándar respectivamente) de los procesos, vía PTY.

> Nota: Esta envoltura no está habilitada por omisión
> Para poder usar la envoltura expect:// se debe instalar la extensión » Expect disponible en » PECL.

expect:// (PECL)

### Uso

- expect://command

### Opciones

Resumen de la Envoltura
Atributo | Permitido
--- | ---
Restringido por allow_url_fopen | No
Permites Lecturas | Sí
Permite Escrituras | No
Permite Añadir contenido | Sí
Permite Lecturas y Escrituras Simultáneas | No
Permite usar la función stat() | No
Permite usar la función unlink() | No
Permite usar la función rename() | No
Permite usar la función mkdir() | No
Permite usar la función rmdir() | No

## Tabla de contenidos

- file:// — Acceso al sistema de ficheros local
- http:// — Acceso a URLs HTTP(s)
- ftp:// — Acceso a URLs FTP(s)
- php:// — Acceso a los diversos flujos I/O
- zlib:// — Flujos de compresión
- data:// — Datos (RFC 2397)
- glob:// — Encuentra nombres de ficheros que coinciden con un patrón dado
- phar:// — Archivo PHP
- ssh2:// — Shell seguro 2
- rar:// — RAR
- ogg:// — Flujos de audio
- expect:// — Flujos de Interacción de Procesos

- La sintaxis básica
  - Etiquetas PHP
  - Escape desde HTML
  - Separación de instrucciones
  - Comentarios
- Los tipos
  - Introducción
  - Sistema de tipos
  - NULL
  - Booleano
  - Los enteros
  - Números de punto flotante
  - Cadenas
  - Strings numéricos
  - Arrays
  - Los objetos
  - Las enumeraciones
  - Recursos
  - Callables
  - Mixed
  - Void
  - Never
  - Tipos de clases relativas
  - Tipo singleton
  - Iterables
  - Declaraciones de tipo
  - Manipulación de tipos
- Variables
  - Conceptos básicos
  - Variables Predefinidas
  - Ámbito de las variables
  - Variables variables
  - Variables desde fuentes externas
- Constantes
  - Sintaxis
  - Constantes predefinidas
  - Constantes mágicas
- Expresiones
- Los operadores
  - Prioridad de los operadores — La prioridad de los operadores
  - Aritmética — Los operadores aritméticos
  - Incremento y decremento — Operadores de incremento y decremento
  - Asignación — Los operadores de asignación
  - Bitwise — Operadores a nivel de bits
  - Comparación — Operadores de comparación
  - Control de errores — Operador de control de errores
  - Ejecución — Operador de ejecución
  - Lógica — Los operadores lógicos
  - String — Operadores de string
  - Arrays — Operadores de arrays
  - Tipo — Operadores de tipos
  - Funcional — Operadores funcionales
- Estructuras de Control
  - Introducción
  - if
  - else
  - elseif/else if
  - Sintaxis alternativa
  - while
  - do-while
  - for
  - foreach
  - break
  - continue
  - switch
  - match
  - declare
  - return
  - require
  - include
  - require_once
  - include_once
  - goto
- Functions
  - User-defined functions
  - Function parameters and arguments
  - Returning values
  - Variable functions
  - Internal (built-in) functions
  - Anonymous functions
  - Arrow Functions
  - First class callable syntax
- Clases y objetos
  - Introducción
  - Sintaxis básica
  - Propiedades
  - Hooks de propiedad
  - Constantes de clase
  - Autocarga de clases
  - Constructores y destructores
  - Visibilidad
  - Herencia
  - El operador de resolución de ámbito (::)
  - Estático
  - Abstracción de clases
  - Interfaces
  - Traits
  - Clases anónimas
  - Sobrecarga mágica
  - Recorrido de objetos
  - Métodos mágicos
  - Palabra clave "final"
  - Clonación de objetos
  - Comparación de objetos
  - Late Static Bindings (Resolución estática en tiempo de ejecución)
  - Objetos y referencias
  - Serialización de objetos — Serializar objetos - objetos en sesión
  - Covarianza y Contravarianza
  - Objetos perezosos
  - Modificaciones en POO (Programación orientada a objetos)
- Los espacios de nombres
  - Introducción — Introducción a los espacios de nombres
  - Espacios de nombres — Definición de espacios de nombres
  - Subespacio de nombres — Declaración de un subespacio de nombres
  - Definición de varios espacios de nombres en el mismo archivo
  - Introducción — Uso de espacios de nombres: introducción
  - Espacios de nombres y lenguaje dinámico
  - Comando namespace y __NAMESPACE__ — El comando namespace y la constante __NAMESPACE__
  - Importación y alias — Uso de espacios de nombres: importación y alias
  - Global — Espacio de nombres global
  - Retorno al espacio global — Uso de espacios de nombres: retorno al espacio global para funciones y constantes
  - Reglas de resolución de nombres
  - Preguntas frecuentes — Preguntas frecuentes: lo que debe saber sobre espacios de nombres
- Enumeraciones
  - Visión general de las enumeraciones
  - Enumeraciones básicas
  - Enumeraciones respaldadas
  - Métodos de enumeración
  - Métodos estáticos de enumeración
  - Constantes de enumeración
  - Traits
  - Valores de enumeración en expresiones constantes
  - Diferencias con los objetos
  - Listado de valores
  - Serialización
  - Por qué las enumeraciones no son extensibles
  - Ejemplos
- Errores
  - Lo básico
  - Errores en PHP 7
- Las excepciones
  - Extender las Excepciones
- Fibers
- Generators
  - Resumen sobre los generadores
  - Sintaxis de un Generador
  - Comparación de los generadores con los objetos Iterator
- Atributos
  - Descripción general de atributos
  - Sintaxis de atributos
  - Lectura de atributos con la API de Reflection
  - Declaración de clases de atributos
- Las referencias
  - ¿Qué es una referencia?
  - ¿Qué hacen las referencias?
  - Lo que las referencias no son
  - Paso por referencia
  - Devolver referencias
  - Destruir una referencia
  - Identificar una referencia
- Variables predefinidas
  - Las Superglobales — Variables internas siempre disponibles, independientemente del contexto
  - $GLOBALS — Hace referencia a todas las variables disponibles en un contexto global
  - $_SERVER — Variables de servidor y de ejecución
  - $_GET — Variables la cadena de consulta
  - $_POST — Datos de formulario de solicitudes HTTP POST
  - $_FILES — Variables de subida de ficheros HTTP
  - $_REQUEST — Variables HTTP Request
  - $_SESSION — Variables de sesión
  - $_ENV — Variables de entorno
  - $_COOKIE — Cookies HTTP
  - $php_errormsg — El último mensaje de error
  - $http_response_header — Cabeceras de respuesta HTTP
  - $argc — El número de argumentos pasados a un script
  - $argv — Array de argumentos pasados al script
- Excepciones predefinidas
  - Exception
  - ErrorException
  - ClosedGeneratorException — La clase ClosedGeneratorException
  - Error
  - ArgumentCountError
  - ArithmeticError
  - AssertionError
  - DivisionByZeroError
  - CompileError
  - ParseError
  - TypeError
  - ValueError
  - UnhandledMatchError
  - FiberError
  - RequestParseBodyException
- Interfaces y clases predefinidas
  - Traversable — La interfaz Traversable
  - Iterator — La interfaz Iterator
  - IteratorAggregate — La interfaz IteratorAggregate
  - InternalIterator — La clase InternalIterator
  - Throwable
  - Countable — La interfaz Countable
  - ArrayAccess — La interfaz ArrayAccess
  - Serializable — La interfaz Serializable
  - Closure — La clase Closure
  - stdClass — La clase stdClass
  - Generator — La clase Generator
  - Fiber — La clase Fiber
  - WeakReference — La clase WeakReference
  - WeakMap — La clase WeakMap
  - Stringable — La interfaz Stringable
  - UnitEnum — La interfaz UnitEnum
  - BackedEnum — La interfaz BackedEnum
  - SensitiveParameterValue — La clase SensitiveParameterValue
  - __PHP_Incomplete_Class — La clase __PHP_Incomplete_Class
- Atributos predefinidos
  - Attribute — El atributo Attribute
  - AllowDynamicProperties — El atributo AllowDynamicProperties
  - DelayedTargetValidation — The DelayedTargetValidation attribute
  - Deprecated — El atributo Deprecated
  - NoDiscard — El atributo NoDiscard
  - Override — La clase Override
  - ReturnTypeWillChange — El atributo ReturnTypeWillChange
  - SensitiveParameter — El atributo SensitiveParameter
- Opciones y parámetros de contexto
  - Opciones de contexto de los sockets — Lista de opciones de contexto de los sockets
  - Opciones de contexto HTTP — Lista de opciones de contexto HTTP
  - Opciones de contexto FTP — Lista de opciones de contexto FTP
  - Opciones de contexto SSL — Lista de opciones de contexto SSL
  - Opciones de contexto Phar — Listado de opciones de contexto Phar
  - Contexto parámetros — Listado de parámetros de contexto
  - Opciones de contexto Zip — Listado de opciones de contexto Zip
  - Opciones de contexto Zlib — Lista de opciones de contexto Zlib
- Protocolos y Envolturas soportados
  - file:// — Acceso al sistema de ficheros local
  - http:// — Acceso a URLs HTTP(s)
  - ftp:// — Acceso a URLs FTP(s)
  - php:// — Acceso a los diversos flujos I/O
  - zlib:// — Flujos de compresión
  - data:// — Datos (RFC 2397)
  - glob:// — Encuentra nombres de ficheros que coinciden con un patrón dado
  - phar:// — Archivo PHP
  - ssh2:// — Shell seguro 2
  - rar:// — RAR
  - ogg:// — Flujos de audio
  - expect:// — Flujos de Interacción de Procesos

# Seguridad

# Introducción

PHP es un potente lenguaje, y su intérprete, bien como módulo del servidor web o bien como binario CGI, puede acceder a ficheros, ejecutar comandos o abrir conexiones de red desde el servidor. Estas propiedades hacen que, por omisión, sea inseguro todo lo que se ejecute en un servidor web. PHP está diseñado específicamente para ser un lenguaje más seguro para escribir aplicaciones CGI que Perl o C. Partiendo de un correcto ajuste de opciones de configuración para tiempo de ejecución y en tiempo de compilación, y el uso de prácticas de programación apropiadas, pueden proporcionarle la combinación de libertad y de seguridad que necesita.

Dado que hay muchas vías para ejecutar PHP, existen muchas opciones de configuración para controlar su comportamiento. Al haber una extensa selección de opciones se garantiza poder usar PHP para un gran número de propósitos, pero a la vez significa que existen combinaciones que conllevan una configuración menos segura.

La flexibilidad de configuración de PHP rivaliza igualmente con la flexibilidad de su código. PHP puede ser usado para construir completas aplicaciones de servidor, con toda la potencia de un usuario de consola, o se puede usar sólo desde el lado del servidor implicando un menor riesgo dentro de un entorno controlado. El cómo construir ese entorno, y cómo de seguro es, depende del desarrollador PHP.

Este capítulo comienza con algunos consejos generales de seguridad, explica las diferentes combinaciones de opciones de configuración y las situaciones en que pueden ser útiles, y describe diferentes consideraciones relacionadas con la programación de acuerdo a 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.

# Instalado como CGI binario

## Tabla de contenidos

- Ataques posibles
- Caso 1: Ficheros públicos servidos solamente
- Caso 2: utilizando cgi.force_redirect
- Caso 3: Configurando doc_root o user_dir
- Caso 4: El analizador de PHP fuera del árbol de la web

## Ataques posibles

Usar PHP como un binario CGI es una opción para configuraciones que por alguna razón no desean integrar PHP como un módulo dentro del software de servidor (como Apache), o usarán PHP con diferentes tipos de envoltorios CGI para crear entornos seguros chroot y setuid para scripts. Esta configuración usualmente involucra la instalación del binario ejecutable de php en el directorio cgi-bin del servidor web. La recomendación » CA-96.11 del CERT recomienda que está en contra de colocar cualquiera de los intérpretes dentro de cgi-bin. Aún si el binario de php puede ser usado como un intérprete independiente, PHP está diseñado para prevenir los ataques que esta configuración hace posible:

- Accediendo a los ficheros del sistema: http://mi.servidor/cgi-bin/php?/etc/passwd La consulta de información en una URL después del signo de interrogación (`?`) es pasado como argumento de la línea de comandos al intérprete por la interfaz del CGI. Usualmente los intérpretes abren y ejecutan el fichero especificado como el primer argumento en la línea de comandos. Cuando es invocado como un binario de CGI, php se niega a interpretar los argumentos de línea de comandos.
- Accediendo a cualquier documento web en el servidor: http://mi.servidor/cgi-bin/php/directorio/secreto/doc.html Parte de la ruta de información de la URL después del nombre del binario de PHP, /directorio/secreto/doc.html es convencionalmente utilizado para especificar el nombre del fichero a ser abierto e interpretado por el programa CGI. Usualmente las directivas de configuración de algunos servidores web (Apache: `Action`) son utilizados para redirigir peticiones a los documentos como http://mi.servidor/directorio/secreto/script.php al intérprete de PHP. Con esta configuración, el servidor web revisa primero los permisos de acceso a los directorios /directorio/secreto, y después crea la petición redirigida http://mi.servidor/cgi-bin/php/directorio/secreto/script.php. Desafortunadamente, si la petición es proporcionada originalmente en esta forma, no se revisan los accesos a los directorios hechos por el servidor web /directorio/secreto/script.php, sino solamente al fichero /cgi-bin/php. De esta forma /cgi-bin/php cualquier usuario está habilitado a acceder a cualquier documento protegido en el servidor web. En PHP, las directivas de configuración en tiempo de ejecución cgi.force_redirect, doc_root y user_dir pueden ser utilizadas para prevenir este ataque, si el árbol de documentos del servidor tiene cualquiera de estos directorios con restricciones de acceso. Véase más abajo para una explicación completa de las diferentes combinaciones.

## Caso 1: Ficheros públicos servidos solamente

Si su servidor no tiene ningún contenido que no esté restringido por contraseña o control de acceso basado en IP, no hay necesidad de estas opciones de configuración. Si su servidor web no le permite hacer redirecciones, o el servidor no tiene una forma de comunicar al binario de PHP que la petición es una forma segura de petición de redireccionada la solicitud, puedes habilitar la directiva ini cgi.force_redirect. Usted todavía tiene que asegurarse que sus scripts de PHP no confían en una forma o en otra para llamar el script, ni directamente http://mi.servidor/cgi-bin/php/directorio/script.php ni por redirección http://mi.servidor/directorio/script.php.

La redirección puede ser configurada en Apache utilizando directivas `Action` y `AddHandler` (vea más abajo).

## Caso 2: utilizando `cgi.force_redirect`

La directiva de configuración cgi.force_redirect previene a cualquiera que llame a PHP directamente por medio de una URL como esta http://mi.servidor/cgi-bin/php/directoriosecreto/script.php. En cambio, php solamente lo analizará en este modo si éste se ha ido a través de una regla directa del servidor web.

Usualmente la redirección en la configuración de Apache se hace con las siguientes directivas:

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

Esta opción ha sido probada solamente con el servidor web Apache, y se basa en que en Apache se configure en una variable de entorno no-estándar de CGI REDIRECT_STATUS para peticiones de redirección. Si su servidor web no soporta ninguna forma de decirle si la petición es directa o redirigida, usted no puede utilizar esta opción y debe usar una de las otras formas de ejecutar la versión CGI aquí documentadas.

## Caso 3: Configurando doc_root o user_dir

Para incluir contenido activo, como scripts y ejecutables, en los directorios de documentos del servidor web es algunas veces considerado una práctica insegura. Si, por el hecho del algún error de configuración, los scripts no se ejecutan y son mostrados como documentos HTML regulares, esto podría resultar en una fuga de información de propiedad intelectual o de información de seguridad como las contraseñas. Por lo tanto muchos Administradores de Sistemas preferirán configurar otra estructura de directorios para scripts que sean accesibles solamente a través del CGI de PHP, y por lo tanto siempre interpretado y no desplegado como tal.

También si el método para asegurar las peticiones no es redirigido, como se describió en la sección anterior, no está disponible, es necesario configurar un script doc_root que sea diferente de la raíz del documento web.

Usted puede configurar el script de la raíz de documento de PHP en la directiva de configuración doc_root en el fichero de configuración, o puede configurar la variable de entorno PHP_DOCUMENT_ROOT. Si éste es configurado, la versión del CGI de PHP siempre construirá el nombre del fichero para abrir con este `doc_root` y la ruta de información en la petición, de tal forma que pueda estar seguro que ningún script será ejecutado fuera de este directorio (excepto por `user_dir` que se encuentra más abajo).

Otra opción utilizable es esta user_dir. Cuando `user_dir` no está configurado, lo único que controla el fichero abierto es `doc_root`. Al abrir una URL como http://mi.servidor/~usuario/documento.php no resulta en la apertura de un fichero bajo el directorio personal de los usuarios, pero si un fichero llamado ~usuario/documento.php debajo de `doc_root` (si, un nombre de directorio que inicia con una a tilde [`~`]).

Si `user_dir` es configurado, por ejemplo public_php, una petición como http://mi.servidor/~usuario/doc.php abrirá un fichero llamado doc.php bajo el directorio llamado public_php debajo de el directorio personal del usuario. Si el directorio personal del usuario es /home/usuario, el fichero ejecutado será /home/user/public_php/doc.php.

La expansión de `user_dir` sucede sin tomar en cuenta la configuración de `doc_root`, así que usted puede controlar el acceso a la raíz de los documentos y el directorio de los usuarios separadamente.

## Caso 4: El analizador de PHP fuera del árbol de la web

Una opción muy segura es poner el binario analizador de PHP en algún lugar fuera del árbol de ficheros de la web. En /usr/local/bin, por ejemplo. El único inconveniente real con esta opción es que ahora tendrá que poner una línea similar a:

    #!/usr/local/bin/php

como la primera línea de cualquier fichero que contenga etiquetas de PHP. También necesitará hacer que el fichero sea ejecutable. Eso significa, tratarlo exactamente como trataría cualquier otro script de CGI escrito en Perl, sh, bash, o cualquier otro lenguaje común de script el cual utilice `#!` como mecanismo de ejecución de si mismo.

Para que PHP maneje la información correctamente de PATH_INFO y PATH_TRANSLATED con esta configuración, La directiva ini cgi.discard_path debe estar habilitada..

# Instalado 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 se está usando PHP para acceder a una base de datos, a menos que tal base de datos disponga de un control de acceso propio, se 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 una araña web (bot) pudiera toparse con la página web de administración de una base de datos, y eliminar todo de la base de datos. Una protección ante este tipo de situaciones es mediante el uso del mecanismo de autorización de Apache, o con modelos de acceso de diseño propio usando LDAP, archivos .htaccess, etc. e incluir ese código como parte de los 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 muy poco 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 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.

Incrementar 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 considerado como una opción por aquellos que no son profesionales en seguridad.

Existen otras soluciones más simples. Mediante el uso de open_basedir se puede controlar y restringir qué directorios pueden ser usados por PHP. También se pueden definir áreas solo-Apache, para restringir todas las actividades basadas en web a archivos que no son de usuarios o del sistema.

# Seguridad de una Sesión

Es importante mantener seguro el manejo de sesión HTTP. La seguridad relacionada a la Sesión está descrita en Seguridad de Sesión en la sección de referencia Módulo de Sesión.

# Seguridad del Sistema de Archivos

## Tabla de contenidos

- Cuestiones relacionadas a bytes nulos

PHP está sujeto a la seguridad integrada en la mayoría de sistemas de servidores con respecto a los permisos de archivos y directorios. Esto permite controlar qué archivos en el sistema de archivos se pueden leer. Se debe tener cuidado con los archivos que son legibles para garantizar que son seguros para la lectura por todos los usuarios que tienen acceso al sistema de archivos.

Desde que PHP fue diseñado para permitir el acceso a nivel de usuarios para el sistema de archivos, es perfectamente posible escribir un script PHP que le permita leer archivos del sistema como /etc/passwd, modificar sus conexiones de red, enviar trabajos de impresión masiva, etc. Esto tiene algunas implicaciones obvias, es necesario asegurarse que los archivos que se van a leer o escribir son los apropiados.

Considere el siguiente script, donde un usuario indica que quiere borrar un archivo en su directorio home. Esto supone una situación en la que una interfaz web en PHP es usada regularmente para gestionar archivos, por lo que es necesario que el usuario Apache pueda borrar archivos en los directorios home de los usuarios.

Ejemplo #1 Un control pobre puede llevar a ....

    <?php

    // eliminar un archivo del directorio personal del usuario
    $username = $_POST['user_submitted_name'];
    $userfile = $_POST['user_submitted_filename'];
    $homedir  = "/home/$username";

    unlink("$homedir/$userfile");

    echo "El archivo ha sido eliminado!";
    ?>

Dado que el nombre de usuario y el nombre del archivo son enviados desde un formulario, estos pueden representar un nombre de archivo y un nombre de usuario que pertenecen a otra persona, incluso se podría borrar el archivo a pesar que se supone que no estaría permitido hacerlo. En este caso, usted desearía usar algún otro tipo de autenticación. Considere lo que podría suceder si las variables enviadas son `"../etc/"` y `"passwd"`. El código entonces se ejecutaría efectivamente como:

Ejemplo #2 ... Un ataque al sistema de archivos

    <?php

    // elimina un archivo desde cualquier lugar en el disco duro al que
    // el usuario de PHP tiene acceso. Si PHP tiene acceso de root:
    $username = $_POST['user_submitted_name']; // "../etc"
    $userfile = $_POST['user_submitted_filename']; // "passwd"
    $homedir  = "/home/$username"; // "/home/../etc"

    unlink("$homedir/$userfile"); // "/home/../etc/passwd"

    echo "El archivo ha sido eliminado!";
    ?>

Hay dos medidas importantes que usted debe tomar para prevenir estas cuestiones.

- Únicamente permisos limitados al usuario web de PHP.
- Revise todas las variables que se envían.

Aquí está una versión mejorada del script:

Ejemplo #3 Comprobación más segura del nombre de archivo

    <?php

    // elimina un archivo del disco duro al que
    // el usuario de PHP tiene acceso.
    $username = $_SERVER['REMOTE_USER']; // usando un mecanismo de autenticación
    $userfile = basename($_POST['user_submitted_filename']);
    $homedir  = "/home/$username";

    $filepath = "$homedir/$userfile";

    if (file_exists($filepath) && unlink($filepath)) {
        $logstring = "Se ha eliminado $filepath\n";
    } else {
        $logstring = "No se ha podido eliminar $filepath\n";
    }

    $fp = fopen("/home/logging/filedelete.log", "a");
    fwrite($fp, $logstring);
    fclose($fp);

    echo htmlentities($logstring, ENT_QUOTES);

    ?>

Sin embargo, incluso esto no está exento de defectos. Si la autenticación del sistema permite a los usuarios crear sus propios inicios de sesión de usuario, y un usuario eligió la entrada `"../etc/"`, el sistema está expuesto una vez más. Por esta razón, puede que prefiera escribir un chequeo más personalizado:

Ejemplo #4 Comprobación más segura del nombre de archivo

    <?php

    $username     = $_SERVER['REMOTE_USER']; // usando un mecanismo de autenticación
    $userfile     = $_POST['user_submitted_filename'];
    $homedir      = "/home/$username";

    $filepath     = "$homedir/$userfile";

    if (!ctype_alnum($username) || !preg_match('/^(?:[a-z0-9_-]|\.(?!\.))+$/iD', $userfile)) {
        die("nombre de usuario o nombre de archivo incorrecto");
    }

    // etc.

    ?>

Dependiendo de sus sistema operativo, hay una gran variedad de archivos a los que debe estar atento, esto incluye las entradas de dispositivos (/dev/ o COM1), archivos de configuracion (archivos /etc/ y archivos `.ini`), las muy conocidas carpetas de almacenamiento (/home/, My Documents), etc. Por esta razón, por lo general es más fácil crear una política en donde se prohíba todo excepto lo que expresamente se permite.

## Cuestiones relacionadas a bytes nulos

Como PHP utiliza las funciones de C para operaciones relacionadas al sistema de archivos, se podría manejar bytes nulos de manera bastante inesperada. Como un byte nulo denota el fin de una cadena en C, las cadenas que contengan estos no serán consideradas por completo, sino sólo hasta que ocurra un byte nulo. El siguiente ejemplo muestra un código vulnerable que presenta este problema:

Ejemplo #1 Script vulnerable a bytes nulos

    <?php

    $file = $_GET['file']; // "../../etc/passwd\0"
    if (file_exists('/home/wwwrun/' . $file . '.php')) {
        // file_exists devolverá true si el archivo /home/wwwrun/../../etc/passwd existe
        include '/home/wwwrun/' . $file . '.php';
        // el archivo /etc/passwd se incluirá
    }

    ?>

Por lo tanto, cualquier cadena que se utiliza en una operación de sistema de archivos siembre deben ser validados correctamente. He aquí una versión mejorada del ejemplo anterior:

Ejemplo #2 Validando correctamente la entrada

    <?php

    $file = $_GET['file'];

    // Lista blanca de valores posibles
    switch ($file) {
        case 'main':
        case 'foo':
        case 'bar':
            include '/home/wwwrun/include/'.$file.'.php';
            break;
        default:
            include '/home/wwwrun/include/main.php';
    }

    ?>

# Seguridad en bases de datos

## Tabla de contenidos

- Diseño de bases de datos
- Conexión a una base de datos
- Modelo de almacenamiento cifrado
- Inyección de SQL

Hoy en día, las bases de datos son componentes esenciales de cualquier aplicación web, permitiendo a los sitios web proveer variedad de contenido dinámico. Puesto que se puede almacenar información muy delicada o secreta en una base de datos, debería considerarse ampliamente proteger las bases de datos.

Para obtener o almacenar cualquier información, es necesario conectarse a la base de datos, enviar una consulta válida, obtener el resultado, y cerrar la conexión. Hoy en día, el lenguaje de consultas más utilizado en esta interacción es el Lenguaje Estructurado de Consultas (SQL, por sus siglas en inglés). Vea como un atacante puede realizar manipulaciones maliciosas con una consulta SQL.

Como es de suponer, PHP no puede proteger una base de datos por sí mismo. Las siguientes secciones tienen como objetivo ser una introducción básica de cómo acceder y manipular bases de datos dentro de scripts de PHP.

Tenga en mente esta sencilla regla: Protección en profundidad. En cuantos más sitios se tomen acciones para aumentar la protección de una base de datos, menor es la probabilidad de que un atacante tenga éxito en exponer o abusar de cualquier información que tenga almacenada. Un buen diseño del esquema de la base de datos y de la aplicación se ocupará de sus mayores temores.

## Diseño de bases de datos

El primer paso es siempre crear una base de datos, a menos que se quiera utilizar una de un tercero. Cuando se crea una base de datos, esta es asignada a un propietario, aquel que ejecutó la sentencia de creación. Usualmente, sólo el propietario (o un superusuario) puede hacer cualquier cosa con los objetos de esa base de datos. Para que otros usuarios puedan utilizarla, se les deben conceder privilegios.

Las aplicaciones nunca deberían conectarse a la base de datos como su propietario o como un superusuario, porque estos usuarios pueden ejecutar cualquier consulta a su antojo; por ejemplo, modificar el esquema (p.ej., eliminar tablas) o borrar su contenido por completo.

Se pueden crear distintos usuarios de una base de datos para cada aspecto de la aplicación con permisos muy limitados a los objetos de dicha base de datos. Solamente deberían otorgarse los privilegios necesarios, evitando así que el mismo usuario pueda interactuar con la base de datos en diferentes casos y uso. Esto significa que si un intruso obtiene acceso a una base de datos utilizando las credenciales de la aplicación, solamente puede efectuar los cambios que la aplicación permita.

## Conexión a una base de datos

Se pueden establecer las conexiones sobre SSL para cifrar las comunicaciones cliente/servidor y aumentar la seguridad, o también emplear ssh para cifrar la conexión de red entre los clientes y el servidor de bases de datos. Si se utiliza algunas de estas opciones, será difícil para un posible atacante la monitorización del tráfico y la obtención de información de la base de datos.

## Modelo de almacenamiento cifrado

SSL/SSH protege los datos que viajan desde el cliente al servidor: SSL/SSH no protege los datos persistentes almacenados en una base de datos. SSL es un protocolo que protege los datos mientras viajan por el cable.

Una vez que un atacante obtiene acceso directo a una base de datos (eludiendo el servidor web), los datos sensibles almacenados podrían ser divulgados o mal utilizados, a menos que la información esté protegida por la base de datos misma. Cifrar los datos es una buena forma de mitigar esta amenaza, pero muy pocas bases de datos ofrecen este tipo de cifrado de datos.

La forma más sencilla para evitar este problema es crear primero un paquete de cifrado propio y utilizarlo en los scripts de PHP. Hay muchas extensiones de PHP que pueden ser de ayuda para esto, tales como OpenSSL y Sodium, cubriendo así una amplia variedad de algoritmos de cifrado. El script cifra los datos antes de insertarlos en la base de datos, y los descifra al obtenerlos. Véanse las referencias para ejemplos adicionales del funcionamiento del cifrado.

### 'Hashing'

En caso de datos que deban estar realmente ocultos, si no fuera necesaria su representación real, (es decir, que no sean mostrados), quizás convenga utilizar algoritmos hash. El ejemplo más típico del uso del hash es a la hora de almacenar el hash criptográfico de una contraseña en una base de datos, en lugar de almacenar la contraseña en sí.

Las funciones de password proporcionan una forma adecuada de utilizar hash con datos delicados y trabajar con estos hash.

password_hash() se emplea para usar un hash con una cadena dada utilizando el algoritmo más fuerte actualmente disponible, mientras que password_verify() comprueba si la contraseña dada coincide con el hash almacenado en la base de datos.

Ejemplo #1 Campo de contraseña con hash

    <?php

    // Almacenar el hash de la contraseña
    $query  = sprintf("INSERT INTO users(name,pwd) VALUES('%s','%s');",
                pg_escape_string($nombre_usuario),
                password_hash($password, PASSWORD_DEFAULT));
    $result = pg_query($connection, $query);

    // Consultar si el usuario envió la contraseña correcta
    $query = sprintf("SELECT pwd FROM users WHERE name='%s';",
                    pg_escape_string($nombre_usuario));
    $row = pg_fetch_assoc(pg_query($connection, $query));

    if ($row && password_verify($contraseña, $row['pwd'])) {
        echo 'Bienvenido, ' . htmlspecialchars($username) . '!';
    } else {
        echo 'La autenticación ha fallado para ' . htmlspecialchars($username) . '.';
    }

    ?>

## Inyección de SQL

La inyección SQL es una técnica en la que un atacante aprovecha fallas en el código de la aplicación encargado de construir consultas SQL dinámicas. El atacante puede obtener acceso a secciones privilegiadas de la aplicación, recuperar toda la información de la base de datos, manipular datos existentes o incluso ejecutar comandos peligrosos a nivel del sistema en el host de la base de datos. La vulnerabilidad ocurre cuando los desarrolladores concatenan o interpolan entrada arbitraria en sus declaraciones SQL.

Ejemplo #1 Dividir el conjunto de resultados en páginas ... y crear superusuarios (PostgreSQL)

En el siguiente ejemplo, la entrada del usuario se interpola directamente en la consulta SQL, lo que permite al atacante obtener una cuenta de superusuario en la base de datos.

    <?php

    $offset = $_GET['offset']; // ¡Cuidado, no hay validación en la entrada de datos!
    $query  = "SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET $offset;";
    $result = pg_query($conn, $query);

    ?>

Un usuario común hace clic en los enlaces 'siguiente' o 'atrás' donde el $índice está codificado en el URL. El script espera que el $índice entrante sea un número. Sin embargo, Qué sucede si alguien intenta ingresar al añadir lo siguiente a la URL?

    0;
    insert into pg_shadow(usename,usesysid,usesuper,usecatupd,passwd)
        select 'crack', usesysid, 't','t','crack'
        from pg_shadow where usename='postgres';
    --

Si ocurriera, el script presentaría un acceso de superusuario al atacante. Observe que `0;` es para proveer un índcie válido a la consulta original y así finalizarla.

> Nota:

> Es una técnica común forzar al analizador SQL a ignorar el resto de la consulta escrita por el desarrollador con `--`, lo cual representa un comentario en SQL.

Una forma factible de obtener contraseñas es burlar las páginas de búsqueda de resultados. Lo único que el atacante necesita hacer es ver si hay variables que hayan sido enviadas y sean empleadas en sentencias SQL que no sean manejadas apropiadamente. Estos filtros se pueden establecer comunmente en un formulario anterior para personalizar las cláusulas `WHERE, ORDER BY, LIMIT` y `OFFSET` en las sentencias `SELECT`. Si la base de datos admite el constructor `UNION`, el atacante podría intentar anteponer una consulta entera a la consulta original para enumerar las contraseñas de una tabla arbitraria. Se recomienda encarecidamente almacenar solo hashes seguros de contraseñas en lugar de las contraseñas mismas.

Ejemplo #2 Enumerar artículos ... y algunas contraseñas (cualquier servidor de bases de datos)

    <?php

    $query  = "SELECT id, name, inserted, size FROM products
               WHERE size = '$size'";
    $result = odbc_exec($conexión, $query);

    ?>

La parte estática de la consulta se puede combinar con otra sentencia `SELECT` la cual revelará todas las contraseñas:

    '
    union select '1', concat(uname||'-'||passwd) as name, '1971-01-01', '0' from usertable;
    --

Las declaraciones `UPDATE` e `INSERT` también son susceptibles a este tipo de ataques.

Ejemplo #3 Desde restablecer una contraseña ... hasta obtener más privilegios (cualquier servidor de bases de datos)

    <?php
    $query = "UPDATE usertable SET pwd='$pwd' WHERE uid='$uid';";
    ?>

Si un usuario malicioso podría enviar el valor `' or uid like'%admin%` a $uid para cambiar la contraseña del administrador, o simplemente cambiar $pwd a `jejeje', trusted=100, admin='yes` para obtener más privilegios, entonces la consulta se tornaría:

    <?php

    // $uid: ' or uid like '%admin%
    $query = "UPDATE usertable SET pwd='...' WHERE uid='' or uid like '%admin%';";

    // $pwd: jejeje', trusted=100, admin='yes
    $query = "UPDATE usertable SET pwd='jejeje', trusted=100, admin='yes' WHERE
    ...;";

    ?>

Aunque sigue siendo evidente que un atacante debe poseer al menos cierto conocimiento de la arquitectura de la base de datos para llevar a cabo un ataque exitoso, obtener esta información a menudo es muy simple. Por ejemplo, el código puede ser parte de un software de código abierto y estar disponible públicamente. Esta información también puede ser revelada por código fuente cerrado, incluso si está codificado, ofuscado o compilado, e incluso por tu propio código a través de la visualización de mensajes de error. Otros métodos incluyen el uso de nombres de tablas y columnas típicos. Por ejemplo, un formulario de inicio de sesión que utiliza una tabla 'users' con nombres de columnas 'id', 'username' y 'password'.

Ejemplo #4 Atacar el sistema operativo del host de la base de datos (MSSQL Server)

Un ejemplo alarmante de cómo los comandos a nivel del sistema operativo pueden ser accedidos en algunos hosts de bases de datos.

    <?php

    $query  = "SELECT * FROM products WHERE id LIKE '%$prod%'";
    $result = mssql_query($query);

    ?>

Si un atacante envía el valor `a%' exec master..xp_cmdshell 'net user test testpass /ADD' --` a $prod, la $query será:

    <?php

    $query  = "SELECT * FROM products
                  WHERE id LIKE '%a%'
                  exec master..xp_cmdshell 'net user test testpass /ADD' --%'";
    $result = mssql_query($query);

    ?>

El servidor MSSQL ejecuta la sentencia SQL en el lote incluyendo un comando para añadir un usuario nuevo a la base de datos de cuentas local. Si esta aplicación estaban siendo ejecutados como `sa` y el servicio MSSQLSERVER estaba ejecutando con los privilegios suficientes, el atacante ahora podría tener una cuenta con la cual acceder a esta máquina.

> Nota:

> Algunos ejemplos anteriores están vinculados a un servidor de bases de datos específico, pero esto no significa que un ataque similar sea imposible contra otros productos. Tu servidor de bases de datos puede ser igualmente vulnerable de otra manera.

Imagen cortesía de » xkcd

### Técnicas de evitación

La forma recomendada de evitar la inyección SQL es vincular todos los datos mediante declaraciones preparadas. Utilizar consultas parametrizadas no es suficiente para evitar por completo la inyección SQL, pero es la manera más fácil y segura de proporcionar datos a las declaraciones SQL. Todas las literales de datos dinámicos en las cláusulas `WHERE`, `SET`, y `VALUES` deben ser reemplazadas con marcadores de posición. Los datos reales se vincularán durante la ejecución y se enviarán por separado del comando SQL.

La vinculación de parámetros solo puede utilizarse para datos. Otras partes dinámicas de la consulta SQL deben filtrarse contra una lista conocida de valores permitidos.

Ejemplo #5 Evitar la inyección SQL mediante el uso de declaraciones preparadas con PDO

    <?php

    // La parte dinámica del SQL se valida contra valores esperados
    $sortingOrder = $_GET['sortingOrder'] === 'DESC' ? 'DESC' : 'ASC';
    $productId = $_GET['productId'];
    // El SQL se prepara con un marcador de posición
    $stmt = $pdo->prepare("SELECT * FROM products WHERE id LIKE ? ORDER BY price {$sortingOrder}");
    // El valor se proporciona con comodines LIKE
    $stmt->execute(["%{$productId}%"]);

    ?>

Las declaraciones preparadas son proporcionadas por PDO, MySQLi y otras bibliotecas de bases de datos.

Los ataques de inyección SQL se basan principalmente en explotar código que no ha sido escrito teniendo en cuenta la seguridad. Nunca confíes en ninguna entrada, especialmente desde el lado del cliente, incluso si proviene de un cuadro de selección, un campo de entrada oculto o una cookie. El primer ejemplo muestra que una consulta tan simple puede causar desastres.

Una estrategia de defensa en profundidad implica varias buenas prácticas de codificación:

- Nunca te conectes a la base de datos como un superusuario o como el propietario de la base de datos. Utiliza siempre usuarios personalizados con privilegios mínimos.
- Verifica si la entrada proporcionada tiene el tipo de datos esperado. PHP tiene una amplia gama de funciones de validación de entrada, desde las más simples encontradas en Funciones de Variables y en Funciones de Tipo de Carácter (por ejemplo, is_numeric(), ctype_digit() respectivamente) hasta el soporte de Expresiones Regulares Compatibles con Perl.
- Si la aplicación espera una entrada numérica, considera verificar los datos con ctype_digit(), cambiar silenciosamente su tipo usando settype(), o usar su representación numérica con sprintf().
- Si la capa de la base de datos no admite la vinculación de variables, entonces coloca comillas alrededor de cada valor proporcionado por el usuario que no sea numérico y que se pase a la base de datos con la función de escape de cadena específica de la base de datos (por ejemplo, mysql_real_escape_string(), sqlite_escape_string(), etc.). Las funciones genéricas como addslashes() son útiles solo en un entorno muy específico (por ejemplo, MySQL en un conjunto de caracteres de un solo byte con NO_BACKSLASH_ESCAPES deshabilitado), así que es mejor evitarlas.
- No imprimas ninguna información específica de la base de datos, especialmente sobre el esquema, por las buenas o por las malas. Consulta también Informes de Errores y Funciones de Manejo y Registro de Errores.

Además, se puede beneficiar del registro de consultas, ya sea dentro de un script o mediante la base de datos en sí misma, si es que lo soporta. Obviamente, llevar un registro no previene los intentos dañinos, aunque puede ser útil para realizar un seguimiento de las aplicación que han sido eludidas. El registro no es útil por sí mismo sino por la información que contiene. Normalmente cuantos más detalles, mejor.

# Reportando errores

Con la seguridad de PHP, hay dos formas para reportar errores. Una es en beneficio, para incrementar la seguridad, y la otra es para perjudicar.

Una táctica estándar de ataque conlleva a perfilar un sistema; llenándolo de datos incorrectos, revisando los tipos y contextos de los errores que son devueltos. Esto le permite al atacante recolectar información acerca del servidor, para determinar posibles debilidades. Por ejemplo, si un atacante ha recogido información sobre una página basada en un envío previo, él podría intentar sobrescribir las variables, o modificarlas:

Ejemplo #1 Atacando variables con una página HTML personalizada

    <form method="post" action="objetivodelataque?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 normalmente son devueltos, pueden ser muy útiles para el desarrollador que está intentando depurar un script, indicando qué cosas, como por ejemplo, qué función o qué fichero de PHP falló, y el número de línea en donde la falla ocurrió. Toda esta es la información que puede ser explotada. Esto no es algo raro para un desarrollador de PHP que utilice las funciones show_source(), highlight_string(), o highlight_file() como una medida de depuración, pero en un sitio en escena, esto puede exponer variables ocultas, sintáxis sin revisar, y otra información peligrosa. Es especialmente peligroso el código en ejecución de fuentes conocidas con manejadores de depuración incluidos, o utilizar técnicas comunes de depuración. Si los atacantes pueden determinar qué técnica en general usted está utilizando, ellos podrían tratar de usar fuerza bruta en una página, enviando varias cadenas comunes de depuración:

Ejemplo #2 Explotando variables comunes de depuración

    <form method="post" action="objetivodelataque?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>

Sin importar el método de manejo de errores, la capacidad de probar errores en un sistema conlleva a proveer a un atacante con mas información.

Por ejemplo, el estilo común de un error genérico de PHP indica que un sistema ciertamente está ejecutando PHP. Si un atacante está en una página `.html`, y quiere probar qué motor hay tras de ese servidor (para buscar debilidades en el sistema), lo alimenta con datos erróneos que lo podrían habilitar a que determine que ese sistema fue construido con PHP.

El error de una función puede indicar ya sea, un sistema que puede estar ejecutando un motor específico de base de datos, o dar las pistas de cómo una página web puede estar programada o diseñada. Esto permite una investigación más profunda dentro de los puertos abiertos de la base de datos, o buscar errores específicos o debilidades en una página web. Pasando diferentes porciones de datos erróneos, por ejemplo, un atacante puede determinar el orden de autenticación en un script, (por medio del número de línea de los errores) como también probar exploits que pueden ser utilizados en diferentes ubicaciones del script.

Un error del sistema de archivos o un error general de PHP puede indicar qué permisos tiene el servidor web, así también la estructura y organización de ficheros en el servidor web. El código de error escrito por el desarrollador puede agravar este problema, conllevando a la explotación fácil de la, hasta entonces, información "oculta".

Hay tres grandes soluciones a este problema. La primera consiste en examinar todas las funciones, e intentar arreglar la mayoría de los errores. La segunda es deshabilitar completamente la notificación de errores de el código en ejecución. La tercera es utilizar las funciones de manejo de error propias de PHP para crear su propio manejador de errores. Dependiendo de su política de seguridad, puede ser que encuentre que las tres sean aplicables a su situación.

Una forma de detectar este problema por adelantado es hacer uso de la función propia de PHP error_reporting(), para ayudarle a asegurar su código y encontrar el uso de variables que podrían ser peligrosas. Al probar su código, antes de distribuirlo, con `E_ALL`, usted puede encontrar rapidamente áreas donde sus variables pueden ser abiertas para envenenamiento o modificación en otras maneras. Una vez usted está listo para distribuirlo, debería deshabilitar completamente el reporte de errores poniendo el valor de error_reporting() a 0, o apagar el visor de errores utilizando la opción `display_errors` del fichero php.ini para aislar su código de ataques. Si decide hacer esto último, también debería definir la ruta de acceso a su archivo de registros utilizando la directiva `error_log`, y poner `log_errors` en "on".

Ejemplo #3 Buscando variables peligrosas con E_ALL

    <?php
    if ($username) {  // No se ha inicializado o revisado antes de utilizar
        $good_login = 1;
    }
    if ($good_login == 1) { // Si la prueba anterior falla, los que no estén inicializados o comprobados antes de utilizar, tendrán acceso
        readfile("/ruta/hacia/datos/altamente/sensibles/index.html");
    }
    ?>

# 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 #1 Uso Peligroso de Variables

    <?php
    // eliminar un archivo del directorio personal del usuario .. ¿o
    // quizás de alguien más?

    unlink ($evil_var);

    // Imprimir el registro del acceso... ¿o quizás una entrada de /etc/passwd?
    fwrite ($fp, $evil_var);

    // Ejecutar algo trivial.. ¿o rm -rf *?
    system ($evil_var);
    exec ($evil_var);

    ?>

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.

Mejore la seguridad deshabilitando las configuraciones de conveniencia que oscurecen el origen, la validez o la integridad de los datos de entrada. La creación implícita de variables y la entrada no verificada pueden llevar a vulnerabilidades como ataques de inyección y manipulación de datos.

Características como `register_globals` y `magic_quotes` (ambas eliminadas en PHP 5.4.0) contribuyeron a estos riesgos al crear automáticamente variables a partir de la entrada del usuario y escapar datos de manera inconsistente. Aunque ya no están en PHP, riesgos similares persisten si la gestión de la entrada es incorrecta.

Habilite error_reporting(E_ALL) para ayudar a detectar variables no inicializadas y validar la entrada. Utilice tipos estrictos (declare(strict_types=1), introducido en PHP 7) para imponer la seguridad de tipos, prevenir conversiones de tipos no intencionadas y mejorar la seguridad general.

# Ocultar PHP

En general, la seguridad por ocultación es una de las formas más débiles de seguridad. Aunque en algunos casos, es aconsejable cada pequeño elemento extra de seguridad.

Unas cuantas técnicas simples pueden ayudar a ocultar PHP, posiblemente retrasando a un atacante que esté tratando de descubrir debilidades en el sistema. Al establecer expose_php a `off` en el fichero php.ini, se reduce la cantidad de información disponible.

Otra táctica es configurar servidores web como Apache para interpretar diferentes tipos de ficheros por medio de PHP, ya sea con una directiva de .htaccess o en el propio fichero de configuración de Apache. Así se pueden utilizar extensiones de ficheros engañosas:

Ejemplo #1 Ocultando PHP como si fuera otro lenguaje

    # Hacer que el código de PHP parezca otro tipo de código
    AddType application/x-httpd-php .asp .py .pl

U ocultarlo completamente:

Ejemplo #2 Utilizar tipos desconocidos para extensiones de PHP

    # Hacer que el código de PHP parezca de tipo desconocido
    AddType application/x-httpd-php .bop .foo .133t

U ocultarlo como código HTML, lo cual tiene un pequeño impacto de rendimiento debido a que todos los ficheros HTML serán procesados por el motor de PHP:

Ejemplo #3 Utilizar tipos HTML para extensiones de PHP

    # Hacer que el código de PHP parezca HTML
    AddType application/x-httpd-php .htm .html

Para que esto funcione eficazmente, se debe cambiar el nombre de los ficheros PHP con las extensiones de arriba. Si bien es una forma de seguridad por ocultamiento, es 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 mejoramiento. Cada nueva versión incluye con frecuencia cambios mayores y menores para mejorar la seguridad y reparar cualquier fallo, problemas de configuración, y otros asuntos que puedan afectar la seguridad y estabilidad global del sistema.

Como cualquier lenguaje y programa de script a nivel de sistema, la mejor estrategia es actualizar con frecuencia y mantenerse alerta sobre las últimas versiones y sus cambios.

- Introducción
- Consideraciones generales
- Instalado como CGI binario
  - Ataques posibles
  - Caso 1: Ficheros públicos servidos solamente
  - Caso 2: utilizando cgi.force_redirect
  - Caso 3: Configurando doc_root o user_dir
  - Caso 4: El analizador de PHP fuera del árbol de la web
- Instalado como módulo de Apache
- Seguridad de una Sesión
- Seguridad del Sistema de Archivos
  - Cuestiones relacionadas a bytes nulos
- Seguridad en bases de datos
  - Diseño de bases de datos
  - Conexión a una base de datos
  - Modelo de almacenamiento cifrado
  - Inyección de SQL
- Reportando errores
- Datos Enviados por el Usuario
- Ocultar PHP
- Mantenerse al día

# Características

# Identificación HTTP con PHP

Es posible utilizar la función header() para solicitar una identificación (`"Authentication Required"`) al cliente, generando así la aparición de una ventana de solicitud de usuario y contraseña. Una vez que los campos han sido completados, la URL será llamada de nuevo, con las variables predefinidas PHP_AUTH_USER, PHP_AUTH_PW y AUTH_TYPE conteniendo respectivamente el nombre de usuario, la contraseña y el tipo de identificación. Estas variables predefinidas se encuentran en los arrays $_SERVER. Solo el método de identificación "Basic" es soportado. Consulte la función header() para más información.

Aquí hay un ejemplo de script que fuerza la identificación del cliente para acceder a una página:

Ejemplo #1 Ejemplo de identificación HTTP simple

    <?php
    if (!isset($_SERVER['PHP_AUTH_USER'])) {
        header('HTTP/1.1 401 Unauthorized');
        header('WWW-Authenticate: Basic realm="My Realm"');
        echo 'Texto utilizado si el visitante usa el botón de cancelación';
        exit;
    } else {
        echo "<p>Hola, {$_SERVER['PHP_AUTH_USER']}.</p>";
        echo "<p>Su contraseña es {$_SERVER['PHP_AUTH_PW']}.</p>";
    }
    ?>

> Nota: Compatibilidad

> Sea muy cuidadoso al usar encabezados HTTP con PHP. Para garantizar la máxima compatibilidad entre los navegadores, la palabra clave "Basic" debe escribirse con una B mayúscula, y el texto de presentación debe colocarse entre comillas dobles (no simples), y exactamente un espacio debe preceder al código 401 en el encabezado HTTP/1.1 401. Los parámetros de autenticación deben estar separados por comas.

En lugar de mostrar simplemente las variables globales PHP_AUTH_USER y PHP_AUTH_PW, se preferirá verificar la validez del nombre de usuario y la contraseña. Por ejemplo, enviando esta información a una base de datos, o buscando en un fichero dbm.

> Nota: Configuración de Apache

> PHP utiliza la presencia de la directiva `AuthType` para determinar si una identificación externa está activada.

Tenga en cuenta, sin embargo, que las manipulaciones anteriores no impiden que cualquier persona con una página no identificada robe las contraseñas de las páginas protegidas, en el mismo servidor.

> Nota: Comportamiento del navegador
> La autenticación HTTP Basic es realmente básica, y no fue diseñada para soportar cierres de sesión. Dado que HTTP es un protocolo sin estado, la mayoría de los navegadores almacenarán en caché las credenciales proporcionadas tan pronto como se reciba un código de estado `2xx`, y las enviarán en cada solicitud, hasta que se cierre el navegador. No existe una forma definida para que un servidor solicite nuevas credenciales. A lo largo de los años, varias soluciones alternativas se han difundido como consejos en Internet, pero todas dependen de cómo los diferentes navegadores han elegido manejar casos límite no definidos (o incluso violaciones del estándar HTTP). Es mejor evitar tales soluciones alternativas y no utilizar la autenticación Basic para nada serio.

> Nota: Configuración de IIS
> Para que la identificación HTTP funcione con un servidor IIS con la versión CGI de PHP, la directiva PHP cgi.rfc2616_headers debe establecerse en `0` (el valor por defecto), y debe editar la configuración "`Directory Security`" de IIS. Haga clic en "`Edit`" y active solo "`Anonymous Access`", todos los demás campos deben dejarse inactivos.

# Cookies

PHP soporta las cookies HTTP de manera transparente. Las cookies son un mecanismo de almacenamiento de información en el cliente, y de lectura de dicha información. Este sistema permite identificar y seguir a los visitantes. Se puede enviar una cookie con la función setcookie() o setrawcookie(). Las cookies forman parte de los encabezados HTTP, lo que impone que setcookie() sea llamada antes de cualquier visualización de texto. Estas son las mismas limitaciones que para header(). Se pueden utilizar las funciones de bufferización de salida para retrasar la visualización de su script hasta que se haya decidido enviar una cookie o encabezados.

Todas las cookies enviadas al servidor por el cliente serán automáticamente incluidas en un array superglobal $_COOKIE si variables_order contiene "C". Si se desea asignar múltiples valores a una sola cookie, se debe añadir `[]` al nombre de la cookie.

Para más detalles, incluyendo notas sobre errores de los navegadores, ver las funciones setcookie() y setrawcookie().

# Sesiones

El soporte para sesiones en PHP consiste en una manera de preservar ciertos datos a través de accesos posteriores, lo que permite crear aplicaciones más personalizadas y mejorar el atractivo de un sitio web. Toda la información está en la sección Referencia de sesiones.

# Gestión de cargas de ficheros

## Tabla de contenidos

- Cargas de ficheros por método POST
- Explicación sobre los mensajes de errores de carga de ficheros
- Errores clásicos
- Cargar múltiples ficheros simultáneamente
- Carga por método PUT
- Ver también

## Cargas de ficheros por método POST

Esta funcionalidad permite a las personas subir tanto texto como ficheros binarios. Con las funciones de identificación y manipulación de ficheros de PHP, se tiene el control total para definir quién tiene derecho a subir, pero también qué se hará con el fichero una vez que se haya subido.

PHP es capaz de recibir ficheros emitidos por un navegador conforme a la norma RFC-1867.

> Nota: Notas de configuración

> Véase también las directivas file_uploads, upload_max_filesize, upload_tmp_dir, post_max_size y max_input_time en php.ini

PHP también soporta la carga por el método PUT como en el navegador Netscape Composer y Amaya del W3C. Consulte el capítulo sobre el soporte del método PUT.

Ejemplo #1 Formulario de carga de fichero

Un formulario de carga de ficheros puede ser construido creando un formulario específico como este:

    <!-- El tipo de codificación de datos, enctype, DEBE ser especificado como se indica a continuación -->
    <form enctype="multipart/form-data" action="_URL_" method="post">
      <!-- MAX_FILE_SIZE debe preceder al campo input de tipo file -->
      <input type="hidden" name="MAX_FILE_SIZE" value="30000" />
      <!-- El nombre del elemento input determina el nombre en el array $_FILES -->
      Envíe este fichero: <input name="userfile" type="file" />
      <input type="submit" value="Enviar el fichero" />
    </form>

`_URL_` en el ejemplo anterior debe ser reemplazado y apuntar a un fichero PHP.

El campo oculto `MAX_FILE_SIZE` (medido en bytes) debe preceder al campo input de tipo file y su valor representa el tamaño máximo aceptado del fichero por PHP. Este elemento de formulario debe ser siempre utilizado, ya que permite informar al usuario que la transferencia deseada es demasiado grande antes de llegar al final de la carga. Tenga en cuenta que este parámetro puede ser "engañado" fácilmente desde el lado del navegador, por lo que no se debe confiar en él, tratándose finalmente de una funcionalidad de conveniencia del lado del cliente. El parámetro PHP (del lado del servidor) sobre el tamaño máximo de un fichero cargado, no puede ser engañado.

> Nota:

> Asegúrese de que su formulario de carga de fichero contenga `enctype="multipart/form-data"`, de lo contrario, el fichero no será cargado.

La variable global $_FILES contendrá toda la información sobre el fichero cargado. Su contenido se detalla en nuestro ejemplo a continuación. Tenga en cuenta que se supone que el nombre de la variable del fichero cargado es userfile, tal como se define en el formulario anterior, pero puede ser cualquier nombre.

$_FILES['userfile']['name']

  El nombre original del fichero, tal como en la máquina del cliente web.

$_FILES['userfile']['type']

  El tipo MIME del fichero, si el navegador ha proporcionado esta información. Por ejemplo, esto podría ser `"image/gif"`. Este tipo mime no es verificado por PHP y, por lo tanto, no se debe tomar su valor para sincronizarse.

$_FILES['userfile']['size']

  El tamaño, en bytes, del fichero cargado.

$_FILES['userfile']['tmp_name']

  El nombre temporal del fichero que será cargado en la máquina servidor.

$_FILES['userfile']['error']

  El código de error asociado a la carga del fichero.

$_FILES['userfile']['full_path']

  La ruta completa tal como se envía por el navegador. Este valor no contiene siempre una verdadera jerarquía de carpetas, y no se debe confiar en él. Disponible a partir de PHP 8.1.0.

El fichero cargado será almacenado temporalmente en el directorio temporal del sistema, a menos que se proporcione otro directorio con la directiva upload_tmp_dir del php.ini. El directorio por defecto del servidor puede ser cambiado en el entorno a través de la variable TMPDIR. Modificar el valor de esta variable con la función putenv() en un script PHP será sin efecto. Esta variable de entorno también puede ser utilizada para asegurarse de que otras operaciones funcionen también en los ficheros cargados.

Ejemplo #2 Validación de carga de ficheros

Véase también las funciones is_uploaded_file() y move_uploaded_file() para más información. El siguiente ejemplo cargará un fichero desde un formulario.

    <?php
    $uploaddir = '/var/www/uploads/';
    $uploadfile = $uploaddir . basename($_FILES['userfile']['name']);

    echo '<pre>';
    if (move_uploaded_file($_FILES['userfile']['tmp_name'], $uploadfile)) {
        echo "El fichero es válido, y ha sido cargado con éxito. Aquí hay más información :\n";
    } else {
        echo "Ataque potencial por carga de ficheros. Aquí hay más información :\n";
    }

    echo 'Aquí hay algunas informaciones de depuración :';
    print_r($_FILES);

    echo '</pre>';

    ?>

El script PHP que recibe el fichero cargado debe poder gestionar el fichero de manera apropiada. Se puede utilizar la variable $_FILES['userfile']['size'] para recalar todos los ficheros que son demasiado grandes o demasiado pequeños. Se puede utilizar la variable $_FILES['userfile']['type'] para descartar los ficheros que no tienen el tipo correcto, pero utilizarla únicamente para una serie de verificaciones, ya que este valor está completamente bajo el control del cliente y no es verificado por PHP. Se puede utilizar la información en $_FILES['userfile']['error'] y adaptar su política en función de los códigos de error. Sea cual sea su política, se debe borrar el fichero del directorio temporal o moverlo.

Si no se selecciona ningún fichero en el formulario, PHP devolverá `0` en $_FILES['userfile']['size'] y nada en $_FILES['userfile']['tmp_name'].

El fichero será borrado automáticamente del directorio temporal al final del script, si no ha sido movido o renombrado.

Ejemplo #3 Envío de un array de ficheros

PHP soporta los arrays en HTML así como con los ficheros.

    <form action="" method="post" enctype="multipart/form-data">
    <p>Imágenes:
    <input type="file" name="pictures[]" />
    <input type="file" name="pictures[]" />
    <input type="file" name="pictures[]" />
    <input type="submit" value="Enviar" />
    </p>
    </form>

    <?php
    foreach ($_FILES["pictures"]["error"] as $key => $error) {
        if ($error == UPLOAD_ERR_OK) {
            $tmp_name = $_FILES["pictures"]["tmp_name"][$key];
            // basename() puede prevenir los ataques "filesystem traversal";
            // otra validación/limpieza del nombre de fichero puede ser apropiada
            $name = basename($_FILES["pictures"]["name"][$key]);
            move_uploaded_file($tmp_name, "data/$name");
        }
    }
    ?>

La barra de progreso de carga puede ser implementada utilizando la progresión de la carga a través de las sesiones.

## Explicación sobre los mensajes de errores de carga de ficheros

PHP devuelve un código de error apropiado en el array de ficheros. Este código de error es accesible en el índice `['error']` del array, que es creado durante la carga por PHP. En otras palabras, el mensaje de error es accesible en la variable $_FILES['userfile']['error'].

El valor de este código de error es una de las constantes `UPLOAD_ERR_*`.

## Errores clásicos

La variable `MAX_FILE_SIZE` no puede especificar un tamaño de fichero mayor que el tamaño que ha sido fijado por upload_max_filesize, en el php.ini. El valor por defecto es 2 megaoctetos.

Si se activa un límite de memoria, puede ser necesario un valor mayor de memory_limit. Asegúrese de haber definido un valor para memory_limit lo suficientemente grande.

Si el valor de max_execution_time es demasiado pequeño, el tiempo de ejecución del script puede exceder este valor. Asegúrese de haber definido un valor para `max_execution_time` lo suficientemente grande.

> Nota: max_execution_time afecta únicamente al tiempo de ejecución del script. El tiempo pasado en la actividad que aparece fuera de la ejecución del script como las llamadas al sistema con la función system(), la función sleep(), las consultas a las bases de datos, el tiempo empleado para realizar la carga del fichero, etc. no está incluido en el cálculo del tiempo máximo de ejecución del script.

Advertencia

max_input_time define el tiempo máximo, en segundos, para que el script reciba los datos; esto incluye la carga del fichero. Para múltiples ficheros, o ficheros grandes, o incluso para usuarios en conexiones lentas, el valor por defecto de `60` segundos puede ser superado.

Si post_max_size está definido de manera demasiado baja, los ficheros grandes no podrán ser cargados. Asegúrese de definir `post_max_size` con un tamaño suficiente.

La configuración de max_file_uploads controla el número máximo de ficheros que pueden ser enviados en una solicitud. Si el número de ficheros enviados supera este límite, entonces $_FILES dejará de recibir. Por ejemplo, si max_file_uploads vale `10`, entonces $_FILES nunca contendrá más de 10 entidades.

No validar los ficheros que se manipulan puede dar acceso a los usuarios a ficheros sensibles en otras carpetas.

Debido a la gran diversidad de sistemas, no se puede garantizar que los ficheros con nombres exóticos (por ejemplo, aquellos que contienen espacios) sean tratados correctamente.

El desarrollador no debe mezclar los campos `input` normales y los campos de carga en una misma variable (utilizando un nombre de `input` como `foo[]`).

## Cargar múltiples ficheros simultáneamente

La carga de múltiples ficheros es posible utilizando diferentes nombres en el atributo `name` de la etiqueta `input`.

También es posible cargar múltiples ficheros simultáneamente y obtener la información en forma de array. Para ello, se debe utilizar la sintaxis de array en los nombres de las etiquetas HTML, como se ha hecho con las selecciones múltiples y las casillas de verificación.

Ejemplo #1 Cargar múltiples ficheros simultáneamente

    <form action="file-upload.php" method="post" enctype="multipart/form-data">
      Envíe múltiples ficheros: <br />
      <input name="userfile[]" type="file" /><br />
      <input name="userfile[]" type="file" /><br />
      <input type="submit" value="Enviar los ficheros" />
    </form>

Cuando el formulario anterior ha sido enviado, los arrays $_FILES['userfile'], $_FILES['userfile']['name'], y $_FILES['userfile']['size'] serán inicializados.

Por ejemplo, supongamos que los ficheros /home/test/review.html y /home/test/xwp.out han sido cargados. En este caso, $_FILES['userfile']['name'][0] contiene review.html y $_FILES['userfile']['name'][1] contiene xwp.out. De manera similar, $_FILES['userfile']['size'][0] contendrá el tamaño del fichero review.html, etc.

$_FILES['userfile']['name'][0], $_FILES['userfile']['tmp_name'][0], $_FILES['userfile']['size'][0] y $_FILES['userfile']['type'][0] también son creados.

Advertencia

El parámetro max_file_uploads limita el número de ficheros que pueden ser enviados en una solicitud. Se debe verificar que su formulario no intente enviar más ficheros en la solicitud de lo que permite este límite.

Ejemplo #2 Cargar un directorio entero

En los campos de carga de fichero HTML, es posible cargar un directorio entero con el atributo `webkitdirectory`. Esta funcionalidad es soportada en la mayoría de los navegadores modernos.

Con la información `full_path`, es posible almacenar las rutas relativas o reconstruir la misma jerarquía de directorios en el directorio.

    <form action="file-upload.php" method="post" enctype="multipart/form-data">
      Envíe este directorio:<br />
      <input name="userfile[]" type="file" webkitdirectory multiple />
      <input type="submit" value="Enviar ficheros" />
    </form>

Advertencia

El atributo `webkitdirectory` no es estándar y no está actualmente en proceso de estandarización. Esto no debe ser utilizado en sitios de producción orientados al Web: no funcionará para todos los usuarios. Puede haber grandes incompatibilidades entre las implementaciones y el comportamiento puede cambiar en el futuro.

PHP analiza únicamente la información de las rutas relativas enviadas por el navegador/user-agent y transmite la información en el array $_FILES. No hay garantías de que los valores en el array `full_path` contengan una verdadera estructura de directorios y la aplicación PHP no debe confiar en esta información.

## Carga por método PUT

PHP soporta el método HTTP PUT utilizado por los navegadores para almacenar ficheros en un servidor. Las solicitudes de tipo PUT son mucho más simples que las cargas de ficheros utilizando el tipo POST, y se parecen a:

    PUT /path/filename.html HTTP/1.1

Normalmente, esto significa que el servidor remoto guardará los datos que siguen en el fichero: /path/filename.html de su disco. Esto no es, por supuesto, muy seguro permitir que Apache o PHP sobrescriban cualquier fichero de la arborescencia. Para evitar esto, primero se debe indicar al servidor que se desea que un script PHP dado gestione la solicitud. Con Apache, hay una directiva para ello: Script. Puede ser colocada en cualquier lugar del fichero de configuración de Apache. En general, los webmasters la colocan en el bloque `<Directory>`, o tal vez en el bloque `<VirtualHost>`. La siguiente línea hará muy bien el trabajo:

    Script PUT /put.php

Indica a Apache que debe enviar las solicitudes de carga por método PUT al script put.php. Por supuesto, esto presupone que se ha activado PHP para que maneje los ficheros de tipo .php, y que PHP está activo. El recurso de destino para todas las solicitudes PUT de este script debe ser el script mismo, y no el nombre del fichero que el fichero cargado debe tener.

Con PHP, se querría hacer algo como lo siguiente en su put.php. Esto copiará el contenido del fichero cargado en el fichero myputfile.ext en el servidor. Probablemente se querrá realizar algunas verificaciones y/o identificar al usuario antes de realizar esta copia de fichero.

Ejemplo #1 Guardado de ficheros HTTP PUT

    <?php
    /* Los datos PUT llegan del flujo */
    $putdata = fopen("php://input", "r");

    /* Abre un fichero para escritura */
    $fp = fopen("myputfile.ext", "w");

    /* Lectura de los datos, 1 Ko a la vez y escritura en el fichero */
    while ($data = fread($putdata, 1024))
    fwrite($fp, $data);

    /* Cierre del flujo */
    fclose($fp);
    fclose($putdata);
    ?>

## Ver también

- Seguridad de los ficheros

# Uso de ficheros a distancia

Mientras el soporte de los gestores de URL ("URL fopen wrapper") esté activado en el php.ini, con la opción allow_url_fopen, se puede utilizar URL (HTTP y FTP) con la mayoría de las funciones que utilizan un nombre de fichero como argumento. Esto incluye especialmente include, include_once, require y require_once (allow_url_include debe estar activo para utilizarlos). Consulte Protocolos y Envolturas soportados para más información sobre los protocolos soportados por PHP.

Por ejemplo, se puede seguir el siguiente ejemplo para abrir un fichero en un servidor web distante, analizar los resultados para extraer la información que se necesita, y luego utilizarla en una consulta de base de datos, o simplemente editar la información en el estilo del sitio.

Ejemplo #1 Conocer el título de una página distante

    <?php
    $file = fopen ("http://www.example.com/", "r");
    if (!$file) {
      echo "<p>Imposible leer la página.\n";
      exit;
    }
    while (!feof ($file)) {
        $line = fgets ($file, 1024);
        /* Esto solo funciona si las etiquetas Title están correctamente utilizadas */
        if (preg_match ("@\<title\>(.*)\</title\>@i", $line, $out)) {
            $title = $out[1];
            break;
        }
    }
    fclose($file);
    ?>

También se puede escribir ficheros en un servidor FTP siempre que se esté conectado con un usuario con los derechos de acceso adecuados, aunque el fichero no existiera aún.

Para conectarse con un usuario distinto de anónimo, se debe especificar un nombre de usuario (y probablemente la contraseña) en la URL, como `ftp://user:password@ftp.example.com/path/to/file`. (Se puede utilizar el mismo tipo de sintaxis para acceder a los ficheros vía HTTP cuando requieren una identificación simple).

Ejemplo #2 Almacenar datos en un servidor distante

    <?php
    $file = fopen ("ftp://ftp.example.com/incoming/outputfile", "w");
    if (!$file) {
      echo "<p>Imposible abrir el fichero distante para escritura.\n";
      exit;
    }
    /* Escritura de los datos. */
    fputs ($file, $_SERVER['HTTP_USER_AGENT'] . "\n");
    fclose ($file);
    ?>

> Nota:

> Nota: se puede tener la idea, a partir del ejemplo anterior, de utilizar la misma técnica para escribir en un log distante, pero como se mencionó anteriormente solo se puede escribir en un nuevo fichero utilizando las funciones fopen() con una URL. Para hacer logs distribuidos, se recomienda consultar la parte syslog().

# Gestión de las conexiones

El estado de las conexiones se conserva internamente por PHP. Hay cuatro estados posibles:

- 0 - NORMAL (normal)
- 1 - ABORTED (anulado)
- 2 - TIMEOUT (caducado)
- 3 - ABORTED and TIMEOUT (anulado y caducado)

Cuando un script PHP está en ejecución, el estado es NORMAL. Si el cliente remoto se desconecta, el estado se convierte en ABORTED. Una desconexión del cliente remoto generalmente es causada por los usuarios presionando su botón STOP. Si se supera el tiempo máximo de ejecución de PHP, (ver set_time_limit()), el script adopta el estado TIMEOUT.

Asimismo, se puede decidir si se desea que la desconexión de un cliente provoque la interrupción del script. A veces es práctico que los scripts continúen ejecutándose hasta el final, incluso si el cliente ya no está presente para recibir la información. Sin embargo, por omisión, el script se detendrá tan pronto como el cliente se desconecte. Este comportamiento puede ser modificado con la directiva ignore_user_abort en el fichero php.ini o bien con la directiva Apache `php_value ignore_user_abort` del fichero Apache httpd.conf o con la función ignore_user_abort(). Si no se solicita a PHP que ignore la desconexión, y el usuario se desconecta, el script será terminado. La única excepción es si se ha registrado una función de cierre, con register_shutdown_function(). Con tal función, cuando el usuario interrumpe su solicitud, en la próxima ejecución del script, PHP se dará cuenta de que el último script no ha sido terminado, y desencadenará la función de cierre. Esta función también será llamada al final del script, si este termina normalmente. Para poder tener un comportamiento diferente según el estado del script al finalizar, se pueden ejecutar comandos específicos a la desconexión gracias a la función connection_aborted(). Esta función devolverá `true` si la conexión ha sido anulada.

El script también puede ser interrumpido automáticamente después de un cierto tiempo. Por omisión, el tiempo límite es de 30 segundos. Este valor puede ser cambiado utilizando la directiva PHP max_execution_time en el fichero php.ini o con la directiva `php_value max_execution_time`, en el fichero Apache httpd.conf o también con la función set_time_limit(). Cuando el tiempo límite expira, el script es terminado, y como en la desconexión del cliente, una función de terminación será llamada. En esta función, se puede saber si es el tiempo límite el que ha causado el fin del script, llamando a la función connection_status(). Esta función devolverá `2` si el tiempo límite ha sido superado.

Una cosa a tener en cuenta es que los dos casos ABORTED y TIMEOUT pueden ser llamados al mismo tiempo. Esto es posible si se solicita a PHP que ignore las desconexiones de los usuarios. PHP aún así notará el hecho de que el usuario se ha desconectado, pero el script continuará. Luego, cuando alcance el límite de tiempo, el script caducará. En ese momento, la función connection_status() devolverá `3`.

# Conexiones persistentes a bases de datos

### ¿Qué son las conexiones persistentes?

Las conexiones persistentes son enlaces que no se cierran al finalizar la ejecución de un script. Cuando se solicita una conexión persistente, PHP comprueba si ya hay una idéntica (que ya estuviera abierta antes), utilizándola si existe. Si no, crea el enlace. Una conexión «idéntica» es una conexión que fue abierta por el mismo host, con el mismo usuario y la misma contraseña (donde sea aplicable).

No hay ningún método para solicitar una conexión específica, o garantizar si obtendrá una conexión existente o una nueva (si todas las conexiones existentes están en uso, o la solicitud está siendo atendida por un trabajador diferente, el cual tiene un grupo separado de conexiones).

Esto significa que no puedes usar las conexiones persistentes de PHP para, por ejemplo:

- asignar una sesión de base de datos específica a un usuario web específico
- crear una transacción grande en múltiples solicitudes
- iniciar una consulta en una solicitud y recopilar los resultados en otra

Las conexiones persistentes no le brindan ninguna funcionalidad que no fuera posible con las conexiones no persistentes.

### Solicitudes web

Hay dos formas las cuales su servidor web puede utilizar PHP para generar páginas web:

El primer método es emplear PHP como una «envoltura» CGI. Cuando se ejecuta de esta forma, se crea y se destruye una instancia del intérprete de PHP por cada solicitud de página (para una página de PHP) al servidor web. Debido a que esta instancia se destruye después de cada solicitud, cualquier recurso que adquiera (tal como un enlace a un servidor de base de datos SQL) es cerrado en la destrucción de dicha instancia. En este caso, no se gana nada utilizando conexiones persistentes: simplemente no persisten.

El segundo método, y más popular, es ejecutar PHP-FPM, o PHP como módulo en un servidor web multiproceso, lo que actualmente solo incluye a Apache. Estas configuraciones suelen tener un proceso (el padre) que coordina un grupo de procesos (sus hijos) los cuales son los que realmente hacen el trabajo de servir páginas web. Cuando una solicitud proviene de un cliente, esta es cedida a uno de los hijos que no esté ya sirviendo a otro cliente. Esto significa que cuando el mismo cliente hace una segunda solicitud al servidor, esta podría ser servida por un proceso hijo diferente a la primera vez. Una vez que se ha abierto una conexión persistente, cualquier solicitud posterior servida por el mismo proceso hijo puede reusar la conexión ya establecida al servidor SQL.

> Nota:

> Puede comprobar qué método utilizan sus solicitudes web consultando el valor de "Server API" en la salida de phpinfo() o el valor de `PHP_SAPI`, ejecutado desde una solicitud web.

> Si la API del servidor es "Apache 2 Handler" o "FPM/FastCGI", se usarán conexiones persistentes en todas las solicitudes atendidas por el mismo trabajador. Con cualquier otro valor, las conexiones persistentes no persistirán después de cada solicitud.

### Procesos de línea de comandos

Dado que PHP de línea de comandos utiliza un nuevo proceso para cada script, las conexiones persistentes no se comparten entre scripts de línea de comandos, por lo que no tiene sentido usarlas en scripts transitorios como crons o comandos. Sin embargo, pueden ser útiles si, por ejemplo, se está desarrollando un servidor de aplicaciones de larga duración que atiende muchas solicitudes o tareas, y cada una puede necesitar su propia conexión a la base de datos.

### ¿Por qué usarlas?

Las conexiones persistentes son recomendables si la sobrecarga para crear un enlace a su servidor SQL es alta. Que esta sobrecarga sea realmente alta o no depende de muchos factores, como el tipo de base de datos que se emplea, si esta se encuentra en la misma computadora en la que está el servidor web, la carga de la máquina donde está el servidor SQL, etc. En resumidas cuentas, si la sobrecarga de una conexión es alta, las conexiones persistentes ayudan considerablemente, haciendo que un proceso hijo únicamente se conecte una vez durante su vida útil, en lugar de hacerlo cada vez que procese una página que requiera una conexión al servidor SQL. Esto significa que cada hijo que abra una conexión persistente tendrá su propia conexión persistente abierta al servidor. Por ejemplo, si se tienen 20 procesos hijos diferentes que ejecutan un script que realiza una conexión persistente al servidor SQL, se tendrán 20 conexiones diferentes al servidor SQL, una por cada hijo.

### Posibles inconvenientes: Límites de conexión

Observe, sin embargo, que esto puede tener algunos inconvenientes si se está usando una base de datos con un limite de conexiones que sea excedido por las conexiones persistentes hijas. Si la base de datos tiene un limite de 16 conexiones simultáneas, y en el curso de una sesión de un servidor ocupado 17 hilos hijos intentan conectarse, uno de ellos no será capaz de hacerlo. Si un script contiene errores que impidan el cierre de las conexiones (como un bucle infinito), la mencionada base de datos con solamente 16 conexiones podría saturarse rápidamente.

Las conexiones persistentes suelen aumentar el número de conexiones abiertas en un momento dado, ya que los procesos inactivos mantienen las conexiones utilizadas en las solicitudes anteriores que atendieron. Si se inicia un gran número de procesos para manejar una oleada de solicitudes, las conexiones que estos abrieron permanecerán activas hasta que el proceso sea finalizado o el servidor de base de datos cierre la conexión.

Asegúrate de que el número máximo de conexiones permitidas por el servidor de base de datos sea superior al número máximo de procesos que atienden solicitudes web (más cualquier otro uso adicional, como tareas programadas o conexiones administrativas).

Consulta la documentación de tu base de datos para obtener información sobre cómo manejar conexiones abandonadas o inactivas (timeouts). Los timeouts largos pueden aumentar significativamente el número de conexiones persistentes abiertas en un momento dado.

### Posibles inconvenientes: Mantenimiento del estado de la conexión

Algunas extensiones de base de datos realizan limpieza automática al reutilizar la conexión; otras delegan esta tarea en el desarrollador de la aplicación. Según la extensión utilizada y el diseño de la aplicación, puede ser necesario realizar una limpieza manual antes de que el script finalice. Los cambios que pueden dejar la conexión en un estado inesperado incluyen:

- Base de datos seleccionada o por defecto
- Bloqueos de tablas
- Transacciones no confirmadas
- Tablas temporales
- Configuraciones o características específicas de la conexión, como el perfilado

Los bloqueos de tablas y las transacciones que no se limpian ni cierran pueden provocar que otras consultas queden bloqueadas indefinidamente o que la reutilización posterior de la conexión genere cambios inesperados.

Tener seleccionada una base de datos incorrecta puede impedir que la conexión reutilizada ejecute las consultas como se espera (o que las ejecute sobre la base de datos equivocada si los esquemas son suficientemente similares).

Si no se eliminan las tablas temporales, las solicitudes posteriores no podrán recrear la misma tabla.

Puede implementar la limpieza utilizando destructores de clase o la función register_shutdown_function(). También puede considerar el uso de proxies dedicados para agrupación de conexiones que incluyan esta funcionalidad.

### Palabras finales

Dado su comportamiento y los posibles inconvenientes descritos anteriormente, no debería utilizar conexiones persistentes sin una evaluación cuidadosa. No deben emplearse sin realizar cambios adicionales en su aplicación y sin una configuración meticulosa del servidor de base de datos, del servidor web y/o de PHP-FPM.

Considere soluciones alternativas, como investigar y corregir las causas del sobrecoste en la creación de conexiones (por ejemplo, desactivar las búsquedas inversas de DNS en el servidor de base de datos), o utilizar proxies dedicados para agrupación de conexiones.

Para APIs web de alto volumen, considere el uso de entornos de ejecución alternativos o servidores de aplicaciones de larga duración.

### Ver también

- ibase_pconnect()
- oci_pconnect()
- odbc_pconnect()
- pfsockopen()
- pg_connect()
- Mysqli y conexiones persistentes
- Gestor de conexiones PDO

# Utilización de la línea de comandos

## Tabla de contenidos

- Diferencia con otros SAPIs
- Opciones
- Utilización
- Flujos I/O
- Shell Interactivo
- Servidor web interno
- Configuraciones INI

## Introducción

El propósito principal de CLI SAPI es el desarrollo de aplicaciones shell con PHP. Las diferencias entre CLI SAPI y otros SAPI se explican en este capítulo. Es importante mencionar que CLI y CGI son SAPI diferentes a pesar de que puedan compartir la mayor parte de sus comportamientos.

El CLI SAPI se activa por defecto utilizando la opción --enable-cli, pero se puede desactivar utilizando la opción --disable-cli al ejecutar el comando ./configure.

El nombre, la ubicación y la existencia de los binarios CLI/CGI dependerán de la forma en que PHP esté instalado en su sistema. Por defecto, al ejecutar make, ambos binarios CGI y CLI se compilan y se nombran respectivamente sapi/cgi/php y sapi/cli/php en su directorio fuente PHP. Se observará que ambos se nombran php. Lo que sucede después durante el make install depende de su línea de configuración. Si un módulo SAPI, como apxs, se ha elegido durante la configuración, o si la opción --disable-cgi se ha activado, el CLI se copia en {PREFIX}/bin/php durante el make install, de lo contrario, el CGI se colocará aquí. Si, por ejemplo, --with-apxs figura en su línea de configuración, el CLI se copia en {PREFIX}/bin/php durante el make install. Si se desea forzar la instalación del binario CGI, ejecute make install-cli después del make install. De lo contrario, también se puede especificar --disable-cgi en su línea de configuración.

> Nota:

> Dado que ambas opciones --enable-cli y --enable-cgi están activadas por defecto, tener simplemente --enable-cli en su línea de configuración no implica necesariamente que el CLI se renombre a {PREFIX}/bin/php durante el make install.

El binario CLI se distribuye en el directorio principal bajo el nombre de php.exe en Windows. La versión CGI se distribuye bajo el nombre de php-cgi.exe. Además, un archivo php-win.exe se distribuye si PHP se configura utilizando la opción de configuración --enable-cli-win32. Este archivo hace lo mismo que la versión CLI, excepto que no muestra nada y no proporciona una consola.

> Nota: ¿Qué SAPI está instalado?

> Desde un terminal, ejecutar php -v indicará si php está en versión CGI o CLI. También se puede consultar la función php_sapi_name() y la constante `PHP_SAPI`.

> Nota:

> Una página `man` de manual Unix está disponible escribiendo man php en el intérprete de comandos.

## Diferencia con otros SAPIs

Las diferencias más notables entre el CLI SAPI y los otros SAPI son:

- A diferencia del CGI SAPI, ningún encabezado HTTP se escribe en el resultado.

  Aunque el CGI SAPI proporciona una forma de eliminar los encabezados HTTP, no es posible activar los encabezados HTTP en el CLI SAPI.

  CLI se ejecuta en modo silencioso por defecto, aunque las opciones -q y --no-header se mantienen para mantener la compatibilidad con versiones anteriores de CGI.

  No cambia el directorio actual al del script. (Las opciones -C y --no-chdir se mantienen por razones de compatibilidad).

  Mensajes de error en texto plano (sin formato HTML).

- Hay varias directivas del php.ini que son ignoradas por el CLI SAPI, ya que no tienen sentido en un entorno shell:

  Directivas php.ini ignoradas
  Directiva | Valor por defecto para CLI SAPI | Comentario
  --- | --- | ---
  html_errors | `false` | Por defecto a `false`, ya que puede ser bastante difícil leer mensajes de error en un terminal cuando están enterrados en etiquetas HTML no interpretadas.
  implicit_flush | `true` | En un terminal, generalmente es deseable que cualquier salida de print, echo y otros, se muestre inmediatamente, y no se coloque en un búfer. Sin embargo, siempre es posible utilizar la bufferización de salida si se desea retrasar una salida, o bien manipular su contenido una última vez.
  max_execution_time | 0 (sin límite) | PHP en un terminal es susceptible de ser utilizado para tareas mucho más diversas que en scripts web, y dado que esto generalmente toma mucho tiempo, este parámetro se establecerá por defecto a 0 permitiendo así ser ilimitado.
  register_argc_argv | `true` | El establecimiento de esta directiva a `true` significa que los scripts ejecutados a través del SAPI CLI siempre tendrán acceso a argc (representando el número de argumentos pasados a la aplicación) y argv (el array que contiene los argumentos pasados). Las variables PHP $argc y $argv se definen y rellenan automáticamente con los valores apropiados, al utilizar el SAPI CLI. Estos valores también pueden encontrarse en la variable $_SERVER, por ejemplo: $_SERVER['argv']. Advertencia La presencia de $argv o $_SERVER['argv'] no es una indicación fiable de que un script se está ejecutando desde la línea de comandos, ya que estas variables pueden definirse en otros contextos cuando register_argc_argv está activado. El valor devuelto por php_sapi_name() debe verificarse en su lugar.
      <?php

      if (php_sapi_name() === 'cli') {
          echo "¡Este script se está ejecutando desde la línea de comandos!\n";
      }
  Advertencia Esta característica está OBSOLETA a partir de PHP 8.5.0. Depender de esta característica está altamente desaconsejado.
  output_buffering | `false` | Aunque esta configuración INI está codificada a `false`, las funciones relacionadas con la visualización del búfer están disponibles.
  max_input_time | `false` | El PHP CLI no soporta GET, POST y la carga de archivos.

  > Nota:

  > Estas directivas no pueden inicializarse con otros valores en el archivo php.ini o por cualquier otro método. Es una limitación, ya que estos valores por defecto se aplican una vez que todos los otros archivos de configuración han sido analizados. Sin embargo, estos valores pueden modificarse durante la ejecución (lo cual no es lógico para ciertas directivas, como register_argc_argv).

  > Nota:

  > Se recomienda establecer ignore_user_abort para los scripts en línea de comandos. Consulte la función ignore_user_abort() para más información.

- Para facilitar el trabajo en un entorno shell, se definen varias constantes para los flujos I/O.

- El CLI SAPI no transforma el directorio actual en el directorio de ejecución del script.

  Ejemplo #1 Ejemplo que muestra la diferencia con el SAPI CGI:

      <?php
      // Una prueba simple: muestra el directorio de ejecución */
      echo getcwd(), "\n";
      ?>

  Cuando se utiliza la versión CGI, la salida será:

      $ pwd
      /tmp

      $ php -q otro_directorio/test.php
      /tmp/otro_directorio

  Esto muestra claramente que PHP cambia el directorio actual y utiliza el directorio del script ejecutado.

  Al utilizar el CLI SAPI, se obtiene:

      $ pwd
      /tmp

      $ php -f otro_directorio/test.php
      /tmp

  Esto proporciona mucha más flexibilidad al escribir scripts shell con PHP.

  > Nota:

  > El CGI SAPI se comporta de la misma manera que el CLI SAPI, pasándole la opción -C, cuando se invoca en la línea de comandos.

## Opciones de línea de comandos

La lista de opciones de línea de comandos proporcionadas por PHP está disponible en cualquier momento ejecutando PHP con la opción -h:

    Uso: php [opciones] [-f] <archivo> [--] [args...]
       php [opciones] -r <código> [--] [args...]
       php [opciones] [-B <begin_code>] -R <código> [-E <end_code>] [--] [args...]
       php [opciones] [-B <begin_code>] -F <archivo> [-E <end_code>] [--] [args...]
       php [opciones] -- [args...]
       php [opciones] -a

      -a               Ejecutar de forma interactiva
      -c <ruta>|<archivo> Buscar el archivo php.ini en este directorio
      -n               No se utilizará ningún archivo php.ini
      -d foo[=bar]     Definir la entrada INI foo con el valor 'bar'
      -e               Generar información extendida para el depurador/perfilador
      -f <archivo>     Analizar y ejecutar <archivo>.
      -h               Esta ayuda
      -i               Información de PHP
      -l               Verificación de sintaxis únicamente (lint)
      -m               Mostrar módulos compilados
      -r <código>      Ejecutar el código PHP sin usar etiquetas de script <?..?>
      -B <begin_code>  Ejecutar <begin_code> antes de procesar las líneas de entrada
      -R <código>      Ejecutar el código PHP para cada línea de entrada
      -F <archivo>     Analizar y ejecutar <archivo> para cada línea de entrada
      -E <end_code>    Ejecutar <end_code> después de procesar todas las líneas de entrada
      -H               Ocultar cualquier argumento pasado de herramientas externas.
      -S <dirección>:<puerto> Ejecutar con el servidor web integrado.
      -t <docroot>     Especificar el directorio raíz del documento para el servidor web integrado.
      -s               Salida de sintaxis HTML resaltada.
      -v               Número de versión
      -w               Salida de código fuente con comentarios y espacios en blanco eliminados.

      args...          Argumentos pasados al script. Usar -- args cuando el primer argumento
                       comienza con - o el script se lee desde stdin

      --ini            Mostrar nombres de archivos de configuración

      --rf <nombre>     Mostrar información sobre la función <nombre>.
      --rc <nombre>     Mostrar información sobre la clase <nombre>.
      --re <nombre>     Mostrar información sobre la extensión <nombre>.
      --rz <nombre>     Mostrar información sobre la extensión Zend <nombre>.
      --ri <nombre>     Mostrar configuración para la extensión <nombre>.

Opciones de línea de comandos
Opción | Opción larga | Descripción
--- | --- | ---
-a | --interactive | Lanza PHP de forma interactiva. Para más información, consulte la documentación sobre el shell interactivo.
-b | --bindpath | Enlaza la ruta para los externos, en modo servidor FASTCGI (solo CGI).
-C | --no-chdir | No ir al directorio del script (solo CGI).
-q | --no-header | Modo silencioso. Suprime la salida de los encabezados HTTP (solo CGI).
-T | --timing | Mide el tiempo de ejecución del script, repetido count veces (solo CGI).
-c | --php-ini | Especifica el nombre del directorio en el que se encuentra el archivo php.ini, o bien especifica un archivo de configuración (`INI`) directamente (que no se llama necesariamente php.ini):
    $ php -c /custom/directory/ mon_script.php

    $ php -c /custom/directory/custom-file.ini mon_script.php
Si esta opción no se especifica, php.ini se buscará en los lugares por defecto.
-n | --no-php-ini | Ignora completamente php.ini.
-d | --define | Define un valor personalizado para cualquier directiva de configuración del archivo php.ini. La sintaxis es:
     -d configuration_directive[=value]
Ejemplo #1 Ejemplo de uso de `-d` para establecer una configuración INI
    # La omisión del valor conduce a dar el valor de "1"
    $ php -d max_execution_time
            -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
    string(1) "1"

    # Pasar un valor vacío conduce a dar el valor de ""
    php -d max_execution_time=
            -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
    string(0) ""

    # La directiva de configuración será cualquier valor pasado después del carácter '='
    $  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 | --profile-info | Genera información extendida para la depuración y el perfilado.
-f | --file | Analiza y ejecuta el archivo especificado. La opción -f es opcional y puede omitirse. El nombre del archivo es suficiente.
-h y -? | --help y --usage | Muestra información sobre la lista actual de opciones de la línea de comandos, así como su descripción.
-i | --info | Llama a la función phpinfo() y muestra el resultado. Si PHP no funciona correctamente, se recomienda utilizar el comando php -i y ver si no hay errores mostrados antes o después de la tabla de información. No olvide que el resultado de esta opción, si se utiliza el modo CGI, está en formato HTML y, por lo tanto, es de tamaño considerable.
-l | --syntax-check | Verifica la sintaxis pero no ejecuta el código PHP dado. La entrada proveniente de la entrada estándar se procesará si no se especifica ningún nombre de archivo, de lo contrario, cada archivo especificado se verificará. En caso de éxito, se muestra el mensaje `No syntax errors detected in <filename>` (Literalmente, no se detectaron errores de sintaxis en el archivo) en la salida estándar. En caso de error, se muestra el mensaje `Errors parsing <filename>` (Literalmente, error de análisis en el archivo filename) junto con los mensajes de error detectados por el analizador mismo. Si se encuentran errores en los archivos especificados (o en la entrada estándar), el código de retorno del shell se establece en `-1`, de lo contrario, el código de retorno del shell se establece en `0`. Esta opción no detecta errores fatales (por ejemplo, funciones no definidas) que requieren la ejecución del código. Nota: Antes de PHP 8.3.0, solo se podía especificar un nombre de archivo para verificar. Nota: Esta opción no funciona con la opción -r.
-m | --modules | Ejemplo #2 Mostrar módulos internos (y cargados) de PHP y Zend
    $ php -m
    [PHP Modules]
    xml
    tokenizer
    standard
    session
    posix
    pcre
    overload
    mysql
    mbstring
    ctype

    [Zend Modules]
> -r | --run | Permite la ejecución de PHP directamente en la línea de comandos. Las etiquetas de PHP (`<?php` y `?>`) no son necesarias y causarán un error de análisis si están presentes. Nota: Se debe prestar especial atención al utilizar esta opción de PHP para que no haya colisión con las sustituciones de variables en la línea de comandos realizadas por el shell. Ejemplo #3 Error de sintaxis al usar comillas dobles
>     $ php -r "$foo = get_defined_constants();"
>     PHP Parse error:  syntax error, unexpected '=' in Command line code on line 1

>     Parse error: syntax error, unexpected '=' in Command line code on line 1
> El problema aquí es que el shell (sh/bash) realiza una sustitución de variables, incluso con las comillas dobles `"`. Dado que la variable $foo probablemente no está definida en el shell, se reemplaza por nada, lo que hace que el código pasado a PHP para ejecutar sea:
>     $ php -r " = get_defined_constants();"
> La solución a este problema es utilizar comillas simples `'`. Las variables de estas cadenas no serán sustituidas por sus valores por el shell. Ejemplo #4 Uso de comillas simples para evitar una sustitución por el shell
>     $ 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 se utiliza un shell diferente de sh/bash, pueden encontrarse otros problemas; si es apropiado, se puede abrir un informe de errores a través de » https://github.com/php/php-src/issues. Es muy fácil tener problemas al intentar incluir variables de shell en el código, o al usar las barras invertidas para la protección. ¡Se le ha advertido! Nota: -r está disponible con el CLI SAPI pero no con el SAPI CGI. Nota: Esta opción solo se utiliza para cosas simples. Por lo tanto, algunas directivas de configuración (por ejemplo, auto_prepend_file y auto_append_file) se ignoran en este modo.
-B | --process-begin | Código PHP a ejecutar antes de procesar stdin.
-R | --process-code | Código PHP a ejecutar para cada línea de entrada. Hay dos variables especiales disponibles en este modo: $argn y $argi. $argn debe contener la línea PHP procesada en ese momento, mientras que $argi debe contener el número de la línea.
-F | --process-file | Archivo PHP a ejecutar para cada línea de entrada.
-E | --process-end | Código PHP a ejecutar después de realizar la entrada. Ejemplo #5 Ejemplo de uso de las opciones -B, -R y -E para contar el número de líneas de un proyecto.
    $ find my_proj | php -B '$l=0;' -R '$l += count(@file($argn));' -E 'echo "Total Lines: $l\n";'
    Total Lines: 37328
-S | --server | Inicia el servidor web interno. Disponible desde 5.4.0.
-t | --docroot | Especifica la raíz de los documentos para el servidor web interno.
-s | --syntax-highlight y --syntax-highlighting | Muestra el código con colorización de sintaxis. Esta opción utiliza el mecanismo interno para analizar el archivo y escribir una versión coloreada del código fuente en formato HTML. Tenga en cuenta que esta opción solo genera un bloque HTML, con las etiquetas HTML `<code> [...] </code>`, sin encabezados HTML. Nota: Esta opción no funciona con la opción -r.
-v | --version | Ejemplo #6 Uso de la opción -v para recuperar el nombre del SAPI así como la versión de PHP y de Zend
    $ php -v
    PHP 5.3.1 (cli) (built: Dec 11 2009 19:55:07)
    Copyright (c) 1997-2009 The PHP Group
    Zend Engine v2.3.0, Copyright (c) 1998-2009 Zend Technologies
-w | --strip | Muestra el código fuente sin comentarios ni espacios. Nota: Esta opción no funciona con la opción -r.
| --ini | Muestra los nombres de los archivos de configuración y los directorios analizados. Opcionalmente, pasar `--ini=diff` para mostrar las diferencias entre los archivos de configuración cargados y la configuración por omisión. Ejemplo #7 Ejemplo con `--ini`
    $ php --ini
    Configuration File (php.ini) Path: /usr/dev/php/5.2/lib
    Loaded Configuration File:         /usr/dev/php/5.2/lib/php.ini
    Scan for additional .ini files in: (none)
    Additional .ini files parsed:      (none)
Nota: La opción `--ini=diff` no está disponible antes de PHP 8.5.0.
--rf | --rfunction | Muestra información sobre la función dada o el método de una clase (es decir, número y nombre de los parámetros). Esta opción solo está disponible si PHP se ha compilado con soporte Reflection. Ejemplo #8 Ejemplo con `--rf`
    $ php --rf var_dump
    Function [ <internal> public function var_dump ] {

      - Parameters [2] {
        Parameter #0 [ <required> $var ]
        Parameter #1 [ <optional> $... ]
      }
    }
--rc | --rclass | Muestra información sobre la clase dada (lista de constantes, propiedades y métodos). Esta opción solo está disponible si PHP se ha compilado con soporte Reflection. Ejemplo #9 Ejemplo con `--rc`
    $ php --rc Directory
    Class [ <internal:standard> class Directory ] {

      - Constants [0] {
      }

      - Static properties [0] {
      }

      - Static methods [0] {
      }

      - Properties [0] {
      }

      - Methods [3] {
        Method [ <internal> public method close ] {
        }

        Method [ <internal> public method rewind ] {
        }

        Method [ <internal> public method read ] {
        }
      }
    }
--re | --rextension | Muestra la información sobre la extensión dada (lista las opciones del php.ini, las funciones definidas, las constantes y las clases). Esta opción solo está disponible si PHP se ha compilado con soporte Reflection. Ejemplo #10 Ejemplo con `--re`
    $ php --re json
    Extension [ <persistent> extension #19 json version 1.2.1 ] {

      - Functions {
        Function [ <internal> function json_encode ] {
        }
        Function [ <internal> function json_decode ] {
        }
      }
    }
--rz | --rzendextension | Muestra la información de configuración para la extensión Zend proporcionada (la misma información que la devuelta por la función phpinfo()).
--ri | --rextinfo | Muestra la información de configuración para la extensión dada (la misma información devuelta por la función phpinfo()). Las informaciones de configuración internas están disponibles utilizando el nombre de extensión "main" o "core". Ejemplo #11 Ejemplo con `--ri`
    $ php --ri date

    date

    date/time support => enabled
    "Olson" Timezone Database Version => 2009.20
    Timezone Database => internal
    Default timezone => Europe/Oslo

    Directive => Local Value => Master Value
    date.timezone => Europe/Oslo => Europe/Oslo
    date.default_latitude => 59.930972 => 59.930972
    date.default_longitude => 10.776699 => 10.776699
    date.sunset_zenith => 90.583333 => 90.583333
    date.sunrise_zenith => 90.583333 => 90.583333

> Nota:

> Las opciones `-rBRFEH`, `--ini` y `--r[fcezi]` solo están disponibles en modo CLI.

## Ejecución de archivos PHP

Hay 3 formas diferentes de llamar al CLI SAPI con código PHP a ejecutar:

1. Indicar a PHP que ejecute un archivo dado:

       php mon_script.php

       php -f mon_script.php

   Ambos métodos (usando -f o no) ejecutan el script contenido en el archivo mon_script.php. Tenga en cuenta que no existe restricción sobre los archivos que se pueden ejecutar; en particular, no es necesario que la extensión del archivo sea `.php`.

2. Dar código PHP a ejecutar directamente en la línea de comandos.

       php -r 'print_r(get_defined_constants());'

   En este caso, se debe prestar especial atención a las variables de entorno, que serán reemplazadas, y a las comillas, que tienen significados especiales en la línea de comandos.

   > Nota:

   > Lea el ejemplo con atención, ¡no hay etiquetas de apertura ni de cierre! La opción -r hace que el uso de estas etiquetas sea innecesario, y agregarlas conduciría a un error de análisis sintáctico.

3. Alimentar la entrada estándar con código PHP (`stdin`).

   Esto proporciona la posibilidad de crear código PHP dinámicamente, luego proporcionarlo a PHP y, finalmente, procesarlo nuevamente en el shell. Aquí hay un ejemplo ficticio:

       $ some_application | some_filter | php | sort -u > final_output.txt

No es posible combinar estos tres modos de ejecución.

Como cualquier aplicación shell, el ejecutable PHP acepta argumentos; sin embargo, el script PHP también puede recibirlos. El número de argumentos que se pueden pasar a su script no está limitado por PHP (el shell tiene un límite en términos de número de caracteres que se pueden pasar. Generalmente, no alcanzará este límite). Los argumentos pasados al script se transmitirán a través de la variable array $argv. El primer índice (cero) contiene siempre el nombre del script llamado desde la línea de comandos. Tenga en cuenta que, si el código se ejecuta en línea usando la opción de línea de comandos -r, el valor de $argv[0] será `"Standard input code"`; anterior a PHP 7.2.0, era un guion (`"-"`) en su lugar. Esto también es cierto si el código se ejecuta a través de un pipe desde `STDIN`.

Una segunda variable global, $argc, contiene el número de elementos del array $argv (y no el número de argumentos pasados a su script).

Mientras los argumentos pasados al script no comiencen con el carácter `-`, no hay nada especial que vigilar. El hecho de pasar argumentos al script que comienzan con `-` plantea problemas porque PHP pensará que debe interpretarlos. Para evitar esto, use el separador `--`. Después de este argumento, todos los argumentos siguientes se pasarán al script sin ser modificados ni analizados por PHP.

    # Esto no ejecutará el código, sino que mostrará la ayuda de PHP
    $ php -r 'var_dump($argv);' -h
    Uso: php [opciones] [-f] <archivo> [args...]
    [...]

    # Esto pasará el argumento '-h' al script y evitará que PHP lo maneje
    $ php -r 'var_dump($argv);' -- -h
    array(2) {
      [0]=>
      string(1) "-"
      [1]=>
      string(2) "-h"
    }

Sin embargo, hay otra forma de usar PHP como script shell; la primera línea del script debe ser `#!/usr/bin/php` (a reemplazar por la ruta hacia el binario PHP CLI en el sistema subyacente). El resto del archivo debe contener el código PHP normal, comprendido entre las etiquetas de apertura/cierre. Después de establecer los permisos de ejecución en el script (chmod +x test), puede ejecutarse como un script shell o perl habitual:

Ejemplo #1 Ejecuta un script PHP como script shell

    #!/usr/bin/php
    <?php
    var_dump($argv);
    ?>

Suponiendo que este archivo se llame test, en el directorio actual, entonces es posible hacer esto:

    $ chmod +x test
    $ ./test -h -- foo
    array(4) {
       [0]=>
       string(6) "./test"
       [1]=>
       string(2) "-h"
       [2]=>
       string(2) "--"
       [3]=>
       string(3) "foo"
    }

Como puede ver, en este caso, no es necesario tener cuidado al pasar parámetros que comienzan con `-` a su script.

El ejecutable PHP puede ser utilizado para ejecutar scripts independientes del servidor web. Si está en un sistema Unix, se recomienda agregar la línea especial al inicio del script, hacerlo ejecutable de manera que el sistema sepa qué programa debe ejecutar el script. En Windows, puede asociar el ejecutable php.exe con el doble clic en los archivos de extensión `.php`, o bien puede hacer un archivo batch para ejecutar el script gracias a PHP. La primera línea utilizada en el mundo Unix no perturbará la ejecución en Windows, lo que hace que los scripts sean fácilmente portables. Un ejemplo completo se proporciona a continuación:

Ejemplo #2 Script previsto para ser ejecutado en línea de comandos (script.php)

    #!/usr/bin/php
    <?php

    if ($argc != 2 || in_array($argv[1], array('--help', '-help', '-h', '-?'))) {
    ?>

    Esto es una línea de comando a una opción.

      Uso:
      <?php echo $argv[0]; ?> <opción>

      <opción> puede ser una palabra que desee mostrar.
      Con las opciones --help, -help, -h,
      y -?, obtendrá esta ayuda.

    <?php
    } else {
        echo $argv[1];
    }
    ?>

El script anterior incluye la primera línea especial que indica que este archivo debe ser ejecutado por PHP. Se trabaja aquí con la versión CLI, por lo que no se mostrará ningún encabezado HTTP.

El programa comienza verificando que se haya especificado el argumento requerido (además del nombre del script, que también se cuenta). Si no está presente, o si el argumento es --help, -help, -h o -?, se mostrará un mensaje de ayuda, utilizando $argv[0] para mostrar dinámicamente el nombre del script tal como se ingresó en la línea de comandos. De lo contrario, el argumento se mostrará tal como se ingresó en el terminal.

Para ejecutar el script anterior en Unix, debe hacerlo ejecutable y luego llamarlo con un comando como: script.php echothis o script.php -h. En Windows, puede hacer un archivo batch para esto:

Ejemplo #3 Archivo batch para ejecutar un script PHP en línea de comandos (script.bat)

    @echo OFF
    "C:\php\php.exe" script.php %*

Suponiendo que el programa anterior se llame script.php, y que el ejecutable CLI php.exe se encuentre en C:\php\php.exe, este archivo batch lo ejecutará con las opciones que le pase: script.bat echothis o script.bat -h.

Vea también la extensión Readline, que dispone de numerosas funciones para mejorar la usabilidad de las aplicaciones PHP en línea de comandos.

En Windows, PHP puede configurarse para funcionar sin necesidad de proporcionar las extensiones C:\php\php.exe o `.php`, tal como se describe en la línea de comandos PHP bajo Microsoft Windows.

> Nota:

> En Windows, se recomienda ejecutar PHP bajo una cuenta de usuario. Cuando PHP se ejecuta bajo un servicio de red, algunas operaciones pueden fallar, ya que "No se realiza ninguna vinculación entre los nombres de cuenta y los identificadores de seguridad".

## Flujos de entrada/salida

El CLI SAPI define algunas constantes para los flujos I/O para hacer que la programación en línea de comandos sea más fácil.

Constantes específicas CLI
Constante | Descripción
--- | ---
`STDIN` | Un flujo ya abierto hacia `stdin`. Esto evita abrirlo explícitamente con
    <?php
    $stdin = fopen('php://stdin', 'r');
    ?>
Si desea leer una sola línea desde `stdin`, puede usar
    <?php
    $line = trim(fgets(STDIN)); // lee una línea desde STDIN
    fscanf(STDIN, "%d\n", $number); // lee números desde STDIN
    ?>
`STDOUT` | Un flujo ya abierto hacia `stdout`. Esto evita abrirlo explícitamente con
    <?php
    $stdout = fopen('php://stdout', 'w');
    ?>
`STDERR` | Un flujo ya abierto hacia `stderr`. Esto evita abrirlo explícitamente con
    <?php
    $stderr = fopen('php://stderr', 'w');
    ?>

Por lo tanto, no es necesario abrir un flujo específico para, por ejemplo, `stderr` pero se puede usar simplemente la constante correspondiente a ese flujo:

    php -r 'fwrite(STDERR, "stderr\n");'

No es necesario cerrar explícitamente estos flujos, ya que se cerrarán automáticamente por PHP al final de su script.

> Nota:

> Estas constantes no están disponibles cuando se lee un script PHP desde `stdin`.

## Shell Interactivo

El CLI SAPI proporciona un shell interactivo al usar la opción -a si PHP se ha compilado con la opción --with-readline. Desde PHP 7.1.0, el shell interactivo también está disponible en Windows, si la extensión readline está activada.

Al usar el shell interactivo, tiene la posibilidad de escribir código PHP y que se ejecute directamente.

Ejemplo #1 Ejecución de código usando el shell interactivo

    $ php -a
    Interactive shell

    php > echo 5+8;
    13
    php > function addTwo($n)
    php > {
    php { return $n + 2;
    php { }
    php > var_dump(addtwo(2));
    int(4)
    php >

El shell interactivo también proporciona autocompletado de funciones, constantes, nombres de clases, variables, llamadas a métodos estáticos y constantes de clases utilizando la tecla de tabulación. Desde PHP 8.4.0, la ruta hacia el archivo de historial puede establecerse utilizando la variable de entorno PHP_HISTFILE.

Ejemplo #2 Autocompletado usando la tecla de tabulación

Presionar dos veces la tecla de tabulación cuando hay varias posibles completaciones mostrará una lista de estas completaciones:

    php > strp[TAB][TAB]
    strpbrk   strpos    strptime
    php > strp

Cuando solo hay una posible completación, presionar la tecla de tabulación una vez completará el resto en la misma línea:

    php > strpt[TAB]ime(

La completación también funcionará para los nombres que se han definido durante la sesión actual del shell interactivo:

    php > $fooThisIsAReallyLongVariableName = 42;
    php > $foo[TAB]ThisIsAReallyLongVariableName

El shell interactivo almacena su historial y puede acceder a él utilizando las teclas arriba y abajo. El historial se guarda en el archivo ~/.php_history.

El CLI SAPI proporciona 2 directivas del php.ini: `cli.pager` y `cli.prompt`. La directiva `cli.pager` permite la definición de un programa externo (como less) a utilizar como pager para la salida en lugar de mostrarla directamente en la pantalla. La directiva `cli.prompt` permite la modificación del prompt `php >`.

También es posible definir directivas del php.ini en un shell interactivo utilizando notaciones abreviadas.

Ejemplo #3 Definición de directivas del php.ini en un shell interactivo

La definición de la directiva `cli.prompt`:

    php > #cli.prompt=hello world :>
    hello world :>

Utilizando comillas invertidas, es posible ejecutar código PHP en el prompt:

    php > #cli.prompt=`echo date('H:i:s');` php >
    15:49:35 php > echo 'hi';
    hi
    15:49:43 php > sleep(2);
    15:49:45 php >

Definición del pager a less:

    php > #cli.pager=less
    php > phpinfo();
    (salida mostrada con less)
    php >

La directiva `cli.prompt` soporta algunas secuencias de escape:

Secuencias de escape de `cli.prompt`
Secuencia: | Descripción:
--- | ---
`\e` | utilizado para agregar colores al prompt. Ejemplo: `\e[032m\v \e[031m\b \e[34m\> \e[0m`
`\v` | La versión de PHP.
`\b` | Indica en qué bloque de PHP nos encontramos. Por ejemplo, `/*` permite indicar que estamos en un comentario multilínea. El ámbito externo se representa por `php`.
`\>` | Indica el carácter utilizado para el prompt. Por defecto, será `>`, pero puede cambiarse cuando el shell se encuentra en un bloque indeterminado o en una cadena de caracteres. Los caracteres posibles son: `' " { ( >`

> Nota:

> Los archivos incluidos a través de auto_prepend_file y auto_append_file se analizan en este modo, pero con algunas restricciones; es decir, las funciones deben haber sido definidas antes de la llamada.

## Modo interactivo

Si la extensión readline no está disponible, anterior a PHP 8.1.0, invocar el CLI SAPI con la opción -a proporciona el modo interactivo. En este modo, se supone que se da un script PHP completo a través de STDIN, y después de la interrupción con ``CTRL` +`D`` (POSIX) o ``CTRL` +`Z`` seguido de `ENTER` (Windows), este script será evaluado. Esto es básicamente idéntico a invocar el CLI SAPI sin la opción -a.

A partir de PHP 8.1.0, invocar el CLI SAPI con la opción -a falla si la extensión readline no está disponible.

## Servidor web interno

Advertencia

Este servidor web está destinado a ayudar en el desarrollo de aplicaciones. También puede ser útil para pruebas y para demostraciones de aplicaciones que se ejecutan en entornos controlados. Sin embargo, no está diseñado para ser un servidor web completo. Por lo tanto, no debe utilizarse en una red pública.

El CLI SAPI proporciona un servidor web interno.

El servidor web se ejecuta en un solo proceso single-threaded, las aplicaciones PHP se retrasarán/suspenderán si una solicitud está bloqueada.

Las solicitudes URI se sirven desde el directorio de trabajo actual donde se inició PHP, a menos que se utilice la opción -t para especificar explícitamente un documento raíz. Si una solicitud URI no especifica un archivo, entonces el archivo index.php o el archivo index.html del directorio actual será devuelto. Si ninguno de estos archivos existe, la búsqueda de un archivo index.php e index.html continuará en el directorio padre y así sucesivamente hasta que se encuentre uno de estos archivos o se alcance el directorio raíz. Si se encuentra un archivo index.php o index.html, se devolverá y $_SERVER['PATH_INFO'] se establecerá como la última parte de la URI. De lo contrario, se devolverá un código de respuesta 404.

Si se proporciona un archivo PHP en la línea de comandos cuando se inicia el servidor web, se tratará como un script "ruteador". El script se ejecutará al inicio de cada solicitud HTTP. Si este script devuelve `false`, entonces el recurso solicitado se devolverá tal cual. De lo contrario, la salida del script se devolverá al navegador.

Los tipos MIME estándar se devuelven para archivos con las extensiones: `.3gp`, `.apk`, `.avi`, `.bmp`, `.css`, `.csv`, `.doc`, `.docx`, `.flac`, `.gif`, `.gz`, `.gzip`, `.htm`, `.html`, `.ics`, `.jpe`, `.jpeg`, `.jpg`, `.js`, `.kml`, `.kmz`, `.m4a`, `.mov`, `.mp3`, `.mp4`, `.mpeg`, `.mpg`, `.odp`, `.ods`, `.odt`, `.oga`, `.ogg`, `.ogv`, `.pdf`, `.png`, `.pps`, `.pptx`, `.qt`, `.svg`, `.swf`, `.tar`, `.text`, `.tif`, `.txt`, `.wav`, `.webm`, `.wmv`, `.xls`, `.xlsx`, `.xml`, `.xsl`, `.xsd`, `.zip` .

A partir de PHP 7.4.0, el servidor web integrado puede configurarse para bifurcar varios trabajadores para probar código que requiere múltiples solicitudes concurrentes al servidor web integrado. Establezca la variable de entorno PHP_CLI_SERVER_WORKERS en el número de trabajadores deseados antes de iniciar el servidor.

> Nota: Esta funcionalidad no está soportada en Windows.

> Nota: Para obtener información sobre el uso de PHP desde la línea de comandos y las opciones disponibles, ejecute php --help o man php. No todas las opciones se aplican al ejecutar el servidor web.

Advertencia

Esta funcionalidad experimental no está destinada a ser utilizada en producción. En general, el Servidor Web integrado no está destinado a ser utilizado en producción.

Ejemplo #1 Inicio del servidor web

    $ cd ~/public_html
    $ php -S localhost:8000

El terminal mostrará:

    PHP 5.4.0 Development Server started at Thu Jul 21 10:43:28 2011
    Listening on localhost:8000
    Document root is /home/me/public_html
    Press Ctrl-C to quit

Después de las solicitudes URI a http://localhost:8000/ y http://localhost:8000/myscript.html, el terminal mostrará algo como:

    PHP 5.4.0 Development Server started at Thu Jul 21 10:43:28 2011
    Listening on localhost:8000
    Document root is /home/me/public_html
    Press Ctrl-C to quit.
    [Thu Jul 21 10:48:48 2011] ::1:39144 GET /favicon.ico - Request read
    [Thu Jul 21 10:48:50 2011] ::1:39146 GET / - Request read
    [Thu Jul 21 10:48:50 2011] ::1:39147 GET /favicon.ico - Request read
    [Thu Jul 21 10:48:52 2011] ::1:39148 GET /myscript.html - Request read
    [Thu Jul 21 10:48:52 2011] ::1:39149 GET /favicon.ico - Request read

Tenga en cuenta que antes de PHP 7.4.0, los recursos estáticos en enlace simbólico no son accesibles en Windows, a menos que el script ruteador lo maneje.

Ejemplo #2 Inicio con un directorio raíz específico

    $ cd ~/public_html
    $ php -S localhost:8000 -t foo/

El terminal mostrará:

    PHP 5.4.0 Development Server started at Thu Jul 21 10:50:26 2011
    Listening on localhost:8000
    Document root is /home/me/public_html/foo
    Press Ctrl-C to quit

Ejemplo #3 Uso de un script ruteador

En este ejemplo, solicitar imágenes las mostrará, pero las solicitudes de archivos HTML mostrarán "¡Bienvenido a PHP!".

    <?php
    // router.php
    if (preg_match('/\.(?:png|jpg|jpeg|gif)$/', $_SERVER["REQUEST_URI"])) {
        return false;    // devuelve la solicitud tal cual.
    } else {
        echo "<p>¡Bienvenido a PHP!</p>";
    }
    ?>

    $ php -S localhost:8000 router.php

Ejemplo #4 Verificación de la utilización de CLI del servidor web

Para reutilizar un script ruteador del marco durante el desarrollo con el CLI del servidor web y luego continuar utilizándolo con un servidor web de producción:

    <?php
    // router.php
    if (php_sapi_name() == 'cli-server') {
        /* Activar la ruta estática y devolver FALSE */
    }
    /* continuar con las operaciones de un index.php normal */
    ?>

    $ php -S localhost:8000 router.php

Ejemplo #5 Manejo de tipos de archivos no soportados

Si necesita servir un recurso estático para el cual el tipo MIME no es manejado por el CLI del servidor web, use esto:

    <?php
    // router.php
    $path = pathinfo($_SERVER["SCRIPT_FILENAME"]);
    if ($path["extension"] == "el") {
        header("Content-Type: text/x-script.elisp");
        readfile($_SERVER["SCRIPT_FILENAME"]);
    }
    else {
        return FALSE;
    }
    ?>

    $ php -S localhost:8000 router.php

Ejemplo #6 Acceso al CLI del servidor web desde una máquina remota

Puede hacer que el servidor web sea accesible en el puerto 8000 para todas las interfaces con:

    $ php -S 0.0.0.0:8000

Advertencia

El servidor web integrado no debe utilizarse en una red pública.

## Configuraciones INI

Opciones de configuración CLI SAPI
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
cli_server.color | "0" | `INI_ALL` |

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`cli_server.color` bool

  Activa el servidor web de desarrollo interno para utilizar la coloración ANSI del código en la salida del terminal.

# Recolección de basura (Garbage Collection)

## Tabla de contenidos

- Bases sobre el conteo de referencias
- Limpieza de Ciclos
- Consideraciones sobre el rendimiento

Esta sección explica los méritos del nuevo mecanismo de recolección de basura (también llamado GC, del término inglés Garbage Collection) disponible a partir de PHP 5.3.

## Bases sobre el conteo de referencias

Una variable PHP se almacena internamente en un contenedor llamado "zval". Un contenedor zval contiene, además del tipo de la variable y su valor, dos informaciones adicionales. La primera se llama "is_ref" y es un valor booléano que indica si una variable forma parte de una referencia o no. Gracias a esta información, el motor de PHP sabe diferenciar las variables normales de las referencias. Como PHP permite al programador utilizar referencias, mediante el operador &, un contenedor zval posee también un mecanismo de conteo de referencias para optimizar el uso de la memoria. Esta segunda información, llamada "refcount", contiene el número de variables (también llamadas símbolos) que apuntan a este contenedor zval. Todos los símbolos se almacenan en una tabla de símbolos, y hay una tabla por ámbito de visibilidad (scope). Hay un ámbito global para el script principal (el que se llama, por ejemplo, a través del navegador) y un ámbito por función o método.

Un contenedor zval se crea cuando se crea una nueva variable con un valor constante, como por ejemplo:

Ejemplo #1 Creación de un nuevo contenedor zval

    <?php
    $a = "new string";
    ?>

En este caso, el nuevo símbolo `a` se crea en el ámbito global, y se crea un nuevo contenedor con el tipo string y el valor `new string`. El bit "is_ref" se establece por omisión en `false` ya que ninguna referencia ha sido creada por el programador. El contador de referencias "refcount" se establece en `1` ya que solo hay un símbolo que utiliza este contenedor. Es de destacar que las referencias (es decir, "is_ref" es `true`) con "refcount" `1`, se tratan como si no fueran referencias (es decir, como si "is_ref" fuera `false`). Si ha instalado » Xdebug, puede mostrar esta información llamando a xdebug_debug_zval().

Ejemplo #2 Mostrar información zval

    <?php
    $a = "new string";
    xdebug_debug_zval('a');
    ?>

El ejemplo anterior mostrará:

    a: (refcount=1, is_ref=0)='new string'

Asignar esta variable a otro símbolo incrementará el refcount.

Ejemplo #3 Incrementar el refcount de una zval

    <?php
    $a = "new string";
    $b = $a;
    xdebug_debug_zval( 'a' );
    ?>

El ejemplo anterior mostrará:

    a: (refcount=2, is_ref=0)='new string'

El refcount vale `2` aquí, ya que el mismo contenedor está ligado tanto a a como a b. PHP es lo suficientemente inteligente como para no duplicar el contenedor cuando no es necesario. Los contenedores se destruyen cuando su "refcount" llega a cero. El "refcount" se decrementa en uno cuando cualquier símbolo ligado a un contenedor sale del ámbito (por ejemplo: cuando la función termina) o cuando un símbolo se desasigna (por ejemplo: por la llamada a unset()). El siguiente ejemplo lo demuestra:

Ejemplo #4 Decrementar el refcount de una zval

    <?php
    $a = "new string";
    $c = $b = $a;
    xdebug_debug_zval( 'a' );
    $b = 42;
    xdebug_debug_zval( 'a' );
    unset( $c );
    xdebug_debug_zval( 'a' );
    ?>

El ejemplo anterior mostrará:

    a: (refcount=3, is_ref=0)='new string'
    a: (refcount=2, is_ref=0)='new string'
    a: (refcount=1, is_ref=0)='new string'

Si ahora se llama a `unset($a);`, el contenedor zval, incluyendo el tipo y el valor, será eliminado de la memoria.

### Tipos compuestos

Las cosas se complican en el caso de tipos compuestos como array y object. A diferencia de los valores escalares, los array y object almacenan sus propiedades en una tabla de símbolos que les es propia. Esto significa que el siguiente ejemplo crea tres contenedores zval:

Ejemplo #5 Creación de una zval array

    <?php
    $a = array( 'meaning' => 'life', 'number' => 42 );
    xdebug_debug_zval( 'a' );
    ?>

Resultado del ejemplo anterior es similar a:

    a: (refcount=1, is_ref=0)=array (
       'meaning' => (refcount=1, is_ref=0)='life',
       'number' => (refcount=1, is_ref=0)=42
    )

O gráficamente

Los tres contenedores zval son: a, meaning, y number. Las mismas reglas se aplican para el incremento y la decrementación de los "refcounts". A continuación, se añade otro elemento al array, y se asigna su valor con el contenido de un elemento ya existente del array:

Ejemplo #6 Añadir un elemento ya existente al array

    <?php
    $a = array( 'meaning' => 'life', 'number' => 42 );
    $a['life'] = $a['meaning'];
    xdebug_debug_zval( 'a' );
    ?>

Resultado del ejemplo anterior es similar a:

    a: (refcount=1, is_ref=0)=array (
       'meaning' => (refcount=2, is_ref=0)='life',
       'number' => (refcount=1, is_ref=0)=42,
       'life' => (refcount=2, is_ref=0)='life'
    )

O gráficamente

La salida Xdebug que vemos indica que el antiguo y el nuevo elemento del array apuntan ahora ambos a un contenedor zval cuyo "refcount" vale `2`. Aunque la salida XDebug muestra dos contenedores zval con el valor 'life', son los mismos. La función xdebug_debug_zval() no muestra esto, pero se podría ver mostrando también el puntero de memoria.

Eliminar un elemento del array es asimilable a la eliminación de un símbolo desde un espacio. Al hacerlo, el "refcount" del contenedor al que apunta el elemento del array se decrementa. Una vez más, si llega a cero, el contenedor zval se elimina de la memoria. El siguiente ejemplo lo demuestra:

Ejemplo #7 Eliminación de un elemento de array

    <?php
    $a = array( 'meaning' => 'life', 'number' => 42 );
    $a['life'] = $a['meaning'];
    unset( $a['meaning'], $a['number'] );
    xdebug_debug_zval( 'a' );
    ?>

Resultado del ejemplo anterior es similar a:

    a: (refcount=1, is_ref=0)=array (
       'life' => (refcount=1, is_ref=0)='life'
    )

Ahora, las cosas se vuelven interesantes si añadimos el array como elemento de sí mismo. Hacemos esto en el siguiente ejemplo, utilizando un operador de referencia para evitar que PHP cree una copia:

Ejemplo #8 Añadir el array como referencia a sí mismo como elemento

    <?php
    $a = array( 'one' );
    $a[] =& $a;
    xdebug_debug_zval( 'a' );
    ?>

Resultado del ejemplo anterior es similar a:

    a: (refcount=2, is_ref=1)=array (
       0 => (refcount=1, is_ref=0)='one',
       1 => (refcount=2, is_ref=1)=...
    )

O gráficamente

Se puede ver que la variable array (a) así como el segundo elemento (1) apuntan ahora a un contenedor cuyo "refcount" vale `2`. Los "..." en la visualización indican una recursión, que, en este caso, significa que el "..." apunta al array mismo.

Como antes, eliminar una variable elimina su símbolo, y el refcount del contenedor al que apuntaba se decrementa. Por lo tanto, si eliminamos la variable $a después de ejecutar el código anterior, el contador de referencias del contenedor al que apuntan $a y el elemento "1" se decrementará en uno, pasando de "2" a "1". Esto se puede representar como:

Ejemplo #9 Eliminación de $a

    (refcount=1, is_ref=1)=array (
       0 => (refcount=1, is_ref=0)='one',
       1 => (refcount=1, is_ref=1)=...
    )

O gráficamente

### Problemas de limpieza

Aunque ya no haya ningún símbolo en el espacio de variables actual que apunte a esta estructura, no puede ser limpiada, ya que el elemento "1" del array sigue apuntando a este mismo array. Como ya no hay ningún símbolo externo que apunte a esta estructura, el usuario no puede limpiarla manualmente; por lo tanto, hay una fuga de memoria. Afortunadamente, PHP destruirá esta estructura al final de la solicitud, pero antes de esta etapa, la memoria no se libera. Esta situación ocurre a menudo si se implementa un algoritmo de análisis u otras ideas donde se tiene un hijo que apunta a su padre. Lo mismo puede ocurrir, por supuesto, con los objetos, y es incluso más probable, ya que siempre se utilizan implícitamente por "referencia".

Esto puede no ser molesto si ocurre solo una o dos veces, pero si hay miles, o incluso millones, de estas fugas de memoria, entonces obviamente esto puede convertirse en un problema importante. Esto es particularmente problemático para los scripts que duran mucho tiempo, como los demonios para los cuales la solicitud nunca termina, o incluso en grandes suites de pruebas unitarias. Este último caso se encontró al lanzar las pruebas unitarias del componente Template de la biblioteca eZ Components. En algunos casos, la suite de pruebas requería más de 2Go de memoria, que el servidor de prueba no tenía realmente disponible.

## Limpieza de Ciclos

Tradicionalmente, los mecanismos de conteo de referencias, como los utilizados anteriormente en PHP, no saben manejar las fugas de memoria debidas a referencias circulares; sin embargo, desde PHP 5.3.0, un algoritmo síncrono derivado del análisis » Concurrent Cycle Collection in Reference Counted Systems se utiliza para abordar este problema en particular.

Una explicación completa del funcionamiento del algoritmo iría un poco más allá del alcance de esta sección, pero aquí presentaremos los principios básicos. En primer lugar, estableceremos algunas reglas básicas. Si un refcount se incrementa, el contenedor siempre se utiliza, por lo tanto, no se limpia. Si el refcount se decrementa y llega a cero, el contenedor zval puede ser eliminado y la memoria liberada. En primer lugar, esto significa que los ciclos perturbadores solo pueden crearse cuando el refcount se decrementa a un valor diferente de cero. Luego, en un ciclo problemático, es posible detectar la basura verificando si es posible o no decrementar su refcount en uno, verificando luego qué zvals tienen un refcount a cero.

Para evitar tener que llamar a la rutina de limpieza en cada decrementación de refcount posible, el algoritmo coloca todas las raíces zval en un "búfer de raíces" (marcándolas en "violeta"). También se asegura de que cada raíz aparezca solo una vez en el búfer. El mecanismo de limpieza solo interviene cuando el búfer está lleno. Vea el paso A en la figura anterior.

En el paso B, el algoritmo lanza una búsqueda en todas las raíces posibles, para decrementar en una unidad los refcounts de todas las zvals que encuentra, teniendo mucho cuidado de no decrementar dos veces el refcount de la misma zval (marcándolas como "grises"). En el paso C, el algoritmo relanza una búsqueda en todas las raíces posibles y escanea el valor de refcount de cada zval. Si encuentra un refcount a cero, la zval se marca como "blanca" (azul en la figura). Si encuentra un valor superior a cero, cancela la decrementación del refcount realizando una búsqueda desde este nodo, y las marca como "negras" nuevamente. En el último paso, D, el algoritmo recorre todo el búfer de raíces y las elimina, escaneando cada zval; cualquier zval marcada como "blanca" en el paso anterior será entonces eliminada de la memoria.

Ahora que se sabe globalmente cómo funciona el algoritmo, se verá cómo se ha integrado en PHP. Por omisión, el recolector de basura de PHP está activado. Sin embargo, hay una opción de php.ini para cambiar esto: zend.enable_gc.

Cuando el recolector de basura está activado, el algoritmo de búsqueda de ciclos descrito anteriormente se ejecuta cada vez que el búfer está lleno. El búfer de raíces tiene un tamaño fijado a 10.000 raíces (este parámetro es modificable gracias a `GC_THRESHOLD_DEFAULT` en `Zend/zend_gc.c` en el código fuente de PHP, por lo tanto, se necesita una recompilación). Si el recolector de basura está desactivado, la búsqueda de ciclos también lo está. Sin embargo, las raíces posibles siempre se registrarán en el búfer, esto no depende de la activación del recolector de basura.

Si el búfer está lleno mientras el mecanismo de limpieza está desactivado, las raíces ya no se registrarán. Estas raíces nunca serán analizadas por el algoritmo, y si formaban parte de referencias circulares, nunca se limpiarán, y causarán fugas de memoria.

La razón por la que las raíces posibles se registran en el búfer incluso si el mecanismo está desactivado es que habría sido demasiado costoso verificar la posible activación del mecanismo en cada intento de agregar una raíz al búfer. El mecanismo de recolección de basura y análisis puede, por su parte, ser muy costoso en tiempo.

Además de poder cambiar el valor del parámetro de configuración zend.enable_gc, también se puede activar o desactivar el mecanismo de recolección de basura llamando a las funciones gc_enable() o gc_disable() respectivamente. Utilizar estas funciones tendrá el mismo efecto que modificar el parámetro de configuración. También se tiene la posibilidad de forzar la ejecución del recolector de basura en un momento dado en el script, incluso si el búfer aún no está completamente lleno. Para ello, utilice la función gc_collect_cycles(), que devolverá el número de ciclos recolectados.

Se puede tomar el control desactivando el recolector de basura o forzándolo a pasar en un momento dado porque algunas partes de la aplicación podrían depender fuertemente del tiempo de procesamiento, en cuyo caso se podría desear que el recolector de basura no se inicie. Por supuesto, al desactivar el recolector de basura para algunas partes de la aplicación, se corre el riesgo de crear fugas de memoria, ya que algunas raíces probables podrían no registrarse en el búfer de memoria de tamaño limitado. En consecuencia, generalmente se recomienda desencadenar manualmente el proceso gracias a gc_collect_cycles() justo antes de la llamada a gc_disable(), para liberar memoria. Esto dejará un búfer vacío, y habrá más espacio para raíces probables cuando el mecanismo esté desactivado.

## Consideraciones sobre el rendimiento

Ya se ha visto en las secciones anteriores que la recolección de raíces probables tenía un impacto muy ligero en el rendimiento, pero esto es en comparación con PHP 5.2 a PHP 5.3. Aunque el registro de raíces probables es más lento que no registrarlas en absoluto, como en PHP 5.2, otras mejoras aportadas por PHP 5.3 hacen que esta operación no se sienta a nivel de rendimiento.

Hay principalmente dos niveles para los cuales se afecta el rendimiento. El primero es la huella de memoria reducida, y el segundo es el retraso en la ejecución, cuando el mecanismo de limpieza realiza su operación de liberación de memoria. Se estudiarán estos dos ejes.

### Huella de memoria reducida

En primer lugar, la razón principal de la implementación del mecanismo de recolección de basura es la reducción de la memoria consumida, limpiando las referencias circulares cuando se cumplen las condiciones requeridas. Con PHP, esto ocurre tan pronto como el búfer de raíces está lleno, o cuando se llama a la función gc_collect_cycles(). En el gráfico a continuación, se muestra el uso de memoria del siguiente script, con PHP 5.2 y con PHP 5.3, excluyendo la memoria obligatoria que PHP consume por sí mismo al inicio.

Ejemplo #1 Ejemplo de uso de memoria

    <?php
    class Foo
    {
        public $var = '3.14159265359';
        public $self;
    }

    $baseMemory = memory_get_usage();

    for ( $i = 0; $i <= 100000; $i++ )
    {
        $a = new Foo;
        $a->self = $a;
        if ( $i % 500 === 0 )
        {
            echo sprintf( '%8d: ', $i ), memory_get_usage() - $baseMemory, "\n";
        }
    }
    ?>

En este ejemplo algo académico, se crea un objeto que tiene un atributo que se referencia a sí mismo. Cuando la variable $a en el script se reasigna a la siguiente iteración, aparecerá una fuga de memoria. En este caso, los dos contenedores zval se fugan (el zval del objeto y el del atributo), pero solo se encuentra una raíz probable: la variable que ha sido eliminada. Cuando el búfer de raíces está lleno después de 10.000 iteraciones (con un total de 10.000 raíces probables), el mecanismo de recolección de basura entra en juego y libera la memoria asociada a estas raíces probables. Esto se ve muy claramente en los gráficos de uso de memoria de PHP 5.3. Después de cada 10.000 iteraciones, el mecanismo se desencadena y libera la memoria asociada a las variables circularmente referenciadas. El mecanismo en cuestión no tiene mucho trabajo en este ejemplo, porque la estructura que se fugó es extremadamente simple. El diagrma muestra que el uso máximo de memoria de PHP 5.3 es de aproximadamente 9Mo, mientras que sigue aumentando con PHP 5.2.

### Ralentizaciones durante la ejecución

El segundo punto donde el mecanismo de recolección de basura (GC) afecta el rendimiento es cuando se ejecuta para liberar la memoria "desperdiciada". Para cuantificar este impacto, se modifica ligeramente el script anterior para tener un número de iteraciones más alto y eliminar la recolección del uso de memoria intermedia. El segundo script se reproduce a continuación:

Ejemplo #2 Impacto de GC en el rendimiento

    <?php
    class Foo
    {
        public $var = '3.14159265359';
        public $self;
    }

    for ( $i = 0; $i <= 1000000; $i++ )
    {
        $a = new Foo;
        $a->self = $a;
    }

    echo memory_get_peak_usage(), "\n";
    ?>

Se lanzará este script 2 veces, una vez con zend.enable_gc en on, y una vez en off:

Ejemplo #3 Ejecución del script anterior

    time php -dzend.enable_gc=0 -dmemory_limit=-1 -n example2.php
    # y
    time php -dzend.enable_gc=1 -dmemory_limit=-1 -n example2.php

En mi máquina, el primer comando parece durar siempre 10,7 segundos, mientras que el segundo comando tarda aproximadamente 11,4 segundos. Esto corresponde a un retraso de aproximadamente el 7%. Sin embargo, la cantidad total de memoria utilizada por el script se reduce en un 98%, pasando de 931Mo a 10Mo. Este benchmark no es muy científico ni representativo de aplicaciones reales, pero demuestra concretamente en qué medida el mecanismo de recolección de basura puede ser útil en términos de consumo de memoria. El punto positivo es que el retraso es siempre del 7%, en el caso particular de este script, mientras que la memoria preservada será cada vez más importante a medida que aparezcan referencias circulares durante la ejecución.

### Estadísticas internas del GC de PHP

Es posible obtener algunas informaciones adicionales concernientes al mecanismo de recolección de basura interno de PHP. Pero para ello, se debe recompilar PHP con el soporte de benchmarking y recolección de datos. Se debe establecer la variable de entorno `CFLAGS` con `-DGC_BENCH=1` antes de lanzar `./configure` con las opciones que interesan. El siguiente ejemplo lo demuestra:

Ejemplo #4 Recompilar PHP para activar el soporte de benchmark del GC

    export CFLAGS=-DGC_BENCH=1
    ./config.nice
    make clean
    make

Cuando se re-ejecuta el código del script anterior con el binario PHP recién reconstruido, se debería ver el siguiente resultado después de la ejecución:

Ejemplo #5 Estadísticas GC

    GC Statistics
    -------------
    Runs:               110
    Collected:          2072204
    Root buffer length: 0
    Root buffer peak:   10000

          Possible            Remove from  Marked
            Root    Buffered     buffer     grey
          --------  --------  -----------  ------
    ZVAL   7175487   1491291    1241690   3611871
    ZOBJ  28506264   1527980     677581   1025731

Las estadísticas más interesantes se muestran en el primer bloque. Se ve aquí que el mecanismo de recolección de basura se ha desencadenado 110 veces, y que en total son más de 2 millones de asignaciones de memoria las que se han liberado durante estos 110 pasos. Tan pronto como el mecanismo haya intervenido al menos una vez, el pico del búfer de raíces es siempre de 10000.

### Conclusión

En general, la recolección de basura de PHP solo causará un retraso cuando el algoritmo de recolección de ciclos se ejecute, lo que significa que en los scripts normales (más cortos), no debería haber ningún impacto en el rendimiento.

Sin embargo, cuando el mecanismo de recolección de ciclos se desencadene en scripts normales, la reducción de la huella de memoria permitirá la ejecución paralela de un número mayor de estos scripts, ya que se utilizará menos memoria en total.

Las ventajas se sienten más claramente en el caso de scripts demonio o que deben ejecutarse durante mucho tiempo. Así, para las aplicaciones » PHP-GTK que a menudo duran más que los scripts web, el nuevo mecanismo debería reducir significativamente las fugas de memoria a largo plazo.

# Rastreo dinámico de DTrace

## Tabla de contenidos

- Introducción a PHP y DTrace
- Usar PHP y DTrace
- Usar SystemTap con las sondas estáticas DTrace de PHP
- Usar bpftrace con las sondas estáticas DTrace de PHP

## Introducción a PHP y DTrace

DTrace es un framework de rastreo siempre disponible, a bajo costo, disponible en varias plataformas, incluyendo Solaris, macOS, Oracle Linux y BSD. DTrace puede rastrear el comportamiento del sistema operativo y la ejecución de programas de usuario. Puede mostrar los valores de los argumentos y ser utilizado para deducir estadísticas de rendimiento. Las sondas son controladas por scripts creados por el usuario y escritos en el lenguaje de script DTrace D. Esto permite un análisis eficiente de los puntos de datos.

Las sondas PHP que no son activamente monitoreadas por el script DTrace D del usuario no contienen código instrumentado, por lo que no hay degradación del rendimiento durante la ejecución normal de la aplicación. Las sondas que son monitoreadas tienen un costo de funcionamiento bastante bajo para generalmente permitir la supervisión de DTrace en sistemas de producción.

PHP incorpora sondas de "Rastreo Estático Definido por el Usuario" (USDT) que se disparan en el momento de la ejecución. Por ejemplo, cuando un script D monitorea la sonda `function-entry` de PHP, entonces, cada vez que se llama a una función del script PHP, esta sonda se dispara y el código de acción del script D asociado se ejecuta. Este código de acción podría, por ejemplo, imprimir los argumentos de la sonda como la ubicación del fichero fuente de la función PHP. La acción también puede agrupar datos como el número de veces que se llama a cada función.

Solo se describen aquí las sondas PHP USDT. Consulte la documentación externa general y específica del sistema operativo para ver cómo DTrace puede ser utilizado para trazar funciones arbitrarias, y cómo puede ser utilizado para trazar el comportamiento del sistema operativo. Tenga en cuenta que no todas las funcionalidades de DTrace están disponibles en todas las implementaciones de DTrace.

Las sondas DTrace estáticas en PHP pueden alternativamente ser utilizadas con la función SystemTap en ciertas distribuciones Linux.

## Usar PHP y DTrace

PHP puede ser configurado con las sondas estáticas DTrace en las plataformas que soportan el rastreo dinámico DTrace.

### Configurar PHP para las sondas estáticas de DTrace

Consulte la documentación específica de la plataforma externa para habilitar el soporte de DTrace del sistema operativo. Por ejemplo, en Oracle Linux inicie un núcleo UEK3 y haga:

    # modprobe fasttrap
    # chmod 666 /dev/dtrace/helper

En lugar de usar `chmod`, puede usar una regla de paquetado ACL para limitar el acceso al dispositivo a un usuario específico.

Construir PHP con el parámetro de configuración `--enable-dtrace`:

    # ./configure --enable-dtrace ...
    # make
    # make install

Esto hace que las sondas estáticas estén disponibles en el núcleo de PHP. Todas las extensiones PHP que proporcionen sus propias sondas deben ser construidas por separado como extensiones compartidas.

Para habilitar las sondas, definir la variable de entorno USE_ZEND_DTRACE=1 a los procesos PHP objetivo.

### Sondas estáticas DTrace en el núcleo de PHP

Las siguientes sondas estáticas están disponibles en PHP
Nombre de la sonda | Descripción de la sonda | Argumentos de la sonda
--- | --- | ---
`request-startup` | Se dispara cuando una petición comienza. | char *file, char *request_uri, char *request_method
`request-shutdown` | Se dispara cuando una petición se detiene. | char *file, char *request_uri, char *request_method
`compile-file-entry` | Se dispara cuando comienza la compilación de un script. | char *compile_file, char *compile_file_translated
`compile-file-return` | Se dispara cuando termina la compilación de un script. | char *compile_file, char *compile_file_translated
`execute-entry` | Se dispara cuando un array de opcodes debe ser ejecutado. Por ejemplo, se dispara en llamadas de función, inclusiones y reanudaciones de generador. | char *request_file, int lineno
`execute-return` | Se dispara después de la ejecución de un array de opcodes. | char *request_file, int lineno
`function-entry` | Se dispara cuando el motor de PHP entra en una función PHP o una llamada de método. | char *function_name, char *request_file, int lineno, char *classname, char *scope
`function-return` | Se dispara cuando el motor PHP regresa de una función PHP o una llamada de método. | char *function_name, char *request_file, int lineno, char *classname, char *scope
`exception-thrown` | Se dispara cuando se lanza una excepción. | char *classname
`exception-caught` | Se dispara cuando se captura una excepción. | char *classname
`error` | Se dispara cuando ocurre un error, independientemente del nivel de error_reporting. | char *errormsg, char *request_file, int lineno

Las extensiones PHP también pueden disponer de sondas estáticas adicionales.

### Lista de sondas estáticas DTrace de PHP

Para listar las sondas disponibles, inicie un proceso PHP y luego ejecute:

    # dtrace -l

El resultado será similar al siguiente:

       ID   PROVIDER            MODULE                          FUNCTION NAME
       [ . . . ]
        4   php15271               php               dtrace_compile_file compile-file-entry
        5   php15271               php               dtrace_compile_file compile-file-return
        6   php15271               php                        zend_error error
        7   php15271               php  ZEND_CATCH_SPEC_CONST_CV_HANDLER exception-caught
        8   php15271               php     zend_throw_exception_internal exception-thrown
        9   php15271               php                 dtrace_execute_ex execute-entry
       10   php15271               php           dtrace_execute_internal execute-entry
       11   php15271               php                 dtrace_execute_ex execute-return
       12   php15271               php           dtrace_execute_internal execute-return
       13   php15271               php                 dtrace_execute_ex function-entry
       14   php15271               php                 dtrace_execute_ex function-return
       15   php15271               php              php_request_shutdown request-shutdown
       16   php15271               php               php_request_startup request-startup

Los valores de la columna Provider son `php` y el identificador del proceso PHP en ejecución.

Si el servidor web Apache está en ejecución, el nombre del módulo podría ser, por ejemplo, libphp5.so, y habría varios bloques de listas, uno por cada proceso Apache en ejecución.

La columna Función hace referencia a la implementación interna en C de PHP, donde se encuentra cada proveedor.

Si no hay un proceso PHP en ejecución, no se mostrará ninguna sonda PHP.

### DTrace con un ejemplo PHP

Este ejemplo muestra los fundamentos del lenguaje de script DTrace D.

Ejemplo #1 all_probes.d para trazar todas las sondas estáticas PHP con DTrace

    #!/usr/sbin/dtrace -Zs

    #pragma D option quiet

    php*:::compile-file-entry
    {
        printf("PHP compile-file-entry\n");
        printf("  compile_file              %s\n", copyinstr(arg0));
        printf("  compile_file_translated   %s\n", copyinstr(arg1));
    }

    php*:::compile-file-return
    {
        printf("PHP compile-file-return\n");
        printf("  compile_file              %s\n", copyinstr(arg0));
        printf("  compile_file_translated   %s\n", copyinstr(arg1));
    }

    php*:::error
    {
        printf("PHP error\n");
        printf("  errormsg                  %s\n", copyinstr(arg0));
        printf("  request_file              %s\n", copyinstr(arg1));
        printf("  lineno                    %d\n", (int)arg2);
    }

    php*:::exception-caught
    {
        printf("PHP exception-caught\n");
        printf("  classname                 %s\n", copyinstr(arg0));
    }

    php*:::exception-thrown
    {
        printf("PHP exception-thrown\n");
        printf("  classname                 %s\n", copyinstr(arg0));
    }

    php*:::execute-entry
    {
        printf("PHP execute-entry\n");
        printf("  request_file              %s\n", copyinstr(arg0));
        printf("  lineno                    %d\n", (int)arg1);
    }

    php*:::execute-return
    {
        printf("PHP execute-return\n");
        printf("  request_file              %s\n", copyinstr(arg0));
        printf("  lineno                    %d\n", (int)arg1);
    }

    php*:::function-entry
    {
        printf("PHP function-entry\n");
        printf("  function_name             %s\n", copyinstr(arg0));
        printf("  request_file              %s\n", copyinstr(arg1));
        printf("  lineno                    %d\n", (int)arg2);
        printf("  classname                 %s\n", copyinstr(arg3));
        printf("  scope                     %s\n", copyinstr(arg4));
    }

    php*:::function-return
    {
        printf("PHP function-return\n");
        printf("  function_name             %s\n", copyinstr(arg0));
        printf("  request_file              %s\n", copyinstr(arg1));
        printf("  lineno                    %d\n", (int)arg2);
        printf("  classname                 %s\n", copyinstr(arg3));
        printf("  scope                     %s\n", copyinstr(arg4));
    }

    php*:::request-shutdown
    {
        printf("PHP request-shutdown\n");
        printf("  file                      %s\n", copyinstr(arg0));
        printf("  request_uri               %s\n", copyinstr(arg1));
        printf("  request_method            %s\n", copyinstr(arg2));
    }

    php*:::request-startup
    {
        printf("PHP request-startup\n");
        printf("  file                      %s\n", copyinstr(arg0));
        printf("  request_uri               %s\n", copyinstr(arg1));
        printf("  request_method            %s\n", copyinstr(arg2));
    }

Este script utiliza la opción `-Z` de dtrace, lo que le permite ejecutarse cuando no hay ningún proceso PHP en ejecución. Si se omitiera esta opción, el script terminaría inmediatamente porque sabe que ninguna de las sondas a monitorear existe.

El script traza todos los puntos de sondeo estáticos de PHP durante la duración de un script PHP en ejecución. Ejecute el script D:

    # ./all_probes.d

Ejecute un script o una aplicación PHP. El script D de monitoreo mostrará los argumentos de cada sonda a medida que se dispare.

Cuando el monitoreo haya terminado, el script D puede ser interrumpido con un ``CTRL`+`C``

En máquinas multi-CPU, el orden de las sondas puede no ser secuencial. Esto depende del CPU que ha procesado las sondas, y de cómo los hilos migran de un CPU a otro. La visualización de los timestamps de las sondas permite reducir la confusión, por ejemplo :

    php*:::function-entry
    {
          printf("%lld: PHP function-entry ", walltimestamp);
          [ . . .]
    }

### Ver también

- OCI8 y el rastreo dinámico DTrace

## Usar SystemTap con las sondas estáticas DTrace de PHP

En ciertas distribuciones Linux, la utilidad de rastreo SystemTap puede ser utilizada para trazar las sondas estáticas DTrace de PHP. Esto está disponible con PHP 5.4.20 y PHP 5.5.

### Instalar PHP con SystemTap

Instale el paquete de desarrollo SDT de SystemTap:

    # yum install systemtap-sdt-devel

Instalar PHP con las sondas DTrace habilitadas:

    # ./configure --enable-dtrace ...
    # make

### Lista de sondas estáticas con SystemTap

Las sondas estáticas en PHP pueden ser listadas utilizando stap:

    # stap -l 'process.provider("php").mark("*")' -c 'sapi/cli/php -i'

Esto produce:

    process("sapi/cli/php").provider("php").mark("compile__file__entry")
    process("sapi/cli/php").provider("php").mark("compile__file__return")
    process("sapi/cli/php").provider("php").mark("error")
    process("sapi/cli/php").provider("php").mark("exception__caught")
    process("sapi/cli/php").provider("php").mark("exception__thrown")
    process("sapi/cli/php").provider("php").mark("execute__entry")
    process("sapi/cli/php").provider("php").mark("execute__return")
    process("sapi/cli/php").provider("php").mark("function__entry")
    process("sapi/cli/php").provider("php").mark("function__return")
    process("sapi/cli/php").provider("php").mark("request__shutdown")
    process("sapi/cli/php").provider("php").mark("request__startup")

### SystemTap con un Ejemplo PHP

Ejemplo #1 all_probes.stp para trazar todas las sondas estáticas PHP con SystemTap

    probe process("sapi/cli/php").provider("php").mark("compile__file__entry") {
        printf("Probe compile__file__entry\n");
        printf("  compile_file %s\n", user_string($arg1));
        printf("  compile_file_translated %s\n", user_string($arg2));
    }
    probe process("sapi/cli/php").provider("php").mark("compile__file__return") {
        printf("Probe compile__file__return\n");
        printf("  compile_file %s\n", user_string($arg1));
        printf("  compile_file_translated %s\n", user_string($arg2));
    }
    probe process("sapi/cli/php").provider("php").mark("error") {
        printf("Probe error\n");
        printf("  errormsg %s\n", user_string($arg1));
        printf("  request_file %s\n", user_string($arg2));
        printf("  lineno %d\n", $arg3);
    }
    probe process("sapi/cli/php").provider("php").mark("exception__caught") {
        printf("Probe exception__caught\n");
        printf("  classname %s\n", user_string($arg1));
    }
    probe process("sapi/cli/php").provider("php").mark("exception__thrown") {
        printf("Probe exception__thrown\n");
        printf("  classname %s\n", user_string($arg1));
    }
    probe process("sapi/cli/php").provider("php").mark("execute__entry") {
        printf("Probe execute__entry\n");
        printf("  request_file %s\n", user_string($arg1));
        printf("  lineno %d\n", $arg2);
    }
    probe process("sapi/cli/php").provider("php").mark("execute__return") {
        printf("Probe execute__return\n");
        printf("  request_file %s\n", user_string($arg1));
        printf("  lineno %d\n", $arg2);
    }
    probe process("sapi/cli/php").provider("php").mark("function__entry") {
        printf("Probe function__entry\n");
        printf("  function_name %s\n", user_string($arg1));
        printf("  request_file %s\n", user_string($arg2));
        printf("  lineno %d\n", $arg3);
        printf("  classname %s\n", user_string($arg4));
        printf("  scope %s\n", user_string($arg5));
    }
    probe process("sapi/cli/php").provider("php").mark("function__return") {
        printf("Probe function__return: %s\n", user_string($arg1));
        printf(" function_name %s\n", user_string($arg1));
        printf("  request_file %s\n", user_string($arg2));
        printf("  lineno %d\n", $arg3);
        printf("  classname %s\n", user_string($arg4));
        printf("  scope %s\n", user_string($arg5));
    }
    probe process("sapi/cli/php").provider("php").mark("request__shutdown") {
        printf("Probe request__shutdown\n");
        printf("  file %s\n", user_string($arg1));
        printf("  request_uri %s\n", user_string($arg2));
        printf("  request_method %s\n", user_string($arg3));
    }
    probe process("sapi/cli/php").provider("php").mark("request__startup") {
        printf("Probe request__startup\n");
        printf("  file %s\n", user_string($arg1));
        printf("  request_uri %s\n", user_string($arg2));
        printf("  request_method %s\n", user_string($arg3));
    }

El script anterior trazará todos los puntos de sondeo estáticos de PHP durante toda la duración de la ejecución de un script PHP:

    # stap -c 'sapi/cli/php test.php' all_probes.stp

## Usar bpftrace con las sondas estáticas DTrace de PHP

En las distribuciones Linux con un núcleo que soporta eBPF, la utilidad bpftrace puede conectarse directamente a las sondas USDT de DTrace de PHP, sin necesidad de SystemTap.

### Instalar bpftrace

Instale bpftrace utilizando el gestor de paquetes de la distribución. Por ejemplo, en Oracle Linux, RHEL o Fedora:

    # dnf install bpftrace

O bien, en Debian o Ubuntu:

    # apt install bpftrace

Los ejemplos siguientes asumen que el binario PHP objetivo está instalado en /usr/bin/php.

Las mismas sondas USDT también son expuestas por otros SAPIs construidos a partir del mismo árbol de fuentes, por lo que el objetivo de la sonda puede ser en su lugar el módulo de Apache (libphp.so) o el binario del FastCGI Process Manager (php-fpm); sustituya la ruta apropiada o conéctese por PID con `-p` según sea necesario.

Asegúrese de que el binario objetivo esté construido con DTrace y de que la variable de entorno esté configurada correctamente. Consulte Configurar PHP para las sondas estáticas de DTrace para más detalles.

Las sondas estáticas en PHP pueden ser listadas utilizando bpftrace:

    # bpftrace -l 'usdt:/usr/bin/php:php:*'

Esto produce:

    usdt:/usr/bin/php:php:compile__file__entry
    usdt:/usr/bin/php:php:compile__file__return
    usdt:/usr/bin/php:php:error
    usdt:/usr/bin/php:php:exception__caught
    usdt:/usr/bin/php:php:exception__thrown
    usdt:/usr/bin/php:php:execute__entry
    usdt:/usr/bin/php:php:execute__return
    usdt:/usr/bin/php:php:function__entry
    usdt:/usr/bin/php:php:function__return
    usdt:/usr/bin/php:php:request__shutdown
    usdt:/usr/bin/php:php:request__startup

Ejemplo #1 all_probes.bt para trazar todas las sondas estáticas PHP con bpftrace

    #!/usr/bin/env bpftrace

    usdt:/usr/bin/php:php:compile__file__entry
    {
        printf("Probe compile__file__entry\n");
        printf("  compile_file %s\n", str(arg0));
        printf("  compile_file_translated %s\n", str(arg1));
    }
    usdt:/usr/bin/php:php:compile__file__return
    {
        printf("Probe compile__file__return\n");
        printf("  compile_file %s\n", str(arg0));
        printf("  compile_file_translated %s\n", str(arg1));
    }
    usdt:/usr/bin/php:php:error
    {
        printf("Probe error\n");
        printf("  errormsg %s\n", str(arg0));
        printf("  request_file %s\n", str(arg1));
        printf("  lineno %d\n", (int32)arg2);
    }
    usdt:/usr/bin/php:php:exception__caught
    {
        printf("Probe exception__caught\n");
        printf("  classname %s\n", str(arg0));
    }
    usdt:/usr/bin/php:php:exception__thrown
    {
        printf("Probe exception__thrown\n");
        printf("  classname %s\n", str(arg0));
    }
    usdt:/usr/bin/php:php:execute__entry
    {
        printf("Probe execute__entry\n");
        printf("  request_file %s\n", str(arg0));
        printf("  lineno %d\n", (int32)arg1);
    }
    usdt:/usr/bin/php:php:execute__return
    {
        printf("Probe execute__return\n");
        printf("  request_file %s\n", str(arg0));
        printf("  lineno %d\n", (int32)arg1);
    }
    usdt:/usr/bin/php:php:function__entry
    {
        printf("Probe function__entry\n");
        printf("  function_name %s\n", str(arg0));
        printf("  request_file %s\n", str(arg1));
        printf("  lineno %d\n", (int32)arg2);
        printf("  classname %s\n", str(arg3));
        printf("  scope %s\n", str(arg4));
    }
    usdt:/usr/bin/php:php:function__return
    {
        printf("Probe function__return\n");
        printf("  function_name %s\n", str(arg0));
        printf("  request_file %s\n", str(arg1));
        printf("  lineno %d\n", (int32)arg2);
        printf("  classname %s\n", str(arg3));
        printf("  scope %s\n", str(arg4));
    }
    usdt:/usr/bin/php:php:request__shutdown
    {
        printf("Probe request__shutdown\n");
        printf("  file %s\n", str(arg0));
        printf("  request_uri %s\n", str(arg1));
        printf("  request_method %s\n", str(arg2));
    }
    usdt:/usr/bin/php:php:request__startup
    {
        printf("Probe request__startup\n");
        printf("  file %s\n", str(arg0));
        printf("  request_uri %s\n", str(arg1));
        printf("  request_method %s\n", str(arg2));
    }

El script anterior trazará todos los puntos de sondeo estáticos del núcleo de PHP durante toda la duración de la ejecución de un script PHP. bpftrace requiere privilegios de root:

    # USE_ZEND_DTRACE=1 bpftrace -c '/usr/bin/php test.php' all_probes.bt

Para trazar un proceso PHP que ya está en ejecución (por ejemplo, un worker de php-fpm o un proceso Apache que carga libphp.so), conéctese por PID:

    # bpftrace -p $PID all_probes.bt

La ruta del objetivo `usdt:` en el script debe coincidir con el binario del proceso en ejecución; ajuste `usdt:/usr/bin/php` al binario de php-fpm o a libphp.so según corresponda.

- Identificación HTTP con PHP
- Cookies
- Sesiones
- Gestión de cargas de ficheros
  - Cargas de ficheros por método POST
  - Explicación sobre los mensajes de errores de carga de ficheros
  - Errores clásicos
  - Cargar múltiples ficheros simultáneamente
  - Carga por método PUT
  - Ver también
- Uso de ficheros a distancia
- Gestión de las conexiones
- Conexiones persistentes a bases de datos
- Utilización de líneas de comando — Utilización de la línea de comandos
  - Diferencia con otros SAPIs
  - Opciones — Opciones de línea de comandos
  - Utilización — Ejecución de archivos PHP
  - Flujos I/O — Flujos de entrada/salida
  - Shell Interactivo
  - Servidor web interno
  - Configuraciones INI
- Recolección de basura (Garbage Collection)
  - Bases sobre el conteo de referencias
  - Limpieza de Ciclos
  - Consideraciones sobre el rendimiento
- Rastreo dinámico de DTrace
  - Introducción a PHP y DTrace
  - Usar PHP y DTrace
  - Usar SystemTap con las sondas estáticas DTrace de PHP
  - Usar bpftrace con las sondas estáticas DTrace de PHP

# Referencia de funciones

Sugerencia

Ver también Categorización de Extensiones.

# Afecta el comportamiento de PHP

# Caché de usuario APC

# Introducción

APCu es un array asociativo almacenado en memoria para PHP. Las claves son de tipo string y los valores son variables PHP de cualquier tipo. APCu solo gestiona la caché de variables del espacio de usuario.

La caché APCu es por proceso bajo Windows, por lo que al utilizar un SAPI basado en procesos (en lugar de en hilos), no será compartida entre diferentes procesos.

APCu es APC sin la caché de código operativo.

La primera versión es 4.0.0, fue un ramificado del código de la cabeza de la rama principal de APC de la época. El soporte para PHP 7 está disponible a partir de APCu 5.0.0. El soporte para PHP 8 está disponible a partir de APCu 5.1.19.

# Instalación/Configuración

## Tabla de contenidos

- Instalación
- Configuración en tiempo de ejecución

## Instalación

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/apcu.

Sugerencia

PHP 7 cuenta con un módulo separado (» apcu-bc) para garantizar la retrocompatibilidad con APC.

En modo retrocompatibilidad, APCu registra las funciones APC aplicables con prototipos retrocompatibles.

Cuando una función APC acepta el argumento `cache_type`, este último es ignorado por la versión retrocompatible de la función y omitido del prototipo de la versión APCu.

Advertencia

A partir de PHP 8.0.0, apcu-bc ya no es aceptado.

> Nota: Con Windows, APCu requiere un directorio temporal en el que el servidor web esté autorizado a escribir. Se verifican sucesivamente las variables de entorno TMP, TEMP y USERPROFILE en este orden y se termina intentando el directorio WINDOWS si ninguna de estas variables ha sido definida.

> Nota: Para obtener más detalles técnicos sobre la implementación, consúltese el » archivo TECHNOTES proporcionado por los desarrolladores .

Las fuentes de APCu están disponibles » aquí.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Aunque los ajustes predeterminados de APCu funcionan correctamente en muchas instalaciones, es útil considerar ajustar estos parámetros de configuración.

Una cuestión importante para la configuración de APCu es cuál es el tamaño adecuado que debe asignarse en la memoria a APCu. La directiva ini que controla este parámetro es `apc.shm_size`. El párrafo a continuación es importante para responder a esta pregunta.

Una vez iniciado el servidor, el script `apc.php`, disponible con la extensión, puede ser copiado en el document root y ejecutado por el navegador. Este script proporciona un análisis detallado del funcionamiento interno de APCu. Si la biblioteca GD está activada en PHP, entonces el script puede mostrar gráficos pertinentes.

Si APCu está funcionando, el número de `Cache full count` (a la izquierda) mostrará el número de veces que el caché ha alcanzado su capacidad máxima y ha tenido que evacuar entradas para liberar memoria. Durante la evacuación, si `apc.ttl` ha sido especificado, APCu intentará primero eliminar las entradas expiradas, es decir, las entradas cuyo TTL ha expirado o las entradas que no tienen TTL definido y que no han sido consultadas en los últimos `apc.ttl` segundos. Si `apc.ttl` no ha sido definido o si la eliminación de las entradas expiradas no ha liberado suficiente espacio, APCu borrará la totalidad del caché.

El número de evacuaciones debe ser mínimo en un caché bien configurado. Si el caché está constantemente lleno y por lo tanto liberado a la fuerza, el removimiento resultante tendrá efectos perjudiciales en el rendimiento del script. La manera más sencilla de reducir este número es asignar más memoria a APCu.

Cuando APCu es compilado con mmap (Memory Mapping), solo utilizará un segmento de memoria, a diferencia del caso en que APCu es construido con SHM (SysV Shared Memory) que utiliza varios segmentos de memoria. MMAP no tiene un límite máximo como SHM en `/proc/sys/kernel/shmmax`. En general, el uso de MMAP es recomendado ya que reclama la memoria más rápidamente cuando el servidor web es reiniciado y reduce el impacto en la asignación de memoria al inicio.

Opciones de configuración de APCu
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
apc.enabled | "1" | `INI_SYSTEM` |
apc.shm_segments | "1" | `INI_SYSTEM` |
apc.shm_size | "32M" | `INI_SYSTEM` |
apc.entries_hint | 512 * apc.shm_size | `INI_SYSTEM` | Anteriormente a APCu 5.1.25, el valor predeterminado era 4096
apc.ttl | "0" | `INI_SYSTEM` |
apc.gc_ttl | "3600" | `INI_SYSTEM` |
apc.mmap_file_mask | NULL | `INI_SYSTEM` |
apc.slam_defense | "0" | `INI_SYSTEM` |
apc.enable_cli | "0" | `INI_SYSTEM` |
apc.use_request_time | "0" | `INI_ALL` | Anteriormente a APCu 5.1.19, el valor predeterminado era `1`.
apc.serializer | "php" | `INI_SYSTEM` | Anteriormente a APCu 5.1.15, el valor predeterminado era `"default"`.
apc.coredump_unmap | "0" | `INI_SYSTEM` |
apc.preload_path | NULL | `INI_SYSTEM` |

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`apc.enabled` bool
  `apc.enabled` puede ser puesto a 0 para desactivar APC. Esto puede ser útil cuando APC es compilado estáticamente en PHP ya que no hay otra manera de desactivarlo (cuando APC es compilado como DSO, la línea `extension` en el fichero `php.ini` puede simplemente ser comentada).
`apc.shm_segments` int
  El número de segmentos de memoria compartida a asignar al caché de compilación Si APC carece de memoria compartida pero que `apc.shm_size` está puesto al valor máximo permitido por el sistema, entonces aumentar este valor puede evitar que APC agote su memoria.
`apc.shm_size` string
  El tamaño de cada segmento de memoria compartida dado en notación abreviada como se indica en esta FAQ. Por defecto, algunos sistemas (incluyendo la mayoría de las variantes de BSD) tienen un límite muy bajo para el tamaño de un segmento de memoria compartida.
`apc.entries_hint` int
  Un "indicio" sobre el número de variables distintas que pueden ser almacenadas. Poner a cero o en caso de duda omitir.
`apc.ttl` int
  Considerar que las entradas de caché sin TTL explícito son expiradas si no han sido consultadas desde hace tantos segundos. En efecto, esto permite que estas entradas sean oportunamente eliminadas durante una inserción en el caché, o antes de una eliminación completa. Tenga en cuenta que debido a que la eliminación es oportunista, las entradas pueden seguir siendo legibles incluso si son más antiguas que `apc.ttl` segundos. Este parámetro no tiene ningún efecto sobre las entradas de caché para las cuales un TTL explícito está especificado.
`apc.gc_ttl` int
  El número de segundos durante los cuales una entrada de caché puede permanecer en la lista de recolección de basura después de haber sido retirada o invalidada. Las entradas son elegibles para eliminación si su número de referencias es cero, o si exceden este límite de tiempo. Si se establece en `0`, la limpieza basada en el tiempo está desactivada, y las entradas solo se eliminan cuando su número de referencias cae a cero.
`apc.mmap_file_mask` string
  Si APCu ha sido compilado con la opción MMAP usando `--enable-mmap`, este parámetro recibe la máscara de fichero de tipo mktemp-style a pasar al módulo mmap para determinar si la región de la memoria usando mmap será guardada a través de un fichero o por la de la memoria compartida. En el caso de que el guardado se haga a través de un fichero, la máscara será de la forma `/tmp/apc.XXXXXX` (con exactamente 6 `X`). Para usar shm_open/mmap de la norma POSIX, la máscara debe contener `.shm`, como en el siguiente ejemplo: `/apc.shm.XXXXXX`. Este parámetro puede ser definido por `/dev/zero` para usar la interfaz `/dev/zero` del núcleo con una memoria usando mmap anónimamente. Dejar este parámetro indefinido forzará un mmap anónimo.
`apc.slam_defense` bool
  Al inicio o durante la modificación de un fichero en un servidor muy ocupado, varios procesos pueden entrar en competencia para poner en caché el mismo fichero al mismo tiempo. Configurar `apc.slam_defense` en `1` puede ayudar a evitar que varios procesos pongan en caché el mismo fichero simultáneamente introduciendo un mecanismo de probabilidad. Si la misma clave es intentada ser puesta en caché en un corto lapso de tiempo por diferentes procesos, salta la puesta en caché para el proceso actual para mitigar los posibles problemas de puesta en caché.
`apc.enable_cli` int
  Principalmente usado para pruebas y depuración. Definir este parámetro permite activar APC en la versión CLI de PHP. Normalmente, no es ideal crear, alimentar y destruir el caché APC en cada solicitud CLI. Sin embargo, en muchos escenarios de prueba es útil poder activar fácilmente APC en la versión CLI de PHP.
`apc.serializer` string
  Este parámetro permite a APC usar un serializador de terceros
`apc.coredump_unmap` bool
  Activa la gestión por APC de señales, tales como SIGSEGV, que provocan la escritura de ficheros core dump cuando son recibidas. Cuando estas señales son recibidas, APC intentará desasignar el segmento de memoria compartida reservado a mmap con el objetivo de excluirlo del fichero core dump. Esta opción puede mejorar la estabilidad del sistema cuando se reciben señales fatales y APC está configurado con un largo segmento de memoria compartida.
  Advertencia

  Esta opción es potencialmente peligrosa. Desasignar un segmento de memoria compartida usado por mmap en el gestor de señales fatales puede causar un comportamiento impredecible si ocurre un error fatal.

  > Nota: Aunque algunos núcleos pueden proporcionar la posibilidad de ignorar muchos tipos de memoria compartida cuando generan un fichero core dump, estas implementaciones también pueden ignorar importantes segmentos de memoria compartida como el tablero de Apache.

`apc.preload_path` string
  Opcional, define una ruta hacia el directorio donde APC cargará los datos del caché al inicio.
`apc.use_request_time` bool
  Usa el tiempo de inicio de la solicitud de la interfaz SAPI para la duración de vida (TTL).

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`APC_ITER_ALL` (int)
`APC_ITER_ATIME` (int)
`APC_ITER_CTIME` (int)
`APC_ITER_DEVICE` (int)
`APC_ITER_DTIME` (int)
`APC_ITER_FILENAME` (int)
`APC_ITER_INODE` (int)
`APC_ITER_KEY` (int)
`APC_ITER_MD5` (int)
`APC_ITER_MEM_SIZE` (int)
`APC_ITER_MTIME` (int)
`APC_ITER_NONE` (int)
`APC_ITER_NUM_HITS` (int)
`APC_ITER_REFCOUNT` (int)
`APC_ITER_TTL` (int)
`APC_ITER_TYPE` (int)
`APC_ITER_VALUE` (int)
`APC_LIST_ACTIVE` (int)
`APC_LIST_DELETED` (int)

# Funciones APCu

# apcu_add

(PECL apcu >= 4.0.0)

apcu_add — Almacena en caché una nueva variable en el almacén de datos

### Descripción

function apcu_add(string `$key`, mixed `$var`, int `$ttl` = 0): bool
function apcu_add(array `$values`, mixed `$unused` = NULL, int `$ttl` = 0): array

Almacena en caché una variable en el almacén de datos, solo si no ha sido ya almacenada.

> Nota: A diferencia de muchos otros mecanismos en PHP, las variables almacenadas utilizando apcu_add() persistirán entre las peticiones (hasta que sus valores sean retirados del caché).

### Parámetros

`key`
  Almacena la variable utilizando este nombre de clave. Cada clave es única en el caché, intentar utilizar apcu_add() para almacenar un dato con una clave `key` ya existente no sobrescribirá el dato sino que devolverá el valor `false`. (Esta es la única diferencia entre las funciones apcu_add() y apcu_store().)
`var`
  La variable a almacenar.
`ttl`
  Duración de vida; almacena la variable `var` en el caché durante `ttl` segundos. Después de la expiración de `ttl`, la variable almacenada será retirada del caché (en la próxima petición). Si no se pasa ningún valor a `ttl` (o si el valor de `ttl` es `0`), la variable persistirá hasta que sea retirada manualmente del caché, o, de lo contrario, fallará al salir del caché (durante un borrado, reinicio, etc.).
`values`
  Los nombres son proporcionados por las claves del array values, las variables por los valores.

### Valores devueltos

Devuelve TRUE si una variable ha sido efectivamente añadida al caché, FALSE en caso contrario. La segunda sintaxis devuelve un array con las claves erróneas.

### Ejemplos

Ejemplo #1 Un ejemplo con apcu_add()

    <?php
    $bar = 'BAR';
    apcu_add('foo', $bar);
    var_dump(apcu_fetch('foo'));
    echo "\n";
    $bar = 'NEVER GETS SET';
    apcu_add('foo', $bar);
    var_dump(apcu_fetch('foo'));
    echo "\n";
    ?>

El ejemplo anterior mostrará:

    string(3) "BAR"
    string(3) "BAR"

### Ver también

- apcu_store() - Almacena una variable en la caché de datos
- apcu_fetch() - Recupera una variable almacenada en la caché
- apcu_delete() - Elimina una variable almacenada en caché

# apcu_cache_info

(PECL apcu >= 4.0.0)

apcu_cache_info — Recupera la información almacenada en la memoria APCu

### Descripción

function apcu_cache_info(bool `$limited` = `false`): array|false

Recupera la información almacenada y los metadatos del almacén de datos de la APCu.

### Parámetros

`limited`
  Si el parámetro `limited` es `true`, el valor devuelto excluirá la lista individual de entradas de la memoria caché. Esto es útil cuando se intentan optimizar las llamadas para la recopilación de estadísticas.

### Valores devueltos

Array de datos en caché (y metadatos) o `false` si ocurre un error

> Nota: apcu_cache_info() hará una advertencia si no puede recuperar los datos de la caché del APCu. Esto suele ocurrir cuando el APCu no está activado.

### Historial de cambios

Versión | Descripción
--- | ---
PECL apcu 3.0.11 | El parámetro `limited` fué introducido.
PECL apcu 3.0.16 | La opción "`filehits`" para el parámetro `cache_type` fué introducido.

### Ejemplos

Ejemplo #1 Un ejemplo de apcu_cache_info()

    <?php
    print_r(apcu_cache_info());
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [num_slots] => 2000
        [ttl] => 0
        [num_hits] => 9
        [num_misses] => 3
        [start_time] => 1123958803
        [cache_list] => Array
            (
                [0] => Array
                    (
                        [filename] => /path/to/apcu_test.php
                        [device] => 29954
                        [inode] => 1130511
                        [type] => file
                        [num_hits] => 1
                        [mtime] => 1123960686
                        [creation_time] => 1123960696
                        [deletion_time] => 0
                        [access_time] => 1123962864
                        [ref_count] => 1
                        [mem_size] => 677
                    )
                [1] => Array (...iterates for each cached file)
    )

### Ver también

- APCu configuration directives
- APCUIterator::getTotalSize() - Obtiene el tamaño total del caché
- APCUIterator::getTotalHits() - Obtener resultados totales de la memoria caché
- APCUIterator::getTotalCount() - Obtiene el conteo total

# apcu_cas

(PECL apcu >= 4.0.0)

apcu_cas — Actualiza un valor antiguo con un nuevo valor

### Descripción

function apcu_cas(string `$key`, int `$old`, int `$new`): bool

apcu_cas() actualiza un valor entero ya existente si el parámetro `old` coincide el valor almacenado actualmente con el valor del parámetro `new`.

### Parámetros

`key`
  La clave del valor que se está actualizando.
`old`
  El valor antiguo (el valor actualmente almacenado).
`new`
  El nuevo valor al que actualizar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de apcu_cas()

    <?php
    apcu_store('foobar', 2);
    echo '$foobar = 2', PHP_EOL;
    echo '$foobar == 1 ? 2 : 1 = ', (apcu_cas('foobar', 1, 2) ? 'ok' : 'fail'), PHP_EOL;
    echo '$foobar == 2 ? 1 : 2 = ', (apcu_cas('foobar', 2, 1) ? 'ok' : 'fail'), PHP_EOL;

    echo '$foobar = ', apcu_fetch('foobar'), PHP_EOL;

    echo '$f__bar == 1 ? 2 : 1 = ', (apcu_cas('f__bar', 1, 2) ? 'ok' : 'fail'), PHP_EOL;

    apcu_store('perfection', 'xyz');
    echo '$perfection == 2 ? 1 : 2 = ', (apcu_cas('perfection', 2, 1) ? 'ok' : 'epic fail'), PHP_EOL;

    echo '$foobar = ', apcu_fetch('foobar'), PHP_EOL;
    ?>

Resultado del ejemplo anterior es similar a:

    $foobar = 2
    $foobar == 1 ? 2 : 1 = fail
    $foobar == 2 ? 1 : 2 = ok
    $foobar = 1
    $f__bar == 1 ? 2 : 1 = fail
    $perfection == 2 ? 1 : 2 = epic fail
    $foobar = 1

### Ver también

- apcu_dec() - Disminuir un número almacenado
- apcu_store() - Almacena una variable en la caché de datos

# apcu_clear_cache

(PECL apcu >= 4.0.0)

apcu_clear_cache — Limpia el caché del APCu

### Descripción

function apcu_clear_cache(): bool

Limpia el caché.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve siempre `true`

### Ver también

- apcu_cache_info() - Recupera la información almacenada en la memoria APCu

# apcu_dec

(PECL apcu >= 4.0.0)

apcu_dec — Disminuir un número almacenado

### Descripción

function apcu_dec(
string `$key`,
int `$step` = 1,
bool `&$success` = ?,
int `$ttl` = 0
): int|false

Disminuye un valor entero almacenado.

### Parámetros

`key`
  La clave de el valor a ser disminuido.
`step`
  El paso, o valor a disminuir.
`success`
  Opcionalmente pasa el valor booleano en caso de éxito o en caso de error a esta variable referenciada.
`ttl`
  TTL para usar si la operación inserta un nuevo valor (en lugar de disminuir uno existente).

### Valores devueltos

Devuelve el valor actual del valor de las claves (`key`) en caso de éxito, o `false` si ocurre un error

### Ejemplos

Ejemplo #1 Ejemplo de apcu_dec()

    <?php
    echo "Hagamos algo con éxito", PHP_EOL;

    apcu_store('anumber', 42);

    echo apcu_fetch('anumber'), PHP_EOL;

    echo apcu_dec('anumber'), PHP_EOL;
    echo apcu_dec('anumber', 10), PHP_EOL;
    echo apcu_dec('anumber', 10, $success), PHP_EOL;

    var_dump($success);

    echo "Ahora, hagamos que falle", PHP_EOL, PHP_EOL;

    apcu_store('astring', 'foo');

    $ret = apcu_dec('astring', 1, $fail);

    var_dump($ret);
    var_dump($fail);
    ?>

Resultado del ejemplo anterior es similar a:

    Hagamos algo con éxito
    42
    41
    31
    21
    bool(true)
    Ahora, hagamos que falle

    bool(false)
    bool(false)

### Ver también

- apcu_inc() - Incrementa un número almacenado

# apcu_delete

(PECL apcu >= 4.0.0)

apcu_delete — Elimina una variable almacenada en caché

### Descripción

function apcu_delete(mixed `$key`): mixed

Elimina una variable almacenada en caché.

### Parámetros

`key`
  Una clave (`key`) empleada para almacenar el valor como un string para una única clave, o como un array de strings para varias claves, o como un object APCUIterator.

### Valores devueltos

Si `key` es una array, se devuelve una array indexada de las claves. De lo contrario, se devuelve `true` en caso de éxito, o `false` en caso de fallo.

### Ejemplos

Ejemplo #1 Un ejemplo deapcu_delete()

    <?php
    $bar = 'BAR';
    apcu_store('foo', $bar);
    apcu_delete('foo');
    // obviamente, esto no es útil de esta forma

    // Alternativamente, borrar varias claves.
    apcu_delete(['foo', 'bar', 'baz']);

    // O utilizar un Iterator con una expresión regular.
    apcu_delete(new APCUIterator('#^myprefix_#'));
    ?>

### Ver también

- apcu_store() - Almacena una variable en la caché de datos
- apcu_fetch() - Recupera una variable almacenada en la caché
- apcu_clear_cache() - Limpia el caché del APCu
- APCUIterator

# apcu_enabled

(PECL apcu >= 4.0.3)

apcu_enabled — Si el APCu es utilizable en el entorno actual

### Descripción

function apcu_enabled(): bool

Devuelve si el APCu es utilizable en el entorno actual.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` uando el APCu es utilizable en el entorno actual, `false` en caso contrario.

# apcu_entry

(PECL apcu >= 5.1.0)

apcu_entry — Recupera o genera de forma atómica una entrada de caché

### Descripción

function apcu_entry(string `$key`, callable `$callback`, int `$ttl` = 0): mixed

Intenta de forma atómica encontrar `key` en la caché; si no se encuentra, se llama a `callback`, pasando `key` como único argumento. El valor de retorno de la llamada se almacena en caché con el `ttl` especificado opcionalmente y se devuelve.

> Nota: Cuando el control entra en apcu_entry(), se adquiere de forma exclusiva el bloqueo de la caché, que se libera cuando el control sale de apcu_entry(). En efecto, esto convierte el cuerpo de `callback` en una sección crítica, impidiendo que dos procesos ejecuten las mismas rutas de código concurrentemente. Además, prohíbe la ejecución concurrente de cualquier otra función de APCu, ya que adquirirán el mismo bloqueo.

Advertencia

La única función de APCu que puede llamarse de forma segura desde `callback` es apcu_entry().

### Parámetros

`key`
  Identificador de la entrada de caché
`callback`
  Una retrollamada que acepta `key` como único argumento y devuelve el valor a almacenar en caché.
`ttl`
  Tiempo de vida; almacena el valor de retorno del `callback` en la caché durante `ttl` segundos. Después de que `ttl` haya transcurrido, la entrada almacenada será eliminada de la caché (en la siguiente petición). Si no se proporciona `ttl` (o si el `ttl` es `0`), el valor persistirá hasta que se elimine manualmente de la caché, o deje de existir en la caché (limpieza, reinicio, etc.).

### Valores devueltos

Devuelve el valor almacenado en caché

### Ejemplos

Ejemplo #1 Un ejemplo de apcu_entry()

    <?php
    $config = apcu_entry("config", function($key) {
     return [
       "fruit" => apcu_entry("config.fruit", function($key){
         return [
           "apples",
           "pears"
         ];
       }),
       "people" => apcu_entry("config.people", function($key){
         return [
          "bob",
          "joe",
          "niki"
         ];
       })
     ];
    });

    var_dump($config);
    ?>

El ejemplo anterior mostrará:

    array(2) {
      ["fruit"]=>
      array(2) {
        [0]=>
        string(6) "apples"
        [1]=>
        string(5) "pears"
      }
      ["people"]=>
      array(3) {
        [0]=>
        string(3) "bob"
        [1]=>
        string(3) "joe"
        [2]=>
        string(4) "niki"
      }
    }

### Ver también

- apcu_store() - Almacena una variable en la caché de datos
- apcu_fetch() - Recupera una variable almacenada en la caché
- apcu_delete() - Elimina una variable almacenada en caché

# apcu_exists

(PECL apcu >= 4.0.0)

apcu_exists — Verifica si una entrada existe

### Descripción

function apcu_exists(string|array `$keys`): bool|array

Verifica si una o varias entradas APCu existen.

### Parámetros

`keys`
  Un string o un array de strings que contiene las claves.

### Valores devueltos

Devuelve el valor `true` si la clave existe, o `false` en caso contrario. O bien, si un array ha sido pasado a `keys`, entonces el valor devuelto es un array conteniendo todas las claves existentes, o un array vacío si ninguna existe.

### Ejemplos

Ejemplo #1 Un ejemplo con apcu_exists()

    <?php
    $fruit  = 'apple';
    $veggie = 'carrot';

    apcu_store('foo', $fruit);
    apcu_store('bar', $veggie);

    if (apcu_exists('foo')) {
        echo "Foo existe: ";
        echo apcu_fetch('foo');
    } else {
        echo "Foo no existe";
    }

    echo PHP_EOL;
    if (apcu_exists('baz')) {
        echo "Baz existe.";
    } else {
        echo "Baz no existe";
    }

    echo PHP_EOL;

    $ret = apcu_exists(array('foo', 'donotexist', 'bar'));
    var_dump($ret);

    ?>

Resultado del ejemplo anterior es similar a:

    Foo existe: apple
    Baz no existe
    array(2) {
      ["foo"]=>
      bool(true)
      ["bar"]=>
      bool(true)
    }

### Ver también

- apcu_cache_info() - Recupera la información almacenada en la memoria APCu
- apcu_fetch() - Recupera una variable almacenada en la caché

# apcu_fetch

(PECL apcu >= 4.0.0)

apcu_fetch — Recupera una variable almacenada en la caché

### Descripción

function apcu_fetch(mixed `$key`, bool `&$success` = ?): mixed

Recupera una entrada de la caché.

### Parámetros

`key`
  La clave `key` utilizada para almacenar el valor (con apcu_store()). Si se pasa un array, entonces cada elemento es recuperado y devuelto.
`success`
  Definido como `true` en caso de éxito y `false` en caso de fallo.

### Valores devueltos

La variable o el array de variables almacenado en caso de éxito; `false` en caso de fallo.

### Historial de cambios

Versión | Descripción
--- | ---
PECL apcu 3.0.17 | El parámetro `success` ha sido añadido.

### Ejemplos

Ejemplo #1 Un ejemplo con apcu_fetch()

    <?php
    $bar = 'BAR';
    apcu_store('foo', $bar);
    var_dump(apcu_fetch('foo'));
    ?>

El ejemplo anterior mostrará:

    string(3) "BAR"

### Ver también

- apcu_store() - Almacena una variable en la caché de datos
- apcu_delete() - Elimina una variable almacenada en caché
- APCUIterator

# apcu_inc

(PECL apcu >= 4.0.0)

apcu_inc — Incrementa un número almacenado

### Descripción

function apcu_inc(
string `$key`,
int `$step` = 1,
bool `&$success` = ?,
int `$ttl` = 0
): int|false

Incrementa un número almacenado.

### Parámetros

`key`
  La clave del valor que debe ser incrementado.
`step`
  El paso de incrementación o el valor a añadir.
`success`
  Opcional, pasa el valor booleano éxito o fallo a la variable referenciada.
`ttl`
  Duración de vida a utilizar si la función inserta una nueva variable (en lugar de incrementar una variable existente).

### Valores devueltos

Devuelve el valor actual asociado a la clave `key` en caso de éxito, o `false` si ocurre un error

### Ejemplos

Ejemplo #1 Un ejemplo con apcu_inc()

    <?php
    echo "Hagamos algo con éxito", PHP_EOL;

    apcu_store('anumber', 42);

    echo apcu_fetch('anumber'), PHP_EOL;

    echo apcu_inc('anumber'), PHP_EOL;
    echo apcu_inc('anumber', 10), PHP_EOL;
    echo apcu_inc('anumber', 10, $success), PHP_EOL;

    var_dump($success);

    echo "Ahora, hagamos que falle", PHP_EOL, PHP_EOL;

    apcu_store('astring', 'foo');

    $ret = apcu_inc('astring', 1, $fail);

    var_dump($ret);
    var_dump($fail);
    ?>

Resultado del ejemplo anterior es similar a:

    Hagamos algo con éxito
    42
    43
    53
    63
    bool(true)
    Ahora, hagamos que falle

    bool(false)
    bool(false)

### Ver también

- apcu_dec() - Disminuir un número almacenado

# apcu_key_info

(PECL apcu >= 4.0.2)

apcu_key_info — Devuelve información detallada sobre la clave de caché

### Descripción

function apcu_key_info(string `$key`): ?array

Devuelve información detallada sobre la clave de caché.

### Parámetros

`key`
  Nombre de la clave.

### Valores devueltos

Un array que contiene información detallada sobre la clave de caché, o el valor `null` si la clave no existe.

### Ejemplos

Ejemplo #1 Un ejemplo con apcu_key_info()

    <?php
    apcu_add('a','b');
    var_dump(apcu_key_info('a'));
    ?>

El ejemplo anterior mostrará:

    array(7) {
      ["hits"]=>
      int(0)
      ["access_time"]=>
      int(1606701783)
      ["mtime"]=>
      int(1606701783)
      ["creation_time"]=>
      int(1606701783)
      ["deletion_time"]=>
      int(0)
      ["ttl"]=>
      int(0)
      ["refs"]=>
      int(0)
    }

### Ver también

- apcu_store() - Almacena una variable en la caché de datos
- apcu_fetch() - Recupera una variable almacenada en la caché
- apcu_delete() - Elimina una variable almacenada en caché

# apcu_sma_info

(PECL apcu >= 4.0.0)

apcu_sma_info — Devuelve información sobre la Asignación de Memoria Compartida de APCu

### Descripción

function apcu_sma_info(bool `$limited` = `false`): array|false

Devuelve información sobre la Asignación de Memoria Compartida de APCu.

### Parámetros

`limited`
  Cuando el valor `false` es pasado (por omisión) a este argumento, la función apcu_sma_info() devuelve información detallada sobre cada segmento.

### Valores devueltos

Un array de datos sobre la Asignación de Memoria Compartida; `false` en caso de fallo.

### Ejemplos

Ejemplo #1 Un ejemplo con apcu_sma_info()

    <?php
    print_r(apcu_sma_info());
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [num_seg] => 1
        [seg_size] => 31457280
        [avail_mem] => 31448408
        [block_lists] => Array
            (
                [0] => Array
                    (
                        [0] => Array
                            (
                                [size] => 31448408
                                [offset] => 8864
                            )

                    )

            )

    )

### Ver también

- Directivas de configuración de APCu

# apcu_store

(PECL apcu >= 4.0.0)

apcu_store — Almacena una variable en la caché de datos

### Descripción

function apcu_store(string `$key`, mixed `$var`, int `$ttl` = 0): bool
function apcu_store(array `$values`, mixed `$unused` = NULL, int `$ttl` = 0): array

Almacena una variable en la caché de datos.

> Nota: A diferencia de muchos otros mecanismos en PHP, las variables almacenadas utilizando apcu_store() persistirán entre las peticiones (hasta que sus valores sean retirados de la caché).

### Parámetros

`key`
  Almacena la variable utilizando este nombre de clave. Cada clave es única en la caché, almacenar un segundo valor con el mismo parámetro `key` sobrescribirá el valor original.
`var`
  La variable a almacenar.
`ttl`
  Duración de vida; almacena la variable `var` en la caché durante un tiempo de `ttl` segundos. Después de la expiración de `ttl`, la variable almacenada será retirada de la caché (en la próxima petición). Si no se pasa ningún valor al parámetro `ttl` (o si el valor de `ttl` es `0`), la variable persistirá hasta que sea retirada manualmente de la caché, o, de lo contrario, fallará al salir de la caché (durante un borrado, reinicio, etc.).
`values`
  Los nombres son proporcionados por las claves del array `values`, las variables por los valores.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error. La segunda sintaxis devuelve un array con las claves erróneas.

### Ejemplos

Ejemplo #1 Un ejemplo con apcu_store()

    <?php
    $bar = 'BAR';
    apcu_store('foo', $bar);
    var_dump(apcu_fetch('foo'));
    ?>

El ejemplo anterior mostrará:

    string(3) "BAR"

### Ver también

- apcu_add() - Almacena en caché una nueva variable en el almacén de datos
- apcu_fetch() - Recupera una variable almacenada en la caché
- apcu_delete() - Elimina una variable almacenada en caché

## Tabla de contenidos

- apcu_add — Almacena en caché una nueva variable en el almacén de datos
- apcu_cache_info — Recupera la información almacenada en la memoria APCu
- apcu_cas — Actualiza un valor antiguo con un nuevo valor
- apcu_clear_cache — Limpia el caché del APCu
- apcu_dec — Disminuir un número almacenado
- apcu_delete — Elimina una variable almacenada en caché
- apcu_enabled — Si el APCu es utilizable en el entorno actual
- apcu_entry — Recupera o genera de forma atómica una entrada de caché
- apcu_exists — Verifica si una entrada existe
- apcu_fetch — Recupera una variable almacenada en la caché
- apcu_inc — Incrementa un número almacenado
- apcu_key_info — Devuelve información detallada sobre la clave de caché
- apcu_sma_info — Devuelve información sobre la Asignación de Memoria Compartida de APCu
- apcu_store — Almacena una variable en la caché de datos

# La clase APCUIterator

(PECL apcu >= 5.0.0)

## Introducción

La clase APCUIterator hace más fácil iterar sobre grandes cachés de APCu. Esto es útil ya que permite iterar sobre grandes cachés en pasos, al mismo tiempo que captura un número definido de entradas por instancia de bloqueo, por lo que libera los bloqueos de caché para otras actividades en lugar de mantener todo el caché para obtener 100 entradas (el valor por defecto). Además, utilizar comparación por expresiones regulares es más eficiente ya que se ha movido al nivel de C.

## Sinopsis de la Clase

class APCUIterator implements Iterator {
/* Métodos */
public function __construct(
array|string|null `$search` = `null`,
int `$format` = APC_ITER_ALL,
int `$chunk_size` = 100,
int `$list` = APC_LIST_ACTIVE
)
public function current(): mixed
public function getTotalCount(): int
public function getTotalHits(): int
public function getTotalSize(): int
public function key(): string
public function next(): bool
public function rewind(): void
public function valid(): bool
}

# APCUIterator::__construct

(PECL apcu >= 5.0.0)

APCUIterator::__construct — Construye un objeto iterador APCUIterator

### Descripción

public function APCUIterator::__construct(
array|string|null `$search` = `null`,
int `$format` = APC_ITER_ALL,
int `$chunk_size` = 100,
int `$list` = APC_LIST_ACTIVE
)

Construye un APCUIterator object.

### Parámetros

`search`
  O bien una expresión regular PCRE que coincide con nombres de clave APCu, dada como string. O una array de strings con nombres de claves APCu. O, opcionalmente `null` para omitir la búsqueda.
`format`
  El formato deseado, tal como está configurado con una o más de las constantes APC_ITER_*.
`chunk_size`
  El tamaño del fragmento. Debe ser un valor mayor que 0. El valor por defecto es 100.
`list`
  El tipo de lista. O bien pasar en `APC_LIST_ACTIVE` o `APC_LIST_DELETED`.

### Ejemplos

Ejemplo #1 Un ejemplo de APCUIterator::__construct()

    <?php
    foreach (new APCUIterator('/^counter\./') as $counter) {
        echo "$counter[key]: $counter[value]\n";
        apc_dec($counter['key'], $counter['value']);
    }
    ?>

### Ver también

- apcu_exists() - Verifica si una entrada existe
- apcu_cache_info() - Recupera la información almacenada en la memoria APCu

# APCUIterator::current

(PECL apcu >= 5.0.0)

APCUIterator::current — Obtener el elemento actual

### Descripción

public function APCUIterator::current(): mixed

Obtiene el elemento actual de la pila APCUIterator.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el elemento actual en caso de éxito, o `false` si no hay más elementos o no existen, o en caso de error.

### Ver también

- APCUIterator::next() - Mueve el puntero al siguiente elemento
- Iterator::current() - Devuelve el elemento actual

# APCUIterator::getTotalCount

(PECL apcu >= 5.0.0)

APCUIterator::getTotalCount — Obtiene el conteo total

### Descripción

public function APCUIterator::getTotalCount(): int

Obtener el conteo total.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El conteo total.

### Ver también

- APCUIterator::getTotalHits() - Obtener resultados totales de la memoria caché
- APCUIterator::getTotalSize() - Obtiene el tamaño total del caché
- apcu_cache_info() - Recupera la información almacenada en la memoria APCu

# APCUIterator::getTotalHits

(PECL apcu >= 5.0.0)

APCUIterator::getTotalHits — Obtener resultados totales de la memoria caché

### Descripción

public function APCUIterator::getTotalHits(): int

Obtiene el número total de visitas a la memoria caché.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El número de visitas en caso de éxito, o `false` en caso de error.

### Ver también

- APCUIterator::getTotalCount() - Obtiene el conteo total
- APCUIterator::getTotalSize() - Obtiene el tamaño total del caché
- apcu_cache_info() - Recupera la información almacenada en la memoria APCu

# APCUIterator::getTotalSize

(PECL apcu >= 5.0.0)

APCUIterator::getTotalSize — Obtiene el tamaño total del caché

### Descripción

public function APCUIterator::getTotalSize(): int

Obtiene el tamaño total del caché.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El tamaño total del caché.

### Ver también

- APCUIterator::getTotalCount() - Obtiene el conteo total
- APCUIterator::getTotalHits() - Obtener resultados totales de la memoria caché
- apc_cache_info()

# APCUIterator::key

(PECL apcu >= 5.0.0)

APCUIterator::key — Obtiene la clave del iterador

### Descripción

public function APCUIterator::key(): string

Obtiene la clave del iterador actual.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la clave en caso de éxito, o `false` en caso de error.

### Ver también

- APCUIterator::current() - Obtener el elemento actual
- Iterator::key() - Devuelve la clave del elemento actual

# APCUIterator::next

(PECL apcu >= 5.0.0)

APCUIterator::next — Mueve el puntero al siguiente elemento

### Descripción

public function APCUIterator::next(): bool

Mueve el puntero del iterador al siguiente elemento.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- APCUIterator::current() - Obtener el elemento actual
- APCUIterator::rewind() - Rebobina el iterador
- Iterator::next() - Avanza al siguiente elemento

# APCUIterator::rewind

(PECL apcu >= 5.0.0)

APCUIterator::rewind — Rebobina el iterador

### Descripción

public function APCUIterator::rewind(): void

Rebobina el iterador hasta el primer elemento.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

### Ver también

- APCUIterator::next() - Mueve el puntero al siguiente elemento
- Iterator::next() - Avanza al siguiente elemento

# APCUIterator::valid

(PECL apcu >= 5.0.0)

APCUIterator::valid — Comprueba si la posición actual es válida

### Descripción

public function APCUIterator::valid(): bool

Comprueba si la posición actual del iterador es válida.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si la posición actual del iterador es válida, en caso contrario `false`.

### Ver también

- APCUIterator::current() - Obtener el elemento actual
- Iterator::valid() - Comprueba si la posición actual es válido

## Tabla de contenidos

- APCUIterator::__construct — Construye un objeto iterador APCUIterator
- APCUIterator::current — Obtener el elemento actual
- APCUIterator::getTotalCount — Obtiene el conteo total
- APCUIterator::getTotalHits — Obtener resultados totales de la memoria caché
- APCUIterator::getTotalSize — Obtiene el tamaño total del caché
- APCUIterator::key — Obtiene la clave del iterador
- APCUIterator::next — Mueve el puntero al siguiente elemento
- APCUIterator::rewind — Rebobina el iterador
- APCUIterator::valid — Comprueba si la posición actual es válida

- Instalación/Configuración
  - Instalación
  - Configuración en tiempo de ejecución
- Constantes predefinidas
- Funciones APCu
  - apcu_add — Almacena en caché una nueva variable en el almacén de datos
  - apcu_cache_info — Recupera la información almacenada en la memoria APCu
  - apcu_cas — Actualiza un valor antiguo con un nuevo valor
  - apcu_clear_cache — Limpia el caché del APCu
  - apcu_dec — Disminuir un número almacenado
  - apcu_delete — Elimina una variable almacenada en caché
  - apcu_enabled — Si el APCu es utilizable en el entorno actual
  - apcu_entry — Recupera o genera de forma atómica una entrada de caché
  - apcu_exists — Verifica si una entrada existe
  - apcu_fetch — Recupera una variable almacenada en la caché
  - apcu_inc — Incrementa un número almacenado
  - apcu_key_info — Devuelve información detallada sobre la clave de caché
  - apcu_sma_info — Devuelve información sobre la Asignación de Memoria Compartida de APCu
  - apcu_store — Almacena una variable en la caché de datos
- APCUIterator — La clase APCUIterator
  - APCUIterator::__construct — Construye un objeto iterador APCUIterator
  - APCUIterator::current — Obtener el elemento actual
  - APCUIterator::getTotalCount — Obtiene el conteo total
  - APCUIterator::getTotalHits — Obtener resultados totales de la memoria caché
  - APCUIterator::getTotalSize — Obtiene el tamaño total del caché
  - APCUIterator::key — Obtiene la clave del iterador
  - APCUIterator::next — Mueve el puntero al siguiente elemento
  - APCUIterator::rewind — Rebobina el iterador
  - APCUIterator::valid — Comprueba si la posición actual es válida

# Componere

# Introducción

Componere (latin, English: compose) se dirige a los entornos de producción y proporciona una API para composición de las clases, parches y moldeado.

##### Composición:

Componere\Definition se utiliza para definir (o redefinir) una clase en tiempo de ejecución; La clase puede entonces registrarse, y en caso de redefinición reemplaza a la clase original durante todo el tiempo que la clase Componere\Definition exista.

public function Componere\Definition::__construct(string `$name`)
public function Componere\Definition::__construct(string `$name`, string `$parent`)
public function Componere\Definition::__construct(string `$name`, array `$interfaces`)
public function Componere\Definition::__construct(string `$name`, string `$parent`, array `$interfaces`)

##### Parcheado:

Componere\Patch se utiliza para cambiar la clase de una instancia específica de un objeto en tiempo de ejecución; Tras su aplicación, el parche permanecerá aplicado durante todo el tiempo que la clase Componere\Patch exista, y puede ser revertido explícitamente.

public function Componere\Patch::__construct(object `$instance`)
public function Componere\Patch::__construct(object `$instance`, array `$interfaces`)

##### Moldeado:

Componere\ Las funciones de moldeado pueden moldear entre tipos compatibles definidos por el usuario; Donde compatible significa Type es sub o super al tipo de `object`.

function Componere\cast(string `$type`, object `$object`): object
function Componere\cast_by_ref(string `$type`, object `$object`): object

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación

## Requerimientos

Se requiere Reflection

## Instalación

La fuente de Componere y las liberaciones están disponibles en » github

# La clase Componere\Abstract\Definition

(Componere 2 >= 2.1.0)

## Introducción

Esta abstracta final representa una entrada de clase, y no debe ser usado por el programador.

## Sinopsis de la Clase

final abstract class Componere\Abstract\Definition {
/* Métodos */
public function addInterface(string `$interface`): Definition
public function addMethod(string `$name`, Componere\Method `$method`): Definition
public function addTrait(string `$trait`): Definition
public function getReflector(): ReflectionClass
}

# Componere\Abstract\Definition::addInterface

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addInterface — Añadir Interface

### Descripción

public function Componere\Abstract\Definition::addInterface(string `$interface`): Definition

Implementará la interface dada en la definición actual

### Parámetros

`interface`
  El nombre de una interface insensible a las mayúsculas y minúsculas

### Valores devueltos

La definición actual

### Excepciones

Advertencia

Lanzará RuntimeException si Definition se registró

# Componere\Abstract\Definition::addMethod

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addMethod — Añadir método

### Descripción

public function Componere\Abstract\Definition::addMethod(string `$name`, Componere\Method `$method`): Definition

Creará o anulará un método en la definición actual.

### Parámetros

`name`
  El nombre del método insensible a las mayúsculas y minúsculas
`method`
  Componere\Method que no se haya añadido previamente a otra Definition

### Valores devueltos

La Definition actual

### Excepciones

Advertencia

Lanzará RuntimeException si Definition se registró

Advertencia

Lanzará RuntimeException si el método se añadió a otra definición

# Componere\Abstract\Definition::addTrait

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addTrait — Añadir rasgo

### Descripción

public function Componere\Abstract\Definition::addTrait(string `$trait`): Definition

Usará el rasgo dado para la definición actual

### Parámetros

`trait`
  El nombre del rasgo insensible a las mayúsculas y minúsculas

### Valores devueltos

La definición actual

### Excepciones

Advertencia

Lanzará RuntimeException si Definition se registró

# Componere\Abstract\Definition::getReflector

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::getReflector — Reflection

### Descripción

public function Componere\Abstract\Definition::getReflector(): ReflectionClass

Creará o devolverá una clase Reflection

### Valores devueltos

Una clase Reflection para la definición actual (en caché)

## Tabla de contenidos

- Componere\Abstract\Definition::addInterface — Añadir Interface
- Componere\Abstract\Definition::addMethod — Añadir método
- Componere\Abstract\Definition::addTrait — Añadir rasgo
- Componere\Abstract\Definition::getReflector — Reflection

# La clase Componere\Definition

(Componere 2 >= 2.1.0)

## Introducción

La clase Definition permite al programador construir y registrar un tipo en tiempo de ejecución.

En caso de que una Definition reemplace una clase existente, la clase existente será restaurada cuando la Definition sea destruida.

## Sinopsis de la Clase

final class Componere\Definition extends Componere\Abstract\Definition {
/* Constructores */
public function __construct(string `$name`)
public function __construct(string `$name`, string `$parent`)
public function __construct(string `$name`, array `$interfaces`)
public function __construct(string `$name`, string `$parent`, array `$interfaces`)
/* Métodos */
public function addConstant(string `$name`, Componere\Value `$value`): Definition
public function addProperty(string `$name`, Componere\Value `$value`): Definition
public function register(): void
public function isRegistered(): bool
public function getClosure(string `$name`): Closure
public function getClosures(): array
/* Métodos heredados */
public function Componere\Abstract\Definition::addInterface(string `$interface`): Definition
public function Componere\Abstract\Definition::addMethod(string `$name`, Componere\Method `$method`): Definition
public function Componere\Abstract\Definition::addTrait(string `$trait`): Definition
public function Componere\Abstract\Definition::getReflector(): ReflectionClass
}

# Componere\Definition::__construct

(Componere 2 >= 2.1.0)

Componere\Definition::__construct — Constructor Definition

### Descripción

public function Componere\Definition::__construct(string `$name`)
public function Componere\Definition::__construct(string `$name`, string `$parent`)
public function Componere\Definition::__construct(string `$name`, array `$interfaces`)
public function Componere\Definition::__construct(string `$name`, string `$parent`, array `$interfaces`)

### Parámetros

`name`
  Un nombre de clase insensible a las mayúsculas y minúsculas
`parent`
  Un nombre de clase insensible a las mayúsculas y minúsculas
`interfaces`
  Un array de nombres de clase insensibles a las mayúsculas y minúsculas

### Excepciones

Advertencia

Lanzará InvalidArgumentException si se intenta reemplazar una clase interna

Advertencia

Lanzará InvalidArgumentException si se intenta sustituir una interface

Advertencia

Lanzará InvalidArgumentException si se intenta reemplazar un rasgo

Advertencia

Lanzará RuntimeException si una clase en `interfaces` no se puede encontrar

Advertencia

Lanzará RuntimeException si una clase en `interfaces` no es una interface

# Componere\Definition::addConstant

(Componere 2 >= 2.1.0)

Componere\Definition::addConstant — Añade constante

### Descripción

public function Componere\Definition::addConstant(string `$name`, Componere\Value `$value`): Definition

Declarará una constante de clase en la definición actual

### Parámetros

`name`
  El nombre de la constante que distingue entre mayúsculas y minúsculas
`value`
  El valor de la constante, no debe ser indefinido o estático

### Valores devueltos

La definición actual

### Excepciones

Advertencia

Lanzará RuntimeException si Definition fué registrado

Advertencia

Lanzará RuntimeException si `name` ya está declarada como una constante

Advertencia

Lanzará RuntimeException si `value` es estática

Advertencia

Lanzará RuntimeException si `value` no está definida

# Componere\Definition::addProperty

(Componere 2 >= 2.1.0)

Componere\Definition::addProperty — Añade propiedad

### Descripción

public function Componere\Definition::addProperty(string `$name`, Componere\Value `$value`): Definition

Declarará una propiedad de clase sobre la definición actual

### Parámetros

`name`
  El nombre de la propiedad distingue mayúsculas y minúsculas
`value`
  El valor por omisión de la propiedad

### Valores devueltos

La definición actual

### Excepciones

Advertencia

Lanzará RuntimeException si Definition se registró

Advertencia

Lanzará RuntimeException si `name` ya está declarada como una propiedad

# Componere\Definition::register

(Componere 2 >= 2.1.0)

Componere\Definition::register — Registro

### Descripción

public function Componere\Definition::register(): void

Registrará la Definition actual

### Excepciones

Advertencia

Lanzará RuntimeException si Definition fué registrada

# Componere\Definition::isRegistered

(Componere 2 >= 2.1.0)

Componere\Definition::isRegistered — Detección del estado

### Descripción

public function Componere\Definition::isRegistered(): bool

Deberá detectar el estado de registro de Definition

### Valores devueltos

Devolverá true si Definition está registrada

# Componere\Definition::getClosure

(Componere 2 >= 2.1.0)

Componere\Definition::getClosure — Obtener Cierre

### Descripción

public function Componere\Definition::getClosure(string `$name`): Closure

Devolverá un cierre para el método especificado por el nombre

### Parámetros

`name`
  El nombre del método insensible a las mayúsculas y minúsculas

### Valores devueltos

Un cierre vinculado al alcance correcto

### Excepciones

Advertencia

Lanzará RuntimeException si Definition se registró

Advertencia

Lanzará RuntimeException si `name` no se pudo encontrar

# Componere\Definition::getClosures

(Componere 2 >= 2.1.0)

Componere\Definition::getClosures — Obtener Cierres

### Descripción

public function Componere\Definition::getClosures(): array

Devolverá un array de cierres

### Valores devueltos

Devolverá todos los métodos como un array de objetos de cierre vinculados al alcance correcto

### Excepciones

Advertencia

Lanzará RuntimeException si Definition se registró

## Tabla de contenidos

- Componere\Definition::__construct — Constructor Definition
- Componere\Definition::addConstant — Añade constante
- Componere\Definition::addProperty — Añade propiedad
- Componere\Definition::register — Registro
- Componere\Definition::isRegistered — Detección del estado
- Componere\Definition::getClosure — Obtener Cierre
- Componere\Definition::getClosures — Obtener Cierres

# La clase Componere\Patch

(Componere 2 >= 2.1.0)

## Introducción

La clase Patch permite al programador cambiar el tipo de una instancia en tiempo de ejecución sin registrar una nueva Definition

Cuando se destruye un parche se revierte, de modo que los casos que fueron parcheados durante la vida del Parche son restaurados a su tipo formal.

## Sinopsis de la Clase

final class Componere\Patch extends Componere\Abstract\Definition {
/* Constructores */
public function __construct(object `$instance`)
public function __construct(object `$instance`, array `$interfaces`)
/* Métodos */
public function apply(): void
public function revert(): void
public function isApplied(): bool
public function derive(object `$instance`): Patch
public function getClosure(string `$name`): Closure
public function getClosures(): array
/* Métodos heredados */
public function Componere\Abstract\Definition::addInterface(string `$interface`): Definition
public function Componere\Abstract\Definition::addMethod(string `$name`, Componere\Method `$method`): Definition
public function Componere\Abstract\Definition::addTrait(string `$trait`): Definition
public function Componere\Abstract\Definition::getReflector(): ReflectionClass
}

# Componere\Patch::__construct

(Componere 2 >= 2.1.0)

Componere\Patch::__construct — Constructor Patch

### Descripción

public function Componere\Patch::__construct(object `$instance`)
public function Componere\Patch::__construct(object `$instance`, array `$interfaces`)

### Parámetros

`instance`
  El objetivo de este Patch
`interfaces`
  Un array de nombres de clase insensibles a las mayúsculas y minúsculas

### Excepciones

Advertencia

Lanzará RuntimeException si una clase en `interfaces` no se puede encontrar

Advertencia

Lanzará RuntimeException si una clase en `interfaces` no es una interface

# Componere\Patch::apply

(Componere 2 >= 2.1.0)

Componere\Patch::apply — Aplicación

### Descripción

public function Componere\Patch::apply(): void

Aplicará el parche actual

# Componere\Patch::revert

(Componere 2 >= 2.1.0)

Componere\Patch::revert — Reversión

### Descripción

public function Componere\Patch::revert(): void

Revertirá el parche actual

# Componere\Patch::isApplied

(Componere 2 >= 2.1.0)

Componere\Patch::isApplied — Detección del estado

### Descripción

public function Componere\Patch::isApplied(): bool

# Componere\Patch::derive

(Componere 2 >= 2.1.1)

Componere\Patch::derive — Derivación del parche

### Descripción

public function Componere\Patch::derive(object `$instance`): Patch

Derivará un Patch (parche) para la `instance` (instancia) dada

### Parámetros

`instance`
  El objetivo del Parche derivado

### Valores devueltos

Patch (parche) para la `instance` (instancia) derivada del Patch (parche) actual

### Excepciones

Advertencia

Lanzará InvalidArgumentException si `instance` no es compatible

# Componere\Patch::getClosure

(Componere 2 >= 2.1.0)

Componere\Patch::getClosure — Obtener Cierre

### Descripción

public function Componere\Patch::getClosure(string `$name`): Closure

Devolverá un cierre para el método especificado por el nombre

### Parámetros

`name`
  El nombre del método insensible a las mayúsculas y minúsculas

### Valores devueltos

Un cierre vinculado al ámbito y objeto correctos

### Excepciones

Advertencia

Lanzará RuntimeException si `name` no se pudo encontrar

# Componere\Patch::getClosures

(Componere 2 >= 2.1.0)

Componere\Patch::getClosures — Obtener Cierres

### Descripción

public function Componere\Patch::getClosures(): array

Devolverá un array de Cierres

### Valores devueltos

Devolverá todos los métodos como un array de objetos de cierre unidos al ámbito y objeto correctos

## Tabla de contenidos

- Componere\Patch::__construct — Constructor Patch
- Componere\Patch::apply — Aplicación
- Componere\Patch::revert — Reversión
- Componere\Patch::isApplied — Detección del estado
- Componere\Patch::derive — Derivación del parche
- Componere\Patch::getClosure — Obtener Cierre
- Componere\Patch::getClosures — Obtener Cierres

# La clase Componere\Method

(Componere 2 >= 2.1.0)

## Introducción

Un método representa una función con banderas de accesibilidad modificables

## Sinopsis de la Clase

final class Componere\Method {
/* Constructor */
public function __construct(Closure `$closure`)
/* Métodos */
public function setPrivate(): Method
public function setProtected(): Method
public function setStatic(): Method
public function getReflector(): ReflectionMethod
}

# Componere\Method::__construct

(Componere 2 >= 2.1.0)

Componere\Method::__construct — Constructor Method

### Descripción

public function Componere\Method::__construct(Closure `$closure`)

### Parámetros

`closure`

# Componere\Method::setPrivate

(Componere 2 >= 2.1.0)

Componere\Method::setPrivate — Modificación de la accesibilidad

### Descripción

public function Componere\Method::setPrivate(): Method

### Valores devueltos

El método actual

### Excepciones

Advertencia

Lanzará RuntimeException si el nivel de acceso fue establecido previamente

# Componere\Method::setProtected

(Componere 2 >= 2.1.0)

Componere\Method::setProtected — Modificación de la accesibilidad

### Descripción

public function Componere\Method::setProtected(): Method

### Valores devueltos

El método actual

### Excepciones

Advertencia

Lanzará RuntimeException si el nivel de acceso fue establecido previamente

# Componere\Method::setStatic

(Componere 2 >= 2.1.0)

Componere\Method::setStatic — Modificación de la accesibilidad

### Descripción

public function Componere\Method::setStatic(): Method

### Valores devueltos

El método actual

# Componere\Method::getReflector

(Componere 2 >= 2.1.0)

Componere\Method::getReflector — Reflection

### Descripción

public function Componere\Method::getReflector(): ReflectionMethod

Creará o devolverá un Método de Reflection

### Valores devueltos

Un método de Reflection para el método actual (en caché)

## Tabla de contenidos

- Componere\Method::__construct — Constructor Method
- Componere\Method::setPrivate — Modificación de la accesibilidad
- Componere\Method::setProtected — Modificación de la accesibilidad
- Componere\Method::setStatic — Modificación de la accesibilidad
- Componere\Method::getReflector — Reflection

# La clase Componere\Value

(Componere 2 >= 2.1.0)

## Introducción

Una clase Value representa una variable PHP de todos los tipos, incluyendo las indefinidas

## Sinopsis de la Clase

final class Componere\Value {
/* Constructor */
public function __construct(mixed `$default` = ?)
/* Métodos */
public function setPrivate(): Value
public function setProtected(): Value
public function setStatic(): Value
public function isPrivate(): bool
public function isProtected(): bool
public function isStatic(): bool
public function hasDefault(): bool
}

# Componere\Value::__construct

(Componere 2 >= 2.1.0)

Componere\Value::__construct — Constructor Value

### Descripción

public function Componere\Value::__construct(mixed `$default` = ?)

### Parámetros

`default`

### Excepciones

Advertencia

Lanzará InvalidArgumentException si `default` no tiene un valor adecuado

# Componere\Value::setPrivate

(Componere 2 >= 2.1.0)

Componere\Value::setPrivate — Modificación de la accesibilidad

### Descripción

public function Componere\Value::setPrivate(): Value

### Valores devueltos

El valor actual

### Excepciones

Advertencia

Lanzará RuntimeException si el nivel de acceso fue establecido previamente

# Componere\Value::setProtected

(Componere 2 >= 2.1.0)

Componere\Value::setProtected — Modificación de la accesibilidad

### Descripción

public function Componere\Value::setProtected(): Value

### Valores devueltos

El valor actual

### Excepciones

Advertencia

Lanzará RuntimeException si el nivel de acceso fue establecido previamente

# Componere\Value::setStatic

(Componere 2 >= 2.1.0)

Componere\Value::setStatic — Modificación de la accesibilidad

### Descripción

public function Componere\Value::setStatic(): Value

### Valores devueltos

El valor actual

# Componere\Value::isPrivate

(Componere 2 >= 2.1.0)

Componere\Value::isPrivate — Detección de accesibilidad

### Descripción

public function Componere\Value::isPrivate(): bool

# Componere\Value::isProtected

(Componere 2 >= 2.1.0)

Componere\Value::isProtected — Detección de accesibilidad

### Descripción

public function Componere\Value::isProtected(): bool

# Componere\Value::isStatic

(Componere 2 >= 2.1.0)

Componere\Value::isStatic — Detección de accesibilidad

### Descripción

public function Componere\Value::isStatic(): bool

# Componere\Value::hasDefault

(Componere 2 >= 2.1.0)

Componere\Value::hasDefault — Interacción de Value

### Descripción

public function Componere\Value::hasDefault(): bool

## Tabla de contenidos

- Componere\Value::__construct — Constructor Value
- Componere\Value::setPrivate — Modificación de la accesibilidad
- Componere\Value::setProtected — Modificación de la accesibilidad
- Componere\Value::setStatic — Modificación de la accesibilidad
- Componere\Value::isPrivate — Detección de accesibilidad
- Componere\Value::isProtected — Detección de accesibilidad
- Componere\Value::isStatic — Detección de accesibilidad
- Componere\Value::hasDefault — Interacción de Value

# Funciones Componere

# Componere\cast

(Componere 2 >= 2.1.2)

Componere\cast — Moldeado

### Descripción

function Componere\cast(string `$type`, object `$object`): object

### Parámetros

`type`
  Un tipo definido por el usuario
`object`
  Un objeto con un tipo definido por el usuario compatible con Type

### Valores devueltos

Un object de tipo Type, moldeado de `object`

### Errores/Excepciones

Advertencia

Lanzará InvalidArgumentException si el tipo de `object` es o se deriva de una clase interna

Advertencia

Lanzará InvalidArgumentException si Type es una interface

Advertencia

Lanzará InvalidArgumentException si Type es un rasgo

Advertencia

Lanzará InvalidArgumentException si Type es una abstracta

Advertencia

Lanzará InvalidArgumentException si Type no es compatible con el tipo de `object`

### Ver también

- Componere\cast_by_ref

# Componere\cast_by_ref

(Componere 2 >= 2.1.2)

Componere\cast_by_ref — Moldeado

### Descripción

function Componere\cast_by_ref(string `$type`, object `$object`): object

### Parámetros

type
  Un tipo definido por el usuario
`object`
  Un objeto con un tipo definido por el usuario compatible con Type

### Valores devueltos

Un object de tipo Type, moldeado de `object`, donde los miembros son referencias a miembros de `object`

### Errores/Excepciones

Advertencia

Lanzará InvalidArgumentException si el tipo de `object` es o se deriva de una clase interna

Advertencia

Lanzará InvalidArgumentException si Type es una interface

Advertencia

Lanzará InvalidArgumentException si Type es un rasgo

Advertencia

Lanzará InvalidArgumentException si Type es una abstracta

Advertencia

Lanzará InvalidArgumentException si Type no es compatible con el tipo de `object`

### Ver también

- Componere\cast

## Tabla de contenidos

- Componere\cast — Moldeado
- Componere\cast_by_ref — Moldeado

- Instalación/Configuración
  - Requerimientos
  - Instalación
- Componere\Abstract\Definition — La clase Componere\Abstract\Definition
  - Componere\Abstract\Definition::addInterface — Añadir Interface
  - Componere\Abstract\Definition::addMethod — Añadir método
  - Componere\Abstract\Definition::addTrait — Añadir rasgo
  - Componere\Abstract\Definition::getReflector — Reflection
- Componere\Definition — La clase Componere\Definition
  - Componere\Definition::__construct — Constructor Definition
  - Componere\Definition::addConstant — Añade constante
  - Componere\Definition::addProperty — Añade propiedad
  - Componere\Definition::register — Registro
  - Componere\Definition::isRegistered — Detección del estado
  - Componere\Definition::getClosure — Obtener Cierre
  - Componere\Definition::getClosures — Obtener Cierres
- Componere\Patch — La clase Componere\Patch
  - Componere\Patch::__construct — Constructor Patch
  - Componere\Patch::apply — Aplicación
  - Componere\Patch::revert — Reversión
  - Componere\Patch::isApplied — Detección del estado
  - Componere\Patch::derive — Derivación del parche
  - Componere\Patch::getClosure — Obtener Cierre
  - Componere\Patch::getClosures — Obtener Cierres
- Componere\Method — La clase Componere\Method
  - Componere\Method::__construct — Constructor Method
  - Componere\Method::setPrivate — Modificación de la accesibilidad
  - Componere\Method::setProtected — Modificación de la accesibilidad
  - Componere\Method::setStatic — Modificación de la accesibilidad
  - Componere\Method::getReflector — Reflection
- Componere\Value — La clase Componere\Value
  - Componere\Value::__construct — Constructor Value
  - Componere\Value::setPrivate — Modificación de la accesibilidad
  - Componere\Value::setProtected — Modificación de la accesibilidad
  - Componere\Value::setStatic — Modificación de la accesibilidad
  - Componere\Value::isPrivate — Detección de accesibilidad
  - Componere\Value::isProtected — Detección de accesibilidad
  - Componere\Value::isStatic — Detección de accesibilidad
  - Componere\Value::hasDefault — Interacción de Value
- Funciones Componere
  - Componere\cast — Moldeado
  - Componere\cast_by_ref — Moldeado

# Manejo y registro de errores

# Introducción

Estas funciones se ocupan del manejo y registro de errores. Le permiten definir sus propias reglas de manejo de errores, así como modificar la manera en que los errores pueden ser registrados. Esto le permite cambiar y mejorar la notificación de errores para acomodarla a sus necesidades.

Con las funciones de registro se pueden enviar mensajes directamente a otras máquinas, a un e-mail (¡o un e-mail a un busca!), al registro del sistema, etc., por lo que puede registrar y monitorizar selectivamente las partes más importantes de sus aplicaciones y sitios web.

Las funciones de notificación de errores le permiten personalizar qué niveles y tipos de errores se dan, abarcando desde simples avisos hasta funciones personalizadas devueltas al originarse un error.

# Instalación/Configuración

## Tabla de contenidos

- Configuración en tiempo de ejecución

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración para la gestión de errores
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
error_reporting | NULL | `INI_ALL` |
fatal_error_backtraces | "1" | `INI_ALL` | Disponible a partir de PHP 8.5.0
display_errors | "1" | `INI_ALL` |
display_startup_errors | "1" | `INI_ALL` | Anterior a PHP 8.0.0, el valor por omisión era `"0"`.
log_errors | "0" | `INI_ALL` |
log_errors_max_len | "1024" | `INI_ALL` | Sin efecto a partir de PHP 8.0.0, eliminado a partir de PHP 8.1.0.
ignore_repeated_errors | "0" | `INI_ALL` |
ignore_repeated_source | "0" | `INI_ALL` |
report_memleaks | "1" | `INI_ALL` | Obsoleto a partir de PHP 8.5.0
track_errors | "0" | `INI_ALL` | Deprecado a partir de PHP 7.2.0, eliminado a partir de PHP 8.0.0.
html_errors | "1" | `INI_ALL` |
xmlrpc_errors | "0" | `INI_SYSTEM` |
xmlrpc_error_number | "0" | `INI_ALL` |
docref_root | "" | `INI_ALL` |
docref_ext | "" | `INI_ALL` |
error_prepend_string | NULL | `INI_ALL` |
error_append_string | NULL | `INI_ALL` |
error_log | NULL | `INI_ALL` |
error_log_mode | 0o644 | `INI_ALL` | Disponible a partir de PHP 8.2.0.
syslog.facility | "LOG_USER" | `INI_SYSTEM` | Disponible a partir de PHP 7.3.0.
syslog.filter | "no-ctrl" | `INI_ALL` | Disponible a partir de PHP 7.3.0.
syslog.ident | "php" | `INI_SYSTEM` | Disponible a partir de PHP 7.3.0.

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`error_reporting` int

  Establece el nivel de error. Este parámetro es un entero, representando un campo de bits. Añada los valores siguientes para elegir el nivel que desee, tal como se describe en la sección Constantes predefinidas, y en el archivo php.ini. Para modificar esta configuración durante la ejecución del script, utilice la función error_reporting(). Consulte también la directiva display_errors.

  El valor por omisión es `E_ALL`.

  Anterior a PHP 8.0.0, el valor por omisión era : ``E_ALL` & ~`E_NOTICE` & ~`E_STRICT` & ~`E_DEPRECATED``. Esto significa que los diagnósticos de nivel `E_NOTICE`, `E_STRICT` y `E_DEPRECATED` no eran mostrados.

  > Nota: Las constantes PHP fuera de PHP

  > El uso de las constantes PHP fuera de PHP, como en el archivo httpd.conf, no tiene significado útil excepto en los casos donde se necesitan valores enteros. Y desde que los niveles de errores fueron añadidos, el valor máximo (para `E_ALL`) debería cambiar. Por lo tanto, en lugar de `E_ALL`, utilice un valor más grande para cubrir todos los bits, un valor numérico como `2147483647` (incluyendo todos los errores, y no solo los errores de tipo `E_ALL`).

`fatal_error_backtraces` bool
  Controla si los errores fatales deben incluir un seguimiento de pila. Los errores fatales son `E_ERROR`, `E_CORE_ERROR`, `E_COMPILE_ERROR`, `E_USER_ERROR`, `E_RECOVERABLE_ERROR`, y `E_PARSE`.
`display_errors` string

  Esta directiva determina si los errores deben ser mostrados en pantalla o no.

  - `Off` : no mostrar ningún error.
  - `On` o `stdout` : mostrar los errores a `stdout`. Es el valor por omisión.
  - `stderr` : mostrar los errores a `stderr`. Solamente efectivo en las SAPIs `CLI`, `phpdbg` y `CGI`.
  El `php.ini-development` empaquetado lo define en `On`; `php.ini-production` lo define en `Off`.

  > Nota: Es una directiva necesaria en desarrollo, pero que nunca debe ser utilizada en un sistema en producción. (ej. sistemas conectados a Internet).

  > Nota:

  > Aunque display_errors puede ser definido durante la ejecución (con la función ini_set()), no tendrá efecto si el script tiene errores fatales, ya que la acción deseada en el momento de la ejecución no será ejecutada.

`display_startup_errors` bool

  Aunque display_errors esté activado, pueden ocurrir errores durante la secuencia de inicio de PHP, y estos errores son ocultados. Con esta opción, puede mostrarlos, lo cual es recomendado para el depurado. Fuera de este caso, se recomienda encarecidamente dejar display_startup_errors en off.

`log_errors` bool

  Indica si los mensajes de error generados por los scripts deben ser registrados en el registro de errores del servidor o en error_log. Esta función es específica del servidor.

  > Nota:

  > Se recomienda utilizar el historial de errores, en lugar de mostrar los errores en los sitios de producción.

`log_errors_max_len` int

  Configura la longitud máxima de los errores que serán registrados en el historial, en kilobytes. En las informaciones de error_log, se añade el origen. El valor por omisión es de 1024. 0 significa que no hay límite de longitud. Esta longitud se aplica para registrar en el historial los errores, mostrar los errores y también a $php_errormsg pero no para las llamadas explícitas a funciones como error_log().

  Cuando un int es utilizado, su valor es medido en bytes. También puede utilizar la notación abreviada como se describe en esta entrada de la FAQ..
`ignore_repeated_errors` bool

  No registrar mensajes repetitivos. Los errores repetidos deben ocurrir en el mismo momento, en la misma línea y desde el mismo archivo de script, a menos que ignore_repeated_source esté definido a `true`.

`ignore_repeated_source` bool

  Ignora la fuente del mensaje en los mensajes repetidos. Cuando se ha configurado esta opción a On, no se registrarán los errores repetidos provenientes de archivos y líneas de código diferentes.

`report_memleaks` bool
  Si este parámetro está definido a On (por omisión), mostrará un informe de fuga de memoria detectada por el gestor de memoria Zend. Este informe será enviado a stderr en las plataformas Posix. En Windows, será enviado al depurador utilizando OutputDebugString() y podrá ser leído con herramientas como » DbgView. Este parámetro solo tiene efecto durante una compilación de depuración, y si error_reporting incluye `E_WARNING` en su lista autorizada.
  Advertencia

  Esta característica está OBSOLETA a partir de PHP 8.5.0. Depender de esta característica está altamente desaconsejado.

`track_errors` bool

  Si esta opción está activada, el último mensaje de error será colocado en la variable $php_errormsg.

`html_errors` bool

  Si está activado, los mensajes de error incluirán etiquetas HTML. El formato de los errores HTML producirá mensajes clicables que redirigirán al usuario hacia una página describiendo el error o la función que causó el error. Estas referencias son afectadas por docref_root y docref_ext.

  Si está desactivado, el mensaje de error será mostrado en texto plano.

`xmlrpc_errors` bool

  Si está activado, desactiva el informe normal de error y formatea los errores como mensajes de error XML-RPC.

`xmlrpc_error_number` int

  Utilizado como valor del elemento XML-RPC faultcode.

`docref_root` string

  El nuevo formato de error contiene una referencia a una página describiendo el error, o la función que causó el error. Para el manual, puede descargar este último en su idioma, y configurar esta opción para que apunte a él. Si su copia del manual es accesible a `"/manual/"`, puede simplemente utilizar `docref_root=/manual/`. Además, debe configurar `docref_ext` para que corresponda a las extensiones de su manual. `docref_ext=.html`. Es posible utilizar referencias externas. Por ejemplo, puede utilizar `docref_root=http://manual/en/` o `docref_root="http://landonize.it/?how=url&theme=classic&filter=Landon&url=http%3A%2F%2Fwww.php.net%2F"`

  La mayoría de las veces, se utiliza la opción docref_root con una barra al final (`"/"`). Pero no es obligatorio, como muestra el segundo ejemplo anterior.

  > Nota:

  > Esta directiva está destinada a ayudar en el desarrollo haciendo fácil la consulta de la descripción de una función. Nunca debe ser utilizada en un sistema de producción (ej. sistema conectado a Internet).

`docref_ext` string

  Consulte también docref_root.

  > Nota:

  > El valor de docref_ext debe comenzar con un punto `"."`.

`error_prepend_string` string

  La cadena a colocar antes de los mensajes de error. Solo utilizado cuando el mensaje de error es mostrado en pantalla. El uso principal es poder añadir etiquetado HTML adicional antes del mensaje de error.

`error_append_string` string

  La cadena a colocar después de los mensajes de error. Solo utilizado cuando el mensaje de error es mostrado en pantalla. El uso principal es poder añadir etiquetado HTML adicional después del mensaje de error.

`error_log` string

  Nombre del archivo donde serán registrados los errores. El archivo debe ser accesible en escritura por el usuario ejecutando el servidor web. Si el valor especial `syslog` es utilizado, los errores serán enviados al sistema de registro del servidor. En Unix, esto corresponde a syslog(3) y en Windows al registro de eventos. Consulte también: syslog(). Si esta directiva no está fijada, los errores son enviados al registro de errores SAPI. Por ejemplo, si es un registro de errores en Apache o `stderr` en CLI. Consulte también la función error_log().

`error_log_mode` int

  Modo de archivo para el archivo definido para error_log.

`syslog.facility` string

  Especifica el tipo de programa que registra el mensaje. Solo efectivo si error_log está definido como "syslog".

`syslog.filter` string

  Especifica el tipo de filtro para filtrar los mensajes registrados. Los caracteres permitidos son pasados sin modificación; todos los demás son escritos en su representación hexadecimal prefijada con `\x`.

  - `all` – la cadena registrada será separada en caracteres de retorno de línea, y todos los caracteres son transmitidos sin alteraciones
  - `ascii` – la cadena registrada será separada en caracteres de retorno de línea, y todo carácter 7-bit ASCII no imprimible será escapado
  - `no-ctrl` – la cadena registrada será separada en caracteres de retorno de línea, y los caracteres no imprimibles serán escapados
  - `raw` – todos los caracteres son pasados al sistema de registro sin alteraciones, sin separaciones en los retornos de línea (idéntico a PHP anterior a 7.3)
  Este parámetro afectará el registro a través de error_log definido como "syslog" y las llamadas a syslog().

  > Nota:

  > El tipo de filtro `raw` está disponible a partir de PHP 7.3.8 y PHP 7.4.0.

  Esta directiva no es soportada en Windows.
`syslog.ident` string

  Especifica la cadena de identidad que es añadida a cada mensaje. Solo efectivo si error_log está definido como "syslog".

# Constantes predefinidas

Las constantes listadas aquí están siempre disponibles en PHP.

Las constantes siguientes (ya sea el valor numérico correspondiente, o su nombre simbólico) se utilizan como una máscara de bits para especificar los errores a reportar. Es posible utilizar los operadores a nivel de bits para combinar estos valores o enmascarar ciertos tipos de errores.

Sugerencia

Los nombres de las constantes pueden ser utilizados en php.ini en lugar de los valores numéricos brutos a los que corresponden. Sin embargo, solo los operadores `|`, `~`, `^`, `!`, `&` son comprendidos en php.ini.

Advertencia

No es posible utilizar los nombres simbólicos fuera de PHP. Por ejemplo, en httpd.conf el valor calculado de la máscara de bits debe ser utilizado en su lugar.

`E_ERROR` (int)
  Errores fatales durante la ejecución Estos indican errores de los cuales no es posible recuperarse, como un problema de asignación de memoria. La ejecución del script es detenida. Valor de la constante: `1`
`E_WARNING` (int)
  Advertencias durante la ejecución (errores no fatales). La ejecución del script no es interrumpida. Valor de la constante: `2`
`E_PARSE` (int)
  Errores de análisis durante la compilación. Los errores de análisis deberían ser generados únicamente por el analizador sintáctico. Valor de la constante: `4`
`E_NOTICE` (int)
  Notificaciones de ejecución. Indican que el script ha encontrado algo que podría señalar un error, pero que también podría ocurrir normalmente durante la ejecución de un script. Valor de la constante: `8`
`E_CORE_ERROR` (int)
  Errores fatales que ocurren durante el inicio inicial de PHP. Es como una `E_ERROR`, excepto que es generada por el núcleo de PHP. Valor de la constante: `16`
`E_CORE_WARNING` (int)
  Advertencias (errores no fatales) que ocurren durante el inicio inicial de PHP. Es como un `E_WARNING`, excepto que es generada por el núcleo de PHP. Valor de la constante: `32`
`E_COMPILE_ERROR` (int)
  Errores fatales de compilación. Es como un `E_ERROR`, excepto que es generado por el motor de script Zend. Valor de la constante: `64`
`E_COMPILE_WARNING` (int)
  Advertencias de compilación (errores no fatales). Es como un `E_WARNING`, excepto que es generado por el motor de script Zend. Valor de la constante: `128`
`E_DEPRECATED` (int)
  Avisos de depreciación durante la ejecución. Actívelo para recibir advertencias sobre código que no funcionará en versiones futuras. Valor de la constante: `8192`
`E_USER_ERROR` (int)
  Mensaje de error generado por el usuario. Esto se asemeja a un `E_ERROR`, excepto que es generado en el código PHP utilizando la función PHP trigger_error(). Valor de la constante: `256`
  Advertencia

  El uso de esta constante con trigger_error() está obsoleto a partir de PHP 8.4.0. Se recomienda lanzar una Exception o llamar a exit() en su lugar.

`E_USER_WARNING` (int)
  Mensaje de advertencia generado por el usuario. Esto se asemeja a un `E_NOTICE`, excepto que es generado en el código PHP utilizando la función PHP trigger_error(). Valor de la constante: `512`
`E_USER_NOTICE` (int)
  Mensaje de notificación generado por el usuario. Esto se asemeja a un `E_NOTICE`, excepto que es generado en el código PHP utilizando la función PHP trigger_error(). Valor de la constante: `1024`
`E_USER_DEPRECATED` (int)
  Mensaje de depreciación generado por el usuario. Esto se asemeja a un `E_DEPRECATED`, excepto que es generado en el código PHP utilizando la función PHP trigger_error(). Valor de la constante: `16384`
`E_STRICT` (int)
  Sugerencias de ejecución emitidas por PHP sobre el código ejecutado para garantizar la compatibilidad futura. Valor de la constante: `2048`
  Advertencia

  Este nivel de error no es utilizado, y ha sido depreciado a partir de PHP 8.4.0.

`E_RECOVERABLE_ERROR` (int)
  "Excepciones" del motor antiguo correspondientes a un error fatal recuperable. Similar a Error pero debe ser capturado mediante un manejador de errores definido por el usuario (ver set_error_handler()). Si no es gestionado, se comporta como `E_ERROR`. Valor de la constante: `4096`

  > Nota: Este nivel de error está efectivamente inutilizado, el único caso en el que puede ocurrir es cuando la interpretación de un object como bool falla. Esto solo puede ocurrir para objetos internos. El ejemplo más común, anterior a PHP 8.4.0, es el uso de una instancia GMP en una condición.

`E_ALL` (int)
  Máscara de bits que contiene todos los errores, advertencias y notificaciones. Valor de la constante: `30719`
  Advertencia

  Anterior a PHP 8.4, el valor de la constante era `32767`.

# Ejemplos

Abajo podemos ver un ejemplo del uso de las capacidades del manejo de errores de PHP. Definimos una función de gestión de errores que registra la información en un archivo (usado un foramto XML), y envía un e-mail a los desarrolladores en caso de que suceda un error crítico en la lógica.

Ejemplo #1 Usar el manejo de errores en un script

    <?php
    // haremos nuestro propio manejo de errores
    error_reporting(0);

    // función de gestión de errores definida por el usuario
    function gestorErrores($númerr, $menserr, $nombrearchivo, $númlínea, $vars)
    {
        // marca de tiempo para la entrada del error
        $fh = date("Y-m-d H:i:s (T)");

        // definir una matriz asociativa de cadena de error
        // en realidad las únicas entradas que deberíamos
        // considerar son E_WARNING, E_NOTICE, E_USER_ERROR,
        // E_USER_WARNING y E_USER_NOTICE
        $tipoerror = array (
                    E_ERROR              => 'Error',
                    E_WARNING            => 'Warning',
                    E_PARSE              => 'Parsing Error',
                    E_NOTICE             => 'Notice',
                    E_CORE_ERROR         => 'Core Error',
                    E_CORE_WARNING       => 'Core Warning',
                    E_COMPILE_ERROR      => 'Compile Error',
                    E_COMPILE_WARNING    => 'Compile Warning',
                    E_USER_ERROR         => 'User Error',
                    E_USER_WARNING       => 'User Warning',
                    E_USER_NOTICE        => 'User Notice',
                    E_STRICT             => 'Runtime Notice',
                    E_RECOVERABLE_ERROR  => 'Catchable Fatal Error'
                    );
        // conjunto de errores por el cuál se guardará un seguimiento de una variable
        $errores_usuario = array(E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE);

        $err = "<errorentry>\n";
        $err .= "\t<datetime>" . $fh . "</datetime>\n";
        $err .= "\t<errornum>" . $númerr . "</errornum>\n";
        $err .= "\t<errortype>" . $tipoerror[$númerr] . "</errortype>\n";
        $err .= "\t<errormsg>" . $menserr . "</errormsg>\n";
        $err .= "\t<scriptname>" . $nombrearchivo . "</scriptname>\n";
        $err .= "\t<scriptlinenum>" . $númlínea . "</scriptlinenum>\n";

        if (in_array($númerr, $errores_usuario)) {
            $err .= "\t<vartrace>" . wddx_serialize_value($vars, "Variables") . "</vartrace>\n";
        }
        $err .= "</errorentry>\n\n";

        // para probar
        // echo $err;

        // guardar al registro de errores, y enviarme un e-mail si hay un error crítico de usuario
        error_log($err, 3, "/usr/local/php4/error.log");
        if ($númerr == E_USER_ERROR) {
            mail("phpdev@example.com", "Error Crítico de Usuario", $err);
        }
    }

    function distancia($vect1, $vect2)
    {
        if (!is_array($vect1) || !is_array($vect2)) {
            trigger_error("Parámetros incorrectos, se esperaba una matriz", E_USER_ERROR);
            return NULL;
        }

        if (count($vect1) != count($vect2)) {
            trigger_error("Los vectores necesitan ser del mismo tamaño", E_USER_ERROR);
            return NULL;
        }

        for ($i=0; $i<count($vect1); $i++) {
            $c1 = $vect1[$i]; $c2 = $vect2[$i];
            $d = 0.0;
            if (!is_numeric($c1)) {
                trigger_error("La coordenada $i del vector 1 no es un número, se usará cero",
                                E_USER_WARNING);
                $c1 = 0.0;
            }
            if (!is_numeric($c2)) {
                trigger_error("La coordenada $i del vector 2 no es un número, se usará cero",
                                E_USER_WARNING);
                $c2 = 0.0;
            }
            $d += $c2*$c2 - $c1*$c1;
        }
        return sqrt($d);
    }

    $gestor_error_antiguo = set_error_handler("gestorErrores");

    // constante no definida, genera una advertencia
    $t = NO_ESTOY_DEFINIDA;

    // definir algunos "vectores"
    $a = array(2, 3, "foo");
    $b = array(5.5, 4.3, -1.6);
    $c = array(1, -3);

    // generar un error de usuario
    $t1 = distancia($c, $b) . "\n";

    // generar otro error de usuario
    $t2 = distancia($b, "no soy una matriz") . "\n";

    // generar una advertencia
    $t3 = distancia($a, $b) . "\n";

    ?>

# Funciones de Manejo de Errores

# Ver también

Véase también syslog().

# debug_backtrace

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

debug_backtrace — Genera el contexto de depuración

### Descripción

function debug_backtrace(int `$options` = `DEBUG_BACKTRACE_PROVIDE_OBJECT`, int `$limit` = 0): array

debug_backtrace() genera un contexto de depuración PHP.

### Parámetros

`options`

  Este argumento es una máscara de las siguientes opciones:

  Opciones para la función debug_backtrace()
  DEBUG_BACKTRACE_PROVIDE_OBJECT | Si se debe o no poblar el índice "object".
  DEBUG_BACKTRACE_IGNORE_ARGS | Si se debe o no omitir el índice "args" y por lo tanto todos los argumentos de la función/método para ahorrar memoria.

  > Nota:

  > Existen cuatro combinaciones posibles:

  > Opciones de debug_backtrace()
  > `debug_backtrace()` | Rellena los dos índices
  > `debug_backtrace(DEBUG_BACKTRACE_PROVIDE_OBJECT)`
  > `debug_backtrace(~DEBUG_BACKTRACE_PROVIDE_OBJECT)` | Omite el índice `"object"` y rellena el índice `"args"`.
  > `debug_backtrace(0)`
  > `debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS)` | Omite ambos el índice `"object"` y el índice `"args"`.
  > `debug_backtrace(~DEBUG_BACKTRACE_PROVIDE_OBJECT | DEBUG_BACKTRACE_IGNORE_ARGS)`
  > `debug_backtrace(DEBUG_BACKTRACE_PROVIDE_OBJECT|DEBUG_BACKTRACE_IGNORE_ARGS)` | Rellena el índice `"object"` y omite el índice `"args"`.

`limit`

  Este argumento puede ser utilizado para limitar el número de marcos en la pila devuelta. Por omisión (`limit`=`0`), la función devuelve todos los marcos de la pila.

### Valores devueltos

Devuelve un array de arrays asociativos. Los elementos de retorno posibles son los siguientes:

Elementos posibles de retorno de la función debug_backtrace()
Nombre | Tipo | Descripción
--- | --- | ---
function | string | El nombre de la función actual. Ver también __FUNCTION__.
line | int | El número de línea actual. Ver también __LINE__.
file | string | El nombre del fichero actual. Ver también __FILE__.
class | string | El nombre de la clase actual. Ver también __CLASS__.
object | object | El objeto actual si `DEBUG_BACKTRACE_PROVIDE_OBJECT` es proporcionado.
type | string | El tipo de clase actual. Si un método es llamado, "->" es devuelto. Si un método estático es llamado, "::" es devuelto. Si una función es llamada, nada será devuelto.
args | array | Si dentro de una función, esto lista los argumentos. Si en un fichero incluido, esto lista los ficheros incluidos. A menos que `DEBUG_BACKTRACE_IGNORE_ARGS` sea proporcionado.

### Ejemplos

Ejemplo #1 Ejemplo con debug_backtrace()

    <?php
    // filename: /tmp/a.php

    function a_test($str)
    {
      echo "\nHi: $str";
      var_dump(debug_backtrace());
    }

    a_test('friend');
    ?>

    <?php
    // filename: /tmp/b.php
    include_once '/tmp/a.php';
    ?>

Resultado de la ejecución de /tmp/b.php:

    Hi: friend
    array(2) {
      [0]=>
        array(4) {
          ["file"] => string(10) "/tmp/a.php"
          ["line"] => int(10)
          ["function"] => string(6) "a_test"
          ["args"]=>
            array(1) {
              [0] => &string(6) "friend"
            }
        }
      [1]=>
        array(4) {
          ["file"] => string(10) "/tmp/b.php"
          ["line"] => int(2)
          ["args"] =>
            array(1) {
              [0] => string(10) "/tmp/a.php"
            }
          ["function"] => string(12) "include_once"
        }
    }

### Ver también

- trigger_error() - Desencadena un error de usuario
- debug_print_backtrace() - Muestra la pila de ejecución de PHP

# debug_print_backtrace

(PHP 5, PHP 7, PHP 8)

debug_print_backtrace — Muestra la pila de ejecución de PHP

### Descripción

function debug_print_backtrace(int `$options` = 0, int `$limit` = 0): void

debug_print_backtrace() muestra la pila de ejecución de PHP. Muestra las llamadas a funciones, los ficheros incluidos/requeridos por include/require así como las llamadas a eval().

### Parámetros

`options`

  Este argumento es una máscara de las siguientes opciones:

  Opciones para debug_print_backtrace()
  DEBUG_BACKTRACE_IGNORE_ARGS | Si se deben omitir el índice "args" y, por lo tanto, todos los argumentos del método/función para preservar la memoria.

`limit`

  Este argumento puede ser utilizado para limitar el número de marcos de la pila a mostrar. Por omisión (`limit`=`0`), todos los marcos de la pila serán mostrados.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con debug_print_backtrace()

    <?php
    // fichero include.php

    function a() {
        b();
    }

    function b() {
        c();
    }

    function c(){
        debug_print_backtrace();
    }

    a();

    ?>

    <?php
    // fichero test.php
    // Este es el fichero que debe ser ejecutado

    include 'include.php';
    ?>

Resultado del ejemplo anterior es similar a:

    #0  c() called at [/tmp/include.php:10]
    #1  b() called at [/tmp/include.php:6]
    #2  a() called at [/tmp/include.php:17]
    #3  include(/tmp/include.php) called at [/tmp/test.php:3]

### Ver también

- debug_backtrace() - Genera el contexto de depuración

# error_clear_last

(PHP 7, PHP 8)

error_clear_last — Elimina el error más reciente

### Descripción

function error_clear_last(): void

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Elimina el error más reciente, haciéndolo irrecuperable con error_get_last().

### Ejemplos

Ejemplo #1 Un ejemplo de error_clear_last()

    <?php
    var_dump(error_get_last());
    error_clear_last();
    var_dump(error_get_last());

    @$a = $b;

    var_dump(error_get_last());
    error_clear_last();
    var_dump(error_get_last());
    ?>

Resultado del ejemplo anterior es similar a:

    NULL
    NULL
    array(4) {
      ["type"]=>
      int(8)
      ["message"]=>
      string(21) "Undefined variable: b"
      ["file"]=>
      string(9) "%s"
      ["line"]=>
      int(6)
    }
    NULL

### Ver también

- Constantes de errores

# error_get_last

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

error_get_last — Obtener el último error que ocurrió

### Descripción

function error_get_last(): ?array

Obtiene información sobre el último error que ocurrió.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una matriz asociativa describiendo el último error con las claves "type" (tipo), "message" (mensaje), "file" (archivo) y "line" (línea). Si el error ha sido causado por una función interna de PHP, el "message" (mensaje) comienza con su nombre. Devuelve `null` si no ha habido aún un error.

### Ejemplos

Ejemplo #1 Un ejemplo de error_get_last()

    <?php
    echo $a;
    print_r(error_get_last());
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [type] => 8
        [message] => Undefined variable: a
        [file] => C:\WWW\index.php
        [line] => 2
    )

### Ver también

- Constantes de error
- La variable $php_errormsg
- error_clear_last() - Elimina el error más reciente
- La directiva `display_errors`
- La directiva `html_errors`
- La directiva `xmlrpc_errors`

# error_log

(PHP 4, PHP 5, PHP 7, PHP 8)

error_log — Envía un mensaje de error al gestor de errores definido

### Descripción

function error_log(
string `$message`,
int `$message_type` = 0,
?string `$destination` = `null`,
?string `$additional_headers` = `null`
): bool

Envía un mensaje de error al historial de errores del servidor web o a un fichero.

### Parámetros

`message`

  El mensaje de error que debe ser almacenado.

`message_type`

  Especifica el destino del mensaje de error. Los tipos posibles de mensajes son:

  error_log() tipos de registro
  0 | `message` es enviado al historial PHP, que se basa en el historial del sistema o un fichero, dependiendo de la configuración de error_log. Esta es la opción por omisión.
  1 | `message` es enviado por email a la dirección `destination`. Este es el único tipo que utiliza el cuarto parámetro `additional_headers`.
  2 | Ya no es una opción.
  3 | `message` es añadido al fichero `destination`. No se añade automáticamente una nueva línea (retorno de carro) al final de la cadena `message`.
  4 | `message` es enviado directamente al gestor de identificación SAPI.

`destination`

  El destino. Esto depende del parámetro `message_type` descrito anteriormente.

`additional_headers`

  Los encabezados adicionales. Estos son utilizados cuando el parámetro `message_type` está definido a `1`. Este tipo de mensaje utiliza la misma función interna que la función mail().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error. Si `message_type` es cero, entonces esta función siempre retorna `true`, independientemente de si el error pudo ser registrado en el registro de eventos.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `destination` y `additional_headers` ahora son nullables.

### Ejemplos

Ejemplo #1 Ejemplos con error_log()

    <?php
    // Envía una notificación por el historial del servidor web,
    // si la conexión a la base de datos es imposible.
    if (!Ora_Logon($username, $password)) {
      error_log("Base Oracle no disponible !", 0);
    }

    // Indicar al administrador, por email, que no hay más FOO
    if (!($foo = allocate_new_foo())) {
      error_log("¡Ay!, No quedan más FOO disponibles !", 1,
      "operador@example.com");
    }

    // Otras maneras de llamar a error_log():
    error_log("¡Gran error !", 3, "/var/tmp/mis-errors.log");
    ?>

### Notas

Advertencia

La función error_log() no es segura a nivel binario. El parámetro `message` será truncado por un carácter nulo.

Sugerencia

El parámetro `message` no debe contener caracteres nulos. Tenga en cuenta que el parámetro `message` puede ser enviado hacia un fichero, un correo, syslog, etc. Utilice las funciones apropiadas de conversión/escape, base64_encode(), rawurlencode() o addslashes() antes de llamar a la función error_log().

# error_reporting

(PHP 4, PHP 5, PHP 7, PHP 8)

error_reporting — Establece el nivel de reporte de errores de PHP

### Descripción

function error_reporting(?int `$error_level` = `null`): int

error_reporting() modifica la directiva error_reporting durante la ejecución del script. PHP posee varios niveles de errores, utilizar esta función configura este nivel durante la duración (de ejecución) del script. Si el parámetro opcional `error_level` no está definido, error_reporting() retornará únicamente el nivel de reporte de errores actual.

### Parámetros

`error_level`

  El nuevo nivel error_reporting. Puede ser un campo de bits o una combinación de constantes. El uso de constantes es altamente recomendado para asegurar una compatibilidad máxima con las futuras versiones. A medida que se crean nuevos niveles de errores, los valores evolucionan, por lo que los valores antiguos ya no tienen necesariamente el mismo significado.

  Las constantes que representan los niveles de errores disponibles y la significación de estos niveles de errores se describe en el manual sobre las constantes predefinidas.

### Valores devueltos

Retorna el nivel de error_reporting antes de que sea cambiado a `error_level`

> Nota: El operador de control de errores `@` modifica el `error_level` durante la gestión de errores.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `error_level` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con error_reporting()

    <?php

    // Desactivar el reporte de errores
    error_reporting(0);

    // Reportar errores de ejecución de script
    error_reporting(E_ERROR | E_WARNING | E_PARSE);

    // Reportar E_NOTICE puede ayudar a mejorar los scripts
    // (variables no inicializadas, variables mal escritas..)
    error_reporting(E_ERROR | E_WARNING | E_PARSE | E_NOTICE);

    // Reportar todas las errores excepto E_NOTICE
    // Esta es la configuración por omisión de php.ini
    error_reporting(E_ALL & ~E_NOTICE);

    // Reportar todas las errores PHP
    error_reporting(E_ALL);

    // Reportar todas las errores PHP
    error_reporting(-1);

    // Igual que error_reporting(E_ALL);
    ini_set('error_reporting', E_ALL);

    ?>

### Notas

Sugerencia

Al pasar el valor `-1`, todas las errores posibles serán mostradas, incluso al agregar nuevos niveles y constantes en las futuras versiones de PHP. Este comportamiento es equivalente a proporcionar la constante `E_ALL`.

### Ver también

- La directiva display_errors
- La directiva html_errors
- La directiva xmlrpc_errors
- El operador de control de errores
- ini_set() - Modifica el valor de una opción de configuración

# get_error_handler

(PHP 8 >= 8.5.0)

get_error_handler — Devuelve la función de manejo de errores definida por el usuario

### Descripción

function get_error_handler(): ?callable

Devuelve la función de manejo de errores definida por el usuario, si se ha definido alguna.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la función de manejo de errores definida. Si se utiliza el gestor por defecto, se devuelve `null`.

El gestor devuelto es la función de devolución de llamada exacta que se pasó a set_error_handler() para definirla.

### Ejemplos

Ejemplo #1 Ejemplo de get_error_handler()

    <?php

    $handler = function (int $errno, string $errstr, ?string $errfile, ?int $errline) {
         echo "Error: " . $errstr . "\n";
    };

    var_dump(get_error_handler()); // NULL

    set_error_handler($handler);

    var_dump(get_error_handler() === $handler); // bool(true)

    ?>

### Notas

Sugerencia

Anteriormente a PHP 8.5.0, esta funcionalidad puede ser proporcionada por el polyfill siguiente:

    <?php
    if (!function_exists('get_error_handler')) {
        function noop_error_handler() {
        }
        function get_error_handler(): ?callable {
            $handler = set_error_handler('noop_error_handler');
            restore_error_handler();
            return $handler;
        }
    }
    ?>

### Ver también

- error_reporting() - Establece el nivel de reporte de errores de PHP
- set_error_handler() - Especifica una función de usuario como gestor de errores
- restore_error_handler() - Restaura la función anterior de manejo de errores
- trigger_error() - Desencadena un error de usuario
- constante de nivel de error

# get_exception_handler

(PHP 8 >= 8.5.0)

get_exception_handler — Devuelve la función de gestión de excepciones definida por el usuario

### Descripción

function get_exception_handler(): ?callable

Devuelve la función de gestión de excepciones definida por el usuario, si se ha definido alguna.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la función de gestión de excepciones definida. Si no se ha definido ninguna, se devuelve `null`.

El gestor devuelto es la función de devolución de llamada exacta que se pasó a set_exception_handler() para definirla.

### Ejemplos

Ejemplo #1 Ejemplo de get_exception_handler()

    <?php

    $handler = function (Throwable $ex) {
         echo "Exception: " . $ex::class . ": " . $ex->getMessage() . "\n";
    };

    var_dump(get_exception_handler()); // NULL

    set_exception_handler($handler);

    var_dump(get_exception_handler() === $handler); // bool(true)

    ?>

### Notas

Sugerencia

Antes de PHP 8.5.0, esta funcionalidad podía ser proporcionada por el siguiente polyfill:

    <?php
    if (!function_exists('get_exception_handler')) {
        function noop_exception_handler() {
        }
        function get_exception_handler(): ?callable {
            $handler = set_exception_handler('noop_exception_handler');
            restore_exception_handler();
            return $handler;
        }
    }
    ?>

### Ver también

- set_exception_handler() - Define una función de usuario para gestionar excepciones
- restore_exception_handler() - Reactiva la antigua función de gestión de excepciones
- restore_error_handler() - Restaura la función anterior de manejo de errores
- error_reporting() - Establece el nivel de reporte de errores de PHP
- Excepciones

# restore_error_handler

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

restore_error_handler — Restaura la función anterior de manejo de errores

### Descripción

function restore_error_handler(): true

Utilizada después de modificar la función de manejo de errores, gracias a set_error_handler(), restore_error_handler() permite reutilizar la versión anterior de manejo de errores (que puede ser la función PHP por defecto, o alguna otra función del usuario).

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Retorna siempre `true`.

### Ejemplos

Ejemplo #1 Ejemplo con restore_error_handler()

Si unserialize() causa un error, entonces el manejador de errores original es restaurado.

    <?php
    function unserialize_handler($errno, $errstr)
    {
    echo "Valor incorrectamente serializado.\n";
    }

    $serialized = 'foo';
    set_error_handler('unserialize_handler');
    $original = unserialize($serialized);
    restore_error_handler();
    ?>

El ejemplo anterior mostrará:

    Valor incorrectamente serializado.

### Ver también

- error_reporting() - Establece el nivel de reporte de errores de PHP
- set_error_handler() - Especifica una función de usuario como gestor de errores
- get_error_handler() - Devuelve la función de manejo de errores definida por el usuario
- restore_exception_handler() - Reactiva la antigua función de gestión de excepciones
- trigger_error() - Desencadena un error de usuario

# restore_exception_handler

(PHP 5, PHP 7, PHP 8)

restore_exception_handler — Reactiva la antigua función de gestión de excepciones

### Descripción

function restore_exception_handler(): true

restore_exception_handler() se utiliza, después del cambio de la función de gestión de excepciones con la función set_exception_handler(), para volver al antiguo gestor de excepciones (que puede ser la función interna o una función definida por el usuario).

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Retorna siempre `true`.

### Ejemplos

Ejemplo #1 Ejemplo con restore_exception_handler()

    <?php
        function exception_handler_1(Exception $e)
        {
            echo '[' . __FUNCTION__ . '] ' . $e->getMessage();
        }

        function exception_handler_2(Exception $e)
        {
            echo '[' . __FUNCTION__ . '] ' . $e->getMessage();
        }

        set_exception_handler('exception_handler_1');
        set_exception_handler('exception_handler_2');

        restore_exception_handler();

        throw new Exception('Esto utiliza el primer gestor de excepciones...');
    ?>

El ejemplo anterior mostrará:

    [exception_handler_1] Esto utiliza el primer gestor de excepciones...

### Ver también

- set_exception_handler() - Define una función de usuario para gestionar excepciones
- get_exception_handler() - Devuelve la función de gestión de excepciones definida por el usuario
- set_error_handler() - Especifica una función de usuario como gestor de errores
- restore_error_handler() - Restaura la función anterior de manejo de errores
- error_reporting() - Establece el nivel de reporte de errores de PHP

# set_error_handler

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

set_error_handler — Especifica una función de usuario como gestor de errores

### Descripción

function set_error_handler(?callable `$callback`, int `$error_levels` = `E_ALL`): ?callable

set_error_handler() selecciona la función de usuario `callback` para gestionar errores en un script.

Esta función puede ser utilizada para definir gestores de errores personalizados durante la ejecución, por ejemplo en aplicaciones que necesitan limpiar archivos/datos cuando ocurre un error crítico o cuando un error es generado en respuesta a ciertas condiciones (utilizando la función trigger_error()).

Debe recordarse que la función estándar de tratamiento de errores de PHP es completamente ignorada para los errores de tipos especificados por `error_levels` a menos que la función de retorno devuelva `false`. Los parámetros de la función error_reporting() no tendrán efecto y el gestor de errores será llamado en cualquier caso. Sin embargo, siempre es posible leer el valor actual de la configuración de error_reporting y hacer que la función de gestión de errores reaccione en consecuencia.

También debe notarse que es responsabilidad del gestor de errores detener la ejecución del script si es necesario llamando a la función exit(). Si la función del gestor de errores devuelve, la ejecución del script continuará con la instrucción siguiente a la que causó el error.

Los siguientes tipos de errores no pueden ser gestionados con esta función: `E_ERROR`, `E_PARSE`, `E_CORE_ERROR`, `E_CORE_WARNING`, `E_COMPILE_ERROR`, `E_COMPILE_WARNING` independientemente de dónde sean generados, así como la mayoría de los `E_STRICT` del archivo en el cual set_error_handler() es llamado.

Si un error ocurre antes de que el script sea ejecutado (por ejemplo una descarga de archivo), el gestor de errores personalizado no podrá ser llamado, ya que aún no está registrado.

### Parámetros

`callback`

  Si `null` es proporcionado, el gestor es reestablecido a su estado por defecto. De lo contrario, el gestor es una función de retorno con la siguiente firma:

  function handler(
  int `$errno`,
  string `$errstr`,
  string `$errfile` = ?,
  int `$errline` = ?,
  array `$errcontext` = ?
  ): bool
  `errno`
    El primer parámetro `errno`, será pasado el nivel de error, en forma de entero.
  `errstr`
    El segundo parámetro `errstr`, será pasado el mensaje de error, en forma de string.
  `errfile`
    Si el cierre acepta un tercer parámetro, `errfile`, será pasado el nombre del archivo en el cual el error fue identificado, en forma de string.
  `errline`
    Si el cierre acepta un cuarto parámetro, `errline`, será pasado el número de línea en la cual el error fue identificado, en forma de entero.
  `errcontext`
    Si el cierre acepta un quinto parámetro, `errcontext`, será pasado como un array que apunta a la tabla de símbolos activos en el momento en que el error ocurrió. En otras palabras, `errcontext` contiene un array con todas las variables que existían cuando el error fue generado. Los gestores de errores de usuario no deben modificar el contexto de error.
    Advertencia

    Este parámetro es OBSOLETO a partir de PHP 7.2.0, y ELIMINADO a partir de PHP 8.0.0. Si la función definida este parámetro sin valor por defecto, un error de "too few arguments" será generado al llamarla.

  Si la función devuelve `false`, entonces el gestor de errores normal continúa.

`error_levels`

  Sirve como máscara para llamar a la función `callback` de la misma forma que la opción de configuración error_reporting controla los errores que son mostrados. Sin la máscara, `callback` será llamado para todos los errores, independientemente del valor de error_reporting.

### Valores devueltos

Devuelve el último gestor de errores (si existe) en forma de callable. Si el gestor de errores interno es utilizado, `null` es devuelto.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `errcontext` ha sido eliminado, y ya no será pasado a los cierres de usuario.
7.2.0 | `errcontext` se ha vuelto obsoleto. El uso de este parámetro emite una notificación `E_DEPRECATED`.

### Ejemplos

Ejemplo #1 Gestor de errores con set_error_handler() y trigger_error()

El ejemplo siguiente ilustra la intercepción de errores internos con generación de error y su explotación en una función de usuario:

    <?php
    // Gestor de errores
    function myErrorHandler($errno, $errstr, $errfile, $errline)
    {
       if (!(error_reporting() & $errno)) {
            // Este código de error no está incluido en error_reporting(), por lo tanto continúa
            // hasta el gestor de errores estándar de PHP
            return false;
        }

        // $errstr debe ser posiblemente escapado:
        $errstr = htmlspecialchars($errstr);

        switch ($errno) {
        case E_USER_ERROR:
            echo "<b>MI ERROR</b> [$errno] $errstr<br />\n";
            echo "  Error fatal en la línea $errline en el archivo $errfile";
            echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
            echo "Detención...<br />\n";
            exit(1);

        case E_USER_WARNING:
            echo "<b>MI ALERTA</b> [$errno] $errstr<br />\n";
            break;

        case E_USER_NOTICE:
            echo "<b>MI AVISO</b> [$errno] $errstr<br />\n";
            break;

        default:
            echo "Tipo de error desconocido: [$errno] $errstr<br />\n";
            break;
        }

        /* No ejecutar el gestor interno de PHP */
        return true;
    }

    // Función para probar la gestión de error
    function scale_by_log($vect, $scale)
    {
        if (!is_numeric($scale) || $scale <= 0) {
            trigger_error("log(x) para x <= 0 es indefinido, usted usó: scale = $scale", E_USER_ERROR);
        }

        if (!is_array($vect)) {
            trigger_error("Tipo de entrada incorrecto, se esperaba un array de valores", E_USER_WARNING);
            return null;
        }

        $temp = array();
        foreach($vect as $pos => $value) {
            if (!is_numeric($value)) {
                trigger_error("El valor en la posición $pos no es un número, se utiliza 0 (cero)", E_USER_NOTICE);
                $value = 0;
            }
            $temp[$pos] = log($scale) * $value;
        }
        return $temp;
      }

    // Configuración del gestor de errores
    $old_error_handler = set_error_handler("myErrorHandler");

    // Generación de algunos errores. Comencemos creando un array
    echo "vector a\n";
    $a = array(2, 3, "foo", 5.5, 43.3, 21.11);
    print_r($a);

    // Generemos ahora un segundo array
    echo "----\nvector b - un aviso (b = log(PI) * a)\n";
    /* Valor en la posición $pos no es un número, se utiliza 0 (cero) */
    $b = scale_by_log($a, M_PI);
    print_r($b);

    // Esto es un problema, hemos utilizado una cadena en lugar de un array
    echo "----\nvector c - una advertencia\n";
    /* Tipo de entrada incorrecto, se esperaba un array de valores */
    $c = scale_by_log("no un array", 2.3);
    var_dump($c); // NULL

    // Esto es un error crítico: el logaritmo de cero o de un número negativo es indefinido
    echo "----\nvector d - error fatal\n";
    /* log(x) para x <= 0 es indefinido, usted usó: scale = $scale" */
    $d = scale_by_log($a, -2.5);
    var_dump($d); // Nunca alcanzado
    ?>

Resultado del ejemplo anterior es similar a:

    vector a
    Array
    (
        [0] => 2
        [1] => 3
        [2] => foo
        [3] => 5.5
        [4] => 43.3
        [5] => 21.11
    )
    ----
    vector b - un aviso (b = log(PI) * a)
    <b>MI AVISO</b> [1024] El valor en la posición 2 no es un número, se utiliza 0 (cero)<br />
    Array
    (
        [0] => 2.2894597716988
        [1] => 3.4341896575482
        [2] => 0
        [3] => 6.2960143721717
        [4] => 49.566804057279
        [5] => 24.165247890281
    )
    ----
    vector c - una advertencia
    <b>MI ALERTA</b> [512] Entrada incorrecta, se esperaba un array de valores<br />
    NULL
    ----
    vector d - error fatal
    <b>MI ERROR</b> [256] log(x) para x <= 0 es indefinido, usted usó: scale = -2.5<br />
    Error fatal en la línea 36 en el archivo trigger_error.php, PHP 4.0.2 (Linux)<br />
    Abandono...<br />

### Ver también

- ErrorException
- error_reporting() - Establece el nivel de reporte de errores de PHP
- restore_error_handler() - Restaura la función anterior de manejo de errores
- get_error_handler() - Devuelve la función de manejo de errores definida por el usuario
- trigger_error() - Desencadena un error de usuario
- Constantes de nivel de error

# set_exception_handler

(PHP 5, PHP 7, PHP 8)

set_exception_handler — Define una función de usuario para gestionar excepciones

### Descripción

function set_exception_handler(?callable `$callback`): ?callable

set_exception_handler() define el manejador de excepciones por defecto si una excepción no es capturada con un bloque de prueba/atrapa. La ejecución se detendrá después de la llamada a la función `callback`.

### Parámetros

`callback`

  La función a llamar cuando ocurre una excepción no capturada. Esta función de gestión debe aceptar un argumento, que será el objeto Throwable que fue lanzado. Las clases Error y Exception implementan la interfaz Throwable. Esta es la firma del manejador:

  function handler(Throwable `$ex`): void

  `null` puede ser pasado en su lugar, para reinicializar este manejador a su estado inicial.

### Valores devueltos

Retorna el manejador previamente definido o `null` en caso de error. Si ningún manejador fue previamente definido, `null` es también retornado.

### Ejemplos

Ejemplo #1 Ejemplo con set_exception_handler()

    <?php
    function exception_handler(Throwable $exception) {
      echo "Excepción no capturada: " , $exception->getMessage(), "\n";
    }

    set_exception_handler('exception_handler');

    throw new Exception('Excepción no capturada');
    echo "No ejecutado\n";
    ?>

### Ver también

- get_exception_handler() - Devuelve la función de gestión de excepciones definida por el usuario
- restore_exception_handler() - Reactiva la antigua función de gestión de excepciones
- restore_error_handler() - Restaura la función anterior de manejo de errores
- error_reporting() - Establece el nivel de reporte de errores de PHP
- Las excepciones

# trigger_error

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

trigger_error — Desencadena un error de usuario

### Descripción

function trigger_error(string `$message`, int `$error_level` = `E_USER_NOTICE`): true

trigger_error() se utiliza para desencadenar un error de usuario. También puede ser utilizada en conjunción con un manejador de errores interno, o un manejador de errores de usuario que haya sido seleccionado como manejador de errores con set_error_handler().

trigger_error() es práctico cuando se debe generar una respuesta particular durante la ejecución.

### Parámetros

`message`

  El mensaje de error designado para este error. Está limitado en longitud a 1024 bytes. Todos los caracteres después de los 1024 bytes serán ignorados.

`error_level`

  El tipo de error designado para este error. Solo funciona con la familia de constantes `E_USER_*` y será por omisión `E_USER_NOTICE`.

  Advertencia

  Pasar `E_USER_ERROR` como `error_level` está ahora deprecado. Lance una Exception o llame a exit() en su lugar.

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

Esta función lanza una ValueError si el `error_level` no es uno de los `E_USER_ERROR`, `E_USER_WARNING`, `E_USER_NOTICE`, `E_USER_DEPRECATED`.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Pasar `E_USER_ERROR` como `error_level` está ahora deprecado. Lance una Exception o llame a exit() en su lugar.
8.4.0 | La función tiene ahora un tipo de retorno true en lugar de bool.
8.0.0 | La función lanza ahora una ValueError si se especifica un `error_level` inválido. Anteriormente, devolvía `false`.

### Ejemplos

Ejemplo #1 Ejemplo con trigger_error()

Ver set_error_handler() para un ejemplo más sustancial.

    <?php
    $password = $_POST['password'] ?? '';
    if ($password === '') {
      trigger_error("Usar una contraseña vacía no es seguro", E_USER_WARNING);
    }
    $hash = password_hash($password, PASSWORD_DEFAULT);
    ?>

### Notas

Advertencia

Las entidades HTML contenidas en el parámetro `message` no son escapadas. Utilice la función htmlentities() en el mensaje si el error debe ser mostrado en un navegador.

### Ver también

- error_reporting() - Establece el nivel de reporte de errores de PHP
- set_error_handler() - Especifica una función de usuario como gestor de errores
- restore_error_handler() - Restaura la función anterior de manejo de errores
- Las constantes de nivel de error
- El atributo Deprecated

# user_error

(PHP 4, PHP 5, PHP 7, PHP 8)

user_error — Alias de trigger_error()

### Descripción

Esta función es un alias de: trigger_error().

## Tabla de contenidos

- debug_backtrace — Genera el contexto de depuración
- debug_print_backtrace — Muestra la pila de ejecución de PHP
- error_clear_last — Elimina el error más reciente
- error_get_last — Obtener el último error que ocurrió
- error_log — Envía un mensaje de error al gestor de errores definido
- error_reporting — Establece el nivel de reporte de errores de PHP
- get_error_handler — Devuelve la función de manejo de errores definida por el usuario
- get_exception_handler — Devuelve la función de gestión de excepciones definida por el usuario
- restore_error_handler — Restaura la función anterior de manejo de errores
- restore_exception_handler — Reactiva la antigua función de gestión de excepciones
- set_error_handler — Especifica una función de usuario como gestor de errores
- set_exception_handler — Define una función de usuario para gestionar excepciones
- trigger_error — Desencadena un error de usuario
- user_error — Alias de trigger_error

- Instalación/Configuración
  - Configuración en tiempo de ejecución
- Constantes predefinidas
- Ejemplos
- Funciones de Manejo de Errores
  - debug_backtrace — Genera el contexto de depuración
  - debug_print_backtrace — Muestra la pila de ejecución de PHP
  - error_clear_last — Elimina el error más reciente
  - error_get_last — Obtener el último error que ocurrió
  - error_log — Envía un mensaje de error al gestor de errores definido
  - error_reporting — Establece el nivel de reporte de errores de PHP
  - get_error_handler — Devuelve la función de manejo de errores definida por el usuario
  - get_exception_handler — Devuelve la función de gestión de excepciones definida por el usuario
  - restore_error_handler — Restaura la función anterior de manejo de errores
  - restore_exception_handler — Reactiva la antigua función de gestión de excepciones
  - set_error_handler — Especifica una función de usuario como gestor de errores
  - set_exception_handler — Define una función de usuario para gestionar excepciones
  - trigger_error — Desencadena un error de usuario
  - user_error — Alias de trigger_error

# Interfaz de función externa (Foreign Function Interface)

# Introducción

Esta extensión permite cargar bibliotecas compartidas (.DLL o .so), llamar a funciones C y acceder a estructuras de datos C desde PHP, sin necesidad de conocer la API de extensión Zend, y sin tener que aprender un tercer lenguaje "intermedio". La API pública se implementa en forma de una clase única FFI con varios métodos estáticos (algunos de los cuales pueden ser llamados dinámicamente), y métodos de objeto sobrecargados, que realizan la interacción real con los datos C.

Precaución

La extensión FFI es peligrosa, ya que permite interfaces con el sistema a un nivel muy bajo. Solo debe ser utilizada por desarrolladores con conocimiento práctico del lenguaje C y de las API C utilizadas. Para minimizar los riesgos, el uso de la API FFI puede ser restringido con la directiva php.ini ffi.enable.

> Nota: La extensión FFI no hace obsoleta la API de extensión clásica de PHP; simplemente se proporciona para la interfaz ad-hoc con funciones y estructuras de datos C.

Sugerencia

Actualmente, el acceso a las estructuras de datos FFI es significativamente (aproximadamente 2 veces) más lento que el acceso a los arrays y objetos nativos de PHP. Por lo tanto, no es útil utilizar la extensión FFI para la velocidad; sin embargo, puede ser aconsejable utilizarla para reducir el uso de memoria.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución

## Requerimientos

Esta extensión requiere que la » biblioteca libffi esté instalada.

## Instalación

Para activar la extensión FFI, PHP debe ser configurado con --with-ffi.

Los usuarios de Windows deben incluir php_ffi.dll en php.ini para activar la extensión FFI.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

FFI Opciones de configuración
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
ffi.enable | "preload" | `INI_SYSTEM` |
ffi.preload | "" | `INI_SYSTEM` |

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`ffi.enable` string
  Permite activar (`"true"`) o desactivar (`"false"`) el uso de la API FFI, o restringirlo únicamente a la interfaz CLI SAPI y a los ficheros pre-cargados (`"preload"`). Las restricciones de la API FFI afectan solo a la clase FFI, pero no a las funciones sobrecargadas de los objetos FFI\CData. Esto significa que es posible crear ciertos objetos FFI\CData en ficheros pre-cargados y luego utilizarlos directamente en scripts PHP.
`ffi.preload` string
  Permite la pre-carga de las ligaduras FFI al inicio, lo cual no es posible con FFI::load() si opcache.preload_user está definido. Esta directiva acepta una lista de nombres de ficheros delimitada por `DIRECTORY_SEPARATOR`. Las ligaduras pre-cargadas son accesibles llamando a FFI::scope().

# Ejemplos

## Tabla de contenidos

- Uso básico de FFI
- Funciones de retrollamada
- Un ejemplo completo de PHP/FFI/precarga

## Uso básico de FFI

Antes de profundizar en los detalles de la API FFI, echemos un vistazo a algunos ejemplos que demuestran la simplicidad de uso de la API FFI para tareas comunes.

> Nota: Algunos de estos ejemplos requieren libc.so.6 y por lo tanto no funcionarán en sistemas donde esta biblioteca no esté disponible.

Ejemplo #1 Llamada a una función desde una biblioteca compartida

    <?php
    // crea un objeto FFI, cargando la libc y exportando la función printf()
    $ffi = FFI::cdef(
        "int printf(const char *format, ...);", // Declaración C regular
        "libc.so.6");
    // llama a la función printf() de C
    $ffi->printf("Hello %s!\n", "world");
    ?>

El ejemplo anterior mostrará:

    Hello world!

> Nota: Tenga en cuenta que algunas funciones C requieren convenciones de llamada específicas, por ejemplo `__fastcall`, `__stdcall` o `__vectorcall`.

Ejemplo #2 Llamada a una función, devolviendo una estructura a través de un argumento

    <?php
    // crea la ligadura gettimeofday()
    $ffi = FFI::cdef("
        typedef unsigned int time_t;
        typedef unsigned int suseconds_t;

        struct timeval {
            time_t      tv_sec;
            suseconds_t tv_usec;
        };

        struct timezone {
            int tz_minuteswest;
            int tz_dsttime;
        };

        int gettimeofday(struct timeval *tv, struct timezone *tz);
    ", "libc.so.6");
    // crea las estructuras de datos C
    $tv = $ffi->new("struct timeval");
    $tz = $ffi->new("struct timezone");
    // llama a la función gettimeofday() de C
    var_dump($ffi->gettimeofday(FFI::addr($tv), FFI::addr($tz)));
    // accede a los campos de la estructura de datos C
    var_dump($tv->tv_sec);
    // imprime toda la estructura de datos C
    var_dump($tz);
    ?>

Resultado del ejemplo anterior es similar a:

    int(0)
    int(1555946835)
    object(FFI\CData:struct timezone)#3 (2) {
      ["tz_minuteswest"]=>
      int(0)
      ["tz_dsttime"]=>
      int(0)
    }

Ejemplo #3 Acceso a variables C existentes

    <?php
    // crea un objeto FFI, cargando la libc y exportando la variable errno
    $ffi = FFI::cdef(
        "int errno;", // Declaración C regular
        "libc.so.6");
    // imprime el valor errno de C
    var_dump($ffi->errno);
    ?>

El ejemplo anterior mostrará:

    int(0)

Ejemplo #4 Creación y modificación de variables C

    <?php
    // crea una nueva variable C de tipo int
    $x = FFI::new("int");
    var_dump($x->cdata);

    // asignación simple
    $x->cdata = 5;
    var_dump($x->cdata);

    // asignación compuesta
    $x->cdata += 2;
    var_dump($x->cdata);
    ?>

El ejemplo anterior mostrará:

    int(0)
    int(5)
    int(7)

Ejemplo #5 Trabajar con arrays C

    <?php
    // crea una estructura de datos en C
    $a = FFI::new("long[1024]");
    // modificación de la estructura como con un array PHP normal
    for ($i = 0; $i < count($a); $i++) {
        $a[$i] = $i;
    }
    var_dump($a[25]);
    $sum = 0;
    foreach ($a as $n) {
        $sum += $n;
    }
    var_dump($sum);
    var_dump(count($a));
    var_dump(FFI::sizeof($a));
    ?>

El ejemplo anterior mostrará:

    int(25)
    int(523776)
    int(1024)
    int(8192)

Ejemplo #6 Trabajar con enums en C

    <?php
    $a = FFI::cdef('typedef enum _zend_ffi_symbol_kind {
        ZEND_FFI_SYM_TYPE,
        ZEND_FFI_SYM_CONST = 2,
        ZEND_FFI_SYM_VAR,
        ZEND_FFI_SYM_FUNC
    } zend_ffi_symbol_kind;
    ');
    var_dump($a->ZEND_FFI_SYM_TYPE);
    var_dump($a->ZEND_FFI_SYM_CONST);
    var_dump($a->ZEND_FFI_SYM_VAR);
    ?>

El ejemplo anterior mostrará:

    int(0)
    int(2)
    int(3)

## Funciones de retrollamada

Es posible asignar una clausura PHP a una variable nativa de tipo puntero de función o pasarla como argumento de función:

Ejemplo #1 Asignación de una Closure PHP a un puntero de función C

    <?php
    $zend = FFI::cdef("
        typedef int (*zend_write_func_t)(const char *str, size_t str_length);
        extern zend_write_func_t zend_write;
    ");

    echo "Hello World 1!\n";

    $orig_zend_write = clone $zend->zend_write;
    $zend->zend_write = function($str, $len) {
        global $orig_zend_write;
        $orig_zend_write("{\n\t", 3);
        $ret = $orig_zend_write($str, $len);
        $orig_zend_write("}\n", 2);
        return $ret;
    };
    echo "Hello World 2!\n";
    $zend->zend_write = $orig_zend_write;
    echo "Hello World 3!\n";
    ?>

El ejemplo anterior mostrará:

    Hello World 1!
    {
            Hello World 2!
    }
    Hello World 3!

Aunque esto funciona, esta funcionalidad no es soportada por todas las plataformas libffi, no es eficiente y provoca fugas de recursos al final de la petición.
Sugerencia

Por lo tanto, se recomienda minimizar el uso de las funciones de retrollamada PHP.

## Un ejemplo completo de PHP/FFI/precarga

php.ini

    ffi.enable=preload
    opcache.preload=preload.php

preload.php

    <?php
    FFI::load(__DIR__ . "/dummy.h");
    opcache_compile_file(__DIR__ . "/dummy.php");
    ?>

dummy.h

    #define FFI_SCOPE "DUMMY"
    #define FFI_LIB "libc.so.6"

    int printf(const char *format, ...);

dummy.php

    <?php
    final class Dummy {
        private static $ffi = null;
        function __construct() {
            if (is_null(self::$ffi)) {
                self::$ffi = FFI::scope("DUMMY");
            }
        }
        function printf($format, ...$args) {
           return (int) self::$ffi->printf($format, ...$args);
        }
    }
    ?>

test.php

    <?php
    $d = new Dummy();
    $d->printf("Hello %s!\n", "world");
    ?>

# Interfaz principal para el código C y los datos

(PHP 7 >= 7.4.0, PHP 8)

## Introducción

Los objetos de esta clase son creados por los métodos de fábrica FFI::cdef(), FFI::load() o FFI::scope(). Las variables C definidas están disponibles como propiedades de la instancia FFI, y las funciones C definidas están disponibles como métodos de la instancia FFI. Los tipos C declarados pueden ser utilizados para crear nuevas estructuras de datos C utilizando FFI::new() y FFI::type().

El análisis de las definiciones FFI y la carga de las bibliotecas compartidas pueden llevar mucho tiempo. No es útil hacerlo en cada solicitud HTTP en un entorno Web. Sin embargo, es posible precargar las definiciones FFI y las bibliotecas al inicio de PHP, e instanciar los objetos FFI cuando sea necesario. Los archivos de encabezado pueden ser extendidos con definiciones `FFI_SCOPE` especiales (por ejemplo `#define FFI_SCOPE "foo"`; el ámbito por omisión es "C") y luego cargados por FFI::load() durante la precarga. Esto conduce a la creación de una ligadura persistente, que estará disponible para todas las solicitudes siguientes a través de FFI::scope(). Consulte el ejemplo completo PHP/FFI/preloading para más detalles.

Es posible precargar más de un archivo de encabezado C en el mismo ámbito.

## Sinopsis de la Clase

final class FFI {
/* Constantes */
public const int __BIGGEST_ALIGNMENT__;
/* Métodos */
public static function addr(FFI\CData `&$ptr`): FFI\CData
public static function alignof(FFI\CData|FFI\CType `&$ptr`): int
public static function arrayType(FFI\CType `$type`, array `$dimensions`): FFI\CType
public function cast(FFI\CType|string `$type`, FFI\CData|int|float|bool|null `&$ptr`): ?FFI\CData
public static function cdef(string `$code` = "", ?string `$lib` = `null`): FFI
public static function free(FFI\CData `&$ptr`): void
public static function isNull(FFI\CData `&$ptr`): bool
public static function load(string `$filename`): ?FFI
public static function memcmp(string|FFI\CData `&$ptr1`, string|FFI\CData `&$ptr2`, int `$size`): int
public static function memcpy(FFI\CData `&$to`, FFI\CData|string `&$from`, int `$size`): void
public static function memset(FFI\CData `&$ptr`, int `$value`, int `$size`): void
public function new(FFI\CType|string `$type`, bool `$owned` = `true`, bool `$persistent` = `false`): ?FFI\CData
public static function scope(string `$name`): FFI
public static function sizeof(FFI\CData|FFI\CType `&$ptr`): int
public static function string(FFI\CData `&$ptr`, ?int `$size` = `null`): string
public function type(string `$type`): ?FFI\CType
public static function typeof(FFI\CData `&$ptr`): FFI\CType
}

## Constantes predefinidas

`FFI::__BIGGEST_ALIGNMENT__`

# FFI::addr

(PHP 7 >= 7.4.0, PHP 8)

FFI::addr — Crea un puntero no gestionado hacia datos C

### Descripción

public static function FFI::addr(FFI\CData `&$ptr`): FFI\CData

Crea un puntero no gestionado hacia los datos C representados por el elemento FFI\CData. La fuente `ptr` debe sobrevivir al puntero resultante. Esta función es principalmente útil para transmitir argumentos a funciones C a través de un puntero.

### Parámetros

`ptr`
  El gestor del puntero hacia una estructura de datos C.

### Valores devueltos

Devuelve el objeto FFI\CData recién creado.

# FFI::alignof

(PHP 7 >= 7.4.0, PHP 8)

FFI::alignof — Recupera el alineamiento

### Descripción

public static function FFI::alignof(FFI\CData|FFI\CType `&$ptr`): int

Recupera el alineamiento del objeto FFI\CData o FFI\CType dado.

### Parámetros

`ptr`
  El identificador de la data o del tipo C.

### Valores devueltos

Devuelve el alineamiento del objeto FFI\CData o FFI\CType dado.

# FFI::arrayType

(PHP 7 >= 7.4.0, PHP 8)

FFI::arrayType — Construye dinámicamente un nuevo tipo de array C

### Descripción

public static function FFI::arrayType(FFI\CType `$type`, array `$dimensions`): FFI\CType

Construye dinámicamente un nuevo tipo de array C con elementos de tipo definido por `type`, y dimensiones especificadas por `dimensions`. En el siguiente ejemplo, `$t1` y `$t2` son tipos de array equivalentes:

    <?php
    $t1 = FFI::type("int[2][3]");
    $t2 = FFI::arrayType(FFI::type("int"), [2, 3]);
    ?>

### Parámetros

`type`
  Una declaración C válida como string, o una instancia de FFI\CType que ya ha sido creada.
`dimensions`
  Las dimensiones del tipo como array.

### Valores devueltos

Devuelve el objeto FFI\CType recién creado.

# FFI::cast

(PHP 7 >= 7.4.0, PHP 8)

FFI::cast — Realiza una conversión de tipo C

### Descripción

public function FFI::cast(FFI\CType|string `$type`, FFI\CData|int|float|bool|null `&$ptr`): ?FFI\CData

FFI::cast() crea un nuevo objeto FFI\CData que hace referencia a la misma estructura de datos C, pero que está asociada a un tipo diferente. El objeto resultante no posee los datos C y la fuente `ptr` debe sobrevivir al resultado. El tipo C puede ser especificado como string con cualquier declaración de tipo C válida o como objeto FFI\CType, creado previamente. Cualquier tipo declarado para la instancia está permitido.

### Parámetros

`type`
  Una declaración C válida como string, o una instancia de FFI\CType que ya ha sido creada.
`ptr`
  El gestor del puntero de una estructura de datos C.

### Valores devueltos

Devuelve el objeto FFI\CData recién creado.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | La llamada estática a FFI::cast() ahora está obsoleta.

# FFI::cdef

(PHP 7 >= 7.4.0, PHP 8)

FFI::cdef — Crea un nuevo objeto FFI

### Descripción

public static function FFI::cdef(string `$code` = "", ?string `$lib` = `null`): FFI

Crea un nuevo objeto FFI.

### Parámetros

`code`
  Un string que contiene una secuencia de declaraciones en lenguaje C ordinario (tipos, estructuras, funciones, variables, etc). De hecho, este string puede ser copiado y pegado desde ficheros de encabezado C.

  > Nota: Las directivas del preprocesador C no son soportadas, es decir, `#include`, `#define` y las macros CPP no funcionan.

`lib`
  El nombre de un fichero de biblioteca compartida, para cargar y enlazar con las definiciones.

  > Nota: Si `lib` es omitido o `null`, las plataformas que soportan `RTLD_DEFAULT` intentan buscar los símbolos declarados en `code` en el ámbito global. Los otros sistemas no lograrán resolver estos símbolos.

### Valores devueltos

Devuelve el objeto FFI recién creado.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Las funciones C que devuelven `void` devuelven un null PHP en lugar de FFI\CType::TYPE_VOID.
8.0.0 | `lib` es ahora nullable.

# FFI::free

(PHP 7 >= 7.4.0, PHP 8)

FFI::free — Libera una estructura de datos no gestionada

### Descripción

public static function FFI::free(FFI\CData `&$ptr`): void

Libera manualmente una estructura de datos no gestionada creada previamente.

### Parámetros

`ptr`
  El gestor del puntero no gestionado de una estructura de datos C.

### Valores devueltos

No se retorna ningún valor.

# FFI::isNull

(PHP 7 >= 7.4.0, PHP 8)

FFI::isNull — Verifica si un objeto FFI\CData es un puntero nulo

### Descripción

public static function FFI::isNull(FFI\CData `&$ptr`): bool

Verifica si un objeto FFI\CData es un puntero nulo.

### Parámetros

`ptr`
  El gestor del puntero hacia una estructura de datos C.

### Valores devueltos

Devuelve si un objeto FFI\CData es un puntero nulo.

# FFI::load

(PHP 7 >= 7.4.0, PHP 8)

FFI::load — Carga las declaraciones C desde un archivo de encabezado C

### Descripción

public static function FFI::load(string `$filename`): ?FFI

Carga las declaraciones C desde un archivo de encabezado C. Es posible especificar las bibliotecas compartidas que deben ser cargadas, utilizando definiciones especiales `FFI_LIB` en el archivo de encabezado C cargado.

### Parámetros

`filename`
  El nombre de un archivo de encabezado C. Las directivas del preprocesador C no son soportadas, es decir, `#include`, `#define` y las macros CPP no funcionan, excepto en los casos particulares enumerados a continuación. El archivo de encabezado debería contener una declaración `#define` para la variable `FFI_SCOPE`, por ejemplo: `#define FFI_SCOPE "MYLIB"`. Consulte la introducción de la clase para más detalles. El archivo de encabezado puede contener una declaración `#define` para la variable `FFI_LIB` para especificar la biblioteca que expone. Si se trata de una biblioteca del sistema, solo se requiere el nombre del archivo, por ejemplo: `#define FFI_LIB "libc.so.6"`. Si se trata de una biblioteca personalizada, se requiere una ruta relativa, por ejemplo: `#define FFI_LIB "./mylib.so"`.

### Valores devueltos

Devuelve el objeto FFI recién creado, o `null` en caso de fallo.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | FFI::load() ahora está permitido en los scripts de precarga cuando el usuario del sistema actual es el mismo que el definido en la directiva de configuración `opcache.preload_user`.

### Ver también

- FFI::scope() - Instancia un objeto FFI con las declaraciones C analizadas durante la precarga

# FFI::memcmp

(PHP 7 >= 7.4.0, PHP 8)

FFI::memcmp — Comparación de zonas de memoria

### Descripción

public static function FFI::memcmp(string|FFI\CData `&$ptr1`, string|FFI\CData `&$ptr2`, int `$size`): int

Compara los `size` bytes de las zonas de memoria `ptr1` y `ptr2`. `ptr1` y `ptr2` pueden ser estructuras de datos nativas (FFI\CData) o strings PHP.

### Parámetros

`ptr1`
  Inicio de una zona de memoria.
`ptr2`
  El inicio de otra zona de memoria.
`size`
  El número de bytes a comparar.

### Valores devueltos

Devuelve un valor inferior a `0` si el contenido de la zona de memoria que comienza en `ptr1` se considera menor que el contenido de la zona de memoria que comienza en `ptr2`, un valor superior a `0` si el contenido de la primera zona de memoria se considera mayor que el de la segunda, y `0` si son iguales.

# FFI::memcpy

(PHP 7 >= 7.4.0, PHP 8)

FFI::memcpy — Copia de una zona de memoria en otra

### Descripción

public static function FFI::memcpy(FFI\CData `&$to`, FFI\CData|string `&$from`, int `$size`): void

Copia `size` bytes de la zona de memoria `from` hacia la zona de memoria `to`.

### Parámetros

`to`
  Inicio de la zona de memoria a copiar.
`from`
  El inicio de la zona de memoria donde la copia debe ser efectuada.
`size`
  El número de bytes a copiar.

### Valores devueltos

No se retorna ningún valor.

# FFI::memset

(PHP 7 >= 7.4.0, PHP 8)

FFI::memset — Rellena una zona de memoria

### Descripción

public static function FFI::memset(FFI\CData `&$ptr`, int `$value`, int `$size`): void

Rellena `size` bytes de la zona de memoria apuntada por `ptr` con el byte dado `value`.

### Parámetros

`ptr`
  Inicio de la zona de memoria a rellenar.
`value`
  El byte a rellenar.
`size`
  El número de bytes a rellenar.

### Valores devueltos

No se retorna ningún valor.

# FFI::new

(PHP 7 >= 7.4.0, PHP 8)

FFI::new — Crea una estructura de datos C

### Descripción

public function FFI::new(FFI\CType|string `$type`, bool `$owned` = `true`, bool `$persistent` = `false`): ?FFI\CData

Crea una estructura de datos nativa del tipo C dado. Cualquier tipo declarado para la instancia está permitido.

### Parámetros

`type`
  `type` es una declaración C válida como string, o una instancia de FFI\CType que ya ha sido creada.
`owned`
  Creación de datos gestionados o no gestionados. Los datos gestionados viven con el objeto FFI\CData devuelto, y son liberados cuando la última referencia a este objeto es liberada por el conteo de referencias ordinario de PHP o el recolector de basura. Los datos no gestionados deben ser liberados llamando a FFI::free(), cuando ya no sean necesarios.
`persistent`
  Asignar la estructura de datos C de manera permanente en el montón del sistema (utilizando malloc()), o en el montón de las peticiones PHP (utilizando emalloc()).

### Valores devueltos

Devuelve el objeto FFI\CData recién creado, o `null` en caso de fallo.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | La llamada estática a FFI::new() ahora está obsoleta.

# FFI::scope

(PHP 7 >= 7.4.0, PHP 8)

FFI::scope — Instancia un objeto FFI con las declaraciones C analizadas durante la precarga

### Descripción

public static function FFI::scope(string `$name`): FFI

Instancia un objeto FFI con las declaraciones C analizadas durante la precarga.

El método FFI::scope() puede ser llamado varias veces para el mismo ámbito. Varias referencias al mismo ámbito pueden ser cargadas al mismo tiempo.

### Parámetros

`name`
  El nombre del ámbito definido por una definición especial `FFI_SCOPE`.

### Valores devueltos

Devuelve el objeto FFI recién creado.

### Ver también

- FFI::load() - Carga las declaraciones C desde un archivo de encabezado C

# FFI::sizeof

(PHP 7 >= 7.4.0, PHP 8)

FFI::sizeof — Recupera el tamaño de los datos o tipos C

### Descripción

public static function FFI::sizeof(FFI\CData|FFI\CType `&$ptr`): int

Devuelve el tamaño del objeto FFI\CData o FFI\CType objeto.

### Parámetros

`ptr`
  El gestor de la data o del tipo C.

### Valores devueltos

Tamaño de la zona de memoria apuntada por `ptr`.

# FFI::string

(PHP 7 >= 7.4.0, PHP 8)

FFI::string — Crea una string PHP a partir de una zona de memoria

### Descripción

public static function FFI::string(FFI\CData `&$ptr`, ?int `$size` = `null`): string

Crea una string PHP a partir de `size` bytes de la zona de memoria apuntada por `ptr`.

### Parámetros

`ptr`
  El inicio de la zona de memoria a partir de la cual crear una string.
`size`
  El número de bytes a copiar en string. Si `size` es omitido o `null`, `ptr` debe ser un array de caracteres C de `char` C con terminación nula.

### Valores devueltos

La string PHP recién creada.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `size` es ahora nullable; anteriormente, su valor por omisión era `0`.

# FFI::type

(PHP 7 >= 7.4.0, PHP 8)

FFI::type — Crea un objeto FFI\CType a partir de una declaración C

### Descripción

public function FFI::type(string `$type`): ?FFI\CType

Esta función crea y devuelve un objeto FFI\CType para el string dado que contiene una declaración de tipo C. Cualquier tipo declarado para la instancia está permitido.

### Parámetros

`type`
  Una declaración C válida como string.

### Valores devueltos

Devuelve el objeto FFI\CType recién creado, o `null` en caso de fallo.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | La llamada estática de FFI::type() está ahora obsoleta.

# FFI::typeof

(PHP 7 >= 7.4.0, PHP 8)

FFI::typeof — Recupera el FFI\CType de FFI\CData

### Descripción

public static function FFI::typeof(FFI\CData `&$ptr`): FFI\CType

Recupera el objeto FFI\CType que representa el tipo del objeto FFI\CData dado.

### Parámetros

`ptr`
  El gestor del puntero hacia una estructura de datos C.

### Valores devueltos

Devuelve el objeto FFI\CType que representa el tipo del objeto FFI\CData dado.

## Tabla de contenidos

- FFI::addr — Crea un puntero no gestionado hacia datos C
- FFI::alignof — Recupera el alineamiento
- FFI::arrayType — Construye dinámicamente un nuevo tipo de array C
- FFI::cast — Realiza una conversión de tipo C
- FFI::cdef — Crea un nuevo objeto FFI
- FFI::free — Libera una estructura de datos no gestionada
- FFI::isNull — Verifica si un objeto FFI\CData es un puntero nulo
- FFI::load — Carga las declaraciones C desde un archivo de encabezado C
- FFI::memcmp — Comparación de zonas de memoria
- FFI::memcpy — Copia de una zona de memoria en otra
- FFI::memset — Rellena una zona de memoria
- FFI::new — Crea una estructura de datos C
- FFI::scope — Instancia un objeto FFI con las declaraciones C analizadas durante la precarga
- FFI::sizeof — Recupera el tamaño de los datos o tipos C
- FFI::string — Crea una string PHP a partir de una zona de memoria
- FFI::type — Crea un objeto FFI\CType a partir de una declaración C
- FFI::typeof — Recupera el FFI\CType de FFI\CData

# Gestor de datos C

(PHP 7 >= 7.4.0, PHP 8)

## Introducción

Los objetos FFI\CData pueden ser utilizados de diferentes maneras, como datos PHP normales:

- Los datos C de tipo escalar pueden ser leídos y asignados a través de la propiedad $cdata, por ejemplo. `$x = FFI::new('int'); $x->cdata = 42;`
- Los campos de tipo struct y union pueden ser accedidos como propiedades de objetos PHP ordinarios, por ejemplo `$cdata->field`
- Los elementos de un array C son accesibles como los elementos de un array PHP, por ejemplo. `$cdata[$offset]`
- Los arrays C pueden ser iterados utilizando instrucciones `foreach`.
- Los arrays C pueden ser utilizados como argumentos de count().
- Los punteros C pueden ser desreferenciados como arrays, por ejemplo `$cdata[0]`
- Los punteros C pueden ser comparados utilizando operadores de comparación ordinarios (`<`, `<=`, `==`, `!=`, `>=`, `>`).
- Los punteros C pueden ser incrementados y decrementados utilizando operaciones ordinarias ( `+`/`-`/ / ). `++`/`--`, por ejemplo `$cdata += 5`
- Los punteros C pueden ser sustraídos de otro utilizando operaciones ordinarias `-`.
- Los punteros C hacia funciones pueden ser llamados como una clausura PHP clásica, por ejemplo `$cdata()`
- Cualquier dato C puede ser duplicado utilizando el operador clone, por ejemplo `$cdata2 = clone $cdata;`
- Todos los datos C pueden ser visualizados utilizando var_dump(), print_r(), etc.
- FFI\CData puede ahora ser atribuido a estructuras y campos a partir de PHP 8.3.0.

> Nota: Las limitaciones notables son que las instancias de FFI\CData no soportan las funciones isset(), empty() y unset(), y que las structs y unions C envueltas no implementan Traversable.

## Sinopsis de la Clase

namespace FFI;
final class CData {
}

## Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | FFI\CData puede ahora ser atribuido a estructuras y campos.

# Gestor de tipo C

(PHP 7 >= 7.4.0, PHP 8)

## Introducción

## Sinopsis de la Clase

namespace FFI;
final class CType {
/* Constantes */
public const int TYPE_VOID;
public const int TYPE_FLOAT;
public const int TYPE_DOUBLE;
public const int TYPE_LONGDOUBLE;
public const int TYPE_UINT8;
public const int TYPE_SINT8;
public const int TYPE_UINT16;
public const int TYPE_SINT16;
public const int TYPE_UINT32;
public const int TYPE_SINT32;
public const int TYPE_UINT64;
public const int TYPE_SINT64;
public const int TYPE_ENUM;
public const int TYPE_BOOL;
public const int TYPE_CHAR;
public const int TYPE_POINTER;
public const int TYPE_FUNC;
public const int TYPE_ARRAY;
public const int TYPE_STRUCT;
public const int ATTR_CONST;
public const int ATTR_INCOMPLETE_TAG;
public const int ATTR_VARIADIC;
public const int ATTR_INCOMPLETE_ARRAY;
public const int ATTR_VLA;
public const int ATTR_UNION;
public const int ATTR_PACKED;
public const int ATTR_MS_STRUCT;
public const int ATTR_GCC_STRUCT;
public const int ABI_DEFAULT;
public const int ABI_CDECL;
public const int ABI_FASTCALL;
public const int ABI_THISCALL;
public const int ABI_STDCALL;
public const int ABI_PASCAL;
public const int ABI_REGISTER;
public const int ABI_MS;
public const int ABI_SYSV;
public const int ABI_VECTORCALL;
/* Métodos */
public function getAlignment(): int
public function getArrayElementType(): FFI\CType
public function getArrayLength(): int
public function getAttributes(): int
public function getEnumKind(): int
public function getFuncABI(): int
public function getFuncParameterCount(): int
public function getFuncParameterType(int `$index`): FFI\CType
public function getFuncReturnType(): FFI\CType
public function getKind(): int
public function getName(): string
public function getPointerType(): FFI\CType
public function getSize(): int
public function getStructFieldNames(): array
public function getStructFieldOffset(string `$name`): int
public function getStructFieldType(string `$name`): FFI\CType
}

## Constantes predefinidas

`FFI\CType::TYPE_VOID`
`FFI\CType::TYPE_FLOAT`
`FFI\CType::TYPE_DOUBLE`
`FFI\CType::TYPE_LONGDOUBLE`
`FFI\CType::TYPE_UINT8`
`FFI\CType::TYPE_SINT8`
`FFI\CType::TYPE_UINT16`
`FFI\CType::TYPE_SINT16`
`FFI\CType::TYPE_UINT32`
`FFI\CType::TYPE_SINT32`
`FFI\CType::TYPE_UINT64`
`FFI\CType::TYPE_SINT64`
`FFI\CType::TYPE_ENUM`
`FFI\CType::TYPE_BOOL`
`FFI\CType::TYPE_CHAR`
`FFI\CType::TYPE_POINTER`
`FFI\CType::TYPE_FUNC`
`FFI\CType::TYPE_ARRAY`
`FFI\CType::TYPE_STRUCT`
`FFI\CType::ATTR_CONST`
`FFI\CType::ATTR_INCOMPLETE_TAG`
`FFI\CType::ATTR_VARIADIC`
`FFI\CType::ATTR_INCOMPLETE_ARRAY`
`FFI\CType::ATTR_VLA`
`FFI\CType::ATTR_UNION`
`FFI\CType::ATTR_PACKED`
`FFI\CType::ATTR_MS_STRUCT`
`FFI\CType::ATTR_GCC_STRUCT`
`FFI\CType::ABI_DEFAULT`
`FFI\CType::ABI_CDECL`
`FFI\CType::ABI_FASTCALL`
`FFI\CType::ABI_THISCALL`
`FFI\CType::ABI_STDCALL`
`FFI\CType::ABI_PASCAL`
`FFI\CType::ABI_REGISTER`
`FFI\CType::ABI_MS`
`FFI\CType::ABI_SYSV`
`FFI\CType::ABI_VECTORCALL`

# FFI\CType::getAlignment

(PHP 8 >= 8.1.0)

FFI\CType::getAlignment — Descripción

### Descripción

public function FFI\CType::getAlignment(): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# FFI\CType::getArrayElementType

(PHP 8 >= 8.1.0)

FFI\CType::getArrayElementType — Descripción

### Descripción

public function FFI\CType::getArrayElementType(): FFI\CType

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# FFI\CType::getArrayLength

(PHP 8 >= 8.1.0)

FFI\CType::getArrayLength — Descripción

### Descripción

public function FFI\CType::getArrayLength(): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# FFI\CType::getAttributes

(PHP 8 >= 8.1.0)

FFI\CType::getAttributes — Descripción

### Descripción

public function FFI\CType::getAttributes(): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# FFI\CType::getEnumKind

(PHP 8 >= 8.1.0)

FFI\CType::getEnumKind — Descripción

### Descripción

public function FFI\CType::getEnumKind(): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# FFI\CType::getFuncABI

(PHP 8 >= 8.1.0)

FFI\CType::getFuncABI — Descripción

### Descripción

public function FFI\CType::getFuncABI(): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# FFI\CType::getFuncParameterCount

(PHP 8 >= 8.1.0)

FFI\CType::getFuncParameterCount — Recuperar el número de argumentos de un tipo de función

### Descripción

public function FFI\CType::getFuncParameterCount(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de argumentos del tipo de función subyacente. Si el tipo subyacente no es una función, se lanza una FFI\Exception.

# FFI\CType::getFuncParameterType

(PHP 8 >= 8.1.0)

FFI\CType::getFuncParameterType — Recuperar el tipo de un parámetro de función

### Descripción

public function FFI\CType::getFuncParameterType(int `$index`): FFI\CType

Devuelve el tipo de un parámetro para el tipo de función subyacente.

### Parámetros

`index`
  Índice del parámetro de la función, basado en cero.

### Valores devueltos

Devuelve el tipo de un parámetro para el tipo de función subyacente. Si el tipo subyacente no es una función, o si el índice proporcionado está fuera del rango de los parámetros de la función, se lanza una FFI\Exception.

# FFI\CType::getFuncReturnType

(PHP 8 >= 8.1.0)

FFI\CType::getFuncReturnType — Descripción

### Descripción

public function FFI\CType::getFuncReturnType(): FFI\CType

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# FFI\CType::getKind

(PHP 8 >= 8.1.0)

FFI\CType::getKind — Descripción

### Descripción

public function FFI\CType::getKind(): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# FFI\CType::getName

(PHP 7 >= 7.4.0, PHP 8)

FFI\CType::getName — Descripción

### Descripción

public function FFI\CType::getName(): string

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# FFI\CType::getPointerType

(PHP 8 >= 8.1.0)

FFI\CType::getPointerType — Descripción

### Descripción

public function FFI\CType::getPointerType(): FFI\CType

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# FFI\CType::getSize

(PHP 8 >= 8.1.0)

FFI\CType::getSize — Descripción

### Descripción

public function FFI\CType::getSize(): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# FFI\CType::getStructFieldNames

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldNames — Descripción

### Descripción

public function FFI\CType::getStructFieldNames(): array

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# FFI\CType::getStructFieldOffset

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldOffset — Descripción

### Descripción

public function FFI\CType::getStructFieldOffset(string `$name`): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`name`

### Valores devueltos

# FFI\CType::getStructFieldType

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldType — Descripción

### Descripción

public function FFI\CType::getStructFieldType(string `$name`): FFI\CType

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`name`

### Valores devueltos

## Tabla de contenidos

- FFI\CType::getAlignment — Descripción
- FFI\CType::getArrayElementType — Descripción
- FFI\CType::getArrayLength — Descripción
- FFI\CType::getAttributes — Descripción
- FFI\CType::getEnumKind — Descripción
- FFI\CType::getFuncABI — Descripción
- FFI\CType::getFuncParameterCount — Recuperar el número de argumentos de un tipo de función
- FFI\CType::getFuncParameterType — Recuperar el tipo de un parámetro de función
- FFI\CType::getFuncReturnType — Descripción
- FFI\CType::getKind — Descripción
- FFI\CType::getName — Descripción
- FFI\CType::getPointerType — Descripción
- FFI\CType::getSize — Descripción
- FFI\CType::getStructFieldNames — Descripción
- FFI\CType::getStructFieldOffset — Descripción
- FFI\CType::getStructFieldType — Descripción

# Excepciones FFI

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

## Introducción

## Sinopsis de la Clase

namespace FFI;
class Exception extends Error {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# Excepciones del analizador sintáctico FFI

(PHP 7 >= 7.4.0, PHP 8)

## Introducción

## Sinopsis de la Clase

namespace FFI;
final class ParserException extends FFI\Exception {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
- Ejemplos
  - Uso básico de FFI
  - Funciones de retrollamada
  - Un ejemplo completo de PHP/FFI/precarga
- FFI — Interfaz principal para el código C y los datos
  - FFI::addr — Crea un puntero no gestionado hacia datos C
  - FFI::alignof — Recupera el alineamiento
  - FFI::arrayType — Construye dinámicamente un nuevo tipo de array C
  - FFI::cast — Realiza una conversión de tipo C
  - FFI::cdef — Crea un nuevo objeto FFI
  - FFI::free — Libera una estructura de datos no gestionada
  - FFI::isNull — Verifica si un objeto FFI\CData es un puntero nulo
  - FFI::load — Carga las declaraciones C desde un archivo de encabezado C
  - FFI::memcmp — Comparación de zonas de memoria
  - FFI::memcpy — Copia de una zona de memoria en otra
  - FFI::memset — Rellena una zona de memoria
  - FFI::new — Crea una estructura de datos C
  - FFI::scope — Instancia un objeto FFI con las declaraciones C analizadas durante la precarga
  - FFI::sizeof — Recupera el tamaño de los datos o tipos C
  - FFI::string — Crea una string PHP a partir de una zona de memoria
  - FFI::type — Crea un objeto FFI\CType a partir de una declaración C
  - FFI::typeof — Recupera el FFI\CType de FFI\CData
- FFI\CData — Gestor de datos C
- FFI\CType — Gestor de tipo C
  - FFI\CType::getAlignment — Descripción
  - FFI\CType::getArrayElementType — Descripción
  - FFI\CType::getArrayLength — Descripción
  - FFI\CType::getAttributes — Descripción
  - FFI\CType::getEnumKind — Descripción
  - FFI\CType::getFuncABI — Descripción
  - FFI\CType::getFuncParameterCount — Recuperar el número de argumentos de un tipo de función
  - FFI\CType::getFuncParameterType — Recuperar el tipo de un parámetro de función
  - FFI\CType::getFuncReturnType — Descripción
  - FFI\CType::getKind — Descripción
  - FFI\CType::getName — Descripción
  - FFI\CType::getPointerType — Descripción
  - FFI\CType::getSize — Descripción
  - FFI\CType::getStructFieldNames — Descripción
  - FFI\CType::getStructFieldOffset — Descripción
  - FFI\CType::getStructFieldType — Descripción
- Excepciones FFI
- FFI\ParserException — Excepciones del analizador sintáctico FFI

# OPcache

# Introducción

OPcache mejora el rendimiento de PHP almacenando el código de bytes de un script precompilado en la memoria compartida, eliminando así la necesidad de que PHP cargue y analice los script en cada petición.

Esta extensión está incluída en PHP 5.5.0 y posteriores, y está » disponible en PECL para las versiones 5.2, 5.3 y 5.4 de PHP.

# Instalación/Configuración

## Tabla de contenidos

- Instalación
- Configuración en tiempo de ejecución

## Instalación

OPcache solo puede ser compilado como una extensión compartida. Si se ha desactivado la compilación de extensiones por omisión con --disable-all, es necesario compilar PHP con la opción --enable-opcache para que OPcache esté disponible.

Una vez compilado, puede utilizarse la directiva de configuración zend_extension para cargar la extensión OPcache en PHP. Esto puede realizarse con `zend_extension=/full/path/to/opcache.so` en plataformas no-Windows, y `zend_extension=C:\path\to\php_opcache.dll` en Windows.

> Nota: Si se desea utilizar OPcache con » Xdebug, debe cargarse OPcache antes que Xdebug.

### Configuración php.ini recomendada

La siguiente configuración es generalmente recomendada, ya que proporciona un buen rendimiento :

    opcache.memory_consumption=128
    opcache.interned_strings_buffer=8
    opcache.max_accelerated_files=4000
    opcache.revalidate_freq=60
    opcache.fast_shutdown=1 ; anterior a PHP 7.2.0
    opcache.enable_cli=1

Asimismo, podría ser deseable desactivar opcache.save_comments y activar opcache.enable_file_override, sin embargo, tenga en cuenta que debe probarse el código antes de utilizarlo en producción, ya que podría romper frameworks y aplicaciones, especialmente en casos donde se utilicen anotaciones de comentarios de documentación.

En Windows, opcache.file_cache_fallback debe estar activado, y opcache.file_cache debe definirse a una carpeta existente y escribible.

Una lista completa de directivas de configuración soportadas por OPcache está disponible.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración de OPcache
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
opcache.enable | 1 | `INI_ALL` |
opcache.enable_cli | 0 | `INI_SYSTEM` | Entre PHP 7.1.2 y 7.1.6 inclusive, el valor por omisión era 1
opcache.memory_consumption | "128" | `INI_SYSTEM` |
opcache.interned_strings_buffer | "8" | `INI_SYSTEM` |
opcache.max_accelerated_files | "10000" | `INI_SYSTEM` |
opcache.max_wasted_percentage | "5" | `INI_SYSTEM` |
opcache.use_cwd | 1 | `INI_SYSTEM` |
opcache.validate_timestamps | 1 | `INI_ALL` |
opcache.revalidate_freq | "2" | `INI_ALL` |
opcache.revalidate_path | 0 | `INI_ALL` |
opcache.save_comments | 1 | `INI_SYSTEM` |
opcache.fast_shutdown | 0 | `INI_SYSTEM` | Eliminado en PHP 7.2.0.
opcache.enable_file_override | 0 | `INI_SYSTEM` |
opcache.optimization_level | "0x7FFEBFFF" | `INI_SYSTEM` | Modificado desde 0x7FFFBFFF en PHP 7.3.0
opcache.inherited_hack | 1 | `INI_SYSTEM` | Eliminado en PHP 7.3.0
opcache.dups_fix | 0 | `INI_ALL` |
opcache.blacklist_filename | "" | `INI_SYSTEM` |
opcache.max_file_size | 0 | `INI_SYSTEM` |
opcache.consistency_checks | 0 | `INI_ALL` | >Desactivado a partir de PHP 8.1.18 y 8.2.5. Eliminado a partir de PHP 8.3.0.
opcache.force_restart_timeout | "180" | `INI_SYSTEM` |
opcache.error_log | "" | `INI_SYSTEM` |
opcache.log_verbosity_level | 1 | `INI_SYSTEM` |
opcache.record_warnings | 0 | `INI_SYSTEM` | Disponible a partir de PHP 8.0.0.
opcache.preferred_memory_model | "" | `INI_SYSTEM` |
opcache.protect_memory | 0 | `INI_SYSTEM` |
opcache.mmap_base | `null` | `INI_SYSTEM` |
opcache.restrict_api | "" | `INI_SYSTEM` |
opcache.file_update_protection | "2" | `INI_ALL` |
opcache.huge_code_pages | 0 | `INI_SYSTEM` |
opcache.lockfile_path | "/tmp" | `INI_SYSTEM` |
opcache.opt_debug_level | 0 | `INI_SYSTEM` | Disponible a partir de PHP 7.1.0
opcache.file_cache | NULL | `INI_SYSTEM` |
opcache.file_cache_only | 0 | `INI_SYSTEM` |
opcache.file_cache_consistency_checks | 1 | `INI_SYSTEM` |
opcache.file_cache_fallback | 1 | `INI_SYSTEM` | Solo para Windows.
opcache.validate_permission | 0 | `INI_SYSTEM` | Disponible a partir de PHP 7.0.14
opcache.validate_root | 0 | `INI_SYSTEM` | Disponible a partir de PHP 7.0.14
opcache.preload | "" | `INI_SYSTEM` | Disponible a partir de PHP 7.4.0
opcache.preload_user | "" | `INI_SYSTEM` | Disponible a partir de PHP 7.4.0
opcache.cache_id | "" | `INI_SYSTEM` | Solo para Windows. Disponible a partir de PHP 7.4.0
opcache.jit | "disable" | `INI_ALL` | Disponible a partir de PHP 8.0.0. Antes de PHP 8.4.0, el valor predeterminado era "tracing".
opcache.jit_buffer_size | 64M | `INI_SYSTEM` | Disponible a partir de PHP 8.0.0. Antes de PHP 8.4.0, el valor predeterminado era 0.
opcache.jit_debug | 0 | `INI_ALL` | Disponible a partir de PHP 8.0.0
opcache.jit_bisect_limit | 0 | `INI_ALL` | Disponible a partir de PHP 8.0.0
opcache.jit_prof_threshold | "0.005" | `INI_ALL` | Disponible a partir de PHP 8.0.0
opcache.jit_max_root_traces | "1024" | `INI_SYSTEM` | Disponible a partir de PHP 8.0.0
opcache.jit_max_side_traces | "128" | `INI_SYSTEM` | Disponible a partir de PHP 8.0.0
opcache.jit_max_exit_counters | "8192" | `INI_SYSTEM` | Disponible a partir de PHP 8.0.0
opcache.jit_hot_loop | "61" | `INI_SYSTEM` | Disponible a partir de PHP 8.0.0. Antes de PHP 8.5.0, el valor predeterminado era 64.
opcache.jit_hot_func | "127" | `INI_SYSTEM` | Disponible a partir de PHP 8.0.0
opcache.jit_hot_return | "8" | `INI_SYSTEM` | Disponible a partir de PHP 8.0.0
opcache.jit_hot_side_exit | "8" | `INI_SYSTEM` | Disponible a partir de PHP 8.0.0
opcache.jit_blacklist_root_trace | "16" | `INI_ALL` | Disponible a partir de PHP 8.0.0
opcache.jit_blacklist_side_trace | "8" | `INI_ALL` | Disponible a partir de PHP 8.0.0
opcache.jit_max_loop_unrolls | "8" | `INI_ALL` | Disponible a partir de PHP 8.0.0
opcache.jit_max_recursive_calls | "2" | `INI_ALL` | Disponible a partir de PHP 8.0.0
opcache.jit_max_recursive_returns | "2" | `INI_ALL` | Disponible a partir de PHP 8.0.0
opcache.jit_max_polymorphic_calls | "2" | `INI_ALL` | Disponible a partir de PHP 8.0.0

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`opcache.enable` bool
  Activa el cache de opcode. Cuando está desactivado, el código no es ni optimizado, ni almacenado en caché. La configuración de `opcache.enable` no puede ser activada durante la ejecución mediante la función ini_set(), solo puede ser desactivada. Intentar activarla en un script generará una advertencia.
`opcache.enable_cli` bool
  Activa el cache de opcode para la versión CLI de PHP.
`opcache.memory_consumption` int
  El tamaño de la memoria compartida utilizada por OPcache, en megabytes. El valor mínimo permisible es `"8"`, que se fuerza si se define un valor más pequeño.
`opcache.interned_strings_buffer` int
  La cantidad de memoria utilizada para almacenar cadenas internas, en megabytes. El valor máximo es de 32767 en arquitecturas de 64 bits, y de 4095 en arquitecturas de 32 bits.

  > Nota: Antes de PHP 8.4.0, el valor máximo era de 4095 megabytes en todas las arquitecturas.

`opcache.max_accelerated_files` int
  El número máximo de claves (y por lo tanto, de scripts) en la tabla de hash de OPcache. El valor actualmente utilizado será el primer número del conjunto de números primos `{ 223, 463, 983, 1979, 3907, 7963, 16229, 32531, 65407, 130987, 262237, 524521, 1048793 }` que sea mayor o igual que el valor configurado. El valor mínimo es 200. El valor máximo es 100000 en PHP < 5.5.6, y 1000000 en versiones posteriores. Los valores fuera de este intervalo se ajustan al intervalo permitido.
`opcache.max_wasted_percentage` int
  El porcentaje máximo de memoria desperdiciada permitido antes de que se programe un reinicio, si no hay suficiente memoria disponible. El valor máximo permisible es `"50"`, que se fuerza si se define un valor más grande.
`opcache.use_cwd` bool
  Si está activado, OPcache añade el directorio de trabajo actual a la clave del script, eliminando así posibles colisiones entre archivos con el mismo nombre base. Desactivar esta funcionalidad mejora el rendimiento, pero puede romper aplicaciones existentes.
`opcache.validate_timestamps` bool

  Si está activado, OPcache verificará las actualizaciones de los scripts cada opcache.revalidate_freq segundos. Cuando esta directiva está desactivada, debe reinicializarse OPcache manualmente mediante la función opcache_reset(), la función opcache_invalidate() o reiniciando el servidor web para que los cambios en el sistema de archivos surtan efecto.

  > Nota: OPcache puede validar siempre el timestamp de un archivo durante la compilación si las opciones opcache.file_update_protection o opcache.max_file_size están definidas en valores no nulos.

`opcache.revalidate_freq` int
  La frecuencia de verificación del timestamp del script para detectar posibles actualizaciones, en segundos. El valor `0` hará que OPcache verifique las actualizaciones en cada petición. Esta directiva de configuración se ignora si opcache.validate_timestamps está desactivado.
`opcache.revalidate_path` bool
  Si está desactivado, los archivos en caché existentes que usan el mismo include_path serán reutilizados. También, si un archivo con el mismo nombre está en otro lugar en el include_path, no será encontrado.
`opcache.save_comments` bool
  Si está desactivado, todos los comentarios de documentación serán eliminados del cache de opcode para reducir el tamaño del código optimizado. La desactivación de esta directiva puede romper aplicaciones y frameworks que dependen del análisis de comentarios para anotaciones, como Doctrine, Zend Framework 2 y PHPUnit.
`opcache.fast_shutdown` bool
  Si está activado, se utilizará una secuencia de cierre rápida, que no libera cada bloque asignado, sino que se basa en el gestor de memoria del Zend Engine para desasignar el conjunto entero de variables de la petición, en masa. Esta directiva fue eliminada en PHP 7.2.0. Una variante de la secuencia de cierre rápido fue integrada en PHP y será utilizada automáticamente si es posible.
`opcache.enable_file_override` bool
  Cuando está activado, el cache de opcode será verificado para saber si un archivo ya ha sido almacenado en caché cuando se llaman a las funciones file_exists(), is_file() y is_readable(). Esto puede aumentar el rendimiento de las aplicaciones que verifican la existencia y la legibilidad de los scripts PHP, pero puede devolver datos obsoletos si opcache.validate_timestamps está desactivado.
`opcache.optimization_level` int
  Una máscara de bits que controla qué pases de optimización se ejecutan. El valor por omisión es `0x7FFEBFFF`, que activa todas las optimizaciones seguras. Desactivar optimizaciones o activar optimizaciones no seguras es principalmente útil para depurar/desarrollar el optimizador. Cada bit en la máscara de bits activa un pase de optimización específico:

  Máscara de bits de pases de optimización
  Bit | Nombre del pase | Descripción | Por omisión
  --- | --- | --- | ---
  0 | PASS_1 | Optimizaciones peephole simples | On
  1 | PASS_2 | No utilizado (fusionado en PASS_1) | On
  2 | PASS_3 | Optimización de saltos simple | On
  3 | PASS_4 | Optimización de llamadas | On
  4 | PASS_5 | Optimización basada en el grafo de flujo de control | On
  5 | PASS_6 | Optimización basada en análisis de flujo de datos | On
  6 | PASS_7 | Si el grafo de llamadas debe utilizarse para optimizaciones basadas en SSA | On
  7 | PASS_8 | Propagación de constantes condicional dispersa | On
  8 | PASS_9 | Optimización de variables temporales | On
  9 | PASS_10 | Eliminación de opcodes NOP | On
  10 | PASS_11 | Compactación de literales | On
  11 | PASS_12 | Pre-cálculo del tamaño de la pila de llamadas | On
  12 | PASS_13 | Eliminación de variables no utilizadas | On
  13 | PASS_14 | Eliminación de código muerto | On
  14 | PASS_15 | Recopilación y sustitución de declaraciones de constantes (no seguro) | Off
  15 | PASS_16 | Inserción en línea de funciones triviales (parte de la optimización de llamadas) | On
  16 | (Flag) | Ignorar la posibilidad de sobrecarga de operadores (no seguro) | Off

  > Nota: Optimizaciones seguras vs no seguras
  > Las optimizaciones seguras (activadas por omisión) preservan el comportamiento exacto del código PHP mientras mejoran el rendimiento. Incluyen la eliminación de código muerto, el plegado de constantes y la optimización de saltos. Las optimizaciones no seguras (desactivadas por omisión) pueden alterar el comportamiento en casos límite:

  > - Bit 14: Recopilación de constantes. Las constantes se sustituyen en tiempo de compilación, ignorando el orden de declaración en tiempo de ejecución:

  >       <?php
  >       echo getA();         // Outputs: "hello" instead of throwing an Error
  >       const A = "hello";
  >       function getA() { return A; }

  > - Bit 16: Ignorar la sobrecarga de operadores. No seguro cuando se utilizan clases con `do_operation` (p. ej. GMP, BCMath) en operaciones aritméticas. Con declaraciones de tipo, el optimizador puede aplicar las mismas optimizaciones de forma segura.

`opcache.inherited_hack` bool
  Esta directiva de configuración se ignora.
`opcache.dups_fix` bool
  Este hack solo debe ser activado como solución de contorno para errores "Cannot redeclare class".
`opcache.blacklist_filename` string
  La ubicación de almacenamiento del archivo que gestiona la lista negra de OPcache. Un archivo de lista negra es un archivo de texto que contiene nombres de archivos que no deben ser acelerados; uno por línea. Se permiten comodines, y también se pueden proporcionar prefijos. Las líneas que comienzan con punto y coma se consideran comentarios y serán ignoradas. Un archivo de lista negra simple se ve así:

      ; Coincide con un archivo específico.
      /var/www/broken.php
      ; Un prefijo que coincide con todos los archivos que comienzan con x.
      /var/www/x
      ; Una coincidencia con comodín.
      /var/www/*-broken.php

`opcache.max_file_size` int
  El tamaño máximo del archivo que puede ser almacenado en caché, en bytes. Si es `0`, todos los archivos podrán ser almacenados en caché.
`opcache.consistency_checks` int
  Si es diferente de cero, OPcache verificará la suma de comprobación del caché cada N peticiones, donde N es el valor de esta directiva de configuración. Esto solo debe ser activado durante el depurado, sabiendo que afecta significativamente al rendimiento.

  > Nota: Desactivado a partir de PHP 8.1.18 y 8.2.5. Eliminado a partir de PHP 8.3.0.

`opcache.force_restart_timeout` int
  La duración de espera para el inicio de un reinicio programado, si el caché no está activado, en segundos. Si este tiempo de espera se alcanza, entonces OPcache asume que algo está mal, y matará los procesos que gestionan los bloqueos en el caché para permitir un reinicio. Si opcache.log_verbosity_level es 2 o más, se registrará una advertencia en el registro de errores cuando ocurra este comportamiento. Esta directiva no es soportada en Windows.
`opcache.error_log` string
  El registro de errores para errores de OPcache. Una cadena vacía será vista como `stderr`, y los errores serán enviados a la salida estándar de errores (que será el registro de errores del servidor web en la mayoría de los casos).
`opcache.log_verbosity_level` int
  El nivel de verbosidad de los registros. Por omisión, solo los errores fatales (nivel 0) y los errores (nivel 1) serán registrados. Los otros niveles disponibles son las alertas (nivel 2), los mensajes informativos (nivel 3), y los mensajes de depuración (nivel 4).
`opcache.record_warnings` bool
  Si esta opción está activada, OPcache registrará los avisos de compilación y los reproducirá en el próximo include, incluso si se sirve desde el caché.
`opcache.preferred_memory_model` string
  El modelo de memoria preferido para OPcache, a utilizar. Si se deja vacío, OPcache elegirá el modelo más apropiado, que es la mejor forma de hacerlo en la mayoría de los casos. Los valores posibles son `mmap`, `shm`, `posix` y `win32`.
`opcache.protect_memory` bool
  Protege la memoria compartida de escrituras no autorizadas durante la ejecución de los scripts. Esto solo es útil para el depurado interno.
`opcache.mmap_base` string
  La base utilizada para los segmentos de memoria compartida en Windows. Todos los procesos PHP deben enlazar la memoria compartida en el mismo espacio de direcciones. El uso de esta directiva permite corregir los errores "Unable to reattach to base address".
`opcache.restrict_api` string
  Permite la llamada a las funciones de la API de OPcache solo desde scripts PHP cuyo camino comienza con una cadena específica. El valor por omisión, "", significa "sin restricciones".
`opcache.file_update_protection` string
  Impide el almacenamiento en caché de archivos que datan menos que este número de segundos. Esto protege del almacenamiento en caché de archivos actualizados incompletamente. Si todas las actualizaciones de archivos son atómicas, el rendimiento puede ser aumentado definiéndolo a `0`. Esto permitirá almacenar en caché los archivos inmediatamente.
`opcache.huge_code_pages` bool
  Activa o desactiva la copia de código PHP (segmento de texto) en HUGE PAGES. Esto debería mejorar el rendimiento, pero requiere una configuración adecuada del sistema operativo. Disponible en Linux a partir de PHP 7.0.0, y en FreeBSD a partir de PHP 7.4.0.
`opcache.lockfile_path` string
  Ruta absoluta utilizada para guardar los archivos de bloqueo compartidos (solo para *nix)
`opcache.opt_debug_level` string
  Produce un volcado de opcode para depurar los diferentes pasos de optimización. 0x10000 mostrará los opcodes tal como el compilador los produce antes de que se produzca cualquier optimización, mientras que 0x20000 mostrará los códigos optimizados.
`opcache.file_cache` string
  Activa y define el directorio de caché de segundo nivel. Esto debería mejorar el rendimiento cuando la memoria SHM está llena, al reiniciar el servidor o reinicializar SMH. El valor por omisión "" desactiva el almacenamiento en caché basado en archivos.
`opcache.file_cache_only` bool
  Activa o desactiva el almacenamiento en caché del opcode en la memoria compartida.

  > Nota: Antes de PHP 8.1.0, desactivar esta directiva con un archivo de caché ya lleno requiere el vaciado manual de la caché.

`opcache.file_cache_consistency_checks` bool
  Activa o desactiva la validación de la suma de comprobación cuando el script se carga desde el caché de archivos.
`opcache.file_cache_fallback` bool
  Sugiere opcache.file_cache_only=1 para un proceso determinado que ha fallado al unirse a la memoria compartida (solo para Windows). Se requiere el caché de archivos activado explícitamente.
  Precaución

  Desactivar esta opción de configuración puede impedir que los procesos se inicien, y por lo tanto se desaconseja.

`opcache.validate_permission` bool
  Valida los permisos de los archivos almacenados en caché con respecto al usuario actual.
`opcache.validate_root` bool
  Impide las colisiones de nombres en entornos `chroot`. Esto debería ser activado en todos los entornos `chroot` para impedir el acceso a archivos fuera del chroot.
`opcache.preload` string
  Especifica un script PHP que será compilado y ejecutado al iniciar el servidor, y que puede precargar otros archivos, ya sea mediante include o utilizando la función opcache_compile_file(). Todas las entidades (por ejemplo funciones y clases) definidas en estos archivos estarán disponibles para las peticiones listas para usar, hasta que el servidor se apague.

  > Nota: El precargado no es soportado en Windows.

`opcache.preload_user` string
  Permite que el precargado se ejecute como usuario del sistema especificado. Esto es útil para servidores que se inician como root antes de cambiar a un usuario del sistema no privilegiado. El precargado como root no está permitido por omisión por razones de seguridad, a menos que esta directiva esté explícitamente definida como `root`. A partir de PHP 8.3.0, esta directiva ya no necesita ser definida para permitir el precargado al ejecutarse como root con CLI SAPI o phpdbg SAPI.
`opcache.cache_id` string

  En Windows, todos los procesos que ejecutan el mismo PHP SAPI bajo el mismo usuario con el mismo ID de caché comparten una instancia única de OPcache. El valor del ID de caché puede ser elegido libremente.

  Sugerencia

  Para IIS, diferentes grupos de aplicaciones pueden tener su propia instancia OPcache utilizando la variable de entorno APP_POOL_ID como `opcache.cache_id`. For IIS, different application pools can have their own OPcache instance by using the environment variable APP_POOL_ID as `opcache.cache_id`.

`opcache.jit` string|int
  Para un uso típico, esta opción acepta una de las cuatro siguientes valores string:
  - `disable`: Desactivado completamente, no puede ser activado durante el tiempo de ejecución.
  - `off`: Desactivado, pero puede ser activado durante el tiempo de ejecución.
  - `tracing`/`on`: Utiliza el tracing JIT. Activado por omisión y recomendado para la mayoría de los usuarios.
  - `function`: Utiliza el function JIT.

  Para un uso avanzado, esta opción acepta un entero de 4 dígitos `CRTO`, donde los dígitos significan:

  `C` (Banderas de optimización específica del CPU)
    - `0`: Desactiva las optimizaciones específicas del CPU.
    - `1`: Activa el uso de AVX, si el CPU lo soporta.
  `R` (asignación de registros)
    - `0`: No realiza ninguna asignación de registros
    - `1`: Realiza asignaciones de registros a nivel de bloque.
    - `2`: Realiza asignaciones de registros globales.
  `T` (disparador)
    - `0`: Compila todas las funciones al cargar el script.
    - `1`: Compila las funciones en su primera ejecución.
    - `2`: Perfila las funciones en la primera petición y compila las funciones más calientes justo después.
    - `3`: Perfila a la volada y compila las funciones calientes.
    - `4`: Actualmente no utilizado.
    - `5`: Utiliza el tracing JIT. Perfila a la volada y compila las trazas para los segmentos de código caliente.
  `O` (nivel de optimización)
    - `0`: Sin JIT.
    - `1`: JIT mínimo (llama a los manejadores estándar de la VM).
    - `2`: Inlinea los manejadores de la VM.
    - `3`: Utiliza la inferencia de tipos.
    - `4`: Utiliza un grafo de llamadas.
    - `5`: Optimiza el script entero.
  El modo `"tracing"` corresponde a `CRTO = 1254`, el modo `"function"` corresponde a `CRTO = 1205`.
`opcache.jit_buffer_size` int
  La cantidad de memoria compartida reservada para código compilado JIT. Un valor de cero desactiva el JIT. Cuando un int es utilizado, su valor es medido en bytes. También puede utilizar la notación abreviada como se describe en esta entrada de la FAQ..
`opcache.jit_debug` int
  Una máscara de bits que especifica qué salida de depuración de JIT activar Para los valores posibles, consulte » zend_jit.h (ver las definiciones de macro que comienzan con `ZEND_JIT_DEBUG`).
`opcache.jit_bisect_limit` int
  Opción de depuración que desactiva la compilación JIT después de la compilación de un cierto número de funciones. Esto puede ser útil para bisectar la fuente de una mala compilación JIT. Nota: esta opción solo funciona cuando el disparador JIT está definido a 0 (compilación al cargar el script) o 1 (compilación a la primera ejecución), por ejemplo, `opcache.jit=1215`. Ver más en la opción opcache.jit.
`opcache.jit_prof_threshold` float
  Al utilizar el modo de disparador "perfilar las funciones en la primera petición", este límite determina si una función es considerada caliente. El número de llamadas a la función dividido por el número de llamadas a todas las funciones debe ser superior a este límite. Por ejemplo, un límite de 0.005 significa que una función que corresponde a más de 0.5% de todas las llamadas será compilada JIT.
`opcache.jit_max_root_traces` int
  Número máximo de trazas raíz (root traces). La traza raíz es un flujo de ejecución que toma primero un camino a través del código, que es una unidad de la compilación JIT. JIT no compilara nuevo código si alcanza este límite.
`opcache.jit_max_side_traces` int
  Número máximo de trazas laterales (side trace) que una traza raíz puede tener. La traza lateral es otro flujo de ejecución que no sigue el camino de la traza raíz compilada. Las trazas laterales pertenecientes a la misma traza raíz no serán compiladas si se alcanza este límite.
`opcache.jit_max_exit_counters` int
  Número máximo de contadores de salida de traza lateral. Esto limita el número total de trazas laterales que puede haber, a través de todas las trazas raíz.
`opcache.jit_hot_loop` int
  Después de cuántas iteraciones un bucle es considerado caliente. El rango de valores válidos es `[0,255]` ; para cualquier parámetro fuera de este rango, por ejemplo -1 o 256, se utilizará el valor por omisión en su lugar. Especialmente, un valor nulo desactivará el JIT para trazar y compilar todos los bucles.

  > Nota: Se recomienda establecer este parámetro a un número primo, para evitar que sea un múltiplo de los contadores de iteraciones de bucle.

`opcache.jit_hot_func` int
  Después de cuántas llamadas una función es considerada caliente. El rango de valores válidos es `[0,255]` ; para cualquier parámetro fuera de este rango, por ejemplo -1 o 256, se utilizará el valor por omisión en su lugar. Especialmente, un valor nulo desactivará el JIT para trazar y compilar todas las funciones.
`opcache.jit_hot_return` int
  Después de cuántos retornos un retorno es considerado caliente. El rango de valores válidos es `[0,255]` ; para cualquier parámetro fuera de este rango, por ejemplo -1 o 256, se utilizará el valor por omisión en su lugar. Especialmente, un valor nulo desactivará el JIT para trazar y compilar todos los retornos.
`opcache.jit_hot_side_exit` int
  Después de cuántas salidas, una salida lateral es considerada caliente. El rango de valores válidos es `[0,255]` ; para cualquier parámetro fuera de este rango, por ejemplo -1 o 256, se utilizará el valor por omisión en su lugar. Especialmente, un valor nulo desactivará el JIT para trazar y compilar todas las salidas laterales.
`opcache.jit_blacklist_root_trace` int
  Número máximo de intentos de compilación de una traza raíz antes de que esta sea excluida.
`opcache.jit_blacklist_side_trace` int
  Número máximo de intentos de compilación de una traza lateral antes de que esta sea excluida.
`opcache.jit_max_loop_unrolls` int
  Número máximo de intentos para desenrollar un bucle en una traza lateral, intentando alcanzar la traza raíz y cerrar el bucle exterior.
`opcache.jit_max_recursive_calls` int
  Número máximo de llamadas recursivas desenrolladas en un bucle.
`opcache.jit_max_recursive_returns` int
  Número máximo de retornos recursivos desenrollados en un bucle.
`opcache.jit_max_polymorphic_calls` int
  Número máximo de intentos para inlinear una llamada polimórfica (dinámica o método). Llamadas por encima de este límite son tratadas como megamórficas y no son inlineadas.

# Precarga

A partir de PHP 7.4.0, PHP puede ser configurado para precargar scripts en el opcache cuando el motor se inicia. Todas las funciones, clases, interfaces o traits (pero no las constantes) de estos ficheros se volverán entonces disponibles globalmente para todas las peticiones sin necesidad de ser explícitamente incluidas. Esto intercambia la comodidad y el rendimiento (ya que el código está siempre disponible) por el uso de la memoria base. Asimismo, requiere reiniciar el proceso PHP para eliminar los scripts precargados, lo que significa que esta funcionalidad solo es práctica en producción, no en un entorno de desarrollo.

Tenga en cuenta que el compromiso óptimo entre rendimiento y memoria puede variar según la aplicación. "Precargar todo" puede ser la estrategia más simple, pero no necesariamente la mejor. Además, la precarga solo es útil cuando hay un proceso persistente de una petición a otra. Esto significa que aunque pueda funcionar en un script CLI si el opcache está activado, generalmente es inútil. La excepción es al utilizar la precarga en las bibliotecas FFI.

> Nota: La precarga no está soportada en Windows.

La configuración de la precarga implica dos pasos, y requiere que el opcache esté activado. En primer lugar, defina el valor opcache.preload en php.ini:

    opcache.preload=preload.php

preload.php es un fichero arbitrario que se ejecutará una vez al inicio del servidor (PHP-FPM, mod_php, etc.) y cargará código en memoria persistente. En los servidores que se inician como root antes de cambiar a un usuario del sistema no privilegiado, o si PHP se ejecuta como root (no recomendado), el valor opcache.preload_user puede especificar el usuario del sistema para ejecutar la precarga. La ejecución de la precarga como root no está permitida por defecto. Defina `opcache.preload_user=root` para permitirlo explícitamente.

En el script preload.php, cualquier fichero referenciado por include, include_once, require, require_once, o opcache_compile_file() serán analizados en la memoria persistente. En el siguiente ejemplo, todos los ficheros .php del directorio src serán precargados, excepto si son un fichero `Test`.

    <?php
    $directory = new RecursiveDirectoryIterator(__DIR__ . '/src');
    $fullTree = new RecursiveIteratorIterator($directory);
    $phpFiles = new RegexIterator($fullTree, '/.+((?<!Test)+\.php$)/i', RecursiveRegexIterator::GET_MATCH);

    foreach ($phpFiles as $key => $file) {
        require_once $file[0];
    }
    ?>

include y opcache_compile_file() funcionarán ambos, pero tienen implicaciones diferentes en la forma en que el código es gestionado.

- include ejecutará el código del fichero, mientras que opcache_compile_file() no lo hará. Esto significa que solo el primero soporta la declaración condicional (las funciones declaradas dentro de un bloque if).
- Debido a que include ejecutará el código, los ficheros incluidos de manera anidada también serán analizados y sus declaraciones precargadas.
- opcache_compile_file() puede cargar ficheros en cualquier orden. Es decir, si a.php define la clase `A` y b.php define la clase `B` que extiende `A`, entonces opcache_compile_file() puede cargar estos dos ficheros en cualquier orden. Al utilizar include, sin embargo, a.php debe ser incluido primero.
- En ambos casos, si un script posterior incluye un fichero que ya ha sido precargado, entonces su contenido siempre se ejecutará, pero los símbolos que define no se volverán a definir. El uso de include_once no evitará que el fichero sea incluido una segunda vez. Puede ser necesario cargar un fichero nuevamente para incluir las constantes globales definidas en él, ya que no son gestionadas por la precarga.

Cuál enfoque es el mejor depende, por lo tanto, del comportamiento deseado. Con código que utilizaría de otro modo un cargador automático, opcache_compile_file() permite una mayor flexibilidad. Con código que sería cargado manualmente de otro modo, include será más robusto.

# Funciones de OPcache

# opcache_compile_file

(PHP 5 >= 5.5.5, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_compile_file — Compila y almacena en caché un script PHP sin ejecutarlo

### Descripción

function opcache_compile_file(string `$filename`): bool

Esta función compila un script PHP y lo añade a la caché de opcode sin ejecutarlo. Esto puede ser utilizado para llenar una caché después de un reinicio del servidor precargando los ficheros que van a ser utilizados.

### Parámetros

`filename`
  La ruta de acceso al fichero PHP a compilar y almacenar en caché.

### Valores devueltos

Devuelve `true` si `filename` ha sido compilado con éxito o `false` si ocurre un error.

### Errores/Excepciones

Si `filename` no puede ser cargado o compilado, se genera un error de tipo `E_WARNING`. Puede utilizarse @ para suprimirlo.

### Ver también

- opcache_invalidate() - Invalida un script almacenado en caché

# opcache_get_configuration

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_get_configuration — Recupera la información de configuración del caché

### Descripción

function opcache_get_configuration(): array|false

Esta función devuelve la información de configuración de la instancia del caché.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array de información, incluyendo ini, lista negra y versión.

### Errores/Excepciones

Si `opcache.restrict_api` es utilizado y la ruta de acceso actual viola las reglas, se emitirá una advertencia de nivel E_WARNING; no se devolverá ninguna información de estado.

### Ver también

- opcache_get_status() - Obtiene información sobre el estado del caché

# opcache_get_status

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_get_status — Obtiene información sobre el estado del caché

### Descripción

function opcache_get_status(bool `$include_scripts` = `true`): array|false

Esta función devuelve información sobre el estado de la instancia del caché en memoria. No devuelve información sobre el caché de ficheros.

### Parámetros

`include_scripts`
  Incluye información específica de los scripts.

### Valores devueltos

Devuelve un array de información, que opcionalmente contiene información específica de estado de un script, o `false` si ocurre un error.

### Errores/Excepciones

Si `opcache.restrict_api` está en uso y la ruta actual viola las reglas, se emitirá una advertencia E_WARNING; no se devolverá ninguna información de estado.

### Historial de cambios

Versión | Descripción
--- | ---
PHP 8.3.0 | `opcache_get_status()['scripts'][n]['revalidate']` contiene ahora un timestamp Unix que indica cuándo se prevé la próxima revalidación del timestamp de los scripts, según lo dictado por la directiva INI `opcache.revalidate_freq`.

### Ejemplos

Ejemplo #1 Un ejemplo de opcache_get_status()

    <?php
    var_dump(opcache_get_status());
    ?>

Resultado del ejemplo anterior es similar a:

    array(9) {
      'opcache_enabled' =>
      bool(true)
      'cache_full' =>
      bool(false)
      'restart_pending' =>
      bool(false)
      'restart_in_progress' =>
      bool(false)
      'memory_usage' =>
      array(4) {
        'used_memory' =>
        int(9167936)
        'free_memory' =>
        int(125049792)
        'wasted_memory' =>
        int(0)
        'current_wasted_percentage' =>
        double(0)
      }
      'interned_strings_usage' =>
      array(4) {
        'buffer_size' =>
        int(8388608)
        'used_memory' =>
        int(2593616)
        'free_memory' =>
        int(5794992)
        'number_of_strings' =>
        int(10358)
      }
      'opcache_statistics' =>
      array(13) {
        'num_cached_scripts' =>
        int(0)
        'num_cached_keys' =>
        int(0)
        'max_cached_keys' =>
        int(16229)
        'hits' =>
        int(0)
        'start_time' =>
        int(1733310010)
        'last_restart_time' =>
        int(0)
        'oom_restarts' =>
        int(0)
        'hash_restarts' =>
        int(0)
        'manual_restarts' =>
        int(0)
        'misses' =>
        int(0)
        'blacklist_misses' =>
        int(0)
        'blacklist_miss_ratio' =>
        double(0)
        'opcache_hit_rate' =>
        double(0)
      }
      'scripts' =>
      array(0) {
      }
      'jit' =>
      array(7) {
        'enabled' =>
        bool(false)
        'on' =>
        bool(false)
        'kind' =>
        int(5)
        'opt_level' =>
        int(4)
        'opt_flags' =>
        int(6)
        'buffer_size' =>
        int(0)
        'buffer_free' =>
        int(0)
      }
    }

### Ver también

- opcache_get_configuration() - Recupera la información de configuración del caché

# opcache_invalidate

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.0)

opcache_invalidate — Invalida un script almacenado en caché

### Descripción

function opcache_invalidate(string `$filename`, bool `$force` = `false`): bool

Esta función invalida un script particular desde el caché opcode. Si el argumento `force` no está definido o vale `false`, el script solo se invalidará si la fecha/hora de modificación del script es más reciente que el opcode en caché. Esta función solo invalida el caché en memoria y no el caché de ficheros.

### Parámetros

`filename`
  La ruta de acceso al script a invalidar.
`force`
  Si vale `true`, el script se invalidará independientemente de si la invalidación es necesaria o no.

### Valores devueltos

Devuelve `true` si el caché opcode para el `filename` ha sido invalidado, o si no había nada que invalidar, o bien `false` si el caché opcode está desactivado.

### Ver también

- opcache_compile_file() - Compila y almacena en caché un script PHP sin ejecutarlo
- opcache_reset() - Reinicia el contenido del cache opcode

# opcache_is_script_cached

(PHP 5 >= 5.5.11, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.4)

opcache_is_script_cached — Indica si un script está en el caché de OPCache

### Descripción

function opcache_is_script_cached(string `$filename`): bool

Esta función verifica si un script PHP ha sido almacenado en el caché de OPCache. Esto puede ser utilizado para detectar fácilmente las "alertas" del caché para un script en particular. Esta función solo verifica el caché en memoria, no el caché de ficheros. Para verificar el caché de ficheros, utilice opcache_is_script_cached_in_file_cache().

### Parámetros

`filename`
  La ruta de acceso al script PHP a verificar.

### Valores devueltos

Retorna `true` si el script `filename` está presente en el caché en memoria de OPCache, `false` en caso contrario.

### Ver también

- opcache_compile_file() - Compila y almacena en caché un script PHP sin ejecutarlo
- opcache_is_script_cached_in_file_cache() - Indica si un script está en la caché de archivos de OPCache

# opcache_is_script_cached_in_file_cache

(PHP 8 >= 8.5.0)

opcache_is_script_cached_in_file_cache — Indica si un script está en la caché de archivos de OPCache

### Descripción

function opcache_is_script_cached_in_file_cache(string `$filename`): bool

Esta función verifica si un script PHP ha sido almacenado en la caché de OPCache. Esto puede utilizarse para detectar más fácilmente el "calentamiento" de la caché para un script en particular. Esta función solo verifica la caché de archivos, no la caché en memoria. Para verificar la caché en memoria, use opcache_is_script_cached().

### Parámetros

`filename`
  La ruta al script PHP a verificar.

### Valores devueltos

Devuelve `true` si `filename` está en la caché de OPCache, `false` en caso contrario.

### Ver también

- opcache_compile_file() - Compila y almacena en caché un script PHP sin ejecutarlo
- opcache_is_script_cached() - Indica si un script está en el caché de OPCache

# opcache_jit_blacklist

(PHP 8 >= 8.4.0)

opcache_jit_blacklist — Excluye una función de la compilación JIT

### Descripción

function opcache_jit_blacklist( Closure `$closure` ): void

Esta función excluye una función particular de la compilación JIT cuando se utiliza Tracing JIT. La función se especifica usando una Closure.

Advertencia

Las partes de la función que ya fueron compiladas por JIT no se ven afectadas y seguirán siendo compiladas por JIT.

### Parámetros

`closure`
  La función a excluir, representada como un callable de primera clase. También es posible pasar una función anónima, en cuyo caso la propia función anónima será excluida.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo básico de opcache_jit_blacklist()

    <?php
    function foo() {
        $x = 1;
        $x += 0;
        ++$x;
        var_dump($x);
    }
    opcache_jit_blacklist(foo(...));
    foo();
    ?>

### Ver también

- opcache_invalidate() - Invalida un script almacenado en caché
- opcache_reset() - Reinicia el contenido del cache opcode

# opcache_reset

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.0)

opcache_reset — Reinicia el contenido del cache opcode

### Descripción

function opcache_reset(): bool

Esta función reinicia el cache opcode en su totalidad. Tras la llamada a la función opcache_reset(), todos los scripts serán recargados y reanalizados en sus próximos llamados. Esta función solo reinicia el cache en memoria, no el cache de los ficheros.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si el cache opcode ha sido reiniciado, o `false` si el cache opcode está desactivado o si el reinicio está pendiente o en curso (ver opcache_get_status()).

### Ver también

- opcache_get_status() - Obtiene información sobre el estado del caché

## Tabla de contenidos

- opcache_compile_file — Compila y almacena en caché un script PHP sin ejecutarlo
- opcache_get_configuration — Recupera la información de configuración del caché
- opcache_get_status — Obtiene información sobre el estado del caché
- opcache_invalidate — Invalida un script almacenado en caché
- opcache_is_script_cached — Indica si un script está en el caché de OPCache
- opcache_is_script_cached_in_file_cache — Indica si un script está en la caché de archivos de OPCache
- opcache_jit_blacklist — Excluye una función de la compilación JIT
- opcache_reset — Reinicia el contenido del cache opcode

- Instalación/Configuración
  - Instalación
  - Configuración en tiempo de ejecución
- Precarga
- Funciones de OPcache
  - opcache_compile_file — Compila y almacena en caché un script PHP sin ejecutarlo
  - opcache_get_configuration — Recupera la información de configuración del caché
  - opcache_get_status — Obtiene información sobre el estado del caché
  - opcache_invalidate — Invalida un script almacenado en caché
  - opcache_is_script_cached — Indica si un script está en el caché de OPCache
  - opcache_is_script_cached_in_file_cache — Indica si un script está en la caché de archivos de OPCache
  - opcache_jit_blacklist — Excluye una función de la compilación JIT
  - opcache_reset — Reinicia el contenido del cache opcode

# Bufferización de salida

# Introducción

Las funciones de bufferización de salida permiten controlar cuándo los datos son enviados por el script. Esto puede ser útil en ciertas situaciones, especialmente si se deben enviar encabezados al navegador después de haber enviado datos. Estas funciones no afectan a los encabezados enviados por la función header() o a las cookies enviadas por setcookie(). Solo las funciones como echo y los datos entre bloques PHP son afectados.

# Instalación/Configuración

## Tabla de contenidos

- Configuración en tiempo de ejecución

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración de los buffers de salida
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
output_buffering | `"0"` | `INI_PERDIR` |
output_handler | `null` | `INI_PERDIR` |
implicit_flush | `"0"` | `INI_ALL` |
url_rewriter.tags | `"form="` | `INI_ALL` | A partir de PHP 7.1.0, este parámetro INI solo tiene efecto en output_add_rewrite_var(). Anterior a PHP 7.1.0, este parámetro INI activaba el soporte transparente del ID de sesión (ver session.trans_sid_tags).
url_rewriter.hosts | `$_SERVER['HTTP_HOST']` se utiliza por omisión. | `INI_ALL` | Disponible a partir de PHP 7.1.0

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`output_buffering` bool/int

  La memoria intermedia de la salida para todos los ficheros puede ser activada al definir esta directiva en `"On"`. Para limitar el tamaño del buffer, un número/cantidad correspondiente al número máximo de bytes permitidos puede ser utilizado en lugar de `"On"` para el valor de esta directiva. Por ejemplo, `output_buffering=4096`.

`output_handler` string

  La salida de los scripts puede ser redirigida hacia una función. Por ejemplo, al definir `output_handler` en mb_output_handler(), la codificación de los caracteres será convertida de manera transparente hacia la codificación especificada. La configuración de cualquier manejador de salida activa automáticamente la memoria intermedia de la salida.

  > Nota:

  > mb_output_handler() y ob_iconv_handler() no pueden ser utilizados juntos, y ob_gzhandler() y zlib.output_compression no pueden ser utilizados con alguno de los siguientes elementos: mb_output_handler(), ob_gzhandler(), zlib.output_compression, el manejador 'URL-Rewriter' (ver session.use_trans_sid y output_add_rewrite_var()).

  > Nota:

  > Solo las funciones internas pueden ser utilizadas con esta directiva. Para las funciones de usuario, utilice ob_start().

`implicit_flush` bool

  `false` por omisión. Al cambiar este valor a `true` se indica a PHP que el buffer de salida debe ser vaciado automáticamente después de cada función de visualización. Esto equivale a llamar a la función flush() después de cada llamada a cualquier función que produzca una salida (como print o echo) y cada bloque HTML.

  Cuando se utiliza PHP en un entorno web, activar esta opción tiene serias implicaciones y generalmente solo se recomienda para depuración. Este valor está por omisión en `true` cuando PHP funciona en modo `CLI SAPI`.

  Ver también ob_implicit_flush().

`url_rewriter.tags` string
  `url_rewriter.tags` especifica las etiquetas HTML y los atributos en los cuales las URLs son reescritas por los valores de output_add_rewrite_var(). Por omisión, es `"form="`. Añadir `"form="` o cualquier atributo `form` añadirá un elemento `input` oculto en el `form` con un atributo de nombre y valor para cada par nombre-valor pasado a output_add_rewrite_var().
  Precaución

  Añadir la misma etiqueta más de una vez a `url_rewriter.tags` utilizará únicamente la primera ocurrencia durante el proceso de reescritura de URL.

  > Nota: Anterior a PHP 7.1.0, url_rewriter.tags era utilizado para especificar session.trans_sid_tags.

`url_rewriter.hosts` string
  `url_rewriter.hosts` especifica los hosts que son reescritos para incluir los valores de la función output_add_rewrite_var(). Por omisión `$_SERVER['HTTP_HOST']`. Varios hosts pueden ser especificados separados por una coma, no se permite ningún espacio entre los hosts. Por ejemplo: `php.net,wiki.php.net,bugs.php.net`

# Constantes predefinidas

Las constantes listadas aquí están siempre disponibles en PHP.

Indicadores de estado transmitidos al controlador de salida

Los siguientes indicadores son transmitidos al segundo parámetro (`phase`) del controlador de salida definido por ob_start() en forma de máscara de bits:

`PHP_OUTPUT_HANDLER_START` (int)

  Indica que el almacenamiento en búfer de salida ha comenzado.

`PHP_OUTPUT_HANDLER_WRITE` (int)

  Indica que el búfer de salida ha comenzado a ser mostrado y contiene datos.

`PHP_OUTPUT_HANDLER_FLUSH` (int)

  Indica que el búfer ha sido mostrado.

`PHP_OUTPUT_HANDLER_CLEAN` (int)

  Indica que el búfer de salida ha sido limpiado.

`PHP_OUTPUT_HANDLER_FINAL` (int)

  Indica que es la operación final de almacenamiento en búfer de salida.

`PHP_OUTPUT_HANDLER_CONT` (int)

  Indica que el búfer ha sido mostrado, pero el almacenamiento en búfer de salida continúa.

  Es un alias de la constante `PHP_OUTPUT_HANDLER_WRITE`.

`PHP_OUTPUT_HANDLER_END` (int)

  Indica que el almacenamiento en búfer de salida ha finalizado.

  Es un alias de la constante `PHP_OUTPUT_HANDLER_FINAL`.

Indicadores de control del búfer de salida

Los siguientes indicadores pueden ser transmitidos al tercer parámetro (`flags`) del controlador de salida definido por ob_start() en forma de máscara de bits:

`PHP_OUTPUT_HANDLER_CLEANABLE` (int)

  Controla si un búfer de salida creado por la función ob_start() puede ser eliminado por ob_clean(). Este indicador no controla el comportamiento de ob_end_clean() o ob_get_clean().

`PHP_OUTPUT_HANDLER_FLUSHABLE` (int)

  Controla si un búfer de salida creado por la función ob_start() puede ser enviado a la salida estándar por ob_flush(). Este indicador no controla el comportamiento de ob_end_flush() o ob_get_flush().

`PHP_OUTPUT_HANDLER_REMOVABLE` (int)

  Controla si un búfer de salida creado por la función ob_start() puede ser eliminado antes del final del script o durante la llamada a ob_end_clean(), ob_end_flush(), ob_get_clean() o ob_get_flush().

`PHP_OUTPUT_HANDLER_STDFLAGS` (int)

  El conjunto por defecto de indicadores para el búfer de salida; actualmente, equivalente a `PHP_OUTPUT_HANDLER_CLEANABLE` | `PHP_OUTPUT_HANDLER_FLUSHABLE` | `PHP_OUTPUT_HANDLER_REMOVABLE`.

Indicadores de estado del controlador de salida

Los siguientes indicadores forman parte de la máscara de bits `flags` devuelta por ob_get_status():

`PHP_OUTPUT_HANDLER_STARTED` (int)

  Indica que el controlador de salida ha sido llamado.

`PHP_OUTPUT_HANDLER_DISABLED` (int)

  Indica que el controlador de salida está desactivado. Este indicador se define cuando el controlador de salida devuelve `false` o falla durante el procesamiento del búfer. Antes de PHP 8.4.0, este indicador podía estar definido durante el inicio de un búfer de salida.

`PHP_OUTPUT_HANDLER_PROCESSED` (int)

  Indica que el controlador de salida ha procesado con éxito el búfer. Disponible desde PHP 8.4.0.

# Bufferización de salida

La bufferización de salida es el almacenamiento en búfer (temporal) de la salida antes de que sea volcada (enviada y eliminada) al navegador (en un contexto web) o al shell (en línea de comandos). Mientras la bufferización de salida esté activa, ninguna salida es enviada por el script, en su lugar, la salida es almacenada en un búfer interno.

## Efectos de la bufferización en PHP

PHP depende de la infraestructura lógica/material subyacente al vaciar el búfer de la salida. La bufferización implementada por las consolas en línea de comandos (por ejemplo, en modo línea) o los servidores web y los navegadores en un contexto web (por ejemplo, completamente bufferizado) afectan cuándo se muestra la salida al usuario final. Algunos de estos efectos pueden ser eliminados ajustando finamente los parámetros del servidor y/o alineando los tamaños de los búferes de las diferentes capas.

## Control de la bufferización de salida en PHP

PHP proporciona un búfer de salida de usuario completamente bufferizado con funciones para iniciar, manipular y desactivar el búfer (la mayoría de las funciones ob_*), y dos funciones para vaciar los búferes del sistema subyacentes (flush() y ob_implicit_flush()). Algunas de estas funcionalidades pueden ser definidas y/o configuradas utilizando los parámetros php.ini apropiados.

## Casos de uso

La bufferización de salida es generalmente útil en situaciones donde la salida bufferizada es modificada o inspeccionada, o es utilizada más de una vez en una petición; o cuando se desea el vaciado controlado del búfer de la salida. Los casos de uso específicos incluyen:

- almacenar en caché el resultado de scripts de cálculo/tiempo intensivos por ejemplo generando páginas `HTML` estáticas
- reutilizar la salida generada al mostrarla, guardarla en un fichero y/o enviarla por correo electrónico
- vaciar la `head` de una página `HTML` separada del `body` permite a los navegadores cargar recursos externos mientras el script ejecuta procesos potencialmente más largos (por ejemplo, acceso a una base de datos/fichero, conexión de red externa). Esto es útil únicamente si el código de estado `HTTP` no puede cambiar después del envío de las cabeceras
- extraer información de funciones que producirían de otro modo una salida (por ejemplo phpinfo())
- controlar la salida de código de terceros al modificar/utilizar partes (por ejemplo, extraer datos, reemplazar palabras/frases, añadir etiquetas `HTML` faltantes), o al eliminarla completamente bajo ciertas condiciones (por ejemplo, errores)
- Polyfiller ciertas funcionalidades de servidor web no disponibles (por ejemplo, comprimir o codificar la salida)

# Vaciar los búferes del sistema

PHP ofrece dos formas de vaciar (enviar y eliminar el contenido) los búferes del sistema: mediante la llamada a flush() y activando el vaciado de búfer implícito con ob_implicit_flush() o el parámetro implicit_flush de php.ini.

## Comportamiento de vaciado del búfer de salida

Con el vaciado de búfer implícito desactivado, PHP solo vacía la salida cuando se llama a flush() o cuando finaliza el script.

Con el vaciado de búfer implícito activado, PHP intentará vaciar después de cada bloque de código que produzca salida. La salida en este contexto son datos de longitud no nula que son:

- fuera de las etiquetas `<?php ?>`
- mostrados por construcciones del lenguaje y funciones cuyo propósito explícito es mostrar variables o strings proporcionados por el usuario tales como echo, print, printf(), var_dump(), var_export(), vprintf()
- mostrados por funciones cuyo propósito es recolectar y producir datos/información sobre el script en ejecución o PHP tales como debug_print_backtrace(), phpcredits(), phpinfo(), ReflectionExtension::info()
- mostrados por PHP en una excepción no capturada o un error no manejado (sujeto a los parámetros de display_errors y error_reporting)
- todo lo que se escribe en `php://output`

> Nota: Mostrar strings vacíos o enviar encabezados no se considera salida y no desencadenará una operación de vaciado de búfer.

Advertencia

Si el vaciado de búfer implícito está activado, los caracteres de control (por ejemplo `"\n"`, `"\r"`, `"\0"`) también desencadenarán un vaciado de búfer.

## Limitaciones

Esta funcionalidad no puede vaciar los búferes de salida a nivel de usuario. Para usarlos juntos, los búferes de salida a nivel de usuario deben ser vaciados antes de vaciar los búferes del sistema para que PHP produzca una salida.

Advertencia

Llamar a flush() o activar el vaciado de búfer implícito puede interferir con los manejadores de salida de los búferes de salida a nivel de usuario que definen y envían encabezados en un contexto web (por ejemplo ob_gzhandler()) al enviar encabezados antes de que estos manejadores lo hagan.

El almacenamiento en búfer implementado por el software/hardware subyacente no puede ser reemplazado por PHP y debe ser tenido en cuenta al utilizar las funciones de control de búferes de PHP. Verificar los parámetros de almacenamiento en búfer de los servidores web/navegadores/consolas y trabajar con ellos puede mitigar los problemas potenciales. Trabajando en un contexto web, ya sea los parámetros de almacenamiento en búfer del servidor web o el almacenamiento en búfer del script podrían ser ajustados para funcionar en conjunto mientras que trabajar con las estrategias de almacenamiento en búfer de varios navegadores puede lograrse ajustando el almacenamiento en búfer en el script PHP. En las consolas que implementan el almacenamiento en búfer por línea, los caracteres de nueva línea podrían ser insertados en los lugares apropiados antes de vaciar la salida.

## Diferencias en el vaciado entre SAPI

Aunque el vaciado de búfer es implementado por cada SAPI de manera ligeramente diferente, estas implementaciones caen en una de dos categorías:

- Los SAPIs usados en un contexto web vaciarán primero los encabezados seguidos de la salida. `Apache2Handler`, `CGI`, `FastCGI` y `FPM` son tales SAPIs
- otros SAPIs tales como `CLI` y `embed` vaciarán solo la salida

# Búferes de salida a nivel de usuario

## Tabla de contenidos

- ¿Qué salida está bufferizada?
- Anidamiento de búferes de salida
- Tamaño del búfer
- Operaciones permitidas en los búferes
- Gestores de salida
- Trabajar con los gestores de salida
- Flags pasados a los gestores de salida
- Valores de retorno de los gestores de salida

La bufferización de salida a nivel de usuario de PHP puede iniciarse, manipularse y finalizar desde el código PHP. Cada uno de estos búferes incluye un búfer de salida y una función de gestión de salida asociada.

## ¿Qué salida está bufferizada?

Los búferes de salida a nivel de usuario de PHP bufferizan toda la salida después de su inicio hasta que sean desactivados o el script finalice. La salida en el contexto de los búferes de salida a nivel de usuario de PHP es todo lo que PHP mostraría o enviaría al navegador. En términos prácticos, la salida es cualquier dato de longitud no nula que sea:

- fuera de las etiquetas `<?php ?>`
- mostrados por construcciones del lenguaje y funciones cuyo propósito explícito es mostrar variables o strings proporcionados por el usuario tales como echo, print, printf(), var_dump(), var_export(), vprintf()
- mostrados por funciones cuyo propósito es recolectar y producir datos/información sobre el script en ejecución o PHP tales como debug_print_backtrace(), phpcredits(), phpinfo(), ReflectionExtension::info()
- mostrados por PHP en una excepción no capturada o un error no manejado (sujeto a los parámetros de display_errors y error_reporting)
- todo lo que se escribe en `php://output`

> Nota: Los datos escritos directamente en `stdout` o pasados a una función SAPI con una funcionalidad similar no serán capturados por los búferes de salida a nivel de usuario. Esto incluye la escritura de datos en `stdout` con fwrite() o el envío de encabezados con header() o setcookie().

## Iniciar un búfer de salida

Los búferes de salida a nivel de usuario pueden iniciarse utilizando la función ob_start() o definiendo los parámetros output_buffering y output_handler de php.ini. Tanto uno como otro pueden crear búferes de salida, ob_start() es más flexible ya que acepta funciones definidas por el usuario como gestores de salida y las operaciones permitidas en el búfer (flush, clean, remove) pueden definirse también. Los búferes de salida iniciados con ob_start() estarán activos a partir de la línea donde se llamó a la función, mientras que los iniciados con output_buffering bufferizarán la salida desde la primera línea del script.

PHP también incluye un gestor de salida interno `"URL-Rewriter"` que inicia su propio búfer de salida y solo permite dos instancias del mismo funcionando al mismo tiempo (una para la reescritura de URL a nivel de usuario y otra para el soporte transparente de identificadores de sesión). Estos búferes pueden iniciarse llamando a la función output_add_rewrite_var() y/o activando el parámetro session.use_trans_sid de php.ini.

La extensión `zlib` tiene su propio búfer de salida que puede activarse utilizando el parámetro zlib.output_compression de php.ini.

> Nota: Mientras que `"URL-Rewriter"` es especial en cuanto a que solo permite dos instancias del mismo funcionando al mismo tiempo, todos los búferes de salida a nivel de usuario utilizan los mismos búferes subyacentes usados por ob_start() con su funcionalidad implementada por una función de gestión de salida personalizada. Como tal, toda su funcionalidad puede emularse con código de usuario.

## Anidamiento de búferes de salida

Si un búfer de salida está activo cuando se inicia un nuevo búfer, el nuevo búfer se anidará dentro del búfer previamente activo. El búfer interno se comportará de la misma manera, ya esté anidado o no, pero la salida bufferizada por este no será bufferizada por el búfer externo. Solo la salida vaciada por el búfer interno será bufferizada por el búfer externo.

La mayoría de las funciones `ob_*` solo funcionan con el búfer de salida activo (el último iniciado) por lo que solo el búfer activo puede vaciarse, limpiarse y desactivarse. Las funciones que funcionan con otros búferes son ob_list_handlers() que devuelve la lista de todos los gestores de salida en uso y ob_get_status() que puede devolver información sobre el búfer activo únicamente o sobre todos los búferes en uso.

Llamar a ob_get_level() o ob_get_status() devolverá el nivel de anidamiento del búfer de salida activo.

Precaución

El valor para los niveles idénticos entre ob_get_level() y ob_get_status() difiere en uno. Para ob_get_level() el primer nivel es `1`, mientras que para ob_get_status() el primer nivel es `0`.

## Tamaño del búfer

Los tamaños de los búferes de salida se expresan mediante enteros y representan el número de bytes que el búfer puede almacenar sin vaciarse. Cuando el tamaño de la salida en el búfer excede el tamaño del búfer, el contenido del búfer se envía al gestor de salida, su valor de retorno se lava y el búfer se vacía.

Con la excepción de `"URL-Rewriter"`, el tamaño de los búferes de salida puede definirse cuando el búfer se inicia. Si se define como `0`, el búfer de salida solo está limitado por la memoria disponible para PHP. Si se define como `1`, el búfer se lava después de cada bloque de código que produce una salida de longitud no nula.

El tamaño de los búferes de salida puede recuperarse llamando a ob_get_status().

Los búferes de salida iniciados con ob_start() tendrán su tamaño de búfer definido al valor entero pasado al segundo parámetro `chunk_size` de la función. Si se omite, se define como `0`.

El búfer de salida iniciado con output_buffering definido como `"On"` tendrá su tamaño de búfer definido como `0`. Si se define como un entero, el tamaño del búfer corresponderá a ese número.

El tamaño del búfer de salida de `"URL-Rewriter"` se define como `0`, por lo que solo está limitado por la memoria disponible para PHP.

El tamaño del búfer de salida de `zlib` está controlado por el parámetro zlib.output_compression de php.ini. Si se define como `"On"`, el tamaño del búfer será `"16K"`/`16384`. Si se define como un entero, el tamaño del búfer corresponderá a ese número en bytes.

## Operaciones permitidas en los búferes

Las operaciones permitidas en los búferes pueden controlarse pasando uno de los flags de control de búfer al tercer parámetro `flags` de ob_start(). Si se omite, todas las operaciones están permitidas por defecto. Si se usa `0` en su lugar, el búfer no puede vaciarse, limpiarse ni desactivarse pero su contenido puede recuperarse.

`PHP_OUTPUT_HANDLER_CLEANABLE` permite a ob_clean() limpiar el contenido del búfer.

Advertencia

La ausencia del flag `PHP_OUTPUT_HANDLER_CLEANABLE` no evitará que ob_end_clean() o ob_get_clean() limpien el contenido del búfer.

`PHP_OUTPUT_HANDLER_FLUSHABLE` permite a ob_flush() vaciar el contenido del búfer.

Advertencia

La ausencia del flag `PHP_OUTPUT_HANDLER_FLUSHABLE` no evitará que ob_end_flush() o ob_get_flush() vacíen el contenido del búfer.

`PHP_OUTPUT_HANDLER_REMOVABLE` permite a ob_end_clean(), ob_end_flush(), ob_get_clean() o ob_get_flush() desactivar el búfer.

`PHP_OUTPUT_HANDLER_STDFLAGS`, la combinación de los tres flags, permite que cada una de las tres operaciones se realice en el búfer.

## Lavar, acceder y limpiar el contenido del búfer

Lavar envía y elimina el contenido del búfer activo. Los búferes de salida se lavan cuando el tamaño de la salida excede el tamaño del búfer, el script finaliza o se llama a ob_flush(), ob_end_flush(), o ob_get_flush().

Precaución

Llamar a ob_end_flush() o ob_get_flush() desactivará el búfer activo.

Precaución

Lavar los búferes lavará el valor de retorno del gestor de salida que puede diferir del contenido del búfer. Por ejemplo, usar ob_gzhandler() comprimirá la salida y lavará la salida comprimida.

El contenido del búfer activo puede recuperarse llamando a ob_get_contents() o ob_get_flush().

Si solo se necesita la longitud del contenido del búfer, ob_get_length() o ob_get_status() devolverá la longitud del contenido en bytes.

Precaución

Llamar a ob_get_clean() o ob_get_flush() desactivará el búfer activo después de devolver su contenido.

El contenido del búfer activo puede limpiarse llamando a ob_clean(), ob_end_clean() o ob_get_clean().

Precaución

Llamar a ob_end_clean() o ob_get_clean() desactivará el búfer activo.

## Desactivar los búferes

Los búferes de salida pueden desactivarse llamando a ob_end_clean(), ob_end_flush(), ob_get_flush() o ob_get_clean().

Advertencia

Los búferes de salida iniciados sin el flag `PHP_OUTPUT_HANDLER_REMOVABLE` no pueden desactivarse y generarán un `E_NOTICE`.

Cada búfer de salida que no haya sido desactivado al final del script o cuando se llama a exit() será lavado y desactivado por el proceso de terminación de PHP. Los búferes se lavarán y desactivarán en orden inverso a su inicio. El último búfer iniciado será el primero, el primer búfer iniciado será el último en lavarse y desactivarse.

Precaución

Si no se desea el lavado del contenido del búfer, debe usarse un gestor de salida personalizado para evitar el lavado al cerrar.

## Gestores de salida

Los gestores de salida son callables asociados a los búferes de salida que se invocan al llamar a ob_clean(), ob_flush(), ob_end_flush(), ob_get_flush(), ob_end_clean(), ob_get_clean() o durante el proceso de terminación de PHP.

> Nota: El proceso de terminación lavará los valores de retorno de los gestores de salida

Si se omite o es `null` al iniciar el búfer de salida se utilizará el gestor de salida interno `"gestor de salida por defecto"` que devuelve el contenido del búfer sin modificar cuando se invoca. Los gestores de salida pueden usarse para devolver una versión modificada del contenido del búfer y/o tener efectos secundarios (por ejemplo, enviar encabezados).

PHP incluye dos gestores de salida internos: `"default output handler"` (el gestor de salida por defecto) y `"URL-Rewriter"` (que está integrado en su propio búfer de salida y solo hasta dos instancias del mismo pueden iniciarse).

La extensión agrupada incluye cuatro gestores de salida adicionales: mb_output_handler(), ob_gzhandler(), ob_iconv_handler(), ob_tidyhandler().

## Trabajar con los gestores de salida

Al ser invocados, los gestores de salida reciben el contenido del búfer y una máscara que indica el estado de la bufferización de salida.

function handler ( string `$buffer` , int `$phase` = ?): string

`buffer`
  El contenido del búfer.
`phase`
  Una máscara de bits de las constantes `PHP_OUTPUT_HANDLER_*` .

Advertencia

Llamar a cualquiera de las siguientes funciones desde un gestor de salida resultará en un error fatal: ob_clean(), ob_end_clean(), ob_end_flush(), ob_flush(), ob_get_clean(), ob_get_flush(), ob_start().

> Nota: Si el `PHP_OUTPUT_HANDLER_DISABLED` de un gestor está definido, el gestor no será invocado al llamar a ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush() ob_get_clean(), ob_get_flush(), ob_clean(), ob_flush() o durante el proceso de terminación de PHP. Antes de PHP 8.4.0, este flag no tenía ningún efecto al llamar a las funciones ob_clean() o ob_flush().

> Nota: El directorio de trabajo del script puede cambiar dentro de la función de parada bajo ciertos servidores web, por ejemplo Apache o el servidor web integrado.

## Flags pasados a los gestores de salida

La máscara de bits pasada al segundo parámetro `phase` del gestor de salida proporciona información sobre la invocación del gestor.

> Nota: La máscara de bits puede incluir más de un flag y el operador `&` debe usarse para verificar si un flag está definido.

Advertencia

El valor de `PHP_OUTPUT_HANDLER_WRITE` y su alias `PHP_OUTPUT_HANDLER_CONT` es `0` por lo que si está definido no puede determinarse excepto usando un operador de igualdad (`==` o `===`).

Los siguientes flags están definidos en una fase específica del ciclo de vida del gestor: `PHP_OUTPUT_HANDLER_START` está definido cuando un gestor es invocado por primera vez. `PHP_OUTPUT_HANDLER_FINAL` o su alias `PHP_OUTPUT_HANDLER_END` está definido cuando un gestor es invocado por última vez, es decir, cuando se desactiva. Este flag también está definido cuando los búferes son desactivados por el proceso de terminación de PHP.

Los siguientes flags están definidos por una invocación específica del gestor: `PHP_OUTPUT_HANDLER_FLUSH` está definido cuando un gestor es invocado al llamar a ob_flush(). `PHP_OUTPUT_HANDLER_WRITE` o su alias `PHP_OUTPUT_HANDLER_CONT` está definido cuando el tamaño de su contenido es igual o excede el tamaño del búfer y el gestor es invocado mientras el búfer se lava automáticamente. `PHP_OUTPUT_HANDLER_FLUSH` está definido cuando un gestor es invocado al llamar a ob_clean(), ob_end_clean() o ob_get_clean(). Cuando se llama a ob_end_clean() o ob_get_clean() también se define `PHP_OUTPUT_HANDLER_FINAL`.

> Nota: Cuando se llama a ob_end_flush() o ob_get_flush() se define `PHP_OUTPUT_HANDLER_FINAL` pero `PHP_OUTPUT_HANDLER_FLUSH` no.

## Valores de retorno de los gestores de salida

El valor de retorno del gestor de salida se convierte internamente a una cadena siguiendo las semánticas de tipo estándar de PHP, con dos excepciones: los arrays y los booleanos.

Los arrays se convierten en la cadena `"Array"` pero el mensaje de advertencia `"Conversión de un array a cadena"` no se dispara.

Si el gestor de salida devuelve `false` se devuelve el contenido del búfer. Si el gestor devuelve `true` se devuelve una cadena vacía.

> Nota: Si un gestor devuelve `false` o lanza una excepción su flag `PHP_OUTPUT_HANDLER_DISABLED` está definido.

## Excepciones lanzadas en los gestores de salida

Si una excepción no capturada es lanzada en un gestor de salida el programa termina y el gestor es invocado por el proceso de terminación después de lo cual se devuelve el mensaje de error `"Excepción no capturada"`.

Si la excepción no capturada es lanzada en un gestor invocado por ob_flush(), ob_end_flush() o ob_get_flush(), el contenido del búfer se lava antes del mensaje de error.

Si una excepción no capturada es lanzada en un gestor de salida durante la terminación, el gestor termina y ni el contenido del búfer ni el mensaje de error son lavados.

> Nota: Si un gestor lanza una excepción su flag `PHP_OUTPUT_HANDLER_DISABLED` está definido.

## Errores generados en los gestores de salida

Si un error no fatal es generado en un gestor de salida el programa continúa su ejecución.

Si un error no fatal es generado en un gestor invocado por ob_flush(), ob_end_flush() o ob_get_flush(), el búfer vacía algunos datos dependiendo del valor de retorno del gestor. Si el gestor devuelve `false` el búfer y el mensaje de error son lavados. Si el gestor devuelve otra cosa, el valor de retorno del gestor es lavado pero no el mensaje de error.

> Nota: Si un gestor devuelve `false` su flag `PHP_OUTPUT_HANDLER_DISABLED` está definido.

Si un error fatal es generado en un gestor de salida el programa termina y el gestor es invocado por el proceso de terminación después de lo cual el mensaje de error es lavado.

Si el error fatal es generado en un gestor invocado por ob_flush(), ob_end_flush() o ob_get_flush(), el contenido del búfer es lavado antes del mensaje de error.

Si un error fatal es generado en un gestor de salida durante la terminación el programa termina sin lavar el contenido del búfer o el mensaje de error.

## Salida en los gestores de salida

En circunstancias específicas, la salida producida en el gestor es lavada con el contenido del búfer. Esta salida no se añade al búfer y no forma parte de la cadena devuelta por ob_get_flush().

Durante las operaciones de lavado de búfer (llamada a ob_flush(), ob_end_flush(), ob_get_flush() y durante la terminación) si el valor de retorno de un gestor es `false` el contenido del búfer es lavado seguido de la salida. Si el gestor no es invocado durante la terminación el gestor lanzando una excepción o la llamada a exit() resulta en el mismo comportamiento.

> Nota: Si un gestor devuelve `false` su flag `PHP_OUTPUT_HANDLER_DISABLED` está definido.

## Flags de estado de los gestores de salida

Los flags de estado de los gestores de la máscara de bits `flags` del búfer están definidos en cada invocación del gestor de salida y forman parte de la máscara de bits `flags` devuelta por ob_get_status(). Si el gestor se ejecuta con éxito y no devuelve `false`, `PHP_OUTPUT_HANDLER_STARTED` y `PHP_OUTPUT_HANDLER_PROCESSED` están definidos. Si el gestor devuelve `false` o lanza una excepción durante la ejecución, `PHP_OUTPUT_HANDLER_STARTED` y `PHP_OUTPUT_HANDLER_DISABLED` están definidos.

> Nota: Si `PHP_OUTPUT_HANDLER_DISABLED` de un gestor está definido, el gestor no será invocado al llamar a ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush() ob_get_clean(), ob_get_flush(), ob_clean(), ob_flush() o durante el proceso de terminación de PHP. Antes de PHP 8.4.0, este flag no tenía ningún efecto al llamar a las funciones ob_clean() o ob_flush().

# Ejemplos

## Tabla de contenidos

- Uso básico
- Uso de la reescritura de salida

## Uso básico

Ejemplo #1 Ejemplo de bufferización de salida

    <?php

    ob_start();
    echo "Bonjour\n";

    setcookie("cookiename", "cookiedata");

    ob_end_flush();

    ?>

En el ejemplo anterior, la instrucción echo se almacena en un buffer hasta la llamada a la función ob_end_flush(). Al mismo tiempo, la llamada a setcookie() ha tenido éxito en la creación de un cookie, sin generar errores. (Normalmente, los encabezados deben enviarse al navegador antes de los datos).

## Uso de la reescritura de salida

Desde PHP 7.1.0, output_add_rewrite_var(), output_reset_rewrite_vars() utiliza un buffer de salida dedicado. Es decir, no utiliza un buffer de salida trans sid.

Ejemplo #1 Ejemplo de reescritura de salida

    <?php
    // Este código funciona con PHP 7.1.0, 7.0.10, 5.6.25 y superior.

    // HTTP_HOST es el host objetivo por defecto. Definir manualmente para que el ejemplo de código funcione.
    $_SERVER['HTTP_HOST'] = 'php.net';

    // La reescritura de salida solo puede reescribir los form. Añadir a=href.
    // Las etiquetas pueden especificarse como tag_name=url_attr, por ejemplo img=src, iframe=src
    // No se permiten espacios entre los argumentos.
    // La etiqueta form es una etiqueta especial que añade un campo oculto.
    ini_set('url_rewriter.tags','a=href,form=');
    var_dump(ini_get('url_rewriter.tags'));

    // Esto se añade a la URL y al formulario
    output_add_rewrite_var('test', 'value');
    ?>
    <a href="//php.net/index.php?bug=1234">bug1234</a>
    <form action="https://php.net/?bug=1234&edit=1" method="post">
     <input type="text" name="title" />
    </form>

El ejemplo anterior mostrará:

    <a href="//php.net/?bug=1234&test=value">bug1234</a>
    <form action="https://php.net/?bug=1234&edit=1" method="post"><input type="hidden" name="test" value="value" />
     <input type="text" name="title" />
    </form>

Desde PHP 7.1.0, las funciones de reescritura de salida tienen sus propios parámetros INI, url_rewriter.tags y url_rewriter.hosts.

# Funciones del Control de la salida

# Ver también

Véase también header() y setcookie().

# flush

(PHP 4, PHP 5, PHP 7, PHP 8)

flush — Vacía los búferes de salida del sistema

### Descripción

function flush(): void

Vacía los búferes de escritura del sistema de PHP y del backend utilizado por PHP (por ejemplo: CGI, un servidor web). En un entorno de línea de comandos, flush() intentará vaciar únicamente el contenido de los búferes, mientras que en un contexto web, los encabezados y el contenido de los búferes son vaciados.

> Nota: flush() puede no poder sortear el esquema de almacenamiento en búfer del servidor web y no tiene ningún efecto sobre un almacenamiento en búfer lado-cliente en el navegador.

> Nota: Esta función no tiene ningún efecto sobre los gestores de salida de nivel usuario tales como aquellos iniciados por ob_start() o output_add_rewrite_var().

Advertencia

flush() puede interferir con los gestores de salida que definen y envían encabezados en un contexto web (por ejemplo, ob_gzhandler()) al enviar encabezados antes de que estos gestores puedan hacerlo.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | El envío de encabezados sin cuerpo tendrá éxito ahora en FastCGI.

### Ver también

- ob_flush() - Vacía (envía) el valor de retorno del manejador de salida activo.
- ob_clean() - Limpiar (borrar) el contenido del búfer de salida activo.
- ob_end_flush() - Vacía (envía) el valor de retorno del manejador de salida activo y desactiva el búfer de salida activo
- ob_end_clean() - Elimina (limpia) el contenido del búfer de salida activo y lo desactiva.

# ob_clean

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_clean — Limpiar (borrar) el contenido del búfer de salida activo.

### Descripción

function ob_clean(): bool

Esta función llama al gestor de salida (con el flag `PHP_OUTPUT_HANDLER_CLEAN`), ignora su valor de retorno y limpia (borra) el contenido del búfer de salida activo.

Esta función no desactiva el búfer de salida activo como lo hacen ob_end_clean() o ob_get_clean().

ob_clean() fallará sin un búfer de salida activo iniciado con el flag `PHP_OUTPUT_HANDLER_CLEANABLE`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Si la función falla, genera una `E_NOTICE`.

### Ver también

- ob_flush() - Vacía (envía) el valor de retorno del manejador de salida activo.
- ob_end_flush() - Vacía (envía) el valor de retorno del manejador de salida activo y desactiva el búfer de salida activo
- ob_end_clean() - Elimina (limpia) el contenido del búfer de salida activo y lo desactiva.

# ob_end_clean

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_end_clean — Elimina (limpia) el contenido del búfer de salida activo y lo desactiva.

### Descripción

function ob_end_clean(): bool

Esta función invoca al gestor de salida (con los flags `PHP_OUTPUT_HANDLER_CLEAN` y `PHP_OUTPUT_HANDLER_FINAL`), ignora su valor de retorno, ignora el contenido del búfer de salida activo y lo desactiva.

ob_end_clean() fallará sin un búfer de salida activo iniciado con el flag `PHP_OUTPUT_HANDLER_REMOVABLE`.

ob_end_clean() eliminará el contenido del búfer de salida activo incluso si fue iniciado sin el flag `PHP_OUTPUT_HANDLER_CLEANABLE`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Si la función falla, genera una `E_NOTICE`.

### Ejemplos

El siguiente ejemplo muestra una manera sencilla de deshacerse del contenido del búfer de salida activo:

Ejemplo #1 Ejemplo con ob_end_clean()

    <?php
    ob_start();
    echo 'Texto que no será mostrado.';
    ob_end_clean();
    ?>

### Ver también

- ob_start() - Activa el temporizador de salida
- ob_get_contents() - Devuelve el contenido del búfer de salida
- ob_clean() - Limpiar (borrar) el contenido del búfer de salida activo.
- ob_get_clean() - Obtiene el contenido del búfer de salida activo y lo desactiva
- ob_end_flush() - Vacía (envía) el valor de retorno del manejador de salida activo y desactiva el búfer de salida activo

# ob_end_flush

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_end_flush — Vacía (envía) el valor de retorno del manejador de salida activo y desactiva el búfer de salida activo

### Descripción

function ob_end_flush(): bool

Esta función llama al manejador de salida (con el flag `PHP_OUTPUT_HANDLER_FINAL`), vacía (envía) su valor de retorno, ignora el contenido del búfer de salida activo y desactiva este último.

ob_end_flush() fallará sin un búfer de salida activo iniciado con el flag `PHP_OUTPUT_HANDLER_REMOVABLE`.

ob_end_flush() vaciará (enviará) el valor de retorno del manejador de salida incluso si el búfer de salida activo ha sido iniciado sin el flag `PHP_OUTPUT_HANDLER_FLUSHABLE`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Si la función falla, genera una `E_NOTICE`.

### Ejemplos

Ejemplo #1 Ejemplo con ob_end_flush()

El ejemplo a continuación muestra un método simple para vaciar todos los búferes:

    <?php
    while (@ob_end_flush());
    ?>

### Ver también

- ob_start() - Activa el temporizador de salida
- ob_get_contents() - Devuelve el contenido del búfer de salida
- ob_flush() - Vacía (envía) el valor de retorno del manejador de salida activo.
- ob_get_flush() - Vacía (envía) el valor de retorno del gestor de salida activo, devuelve el contenido del búfer de salida activo y lo desactiva.
- ob_end_clean() - Elimina (limpia) el contenido del búfer de salida activo y lo desactiva.

# ob_flush

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_flush — Vacía (envía) el valor de retorno del manejador de salida activo.

### Descripción

function ob_flush(): bool

Esta función llama al manejador de salida (con el flag `PHP_OUTPUT_HANDLER_FLUSH`), vacía (envía) su valor de retorno e ignora el contenido del búfer de salida activo.

Esta función no desactiva el búfer de salida activo como lo hacen ob_end_flush() o ob_get_flush().

ob_flush() fallará sin un búfer de salida activo iniciado con el flag `PHP_OUTPUT_HANDLER_FLUSHABLE`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Si la función falla, genera una `E_NOTICE`.

### Ver también

- ob_start() - Activa el temporizador de salida
- ob_get_contents() - Devuelve el contenido del búfer de salida
- ob_end_flush() - Vacía (envía) el valor de retorno del manejador de salida activo y desactiva el búfer de salida activo
- ob_get_flush() - Vacía (envía) el valor de retorno del gestor de salida activo, devuelve el contenido del búfer de salida activo y lo desactiva.
- ob_clean() - Limpiar (borrar) el contenido del búfer de salida activo.

# ob_get_clean

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_get_clean — Obtiene el contenido del búfer de salida activo y lo desactiva

### Descripción

function ob_get_clean(): string|false

Esta función llama al gestor de salida (con los flags `PHP_OUTPUT_HANDLER_CLEAN` y `PHP_OUTPUT_HANDLER_FINAL`), ignora su valor de retorno, devuelve el contenido del búfer de salida activo y lo desactiva.

ob_get_clean() fallará sin un búfer de salida activo iniciado con el flag `PHP_OUTPUT_HANDLER_REMOVABLE`.

ob_get_clean() eliminará el contenido del búfer de salida activo incluso si fue iniciado sin el flag `PHP_OUTPUT_HANDLER_CLEANABLE`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el contenido del búfer de salida activo en caso de éxito o `false` en caso de fallo.

Precaución

ob_get_clean() devolverá false pero no generará una `E_NOTICE` si no hay un búfer de salida activo.

### Errores/Excepciones

Si la función falla, genera una `E_NOTICE`.

### Ejemplos

Ejemplo #1 Ejemplo con ob_get_clean()

    <?php

    ob_start();

    echo "¡Hola mundo!";

    $out = ob_get_clean();
    $out = strtolower($out);

    var_dump($out);
    ?>

El ejemplo anterior mostrará:

    string(18) "¡hola mundo!"

### Ver también

- ob_start() - Activa el temporizador de salida
- ob_get_contents() - Devuelve el contenido del búfer de salida
- ob_clean() - Limpiar (borrar) el contenido del búfer de salida activo.
- ob_end_clean() - Elimina (limpia) el contenido del búfer de salida activo y lo desactiva.
- ob_get_flush() - Vacía (envía) el valor de retorno del gestor de salida activo, devuelve el contenido del búfer de salida activo y lo desactiva.

# ob_get_contents

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_get_contents — Devuelve el contenido del búfer de salida

### Descripción

function ob_get_contents(): string|false

Devuelve el contenido del búfer de salida sin borrarlo.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el contenido del búfer de salida sin borrarlo o `false`, si la temporización de salida no está activada.

### Ejemplos

Ejemplo #1 Ejemplo con ob_get_contents()

    <?php

    ob_start();

    echo "Bonjour ";

    $out1 = ob_get_contents();

    echo "le monde !";

    $out2 = ob_get_contents();

    ob_end_clean();

    var_dump($out1, $out2);
    ?>

El ejemplo anterior mostrará:

    string(8) "Bonjour "
    string(18) "Bonjour le monde !"

### Ver también

- ob_start() - Activa el temporizador de salida
- ob_get_length() - Devuelve la longitud del contenido del búfer de salida

# ob_get_flush

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_get_flush — Vacía (envía) el valor de retorno del gestor de salida activo, devuelve el contenido del búfer de salida activo y lo desactiva.

### Descripción

function ob_get_flush(): string|false

Esta función llama al gestor de salida (con el flag `PHP_OUTPUT_HANDLER_FINAL`), envía (vacía) su valor de retorno, devuelve el contenido del búfer de salida activo y desactiva el búfer de salida activo.

ob_get_flush() fallará sin un búfer de salida activo iniciado con el flag `PHP_OUTPUT_HANDLER_REMOVABLE`.

ob_get_flush() vaciará (enviará) el valor de retorno del gestor de salida incluso si el búfer de salida activo ha sido iniciado sin el flag `PHP_OUTPUT_HANDLER_FLUSHABLE`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el contenido del búfer de salida activo en caso de éxito o `false` en caso de fallo.

### Errores/Excepciones

En caso de fallo de la función, genera una `E_NOTICE`.

### Ejemplos

Ejemplo #1 Ejemplo con ob_get_flush()

    <?php
    //Utilización de output_buffering=On
    print_r(ob_list_handlers());

    //Guardado del búfer en un fichero
    $buffer = ob_get_flush();
    file_put_contents('buffer.txt', $buffer);

    print_r(ob_list_handlers());
    ?>

El ejemplo anterior mostrará:

    Array
    (
        [0] => default output handler
    )
    Array
    (
    )

### Ver también

- ob_start() - Activa el temporizador de salida
- ob_get_contents() - Devuelve el contenido del búfer de salida
- ob_flush() - Vacía (envía) el valor de retorno del manejador de salida activo.
- ob_end_flush() - Vacía (envía) el valor de retorno del manejador de salida activo y desactiva el búfer de salida activo
- ob_get_clean() - Obtiene el contenido del búfer de salida activo y lo desactiva

# ob_get_length

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

ob_get_length — Devuelve la longitud del contenido del búfer de salida

### Descripción

function ob_get_length(): int|false

Devuelve la longitud del contenido del búfer de salida, en bytes.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la longitud del contenido del búfer de salida, en bytes, si la temporización está activada, y `false` en caso contrario.

### Ejemplos

Ejemplo #1 Ejemplo con ob_get_length()

    <?php

    ob_start();

    echo "Bonjour ";

    $len1 = ob_get_length();

    echo "le monde";

    $len2 = ob_get_length();

    ob_end_clean();

    echo $len1 . ", " . $len2;
    ?>

El ejemplo anterior mostrará:

    8, 16

### Ver también

- ob_start() - Activa el temporizador de salida
- ob_get_contents() - Devuelve el contenido del búfer de salida

# ob_get_level

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_get_level — Devuelve el número de niveles de anidación del sistema de temporización de salida

### Descripción

function ob_get_level(): int

Devuelve el número de niveles de anidación del sistema de temporización de salida.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de niveles de anidación del sistema de temporización de salida, y cero si no está activo.

Precaución

El valor para los niveles idénticos entre ob_get_level() y ob_get_status() difiere en uno. Para ob_get_level(), el primer nivel es `1`. Mientras que para ob_get_status(), el primer nivel es `0`.

### Ver también

- ob_start() - Activa el temporizador de salida
- ob_get_status() - Lee el estado del búfer de salida
- ob_get_contents() - Devuelve el contenido del búfer de salida

# ob_get_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_get_status — Lee el estado del búfer de salida

### Descripción

function ob_get_status(bool `$full_status` = `false`): array

ob_get_status() devuelve información sobre el estado del búfer de salida de alto nivel o de todos los búferes de salida si `full_status` está definido como `true`.

### Parámetros

`full_status`

  `true` para devolver todos los búferes de salida. Si es `false` o no está definido, solo se devolverá el estado del búfer de salida de alto nivel.

### Valores devueltos

Si el parámetro `full_status` está omitido o es igual a `false`, se devuelve un array simple que contiene información sobre el estado del nivel de salida activo.

Si el parámetro `full_status` es igual a `true`, se devuelve un array con un elemento para cada nivel de búfer de salida activo. El nivel de salida se utiliza como clave del array superior y cada elemento del array es a su vez otro array que contiene información sobre un nivel de salida activo.

Se devuelve un array vacío si la memoria intermedia de salida no está activada.

Elementos devueltos por la función ob_get_status()
Clave | Valor
--- | ---
name | Nombre del gestor de salida activo (ver los valores de retorno de ob_list_handlers() para más detalles)
type | `0` (gestor interno) o `1` (gestor proporcionado por el usuario)
flags | Máscara de bits de los indicadores definidos por la función ob_start(), el tipo de gestor de salida (ver arriba) y el estado del proceso de memoria intermedia ( `PHP_OUTPUT_HANDLER_*` constantes). Si el gestor ha procesado con éxito el búfer y no ha devuelto `false`, `PHP_OUTPUT_HANDLER_STARTED` y `PHP_OUTPUT_HANDLER_PROCESSED` estarán definidos. Si el gestor ha fallado al procesar el búfer o ha devuelto `false`, `PHP_OUTPUT_HANDLER_STARTED` y `PHP_OUTPUT_HANDLER_DISABLED` estarán definidos.
level | Nivel de anidación de la salida (a partir de cero). Tenga en cuenta que el valor devuelto para el mismo nivel por la función ob_get_level() está desplazado en uno. El primer nivel es `0` para ob_get_status(), y `1` para ob_get_level().
chunk_size | Tamaño del fragmento en bytes. Definido por la función ob_start() o output_buffering si está activado y su valor está definido como un entero positivo
buffer_size | Tamaño del búfer de salida en bytes
buffer_used | Tamaño de los datos en el búfer de salida en bytes (el mismo que el valor de retorno entero de ob_get_length())

### Ejemplos

Ejemplo #1 Array devuelto cuando el parámetro `full_status` es igual a `true`

    Array
    (
        [type] => 0
        [flags] => 112
        [level] => 2
        [chunk_size] => 0
        [buffer_size] => 16384
        [buffer_used] => 1024
    )

Ejemplo #2 Array devuelto cuando el parámetro `full_status` es igual a `true`

    Array
    (
        [0] => Array
            (
                [name] => default output handler
                [type] => 0
                [flags] => 112
                [level] => 1
                [chunk_size] => 0
                [buffer_size] => 16384
                [buffer_used] => 2048
            )

        [1] => Array
            (
                [name] => URL-Rewriter
                [type] => 0
                [flags] => 112
                [level] => 2
                [chunk_size] => 0
                [buffer_size] => 16384
                [buffer_used] => 1024
            )

    )

### Ver también

- ob_get_level() - Devuelve el número de niveles de anidación del sistema de temporización de salida
- ob_list_handlers() - Lista los gestores de salida utilizados
- ob_get_length() - Devuelve la longitud del contenido del búfer de salida
- ob_start() - Activa el temporizador de salida

# ob_implicit_flush

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_implicit_flush — Activa/desactiva el envío implícito

### Descripción

function ob_implicit_flush(bool `$enable` = `true`): void

ob_implicit_flush() activa/desactiva el envío implícito. La puesta en memoria intermedia implícita provocará una operación de volcado después de cada bloque de código que produzca una salida, de modo que no serán necesarios los llamados explícitos a flush().

> Nota: Mostrar strings vacíos o enviar encabezados no se considera una salida y no desencadenará una operación de volcado.

> Nota: Esta función no tiene ningún efecto sobre los gestores de salida de nivel usuario, tales como los iniciados por ob_start() o output_add_rewrite_var().

### Parámetros

`enable`

  `true` para activar, `false` en caso contrario.

### Valores devueltos

No se retorna ningún valor.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `enable` ahora espera un valor bool; anteriormente, se esperaba un int.

### Ver también

- flush() - Vacía los búferes de salida del sistema
- ob_start() - Activa el temporizador de salida
- ob_end_flush() - Vacía (envía) el valor de retorno del manejador de salida activo y desactiva el búfer de salida activo

# ob_list_handlers

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_list_handlers — Lista los gestores de salida utilizados

### Descripción

function ob_list_handlers(): array

Lista los gestores de salida utilizados.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array con el gestor de salida en uso (si existe).

Si output_buffering está activado y no se ha definido ningún output_handler, o si no se ha pasado ninguna función de retorno o `null` a ob_start(), se devuelve `"default output handler"`. Activar output_buffering y definir un output_handler equivale a pasar una función interna (integrada) a ob_start().

Si se ha pasado un callable a ob_start(), se devuelve el nombre completamente cualificado del callable. Si el callable es un objeto que implementa __invoke(), se devuelve el nombre completamente cualificado del método __invoke() del objeto. Si el callable es una Closure, se devuelve `"Closure::__invoke"`.

### Ejemplos

Ejemplo #1 Ejemplo con ob_list_handlers()

    <?php
    // uso de output_buffering=On, sin output_handler definido
    var_dump(ob_list_handlers());
    ob_end_flush();

    // ningún retorno o null
    ob_start();
    var_dump(ob_list_handlers());

    // Función anónima
    ob_start(function($string) { return $string; });
    var_dump(ob_list_handlers());
    ob_end_flush();

    // función flecha
    ob_start(fn($string) => $string);
    var_dump(ob_list_handlers());
    ob_end_flush();

    // callable de primera clase
    $firstClassCallable = userDefinedFunction(...);

    ob_start([$firstClassCallable, '__invoke']);
    var_dump(ob_list_handlers());
    ob_end_flush();

    // función interna (integrada)
    ob_start('print_r');
    var_dump(ob_list_handlers());
    ob_end_flush();

    // función definida por el usuario
    function userDefinedFunction($string, $flags) { return $string; };

    ob_start('userDefinedFunction');
    var_dump(ob_list_handlers());
    ob_end_flush();

    class MyClass {
        public static function staticHandle($string) {
            return $string;
        }

        public static function handle($string) {
            return $string;
        }

        public function __invoke($string) {
            return $string;
        }
    }

    // clase y método estático
    ob_start(['MyClass','staticHandle']);
    var_dump(ob_list_handlers());
    ob_end_flush();

    // objeto y método no estático
    ob_start([new MyClass,'handle']);
    var_dump(ob_list_handlers());
    ob_end_flush();

    // objeto invocable
    ob_start(new MyClass);
    var_dump(ob_list_handlers());
    ob_end_flush();
    ?>

El ejemplo anterior mostrará:

    array(1) {
      [0]=>
      string(22) "default output handler"
    }
    array(1) {
      [0]=>
      string(22) "default output handler"
    }
    array(1) {
      [0]=>
      string(7) "print_r"
    }
    array(1) {
      [0]=>
      string(19) "userDefinedFunction"
    }
    array(1) {
      [0]=>
      string(17) "Closure::__invoke"
    }
    array(1) {
      [0]=>
      string(17) "Closure::__invoke"
    }
    array(1) {
      [0]=>
      string(17) "Closure::__invoke"
    }
    array(1) {
      [0]=>
      string(21) "MyClass::staticHandle"
    }
    array(1) {
      [0]=>
      string(15) "MyClass::handle"
    }
    array(1) {
      [0]=>
      string(17) "MyClass::__invoke"
    }

### Ver también

- ob_end_clean() - Elimina (limpia) el contenido del búfer de salida activo y lo desactiva.
- ob_end_flush() - Vacía (envía) el valor de retorno del manejador de salida activo y desactiva el búfer de salida activo
- ob_get_flush() - Vacía (envía) el valor de retorno del gestor de salida activo, devuelve el contenido del búfer de salida activo y lo desactiva.
- ob_start() - Activa el temporizador de salida

# ob_start

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_start — Activa el temporizador de salida

### Descripción

function ob_start(?callable `$callback` = `null`, int `$chunk_size` = 0, int `$flags` = `PHP_OUTPUT_HANDLER_STDFLAGS`): bool

Esta función activa el almacenamiento en búfer de la salida. Cuando el almacenamiento en búfer está activo, ninguna salida es enviada desde el script; en su lugar, la salida se almacena en un búfer interno. Consulte ¿Qué salida está bufferizada? para saber exactamente qué salidas están afectadas.

Los búferes de salida son apilables, es decir ob_start() puede ser llamada mientras otro búfer está activo. Si varios búferes de salida están activos, la salida es filtrada secuencialmente a través de cada uno de ellos en el orden de anidación. Consulte Anidamiento de búferes de salida para más detalles.

Consulte Búferes de salida a nivel de usuario para una descripción detallada de los búferes de salida.

### Parámetros

`callback`

  Un `callback` callable opcional puede ser especificado. También puede ser omitido pasando `null`.

  `callback` es invocado cuando el búfer de salida es vaciado (enviado), limpiado, o cuando el búfer de salida es vaciado al final del script.

  La firma del `callback` es la siguiente:

  function handler(string `$buffer`, int `$phase` = ?): string
  `buffer`
    Contenido del buffer de salida.
  `phase`
    Máscara de bits de las constantes `PHP_OUTPUT_HANDLER_*` . Consulte Flags pasados a los gestores de salida para más detalles.

  Si `callback` devuelve `false`, el contenido del búfer es enviado. Consulte Valores de retorno de los gestores de salida para más detalles.

  Advertencia

  Llamar a alguna de las siguientes funciones desde un manejador de salida provocará un error fatal: ob_clean(), ob_end_clean(), ob_end_flush(), ob_flush(), ob_get_clean(), ob_get_flush(), ob_start().

  Consulte Gestores de salida y Trabajar con los gestores de salida para más detalles sobre los `callback`s (manejadores de salida).

`chunk_size`

  Si el parámetro opcional `chunk_size` es pasado, la función de devolución de llamada es llamada cada nueva línea después de `chunk_size` bytes de salida. El valor por omisión `0` significa que toda la salida es almacenada en búfer hasta que el búfer sea desactivado. Consulte Tamaño del búfer para más detalles.

`flags`

  El parámetro `flags` es una máscara que controla las operaciones que pueden ser realizadas sobre el búfer de salida. Por omisión, permite que el búfer de salida sea limpiado, enviado y eliminado, lo cual puede ser definido explícitamente con los indicadores de control del búfer . Consulte Operaciones permitidas en los búferes para más detalles.

  Cada flag controla el acceso a un conjunto de funciones, tal como se describe a continuación:

  Constante | Funciones
  --- | ---
  `PHP_OUTPUT_HANDLER_CLEANABLE` | ob_clean(),
  `PHP_OUTPUT_HANDLER_FLUSHABLE` | ob_flush(),
  `PHP_OUTPUT_HANDLER_REMOVABLE` | ob_end_clean(), ob_end_flush() y ob_get_clean(). ob_get_flush().

  > Nota: Antes de PHP 8.4.0, el parámetro flags podía definir los flags de estado del manejador de salida también.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de manejo de salida con función de devolución de llamada

    <?php

    function handler($buffer)
    {
      // reemplaza todas las patatas por zanahorias
      return (str_replace("pommes de terre", "carottes", $buffer));
    }

    ob_start("handler");

    ?>
    <html>
    <body>
    <p>Es como comparar zanahorias y patatas.</p>
    </body>
    </html>
    <?php

    ob_end_flush();

    ?>

El ejemplo anterior mostrará:

    <html>
    <body>
    <p>Es como comparar zanahorias y zanahorias.</p>
    </body>
    </html>

Ejemplo #2 Crea un búfer de salida no eliminable

    <?php

    ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^ PHP_OUTPUT_HANDLER_REMOVABLE);

    ?>

### Ver también

- ob_get_contents() - Devuelve el contenido del búfer de salida
- ob_end_clean() - Elimina (limpia) el contenido del búfer de salida activo y lo desactiva.
- ob_end_flush() - Vacía (envía) el valor de retorno del manejador de salida activo y desactiva el búfer de salida activo
- ob_implicit_flush() - Activa/desactiva el envío implícito
- ob_gzhandler() - Función de recuperación para la compresión automática de pastillas
- ob_iconv_handler() - Convierte la codificación de caracteres al manejador del buffer de salida
- mb_output_handler() - Función de tratamiento de los despliegues
- ob_tidyhandler() - Función callback de ob_start para reparar el buffer

# output_add_rewrite_var

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

output_add_rewrite_var — Añade una regla de reescritura de URL

### Descripción

function output_add_rewrite_var(string `$name`, string `$value`): bool

Esta función inicia el gestor de búfer de salida `'URL-Rewriter'` si no está activo, almacena los argumentos `name` y `value`, y cuando el búfer se vacía, reescribe las URLs y los formularios según los argumentos ini aplicables. Las llamadas posteriores a esta función almacenarán todas las parejas nombre/valor adicionales hasta que el gestor sea desactivado.

Cuando el búfer de salida se vacía (al llamar a ob_flush(), ob_end_flush(), ob_get_flush() o al final del script), el gestor `'URL-Rewriter'` añade las parejas nombre/valor como argumentos de consulta a las URLs en los atributos de las etiquetas HTML y añade campos ocultos a los formularios según los valores de las directivas de configuración url_rewriter.tags y url_rewriter.hosts.

Cada pareja nombre/valor añadida al gestor `'URL-Rewriter'` se añade a las URLs y/o formularios incluso si esto resulta en argumentos de consulta de URL duplicados o elementos con los mismos atributos de nombre.

> Nota: Una vez que el gestor `'URL-Rewriter'` ha sido desactivado, no puede ser reiniciado.

Advertencia

Antes de PHP 8.4.0, los hosts a reescribir se definían en session.trans_sid_hosts en lugar de url_rewriter.hosts.

### Parámetros

`name`

  El nombre de la variable.

`value`

  El valor de la variable.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
7.1.0 | A partir de PHP 7.1.0, se utiliza un búfer de salida dedicado, url_rewriter.tags se utiliza únicamente para las funciones de salida y url_rewriter.hosts está disponible. Anterior a PHP 7.1.0, las variables de reescritura definidas por output_add_rewrite_var() compartían un búfer de salida con el soporte transparente del ID de sesión (ver session.trans_sid_tags).

### Ejemplos

Ejemplo #1 Ejemplo con output_add_rewrite_var()

    <?php
    ini_set('url_rewriter.tags', 'a=href,form=');

    output_add_rewrite_var('var', 'value');

    // Algunos enlaces
    echo '<a href="file.php">link</a>
    <a href="http://example.com">link2</a>';

    // un formulario
    echo '<form action="script.php" method="post">
    <input type="text" name="var2" />
    </form>';

    print_r(ob_list_handlers());
    ?>

El ejemplo anterior mostrará:

    <a href="file.php?var=value">link</a>
    <a href="http://example.com">link2</a>

    <form action="script.php" method="post">
    <input type="hidden" name="var" value="value" />
    <input type="text" name="var2" />
    </form>

    Array
    (
        [0] => URL-Rewriter
    )

### Ver también

- output_reset_rewrite_vars() - Anula la reescritura de URL
- ob_flush() - Vacía (envía) el valor de retorno del manejador de salida activo.
- ob_list_handlers() - Lista los gestores de salida utilizados
- url_rewriter.tags
- url_rewriter.hosts

# output_reset_rewrite_vars

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

output_reset_rewrite_vars — Anula la reescritura de URL

### Descripción

function output_reset_rewrite_vars(): bool

Esta función elimina todas las variables de reescritura previamente definidas por la función output_add_rewrite_var().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
7.1.0 | Antes de PHP 7.1.0, las variables de reescritura definidas por output_add_rewrite_var() utilizaban el mismo buffer de salida del módulo de sesión trans sid. Desde PHP 7.1.0, se utiliza un buffer de salida dedicado y output_reset_rewrite_vars() elimina únicamente las vars de reescritura definidas por output_add_rewrite_var().

### Ejemplos

Ejemplo #1 Ejemplo con output_reset_rewrite_vars()

    <?php
    ini_set('url_rewriter.tags', 'a=href');

    output_add_rewrite_var('var', 'value');

    echo '<a href="file.php">link</a>';
    ob_flush();

    output_reset_rewrite_vars();
    echo '<a href="file.php">link</a>';
    ?>

El ejemplo anterior mostrará:

    <a href="file.php?var=value">link</a>
    <a href="file.php">link</a>

### Ver también

- output_add_rewrite_var() - Añade una regla de reescritura de URL
- ob_flush() - Vacía (envía) el valor de retorno del manejador de salida activo.
- ob_list_handlers() - Lista los gestores de salida utilizados
- url_rewriter.tags
- url_rewriter.hosts
- session.trans_sid_tags
- session.trans_sid_hosts

## Tabla de contenidos

- flush — Vacía los búferes de salida del sistema
- ob_clean — Limpiar (borrar) el contenido del búfer de salida activo.
- ob_end_clean — Elimina (limpia) el contenido del búfer de salida activo y lo desactiva.
- ob_end_flush — Vacía (envía) el valor de retorno del manejador de salida activo y desactiva el búfer de salida activo
- ob_flush — Vacía (envía) el valor de retorno del manejador de salida activo.
- ob_get_clean — Obtiene el contenido del búfer de salida activo y lo desactiva
- ob_get_contents — Devuelve el contenido del búfer de salida
- ob_get_flush — Vacía (envía) el valor de retorno del gestor de salida activo, devuelve el contenido del búfer de salida activo y lo desactiva.
- ob_get_length — Devuelve la longitud del contenido del búfer de salida
- ob_get_level — Devuelve el número de niveles de anidación del sistema de temporización de salida
- ob_get_status — Lee el estado del búfer de salida
- ob_implicit_flush — Activa/desactiva el envío implícito
- ob_list_handlers — Lista los gestores de salida utilizados
- ob_start — Activa el temporizador de salida
- output_add_rewrite_var — Añade una regla de reescritura de URL
- output_reset_rewrite_vars — Anula la reescritura de URL

- Instalación/Configuración
  - Configuración en tiempo de ejecución
- Constantes predefinidas
- Bufferización de salida
- Vaciar los búferes del sistema
- Búferes de salida a nivel de usuario
  - ¿Qué salida está bufferizada?
  - Anidamiento de búferes de salida
  - Tamaño del búfer
  - Operaciones permitidas en los búferes
  - Gestores de salida
  - Trabajar con los gestores de salida
  - Flags pasados a los gestores de salida
  - Valores de retorno de los gestores de salida
- Ejemplos
  - Uso básico
  - Uso de la reescritura de salida
- Funciones del Control de la salida
  - flush — Vacía los búferes de salida del sistema
  - ob_clean — Limpiar (borrar) el contenido del búfer de salida activo.
  - ob_end_clean — Elimina (limpia) el contenido del búfer de salida activo y lo desactiva.
  - ob_end_flush — Vacía (envía) el valor de retorno del manejador de salida activo y desactiva el búfer de salida activo
  - ob_flush — Vacía (envía) el valor de retorno del manejador de salida activo.
  - ob_get_clean — Obtiene el contenido del búfer de salida activo y lo desactiva
  - ob_get_contents — Devuelve el contenido del búfer de salida
  - ob_get_flush — Vacía (envía) el valor de retorno del gestor de salida activo, devuelve el contenido del búfer de salida activo y lo desactiva.
  - ob_get_length — Devuelve la longitud del contenido del búfer de salida
  - ob_get_level — Devuelve el número de niveles de anidación del sistema de temporización de salida
  - ob_get_status — Lee el estado del búfer de salida
  - ob_implicit_flush — Activa/desactiva el envío implícito
  - ob_list_handlers — Lista los gestores de salida utilizados
  - ob_start — Activa el temporizador de salida
  - output_add_rewrite_var — Añade una regla de reescritura de URL
  - output_reset_rewrite_vars — Anula la reescritura de URL

# Opciones e Información de PHP

# Introducción

Estas funciones permiten obtener mucha información sobre PHP, p.ej., configuración en tiempo de ejecución, extensiones en uso, versión, y mucho más. También se pueden encontrar funciones para establecer opciones al ejecutar PHP. Aquí se puede encontrar la función probablemente más conocida de PHP - phpinfo() -.

# Instalación/Configuración

## Tabla de contenidos

- Configuración en tiempo de ejecución

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
assert.active | "1" | `INI_ALL` | Obsoleto a partir de PHP 8.3.0
assert.bail | "0" | `INI_ALL` | Obsoleto a partir de PHP 8.3.0
assert.warning | "1" | `INI_ALL` | Obsoleto a partir de PHP 8.3.0
assert.callback | NULL | `INI_ALL` | Obsoleto a partir de PHP 8.3.0
assert.quiet_eval | "0" | `INI_ALL` | Eliminado a partir de PHP 8.0.0
assert.exception | "1" | `INI_ALL` | Anterior a PHP 8.0.0, el valor por defecto es `"0"` Obsoleto a partir de PHP 8.3.0
enable_dl | "1" | `INI_SYSTEM` | Esta funcionalidad obsoleta será ciertamente eliminada en el futuro.
max_execution_time | "30" | `INI_ALL` |
max_input_time | "-1" | `INI_PERDIR` |
max_input_nesting_level | "64" | `INI_PERDIR` |
max_input_vars | 1000 | `INI_PERDIR` |
zend.enable_gc | "1" | `INI_ALL` |
zend.max_allowed_stack_size | "0" | `INI_SYSTEM` | Disponible a partir de PHP 8.3.0.
zend.reserved_stack_size | "0" | `INI_SYSTEM` | Disponible a partir de PHP 8.3.0.
fiber.stack_size |  | `INI_ALL` | Disponible a partir de PHP 8.1.0.

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`assert.active` bool

  Activa las evaluaciones de tipo assert(). zend.assertions debería ser utilizado en su lugar para controlar el comportamiento de assert().

  Advertencia

  Esta característica está OBSOLETA a partir de PHP 8.3.0. Depender de esta característica está altamente desaconsejado.

`assert.bail` bool

  Termina el script si una aserción falla.

  Advertencia

  Esta característica está OBSOLETA a partir de PHP 8.3.0. Depender de esta característica está altamente desaconsejado.

`assert.warning` bool

  Emite una alerta PHP para cada aserción que falle.

  Advertencia

  Esta característica está OBSOLETA a partir de PHP 8.3.0. Depender de esta característica está altamente desaconsejado.

`assert.callback` string

  Función definida por el programador, a llamar para cada aserción fallida.

  Advertencia

  Esta característica está OBSOLETA a partir de PHP 8.3.0. Depender de esta característica está altamente desaconsejado.

`assert.quiet_eval` bool
  Advertencia

  Esta característica ha sido ELIMINADA a partir de PHP 8.0.0.

  Utiliza la configuración actual de error_reporting() durante las evaluaciones de aserciones. Si está activada, ningún error es mostrado (error_reporting(0) implícito) durante la evaluación. Si está desactivada, los errores son mostrados según la configuración de error_reporting()

`assert.exception` bool

  Lanza una excepción AssertionError cuando una aserción falla.

  Advertencia

  Esta característica está OBSOLETA a partir de PHP 8.3.0. Depender de esta característica está altamente desaconsejado.

`enable_dl` bool

  Esta directiva permite activar o desactivar la carga dinámica de extensiones PHP con la función PHP dl().

  La razón principal para desactivar este sistema es la seguridad. Con la carga dinámica, es posible eludir las restricciones impuestas por open_basedir.

`max_execution_time` int

  Establece el tiempo máximo de ejecución de un script, en segundos. Esto evita que los scripts en bucles infinitos saturen el servidor. La configuración por defecto es de `30` segundos. Cuando PHP funciona desde la línea de comando, el valor por defecto es `0`.

  En sistemas no-Windows, el tiempo máximo de ejecución no se ve afectado por llamadas al sistema como sleep(). Consulte la función set_time_limit() para más detalles.

  El servidor web puede tener otras configuraciones de tiempo límite de ejecución que también pueden interrumpir PHP. Apache tiene una directiva `Timeout` e IIS tiene una función CGI para ello. Por defecto, ambas valen 300 segundos. Consulte la documentación del servidor web para más detalles.

`max_input_time` int

  Esta opción especifica la duración máxima para analizar los datos de entrada, como POST y GET. Esta duración se mide desde el momento en que PHP es invocado en el servidor hasta el inicio de la ejecución del script. El valor por defecto es `-1`, lo que significa que max_execution_time es utilizado en su lugar. Establecer el valor a `0` para permitir una ejecución ilimitada.

`max_input_nesting_level` int

  Define la profundidad máxima de las variables de entrada (es decir, $_GET, $_POST..)

`max_input_vars` int

  El número de variables de entrada que pueden ser aceptadas (este límite se aplica a las variables superglobales $_GET, $_POST y $_COOKIE, por separado). El uso de esta directiva permite limitar las posibilidades de ataque por denegación de servicio utilizando colisiones de hash. Si hay más variables de entrada que el número especificado por esta directiva, una alerta de tipo `E_WARNING` será emitida, y las variables adicionales serán eliminadas de la solicitud.

`zend.enable_gc` bool

  Activa o desactiva la recolección de referencias circulares.

`zend.max_allowed_stack_size` int

  La cantidad máxima de memoria de pila nativa (stack) permitida por el sistema operativo para el programa. Intentar consumir más de lo que el sistema permite generalmente resulta en un fallo brusco, sin información de depuración fácilmente disponible. Para facilitar la depuración, el motor lanza una Error antes de que esto ocurra (cuando el programa utiliza más de zend.max_allowed_stack_size-zend.reserved_stack_size bytes de pila).

  La recursión en el código definido por el usuario no consume pila nativa. Sin embargo, las funciones internas y los métodos mágicos, sí consumen pila nativa. Una recursión muy profunda que involucre estas funciones puede hacer que el programa agote toda la memoria de pila disponible.

  Los valores posibles para este parámetro son:

  - `0` : Detectar automáticamente la memoria de pila nativa máxima que el sistema operativo permite para el programa. Este es el valor por defecto. Cuando la detección es imposible, se utiliza un valor por defecto del sistema.
  - `-1` : Desactiva la verificación del tamaño de la pila en el motor.
  - Entero positivo : Un tamaño fijo, en bytes. Establecer este valor demasiado alto equivale a desactivar la verificación de la tamaño de la pila.

  Como el tamaño de pila de las fibers está determinado por fiber.stack_size, el valor de este parámetro es utilizado en lugar de zend.max_allowed_stack_size durante la verificación del uso de la pila durante la ejecución de una Fiber.

  > Nota:

  > Esto no tiene ninguna relación con los desbordamientos de búfer de pila (stack buffer overflows), y no es una funcionalidad de seguridad.

`zend.reserved_stack_size` int

  El tamaño reservado de la pila, en bytes. Este se resta de la tamaño máximo de pila permitido, como un margen de seguridad, durante la verificación del tamaño de la pila.

  Los valores posibles para este parámetro son:

  - `0` : Detectar automáticamente un tamaño razonable.
  - Entero positivo : Un tamaño fijo, en bytes.
`fiber.stack_size` int

  El tamaño de la pila nativa, en bytes, asignada a cada Fiber.

  El valor por defecto es de 1 Mio en sistemas donde el tamaño de los punteros es inferior a 8 bytes, o de 2 Mio en caso contrario.

# Constantes predefinidas

Las constantes listadas aquí están siempre disponibles en PHP.

Constantes | Descripción
--- | ---
Constantes predefinidas de phpcredits()
`CREDITS_GROUP` (int) | Una lista de los desarrolladores principales
`CREDITS_GENERAL` (int) | Créditos generales. Diseño del lenguaje, conceptos, autores de PHP y módulo SAPI.
`CREDITS_SAPI` (int) | Una lista de las API de servidores, y sus autores.
`CREDITS_MODULES` (int) | Una lista de las extensiones de PHP, y sus autores
`CREDITS_DOCS` (int) | Los créditos del equipo de documentación
`CREDITS_FULLPAGE` (int) | Generalmente utilizado combinado con otras opciones. Esta opción indica que debe generarse una página HTML completa.
`CREDITS_QA` (int) | Los créditos para el grupo de aseguramiento de calidad.
`CREDITS_ALL` (int) | Todos los créditos. Es el equivalente a: `CREDITS_DOCS | CREDITS_GENERAL | CREDITS_GROUP | CREDITS_MODULES | CREDITS_QA | CREDITS_FULLPAGE`. Genera una página HTML completa y autónoma. Es el valor por omisión.

Constantes | Descripción
--- | ---
Constantes de phpinfo()
`INFO_GENERAL` (int) | La línea de configuración, la ruta del php.ini, la fecha de compilación, el sistema y más.
`INFO_CREDITS` (int) | Créditos de PHP. Véase también phpcredits().
`INFO_CONFIGURATION` (int) | Valores locales y de servidor de las directivas PHP. Véase también ini_get().
`INFO_MODULES` (int) | Los módulos cargados y sus configuraciones respectivas.
`INFO_ENVIRONMENT` (int) | Las variables de entorno, que también están disponibles en $_ENV.
`INFO_VARIABLES` (int) | Todas las variables predefinidas : `EGPCS` (Entorno, GET, POST, Cookie, Servidor).
`INFO_LICENSE` (int) | La licencia de PHP. Véase también la » FAQ de la licencia.
`INFO_ALL` (int) | Muestra todos los valores citados anteriormente. Es el valor por omisión.

Constantes | Descripción
--- | ---
Constantes modo INI
`INI_USER` (int) | Esta entrada puede ser definida en los scripts de usuario (como con ini_set()) o en el registro de Windows. La entrada puede ser definida en el fichero .user.ini.
`INI_PERDIR` (int) | Esta entrada puede ser definida en el fichero php.ini, .htaccess, httpd.conf o .user.ini.
`INI_SYSTEM` (int) | Esta entrada puede ser definida en el fichero php.ini o httpd.conf.
`INI_ALL` (int) | Esta entrada puede ser definida en cualquier lugar.

Las constantes de aserciones sirven con la función assert_options().

Constantes | Descripción
--- | ---
Constantes de assert()
`ASSERT_ACTIVE` (int) | Activa la evaluación assert(). Advertencia Esta característica está OBSOLETA a partir de PHP 8.3.0. Depender de esta característica está altamente desaconsejado.
`ASSERT_CALLBACK` (int) | Función de retrollamada de aserciones fallidas. Advertencia Esta característica está OBSOLETA a partir de PHP 8.3.0. Depender de esta característica está altamente desaconsejado.
`ASSERT_BAIL` (int) | Termina la ejecución de aserciones fallidas. Advertencia Esta característica está OBSOLETA a partir de PHP 8.3.0. Depender de esta característica está altamente desaconsejado.
`ASSERT_EXCEPTION` (int) | Lanza una AssertionError para cada aserción fallida. Advertencia Esta característica está OBSOLETA a partir de PHP 8.3.0. Depender de esta característica está altamente desaconsejado.
`ASSERT_WARNING` (int) | Emite una alerta PHP para cada aserción fallida. Advertencia Esta característica está OBSOLETA a partir de PHP 8.3.0. Depender de esta característica está altamente desaconsejado.
`ASSERT_QUIET_EVAL` (int) | Desactiva el `error_reporting` durante la evaluación de las expresiones de aserción. Advertencia Esta característica ha sido ELIMINADA a partir de PHP 8.0.0.

Las constantes siguientes solo están disponibles si el sistema de alojamiento es Windows, y pueden proporcionar información sobre las versiones, lo que permite detectar la presencia de funcionalidades. Están disponibles desde PHP 5.3.0.

Constantes | Descripción
--- | ---
Constantes particulares a Windows
`PHP_WINDOWS_VERSION_MAJOR` (int) | La versión mayor de Windows, que puede ser `4` (NT4/Me/98/95), `5` (XP/2003 R2/2003/2000) o `6` (Vista/2008/7/8/8.1).
`PHP_WINDOWS_VERSION_MINOR` (int) | La versión menor de Windows, que puede ser `0` (Vista/2008/2000/NT4/95), `1` (XP), `2` (2003 R2/2003/XP x64), `10` (98) o `90` (ME).
`PHP_WINDOWS_VERSION_BUILD` (int) | El número de compilación de Windows (por ejemplo, Windows Vista con SP1 tiene el número 6001)
`PHP_WINDOWS_VERSION_PLATFORM` (int) | La plataforma que PHP utiliza actualmente: este valor puede ser `2` en Windows Vista/XP/2000/NT4, Server 2008/2003 y en Windows ME/98/95 este valor es `1`.
`PHP_WINDOWS_VERSION_SP_MAJOR` (int) | La versión mayor del paquete de servicio instalado: este valor es `0` si ningún paquete de servicio está disponible. Por ejemplo, Windows XP con el paquete de servicio 3 da el valor `3` a esta constante.
`PHP_WINDOWS_VERSION_SP_MINOR` (int) | La versión menor del paquete de servicio instalado. Este valor es `0` si ningún paquete de servicio está instalado.
`PHP_WINDOWS_VERSION_SUITEMASK` (int) | La máscara es un campo de bits que permite conocer la presencia de diferentes funcionalidades de Windows. Vea la tabla a continuación para conocer los diferentes campos.
`PHP_WINDOWS_VERSION_PRODUCTTYPE` (int) | Esta constante contiene el valor utilizado para determinar el valor de las constantes `PHP_WINDOWS_NT_*`. Este valor puede ser una de las constantes `PHP_WINDOWS_NT_*`, indicando el tipo de plataforma.
`PHP_WINDOWS_NT_DOMAIN_CONTROLLER` (int) | El controlador de dominio.
`PHP_WINDOWS_NT_SERVER` (int) | Un servidor de sistema (ej. `Server 2008/2003/2000`). Tenga en cuenta que si es un controlador de dominio, se indica en `PHP_WINDOWS_NT_DOMAIN_CONTROLLER`.
`PHP_WINDOWS_NT_WORKSTATION` (int) | Un puesto de trabajo (ej. `Vista/XP/2000/NT4`)

La tabla a continuación presenta las funcionalidades que pueden ser verificadas en el campo de bits de la constante `PHP_WINDOWS_VERSION_SUITEMASK`.

Campos de la máscara Windows
Bits | Descripción
--- | ---
`0x00000004` | Los componentes Microsoft BackOffice están instalados.
`0x00000400` | Windows Server 2003, Web Edition está instalado.
`0x00004000` | Windows Server 2003, Compute Cluster Edition está instalado.
`0x00000080` | Windows Server 2008 Datacenter, Windows Server 2003, Datacenter Edition o Windows 2000 Datacenter Server está instalado.
`0x00000002` | Windows Server 2008 Enterprise, Windows Server 2003, Enterprise Edition, Windows 2000 Advanced Server, o Windows NT Server 4.0 Enterprise Edition está instalado.
`0x00000040` | Windows XP Embedded está instalado.
`0x00000200` | Windows Vista Home Premium, Windows Vista Home Basic, o Windows XP Home Edition está instalado.
`0x00000100` | Remote Desktop es soportado, pero solo una sesión interactiva es soportada. Este valor está presente, a menos que el sistema no funcione en modo servidor de aplicación.
`0x00000001` | Microsoft Small Business Server fue instalado en el sistema, pero fue actualizado a una nueva versión de Windows.
`0x00000020` | Microsoft Small Business Server está instalado con la licencia cliente restringida.
`0x00002000` | Windows Storage Server 2003 R2 o Windows Storage Server 2003 está instalado.
`0x00000010` | Terminal Services está instalado. Este valor siempre está activado. Si este valor está activado, pero `0x00000100` no lo está, entonces el sistema funciona en modo de servidor de aplicación.
`0x00008000` | Windows Home Server está instalado.

# Funciones de Opciones/Info de PHP

# assert

(PHP 4, PHP 5, PHP 7, PHP 8)

assert — Verifica una aserción

### Descripción

function assert(mixed `$assertion`, Throwable|string|null `$description` = `null`): bool

assert() permite definir expectativas: aserciones que tienen efecto en los entornos de desarrollo y prueba, pero que están optimizadas para no tener costo en producción.

Las aserciones pueden ser utilizadas para ayudar en la depuración. Un caso de uso para las aserciones es servir como verificaciones de coherencia para precondiciones que deberían siempre ser `true`, y si no lo son, esto indica errores de programación. Otro caso de uso es garantizar la presencia de ciertas funcionalidades tales como funciones de extensión o ciertos límites y funcionalidades del sistema.

Como las aserciones pueden ser configuradas para ser eliminadas, no deben ser utilizadas para operaciones normales en tiempo de ejecución, tales como verificaciones de parámetros de entrada. En general, el código debe comportarse como se espera incluso si la verificación de aserciones está desactivada.

assert() verificará que la expectativa dada en `assertion` sea satisfecha. Si no lo es y por lo tanto el resultado es `false`, tomará la acción apropiada según la configuración de assert().

El comportamiento de assert() está dictado por los siguientes parámetros INI:

Assert Opciones de configuración
Nombre | Por defecto | Descripción | Historial de cambios
--- | --- | --- | ---
zend.assertions | `1` | `1` : genera y ejecuta el código (modo desarrollo) `0` : genera el código pero lo evita en tiempo de ejecución `-1` : no genera el código (modo producción)
assert.active | `true` | Si `false`, assert() no verifica la expectativa y siempre devuelve `true`, sin condición. | Deprecado a partir de PHP 8.3.0.
assert.callback | `null` | Una función definida por el usuario a llamar cuando una aserción falla. Su firma debería ser: function assert_callback( string `$file`, int `$line`, null `$assertion`, string `$description` = ? ): void | Anterior a PHP 8.0.0, la firma de la función de devolución de llamada debería ser: function assert_callback( string `$file`, int `$line`, string `$assertion`, string `$description` = ? ): void Deprecado a partir de PHP 8.3.0.
assert.exception | `true` | Si `true`, lanzará una AssertionError si la expectativa no es cumplida. | Deprecado a partir de PHP 8.3.0.
assert.bail | `false` | Si `true`, interrumpirá la ejecución del script PHP si la expectativa no es cumplida. | Deprecado a partir de PHP 8.3.0.
assert.warning | `true` | Si `true`, emitirá un `E_WARNING` si la expectativa no es cumplida. Este parámetro INI es ineficaz si assert.exception está activado. | Deprecado a partir de PHP 8.3.0.

### Parámetros

`assertion`

  Esta es cualquier expresión que devuelve un valor, que será ejecutada y cuyo resultado será utilizado para indicar si la aserción tuvo éxito o falló.

  Advertencia

  Anterior a PHP 8.0.0, si `assertion` era una string, era interpretada como código PHP y ejecutada vía eval(). Esta cadena era pasada a la función de devolución de llamada como tercer argumento. Este comportamiento estaba DEPRECADO en PHP 7.2.0, y es ELIMINADO a partir de PHP 8.0.0

`description`

  Si `description` es una instancia de Throwable, será lanzada únicamente si `assertion` es ejecutada y falla.

  > Nota:

  > A partir de PHP 8.0.0, esto se hace antes de llamar a la función de devolución de llamada de aserción eventualmente definida

  > Nota:

  > A partir de PHP 8.0.0, el objeto object será lanzado independientemente de la configuración de assert.exception.

  > Nota:

  > A partir de PHP 8.0.0, el parámetro assert.bail no tiene ningún efecto en este caso.

  Si `description` es una string, este mensaje será utilizado si se emite una excepción o advertencia. Una descripción opcional, que será incluida en el mensaje de fallo si la `assertion` falla.

  Si `description` es omitido. Se crea una descripción por defecto equivalente al código fuente de la llamada a assert() en tiempo de compilación.

### Valores devueltos

assert() siempre devolverá `true` si al menos una de las siguientes condiciones es verdadera:

- `zend.assertions=0`
- `zend.assertions=-1`
- `assert.active=0`
- `assert.exception=1`
- `assert.bail=1`
- Un objeto de excepción personalizado es pasado a `description`.

Si ninguna de las condiciones es verdadera, assert() devolverá `true` si `assertion` es verdadero, y `false` de lo contrario.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Todas las configuraciones INI `assert.` han sido depreciadas.
8.0.0 | La función assert() ya no evaluará argumentos de tipo string, en su lugar, serán tratados como cualquier otro argumento. `assert($a == $b)` debería ser utilizado en lugar de `assert('$a == $b')`. La directiva `assert.quiet_eval` php.ini y la constante `ASSERT_QUIET_EVAL` también han sido eliminadas, ya que no tendrían ningún efecto.
8.0.0 | Si `description` es una instancia de Throwable, el objeto es lanzado si la aserción falla, independientemente del valor de assert.exception.
8.0.0 | Si `description` es una instancia de Throwable, ninguna función de devolución de llamada de usuario es llamada incluso si está definida.
8.0.0 | Declarar una función que se llame `assert()` dentro de un espacio de nombres ya no es permitido, y genera una `E_COMPILE_ERROR`.
7.3.0 | Declarar una función que se llame `assert()` dentro de un espacio de nombres se ha depreciado. Tales declaraciones generan ahora una `E_DEPRECATED`.
7.2.0 | El uso de una string como `assertion` se ha depreciado. Esto emite ahora una advertencia `E_DEPRECATED` cuando assert.active y zend.assertions están ambos definidos a `1`.

### Ejemplos

Ejemplo #1 Ejemplo de assert()

    <?php
    assert(1 > 2);
    echo '¡Hola!';
    ?>

Si las aserciones están activadas (`zend.assertions=1`) el ejemplo anterior mostraría:

    Fatal error: Uncaught AssertionError: assert(1 > 2) in example.php:2
    Stack trace:
    #0 example.php(2): assert(false, 'assert(1 > 2)')
    #1 {main}
      thrown in example.php on line 2

Si las aserciones están desactivadas (`zend.assertions=0` o `zend.assertions=-1`) el ejemplo anterior mostraría:

    ¡Hola!

Ejemplo #2 Uso de un mensaje personalizado

    <?php
    assert(1 > 2, "Se esperaba que uno fuera mayor que dos");
    echo '¡Hola!';
    ?>

Si las aserciones están activadas, el ejemplo anterior mostraría: el ejemplo anterior mostraría:

    Fatal error: Uncaught AssertionError: Se esperaba que uno fuera mayor que dos in example.php:2
    Stack trace:
    #0 example.php(2): assert(false, 'Se esperaba que uno...')
    #1 {main}
      thrown in example.php on line 2

Si las aserciones están desactivadas, el ejemplo anterior mostraría: el ejemplo anterior mostraría:

    ¡Hola!

Ejemplo #3 Uso de una clase de excepción personalizada

    <?php
          class ArithmeticAssertionError extends AssertionError {}

          assert(1 > 2, new ArithmeticAssertionError("Se esperaba que uno fuera mayor que dos"));
          echo '¡Hola!';

Si las aserciones están activadas, el ejemplo anterior mostraría: el ejemplo anterior mostraría:

    Fatal error: Uncaught ArithmeticAssertionError: Se esperaba que uno fuera mayor que dos in example.php:4
    Stack trace:
    #0 {main}
      thrown in example.php on line 4

Si las aserciones están desactivadas, el ejemplo anterior mostraría:

    ¡Hola!

### Ver también

- assert_options() - Define/recupere diferentes opciones de aserciones

# assert_options

(PHP 4, PHP 5, PHP 7, PHP 8)

assert_options — Define/recupere diferentes opciones de aserciones

Advertencia

Esta función está OBSOLETA a partir de PHP 8.3.0. Depender de esta función está altamente desaconsejado.

### Descripción

function assert_options(int `$option`, mixed `$value` = ?): mixed

assert_options() permite modificar las diversas opciones de la función assert(), o simplemente conocer la configuración actual.

> Nota: El uso de assert_options() no se recomienda en favor de definir y recuperar las directivas php.ini zend.assertions y assert.exception con ini_set() y ini_get(), respectivamente.

### Parámetros

`option`

  Opciones de aserciones
  Opción | Directiva | Valor por omisión | Descripción
  --- | --- | --- | ---
  ASSERT_ACTIVE | assert.active | 1 | Activa la evaluación de la función assert()
  ASSERT_EXCEPTION | assert.exception | 1 | Lanza una AssertionError para cada aserción fallida
  ASSERT_WARNING | assert.warning | 1 | Genera una alerta PHP para cada aserción falsa
  ASSERT_BAIL | assert.bail | 0 | Termina la ejecución en caso de aserción falsa
  ASSERT_QUIET_EVAL | assert.quiet_eval | 0 | Desactiva el informe de error durante la evaluación de una aserción. Eliminada a partir de PHP 8.0.0
  ASSERT_CALLBACK | assert.callback | (`null`) | Función de devolución de llamada del usuario, para el tratamiento de aserciones falsas

`value`

  Un nuevo valor, opcional, para la opción.

  La función de devolución de llamada definida mediante `ASSERT_CALLBACK` o assert.callback debería tener la siguiente firma:

  function assert_callback(
  string `$file`,
  int `$line`,
  ?string `$assertion`,
  string `$description` = ?
  ): void
  `file`
    El fichero donde assert() fue llamado.
  `line`
    La línea donde assert() fue llamado.
  `assertion`
    Antes de PHP 8.0.0, el primer parámetro de la función assert() era la aserción pasada, pero solo cuando la aserción se proporcionaba como string. (Si la aserción era una condición booleana, este parámetro era una cadena vacía.) A partir de PHP 8.0.0, este parámetro es siempre `null`.
  `description`
    La descripción que se proporcionó a assert().

Pasar una cadena vacía como `value` restablece la función de retrollamada assert.

### Valores devueltos

Devuelve el valor original de la opción.

### Errores/Excepciones

Si `option` no es una opción válida, se lanza una ValueError.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | assert_options() ahora está obsoleto.
8.0.0 | Si `option` no es una opción válida, se lanza una ValueError. Anteriormente, se devolvía `false`.

### Ejemplos

Ejemplo #1 Ejemplo con assert_options()

    <?php
    // Esta es nuestra función para manejar
    // los errores de aserción
    function assert_failure($file, $line, $assertion, $message)
    {
        echo "La aserción $assertion en $file en la línea $line ha fallado: $message";
    }

    // Esta es nuestra función de prueba
    function test_assert($parameter)
    {
        assert(is_bool($parameter));
    }

    // Define nuestras opciones de aserción
    assert_options(ASSERT_ACTIVE,   true);
    assert_options(ASSERT_BAIL,     true);
    assert_options(ASSERT_WARNING,  false);
    assert_options(ASSERT_CALLBACK, 'assert_failure');

    // Una aserción que debe fallar
    test_assert(1);

    // Esto nunca se alcanza, ya que ASSERT_BAIL
    // es true
    echo 'Nunca alcanzado';
    ?>

### Ver también

- assert() - Verifica una aserción

# cli_get_process_title

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

cli_get_process_title — Devuelve el título del proceso actual

### Descripción

function cli_get_process_title(): ?string

Devuelve el título del proceso actual, tal como se definió mediante la función cli_set_process_title(). Tenga en cuenta que este título puede ser ligeramente diferente al que se muestra mediante los comandos ps y top, según el sistema subyacente.

Esta función solo está disponible en modo CLI.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el título del proceso actual, en forma de una cadena de caracteres, o `null` si ocurre un error.

### Errores/Excepciones

Se generará una advertencia de nivel `E_WARNING` si el sistema subyacente no es compatible.

### Ejemplos

Ejemplo #1 Ejemplo con cli_get_process_title()

    <?php
    echo "Título del proceso: " . cli_get_process_title() . "\n";
    ?>

### Ver también

- cli_set_process_title() - Define el título del proceso

# cli_set_process_title

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

cli_set_process_title — Define el título del proceso

### Descripción

function cli_set_process_title(string `$title`): bool

Define el título del proceso visible con herramientas como top y ps. Esta función solo está disponible en modo CLI.

### Parámetros

`title`
  El nuevo título.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Se generará una alerta de nivel `E_WARNING` si el sistema subyacente no es compatible.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | cli_set_process_title() ahora emite una alerta `E_WARNING` al definir un título de proceso demasiado largo; antes el título era truncado.

### Ejemplos

    <?php
    $title = "Mi super script PHP";
    $pid = getmypid(); // puede utilizarse para ver el título del proceso en ps

    if (!cli_set_process_title($title)) {
        echo "No se puede definir el título del proceso para el PID $pid...\n";
        exit(1);
    } else {
        echo "¡El título del proceso '$title' para el PID $pid ha sido definido correctamente!\n";
        sleep(5);
    }
    ?>

### Ver también

- cli_get_process_title() - Devuelve el título del proceso actual

# dl

(PHP 4, PHP 5, PHP 7, PHP 8)

dl — Carga una extensión PHP dinámicamente

### Descripción

function dl(string `$extension_filename`): bool

Carga la extensión PHP `extension_filename` dinámicamente.

Utilice la función extension_loaded() para verificar si una extensión está cargada o no. Esta función funciona tanto con extensiones nativas como con extensiones cargadas dinámicamente (vía el php.ini o dl()).

Advertencia

Esta función solo está disponible para los SAPI CLI e integrados, y el SAPI CGI cuando se ejecuta desde la línea de comandos.

### Parámetros

`extension_filename`

  Este parámetro es solo el nombre de archivo de la extensión, que depende de la plataforma. Por ejemplo la extensión sockets (si compilada como módulo compartido, y no por defecto), se llamará sockets.so bajo Unix, y php_sockets.dll bajo Windows.

  La carpeta desde la cual se cargan las extensiones depende de la plataforma:

  Windows - Si no se indica explícitamente en el archivo php.ini, la extensión se carga desde C:\php5\ por defecto.

  Unix - Si no se indica explícitamente en el archivo php.ini, la carpeta de extensiones depende de

  - Si PHP fue compilado con la opción `--enable-debug` o no
  - Si PHP fue compilado con soporte para ZTS (`Zend Thread Safety`) o no
  - de la constante interna `ZEND_MODULE_API_NO` (versión interna de API de módulo Zend, que en realidad es la fecha en que se realizó una modificación importante de la API, por ejemplo `20010901`)
  Considerando estos parámetros, la carpeta de extensiones será entonces `<install-dir>/lib/php/extensions/ <debug-or-not>-<zts-or-not>-ZEND_MODULE_API_NO`, por ejemplo /usr/local/php/lib/php/extensions/debug-non-zts-20010901 o /usr/local/php/lib/php/extensions/no-debug-zts-20010901.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error. Si la funcionalidad de carga de módulos no está disponible, o ha sido desactivada (desactivando la directiva enable_dl en el php.ini) se emitirá un `E_ERROR` y la ejecución del script será detenida. Si la función dl() falla porque la biblioteca no pudo ser encontrada, dl() retornará `false` y emitirá un mensaje de advertencia `E_WARNING`.

### Ejemplos

Ejemplo #1 Ejemplos con dl()

    <?php
    // Carga para todas las plataformas
    if (!extension_loaded('sqlite')) {
        if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
            dl('php_sqlite.dll');
        } else {
            dl('sqlite.so');
        }
    }

    // O usar la constante PHP_SHLIB_SUFFIX
    if (!extension_loaded('sqlite')) {
        $prefix = (PHP_SHLIB_SUFFIX === 'dll') ? 'php_' : '';
        dl($prefix . 'sqlite.' . PHP_SHLIB_SUFFIX);
    }
    ?>

### Notas

> Nota:

> dl() es sensible a mayúsculas/minúsculas en plataformas Unix.

### Ver también

- Directivas de carga de extensiones
- extension_loaded() - Determina si una extensión está cargada o no

# extension_loaded

(PHP 4, PHP 5, PHP 7, PHP 8)

extension_loaded — Determina si una extensión está cargada o no

### Descripción

function extension_loaded(string `$extension`): bool

Determina si una extensión está cargada o no.

### Parámetros

`extension`

  El nombre de la extensión. Este argumento no es sensible a mayúsculas/minúsculas.

  Los nombres de las diferentes extensiones PHP pueden ser conocidos utilizando la función phpinfo() o bien si se utiliza la versión `CGI` o `CLI` de PHP, se puede utilizar la opción de línea de comandos `-m` para mostrar todas las extensiones disponibles :

      $ php -m
      [PHP Modules]
      xml
      tokenizer
      standard
      sockets
      session
      posix
      pcre
      overload
      mysql
      mbstring
      ctype

      [Zend Modules]

### Valores devueltos

Retorna `true` si la extensión `extension` ha sido cargada, `false` en caso contrario.

### Ejemplos

Ejemplo #1 Ejemplo con extension_loaded()

    <?php
    if (!extension_loaded('gd')) {
        if (!dl('gd.so')) {
            exit;
        }
    }
    ?>

### Ver también

- get_loaded_extensions() - Devuelve la lista de todos los módulos compilados y cargados
- get_extension_funcs() - Lista las funciones de una extensión
- phpinfo() - Muestra numerosas informaciones sobre la configuración de PHP
- dl() - Carga una extensión PHP dinámicamente
- function_exists() - Indica si una función está definida

# gc_collect_cycles

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_collect_cycles — Fuerza la recolección de los ciclos de basura existentes

### Descripción

function gc_collect_cycles(): int

Recogida de las fuerzas de los ciclos de basura existentes.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de ciclos de recogida.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | El valor de retorno ya no incluye las cadenas y los recursos que fueron recolectados indirectamente a través de los ciclos.

### Ver también

- Recolección de Basura

# gc_disable

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_disable — Desactiva el recolector de referencia circular

### Descripción

function gc_disable(): void

Desactiva el recolector de referencia circular. zend.enable_gc a `0`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

### Ver también

- Recolección de Basura

# gc_enable

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_enable — Activa el colector de referencia circular

### Descripción

function gc_enable(): void

Activa el colector de referencia circular, estableciendo zend.enable_gc a `1`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

### Ver también

- Recolección de basura

# gc_enabled

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_enabled — Devuelve el estado del colector de referencia circular

### Descripción

function gc_enabled(): bool

Devuelve el estado del colector de referencia circular.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si el recolector de basura está activado, `false` en caso contrario.

### Ejemplos

Ejemplo #1 Ejemplo de gc_enabled()

    <?php
    if(gc_enabled()) gc_collect_cycles();
    ?>

### Ver también

- Recolección de Basura

# gc_mem_caches

(PHP 7, PHP 8)

gc_mem_caches — Libera memoria utilizada por el gestor de memoria de Zend Engine

### Descripción

function gc_mem_caches(): int

Libera memoria utilizada por el gestor de memoria de Zend Engine.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de bytes liberados.

### Ver también

- Recolección de basura (Garbage Collection)

# gc_status

(PHP 7 >= 7.3.0, PHP 8)

gc_status — Obtiene información sobre el recolector de basura

### Descripción

function gc_status(): array

Obtiene información sobre el estado actual del recolector de basura.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array asociativo con los siguientes elementos:

- `"runs"`
- `"collected"`
- `"threshold"`
- `"roots"`
- `"running"`
- `"protected"`
- `"full"`
- `"buffer_size"`
- `"application_time"`
- `"collector_time"`
- `"destructor_time"`
- `"free_time"`

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | gc_status() devuelve ahora los campos adicionales siguientes: `"running"`, `"protected"`, `"full"`, `"buffer_size"`, `"application_time"`, `"collector_time"`, `"destructor_time"`, y `"free_time"`.

### Ejemplos

Ejemplo #1 Uso de gc_status()

    <?php

    // crear el árbol de objetos que requiere la recolección de basura
    $a = new stdClass();
    $a->b = [];
    for ($i = 0; $i < 100000; $i++) {
        $b = new stdClass();
        $b->a = $a;
        $a->b[] = $b;
    }
    unset($a);
    unset($b);
    gc_collect_cycles();

    var_dump(gc_status());

Resultado del ejemplo anterior es similar a:

    array(4) {
      ["runs"]=>
      int(5)
      ["collected"]=>
      int(100002)
      ["threshold"]=>
      int(50001)
      ["roots"]=>
      int(0)
    }

Resultado del ejemplo anterior en PHP 8.3 es similar a:

    array(12) {
      ["running"]=>
      bool(false)
      ["protected"]=>
      bool(false)
      ["full"]=>
      bool(false)
      ["runs"]=>
      int(5)
      ["collected"]=>
      int(100002)
      ["threshold"]=>
      int(50001)
      ["buffer_size"]=>
      int(131072)
      ["roots"]=>
      int(0)
      ["application_time"]=>
      float(0.031182458)
      ["collector_time"]=>
      float(0.020106291)
      ["destructor_time"]=>
      float(0)
      ["free_time"]=>
      float(0.003707167)
    }

### Ver también

- Recolector de basura (Garbage Collection)

# get_cfg_var

(PHP 4, PHP 5, PHP 7, PHP 8)

get_cfg_var — Devuelve el valor de una opción de PHP

### Descripción

function get_cfg_var(string `$option`): string|array|false

Devuelve el valor de la opción `option` de configuración de PHP.

get_cfg_var() no devuelve las opciones que fueron seleccionadas durante la compilación de PHP, ni lee en el archivo de configuración de Apache.

Para verificar si el sistema utiliza el archivo de configuración, intente leer el valor de cfg_file_path. Si este valor está disponible, entonces el archivo de configuración se utiliza.

### Parámetros

`option`

  El nombre de la opción de configuración.

### Valores devueltos

Devuelve el valor actual de la opción PHP `option` o bien `false` si ocurre un error.

### Ver también

- ini_get() - Lee el valor de una opción de configuración
- ini_get_all() - Lee todos los valores de configuración

# get_current_user

(PHP 4, PHP 5, PHP 7, PHP 8)

get_current_user — Devuelve el nombre del propietario del script actual

### Descripción

function get_current_user(): string

Devuelve el nombre del propietario del script actual.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el nombre del usuario, en forma de string.

### Ejemplos

Ejemplo #1 Ejemplo con get_current_user()

    <?php
    echo 'Propietario del script actual : ' . get_current_user();
    ?>

Resultado del ejemplo anterior es similar a:

    Propietario del script actual : SYSTEM

### Ver también

- getmyuid() - Retorna el UID del propietario del script actual
- getmygid() - Retorna el GID del propietario del script
- getmypid() - Devuelve el número de proceso actual de PHP
- getmyinode() - Devuelve el inodo del script
- getlastmod() - Devuelve la fecha de última modificación de la página

# get_defined_constants

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

get_defined_constants — Devuelve la lista de constantes y sus valores

### Descripción

function get_defined_constants(bool `$categorize` = `false`): array

Devuelve los nombres y valores de las constantes ya definidas. Esto incluye las constantes creadas por las extensiones, y aquellas creadas con la función define().

### Parámetros

`categorize`

  Permite a esta función devolver un array multidimensional con las categorías como claves de la primera dimensión y las constantes junto con sus valores en la segunda dimensión.

      <?php
      define("MY_CONSTANT", 1);
      print_r(get_defined_constants(true));
      ?>

  Resultado del ejemplo anterior es similar a:

      Array
      (
          [Core] => Array
              (
                  [E_ERROR] => 1
                  [E_WARNING] => 2
                  [E_PARSE] => 4
                  [E_NOTICE] => 8
                  [E_CORE_ERROR] => 16
                  [E_CORE_WARNING] => 32
                  [E_COMPILE_ERROR] => 64
                  [E_COMPILE_WARNING] => 128
                  [E_USER_ERROR] => 256
                  [E_USER_WARNING] => 512
                  [E_USER_NOTICE] => 1024
                  [E_ALL] => 2047
                  [TRUE] => 1
              )

          [pcre] => Array
              (
                  [PREG_PATTERN_ORDER] => 1
                  [PREG_SET_ORDER] => 2
                  [PREG_OFFSET_CAPTURE] => 256
                  [PREG_SPLIT_NO_EMPTY] => 1
                  [PREG_SPLIT_DELIM_CAPTURE] => 2
                  [PREG_SPLIT_OFFSET_CAPTURE] => 4
                  [PREG_GREP_INVERT] => 1
              )

          [user] => Array
              (
                  [MY_CONSTANT] => 1
              )

      )

### Valores devueltos

Devuelve un array de constantes en el formato "nombre de la constante" => "valor de la constante", opcionalmente agrupadas por el nombre de la extensión que registró la constante.

### Ejemplos

Ejemplo #1 Ejemplo con get_defined_constants()

    <?php
    print_r(get_defined_constants());
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [E_ERROR] => 1
        [E_WARNING] => 2
        [E_PARSE] => 4
        [E_NOTICE] => 8
        [E_CORE_ERROR] => 16
        [E_CORE_WARNING] => 32
        [E_COMPILE_ERROR] => 64
        [E_COMPILE_WARNING] => 128
        [E_USER_ERROR] => 256
        [E_USER_WARNING] => 512
        [E_USER_NOTICE] => 1024
        [E_ALL] => 2047
        [TRUE] => 1
    )

### Ver también

- defined() - Verifica si una constante con el nombre dado existe
- constant() - Retorna el valor de una constante
- get_loaded_extensions() - Devuelve la lista de todos los módulos compilados y cargados
- get_defined_functions() - Lista todas las funciones definidas
- get_defined_vars() - Lista todas las variables definidas

# get_extension_funcs

(PHP 4, PHP 5, PHP 7, PHP 8)

get_extension_funcs — Lista las funciones de una extensión

### Descripción

function get_extension_funcs(string `$extension`): array|false

Devuelve el nombre de las funciones definidas en el módulo `extension`.

### Parámetros

`extension`

  El nombre del módulo.

  > Nota:

  > Este argumento debe estar en minúsculas.

### Valores devueltos

Devuelve un array que contiene todas las funciones, o `false` si `extension` no es una extensión válida.

### Ejemplos

Ejemplo #1 Muestra todas las funciones XML

    <?php
    print_r(get_extension_funcs("xml"));
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => xml_parser_create
        [1] => xml_parser_create_ns
        [2] => xml_set_object
        [3] => xml_set_element_handler
        [4] => xml_set_character_data_handler
        [5] => xml_set_processing_instruction_handler
        [6] => xml_set_default_handler
        [7] => xml_set_unparsed_entity_decl_handler
        [8] => xml_set_notation_decl_handler
        [9] => xml_set_external_entity_ref_handler
        [10] => xml_set_start_namespace_decl_handler
        [11] => xml_set_end_namespace_decl_handler
        [12] => xml_parse
        [13] => xml_parse_into_struct
        [14] => xml_get_error_code
        [15] => xml_error_string
        [16] => xml_get_current_line_number
        [17] => xml_get_current_column_number
        [18] => xml_get_current_byte_index
        [19] => xml_parser_free
        [20] => xml_parser_set_option
        [21] => xml_parser_get_option
    )

### Ver también

- get_loaded_extensions() - Devuelve la lista de todos los módulos compilados y cargados
- ReflectionExtension::getFunctions() - Obtiene las funciones de una extensión

# get_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

get_include_path — Lee el valor de la directiva de configuración include_path

### Descripción

function get_include_path(): string|false

Lee el valor de la directiva de configuración include_path.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la ruta, en forma de string, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con get_include_path()

    <?php
    echo get_include_path();

    // O utilizar ini_get()
    echo ini_get('include_path');
    ?>

### Ver también

- ini_get() - Lee el valor de una opción de configuración
- restore_include_path() - Restaura el valor de la directiva de configuración include_path
- set_include_path() - Modifica el valor de la directiva de configuración include_path
- include - include

# get_included_files

(PHP 4, PHP 5, PHP 7, PHP 8)

get_included_files — Devuelve un array con los nombres de los ficheros que son incluidos en un script

### Descripción

function get_included_files(): array

Devuelve un array que contiene los nombres de todos los ficheros que han sido añadidos al script con las funciones include, include_once, require o require_once.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array que contiene los nombres de todos los ficheros.

El script en curso es considerado como fichero incluido, por lo que será listado junto con los otros ficheros a los que se hace referencia con include y las funciones similares.

Los ficheros incluidos o requeridos varias veces solo se muestran una vez en el array devuelto.

### Ejemplos

Ejemplo #1 Ejemplo con get_included_files()

    <?php
    // Este fichero es abc.php

    include 'test1.php';
    include_once 'test2.php';
    require 'test3.php';
    require_once 'test4.php';

    $included_files = get_included_files();

    foreach ($included_files as $filename) {
        echo "$filename\n";
    }

    ?>

El ejemplo anterior mostrará:

    /path/to/abc.php
    /path/to/test1.php
    /path/to/test2.php
    /path/to/test3.php
    /path/to/test4.php

### Ver también

- include - include
- include_once - include_once
- require - require
- require_once - require_once
- get_required_files() - Alias de get_included_files

# get_loaded_extensions

(PHP 4, PHP 5, PHP 7, PHP 8)

get_loaded_extensions — Devuelve la lista de todos los módulos compilados y cargados

### Descripción

function get_loaded_extensions(bool `$zend_extensions` = `false`): array

Devuelve un array que contiene los nombres de todos los módulos compilados y cargados por la aplicación PHP actual.

### Parámetros

`zend_extensions`

  Devuelve únicamente las extensiones Zend. Por omisión vale `false` y solo lista las extensiones PHP clásicas como mysqli por ejemplo.

### Valores devueltos

Devuelve un array indexado con los nombres de todos los módulos.

### Ejemplos

Ejemplo #1 Ejemplo con get_loaded_extensions()

    <?php
    print_r(get_loaded_extensions());
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Core
        [1] => date
        [2] => libxml
        [3] => pcre
        [4] => sqlite3
        [5] => zlib
        [6] => ctype
        [7] => dom
        [8] => fileinfo
        [9] => filter
        [10] => hash
        [11] => json
        [12] => mbstring
        [13] => SPL
        [14] => PDO
        [15] => session
        [16] => posix
        [17] => Reflection
        [18] => standard
        [19] => SimpleXML
        [20] => pdo_sqlite
        [21] => Phar
        [22] => tokenizer
        [23] => xml
        [24] => xmlreader
        [25] => xmlwriter
        [26] => gmp
        [27] => iconv
        [28] => intl
        [29] => bcmath
        [30] => sodium
        [31] => Zend OPcache
    )

### Ver también

- get_extension_funcs() - Lista las funciones de una extensión
- extension_loaded() - Determina si una extensión está cargada o no
- dl() - Carga una extensión PHP dinámicamente
- phpinfo() - Muestra numerosas informaciones sobre la configuración de PHP

# get_magic_quotes_gpc

(PHP 4, PHP 5, PHP 7)

get_magic_quotes_gpc — Devuelve la configuración actual de la opción magic_quotes_gpc

Advertencia

Esta función está OBSOLETA a partir de PHP 7.4.0, y ha sido ELIMINADA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

function get_magic_quotes_gpc(): false

Siempre devuelve `false`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Siempre devuelve `false`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función ha sido eliminada.
7.4.0 | Esta función está obsoleta.

### Ver también

- addslashes() - Añade barras invertidas en un string
- stripslashes() - Quita las barras de un string con comillas escapadas
- get_magic_quotes_runtime() - Devuelve la configuración actual de la opción magic_quotes_runtime
- ini_get() - Lee el valor de una opción de configuración

# get_magic_quotes_runtime

(PHP 4, PHP 5, PHP 7)

get_magic_quotes_runtime — Devuelve la configuración actual de la opción magic_quotes_runtime

Advertencia

Esta función está OBSOLETA a partir de PHP 7.4.0, y ha sido ELIMINADA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

function get_magic_quotes_runtime(): false

Siempre devuelve `false`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Siempre devuelve `false`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función ha sido eliminada.
7.4.0 | Esta función está obsoleta.

### Ver también

- get_magic_quotes_gpc() - Devuelve la configuración actual de la opción magic_quotes_gpc

# get_required_files

(PHP 4, PHP 5, PHP 7, PHP 8)

get_required_files — Alias de get_included_files()

### Descripción

Esta función es un alias de: get_included_files().

# get_resources

(PHP 7, PHP 8)

get_resources — Devuelve los recursos activos

### Descripción

function get_resources(?string `$type` = `null`): array

Devuelve un array de todos los recursos resource actualmente activos, opcionalmente filtrados por el tipo de recurso.

> Nota: Esta función está destinada a fines de depuración y prueba. No está pensada para ser utilizada en entornos de producción, y mucho menos para acceder o incluso manipular recursos que normalmente no son accesibles (por ejemplo, el recurso de flujo subyacente de las instancias de SplFileObject).

### Parámetros

`type`

  Si se define, esto hará que get_resources() devuelva solo los recursos del tipo dado. Una lista de tipos de recursos está disponible.

  Si se proporciona string `Unknown` para el tipo, en ese caso solo se devolverán los recursos cuyo tipo es desconocido.

  Si se omite, se devolverán todos los recursos.

### Valores devueltos

Devuelve un array de los recursos actualmente activos, indexados por el número del recurso.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `type` ahora es nullable.

### Ejemplos

Ejemplo #1 get_resources() sin filtrar

    <?php
    $fp = tmpfile();
    var_dump(get_resources());
    ?>

Resultado del ejemplo anterior es similar a:

    array(1) {
      [1]=>
      resource(1) of type (stream)
    }

Ejemplo #2 get_resources() filtrado

    <?php
    $fp = tmpfile();
    var_dump(get_resources('stream'));
    var_dump(get_resources('curl'));
    ?>

Resultado del ejemplo anterior es similar a:

    array(1) {
      [1]=>
      resource(1) of type (stream)
    }
    array(0) {
    }

### Ver también

- get_loaded_extensions() - Devuelve la lista de todos los módulos compilados y cargados
- get_defined_constants() - Devuelve la lista de constantes y sus valores
- get_defined_functions() - Lista todas las funciones definidas
- get_defined_vars() - Lista todas las variables definidas

# getenv

(PHP 4, PHP 5, PHP 7, PHP 8)

getenv — Retorna el valor de una o todas las variables de entorno

### Descripción

function getenv(?string `$name` = `null`, bool `$local_only` = `false`): string|array|false

Retorna el valor de una o todas las variables de entorno.

Puede verse una lista completa de las variables de entorno utilizando la función phpinfo(). Puede encontrarse el significado de cada una de ellas consultando la » RFC 3875, en particular la sección 4.1 "Request Meta-Variables".

### Parámetros

`name`

  El nombre de la variable como string o `null`.

`local_only`

  Cuando se establece en `true`, solo se retornan las variables de entorno locales, definidas por el sistema operativo o putenv. Esto solo tiene efecto cuando `name` es un string.

### Valores devueltos

Retorna el valor de la variable de entorno `name`, o `false` si la variable de entorno `name` no existe. Si `name` es omitido, todas las variables de entorno son retornadas como un array asociativo.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | El `name` ahora es nullable.
7.1.0 | `name` ahora puede ser omitido para recuperar un array asociativo de todas las variables de entorno.
7.0.9 | Se ha añadido el parámetro `local_only`.

### Ejemplos

Ejemplo #1 Ejemplo con getenv()

    <?php
    // Ejemplo de uso de getenv()
    $ip = getenv('REMOTE_ADDR');

    // O simplemente usar una Superglobal ($_SERVER o $_ENV)
    $ip = $_SERVER['REMOTE_ADDR'];

    // Obtener de forma segura el valor de una variable de entorno,
    // ignorando si ha sido definida por un SAPI o modificada con putenv
    $ip = getenv('REMOTE_ADDR', true) ?: getenv('REMOTE_ADDR')
    ?>

### Notas

Advertencia

Si PHP se ejecuta en un SAPI como Fast CGI, esta función retornará siempre el valor de una variable de entorno definida por el SAPI, incluso si putenv() ha sido utilizado para definir una variable de entorno local con el mismo nombre. El parámetro `local_only` debe ser utilizado para retornar los valores de variables de entorno definidas localmente.

### Ver también

- putenv() - Establece el valor de una variable de entorno
- apache_getenv() - Lee una variable de proceso Apache
- Superglobales

# getlastmod

(PHP 4, PHP 5, PHP 7, PHP 8)

getlastmod — Devuelve la fecha de última modificación de la página

### Descripción

function getlastmod(): int|false

Devuelve la fecha de última modificación del script principal en ejecución.

Si se desea obtener la fecha de última modificación de un fichero diferente, se debe utilizar la función filemtime().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la fecha de última modificación de la página. El valor devuelto es un timestamp UNIX, utilizable como argumento con la función date(). Devuelve `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con getlastmod()

    <?php
    // muestra por ejemplo 'Última modificación: April 20 2004 20:43:59.'
    echo "Última modificación : " . date ("F d Y H:i:s.", getlastmod());
    ?>

### Ver también

- date() - Da formato a una marca de tiempo de Unix (Unix timestamp)
- getmyuid() - Retorna el UID del propietario del script actual
- getmygid() - Retorna el GID del propietario del script
- get_current_user() - Devuelve el nombre del propietario del script actual
- getmyinode() - Devuelve el inodo del script
- getmypid() - Devuelve el número de proceso actual de PHP
- filemtime() - Lee la fecha de última modificación del fichero

# getmygid

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

getmygid — Retorna el GID del propietario del script

### Descripción

function getmygid(): int|false

Retorna el GID del propietario del script.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Retorna el GID del propietario del script actual, o `false` en caso de error.

### Ver también

- getmyuid() - Retorna el UID del propietario del script actual
- getmypid() - Devuelve el número de proceso actual de PHP
- get_current_user() - Devuelve el nombre del propietario del script actual
- getmyinode() - Devuelve el inodo del script
- getlastmod() - Devuelve la fecha de última modificación de la página

# getmyinode

(PHP 4, PHP 5, PHP 7, PHP 8)

getmyinode — Devuelve el inodo del script

### Descripción

function getmyinode(): int|false

Devuelve el inodo del script actual.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el inodo del script actual, en forma de int, o `false` en caso de error.

### Ver también

- getmygid() - Retorna el GID del propietario del script
- getmyuid() - Retorna el UID del propietario del script actual
- getmypid() - Devuelve el número de proceso actual de PHP
- get_current_user() - Devuelve el nombre del propietario del script actual
- getlastmod() - Devuelve la fecha de última modificación de la página

# getmypid

(PHP 4, PHP 5, PHP 7, PHP 8)

getmypid — Devuelve el número de proceso actual de PHP

### Descripción

function getmypid(): int|false

Devuelve el número de proceso actual de PHP.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de proceso actual de PHP, o `false` en caso de error.

### Notas

Advertencia

Los identificadores de proceso no son únicos, y constituyen una fuente de entropía baja. Se recomienda no utilizar los pid para garantizar la seguridad de un sistema.

### Ver también

- getmygid() - Retorna el GID del propietario del script
- getmyuid() - Retorna el UID del propietario del script actual
- get_current_user() - Devuelve el nombre del propietario del script actual
- getmyinode() - Devuelve el inodo del script
- getlastmod() - Devuelve la fecha de última modificación de la página

# getmyuid

(PHP 4, PHP 5, PHP 7, PHP 8)

getmyuid — Retorna el UID del propietario del script actual

### Descripción

function getmyuid(): int|false

Retorna el UID del propietario del script actual.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Retorna el identificador del propietario del script actual (UID) o `false` en caso de error.

### Ver también

- getmygid() - Retorna el GID del propietario del script
- getmypid() - Devuelve el número de proceso actual de PHP
- get_current_user() - Devuelve el nombre del propietario del script actual
- getmyinode() - Devuelve el inodo del script
- getlastmod() - Devuelve la fecha de última modificación de la página

# getopt

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

getopt — Lee las opciones pasadas en la línea de comandos

### Descripción

function getopt(string `$short_options`, array `$long_options` = [], int `&$rest_index` = `null`): array|false

getopt() lee las opciones pasadas en la línea de comandos.

### Parámetros

`short_options`
  Cada carácter en esta cadena será utilizado como caracteres opcionales y deberá coincidir con las opciones pasadas, comenzando por un guión simple (`-`). Por ejemplo, una cadena opcional `"x"` coincidirá con la opción `-x`. Solo se permiten a-z, A-Z y 0-9.
`long_options`
  Un array de opciones. Cada elemento de este array será utilizado como opción y deberá coincidir con las opciones pasadas, comenzando por un guión doble (`--`). Por ejemplo, un elemento `longopts` `"opt"` coincidirá con la opción `--opt`.
`rest_index`
  Si el parámetro `rest_index` está presente, entonces el índice donde se detuvo el análisis de los argumentos será escrito en esta variable.

El parámetro `short_options` puede contener los siguientes elementos:

- Caracteres individuales (no aceptan valor)
- Caracteres seguidos por un dos-puntos (el parámetro requiere un valor)
- Caracteres seguidos por dos dos-puntos (valor opcional)

Los valores opcionales son los primeros argumentos después de la cadena. Si un valor es requerido, no importa si el valor está seguido de un espacio o no. Ver la nota.

> Nota: Los valores opcionales no aceptan el espacio como separador.

El array de valores `long_options` puede contener:

- String (parámetro no acepta ningún valor)
- String seguido de un dos-puntos (parámetro requiere un valor)
- String seguido de dos dos-puntos (valor opcional)

> Nota:

> El formato de los parámetros `short_options` y `long_options` es idéntico; la única diferencia es que `long_options` toma un array en opción (donde cada elemento es una opción) mientras que `short_options` toma una cadena (donde cada carácter es una opción).

### Valores devueltos

Esta función devuelve un array de opciones/argumentos, o `false` si ocurre un error.

> Nota:

> El análisis de las opciones se detendrá cuando se encuentre la primera opción incorrecta, y todo lo que siga será ignorado.

### Historial de cambios

Versión | Descripción
--- | ---
7.1.0 | Se añadió el parámetro `rest_index`.

### Ejemplos

Ejemplo #1 Ejemplo con getopt(): los fundamentos

    <?php
    // Script example.php
    $options = getopt("f:hp:");
    var_dump($options);
    ?>

    shell> php example.php -fvalue -h

El ejemplo anterior mostrará:

    array(2) {
      ["f"]=>
      string(5) "value"
      ["h"]=>
      bool(false)
    }

Ejemplo #2 Segundo ejemplo con getopt(): Introducción a las opciones largas

    <?php
    // Script example.php
    $shortopts  = "";
    $shortopts .= "f:";  // Valor requerido
    $shortopts .= "v::"; // Valor opcional
    $shortopts .= "abc"; // Estas opciones no aceptan valor

    $longopts  = array(
        "required:",     // Valor requerido
        "optional::",    // Valor opcional
        "option",        // Ningún valor
        "opt",           // Ningún valor
    );
    $options = getopt($shortopts, $longopts);
    var_dump($options);
    ?>

    shell> php example.php -f "value for f" -v -a --required value --optional="optional value" --option

El ejemplo anterior mostrará:

    array(6) {
      ["f"]=>
      string(11) "value for f"
      ["v"]=>
      bool(false)
      ["a"]=>
      bool(false)
      ["required"]=>
      string(5) "value"
      ["optional"]=>
      string(14) "optional value"
      ["option"]=>
      bool(false)
    }

Ejemplo #3 Tercer ejemplo con getopt(): Pasar múltiples opciones

    <?php
    // Script example.php
    $options = getopt("abc");
    var_dump($options);
    ?>

    shell> php example.php -aaac

El ejemplo anterior mostrará:

    array(2) {
      ["a"]=>
      array(3) {
        [0]=>
        bool(false)
        [1]=>
        bool(false)
        [2]=>
        bool(false)
      }
      ["c"]=>
      bool(false)
    }

Ejemplo #4 Ejemplo de getopt(): Utilizando `rest_index`

    <?php
    // Script example.php
    $rest_index = null;
    $opts = getopt('a:b:', [], $rest_index);
    $pos_args = array_slice($argv, $rest_index);
    var_dump($pos_args);

    shell> php example.php -a 1 -b 2 -- test

El ejemplo anterior mostrará:

    array(1) {
      [0]=>
      string(4) "test"
    }

### Ver también

- $argv

# getrusage

(PHP 4, PHP 5, PHP 7, PHP 8)

getrusage — Devuelve el nivel de utilización de los recursos

### Descripción

function getrusage(int `$mode` = 0): array|false

Es una interfaz a la función del sistema getrusage(2). Devuelve un array asociativo que contiene las informaciones devueltas por esta llamada al sistema.

### Parámetros

`mode`

  Si `mode` es igual a 1, getrusage() será llamado con el argumento `RUSAGE_CHILDREN`.

### Valores devueltos

Devuelve un array asociativo que contiene los datos devueltos desde la llamada al sistema. Todas las entradas son accesibles utilizando sus nombres de campos documentados. Devuelve `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con getrusage()

    <?php
    $dat = getrusage();
    echo $dat["ru_oublock"];       // número de operaciones de bloque de salida
    echo $dat["ru_inblock"];       // número de operaciones de bloque de entrada
    echo $dat["ru_msgsnd"];        // número de mensajes IPC enviados
    echo $dat["ru_msgrcv"];        // número de mensajes IPC recibidos
    echo $dat["ru_maxrss"];        // tamaño máximo del grupo de residentes
    echo $dat["ru_ixrss"];         // tamaño de la memoria compartida integral
    echo $dat["ru_idrss"];         // tamaño integral de los datos no compartidos
    echo $dat["ru_minflt"];        // número de páginas recuperadas (falta de página menor)
    echo $dat["ru_majflt"];        // número de faltas de página (falta de página mayor)
    echo $dat["ru_nsignals"];      // número de señales recibidas
    echo $dat["ru_nvcsw"];         // número de cambios de contexto voluntarios
    echo $dat["ru_nivcsw"];        // número de cambios de contexto involuntarios
    echo $dat["ru_nswap"];         // tamaño de la memoria swap
    echo $dat["ru_utime.tv_usec"]; // tiempo de usuario utilizado (en microsegundos)
    echo $dat["ru_utime.tv_sec"];  // tiempo de usuario utilizado (en segundos)
    echo $dat["ru_stime.tv_usec"]; // tiempo de sistema utilizado (en microsegundos)
    echo $dat["ru_stime.tv_sec"]; // tiempo de sistema utilizado (en segundos)
    ?>

### Notas

> Nota:

> Bajo Windows, la función getrusage() solo va a devolver los siguientes miembros:

> - `"ru_stime.tv_sec"`
> - `"ru_stime.tv_usec"`
> - `"ru_utime.tv_sec"`
> - `"ru_utime.tv_usec"`
> - `"ru_majflt"` (solo si `mode` vale `RUSAGE_SELF`)
> - `"ru_maxrss"` (solo si `mode` vale `RUSAGE_SELF`)

> Si getrusage() es llamado con el argumento `mode` valiendo `1` (`RUSAGE_CHILDREN`), entonces la utilización de los recursos para los hilos son recolectados (lo que significa que, internamente, la función es llamada con `RUSAGE_THREAD`).

> Nota:

> Bajo BeOS 2000, solo los siguientes miembros son devueltos:

> - `"ru_stime.tv_sec"`
> - `"ru_stime.tv_usec"`
> - `"ru_utime.tv_sec"`
> - `"ru_utime.tv_usec"`

### Ver también

- La página del manual getrusage(2) de su sistema

# ini_alter

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_alter — Alias de ini_set()

### Descripción

Esta función es un alias de: ini_set().

# ini_get

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_get — Lee el valor de una opción de configuración

### Descripción

function ini_get(string `$option`): string|false

Devuelve el valor de la opción de configuración `varname` en caso de éxito.

### Parámetros

`option`

  El nombre de la opción de configuración.

### Valores devueltos

Devuelve el valor de la opción de configuración `varname` en caso de éxito, o un string vacío para los valores `null`. Devuelve `false` si la opción de configuración no existe.

### Ejemplos

Ejemplo #1 Ejemplos con ini_get()

    <?php

    /*
    Nuestro archivo php.ini contiene las siguientes directivas:

    display_errors = On
    opcache.enable_cli = Off
    post_max_size = 8M
    */

    echo 'display_errors = ' . ini_get('display_errors') . "\n";
    echo 'opcache.enable_cli = ' . (int) ini_get('opcache.enable_cli') . "\n";
    echo 'post_max_size = ' . ini_get('post_max_size') . "\n";
    echo 'post_max_size + 1 = ' . (rtrim(ini_get('post_max_size'), 'KMG') + 1) . "\n";
    echo 'post_max_size in bytes = ' . ini_parse_quantity(ini_get('post_max_size'));

    ?>

Resultado del ejemplo anterior es similar a:

    display_errors = 1
    opcache.enable_cli = 0
    post_max_size = 8M
    post_max_size+1 = 9
    post_max_size in bytes = 8388608

### Notas

> Nota: Lectura de valores booleanos

> Una directiva de configuración con el valor `off` será devuelta en forma de cadena vacía o "0" mientras que el valor `on` devolverá "`1`". Esta función también puede devolver el valor literal del archivo INI.

> Nota: Al leer los tamaños de memoria

> Varias directivas que tratan sobre tamaño de memoria, como upload_max_filesize, están almacenadas en el archivo php.ini con una notación corta. ini_get() devuelve la cadena exacta almacenada en el archivo php.ini y NO su equivalente int. Aplicar operaciones aritméticas clásicas sobre estos valores no conducirá a nada bueno. La función ini_parse_quantity() puede ser utilizada para convertir la notación abreviada en bytes.

> Nota:

> ini_get() no puede leer las opciones ini de tipo "array" como `pdo.dsn.*`, y devuelve `false` en este caso.

### Ver también

- get_cfg_var() - Devuelve el valor de una opción de PHP
- ini_get_all() - Lee todos los valores de configuración
- ini_parse_quantity() - Devuelve el tamaño interpretado a partir de la sintaxis abreviada ini
- ini_restore() - Restaura el valor de la opción de configuración
- ini_set() - Modifica el valor de una opción de configuración

# ini_get_all

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ini_get_all — Lee todos los valores de configuración

### Descripción

function ini_get_all(?string `$extension` = `null`, bool `$details` = `true`): array|false

Devuelve todas las valores de configuración.

### Parámetros

`extension`

  Un nombre de extensión, opcional. Si no es `null` o diferente de la string `core`, esta función devolverá únicamente las opciones específicas de esta extensión.

`details`

  Obtiene los detalles, o únicamente el valor actual de cada configuración. Por omisión, vale `true` (obtiene los detalles).

### Valores devueltos

Devuelve un array asociativo cuyas claves son los nombres de las directivas. Devuelve `false` y genera un error de nivel `E_WARNING` si la `extension` no existe.

Cuando el argumento `details` vale `true` (por defecto), el array contendrá los valores `global_value` (definidos en el archivo php.ini), `local_value` (definido eventualmente con la función ini_set() o mediante un .htaccess), y `access` (el grado de acceso).

Cuando el argumento `details` vale `false`, el valor será el valor actual de la opción.

Ver el manual para más información sobre el significado del grado de acceso.

> Nota:

> Es posible que una directiva tenga varios grados de acceso, y por eso `access` muestra los valores del máscara apropiados.

### Ejemplos

Ejemplo #1 Ejemplo con ini_get_all()

    <?php
    print_r(ini_get_all("pcre"));
    print_r(ini_get_all());
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [pcre.backtrack_limit] => Array
            (
                [global_value] => 100000
                [local_value] => 100000
                [access] => 7
            )

        [pcre.recursion_limit] => Array
            (
                [global_value] => 100000
                [local_value] => 100000
                [access] => 7
            )

    )
    Array
    (
        [allow_call_time_pass_reference] => Array
            (
                [global_value] => 0
                [local_value] => 0
                [access] => 6
            )

        [allow_url_fopen] => Array
            (
                [global_value] => 1
                [local_value] => 1
                [access] => 4
            )

        ...

    )

Ejemplo #2 Desactiva el argumento `details`

    <?php
    print_r(ini_get_all("pcre", false)); // Añadido en PHP 5.3.0
    print_r(ini_get_all(null, false)); // Añadido en PHP 5.3.0
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [pcre.backtrack_limit] => 100000
        [pcre.recursion_limit] => 100000
    )
    Array
    (
        [allow_call_time_pass_reference] => 0
        [allow_url_fopen] => 1
        ...
    )

### Notas

> Nota:

> ini_get_all() ignora las opciones ini "array" tales como `pdo.dsn.*`.

### Ver también

- Cómo modificar la configuración
- ini_get() - Lee el valor de una opción de configuración
- ini_restore() - Restaura el valor de la opción de configuración
- ini_set() - Modifica el valor de una opción de configuración
- get_loaded_extensions() - Devuelve la lista de todos los módulos compilados y cargados
- phpinfo() - Muestra numerosas informaciones sobre la configuración de PHP
- ReflectionExtension::getINIEntries() - Recupera las entradas ini de la extensión

# ini_parse_quantity

(PHP 8 >= 8.2.0)

ini_parse_quantity — Devuelve el tamaño interpretado a partir de la sintaxis abreviada ini

### Descripción

function ini_parse_quantity(string `$shorthand`): int

Devuelve el tamaño interpretado en bytes en caso de éxito a partir de una sintaxis abreviada ini.

### Parámetros

`shorthand`

  La sintaxis abreviada ini a interpretar, debe ser un número seguido de un multiplicador opcional. Los multiplicadores siguientes son soportados: `k`/`K` (`1024`), `m`/`M` (`1048576`), `g`/`G` (`1073741824`). El número puede ser un decimal, hexadecimal (prefijado por `0x` o `0X`), octal (prefijado por `0o`, `0O` o `0`) o binario (prefijado por `0b` o `0B`)

### Valores devueltos

Devuelve el tamaño interpretado en bytes en tanto que int.

### Errores/Excepciones

Si el valor no puede ser interpretado, o si un multiplicador inválido es utilizado, un `E_WARNING` es emitido.

### Ejemplos

Ejemplo #1 Algunos ejemplos de ini_parse_quantity()

    <?php

    var_dump(ini_parse_quantity('1024'));
    var_dump(ini_parse_quantity('1024M'));
    var_dump(ini_parse_quantity('512K'));
    var_dump(ini_parse_quantity('0xFFk'));
    var_dump(ini_parse_quantity('0b1010k'));
    var_dump(ini_parse_quantity('0o1024'));
    var_dump(ini_parse_quantity('01024'));
    var_dump(ini_parse_quantity('Foobar'));
    var_dump(ini_parse_quantity('10F'));

    ?>

El ejemplo anterior mostrará:

    int(1024)
    int(1073741824)
    int(524288)
    int(261120)
    int(10240)
    int(532)
    int(532)

    Warning: Invalid quantity "Foobar": no valid leading digits, interpreting as "0" for backwards compatibility
    int(0)

    Warning: Invalid quantity "10F": unknown multiplier "F", interpreting as "10" for backwards compatibility
    int(10)

### Ver también

- ini_get() - Lee el valor de una opción de configuración

# ini_restore

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_restore — Restaura el valor de la opción de configuración

### Descripción

function ini_restore(string `$option`): void

Restaura el valor original de la opción de configuración `varname`.

### Parámetros

`option`

  El nombre de la opción de configuración.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ini_restore()

    <?php
    $setting = 'html_errors';

    echo 'Valor actual de \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;

    ini_set($setting, ini_get($setting) ? 0 : 1);
    echo 'Nuevo valor de \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;

    ini_restore($setting);
    echo 'Valor original de \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;
    ?>

El ejemplo anterior mostrará:

    Valor actual de 'html_errors': 1
    Nuevo valor de 'html_errors': 0
    Valor original de 'html_errors': 1

### Ver también

- ini_get() - Lee el valor de una opción de configuración
- ini_get_all() - Lee todos los valores de configuración
- ini_set() - Modifica el valor de una opción de configuración

# ini_set

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_set — Modifica el valor de una opción de configuración

### Descripción

function ini_set(string `$option`, string|int|float|bool|null `$value`): string|false

Cambia el valor de la opción de configuración `varname` y le asigna el valor de `newvalue`. El valor de la opción de configuración será modificado durante toda la ejecución del script y específicamente para este script. Volverá a su valor por omisión al finalizar el script.

### Parámetros

`option`

  Las opciones disponibles no pueden ser todas modificadas con ini_set(). La lista de todas las opciones disponibles se encuentra en el apéndice.

`value`

  El nuevo valor para la opción.

### Valores devueltos

Devuelve el valor anterior en caso de éxito, `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | `value` ahora acepta cualquier tipo de valor escalar (incluyendo `null`). Anteriormente, solo se aceptaban valores de tipo string.

### Ejemplos

Ejemplo #1 Define una opción de configuración

    <?php
    echo ini_get('display_errors');

    if (!ini_get('display_errors')) {
        ini_set('display_errors', '1');
    }

    echo ini_get('display_errors');
    ?>

### Ver también

- get_cfg_var() - Devuelve el valor de una opción de PHP
- ini_get() - Lee el valor de una opción de configuración
- ini_get_all() - Lee todos los valores de configuración
- ini_restore() - Restaura el valor de la opción de configuración
- Cómo modificar la configuración

# memory_get_peak_usage

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

memory_get_peak_usage — Devuelve la cantidad máxima de memoria asignada por PHP

### Descripción

function memory_get_peak_usage(bool `$real_usage` = `false`): int

Devuelve la cantidad máxima de memoria, en bytes, que ha sido asignada al script PHP.

### Parámetros

`real_usage`

  Definir como `true` para obtener el tamaño real de la memoria asignada por el sistema. Si este argumento no está definido o vale `false`, solo se devolverá la memoria utilizada por `emalloc()`.

### Valores devueltos

Devuelve la cantidad de memoria, en bytes.

### Ver también

- memory_get_usage() - Indica la cantidad de memoria utilizada por PHP
- memory_reset_peak_usage() - Reinicia el uso máximo de memoria
- memory_limit

# memory_get_usage

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

memory_get_usage — Indica la cantidad de memoria utilizada por PHP

### Descripción

function memory_get_usage(bool `$real_usage` = `false`): int

Devuelve la cantidad de memoria asignada a PHP en este momento.

### Parámetros

`real_usage`

  Definir como `true` para obtener el tamaño total de la memoria asignada por el sistema. Si este argumento no está definido o es `false`, solo se retornará la memoria utilizada.

> Nota:

> PHP solo puede rastrear la memoria asignada por `emalloc()`

### Valores devueltos

Devuelve la cantidad de memoria, en bytes.

### Ejemplos

Ejemplo #1 Ejemplo con memory_get_usage()

    <?php
    // Esto es solo un ejemplo. Los números a continuación
    // variarán según los sistemas y las configuraciones

    echo memory_get_usage() . "\n"; // 36640

    $a = str_repeat("Hello", 4242);

    echo memory_get_usage() . "\n"; // 57960

    unset($a);

    echo memory_get_usage() . "\n"; // 36744

    ?>

### Ver también

- memory_get_peak_usage() - Devuelve la cantidad máxima de memoria asignada por PHP
- memory_limit

# memory_reset_peak_usage

(PHP 8 >= 8.2.0)

memory_reset_peak_usage — Reinicia el uso máximo de memoria

### Descripción

function memory_reset_peak_usage(): void

Reinicia el uso máximo de memoria devuelto por la función memory_get_peak_usage().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo de memory_reset_peak_usage()

    <?php

    var_dump(memory_get_peak_usage());

    $a = str_repeat("Hello", 424242);
    var_dump(memory_get_peak_usage());

    unset($a);
    memory_reset_peak_usage();

    $a = str_repeat("Hello", 2424);
    var_dump(memory_get_peak_usage());

    ?>

Resultado del ejemplo anterior es similar a:

    int(422440)
    int(2508672)
    int(399208)

### Ver también

- memory_get_peak_usage() - Devuelve la cantidad máxima de memoria asignada por PHP

# php_ini_loaded_file

(PHP 5 >= 5.2.4, PHP 7, PHP 8)

php_ini_loaded_file — Obtiene la ruta de un archivo php.ini cargado

### Descripción

function php_ini_loaded_file(): string|false

Verifica si un archivo php.ini está cargado y obtiene su ruta.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

La ruta del archivo php.ini cargado, o `false` si no se ha cargado ninguno.

### Ejemplos

Ejemplo #1 Ejemplo con php_ini_loaded_file()

    <?php
    $inipath = php_ini_loaded_file();

    if ($inipath) {
        echo 'php.ini cargado : ' . $inipath;
    } else {
        echo 'No se ha cargado ningún archivo php.ini';
    }
    ?>

Resultado del ejemplo anterior es similar a:

    php.ini cargado : /usr/local/php/php.ini

### Ver también

- php_ini_scanned_files() - Devuelve la lista de ficheros .ini analizados en los directorios de configuración adicionales
- phpinfo() - Muestra numerosas informaciones sobre la configuración de PHP
- El archivo de configuración

# php_ini_scanned_files

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

php_ini_scanned_files — Devuelve la lista de ficheros .ini analizados en los directorios de configuración adicionales

### Descripción

function php_ini_scanned_files(): string|false

php_ini_scanned_files() devuelve una lista de nombres de ficheros de configuración analizados después de php.ini. Esta lista está en formato CSV. Los directorios examinados son definidos por una opción de configuración durante la compilación, y opcionalmente por una variable de entorno durante la ejecución: más información está disponible en el guía de instalación.

Los ficheros de configuración devueltos incluyen la ruta completa.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un string donde los ficheros .ini están separados por comas en caso de éxito. Cada coma es seguida por un retorno de línea. Si la directiva de configuración --with-config-file-scan-dir no ha sido definida y la variable de entorno PHP_INI_SCAN_DIR no está definida, `false` es devuelto. Si estaba definida y el directorio estaba vacío, una cadena vacía es devuelta. Si un fichero es ilegible, el fichero será igualmente incluido en el string devuelto pero también provocará un error PHP. Este error PHP será visible tanto durante la compilación como al utilizar php_ini_scanned_files().

### Ejemplos

Ejemplo #1 Un ejemplo de lista devuelta por php_ini_scanned_files()

    <?php
    if ($filelist = php_ini_scanned_files()) {
        if (strlen($filelist) > 0) {
            $files = explode(',', $filelist);

            foreach ($files as $file) {
                echo "<li>" . trim($file) . "</li>\n";
            }
        }
    }
    ?>

### Ver también

- ini_set() - Modifica el valor de una opción de configuración
- phpinfo() - Muestra numerosas informaciones sobre la configuración de PHP
- php_ini_loaded_file() - Obtiene la ruta de un archivo php.ini cargado

# php_sapi_name

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

php_sapi_name — Devuelve el tipo de interfaz utilizada entre el servidor web y PHP

### Descripción

function php_sapi_name(): string|false

Devuelve una cadena en minúsculas que describe el tipo de interfaz (la API, SAPI del servidor) que PHP utiliza. Por ejemplo, en PHP CLI, esta cadena será "cli" mientras que con Apache, puede tener varios valores diferentes según el SAPI exacto utilizado. Las posibles valores se listan a continuación.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el tipo de la interfaz, en forma de string en minúsculas, o `false` si ocurre un error.

A continuación se muestra una lista no exhaustiva de los posibles valores : `apache`, `apache2handler`, `cgi` (hasta PHP 5.3), `cgi-fcgi`, `cli`, `cli-server`, `embed`, `fpm-fcgi`, `litespeed`, `phpdbg`.

### Ejemplos

Ejemplo #1 Ejemplo con php_sapi_name()

Este ejemplo busca la subcadena `cgi` ya que también puede ser `cgi-fcgi`.

    <?php
    $sapi_type = php_sapi_name();
    if (substr($sapi_type, 0, 3) == 'cgi') {
        echo "Se utiliza CGI PHP\n";
    } else {
        echo "No se utiliza CGI PHP\n";
    }
    ?>

### Notas

> Nota: Un enfoque alternativo

> La constante PHP `PHP_SAPI` tiene un valor idéntico a php_sapi_name().

Sugerencia

# Un comportamiento inesperado

El SAPI definido no debe ser ambiguo, ya que por ejemplo, en lugar de `apache`, puede ser definido como `apache2handler`.

### Ver también

- PHP_SAPI

# php_uname

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

php_uname — Devuelve información sobre el sistema operativo

### Descripción

function php_uname(string `$mode` = "a"): string

php_uname() devuelve una descripción del sistema operativo en el que se ejecuta PHP. Es la misma cadena que se ve al principio de phpinfo(). Si solo se desea conocer el nombre del sistema operativo, puede utilizarse la constante `PHP_OS`, pero debe tenerse en cuenta que esta constante contiene el nombre del sistema en el que PHP fue compilado.

En algunas antiguas plataformas Unix, no es posible determinar las informaciones corrientes del SO, en cuyo caso esta función se limita a devolver el nombre del SO en el que PHP fue compilado. Esto solo ocurrirá si la biblioteca `uname()` no existe o no funciona.

### Parámetros

`mode`

  `mode` es un solo carácter que define qué información se devolverá:

  - `'a'`: Este es el valor por omisión. Devuelve las mismas informaciones que los modos individuales `'s'`, `'n'`, `'r'`, `'v'`, `'m'` separadas por espacios.

  - `'s'`: nombre del sistema operativo. Por ejemplo, `FreeBSD`.
  - `'n'`: nombre del host. Por ejemplo, `localhost.example.com`.
  - `'r'`: nombre de la versión. Por ejemplo, `5.1.2-RELEASE`.
  - `'v'`: información sobre la versión. Varía enormemente según el sistema operativo.
  - `'m'`: tipo de máquina. Por ejemplo, `i386`.

### Valores devueltos

Devuelve la descripción, en forma de string.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Levanta una excepción ValueError cuando se especifica un `mode` inválido.

### Ejemplos

Ejemplo #1 Ejemplos con php_uname()

    <?php
    echo php_uname();
    echo PHP_OS;

    /* Salidas posibles:
    Linux localhost 2.4.21-0.13mdk #1 Fri Mar 14 15:08:06 EST 2003 i686
    Linux

    FreeBSD localhost 3.2-RELEASE #15: Mon Dec 17 08:46:02 GMT 2001
    FreeBSD

    Windows NT XN1 5.1 build 2600
    WINNT
    */

    if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
        echo 'El servidor se ejecuta en Windows !';
    } else {
        echo 'El servidor no se ejecuta en Windows !';
    }

    ?>

Existen también algunas constantes PHP predefinidas relacionadas que pueden resultar útiles, por ejemplo:

Ejemplo #2 Ejemplos con algunas constantes relacionadas con el sistema

    <?php
    // *nix
    echo DIRECTORY_SEPARATOR; // /
    echo PHP_SHLIB_SUFFIX;    // so
    echo PATH_SEPARATOR;      // :

    // Win*
    echo DIRECTORY_SEPARATOR; // \
    echo PHP_SHLIB_SUFFIX;    // dll
    echo PATH_SEPARATOR;      // ;
    ?>

### Ver también

- phpversion() - Devuelve el número de la versión actual de PHP
- php_sapi_name() - Devuelve el tipo de interfaz utilizada entre el servidor web y PHP
- phpinfo() - Muestra numerosas informaciones sobre la configuración de PHP

# phpcredits

(PHP 4, PHP 5, PHP 7, PHP 8)

phpcredits — Muestra los créditos de PHP

### Descripción

function phpcredits(int `$flags` = `CREDITS_ALL`): true

Muestra la lista de desarrolladores de PHP, módulos, etc. Genera el código HTML apropiado para insertar la información en una página.

### Parámetros

`flags`

  Para generar una página personalizada sobre los créditos, debe utilizarse el argumento `flags`.

  Argumentos predefinidos de phpcredits()
  Nombre | Descripción
  --- | ---
  CREDITS_ALL | Todos los créditos, equivalente a: `CREDITS_DOCS` + `CREDITS_GENERAL` + `CREDITS_GROUP` + `CREDITS_MODULES` + `CREDITS_FULLPAGE`. La función genera entonces una página HTML completa.
  CREDITS_DOCS | Los créditos del grupo de documentación
  CREDITS_FULLPAGE | En general, este argumento se utiliza con otras constantes. Indica que la página generada debe ser una página HTML completa, con todas las etiquetas necesarias.
  CREDITS_GENERAL | Créditos Generales: diseño y concepción del lenguaje, autores de PHP y del módulo SAPI.
  CREDITS_GROUP | Una lista de los desarrolladores principales
  CREDITS_MODULES | Una lista de las extensiones de PHP y sus autores
  CREDITS_SAPI | Una lista de las API de servidor para PHP y sus autores

### Valores devueltos

Retorna siempre `true`.

### Ejemplos

Ejemplo #1 Ejemplo con phpcredits()

    <?php
    phpcredits(CREDITS_GENERAL);
    ?>

Ejemplo #2 Muestra los desarrolladores principales así como el grupo de documentación

    <?php
    phpcredits(CREDITS_GROUP | CREDITS_DOCS | CREDITS_FULLPAGE);
    ?>

Ejemplo #3 Muestra todos los créditos

    <html>
     <head>
      <title>Mi página de créditos</title>
     </head>
     <body>
    <?php
    // Un poco de su código
    phpcredits(CREDITS_ALL - CREDITS_FULLPAGE);
    // Más de su código
    ?>
     </body>
    </html>

### Notas

> Nota:

> La función phpcredits() muestra texto plano en lugar de HTML cuando se utiliza en modo CLI.

### Ver también

- phpversion() - Devuelve el número de la versión actual de PHP
- phpinfo() - Muestra numerosas informaciones sobre la configuración de PHP

# phpinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

phpinfo — Muestra numerosas informaciones sobre la configuración de PHP

### Descripción

function phpinfo(int `$flags` = `INFO_ALL`): true

Muestra numerosas informaciones sobre PHP, relativas a su configuración actual: opciones de compilación, extensiones, versión, informaciones sobre el servidor, y el entorno (cuando es compilado como módulo), entorno PHP, informaciones sobre el sistema, rutas, valores generales y locales de configuración, encabezados HTTP y la licencia PHP.

Como todos los sistemas están configurados de manera diferente, phpinfo() sirve generalmente para verificar la configuración así como las variables predefinidas, para una plataforma dada.

phpinfo() es una buena herramienta de depuración, ya que muestra el contenido de todas las variables EGPCS (Entorno, GET, POST, Cookie, Servidor).

### Parámetros

`flags`

  La visualización puede ser personalizada utilizando una o varias de las constantes siguientes. Estas son combinables con el operador a nivel de bits, y deben ser pasadas en el argumento `flags`. También se pueden sumar estas constantes.

  Opciones de phpinfo()
  Nombre de la constante | Valor | Descripción
  --- | --- | ---
  INFO_GENERAL | 1 | La línea de configuración, la ruta del php.ini, la fecha de compilación, el servidor web, el sistema, etc.
  INFO_CREDITS | 2 | Los créditos de PHP. Ver también phpcredits().
  INFO_CONFIGURATION | 4 | Valores actuales locales y generales de las directivas PHP. Ver también la función ini_get().
  INFO_MODULES | 8 | Módulos cargados y su configuración específica. Ver también la función get_loaded_extensions().
  INFO_ENVIRONMENT | 16 | Informaciones sobre las variables de entorno, que están disponibles en la variable $_ENV.
  INFO_VARIABLES | 32 | Muestra todas las variables predefinidas, provenientes del entorno, el método GET, el método POST, las cookies y el servidor.
  INFO_LICENSE | 64 | La licencia PHP. Ver también » la FAQ de la licencia.
  INFO_ALL | -1 | Muestra todas las informaciones mencionadas.

### Valores devueltos

Retorna siempre `true`.

### Ejemplos

Ejemplo #1 Ejemplo con phpinfo()

    <?php

    // Muestra todas las informaciones, como lo haría INFO_ALL
    phpinfo();

    // Muestra únicamente el módulo de información.
    // phpinfo(8) proporcionaría las mismas informaciones.
    phpinfo(INFO_MODULES);

    ?>

### Notas

> Nota:

> En las versiones anteriores a PHP 5.5, parte de las informaciones mostradas están desactivadas si la directiva expose_php está configurada con el valor `off`. Esto incluye los logos PHP y Zend, así como los créditos.

> Nota:

> phpinfo() muestra texto en lugar de HTML cuando se utiliza la versión CLI.

### Ver también

- phpversion() - Devuelve el número de la versión actual de PHP
- phpcredits() - Muestra los créditos de PHP
- ini_get() - Lee el valor de una opción de configuración
- ini_set() - Modifica el valor de una opción de configuración
- get_loaded_extensions() - Devuelve la lista de todos los módulos compilados y cargados
- las variables predefinidas

# phpversion

(PHP 4, PHP 5, PHP 7, PHP 8)

phpversion — Devuelve el número de la versión actual de PHP

### Descripción

function phpversion(?string `$extension` = `null`): string|false

Devuelve el número de la versión actual de PHP.

### Parámetros

`extension`

  Un nombre de extensión, opcional.

### Valores devueltos

Devuelve la versión actual de PHP como un string. Si se proporciona un argumento string al parámetro `extension`, phpversion() devuelve la versión de esta extensión, o `false` si no hay información de versión asociada o esta extensión no está activada.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `extension` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con phpversion()

    <?php

    // muestra el número de versión actual de PHP.
    echo 'Versión actual de PHP: ' . phpversion();

    // muestra por ejemplo '1.22.3' o nada si esta extensión no está activa
    echo phpversion('tidy');
    ?>

Ejemplo #2 Ejemplo con `PHP_VERSION_ID`

    <?php

    /**
     * PHP_VERSION_ID se define como un número, donde a mayor número,
     * más reciente es la versión de PHP utilizada. Se define como en
     * la expresión anterior:
     *
     * $version_id = $major_version * 10000 + $minor_version * 100 + $release_version;
     *
     * Ahora, con PHP_VERSION_ID, se pueden verificar las funcionalidades
     * que esta versión de PHP puede tener, lo que evita usar version_compare()
     * cada vez que se verifica si la versión actual de PHP puede no
     * soportar una funcionalidad.
     *
     * Por ejemplo, aquí se pueden definir las constantes PHP_*_VERSION que no
     * están disponibles en versiones a partir de 5.2.7.
     */

    if (PHP_VERSION_ID < 50207) {
        define('PHP_MAJOR_VERSION',   $version[0]);
        define('PHP_MINOR_VERSION',   $version[1]);
        define('PHP_RELEASE_VERSION', $version[2]);

        // etc.

    }

    ?>

### Notas

> Nota:

> Esta información también está disponible a través de la constante predefinida `PHP_VERSION`. Más información sobre versiones, con las constantes `PHP_VERSION_*`.

> Nota:

> Algunas extensiones pueden definir su propio número de versión. Sin embargo, la mayoría de las extensiones incluidas utilizarán la versión de PHP como número de versión.

### Ver también

- las constantes PHP_VERSION
- version_compare() - Comparar dos strings de versión en el formato de versiones de PHP
- phpinfo() - Muestra numerosas informaciones sobre la configuración de PHP
- phpcredits() - Muestra los créditos de PHP
- zend_version() - Lee la versión actual del motor Zend

# putenv

(PHP 4, PHP 5, PHP 7, PHP 8)

putenv — Establece el valor de una variable de entorno

### Descripción

function putenv(string `$assignment`): bool

Agrega `setting` al entorno del servidor. La variable de entorno existirá únicamente durante la petición actual. Al final de la petición el entorno es recuperado a su estado original.

### Parámetros

`asignación`

  El parámetro, como p.ej. `"FOO=BAR"`

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Definición de una variable de entorno

    <?php
    putenv("UNIQID=$uniqid");
    ?>

### Ver también

- getenv() - Retorna el valor de una o todas las variables de entorno
- apache_setenv() - Establece una variable subprocess_env de Apache

# restore_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7)

restore_include_path — Restaura el valor de la directiva de configuración include_path

Advertencia

Esta función está OBSOLETA a partir de PHP 7.4.0, y ha sido ELIMINADA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

function restore_include_path(): void

Restaura el valor de la directiva de configuración include_path a su valor original al inicio del script, tal como se indica en el php.ini.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función ha sido eliminada.
7.4.0 | Esta función está obsoleta.

### Ejemplos

Ejemplo #1 Ejemplo con restore_include_path()

    <?php

    echo get_include_path();  // .:/usr/local/lib/php

    set_include_path('/inc');

    echo get_include_path();  // /inc

    restore_include_path();

    // O usar ini_restore()
    ini_restore('include_path');

    echo get_include_path();  // .:/usr/local/lib/php

    ?>

### Ver también

- ini_restore() - Restaura el valor de la opción de configuración
- get_include_path() - Lee el valor de la directiva de configuración include_path
- set_include_path() - Modifica el valor de la directiva de configuración include_path
- include - include

# set_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

set_include_path — Modifica el valor de la directiva de configuración include_path

### Descripción

function set_include_path(string `$include_path`): string|false

Modifica el valor de la directiva de configuración include_path, durante la ejecución del script en curso.

### Parámetros

`include_path`

  El nuevo valor para la directiva de configuración include_path

### Valores devueltos

Devuelve el valor anterior de include_path en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con set_include_path()

    <?php
    set_include_path('/usr/lib/pear');

    // O usar ini_set()
    ini_set('include_path', '/usr/lib/pear');
    ?>

Ejemplo #2 Añadir al camino de inclusión

Usando la constante `PATH_SEPARATOR`, es posible extender el camino de inclusión según el sistema.

En este ejemplo, se añade /usr/lib/pear al final del actual `include_path`.

    <?php
    $path = '/usr/lib/pear';
    set_include_path(get_include_path() . PATH_SEPARATOR . $path);
    ?>

### Ver también

- ini_set() - Modifica el valor de una opción de configuración
- get_include_path() - Lee el valor de la directiva de configuración include_path
- restore_include_path() - Restaura el valor de la directiva de configuración include_path
- include - include

# set_time_limit

(PHP 4, PHP 5, PHP 7, PHP 8)

set_time_limit — Establece el tiempo máximo de ejecución de un script

### Descripción

function set_time_limit(int `$seconds`): bool

Establece el tiempo de expiración de un script, en segundos. Si se alcanza este límite, el script se interrumpe y se genera un error fatal. El valor por omisión es 30 segundos o, si está definido, el valor de la directiva `max_execution_time` en el php.ini.

Cuando se invoca, set_time_limit() reinicia el contador. En otras palabras, si el límite por omisión es de 30 segundos, y después de 25 segundos de ejecución del script se realiza la llamada `set_time_limit(20)`, entonces el script ejecutará un total de 45 segundos antes de finalizar.

### Parámetros

`seconds`

  El tiempo máximo de ejecución, en segundos. Si es `0`, no se establece límite alguno.

### Valores devueltos

Devuelve `true` en caso de éxito, o `false` si ocurre un error.

### Notas

> Nota:

> La función set_time_limit() y la directiva de configuración max_execution_time solo afectan al tiempo de ejecución del script en sí. Todo tiempo pasado fuera del script, como llamadas al sistema utilizando system(), operaciones en flujos, consultas a bases de datos, etc., no se tienen en cuenta al calcular la duración máxima de ejecución del script. Esto no es válido en Windows donde el tiempo medido es el tiempo real.

### Ver también

- max_execution_time
- max_input_time

# sys_get_temp_dir

(PHP 5 >= 5.2.1, PHP 7, PHP 8)

sys_get_temp_dir — Devuelve la ruta del directorio utilizado para los ficheros temporales

### Descripción

function sys_get_temp_dir(): string

Devuelve la ruta del directorio PHP donde se almacenan los ficheros temporales por defecto.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la ruta del directorio temporal.

### Ejemplos

Ejemplo #1 Ejemplo con sys_get_temp_dir()

    <?php
    // Creación de un fichero temporal en el directorio
    // de ficheros temporales, utilizando la función sys_get_temp_dir()
    $temp_file = tempnam(sys_get_temp_dir(), 'Tux');

    echo $temp_file;
    ?>

Resultado del ejemplo anterior es similar a:

    C:\Windows\Temp\TuxA318.tmp

### Ver también

- tmpfile() - Crea un fichero temporal
- tempnam() - Crea un fichero con un nombre único

# version_compare

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

version_compare — Comparar dos strings de versión en el formato de versiones de PHP

### Descripción

function version_compare(string `$version1`, string `$version2`, ?string `$operator` = `null`): int|bool

version_compare() compara dos versiones de PHP estandarizadas.

version_compare() reemplaza inicialmente `_`, `-` y `+` por un punto (`.`) en los strings de versión y también inserta puntos antes y después de cualquier carácter no numérico para que, por ejemplo, '4.3.5RC1' se convierta en '4.3.5.RC.1'. Luego, compara los fragmentos de izquierda a derecha. Si una parte contiene caracteres alfabéticos, estos son gestionados en el siguiente orden: `any string not found in this list` < `dev` < `alpha` = `a` < `beta` = `b` < `RC` = `rc` < `#` < `pl` = `p`. De esta manera, es posible comparar no solo versiones de diferentes niveles, como '4.1' y '4.1.2', sino también versiones de desarrollo de PHP, en cualquier etapa.

### Parámetros

`version1`

  Primer número de versión.

`version2`

  Segundo número de versión.

`operator`

  Un operador opcional. Los operadores posibles son: `<`, `lt`, `<=`, `le`, `>`, `gt`, `>=`, `ge`, `==`, `=`, `eq`, `!=`, `<>`, `ne` respectivamente.

  Este parámetro es sensible a mayúsculas/minúsculas, por lo que los valores deben estar en minúsculas.

### Valores devueltos

Por omisión, version_compare() devuelve `-1` si la primera versión es inferior a la segunda, `0` si son iguales, y `1` si la segunda es inferior a la primera.

Cuando se utiliza el parámetro opcional `operator`, la función devuelve `true` si la relación es la especificada por el operador, `false` en caso contrario.

### Ejemplos

Los ejemplos siguientes utilizan la constante `PHP_VERSION`, sabiendo que contiene el valor de la versión de PHP utilizada para ejecutar el código.

Ejemplo #1 Ejemplo con version_compare()

    <?php
    if (version_compare(PHP_VERSION, '7.0.0') >= 0) {
        echo 'Tengo al menos la versión 7.0.0 de PHP; mi versión: ' . PHP_VERSION . "\n";
    }

    if (version_compare(PHP_VERSION, '5.3.0') >= 0) {
        echo 'Tengo al menos la versión 5.3.0 de PHP; mi versión: ' . PHP_VERSION . "\n";
    }

    if (version_compare(PHP_VERSION, '5.0.0', '>=')) {
        echo 'Tengo al menos la versión 5.0.0 de PHP; mi versión: ' . PHP_VERSION . "\n";
    }

    if (version_compare(PHP_VERSION, '5.0.0', '<')) {
        echo 'Aún utilizo PHP 4; mi versión: ' . PHP_VERSION . "\n";
    }
    ?>

### Notas

> Nota:

> La constante `PHP_VERSION` contiene la versión actual de PHP.

> Nota:

> Tenga en cuenta que las versiones intermedias, como `5.3.0-dev`, son consideradas inferiores a sus versiones finales (como 5.3.0).

> Nota:

> Los strings especiales de versión como `alpha` y `beta` son sensibles a mayúsculas/minúsculas. Los strings de versión provenientes de fuentes arbitrarias que no siguen el estándar de PHP deben ser convertidos a minúsculas utilizando la función strtolower() antes de llamar a la función version_compare().

### Ver también

- phpversion() - Devuelve el número de la versión actual de PHP
- php_uname() - Devuelve información sobre el sistema operativo
- function_exists() - Indica si una función está definida

# zend_thread_id

(PHP 5, PHP 7, PHP 8)

zend_thread_id — Devuelve un identificador único del hilo actual

### Descripción

function zend_thread_id(): int

Esta función devuelve un identificador único para el hilo actual.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el identificador del hilo, en forma de int.

### Ejemplos

Ejemplo #1 Ejemplo con zend_thread_id()

    <?php
    $thread_id = zend_thread_id();

    echo 'ID del hilo actual : ' . $thread_id;
    ?>

Resultado del ejemplo anterior es similar a:

    ID del hilo actual : 7864

### Notas

> Nota:

> Esta función solo está disponible si PHP ha sido compilado con soporte ZTS (`Zend Thread Safety`) y el modo de depuración (`--enable-debug`).

# zend_version

(PHP 4, PHP 5, PHP 7, PHP 8)

zend_version — Lee la versión actual del motor Zend

### Descripción

function zend_version(): string

Devuelve una cadena que contiene el número de versión del motor de análisis Zend actualmente en uso.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de versión del motor Zend, en forma de string.

### Ejemplos

Ejemplo #1 Ejemplo con zend_version()

    <?php
    echo "Versión del motor Zend: " . zend_version();
    ?>

Resultado del ejemplo anterior es similar a:

    Versión del motor Zend: 2.2.0

### Ver también

- phpinfo() - Muestra numerosas informaciones sobre la configuración de PHP
- phpcredits() - Muestra los créditos de PHP
- phpversion() - Devuelve el número de la versión actual de PHP

## Tabla de contenidos

- assert — Verifica una aserción
- assert_options — Define/recupere diferentes opciones de aserciones
- cli_get_process_title — Devuelve el título del proceso actual
- cli_set_process_title — Define el título del proceso
- dl — Carga una extensión PHP dinámicamente
- extension_loaded — Determina si una extensión está cargada o no
- gc_collect_cycles — Fuerza la recolección de los ciclos de basura existentes
- gc_disable — Desactiva el recolector de referencia circular
- gc_enable — Activa el colector de referencia circular
- gc_enabled — Devuelve el estado del colector de referencia circular
- gc_mem_caches — Libera memoria utilizada por el gestor de memoria de Zend Engine
- gc_status — Obtiene información sobre el recolector de basura
- get_cfg_var — Devuelve el valor de una opción de PHP
- get_current_user — Devuelve el nombre del propietario del script actual
- get_defined_constants — Devuelve la lista de constantes y sus valores
- get_extension_funcs — Lista las funciones de una extensión
- get_include_path — Lee el valor de la directiva de configuración include_path
- get_included_files — Devuelve un array con los nombres de los ficheros que son incluidos en un script
- get_loaded_extensions — Devuelve la lista de todos los módulos compilados y cargados
- get_magic_quotes_gpc — Devuelve la configuración actual de la opción magic_quotes_gpc
- get_magic_quotes_runtime — Devuelve la configuración actual de la opción magic_quotes_runtime
- get_required_files — Alias de get_included_files
- get_resources — Devuelve los recursos activos
- getenv — Retorna el valor de una o todas las variables de entorno
- getlastmod — Devuelve la fecha de última modificación de la página
- getmygid — Retorna el GID del propietario del script
- getmyinode — Devuelve el inodo del script
- getmypid — Devuelve el número de proceso actual de PHP
- getmyuid — Retorna el UID del propietario del script actual
- getopt — Lee las opciones pasadas en la línea de comandos
- getrusage — Devuelve el nivel de utilización de los recursos
- ini_alter — Alias de ini_set
- ini_get — Lee el valor de una opción de configuración
- ini_get_all — Lee todos los valores de configuración
- ini_parse_quantity — Devuelve el tamaño interpretado a partir de la sintaxis abreviada ini
- ini_restore — Restaura el valor de la opción de configuración
- ini_set — Modifica el valor de una opción de configuración
- memory_get_peak_usage — Devuelve la cantidad máxima de memoria asignada por PHP
- memory_get_usage — Indica la cantidad de memoria utilizada por PHP
- memory_reset_peak_usage — Reinicia el uso máximo de memoria
- php_ini_loaded_file — Obtiene la ruta de un archivo php.ini cargado
- php_ini_scanned_files — Devuelve la lista de ficheros .ini analizados en los directorios de configuración adicionales
- php_sapi_name — Devuelve el tipo de interfaz utilizada entre el servidor web y PHP
- php_uname — Devuelve información sobre el sistema operativo
- phpcredits — Muestra los créditos de PHP
- phpinfo — Muestra numerosas informaciones sobre la configuración de PHP
- phpversion — Devuelve el número de la versión actual de PHP
- putenv — Establece el valor de una variable de entorno
- restore_include_path — Restaura el valor de la directiva de configuración include_path
- set_include_path — Modifica el valor de la directiva de configuración include_path
- set_time_limit — Establece el tiempo máximo de ejecución de un script
- sys_get_temp_dir — Devuelve la ruta del directorio utilizado para los ficheros temporales
- version_compare — Comparar dos strings de versión en el formato de versiones de PHP
- zend_thread_id — Devuelve un identificador único del hilo actual
- zend_version — Lee la versión actual del motor Zend

- Instalación/Configuración
  - Configuración en tiempo de ejecución
- Constantes predefinidas
- Funciones de Opciones/Info de PHP
  - assert — Verifica una aserción
  - assert_options — Define/recupere diferentes opciones de aserciones
  - cli_get_process_title — Devuelve el título del proceso actual
  - cli_set_process_title — Define el título del proceso
  - dl — Carga una extensión PHP dinámicamente
  - extension_loaded — Determina si una extensión está cargada o no
  - gc_collect_cycles — Fuerza la recolección de los ciclos de basura existentes
  - gc_disable — Desactiva el recolector de referencia circular
  - gc_enable — Activa el colector de referencia circular
  - gc_enabled — Devuelve el estado del colector de referencia circular
  - gc_mem_caches — Libera memoria utilizada por el gestor de memoria de Zend Engine
  - gc_status — Obtiene información sobre el recolector de basura
  - get_cfg_var — Devuelve el valor de una opción de PHP
  - get_current_user — Devuelve el nombre del propietario del script actual
  - get_defined_constants — Devuelve la lista de constantes y sus valores
  - get_extension_funcs — Lista las funciones de una extensión
  - get_include_path — Lee el valor de la directiva de configuración include_path
  - get_included_files — Devuelve un array con los nombres de los ficheros que son incluidos en un script
  - get_loaded_extensions — Devuelve la lista de todos los módulos compilados y cargados
  - get_magic_quotes_gpc — Devuelve la configuración actual de la opción magic_quotes_gpc
  - get_magic_quotes_runtime — Devuelve la configuración actual de la opción magic_quotes_runtime
  - get_required_files — Alias de get_included_files
  - get_resources — Devuelve los recursos activos
  - getenv — Retorna el valor de una o todas las variables de entorno
  - getlastmod — Devuelve la fecha de última modificación de la página
  - getmygid — Retorna el GID del propietario del script
  - getmyinode — Devuelve el inodo del script
  - getmypid — Devuelve el número de proceso actual de PHP
  - getmyuid — Retorna el UID del propietario del script actual
  - getopt — Lee las opciones pasadas en la línea de comandos
  - getrusage — Devuelve el nivel de utilización de los recursos
  - ini_alter — Alias de ini_set
  - ini_get — Lee el valor de una opción de configuración
  - ini_get_all — Lee todos los valores de configuración
  - ini_parse_quantity — Devuelve el tamaño interpretado a partir de la sintaxis abreviada ini
  - ini_restore — Restaura el valor de la opción de configuración
  - ini_set — Modifica el valor de una opción de configuración
  - memory_get_peak_usage — Devuelve la cantidad máxima de memoria asignada por PHP
  - memory_get_usage — Indica la cantidad de memoria utilizada por PHP
  - memory_reset_peak_usage — Reinicia el uso máximo de memoria
  - php_ini_loaded_file — Obtiene la ruta de un archivo php.ini cargado
  - php_ini_scanned_files — Devuelve la lista de ficheros .ini analizados en los directorios de configuración adicionales
  - php_sapi_name — Devuelve el tipo de interfaz utilizada entre el servidor web y PHP
  - php_uname — Devuelve información sobre el sistema operativo
  - phpcredits — Muestra los créditos de PHP
  - phpinfo — Muestra numerosas informaciones sobre la configuración de PHP
  - phpversion — Devuelve el número de la versión actual de PHP
  - putenv — Establece el valor de una variable de entorno
  - restore_include_path — Restaura el valor de la directiva de configuración include_path
  - set_include_path — Modifica el valor de la directiva de configuración include_path
  - set_time_limit — Establece el tiempo máximo de ejecución de un script
  - sys_get_temp_dir — Devuelve la ruta del directorio utilizado para los ficheros temporales
  - version_compare — Comparar dos strings de versión en el formato de versiones de PHP
  - zend_thread_id — Devuelve un identificador único del hilo actual
  - zend_version — Lee la versión actual del motor Zend

# Depurador interactivo PHP

# Introducción

Implementado como un módulo SAPI, phpdbg puede ejercer un control completo sobre el entorno sin afectar la funcionalidad o el rendimiento del código.

phpdbg tiene como objetivo ser una plataforma de depuración ligera, potente y fácil de usar para PHP. Ofrece las siguientes funcionalidades:

- Depuración paso a paso
- Punto de interrupción flexible (método de clase, función, archivo:línea, dirección, opcode)
- Acceso fácil a PHP con eval() integrado
- Una API de usuario
- SAPI Agnóstico - Fácilmente integrable
- Soporte de archivo de configuración PHP
- Super Globales JIT - ¡Defina las suyas!!
- Soporte readline opcional - Operación cómoda del terminal
- Operación fácil - Consulte la ayuda :)

Opción de línea de comandos
Opción | Argumento de ejemplo | Descripción
--- | --- | ---
-c | -c/my/php.ini | Define el archivo php.ini a cargar
-d | -dmemory_limit=4G | Define una directiva php.ini
-n |  | Desactiva el php.ini por defecto
-q |  | Suprime el banner de bienvenida
-v |  | Activa la salida oplog
-b |  | Desactiva el color
-i | -imy.init | Define el archivo .phpdbginit
-I |  | Ignora el .phpdbginit por defecto
-O | -Omy.oplog | Define el archivo de salida oplog
-r |  | Ejecuta el contexto de ejecución
-rr |  | Ejecuta el contexto de ejecución y sale después de la ejecución (sin respetar los puntos de interrupción)
-e |  | Genera información extendida para el depurador/profiler
-E |  | Activa la evaluación paso a paso con eval, ¡atención!
-s | -s=, -s=foo | Lee el código a ejecutar desde stdin con un delimitador opcional
-S | -Scli | Sobrescribe el nombre SAPI, ¡atención!
-l | -l4000 | Establece el puerto de la consola remota
-a | -a192.168.0.3 | Establece la dirección de enlace de la consola remota
-x |  | Activa la salida xml (en lugar de la salida de texto normal)
-p | -p, -p=func, -p* | Muestra los opcodes y sale
-h |  | Muestra el resumen de ayuda
-V |  | Muestra el número de versión
-- | -- arg1 arg2 | Utilizado para delimitar los argumentos phpdbg y php $argv; añada cualquier argumento $argv después

# Instalación/Configuración

## Tabla de contenidos

- Configuración en tiempo de ejecución

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración de phpdbg
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
phpdbg.eol | 2 | `INI_ALL` | Eliminada a partir de PHP 8.1.0
phpdbg.path |  | 6 | Eliminada a partir de PHP 8.1.0

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`phpdbg.eol` mixed

  El tipo de fin de línea a utilizar para la salida. Para definir el valor, se debe utilizar uno de los alias de string.

  int Valor | string Alias
  --- | ---
  `0` | `CRLF`, `crlf`, `DOS`, `dos`
  `1` | `LF`, `lf`, `UNIX`, `unix`
  `2` | `CR`, `cr`, `MAC`, `mac`

`phpdbg.path` string

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`PHPDBG_VERSION` (string)
`PHPDBG_FILE` (int)
  Eliminado desde PHP 7.3.0.
`PHPDBG_METHOD` (int)
  Eliminado desde PHP 7.3.0.
`PHPDBG_LINENO` (int)
  Eliminado desde PHP 7.3.0.
`PHPDBG_FUNC` (int)
  Eliminado desde PHP 7.3.0.
`PHPDBG_COLOR_PROMPT` (int)
`PHPDBG_COLOR_NOTICE` (int)
`PHPDBG_COLOR_ERROR` (int)

# phpdbg Funciones

# phpdbg_break_file

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_file — Inserta un punto de interrupción en una línea de un fichero

### Descripción

function phpdbg_break_file(string `$file`, int `$line`): void

Inserta un punto de interrupción en la línea `line` en el fichero `file`.

### Parámetros

`file`
  El nombre del fichero.
`line`
  El número de la línea.

### Valores devueltos

No se retorna ningún valor.

### Ver también

- phpdbg_break_function() - Inserta un punto de interrupción en la entrada de una función
- phpdbg_break_method() - Inserta un punto de interrupción en la entrada de un método
- phpdbg_break_next() - Inserta un punto de interrupción en el próximo opcode
- phpdbg_clear() - Elimina todos los puntos de interrupción

# phpdbg_break_function

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_function — Inserta un punto de interrupción en la entrada de una función

### Descripción

function phpdbg_break_function(string `$function`): void

Inserta un punto de interrupción en la entrada de la función `function`.

### Parámetros

`function`
  El nombre de la función.

### Valores devueltos

No se retorna ningún valor.

### Ver también

- phpdbg_break_file() - Inserta un punto de interrupción en una línea de un fichero
- phpdbg_break_method() - Inserta un punto de interrupción en la entrada de un método
- phpdbg_break_next() - Inserta un punto de interrupción en el próximo opcode
- phpdbg_clear() - Elimina todos los puntos de interrupción

# phpdbg_break_method

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_method — Inserta un punto de interrupción en la entrada de un método

### Descripción

function phpdbg_break_method(string `$class`, string `$method`): void

Inserta un punto de interrupción en la entrada del método `method` de la clase `class`.

### Parámetros

`class`
  El nombre de la clase.
`method`
  El nombre del método.

### Valores devueltos

No se retorna ningún valor.

### Ver también

- phpdbg_break_file() - Inserta un punto de interrupción en una línea de un fichero
- phpdbg_break_function() - Inserta un punto de interrupción en la entrada de una función
- phpdbg_break_next() - Inserta un punto de interrupción en el próximo opcode
- phpdbg_clear() - Elimina todos los puntos de interrupción

# phpdbg_break_next

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_next — Inserta un punto de interrupción en el próximo opcode

### Descripción

function phpdbg_break_next(): void

Inserta un punto de interrupción en el próximo opcode.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

### Ver también

- phpdbg_break_file() - Inserta un punto de interrupción en una línea de un fichero
- phpdbg_break_function() - Inserta un punto de interrupción en la entrada de una función
- phpdbg_break_method() - Inserta un punto de interrupción en la entrada de un método
- phpdbg_clear() - Elimina todos los puntos de interrupción

# phpdbg_clear

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_clear — Elimina todos los puntos de interrupción

### Descripción

function phpdbg_clear(): void

Elimina todos los puntos de interrupción que han sido definidos, ya sea mediante una de las funciones phpdbg_break_*(), o de manera interactiva a través de la consola.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

### Ver también

- phpdbg_break_file() - Inserta un punto de interrupción en una línea de un fichero
- phpdbg_break_function() - Inserta un punto de interrupción en la entrada de una función
- phpdbg_break_method() - Inserta un punto de interrupción en la entrada de un método
- phpdbg_break_next() - Inserta un punto de interrupción en el próximo opcode

# phpdbg_color

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_color — Define el color de ciertos elementos

### Descripción

function phpdbg_color(int `$element`, string `$color`): void

Define el color `color` para el elemento `element`.

### Parámetros

`element`
  Una de las constantes `PHPDBG_COLOR_*`.
`color`
  El nombre del color. Puede ser `white`, `red`, `green`, `yellow`, `blue`, `purple`, `cyan` o `black`, y, opcionalmente, con los complementos `-bold` o `-underline`; por ejemplo `white-bold` o `green-underline`.

### Valores devueltos

No se retorna ningún valor.

### Ver también

- phpdbg_prompt() - Define el indicador de comandos

# phpdbg_end_oplog

(PHP 7, PHP 8)

phpdbg_end_oplog — Finaliza un oplog

### Descripción

function phpdbg_end_oplog(array `$options` = []): ?array

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`options`

### Valores devueltos

# phpdbg_exec

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_exec — Intenta definir el contexto de ejecución

### Descripción

function phpdbg_exec(string `$context`): string|bool

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`context`

### Valores devueltos

Si el contexto de ejecución ha sido definido con éxito, este contexto será devuelto. Si el contexto de ejecución no ha sido definido, `true` será devuelto. Si un error ha ocurrido durante la definición del contexto, `false` será devuelto y un error de nivel `E_WARNING` será emitido.

# phpdbg_get_executable

(PHP 7, PHP 8)

phpdbg_get_executable — Devuelve un ejecutable

### Descripción

function phpdbg_get_executable(array `$options` = []): array

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`options`

### Valores devueltos

# phpdbg_prompt

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_prompt — Define el indicador de comandos

### Descripción

function phpdbg_prompt(string `$string`): void

Define el indicador de comandos para la cadena `string`.

### Parámetros

`string`
  La cadena a utilizar como indicador de comandos.

### Valores devueltos

No se retorna ningún valor.

### Ver también

- phpdbg_color() - Define el color de ciertos elementos

# phpdbg_start_oplog

(PHP 7, PHP 8)

phpdbg_start_oplog — Inicia un oplog

### Descripción

function phpdbg_start_oplog(): void

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

## Tabla de contenidos

- phpdbg_break_file — Inserta un punto de interrupción en una línea de un fichero
- phpdbg_break_function — Inserta un punto de interrupción en la entrada de una función
- phpdbg_break_method — Inserta un punto de interrupción en la entrada de un método
- phpdbg_break_next — Inserta un punto de interrupción en el próximo opcode
- phpdbg_clear — Elimina todos los puntos de interrupción
- phpdbg_color — Define el color de ciertos elementos
- phpdbg_end_oplog — Finaliza un oplog
- phpdbg_exec — Intenta definir el contexto de ejecución
- phpdbg_get_executable — Devuelve un ejecutable
- phpdbg_prompt — Define el indicador de comandos
- phpdbg_start_oplog — Inicia un oplog

- Instalación/Configuración
  - Configuración en tiempo de ejecución
- Constantes predefinidas
- phpdbg Funciones
  - phpdbg_break_file — Inserta un punto de interrupción en una línea de un fichero
  - phpdbg_break_function — Inserta un punto de interrupción en la entrada de una función
  - phpdbg_break_method — Inserta un punto de interrupción en la entrada de un método
  - phpdbg_break_next — Inserta un punto de interrupción en el próximo opcode
  - phpdbg_clear — Elimina todos los puntos de interrupción
  - phpdbg_color — Define el color de ciertos elementos
  - phpdbg_end_oplog — Finaliza un oplog
  - phpdbg_exec — Intenta definir el contexto de ejecución
  - phpdbg_get_executable — Devuelve un ejecutable
  - phpdbg_prompt — Define el indicador de comandos
  - phpdbg_start_oplog — Inicia un oplog

# runkit7

# Introducción

La extensión runkit7 proporciona medios para modificar las constantes, las funciones definidas por el usuario y las clases definidas por el usuario. Asimismo, proporciona variables superglobales personalizadas.

Este paquete es un fork del paquete » runkit que proporciona soporte para PHP 7.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución

## Requerimientos

Modificar constantes, funciones, clases y métodos así como las superglobales personalizadas funciona con todas las versiones de PHP 7. No se requieren exigencias especiales.

## Instalación

Esta extensión » PECL no está integrada en PHP.

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/runkit7.

Los binarios Windows (los archivos DLL) para esta extensión PECL están disponibles en el sitio web PECL.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de Configuración de Runkit
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
runkit.superglobal | "" | `INI_PERDIR` |
runkit.internal_override | "0" | `INI_SYSTEM` |

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`runkit.superglobal` string
  Una lista separada por comas de nombres de variables que van a ser tratadas como superglobales. Este valor debería estar establecido a través del archivo php.ini, pero puede funcionar en contextos de configuración por directorio dependiendo de su SAPI.

  Ejemplo #1 Superglobales personalizadas con runkit.superglobal=_FOO,_BAR en php.ini

      <?php
      function mostrar_valores() {
        echo "Foo es $_FOO\n";
        echo "Bar es $_BAR\n";
        echo "Baz es $_BAZ\n";
      }

      $_FOO = 'foo';
      $_BAR = 'bar';
      $_BAZ = 'baz';

      /* Muestra foo y bar, pero no baz */
      mostrar_valores();
      ?>

`runkit.internal_override` boolean
  Habilita la capacidad de modificar/renombrar/eliminar funciones internas.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`RUNKIT7_IMPORT_FUNCTIONS` (int)
  El flag runkit7_import() indica que las funciones normales deben ser importadas del archivo especificado.
`RUNKIT7_IMPORT_CLASS_METHODS` (int)
  El flag runkit7_import() indica que los métodos de clase deben ser importados del archivo especificado.
`RUNKIT7_IMPORT_CLASS_CONSTS` (int)
  El flag runkit7_import() indica que las constantes de clase deben ser importadas del archivo especificado.
`RUNKIT7_IMPORT_CLASS_PROPS` (int)
  El flag runkit7_import() indica que las propiedades de clase estándar deben ser importadas del archivo especificado.
`RUNKIT7_IMPORT_CLASS_STATIC_PROPS` (int)
  El flag runkit7_import() indica que las propiedades estáticas de clase deben ser importadas del archivo especificado. Disponible a partir de Runkit 1.0.1.
`RUNKIT7_IMPORT_CLASSES` (int)
  El flag runkit7_import() representa un OU a nivel de bits de las constantes `RUNKIT7_IMPORT_CLASS_*`.
`RUNKIT7_IMPORT_OVERRIDE` (int)
  El flag runkit7_import() indica que si alguna de las funciones, métodos, constantes o propiedades importados ya existen, deben ser sobrescritos por las nuevas definiciones. Si este flag no está definido, entonces todas las definiciones importadas que ya existan serán ignoradas.
`RUNKIT7_ACC_RETURN_REFERENCE` (int)
  Incluir este flag para hacer que la función o método creado o redefinido devuelva una referencia.
`RUNKIT7_ACC_PUBLIC` (int)
  El flag para runkit7_method_add() y runkit7_method_redefine() para hacer que el método sea público.
`RUNKIT7_ACC_PROTECTED` (int)
  El flag para runkit7_method_add() y runkit7_method_redefine() para hacer que el método sea protegido.
`RUNKIT7_ACC_PRIVATE` (int)
  El flag para runkit7_method_add() y runkit7_method_redefine() para hacer que el método sea privado.
`RUNKIT7_ACC_STATIC` (int)
  El flag para runkit7_method_add() y runkit7_method_redefine() para hacer que el método sea estático.
`RUNKIT7_FEATURE_MANIPULATION` (int)
  Igual a 1 si la manipulación en tiempo de ejecución está activada, y 0 en caso contrario.
`RUNKIT7_FEATURE_SUPERGLOBALS` (int)
  Igual a 1 si las superglobales personalizadas están activadas, y 0 en caso contrario.
`RUNKIT7_FEATURE_SANDBOX` (int)
  Siempre 0, es impracticable implementar la funcionalidad de entorno de pruebas en php 7.

# Funciones de runkit7

# runkit7_constant_add

(PECL runkit7 >= Unknown)

runkit7_constant_add — Similar a define(), pero permite definir constantes en las definiciones de clase también

### Descripción

function runkit7_constant_add(string `$constant_name`, mixed `$value`, int `$newVisibility` = ?): bool

### Parámetros

`constant_name`
  El nombre de la constante a declarar. Puede ser un string para indicar una constante global, o `classname::constname` para indicar una constante de clase.
`value`
  NULL, Bool, Long, Double, String, Array, o Resource a almacenar en la nueva constante.
`newVisibility`
  La visibilidad de la constante, para las constantes de clase. Público por omisión. Una de las constantes `RUNKIT7_ACC_*`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- define() - Define una constante
- runkit7_constant_redefine() - Redefine una constante ya definida
- runkit7_constant_remove() - Elimina una constante ya definida

# runkit7_constant_redefine

(PECL runkit7 >= Unknown)

runkit7_constant_redefine — Redefine una constante ya definida

### Descripción

function runkit7_constant_redefine(string `$constant_name`, mixed `$value`, int `$new_visibility` = ?): bool

### Parámetros

`constant_name`
  La constante a redefinir. Puede ser el nombre de una constante global, o `classname::constname` indicando una constante de clase.
`value`
  El valor a asignar a la constante.
`new_visibility`
  La nueva visibilidad de la constante, para constantes de clase. Por omisión, permanece sin cambios. Una de las constantes `RUNKIT7_ACC_*`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- runkit7_constant_add() - Similar a define(), pero permite definir constantes en las definiciones de clase también
- runkit7_constant_remove() - Elimina una constante ya definida

# runkit7_constant_remove

(PECL runkit7 >= Unknown)

runkit7_constant_remove — Elimina una constante ya definida

### Descripción

function runkit7_constant_remove(string `$constant_name`): bool

### Parámetros

`constant_name`
  El nombre de la constante a eliminar. Puede ser el nombre de una constante global, o `classname::constname` indicando una constante de clase.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- define() - Define una constante
- runkit7_constant_add() - Similar a define(), pero permite definir constantes en las definiciones de clase también
- runkit7_constant_redefine() - Redefine una constante ya definida

# runkit7_function_add

(PECL runkit7 >= Unknown)

runkit7_function_add — Añade una nueva función, similar a create_function()

### Descripción

function runkit7_function_add(
string `$function_name`,
string `$argument_list`,
string `$code`,
bool `$return_by_reference` = `null`,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool
function runkit7_function_add(
string `$function_name`,
Closure `$closure`,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool

### Parámetros

`function_name`
  El nombre de la función a crear
`argument_list`
  La lista de argumentos separados por comas
`code`
  El código que compone la función
`closure`
  Una closure que define la función
`return_by_reference`
  Si la función debe devolver por referencia
`doc_comment`
  El comentario de documentación de la función
`return_type`
  El tipo de retorno de la función
`is_strict`
  Si la función debe comportarse como si fuera declarada en un archivo con `strict_types=1`

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Un ejemplo de runkit7_function_add()

    <?php
    runkit7_function_add('testme','$a,$b','echo "The value of a is $a\n"; echo "The value of b is $b\n";');
    testme(1,2);
    ?>

El ejemplo anterior mostrará:

    The value of a is 1
    The value of b is 2

### Ver también

- create_function() - Crea una función anónima
- runkit7_function_redefine() - Sustituye una definición de función por una nueva implementación
- runkit7_function_copy() - Copia una función hacia un nuevo nombre de función
- runkit7_function_rename() - Cambiar un nombre de función
- runkit7_function_remove() - Elimina una definición de función
- runkit7_method_add() - Añade dinámicamente un nuevo método a una clase dada

# runkit7_function_copy

(PECL runkit7 >= Unknown)

runkit7_function_copy — Copia una función hacia un nuevo nombre de función

### Descripción

function runkit7_function_copy(string `$source_name`, string `$target_name`): bool

### Parámetros

`source_name`
  El nombre de la función existente
`target_name`
  El nombre de la nueva función hacia la cual copiar la definición

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Un ejemplo de runkit7_function_copy()

    <?php
    function original() {
      echo "In a function\n";
    }
    runkit7_function_copy('original','duplicate');
    original();
    duplicate();
    ?>

El ejemplo anterior mostrará:

    In a function
    In a function

### Ver también

- runkit7_function_add() - Añade una nueva función, similar a create_function
- runkit7_function_redefine() - Sustituye una definición de función por una nueva implementación
- runkit7_function_rename() - Cambiar un nombre de función
- runkit7_function_remove() - Elimina una definición de función

# runkit7_function_redefine

(PECL runkit7 >= Unknown)

runkit7_function_redefine — Sustituye una definición de función por una nueva implementación

### Descripción

function runkit7_function_redefine(
string `$function_name`,
string `$argument_list`,
string `$code`,
bool `$return_by_reference` = `null`,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool
function runkit7_function_redefine(
string `$function_name`,
Closure `$closure`,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool

> Nota: Por defecto, solo las funciones definidas por el usuario pueden ser eliminadas, renombradas o modificadas. Para sobreescribir funciones internas, se debe activar la configuración `runkit.internal_override` en el archivo php.ini del sistema entero.

### Parámetros

`function_name`
  El nombre de la función a redefinir
`argument_list`
  La nueva lista de argumentos a aceptar por la función
`code`
  El código de la nueva implementación
`closure`
  Una closure que define la función
`return_by_reference`
  Si la función debe devolver por referencia
`doc_comment`
  El comentario de documentación de la función
`return_type`
  El tipo de retorno de la función
`is_strict`
  Si la función se comporta como si estuviera declarada en un fichero con `strict_types=1`

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Un ejemplo de runkit7_function_redefine()

    <?php
    function testme() {
      echo "Original Testme Implementation\n";
    }
    testme();
    runkit7_function_redefine('testme','','echo "New Testme Implementation\n";');
    testme();
    ?>

El ejemplo anterior mostrará:

    Original Testme Implementation
    New Testme Implementation

### Ver también

- runkit7_function_add() - Añade una nueva función, similar a create_function
- runkit7_function_copy() - Copia una función hacia un nuevo nombre de función
- runkit7_function_rename() - Cambiar un nombre de función
- runkit7_function_remove() - Elimina una definición de función
- runkit7_method_redefine() - Cambiar dinámicamente el código del método dado

# runkit7_function_remove

(PECL runkit7 >= Unknown)

runkit7_function_remove — Elimina una definición de función

### Descripción

function runkit7_function_remove(string `$function_name`): bool

> Nota: Por defecto, solo las funciones definidas por el usuario pueden ser eliminadas, renombradas o modificadas. Para sobreescribir funciones internas, se debe activar la configuración `runkit.internal_override` en el archivo php.ini del sistema entero.

### Parámetros

`function_name`
  El nombre de la función a eliminar

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- runkit7_function_add() - Añade una nueva función, similar a create_function
- runkit7_function_copy() - Copia una función hacia un nuevo nombre de función
- runkit7_function_redefine() - Sustituye una definición de función por una nueva implementación
- runkit7_function_rename() - Cambiar un nombre de función

# runkit7_function_rename

(PECL runkit7 >= Unknown)

runkit7_function_rename — Cambiar un nombre de función

### Descripción

function runkit7_function_rename(string `$source_name`, string `$target_name`): bool

> Nota: Por defecto, solo las funciones definidas por el usuario pueden ser eliminadas, renombradas o modificadas. Para sobreescribir funciones internas, se debe activar la configuración `runkit.internal_override` en el archivo php.ini del sistema entero.

### Parámetros

`source_name`
  El nombre de la función existente
`target_name`
  El nuevo nombre de la función

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- runkit7_function_add() - Añade una nueva función, similar a create_function
- runkit7_function_copy() - Copia una función hacia un nuevo nombre de función
- runkit7_function_redefine() - Sustituye una definición de función por una nueva implementación
- runkit7_function_remove() - Elimina una definición de función

# runkit7_import

(PECL runkit7 >= Unknown)

runkit7_import — Realiza la importación de un fichero PHP importando las definiciones de funciones y clases, sobrescribiéndolas si es necesario

Advertencia

Esta característica ha sido eliminada en PECL runkit7 4.0.0.

### Descripción

function runkit7_import(string `$filename`, int `$flags` = ?): bool

Similar a include. Sin embargo, todo código que se encuentre fuera de una función o clase es simplemente ignorado. Además, en función del valor de `flags`, toda función o clase ya existente en el entorno de ejecución actual puede ser automáticamente sobrescrita por sus nuevas definiciones.

### Parámetros

`filename`
  El nombre del fichero a partir del cual importar las definiciones de funciones y clases
`flags`
  Una operación a nivel de bits de la familia de constantes `RUNKIT7_IMPORT_*`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# runkit7_method_add

(PECL runkit7 >= Unknown)

runkit7_method_add — Añade dinámicamente un nuevo método a una clase dada

### Descripción

function runkit7_method_add(
string `$class_name`,
string `$method_name`,
string `$argument_list`,
string `$code`,
int `$flags` = RUNKIT7_ACC_PUBLIC,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool
function runkit7_method_add(
string `$class_name`,
string `$method_name`,
Closure `$closure`,
int `$flags` = RUNKIT7_ACC_PUBLIC,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool

### Parámetros

`class_name`
  La clase a la cual se añadirá este método
`method_name`
  El nombre del método a añadir
`argument_list`
  La lista de argumentos separados por comas para el nuevo método
`code`
  El código a evaluar cuando `method_name` es llamado
`closure`
  Una closure que define el método.
`flags`
  El tipo de método a crear, puede ser `RUNKIT7_ACC_PUBLIC`, `RUNKIT7_ACC_PROTECTED` o `RUNKIT7_ACC_PRIVATE` opcionalmente combinado mediante una operación bit a bit OU con `RUNKIT7_ACC_STATIC`
`doc_comment`
  El comentario de documentación del método.
`return_type`
  El tipo de retorno del método.
`is_strict`
  Si el método se comporta como si fuera declarado en un fichero con `strict_types=1`

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de runkit7_method_add()

    <?php
    class Example {
        function foo() {
            echo "foo!\n";
        }
    }

    // Crear un objeto Example
    $e = new Example();

    // Añadir un nuevo método público
    runkit7_method_add(
        'Example',
        'add',
        '$num1, $num2',
        'return $num1 + $num2;',
        RUNKIT7_ACC_PUBLIC
    );

    // Sumar 12 + 4
    echo $e->add(12, 4);
    ?>

El ejemplo anterior mostrará:

    16

### Ver también

- runkit7_method_copy() - Copia un método de una clase a otra
- runkit7_method_redefine() - Cambiar dinámicamente el código del método dado
- runkit7_method_remove() - Elimina dinámicamente el método especificado
- runkit7_method_rename() - Cambiar dinámicamente el nombre del método dado
- runkit7_function_add() - Añade una nueva función, similar a create_function

# runkit7_method_copy

(PECL runkit7 >= Unknown)

runkit7_method_copy — Copia un método de una clase a otra

### Descripción

function runkit7_method_copy(
string `$destination_class`,
string `$destination_method_name`,
string `$source_class`,
string `$source_method_name` = ?
): bool

### Parámetros

`destination_class`
  La clase de destino para el método copiado
`destination_method_name`
  El nombre del método de destino
`source_class`
  La clase fuente del método a copiar
`source_method_name`
  El nombre del método a copiar de la clase fuente. Si este argumento es omitido, se asume el valor de `destination_method_name`.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de runkit7_method_copy()

    <?php
    class Foo {
        function example() {
            return "foo!\n";
        }
    }

    class Bar {
        // sin métodos inicialmente
    }

    // copia el example() de la clase Foo a la clase Bar, como baz()
    runkit7_method_copy('Bar', 'baz', 'Foo', 'example');

    // muestra la función copiada
    echo Bar::baz();
    ?>

El ejemplo anterior mostrará:

    foo!

### Ver también

- runkit7_method_add() - Añade dinámicamente un nuevo método a una clase dada
- runkit7_method_redefine() - Cambiar dinámicamente el código del método dado
- runkit7_method_remove() - Elimina dinámicamente el método especificado
- runkit7_method_rename() - Cambiar dinámicamente el nombre del método dado
- runkit7_function_copy() - Copia una función hacia un nuevo nombre de función

# runkit7_method_redefine

(PECL runkit7 >= Unknown)

runkit7_method_redefine — Cambiar dinámicamente el código del método dado

### Descripción

function runkit7_method_redefine(
string `$class_name`,
string `$method_name`,
string `$argument_list`,
string `$code`,
int `$flags` = RUNKIT7_ACC_PUBLIC,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool
function runkit7_method_redefine(
string `$class_name`,
string `$method_name`,
Closure `$closure`,
int `$flags` = RUNKIT7_ACC_PUBLIC,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool

### Parámetros

`class_name`
  La clase en la que redefinir el método
`method_name`
  El nombre del método a redefinir
`argument_list`
  La lista de argumentos separados por comas para el método redefinido
`code`
  El nuevo código a evaluar cuando `method_name` es llamado
`closure`
  Una closure que define el método.
`flags`
  El método redefinido puede ser `RUNKIT7_ACC_PUBLIC`, `RUNKIT7_ACC_PROTECTED` o `RUNKIT7_ACC_PRIVATE` opcionalmente combinado mediante una operación bit a bit OU con `RUNKIT7_ACC_STATIC`
`doc_comment`
  El comentario de documentación del método.
`return_type`
  El tipo de retorno del método.
`is_strict`
  Si el método se comporta como si fuera declarado en un archivo con `strict_types=1`

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de runkit7_method_redefine()

    <?php
    class Example {
        function foo() {
            return "foo!\n";
        }
    }

    // crear un objeto Example
    $e = new Example();

    // muestra Example::foo() (antes de la redefinición)
    echo "Before: " . $e->foo();

    // Redefine el método 'foo'
    runkit7_method_redefine(
        'Example',
        'foo',
        '',
        'return "bar!\n";',
        RUNKIT7_ACC_PUBLIC
    );

    // muestra Example::foo() (después de la redefinición)
    echo "After: " . $e->foo();
    ?>

El ejemplo anterior mostrará:

    Before: foo!
    After: bar!

### Ver también

- runkit7_method_add() - Añade dinámicamente un nuevo método a una clase dada
- runkit7_method_copy() - Copia un método de una clase a otra
- runkit7_method_remove() - Elimina dinámicamente el método especificado
- runkit7_method_rename() - Cambiar dinámicamente el nombre del método dado
- runkit7_function_redefine() - Sustituye una definición de función por una nueva implementación

# runkit7_method_remove

(PECL runkit7 >= Unknown)

runkit7_method_remove — Elimina dinámicamente el método especificado

### Descripción

function runkit7_method_remove(string `$class_name`, string `$method_name`): bool

> Nota: Esta función no puede ser utilizada para manipular el método en curso de utilización (o encadenado).

### Parámetros

`class_name`
  La clase de la cual eliminar el método
`method_name`
  El nombre del método a eliminar

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de runkit7_method_remove()

    <?php
    class Example {
        function foo() {
            return "foo!\n";
        }

        function bar() {
            return "bar!\n";
        }
    }

    // Elimina el método 'foo'
    runkit7_method_remove(
        'Example',
        'foo'
    );

    echo implode(' ', get_class_methods('Example'));

    ?>

El ejemplo anterior mostrará:

    bar

### Ver también

- runkit7_method_add() - Añade dinámicamente un nuevo método a una clase dada
- runkit7_method_copy() - Copia un método de una clase a otra
- runkit7_method_redefine() - Cambiar dinámicamente el código del método dado
- runkit7_method_rename() - Cambiar dinámicamente el nombre del método dado
- runkit7_function_remove() - Elimina una definición de función

# runkit7_method_rename

(PECL runkit7 >= Unknown)

runkit7_method_rename — Cambiar dinámicamente el nombre del método dado

### Descripción

function runkit7_method_rename(string `$class_name`, string `$source_method_name`, string `$target_method_name`): bool

> Nota: Esta función no puede ser utilizada para manipular el método en curso de utilización (o encadenado).

### Parámetros

`class_name`
  La clase en la que renombrar el método
`source_method_name`
  El nombre del método a renombrar
`target_method_name`
  El nuevo nombre a dar al método renombrado

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de runkit7_method_rename()

    <?php
    class Example {
        function foo() {
            return "foo!\n";
        }
    }

    // Renombrar el método 'foo' a 'bar'
    runkit7_method_rename(
        'Example',
        'foo',
        'bar'
    );

    // Mostrar la función renombrada
    echo (new Example)->bar();
    ?>

El ejemplo anterior mostrará:

    foo!

### Ver también

- runkit7_method_add() - Añade dinámicamente un nuevo método a una clase dada
- runkit7_method_copy() - Copia un método de una clase a otra
- runkit7_method_redefine() - Cambiar dinámicamente el código del método dado
- runkit7_method_remove() - Elimina dinámicamente el método especificado
- runkit7_function_rename() - Cambiar un nombre de función

# runkit7_object_id

(PECL runkit7 >= Unknown)

runkit7_object_id — Devuelve el identificador de objeto para un objeto dado

### Descripción

function runkit7_object_id(object `$obj`): int

Esta función es equivalente a spl_object_id().

Esta función devuelve un identificador único para el objeto. El identificador de objeto es único durante la vida del objeto. Una vez destruido el objeto, su identificador puede ser reutilizado para otros objetos. Este comportamiento es similar a spl_object_hash().

### Parámetros

`obj`
  Un objeto cualquiera.

### Valores devueltos

Un identificador entero que es único para cada objeto actualmente existente y siempre es el mismo para cada objeto.

### Notas

> Nota: Cuando un objeto es destruido, su identificador puede ser reutilizado para otros objetos.

### Ver también

- spl_object_id() - Devuelve el gestor de objeto entero para un objeto dado

# runkit7_superglobals

(PECL runkit7 >= Unknown)

runkit7_superglobals — Devuelve un array indexado numéricamente de las superglobales registradas

### Descripción

function runkit7_superglobals(): array

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array indexado numéricamente de las superglobales registradas. Es decir, _GET, _POST, _REQUEST, _COOKIE, _SESSION, _SERVER, _ENV, _FILES

### Ver también

- Ámbito de las variables

# runkit7_zval_inspect

(PECL runkit7 >= Unknown)

runkit7_zval_inspect — Proporciona información sobre el valor pasado con los tipos de datos, los conteos de referencia, etc

### Descripción

function runkit7_zval_inspect(string `$value`): array

### Parámetros

`value`
  El valor para el cual se devuelve la representación

### Valores devueltos

El array devuelto por esta función contiene los siguientes elementos:

- `address`
- `refcount` (opcional)
- `is_ref` (opcional)
- `type`

### Ejemplos

Ejemplo #1 Ejemplo de runkit7_zval_inspect()

    <?php

    $var = new DateTime();
    var_dump(runkit7_zval_inspect($var));

    $var = 1;
    var_dump(runkit7_zval_inspect($var));
    ?>

El ejemplo anterior mostrará:

    array(4) {
      ["address"]=>
      string(14) "0x7f45ab21b1e0"
      ["refcount"]=>
      int(2)
      ["is_ref"]=>
      bool(false)
      ["type"]=>
      int(8)
    }

    array(2) {
      ["address"]=>
      string(14) "0x7f45ab21b1e0"
      ["type"]=>
      int(4)
    }

### Ver también

- References Explained
- » References Explained (by Derick Rethans)

## Tabla de contenidos

- runkit7_constant_add — Similar a define(), pero permite definir constantes en las definiciones de clase también
- runkit7_constant_redefine — Redefine una constante ya definida
- runkit7_constant_remove — Elimina una constante ya definida
- runkit7_function_add — Añade una nueva función, similar a create_function
- runkit7_function_copy — Copia una función hacia un nuevo nombre de función
- runkit7_function_redefine — Sustituye una definición de función por una nueva implementación
- runkit7_function_remove — Elimina una definición de función
- runkit7_function_rename — Cambiar un nombre de función
- runkit7_import — Realiza la importación de un fichero PHP importando las definiciones de funciones y clases, sobrescribiéndolas si es necesario
- runkit7_method_add — Añade dinámicamente un nuevo método a una clase dada
- runkit7_method_copy — Copia un método de una clase a otra
- runkit7_method_redefine — Cambiar dinámicamente el código del método dado
- runkit7_method_remove — Elimina dinámicamente el método especificado
- runkit7_method_rename — Cambiar dinámicamente el nombre del método dado
- runkit7_object_id — Devuelve el identificador de objeto para un objeto dado
- runkit7_superglobals — Devuelve un array indexado numéricamente de las superglobales registradas
- runkit7_zval_inspect — Proporciona información sobre el valor pasado con los tipos de datos, los conteos de referencia, etc

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
- Constantes predefinidas
- Funciones de runkit7
  - runkit7_constant_add — Similar a define(), pero permite definir constantes en las definiciones de clase también
  - runkit7_constant_redefine — Redefine una constante ya definida
  - runkit7_constant_remove — Elimina una constante ya definida
  - runkit7_function_add — Añade una nueva función, similar a create_function
  - runkit7_function_copy — Copia una función hacia un nuevo nombre de función
  - runkit7_function_redefine — Sustituye una definición de función por una nueva implementación
  - runkit7_function_remove — Elimina una definición de función
  - runkit7_function_rename — Cambiar un nombre de función
  - runkit7_import — Realiza la importación de un fichero PHP importando las definiciones de funciones y clases, sobrescribiéndolas si es necesario
  - runkit7_method_add — Añade dinámicamente un nuevo método a una clase dada
  - runkit7_method_copy — Copia un método de una clase a otra
  - runkit7_method_redefine — Cambiar dinámicamente el código del método dado
  - runkit7_method_remove — Elimina dinámicamente el método especificado
  - runkit7_method_rename — Cambiar dinámicamente el nombre del método dado
  - runkit7_object_id — Devuelve el identificador de objeto para un objeto dado
  - runkit7_superglobals — Devuelve un array indexado numéricamente de las superglobales registradas
  - runkit7_zval_inspect — Proporciona información sobre el valor pasado con los tipos de datos, los conteos de referencia, etc

# Operaciones de usuario para Zend

# Introducción

La extensión uopz - User Operations for Zend (N. del T.: operaciones de usuario para Zend) - expone las funcionalidades del motor Zend, normalmente utilizadas durante la compilación y la ejecución, para permitir la modificación de las estructuras internas que representan el código PHP, y para que el código de usuario interactúe con la VM.

uopz soporta las siguientes actividades:

- Sobrescritura de opcodes incluyendo ZEND_EXIT y ZEND_NEW
- Guardado y restauración de funciones y métodos
- Renombrado de funciones y métodos
- Copiado de funciones y métodos
- Eliminación de funciones y métodos
- Re-definición de constantes globales y de clase
- Eliminación de constantes globales y de clase
- Composición y modificación de clases en tiempo de ejecución

> Nota:

> Todas las actividades soportadas son compatibles con opcache.

Precaución

PECL uopz 6.1.1 no es compatible con Xdebug >= 2.9.4. Las versiones posteriores de uopz no son compatibles con Xdebug < 2.9.4.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución

## Requerimientos

A partir de uopz 5.0, PHP 7.0 es necesario. A partir de uopz 5.1, PHP 7.1+ es necesario.

## Instalación

Las versiones de uopz están alojadas por PECL y el código fuente por » github; la forma más sencilla de instalarlo es a través de la instalación via PECL : » https://pecl.php.net/package/uopz.

Los usuarios de Windows pueden descargar los binarios desde el sitio web de » PECL.

A partir de uopz 5.0.0, la extensión debe ser cargada como una extensión. Anterior a esta versión, debe ser cargada como una zend_extension.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

uopz Opciones de configuración
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
uopz.disable | "0" | `INI_SYSTEM` | Disponible a partir de uopz 5.0.2
uopz.exit | "0" | `INI_SYSTEM` | Disponible a partir de uopz 6.0.1
uopz.overloads | "1" | `INI_SYSTEM` | Disponible a partir de uopz 2.0.2. Eliminado a partir de uopz 5.0.0.

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`uopz.disable` bool

  Si está activado, uopz no debería tener ningún efecto sobre el motor.

`uopz.exit` bool

  Permitir o no la ejecución de los códigos de operación (opcodes) de salida. Este parámetro puede ser sobreescrito durante la ejecución llamando a uopz_allow_exit().

`uopz.overloads` bool

  Activa la posibilidad de utilizar uopz_overload().

> Nota: Al ejecutar con OPcache activado, puede ser necesario desactivar todas las optimizaciones OPcache (`opcache.optimization_level=0`).

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

Los siguientes opcodes son definidos como constantes por uopz antes de 5.0.0:

`ZEND_EXIT` (int)
  Invoca exit() y die(); no recibe ningún argumento. Devuelve `true` para salir, `false` para continuar
`ZEND_NEW` (int)
  Invocado por la construcción de un objeto, recibe el objeto de la clase creada como único argumento
`ZEND_THROW` (int)
  Invocado por la estructura throw, recibe la excepción de la clase emitida como único argumento
`ZEND_FETCH_CLASS` (int)
  Invocado durante una composición, recibe la clase, el nombre de la clase recuperada como único argumento
`ZEND_ADD_TRAIT` (int)
  Invocado durante una composición, recibe la clase en la cual el trait será añadido, como primer argumento, y el nombre del trait como segundo argumento
`ZEND_ADD_INTERFACE` (int)
  Invocado durante una composición, recibe la clase en la cual la interfaz será añadida como primer argumento, y el nombre de la interfaz como segundo argumento
`ZEND_INSTANCEOF` (int)
  Invocado por el operador instanceof, recibe el objeto a verificar como primer argumento, y el nombre de la clase a la que pertenece el objeto como segundo argumento

Las siguientes constantes controlan el comportamiento del VM después de que un gestor usuario sea llamado; sea extremadamente cuidadoso! Estas constantes son eliminadas a partir de uopz 5.0.0.

`ZEND_USER_OPCODE_CONTINUE` (int)
  Avance de un opcode, y continúe
`ZEND_USER_OPCODE_ENTER` (int)
  Entrar en un nuevo op_array sin recursión
`ZEND_USER_OPCODE_LEAVE` (int)
  Retorna el op_array llamado en el mismo ejecutor
`ZEND_USER_OPCODE_DISPATCH` (int)
  Despacha el gestor opcode original
`ZEND_USER_OPCODE_DISPATCH_TO` (int)
  Despacha a un gestor específico (o combinado con la constante opcode de ZEND)
`ZEND_USER_OPCODE_RETURN` (int)
  Sale del ejecutor (retorna a la función)

Los siguientes modificadores están registrados como constantes por uopz

`ZEND_ACC_PUBLIC` (int)
  Marca una función como pública, el comportamiento por omisión
`ZEND_ACC_PROTECTED` (int)
  Marca una función como protegida
`ZEND_ACC_PRIVATE` (int)
  Marca una función como privada
`ZEND_ACC_STATIC` (int)
  Marca una función como estática
`ZEND_ACC_FINAL` (int)
  Marca una función como final
`ZEND_ACC_ABSTRACT` (int)
  Marca una función como abstracta
`ZEND_ACC_CLASS` (int)
  Registro ficticio para consistencia, el tipo de entrada de clase por omisión. Eliminada a partir de uopz 5.0.0.
`ZEND_ACC_INTERFACE` (int)
  Marca la clase como una interfaz. Eliminada a partir de uopz 5.0.0.
`ZEND_ACC_TRAIT` (int)
  Marca la clase como un trait. Eliminada a partir de uopz 5.0.0.
`ZEND_ACC_FETCH` (int)
  Utilizado para recuperar solo los flags. Eliminada a partir de uopz 5.0.0.

# Funciones Uopz

# uopz_add_function

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_add_function — Añade una función o método inexistente

### Descripción

function uopz_add_function(string `$function`, Closure `$handler`, int `&$flags` = ZEND_ACC_PUBLIC): bool
function uopz_add_function(
string `$class`,
string `$function`,
Closure `$handler`,
int `&$flags` = ZEND_ACC_PUBLIC,
int `&$all` = `true`
): bool

Añade una función o método inexistente.

### Parámetros

`class`

  El nombre de la clase.

`function`

  El nombre de la función o método.

`handler`

  La Closure que define la nueva función o método.

`flags`

  Los flags a definir para la nueva función o método.

`all`

  Si todas las clases que heredan de `class` serán también afectadas.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

uopz_add_function() lanza una RuntimeException si la función o método a añadir ya existe.

### Ejemplos

Ejemplo #1 Uso básico de uopz_add_function()

    <?php
    uopz_add_function('foo', function () {echo 'bar';});
    foo();
    ?>

El ejemplo anterior mostrará:

    bar

### Ver también

- uopz_del_function() - Elimina una función o método previamente añadido
- uopz_set_return() - Proporciona un valor de retorno para una función existente

# uopz_allow_exit

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_allow_exit — Permite controlar el opcode exit desactivado

### Descripción

function uopz_allow_exit(bool `$allow`): void

Por omisión, uopz desactiva el opcode exit, por lo que las llamadas a exit() son prácticamente ignoradas. uopz_allow_exit() permite controlar este comportamiento.

### Parámetros

`allow`

  Permitir o no la ejecución de los opcodes exit.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo de uopz_allow_exit()

    <?php
    exit(1);
    echo 1;
    uopz_allow_exit(true);
    exit(2);
    echo 2;
    ?>

El ejemplo anterior mostrará:

    1

### Notas

Precaución

OPcache optimiza el código muerto después de una salida incondicional.

### Ver también

- uopz_get_exit_status() - Devuelve el último estado de salida definido

# uopz_backup

(PECL uopz 1 >= 1.0.3, PECL uopz 2)

uopz_backup — Guarda una función

Advertencia

Esta función ha sido ELIMINADA en PECL uopz 5.0.0.

### Descripción

function uopz_backup(string `$function`): void
function uopz_backup(string `$class`, string `$function`): void

Guarda una función en tiempo de ejecución.

### Parámetros

`class`

  El nombre de la clase que contiene la función a guardar

`function`

  El nombre de la función

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo con uopz_backup()

    <?php
    uopz_backup("fgets");
    uopz_function("fgets", function(){
        return true;
    });
    var_dump(fgets());
    ?>

El ejemplo anterior mostrará:

    bool(true)

# uopz_compose

(PECL uopz 1, PECL uopz 2)

uopz_compose — Componer una clase

Advertencia

Esta función ha sido ELIMINADA en PECL uopz 5.0.0.

### Descripción

function uopz_compose(
string `$name`,
array `$classes`,
array `$methods` = ?,
array `$properties` = ?,
int `$flags` = ?
): void

Crea una nueva clase con el nombre especificado, que implementa, extiende o utiliza todas las clases proporcionadas.

### Parámetros

`name`

  Un nombre de clase válido

`classes`

  Un array de clases, interfaces o nombres de trait

`methods`

  Un array asociativo de métodos; los valores son o bien closures, o bien [modificadores => closure]

`properties`

  Un array asociativo de propiedades, con las claves como nombres, y los valores como modificadores

`flags`

  Tipo de entrada; por omisión, ZEND_ACC_CLASS

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo con uopz_compose()

    <?php
    class myClass {}
    trait myTrait {}
    interface myInterface {}

    uopz_compose(
        Composed::class, [
            myClass::class,
            myTrait::class,
            myInterface::class
        ], [
        "__construct" => function() {
            /* ... */
        }
    ]);

    var_dump(
     class_uses(Composed::class),
     class_parents(Composed::class),
     class_implements(Composed::class));
    ?>

El ejemplo anterior mostrará:

    array(1) {
      ["myTrait"]=>
      string(7) "myTrait"
    }
    array(1) {
      ["myClass"]=>
      string(7) "myClass"
    }
    array(1) {
      ["myInterface"]=>
      string(11) "myInterface"
    }

# uopz_copy

(PECL uopz 1 >= 1.0.4, PECL uopz 2)

uopz_copy — Copia una función

Advertencia

Esta función ha sido ELIMINADA en PECL uopz 5.0.0.

### Descripción

function uopz_copy(string `$function`): Closure
function uopz_copy(string `$class`, string `$function`): Closure

Copia una función a partir de su nombre.

### Parámetros

`class`

  El nombre de la clase que contiene la función a copiar

`function`

  El nombre de la función

### Valores devueltos

Una closure para la función especificada.

### Ejemplos

Ejemplo #1 Ejemplo con uopz_copy()

    <?php
    $strtotime = uopz_copy('strtotime');

    uopz_function("strtotime", function($arg1, $arg2) use($strtotime) {
        /* se puede llamar a la función strtotime original desde aquí */
        var_dump($arg1);
    });

    var_dump(strtotime('dummy'));
    ?>

El ejemplo anterior mostrará:

    string(5) "dummy"

# uopz_del_function

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_del_function — Elimina una función o método previamente añadido

### Descripción

function uopz_del_function(string `$function`): bool
function uopz_del_function(string `$class`, string `$function`, int `&$all` = `true`): bool

Elimina una función o método previamente añadido.

### Parámetros

`class`

  El nombre de la clase.

`function`

  El nombre de la función o método.

`all`

  Si todas las clases que heredan de `class` serán también afectadas.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

uopz_del_function() lanza una RuntimeException si la función o método a eliminar no ha sido añadido por uopz_add_function().

### Ejemplos

Ejemplo #1 Uso básico de uopz_del_function()

    <?php
    uopz_add_function('foo', function () {echo 'bar';});
    var_dump(function_exists('foo'));
    uopz_del_function('foo');
    var_dump(function_exists('foo'));
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(false)

### Ver también

- uopz_add_function() - Añade una función o método inexistente
- uopz_unset_return() - Suprime un valor de retorno previamente fijado para una función

# uopz_delete

(PECL uopz 1, PECL uopz 2)

uopz_delete — Elimina una función

Advertencia

Esta función ha sido ELIMINADA en PECL uopz 5.0.0.

### Descripción

function uopz_delete(string `$function`): void
function uopz_delete(string `$class`, string `$function`): void

Elimina una función o método.

### Parámetros

`class`

  El nombre de la clase.

`function`

  El nombre de la función o método.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo con uopz_delete()

    <?php
    uopz_delete("strlen");

    echo strlen("Hello World");
    ?>

Resultado del ejemplo anterior es similar a:

    PHP Fatal error: Call to undefined function strlen() in /path/to/script.php on line 4

Ejemplo #2 Ejemplo con uopz_delete() y una clase

    <?php
    class My {
        public static function strlen($arg) {
            return strlen($arg);
        }
    }

    uopz_delete(My::class, "strlen");

    echo My::strlen("Hello World");
    ?>

Resultado del ejemplo anterior es similar a:

    PHP Fatal error: Call to undefined method My::strlen() in /path/to/script.php on line 10

# uopz_extend

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7 < 7.1.0)

uopz_extend — Extiende una clase en tiempo de ejecución

### Descripción

function uopz_extend(string `$class`, string `$parent`): bool

Extiende la clase `class` utilizando la clase `parent`.

### Parámetros

`class`

  El nombre de la clase a extender

`parent`

  El nombre de la clase padre

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

A partir de PHP 7.4.0, uopz_extend() emite una RuntimeException, si OPcache está activado, y la entrada de clase de `class` o `parent` (si en un trait) es inmutable.

### Ejemplos

Ejemplo #1 Ejemplo con uopz_extend()

    <?php
    class A {}
    class B {}

    uopz_extend(A::class, B::class);

    var_dump(class_parents(A::class));
    ?>

El ejemplo anterior mostrará:

    array(1) {
      ["B"]=>
      string(1) "B"
    }

# uopz_flags

(PECL uopz 2 >= 2.0.2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_flags — Recupera o define los flags de una función o clase

### Descripción

function uopz_flags(string `$function`, int `$flags` = PHP_INT_MAX): int
function uopz_flags(string `$class`, string `$function`, int `$flags` = PHP_INT_MAX): int

Recupera o define los flags de una clase o entrada de función en tiempo de ejecución.

### Parámetros

`class`

  El nombre de la clase

`function`

  El nombre de la función. Si `class` es proporcionado y una string vacía es pasada como `function`, uopz_flags() recupera o define los flags de la propia clase.

`flags`

  Un conjunto válido de flags ZEND_ACC_. Si se omite, uopz_flags() actúa como recuperador.

### Valores devueltos

Si se definen flags, devuelve los flags antiguos, de lo contrario, devuelve los flags actuales

### Errores/Excepciones

A partir de PHP 7.4.0, si el parámetro `flags` es proporcionado uopz_flags() emite una RuntimeException, si OPcache está activado, y la entrada de clase de `class` o la entrada de función `function` es inmutable.

### Historial de cambios

Versión | Descripción
--- | ---
PECL uopz 5.0.0 | El parámetro `flags` es ahora opcional. Anteriormente, `ZEND_ACC_FETCH` debía ser pasado para usar uopz_flags() como recuperador.

### Ejemplos

Ejemplo #1 Ejemplo con uopz_flags()

    <?php
    class Test {
        public function method() {
            return __CLASS__;
        }
    }

    $flags = uopz_flags("Test", "method");

    var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_PRIVATE));
    var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_STATIC));

    var_dump(uopz_flags("Test", "method", $flags|ZEND_ACC_STATIC|ZEND_ACC_PRIVATE));

    var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_PRIVATE));
    var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_STATIC));
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(false)
    int(1234567890)
    bool(true)
    bool(true)

Ejemplo #2 Transformar una clase final en no final

    <?php
    final class MyClass
    {
    }

    $flags = uopz_flags(MyClass::class, '');
    uopz_flags(MyClass::class, '', $flags & ~ZEND_ACC_FINAL);
    var_dump((new ReflectionClass(MyClass::class))->isFinal());
    ?>

El ejemplo anterior mostrará:

    bool(false)

# uopz_function

(PECL uopz 1, PECL uopz 2)

uopz_function — Crea una función en tiempo de ejecución

Advertencia

Esta función ha sido ELIMINADA en PECL uopz 5.0.0.

### Descripción

function uopz_function(string `$function`, Closure `$handler`, int `$modifiers` = ?): void
function uopz_function(
string `$class`,
string `$function`,
Closure `$handler`,
int `$modifiers` = ?
): void

Crea una función en tiempo de ejecución.

### Parámetros

`class`

  El nombre de la clase que debe recibir la nueva función

`function`

  El nombre de la función

`handler`

  La closure de la función

`modifiers`

  Los modificadores de la función; por omisión, copiados o ZEND_ACC_PUBLIC

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo con uopz_function()

    <?php
    uopz_function("my_strlen", function($arg) {
        return strlen($arg);
    });
    echo my_strlen("Hello World");
    ?>

El ejemplo anterior mostrará:

    11

Ejemplo #2 Ejemplo con uopz_function() y una clase

    <?php
    class My {}

    uopz_function(My::class, "strlen", function($arg) {
        return strlen($arg);
    }, ZEND_ACC_STATIC);

    echo My::strlen("Hello World");
    ?>

El ejemplo anterior mostrará:

    11

# uopz_get_exit_status

(PECL uopz 5, PECL uopz , PECL uopz 7)

uopz_get_exit_status — Devuelve el último estado de salida definido

### Descripción

function uopz_get_exit_status(): mixed

Devuelve el último estado de salida definido, es decir, el valor pasado a exit().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función devuelve el último estado de salida, o `null` si exit() no ha sido llamada.

### Ejemplos

Ejemplo #1 Ejemplo de uopz_get_exit_status()

    <?php
    exit(123);
    echo uopz_get_exit_status();?>

El ejemplo anterior mostrará:

    123

### Notas

Precaución

OPcache optimiza el código muerto después de una salida incondicional.

### Ver también

- uopz_allow_exit() - Permite controlar el opcode exit desactivado

# uopz_get_hook

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_hook — Devuelve el hook previamente definido en una función o método

### Descripción

function uopz_get_hook(string `$function`): Closure
function uopz_get_hook(string `$class`, string `$function`): Closure

Devuelve el hook previamente definido en una función o método.

### Parámetros

`class`

  El nombre de la clase.

`function`

  El nombre de la función o método.

### Valores devueltos

Devuelve el hook previamente definido en una función o método, o `null` si ningún hook ha sido definido.

### Ejemplos

Ejemplo #1 Uso básico de uopz_get_hook()

    <?php
    function foo() {
        echo 'foo';
    }
    uopz_set_hook('foo', function () {echo 'bar';});
    var_dump(uopz_get_hook('foo'));
    ?>

Resultado del ejemplo anterior es similar a:

    object(Closure)#2 (0) {
    }

### Ver también

- uopz_set_hook() - Define el hook que se ejecutará al entrar en una función o un método
- uopz_unset_hook() - Suprime el hook previamente fijado sobre una función o un método

# uopz_get_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_mock — Devuelve la simulación actual de una clase

### Descripción

function uopz_get_mock(string `$class`): mixed

Devuelve la simulación actual de `class`.

### Parámetros

`class`

  El nombre de la clase simulada.

### Valores devueltos

O bien una cadena que contiene el nombre de la simulación, o bien un objeto, o bien `null` si ninguna simulación ha sido definida.

### Ejemplos

Ejemplo #1 Ejemplo de uopz_get_mock()

    <?php
    class A {
        public static function who() {
            echo "A";
        }
    }

    class mockA {
        public static function who() {
            echo "mockA";
        }
    }

    uopz_set_mock(A::class, mockA::class);
    echo uopz_get_mock(A::class);
    ?>

El ejemplo anterior mostrará:

    mockA

### Ver también

- uopz_set_mock() - Utiliza una simulación en lugar de una clase para nuevos objetos
- uopz_unset_mock() - Suprime la simulación previamente fijada

# uopz_get_property

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_property — Devuelve el valor de una propiedad de clase o instancia

### Descripción

function uopz_get_property(string `$class`, string `$property`): mixed
function uopz_get_property(object `$instance`, string `$property`): mixed

Devuelve el valor de una propiedad de clase estática, si `class` es proporcionado, o el valor de una propiedad de instancia, si `instance` es proporcionado.

### Parámetros

`class`

  El nombre de la clase.

`instance`

  La instancia del objeto.

`property`

  El nombre de la propiedad.

### Valores devueltos

Devuelve el valor de la propiedad de clase o instancia, o `null` si la propiedad no está definida.

### Ejemplos

Ejemplo #1 Uso básico de uopz_get_property()

    <?php
    class Foo {
        private static $staticBar = 10;
        private $bar = 100;
    }
    $foo = new Foo;
    var_dump(uopz_get_property('Foo', 'staticBar'));
    var_dump(uopz_get_property($foo, 'bar'));
    ?>

Resultado del ejemplo anterior es similar a:

    int(10)
    int(100)

### Ver también

- uopz_set_property() - Establece el valor de una propiedad de clase existente o de instancia

# uopz_get_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_return — Devuelve un valor de retorno previamente definido para una función

### Descripción

function uopz_get_return(string `$function`): mixed
function uopz_get_return(string `$class`, string `$function`): mixed

Devuelve el valor de retorno de la `function` previamente definido por uopz_set_return().

### Parámetros

`class`

  El nombre de la clase que contiene la función

`function`

  El nombre de la función

### Valores devueltos

El valor de retorno o la closure previamente definida.

### Ejemplos

Ejemplo #1 Ejemplo de uopz_get_return()

    <?php
    uopz_set_return("strlen", 42);
    echo uopz_get_return("strlen");
    ?>

El ejemplo anterior mostrará:

    42

# uopz_get_static

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_static — Devuelve las variables estáticas de una función o método

### Descripción

function uopz_get_static(string `$class`, string `$function`): array
function uopz_get_static(string `$function`): array

Devuelve las variables estáticas de una función o método.

### Parámetros

`class`

  El nombre de la clase.

`function`

  El nombre de la función o método.

### Valores devueltos

Devuelve un array asociativo de nombres de variables mapeados a sus valores actuales en caso de éxito, o `null` si la función o método no existe.

Desde PHP 8.3.0, los inicializadores estáticos se calculan ya sea durante la compilación, o si no es posible, solo cuando la función o método se ejecuta por primera vez, en cuyo caso el valor de la variable estática se reporta como `null` antes de la primera invocación.

### Ejemplos

Ejemplo #1 Uso básico de uopz_get_static()

    <?php
    function foo() {
        static $bar = 'baz';
    }
    var_dump(uopz_get_static('foo'));
    ?>

El ejemplo anterior mostrará:

    array(1) {
      ["bar"]=>
      string(3) "baz"
    }

### Ver también

- ReflectionFunctionAbstract::getStaticVariables() - Obtiene las variables estáticas
- uopz_set_static() - Fija las variables estáticas en el ámbito de una función o de un método

# uopz_implement

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7 < 7.1.0)

uopz_implement — Implementa una interfaz en tiempo de ejecución

### Descripción

function uopz_implement(string `$class`, string `$interface`): bool

Implementa la `interface` en la `class`.

### Parámetros

`class`

  El nombre de la clase.

`interface`

  El nombre de la interfaz.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

A partir de PHP 7.4.0, uopz_implement() emite una RuntimeException, si OPcache está activado, y la entrada de clase de `class` es inmutable.

### Ejemplos

Ejemplo #1 Ejemplo con uopz_implement()

    <?php
    interface myInterface {}

    class myClass {}

    uopz_implement(myClass::class, myInterface::class);

    var_dump(class_implements(myClass::class));
    ?>

El ejemplo anterior mostrará:

    array(1) {
      ["myInterface"]=>
      string(11) "myInterface"
    }

# uopz_overload

(PECL uopz 1, PECL uopz 2)

uopz_overload — Sobrecarga un opcode de la VM

Advertencia

Esta función ha sido ELIMINADA en PECL uopz 5.0.0.

### Descripción

function uopz_overload(int `$opcode`, Callable `$callable`): void

Sobrecarga el `opcode` especificado con una función definida por el usuario.

### Parámetros

`opcode`

  Un opcode válido; consulte las constantes para más detalles sobre los códigos admitidos.

`callable`

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo con uopz_overload()

    <?php
    uopz_overload(ZEND_EXIT, function(){});

    exit();
    echo "Hello World";
    ?>

El ejemplo anterior mostrará:

    Hello World

# uopz_redefine

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_redefine — Redefinir una constante

### Descripción

function uopz_redefine(string `$constant`, mixed `$value`): bool
function uopz_redefine(string `$class`, string `$constant`, mixed `$value`): bool

Redefine la constante `constant` proporcionada, a `value`.

### Parámetros

`class`

  El nombre de la clase que contiene la constante

`constant`

  El nombre de la constante

`value`

  El nuevo valor de la constante; debe ser un tipo válido para una constante

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con uopz_redefine()

    <?php
    define("MY", 100);

    uopz_redefine("MY", 1000);

    echo MY;
    ?>

El ejemplo anterior mostrará:

    1000

# uopz_rename

(PECL uopz 1, PECL uopz 2)

uopz_rename — Cambia el nombre de una función en tiempo de ejecución

Advertencia

Esta función ha sido ELIMINADA en PECL uopz 5.0.0.

### Descripción

function uopz_rename(string `$function`, string `$rename`): void
function uopz_rename(string `$class`, string `$function`, string `$rename`): void

Cambia el nombre de la función `function` a `rename`.

> Nota:

> Si ambas funciones existen, sus nombres serán intercambiados.

### Parámetros

`class`

  El nombre de la clase que contiene la función

`function`

  El nombre de una función existente

`rename`

  El nuevo nombre de la función

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo con uopz_rename()

    <?php
    uopz_rename("strlen", "original_strlen");

    echo original_strlen("Hello World");
    ?>

El ejemplo anterior mostrará:

    11

Ejemplo #2 Ejemplo con uopz_rename() y una clase

    <?php
    class My {
        public function strlen($arg) {
            return strlen($arg);
        }
    }

    uopz_rename(My::class, "strlen", "original_strlen");

    echo My::original_strlen("Hello World");
    ?>

El ejemplo anterior mostrará:

    11

# uopz_restore

(PECL uopz 1 >= 1.0.3, PECL uopz 2)

uopz_restore — Restaura una función guardada

Advertencia

Esta función ha sido ELIMINADA en PECL uopz 5.0.0.

### Descripción

function uopz_restore(string `$function`): void
function uopz_restore(string `$class`, string `$function`): void

Restaura una función guardada.

### Parámetros

`class`

  El nombre de la clase que contiene la función a restaurar

`function`

  El nombre de la función

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo con uopz_restore()

    <?php
    uopz_backup("fgets");
    uopz_function("fgets", function(){
        return true;
    });
    var_dump(fgets());
    uopz_restore('fgets');
    fgets();
    ?>

Resultado del ejemplo anterior es similar a:

    Advertencia: fgets() espera al menos 1 parámetro, 0 dado en /path/to/script.php en la línea 8

# uopz_set_hook

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_hook — Define el hook que se ejecutará al entrar en una función o un método

### Descripción

function uopz_set_hook(string `$function`, Closure `$hook`): bool
function uopz_set_hook(string `$class`, string `$function`, Closure `$hook`): bool

Define un hook que se ejecutará al entrar en una función o un método.

### Parámetros

`class`

  El nombre de la clase.

`function`

  El nombre de la función o del método.

`hook`

  Una función anónima que se ejecutará al entrar en la función o el método.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Uso básico de uopz_set_hook()

    <?php
    function foo() {
        echo 'foo';
    }
    uopz_set_hook('foo', function () {echo 'bar';});
    foo();
    ?>

El ejemplo anterior mostrará:

    barfoo

### Ver también

- uopz_get_hook() - Devuelve el hook previamente definido en una función o método
- uopz_unset_hook() - Suprime el hook previamente fijado sobre una función o un método

# uopz_set_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_mock — Utiliza una simulación en lugar de una clase para nuevos objetos

### Descripción

function uopz_set_mock(string `$class`, mixed `$mock`): void

Si `mock` es una cadena que contiene el nombre de una clase, se instanciará en lugar de `class`. `mock` también puede ser un objeto.

> Nota:

> Solo el acceso dinámico a las propiedades y métodos usará el objeto `mock`. El acceso estático sigue utilizando la `class` original. Consulte el ejemplo a continuación.

### Parámetros

`class`

  El nombre de la clase que se va a simular.

`mock`

  La simulación a usar en forma de cadena que contiene el nombre de la clase a usar o un objeto. Si se pasa una cadena, debe ser el nombre totalmente calificado de la clase. Se recomienda usar la constante mágica `::class` en este caso.

### Valores devueltos

No se retorna ningún valor.

### Historial de cambios

Versión | Descripción
--- | ---
PECL uopz 6.0.0 | La simulación de miembros estáticos ya no es compatible con esta función. uopz_redefine() y uopz_set_return(), o Componere pueden ser utilizados en su lugar.

### Ejemplos

Ejemplo #1 Ejemplo de uopz_set_mock()

    <?php
    class A {
        public function who() {
            echo "A";
        }
    }

    class mockA {
        public function who() {
            echo "mockA";
        }
    }

    uopz_set_mock(A::class, mockA::class);
    (new A)->who();
    ?>

El ejemplo anterior mostrará:

    mockA

Ejemplo #2 Ejemplo de uopz_set_mock()

    <?php
    class A {
        public function who() {
            echo "A";
        }
    }

    uopz_set_mock(A::class, new class {
                                public function who() {
                                    echo "mockA";
                                }
                            });
    (new A)->who();
    ?>

El ejemplo anterior mostrará:

    mockA

Ejemplo #3 uopz_set_mock() y miembros estáticos

Desde uopz 6.0.0, la simulación de miembros estáticos ya no es compatible.

    <?php
    class A {
        const CON = 'A';
        public static function who() {
            echo "A";
        }
    }

    uopz_set_mock(A::class, new class {
                                const CON = 'mockA';
                                public static function who() {
                                    echo "mockA";
                                }
                            });
    echo A::CON, PHP_EOL;
    A::who();
    ?>

El ejemplo anterior mostrará:

    A
    A

El ejemplo anterior muestra con uopz 5:

    mockA
    mockA

### Ver también

- uopz_get_mock() - Devuelve la simulación actual de una clase
- uopz_unset_mock() - Suprime la simulación previamente fijada

# uopz_set_property

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_property — Establece el valor de una propiedad de clase existente o de instancia

### Descripción

function uopz_set_property(string `$class`, string `$property`, mixed `$value`): void
function uopz_set_property(object `$instance`, string `$property`, mixed `$value`): void

Establece el valor de una propiedad de clase estática existente, si se proporciona `class`, o el valor de una propiedad de instancia (sin importar si la propiedad de instancia ya existe), si se proporciona `instance`.

### Parámetros

`class`

  El nombre de la clase.

`instance`

  La instancia del objeto.

`property`

  El nombre de la propiedad.

`value`

  El valor a asignar a la propiedad.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Uso básico de uopz_set_property()

    <?php
    class Foo {
       private static $staticBar;
       private $bar;
       public static function testStaticBar() {
          return self::$staticBar;
       }
       public function testBar() {
          return $this->bar;
       }
    }
    $foo = new Foo;
    uopz_set_property('Foo', 'staticBar', 10);
    uopz_set_property($foo, 'bar', 100);
    var_dump(Foo::testStaticBar());
    var_dump($foo->testBar());
    ?>

El ejemplo anterior mostrará:

    int(10)

### Ver también

- uopz_get_property() - Devuelve el valor de una propiedad de clase o instancia

# uopz_set_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_return — Proporciona un valor de retorno para una función existente

### Descripción

function uopz_set_return(string `$function`, mixed `$value`, bool `$execute` = `false`): bool
function uopz_set_return(
string `$class`,
string `$function`,
mixed `$value`,
bool `$execute` = `false`
): bool

Establece el valor de retorno de la `function` a `value`. Si `value` es una función anónima y `execute` está establecido, la función anónima se ejecutará en lugar de la función original. Es posible llamar a la función original desde la función anónima.

> Nota:

> Esta función reemplaza a uopz_rename().

### Parámetros

`class`

  El nombre de la clase que contiene la función

`function`

  El nombre de una función existente

`value`

  El valor que la función debe devolver. Si se proporciona una función anónima y el flag de ejecución está establecido, la función anónima se ejecutará en lugar de la función original.

`execute`

  Si es verdadero, y se ha proporcionado una función anónima como valor, la función anónima se ejecutará en lugar de la función original.

### Valores devueltos

Devuelve `true` en caso de éxito, de lo contrario `false`.

### Ejemplos

Ejemplo #1 Ejemplo de uopz_set_return()

    <?php
    uopz_set_return("strlen", 42);
    echo strlen("Banana");
    ?>

El ejemplo anterior mostrará:

    42

Ejemplo #2 Ejemplo de uopz_set_return()

    <?php
    uopz_set_return("strlen", function($str) { return strlen($str) * 2; }, true );
    echo strlen("Banana");
    ?>

El ejemplo anterior mostrará:

    12

Ejemplo #3 Ejemplo de uopz_set_return() con una clase

    <?php
    class My {
        public static function strlen($arg) {
            return strlen($arg);
        }
    }
    uopz_set_return(My::class, "strlen", function($str) { return strlen($str) * 2; }, true );
    echo My::strlen("Banana");
    ?>

El ejemplo anterior mostrará:

    12

# uopz_set_static

(PECL uopz 5, PECL uopz , PECL uopz 7)

uopz_set_static — Fija las variables estáticas en el ámbito de una función o de un método

### Descripción

function uopz_set_static(string `$function`, array `$static`): void
function uopz_set_static(string `$class`, string `$function`, array `$static`): void

Fija las variables estáticas en el ámbito de una función o de un método.

### Parámetros

`class`

  El nombre de la clase.

`function`

  El nombre de la función o del método.

`static`

  El array asociativo de nombres de variables mapeados a sus valores.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo de uso de uopz_set_static()

    <?php
    function foo() {
        static $bar = 'baz';
        var_dump($bar);
    }
    uopz_set_static('foo', ['bar' => 'qux']);
    foo();
    ?>

El ejemplo anterior mostrará:

    string(3) "qux"

### Ver también

- uopz_get_static() - Devuelve las variables estáticas de una función o método

# uopz_undefine

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_undefine — Elimina una constante

### Descripción

function uopz_undefine(string `$constant`): bool
function uopz_undefine(string `$class`, string `$constant`): bool

Elimina una constante en tiempo de ejecución.

### Parámetros

`class`

  El nombre de la clase que contiene la `constant`

`constant`

  El nombre de una constante existente

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con uopz_undefine()

    <?php
    define("MY", true);

    uopz_undefine("MY");

    var_dump(defined("MY"));
    ?>

El ejemplo anterior mostrará:

    bool(false)

# uopz_unset_hook

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_hook — Suprime el hook previamente fijado sobre una función o un método

### Descripción

function uopz_unset_hook(string `$function`): bool
function uopz_unset_hook(string `$class`, string `$function`): bool

Suprime el hook previamente fijado sobre una función o un método.

### Parámetros

`class`

  El nombre de la clase.

`function`

  El nombre de la función o del método.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Uso básico de uopz_unset_hook()

    <?php
    function foo() {
        echo 'foo';
    }
    uopz_set_hook('foo', function () {echo 'bar';});
    foo();
    echo PHP_EOL;
    uopz_unset_hook('foo');
    foo();
    ?>

El ejemplo anterior mostrará:

    barfoo
    foo

### Ver también

- uopz_set_hook() - Define el hook que se ejecutará al entrar en una función o un método
- uopz_get_hook() - Devuelve el hook previamente definido en una función o método

# uopz_unset_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_mock — Suprime la simulación previamente fijada

### Descripción

function uopz_unset_mock(string `$class`): void

Suprime la simulación previamente fijada para `class`.

### Parámetros

`class`

  El nombre de la clase simulada.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

Una RuntimeException es lanzada si ninguna simulación ha sido previamente fijada para `class`.

### Ejemplos

Ejemplo #1 Ejemplo de uopz_unset_mock()

    <?php
    class A {
        public static function who() {
            echo "A";
        }
    }

    class mockA {
        public static function who() {
            echo "mockA";
        }
    }

    uopz_set_mock(A::class, mockA::class);
    uopz_unset_mock(A::class);
    A::who();
    ?>

El ejemplo anterior mostrará:

    A

### Ver también

- uopz_set_mock() - Utiliza una simulación en lugar de una clase para nuevos objetos
- uopz_get_mock() - Devuelve la simulación actual de una clase

# uopz_unset_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_return — Suprime un valor de retorno previamente fijado para una función

### Descripción

function uopz_unset_return(string `$function`): bool
function uopz_unset_return(string `$class`, string `$function`): bool

Suprime el valor de retorno de la `function` previamente fijado por uopz_set_return().

### Parámetros

`class`

  El nombre de la clase que contiene la función

`function`

  El nombre de la función

### Valores devueltos

`true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo de uopz_unset_return()

    <?php
    uopz_set_return("strlen", 42);
    $len = strlen("Banana");
    uopz_unset_return("strlen");
    echo $len + strlen("Banana");
    ?>

El ejemplo anterior mostrará:

    48

## Tabla de contenidos

- uopz_add_function — Añade una función o método inexistente
- uopz_allow_exit — Permite controlar el opcode exit desactivado
- uopz_backup — Guarda una función
- uopz_compose — Componer una clase
- uopz_copy — Copia una función
- uopz_del_function — Elimina una función o método previamente añadido
- uopz_delete — Elimina una función
- uopz_extend — Extiende una clase en tiempo de ejecución
- uopz_flags — Recupera o define los flags de una función o clase
- uopz_function — Crea una función en tiempo de ejecución
- uopz_get_exit_status — Devuelve el último estado de salida definido
- uopz_get_hook — Devuelve el hook previamente definido en una función o método
- uopz_get_mock — Devuelve la simulación actual de una clase
- uopz_get_property — Devuelve el valor de una propiedad de clase o instancia
- uopz_get_return — Devuelve un valor de retorno previamente definido para una función
- uopz_get_static — Devuelve las variables estáticas de una función o método
- uopz_implement — Implementa una interfaz en tiempo de ejecución
- uopz_overload — Sobrecarga un opcode de la VM
- uopz_redefine — Redefinir una constante
- uopz_rename — Cambia el nombre de una función en tiempo de ejecución
- uopz_restore — Restaura una función guardada
- uopz_set_hook — Define el hook que se ejecutará al entrar en una función o un método
- uopz_set_mock — Utiliza una simulación en lugar de una clase para nuevos objetos
- uopz_set_property — Establece el valor de una propiedad de clase existente o de instancia
- uopz_set_return — Proporciona un valor de retorno para una función existente
- uopz_set_static — Fija las variables estáticas en el ámbito de una función o de un método
- uopz_undefine — Elimina una constante
- uopz_unset_hook — Suprime el hook previamente fijado sobre una función o un método
- uopz_unset_mock — Suprime la simulación previamente fijada
- uopz_unset_return — Suprime un valor de retorno previamente fijado para una función

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
- Constantes predefinidas
- Funciones Uopz
  - uopz_add_function — Añade una función o método inexistente
  - uopz_allow_exit — Permite controlar el opcode exit desactivado
  - uopz_backup — Guarda una función
  - uopz_compose — Componer una clase
  - uopz_copy — Copia una función
  - uopz_del_function — Elimina una función o método previamente añadido
  - uopz_delete — Elimina una función
  - uopz_extend — Extiende una clase en tiempo de ejecución
  - uopz_flags — Recupera o define los flags de una función o clase
  - uopz_function — Crea una función en tiempo de ejecución
  - uopz_get_exit_status — Devuelve el último estado de salida definido
  - uopz_get_hook — Devuelve el hook previamente definido en una función o método
  - uopz_get_mock — Devuelve la simulación actual de una clase
  - uopz_get_property — Devuelve el valor de una propiedad de clase o instancia
  - uopz_get_return — Devuelve un valor de retorno previamente definido para una función
  - uopz_get_static — Devuelve las variables estáticas de una función o método
  - uopz_implement — Implementa una interfaz en tiempo de ejecución
  - uopz_overload — Sobrecarga un opcode de la VM
  - uopz_redefine — Redefinir una constante
  - uopz_rename — Cambia el nombre de una función en tiempo de ejecución
  - uopz_restore — Restaura una función guardada
  - uopz_set_hook — Define el hook que se ejecutará al entrar en una función o un método
  - uopz_set_mock — Utiliza una simulación en lugar de una clase para nuevos objetos
  - uopz_set_property — Establece el valor de una propiedad de clase existente o de instancia
  - uopz_set_return — Proporciona un valor de retorno para una función existente
  - uopz_set_static — Fija las variables estáticas en el ámbito de una función o de un método
  - uopz_undefine — Elimina una constante
  - uopz_unset_hook — Suprime el hook previamente fijado sobre una función o un método
  - uopz_unset_mock — Suprime la simulación previamente fijada
  - uopz_unset_return — Suprime un valor de retorno previamente fijado para una función

# Caché de Windows para PHP

# Introducción

La Extensión de Caché de Windows para PHP es un acelerador de PHP utilizado para incrementar la velocidad de las aplicaciones de PHP que se ejecutan sobre Windows y Windows Server. Una vez que la Extensión de Caché de Windows para PHP está habilitada y cargada por el motor de PHP, las aplicaciones de PHP se podrán aprovechar de la funcionalidad sin ninguna modificación en el código.

La Extensión de Caché de Windows para PHP incluye 5 tipos diferentes de cachés. A continuación se describe el propósito de cada tipo de caché y los beneficios que ofrece.

- Caché de opcodes de PHP - PHP es un motor de procesamiento de scripts que lee un flujo de datos de entrada que contiene texto, instrucciones de PHP, o ambas, y produce otro flujo de datos, generalmente en formato HTML. Esto significa que, en un servidor web, el motor de PHP lee, analiza, compila y ejecuta un script de PHP cada vez que es solicitado por un cliente web. Las operaciones de lectura, análisis y compilación añaden una carga adicional a la CPU del servidor web y del sistema de ficheros y por tanto afectar al rendimiento global de una aplicación web PHP. La caché de bytecodes (opcodes) de PHP se utiliza para almacenar, en memoria compartida, el script de bytecodes ya compilado de manera que pueda ser re-utilizado por el motor de PHP para ejecuciones posteriores del mismo script.

  El soporte para el almacenamiento en caché de opcode fue eliminado en `Wincache 2.0.0`, todos los usuarios que desean tener un opcache debe utilizar la extensión OPcache que se incluye en PHP.

- Caché de Fichero - Incluso con la caché de opcodes de PHP activada, en un sistema de ficheros el motor de PHP, debe acceder a los ficheros de script. Cuando los script de PHP son almacenados en un UNC remoto de compartición de ficheros, las operaciones sobre ficheros introducen una considerable sobrecarga de rendimiento. La Extensión de Caché de Windows para PHP incluye una caché de ficheros que es utilizada para almacenar los contenidos de los ficheros de script de PHP en memoria compartida, lo que reduce la cantidad de operaciones en el sistema de ficheros realizado por el motor de PHP.

- Caché de Resolución de Rutas de Ficheros - Los script de PHP a menudo incluyen u operan con ficheros mediante el uso de rutas relativas. Cada ruta de fichero debe ser normalizada por el motor de PHP a una ruta de fichero absoluta. Cuando una aplicación de PHP emplea muchos ficheros PHP y accede a ellos mediante rutas relativas, el tener que resolver las rutas puede afectar de manera negativa al rendimiento de la aplicación. La Extensión de Caché de Windows para PHP ofrece una caché de Resolución de Rutas de Ficheros, que se emplea para almacenar los mapeos entre las rutas relativas de ficheros y las absolutas, reduciendo por tanto la cantidad de resoluciones de rutas que el motor de PHP tiene que realizar.

- Caché de Usuario (disponible desde la versión 1.1.0) - Los scripts de PHP pueden aprovecharse de la caché de la memoria compartida mediante el uso del API de la caché de usuario. Los objetos PHP y las variables se pueden almacenar en la caché de usuario y ser reutilizadas en posteriores peticiones. Esto se puede emplear para mejorar el rendimiento de los script de PHP y para compartir datos entre múltiples procesos de PHP.

- Gestor de Sesión (disponible desde la versión 1.1.0) - El gestor de sesión WinCache se puede emplear para almacenar los datos de la sesión PHP en la memoria compartida. Esto evita operaciones del sistema de ficheros para leer y escribir datos de sesión, lo que mejora el rendimiento cuando se almacenan grandes cantidades de datos en la sesión de PHP.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución
- Script de estadísticas WinCache
- Manejador de sesiones WinCache
- Redirecciones de funciones WinCache

## Requerimientos

La extensión actualmente solo es compatible con las siguientes configuraciones:

Sistema Operativo Windows:

- Windows XP SP3 con IIS 5.1 y la » Extensión FastCGI
- Windows Server 2003 con IIS 6.0 y la » Extensión FastCGI
- Windows Vista SP1 con IIS 7.0 y el módulo FastCGI
- Windows Server 2008 con IIS 7.0 y el módulo FastCGI
- Windows 7 con IIS 7.5 y el módulo FastCGI
- Windows Server 2008 R2 con IIS 7.5 y el módulo FastCGI

PHP:

- PHP 5.2.X, compilación no segura para subprocesos
- PHP 5.3 X86, compilación VC9 no segura para subprocesos

> Nota: La extensión WinCache solo puede ser utilizada cuando IIS está configurado para ejecutar PHP a través de FastCGI.

## Instalación

Esta extensión » PECL no está integrada en PHP.

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/wincache.

Hay dos paquetes para esta extensión: un paquete es para las versiones PHP 5.2.X, y el otro paquete es para PHP 5.3.X. Elija el paquete adecuado para la versión de PHP que esté utilizando.

Para instalar y activar la extensión, siga estos pasos:

1. Descomprima el paquete en una ubicación temporal.

2. Copie el archivo php_wincache.dll en la carpeta de extensiones PHP. Generalmente, esta carpeta se llama "ext" y está ubicada en el mismo directorio que todos los archivos binarios de PHP. Por ejemplo: C:\Program Files\PHP\ext.

3. Con un editor de texto, abra el archivo php.ini, que generalmente se encuentra en el mismo directorio que todos los archivos binarios de PHP. Por ejemplo: C:\Program Files\PHP\php.ini.

4. Agregue la siguiente línea al final del archivo php.ini: `extension = php_wincache.dll`.

5. Guarde y cierre el archivo php.ini.

6. Reinicie el grupo de aplicaciones IIS para que PHP recoja los cambios de configuración. Para verificar que la extensión se ha activado, cree un archivo llamado phpinfo.php que contenga una llamada a la función phpinfo.

7. Guarde el archivo phpinfo.php en el directorio raíz de un sitio web IIS que utilice PHP, luego abra un navegador y realice una solicitud a http://localhost/phpinfo.php. Busque una sección llamada `wincache` en la página devuelta. Si la extensión está activada, la salida de phpinfo listará los parámetros de configuración proporcionados por WinCache.

> Nota: No olvide eliminar el archivo phpinfo.php del directorio raíz después de haber verificado que la extensión se ha activado.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

La siguiente tabla enumera y explica los ajustes de configuración proporcionados por la extensión WinCache:

Opciones de configuración de WinCache
Nombre | Por defecto | Mínimo | Máximo | Cambiable | Historial de cambios
--- | --- | --- | --- | --- | ---
wincache.fcenabled | "1" | "0" | "1" | `INI_ALL` | Disponible a partir de WinCache 1.0.0
wincache.fcenabledfilter | "NULL" | "NULL" | "NULL" | `INI_SYSTEM` | Disponible a partir de WinCache 1.0.0
wincache.fcachesize | "24" | "5" | "255" | `INI_SYSTEM` | Disponible a partir de WinCache 1.0.0
wincache.fcndetect | "1" | "0" | "1" | `INI_SYSTEM` | Disponible a partir de WinCache 1.1.0
wincache.maxfilesize | "256" | "10" | "2048" | `INI_SYSTEM` | Disponible a partir de WinCache 1.0.0
wincache.ocenabled | "1" | "0" | "1" | `INI_ALL` | Disponible a partir de WinCache 1.0.0. Eliminada a partir de 2.0.0.0
wincache.ocenabledfilter | "NULL" | "NULL" | "NULL" | `INI_SYSTEM` | Disponible a partir de WinCache 1.0.0. Eliminada a partir de 2.0.0.0
wincache.ocachesize | "96" | "15" | "255" | `INI_SYSTEM` | Disponible a partir de WinCache 1.0.0. Eliminada a partir de 2.0.0.0
wincache.filecount | "4096" | "1024" | "16384" | `INI_SYSTEM` | Disponible a partir de WinCache 1.0.0
wincache.chkinterval | "30" | "0" | "300" | `INI_SYSTEM` | Disponible a partir de WinCache 1.0.0
wincache.ttlmax | "1200" | "0" | "7200" | `INI_SYSTEM` | Disponible a partir de WinCache 1.0.0
wincache.enablecli | 0 | 0 | 1 | `INI_SYSTEM` | Disponible a partir de WinCache 1.0.0
wincache.ignorelist | NULL | NULL | NULL | `INI_ALL` | Disponible a partir de WinCache 1.0.0
wincache.namesalt | NULL | NULL | NULL | `INI_SYSTEM` | Disponible a partir de WinCache 1.0.0
wincache.ucenabled | 1 | 0 | 1 | `INI_SYSTEM` | Disponible a partir de WinCache 1.1.0
wincache.ucachesize | 8 | 5 | 85 | `INI_SYSTEM` | Disponible a partir de WinCache 1.1.0
wincache.scachesize | 8 | 5 | 85 | `INI_SYSTEM` | Disponible a partir de WinCache 1.1.0
wincache.rerouteini | NULL | NULL | NULL | `INI_SYSTEM` | Disponible a partir de WinCache 1.2.0. Eliminada a partir de 1.3.7
wincache.reroute_enabled | 1 | 0 | 1 | `INI_SYSTEM`|`INI_PERDIR` | Disponible a partir de WinCache 1.3.7
wincache.srwlocks | 1 | 0 | 1 | `INI_SYSTEM` | Disponible a partir de WinCache 1.3.6.3. Eliminada a partir de 2.0.0.0
wincache.filemapdir | NULL | NULL | NULL | `INI_SYSTEM` | Disponible a partir de WinCache 1.3.7.4

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`wincache.fcenabled` bool
  Habilita o deshabilita la caché de ficheros.
`wincache.fcenabledfilter` string
  Define una lista separada por comas de identificadores de sitios web de IIS donde debería habilitarse o deshabilitarse la caché de ficheros. Esta opción funciona junto con `wincache.fcenabled`: si `wincache.fcenabled` se establece a 1, los sitios enumerados en `wincache.fcenabledfilter` tendrán la caché de ficheros desactivada; si `wincache.fcenabled` se establece a 0, los sitios enumerados en `wincache.fcenabledfilter` tendrán la caché activada.
`wincache.fcachesize` int
  Define el tamaño máximo de memoria (en megabytes) que se asigna a la caché de ficheros. Si el tamaño total de ficheros en caché excede el valor especificado en este ajuste, se eliminarán los ficheros más antiguos de la caché de ficheros.
`wincache.fcndetect` bool
  Habilita o deshabilita la detección de notificaciones de cambios en ficheros. Si está soportada la notificación de cambios en ficheros, se usará para refrescar las entradas de la caché de códigos de operación y de ficheros en cuanto los ficheros correspondientes sean modificados en un sistema de ficheros. Si la notificación de cambios en ficheros no está soportada, por ejemplo, al usar la compartición de ficheros en red, wincache hará un sondeo para los cambios en ficheros en intervalos de tiempo regulares especificados por `wincache.chkinterval`.
`wincache.maxfilesize` int
  Define el tamaño máximo permitido (en kilobytes) para que un fichero sea almacenado en caché. Si un fichero excede el valor especificado, no será almacenado en caché. Este ajuste se aplica solamente a la caché de ficheros.
`wincache.ocenabled` bool
  Advertencia

  Esta opción ha sido eliminada a partir de 2.0.0.0

  Habilita o deshabilita la caché de códigos de operaciones ("opcodes")
`wincache.ocenabledfilter` string
  Advertencia

  Esta opción ha sido eliminada a partir de 2.0.0.0

  Define una lista separada por comas de identificadores de sitios web de IIS donde se debería habilitar o deshabilitar la caché de códigos de operaciones. Este ajuste funciona junto con `wincache.ocenabled`: si `wincache.ocenabled` se establece a 1, los sitios enumerados en `wincache.ocenabledfilter` tendrán la caché de códigos de operaciones desactivada; si `wincache.ocenabled` se establece a 0, los sitios enumerados en `wincache.ocenabledfilter` tendrán la caché de códigos de operaciones activada.
`wincache.ocachesize` int
  Advertencia

  Esta opción ha sido eliminada a partir de 2.0.0.0

  Define el tamaño máximo de memoria (en megabytes) que se asigna a la caché de códigos de operaciones. Si el tamaño de dicha caché excede el valor especificado se eliminarán de la caché los códigos de operación más antiguos. Observe que el tamaño de la caché de códigos de operaciones debe ser al menos tres veces mayor que el tamaño de la caché de ficheros. Si no fuera así, el tamaño de la caché de códigos de operaciones será aumentada automáticamente.
`wincache.filecount` int
  Define cuántos ficheros se preveen que almacene en caché la extensión, para así asignar el tamaño de memoria apropiada en el momento del arranque. Si el número de ficheros excede el valor especificado, WinCache reasignará tanta memoria como sea necesaria.
`wincache.chkinterval` int
  Define la frecuencia (en segundos) con que la extensión comprobará los cambios en ficheros para refrescar la caché. Si se establece a 0 se deshabilitará el refresco de la caché. Los cambios en ficheros no se verán reflejados en la caché al menos que la entrada de la caché para tales ficheros sea eliminada mediante limpieza ("scavenger"), o la provisión ("pool") de aplicaciones de IIS sea reclicada, o se llame a la función wincache_refresh_if_changed.
`wincache.ttlmax` int
  Define el tiempo máximo de vida (en segundos) para una entrada de caché que no se esté usando. Si se establece a 0, se desactivará la limpieza de la caché, por lo que las entradas en caché nunca serán eliminadas durante el tiempo de vida del proceso obrero ("worker") de IIS.
`wincache.enablecli` bool
  Define si la caché se habilita cuando PHP se está ejecutando en modo de línea de comandos (CLI).
`wincache.ignorelist` string

  Define una lista de ficheros que no deberían ser almacenados en caché por la extensión. La lista de ficheros se especifica empleando solamente nombres de ficheros, separados por el símbolo tubería - "|".

  Ejemplo #1 Ejemplo de `wincache.ignorelist`

      wincache.ignorelist = "index.php|misc.php|admin.php"

`wincache.namesalt` string
  Define un string que será usado al nombrar los objetos específicos de la extensión que están almacenados en la memoria compartida. Se emplea para evitar conflictos que podrían causarse si otras aplicaciones dentro de un proceso obrero de IIS intenta acceder a la memoria compartida. La longitud del sting namesalt no puede exceder de 8 caracteres.
`wincache.ucenabled` bool
  Habilita o deshabilita la caché de usuarios.
`wincache.ucachesize` int
  Define el tamaño máximo de memoria en megabytes que se asigna para la caché de usuario. Si el tamaño total de las variables almacenadas en la caché de usuario excede el valor especificado, se eliminarán las variables más antiguas de la caché.
`wincache.scachesize` int
  Define el tamaño máximo de memoria en megabytes que se asigna para la caché de sesión. Si el tamaño total de los datos almacenados en la caché de sesión excede el valor especificado, se eliminarán los datos más antiguos de la caché.
`wincache.rerouteini` string
  Advertencia

  Esta opción ha sido eliminada a partir de 1.3.7. Véase `wincache.reroute_enabled` para una funcionalidad similar a partir de 1.3.7.

  Especifica una ruta absoluta o relativa al fichero reroute.ini que contiene la lista de funciones de PHP cuya implementación debería ser remplazada con las funciones equivalentes de WinCache. Si se especifica una ruta relativa, se asume que sea relativa a la ubicación del fichero php-cgi.exe.
`wincache.reroute_enabled` bool
  Habilita o deshabilita el redireccionamiento de varias funciones de E/S de ficheros a través de la caché de ficheros.
`wincache.srwlocks` bool
  Advertencia

  Esta opción ha sido eliminada a partir de 2.0.0.0

  Habilita o deshabilita el uso de bloqueos ("locks) de lectura/escritura compartidos. La deshabilitación es útil cuando se dan condiciones de problemas de punto muerto ("deadlock") en WinCache.
`wincache.filemapdir` string
  Especifica una ruta absoluta al directorio donde WinCache almacenará los ficheros temporales empleados para segmentos de memoria compartida. Este directorio debe estar en la máquina local y no en un sistema de ficheros en la red. Si no se especifica este directorio, WinCache utilizará el fichero de paginación de Windows para todos los segmentos de memoria compartida.

## Script de estadísticas WinCache

El paquete de instalación para WinCache incluye un script PHP, wincache.php, que puede ser utilizado para obtener información y estadísticas sobre la caché.

Si la extensión WinCache se instaló a través del instalador de Microsoft Web Platform, entonces este script se encuentra en %SystemDrive%\Program Files\IIS\Windows Cache for PHP\. En una versión de 64 bits del sistema operativo Windows Server, el script se encuentra en %SystemDrive%\Program Files (x86)\IIS\Windows Cache for PHP. Si la extensión se instaló manualmente, entonces el archivo wincache.php estará ubicado en el mismo directorio desde el cual se extrajo el contenido del paquete de instalación.

Para usar wincache.php, cópielo en el directorio raíz de un sitio web o en cualquier subdirectorio. Para proteger el script, ábralo en cualquier editor y reemplace los valores de las constantes USERNAME y PASSWORD. Si alguna otra autenticación IIS está habilitada en el servidor, entonces siga las instrucciones en los comentarios:

Ejemplo #1 Configuración de la autenticación para wincache.php

    <?php
    /**
     * ======================== CONFIGURACIÓN DE AJUSTES ==============================
     * Si no desea usar la autenticación para esta página, establezca USE_AUTHENTICATION en 0.
     * Si usa autenticación, reemplace la contraseña predeterminada.
     */
    define('USE_AUTHENTICATION', 1);
    define('USERNAME', 'wincache');
    define('PASSWORD', 'wincache');

    /**
     * La autenticación PHP básica solo funcionará cuando IIS esté configurado para admitir
     * 'Autenticación anónima' y nada más. Si IIS está configurado para admitir/usar
     * cualquier otro tipo de autenticación como Básica/Negociar/Digest, etc., esto no funcionará.
     * En ese caso, use la matriz a continuación para definir los nombres de los usuarios en su
     * dominio/red/grupo de trabajo a los que desea otorgar acceso.
     */
    $user_allowed = array('DOMAIN\user1', 'DOMAIN\user2', 'DOMAIN\user3');

    /**
     * Si la matriz contiene la cadena 'all', entonces todos los usuarios autenticados por IIS
     * tendrán acceso a la página. Descomente la línea a continuación y comente la línea anterior
     * para otorgar acceso a todos los usuarios que sean autenticados por IIS.
     */
    /* $user_allowed = array('all'); */

    /** ===================== FIN DE CONFIGURACIÓN DE AJUSTES ========================== */
    ?>

> Nota: Siempre proteja el script wincache.php utilizando el mecanismo de autenticación integrado o el mecanismo de autenticación del servidor. Dejar este script sin protección puede comprometer la seguridad de su aplicación web y del servidor.

## Manejador de sesiones WinCache

El manejador de sesiones WinCache (disponible desde WinCache 1.1.0) puede ser utilizado para configurar PHP para almacenar los datos de sesión en la memoria compartida del caché de sesión. El uso de la memoria compartida en lugar de la sesión predeterminada ayuda a mejorar el rendimiento de las aplicaciones PHP que almacenan grandes cantidades de datos en objetos de sesión. El caché de sesión Wincache utiliza archivos basados en memoria compartida, lo que asegura que los datos de sesión no se perderán durante el reciclaje de la cola de aplicaciones IIS.

Para configurar PHP para usar el manejador de sesiones WinCache, establezca el parámetro session.save_handler del archivo php.ini a wincache. De forma predeterminada, la ubicación donde se almacenan los archivos temporales en Windows se usa para almacenar los datos de sesión. Para cambiar esta ubicación, use la directiva session.save_path.

Ejemplo #1 Activar el manejador de sesiones WinCache

    session.save_handler = wincache
    session.save_path = C:\inetpub\temp\session\

## Redirecciones de funciones WinCache

NOTA: wincache.rerouteini fue eliminado con WinCache 1.3.7.0. Esto ha sido reemplazado por el redireccionamiento automático de funciones. Ver: wincache.reroute_enabled

Las funcionalidades de redireccionamiento de funciones de WinCache (disponibles desde WinCache 1.2.0, eliminadas desde WinCache 1.3.7.0) pueden ser utilizadas para reemplazar funciones PHP nativas por sus equivalentes optimizados para casos particulares. La extensión Wincache incluye implementaciones de funciones PHP optimizadas para Windows, especialmente en casos de acceso a red o sistema de archivos. Las siguientes funciones están involucradas:

- file_exists
- file_get_contents
- readfile
- is_readable
- is_writable
- is_dir
- realpath
- filesize

Para configurar el redireccionamiento de funciones con Wincache, use el archivo reroute.ini incluido en el paquete. Cópielo en el directorio donde se encuentra php.ini. Luego, agregue wincache.rerouteini en php.ini y especifique la ruta absoluta o relativa a reroute.ini.

Ejemplo #1 Activación de las funcionalidades de redireccionamiento de funciones de WinCache

    wincache.rerouteini = C:\PHP\reroute.ini

> Nota: Si está habilitado, se recomienda aumentar el tamaño del caché de archivos. Esto se puede hacer usando el parámetro wincache.fcachesize.

El archivo reroute.ini contiene la correspondencia entre la función PHP nativa y el equivalente de Wincache. Cada línea en el archivo define una correspondencia. Aquí está la sintaxis:

`<Nombre de la función PHP>:[<número de parámetros de la función>]=<nombre de la función wincache>`

A continuación se muestra un ejemplo de archivo. En este ejemplo, las llamadas a las funciones PHP file_get_contents() serán reemplazadas por wincache_file_get_contents() solo si el número de parámetros pasados a la función es menor o igual a dos. Es útil especificar el número de parámetros cuando la función de reemplazo no está diseñada para usar todos ellos.

Ejemplo #2 Reroute.ini

    [FunctionRerouteList]
    file_exists=wincache_file_exists
    file_get_contents:2=wincache_file_get_contents
    readfile:2=wincache_readfile
    is_readable=wincache_is_readable
    is_writable=wincache_is_writable
    is_writeable=wincache_is_writable
    is_file=wincache_is_file
    is_dir=wincache_is_dir
    realpath=wincache_realpath
    filesize=wincache_filesize

# Funciones de WinCache

# wincache_fcache_fileinfo

(PECL wincache >= 1.0.0)

wincache_fcache_fileinfo — Extrae información sobre los archivos almacenados en la caché de archivos

### Descripción

function wincache_fcache_fileinfo(bool `$summaryonly` = `false`): array|false

Extrae información sobre el contenido de la caché de archivos y su utilización.

### Parámetros

`summaryonly`

  Controla si el array devuelto debe contener información sobre las entradas individuales del caché además del resumen del caché de archivos.

### Valores devueltos

Array de metadatos sobre la caché de archivos o `false` si ocurre un error

El array devuelto por esta función contiene los siguientes elementos:

- `total_cache_uptime` - Tiempo total de actividad en segundos de la caché de archivos
- `total_file_count` - Número total de archivos actualmente en la caché de archivos
- `total_hit_count` - Número de veces que los archivos han sido servidos desde la caché de archivos
- `total_miss_count` - Número de veces que los archivos no se encontraron en la caché de archivos

- `file_entries` - Array que contiene información sobre todos los archivos almacenados en caché:

  - `file_name` - Nombre y ruta absoluta del archivo en caché
  - `add_time` - Tiempo en segundos desde que el archivo fue añadido a la caché de archivos
  - `use_time` - Tiempo en segundos desde que el archivo fue consultado en la caché de archivos
  - `last_check` - Tiempo en segundos desde la última verificación de modificaciones
  - `hit_count` - Número de veces que el archivo ha sido servido desde la caché
  - `file_size` - Tamaño en bytes del archivo almacenado en caché

### Ejemplos

Ejemplo #1 Un ejemplo de wincache_fcache_fileinfo()

    <pre>
    <?php
    print_r(wincache_fcache_fileinfo());
    ?>
    </pre>

El ejemplo anterior mostrará:

    Array
    (
        [total_cache_uptime] => 3234
        [total_file_count] => 5
        [total_hit_count] => 0
        [total_miss_count] => 1
        [file_entries] => Array
            (
                [1] => Array
                    (
                        [file_name] => c:\inetpub\wwwroot\checkcache.php
                        [add_time] => 1
                        [use_time] => 0
                        [last_check] => 1
                        [hit_count] => 1
                        [file_size] => 2435
                    )
                [2] => Array (...iterates for each cached file)
            )
    )

### Ver también

- wincache_fcache_meminfo() - Recupera información sobre el uso de memoria caché de ficheros
- wincache_ocache_fileinfo() - Extrae información sobre los archivos almacenados en el caché opcode
- wincache_ocache_meminfo() - Extrae información sobre la utilización del caché opcode
- wincache_rplist_fileinfo() - Recupera información de la caché sobre una ruta de archivo resuelta
- wincache_rplist_meminfo() - Recupera información sobre el uso de la memoria por la caché de ruta de archivo resuelta
- wincache_refresh_if_changed() - Actualiza las entradas del caché para los archivos almacenados en caché
- wincache_ucache_meminfo() - Recupera información sobre el uso de memoria caché de usuario
- wincache_ucache_info() - Recupera información sobre los datos almacenados en la caché del usuario
- wincache_scache_info() - Recupera información sobre archivos almacenados en el caché de sesión.
- wincache_scache_meminfo() - Recupera información sobre el uso de memoria caché de sesión

# wincache_fcache_meminfo

(PECL wincache >= 1.0.0)

wincache_fcache_meminfo — Recupera información sobre el uso de memoria caché de ficheros

### Descripción

function wincache_fcache_meminfo(): array|false

Recupera información sobre el uso de la memoria caché del fichero.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Array de meta datos sobre el uso de memoria caché de ficheros o `false` si ocurre un error

El array devuelta por esta función contiene los siguientes elementos:

- `memory_total` - cantidad de memoria en bytes asignados para la caché de ficheros
- `memory_free` - cantidad de memoria libre en bytes disponibles para la caché de ficheros
- `num_used_blks` - número de bloques de memoria utilizados por la caché de ficheros
- `num_free_blks` - número de bloques de memoria libre disponibles para la caché de ficheros
- `memory_overhead` - cantidad de memoria en bytes utilizados para las estructuras internas de la caché de ficheros

### Ejemplos

Ejemplo #1 Un ejemplo de wincache_fcache_meminfo()

    <pre>
    <?php
    print_r(wincache_fcache_meminfo());
    ?>
    </pre>

El ejemplo anterior mostrará:

    Array
    (
        [memory_total] => 134217728
        [memory_free] => 131339120
        [num_used_blks] => 361
        [num_free_blks] => 3
        [memory_overhead] => 5856
    )

### Ver también

- wincache_fcache_fileinfo() - Extrae información sobre los archivos almacenados en la caché de archivos
- wincache_ocache_fileinfo() - Extrae información sobre los archivos almacenados en el caché opcode
- wincache_ocache_meminfo() - Extrae información sobre la utilización del caché opcode
- wincache_rplist_fileinfo() - Recupera información de la caché sobre una ruta de archivo resuelta
- wincache_rplist_meminfo() - Recupera información sobre el uso de la memoria por la caché de ruta de archivo resuelta
- wincache_refresh_if_changed() - Actualiza las entradas del caché para los archivos almacenados en caché
- wincache_ucache_meminfo() - Recupera información sobre el uso de memoria caché de usuario
- wincache_ucache_info() - Recupera información sobre los datos almacenados en la caché del usuario
- wincache_scache_info() - Recupera información sobre archivos almacenados en el caché de sesión.
- wincache_scache_meminfo() - Recupera información sobre el uso de memoria caché de sesión

# wincache_lock

(PECL wincache >= 1.1.0)

wincache_lock — Obtiene un bloqueo exclusivo en una clave dada

### Descripción

function wincache_lock(string `$key`, bool `$isglobal` = `false`): bool

Obtiene un bloqueo exclusivo sobre una clave dada. La ejecución del script actual quedará en espera que se pueda obtener el bloqueo. Una vez obtenido el bloqueo, el otro script que intente solicitar dicho bloqueo utilizando la misma clave quedará en espera, hasta que el script actual libere el bloqueo con wincache_unlock().

Advertencia

El uso de wincache_lock() y wincache_unlock() puede causar bloqueos de punto muerto al ejecutar scripts de PHP en un entorno multiproceso como FastCGI. No emplear estas funciones a menos que se esté absolutamente seguro de que son necesarias. Para la mayoría de las operaciones en la caché de usuario no es necesario usar estas funciones.

### Parámetros

`key`

  Nombre de la clave en la caché para adquirir el bloqueo.

`isglobal`

  Controla si el ámbito del bloqueo es a nivel de sistema o local. Los bloqueos locales tienen alcance para la «pool» de la aplicación en el caso de FastCGI de IIS o a todos los procesos de php que tengan el mismo identificador de proceso padre.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Empleo de wincache_lock()

    <?php
    $fp = fopen("/tmp/lock.txt", "r+");
    if (wincache_lock(“lock_txt_lock”)) { // realizar un bloqueo exclusivo
        ftruncate($fp, 0); // truncate file
        fwrite($fp, "Write something here\n");
        wincache_unlock(“lock_txt_lock”); // liberar el bloqueo
    } else {
        echo "No se pudo obtener el bloqueo";
    }
    fclose($fp);
    ?>

### Ver también

- wincache_unlock() - Libera un bloqueo exclusivo sobre una clave dada
- wincache_ucache_set() - Añade una variable a la caché de usuario y sobrescribe la variable si ya existe en la caché
- wincache_ucache_get() - Obtiene una variable almacenada en la caché del usuario
- wincache_ucache_delete() - Elimina las variables de la memoria caché del usuario
- wincache_ucache_clear() - Elimina todo el contenido de la caché del usuario
- wincache_ucache_exists() - Comprueba si una variable existe en la caché del usuario
- wincache_ucache_meminfo() - Recupera información sobre el uso de memoria caché de usuario
- wincache_ucache_info() - Recupera información sobre los datos almacenados en la caché del usuario
- wincache_scache_info() - Recupera información sobre archivos almacenados en el caché de sesión.

# wincache_ocache_fileinfo

(PECL wincache >= 1.0.0)

wincache_ocache_fileinfo — Extrae información sobre los archivos almacenados en el caché opcode

### Descripción

function wincache_ocache_fileinfo(bool `$summaryonly` = `false`): array|false

Extrae información sobre el contenido del caché opcode y su utilización.

Advertencia

Esta función ha sido ELIMINADA a partir de PHP 7.0.0.

### Parámetros

`summaryonly`

  Controla si el array devuelto debe contener información sobre las entradas individuales del caché además del resumen del caché opcode.

### Valores devueltos

Array de metadatos sobre el caché opcode o `false` si ocurre un error

El array devuelto por esta función contiene los siguientes elementos:

- `total_cache_uptime` - Tiempo total de actividad en segundos del caché opcode
- `total_file_count` - Número total de archivos actualmente en el caché opcode
- `total_hit_count` - Número total de veces que el opcode compilado ha sido servido desde el caché
- `total_miss_count` - Número de veces que el opcode compilado no se encontró en el caché
- `is_local_cache` - true si los metadatos del caché son para una instancia de caché local, false si los metadatos son para el caché global.

- `file_entries` - Array que contiene información sobre todos los archivos almacenados en caché:

  - `file_name` - Nombre de archivo absoluto del archivo en caché
  - `add_time` - Tiempo en segundos desde que el archivo fue añadido al caché opcode
  - `use_time` - Tiempo en segundos desde que el archivo fue consultado en el caché opcode
  - `last_check` - Tiempo en segundos desde que el archivo fue verificado para cambios
  - `hit_count` - Número de veces que el archivo ha sido servido desde el caché
  - `function_count` - Número de funciones en el caché
  - `class_count` - Número de clases en el caché

### Ejemplos

Ejemplo #1 Un ejemplo de wincache_ocache_fileinfo()

    <pre>
    <?php
    print_r(wincache_ocache_fileinfo());
    ?>
    </pre>

El ejemplo anterior mostrará:

    Array
    (
        [total_cache_uptime] => 17357
        [total_file_count] => 121
        [total_hit_count] => 36562
        [total_miss_count] => 201
        [file_entries] => Array
            (
                [1] => Array
                    (
                        [file_name] => c:\inetpub\wwwroot\checkcache.php
                        [add_time] => 17356
                        [use_time] => 7
                        [last_check] => 10
                        [hit_count] => 454
                        [function_count] => 0
                        [class_count] => 1
                    )
                [2] => Array (...iterates for each cached file)
            )
    )

### Ver también

- wincache_fcache_fileinfo() - Extrae información sobre los archivos almacenados en la caché de archivos
- wincache_fcache_meminfo() - Recupera información sobre el uso de memoria caché de ficheros
- wincache_ocache_meminfo() - Extrae información sobre la utilización del caché opcode
- wincache_rplist_fileinfo() - Recupera información de la caché sobre una ruta de archivo resuelta
- wincache_rplist_meminfo() - Recupera información sobre el uso de la memoria por la caché de ruta de archivo resuelta
- wincache_refresh_if_changed() - Actualiza las entradas del caché para los archivos almacenados en caché
- wincache_ucache_meminfo() - Recupera información sobre el uso de memoria caché de usuario
- wincache_ucache_info() - Recupera información sobre los datos almacenados en la caché del usuario
- wincache_scache_info() - Recupera información sobre archivos almacenados en el caché de sesión.
- wincache_scache_meminfo() - Recupera información sobre el uso de memoria caché de sesión

# wincache_ocache_meminfo

(PECL wincache >= 1.0.0)

wincache_ocache_meminfo — Extrae información sobre la utilización del caché opcode

### Descripción

function wincache_ocache_meminfo(): array|false

Extrae información sobre la utilización de la memoria por el caché opcode.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Tabla de metadatos sobre la utilización de la memoria caché opcode o `false` si ocurre un error

La tabla devuelta por esta función contiene los siguientes elementos:

- `memory_total` - Cantidad de memoria en bytes, asignada para el caché opcode
- `memory_free` - Cantidad de memoria libre en bytes, disponible para el caché opcode
- `num_used_blks` - Número de bloques de memoria utilizados por el caché opcode
- `num_free_blks` - Número de bloques de memoria libres disponibles para el caché opcode
- `memory_overhead` - Cantidad de memoria en bytes utilizada para la estructura interna del caché opcode

Advertencia

Esta función ha sido ELIMINADA a partir de PHP 7.0.0.

### Ejemplos

Ejemplo #1 Un ejemplo de wincache_ocache_meminfo()

    <pre>
    <?php
    print_r(wincache_ocache_meminfo());
    ?>
    </pre>

El ejemplo anterior mostrará:

    Array
    (
        [memory_total] => 134217728
        [memory_free] => 112106972
        [num_used_blks] => 15469
        [num_free_blks] => 4
        [memory_overhead] => 247600
    )

### Ver también

- wincache_fcache_fileinfo() - Extrae información sobre los archivos almacenados en la caché de archivos
- wincache_fcache_meminfo() - Recupera información sobre el uso de memoria caché de ficheros
- wincache_ocache_fileinfo() - Extrae información sobre los archivos almacenados en el caché opcode
- wincache_rplist_fileinfo() - Recupera información de la caché sobre una ruta de archivo resuelta
- wincache_rplist_meminfo() - Recupera información sobre el uso de la memoria por la caché de ruta de archivo resuelta
- wincache_refresh_if_changed() - Actualiza las entradas del caché para los archivos almacenados en caché
- wincache_ucache_meminfo() - Recupera información sobre el uso de memoria caché de usuario
- wincache_ucache_info() - Recupera información sobre los datos almacenados en la caché del usuario
- wincache_scache_info() - Recupera información sobre archivos almacenados en el caché de sesión.
- wincache_scache_meminfo() - Recupera información sobre el uso de memoria caché de sesión

# wincache_refresh_if_changed

(PECL wincache >= 1.0.0)

wincache_refresh_if_changed — Actualiza las entradas del caché para los archivos almacenados en caché

### Descripción

function wincache_refresh_if_changed(array `$files` = NULL): bool

Actualiza las entradas del caché para los archivos cuyos nombres se han pasado en los argumentos de entrada. Si no se especifica ningún argumento, entonces se actualizan todas las entradas del caché.

### Parámetros

`files`

  Array de nombres de archivos para los archivos que necesitan ser actualizados. Se puede usar una ruta de archivo absoluta o relativa.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

WinCache realiza verificaciones regulares en los archivos almacenados en caché para asegurarse de que, si un archivo ha cambiado, la entrada correspondiente en la memoria caché se actualice. Por defecto, esta verificación se realiza cada 30 segundos. Si, por ejemplo, un script PHP actualiza otro script PHP donde se almacenan las configuraciones de la aplicación, entonces puede ocurrir que, después de que los cambios de configuración se hayan guardado, la aplicación siga utilizando los parámetros antiguos durante algún tiempo hasta que el caché se actualice. En este caso, es preferible actualizar el caché justo después de que el archivo haya sido modificado. El ejemplo siguiente muestra cómo hacerlo.

Ejemplo #1 Un ejemplo de wincache_refresh_if_changed()

    <?php
    $filename = 'C:\inetpub\wwwroot\config.php';
    $handle = fopen($filename, 'w+');
    if ($handle === FALSE) die('Failed to open file '.$filename.' for writing');
    fwrite($handle, '<?php $setting=something; ?>');
    fclose($handle);
    wincache_refresh_if_changed(array($filename));
    ?>

### Ver también

- wincache_fcache_fileinfo() - Extrae información sobre los archivos almacenados en la caché de archivos
- wincache_fcache_meminfo() - Recupera información sobre el uso de memoria caché de ficheros
- wincache_ocache_fileinfo() - Extrae información sobre los archivos almacenados en el caché opcode
- wincache_ocache_meminfo() - Extrae información sobre la utilización del caché opcode
- wincache_rplist_fileinfo() - Recupera información de la caché sobre una ruta de archivo resuelta
- wincache_rplist_meminfo() - Recupera información sobre el uso de la memoria por la caché de ruta de archivo resuelta
- wincache_ucache_meminfo() - Recupera información sobre el uso de memoria caché de usuario
- wincache_ucache_info() - Recupera información sobre los datos almacenados en la caché del usuario

# wincache_rplist_fileinfo

(PECL wincache >= 1.0.0)

wincache_rplist_fileinfo — Recupera información de la caché sobre una ruta de archivo resuelta

### Descripción

function wincache_rplist_fileinfo(bool `$summaryonly` = `false`): array|false

Recupera información sobre las asignaciones almacenadas en caché entre rutas de archivos relativas y sus correspondencias en rutas de archivos absolutas

### Parámetros

`summaryonly`

### Valores devueltos

Un array de metadatos con información sobre la caché de una ruta de archivo resuelta o `false` si ocurre un error

El array devuelto por esta función contiene los siguientes elementos:

- `total_file_count` - número total de rutas de archivos almacenadas en la caché

- `rplist_entries` - un array que contiene la información sobre las rutas de archivo presentes en la caché:

  - `resolve_path` - ruta hacia el archivo
  - `subkey_data` - ruta absoluta correspondiente

### Ejemplos

Ejemplo #1 Ejemplo con wincache_rplist_fileinfo()

    <pre>
    <?php
    print_r(wincache_rplist_fileinfo());
    ?>
    </pre>

El ejemplo anterior mostrará:

    Array
    (
        [total_file_count] => 5
        [rplist_entries] => Array
            (
                [1] => Array
                    (
                        [resolve_path] => checkcache.php
                        [subkey_data] => c:\inetpub\wwwroot|c:\inetpub\wwwroot\checkcache.php
                    )

                [2] => Array (...iterates for each cached file)
            )
    )

### Ver también

- wincache_fcache_meminfo() - Recupera información sobre el uso de memoria caché de ficheros
- wincache_fcache_fileinfo() - Extrae información sobre los archivos almacenados en la caché de archivos
- wincache_ocache_fileinfo() - Extrae información sobre los archivos almacenados en el caché opcode
- wincache_ocache_meminfo() - Extrae información sobre la utilización del caché opcode
- wincache_rplist_meminfo() - Recupera información sobre el uso de la memoria por la caché de ruta de archivo resuelta
- wincache_refresh_if_changed() - Actualiza las entradas del caché para los archivos almacenados en caché
- wincache_ucache_meminfo() - Recupera información sobre el uso de memoria caché de usuario
- wincache_ucache_info() - Recupera información sobre los datos almacenados en la caché del usuario
- wincache_scache_info() - Recupera información sobre archivos almacenados en el caché de sesión.
- wincache_scache_meminfo() - Recupera información sobre el uso de memoria caché de sesión

# wincache_rplist_meminfo

(PECL wincache >= 1.0.0)

wincache_rplist_meminfo — Recupera información sobre el uso de la memoria por la caché de ruta de archivo resuelta

### Descripción

function wincache_rplist_meminfo(): array|false

Recupera información sobre el uso de la memoria por la caché de ruta de archivo resuelta.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array de metadatos que describe el uso de la memoria por la caché de ruta de archivo resuelta. o `false` si ocurre un error

El array devuelto por esta función contiene los siguientes elementos:

- `memory_total` - cantidad de memoria, en bytes, asignada a la caché de rutas de archivos resueltas
- `memory_free` - cantidad de memoria libre, en bytes, disponible para la caché de rutas de archivos resueltas
- `num_used_blks` - número de bloques de memoria usados por la caché de rutas de archivos resueltas
- `num_free_blks` - número de bloques de memoria libres para la caché de rutas de archivos resueltas
- `memory_overhead` - cantidad de memoria, en bytes, usada para la estructura interna de la caché de rutas de archivos resueltas

### Ejemplos

Ejemplo #1 Ejemplo con wincache_rplist_meminfo()

    <pre>
    <?php
    print_r(wincache_rplist_meminfo());
    ?>
    </pre>

El ejemplo anterior mostrará:

    Array
    (
        [memory_total] => 9437184
        [memory_free] => 9416744
        [num_used_blks] => 23
        [num_free_blks] => 1
        [memory_overhead] => 416
    )

### Ver también

- wincache_fcache_fileinfo() - Extrae información sobre los archivos almacenados en la caché de archivos
- wincache_fcache_meminfo() - Recupera información sobre el uso de memoria caché de ficheros
- wincache_ocache_fileinfo() - Extrae información sobre los archivos almacenados en el caché opcode
- wincache_ocache_meminfo() - Extrae información sobre la utilización del caché opcode
- wincache_rplist_fileinfo() - Recupera información de la caché sobre una ruta de archivo resuelta
- wincache_refresh_if_changed() - Actualiza las entradas del caché para los archivos almacenados en caché
- wincache_ucache_meminfo() - Recupera información sobre el uso de memoria caché de usuario
- wincache_ucache_info() - Recupera información sobre los datos almacenados en la caché del usuario
- wincache_scache_info() - Recupera información sobre archivos almacenados en el caché de sesión.
- wincache_scache_meminfo() - Recupera información sobre el uso de memoria caché de sesión

# wincache_scache_info

(PECL wincache >= 1.1.0)

wincache_scache_info — Recupera información sobre archivos almacenados en el caché de sesión.

### Descripción

function wincache_scache_info(bool `$summaryonly` = `false`): array|false

Recupera información sobre el contenido del caché de sesión y su utilización.

### Parámetros

`summaryonly`

  Controla si el array devuelto debe contener información sobre entradas individuales del caché además del resumen del caché.

### Valores devueltos

Un array de metadatos sobre el caché para esta sesión o `false` si ocurre un error

El array devuelto por esta función contiene los siguientes elementos:

- `total_cache_uptime` - duración total (en segundos) de activación del caché
- `total_item_count` - número total de elementos contenidos actualmente en el caché
- `is_local_cache` - `true` si los metadatos del caché son para una instancia de caché local, `false` si son para un caché global
- `total_hit_count` - número total de veces que los datos han sido servidos desde el caché
- `total_miss_count` - número total de veces que los datos no se encontraron en el caché

- `scache_entries` - un array que contiene información sobre los elementos almacenados en caché:

  - `key_name` - nombre de la clave usada para almacenar los datos
  - `value_type` - tipo del valor almacenado
  - `use_time` - tiempo, en segundos, desde el último acceso del archivo desde el caché opcode
  - `last_check` - tiempo, en segundos, desde la última vez que el archivo fue verificado para detectar cambios
  - `ttl_seconds` - tiempo restante antes de la eliminación de los datos del caché, 0 significa que nunca serán eliminados
  - `age_seconds` - tiempo transcurrido desde el momento en que se agregaron los datos en la caché
  - `hitcount` - número de veces que los datos han sido servidos desde el caché

### Ejemplos

Ejemplo #1 Ejemplo con wincache_scache_info()

    <pre>
    <?php
    print_r(wincache_scache_info());
    ?>
    </pre>

El ejemplo anterior mostrará:

    Array
    (
        [total_cache_uptime] => 17357
        [total_file_count] => 121
        [total_hit_count] => 36562
        [total_miss_count] => 201
        [scache_entries] => Array
            (
                [1] => Array
                    (
                        [file_name] => c:\inetpub\wwwroot\checkcache.php
                        [add_time] => 17356
                        [use_time] => 7
                        [last_check] => 10
                        [hit_count] => 454
                        [function_count] => 0
                        [class_count] => 1
                    )
                [2] => Array (...iterates for each cached file)
            )
    )

### Ver también

- wincache_fcache_fileinfo() - Extrae información sobre los archivos almacenados en la caché de archivos
- wincache_fcache_meminfo() - Recupera información sobre el uso de memoria caché de ficheros
- wincache_ocache_meminfo() - Extrae información sobre la utilización del caché opcode
- wincache_rplist_fileinfo() - Recupera información de la caché sobre una ruta de archivo resuelta
- wincache_rplist_meminfo() - Recupera información sobre el uso de la memoria por la caché de ruta de archivo resuelta
- wincache_refresh_if_changed() - Actualiza las entradas del caché para los archivos almacenados en caché
- wincache_ucache_meminfo() - Recupera información sobre el uso de memoria caché de usuario
- wincache_ucache_info() - Recupera información sobre los datos almacenados en la caché del usuario
- wincache_scache_meminfo() - Recupera información sobre el uso de memoria caché de sesión

# wincache_scache_meminfo

(PECL wincache >= 1.1.0)

wincache_scache_meminfo — Recupera información sobre el uso de memoria caché de sesión

### Descripción

function wincache_scache_meminfo(): array|false

Recupera información sobre el uso de memoria caché de la sesión.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Array de metadatos sobre el uso de la memoria caché de sesión o `false` si ocurre un error

El array devuelto por esta función contiene los siguientes elementos:

- `memory_total` - cantidad de memoria en bytes asignado para la caché de sesión
- `memory_free` - cantidad de memoria libre en bytes disponible para la caché de sesión
- `num_used_blks` - número de bloques de memoria utilizados por el caché de la sesión
- `num_free_blks` - número de bloques disponibles en la memoria de la caché de sesión
- `memory_overhead` - cantidad de memoria en bytes utilizado para las estructuras de sesión de caché interna

### Ejemplos

Ejemplo #1 Ejemplo de wincache_scache_meminfo()

    <pre>
    <?php
    print_r(wincache_scache_meminfo());
    ?>
    </pre>

El ejemplo anterior mostrará:

    Array
    (
        [memory_total] => 5242880
        [memory_free] => 5215056
        [num_used_blks] => 6
        [num_free_blks] => 3
        [memory_overhead] => 176
    )

### Ver también

- wincache_fcache_fileinfo() - Extrae información sobre los archivos almacenados en la caché de archivos
- wincache_fcache_meminfo() - Recupera información sobre el uso de memoria caché de ficheros
- wincache_ocache_fileinfo() - Extrae información sobre los archivos almacenados en el caché opcode
- wincache_rplist_fileinfo() - Recupera información de la caché sobre una ruta de archivo resuelta
- wincache_rplist_meminfo() - Recupera información sobre el uso de la memoria por la caché de ruta de archivo resuelta
- wincache_refresh_if_changed() - Actualiza las entradas del caché para los archivos almacenados en caché
- wincache_ucache_info() - Recupera información sobre los datos almacenados en la caché del usuario
- wincache_scache_info() - Recupera información sobre archivos almacenados en el caché de sesión.

# wincache_ucache_add

(PECL wincache >= 1.1.0)

wincache_ucache_add — Añade una nueva variable al caché de usuario solo si la variable todavía no existe en el cache

### Descripción

function wincache_ucache_add(string `$key`, mixed `$value`, int `$ttl` = 0): bool
function wincache_ucache_add(array `$values`, mixed `$unused` = NULL, int `$ttl` = 0): bool

Añade una variable al caché de usuario, solo si no existe ya en el caché. La variable permanecerá en el caché mientras no se alcance el tiempo de expiración o hasta que no se elimine con la función wincache_ucache_delete() o la función wincache_ucache_clear().

### Parámetros

`key`

  Almacena la variable usando el nombre `key`. Si una variable correspondiente a la misma clave ya está presente en el caché, la función fallará y devolverá `false`. El parámetro `key` es sensible a mayúsculas y minúsculas. Para sobrescribir este valor, si `key` está presente, use la función wincache_ucache_set() en su lugar. `key` también puede ser un array de pares nombre => valor donde los nombres serán usados como claves. Este formato puede ser usado para añadir múltiples valores en el caché en una sola operación.

`value`

  El valor de la variable a almacenar. El parámetro `Value` soporta todos los tipos de datos, excepto recursos, como punteros de archivos. Este parámetro será ignorado si el primer argumento es un array. Generalmente, se debe pasar el valor `null` al parámetro `value` cuando se usa un array para el parámetro `key`. Si el parámetro `value` es un objeto, o un array que contiene objetos, entonces los objetos serán serializados. Consulte la función __sleep() para más detalles sobre la serialización de objetos.

`values`

  Array asociativo de claves y valores.

`ttl`

  Duración de vida de la variable en el caché, en segundos. Después del tiempo especificado por el parámetro `ttl`, la variable almacenada será eliminada del caché. Este parámetro toma, como valor por defecto, cero (`0`), lo que significa que la variable permanecerá en el caché hasta que no sea explícitamente eliminada usando la función wincache_ucache_delete() o la función wincache_ucache_clear().

### Valores devueltos

Si el parámetro `key` es una string, la función devuelve `true` en caso de éxito, `false` si ocurre un error.

Si el parámetro `key` es un array, la función devuelve:

- Si todas las parejas nombre => valor del array pueden ser definidas, la función devolverá un array vacío;
- Si ninguna de las parejas nombre => valor del array puede ser definida, la función devolverá `false` ;
- Si algunas pueden ser definidas, y otras no, la función devolverá un array de parejas nombre => valor que no han podido ser definidas en el caché de usuario.

### Ejemplos

Ejemplo #1 Ejemplo con wincache_ucache_add() y el parámetro `key` en forma de string

    <?php
    $bar = 'BAR';
    var_dump(wincache_ucache_add('foo', $bar));
    var_dump(wincache_ucache_add('foo', $bar));
    var_dump(wincache_ucache_get('foo'));
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(false)
    string(3) "BAR"

Ejemplo #2 Ejemplo con wincache_ucache_add() y el parámetro `key` en forma de array

    <?php
    $colors_array = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
    var_dump(wincache_ucache_add($colors_array));
    var_dump(wincache_ucache_add($colors_array));
    var_dump(wincache_ucache_get('Blue'));
    ?>

El ejemplo anterior mostrará:

    array(0) { }
    array(4) {
      ["green"]=> int(-1)
      ["Blue"]=> int(-1)
      ["yellow"]=> int(-1)
      ["cyan"]=> int(-1)
    }
    string(1) "6"

### Ver también

- wincache_ucache_set() - Añade una variable a la caché de usuario y sobrescribe la variable si ya existe en la caché
- wincache_ucache_get() - Obtiene una variable almacenada en la caché del usuario
- wincache_ucache_delete() - Elimina las variables de la memoria caché del usuario
- wincache_ucache_clear() - Elimina todo el contenido de la caché del usuario
- wincache_ucache_exists() - Comprueba si una variable existe en la caché del usuario
- wincache_ucache_meminfo() - Recupera información sobre el uso de memoria caché de usuario
- wincache_ucache_info() - Recupera información sobre los datos almacenados en la caché del usuario
- __sleep()

# wincache_ucache_cas

(PECL wincache >= 1.1.0)

wincache_ucache_cas — Compara la variable con el valor antiguo y le asigna un nuevo valor a este

### Descripción

function wincache_ucache_cas(string `$key`, int `$old_value`, int `$new_value`): bool

Compara la variable asociada con la `key` con `old_value` y si coincide entonces asigna el `new_value` a este.

### Parámetros

`key`

  El parámetro `key` que se utiliza para almacenar la variable en la caché. `key` distingue mayúsculas de minúsculas.

`old_value`

  Valor anterior de la variable apuntada por `key` en la memoria caché del usuario. El valor debe ser de tipo `long`, en caso contrario la función devuelve `false`.

`new_value`

  El nuevo valor que se asignará a la variable indicada por la `key` si se encuentra una coincidencia. El valor debe ser de tipo `long`, en caso contrario la función devolverá `false`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Usando wincache_ucache_cas()

    <?php
    wincache_ucache_set('counter', 2922);
    var_dump(wincache_ucache_cas('counter', 2922, 1));
    var_dump(wincache_ucache_get('counter'));
    ?>

El ejemplo anterior mostrará:

    bool(true)
    int(1)

### Ver también

- wincache_ucache_inc() - Incrementa el valor asociado a la clave
- wincache_ucache_dec() - Disminuye el valor asociado a la clave

# wincache_ucache_clear

(PECL wincache >= 1.1.0)

wincache_ucache_clear — Elimina todo el contenido de la caché del usuario

### Descripción

function wincache_ucache_clear(): bool

Borra o elimina todos los valores almacenados en la caché del usuario.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Usando wincache_ucache_clear()

    <?php
    wincache_ucache_set('green', 1);
    wincache_ucache_set('red', 2);
    wincache_ucache_set('orange', 4);
    wincache_ucache_set('blue', 8);
    wincache_ucache_set('cyan', 16);
    $array1 = array('green', 'red', 'orange', 'blue', 'cyan');
    var_dump(wincache_ucache_get($array1));
    var_dump(wincache_ucache_clear());
    var_dump(wincache_ucache_get($array1));
    ?>

El ejemplo anterior mostrará:

    array(5) { ["green"]=> int(1)
               ["red"]=> int(2)
               ["orange"]=> int(4)
               ["blue"]=> int(8)
               ["cyan"]=> int(16) }
    bool(true)
    bool(false)

### Ver también

- wincache_ucache_set() - Añade una variable a la caché de usuario y sobrescribe la variable si ya existe en la caché
- wincache_ucache_add() - Añade una nueva variable al caché de usuario solo si la variable todavía no existe en el cache
- wincache_ucache_delete() - Elimina las variables de la memoria caché del usuario
- wincache_ucache_get() - Obtiene una variable almacenada en la caché del usuario
- wincache_ucache_exists() - Comprueba si una variable existe en la caché del usuario
- wincache_ucache_meminfo() - Recupera información sobre el uso de memoria caché de usuario
- wincache_ucache_info() - Recupera información sobre los datos almacenados en la caché del usuario

# wincache_ucache_dec

(PECL wincache >= 1.1.0)

wincache_ucache_dec — Disminuye el valor asociado a la clave

### Descripción

function wincache_ucache_dec(string `$key`, int `$dec_by` = 1, bool `&$success` = ?): mixed

Disminuye el valor asociado a la `key` por 1 o como se especifica por `dec_by`.

### Parámetros

`key`

  El parámetro `key` que se utiliza para almacenar la variable en la caché. `key` distingue mayúsculas de minúsculas.

`dec_by`

  El valor de la variable asociada por el que conseguirá que `key` disminuya. Si el argumento es un número de punto flotante se truncará al integer más cercano. La variable asociada con la `key` debe ser de tipo `long`, en caso contrario la función falla y devolverá `false`.

`success`

  Será establecido a `true` en caso de éxito y `false` en caso de error.

### Valores devueltos

Devuelve el valor decrementado en caso de éxito y `false` en caso de error.

### Ejemplos

Ejemplo #1 Usando wincache_ucache_dec()

    <?php
    wincache_ucache_set('counter', 1);
    var_dump(wincache_ucache_dec('counter', 2923, $success));
    var_dump($success);
    ?>

El ejemplo anterior mostrará:

    int(2922)
    bool(true)

### Ver también

- wincache_ucache_inc() - Incrementa el valor asociado a la clave
- wincache_ucache_cas() - Compara la variable con el valor antiguo y le asigna un nuevo valor a este

# wincache_ucache_delete

(PECL wincache >= 1.1.0)

wincache_ucache_delete — Elimina las variables de la memoria caché del usuario

### Descripción

function wincache_ucache_delete(mixed `$key`): bool

Elimina los elementos de la caché del usuario apuntado por `key`.

### Parámetros

`key`

  El parámetro `key` que se utiliza para almacenar la variable en la caché. `key` distingue mayúsculas de minúsculas. `key` puede ser un array de claves.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

Si `key` es un array, entonces la función devuelve `false` si cada elemento del array no se borra de la memoria caché del usuario, en caso contrario devuelve un array que consta de todas las claves que se eliminan.

### Ejemplos

Ejemplo #1 Usando wincache_ucache_delete() con `key` como un string

    <?php
    wincache_ucache_set('foo', 'bar');
    var_dump(wincache_ucache_delete('foo'));
    var_dump(wincache_ucache_exists('foo'));
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(false)

Ejemplo #2 Usingwincache_ucache_delete() con `key` como un array

    <?php
    $array1 = array('green' => '5', 'blue' => '6', 'yellow' => '7', 'cyan' => '8');
    wincache_ucache_set($array1);
    $array2 = array('green', 'blue', 'yellow', 'cyan');
    var_dump(wincache_ucache_delete($array2));
    ?>

El ejemplo anterior mostrará:

    array(4) { [0]=> string(5) "green"
               [1]=> string(4) "blue"
               [2]=> string(6) "yellow"
               [3]=> string(4) "cyan" }

Ejemplo #3 Using wincache_ucache_delete() con `key` como un array donde algunos elementos no se pueden eliminar

    <?php
    $array1 = array('green' => '5', 'blue' => '6', 'yellow' => '7', 'cyan' => '8');
    wincache_ucache_set($array1);
    $array2 = array('orange', 'red', 'yellow', 'cyan');
    var_dump(wincache_ucache_delete($array2));
    ?>

El ejemplo anterior mostrará:

    array(2) { [0]=> string(6) "yellow"
               [1]=> string(4) "cyan" }

### Ver también

- wincache_ucache_set() - Añade una variable a la caché de usuario y sobrescribe la variable si ya existe en la caché
- wincache_ucache_add() - Añade una nueva variable al caché de usuario solo si la variable todavía no existe en el cache
- wincache_ucache_get() - Obtiene una variable almacenada en la caché del usuario
- wincache_ucache_clear() - Elimina todo el contenido de la caché del usuario
- wincache_ucache_exists() - Comprueba si una variable existe en la caché del usuario
- wincache_ucache_meminfo() - Recupera información sobre el uso de memoria caché de usuario
- wincache_ucache_info() - Recupera información sobre los datos almacenados en la caché del usuario

# wincache_ucache_exists

(PECL wincache >= 1.1.0)

wincache_ucache_exists — Comprueba si una variable existe en la caché del usuario

### Descripción

function wincache_ucache_exists(string `$key`): bool

Comprueba si una variable con la `key` existe en la caché de usuario o no.

### Parámetros

`key`

  La `key` que se utiliza para almacenar la variable en la caché. `key` distingue mayúsculas de minúsculas.

### Valores devueltos

Devuelve `true` si la variable con la `key` existe, en caso contrario devuelve `false`.

### Ejemplos

Ejemplo #1 Usando wincache_ucache_exists()

    <?php
    if (!wincache_ucache_exists('green'))
        wincache_ucache_set('green', 1);
    var_dump(wincache_ucache_exists('green'));
    ?>

El ejemplo anterior mostrará:

    bool(true)

### Ver también

- wincache_ucache_set() - Añade una variable a la caché de usuario y sobrescribe la variable si ya existe en la caché
- wincache_ucache_add() - Añade una nueva variable al caché de usuario solo si la variable todavía no existe en el cache
- wincache_ucache_get() - Obtiene una variable almacenada en la caché del usuario
- wincache_ucache_clear() - Elimina todo el contenido de la caché del usuario
- wincache_ucache_delete() - Elimina las variables de la memoria caché del usuario
- wincache_ucache_meminfo() - Recupera información sobre el uso de memoria caché de usuario
- wincache_ucache_info() - Recupera información sobre los datos almacenados en la caché del usuario

# wincache_ucache_get

(PECL wincache >= 1.1.0)

wincache_ucache_get — Obtiene una variable almacenada en la caché del usuario

### Descripción

function wincache_ucache_get(mixed `$key`, bool `&$success` = ?): mixed

Obtiene una variable almacenada en la caché del usuario.

### Parámetros

`key`

  La `key` que se utiliza para almacenar la variable en la caché. `key` distingue mayúsculas de minúsculas. `key` puede ser un array de claves. En este caso el valor de retorno será un array de valores de cada elemento en el array `key`. Si un objeto, o un array que contiene objetos, es retornado, entonces los objetos serán decodificados. Véase __wakeup() para más detalles sobre decodificar objetos.

`success`

  Se establecerá en `true` en caso de éxito y `false` en caso de error.

### Valores devueltos

Si `key` es un string, la función devuelve el valor de la variable almacenada con esa clave. El parámetro `success` es establecido a `true` en caso de éxito y a `false` en caso de error.

El parámetro `key` es un array, el parámetro `success` siempre se establece en `true`. El array devuelto (pares nombre => valor) contendrá sólo aquellos pares nombre => valor en donde la operación de obtención de caché de usuario se ha realizado correctamente. Si ninguna de las claves del array encuentran una coincidencia en la caché del usuario, un array vacío será devuelto.

### Ejemplos

Ejemplo #1 wincache_ucache_get() con `key` como un string

    <?php
    wincache_ucache_add('color', 'blue');
    var_dump(wincache_ucache_get('color', $success));
    var_dump($success);
    ?>

El ejemplo anterior mostrará:

    string(4) "blue"
    bool(true)

Ejemplo #2 wincache_ucache_get() con `key` como un array

    <?php
    $array1 = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
    wincache_ucache_set($array1);
    $array2 = array('green', 'Blue', 'yellow', 'cyan');
    var_dump(wincache_ucache_get($array2, $success));
    var_dump($success);
    ?>

El ejemplo anterior mostrará:

    array(4) { ["green"]=> string(1) "5"
               ["Blue"]=> string(1) "6"
               ["yellow"]=> string(1) "7"
               ["cyan"]=> string(1) "8" }
    bool(true)

### Ver también

- wincache_ucache_add() - Añade una nueva variable al caché de usuario solo si la variable todavía no existe en el cache
- wincache_ucache_set() - Añade una variable a la caché de usuario y sobrescribe la variable si ya existe en la caché
- wincache_ucache_delete() - Elimina las variables de la memoria caché del usuario
- wincache_ucache_clear() - Elimina todo el contenido de la caché del usuario
- wincache_ucache_exists() - Comprueba si una variable existe en la caché del usuario
- wincache_ucache_meminfo() - Recupera información sobre el uso de memoria caché de usuario
- wincache_ucache_info() - Recupera información sobre los datos almacenados en la caché del usuario
- __wakeup()

# wincache_ucache_inc

(PECL wincache >= 1.1.0)

wincache_ucache_inc — Incrementa el valor asociado a la clave

### Descripción

function wincache_ucache_inc(string `$key`, int `$inc_by` = 1, bool `&$success` = ?): mixed

Incrementa el valor asociado a la `key` por 1 o como se especifica por `inc_by`.

### Parámetros

`key`

  La `key` que se utiliza para almacenar la variable en la caché. `key` distingue mayúsculas de minúsculas.

`inc_by`

  El valor por el cual la variable asociada con la `key` será incrementada. Si el argumento es un número de punto flotante se truncará al integer más cercano. La variable asociada con la `key` debe ser de tipo `long`, de lo contrario la función falla y devuelve `false`.

`success`

  Se establecerá en `true` en caso de éxito y `false` en caso de error.

### Valores devueltos

Devuelve el valor incrementado en caso de éxito y `false` en caso de error.

### Ejemplos

Ejemplo #1 Usando wincache_ucache_inc()

    <?php
    wincache_ucache_set('counter', 1);
    var_dump(wincache_ucache_inc('counter', 2921, $success));
    var_dump($success);
    ?>

El ejemplo anterior mostrará:

    int(2922)
    bool(true)

### Ver también

- wincache_ucache_dec() - Disminuye el valor asociado a la clave
- wincache_ucache_cas() - Compara la variable con el valor antiguo y le asigna un nuevo valor a este

# wincache_ucache_info

(PECL wincache >= 1.1.0)

wincache_ucache_info — Recupera información sobre los datos almacenados en la caché del usuario

### Descripción

function wincache_ucache_info(bool `$summaryonly` = `false`, string `$key` = NULL): array|false

Recupera información sobre los datos almacenados en la caché del usuario.

### Parámetros

`summaryonly`

  Controla si el array devuelto contiene información sobre las entradas de caché individuales junto con el resumen caché del usuario.

`key`

  La clave de una entrada en la caché del usuario. Si se especifica a continuación, el array devuelto contendrá información sólo acerca de que la entrada de caché. Si no se especifica y `summaryonly` es establecido a `false` entonces el array devuelto contendrá información sobre todas las entradas en la caché.

### Valores devueltos

Array de metadatos sobre caché de usuario o `false` si ocurre un error

El array devuelto por esta función contiene los siguientes elementos:

- `total_cache_uptime` - tiempo total en segundos que el caché de usuario ha sido activo
- `total_item_count` - número total de elementos que están actualmente en la caché del usuario
- `is_local_cache` - true si el caché es de metadatos para una instancia de caché local, false si los metadatos es para el la caché global
- `total_hit_count` - número de veces que los datos se han servido de la memoria caché
- `total_miss_count` - número de veces que los datos no se han encontrado en la caché

- `ucache_entries` - un array que contiene la información sobre todos los elementos almacenados en caché:

  - `key_name` - nombre de la clave que se utiliza para almacenar los datos
  - `value_type` - tipo de valor almacenado por la clave
  - `use_time` - tiempo en segundos desde el fichero ha sido visitado en la caché de código de operación
  - `last_check` - tiempo en segundos desde el fichero ha sido chequeado para modificaciones
  - `is_session` - indica si los datos son una variable de sesión
  - `ttl_seconds` - el tiempo restante de los datos a vivir en la memoria caché, 0 significa infinito
  - `age_seconds` - tiempo transcurrido desde el momento que los datos han sido añadidos en la caché
  - `hitcount` - número de veces que los datos se han servido de la memoria caché

### Ejemplos

Ejemplo #1 Usar wincache_ucache_info()

    <?php
    wincache_ucache_get('green');
    wincache_ucache_set('green', 2922);
    wincache_ucache_get('green');
    wincache_ucache_get('green');
    wincache_ucache_get('green');
    print_r(wincache_ucache_info());
    ?>

El ejemplo anterior mostrará:

    Array
    ( ["total_cache_uptime"] => int(0)
      ["is_local_cache"] => bool(false)
      ["total_item_count"] => int(1)
      ["total_hit_count"] => int(3)
      ["total_miss_count"] => int(1)
      ["ucache_entries"] => Array(1)
        ( [1] => Array(6)
          (
            ["key_name"] => string(5) "green"
            ["value_type"] => string(4) "long"
            ["is_session"] => int(0)
            ["ttl_seconds"] => int(0)
            ["age_seconds"] => int(0)
            ["hitcount"] => int(3)
           )
        )
    )

### Ver también

- wincache_fcache_meminfo() - Recupera información sobre el uso de memoria caché de ficheros
- wincache_ocache_fileinfo() - Extrae información sobre los archivos almacenados en el caché opcode
- wincache_ocache_meminfo() - Extrae información sobre la utilización del caché opcode
- wincache_rplist_meminfo() - Recupera información sobre el uso de la memoria por la caché de ruta de archivo resuelta
- wincache_rplist_fileinfo() - Recupera información de la caché sobre una ruta de archivo resuelta
- wincache_refresh_if_changed() - Actualiza las entradas del caché para los archivos almacenados en caché
- wincache_ucache_meminfo() - Recupera información sobre el uso de memoria caché de usuario
- wincache_scache_info() - Recupera información sobre archivos almacenados en el caché de sesión.
- wincache_scache_meminfo() - Recupera información sobre el uso de memoria caché de sesión

# wincache_ucache_meminfo

(PECL wincache >= 1.1.0)

wincache_ucache_meminfo — Recupera información sobre el uso de memoria caché de usuario

### Descripción

function wincache_ucache_meminfo(): array|false

Recupera información sobre el uso de memoria caché del usuario.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Array de metadatos sobre el uso de la memoria caché de usuario o `false` si ocurre un error

El array devuelto por esta función contiene los siguientes elementos:

- `memory_total` - cantidad de memoria en bytes asignado para la caché de usuario
- `memory_free` - cantidad de memoria libre en bytes disponible para la caché de usuario
- `num_used_blks` - número de bloques de memoria utilizados por el caché del usuario
- `num_free_blks` - número de bloques disponibles en la memoria de la caché del usuario
- `memory_overhead` - cantidad de memoria en bytes utilizado para las estructuras de los usuarios de caché interna

### Ejemplos

Ejemplo #1 Ejemplo de wincache_ucache_meminfo()

    <pre>
    <?php
    print_r(wincache_ucache_meminfo());
    ?>
    </pre>

El ejemplo anterior mostrará:

    Array
    (
        [memory_total] => 5242880
        [memory_free] => 5215056
        [num_used_blks] => 6
        [num_free_blks] => 3
        [memory_overhead] => 176
    )

### Ver también

- wincache_fcache_fileinfo() - Extrae información sobre los archivos almacenados en la caché de archivos
- wincache_fcache_meminfo() - Recupera información sobre el uso de memoria caché de ficheros
- wincache_ocache_fileinfo() - Extrae información sobre los archivos almacenados en el caché opcode
- wincache_rplist_fileinfo() - Recupera información de la caché sobre una ruta de archivo resuelta
- wincache_rplist_meminfo() - Recupera información sobre el uso de la memoria por la caché de ruta de archivo resuelta
- wincache_refresh_if_changed() - Actualiza las entradas del caché para los archivos almacenados en caché
- wincache_ucache_info() - Recupera información sobre los datos almacenados en la caché del usuario
- wincache_scache_info() - Recupera información sobre archivos almacenados en el caché de sesión.
- wincache_scache_meminfo() - Recupera información sobre el uso de memoria caché de sesión

# wincache_ucache_set

(PECL wincache >= 1.1.0)

wincache_ucache_set — Añade una variable a la caché de usuario y sobrescribe la variable si ya existe en la caché

### Descripción

function wincache_ucache_set(mixed `$key`, mixed `$value`, int `$ttl` = 0): bool
function wincache_ucache_set(array `$values`, mixed `$unused` = NULL, int `$ttl` = 0): bool

Añade una variable a la caché de usuario. Sobrescribe una variable si ya existe en la caché. La variable así creada o actualizada permanecerá en la caché de usuario mientras no se alcance el tiempo de expiración o hasta que no se elimine con la función wincache_ucache_delete() o la función wincache_ucache_clear().

### Parámetros

`key`

  Almacena la variable usando la clave `key`. Si una variable usando la misma clave `key` ya está presente, la función sobrescribirá el valor anterior con el nuevo. El parámetro `key` es sensible a mayúsculas y minúsculas. `key` también puede ser un array de pares nombre => valor donde los nombres serán usados como claves. Esto puede ser útil para añadir múltiples valores en la caché en una sola operación, evitando así las condiciones de carrera.

`value`

  Valor de la variable a almacenar. El parámetro `Value` soporta todos los tipos de datos, excepto recursos, como punteros de archivos. Este parámetro es ignorado si el primer argumento es un array. Es convención pasar `null` como `value` cuando se usa un array en el parámetro `key`. Si el parámetro `value` es un objeto, o un array que contiene objetos, entonces todos los objetos serán serializados. Consulte la función __sleep() para más detalles sobre la serialización de objetos.

`values`

  Array asociativo de claves y valores.

`ttl`

  Tiempo de vida de la variable en la caché, en segundos. Después del tiempo especificado por el parámetro `ttl`, la variable almacenada será eliminada de la caché de usuario. Este parámetro toma por defecto el valor cero (`0`), lo que significa que la variable permanecerá en la caché hasta que no sea explícitamente eliminada llamando a la función wincache_ucache_delete() o la función wincache_ucache_clear().

### Valores devueltos

Si `key` es un string, la función devolverá `true` en caso de éxito, `false` si ocurre un error.

Si `key` es un array, la función devolverá:

- Si todas las parejas nombre => valor del array han podido ser definidas, la función devolverá un array vacío.
- Si ninguna de las parejas nombre => valor del array ha podido ser definida, la función devolverá `false`.
- Si algunas parejas han sido definidas, y otras no, la función devolverá un array de parejas nombre => valor que no han podido ser definidas en la caché de usuario.

### Ejemplos

Ejemplo #1 Ejemplo con wincache_ucache_set() y el parámetro `key` en forma de string

    <?php
    $bar = 'BAR';
    var_dump(wincache_ucache_set('foo', $bar));
    var_dump(wincache_ucache_get('foo'));
    $bar1 = 'BAR1';
    var_dump(wincache_ucache_set('foo', $bar1));
    var_dump(wincache_ucache_get('foo'));
    ?>

El ejemplo anterior mostrará:

    bool(true)
    string(3) "BAR"
    bool(true)
    string(3) "BAR1"

Ejemplo #2 Ejemplo con wincache_ucache_set() y el parámetro `key` en forma de array

    <?php
    $colors_array = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
    var_dump(wincache_ucache_set($colors_array));
    var_dump(wincache_ucache_set($colors_array));
    var_dump(wincache_ucache_get('Blue'));
    ?>

El ejemplo anterior mostrará:

    array(0) {}
    array(0) {}
    string(1) "6"

### Ver también

- wincache_ucache_add() - Añade una nueva variable al caché de usuario solo si la variable todavía no existe en el cache
- wincache_ucache_get() - Obtiene una variable almacenada en la caché del usuario
- wincache_ucache_delete() - Elimina las variables de la memoria caché del usuario
- wincache_ucache_clear() - Elimina todo el contenido de la caché del usuario
- wincache_ucache_exists() - Comprueba si una variable existe en la caché del usuario
- wincache_ucache_meminfo() - Recupera información sobre el uso de memoria caché de usuario
- wincache_ucache_info() - Recupera información sobre los datos almacenados en la caché del usuario
- __sleep()

# wincache_unlock

(PECL wincache >= 1.1.0)

wincache_unlock — Libera un bloqueo exclusivo sobre una clave dada

### Descripción

function wincache_unlock(string `$key`): bool

Libera un bloqueo exclusivo que se obtuvo en una clave dada mediante wincache_lock(). Si cualquier otro proceso fue bloqueado en espera de el bloqueo en esta clave, este proceso será capaz de obtener el bloqueo.

Advertencia

Usando wincache_lock() y wincache_unlock() puede causar bloqueos al ejecutar los scripts PHP en un entorno de multi-proceso, como FastCGI. No utilice estas funciones a menos que esté absolutamente seguro de que necesitan para su uso. Para la mayoría de las operaciones en la caché de usuario no es necesario el uso de estas funciones.

### Parámetros

`key`

  Nombre de la llave en la caché para liberar el bloqueo.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Usar wincache_unlock()

    <?php
    $fp = fopen("/tmp/lock.txt", "r+");
    if (wincache_lock(“lock_txt_lock”)) { // hacer un bloqueo exclusivo
        ftruncate($fp, 0); // truncate file
        fwrite($fp, "Escribir algo aquí\n");
        wincache_unlock(“lock_txt_lock”); // liberar el bloqueo
    } else {
        echo "No se pudo obtener el bloqueo!";
    }
    fclose($fp);
    ?>

### Ver también

- wincache_lock() - Obtiene un bloqueo exclusivo en una clave dada
- wincache_ucache_set() - Añade una variable a la caché de usuario y sobrescribe la variable si ya existe en la caché
- wincache_ucache_get() - Obtiene una variable almacenada en la caché del usuario
- wincache_ucache_delete() - Elimina las variables de la memoria caché del usuario
- wincache_ucache_clear() - Elimina todo el contenido de la caché del usuario
- wincache_ucache_exists() - Comprueba si una variable existe en la caché del usuario
- wincache_ucache_meminfo() - Recupera información sobre el uso de memoria caché de usuario
- wincache_ucache_info() - Recupera información sobre los datos almacenados en la caché del usuario
- wincache_scache_info() - Recupera información sobre archivos almacenados en el caché de sesión.

## Tabla de contenidos

- wincache_fcache_fileinfo — Extrae información sobre los archivos almacenados en la caché de archivos
- wincache_fcache_meminfo — Recupera información sobre el uso de memoria caché de ficheros
- wincache_lock — Obtiene un bloqueo exclusivo en una clave dada
- wincache_ocache_fileinfo — Extrae información sobre los archivos almacenados en el caché opcode
- wincache_ocache_meminfo — Extrae información sobre la utilización del caché opcode
- wincache_refresh_if_changed — Actualiza las entradas del caché para los archivos almacenados en caché
- wincache_rplist_fileinfo — Recupera información de la caché sobre una ruta de archivo resuelta
- wincache_rplist_meminfo — Recupera información sobre el uso de la memoria por la caché de ruta de archivo resuelta
- wincache_scache_info — Recupera información sobre archivos almacenados en el caché de sesión.
- wincache_scache_meminfo — Recupera información sobre el uso de memoria caché de sesión
- wincache_ucache_add — Añade una nueva variable al caché de usuario solo si la variable todavía no existe en el cache
- wincache_ucache_cas — Compara la variable con el valor antiguo y le asigna un nuevo valor a este
- wincache_ucache_clear — Elimina todo el contenido de la caché del usuario
- wincache_ucache_dec — Disminuye el valor asociado a la clave
- wincache_ucache_delete — Elimina las variables de la memoria caché del usuario
- wincache_ucache_exists — Comprueba si una variable existe en la caché del usuario
- wincache_ucache_get — Obtiene una variable almacenada en la caché del usuario
- wincache_ucache_inc — Incrementa el valor asociado a la clave
- wincache_ucache_info — Recupera información sobre los datos almacenados en la caché del usuario
- wincache_ucache_meminfo — Recupera información sobre el uso de memoria caché de usuario
- wincache_ucache_set — Añade una variable a la caché de usuario y sobrescribe la variable si ya existe en la caché
- wincache_unlock — Libera un bloqueo exclusivo sobre una clave dada

# Compilación en Windows

## Tabla de contenidos

- Prerrequisitos
- Compilar y construir
- Verificar la compilación

## Prerrequisitos

Para compilar la extensión WinCache, se necesitará:

1. el código fuente de PHP
2. un entorno de compilación PHP
3. el código fuente de WinCache

Para completar los dos primeros pasos, siga la guía paso a paso » Compilar PHP en Windows.

Para obtener el código fuente de WinCache, siga las instrucciones descritas en Descargar extensiones PECL.

## Compilar y construir

Los siguientes pasos describen cómo compilar y construir WinCache en Windows:

1. Abra una ventana de comandos utilizada para compilar PHP

2. Vaya al directorio raíz donde se encuentran las fuentes de PHP

3. Ejecute el comando:

       cscript.exe win32\build\buildconf.js

4. Ejecute el comando:

       configure.bat --help

   La salida contendrá una nueva opción `--enable-wincache`.

5. Ejecute el comando:

       configure.js [todas las opciones usadas para compilar PHP] --enable-wincache

   `--enable-wincache` es la única opción adicional requerida para asegurarse de que la extensión WinCache se compile correctamente. Esta opción permite construir WinCache y enlazarlo estáticamente con la DLL de PHP. Para construir la extensión como una DLL externa, use la opción `--enable-wincache=shared`.

6. Ejecute el comando:

       nmake

## Verificar la compilación

Los siguientes pasos describen cómo verificar que WinCache se ha compilado correctamente:

1. Vaya al directorio donde se construyen los archivos PHP.

2. Ejecute el comando:

       php.exe -n -d extension=php_wincache.dll -re wincache

   Si WinCache se ha compilado correctamente, la salida de este comando listará las directivas INI y las funciones soportadas por WinCache.

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
  - Script de estadísticas WinCache
  - Manejador de sesiones WinCache
  - Redirecciones de funciones WinCache
- Funciones de WinCache
  - wincache_fcache_fileinfo — Extrae información sobre los archivos almacenados en la caché de archivos
  - wincache_fcache_meminfo — Recupera información sobre el uso de memoria caché de ficheros
  - wincache_lock — Obtiene un bloqueo exclusivo en una clave dada
  - wincache_ocache_fileinfo — Extrae información sobre los archivos almacenados en el caché opcode
  - wincache_ocache_meminfo — Extrae información sobre la utilización del caché opcode
  - wincache_refresh_if_changed — Actualiza las entradas del caché para los archivos almacenados en caché
  - wincache_rplist_fileinfo — Recupera información de la caché sobre una ruta de archivo resuelta
  - wincache_rplist_meminfo — Recupera información sobre el uso de la memoria por la caché de ruta de archivo resuelta
  - wincache_scache_info — Recupera información sobre archivos almacenados en el caché de sesión.
  - wincache_scache_meminfo — Recupera información sobre el uso de memoria caché de sesión
  - wincache_ucache_add — Añade una nueva variable al caché de usuario solo si la variable todavía no existe en el cache
  - wincache_ucache_cas — Compara la variable con el valor antiguo y le asigna un nuevo valor a este
  - wincache_ucache_clear — Elimina todo el contenido de la caché del usuario
  - wincache_ucache_dec — Disminuye el valor asociado a la clave
  - wincache_ucache_delete — Elimina las variables de la memoria caché del usuario
  - wincache_ucache_exists — Comprueba si una variable existe en la caché del usuario
  - wincache_ucache_get — Obtiene una variable almacenada en la caché del usuario
  - wincache_ucache_inc — Incrementa el valor asociado a la clave
  - wincache_ucache_info — Recupera información sobre los datos almacenados en la caché del usuario
  - wincache_ucache_meminfo — Recupera información sobre el uso de memoria caché de usuario
  - wincache_ucache_set — Añade una variable a la caché de usuario y sobrescribe la variable si ya existe en la caché
  - wincache_unlock — Libera un bloqueo exclusivo sobre una clave dada
- Compilación en Windows
  - Prerrequisitos
  - Compilar y construir
  - Verificar la compilación

# Perfilador jerárquico

# Introducción

El XHProf es un perfilador ligero jerárquico y basado en la instrumentación. Durante la fase de recopilación de datos, lleva un registro de los recuentos de llamadas e incluso métricas para los arcos en el calibre dinámico de un programa. Calcula las exclusivas métricas en la fase de reporte/procesamiento posterior, como el tiempo de espera (transcurrido), El tiempo de la CPU y el uso de la memoria. Un perfil de funciones puede ser dividido por los llamantes o llamadas. El XHProf maneja funciones recursivas detectando ciclos en la caligrafía en el propio momento de la recogida de datos y evitar los ciclos dando nombres calificados de profundidad para las invocaciones recursivas.

XHProf incluye una sencilla interfaz de usuario basada en HTML (escrita en PHP). El navegador basado en La interfaz de usuario para ver los resultados de los perfiles hace que sea fácil ver los resultados o compartirlos. con los compañeros. También se admite una vista de imagen de caligrafía.

Los informes del XHProf a menudo pueden ser útiles para entender la estructura del código siendo ejecutado. La naturaleza jerárquica de los informes puede ser utilizada para determinar, por ejemplo, qué cadena de llamadas llevó a que se llamara a una función en particular.

El XHProf permite comparar dos ejecuciones (también conocidas como informes "diff") o agregar datos de múltiples ejecuciones. Informes diferenciales y agregados, muy parecidos a los informes de una sola ejecución, ofrecen vistas "planas" y "jerárquicas" del perfil.

Se puede encontrar documentación adicional a través del sitio » facebook xhprof.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución

## Requerimientos

Aunque no es obligatorio, xhprof incluye una interfaz que está escrito en PHP. Se utiliza para guardar y mostrar los datos reseñados en una forma utilizable, donde la observación se realiza mediante un navegador web. Por lo tanto, un servidor web PHP activado probablemente mejorará la experiencia xhprof.

También hay un "fork" (bifurcación del desarrollo) de la interfaz gráfica de usuario en » http://github.com/preinheimer/xhprof

## Instalación

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/xhprof

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Xhprof Opciones de configuración
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
xhprof.output_dir | "" | `INI_ALL` |

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`xhprof.output_dir` string

  Directorio utilizado por la aplicación por defecto de la interfaz iXHProfRuns (es decir, la clase XHProfRuns_Default) para el almacenamiento XHProf.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`XHPROF_FLAGS_NO_BUILTINS` (int)
  Se utiliza para saltar todas las funciones incorporadas (internas)
`XHPROF_FLAGS_CPU` (int)
  Se utiliza para agregar información de la CPU a la salida.
`XHPROF_FLAGS_MEMORY` (int)
  Se utiliza para agregar información de la memoria a la salida.

# Ejemplos

Ejemplo #1 Ejemplo Xhprof con interfaz gráfica de usuario opcional

En este ejemplo se inicia y detiene el perfilador, a continuación, utiliza interfaz gráfica de usuario para guardar y analizar los resultados. En otras palabras, el código de la extensión se termina en la llamada a xhprof_disable() .

    <?php
    xhprof_enable(XHPROF_FLAGS_CPU + XHPROF_FLAGS_MEMORY);

    for ($i = 0; $i <= 1000; $i++) {
        $a = $i * $i;
    }

    $xhprof_data = xhprof_disable();

    $XHPROF_ROOT = "/tools/xhprof/";
    include_once $XHPROF_ROOT . "/xhprof_lib/utils/xhprof_lib.php";
    include_once $XHPROF_ROOT . "/xhprof_lib/utils/xhprof_runs.php";

    $xhprof_runs = new XHProfRuns_Default();
    $run_id = $xhprof_runs->save_run($xhprof_data, "xhprof_testing");

    echo "http://localhost/xhprof/xhprof_html/index.php?run={$run_id}&source=xhprof_testing\n";

    ?>

Resultado del ejemplo anterior es similar a:

    http://localhost/xhprof/xhprof_html/index.php?run=t11_4bdf44d21121f&source=xhprof_testing

# Xhprof Funciones

# xhprof_disable

(PECL xhprof >= 0.9.0)

xhprof_disable — Detiene el perfilado xhprof

### Descripción

function xhprof_disable(): ?array

Detiene el perfilado y devuelve los datos xhprof correspondientes a su ejecución.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array de datos xhprof, procedentes de su ejecución. Devuelve `null` si el perfilado no está activado.

### Ejemplos

Ejemplo #1 Ejemplo con xhprof_disable()

    <?php
    xhprof_enable();

    $foo = strlen("foo bar");

    $xhprof_data = xhprof_disable();

    print_r($xhprof_data);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [main()==>strlen] => Array
            (
                [ct] => 1
                [wt] => 279
            )

        [main()==>xhprof_disable] => Array
            (
                [ct] => 1
                [wt] => 9
            )

        [main()] => Array
            (
                [ct] => 1
                [wt] => 610
            )

    )

# xhprof_enable

(PECL xhprof >= 0.9.0)

xhprof_enable — Inicia perfil xhprof

### Descripción

function xhprof_enable(int `$flags` = 0, array `$options` = ?): void

Inicia perfiles xhprof.

### Parámetros

`flags`

  Flags opcionales para añadir información adicional a la creación de perfiles. Véase las constantes XHprof Para obtener más información acerca de estos flags, p. ej., `XHPROF_FLAGS_MEMORY` para permitir perfiles de memoria.

`options`

  Un array de opciones opcionales, es decir, la opción 'ignored_functions' para pasar en las funciones que se ignoraron durante el perfilado.

### Valores devueltos

`null`

### Historial de cambios

Versión | Descripción
--- | ---
PECL xhprof 0.9.2 | El parámetro opcional `options` fué agregado.

### Ejemplos

Ejemplo #1 Ejemplos de xhprof_enable()

    <?php
    // 1. tiempo transcurrido + memoria + perfiles CPU; e ignorar las funciones integradas (internas)
    xhprof_enable(XHPROF_FLAGS_NO_BUILTINS | XHPROF_FLAGS_CPU | XHPROF_FLAGS_MEMORY);

    // 2. perfil tiempo transcurrido; ignorando call_user_func* durante el perfilado
    xhprof_enable(
        0,
        array('ignored_functions' =>  array('call_user_func',
                                            'call_user_func_array')));

    // 3. tiempo transcurrido + perfil de memoria; ignorando call_user_func* durante el perfilado
    xhprof_enable(
        XHPROF_FLAGS_MEMORY,
        array('ignored_functions' =>  array('call_user_func',
                                            'call_user_func_array')));
    ?>

### Ver también

- xhprof_disable() - Detiene el perfilado xhprof
- xhprof_sample_enable() - Iniciar el analisis de XHProf en modo de muestreo
- memory_get_usage() - Indica la cantidad de memoria utilizada por PHP
- getrusage() - Devuelve el nivel de utilización de los recursos

# xhprof_sample_disable

(PECL xhprof >= 0.9.0)

xhprof_sample_disable — Detiene el perfilado xhprof por muestreo

### Descripción

function xhprof_sample_disable(): ?array

Detiene el perfilado xhprof por muestreo y devuelve la información de perfilado.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array de datos de muestreo xhprof, procedentes de su ejecución. Devuelve `null` si el perfilado no está activado.

### Ejemplos

Ejemplo #1 Ejemplo con xhprof_sample_disable()

    <?php
    xhprof_sample_enable();

    for ($i = 0; $i <= 10000; $i++) {
        $a = strlen($i);
        $b = $i * $a;
        $c = rand();
    }

    $xhprof_data = xhprof_sample_disable();

    print_r($xhprof_data);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [1272935300.800000] => main()
        [1272935300.900000] => main()
    )

# xhprof_sample_enable

(PECL xhprof >= 0.9.0)

xhprof_sample_enable — Iniciar el analisis de XHProf en modo de muestreo

### Descripción

function xhprof_sample_enable(): void

Inicia la creación de perfiles en modo de muestra, que es una versión más ligera de peso de xhprof_enable() . El intervalo de muestreo es 0,1 segundos, y las muestras de registro de la pila de llamadas de función completa. El caso de uso principal es en gastos indirectos más bajos se requiere cuando se hace la supervisión del rendimiento y de diagnóstico.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

`null`

### Ver también

- xhprof_sample_disable() - Detiene el perfilado xhprof por muestreo
- xhprof_enable() - Inicia perfil xhprof
- memory_get_usage() - Indica la cantidad de memoria utilizada por PHP
- getrusage() - Devuelve el nivel de utilización de los recursos

## Tabla de contenidos

- xhprof_disable — Detiene el perfilado xhprof
- xhprof_enable — Inicia perfil xhprof
- xhprof_sample_disable — Detiene el perfilado xhprof por muestreo
- xhprof_sample_enable — Iniciar el analisis de XHProf en modo de muestreo

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
- Constantes predefinidas
- Ejemplos
- Xhprof Funciones
  - xhprof_disable — Detiene el perfilado xhprof
  - xhprof_enable — Inicia perfil xhprof
  - xhprof_sample_disable — Detiene el perfilado xhprof por muestreo
  - xhprof_sample_enable — Iniciar el analisis de XHProf en modo de muestreo

# Yac

# Introducción

Yac (Otro caché), es un caché de datos de usuario de memoria compartida sin bloqueo, podría utilizarse para reemplazar el APC, el memcache local.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución
- Tipos de recursos

## Requerimientos

## Instalación

Esta extensión » PECL no está integrada en PHP.

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/yac.

Los binarios Windows (los archivos DLL) para esta extensión PECL están disponibles en el sitio web PECL.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Yac Opciones de configuración
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
yac.compress_threshold | -1 | `INI_SYSTEM` |
yac.debug | 0 | `INI_ALL` |
yac.enable | 1 | `INI_SYSTEM` |
yac.enable_cli | 0 | `INI_SYSTEM` |
yac.keys_memory_size | 4M | `INI_SYSTEM` |
yac.serializer | php | `INI_SYSTEM` |
yac.values_memory_size | 64M | `INI_SYSTEM` |

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`yac.compress_threshold` int

`yac.debug` int

`yac.enable` int

`yac.enable_cli` int

`yac.keys_memory_size` string

`yac.serializer` string

`yac.values_memory_size` string

## Tipos de recursos

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`YAC_VERSION` (string)
`YAC_MAX_KEY_LEN` (int)
  La longitud máxima de una clave podría ser, es de 48 bytes.
`YAC_MAX_VALUE_RAW_LEN` (int)
`YAC_MAX_RAW_COMPRESSED_LEN` (int)
`YAC_SERIALIZER_PHP` (int)
  Usa php serialize como serializador
`YAC_SERIALIZER_JSON` (int)
  Usa json como serializador (requrie --enable-json)
`YAC_SERIALIZER_IGBINARY` (int)
  Usa igbinary como serializador (require --enable-igbinary)
`YAC_SERIALIZER_MSGPACK` (int)
  Usa msgpack como serializador (require --enable-msgpack)
`YAC_SERIALIZER` (string)
  Qué serializador está yac usando

# La clase Yac

(PECL yac >= 1.0.0)

## Introducción

## Sinopsis de la Clase

class Yac {
/* Propiedades */
protected $_prefix;
/* Métodos */
public function __construct(string `$prefix` = "")
public function add(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function add(array `$key_vals`): bool
public function delete(string|array `$keys`, int `$ttl` = ?): bool
public function dump(int `$$num`): mixed
public function flush(): bool
public function get(string|array `$key`, int `&$cas` = `null`): mixed
public function __get(string `$key`): mixed
public function info(): array
public function set(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function add(array `$key_vals`): bool
public function __set(string `$keys`, mixed `$value`): mixed
}

## Propiedades

_prefix

# Yac::add

(PECL yac >= 1.0.0)

Yac::add — Guardar en caché

### Descripción

public function Yac::add(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function Yac::add(array `$key_vals`): bool

Añadir un artículo al caché.

### Parámetros

`keys`

  string clave

`value`

  valor mixto, Todo tipo de valor php podría ser almacenado excepto resource

`ttl`

  tiempo de expiración

### Valores devueltos

bool, `true` en caso de éxito, `false` en caso de fallar.

> Nota:

> Yac::add() puede fallar si el casillero no se puede obtener, así que, si necesitas que el valor se almacene correctamente, puedes escribir códigos como:

> Ejemplo #1 Asegúrate de que el artículo se almacene

>     while(!$yac->set("key", "value"));

# Yac::__construct

(PECL yac >= 1.0.0)

Yac::__construct — Constructor

### Descripción

public function Yac::__construct(string `$prefix` = "")

se utiliza un prefijo para preparar las claves, esto podría utilizarse para evitar conflictos entre aplicaciones.

### Parámetros

`prefix`

  Prefijo string

### Errores/Excepciones

Lanza una Exception si Yac no está habilitado. Lanza Exception si `prefix` excede la longitud máxima de clave de 48 (`YAC_MAX_KEY_LEN`) bytes.

# Yac::delete

(PECL yac >= 1.0.0)

Yac::delete — Eliminar los artículos de la memoria caché

### Descripción

public function Yac::delete(string|array `$keys`, int `$ttl` = ?): bool

retira los artículos de la memoria caché

### Parámetros

`keys`

  clave string, o array de multiples claves para ser removidas.

`ttl`

  si se establece un retraso, la eliminación marcará los elementos como inválidos en ttl segundo.

### Valores devueltos

# Yac::dump

(PECL yac >= 1.0.0)

Yac::dump — Volcar cache

### Descripción

public function Yac::dump(int `$$num`): mixed

Volcar valores almacenados en caché

### Parámetros

`num`

  El número máximo de artículos debe ser devuelto

### Valores devueltos

mixed

# Yac::flush

(PECL yac >= 1.0.0)

Yac::flush — Limpiar el caché

### Descripción

public function Yac::flush(): bool

Eliminar todos los valores almacenados

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

bool, siempre true

# Yac::get

(PECL yac >= 1.0.0)

Yac::get — Recuperar los valores de caché

### Descripción

public function Yac::get(string|array `$key`, int `&$cas` = `null`): mixed

Recuperar los valores de caché

### Parámetros

`key`

  claves string, o array de multiples claves.

`cas`

  Si no es `null`, se ajustará al caso del artículo recuperado.

### Valores devueltos

mixed en caso de éxito, false en caso de error

# Yac::__get

(PECL yac >= 1.0.0)

Yac::__get — Getter

### Descripción

public function Yac::__get(string `$key`): mixed

Recupera los valores del caché

### Parámetros

`key`

  clave string

### Valores devueltos

mixed en caso de éxito, `null` en caso de error.

# Yac::info

(PECL yac >= 1.0.0)

Yac::info — Estado del caché

### Descripción

public function Yac::info(): array

Obtener el estado del sistema de caché

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array, consistente con: "memory_size", "slots_memory_size", "values_memory_size", "segment_size", "segment_num", "miss", "hits", "fails", "kicks", "recycles", "slots_size", "slots_used"

# Yac::set

(PECL yac >= 1.0.0)

Yac::set — Guardar en el caché

### Descripción

public function Yac::set(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function Yac::add(array `$key_vals`): bool

Añade un elemento a la caché, si la clave ya existe, se sobreescribe.

### Parámetros

`keys`

  clave string

`value`

  valor mixed, Todo tipo de valor php podría ser almacenado excepto resource

`ttl`

  tiempo de expiración

### Valores devueltos

el valor de sí mismo

# Yac::__set

(PECL yac >= 1.0.0)

Yac::__set — Setter

### Descripción

public function Yac::__set(string `$keys`, mixed `$value`): mixed

almacena un elemento en el caché

### Parámetros

`keys`

  clave string

`value`

  valor mixed, Todo tipo de valor php podría ser almacenado excepto resource

### Valores devueltos

Siempre devuelve el valor de sí mismo

## Tabla de contenidos

- Yac::add — Guardar en caché
- Yac::__construct — Constructor
- Yac::delete — Eliminar los artículos de la memoria caché
- Yac::dump — Volcar cache
- Yac::flush — Limpiar el caché
- Yac::get — Recuperar los valores de caché
- Yac::__get — Getter
- Yac::info — Estado del caché
- Yac::set — Guardar en el caché
- Yac::__set — Setter

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
  - Tipos de recursos
- Constantes predefinidas
- Yac — La clase Yac
  - Yac::add — Guardar en caché
  - Yac::__construct — Constructor
  - Yac::delete — Eliminar los artículos de la memoria caché
  - Yac::dump — Volcar cache
  - Yac::flush — Limpiar el caché
  - Yac::get — Recuperar los valores de caché
  - Yac::__get — Getter
  - Yac::info — Estado del caché
  - Yac::set — Guardar en el caché
  - Yac::__set — Setter

- APCu — Caché de usuario APC
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones APCu
  - APCUIterator — La clase APCUIterator
- Componere
  - Instalación/Configuración
  - Componere\Abstract\Definition — La clase Componere\Abstract\Definition
  - Componere\Definition — La clase Componere\Definition
  - Componere\Patch — La clase Componere\Patch
  - Componere\Method — La clase Componere\Method
  - Componere\Value — La clase Componere\Value
  - Funciones Componere
- Manejo de errores — Manejo y registro de errores
  - Instalación/Configuración
  - Constantes predefinidas
  - Ejemplos
  - Funciones de Manejo de Errores
- FFI — Interfaz de función externa (Foreign Function Interface)
  - Instalación/Configuración
  - Ejemplos
  - FFI — Interfaz principal para el código C y los datos
  - FFI\CData — Gestor de datos C
  - FFI\CType — Gestor de tipo C
  - Excepciones FFI
  - FFI\ParserException — Excepciones del analizador sintáctico FFI
- OPcache
  - Instalación/Configuración
  - Precarga
  - Funciones de OPcache
- Control de la visualización — Bufferización de salida
  - Instalación/Configuración
  - Constantes predefinidas
  - Bufferización de salida
  - Vaciar los búferes del sistema
  - Búferes de salida a nivel de usuario
  - Ejemplos
  - Funciones del Control de la salida
- Opciones/Info de PHP — Opciones e Información de PHP
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones de Opciones/Info de PHP
- phpdbg — Depurador interactivo PHP
  - Instalación/Configuración
  - Constantes predefinidas
  - phpdbg Funciones
- runkit7
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones de runkit7
- uopz — Operaciones de usuario para Zend
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones Uopz
- WinCache — Caché de Windows para PHP
  - Instalación/Configuración
  - Funciones de WinCache
  - Compilación en Windows
- Xhprof — Perfilador jerárquico
  - Instalación/Configuración
  - Constantes predefinidas
  - Ejemplos
  - Xhprof Funciones
- Yac
  - Instalación/Configuración
  - Constantes predefinidas
  - Yac — La clase Yac

# Manipulación de formatos de audio

# Vinculaciones de audio del OpenAL

# Introducción

Vinculaciones de audio independientes de la plataforma. Requiere la » biblioteca OpenAL.

# Instalación/Configuración

## Tabla de contenidos

- Instalación
- Tipos de recursos

## Instalación

Esta extensión » PECL no está integrada en PHP.

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/openal.

No hay biblioteca DLL para esta extensión PECL actualmente disponible. Consulte la sección Compilación en Windows.

## Tipos de recursos

Esta extensión define cuatro tipos de recursos: Open AL(Device) - Devuelto por openal_device_open(), Open AL(Context) - Devuelto por openal_context_create(), Open AL(Buffer) - Devuelto por openal_buffer_create(), y Open AL(Source) - Devuelto por openal_source_create().

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`ALC_FREQUENCY` (int)
  Atributo de contexto
`ALC_REFRESH` (int)
  Atributo de contexto
`ALC_SYNC` (int)
  Atributo de contexto
`AL_FREQUENCY` (int)
  Configuración del buffer
`AL_BITS` (int)
  Configuración del buffer
`AL_CHANNELS` (int)
  Configuración del buffer
`AL_SIZE` (int)
  Configuración del buffer
`AL_BUFFER` (int)
  Configuración de la fuente/escucha (Entero)
`AL_SOURCE_RELATIVE` (int)
  Configuración de la fuente/escucha (Entero)
`AL_SOURCE_STATE` (int)
  Configuración de la fuente/escucha (Entero)
`AL_PITCH` (int)
  Configuración de la fuente/escucha (Número de punto flotante)
`AL_GAIN` (int)
  Configuración de la fuente/escucha (Número de punto flotante)
`AL_MIN_GAIN` (int)
  Configuración de la fuente/escucha (Número de punto flotante)
`AL_MAX_GAIN` (int)
  Configuración de la fuente/escucha (Número de punto flotante)
`AL_MAX_DISTANCE` (int)
  Configuración de la fuente/escucha (Número de punto flotante)
`AL_ROLLOFF_FACTOR` (int)
  Configuración de la fuente/escucha (Número de punto flotante)
`AL_CONE_OUTER_GAIN` (int)
  Configuración de la fuente/escucha (Número de punto flotante)
`AL_CONE_INNER_ANGLE` (int)
  Configuración de la fuente/escucha (Número de punto flotante)
`AL_CONE_OUTER_ANGLE` (int)
  Configuración de la fuente/escucha (Número de punto flotante)
`AL_REFERENCE_DISTANCE` (int)
  Configuración de la fuente/escucha (Número de punto flotante)
`AL_POSITION` (int)
  Configuración de la fuente/escucha (Número vectorial de punto flotante)
`AL_VELOCITY` (int)
  Configuración de la fuente/escucha (Número vectorial de punto flotante)
`AL_DIRECTION` (int)
  Configuración de la fuente/escucha (Número vectorial de punto flotante)
`AL_ORIENTATION` (int)
  Configuración de la fuente/escucha (Número vectorial de punto flotante)
`AL_FORMAT_MONO8` (int)
  Formato PCM
`AL_FORMAT_MONO16` (int)
  Formato PCM
`AL_FORMAT_STEREO8` (int)
  Formato PCM
`AL_FORMAT_STEREO16` (int)
  Formato PCM
`AL_INITIAL` (int)
  Estado de la Fuente
`AL_PLAYING` (int)
  Estado de la Fuente
`AL_PAUSED` (int)
  Estado de la Fuente
`AL_STOPPED` (int)
  Estado de la Fuente
`AL_LOOPING` (int)
  Estado de la Fuente
`AL_TRUE` (int)
  Valor booleano reconocido por OpenAL
`AL_FALSE` (int)
  Valor booleano reconocido por OpenAL

# Funciones de OpenAL

# openal_buffer_create

(PECL openal >= 0.1.0)

openal_buffer_create — Genera un buffer OpenAL

### Descripción

function openal_buffer_create(): resource

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

openal_buffer_create() devuelve un recurso Open AL(Buffer) o `false` en caso de error.

### Ver también

- openal_buffer_loadwav() - Carga un archivo .wav dentro de un buffer
- openal_buffer_data() - Carga un buffer con datos

# openal_buffer_data

(PECL openal >= 0.1.0)

openal_buffer_data — Carga un buffer con datos

### Descripción

function openal_buffer_data(
resource `$buffer`,
int `$format`,
string `$data`,
int `$freq`
): bool

### Parámetros

`buffer`
  Un recurso Open AL(Buffer) (previamente creado por openal_buffer_create()).
`format`
  Formato de `data`, uno de: `AL_FORMAT_MONO8`, `AL_FORMAT_MONO16`, `AL_FORMAT_STEREO8` y `AL_FORMAT_STEREO16`
`data`
  Bloque de datos de audio binario en el `format` y el `freq` especificado.
`freq`
  Frecuencia de `data` dados en Hz.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- openal_buffer_loadwav() - Carga un archivo .wav dentro de un buffer
- openal_stream() - Inicia el streaming de una fuente

# openal_buffer_destroy

(PECL openal >= 0.1.0)

openal_buffer_destroy — Destruye un buffer OpenAL

### Descripción

function openal_buffer_destroy(resource `$buffer`): bool

### Parámetros

`buffer`
  Un recurso Open AL(Buffer) (previamente creado por openal_buffer_create()).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- openal_buffer_create() - Genera un buffer OpenAL

# openal_buffer_get

(PECL openal >= 0.1.0)

openal_buffer_get — Obtiene las propiedades del buffer OpenAL

### Descripción

function openal_buffer_get(resource `$buffer`, int `$property`): int|false

### Parámetros

`buffer`
  Un recurso Open AL(Buffer) (creado previamente por openal_buffer_create()).
`property`
  Una propiedad específica, una de las siguientes: `AL_FREQUENCY`, `AL_BITS`, `AL_CHANNELS` y `AL_SIZE`.

### Valores devueltos

Devuelve un valor entero apropiado para la propiedad solicitada `property` o `false` si ocurre un error.

### Ver también

- openal_buffer_create() - Genera un buffer OpenAL

# openal_buffer_loadwav

(PECL openal >= 0.1.0)

openal_buffer_loadwav — Carga un archivo .wav dentro de un buffer

### Descripción

function openal_buffer_loadwav(resource `$buffer`, string `$wavfile`): bool

### Parámetros

`buffer`
  Un recurso Open AL(Buffer) (previamente creado por openal_buffer_create()).
`wavfile`
  Ruta al archivo .wav en el sistema de archivo local.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- openal_buffer_data() - Carga un buffer con datos
- openal_stream() - Inicia el streaming de una fuente

# openal_context_create

(PECL openal >= 0.1.0)

openal_context_create — Crea un contexto de procesamiento de audio

### Descripción

function openal_context_create(resource `$device`): resource

### Parámetros

`device`
  Un recurso Open AL(Device) (previamente creado por openal_device_open()).

### Valores devueltos

Devuelve un recurso Open AL(Context) en éxito o `false` en fallo.

### Ver también

- openal_device_open() - Inicia la capa de audio del OpenAL
- openal_context_destroy() - Destruye un contexto

# openal_context_current

(PECL openal >= 0.1.0)

openal_context_current — Crea el corriente contexto especificado

### Descripción

function openal_context_current(resource `$context`): bool

### Parámetros

`context`
  Un recurso Open AL(Context) (previamente creado por openal_context_create()).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- openal_context_create() - Crea un contexto de procesamiento de audio

# openal_context_destroy

(PECL openal >= 0.1.0)

openal_context_destroy — Destruye un contexto

### Descripción

function openal_context_destroy(resource `$context`): bool

### Parámetros

`context`
  Un recurso Open AL(Context) (previamente creado por openal_context_create()).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- openal_context_create() - Crea un contexto de procesamiento de audio

# openal_context_process

(PECL openal >= 0.1.0)

openal_context_process — Procesa un contexto especificado

### Descripción

function openal_context_process(resource `$context`): bool

### Parámetros

`context`
  Un recurso Open AL(Context) (previamente creado por openal_context_create()).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- openal_context_create() - Crea un contexto de procesamiento de audio
- openal_context_current() - Crea el corriente contexto especificado
- openal_context_suspend() - Suspende el contexto especificado

# openal_context_suspend

(PECL openal >= 0.1.0)

openal_context_suspend — Suspende el contexto especificado

### Descripción

function openal_context_suspend(resource `$context`): bool

### Parámetros

`context`
  Un recurso Open AL(Context) (previamente creado por openal_context_create()).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- openal_context_create() - Crea un contexto de procesamiento de audio
- openal_context_current() - Crea el corriente contexto especificado
- openal_context_process() - Procesa un contexto especificado

# openal_device_close

(PECL openal >= 0.1.0)

openal_device_close — Cierra un dispositivo OpenAL

### Descripción

function openal_device_close(resource `$device`): bool

### Parámetros

`device`
  Un recurso Open AL(Device) (previamente creado por openal_device_open()) para ser cerrado.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- openal_device_open() - Inicia la capa de audio del OpenAL

# openal_device_open

(PECL openal >= 0.1.0)

openal_device_open — Inicia la capa de audio del OpenAL

### Descripción

function openal_device_open(string `$device_desc` = ?): resource

### Parámetros

`device_desc`
  Abre un dispositivo de audio especiado opcionalmente por `device_desc`. Si `device_desc` no está especificado el primer dispositivo de audio disponible será usado.

### Valores devueltos

Devuelve un recurso Open AL(Device) en éxito o `false` en fallo.

### Ver también

- openal_device_close() - Cierra un dispositivo OpenAL
- openal_context_create() - Crea un contexto de procesamiento de audio

# openal_listener_get

(PECL openal >= 0.1.0)

openal_listener_get — Devuelve una propiedad de oyente

### Descripción

function openal_listener_get(int `$property`): mixed

### Parámetros

`property`
  Propiedad para recuperar, una de: `AL_GAIN` (float), `AL_POSITION` (array(float,float,float)), `AL_VELOCITY` (array(float,float,float)) y `AL_ORIENTATION` (array(float,float,float)).

### Valores devueltos

Devuelve un flotante o un arreglo de flotantes (como apropiado) o `false` si ocurre un error.

### Ver también

- openal_listener_set() - Establece una propiedad de oyente

# openal_listener_set

(PECL openal >= 0.1.0)

openal_listener_set — Establece una propiedad de oyente

### Descripción

function openal_listener_set(int `$property`, mixed `$setting`): bool

### Parámetros

`property`
  Propiedad a establecer, una de: `AL_GAIN` (float), `AL_POSITION` (array(float,float,float)), `AL_VELOCITY` (array(float,float,float)) y `AL_ORIENTATION` (array(float,float,float)).
`setting`
  Valor a establecer, ya sea flotante, o un arreglo de flotantes como apropiado.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- openal_listener_get() - Devuelve una propiedad de oyente

# openal_source_create

(PECL openal >= 0.1.0)

openal_source_create — Genera un recurso de fuente

### Descripción

function openal_source_create(): resource

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un recurso Open AL(Source) o `false` en caso de error.

### Ver también

- openal_source_set() - Establece la propiedad de la fuente
- openal_source_play() - Empieza la reproducción de la fuente
- openal_source_destroy() - Destruye una fuente de recursos

# openal_source_destroy

(PECL openal >= 0.1.0)

openal_source_destroy — Destruye una fuente de recursos

### Descripción

function openal_source_destroy(resource `$source`): bool

### Parámetros

`source`
  Un recurso Open AL(Source) (previamente creado por openal_source_create()).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- openal_source_create() - Genera un recurso de fuente

# openal_source_get

(PECL openal >= 0.1.0)

openal_source_get — Recupera una propiedad de una fuente del OpenAL

### Descripción

function openal_source_get(resource `$source`, int `$property`): mixed

### Parámetros

`source`
  Un recurso Open AL(Source) (previamente creado por openal_source_create()).
`property`
  Propiedad para obtener, una de: `AL_SOURCE_RELATIVE` (int), `AL_SOURCE_STATE` (int), `AL_PITCH` (float), `AL_GAIN` (float), `AL_MIN_GAIN` (float), `AL_MAX_GAIN` (float), `AL_MAX_DISTANCE` (float), `AL_ROLLOFF_FACTOR` (float), `AL_CONE_OUTER_GAIN` (float), `AL_CONE_INNER_ANGLE` (float), `AL_CONE_OUTER_ANGLE` (float), `AL_REFERENCE_DISTANCE` (float), `AL_POSITION` (array(float,float,float)), `AL_VELOCITY` (array(float,float,float)), `AL_DIRECTION` (array(float,float,float)).

### Valores devueltos

Devuelve el tipo asociado con la propiedad que se recupera o `false` si ocurre un error.

### Ver también

- openal_source_create() - Genera un recurso de fuente
- openal_source_set() - Establece la propiedad de la fuente
- openal_source_play() - Empieza la reproducción de la fuente

# openal_source_pause

(PECL openal >= 0.1.0)

openal_source_pause — Pausa la fuente

### Descripción

function openal_source_pause(resource `$source`): bool

### Parámetros

`source`
  Un recurso Open AL(Source) (previamente creado por openal_source_create()).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- openal_source_stop() - Detiene la reproducción de la fuente
- openal_source_play() - Empieza la reproducción de la fuente
- openal_source_rewind() - Rebobina la fuente

# openal_source_play

(PECL openal >= 0.1.0)

openal_source_play — Empieza la reproducción de la fuente

### Descripción

function openal_source_play(resource `$source`): bool

### Parámetros

`source`
  Un recurso Open AL(Source) (previamente creado por openal_source_create()).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- openal_source_stop() - Detiene la reproducción de la fuente
- openal_source_pause() - Pausa la fuente
- openal_source_rewind() - Rebobina la fuente

# openal_source_rewind

(PECL openal >= 0.1.0)

openal_source_rewind — Rebobina la fuente

### Descripción

function openal_source_rewind(resource `$source`): bool

### Parámetros

`source`
  Un recurso Open AL(Source) (previamente creado por openal_source_create()).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- openal_source_stop() - Detiene la reproducción de la fuente
- openal_source_pause() - Pausa la fuente
- openal_source_play() - Empieza la reproducción de la fuente

# openal_source_set

(PECL openal >= 0.1.0)

openal_source_set — Establece la propiedad de la fuente

### Descripción

function openal_source_set(resource `$source`, int `$property`, mixed `$setting`): bool

### Parámetros

`source`
  Un recurso Open AL(Source) (previamente creado por openal_source_create()).
`property`
  Propiedad para establecer, una de: `AL_BUFFER` (OpenAL(Source)), `AL_LOOPING` (bool), `AL_SOURCE_RELATIVE` (int), `AL_SOURCE_STATE` (int), `AL_PITCH` (float), `AL_GAIN` (float), `AL_MIN_GAIN` (float), `AL_MAX_GAIN` (float), `AL_MAX_DISTANCE` (float), `AL_ROLLOFF_FACTOR` (float), `AL_CONE_OUTER_GAIN` (float), `AL_CONE_INNER_ANGLE` (float), `AL_CONE_OUTER_ANGLE` (float), `AL_REFERENCE_DISTANCE` (float), `AL_POSITION` (array(float,float,float)), `AL_VELOCITY` (array(float,float,float)), `AL_DIRECTION` (array(float,float,float)).
`setting`
  El valor para asignar a la `property` especifica. Consulta la descripción de la `property` para una descripción de el valor(es) esperando.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- openal_source_create() - Genera un recurso de fuente
- openal_source_get() - Recupera una propiedad de una fuente del OpenAL
- openal_source_play() - Empieza la reproducción de la fuente

# openal_source_stop

(PECL openal >= 0.1.0)

openal_source_stop — Detiene la reproducción de la fuente

### Descripción

function openal_source_stop(resource `$source`): bool

### Parámetros

`source`
  Un recurso Open AL(Source) (previamente creado por openal_source_create()).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- openal_source_play() - Empieza la reproducción de la fuente
- openal_source_pause() - Pausa la fuente
- openal_source_rewind() - Rebobina la fuente

# openal_stream

(PECL openal >= 0.1.0)

openal_stream — Inicia el streaming de una fuente

### Descripción

function openal_stream(resource `$source`, int `$format`, int `$rate`): resource|false

### Parámetros

`source`
  Un recurso Open AL(Source) (previamente creado por openal_source_create()).
`format`
  El formato del argumento `data`, uno de los siguientes: `AL_FORMAT_MONO8`, `AL_FORMAT_MONO16`, `AL_FORMAT_STEREO8` y `AL_FORMAT_STEREO16`.
`rate`
  La frecuencia de los datos a streamear, en Hz.

### Valores devueltos

Devuelve un recurso de streaming o `false` si ocurre un error.

### Ver también

- openal_source_create() - Genera un recurso de fuente
- fwrite() - Escribe en un fichero en modo binario

## Tabla de contenidos

- openal_buffer_create — Genera un buffer OpenAL
- openal_buffer_data — Carga un buffer con datos
- openal_buffer_destroy — Destruye un buffer OpenAL
- openal_buffer_get — Obtiene las propiedades del buffer OpenAL
- openal_buffer_loadwav — Carga un archivo .wav dentro de un buffer
- openal_context_create — Crea un contexto de procesamiento de audio
- openal_context_current — Crea el corriente contexto especificado
- openal_context_destroy — Destruye un contexto
- openal_context_process — Procesa un contexto especificado
- openal_context_suspend — Suspende el contexto especificado
- openal_device_close — Cierra un dispositivo OpenAL
- openal_device_open — Inicia la capa de audio del OpenAL
- openal_listener_get — Devuelve una propiedad de oyente
- openal_listener_set — Establece una propiedad de oyente
- openal_source_create — Genera un recurso de fuente
- openal_source_destroy — Destruye una fuente de recursos
- openal_source_get — Recupera una propiedad de una fuente del OpenAL
- openal_source_pause — Pausa la fuente
- openal_source_play — Empieza la reproducción de la fuente
- openal_source_rewind — Rebobina la fuente
- openal_source_set — Establece la propiedad de la fuente
- openal_source_stop — Detiene la reproducción de la fuente
- openal_stream — Inicia el streaming de una fuente

- Instalación/Configuración
  - Instalación
  - Tipos de recursos
- Constantes predefinidas
- Funciones de OpenAL
  - openal_buffer_create — Genera un buffer OpenAL
  - openal_buffer_data — Carga un buffer con datos
  - openal_buffer_destroy — Destruye un buffer OpenAL
  - openal_buffer_get — Obtiene las propiedades del buffer OpenAL
  - openal_buffer_loadwav — Carga un archivo .wav dentro de un buffer
  - openal_context_create — Crea un contexto de procesamiento de audio
  - openal_context_current — Crea el corriente contexto especificado
  - openal_context_destroy — Destruye un contexto
  - openal_context_process — Procesa un contexto especificado
  - openal_context_suspend — Suspende el contexto especificado
  - openal_device_close — Cierra un dispositivo OpenAL
  - openal_device_open — Inicia la capa de audio del OpenAL
  - openal_listener_get — Devuelve una propiedad de oyente
  - openal_listener_set — Establece una propiedad de oyente
  - openal_source_create — Genera un recurso de fuente
  - openal_source_destroy — Destruye una fuente de recursos
  - openal_source_get — Recupera una propiedad de una fuente del OpenAL
  - openal_source_pause — Pausa la fuente
  - openal_source_play — Empieza la reproducción de la fuente
  - openal_source_rewind — Rebobina la fuente
  - openal_source_set — Establece la propiedad de la fuente
  - openal_source_stop — Detiene la reproducción de la fuente
  - openal_stream — Inicia el streaming de una fuente

- OpenAL — Vinculaciones de audio del OpenAL
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones de OpenAL

# Servicios de autenticación

# Radius

# Introducción

Este paquete se basa en los libradius de FreeBSD (Autenticación remota telefónica de servicio de usuario). Permite a los clientes realizar la autenticación y la contabilidad por medio de solicitudes de red a servidores remotos.

Esta extensión PECL añade soporte completo para la autenticación Radius (» RFC 2865) y contabilidad Radius (» RFC 2866). Este paquete está disponible para Unix (probado en FreeBSD y Linux) y para Windows.

> Nota: Una descripción exacta de libradius se pueden encontrar » aquí. Una descripción detallada del archivo de configuración se puede encontrar » aquí.

# Instalación/Configuración

## Tabla de contenidos

- Instalación

## Instalación

Esta extensión » PECL no está integrada en PHP.

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/radius.

# Constantes predefinidas

## Tabla de contenidos

- Opciones RADIUS
- Tipos de paquetes RADIUS
- Tipos de atributo RADIUS
- Tipos de atributo RADIUS específicos del vendedor

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`RADIUS_MPPE_KEY_LEN` (int)
  La longitud máxima de las claves MPPE.

## Opciones RADIUS

Varias funciones RADIUS aceptan opciones en forma de máscara de octetos. Las constantes que representan estas opciones se enumeran a continuación.

`RADIUS_OPTION_SALT` (int)
  Cuando se define, esta opción hará que el valor del atributo sea cifrado salt.
`RADIUS_OPTION_TAGGED` (int)
  Cuando se define, esta opción hará que el valor del atributo provenga del argumento tag.

## Tipos de paquetes RADIUS

Los paquetes RADIUS, ya sean solicitados o recibidos como respuesta, siempre incluyen un tipo. Esta constante se proporciona para facilitar la especificación de un tipo al utilizar la función radius_create_request(), y al comparar el resultado con la función radius_send_request().

`RADIUS_ACCESS_REQUEST` (int)
  Un Access-Request, utilizado para autenticar un usuario en un servidor RADIUS. Los paquetes Access-Request deben incluir un atributo `RADIUS_NAS_IP_ADDRESS`, o un atributo `RADIUS_NAS_IDENTIFIER` pero también incluir un atributo `RADIUS_USER_PASSWORD`, y un atributo `RADIUS_CHAP_PASSWORD` o bien un atributo `RADIUS_STATE`, y deben incluir un atributo `RADIUS_USER_NAME`.
`RADIUS_ACCESS_ACCEPT` (int)
  Una respuesta Access-Accept a un paquete Access-Request indica que el servidor RADIUS ha autenticado al usuario con éxito.
`RADIUS_ACCESS_REJECT` (int)
  Una respuesta Access-Reject a un paquete Access-Request indica que el servidor RADIUS no ha logrado autenticar al usuario.
`RADIUS_ACCESS_CHALLENGE` (int)
  Una respuesta Access-Challenge a un paquete Access-Request indica que el servidor RADIUS requiere más información de otro paquete Access-Request antes de autenticar al usuario.
`RADIUS_ACCOUNTING_REQUEST` (int)
  Un paquete Accounting-Request, utilizado para transmitir información de contabilidad para un servicio del servidor RADIUS.
`RADIUS_ACCOUNTING_RESPONSE` (int)
  Una respuesta Accounting-Response a un paquete Accounting-Request.
`RADIUS_COA_REQUEST` (int)
  Un paquete CoA-Request, enviado desde un servidor RADIUS para indicar que los permisos han cambiado en la sesión del usuario. Se debe emitir una respuesta en forma de CoA-ACK o CoA-NAK. Esta constante está disponible desde PECL radius 1.3.0 y versiones posteriores.
`RADIUS_COA_ACK` (int)
  Un paquete CoA-ACK, enviado al servidor RADIUS para indicar que los permisos del usuario han sido actualizados. Esta constante está disponible desde PECL radius 1.3.0 y versiones posteriores.
`RADIUS_COA_NAK` (int)
  Un paquete CoA-NAK, enviado al servidor RADIUS para indicar que los permisos del usuario no han podido ser actualizados. Esta constante está disponible desde PECL radius 1.3.0 y versiones posteriores.
`RADIUS_DISCONNECT_REQUEST` (int)
  Un paquete Disconnect-Request, enviado desde el servidor RADIUS para indicar que la sesión del usuario debe cerrarse. Esta constante está disponible desde PECL radius 1.3.0 y versiones posteriores.
`RADIUS_DISCONNECT_ACK` (int)
  Un paquete Disconnect-ACK, enviado al servidor RADIUS para indicar que la sesión del usuario ha finalizado. Esta constante está disponible desde PECL radius 1.3.0 y versiones posteriores.
`RADIUS_DISCONNECT_NAK` (int)
  Un paquete Disconnect-NAK, enviado al servidor RADIUS para indicar que la sesión del usuario no ha podido finalizar. Esta constante está disponible desde PECL radius 1.3.0 y versiones posteriores.

## Tipos de atributo RADIUS

Estas constantes definen tipos de atributo RADIUS que pueden ser utilizadas con las funciones radius_put_addr(), radius_put_attr(), radius_put_int() y radius_put_string().

`RADIUS_USER_NAME` (int)
  El atributo User-Name. El valor del atributo debe ser un string que contenga el nombre de usuario que desea autenticarse, y puede ser definido utilizando la función radius_put_attr().
`RADIUS_USER_PASSWORD` (int)
  El atributo User-Password. El valor del atributo debe ser un string que contenga la contraseña del usuario, y puede ser definido utilizando la función radius_put_attr(). Este valor será cifrado durante la transmisión como se describe en la » sección 5.2 de la RFC 2865.
`RADIUS_CHAP_PASSWORD` (int)
  El atributo Chap-Password. El valor del atributo debe ser un string que contenga el primer octeto (que es el identificador CHAP), seguido de una subsecuencia de 16 octetos que contenga el hash MD5 del identificador CHAP, la contraseña en texto plano, y el valor del desafío CHAP, todo concatenado. Tenga en cuenta que el valor del desafío CHAP también debe ser enviado por separado en el atributo `RADIUS_CHAP_CHALLENGE`.

  Ejemplo #1 Uso de contraseñas CHAP

      <?php
      // Primero, creamos un manejador de autenticación y una solicitud.
      $radh = radius_auth_open();
      radius_add_server($radh, $server, $port, $secret, 3, 3);
      radius_create_request($radh, RADIUS_ACCESS_REQUEST);

      // Supongamos que $password contiene la contraseña en texto plano:

      // Generación del desafío.
      $challenge = mt_rand();

      // Especifica un identificador CHAP.
      $ident = 1;

      // Añade el atributo Chap-Password.
      $cp = hash('md5', pack('Ca*', $ident, $password.$challenge), true);
      radius_put_attr($radh, RADIUS_CHAP_PASSWORD, pack('C', $ident).$cp);

      // Añade el atributo Chap-Challenge.
      radius_put_attr($radh, RADIUS_CHAP_CHALLENGE, $challenge);

      /* A partir de aquí, podemos añadir los otros atributos
       * y llamar a la función radius_send_request(). */
      ?>

`RADIUS_NAS_IP_ADDRESS` (int)
  El atributo NAS-IP-Address. El valor del atributo esperado es la dirección IP del cliente RADIUS codificada como un entero, que puede ser definida utilizando la función radius_put_addr().
`RADIUS_NAS_PORT` (int)
  El atributo NAS-Port. El valor del atributo esperado es el puerto físico del usuario en el cliente RADIUS, codificado como un entero, que puede ser definido utilizando la función radius_put_int().
`RADIUS_SERVICE_TYPE` (int)
  El atributo Service-Type. El valor del atributo indica el tipo de servicio que el usuario solicita, y debe ser un entero, que puede ser definido utilizando la función radius_put_int().

  Se proporcionan constantes para representar los valores posibles de este atributo. Aquí están:

  - `RADIUS_LOGIN`
  - `RADIUS_FRAMED`
  - `RADIUS_CALLBACK_LOGIN`
  - `RADIUS_CALLBACK_FRAMED`
  - `RADIUS_OUTBOUND`
  - `RADIUS_ADMINISTRATIVE`
  - `RADIUS_NAS_PROMPT`
  - `RADIUS_AUTHENTICATE_ONLY`
  - `RADIUS_CALLBACK_NAS_PROMPT`
`RADIUS_FRAMED_PROTOCOL` (int)

  El atributo Framed-Protocol. El valor del atributo esperado es un entero, que indica el framing a utilizar para el acceso, y puede ser definido utilizando la función radius_put_int(). Los valores posibles para este atributo son:

  - `RADIUS_PPP`
  - `RADIUS_SLIP`
  - `RADIUS_ARAP`
  - `RADIUS_GANDALF`
  - `RADIUS_XYLOGICS`
`RADIUS_FRAMED_IP_ADDRESS` (int)
  El atributo Framed-IP-Address. El valor esperado es una dirección de la red del usuario codificada como un entero, que puede ser definida utilizando la función radius_put_addr() y recuperada utilizando la función radius_cvt_addr().
`RADIUS_FRAMED_IP_NETMASK` (int)
  El atributo Framed-IP-Netmask. El valor esperado es una máscara de red del usuario, codificada como un entero, que puede ser definida utilizando la función radius_put_addr() y recuperada utilizando la función radius_cvt_addr().
`RADIUS_FRAMED_ROUTING` (int)
  El atributo Framed-Routing. El valor esperado es un entero que indica el método de enrutamiento para el usuario, que puede ser definido utilizando la función radius_put_int().

  Valores posibles:

  - `0`: Sin enrutamiento
  - `1`: Enviar paquetes de enrutamiento
  - `2`: Escuchar paquetes de enrutamiento
  - `3`: Enviar y escuchar
`RADIUS_FILTER_ID` (int)
  El atributo Filter-ID. El valor esperado es una implementación específica, legible por humanos, de strings de filtros, que pueden ser definidas utilizando la función radius_put_attr().
`RADIUS_FRAMED_MTU` (int)
  El atributo Framed-MTU. El valor esperado es un entero, que indica el MTU a configurar para el usuario, y puede ser definido utilizando la función radius_put_int().
`RADIUS_FRAMED_COMPRESSION` (int)

  El atributo Framed-Compression. El valor esperado es un entero, que indica el protocolo de compresión a utilizar, y puede ser definido utilizando la función radius_put_int(). Valores posibles:

  - `RADIUS_COMP_NONE`: Sin compresión
  - `RADIUS_COMP_VJ`: Compresión de cabecera VJ TCP/IP
  - `RADIUS_COMP_IPXHDR`: Compresión de cabecera IPX
  - `RADIUS_COMP_STAC_LZS`: Compresión Stac-LZS (añadido en PECL radius 1.3.0b2)
`RADIUS_LOGIN_IP_HOST` (int)
  El atributo Login-IP-Host. El valor esperado es la dirección IP de conexión del usuario, codificada como un entero, que puede ser definido utilizando la función radius_put_addr().
`RADIUS_LOGIN_SERVICE` (int)
  El atributo Login-Service. El valor esperado es un entero que indica el servicio al que el usuario se conecta en el host de identificación. El valor puede ser convertido a un entero PHP mediante la función radius_cvt_int().
`RADIUS_LOGIN_TCP_PORT` (int)
  El atributo Login-TCP-Port. El valor esperado es un entero que indica el puerto al que el usuario se conecta en el host de identificación. El valor puede ser convertido a un entero PHP mediante la función radius_cvt_int().
`RADIUS_REPLY_MESSAGE` (int)
  El atributo Reply-Message. El valor esperado es un string que contiene un texto que puede ser mostrado al usuario en respuesta a una solicitud de acceso.
`RADIUS_CALLBACK_NUMBER` (int)
  El atributo Callback-Number. El valor esperado es un string que contiene la cadena de marcación a utilizar para la función de devolución de llamada.
`RADIUS_CALLBACK_ID` (int)
  El atributo Callback-Id. El valor esperado es un string que contiene el nombre de la implementación específica del lugar a llamar.
`RADIUS_FRAMED_ROUTE` (int)
  El atributo Framed-Route. El valor esperado es un string que contiene un conjunto de rutas de implementación específica a configurar para el usuario.
`RADIUS_FRAMED_IPX_NETWORK` (int)
  El atributo Framed-IPX-Network. El valor esperado es un entero que contiene la red IPX a configurar para el usuario, o `0xFFFFFFFE` para indicar que el cliente RADIUS debe seleccionar la red, y puede ser accedido mediante la función radius_cvt_int().
`RADIUS_STATE` (int)
  El atributo State. El valor esperado es un string que contiene la implementación definida incluida en un Access-Challenge desde un servidor que debe ser incluida en la subsiguiente Access-Request, y puede ser definido utilizando la función radius_put_attr().
`RADIUS_CLASS` (int)
  El atributo Class. El valor esperado es un string arbitrario que incluye el mensaje de un Access-Accept que debe ser enviado al servidor de cuentas en los mensajes Accounting-Request, y puede ser definido mediante la función radius_put_attr().
`RADIUS_VENDOR_SPECIFIC` (int)
  El atributo Vendor-Specific. En general, los valores del atributo del vendedor deben ser definidos utilizando las funciones radius_put_vendor_addr(), radius_put_vendor_attr(), radius_put_vendor_int() y radius_put_vendor_string(), en lugar de hacerlo directamente. Esta constante es útil al interpretar los atributos específicos del vendedor en las respuestas de un servidor RADIUS; cuando se recibe un atributo específico del vendedor, la función radius_get_vendor_attr() debe ser utilizada para acceder al identificador del vendedor, el tipo de atributo y el valor del atributo.
`RADIUS_SESSION_TIMEOUT` (int)
  Tiempo de espera de la sesión
`RADIUS_IDLE_TIMEOUT` (int)
  Tiempo de expiración
`RADIUS_TERMINATION_ACTION` (int)
  Acción de terminación
`RADIUS_CALLED_STATION_ID` (int)
  Identificador de la estación llamada
`RADIUS_CALLING_STATION_ID` (int)
  Identificador de la estación llamante
`RADIUS_NAS_IDENTIFIER` (int)
  Identificador NAS
`RADIUS_PROXY_STATE` (int)
  Estado del Proxy
`RADIUS_LOGIN_LAT_SERVICE` (int)
  Servicio de identificación LAT
`RADIUS_LOGIN_LAT_NODE` (int)
  Nodo de identificación LAT
`RADIUS_LOGIN_LAT_GROUP` (int)
  Grupo de identificación LAT
`RADIUS_FRAMED_APPLETALK_LINK` (int)
  Enlace framé Appletalk
`RADIUS_FRAMED_APPLETALK_NETWORK` (int)
  Red framé Appletalk
`RADIUS_FRAMED_APPLETALK_ZONE` (int)
  Zona framé Appletalk
`RADIUS_CHAP_CHALLENGE` (int)
  Desafío
`RADIUS_NAS_PORT_TYPE` (int)

  Tipo de puerto NAS:

  - `RADIUS_ASYNC`
  - `RADIUS_SYNC`
  - `RADIUS_ISDN_SYNC`
  - `RADIUS_ISDN_ASYNC_V120`
  - `RADIUS_ISDN_ASYNC_V110`
  - `RADIUS_VIRTUAL`
  - `RADIUS_PIAFS`
  - `RADIUS_HDLC_CLEAR_CHANNEL`
  - `RADIUS_X_25`
  - `RADIUS_X_75`
  - `RADIUS_G_3_FAX`
  - `RADIUS_SDSL`
  - `RADIUS_ADSL_CAP`
  - `RADIUS_ADSL_DMT`
  - `RADIUS_IDSL`
  - `RADIUS_ETHERNET`
  - `RADIUS_XDSL`
  - `RADIUS_CABLE`
  - `RADIUS_WIRELESS_OTHER`
  - `RADIUS_WIRELESS_IEEE_802_11`
`RADIUS_PORT_LIMIT` (int)
  Límite del puerto
`RADIUS_LOGIN_LAT_PORT` (int)
  Puerto de identificación LAT
`RADIUS_CONNECT_INFO` (int)
  Información de conexión
`RADIUS_ACCT_STATUS_TYPE` (int)

  Tipo de estado de la cuenta:

  - `RADIUS_START`
  - `RADIUS_STOP`
  - `RADIUS_ACCOUNTING_ON`
  - `RADIUS_ACCOUNTING_OFF`
`RADIUS_ACCT_DELAY_TIME` (int)
  Tiempo de espera máximo de identificación
`RADIUS_ACCT_INPUT_OCTETS` (int)
  Octetos de entrada de identificación
`RADIUS_ACCT_OUTPUT_OCTETS` (int)
  Octetos de salida de identificación
`RADIUS_ACCT_SESSION_ID` (int)
  Identificador de sesión de identificación
`RADIUS_ACCT_AUTHENTIC` (int)

  Identificación auténtica, uno entre:

  - `RADIUS_AUTH_RADIUS`
  - `RADIUS_AUTH_LOCAL`
  - `RADIUS_AUTH_REMOTE`
`RADIUS_ACCT_SESSION_TIME` (int)
  Duración de la sesión de identificación
`RADIUS_ACCT_INPUT_PACKETS` (int)
  Paquetes de entrada de identificación
`RADIUS_ACCT_OUTPUT_PACKETS` (int)
  Paquetes de salida de identificación
`RADIUS_ACCT_TERMINATE_CAUSE` (int)

  Causa de la finalización de la identificación, uno entre:

  - `RADIUS_TERM_USER_REQUEST`
  - `RADIUS_TERM_LOST_CARRIER`
  - `RADIUS_TERM_LOST_SERVICE`
  - `RADIUS_TERM_IDLE_TIMEOUT`
  - `RADIUS_TERM_SESSION_TIMEOUT`
  - `RADIUS_TERM_ADMIN_RESET`
  - `RADIUS_TERM_ADMIN_REBOOT`
  - `RADIUS_TERM_PORT_ERROR`
  - `RADIUS_TERM_NAS_ERROR`
  - `RADIUS_TERM_NAS_REQUEST`
  - `RADIUS_TERM_NAS_REBOOT`
  - `RADIUS_TERM_PORT_UNNEEDED`
  - `RADIUS_TERM_PORT_PREEMPTED`
  - `RADIUS_TERM_PORT_SUSPENDED`
  - `RADIUS_TERM_SERVICE_UNAVAILABLE`
  - `RADIUS_TERM_CALLBACK`
  - `RADIUS_TERM_USER_ERROR`
  - `RADIUS_TERM_HOST_REQUEST`
`RADIUS_ACCT_MULTI_SESSION_ID` (int)
  Identificador de una sesión múltiple de identificación
`RADIUS_ACCT_LINK_COUNT` (int)
  Número de enlaces de identificación

Constantes de tipo de servicio
`RADIUS_LOGIN`
`RADIUS_FRAMED`
`RADIUS_CALLBACK_LOGIN`
`RADIUS_CALLBACK_FRAMED`
`RADIUS_OUTBOUND`
`RADIUS_ADMINISTRATIVE`
`RADIUS_NAS_PROMPT`
`RADIUS_AUTHENTICATE_ONLY`
`RADIUS_CALLBACK_NAS_PROMPT`

Constantes de Framed-Protocol
`RADIUS_PPP`
`RADIUS_SLIP`
`RADIUS_ARAP`
`RADIUS_GANDALF`
`RADIUS_XYLOGICS`

Constantes de Framed-Compression
`RADIUS_COMP_NONE`
`RADIUS_COMP_VJ`
`RADIUS_COMP_IPXHDR`
`RADIUS_COMP_STAC_LZS`

Constantes de tipo de puerto NAS
`RADIUS_ASYNC`
`RADIUS_SYNC`
`RADIUS_ISDN_SYNC`
`RADIUS_ISDN_ASYNC_V120`
`RADIUS_ISDN_ASYNC_V110`
`RADIUS_VIRTUAL`
`RADIUS_PIAFS`
`RADIUS_HDLC_CLEAR_CHANNEL`
`RADIUS_X_25`
`RADIUS_X_75`
`RADIUS_G_3_FAX`
`RADIUS_SDSL`
`RADIUS_ADSL_CAP`
`RADIUS_ADSL_DMT`
`RADIUS_IDSL`
`RADIUS_ETHERNET`
`RADIUS_XDSL`
`RADIUS_CABLE`
`RADIUS_WIRELESS_OTHER`
`RADIUS_WIRELESS_IEEE_802_11`

Constantes de tipo de estado de contabilidad
`RADIUS_START`
`RADIUS_STOP`
`RADIUS_ACCOUNTING_ON`
`RADIUS_ACCOUNTING_OFF`

Constantes de autenticación de contabilidad
`RADIUS_AUTH_RADIUS`
`RADIUS_AUTH_LOCAL`
`RADIUS_AUTH_REMOTE`

Constantes de causa de terminación de contabilidad
`RADIUS_TERM_USER_REQUEST`
`RADIUS_TERM_LOST_CARRIER`
`RADIUS_TERM_LOST_SERVICE`
`RADIUS_TERM_IDLE_TIMEOUT`
`RADIUS_TERM_SESSION_TIMEOUT`
`RADIUS_TERM_ADMIN_RESET`
`RADIUS_TERM_ADMIN_REBOOT`
`RADIUS_TERM_PORT_ERROR`
`RADIUS_TERM_NAS_ERROR`
`RADIUS_TERM_NAS_REQUEST`
`RADIUS_TERM_NAS_REBOOT`
`RADIUS_TERM_PORT_UNNEEDED`
`RADIUS_TERM_PORT_PREEMPTED`
`RADIUS_TERM_PORT_SUSPENDED`
`RADIUS_TERM_SERVICE_UNAVAILABLE`
`RADIUS_TERM_CALLBACK`
`RADIUS_TERM_USER_ERROR`
`RADIUS_TERM_HOST_REQUEST`
`RADIUS_MICROSOFT_MS_CHAP_RESPONSE`
`RADIUS_MICROSOFT_MS_CHAP_ERROR`
`RADIUS_MICROSOFT_MS_CHAP_PW_1`
`RADIUS_MICROSOFT_MS_CHAP_PW_2`
`RADIUS_MICROSOFT_MS_CHAP_LM_ENC_PW`
`RADIUS_MICROSOFT_MS_CHAP_NT_ENC_PW`
`RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY`
`RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES`
`RADIUS_MICROSOFT_MS_RAS_VENDOR`
`RADIUS_MICROSOFT_MS_CHAP_DOMAIN`
`RADIUS_MICROSOFT_MS_CHAP_CHALLENGE`
`RADIUS_MICROSOFT_MS_CHAP_MPPE_KEYS`
`RADIUS_MICROSOFT_MS_BAP_USAGE`
`RADIUS_MICROSOFT_MS_LINK_UTILIZATION_THRESHOLD`
`RADIUS_MICROSOFT_MS_LINK_DROP_TIME_LIMIT`
`RADIUS_MICROSOFT_MS_MPPE_SEND_KEY`
`RADIUS_MICROSOFT_MS_MPPE_RECV_KEY`
`RADIUS_MICROSOFT_MS_RAS_VERSION`
`RADIUS_MICROSOFT_MS_OLD_ARAP_PASSWORD`
`RADIUS_MICROSOFT_MS_NEW_ARAP_PASSWORD`
`RADIUS_MICROSOFT_MS_ARAP_PASSWORD_CHANGE_REASON`
`RADIUS_MICROSOFT_MS_FILTER`
`RADIUS_MICROSOFT_MS_ACCT_AUTH_TYPE`
`RADIUS_MICROSOFT_MS_ACCT_EAP_TYPE`
`RADIUS_MICROSOFT_MS_CHAP2_RESPONSE`
`RADIUS_MICROSOFT_MS_CHAP2_SUCCESS`
`RADIUS_MICROSOFT_MS_CHAP2_PW`
`RADIUS_MICROSOFT_MS_PRIMARY_DNS_SERVER`
`RADIUS_MICROSOFT_MS_SECONDARY_DNS_SERVER`
`RADIUS_MICROSOFT_MS_PRIMARY_NBNS_SERVER`
`RADIUS_MICROSOFT_MS_SECONDARY_NBNS_SERVER`
`RADIUS_MICROSOFT_MS_ARAP_CHALLENGE`

## Tipos de atributo RADIUS específicos del vendedor

`RADIUS_VENDOR_MICROSOFT` (int)

  Atributos específicos de Microsoft (» RFC 2548):

  - `RADIUS_MICROSOFT_MS_CHAP_RESPONSE`
  - `RADIUS_MICROSOFT_MS_CHAP_ERROR`
  - `RADIUS_MICROSOFT_MS_CHAP_PW_1`
  - `RADIUS_MICROSOFT_MS_CHAP_PW_2`
  - `RADIUS_MICROSOFT_MS_CHAP_LM_ENC_PW`
  - `RADIUS_MICROSOFT_MS_CHAP_NT_ENC_PW`
  - `RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY`
  - `RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES`
  - `RADIUS_MICROSOFT_MS_RAS_VENDOR`
  - `RADIUS_MICROSOFT_MS_CHAP_DOMAIN`
  - `RADIUS_MICROSOFT_MS_CHAP_CHALLENGE`
  - `RADIUS_MICROSOFT_MS_CHAP_MPPE_KEYS`
  - `RADIUS_MICROSOFT_MS_BAP_USAGE`
  - `RADIUS_MICROSOFT_MS_LINK_UTILIZATION_THRESHOLD`
  - `RADIUS_MICROSOFT_MS_LINK_DROP_TIME_LIMIT`
  - `RADIUS_MICROSOFT_MS_MPPE_SEND_KEY`
  - `RADIUS_MICROSOFT_MS_MPPE_RECV_KEY`
  - `RADIUS_MICROSOFT_MS_RAS_VERSION`
  - `RADIUS_MICROSOFT_MS_OLD_ARAP_PASSWORD`
  - `RADIUS_MICROSOFT_MS_NEW_ARAP_PASSWORD`
  - `RADIUS_MICROSOFT_MS_ARAP_PASSWORD_CHANGE_REASON`
  - `RADIUS_MICROSOFT_MS_FILTER`
  - `RADIUS_MICROSOFT_MS_ACCT_AUTH_TYPE`
  - `RADIUS_MICROSOFT_MS_ACCT_EAP_TYPE`
  - `RADIUS_MICROSOFT_MS_CHAP2_RESPONSE`
  - `RADIUS_MICROSOFT_MS_CHAP2_SUCCESS`
  - `RADIUS_MICROSOFT_MS_CHAP2_PW`
  - `RADIUS_MICROSOFT_MS_PRIMARY_DNS_SERVER`
  - `RADIUS_MICROSOFT_MS_SECONDARY_DNS_SERVER`
  - `RADIUS_MICROSOFT_MS_PRIMARY_NBNS_SERVER`
  - `RADIUS_MICROSOFT_MS_SECONDARY_NBNS_SERVER`
  - `RADIUS_MICROSOFT_MS_ARAP_CHALLENGE`

# Ejemplos

¿Cómo iniciar?

- Obtener un recurso radius
- Configurar la librería
- Crear la petición
- Poner atributos
- Enviar la petición
- Recibir atributos
- Cerrar el recurso radius (opcional)

También sirve echar un vistazo a los ejemplos en este paquete.

El paquete contiene un ejemplo de script php. Este script demuestra como autenticar con radius utilizando PAP o CHAP (md5). Si se autentica con servidores Microsoft Radius entonces no le será posible utilizar CHAP (md5). Si quisiera autenticarse con servidores Microsoft tiene que utilizar MS-CHAPv1 o MS-CHAPv2, pero es más complicado, porque usted necesita md4, sha1 y des para generar los datos correctos. Los ejemplos adjuntos demuestran todos los métodos de autenticación, incluyendo MS-CHAPv1 y MS-CHAPv2. Para tener funcionando MS-CHAP necesita las extensiones mcrypt y mhash iniciando con la version 1.2 de este paquete, la extensión mcrypt ya no es necesaria.

# Funciones Radius

# radius_acct_open

(PECL radius >= 1.1.0)

radius_acct_open — Crea un manejador Radius para el conteo

### Descripción

function radius_acct_open(): resource

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un manejador en caso de tener éxito, `false` en caso de error. Esta función falla solamente si hay insuficiencia de memoria.

### Ejemplos

Ejemplo #1 radius_acct_open() example

    <?php
    $res = radius_acct_open ()
        or die ("No se pudo crear un manejador handle");
    print "Manejador creado exitosamente";
    ?>

# radius_add_server

(PECL radius >= 1.1.0)

radius_add_server — Añade un servidor

### Descripción

function radius_add_server(
resource `$radius_handle`,
string `$hostname`,
int `$port`,
string `$secret`,
int `$timeout`,
int `$max_tries`
): bool

radius_add_server() puede ser utilizado varias veces, y puede ser utilizado junto con la función radius_config(). Como máximo, pueden especificarse 10 servidores. Cuando se proporcionan varios servidores, se intentan de forma `round-robin` hasta que se recibe una respuesta válida, o hasta que se alcanza el límite `max_tries` de cada servidor.

### Parámetros

`radius_handle`
`hostname`
  El argumento `hostname` especifica el host servidor, ya sea como nombre de dominio completo o como dirección IP.
`port`

  El `port` especifica el puerto UDP al que conectar en el servidor. Si el puerto dado es `0`, la biblioteca buscará el servicio `radius/udp` o `radacct/udp` en la base de datos de servicios de red y utilizará el puerto encontrado. Si no se encuentra ninguna entrada, la biblioteca utilizará los puertos Radius estándar, 1812 para la autenticación y 1813 para las cuentas.

`secret`
  El secreto compartido para el host servidor se pasa al argumento `secret`. El protocolo Radius ignora todo excepto los primeros 128 bytes del secreto compartido.
`timeout`
  El tiempo límite para recibir respuestas del servidor se pasa al argumento `timeout`, en segundos.
`max_tries`
  El número máximo de solicitudes repetidas a realizar antes de fallar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con radius_add_server()

    <?php
    if (!radius_add_server($res, 'radius.example.com', 1812, 'testing123', 3, 3)) {
        echo 'Error Radius :' . radius_strerror($res). "\n<br>";
        exit;
    }
    ?>

### Ver también

- radius_config() - Solicita a la biblioteca que lea un archivo de configuración dado

# radius_auth_open

(PECL radius >= 1.1.0)

radius_auth_open — Crea un identificador de Radius para la autenticación

### Descripción

function radius_auth_open(): resource

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un manejador en caso de éxito, `false` en caso de error. Esta función sólo falla si hay insuficiente memoria disponible.

### Ejemplos

Ejemplo #1 Ejemplo de radius_auth_open()

    <?php
    $radh = radius_auth_open()
        or die ("No se pudo crear el manejador");
    echo "Manejador creado con éxito";
    ?>

# radius_close

(PECL radius >= 1.1.0)

radius_close — Libera todos los recursos

### Descripción

function radius_close(resource `$radius_handle`): bool

No es necesario llamar a esta función debido a que php libera todos los recursos al final de cada petición.

### Parámetros

`radius_handle`
  El recurso RADIUS.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# radius_config

(PECL radius >= 1.1.0)

radius_config — Solicita a la biblioteca que lea un archivo de configuración dado

### Descripción

function radius_config(resource `$radius_handle`, string `$file`): bool

Antes de cualquier petición Radius, la biblioteca debe conocer el servidor a contactar. La manera sencilla de configurar la biblioteca es llamar a la función radius_config(). radius_config() solicita a la biblioteca que lea un archivo de configuración cuyo formato se describe en la página » radius.conf.

### Parámetros

`radius_handle`
`file`
  La ruta hacia el archivo de configuración se pasa como argumento a la función radius_config(). La biblioteca puede ser configurada también llamando a la función radius_add_server().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- radius_add_server() - Añade un servidor

# radius_create_request

(PECL radius >= 1.1.0)

radius_create_request — Crea una solicitud de cuenta o de identificación

### Descripción

function radius_create_request(resource `$radius_handle`, int `$type`): bool

Una solicitud Radius consiste en código que especifica una solicitud concreta, así como cero o varios atributos que proporcionan información adicional. Para comenzar a construir una nueva solicitud, llámese a la función radius_create_request().

> Nota: Advertencia: Debe llamarse a esta función antes de pasar cualquier argumento.

### Parámetros

`radius_handle`
`type`
  El tipo es `RADIUS_ACCESS_REQUEST` o `RADIUS_ACCOUNTING_REQUEST`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con radius_create_request()

    <?php
    if (!radius_create_request($res, RADIUS_ACCESS_REQUEST)) {
        echo 'Error Radius :' . radius_strerror($res). "\n<br />";
        exit;
    }
    ?>

### Ver también

- radius_send_request() - Envía una solicitud y espera una respuesta

# radius_cvt_addr

(PECL radius >= 1.1.0)

radius_cvt_addr — Convierte datos brutos en dirección IP

### Descripción

function radius_cvt_addr(string `$data`): string

Convierte datos brutos en dirección IP

### Parámetros

`data`
  Datos de entrada

### Valores devueltos

Devuelve la dirección IP.

### Ejemplos

Ejemplo #1 Ejemplo con radius_cvt_addr()

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf ("Error al recuperar los atributos: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        switch ($attr) {

        case RADIUS_FRAMED_IP_ADDRESS:
            $ip = radius_cvt_addr($data);
            echo "IP: $ip<br>\n";
            break;

        case RADIUS_FRAMED_IP_NETMASK:
            $mask = radius_cvt_addr($data);
            echo "MÁSCARA: $mask<br>\n";
            break;
        }
    }
    ?>

### Ver también

- radius_cvt_int() - Convierte datos brutos en entero
- radius_cvt_string() - Convierte datos brutos en string

# radius_cvt_int

(PECL radius >= 1.1.0)

radius_cvt_int — Convierte datos brutos en entero

### Descripción

function radius_cvt_int(string `$data`): int

Convierte datos brutos en entero

### Parámetros

`data`
  Datos de entrada.

### Valores devueltos

Devuelve el entero, recuperado desde los datos.

### Ejemplos

Ejemplo #1 Ejemplo con radius_cvt_int()

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf ("Error al recuperar los atributos: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        switch ($attr) {

        case RADIUS_FRAMED_MTU:
            $mtu = radius_cvt_int($data);
            echo "MTU: $mtu<br>\n";
            break;
        }
    }
    ?>

### Ver también

- radius_cvt_addr() - Convierte datos brutos en dirección IP
- radius_cvt_string() - Convierte datos brutos en string

# radius_cvt_string

(PECL radius >= 1.1.0)

radius_cvt_string — Convierte datos brutos en string

### Descripción

function radius_cvt_string(string `$data`): string

Convierte datos brutos en string

### Parámetros

`data`
  Datos de entrada

### Valores devueltos

Devuelve el string, recuperado desde los datos.

### Ejemplos

Ejemplo #1 Ejemplo con radius_cvt_string()

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf ("Error al recuperar los atributos: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        switch ($attr) {

        case RADIUS_FILTER_ID:
            $id = radius_cvt_string($data);
            echo "Filtre ID : $id<br>\n";
            break;
        }
    }
    ?>

### Ver también

- radius_cvt_addr() - Convierte datos brutos en dirección IP
- radius_cvt_int() - Convierte datos brutos en entero

# radius_demangle

(PECL radius >= 1.2.0)

radius_demangle — Deshidrata datos

### Descripción

function radius_demangle(resource `$radius_handle`, string `$mangled`): string

Algunos datos (contraseñas, claves MS-CHAPv1 MPPE) son "deshidratados" por razones de seguridad y deben ser "deshidratados" antes de poder utilizarlos.

### Parámetros

`radius_handle`
  El recurso RADIUS.
`mangled`
  Los datos deformados a descifrar

### Valores devueltos

Devuelve la cadena "deshidratada" o `false` si ocurre un error.

# radius_demangle_mppe_key

(PECL radius >= 1.2.0)

radius_demangle_mppe_key — Deriva las claves mppe desde datos

### Descripción

function radius_demangle_mppe_key(resource `$radius_handle`, string `$mangled`): string

Al utilizar MPPE con MS-CHAPv2, las claves recibidas y enviadas son "secadas" (ver la » RFC 2548), sin embargo, esta función es útil, ya que no se sabe si existe o no una implementación de PPTP-MPPE en PHP.

### Parámetros

`radius_handle`
  El recurso RADIUS.
`mangled`
  Los datos deformados a descifrar

### Valores devueltos

Devuelve el string o `false` si ocurre un error.

# radius_get_attr

(PECL radius >= 1.1.0)

radius_get_attr — Extrae un atributo

### Descripción

function radius_get_attr(resource `$radius_handle`): mixed

Al igual que las solicitudes Radius, cada respuesta debe contener cero o varios atributos. Tras recibir una respuesta con éxito mediante la función radius_send_request(), estos atributos pueden ser extraídos uno a uno utilizando la función radius_get_attr(). En cada llamada a radius_get_attr(), se recupera el siguiente atributo desde la respuesta actual.

### Parámetros

`radius_handle`
  El recurso RADIUS.

### Valores devueltos

Devuelve un array asociativo que contiene el tipo de atributo junto con los datos o un número de error <= 0.

### Ejemplos

Ejemplo #1 Ejemplo con radius_get_attr()

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf("Error al recuperar el atributo: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];
        printf("Atributo recuperado :%d %d bytes %s\n", $attr, strlen($data), bin2hex($data));
    }
    ?>

### Ver también

- radius_put_attr() - Adjunta un atributo binario
- radius_get_vendor_attr() - Extrae un atributo específico del proveedor
- radius_put_vendor_attr() - Adjunta un atributo binario a un proveedor específico
- radius_send_request() - Envía una solicitud y espera una respuesta

# radius_get_tagged_attr_data

(PECL radius >= 1.3.0)

radius_get_tagged_attr_data — Extrae los datos de un atributo

### Descripción

function radius_get_tagged_attr_data(string `$data`): string|false

Si un atributo que contiene un tag ha sido devuelto por la función radius_get_attr(), radius_get_tagged_attr_data() devuelve los datos desde este atributo.

### Parámetros

`data`
  El atributo que contiene un tag a decodificar.

### Valores devueltos

Devuelve los datos del atributo o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con radius_get_tagged_attr_data()

    <?php
    while ($resa = radius_get_attr($res)) {
        if (!is_array($resa)) {
            printf ("Error al recuperar el atributo: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        $tag = radius_get_tagged_attr_tag($data);
        $value = radius_get_tagged_attr_data($data);

        printf("Recuperación del atributo que contiene el tag %d y el valor %s\n", $tag, $value);
    }
    ?>

### Ver también

- radius_get_attr() - Extrae un atributo
- radius_get_tagged_attr_tag() - Extrae la etiqueta desde un atributo

# radius_get_tagged_attr_tag

(PECL radius >= 1.3.0)

radius_get_tagged_attr_tag — Extrae la etiqueta desde un atributo

### Descripción

function radius_get_tagged_attr_tag(string `$data`): int|false

Si un atributo que contiene una etiqueta ha sido devuelto por la función radius_get_attr(), radius_get_tagged_attr_data() va devolver la etiqueta desde el atributo.

### Parámetros

`data`
  El atributo a decodificar.

### Valores devueltos

Devuelve la etiqueta desde el atributo o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con radius_get_tagged_attr_tag()

    <?php
    while ($resa = radius_get_attr($res)) {
        if (!is_array($resa)) {
            printf ("Error al recuperar el atributo: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        $tag = radius_get_tagged_attr_tag($data);
        $value = radius_get_tagged_attr_data($data);

        printf("Recuperación del atributo conteniendo la etiqueta %d y el valor %s\n", $tag, $value);
    }
    ?>

### Ver también

- radius_get_attr() - Extrae un atributo
- radius_get_tagged_attr_data() - Extrae los datos de un atributo

# radius_get_vendor_attr

(PECL radius >= 1.1.0)

radius_get_vendor_attr — Extrae un atributo específico del proveedor

### Descripción

function radius_get_vendor_attr(string `$data`): array|false

Si radius_get_attr() devuelve `RADIUS_VENDOR_SPECIFIC`, radius_get_vendor_attr() puede ser llamado para determinar el proveedor.

### Parámetros

`data`
  Datos de entrada.

### Valores devueltos

Devuelve un array asociativo que contiene el tipo de atributo, el proveedor así como los datos, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con radius_get_vendor_attr()

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf ("Error al recuperar el atributo: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];
        printf("Atributo recuperado :%d %d octetos %s\n", $attr, strlen($data), bin2hex($data));
        if ($attr == RADIUS_VENDOR_SPECIFIC) {

            $resv = radius_get_vendor_attr($data);
            if (is_array($resv)) {
                $vendor = $resv['vendor'];
                $attrv = $resv['attr'];
                $datav = $resv['data'];
                printf("Recuperación del proveedor del atributo :%d %d octetos %s\n", $attrv, strlen($datav), bin2hex($datav));
            }

        }
    }
    ?>

### Ver también

- radius_get_attr() - Extrae un atributo
- radius_put_vendor_attr() - Adjunta un atributo binario a un proveedor específico

# radius_put_addr

(PECL radius >= 1.1.0)

radius_put_addr — Adjunta una dirección IP como atributo

### Descripción

function radius_put_addr(
resource `$radius_handle`,
int `$type`,
string `$addr`,
int `$options` = 0,
int `$tag` = ?
): bool

Adjunta una dirección IP a la solicitud RADIUS actual.

> Nota: Una petición debe ser creada mediante la función radius_create_request() antes de que esta función pueda ser llamada.

### Parámetros

`radius_handle`
  El recurso RADIUS.
`type`
  El tipo de atributo.
`addr`
  Una dirección IPv4; por ejemplo `10.0.0.1`.
`options`
  Una máscara de opciones de atributo. Las opciones disponibles incluyen `RADIUS_OPTION_TAGGED` y `RADIUS_OPTION_SALT`.
`tag`
  La etiqueta del atributo. Este parámetro es ignorado mientras que la opción `RADIUS_OPTION_TAGGED` esté definida.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL radius 1.3.0 | Los parámetros `options` y `tag` fueron añadidos.

# radius_put_attr

(PECL radius >= 1.1.0)

radius_put_attr — Adjunta un atributo binario

### Descripción

function radius_put_attr(
resource `$radius_handle`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Adjunta un atributo binario a la petición RADIUS actual.

> Nota: Una petición debe ser creada mediante la función radius_create_request() antes de que esta función pueda ser llamada.

### Parámetros

`radius_handle`
  El recurso RADIUS.
`type`
  El tipo de atributo.
`value`
  El valor del atributo, que será tratado como un string sin tratar.
`options`
  Una máscara de opciones de atributo. Las opciones disponibles incluyen `RADIUS_OPTION_TAGGED` y `RADIUS_OPTION_SALT`.
`tag`
  La etiqueta del atributo. Este parámetro es ignorado mientras que la opción `RADIUS_OPTION_TAGGED` esté definida.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL radius 1.3.0 | Los parámetros `options` y `tag` han sido añadidos.

### Ejemplos

Ejemplo #1 Ejemplo con radius_put_attr()

    <?php
    mt_srand(time());
    $chall = mt_rand();
    $chapval = hash('md5', pack('Ca*',1 , 'sepp' . $chall));
    $pass = pack('CH*', 1, $chapval);
    if (!radius_put_attr($res, RADIUS_CHAP_PASSWORD, $pass)) {
        echo 'RadiusError:' . radius_strerror($res). "\n<br />";
        exit;
    }
    ?>

### Ver también

- radius_get_attr() - Extrae un atributo
- radius_get_vendor_attr() - Extrae un atributo específico del proveedor
- radius_put_vendor_attr() - Adjunta un atributo binario a un proveedor específico

# radius_put_int

(PECL radius >= 1.1.0)

radius_put_int — Adjunta un atributo entero

### Descripción

function radius_put_int(
resource `$radius_handle`,
int `$type`,
int `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Adjunta un atributo entero a la petición RADIUS actual.

> Nota: Una petición debe ser creada mediante la función radius_create_request() antes de que esta función pueda ser llamada.

### Parámetros

`radius_handle`
  El recurso RADIUS.
`type`
  El tipo de atributo.
`value`
  El valor del atributo.
`options`
  Una máscara de opciones de atributo. Las opciones disponibles incluyen `RADIUS_OPTION_TAGGED` y `RADIUS_OPTION_SALT`.
`tag`
  La etiqueta del atributo. Este parámetro es ignorado mientras que la opción `RADIUS_OPTION_TAGGED` esté definida.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL radius 1.3.0 | Los parámetros `options` y `tag` han sido añadidos.

### Ejemplos

Ejemplo #1 Ejemplo con radius_put_int()

    <?php
    if (!radius_put_int($res, RAD_FRAMED_PROTOCOL, RAD_PPP)) {
       echo 'Error Radius :' . radius_strerror($res). "\n<br />";
       exit;
    }
    ?>

### Ver también

- radius_put_string() - Adjunta un atributo de tipo string
- radius_put_vendor_int() - Adjunta un atributo entero a un proveedor específico
- radius_put_vendor_string() - Adjunta un atributo en forma de string a un vendedor específico

# radius_put_string

(PECL radius >= 1.1.0)

radius_put_string — Adjunta un atributo de tipo string

### Descripción

function radius_put_string(
resource `$radius_handle`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Adjunta un atributo en forma de string a la petición RADIUS actual. Generalmente, la función radius_put_attr() es más útil para esto, ya que es segura a nivel de bits.

> Nota: Una petición debe ser creada mediante la función radius_create_request() antes de que esta función pueda ser llamada.

### Parámetros

`radius_handle`
  El recurso RADIUS.
`type`
  El tipo de atributo.
`value`
  El valor del atributo. Este valor es esperado por la biblioteca subyacente como terminado por `null` ; por lo tanto, este parámetro no es seguro a nivel de bits.
`options`
  Una máscara de opciones de atributo. Las opciones disponibles incluyen `RADIUS_OPTION_TAGGED` y `RADIUS_OPTION_SALT`.
`tag`
  La etiqueta del atributo. Este parámetro es ignorado mientras que la opción `RADIUS_OPTION_TAGGED` esté definida.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL radius 1.3.0 | Los parámetros `options` y `tag` fueron añadidos.

### Ejemplos

Ejemplo #1 Ejemplo con radius_put_string()

    <?php
    if (!radius_put_string($res, RADIUS_USER_NAME, 'billy')) {
        echo 'Error Radius :' . radius_strerror($res). "\n<br />";
        exit;
    }
    ?>

### Ver también

- radius_put_int() - Adjunta un atributo entero
- radius_put_vendor_int() - Adjunta un atributo entero a un proveedor específico
- radius_put_vendor_string() - Adjunta un atributo en forma de string a un vendedor específico

# radius_put_vendor_addr

(PECL radius >= 1.1.0)

radius_put_vendor_addr — Asocia una dirección IP específica a un proveedor

### Descripción

function radius_put_vendor_addr(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
string `$addr`
): bool

Asocia una dirección IP específica al proveedor para la solicitud RADIUS actual.

> Nota: Una petición debe ser creada mediante la función radius_create_request() antes de que esta función pueda ser llamada.

### Parámetros

`radius_handle`
  El recurso RADIUS.
`vendor`
  El identificador del proveedor.
`type`
  El tipo de atributo.
`addr`
  Una dirección IPv4; por ejemplo `10.0.0.1`.
`options`
  Una máscara de opciones de atributo. Las opciones disponibles incluyen `RADIUS_OPTION_TAGGED` y `RADIUS_OPTION_SALT`.
`tag`
  La etiqueta del atributo. Este parámetro es ignorado mientras que la opción `RADIUS_OPTION_TAGGED` esté definida.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL radius 1.3.0 | Se han añadido los parámetros `options` y `tag`.

# radius_put_vendor_attr

(PECL radius >= 1.1.0)

radius_put_vendor_attr — Adjunta un atributo binario a un proveedor específico

### Descripción

function radius_put_vendor_attr(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Adjunta un atributo binario específico al proveedor para la petición RADIUS actual.

> Nota: Una petición debe ser creada mediante la función radius_create_request() antes de que esta función pueda ser llamada.

### Parámetros

`radius_handle`
  El recurso RADIUS.
`vendor`
  El identificador del proveedor.
`type`
  El tipo de atributo.
`value`
  El valor del atributo, que será tratado como un string sin tratar.
`options`
  Una máscara de opciones de atributo. Las opciones disponibles incluyen `RADIUS_OPTION_TAGGED` y `RADIUS_OPTION_SALT`.
`tag`
  La etiqueta del atributo. Este parámetro es ignorado mientras que la opción `RADIUS_OPTION_TAGGED` esté definida.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL radius 1.3.0 | Los parámetros `options` y `tag` fueron añadidos.

### Ejemplos

Ejemplo #1 Ejemplo con radius_put_vendor_attr()

    <?php
    if (!radius_put_vendor_attr($res, RADIUS_VENDOR_MICROSOFT, RAD_MICROSOFT_MS_CHAP_CHALLENGE, $challenge)) {
        echo 'Error Radius :' . radius_strerror($res). "\n<br />";
        exit;
    }
    ?>

### Ver también

- radius_get_vendor_attr() - Extrae un atributo específico del proveedor

# radius_put_vendor_int

(PECL radius >= 1.1.0)

radius_put_vendor_int — Adjunta un atributo entero a un proveedor específico

### Descripción

function radius_put_vendor_int(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
int `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Adjunta un atributo específico al proveedor en la petición RADIUS actual.

### Parámetros

`radius_handle`
  El recurso RADIUS.
`vendor`
  El identificador del proveedor.
`type`
  El tipo de atributo.
`value`
  El valor del atributo.
`options`
  Una máscara de opciones de atributo. Las opciones disponibles incluyen `RADIUS_OPTION_TAGGED` y `RADIUS_OPTION_SALT`.
`tag`
  La etiqueta del atributo. Este parámetro es ignorado mientras que la opción `RADIUS_OPTION_TAGGED` esté definida.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL radius 1.3.0 | Se han añadido los argumentos `options` y `tag`.

### Ver también

- radius_put_vendor_string() - Adjunta un atributo en forma de string a un vendedor específico

# radius_put_vendor_string

(PECL radius >= 1.1.0)

radius_put_vendor_string — Adjunta un atributo en forma de string a un vendedor específico

### Descripción

function radius_put_vendor_string(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Adjunta un atributo específico al vendedor a la petición actual RADIUS. En general, radius_put_vendor_attr() es una función más práctica para adjuntar atributos, siendo segura a nivel de bits.

### Parámetros

`radius_handle`
  El recurso RADIUS.
`vendor`
  El identificador del proveedor.
`type`
  El tipo de atributo.
`value`
  El valor del atributo. Este valor es esperado por la biblioteca subyacente como terminado por `null` ; por lo tanto, este parámetro no es seguro a nivel de bits.
`options`
  Una máscara de opciones de atributo. Las opciones disponibles incluyen `RADIUS_OPTION_TAGGED` y `RADIUS_OPTION_SALT`.
`tag`
  La etiqueta del atributo. Este parámetro es ignorado mientras que la opción `RADIUS_OPTION_TAGGED` esté definida.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL radius 1.3.0 | Los parámetros `options` y `tag` fueron añadidos.

### Ver también

- radius_put_vendor_int() - Adjunta un atributo entero a un proveedor específico

# radius_request_authenticator

(PECL radius >= 1.1.0)

radius_request_authenticator — Devuelve el identificador solicitado

### Descripción

function radius_request_authenticator(resource `$radius_handle`): string

El identificador solicitado es necesario para la recuperación de datos como contraseñas y claves de cifrado.

### Parámetros

`radius_handle`
  El recurso RADIUS.

### Valores devueltos

Devuelve el identificador solicitado como string o `false` en caso de error.

### Ver también

- radius_demangle() - Deshidrata datos

# radius_salt_encrypt_attr

(PECL radius >= 1.3.0)

radius_salt_encrypt_attr — Cifra un valor utilizando un Salt

### Descripción

function radius_salt_encrypt_attr(resource `$radius_handle`, string `$data`): string|false

Se aplica el algoritmo RADIUS salt al valor proporcionado.

Generalmente, esto se realiza automáticamente al proporcionar la opción `RADIUS_OPTION_SALT` a la función que define el atributo, pero esta función puede ser utilizada si se requiere una construcción de consulta a bajo nivel.

### Parámetros

`data`
  Los datos a cifrar con un salt.

### Valores devueltos

Devuelve los datos cifrados utilizando un salt o `false` si ocurre un error.

### Ver también

- radius_put_addr() - Adjunta una dirección IP como atributo
- radius_put_attr() - Adjunta un atributo binario
- radius_put_int() - Adjunta un atributo entero
- radius_put_string() - Adjunta un atributo de tipo string

# radius_send_request

(PECL radius >= 1.1.0)

radius_send_request — Envía una solicitud y espera una respuesta

### Descripción

function radius_send_request(resource `$radius_handle`): int

Una vez que se ha construido una solicitud Radius, esta es enviada mediante la función radius_send_request().

La función radius_send_request() envía la solicitud y espera una respuesta válida, intentando de nuevo, según el método `round-robin` siempre que sea necesario.

### Parámetros

`radius_handle`
  El recurso RADIUS.

### Valores devueltos

Si se recibe una respuesta válida, radius_send_request() devuelve el código Radius que especifica el tipo de respuesta. Esto es, típicamente, `RADIUS_ACCESS_ACCEPT`, `RADIUS_ACCESS_REJECT` o `RADIUS_ACCESS_CHALLENGE`. Si no se recibe ninguna respuesta válida, radius_send_request() devolverá `false`.

### Ver también

- radius_create_request() - Crea una solicitud de cuenta o de identificación

# radius_server_secret

(PECL radius >= 1.1.0)

radius_server_secret — Devuelve el secreto compartido

### Descripción

function radius_server_secret(resource `$radius_handle`): string

El secreto compartido es necesario para el restablecimiento de los datos como las contraseñas y las claves de cifrado.

### Parámetros

`radius_handle`
  El recurso RADIUS.

### Valores devueltos

Devuelve el secreto compartido del servidor como un string o `false` en caso de error.

# radius_strerror

(PECL radius >= 1.1.0)

radius_strerror — Devuelve un mensaje de error

### Descripción

function radius_strerror(resource `$radius_handle`): string

Si las funciones radio fallan entonces guardan un mensaje de error. Este mensaje de error puede ser obtenido con esta función.

### Parámetros

`radius_handle`
  El recurso RADIUS.

### Valores devueltos

Devuelve mensajes de error como string de funciones radio fallidas.

## Tabla de contenidos

- radius_acct_open — Crea un manejador Radius para el conteo
- radius_add_server — Añade un servidor
- radius_auth_open — Crea un identificador de Radius para la autenticación
- radius_close — Libera todos los recursos
- radius_config — Solicita a la biblioteca que lea un archivo de configuración dado
- radius_create_request — Crea una solicitud de cuenta o de identificación
- radius_cvt_addr — Convierte datos brutos en dirección IP
- radius_cvt_int — Convierte datos brutos en entero
- radius_cvt_string — Convierte datos brutos en string
- radius_demangle — Deshidrata datos
- radius_demangle_mppe_key — Deriva las claves mppe desde datos
- radius_get_attr — Extrae un atributo
- radius_get_tagged_attr_data — Extrae los datos de un atributo
- radius_get_tagged_attr_tag — Extrae la etiqueta desde un atributo
- radius_get_vendor_attr — Extrae un atributo específico del proveedor
- radius_put_addr — Adjunta una dirección IP como atributo
- radius_put_attr — Adjunta un atributo binario
- radius_put_int — Adjunta un atributo entero
- radius_put_string — Adjunta un atributo de tipo string
- radius_put_vendor_addr — Asocia una dirección IP específica a un proveedor
- radius_put_vendor_attr — Adjunta un atributo binario a un proveedor específico
- radius_put_vendor_int — Adjunta un atributo entero a un proveedor específico
- radius_put_vendor_string — Adjunta un atributo en forma de string a un vendedor específico
- radius_request_authenticator — Devuelve el identificador solicitado
- radius_salt_encrypt_attr — Cifra un valor utilizando un Salt
- radius_send_request — Envía una solicitud y espera una respuesta
- radius_server_secret — Devuelve el secreto compartido
- radius_strerror — Devuelve un mensaje de error

- Instalación/Configuración
  - Instalación
- Constantes predefinidas
  - Opciones RADIUS
  - Tipos de paquetes RADIUS
  - Tipos de atributo RADIUS
  - Tipos de atributo RADIUS específicos del vendedor
- Ejemplos
- Funciones Radius
  - radius_acct_open — Crea un manejador Radius para el conteo
  - radius_add_server — Añade un servidor
  - radius_auth_open — Crea un identificador de Radius para la autenticación
  - radius_close — Libera todos los recursos
  - radius_config — Solicita a la biblioteca que lea un archivo de configuración dado
  - radius_create_request — Crea una solicitud de cuenta o de identificación
  - radius_cvt_addr — Convierte datos brutos en dirección IP
  - radius_cvt_int — Convierte datos brutos en entero
  - radius_cvt_string — Convierte datos brutos en string
  - radius_demangle — Deshidrata datos
  - radius_demangle_mppe_key — Deriva las claves mppe desde datos
  - radius_get_attr — Extrae un atributo
  - radius_get_tagged_attr_data — Extrae los datos de un atributo
  - radius_get_tagged_attr_tag — Extrae la etiqueta desde un atributo
  - radius_get_vendor_attr — Extrae un atributo específico del proveedor
  - radius_put_addr — Adjunta una dirección IP como atributo
  - radius_put_attr — Adjunta un atributo binario
  - radius_put_int — Adjunta un atributo entero
  - radius_put_string — Adjunta un atributo de tipo string
  - radius_put_vendor_addr — Asocia una dirección IP específica a un proveedor
  - radius_put_vendor_attr — Adjunta un atributo binario a un proveedor específico
  - radius_put_vendor_int — Adjunta un atributo entero a un proveedor específico
  - radius_put_vendor_string — Adjunta un atributo en forma de string a un vendedor específico
  - radius_request_authenticator — Devuelve el identificador solicitado
  - radius_salt_encrypt_attr — Cifra un valor utilizando un Salt
  - radius_send_request — Envía una solicitud y espera una respuesta
  - radius_server_secret — Devuelve el secreto compartido
  - radius_strerror — Devuelve un mensaje de error

- Radius
  - Instalación/Configuración
  - Constantes predefinidas
  - Ejemplos
  - Funciones Radius

# Extensiones específicas de la línea de comandos

# GNU Readline

# Introducción

Las funciones readline implementan una interfaz de la biblioteca GNU readline. Estas funciones proporcionan líneas de comandos editables. Un ejemplo es proporcionado mostrando cómo Bash permite el uso de las flechas para insertar caracteres o desplazarse por el historial de comandos. Debido a la naturaleza de esta biblioteca, no se debería necesitar en las aplicaciones Web, pero puede ser muy útil durante la escritura de scripts utilizados desde la línea de comandos.

A partir de PHP 7.1.0 esta extensión es soportada en Windows.

Precaución

¡La extensión readline no es thread-safe! Por consiguiente, el uso de esta con cualquier SAPI que sea verdaderamente thread-safe (como Apache mod_winnt) está fuertemente desaconsejado.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución

## Requerimientos

Para utilizar las funciones readline, debe instalarse libreadline. Puede encontrarse libreadline en la página de inicio del proyecto GNU Readline, en » https://tiswww.case.edu/php/chet/readline/rltop.html. Es mantenido por Chet Ramey, quien es también el autor de Bash.

Asimismo, pueden utilizarse estas funciones con la biblioteca libedit, un reemplazo no-GPL de la biblioteca readline. La biblioteca libedit está bajo licencia BSD y disponible para descarga en » http://www.thrysoee.dk/editline/.

## Instalación

Para utilizar estas funciones, es necesario compilar la versión CGI o CLI de PHP con soporte readline. También es necesario utilizar la opción de compilación --with-readline[=DIR]. Si se desea utilizar el reemplazo readline de libedit, configure PHP --with-libedit[=DIR].

En Windows esta extensión está disponible por omisión a partir de PHP 7.1.0.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración Readline
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
cli.pager | "" | `INI_ALL` |
cli.prompt | "\\b \\> " | `INI_ALL` |

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`cli.pager` string
  Herramienta externa para mostrar la salida de la línea de comandos.
`cli.prompt` string
  Véase Línea de Comandos.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`READLINE_LIB` (string)
  La biblioteca utilizada para el soporte de readline; actualmente sea `readline` o `libedit`.

# Funciones Readline

# readline

(PHP 4, PHP 5, PHP 7, PHP 8)

readline — Lee una línea

### Descripción

function readline(?string `$prompt` = `null`): string|false

Devuelve una línea introducida por el usuario. La línea debe ser añadida al historial manualmente, mediante la función readline_add_history().

### Parámetros

`prompt`
  Puede especificarse un string para utilizarlo como prompt al usuario.

### Valores devueltos

Devuelve un string del usuario. La línea devuelta ha sido limpiada del carácter final de nueva línea. Si no hay más datos para leer, entonces se devuelve `false`.

### Ejemplos

Ejemplo #1 Ejemplo con readline()

    <?php
    // Lee 3 comandos del usuario
    for ($i=0; $i < 3; $i++) {
            $line = readline("Comando : ");
            readline_add_history($line);
    }

    // Lista el historial
    print_r(readline_list_history());

    // Lista las variables
    print_r(readline_info());
    ?>

# readline_add_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_add_history — Se añade una línea al historial

### Descripción

function readline_add_history(string `$prompt`): true

Se añade una línea al historial.

### Parámetros

`prompt`
  La línea a añadir al historial.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | El tipo de retorno es ahora `true`, anteriormente era bool.

# readline_callback_handler_install

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_handler_install — Inicializa la interfaz y el terminal de devolución de llamada de readline, muestra el prompt y retorna inmediatamente

### Descripción

function readline_callback_handler_install(string `$prompt`, callable `$callback`): true

Define una interfaz de devolución de llamada para readline, muestra el `prompt` y retorna inmediatamente. Llamar a esta función dos veces sin borrar previamente la interfaz de devolución de llamada anterior borrará automáticamente y correctamente la interfaz antigua.

La funcionalidad de devolución de llamada es muy útil cuando se combina con la función stream_select() que permite la interconexión IO / entrada de usuario, a diferencia de readline().

### Parámetros

`prompt`
  El mensaje de prompt.
`callback`
  La función `callback` toma un argumento: la entrada de usuario retornada.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | El tipo de retorno es ahora `true`, anteriormente era bool.

### Ejemplos

Ejemplo #1 Ejemplo de interfaz de devolución de llamada de Readline

    <?php
    function rl_callback($ret)
    {
        global $c, $prompting;

        echo "You entered: $ret\n";
        $c++;

        if ($c > 10) {
            $prompting = false;
            readline_callback_handler_remove();
        } else {
            readline_callback_handler_install("[$c] Entrar algo: ", 'rl_callback');
        }
    }

    $c = 1;
    $prompting = true;

    readline_callback_handler_install("[$c] Entrar algo: ", 'rl_callback');

    while ($prompting) {
        $w = NULL;
        $e = NULL;
        $n = stream_select($r = array(STDIN), $w, $e, null);
        if ($n && in_array(STDIN, $r)) {
            // lee un carácter, llamará a la función de devolución de llamada cuando se ingrese una nueva línea
            readline_callback_read_char();
        }
    }

    echo "El prompt está desactivado. Todo ha sido realizado.\n";
    ?>

### Ver también

- readline_callback_handler_remove() - Elimina un manejador de devolución de llamada readline
- readline_callback_read_char() - Lee un carácter e informa a la interfaz de devolución de llamada readline
- stream_select() - Supervisa la modificación de uno o varios flujos

# readline_callback_handler_remove

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_handler_remove — Elimina un manejador de devolución de llamada readline

### Descripción

function readline_callback_handler_remove(): bool

Elimina un manejador de devolución de llamada instalado previamente y restaura los parámetros del terminal.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si un manejador de devolución de llamada previamente instalado ha sido eliminado o `false` si no ha sido encontrado.

### Ejemplos

Consulte la función readline_callback_handler_install() para un ejemplo sobre el uso de la interfaz de devolución de llamada readline.

### Ver también

- readline_callback_handler_install() - Inicializa la interfaz y el terminal de devolución de llamada de readline, muestra el prompt y retorna inmediatamente
- readline_callback_read_char() - Lee un carácter e informa a la interfaz de devolución de llamada readline

# readline_callback_read_char

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_read_char — Lee un carácter e informa a la interfaz de devolución de llamada readline

### Descripción

function readline_callback_read_char(): void

Lee un carácter de la entrada del usuario. Cuando se recibe una línea, la función informa a la interfaz de devolución de llamada readline instalada mediante readline_callback_handler_install() de que una línea está lista para ser ingresada.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ver la función readline_callback_handler_install() para un ejemplo sobre el uso de la interfaz de devolución de llamada readline.

### Ver también

- readline_callback_handler_install() - Inicializa la interfaz y el terminal de devolución de llamada de readline, muestra el prompt y retorna inmediatamente
- readline_callback_handler_remove() - Elimina un manejador de devolución de llamada readline

# readline_clear_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_clear_history — Elimina el historial

### Descripción

function readline_clear_history(): true

Elimina el historial.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | El tipo de retorno es ahora `true`, anteriormente era bool.

# readline_completion_function

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_completion_function — Registra una función de completado

### Descripción

function readline_completion_function(callable `$callback`): bool

Registra una nueva función de completado. Es la misma funcionalidad que cuando se utiliza la tecla de tabulación bajo Bash.

### Parámetros

`callback`
  Debe proporcionarse el nombre de una función que acepte un nombre parcial de comando, y devuelva una lista de funciones completas posibles.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# readline_info

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_info — Lee o modifica diversas variables internas de readline

### Descripción

function readline_info(?string `$var_name` = `null`, int|string|bool|null `$value` = `null`): mixed

Lee/modifica diversas variables internas.

### Parámetros

`var_name`
  Un nombre de variable.
`value`
  Si se proporciona, será el nuevo valor a definir.

### Valores devueltos

Cuando se invoca sin parámetros, readline_info() devuelve un array que contiene los valores de los parámetros de Readline. Los elementos estarán indexados por las claves siguientes : `"done"`, `"end"`, `"erase_empty_line"`, `"library_version"`, `"line_buffer"`, `"mark"`, `"pending_input"`, `"point"`, `"prompt"`, `"readline_name"` y `"terminal_name"`. El array solo contendrá los elementos que sean soportados por la biblioteca utilizada para construir la extensión readline.

Si se invoca con uno o dos parámetros, se devuelve el valor anterior.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `var_name` y `value` ahora son nullable.

# readline_list_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_list_history — Lista el historial

### Descripción

function readline_list_history(): array

Lista el historial.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array con la lista de todas las líneas de comandos del historial. Los elementos están indexados numéricamente, a partir de `0`.

# readline_on_new_line

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_on_new_line — Indica a readline que el cursor ha pasado a una nueva línea

### Descripción

function readline_on_new_line(): void

Indica a readline que el cursor ha pasado a una nueva línea.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

### Notas

> Nota: Esta función solo está disponible si es soportada por la biblioteca readline subyacente. No es soportada en Windows.

# readline_read_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_read_history — Lee el historial

### Descripción

function readline_read_history(?string `$filename` = `null`): bool

Lee una línea del historial desde el fichero `filename`.

### Parámetros

`filename`
  Ruta de acceso al fichero que contiene el historial de comandos.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `filename` ahora es nullable.

# readline_redisplay

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_redisplay — Solicita a readline que vuelva a mostrar la información

### Descripción

function readline_redisplay(): void

Solicita a readline que vuelva a mostrar la información.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

# readline_write_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_write_history — Escribe en el historial

### Descripción

function readline_write_history(?string `$filename` = `null`): bool

Escribe el historial en el fichero `filename`.

### Parámetros

`filename`
  Ruta de acceso al fichero a guardar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `filename` ahora es nullable.

## Tabla de contenidos

- readline — Lee una línea
- readline_add_history — Se añade una línea al historial
- readline_callback_handler_install — Inicializa la interfaz y el terminal de devolución de llamada de readline, muestra el prompt y retorna inmediatamente
- readline_callback_handler_remove — Elimina un manejador de devolución de llamada readline
- readline_callback_read_char — Lee un carácter e informa a la interfaz de devolución de llamada readline
- readline_clear_history — Elimina el historial
- readline_completion_function — Registra una función de completado
- readline_info — Lee o modifica diversas variables internas de readline
- readline_list_history — Lista el historial
- readline_on_new_line — Indica a readline que el cursor ha pasado a una nueva línea
- readline_read_history — Lee el historial
- readline_redisplay — Solicita a readline que vuelva a mostrar la información
- readline_write_history — Escribe en el historial

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
- Constantes predefinidas
- Funciones Readline
  - readline — Lee una línea
  - readline_add_history — Se añade una línea al historial
  - readline_callback_handler_install — Inicializa la interfaz y el terminal de devolución de llamada de readline, muestra el prompt y retorna inmediatamente
  - readline_callback_handler_remove — Elimina un manejador de devolución de llamada readline
  - readline_callback_read_char — Lee un carácter e informa a la interfaz de devolución de llamada readline
  - readline_clear_history — Elimina el historial
  - readline_completion_function — Registra una función de completado
  - readline_info — Lee o modifica diversas variables internas de readline
  - readline_list_history — Lista el historial
  - readline_on_new_line — Indica a readline que el cursor ha pasado a una nueva línea
  - readline_read_history — Lee el historial
  - readline_redisplay — Solicita a readline que vuelva a mostrar la información
  - readline_write_history — Escribe en el historial

- Readline — GNU Readline
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones Readline

# Extensiones de compresión y archivos

# Bzip2

# Introducción

Las funciones de bzip2 se utilizan para leer y escribir ficheros comprimidos con bzip2 (.bz2) de forma transparente.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Tipos de recursos

## Requerimientos

Este módulo usa las funciones de la librería » bzip2 por Julian Seward. Este módulo requiere bzip2/libbzip2 version >= 1.0.x.

## Instalación

El soporte de Bzip2 en PHP no está activado por defecto. Se necesita usar la opción de configuración --with-bz2[=DIR] al compilar PHP para activar soporte de bzip2.

## Tipos de recursos

Esta extensión define un tipo de recurso: apunta a un archivo identificando el fichero bz2 a trabajar.

# Ejemplos

Este ejemplo abre un fichero temporal y escribe una cadena de prueba en el, muestra el contenido del fichero.

Ejemplo #1 Pequeño ejemplo de bzip2

    <?php

    $filename = "/tmp/testfile.bz2";
    $str = "Esto es una cadena de prueba.\n";

    // Abriendo fichero para escribir
    $bz = bzopen($filename, "w");

    // escribe la cadena en el fichero
    bzwrite($bz, $str);

    // cierra el fichero
    bzclose($bz);

    // abre el fichero para escritura
    $bz = bzopen($filename, "r");

    // lee 10 caracteres
    echo bzread($bz, 10);

    // muestra salida hasta el final del fichero (o los siguientes 1024 caracteres) y lo cierra.
    echo bzread($bz);

    bzclose($bz);

    ?>

# Funciones de Bzip2

# bzclose

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzclose — Cierra un fichero bzip2

### Descripción

function bzclose(resource `$bz`): bool

Cierra el dado puntero del fichero bzip2.

### Parámetros

`bz`
  El puntero del fichero. Debe ser un puntero válido a un fichero abierto con bzopen() satisfactoriamente.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- bzopen() - Abre un archivo comprimido con bzip2

# bzcompress

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzcompress — Comprime una cadena con bzip2

### Descripción

function bzcompress(string `$data`, int `$block_size` = 4, int `$work_factor` = 0): string|int

bzcompress() comprime la cadena dada y devuelve los datos así codificados.

### Parámetros

`data`
  La cadena a comprimir.
`block_size`
  Especifica el tamaño de bloque utilizado durante la compresión y debe ser un número de 1 a 9, siendo 9 la mejor compresión, pero que utiliza más recursos para realizarse.
`work_factor`
  Controla el comportamiento de la compresión en los peores casos de datos altamente repetitivos. Este valor puede ir de 0 a 250 (0 es un valor especial). Fuera de `work_factor`, el resultado será el mismo.

### Valores devueltos

La cadena comprimida o un número de error si ocurre un error.

### Ejemplos

Ejemplo #1 Compresión de datos

    <?php
    $str = "datos simples";
    $bzstr = bzcompress($str, 9);
    echo $bzstr;
    ?>

### Ver también

- bzdecompress() - Descomprime una cadena bzip2

# bzdecompress

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzdecompress — Descomprime una cadena bzip2

### Descripción

function bzdecompress(string `$data`, bool `$use_less_memory` = `false`): string|int|false

bzdecompress() descomprime la cadena dada que contiene datos comprimidos bzip2.

### Parámetros

`data`
  La cadena a descomprimir.
`use_less_memory`
  Si este argumento es `true`, se utilizará otro algoritmo de descompresión: consume menos memoria (el máximo solicitado ronda los 2300 ko), pero funciona globalmente a la mitad de la velocidad. Consulte la » documentación bzip2 para obtener más detalles sobre esta funcionalidad.

### Valores devueltos

La cadena descomprimida, o `false`, o un número de error si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | El tipo de `use_less_memory` ha sido modificado de int a bool. Anteriormente, el valor por omisión era `0`.

### Ejemplos

Ejemplo #1 Descompresión de una cadena

    <?php
    $start_str = "frase a comprimir";
    $bzstr = bzcompress($start_str);

    echo "Cadena comprimida : ";
    echo $bzstr;
    echo "\n<br />\n";

    $str = bzdecompress($bzstr);
    echo "Cadena descomprimida : ";
    echo $str;
    echo "\n<br />\n";
    ?>

### Ver también

- bzcompress() - Comprime una cadena con bzip2

# bzerrno

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerrno — Devuelve el número de erro de bzip2

### Descripción

function bzerrno(resource `$bz`): int

Devuelve el número de error de cualquier error bzip2 devuelto por el puntero del fichero dado.

### Parámetros

`bz`
  El puntero del fichero. Debe ser un puntero a un fichero abierto con bzopen() satisfactoriamente.

### Valores devueltos

Devuelve el número de error como entero.

### Ver también

- bzerror() - Devuelve el número de error y la cadena del error de bzip2 en un array
- bzerrstr() - Devuelve una cadena de error de bzip2

# bzerror

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerror — Devuelve el número de error y la cadena del error de bzip2 en un array

### Descripción

function bzerror(resource `$bz`): array

Devuelve el número de error y la cadena de error de cualquier error bzip2 devuelto por el puntero del fichero dado.

### Parámetros

`bz`
  El puntero del fichero. Debe ser un puntero a un fichero abierto con bzopen() satisfactoriamente.

### Valores devueltos

Devuelve un array asociativo, con el código de error en la entrada `errno` y el mensaje de error en la entrada `errstr`.

### Ejemplos

Ejemplo #1 Ejemplo de bzerror()

    <?php
    $error = bzerror($bz);

    echo $error["errno"];
    echo $error["errstr"];
    ?>

### Ver también

- bzerrno() - Devuelve el número de erro de bzip2
- bzerrstr() - Devuelve una cadena de error de bzip2

# bzerrstr

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerrstr — Devuelve una cadena de error de bzip2

### Descripción

function bzerrstr(resource `$bz`): string

Obtiene la cadena de error de cualquier error bzip2 devuelto por el puntero dado.

### Parámetros

`bz`
  El puntero del fichero. Debe ser un puntero a un fichero abierto con bzopen() satisfactoriamente.

### Valores devueltos

Devuelve una cadena que contiene el mensaje de error.

### Ver también

- bzerrno() - Devuelve el número de erro de bzip2
- bzerror() - Devuelve el número de error y la cadena del error de bzip2 en un array

# bzflush

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzflush — No realiza ninguna acción

### Descripción

function bzflush(resource `$bz`): bool

Esta función está diseñada para forzar la escritura de todos los datos bzip2 almacenados en el búfer para el puntero de archivo representado por `bz`, pero está implementada como una función nula en libbz2, por lo que no realiza ninguna acción.

### Parámetros

`bz`
  El puntero de archivo. Debe ser válido y debe apuntar a un archivo abierto con éxito por la función bzopen().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- bzread() - Lectura binaria de un archivo bzip2
- bzwrite() - Escritura binaria en un archivo bzip2

# bzopen

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzopen — Abre un archivo comprimido con bzip2

### Descripción

function bzopen(string|resource `$file`, string `$mode`): resource|false

bzopen() abre un archivo bzip2 (.bz2) en modo escritura o lectura.

### Parámetros

`file`
  El nombre del fichero a abrir o un recurso de flujo existente.
`mode`
  Los modos `'r'` (para lectura), y `'w'` (para escritura) son soportados. Cualquier otra opción hará que la función bzopen() retorne `false`.

### Valores devueltos

Si la apertura falla, bzopen() retorna `false`, de lo contrario, retorna un puntero al fichero abierto.

### Ejemplos

Ejemplo #1 Ejemplo con bzopen()

    <?php

    $file = "/tmp/foo.bz2";
    $bz = bzopen($file, "r") or die("Imposible abrir el fichero $file para lectura");

    bzclose($bz);

    ?>

### Ver también

- bzclose() - Cierra un fichero bzip2

# bzread

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzread — Lectura binaria de un archivo bzip2

### Descripción

function bzread(resource `$bz`, int `$length` = 1024): string|false

bzread() lee desde el puntero de archivo bzip2 dado.

La lectura se detiene cuando `length` (no comprimido) caracteres han sido leídos o si se alcanza el final del archivo, el primero de los dos que ocurra.

### Parámetros

`bz`
  El puntero de archivo. Debe ser válido y debe apuntar a un archivo abierto correctamente por la función bzopen().
`length`
  Si no se especifica, bzread() leerá 1024 (no comprimidos) caracteres a la vez. Un máximo de 8192 caracteres no comprimidos serán leídos a la vez.

### Valores devueltos

Devuelve los datos no comprimidos o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con bzread()

    <?php

    $file = "/tmp/foo.bz2";
    $bz = bzopen($file, "r") or die("Imposible abrir el archivo $file");

    $decompressed_file = '';
    while (!feof($bz)) {
      $decompressed_file .= bzread($bz, 4096);
    }
    bzclose($bz);

    echo "El contenido del archivo $file es : <br />\n";
    echo $decompressed_file;

    ?>

### Ver también

- bzwrite() - Escritura binaria en un archivo bzip2
- feof() - Prueba el final del archivo
- bzopen() - Abre un archivo comprimido con bzip2

# bzwrite

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzwrite — Escritura binaria en un archivo bzip2

### Descripción

function bzwrite(resource `$bz`, string `$data`, ?int `$length` = `null`): int|false

bzwrite() escribe una cadena en el flujo de archivo bzip2 dado.

### Parámetros

`bz`
  El puntero de archivo. Debe ser válido y debe apuntar a un archivo abierto correctamente por la función bzopen().
`data`
  Los datos escritos.
`length`
  Si se proporciona, la escritura se detendrá después de que `length` (no comprimidos) bytes hayan sido escritos o bien se alcance el final de `data`, el primero de los dos que ocurra.

### Valores devueltos

Devuelve el número de bytes escritos o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `length` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con bzwrite()

    <?php
    $str = "datos no comprimidos";
    $bz = bzopen("/tmp/foo.bz2", "w");
    bzwrite($bz, $str, strlen($str));
    bzclose($bz);
    ?>

### Ver también

- bzread() - Lectura binaria de un archivo bzip2
- bzopen() - Abre un archivo comprimido con bzip2

## Tabla de contenidos

- bzclose — Cierra un fichero bzip2
- bzcompress — Comprime una cadena con bzip2
- bzdecompress — Descomprime una cadena bzip2
- bzerrno — Devuelve el número de erro de bzip2
- bzerror — Devuelve el número de error y la cadena del error de bzip2 en un array
- bzerrstr — Devuelve una cadena de error de bzip2
- bzflush — No realiza ninguna acción
- bzopen — Abre un archivo comprimido con bzip2
- bzread — Lectura binaria de un archivo bzip2
- bzwrite — Escritura binaria en un archivo bzip2

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Tipos de recursos
- Ejemplos
- Funciones de Bzip2
  - bzclose — Cierra un fichero bzip2
  - bzcompress — Comprime una cadena con bzip2
  - bzdecompress — Descomprime una cadena bzip2
  - bzerrno — Devuelve el número de erro de bzip2
  - bzerror — Devuelve el número de error y la cadena del error de bzip2 en un array
  - bzerrstr — Devuelve una cadena de error de bzip2
  - bzflush — No realiza ninguna acción
  - bzopen — Abre un archivo comprimido con bzip2
  - bzread — Lectura binaria de un archivo bzip2
  - bzwrite — Escritura binaria en un archivo bzip2

# LZF

# Introducción

LZF es un algoritmo de compresión muy rápido, ideal para ahorrar espacio con solamente un ligero costo de velocidad. Puede optimizarse para velocidad o espacio a la hora de compilar. Esta extensión utiliza la librería » liblzf por Marc Lehmann para sus operaciones.

# Instalación/Configuración

## Tabla de contenidos

- Instalación

## Instalación

Esta extensión » PECL no está integrada en PHP. Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/lzf.

Para utilizar estas funciones, PHP debe ser compilado con soporte para LZF mediante la opción de configuración --with-lzf[=DIR]. Asimismo, puede especificarse la opción --enable-lzf-better-compression para optimizar LZF en términos de espacio, aunque esto puede afectar negativamente a la velocidad.

Los usuarios de Windows deben activar la biblioteca php_lzf.dll en el php.ini para poder utilizar estas funciones.

# Funciones LZF

# lzf_compress

(PECL lzf >= 0.1.0)

lzf_compress — Compresión LZF

### Descripción

function lzf_compress(string `$data`): string

lzf_compress() comprime el string `data` dado utilizando codificación LZF.

### Parámetros

`data`
  El string a comprimir.

### Valores devueltos

Devuelve los datos comprimidos o `false` si ocurrió un error.

### Ver también

- lzf_decompress() - Descompresión LZF

# lzf_decompress

(PECL lzf >= 0.1.0)

lzf_decompress — Descompresión LZF

### Descripción

function lzf_decompress(string `$data`): string

lzf_compress() descomprime la cadena `data` dada que contiene los datos codificados en lzf.

### Parámetros

`data`
  La cadena comprimida.

### Valores devueltos

Devuelve los datos descomprimidos o `false` si ocurrió un error.

### Ver también

- lzf_compress() - Compresión LZF

# lzf_optimized_for

(PECL lzf >= 1.0.0)

lzf_optimized_for — Determina para qué fue optimizada la extensión LZF

### Descripción

function lzf_optimized_for(): int

Determina para qué fue optimizada la extensión LZF durante la compilación.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve 1 si LZF fue optimizada para velocidad, 0 para compresión.

## Tabla de contenidos

- lzf_compress — Compresión LZF
- lzf_decompress — Descompresión LZF
- lzf_optimized_for — Determina para qué fue optimizada la extensión LZF

- Instalación/Configuración
  - Instalación
- Funciones LZF
  - lzf_compress — Compresión LZF
  - lzf_decompress — Descompresión LZF
  - lzf_optimized_for — Determina para qué fue optimizada la extensión LZF

# Phar

# Introducción

La extensión phar proporciona un medio para empaquetar una aplicación PHP completa en un único archivo llamado "phar" (PHP Archive) para facilitar la instalación y configuración. Además de este servicio, la extensión también proporciona una clase de abstracción de formato de archivo para crear y manipular archivos tar y zip a través de la clase PharData, de manera similar a como PDO proporciona una interfaz unificada para acceder a diferentes bases de datos. Sin embargo, a diferencia de PDO, que no puede transferir datos entre bases de datos, Phar tiene la capacidad de convertir archivos tar, zip y phar con una sola línea de código. Consulte Phar::convertToExecutable() para obtener un ejemplo.

¿Qué es phar? Las archivos phar son en realidad un medio práctico para agrupar varios archivos en uno solo. Así, un archivo phar permite distribuir una aplicación PHP completa en un único archivo y ejecutarla desde este archivo sin necesidad de extraerlo en el disco. Además, los archivos phar pueden ser ejecutados por PHP tan fácilmente como cualquier otro archivo, tanto desde la línea de comandos como a través de un servidor web. Phar es una especie de memoria USB para aplicaciones PHP.

Phar implementa esta funcionalidad mediante un flujo. Normalmente, para utilizar un archivo externo desde un script PHP, se debe utilizar la función include:

Ejemplo #1 Utilizar un archivo externo

    <?php
     include '/ruta/al/archivo/externo.php';
     ?>

Puede considerarse que PHP convierte en realidad `/ruta/al/archivo/externo.php` en un flujo `file:///ruta/al/archivo/externo.php`, y que utiliza de forma oculta las funciones de flujo de archivos planos para acceder a archivos locales.

Para utilizar un archivo llamado `archivo.php` contenido en un archivo phar `/ruta/al/miphar.phar`, la sintaxis es casi similar a la sintaxis `file://` anterior.

Ejemplo #2 Utilizar un archivo contenido en un archivo phar

    <?php
     include 'phar:///ruta/al/miphar.phar/archivo.php';
     ?>

En realidad, un archivo phar puede tratarse como si fuera un disco externo, utilizando cualquiera de las funciones relacionadas con fopen(), opendir() y mkdir() para leer, modificar o crear nuevos archivos o directorios dentro del archivo phar. Esto permite que aplicaciones PHP completas sean distribuidas en un único archivo y ejecutadas desde él.

El uso más común de un archivo phar es distribuir una aplicación completa en un único archivo. Por ejemplo, el instalador PEAR que se incluye con las versiones de PHP se distribuye mediante un archivo phar. Para utilizar el archivo phar distribuido de esta manera, este puede ser ejecutado mediante la línea de comandos o a través de un navegador web.

Los archivos phar pueden distribuirse en formato `tar`, `zip` o en el formato `phar` especialmente diseñado para la extensión phar. Cada formato de archivo tiene sus ventajas e inconvenientes. Los archivos zip y tar pueden ser extraídos por cualquier herramienta de terceros que pueda leer el formato, pero requieren la extensión phar para ser ejecutados por PHP. El formato de archivo phar es único y dedicado a la extensión phar y solo puede ser creado por esta o por el paquete PEAR » PHP_Archive, pero tiene la ventaja de no requerir la instalación de la extensión phar para que la aplicación empaquetada pueda ser ejecutada.

En otras palabras, incluso con la extensión phar desactivada, es posible ejecutar o incluir un archivo basado en phar. Acceder a archivos individuales dentro de un archivo phar solo es posible con la extensión phar a menos que el archivo phar haya sido creado por PHP_Archive.

La extensión phar también es capaz de convertir un archivo phar desde un tar hacia un archivo zip o phar con un solo comando:

Ejemplo #3 Convertir un archivo phar al formato tar

    <?php
     $phar = new Phar('miphar.phar');
     $pgz = $phar->convertToExecutable(Phar::TAR, Phar::GZ); // produce miphar.phar.tar.gz
     ?>

Phar puede comprimir archivos individuales o un archivo completo utilizando la compresión gzip o bzip2, y puede verificar la integridad del archivo automáticamente utilizando funciones de firma MD5, SHA-1, SHA-256 o SHA-512.

Finalmente, la extensión phar está orientada a la seguridad, desactiva por defecto los accesos de escritura en archivos phar ejecutables y requiere la desactivación a nivel de sistema del parámetro `phar.readonly` del php.ini para crear o modificar archivos phar. Los archivos tar y zip sin el marcador ejecutable pueden ser siempre creados o modificados utilizando la clase PharData.

Si se crean aplicaciones con el propósito de distribuirlas, se debe leer Cómo crear archivos Phar. Si se desea más información sobre las diferencias entre los formatos de archivo que phar soporta, se debe leer Phar, Tar y Zip.

Si se utilizan aplicaciones phar, hay trucos muy útiles en Cómo utilizar archivos Phar.

La palabra `phar` es la contracción de `PHP` y de `Archive` y está fuertemente inspirada en la palabra `jar` (Java Archive) familiar a los desarrolladores Java.

La implementación de los archivos Phar se basa en el paquete PEAR » PHP_Archive, y los detalles de implementación son los mismos, aunque la extensión Phar es más potente. Además, esta permite que la mayoría de las aplicaciones PHP sean ejecutadas sin modificación mientras que los archivos basados en PHP_Archive requieren a menudo muchas modificaciones para funcionar.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución
- Tipos de recursos

## Requerimientos

Puede ser deseable activar las extensiones zlib y bzip2 para aprovechar el soporte de archivos phar comprimidos. Asimismo, para utilizar las firmas OpenSSL, la extensión OpenSSL debe ser activada.

Si zend.multibyte está activado, zend.detect_unicode también debe estar activado.

## Instalación

La extensión Phar está integrada en PHP y activada por omisión. Para desactivar el soporte de Phar, se utiliza la opción de configuración --disable-phar.

Phar también puede ser instalado desde la extensión PECL para versiones anteriores de PHP, la » página PECL de Phar contiene más información y el registro de cambios.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de Configuración de Flujos y Sistema de Ficheros
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
phar.readonly | "1" | `INI_ALL` |
phar.require_hash | "1" | `INI_ALL` |
phar.cache_list | "" | `INI_SYSTEM` |

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`phar.readonly` bool

  Esta opción deshabilita la modificación o creación de archivos Phar usando el flujo `phar` o el soporte para escritura de objetos Phar. Este ajuste debería estar siempre activado en máquinas de producción, ya que el soporte para escritura conveniente de la extensión phar podría permitir la simple creación de un virus basado en PHP al asociarse con otras vulnerabilidades de seguridad comunes.

  > Nota:

  > Este ajuste sólo puede ser desactivado en php.ini por motivos de seguridad. Si `phar.readonly` está deshabilitado en php.ini, un usuario puede habilitar `phar.readonly` en un script o deshabilitarlo después. Si `phar.readonly` está habilitado en php.ini, un scrip puede "re-habilitar" inofensivamente la variable INI, pero no puede deshabilitarla.

`phar.require_hash` bool

  Esta opción forzará a todos los archivos Phar abiertos a que contengan algún tipo de signatura (actualmente está soportadas MD5, SHA1, SHA256 y SHA512), y rehusará procesar cualquer archivo Phar que no contenga una signatura.

  > Nota:

  > Este ajuste sólo puede ser desactivado en php.ini por motivos de seguridad. Si `phar.require_hash` está deshabilitado en php.ini, un usuario puede habilitar `phar.require_hash` en un script o deshabilitarlo después. Si `phar.require_hash` está habilitado en php.ini, un scrip puede "re-habilitar" inofensivamente la variable INI, pero no puede deshabilitarla.

  > Este ajuste no afecta a la lectura de ficheros tar planos con la clase PharData.

  Precaución

  `phar.require_hash` no proporciona ninguna seguridad per se, es simplemente una medida contra la ejecución accidental de archivos Phar corruptos, porque cualquiera que pueda alterar el Phar podría corregir fácilmente la firma.

`phar.cache_list` string

  Permite mapear archivos phar para que sean preanalizados en el arranque del servidor web, proporcionando una mejora de rendimiento que saca ficheros en ejecución de un archivo phar casi tan rápido como si esos ficheros se ejecutaran desde una instalación tradicional basada en disco.

  Ejemplo #1 Ejemplo de uso de phar.cache_list

      en php.ini (windows):
      phar.cache_list =C:\ruta\a\phar1.phar;C:\ruta\a\phar2.phar
      en php.ini (unix):
      phar.cache_list =/ruta/a/phar1.phar:/ruta/a/phar2.phar

## Tipos de recursos

La extensión Phar proporciona el flujo `phar`, que permite el acceso de forma transparente a los ficheros contenidos en un phar. Para más información, consulte el formato de archivo Phar

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

Las constantes de compresión Phar
Constante | Valor | Descripción
--- | --- | ---
`Phar::NONE` (int) | 0x00000000 | ninguna compresión
`Phar::COMPRESSED` (int) | 0x0000F000 | máscara de bits que puede ser utilizada con los flags de fichero para determinar si se utiliza una compresión
`Phar::GZ` (int) | 0x00001000 | compresión zlib (gzip)
`Phar::BZ2` (int) | 0x00002000 | compresión bzip2

Las constantes de formato de fichero Phar
Constante | Valor | Descripción
--- | --- | ---
`Phar::PHAR` (int) | 1 | formato de fichero phar
`Phar::TAR` (int) | 2 | formato de fichero tar
`Phar::ZIP` (int) | 3 | formato de fichero zip

Las constantes de firma Phar
Constante | Valor | Descripción
--- | --- | ---
`Phar::MD5` (int) | 0x0001 | firma con el algoritmo md5
`Phar::SHA1` (int) | 0x0002 | firma con el algoritmo sha1
`Phar::SHA256` (int) | 0x0003 | firma con el algoritmo sha256 (requiere la extensión hash)
`Phar::SHA512` (int) | 0x0004 | firma con el algoritmo sha512 (requiere la extensión hash)
`Phar::OPENSSL` (int) | 0x0010 | firma con un par de claves privada/pública OpenSSL. Es una verdadera firma de clave asimétrica
`Phar::OPENSSL_SHA256` (int) |  |
`Phar::OPENSSL_SHA512` (int) |  |

Las constantes de sobrescritura de mime Phar webPhar
Constante | Valor | Descripción
--- | --- | ---
`Phar::PHP` (int) | 0 | utilizada para especificar el argumento de sobrescritura mime de Phar::webPhar() y hacer que la extensión sea analizada como un fichero PHP
`Phar::PHPS` (int) | 1 | utilizada para especificar el argumento de sobrescritura mime de Phar::webPhar() y hacer que la extensión sea analizada como un fichero PHP mediante highlight_file()

# Utilizar los archivos Phar

## Tabla de contenidos

- Utilizar los archivos Phar : Introducción
- Utilizar los archivos Phar : el flujo phar
- Utilizar los archivos Phar : las clases Phar y PharData

## Utilizar los archivos Phar : Introducción

Los archivos Phar son idénticos en concepto a los archivos JAR de Java, pero están diseñados específicamente para las necesidades y la flexibilidad de las aplicaciones PHP. Un archivo Phar se utiliza para distribuir una aplicación PHP completa o una biblioteca en forma de un único archivo. Una aplicación en forma de archivo Phar se utiliza exactamente de la misma forma que cualquier otra aplicación PHP:

    php aplicacionesympa.phar

El uso de una biblioteca en forma de archivo Phar es el mismo que cualquier otra biblioteca PHP:

    <?php
    include 'bibliothequesympa.phar';
    ?>

El flujo `phar` proporciona el núcleo de la extensión phar, y es descrito en detalle aquí. El flujo phar permite el acceso a los ficheros contenidos en un archivo phar mediante las funciones estándar de ficheros fopen(), opendir(), y cualquier otra que funcione con ficheros normales. El flujo `phar` soporta todas las operaciones de lectura/escritura tanto en ficheros como en directorios.

    <?php
    include 'phar://bibliothequesympa.phar/fichero/interne.php';
    header('Content-type: image/jpeg');
    // los phars pueden ser alcanzados mediante la ruta completa o mediante alias
    echo file_get_contents('phar:///ruta/completa/hacia/bibliothequesympa.phar/images/wow.jpg');
    ?>

La clase Phar implementa funcionalidades avanzadas para acceder a los ficheros y crear archivos phar. La clase Phar es descrita en detalle aquí.

    <?php
    try {
        // abre un phar existente
        $p = new Phar('bibliothequesympa.phar', 0);
        // Phar extiende la clase DirectoryIterator de SPL
        foreach (new RecursiveIteratorIterator($p) as $file) {
            // $file es una clase PharFileInfo y heredada de SplFileInfo
            echo $file->getFileName() . "\n";
            echo file_get_contents($file->getPathName()) . "\n"; // muestra el contenido;
        }
        if (isset($p['fichero/interne.php'])) {
            var_dump($p['fichero/interne.php']->getMetadata());
        }

        // crea un nuevo phar - phar.readonly debe ser 0 en php.ini
        // phar.readonly está activado por omisión por razones de seguridad.
        // En servidores de producción, los Phars no necesitan ser creados,
        // solo ejecutados.
        if (Phar::canWrite()) {
            $p = new Phar('nuevophar.tar.phar', 0, 'nuevophar.tar.phar');
            // Se crea un archivo Phar basado en tar, comprimido por gzip (.tar.gz)
            $p = $p->convertToExecutable(Phar::TAR, Phar::GZ);

            // crea una transacción - nada se escribe en nuevophar.phar
            // hasta que stopBuffering() sea llamado, aunque se requiere almacenamiento temporal
            $p->startBuffering();
            // añade todos los ficheros de /ruta/hacia/elproyecto en el phar con el prefijo "proyecto"
            $p->buildFromIterator(new RecursiveIteratorIterator(new RecursiveDirectoryIterator('/ruta/hacia/elproyecto')), '/ruta/hacia/');

            // añade un nuevo fichero utilizando la API de acceso por array
            $p['fichero1.txt'] = 'Información';
            $fp = fopen('grosfichero.dat', 'rb');
            // copia todos los datos del flujo
            $p['data/grosfichero.dat'] = $fp;

            if (Phar::canCompress(Phar::GZ)) {
                $p['data/grosfichero.dat']->compress(Phar::GZ);
            }

            $p['images/wow.jpg'] = file_get_contents('images/wow.jpg');
            // cualquier valor puede ser guardado como metadatos específicos del fichero
            $p['images/wow.jpg']->setMetadata(array('mime-type' => 'image/jpeg'));
            $p['index.php'] = file_get_contents('index.php');
            $p->setMetadata(array('bootstrap' => 'index.php'));

            // guarda el archivo phar en el disco
            $p->stopBuffering();
        }
    } catch (Exception $e) {
        echo 'No ha podido abrir el Phar: ', $e;
    }
    ?>

Por otro lado, la verificación del contenido del archivo phar puede realizarse utilizando uno de los algoritmos de firma simétrica (MD5, SHA1, SHA256 y SHA512 si ext/hash está activada) y utilizando la firma asimétrica por clave pública/privada de OpenSSL. Para aprovechar la firma OpenSSL, debe generarse un par de claves pública/privada y utilizar la clave privada para firmar con Phar::setSignatureAlgorithm(). Además, la clave pública, extraída utilizando este código:

    <?php
    $public = openssl_get_publickey(file_get_contents('private.pem'));
    $pkey = '';
    openssl_pkey_export($public, $pkey);
    ?>

debe ser guardada por separado del archivo phar que verifica. Si el archivo phar es guardado como `/ruta/hacia/mi.phar`, la clave pública debe ser guardada como `/ruta/hacia/mi.phar.pubkey`, de lo contrario phar no será capaz de verificar la firma OpenSSL.

La clase Phar también proporciona tres métodos estáticos, Phar::webPhar(), Phar::mungServer() y Phar::interceptFileFuncs() que son cruciales para empaquetar aplicaciones PHP destinadas a ser utilizadas en un sistema de ficheros clásico o como aplicación web. Phar::webPhar() implementa un controlador que enruta las llamadas HTTP al lugar correcto del archivo phar. Phar::mungServer() se utiliza para modificar los valores del array $_SERVER para indicar a las aplicaciones que utilicen estos valores. Phar::interceptFileFuncs() indica a Phar que intercepte las llamadas a fopen(), file_get_contents(), opendir(), y a todas las funciones basadas en stat (file_exists(), is_readable(), etc) y enruta todos los caminos relativos a los lugares correctos del archivo phar.

Por ejemplo, empaquetar una versión de la famosa aplicación phpMyAdmin en un archivo phar requiere simplemente este script y, a partir de entonces, `phpMyAdmin.phar.tar.php` puede ser accedido como un fichero clásico desde su servidor web, después de haber modificado la pareja usuario/contraseña:

    <?php
    @unlink('phpMyAdmin.phar.tar.php');
    copy('phpMyAdmin-2.11.3-english.tar.gz', 'phpMyAdmin.phar.tar.php');
    $a = new Phar('phpMyAdmin.phar.tar.php');
    $a->startBuffering();
    $a["phpMyAdmin-2.11.3-english/config.inc.php"] = '<?php
    /* Servers configuration */
    $i = 0;

    /* Server localhost (config:root) [1] */
    $i++;
    $cfg[\'Servers\'][$i][\'host\'] = \'localhost\';
    $cfg[\'Servers\'][$i][\'extension\'] = \'mysqli\';
    $cfg[\'Servers\'][$i][\'connect_type\'] = \'tcp\';
    $cfg[\'Servers\'][$i][\'compress\'] = false;
    $cfg[\'Servers\'][$i][\'auth_type\'] = \'config\';
    $cfg[\'Servers\'][$i][\'user\'] = \'root\';
    $cfg[\'Servers\'][$i][\'password\'] = \'\';

    /* End of servers configuration */
    if (strpos(PHP_OS, \'WIN\') !== false) {
        $cfg[\'UploadDir\'] = getcwd();
    } else {
        $cfg[\'UploadDir\'] = \'/tmp/pharphpmyadmin\';
        @mkdir(\'/tmp/pharphpmyadmin\');
        @chmod(\'/tmp/pharphpmyadmin\', 0777);
    }';
    $a->setStub('<?php
    Phar::interceptFileFuncs();
    Phar::webPhar("phpMyAdmin.phar", "phpMyAdmin-2.11.3-english/index.php");
    echo "phpMyAdmin está destinado a ser ejecutado desde un navegador web\n";
    exit -1;
    __HALT_COMPILER();
    ');
    $a->stopBuffering();
    ?>

## Utilizar los archivos Phar : el flujo phar

El flujo Phar soporta totalmente fopen() para las lecturas/escrituras (no las concatenaciones), unlink(), stat(), fstat(), fseek(), rename(), y las operaciones de flujo sobre los directorios opendir(), y rmdir() y mkdir().

La compresión y los metadatos individuales por fichero pueden también ser manipulados dentro del archivo Phar utilizando los contextos de flujo:

    <?php
    $context = stream_context_create(array('phar' =>
                                        array('compress' => Phar::GZ)),
                                        array('metadata' => array('user' => 'cellog')));
    file_put_contents('phar://mon.phar/unfichero.php', 0, $context);
    ?>

El flujo `phar` no actúa sobre los ficheros remotos y no puede considerar los ficheros remotos, etc... incluso si las opciones INI allow_url_fopen y allow_url_include están desactivadas.

Aunque es posible crear archivos phar desde cero utilizando solo las operaciones sobre los flujos, es preferible utilizar la funcionalidad incluida en la clase Phar. El flujo es mejor utilizado para las operaciones de lectura.

## Utilizar los archivos Phar : las clases Phar y PharData

La clase Phar soporta la lectura y la manipulación de los archivos Phar, así como la iteración a través de la funcionalidad heredada de la clase RecursiveDirectoryIterator. Con el soporte de la interfaz ArrayAccess, los ficheros contenidos en un archivo Phar pueden ser accedidos como si fueran miembros de un array asociativo.

La clase PharData extiende la clase Phar, y permite la creación y modificación de archivos tar y zip no ejecutables (datos) incluso si `phar.readonly`=1 en php.ini. Por lo tanto, PharData::setAlias() y PharData::setStub() están ambas desactivadas ya que los conceptos de alias y contenedor están restringidos a los archivos phar ejecutables.

Es importante señalar que cuando un archivo Phar es creado, la ruta completa debe ser pasada al constructor del objeto Phar. Una ruta relativa impediría la inicialización.

Suponiendo que `$p` es un objeto inicializado de esta forma:

    <?php
    $p = new Phar('/ruta/hacia/miphar.phar', 0, 'miphar.phar');
    ?>

Un archivo Phar vacío será creado como `/ruta/hacia/miphar.phar`, o si `/ruta/hacia/miphar.phar` ya existe, será abierto de nuevo. El término `miphar.phar` demuestra el concepto de un alias que puede ser utilizado para referenciar `/ruta/hacia/miphar.phar` en URLs como esto:

    <?php
    // estas dos llamadas a file_get_contents() son equivalentes si
    // /ruta/hacia/miphar.phar tiene un alias explícito de "miphar.phar"
    // en su manifiesto, o si el phar fue inicializado con la instanciación de
    // el objeto Phar del ejemplo anterior
    $f = file_get_contents('phar:///ruta/hacia/miphar.phar/algo.txt');
    $f = file_get_contents('phar://miphar.phar/algo.txt');
    ?>

Con el objeto Phar `$p` recién creado, las siguientes cosas son posibles:

- `$a = $p['fichero.php']` crea una PharFileInfo que se refiere al contenido de `phar://miphar.phar/fichero.php`
- `$p['fichero.php'] = $v` crea un nuevo fichero (`phar://miphar.phar/fichero.php`), o sobrescribe un fichero existente dentro de `miphar.phar`. `$v` puede ser una cadena o un puntero a un fichero abierto, en cuyo caso el contenido del fichero será utilizado para crear el nuevo fichero. Tenga en cuenta que `$p->addFromString('fichero.php', $v)` es equivalente en términos de funcionalidad al caso anterior. También es posible añadir el contenido de un fichero con `$p->addFile('/ruta/hacia/fichero.php', 'fichero.php')`. Finalmente, un directorio vacío puede ser creado con `$p->addEmptyDir('vacío')`.
- `isset($p['fichero.php'])` puede ser utilizado para determinar si `phar://miphar.phar/fichero.php` existe dentro de `miphar.phar`.
- `unset($p['fichero.php'])` elimina `phar://miphar.phar/fichero.php` de `miphar.phar`.

Además, el objeto Phar es el único medio de acceder a los metadatos específicos de Phar, mediante Phar::getMetadata(), y es también el único medio de establecer o recuperar el contenedor del cargador del archivo Phar mediante Phar::getStub() y Phar::setStub(). Además, la compresión para el archivo Phar completo puede ser manipulada solo mediante la clase Phar.

La lista completa de funcionalidades del objeto Phar está documentada a continuación.

La clase PharFileInfo extiende la clase SplFileInfo y añade varios métodos para manipular los metadatos específicos de Phar de un fichero contenido en un Phar, tales como manipular la compresión o los metadatos.

# Creación de archivos Phar

## Tabla de contenidos

- Creación de archivos Phar: Introducción

## Creación de archivos Phar: Introducción

Para ser escrita completamente en un futuro próximo. Antes de leer esto, asegúrese de leer Como utilizar archivos PHAR.

Un buen lugar para empezar es leer acerca de Phar::buildFromIterator(), y los detalles de la elección del formato de fichero disponible para los archivos. Una adecuada comprensión de lo que es y hace una rutina de interoperabilidad (stub), es crucial para la creación de un archivo PHAR, así Phar::setStub() y Phar::createDefaultStub() son buenos lugares para comenzar. Si va a distribuir una aplicación basada en web es fundamental saber qué es y cómo funciona Phar::webPhar() y el método relacionado Phar::mungServer(). Cualquier aplicación que tenga acceso a sus propios ficheros también debe considerar el uso de Phar::interceptFileFuncs().

# ¿Qué hace que un phar sea un phar y no un tar o un zip?

## Tabla de contenidos

- Los componentes de todas las archivos Phar, independientemente del formato de archivo
- El contenedor de archivo Phar
- Comparación entre Phar, Tar y Zip
- Los phars basados en Tar
- Los phars basados en Zip
- El formato de archivo Phar
- Flags "bitmapped" globales del Phar
- Definición de las entradas del manifiesto Phar
- Formato de firma Phar

## Los componentes de todas las archivos Phar, independientemente del formato de archivo

Todos los archivos Phar contienen de tres a cuatro secciones:

1. Un contenedor

2. Un manifiesto que describe el contenido

3. El contenido del archivo

4. Una firma (opcional) para verificar la integridad (solo con el formato de archivo phar)

## El contenedor de archivo Phar

Un contenedor Phar es un simple archivo PHP. El contenedor mínimo contiene:

    <?php __HALT_COMPILER();

Un contenedor debe contener al menos el token `__HALT_COMPILER();` como conclusión. Típicamente, un contenedor contendrá las siguientes funcionalidades de carga:

    <?php
    Phar::mapPhar();
    include 'phar://monphar.phar/index.php';
    __HALT_COMPILER();

No hay restricciones sobre el contenido de un contenedor Phar, excepto la necesidad de concluir con `__HALT_COMPILER();`. La etiqueta de cierre PHP ``

    ?>

puede ser incluida u omitida, pero no puede haber más de un espacio entre el `;` y la etiqueta de cierre `

    ?>

`, de lo contrario la extensión phar no será capaz de leer el manifiesto del archivo.

En un archivo phar basado en tar o zip, el contenedor se almacena en el archivo `.phar/stub.php`. El contenedor por defecto de los archivos Phar basados en phar contiene aproximadamente 7ko de código para extraer el contenido del phar y ejecutarlo. Consulte la función Phar::createDefaultStub() para más detalles.

El alias phar se almacena, en el caso de un archivo phar basado en tar o zip, en el archivo `.phar/alias.txt` como texto plano.

## Comparación entre Phar, Tar y Zip

¿Cuáles son las ventajas y desventajas de cada uno de los tres formatos soportados por la extensión phar? Esta tabla intenta responder a esta pregunta.

Tabla comparativa: Phar, Tar y Zip
Funcionalidad | Phar | Tar | Zip
--- | --- | --- | ---
Formato de archivo estándar | No | Sí | Sí
Puede ser ejecutado sin la extensión Phar [1] | Sí | No | No
Compresión por archivo | Sí | No | Sí
Compresión para todo el archivo | Sí | Sí | No
Validación por firma de todo el archivo | Sí | Sí | Sí
Soporte de aplicaciones específicamente web | Sí | Sí | Sí
Metadatos por archivo | Sí | Sí | Sí
Metadatos para todo el archivo | Sí | Sí | Sí
Creación/modificación de archivo [2] | Sí | Sí | Sí
Soporte completo de todas las funciones de flujo | Sí | Sí | Sí
Puede ser creado/modificado incluso si phar.readonly=1 [3] | No | Sí | Sí

Sugerencia

[1] PHP no puede acceder directamente al contenido de un archivo Phar sin que la extensión Phar esté instalada si utiliza un `contenedor` que extrae el contenido del archivo phar. El contenedor creado por Phar::createDefaultStub() extrae el archivo phar y ejecuta su contenido desde un directorio temporal si no se encuentra ninguna extensión phar.

Sugerencia

[2] Todos los accesos en escritura requieren que `phar.readonly` esté desactivado en el php.ini o directamente desde la línea de comandos.

Sugerencia

[3] Solo los archivos tar o zip sin `.phar` en su nombre y sin contenedor ejecutable `.phar/stub.php` pueden ser creados si phar.readonly=1.

## Los phars basados en Tar

Los archivos basados en el formato de archivo tar son conformes al formato moderno USTAR. El diseño de los encabezados del archivo tar lo hace más eficiente que el formato de archivo zip y tan eficiente como el formato de archivo phar cuando se trata de acceder a los datos. Los nombres de archivos están limitados a 255 bytes, incluyendo la ruta completa dentro del archivo phar basado en tar. Estos archivos pueden ser completamente comprimidos en formato gzip o bzip2 mientras siguen siendo ejecutables por la extensión Phar.

Hay un soporte limitado para leer los tarballs en el formato pax interchangeable, pero todos los encabezados pax reconocidos (actualmente, typeflag `x` y `g`) son silenciosamente ignorados. También hay un soporte limitado para los archivos GNU Tar; actualmente, los encabezados `././@LongLink` son resueltos.

Para comprimir un archivo completo, utilice Phar::compress(). Para descomprimir un archivo completo, utilice Phar::decompress().

## Los phars basados en Zip

Los archivos basados en el formato de archivo zip soportan numerosas funcionalidades incluidas en el formato zip. Los metadatos por archivo o sobre todo el archivo se almacenan en los comentarios del archivo zip y del archivo zip como una cadena de caracteres serializada. Los comentarios zip ya existentes serán leídos sin problemas como una cadena. Las lecturas/escrituras comprimidas son soportadas por la compresión zlib DEFLATE, y solo las lecturas comprimidas por la compresión bzip2. No hay límite en el número de archivos dentro de un archivo phar basado en zip. Los directorios vacíos se almacenan en el archivo zip como archivos con una barra final, como `mi/directorio/`

## El formato de archivo Phar

El formato de archivo phar está compuesto por contenedor/manifiesto/contenido/firma, y almacena las informaciones cruciales de lo que está contenido en el archivo phar en su `manifiesto`.

El manifiesto Phar es un formato altamente optimizado que permite la especificación archivo por archivo de la compresión, los permisos y hasta metadatos de usuario tales como el usuario o el grupo propietario. Todos los valores de más de un byte son almacenados en formato little-endian, A excepción de la versión de la API que es almacenada por razones históricas en 3 trozos big-endian.

Todos los flags no utilizados están reservados para un uso futuro y no deben ser utilizados para almacenar informaciones personalizadas. Utilice los metadatos por archivo para almacenar metadatos personalizados sobre archivos particulares.

El formato de archivo básico del manifiesto de un archivo Phar es el siguiente:

Formato global del manifiesto Phar
Tamaño en bytes | Descripción
--- | ---
4 bytes | Longitud del manifiesto en bytes (limitada a 1 MB)
4 bytes | Número de archivos en el Phar
2 bytes | Versión de la API del manifiesto Phar (actualmente 1.0.0)
4 bytes | Flags "bitmapped" globales del Phar
4 bytes | Longitud del alias Phar
?? | El alias Phar (longitud basada en el valor anterior)
4 bytes | Longitud de los metadatos Phar (`0` si no hay)
?? | Metadatos Phar serializados, almacenados en un formato serialize()
al menos 24 * bytes de las entradas | Entradas para cada archivo

## Flags "bitmapped" globales del Phar

Estos son los flags "bitmapped" actualmente reconocidos por la extensión Phar para el bitmap completo global de Phar:

Valores de bitmap reconocidos
Valor | Descripción
--- | ---
`0x00010000` | Si está presente, el Phar contiene una firma de verificación
`0x00001000` | Si está presente, el Phar contiene al menos 1 archivo que es comprimido mediante zlib DEFLATE
`0x00002000` | Si está presente, el Phar contiene al menos 1 archivo que es comprimido mediante bzip2

## Definición de las entradas del manifiesto Phar

Cada archivo del manifiesto contiene las siguientes informaciones:

Entrada del manifiesto Phar
Tamaño en bytes | Descripción
--- | ---
4 bytes | Longitud del nombre de archivo en bytes
?? | Nombre de archivo (longitud basada en el valor anterior)
4 bytes | Tamaño del archivo descomprimido en bytes
4 bytes | Timestamp Unix del archivo
4 bytes | Tamaño del archivo comprimido en bytes
4 bytes | Suma de control CRC32 del contenido descomprimido del archivo
4 bytes | Flags bitmapped específicos del archivo
4 bytes | Longitud de los metadatos del archivo serializados (`0` si no hay)
?? | Metadatos del archivo serializados, almacenados en un formato serialize()

Se debe notar que a partir de la API 1.1.1, los directorios vacíos son almacenados como nombres de archivo con una barra final como `mi/directorio/`

Los valores reconocidos de flags bitmapped específicos del archivo son:

Valores reconocidos de bitmap
Valor | Descripción
--- | ---
`0x000001FF` | Estos bits están reservados para definir permisos específicos del archivo. Estos son utilizados para fstat() y pueden ser utilizados para recrear los permisos deseados en caso de extracción.
`0x00001000` | Si está presente, el archivo es comprimido mediante zlib DEFLATE
`0x00002000` | Si está presente, el archivo es comprimido mediante bzip2

## Formato de firma Phar

Los Phar que contienen una firma siempre tienen la firma añadida al final del Phar, después del cargador, el manifiesto y el contenido. Los tipos de firma soportados hasta la fecha son MD5, SHA1, SHA256, SHA512, y OPENSSL.

Formato de firma
Longitud en bytes | Descripción
--- | ---
variante | La firma actual, 20 bytes para una SHA1, 16 bytes para una MD5, 32 bytes para una SHA256, y 64 bytes para una SHA512. La longitud de una firma OPENSSL depende del tamaño de la clave privada.
4 bytes | Los flags de firma. `0x0001` es utilizado para definir una firma MD5, `0x0002` para una SHA1, `0x0003` para una SHA256 y `0x0004` para una SHA512. El soporte para las firmas SHA256 y SHA512 está disponible a partir de la versión 1.1.0 de la API. `0x0010` es utilizado para definir una firma OPENSSL, que está disponible a partir de la versión 1.1.1 de la API, si OpenSSL está disponible.
4 bytes | `GBMB` mágico utilizado para definir la presencia de una firma.

# La clase Phar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

## Introducción

La clase Phar proporciona una interfaz de alto nivel para acceder y crear archivos phar.

## Sinopsis de la Clase

class Phar extends RecursiveDirectoryIterator implements Countable, ArrayAccess {
/* Constantes heredadas */
public const int FilesystemIterator::CURRENT_MODE_MASK;
public const int FilesystemIterator::CURRENT_AS_PATHNAME;
public const int FilesystemIterator::CURRENT_AS_FILEINFO;
public const int FilesystemIterator::CURRENT_AS_SELF;
public const int FilesystemIterator::KEY_MODE_MASK;
public const int FilesystemIterator::KEY_AS_PATHNAME;
public const int FilesystemIterator::FOLLOW_SYMLINKS;
public const int FilesystemIterator::KEY_AS_FILENAME;
public const int FilesystemIterator::NEW_CURRENT_AND_KEY;
public const int FilesystemIterator::OTHER_MODE_MASK;
public const int FilesystemIterator::SKIP_DOTS;
public const int FilesystemIterator::UNIX_PATHS;
/* Constantes */
const int BZ2;
const int GZ;
const int NONE;
const int PHAR;
const int TAR;
const int ZIP;
const int COMPRESSED;
const int PHP;
const int PHPS;
const int MD5;
const int OPENSSL;
const int OPENSSL_SHA256;
const int OPENSSL_SHA512;
const int SHA1;
const int SHA256;
const int SHA512;
/* Métodos */
public function __construct(string `$filename`, int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS, ?string `$alias` = `null`)
public function addEmptyDir(string `$directory`): void
public function addFile(string `$filename`, ?string `$localName` = `null`): void
public function addFromString(string `$localName`, string `$contents`): void
final public static function apiVersion(): string
public function buildFromDirectory(string `$directory`, string `$pattern` = ""): array
public function buildFromIterator(Traversable `$iterator`, ?string `$baseDirectory` = `null`): array
final public static function canCompress(int `$compression` = 0): bool
final public static function canWrite(): bool
public function compress(int `$compression`, ?string `$extension` = `null`): ?Phar
public function compressFiles(int `$compression`): void
public function convertToData(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?PharData
public function convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar
public function copy(string `$from`, string `$to`): true
public function count(int `$mode` = `COUNT_NORMAL`): int
final public static function createDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): string
public function decompress(?string `$extension` = `null`): ?Phar
public function decompressFiles(): true
public function delMetadata(): true
public function delete(string `$localName`): true
public function extractTo(string `$directory`, array|string|null `$files` = `null`, bool `$overwrite` = `false`): bool
public function getAlias(): ?string
public function getMetadata(array `$unserializeOptions` = []): mixed
public function getModified(): bool
public function getPath(): string
public function getSignature(): array|false
public function getStub(): string
final public static function getSupportedCompression(): array
final public static function getSupportedSignatures(): array
public function getVersion(): string
public function hasMetadata(): bool
final public static function interceptFileFuncs(): void
public function isBuffering(): bool
public function isCompressed(): int|false
public function isFileFormat(int `$format`): bool
final public static function isValidPharFilename(string `$filename`, bool `$executable` = `true`): bool
public function isWritable(): bool
final public static function loadPhar(string `$filename`, ?string `$alias` = `null`): bool
final public static function mapPhar(?string `$alias` = `null`, int `$offset` = 0): bool
final public static function mount(string `$pharPath`, string `$externalPath`): void
final public static function mungServer(array `$variables`): void
public function offsetExists(string `$localName`): bool
public function offsetGet(string `$localName`): SplFileInfo
public function offsetSet(string `$localName`, resource|string `$value`): void
public function offsetUnset(string `$localName`): void
final public static function running(bool `$returnPhar` = `true`): string
public function setAlias(string `$alias`): true
public function setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): true
public function setMetadata(mixed `$metadata`): void
public function setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void
public function setStub(resource|string `$stub`, int `$length` = -1): true
public function startBuffering(): void
public function stopBuffering(): void
final public static function unlinkArchive(string `$filename`): true
final public static function webPhar(
?string `$alias` = `null`,
?string `$index` = `null`,
?string `$fileNotFoundScript` = `null`,
array `$mimeTypes` = [],
?callable `$rewrite` = `null`
): void
public function __destruct()
/* Métodos heredados */
public function RecursiveDirectoryIterator::getChildren(): RecursiveDirectoryIterator
public function RecursiveDirectoryIterator::getSubPath(): string
public function RecursiveDirectoryIterator::getSubPathname(): string
public function RecursiveDirectoryIterator::hasChildren(bool `$allowLinks` = `false`): bool
public function RecursiveDirectoryIterator::key(): string
public function RecursiveDirectoryIterator::next(): void
public function RecursiveDirectoryIterator::rewind(): void
public function FilesystemIterator::current(): string|SplFileInfo|FilesystemIterator
public function FilesystemIterator::getFlags(): int
public function FilesystemIterator::key(): string
public function FilesystemIterator::next(): void
public function FilesystemIterator::rewind(): void
public function FilesystemIterator::setFlags(int `$flags`): void
public function DirectoryIterator::current(): mixed
public function DirectoryIterator::getBasename(string `$suffix` = ""): string
public function DirectoryIterator::getExtension(): string
public function DirectoryIterator::getFilename(): string
public function DirectoryIterator::isDot(): bool
public function DirectoryIterator::key(): mixed
public function DirectoryIterator::next(): void
public function DirectoryIterator::rewind(): void
public function DirectoryIterator::seek(int `$offset`): void
public function DirectoryIterator::__toString(): string
public function DirectoryIterator::valid(): bool
public function SplFileInfo::getATime(): int|false
public function SplFileInfo::getBasename(string `$suffix` = ""): string
public function SplFileInfo::getCTime(): int|false
public function SplFileInfo::getExtension(): string
public function SplFileInfo::getFileInfo(?string `$class` = `null`): SplFileInfo
public function SplFileInfo::getFilename(): string
public function SplFileInfo::getGroup(): int|false
public function SplFileInfo::getInode(): int|false
public function SplFileInfo::getLinkTarget(): string|false
public function SplFileInfo::getMTime(): int|false
public function SplFileInfo::getOwner(): int|false
public function SplFileInfo::getPath(): string
public function SplFileInfo::getPathInfo(?string `$class` = `null`): ?SplFileInfo
public function SplFileInfo::getPathname(): string
public function SplFileInfo::getPerms(): int|false
public function SplFileInfo::getRealPath(): string|false
public function SplFileInfo::getSize(): int|false
public function SplFileInfo::getType(): string|false
public function SplFileInfo::isDir(): bool
public function SplFileInfo::isExecutable(): bool
public function SplFileInfo::isFile(): bool
public function SplFileInfo::isLink(): bool
public function SplFileInfo::isReadable(): bool
public function SplFileInfo::isWritable(): bool
public function SplFileInfo::openFile(string `$mode` = "r", bool `$useIncludePath` = `false`, ?resource `$context` = `null`): SplFileObject
public function SplFileInfo::setFileClass(string `$class` = `SplFileObject::class`): void
public function SplFileInfo::setInfoClass(string `$class` = `SplFileInfo::class`): void
public function SplFileInfo::__toString(): string
}

## Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Se añadió el soporte para la extensión de timestamp Unix en archivos basados en Zip.
8.0.0 | Los metadatos ya no se deserializan al abrir el archivo, sino que se posponen hasta que se llama a Phar::getMetadata().

## Notas

Precaución

Antes de PHP 8.0.0, los metadatos se deserializaban al abrir el archivo. Esto podía provocar vulnerabilidades de seguridad. A partir de PHP 8.0.0, los metadatos solo se deserializan al llamar a Phar::getMetadata(), que ofrece opciones para restringir la deserialización por razones de seguridad.

# Phar::addEmptyDir

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addEmptyDir — Añade un directorio vacío al archivo phar

### Descripción

public function Phar::addEmptyDir(string `$directory`): void

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Mediante este método se crea un directorio vacío con la ruta `dirname`. Este método es idéntico a ZipArchive::addEmptyDir().

### Parámetros

`directory`

  El nombre del directorio vacío a crear en el archivo phar

### Valores devueltos

No se devuelve ningún valor, se lanza una excepción en caso de error.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::addEmptyDir()

    <?php
    try {
        $a = new Phar('/ruta/al/archivo.phar');

        $a->addEmptyDir('/ruta/completa/al/fichero');
        // demuestra cómo se almacena el fichero
        $b = $a['ruta/completa/al/fichero']->isDir();
    } catch (Exception $e) {
        // maneja los errores aquí
    }
    ?>

### Ver también

- PharData::addEmptyDir() - Añade un directorio vacío al archivo tar/zip
- Phar::addFile() - Añade un fichero del sistema de ficheros al archivo phar
- Phar::addFromString() - Añade un fichero desde un string al archivo phar

# Phar::addFile

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addFile — Añade un fichero del sistema de ficheros al archivo phar

### Descripción

public function Phar::addFile(string `$filename`, ?string `$localName` = `null`): void

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Mediante este método, cualquier fichero o URL puede ser añadido al archivo phar. Si el segundo parámetro opcional `localName` es un string, el fichero será almacenado en el archivo con ese nombre, de lo contrario el parámetro `filename` se utiliza como ruta hacia donde almacenar el archivo. Las URL deben ser locales, de lo contrario se lanza una excepción. Este método es idéntico a ZipArchive::addFile().

### Parámetros

`filename`

  Ruta absoluta o relativa hacia un fichero del disco a añadir al archivo phar.

`localName`

  Ruta donde el fichero será almacenado en el archivo.

### Valores devueltos

No hay valor de retorno, se lanza una excepción en caso de fallo.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `localName` ahora es nullable.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::addFile()

    <?php
    try {
        $a = new Phar('/ruta/al/phar.phar');

        $a->addFile('/ruta/completa/al/fichero');
        // demuestra cómo el fichero es almacenado
        $b = $a['ruta/completa/al/fichero']->getContent();

        $a->addFile('/ruta/completa/al/fichero', 'mi/fichero.txt');
        $c = $a['mi/fichero.txt']->getContent();

        // demuestra el uso de URL
        $a->addFile('http://www.ejemplo.com', 'ejemplo.html');
    } catch (Exception $e) {
        // maneja los errores aquí
    }
    ?>

### Notas

> Nota: Phar::addFile(), Phar::addFromString() y Phar::offsetSet() registran un nuevo archivo phar cada vez que son llamadas. Si las prestaciones son una preocupación, Phar::buildFromDirectory() o Phar::buildFromIterator() deberían ser utilizadas en su lugar.

### Ver también

- Phar::offsetSet() - Establece el contenido de un fichero interno en el archivo a partir del contenido de un fichero externo
- PharData::addFile() - Añade un fichero del sistema de archivos al archivo tar/zip
- Phar::addFromString() - Añade un fichero desde un string al archivo phar
- Phar::addEmptyDir() - Añade un directorio vacío al archivo phar

# Phar::addFromString

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addFromString — Añade un fichero desde un string al archivo phar

### Descripción

public function Phar::addFromString(string `$localName`, string `$contents`): void

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Esta función permite añadir cualquier string a un archivo phar. El fichero se almacenará en el archivo con `localname` como ruta. Esta función es idéntica a ZipArchive::addFromString().

### Parámetros

`localName`

  Ruta donde el fichero será almacenado en el archivo.

`contents`

  El contenido del fichero a almacenar

### Valores devueltos

No devuelve ningún valor, se lanza una excepción en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con Phar::addFromString()

    <?php
    try {
        $a = new Phar('/ruta/al/archivo.phar');

        $a->addFromString('ruta/al/fichero.txt', 'mi fichero simple');
        $b = $a['ruta/al/fichero.txt']->getContent();

        // para añadir contenido desde un descriptor de flujo para archivos grandes, utilice offsetSet()
        $c = fopen('/ruta/al/archivo_grande.bin');
        $a['archivo_grande.bin'] = $c;
        fclose($c);
    } catch (Exception $e) {
        // manejo de errores aquí
    }
    ?>

### Notas

> Nota: Phar::addFile(), Phar::addFromString() y Phar::offsetSet() registran un nuevo archivo phar cada vez que son llamadas. Si las prestaciones son una preocupación, Phar::buildFromDirectory() o Phar::buildFromIterator() deberían ser utilizadas en su lugar.

### Ver también

- Phar::offsetSet() - Establece el contenido de un fichero interno en el archivo a partir del contenido de un fichero externo
- PharData::addFromString() - Añade un fichero a partir de un string al archivo tar/zip
- Phar::addFile() - Añade un fichero del sistema de ficheros al archivo phar
- Phar::addEmptyDir() - Añade un directorio vacío al archivo phar

# Phar::apiVersion

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::apiVersion — Devuelve la versión de la API

### Descripción

final public static function Phar::apiVersion(): string

Devuelve la versión de la API del formato de archivo phar que será utilizada para la creación de phars. La extensión Phar soporta la lectura de las versiones de API 1.0.0 y superiores. La versión de API 1.1.0 es requerida para los hashes SHA-256 y SHA-512, y la versión de API 1.1.1 es requerida para almacenar directorios vacíos.

### Parámetros

### Valores devueltos

La versión de la API, por ejemplo `"1.0.0"`.

### Ejemplos

Ejemplo #1 Un ejemplo conPhar::apiVersion()

    <?php
    echo Phar::apiVersion();
    ?>

El ejemplo anterior mostrará:

    1.1.1

# Phar::buildFromDirectory

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::buildFromDirectory — Construye un archivo phar a partir de los ficheros de un directorio

### Descripción

public function Phar::buildFromDirectory(string `$directory`, string `$pattern` = ""): array

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Rellena un archivo phar a partir del contenido de un directorio. El segundo parámetro, opcional, es una expresión regular (pcre) utilizada para excluir ficheros. Todo fichero cuyo nombre cumpla la expresión regular será incluido, los demás serán excluidos. Para un control más fino, utilice Phar::buildFromIterator().

### Parámetros

`directory`

  La ruta absoluta o relativa hacia el directorio que contiene todos los ficheros a añadir al archivo.

`pattern`

  Una expresión regular opcional utilizada para filtrar la lista de ficheros. Solo los ficheros cuyo nombre cumpla la expresión regular serán incluidos en el archivo.

### Valores devueltos

Phar::buildFromDirectory() devuelve un array asociativo que hace corresponder la ruta interna del fichero con la ruta completa en el sistema de ficheros.

### Errores/Excepciones

Este método lanza una excepción BadMethodCallException cuando no es capaz de instanciar el iterador de directorio interno, o una excepción PharException si ha habido errores durante el guardado del archivo.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Phar::buildFromDirectory() ya no devuelve `false`.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::buildFromDirectory()

    <?php
    // crea con el alias "proyecto.phar"
    $phar = new Phar('proyecto.phar', 0, 'proyecto.phar');
    // añade ficheros en el proyecto
    $phar->buildFromDirectory(dirname(__FILE__) . '/proyecto');
    $phar->setStub($phar->createDefaultWebStub('cli/index.php', 'www/index.php'));

    $phar2 = new Phar('proyecto2.phar', 0, 'proyecto2.phar');
    // añade todos los ficheros en el proyecto, pero solo los ficheros .php
    $phar->buildFromDirectory(dirname(__FILE__) . '/proyecto', '/\.php$/');
    $phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
    ?>

### Ver también

- Phar::buildFromIterator() - Construye un archivo phar a partir de un iterador

# Phar::buildFromIterator

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::buildFromIterator — Construye un archivo phar a partir de un iterador

### Descripción

public function Phar::buildFromIterator(Traversable `$iterator`, ?string `$baseDirectory` = `null`): array

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Rellena un archivo phar a partir de un iterador. Dos estilos de iterador son soportados: los iteradores que hacen corresponder el nombre de archivo dentro del phar con el nombre de un archivo en el disco, y los iteradores como DirectoryIterator que devuelven objetos SplFileInfo. Para los iteradores que devuelven objetos SplFileInfo, el segundo parámetro es obligatorio.

### Parámetros

`iterator`

  Un iterador que asocia un archivo con una posición, o bien devuelve objetos SplFileInfo.

`baseDirectory`

  Para los iteradores que devuelven objetos SplFileInfo, la porción de ruta absoluta de cada archivo que debe ser eliminada al añadir al archivo phar.

### Valores devueltos

Phar::buildFromIterator() devuelve un array asociativo que asocia la representación interna del archivo a un camino absoluto en el sistema.

### Errores/Excepciones

Este método emite una excepción UnexpectedValueException cuando el iterador devuelve valores falsos, tales como una clave entera en lugar de una cadena; una excepción BadMethodCallException cuando un iterador basado en SplFileInfo es pasado sin parámetro `baseDirectory`, o una excepción PharException si ha habido errores al guardar el archivo phar.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Phar::buildFromIterator() ya no devuelve `false` ahora.
8.0.0 | `baseDirectory` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con Phar::buildFromIterator() y SplFileInfo

Para la mayoría de archivos phar, el archivo refleja la estructura de un directorio, y el segundo estilo es el más útil. Por ejemplo, para crear un archivo phar que contenga los archivos de la estructura del directorio:

    /ruta/hacia/proyecto/
                     config/
                            dist.xml
                            debug.xml
                     lib/
                         file1.php
                         file2.php
                     src/
                         processthing.php
                     www/
                         index.php
                     cli/
                         index.php

Este código puede ser utilizado para añadir al archivo "proyecto.phar":

    <?php
    // crea con el alias "proyecto.phar"
    $phar = new Phar('proyecto.phar', 0, 'proyecto.phar');
    $phar->buildFromIterator(
        new RecursiveIteratorIterator(
         new RecursiveDirectoryIterator('/ruta/hacia/proyecto')),
        '/ruta/hacia/proyecto');
    $phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
    ?>

El archivo proyecto.phar puede ser utilizado inmediatamente. Phar::buildFromIterator() no establece parámetros tales como la compresión o los metadatos; esto puede ser hecho después de crear el archivo phar.

Es interesante notar que Phar::buildFromIterator() también puede ser utilizado para copiar los elementos de un archivo phar existente, ya que el objeto Phar hereda de DirectoryIterator:

    <?php
    // crea con el alias "proyecto.phar"
    $phar = new Phar('proyecto.phar', 0, 'proyecto.phar');
    $phar->buildFromIterator(
        new RecursiveIteratorIterator(
         new Phar('/ruta/hacia/otrophar.phar')),
        'phar:///ruta/hacia/otrophar.phar/ruta/hacia/proyecto');
    $phar->setStub($phar->createDefaultWebStub('cli/index.php', 'www/index.php'));
    ?>

Ejemplo #2 Ejemplo con Phar::buildFromIterator() y otros iteradores

La segunda forma de iterador puede ser utilizada con cualquier iterador que devuelva una correspondencia clave => valor, tales como ArrayIterator:

    <?php
    // crea con el alias "proyecto.phar"
    $phar = new Phar('proyecto.phar', 0, 'proyecto.phar');
    $phar->buildFromIterator(
        new ArrayIterator(
         array(
            'interna/fichero.php' => dirname(__FILE__) . '/unfichero.php',
            'otro/fichero.jpg' => fopen('/ruta/hacia/grande.jpg', 'rb'),
         )));
    $phar->setStub($phar->createDefaultWebStub('cli/index.php', 'www/index.php'));
    ?>

### Ver también

- Phar::buildFromDirectory() - Construye un archivo phar a partir de los ficheros de un directorio

# Phar::canCompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::canCompress — Determina si la extensión phar soporta la compresión utilizando zip o bzip2

### Descripción

final public static function Phar::canCompress(int `$compression` = 0): bool

Este método debe ser utilizado para determinar si la compresión es posible antes de cargar un archivo phar que contiene ficheros comprimidos.

### Parámetros

`compression`

  `Phar::GZ` y `Phar::BZ2` pueden ser utilizadas para determinar si la compresión es posible con zlib o bzip2, respectivamente.

### Valores devueltos

`true` si la compresión/descompresión está disponible, `false` en caso contrario.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::canCompress()

    <?php
    if (Phar::canCompress()) {
        echo file_get_contents('phar://pharcompresse.phar/interne/fichero.txt');
    } else {
        echo 'compresión no disponible';
    }
    ?>

### Ver también

- PharFileInfo::getCompressedSize() - Devuelve el tamaño actual (con compresión) del fichero dentro del archivo Phar
- PharFileInfo::isCompressed() - Indica si la entrada está comprimida
- PharFileInfo::compress() - Comprime la entrada Phar actual con una de las compresiones zlib o bzip2
- PharFileInfo::decompress() - Descomprime la entrada Phar actual dentro del phar
- Phar::isCompressed() - Devuelve Phar::GZ o PHAR::BZ2 si el archivo completo está comprimido (.tar.gz/tar.bz, etc)
- Phar::compressFiles() - Comprime todos los ficheros del archivo Phar actual
- Phar::decompressFiles() - Descomprime todos los ficheros del archivo Phar actual
- Phar::getSupportedCompression() - Devuelve un array de los algoritmos de compresión soportados
- Phar::convertToExecutable() - Convierte un archivo phar a otro formato de archivo de archivo phar ejecutable
- Phar::convertToData() - Convierte un archivo phar en un fichero no ejecutable

# Phar::canWrite

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::canWrite — Determina si la extensión phar soporta la creación y escritura de archivos phar

### Descripción

final public static function Phar::canWrite(): bool

Este método estático determina si el acceso en escritura ha sido desactivado en el php.ini del sistema mediante la variable INI phar.readonly.

### Parámetros

### Valores devueltos

`true` si el acceso en escritura es posible, `false` en caso contrario.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::canWrite()

    <?php
    if (Phar::canWrite()) {
        file_put_contents('phar://monphar.phar/fichero.txt', 'coucou');
    }
    ?>

### Ver también

- phar.readonly
- Phar::isWritable() - Retorna true si el archivo phar puede ser modificado

# Phar::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::compress — Comprime el archivo Phar completo utilizando la compresión Gzip o Bzip2

### Descripción

public function Phar::compress(int `$compression`, ?string `$extension` = `null`): ?Phar

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

En el caso de los archivos phar basados en tar o en phar, este método comprime el archivo completo utilizando la compresión gzip o bzip2. El archivo resultante puede ser procesado con el comando gzip/bzip2, o accedido directamente y de forma transparente con la extensión Phar.

En el caso de los archivos phar basados en Zip, este método falla lanzando una excepción. La extensión zlib debe estar activada para comprimir con gzip, mientras que la extensión bzip2 debe estar activada para comprimir con bzip2. Al igual que con todas las funcionalidades que modifican el contenido de un phar, la variable INI phar.readonly debe estar a off para funcionar.

Además, este método renombra automáticamente el archivo, añadiendo a su nombre `.gz`, `.bz2` o eliminando la extensión si `Phar::NONE` es pasado para eliminar la compresión. De lo contrario, una extensión de archivo puede también ser especificada utilizando el segundo parámetro.

### Parámetros

`compression`

  La compresión debe ser `Phar::GZ`, `Phar::BZ2` para beneficiarse de la compresión, o bien `Phar::NONE` para eliminar la compresión.

`extension`

  Por omisión, la extensión es `.phar.gz` o `.phar.bz2` para comprimir los archivos phar, y `.phar.tar.gz` o `.phar.tar.bz2` para comprimir los archivos tar. Para descomprimir, las extensiones por omisión son `.phar` y `.phar.tar`.

### Valores devueltos

Devuelve un objeto Phar, o `null` en caso de error.

### Errores/Excepciones

Levanta una excepción BadMethodCallException si la variable INI phar.readonly está a on, si la extensión zlib no está disponible, o si la extensión bzip2 no está activada.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `extension` ahora es nullable.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::compress()

    <?php
    $p = new Phar('/ruta/al/mon.phar', 0, 'mon.phar');
    $p['monfichier.txt'] = 'hola';
    $p['monfichier2.txt'] = 'hola';
    $p1 = $p->compress(Phar::GZ); // copia a /ruta/al/mon.phar.gz
    $p2 = $p->compress(Phar::BZ2); // copia a /ruta/al/mon.phar.bz2
    $p3 = $p2->compress(Phar::NONE); // excepción: /ruta/al/mon.phar ya existe
    ?>

### Ver también

- PharFileInfo::getCompressedSize() - Devuelve el tamaño actual (con compresión) del fichero dentro del archivo Phar
- PharFileInfo::isCompressed() - Indica si la entrada está comprimida
- PharFileInfo::compress() - Comprime la entrada Phar actual con una de las compresiones zlib o bzip2
- PharFileInfo::decompress() - Descomprime la entrada Phar actual dentro del phar
- PharData::compress() - Comprime el archivo tar/zip completo utilizando la compresión Gzip o Bzip2
- Phar::canCompress() - Determina si la extensión phar soporta la compresión utilizando zip o bzip2
- Phar::isCompressed() - Devuelve Phar::GZ o PHAR::BZ2 si el archivo completo está comprimido (.tar.gz/tar.bz, etc)
- Phar::decompress() - Descomprime el archivo tar completo
- Phar::getSupportedCompression() - Devuelve un array de los algoritmos de compresión soportados
- Phar::compressFiles() - Comprime todos los ficheros del archivo Phar actual
- Phar::decompressFiles() - Descomprime todos los ficheros del archivo Phar actual

# Phar::compressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::compressFiles — Comprime todos los ficheros del archivo Phar actual

### Descripción

public function Phar::compressFiles(int `$compression`): void

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Para los archivos phar basados en tar, este método lanza una excepción BadMethodCallException ya que la compresión de ficheros individuales dentro de un archivo tar no es soportada por el formato de archivo. Utilice Phar::compress() para comprimir un archivo phar basado en tar en su totalidad.

Para las extensiones phar basadas en Zip, este método comprime todos los ficheros del archivo Phar utilizando la compresión especificada. Las extensiones zlib o bzip2 deben estar activadas para aprovechar esta funcionalidad. Asimismo, si uno o varios ficheros ya han sido comprimidos utilizando la compresión bzip2/zlib, la extensión adecuada debe estar activada para descomprimir los ficheros antes de recomprimirlos. Como con todas las funcionalidades que modifican el contenido de un phar, la variable INI phar.readonly debe estar a off para funcionar.

### Parámetros

`compression`

  La compresión debe ser `Phar::GZ`, `Phar::BZ2` para beneficiarse de la compresión, o bien `Phar::NONE` para eliminar la compresión.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

Lanza una excepción BadMethodCallException si la variable INI phar.readonly está a on, si la extensión zlib no está disponible, o si uno o varios ficheros han sido comprimidos con el algoritmo bzip2 y la extensión bzip2 no está activada.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::compressFiles()

    <?php
    $p = new Phar('/ruta/al/mon.phar', 0, 'mon.phar');
    $p['monfichero.txt'] = 'hola';
    $p['monfichero2.txt'] = 'hola';
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    $p->compressFiles(Phar::GZ);
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    ?>

El ejemplo anterior mostrará:

    string(10) "monfichero.txt"
    bool(false)
    bool(false)
    bool(false)
    string(11) "monfichero2.txt"
    bool(false)
    bool(false)
    bool(false)
    string(10) "monfichero.txt"
    int(4096)
    bool(false)
    bool(true)
    string(11) "monfichero2.txt"
    int(4096)
    bool(false)
    bool(true)

### Ver también

- PharFileInfo::getCompressedSize() - Devuelve el tamaño actual (con compresión) del fichero dentro del archivo Phar
- PharFileInfo::isCompressed() - Indica si la entrada está comprimida
- PharFileInfo::compress() - Comprime la entrada Phar actual con una de las compresiones zlib o bzip2
- PharFileInfo::decompress() - Descomprime la entrada Phar actual dentro del phar
- Phar::canCompress() - Determina si la extensión phar soporta la compresión utilizando zip o bzip2
- Phar::isCompressed() - Devuelve Phar::GZ o PHAR::BZ2 si el archivo completo está comprimido (.tar.gz/tar.bz, etc)
- Phar::decompressFiles() - Descomprime todos los ficheros del archivo Phar actual
- Phar::getSupportedCompression() - Devuelve un array de los algoritmos de compresión soportados
- Phar::compress() - Comprime el archivo Phar completo utilizando la compresión Gzip o Bzip2
- Phar::decompress() - Descomprime el archivo tar completo

# Phar::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::__construct — Construye un objeto de archivo Phar

### Descripción

public function Phar::__construct(string `$filename`, int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS, ?string `$alias` = `null`)

### Parámetros

`filename`

  La ruta hacia un archivo Phar existente o a crear. El nombre del fichero debe contener la extensión .phar.

`flags`

  Los flags a pasar a la clase padre RecursiveDirectoryIterator.

`alias`

  Alias con el cual se debe hacer referencia al archivo al llamar a las funcionalidades de flujo.

### Errores/Excepciones

Levanta una excepción BadMethodCallException si el método es llamado dos veces, o UnexpectedValueException si el archivo no puede ser abierto.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::__construct()

    <?php
    try {
        $p = new Phar('/path/to/my.phar', FilesystemIterator::CURRENT_AS_FILEINFO | FilesystemIterator::KEY_AS_FILENAME,
                      'mon.phar');
    } catch (UnexpectedValueException $e) {
        die('No puede abrir mon.phar');
    } catch (BadMethodCallException $e) {
        echo 'técnicamente, esto no puede ocurrir';
    }
    // ahora funciona
    echo file_get_contents('phar://mon.phar/ejemplo.txt');
    // y funciona como si hubiéramos escrito
    echo file_get_contents('phar:///ruta/al/mon.phar/ejemplo.txt');
    ?>

# Phar::convertToData

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::convertToData — Convierte un archivo phar en un fichero no ejecutable

### Descripción

public function Phar::convertToData(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?PharData

Convierte un archivo phar ejecutable en un fichero tar o zip. Para hacer que el tar o el zip no sea ejecutable, el contenedor phar y el alias phar son eliminados del archivo recién creado.

Si no se especifica ningún cambio, este método lanza una excepción BadMethodCallException si el archivo está en el formato de archivo phar. Para los archivos basados en tar o zip, este método convierte el archivo en un archivo no ejecutable.

En caso de éxito, el método crea un nuevo archivo en el disco y devuelve un objeto PharData. El archivo antiguo no se elimina del disco, lo cual debe hacerse manualmente al final del proceso.

### Parámetros

`format`

  Debe ser uno de los formatos `Phar::TAR` o `Phar::ZIP`. Si este argumento es `null`, se conservará el formato de archivo actual.

`compression`

  Debe ser `Phar::NONE` para ninguna compresión global, `Phar::GZ` para una compresión basada en zlib y `Phar::BZ2` para una compresión basada en bzip2.

`extension`

  Este argumento se utiliza para sobrescribir la extensión por defecto de un archivo convertido. Cabe señalar que `.phar` no puede ser utilizado en el nombre de archivo de un archivo tar o zip no ejecutable.

  Si se convierte a un archivo basado en tar, las extensiones por defecto son `.tar`, `.tar.gz`, y `.tar.bz2` según la compresión especificada. Para los archivos phar basados en zip, la extensión por defecto es `.zip`.

### Valores devueltos

El método devuelve un objeto PharData en caso de éxito, o `null` en caso de fallo.

### Errores/Excepciones

Este método lanza una excepción BadMethodCallException si no es capaz de comprimir, si se ha especificado un método de compresión desconocido o si el archivo solicitado ha sido almacenado en búfer con Phar::startBuffering() sin ser concluido con Phar::stopBuffering(), y lanza una excepción PharException si se ha encontrado algún problema durante la fase de creación del archivo.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `format`, `compression`, y `extension` ahora son nullable.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::convertToData()

Utilización de Phar::convertToData():

    <?php
    try {
        $tarphar = new Phar('monphar.phar.tar');
        // note que monphar.phar.tar no es *eliminado*
        // se convierte al formato de archivo tar no ejecutable
        // crea monphar.tar
        $tar = $tarphar->convertToData();
        // se convierte al formato de archivo zip no ejecutable y crea monphar.zip
        $zip = $tarphar->convertToData(Phar::ZIP);
        // crea monphar.tbz
        $tgz = $tarphar->convertToData(Phar::TAR, Phar::BZ2, '.tbz');
        // crea monphar.phar.tgz
        $phar = $tarphar->convertToData(Phar::PHAR); // lanza una excepción
    } catch (Exception $e) {
        // se manejan los errores aquí
    }
    ?>

### Ver también

- Phar::convertToExecutable() - Convierte un archivo phar a otro formato de archivo de archivo phar ejecutable
- PharData::convertToExecutable() - Convierte un archivo tar/zip no ejecutable en un archivo phar ejecutable
- PharData::convertToData() - Convierte un archivo phar en un archivo tar o zip no ejecutable

# Phar::convertToExecutable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::convertToExecutable — Convierte un archivo phar a otro formato de archivo de archivo phar ejecutable

### Descripción

public function Phar::convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Este método se utiliza para convertir un archivo phar a otro formato de archivo. Por ejemplo, puede ser utilizado para crear un archivo phar basado en tar a partir de un archivo phar basado en zip o a partir de un archivo phar ejecutable basado en el formato de archivo phar. Asimismo, puede ser utilizado para aplicar una compresión global a un archivo basado en tar o en phar.

Si no se especifica ningún cambio, este método lanza una excepción BadMethodCallException.

En caso de éxito, el método crea un nuevo archivo en el disco y devuelve un objeto Phar. El archivo antiguo no es eliminado del disco, lo cual debe hacerse manualmente al final del procedimiento.

### Parámetros

`format`

  Debe ser uno de los formatos `Phar::PHAR`, `Phar::TAR`, o `Phar::ZIP`. Si este argumento es `null`, el formato de archivo actual será conservado.

`compression`

  Debe ser `Phar::NONE` para ninguna compresión global, `Phar::GZ` para una compresión basada en zlib y `Phar::BZ2` para una compresión basada en bzip2.

`extension`

  Este argumento se utiliza para sobrescribir la extensión por defecto de un archivo convertido. Cabe señalar que todos los archivos phar basados en zip o en tar deben contener `.phar` en su extensión para ser tratados como un archivo phar.

  Si se convierte a un archivo basado en phar, las extensiones por defecto son `.phar`, `.phar.gz`, o `.phar.bz2` según la compresión especificada. Para los archivos phar basados en tar, las extensiones por defecto son `.phar.tar`, `.phar.tar.gz`, y `.phar.tar.bz2`. Para los archivos phar basados en zip, la extensión por defecto es `.phar.zip`.

### Valores devueltos

El método devuelve un objeto Phar en caso de éxito, o `null` en caso de fallo.

### Errores/Excepciones

Este método lanza una excepción BadMethodCallException si no es capaz de comprimir, si se ha especificado un método de compresión desconocido o si el archivo solicitado ha sido almacenado en búfer con Phar::startBuffering() sin ser concluido con Phar::stopBuffering(), lanza una excepción UnexpectedValueException si el soporte de escritura ha sido desactivado y lanza una excepción PharException si se ha encontrado algún problema durante la fase de creación del archivo.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `format`, `compression`, y `extension` ahora son nullable.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::convertToExecutable()

Utilicemos Phar::convertToExecutable() :

    <?php
    try {
        $tarphar = new Phar('monphar.phar.tar');
        // se convierte al formato de archivo phar
        // note que monphar.phar.tar *no* es borrado
        $phar = $tarphar->convertToExecutable(Phar::PHAR); // crea monphar.phar
        $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
        // crea monphar.phar.tgz
        $compressed = $phar->convertToExecutable(Phar::TAR, Phar::GZ, '.phar.tgz');
    } catch (Exception $e) {
        // se manejan los errores aquí
    }
    ?>

### Ver también

- Phar::convertToData() - Convierte un archivo phar en un fichero no ejecutable
- PharData::convertToExecutable() - Convierte un archivo tar/zip no ejecutable en un archivo phar ejecutable
- PharData::convertToData() - Convierte un archivo phar en un archivo tar o zip no ejecutable

# Phar::copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::copy — Copia un fichero perteneciente a un archivo hacia otro fichero del mismo archivo

### Descripción

public function Phar::copy(string `$from`, string `$to`): true

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Copia un fichero perteneciente a un archivo hacia un nuevo fichero del mismo archivo. Es una alternativa orientada a objetos al uso de copy() con un flujo phar.

### Parámetros

`from`

`to`

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

Levanta una excepción UnexpectedValueException si el fichero origen no existe, si el fichero destino ya existe, si el acceso en escritura está desactivado, si abrir uno u otro de los ficheros falla, si la lectura del fichero origen falla, o levanta una excepción PharException si la escritura de los cambios en el phar falla.

### Ejemplos

Ejemplo #1 Ejemplo con Phar::copy()

Este ejemplo muestra cómo utilizar Phar::copy() y la comparación en términos de rendimiento con el equivalente utilizando el flujo phar. La diferencia principal entre los dos métodos concierne la gestión de errores. Todos los métodos Phar levantan excepciones, mientras que las funciones de flujo utilizan trigger_error().

    <?php

    try {
        $phar = new Phar('monphar.phar');

        $phar['a'] = 'salut';
        $phar->copy('a', 'b');

        echo $phar['b']; // Muestra "phar://myphar.phar/b"
    } catch (Exception $e) {
        // Maneja los errores
    }

    // El equivalente en términos de flujo del código anterior
    // se devuelven E_WARNING en lugar de excepciones
    copy('phar://monphar.phar/a', 'phar//monphar.phar/c');
    echo file_get_contents('phar://monphar.phar/c'); // Muestra "salut"

    ?>

# Phar::count

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::count — Devuelve el número de entradas (ficheros) en el archivo Phar

### Descripción

public function Phar::count(int `$mode` = `COUNT_NORMAL`): int

### Parámetros

`mode`

  `mode` es un valor entero que especifica el modo de conteo a utilizar. Por omisión, se define como `COUNT_NORMAL`, que solo cuenta el número de elementos en el archivo que no han sido eliminados o ocultados. Cuando se define como `COUNT_RECURSIVE`, cuenta todos los elementos del archivo, incluyendo aquellos que han sido eliminados o ocultados.

### Valores devueltos

El número de ficheros contenidos en el phar, o `0` (el número cero) si no hay ninguno.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::count()

    <?php
    // se asegura de que el phar no exista
    @unlink('lenouveauphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/lenouveauphar.phar', 0, 'le nouveauphar.phar');
    } catch (Exception $e) {
        echo 'No puede crear el phar:', $e;
    }
    echo 'El nuevo phar tiene ' . $p->count() . " entradas\n";
    $p['file.txt'] = 'salut';
    echo 'El nuevo phar tiene ' . $p->count() . " entradas\n";
    ?>

El ejemplo anterior mostrará:

    El nuevo phar tiene 0 entradas
    El nuevo phar tiene 1 entradas

# Phar::createDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::createDefaultStub — Crea un contenedor de carga de un archivo Phar

### Descripción

final public static function Phar::createDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): string

Este método está destinado a la creación de contenedores específicos del formato de archivo phar y no está diseñado para ser utilizado con archivos phar basados en tar o zip.

Los archivos Phar contienen un cargador o contenedor escrito en PHP que se ejecuta cuando el archivo es ejecutado ya sea mediante una inclusión

    <?php
    include 'monphar.phar';
    ?>

o mediante una simple ejecución:

    php monphar.phar

Este método proporciona un medio simple y fácil de crear un contenedor que lanzará un archivo de inicio desde el archivo phar. Además, se pueden especificar archivos diferentes para ejecutar el archivo desde la línea de comandos o desde un servidor web. El contenedor de carga llama entonces a Phar::interceptFileFuncs() para permitir el empaquetado fácil de aplicaciones PHP que acceden al sistema de archivos. Si la extensión phar no está presente, el contenedor de carga extraerá el archivo phar a un directorio temporal y tratará los archivos. Una función de apagado eliminará los archivos temporales al final.

### Parámetros

`index`

  Ruta relativa dentro del archivo phar a ejecutar en caso de acceso desde la línea de comandos

`webIndex`

  Ruta relativa dentro del archivo phar a ejecutar en caso de acceso desde un navegador

### Valores devueltos

Devuelve un string que contiene un contenedor de carga personalizado que permite que el archivo Phar creado funcione con o sin la extensión Phar activada.

### Errores/Excepciones

Lanza una excepción UnexpectedValueException si uno de los argumentos es más largo de 400 bytes.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `index` y `webIndex` ahora son nullable.

### Ejemplos

Ejemplo #1 Ejemplo con Phar::createDefaultStub()

    <?php
    try {
        $phar = new Phar('monphar.phar');
        $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
    } catch (Exception $e) {
        // trata los errores
    }
    ?>

### Ver también

- Phar::setStub() - Utilizado para especificar el cargador PHP o el contenedor de carga de un archivo Phar
- Phar::getStub() - Retorna el cargador PHP o el contenedor de carga de un archivo Phar

# Phar::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::decompress — Descomprime el archivo tar completo

### Descripción

public function Phar::decompress(?string `$extension` = `null`): ?Phar

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Para los archivos phar basados en tar y en phar, este método descomprime el archivo completo.

Para los archivos phar basados en Zip, este método falla y lanza una excepción. La extensión zlib debe estar activa para descomprimir un archivo comprimido con gzip, y la extensión bzip2 debe estar activa para descomprimir un archivo comprimido con bzip2. Al igual que con todas las funcionalidades que modifican el contenido de un phar, la variable INI phar.readonly debe estar a off para que funcione.

Además, este método cambia automáticamente la extensión del archivo, `.phar` Por omisión para los archivos phar, o `.phar.tar` para los archivos phar basados en tar. De lo contrario, se puede especificar una extensión de archivo utilizando el segundo argumento.

### Parámetros

`extension`

  Para descomprimir, las extensiones de archivo por omisión son `.phar` y `.phar.tar`. Utilice este argumento para especificar otra extensión de archivo. Cabe señalar que todos los archivos phar ejecutables deben contener `.phar` en su nombre de archivo.

### Valores devueltos

Se devuelve un objeto Phar en caso de éxito, o `null` en caso de fallo.

### Errores/Excepciones

Se lanza una excepción BadMethodCallException si la variable INI phar.readonly está a on, si la extensión zlib no está disponible, o si la extensión bzip2 no está activada.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `extension` ahora es nullable.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::decompress()

    <?php
    $p = new Phar('/ruta/al/mon.phar', 0, 'mon.phar.gz');
    $p['monfichero.txt'] = 'hola';
    $p['monfichero.txt'] = 'hola';
    $p3 = $p2->decompress(); // crea /ruta/al/mon.phar
    ?>

### Ver también

- PharFileInfo::getCompressedSize() - Devuelve el tamaño actual (con compresión) del fichero dentro del archivo Phar
- PharFileInfo::isCompressed() - Indica si la entrada está comprimida
- PharFileInfo::compress() - Comprime la entrada Phar actual con una de las compresiones zlib o bzip2
- PharFileInfo::decompress() - Descomprime la entrada Phar actual dentro del phar
- PharData::compress() - Comprime el archivo tar/zip completo utilizando la compresión Gzip o Bzip2
- Phar::canCompress() - Determina si la extensión phar soporta la compresión utilizando zip o bzip2
- Phar::isCompressed() - Devuelve Phar::GZ o PHAR::BZ2 si el archivo completo está comprimido (.tar.gz/tar.bz, etc)
- Phar::compress() - Comprime el archivo Phar completo utilizando la compresión Gzip o Bzip2
- Phar::getSupportedCompression() - Devuelve un array de los algoritmos de compresión soportados
- Phar::compressFiles() - Comprime todos los ficheros del archivo Phar actual
- Phar::decompressFiles() - Descomprime todos los ficheros del archivo Phar actual

# Phar::decompressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::decompressFiles — Descomprime todos los ficheros del archivo Phar actual

### Descripción

public function Phar::decompressFiles(): true

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Para los archivos phar basados en tar, este método lanza una excepción BadMethodCallException, ya que la compresión individual de los ficheros dentro de un archivo tar no es soportada por el formato de archivo. Utilice Phar::compress() para comprimir en un archivo phar basado en tar en su totalidad.

Para los archivos phar basados en Zip o en phar, este método descomprime todos los ficheros del archivo Phar. Las extensiones zlib o bzip2 deben estar activadas para aprovechar esta funcionalidad si alguno de los ficheros está comprimido utilizando la compresión bzip2/zlib. Al igual que con todas las funcionalidades que modifican el contenido de un phar, la variable INI phar.readonly debe estar a off para que funcione.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

Lanza una excepción BadMethodCallException si la variable INI phar.readonly está a on, si la extensión zlib no está disponible o si alguno de los ficheros está comprimido utilizando la compresión bzip2 y la extensión bzip2 no está activada.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::decompressFiles()

    <?php
    $p = new Phar('/ruta/hacia/mon.phar', 0, 'mon.phar');
    $p['monfichier.txt'] = 'hola';
    $p['monfichier2.txt'] = 'hola';
    $p->compressFiles(Phar::GZ);
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    $p->decompressFiles();
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    ?>

El ejemplo anterior mostrará:

    string(10) "monfichier.txt"
    int(4096)
    bool(false)
    bool(true)
    string(11) "monfichier2.txt"
    int(4096)
    bool(false)
    bool(true)
    string(10) "monfichier.txt"
    bool(false)
    bool(false)
    bool(false)
    string(11) "monfichier2.txt"
    bool(false)
    bool(false)
    bool(false)

### Ver también

- PharFileInfo::getCompressedSize() - Devuelve el tamaño actual (con compresión) del fichero dentro del archivo Phar
- PharFileInfo::isCompressed() - Indica si la entrada está comprimida
- PharFileInfo::compress() - Comprime la entrada Phar actual con una de las compresiones zlib o bzip2
- PharFileInfo::decompress() - Descomprime la entrada Phar actual dentro del phar
- Phar::canCompress() - Determina si la extensión phar soporta la compresión utilizando zip o bzip2
- Phar::isCompressed() - Devuelve Phar::GZ o PHAR::BZ2 si el archivo completo está comprimido (.tar.gz/tar.bz, etc)
- Phar::compressFiles() - Comprime todos los ficheros del archivo Phar actual
- Phar::getSupportedCompression() - Devuelve un array de los algoritmos de compresión soportados
- Phar::compress() - Comprime el archivo Phar completo utilizando la compresión Gzip o Bzip2
- Phar::decompress() - Descomprime el archivo tar completo

# Phar::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::delMetadata — Elimina los metadatos globales del phar

### Descripción

public function Phar::delMetadata(): true

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Elimina los metadatos globales del phar

### Parámetros

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

Genera una excepción PharException si ocurren errores durante la escritura en el disco.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::delMetaData()

    <?php
    try {
        $phar = new Phar('monphar.phar');
        var_dump($phar->getMetadata());
        $phar->setMetadata("salut");
        var_dump($phar->getMetadata());
        $phar->delMetadata();
        var_dump($phar->getMetadata());
    } catch (Exception $e) {
        // manejo de errores
    }
    ?>

El ejemplo anterior mostrará:

    NULL
    string(8) "salut"
    NULL

### Ver también

- Phar::getMetadata() - Devuelve las metadatos del archivo phar
- Phar::setMetadata() - Establece las metadatos del archivo phar
- Phar::hasMetadata() - Determina si el phar contiene o no metadatos

# Phar::delete

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::delete — Elimina un fichero dentro de un archivo phar

### Descripción

public function Phar::delete(string `$localName`): true

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Elimina un fichero dentro de un archivo phar. Es equivalente a la llamada a unlink() en un contexto de flujo, como se describe en el siguiente ejemplo...

### Parámetros

`localName`

  Ruta del fichero a eliminar dentro del archivo.

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

Genera una excepción PharException si se producen errores durante la escritura en el disco.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::delete()

    <?php
    try {
        $phar = new Phar('monphar.phar');
        $phar->delete('efface/moi.php');
        // es equivalente a:
        unlink('phar://monphar.phar/efface/moi.php');
    } catch (Exception $e) {
        // manejo de errores
    }
    ?>

### Ver también

- PharData::delete() - Elimina un fichero dentro del archivo tar/zip
- Phar::unlinkArchive() - Elimina completamente un archivo phar del disco y de la memoria

# Phar::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::__destruct — Destruye un objeto archivo Phar

### Descripción

public function Phar::__destruct()

### Parámetros

Esta función no contiene ningún parámetro.

# Phar::extractTo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::extractTo — Extrae el contenido de un archivo phar hacia un directorio

### Descripción

public function Phar::extractTo(string `$directory`, array|string|null `$files` = `null`, bool `$overwrite` = `false`): bool

Extrae todos los ficheros de un archivo phar hacia el disco. Los ficheros y los directorios extraídos conservan los permisos de manera idéntica a los del interior del archivo. Los parámetros opcionales permiten controlar qué ficheros se extraen y si los ficheros ya existentes en el disco pueden ser sobrescritos. El segundo parámetro `files` puede ser el nombre de un fichero o directorio, o un array de nombres de ficheros y directorios a extraer. Por omisión, este método no sobrescribe los ficheros existentes, el tercer parámetro puede ser pasado a `true` para activar la sobrescritura de ficheros. Este método es idéntico a ZipArchive::extractTo().

### Parámetros

`directory`

  Ruta de acceso hacia la cual extraer los ficheros `files`

`files`

  El nombre de un fichero o directorio o un array de ficheros/directorios a extraer, `null` para ignorar este parámetro

`overwrite`

  Pasarlo a `true` para activar la sobrescritura de ficheros existentes

### Valores devueltos

devuelve `true` en caso de éxito, pero es más seguro verificar si se lanzan excepciones, y considerar que todo ha ido bien si ninguna es lanzada.

### Errores/Excepciones

Lanza una excepción PharException si ocurren errores durante la escritura en el disco.

### Ejemplos

Ejemplo #1 Ejemplo con Phar::extractTo()

    <?php
    try {
        $phar = new Phar('monphar.phar');
        $phar->extractTo('/chemin/complet'); // extrae todos los ficheros
        $phar->extractTo('/autre/chemin', 'fichier.txt'); // extrae solo fichier.txt
        $phar->extractTo('/ce/chemin',
            array('fichier1.txt', 'fichier2.txt')); // extrae solo 2 ficheros
        $phar->extractTo('/troisieme/chemin', null, true); // extrae todos los ficheros, sobrescribiendo
    } catch (Exception $e) {
        // maneja los errores
    }
    ?>

### Notas

> Nota: Los sistemas de archivos NTFS de Windows no soportan ciertos caracteres en los nombres de archivo, como `<|>*?":`. Los nombres de archivo con un punto final no son soportados. A diferencia de algunas herramientas de extracción, este método no reemplaza estos caracteres con un guión bajo, sino que falla al extraer tales archivos.

### Ver también

- PharData::extractTo() - Extrae el contenido de un archivo tar/zip hacia un directorio

# Phar::getAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.1)

Phar::getAlias — Obtiene el alias para Phar

### Descripción

public function Phar::getAlias(): ?string

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el alias o `null` si no hay alias.

# Phar::getMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getMetadata — Devuelve las metadatos del archivo phar

### Descripción

public function Phar::getMetadata(array `$unserializeOptions` = []): mixed

Recupera las metadatos del archivo. Estas pueden ser cualquier variable PHP que pueda ser serializada.

Precaución

Acceder a los metadatos activará la deserialización, lo que puede provocar la ejecución de código PHP arbitrario. No utilice esto en archivos phar no confiables ni configure `unserializeOptions` de forma segura.

### Parámetros

No se proporcionan parámetros.

### Valores devueltos

Cualquier variable PHP que pueda ser serializada y que se almacena como metadato del archivo Phar, o `null` si no se almacenan metadatos.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Se ha añadido el parámetro `unserializeOptions`.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::getMetadata()

    <?php
    // se asegura de que el phar no exista
    @unlink('nouveauphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/nouveauphar.phar', 0, 'nouveauphar.phar');
        $p['fichier.php'] = '<?php echo "salut";';
        $p->setMetadata(array('bootstrap' => 'fichier.php'));
        var_dump($p->getMetadata());
    } catch (Exception $e) {
        echo 'No puede modificar el phar :', $e;
    }
    ?>

El ejemplo anterior mostrará:

    array(1) {
      ["bootstrap"]=>
      string(8) "fichier.php"
    }

### Ver también

- Phar::setMetadata() - Establece las metadatos del archivo phar
- Phar::delMetadata() - Elimina los metadatos globales del phar
- Phar::hasMetadata() - Determina si el phar contiene o no metadatos

# Phar::getModified

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getModified — Indica si el archivo phar ha sido modificado

### Descripción

public function Phar::getModified(): bool

Determina si un archivo phar ha tenido algún fichero interno eliminado o si el contenido de un fichero ha cambiado de alguna manera.

### Parámetros

No se admiten argumentos.

### Valores devueltos

`true` si el phar ha sido modificado desde su apertura, `false` en caso contrario.

# Phar::getPath

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Phar::getPath — Obtiene la ruta de acceso absoluta del archivo Phar en el disco

### Descripción

public function Phar::getPath(): string

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# Phar::getSignature

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getSignature — Devuelve la firma MD5/SHA1/SHA256/SHA512 de un archivo Phar

### Descripción

public function Phar::getSignature(): array|false

Devuelve la firma de verificación de un archivo phar en forma de un string hexadecimal.

### Parámetros

### Valores devueltos

Un array con la firma del archivo abierto con el `hash` como clave y "`MD5`", "`SHA-1`", "`SHA-256`" o "`SHA-512`" como `hash_type`. Esta firma es un hash calculado a partir del contenido completo del archivo; puede ser utilizada para verificar la integridad del archivo. Una firma válida es absolutamente requerida para todos los archivos phar ejecutables si la variable INI phar.require_hash vale `true`. Si no hay firma, la función devuelve `false`

# Phar::getStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getStub — Retorna el cargador PHP o el contenedor de carga de un archivo Phar

### Descripción

public function Phar::getStub(): string

Los archivos phar contienen un cargador, o contenedor (`stub`), escrito en PHP que se ejecuta cuando el archivo mismo es ejecutado ya sea por inclusión:

    <?php
    include 'monphar.phar';
    ?>

o por simple ejecución:

    php monphar.phar

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Retorna un string con el contenido del contenedor de carga (`stub`) del archivo phar actual.

### Errores/Excepciones

Levanta una excepción RuntimeException si no es posible leer el contenedor de carga del archivo Phar.

### Ejemplos

Ejemplo #1 Ejemplo con Phar::getStub()

    <?php
    $p = new Phar('/ruta/versus/mon.phar', 0, 'mon.phar');
    echo $p->getStub();
    echo "==SIGUIENTE==\n";
    $p->setStub("<?php
    function __autoload($class)
    {
        include 'phar://' . str_replace('_', '/', $class);
    }
    Phar::mapPhar('monphar.phar');
    include 'phar://monphar.phar/inicio.php';
    __HALT_COMPILER(); ?>");
    echo $p->getStub();
    ?>

El ejemplo anterior mostrará:

    <?php __HALT_COMPILER(); ?>
    ==SIGUIENTE==
    <?php
    function __autoload($class)
    {
        include 'phar://' . str_replace('_', '/', $class);
    }
    Phar::mapPhar('monphar.phar');
    include 'phar://monphar.phar/inicio.php';
    __HALT_COMPILER(); ?>

### Ver también

- Phar::setStub() - Utilizado para especificar el cargador PHP o el contenedor de carga de un archivo Phar
- Phar::createDefaultStub() - Crea un contenedor de carga de un archivo Phar

# Phar::getSupportedCompression

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::getSupportedCompression — Devuelve un array de los algoritmos de compresión soportados

### Descripción

final public static function Phar::getSupportedCompression(): array

### Parámetros

No se admiten argumentos.

### Valores devueltos

Devuelve un array que contiene uno de los algoritmos `Phar::GZ` o `Phar::BZ2`, según la disponibilidad de la extensión zlib o de la extensión bz2.

### Ver también

- PharFileInfo::getCompressedSize() - Devuelve el tamaño actual (con compresión) del fichero dentro del archivo Phar
- PharFileInfo::isCompressed() - Indica si la entrada está comprimida
- PharFileInfo::compress() - Comprime la entrada Phar actual con una de las compresiones zlib o bzip2
- PharFileInfo::decompress() - Descomprime la entrada Phar actual dentro del phar
- Phar::compress() - Comprime el archivo Phar completo utilizando la compresión Gzip o Bzip2
- Phar::decompress() - Descomprime el archivo tar completo
- Phar::canCompress() - Determina si la extensión phar soporta la compresión utilizando zip o bzip2
- Phar::isCompressed() - Devuelve Phar::GZ o PHAR::BZ2 si el archivo completo está comprimido (.tar.gz/tar.bz, etc)
- Phar::compressFiles() - Comprime todos los ficheros del archivo Phar actual
- Phar::decompressFiles() - Descomprime todos los ficheros del archivo Phar actual

# Phar::getSupportedSignatures

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.1.0)

Phar::getSupportedSignatures — Devuelve un array de los tipos de firma soportados

### Descripción

final public static function Phar::getSupportedSignatures(): array

Devuelve un array de los tipos de firma soportados

### Parámetros

No se admiten argumentos.

### Valores devueltos

Devuelve un array que contiene uno o más de los tipos `MD5`, `SHA-1`, `SHA-256`, `SHA-512`.

### Ver también

- Phar::getSignature() - Devuelve la firma MD5/SHA1/SHA256/SHA512 de un archivo Phar
- Phar::setSignatureAlgorithm() - Establece y aplica el algoritmo de firma de un phar

# Phar::getVersion

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getVersion — Devuelve las informaciones de versión del archivo Phar

### Descripción

public function Phar::getVersion(): string

Devuelve la versión de la API de un archivo Phar abierto.

### Parámetros

### Valores devueltos

La versión de la API del archivo abierto. No debe confundirse con la versión de API que la extensión phar cargada utilizará para crear nuevos archivos phar. Cada archivo Phar tiene la versión de API codificada de forma fija en su manifiesto. Para más información, consulte el formato de archivo Phar.

### Ver también

- Phar::apiVersion() - Devuelve la versión de la API

# Phar::hasMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::hasMetadata — Determina si el phar contiene o no metadatos

### Descripción

public function Phar::hasMetadata(): bool

Determina si el phar contiene o no metadatos.

### Parámetros

No se admiten argumentos.

### Valores devueltos

Devuelve `true` si están presentes metadatos, `false` en caso contrario.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::hasMetadata()

    <?php
    try {
        $phar = new Phar('monphar.phar');
        var_dump($phar->hasMetadata());
        $phar->setMetadata(array('deschoses' => 'salut'));
        var_dump($phar->hasMetadata());
        $phar->delMetadata();
        var_dump($phar->hasMetadata());
    } catch (Exception $e) {
        // manejo de errores
    }
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(true)
    bool(false)

### Ver también

- Phar::getMetadata() - Devuelve las metadatos del archivo phar
- Phar::setMetadata() - Establece las metadatos del archivo phar
- Phar::delMetadata() - Elimina los metadatos globales del phar

# Phar::interceptFileFuncs

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::interceptFileFuncs — Indica a phar que debe interceptar las funciones de archivos

### Descripción

final public static function Phar::interceptFileFuncs(): void

Indica a phar que debe interceptar fopen(), readfile(), file_get_contents(), opendir() y todas las funciones relativas a stat. Si cualquiera de estas funciones es llamada desde el archivo phar con una ruta relativa, la llamada es modificada para acceder a un archivo dentro del archivo. Las rutas absolutas se asumen como intentos de carga de archivos externos desde el sistema de archivos.

Esta función permite la ejecución de aplicaciones PHP diseñadas para ser lanzadas fuera de un disco duro, como aplicación phar.

### Parámetros

No se proporcionan argumentos.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo con Phar::interceptFileFuncs()

    <?php
    Phar::interceptFileFuncs();
    include 'phar://' . __FILE__ . '/fichero.php';
    ?>

Suponiendo que este phar se llama `/ruta/hacia/miphar.phar` y contiene `fichero.php` y `fichero2.txt`, si `fichero.php` contiene este código:

Ejemplo #2 Un ejemplo con Phar::interceptFileFuncs()

    <?php
    echo file_get_contents('fichero2.txt');
    ?>

Normalmente, PHP buscaría en el directorio actual el archivo llamado `file2.txt`, es decir, en el directorio de fichero.php o el directorio actual del usuario de la línea de comandos. Phar::interceptFileFuncs() indica a PHP que considere `phar:///ruta/hacia/miphar.phar/` como directorio actual y así abre en el ejemplo anterior el archivo `phar:///ruta/hacia/miphar.phar/fichero2.txt`.

# Phar::isBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::isBuffering — Determina si las operaciones de escritura de Phar están en búfer o se escriben directamente en el disco

### Descripción

public function Phar::isBuffering(): bool

Este método puede ser utilizado para determinar si un Phar guardará sus cambios inmediatamente en el disco o si es necesario un llamado a la función Phar::stopBuffering() para escribir las modificaciones.

El búfer de escritura de Phar se realiza por archivo; el búfer del archivo Phar `foo.phar` no afecta en nada los cambios realizados en el archivo Phar `bar.phar`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si las operaciones de escritura están en búfer, `false` en caso contrario.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::isBuffering()

    <?php
    $p = new Phar(dirname(__FILE__) . '/nouveauphar.phar', 0, 'nouveauphar.phar');
    $p2 = new Phar('pharexistant.phar');
    $p['fichier1.txt'] = 'salut';
    var_dump($p->isBuffering());
    var_dump($p2->isBuffering());
    ?>
    =2=
    <?php
    $p->startBuffering();
    var_dump($p->isBuffering());
    var_dump($p2->isBuffering());
    $p->stopBuffering();
    ?>
    =3=
    <?php
    var_dump($p->isBuffering());
    var_dump($p2->isBuffering());
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(false)
    =2=
    bool(true)
    bool(false)
    =3=
    bool(false)
    bool(false)

### Ver también

- Phar::startBuffering() - Inicia el almacenamiento en búfer de escrituras Phar, sin modificar el objeto Phar en el disco
- Phar::stopBuffering() - Detiene el almacenamiento en búfer de las escrituras Phar y provoca la escritura en el disco

# Phar::isCompressed

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::isCompressed — Devuelve Phar::GZ o PHAR::BZ2 si el archivo completo está comprimido (.tar.gz/tar.bz, etc)

### Descripción

public function Phar::isCompressed(): int|false

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Devuelve Phar::GZ o PHAR::BZ2 si el archivo completo está comprimido (.tar.gz/tar.bz, etc). Los archivos phar basados en Zip no pueden ser comprimidos como archivo, y este método siempre devolverá `false` si se consulta un archivo phar basado en Zip.

### Parámetros

No se admiten argumentos.

### Valores devueltos

`Phar::GZ`, `Phar::BZ2` o `false`.

### Ejemplos

Ejemplo #1 Ejemplo con Phar::isCompressed()

    <?php
    try {
        $phar1 = new Phar('monphar.zip.phar');
        var_dump($phar1->isCompressed());
        $phar2 = new Phar('monpharnoncompresse.tar.phar');
        var_dump($phar2->isCompressed());
        $phar2->compress(Phar::GZ);
        var_dump($phar2->isCompressed() == Phar::GZ);
    } catch (Exception $e) {
    }
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(false)
    bool(true)

### Ver también

- PharFileInfo::getCompressedSize() - Devuelve el tamaño actual (con compresión) del fichero dentro del archivo Phar
- PharFileInfo::isCompressed() - Indica si la entrada está comprimida
- PharFileInfo::decompress() - Descomprime la entrada Phar actual dentro del phar
- PharFileInfo::compress() - Comprime la entrada Phar actual con una de las compresiones zlib o bzip2
- Phar::decompress() - Descomprime el archivo tar completo
- Phar::compress() - Comprime el archivo Phar completo utilizando la compresión Gzip o Bzip2
- Phar::canCompress() - Determina si la extensión phar soporta la compresión utilizando zip o bzip2
- Phar::compressFiles() - Comprime todos los ficheros del archivo Phar actual
- Phar::decompressFiles() - Descomprime todos los ficheros del archivo Phar actual
- Phar::getSupportedCompression() - Devuelve un array de los algoritmos de compresión soportados

# Phar::isFileFormat

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::isFileFormat — Retorna `true` si el archivo phar está basado en el formato de archivo tar/phar/zip según el argumento

### Descripción

public function Phar::isFileFormat(int `$format`): bool

### Parámetros

`format`

  Puede ser `Phar::PHAR`, `Phar::TAR` o `Phar::ZIP` para probar el formato de archivo del archivo.

### Valores devueltos

Retorna `true` si el archivo phar utiliza el formato de archivo especificado en el argumento

### Errores/Excepciones

Se lanza una excepción PharException si el argumento es un formato de archivo desconocido.

### Ver también

- Phar::convertToExecutable() - Convierte un archivo phar a otro formato de archivo de archivo phar ejecutable
- Phar::convertToData() - Convierte un archivo phar en un fichero no ejecutable

# Phar::isValidPharFilename

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::isValidPharFilename — Determina si el nombre de fichero especificado es un nombre de fichero válido para un archivo phar

### Descripción

final public static function Phar::isValidPharFilename(string `$filename`, bool `$executable` = `true`): bool

Determina si el nombre de fichero especificado es un nombre de fichero válido para un archivo phar, que será reconocido como tal por la extensión phar. Esto puede ser utilizado para probar un nombre sin tener que instanciar un archivo phar y atrapar la inevitable Exception que será lanzada si se especifica un nombre de fichero no válido.

### Parámetros

`filename`

  El nombre o la ruta completa hacia un archivo phar no creado aún

`executable`

  Este argumento determina si el nombre de fichero debe ser tratado como el de un archivo phar ejecutable o como un archivo de datos no ejecutable.

### Valores devueltos

Devuelve `true` si el nombre de fichero es válido, `false` en caso contrario.

# Phar::isWritable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::isWritable — Retorna `true` si el archivo phar puede ser modificado

### Descripción

public function Phar::isWritable(): bool

Este método retorna `true` si `phar.readonly` está en `0` y el archivo phar actual en el disco no es de solo lectura.

### Parámetros

No se admiten argumentos.

### Valores devueltos

Retorna `true` si el archivo phar puede ser modificado

### Ver también

- Phar::canWrite() - Determina si la extensión phar soporta la creación y escritura de archivos phar
- PharData::isWritable() - Verifica si el archivo tar/zip puede ser modificado

# Phar::loadPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::loadPhar — Carga cualquier archivo phar con un alias

### Descripción

final public static function Phar::loadPhar(string `$filename`, ?string `$alias` = `null`): bool

Este método puede ser utilizado para leer el contenido de un archivo Phar externo. Esto es principalmente útil para asignar un alias a un phar de tal forma que las referencias posteriores al phar puedan realizarse mediante un alias más corto o para cargar archivos Phar que contienen solo datos y que no están destinados a ser ejecutados/incluidos en scripts PHP.

### Parámetros

`filename`

  la ruta relativa o absoluta hacia el archivo phar a abrir

`alias`

  El alias que podrá ser utilizado para referirse al archivo phar. Tenga en cuenta que muchos archivos phar especifican un alias explícito dentro del archivo phar, y se lanzará una excepción PharException si se especifica un nuevo alias en este caso.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Se lanza una excepción PharException si se pasa un alias mientras que el archivo phar ya tiene un alias explícito

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::loadPhar()

Phar::loadPhar puede ser utilizada en cualquier lugar para cargar un archivo phar externo mientras que Phar::mapPhar debe ser utilizada en un contenedor de carga para un Phar.

    <?php
    try {
        Phar::loadPhar('/ruta/al/phar.phar', 'mi.phar');
        echo file_get_contents('phar://mi.phar/fichero.txt');
    } catch (PharException $e) {
        echo $e;
    }
    ?>

### Ver también

- Phar::mapPhar() - Lee el phar ejecutado y carga su manifiesto

# Phar::mapPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::mapPhar — Lee el phar ejecutado y carga su manifiesto

### Descripción

final public static function Phar::mapPhar(?string `$alias` = `null`, int `$offset` = 0): bool

Este método estático puede ser utilizado únicamente dentro del contenedor de carga de un archivo Phar para inicializar el phar cuando es ejecutado directamente o cuando es incluido en otro script.

### Parámetros

`alias`

  El alias que puede ser utilizado en la URL `phar://` para referirse al archivo en lugar de utilizar su ruta completa.

`offset`

  Variable no utilizada, presente por motivos de compatibilidad con la biblioteca PHP_Archive de PEAR.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Se lanza una excepción PharException si el método no es llamado directamente dentro de la ejecución de PHP, si no se encuentra ningún token __HALT_COMPILER(); en el archivo fuente actual o si el archivo no puede ser abierto en lectura.

### Ejemplos

Ejemplo #1 Ejemplo con Phar::mapPhar()

mapPhar debe ser utilizado únicamente dentro del contenedor de carga de un phar. Utilice loadPhar para cargar un phar externo en memoria.

A continuación se muestra un ejemplo de contenedor de carga Phar que utiliza mapPhar.

    <?php
    function __autoload($class)
    {
        include 'phar://mon.phar/' . str_replace('_', '/', $class) . '.php';
    }
    try {
        Phar::mapPhar('mon.phar');
        include 'phar://mon.phar/demarrage.php';
    } catch (PharException $e) {
        echo $e->getMessage();
        die('No puede inicializar el Phar');
    }
    __HALT_COMPILER();

### Ver también

- Phar::loadPhar() - Carga cualquier archivo phar con un alias

# Phar::mount

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::mount — Monta un camino o un fichero externo a una ubicación virtual dentro del archivo phar

### Descripción

final public static function Phar::mount(string `$pharPath`, string `$externalPath`): void

Al igual que el concepto unix de montar un dispositivo externo en un punto de la jerarquía, Phar::mount() permite referirse a ficheros y directorios externos como si estuvieran dentro del archivo.

### Parámetros

`pharPath`

  El camino interno dentro del archivo phar a utilizar como punto de montaje. Debe ser un camino relativo dentro del archivo phar, y no debe existir ya.

`externalPath`

  Un camino o URL hacia un fichero o directorio externo a montar dentro del archivo

### Valores devueltos

No devuelve valor. Se lanza una excepción PharException en caso de fallo.

### Errores/Excepciones

Se lanza una excepción PharException si se encuentra un problema durante el montaje.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::mount()

El siguiente ejemplo muestra el acceso a un fichero de configuración externo como si fuera un camino dentro del archivo phar.

Primero, el código dentro del archivo phar:

    <?php
    $configuration = simplexml_load_string(file_get_contents(
        Phar::running(false) . '/config.xml'));
    ?>

Luego el código externo utilizado para montar el fichero de configuración:

    <?php
    // se comienza configurando la asociación entre el fichero config.xml abstracto
    // y el que está en el disco
    Phar::mount('phar://config.xml', '/home/example/config.xml');
    // ahora se lanza la aplicación
    include '/ruta/al/archivo.phar';
    ?>

Otro método es colocar el código de montaje dentro del contenedor de carga del archivo phar. Aquí hay un ejemplo para configurar un fichero de configuración por defecto si no se hace ninguna configuración de usuario:

    <?php
    // se comienza configurando la asociación entre el fichero config.xml abstracto
    // y el que está en el disco
    if (defined('EXTERNAL_CONFIG')) {
        Phar::mount('config.xml', EXTERNAL_CONFIG);
        if (file_exists(__DIR__ . '/extra_config.xml')) {
            Phar::mount('extra.xml', __DIR__ . '/extra_config.xml');
        }
    } else {
        Phar::mount('config.xml', 'phar://' . __FILE__ . '/default_config.xml');
        Phar::mount('extra.xml', 'phar://' . __FILE__ . '/default_extra.xml');
    }
    // ahora se lanza la aplicación
    include 'phar://' . __FILE__ . '/index.php';
    __HALT_COMPILER();
    ?>

... y el código externo para cargar este archivo phar:

    <?php
    define('EXTERNAL_CONFIG', '/home/ejemplo/config.xml');
    // ahora se lanza la aplicación
    include '/ruta/al/archivo.phar';
    ?>

# Phar::mungServer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::mungServer — Define una lista de un máximo de 4 variables $_SERVER que deben ser modificadas durante la ejecución

### Descripción

final public static function Phar::mungServer(array `$variables`): void

Phar::mungServer() debe ser llamada solo en el contenedor de carga de un archivo phar.

Define una lista de un máximo de 4 variables $_SERVER que deben ser modificadas durante la ejecución. Las variables que pueden ser modificadas para borrar los rastros de la ejecución phar son `REQUEST_URI`, `PHP_SELF`, `SCRIPT_NAME` y `SCRIPT_FILENAME`.

Por sí sola, esta método no hace nada. Toma efecto solo cuando se combina con Phar::webPhar() y solo si el archivo solicitado es un archivo PHP a parsear. Tenga en cuenta que las variables `PATH_INFO` y `PATH_TRANSLATED` siempre son modificadas.

Los valores iniciales de las variables que son modificadas son almacenados en el array SERVER con el prefijo `PHAR_` y por ejemplo `SCRIPT_NAME` será almacenada como `PHAR_SCRIPT_NAME`.

### Parámetros

`variables`

  un array que contiene cualquiera de estas strings. `REQUEST_URI`, `PHP_SELF`, `SCRIPT_NAME` y `SCRIPT_FILENAME` como índices de strings. Otros valores desencadenan una excepción y Phar::mungServer() es sensible a mayúsculas/minúsculas.

### Valores devueltos

No devuelve ningún valor.

### Errores/Excepciones

Levanta una excepción UnexpectedValueException si se encuentra algún problema en los datos pasados.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::mungServer()

    <?php
    // ejemplo de contenedor
    Phar::mungServer(array('REQUEST_URI'));
    Phar::webPhar();
    __HALT_COMPILER();
    ?>

### Ver también

- Phar::webPhar() - Redirige una solicitud desde un navegador web a un fichero interno en el archivo phar
- Phar::setStub() - Utilizado para especificar el cargador PHP o el contenedor de carga de un archivo Phar

# Phar::offsetExists

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetExists — Determina si un fichero existe en el phar

### Descripción

public function Phar::offsetExists(string `$localName`): bool

Es una implementación de la interfaz ArrayAccess que permite la manipulación directa del contenido de un archivo Phar utilizando los corchetes de acceso al array.

offsetExists() es llamado como isset() es llamado.

### Parámetros

`localName`

  El nombre de fichero (en ruta relativa) a buscar en el Phar.

### Valores devueltos

Devuelve `true` si el fichero existe en el phar, `false` en caso contrario.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::offsetExists()

    <?php
    $p = new Phar(dirname(__FILE__) . '/mon.phar', 0, 'mon.phar');
    $p['premierfichier.txt'] = 'premier fichier';
    $p['secondfichier.txt'] = 'second fichier';
    // las líneas siguientes hacen uso de offsetExists() de forma indirecta
    var_dump(isset($p['premierfichier.txt']));
    var_dump(isset($p['pasla.txt']));
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(false)

### Ver también

- Phar::offsetGet() - Obtiene un objeto PharFileInfo a partir de un fichero
- Phar::offsetSet() - Establece el contenido de un fichero interno en el archivo a partir del contenido de un fichero externo
- Phar::offsetUnset() - Elimina un fichero de un phar

# Phar::offsetGet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetGet — Obtiene un objeto PharFileInfo a partir de un fichero

### Descripción

public function Phar::offsetGet(string `$localName`): SplFileInfo

Esta es una implementación de la interfaz ArrayAccess que permite la manipulación directa del contenido de un archivo Phar utilizando los corchetes de acceso a array. Phar::offsetGet() se utiliza para extraer ficheros de un archivo Phar.

### Parámetros

`localName`

  El nombre de fichero (en ruta relativa) a buscar en el Phar.

### Valores devueltos

Se devuelve un objeto PharFileInfo que puede ser utilizado para integrar el contenido de un fichero o para recuperar información sobre el fichero actual.

### Errores/Excepciones

Este método lanza una excepción BadMethodCallException si el fichero no existe en el archivo Phar.

### Ejemplos

Ejemplo #1 Ejemplo con Phar::offsetGet()

Al igual que con todas las clases que implementan la interfaz ArrayAccess, Phar::offsetGet() es llamada automáticamente cuando se utilizan los corchetes de acceso a array (`[]`).

    <?php
    $p = new Phar(dirname(__FILE__) . '/monphar.phar', 0, 'monphar.phar');
    $p['existe.txt'] = "el fichero existe\n";
    try {
        // llama automáticamente a offsetGet()
        echo $p['existe.txt'];
        echo $p['nexistepas.txt'];
    } catch (BadMethodCallException $e) {
        echo $e;
    }
    ?>

El ejemplo anterior mostrará:

    el fichero existe
    Entry nexistepas.txt does not exist

### Ver también

- Phar::offsetExists() - Determina si un fichero existe en el phar
- Phar::offsetSet() - Establece el contenido de un fichero interno en el archivo a partir del contenido de un fichero externo
- Phar::offsetUnset() - Elimina un fichero de un phar

# Phar::offsetSet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetSet — Establece el contenido de un fichero interno en el archivo a partir del contenido de un fichero externo

### Descripción

public function Phar::offsetSet(string `$localName`, resource|string `$value`): void

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Es una implementación de la interfaz ArrayAccess que permite la manipulación directa del contenido de un archivo Phar utilizando los corchetes de acceso al array. offsetSet se utiliza para modificar un fichero existente o para añadir un nuevo fichero al archivo Phar.

### Parámetros

`localName`

  El nombre del fichero (en ruta relativa) a buscar en el Phar.

`value`

  Contenido del fichero.

### Valores devueltos

No se devuelve ningún valor.

### Errores/Excepciones

Si phar.readonly está a `1`, se lanza una excepción BadMethodCallException, ya que modificar un Phar solo es permitido cuando phar.readonly está a `0`. Se lanza una excepción PharException si ha habido un problema al escribir los cambios del archivo Phar en el disco.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::offsetSet()

offsetSet no debe ser accedido directamente, sino a través del operador de acceso al array, `[]`.

    <?php
    $p = new Phar('/ruta/al/mon.phar', 0, 'mon.phar');
    try {
        // llama a offsetSet
        $p['fichero.txt'] = 'Hola';
    } catch (Exception $e) {
        echo 'No puede modificar fichero.txt:', $e;
    }
    ?>

### Notas

> Nota: Phar::addFile(), Phar::addFromString() y Phar::offsetSet() registran un nuevo archivo phar cada vez que son llamadas. Si las prestaciones son una preocupación, Phar::buildFromDirectory() o Phar::buildFromIterator() deberían ser utilizadas en su lugar.

### Ver también

- Phar::offsetExists() - Determina si un fichero existe en el phar
- Phar::offsetGet() - Obtiene un objeto PharFileInfo a partir de un fichero
- Phar::offsetUnset() - Elimina un fichero de un phar

# Phar::offsetUnset

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetUnset — Elimina un fichero de un phar

### Descripción

public function Phar::offsetUnset(string `$localName`): void

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Esta es una implementación de la interfaz ArrayAccess que permite la manipulación directa del contenido de un archivo Phar utilizando los corchetes de acceso al array. offsetUnset se utiliza para eliminar un fichero existente y es llamado por la función unset().

### Parámetros

`localName`

  El nombre del fichero (en ruta relativa) a buscar en el Phar.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

Si phar.readonly está a `1`, se lanza una excepción BadMethodCallException, ya que modificar un Phar solo es permitido cuando phar.readonly está a `0`. Se lanza una excepción PharException si ha habido un problema al escribir los cambios del archivo Phar en el disco.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::offsetUnset()

    <?php
    $p = new Phar('/ruta/al/mon.phar', 0, 'mon.phar');
    try {
        // elimina archivo.txt de mon.phar llamando a offsetUnset
        unset($p['archivo.txt']);
    } catch (Exception $e) {
        echo 'No se puede eliminar archivo.txt: ', $e;
    }
    ?>

### Ver también

- Phar::offsetExists() - Determina si un fichero existe en el phar
- Phar::offsetGet() - Obtiene un objeto PharFileInfo a partir de un fichero
- Phar::offsetSet() - Establece el contenido de un fichero interno en el archivo a partir del contenido de un fichero externo
- Phar::unlinkArchive() - Elimina completamente un archivo phar del disco y de la memoria
- Phar::delete() - Elimina un fichero dentro de un archivo phar

# Phar::running

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::running — Devuelve la ruta completa en el disco o la URL phar completa del archivo phar actualmente ejecutado

### Descripción

final public static function Phar::running(bool `$returnPhar` = `true`): string

Devuelve la ruta completa del archivo phar ejecutado. Esto es utilizado de manera similar a la constante mágica `__FILE__` y tiene efectos únicamente dentro de un archivo phar que está siendo ejecutado.

Dentro de un contenedor de carga de un archivo, Phar::running() devuelve `""`. Utilice simplemente `__FILE__` para acceder al phar actual dentro de un contenedor de carga.

### Parámetros

`returnPhar`

  Si `false`, se devuelve la ruta completa en el disco hacia el phar. Si `true`, se devuelve una URL phar completa.

### Valores devueltos

Devuelve la ruta del fichero si es válida, de lo contrario una cadena vacía.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::running()

Para el ejemplo siguiente, se asume que el archivo phar es `/ruta/al/archivo.phar`.

    <?php
    $a = Phar::running(); // $a vale "phar:///ruta/al/archivo.phar"
    $b = Phar::running(false); // $b vale "/ruta/al/archivo.phar"
    ?>

# Phar::setAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.1)

Phar::setAlias — Establece el alias del archivo Phar

### Descripción

public function Phar::setAlias(string `$alias`): true

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Establece el alias del archivo Phar y lo escribe como alias permanente de este archivo phar. Un alias puede ser utilizado dentro de un archivo phar para asegurar que el uso del flujo `phar` para acceder a ficheros internos funcione siempre independientemente de la ubicación del archivo phar en el sistema de ficheros. Una alternativa consiste en confiar en la intercepción de include realizada por Phar o en utilizar Phar::interceptFileFuncs() y usar rutas relativas.

### Parámetros

`alias`

  Una pequeña cadena con la que se referirá a este archivo durante los accesos con el flujo `phar`.

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

Se lanza una excepción UnexpectedValueException cuando el acceso en escritura está desactivado y se lanza una excepción PharException si el alias ya está en uso o si se ha encontrado un problema al escribir los cambios en el disco.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Phar::setAlias() ahora tiene un tipo de retorno provisional de tipo true.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::setAlias()

    <?php
    try {
        $phar = new Phar('monphar.phar');
        $phar->setAlias('monp.phar');
    } catch (Exception $e) {
        // trata los errores
    }
    ?>

### Ver también

- Phar::__construct() - Construye un objeto de archivo Phar
- Phar::interceptFileFuncs() - Indica a phar que debe interceptar las funciones de archivos

# Phar::setDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::setDefaultStub — Utilizado para establecer el cargador PHP o el contenedor de carga de un archivo Phar como cargador por defecto

### Descripción

public function Phar::setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): true

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Este método es un atajo que combina las funcionalidades de Phar::createDefaultStub() y Phar::setStub().

### Parámetros

`index`

  Ruta relativa dentro del archivo phar a ejecutar si se lanza desde la línea de comandos

`webIndex`

  Ruta relativa dentro del archivo phar a ejecutar si se lanza desde un navegador

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

Se lanza una excepción UnexpectedValueException si phar.readonly está activada en el php.ini. Se lanza una excepción PharException si se encuentran problemas al escribir los cambios en el disco.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Phar::setDefaultStub() ahora tiene un tipo de retorno provisional de true.
8.0.0 | `webIndex` ahora es nullable.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::setDefaultStub()

    <?php
    try {
        $phar = new Phar('monphar.phar');
        $phar->setDefaultStub('cli.php', 'web/index.php');
        // es equivalente a:
        // $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
    } catch (Exception $e) {
        // manejo de errores
    }
    ?>

### Ver también

- Phar::setStub() - Utilizado para especificar el cargador PHP o el contenedor de carga de un archivo Phar
- Phar::createDefaultStub() - Crea un contenedor de carga de un archivo Phar

# Phar::setMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::setMetadata — Establece las metadatos del archivo phar

### Descripción

public function Phar::setMetadata(mixed `$metadata`): void

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Phar::setMetadata() debe ser utilizada para almacenar datos personalizados que describen el archivo phar, como una entidad separada. PharFileInfo::setMetadata() debe ser utilizada para las metadatos específicas de los ficheros. Las metadatos pueden disminuir el rendimiento de carga de un archivo phar si los datos son grandes.

Un uso posible de las metadatos es la especificación de los ficheros a utilizar dentro del archivo para ejecutarlo, o la ubicación de un fichero de manifiesto como el fichero package.xml de » PEAR. En general, cualquier dato útil que describa el archivo phar puede ser almacenado.

### Parámetros

`metadata`

  Cualquier variable PHP que contenga información a almacenar y que describa el archivo phar

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::setMetadata()

    <?php
    // se asegura de que el phar no exista ya
    @unlink('nuevo.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/nuevo.phar', 0, 'nuevo.phar');
        $p['fichero.php'] = '<?php echo "hola"';
        $p->setMetadata(array('cargador' => 'fichero.php'));
        var_dump($p->getMetadata());
    } catch (Exception $e) {
        echo 'No puede crear/modificar el phar :', $e;
    }
    ?>

El ejemplo anterior mostrará:

    array(1) {
      ["cargador"]=>
      string(11) "fichero.php"
    }

### Ver también

- Phar::getMetadata() - Devuelve las metadatos del archivo phar
- Phar::delMetadata() - Elimina los metadatos globales del phar
- Phar::hasMetadata() - Determina si el phar contiene o no metadatos

# Phar::setSignatureAlgorithm

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.1.0)

Phar::setSignatureAlgorithm — Establece y aplica el algoritmo de firma de un phar

### Descripción

public function Phar::setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Establece y aplica el algoritmo de firma de un phar. El algoritmo de firma debe ser `Phar::MD5`, `Phar::SHA1`, `Phar::SHA256`, `Phar::SHA512`, o `Phar::OPENSSL`.

Tenga en cuenta que todas las archives phar ejecutables tienen una firma creada automáticamente, `SHA1` por omisión. Las archives de datos basadas en tar o en zip (creadas con la clase PharData) deben tener su firma creada y asignada explícitamente mediante Phar::setSignatureAlgorithm().

### Parámetros

`algo`

  Uno de los algoritmos `Phar::MD5`, `Phar::SHA1`, `Phar::SHA256`, `Phar::SHA512`, o `Phar::OPENSSL`

`privateKey`

  El contenido de una clave privada OpenSSL, tal como se extrae de un certificado o de un archivo de clave OpenSSL:

      <?php
      $private = openssl_get_privatekey(file_get_contents('private.pem'));
      $pkey = '';
      openssl_pkey_export($private, $pkey);
      $p->setSignatureAlgorithm(Phar::OPENSSL, $pkey);
      ?>

  Consulte la introducción de phar para las instrucciones de nombramiento y ubicación del archivo de clave pública.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

Genera una excepción UnexpectedValueException para muchos errores y una excepción PharException si ocurren problemas durante la escritura de los cambios en el disco.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `privateKey` ahora es nullable.

### Ver también

- Phar::getSupportedSignatures() - Devuelve un array de los tipos de firma soportados
- Phar::getSignature() - Devuelve la firma MD5/SHA1/SHA256/SHA512 de un archivo Phar

# Phar::setStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::setStub — Utilizado para especificar el cargador PHP o el contenedor de carga de un archivo Phar

### Descripción

public function Phar::setStub(resource|string `$stub`, int `$length` = -1): true

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Este método se utiliza para añadir un cargador PHP a un nuevo archivo Phar, o para reemplazar el contenedor de carga de un archivo Phar existente.

El contenedor de carga de un archivo Phar se utiliza cuando un archivo es incluido directamente como en este ejemplo:

    <?php
    include 'myphar.phar';
    ?>

o mediante una simple ejecución:

    php myphar.phar

El cargador no se utiliza cuando un fichero es incluido a través del flujo `phar` como esto:

    <?php
    include 'phar://monphar.phar/unfchier.php';
    ?>

### Parámetros

`stub`

  Una cadena o un resource de flujo abierto a utilizar como contenedor ejecutable para este archivo phar.

`length`
  Longitud de `stub` en bytes.
  Advertencia

  Pasar el argumento `length` con un resource en el primer argumento está OBSOLETO a partir de PHP 8.3.0. Utilizar `$phar->setStub(stream_get_contents($resource))` en su lugar.

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

Una excepción UnexpectedValueException es lanzada si phar.readonly está activado en el php.ini. Una excepción PharException es lanzada si se encuentran problemas al escribir los cambios en el disco.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | El tipo de retorno es ahora `true`, anteriormente era bool.
8.3.0 | Llamar a Phar::setStub() con una resource y una `length` ahora está obsoleto. Tales llamadas deberían ser reemplazadas por: `$phar->setStub(stream_get_contents($resource));`

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::setStub()

    <?php

    try {
        $p = new Phar(dirname(__FILE__) . '/nouveau.phar', 0, 'nouveau.phar');
        $p['a.php'] = '<?php var_dump("Salut");';
        $p->setStub('<?php var_dump("Premier"); Phar::mapPhar("nouveau.phar"); __HALT_COMPILER(); ?>');
        include 'phar://nouveau.phar/a.php';
        var_dump($p->getStub());

        $p['b.php'] = '<?php var_dump("Tout le monde");';
        $p->setStub('<?php var_dump("Second"); Phar::mapPhar("nouveau.phar"); __HALT_COMPILER(); ?>');
        include 'phar://nouveau.phar/b.php';
        var_dump($p->getStub());
    } catch (Exception $e) {
        echo 'Error al escribir nuevo.phar: ', $e;
    }
    ?>

El ejemplo anterior mostrará:

    string(5) "Salut"
    string(79) "<?php var_dump("Premier"); Phar::mapPhar("nouveau.phar"); __HALT_COMPILER(); ?>"
    string(13) "Tout le monde"
    string(78) "<?php var_dump("Second"); Phar::mapPhar("nouveau.phar"); __HALT_COMPILER(); ?>"

### Ver también

- Phar::getStub() - Retorna el cargador PHP o el contenedor de carga de un archivo Phar
- Phar::createDefaultStub() - Crea un contenedor de carga de un archivo Phar

# Phar::startBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::startBuffering — Inicia el almacenamiento en búfer de escrituras Phar, sin modificar el objeto Phar en el disco

### Descripción

public function Phar::startBuffering(): void

Aunque técnicamente innecesario, el método Phar::startBuffering() puede proporcionar un aumento de rendimiento durante la creación o modificación de un archivo Phar con un gran número de ficheros. Normalmente, cada vez que un fichero dentro del archivo Phar es creado o modificado, el archivo Phar completo se recrea incluyendo los cambios. De esta manera, el archivo siempre estará actualizado con respecto a las operaciones que se le aplican.

Aunque esto pueda parecer innecesario durante la creación de un archivo Phar simple, adquiere sentido al escribir el archivo Phar completo de una sola vez. Asimismo, es frecuente necesitar realizar una serie de cambios y asegurarse de que todos son posibles antes de escribir en el disco, de manera similar a las transacciones de las bases de datos relacionales. Las funciones Phar::startBuffering()/Phar::stopBuffering() están disponibles con este propósito.

El almacenamiento en búfer Phar se realiza por archivo, el búfer activo para el archivo Phar `foo.phar` no afecta a los cambios realizados en el archivo Phar `bar.phar`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::startBuffering()

    <?php
    // se asegura de que el phar no exista ya
    @unlink('nouveau.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/nouveau.phar', 0, 'nouveau.phar');
    } catch (Exception $e) {
        echo 'No puede crear el phar:', $e;
    }
    echo 'El nuevo phar tiene ' . $p->count() . " entradas\n";
    $p->startBuffering();
    $p['fichier.txt'] = 'salut';
    $p['fichier2.txt'] = 'jolie';
    $p['fichier2.txt']->setCompressedGZ();
    $p['fichier3.txt'] = 'môme';
    $p['fichier3.txt']->setMetadata(42);
    $p->setStub("<?php
    function __autoload($class)
    {
        include 'phar://monphar.phar/' . str_replace('_', '/', $class) . '.php';
    }
    Phar::mapPhar('monphar.phar');
    include 'phar://monphar.phar/demarrage.php';
    __HALT_COMPILER();");
    $p->stopBuffering();
    ?>

### Ver también

- Phar::stopBuffering() - Detiene el almacenamiento en búfer de las escrituras Phar y provoca la escritura en el disco
- Phar::isBuffering() - Determina si las operaciones de escritura de Phar están en búfer o se escriben directamente en el disco

# Phar::stopBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::stopBuffering — Detiene el almacenamiento en búfer de las escrituras Phar y provoca la escritura en el disco

### Descripción

public function Phar::stopBuffering(): void

Phar::stopBuffering() se utiliza en conjunción con el método Phar::startBuffering(). Phar::startBuffering() puede proporcionar un aumento de rendimiento durante la creación o modificación de un archivo Phar con un gran número de ficheros. Normalmente, cada vez que un fichero dentro del archivo Phar es creado o modificado, el archivo Phar completo se recrea incluyendo los cambios. De esta manera, el archivo estará siempre actualizado respecto a las operaciones que se le aplican.

Aunque esto puede parecer innecesario durante la creación de un archivo Phar simple, adquiere sentido al escribir el archivo Phar completo de una sola vez. Asimismo, es frecuentemente necesario realizar una serie de cambios y asegurarse de que todos son posibles antes de escribir en el disco, de manera similar a las transacciones de las bases de datos relacionales. Las funciones Phar::startBuffering()/Phar::stopBuffering() están disponibles con este propósito.

El almacenamiento en búfer Phar se realiza por archivo, el búfer activo para el archivo Phar `foo.phar` no afecta a los cambios realizados en el archivo Phar `bar.phar`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

Se lanza una excepción PharException si se encuentran problemas durante la escritura de los cambios en el disco.

### Ejemplos

Ejemplo #1 Un ejemplo Phar::stopBuffering()

    <?php
    $p = new Phar(dirname(__FILE__) . '/nouveau.phar', 0, 'nouveau.phar');
    $p['fichier1.txt'] = 'salut';
    $p->startBuffering();
    var_dump($p->getStub());
    $p->setStub("<?php
    function __autoload(\$class)
    {
        include 'phar://nouveau.phar/' . str_replace('_', '/', \$class) . '.php';
    }
    Phar::mapPhar('nouveau.phar');
    include 'phar://nouveau.phar/demarrage.php';
    __HALT_COMPILER();");
    $p->stopBuffering();
    var_dump($p->getStub());
    ?>

El ejemplo anterior mostrará:

    string(24) "<?php __HALT_COMPILER();"
    string(195) "<?php
    function __autoload($class)
    {
        include 'phar://' . str_replace('_', '/', $class);
    }
    Phar::mapPhar('nouveau.phar');
    include 'phar://nouveau.phar/demarrage.php';
    __HALT_COMPILER();"

### Ver también

- Phar::startBuffering() - Inicia el almacenamiento en búfer de escrituras Phar, sin modificar el objeto Phar en el disco
- Phar::isBuffering() - Determina si las operaciones de escritura de Phar están en búfer o se escriben directamente en el disco

# Phar::unlinkArchive

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::unlinkArchive — Elimina completamente un archivo phar del disco y de la memoria

### Descripción

final public static function Phar::unlinkArchive(string `$filename`): true

Elimina completamente un archivo phar del disco y de la memoria

### Parámetros

`filename`

  La ruta en el disco hacia el archivo phar.

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

Se lanza una excepción PharException si existen punteros abiertos hacia ficheros del archivo phar, o si objetos Phar, PharData, o PharFileInfo hacen referencia al archivo phar.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::unlinkArchive()

    <?php
    // uso simple
    Phar::unlinkArchive('/ruta/al/archivo.phar');

    // un ejemplo más común:
    $p = new Phar('archivo.phar');
    $fp = fopen('phar://archivo.phar/fichero.txt', 'r');
    // esto crea 'archivo.phar.gz'
    $gp = $p->compress(Phar::GZ);
    // elimina todas las referencias al archivo
    unset($p);
    fclose($fp);
    // borra ahora todo rastro del archivo
    Phar::unlinkArchive('archivo.phar');
    ?>

### Ver también

- Phar::delete() - Elimina un fichero dentro de un archivo phar
- Phar::offsetUnset() - Elimina un fichero de un phar

# Phar::webPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::webPhar — Redirige una solicitud desde un navegador web a un fichero interno en el archivo phar

### Descripción

final public static function Phar::webPhar(
?string `$alias` = `null`,
?string `$index` = `null`,
?string `$fileNotFoundScript` = `null`,
array `$mimeTypes` = [],
?callable `$rewrite` = `null`
): void

Phar::webPhar() actúa como Phar::mapPhar() para los phars orientados a web. Este método analiza $_SERVER['REQUEST_URI'] y enruta las solicitudes de un navegador hacia un fichero interno del archivo. Esto simula un servidor web, enrutando solicitudes al fichero correcto, enviando los encabezados adecuados y analizando el fichero PHP como corresponde. Combinado con Phar::mungServer() y Phar::interceptFileFuncs(), cualquier aplicación web puede ser utilizada sin cambios a partir del archivo phar.

Phar::webPhar() debe ser llamado únicamente desde el contenedor de carga de un archivo phar (consultar esto para obtener más información sobre los contenedores).

### Parámetros

`alias`

  El alias que puede ser utilizado en la URL `phar://` para referirse al archivo, en lugar de su ruta completa.

`index`

  La ubicación dentro del archivo del índice de directorio.

`fileNotFoundScript`

  La ubicación del script a ejecutar cuando un fichero no es encontrado. Este script debe enviar los encabezados HTTP 404 correctos.

`mimeTypes`

  Un array que hace corresponder extensiones de fichero adicionales a tipos MIME. Si las correspondencias por defecto son suficientes, se debe pasar un array vacío. Por defecto, estas correspondencias son las siguientes:

      <?php
      $mimes = array(
          'phps' => Phar::PHPS, // paso a highlight_file()
          'c' => 'text/plain',
          'cc' => 'text/plain',
          'cpp' => 'text/plain',
          'c++' => 'text/plain',
          'dtd' => 'text/plain',
          'h' => 'text/plain',
          'log' => 'text/plain',
          'rng' => 'text/plain',
          'txt' => 'text/plain',
          'xsd' => 'text/plain',
          'php' => Phar::PHP, // analizar como PHP
          'inc' => Phar::PHP, // analizar como PHP
          'avi' => 'video/avi',
          'bmp' => 'image/bmp',
          'css' => 'text/css',
          'gif' => 'image/gif',
          'htm' => 'text/html',
          'html' => 'text/html',
          'htmls' => 'text/html',
          'ico' => 'image/x-ico',
          'jpe' => 'image/jpeg',
          'jpg' => 'image/jpeg',
          'jpeg' => 'image/jpeg',
          'js' => 'application/x-javascript',
          'midi' => 'audio/midi',
          'mid' => 'audio/midi',
          'mod' => 'audio/mod',
          'mov' => 'movie/quicktime',
          'mp3' => 'audio/mp3',
          'mpg' => 'video/mpeg',
          'mpeg' => 'video/mpeg',
          'pdf' => 'application/pdf',
          'png' => 'image/png',
          'swf' => 'application/shockwave-flash',
          'tif' => 'image/tiff',
          'tiff' => 'image/tiff',
          'wav' => 'audio/wav',
          'xbm' => 'image/xbm',
          'xml' => 'text/xml',
      );
      ?>

`rewrite`

  La función de reescritura que se pasa toma como único argumento un string y debe devolver un string o false.

  Si se utiliza fast-cgi o cgi, el argumento pasado a la función es el valor de la variable $_SERVER['PATH_INFO']. De lo contrario, el argumento pasado a la función es el valor de la variable $_SERVER['REQUEST_URI'].

  Si se devuelve un string, será utilizado en la ruta interna del fichero. Si se devuelve false, entonces webPhar() enviará un código HTTP 403.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

Levanta una excepción PharException cuando el fichero interno no puede ser abierto o si la llamada se realiza fuera de un contenedor. Si se pasa un valor de array no válido en `mimeTypes` o si se pasa una función de devolución de llamada inválida al parámetro `rewrite`, entonces se levanta una excepción UnexpectedValueException.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `fileNotFoundScript` y `rewrite` ahora son nullable.

### Ejemplos

Ejemplo #1 Ejemplo con Phar::webPhar()

En el ejemplo siguiente, el phar creado mostrará `Hola mundo` si alguien llama a `/miphar.phar/index.php` o `/miphar.phar`, y mostrará la fuente de `index.phps` si `/miphar.phar/index.phps` es llamado.

    <?php
    // el archivo phar es creado:
    try {
        $phar = new Phar('miphar.phar');
        $phar['index.php'] = '<?php echo "Hola mundo"; ?>';
        $phar['index.phps'] = '<?php echo "Hola mundo"; ?>';
        $phar->setStub('<?php
    Phar::webPhar();
    __HALT_COMPILER(); ?>');
    } catch (Exception $e) {
        // se manejan los errores aquí
    }
    ?>

### Ver también

- Phar::mungServer() - Define una lista de un máximo de 4 variables $_SERVER que deben ser modificadas durante la ejecución
- Phar::interceptFileFuncs() - Indica a phar que debe interceptar las funciones de archivos

## Tabla de contenidos

- Phar::addEmptyDir — Añade un directorio vacío al archivo phar
- Phar::addFile — Añade un fichero del sistema de ficheros al archivo phar
- Phar::addFromString — Añade un fichero desde un string al archivo phar
- Phar::apiVersion — Devuelve la versión de la API
- Phar::buildFromDirectory — Construye un archivo phar a partir de los ficheros de un directorio
- Phar::buildFromIterator — Construye un archivo phar a partir de un iterador
- Phar::canCompress — Determina si la extensión phar soporta la compresión utilizando zip o bzip2
- Phar::canWrite — Determina si la extensión phar soporta la creación y escritura de archivos phar
- Phar::compress — Comprime el archivo Phar completo utilizando la compresión Gzip o Bzip2
- Phar::compressFiles — Comprime todos los ficheros del archivo Phar actual
- Phar::__construct — Construye un objeto de archivo Phar
- Phar::convertToData — Convierte un archivo phar en un fichero no ejecutable
- Phar::convertToExecutable — Convierte un archivo phar a otro formato de archivo de archivo phar ejecutable
- Phar::copy — Copia un fichero perteneciente a un archivo hacia otro fichero del mismo archivo
- Phar::count — Devuelve el número de entradas (ficheros) en el archivo Phar
- Phar::createDefaultStub — Crea un contenedor de carga de un archivo Phar
- Phar::decompress — Descomprime el archivo tar completo
- Phar::decompressFiles — Descomprime todos los ficheros del archivo Phar actual
- Phar::delMetadata — Elimina los metadatos globales del phar
- Phar::delete — Elimina un fichero dentro de un archivo phar
- Phar::__destruct — Destruye un objeto archivo Phar
- Phar::extractTo — Extrae el contenido de un archivo phar hacia un directorio
- Phar::getAlias — Obtiene el alias para Phar
- Phar::getMetadata — Devuelve las metadatos del archivo phar
- Phar::getModified — Indica si el archivo phar ha sido modificado
- Phar::getPath — Obtiene la ruta de acceso absoluta del archivo Phar en el disco
- Phar::getSignature — Devuelve la firma MD5/SHA1/SHA256/SHA512 de un archivo Phar
- Phar::getStub — Retorna el cargador PHP o el contenedor de carga de un archivo Phar
- Phar::getSupportedCompression — Devuelve un array de los algoritmos de compresión soportados
- Phar::getSupportedSignatures — Devuelve un array de los tipos de firma soportados
- Phar::getVersion — Devuelve las informaciones de versión del archivo Phar
- Phar::hasMetadata — Determina si el phar contiene o no metadatos
- Phar::interceptFileFuncs — Indica a phar que debe interceptar las funciones de archivos
- Phar::isBuffering — Determina si las operaciones de escritura de Phar están en búfer o se escriben directamente en el disco
- Phar::isCompressed — Devuelve Phar::GZ o PHAR::BZ2 si el archivo completo está comprimido (.tar.gz/tar.bz, etc)
- Phar::isFileFormat — Retorna true si el archivo phar está basado en el formato de archivo tar/phar/zip según el argumento
- Phar::isValidPharFilename — Determina si el nombre de fichero especificado es un nombre de fichero válido para un archivo phar
- Phar::isWritable — Retorna true si el archivo phar puede ser modificado
- Phar::loadPhar — Carga cualquier archivo phar con un alias
- Phar::mapPhar — Lee el phar ejecutado y carga su manifiesto
- Phar::mount — Monta un camino o un fichero externo a una ubicación virtual dentro del archivo phar
- Phar::mungServer — Define una lista de un máximo de 4 variables $_SERVER que deben ser modificadas durante la ejecución
- Phar::offsetExists — Determina si un fichero existe en el phar
- Phar::offsetGet — Obtiene un objeto PharFileInfo a partir de un fichero
- Phar::offsetSet — Establece el contenido de un fichero interno en el archivo a partir del contenido de un fichero externo
- Phar::offsetUnset — Elimina un fichero de un phar
- Phar::running — Devuelve la ruta completa en el disco o la URL phar completa del archivo phar actualmente ejecutado
- Phar::setAlias — Establece el alias del archivo Phar
- Phar::setDefaultStub — Utilizado para establecer el cargador PHP o el contenedor de carga de un archivo Phar como cargador por defecto
- Phar::setMetadata — Establece las metadatos del archivo phar
- Phar::setSignatureAlgorithm — Establece y aplica el algoritmo de firma de un phar
- Phar::setStub — Utilizado para especificar el cargador PHP o el contenedor de carga de un archivo Phar
- Phar::startBuffering — Inicia el almacenamiento en búfer de escrituras Phar, sin modificar el objeto Phar en el disco
- Phar::stopBuffering — Detiene el almacenamiento en búfer de las escrituras Phar y provoca la escritura en el disco
- Phar::unlinkArchive — Elimina completamente un archivo phar del disco y de la memoria
- Phar::webPhar — Redirige una solicitud desde un navegador web a un fichero interno en el archivo phar

# La clase PharData

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

## Introducción

La clase PharData proporciona una interfaz de alto nivel para acceder y crear archivos tar y zip no ejecutables. Dado que estos archivos no contienen un contenedor y no pueden ser ejecutados por la extensión phar, es posible crear y manipular archivos zip y tar normales utilizando la clase PharData incluso si el parámetro `phar.readonly` del php.ini está a `1`.

## Sinopsis de la Clase

class PharData extends RecursiveDirectoryIterator implements Countable, ArrayAccess {
/* Constantes heredadas */
public const int FilesystemIterator::CURRENT_MODE_MASK;
public const int FilesystemIterator::CURRENT_AS_PATHNAME;
public const int FilesystemIterator::CURRENT_AS_FILEINFO;
public const int FilesystemIterator::CURRENT_AS_SELF;
public const int FilesystemIterator::KEY_MODE_MASK;
public const int FilesystemIterator::KEY_AS_PATHNAME;
public const int FilesystemIterator::FOLLOW_SYMLINKS;
public const int FilesystemIterator::KEY_AS_FILENAME;
public const int FilesystemIterator::NEW_CURRENT_AND_KEY;
public const int FilesystemIterator::OTHER_MODE_MASK;
public const int FilesystemIterator::SKIP_DOTS;
public const int FilesystemIterator::UNIX_PATHS;
/* Métodos */
public function __construct(
string `$filename`,
int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS,
?string `$alias` = `null`,
int `$format` = 0
)
public function addEmptyDir(string `$directory`): void
public function addFile(string `$filename`, ?string `$localName` = `null`): void
public function addFromString(string `$localName`, string `$contents`): void
public function buildFromDirectory(string `$directory`, string `$pattern` = ""): array
public function buildFromIterator(Traversable `$iterator`, ?string `$baseDirectory` = `null`): array
public function compress(int `$compression`, ?string `$extension` = `null`): ?PharData
public function compressFiles(int `$compression`): void
public function convertToData(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?PharData
public function convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar
public function copy(string `$from`, string `$to`): true
public function decompress(?string `$extension` = `null`): ?PharData
public function decompressFiles(): true
public function delMetadata(): true
public function delete(string `$localName`): true
public function extractTo(string `$directory`, array|string|null `$files` = `null`, bool `$overwrite` = `false`): bool
public function isWritable(): bool
public function offsetSet(string `$localName`, resource|string `$value`): void
public function offsetUnset(string `$localName`): void
public function setAlias(string `$alias`): bool
public function setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): bool
public function setMetadata(mixed `$metadata`): void
public function setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void
public function setStub(resource|string `$stub`, int `$length` = -1): true
public function __destruct()
/* Métodos heredados */
public function RecursiveDirectoryIterator::getChildren(): RecursiveDirectoryIterator
public function RecursiveDirectoryIterator::getSubPath(): string
public function RecursiveDirectoryIterator::getSubPathname(): string
public function RecursiveDirectoryIterator::hasChildren(bool `$allowLinks` = `false`): bool
public function RecursiveDirectoryIterator::key(): string
public function RecursiveDirectoryIterator::next(): void
public function RecursiveDirectoryIterator::rewind(): void
public function FilesystemIterator::current(): string|SplFileInfo|FilesystemIterator
public function FilesystemIterator::getFlags(): int
public function FilesystemIterator::key(): string
public function FilesystemIterator::next(): void
public function FilesystemIterator::rewind(): void
public function FilesystemIterator::setFlags(int `$flags`): void
public function DirectoryIterator::current(): mixed
public function DirectoryIterator::getBasename(string `$suffix` = ""): string
public function DirectoryIterator::getExtension(): string
public function DirectoryIterator::getFilename(): string
public function DirectoryIterator::isDot(): bool
public function DirectoryIterator::key(): mixed
public function DirectoryIterator::next(): void
public function DirectoryIterator::rewind(): void
public function DirectoryIterator::seek(int `$offset`): void
public function DirectoryIterator::__toString(): string
public function DirectoryIterator::valid(): bool
public function SplFileInfo::getATime(): int|false
public function SplFileInfo::getBasename(string `$suffix` = ""): string
public function SplFileInfo::getCTime(): int|false
public function SplFileInfo::getExtension(): string
public function SplFileInfo::getFileInfo(?string `$class` = `null`): SplFileInfo
public function SplFileInfo::getFilename(): string
public function SplFileInfo::getGroup(): int|false
public function SplFileInfo::getInode(): int|false
public function SplFileInfo::getLinkTarget(): string|false
public function SplFileInfo::getMTime(): int|false
public function SplFileInfo::getOwner(): int|false
public function SplFileInfo::getPath(): string
public function SplFileInfo::getPathInfo(?string `$class` = `null`): ?SplFileInfo
public function SplFileInfo::getPathname(): string
public function SplFileInfo::getPerms(): int|false
public function SplFileInfo::getRealPath(): string|false
public function SplFileInfo::getSize(): int|false
public function SplFileInfo::getType(): string|false
public function SplFileInfo::isDir(): bool
public function SplFileInfo::isExecutable(): bool
public function SplFileInfo::isFile(): bool
public function SplFileInfo::isLink(): bool
public function SplFileInfo::isReadable(): bool
public function SplFileInfo::isWritable(): bool
public function SplFileInfo::openFile(string `$mode` = "r", bool `$useIncludePath` = `false`, ?resource `$context` = `null`): SplFileObject
public function SplFileInfo::setFileClass(string `$class` = `SplFileObject::class`): void
public function SplFileInfo::setInfoClass(string `$class` = `SplFileInfo::class`): void
public function SplFileInfo::__toString(): string
}

# PharData::addEmptyDir

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addEmptyDir — Añade un directorio vacío al archivo tar/zip

### Descripción

public function PharData::addEmptyDir(string `$directory`): void

Con este método, se crea un directorio vacío con la ruta `dirname`. Este método es idéntico a ZipArchive::addEmptyDir().

### Parámetros

`directory`

  El nombre del directorio vacío a crear en el archivo phar

### Valores devueltos

No se devuelve ningún valor, se lanza una excepción en caso de fallo.

### Ejemplos

Ejemplo #1 Un ejemplo con PharData::addEmptyDir()

    <?php
    try {
        $a = new PharData('/ruta/al/archivo.tar');

        $a->addEmptyDir('/ruta/completa/al/fichero');
        // muestra cómo se almacena el fichero
        $b = $a['ruta/completa/al/fichero']->isDir();
    } catch (Exception $e) {
        // los errores se manejan aquí
    }
    ?>

### Ver también

- Phar::addEmptyDir() - Añade un directorio vacío al archivo phar
- PharData::addFile() - Añade un fichero del sistema de archivos al archivo tar/zip
- PharData::addFromString() - Añade un fichero a partir de un string al archivo tar/zip

# PharData::addFile

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addFile — Añade un fichero del sistema de archivos al archivo tar/zip

### Descripción

public function PharData::addFile(string `$filename`, ?string `$localName` = `null`): void

Con este método, cualquier fichero o URL puede ser añadido al archivo tar/zip. Si el segundo argumento opcional `localname` es especificado, el fichero será almacenado en el archivo con este nombre, de lo contrario el argumento `file` es utilizado como ruta hacia donde almacenar el fichero dentro de el archivo. Las URLs deben tener un nombre local de lo contrario se lanza una excepción. Este método es idéntico a ZipArchive::addFile().

### Parámetros

`filename`

  Ruta relativa o absoluta hacia un fichero del disco a añadir al archivo phar.

`localName`

  Ruta hacia donde el fichero será almacenado dentro del archivo.

### Valores devueltos

No se devuelve ningún valor, se lanza una excepción en caso de fallo.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `localName` ahora es nullable.

### Ejemplos

Ejemplo #1 Un ejemplo con PharData::addFile()

    <?php
    try {
        $a = new PharData('/ruta/al/archivo.tar');

        $a->addFile('/ruta/completa/al/fichero');
        // muestra cómo el fichero es almacenado
        $b = $a['ruta/completa/al/fichero']->getContent();

        $a->addFile('/ruta/completa/al/fichero', 'mi/fichero.txt');
        $c = $a['mi/fichero.txt']->getContent();

        // muestra el uso de URLs
        $a->addFile('http://www.ejemplo.com', 'ejemplo.html');
    } catch (Exception $e) {
        // los errores son manejados aquí
    }
    ?>

### Notas

> Nota: PharData::addFile(), PharData::addFromString() y PharData::offsetSet() registran un nuevo archivo phar cada vez que son llamadas. Si las prestaciones son una preocupación, PharData::buildFromDirectory() o PharData::buildFromIterator() deberían ser utilizadas en su lugar.

### Ver también

- PharData::offsetSet() - Rellena un fichero dentro del archivo tar/zip con el contenido de un fichero externo o de un string
- Phar::addFile() - Añade un fichero del sistema de ficheros al archivo phar
- PharData::addFromString() - Añade un fichero a partir de un string al archivo tar/zip
- PharData::addEmptyDir() - Añade un directorio vacío al archivo tar/zip

# PharData::addFromString

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addFromString — Añade un fichero a partir de un string al archivo tar/zip

### Descripción

public function PharData::addFromString(string `$localName`, string `$contents`): void

Añade un string al archivo tar/zip. El fichero será almacenado en el archivo con la ruta `localname`. Este método es idéntico a ZipArchive::addFromString().

### Parámetros

`localName`

  Ruta hacia la cual el fichero será almacenado dentro del archivo.

`contents`

  El contenido del fichero a almacenar

### Valores devueltos

No hay valor de retorno, se lanza una excepción en caso de fallo.

### Ejemplos

Ejemplo #1 Ejemplo con PharData::addFromString()

    <?php
    try {
        $a = new PharData('/ruta/versus/mon.tar');

        $a->addFromString('ruta/versus/fichero.txt', 'mi fichero simple');
        $b = $a['ruta/versus/fichero.txt']->getContent();

        // para añadir contenido a partir de un manejador de flujo para archivos grandes, utilice offsetSet()
        $c = fopen('/ruta/versus/grandearchivo.bin');
        $a['grandearchivo.bin'] = $c;
        fclose($c);
    } catch (Exception $e) {
        // los errores son tratados aquí
    }
    ?>

### Notas

> Nota: Phar::addFile(), Phar::addFromString() y Phar::offsetSet() registran un nuevo archivo phar cada vez que son llamadas. Si las prestaciones son una preocupación, Phar::buildFromDirectory() o Phar::buildFromIterator() deberían ser utilizadas en su lugar.

### Ver también

- PharData::offsetSet() - Rellena un fichero dentro del archivo tar/zip con el contenido de un fichero externo o de un string
- Phar::addFromString() - Añade un fichero desde un string al archivo phar
- PharData::addFile() - Añade un fichero del sistema de archivos al archivo tar/zip
- PharData::addEmptyDir() - Añade un directorio vacío al archivo tar/zip

# PharData::buildFromDirectory

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::buildFromDirectory — Construye un archivo tar/zip a partir de los ficheros de un directorio

### Descripción

public function PharData::buildFromDirectory(string `$directory`, string `$pattern` = ""): array

Rellena un archivo tar/zip a partir del contenido de un directorio. El segundo argumento opcional es una expresión regular (pcre) utilizada para excluir ficheros. Cualquier fichero cuyo nombre cumpla la expresión será incluido, todos los demás serán excluidos. Para un control más fino, utilice PharData::buildFromIterator().

### Parámetros

`directory`

  La ruta relativa o absoluta hacia el directorio que contiene todos los ficheros a añadir al archivo.

`pattern`

  Una expresión regular opcional que se utiliza para filtrar la lista de ficheros. Solo los ficheros cuyos nombres cumplan la expresión serán incluidos en el archivo.

### Valores devueltos

Phar::buildFromDirectory() devuelve un array asociativo que hace corresponder una ruta de fichero interno con una ruta completa en el sistema de ficheros, o `false` si ocurre un error.

### Errores/Excepciones

Este método lanza una excepción BadMethodCallException cuando no es capaz de instanciar los iteradores internos de directorio, o una excepción PharException si se han encontrado errores durante el registro del archivo phar.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | PharData::buildFromDirectory() ya no devuelve `false`.

### Ejemplos

Ejemplo #1 Un ejemplo con PharData::buildFromDirectory()

    <?php
    $phar = new PharData('projet.tar');
    // añade todos los ficheros al proyecto
    $phar->buildFromDirectory(dirname(__FILE__) . '/projet');

    $phar2 = new PharData('projet2.zip');
    // añade todos los ficheros al proyecto incluyendo solo los ficheros php
    $phar2->buildFromDirectory(dirname(__FILE__) . '/projet', '/\.php$/');
    ?>

### Ver también

- Phar::buildFromDirectory() - Construye un archivo phar a partir de los ficheros de un directorio
- PharData::buildFromIterator() - Construye un archivo tar o zip a partir de un iterador

# PharData::buildFromIterator

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::buildFromIterator — Construye un archivo tar o zip a partir de un iterador

### Descripción

public function PharData::buildFromIterator(Traversable `$iterator`, ?string `$baseDirectory` = `null`): array

Rellena un archivo tar o zip a partir de un iterador. Dos estilos de iteradores son soportados, los iteradores que hacen corresponder la ruta de archivo dentro del archivo con la ruta en el disco y los iteradores como DirectoryIterator que devuelven objetos SplFileInfo. Para los iteradores que devuelven objetos SplFileInfo, el segundo argumento es requerido.

### Parámetros

`iterator`

  Cualquier iterador que haga corresponder de forma asociativa un archivo tar/zip o que devuelva objetos SplFileInfo

`baseDirectory`

  Para los iteradores que devuelven objetos SplFileInfo, la parte del camino completo hacia el archivo a eliminar al añadir al archivo tar/zip

### Valores devueltos

PharData::buildFromIterator() devuelve un array asociativo que hace corresponder una ruta de archivo interna con una ruta completa hacia el archivo en el sistema de archivos.

### Errores/Excepciones

Este método devuelve una excepción UnexpectedValueException cuando el iterador devuelve valores incorrectos, como una clave entera en lugar de una cadena, una excepción BadMethodCallException cuando se pasa un iterador basado en SplFileInfo sin el argumento `baseDirectory`, o una excepción PharException si se han encontrado errores al guardar el archivo phar.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | PharData::buildFromIterator() ya no devuelve `false` ahora.
8.0.0 | `baseDirectory` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con PharData::buildFromIterator() y SplFileInfo

Para la mayoría de los archivos tar/zip, el archivo reflejará la estructura de directorio actual y el segundo estilo es el más útil. Por ejemplo, para crear un archivo tar/zip que contenga los archivos con la estructura de directorio a continuación:

    /chemin/vers/projet/
                     config/
                            dist.xml
                            debug.xml
                     lib/
                         fichier1.php
                         fichier2.php
                     src/
                         processthing.php
                     www/
                         index.php
                     cli/
                         index.php

Este código puede ser utilizado para añadir archivos a el archivo "projet.tar" tar:

    <?php
    $phar = new PharData('projet.tar');
    $phar->buildFromIterator(
        new RecursiveIteratorIterator(
         new RecursiveDirectoryIterator('/chemin/vers/projet')),
        '/chemin/vers/projet');
    ?>

El archivo `projet.tar` puede entonces ser borrado inmediatamente. PharData::buildFromIterator() no establece parámetros como la compresión, las metadatos, lo cual puede ser hecho después de haber creado el archivo tar/zip.

Se debe notar que Phar::buildFromIterator() también puede ser utilizado para copiar el contenido de un archivo phar, tar o zip existente, ya que el objeto PharData es derivado de DirectoryIterator:

    <?php
    $phar = new PharData('projet.tar');
    $phar->buildFromIterator(
        new RecursiveIteratorIterator(
         new Phar('/chemin/vers/unautrephar.phar')),
        'phar:///chemin/vers/unautrephar.phar/chemin/vers/projet');
    $phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
    ?>

Ejemplo #2 Ejemplo con PharData::buildFromIterator() y otros iteradores

La segunda forma de iterador puede ser utilizada con cualquier iterador que devuelva una asociación clave => valor, tal como ArrayIterator:

    <?php
    $phar = new PharData('projet.tar');
    $phar->buildFromIterator(
        new ArrayIterator(
         array(
            'interne/fichier.php' => dirname(__FILE__) . '/unfichier.php',
            'unautre/fichier.jpg' => fopen('/chemin/vers/grosfichier.jpg', 'rb'),
         )));
    ?>

### Ver también

- Phar::buildFromIterator() - Construye un archivo phar a partir de un iterador

# PharData::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::compress — Comprime el archivo tar/zip completo utilizando la compresión Gzip o Bzip2

### Descripción

public function PharData::compress(int `$compression`, ?string `$extension` = `null`): ?PharData

Para los archivos tar, este método comprime el archivo completo utilizando la compresión gzip o bzip2. El archivo resultante puede ser manipulado con el comando gunzip/bunzip, o ser accedido directamente y de forma transparente con la extensión Phar.

Para los archivos zip, este método falla al lanzar una excepción. La extensión zlib debe estar activada para comprimir con gzip, la extensión bzip2 debe estar activada para comprimir con bzip2.

Asimismo, este método renombra automáticamente el archivo, añadiendo el sufijo `.gz`, `.bz2` o eliminando la extensión si `Phar::NONE` es especificado para eliminar la compresión. De lo contrario, una extensión de archivo puede ser especificada con el segundo argumento.

### Parámetros

`compression`

  La compresión debe ser `Phar::GZ` o `Phar::BZ2` para aplicar una compresión, o `Phar::NONE` para eliminarla.

`extension`

  Por omisión, la extensión es `.tar.gz` o `.tar.bz2` para comprimir un tar, y `.tar` para descomprimir.

### Valores devueltos

Un objeto PharData es devuelto en caso de éxito, `null` en caso de error.

### Errores/Excepciones

Levanta una excepción BadMethodCallException si la extensión zlib no está disponible, o si la extensión bzip2 no está activada.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `extension` ahora es nullable.

### Ejemplos

Ejemplo #1 Un ejemplo con PharData::compress()

    <?php
    $p = new PharData('/ruta/al/mio.tar');
    $p['monfichier.txt'] = 'salut';
    $p['monfichier2.txt'] = 'salut';
    $p1 = $p->compress(Phar::GZ); // copies hacia /path/to/my.tar.gz
    $p2 = $p->compress(Phar::BZ2); // copies hacia /path/to/my.tar.bz2
    $p3 = $p2->compress(Phar::NONE); // excepción: /path/to/my.tar ya existe
    ?>

### Ver también

- Phar::compress() - Comprime el archivo Phar completo utilizando la compresión Gzip o Bzip2

# PharData::compressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::compressFiles — Comprime todos los ficheros del archivo tar/zip actual

### Descripción

public function PharData::compressFiles(int `$compression`): void

Para los archivos basados en tar, este método genera una excepción BadMethodCallException ya que la compresión individual de los ficheros de un archivo tar no es soportada por este formato de archivo. Utilice PharData::compress() para comprimir un archivo basado en tar completo.

Para los archivos basados en Zip, este método comprime todos los ficheros del archivo utilizando la compresión especificada. Las extensiones zlib o bzip2 deben estar activadas para aprovechar esta funcionalidad. Además, si al menos un fichero ya está comprimido utilizando la compresión bzip2/zlib, la extensión adecuada debe estar activada para descomprimir los ficheros antes de volver a comprimirlos.

### Parámetros

`compression`

  La compresión debe ser `Phar::GZ` o `Phar::BZ2` para aplicar una compresión, o `Phar::NONE` para eliminarla.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

Genera una excepción BadMethodCallException si la variable INI phar.readonly está a on, si la extensión zlib no está disponible o si al menos un fichero está comprimido vía bzip2 y la extensión bzip2 no está activada.

### Ejemplos

Ejemplo #1 Un ejemplo con PharData::compressFiles()

    <?php
    $p = new Phar('/ruta/al/mon.phar', 0, 'mon.phar');
    $p['monfichero.txt'] = 'hola';
    $p['monfichero2.txt'] = 'hola';
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    $p->compressFiles(Phar::GZ);
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    ?>

El ejemplo anterior mostrará:

    string(14) "monfichero.txt"
    bool(false)
    bool(false)
    bool(false)
    string(15) "monfichero2.txt"
    bool(false)
    bool(false)
    bool(false)
    string(14) "monfichero.txt"
    int(4096)
    bool(false)
    bool(true)
    string(15) "monfichero2.txt"
    int(4096)
    bool(false)
    bool(true)

### Ver también

- PharFileInfo::getCompressedSize() - Devuelve el tamaño actual (con compresión) del fichero dentro del archivo Phar
- PharFileInfo::isCompressed() - Indica si la entrada está comprimida
- PharFileInfo::compress() - Comprime la entrada Phar actual con una de las compresiones zlib o bzip2
- PharFileInfo::decompress() - Descomprime la entrada Phar actual dentro del phar
- Phar::canCompress() - Determina si la extensión phar soporta la compresión utilizando zip o bzip2
- Phar::isCompressed() - Devuelve Phar::GZ o PHAR::BZ2 si el archivo completo está comprimido (.tar.gz/tar.bz, etc)
- PharData::decompressFiles() - Descomprime todos los ficheros del archivo zip actual
- Phar::getSupportedCompression() - Devuelve un array de los algoritmos de compresión soportados
- PharData::compress() - Comprime el archivo tar/zip completo utilizando la compresión Gzip o Bzip2
- PharData::decompress() - Descomprime el archivo Phar completo

# PharData::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::__construct — Construye un objeto de archivo tar o zip no ejecutable

### Descripción

public function PharData::__construct(
string `$filename`,
int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS,
?string `$alias` = `null`,
int `$format` = 0
)

### Parámetros

`filename`

  Ruta hacia un archivo tar/zip existente o a crear

`flags`

  Banderas a pasar a la clase padre Phar RecursiveDirectoryIterator.

`alias`

  El alias del archivo Phar a utilizar durante las llamadas a las funcionalidades de flujo.

`format`

  Una de las constantes de formato de archivo disponibles en la clase Phar.

### Errores/Excepciones

Levanta una excepción BadMethodCallException si es llamada dos veces, una excepción UnexpectedValueException si el archivo phar no puede ser abierto.

### Ejemplos

Ejemplo #1 Un ejemplo con PharData::__construct()

    <?php
    try {
        $p = new PharData('/path/to/my.tar', Phar::CURRENT_AS_FILEINFO | Phar::KEY_AS_FILENAME);
    } catch (UnexpectedValueException $e) {
        die('No puede abrir my.tar');
    } catch (BadMethodCallException $e) {
        echo 'técnicamente, esto no puede ocurrir';
    }
    echo file_get_contents('phar:///ruta/vers/my.tar/ejemplo.txt');
    ?>

# PharData::convertToData

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::convertToData — Convierte un archivo phar en un archivo tar o zip no ejecutable

### Descripción

public function PharData::convertToData(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?PharData

Este método se utiliza para convertir un archivo tar o zip no ejecutable en otro formato no ejecutable.

Si no se solicita ningún cambio, este método, este método lanza una excepción BadMethodCallException. Este método debe utilizarse para convertir un archivo tar al formato zip y viceversa. Aunque es posible cambiar la compresión de un archivo tar con este método, es preferible utilizar el método PharData::compress() para mantener la coherencia a nivel de lógica.

En caso de éxito, este método crea un nuevo archivo en el disco y devuelve un objeto PharData. El archivo antiguo no se borra del disco, lo cual debe hacerse manualmente una vez finalizado el procesamiento.

### Parámetros

`format`

  El formato debe ser `Phar::TAR` o `Phar::ZIP`. Si es `null`, se conservará el formato de archivo actual.

`compression`

  La compresión debe ser `Phar::NONE` para evitar la compresión del archivo completo, `Phar::GZ` para la compresión basada en zlib, y `Phar::BZ2` para la compresión basada en bzip.

`extension`

  Este parámetro se utiliza para sobrescribir la extensión de archivo por defecto del archivo convertido. Tenga en cuenta que `.phar` no puede utilizarse en ninguna parte del nombre de archivo de un archivo tar o zip no ejecutable.

  En caso de conversión a un archivo phar basado en tar, las extensiones por defecto son `.tar`, `.tar.gz` y `.tar.bz2` según la compresión especificada. Para los archivos basados en zip, la extensión por defecto es `.zip`.

### Valores devueltos

Este método devuelve un objeto PharData en caso de éxito, o `null` en caso de fallo.

### Errores/Excepciones

Este método lanza una excepción BadMethodCallException cuando no es capaz de comprimir, cuando se ha especificado un método de compresión desconocido, cuando el archivo solicitado está en búfer con Phar::startBuffering() y no se ha finalizado con Phar::stopBuffering(), y lanza una excepción PharException si se produce algún problema durante la creación del phar.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `format`, `compression`, y `extension` ahora son nullable.

### Ejemplos

Ejemplo #1 Un ejemplo con PharData::convertToData()

Utilicemos PharData::convertToData():

    <?php
    try {
        $tarphar = new PharData('monphar.tar');
        // note que monphar.tar no se *borra*
        // al convertirlo al formato tar no ejecutable
        // se crea monphar.zip
        $zip = $tarphar->convertToData(Phar::ZIP);
        // se crea monphar.tbz
        $tgz = $zip->convertToData(Phar::TAR, Phar::BZ2, '.tbz');
        // se crea monphar.phar.tgz
        $phar = $tarphar->convertToData(Phar::PHAR); // lanza una excepción
    } catch (Exception $e) {
        // los errores se manejan aquí
    }
    ?>

### Ver también

- Phar::convertToExecutable() - Convierte un archivo phar a otro formato de archivo de archivo phar ejecutable
- Phar::convertToData() - Convierte un archivo phar en un fichero no ejecutable
- PharData::convertToExecutable() - Convierte un archivo tar/zip no ejecutable en un archivo phar ejecutable

# PharData::convertToExecutable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::convertToExecutable — Convierte un archivo tar/zip no ejecutable en un archivo phar ejecutable

### Descripción

public function PharData::convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Este método se utiliza para convertir un archivo tar o zip no ejecutable en un archivo phar ejecutable. Cualquiera de los tres formatos de archivo (phar, tar o zip) puede ser utilizado y la compresión del archivo completo también es posible.

Si no se solicita ningún cambio, este método lanza una excepción BadMethodCallException.

En caso de éxito, este método crea un nuevo archivo en el disco y devuelve un objeto Phar. El archivo antiguo no se borra del disco, lo cual debe hacerse manualmente una vez finalizado el procesamiento.

### Parámetros

`format`

  El formato debe ser `Phar::PHAR`, `Phar::TAR` o `Phar::ZIP`. Si es `null`, se conservará el formato de archivo actual.

`compression`

  La compresión debe ser `Phar::NONE` para evitar la compresión del archivo completo, `Phar::GZ` para la compresión basada en zlib, y `Phar::BZ2` para la compresión basada en bzip.

`extension`

  Este parámetro se utiliza para sobrescribir la extensión de archivo por defecto del archivo convertido. Tenga en cuenta que todos los archivos basados en tar y zip deben contener `.phar` en su extensión de archivo para poder ser tratados como archivos phar.

  En caso de conversión a un archivo basado en phar, las extensiones por defecto son `.phar`, `.phar.gz` o `.phar.bz2` según la compresión especificada. Para los archivos phar basados en tar, las extensiones por defecto son `.phar.tar`, `.phar.tar.gz` y `.phar.tar.bz2`. Para los archivos phar basados en zip, la extensión por defecto es `.phar.zip`.

### Valores devueltos

Este método devuelve un objeto Phar en caso de éxito, o `null` en caso de fallo

### Errores/Excepciones

Este método lanza una excepción BadMethodCallException cuando no puede comprimir, cuando se ha especificado un método de compresión desconocido, cuando el archivo solicitado está en búfer con Phar::startBuffering() y no se ha concluido con Phar::stopBuffering(), lanza una excepción UnexpectedValueException si el soporte de escritura está desactivado, y lanza una excepción PharException si se han encontrado problemas durante la creación del phar.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `format`, `compression`, y `localName` ahora son nullable.

### Ejemplos

Ejemplo #1 Un ejemplo con PharData::convertToExecutable()

Utilizando PharData::convertToExecutable() :

    <?php
    try {
        $tarphar = new PharData('monphar.tar');
        // lo convierte al formato de archivo phar
        // note que monphar.tar *no* se borra
        $phar = $tarphar->convertToExecutable(Phar::PHAR); // crea monphar.phar
        $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
        // crea monphar.phar.tgz
        $compressed = $tarphar->convertToExecutable(Phar::TAR, Phar::GZ, '.phar.tgz');
    } catch (Exception $e) {
        // los errores se manejan aquí
    }
    ?>

### Ver también

- Phar::convertToExecutable() - Convierte un archivo phar a otro formato de archivo de archivo phar ejecutable
- Phar::convertToData() - Convierte un archivo phar en un fichero no ejecutable
- PharData::convertToData() - Convierte un archivo phar en un archivo tar o zip no ejecutable

# PharData::copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::copy — Copia un fichero interno del archivo tar/zip a otro fichero dentro del mismo archivo

### Descripción

public function PharData::copy(string `$from`, string `$to`): true

Copia un fichero interno del archivo tar/zip a otro fichero dentro del mismo archivo. Es una alternativa orientada a objetos al uso de copy() con el gestor de flujos phar.

### Parámetros

`from`

`to`

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

Se lanza una excepción UnexpectedValueException si el fichero de origen no existe, si el fichero de destino ya existe, si el soporte de escritura está desactivado, si falla la apertura de alguno de los dos ficheros o si falla la lectura del fichero de origen; o se lanza una excepción PharException si falla la escritura de los cambios del archivo phar.

### Ejemplos

Ejemplo #1 Un ejemplo con PharData::copy()

Este ejemplo muestra el uso de PharData::copy() y su equivalente en términos de gestor de flujos. La principal diferencia entre ambos enfoques radica en la gestión de errores. Todos los métodos PharData lanzan excepciones, mientras que el gestor de flujos utiliza trigger_error().

    <?php

    try {
        $phar = new PharData('monphar.tar');
        $phar['a'] = 'salut';
        $phar->copy('a', 'b');
        echo $phar['b']; // Muestra "phar://myphar.tar/b"
    } catch (Exception $e) {
        // Se manejan los errores
    }

    // El equivalente en términos de flujo del ejemplo anterior.
    // Se lanzan E_WARNING en caso de error en lugar de excepciones.
    copy('phar://monphar.tar/a', 'phar//monphar.tar/c');
    echo file_get_contents('phar://monphar.tar/c'); // Muestra "salut"
    ?>

# PharData::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::decompress — Descomprime el archivo Phar completo

### Descripción

public function PharData::decompress(?string `$extension` = `null`): ?PharData

Descomprime el archivo completo, si es un archivo tar.

Para los archivos Zip, este método falla y lanza una excepción. La extensión zlib debe estar activada para descomprimir un archivo comprimido con gzip y la extensión bzip2 debe estar disponible para descomprimir un archivo comprimido con bzip2.

Además, este método renombra automáticamente la extensión de archivo del archivo, `.tar` por defecto. De lo contrario, una extensión de archivo puede especificarse con el argumento `extension`.

### Parámetros

`extension`

  Para descomprimir, la extensión por defecto es `.tar`. Utilice este argumento para especificar otra extensión de archivo. Tenga en cuenta que solo los archivos ejecutables pueden contener `.phar` en su nombre de archivo.

### Valores devueltos

Un objeto PharData es devuelto en caso de éxito, o `null` en caso de fallo.

### Errores/Excepciones

Levanta una excepción BadMethodCallException si la extensión zlib no está disponible o si la extensión bzip2 no está activada.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `extension` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con PharData::decompress()

    <?php
    $p = new PharData('/path/to/my.tar.gz');
    $p->decompress(); // crea /path/to/my.tar
    ?>

### Ver también

- PharFileInfo::getCompressedSize() - Devuelve el tamaño actual (con compresión) del fichero dentro del archivo Phar
- PharFileInfo::isCompressed() - Indica si la entrada está comprimida
- PharFileInfo::compress() - Comprime la entrada Phar actual con una de las compresiones zlib o bzip2
- PharFileInfo::decompress() - Descomprime la entrada Phar actual dentro del phar
- PharData::compress() - Comprime el archivo tar/zip completo utilizando la compresión Gzip o Bzip2
- Phar::canCompress() - Determina si la extensión phar soporta la compresión utilizando zip o bzip2
- Phar::isCompressed() - Devuelve Phar::GZ o PHAR::BZ2 si el archivo completo está comprimido (.tar.gz/tar.bz, etc)
- PharData::compress() - Comprime el archivo tar/zip completo utilizando la compresión Gzip o Bzip2
- Phar::getSupportedCompression() - Devuelve un array de los algoritmos de compresión soportados
- PharData::compressFiles() - Comprime todos los ficheros del archivo tar/zip actual
- PharData::decompressFiles() - Descomprime todos los ficheros del archivo zip actual

# PharData::decompressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::decompressFiles — Descomprime todos los ficheros del archivo zip actual

### Descripción

public function PharData::decompressFiles(): true

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Para los archivos basados en tar, este método levanta una excepción BadMethodCallException, ya que la compresión individual de los ficheros dentro de un archivo tar no es soportada por el formato de archivo. Utilice PharData::compress() para comprimir un archivo completo basado en tar.

Para los archivos basados en Zip, este método descomprime todos los ficheros del archivo. Las extensiones zlib o bzip2 deben estar activadas para aprovechar esta funcionalidad si al menos uno de los ficheros está comprimido con bzip2/zlib.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

Levanta una excepción BadMethodCallException si la extensión zlib no está disponible o si al menos uno de los ficheros está comprimido con bzip2 y la extensión bzip2 no está activada.

### Ejemplos

Ejemplo #1 Un ejemplo con PharData::decompressFiles()

    <?php
    $p = new PharData('/ruta/hacia/mion.zip');
    $p['mifichero.txt'] = 'hola';
    $p['mifichero2.txt'] = 'hola';
    $p->compressFiles(Phar::GZ);
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    $p->decompressFiles();
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    ?>

El ejemplo anterior mostrará:

    string(14) "mifichero.txt"
    int(4096)
    bool(false)
    bool(true)
    string(15) "mifichero2.txt"
    int(4096)
    bool(false)
    bool(true)
    string(14) "mifichero.txt"
    bool(false)
    bool(false)
    bool(false)
    string(15) "mifichero2.txt"
    bool(false)
    bool(false)
    bool(false)

### Ver también

- PharFileInfo::getCompressedSize() - Devuelve el tamaño actual (con compresión) del fichero dentro del archivo Phar
- PharFileInfo::isCompressed() - Indica si la entrada está comprimida
- PharFileInfo::compress() - Comprime la entrada Phar actual con una de las compresiones zlib o bzip2
- PharFileInfo::decompress() - Descomprime la entrada Phar actual dentro del phar
- Phar::canCompress() - Determina si la extensión phar soporta la compresión utilizando zip o bzip2
- Phar::isCompressed() - Devuelve Phar::GZ o PHAR::BZ2 si el archivo completo está comprimido (.tar.gz/tar.bz, etc)
- PharData::compressFiles() - Comprime todos los ficheros del archivo tar/zip actual
- Phar::getSupportedCompression() - Devuelve un array de los algoritmos de compresión soportados
- PharData::compress() - Comprime el archivo tar/zip completo utilizando la compresión Gzip o Bzip2
- PharData::decompress() - Descomprime el archivo Phar completo

# PharData::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::delMetadata — Elimina los metadatos globales de un archivo zip

### Descripción

public function PharData::delMetadata(): true

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Elimina los metadatos globales del archivo zip

### Parámetros

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

Se genera una excepción PharException si se producen errores durante la escritura de los cambios en el disco.

### Ejemplos

Ejemplo #1 Un ejemplo con PharData::delMetaData()

    <?php
    try {
        $phar = new PharData('monphar.zip');
        var_dump($phar->getMetadata());
        $phar->setMetadata("salut");
        var_dump($phar->getMetadata());
        $phar->delMetadata();
        var_dump($phar->getMetadata());
    } catch (Exception $e) {
        // se manejan los errores
    }
    ?>

El ejemplo anterior mostrará:

    NULL
    string(5) "salut"
    NULL

### Ver también

- Phar::delMetadata() - Elimina los metadatos globales del phar

# PharData::delete

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::delete — Elimina un fichero dentro del archivo tar/zip

### Descripción

public function PharData::delete(string `$localName`): true

Elimina un fichero dentro del archivo. Es equivalente a la llamada a unlink() utilizando el manejador de flujo phar, como se muestra en el ejemplo a continuación.

### Parámetros

`localName`

  Ruta del fichero a eliminar dentro del archivo.

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

Genera una excepción PharException si se producen errores durante la escritura de los cambios en el disco.

### Ejemplos

Ejemplo #1 Un ejemplo con PharData::delete()

    <?php
    try {
        $phar = new PharData('monphar.zip');
        $phar->delete('efface/moi.php');
        // es equivalente a:
        unlink('phar://monphar.phar/efface/mon.php');
    } catch (Exception $e) {
        // se manejan los errores
    }
    ?>

### Ver también

- Phar::delete() - Elimina un fichero dentro de un archivo phar

# PharData::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::__destruct — Destruye un objeto tar no ejecutable o un archivo zip

### Descripción

public function PharData::__destruct()

### Parámetros

Esta función no contiene ningún parámetro.

# PharData::extractTo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::extractTo — Extrae el contenido de un archivo tar/zip hacia un directorio

### Descripción

public function PharData::extractTo(string `$directory`, array|string|null `$files` = `null`, bool `$overwrite` = `false`): bool

Extrae todos los ficheros de un archivo tar/zip hacia el disco. Los ficheros y directorios extraídos conservan los permisos tal como en el archivo. Los parámetros opcionales permiten un eventual control sobre qué ficheros serán extraídos y si los ficheros ya existentes en el disco pueden ser sobrescritos. El segundo parámetro `files` puede ser el nombre de un fichero o directorio a extraer, o un array de nombres de ficheros y directorios a extraer. Por omisión, este método no sobrescribirá ningún fichero ya existente, a menos que el tercer parámetro sea `true`. Este método es idéntico a ZipArchive::extractTo().

### Parámetros

`directory`

  Ruta donde los ficheros serán extraídos.

`files`

  El nombre de un fichero o directorio a extraer, o un array de ficheros/directorios a extraer

`overwrite`

  Pasarlo a `true` para activar la sobrescritura de ficheros ya existentes

### Valores devueltos

Devuelve `true` en caso de éxito, pero es preferible verificar las excepciones lanzadas y considerar el éxito si ninguna se produce.

### Errores/Excepciones

Lanza una excepción PharException si se encuentran errores al escribir los cambios en el disco.

### Ejemplos

Ejemplo #1 Ejemplo con PharData::extractTo()

    <?php
    try {
        $phar = new PharData('monphar.tar');
        $phar->extractTo('/ruta/completa'); // extrae todos los ficheros
        $phar->extractTo('/otra/ruta', 'fichero.txt'); // extrae solo fichero.txt
        $phar->extractTo('/esta/ruta',
            array('fichero1.txt', 'fichero2.txt')); // extrae solo 2 ficheros
        $phar->extractTo('/tercera/ruta', null, true); // extrae todos los ficheros, sobrescribiendo
    } catch (Exception $e) {
        // se manejan los errores
    }
    ?>

### Notas

> Nota: Los sistemas de archivos NTFS de Windows no soportan ciertos caracteres en los nombres de archivo, como `<|>*?":`. Los nombres de archivo con un punto final no son soportados. A diferencia de algunas herramientas de extracción, este método no reemplaza estos caracteres con un guión bajo, sino que falla al extraer tales archivos.

### Ver también

- Phar::extractTo() - Extrae el contenido de un archivo phar hacia un directorio

# PharData::isWritable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::isWritable — Verifica si el archivo tar/zip puede ser modificado

### Descripción

public function PharData::isWritable(): bool

Este método devuelve `true` si el archivo tar/zip en el disco no es de solo lectura. A diferencia de Phar::isWritable(), los archivos tar/zip de datos pueden ser modificados incluso si `phar.readonly` está a `1`.

### Parámetros

No se proporcionan argumentos.

### Valores devueltos

Devuelve `true` si el archivo tar/zip puede ser modificado

### Ver también

- Phar::canWrite() - Determina si la extensión phar soporta la creación y escritura de archivos phar
- Phar::isWritable() - Retorna true si el archivo phar puede ser modificado

# PharData::offsetSet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::offsetSet — Rellena un fichero dentro del archivo tar/zip con el contenido de un fichero externo o de un string

### Descripción

public function PharData::offsetSet(string `$localName`, resource|string `$value`): void

Es una implementación de la interfaz ArrayAccess que permite la manipulación directa del contenido de un archivo tar/zip utilizando los corchetes, operadores de acceso al array. offsetSet es utilizado para modificar un fichero existente o para añadir un nuevo fichero al archivo tar/zip.

### Parámetros

`localName`

  La ruta (relativa) del fichero a modificar dentro del archivo tar o zip.

`value`

  Contenido del fichero.

### Valores devueltos

No se devuelve ningún valor.

### Errores/Excepciones

Se lanza una excepción PharException si se han encontrado problemas al escribir en el disco los cambios del archivo tar/zip.

### Ejemplos

Ejemplo #1 Un ejemplo con PharData::offsetSet()

offsetSet no debe ser accedido directamente, sino que debe ser utilizado a través del operador `[]`.

    <?php
    $p = new PharData('/ruta/al/mon.tar');
    try {
        // llama a offsetSet
        $p['fichero.txt'] = 'Hola';
    } catch (Exception $e) {
        echo 'No se puede modificar fichero.txt:', $e;
    }
    ?>

### Notas

> Nota: Phar::addFile(), Phar::addFromString() y Phar::offsetSet() registran un nuevo archivo phar cada vez que son llamadas. Si las prestaciones son una preocupación, Phar::buildFromDirectory() o Phar::buildFromIterator() deberían ser utilizadas en su lugar.

### Ver también

- Phar::offsetSet() - Establece el contenido de un fichero interno en el archivo a partir del contenido de un fichero externo

# PharData::offsetUnset

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::offsetUnset — Elimina un fichero de un archivo tar/zip

### Descripción

public function PharData::offsetUnset(string `$localName`): void

Es una implementación de la interfaz ArrayAccess que permite la manipulación directa del contenido de un archivo tar/zip utilizando los corchetes, operadores de acceso al array. offsetUnset es utilizado para borrar un fichero existente y es llamado por la construcción de lenguaje unset().

### Parámetros

`localName`

  La ruta (relativa) del fichero a modificar dentro del archivo tar o zip.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

Genera una excepción PharException si se han encontrado problemas al escribir en el disco los cambios del archivo tar/zip.

### Ejemplos

Ejemplo #1 Un ejemplo con PharData::offsetUnset()

    <?php
    $p = new PharData('/ruta/al/mon.zip');
    try {
        // borra archivo.txt de mon.zip llamando a offsetUnset
        unset($p['archivo.txt']);
    } catch (Exception $e) {
        echo 'No puede borrar archivo.txt: ', $e;
    }
    ?>

### Ver también

- Phar::offsetUnset() - Elimina un fichero de un phar

# PharData::setAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setAlias — Función inútil (Phar::setAlias no es válido para PharData)

### Descripción

public function PharData::setAlias(string `$alias`): bool

Los archivos tar/zip no ejecutables no pueden tener alias, por lo que este método solo genera una excepción.

### Parámetros

`alias`

  Una corta cadena de caracteres a la cual referirse para invocar al archivo mediante el gestor de flujos phar. Este argumento es ignorado.

### Valores devueltos

### Errores/Excepciones

Genera una excepción PharException al llamar al método

### Ver también

- Phar::setAlias() - Establece el alias del archivo Phar

# PharData::setDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setDefaultStub — Función inútil (Phar::setDefaultStub no es válido para PharData)

### Descripción

public function PharData::setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): bool

Los archivos tar/zip no ejecutables no pueden tener un contenedor de carga, por lo que este método solo genera una excepción.

### Parámetros

`index`

  Ruta relativa dentro del archivo phar a ejecutar en caso de acceso desde la línea de comandos

`webIndex`

  Ruta relativa dentro del archivo phar a ejecutar en caso de acceso desde un navegador

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Genera una excepción PharException al llamar al método

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `webIndex` ahora es nullable.

### Ver también

- Phar::setDefaultStub() - Utilizado para establecer el cargador PHP o el contenedor de carga de un archivo Phar como cargador por defecto

# PharData::setMetadata

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

PharData::setMetadata — Fija las metadatos del archivo

### Descripción

public function PharData::setMetadata(mixed `$metadata`): void

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Phar::setMetadata() debe ser utilizado para almacenar metadatos personalizados que describen algo acerca del archivo phar como entidad completa. PharFileInfo::setMetadata() debe ser utilizado para metadatos específicos de ficheros. Las metadatos pueden degradar el rendimiento de carga de un archivo phar si los datos son demasiado pesados.

Las metadatos pueden ser utilizadas para especificar qué fichero dentro del archivo debe ser utilizado para cargar el archivo o la ubicación de un fichero de manifiesto como el fichero package.xml de » PEAR. En general, cualquier dato útil que describa el archivo phar puede ser almacenado.

### Parámetros

`metadata`

  Cualquier variable PHP que contenga información a almacenar para describir el archivo phar

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Un ejemplo con Phar::setMetadata()

    <?php
    // se asegura de que el phar no exista
    @unlink('nouveauphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/nouveauphar.phar', 0, 'nouveauphar.phar');
        $p['fichier.php'] = '<?php echo "salut"';
        $p->setMetadata(array('chargement' => 'fichier.php'));
        var_dump($p->getMetadata());
    } catch (Exception $e) {
        echo 'No puede crear/modificar el phar:', $e;
    }
    ?>

El ejemplo anterior mostrará:

    array(1) {
      ["chargement"]=>
      string(11) "fichier.php"
    }

### Ver también

- Phar::getMetadata() - Devuelve las metadatos del archivo phar
- Phar::delMetadata() - Elimina los metadatos globales del phar
- Phar::hasMetadata() - Determina si el phar contiene o no metadatos

# PharData::setSignatureAlgorithm

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

PharData::setSignatureAlgorithm — Asigna el algoritmo de firma de un phar y lo aplica

### Descripción

public function PharData::setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void

> Nota: Este método requiere que la variable de configuración INI `phar.readonly` esté definida a `0` para funcionar con los objetos Phar. De lo contrario, se lanzará una excepción PharException.

Asigna el algoritmo de firma de un phar y lo aplica. El algoritmo de firma debe ser `Phar::MD5`, `Phar::SHA1`, `Phar::SHA256`, `Phar::SHA512`, o `Phar::OPENSSL`.

### Parámetros

`algo`

  Un algoritmo entre `Phar::MD5`, `Phar::SHA1`, `Phar::SHA256`, `Phar::SHA512`, o `Phar::OPENSSL`.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

Levanta una excepción UnexpectedValueException para muchos errores, una excepción BadMethodCallException si la llamada se realiza para un archivo phar basado en tar o en zip, una excepción PharException si se encuentran problemas al escribir los cambios en el disco.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `privateKey` ahora es nullable.

### Ver también

- Phar::getSupportedSignatures() - Devuelve un array de los tipos de firma soportados
- Phar::getSignature() - Devuelve la firma MD5/SHA1/SHA256/SHA512 de un archivo Phar

# PharData::setStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setStub — Función inútil (Phar::setStub no es válido para PharData)

### Descripción

public function PharData::setStub(resource|string `$stub`, int `$length` = -1): true

Los archivos tar/zip no ejecutables no pueden tener un contenedor de carga, por lo que este método solo genera una excepción.

### Parámetros

`stub`
  Formalmente, un string o un manejador de flujo abierto para usar como contenedor de carga ejecutable para este archivo phar. Este argumento es ignorado.
`length`
  `stub` en bytes. Este argumento es ignorado.

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

Genera una excepción PharException en cualquier llamada al método

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | El tipo de retorno es ahora `true`, anteriormente era bool.

### Ver también

- Phar::setStub() - Utilizado para especificar el cargador PHP o el contenedor de carga de un archivo Phar

## Tabla de contenidos

- PharData::addEmptyDir — Añade un directorio vacío al archivo tar/zip
- PharData::addFile — Añade un fichero del sistema de archivos al archivo tar/zip
- PharData::addFromString — Añade un fichero a partir de un string al archivo tar/zip
- PharData::buildFromDirectory — Construye un archivo tar/zip a partir de los ficheros de un directorio
- PharData::buildFromIterator — Construye un archivo tar o zip a partir de un iterador
- PharData::compress — Comprime el archivo tar/zip completo utilizando la compresión Gzip o Bzip2
- PharData::compressFiles — Comprime todos los ficheros del archivo tar/zip actual
- PharData::__construct — Construye un objeto de archivo tar o zip no ejecutable
- PharData::convertToData — Convierte un archivo phar en un archivo tar o zip no ejecutable
- PharData::convertToExecutable — Convierte un archivo tar/zip no ejecutable en un archivo phar ejecutable
- PharData::copy — Copia un fichero interno del archivo tar/zip a otro fichero dentro del mismo archivo
- PharData::decompress — Descomprime el archivo Phar completo
- PharData::decompressFiles — Descomprime todos los ficheros del archivo zip actual
- PharData::delMetadata — Elimina los metadatos globales de un archivo zip
- PharData::delete — Elimina un fichero dentro del archivo tar/zip
- PharData::__destruct — Destruye un objeto tar no ejecutable o un archivo zip
- PharData::extractTo — Extrae el contenido de un archivo tar/zip hacia un directorio
- PharData::isWritable — Verifica si el archivo tar/zip puede ser modificado
- PharData::offsetSet — Rellena un fichero dentro del archivo tar/zip con el contenido de un fichero externo o de un string
- PharData::offsetUnset — Elimina un fichero de un archivo tar/zip
- PharData::setAlias — Función inútil (Phar::setAlias no es válido para PharData)
- PharData::setDefaultStub — Función inútil (Phar::setDefaultStub no es válido para PharData)
- PharData::setMetadata — Fija las metadatos del archivo
- PharData::setSignatureAlgorithm — Asigna el algoritmo de firma de un phar y lo aplica
- PharData::setStub — Función inútil (Phar::setStub no es válido para PharData)

# La clase PharFileInfo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

## Introducción

La clase PharFileInfo proporciona una interfaz de alto nivel para acceder al contenido y a los atributos de un fichero contenido en un archivo phar.

## Sinopsis de la Clase

class PharFileInfo extends SplFileInfo {
/* Métodos */
public function __construct(string `$filename`)
public function chmod(int `$perms`): void
public function compress(int `$compression`): true
public function decompress(): true
public function delMetadata(): true
public function getCRC32(): int
public function getCompressedSize(): int
public function getContent(): string
public function getMetadata(array `$unserializeOptions` = []): mixed
public function getPharFlags(): int
public function hasMetadata(): bool
public function isCRCChecked(): bool
public function isCompressed(?int `$compression` = `null`): bool
public function setMetadata(mixed `$metadata`): void
public function __destruct()
/* Métodos heredados */
public function SplFileInfo::getATime(): int|false
public function SplFileInfo::getBasename(string `$suffix` = ""): string
public function SplFileInfo::getCTime(): int|false
public function SplFileInfo::getExtension(): string
public function SplFileInfo::getFileInfo(?string `$class` = `null`): SplFileInfo
public function SplFileInfo::getFilename(): string
public function SplFileInfo::getGroup(): int|false
public function SplFileInfo::getInode(): int|false
public function SplFileInfo::getLinkTarget(): string|false
public function SplFileInfo::getMTime(): int|false
public function SplFileInfo::getOwner(): int|false
public function SplFileInfo::getPath(): string
public function SplFileInfo::getPathInfo(?string `$class` = `null`): ?SplFileInfo
public function SplFileInfo::getPathname(): string
public function SplFileInfo::getPerms(): int|false
public function SplFileInfo::getRealPath(): string|false
public function SplFileInfo::getSize(): int|false
public function SplFileInfo::getType(): string|false
public function SplFileInfo::isDir(): bool
public function SplFileInfo::isExecutable(): bool
public function SplFileInfo::isFile(): bool
public function SplFileInfo::isLink(): bool
public function SplFileInfo::isReadable(): bool
public function SplFileInfo::isWritable(): bool
public function SplFileInfo::openFile(string `$mode` = "r", bool `$useIncludePath` = `false`, ?resource `$context` = `null`): SplFileObject
public function SplFileInfo::setFileClass(string `$class` = `SplFileObject::class`): void
public function SplFileInfo::setInfoClass(string `$class` = `SplFileInfo::class`): void
public function SplFileInfo::__toString(): string
}

# PharFileInfo::chmod

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::chmod — Fija los bits de permiso específicos de los ficheros

### Descripción

public function PharFileInfo::chmod(int `$perms`): void

PharFileInfo::chmod() permite fijar los bits de ejecución de los ficheros, así como los de solo lectura. Los de escritura son ignorados ya que se fijan al inicio por la variable INI phar.readonly. Al igual que con todas las funcionalidades que modifican el contenido de un phar, la variable INI phar.readonly debe estar en off para tener éxito si el fichero se encuentra dentro de un archivo Phar. Los ficheros dentro de un archivo PharData no tienen esta restricción.

### Parámetros

`perms`

  Los permisos (ver chmod())

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Un ejemplo con PharFileInfo::chmod()

    <?php
    // se asegura de que el phar no exista
    @unlink('nouveauphar.phar');
    try {
        $p = new Phar('nouveauphar.phar', 0, 'nouveauphar.phar');
        $p['fichier.sh'] = '#!/usr/local/lib/php
        <?php echo "salut"; ?>';
        // establece el bit de ejecución
        $p['fichier.sh']->chmod(0555);
        var_dump($p['fichier.sh']->isExecutable());
    } catch (Exception $e) {
        echo 'No puede crear/modificar el phar: ', $e;
    }
    ?>

El ejemplo anterior mostrará:

    bool(true)

# PharFileInfo::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharFileInfo::compress — Comprime la entrada Phar actual con una de las compresiones zlib o bzip2

### Descripción

public function PharFileInfo::compress(int `$compression`): true

Este método comprime el fichero dentro del archivo Phar utilizando una de las compresiones bzip2 o zlib. Las extensiones bzip2 o zlib deben estar activadas para aprovechar esta funcionalidad. Además, si el fichero ya está comprimido, la extensión adecuada debe estar activada para descomprimirlo. Al igual que con todas las funcionalidades que modifican el contenido de un phar, la variable INI phar.readonly debe estar a off para tener éxito si el fichero está dentro de un archivo Phar. Los ficheros dentro de archivos PharData no tienen esta restricción.

### Parámetros

`compression`

  La compresión debe ser `Phar::GZ` o `Phar::BZ2`.

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

Levanta una excepción BadMethodCallException si la variable INI phar.readonly está a on, o si la extensión bzip2/zlib no está disponible.

### Ejemplos

Ejemplo #1 Un ejemplo con PharFileInfo::compress()

    <?php
    try {
        $p = new Phar('/ruta/hacia/mifichero.phar', 0, 'mifichero.phar');
        $p['mifichero.txt'] = 'hola';
        $file = $p['mifichero.txt'];
        var_dump($file->isCompressed(Phar::BZ2));
        $p['mifichero.txt']->compress(Phar::BZ2);
        var_dump($file->isCompressed(Phar::BZ2));
    } catch (Exception $e) {
        echo 'No puede crear/modificar mifichero.phar : ', $e;
    }
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(true)

### Ver también

- PharFileInfo::getCompressedSize() - Devuelve el tamaño actual (con compresión) del fichero dentro del archivo Phar
- PharFileInfo::isCompressed() - Indica si la entrada está comprimida
- PharFileInfo::decompress() - Descomprime la entrada Phar actual dentro del phar
- Phar::canCompress() - Determina si la extensión phar soporta la compresión utilizando zip o bzip2
- Phar::isCompressed() - Devuelve Phar::GZ o PHAR::BZ2 si el archivo completo está comprimido (.tar.gz/tar.bz, etc)
- Phar::compressFiles() - Comprime todos los ficheros del archivo Phar actual
- Phar::decompressFiles() - Descomprime todos los ficheros del archivo Phar actual
- Phar::compress() - Comprime el archivo Phar completo utilizando la compresión Gzip o Bzip2
- Phar::decompress() - Descomprime el archivo tar completo
- Phar::getSupportedCompression() - Devuelve un array de los algoritmos de compresión soportados

# PharFileInfo::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::__construct — Construye un objeto de entrada Phar

### Descripción

public function PharFileInfo::__construct(string `$filename`)

Este método no debe ser llamado directamente. En su lugar, un objeto PharFileInfo es inicializado llamando Phar::offsetGet() mediante un acceso de tipo array.

### Parámetros

`filename`

  La URL completa para recuperar un fichero. Si se desea recuperar la información del fichero `mi/fichero.php` del phar `boo.phar`, se deberá especificar `phar://boo.phar/mi/fichero.php`.

### Errores/Excepciones

Genera una excepción BadMethodCallException si __construct() es llamado dos veces. Genera una excepción UnexpectedValueException si la URL del phar solicitado está mal formada, si el phar no puede ser abierto o si el fichero no puede ser encontrado dentro del phar.

### Ejemplos

Ejemplo #1 Ejemplo con PharFileInfo::__construct()

    <?php
    try {
        $p = new Phar('/ruta/hacia/mon.phar', 0, 'mon.phar');
        $p['fichierdetest.txt'] = "hola\nmi\namigo";
        $file = $p['fichierdetest.txt'];
        foreach ($file as $line => $text) {
            echo "línea número $line: $text";
        }
        // esto también funciona
        $file = new PharFileInfo('phar:///ruta/hacia/mon.phar/fichierdetest.txt');
        foreach ($file as $line => $text) {
            echo "línea número $line: $text";
        }
    } catch (Exception $e) {
        echo 'La operación Phar ha fallado: ', $e;
    }
    ?>

El ejemplo anterior mostrará:

    línea número 1: hola
    línea número 2: mi
    línea número 3: amigo
    línea número 1: hola
    línea número 2: mi
    línea número 3: amigo

# PharFileInfo::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharFileInfo::decompress — Descomprime la entrada Phar actual dentro del phar

### Descripción

public function PharFileInfo::decompress(): true

Este método descomprime el fichero dentro del archivo Phar. Según la forma en que el fichero esté comprimido, las extensiones bzip2 o zlib deben estar activadas para aprovechar esta funcionalidad. Al igual que con todas las funcionalidades que modifican el contenido de un phar, la variable INI phar.readonly debe estar a off para tener éxito si el fichero se encuentra en un archivo Phar. Los ficheros dentro de archivos PharData no tienen esta restricción.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

Se genera una excepción BadMethodCallException si la variable INI phar.readonly está a on, o si la extensión bzip2/zlib no está disponible.

### Ejemplos

Ejemplo #1 Ejemplo con PharFileInfo::decompress()

    <?php
    try {
        $p = new Phar('/ruta/hacia/mon.phar', 0, 'mon.phar');
        $p['monfichier.txt'] = 'hola';
        $file = $p['monfichier.txt'];
        $file->compress(Phar::GZ);
        var_dump($file->isCompressed());
        $p['monfichier.txt']->decompress();
        var_dump($file->isCompressed());
    } catch (Exception $e) {
        echo 'No puede crear/modificar mon.phar: ', $e;
    }
    ?>

El ejemplo anterior mostrará:

    int(4096)
    bool(false)

### Ver también

- PharFileInfo::getCompressedSize() - Devuelve el tamaño actual (con compresión) del fichero dentro del archivo Phar
- PharFileInfo::isCompressed() - Indica si la entrada está comprimida
- PharFileInfo::compress() - Comprime la entrada Phar actual con una de las compresiones zlib o bzip2
- Phar::canCompress() - Determina si la extensión phar soporta la compresión utilizando zip o bzip2
- Phar::isCompressed() - Devuelve Phar::GZ o PHAR::BZ2 si el archivo completo está comprimido (.tar.gz/tar.bz, etc)
- Phar::compressFiles() - Comprime todos los ficheros del archivo Phar actual
- Phar::decompressFiles() - Descomprime todos los ficheros del archivo Phar actual
- Phar::compress() - Comprime el archivo Phar completo utilizando la compresión Gzip o Bzip2
- Phar::decompress() - Descomprime el archivo tar completo
- Phar::getSupportedCompression() - Devuelve un array de los algoritmos de compresión soportados

# PharFileInfo::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

PharFileInfo::delMetadata — Elimina las metadatos de la entrada

### Descripción

public function PharFileInfo::delMetadata(): true

Elimina las metadatos de la entrada, si las hay.

### Parámetros

No hay parámetros.

### Valores devueltos

Retorna siempre `true`. Al igual que con todas las funcionalidades que modifican el contenido de un phar, la variable INI phar.readonly debe estar en off para tener éxito si el fichero está dentro de un archivo Phar. Los ficheros dentro de archivos PharData no tienen esta restricción.

### Errores/Excepciones

Genera una excepción PharException si se han encontrado errores al escribir los cambios en el disco, y una excepción BadMethodCallException si el acceso en escritura está desactivado.

### Ejemplos

Ejemplo #1 Un ejemplo con PharFileInfo::delMetaData()

    <?php
    try {
        $a = new Phar('monphar.phar');
        $a['salut'] = 'salut';
        var_dump($a['salut']->delMetadata());
        $a['salut']->setMetadata('mon pote');
        var_dump($a['salut']->delMetadata());
        var_dump($a['salut']->delMetadata());
    } catch (Exception $e) {
        // se manejan los errores
    }
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(true)
    bool(false)

### Ver también

- PharFileInfo::setMetadata() - Establece las metadatos específicas de un fichero
- PharFileInfo::hasMetadata() - Devuelve las metadatos de la entrada
- PharFileInfo::getMetadata() - Devuelve las metadatos específicas adjuntas a un fichero
- Phar::setMetadata() - Establece las metadatos del archivo phar
- Phar::hasMetadata() - Determina si el phar contiene o no metadatos
- Phar::getMetadata() - Devuelve las metadatos del archivo phar

# PharFileInfo::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::__destruct — Destruye un objeto PharFileInfo

### Descripción

public function PharFileInfo::__destruct()

### Parámetros

Esta función no contiene ningún parámetro.

# PharFileInfo::getCRC32

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getCRC32 — Retorna el código CRC32 o levanta una excepción si el CRC no ha sido verificado

### Descripción

public function PharFileInfo::getCRC32(): int

Retorna la suma de verificación crc32() del fichero dentro del archivo Phar.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

La suma de verificación crc32() del fichero dentro del archivo Phar.

### Errores/Excepciones

Levanta una excepción BadMethodCallException si el CRC32 del fichero no ha sido verificado aún. Esto no ocurre normalmente, ya que el CRC es verificado al abrir el fichero en modo lectura o escritura.

### Ejemplos

Ejemplo #1 Ejemplo con PharFileInfo::getCRC32()

    <?php
    try {
        $p = new Phar('/ruta/versus/mon.phar', 0, 'mon.phar');
        $p['monfichier.txt'] = 'salut';
        $file = $p['monfichier.txt'];
        echo $file->getCRC32();
    } catch (Exception $e) {
        echo 'La escritura de mon.phar.phar ha fallado: ', $e;
    }
    ?>

El ejemplo anterior mostrará:

    3633523372

# PharFileInfo::getCompressedSize

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getCompressedSize — Devuelve el tamaño actual (con compresión) del fichero dentro del archivo Phar

### Descripción

public function PharFileInfo::getCompressedSize(): int

Este método devuelve el tamaño del fichero dentro del archivo Phar. Los ficheros no comprimidos devolverán el mismo valor con getCompressedSize que con filesize()

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El tamaño en bytes del fichero dentro del archivo Phar en el disco.

### Ejemplos

Ejemplo #1 Un ejemplo con PharFileInfo::getCompressedSize()

    <?php
    try {
        $p = new Phar('/ruta/hacia/mon.phar', 0, 'mon.phar');
        $p['monfichier.txt'] = 'hola';
        $file = $p['monfichier.txt'];
        echo $file->getCompressedSize();
    } catch (Exception $e) {
        echo 'La escritura de mon.phar ha fallado: ', $e;
    }
    ?>

El ejemplo anterior mostrará:

    2

### Ver también

- PharFileInfo::isCompressed() - Indica si la entrada está comprimida
- PharFileInfo::decompress() - Descomprime la entrada Phar actual dentro del phar
- PharFileInfo::compress() - Comprime la entrada Phar actual con una de las compresiones zlib o bzip2
- Phar::canCompress() - Determina si la extensión phar soporta la compresión utilizando zip o bzip2
- Phar::isCompressed() - Devuelve Phar::GZ o PHAR::BZ2 si el archivo completo está comprimido (.tar.gz/tar.bz, etc)
- Phar::compress() - Comprime el archivo Phar completo utilizando la compresión Gzip o Bzip2
- Phar::decompress() - Descomprime el archivo tar completo
- Phar::getSupportedCompression() - Devuelve un array de los algoritmos de compresión soportados
- Phar::decompressFiles() - Descomprime todos los ficheros del archivo Phar actual
- Phar::compressFiles() - Comprime todos los ficheros del archivo Phar actual

# PharFileInfo::getContent

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

PharFileInfo::getContent — Obtiene el contenido completo del fichero de la entrada

### Descripción

public function PharFileInfo::getContent(): string

Esta función se comporta como file_get_contents() pero para Phar.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el contenido del fichero.

# PharFileInfo::getMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getMetadata — Devuelve las metadatos específicas adjuntas a un fichero

### Descripción

public function PharFileInfo::getMetadata(array `$unserializeOptions` = []): mixed

Devuelve las metadatos que han sido guardadas en el manifiesto del archivo Phar para este fichero.

### Parámetros

### Valores devueltos

Cualquier variable PHP que pueda ser serializada y que se almacena como metadatos para el fichero, o `null` si no se almacenan metadatos.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | El argumento `unserializeOptions` ha sido añadido.

### Ejemplos

Ejemplo #1 Un ejemplo con PharFileInfo::getMetadata()

    <?php
    // se asegura de que el phar no esté ya
    @unlink('nouveauphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/nouveauphar.phar', 0, 'nouveauphar.phar');
        $p['fichier.txt'] = 'salut';
        $p['fichier.txt']->setMetadata(array('utilisateur' => 'PhilDaiguille', 'mime-type' => 'text/plain'));
        var_dump($p['fichier.txt']->getMetadata());
    } catch (Exception $e) {
        echo 'No puede crear/modificar nouveauphar.phar: ', $e;
    }
    ?>

El ejemplo anterior mostrará:

    array(2) {
      ["utilisateur"]=>
      string(7) "PhilDaiguille"
      ["mime-type"]=>
      string(10) "text/plain"
    }

### Ver también

- PharFileInfo::setMetadata() - Establece las metadatos específicas de un fichero
- PharFileInfo::hasMetadata() - Devuelve las metadatos de la entrada
- PharFileInfo::delMetadata() - Elimina las metadatos de la entrada
- Phar::setMetadata() - Establece las metadatos del archivo phar
- Phar::hasMetadata() - Determina si el phar contiene o no metadatos
- Phar::getMetadata() - Devuelve las metadatos del archivo phar

# PharFileInfo::getPharFlags

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getPharFlags — Devuelve los flags del archivo Phar

### Descripción

public function PharFileInfo::getPharFlags(): int

Este método devuelve los flags establecidos en el manifiesto para un Phar. Siempre devolverá `0` en su implementación actual.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Los flags Phar (siempre `0` en su implementación actual)

### Ejemplos

Ejemplo #1 Un ejemplo con PharFileInfo::getPharFlags()

    <?php
    try {
        $p = new Phar('/ruta/versus/mon.phar', 0, 'mon.phar');
        $p['monfichier.txt'] = 'hola';
        $file = $p['monfichier.txt'];
        var_dump($file->getPharFlags());
    } catch (Exception $e) {
        echo 'No puede crear/modificar mon.phar: ', $e;
    }
    ?>

El ejemplo anterior mostrará:

    int(0)

# PharFileInfo::hasMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

PharFileInfo::hasMetadata — Devuelve las metadatos de la entrada

### Descripción

public function PharFileInfo::hasMetadata(): bool

Devuelve las metadatos de un fichero dentro de un archivo Phar.

### Parámetros

No se admiten argumentos.

### Valores devueltos

Devuelve `false` si no hay metadatos presentes o son `null`, `true` si las metadatos no son `null`

### Ver también

- PharFileInfo::setMetadata() - Establece las metadatos específicas de un fichero
- PharFileInfo::getMetadata() - Devuelve las metadatos específicas adjuntas a un fichero
- PharFileInfo::delMetadata() - Elimina las metadatos de la entrada
- Phar::setMetadata() - Establece las metadatos del archivo phar
- Phar::hasMetadata() - Determina si el phar contiene o no metadatos
- Phar::getMetadata() - Devuelve las metadatos del archivo phar

# PharFileInfo::isCRCChecked

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::isCRCChecked — Determina si el fichero tiene un CRC verificado

### Descripción

public function PharFileInfo::isCRCChecked(): bool

Este método determina si un fichero dentro de un archivo Phar tiene un CRC verificado.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

`true` si el fichero tiene un CRC verificado, `false` en caso contrario.

### Ejemplos

Ejemplo #1 Un ejemplo con PharFileInfo::isCRCChecked()

    <?php
    try {
        $p = new Phar('/ruta/al/mon.phar', 0, 'mon.phar');
        $p['monfichier.txt'] = 'hola';
        $file = $p['monfichier.txt'];
        var_dump($file->isCRCChecked());
    } catch (Exception $e) {
        echo 'La creación/modificación de mon.phar ha fallado: ', $e;
    }
    ?>

El ejemplo anterior mostrará:

    bool(true)

# PharFileInfo::isCompressed

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::isCompressed — Indica si la entrada está comprimida

### Descripción

public function PharFileInfo::isCompressed(?int `$compression` = `null`): bool

Este método determina si un fichero dentro de un archivo Phar está comprimido con una de las compresiones Gzip o Bzip2.

### Parámetros

`compression`

  Una de las compresiones `Phar::GZ` o `Phar::BZ2`, sin compresión por omisión.

### Valores devueltos

`true` si el fichero dentro del archivo está comprimido, `false` en caso contrario.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `compression` ahora es nullable.

### Ejemplos

Ejemplo #1 Un ejemplo con PharFileInfo::isCompressed()

    <?php
    try {
        $p = new Phar('/ruta/versus/mon.phar', 0, 'mon.phar');
        $p['monfichier.txt'] = 'salut';
        $p['monfichier2.txt'] = 'salut';
        $p['monfichier2.txt']->setCompressedGZ();
        $file = $p['monfichier.txt'];
        $file2 = $p['monfichier2.txt'];
        var_dump($file->isCompressed());
        var_dump($file2->isCompressed());
    } catch (Exception $e) {
        echo 'La creación/modificación de mon.phar ha fallado: ', $e;
    }
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(true)

### Ver también

- PharFileInfo::getCompressedSize() - Devuelve el tamaño actual (con compresión) del fichero dentro del archivo Phar
- PharFileInfo::decompress() - Descomprime la entrada Phar actual dentro del phar
- PharFileInfo::compress() - Comprime la entrada Phar actual con una de las compresiones zlib o bzip2
- Phar::decompress() - Descomprime el archivo tar completo
- Phar::compress() - Comprime el archivo Phar completo utilizando la compresión Gzip o Bzip2
- Phar::canCompress() - Determina si la extensión phar soporta la compresión utilizando zip o bzip2
- Phar::isCompressed() - Devuelve Phar::GZ o PHAR::BZ2 si el archivo completo está comprimido (.tar.gz/tar.bz, etc)
- Phar::getSupportedCompression() - Devuelve un array de los algoritmos de compresión soportados
- Phar::decompressFiles() - Descomprime todos los ficheros del archivo Phar actual
- Phar::compressFiles() - Comprime todos los ficheros del archivo Phar actual

# PharFileInfo::setMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::setMetadata — Establece las metadatos específicas de un fichero

### Descripción

public function PharFileInfo::setMetadata(mixed `$metadata`): void

PharFileInfo::setMetadata() debe ser utilizada únicamente para almacenar datos personalizados en un fichero que no pueden ser almacenados con las informaciones normalmente almacenadas con el fichero. Las metadatos pueden degradar el rendimiento de carga de un archivo phar si los datos son demasiado pesados o si hay muchos ficheros con metadatos. Es importante señalar que los permisos de ficheros son soportados nativamente en un phar; es posible fijarlos con el método PharFileInfo::chmod(). Al igual que con todas las funcionalidades que modifican el contenido del phar, la variable INI phar.readonly debe estar a off para tener éxito si el fichero está dentro de un archivo Phar. Los ficheros dentro de archivos PharData no tienen esta restricción.

Un uso posible de las metadatos es el paso de un usuario/grupo que debería ser utilizado cuando un fichero es extraído del phar hacia el disco. También puede especificarse un tipo MIME a devolver. En general, puede almacenarse cualquier dato útil que describa un fichero pero que no pueda ser inscrito directamente en él.

### Parámetros

`metadata`

  Cualquier variable PHP que contenga información a almacenar aparte del fichero

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Un ejemplo con PharFileInfo::setMetadata()

    <?php
    // se asegura de que el phar no exista ya
    @unlink('nouveauphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/nouveauphar.phar', 0, 'nouveauphar.phar');
        $p['fichier.txt'] = 'salut';
        $p['fichier.txt']->setMetadata(array('utilisateur' => 'PhilDaiguille', 'mime-type' => 'text/plain'));
        var_dump($p['fichier.txt']->getMetadata());
    } catch (Exception $e) {
        echo 'No puede crear/modificar el phar : ', $e;
    }
    ?>

El ejemplo anterior mostrará:

    array(2) {
      ["utilisateur"]=>
      string(7) "PhilDaiguille"
      ["mime-type"]=>
      string(10) "text/plain"
    }

### Ver también

- PharFileInfo::hasMetadata() - Devuelve las metadatos de la entrada
- PharFileInfo::getMetadata() - Devuelve las metadatos específicas adjuntas a un fichero
- PharFileInfo::delMetadata() - Elimina las metadatos de la entrada
- Phar::setMetadata() - Establece las metadatos del archivo phar
- Phar::hasMetadata() - Determina si el phar contiene o no metadatos
- Phar::getMetadata() - Devuelve las metadatos del archivo phar

## Tabla de contenidos

- PharFileInfo::chmod — Fija los bits de permiso específicos de los ficheros
- PharFileInfo::compress — Comprime la entrada Phar actual con una de las compresiones zlib o bzip2
- PharFileInfo::__construct — Construye un objeto de entrada Phar
- PharFileInfo::decompress — Descomprime la entrada Phar actual dentro del phar
- PharFileInfo::delMetadata — Elimina las metadatos de la entrada
- PharFileInfo::__destruct — Destruye un objeto PharFileInfo
- PharFileInfo::getCRC32 — Retorna el código CRC32 o levanta una excepción si el CRC no ha sido verificado
- PharFileInfo::getCompressedSize — Devuelve el tamaño actual (con compresión) del fichero dentro del archivo Phar
- PharFileInfo::getContent — Obtiene el contenido completo del fichero de la entrada
- PharFileInfo::getMetadata — Devuelve las metadatos específicas adjuntas a un fichero
- PharFileInfo::getPharFlags — Devuelve los flags del archivo Phar
- PharFileInfo::hasMetadata — Devuelve las metadatos de la entrada
- PharFileInfo::isCRCChecked — Determina si el fichero tiene un CRC verificado
- PharFileInfo::isCompressed — Indica si la entrada está comprimida
- PharFileInfo::setMetadata — Establece las metadatos específicas de un fichero

# La clase PharException

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

## Introducción

La clase PharException proporciona una clase de excepción específica para phar para los bloques try/catch.

## Sinopsis de la Clase

class PharException extends Exception {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
  - Tipos de recursos
- Constantes predefinidas
- Utilizar los archivos Phar
  - Utilizar los archivos Phar : Introducción
  - Utilizar los archivos Phar : el flujo phar
  - Utilizar los archivos Phar : las clases Phar y PharData
- Creación de archivos Phar
  - Creación de archivos Phar: Introducción
- ¿Qué hace que un phar sea un phar y no un tar o un zip?
  - Los componentes de todas las archivos Phar, independientemente del formato de archivo
  - El contenedor de archivo Phar
  - Comparación entre Phar, Tar y Zip
  - Los phars basados en Tar
  - Los phars basados en Zip
  - El formato de archivo Phar
  - Flags "bitmapped" globales del Phar
  - Definición de las entradas del manifiesto Phar
  - Formato de firma Phar
- Phar — La clase Phar
  - Phar::addEmptyDir — Añade un directorio vacío al archivo phar
  - Phar::addFile — Añade un fichero del sistema de ficheros al archivo phar
  - Phar::addFromString — Añade un fichero desde un string al archivo phar
  - Phar::apiVersion — Devuelve la versión de la API
  - Phar::buildFromDirectory — Construye un archivo phar a partir de los ficheros de un directorio
  - Phar::buildFromIterator — Construye un archivo phar a partir de un iterador
  - Phar::canCompress — Determina si la extensión phar soporta la compresión utilizando zip o bzip2
  - Phar::canWrite — Determina si la extensión phar soporta la creación y escritura de archivos phar
  - Phar::compress — Comprime el archivo Phar completo utilizando la compresión Gzip o Bzip2
  - Phar::compressFiles — Comprime todos los ficheros del archivo Phar actual
  - Phar::__construct — Construye un objeto de archivo Phar
  - Phar::convertToData — Convierte un archivo phar en un fichero no ejecutable
  - Phar::convertToExecutable — Convierte un archivo phar a otro formato de archivo de archivo phar ejecutable
  - Phar::copy — Copia un fichero perteneciente a un archivo hacia otro fichero del mismo archivo
  - Phar::count — Devuelve el número de entradas (ficheros) en el archivo Phar
  - Phar::createDefaultStub — Crea un contenedor de carga de un archivo Phar
  - Phar::decompress — Descomprime el archivo tar completo
  - Phar::decompressFiles — Descomprime todos los ficheros del archivo Phar actual
  - Phar::delMetadata — Elimina los metadatos globales del phar
  - Phar::delete — Elimina un fichero dentro de un archivo phar
  - Phar::__destruct — Destruye un objeto archivo Phar
  - Phar::extractTo — Extrae el contenido de un archivo phar hacia un directorio
  - Phar::getAlias — Obtiene el alias para Phar
  - Phar::getMetadata — Devuelve las metadatos del archivo phar
  - Phar::getModified — Indica si el archivo phar ha sido modificado
  - Phar::getPath — Obtiene la ruta de acceso absoluta del archivo Phar en el disco
  - Phar::getSignature — Devuelve la firma MD5/SHA1/SHA256/SHA512 de un archivo Phar
  - Phar::getStub — Retorna el cargador PHP o el contenedor de carga de un archivo Phar
  - Phar::getSupportedCompression — Devuelve un array de los algoritmos de compresión soportados
  - Phar::getSupportedSignatures — Devuelve un array de los tipos de firma soportados
  - Phar::getVersion — Devuelve las informaciones de versión del archivo Phar
  - Phar::hasMetadata — Determina si el phar contiene o no metadatos
  - Phar::interceptFileFuncs — Indica a phar que debe interceptar las funciones de archivos
  - Phar::isBuffering — Determina si las operaciones de escritura de Phar están en búfer o se escriben directamente en el disco
  - Phar::isCompressed — Devuelve Phar::GZ o PHAR::BZ2 si el archivo completo está comprimido (.tar.gz/tar.bz, etc)
  - Phar::isFileFormat — Retorna true si el archivo phar está basado en el formato de archivo tar/phar/zip según el argumento
  - Phar::isValidPharFilename — Determina si el nombre de fichero especificado es un nombre de fichero válido para un archivo phar
  - Phar::isWritable — Retorna true si el archivo phar puede ser modificado
  - Phar::loadPhar — Carga cualquier archivo phar con un alias
  - Phar::mapPhar — Lee el phar ejecutado y carga su manifiesto
  - Phar::mount — Monta un camino o un fichero externo a una ubicación virtual dentro del archivo phar
  - Phar::mungServer — Define una lista de un máximo de 4 variables $_SERVER que deben ser modificadas durante la ejecución
  - Phar::offsetExists — Determina si un fichero existe en el phar
  - Phar::offsetGet — Obtiene un objeto PharFileInfo a partir de un fichero
  - Phar::offsetSet — Establece el contenido de un fichero interno en el archivo a partir del contenido de un fichero externo
  - Phar::offsetUnset — Elimina un fichero de un phar
  - Phar::running — Devuelve la ruta completa en el disco o la URL phar completa del archivo phar actualmente ejecutado
  - Phar::setAlias — Establece el alias del archivo Phar
  - Phar::setDefaultStub — Utilizado para establecer el cargador PHP o el contenedor de carga de un archivo Phar como cargador por defecto
  - Phar::setMetadata — Establece las metadatos del archivo phar
  - Phar::setSignatureAlgorithm — Establece y aplica el algoritmo de firma de un phar
  - Phar::setStub — Utilizado para especificar el cargador PHP o el contenedor de carga de un archivo Phar
  - Phar::startBuffering — Inicia el almacenamiento en búfer de escrituras Phar, sin modificar el objeto Phar en el disco
  - Phar::stopBuffering — Detiene el almacenamiento en búfer de las escrituras Phar y provoca la escritura en el disco
  - Phar::unlinkArchive — Elimina completamente un archivo phar del disco y de la memoria
  - Phar::webPhar — Redirige una solicitud desde un navegador web a un fichero interno en el archivo phar
- PharData — La clase PharData
  - PharData::addEmptyDir — Añade un directorio vacío al archivo tar/zip
  - PharData::addFile — Añade un fichero del sistema de archivos al archivo tar/zip
  - PharData::addFromString — Añade un fichero a partir de un string al archivo tar/zip
  - PharData::buildFromDirectory — Construye un archivo tar/zip a partir de los ficheros de un directorio
  - PharData::buildFromIterator — Construye un archivo tar o zip a partir de un iterador
  - PharData::compress — Comprime el archivo tar/zip completo utilizando la compresión Gzip o Bzip2
  - PharData::compressFiles — Comprime todos los ficheros del archivo tar/zip actual
  - PharData::__construct — Construye un objeto de archivo tar o zip no ejecutable
  - PharData::convertToData — Convierte un archivo phar en un archivo tar o zip no ejecutable
  - PharData::convertToExecutable — Convierte un archivo tar/zip no ejecutable en un archivo phar ejecutable
  - PharData::copy — Copia un fichero interno del archivo tar/zip a otro fichero dentro del mismo archivo
  - PharData::decompress — Descomprime el archivo Phar completo
  - PharData::decompressFiles — Descomprime todos los ficheros del archivo zip actual
  - PharData::delMetadata — Elimina los metadatos globales de un archivo zip
  - PharData::delete — Elimina un fichero dentro del archivo tar/zip
  - PharData::__destruct — Destruye un objeto tar no ejecutable o un archivo zip
  - PharData::extractTo — Extrae el contenido de un archivo tar/zip hacia un directorio
  - PharData::isWritable — Verifica si el archivo tar/zip puede ser modificado
  - PharData::offsetSet — Rellena un fichero dentro del archivo tar/zip con el contenido de un fichero externo o de un string
  - PharData::offsetUnset — Elimina un fichero de un archivo tar/zip
  - PharData::setAlias — Función inútil (Phar::setAlias no es válido para PharData)
  - PharData::setDefaultStub — Función inútil (Phar::setDefaultStub no es válido para PharData)
  - PharData::setMetadata — Fija las metadatos del archivo
  - PharData::setSignatureAlgorithm — Asigna el algoritmo de firma de un phar y lo aplica
  - PharData::setStub — Función inútil (Phar::setStub no es válido para PharData)
- PharFileInfo — La clase PharFileInfo
  - PharFileInfo::chmod — Fija los bits de permiso específicos de los ficheros
  - PharFileInfo::compress — Comprime la entrada Phar actual con una de las compresiones zlib o bzip2
  - PharFileInfo::__construct — Construye un objeto de entrada Phar
  - PharFileInfo::decompress — Descomprime la entrada Phar actual dentro del phar
  - PharFileInfo::delMetadata — Elimina las metadatos de la entrada
  - PharFileInfo::__destruct — Destruye un objeto PharFileInfo
  - PharFileInfo::getCRC32 — Retorna el código CRC32 o levanta una excepción si el CRC no ha sido verificado
  - PharFileInfo::getCompressedSize — Devuelve el tamaño actual (con compresión) del fichero dentro del archivo Phar
  - PharFileInfo::getContent — Obtiene el contenido completo del fichero de la entrada
  - PharFileInfo::getMetadata — Devuelve las metadatos específicas adjuntas a un fichero
  - PharFileInfo::getPharFlags — Devuelve los flags del archivo Phar
  - PharFileInfo::hasMetadata — Devuelve las metadatos de la entrada
  - PharFileInfo::isCRCChecked — Determina si el fichero tiene un CRC verificado
  - PharFileInfo::isCompressed — Indica si la entrada está comprimida
  - PharFileInfo::setMetadata — Establece las metadatos específicas de un fichero
- PharException — La clase PharException

# Archivos Rar

# Introducción

Rar es un potente y eficaz archivador creado por Eugene Roshal. Esta extensión proporciona la posibilidad de leer archivos Rar, pero no soporta la escritura de los mismos, ya que no es compatible con la biblioteca UnRar y está directamente prohibido por su licencia.

Se puede encontrar más información sobre Rar y UnRar en » http://www.rarlabs.com/.

# Instalación/Configuración

## Tabla de contenidos

- Instalación
- Tipos de recursos

## Instalación

Rar está actualmente disponible a través de PECL » https://pecl.php.net/package/rar.

Puede utilizarse el asistente de instalación PECL para instalar la extensión Rar, utilizando el siguiente comando: pecl -v install rar.

Asimismo, puede descargarse el paquete tar.gz e instalarse Rar manualmente:

Ejemplo #1 Instalación de Rar

    gunzip rar-xxx.tgz
    tar -xvf rar-xxx.tar
    cd rar-xxx
    phpize
    ./configure && make && make install

Los usuarios de Windows deben activar la biblioteca php_rar.dll en el archivo php.ini para utilizar estas funciones.

## Tipos de recursos

Esta extensión registra 3 clases internas: La representación del archivo retornada por la función rar_open() – RarArchive, la representación de las entradas retornadas por las funciones rar_list() y rar_entry_get() – RarEntry y las excepciones de tipo RarException.

Esta extensión registra también un flujo de recurso llamado "rar" y un gestor de url llamado "rar wrapper", registrado bajo el prefijo "rar".

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`RAR_HOST_MSDOS` (int)
  Use `RarEntry::HOST_MSDOS` en su lugar.
`RAR_HOST_OS2` (int)
  Use `RarEntry::HOST_OS2` en su lugar.
`RAR_HOST_WIN32` (int)
  Use `RarEntry::HOST_WIN32` en su lugar.
`RAR_HOST_UNIX` (int)
  Use `RarEntry::HOST_UNIX` en su lugar.
`RAR_HOST_BEOS` (int)
  Use `RarEntry::HOST_BEOS` en su lugar.

# Ejemplos

Ver también `rar://`.

Ejemplo #1 Descompresión "al vuelo"

    <?php

    if (!array_key_exists("i", $_GET) || !is_numeric($_GET["i"]))
        die("Index unspecified or non-numeric");
    $index = (int) $_GET["i"];

    $arch = RarArchive::open("example.rar");
    if ($arch === FALSE)
        die("Cannot open example.rar");

    $entries = $arch->getEntries();
    if ($entries === FALSE)
        die("Cannot retrieve entries");

    if (!array_key_exists($index, $entries))
        die("No such index: $index");

    $orfilename = $entries[$index]->getName(); //UTF-8 encoded

    $filesize = $entries[$index]->getUnpackedSize();

    /* you could check HTTP_IF_MODIFIED_SINCE here and compare with
     * $entries[$index]->getFileTime(). You could also send a
     * "Last modified" header */

    $fp = $entries[$index]->getStream();
    if ($fp === FALSE)
        die("Cannot open file with index $index insided the archive.");

    $arch->close(); //no longer needed; stream is independent

    function detectUserAgent() {
        if (!array_key_exists('HTTP_USER_AGENT', $_SERVER))
            return "Other";

        $uas = $_SERVER['HTTP_USER_AGENT'];
        if (preg_match("@Opera/@", $uas))
            return "Opera";
        if (preg_match("@Firefox/@", $uas))
            return "Firefox";
        if (preg_match("@Chrome/@", $uas))
            return "Chrome";
        if (preg_match("@MSIE ([0-9.]+);@", $uas, $matches)) {
            if (((float) $matches[1]) >= 7.0)
                return "IE";
        }

        return "Other";
    }

    /*
     * We have 3 options:
     * - For FF and Opera, which support RFC 2231, use that format.
     * - For IE and Chrome, use attwithfnrawpctenclong
     *   (http://greenbytes.de/tech/tc2231/#attwithfnrawpctenclong)
     * - For the others, convert to ISO-8859-1, if possible
     */
    $formatRFC2231 = 'Content-Disposition: attachment; filename*=UTF-8\'\'%s';
    $formatDef = 'Content-Disposition: attachment; filename="%s"';

    switch (detectUserAgent()) {
        case "Opera":
        case "Firefox":
            $orfilename = rawurlencode($orfilename);
            $format = $formatRFC2231;
            break;

        case "IE":
        case "Chrome":
            $orfilename = rawurlencode($orfilename);
            $format = $formatDef;
            break;
        default:
            if (function_exists('iconv'))
                $orfilename =
                    @iconv("UTF-8", "ISO-8859-1//TRANSLIT", $orfilename);
            $format = $formatDef;
    }

    header(sprintf($format, $orfilename));
    //cannot send error messages from now on (headers already sent)

    //replace by real content type, perhaps infering from the file extension
    $contentType = "application/octet-stream";
    header("Content-Type: $contentType");

    header("Content-Transfer-Encoding: binary");

    header("Content-Length: $filesize");

    if ($_SERVER['REQUEST_METHOD'] == "HEAD")
        die();

    while (!feof($fp)) {
        $s = @fread($fp, 8192);
        if ($s === false)
            break; //useless to send error messages

        echo $s;
    }
    ?>

En este ejemplo se obtiene el archivo que contiene el archivo RAR y se ofrece para descargar.

Ejemplo #2 Ejemplo de sistema de extracción de archivos Rar

    <?php

    $rar_file = rar_open('example.rar') or die("Can't open Rar archive");

    $entries = rar_list($rar_file);

    foreach ($entries as $entry) {
        echo 'Filename: ' . $entry->getName() . "\n";
        echo 'Packed size: ' . $entry->getPackedSize() . "\n";
        echo 'Unpacked size: ' . $entry->getUnpackedSize() . "\n";

        $entry->extract('/dir/extract/to/');
    }

    rar_close($rar_file);

    ?>

Este ejemplo extrae cada archivo del archivo Rar en el directorio especificado.

# Funciones Rar

# rar_wrapper_cache_stats

(PECL rar >= 3.0.0)

rar_wrapper_cache_stats — Caché de aciertos y errores del URL wrapper

### Descripción

function rar_wrapper_cache_stats(): string

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

## Tabla de contenidos

- rar_wrapper_cache_stats — Caché de aciertos y errores del URL wrapper

# La clase RarArchive

(PECL rar >= 2.0.0)

## Introducción

Esta clase representa un archivo RAR que puede estar formado por varios volúmenes (partes) y que contiene una serie de entradas RAR (por ejemplo: archivos, directorios y otros objetos especiales, como enlaces simbólicos).

Los objetos de esta clase puede ser atravesado, dando las entradas almacenadas en el archivo RAR respectivamente. Estas entradas también pueden ser obtenidas mediante RarArchive::getEntry() y RarArchive::getEntries().

## Sinopsis de la Clase

final class RarArchive implements Traversable {
/* Métodos */
public function close(): bool
public function getComment(): string
public function getEntries(): array|false
public function getEntry(string `$entryname`): RarEntry|false
public function isBroken(): bool
public function isSolid(): bool
public static function open(string `$filename`, string `$password` = NULL, callable `$volume_callback` = NULL): RarArchive|false
public function setAllowBroken(bool `$allow_broken`): bool
public function __toString(): string
}

# RarArchive::close

# rar_close

(PECL rar >= 2.0.0)

RarArchive::close -- rar_close — Cerrar archivo RAR y liberar todos los recursos

### Descripción

Estilo orientado a objetos (método):

public function RarArchive::close(): bool

Estilo procedimental:

function rar_close(RarArchive `$rarfile`): bool

Cerar archivo RAR y liberar todos los recursos asignados.

### Parámetros

`rarfile`
  Un objeto RarArchive, abierto con rar_open().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL rar 2.0.0 | Las entradas RAR devueltas por RarArchive::getEntry() y RarArchive::getEntries() son ahora invalidadas cuando se llama a este método. Esto significa que todos los métodos de instancia llamados por tales entradas y no garantizan el éxito.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    $rar_arch = RarArchive::open('latest_winrar.rar');
    echo $rar_arch."\n";
    $rar_arch->close();
    echo $rar_arch."\n";
    ?>

Resultado del ejemplo anterior es similar a:

    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar"
    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)

Ejemplo #2 Estilo procedimental

    <?php
    $rar_arch = rar_open('latest_winrar.rar');
    echo $rar_arch."\n";
    rar_close($rar_arch);
    echo $rar_arch."\n";
    ?>

# RarArchive::getComment

# rar_comment_get

(PECL rar >= 2.0.0)

RarArchive::getComment -- rar_comment_get — Obtener comentarios de texto desde el archivo RAR

### Descripción

Estilo orientado a objetos (method):

public function RarArchive::getComment(): string

Estilo procedimental:

function rar_comment_get(RarArchive `$rarfile`): string

Obtener (global) comentario almacenado en el archivo RAR. Este puede ser de hasta 64 KiB de longitud.

> Nota: Esta extensión no es compatible con los comentarios en el nivel de entrada.

### Parámetros

`rarfile`
  Un objeto RarArchive, abierto con rar_open().

### Valores devueltos

Devuelve el comentario o `null` si no hay ninguno.

> Nota: RAR no tiene actualmente soporte para comentarios unicode. La codificación de los resultados de esta función no es especificado, pero esta debe ser probablemente Windows-1252.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    $rar_arch = RarArchive::open('commented.rar');
    echo $rar_arch->getComment();
    ?>

Resultado del ejemplo anterior es similar a:

    This is the comment of the file commented.rar.

Ejemplo #2 Estilo procedimental

    <?php
    $rar_arch = rar_open('commented.rar');
    echo rar_comment_get($rar_arch);
    ?>

# RarArchive::getEntries

# rar_list

(PECL rar >= 2.0.0)

RarArchive::getEntries -- rar_list — Obtener la lista completa de entradas del archivo RAR

### Descripción

Estilo orientado a objetos (método):

public function RarArchive::getEntries(): array|false

Estilo procedimental:

function rar_list(RarArchive `$rarfile`): array|false

Obtener la lista de entradas (archivos y directorios) de el archivo RAR.

> Nota: Si el archivo tiene entradas con el mismo nombre, este método, junto con RarArchive `foreach` iteraciona y otorga un acceso array-like con índices numéricos, únicos para acceder a todas las entradas (por ejemplo, RarArchive::getEntry() y el `rar://` wrapper son insuficientes).

### Parámetros

`rarfile`
  Un objeto RarArchive, abierto con rar_open().

### Valores devueltos

rar_list() devuelve array de objetos RarEntry o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL rar 3.0.0 | Soporte para archivos RAR con nombres entrada repetidos que ya no produce deficiencias.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    $rar_arch = RarArchive::open('solid.rar');
    if ($rar_arch === FALSE)
        die("Could not open RAR archive.");

    $rar_entries = $rar_arch->getEntries();
    if ($rar_entries === FALSE)
        die("Could retrieve entries.");

    echo "Found " . count($rar_entries) . " entries.\n";

    foreach ($rar_entries as $e) {
        echo $e;
        echo "\n";
    }
    $rar_arch->close();
    ?>

Resultado del ejemplo anterior es similar a:

    Found 2 entries.
    RarEntry for file "tese.txt" (23b93a7a)
    RarEntry for file "unrardll.txt" (2ed64b6e)

Ejemplo #2 Estilo procedimental

    <?php
    $rar_arch = rar_open('solid.rar');
    if ($rar_arch === FALSE)
        die("Could not open RAR archive.");

    $rar_entries = rar_list($rar_arch);
    if ($rar_entries === FALSE)
        die("Could not retrieve entries.");

    echo "Found " . count($rar_entries) . " entries.\n";

    foreach ($rar_entries as $e) {
        echo $e;
        echo "\n";
    }
    rar_close($rar_arch);
    ?>

### Ver también

- RarArchive::getEntry() - Obtener el objeto entrada desde el archivo RAR
- `rar://` wrapper

# RarArchive::getEntry

# rar_entry_get

(PECL rar >= 2.0.0)

RarArchive::getEntry -- rar_entry_get — Obtener el objeto entrada desde el archivo RAR

### Descripción

Estilo orientado a objetos (método):

public function RarArchive::getEntry(string `$entryname`): RarEntry|false

Estilo procedimental:

function rar_entry_get(RarArchive `$rarfile`, string `$entryname`): RarEntry|false

Obtener el objeto entrada (archivo o directorio) desde el archivo RAR.

> Nota: También puede obtener objetos de entrada utilizando RarArchive::getEntries(). Tenga en cuenta que un archivo RAR puede tener varias entradas con el mismo nombre; este método recuperará sólo el primero.

### Parámetros

`rarfile`
  Un objeto RarArchive, abierto con rar_open().
`entryname`
  Ruta a la entrada dentro del archivo RAR.

  > Nota: La ruta debe ser la misma devuelta por RarEntry::getName().

### Valores devueltos

Devuelve el objeto RarEntry encontrado o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    $rar_arch = RarArchive::open('solid.rar');
    if ($rar_arch === FALSE)
        die("Could not open RAR archive.");
    $rar_entry = $rar_arch->getEntry('tese.txt');
    if ($rar_entry === FALSE)
        die("Could not get such entry");
    echo get_class($rar_entry)."\n";
    echo $rar_entry;
    $rar_arch->close();
    ?>

Resultado del ejemplo anterior es similar a:

    RarEntry
    RarEntry for file "tese.txt" (23b93a7a)

Ejemplo #2 Estilo procedimental

    <?php
    $rar_arch = rar_open('solid.rar');
    if ($rar_arch === FALSE)
        die("Could not open RAR archive.");
    $rar_entry = rar_entry_get($rar_arch, 'tese.txt');
    if ($rar_entry === FALSE)
        die("Could not get such entry");
    echo get_class($rar_entry)."\n";
    echo $rar_entry;
    rar_close($rar_arch);
    ?>

### Ver también

- RarArchive::getEntries() - Obtener la lista completa de entradas del archivo RAR
- `rar://` wrapper

# RarArchive::isBroken

# rar_broken_is

(PECL rar >= 3.0.0)

RarArchive::isBroken -- rar_broken_is — Comprobar si un archivo está dañado (incompleto)

### Descripción

Estilo orientado a objetos (método):

public function RarArchive::isBroken(): bool

Estilo procedimental:

function rar_broken_is(RarArchive `$rarfile`): bool

Esta función determina si un archivo está incompleto, por ejemplo, Si un volumen no se encuentra o un volumen está truncado.

### Parámetros

`rarfile`
  Un objeto RarArchive, abierto con rar_open().

### Valores devueltos

Devuelve `true` si el archivo está dañado, `false` en caso contrario. Esta función puede también devolver `false` si el archivo pasado fue cerrado. La única manera para poder distinguir aparte ambos casos es habilitando y permitiendo excepciones con RarException::setUsingExceptions(); sin embargo, esto debería ser innecesario, ya que un programa no debe funcionar con archivos cerrados.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    function retnull() { return null; }
    $file = dirname(__FILE__) . "/multi_broken.part1.rar";
    /* El tercer argumento es utilizado para omitir avisos */
    $arch = RarArchive::open($file, null, 'retnull');
    var_dump($arch->isBroken());
    ?>

Resultado del ejemplo anterior es similar a:

    bool(true)

Ejemplo #2 Estilo procedimental

    <?php
    function retnull() { return null; }
    $file = dirname(__FILE__) . "/multi_broken.part1.rar";
    /* El tercer argumento es utilizado para omitir avisos */
    $arch = rar_open($file, null, 'retnull');
    var_dump(rar_broken_is($arch));
    ?>

### Ver también

- RarArchive::setAllowBroken() - Determina si la apertura de archivos dañados se permite

# RarArchive::isSolid

# rar_solid_is

(PECL rar >= 2.0.0)

RarArchive::isSolid -- rar_solid_is — Comprueba si el archivo RAR es sólido

### Descripción

Estilo orientado a objetos (método):

public function RarArchive::isSolid(): bool

Estilo procedimental:

function rar_solid_is(RarArchive `$rarfile`): bool

Comprueba si el archivo RAR es sólido. La extracción individual de ficheros es más lenta en archivos sólidos.

### Parámetros

`rarfile`
  La instancia del RarArchive, abierto con rar_open().

### Valores devueltos

Devuelve `true` si el archivo es sólido, de lo contrario retorna `false`.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    $arch1 = RarArchive::open("store_method.rar");
    $arch2 = RarArchive::open("solid.rar");
    echo "$arch1: " . ($arch1->isSolid()?'yes':'no') ."\n";
    echo "$arch2: " . ($arch2->isSolid()?'yes':'no') . "\n";
    ?>

Resultado del ejemplo anterior es similar a:

    RAR Archive "C:\php_rar\trunk\tests\store_method.rar": no
    RAR Archive "C:\php_rar\trunk\tests\solid.rar": yes

Ejemplo #2 Estilo procedimental

    <?php
    $arch1 = rar_open("store_method.rar");
    $arch2 = rar_open("solid.rar");
    echo "$arch1: " . (rar_solid_is($arch1)?'yes':'no') ."\n";
    echo "$arch2: " . (rar_solid_is($arch2)?'yes':'no') . "\n";
    ?>

# RarArchive::open

# rar_open

(PECL rar >= 2.0.0)

RarArchive::open -- rar_open — Abre un archivo RAR

### Descripción

Estilo orientado a objetos (método):

public static function RarArchive::open(string `$filename`, string `$password` = NULL, callable `$volume_callback` = NULL): RarArchive|false

Estilo procedimental:

function rar_open(string `$filename`, string `$password` = NULL, callable `$volume_callback` = NULL): RarArchive|false

Abre un archivo RAR especificado y devuelve la instancia RarArchive que lo representa.

> Nota: Si el archivo a abrir esta dividido en volúmenes, se deberá pasar la ruta del primer volúmen como parámetro de la función. De lo contrario, no todos los archivos se mostraran.

### Parámetros

`filename`
  Ruta del archivo Rar.
`password`
  Contraseña en texto plano, si fuera necesario descifrar la cabecera del archivo. También se utilizará por defecto si hay archivos encriptados encontrados. Tenga en cuenta que los archivos pueden poseer diferentes contraseñas en cuanto a las cabeceras y entre ellos.
`volume_callback`
  Una función que recibe como parámetro la ruta del volúmen que no fue encontrado y retorna una cadena con la ruta correcta para dicho archivo o `null` si el volúmen no existe o no es conocido. El programador debería asegurar que la función pasada no cause bucles, ya que esta función es llamada repetidas veces si la ruta devuelta en una llamada previa no corresponde con el volúmen solicitado. Especificando este parámetro se omite la notice que se emitiría cuando un volúmen no es encontrado; una implementación que solo devuelva `null` puede, por lo tanto, utilizarce para omitir dichos notices.

Advertencia

En versiones menores a 2.0.0 de PHP, esta función no manejaria rutas relativas correctamente. Use realpath() como una solución.

### Valores devueltos

Devuelve una instancia del RarArchive solicitado o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL rar 3.0.0 | `volume_callback` fue agregada.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    $rar_arch = RarArchive::open('encrypted_headers.rar', 'samplepassword');
    if ($rar_arch === FALSE)
        die("Failed opening file");

    $entries = $rar_arch->getEntries();
    if ($entries === FALSE)
        die("Failed fetching entries");

    echo "Found " . count($entries) . " files.\n";

    if (empty($entries))
        die("No valid entries found.");

    $stream = reset($entries)->getStream();
    if ($stream === FALSE)
        die("Failed opening first file");

    $rar_arch->close();

    echo "Content of first one follows:\n";
    echo stream_get_contents($stream);

    fclose($stream);
    ?>

Resultado del ejemplo anterior es similar a:

    Found 2 files.
    Content of first one follows:
    Encrypted file 1 contents.

Ejemplo #2 Estilo procedimental

    <?php
    $rar_arch = rar_open('encrypted_headers.rar', 'samplepassword');
    if ($rar_arch === FALSE)
        die("Failed opening file");

    $entries = rar_list($rar_arch);
    if ($entries === FALSE)
        die("Failed fetching entries");

    echo "Found " . count($entries) . " files.\n";

    if (empty($entries))
        die("No valid entries found.");

    $stream = reset($entries)->getStream();
    if ($stream === FALSE)
        die("Failed opening first file");

    rar_close($rar_arch);

    echo "Content of first one follows:\n";
    echo stream_get_contents($stream);

    fclose($stream);
    ?>

Ejemplo #3 Volume Callback

    <?php
    /* En este ejemplo, hay un volúmen llamdo multi_broken.part1.rar
     * cuyo próximo volúmen es llamado multi.part2.rar */
    function resolve($vol) {
        if (preg_match('/_broken/', $vol))
            return str_replace('_broken', '', $vol);
        else
            return null;
    }
    $rar_file1 = rar_open(dirname(__FILE__).'/multi_broken.part1.rar', null, 'resolve');
    $entry = $rar_file1->getEntry('file2.txt');
    $entry->extract(null, dirname(__FILE__) . "/temp_file2.txt");
    ?>

### Ver también

- `rar://` wrapper

# RarArchive::setAllowBroken

(PECL rar >= 3.0.0)

RarArchive::setAllowBroken — Determina si la apertura de archivos dañados se permite

### Descripción

Estilo orientado a objetos (method):

public function RarArchive::setAllowBroken(bool `$allow_broken`): bool

Estilo procedimental:

function rar_allow_broken_set(RarArchive `$rarfile`, bool `$allow_broken`): bool

Este método determina si los archivos dañados pueden ser leidos o todas las operaciones que intenten extraer el archivo de las entradas producirán un error. Los archivos rotos son archivos para los cuales ningún error es detectado cuando el archivo es abierto pero un error se produce cuando leemos las entradas.

### Parámetros

`rarfile`
  Un objeto RarArchive, abierto con rar_open().
`allow_broken`
  Determina si se permite la lectura de archivos dañados (`true`) o no (`false`).

### Valores devueltos

Devuelve `true` o `false` si ocurre un error. Sólo se producirá un error si el archivo ya fue cerrado.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    function retnull() { return null; }
    $file = dirname(__FILE__) . "/multi_broken.part1.rar";
    /* El tercer argumento omite el mensaje "volumen no encontrado" */
    $a = RarArchive::open($file, null, 'retnull');
    $a->setAllowBroken(true);
    foreach ($a->getEntries() as $e) {
        echo "$e\n";
    }
    var_dump(count($a));
    ?>

Resultado del ejemplo anterior es similar a:

    RarEntry for file "file1.txt" (52b28202)
    int(1)

Ejemplo #2 Estilo procedimental

    <?php
    function retnull() { return null; }
    $file = dirname(__FILE__) . "/multi_broken.part1.rar";
    /* El tercer argumento omite el mensaje "volumen no encontrado" */
    $a = rar_open($file, null, 'retnull');
    rar_allow_broken_set($a, true);
    foreach (rar_list($a) as $e) {
        echo "$e\n";
    }
    var_dump(count($a));
    ?>

### Ver también

- RarArchive::isBroken() - Comprobar si un archivo está dañado (incompleto)

# RarArchive::__toString

(PECL rar >= 2.0.0)

RarArchive::__toString — Obtener representación de texto

### Descripción

public function RarArchive::__toString(): string

Proporciona una representación de cadena para este objeto RarArchive. Esta actualmente muestra la ruta completa del volumen de archivo que fue abierto y si el recurso es válido o ya estaba cerrado a través de una llamada a RarArchive::close().

Este método debe ser utilizado sólo para propósitos de depuración, ya que no existen garantías en cuanto a la información que contiene el resultado o cómo esta es formateada.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Una representación textual de este objeto RarArchive. El contenido de esta representación no es especificado.

### Ejemplos

Ejemplo #1 Ejemplo de RarArchive::__toString()

    <?php
    $rar_arch = RarArchive::open('latest_winrar.rar');
    echo $rar_arch."\n";
    $rar_arch->close();
    echo $rar_arch."\n";
    ?>

Resultado del ejemplo anterior es similar a:

    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar"
    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)

## Tabla de contenidos

- RarArchive::close — Cerrar archivo RAR y liberar todos los recursos
- RarArchive::getComment — Obtener comentarios de texto desde el archivo RAR
- RarArchive::getEntries — Obtener la lista completa de entradas del archivo RAR
- RarArchive::getEntry — Obtener el objeto entrada desde el archivo RAR
- RarArchive::isBroken — Comprobar si un archivo está dañado (incompleto)
- RarArchive::isSolid — Comprueba si el archivo RAR es sólido
- RarArchive::open — Abre un archivo RAR
- RarArchive::setAllowBroken — Determina si la apertura de archivos dañados se permite
- RarArchive::__toString — Obtener representación de texto

# La clase RarEntry

(PECL rar >= 0.1)

## Introducción

Una entrada RAR, representa un directorio o un archivo comprimido dentro de un archivo RAR.

## Sinopsis de la Clase

final class RarEntry {
/* Constantes */
const int HOST_MSDOS = 0;
const int HOST_OS2 = 1;
const int HOST_WIN32 = 2;
const int HOST_UNIX = 3;
const int HOST_MACOS = 4;
const int HOST_BEOS = 5;
const int ATTRIBUTE_WIN_READONLY = 1;
const int ATTRIBUTE_WIN_HIDDEN = 2;
const int ATTRIBUTE_WIN_SYSTEM = 4;
const int ATTRIBUTE_WIN_DIRECTORY = 16;
const int ATTRIBUTE_WIN_ARCHIVE = 32;
const int ATTRIBUTE_WIN_DEVICE = 64;
const int ATTRIBUTE_WIN_NORMAL = 128;
const int ATTRIBUTE_WIN_TEMPORARY = 256;
const int ATTRIBUTE_WIN_SPARSE_FILE = 512;
const int ATTRIBUTE_WIN_REPARSE_POINT = 1024;
const int ATTRIBUTE_WIN_COMPRESSED = 2048;
const int ATTRIBUTE_WIN_OFFLINE = 4096;
const int ATTRIBUTE_WIN_NOT_CONTENT_INDEXED = 8192;
const int ATTRIBUTE_WIN_ENCRYPTED = 16384;
const int ATTRIBUTE_WIN_VIRTUAL = 65536;
const int ATTRIBUTE_UNIX_WORLD_EXECUTE = 1;
const int ATTRIBUTE_UNIX_WORLD_WRITE = 2;
const int ATTRIBUTE_UNIX_WORLD_READ = 4;
const int ATTRIBUTE_UNIX_GROUP_EXECUTE = 8;
const int ATTRIBUTE_UNIX_GROUP_WRITE = 16;
const int ATTRIBUTE_UNIX_GROUP_READ = 32;
const int ATTRIBUTE_UNIX_OWNER_EXECUTE = 64;
const int ATTRIBUTE_UNIX_OWNER_WRITE = 128;
const int ATTRIBUTE_UNIX_OWNER_READ = 256;
const int ATTRIBUTE_UNIX_STICKY = 512;
const int ATTRIBUTE_UNIX_SETGID = 1024;
const int ATTRIBUTE_UNIX_SETUID = 2048;
const int ATTRIBUTE_UNIX_FINAL_QUARTET = 61440;
const int ATTRIBUTE_UNIX_FIFO = 4096;
const int ATTRIBUTE_UNIX_CHAR_DEV = 8192;
const int ATTRIBUTE_UNIX_DIRECTORY = 16384;
const int ATTRIBUTE_UNIX_BLOCK_DEV = 24576;
const int ATTRIBUTE_UNIX_REGULAR_FILE = 32768;
const int ATTRIBUTE_UNIX_SYM_LINK = 40960;
const int ATTRIBUTE_UNIX_SOCKET = 49152;
/* Métodos */
public function extract(
string `$dir`,
string `$filepath` = "",
string `$password` = NULL,
bool `$extended_data` = `false`
): bool
public function getAttr(): int
public function getCrc(): string
public function getFileTime(): string
public function getHostOs(): int
public function getMethod(): int
public function getName(): string
public function getPackedSize(): int
public function getStream(string `$password` = ?): resource|false
public function getUnpackedSize(): int
public function getVersion(): int
public function isDirectory(): bool
public function isEncrypted(): bool
public function __toString(): string
}

## Constantes predefinidas

`RarEntry::HOST_MSDOS`
  Si el valor devuelto por RarEntry::getHostOs() es igual a esta constante, MS-DOS fue utilizado para añadir esta entrada. Utilizar en lugar de `RAR_HOST_MSDOS`.
`RarEntry::HOST_OS2`
  Si el valor devuelto por RarEntry::getHostOs() es igual a esta constante, OS/2 fue utilizado para añadir esta entrada. Destinado para sustituir a `RAR_HOST_OS2`.
`RarEntry::HOST_WIN32`
  Si el valor devuelto por RarEntry::getHostOs() es igual a esta constante, Microsoft Windows fue utilizado para añadir esta entrada. Destinado para sustituir a `RAR_HOST_WIN32`.
`RarEntry::HOST_UNIX`
  Si el valor devuelto por RarEntry::getHostOs() es igual a esta constante, un Sistema Operativo UNIX no especificado fue utilizado para añadir esta entrada. Destinado para sustituir a `RAR_HOST_UNIX`.
`RarEntry::HOST_MACOS`
  Si el valor devuelto por RarEntry::getHostOs() es igual a esta constante, un Sistema Operativo Mac fue utilizado para añadir esta entrada.
`RarEntry::HOST_BEOS`
  Si el valor devuelto por RarEntry::getHostOs() es igual a esta constante, un Sistema Operativo BeOS fue utilizado para añadir esta entrada. Destinado para sustituir a `RAR_HOST_BEOS`.
`RarEntry::ATTRIBUTE_WIN_READONLY`
  Bit que representa una entrada de Windows con un atributo de sólo lectura. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_HIDDEN`
  Bit que representa una entrada de Windows con un atributo oculto. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_SYSTEM`
  Bits que representa una entrada de Windows con un atributo del sistema. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_DIRECTORY`
  Bit que representa una entrada de Windows con un atributo de directorio (entrada es un directorio). Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es Microsoft Windows. Véase también RarEntry::isDirectory(), que también trabaja con entradas que no fueron añadidas en WinRAR.
`RarEntry::ATTRIBUTE_WIN_ARCHIVE`
  Bit que representa una entrada de Windows con un atributo de archivo. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_DEVICE`
  Bit que representa una entrada de Windows con un atributo de dispositivo. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_NORMAL`
  Bit que representa una entrada de Windows con un atributo de archivo normal (entrada NO es un directorio). Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es Microsoft Windows. Véase también RarEntry::isDirectory(), que también trabaja con entradas que no fueron añadidas en WinRAR.
`RarEntry::ATTRIBUTE_WIN_TEMPORARY`
  Bit que representa una entrada de Windows con un atributo temporal. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_SPARSE_FILE`
  Bit que representa una entrada de Windows con un atributo de archivo disperso (archivo es un archivo disperso NTFS). Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_REPARSE_POINT`
  Bit que representa una entrada de Windows con un atributo punto de re-análisis (entrada es un punto de re-análisis NTFS, por ejemplo, un directorio enlace o un sistema de montaje de archivos). Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_COMPRESSED`
  Bit que representa una entrada de Windows con un atributo comprimido (sólo NTFS). Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_OFFLINE`
  Bit que representa una entrada de Windows con un atributo fuera de línea (entrada es desconectada y no accesible). Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_NOT_CONTENT_INDEXED`
  Bit que representa una entrada de Windows con un atributo de contenido no indexado (entrada deberá ser indexada). Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_ENCRYPTED`
  Bit que representa una entrada de Windows con un atributo cifrado (sólo NTFS). Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_VIRTUAL`
  Bit que representa una entrada de Windows con un atributo virtual. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
`RarEntry::ATTRIBUTE_UNIX_WORLD_EXECUTE`
  Bit que representa una entrada que es ejecutable en el mundo UNIX. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es UNIX.
`RarEntry::ATTRIBUTE_UNIX_WORLD_WRITE`
  Bit que representa una entrada que es escribible en el mundo UNIX. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es UNIX.
`RarEntry::ATTRIBUTE_UNIX_WORLD_READ`
  Bit que representa una entrada que es leible en el mundo UNIX. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es UNIX.
`RarEntry::ATTRIBUTE_UNIX_GROUP_EXECUTE`
  Bit que representa una entrada UNIX que es grupo ejecutable. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es UNIX.
`RarEntry::ATTRIBUTE_UNIX_GROUP_WRITE`
  Bit que representa una entrada UNIX que es grupo escribible. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es UNIX.
`RarEntry::ATTRIBUTE_UNIX_GROUP_READ`
  Bit que representa una entrada UNIX que es grupo leible. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es UNIX.
`RarEntry::ATTRIBUTE_UNIX_OWNER_EXECUTE`
  Bit que representa una entrada UNIX que es propietario ejecutable. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es UNIX.
`RarEntry::ATTRIBUTE_UNIX_OWNER_WRITE`
  Bit que representa una entrada UNIX que es propietario escribible. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es UNIX.
`RarEntry::ATTRIBUTE_UNIX_OWNER_READ`
  Bit que representa una entrada UNIX que es propietario leible. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es UNIX.
`RarEntry::ATTRIBUTE_UNIX_STICKY`
  Bit que representa el sticky bit UNIX. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es UNIX.
`RarEntry::ATTRIBUTE_UNIX_SETGID`
  Bit que representa el atributo UNIX setgid. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es UNIX.
`RarEntry::ATTRIBUTE_UNIX_SETUID`
  Bit que representa el atributo UNIX setuid. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es UNIX.
`RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`
  Máscara para aislar a los últimos cuatro bits (nibble) de atributos UNIX (_S_IFMT, el tipo de máscara de archivo). Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es UNIX y con las constantes `RarEntry::ATTRIBUTE_UNIX_FIFO`, `RarEntry::ATTRIBUTE_UNIX_CHAR_DEV`, `RarEntry::ATTRIBUTE_UNIX_DIRECTORY`, `RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV`, `RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE`, `RarEntry::ATTRIBUTE_UNIX_SYM_LINK` and `RarEntry::ATTRIBUTE_UNIX_SOCKET`.
`RarEntry::ATTRIBUTE_UNIX_FIFO`
  FIFOs Unix tendrá atributos cuyos últimos cuatro bits tienen este valor. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es UNIX y con la constante `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.
`RarEntry::ATTRIBUTE_UNIX_CHAR_DEV`
  Dispositivo de tipo carácter Unix tendrá atributos cuyos últimos cuatro bits tienen este valor. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es UNIX y con la constante `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.
`RarEntry::ATTRIBUTE_UNIX_DIRECTORY`
  Directorios Unix tendrá atributos cuyos últimos cuatro bits tienen este valor. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es UNIX y con la constante `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`. Véase también RarEntry::isDirectory(), que también trabaja con entradas que fueron añadidas en otros sistemas operativos.
`RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV`
  Dispositivo de tipo bloque Unix tendrá atributos cuyos últimos cuatro bits tienen este valor. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es UNIX y con la constante `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.
`RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE`
  Archivos regular Unix (no directorios) tendrá atributos cuyos últimos cuatro bits tienen este valor. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es UNIX y con la constante `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`. Véase también RarEntry::isDirectory(), ue también trabaja con entradas que fueron añadidas en otros sistemas operativos.
`RarEntry::ATTRIBUTE_UNIX_SYM_LINK`
  Enlace simbólico Unix tendrá atributos cuyos últimos cuatro bits tienen este valor. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es UNIX y con la constante `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.
`RarEntry::ATTRIBUTE_UNIX_SOCKET`
  Sockets Unix will tendrá atributos cuyos últimos cuatro bits tienen este valor. Para ser utilizado con RarEntry::getAttr() en entradas cuyo sistema operativo anfitrión es UNIX y con la constante `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.

# RarEntry::extract

(PECL rar >= 0.1)

RarEntry::extract — Extraer entrada del archivo

### Descripción

public function RarEntry::extract(
string `$dir`,
string `$filepath` = "",
string `$password` = NULL,
bool `$extended_data` = `false`
): bool

RarEntry::extract() extrae los datos de entrada. Esto creará un nuevo archivo en el `dir` especificado con el mismo nombre que el nombre de la entrada, a menos que el segundo argumento sea especificado. Siga leyendo más abajo para obtener mayor información.

### Parámetros

`dir`
  Ruta al directorio donde los archivos deben ser extraídos. Este parámetro es considerado si y sólo si no es `filepath`. Si ambos parámetros están vacíos se intentará una extracción en el directorio actual.
`filepath`
  Ruta (relativa o absoluta) que contiene el directorio y el nombre del archivo extraído. Este parámetro anula los parámetros `dir` y el nombre del archivo original.
`password`
  La contraseña utilizada para cifrar esta entrada. Si la entrada no está cifrada, este valor no se utilizará y puede ser omitido. Si se omite este parámetro y la entrada está cifrada, la contraseña dada a rar_open(), será utlizada. Si una contraseña incorrecta es dada, de forma explicita o implicita via rar_open(), la comprobación CRC fallará y este método fallará y devolverá `false`. Si no se da la contraseña y se requiere una, este método fallará y devolverá `false`. Puede comprobar si una entrada está cifrada con RarEntry::isEncrypted().
`extended_data`
  Si `true`, información extendida tales como NTFS ACLs e información propietaria Unix será establecida en los archivos extraidos, siempre que esta esté presente en el archivo.

Advertencia

Antes de la versión 2.0.0, esta función no manejaba las rutas relativas correctamente. Utilice realpath() como una solución.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL rar 3.0.0 | `extended_data` fue añadido.
PECL rar 3.0.0 | Soporte para archivos RAR con nombres de entrada que se repiten ya no es defectuoso

### Ejemplos

Ejemplo #1 Ejemplo de RarEntry::extract()

    <?php

    $rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

    $entry->extract('/dir/to'); // crear /dir/to/Dir/file.txt
    $entry->extract(false, '/dir/to/new_name.txt'); // crear /dir/to/new_name.txt

    ?>

Ejemplo #2 ¿Cómo extraer todos los archivos en archivo?:

    <?php

    /* ejemplo por Erik Jenssen también conocido como erix */

    $filename = "foobar.rar";
    $filepath = "/home/foo/bar/";

    $rar_file = rar_open($filepath.$filename);
    $list = rar_list($rar_file);
    foreach($list as $file) {
        $entry = rar_entry_get($rar_file, $file);
        $entry->extract("."); // extraer el directorio actual
    }
    rar_close($rar_file);

    ?>

### Ver también

- RarEntry::getStream() - Obtener manejador de archivo para entrada
- `rar://` wrapper

# RarEntry::getAttr

(PECL rar >= 0.1)

RarEntry::getAttr — Obtener los atributos de la entrada

### Descripción

public function RarEntry::getAttr(): int

Devuelve los atributos dependientes del SO del archivo de entrada.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve los atributos o `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo de RarEntry::getAttr()

    <?php

    $rar_file = rar_open('example.rar') or die("Can't open Rar archive");

    $entry = rar_entry_get($rar_file, 'dir/in/the/archive') or die("Can't find such entry");

    $host_os = $entry->getHostOs();
    $attr = $entry->getAttr();

    switch($host_os) {
        case RAR_HOST_MSDOS:
        case RAR_HOST_OS2:
        case RAR_HOST_WIN32:
        case RAR_HOST_MACOS:
            printf("%c%c%c%c%c%c\n",
                    ($attr & 0x08) ? 'V' : '.',
                    ($attr & 0x10) ? 'D' : '.',
                    ($attr & 0x01) ? 'R' : '.',
                    ($attr & 0x02) ? 'H' : '.',
                    ($attr & 0x04) ? 'S' : '.',
                    ($attr & 0x20) ? 'A' : '.');
            break;
        case RAR_HOST_UNIX:
        case RAR_HOST_BEOS:
            switch ($attr & 0xF000)
            {
                case 0x4000:
                    printf("d");
                    break;
                case 0xA000:
                    printf("l");
                    break;
                default:
                    printf("-");
                    break;
            }
            printf("%c%c%c%c%c%c%c%c%c\n",
                    ($attr & 0x0100) ? 'r' : '-',
                    ($attr & 0x0080) ? 'w' : '-',
                    ($attr & 0x0040) ? (($attr & 0x0800) ? 's':'x'):(($attr & 0x0800) ? 'S':'-'),
                    ($attr & 0x0020) ? 'r' : '-',
                    ($attr & 0x0010) ? 'w' : '-',
                    ($attr & 0x0008) ? (($attr & 0x0400) ? 's':'x'):(($attr & 0x0400) ? 'S':'-'),
                    ($attr & 0x0004) ? 'r' : '-',
                    ($attr & 0x0002) ? 'w' : '-',
                    ($attr & 0x0001) ? 'x' : '-');
            break;
    }

    rar_close($rar_file);

    ?>

### Ver también

- RarEntry::getHostOs() - Obtener sistema operativo anfitrión del archivo de entrada
- Las constantes de RarEntry

# RarEntry::getCrc

(PECL rar >= 0.1)

RarEntry::getCrc — Obtener el CRC de la entrada

### Descripción

public function RarEntry::getCrc(): string

Devuelve una cadena hexadecimal representación de el CRC del archivo de entrada.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el CRC del archivo de entrada o `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL rar 2.0.0 | Este método devuelve ahora valores correctos para archivos de varios volúmenes.

# RarEntry::getFileTime

(PECL rar >= 0.1)

RarEntry::getFileTime — Devolver entrada última fecha de modificación

### Descripción

public function RarEntry::getFileTime(): string

Devuelve entrada última fecha modificación.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve entrada última fecha de modificación como una cadena en formato `YYYY-MM-DD HH:II:SS`, o `false` en caso de error.

# RarEntry::getHostOs

(PECL rar >= 0.1)

RarEntry::getHostOs — Obtener sistema operativo anfitrión del archivo de entrada

### Descripción

public function RarEntry::getHostOs(): int

Devuelve el código del sistema operativo anfitrión del archivo de entrada.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el código del sistema operativo anfitrión, o `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo de RarEntry::getHostOs() (version >= 2.0.0)

    <?php

    $rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

    switch ($entry->getHostOs()) {
        case RarEntry::HOST_MSDOS:
            echo "MS-DOS\n";
            break;
        case RarEntry::HOST_OS2:
            echo "OS2\n";
            break;
        case RarEntry::HOST_WIN32:
            echo "Win32\n";
            break;
        case RarEntry::HOST_MACOS:
            echo "MacOS\n";
            break;
        case RarEntry::HOST_UNIX:
            echo "Unix/Linux\n";
            break;
        case RarEntry::HOST_BEOS:
            echo "BeOS\n";
            break;
    }

    ?>

Ejemplo #2 RarEntry::getHostOs() example (version <= 1.0.0)

    <?php

    $rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

    switch ($entry->getHostOs()) {
        case RAR_HOST_MSDOS:
            echo "MS-DOS\n";
            break;
        case RAR_HOST_OS2:
            echo "OS2\n";
            break;
        case RAR_HOST_WIN32:
            echo "Win32\n";
            break;
        case RAR_HOST_MACOS:
            echo "MacOS\n";
            break;
        case RAR_HOST_UNIX:
            echo "Unix/Linux\n";
            break;
        case RAR_HOST_BEOS:
            echo "BeOS\n";
            break;
    }

    ?>

### Ver también

- RarEntry::extract() - Extraer entrada del archivo

# RarEntry::getMethod

(PECL rar >= 0.1)

RarEntry::getMethod — Obtener método pack de la entrada

### Descripción

public function RarEntry::getMethod(): int

RarEntry::getMethod() devuelve el número del método utilizado cuando añadimos archivo actual de entrada.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de método o `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo de RarEntry::getMethod()

    <?php

    $rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

    echo "Method number: " . $entry->getMethod();

    ?>

# RarEntry::getName

(PECL rar >= 0.1)

RarEntry::getName — Obtener el nombre de la entrada

### Descripción

public function RarEntry::getName(): string

Devuelve el nombre (con la ruta) de el archivo entrada.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el nombre de la entrada como una cadena, o `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL rar 2.0.0 | Desde la versión 2.0.0, la cadena devuelta está codificada en Unicode/UTF-8.

### Ejemplos

Ejemplo #1 Ejemplo de RarEntry::getName()

    <?php

    //este ejemplo, es seguro, incluso en páginas no codificados en UTF-8
    //para esa codificación en UTF-8, la llamada a mb_convert_encoding es innecesaria.

    $rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

    echo "Entry name: " . mb_convert_encoding(
        htmlentities(
            $entry->getName(),
            ENT_COMPAT,
            "UTF-8"
        ),
        "HTML-ENTITIES",
        "UTF-8"
    );

    ?>

# RarEntry::getPackedSize

(PECL rar >= 0.1)

RarEntry::getPackedSize — Obtiene el tamaño empaquetado de la entrada

### Descripción

public function RarEntry::getPackedSize(): int

Obtiene el tamaño empaquetado del archivo entrada.

> Nota: Tenga en cuenta que en las plataformas de 32 bits de longitud (que incluye Windows x64), el tamaño máximo devuelto está limitado a 2 GB. Compruebe la constante `PHP_INT_MAX`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el tamaño empaquetado, o `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL rar 2.0.0 | Este método devuelve ahora los valores correctos de empaquetado mayores a 2 GB en plataformas de 64-bit ints y nunca devuelve valores negativos en otras plataformas.

### Ejemplos

Ejemplo #1 Ejemplo de RarEntry::getPackedSize()

    <?php

    $rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

    echo "Packed size of " . $entry->getName() . " = " . $entry->getPackedSize() . " bytes";

    ?>

# RarEntry::getStream

(PECL rar >= 2.0.0)

RarEntry::getStream — Obtener manejador de archivo para entrada

### Descripción

public function RarEntry::getStream(string `$password` = ?): resource|false

Devuelve un manejador de archivo que soporta operaciones de lectura. Este manejador proporciona descompresión al vuelo para esta entrada.

El manejador no es invalidado por llamar a rar_close().

Advertencia

El flujo resultante no tiene verificación de integridad. En particular, archivo corrupto y descifrado con una clave errónea, no será detectado. Es responsabilidad del programador utilizar la entrada CRC para comprobar la integridad, si así lo desea.

### Parámetros

`password`
  La contraseña utilizada para cifrar esta entrada. Si la entrada no está cifrada, este valor no se utilizará y puede ser omitido. Si el parámetro es omitido y la entrada está cifrada, la contraseña dada a rar_open(), será utilizada. Si una contraseña incorrecta es dada, ya sea explícita o implícitamente via rar_open(), teste método resultante de flujo producirá error de salida. Si no se especifica la contraseña y se requiere una, este método fallará y devolverá `false`. Puede comprobar si una entrada está cifrada con RarEntry::isEncrypted().

### Valores devueltos

El manejador de archivo o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL rar 3.0.0 | Soporte para archivos RAR con nombres de entrada que se repiten ya no es defectuoso.

### Ejemplos

Ejemplo #1 Ejemplo de RarEntry::getStream()

    <?php

    $rar_file = rar_open('example.rar');
    if ($rar_file === false)
        die("Failed to open Rar archive");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt');
    if ($entry === false)
        die("Failed to find such entry");

    $stream = $entry->getStream();
    if ($stream === false)
        die("Failed to obtain stream.");

    rar_close($rar_file); //flujo es independiente de archivo

    while (!feof($stream)) {
        $buff = fread($stream, 8192);
        if ($buff !== false)
            echo $buff;
        else
            break; //error fread
    }

    fclose($stream);

    ?>

### Ver también

- RarEntry::extract() - Extraer entrada del archivo
- `rar://` wrapper

# RarEntry::getUnpackedSize

(PECL rar >= 0.1)

RarEntry::getUnpackedSize — Obtener el tamaño descomprimido de la entrada

### Descripción

public function RarEntry::getUnpackedSize(): int

Obtiene el tamaño descomprimido del archivo entrada.

> Nota: Tenga en cuenta que en las plataformas de 32 bits de longitud (que incluye Windows x64), el tamaño máximo devueltos está limitado a 2 GB. Compruebe la constante `PHP_INT_MAX`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el tamaño descomprimido, o `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL rar 2.0.0 | Este método devuelve ahora valores correctos de tamaño descomprimido superiores a 2 GB en plataformas con 64-bit ints y nunca devuelve valores negativos en otras plataformas.

### Valores devueltos

Ejemplo #1 Ejemplo de RarEntry::getUnpackedSize()

    <?php

    $rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

    echo "Unpacked size of " . $entry->getName() . " = " . $entry->getUnpackedSize() . " bytes";

    ?>

# RarEntry::getVersion

(PECL rar >= 0.1)

RarEntry::getVersion — Obtener la versión mínima del programa RAR requerida para desempaquetar la entrada

### Descripción

public function RarEntry::getVersion(): int

Devuelve la versión mínima del programa RAR (por ejemplo WinRAR) requerida para desempaquetar la entrada. Esta es codificada como 10 * version mayor + versión menor.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la versión o `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo de RarEntry::getVersion()

    <?php

    $rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

    echo "Rar version required for unpacking: " . $entry->getVersion();

    ?>

# RarEntry::isDirectory

(PECL rar >= 2.0.0)

RarEntry::isDirectory — Comprobar si una entrada representa un directorio

### Descripción

public function RarEntry::isDirectory(): bool

Comprueba si una entrada representa un directorio.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si la entrada es un directorio y `false` en caso contrario.

### Notas

Esta función sólo está disponible desde la versión 2.0.0, pero también puede comprobarse si una entrada es un directorio mediante la comprobación de los atributos de entrada, así (sólo funciona para los archivos comprimidos en RAR por Windows o Unix):

    <?php
    //...
    //Abrir archivo, obtener la entrada y almacenarla en la variable $e...
    //...

    $isDirectory = (bool) ((($e->getHostOs() == RAR_HOST_WIN32) && ($e->getAttr() & 0x10)) ||
        (($e->getHostOs() == RAR_HOST_UNIX) && (($e->getAttr() & 0xf000) == 0x4000)));
    ?>

# RarEntry::isEncrypted

(PECL rar >= 2.0.0)

RarEntry::isEncrypted — Comprobar si una entrada está cifrada

### Descripción

public function RarEntry::isEncrypted(): bool

Comprueba si el contenido de la entrada actual está cifrado.

> Nota: La contraseña utilizada puede variar entre los archivos dentro del mismo archivo RAR.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si la entrada actual se encuentra cifrada y `false` en caso contrario.

# RarEntry::__toString

(PECL rar >= 2.0.0)

RarEntry::__toString — Obtener texto representación de entrada

### Descripción

public function RarEntry::__toString(): string

RarEntry::__toString() devuelve una representación textual de esta entrada. Esta incluye si la entrada es un archivo o un directorio (enlaces simbólicos y otros objetos especiales serán tratados como archivos), el nombre UTF-8 de la entrada y su CRC. La forma y el contenido de esta representación puede cambiar en el futuro, así que no son fiables.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Una representación textual de la entrada.

## Tabla de contenidos

- RarEntry::extract — Extraer entrada del archivo
- RarEntry::getAttr — Obtener los atributos de la entrada
- RarEntry::getCrc — Obtener el CRC de la entrada
- RarEntry::getFileTime — Devolver entrada última fecha de modificación
- RarEntry::getHostOs — Obtener sistema operativo anfitrión del archivo de entrada
- RarEntry::getMethod — Obtener método pack de la entrada
- RarEntry::getName — Obtener el nombre de la entrada
- RarEntry::getPackedSize — Obtiene el tamaño empaquetado de la entrada
- RarEntry::getStream — Obtener manejador de archivo para entrada
- RarEntry::getUnpackedSize — Obtener el tamaño descomprimido de la entrada
- RarEntry::getVersion — Obtener la versión mínima del programa RAR requerida para desempaquetar la entrada
- RarEntry::isDirectory — Comprobar si una entrada representa un directorio
- RarEntry::isEncrypted — Comprobar si una entrada está cifrada
- RarEntry::__toString — Obtener texto representación de entrada

# La clase RarException

(PECL rar >= 2.0.0)

## Introducción

Esta clase sirve para dos propósitos: estas son el tipo de las excepciones lanzadas por la extensión RAR funciones y métodos y esto permite, a través de métodos estáticos consultar y definir el error y el comportamiento de la extensión, por ejemplo, si las excepciones son lanzadas o solamente se emiten advertencias.

Los códigos de error que se utilizan los siguientes:

- -1 - error fuera de biblioteca UnRAR
- 11 - memoria insuficiente
- 12 - datos dañados
- 13 - archivo dañado
- 14 - formato desconocido
- 15 - error de apertura de archivo
- 16 - error al crear archivo
- 17 - error al cerrar archivo
- 18 - error de lectura
- 19 - error de escritura
- 20 - búfer demasiado pequeño
- 21 - error RAR desconocido
- 22 - contraseña requerida pero no especificada

## Sinopsis de la Clase

final class RarException extends Exception {
/* Métodos */
public static function isUsingExceptions(): bool
public static function setUsingExceptions(bool `$using_exceptions`): void
/* Métodos heredados */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# RarException::isUsingExceptions

(PECL rar >= 2.0.0)

RarException::isUsingExceptions — Comprobar si el manejador de errores con excepciones está en uso

### Descripción

public static function RarException::isUsingExceptions(): bool

Comprueba si las funciones RAR emitirán avisos y devolverán valores de error o si ellas lanzarán excepciones en la mayoría de las circunstancias (no incluye algunos errores de programación tales como pasar el tipo incorrecto de argumento).

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si las excepciones estan siendo utilizadas, `false` en caso contrario.

### Ejemplos

Ejemplo #1 Ejemplo de RarException::isUsingExceptions()

    <?php
    //El valor predeterminado es no usar excepciones
    var_dump(RarException::isUsingExceptions());
    ?>

Resultado del ejemplo anterior es similar a:

    bool(false)

### Ver también

- RarException::setUsingExceptions() - Activar y desactivar el manejador de errores con excepciones

# RarException::setUsingExceptions

(PECL rar >= 2.0.0)

RarException::setUsingExceptions — Activar y desactivar el manejador de errores con excepciones

### Descripción

public static function RarException::setUsingExceptions(bool `$using_exceptions`): void

Si y sólo si el argumento es `true`, entonces, en lugar de emitir advertencias y devolver un valor especial indicando error cuando la biblioteca UnRAR encuentre un error, una excepción de tipo RarException será lanzada.

Las excepciones también será lanzado para los siguientes errores, que se producen fuera de la biblioteca (su código de error será -1):

- intentar algunas operaciones en un objeto RarArchive cerrado o un objeto RarEntry relativo al primero;
- intentar obtener una entrada que no existe con RarArchive::getEntry().

### Parámetros

`using_exceptions`
  Debe ser `true` para activar lanzamiento de excepciones, `false` para descativarlo (el valor por defecto).

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo de RarException::setUsingExceptions()

    <?php
    var_dump(RarException::isUsingExceptions());
    $arch = RarArchive::open("does_not_exist.rar");
    var_dump($arch);

    RarException::setUsingExceptions(true);
    var_dump(RarException::isUsingExceptions());
    $arch = RarArchive::open("does_not_exist.rar");
    var_dump($arch); //not reached
    ?>

Resultado del ejemplo anterior es similar a:

    bool(false)

    Warning: RarArchive::open(): Failed to open does_not_exist.rar: ERAR_EOPEN (file open error) in C:\php_rar\trunk\tests\test.php on line 3
    bool(false)
    bool(true)

    Fatal error: Uncaught exception 'RarException' with message 'unRAR internal error: Failed to open does_not_exist.rar: ERAR_EOPEN (file open error)' in C:\php_rar\trunk\tests\test.php:8
    Stack trace:
    #0 C:\php_rar\trunk\tests\test.php(8): RarArchive::open('does_not_exist....')
    #1 {main}
      thrown in C:\php_rar\trunk\tests\test.php on line 8

### Ver también

- RarException::isUsingExceptions() - Comprobar si el manejador de errores con excepciones está en uso

## Tabla de contenidos

- RarException::isUsingExceptions — Comprobar si el manejador de errores con excepciones está en uso
- RarException::setUsingExceptions — Activar y desactivar el manejador de errores con excepciones

- Instalación/Configuración
  - Instalación
  - Tipos de recursos
- Constantes predefinidas
- Ejemplos
- Funciones Rar
  - rar_wrapper_cache_stats — Caché de aciertos y errores del URL wrapper
- RarArchive — La clase RarArchive
  - RarArchive::close — Cerrar archivo RAR y liberar todos los recursos
  - RarArchive::getComment — Obtener comentarios de texto desde el archivo RAR
  - RarArchive::getEntries — Obtener la lista completa de entradas del archivo RAR
  - RarArchive::getEntry — Obtener el objeto entrada desde el archivo RAR
  - RarArchive::isBroken — Comprobar si un archivo está dañado (incompleto)
  - RarArchive::isSolid — Comprueba si el archivo RAR es sólido
  - RarArchive::open — Abre un archivo RAR
  - RarArchive::setAllowBroken — Determina si la apertura de archivos dañados se permite
  - RarArchive::__toString — Obtener representación de texto
- RarEntry — La clase RarEntry
  - RarEntry::extract — Extraer entrada del archivo
  - RarEntry::getAttr — Obtener los atributos de la entrada
  - RarEntry::getCrc — Obtener el CRC de la entrada
  - RarEntry::getFileTime — Devolver entrada última fecha de modificación
  - RarEntry::getHostOs — Obtener sistema operativo anfitrión del archivo de entrada
  - RarEntry::getMethod — Obtener método pack de la entrada
  - RarEntry::getName — Obtener el nombre de la entrada
  - RarEntry::getPackedSize — Obtiene el tamaño empaquetado de la entrada
  - RarEntry::getStream — Obtener manejador de archivo para entrada
  - RarEntry::getUnpackedSize — Obtener el tamaño descomprimido de la entrada
  - RarEntry::getVersion — Obtener la versión mínima del programa RAR requerida para desempaquetar la entrada
  - RarEntry::isDirectory — Comprobar si una entrada representa un directorio
  - RarEntry::isEncrypted — Comprobar si una entrada está cifrada
  - RarEntry::__toString — Obtener texto representación de entrada
- RarException — La clase RarException
  - RarException::isUsingExceptions — Comprobar si el manejador de errores con excepciones está en uso
  - RarException::setUsingExceptions — Activar y desactivar el manejador de errores con excepciones

# Zip

# Introducción

Esta extensión permite leer o escribir de forma transparente archivos comprimidos ZIP y los ficheros que hay dentro.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Tipos de recursos

## Requerimientos

Esta extensión requiere » libzip. La versión 1.1.2 estaba incluida en PHP hasta la versión 7.3.

La versión mínima soportada es 0.11, pero se recomienda encarecidamente una versión superior.

- Versión 1.2 requerida para soporte de encriptación, ver ZipArchive::setEncryptionIndex()
- Versión 1.3 requerida para soporte de progreso, ver ZipArchive::registerProgressCallback()
- Versión 1.6 requerida para soporte de cancelación, ver ZipArchive::registerCancelCallback()

## Instalación

## Sistemas Linux

Para usar estas funciones, PHP debe compilarse con soporte ZIP utilizando la opción de configuración --with-zip.

Antes de PHP 7.4.0, libzip estaba incluida con PHP, y para compilar la extensión se necesitaba usar la opción de configuración --enable-zip. Compilar contra la libzip incluida estaba desaconsejado a partir de PHP 7.3.0, pero aún era posible usando la opción de configuración --without-libzip.

Se ha añadido una opción de configuración --with-libzip=DIR para usar una instalación de libzip del sistema. Se requiere la versión 0.11 de libzip, recomendándose la 0.11.2 o superior.

## Windows

A partir de PHP 8.2.0, el archivo php_zip.dll DLL debe ser habilitado en php.ini. Anteriormente, esta extensión estaba integrada.

## Instalación mediante PECL

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/zip.

## Tipos de recursos

Existen dos tipos de recursos usados en el módulo Zip. El primero es el directorio Zip para el fichero Zip, el segundo la entrada Zip para la entrada de archivos.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

ZipArchive usa constantes de clase. Existen varios tipos de constantes, los principales son: Flags (prefijadas con `FL_`), Flags globales (prefijadas con `AFL_`), errores (prefijados con `ER_`) y modos (sin prefijo).

Modos de apertura de archivos
`ZipArchive::CREATE` (int)
  Crea el archivo si no existe.
`ZipArchive::OVERWRITE` (int)
  Si existe un archivo, ignora su contenido actual. En otras palabras, lo trata de la misma manera que un archivo vacío.
`ZipArchive::EXCL` (int)
  Error si el fichero ya existe.
`ZipArchive::RDONLY` (int)
  Abrir archivo en modo de solo lectura. Disponible a partir de PHP 7.4.3 y PECL zip 1.17.1, respectivamente, si se compila con libzip ≥ 1.0.0.
`ZipArchive::CHECKCONS` (int)
  Realiza comprobaciones de coherencia adicionales al archivo, producirá un error si falla.

Flags globales del archivo
`ZipArchive::AFL_RDONLY` (int)
  Archivo en modo de solo lectura, no se puede borrar. Disponible a partir de PHP 8.3.0 y PECL zip 1.22.0, respectivamente, si se compila con libzip ≥ 1.10.0.
`ZipArchive::AFL_IS_TORRENTZIP` (int)
  Sl archivo actual está comprimido en torrentzip. Disponible a partir de PHP 8.3.0 y PECL zip 1.22.0, respectivamente, si se compila con libzip ≥ 1.10.0.
`ZipArchive::AFL_WANT_TORRENTZIP` (int)
  Crear archivo en formato torrentzip. Disponible a partir de PHP 8.3.0 y PECL zip 1.22.0, respectivamente, si se compila con libzip ≥ 1.10.0.
`ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE` (int)
  No eliminar archivo si el archivo está vacío. Disponible a partir de PHP 8.3.0 y PECL zip 1.22.0, respectivamente, si se compila con libzip ≥ 1.10.0.

Flags del archivo
`ZipArchive::FL_NOCASE` (int)
  Ignorar mayúsculas el lookup del nombre
`ZipArchive::FL_NODIR` (int)
  Ignorar el componente directorio
`ZipArchive::FL_COMPRESSED` (int)
  Leer datos comprimidos
`ZipArchive::FL_UNCHANGED` (int)
  Usar los datos originales, ignorando cambios.
`ZipArchive::FL_RECOMPRESS` (int)
  Forzar la recompresión de los datos. Disponible a partir de PHP 8.0.0 y PECL zip 1.18.0. Obsoleto a partir de PHP 8.3.0 y PECL zip 1.22.1, será eliminado en una futura versión de libzip.
`ZipArchive::FL_ENCRYPTED` (int)
  Leer datos encriptados (implica FL_COMPRESSED). Disponible a partir de PHP 8.0.0 y PECL zip 1.18.0.
`ZipArchive::FL_OVERWRITE` (int)
  Si existe un archivo con nombre, sobrescríbalo (reemplácelo). Disponible a partir de PHP 8.0.0 y PECL zip 1.18.0.
`ZipArchive::FL_LOCAL` (int)
  En la cabecera local. Disponible a partir de PHP 8.0.0 y PECL zip 1.18.0.
`ZipArchive::FL_CENTRAL` (int)
  En el directorio central. Disponible a partir de PHP 8.0.0 y PECL zip 1.18.0.
`ZipArchive::FL_ENC_GUESS` (int)
  Codificación de la cadena de suposición (guess string) (predeterminado). Disponible a partir de PHP 7.0.8.
`ZipArchive::FL_ENC_RAW` (int)
  Obtener la cadena sin modificaciones. Disponible a partir de PHP 7.0.8.
`ZipArchive::FL_ENC_STRICT` (int)
  Seguir la especificación estrictamente. Disponible a partir de PHP 7.0.8.
`ZipArchive::FL_ENC_UTF_8` (int)
  La cadena está codificada en UTF-8. Disponible a partir de PHP 7.0.8.
`ZipArchive::FL_ENC_CP437` (int)
  La cadena está codifica en CP437. Disponible a partir de PHP 7.0.8.
`ZipArchive::FL_OPEN_FILE_NOW` (int)
  Abre el archivo cuando se añade en lugar de esperar a que se cierre el archivo comprimido. Tenga en cuenta el consumo de descriptores de archivo. Disponible a partir de PHP 8.3.0 y PECL zip 1.22.1.

Modos de compresión
`ZipArchive::CM_DEFAULT` (int)
  Mejor para desinflar o almacenar.
`ZipArchive::CM_STORE` (int)
  almacenar (no comprimir).
`ZipArchive::CM_SHRINK` (int)
  Reducir
`ZipArchive::CM_REDUCE_1` (int)
  reducido con factor 1
`ZipArchive::CM_REDUCE_2` (int)
  reducido con factor 2
`ZipArchive::CM_REDUCE_3` (int)
  reducido con factor 3
`ZipArchive::CM_REDUCE_4` (int)
  reducido con factor 4
`ZipArchive::CM_IMPLODE` (int)
  implodado
`ZipArchive::CM_DEFLATE` (int)
  Deflactado
`ZipArchive::CM_DEFLATE64` (int)
  deflate64
`ZipArchive::CM_PKWARE_IMPLODE` (int)
  PKWARE imploding
`ZipArchive::CM_BZIP2` (int)
  Algoritmo BZIP2
`ZipArchive::CM_LZMA` (int)
  Algoritmo LZMA
`ZipArchive::CM_LZMA2` (int)
  Algoritmo LZMA2. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.0, respectivamente, si se compila con libzip ≥ 1.6.0.
`ZipArchive::CM_ZSTD` (int)
  Algoritmo Zstandard. Disponible a partir de PHP 8.0.0 y PECL zip 1.19.1, respectivamente, si se compila con libzip ≥ 1.8.0.
`ZipArchive::CM_XZ` (int)
  Algoritmo XZ. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.1, respectivamente, si se compila con libzip ≥ 1.6.0.
`ZipArchive::CM_TERSE` (int)
`ZipArchive::CM_LZ77` (int)
`ZipArchive::CM_WAVPACK` (int)
`ZipArchive::CM_PPMD` (int)

Errores
`ZipArchive::ER_OK` (int)
  Sin errores.
`ZipArchive::ER_MULTIDISK` (int)
  Archivos zip multi-disk no soportados.
`ZipArchive::ER_RENAME` (int)
  Mantener fichero temporal fallado.
`ZipArchive::ER_CLOSE` (int)
  Cerrar fichero zip fallado.
`ZipArchive::ER_SEEK` (int)
  Buscar error
`ZipArchive::ER_READ` (int)
  Leer error
`ZipArchive::ER_WRITE` (int)
  Escribir error
`ZipArchive::ER_CRC` (int)
  Error CRC
`ZipArchive::ER_ZIPCLOSED` (int)
  Conteniendo el fichero zip que ha sido cerrado
`ZipArchive::ER_NOENT` (int)
  No existe el fichero.
`ZipArchive::ER_EXISTS` (int)
  El fichero ya existe
`ZipArchive::ER_OPEN` (int)
  No se puede abrir el fichero
`ZipArchive::ER_TMPOPEN` (int)
  Fallo al intentar crear fichero temporal.
`ZipArchive::ER_ZLIB` (int)
  Error de Zlib
`ZipArchive::ER_MEMORY` (int)
  Error de asignación de memoria
`ZipArchive::ER_CHANGED` (int)
  La entrada a cambiado
`ZipArchive::ER_COMPNOTSUPP` (int)
  Método de compresión no soportado.
`ZipArchive::ER_EOF` (int)
  EOF precoz.
`ZipArchive::ER_INVAL` (int)
  Argumento inválido
`ZipArchive::ER_NOZIP` (int)
  No es un archivo zip
`ZipArchive::ER_INTERNAL` (int)
  Error interno
`ZipArchive::ER_INCONS` (int)
  Fichero Zip inconsistente
`ZipArchive::ER_REMOVE` (int)
  No se puede eliminar el fichero
`ZipArchive::ER_DELETED` (int)
  La entrada ha sido eliminada
`ZipArchive::ER_ENCRNOTSUPP` (int)
  No se admite el método de cifrado. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.1, respectivamente.
`ZipArchive::ER_RDONLY` (int)
  Archivo de sólo lectura. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.1, respectivamente.
`ZipArchive::ER_NOPASSWD` (int)
  No se ha proporcionado ninguna contraseña. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.1, respectivamente.
`ZipArchive::ER_WRONGPASSWD` (int)
  Contraseña incorrecta proporcionada. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.1, respectivamente.
`ZipArchive::ER_OPNOTSUPP` (int)
  Operación no soportada. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.1, respectivamente, si se compila con libzip ≥ 1.0.0.
`ZipArchive::ER_INUSE` (int)
  Recurso todavía en uso. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.1, respectivamente, si se compila con libzip ≥ 1.0.0.
`ZipArchive::ER_TELL` (int)
  Diga error. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.1, respectivamente, si se compila con libzip ≥ 1.0.0.
`ZipArchive::ER_COMPRESSED_DATA` (int)
  Los datos comprimidos no son válidos. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.1, respectivamente, si se compila con libzip ≥ 1.6.0.
`ZipArchive::ER_CANCELLED` (int)
  Operación cancelada. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.1, respectivamente, si se compila con libzip ≥ 1.6.0.
`ZipArchive::ER_DATA_LENGTH` (int)
  Longitud de datos inesperada. Disponible a partir de PHP 8.3.0 y PECL zip 1.22.0, respectivamente, si se compila con libzip ≥ 1.10.0.
`ZipArchive::ER_NOT_ALLOWED` (int)
  No permitido en torrentzip. Disponible a partir de PHP 8.3.0 y PECL zip 1.22.0, respectivamente, si se compila con libzip ≥ 1.10.0.
`ZipArchive::ER_TRUNCATED_ZIP` (int)
  Archivo zip posiblemente truncado o corrupto. Disponible a partir de PHP 8.4.0 y PECL zip 1.22.4, respectivamente, si se compila contra libzip ≥ 1.11.1.

Modos de cifrado
`ZipArchive::EM_NONE` (int)
  No hay encriptación. Disponible a partir de PHP 7.2.0 y PECL zip 1.14.0, respectivamente.
`ZipArchive::EM_TRAD_PKWARE` (int)
  Cifrado tradicional PKWARE. Disponible a partir de PHP 8.0.0 y PECL zip 1.19.0, respectivamente.
`ZipArchive::EM_AES_128` (int)
  Encriptación AES 128. Disponible a partir de PHP 7.2.0 y PECL zip 1.14.0, respectivamente, si se compila con libzip ≥ 1.2.0.
`ZipArchive::EM_AES_192` (int)
  Encriptación AES 192. Disponible a partir de PHP 7.2.0 y PECL zip 1.14.0, respectivamente, si se compila con libzip ≥ 1.2.0.
`ZipArchive::EM_AES_256` (int)
  Encriptación AES 256. Disponible a partir de PHP 7.2.0 y PECL zip 1.14.0, respectivamente, si se compila con libzip ≥ 1.2.0.
`ZipArchive::EM_UNKNOWN` (int)
  Algoritmo de cifrado desconocido. Disponible a partir de PHP 8.0.0 y PECL zip 1.19.0, respectivamente.

Constantes de parámetro de longitud
`ZipArchive::LENGTH_TO_END` (int)
  Usa el tamaño del archivo; si el archivo crece, los datos adicionales se ignoran; si el archivo se reduce, se genera un error (`ZipArchive::ER_DATA_LENGTH`). Disponible a partir de PHP 8.3.0 y PECL zip 1.22.2.
`ZipArchive::LENGTH_UNCHECKED` (int)
  Usa todos los datos disponibles. Disponible a partir de PHP 8.3.0 y PECL zip 1.22.2, si se compila con libzip ≥ 1.10.1.

Otras constantes
`ZipArchive::LIBZIP_VERSION` (string)
  Versión de la biblioteca Zip. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.0.

Constantes de sistema operativo para atributos externos
`ZipArchive::OPSYS_DOS` (int)
`ZipArchive::OPSYS_AMIGA` (int)
`ZipArchive::OPSYS_OPENVMS` (int)
`ZipArchive::OPSYS_UNIX` (int)
`ZipArchive::OPSYS_VM_CMS` (int)
`ZipArchive::OPSYS_ATARI_ST` (int)
`ZipArchive::OPSYS_OS_2` (int)
`ZipArchive::OPSYS_MACINTOSH` (int)
`ZipArchive::OPSYS_Z_SYSTEM` (int)
`ZipArchive::OPSYS_CPM` (int)
`ZipArchive::OPSYS_WINDOWS_NTFS` (int)
`ZipArchive::OPSYS_MVS` (int)
`ZipArchive::OPSYS_VSE` (int)
`ZipArchive::OPSYS_ACORN_RISC` (int)
`ZipArchive::OPSYS_VFAT` (int)
`ZipArchive::OPSYS_ALTERNATE_MVS` (int)
`ZipArchive::OPSYS_BEOS` (int)
`ZipArchive::OPSYS_TANDEM` (int)
`ZipArchive::OPSYS_OS_400` (int)
`ZipArchive::OPSYS_OS_X` (int)
`ZipArchive::OPSYS_DEFAULT` (int)
  Disponible a partir de PECL zip 1.12.4.

# Ejemplos

Ejemplo #1 Crear un fichero Zip

    <?php

    $zip = new ZipArchive();
    $filename = "./test112.zip";

    if ($zip->open($filename, ZipArchive::CREATE)!==TRUE) {
        exit("cannot open <$filename>\n");
    }

    $zip->addFromString("testfilephp.txt" . time(), "#1 Esto es una cadena de prueba añadida como  testfilephp.txt.\n");
    $zip->addFromString("testfilephp2.txt" . time(), "#2 Esto es una cadena de prueba añadida como testfilephp2.txt.\n");
    $zip->addFile($thisdir . "/too.php","/testfromfile.php");
    echo "numficheros: " . $zip->numFiles . "\n";
    echo "estado:" . $zip->status . "\n";
    $zip->close();
    ?>

Ejemplo #2 Volcar la información del archivo y listarlos

    <?php
    $za = new ZipArchive();

    $za->open('test_with_comment.zip');
    print_r($za);
    var_dump($za);
    echo "numFicheros: " . $za->numFiles . "\n";
    echo "estado: " . $za->status  . "\n";
    echo "estadosSis: " . $za->statusSys . "\n";
    echo "nombreFichero: " . $za->filename . "\n";
    echo "comentario: " . $za->comment . "\n";

    for ($i=0; $i<$za->numFiles;$i++) {
        echo "index: $i\n";
        print_r($za->statIndex($i));
    }
    echo "numFichero:" . $za->numFiles . "\n";
    ?>

Ejemplo #3 Usando contenedor Zip, leer meta info de OpenOffice

    <?php
    $reader = new XMLReader();

    $reader->open('zip://' . dirname(__FILE__) . '/test.odt#meta.xml');
    $odt_meta = array();
    while ($reader->read()) {
        if ($reader->nodeType == XMLREADER::ELEMENT) {
            $elm = $reader->name;
        } else {
            if ($reader->nodeType == XMLREADER::END_ELEMENT && $reader->name == 'office:meta') {
                break;
            }
            if (!trim($reader->value)) {
                continue;
            }
            $odt_meta[$elm] = $reader->value;
        }
    }
    print_r($odt_meta);
    ?>

Este ejemplo utiliza la antigua API (PHP 4), abre un fichero ZIP, lee cada fichero del archivo y imprime su contenido. El archivotest2.zip usado en este ejmplo es uno de los archivos de prueba la fuente de distribución de ZZIPlib.

Ejemplo #4 Ejemplo del uso de Zip

    <?php

    $zip = zip_open("/tmp/test2.zip");

    if ($zip) {
        while ($zip_entry = zip_read($zip)) {
            echo "Nombre:               " . zip_entry_name($zip_entry) . "\n";
            echo "Tamaño actual del fichero:    " . zip_entry_filesize($zip_entry) . "\n";
            echo "Tamaño comprimido:    " . zip_entry_compressedsize($zip_entry) . "\n";
            echo "Método de compresión: " . zip_entry_compressionmethod($zip_entry) . "\n";

            if (zip_entry_open($zip, $zip_entry, "r")) {
                echo "Contenido del fichero:\n";
                $buf = zip_entry_read($zip_entry, zip_entry_filesize($zip_entry));
                echo "$buf\n";

                zip_entry_close($zip_entry);
            }
            echo "\n";

        }

        zip_close($zip);

    }
    ?>

# La clase ZipArchive

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

## Introducción

Un fichero, comprimido con Zip.

## Sinopsis de la Clase

class ZipArchive implements Countable {
/* Constantes */
public const int CREATE;
public const int EXCL;
public const int CHECKCONS;
public const int OVERWRITE;
public const int RDONLY;
public const int FL_NOCASE;
public const int FL_NODIR;
public const int FL_COMPRESSED;
public const int FL_UNCHANGED;
public const int FL_RECOMPRESS;
public const int FL_ENCRYPTED;
public const int FL_OVERWRITE;
public const int FL_LOCAL;
public const int FL_CENTRAL;
public const int FL_ENC_GUESS;
public const int FL_ENC_RAW;
public const int FL_ENC_STRICT;
public const int FL_ENC_UTF_8;
public const int FL_ENC_CP437;
public const int FL_OPEN_FILE_NOW;
public const int CM_DEFAULT;
public const int CM_STORE;
public const int CM_SHRINK;
public const int CM_REDUCE_1;
public const int CM_REDUCE_2;
public const int CM_REDUCE_3;
public const int CM_REDUCE_4;
public const int CM_IMPLODE;
public const int CM_DEFLATE;
public const int CM_DEFLATE64;
public const int CM_PKWARE_IMPLODE;
public const int CM_BZIP2;
public const int CM_LZMA;
public const int CM_LZMA2;
public const int CM_ZSTD;
public const int CM_XZ;
public const int CM_TERSE;
public const int CM_LZ77;
public const int CM_WAVPACK;
public const int CM_PPMD;
public const int ER_OK;
public const int ER_MULTIDISK;
public const int ER_RENAME;
public const int ER_CLOSE;
public const int ER_SEEK;
public const int ER_READ;
public const int ER_WRITE;
public const int ER_CRC;
public const int ER_ZIPCLOSED;
public const int ER_NOENT;
public const int ER_EXISTS;
public const int ER_OPEN;
public const int ER_TMPOPEN;
public const int ER_ZLIB;
public const int ER_MEMORY;
public const int ER_CHANGED;
public const int ER_COMPNOTSUPP;
public const int ER_EOF;
public const int ER_INVAL;
public const int ER_NOZIP;
public const int ER_INTERNAL;
public const int ER_INCONS;
public const int ER_REMOVE;
public const int ER_DELETED;
public const int ER_ENCRNOTSUPP;
public const int ER_RDONLY;
public const int ER_NOPASSWD;
public const int ER_WRONGPASSWD;
public const int ER_OPNOTSUPP;
public const int ER_INUSE;
public const int ER_TELL;
public const int ER_COMPRESSED_DATA;
public const int ER_CANCELLED;
public const int ER_DATA_LENGTH;
public const int ER_NOT_ALLOWED;
public const int ER_TRUNCATED_ZIP;
public const int AFL_RDONLY;
public const int AFL_IS_TORRENTZIP;
public const int AFL_WANT_TORRENTZIP;
public const int AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE;
public const int OPSYS_DOS;
public const int OPSYS_AMIGA;
public const int OPSYS_OPENVMS;
public const int OPSYS_UNIX;
public const int OPSYS_VM_CMS;
public const int OPSYS_ATARI_ST;
public const int OPSYS_OS_2;
public const int OPSYS_MACINTOSH;
public const int OPSYS_Z_SYSTEM;
public const int OPSYS_CPM;
public const int OPSYS_WINDOWS_NTFS;
public const int OPSYS_MVS;
public const int OPSYS_VSE;
public const int OPSYS_ACORN_RISC;
public const int OPSYS_VFAT;
public const int OPSYS_ALTERNATE_MVS;
public const int OPSYS_BEOS;
public const int OPSYS_TANDEM;
public const int OPSYS_OS_400;
public const int OPSYS_OS_X;
public const int OPSYS_DEFAULT;
public const int EM_NONE;
public const int EM_TRAD_PKWARE;
public const int EM_AES_128;
public const int EM_AES_192;
public const int EM_AES_256;
public const int EM_UNKNOWN;
public const string LIBZIP_VERSION;
public const int LENGTH_TO_END;
public const int LENGTH_UNCHECKED;
/* Propiedades */
public readonly int $lastId;
public readonly int $status;
public readonly int $statusSys;
public readonly int $numFiles;
public readonly string $filename;
public readonly string $comment;
/* Métodos */
public function addEmptyDir(string `$dirname`, int `$flags` = 0): bool
public function addFile(
string `$filepath`,
string `$entryname` = "",
int `$start` = 0,
int `$length` = `ZipArchive::LENGTH_TO_END`,
int `$flags` = `ZipArchive::FL_OVERWRITE`
): bool
public function addFromString(string `$name`, string `$content`, int `$flags` = `ZipArchive::FL_OVERWRITE`): bool
public function addGlob(string `$pattern`, int `$flags` = 0, array `$options` = []): array|false
public function addPattern(string `$pattern`, string `$path` = ".", array `$options` = []): array|false
public function clearError(): void
public function close(): bool
public function count(): int
public function deleteIndex(int `$index`): bool
public function deleteName(string `$name`): bool
public function extractTo(string `$pathto`, array|string|null `$files` = `null`): bool
public function getArchiveComment(int `$flags` = 0): string|false
public function getArchiveFlag(int `$flag`, int `$flags` = 0): int
public function getCommentIndex(int `$index`, int `$flags` = 0): string|false
public function getCommentName(string `$name`, int `$flags` = 0): string|false
public function getExternalAttributesIndex(
int `$index`,
int `&$opsys`,
int `&$attr`,
int `$flags` = 0
): bool
public function getExternalAttributesName(
string `$name`,
int `&$opsys`,
int `&$attr`,
int `$flags` = 0
): bool
public function getFromIndex(int `$index`, int `$len` = 0, int `$flags` = 0): string|false
public function getFromName(string `$name`, int `$len` = 0, int `$flags` = 0): string|false
public function getNameIndex(int `$index`, int `$flags` = 0): string|false
public function getStatusString(): string
public function getStream(string `$name`): resource|false
public function getStreamIndex(int `$index`, int `$flags` = 0): resource|false
public function getStreamName(string `$name`, int `$flags` = 0): resource|false
public static function isCompressionMethodSupported(int `$method`, bool `$enc` = `true`): bool
public static function isEncryptionMethodSupported(int `$method`, bool `$enc` = `true`): bool
public function locateName(string `$name`, int `$flags` = 0): int|false
public function open(string `$filename`, int `$flags` = 0): bool|int
public function registerCancelCallback(callable `$callback`): bool
public function registerProgressCallback(float `$rate`, callable `$callback`): bool
public function renameIndex(int `$index`, string `$new_name`): bool
public function renameName(string `$name`, string `$new_name`): bool
public function replaceFile(
string `$filepath`,
int `$index`,
int `$start` = 0,
int `$length` = `ZipArchive::LENGTH_TO_END`,
int `$flags` = 0
): bool
public function setArchiveComment(string `$comment`): bool
public function setArchiveFlag(int `$flag`, int `$value`): bool
public function setCommentIndex(int `$index`, string `$comment`): bool
public function setCommentName(string `$name`, string `$comment`): bool
public function setCompressionIndex(int `$index`, int `$method`, int `$compflags` = 0): bool
public function setCompressionName(string `$name`, int `$method`, int `$compflags` = 0): bool
public function setEncryptionIndex(int `$index`, int `$method`, #[\SensitiveParameter]?string `$password` = `null`): bool
public function setEncryptionName(string `$name`, int `$method`, #[\SensitiveParameter]?string `$password` = `null`): bool
public function setExternalAttributesIndex(
int `$index`,
int `$opsys`,
int `$attr`,
int `$flags` = 0
): bool
public function setExternalAttributesName(
string `$name`,
int `$opsys`,
int `$attr`,
int `$flags` = 0
): bool
public function setMtimeIndex(int `$index`, int `$timestamp`, int `$flags` = 0): bool
public function setMtimeName(string `$name`, int `$timestamp`, int `$flags` = 0): bool
public function setPassword(#[\SensitiveParameter]string `$password`): bool
public function statIndex(int `$index`, int `$flags` = 0): array|false
public function statName(string `$name`, int `$flags` = 0): array|false
public function unchangeAll(): bool
public function unchangeArchive(): bool
public function unchangeIndex(int `$index`): bool
public function unchangeName(string `$name`): bool
}

## Propiedades

lastId
  Valor de índice de la última entrada añadida (archivo o directorio). Disponible para archivo cerrado, a partir de PHP 8.0.0 y PECL zip 1.18.0.
status
  Estado del archivo Zip. Disponible para archivo cerrado, a partir de PHP 8.0.0 y PECL zip 1.18.0.
statusSys
  Estado del sistema del archivo Zip. Disponible para archivo cerrado, a partir de PHP 8.0.0 y PECL zip 1.18.0.
numFiles
  Número de ficheros en el archivo
filename
  Nombre del archivo en le sistema de archivos
comment
  Comentario para el archivo

# ZipArchive::addEmptyDir

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.8.0)

ZipArchive::addEmptyDir — Añadir un nuevo directorio

### Descripción

public function ZipArchive::addEmptyDir(string `$dirname`, int `$flags` = 0): bool

Añade un directoro vacío en el archivo.

### Parámetros

`dirname`
  El directorio a añadir.
`flags`
  Máscara de bits compuesta por `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`. El comportamiento de estas constantes se describe en la página de constantes ZIP.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL zip 1.18.0 | Se añadio `flags`.

### Ejemplos

Ejemplo #1 Crea un nuevo directorio en un archivo

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        if($zip->addEmptyDir('newDirectory')) {
            echo 'Creado nuevo directorio root';
        } else {
            echo 'No se puede crear el directorio';
        }
        $zip->close();
    } else {
        echo 'falló';
    }
    ?>

# ZipArchive::addFile

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::addFile — Añade un fichero al archivo ZIP para la ruta dada

### Descripción

public function ZipArchive::addFile(
string `$filepath`,
string `$entryname` = "",
int `$start` = 0,
int `$length` = `ZipArchive::LENGTH_TO_END`,
int `$flags` = `ZipArchive::FL_OVERWRITE`
): bool

Añade un fichero al archivo ZIP par la ruta dada.

> Nota: Para una portabilidad máxima, se recomienda siempre utilizar barras oblicuas (`/`) como separador de directorio en los nombres de archivos zip.

### Parámetros

`filename`
  La ruta del fichero a añadir.
`entryname`
  Si corresponde, este es el nombre local dentro del archivo ZIP que reemplazará el `filepath`.
`start`
  Para la copia parcial, posición de inicio.
`length`
  Para copia parcial, longitud a copiar, si `ZipArchive::LENGTH_TO_END` (0) se usa el tamaño del archivo, si `ZipArchive::LENGTH_UNCHECKED` se usa todo el archivo (comenzando desde `start`).
`flags`
  Máscara de bits compuesta por `ZipArchive::FL_OVERWRITE`, `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`, `ZipArchive::FL_OPEN_FILE_NOW`. El comportamiento de estas constantes se describe en la página de constantes ZIP.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL zip 1.18.0 | Se añadio `flags`.
8.3.0, PECL zip 1.22.1 | Se añadio `ZipArchive::FL_OPEN_FILE_NOW`.
8.3.0, PECL zip 1.22.2 | Se añadieron `ZipArchive::LENGTH_TO_END` y `ZipArchive::LENGTH_UNCHECKED`.

### Ejemplos

Este ejemplo abre un archivo ZIP test.zip y añade el fichero /path/to/index.txt. como newname.txt.

Ejemplo #1 Abrir y extraer

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->addFile('/path/to/index.txt', 'newname.txt');
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

### Notas

> Nota: Cuando un fichero es añadido al archivo, PHP bloqueará el fichero. El bloqueo se desbloqueará cuando el objeto ZipArchive finalice, ya sea a través de ZipArchive::close() o el objeto ZipArchive sea destruido. Esto puede impedir que se pueda eliminar el archivo que se está añadiendo hasta después de que el bloqueo haya sido liberado.

### Ver también

- ZipArchive::replaceFile() - Reemplaza fichero en el archivo ZIP con una ruta determinada

# ZipArchive::addFromString

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::addFromString — Añadir un fichero al archivo ZIP usando su contenido

### Descripción

public function ZipArchive::addFromString(string `$name`, string `$content`, int `$flags` = `ZipArchive::FL_OVERWRITE`): bool

Añade un fichero al archivo ZIP usando su contenido.

> Nota: Para una portabilidad máxima, se recomienda siempre utilizar barras oblicuas (`/`) como separador de directorio en los nombres de archivos zip.

### Parámetros

`name`
  Nombre de la entrada a crear.
`content`
  El contenido a usar para crear la entrada. Es usado en modo binary safe.
`flags`
  Máscara de bits compuesta por `ZipArchive::FL_OVERWRITE`, `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`. El comportamiento de estas constantes se describe en la página de constantes ZIP.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL zip 1.18.0 | Se añadio `flags`.

### Ejemplos

Ejemplo #1 Añade una entrada al nuevo fichero

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('test.txt', 'el contenido del fichero va aquí');
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

Ejemplo #2 Añade un fichero en un directorio dentro de un archivo

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->addFromString('dir/test.txt', 'el contenido del fichero va aquí');
        $zip->close();
        echo 'ok';
    } else {
        echo 'falló';
    }
    ?>

# ZipArchive::addGlob

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL zip >= 1.9.0)

ZipArchive::addGlob — Añadir ficheros de un directorio mediante un patrón glob

### Descripción

public function ZipArchive::addGlob(string `$pattern`, int `$flags` = 0, array `$options` = []): array|false

Añade ficheros de un directorio que corresponde con el patrón global `pattern`.

> Nota: Para una portabilidad máxima, se recomienda siempre utilizar barras oblicuas (`/`) como separador de directorio en los nombres de archivos zip.

### Parámetros

`pattern`
  Un patrón glob()contra el cual se hará la correspondencia con los ficheros.
`flags`
  Una máscara de un bit de marcas `glob()`.
`options`

  Un array asociativo de opciones. Las opciones disponibles son:

  - `"add_path"` Prefijo a indicar cuando se traduce la ruta de acceso del fichero dentro del archivo. Esta traducción se aplica después de cualquier operación de eliminación definida por las opciones `"remove_path"` o `"remove_all_path"`.
  - `"remove_path"` Prefijo para eliminar la ruta de acceso de los ficheros antes de añadirlos al archivo.
  - `"remove_all_path"` `true` para utilizar únicamente el nombre del fichero y añadirlo a la raíz del archivo.
  - `"flags"` Máscara de bits compuesta por `ZipArchive::FL_OVERWRITE`, `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`, `ZipArchive::FL_OPEN_FILE_NOW`. El comportamiento de estas constantes se describe en la página de constantes ZIP.
  - `"comp_method"` Método de compresión, una de las constantes `ZipArchive::CM_*`, ver la página de constantes ZIP.
  - `"comp_flags"` Nivel de compresión.
  - `"enc_method"` Método de cifrado, una de las constantes `ZipArchive::EM_*`, ver la página de constantes ZIP.
  - `"enc_password"` Contraseña utilizada para el cifrado.

### Valores devueltos

Un array de archivos añadidos en caso de éxito o `false` si ocurre un error

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL zip 1.18.0 | Se añadió `"flags"` en `options`.
8.0.0, PECL zip 1.18.1 | Se añadieron `"comp_method"`, `"comp_flags"`, `"enc_method"` y `"enc_password"` en `options`.
8.3.0, PECL zip 1.22.1 | Se añadió `ZipArchive::FL_OPEN_FILE_NOW`.

### Ejemplos

Ejemplo #1 Ejemplo con ZipArchive::addGlob()

Añadir todos los ficheros de scripts y texto php del directorio de trabajo actual

    <?php
    $zip = new ZipArchive();
    $ret = $zip->open('application.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE);
    if ($ret !== TRUE) {
        printf('Erróneo con el código %d', $ret);
    } else {
        $options = array('add_path' => 'sources/', 'remove_all_path' => TRUE);
        $zip->addGlob('*.{php,txt}', GLOB_BRACE, $options);
        $zip->close();
    }
    ?>

### Ver también

- ZipArchive::addFile() - Añade un fichero al archivo ZIP para la ruta dada
- ZipArchive::addPattern() - Añade ficheros de un directorio a partir de un patrón PCRE

# ZipArchive::addPattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL zip >= 1.9.0)

ZipArchive::addPattern — Añade ficheros de un directorio a partir de un patrón PCRE

### Descripción

public function ZipArchive::addPattern(string `$pattern`, string `$path` = ".", array `$options` = []): array|false

Añade ficheros de un directorio que coinciden con la expresión regular `pattern`. La operación no es recursiva. Únicamente se hará la correspondencia del patrón con el nombre del fichero.

### Parámetros

`pattern`
  Un patrón PCRE contra el cual se realizará la correspondencia.
`path`
  El directorio que será escaneado. Por defecto es el directorio de trabajo actual.
`options`
  Un array asociativo de opciones aceptadas por ZipArchive::addGlob().

### Valores devueltos

Un array de archivos añadidos en caso de éxito o `false` si ocurre un error

### Ejemplos

Ejemplo #1 Ejemplo con ZipArchive::addPattern()

Añadir todos los scripts y ficheros de texto php del directorio actual

    <?php
    $zip = new ZipArchive();
    $ret = $zip->open('application.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE);
    if ($ret !== TRUE) {
        printf('Erróneo con código %d', $ret);
    } else {
        $directory = realpath('.');
        $options = array('add_path' => 'sources/', 'remove_path' => $directory);
        $zip->addPattern('/\.(?:php|txt)$/', $directory, $options);
        $zip->close();
    }
    ?>

### Ver también

- ZipArchive::addFile() - Añade un fichero al archivo ZIP para la ruta dada
- ZipArchive::addGlob() - Añadir ficheros de un directorio mediante un patrón glob

# ZipArchive::clearError

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::clearError — Borra el mensaje de error, los mensajes del sistema y/o zip

### Descripción

public function ZipArchive::clearError(): void

Borra el mensaje de error, los mensajes del sistema y/o zip.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

### Ver también

- ZipArchive::getStatusString() - Devuelve mensajes de: estado de error, de sistema y/o mensajes de zip

# ZipArchive::close

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::close — Cierra el fichero activo (abierto o el nuevo creado)

### Descripción

public function ZipArchive::close(): bool

Cierra fichero abierto o creado y guarda los cambios. Este método es automáticamente llamado al finalizar el script.

Si el archivo no contiene ningún fichero, el fichero es completamente eliminado por defecto (no se escribe ningún archivo vacío) según el valor de la bandera global `ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ZipArchive::setArchiveFlag() - Define una bandera global de un archivo ZIP

# ZipArchive::count

(PHP 7 >= 7.2.0, PHP 8, PECL zip >= 1.15.0)

ZipArchive::count — Cuenta el número de archivos en el archivo

### Descripción

public function ZipArchive::count(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de ficheros en el archivo.

# ZipArchive::deleteIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::deleteIndex — Elimina una entrada en el archivo usando su índice

### Descripción

public function ZipArchive::deleteIndex(int `$index`): bool

Elimina una entrada en su archivo usando su índice.

### Parámetros

`index`
  Índice de la entrada a eliminar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Elimina el fichero desde el archivo usando su índice

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->deleteIndex(2);
        $zip->close();
        echo 'ok';
    } else {
        echo 'falló';
    }
    ?>

# ZipArchive::deleteName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::deleteName — Elimina una entrada en el archivo por su nombre

### Descripción

public function ZipArchive::deleteName(string `$name`): bool

Elimina una entrada en el archivo por su nombre

### Parámetros

`name`
  Nombre de la entrada a eliminar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Eliminado un fichero y un directorio desde un archivo, usando nombres

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test1.zip') === TRUE) {
        $zip->deleteName('testfromfile.php');
        $zip->deleteName('testDir/');
        $zip->close();
        echo 'ok';
    } else {
        echo 'Falló';
    }
    ?>

# ZipArchive::extractTo

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::extractTo — Extraer el contenido del archivo

### Descripción

public function ZipArchive::extractTo(string `$pathto`, array|string|null `$files` = `null`): bool

Extrae el archivo completo o los ficheros dados en la ruta que se especifique.

Advertencia

Los permisos por omisión para los archivos y directorios extraídos dan el más amplio acceso posible. Esto se puede restringir estableciendo la umask actual, que se puede cambiar usando umask().

Por razones de seguridad, los permisos originales no se restauran. Para ver un ejemplo de cómo restaurarlos, consulte el ejemplo de código en la página de ZipArchive::getExternalAttributesIndex().

### Parámetros

`pathto`
  Destino en donde extraer los ficheros.
`files`
  Las entradas a extraer. Acepta tanto un solo nombre o un array de nombres.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Extraer todas las entradas

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->extractTo('/my/destination/dir/');
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

Ejemplo #2 Extraer dos entradas

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test_im.zip');
    if ($res === TRUE) {
        $zip->extractTo('/my/destination/dir/', array('pear_item.gif', 'testfromfile.php'));
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

### Notas

> Nota: Los sistemas de archivos NTFS de Windows no soportan ciertos caracteres en los nombres de archivo, como `<|>*?":`. Los nombres de archivo con un punto final no son soportados. A diferencia de algunas herramientas de extracción, este método no reemplaza estos caracteres con un guión bajo, sino que falla al extraer tales archivos.

# ZipArchive::getArchiveComment

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getArchiveComment — Devuelve el comentario del archivo ZIP

### Descripción

public function ZipArchive::getArchiveComment(int `$flags` = 0): string|false

Devuelve el comentario del archivo ZIP.

### Parámetros

`flags`
  Si las flags se establecen en `ZipArchive::FL_UNCHANGED`, el comentario original se devuelve sin cambios.

### Valores devueltos

Devuelve el comentario del archivo Zip o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Vuelca el comentario del archivo

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test_with_comment.zip');
    if ($res === TRUE) {
        var_dump($zip->getArchiveComment());
        /* O usando la propiedad del archivo */
        var_dump($zip->comment);
    } else {
        echo 'falló, código:' . $res;
    }
    ?>

# ZipArchive::getArchiveFlag

(PHP >= 8.3.0, PECL zip >= 1.22.0)

ZipArchive::getArchiveFlag — Devuelve el valor de una bandera global del archivo

### Descripción

public function ZipArchive::getArchiveFlag(int `$flag`, int `$flags` = 0): int

Devuelve el valor de una bandera global del archivo.

### Parámetros

`flag`

  La bandera global a recuperar, entre las constantes `AFL_*`:

  - `ZipArchive::AFL_RDONLY`
  - `ZipArchive::AFL_IS_TORRENTZIP`
  - `ZipArchive::AFL_WANT_TORRENTZIP`
  - `ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE`
`flags`
  Si `flags` se define como `ZipArchive::FL_UNCHANGED`, la bandera original no se modifica y se devuelve.

### Valores devueltos

Devuelve 1 si la bandera está definida para el archivo, 0 si no lo está, y -1 si ocurre un error.

### Ejemplos

Ejemplo #1 Prueba si el archivo está en formato torrentzip

    <?php

    $zip = new ZipArchive;
    $res = $zip->open('test.zip');

    if ($res === TRUE) {
        var_dump($zip->getArchiveFlag(ZipArchive::AFL_IS_TORRENTZIP));
    } else {
        echo 'Fallo, código: ' . $res;
    }
    ?>

### Ver también

- ZipArchive::setArchiveFlag() - Define una bandera global de un archivo ZIP

# ZipArchive::getCommentIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::getCommentIndex — Devuelve el comentario de una entrada usando la entrada díndice

### Descripción

public function ZipArchive::getCommentIndex(int `$index`, int `$flags` = 0): string|false

Devuelve el comentario de una entrada usando la entrada índice.

### Parámetros

`index`
  Índice de la entrada
`flags`
  Si flags `ZipArchive::FL_UNCHANGED`, se devolverá el comentario original no cambiado.

### Valores devueltos

Con éxito devuelve el comentario o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Vuelca el comentario de la entrada

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test1.zip');
    if ($res === TRUE) {
        var_dump($zip->getCommentIndex(1));
    } else {
        echo 'falló, código:' . $res;
    }
    ?>

# ZipArchive::getCommentName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::getCommentName — Devuelve el comentario de una entrada usando el nombre de la entrada

### Descripción

public function ZipArchive::getCommentName(string `$name`, int `$flags` = 0): string|false

Devuelve el comentario de una entrada usando el nombre de la entrada.

### Parámetros

`name`
  Nombre de la entrada
`flags`
  Si flags está defindo a `ZipArchive::FL_UNCHANGED`, se devuelve el comentario original no cambiado.

### Valores devueltos

Devuelve el comentario si se ejecutó con éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Vuelca el comentario de la entrada

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test1.zip');
    if ($res === TRUE) {
        var_dump($zip->getCommentName('test/entry1.txt'));
    } else {
        echo 'Falló, código:' . $res;
    }
    ?>

# ZipArchive::getExternalAttributesIndex

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::getExternalAttributesIndex — Obtener los atributos externos de una entrada definida por su índice

### Descripción

public function ZipArchive::getExternalAttributesIndex(
int `$index`,
int `&$opsys`,
int `&$attr`,
int `$flags` = 0
): bool

Recuperar los atributos externos de una entrada definida por su índice.

### Parámetros

`index`
  El índice de la entrada.
`opsys`
  En caso de éxito, recibe el código del sistema operativo definido por una de las constantes ZipArchive::OPSYS_.
`attr`
  En caso de éxito, recibe los atributos externos. El valor dependerá del sistema operativo.
`flags`
  Si flags se establece a `ZipArchive::FL_UNCHANGED`, se devuelven los atributos originales sin cambios.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Este ejemplo extrae todas las entradas de un archivo ZIP test.zip y asigna los permisos Unix tomados de los atributos externos.

Ejemplo #1 Extraer todas las entradas con permisos Unix

    <?php
    $zip = new ZipArchive();
    if ($zip->open('test.zip') === TRUE) {
        for ($idx=0 ; $s = $zip->statIndex($idx) ; $idx++) {
            if ($zip->extractTo('.', $s['name'])) {
                if ($zip->getExternalAttributesIndex($idx, $opsys, $attr)
                    && $opsys==ZipArchive::OPSYS_UNIX) {
                   chmod($s['name'], ($attr >> 16) & 0777);
                }
            }
        }
        $zip->close();
        echo "Ok\n";
    } else {
        echo "KO\n";
    }
    ?>

# ZipArchive::getExternalAttributesName

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::getExternalAttributesName — Obtener los atributos externos de una entrada definida por su nombre

### Descripción

public function ZipArchive::getExternalAttributesName(
string `$name`,
int `&$opsys`,
int `&$attr`,
int `$flags` = 0
): bool

Obtener los atributos externos de una entrada definida por su nombre.

### Parámetros

`name`
  El nombre de la entrada.
`opsys`
  En caso de éxito, recibe el código del sistema operativo definido por una de las constantes ZipArchive::OPSYS_.
`attr`
  En caso de éxito, recibe los atributos externos. El valor depende del sistema operativo.
`flags`
  Si flags se establece a `ZipArchive::FL_UNCHANGED`, se devuelven los atributos originales sin cambios.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# ZipArchive::getFromIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getFromIndex — Devuelve el contenido de la entrada usando su índice

### Descripción

public function ZipArchive::getFromIndex(int `$index`, int `$len` = 0, int `$flags` = 0): string|false

Devuelve el contenido de la entrada usando su índice.

### Parámetros

`index`
  El índice de la entrada
`len`
  La longitud que se see desde la entrada. Si es `0`, entonces toda la entrada se lee.
`flags`

  Las flags usadas para abrir el fichero. Los siguientes valores pueden combinarse con OR.

  - `ZipArchive::FL_UNCHANGED`
  - `ZipArchive::FL_COMPRESSED`

### Valores devueltos

Devuelve el contenido de la entrada si se ejecutó con éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Obtener el contenido del fichero

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        echo $zip->getFromIndex(2);
        $zip->close();
    } else {
        echo 'falló';
    }
    ?>

### Ver también

- ZipArchive::getFromName() - Devuelve el contenido de la entrada utilizando su nombre

# ZipArchive::getFromName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getFromName — Devuelve el contenido de la entrada utilizando su nombre

### Descripción

public function ZipArchive::getFromName(string `$name`, int `$len` = 0, int `$flags` = 0): string|false

Devuelve el contenido de la entrada utilizando su nombre

### Parámetros

`name`
  Nombre de la entrada
`len`
  La longitud a ser leída desde la entrada. Si es `0`, entonces toda la entrada es leída.
`flags`

  Los indicadores a utilizar para abrir el archivo. Los siguientes valores podrían ser escritos juntos con un OR lógico en él.

  - `ZipArchive::FL_UNCHANGED`
  - `ZipArchive::FL_COMPRESSED`
  - `ZipArchive::FL_NOCASE`

### Valores devueltos

Devuelve el contenido de la entrada en caso de tener éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Obtener el contenido de los ficheros

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test1.zip') === TRUE) {
        echo $zip->getFromName('testfromfile.php');
        $zip->close();
    } else {
        echo 'falló';
    }
    ?>

Ejemplo #2 Convierte una imagen desde una entrada de fichero zip

    <?php
    $z = new ZipArchive();
    if ($z->open(dirname(__FILE__) . '/test_im.zip')) {
        $im_string = $z->getFromName("pear_item.gif");
        $im = imagecreatefromstring($im_string);
        imagepng($im, 'b.png');
    }
    ?>

### Ver también

- ZipArchive::getFromIndex() - Devuelve el contenido de la entrada usando su índice

# ZipArchive::getNameIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::getNameIndex — Devuelve el nombre de una entrada utilizando su índice

### Descripción

public function ZipArchive::getNameIndex(int `$index`, int `$flags` = 0): string|false

Devuelve el nombre de una entrada utilizando su índice.

### Parámetros

`index`
  El índice de la entrada.
`flags`
  Si las flags se establecen en `ZipArchive::FL_UNCHANGED`, el nombre original es devuelto sin cambios.

### Valores devueltos

Devuelve el nombre en caso de tener éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de ZipArchive::getNameIndex()

    <?php
    if ($zip->open('test.zip') == TRUE) {
     for ($i = 0; $i < $zip->numFiles; $i++) {
         $filename = $zip->getNameIndex($i);
         // ...
     }
    }
    ?>

# ZipArchive::getStatusString

(PHP 5 >= 5.2.7, PHP 7, PHP 8)

ZipArchive::getStatusString — Devuelve mensajes de: estado de error, de sistema y/o mensajes de zip

### Descripción

public function ZipArchive::getStatusString(): string

Devuelve mensajes de: estado de error, de sistema y/o mensajes de zip.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un string con el mensaje de estado.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL zip 1.18.0 | Este método puede ser llamado en un archivo cerrado.
8.0.0, PECL zip 1.18.0 | Este método ya no devuelve `false` en caso de fallo.

# ZipArchive::getStream

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getStream — Obtener un manejador de fichero para la entrada definido por su nombre (sólo lectura)

### Descripción

public function ZipArchive::getStream(string `$name`): resource|false

Obtener un manejador de fichero para la entrada definido por su nombre. Por ahora, éste solamente soporta operaciones de lectura.

### Parámetros

`name`
  El nombre de la entrada a utilizar.

### Valores devueltos

Devuelve un puntero de fichero (un recurso) en caso de tener éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Obtiene los contenidos de entrada con fread() y lo almacena

    <?php
    $contents = '';
    $z = new ZipArchive();
    if ($z->open('test.zip')) {
        $fp = $z->getStream('test');
        if(!$fp) exit("failed\n");

        while (!feof($fp)) {
            $contents .= fread($fp, 2);
        }

        fclose($fp);
        file_put_contents('t',$contents);
        echo "done.\n";
    }
    ?>

Ejemplo #2 Lo mismo como el ejemplo anterior pero con fopen() y el envoltorio de flujo de zip

    <?php
    $contents = '';
    $fp = fopen('zip://' . dirname(__FILE__) . '/test.zip#test', 'r');
    if (!$fp) {
        exit("cannot open\n");
    }
    while (!feof($fp)) {
        $contents .= fread($fp, 2);
    }
    echo "$contents\n";
    fclose($fp);
    echo "done.\n";
    ?>

Ejemplo #3 El flujo de envoltorio y la imagen, también pueden ser utilizados con la función xml

    <?php
    $im = imagecreatefromgif('zip://' . dirname(__FILE__) . '/test_im.zip#pear_item.gif');
    imagepng($im, 'a.png');
    ?>

### Ver también

- ZipArchive::getStreamIndex() - Recupera un manejador de archivo para la entrada definida por su índice (solo lectura)
- ZipArchive::getStreamName() - Recupera un manejador de archivo para la entrada definida por su nombre (solo lectura)
- Flujos de compresión

# ZipArchive::getStreamIndex

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::getStreamIndex — Recupera un manejador de archivo para la entrada definida por su índice (solo lectura)

### Descripción

public function ZipArchive::getStreamIndex(int `$index`, int `$flags` = 0): resource|false

Recupera un manejador de archivo para la entrada definida por su índice. Actualmente, esta función solo soporta operaciones de lectura.

### Parámetros

`index`
  Índice de la entrada a utilizar.
`flags`
  Si `flags` se define como `ZipArchive::FL_UNCHANGED`, el flujo original es devuelto.

### Valores devueltos

Devuelve un puntero de archivo (recurso) en caso de éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Obtener el contenido de la entrada con fread() y almacenarlo

    <?php
    $contents = '';
    $z = new ZipArchive();
    if ($z->open('test.zip')) {
        $fp = $z->getStreamIndex(1, ZipArchive::FL_UNCHANGED);
        if(!$fp) die($z->getStatusString());

        echo stream_get_contents($fp);

        fclose($fp);
    }
    ?>

### Ver también

- ZipArchive::getStreamName() - Recupera un manejador de archivo para la entrada definida por su nombre (solo lectura)

# ZipArchive::getStreamName

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::getStreamName — Recupera un manejador de archivo para la entrada definida por su nombre (solo lectura)

### Descripción

public function ZipArchive::getStreamName(string `$name`, int `$flags` = 0): resource|false

Recupera un manejador de archivo para la entrada definida por su nombre. Actualmente, esta función solo soporta operaciones de lectura.

### Parámetros

`name`
  El nombre de la entrada a utilizar.
`flags`
  Si `flags` se define como `ZipArchive::FL_UNCHANGED`, el flujo original es devuelto.

### Valores devueltos

Devuelve un puntero de archivo (recurso) en caso de éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Obtener el contenido de la entrada con fread() y almacenarlo

    <?php
    $contents = '';
    $z = new ZipArchive();
    if ($z->open('test.zip')) {
        $fp = $z->getStreamName('test', ZipArchive::FL_UNCHANGED);
        if(!$fp) die($z->getStatusString());

        echo stream_get_contents($fp);

        fclose($fp);
    }
    ?>

### Ver también

- ZipArchive::getStreamIndex() - Recupera un manejador de archivo para la entrada definida por su índice (solo lectura)

# ZipArchive::isCompressionMethodSupported

(PHP >= 8.0.0, PECL zip >= 1.19.0)

ZipArchive::isCompressionMethodSupported — Verifica si un método de compresión es soportado por libzip

### Descripción

public static function ZipArchive::isCompressionMethodSupported(int `$method`, bool `$enc` = `true`): bool

Verifica si un método de compresión es soportado por libzip.

### Parámetros

`method`
  El método de compresión, una de las constantes `ZipArchive::CM_*`.
`enc`
  Si es `true`, verifica la compresión; si es `false`, verifica la descompresión.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Notas

> Nota: Esta función está disponible solo si la compilación se realizó con ≥ 1.7.0.

### Ver también

- ZipArchive::setCompressionIndex() - Establecer el método de compresión de una entrada definida por su índice
- ZipArchive::setCompressionName() - Establecer el método de compresión de una entrada definida por su nombre

# ZipArchive::isEncryptionMethodSupported

(PHP >= 8.0.0, PECL zip >= 1.19.0)

ZipArchive::isEncryptionMethodSupported — Verifica si un método de cifrado es soportado por libzip

### Descripción

public static function ZipArchive::isEncryptionMethodSupported(int `$method`, bool `$enc` = `true`): bool

Verifica si un método de cifrado es soportado por libzip.

### Parámetros

`method`
  El método de cifrado, una de las constantes `ZipArchive::EM_*`.
`enc`
  Si es `true`, verifica el cifrado; si es `false`, verifica el descifrado.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Notas

> Nota: Esta función está disponible solo si la extensión ha sido compilada con libzip ≥ 1.7.0.

### Ver también

- ZipArchive::setEncryptionIndex() - Establece el método de cifrado de una entrada definida por su índice
- ZipArchive::setEncryptionName() - Establece el método de cifrado de una entrada definida por su nombre

# ZipArchive::locateName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::locateName — Devuelve el índice de la entrada en el archivo

### Descripción

public function ZipArchive::locateName(string `$name`, int `$flags` = 0): int|false

Localiza una entrada utilizando su nombre.

### Parámetros

`name`
  El nombre de la entrada a buscar
`flags`

  Los indicadores son especificados agregándoles OR a los siguientes valores, ó 0 para ninguno de ellos.

  - `ZipArchive::FL_NOCASE`
  - `ZipArchive::FL_NODIR`

### Valores devueltos

Devuelve el índice de la entrada en caso de tener éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Crear un archivo y luego utilizarlo con ZipArchive::locateName()

    <?php
    $file = 'testlocate.zip';

    $zip = new ZipArchive;
    if ($zip->open($file, ZipArchive::CREATE) !== TRUE) {
        exit('falló');
    }

    $zip->addFromString('entry1.txt', 'entry #1');
    $zip->addFromString('entry2.txt', 'entry #2');
    $zip->addFromString('dir/entry2d.txt', 'entry #2');

    if ($zip->status !== ZipArchive::ER_OK) {
        echo "falló al escribir en el archivo zip\n";
    }
    $zip->close();

    if ($zip->open($file) !== TRUE) {
        exit('falló');
    }

    echo $zip->locateName('entry1.txt') . "\n";
    echo $zip->locateName('eNtry2.txt') . "\n";
    echo $zip->locateName('eNtry2.txt', ZipArchive::FL_NOCASE) . "\n";
    echo $zip->locateName('enTRy2d.txt', ZipArchive::FL_NOCASE|ZipArchive::FL_NODIR) . "\n";
    $zip->close();

    ?>

El ejemplo anterior mostrará:

    El ejemplo de arriba mostrará la salida:

    0

    1
    2

# ZipArchive::open

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::open — Abrir un fichero de archivo en formato ZIP

### Descripción

public function ZipArchive::open(string `$filename`, int `$flags` = 0): bool|int

Abre un archivo zip nuevo o existente para leer, escribir o modificar.

Desde libzip 1.6.0, un archivo vacío ya no es un archivo válido.

### Parámetros

`filename`
  El nombre del fichero del archivo ZIP para ser abierto.
`flags`

  El modo a utilizar para abrir el archivo.

  - `ZipArchive::OVERWRITE`
  - `ZipArchive::CREATE`
  - `ZipArchive::RDONLY`
  - `ZipArchive::EXCL`
  - `ZipArchive::CHECKCONS`

### Valores devueltos

Devuelve `true` en caso de éxito, `false` o uno de los siguientes códigos de error en caso de error:

`ZipArchive::ER_EXISTS`
  El fichero ya existe.
`ZipArchive::ER_INCONS`
  Archivo zip inconsistente.
`ZipArchive::ER_INVAL`
  Argumento no válido.
`ZipArchive::ER_MEMORY`
  Falló malloc.
`ZipArchive::ER_NOENT`
  No existe el fichero.
`ZipArchive::ER_NOZIP`
  No es un archivo zip.
`ZipArchive::ER_OPEN`
  No se puede abrir el fichero.
`ZipArchive::ER_READ`
  Error de lectura.
`ZipArchive::ER_SEEK`
  Error de búsqueda.

### Ejemplos

Ejemplo #1 Abrir y extraer

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        echo 'ok';
        $zip->extractTo('test');
        $zip->close();
    } else {
        echo 'falló, código:' . $res;
    }
    ?>

Ejemplo #2 Crear un fichero

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('test.txt', 'el contenido del fichero va aquí');
        $zip->addFile('data.txt', 'entryname.txt');
        $zip->close();
        echo 'ok';
    } else {
        echo 'falló';
    }
    ?>

Ejemplo #3 Crear un fichero temporal

    <?php
    $name = tempnam(sys_get_temp_dir(), "FOO");
    $zip = new ZipArchive;
    $res = $zip->open($name, ZipArchive::OVERWRITE); /* truncate as empty file is not valid */
    if ($res === TRUE) {
        $zip->addFile('data.txt', 'entryname.txt');
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

# ZipArchive::registerCancelCallback

(PHP >= 8.0.0, PECL zip >= 1.17.0)

ZipArchive::registerCancelCallback — Registrar una llamada para permitir la cancelación durante el cierre del archivo

### Descripción

public function ZipArchive::registerCancelCallback(callable `$callback`): bool

Registrar una función `callback` para permitir la cancelación durante el cierre del archivo.

### Parámetros

`callback`
  Si esta función vuelve a 0, la operación continuará, otro valor será cancelado.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Este ejemplo crea un archivo ZIP php.zip y cancela la operación en alguna condición de operación.

Ejemplo #1 Archivar un fichero

    <?php
    $zip = new ZipArchive();
    if ($zip->open('php.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE)) {
        $zip->addFile(PHP_BINARY, 'php');
        $zip->registerCancelCallback(function () {
            return ($someruncondition ? -1 : 0);
        });
        $zip->close();
    }

### Notas

> Nota: Esta función sólo está disponible si se construye con libzip ≥ 1.6.0.

### Ver también

- ZipArchive::registerProgressCallback() - Registra una llamada para proporcionar actualizaciones durante el cierre del archivo

# ZipArchive::registerProgressCallback

(PHP >= 8.0.0, PECL zip >= 1.17.0)

ZipArchive::registerProgressCallback — Registra una llamada para proporcionar actualizaciones durante el cierre del archivo

### Descripción

public function ZipArchive::registerProgressCallback(float `$rate`, callable `$callback`): bool

Registra una función `callback` para proporcionar actualizaciones durante el cierre del archivo.

### Parámetros

`rate`
  Cambiar entre cada llamada de la devolución de llamada (de 0.0 a 1.0).
`callback`
  Esta función recibirá el actual `state` como un float (de 0.0 a 1.0).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Este ejemplo crea un archivo ZIP php.zip y muestra la progresión.

Ejemplo #1 Archivar un fichero

    $zip = new ZipArchive();
    if ($zip->open('php.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE)) {
        $zip->addFile(PHP_BINARY, 'php');
        $zip->registerProgressCallback(0.05, function ($r) {
            printf("%d%%\n", $r * 100);
        });
        $zip->close();
    }

### Notas

> Nota: Esta función sólo está disponible si se construye con libzip ≥ 1.3.0.

### Ver también

- ZipArchive::registerCancelCallback() - Registrar una llamada para permitir la cancelación durante el cierre del archivo

# ZipArchive::renameIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::renameIndex — Renombra una entrada definida por su índice

### Descripción

public function ZipArchive::renameIndex(int `$index`, string `$new_name`): bool

Renombra una entrada definida por su índice.

### Parámetros

`index`
  Índice de la entrada a renombrar.
`new_name`
  Nombre nuevo.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Renombra una entrada

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->renameIndex(2,'newname.txt');
        $zip->close();
    } else {
        echo 'falló, código:' . $res;
    }
    ?>

# ZipArchive::renameName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::renameName — Renombra una entrada definida por su nombre

### Descripción

public function ZipArchive::renameName(string `$name`, string `$new_name`): bool

Renombra una entrada definida por su nombre.

### Parámetros

`name`
  Nombre de la entrada a renombrar.
`new_name`
  Nombre nuevo.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Renombra una entrada

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->renameName('currentname.txt','newname.txt');
        $zip->close();
    } else {
        echo 'falló, código:' . $res;
    }
    ?>

# ZipArchive::replaceFile

(PHP >= 8.0.0, PECL zip >= 1.18.0)

ZipArchive::replaceFile — Reemplaza fichero en el archivo ZIP con una ruta determinada

### Descripción

public function ZipArchive::replaceFile(
string `$filepath`,
int `$index`,
int `$start` = 0,
int `$length` = `ZipArchive::LENGTH_TO_END`,
int `$flags` = 0
): bool

Reemplaza fichero en el archivo ZIP con una ruta determinada.

> Nota: Para una portabilidad máxima, se recomienda siempre utilizar barras oblicuas (`/`) como separador de directorio en los nombres de archivos zip.

### Parámetros

`filepath`
  La ruta del archivo a añadir.
`index`
  El índice del archivo a reemplazar, su nombre no ha cambiado.
`start`
  Para la copia parcial, posición de inicio.
`length`
  Para copia parcial, longitud a copiar, si `ZipArchive::LENGTH_TO_END` (0) se usa el tamaño del archivo, si `ZipArchive::LENGTH_UNCHECKED` se usa todo el archivo (comenzando desde `start`).
`flags`
  Máscara de bits compuesta por `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`, `ZipArchive::FL_OPEN_FILE_NOW`. El comportamiento de estas constantes se describe en la página de constantes ZIP.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0, PECL zip 1.22.1 | Se añadio `ZipArchive::FL_OPEN_FILE_NOW`.
8.3.0, PECL zip 1.22.2 | Se añadieron `ZipArchive::LENGTH_TO_END` y `ZipArchive::LENGTH_UNCHECKED`.

### Ejemplos

Este ejemplo abre un archivo ZIP test.zip y sustituye la entrada del índice 1 con /path/to/index.txt.

Ejemplo #1 Abrir y reemplazar

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->replaceFile('/path/to/index.txt', 1);
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

### Ver también

- ZipArchive::addFile() - Añade un fichero al archivo ZIP para la ruta dada

# ZipArchive::setArchiveComment

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setArchiveComment — Establece el comentario de un archivo ZIP

### Descripción

public function ZipArchive::setArchiveComment(string `$comment`): bool

Establece el comentario de un archivo ZIP.

### Parámetros

`comment`
  Los contenidos del comentario.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Crear un archivo y establecer un comentario

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('test.txt', 'El contenido del fichero va aquí');
        $zip->setArchiveComment('nuevo comentario del archivo');
        $zip->close();
        echo 'ok';
    } else {
        echo 'falló';
    }
    ?>

# ZipArchive::setArchiveFlag

(PHP >= 8.3.0, PECL zip >= 1.22.0)

ZipArchive::setArchiveFlag — Define una bandera global de un archivo ZIP

### Descripción

public function ZipArchive::setArchiveFlag(int `$flag`, int `$value`): bool

Define una bandera global de un archivo ZIP.

### Parámetros

`flag`

  La bandera global a cambiar, entre las constantes `AFL_*`.

  - `ZipArchive::AFL_WANT_TORRENTZIP`
  - `ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE`
`value`
  El nuevo valor de la bandera.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Crear un archivo torrentzip

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->setArchiveFlag(ZipArchive::AFL_WANT_TORRENTZIP, 1);
        $zip->addFromString('test.txt', 'file content goes here');
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

### Ver también

- ZipArchive::getArchiveFlag() - Devuelve el valor de una bandera global del archivo

# ZipArchive::setCommentIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setCommentIndex — Establece el comentario de una entrada definido por su índice

### Descripción

public function ZipArchive::setCommentIndex(int `$index`, string `$comment`): bool

Establece el comentario de una entrada definido por su índice.

### Parámetros

`index`
  Índice de la entrada.
`comment`
  Los contenidos del comentario.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Abrir un archivo y establecer un comentario para una entrada

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->setCommentIndex(2, 'comentario de la entrada nueva');
        $zip->close();
        echo 'ok';
    } else {
        echo 'falló';
    }
    ?>

# ZipArchive::setCommentName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setCommentName — Establece el comentario de una entrada definido por su nombre

### Descripción

public function ZipArchive::setCommentName(string `$name`, string `$comment`): bool

Establece el comentario de una entrada definido por su nombre.

### Parámetros

`name`
  Nombre de la entrada.
`comment`
  Los contenidos del comentario.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Abrir un archivo y establecer un comentario para una entrada

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->setCommentName('entry1.txt', 'comentario de la entrada nueva');
        $zip->close();
        echo 'ok';
    } else {
        echo 'falló';
    }
    ?>

# ZipArchive::setCompressionIndex

(PHP 7, PHP 8, PECL zip >= 1.13.0)

ZipArchive::setCompressionIndex — Establecer el método de compresión de una entrada definida por su índice

### Descripción

public function ZipArchive::setCompressionIndex(int `$index`, int `$method`, int `$compflags` = 0): bool

Establecer el método de compresión de una entrada definida por su índice.

### Parámetros

`index`
  El índice de la entrada.
`method`
  El método de compresión, una de las constantes `ZipArchive::CM_*`.
`compflags`
  Nivel de compresión.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Añadir ficheros con diferentes métodos de compresión a un archivo

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('foo', 'Un texto');
        $zip->addFromString('bar', 'Otro texto');
        $zip->setCompressionIndex(0, ZipArchive::CM_STORE);
        $zip->setCompressionIndex(1, ZipArchive::CM_DEFLATE);
        $zip->close();
        echo 'ok';
    } else {
        echo 'fallo';
    }
    ?>

# ZipArchive::setCompressionName

(PHP 7, PHP 8, PECL zip >= 1.13.0)

ZipArchive::setCompressionName — Establecer el método de compresión de una entrada definida por su nombre

### Descripción

public function ZipArchive::setCompressionName(string `$name`, int `$method`, int `$compflags` = 0): bool

Establecer el método de compresión de una entrada definida por su nombre.

### Parámetros

`name`
  El nombre de la entrada.
`method`
  El método de compresión. Una de las constantes `ZipArchive::CM_*`.
`compflags`
  Nivel de compresión.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Añadir ficheros con diferentes métodos de compresión a un archivo

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('foo', 'Un texto');
        $zip->addFromString('bar', 'Otro texto');
        $zip->setCompressionName('foo', ZipArchive::CM_STORE);
        $zip->setCompressionName('bar', ZipArchive::CM_DEFLATE);
        $zip->close();
        echo 'ok';
    } else {
        echo 'fallo';
    }
    ?>

Ejemplo #2 Añadir fichero y establecer el método de compresión

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFile('foo.jpg', 'bar.jpg');
        $zip->setCompressionName('bar.jpg', ZipArchive::CM_XZ);
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

# ZipArchive::setEncryptionIndex

(PHP >= 7.2.0, PHP 8, PECL zip >= 1.14.0)

ZipArchive::setEncryptionIndex — Establece el método de cifrado de una entrada definida por su índice

### Descripción

public function ZipArchive::setEncryptionIndex(int `$index`, int `$method`, #[\SensitiveParameter]?string `$password` = `null`): bool

Establece el método de cifrado de una entrada definida por su índice.

### Parámetros

`index`
  Índice de la entrada.
`method`
  El método de cifrado definido por una de las constantes ZipArchive::EM_.
`password`
  Contraseña opcional, se utiliza por defecto cuando falta.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `password` ahora es anulable.

### Notas

> Nota: Esta función sólo está disponible si se construye con libzip ≥ 1.2.0.

### Ver también

- ZipArchive::setPassword() - Establece la contraseña para el archivo activo
- ZipArchive::setEncryptionName() - Establece el método de cifrado de una entrada definida por su nombre

# ZipArchive::setEncryptionName

(PHP >= 7.2.0, PHP 8, PECL zip >= 1.14.0)

ZipArchive::setEncryptionName — Establece el método de cifrado de una entrada definida por su nombre

### Descripción

public function ZipArchive::setEncryptionName(string `$name`, int `$method`, #[\SensitiveParameter]?string `$password` = `null`): bool

Establece el método de cifrado de una entrada definida por su nombre.

### Parámetros

`name`
  Nombre de la entrada.
`method`
  El método de encriptación definido por una de las constantes ZipArchive::EM_.
`password`
  Contraseña opcional, se utiliza por defecto cuando falta.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `password` ahora es anulable.

### Ejemplos

Este ejemplo crea un archivo ZIP test.zip y añade al archivo test.txt encriptado usando el método AES 256.

Ejemplo #1 Archivar y encriptar un archivo

    <?php
    $zip = new ZipArchive();
    if ($zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
        $zip->setPassword('secret');
        $zip->addFile('text.txt');
        $zip->setEncryptionName('text.txt', ZipArchive::EM_AES_256);
        $zip->close();
        echo "Ok\n";
    } else {
        echo "KO\n";
    }
    ?>

### Notas

> Nota: Esta función sólo está disponible si se construye con libzip ≥ 1.2.0.

### Ver también

- ZipArchive::setPassword() - Establece la contraseña para el archivo activo
- ZipArchive::setEncryptionIndex() - Establece el método de cifrado de una entrada definida por su índice

# ZipArchive::setExternalAttributesIndex

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setExternalAttributesIndex — Establece los atributos externos de una entrada definida por su índice

### Descripción

public function ZipArchive::setExternalAttributesIndex(
int `$index`,
int `$opsys`,
int `$attr`,
int `$flags` = 0
): bool

Establece los atributos externos de una entrada definida por su índice.

### Parámetros

`index`
  El índice de la entrada.
`opsys`
  El código del sistema operativo definido por una de las constantes ZipArchive::OPSYS_.
`attr`
  Los atributos externos. El valor depende del sistema operativo.
`flags`
  Banderas opcionales. Actualmente no se utiliza.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# ZipArchive::setExternalAttributesName

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setExternalAttributesName — Establece los atributos externos de una entrada definida por su nombre

### Descripción

public function ZipArchive::setExternalAttributesName(
string `$name`,
int `$opsys`,
int `$attr`,
int `$flags` = 0
): bool

Establece los atributos externos de una entrada definida por su nombre.

### Parámetros

`name`
  El nombre de la entrada.
`opsys`
  El código del sistema operativo definido por una de las constantes ZipArchive::OPSYS_.
`attr`
  Los atributos externos. El valor depende del sistema operativo.
`flags`
  Banderas opcionales. Actualmente no se utiliza.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Este ejemplo abre un archivo comprimido ZIP test.zip y añade el fichero test.txt con sus permisos Unix como atributos externos.

Ejemplo #1 Archivar un fichero, con sus permisos Unix

    <?php
    $zip = new ZipArchive();
    $stat = stat($filename='test.txt');
    if (is_array($stat) && $zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
        $zip->addFile($filename);
        $zip->setExternalAttributesName($filename, ZipArchive::OPSYS_UNIX, $stat['mode'] << 16);
        $zip->close();
        echo "Ok\n";
    } else {
        echo "KO\n";
    }
    ?>

# ZipArchive::setMtimeIndex

(PHP >= 8.0.0, PECL zip >= 1.16.0)

ZipArchive::setMtimeIndex — Establece el tiempo de modificación de una entrada definido por su índice

### Descripción

public function ZipArchive::setMtimeIndex(int `$index`, int `$timestamp`, int `$flags` = 0): bool

Establece el tiempo de modificación de una entrada definido por su índice.

### Parámetros

`index`
  Índice de la entrada.
`timestamp`
  La hora de modificación (unix timestamp) del archivo.
`flags`
  Flags opcionales, sin usar por ahora.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Este ejemplo crea un archivo ZIP test.zip y añade al archivo test.txt con su fecha de modificación.

Ejemplo #1 Archivar un fichero

    <?php
    $zip = new ZipArchive();
    if ($zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
        $zip->addFile('text.txt');
        $zip->setMtimeIndex(0, mktime(0,0,0,12,25,2019));
        $zip->close();
        echo "Ok\n";
    } else {
        echo "KO\n";
    }
    ?>

### Notas

> Nota: Esta función sólo está disponible si se construye con libzip ≥ 1.0.0.

### Ver también

- ZipArchive::setMtimeName() - Establece la hora de modificación de una entrada definida por su nombre

# ZipArchive::setMtimeName

(PHP >= 8.0.0, PECL zip >= 1.16.0)

ZipArchive::setMtimeName — Establece la hora de modificación de una entrada definida por su nombre

### Descripción

public function ZipArchive::setMtimeName(string `$name`, int `$timestamp`, int `$flags` = 0): bool

Establece la hora de modificación de una entrada definida por su nombre.

### Parámetros

`name`
  Nombre de la entrada.
`timestamp`
  La hora de modificación (unix timestamp) del archivo.
`flags`
  Flags opcionales, sin usar por ahora.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Este ejemplo crea un archivo ZIP test.zip y añade al archivo test.txt con su fecha de modificación.

Ejemplo #1 Archivar un fichero

    <?php
    $zip = new ZipArchive();
    if ($zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
        $zip->addFile('text.txt');
        $zip->setMtimeName('text.txt', mktime(0,0,0,12,25,2019));
        $zip->close();
        echo "Ok\n";
    } else {
        echo "KO\n";
    }
    ?>

### Notas

> Nota: Esta función sólo está disponible si se construye con libzip ≥ 1.0.0.

### Ver también

- ZipArchive::setMtimeIndex() - Establece el tiempo de modificación de una entrada definido por su índice

# ZipArchive::setPassword

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setPassword — Establece la contraseña para el archivo activo

### Descripción

public function ZipArchive::setPassword(#[\SensitiveParameter]string `$password`): bool

Establece la contraseña para el archivo activo.

### Parámetros

`password`
  La contraseña a emplear para el archivo.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Notas

> Nota: A partir de PHP 7.2.0 y libzip 1.2.0 la contraseña se utiliza para descomprimir el archivo, y también es la contraseña por omisión para ZipArchive::setEncryptionName() y ZipArchive::setEncryptionIndex(). Anteriormente, esta función sólo establecía la contraseña que se usaría para descomprimir el archivo; No se convirtió en un no protegido con contraseña ZipArchive en un protegido con contraseña ZipArchive.

### Ver también

- ZipArchive::setEncryptionIndex() - Establece el método de cifrado de una entrada definida por su índice
- ZipArchive::setEncryptionName() - Establece el método de cifrado de una entrada definida por su nombre

# ZipArchive::statIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::statIndex — Obtiene los detalles de una entrada definida por su índice

### Descripción

public function ZipArchive::statIndex(int `$index`, int `$flags` = 0): array|false

La función obtiene información acerca de la entrada definida por su índice.

### Parámetros

`index`
  Índice de la entrada
`flags`
  `ZipArchive::FL_UNCHANGED` podría ser puesto con otros OR lógicos en él para pedir información acerca del fichero original en el archivo, ignorando cualquiera de los cambios hechos.

### Valores devueltos

Devuelve una matríz conteniendo los detalles de la entrada, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Volcar la información estadística de una entrada

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        print_r($zip->statIndex(3));
        $zip->close();
    } else {
        echo 'falló, código:' . $res;
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [name] => foobar/baz
        [index] => 3
        [crc] => 499465816
        [size] => 27
        [mtime] => 1123164748
        [comp_size] => 24
        [comp_method] => 8
    )

# ZipArchive::statName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::statName — Obtener los detalles de una entrada definida por su nombre

### Descripción

public function ZipArchive::statName(string `$name`, int `$flags` = 0): array|false

La función obtiene información acerca de la entrada definida por su nombre.

### Parámetros

`name`
  Nombre de la entrada
`flags`

  El argumento flags especifica cómo la búsqueda del nombre debería se hecho. También, `ZipArchive::FL_UNCHANGED` podría ser puesta con otros OR en él para solicitar la información acerca del fichero original en el archivo, ignorando cualquier cambio realizado.

  - `ZipArchive::FL_NOCASE`
  - `ZipArchive::FL_NODIR`
  - `ZipArchive::FL_UNCHANGED`

### Valores devueltos

Devuelve una matríz que contenie detalles de la entrada o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Volcar la información estadística de una entrada

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        print_r($zip->statName('foobar/baz'));
        $zip->close();
    } else {
        echo 'falló, código:' . $res;
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [name] => foobar/baz
        [index] => 3
        [crc] => 499465816
        [size] => 27
        [mtime] => 1123164748
        [comp_size] => 24
        [comp_method] => 8
    )

# ZipArchive::unchangeAll

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeAll — Deshacer todos los cambios hechos en el archivo

### Descripción

public function ZipArchive::unchangeAll(): bool

Deshacer todos los cambios hechos en el archivo.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# ZipArchive::unchangeArchive

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeArchive — Revertir todos los cambios globales hechos en el archivo

### Descripción

public function ZipArchive::unchangeArchive(): bool

Revertir todos los cambios globales en el archivo. Por ahora, esto solamente revierte los cambios de los comentarios del archivo.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# ZipArchive::unchangeIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeIndex — Revertir todos los cambios hechos a una entrada en el índice dado

### Descripción

public function ZipArchive::unchangeIndex(int `$index`): bool

Revertir todos los cambios hechos a una entrada en el índice dado.

### Parámetros

`index`
  Índice de la entrada.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# ZipArchive::unchangeName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::unchangeName — Deshace todos los cambios realizados a una entrada con un nombre dado

### Descripción

public function ZipArchive::unchangeName(string `$name`): bool

Deshacer todos los cambios hechos a una entrada.

### Parámetros

`name`
  Nombre de la entrada.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

## Tabla de contenidos

- ZipArchive::addEmptyDir — Añadir un nuevo directorio
- ZipArchive::addFile — Añade un fichero al archivo ZIP para la ruta dada
- ZipArchive::addFromString — Añadir un fichero al archivo ZIP usando su contenido
- ZipArchive::addGlob — Añadir ficheros de un directorio mediante un patrón glob
- ZipArchive::addPattern — Añade ficheros de un directorio a partir de un patrón PCRE
- ZipArchive::clearError — Borra el mensaje de error, los mensajes del sistema y/o zip
- ZipArchive::close — Cierra el fichero activo (abierto o el nuevo creado)
- ZipArchive::count — Cuenta el número de archivos en el archivo
- ZipArchive::deleteIndex — Elimina una entrada en el archivo usando su índice
- ZipArchive::deleteName — Elimina una entrada en el archivo por su nombre
- ZipArchive::extractTo — Extraer el contenido del archivo
- ZipArchive::getArchiveComment — Devuelve el comentario del archivo ZIP
- ZipArchive::getArchiveFlag — Devuelve el valor de una bandera global del archivo
- ZipArchive::getCommentIndex — Devuelve el comentario de una entrada usando la entrada díndice
- ZipArchive::getCommentName — Devuelve el comentario de una entrada usando el nombre de la entrada
- ZipArchive::getExternalAttributesIndex — Obtener los atributos externos de una entrada definida por su índice
- ZipArchive::getExternalAttributesName — Obtener los atributos externos de una entrada definida por su nombre
- ZipArchive::getFromIndex — Devuelve el contenido de la entrada usando su índice
- ZipArchive::getFromName — Devuelve el contenido de la entrada utilizando su nombre
- ZipArchive::getNameIndex — Devuelve el nombre de una entrada utilizando su índice
- ZipArchive::getStatusString — Devuelve mensajes de: estado de error, de sistema y/o mensajes de zip
- ZipArchive::getStream — Obtener un manejador de fichero para la entrada definido por su nombre (sólo lectura)
- ZipArchive::getStreamIndex — Recupera un manejador de archivo para la entrada definida por su índice (solo lectura)
- ZipArchive::getStreamName — Recupera un manejador de archivo para la entrada definida por su nombre (solo lectura)
- ZipArchive::isCompressionMethodSupported — Verifica si un método de compresión es soportado por libzip
- ZipArchive::isEncryptionMethodSupported — Verifica si un método de cifrado es soportado por libzip
- ZipArchive::locateName — Devuelve el índice de la entrada en el archivo
- ZipArchive::open — Abrir un fichero de archivo en formato ZIP
- ZipArchive::registerCancelCallback — Registrar una llamada para permitir la cancelación durante el cierre del archivo
- ZipArchive::registerProgressCallback — Registra una llamada para proporcionar actualizaciones durante el cierre del archivo
- ZipArchive::renameIndex — Renombra una entrada definida por su índice
- ZipArchive::renameName — Renombra una entrada definida por su nombre
- ZipArchive::replaceFile — Reemplaza fichero en el archivo ZIP con una ruta determinada
- ZipArchive::setArchiveComment — Establece el comentario de un archivo ZIP
- ZipArchive::setArchiveFlag — Define una bandera global de un archivo ZIP
- ZipArchive::setCommentIndex — Establece el comentario de una entrada definido por su índice
- ZipArchive::setCommentName — Establece el comentario de una entrada definido por su nombre
- ZipArchive::setCompressionIndex — Establecer el método de compresión de una entrada definida por su índice
- ZipArchive::setCompressionName — Establecer el método de compresión de una entrada definida por su nombre
- ZipArchive::setEncryptionIndex — Establece el método de cifrado de una entrada definida por su índice
- ZipArchive::setEncryptionName — Establece el método de cifrado de una entrada definida por su nombre
- ZipArchive::setExternalAttributesIndex — Establece los atributos externos de una entrada definida por su índice
- ZipArchive::setExternalAttributesName — Establece los atributos externos de una entrada definida por su nombre
- ZipArchive::setMtimeIndex — Establece el tiempo de modificación de una entrada definido por su índice
- ZipArchive::setMtimeName — Establece la hora de modificación de una entrada definida por su nombre
- ZipArchive::setPassword — Establece la contraseña para el archivo activo
- ZipArchive::statIndex — Obtiene los detalles de una entrada definida por su índice
- ZipArchive::statName — Obtener los detalles de una entrada definida por su nombre
- ZipArchive::unchangeAll — Deshacer todos los cambios hechos en el archivo
- ZipArchive::unchangeArchive — Revertir todos los cambios globales hechos en el archivo
- ZipArchive::unchangeIndex — Revertir todos los cambios hechos a una entrada en el índice dado
- ZipArchive::unchangeName — Deshace todos los cambios realizados a una entrada con un nombre dado

# Funciones Zip

Advertencia

La API mediante funciones está obsoleta a partir de PHP 8.0.0. Debe usarse ZipArchive en su lugar.

# zip_close

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_close — Cierra un archivo Zip

Advertencia

Esta función está OBSOLETA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function zip_close(resource `$zip`): void

zip_close() cierra el archivo ZIP dado.

### Parámetros

`zip`
  Un archivo ZIP previamente abierto con la función zip_open().

### Valores devueltos

No se retorna ningún valor.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función está obsoleta en favor de la API orientada a objetos, ver ZipArchive::close().

### Ver también

- zip_open() - Abre un archivo ZIP
- zip_read() - Lee la siguiente entrada en un archivo ZIP

# zip_entry_close

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_close — Cierra un directorio de archivo

Advertencia

Esta función está OBSOLETA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function zip_entry_close(resource `$zip_entry`): bool

zip_entry_close() cierra un directorio de archivo dado.

### Parámetros

`zip_entry`
  Un directorio de archivo previamente abierto con la función zip_entry_open().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función está obsoleta en favor de la API orientada a objetos.

### Ver también

- zip_entry_open() - Abre un directorio de archivo para lectura
- zip_entry_read() - Lee el contenido de un archivo en un directorio

# zip_entry_compressedsize

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_compressedsize — Lee el tamaño comprimido de un directorio de archivo

Advertencia

Esta función está OBSOLETA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function zip_entry_compressedsize(resource `$zip_entry`): int|false

zip_entry_compressedsize() devuelve el tamaño comprimido de un directorio de archivo dado.

### Parámetros

`zip_entry`
  Un directorio de archivo devuelto por la función zip_read().

### Valores devueltos

El tamaño comprimido, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función está obsoleta en favor de la API orientada a objetos, ver ZipArchive::statIndex().

### Ver también

- zip_open() - Abre un archivo ZIP
- zip_read() - Lee la siguiente entrada en un archivo ZIP

# zip_entry_compressionmethod

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_compressionmethod — Lee el método de compresión usado en un directorio de archivo

Advertencia

Esta función está OBSOLETA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function zip_entry_compressionmethod(resource `$zip_entry`): string|false

zip_entry_compressionmethod() devuelve el método de compresión usado en el directorio de archivo especificado por `zip_entry`.

### Parámetros

`zip_entry`
  Un directorio de archivo devuelto por la función zip_read().

### Valores devueltos

El método de compresión, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función está obsoleta en favor de la API orientada a objetos, ver ZipArchive::statIndex().

### Ver también

- zip_open() - Abre un archivo ZIP
- zip_read() - Lee la siguiente entrada en un archivo ZIP

# zip_entry_filesize

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_filesize — Lee el tamaño descomprimido de un directorio de archivo

Advertencia

Esta función está OBSOLETA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function zip_entry_filesize(resource `$zip_entry`): int|false

zip_entry_filesize() devuelve el tamaño descomprimido de un directorio de archivo dado.

### Parámetros

`zip_entry`
  Un directorio de archivo devuelto por la función zip_read().

### Valores devueltos

El tamaño descomprimido del directorio de archivo, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función está obsoleta en favor de la API orientada a objetos, ver ZipArchive::statIndex().

### Ver también

- zip_open() - Abre un archivo ZIP
- zip_read() - Lee la siguiente entrada en un archivo ZIP

# zip_entry_name

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_name — Lee el nombre de un directorio de archivo

Advertencia

Esta función está OBSOLETA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function zip_entry_name(resource `$zip_entry`): string|false

zip_entry_name() devuelve el nombre de un directorio de archivo dado.

### Parámetros

`zip_entry`
  Un directorio de archivo devuelto por la función zip_read().

### Valores devueltos

El nombre del directorio de archivo, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función está obsoleta en favor de la API orientada a objetos, ver ZipArchive::statIndex().

### Ver también

- zip_open() - Abre un archivo ZIP
- zip_read() - Lee la siguiente entrada en un archivo ZIP

# zip_entry_open

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_open — Abre un directorio de archivo para lectura

Advertencia

Esta función está OBSOLETA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function zip_entry_open(resource `$zip_dp`, resource `$zip_entry`, string `$mode` = "rb"): bool

zip_entry_open() abre un directorio en un archivo ZIP para lectura.

### Parámetros

`zip_dp`
  Un recurso válido devuelto por la función zip_open().
`zip_entry`
  Un directorio de archivo devuelto por la función zip_read().
`mode`
  Todos los métodos especificados en la documentación de la función fopen().

  > Nota: Actualmente, `mode` es ignorado y siempre vale `"rb"`. Esto se debe a que el soporte ZIP de PHP es solo de lectura.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

> Nota: A diferencia de fopen() y otras funciones de archivos, el valor devuelto por zip_entry_open() solo indica el resultado de la operación y no es necesario para la lectura o el cierre del archivo del directorio de archivo.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función está obsoleta en favor de la API orientada a objetos.

### Ver también

- zip_entry_close() - Cierra un directorio de archivo
- zip_entry_read() - Lee el contenido de un archivo en un directorio

# zip_entry_read

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_read — Lee el contenido de un archivo en un directorio

Advertencia

Esta función está OBSOLETA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function zip_entry_read(resource `$zip_entry`, int `$len` = 1024): string|false

zip_entry_read() lee en un directorio de archivo abierto.

### Parámetros

`zip_entry`
  Un directorio de archivo devuelto por la función zip_read().
`len`
  El número de bytes a devolver.

  > Nota: Esto debe ser el tamaño descomprimido que desea leer.

### Valores devueltos

Devuelve los datos leídos, una cadena vacía si se está al final del archivo, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función está obsoleta en favor de la API orientada a objetos, ver ZipArchive::getFromIndex().

### Ver también

- zip_entry_open() - Abre un directorio de archivo para lectura
- zip_entry_close() - Cierra un directorio de archivo
- zip_entry_filesize() - Lee el tamaño descomprimido de un directorio de archivo

# zip_open

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_open — Abre un archivo ZIP

Advertencia

Esta función está OBSOLETA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function zip_open(string `$filename`): resource|int|false

zip_open() abre un nuevo archivo ZIP para lectura.

### Parámetros

`filename`
  El nombre del archivo ZIP a abrir.

### Valores devueltos

Devuelve un recurso a utilizar más tarde con las funciones zip_read() y zip_close(), o bien devuelve `false` o el número de error si el parámetro `filename` no existe o en caso de otro error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función está obsoleta en favor de la API orientada a objetos, ver ZipArchive::open().

### Ver también

- zip_read() - Lee la siguiente entrada en un archivo ZIP
- zip_close() - Cierra un archivo Zip

# zip_read

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_read — Lee la siguiente entrada en un archivo ZIP

Advertencia

Esta función está OBSOLETA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function zip_read(resource `$zip`): resource|false

zip_read() lee la siguiente entrada en un archivo ZIP.

### Parámetros

`zip`
  Un archivo ZIP previamente abierto con la función zip_open().

### Valores devueltos

Devuelve un recurso de entrada de directorio para usar más tarde con las funciones `zip_entry_...`, o `false` si no hay más entradas para leer, o un código de error si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función está obsoleta en favor de la API orientada a objetos, ver ZipArchive::statIndex().

### Ver también

- zip_open() - Abre un archivo ZIP
- zip_close() - Cierra un archivo Zip
- zip_entry_open() - Abre un directorio de archivo para lectura
- zip_entry_read() - Lee el contenido de un archivo en un directorio

## Tabla de contenidos

- zip_close — Cierra un archivo Zip
- zip_entry_close — Cierra un directorio de archivo
- zip_entry_compressedsize — Lee el tamaño comprimido de un directorio de archivo
- zip_entry_compressionmethod — Lee el método de compresión usado en un directorio de archivo
- zip_entry_filesize — Lee el tamaño descomprimido de un directorio de archivo
- zip_entry_name — Lee el nombre de un directorio de archivo
- zip_entry_open — Abre un directorio de archivo para lectura
- zip_entry_read — Lee el contenido de un archivo en un directorio
- zip_open — Abre un archivo ZIP
- zip_read — Lee la siguiente entrada en un archivo ZIP

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Tipos de recursos
- Constantes predefinidas
- Ejemplos
- ZipArchive — La clase ZipArchive
  - ZipArchive::addEmptyDir — Añadir un nuevo directorio
  - ZipArchive::addFile — Añade un fichero al archivo ZIP para la ruta dada
  - ZipArchive::addFromString — Añadir un fichero al archivo ZIP usando su contenido
  - ZipArchive::addGlob — Añadir ficheros de un directorio mediante un patrón glob
  - ZipArchive::addPattern — Añade ficheros de un directorio a partir de un patrón PCRE
  - ZipArchive::clearError — Borra el mensaje de error, los mensajes del sistema y/o zip
  - ZipArchive::close — Cierra el fichero activo (abierto o el nuevo creado)
  - ZipArchive::count — Cuenta el número de archivos en el archivo
  - ZipArchive::deleteIndex — Elimina una entrada en el archivo usando su índice
  - ZipArchive::deleteName — Elimina una entrada en el archivo por su nombre
  - ZipArchive::extractTo — Extraer el contenido del archivo
  - ZipArchive::getArchiveComment — Devuelve el comentario del archivo ZIP
  - ZipArchive::getArchiveFlag — Devuelve el valor de una bandera global del archivo
  - ZipArchive::getCommentIndex — Devuelve el comentario de una entrada usando la entrada díndice
  - ZipArchive::getCommentName — Devuelve el comentario de una entrada usando el nombre de la entrada
  - ZipArchive::getExternalAttributesIndex — Obtener los atributos externos de una entrada definida por su índice
  - ZipArchive::getExternalAttributesName — Obtener los atributos externos de una entrada definida por su nombre
  - ZipArchive::getFromIndex — Devuelve el contenido de la entrada usando su índice
  - ZipArchive::getFromName — Devuelve el contenido de la entrada utilizando su nombre
  - ZipArchive::getNameIndex — Devuelve el nombre de una entrada utilizando su índice
  - ZipArchive::getStatusString — Devuelve mensajes de: estado de error, de sistema y/o mensajes de zip
  - ZipArchive::getStream — Obtener un manejador de fichero para la entrada definido por su nombre (sólo lectura)
  - ZipArchive::getStreamIndex — Recupera un manejador de archivo para la entrada definida por su índice (solo lectura)
  - ZipArchive::getStreamName — Recupera un manejador de archivo para la entrada definida por su nombre (solo lectura)
  - ZipArchive::isCompressionMethodSupported — Verifica si un método de compresión es soportado por libzip
  - ZipArchive::isEncryptionMethodSupported — Verifica si un método de cifrado es soportado por libzip
  - ZipArchive::locateName — Devuelve el índice de la entrada en el archivo
  - ZipArchive::open — Abrir un fichero de archivo en formato ZIP
  - ZipArchive::registerCancelCallback — Registrar una llamada para permitir la cancelación durante el cierre del archivo
  - ZipArchive::registerProgressCallback — Registra una llamada para proporcionar actualizaciones durante el cierre del archivo
  - ZipArchive::renameIndex — Renombra una entrada definida por su índice
  - ZipArchive::renameName — Renombra una entrada definida por su nombre
  - ZipArchive::replaceFile — Reemplaza fichero en el archivo ZIP con una ruta determinada
  - ZipArchive::setArchiveComment — Establece el comentario de un archivo ZIP
  - ZipArchive::setArchiveFlag — Define una bandera global de un archivo ZIP
  - ZipArchive::setCommentIndex — Establece el comentario de una entrada definido por su índice
  - ZipArchive::setCommentName — Establece el comentario de una entrada definido por su nombre
  - ZipArchive::setCompressionIndex — Establecer el método de compresión de una entrada definida por su índice
  - ZipArchive::setCompressionName — Establecer el método de compresión de una entrada definida por su nombre
  - ZipArchive::setEncryptionIndex — Establece el método de cifrado de una entrada definida por su índice
  - ZipArchive::setEncryptionName — Establece el método de cifrado de una entrada definida por su nombre
  - ZipArchive::setExternalAttributesIndex — Establece los atributos externos de una entrada definida por su índice
  - ZipArchive::setExternalAttributesName — Establece los atributos externos de una entrada definida por su nombre
  - ZipArchive::setMtimeIndex — Establece el tiempo de modificación de una entrada definido por su índice
  - ZipArchive::setMtimeName — Establece la hora de modificación de una entrada definida por su nombre
  - ZipArchive::setPassword — Establece la contraseña para el archivo activo
  - ZipArchive::statIndex — Obtiene los detalles de una entrada definida por su índice
  - ZipArchive::statName — Obtener los detalles de una entrada definida por su nombre
  - ZipArchive::unchangeAll — Deshacer todos los cambios hechos en el archivo
  - ZipArchive::unchangeArchive — Revertir todos los cambios globales hechos en el archivo
  - ZipArchive::unchangeIndex — Revertir todos los cambios hechos a una entrada en el índice dado
  - ZipArchive::unchangeName — Deshace todos los cambios realizados a una entrada con un nombre dado
- Funciones Zip
  - zip_close — Cierra un archivo Zip
  - zip_entry_close — Cierra un directorio de archivo
  - zip_entry_compressedsize — Lee el tamaño comprimido de un directorio de archivo
  - zip_entry_compressionmethod — Lee el método de compresión usado en un directorio de archivo
  - zip_entry_filesize — Lee el tamaño descomprimido de un directorio de archivo
  - zip_entry_name — Lee el nombre de un directorio de archivo
  - zip_entry_open — Abre un directorio de archivo para lectura
  - zip_entry_read — Lee el contenido de un archivo en un directorio
  - zip_open — Abre un archivo ZIP
  - zip_read — Lee la siguiente entrada en un archivo ZIP

# Compresión Zlib

# Introducción

Este módulo permite leer y escribir ficheros comprimidos con gzip (.gz) de forma transparente, a través de las versiones de la mayoría de las funciones de sistemas de ficheros que trabajan con ficheros comprimidos con gzip (y también con ficheros descomprimidos, pero no con sockets).

> Nota:

> PHP viene con una envoltura basada en fopen para ficheros .gz. Hay más información disponible en la sección sobre zlib://.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución
- Tipos de recursos

## Requerimientos

Este módulo usa las funciones de » zlib por Jean-loup Gailly y Mark Adler. A partir de PHP 8.4.0, la versión mínima de zlib requerida es 1.2.11. Antes de PHP 8.4.0, la versión mínima de zlib requerida era 1.2.0.4.

## Instalación

El soporte para Zlib en PHP no está activado por defecto. Es necesario configurar PHP con la opción --with-zlib[=DIR]

La versión Windows de PHP dispone del soporte automático de esta extensión. No es necesario añadir ninguna biblioteca adicional para disponer de estas funciones.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

La extensión zlib ofrece la opción de comprimir de manera trasparente las páginas sobre la marcha, si el navegador que hace la solicitud lo soporta. Por lo tanto hay tres opciones en el archivo de configuración php.ini.

Opciones de Configuración de Zlib
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
zlib.output_compression | "0" | `INI_ALL` |
zlib.output_compression_level | "-1" | `INI_ALL` |
zlib.output_handler | "" | `INI_ALL` |

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`zlib.output_compression` bool/int

  Para comprimir páginas transparentemente. Si esta opción está configurada en "On" en php.ini o en la configuración de Apache, las páginas serán comprimidas si el navegador envía un encabezado "Accept-Encoding: gzip" o "deflate". Los encabezados "Content-Encoding: gzip" (respectivamente "deflate") y "Vary: Accept-Encoding" serán agregados a la salida. En tiempo de ejecución, esto se puede configurar sólo antes de enviar cualquier salida.

  Esta opción también acepta valores enteros (integer) en lugar de boolean en "On"/"Off", usando esto se puede configurar el tamaño del buffer de salida (por defecto es 4KB).

  > Nota:

  > output_handler debe estar vacío si ésta se configura en 'On' ! De otra manera se debe usar `zlib.output_handler`.

`zlib.output_compression_level` int

  Nivel de compresión usado para la salida de la compresión transparente. Especifica un valor entre 0 (no comprimido) y 9 (máxima compresión). El valor por defecto es -1, que deja que el servidor decida cual nivel utilizar.

`zlib.output_handler` string

  No se pueden especificar manejadores adicionales de salida si zlib.output_compression está activada aquí. Esta configuración hace lo mismo que output_handler pero en un orden diferente.

## Tipos de recursos

Esta extensión define un recurso de archivo puntero retornado por gzopen(). Antes de PHP 8.0.0, `zlib.deflate` y `zlib.inflate` recursos también estaban definidos.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`FORCE_GZIP` (int)
`FORCE_DEFLATE` (int)
`ZLIB_ENCODING_RAW` (int)
  Algoritmo DEFLATE según RFC 1951.
`ZLIB_ENCODING_DEFLATE` (int)
  Algoritmo de compresión ZLIB según RFC 1950.
`ZLIB_ENCODING_GZIP` (int)
  Algoritmo GZIP según RFC 1952.
`ZLIB_FILTERED` (int)
`ZLIB_HUFFMAN_ONLY` (int)
`ZLIB_FIXED` (int)
`ZLIB_RLE` (int)
`ZLIB_DEFAULT_STRATEGY` (int)
`ZLIB_BLOCK` (int)
`ZLIB_NO_FLUSH` (int)
`ZLIB_PARTIAL_FLUSH` (int)
`ZLIB_SYNC_FLUSH` (int)
`ZLIB_FULL_FLUSH` (int)
`ZLIB_FINISH` (int)
`ZLIB_VERSION` (string)
  Número de versión de `zlib` como string.
`ZLIB_VERNUM` (int)
  Número de versión de `zlib` como int.
`ZLIB_OK` (int)
  No hay errores o información adicional de estado.
`ZLIB_STREAM_END` (int)
  El stream terminó exitosamente.
`ZLIB_NEED_DICT` (int)
  Se necesita un diccionario preestablecido.
`ZLIB_ERRNO` (int)
  Error en la operación de archivo.
`ZLIB_STREAM_ERROR` (int)
  El estado del stream es inconsistente o un parámetro es inválido.
`ZLIB_DATA_ERROR` (int)
  Los datos de entrada están corruptos.
`ZLIB_MEM_ERROR` (int)
  Memoria insuficiente.
`ZLIB_BUF_ERROR` (int)
  No se puede progresar debido a espacio de buffer insuficiente o finalización inesperada de un stream de entrada.
`ZLIB_VERSION_ERROR` (int)
  La versión de la biblioteca `zlib` es incompatible con la versión asumida por el llamador.

# Ejemplos

Este ejemplo abre un archivo temporal y escribe una cadena de prueba en él, entonces muestra el contenido de este archivo dos veces.

Ejemplo #1 Pequeño Ejemplo de Zlib

    <?php

    $filename = tempnam('/tmp', 'zlibtest') . '.gz';
    echo "<html>\n<head></head>\n<body>\n<pre>\n";
    $s = "Sólo una prueba, prueba, prueba, prueba, prueba, prueba!\n";

    // abre el archivo para escribir con compresión máxima
    $zp = gzopen($filename, "w9");

    // escribe la cadena en el archivo
    gzwrite($zp, $s);

    // cierra el archivo
    gzclose($zp);

    // abre el archivo para lectura
    $zp = gzopen($filename, "r");

    // lee el tercer carácter
    echo gzread($zp, 3);

    // salida hasta el fin del archivo y lo cierra
    gzpassthru($zp);
    gzclose($zp);

    echo "\n";

    // abre el archivo y muestra el contenido (por segunda vez).
    if (readgzfile($filename) != strlen($s)) {
            echo "Error con funciones de zlib!";
    }
    unlink($filename);
    echo "</pre>\n</body>\n</html>\n";

    ?>

Ejemplo #2 Trabajando con la API de compresión y descompresión increemental

    <?php
    // Perform GZIP compression:
    $deflateContext = deflate_init(ZLIB_ENCODING_GZIP);
    $compressed = deflate_add($deflateContext, "Data to compress", ZLIB_NO_FLUSH);
    $compressed .= deflate_add($deflateContext, ", more data", ZLIB_NO_FLUSH);
    $compressed .= deflate_add($deflateContext, ", and even more data!", ZLIB_FINISH);

    // Perform GZIP decompression:
    $inflateContext = inflate_init(ZLIB_ENCODING_GZIP);
    $uncompressed = inflate_add($inflateContext, $compressed, ZLIB_NO_FLUSH);
    $uncompressed .= inflate_add($inflateContext, NULL, ZLIB_FINISH);
    echo $uncompressed;
    ?>

El ejemplo anterior mostrará:

    Data to compress, more data, and even more data!

# Funciones de Zlib

# deflate_add

(PHP 7, PHP 8)

deflate_add — Comprime datos de manera incremental

### Descripción

function deflate_add(DeflateContext `$context`, string `$data`, int `$flush_mode` = `ZLIB_SYNC_FLUSH`): string|false

Comprime de manera incremental los datos en el contexto especificado.

### Parámetros

`context`

  Un contexto creado con deflate_init().

`data`

  Un fragmento de datos a comprimir.

`flush_mode`

  Una de las `ZLIB_BLOCK`, `ZLIB_NO_FLUSH`, `ZLIB_PARTIAL_FLUSH`, `ZLIB_SYNC_FLUSH` (por defecto), `ZLIB_FULL_FLUSH`, `ZLIB_FINISH`. Normalmente, querrá establecer `ZLIB_NO_FLUSH` para maximizar la compresión, y `ZLIB_FINISH` para terminar con el último fragmento de datos. Consulte el » manual de zlib para una descripción detallada de estas constantes.

### Valores devueltos

Devuelve un fragmento de datos comprimidos, o `false` si ocurre un error.

### Errores/Excepciones

Si se proporciona un argumento inválido, se genera un error de nivel `E_WARNING`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `context` ahora espera una instancia de DeflateContext; anteriormente se esperaba un recurso.

### Ver también

- deflate_init() - Inicializa un contexto de compresión incremental

# deflate_init

(PHP 7, PHP 8)

deflate_init — Inicializa un contexto de compresión incremental

### Descripción

function deflate_init(int `$encoding`, array|object `$options` = []): DeflateContext|false

Inicializa un contexto de compresión incremental utilizando el `encoding` especificado.

Es importante señalar que la opción `window` aquí solo define el tamaño de la ventana del algoritmo, diferente de los filtros zlib donde el mismo parámetro también define la codificación a utilizar; la codificación debe ser definida con el parámetro `encoding`.

Limitación: actualmente no hay manera de establecer la información del encabezado en un flujo comprimido GZIP, que se define como sigue: firma GZIP (`\x1f\x8B`); método de compresión (`\x08` == DEFLATE); 6 bytes nulos; el sistema operativo establecido en el sistema actual (`\x00` = Windows, `\x03` = Unix, etc.).

### Parámetros

`encoding`

  Una de las constantes `ZLIB_ENCODING_*`.

`options`

  Un array asociativo que puede contener los siguientes elementos:

  level

    El nivel de compresión en el rango -1..9; por defecto -1.

  memory

    El nivel de memoria de compresión en el rango 1..9; por defecto 8.

  window

    El tamaño de la ventana zlib (logarítmico) en el rango `8`..`15`; por defecto `15`. zlib cambia un tamaño de ventana de `8` a `9`, y a partir de zlib 1.2.8 falla con una advertencia, si se solicita un tamaño de ventana de `8` para `ZLIB_ENCODING_RAW` o `ZLIB_ENCODING_GZIP`.

  strategy

    Una de las `ZLIB_FILTERED`, `ZLIB_HUFFMAN_ONLY`, `ZLIB_RLE`, `ZLIB_FIXED` o `ZLIB_DEFAULT_STRATEGY` (por defecto).

  dictionary

    Un string o un array de strings del diccionario predefinido (por defecto: ningún diccionario predefinido).

### Valores devueltos

Devuelve un contexto de compresión (`zlib.deflate`) en caso de éxito, o `false` si ocurre un error.

### Errores/Excepciones

Si se pasa una opción inválida a `options` o si el contexto no pudo ser creado, se genera un error de nivel `E_WARNING`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función ahora devuelve una instancia de DeflateContext; anteriormente, se devolvía un resource.

### Ver también

- deflate_add() - Comprime datos de manera incremental
- inflate_init() - Inicializa un contexto de descompresión incremental

# gzclose

(PHP 4, PHP 5, PHP 7, PHP 8)

gzclose — Cierra el apuntador de un archivo gz abierto

### Descripción

function gzclose(resource `$stream`): bool

Cierra el apuntador del archivo gz dado.

### Parámetros

`stream`

  El apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente por gzopen().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de gzclose()

    <?php
    $gz = gzopen('somefile.gz','w9');
    gzputs ($gz, 'I was added to somefile.gz');
    gzclose($gz);
    ?>

### Ver también

- gzopen() - Abre un archivo gz

# gzcompress

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

gzcompress — Comprime una cadena

### Descripción

function gzcompress(string `$data`, int `$level` = -1, int `$encoding` = `ZLIB_ENCODING_DEFLATE`): string|false

Esta función comprime la cadena dada usando el formato de datos `ZLIB`.

Para detalles sobre el algoritmo de compresión ZLIB, ver el documento "» Especificación del formato de datos comprimidos ZLIB versión 3.3" (RFC 1950).

> Nota:

> Esto no es lo mismo que la compresión que gzip, la cuál incluye algunos encabezados de datos. Ver gzencode() para la compresión gzip.

### Parámetros

`data`

  Los datos a comprimir.

`level`

  El nivel de compresión. Se puede dar como 0 para ninguna compresión, hasta 9 para la máxima compresión.

  Si se utiliza -1, se usará la compresión por defecto de la librería zlib la cual es 6.

`encoding`

  Una de las constentes `ZLIB_ENCODING_*`.

### Valores devueltos

La cadena comprimida o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de gzcompress()

    <?php
    $compressed = gzcompress('Compress me', 9);
    echo $compressed;
    ?>

### Ver también

- gzdeflate() - Comprime una cadena
- gzinflate() - Descomprime una cadena comprimida
- gzuncompress() - Descomprime una cadena comprimida
- gzencode() - Crea una cadena comprimida con gzip

# gzdecode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

gzdecode — Decodifica una cadena comprimida con gzip

### Descripción

function gzdecode(string `$data`, int `$max_length` = 0): string|false

Está función retorna una versión decodificada de la entrada `data`.

### Parámetros

`data`

  Los datos para decodificar, codificados con gzencode().

`max_length`

  La longitud máxima de datos que decodificar.

### Valores devueltos

La cadena decodificada, o o `false` si ocurre un error.

### Errores/Excepciones

En caso de fallo, se emite un error de nivel `E_WARNING`.

### Ver también

- gzencode() - Crea una cadena comprimida con gzip

# gzdeflate

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzdeflate — Comprime una cadena

### Descripción

function gzdeflate(string `$data`, int `$level` = -1, int `$encoding` = `ZLIB_ENCODING_RAW`): string|false

Esta función comprime la cadena dada utilizando el formato de datos `DEFLATE`.

Para más detalles sobre el algoritmo de compresión DEFLATE ver el documento "» Especificación del formato de datos comprimidos DEFLATE versión 1.3" (RFC 1951).

### Parámetros

`data`

  Los datos a comprimir.

`level`

  El nivel de compresión. Se puede dar desde 0 para ninguna compresión hasta 9 para máxima compresión. Si no se especifica, se utilizará el nivel de compresión por defecto de la librería zlib.

`encoding`

  Una de las constantes `ZLIB_ENCODING_*`.

### Valores devueltos

La cadena comprimida o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de gzdeflate()

    <?php
    $compressed = gzdeflate('Compress me', 9);
    echo $compressed;
    ?>

### Ver también

- gzinflate() - Descomprime una cadena comprimida
- gzcompress() - Comprime una cadena
- gzuncompress() - Descomprime una cadena comprimida
- gzencode() - Crea una cadena comprimida con gzip

# gzencode

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzencode — Crea una cadena comprimida con gzip

### Descripción

function gzencode(string `$data`, int `$level` = -1, int `$encoding` = `ZLIB_ENCODING_GZIP`): string|false

Esta función retorna una versión comprimida de la `data` de entrada, compatible con la salida del programa gzip.

Para más información sobre el formato de archivo GZIP, ver el documento: » Especificación del formato de archivo GZIP versión 4.3 (RFC 1952).

### Parámetros

`data`

  Los datos a codificar.

`level`

  El nivel de compresión. Se puede dar como 0 para ninguna compresión, hasta 9 para la máxima compresión. Si no se incluye, se utilizará el nivel de compresión por defecto de la librería zlib.

`encoding`

  El modo de codificación. Puede ser `FORCE_GZIP` (por defecto) o `FORCE_DEFLATE`.

  `FORCE_DEFLATE` genera una salida que cumple el RFC 1950, consistente en un encabezado zlib, los datos comprimidos y una suma de control Adler.

### Valores devueltos

La cadena codificada o `false` si ocurre un error.

### Ejemplos

Los datos resultantes contienen los encabezados y estructura de datos apropiados para construir un archivo .gz estándar, por ejemplo:

Ejemplo #1 Creando un archivo gzip

    <?php
    $data = file_get_contents("bigfile.txt");
    $gzdata = gzencode($data, 9);
    file_put_contents("bigfile.txt.gz", $gzdata);
    ?>

### Ver también

- gzdecode() - Decodifica una cadena comprimida con gzip
- gzdeflate() - Comprime una cadena
- gzinflate() - Descomprime una cadena comprimida
- gzuncompress() - Descomprime una cadena comprimida
- gzcompress() - Comprime una cadena
- » Especificación del formato ZLIB de compresión de datos (RFC 1950)

# gzeof

(PHP 4, PHP 5, PHP 7, PHP 8)

gzeof — Prueba de apuntador para EOF de archivo gz

### Descripción

function gzeof(resource `$stream`): bool

Prueba el apuntador de archivo GZ dado en busca del EOF (fin de archivo).

### Parámetros

`stream`

  El apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente por gzopen().

### Valores devueltos

Retorna `true` si el apuntador GZ está al EOF del archivo o si ocurrió un error; de lo contrario retorna `false`.

### Ejemplos

Ejemplo #1 Ejemplo de gzeof()

    <?php
    $gz = gzopen('somefile.gz', 'r');
    while (!gzeof($gz)) {
      echo gzgetc($gz);
    }
    gzclose($gz);
    ?>

# gzfile

(PHP 4, PHP 5, PHP 7, PHP 8)

gzfile — Lee un archivo gz completo en una matriz

### Descripción

function gzfile(string `$filename`, bool `$use_include_path` = `false`): array|false

Está función es identica a readgzfile(), excepto que retorna el archivo en una matriz.

### Parámetros

`filename`

  El nombre del archivo.

`use_include_path`
  Si se establece a `true`, también se buscan los archivos en la ruta include_path.

### Valores devueltos

Una matriz que contiene el archivo, una línea por celda, incluidas líneas vacías, y con líneas nuevas aún unidas, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | `use_include_path` es ahora de tipo bool. Anteriormente, era de tipo int.

### Ejemplos

Ejemplo #1 Ejemplo de gzfile()

    <?php
    $lines = gzfile('somefile.gz');
    foreach ($lines as $line) {
        echo $line;
    }
    ?>

### Ver también

- readgzfile() - Lee todo el archivo comprimido
- gzopen() - Abre un archivo gz

# gzgetc

(PHP 4, PHP 5, PHP 7, PHP 8)

gzgetc — Obtiene el caracter donde está el apuntador al archivo gz

### Descripción

function gzgetc(resource `$stream`): string|false

Retorna una cadena que contiene un solo caracter (sin comprimir) leído del apuntador al archivo gz dado.

### Parámetros

`stream`

  El apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente por gzopen().

### Valores devueltos

El caracter sin comprimir o `false` en caso de EOF (a diferencia de gzeof()).

### Ejemplos

Ejemplo #1 Ejemplo de gzgetc()

    <?php
    $gz = gzopen('somefile.gz', 'r');
    while (!gzeof($gz)) {
      echo gzgetc($gz);
    }
    gzclose($gz);
    ?>

### Ver también

- gzopen() - Abre un archivo gz
- gzgets() - Obtiene la línea del apuntador al archivo

# gzgets

(PHP 4, PHP 5, PHP 7, PHP 8)

gzgets — Obtiene la línea del apuntador al archivo

### Descripción

function gzgets(resource `$stream`, ?int `$length` = `null`): string|false

Obtiene una cadena (sin comprimir) de hasta un largo de - 1 bytes leídos desde el apuntador al archivo dado. La lectura termina cuando el largo de - 1 bytes ha sido leído, en un salto de línea o cuando se alcance el fin del archivo (EOF), lo que ocurra primero.

### Parámetros

`stream`

  El apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente por gzopen().

`length`

  La longitud de los datos a obtener.

### Valores devueltos

La cadena sin comprimir o `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `length` ahora es anulable; anteriormente, el valor predeterminado era `1024`.

### Ejemplos

Ejemplo #1 Ejemplo de gzgets()

    <?php
    $handle = gzopen('somefile.gz', 'r');
    while (!gzeof($handle)) {
       $buffer = gzgets($handle, 4096);
       echo $buffer;
    }
    gzclose($handle);
    ?>

### Ver también

- gzopen() - Abre un archivo gz
- gzgetc() - Obtiene el caracter donde está el apuntador al archivo gz
- gzwrite() - Escritura en un archivo gz, segura a nivel binario

# gzgetss

(PHP 4, PHP 5, PHP 7)

gzgetss — Obtiene la línea del apuntador al archivo gz y retira las etiquetas HTML

Advertencia

Esta función está OBSOLETA a partir de PHP 7.3.0, y ha sido ELIMINADA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

function gzgetss(resource `$zp`, int `$length`, string `$allowable_tags` = ?): string

Función identica a gzgets(), excepto que gzgetss() intenta retirar cualquier etiqueta HTML y PHP del texto que esta leyendo.

### Parámetros

`zp`

  El apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente por gzopen().

`length`

  La longitud de los datos a obtener.

`allowable_tags`

  Se puede usar éste parámetro opcional para especificar cuales etiquetas no se deben retirar.

### Valores devueltos

La cadena descomprimida y sin etiquetas o `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo de gzgetss()

    <?php
    $handle = gzopen('somefile.gz', 'r');
    while (!gzeof($handle)) {
       $buffer = gzgetss($handle, 4096);
       echo $buffer;
    }
    gzclose($handle);
    ?>

### Ver también

- gzopen() - Abre un archivo gz
- gzgets() - Obtiene la línea del apuntador al archivo
- strip_tags() - Elimina las etiquetas HTML y PHP de un string

# gzinflate

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzinflate — Descomprime una cadena comprimida

### Descripción

function gzinflate(string `$data`, int `$max_length` = 0): string|false

Esta función descomprime una cadena comprimida.

### Parámetros

`data`

  Los datos comprimidos con gzdeflate().

`max_length`

  La longitud máxima de los datos descodificados.

### Valores devueltos

Los datos originales descomprimidos o `false` en caso de error.

La función retornará un error si los datos descomprimidos son más de 32768 veces la longitud de la `data` de entrada o, a menos que `max_length` sea `0`, mayores que el parámetro opcional `max_length`.

### Ejemplos

Ejemplo #1 Ejemplo de gzinflate()

    <?php
    $compressed   = gzdeflate('Compress me', 9);
    $uncompressed = gzinflate($compressed);
    echo $uncompressed;
    ?>

### Ver también

- gzdeflate() - Comprime una cadena
- gzcompress() - Comprime una cadena
- gzuncompress() - Descomprime una cadena comprimida
- gzencode() - Crea una cadena comprimida con gzip

# gzopen

(PHP 4, PHP 5, PHP 7, PHP 8)

gzopen — Abre un archivo gz

### Descripción

function gzopen(string `$filename`, string `$mode`, bool `$use_include_path` = `false`): resource|false

Abre un archivo gzip (.gz) para lectura o escritura.

gzopen() se puede usar para leer un archivo el cual no esté en formato gzip; en este caso gzread() leerá directamente el archivo sin descomprimirlo.

### Parámetros

`filename`

  El nombre del archivo.

`mode`

  Como en fopen() (`rb` o `wb`) pero también puede incluir un nivel de compresión (`wb9`) u una estrategia: `f` para datos filtrados como en `wb6f`, `h` para `compresión Huffman solamente` como en `wb1h`. (Ver la descripción de `deflateInit2` en zlib.h para más información sobre el parámetro de estrategia.)

`use_include_path`
  Si se define como `true`, también se busca el archivo en la ruta include_path.

### Valores devueltos

Retorna un apuntador hacia el archivo abierto, después de eso, cualquier cosa que se lea desde este descriptor de archivo sera descomprimido de forma transparente y lo que se escriba será comprimido.

Si falla la apertura, la función retorna `false`.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | `use_include_path` es ahora de tipo bool. Anteriormente, era de tipo int.

### Ejemplos

Ejemplo #1 Ejemplo de gzopen()

    <?php
    $fp = gzopen("/tmp/file.gz", "r");
    ?>

### Ver también

- gzclose() - Cierra el apuntador de un archivo gz abierto

# gzpassthru

(PHP 4, PHP 5, PHP 7, PHP 8)

gzpassthru — Muestra todos los datos restantes a partir del apuntador al achivo gz

### Descripción

function gzpassthru(resource `$stream`): int

Lee hasta el EOF desde la posición en el apuntador al archivo gz y escribe los resultados (sin comprimir) en la salida estándar.

> Nota:

> Se puede necesitar llamar a la función gzrewind() para restablecer el apuntador al inicio del archivo, si ya se han escrito datos en él.

Sugerencia

Si sólo se desea volcar el contenido de un archivo en el buffer de salida, sin modificarlo primero o buscando una posición particular, se puede usar la función readgzfile(), la cual ahorra el llamado a la función gzopen().

### Parámetros

`stream`

  El apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente por gzopen().

### Valores devueltos

El número de caracteres sin comprimir leídos de `gz` y pasados a través de la entrada.

### Ejemplos

Ejemplo #1 Ejemplo de gzpassthru()

    <?php
    $fp = gzopen('file.gz', 'r');
    gzpassthru($fp);
    gzclose($fp);
    ?>

# gzputs

(PHP 4, PHP 5, PHP 7, PHP 8)

gzputs — Alias de gzwrite()

### Descripción

Esta función es un alias de: gzwrite().

# gzread

(PHP 4, PHP 5, PHP 7, PHP 8)

gzread — Lectura de archivo gz segura a nivel binario

### Descripción

function gzread(resource `$stream`, int `$length`): string|false

gzread() lee los bytes hasta el parámetro `length` desde el apuntador al archivo gz dado. La lectura se detiene cuando los bytes del parámetro `length` (sin comprimir) sean leídos o cuando se alcance el fin del archivo (EOF), lo que ocurra primero.

### Parámetros

`stream`

  El apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente por gzopen().

`length`

  El número de bytes a leer.

### Valores devueltos

Los datos que han sido leídos, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
7.4.0 | Esta función ahora devuelve `false` en caso de fallo; antes se devolvía `0`.

### Ejemplos

Ejemplo #1 Ejemplo de gzread()

    <?php
    // pasar los contenidos de un archivo gz a una cadena
    $filename = "/usr/local/something.txt.gz";
    $zd = gzopen($filename, "r");
    $contents = gzread($zd, 10000);
    gzclose($zd);
    ?>

### Ver también

- gzwrite() - Escritura en un archivo gz, segura a nivel binario
- gzopen() - Abre un archivo gz
- gzgets() - Obtiene la línea del apuntador al archivo
- gzgetss() - Obtiene la línea del apuntador al archivo gz y retira las etiquetas HTML
- gzfile() - Lee un archivo gz completo en una matriz
- gzpassthru() - Muestra todos los datos restantes a partir del apuntador al achivo gz

# gzrewind

(PHP 4, PHP 5, PHP 7, PHP 8)

gzrewind — Reinicia la posición del apuntador a un archivo gz

### Descripción

function gzrewind(resource `$stream`): bool

Coloca el indicador de posición del apuntador al archivo gz dado al comienzo del flujo del archivo.

### Parámetros

`stream`

  El apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente por gzopen().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- gzseek() - Ubica el apuntador a un archivo gz
- gztell() - Indica la posición de lectura/escritura del apuntador al archivo gz

# gzseek

(PHP 4, PHP 5, PHP 7, PHP 8)

gzseek — Ubica el apuntador a un archivo gz

### Descripción

function gzseek(resource `$stream`, int `$offset`, int `$whence` = `SEEK_SET`): int

Establece el indicador de posición para el apuntador al archivo dado en el desplazamiento de bytes fijado en el flujo del archivo. Es equivalente a llamar (en C) a `gzseek(zp, offset, SEEK_SET)`.

Si el archivo está abierto para lectura, ésta función es emulada pero puede ser extremadamente lenta. Si el archivo está abierto para escritura, sólo está soportada la búsqueda hacia adelante; entonces gzseek() comprime una secuencia de ceros hasta la nueva posición de inicio.

### Parámetros

`stream`

  El apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente por gzopen().

`offset`

  El desplazamiento buscado.

`whence`

  Los valores de `whence` son:

  - `SEEK_SET` - Establece la posición igual al `offset` de bytes.
  - `SEEK_CUR` - Establece la posición en la posición actual más el `offset`.

  Si `whence` no se especifica, se asume que es `SEEK_SET`.

### Valores devueltos

En caso de éxito, retorna 0; en caso contrario, devuelve -1. Notese que buscar pasado el EOF no es considerado un error.

### Ejemplos

Ejemplo #1 Ejamplo de gzseek()

    <?php
    $gz = gzopen('somefile.gz', 'r');
    gzseek($gz,2);
    echo gzgetc($gz);
    gzclose($gz);
    ?>

### Ver también

- gztell() - Indica la posición de lectura/escritura del apuntador al archivo gz
- gzrewind() - Reinicia la posición del apuntador a un archivo gz

# gztell

(PHP 4, PHP 5, PHP 7, PHP 8)

gztell — Indica la posición de lectura/escritura del apuntador al archivo gz

### Descripción

function gztell(resource `$stream`): int|false

Obtiene la posición del apuntador al archivo dado; por ejemplo, su desplazamiento en el flujo del archivo sin comprimir.

### Parámetros

`stream`

  El apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente por gzopen().

### Valores devueltos

La posición del apuntador al archivo o `false` si ocurre un error.

### Ver también

- gzopen() - Abre un archivo gz
- gzseek() - Ubica el apuntador a un archivo gz
- gzrewind() - Reinicia la posición del apuntador a un archivo gz

# gzuncompress

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

gzuncompress — Descomprime una cadena comprimida

### Descripción

function gzuncompress(string `$data`, int `$max_length` = 0): string|false

Está función descomprime una cadena comprimida

### Parámetros

`data`

  Los datos comprimidos con gzcompress().

`max_length`

  La longitud máxima de datos a decodificar.

### Valores devueltos

Los datos originales sin comprimir o `false` en caso de error.

La función retornará un error si los datos descomprimidos son más de 32768 veces la longitud de la entrada comprimida `data` o mayores que el parámetro opcional `max_length`.

### Ejemplos

Ejemplo #1 Ejemplo de gzuncompress()

    <?php
    $compressed   = gzcompress('Compress me', 9);
    $uncompressed = gzuncompress($compressed);
    echo $uncompressed;
    ?>

### Ver también

- gzcompress() - Comprime una cadena
- gzinflate() - Descomprime una cadena comprimida
- gzdeflate() - Comprime una cadena
- gzencode() - Crea una cadena comprimida con gzip

# gzwrite

(PHP 4, PHP 5, PHP 7, PHP 8)

gzwrite — Escritura en un archivo gz, segura a nivel binario

### Descripción

function gzwrite(resource `$stream`, string `$data`, ?int `$length` = `null`): int|false

gzwrite() escribe el contenido de `data` al archivo gz dado.

### Parámetros

`stream`

  El apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente por gzopen().

`data`

  La cadena a escribir.

`length`

  El número de bytes sin comprimir a escribir. Si se suministra, la escritura se detendrá después de que se hayan escrito los bytes (sin comprimir) del parámetro `length` o de que sea alcanzado el fin de la `data`, lo que ocurra primero.

### Valores devueltos

Retorna el número de bytes (sin comprimir) escritos en el flujo del archivo gz dado, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `length` ahora es anulable; anteriormente, el valor predeterminado era `0`.
7.4.0 | Esta función ahora devuelve `false` en caso de fallo; antes se devolvía `0`.

### Ejemplos

Ejemplo #1 Ejemplo de gzwrite()

    <?php
    $string = 'Some information to compress';
    $gz = gzopen('somefile.gz','w9');
    gzwrite($gz, $string);
    gzclose($gz);
    ?>

### Ver también

- gzread() - Lectura de archivo gz segura a nivel binario
- gzopen() - Abre un archivo gz

# inflate_add

(PHP 7, PHP 8)

inflate_add — Descomprime datos de manera incremental

### Descripción

function inflate_add(InflateContext `$context`, string `$data`, int `$flush_mode` = `ZLIB_SYNC_FLUSH`): string|false

Descomprime de manera incremental los datos en el `context` especificado.

Limitación: la información del encabezado de un flujo comprimido GZIP no está disponible.

### Parámetros

`context`

  Un contexto creado con inflate_init().

`data`

  Un fragmento de datos comprimidos.

`flush_mode`

  Una de las `ZLIB_BLOCK`, `ZLIB_NO_FLUSH`, `ZLIB_PARTIAL_FLUSH`, `ZLIB_SYNC_FLUSH` (por defecto), `ZLIB_FULL_FLUSH`, `ZLIB_FINISH`. Normalmente querrá establecer `ZLIB_NO_FLUSH` para maximizar la compresión, y `ZLIB_FINISH` para terminar con el último fragmento de datos. Consulte el » manual de zlib para una descripción detallada de estas constantes.

### Valores devueltos

Devuelve un fragmento de datos descomprimidos, o `false` si ocurre un error.

### Errores/Excepciones

Si se proporcionan parámetros inválidos, descomprimir los datos requiere un diccionario predefinido, pero ninguno está especificado, el flujo comprimido está corrupto o tiene un checksum inválido, se genera un error de nivel `E_WARNING`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `context` ahora espera una instancia InflateContext antes se esperaba un resource.

### Ver también

- inflate_init() - Inicializa un contexto de descompresión incremental

# inflate_get_read_len

(PHP 7 >= 7.2.0, PHP 8)

inflate_get_read_len — Devuelve el número de bytes leídos hasta el momento

### Descripción

function inflate_get_read_len(InflateContext `$context`): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`context`

### Valores devueltos

Devuelve el número de bytes leídos hasta el momento o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `context` ahora espera una instancia de InflateContext; anteriormente se esperaba un resource.

# inflate_get_status

(PHP 7 >= 7.2.0, PHP 8)

inflate_get_status — Devuelve el estado de descompresión

### Descripción

function inflate_get_status(InflateContext `$context`): int

Generalmente devuelve `ZLIB_OK` o `ZLIB_STREAM_END`.

### Parámetros

`context`

### Valores devueltos

Devuelve el estado de descompresión.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `context` ahora espera una instancia de InflateContext; anteriormente se esperaba un resource.

# inflate_init

(PHP 7, PHP 8)

inflate_init — Inicializa un contexto de descompresión incremental

### Descripción

function inflate_init(int `$encoding`, array|object `$options` = []): InflateContext|false

Inicializa un contexto de descompresión incremental con el `encoding` especificado.

### Parámetros

`encoding`

  Una de las constantes `ZLIB_ENCODING_*`.

`options`

  Un array asociativo que puede contener los siguientes elementos:

  level

    El nivel de compresión en el rango -1..9; por defecto -1.

  memory

    El nivel de memoria de compresión en el rango 1..9; por defecto 8.

  window

    El tamaño de la ventana de compresión (logarítmica) en el rango 8..15; por defecto 15.

  strategy

    Una de las `ZLIB_FILTERED`, `ZLIB_HUFFMAN_ONLY`, `ZLIB_RLE`, `ZLIB_FIXED` o `ZLIB_DEFAULT_STRATEGY` (por defecto).

  dictionary

    Un string o un array de strings del diccionario predefinido (por defecto: ningún diccionario predefinido).

### Valores devueltos

Devuelve un contexto de descompresión (`zlib.inflate`) en caso de éxito, o `false` si ocurre un error.

### Errores/Excepciones

Si se pasa un codificación o una opción inválida a `options`, o si el contexto no pudo ser creado, se genera un error de nivel `E_WARNING`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función ahora devuelve una instancia de InflateContext; anteriormente, se devolvía un resource.

### Notas

Precaución

A diferencia de gzinflate(), los contextos de inflado incremental no limitan la longitud de los datos decodificados, por lo que no proporcionan ninguna protección automática contra las bombas Zip.

### Ver también

- inflate_add() - Descomprime datos de manera incremental
- deflate_init() - Inicializa un contexto de compresión incremental

# ob_gzhandler

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ob_gzhandler — Función de recuperación para la compresión automática de pastillas

### Descripción

function ob_gzhandler(string `$data`, int `$flags`): string|false

ob_gzhandler() está destinada a ser usada como función de devolución de llamada por ob_start() para facilitar el envío de datos comprimidos a los navegadores que soportan páginas comprimidas. Antes de que ob_gzhandler() envíe los datos comprimidos, determina los tipos de codificación que son soportados por el navegador ("gzip", "deflate" o ninguno) y devuelve el contenido de los búferes de manera apropiada. Todos los navegadores son manejados, ya que es responsabilidad de los navegadores enviar un encabezado indicando los tipos de páginas soportadas. Si el navegador no soporta páginas comprimidas, esta función devolverá `false`.

### Parámetros

`data`

`flags`

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo con ob_gzhandler()

    <?php

    ob_start("ob_gzhandler");

    ?>
    <html>
    <body>
    <p>Esto debería ser una página comprimida.</p>
    </body>
    </html>

### Notas

> Nota:

> ob_gzhandler() requiere la extensión zlib.

> Nota:

> No puede usar simultáneamente ob_gzhandler() y zlib.output_compression. Además, tenga en cuenta que zlib.output_compression es preferible a ob_gzhandler().

### Ver también

- ob_start() - Activa el temporizador de salida
- ob_end_flush() - Vacía (envía) el valor de retorno del manejador de salida activo y desactiva el búfer de salida activo

# readgzfile

(PHP 4, PHP 5, PHP 7, PHP 8)

readgzfile — Lee todo el archivo comprimido

### Descripción

function readgzfile(string `$filename`, bool `$use_include_path` = `false`): int|false

readgzfile() lee el archivo `filename`, lo descomprime y muestra el resultado.

readgzfile() también puede utilizarse para leer un archivo que no está comprimido: en este caso, readgzfile() leerá el archivo sin descomprimirlo.

### Parámetros

`filename`

  El nombre del fichero. Este fichero deberá ser abierto desde el sistema de ficheros y su contenido será mostrado.

`use_include_path`
  Cuando se define como `true` la ruta include_path será utilizada para determinar el fichero a abrir.

### Valores devueltos

Devuelve el número de bytes (descomprimidos) leídos desde el fichero en caso de éxito, o `false` si ocurre un error

### Errores/Excepciones

En caso de fallo, se emitirá una advertencia de tipo `E_WARNING`.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | `use_include_path` es ahora de tipo bool. Anteriormente, era de tipo int.

### Ver también

- gzpassthru() - Muestra todos los datos restantes a partir del apuntador al achivo gz
- gzfile() - Lee un archivo gz completo en una matriz
- gzopen() - Abre un archivo gz

# zlib_decode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

zlib_decode — Descomprime datos codificados en craw/gzip/zlib

### Descripción

function zlib_decode(string `$data`, int `$max_length` = 0): string|false

Descomprime datos codificados en raw/gzip/zlib.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`data`

`max_length`

### Valores devueltos

Devuelve los datos no comprimidos, o `false` si ocurre un error.

### Ver también

- zlib_encode() - Comprime datos con la codificación especificada

# zlib_encode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

zlib_encode — Comprime datos con la codificación especificada

### Descripción

function zlib_encode(string `$data`, int `$encoding`, int `$level` = -1): string|false

Comprime datos con la codificación especificada.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`data`

  Los datos a comprimir.

`encoding`

  El algoritmo de compresión. O bien `ZLIB_ENCODING_RAW`, `ZLIB_ENCODING_DEFLATE` o `ZLIB_ENCODING_GZIP`.

`level`

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de zlib_encode()

    <?php
    $str = 'hello world';
    $enc = zlib_encode($str, ZLIB_ENCODING_DEFLATE);
    echo bin2hex($enc);
    ?>

El ejemplo anterior mostrará:

    789ccb48cdc9c95728cf2fca4901001a0b045d

### Ver también

- zlib_decode() - Descomprime datos codificados en craw/gzip/zlib

# zlib_get_coding_type

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

zlib_get_coding_type — Retorna el tipo de codificación utilizada para hacer la compresión

### Descripción

function zlib_get_coding_type(): string|false

Retorna el tipo de codificación utilizada para hacer la compresión.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Los posibles valores de retorno son `gzip`, `deflate` o `false`.

### Ver también

- La directiva zlib.output_compression

## Tabla de contenidos

- deflate_add — Comprime datos de manera incremental
- deflate_init — Inicializa un contexto de compresión incremental
- gzclose — Cierra el apuntador de un archivo gz abierto
- gzcompress — Comprime una cadena
- gzdecode — Decodifica una cadena comprimida con gzip
- gzdeflate — Comprime una cadena
- gzencode — Crea una cadena comprimida con gzip
- gzeof — Prueba de apuntador para EOF de archivo gz
- gzfile — Lee un archivo gz completo en una matriz
- gzgetc — Obtiene el caracter donde está el apuntador al archivo gz
- gzgets — Obtiene la línea del apuntador al archivo
- gzgetss — Obtiene la línea del apuntador al archivo gz y retira las etiquetas HTML
- gzinflate — Descomprime una cadena comprimida
- gzopen — Abre un archivo gz
- gzpassthru — Muestra todos los datos restantes a partir del apuntador al achivo gz
- gzputs — Alias de gzwrite
- gzread — Lectura de archivo gz segura a nivel binario
- gzrewind — Reinicia la posición del apuntador a un archivo gz
- gzseek — Ubica el apuntador a un archivo gz
- gztell — Indica la posición de lectura/escritura del apuntador al archivo gz
- gzuncompress — Descomprime una cadena comprimida
- gzwrite — Escritura en un archivo gz, segura a nivel binario
- inflate_add — Descomprime datos de manera incremental
- inflate_get_read_len — Devuelve el número de bytes leídos hasta el momento
- inflate_get_status — Devuelve el estado de descompresión
- inflate_init — Inicializa un contexto de descompresión incremental
- ob_gzhandler — Función de recuperación para la compresión automática de pastillas
- readgzfile — Lee todo el archivo comprimido
- zlib_decode — Descomprime datos codificados en craw/gzip/zlib
- zlib_encode — Comprime datos con la codificación especificada
- zlib_get_coding_type — Retorna el tipo de codificación utilizada para hacer la compresión

# La clase DeflateContext

(PHP 8)

## Introducción

Una clase completamente opaca que reemplaza los recursos `zlib.deflate` a partir de PHP 8.0.0.

## Sinopsis de la Clase

final class DeflateContext {
}

# La clase InflateContext

(PHP 8)

## Introducción

Una clase completamente opaca que reemplaza los recursos `zlib.inflate` de PHP 8.0.0.

## Sinopsis de la Clase

final class InflateContext {
}

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
  - Tipos de recursos
- Constantes predefinidas
- Ejemplos
- Funciones de Zlib
  - deflate_add — Comprime datos de manera incremental
  - deflate_init — Inicializa un contexto de compresión incremental
  - gzclose — Cierra el apuntador de un archivo gz abierto
  - gzcompress — Comprime una cadena
  - gzdecode — Decodifica una cadena comprimida con gzip
  - gzdeflate — Comprime una cadena
  - gzencode — Crea una cadena comprimida con gzip
  - gzeof — Prueba de apuntador para EOF de archivo gz
  - gzfile — Lee un archivo gz completo en una matriz
  - gzgetc — Obtiene el caracter donde está el apuntador al archivo gz
  - gzgets — Obtiene la línea del apuntador al archivo
  - gzgetss — Obtiene la línea del apuntador al archivo gz y retira las etiquetas HTML
  - gzinflate — Descomprime una cadena comprimida
  - gzopen — Abre un archivo gz
  - gzpassthru — Muestra todos los datos restantes a partir del apuntador al achivo gz
  - gzputs — Alias de gzwrite
  - gzread — Lectura de archivo gz segura a nivel binario
  - gzrewind — Reinicia la posición del apuntador a un archivo gz
  - gzseek — Ubica el apuntador a un archivo gz
  - gztell — Indica la posición de lectura/escritura del apuntador al archivo gz
  - gzuncompress — Descomprime una cadena comprimida
  - gzwrite — Escritura en un archivo gz, segura a nivel binario
  - inflate_add — Descomprime datos de manera incremental
  - inflate_get_read_len — Devuelve el número de bytes leídos hasta el momento
  - inflate_get_status — Devuelve el estado de descompresión
  - inflate_init — Inicializa un contexto de descompresión incremental
  - ob_gzhandler — Función de recuperación para la compresión automática de pastillas
  - readgzfile — Lee todo el archivo comprimido
  - zlib_decode — Descomprime datos codificados en craw/gzip/zlib
  - zlib_encode — Comprime datos con la codificación especificada
  - zlib_get_coding_type — Retorna el tipo de codificación utilizada para hacer la compresión
- DeflateContext — La clase DeflateContext
- InflateContext — La clase InflateContext

- Bzip2
  - Instalación/Configuración
  - Ejemplos
  - Funciones de Bzip2
- LZF
  - Instalación/Configuración
  - Funciones LZF
- Phar
  - Instalación/Configuración
  - Constantes predefinidas
  - Utilizar los archivos Phar
  - Creación de archivos Phar
  - ¿Qué hace que un phar sea un phar y no un tar o un zip?
  - Phar — La clase Phar
  - PharData — La clase PharData
  - PharFileInfo — La clase PharFileInfo
  - PharException — La clase PharException
- Rar — Archivos Rar
  - Instalación/Configuración
  - Constantes predefinidas
  - Ejemplos
  - Funciones Rar
  - RarArchive — La clase RarArchive
  - RarEntry — La clase RarEntry
  - RarException — La clase RarException
- Zip
  - Instalación/Configuración
  - Constantes predefinidas
  - Ejemplos
  - ZipArchive — La clase ZipArchive
  - Funciones Zip
- Zlib — Compresión Zlib
  - Instalación/Configuración
  - Constantes predefinidas
  - Ejemplos
  - Funciones de Zlib
  - DeflateContext — La clase DeflateContext
  - InflateContext — La clase InflateContext

# Extensiones criptográficas

# HASH (framework de resúmenes de mensaje)

# Introducción

Esta extensión proporciona funciones que pueden usarse para el procesamiento directo o incremental de mensajes de longitud arbitraria utilizando una variedad de algoritmos de hash, incluyendo la generación de valores HMAC y derivaciones de claves incluyendo HKDF y PBKDF2.

Existen aproximadamente tres categorías de algoritmos de hash, y una lista completa de algoritmos puede encontrarse en la documentación de hash_algos().

- Algoritmos de suma de verificación (como `"crc32b"` o `"adler32"`): Estos se utilizan para calcular sumas de verificación, útiles en situaciones como cuando se deben detectar errores de transmisión. Suelen ser muy rápidos. Estos algoritmos a menudo generan valores que son fácilmente "adivinables" o pueden ser manipulados para crear colisiones, por lo que son completamente inadecuados para uso criptográfico.
- Algoritmos no criptográficos (como la familia xxHash): Estos se utilizan a menudo para calcular valores hash para tablas hash, ya que están diseñados para ofrecer una buena distribución sobre entradas de string arbitrarias. También suelen ser rápidos, pero no son adecuados para uso criptográfico.
- Algoritmos criptográficos (como la familia SHA-2): Estos están diseñados para generar valores hash que sean representativos de sus entradas pero que no sean adivinables ni propensos a colisiones. El rendimiento suele ser una preocupación secundaria, pero el hardware moderno a menudo admite un manejo especial para estos algoritmos que PHP intenta utilizar cuando está disponible. El Centro de Recursos de Seguridad Informática del NIST tiene » una explicación de los algoritmos actualmente aprobados por los Estándares Federales de Procesamiento de Información de los Estados Unidos.
  Precaución

  Algunos de los primeros algoritmos criptográficos, como `"md4"`, `"md5"` y `"sha1"`, han demostrado ser propensos a ataques de colisión y generalmente se recomienda no utilizarlos más para aplicaciones criptográficas.

Consulte también las preguntas frecuentes sobre el Hashing Seguro de Contraseñas para obtener información sobre las mejores prácticas para el uso de funciones hash en el manejo de contraseñas.

# Instalación/Configuración

## Tabla de contenidos

- Instalación
- Tipos de recursos

## Instalación

La extensión Hash es una extensión principal de PHP, por lo que siempre está habilitada.

Antes de PHP 7.4.0, la extensión Hash se incluía y compilaba con PHP por defecto, pero podía deshabilitarse explícitamente usando --disable-hash.

Antes de 5.1.2, la extensión Hash se instalaba como un » módulo PECL.

## Tipos de recursos

Esta extensión define un recurso de Contexto de Hashing devuelto por hash_init().

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`HASH_HMAC` (int)
  Indicador opcional para hash_init(). Indica que el algoritmo de clave HMAC debe ser aplicado al contexto actual de hash.

# La clase HashContext

(PHP 7 >= 7.2.0, PHP 8)

## Introducción

## Sinopsis de la Clase

final class HashContext {
/* Métodos */
private function __construct()
public function __debugInfo(): array
public function __serialize(): array
public function __unserialize(array `$data`): void
}

# HashContext::__construct

(PHP 7 >= 7.2.0, PHP 8)

HashContext::__construct — Constructor privado para prohibir la instanciación directa

### Descripción

private function HashContext::__construct()

### Parámetros

Esta función no contiene ningún parámetro.

# HashContext::__debugInfo

(PHP 8 >= 8.4.0)

HashContext::__debugInfo — Devuelve información de depuración sobre el contexto de hash

### Descripción

public function HashContext::__debugInfo(): array

Este método no está pensado para ser llamado directamente; es invocado por var_dump() y funciones relacionadas al inspeccionar una instancia de HashContext.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array asociativo con información de depuración. Contiene una clave `algo` que almacena el nombre del algoritmo de hash en uso por el contexto.

### Ejemplos

Ejemplo #1 Ejemplo de HashContext::__debugInfo()

    <?php
    $ctx = hash_init('sha256');
    var_dump($ctx);
    ?>

El ejemplo anterior mostrará:

    object(HashContext)#1 (1) {
      ["algo"]=>
      string(6) "sha256"
    }

### Ver también

- hash_init() - Inicializa un contexto de hachado incremental
- var_dump() - Muestra información sobre una variable

# HashContext::__serialize

(PHP 8)

HashContext::__serialize — Serializa el objeto HashContext

### Descripción

public function HashContext::__serialize(): array

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

# HashContext::__unserialize

(PHP 8)

HashContext::__unserialize — Deserializa el parámetro `data` en un objeto HashContext

### Descripción

public function HashContext::__unserialize(array `$data`): void

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`data`

  El valor que se está deserializando.

### Valores devueltos

No se retorna ningún valor.

## Tabla de contenidos

- HashContext::__construct — Constructor privado para prohibir la instanciación directa
- HashContext::__debugInfo — Devuelve información de depuración sobre el contexto de hash
- HashContext::__serialize — Serializa el objeto HashContext
- HashContext::__unserialize — Deserializa el parámetro data en un objeto HashContext

# Funciones de hash

# hash

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash — Genera un valor de hachado (huella digital)

### Descripción

function hash(
string `$algo`,
string `$data`,
bool `$binary` = `false`,
array `$options` = []
): string

### Parámetros

`algo`

  Nombre del algoritmo de hachado seleccionado (por ejemplo: `"sha256"`). Para una lista de los algoritmos soportados ver hash_algos().

`data`

  Mensaje a hachar.

`binary`

  Cuando vale `true`, la salida será datos binarios sin tratar. Cuando vale `false`, la salida será dígitos hexadecimales en minúscula.

`options`

  Un array de opciones para los diversos algoritmos de hachado. Actualmente, solo el parámetro `"seed"` es soportado para las variantes MurmurHash.

### Valores devueltos

Devuelve un string que contiene la huella digital calculada en dígitos hexadecimales minúsculos a menos que `binary` esté fijado a `true`. En este caso, la representación binaria sin tratar de la huella digital es devuelta.

### Errores/Excepciones

Lanza una excepción ValueError si `algo` es desconocido.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `options` ha sido añadido.
8.0.0 | Ahora lanza una excepción ValueError si `algo` es desconocido; anteriormente, `false` era devuelto y se emitía un mensaje `E_WARNING`.

### Ejemplos

Ejemplo #1 Ejemplo con hash()

    <?php
    echo hash('sha256', 'The quick brown fox jumped over the lazy dog.');
    ?>

El ejemplo anterior mostrará:

    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483

### Ver también

- hash_init() - Inicializa un contexto de hachado incremental
- hash_file() - Genera un valor de hash utilizando el contenido de un fichero dado
- hash_hmac() - Genera un valor de clave de hash utilizando el método HMAC

# hash_algos

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_algos — Devuelve una lista de los algoritmos de hash registrados

### Descripción

function hash_algos(): array

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array indexado numéricamente que contiene la lista de algoritmos de hash disponibles.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Se ha añadido soporte para MurmurHash3 y xxHash.
7.4.0 | Se ha añadido soporte para crc32c.
7.1.0 | Se ha añadido soporte para sha512/224, sha512/256, sha3-224, sha3-256, sha3-384 y sha3-512.

### Ejemplos

Ejemplo #1 Ejemplo con hash_algos()

A partir de PHP 8.1.0, hash_algos() devolverá la siguiente lista de algoritmos:

    <?php
    print_r(hash_algos());
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => md2
        [1] => md4
        [2] => md5
        [3] => sha1
        [4] => sha224
        [5] => sha256
        [6] => sha384
        [7] => sha512/224
        [8] => sha512/256
        [9] => sha512
        [10] => sha3-224
        [11] => sha3-256
        [12] => sha3-384
        [13] => sha3-512
        [14] => ripemd128
        [15] => ripemd160
        [16] => ripemd256
        [17] => ripemd320
        [18] => whirlpool
        [19] => tiger128,3
        [20] => tiger160,3
        [21] => tiger192,3
        [22] => tiger128,4
        [23] => tiger160,4
        [24] => tiger192,4
        [25] => snefru
        [26] => snefru256
        [27] => gost
        [28] => gost-crypto
        [29] => adler32
        [30] => crc32
        [31] => crc32b
        [32] => crc32c
        [33] => fnv132
        [34] => fnv1a32
        [35] => fnv164
        [36] => fnv1a64
        [37] => joaat
        [38] => murmur3a
        [39] => murmur3c
        [40] => murmur3f
        [41] => xxh32
        [42] => xxh64
        [43] => xxh3
        [44] => xxh128
        [45] => haval128,3
        [46] => haval160,3
        [47] => haval192,3
        [48] => haval224,3
        [49] => haval256,3
        [50] => haval128,4
        [51] => haval160,4
        [52] => haval192,4
        [53] => haval224,4
        [54] => haval256,4
        [55] => haval128,5
        [56] => haval160,5
        [57] => haval192,5
        [58] => haval224,5
        [59] => haval256,5
    )

### Ver también

- hash() - Genera un valor de hachado (huella digital)
- hash_hmac_algos() - Devuelve una lista de algoritmos de hash registrados adecuados para hash_hmac

# hash_copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

hash_copy — Copia un contexto de hachado

### Descripción

function hash_copy(HashContext `$context`): HashContext

### Parámetros

`context`

  Contexto de hachado, retornado por la función hash_init().

### Valores devueltos

Retorna una copia del contexto de hash.

### Historial de cambios

Versión | Descripción
--- | ---
7.2.0 | Acepta y retorna una clase HashContext en lugar de un recurso.

### Ejemplos

Ejemplo #1 Ejemplo con hash_copy()

    <?php
    $context = hash_init("sha256");
    hash_update($context, "The quick brown fox ");

    /* copia el contexto para poder continuar utilizándolo */
    $copy_context = hash_copy($context);

    echo hash_final($context), "\n";

    hash_update($copy_context, "jumped over the lazy dog.");
    echo hash_final($copy_context), "\n";
    ?>

El ejemplo anterior mostrará:

    b29d66e56ed90cce9b0165c43fedec612b60a071974d8be4513e18580d55b5bd
    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483

# hash_equals

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

hash_equals — Comparación de strings resistente a ataques temporales

### Descripción

function hash_equals(#[\SensitiveParameter]string `$known_string`, #[\SensitiveParameter]string `$user_string`): bool

Verifica si dos strings son iguales sin revelar información sobre el contenido de `known_string` mediante el tiempo de ejecución.

Esta función puede ser utilizada para mitigar ataques temporales. La ejecución de una comparación regular con `===` tomará más o menos tiempo dependiendo de si las dos valores son diferentes o no y según la posición en la que la primera diferencia pueda ser encontrada, dejando así filtrar información sobre el contenido de la `known_string` secreta.

Precaución

Es importante pasar el string proporcionado por el usuario como segundo argumento en lugar del primero.

### Parámetros

`known_string`

  El string conocido que debe ser mantenido en secreto.

`user_string`

  El string proporcionado por el usuario a comparar.

### Valores devueltos

Retorna `true` si los dos strings son iguales, `false` en caso contrario.

### Ejemplos

Ejemplo #1 Ejemplo dehash_equals()

    <?php
    $secretKey = '8uRhAeH89naXfFXKGOEj';

    // El valor y la firma son proporcionados por el usuario, p. ej. en la URL
    // y recuperados mediante $_GET.
    $value = 'username=rasmuslerdorf';
    $signature = '8c35009d3b50caf7f5d2c1e031842e6b7823a1bb781d33c5237cd27b57b5f327';

    if (hash_equals(hash_hmac('sha256', $value, $secretKey), $signature)) {
        echo "El valor está firmado correctamente.", PHP_EOL;
    } else {
        echo "El valor ha sido manipulado.", PHP_EOL;
    }
    ?>

El ejemplo anterior mostrará:

    El valor está firmado correctamente.

### Notas

> Nota:

> Ambos argumentos deben tener la misma longitud para ser comparados con éxito. Cuando se pasan argumentos de longitud diferente, `false` es retornado inmediatamente y la longitud del string conocido puede ser revelada en caso de ataque temporal.

### Ver también

- hash_hmac() - Genera un valor de clave de hash utilizando el método HMAC

# hash_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_file — Genera un valor de hash utilizando el contenido de un fichero dado

### Descripción

function hash_file(
string `$algo`,
string `$filename`,
bool `$binary` = `false`,
array `$options` = []
): string|false

### Parámetros

`algo`

  Nombre del algoritmo de hash seleccionado (por ejemplo: `"sha256"`). Para una lista de los algoritmos disponibles ver hash_algos().

`filename`

  URL que indica la ubicación del fichero que será hasheado; Soporta los envolventes fopen().

`binary`

  Cuando vale `true`, la salida será datos binarios sin tratar. Cuando vale `false`, la salida será dígitos hexadecimales en minúscula.

`options`

  Un array de opciones para los diversos algoritmos de hash. Actualmente, solo el parámetro `"seed"` es soportado para las variantes MurmurHash.

### Valores devueltos

Devuelve un string que contiene la huella digital calculada en dígitos hexadecimales minúsculos a menos que `binary` esté fijado a `true`. En este caso, la representación binaria sin tratar de la huella digital es devuelta, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `options` ha sido añadido.

### Ejemplos

Ejemplo #1 Ejemplo con hash_file()

    <?php
    /* Crea un fichero para calcular su huella digital */
    file_put_contents('example.txt', 'The quick brown fox jumped over the lazy dog.');

    echo hash_file('sha256', 'example.txt');
    ?>

El ejemplo anterior mostrará:

    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483

### Ver también

- hash_init() - Inicializa un contexto de hachado incremental
- hash_hmac_file() - Genera un valor de clave de hash utilizando el método HMAC y el contenido de un fichero dado

# hash_final

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_final — Finaliza un hachaje incremental y devuelve el resultado de la huella digital

### Descripción

function hash_final(HashContext `$context`, bool `$binary` = `false`): string

### Parámetros

`context`

  Contexto de hachaje devuelto por hash_init().

`binary`

  Cuando es `true`, la salida será datos brutos binarios. Cuando es `false`, la salida será dígitos hexadecimales en minúscula.

### Valores devueltos

Devuelve una cadena de caracteres que contiene la huella digital calculada en dígitos hexadecimales en minúscula a menos que `binary` esté fijado a `true`. En este caso, se devuelve la representación bruta binaria de la huella digital.

### Historial de cambios

Versión | Descripción
--- | ---
7.2.0 | Acepta una HashContext en lugar de un recurso.

### Ver también

- hash_init() - Inicializa un contexto de hachado incremental
- hash_update() - Añade datos en el contexto de hash activo
- hash_update_stream() - Introduce datos en un contexto de hash activo desde un flujo abierto
- hash_update_file() - Se añaden datos en un contexto de hash activo a partir de un fichero

# hash_hkdf

(PHP 7 >= 7.1.2, PHP 8)

hash_hkdf — Genera una derivación de clave HKDF a partir de una clave de entrada proporcionada

### Descripción

function hash_hkdf(
string `$algo`,
#[\SensitiveParameter]string `$key`,
int `$length` = 0,
string `$info` = "",
string `$salt` = ""
): string

### Parámetros

`algo`

  Nombre del algoritmo hash seleccionado (por ejemplo, `"sha256"`). Para ver una lista de algoritmos soportados, consulte hash_hmac_algos().

  > Nota:

  > No se permiten funciones hash no criptográficas.

`key`

  Material de clave de entrada (binario sin tratar). No puede estar vacío.

`length`

  Longitud deseada de la salida en bytes. No puede ser mayor que 255 veces el tamaño de la función hash elegida.

  Si `length` es `0`, la longitud de salida será por omisión el tamaño de la función hash elegida.

`info`

  String de información específica de la aplicación/contexto.

`salt`

  Salt a utilizar durante la derivación.

  Aunque es opcional, añadir un salt aleatorio mejora significativamente la robustez de HKDF.

### Valores devueltos

Devuelve un string que contiene una representación binaria sin tratar de la clave derivada (también conocida como material de clave de salida - OKM).

### Errores/Excepciones

Lanza una excepción ValueError si `key` está vacío, `algo` es desconocido/no criptográfico, `length` es menor que `0` o demasiado grande (mayor que 255 veces el tamaño de la función hash).

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Ahora lanza una excepción ValueError en caso de error. Anteriormente, se devolvía `false` y se emitía un mensaje `E_WARNING`.

### Ejemplos

El ejemplo siguiente produce un par de claves separadas, adecuadas para crear una construcción de tipo encrypt-then-HMAC, utilizando AES-256 y SHA-256 para cifrado y autenticación respectivamente.

Ejemplo #1 Ejemplo de hash_hkdf()

    <?php
    // Generar una clave aleatoria y un salt para fortalecerla durante la derivación.
    $inputKey = random_bytes(32);
    $salt = random_bytes(16);

    // Derivar un par de claves separadas, utilizando la misma entrada creada arriba.
    $encryptionKey = hash_hkdf('sha256', $inputKey, 32, 'aes-256-encryption', $salt);
    $authenticationKey = hash_hkdf('sha256', $inputKey, 32, 'sha-256-authentication', $salt);

    var_dump($encryptionKey !== $authenticationKey); // bool(true)
    ?>

### Ver también

- hash_pbkdf2() - Genera una clave PBKDF2 derivada de la contraseña proporcionada
- » RFC 5869
- » implementación en espacio de usuario

# hash_hmac

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_hmac — Genera un valor de clave de hash utilizando el método HMAC

### Descripción

function hash_hmac(
string `$algo`,
string `$data`,
#[\SensitiveParameter]string `$key`,
bool `$binary` = `false`
): string

### Parámetros

`algo`

  Nombre del algoritmo de hash seleccionado (por ejemplo: `"sha256"`). Para una lista de los algoritmos soportados ver hash_hmac_algos().

  > Nota:

  > Las funciones de hash no criptográficas no están permitidas.

`data`

  El mensaje que será hasheado.

`key`

  Clave secreta compartida utilizada para generar la variación HMAC de la huella digital.

`binary`

  Cuando es `true`, la salida será datos binarios sin tratar. Cuando es `false`, la salida será dígitos hexadecimales en minúscula.

### Valores devueltos

Retorna un string que contiene la huella digital calculada en dígitos hexadecimales en minúscula a menos que `binary` esté fijado a `true`. En este caso, la representación binaria sin tratar de la huella digital es retornada.

### Errores/Excepciones

Levanta una excepción ValueError si el argumento `algo` es desconocido o no es una función de hash criptográfica.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | hash_hmac() ahora levanta una excepción ValueError si el `algo` es desconocido o no es una función de hash criptográfica ; anteriormente, `false` era retornado y se emitía un mensaje `E_WARNING`.
7.2.0 | El uso de funciones de hash no criptográficas (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) ha sido desactivado.

### Ejemplos

Ejemplo #1 Ejemplo con hash_hmac()

    <?php
    echo hash_hmac('sha256', 'The quick brown fox jumped over the lazy dog.', 'secret');
    ?>

El ejemplo anterior mostrará:

    9c5c42422b03f0ee32949920649445e417b2c634050833c5165704b825c2a53b

### Ver también

- hash_hmac_algos() - Devuelve una lista de algoritmos de hash registrados adecuados para hash_hmac
- hash_hmac_file() - Genera un valor de clave de hash utilizando el método HMAC y el contenido de un fichero dado
- hash_equals() - Comparación de strings resistente a ataques temporales

# hash_hmac_algos

(PHP 7 >= 7.2.0, PHP 8)

hash_hmac_algos — Devuelve una lista de algoritmos de hash registrados adecuados para hash_hmac

### Descripción

function hash_hmac_algos(): array

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array indexado numéricamente que contiene la lista de todos los algoritmos de hash disponibles que son adecuados para hash_hmac().

### Ejemplos

Ejemplo #1 Ejemplo con hash_hmac_algos()

    <?php
    print_r(hash_hmac_algos());

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => md2
        [1] => md4
        [2] => md5
        [3] => sha1
        [4] => sha224
        [5] => sha256
        [6] => sha384
        [7] => sha512/224
        [8] => sha512/256
        [9] => sha512
        [10] => sha3-224
        [11] => sha3-256
        [12] => sha3-384
        [13] => sha3-512
        [14] => ripemd128
        [15] => ripemd160
        [16] => ripemd256
        [17] => ripemd320
        [18] => whirlpool
        [19] => tiger128,3
        [20] => tiger160,3
        [21] => tiger192,3
        [22] => tiger128,4
        [23] => tiger160,4
        [24] => tiger192,4
        [25] => snefru
        [26] => snefru256
        [27] => gost
        [28] => gost-crypto
        [29] => haval128,3
        [30] => haval160,3
        [31] => haval192,3
        [32] => haval224,3
        [33] => haval256,3
        [34] => haval128,4
        [35] => haval160,4
        [36] => haval192,4
        [37] => haval224,4
        [38] => haval256,4
        [39] => haval128,5
        [40] => haval160,5
        [41] => haval192,5
        [42] => haval224,5
        [43] => haval256,5
    )

### Notas

> Nota:

> Antes de PHP 7.2.0 la única forma de recuperar una lista de los algoritmos disponibles era llamar a hash_algos() que también devolvía algoritmos que no son adecuados para hash_hmac().

### Ver también

- hash_hmac() - Genera un valor de clave de hash utilizando el método HMAC
- hash_algos() - Devuelve una lista de los algoritmos de hash registrados

# hash_hmac_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_hmac_file — Genera un valor de clave de hash utilizando el método HMAC y el contenido de un fichero dado

### Descripción

function hash_hmac_file(
string `$algo`,
string `$filename`,
#[\SensitiveParameter]string `$key`,
bool `$binary` = `false`
): string|false

### Parámetros

`algo`

  Nombre del algoritmo de hash seleccionado (por ejemplo: `"sha256"`). Para una lista de los algoritmos soportados ver hash_hmac_algos().

  > Nota:

  > Las funciones de hash no criptográficas no están autorizadas.

`filename`

  URL que indica la ubicación del fichero que será hasheado; Soporta las envolturas fopen().

`key`

  Clave secreta compartida utilizada para generar la varianza HMAC de la huella digital.

`binary`

  Cuando vale `true`, la salida será datos brutos binarios. Cuando vale `false`, la salida serán dígitos hexadecimales en minúscula.

### Valores devueltos

Devuelve una cadena de caracteres que contiene la huella digital calculada en dígitos hexadecimales en minúscula a menos que `binary` esté fijado a `true`. En este caso, se devuelve la representación bruta binaria de la huella digital. Devuelve `false` si el fichero `filename` no puede ser leído.

### Errores/Excepciones

Levanta una excepción ValueError si el parámetro `algo` es desconocido o no es una función de hash criptográfica.

### Historial de cambios

Versión | Descripción
--- | ---
7.2.0 | El uso de funciones de hash no criptográficas (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) ha sido desactivado.
8.0.0 | Levanta una excepción ValueError a partir de ahora si el parámetro `algo` es desconocido o no es una función de hash criptográfica; previamente, `false` era devuelto y se emitía un mensaje `E_WARNING`.

### Ejemplos

Ejemplo #1 Ejemplo con hash_hmac_file()

    <?php
    /* Crea un fichero para calcular su huella digital */
    file_put_contents('example.txt', 'The quick brown fox jumped over the lazy dog.');

    echo hash_hmac_file('sha256', 'example.txt', 'secret');
    ?>

El ejemplo anterior mostrará:

    9c5c42422b03f0ee32949920649445e417b2c634050833c5165704b825c2a53b

### Ver también

- hash_hmac() - Genera un valor de clave de hash utilizando el método HMAC
- hash_hmac_algos() - Devuelve una lista de algoritmos de hash registrados adecuados para hash_hmac
- hash_init() - Inicializa un contexto de hachado incremental
- hash_equals() - Comparación de strings resistente a ataques temporales

# hash_init

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_init — Inicializa un contexto de hachado incremental

### Descripción

function hash_init(
string `$algo`,
int `$flags` = 0,
#[\SensitiveParameter]string `$key` = "",
array `$options` = []
): HashContext

### Parámetros

`algo`

  Nombre del algoritmo de hachado seleccionado (por ejemplo: `"sha256"`). Para una lista de los algoritmos soportados ver hash_algos().

  > Nota:

  > Las funciones de hachado no criptográficas no están permitidas si se especifica el flag `HASH_HMAC`.

`flags`

  Configuraciones opcionales para la generación del hachado, actualmente solo soporta una opción: `HASH_HMAC`. Cuando esta opción es especificada, el parámetro `key` debe ser especificado.

`key`

  Cuando `HASH_HMAC` es especificada para `flags`, una clave secreta compartida que será utilizada con el método de hachado HMAC debe ser proporcionada en este parámetro.

`options`

  Un array de opciones para los algoritmos diversos de hachado. Actualmente, solo el parámetro `"seed"` es soportado para las variantes MurmurHash.

### Valores devueltos

Retorna el contexto de hachado HashContext para su utilización con hash_update(), hash_update_stream(), hash_update_file() y hash_final().

### Errores/Excepciones

- Levanta una excepción ValueError si el `algo` es desconocido, si es una función de hachado no criptográfica, o si `key` está vacío.
- Pasar opciones de configuración de tipo incorrecto en `options` emitirá ahora un error `E_DEPRECATED`, ya que pueden ser mal interpretadas. Esto resultará en una excepción ValueError en el futuro.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Pasar opciones de un tipo incorrecto está ahora desaconsejado.
8.1.0 | El parámetro `options` ha sido añadido.
7.2.0 | El uso de funciones de hachado no criptográficas (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) con `HASH_HMAC` ha sido desactivado.
7.2.0 | Retorna una HashContext en lugar de un recurso. | 8.0.0 | Levanta una excepción ValueError ahora si el parámetro `algo` es desconocido o no es una función de hachado criptográfica, o si el parámetro `key` está vacío. Anteriormente, `false` era retornado y un mensaje `E_WARNING` era emitido.

### Ejemplos

Ejemplo #1 Ejemplo de hachado incremental

    <?php
    $hash = hash('sha256', 'The quick brown fox jumped over the lazy dog.');

    $ctx = hash_init('sha256');
    hash_update($ctx, 'The quick brown fox ');
    hash_update($ctx, 'jumped over the lazy dog.');
    $incremental_hash = hash_final($ctx);

    echo $incremental_hash, PHP_EOL;
    var_dump($hash === $incremental_hash);
    ?>

El ejemplo anterior mostrará:

    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483
    bool(true)

### Ver también

- hash_algos() - Devuelve una lista de los algoritmos de hash registrados
- hash_update() - Añade datos en el contexto de hash activo
- hash_update_file() - Se añaden datos en un contexto de hash activo a partir de un fichero
- hash_update_stream() - Introduce datos en un contexto de hash activo desde un flujo abierto
- hash_final() - Finaliza un hachaje incremental y devuelve el resultado de la huella digital

# hash_pbkdf2

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

hash_pbkdf2 — Genera una clave PBKDF2 derivada de la contraseña proporcionada

### Descripción

function hash_pbkdf2(
string `$algo`,
#[\SensitiveParameter]string `$password`,
string `$salt`,
int `$iterations`,
int `$length` = 0,
bool `$binary` = `false`,
array `$options` = []
): string

### Parámetros

`algo`

  Nombre del algoritmo de hash seleccionado (por ejemplo: `"sha256"`). Para una lista de los algoritmos soportados ver hash_hmac_algos().

  > Nota:

  > Las funciones de hash no criptográficas no están permitidas.

`password`

  La contraseña a utilizar para la derivación.

`salt`

  El salt a utilizar para la derivación. Este valor debe ser generado aleatoriamente.

`iterations`

  El número de iteraciones internas para efectuar la derivación.

`length`

  La longitud de la cadena de salida. Si el parámetro `binary` vale `true`, este parámetro corresponderá a la longitud, en bytes, de la clave derivada; si el parámetro `binary` vale `false`, corresponderá al doble de la longitud, en bytes, de la clave derivada (ya que cada byte de la clave es devuelto sobre dos hexits).

  Si `0` es pasado, la salida completa del algoritmo elegido será utilizada.

`binary`

  Cuando está definido a `true`, la función mostrará los datos binarios brutos. Si vale `false`, la visualización se hará en minúsculas.

`options`

  Un array de opciones para los diferentes algoritmos de hash. Actualmente, solo la clave `"seed"` es soportada por las variantes MurmurHash.

### Valores devueltos

Devuelve una cadena que contiene la clave derivada en minúsculas, a menos que el parámetro `binary` esté posicionado a `true` en cuyo caso, la representación binaria bruta de la clave derivada será devuelta.

### Errores/Excepciones

Una excepción ValueError si el algoritmo no es conocido, si el parámetro `iterations` es inferior o igual a `0`, si la longitud `length` es inferior o igual a `0` o si el `salt` es demasiado largo (mayor que `INT_MAX``- 4`).

### Historial de cambios

Versión | Descripción
--- | ---
7.2.0 | El uso de funciones de hash no criptográficas (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) ha sido desactivado.
8.0.0 | Levanta una excepción ValueError ahora en caso de error. Anteriormente, `false` era devuelto y un mensaje `E_WARNING` era emitido.

### Ejemplos

Ejemplo #1 Ejemplo con hash_pbkdf2()

    <?php
    $password = "password";
    $iterations = 600000;

    // Genera un salt criptográficamente seguro aleatorio usando la función random_bytes(),
    $salt = random_bytes(16);

    $hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 20);
    var_dump($hash);

    // Para binario bruto, $length debe ser dividido por dos para resultados equivalentes
    $hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 10, true);
    var_dump(bin2hex($hash));
    ?>

Resultado del ejemplo anterior es similar a:

    string(20) "120fb6cffcf8b32c43e7"
    string(20) "120fb6cffcf8b32c43e7"

### Notas

Precaución

El método PBKDF2 puede ser utilizado para hashear contraseñas para el almacenamiento. Sin embargo, debe tenerse en cuenta que la función password_hash() o la función crypt() con la constante `CRYPT_BLOWFISH` es mejor para este uso.

### Ver también

- password_hash() - Crea una clave de hash para una contraseña
- hash_hkdf() - Genera una derivación de clave HKDF a partir de una clave de entrada proporcionada
- sodium_crypto_pwhash() - Deriva una clave a partir de una contraseña, utilizando Argon2

# hash_update

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update — Añade datos en el contexto de hash activo

### Descripción

function hash_update(HashContext `$context`, string `$data`): true

### Parámetros

`context`

  Contexto de hash devuelto por hash_init().

`data`

  Mensaje que será incluido en la huella de hash.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Posee ahora un tipo de retorno true en lugar de bool.
7.2.0 | Acepta una HashContext en lugar de un recurso.

### Ver también

- hash_init() - Inicializa un contexto de hachado incremental
- hash_update_file() - Se añaden datos en un contexto de hash activo a partir de un fichero
- hash_update_stream() - Introduce datos en un contexto de hash activo desde un flujo abierto
- hash_final() - Finaliza un hachaje incremental y devuelve el resultado de la huella digital

# hash_update_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update_file — Se añaden datos en un contexto de hash activo a partir de un fichero

### Descripción

function hash_update_file(HashContext `$context`, string `$filename`, ?resource `$stream_context` = `null`): bool

### Parámetros

`context`

  Contexto de hash devuelto por hash_init().

`filename`

  URL que indica la ubicación del fichero que será hasheado; admite las envolturas fopen().

`stream_context`

  Contexto de flujo devuelto por stream_context_create().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `stream_context` ahora es nullable.
7.2.0 | Acepta una HashContext en lugar de un recurso.

### Ver también

- hash_init() - Inicializa un contexto de hachado incremental
- hash_update() - Añade datos en el contexto de hash activo
- hash_update_stream() - Introduce datos en un contexto de hash activo desde un flujo abierto
- hash_final() - Finaliza un hachaje incremental y devuelve el resultado de la huella digital
- hash_file() - Genera un valor de hash utilizando el contenido de un fichero dado

# hash_update_stream

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update_stream — Introduce datos en un contexto de hash activo desde un flujo abierto

### Descripción

function hash_update_stream(HashContext `$context`, resource `$stream`, int `$length` = -1): int

### Parámetros

`context`

  Contexto de hash devuelto por hash_init().

`stream`

  Gestor de fichero abierto como el devuelto por cualquier función de creación de flujos.

`length`

  Número máximo de caracteres a copiar desde `stream` al contexto de hash.

### Valores devueltos

Número real de bytes añadidos al contexto de hash desde `stream`.

### Historial de cambios

Versión | Descripción
--- | ---
7.2.0 | Acepta HashContext en lugar de resource.

### Ejemplos

Ejemplo #1 Ejemplo de hash_update_stream()

    <?php
    $fp = tmpfile();
    fwrite($fp, 'jumped over the lazy dog.');
    rewind($fp);

    $ctx = hash_init('sha256');
    hash_update($ctx, 'The quick brown fox ');
    hash_update_stream($ctx, $fp);
    echo hash_final($ctx);
    ?>

El ejemplo anterior mostrará:

    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483

### Ver también

- hash_init() - Inicializa un contexto de hachado incremental
- hash_update() - Añade datos en el contexto de hash activo
- hash_final() - Finaliza un hachaje incremental y devuelve el resultado de la huella digital

## Tabla de contenidos

- hash — Genera un valor de hachado (huella digital)
- hash_algos — Devuelve una lista de los algoritmos de hash registrados
- hash_copy — Copia un contexto de hachado
- hash_equals — Comparación de strings resistente a ataques temporales
- hash_file — Genera un valor de hash utilizando el contenido de un fichero dado
- hash_final — Finaliza un hachaje incremental y devuelve el resultado de la huella digital
- hash_hkdf — Genera una derivación de clave HKDF a partir de una clave de entrada proporcionada
- hash_hmac — Genera un valor de clave de hash utilizando el método HMAC
- hash_hmac_algos — Devuelve una lista de algoritmos de hash registrados adecuados para hash_hmac
- hash_hmac_file — Genera un valor de clave de hash utilizando el método HMAC y el contenido de un fichero dado
- hash_init — Inicializa un contexto de hachado incremental
- hash_pbkdf2 — Genera una clave PBKDF2 derivada de la contraseña proporcionada
- hash_update — Añade datos en el contexto de hash activo
- hash_update_file — Se añaden datos en un contexto de hash activo a partir de un fichero
- hash_update_stream — Introduce datos en un contexto de hash activo desde un flujo abierto

- Instalación/Configuración
  - Instalación
  - Tipos de recursos
- Constantes predefinidas
- HashContext — La clase HashContext
  - HashContext::__construct — Constructor privado para prohibir la instanciación directa
  - HashContext::__debugInfo — Devuelve información de depuración sobre el contexto de hash
  - HashContext::__serialize — Serializa el objeto HashContext
  - HashContext::__unserialize — Deserializa el parámetro data en un objeto HashContext
- Funciones de hash
  - hash — Genera un valor de hachado (huella digital)
  - hash_algos — Devuelve una lista de los algoritmos de hash registrados
  - hash_copy — Copia un contexto de hachado
  - hash_equals — Comparación de strings resistente a ataques temporales
  - hash_file — Genera un valor de hash utilizando el contenido de un fichero dado
  - hash_final — Finaliza un hachaje incremental y devuelve el resultado de la huella digital
  - hash_hkdf — Genera una derivación de clave HKDF a partir de una clave de entrada proporcionada
  - hash_hmac — Genera un valor de clave de hash utilizando el método HMAC
  - hash_hmac_algos — Devuelve una lista de algoritmos de hash registrados adecuados para hash_hmac
  - hash_hmac_file — Genera un valor de clave de hash utilizando el método HMAC y el contenido de un fichero dado
  - hash_init — Inicializa un contexto de hachado incremental
  - hash_pbkdf2 — Genera una clave PBKDF2 derivada de la contraseña proporcionada
  - hash_update — Añade datos en el contexto de hash activo
  - hash_update_file — Se añaden datos en un contexto de hash activo a partir de un fichero
  - hash_update_stream — Introduce datos en un contexto de hash activo desde un flujo abierto

# Mcrypt

# Introducción

Advertencia

Esta funcionalidad está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0.

Las alternativas a esta funcionalidad incluyen:

- Sodium (disponible a partir de PHP 7.2.0)
- OpenSSL

> Nota: Esta extensión ha sido movida al módulo » PECL y no será integrada en PHP a partir de PHP 7.2.0.

Estas funciones permiten acceder a la biblioteca mcrypt, que dispone de una gran variedad de algoritmos de cifrado, como DES, TripleDES, Blowfish (por omisión), 3-WAY, SAFER-SK64, SAFER-SK128, TWOFISH, TEA, RC2 y GOST en modos CBC, OFB, CFB y ECB. Asimismo, aceptan también RC6 e IDEA que son considerados como "no libres". CFB/OFB es de 8 bits por omisión.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución
- Tipos de recursos

## Requerimientos

Estas funciones utilizan » mcrypt. Para utilizar esta biblioteca, descargue el fichero libmcrypt-x.x.tar.gz desde » http://mcrypt.sourceforge.net/ y siga las instrucciones de instalación proporcionadas.

Se requiere la versión 2.5.6 o posterior de la biblioteca libmcrypt.

Los usuarios de Windows encontrarán la biblioteca en la versión Windows de PHP 5.3. La versión binaria de Windows de PHP 5.3 utiliza la versión estática de la biblioteca MCrypt, no se necesita ninguna DLL.

Si se compila PHP con la biblioteca `libmcrypt 2.4.x`, se admiten los siguientes algoritmos: `"CAST"`, `"LOKI97"`, `"RIJNDAEL"`, `"SAFERPLUS"`, `"SERPENT"` así como los siguientes cifrados: `"ENIGMA"` (cifrado), `"PANAMA"`, `"RC4"` y `"WAKE"`. Con `libmcrypt 2.4.x` otro modo de cifrado está disponible: `"nOFB"`.

## Instalación

Esta extensión ha sido movida al módulo » PECL y no será integrada en PHP a partir de PHP 7.2.0

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/mcrypt.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración mcrypt
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
mcrypt.algorithms_dir | `null` | `INI_ALL` |
mcrypt.modes_dir | `null` | `INI_ALL` |

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`mcrypt.algorithms_dir` string
  El directorio que contiene los algoritmos. Por omisión es el directorio indicado durante la compilación de libmcrypt, típicamente se trata de /usr/local/lib/libmcrypt. Consulte mcrypt_list_algorithms() para más detalles.
`mcrypt.modes_dir` string
  El directorio que contiene los modos. Por omisión es el directorio indicado durante la compilación de libmcrypt, típicamente se trata de /usr/local/lib/libmcrypt. Consulte mcrypt_list_modes() para más detalles.

## Tipos de recursos

mcrypt_module_open() devuelve un puntero de cifrado.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

Mcrypt puede operar en 4 modos de cifrado (`CBC`, `OFB`, `CFB` y `ECB`). Si está vinculado contra libmcrypt-2.4.x o posterior, las funciones pueden operar asimismo en modo `nOFB` y en modo `STREAM`. A continuación se encuentra una lista con todos los modos de cifrado soportados con las constantes que están definidas para el modo de cifrado. Para una referencia más completa y discusiones, ver Applied Cryptography by Schneier (ISBN 0-471-11709-9).

- `MCRYPT_MODE_ECB` (`electronic codebook`) es un modo de cifrado por bloques que generalmente es inapropiado para la mayoría de los usos. El uso de este modo está desaconsejado.
- `MCRYPT_MODE_CBC` (`cipher block chaining`) es un modo de cifrado por bloques que es considerablemente más seguro que el modo `ECB`.
- `MCRYPT_MODE_CFB` (`cipher feedback, en modo de 8 bits`) es un modo de cifrado por flujo. Se recomienda utilizar el modo `NCFB` en lugar del modo `CFB`.
- `MCRYPT_MODE_OFB` (`output feedback, en 8 bits`) es un modo de cifrado por flujo comparable a `CFB`, pero puede ser utilizado en aplicaciones donde la propagación de errores no puede ser tolerada. Se recomienda utilizar el modo `NOFB` en lugar del modo `OFB`.
- `MCRYPT_MODE_NOFB` (`output feedback, en modo de n bits`) es comparable al modo `OFB`, pero opera sobre el tamaño de bloque completo del algoritmo.
- `MCRYPT_MODE_STREAM` es un modo adicional, para incluir algoritmos de flujo tales como `"WAKE"` o `"RC4"`.

Mcrypt soporta otros modos de operación para los cuales no hay constantes predefinidas. Pueden ser utilizados pasando un string en lugar de las constantes faltantes.

- `"ctr"` (`counter mode`) es un modo de cifrado por flujo.
- `"ncfb"` (`cipher feedback, en modo de n bits`) es comparable al modo `CFB`, pero opera sobre el tamaño de bloque completo del algoritmo.

A continuación se presentan algunos otros modos y métodos de compresión:

`MCRYPT_ENCRYPT` (int)
`MCRYPT_DECRYPT` (int)
`MCRYPT_DEV_RANDOM` (int)
`MCRYPT_DEV_URANDOM` (int)
`MCRYPT_RAND` (int)

# Modos de cifrado Mcrypt

A continuación se presenta una lista no exhaustiva de los modos de cifrado de la extensión mcrypt. Para disponer de una lista completa de los cifrados soportados, consulte las definiciones en el fichero mcrypt.h. La regla general con la API mcrypt-2.2.x es que se puede acceder al modo de cifrado desde PHP con la constante MCRYPT_ciphername. Con la biblioteca libmcrypt-2.4.x y libmcrypt-2.5.x, estas constantes funcionan siempre, pero es posible especificar el nombre del cifrado en una cadena, al llamar a mcrypt_module_open().

- MCRYPT_3DES
- MCRYPT_ARCFOUR_IV (libmcrypt > 2.4.x únicamente)
- MCRYPT_ARCFOUR (libmcrypt > 2.4.x únicamente)
- MCRYPT_BLOWFISH
- MCRYPT_CAST_128
- MCRYPT_CAST_256
- MCRYPT_CRYPT
- MCRYPT_DES
- MCRYPT_DES_COMPAT (libmcrypt 2.2.x únicamente)
- MCRYPT_ENIGMA (libmcrypt > 2.4.x únicamente, alias de MCRYPT_CRYPT)
- MCRYPT_GOST
- MCRYPT_IDEA (no libre)
- MCRYPT_LOKI97 (libmcrypt > 2.4.x únicamente)
- MCRYPT_MARS (libmcrypt > 2.4.x únicamente, no libre)
- MCRYPT_PANAMA (libmcrypt > 2.4.x únicamente)
- MCRYPT_RIJNDAEL_128 (libmcrypt > 2.4.x únicamente)
- MCRYPT_RIJNDAEL_192 (libmcrypt > 2.4.x únicamente)
- MCRYPT_RIJNDAEL_256 (libmcrypt > 2.4.x únicamente)
- MCRYPT_RC2
- MCRYPT_RC4 (libmcrypt 2.2.x únicamente)
- MCRYPT_RC6 (libmcrypt > 2.4.x únicamente)
- MCRYPT_RC6_128 (libmcrypt 2.2.x únicamente)
- MCRYPT_RC6_192 (libmcrypt 2.2.x únicamente)
- MCRYPT_RC6_256 (libmcrypt 2.2.x únicamente)
- MCRYPT_SAFER64
- MCRYPT_SAFER128
- MCRYPT_SAFERPLUS (libmcrypt > 2.4.x únicamente)
- MCRYPT_SERPENT(libmcrypt > 2.4.x únicamente)
- MCRYPT_SERPENT_128 (libmcrypt 2.2.x únicamente)
- MCRYPT_SERPENT_192 (libmcrypt 2.2.x únicamente)
- MCRYPT_SERPENT_256 (libmcrypt 2.2.x únicamente)
- MCRYPT_SKIPJACK (libmcrypt > 2.4.x únicamente)
- MCRYPT_TEAN (libmcrypt 2.2.x únicamente)
- MCRYPT_THREEWAY
- MCRYPT_TRIPLEDES (libmcrypt > 2.4.x únicamente)
- MCRYPT_TWOFISH (para las versiones antiguas de mcrypt 2.x o mcrypt > 2.4.x )
- MCRYPT_TWOFISH128 (TWOFISHxxx está disponible en las nuevas versiones 2.x, pero no en las versiones 2.4.x)
- MCRYPT_TWOFISH192
- MCRYPT_TWOFISH256
- MCRYPT_WAKE (libmcrypt > 2.4.x únicamente)
- MCRYPT_XTEA (libmcrypt > 2.4.x únicamente)

Se debe (modo `CFB` y `OFB`) o puede (modo `CBC`) proporcionar un vector de inicialización (IV) para estos modos de cifrado. IV debe ser único, y tener el mismo valor en el cifrado y en el descifrado. Para datos que serán almacenados después del cifrado, se puede tomar el resultado de una función como MD5, aplicada al nombre del fichero. De lo contrario, se puede enviar IV con los datos cifrados, (consulte el capítulo 9.3 de Applied Cryptography by Schneier (ISBN 0-471-11709-9) de Schneier (ISBN 0-471-11709-9) para más detalles sobre el tema).

# Funciones Mcrypt

# mcrypt_create_iv

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_create_iv — Crea un vector de inicialización (IV) a partir de una fuente aleatoria

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0.

Las alternativas a esta función incluyen:

- random_bytes()

### Descripción

function mcrypt_create_iv(int `$size`, int `$source` = MCRYPT_DEV_URANDOM): string

mcrypt_create_iv() crea un IV (vector de inicialización) a partir de una fuente aleatoria.

El vector de inicialización es el único medio de proporcionar una inicialización de reemplazo a los métodos de inicialización. Este vector no necesita ser particularmente secreto, aunque es mejor que lo sea. Puede enviarse con los documentos cifrados sin perder seguridad.

### Parámetros

`size`
  El tamaño del vector.
`source`
  La fuente de un IV. La fuente puede ser `MCRYPT_RAND` (el generador de números aleatorios del sistema), `MCRYPT_DEV_RANDOM` (lee los datos desde /dev/random) y `MCRYPT_DEV_URANDOM` (lee los datos desde /dev/urandom). Antes de la versión 5.3.0, `MCRYPT_RAND` era la única constante soportada por Windows. Tenga en cuenta que el valor por defecto de este parámetro era `MCRYPT_DEV_RANDOM` antes de PHP 5.6.0.

  > Nota: Tenga en cuenta que la constante `MCRYPT_DEV_RANDOM` puede bloquearse mientras espera que haya más entropía disponible.

### Valores devueltos

Devuelve el vector de inicialización, o bien `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con mcrypt_create_iv()

    <?php
         $size = mcrypt_get_iv_size(MCRYPT_CAST_256, MCRYPT_MODE_CFB);
         $iv = mcrypt_create_iv($size, MCRYPT_DEV_RANDOM);
         ?>

### Ver también

- » http://www.ciphersbyritter.com/GLOSSARY.HTM#IV
- » http://www.quadibloc.com/crypto/co0409.htm
- Capítulo 9.3 de Applied Cryptography by Schneier (ISBN 0-471-11709-9)
- random_bytes() - Obtiene bytes aleatorios criptográficamente seguros

# mcrypt_decrypt

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_decrypt — Descifra un texto con los parámetros dados

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_decrypt(
string `$cipher`,
string `$key`,
string `$data`,
string `$mode`,
string `$iv` = ?
): string|false

Descifra los datos `data` y devuelve los datos descifrados.

### Parámetros

`cipher`
  Una de las constantes `MCRYPT_ciphername`, o el nombre del algoritmo como cadena.
`key`
  La clave utilizada durante el cifrado de los datos. Si el tamaño de la clave proporcionada no es soportado por el cipher, la función emitirá una advertencia y devolverá `false`
`data`
  Los datos que serán descifrados utilizando los parámetros `cipher` y `mode`. Si el tamaño de los datos no corresponde a n * el tamaño del bloque, los datos serán completados con '`\0`'.
`mode`
  Una de las constantes `MCRYPT_MODE_modename`, o una de las siguientes cadenas: "ecb", "cbc", "cfb", "ofb", "nofb" o "stream".
`iv`
  Utilizado para la inicialización en los modos CBC, CFB, OFB, y en algunos algoritmos en modo STREAM. Si el tamaño del IV proporcionado no es soportado por el modo de encadenamiento o no se proporcionó un IV, pero el modo de encadenamiento requiere uno, la función emitirá una advertencia y devolverá `false`.

### Valores devueltos

Devuelve los datos descifrados en forma de string o `false` si ocurre un error.

### Ver también

- mcrypt_encrypt() - Cifra un texto

# mcrypt_enc_get_algorithms_name

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_algorithms_name — Devuelve el nombre del algoritmo de cifrado

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_enc_get_algorithms_name(resource `$td`): string

mcrypt_enc_get_algorithms_name() devuelve el nombre de el algoritmo utilizado por `td`.

### Parámetros

`td`
  El recurso de cifrado.

### Valores devueltos

Devuelve el nombre del algoritmo actual, en forma de string

### Ejemplos

Ejemplo #1 Ejemplo con mcrypt_enc_get_algorithms_name()

    <?php
         $td = mcrypt_module_open (MCRYPT_CAST_256, '', MCRYPT_MODE_CFB, '');
         echo mcrypt_enc_get_algorithms_name($td). "\n";

         $td = mcrypt_module_open ('cast-256', '', MCRYPT_MODE_CFB, '');
         echo mcrypt_enc_get_algorithms_name($td). "\n";
         ?>

El ejemplo anterior mostrará:

    CAST-256
    CAST-256

# mcrypt_enc_get_block_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_block_size — Devuelve el tamaño de bloque de un algoritmo

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_enc_get_block_size(resource `$td`): int

Obtiene el tamaño de bloque de un algoritmo.

### Parámetros

`td`
  El gestor de ficheros.

### Valores devueltos

Devuelve el tamaño de bloque del algoritmo, en bytes.

# mcrypt_enc_get_iv_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_iv_size — Devuelve el tamaño del VI de un algoritmo

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_enc_get_iv_size(resource `$td`): int

Esta función devuelve el tamaño del VI del algoritmo designado por `td`, en bytes. Si el valor devuelto es 0, es que el algoritmo no requiere de VI. Un VI es requerido en modo `"cbc"`, `"cfb"` y `"ofb"`, y a veces en modo `"stream"`.

### Parámetros

`td`
  El gestor de ficheros.

### Valores devueltos

Devuelve el tamaño del IV, o `0` si el IV es ignorado por el algoritmo.

# mcrypt_enc_get_key_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_key_size — Devuelve el tamaño máximo de la clave para un modo

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_enc_get_key_size(resource `$td`): int

Devuelve el tamaño máximo de la clave para un modo dado.

### Parámetros

`td`
  El gestor de fichero.

### Valores devueltos

Devuelve el tamaño máximo de la clave para el modo dado.

# mcrypt_enc_get_modes_name

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_modes_name — Devuelve el nombre del modo

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_enc_get_modes_name(resource `$td`): string

Devuelve el nombre del modo.

### Parámetros

`td`
  El recurso de cifrado.

### Valores devueltos

Devuelve el nombre, en forma de string.

### Ejemplos

Ejemplo #1 Ejemplo con mcrypt_enc_get_modes_name()

    <?php
    $td = mcrypt_module_open (MCRYPT_CAST_256, '', MCRYPT_MODE_CFB, '');
    echo mcrypt_enc_get_modes_name($td). "\n";

    $td = mcrypt_module_open ('cast-256', '', 'ecb', '');
    echo mcrypt_enc_get_modes_name($td). "\n";
    ?>

El ejemplo anterior mostrará:

    CFB
    ECB

# mcrypt_enc_get_supported_key_sizes

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_supported_key_sizes — Devuelve un array que contiene los tamaños de clave admitidos por un algoritmo

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_enc_get_supported_key_sizes(resource `$td`): array

mcrypt_enc_get_supported_key_sizes() lee los tamaños de clave soportados por el algoritmo actual del recurso de cifrado `td`.

### Parámetros

`td`
  El recurso de cifrado.

### Valores devueltos

Devuelve un array que contiene los tamaños de clave soportados por el algoritmo designado por `td`. Si devuelve un array vacío, es que todas las claves entre 1 y mcrypt_enc_get_key_size() son admitidas por el algoritmo.

### Ejemplos

Ejemplo #1 Ejemplo con mcrypt_enc_get_supported_key_sizes()

    <?php
        $td = mcrypt_module_open('rijndael-256', '', 'ecb', '');
        var_dump(mcrypt_enc_get_supported_key_sizes($td));
    ?>

El ejemplo anterior mostrará:

    array(3) {
      [0]=>
      int(16)
      [1]=>
      int(24)
      [2]=>
      int(32)
    }

# mcrypt_enc_is_block_algorithm

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_is_block_algorithm — Comprueba si el cifrado es por bloques en un algoritmo

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_enc_is_block_algorithm(resource `$td`): bool

Comprueba si el cifrado es por bloques en un algoritmo.

### Parámetros

`td`
  El recurso de cifrado.

### Valores devueltos

Devuelve `true` si el algoritmo utilizado es un algoritmo por bloques, y `false` si es un algoritmo por flujo.

# mcrypt_enc_is_block_algorithm_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_is_block_algorithm_mode — Comprueba si el modo de cifrado es por bloques

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_enc_is_block_algorithm_mode(resource `$td`): bool

Comprueba si el modo de cifrado es por bloques (por ejemplo, `false` para un flujo, y `true` para `"cbc"`, `"cfb"`, `"ofb"`).

### Parámetros

`td`
  El recurso de cifrado.

### Valores devueltos

Devuelve `true` si este modo utiliza algoritmos por bloques, y `false` en caso contrario.

# mcrypt_enc_is_block_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_is_block_mode — Comprueba si el modo devuelve los datos por bloques

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_enc_is_block_mode(resource `$td`): bool

Comprueba si el modo devuelve los datos por bloques (por ejemplo, `true` para `"cbc"` y `"ecb"`, y `false` para `"cfb"` y un flujo).

### Parámetros

`td`
  El recurso de cifrado.

### Valores devueltos

Devuelve `true` si el modo devuelve bloques de bytes, o bien `false` si solo devuelve bytes.

# mcrypt_enc_self_test

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_self_test — Prueba un módulo abierto

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_enc_self_test(resource `$td`): int

Realiza una prueba del módulo abierto y designado por `td`.

### Parámetros

`td`
  El recurso de cifrado.

### Valores devueltos

Devuelve `0` en caso de éxito o un int negativo en caso de fallo.

# mcrypt_encrypt

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_encrypt — Cifra un texto

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_encrypt(
string `$cipher`,
string `$key`,
string `$data`,
string `$mode`,
string `$iv` = ?
): string|false

mcrypt_encrypt() cifra los datos y devuelve los datos cifrados.

### Parámetros

`cipher`
  Una de las constantes `MCRYPT_ciphername`, o el nombre del algoritmo como cadena.
`key`
  La clave con la que se cifrarán los datos. Si el tamaño de la clave proporcionada no es compatible con el cipher, la función emitirá una advertencia y devolverá `false`
`data`
  Los datos que se cifrarán, con el `cipher` y el `mode` indicado. Si el tamaño de los datos no es un múltiplo del tamaño de bloque, los datos se rellenarán con caracteres '`\0`', según sea necesario. El texto cifrado devuelto puede ser más largo que el tamaño de los datos pasados como argumento a través de `data`.
`mode`
  Una de las constantes `MCRYPT_MODE_modename`, o una de las siguientes cadenas: "ecb", "cbc", "cfb", "ofb", "nofb" o "stream".
`iv`
  Utilizado para la inicialización en los modos CBC, CFB, OFB, y en algunos algoritmos en modo STREAM. Si el tamaño del IV proporcionado no es soportado por el modo de encadenamiento o no se proporcionó un IV, pero el modo de encadenamiento requiere uno, la función emitirá una advertencia y devolverá `false`.

### Valores devueltos

Devuelve los datos cifrados, como string o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con mcrypt_encrypt()

    <?php
        # --- CIFRADO ---

        # la clave debería ser un binario aleatorio, utilice la función scrypt, bcrypt
        # o PBKDF2 para convertir una cadena de caracteres en una clave.
        # La clave se especifica utilizando notación hexadecimal.
        $key = pack('H*', "bcb04b7e103a0cd8b54763051cef08bc55abe029fdebae5e1d417e2ffb2a00a3");

        # Muestra el tamaño de la clave utilizada; claves de 16, 24 o 32 bytes para
        # AES-128, 192 y 256 respectivamente.
        $key_size =  strlen($key);
        echo "Tamaño de la clave: " . $key_size . "\n";

        $plaintext = "Esta cadena de caracteres ha sido cifrada en AES-256 / CBC / ZeroBytePadding.";

        # Crea un IV aleatorio para usar con el cifrado CBC
        $iv_size = mcrypt_get_iv_size(MCRYPT_RIJNDAEL_128, MCRYPT_MODE_CBC);
        $iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);

        # Crea un texto cifrado compatible con AES (Rijndael block size = 128)
        # para mantener el texto confidencial.
        # Solo aplicable para entradas codificadas que nunca terminan
        # con el valor 00h (debido a la eliminación predeterminada de ceros finales)
        $ciphertext = mcrypt_encrypt(MCRYPT_RIJNDAEL_128, $key,
                                     $plaintext, MCRYPT_MODE_CBC, $iv);

        # Se añade el IV al inicio del texto cifrado para hacerlo disponible para el descifrado
        $ciphertext = $iv . $ciphertext;

        # Codifica el texto cifrado resultante para que pueda ser representado por una cadena de caracteres
        $ciphertext_base64 = base64_encode($ciphertext);

        echo  $ciphertext_base64 . "\n";

        # === ADVERTENCIA ===

        # El texto cifrado resultante no contiene integridad ni autenticación
        # y no está protegido contra ataques de tipo "oracle padding".

        # --- DESCIFRADO ---

        $ciphertext_dec = base64_decode($ciphertext_base64);

        # Obtiene el IV, iv_size debe haber sido creado utilizando la función
        # mcrypt_get_iv_size()
        $iv_dec = substr($ciphertext_dec, 0, $iv_size);

        # Obtiene el texto del cipher (todo, excepto $iv_size del inicio)
        $ciphertext_dec = substr($ciphertext_dec, $iv_size);

        # Se deben eliminar los caracteres de valor 00h del final del texto plano
        $plaintext_dec = mcrypt_decrypt(MCRYPT_RIJNDAEL_128, $key,
                                        $ciphertext_dec, MCRYPT_MODE_CBC, $iv_dec);

        echo  $plaintext_dec . "\n";
    ?>

El ejemplo anterior mostrará:

    Tamaño de la clave: 32
    ENJW8mS2KaJoNB5E5CoSAAu0xARgsR1bdzFWpEn+poYw45q+73az5kYi4j+0haevext1dGrcW8Qi59txfCBV8BBj3bzRP3dFCp3CPQSJ8eU=
    Esta cadena de caracteres ha sido cifrada en AES-256 / CBC / ZeroBytePadding.

### Ver también

- mcrypt_decrypt() - Descifra un texto con los parámetros dados
- mcrypt_module_open() - Abre el módulo del algoritmo y del modo a utilizar

# mcrypt_generic

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic — Cifra los datos

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_generic(resource `$td`, string `$data`): string

mcrypt_generic() cifra los datos `data`. Los datos se completan con "`\0`" para obtener un tamaño múltiplo del tamaño de un bloque. Devuelve los datos cifrados. Tenga en cuenta que la longitud del string devuelto puede ser más larga que la pasada como argumento, debido al relleno.

Si se desea almacenar los datos cifrados en una base de datos asegúrese de almacenar el string completo devuelto por esta función, de lo contrario el string no se descifrará correctamente. Si el string original contiene 10 caracteres y el tamaño de un bloque es de 8 (utilice mcrypt_enc_get_block_size() para determinar este tamaño), se necesitará al menos 16 caracteres en el campo de la base de datos. Tenga en cuenta que el string devuelto por mdecrypt_generic() tendrá 16 caracteres de longitud... utilice `rtrim($str, "\0")` para eliminar el relleno.

Por ejemplo, si se almacenan los datos en una base de datos MySQL, recuerde que los campos de tipo VARCHAR eliminan automáticamente los espacios adicionales durante la inserción. Como los datos cifrados pueden terminar con un espacio (ASCII 32), los datos se dañarán por esta eliminación. Almacene los datos en un campo de tipo TINYBLOB/TINYTEXT (o más grande) para que todo funcione normalmente.

### Parámetros

`td`
  El recurso de cifrado. El manejador de cifrado `td` debe ser inicializado con la función mcrypt_generic_init(), con una clave y un VI, antes de llamar a esta función. Cuando el cifrado se realiza, se deben liberar los buffers llamando a la función mcrypt_generic_deinit(). Consulte mcrypt_module_open() para un ejemplo.
`data`
  Los datos a cifrar.

### Valores devueltos

Devuelve los datos cifrados.

### Ver también

- mdecrypt_generic() - Desencripta los datos
- mcrypt_generic_init() - Inicializa todos los buffers necesarios
- mcrypt_generic_deinit() - Prepara el módulo para la descarga

# mcrypt_generic_deinit

(PHP 4 >= 4.0.7, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic_deinit — Prepara el módulo para la descarga

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_generic_deinit(resource `$td`): bool

Prepara el módulo de cifrado `td` para la descarga. Todos los búferes se vacían, pero el módulo no se descarga. Se debe llamar a mcrypt_module_close() manualmente (aunque PHP lo hará por usted al final del script).

### Parámetros

`td`
  El recurso de cifrado.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- mcrypt_module_open() - Abre el módulo del algoritmo y del modo a utilizar
- mcrypt_generic_init() - Inicializa todos los buffers necesarios

# mcrypt_generic_init

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic_init — Inicializa todos los buffers necesarios

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_generic_init(resource `$td`, string `$key`, string `$iv`): int

Se debe llamar a mcrypt_generic_init() antes de cada llamada a mcrypt_generic() o mdecrypt_generic().

### Parámetros

`td`
  El recurso de cifrado.
`key`
  El tamaño máximo de la clave debe ser el devuelto por mcrypt_enc_get_key_size() y todos los valores inferiores también serán válidos.
`iv`
  El vector de inicialización (VI) debe tener el tamaño de un bloque, pero se debe leer su tamaño llamando a mcrypt_enc_get_iv_size(). VI es ignorado en modo ECB. VI DEBE existir en modos `"CFB"`, `"CBC"`, `"STREAM"`, `"nOFB"` y `"OFB"`. Debe ser aleatorio y único (pero no secreto). El mismo VI debe ser utilizado para el cifrado y el descifrado. Si no se desea utilizar, se puede rellenar con ceros, pero no se recomienda.

### Valores devueltos

Devuelve un valor negativo en caso de error: -3 si el tamaño de la clave es incorrecto, -4 cuando hay un problema de asignación de memoria y cualquier otro valor en caso de error desconocido. Si ocurre un error, se muestra una alerta. `false` es devuelto si se pasan parámetros incorrectos a la función.

### Ver también

- mcrypt_module_open() - Abre el módulo del algoritmo y del modo a utilizar

# mcrypt_get_block_size

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_block_size — Devuelve el tamaño de bloques de un cifrado

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_get_block_size(int `$cipher`): int|false
function mcrypt_get_block_size(string `$cipher`, string `$mode`): int|false

El primer prototipo se utiliza cuando PHP está compilado con la biblioteca libmcrypt 2.2.x, el segundo cuando está compilado con libmcrypt 2.4.x o 2.5.x.

mcrypt_get_block_size() sirve para leer el tamaño de bloques del cifrado `cipher` (en combinación con un modo de cifrado).

Se recomienda utilizar la función mcrypt_enc_get_block_size(), ya que utiliza el recurso devuelto por mcrypt_module_open().

### Parámetros

`cipher`
  Una de las constantes `MCRYPT_ciphername`, o el nombre del algoritmo como cadena.
`mode`
  Una de las constantes `MCRYPT_MODE_modename`, o una de las siguientes cadenas: "ecb", "cbc", "cfb", "ofb", "nofb" o "stream".

### Valores devueltos

Lee el tamaño de bloque, en forma de un int.

### Ejemplos

Ejemplo #1 Ejemplo con mcrypt_get_block_size()

Este ejemplo muestra cómo utilizar esta función cuando PHP está compilado con libmcrypt 2.4.x y 2.5.x.

    <?php
    echo mcrypt_get_block_size('tripledes', 'ecb'); // 8
    ?>

### Ver también

- mcrypt_get_key_size() - Devuelve el tamaño de la clave de cifrado
- mcrypt_enc_get_block_size() - Devuelve el tamaño de bloque de un algoritmo
- mcrypt_encrypt() - Cifra un texto

# mcrypt_get_cipher_name

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_cipher_name — Lee el nombre del cifrado utilizado

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_get_cipher_name(int `$cipher`): string
function mcrypt_get_cipher_name(string `$cipher`): string

mcrypt_get_cipher_name() devuelve el nombre del cifrado utilizado.

mcrypt_get_cipher_name() toma el número de cifrado (con libmcrypt 2.2.x) o toma el nombre del cifrado (con libmcrypt 2.4.x) como argumento, y devuelve el nombre del cifrado, o `false`, si no existe.

### Parámetros

`cipher`
  Una de las constantes `MCRYPT_ciphername`, o el nombre del algoritmo como cadena.

### Valores devueltos

Esta función devuelve el nombre del cipher o `false` si el cipher no existe.

### Ejemplos

Ejemplo #1 Ejemplo con mcrypt_get_cipher_name()

    <?php
    $cipher = MCRYPT_TripleDES;

    echo mcrypt_get_cipher_name($cipher);
    ?>

El ejemplo anterior mostrará:

    3DES

# mcrypt_get_iv_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_iv_size — Retorna el tamaño del VI utilizado por un par cifrado/modo

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_get_iv_size(string `$cipher`, string `$mode`): int

mcrypt_get_iv_size() retorna el tamaño del vector de inicialización (VI). Si el algoritmo no utiliza un vector de inicialización, se retorna cero.

Es más útil utilizar la función mcrypt_enc_get_iv_size(), ya que utiliza el recurso retornado por mcrypt_module_open().

### Parámetros

`cipher`
  Una de las constantes `MCRYPT_ciphername`, o el nombre del algoritmo como cadena.
`mode`
  Una de las constantes `MCRYPT_MODE_modename`, o una de las siguientes cadenas: "ecb", "cbc", "cfb", "ofb", "nofb" o "stream". El VI es ignorado en modo ECB, ya que este modo no lo requiere. Debe tener el mismo VI (punto de partida) durante el cifrado y el descifrado, de lo contrario, el cifrado fallará.

### Valores devueltos

Retorna el tamaño del vector de inicialización (VI), en bytes. En caso de error, la función retorna `false`. Si el vector de inicialización no es necesario, se retorna 0.

### Ejemplos

Ejemplo #1 Ejemplo con mcrypt_get_iv_size()

    <?php
    echo mcrypt_get_iv_size(MCRYPT_CAST_256, MCRYPT_MODE_CFB) . "\n";

    echo mcrypt_get_iv_size('des', 'ecb') . "\n";
    ?>

### Ver también

- mcrypt_get_block_size() - Devuelve el tamaño de bloques de un cifrado
- mcrypt_enc_get_iv_size() - Devuelve el tamaño del VI de un algoritmo
- mcrypt_create_iv() - Crea un vector de inicialización (IV) a partir de una fuente aleatoria

# mcrypt_get_key_size

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_key_size — Devuelve el tamaño de la clave de cifrado

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_get_key_size(int `$cipher`): int|false
function mcrypt_get_key_size(string `$cipher`, string `$mode`): int|false

La primera sintaxis utiliza libmcrypt 2.2.x, y la segunda libmcrypt 2.4.x o posterior.

mcrypt_get_key_size() se utiliza para obtener el tamaño de la clave del cifrado `cipher`.

Es más interesante utilizar la función mcrypt_enc_get_key_size() ya que utiliza el recurso devuelto por la función mcrypt_module_open().

### Parámetros

`cipher`
  Una de las constantes `MCRYPT_ciphername`, o el nombre del algoritmo como cadena.
`mode`
  Una de las constantes `MCRYPT_MODE_modename`, o una de las siguientes cadenas: "ecb", "cbc", "cfb", "ofb", "nofb" o "stream".

### Valores devueltos

Devuelve el tamaño máximo soportado para una clave del algoritmo, en bytes o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con mcrypt_get_key_size()

    <?php
    echo mcrypt_get_key_size('tripledes', 'ecb');
    ?>

El ejemplo anterior muestra el uso de la función cuando ha sido compilada con la biblioteca 2.4.x o 2.5.x.

El ejemplo anterior mostrará:

    24

### Ver también

- mcrypt_get_block_size() - Devuelve el tamaño de bloques de un cifrado
- mcrypt_enc_get_key_size() - Devuelve el tamaño máximo de la clave para un modo
- mcrypt_encrypt() - Cifra un texto

# mcrypt_list_algorithms

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_list_algorithms — Lista todos los algoritmos de cifrado soportados

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_list_algorithms(string `$lib_dir` = ini_get("mcrypt.algorithms_dir")): array

Lista todos los algoritmos de cifrado de `lib_dir`.

### Parámetros

`lib_dir`
  Especifica el directorio donde se encuentran los algoritmos. Si se omite, se utiliza el valor de la directiva `mcrypt.algorithms_dir` del fichero php.ini.

### Valores devueltos

Devuelve un array con los algoritmos soportados.

### Ejemplos

Ejemplo #1 Ejemplo con mcrypt_list_algorithms()

    <?php
    $algorithms = mcrypt_list_algorithms();
    print_r($algorithms);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => cast-128
        [1] => gost
        [2] => rijndael-128
        [3] => twofish
        [4] => arcfour
        [5] => cast-256
        [6] => loki97
        [7] => rijndael-192
        [8] => saferplus
        [9] => wake
        [10] => blowfish-compat
        [11] => des
        [12] => rijndael-256
        [13] => serpent
        [14] => xtea
        [15] => blowfish
        [16] => enigma
        [17] => rc2
        [18] => tripledes
    )

# mcrypt_list_modes

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_list_modes — Lista todos los modos de cifrado soportados

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_list_modes(string `$lib_dir` = ini_get("mcrypt.modes_dir")): array

Lista todos los modos de cifrado de `lib_dir`.

### Parámetros

`lib_dir`
  Especifica el directorio donde se encuentran todos los modos. Si se omite, se utiliza el valor de la directiva `mcrypt.modes_dir` en el php.ini.

### Valores devueltos

Devuelve un array con todos los modos soportados.

### Ejemplos

Ejemplo #1 Ejemplo con mcrypt_list_modes()

    <?php
    $modes = mcrypt_list_modes();

    foreach ($modes as $mode) {
        echo "$mode <br />\n";
    }
    ?>

El ejemplo anterior mostrará todos los modos soportados en el directorio por omisión. Si el modo no está definido por la directiva `mcrypt.modes_dir` del php.ini, se utilizará el directorio por omisión de mcrypt (el directorio /usr/local/lib/libmcrypt).

# mcrypt_module_close

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_close — Libera el módulo de cifrado

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_module_close(resource `$td`): bool

Libera el módulo `td`.

### Parámetros

`td`
  El recurso de cifrado.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- mcrypt_module_open() - Abre el módulo del algoritmo y del modo a utilizar

# mcrypt_module_get_algo_block_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_get_algo_block_size — Devuelve el tamaño de bloques de un algoritmo

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_module_get_algo_block_size(string `$algorithm`, string `$lib_dir` = ?): int

Devuelve el tamaño de bloques de un algoritmo.

### Parámetros

`algorithm`
  El nombre del algoritmo.
`lib_dir`
  El parámetro opcional `lib_dir` contiene la ruta de acceso hasta el módulo del algoritmo en el sistema.

### Valores devueltos

Devuelve el tamaño de bloques de un algoritmo, en bytes.

# mcrypt_module_get_algo_key_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_get_algo_key_size — Devuelve el tamaño máximo de clave

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_module_get_algo_key_size(string `$algorithm`, string `$lib_dir` = ?): int

Devuelve el tamaño máximo de clave.

### Parámetros

`algorithm`
  El nombre del algoritmo.
`lib_dir`
  El parámetro opcional `lib_dir` contiene la ruta hasta el módulo del algoritmo en el sistema.

### Valores devueltos

Devuelve el tamaño máximo de la clave soportada por el algoritmo `algorithm`.

# mcrypt_module_get_supported_key_sizes

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_get_supported_key_sizes — Devuelve un array que contiene los tamaños de claves soportados por el algoritmo abierto

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_module_get_supported_key_sizes(string `$algorithm`, string `$lib_dir` = ?): array

Devuelve un array que contiene los tamaños de claves soportados por el algoritmo de cifrado `algorithm`. Si devuelve un array vacío, entonces todas las claves entre 1 y mcrypt_module_get_algo_key_size() son soportadas por el algoritmo.

### Parámetros

`algorithm`
  El algoritmo a utilizar.
`lib_dir`
  El parámetro opcional `lib_dir` puede contener la ruta de acceso del directorio de instalación del módulo, en el sistema.

### Valores devueltos

Devuelve un array que contiene los tamaños de claves soportados por el algoritmo de cifrado `algorithm`. Si devuelve un array vacío, entonces todas las claves entre 1 y mcrypt_module_get_algo_key_size() son soportadas por el algoritmo.

### Ver también

- mcrypt_enc_get_supported_key_sizes() - Devuelve un array que contiene los tamaños de clave admitidos por un algoritmo

# mcrypt_module_is_block_algorithm

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_is_block_algorithm — Indica si un algoritmo funciona por bloques

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_module_is_block_algorithm(string `$algorithm`, string `$lib_dir` = ?): bool

Esta función devuelve `true` si `algorithm` es un algoritmo por bloques, o `false` si es un algoritmo por flujo.

### Parámetros

`algorithm`
  El algoritmo a verificar.
`lib_dir`
  El parámetro opcional `lib_dir` puede contener la ruta donde se encuentran los módulos de los algoritmos en el disco del sistema.

### Valores devueltos

Devuelve `true` si el algoritmo especificado es un algoritmo por bloques o `false` si es un algoritmo por flujo.

# mcrypt_module_is_block_algorithm_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_is_block_algorithm_mode — Indica si un modo funciona por bloques

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_module_is_block_algorithm_mode(string `$mode`, string `$lib_dir` = ?): bool

Esta función devuelve `true` si el modo debe ser utilizado con un algoritmo por bloques, de lo contrario, devuelve `false` (i.e. `false` para un flujo, y `true` para cbc, cfb, ofb).

### Parámetros

`mode`
  El modo a verificar.
`lib_dir`
  El argumento opcional `lib_dir` puede contener el directorio donde los módulos de algoritmo se encuentran en el sistema.

### Valores devueltos

Esta función devuelve `true` si el modo debe ser utilizado con un algoritmo por bloques, de lo contrario, devuelve `false` (i.e. `false` para un flujo, y `true` para cbc, cfb, ofb).

# mcrypt_module_is_block_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_is_block_mode — Indica si un modo trabaja por bloques

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_module_is_block_mode(string `$mode`, string `$lib_dir` = ?): bool

Esta función devuelve `true` si este modo proporciona bloques de bytes o `false` si solo produce bytes. (i.e. `true` para `"cbc"` y `"ecb"`, y `false` para `"cfb"` y `"stream"`).

### Parámetros

`mode`
  Una de las constantes `MCRYPT_MODE_modename`, o una de las siguientes cadenas: "ecb", "cbc", "cfb", "ofb", "nofb" o "stream".
`lib_dir`
  El parámetro opcional `lib_dir` contiene la ruta de acceso hasta el módulo del algoritmo en el sistema.

### Valores devueltos

Esta función devuelve `true` si este modo proporciona bloques de bytes o `false` si solo produce bytes. (i.e. `true` para `"cbc"` y `"ecb"`, y `false` para `"cfb"` y `"stream"`).

# mcrypt_module_open

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_open — Abre el módulo del algoritmo y del modo a utilizar

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_module_open(
string `$algorithm`,
string `$algorithm_directory`,
string `$mode`,
string `$mode_directory`
): resource

mcrypt_module_open() abre el módulo del algoritmo y del modo a utilizar. El nombre del algoritmo se especifica mediante el parámetro `algorithm` (por ejemplo: `"twofish"`), o bien una de las constantes `MCRYPT_ciphername`. La biblioteca se cierra al llamar a mcrypt_module_close().

### Parámetros

`algorithm`
  Una de las constantes `MCRYPT_ciphername`, o el nombre del algoritmo como cadena.
`algorithm_directory`
  El parámetro `algorithm_directory` se utiliza para localizar el módulo de cifrado. Cuando se especifica un nombre de directorio, se utilizará. Si se especifica una cadena vacía (`""`), se utilizará el valor definido en la directiva `mcrypt.algorithms_dir` del fichero php.ini. Cuando no está definida, el directorio por omisión utilizado será aquel en el que se encuentre la biblioteca libmcrypt (habitualmente, /usr/local/lib/libmcrypt).
`mode`
  Una de las constantes `MCRYPT_MODE_modename`, o una de las siguientes cadenas: "ecb", "cbc", "cfb", "ofb", "nofb" o "stream".
`mode_directory`
  El parámetro `mode_directory` se utiliza para localizar el módulo de cifrado. Si se especifica un nombre de directorio, se utilizará. Cuando se especifica una cadena vacía (`""`), se utilizará el valor de la directiva `mcrypt.modes_dir` del fichero php.ini. Si no está definida, el directorio por omisión utilizado será aquel en el que se encuentre la biblioteca libmcrypt (habitualmente /usr/local/lib/libmcrypt).

### Valores devueltos

Normalmente, esta función devuelve un descriptor de cifrado, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con mcrypt_module_open()

    <?php
    $td = mcrypt_module_open(MCRYPT_DES, '',
        MCRYPT_MODE_ECB, '/usr/lib/mcrypt-modes');

    $td = mcrypt_module_open('rijndael-256', '', 'ofb', '');
    ?>

La primera línea del ejemplo anterior intentará abrir el cifrado `DES`, en el directorio por omisión, y el modo `ECB` en el directorio /usr/lib/mcrypt-modes. El segundo ejemplo utiliza las cadenas como nombre para el cifrado y el modo. Esto solo funciona si la extensión está compilada con libmcrypt 2.4.x o 2.5.x.

Ejemplo #2 Utilización de mcrypt_module_open() para cifrar

    <?php
    /* Carga un cifrado */
    $td = mcrypt_module_open('rijndael-256', '', 'ofb', '');

    /* Crea el VI y determina el tamaño de la clave */
    $iv = mcrypt_create_iv(mcrypt_enc_get_iv_size($td), MCRYPT_DEV_RANDOM);
    $ks = mcrypt_enc_get_key_size($td);

    /* Crea la clave (ejemplo únicamente: MD5 no es un buen algoritmo de hash para esto) */
    $key = substr(hash('md5', 'very secret key'), 0, $ks);

    /* Inicializa el cifrado */
    mcrypt_generic_init($td, $key, $iv);

    /* Cifra los datos */
    $encrypted = mcrypt_generic($td, 'This is very important data');

    /* Libera el gestor de cifrado */
    mcrypt_generic_deinit($td);

    /* Inicializa el módulo de cifrado para el descifrado */
    mcrypt_generic_init($td, $key, $iv);

    /* Descifra los datos */
    $decrypted = mdecrypt_generic($td, $encrypted);

    /* Libera el gestor de descifrado y cierra el módulo */
    mcrypt_generic_deinit($td);
    mcrypt_module_close($td);

    /* Muestra la cadena */
    echo trim($decrypted)."\n";
    ?>

### Ver también

- mcrypt_module_close() - Libera el módulo de cifrado
- mcrypt_generic() - Cifra los datos
- mdecrypt_generic() - Desencripta los datos
- mcrypt_generic_init() - Inicializa todos los buffers necesarios
- mcrypt_generic_deinit() - Prepara el módulo para la descarga

# mcrypt_module_self_test

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_self_test — Prueba un modo

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mcrypt_module_self_test(string `$algorithm`, string `$lib_dir` = ?): bool

Realiza una prueba sobre el algoritmo especificado.

### Parámetros

`algorithm`
  Una de las constantes `MCRYPT_ciphername`, o el nombre del algoritmo como cadena.
`lib_dir`
  El argumento opcional `lib_dir` contiene la ruta de acceso hasta el módulo del algoritmo en el sistema.

### Valores devueltos

Devuelve `true` si la prueba funciona, y `false` en caso contrario.

### Ejemplos

Ejemplo #1 Ejemplo con mcrypt_module_self_test()

    <?php
    var_dump(mcrypt_module_self_test(MCRYPT_RIJNDAEL_128)) . "\n";
    var_dump(mcrypt_module_self_test(MCRYPT_BOGUS_CYPHER));
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(false)

# mdecrypt_generic

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mdecrypt_generic — Desencripta los datos

Advertencia

Esta función está OBSOLETA a partir de PHP 7.1.0 y ha sido ELIMINADA a partir de PHP 7.2.0. Depender de esta función está altamente desaconsejado.

### Descripción

function mdecrypt_generic(resource `$td`, string `$data`): string

Desencripta los datos `data`. Tenga en cuenta que la longitud del string desencriptado puede ser más larga que el string original, ya que puede haber sido completado con caracteres.

### Parámetros

`td`
  Un descriptor de cifrado, devuelto por la función mcrypt_module_open()
`data`
  Los datos cifrados.

### Valores devueltos

Devuelve el string desencriptado.

### Ejemplos

Ejemplo #1 Ejemplo con mdecrypt_generic()

    <?php
    /* Datos */
    $key = 'Esta es una clave de cifrado muy larga, incluso demasiado larga';
    $plain_text = 'Estos son datos importantes';

    /* Abre el módulo y crea un VI */
    $td = mcrypt_module_open('des', '', 'ecb', '');
    $key = substr($key, 0, mcrypt_enc_get_key_size($td));
    $iv_size = mcrypt_enc_get_iv_size($td);
    $iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);

    /* Inicializa el módulo de cifrado */
    if (mcrypt_generic_init($td, $key, $iv) != -1) {

        /* Cifra los datos */
        $c_t = mcrypt_generic($td, $plain_text);
        mcrypt_generic_deinit($td);

        /* Reinicia los buffers para el descifrado */
        mcrypt_generic_init($td, $key, $iv);
        $p_t = mdecrypt_generic($td, $c_t);

        /* Limpia */
        mcrypt_generic_deinit($td);
        mcrypt_module_close($td);
    }

    if (strncmp($p_t, $plain_text, strlen($plain_text)) == 0) {
        echo "ok\n";
    } else {
        echo "error\n";
    }
    ?>

El ejemplo anterior muestra cómo verificar que los datos antes del cifrado son los mismos que después del cifrado/descifrado. Es muy importante reiniciar el buffer de cifrado con mcrypt_generic_init() antes de descifrar los datos.

El gestor de descifrado debe ser siempre inicializado por la función mcrypt_generic_init() con una clave y un VI antes de llamar a esta función. Cuando el cifrado está hecho, es necesario liberar los datos cifrados llamando a mcrypt_generic_deinit(). Consulte mcrypt_module_open() para un ejemplo.

### Ver también

- mcrypt_generic() - Cifra los datos
- mcrypt_generic_init() - Inicializa todos los buffers necesarios
- mcrypt_generic_deinit() - Prepara el módulo para la descarga

## Tabla de contenidos

- mcrypt_create_iv — Crea un vector de inicialización (IV) a partir de una fuente aleatoria
- mcrypt_decrypt — Descifra un texto con los parámetros dados
- mcrypt_enc_get_algorithms_name — Devuelve el nombre del algoritmo de cifrado
- mcrypt_enc_get_block_size — Devuelve el tamaño de bloque de un algoritmo
- mcrypt_enc_get_iv_size — Devuelve el tamaño del VI de un algoritmo
- mcrypt_enc_get_key_size — Devuelve el tamaño máximo de la clave para un modo
- mcrypt_enc_get_modes_name — Devuelve el nombre del modo
- mcrypt_enc_get_supported_key_sizes — Devuelve un array que contiene los tamaños de clave admitidos por un algoritmo
- mcrypt_enc_is_block_algorithm — Comprueba si el cifrado es por bloques en un algoritmo
- mcrypt_enc_is_block_algorithm_mode — Comprueba si el modo de cifrado es por bloques
- mcrypt_enc_is_block_mode — Comprueba si el modo devuelve los datos por bloques
- mcrypt_enc_self_test — Prueba un módulo abierto
- mcrypt_encrypt — Cifra un texto
- mcrypt_generic — Cifra los datos
- mcrypt_generic_deinit — Prepara el módulo para la descarga
- mcrypt_generic_init — Inicializa todos los buffers necesarios
- mcrypt_get_block_size — Devuelve el tamaño de bloques de un cifrado
- mcrypt_get_cipher_name — Lee el nombre del cifrado utilizado
- mcrypt_get_iv_size — Retorna el tamaño del VI utilizado por un par cifrado/modo
- mcrypt_get_key_size — Devuelve el tamaño de la clave de cifrado
- mcrypt_list_algorithms — Lista todos los algoritmos de cifrado soportados
- mcrypt_list_modes — Lista todos los modos de cifrado soportados
- mcrypt_module_close — Libera el módulo de cifrado
- mcrypt_module_get_algo_block_size — Devuelve el tamaño de bloques de un algoritmo
- mcrypt_module_get_algo_key_size — Devuelve el tamaño máximo de clave
- mcrypt_module_get_supported_key_sizes — Devuelve un array que contiene los tamaños de claves soportados por el algoritmo abierto
- mcrypt_module_is_block_algorithm — Indica si un algoritmo funciona por bloques
- mcrypt_module_is_block_algorithm_mode — Indica si un modo funciona por bloques
- mcrypt_module_is_block_mode — Indica si un modo trabaja por bloques
- mcrypt_module_open — Abre el módulo del algoritmo y del modo a utilizar
- mcrypt_module_self_test — Prueba un modo
- mdecrypt_generic — Desencripta los datos

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
  - Tipos de recursos
- Constantes predefinidas
- Modos de cifrado Mcrypt
- Funciones Mcrypt
  - mcrypt_create_iv — Crea un vector de inicialización (IV) a partir de una fuente aleatoria
  - mcrypt_decrypt — Descifra un texto con los parámetros dados
  - mcrypt_enc_get_algorithms_name — Devuelve el nombre del algoritmo de cifrado
  - mcrypt_enc_get_block_size — Devuelve el tamaño de bloque de un algoritmo
  - mcrypt_enc_get_iv_size — Devuelve el tamaño del VI de un algoritmo
  - mcrypt_enc_get_key_size — Devuelve el tamaño máximo de la clave para un modo
  - mcrypt_enc_get_modes_name — Devuelve el nombre del modo
  - mcrypt_enc_get_supported_key_sizes — Devuelve un array que contiene los tamaños de clave admitidos por un algoritmo
  - mcrypt_enc_is_block_algorithm — Comprueba si el cifrado es por bloques en un algoritmo
  - mcrypt_enc_is_block_algorithm_mode — Comprueba si el modo de cifrado es por bloques
  - mcrypt_enc_is_block_mode — Comprueba si el modo devuelve los datos por bloques
  - mcrypt_enc_self_test — Prueba un módulo abierto
  - mcrypt_encrypt — Cifra un texto
  - mcrypt_generic — Cifra los datos
  - mcrypt_generic_deinit — Prepara el módulo para la descarga
  - mcrypt_generic_init — Inicializa todos los buffers necesarios
  - mcrypt_get_block_size — Devuelve el tamaño de bloques de un cifrado
  - mcrypt_get_cipher_name — Lee el nombre del cifrado utilizado
  - mcrypt_get_iv_size — Retorna el tamaño del VI utilizado por un par cifrado/modo
  - mcrypt_get_key_size — Devuelve el tamaño de la clave de cifrado
  - mcrypt_list_algorithms — Lista todos los algoritmos de cifrado soportados
  - mcrypt_list_modes — Lista todos los modos de cifrado soportados
  - mcrypt_module_close — Libera el módulo de cifrado
  - mcrypt_module_get_algo_block_size — Devuelve el tamaño de bloques de un algoritmo
  - mcrypt_module_get_algo_key_size — Devuelve el tamaño máximo de clave
  - mcrypt_module_get_supported_key_sizes — Devuelve un array que contiene los tamaños de claves soportados por el algoritmo abierto
  - mcrypt_module_is_block_algorithm — Indica si un algoritmo funciona por bloques
  - mcrypt_module_is_block_algorithm_mode — Indica si un modo funciona por bloques
  - mcrypt_module_is_block_mode — Indica si un modo trabaja por bloques
  - mcrypt_module_open — Abre el módulo del algoritmo y del modo a utilizar
  - mcrypt_module_self_test — Prueba un modo
  - mdecrypt_generic — Desencripta los datos

# Mhash

# Introducción

Estas funciones han sido previstas para funcionar con » mhash. Mhash puede ser utilizada para crear una suma de verificación, un hash y mucho más.

Este conjunto de funciones representa una interfaz con la biblioteca mhash. Mhash acepta un gran número de algoritmos diferentes, tales como MD5, SHA1, GOST y muchos otros. Para una lista completa de los hashes soportados, refiérase a la página sobre las constantes. La regla general es que se puede acceder a un algoritmo desde PHP con la constante `MHASH_hashname`. Por ejemplo, para acceder al algoritmo TIGER, se puede utilizar la constante PHP `MHASH_TIGER`.

> Nota:

> Esta extensión está obsoleta. Utilice la extensión Hash en su lugar.

> Nota:

> A partir de PHP 7.0.0 la extensión Mhash ha sido completamente integrada en la extensión Hash. Por consiguiente, ya no es posible detectar el soporte de Mhash gracias a extension_loaded(); utilice function_exists() en su lugar. Además, Mhash ya no es señalado por get_loaded_extensions() y las funcionalidades relacionadas.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación

## Requerimientos

Para utilizarlo, descargue las distribuciones de mhash desde este » sitio web y siga las instrucciones de instalación incluidas.

## Instalación

Será necesario compilar PHP con la opción --with-mhash[=DIR] para activar esta extensión. DIR es la ruta del directorio de instalación de la biblioteca MHASH.

Desde PHP 5.3.0, la extensión mhash es emulada a través de la extensión Hash. Asimismo, la opción que permite especificar el directorio de instalación de mhash ya no tiene efecto, y esta extensión requiere la instalación de la extensión hash para funcionar.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

A continuación se presenta una lista de los modos que son soportados por mhash. Si un modo no está listado aquí, pero está listado en la documentación mhash como soportado, se puede considerar que esta lista no está actualizada.

`MHASH_ADLER32` (int)
`MHASH_CRC32` (int)
`MHASH_CRC32B` (int)
`MHASH_CRC32C` (int)
  Disponible a partir de PHP 7.4.0.
`MHASH_FNV132` (int)
`MHASH_FNV1A32` (int)
`MHASH_FNV164` (int)
`MHASH_FNV1A64` (int)
`MHASH_GOST` (int)
`MHASH_HAVAL128` (int)
`MHASH_HAVAL160` (int)
`MHASH_HAVAL192` (int)
`MHASH_HAVAL224` (int)
`MHASH_HAVAL256` (int)
`MHASH_JOAAT` (int)
`MHASH_MD2` (int)
`MHASH_MD4` (int)
`MHASH_MD5` (int)
`MHASH_MURMUR3A` (int)
  Disponible desde PHP 8.1.0.
`MHASH_MURMUR3C` (int)
  Disponible desde PHP 8.1.0.
`MHASH_MURMUR3F` (int)
  Disponible desde PHP 8.1.0.
`MHASH_RIPEMD128` (int)
`MHASH_RIPEMD160` (int)
`MHASH_RIPEMD256` (int)
`MHASH_RIPEMD320` (int)
`MHASH_SHA1` (int)
`MHASH_SHA224` (int)
`MHASH_SHA256` (int)
`MHASH_SHA384` (int)
`MHASH_SHA512` (int)
`MHASH_SNEFRU128` (int)
`MHASH_SNEFRU256` (int)
`MHASH_TIGER` (int)
`MHASH_TIGER128` (int)
`MHASH_TIGER160` (int)
`MHASH_WHIRLPOOL` (int)

# Ejemplos

Ejemplo #1 Calcule el MD5 y el hmac, luego lo muestra como un hexadecimal

    <?php
    $input = "what do ya want for nothing?";
    $hash = mhash(MHASH_MD5, $input);
    echo "El hash vale " . bin2hex($hash) . "<br />\n";
    $hash = mhash(MHASH_MD5, $input, "Jefe");
    echo "El hmac vale " . bin2hex($hash) . "<br />\n";
    ?>

El ejemplo anterior mostrará:

    El hash vale d03cb659cbf9192dcd066272249f8412
    El hmac vale 750c783e6ab0b503eaa86e310a5db738

# Funciones Mhash

# mhash

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash — Calcula un hash

Advertencia

Esta función está OBSOLETA a partir de PHP 8.1.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function mhash(int `$algo`, string `$data`, ?string `$key` = null): string|false

mhash() aplica la función de hash `algo` a los datos `data`.

### Parámetros

`algo`

  El identificador del hash. Uno de los constantes `MHASH_hashname`.

`data`

  La entrada del usuario, en forma de string.

`key`

  Especificado, la función devolverá el HMAC resultante. HMAC es un hash indexado utilizado para la identificación de mensaje, o bien un simple informe de mensaje, según la clave especificada. Algunos algoritmos soportados en mhash no son compatibles con el modo HMAC.

### Valores devueltos

Devuelve el hash resultante (también llamado "digest") o HMAC, en forma de string o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Esta función ha sido deprecada. Utilizar las funciones `hash_*()` en su lugar.
8.0.0 | `key` es ahora nullable.

# mhash_count

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash_count — Recupera el identificador máximo de hash

Advertencia

Esta función está OBSOLETA a partir de PHP 8.1.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function mhash_count(): int

Recupera el identificador máximo de hash.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el identificador de hash máximo. Los hashes están numerados de 0 hasta este identificador.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Esta función ha sido deprecada. Utilizar las funciones `hash_*()` en su lugar.

### Ejemplos

Ejemplo #1 Recorrer la lista de hashes

    <?php

    $nr = mhash_count();

    for ($i = 0; $i <= $nr; $i++) {
        echo sprintf("El tamaño de bloque de %s es %d\n",
            mhash_get_hash_name($i),
            mhash_get_block_size($i));
    }
    ?>

# mhash_get_block_size

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash_get_block_size — Devuelve el tamaño del bloque del hash

Advertencia

Esta función está OBSOLETA a partir de PHP 8.1.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function mhash_get_block_size(int `$algo`): int|false

Devuelve el tamaño del bloque del `algo` especificado.

### Parámetros

`algo`

  El identificador del hash. Una de las constantes `MHASH_hashname`.

### Valores devueltos

Devuelve el tamaño, en bytes, o `false` si el `algo` no existe.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Esta función ha sido deprecada. Utilizar las funciones `hash_*()` en su lugar.

### Ejemplos

Ejemplo #1 Ejemplo con mhash_get_block_size()

    <?php

    echo mhash_get_block_size(MHASH_MD5); // 16

    ?>

# mhash_get_hash_name

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash_get_hash_name — Devuelve el nombre del hash

Advertencia

Esta función está OBSOLETA a partir de PHP 8.1.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function mhash_get_hash_name(int `$algo`): string|false

Devuelve el nombre del `algo` especificado.

### Parámetros

`algo`

  El identificador del hash. Una de las constantes `MHASH_hashname`.

### Valores devueltos

Devuelve el nombre del hash o `false` si el hash no existe.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Esta función ha sido deprecada. Utilizar las funciones `hash_*()` en su lugar.

### Ejemplos

Ejemplo #1 Ejemplo con mhash_get_hash_name()

    <?php

    echo mhash_get_hash_name(MHASH_MD5); // MD5

    ?>

# mhash_keygen_s2k

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

mhash_keygen_s2k — Genera una clave

Advertencia

Esta función está OBSOLETA a partir de PHP 8.1.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function mhash_keygen_s2k(
int `$algo`,
string `$password`,
string `$salt`,
int `$length`
): string|false

Genera una clave según el `algo` proporcionado, utilizando la contraseña `password` proporcionada.

Esta función utiliza el algoritmo `Salted S2K`, especificado en OpenPGP (» RFC 2440).

Es importante tener en cuenta que las contraseñas proporcionadas por los usuarios no son recomendadas para generar claves criptográficas, dado que los usuarios normales recuerdan contraseñas que pueden teclear. Estas contraseñas utilizan solo 6 a 7 de los 8 bits de un carácter (o incluso menos). Se recomienda encarecidamente aplicar una función de transformación (como esta) a una contraseña de usuario.

### Parámetros

`algo`

  El identificador del hash utilizado para crear la clave. Una de las constantes `MHASH_hashname`.

`password`

  Contraseña proporcionada por el usuario.

`salt`

  Debe ser diferente y suficientemente aleatorio para cada clave que se genera, a fin de crear claves diferentes. Dado que el parámetro `salt` debe ser conocido cuando se verifican las claves, es una buena idea añadirlo a la clave. El parámetro salt debe tener una longitud de 8 bytes, y se rellenará con ceros si se proporciona uno de menor tamaño.

`length`

  La longitud de la clave, en bytes.

### Valores devueltos

Devuelve la clave generada, en forma de string, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Esta función ha sido deprecada. Utilizar las funciones `hash_*()` en su lugar.

## Tabla de contenidos

- mhash — Calcula un hash
- mhash_count — Recupera el identificador máximo de hash
- mhash_get_block_size — Devuelve el tamaño del bloque del hash
- mhash_get_hash_name — Devuelve el nombre del hash
- mhash_keygen_s2k — Genera una clave

- Instalación/Configuración
  - Requerimientos
  - Instalación
- Constantes predefinidas
- Ejemplos
- Funciones Mhash
  - mhash — Calcula un hash
  - mhash_count — Recupera el identificador máximo de hash
  - mhash_get_block_size — Devuelve el tamaño del bloque del hash
  - mhash_get_hash_name — Devuelve el nombre del hash
  - mhash_keygen_s2k — Genera una clave

# OpenSSL

# Introducción

Esta extensión vincula funciones de la biblioteca » OpenSSL para el cifrado y descifrado simétrico y asimétrico, PBKDF2, PKCS7, PKCS12, X509 y otras operaciones criptográficas. Además, proporciona una implementación de flujo TLS.

OpenSSL ofrece muchas funcionalidades que este módulo no ofrece actualmente. Algunas podrían ser añadidas en el futuro.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución
- Tipos de recursos

## Requerimientos

Para poder utilizar las funciones OpenSSL, debe instalarse la biblioteca » OpenSSL. PHP 7.0 requiere OpenSSL >= 0.9.8, < 1.2. PHP 7.1-8.0 requieren OpenSSL >= 1.0.1, < 3.0. PHP >= 8.1 requiere OpenSSL >= 1.0.2, < 4.0. PHP >= 8.4 requiere OpenSSL >= 1.1.1, < 4.0.

Advertencia

Se recomienda encarecidamente utilizar la versión mantenida de OpenSSL para evitar ciertas vulnerabilidades en el servidor web.

## Instalación

Para utilizar el soporte OpenSSL de PHP, también debe compilarse PHP con la opción de configuración --with-openssl.

La biblioteca OpenSSL también posee dependencias en tiempo de ejecución. Por ejemplo, OpenSSL necesita acceder a un generador de números pseudo-aleatorios; en la mayoría de las plataformas Unix (incluyendo Linux), debe tener acceso al dispositivo `/dev/urandom` o `/dev/random`.

La opción de configuración --with-system-ciphers está disponible que hace que PHP utilice la lista de cifrado del sistema en lugar de los valores por omisión codificados en el programa.

> Nota: Nota para usuarios Win32

> Para hacer funcionar esta extensión, algunas bibliotecas DLL deben estar disponibles a través del PATH del sistema Windows. Lea la F.A.Q titulada "Cómo agregar mi carpeta PHP a mi PATH de Windows" para más información. Copiar las bibliotecas DLL desde la carpeta PHP a la carpeta del sistema de Windows también funciona (ya que la carpeta del sistema está por defecto en el PATH del sistema), pero este método no es recomendado. Esta extensión requiere que los siguientes archivos estén en el PATH: libeay32.dll, o, a partir de OpenSSL 1.1, libcrypto-*.dll

> Además, si se ha previsto utilizar las funciones relativas a la generación de claves y a los certificados, debe instalarse un fichero openssl.cnf válido en el sistema. Un fichero de configuración básico está incluido en las distribuciones de PHP para win32 en el directorio extras/ssl.

> PHP buscará el fichero openssl.cnf siguiendo la siguiente táctica:

> - La variable de entorno OPENSSL_CONF, si está definida, será utilizada como ruta (incluyendo el fichero) hacia el fichero de configuración.
> - La variable de entorno SSLEAY_CONF, si está definida, será utilizada como ruta (incluyendo el fichero) hacia el fichero de configuración.
> - El fichero openssl.cnf se supondrá que se encuentra en el directorio de certificados, tal como se configuró durante la compilación de la biblioteca openssl. Esto significa generalmente C:\Program Files\Common Files\SSL\openssl.cnf (x64) o C:\Program Files (x86)\Common Files\SSL\openssl.cnf (x86), o, antes de PHP 7.4.0, c:\usr\local\ssl\openssl.cnf.
> En su instalación, deberá decidirse si se va a instalar el fichero de configuración en la ruta por omisión o si se va a hacer en otro lugar y configurar una variable de entorno (posiblemente por sitio virtual). Tenga en cuenta que es posible reemplazar la ruta por omisión utilizando el parámetro `options` de las funciones que requieren un fichero de configuración.
> Precaución

> Asegúrese de que los usuarios no privilegiados no estén autorizados a modificar openssl.cnf.

> A partir de OpenSSL 3.0.0, que se utiliza por omisión en Windows desde PHP 8.2.0, varios algoritmos han sido considerados obsoletos. Estos algoritmos suelen haber caído en desuso, han sido considerados no seguros por la comunidad criptográfica, o algo similar. Estos algoritmos siguen disponibles a través del proveedor de algoritmos legacy (extras/ssl/legacy.dll) ; su utilización se describe en la sección » configuración del proveedor del manual OpenSSL.

### Historial de cambios

Versión | Descripción
--- | ---
7.4.0 | La opción --with-openssl[=DIR] ya no acepta argumentos de directorio en favor del ajuste de la variable pkg-config PKG_CONFIG_PATH hacia la ubicación de OpenSSL, o especificando las variables OPENSSL_LIBS y OPENSSL_CFLAGS.
La ruta de configuración por omisión de OpenSSL ha sido modificada de C:\usr\local\ssl a C:\Program Files\Common Files\SSL y C:\Program Files (x86)\Common Files\SSL, respectivamente.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

openssl Opciones de configuración
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
openssl.cafile | "" | `INI_PERDIR` |
openssl.capath | "" | `INI_PERDIR` |
openssl.libctx | "custom" | `INI_PERDIR` |

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`openssl.cafile` string

  Ubicación del archivo de Autoridad de Certificación en el sistema de archivos local que debería ser utilizado con la opción de contexto verify_peer para autenticar la identidad del par remoto.

`openssl.capath` string

  Si cafile no está especificado o si el certificado no es encontrado allí, el directorio apuntado por capath es examinado para encontrar un certificado adecuado. capath debe ser un directorio de certificados correctamente hasheado.

`openssl.libctx` string
  Especifica el tipo de contexto de biblioteca OpenSSL que se utilizará. El valor predeterminado, `custom`, crea un contexto de biblioteca independiente para cada worker o subproceso. Esto mejora el aislamiento de otras bibliotecas que utilizan OpenSSL y, en compilaciones ZTS, aumenta la separación entre subprocesos. También es posible usar el valor `default`, que hace que PHP utilice el contexto de biblioteca predeterminado global de OpenSSL.

Ver también las opciones del contexto de flujo SSL.

## Tipos de recursos

Antes de PHP 8.0.0, existían 3 tipos de recursos definidos en el módulo OpenSSL:

- `OpenSSL key`
- `OpenSSL X.509`
- `OpenSSL X.509 CSR`

# Constantes predefinidas

## Tabla de contenidos

- Opciones de validación general
- Opciones de relleno (Padding) para el cifrado asimétrico
- Tipos de clave
- Constantes/opciones PKCS7
- Bandera/Constantes CMS
- Algoritmo de firma
- Cifrados
- Constantes de versión
- Constantes de identificación del nombre del servidor
- Otras constantes

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

## Opciones de validación general

`X509_PURPOSE_SSL_CLIENT` (int)
`X509_PURPOSE_SSL_SERVER` (int)
`X509_PURPOSE_NS_SSL_SERVER` (int)
`X509_PURPOSE_SMIME_SIGN` (int)
`X509_PURPOSE_SMIME_ENCRYPT` (int)
`X509_PURPOSE_CRL_SIGN` (int)
`X509_PURPOSE_ANY` (int)
`X509_PURPOSE_OCSP_HELPER` (int)
  Verifica el certificado para su uso como ayudante de respondedor OCSP. Disponible a partir de PHP 8.4.0.
`X509_PURPOSE_TIMESTAMP_SIGN` (int)
  Verifica el certificado para su uso como firmante de marcas de tiempo de confianza. Disponible a partir de PHP 8.4.0.

## Opciones de relleno (`Padding`) para el cifrado asimétrico

`OPENSSL_PKCS1_PADDING` (int)
`OPENSSL_SSLV23_PADDING` (int)
`OPENSSL_NO_PADDING` (int)
`OPENSSL_PKCS1_OAEP_PADDING` (int)
`OPENSSL_PKCS1_PSS_PADDING` (int)
  Relleno RSA-PSS. Disponible a partir de PHP 8.5.0.

## Tipos de clave

`OPENSSL_KEYTYPE_RSA` (int)
  Tipo de clave RSA.
`OPENSSL_KEYTYPE_DSA` (int)
  Tipo de clave DSA.
`OPENSSL_KEYTYPE_DH` (int)
  Tipo de clave DH (Diffie-Hellman).
`OPENSSL_KEYTYPE_EC` (int)
  Tipo de clave de curva elíptica.
`OPENSSL_KEYTYPE_X25519` (int)
  Tipo de clave de curva X25519. Esta constante solo está disponible cuando PHP se compila con OpenSSL 3.0+.
`OPENSSL_KEYTYPE_ED25519` (int)
  Tipo de clave de curva Ed25519. Esta constante solo está disponible cuando PHP se compila con OpenSSL 3.0+.
`OPENSSL_KEYTYPE_X448` (int)
  Tipo de clave de curva X448. Esta constante solo está disponible cuando PHP se compila con OpenSSL 3.0+.
`OPENSSL_KEYTYPE_ED448` (int)
  Tipo de clave de curva Ed448. Esta constante solo está disponible cuando PHP se compila con OpenSSL 3.0+.

## Constantes/opciones PKCS7

Las funciones S/MIME utilizan opciones que se especifican mediante un campo de bits. Los valores válidos son:

Constantes PKCS7
Constante | Descripción
--- | ---
`PKCS7_TEXT` (int) | Añade el texto en claro en los encabezados del mensaje firmado/cifrado. Al descifrar o verificar, se eliminan simplemente estos datos. Si el mensaje cifrado o firmado no es del tipo MIME, se producirá un error.
`PKCS7_BINARY` (int) | Normalmente, el mensaje se convierte al formato canónico que utiliza efectivamente `CR` y `LF` como fin de línea, como se solicita en las especificaciones de S/MIME. Cuando esta opción está activada, el mensaje no se convertirá. Esto es útil cuando se manipulan datos binarios que no están en formato MIME.
`PKCS7_NOINTERN` (int) | Al verificar un mensaje, los certificados (si los hay) incluidos en el mensaje se utilizan normalmente para buscar el certificado de firma. Con esta opción, solo se utiliza el certificado especificado por el argumento `untrusted_certificates_filename` de la función openssl_pkcs7_verify(). Los certificados proporcionados pueden seguir utilizándose, con un nivel de confianza reducido.
`PKCS7_NOVERIFY` (int) | No verifica los certificados de los firmantes de un mensaje firmado.
`PKCS7_NOCHAIN` (int) | No encadena las verificaciones de los certificados de los firmantes. Es decir, no utiliza los certificados contenidos en el mensaje.
`PKCS7_NOCERTS` (int) | Al firmar un mensaje, el certificado del firmante se incluye normalmente. Con esta opción, esto se desactiva. Esto reducirá el tamaño del mensaje, pero el verificador deberá tener una copia local del certificado del firmante (pasado al argumento `untrusted_certificates_filename`, con la función openssl_pkcs7_verify()).
`PKCS7_NOATTR` (int) | Normalmente, cuando se firma un mensaje, se incluye un conjunto de atributos que contiene la hora de firma y el algoritmo simétrico soportado, en el mensaje. Con esta opción, no se incluye.
`PKCS7_DETACHED` (int) | Al firmar un mensaje, se utiliza la firma en texto claro, con el tipo MIME `"multipart/signed"`. Este es el valor por defecto del argumento `flags` para la función openssl_pkcs7_sign(). Si se anula esta opción, el mensaje se firmará de manera opaca, lo que resiste mejor a la traducción de los relés de correo (algunos antiguos servidores de correo corrompen los mensajes), pero impide la lectura por los clientes de correo que no conocen S/MIME.
`PKCS7_NOSIGS` (int) | No verifica las firmas de un mensaje
`PKCS7_NOOLDMIMETYPE` (int) | Disponible a partir de PHP 8.3.0. Establece el encabezado HTTP Content-Type en `application/pkcs7-mime` en lugar de `application/x-pkcs7-mime` para cifrar un mensaje.
`PKCS7_NOSMIMECAP` (int) | Disponible a partir de PHP 8.5.0. No incluye las capacidades S/MIME (SMIMECapabilities) en la firma.
`PKCS7_CRLFEOL` (int) | Disponible a partir de PHP 8.5.0. Utiliza `CRLF` como fin de línea en la salida.
`PKCS7_NOCRL` (int) | Disponible a partir de PHP 8.5.0. No incluye las CRL en la estructura PKCS7.
`PKCS7_NO_DUAL_CONTENT` (int) | Disponible a partir de PHP 8.5.0. No incluye el contenido duplicado, evitando la duplicación del contenido firmado.

## Bandera/Constantes CMS

Las funciones CMS utilizan banderas que se especifican utilizando una máscara de bits que incluye una o más de las siguientes opciones:

Constantes CMS
Constantes | Descripción
--- | ---
`OPENSSL_CMS_TEXT` (int) | Añade el encabezado content type `text/plain` al mensaje cifrado/firmado. Al descifrar/verificar, estos encabezados se eliminan de la salida, si el mensaje descifrado o verificado no es del tipo MIME `text/plain` entonces se producirá un error.
`OPENSSL_CMS_BINARY` (int) | Normalmente el mensaje de entrada se convierte a su forma "canónica" que en realidad utiliza `CR` y `LF` como fin de línea: tal como se requiere por la especificación CMS. Cuando esta opción está presente, ninguna traducción se realiza. Esto es útil al manejar datos binarios que pueden no estar en formato CMS.
`OPENSSL_CMS_NOINTERN` (int) | Al verificar un mensaje, los certificados (si los hay) incluidos en el mensaje se utilizan normalmente para buscar el certificado de firma. Con esta opción, solo se utilizan los certificados especificados en el argumento `untrusted_certificates_filename` de openssl_cms_verify(). Los certificados proporcionados pueden seguir utilizándose como autoridades de certificación no fiables.
`OPENSSL_CMS_NOVERIFY` (int) | No verifica el certificado del firmante de un mensaje firmado.
`OPENSSL_CMS_NOCERTS` (int) | Al firmar un mensaje el certificado del firmante se incluye normalmente, con esta opción se excluye. Esto reducirá el tamaño del mensaje firmado pero el verificador debe tener una copia del certificado del firmante disponible localmente (pasado utilizando `untrusted_certificates_filename` de openssl_cms_verify() por ejemplo).
`OPENSSL_CMS_NOATTR` (int) | Normalmente cuando un mensaje es firmado, se incluyen un conjunto de atributos que incluyen la hora de firma y los algoritmos simétricos soportados. Con esta opción no se incluyen.
`OPENSSL_CMS_DETACHED` (int) | Al firmar un mensaje, se utiliza la firma en texto claro con el tipo MIME `"multipart/signed"`. Este es el comportamiento por defecto, si no se especifica ningún `flags` a openssl_cms_sign(). Si se desactiva esta opción, el mensaje se firmará utilizando una firma opaca, que es más resistente a la traducción por los relés de correo pero no puede ser leída por los agentes de correo que no soportan S/MIME.
`OPENSSL_CMS_NOSIGS` (int) | No intenta verificar las firmas de un mensaje
`OPENSSL_CMS_OLDMIMETYPE` (int) | Disponible a partir de PHP 8.3.0. Establece el encabezado HTTP Content-Type en `application/x-pkcs7-mime` en lugar de `application/pkcs7-mime` para cifrar un mensaje.

## Algoritmo de firma

`OPENSSL_ALGO_DSS1` (int)
`OPENSSL_ALGO_SHA1` (int)
  Utilizado como algoritmo por defecto para las funciones openssl_sign() y openssl_verify().
`OPENSSL_ALGO_SHA224` (int)
`OPENSSL_ALGO_SHA256` (int)
`OPENSSL_ALGO_SHA384` (int)
`OPENSSL_ALGO_SHA512` (int)
`OPENSSL_ALGO_RMD160` (int)
`OPENSSL_ALGO_MD5` (int)
`OPENSSL_ALGO_MD4` (int)
`OPENSSL_ALGO_MD2` (int)
  Esta constante solo está disponible cuando PHP se compila con soporte MD2. Es necesario pasar el CFLAG `-DHAVE_OPENSSL_MD2_H` al compilar PHP y pasar `enable-md2` al compilar OpenSSL 1.0.0+.

## Cifrados

`OPENSSL_DEFAULT_STREAM_CIPHERS` (string)
  Lista de cifrados por defecto.
`OPENSSL_CIPHER_RC2_40` (int)
`OPENSSL_CIPHER_RC2_128` (int)
`OPENSSL_CIPHER_RC2_64` (int)
`OPENSSL_CIPHER_DES` (int)
`OPENSSL_CIPHER_3DES` (int)

`OPENSSL_CIPHER_AES_128_CBC` (int)
`OPENSSL_CIPHER_AES_192_CBC` (int)
`OPENSSL_CIPHER_AES_256_CBC` (int)

## Constantes de versión

`OPENSSL_VERSION_TEXT` (string)
`OPENSSL_VERSION_NUMBER` (int)

## Constantes de identificación del nombre del servidor

`OPENSSL_TLSEXT_SERVER_NAME` (int)
  Si el soporte SNI está disponible o no.

> Nota:

> Esta constante solo está disponible cuando PHP se compila con OpenSSL 0.9.8j o posterior

## Otras constantes

`OPENSSL_RAW_DATA` (int)
  Si `OPENSSL_RAW_DATA` está definida en openssl_encrypt() o openssl_decrypt(), los datos devueltos se devuelven tal cual. Cuando esto no está especificado, los datos devueltos al llamador están codificados en Base64.
`OPENSSL_DONT_ZERO_PAD_KEY` (int)
  Impide que openssl_encrypt() rellene las claves que son más cortas que la longitud de clave por defecto.
`OPENSSL_ZERO_PADDING` (int)
  Por defecto, las operaciones de cifrado se completan utilizando bloques estándar y el relleno se verifica y elimina al descifrar. Si la constante `OPENSSL_ZERO_PADDING` está definida en el argumento `options` de la función openssl_encrypt() o openssl_decrypt() entonces no se realizará ningún relleno, la cantidad total de datos cifrados deberá ser entonces un múltiplo del tamaño del bloque o bien se producirá un error.
`OPENSSL_ENCODING_SMIME` (int)
  Indica que la codificación es S/MIME.
`OPENSSL_ENCODING_DER` (int)
  Indica que la codificación es DER (Distinguished Encoding Rules).
`OPENSSL_ENCODING_PEM` (int)
  Indica que la codificación es PEM (Privacy-Enhanced Mail).

# Parámetros de claves/certificados

Un gran número de funciones OpenSSL requieren una clave o un certificado como parámetros. Los métodos siguientes pueden ser utilizados para obtenerlos:

- Certificados

  1. Una instancia de OpenSSLCertificate (o anterior a PHP 8.0.0, un resource de tipo `OpenSSL X.509`) devuelta por openssl_x509_read()
  2. Una cadena con el formato file://path/to/cert.pem; El fichero identificado debe contener un certificado, codificado en formato PEM.
  3. Una cadena que contiene el contenido de un certificado, codificado en formato PEM, puede comenzar por `-----BEGIN CERTIFICATE-----`.

- Solicitudes de firma de certificados (Certificate Signing Requests, abreviado CSRs)

  1. Una instancia de OpenSSLCertificateSigningRequest (o anterior a PHP 8.0.0, un resource de tipo `OpenSSL X.509 CSR`) devuelta por openssl_csr_new()
  2. Una string con el formato file://path/to/csr.pem; el fichero nombrado debe contener un CSR codificado en formato PEM.
  3. Una string que contiene el contenido de un CSR, codificado en formato PEM, puede comenzar por `-----BEGIN CERTIFICATE REQUEST-----`.

- Claves públicas/privadas

  1. Una instancia de OpenSSLAsymmetricKey (o anterior a PHP 8.0.0, un resource de tipo `OpenSSL key`) devuelta por openssl_csr_new()
  2. Para las claves públicas únicamente: una instancia de OpenSSLCertificate (o anterior a PHP 8.0.0, un resource de tipo `OpenSSL X.509`)
  3. Una cadena con el formato: file://path/to/file.pem. El fichero debe contener una clave privada, o un certificado, codificado en formato PEM (puede contener ambos).
  4. Una string que contiene el contenido de un certificado/clave, codificado en formato PEM, puede comenzar por `-----BEGIN PUBLIC KEY-----`.
  5. Para las claves privadas, también puede utilizarse la sintaxis `array($key, $passphrase)`, donde $key representa una clave especificada por un fichero o una representación textual como se ha citado anteriormente, y $passphrase representa una cadena que contiene la frase de contraseña de esta clave privada.

# Verificación de certificados

Cuando se llama a una función que va a verificar una firma o un certificado, el argumento `ca_info` debe ser un array que contenga los nombres de un directorio y un fichero que indiquen los emisores de confianza. Si se especifica un directorio, debe ser correcto, ya que openssl lo utilizará.

# Funciones de OpenSSL

# openssl_cipher_iv_length

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

openssl_cipher_iv_length — Obtiene la longitud del vector de inicialización cipher

### Descripción

function openssl_cipher_iv_length(string `$cipher_algo`): int|false

Obtiene la longitud del vector de inicialización cipher.

### Parámetros

`cipher_algo`

  El método cipher. Consulte la función openssl_get_cipher_methods() para obtener una lista de valores potenciales.

### Valores devueltos

Devuelve la longitud cipher en caso de éxito, o `false` si ocurre un error.

### Errores/Excepciones

Genera un error de nivel `E_WARNING` cuando el algoritmo cipher es desconocido.

### Ejemplos

Ejemplo #1 Ejemplo con openssl_cipher_iv_length()

    <?php
    $method = 'AES-128-CBC';
    $ivlen = openssl_cipher_iv_length($method);

    echo $ivlen;
    ?>

Resultado del ejemplo anterior es similar a:

    16

# openssl_cipher_key_length

(PHP 8 >= 8.2.0)

openssl_cipher_key_length — Devuelve la longitud de la clave de cifrado

### Descripción

function openssl_cipher_key_length(string `$cipher_algo`): int|false

Devuelve la longitud de la clave de cifrado.

### Parámetros

`cipher_algo`

  El método de cifrado, ver openssl_get_cipher_methods() para una lista de valores potenciales.

### Valores devueltos

Devuelve la longitud de la clave de cifrado en caso de éxito, o `false` si ocurre un error.

### Errores/Excepciones

Emite un error de nivel `E_WARNING` cuando el algoritmo de cifrado es desconocido.

### Ejemplos

Ejemplo #1 Ejemplo de openssl_cipher_key_length()

    <?php
    $method = 'AES-128-CBC';

    var_dump(openssl_cipher_key_length($method));
    ?>

Resultado del ejemplo anterior es similar a:

    int(16)

# openssl_cms_decrypt

(PHP 8)

openssl_cms_decrypt — Descifra un mensaje CMS

### Descripción

function openssl_cms_decrypt(
string `$input_filename`,
string `$output_filename`,
#[\SensitiveParameter]OpenSSLCertificate|string `$certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string|null `$private_key` = `null`,
int `$encoding` = `OPENSSL_ENCODING_SMIME`
): bool

Descifra un mensaje CMS.

### Parámetros

`input_filename`

  El nombre de un fichero que contiene contenido cifrado.

`output_filename`

  El nombre del fichero para depositar el contenido descifrado.

`certificate`

  El nombre del fichero que contiene un certificado del destinatario.

`private_key`

  El nombre del fichero que contiene una clave PKCS#8.

`encoding`

  La codificación del fichero de entrada. Una de las constantes `OPENSSL_ENCODING_SMIME`, `OPENSSL_ENCODING_DER` o `OPENSSL_ENCODING_PEM`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# openssl_cms_encrypt

(PHP 8)

openssl_cms_encrypt — Cifra un mensaje CMS

### Descripción

function openssl_cms_encrypt(
string `$input_filename`,
string `$output_filename`,
OpenSSLCertificate|array|string `$certificate`,
?array `$headers`,
int `$flags` = 0,
int `$encoding` = `OPENSSL_ENCODING_SMIME`,
string|int `$cipher_algo` = `OPENSSL_CIPHER_AES_128_CBC`
): bool

Esta función cifra el contenido para uno o varios destinatarios, basado en los certificados que se le pasan.

### Parámetros

`input_filename`

  El fichero a cifrar.

`output_filename`

  El fichero de salida.

`certificate`

  Los destinatarios a cifrar.

`headers`

  Las cabeceras a incluir al utilizar S/MIME.

`flags`

  Los flag a pasar a CMS_sign.

`encoding`

  Una codificación de salida. Una de las constantes `OPENSSL_ENCODING_SMIME`, `OPENSSL_ENCODING_DER` o `OPENSSL_ENCODING_PEM`.

`cipher_algo`

  El cifrado a utilizar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | `cipher_algo` es ahora de tipo int o string. Anteriormente, era de tipo int.
8.1.0 | El algoritmo de cifrado por omisión (`cipher_algo`) es ahora AES-128-CBC (`OPENSSL_CIPHER_AES_128_CBC`). Anteriormente, se utilizaba PKCS7/CMS (`OPENSSL_CIPHER_RC2_40`).

# openssl_cms_read

(PHP 8)

openssl_cms_read — Exporta el fichero CMS a un array de certificados PEM

### Descripción

function openssl_cms_read(string `$input_filename`, array `&$certificates`): bool

Realiza la operación inversa de openssl_pkcs7_read().

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`input_filename`

`certificates`

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# openssl_cms_sign

(PHP 8)

openssl_cms_sign — Firma un fichero

### Descripción

function openssl_cms_sign(
string `$input_filename`,
string `$output_filename`,
OpenSSLCertificate|string `$certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
?array `$headers`,
int `$flags` = 0,
int `$encoding` = `OPENSSL_ENCODING_SMIME`,
?string `$untrusted_certificates_filename` = `null`
): bool

Esta función firma un fichero con un certificado X.509 y una clave.

### Parámetros

`input_filename`

  El nombre del fichero a firmar.

`output_filename`

  El nombre del fichero para depositar los resultados.

`certificate`

  El certificado de firma. Véase Parámetros de clave/certificado para una lista de valores válidos.

`private_key`

  La clave asociada al `certificate`. Véase Parámetros de clave/certificado para una lista de valores válidos.

`headers`

  Un array de encabezados a incluir en la salida S/MIME.

`flags`

  Los flag a pasar a cms_sign().

`encoding`

  La codificación del fichero de salida. Una de las constantes `OPENSSL_ENCODING_SMIME`, `OPENSSL_ENCODING_DER` o `OPENSSL_ENCODING_PEM`.

`untrusted_certificates_filename`

  Los certificados intermedios a incluir en la firma.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de openssl_cms_sign()

    <?php

    openssl_cms_sign('input.txt', 'output.txt', 'file://cert.pem', 'file://privkey.pem', null, OPENSSL_CMS_BINARY, OPENSSL_ENCODING_DER, 'chain.pem');
    ?>

# openssl_cms_verify

(PHP 8)

openssl_cms_verify — Verifica una firma CMS

### Descripción

function openssl_cms_verify(
string `$input_filename`,
int `$flags` = 0,
?string `$certificates` = `null`,
array `$ca_info` = [],
?string `$untrusted_certificates_filename` = `null`,
?string `$content` = `null`,
?string `$pk7` = `null`,
?string `$sigfile` = `null`,
int `$encoding` = `OPENSSL_ENCODING_SMIME`
): bool

Esta función verifica una firma CMS, ya sea adjunta o desprendida, con la codificación especificada.

### Parámetros

`input_filename`

  El fichero de entrada.

`flags`

  Los flag a pasar a cms_verify().

`certificates`

  Un fichero con el certificado del firmante y eventualmente certificados intermedios.

`ca_info`

  Un array que contiene certificados de autoridad auto-firmados.

`untrusted_certificates_filename`

  Un fichero que contiene certificados intermedios adicionales.

`content`

  Un fichero que apunta al contenido cuando las firmas están desprendidas.

`pk7`

`sigfile`

  Un fichero para guardar la firma.

`encoding`

  La codificación del fichero de entrada. Una de las constantes `OPENSSL_ENCODING_SMIME`, `OPENSSL_ENCODING_DER` o `OPENSSL_ENCODING_PEM`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# openssl_csr_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_export — Exporta un CSR a un fichero o una variable

### Descripción

function openssl_csr_export(OpenSSLCertificateSigningRequest|string `$csr`, string `&$output`, bool `$no_text` = `true`): bool

openssl_csr_export() toma la solicitud de firma de certificado representada por `CSR` y la almacena en formato PEM en `output`, que es pasado por referencia.

### Parámetros

`csr`
  Ver los parámetros CSR para obtener una lista de los valores válidos.
`output`

  En caso de éxito, esta cadena contendrá el CSR codificado en PEM

`no_text`
  El parámetro opcional `notext` afecta al nivel de verbosidad del display; si vale `false`, se añadirán información legible por humanos en el display. Por omisión, el parámetro `notext` vale `true`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `csr` ahora acepta una instancia de OpenSSLCertificateSigningRequest; anteriormente, se aceptaba un resource de tipo `OpenSSL X.509 CSR`.

### Ejemplos

Ejemplo #1 Ejemplo de openssl_csr_export()

    <?php
    $subject = array(
        "commonName" => "example.com",
    );
    $private_key = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $configargs = array(
        'digest_alg' => 'sha256WithRSAEncryption'
    );
    $csr = openssl_csr_new($subject, $private_key, $configargs);
    openssl_csr_export($csr, $csr_string);
    echo $csr_string;
    ?>

### Ver también

- openssl_csr_export_to_file() - Exporta una CSR a un fichero
- openssl_csr_new() - Genera una CSR
- openssl_csr_sign() - Firma un CSR con otro certificado (o consigo mismo) y genera un certificado

# openssl_csr_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_export_to_file — Exporta una CSR a un fichero

### Descripción

function openssl_csr_export_to_file(OpenSSLCertificateSigningRequest|string `$csr`, string `$output_filename`, bool `$no_text` = `true`): bool

openssl_csr_export_to_file() toma la CSR representada por el argumento `csr` y la guarda en formato PEM en el fichero nombrado `output_filename`.

### Parámetros

`csr`
  Ver los parámetros CSR para obtener una lista de los valores válidos.
`output_filename`

  Ruta hacia el fichero de salida.

`no_text`
  El parámetro opcional `notext` afecta al nivel de verbosidad del display; si vale `false`, se añadirán información legible por humanos en el display. Por omisión, el parámetro `notext` vale `true`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `csr` ahora acepta una instancia de OpenSSLCertificateSigningRequest; anteriormente, se aceptaba un resource de tipo `OpenSSL X.509 CSR`.

### Ejemplos

Ejemplo #1 Ejemplo de openssl_csr_export_to_file()

    <?php
    $subject = array(
        "commonName" => "example.com",
    );
    $private_key = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha384') );
    openssl_pkey_export_to_file($private_key, 'example-priv.key');
    // Al mismo tiempo que el sujeto, la CSR contiene la clave pública correspondiente a la clave privada
    openssl_csr_export_to_file($csr, 'example-csr.pem');
    ?>

### Ver también

- openssl_csr_export() - Exporta un CSR a un fichero o una variable
- openssl_csr_new() - Genera una CSR
- openssl_csr_sign() - Firma un CSR con otro certificado (o consigo mismo) y genera un certificado

# openssl_csr_get_public_key

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_csr_get_public_key — Devuelve la clave pública de un CSR

### Descripción

function openssl_csr_get_public_key(OpenSSLCertificateSigningRequest|string `$csr`, bool `$short_names` = `true`): OpenSSLAsymmetricKey|false

openssl_csr_get_public_key() extrae la clave pública de la `csr` y la prepara para su utilización por otras funciones.

### Parámetros

`csr`
  Ver los parámetros CSR para obtener una lista de los valores válidos.
`short_names`
  Advertencia

  Este parámetro es ignorado

### Valores devueltos

Devuelve una OpenSSLAsymmetricKey en caso de éxito, o `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de OpenSSLAsymmetricKey ; anteriormente se devolvía un resource de tipo `OpenSSL key`.
8.0.0 | `csr` acepta ahora una instancia de OpenSSLCertificateSigningRequest ; anteriormente, se aceptaba un resource de tipo `OpenSSL X.509 CSR`.

### Ejemplos

Ejemplo #1 Ejemplo de openssl_csr_get_public_key()

    <?php
    $subject = array(
        "commonName" => "example.com",
    );
    $private_key = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha256') );
    $public_key = openssl_csr_get_public_key($csr);
    $info = openssl_pkey_get_details($public_key);
    echo $info['key'];
    ?>

### Ver también

- openssl_csr_get_subject() - Retorna el sujeto de una CSR
- openssl_csr_new() - Genera una CSR
- openssl_pkey_get_details() - Devuelve un array que contiene los detalles de la clave
- openssl_pkey_export_to_file() - Guarda una clave en formato ASCII en un fichero
- openssl_pkey_export() - Almacena una representación exportable de la clave en una cadena de caracteres

# openssl_csr_get_subject

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_csr_get_subject — Retorna el sujeto de una CSR

### Descripción

function openssl_csr_get_subject(OpenSSLCertificateSigningRequest|string `$csr`, bool `$short_names` = `true`): array|false

openssl_csr_get_subject() retorna las informaciones sobre el nombre distintivo del sujeto codificado en el `csr`, incluyendo los campos commonName (CN), organizationName (O), countryName (C) etc.

### Parámetros

`csr`
  Ver los parámetros CSR para obtener una lista de los valores válidos.
`short_names`

  `short_names` controla cómo los datos son indexados en el array - si `short_names` es `true` (por omisión) entonces los campos serán indexados con la forma corta del nombre, de lo contrario el nombre completo será utilizado - por ejemplo: CN es la forma corta de commonName.

### Valores devueltos

Retorna un array asociativo con las descripciones de los sujetos, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `csr` ahora acepta una instancia de OpenSSLCertificateSigningRequest ; anteriormente, se aceptaba un resource de tipo `OpenSSL X.509 CSR`.

### Ejemplos

Ejemplo #1 Ejemplo con openssl_csr_get_subject()

    <?php
    $subject = array(
        "countryName" => "CA",
        "stateOrProvinceName" => "Alberta",
        "localityName" => "Calgary",
        "organizationName" => "XYZ Widgets Inc",
        "organizationalUnitName" => "PHP Documentation Team",
        "commonName" => "Wez Furlong",
        "emailAddress" => "wez@example.com",
    );
    $private_key = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $configargs = array(
        'digest_alg' => 'sha512WithRSAEncryption'
    );
    $csr = openssl_csr_new($subject, $privkey, $configargs);
    print_r(openssl_csr_get_subject($csr));
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [C] => CA
        [ST] => Alberta
        [L] => Calgary
        [O] => XYZ Widgets Inc
        [OU] => PHP Documentation Team
        [CN] => Wez Furlong
        [emailAddress] => wez@example.com
    )

### Ver también

- openssl_csr_new() - Genera una CSR
- openssl_csr_get_public_key() - Devuelve la clave pública de un CSR
- openssl_x509_parse() - Analiza un certificado X509

# openssl_csr_new

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_new — Genera una CSR

### Descripción

function openssl_csr_new(
array `$distinguished_names`,
#[\SensitiveParameter]?OpenSSLAsymmetricKey `&$private_key`,
?array `$options` = `null`,
?array `$extra_attributes` = `null`
): OpenSSLCertificateSigningRequest|bool

openssl_csr_new() genera una nueva CSR (requisición de firma de certificado), basada en la información proporcionada por `distinguished_names`.

> Nota: Debe existir un archivo openssl.cnf válido e instalado para que esta función opere correctamente. Ver las notas encontradas en la sección concerniente a la instalación para más información.

### Parámetros

`distinguished_names`

  El nombre distintivo (Distinguished Name) o los campos del sujeto a incluir en el certificado. El `distinguished_names` es un array asociativo cuyas claves representan los nombres de atributos de los Distinguished Names, y los valores pueden ser cadenas (para un valor único) o arrays (si se deben definir varios valores).

`private_key`

  `private_key` debe ser una clave privada que haya sido generada por openssl_pkey_new() (u obtenida de otro modo mediante alguna de las funciones de la familia openssl_pkey), o la variable `null`. Si su valor es una variable `null`, se genera una nueva clave privada según las `options` proporcionadas y se asigna a la variable suministrada. La parte pública correspondiente de la clave se utilizará para firmar la CSR.

`options`

  Por omisión, se utiliza el archivo `openssl.conf` del sistema para inicializar la requisición; puede especificarse una sección del archivo de configuración configurando la clave `config_section_section` en `options`. También puede especificarse un archivo de configuración alternativo de OpenSSL configurando el valor de `config` con la ruta del archivo a utilizar. Si las claves siguientes están presentes en `options`, se comportan como sus equivalentes en `openssl.conf`, según la lista siguiente.

  Sobrescribir configuración
  `options` | tipo | Equivalente de `openssl.conf` | descripción
  --- | --- | --- | ---
  digest_alg | string | default_md | Método de digest o firma de hash, generalmente uno de openssl_get_md_methods()
  x509_extensions | string | x509_extensions | Selecciona qué extensión utilizar al crear un certificado x509
  req_extensions | string | req_extensions | Selecciona qué extensión utilizar al crear una CSR
  private_key_bits | int | default_bits | Especifica la longitud en bits de la clave privada
  private_key_type | int | none | Especifica el tipo de clave privada a crear. Puede ser uno de `OPENSSL_KEYTYPE_DSA`, `OPENSSL_KEYTYPE_DH`, `OPENSSL_KEYTYPE_RSA` o `OPENSSL_KEYTYPE_EC`. El valor por omisión es `OPENSSL_KEYTYPE_RSA`.
  encrypt_key | bool | encrypt_key | ¿Debe estar cifrada la clave (con contraseña) exportada?
  encrypt_key_cipher | int | none | Una de las constantes cipher.
  curve_name | string | none | Uno de openssl_get_curve_names().
  config | string | N/A | Ruta hacia su archivo openssl.conf alternativo.

`extra_attributes`

  `extra_attributes` se utiliza para especificar atributos adicionales para la CSR. Se trata de un array asociativo cuyas claves se convierten en OID y se aplican como atributos de CSR.

### Valores devueltos

Devuelve la CSR en caso de éxito, `true` si la creación de la CSR tiene éxito pero falla la firma o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | El array asociativo `distinguished_names` ahora admite arrays como valores, permitiendo especificar varios valores para un mismo atributo.
8.4.0 | El parámetro `extra_attributes` ahora define correctamente los atributos del CSR, en lugar de modificar el nombre distintivo del sujeto como hacía anteriormente de forma incorrecta.
8.0.0 | `csr` ahora acepta una instancia de OpenSSLCertificateSigningRequest ; anteriormente, se aceptaba un resource de tipo `OpenSSL X.509 CSR`.
8.0.0 | En caso de éxito, esta función ahora devuelve una instancia de OpenSSLAsymmetricKey ; anteriormente se devolvía una resource de tipo `OpenSSL key`.
7.1.0 | `options` ahora admite `curve_name`.

### Ejemplos

Ejemplo #1 Creación de un certificado autosignado

    <?php
    // para certificados SSL de servidor, el commonName es el nombre de dominio a proteger
    // para certificados de correo electrónico S/MIME el commonName es el propietario de la dirección de correo
    // los campos de ubicación e identificación hacen referencia al propietario del dominio o al objeto del correo a proteger
    $dn = array(
        "countryName" => "GB",
        "stateOrProvinceName" => "Somerset",
        "localityName" => "Glastonbury",
        "organizationName" => "The Brain Room Limited",
        "organizationalUnitName" => "PHP Documentation Team",
        "commonName" => "Wez Furlong",
        "emailAddress" => "wez@example.com"
    );

    // Genera un nuevo par de claves privada (y pública)
    $privkey = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));

    // Genera una requisición de firma de certificado
    $csr = openssl_csr_new($dn, $privkey, array('digest_alg' => 'sha256'));

    // Genera un certificado autosignado, válido durante 365 días
    $x509 = openssl_csr_sign($csr, null, $privkey, $days=365, array('digest_alg' => 'sha256'));

    // Guarde su clave privada, CSR y certificado autosignado para uso posterior
    openssl_csr_export($csr, $csrout) and var_dump($csrout);
    openssl_x509_export($x509, $certout) and var_dump($certout);
    openssl_pkey_export($privkey, $pkeyout, "mypassword") and var_dump($pkeyout);

    // Muestra los errores que han ocurrido
    while (($e = openssl_error_string()) !== false) {
        echo $e . "\n";
    }
    ?>

Ejemplo #2 Crear un certificado ECC autosignado (a partir de PHP 7.1.0)

    <?php
    $subject = array(
        "commonName" => "docs.php.net",
    );

    // Genera un nuevo par de claves privada (y pública)
    $private_key = openssl_pkey_new(array(
        "private_key_type" => OPENSSL_KEYTYPE_EC,
        "curve_name" => 'prime256v1',
    ));

    // Genera una requisición de firma de certificado
    $csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha384'));

    // Genera un certificado EC autosignado
    $x509 = openssl_csr_sign($csr, null, $private_key, $days=365, array('digest_alg' => 'sha384'));
    openssl_x509_export_to_file($x509, 'ecc-cert.pem');
    openssl_pkey_export_to_file($private_key, 'ecc-private.key');
    ?>

### Ver también

- openssl_csr_sign() - Firma un CSR con otro certificado (o consigo mismo) y genera un certificado

# openssl_csr_sign

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_sign — Firma un CSR con otro certificado (o consigo mismo) y genera un certificado

### Descripción

function openssl_csr_sign(
OpenSSLCertificateSigningRequest|string `$csr`,
OpenSSLCertificate|string|null `$ca_certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
int `$days`,
?array `$options` = `null`,
int `$serial` = 0,
?string `$serial_hex` = `null`
): OpenSSLCertificate|false

openssl_csr_sign() genera un certificado x509 desde el CSR proporcionado.

> Nota: Debe existir un archivo openssl.cnf válido e instalado para que esta función opere correctamente. Ver las notas encontradas en la sección concerniente a la instalación para más información.

### Parámetros

`csr`

  Un CSR generado previamente por openssl_csr_new(). Sin embargo, esto también puede ser la ruta hacia un CSR codificado en formato PEM si se especifica con file://path/to/csr o una cadena exportada generada por openssl_csr_export().

`ca_certificate`

  El certificado generado será firmado por el certificado `ca_certificate`. Si `ca_certificate` es `null`, el certificado generado será autosignado.

`private_key`

  `private_key` es la clave privada que corresponde al certificado `ca_certificate`.

`days`

  `days` especifica la duración para la cual el certificado es válido, en número de días.

`options`

  Se pueden ajustar las opciones de firma CSR con `options`. Consulte la función openssl_csr_new() para obtener más información sobre `options`.

`serial`

  Un número de serie opcional para el certificado emitido. Si no se especifica, tendrá un valor de 0.

`serial_hex`

  Una cadena hexadecimal opcional que representa el número de serie del certificado emitido. Si se define, tiene prioridad sobre el valor del parámetro `serial`. Si no se especifica o se define como `null`, se utiliza el valor del parámetro `serial` en su lugar.

### Valores devueltos

Devuelve una instancia de OpenSSLCertificate en caso de éxito, `false` en caso contrario.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Se ha añadido el parámetro `serial_hex`.
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de OpenSSLCertificate ; anteriormente se devolvía un resource de tipo `OpenSSL X.509`.
8.0.0 | `csr` ahora acepta una instancia de OpenSSLCertificateSigningRequest ; anteriormente se aceptaba un resource de tipo `OpenSSL X.509 CSR`.
8.0.0 | `ca_certificate` ahora acepta una instancia de OpenSSLCertificate ; anteriormente se aceptaba un resource de tipo `OpenSSL X.509`.
8.0.0 | `ca_certificate` ahora acepta una instancia de OpenSSLAsymmetricKey o OpenSSLCertificate ; anteriormente se aceptaba un resource de tipo `OpenSSL key` o `OpenSSL X.509`.

### Ejemplos

Ejemplo #1 Ejemplo con openssl_csr_sign() - firmar una CSR (cómo ser su propia Autoridad de Certificación)

    <?php
    // Supongamos que este script está configurado para recibir CSR que han
    // sido pegados en un campo textarea desde otra página
    $csrdata = $_POST["CSR"];

    // Vamos a firmar la solicitud con nuestro propio certificado, como
    // "autoridad de certificación". Puede utilizarse cualquier certificado para firmar otro,
    // pero el proceso es inútil a menos que el certificado de firma tenga la confianza de los usuarios
    // que utilizarán el nuevo certificado firmado.

    // Necesitamos nuestro certificado y la clave privada
    $cacert = "file://path/to/ca.crt";
    $privkey = array("file://path/to/ca.key", "la_clave_secreta_de_su_certificado");

    $usercert = openssl_csr_sign($csrdata, $cacert, $privkey, 365, array('digest_alg'=>'sha256') );

    // Mostramos ahora el certificado generado, de forma que el usuario
    // pueda copiarlo/pegarlo en su configuración local (como un
    // archivo que contiene los certificados de su servidor SSL)
    openssl_x509_export($usercert, $certout);
    echo $certout;

    // Muestra todos los errores ocurridos
    while (($e = openssl_error_string()) !== false) {
        echo $e . "\n";
    }
    ?>

# openssl_decrypt

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_decrypt — Descifrar los datos

### Descripción

function openssl_decrypt(
string `$data`,
string `$cipher_algo`,
#[\SensitiveParameter]string `$passphrase`,
int `$options` = 0,
string `$iv` = "",
?string `$tag` = `null`,
string `$aad` = ""
): string|false

Toma una cadena sin tratar o codificada en base64 y la descifra utilizando el método y la frase de contraseña proporcionados.

### Parámetros

`data`

  El mensaje cifrado a descifrar.

`cipher_algo`

  El algoritmo de cifrado. Para obtener la lista de algoritmos de cifrado disponibles, utilizar openssl_get_cipher_methods().

`passphrase`

  La frase de contraseña. Si la frase de contraseña es más corta de lo esperado, se completa silenciosamente con caracteres `NUL`; si la frase de contraseña es más larga de lo esperado, se trunca silenciosamente.

  Precaución

  No se utiliza ninguna función de derivación de clave para el parámetro `passphrase` como su nombre podría sugerir. La única operación utilizada es el relleno con caracteres `NUL` o la truncación si la longitud es diferente de la esperada.

`options`

  El parámetro `options` puede tomar como valor `OPENSSL_RAW_DATA` o `OPENSSL_ZERO_PADDING` o `OPENSSL_DONT_ZERO_PAD_KEY`.

`iv`

  Un vector de inicialización no-`null`. Si el VI es más corto de lo esperado, se completa con caracteres `NUL` y se emite un aviso; si la frase de contraseña es más larga de lo esperado, se trunca y se emite un aviso.

`tag`

  La etiqueta de autenticación en modo de cifrado AEAD. Si es incorrecta, la autenticación falla y la función devuelve `false`.

  Precaución

  La longitud de `tag` no es verificada por la función. Es responsabilidad del llamador asegurarse de que la longitud del tag coincida con la longitud del tag recibido cuando openssl_encrypt() fue llamada. De lo contrario, el descifrado puede tener éxito si el inicio del tag proporcionado coincide con el inicio del verdadero tag.

`aad`

  Datos adicionales autenticados.

### Valores devueltos

La cadena descifrada en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Emite un error de nivel `E_WARNING` si se pasa un algoritmo de cifrado desconocido a través de `cipher_algo`.

Emite un error de nivel `E_WARNING` si se pasa un valor vacío como parámetro `iv`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | `tag` ahora es nullable.
7.1.0 | Se añadieron los parámetros `tag` y `aad`.

### Ver también

- openssl_encrypt() - Cifra los datos

# openssl_dh_compute_key

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_dh_compute_key — Calcula un secreto compartido para un valor público de la clave DH pública remota y la clave DH local

### Descripción

function openssl_dh_compute_key(string `$public_key`, #[\SensitiveParameter]OpenSSLAsymmetricKey `$private_key`): string|false

El secreto compartido devuelto por openssl_dh_compute_key() se utiliza a menudo como una clave de cifrado para comunicarse de forma secreta con una parte remota. Esto es conocido como el intercambio de claves Diffie-Hellman.

Precaución

Es importante utilizar los mismos parámetros DH para los pares de claves locales y remotas; de lo contrario, el secreto generado entre las dos partes no coincidirá.

> Nota: ECDH solo es compatible a partir de PHP 8.1.0 y OpenSSL 3.0.0.

### Parámetros

`public_key`

  Clave DH pública de la parte remota.

`private_key`

  Una clave DH privada local, correspondiente a la clave pública a compartir con la parte remota.

### Valores devueltos

Devuelve el secreto compartido en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `private_key` ahora acepta una instancia de OpenSSLAsymmetricKey ; anteriormente, se aceptaba un resource de tipo `OpenSSL key`.

### Ejemplos

Ejemplo #1 Calcular un secreto compartido

Primero, se genera localmente un par de claves DH pública/privada y se solicita a la parte remota que haga lo mismo. Se debe utilizar la utilidad de línea de comandos `openssl`

    # generar un par de claves privada/pública
    openssl dhparam -out dhparam.pem 2048
    openssl genpkey -paramfile dhparam.pem -out privatekey.pem

    # extraer solo la clave pública
    openssl pkey -in privatekey.pem -pubout -out publickey.pem

Ahora, envíe su clave pública a la parte remota. Utilice el comando `openssl pkey` para mostrar la clave pública que le será enviada por la parte remota.

    openssl pkey -pubin -in remotepublickey.pem -text -noout

Resultado del ejemplo anterior es similar a:

    PKCS#3 DH Public-Key: (2048 bit)
        public-key:
            67:e5:e5:fa:e0:7b:0f:96:2c:dc:96:44:5f:50:02:
            9e:8d:c2:6c:04:68:b0:d1:1d:75:66:fc:63:f5:e3:
            42:30:b8:96:c1:45:cc:08:60:b4:21:3b:dd:ee:66:
            88:db:77:d9:1e:11:89:d4:5c:f2:7a:f2:f1:fe:1c:
            77:9d:6f:13:b8:b2:56:00:ef:cb:3b:60:79:74:02:
            98:f5:f9:8e:3e:b5:62:08:de:ca:8c:c3:40:4a:80:
            79:d5:43:06:17:a8:19:56:af:cc:95:5e:e2:32:2d:
            d2:14:7b:76:5a:9a:f1:3c:76:76:35:cc:7b:c1:a5:
            f4:39:e5:b6:ca:71:3f:7c:3f:97:e5:ab:86:c1:cd:
            0e:e6:ee:04:c9:e6:2d:80:7e:59:c0:49:eb:b6:64:
            4f:a8:f9:bb:a3:87:b3:3d:76:01:9e:2b:16:94:a4:
            37:30:fb:35:e2:63:be:23:90:b9:ef:3f:46:46:04:
            94:8f:60:79:7a:51:55:d6:1a:1d:f5:d9:7f:4a:3e:
            aa:ac:b0:d0:82:cc:c2:e0:94:e0:54:c1:17:83:0b:
            74:08:4d:5a:79:ae:ff:7f:1c:04:ab:23:39:4a:ae:
            87:83:55:43:ab:7a:7c:04:9d:20:80:bb:af:5f:16:
            a3:e3:20:b9:21:47:8c:f8:7f:a8:60:80:9e:61:77:
            36
     [...abbreviated...]

Utilizar esta clave pública como argumento para openssl_dh_compute_key() para calcular el secreto compartido.

    <?php
    $remote_public_key = '67e5e5fae07b0f962cdc96445f50029e8dc26c0468b0d11d7566fc63f5e34230b896c145cc0860b4213bddee6688db77d91e1189d45cf27af2f1fe1c779d6f13b8b25600efcb3b6079740298f5f98e3eb56208deca8cc3404a8079d5430617a81956afcc955ee2322dd2147b765a9af13c767635cc7bc1a5f439e5b6ca713f7c3f97e5ab86c1cd0ee6ee04c9e62d807e59c049ebb6644fa8f9bba387b33d76019e2b1694a43730fb35e263be2390b9ef3f464604948f60797a5155d61a1df5d97f4a3eaaacb0d082ccc2e094e054c117830b74084d5a79aeff7f1c04ab23394aae87835543ab7a7c049d2080bbaf5f16a3e320b921478cf87fa860809e617736';

    $local_priv_key = openssl_pkey_get_private('file://privatekey.pem');

    $shared_secret = openssl_dh_compute_key(hex2bin($remote_public_key), $local_priv_key);
    echo bin2hex($shared_secret)."\n";
    ?>

Ejemplo #2 Generar un par de claves DH pública/privada en PHP

Primero, generar el número primo DH

    openssl dhparam -out dhparam.pem 2048
    openssl dh -in dhparam.pem -noout  -text

Resultado del ejemplo anterior es similar a:

    PKCS#3 DH Parameters: (2048 bit)
            prime:
                00:a3:25:1e:73:3f:44:b9:2b:ee:f4:9d:9f:37:6a:
                4b:fd:1d:bd:f4:af:da:c8:10:77:59:41:c6:5f:73:
                d2:88:29:39:cd:1c:5f:c3:9f:0f:22:d2:9c:20:c1:
                e4:c0:18:03:b8:b6:d8:da:ad:3b:39:a6:da:8e:fe:
                12:30:e9:03:5d:22:ba:ef:18:d2:7b:69:f9:5b:cb:
                78:c6:0c:8c:6b:f2:49:92:c2:49:e0:45:77:72:b3:
                55:36:30:f2:40:17:89:18:50:03:fa:2d:54:7a:7f:
                34:4c:73:32:b6:88:14:51:14:be:80:57:95:e6:a3:
                f6:51:ff:17:47:4f:15:d6:0e:6c:47:53:72:2c:2a:
                4c:21:cb:7d:f3:49:97:c9:47:5e:40:33:7b:99:52:
                7e:7a:f3:52:27:80:de:1b:26:6b:40:bb:14:11:0b:
                fb:e6:d8:2f:cf:a0:06:2f:96:b9:1c:0b:b4:cb:d3:
                a6:62:9c:48:67:f6:81:f2:c6:ff:45:03:0a:9d:67:
                9d:ce:27:d9:6b:48:5d:ca:fb:c2:5d:84:9b:8b:cb:
                40:c7:a4:0c:8a:6e:f4:ab:ba:b6:10:c3:b8:25:4d:
                cf:60:96:f4:db:e8:00:1c:58:47:7a:fb:51:86:d1:
                22:d7:4e:94:31:7a:d5:da:3d:53:de:da:bb:64:8d:
                62:6b
            generator: 2 (0x2)

El número primo y los valores del generador se pasan como p y q en openssl_pkey_new()

    <?php
    $configargs = array();
    $configargs['p'] = hex2bin('00a3251e733f44b92beef49d9f376a4bfd1dbdf4afdac810775941c65f73d2882939cd1c5fc39f0f22d29c20c1e4c01803b8b6d8daad3b39a6da8efe1230e9035d22baef18d27b69f95bcb78c60c8c6bf24992c249e0457772b3553630f2401789185003fa2d547a7f344c7332b688145114be805795e6a3f651ff17474f15d60e6c4753722c2a4c21cb7df34997c9475e40337b99527e7af3522780de1b266b40bb14110bfbe6d82fcfa0062f96b91c0bb4cbd3a6629c4867f681f2c6ff45030a9d679dce27d96b485dcafbc25d849b8bcb40c7a40c8a6ef4abbab610c3b8254dcf6096f4dbe8001c58477afb5186d122d74e94317ad5da3d53dedabb648d626b');
    $configargs['g'] = hex2bin('02');
    $private_key = openssl_pkey_new(array('dh' => $configargs));
    openssl_pkey_export_to_file($private_key,'privatekey.pem',$passphrase='y0urp@s5phr@se');

    $details = openssl_pkey_get_details($private_key);
    $local_pub_key = $details['dh']['pub_key'];
    echo bin2hex($local_pub_key)."\n";
    // puede enviar su clave pública a la parte remota

    $details = openssl_pkey_get_details(openssl_pkey_get_public("file://remotepublickey.pem"));
    $remote_public_key = $details['dh']['pub_key'];
    $shared_secret = openssl_dh_compute_key($remote_public_key, $private_key);
    echo bin2hex($shared_secret)."\n";
    ?>

### Ver también

- openssl_pkey_new() - Genera una nueva clave privada
- openssl_pkey_get_details() - Devuelve un array que contiene los detalles de la clave
- openssl_pkey_get_private() - Lee una clave privada
- openssl_pkey_get_public() - Extrae una clave pública de un certificado y la prepara

# openssl_digest

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_digest — Calcula un digest

### Descripción

function openssl_digest(string `$data`, string `$digest_algo`, bool `$binary` = `false`): string|false

Calcula un hash digest para los datos de entrada utilizando el método proporcionado. Devuelve un string bruto o hexadecimal.

### Parámetros

`data`

  Los datos.

`digest_algo`

  El método digest a utilizar, por ejemplo "SHA256". Consulte openssl_get_md_methods() para obtener la lista de métodos de digest disponibles.

`binary`

  Pase a `true` y se devolverá un dato bruto, de lo contrario el valor devuelto será hexadecimal.

### Valores devueltos

Devuelve el valor en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Emite un error de nivel `E_WARNING` si se pasa un algoritmo desconocido al argumento `digest_algo`.

### Ver también

- openssl_get_md_methods() - Obtiene la lista de métodos digest disponibles

# openssl_encrypt

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_encrypt — Cifra los datos

### Descripción

function openssl_encrypt(
#[\SensitiveParameter]string `$data`,
string `$cipher_algo`,
#[\SensitiveParameter]string `$passphrase`,
int `$options` = 0,
string `$iv` = "",
string `&$tag` = `null`,
string `$aad` = "",
int `$tag_length` = 16
): string|false

Cifra los datos pasados con el método y la frase de contraseña especificados. Devuelve un string bruto o codificado en base64.

### Parámetros

`data`

  Los datos del mensaje en texto bruto a cifrar.

`cipher_algo`

  El método de cifrado. Para una lista de los métodos de cifrado disponibles, utilizar openssl_get_cipher_methods().

`passphrase`

  La frase de contraseña. Si la frase de contraseña es más corta de lo esperado, se rellena silenciosamente con caracteres `NUL`; si la frase de contraseña es más larga de lo esperado, se trunca silenciosamente.

  Precaución

  No se utiliza ninguna función de derivación de clave para el parámetro `passphrase` como su nombre podría sugerir. La única operación utilizada es el relleno con caracteres `NUL` o la truncación si la longitud es diferente de la esperada.

`options`

  `options` es una disyunción a nivel de bits de los flags `OPENSSL_RAW_DATA` y `OPENSSL_ZERO_PADDING` o `OPENSSL_DONT_ZERO_PAD_KEY`.

`iv`

  Un vector de inicialización no-`null`. Si el IV es más corto de lo esperado, se completa con caracteres `NUL` y se emite un aviso; si la frase de contraseña es más larga de lo esperado, se trunca y se emite un aviso.

`tag`

  La etiqueta de autenticación pasada por referencia al utilizar el modo de cifrado AEAD (GCM o CCM).

`aad`

  Datos adicionales autenticados.

`tag_length`

  La longitud de la `tag` de autenticación. Su valor puede estar entre 4 y 16 para el modo GCM.

### Valores devueltos

Devuelve la cadena cifrada en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Emite un error de nivel `E_WARNING` si se pasa un algoritmo de cifrado desconocido como parámetro `cipher_algo`.

Emite un error de nivel `E_WARNING` si se pasa un valor vacío como parámetro `iv`.

### Historial de cambios

Versión | Descripción
--- | ---
7.1.0 | Se añadieron los parámetros `tag`, `aad` y `tag_length`.

### Ejemplos

Ejemplo #1 Ejemplo de cifrado autenticado AES en modo GCM para PHP 7.1+

    <?php
    //$key debería ser generado previamente de manera criptográfica, tal como openssl_random_pseudo_bytes
    $plaintext = "message to be encrypted";
    $cipher = "aes-128-gcm";
    if (in_array($cipher, openssl_get_cipher_methods()))
    {
        $ivlen = openssl_cipher_iv_length($cipher);
        $iv = openssl_random_pseudo_bytes($ivlen);
        $ciphertext = openssl_encrypt($plaintext, $cipher, $key, $options=0, $iv, $tag);
        //guardar $cipher, $iv, y $tag para el descifrado posterior
        $original_plaintext = openssl_decrypt($ciphertext, $cipher, $key, $options=0, $iv, $tag);
        echo $original_plaintext."\n";
    }
    ?>

Ejemplo #2 Ejemplo de cifrado autenticado AES en modo GCM anterior a PHP 7.1

    <?php
    //$key debería ser generado previamente de manera criptográfica, tal como openssl_random_pseudo_bytes
    $plaintext = "message to be encrypted";
    $ivlen = openssl_cipher_iv_length($cipher="AES-128-CBC");
    $iv = openssl_random_pseudo_bytes($ivlen);
    $ciphertext_raw = openssl_encrypt($plaintext, $cipher, $key, $options=OPENSSL_RAW_DATA, $iv);
    $hmac = hash_hmac('sha256', $ciphertext_raw, $key, $as_binary=true);
    $ciphertext = base64_encode( $iv.$hmac.$ciphertext_raw );

    // descifrar más tarde ...
    $c = base64_decode($ciphertext);
    $ivlen = openssl_cipher_iv_length($cipher="AES-128-CBC");
    $iv = substr($c, 0, $ivlen);
    $hmac = substr($c, $ivlen, $sha2len=32);
    $ciphertext_raw = substr($c, $ivlen+$sha2len);
    $original_plaintext = openssl_decrypt($ciphertext_raw, $cipher, $key, $options=OPENSSL_RAW_DATA, $iv);
    $calcmac = hash_hmac('sha256', $ciphertext_raw, $key, $as_binary=true);
    if (hash_equals($hmac, $calcmac))// comparación segura contra ataques de tiempo
    {
        echo $original_plaintext."\n";
    }
    ?>

### Ver también

- openssl_decrypt() - Descifrar los datos

# openssl_error_string

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_error_string — Retorna el mensaje de error OpenSSL

### Descripción

function openssl_error_string(): string|false

openssl_error_string() retorna el último error de la biblioteca OpenSSL. Los mensajes de error son puestos en cola, y la función openssl_error_string() debe ser llamada varias veces para mostrar todos los errores. El último error será el más reciente en esta cola.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Retorna un mensaje de error, en forma de string, o `false` si no hay más mensajes que mostrar.

### Ejemplos

Ejemplo #1 Ejemplo con openssl_error_string()

    <?php
    // Supongamos que se ha llamado a una función que ha generado un error
    while ($msg = openssl_error_string())
        echo $msg . "<br />\n";
    ?>

# openssl_free_key

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_free_key — Libera los recursos

Advertencia

Esta función está OBSOLETA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function openssl_free_key(OpenSSLAsymmetricKey `$key`): void

openssl_free_key() libera las claves asociadas a `key` de la memoria.

### Parámetros

`key`

### Valores devueltos

No se retorna ningún valor.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función es ahora obsoleta ya que no tiene ningún efecto.
8.0.0 | `key` acepta ahora una instancia de OpenSSLAsymmetricKey; anteriormente, se aceptaba un resource de tipo `OpenSSL key`.

# openssl_get_cert_locations

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_get_cert_locations — Obtener las ubicaciones de certificados disponibles

### Descripción

function openssl_get_cert_locations(): array

openssl_get_cert_locations() devuelve un array con información sobre la ubicaciones de certificados disponibles donde buscar certificados SSL.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array con las ubicaciones de certificados disponibles.

### Ejemplos

Ejemplo #1 Ejemplo de openssl_get_cert_locations()

    <?php
    var_dump(openssl_get_cert_locations());
    ?>

El ejemplo anterior mostrará:

    array(8) {
      ["default_cert_file"]=>
      string(21) "/usr/lib/ssl/cert.pem"
      ["default_cert_file_env"]=>
      string(13) "SSL_CERT_FILE"
      ["default_cert_dir"]=>
      string(18) "/usr/lib/ssl/certs"
      ["default_cert_dir_env"]=>
      string(12) "SSL_CERT_DIR"
      ["default_private_dir"]=>
      string(20) "/usr/lib/ssl/private"
      ["default_default_cert_area"]=>
      string(12) "/usr/lib/ssl"
      ["ini_cafile"]=>
      string(0) ""
      ["ini_capath"]=>
      string(0) ""
    }

# openssl_get_cipher_methods

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_get_cipher_methods — Obtiene la lista de métodos de cifrado disponibles

### Descripción

function openssl_get_cipher_methods(bool `$aliases` = `false`): array

Obtiene la lista de métodos de cifrado disponibles.

### Parámetros

`aliases`

  Pásese `true` si se desea que los alias de los métodos de cifrado sean incluidos en el array devuelto.

### Valores devueltos

Un array de los métodos de cifrado disponibles. Cabe señalar que antes de OpenSSL 1.1.1, los métodos de cifrado se devolvían en mayúsculas y minúsculas; a partir de OpenSSL 1.1.1 solo se devuelve la variante en minúsculas.

### Ejemplos

Ejemplo #1 Ejemplo openssl_get_cipher_methods()

Muestra cómo son los ciphers disponibles, así como los alias disponibles.

    <?php
    $ciphers             = openssl_get_cipher_methods();
    $ciphers_and_aliases = openssl_get_cipher_methods(true);
    $cipher_aliases      = array_diff($ciphers_and_aliases, $ciphers);

    //ECB mode should be avoided
    $ciphers = array_filter( $ciphers, function($n) { return stripos($n,"ecb")===FALSE; } );

    //At least as early as Aug 2016, Openssl declared the following weak: RC2, RC4, DES, 3DES, MD5 based
    $ciphers = array_filter( $ciphers, function($c) { return stripos($c,"des")===FALSE; } );
    $ciphers = array_filter( $ciphers, function($c) { return stripos($c,"rc2")===FALSE; } );
    $ciphers = array_filter( $ciphers, function($c) { return stripos($c,"rc4")===FALSE; } );
    $ciphers = array_filter( $ciphers, function($c) { return stripos($c,"md5")===FALSE; } );
    $cipher_aliases = array_filter($cipher_aliases,function($c) { return stripos($c,"des")===FALSE; } );
    $cipher_aliases = array_filter($cipher_aliases,function($c) { return stripos($c,"rc2")===FALSE; } );

    print_r($ciphers);
    print_r($cipher_aliases);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => aes-128-cbc
        [1] => aes-128-cbc-hmac-sha1
        [2] => aes-128-cbc-hmac-sha256
        [3] => aes-128-ccm
        [4] => aes-128-cfb
        [5] => aes-128-cfb1
        [6] => aes-128-cfb8
        [7] => aes-128-ctr
        [9] => aes-128-gcm
        [10] => aes-128-ocb
        [11] => aes-128-ofb
        [12] => aes-128-xts
        [13] => aes-192-cbc
        [14] => aes-192-ccm
        [15] => aes-192-cfb
        [16] => aes-192-cfb1
        [17] => aes-192-cfb8
        [18] => aes-192-ctr
        [20] => aes-192-gcm
        [21] => aes-192-ocb
        [22] => aes-192-ofb
        [23] => aes-256-cbc
        [24] => aes-256-cbc-hmac-sha1
        [25] => aes-256-cbc-hmac-sha256
        [26] => aes-256-ccm
        [27] => aes-256-cfb
        [28] => aes-256-cfb1
        [29] => aes-256-cfb8
        [30] => aes-256-ctr
        [32] => aes-256-gcm
        [33] => aes-256-ocb
        [34] => aes-256-ofb
        [35] => aes-256-xts
        [36] => aria-128-cbc
        [37] => aria-128-ccm
        [38] => aria-128-cfb
        [39] => aria-128-cfb1
        [40] => aria-128-cfb8
        [41] => aria-128-ctr
        [43] => aria-128-gcm
        [44] => aria-128-ofb
        [45] => aria-192-cbc
        [46] => aria-192-ccm
        [47] => aria-192-cfb
        [48] => aria-192-cfb1
        [49] => aria-192-cfb8
        [50] => aria-192-ctr
        [52] => aria-192-gcm
        [53] => aria-192-ofb
        [54] => aria-256-cbc
        [55] => aria-256-ccm
        [56] => aria-256-cfb
        [57] => aria-256-cfb1
        [58] => aria-256-cfb8
        [59] => aria-256-ctr
        [61] => aria-256-gcm
        [62] => aria-256-ofb
        [63] => bf-cbc
        [64] => bf-cfb
        [66] => bf-ofb
        [67] => camellia-128-cbc
        [68] => camellia-128-cfb
        [69] => camellia-128-cfb1
        [70] => camellia-128-cfb8
        [71] => camellia-128-ctr
        [73] => camellia-128-ofb
        [74] => camellia-192-cbc
        [75] => camellia-192-cfb
        [76] => camellia-192-cfb1
        [77] => camellia-192-cfb8
        [78] => camellia-192-ctr
        [80] => camellia-192-ofb
        [81] => camellia-256-cbc
        [82] => camellia-256-cfb
        [83] => camellia-256-cfb1
        [84] => camellia-256-cfb8
        [85] => camellia-256-ctr
        [87] => camellia-256-ofb
        [88] => cast5-cbc
        [89] => cast5-cfb
        [91] => cast5-ofb
        [92] => chacha20
        [93] => chacha20-poly1305
        [111] => id-aes128-CCM
        [112] => id-aes128-GCM
        [113] => id-aes128-wrap
        [114] => id-aes128-wrap-pad
        [115] => id-aes192-CCM
        [116] => id-aes192-GCM
        [117] => id-aes192-wrap
        [118] => id-aes192-wrap-pad
        [119] => id-aes256-CCM
        [120] => id-aes256-GCM
        [121] => id-aes256-wrap
        [122] => id-aes256-wrap-pad
        [124] => idea-cbc
        [125] => idea-cfb
        [127] => idea-ofb
        [137] => seed-cbc
        [138] => seed-cfb
        [140] => seed-ofb
        [141] => sm4-cbc
        [142] => sm4-cfb
        [143] => sm4-ctr
        [145] => sm4-ofb
    )
    Array
    (
        [36] => aes128
        [37] => aes128-wrap
        [38] => aes192
        [39] => aes192-wrap
        [40] => aes256
        [41] => aes256-wrap
        [69] => aria128
        [70] => aria192
        [71] => aria256
        [72] => bf
        [77] => blowfish
        [99] => camellia128
        [100] => camellia192
        [101] => camellia256
        [102] => cast
        [103] => cast-cbc
        [146] => idea
        [164] => seed
        [169] => sm4
    )

### Ver también

- openssl_get_md_methods() - Obtiene la lista de métodos digest disponibles

# openssl_get_curve_names

(PHP 7 >= 7.1.0, PHP 8)

openssl_get_curve_names — Obtiene la lista de nombres de curvas disponibles para ECC

### Descripción

function openssl_get_curve_names(): array|false

Obtiene la lista de nombres de curvas disponibles para su uso en la criptografía de curva elíptica (ECC) para las operaciones de clave pública/privada. Las dos curvas más ampliamente estandarizadas/soportadas son prime256v1 (NIST P-256) y secp384r1 (NIST P-384).

Equivalencias aproximadas de tamaños de claves de AES, RSA, DSA y ECC
Tamaño de clave simétrica AES (Bits) | Tamaño de clave RSA y DSA (Bits) | Tamaño de clave ECC (Bits)
--- | --- | ---
80 | 1024 | 160
112 | 2048 | 224
128 | 3072 | 256
192 | 7680 | 384
256 | 15360 | 512

» NIST recomienda utilizar curvas ECC que tengan al menos 256 bits.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array de los nombres de curvas disponibles, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con openssl_get_curve_names()

    <?php
    $curve_names = openssl_get_curve_names();
    print_r($curve_names);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => secp112r1
        [1] => secp112r2
        [2] => secp128r1
        [3] => secp128r2
        [4] => secp160k1
        [5] => secp160r1
        [6] => secp160r2
        [7] => secp192k1
        [8] => secp224k1
        [9] => secp224r1
        [10] => secp256k1
        [11] => secp384r1
        [12] => secp521r1
        [13] => prime192v1
        [14] => prime192v2
        [15] => prime192v3
        [16] => prime239v1
        [17] => prime239v2
        [18] => prime239v3
        [19] => prime256v1
        [20] => sect113r1
        [21] => sect113r2
        [22] => sect131r1
        [23] => sect131r2
        [24] => sect163k1
        [25] => sect163r1
        [26] => sect163r2
        [27] => sect193r1
        [28] => sect193r2
        [29] => sect233k1
        [30] => sect233r1
        [31] => sect239k1
        [32] => sect283k1
        [33] => sect283r1
        [34] => sect409k1
        [35] => sect409r1
        [36] => sect571k1
        [37] => sect571r1
        [38] => c2pnb163v1
        [39] => c2pnb163v2
        [40] => c2pnb163v3
        [41] => c2pnb176v1
        [42] => c2tnb191v1
        [43] => c2tnb191v2
        [44] => c2tnb191v3
        [45] => c2pnb208w1
        [46] => c2tnb239v1
        [47] => c2tnb239v2
        [48] => c2tnb239v3
        [49] => c2pnb272w1
        [50] => c2pnb304w1
        [51] => c2tnb359v1
        [52] => c2pnb368w1
        [53] => c2tnb431r1
        [54] => wap-wsg-idm-ecid-wtls1
        [55] => wap-wsg-idm-ecid-wtls3
        [56] => wap-wsg-idm-ecid-wtls4
        [57] => wap-wsg-idm-ecid-wtls5
        [58] => wap-wsg-idm-ecid-wtls6
        [59] => wap-wsg-idm-ecid-wtls7
        [60] => wap-wsg-idm-ecid-wtls8
        [61] => wap-wsg-idm-ecid-wtls9
        [62] => wap-wsg-idm-ecid-wtls10
        [63] => wap-wsg-idm-ecid-wtls11
        [64] => wap-wsg-idm-ecid-wtls12
        [65] => Oakley-EC2N-3
        [66] => Oakley-EC2N-4
        [67] => brainpoolP160r1
        [68] => brainpoolP160t1
        [69] => brainpoolP192r1
        [70] => brainpoolP192t1
        [71] => brainpoolP224r1
        [72] => brainpoolP224t1
        [73] => brainpoolP256r1
        [74] => brainpoolP256t1
        [75] => brainpoolP320r1
        [76] => brainpoolP320t1
        [77] => brainpoolP384r1
        [78] => brainpoolP384t1
        [79] => brainpoolP512r1
        [80] => brainpoolP512t1
    )

# openssl_get_md_methods

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_get_md_methods — Obtiene la lista de métodos digest disponibles

### Descripción

function openssl_get_md_methods(bool `$aliases` = `false`): array

Obtiene la lista de métodos digest disponibles.

### Parámetros

`aliases`

  Pásese `true` si se desean incluir los alias de digest en el array devuelto.

### Valores devueltos

Un array de los métodos digest disponibles.

### Ejemplos

Ejemplo #1 Ejemplo openssl_get_md_methods()

Muestra cómo son los digests disponibles, así como los alias disponibles.

    <?php
    $digests             = openssl_get_md_methods();
    $digests_and_aliases = openssl_get_md_methods(true);
    $digest_aliases      = array_diff($digests_and_aliases, $digests);

    print_r($digests);

    print_r($digest_aliases);

    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => DSA
        [1] => DSA-SHA
        [2] => MD2
        [3] => MD4
        [4] => MD5
        [5] => RIPEMD160
        [6] => SHA
        [7] => SHA1
        [8] => SHA224
        [9] => SHA256
        [10] => SHA384
        [11] => SHA512
        [12] => dsaEncryption
        [13] => dsaWithSHA
        [14] => ecdsa-with-SHA1
        [15] => md2
        [16] => md4
        [17] => md5
        [18] => ripemd160
        [19] => sha
        [20] => sha1
        [21] => sha224
        [22] => sha256
        [23] => sha384
        [24] => sha512
    )
    Array
    (
        [2] => DSA-SHA1
        [3] => DSA-SHA1-old
        [4] => DSS1
        [9] => RSA-MD2
        [10] => RSA-MD4
        [11] => RSA-MD5
        [12] => RSA-RIPEMD160
        [13] => RSA-SHA
        [14] => RSA-SHA1
        [15] => RSA-SHA1-2
        [16] => RSA-SHA224
        [17] => RSA-SHA256
        [18] => RSA-SHA384
        [19] => RSA-SHA512
        [28] => dsaWithSHA1
        [29] => dss1
        [32] => md2WithRSAEncryption
        [34] => md4WithRSAEncryption
        [36] => md5WithRSAEncryption
        [37] => ripemd
        [39] => ripemd160WithRSA
        [40] => rmd160
        [43] => sha1WithRSAEncryption
        [45] => sha224WithRSAEncryption
        [47] => sha256WithRSAEncryption
        [49] => sha384WithRSAEncryption
        [51] => sha512WithRSAEncryption
        [52] => shaWithRSAEncryption
        [53] => ssl2-md5
        [54] => ssl3-md5
        [55] => ssl3-sha1
    )

### Ver también

- openssl_digest() - Calcula un digest
- openssl_get_cipher_methods() - Obtiene la lista de métodos de cifrado disponibles

# openssl_get_privatekey

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_get_privatekey — Alias de openssl_pkey_get_private()

### Descripción

Esta función es un alias de: openssl_pkey_get_private().

# openssl_get_publickey

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_get_publickey — Alias de openssl_pkey_get_public()

### Descripción

Esta función es un alias de: openssl_pkey_get_public().

# openssl_open

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_open — Abre datos sellados

### Descripción

function openssl_open(
string `$data`,
#[\SensitiveParameter]string `&$output`,
string `$encrypted_key`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
string `$cipher_algo`,
?string `$iv` = `null`
): bool

La openssl_open() abre (descifra) `data` utilizando una clave de envoltura que se descifra a partir de `encrypted_key` utilizando `private_key`. La descifrado se realiza mediante `cipher_algo` y `iv`. El IV es requerido únicamente si el método de cifrado lo exige. La función llena `output` con los datos descifrados. La clave de envoltura generalmente se genera cuando los datos son sellados utilizando una clave pública asociada a la clave privada. Consulte openssl_seal() para más información.

### Parámetros

`data`

  Los datos sellados.

`output`

  Si la llamada tiene éxito, los datos abiertos son devueltos en este parámetro.

`encrypted_key`

  La clave simétrica cifrada que puede ser descifrada utilizando `private_key`

`private_key`

  La clave privada utilizada para descifrar `encrypted_key`.

`cipher_algo`

  El método de cifrado utilizado para el descifrado de `data`.

  Precaución

  El valor por omisión para las versiones de PHP anteriores a 8.0 es (`'RC4'`), que es considerada como no segura. Se recomienda fuertemente especificar explícitamente un método de cifrado seguro.

`iv`

  El vector de inicialización utilizado para el descifrado de `data`. Es requerido si el método de cifrado necesita un IV. Esto puede ser determinado llamando a openssl_cipher_iv_length() con `cipher_algo`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `private_key` ahora acepta una instancia de OpenSSLAsymmetricKey o OpenSSLCertificate; anteriormente, se aceptaba un resource de tipo `OpenSSL key` o `OpenSSL X.509 CSR`.
8.0.0 | `cipher_algo` ya no es un parámetro opcional.

### Ejemplos

Ejemplo #1 Ejemplo con openssl_open()

    <?php

    // Se asume que $sealed, $env_key y $iv contienen los datos sellados,
    // la clave de envoltura y el IV. Todos proporcionados por el remitente.

    // Obtener la clave privada desde el archivo ubicado en private_key.pem
    $pkey = openssl_get_privatekey("file://private_key.pem");

    // Descifrado de los datos: se colocan en $open
    if (openssl_open($sealed, $open, $env_key, $pkey, 'AES256', $iv)) {
        echo "Aquí están los datos descifrados: ", $open;
    } else {
        echo "No se pudo descifrar los datos";
    }

    ?>

### Ver también

- openssl_seal() - Sella datos

# openssl_password_hash

(PHP 8 >= 8.4.0)

openssl_password_hash — Crea un hash de contraseña usando la implementación de Argon2 de OpenSSL

### Descripción

function openssl_password_hash(string `$algo`, string `$password`, array `$options` = []): string

Crea un hash de contraseña usando la implementación de Argon2 de OpenSSL. Es una alternativa a password_hash() que utiliza OpenSSL como backend, lo que puede ofrecer aceleración por hardware en algunas plataformas.

Esta función solo está disponible cuando PHP se compila con soporte de OpenSSL que incluye Argon2 (`HAVE_OPENSSL_ARGON2`).

### Parámetros

`algo`

  El algoritmo de hash de contraseña. Valores soportados: `"argon2id"` y `"argon2i"`.

`password`

  La contraseña del usuario.

`options`

  Un array asociativo de opciones. Claves soportadas:

  - `memory_cost` - Memoria máxima (en KiB) que puede utilizarse para calcular el hash
  - `time_cost` - Tiempo máximo que puede tomar calcular el hash
  - `threads` - Número de hilos a utilizar para calcular el hash

### Valores devueltos

Devuelve el hash de la contraseña como una string.

### Errores/Excepciones

Lanza un ValueError si `algo` no es uno de los valores soportados (`"argon2i"` o `"argon2id"`).

Lanza un Error si la operación de hashing falla por una razón desconocida.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Se ha añadido la función.

### Ejemplos

Ejemplo #1 Ejemplo con openssl_password_hash()

    <?php
    $hash = openssl_password_hash('argon2id', 'my-secret-password');
    echo $hash;
    ?>

Resultado del ejemplo anterior es similar a:

    $argon2id$v=19$m=65536,t=4,p=1$c29tZXNhbHR2YWx1ZQ$hashvalue...

Ejemplo #2 openssl_password_hash() con opciones personalizadas

    <?php
    $hash = openssl_password_hash('argon2id', 'my-secret-password', [
        'memory_cost' => 65536,
        'time_cost'   => 4,
        'threads'     => 1,
    ]);
    ?>

### Ver también

- openssl_password_verify() - Verifica una contraseña frente a un hash usando la implementación de Argon2 de OpenSSL
- password_hash() - Crea una clave de hash para una contraseña

# openssl_password_verify

(PHP 8 >= 8.4.0)

openssl_password_verify — Verifica una contraseña frente a un hash usando la implementación de Argon2 de OpenSSL

### Descripción

function openssl_password_verify(string `$algo`, string `$password`, string `$hash`): bool

Verifica que una contraseña coincida con un hash creado por openssl_password_hash().

Esta función solo está disponible cuando PHP se compila con soporte de OpenSSL que incluye Argon2 (`HAVE_OPENSSL_ARGON2`).

### Parámetros

`algo`

  El algoritmo de hash de contraseña. Valores soportados: `"argon2id"` y `"argon2i"`.

`password`

  La contraseña del usuario.

`hash`

  Un hash creado por openssl_password_hash().

### Valores devueltos

Devuelve `true` si la contraseña y el hash coinciden, `false` en caso contrario.

### Errores/Excepciones

Lanza un ValueError si `algo` no es uno de los valores soportados (`"argon2i"` o `"argon2id"`).

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Se ha añadido la función.

### Ejemplos

Ejemplo #1 Ejemplo con openssl_password_verify()

    <?php
    $hash = openssl_password_hash('argon2id', 'my-secret-password');

    if (openssl_password_verify('argon2id', 'my-secret-password', $hash)) {
        echo 'La contraseña coincide.';
    } else {
        echo 'La contraseña no coincide.';
    }
    ?>

### Ver también

- openssl_password_hash() - Crea un hash de contraseña usando la implementación de Argon2 de OpenSSL
- password_verify() - Verifica que una contraseña coincide con un hash

# openssl_pbkdf2

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

openssl_pbkdf2 — Genera una cadena PKCS5 v2 PBKDF2

### Descripción

function openssl_pbkdf2(
#[\SensitiveParameter]string `$password`,
string `$salt`,
int `$key_length`,
int `$iterations`,
string `$digest_algo` = "sha1"
): string|false

openssl_pbkdf2() calcula PBKDF2 (Password-Based Key Derivation Function 2), una función de derivación de clave definida en PKCS5 v2.

### Parámetros

`password`

  Contraseña desde la cual se genera la clave derivada.

`salt`
  PBKDF2 recomienda un sal criptográfico de al menos 128 bits (16 octetos).
`key_length`

  Longitud deseada de la clave de salida.

`iterations`

  El número de iteraciones deseado. » El NIST recomienda al menos 1 000. A partir de 2023, el OWASP recomienda 600 000 iteraciones para PBKDF2-HMAC-SHA256 y 210 000 para PBKDF2-HMAC-SHA512.

`digest_algo`

  Algoritmo de hash o digest opcional a partir de openssl_get_md_methods(). Por omisión SHA-1. Se recomienda definirlo en SHA-256 o SHA-512.

### Valores devueltos

Devuelve una cadena binaria sin tratar o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con openssl_pbkdf2()

    <?php
    $password = 'password';
    $salt = openssl_random_pseudo_bytes(16);
    $keyLength = 20;
    $iterations = 600000;
    $generated_key = openssl_pbkdf2($password, $salt, $keyLength, $iterations, 'sha256');
    echo bin2hex($generated_key)."\n";
    echo base64_encode($generated_key)."\n";
    ?>

### Ver también

- hash_pbkdf2() - Genera una clave PBKDF2 derivada de la contraseña proporcionada
- openssl_get_md_methods() - Obtiene la lista de métodos digest disponibles

# openssl_pkcs12_export

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_export — Exporta un certificado compatible PKCS#12 a una variable

### Descripción

function openssl_pkcs12_export(
OpenSSLCertificate|string `$certificate`,
string `&$output`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
#[\SensitiveParameter]string `$passphrase`,
array `$options` = []
): bool

openssl_pkcs12_export() almacena un certificado `certificate` en una cadena denominada `output` en un formato PKCS#12.

### Parámetros

`x509`
  Ver los parámetros clave/Certificados para una lista de valores válidos.
`output`

  En caso de éxito, esta variable contendrá el PKCS#12.

`private_key`

  Clave privada del archivo PKCS#12. Consulte Parámetros de claves pública/privada para obtener la lista de valores válidos.

`passphrase`

  Contraseña de cifrado para desbloquear el archivo PKCS#12.

`options`

  Array opcional, las otras claves serán ignoradas.

  Clave | Descripción
  --- | ---
  `"extracerts"` | Array de certificados adicionales o de un certificado único a incluir en el archivo PKCS#12.
  `"friendly_name"` | cadena a utilizar para el certificado y la clave proporcionados

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `certificate` ahora acepta una instancia de OpenSSLCertificate ; anteriormente, se aceptaba un resource de tipo `OpenSSL X.509 CSR`.
8.0.0 | `private_key` ahora acepta una instancia de OpenSSLAsymmetricKey o OpenSSLCertificate ; anteriormente, se aceptaba un resource de tipo `OpenSSL key` o `OpenSSL X.509`.

# openssl_pkcs12_export_to_file

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_export_to_file — Exporta un certificado compatible con PKCS#12

### Descripción

function openssl_pkcs12_export_to_file(
OpenSSLCertificate|string `$certificate`,
string `$output_filename`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
#[\SensitiveParameter]string `$passphrase`,
array `$options` = []
): bool

openssl_pkcs12_export_to_file() almacena un certificado `certificate` en un fichero denominado `output_filename` en un formato de fichero PKCS#12.

### Parámetros

`x509`
  Ver los parámetros clave/Certificados para una lista de valores válidos.
`output_filename`

  Ruta de acceso al fichero de salida.

`private_key`

  Clave privada del fichero PKCS#12. Ver parámetros Clave/Certificado para una lista de valores válidos.

`passphrase`

  Contraseña de cifrado para desbloquear el fichero PKCS#12.

`options`

  Array opcional, las demás claves serán ignoradas.

  Clave | Descripción
  --- | ---
  `"extracerts"` | array de certificados adicionales o un certificado único a incluir en el fichero PKCS#12.
  `"friendly_name"` | string a utilizar para el certificado y la clave proporcionados

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `certificate` ahora acepta una instancia de OpenSSLCertificate ; anteriormente, se aceptaba un resource de tipo `OpenSSL X.509 CSR`.
8.0.0 | `private_key` ahora acepta una instancia de OpenSSLAsymmetricKey o OpenSSLCertificate ; anteriormente, se aceptaba un resource de tipo `OpenSSL key` o `OpenSSL X.509`.

# openssl_pkcs12_read

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_read — Lee un certificado PKCS#12 en un array

### Descripción

function openssl_pkcs12_read(string `$pkcs12`, array `&$certificates`, #[\SensitiveParameter]string `$passphrase`): bool

openssl_pkcs12_read() lee el certificado PKCS#12 proporcionado por el argumento `pkcs12` en un array denominado `certificates`.

### Parámetros

`pkcs12`

  El contenido del almacén de certificados, no el nombre del fichero.

`certificates`

  En caso de éxito, este array contendrá los datos del certificado.

`passphrase`

  Frase de contraseña para desencriptar el archivo PKCS#12.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 openssl_pkcs12_read() example

    <?php
    if (!$cert_store = file_get_contents("/certs/file.p12")) {
        echo "Error: No se pudo leer el fichero de certificado\n";
        exit;
    }

    if (openssl_pkcs12_read($cert_store, $cert_info, "my_secret_pass")) {
        echo "Información del Certificado\n";
        print_r($cert_info);
    } else {
        echo "Error: No se pudo leer el almacén de certificados.\n";
        exit;
    }
    ?>

# openssl_pkcs7_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_decrypt — Descifra un mensaje S/MIME

### Descripción

function openssl_pkcs7_decrypt(
string `$input_filename`,
string `$output_filename`,
#[\SensitiveParameter]OpenSSLCertificate|string `$certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string|null `$private_key` = `null`
): bool

Descifra el mensaje S/MIME contenido en el fichero `input_filename`, utilizando el certificado y la clave privada asociados por `certificate` y `private_key`.

### Parámetros

`input_filename`

`output_filename`

  El mensaje descifrado se escribe en el fichero especificado por este argumento.

`certificate`

`private_key`

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `private_key` acepta ahora una instancia de OpenSSLAsymmetricKey o OpenSSLCertificate; anteriormente, se aceptaba un resource de tipo `OpenSSL key` o `OpenSSL X.509 CSR`.

### Ejemplos

Ejemplo #1 Ejemplo con openssl_pkcs7_decrypt()

    <?php
    // $cert y $key contienen sus certificados y claves privadas
    // Se asume que el mensaje está dirigido a usted
    $infilename = "encrypted.msg";  // este fichero contiene su mensaje cifrado
    $outfilename = "decrypted.msg"; // asegúrese de poder escribir en este fichero

    if (openssl_pkcs7_decrypt($infilename, $outfilename, $cert, $key)) {
        echo "descifrado !";
    } else {
        echo "Error al descifrar !";
    }
    ?>

# openssl_pkcs7_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_encrypt — Cifra un mensaje S/MIME

### Descripción

function openssl_pkcs7_encrypt(
string `$input_filename`,
string `$output_filename`,
OpenSSLCertificate|array|string `$certificate`,
?array `$headers`,
int `$flags` = 0,
int `$cipher_algo` = `OPENSSL_CIPHER_AES_128_CBC`
): bool

openssl_pkcs7_encrypt() toma el contenido del fichero `input_filename` y lo cifra utilizando un cifrado RC2 de 40 bits, de manera que el mensaje solo pueda ser leído por el poseedor de `certificate`.

### Parámetros

`input_filename`

`output_filename`

`certificate`

  Puede ser un certificado X.509 o un array de certificados X.509.

`headers`

  `headers` es un array de encabezados que serán añadidos al inicio del mensaje, una vez que los datos hayan sido cifrados.

  `headers` puede ser un array asociativo, donde las claves son los nombres de los encabezados, o bien un array indexado donde cada línea contiene un encabezado completo.

`flags`

  `flags` puede ser utilizado para especificar opciones que afectarán al cifrado (ver las constantes PKCS7).

`cipher_algo`

  Una de las constantes cipher.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El algoritmo de cifrado por omisión (`cipher_algo`) es ahora AES-128-CBC (`OPENSSL_CIPHER_AES_128_CBC`). Anteriormente, se utilizaba PKCS7/CMS (`OPENSSL_CIPHER_RC2_40`).
8.0.0 | `certificate` acepta ahora una instancia de OpenSSLCertificate; anteriormente, se aceptaba un resource de tipo `OpenSSL X.509 CSR`.

### Ejemplos

Ejemplo #1 Ejemplo con openssl_pkcs7_encrypt()

    <?php
    // el mensaje que se desea cifrar y enviar a su agente secreto
    // en misión, llamado "nighthawk". Tiene su certificado
    // en el fichero "nighthawk.pem"
    $data = <<<EOD
    Nighthawk,

    Top secret, solo para sus ojos !

    El enemigo se acerca! Reúnase en el café a las 8:30,
    para su pasaporte falso.

    HQ
    EOD;

    // Carga de la clave
    $key = file_get_contents("nighthawk.pem");

    // Guardado del mensaje en un fichero
    $fp = fopen("msg.txt", "w");
    fwrite($fp, $data);
    fclose($fp);

    // Cifrado del mensaje
    if (openssl_pkcs7_encrypt("msg.txt", "enc.txt", $key,
        array("To" => "nighthawk@example.com", // sintaxis en forma de clave
              "From: HQ <hq@example.com>", // sintaxis en forma de índice
              "Subject" => "Solo para sus ojos !"))) {
        // mensaje cifrado - envíelo !
        exec(ini_get("sendmail_path") . " < enc.txt");
    }
    ?>

# openssl_pkcs7_read

(PHP 7 >= 7.2.0, PHP 8)

openssl_pkcs7_read — Exporta el fichero PKCS7 a un array de certificados PEM

### Descripción

function openssl_pkcs7_read(string `$data`, array `&$certificates`): bool

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`data`

  El string de datos que debe ser analizado (en formato p7b).

`certificates`

  Un array de certificados PEM desde los datos de entrada p7b.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Obtener un array PEM desde un fichero P7B

    <?php

    $file = 'certs.p7b';

    $f = file_get_contents($file);
    $p7 = array();
    $r = openssl_pkcs7_read($f, $p7);

    if ($r === false) {
        printf("ERROR: %s no es un fichero p7b válido".PHP_EOL, $file);
            for($e = openssl_error_string(), $i = 0; $e; $e = openssl_error_string(), $i++)
                printf("SSL l%d: %s".PHP_EOL, $i, $e);
        exit(1);
    }

    print_r($p7);
    ?>

### Ver también

- openssl_csr_sign() - Firma un CSR con otro certificado (o consigo mismo) y genera un certificado

# openssl_pkcs7_sign

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_sign — Firma un mensaje S/MIME

### Descripción

function openssl_pkcs7_sign(
string `$input_filename`,
string `$output_filename`,
OpenSSLCertificate|string `$certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
?array `$headers`,
int `$flags` = `PKCS7_DETACHED`,
?string `$untrusted_certificates_filename` = `null`
): bool

openssl_pkcs7_sign() toma el contenido del fichero `input_filename` y lo firma utilizando el certificado y la clave privada contenidos en los argumentos `certificate` y `private_key`.

### Parámetros

`input_filename`

  El fichero de entrada que se tiene la intención de firmar digitalmente.

`output_filename`

  El fichero donde se escribirá la firma digital.

`certificate`

  El certificado X.509 utilizado para firmar digitalmente `input_filename`. Ver parámetros Clave/Certificado para una lista de valores válidos.

`private_key`

  `private_key` es la clave privada correspondiente a `certificate`. Ver parámetros Clave Pública/Privada para una lista de valores válidos.

`headers`

  `headers` es un array de encabezados que serán añadidos a los datos cifrados (ver la función openssl_pkcs7_encrypt() para más detalles sobre el formato del parámetro).

`flags`

  `flags` puede ser utilizado para modificar la salida. Ver las constantes PKCS7.

`untrusted_certificates_filename`

  `untrusted_certificates_filename` especifica el nombre del fichero que contiene un conjunto de certificados adicionales a incluir en la firma, los cuales podrán ayudar al destinatario a verificar los datos que se utilizan.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `certificate` ahora acepta una instancia de OpenSSLCertificate ; anteriormente, se aceptaba un resource de tipo `OpenSSL X.509 CSR`.
8.0.0 | `private_key` ahora acepta una instancia de OpenSSLAsymmetricKey o OpenSSLCertificate ; anteriormente, se aceptaba un resource de tipo `OpenSSL key` o `OpenSSL X.509`.

### Ejemplos

Ejemplo #1 Ejemplo con openssl_pkcs7_sign()

    <?php
    // el mensaje que se quiere firmar, para que el destinatario esté seguro de que
    // proviene de usted
    $data = <<<EOD

    Usted está autorizado a gastar 10 000€ en gastos de viaje.

    El PDG
    EOD;
    // guardar el mensaje en un fichero
    $fp = fopen("msg.txt", "w");
    fwrite($fp, $data);
    fclose($fp);
    // cifrarlo
    if (openssl_pkcs7_sign("msg.txt", "signed.txt", "file://mycert.pem",
        array("file://mycert.pem", "mypassphrase"),
        array("To" => "joes@example.com", // sintaxis con clave
              "From: HQ <ceo@example.com>", // sintaxis indexada
              "Subject" => "Eyes only")
        )) {
        // mensaje firmado - ¡envíelo!
        exec(ini_get("sendmail_path") . " < signed.txt");
    }
    ?>

# openssl_pkcs7_verify

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_verify — Verifica la firma de un mensaje S/MIME

### Descripción

function openssl_pkcs7_verify(
string `$input_filename`,
int `$flags`,
?string `$signers_certificates_filename` = `null`,
array `$ca_info` = [],
?string `$untrusted_certificates_filename` = `null`,
?string `$content` = `null`,
?string `$output_filename` = `null`
): bool|int

openssl_pkcs7_verify() lee el mensaje S/MIME contenido en el fichero `filename` y examina la firma digital.

### Parámetros

`input_filename`

  Ruta hacia el mensaje.

`flags`

  `flags` sirve para modificar la forma en que se verifica la firma. Consulte las constantes PKCS7. Por omisión, el valor es: PKCS7_DETACHED.

`signers_certificates_filename`

  Si el parámetro `signers_certificates_filename` es especificado, debe ser una cadena que contenga el nombre de un fichero que contiene el certificado del firmante, en formato PEM.

`ca_info`

  Si el parámetro `ca_info` es especificado, debe contener la información sobre los certificados de confianza de terceros utilizados durante la verificación. Consulte verificación de certificados para más detalles.

`untrusted_certificates_filename`

  Si el parámetro `untrusted_certificates_filename` es especificado, debe representar el nombre de un fichero que contiene un conjunto de certificados utilizados como certificados de poca confianza.

`content`

  Puede especificarse un nombre de fichero con el parámetro `content` que puede ser rellenado con los datos verificados, pero sin las informaciones de firma.

`output_filename`

### Valores devueltos

Devuelve `true` si la firma es verificada, y `false` en caso contrario (el mensaje ha sido modificado, o bien el certificado de firma es inválido) o -1 si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `signers_certificates_filename`, `untrusted_certificates_filename`, `content` y `output_filename` ahora son nullable.
7.2.0 | Se ha añadido el parámetro `output_filename`.

### Notas

> Nota: Tal como se especifica en la RFC 2045, las líneas no deben ser más largas que 76 caracteres en el parámetro `input_filename`.

# openssl_pkey_derive

(PHP 7 >= 7.3.0, PHP 8)

openssl_pkey_derive — Calcula el secreto compartido para el valor público de la clave DH o ECDH remota y local

### Descripción

function openssl_pkey_derive(OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`, #[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`, int `$key_length` = 0): string|false

openssl_pkey_derive() toma un conjunto de `public_key` y `private_key` y deriva un secreto compartido, para claves DH o EC.

### Parámetros

`public_key`

  `public_key` es la clave pública para la derivación. Consulte Parámetros de clave/certificado para una lista de valores válidos.

`private_key`

  `private_key` es la clave privada para la derivación. Consulte Parámetros de clave pública/privada para una lista de valores válidos.

`key_length`

  Si no es nulo, intentará establecer la longitud deseada del secreto derivado.

  Precaución

  Este parámetro está obsoleto y no debe utilizarse, ya que no funciona como se espera. Nunca devuelve un secreto más largo que el tamaño del primero Si la longitud deseada es menor que el tamaño del primero, trunca la longitud solo para las claves ECDH, pero falla para las claves DH.

### Valores devueltos

El secreto derivado en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | El parámetro `key_length` ahora está obsoleto.

### Ejemplos

Ejemplo #1 Ejemplo de openssl_pkey_derive()

    <?php
    // Carga la clave privada
    $priv = openssl_pkey_get_private("-----BEGIN PRIVATE KEY-----
    MIICJgIBADCCARcGCSqGSIb3DQEDATCCAQgCggEBAJLxRCaZ933uW+AXmabHFDDy
    upojBIRlbmQLJZfigDaSA1f9YOTsIv+WwVFTX/J1mtCyx9uBcz0Nt2kmVwxWuc2f
    VtCEMPsmLsVXX7xRUFLpyX1Y1IYGBVXQOoOvLWYQjpZgnx47Pkh1Ok1+smffztfC
    0DCNt4KorWrbsPcmqBejXHN79KvWFjZmXOksRiNu/Bn76RiqvofC4z8Ri3kHXQG2
    197JGZzzFXHadGC3xbkg8UxsNbYhVMKbm0iANfafUH7/hoS9UjAVQYtvwe7YNiW/
    HnyfVCrKwcc7sadd8Iphh+3lf5P1AhaQEAMytanrzq9RDXKBxuvpSJifRYasZYsC
    AQIEggEEAoIBAGwAYC2E81Y1U2Aox0U7u1+vBcbht/OO87tutMvc4NTLf6NLPHsW
    cPqBixs+3rSn4fADzAIvdLBmogjtiIZoB6qyHrllF/2xwTVGEeYaZIupQH3bMK2b
    6eUvnpuu4Ytksiz6VpXBBRMrIsj3frM+zUtnq8vKUr+TbjV2qyKR8l3eNDwzqz30
    dlbKh9kIhZafclHfRVfyp+fVSKPfgrRAcLUgAbsVjOjPeJ90xQ4DTMZ6vjiv6tHM
    hkSjJIcGhRtSBzVF/cT38GyCeTmiIA/dRz2d70lWrqDQCdp9ArijgnpjNKAAulSY
    CirnMsGZTDGmLOHg4xOZ5FEAzZI2sFNLlcw=
    -----END PRIVATE KEY-----
    ");

    // Carga la clave pública
    $pub = openssl_pkey_get_public("-----BEGIN PUBLIC KEY-----
    MIICJDCCARcGCSqGSIb3DQEDATCCAQgCggEBAJLxRCaZ933uW+AXmabHFDDyupoj
    BIRlbmQLJZfigDaSA1f9YOTsIv+WwVFTX/J1mtCyx9uBcz0Nt2kmVwxWuc2fVtCE
    MPsmLsVXX7xRUFLpyX1Y1IYGBVXQOoOvLWYQjpZgnx47Pkh1Ok1+smffztfC0DCN
    t4KorWrbsPcmqBejXHN79KvWFjZmXOksRiNu/Bn76RiqvofC4z8Ri3kHXQG2197J
    GZzzFXHadGC3xbkg8UxsNbYhVMKbm0iANfafUH7/hoS9UjAVQYtvwe7YNiW/Hnyf
    VCrKwcc7sadd8Iphh+3lf5P1AhaQEAMytanrzq9RDXKBxuvpSJifRYasZYsCAQID
    ggEFAAKCAQAiCSBpxvGgsTorxAWtcAlSmzAJnJxFgSPef0g7OjhESytnc8G2QYmx
    ovMt5KVergcitztWh08hZQUdAYm4rI+zMlAFDdN8LWwBT/mGKSzRkWeprd8E7mvy
    ucqC1YXCMqmIwPySvLQUB/Dl8kgau7BLAnIJm8VP+MVrn8g9gghD0qRCgPgtEaDV
    vocfgnOU43rhKnIgO0cHOKtw2qybSFB8QuZrYugq4j8Bwkrzh6rdMMeyMl/ej5Aj
    c0wamOzuBDtXt0T9+Fx3khHaowjCc7xJZRgZCxg43SbqMWJ9lUg94I7+LTX61Gyv
    dtlkbGbtoDOnxeNnN93gwQZngGYZYciu
    -----END PUBLIC KEY-----
    ");

    // Salida de la versión hexadecimal de la clave derivada
    echo bin2hex(openssl_pkey_derive($pub,$priv));

# openssl_pkey_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_export — Almacena una representación exportable de la clave en una cadena de caracteres

### Descripción

function openssl_pkey_export(
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$key`,
string `&$output`,
#[\SensitiveParameter]?string `$passphrase` = `null`,
?array `$options` = `null`
): bool

openssl_pkey_export() exporta la clave `key` en formato de cadena PEM, y la almacena en la variable `output` (que se pasa por referencia).

> Nota: Debe existir un archivo openssl.cnf válido e instalado para que esta función opere correctamente. Ver las notas encontradas en la sección concerniente a la instalación para más información.

### Parámetros

`key`

`output`

`passphrase`

  La clave puede estar protegida por la contraseña `passphrase`.

`options`

  `options` puede ser utilizado para ajustar el proceso de exportación especificando o reemplazando las opciones del archivo de configuración de OpenSSL. Consulte openssl_csr_new() para más información sobre `options`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `key` ahora acepta una instancia de OpenSSLAsymmetricKey o OpenSSLCertificate ; anteriormente, se aceptaba un resource de tipo `OpenSSL key` o `OpenSSL X.509`.

# openssl_pkey_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_export_to_file — Guarda una clave en formato ASCII en un fichero

### Descripción

function openssl_pkey_export_to_file(
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$key`,
string `$output_filename`,
#[\SensitiveParameter]?string `$passphrase` = `null`,
?array `$options` = `null`
): bool

openssl_pkey_export_to_file() guarda la clave en formato ASCII (PEM) `key` en el fichero `output_filename`.

> Nota: Debe existir un archivo openssl.cnf válido e instalado para que esta función opere correctamente. Ver las notas encontradas en la sección concerniente a la instalación para más información.

### Parámetros

`key`

`output_filename`

  Ruta del fichero de salida.

`passphrase`

  La clave puede estar eventualmente protegida por una `frase de contraseña`.

`options`

  `options` puede ser utilizado para ajustar el proceso de exportación especificando o reemplazando las opciones del archivo de configuración de OpenSSL. Véase openssl_csr_new() para más información sobre `options`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `key` acepta ahora una instancia de OpenSSLAsymmetricKey o OpenSSLCertificate; anteriormente, se aceptaba un resource de tipo `OpenSSL key` o `OpenSSL X.509`.

# openssl_pkey_free

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_free — Libera una clave privada

Advertencia

Esta función está OBSOLETA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function openssl_pkey_free(OpenSSLAsymmetricKey `$key`): void

> Nota: Esta función no tiene ningún efecto. Anterior a PHP 8.0.0, esta función era utilizada para cerrar un recurso.

Libera una clave privada creada por la función openssl_pkey_new().

### Parámetros

`key`

  Recurso que representa la clave.

### Valores devueltos

No se retorna ningún valor.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función es ahora obsoleta ya que no tiene ningún efecto.
8.0.0 | `key` acepta ahora una instancia de OpenSSLAsymmetricKey; anteriormente, se aceptaba un resource de tipo `OpenSSL key`.

# openssl_pkey_get_details

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_pkey_get_details — Devuelve un array que contiene los detalles de la clave

### Descripción

function openssl_pkey_get_details(OpenSSLAsymmetricKey `$key`): array|false

Esta función devuelve los detalles de la clave (bits, key, type).

### Parámetros

`key`

  Recurso que contiene la clave.

### Valores devueltos

Devuelve un array con los detalles de la clave en caso de éxito, o `false` en caso de fallo. El array devuelto contiene los índices `bits` (número de bits), `key` (representación en forma de string de la clave pública) y `type` (tipo de clave que es uno de `OPENSSL_KEYTYPE_RSA`, `OPENSSL_KEYTYPE_DSA`, `OPENSSL_KEYTYPE_DH`, `OPENSSL_KEYTYPE_EC`, `OPENSSL_KEYTYPE_X25519`, `OPENSSL_KEYTYPE_ED25519`, `OPENSSL_KEYTYPE_X448`, `OPENSSL_KEYTYPE_ED448`, o `-1` significando desconocido).

Dependiendo del tipo de claves utilizadas, pueden devolverse detalles adicionales. Tenga en cuenta que algunos elementos pueden no estar siempre disponibles.

- `OPENSSL_KEYTYPE_RSA`, se devuelve una clave de array adicional llamada `"rsa"`, que contiene los datos de la clave.

  Clave | Descripción
  --- | ---
  `"n"` | módulo
  `"e"` | exponente público
  `"d"` | exponente privado
  `"p"` | número primo 1
  `"q"` | número primo 2
  `"dmp1"` | exponent1, d mod (p-1)
  `"dmq1"` | exponent2, d mod (q-1)
  `"iqmp"` | coeficiente, (inverso de q) mod p

- `OPENSSL_KEYTYPE_DSA`, se devuelve una clave de array adicional llamada `"dsa"`, que contiene los datos de la clave.

  Clave | Descripción
  --- | ---
  `"p"` | número primo (público)
  `"q"` | 160-bit número sub-prime, q | p-1 (público)
  `"g"` | generador del subgrupo (público)
  `"priv_key"` | clave privada x
  `"pub_key"` | clave pública y = g^x

- `OPENSSL_KEYTYPE_DH`, se devuelve una clave de array adicional llamada `"dh"`, que contiene los datos de la clave.

  Clave | Descripción
  --- | ---
  `"p"` | número primo (compartido)
  `"g"` | generador de Z_p (compartido)
  `"priv_key"` | valor privado DH x
  `"pub_key"` | valor público DH g^x

- `OPENSSL_KEYTYPE_X25519`, `OPENSSL_KEYTYPE_ED25519`, `OPENSSL_KEYTYPE_X448`, o `OPENSSL_KEYTYPE_ED448`, se devuelve una clave adicional en el array llamada `"x25519"`, `"ed25519"`, `"x448"`, o `"ed448"` respectivamente, que contiene los datos de la clave.

  Clave | Descripción
  --- | ---
  `"priv_key"` | clave privada
  `"pub_key"` | clave pública

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Se añadió el soporte para claves basadas en Curve25519 y Curve448. Más específicamente, se introdujeron los campos `x25519`, `ed25519`, `x448` y `ed448`.
8.0.0 | `key` ahora acepta una instancia de OpenSSLAsymmetricKey; anteriormente, se aceptaba un resource de tipo `OpenSSL key`.

# openssl_pkey_get_private

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_get_private — Lee una clave privada

### Descripción

function openssl_pkey_get_private(#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`, #[\SensitiveParameter]?string `$passphrase` = `null`): OpenSSLAsymmetricKey|false

openssl_pkey_get_private() analiza la clave `private_key` y la prepara para ser utilizada por otras funciones.

### Parámetros

`private_key`

  `private_key` puede ser uno de los siguientes valores:

  1. una cadena en el formato file://path/to/file.pem. El fichero así designado debe contener una clave privada o un certificado en formato PEM (eventualmente ambos).
  2. Una clave privada en formato PEM.
`passphrase`

  El parámetro opcional `passphrase` debe ser utilizado si la clave especificada está cifrada (protegida por una contraseña).

### Valores devueltos

Devuelve una instancia de OpenSSLAsymmetricKey en caso de éxito, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de OpenSSLAsymmetricKey; anteriormente se devolvía un resource de tipo `OpenSSL key`.
8.0.0 | `private_key` acepta ahora una instancia de OpenSSLAsymmetricKey o OpenSSLCertificate; anteriormente se aceptaba un resource de tipo `OpenSSL key` o `OpenSSL X.509`.
8.0.0 | `passphrase` es ahora nullable.

# openssl_pkey_get_public

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_get_public — Extrae una clave pública de un certificado y la prepara

### Descripción

function openssl_pkey_get_public(OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`): OpenSSLAsymmetricKey|false

openssl_pkey_get_public() extrae la clave pública del certificado `public_key` y la prepara para ser utilizada por otras funciones.

### Parámetros

`public_key`

  `public_key` puede tener uno de los siguientes valores:

  1. Una instancia de OpenSSLAsymmetricKey.
  2. Una cadena en el formato file://path/to/file.pem. El fichero designado debe contener una clave pública o un certificado en formato PEM (eventualmente ambos).
  3. Una clave pública en formato PEM.

### Valores devueltos

Devuelve una instancia de OpenSSLAsymmetricKey en caso de éxito, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de OpenSSLAsymmetricKey; anteriormente se devolvía un resource de tipo `OpenSSL key`.
8.0.0 | `public_key` acepta ahora una instancia de OpenSSLAsymmetricKey o OpenSSLCertificate; anteriormente se aceptaba un resource de tipo `OpenSSL key` o `OpenSSL X.509`.

# openssl_pkey_new

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_new — Genera una nueva clave privada

### Descripción

function openssl_pkey_new(?array `$options` = `null`): OpenSSLAsymmetricKey|false

openssl_pkey_new() genera una nueva clave privada. Cómo obtener el componente público de la clave se demuestra en un ejemplo a continuación.

> Nota: Debe existir un archivo openssl.cnf válido e instalado para que esta función opere correctamente. Ver las notas encontradas en la sección concerniente a la instalación para más información.

### Parámetros

`options`

  Es posible afinar la generación de claves (por ejemplo, especificando el número de bits o los parámetros) mediante el argumento `options`. Estas opciones pueden ser parámetros específicos del algoritmo utilizados para la generación de claves, u opciones genéricas también utilizadas para la generación de CSR si no se especifican. Consulte openssl_csr_new() para obtener más información sobre el uso de `options` para un CSR. Entre estas opciones, solo `private_key_bits`, `private_key_type`, `curve_name`, y `config` se utilizan para la generación de claves. Las opciones específicas de un algoritmo se utilizan si el array asociativo incluye una de las claves específicas.

  - Clave `"rsa"` para definir los parámetros RSA.

    options | type | format | requis | description
    --- | --- | --- | --- | ---
    `"n"` | string | número binario | sí | módulo
    `"e"` | string | número binario | no | exponente público
    `"d"` | string | número binario | sí | exponente privado
    `"p"` | string | número binario | no | primer 1
    `"q"` | string | número binario | no | primer 2
    `"dmp1"` | string | número binario | no | exponent1, d mod (p-1)
    `"dmq1"` | string | número binario | no | exponent2, d mod (q-1)
    `"iqmp"` | string | número binario | no | coeficiente, (inverso de q) mod p

  - Clave `"dsa"` para definir los parámetros DSA.

    options | type | format | requis | description
    --- | --- | --- | --- | ---
    `"p"` | string | número binario | no | número primo (público)
    `"q"` | string | número binario | no | 160 bits sub-prime, q | p-1 (público)
    `"g"` | string | número binario | no | generador del subgrupo (público)
    `"priv_key"` | string | clave PEM | no | clave privada x
    `"pub_key"` | string | clave PEM | no | clave pública y = g^x

  - Clave `"dh"` para los parámetros DH (intercambio de claves Diffie–Hellman).

    Options | Tipo | Format | Requis | Descripción
    --- | --- | --- | --- | ---
    `"p"` | string | número binario | no | número primo (compartido)
    `"g"` | string | número binario | no | generador de Z_p (compartido)
    `"priv_key"` | string | clave PEM | no | valor DH privado x
    `"pub_key"` | string | clave PEM | no | valor DH público g^x

  - Clave `"ec"` para los parámetros de curva elíptica

    Options | Tipo | Format | Requis | Descripción
    --- | --- | --- | --- | ---
    `"curve_name"` | string | nombre | no | nombre de la curva, ver openssl_get_curve_names()
    `"p"` | string | número binario | no | número primo del campo para la curva sobre Fp
    `"a"` | string | número binario | no | coeficiente a de la curva para Fp : y^2 mod p = x^3 + ax + b mod p
    `"b"` | string | número binario | no | coeficiente b de la curva para Fp : y^2 mod p = x^3 + ax + b mod p
    `"seed"` | string | número binario | no | número aleatorio opcional utilizado para generar el coeficiente b
    `"generator"` | string | punto codificado en binario | no | punto generador de la curva
    `"g_x"` | string | número binario | no | coordenada x del punto generador de la curva
    `"g_y"` | string | número binario | no | coordenada y del punto generador de la curva
    `"cofactor"` | string | número binario | no | cofactor de la curva
    `"order"` | string | número binario | no | orden de la curva
    `"x"` | string | número binario | no | coordenada x (pública)
    `"y"` | string | número binario | no | coordenada y (pública)
    `"d"` | string | número binario | no | clave privada

  - Claves `"x25519"`, `"x448"`, `"ed25519"`, `"ed448"` para los parámetros Curve25519 y Curve448.

    Options | Tipo | Format | Requis | Descripción
    --- | --- | --- | --- | ---
    `"priv_key"` | string | clave PEM | no | clave privada
    `"pub_key"` | string | clave PEM | no | clave pública

### Valores devueltos

Devuelve una instancia de OpenSSLAsymmetricKey en caso de éxito, `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Se añadió el soporte para claves basadas en Curve25519 y Curve448 con la introducción de los campos `x25519`, `ed25519`, `x448`, y `ed448`.
8.3.0 | Se añadió el soporte para la generación de claves EC con parámetros EC personalizados. Más específicamente, con la introducción de las opciones EC: `p`, `a`, `b`, `seed`, `generator`, `g_x`, `g_y`, `cofactor`, y `order`.
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de OpenSSLAsymmetricKey; anteriormente, se devolvía un resource de tipo `OpenSSL key`.
7.1.0 | Se añadió la opción `curve_name` para permitir la creación de claves EC.

### Ejemplos

Ejemplo #1 Obtener la clave pública a partir de una clave privada

    <?php

    $private_key = openssl_pkey_new();
    $public_key_pem = openssl_pkey_get_details($private_key)['key'];
    echo $public_key_pem, PHP_EOL;

    $public_key = openssl_pkey_get_public($public_key_pem);
    var_dump($public_key);

    ?>

Resultado del ejemplo anterior es similar a:

    // Resultado antes de PHP 8.0.0; note que la función devuelve un recurso
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwknBFEherZe74BiRjTFA
    hqwZ1SK7brwq7C/afnLXKhRR7jnrpfM0ypC46q8xz5UZswenZakJ7kd5fls+r4Bv
    3P8XsKYLTh2m1GiWQhV1g77cNIN4qNWh70PiDO3fB2446o1LBgToQYuRZS5YQRfJ
    rVD0ysgtVcCU9tjaey28HlgApOpYFTaaKPj2MBmEYpMC+kG2HhL12GfpHUi2eiXI
    dXT2WskWHWvUrmQ7fJIfI92JlDokV62DH/q1oiedLs9OPNb0rL1aAmYdzaVN6XNH
    x/o4Lh125v2vAPV9E3fZCDc/HDEUaahpjanMiCQEgEDp5Hr+CRkvERT5/ydN+p08
    5wIDAQAB
    -----END PUBLIC KEY-----
    resource(6) of type (OpenSSL key)

    // Resultado a partir de PHP 8.0.0; note que la función devuelve un objeto
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwknBFEherZe74BiRjTFA
    hqwZ1SK7brwq7C/afnLXKhRR7jnrpfM0ypC46q8xz5UZswenZakJ7kd5fls+r4Bv
    3P8XsKYLTh2m1GiWQhV1g77cNIN4qNWh70PiDO3fB2446o1LBgToQYuRZS5YQRfJ
    rVD0ysgtVcCU9tjaey28HlgApOpYFTaaKPj2MBmEYpMC+kG2HhL12GfpHUi2eiXI
    dXT2WskWHWvUrmQ7fJIfI92JlDokV62DH/q1oiedLs9OPNb0rL1aAmYdzaVN6XNH
    x/o4Lh125v2vAPV9E3fZCDc/HDEUaahpjanMiCQEgEDp5Hr+CRkvERT5/ydN+p08
    5wIDAQAB
    -----END PUBLIC KEY-----

    object(OpenSSLAsymmetricKey)#2 (0) {
    }

Ejemplo #2 Generación de una clave RSA a partir de parámetros

    <?php

    $nhex = "BBF82F090682CE9C2338AC2B9DA871F7368D07EED41043A440D6B6F07454F51F" .
            "B8DFBAAF035C02AB61EA48CEEB6FCD4876ED520D60E1EC4619719D8A5B8B807F" .
            "AFB8E0A3DFC737723EE6B4B7D93A2584EE6A649D060953748834B2454598394E" .
            "E0AAB12D7B61A51F527A9A41F6C1687FE2537298CA2A8F5946F8E5FD091DBDCB";

    $ehex = "11";
    $dhex = "A5DAFC5341FAF289C4B988DB30C1CDF83F31251E0668B42784813801579641B2" .
            "9410B3C7998D6BC465745E5C392669D6870DA2C082A939E37FDCB82EC93EDAC9" .
            "7FF3AD5950ACCFBC111C76F1A9529444E56AAF68C56C092CD38DC3BEF5D20A93" .
            "9926ED4F74A13EDDFBE1A1CECC4894AF9428C2B7B8883FE4463A4BC85B1CB3C1";

    $phex = "EECFAE81B1B9B3C908810B10A1B5600199EB9F44AEF4FDA493B81A9E3D84F632" .
            "124EF0236E5D1E3B7E28FAE7AA040A2D5B252176459D1F397541BA2A58FB6599";

    $qhex = "C97FB1F027F453F6341233EAAAD1D9353F6C42D08866B1D05A0F2035028B9D86" .
            "9840B41666B42E92EA0DA3B43204B5CFCE3352524D0416A5A441E700AF461503";

    $dphex = "11";
    $dqhex = "11";
    $qinvhex = "b06c4fdabb6301198d265bdbae9423b380f271f73453885093077fcd39e2119f" .
               "c98632154f5883b167a967bf402b4e9e2e0f9656e698ea3666edfb25798039f7";

    $rsa= openssl_pkey_new([
        'rsa' => [
            'n' => hex2bin($nhex),
            'e' => hex2bin($ehex),
            'd' => hex2bin($dhex),
            'p' => hex2bin($phex),
            'q' => hex2bin($qhex),
            'dmp1' => hex2bin($dphex),
            'dmq1' => hex2bin($dqhex),
            'iqmp' => hex2bin($qinvhex),
        ],
    ]);
    $details = openssl_pkey_get_details($rsa);
    var_dump($details);

    ?>

# openssl_private_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_private_decrypt — Descifra datos con una clave privada

### Descripción

function openssl_private_decrypt(
string `$data`,
#[\SensitiveParameter]string `&$decrypted_data`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
int `$padding` = `OPENSSL_PKCS1_PADDING`,
?string `$digest_algo` = `null`
): bool

openssl_private_decrypt() descifra `data` que ha sido cifrada previamente con openssl_public_encrypt(), y almacena el resultado en la variable `decrypted_data`.

Esta función puede ser utilizada, por ejemplo, para descifrar datos que solo deben ser accesibles para el usuario.

### Parámetros

`data`

`decrypted_data`

`private_key`

  `private_key` debe ser la clave privada utilizada para cifrar los datos.

`padding`

  `padding` puede ser `OPENSSL_PKCS1_PADDING`, `OPENSSL_SSLV23_PADDING`, `OPENSSL_PKCS1_OAEP_PADDING` o `OPENSSL_NO_PADDING`.

`digest_algo`
  El algoritmo de resumen para el relleno OAEP, o `null` para utilizar el algoritmo por omisión.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | Se ha añadido el parámetro opcional `digest_algo`.
8.0.0 | `private_key` ahora acepta una instancia de OpenSSLAsymmetricKey o OpenSSLCertificate; anteriormente, se aceptaba un resource de tipo `OpenSSL key` o `OpenSSL X.509`.

### Ver también

- openssl_public_encrypt() - Cifra datos con una clave pública
- openssl_public_decrypt() - Descifra datos con una clave pública

# openssl_private_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_private_encrypt — Cifra datos con una clave privada

### Descripción

function openssl_private_encrypt(
#[\SensitiveParameter]string `$data`,
string `&$encrypted_data`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
int `$padding` = `OPENSSL_PKCS1_PADDING`
): bool

openssl_private_encrypt() cifra los datos `data` con la clave privada `private_key` y almacena el resultado en `encrypted_data`. Los datos cifrados pueden ser descifrados con la función openssl_public_decrypt().

Esta función puede ser utilizada para firmar los datos (o sus cifrados) para demostrar que no han sido escritos por otra persona.

### Parámetros

`data`

`encrypted_data`

`private_key`

  `private_key` debe ser la clave privada correspondiente a la clave pública que será utilizada para descifrar los datos.

`padding`

  El parámetro `padding` puede ser `OPENSSL_PKCS1_PADDING` o `OPENSSL_NO_PADDING`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `private_key` acepta ahora una instancia de OpenSSLAsymmetricKey o OpenSSLCertificate ; anteriormente, se aceptaba un resource de tipo `OpenSSL key` o `OpenSSL X.509`.

### Ver también

- openssl_public_encrypt() - Cifra datos con una clave pública
- openssl_public_decrypt() - Descifra datos con una clave pública

# openssl_public_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_public_decrypt — Descifra datos con una clave pública

### Descripción

function openssl_public_decrypt(
string `$data`,
#[\SensitiveParameter]string `&$decrypted_data`,
OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`,
int `$padding` = `OPENSSL_PKCS1_PADDING`
): bool

openssl_public_decrypt() descifra los datos `data` que han sido cifrados con la función openssl_private_encrypt() y almacena el resultado en `decrypted_data`.

Puede utilizarse esta función para verificar si el mensaje ha sido escrito por el propietario de la clave privada.

### Parámetros

`data`

`decrypted_data`

`public_key`

  `public_key` debe ser la clave pública que ha sido utilizada para cifrar los datos.

`padding`

  `padding` puede ser `OPENSSL_PKCS1_PADDING` o `OPENSSL_NO_PADDING`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `public_key` acepta ahora una instancia de OpenSSLAsymmetricKey o OpenSSLCertificate ; anteriormente, se aceptaba un resource de tipo `OpenSSL key` o `OpenSSL X.509` .

### Ver también

- openssl_private_encrypt() - Cifra datos con una clave privada
- openssl_private_decrypt() - Descifra datos con una clave privada

# openssl_public_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_public_encrypt — Cifra datos con una clave pública

### Descripción

function openssl_public_encrypt(
#[\SensitiveParameter]string `$data`,
string `&$encrypted_data`,
OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`,
int `$padding` = `OPENSSL_PKCS1_PADDING`,
?string `$digest_algo` = `null`
): bool

openssl_public_encrypt() cifra los datos `data` con la clave pública `public_key` y almacena el resultado en `encrypted_data`. Los datos cifrados pueden ser descifrados con la función openssl_private_decrypt().

Esta función puede ser utilizada para cifrar un mensaje que podrá ser leído únicamente por el propietario de la clave privada. Puede ser igualmente utilizada para almacenar datos seguros en una base de datos.

### Parámetros

`data`

`encrypted_data`

  Contendrá el resultado del cifrado.

`public_key`

  `public_key` debe ser la clave pública correspondiente a la clave privada que será utilizada para descifrar los datos.

`padding`

  `padding` puede ser `OPENSSL_PKCS1_PADDING`, `OPENSSL_SSLV23_PADDING`, `OPENSSL_PKCS1_OAEP_PADDING` o `OPENSSL_NO_PADDING`.

`digest_algo`
  El algoritmo de resumen para el relleno OAEP, o `null` para utilizar el algoritmo por omisión.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | Se ha añadido el parámetro opcional `digest_algo`.
8.0.0 | `public_key` acepta ahora una instancia de OpenSSLAsymmetricKey o OpenSSLCertificate ; anteriormente, se aceptaba un resource de tipo `OpenSSL key` o `OpenSSL X.509`.

### Ver también

- openssl_private_encrypt() - Cifra datos con una clave privada
- openssl_private_decrypt() - Descifra datos con una clave privada

# openssl_random_pseudo_bytes

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_random_pseudo_bytes — Genera una cadena pseudo-aleatoria de octetos

### Descripción

function openssl_random_pseudo_bytes(int `$length`, bool `&$strong_result` = `null`): string

Genera una string pseudo-aleatoria de octetos, cuya longitud es especificada por el argumento `length`.

Indica asimismo si el algoritmo fuerte de criptología ha sido utilizado para producir estos octetos pseudo-aleatorios, utilizando el argumento `strong_result`.

### Parámetros

`length`

  El tamaño deseado para la cadena de octetos. Debe ser un número entero positivo inferior o igual a `2147483647`. PHP intentará convertir este argumento a un entero no nulo para utilizarlo.

`strong_result`

  Si se proporciona, determina si el algoritmo de criptología utilizado era criptológicamente fuerte, es decir, seguro para ser utilizado con GPG, contraseñas, etc. `true` si lo es, `false` en caso contrario.

### Valores devueltos

Devuelve la cadena de octetos generada.

### Errores/Excepciones

openssl_random_pseudo_bytes() lanza una Exception en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `strong_result` ahora es nullable.
7.4.0 | La función ya no devuelve `false` en caso de error, sino que lanza una Exception en su lugar.

### Ejemplos

Ejemplo #1 Ejemplo openssl_random_pseudo_bytes()

    <?php
    for ($i = 1; $i <= 4; $i++) {
        $bytes = openssl_random_pseudo_bytes($i, $cstrong);
        $hex   = bin2hex($bytes);

        echo "Longitud : Octetos : $i y Hex: " . strlen($hex) . PHP_EOL;
        var_dump($hex);
        var_dump($cstrong);
        echo PHP_EOL;
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Longitud : Octetos : 1 y Hex: 2
    string(2) "42"
    bool(true)

    Longitud : Octetos : 2 y Hex: 4
    string(4) "dc6e"
    bool(true)

    Longitud : Octetos : 3 y Hex: 6
    string(6) "288591"
    bool(true)

    Longitud : Octetos : 4 y Hex: 8
    string(8) "ab86d144"
    bool(true)

### Ver también

- random_bytes() - Obtiene bytes aleatorios criptográficamente seguros
- bin2hex() - Convierte datos binarios en representación hexadecimal
- crypt() - Hash de un solo sentido (indescifrable)
- random_int() - Obtiene un integer seleccionado de manera uniforme y criptográficamente segura

# openssl_seal

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_seal — Sella datos

### Descripción

function openssl_seal(
#[\SensitiveParameter]string `$data`,
string `&$sealed_data`,
array `&$encrypted_keys`,
array `$public_key`,
string `$cipher_algo`,
string `&$iv` = `null`
): int|false

La openssl_seal() sella (cifra) `data` utilizando el `cipher_algo` especificado con una clave secreta generada aleatoriamente. La clave es posteriormente cifrada con cada una de las claves públicas en el array `public_key`, y cada clave de envoltura cifrada es devuelta en `encrypted_keys`. Esto permite enviar datos sellados a múltiples destinatarios (siempre que sus claves públicas estén disponibles). Cada destinatario debe recibir tanto los datos sellados como la clave de envoltura que ha sido cifrada con la clave pública del destinatario. El IV (vector de inicialización) es generado, y su valor es devuelto en `iv`.

### Parámetros

`data`

  Los datos a sellar

`sealed_data`

  Los datos sellados.

`encrypted_keys`

  Array de claves cifradas.

`public_key`

  Array de instancias OpenSSLAsymmetricKey que contienen las claves públicas.

`cipher_algo`

  El método de cifrado.

  Precaución

  El valor por omisión para versiones de PHP anteriores a 8.0 es (`'RC4'`), que se considera no segura. Se recomienda encarecidamente especificar explícitamente un método de cifrado seguro.

`iv`

  El vector de inicialización para el descifrado de `data`. Es requerido si el método de cifrado necesita un IV. Esto puede ser determinado llamando a openssl_cipher_iv_length() con `cipher_algo`.

  Precaución

  El IV no puede ser definido explícitamente. Cualquier valor que se le asigne es sobrescrito por un valor generado aleatoriamente.

### Valores devueltos

Devuelve la longitud de los datos sellados en caso de éxito, y `false` en caso contrario. En caso de éxito, los datos sellados son colocados en el parámetro `sealed_data`, y las claves de envoltura en `encrypted_keys`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `public_key` ahora acepta un array de instancias de OpenSSLAsymmetricKey; anteriormente, se aceptaba un array de resources de tipo `OpenSSL key`.
8.0.0 | `cipher_algo` ya no es un parámetro opcional.
8.0.0 | `iv` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con openssl_seal()

    <?php

    $data = "test";

    // obtener las claves públicas
    $pk1 = openssl_get_publickey("file://cert1.pem");
    $pk2 = openssl_get_publickey("file://cert2.pem");

    // sella el mensaje: solo los poseedores de $pk1 y $pk2 pueden descifrar
    // el mensaje $sealed con las claves $ekeys[0] y $ekeys[1] (respectivamente).
    openssl_seal($data, $sealed, $ekeys, array($pk1, $pk2));

    if (openssl_seal($data, $sealed, $ekeys, array($pk1, $pk2), 'AES256', $iv) > 0) {
        // posiblemente almacenar los valores $sealed y $iv y utilizarlos más tarde en openssl_open
        echo "éxito\n";
    }
    ?>

### Ver también

- openssl_open() - Abre datos sellados

# openssl_sign

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_sign — Firma los datos

### Descripción

function openssl_sign(
string `$data`,
string `&$signature`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
string|int `$algorithm` = `OPENSSL_ALGO_SHA1`,
int `$padding` = 0
): bool

openssl_sign() calcula la firma de los datos `data` generando una firma digital criptográfica utilizando la clave privada asociada con el parámetro `private_key`. Tenga en cuenta que los datos en sí no son cifrados.

### Parámetros

`data`

  La cadena de datos que se desea firmar.

`signature`

  Si la llamada a la función tiene éxito, la firma será devuelta en el parámetro `signature`.

`private_key`

  OpenSSLAsymmetricKey - una clave, devuelta por la función openssl_get_privatekey()

  string - una clave en formato PEM.

`algorithm`

  int - uno de los algoritmos de firma.

  string - una cadena válida devuelta por la función openssl_get_md_methods(), por ejemplo: "sha256WithRSAEncryption" o "sha384".

`padding`
  Relleno RSA PSS a utilizar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | Se ha añadido el parámetro opcional `padding`.
8.0.0 | `private_key` ahora acepta una instancia de OpenSSLAsymmetricKey o OpenSSLCertificate; anteriormente, se aceptaba un resource de tipo `OpenSSL key` o `OpenSSL X.509`.

### Ejemplos

Ejemplo #1 Ejemplo con openssl_sign()

    <?php
    // Se asume que $data contiene los datos a firmar

    // lectura de la clave pública para cada destinatario
    $pkeyid = openssl_pkey_get_private("file://src/openssl-0.9.6/demos/sign/key.pem");

    // cálculo de la firma
    openssl_sign($data, $signature, $pkeyid);

    // libera las claves de la memoria
    openssl_free_key($pkeyid);
    ?>

Ejemplo #2 Ejemplo con openssl_sign()

    <?php
    //datos que se desean firmar
    $data = 'my data';

    //Crea una nueva clave privada y pública
    $new_key_pair = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    openssl_pkey_export($new_key_pair, $private_key_pem);

    $details = openssl_pkey_get_details($new_key_pair);
    $public_key_pem = $details['key'];

    //Creación de la firma
    openssl_sign($data, $signature, $private_key_pem, OPENSSL_ALGO_SHA256);

    //Guardado para uso posterior
    file_put_contents('private_key.pem', $private_key_pem);
    file_put_contents('public_key.pem', $public_key_pem);
    file_put_contents('signature.dat', $signature);

    //Verificación de la firma
    $r = openssl_verify($data, $signature, $public_key_pem, "sha256WithRSAEncryption");
    var_dump($r);
    ?>

### Ver también

- openssl_verify() - Verifica una firma

# openssl_spki_export

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_export — Exporta un PEM válido formateado como una clave pública firmada

### Descripción

function openssl_spki_export(string `$spki`): string|false

Exporta un PEM válido formateado como una clave pública firmada.

### Parámetros

`spki`

  Una clave pública firmada válida

### Valores devueltos

Devuelve el PEM asociado formateado como clave pública, o `false` si se produce un error.

### Errores/Excepciones

Emite una alerta de nivel `E_WARNING` si un argumento no válido es pasado mediante el parámetro `spki`.

### Ejemplos

Ejemplo #1 Ejemplo con openssl_spki_export()

Extrae el PEM asociado formateado como clave pública, o `null` en caso de fallo.

    <?php
    $pkey = openssl_pkey_new('secret password');
    $spkac = openssl_spki_new($pkey, 'challenge string');
    $pubKey = openssl_spki_export(preg_replace('/SPKAC=/', '', $spkac));

    if ($pubKey) {
        echo $pubKey;
    }
    ?>

Ejemplo #2 Ejemplo con openssl_spki_export() desde <keygen>

Extrae el PEM asociado formateado como clave pública, procedente de un elemento <keygen>

    <?php
    $spkac = openssl_spki_export(preg_replace('/SPKAC=/', '', $_POST['spkac']));
    if ($spkac != NULL) {
        echo $spkac;
    } else {
        echo "La extracción de la clave pública ha fallado";
    }
    ?>
    <keygen name="spkac" challenge="challenge string" keytype="RSA">

### Ver también

- openssl_spki_new() - Genera una clave pública firmada y realiza un desafío
- openssl_spki_verify() - Verifica una clave pública firmada y realiza un desafío
- openssl_spki_export_challenge() - Exporta el challenge asociado con la clave pública firmada
- openssl_get_md_methods() - Obtiene la lista de métodos digest disponibles
- openssl_csr_new() - Genera una CSR
- openssl_csr_sign() - Firma un CSR con otro certificado (o consigo mismo) y genera un certificado

# openssl_spki_export_challenge

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_export_challenge — Exporta el challenge asociado con la clave pública firmada

### Descripción

function openssl_spki_export_challenge(string `$spki`): string|false

Exporta el challenge asociado con la clave pública firmada.

### Parámetros

`spki`

  Una clave pública firmada válida

### Valores devueltos

Devuelve el challenge asociado en forma de string o `false` en caso de error.

### Errores/Excepciones

Emite una advertencia de nivel `E_WARNING` si se pasa un argumento inválido a través del parámetro `spki`.

### Ejemplos

Ejemplo #1 Ejemplo con openssl_spki_export_challenge()

Extrae el challenge asociado en forma de string o `null` en caso de error.

    <?php
    $pkey = openssl_pkey_new('secret password');
    $spkac = openssl_spki_new($pkey, 'challenge string');
    $challenge = openssl_spki_export_challenge(preg_replace('/SPKAC=/', '', $spkac));
    ?>

Ejemplo #2 Ejemplo con openssl_spki_export_challenge() desde <keygen>

Extrae el challenge asociado de un elemento <keygen>

    <?php
    $challenge = openssl_spki_export_challenge(preg_replace('/SPKAC=/', '', $_POST['spkac']));
    ?>
    <keygen name="spkac" challenge="challenge string" keytype="RSA">

### Ver también

- openssl_spki_new() - Genera una clave pública firmada y realiza un desafío
- openssl_spki_verify() - Verifica una clave pública firmada y realiza un desafío
- openssl_spki_export() - Exporta un PEM válido formateado como una clave pública firmada
- openssl_get_md_methods() - Obtiene la lista de métodos digest disponibles
- openssl_csr_new() - Genera una CSR
- openssl_csr_sign() - Firma un CSR con otro certificado (o consigo mismo) y genera un certificado

# openssl_spki_new

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_new — Genera una clave pública firmada y realiza un desafío

### Descripción

function openssl_spki_new(#[\SensitiveParameter]OpenSSLAsymmetricKey `$private_key`, string `$challenge`, int `$digest_algo` = `OPENSSL_ALGO_MD5`): string|false

Genera una clave pública firmada utilizando un algoritmo de hash especificado.

### Parámetros

`private_key`

  `private_key` debe ser una clave privada que haya sido previamente generada por la función openssl_pkey_new() (o de lo contrario, obtenida desde una función de la familia openssl_pkey). La porción pública de la clave será utilizada para firmar el CSR.

`challenge`

  El desafío asociado al SPKAC

`digest_algo`

  El algoritmo digest. Ver openssl_get_md_method().

### Valores devueltos

Devuelve una clave pública firmada en forma de string o `false` en caso de fallo.

### Errores/Excepciones

Emite una alerta de nivel `E_WARNING` si un algoritmo con una firma desconocida es pasado mediante el parámetro `digest_algo`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `private_key` ahora acepta una instancia de OpenSSLAsymmetricKey; anteriormente, se aceptaba un resource de tipo `OpenSSL key`.

### Ejemplos

Ejemplo #1 Ejemplo con openssl_spki_new()

Genera un nuevo SPKAC con el digest por defecto (MD5)

    <?php
    $pkey = openssl_pkey_new('secret password');
    $spkac = openssl_spki_new($pkey, 'testing');

    if ($spkac !== NULL) {
        echo $spkac;
    } else {
        echo "La generación de SPKAC ha fallado";
    }
    ?>

Resultado del ejemplo anterior es similar a:

    MIICRzCCAS8wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDM3V3sS4o4
    mB9dczziRnjGAmSp+JwPrHoYMAFGvDNmZGyiWfU586X4BKs++BAj7e/FsAfno0Hd
    hN9FwpCNFSox30L03nQvLYJE7f/WqigwBeMRT7Op/xvFks4sT70xP2HRYv4KqP9a
    WRcKU6cFH8VxhFhqM2txEIxZKdFLaL28yT7bEDmcglf4JLDdgNMb9rET1dkgtKE6
    dOaJHPGjf1uvnOH4YwkQr7n4sLUR3Kdbh0ZJAFuQVDZulo+LLzxBBkqJJcB6FhF+
    oXCdHTKZnqAhpWDz+NXYytAmevab6IYm5TWPWsJUv1YKJA5lg2mXbbloIZlN9Mgc
    i9fi03bdw+crAgMBAAEWB3Rlc3RpbmcwDQYJKoZIhvcNAQEEBQADggEBALyUvP/o
    pPSoWBlorFyZ2RnGwKf9qMpE0q2IJP7G3oDR4LyK/m933DUiZ+YnqThrH/CWb4Ek
    y5I3OCyl3S4wCuU1ibZZwDVwYShr5ELp0J9PEf7qMQZOhNsizoC7k+Czb2xB6hYW
    sKfsfTKm3cXBtH3fdgc/Z1Z7VSWnAzYo38snqm72NTf5yFRnrQdphNNXi+kn1zHA
    lxXRyFDXHOcYsOnwAWfyXFA4QDHQ0ezz0UoCY8gJXovcZb4GRYqOLUAsF2HcNboy
    29WN8VqE29sL9QxVZFlwMcqyoLcNnyw38GvNvAGqSvzzbnEFP2MAQXJVe0H0hdp/
    MML5G2iNVgNozAo=

### Ver también

- openssl_spki_verify() - Verifica una clave pública firmada y realiza un desafío
- openssl_spki_export_challenge() - Exporta el challenge asociado con la clave pública firmada
- openssl_spki_export() - Exporta un PEM válido formateado como una clave pública firmada
- openssl_get_md_methods() - Obtiene la lista de métodos digest disponibles
- openssl_csr_new() - Genera una CSR
- openssl_csr_sign() - Firma un CSR con otro certificado (o consigo mismo) y genera un certificado

# openssl_spki_verify

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_verify — Verifica una clave pública firmada y realiza un desafío

### Descripción

function openssl_spki_verify(string `$spki`): bool

Verifica una clave pública firmada y realiza un desafío.

### Parámetros

`spki`

  Una clave pública firmada válida

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Emite una alerta de nivel `E_WARNING` si un argumento inválido es pasado al parámetro `spkac`.

### Ejemplos

Ejemplo #1 Ejemplo con openssl_spki_verify()

Valida una clave pública firmada existente y realiza un desafío

    <?php
    $pkey = openssl_pkey_new('secret password');
    $spkac = openssl_spki_new($pkey, 'challenge string');

    if (openssl_spki_verify(preg_replace('/SPKAC=/', '', $spkac))) {
        echo $spkac;
    } else {
        echo "La validación SPKAC ha fallado";
    }
    ?>

Ejemplo #2 Ejemplo con openssl_spki_verify() desde <keygen>

Valida una clave pública firmada existente procedente de un elemento <keygen>

    <?php
    if (openssl_spki_verify(preg_replace('/SPKAC=/', '', $_POST['spkac']))) {
        echo $spkac;
    } else {
        echo "La validación SPKAC ha fallado";
    }
    ?>
    <keygen name="spkac" challenge="challenge string" keytype="RSA">

### Ver también

- openssl_spki_new() - Genera una clave pública firmada y realiza un desafío
- openssl_spki_export_challenge() - Exporta el challenge asociado con la clave pública firmada
- openssl_spki_export() - Exporta un PEM válido formateado como una clave pública firmada
- openssl_get_md_methods() - Obtiene la lista de métodos digest disponibles
- openssl_csr_new() - Genera una CSR
- openssl_csr_sign() - Firma un CSR con otro certificado (o consigo mismo) y genera un certificado

# openssl_verify

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_verify — Verifica una firma

### Descripción

function openssl_verify(
string `$data`,
string `$signature`,
OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`,
string|int `$algorithm` = `OPENSSL_ALGO_SHA1`,
int `$padding` = 0
): int|false

openssl_verify() verifica que la firma `signature` es correcta para los datos `data`, y con la clave pública `public_key`. Esta clave debe ser la clave pública correspondiente a la clave privada utilizada durante la firma.

### Parámetros

`data`

  La cadena de datos utilizada para generar la firma

`signature`

  Una cadena binaria bruta, generada por la función openssl_sign() o similar

`public_key`

  OpenSSLAsymmetricKey - una clave, retornada por la función openssl_get_publickey()

  string - una clave en formato PEM, por ejemplo: `-----BEGIN PUBLIC KEY----- MIIBCgK...`.

`algorithm`

  int - una de las firmas de algoritmos.

  string - una cadena válida retornada por la función openssl_get_md_methods(), por ejemplo: "sha1WithRSAEncryption" o "sha512". Algoritmo por omisión: "OPENSSL_ALGO_SHA1".

`padding`
  Relleno RSA PSS a utilizar.

### Valores devueltos

Retorna 1 si la firma es correcta, 0 si es incorrecta y -1 o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | Se ha añadido el parámetro opcional `padding`.
8.0.0 | `public_key` acepta ahora una instancia de OpenSSLAsymmetricKey o OpenSSLCertificate; anteriormente, se aceptaba un resource de tipo `OpenSSL key` o `OpenSSL X.509`.

### Ejemplos

Ejemplo #1 Ejemplo con openssl_verify()

    <?php
    // Se asume que $data y $signature contienen los datos a firmar y
    // la firma.

    // Lectura de la clave pública desde el certificado
    $pubkeyid = openssl_pkey_get_public("file://src/openssl-0.9.6/demos/sign/cert.pem");

    // indica si la firma es correcta
    $ok = openssl_verify($data, $signature, $pubkeyid);
    if ($ok == 1) {
        echo "Firma válida";
    } elseif ($ok == 0) {
        echo "Firma errónea";
    } else {
        echo "Error de verificación de la firma";
    }
    // libera las claves de la memoria
    openssl_free_key($pubkeyid);
    ?>

Ejemplo #2 Ejemplo con openssl_verify()

    <?php
    //Datos que se desean firmar
    $data = 'my data';

    //Crea una nueva clave privada y pública
    $private_key_res = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $details = openssl_pkey_get_details($private_key_res);
    $public_key_res = openssl_pkey_get_public($details['key']);

    //Crea una firma
    openssl_sign($data, $signature, $private_key_res, "sha256WithRSAEncryption");

    //Verifica la firma
    $ok = openssl_verify($data, $signature, $public_key_res, OPENSSL_ALGO_SHA256);
    if ($ok == 1) {
        echo "válida";
    } elseif ($ok == 0) {
        echo "inválida";
    } else {
        echo "error: ".openssl_error_string();
    }
    ?>

### Ver también

- openssl_sign() - Firma los datos

# openssl_x509_check_private_key

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_check_private_key — Verifica si una clave privada corresponde a un certificado

### Descripción

function openssl_x509_check_private_key(OpenSSLCertificate|string `$certificate`, #[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`): bool

Verifica si el argumento `private_key` proporcionado es la clave privada que corresponde a `certificate`.

Advertencia

Esta función no verifica si KEY es efectivamente una clave privada o no. Simplemente compara el material público (por ejemplo exponent y modulo de una clave RSA) y/o los parámetros de clave (por ejemplo los parámetros EC de una clave EC) de un par de claves.

Esto significa, por ejemplo, que una clave pública podría ser proporcionada para `private_key` y la función puede devolver `true`.

### Parámetros

`certificate`

  El certificado.

`private_key`

  La clave privada.

### Valores devueltos

Devuelve `true` si `private_key` es la clave privada que corresponde a `certificate`, o `false` en caso contrario.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `certificate` ahora acepta una instancia de OpenSSLCertificate ; anteriormente, se aceptaba un resource de tipo `OpenSSL X.509`.
8.0.0 | `private_key` ahora acepta una instancia de OpenSSLAsymmetricKey o OpenSSLCertificate ; anteriormente, se aceptaba un resource de tipo `OpenSSL key` o `OpenSSL X.509`.

# openssl_x509_checkpurpose

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_checkpurpose — Verifica el uso de un certificado

### Descripción

function openssl_x509_checkpurpose(
OpenSSLCertificate|string `$certificate`,
int `$purpose`,
array `$ca_info` = [],
?string `$untrusted_certificates_file` = `null`
): bool|int

openssl_x509_checkpurpose() examina el certificado especificado por `certificate`, para ver si puede ser utilizado para una operación particular `purpose`.

### Parámetros

`certificate`

  El certificado examinado.

`purpose`

  Uso de openssl_x509_checkpurpose()
  Constante | Descripción
  --- | ---
  X509_PURPOSE_SSL_CLIENT | ¿Puede el certificado ser utilizado con el cliente de una conexión SSL?
  X509_PURPOSE_SSL_SERVER | ¿Puede el certificado ser utilizado con el servidor de una conexión SSL?
  X509_PURPOSE_NS_SSL_SERVER | ¿Puede el certificado ser utilizado con un servidor Netscape de una conexión SSL?
  X509_PURPOSE_SMIME_SIGN | ¿Puede el certificado ser utilizado para firmar correos en el estándar S/MIME?
  X509_PURPOSE_SMIME_ENCRYPT | ¿Puede el certificado ser utilizado para cifrar un correo en formato S/MIME?
  X509_PURPOSE_CRL_SIGN | ¿Puede el certificado ser utilizado para cifrar una lista de revocación de certificados? (CRL)?
  X509_PURPOSE_ANY | ¿Puede el certificado ser utilizado para cualquiera de estos casos?

  Estas opciones no son campos de bits: solo puede pasarse una a la vez.
`ca_info`

  `ca_info` debe ser un array de directorios/ficheros de CA de confianza como se describe en la Verificación de certificados.

`untrusted_certificates_file`

  Si se especifica, es el nombre de un fichero en formato PEM que contiene los certificados que podrán ayudar durante la verificación del certificado, aunque se les deba otorgar una confianza limitada.

### Valores devueltos

Retorna `true` si el certificado puede ser utilizado para un propósito particular, `false` si no puede serlo, o -1 si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `certificate` ahora acepta una instancia de OpenSSLCertificate; anteriormente, se aceptaba un resource de tipo `OpenSSL X.509`.
8.0.0 | `untrusted_certificates_file` ahora es nullable.

# openssl_x509_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_export — Exporta un certificado a una cadena de caracteres

### Descripción

function openssl_x509_export(OpenSSLCertificate|string `$certificate`, string `&$output`, bool `$no_text` = `true`): bool

openssl_x509_export() almacena un certificado `certificate` en el fichero `output` en formato PEM.

### Parámetros

`x509`
  Ver los parámetros clave/Certificados para una lista de valores válidos.
`output`

  En caso de éxito, contendrá el PEM.

`no_text`
  El parámetro opcional `notext` afecta al nivel de verbosidad del display; si vale `false`, se añadirán información legible por humanos en el display. Por omisión, el parámetro `notext` vale `true`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `certificate` acepta ahora una instancia de OpenSSLCertificate; anteriormente, se aceptaba un resource de tipo `OpenSSL X.509`.

# openssl_x509_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_export_to_file — Exporta un certificado a un archivo

### Descripción

function openssl_x509_export_to_file(OpenSSLCertificate|string `$certificate`, string `$output_filename`, bool `$no_text` = `true`): bool

openssl_x509_export_to_file() almacena un certificado `certificate` en el archivo `output_filename` en formato PEM.

### Parámetros

`x509`
  Ver los parámetros clave/Certificados para una lista de valores válidos.
`output_filename`

  Ruta del archivo de salida.

`no_text`
  El parámetro opcional `notext` afecta al nivel de verbosidad del display; si vale `false`, se añadirán información legible por humanos en el display. Por omisión, el parámetro `notext` vale `true`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `certificate` acepta ahora una instancia de OpenSSLCertificate; anteriormente, se aceptaba un resource de tipo `OpenSSL X.509`.

# openssl_x509_fingerprint

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_x509_fingerprint — Calcula la huella digital o el resumen de un certificado X.509 dado

### Descripción

function openssl_x509_fingerprint(OpenSSLCertificate|string `$certificate`, string `$digest_algo` = "sha1", bool `$binary` = `false`): string|false

La función openssl_x509_fingerprint() devuelve el resumen de un certificado `certificate` en forma de string.

### Parámetros

`x509`
  Ver los parámetros clave/Certificados para una lista de valores válidos.
`digest_algo`

  El método de resumen o el algoritmo de hash a utilizar, por ejemplo "sha256", uno de openssl_get_md_methods().

`binary`

  Cuando se define como `true`, muestra los datos binarios sin tratar. `false` muestra en hexits minúsculas.

### Valores devueltos

Devuelve una string que contiene la huella digital calculada del certificado en forma de hexits minúsculas, a menos que `binary` esté definido como `true` en cuyo caso se devuelve la representación binaria sin tratar del resumen del mensaje.

Devuelve `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `certificate` ahora acepta una instancia de OpenSSLCertificate; anteriormente, se aceptaba un resource de tipo `OpenSSL X.509`.

# openssl_x509_free

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_free — Libera los recursos tomados por un certificado

Advertencia

Esta función está OBSOLETA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function openssl_x509_free(OpenSSLCertificate `$certificate`): void

> Nota: Esta función no tiene ningún efecto. Anterior a PHP 8.0.0, esta función era utilizada para cerrar un recurso.

openssl_x509_free() libera los recursos de memoria tomados por el certificado `certificate`.

### Parámetros

`certificate`

### Valores devueltos

No se retorna ningún valor.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función es ahora obsoleta ya que no tiene ningún efecto.
8.0.0 | `certificate` ahora acepta una instancia de OpenSSLCertificate; anteriormente, se aceptaba un resource de tipo `OpenSSL X.509`.

# openssl_x509_parse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_parse — Analiza un certificado X509

### Descripción

function openssl_x509_parse(OpenSSLCertificate|string `$certificate`, bool `$short_names` = `true`): array|false

openssl_x509_parse() analiza el certificado X509 `certificate`, y devuelve las informaciones contenidas en él, incluyendo el sujeto (`subject`), nombre (`name`), emisor (`issuer name`), fechas de inicio y fin (`valid from date` y `valid to date`), etc.

### Parámetros

`certificate`

  Certificado X509. Ver parámetro de Clave/Certificado para una lista de valores válidos.

`short_names`

  `short_names` controla la indexación de los datos en el array: si `short_names` vale `true` (valor por omisión), entonces los campos serán indexados con la forma corta de los nombres, de lo contrario, se utilizarán los nombres largos. (por ejemplo, `CN` es el nombre corto de `commonName`).

### Valores devueltos

La estructura de los datos devueltos es (intencionalmente) no documentada, ya que está sujeta a cambios sin previo aviso.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | El análisis de un certificado sin segundos en UTCTime ya no es permitido para ninguna versión de OpenSSL. Esto ya estaba prohibido para OpenSSL versión 3.3+.
8.0.0 | `certificate` ahora acepta una instancia de OpenSSLCertificate; anteriormente, se aceptaba un resource de tipo `OpenSSL X.509`.

# openssl_x509_read

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_read — Analiza un certificado X.509 y devuelve un objeto

### Descripción

function openssl_x509_read(OpenSSLCertificate|string `$certificate`): OpenSSLCertificate|false

openssl_x509_read() analiza el certificado `certificate` y devuelve un objeto OpenSSLCertificate para este.

### Parámetros

`certificate`

  Certificado X509. Ver parámetros clave/certificados para la lista de valores válidos.

### Valores devueltos

Devuelve un OpenSSLCertificate en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Se emite un `E_WARNING` si no se puede recuperar el certificado X.509.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de OpenSSLCertificate ; anteriormente, se devolvía un resource de tipo `OpenSSL X.509`.
8.0.0 | `certificate` acepta ahora una instancia de OpenSSLCertificate ; anteriormente, se aceptaba un resource de tipo `OpenSSL X.509`.

# openssl_x509_verify

(PHP 7 >= 7.4.0, PHP 8)

openssl_x509_verify — Verifica la firma digital de un certificado x509 con respecto a una clave pública

### Descripción

function openssl_x509_verify(OpenSSLCertificate|string `$certificate`, OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`): int

La función openssl_x509_verify() verifica que el certificado `certificate` ha sido firmado por la clave privada correspondiente a la clave pública `public_key`.

### Parámetros

`x509`
  Ver los parámetros clave/Certificados para una lista de valores válidos.
`public_key`

  OpenSSLAsymmetricKey - una clave, devuelta por la función openssl_get_publickey()

  string - una clave con formato PEM, por ejemplo, `-----BEGIN PUBLIC KEY----- MIIBCgK...`.

### Valores devueltos

Devuelve 1 si la firma es correcta, 0 si es incorrecta y -1 si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `certificate` acepta ahora una instancia de OpenSSLCertificate; anteriormente, un resource de tipo `OpenSSL X.509` era aceptado.
8.0.0 | `public_key` acepta ahora una instancia de OpenSSLAsymmetricKey o OpenSSLCertificate; anteriormente, un resource de tipo `OpenSSL key` o `OpenSSL X.509` era aceptado.

### Ejemplos

Ejemplo #1 Ejemplo con openssl_x509_verify()

    <?php
    $hostname = "news.php.net";
    $ssloptions = array(
        "capture_peer_cert" => true,
        "capture_peer_cert_chain" => true,
        "allow_self_signed"=> false,
        "CN_match" => $hostname,
        "verify_peer" => true,
        "SNI_enabled" => true,
        "SNI_server_name" => $hostname,
    );

    $ctx = stream_context_create( array("ssl" => $ssloptions) );
    $result = stream_socket_client("ssl://$hostname:443", $errno, $errstr, 30, STREAM_CLIENT_CONNECT, $ctx);
    $cont = stream_context_get_params($result);
    $x509 = $cont["options"]["ssl"]["peer_certificate"];
    $certparsed = openssl_x509_parse($x509);

    foreach($cont["options"]["ssl"]["peer_certificate_chain"] as $chaincert)
    {
        $chainparsed = openssl_x509_parse($chaincert);
        $chain_public_key = openssl_get_publickey($chaincert);
        $r = openssl_x509_verify($x509, $chain_public_key);
        if ($r==1)
        {
            echo $certparsed['subject']['CN'];
            echo " fue firmado digitalmente por ";
            echo $chainparsed['subject']['CN']."\n";
        }
    }
    ?>

### Ver también

- openssl_verify() - Verifica una firma
- openssl_get_publickey() - Alias de openssl_pkey_get_public

## Tabla de contenidos

- openssl_cipher_iv_length — Obtiene la longitud del vector de inicialización cipher
- openssl_cipher_key_length — Devuelve la longitud de la clave de cifrado
- openssl_cms_decrypt — Descifra un mensaje CMS
- openssl_cms_encrypt — Cifra un mensaje CMS
- openssl_cms_read — Exporta el fichero CMS a un array de certificados PEM
- openssl_cms_sign — Firma un fichero
- openssl_cms_verify — Verifica una firma CMS
- openssl_csr_export — Exporta un CSR a un fichero o una variable
- openssl_csr_export_to_file — Exporta una CSR a un fichero
- openssl_csr_get_public_key — Devuelve la clave pública de un CSR
- openssl_csr_get_subject — Retorna el sujeto de una CSR
- openssl_csr_new — Genera una CSR
- openssl_csr_sign — Firma un CSR con otro certificado (o consigo mismo) y genera un certificado
- openssl_decrypt — Descifrar los datos
- openssl_dh_compute_key — Calcula un secreto compartido para un valor público de la clave DH pública remota y la clave DH local
- openssl_digest — Calcula un digest
- openssl_encrypt — Cifra los datos
- openssl_error_string — Retorna el mensaje de error OpenSSL
- openssl_free_key — Libera los recursos
- openssl_get_cert_locations — Obtener las ubicaciones de certificados disponibles
- openssl_get_cipher_methods — Obtiene la lista de métodos de cifrado disponibles
- openssl_get_curve_names — Obtiene la lista de nombres de curvas disponibles para ECC
- openssl_get_md_methods — Obtiene la lista de métodos digest disponibles
- openssl_get_privatekey — Alias de openssl_pkey_get_private
- openssl_get_publickey — Alias de openssl_pkey_get_public
- openssl_open — Abre datos sellados
- openssl_password_hash — Crea un hash de contraseña usando la implementación de Argon2 de OpenSSL
- openssl_password_verify — Verifica una contraseña frente a un hash usando la implementación de Argon2 de OpenSSL
- openssl_pbkdf2 — Genera una cadena PKCS5 v2 PBKDF2
- openssl_pkcs12_export — Exporta un certificado compatible PKCS#12 a una variable
- openssl_pkcs12_export_to_file — Exporta un certificado compatible con PKCS#12
- openssl_pkcs12_read — Lee un certificado PKCS#12 en un array
- openssl_pkcs7_decrypt — Descifra un mensaje S/MIME
- openssl_pkcs7_encrypt — Cifra un mensaje S/MIME
- openssl_pkcs7_read — Exporta el fichero PKCS7 a un array de certificados PEM
- openssl_pkcs7_sign — Firma un mensaje S/MIME
- openssl_pkcs7_verify — Verifica la firma de un mensaje S/MIME
- openssl_pkey_derive — Calcula el secreto compartido para el valor público de la clave DH o ECDH remota y local
- openssl_pkey_export — Almacena una representación exportable de la clave en una cadena de caracteres
- openssl_pkey_export_to_file — Guarda una clave en formato ASCII en un fichero
- openssl_pkey_free — Libera una clave privada
- openssl_pkey_get_details — Devuelve un array que contiene los detalles de la clave
- openssl_pkey_get_private — Lee una clave privada
- openssl_pkey_get_public — Extrae una clave pública de un certificado y la prepara
- openssl_pkey_new — Genera una nueva clave privada
- openssl_private_decrypt — Descifra datos con una clave privada
- openssl_private_encrypt — Cifra datos con una clave privada
- openssl_public_decrypt — Descifra datos con una clave pública
- openssl_public_encrypt — Cifra datos con una clave pública
- openssl_random_pseudo_bytes — Genera una cadena pseudo-aleatoria de octetos
- openssl_seal — Sella datos
- openssl_sign — Firma los datos
- openssl_spki_export — Exporta un PEM válido formateado como una clave pública firmada
- openssl_spki_export_challenge — Exporta el challenge asociado con la clave pública firmada
- openssl_spki_new — Genera una clave pública firmada y realiza un desafío
- openssl_spki_verify — Verifica una clave pública firmada y realiza un desafío
- openssl_verify — Verifica una firma
- openssl_x509_check_private_key — Verifica si una clave privada corresponde a un certificado
- openssl_x509_checkpurpose — Verifica el uso de un certificado
- openssl_x509_export — Exporta un certificado a una cadena de caracteres
- openssl_x509_export_to_file — Exporta un certificado a un archivo
- openssl_x509_fingerprint — Calcula la huella digital o el resumen de un certificado X.509 dado
- openssl_x509_free — Libera los recursos tomados por un certificado
- openssl_x509_parse — Analiza un certificado X509
- openssl_x509_read — Analiza un certificado X.509 y devuelve un objeto
- openssl_x509_verify — Verifica la firma digital de un certificado x509 con respecto a una clave pública

# La clase OpenSSLCertificate

(PHP 8)

## Introducción

Una clase completamente opaca que reemplaza los recursos `OpenSSL X.509` a partir de PHP 8.0.0.

## Sinopsis de la Clase

final class OpenSSLCertificate {
}

# La clase OpenSSLCertificateSigningRequest

(PHP 8)

## Introducción

Una clase completamente opaca que reemplaza los recursos `OpenSSL X.509 CSR` a partir de PHP 8.0.0.

## Sinopsis de la Clase

final class OpenSSLCertificateSigningRequest {
}

# La clase OpenSSLAsymmetricKey

(PHP 8)

## Introducción

Una clase completamente opaca que reemplaza los recursos `OpenSSL key` a partir de PHP 8.0.0.

## Sinopsis de la Clase

final class OpenSSLAsymmetricKey {
}

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
  - Tipos de recursos
- Constantes predefinidas
  - Opciones de validación general
  - Opciones de relleno (Padding) para el cifrado asimétrico
  - Tipos de clave
  - Constantes/opciones PKCS7
  - Bandera/Constantes CMS
  - Algoritmo de firma
  - Cifrados
  - Constantes de versión
  - Constantes de identificación del nombre del servidor
  - Otras constantes
- Parámetros de claves/certificados
- Verificación de certificados
- Funciones de OpenSSL
  - openssl_cipher_iv_length — Obtiene la longitud del vector de inicialización cipher
  - openssl_cipher_key_length — Devuelve la longitud de la clave de cifrado
  - openssl_cms_decrypt — Descifra un mensaje CMS
  - openssl_cms_encrypt — Cifra un mensaje CMS
  - openssl_cms_read — Exporta el fichero CMS a un array de certificados PEM
  - openssl_cms_sign — Firma un fichero
  - openssl_cms_verify — Verifica una firma CMS
  - openssl_csr_export — Exporta un CSR a un fichero o una variable
  - openssl_csr_export_to_file — Exporta una CSR a un fichero
  - openssl_csr_get_public_key — Devuelve la clave pública de un CSR
  - openssl_csr_get_subject — Retorna el sujeto de una CSR
  - openssl_csr_new — Genera una CSR
  - openssl_csr_sign — Firma un CSR con otro certificado (o consigo mismo) y genera un certificado
  - openssl_decrypt — Descifrar los datos
  - openssl_dh_compute_key — Calcula un secreto compartido para un valor público de la clave DH pública remota y la clave DH local
  - openssl_digest — Calcula un digest
  - openssl_encrypt — Cifra los datos
  - openssl_error_string — Retorna el mensaje de error OpenSSL
  - openssl_free_key — Libera los recursos
  - openssl_get_cert_locations — Obtener las ubicaciones de certificados disponibles
  - openssl_get_cipher_methods — Obtiene la lista de métodos de cifrado disponibles
  - openssl_get_curve_names — Obtiene la lista de nombres de curvas disponibles para ECC
  - openssl_get_md_methods — Obtiene la lista de métodos digest disponibles
  - openssl_get_privatekey — Alias de openssl_pkey_get_private
  - openssl_get_publickey — Alias de openssl_pkey_get_public
  - openssl_open — Abre datos sellados
  - openssl_password_hash — Crea un hash de contraseña usando la implementación de Argon2 de OpenSSL
  - openssl_password_verify — Verifica una contraseña frente a un hash usando la implementación de Argon2 de OpenSSL
  - openssl_pbkdf2 — Genera una cadena PKCS5 v2 PBKDF2
  - openssl_pkcs12_export — Exporta un certificado compatible PKCS#12 a una variable
  - openssl_pkcs12_export_to_file — Exporta un certificado compatible con PKCS#12
  - openssl_pkcs12_read — Lee un certificado PKCS#12 en un array
  - openssl_pkcs7_decrypt — Descifra un mensaje S/MIME
  - openssl_pkcs7_encrypt — Cifra un mensaje S/MIME
  - openssl_pkcs7_read — Exporta el fichero PKCS7 a un array de certificados PEM
  - openssl_pkcs7_sign — Firma un mensaje S/MIME
  - openssl_pkcs7_verify — Verifica la firma de un mensaje S/MIME
  - openssl_pkey_derive — Calcula el secreto compartido para el valor público de la clave DH o ECDH remota y local
  - openssl_pkey_export — Almacena una representación exportable de la clave en una cadena de caracteres
  - openssl_pkey_export_to_file — Guarda una clave en formato ASCII en un fichero
  - openssl_pkey_free — Libera una clave privada
  - openssl_pkey_get_details — Devuelve un array que contiene los detalles de la clave
  - openssl_pkey_get_private — Lee una clave privada
  - openssl_pkey_get_public — Extrae una clave pública de un certificado y la prepara
  - openssl_pkey_new — Genera una nueva clave privada
  - openssl_private_decrypt — Descifra datos con una clave privada
  - openssl_private_encrypt — Cifra datos con una clave privada
  - openssl_public_decrypt — Descifra datos con una clave pública
  - openssl_public_encrypt — Cifra datos con una clave pública
  - openssl_random_pseudo_bytes — Genera una cadena pseudo-aleatoria de octetos
  - openssl_seal — Sella datos
  - openssl_sign — Firma los datos
  - openssl_spki_export — Exporta un PEM válido formateado como una clave pública firmada
  - openssl_spki_export_challenge — Exporta el challenge asociado con la clave pública firmada
  - openssl_spki_new — Genera una clave pública firmada y realiza un desafío
  - openssl_spki_verify — Verifica una clave pública firmada y realiza un desafío
  - openssl_verify — Verifica una firma
  - openssl_x509_check_private_key — Verifica si una clave privada corresponde a un certificado
  - openssl_x509_checkpurpose — Verifica el uso de un certificado
  - openssl_x509_export — Exporta un certificado a una cadena de caracteres
  - openssl_x509_export_to_file — Exporta un certificado a un archivo
  - openssl_x509_fingerprint — Calcula la huella digital o el resumen de un certificado X.509 dado
  - openssl_x509_free — Libera los recursos tomados por un certificado
  - openssl_x509_parse — Analiza un certificado X509
  - openssl_x509_read — Analiza un certificado X.509 y devuelve un objeto
  - openssl_x509_verify — Verifica la firma digital de un certificado x509 con respecto a una clave pública
- OpenSSLCertificate — La clase OpenSSLCertificate
- OpenSSLCertificateSigningRequest — La clase OpenSSLCertificateSigningRequest
- OpenSSLAsymmetricKey — La clase OpenSSLAsymmetricKey

# Tabla de hachaje de contraseñas

# Introducción

La API de hachaje de contraseñas proporciona un gestor simple de utilizar basado en la función crypt() y otros algoritmos de hachaje de contraseñas, facilitando la creación y gestión de contraseñas de manera segura.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación

## Requerimientos

No se requiere ninguna biblioteca externa para compilar esta extensión.

Para el hachado de contraseñas Argon2, debe estar disponible » libargon2 o, a partir de PHP 8.4.0, la versión OpenSSL 3.2 o superior. A partir de PHP 7.3.0, se requiere la versión 20161029 o superior de libargon2 si se utiliza libargon2.

## Instalación

No hay instalación necesaria para usar estas funciones, son parte del núcleo de PHP.

Sin embargo, para activar el hachado de contraseñas Argon2, PHP debe ser compilado con soporte para libargon2 utilizando la opción de configuración --with-password-argon2 o, a partir de PHP 8.4.0, con OpenSSL utilizando --with-openssl y --with-openssl-argon2.

Anterior a PHP 8.1.0, era posible especificar el directorio argon2 con --with-password-argon2[=DIR].

# Constantes predefinidas

Las constantes listadas aquí están siempre disponibles en PHP.

`PASSWORD_BCRYPT` (string)

  La constante `PASSWORD_BCRYPT` se utiliza para crear un nuevo hash de contraseña utilizando el algoritmo `CRYPT_BLOWFISH`.

  Siempre ha devuelto el resultado del hash utilizando el formato crypt "$2y$", que siempre será un string de 60 caracteres de longitud.

  Opciones admitidas:

  - `salt` (string) - permite proporcionar manualmente un salt a utilizar para el hash de la contraseña. Tenga en cuenta que esto sobrescribirá cualquier salt generado automáticamente.

    Si se omite, un salt aleatorio será generado por la función password_hash() para cada contraseña hasheada. Este es el propósito de la operación y a partir de PHP 7.0.0 la opción salt ha sido desaconsejada.

  - `cost` (int) - el costo algorítmico a utilizar. Ejemplos de estos valores pueden encontrarse en la página de documentación de la función crypt().

    Si se omite, se utilizará un valor por defecto de `12`. Es una buena base pero podría ser necesario aumentarlo según la arquitectura del hardware.

`PASSWORD_BCRYPT_DEFAULT_COST` (int)

`PASSWORD_ARGON2I` (string)

  `PASSWORD_ARGON2I` se utiliza para crear nuevos hashes de contraseña utilizando el algoritmo Argon2i.

  Opciones admitidas:

  - `memory_cost` (int) - Memoria máxima (en kibibytes) que puede ser utilizada para calcular el hash Argon2. Por defecto a `PASSWORD_ARGON2_DEFAULT_MEMORY_COST`.

  - `time_cost` (int) - Tiempo máximo de duración que puede tomar calcular el hash Argon2. Por defecto a `PASSWORD_ARGON2_DEFAULT_TIME_COST`.

  - `threads` (int) - Número de hilos a utilizar para calcular el hash Argon2. Por defecto a `PASSWORD_ARGON2_DEFAULT_THREADS`. Solo disponible con libargon2, y no con la implementación libsodium.

  Disponible a partir de PHP 7.2.0.

`PASSWORD_ARGON2ID` (string)

  `PASSWORD_ARGON2ID` se utiliza para crear nuevos hashes de contraseña utilizando el algoritmo Argon2id. Admite las mismas opciones que `PASSWORD_ARGON2I`.

  Disponible a partir de PHP 7.3.0.

`PASSWORD_ARGON2_DEFAULT_MEMORY_COST` (int)

  Cantidad de memoria por defecto (en bytes) que será utilizada al intentar calcular un hash.

  Disponible a partir de PHP 7.2.0.

`PASSWORD_ARGON2_DEFAULT_TIME_COST` (int)

  Tiempo por defecto que se tomará para intentar calcular un hash.

  Disponible a partir de PHP 7.2.0.

`PASSWORD_ARGON2_DEFAULT_THREADS` (int)

  Número por defecto de hilos que Argon2lib utilizará. No disponible con la implementación libsodium.

  Disponible a partir de PHP 7.2.0.

`PASSWORD_ARGON2_PROVIDER` (string)

  Disponible a partir de PHP 7.4.0.

`PASSWORD_DEFAULT` (string)

  El algoritmo por defecto a utilizar para el hash si no se proporciona ningún algoritmo. Este valor puede cambiar en futuras versiones de PHP donde es probable que se admitan mejores algoritmos de hash.

  Es importante tener en cuenta que con el tiempo, esta constante puede cambiar. Por lo tanto, es crucial ser consciente de que la longitud del hash resultante puede variar. Por consiguiente, al utilizar `PASSWORD_DEFAULT`, el hash resultante debe almacenarse de una manera capaz de admitir hashes arbitrarios, la anchura recomendada es de `255` bytes.

  Actualmente, es un alias de `PASSWORD_BCRYPT`.

##### Historial de cambios

Versión | Descripción
--- | ---
7.4.0 | Los valores para las constantes `PASSWORD_BCRYPT`, `PASSWORD_ARGON2I`, `PASSWORD_ARGON2ID` y `PASSWORD_DEFAULT` ahora son strings. Anteriormente, eran ints.

# Funciones de hash de contraseñas

# password_algos

(PHP 7 >= 7.4.0, PHP 8)

password_algos — Obtiene todos los identificadores de los algoritmos de hash de contraseñas disponibles

### Descripción

function password_algos(): array

Devuelve una lista completa de todos los identificadores de los algoritmos de hash de contraseñas registrados, en forma de un array de string.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve todos los identificadores de los algoritmos de hash de contraseñas disponibles.

### Ejemplos

Ejemplo #1 Uso básico de la función password_algos()

    <?php
    print_r(password_algos());
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => 2y
        [1] => argon2i
        [2] => argon2id
    )

# password_get_info

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_get_info — Devuelve información sobre el hash proporcionado

### Descripción

function password_get_info(string `$hash`): array

Cuando se le pasa un hash válido creado con un algoritmo soportado por password_hash(), esta función devolverá un array con información sobre dicho hash.

### Parámetros

`hash`

  Un hash creado por la función password_hash().

### Valores devueltos

Devuelve un array asociativo con tres elementos:

- `algo`, que coincidirá con una constante de algoritmo de contraseñas
- `algoName`, que tiene el nombre legible por humanos del algoritmo
- `options`, que incluye las opciones proporcionadas al llamar a password_hash()

# password_hash

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_hash — Crea una clave de hash para una contraseña

### Descripción

function password_hash(#[\SensitiveParameter]string `$password`, string|int|null `$algo`, array `$options` = []): string

La función password_hash() crea un nuevo hash utilizando un algoritmo de hash fuerte e irreversible.

Los siguientes algoritmos son actualmente soportados:

- `PASSWORD_DEFAULT` - Uso del algoritmo bcrypt (por omisión desde PHP 5.5.0). Tenga en cuenta que esta constante está diseñada para cambiar con el tiempo, a medida que se añaden algoritmos más recientes y fuertes a PHP. Por esta razón, la longitud del resultado de este algoritmo puede cambiar con el tiempo, por lo que se recomienda almacenar el resultado en una columna de la base de datos que pueda contener al menos 60 caracteres (255 bytes puede ser una muy buena opción).
- `PASSWORD_BCRYPT` - Uso del algoritmo bcrypt para crear la clave de hash. Esto creará una clave de hash estándar crypt() utilizando el identificador `$2y$`.
- `PASSWORD_ARGON2I` - Utiliza el algoritmo de hash Argon2i para crear el hash. Este algoritmo solo está disponible si PHP ha sido compilado con el soporte de Argon2
- `PASSWORD_ARGON2ID` - Utiliza el algoritmo de hash Argon2id para crear el hash. Este algoritmo solo está disponible si PHP ha sido compilado con el soporte de Argon2

Opciones soportadas para `PASSWORD_BCRYPT`:

- `salt` (string) - para proporcionar manualmente un salt a utilizar durante el hash de la contraseña. Tenga en cuenta que esta opción evitará la generación automática.

  Si se omite, un salt aleatorio será generado por la función password_hash() para cada contraseña hash. Este es el modo de funcionamiento previsto.

  Advertencia

  La opción Salt está obsoleta. Es preferible utilizar simplemente el salt que se genera por omisión. A partir de PHP 8.0.0, un salt proporcionado explícitamente es ignorado.

- `cost` (int) - determina el costo algorítmico que debe ser utilizado. Ejemplos de estos valores pueden ser encontrados en la página de documentación de la función crypt().

  Si se omite, el valor por omisión `12` será utilizado. Este es un buen compromiso, pero debe ser ajustado según el hardware utilizado.

Opciones soportadas para `PASSWORD_ARGON2I` y `PASSWORD_ARGON2ID`:

- `memory_cost` (int) - Memoria máxima (en kilobytes binarios) que puede ser utilizada para calcular el hash Argon2. Por omisión a `PASSWORD_ARGON2_DEFAULT_MEMORY_COST`.

- `time_cost` (int) - Duración máxima de tiempo que puede tomar para calcular el hash Argon2. Por omisión a `PASSWORD_ARGON2_DEFAULT_TIME_COST`.

- `threads` (int) - Número de hilos a utilizar para calcular el hash Argon2. Por omisión a `PASSWORD_ARGON2_DEFAULT_THREADS`.

  Advertencia

  Solo disponible cuando PHP utiliza libargon2, y no la implementación libsodium.

### Parámetros

`password`

  La contraseña del usuario.

  Precaución

  El uso de la constante `PASSWORD_BCRYPT` para el algoritmo hará que el parámetro `password` sea truncado a una longitud máxima de 72 bytes.

`algo`

  Una constante del algoritmo de contraseña que representa el algoritmo a utilizar durante el hasheo de la contraseña.

`options`

  Un array asociativo que contiene las opciones. Ver también las constantes del algoritmo de contraseña para la documentación sobre las opciones soportadas para cada algoritmo.

### Valores devueltos

Retorna la contraseña hash.

El algoritmo utilizado, el costo y el salt están contenidos en el hash retornado. También, toda la información útil para verificar este último está incluida. Esto permite que la función password_verify() verifique el hash sin necesidad de almacenar por separado esta información.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | El valor por omisión de la opción `cost` del algoritmo `PASSWORD_BCRYPT` ha sido aumentado de `10` a `12`.
8.3.0 | password_hash() ahora asocia la excepción Random\RandomException subyacente a Exception::$previous cuando una ValueError es lanzada debido a un fallo en la generación del salt.
8.0.0 | password_hash() ya no retorna `false` en caso de fallo, una ValueError será lanzada si el algoritmo de hash de contraseña no es válido, o una Error si el hash de contraseña falló por una razón desconocida.
8.0.0 | `algo` ahora es nullable.
7.4.0 | El parámetro `algo` ahora espera una string, pero sigue aceptando un int para mantener la compatibilidad hacia atrás.
7.4.0 | La extensión sodium proporciona una implementación alternativa para las contraseñas Argon2.
7.3.0 | Añadido el soporte para contraseñas Argon2id utilizando `PASSWORD_ARGON2ID`.
7.2.0 | Añadido el soporte para contraseñas Argon2i utilizando `PASSWORD_ARGON2I`.

### Ejemplos

Ejemplo #1 Ejemplo con password_hash()

    <?php
    echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);
    ?>

Resultado del ejemplo anterior es similar a:

    $2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.

Ejemplo #2 Ejemplo con password_hash() definiendo manualmente la opción cost

    <?php
    $options = [
         // Aumenta el costo de bcrypt de 12 a 13.
        'cost' => 13,
    ];
    echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);
    ?>

Resultado del ejemplo anterior es similar a:

    $2y$13$xeDfQumlmdm0Sco.4qmH1OGfUUmOcuRmfae0dPJhjX1Bq0yYhqbNi

Ejemplo #3 Ejemplo con password_hash() para encontrar un buen costo (cost)

Este código realizará un benchmark de la máquina para determinar el costo máximo que puede ser utilizado sin degradar la experiencia del usuario. Se recomienda elegir el costo más alto posible sin ralentizar otras operaciones que la máquina debe ejecutar. 11 es una buena base, y un valor más alto es preferible si la máquina es suficientemente rápida. El código de abajo apunta a un tiempo de estiramiento ≤ 350 milisegundos, lo cual representa un retraso adecuado para sistemas que manejan conexiones interactivas.

    <?php
    $timeTarget = 0.350; // 350 milisegundos

    $cost = 11;
    do {
        $cost++;
        $start = microtime(true);
        password_hash("test", PASSWORD_BCRYPT, ["cost" => $cost]);
        $end = microtime(true);
    } while (($end - $start) < $timeTarget);

    echo "Valor de 'cost' más apropiado: " . $cost - 1;
    ?>

Resultado del ejemplo anterior es similar a:

    Valor de 'cost' más apropiado: 13

Ejemplo #4 Ejemplo con password_hash() y Argon2i

    <?php
    echo 'Argon2i hash: ' . password_hash('rasmuslerdorf', PASSWORD_ARGON2I);
    ?>

Resultado del ejemplo anterior es similar a:

    Argon2i hash: $argon2i$v=19$m=1024,t=2,p=2$YzJBSzV4TUhkMzc3d3laeg$zqU/1IN0/AogfP4cmSJI1vc8lpXRW9/S0sYY2i2jHT0

### Notas

Precaución

Se recomienda encarecidamente no proporcionar un salt explícito para esta función. Un salt seguro será generado automáticamente si no se especifica ningún salt.

Como se mencionó anteriormente, el uso de la opción `salt` a partir de PHP 7.0.0 generará una advertencia de deprecación. El soporte para un salt explícito fue eliminado a partir de PHP 8.0.0.

> Nota:

> Se recomienda probar esta función en la máquina utilizada y ajustar el/los parámetro(s) de costo para que la ejecución de la función tome menos de 350 milisegundos para conexiones interactivas. El script del ejemplo anterior ayudará a elegir un costo bcrypt adecuado para la máquina dada.

> Nota: La actualización de los algoritmos soportados por esta función (o el cambio al por omisión) debe seguir las siguientes reglas:

> - Cada nuevo algoritmo debe formar parte del núcleo de PHP durante al menos 1 versión completa antes de aspirar a convertirse en el algoritmo por omisión. También, si, por ejemplo, un nuevo algoritmo es añadido en la versión 7.5.5, no será elegible como algoritmo por omisión hasta PHP 7.7 (sabiendo que 7.6 será la primera versión completa). Pero si un algoritmo diferente ha sido añadido en 7.6.0, también será elegible como algoritmo por omisión a partir de la versión 7.7.0.
> - El algoritmo por omisión solo puede ser cambiado durante una versión completa (7.3.0, 8.0.0, etc...) y no durante una versión de revisión. La única excepción a este principio básico sería una emergencia, por ejemplo, al descubrir un bug crítico de seguridad en el algoritmo por omisión.

### Ver también

- password_verify() - Verifica que una contraseña coincide con un hash
- password_needs_rehash() - Verifica que el hash proporcionado cumple con el algoritmo y las opciones especificadas
- crypt() - Hash de un solo sentido (indescifrable)
- sodium_crypto_pwhash_str() - Devuelve un hash codificado en ASCII

# password_needs_rehash

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_needs_rehash — Verifica que el hash proporcionado cumple con el algoritmo y las opciones especificadas

### Descripción

function password_needs_rehash(string `$hash`, string|int|null `$algo`, array `$options` = []): bool

Esta función verifica que el hash proporcionado corresponde al algoritmo y a las opciones especificadas. Si no es así, el hash debería ser re-generado.

### Parámetros

`hash`

  Un hash creado por la función password_hash().

`algo`

  Una constante del algoritmo de contraseña que representa el algoritmo a utilizar durante el hasheo de la contraseña.

`options`

  Un array asociativo que contiene las opciones. Ver también las constantes del algoritmo de contraseña para la documentación sobre las opciones soportadas para cada algoritmo.

### Valores devueltos

Devuelve `true` si el hash debe ser re-generado para corresponder a los parámetros `algo` y `options` proporcionados, o `false` en caso contrario.

### Historial de cambios

Versión | Descripción
--- | ---
7.4.0 | El parámetro `algo` ahora espera una string, pero sigue aceptando un int para mantener la compatibilidad con versiones anteriores.

### Ejemplos

Ejemplo #1 Uso de password_needs_rehash()

    <?php

    $password = 'rasmuslerdorf';
    $hash = '$2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.';

    $algorithm = PASSWORD_BCRYPT;
    // El parámetro cost de bcrypt puede evolucionar con el tiempo según las mejoras de hardware.
    $options = ['cost' => 13];

    // Primero se verifica que la contraseña coincide con el hash almacenado
    if (password_verify($password, $hash)) {
        // Verifica si el algoritmo o las opciones han cambiado
        if (password_needs_rehash($hash, $algorithm, $options)) {
        if (password_needs_rehash($hash, PASSWORD_DEFAULT, $options)) {
            // Se crea un nuevo hash para actualizar el anterior
            $newHash = password_hash($password, $algorithm, $options);

            // Actualizar la entrada del usuario con $newHash
        }

        // Ejecutar el inicio de sesión del usuario
    }
    ?>

# password_verify

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_verify — Verifica que una contraseña coincide con un hash

### Descripción

function password_verify(#[\SensitiveParameter]string `$password`, string `$hash`): bool

Verifica que el hash proporcionado coincide con la contraseña proporcionada. La función password_verify() es compatible con la función crypt(). Por lo tanto, una contraseña hasheada por la función crypt() puede ser utilizada con la función password_verify().

Tenga en cuenta que la función password_hash() devuelve el algoritmo, el "cost", y el salt como partes del hash devuelto. Sin embargo, toda la información necesaria para verificar el hash está incluida. Esto permite a la función verificar el hash sin necesidad de almacenamiento separado para la información concerniente al algoritmo y al salt.

Esta función es segura contra ataques por tiempo.

### Parámetros

`password`

  La contraseña del usuario.

`hash`

  Un hash creado por la función password_hash().

### Valores devueltos

Devuelve `true` si la contraseña y el hash coinciden, o `false` en caso contrario.

### Ejemplos

Ejemplo #1 Ejemplo con password_verify()

Este es un ejemplo simplificado; se recomienda re-hashear una contraseña correcta si es necesario; ver la función password_needs_rehash() para un ejemplo.

    <?php
    // Ver el ejemplo proporcionado en la página de la función password_hash()
    // para saber de dónde proviene esto.
    $hash = '$2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.';

    if (password_verify('rasmuslerdorf', $hash)) {
        echo 'La contraseña es válida !';
    } else {
        echo 'La contraseña es inválida.';
    }
    ?>

El ejemplo anterior mostrará:

    La contraseña es válida !

### Ver también

- password_needs_rehash() - Verifica que el hash proporcionado cumple con el algoritmo y las opciones especificadas
- password_hash() - Crea una clave de hash para una contraseña
- sodium_crypto_pwhash_str_verify() - Verifica que una contraseña corresponde a un hash

## Tabla de contenidos

- password_algos — Obtiene todos los identificadores de los algoritmos de hash de contraseñas disponibles
- password_get_info — Devuelve información sobre el hash proporcionado
- password_hash — Crea una clave de hash para una contraseña
- password_needs_rehash — Verifica que el hash proporcionado cumple con el algoritmo y las opciones especificadas
- password_verify — Verifica que una contraseña coincide con un hash

- Instalación/Configuración
  - Requerimientos
  - Instalación
- Constantes predefinidas
- Funciones de hash de contraseñas
  - password_algos — Obtiene todos los identificadores de los algoritmos de hash de contraseñas disponibles
  - password_get_info — Devuelve información sobre el hash proporcionado
  - password_hash — Crea una clave de hash para una contraseña
  - password_needs_rehash — Verifica que el hash proporcionado cumple con el algoritmo y las opciones especificadas
  - password_verify — Verifica que una contraseña coincide con un hash

# Rnp

# Introducción

Advertencia

Esta extensión es EXPERIMENTAL. El comportamiento de esta extensión, los nombres de sus funciones, y toda la documentación alrededor de esta extensión puede cambiar sin previo aviso en una próxima versión de PHP. Esta extensión debe ser utilizada bajo su propio riesgo.

Este módulo permite utilizar la biblioteca » RNP. RNP es una biblioteca OpenPGP C++ de alto rendimiento utilizada por Mozilla Thunderbird.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación

## Requerimientos

Para utilizar las funciones de la biblioteca RNP, es necesario instalar la » biblioteca RNP. La versión de la biblioteca RNP debe ser >= 0.16.2.

## Instalación

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/rnp

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`RNP_KEYSTORE_GPG` (string)
  Formato del almacén de claves "GPG".
`RNP_KEYSTORE_KBX` (string)
  Formato del almacén de claves "KBX". Solo para claves públicas. Una caja de claves (keybox) es un formato de fichero utilizado para almacenar claves públicas con metadatos e índices.
`RNP_KEYSTORE_G10` (string)
  Formato del almacén de claves "G10". Para claves privadas.
`RNP_LOAD_SAVE_PUBLIC_KEYS` (integer)
  Carga o guarda solo las claves públicas. Puede ser combinado con `RNP_LOAD_SAVE_SECRET_KEYS` para cargar tanto las claves públicas como privadas en el contexto FFI o guardarlas del contexto.
`RNP_LOAD_SAVE_SECRET_KEYS` (integer)
  Carga o guarda solo las claves secretas. Puede ser combinado con `RNP_LOAD_SAVE_PUBLIC_KEYS` para cargar tanto las claves públicas como privadas en el contexto FFI o guardarlas del contexto.
`RNP_LOAD_SAVE_PERMISSIVE` (integer)
  Permite ignorar los paquetes de firma/clave/subclave incorrectos durante la importación de claves.
`RNP_LOAD_SAVE_SINGLE` (integer)
  Si se define, solo la primera clave será cargada.
`RNP_LOAD_SAVE_BASE64` (integer)
  Permite la importación de claves codificadas en base64 (claves autocrypt).
`RNP_FEATURE_SYMM_ALG` (string)
  Lista los algoritmos de cifrado simétrico disponibles.
`RNP_FEATURE_AEAD_ALG` (string)
  Lista los algoritmos AEAD disponibles.
`RNP_FEATURE_PROT_MODE` (string)
  Lista los modos de protección disponibles.
`RNP_FEATURE_PK_ALG` (string)
  Lista los algoritmos de clave pública disponibles.
`RNP_FEATURE_HASH_ALG` (string)
  Lista los algoritmos de hash disponibles.
`RNP_FEATURE_COMP_ALG` (string)
  Lista los algoritmos de compresión disponibles.
`RNP_FEATURE_CURVE` (string)
  Lista las curvas elípticas disponibles.
`RNP_DUMP_MPI` (integer)
  Muestra los valores MPI (enteros multi-precisión).
`RNP_DUMP_RAW` (integer)
  Muestra también el contenido sin tratar del paquete.
`RNP_DUMP_GRIP` (integer)
  Muestra las huellas y los identificadores de clave.
`RNP_JSON_DUMP_MPI` (integer)
  Muestra los valores MPI (enteros multi-precisión).
`RNP_JSON_DUMP_RAW` (integer)
  Muestra también el contenido sin tratar del paquete.
`RNP_JSON_DUMP_GRIP` (integer)
  Muestra las huellas y los identificadores de clave.
`RNP_ENCRYPT_NOWRAP` (integer)
  Permite el cifrado del mensaje firmado. El mensaje no está envuelto en un paquete de datos literales.
`RNP_KEY_EXPORT_ARMORED` (integer)
  Activa la armadura ASCII de los datos exportados.
`RNP_KEY_EXPORT_PUBLIC` (integer)
  Exporta la clave pública.
`RNP_KEY_EXPORT_SECRET` (integer)
  Exporta la clave secreta.
`RNP_KEY_EXPORT_SUBKEYS` (integer)
  Si la clave principal es exportada, todas las subclaves lo serán también.
`RNP_KEY_EXPORT_BASE64` (integer)
  Exporta la clave autocrypt codificada en base64 en lugar de binaria.
`RNP_KEY_REMOVE_PUBLIC` (integer)
  Elimina la clave pública.
`RNP_KEY_REMOVE_SECRET` (integer)
  Elimina la clave secreta.
`RNP_KEY_REMOVE_SUBKEYS` (integer)
  Si la clave principal es eliminada, todas las subclaves lo serán también.

# Ejemplos

## Tabla de contenidos

- Texto firmado en claro

## Texto firmado en claro

Este ejemplo va a firmar en claro un texto dado.

Ejemplo #1 Ejemplo de firma RNP en claro

    <?php
    // inicializa el objeto FFI
    $ffi = rnp_ffi_create('GPG', 'GPG');

    // genera una clave RSA
    $key = rnp_op_generate_key($ffi, 'test@example.com', 'RSA');

    // firma
    $data = "Example text to sign";
    $signature = rnp_op_sign_cleartext($ffi, $data, array($key));

    echo $signature;

    // destruye el objeto FFI
    rnp_ffi_destroy($ffi);
    ?>

# Funciones de Rnp

# rnp_backend_string

(PECL rnp >= 0.1.1)

rnp_backend_string — Devuelve el nombre de la biblioteca back-end de criptografía

### Descripción

function rnp_backend_string(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El nombre de la biblioteca back-end de criptografía. Las bibliotecas de criptografía soportadas son "Botan" y "OpenSSL".

# rnp_backend_version

(PECL rnp >= 0.1.1)

rnp_backend_version — Devuelve la versión de la biblioteca back-end de criptografía

### Descripción

function rnp_backend_version(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

La versión en forma de string.

# rnp_decrypt

(PECL rnp >= 0.1.1)

rnp_decrypt — Desencripta un mensaje PGP

### Descripción

function rnp_decrypt(RnpFFI `$ffi`, string `$input`): string|false

Las claves privadas utilizadas para el desencriptado deben ser cargadas en el objeto FFI antes de llamar a esta función. Si se ha utilizado el cifrado por contraseña, el proveedor de contraseña debe ser definido llamando a rnp_ffi_set_pass_provider().

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().
`input`
  El mensaje cifrado.

### Valores devueltos

El mensaje desencriptado en caso de éxito o `false` si ocurre un error.

# rnp_dump_packets

(PECL rnp >= 0.1.1)

rnp_dump_packets — Muestra la información del flujo de paquetes OpenPGP en un formato legible por el ser humano

### Descripción

function rnp_dump_packets(string `$input`, int `$flags`): string|false

### Parámetros

`input`
  La cadena de entrada que contiene los datos OpenPGP, ya sea en formato binario o en formato ASCII-armored.
`flags`
  Ver las constantes predefinidas `RNP_DUMP_*`.

### Valores devueltos

Un texto que describe la secuencia de paquetes o `false` si ocurre un error.

# rnp_dump_packets_to_json

(PECL rnp >= 0.1.1)

rnp_dump_packets_to_json — Muestra la información del flujo de paquetes OpenPGP en un string JSON

### Descripción

function rnp_dump_packets_to_json(string `$input`, int `$flags`): string|false

### Parámetros

`input`
  El string de entrada que contiene los datos OpenPGP, ya sea en formato binario o en formato ASCII-armored.
`flags`
  Ver las constantes predefinidas `RNP_JSON_DUMP_*`.

### Valores devueltos

Un string JSON con la información o `false` si ocurre un error

# rnp_ffi_create

(PECL rnp >= 0.1.1)

rnp_ffi_create — Crear un objeto de nivel superior utilizado para interactuar con la biblioteca

### Descripción

function rnp_ffi_create(string `$pub_format`, string `$sec_format`): RnpFFI|false

### Parámetros

`pub_format`
  El formato del llavero de claves públicas, RNP_KEYSTORE_GPG o otra constante RNP_KEYSTORE_*.
`sec_format`
  El formato del llavero de claves secretas, RNP_KEYSTORE_GPG o otra constante RNP_KEYSTORE_*.

### Valores devueltos

Devuelve un objeto RnpFFI en caso de éxito o `false` si ocurre un error.

# rnp_ffi_destroy

(PECL rnp >= 0.1.1)

rnp_ffi_destroy — Destruye el objeto de nivel superior utilizado para interactuar con la biblioteca

### Descripción

function rnp_ffi_destroy(RnpFFI `$ffi`): void

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().

### Valores devueltos

# rnp_ffi_set_pass_provider

(PECL rnp >= 0.1.1)

rnp_ffi_set_pass_provider — Define la función de retrollamada del proveedor de contraseña

### Descripción

function rnp_ffi_set_pass_provider(RnpFFI `$ffi`, callable `$password_callback`): bool

Define la función de retrollamada del proveedor de contraseña. Esta función puede solicitar la contraseña en una entrada estándar (si el script PHP se ejecuta en un entorno de línea de comandos), mostrar un cuadro de diálogo GUI o proporcionar la contraseña de todas las maneras posibles. Las contraseñas solicitadas se utilizan para cifrar o descifrar las claves secretas o realizar operaciones de cifrado/descifrado simétricas.

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().
`password_callback`

  La función que debe ser llamada para cada solicitud de contraseña. Tiene la siguiente firma:

  function password_callback(string `$key_fp`, string `$pgp_context`, string `&$password`): bool
  - `$key_fp` - La huella de la clave, si corresponde. Puede estar vacío.
  - `$pgp_context` - Cadena que describe por qué se solicita la clave.
  - `$password` - Referencia de cadena donde debe almacenarse la contraseña proporcionada.
  La función de retrollamada debe devolver `true` si la contraseña se ha establecido correctamente o `false` si ocurre un error.

### Valores devueltos

Devuelve `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de una función de retrollamada simple

    <?php
    function password_callback(string $key_fp, string $pgp_context, string &$password)
    {
        $password = "password";

        return true;
    }

    $ffi = rnp_ffi_create('GPG', 'GPG');

    rnp_ffi_set_pass_provider($ffi, 'password_callback');

# rnp_import_keys

(PECL rnp >= 0.1.1)

rnp_import_keys — Importa claves desde una string PHP hacia el llavero de claves y devuelve un JSON describiendo las claves nuevas o actualizadas

### Descripción

function rnp_import_keys(RnpFFI `$ffi`, string `$input`, int `$flags`): string|false

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().
`input`
  Los paquetes OpenPGP que contienen la o las claves a cargar. Puede ser binario o ASCII armored.
`flags`
  Ver las constantes predefinidas `RNP_LOAD_SAVE_*`.

### Valores devueltos

Una string JSON con la información sobre las claves nuevas y actualizadas en caso de éxito o `false` si ocurre un error.

# rnp_import_signatures

(PECL rnp >= 0.1.1)

rnp_import_signatures — Importa firmas autónomas en el llavero de claves y devuelve un JSON que describe las claves actualizadas

### Descripción

function rnp_import_signatures(RnpFFI `$ffi`, string `$input`, int `$flags`): string|false

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().
`input`
  Los paquetes OpenPGP que contienen las firmas a importar. Puede ser binario o ASCII armado.
`flags`
  Actualmente debe ser 0.

### Valores devueltos

La cadena JSON con información sobre las claves actualizadas en caso de éxito o `false` si ocurre un error.

# rnp_key_export

(PECL rnp >= 0.1.1)

rnp_key_export — Exporta una clave

### Descripción

function rnp_key_export(RnpFFI `$ffi`, string `$key_fp`, int `$flags`): string|false

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().
`key_fp`
  La huella de la clave.
`flags`
  Ver `RNP_KEY_EXPORT_*` constantes predefinidas (excepto `RNP_KEY_EXPORT_BASE64`).

### Valores devueltos

El paquete OpenPGP exportado de la clave (binario o ASCII-armored) en caso de éxito o `false` si ocurre un error.

# rnp_key_export_autocrypt

(PECL rnp >= 0.1.1)

rnp_key_export_autocrypt — Exporta la clave mínima para la funcionalidad autocrypt (solo 5 paquetes: clave, uid, firma, subclave de cifrado, firma)

### Descripción

function rnp_key_export_autocrypt(
RnpFFI `$ffi`,
string `$key_fp`,
string `$subkey_fp`,
string `$uid`,
int `$flags`
): string|false

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().
`key_fp`
  La huella de la clave primaria.
`subkey_fp`
  La subclave a exportar. Puede ser una string vacía para elegir la primera subclave apropiada.
`uid`
  El identificador del usuario a exportar. Puede ser una string vacía si la clave exportada solo tiene un identificador.
`flags`
  Solo `RNP_KEY_EXPORT_BASE64` es actualmente soportado. Activarlo exportará los datos de la clave codificados en base64 en lugar de binario.

### Valores devueltos

Los paquetes OpenPGP de la clave exportada en caso de éxito o `false` si ocurre un error.

# rnp_key_export_revocation

(PECL rnp >= 0.1.1)

rnp_key_export_revocation — Genera y exporta una firma de revocación de clave primaria

### Descripción

function rnp_key_export_revocation(
RnpFFI `$ffi`,
string `$key_fp`,
int `$flags`,
array `$options` = ?
): string|false

Notas: para revocar una clave, será necesario importar esta firma en el llavero de claves o utilizar la función rnp_key_revoke().

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().
`key_fp`
  La huella de la clave primaria a revocar.
`flags`
  `RNP_KEY_EXPORT_ARMORED` o 0.
`options`
  Un array asociativo con opciones.

  Clave | Tipo de datos | Descripción
  --- | --- | ---
  `"hash"` | string | Define el algoritmo de hash utilizado en el cálculo de la firma.
  `"code"` | string | Código de razón de la revocación. Valores posibles: 'no', 'superseded', 'compromised', 'retired'. Si no se define, se utilizará el valor 'no' por omisión.
  `"reason"` | string | Representación textual de la razón de la revocación.

### Valores devueltos

Revocación exportada en caso de éxito o `false` si ocurre un error.

# rnp_key_get_info

(PECL rnp >= 0.1.1)

rnp_key_get_info — Devuelve información sobre la clave

### Descripción

function rnp_key_get_info(RnpFFI `$ffi`, string `$key_fp`): array|false

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().
`key_fp`
  La huella de la clave.

### Valores devueltos

Un array asociativo con información sobre la clave o `false` si ocurre un error.

Clave | Tipo de datos | Descripción
--- | --- | ---
`"is_primary"` | boolean | `true` si esta clave es la clave primaria.
`"is_sub"` | boolean | `true` si esta clave es una subclave.
`"is_valid"` | boolean | `true` si la clave pública es válida. Esto incluye las verificaciones de auto-firmas, las fechas de expiración, las revocaciones, etc.
`"is_revoked"` | boolean | `true` si esta clave está revocada.
`"is_superseded"` | boolean | `true` si esta clave está obsoleta. Presente solo si la clave está revocada.
`"is_compromised"` | boolean | `true` si esta clave está comprometida. Presente solo si la clave está revocada.
`"is_retired"` | boolean | `true` si esta clave está retirada. Presente solo si la clave está revocada.
`"is_expired"` | boolean | `true` si esta clave está expirada.
`"have_secret"` | boolean | `true` si esta clave tiene una parte secreta.
`"is_locked"` | boolean | `true` si esta clave está actualmente bloqueada. Presente solo para claves secretas.
`"is_protected"` | boolean | `true` si esta clave está protegida. Presente solo para claves secretas. Una clave protegida es una clave que está cifrada y puede ser almacenada de manera segura en memoria y bloqueada/desbloqueada según sea necesario.
`"have_public"` | boolean | `true` si esta clave tiene una parte pública. En general, todas las claves tienen una parte pública.
`"valid_till"` | integer | El timestamp hasta el cual la clave puede ser considerada válida. Nota: esto tendrá en cuenta no solo la expiración de la clave, sino también las revocaciones. Para la subclave primaria, el tiempo de validez de la clave pública también será verificado.
`"bits"` | integer | El número de bits en la clave. Para las claves basadas en EC, esto contendrá el tamaño de la curva.
`"alg"` | string | El algoritmo de nombre de clave.
`"subkeys"` | array | Un array indexado que contiene información sobre las subclaves. Puede estar vacío si la clave primaria no tiene subclaves.
`"uids"` | array | Un array indexado que contiene información sobre los identificadores de usuario. Puede estar vacío si la clave primaria no tiene identificadores de usuario.

# rnp_key_remove

(PECL rnp >= 0.1.1)

rnp_key_remove — Elimina una clave de los llaveros

### Descripción

function rnp_key_remove(RnpFFI `$ffi`, string `$key_fp`, int `$flags`): bool

Nota: es necesario llamar a rnp_save_keys() para escribir los llaveros actualizados.

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().
`key_fp`
  La huella de la clave.
`flags`
  Ver `RNP_KEY_REMOVE_*` constantes predefinidas. El flag `RNP_KEY_REMOVE_SUBKEYS` solo funcionará para la clave principal y eliminará también todas sus subclaves.

### Valores devueltos

Devuelve `true` en caso de éxito o `false` si ocurre un error.

# rnp_key_revoke

(PECL rnp >= 0.1.1)

rnp_key_revoke — Elimina una clave o una subclave generando y añadiendo una firma de revocación

### Descripción

function rnp_key_revoke(
RnpFFI `$ffi`,
string `$key_fp`,
int `$flags`,
array `$options` = ?
): bool

Nota: es necesario llamar a rnp_save_keys() para escribir los ficheros de claves actualizados.

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().
`key_fp`
  La huella de la clave.
`flags`
  Actualmente debe ser 0.
`options`
  Un array asociativo con opciones.

  Clave | Tipo de datos | Descripción
  --- | --- | ---
  `"hash"` | string | Define el algoritmo de hash utilizado durante el cálculo de la firma.
  `"code"` | string | El código de revocación de la clave. Los valores posibles son 'no', 'superseded', 'compromised', 'retired'. Si no se define, se utilizará el valor 'no' por omisión.
  `"reason"` | string | Representación textual de la razón de la revocación.

### Valores devueltos

Devuelve `true` en caso de éxito o `false` si ocurre un error.

# rnp_list_keys

(PECL rnp >= 0.1.1)

rnp_list_keys — Enumera todas las claves presentes en un llavero de claves por tipo de identificador especificado

### Descripción

function rnp_list_keys(RnpFFI `$ffi`, string `$identifier_type`): array|false

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().
`identifier_type`
  La clave de tipo de identificador ("userid", "keyid", "grip", "fingerprint").

### Valores devueltos

Un array asociativo donde la clave es un string de identificador y el valor es una huella de clave PGP o `false` si ocurre un error.

# rnp_load_keys

(PECL rnp >= 0.1.1)

rnp_load_keys — Carga las claves a partir de un string PHP

### Descripción

function rnp_load_keys(
RnpFFI `$ffi`,
string `$format`,
string `$input`,
int `$flags`
): bool

Se debe tener en cuenta que para G10, la entrada debe ser un directorio (que ya debe existir).

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().
`format`
  El formato de clave para los datos (GPG, KBX, G10).
`input`
  Los paquetes OpenPGP que contienen la o las claves a cargar. Puede ser binario o ASCII armored.
`flags`
  Ver la descripción de los flags `RNP_LOAD_SAVE_*`.

### Valores devueltos

Devuelve `true` en caso de éxito o `false` si ocurre un error

# rnp_load_keys_from_path

(PECL rnp >= 0.1.1)

rnp_load_keys_from_path — Carga claves a partir de la ruta especificada

### Descripción

function rnp_load_keys_from_path(
RnpFFI `$ffi`,
string `$format`,
string `$input_path`,
int `$flags`
): bool

Es importante señalar que para G10, la entrada debe ser un directorio (que ya debe existir).

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().
`format`
  El formato de clave para los datos (GPG, KBX, G10).
`input_path`
  El fichero o directorio que contiene las claves.
`flags`
  Ver la descripción de los flags `RNP_LOAD_SAVE_*`.

### Valores devueltos

Devuelve `true` en caso de éxito o `false` si ocurre un error.

# rnp_locate_key

(PECL rnp >= 0.1.1)

rnp_locate_key — Búsqueda de la clave

### Descripción

function rnp_locate_key(RnpFFI `$ffi`, string `$identifier_type`, string `$identifier`): string|false

Nota: los identificadores válidos se verifican durante la búsqueda por identificador.

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().
`identifier_type`
  Cadena de tipo de identificador: "userid", "keyid", "fingerprint", "grip".
`identifier`
  El identificador del usuario OpenPGP (nombre y correo electrónico) para el tipo "userid", cadena hexadecimal que representa el identificador de clave, la huella digital o el grip de clave correspondiente.

### Valores devueltos

Devuelve la huella digital hexadecimal de la clave encontrada en caso de éxito o `false` si ocurre un error.

# rnp_op_encrypt

(PECL rnp >= 0.1.1)

rnp_op_encrypt — Cifra un mensaje

### Descripción

function rnp_op_encrypt(
RnpFFI `$ffi`,
string `$message`,
array `$recipient_keys_fp`,
array `$options` = ?
): string|false

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().
`message`
  El mensaje a cifrar.
`recipient_keys_fp`
  Un array con las huellas de las claves del destinatario. Al menos una clave debe estar presente.
`options`
  Un array asociativo con opciones.

  Clave | Tipo de dato | Descripción
  --- | --- | ---
  `"compression_alg"` | string | Algoritmo de compresión. Las opciones `"compression_alg"` y `"compression_level"` deben estar ambas definidas para activar la compresión de los datos.
  `"compression_level"` | integer | El nivel de compresión, de 0 a 9. 0 desactiva la compresión.
  `"armor"` | boolean | Activa la salida ASCII armada. Desactivada por omisión.
  `"add_signature"` | boolean | El mensaje cifrado será también firmado.
  `"hash"` | string | Define el algoritmo de hash utilizado en el cálculo de la firma. La opción "add_signature" debe estar definida a `true`.
  `"creation_time"` | integer | Define la hora de creación de la firma en segundos desde el 1 de enero de 1970 UTC. Por omisión, se utiliza la hora actual.
  `"expiration_time"` | integer | Define el tiempo de expiración de la firma en segundos desde la hora de creación. El valor 0 se utiliza para marcar la firma como no expirante (valor por omisión).
  `"password"` | string | Añade una contraseña utilizada para cifrar los datos.
  `"cipher"` | string | Define el algoritmo de cifrado simétrico. Los valores posibles son "IDEA", "TRIPLEDES", "CAST5", "BLOWFISH", "AES128", "AES192", "AES256", "TWOFISH", "CAMELLIA128", "CAMELLIA192", "CAMELLIA256", "SM4".
  `"aead"` | string | Define el algoritmo de modo AEAD. Los valores posibles son "None" para desactivar AEAD, "EAX", "OCB".
  `"aead_bits"` | integer | Define la longitud del chunk para el modo AEAD en número de bits de tamaño de chunk. Debe estar comprendido entre 0 y 56.
  `"flags"` | integer | Define indicadores de cifrado adicionales. Los indicadores soportados son: RNP_ENCRYPT_NOWRAP - no envolver los datos en un paquete de datos literales. Esto permitiría cifrar datos ya firmados.
  `"file_name"` | string | Define el nombre de fichero almacenado internamente para los datos cifrados. El valor especial _CONSOLE puede ser utilizado para marcar el mensaje como "para sus ojos solamente", es decir, que no debe ser almacenado en ningún lugar sino solo mostrado al destinatario. Por omisión, es una cadena vacía.
  `"file_mtime"` | integer | Define la fecha de modificación del fichero de entrada en segundos desde el 1 de enero de 1970 UTC.

### Valores devueltos

Los datos cifrados en caso de éxito o `false` si ocurre un error.

# rnp_op_generate_key

(PECL rnp >= 0.1.1)

rnp_op_generate_key — Genera una clave

### Descripción

function rnp_op_generate_key(
RnpFFI `$ffi`,
string `$userid`,
string `$key_alg`,
string `$sub_alg` = ?,
array `$options` = ?
): string|false

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().
`userid`
  El identificador del usuario PGP - texto que debe representar el nombre y la dirección de correo electrónico del titular de la clave.
`key_alg`
  La clave del algoritmo (es decir, 'RSA', 'DSA', etc).
`sub_alg`
  El algoritmo de subclave. Si no está definido, la subclave no será generada.
`options`
  Un array asociativo con opciones.

  Clave | Tipo de datos | Descripción
  --- | --- | ---
  `"bits"` | integer | El tamaño de la clave principal en bits. Aplicable únicamente a las claves RSA, DSA y El-Gamal.
  `"hash"` | string | Algoritmo de hash utilizado en la firma de la clave o la firma de ligadura de subclave.
  `"dsa_qbits"` | integer | Define el tamaño de un parámetro `q` para la clave DSA. Nota: se definirá un valor predeterminado adecuado, según el número de bits de la clave. Sin embargo, puede ser reemplazado si es necesario.
  `"curve"` | string | Define la curva utilizada para la clave ECC. Nota: esto se aplica únicamente a las claves ECDSA, ECDH y SM2.
  `"request_password"` | boolean | Activa la solicitud de contraseña a través del proveedor de contraseñas. Esta contraseña será utilizada para el cifrado de la clave. La función de retrollamada del proveedor de contraseñas debe ser definida previamente llamando a rnp_ffi_set_pass_provider(). Nota: este parámetro será ignorado si la contraseña ha sido definida a través de `"password"`
  `"password"` | string | Define la contraseña utilizada para cifrar los datos de la clave secreta.
  `"expiration"` | integer | Define el tiempo de expiración de la clave principal y la subclave en segundos.
  `"sub_bits"` | integer | El tamaño de la subclave en bits. Aplicable únicamente a las claves RSA, DSA y El-Gamal.
  `"sub_hash"` | string | Algoritmo de hash utilizado en la firma de la subclave o la firma de ligadura de subclave.
  `"sub_curve"` | string | Define la curva utilizada para la subclave ECC. Nota: esto se aplica únicamente a las claves ECDSA, ECDH y SM2.

### Valores devueltos

La huella de la clave principal generada o `false` si ocurre un error. Esta huella puede ser utilizada más tarde para referenciar la clave en las operaciones de firma y cifrado. Los datos de la clave se almacenan en el contexto de memoria FFI y pueden ser guardados utilizando rnp_save_keys() o rnp_save_keys_to_path().

# rnp_op_sign

(PECL rnp >= 0.1.1)

rnp_op_sign — Realiza una operación de firma sobre datos binarios, devuelve la o las firmas integradas

### Descripción

function rnp_op_sign(
RnpFFI `$ffi`,
string `$data`,
array `$keys_fp`,
array `$options` = ?
): string|false

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().
`data`
  Datos a firmar.
`keys_fp`
  Un array con las huellas de las claves. Al menos una clave debe ser proporcionada. Las claves deben estar presentes en `ffi`.
`options`
  Un array asociativo con opciones.

  Clave | Tipo de datos | Descripción
  --- | --- | ---
  `"compression_alg"` | string | Algoritmo de compresión. Las opciones `"compression_alg"` y `"compression_level"` deben ser ambas definidas para activar la compresión de datos.
  `"compression_level"` | integer | Nivel de compresión, 0-9. 0 desactiva la compresión.
  `"armor"` | boolean | Activa la salida ASCII armada. Desactivado por omisión.
  `"hash"` | string | Define el algoritmo de hash utilizado en el cálculo de la firma.
  `"creation_time"` | integer | Define la hora de creación de la firma en segundos desde el 1 de enero de 1970 UTC. Por omisión, se utiliza la hora actual.
  `"expiration_time"` | integer | Define el tiempo de expiración de la firma en segundos desde la hora de creación. El valor 0 se utiliza para marcar la firma como no expirante (valor por omisión).
  `"file_name"` | string | Define el nombre del fichero de entrada. El valor especial _CONSOLE puede ser utilizado para marcar el mensaje como 'para sus ojos solamente', es decir, que no debe ser almacenado en ningún lugar sino solo mostrado al destinatario. Por omisión, es una cadena vacía.
  `"file_mtime"` | integer | Define la fecha de modificación del fichero de entrada en segundos desde el 1 de enero de 1970 UTC.

### Valores devueltos

Los datos firmados con la(s) firma(s) integrada en caso de éxito o `false` si ocurre un error.

# rnp_op_sign_cleartext

(PECL rnp >= 0.1.1)

rnp_op_sign_cleartext — Realiza una operación de firma sobre datos textuales, devuelve el mensaje firmado en claro

### Descripción

function rnp_op_sign_cleartext(
RnpFFI `$ffi`,
string `$data`,
array `$keys_fp`,
array `$options` = ?
): string|false

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().
`data`
  Los datos a firmar.
`keys_fp`
  El array con las huellas de las claves. Al menos una clave debe ser proporcionada. Las claves deben estar presentes en `ffi`.
`options`
  Un array asociativo con opciones.

  Clave | Tipo de dato | Descripción
  --- | --- | ---
  `"armor"` | boolean | Activa la salida ASCII armada. Desactivado por omisión.
  `"hash"` | string | Define el algoritmo de hash utilizado durante el cálculo de la firma.
  `"creation_time"` | integer | Define la hora de creación de la firma en segundos desde el 1 de enero de 1970 UTC. Por omisión, se utiliza la hora actual.
  `"expiration_time"` | integer | Define el tiempo de expiración de la firma en segundos desde la hora de creación. El valor 0 se utiliza para marcar la firma como no expirada (valor por omisión).

### Valores devueltos

El mensaje firmado en claro que contiene los datos fuente con encabezados adicionales y la firma ASCII-armored en caso de éxito o `false` si ocurre un error.

# rnp_op_sign_detached

(PECL rnp >= 0.1.1)

rnp_op_sign_detached — Realiza una operación de firma, devuelve la firma desvinculada

### Descripción

function rnp_op_sign_detached(
RnpFFI `$ffi`,
string `$data`,
array `$keys_fp`,
array `$options` = ?
): string|false

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().
`data`
  Los datos a firmar.
`keys_fp`
  Un array con las huellas de las claves. Al menos una clave debe ser proporcionada. Las claves deben estar presentes en `ffi`.
`options`
  Un array asociativo con opciones.

  Clave | Tipo de dato | Descripción
  --- | --- | ---
  `"armor"` | boolean | Activa la salida ASCII-armored. Desactivado por omisión.
  `"hash"` | string | Define el algoritmo de hash utilizado durante el cálculo de la firma.
  `"creation_time"` | integer | Define la hora de creación de la firma en segundos desde el 1 de enero de 1970 UTC. Por omisión, se utiliza la hora actual.
  `"expiration_time"` | integer | Define el tiempo de expiración de la firma en segundos desde la hora de creación. El valor 0 se utiliza para marcar la firma como no expirada (valor por omisión).

### Valores devueltos

Los datos de firma(s) desvinculados en caso de éxito o `false` si ocurre un error.

# rnp_op_verify

(PECL rnp >= 0.1.1)

rnp_op_verify — Verifica las firmas integradas o en claro

### Descripción

function rnp_op_verify(RnpFFI `$ffi`, string `$data`): array|false

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().
`data`
  Los datos firmados.

### Valores devueltos

Un array asociativo con información sobre los resultados de la verificación o `false` si ocurre un error.

Clave | Tipo de datos | Descripción
--- | --- | ---
`"verification_status"` | string | Resultados de la verificación global, ya sea la cadena "Success" o un mensaje de error apropiado. El resultado "Success" se define cuando al menos una firma es válida y se verifica con éxito. El resultado de la verificación individual para cada firma puede ser verificado en el array "signatures".
`"file_name"` | string | El nombre del fichero.
`"file_mtime"` | integer | Hora de modificación del fichero.
`"mode"` | string | Modo de protección de los datos (cifrado) utilizado en el mensaje procesado. Los valores actualmente definidos son "none", "cfb", "cfb-mdc", "aead-ocb", "aead-eax".
`"cipher"` | string | Cifrado simétrico utilizado para el cifrado de los datos.
`"valid_integrity"` | boolean | `true` si la protección de la integridad del mensaje ha sido utilizada (es decir, MDC o AEAD) y ha sido validada con éxito.
`"signatures"` | array | Un array asociativo que describe cada firma encontrada. Ver la descripción a continuación.

El subarray "signatures".

Clave | Tipo de datos | Descripción
--- | --- | ---
"verification_status" | string | Estado de verificación de la firma, ya sea la cadena "Success" o un mensaje de error apropiado.
"creation_time" | integer | Hora de creación de la firma en segundos desde el 1 de enero de 1970 UTC.
"expiration_time" | integer | El tiempo de expiración de la firma en segundos desde el tiempo de creación o 0 si la firma no expira nunca.
"hash" | string | Algoritmo de hash utilizado para calcular la firma.
"signing_key" | string | La huella de la clave utilizada para firmar. Puede ser "Not found" si la clave pública correspondiente no está cargada en el objeto FFI.
"signature_type" | string | El tipo de firma. Los valores actualmente definidos son "binary", "text", "standalone", "certification (generic)", "certification (persona)", "certification (casual)", "certification (positive)", "subkey binding", "primary key binding", "direct", "key revocation", "subkey revocation", "certification revocation", "timestamp", "uknown: 0..255".

# rnp_op_verify_detached

(PECL rnp >= 0.1.1)

rnp_op_verify_detached — Verifica las firmas desvinculadas

### Descripción

function rnp_op_verify_detached(RnpFFI `$ffi`, string `$data`, string `$signature`): array|false

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().
`data`
  Los datos fuente.
`signature`
  Los datos de firma desvinculada.

### Valores devueltos

Un array asociativo con información sobre los resultados de la verificación o `false` si ocurre un error.

Clave | Tipo de datos | Descripción
--- | --- | ---
`"verification_status"` | string | Los resultados de la verificación global, ya sea la cadena "Success" o un mensaje de error apropiado. El resultado "Success" se define cuando al menos una firma es válida y verificada con éxito. Los resultados de verificación individuales para cada firma pueden ser verificados en el array "signatures".
`"file_name"` | string | Nombre del fichero.
`"file_mtime"` | integer | Hora de modificación del fichero.
`"mode"` | string | Modo de protección de los datos (cifrado) utilizado en el mensaje procesado. Los valores actualmente definidos son "none", "cfb", "cfb-mdc", "aead-ocb", "aead-eax".
`"cipher"` | string | Algoritmo de cifrado simétrico utilizado para el cifrado de los datos.
`"valid_integrity"` | boolean | `true` si la protección de la integridad del mensaje ha sido utilizada (es decir, MDC o AEAD) y ha sido validada con éxito.
`"signatures"` | array | Un array asociativo que describe cada firma encontrada. Ver la descripción a continuación.

Un subarray "signatures".

Clave | Tipo de datos | Descripción
--- | --- | ---
"verification_status" | string | Estado de verificación de la firma, ya sea la cadena "Success" o un mensaje de error apropiado.
"creation_time" | integer | Hora de creación de la firma en segundos desde el 1 de enero de 1970 UTC.
"expiration_time" | integer | Tiempo de expiración de la firma en segundos desde la hora de creación o 0 si la firma no expira nunca.
"hash" | string | Algoritmo de hash utilizado para calcular la firma.
"signing_key" | string | La huella de la clave utilizada para firmar. Puede ser "Not found" si la clave pública correspondiente no está cargada en el objeto FFI.
"signature_type" | string | El tipo de firma. Los valores actualmente definidos son "binary", "text", "standalone", "certification (generic)", "certification (persona)", "certification (casual)", "certification (positive)", "subkey binding", "primary key binding", "direct", "key revocation", "subkey revocation", "certification revocation", "timestamp", "unknown: 0..255".

# rnp_save_keys

(PECL rnp >= 0.1.1)

rnp_save_keys — Guarda las claves en una string PHP

### Descripción

function rnp_save_keys(
RnpFFI `$ffi`,
string `$format`,
string `&$output`,
int `$flags`
): bool

Se debe tener en cuenta que para G10, la salida debe ser un directorio (que ya debe existir).

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().
`format`
  El formato de clave para los datos (GPG, KBX, G10).
`output`
  Los paquetes de claves se guardarán en la string referenciada por `output`.
`flags`
  Ver la descripción de los flags `RNP_LOAD_SAVE_*`.

### Valores devueltos

Devuelve `true` en caso de éxito o `false` si ocurre un error.

# rnp_save_keys_to_path

(PECL rnp >= 0.1.1)

rnp_save_keys_to_path — Guarda las claves en la ruta especificada

### Descripción

function rnp_save_keys_to_path(
RnpFFI `$ffi`,
string `$format`,
string `$output_path`,
int `$flags`
): bool

Guarda las claves presentes en el objeto FFI (cargadas o generadas) en el fichero o directorio especificado.

### Parámetros

`ffi`
  El objeto FFI retornado por rnp_ffi_create().
`format`
  El formato de clave para los datos (GPG, KBX, G10).
`output_path`
  La ruta del fichero o directorio donde las claves deben ser guardadas.
`flags`
  Ver la descripción de los flags `RNP_LOAD_SAVE_*`.

### Valores devueltos

Devuelve `true` en caso de éxito o `false` si ocurre un error.

# rnp_supported_features

(PECL rnp >= 0.1.1)

rnp_supported_features — Devuelve las funcionalidades soportadas en formato JSON

### Descripción

function rnp_supported_features(string `$type`): string|false

Devuelve el formato JSON que contiene un array de los valores de funcionalidades rnp soportadas (algoritmos, curvas, etc.) por tipo.

### Parámetros

`type`
  Ver las constantes RNP_FEATURE_* para los valores soportados.

### Valores devueltos

Un string que contiene un array formateado en JSON de los algoritmos, curvas, etc. soportados o `false` si ocurre un error.

# rnp_version_string

(PECL rnp >= 0.1.1)

rnp_version_string — La versión de la biblioteca RNP

### Descripción

function rnp_version_string(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el string de versión de la biblioteca RNP.

# rnp_version_string_full

(PECL rnp >= 0.1.1)

rnp_version_string_full — La cadena de versión completa de la biblioteca RNP

### Descripción

function rnp_version_string_full(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la cadena de versión completa de la biblioteca RNP.

## Tabla de contenidos

- rnp_backend_string — Devuelve el nombre de la biblioteca back-end de criptografía
- rnp_backend_version — Devuelve la versión de la biblioteca back-end de criptografía
- rnp_decrypt — Desencripta un mensaje PGP
- rnp_dump_packets — Muestra la información del flujo de paquetes OpenPGP en un formato legible por el ser humano
- rnp_dump_packets_to_json — Muestra la información del flujo de paquetes OpenPGP en un string JSON
- rnp_ffi_create — Crear un objeto de nivel superior utilizado para interactuar con la biblioteca
- rnp_ffi_destroy — Destruye el objeto de nivel superior utilizado para interactuar con la biblioteca
- rnp_ffi_set_pass_provider — Define la función de retrollamada del proveedor de contraseña
- rnp_import_keys — Importa claves desde una string PHP hacia el llavero de claves y devuelve un JSON describiendo las claves nuevas o actualizadas
- rnp_import_signatures — Importa firmas autónomas en el llavero de claves y devuelve un JSON que describe las claves actualizadas
- rnp_key_export — Exporta una clave
- rnp_key_export_autocrypt — Exporta la clave mínima para la funcionalidad autocrypt (solo 5 paquetes: clave, uid, firma, subclave de cifrado, firma)
- rnp_key_export_revocation — Genera y exporta una firma de revocación de clave primaria
- rnp_key_get_info — Devuelve información sobre la clave
- rnp_key_remove — Elimina una clave de los llaveros
- rnp_key_revoke — Elimina una clave o una subclave generando y añadiendo una firma de revocación
- rnp_list_keys — Enumera todas las claves presentes en un llavero de claves por tipo de identificador especificado
- rnp_load_keys — Carga las claves a partir de un string PHP
- rnp_load_keys_from_path — Carga claves a partir de la ruta especificada
- rnp_locate_key — Búsqueda de la clave
- rnp_op_encrypt — Cifra un mensaje
- rnp_op_generate_key — Genera una clave
- rnp_op_sign — Realiza una operación de firma sobre datos binarios, devuelve la o las firmas integradas
- rnp_op_sign_cleartext — Realiza una operación de firma sobre datos textuales, devuelve el mensaje firmado en claro
- rnp_op_sign_detached — Realiza una operación de firma, devuelve la firma desvinculada
- rnp_op_verify — Verifica las firmas integradas o en claro
- rnp_op_verify_detached — Verifica las firmas desvinculadas
- rnp_save_keys — Guarda las claves en una string PHP
- rnp_save_keys_to_path — Guarda las claves en la ruta especificada
- rnp_supported_features — Devuelve las funcionalidades soportadas en formato JSON
- rnp_version_string — La versión de la biblioteca RNP
- rnp_version_string_full — La cadena de versión completa de la biblioteca RNP

# La clase RnpFFI

(PECL rnp >= 0.1.1)

## Introducción

## Sinopsis de la Clase

class RnpFFI {
}

- Instalación/Configuración
  - Requerimientos
  - Instalación
- Constantes predefinidas
- Ejemplos
  - Texto firmado en claro
- Funciones de Rnp
  - rnp_backend_string — Devuelve el nombre de la biblioteca back-end de criptografía
  - rnp_backend_version — Devuelve la versión de la biblioteca back-end de criptografía
  - rnp_decrypt — Desencripta un mensaje PGP
  - rnp_dump_packets — Muestra la información del flujo de paquetes OpenPGP en un formato legible por el ser humano
  - rnp_dump_packets_to_json — Muestra la información del flujo de paquetes OpenPGP en un string JSON
  - rnp_ffi_create — Crear un objeto de nivel superior utilizado para interactuar con la biblioteca
  - rnp_ffi_destroy — Destruye el objeto de nivel superior utilizado para interactuar con la biblioteca
  - rnp_ffi_set_pass_provider — Define la función de retrollamada del proveedor de contraseña
  - rnp_import_keys — Importa claves desde una string PHP hacia el llavero de claves y devuelve un JSON describiendo las claves nuevas o actualizadas
  - rnp_import_signatures — Importa firmas autónomas en el llavero de claves y devuelve un JSON que describe las claves actualizadas
  - rnp_key_export — Exporta una clave
  - rnp_key_export_autocrypt — Exporta la clave mínima para la funcionalidad autocrypt (solo 5 paquetes: clave, uid, firma, subclave de cifrado, firma)
  - rnp_key_export_revocation — Genera y exporta una firma de revocación de clave primaria
  - rnp_key_get_info — Devuelve información sobre la clave
  - rnp_key_remove — Elimina una clave de los llaveros
  - rnp_key_revoke — Elimina una clave o una subclave generando y añadiendo una firma de revocación
  - rnp_list_keys — Enumera todas las claves presentes en un llavero de claves por tipo de identificador especificado
  - rnp_load_keys — Carga las claves a partir de un string PHP
  - rnp_load_keys_from_path — Carga claves a partir de la ruta especificada
  - rnp_locate_key — Búsqueda de la clave
  - rnp_op_encrypt — Cifra un mensaje
  - rnp_op_generate_key — Genera una clave
  - rnp_op_sign — Realiza una operación de firma sobre datos binarios, devuelve la o las firmas integradas
  - rnp_op_sign_cleartext — Realiza una operación de firma sobre datos textuales, devuelve el mensaje firmado en claro
  - rnp_op_sign_detached — Realiza una operación de firma, devuelve la firma desvinculada
  - rnp_op_verify — Verifica las firmas integradas o en claro
  - rnp_op_verify_detached — Verifica las firmas desvinculadas
  - rnp_save_keys — Guarda las claves en una string PHP
  - rnp_save_keys_to_path — Guarda las claves en la ruta especificada
  - rnp_supported_features — Devuelve las funcionalidades soportadas en formato JSON
  - rnp_version_string — La versión de la biblioteca RNP
  - rnp_version_string_full — La cadena de versión completa de la biblioteca RNP
- RnpFFI — La clase RnpFFI

# Sodium

# Introducción

Sodium es una biblioteca moderna y fácil de usar para el cifrado, descifrado, firmas y hashing de contraseñas, entre otros. Su objetivo es proporcionar todas las operaciones básicas necesarias para la construcción de herramientas criptográficas de nivel superior.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación

## Requerimientos

Esta extensión requiere » libsodium ≥ 1.0.8.

## Instalación

A partir de PHP 7.2.0 esta extensión se proporciona con PHP. Para las versiones de PHP más antiguas esta extensión está disponible a través de PECL.

## Sistemas Linux

Para poder utilizar esta extensión se debe compilar PHP con el soporte de sodium utilizando la opción de configuración --with-sodium[=DIR].

## Windows

Para poder utilizar esta extensión se debe añadir `extension=php_sodium.dll` al php.ini.

## Instalación a través de PECL

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/libsodium

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`SODIUM_LIBRARY_VERSION` (string)
`SODIUM_LIBRARY_MAJOR_VERSION` (int)
`SODIUM_LIBRARY_MINOR_VERSION` (int)
`SODIUM_BASE64_VARIANT_ORIGINAL` (int)
`SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING` (int)
`SODIUM_BASE64_VARIANT_URLSAFE` (int)
`SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING` (int)
`SODIUM_CRYPTO_AEAD_AEGIS128L_KEYBYTES` (int)
  Disponible a partir de PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS128L_NSECBYTES` (int)
  Disponible a partir de PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS128L_NPUBBYTES` (int)
  Disponible a partir de PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS128L_ABYTES` (int)
  Disponible a partir de PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_KEYBYTES` (int)
  Disponible a partir de PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_NSECBYTES` (int)
  Disponible a partir de PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_NPUBBYTES` (int)
  Disponible a partir de PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_ABYTES` (int)
  Disponible a partir de PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AES256GCM_KEYBYTES` (int)
`SODIUM_CRYPTO_AEAD_AES256GCM_NSECBYTES` (int)
`SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES` (int)
`SODIUM_CRYPTO_AEAD_AES256GCM_ABYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_KEYBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NSECBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NPUBBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_ABYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_KEYBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NSECBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NPUBBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_ABYTES` (int)
`SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_ABYTES` (int)
`SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_KEYBYTES` (int)
`SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES` (int)
`SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NSECBYTES` (int)
`SODIUM_CRYPTO_AUTH_BYTES` (int)
`SODIUM_CRYPTO_AUTH_KEYBYTES` (int)
`SODIUM_CRYPTO_BOX_SEALBYTES` (int)
`SODIUM_CRYPTO_BOX_SECRETKEYBYTES` (int)
`SODIUM_CRYPTO_BOX_PUBLICKEYBYTES` (int)
`SODIUM_CRYPTO_BOX_KEYPAIRBYTES` (int)
`SODIUM_CRYPTO_BOX_MACBYTES` (int)
`SODIUM_CRYPTO_BOX_NONCEBYTES` (int)
`SODIUM_CRYPTO_BOX_SEEDBYTES` (int)
`SODIUM_CRYPTO_KDF_BYTES_MIN` (int)
`SODIUM_CRYPTO_KDF_BYTES_MAX` (int)
`SODIUM_CRYPTO_KDF_CONTEXTBYTES` (int)
`SODIUM_CRYPTO_KDF_KEYBYTES` (int)
`SODIUM_CRYPTO_KX_SEEDBYTES` (int)
`SODIUM_CRYPTO_KX_SESSIONKEYBYTES` (int)
`SODIUM_CRYPTO_KX_PUBLICKEYBYTES` (int)
`SODIUM_CRYPTO_KX_SECRETKEYBYTES` (int)
`SODIUM_CRYPTO_KX_KEYPAIRBYTES` (int)
`SODIUM_CRYPTO_GENERICHASH_BYTES` (int)
`SODIUM_CRYPTO_GENERICHASH_BYTES_MIN` (int)
`SODIUM_CRYPTO_GENERICHASH_BYTES_MAX` (int)
`SODIUM_CRYPTO_GENERICHASH_KEYBYTES` (int)
`SODIUM_CRYPTO_GENERICHASH_KEYBYTES_MIN` (int)
`SODIUM_CRYPTO_GENERICHASH_KEYBYTES_MAX` (int)
`SODIUM_CRYPTO_PWHASH_ALG_ARGON2I13` (int)
`SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13` (int)
`SODIUM_CRYPTO_PWHASH_ALG_DEFAULT` (int)
`SODIUM_CRYPTO_PWHASH_SALTBYTES` (int)
`SODIUM_CRYPTO_PWHASH_STRPREFIX` (int)
`SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE` (int)
`SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE` (int)
`SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE` (int)
`SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE` (int)
`SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE` (int)
`SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_SALTBYTES` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_STRPREFIX` (string)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_SENSITIVE` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_SENSITIVE` (int)
`SODIUM_CRYPTO_CORE_RISTRETTO255_BYTES` (int)
  Disponible a partir de PHP 8.1.0.
`SODIUM_CRYPTO_CORE_RISTRETTO255_HASHBYTES` (int)
  Disponible a partir de PHP 8.1.0.
`SODIUM_CRYPTO_CORE_RISTRETTO255_NONREDUCEDSCALARBYTES` (int)
  Disponible a partir de PHP 8.1.0.
`SODIUM_CRYPTO_CORE_RISTRETTO255_SCALARBYTES` (int)
  Disponible a partir de PHP 8.1.0.
`SODIUM_CRYPTO_SCALARMULT_BYTES` (int)
`SODIUM_CRYPTO_SCALARMULT_SCALARBYTES` (int)
`SODIUM_CRYPTO_SCALARMULT_RISTRETTO255_BYTES` (int)
  Disponible a partir de PHP 8.1.0.
`SODIUM_CRYPTO_SCALARMULT_RISTRETTO255_SCALARBYTES` (int)
  Disponible a partir de PHP 8.1.0.
`SODIUM_CRYPTO_SHORTHASH_BYTES` (int)
`SODIUM_CRYPTO_SHORTHASH_KEYBYTES` (int)
`SODIUM_CRYPTO_SECRETBOX_KEYBYTES` (int)
`SODIUM_CRYPTO_SECRETBOX_MACBYTES` (int)
`SODIUM_CRYPTO_SECRETBOX_NONCEBYTES` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_ABYTES` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_HEADERBYTES` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_KEYBYTES` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_MESSAGEBYTES_MAX` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_PUSH` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_REKEY` (int)
`SODIUM_CRYPTO_SIGN_BYTES` (int)
`SODIUM_CRYPTO_SIGN_SEEDBYTES` (int)
`SODIUM_CRYPTO_SIGN_PUBLICKEYBYTES` (int)
`SODIUM_CRYPTO_SIGN_SECRETKEYBYTES` (int)
`SODIUM_CRYPTO_SIGN_KEYPAIRBYTES` (int)
`SODIUM_CRYPTO_STREAM_NONCEBYTES` (int)
`SODIUM_CRYPTO_STREAM_KEYBYTES` (int)
`SODIUM_CRYPTO_STREAM_XCHACHA20_KEYBYTES` (int)
  Disponible a partir de PHP 8.1.0.
`SODIUM_CRYPTO_STREAM_XCHACHA20_NONCEBYTES` (int)
  Disponible a partir de PHP 8.1.0.

# Sodium Funciones

# sodium_add

(PHP 7 >= 7.2.0, PHP 8)

sodium_add — Suma grandes números

### Descripción

function sodium_add(string `&$string1`, string `$string2`): void

Esto suma el argumento `string2` a `string1`, sobrescribiendo el valor almacenado en `string1`. Esta función asume que ambos argumentos son strings binarios que representan enteros sin signo en bytes de orden bajo.

### Parámetros

`string1`
  El string que representa un entero sin signo de longitud arbitraria en bytes de orden bajo. Este argumento se pasa por referencia y contendrá la suma de ambos argumentos.
`string2`
  El string que representa un entero sin signo de longitud arbitraria en bytes de orden bajo.

### Valores devueltos

No se retorna ningún valor.

# sodium_base642bin

(PHP 7 >= 7.2.0, PHP 8)

sodium_base642bin — Decodifica una cadena codificada en base64 en binario sin tratar.

### Descripción

function sodium_base642bin(#[\SensitiveParameter]string `$string`, int `$id`, string `$ignore` = ""): string

Convierte una cadena codificada en base64 en binario sin tratar. A diferencia de base64_decode(), sodium_base642bin() es de tiempo constante (una propiedad importante para cualquier código que manipule entradas criptográficas, tales como textos en claro o claves) y soporta múltiples conjuntos de caracteres.

### Parámetros

`string`
  string; Cadena codificada.
`id`
  - `SODIUM_BASE64_VARIANT_ORIGINAL` para el estándar (`A-Za-z0-9/\+`) codificado en base64.
  - `SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING` para el estándar (`A-Za-z0-9/\+`) codificado en base64, sin caracteres de relleno `=`.
  - `SODIUM_BASE64_VARIANT_URLSAFE` para la codificación Base64 segura para URL (`A-Za-z0-9\-_`).
  - `SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING` para la codificación Base64 segura para URL (`A-Za-z0-9\-_`), sin caracteres de relleno `=`.
`ignore`
  Los caracteres a ignorar durante la decodificación (por ejemplo, los caracteres de espaciado).

### Valores devueltos

La cadena decodificada.

# sodium_bin2base64

(PHP 7 >= 7.2.0, PHP 8)

sodium_bin2base64 — Codifica una string binaria bruta en base64.

### Descripción

function sodium_bin2base64(#[\SensitiveParameter]string `$string`, int `$id`): string

Convierte una string binaria bruta en una string codificada en base64. A diferencia de base64_encode(), sodium_bin2base64() es de tiempo constante (una propiedad importante para cualquier código que manipule entradas criptográficas, como textos en claro o claves) y admite varios conjuntos de caracteres.

### Parámetros

`string`
  La string binaria bruta.
`id`
  - `SODIUM_BASE64_VARIANT_ORIGINAL` para el estándar (`A-Za-z0-9/\+`) codificado en base64.
  - `SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING` para el estándar (`A-Za-z0-9/\+`) codificado en base64, sin caracteres de relleno `=`.
  - `SODIUM_BASE64_VARIANT_URLSAFE` para la codificación Base64 segura para URL (`A-Za-z0-9\-_`).
  - `SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING` para la codificación Base64 segura para URL (`A-Za-z0-9\-_`), sin caracteres de relleno `=`.

### Valores devueltos

La string codificada en base64.

# sodium_bin2hex

(PHP 7 >= 7.2.0, PHP 8)

sodium_bin2hex — Codificar en hexadecimal

### Descripción

function sodium_bin2hex(#[\SensitiveParameter]string `$string`): string

Convierte una cadena binaria bruta en una cadena codificada en hexadecimal. A diferencia de la función de codificación hexadecimal estándar, sodium_bin2hex() es de tiempo constante (una propiedad importante para cualquier código que manipule entradas criptográficas, como textos sin formato o claves).

### Parámetros

`string`
  Una cadena binaria bruta.

### Valores devueltos

Una cadena codificada en hexadecimal.

# sodium_compare

(PHP 7 >= 7.2.0, PHP 8)

sodium_compare — Comparar grandes números

### Descripción

function sodium_compare(#[\SensitiveParameter]string `$string1`, #[\SensitiveParameter]string `$string2`): int

Compara dos strings como si fueran enteros no signados de longitud arbitraria, en bytes de orden bajo, sin fuga de canal secundario.

### Parámetros

`string1`
  Operando izquierdo
`string2`
  Operando derecho

### Valores devueltos

Devuelve `-1` si `string1` es más pequeño que `string2`.

Devuelve `1` si `string1` es más grande que `string2`.

Devuelve `0` si las dos strings son iguales.

# sodium_crypto_aead_aegis128l_decrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis128l_decrypt — Verifica y luego descifra un mensaje con AEGIS-128L

### Descripción

function sodium_crypto_aead_aegis128l_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Verifica y luego descifra un mensaje con AEGIS-128L.

### Parámetros

`ciphertext`
  Debe estar en el formato proporcionado por sodium_crypto_aead_aegis128l_encrypt().
`additional_data`
  Además, datos autenticados. Esto se utiliza en la verificación de la etiqueta de autenticación añadida al texto cifrado, pero no se cifra ni se almacena en el texto cifrado.
`nonce`
  Un número que debe ser utilizado una sola vez, por mensaje.
`key`
  La clave de cifrado (128 bits).

### Valores devueltos

Devuelve el texto en claro en caso de éxito, o `false` si ocurre un error.

### Ver también

- sodium_crypto_aead_aegis128l_encrypt() - Cifra y autentica un mensaje con AEGIS-128L
- sodium_crypto_aead_aegis128l_keygen() - Genera una clave AEGIS-128L aleatoria

# sodium_crypto_aead_aegis128l_encrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis128l_encrypt — Cifra y autentica un mensaje con AEGIS-128L

### Descripción

function sodium_crypto_aead_aegis128l_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Cifra y autentica un mensaje con AEGIS-128L.

### Parámetros

`message`
  El mensaje en claro a cifrar.
`additional_data`
  Datos adicionales autenticados. Esto se utiliza en la verificación de la etiqueta de autenticación añadida al texto cifrado, pero no se cifra ni se almacena en el texto cifrado.
`nonce`
  Un número que debe ser utilizado una sola vez, por mensaje.
`key`
  La clave de cifrado (128 bits).

### Valores devueltos

Devuelve el texto cifrado y la etiqueta de autenticación como una cadena de bytes en bruto.

### Ver también

- sodium_crypto_aead_aegis128l_decrypt() - Verifica y luego descifra un mensaje con AEGIS-128L
- sodium_crypto_aead_aegis128l_keygen() - Genera una clave AEGIS-128L aleatoria

# sodium_crypto_aead_aegis128l_keygen

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis128l_keygen — Genera una clave AEGIS-128L aleatoria

### Descripción

function sodium_crypto_aead_aegis128l_keygen(): string

Genera una clave aleatoria de 128 bits para ser utilizada con sodium_crypto_aead_aegis128l_encrypt() y sodium_crypto_aead_aegis128l_decrypt().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una clave aleatoria de 128 bits.

### Ver también

- sodium_crypto_aead_aegis128l_decrypt() - Verifica y luego descifra un mensaje con AEGIS-128L
- sodium_crypto_aead_aegis128l_encrypt() - Cifra y autentica un mensaje con AEGIS-128L

# sodium_crypto_aead_aegis256_decrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis256_decrypt — Verifica y luego descifra un mensaje con AEGIS-256

### Descripción

function sodium_crypto_aead_aegis256_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Verifica y luego descifra un mensaje con AEGIS-256.

### Parámetros

`ciphertext`
  Debe estar en el formato proporcionado por sodium_crypto_aead_aegis256_encrypt().
`additional_data`
  Además, datos autenticados. Esto se utiliza en la verificación de la etiqueta de autenticación añadida al texto cifrado, pero no se cifra ni se almacena en el texto cifrado.
`nonce`
  Un número que debe ser utilizado una sola vez, por mensaje.
`key`
  La clave de cifrado (256 bits).

### Valores devueltos

Devuelve el texto en claro en caso de éxito, o `false` si ocurre un error.

### Ver también

- sodium_crypto_aead_aegis256_encrypt() - Cifra y autentica un mensaje con AEGIS-256
- sodium_crypto_aead_aegis256_keygen() - Genera una clave AEGIS-256 aleatoria

# sodium_crypto_aead_aegis256_encrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis256_encrypt — Cifra y autentica un mensaje con AEGIS-256

### Descripción

function sodium_crypto_aead_aegis256_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Cifra y autentica un mensaje con AEGIS-256.

### Parámetros

`message`
  El mensaje en claro a cifrar.
`additional_data`
  Datos adicionales autenticados. Esto se utiliza en la verificación de la etiqueta de autenticación añadida al texto cifrado, pero no se cifra ni se almacena en el texto cifrado.
`nonce`
  Un número que debe ser utilizado una sola vez, por mensaje.
`key`
  La clave de cifrado (256 bits).

### Valores devueltos

Devuelve el texto cifrado y la etiqueta de autenticación en forma de cadena de octetos sin tratar.

### Ver también

- sodium_crypto_aead_aegis256_decrypt() - Verifica y luego descifra un mensaje con AEGIS-256
- sodium_crypto_aead_aegis256_keygen() - Genera una clave AEGIS-256 aleatoria

# sodium_crypto_aead_aegis256_keygen

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis256_keygen — Genera una clave AEGIS-256 aleatoria

### Descripción

function sodium_crypto_aead_aegis256_keygen(): string

Genera una clave aleatoria de 256 bits para ser utilizada con sodium_crypto_aead_aegis256_encrypt() y sodium_crypto_aead_aegis256_decrypt().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una clave aleatoria de 256 bits.

### Ver también

- sodium_crypto_aead_aegis256_decrypt() - Verifica y luego descifra un mensaje con AEGIS-256
- sodium_crypto_aead_aegis256_encrypt() - Cifra y autentica un mensaje con AEGIS-256

# sodium_crypto_aead_aes256gcm_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_decrypt — Verifica y luego descifra un mensaje con AES-256-GCM

### Descripción

function sodium_crypto_aead_aes256gcm_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Verifica y luego descifra con AES-256-GCM. Disponible únicamente si sodium_crypto_aead_aes256gcm_is_available() devuelve `true`.

### Parámetros

`ciphertext`
  Debe estar en el formato proporcionado por sodium_crypto_aead_aes256gcm_encrypt() (cifrar y etiquetar, concatenados).
`additional_data`
  Datos adicionales autenticados. Esto se utiliza en la verificación de la etiqueta de autenticación añadida al texto cifrado, pero no es cifrado ni almacenado en el texto cifrado.
`nonce`
  Un número que debe ser utilizado una sola vez, por mensaje. 12 bytes de largo.
`key`
  La clave de cifrado (256 bits).

### Valores devueltos

Devuelve el texto en claro en caso de éxito, o `false` si ocurre un error.

# sodium_crypto_aead_aes256gcm_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_encrypt — Cifra y autentica con AES-256-GCM

### Descripción

function sodium_crypto_aead_aes256gcm_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Cifra y autentica con AES-256-GCM. Disponible únicamente si sodium_crypto_aead_aes256gcm_is_available() devuelve `true`.

### Parámetros

`message`
  El mensaje en texto claro a cifrar.
`additional_data`
  Datos adicionales autenticados. Esto se utiliza en la verificación de la etiqueta de autenticación añadida al texto cifrado, pero no se cifra ni se almacena en el texto cifrado.
`nonce`
  Un número que debe ser utilizado una sola vez, por mensaje. 12 bytes de largo.
`key`
  La clave de cifrado (256 bits).

### Valores devueltos

Devuelve el texto cifrado y la etiqueta de autenticación en forma de cadena de bytes binarios sin tratar. (Formato: texto cifrado, luego etiqueta.)

# sodium_crypto_aead_aes256gcm_is_available

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_is_available — Verifica si el hardware soporta AES256-GCM

### Descripción

function sodium_crypto_aead_aes256gcm_is_available(): bool

El valor de retorno de esta función depende de si el hardware soporta o no el AES acelerado por hardware.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si es seguro cifrar con AES-256-GCM, y `false` en caso contrario.

# sodium_crypto_aead_aes256gcm_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_keygen — Genera una clave AES-256-GCM aleatoria

### Descripción

function sodium_crypto_aead_aes256gcm_keygen(): string

Genera una clave aleatoria para su uso con sodium_crypto_aead_aes256gcm_encrypt() y sodium_crypto_aead_aes256gcm_decrypt().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una clave aleatoria de 256 bits.

# sodium_crypto_aead_chacha20poly1305_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_decrypt — Verifica y luego descifra con ChaCha20-Poly1305

### Descripción

function sodium_crypto_aead_chacha20poly1305_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Verifica y luego descifra con ChaCha20-Poly1305.

### Parámetros

`ciphertext`
  Debe estar en el formato proporcionado por sodium_crypto_aead_chacha20poly1305_encrypt() (cifrar y etiquetar, concatenados).
`additional_data`
  Datos adicionales autenticados. Esto se utiliza en la verificación de la etiqueta de autenticación añadida al texto cifrado, pero no se cifra ni se almacena en el texto cifrado.
`nonce`
  Un número que debe ser utilizado una sola vez, por mensaje. 8 bytes de longitud.
`key`
  La clave de cifrado. 256 bits.

### Valores devueltos

Devuelve el texto en claro en caso de éxito, o `false` si ocurre un error.

# sodium_crypto_aead_chacha20poly1305_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_encrypt — Cifra y autentica con ChaCha20-Poly1305

### Descripción

function sodium_crypto_aead_chacha20poly1305_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Cifra y autentica con ChaCha20-Poly1305.

### Parámetros

`message`
  El mensaje en texto claro a cifrar.
`additional_data`
  Datos adicionales autenticados. Esto se utiliza en la verificación de la etiqueta de autenticación añadida al texto cifrado, pero no se cifra ni se almacena en el texto cifrado.
`nonce`
  Un número que debe ser utilizado una sola vez, por mensaje. 8 bytes de largo.
`key`
  La clave de cifrado. 256 bits.

### Valores devueltos

Devuelve la clave de cifrado y la etiqueta en caso de éxito, o `false` si ocurre un error.

# sodium_crypto_aead_chacha20poly1305_ietf_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_decrypt — Verifica que el texto cifrado incluye una etiqueta válida

### Descripción

function sodium_crypto_aead_chacha20poly1305_ietf_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Verifica y luego descifra con ChaCha20-Poly1305 (variante IETF).

La variante IETF utiliza nonces de 96 bits y contadores internos de 32 bits, en lugar de 64 bits para ambos.

### Parámetros

`ciphertext`
  Debe estar en el formato proporcionado por sodium_crypto_aead_chacha20poly1305_ietf_encrypt() (texto cifrado y etiqueta, concatenados).
`additional_data`
  Datos adicionales autenticados. Esto se utiliza en la verificación de la etiqueta de autenticación añadida al texto cifrado, pero no se cifra ni se almacena en el texto cifrado.
`nonce`
  Un número que debe ser utilizado una sola vez, por mensaje. 12 bytes de largo.
`key`
  La clave de cifrado (256 bits).

### Valores devueltos

Devuelve el texto en claro en caso de éxito, o `false` si ocurre un error.

# sodium_crypto_aead_chacha20poly1305_ietf_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_encrypt — Cifra un mensaje

### Descripción

function sodium_crypto_aead_chacha20poly1305_ietf_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Cifra y autentica con ChaCha20-Poly1305 (variante IETF).

La variante IETF utiliza nonces de 96 bits y contadores internos de 32 bits, en lugar de 64 bits para ambos.

### Parámetros

`message`
  El mensaje en texto claro a cifrar.
`additional_data`
  Datos adicionales autenticados. Esto se utiliza en la verificación de la etiqueta de autenticación añadida al texto cifrado, pero no se cifra ni se almacena en el texto cifrado.
`nonce`
  Un número que debe ser utilizado una sola vez, por mensaje. 12 bytes de largo.
`key`
  La clave de cifrado (256 bits).

### Valores devueltos

Devuelve la clave de cifrado y la etiqueta en caso de éxito, o `false` si ocurre un error.

# sodium_crypto_aead_chacha20poly1305_ietf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_keygen — Genera una clave ChaCha20-Poly1305 (IETF) aleatoria

### Descripción

function sodium_crypto_aead_chacha20poly1305_ietf_keygen(): string

Genera una clave aleatoria para su uso con sodium_crypto_aead_chacha20poly1305_ietf_encrypt() y sodium_crypto_aead_chacha20poly1305_ietf_decrypt().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una clave aleatoria de 256 bits.

# sodium_crypto_aead_chacha20poly1305_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_keygen — Genera una clave ChaCha20-Poly1305 aleatoria

### Descripción

function sodium_crypto_aead_chacha20poly1305_keygen(): string

Genera una clave aleatoria para su uso con sodium_crypto_aead_chacha20poly1305_encrypt() y sodium_crypto_aead_chacha20poly1305_decrypt().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una clave aleatoria de 256 bits.

# sodium_crypto_aead_xchacha20poly1305_ietf_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — (Preferido) Verificar y luego descifrar con XChaCha20-Poly1305

### Descripción

function sodium_crypto_aead_xchacha20poly1305_ietf_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Verificar y luego descifrar con ChaCha20-Poly1305 (variante de nonce extendido).

Generalmente, XChaCha20-Poly1305 es el mejor de los modos AEAD proporcionados para usar.

### Parámetros

`ciphertext`
  Debe estar en el formato proporcionado por sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() (texto cifrado y etiqueta, concatenados).
`additional_data`
  Datos adicionales autenticados. Esto se usa en la verificación de la etiqueta de autenticación adjunta al texto cifrado, pero no se cifra ni se almacena en el texto cifrado.
`nonce`
  Un número que debe usarse solo una vez, por mensaje. 24 bytes de largo. Este es un límite lo suficientemente grande para generar aleatoriamente (es decir, random_bytes()).
`key`
  Clave de cifrado (256 bits).

### Valores devueltos

Devuelve el texto plano en caso de éxito, o `false` si ocurre un error.

# sodium_crypto_aead_xchacha20poly1305_ietf_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — (Preferido) Cifra y luego autentica con XChaCha20-Poly1305

### Descripción

function sodium_crypto_aead_xchacha20poly1305_ietf_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Cifra y luego autentica con XChaCha20-Poly1305 (variante eXtended-nonce).

Generalmente, XChaCha20-Poly1305 es el mejor de los modos AEAD proporcionados para usar.

### Parámetros

`message`
  El mensaje en texto claro a cifrar.
`additional_data`
  Datos adicionales autenticados. Esto se utiliza en la verificación de la etiqueta de autenticación añadida al texto cifrado, pero no se cifra ni se almacena en el texto cifrado.
`nonce`
  Un número que debe ser utilizado una sola vez, por mensaje. 24 bytes de largo. Este es un límite suficientemente grande para ser generado aleatoriamente (i.e. random_bytes()).
`key`
  La clave de cifrado (256 bits).

### Valores devueltos

Devuelve la clave de cifrado y la etiqueta en caso de éxito, o `false` si ocurre un error.

# sodium_crypto_aead_xchacha20poly1305_ietf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_keygen — Genera una clave ChaCha20-Poly1305 aleatoria

### Descripción

function sodium_crypto_aead_xchacha20poly1305_ietf_keygen(): string

Genera una clave aleatoria para su uso con sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() y sodium_crypto_aead_xchacha20poly1305_ietf_decrypt().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una clave aleatoria de 256 bits.

# sodium_crypto_auth

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth — Calcula una etiqueta para el mensaje

### Descripción

function sodium_crypto_auth(string `$message`, #[\SensitiveParameter]string `$key`): string

El mensaje de autenticación simétrica a través de sodium_crypto_auth() proporciona integridad, pero no confidencialidad.

A diferencia de las firmas digitales (por ejemplo sodium_crypto_sign_detached()), cualquier parte capaz de verificar un mensaje también es capaz de autenticar sus propios mensajes. (De ahí, la autenticación simétrica.)

### Parámetros

`message`
  El mensaje que se desea autenticar
`key`
  La clave de autenticación

### Valores devueltos

La clave de autenticación

# sodium_crypto_auth_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth_keygen — Genera una clave aleatoria para sodium_crypto_auth

### Descripción

function sodium_crypto_auth_keygen(): string

Genera una clave aleatoria para su uso con sodium_crypto_auth() y sodium_crypto_auth_verify().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una clave aleatoria de 256 bits.

# sodium_crypto_auth_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth_verify — Verifica que la etiqueta es válida para el mensaje

### Descripción

function sodium_crypto_auth_verify(string `$mac`, string `$message`, #[\SensitiveParameter]string `$key`): bool

Verifica que la etiqueta es válida para un mensaje y una clave dados.

A diferencia de las firmas digitales (por ejemplo sodium_crypto_sign_verify_detached()), cualquier parte capaz de verificar un mensaje también es capaz de autenticar sus propios mensajes. (De ahí, la autenticación simétrica.)

### Parámetros

`mac`
  Etiqueta de autenticación producida por sodium_crypto_auth()
`message`
  Mensaje
`key`
  La clave de autenticación

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# sodium_crypto_box

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box — Cifrado asimétrico autenticado

### Descripción

function sodium_crypto_box(#[\SensitiveParameter]string `$message`, string `$nonce`, #[\SensitiveParameter]string `$key_pair`): string

Cifra un mensaje utilizando criptografía asimétrica (clave pública).

El algoritmo utilizado por las funciones prefijadas por sodium_crypto_box() es Diffie-Hellman sobre la curva de Montgomery, Curve25519; generalmente abreviado como X25519.

### Parámetros

`message`
  El mensaje a cifrar.
`nonce`
  Un número que debe ser utilizado una sola vez, por mensaje. 24 bytes de largo. Este es un límite suficientemente grande para ser generado aleatoriamente (i.e. random_bytes()).
`key_pair`
  Ver sodium_crypto_box_keypair_from_secretkey_and_publickey(). Esto incluye la clave pública del remitente y la clave secreta del destinatario.

### Valores devueltos

Devuelve el mensaje cifrado (ciphertext más etiqueta de autenticación). El texto cifrado será 16 bytes más largo que el texto en claro, y una string binaria bruta. Ver sodium_bin2base64() para un encodaje seguro para el almacenamiento.

# sodium_crypto_box_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_keypair — Genera aleatoriamente una clave secreta y una clave pública correspondiente

### Descripción

function sodium_crypto_box_keypair(): string

Genera una clave secreta y una clave pública en una sola cadena.

Para extraer la clave secreta de esta cadena de clave unificada, ver sodium_crypto_box_secretkey(). Para extraer la clave pública de esta cadena de clave unificada, ver sodium_crypto_box_publickey().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Una cadena que contiene tanto la clave secreta X25519 como la clave pública X25519 correspondiente.

# sodium_crypto_box_keypair_from_secretkey_and_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_keypair_from_secretkey_and_publickey — Crear una pareja de claves unificada a partir de una clave secreta y una clave pública

### Descripción

function sodium_crypto_box_keypair_from_secretkey_and_publickey(#[\SensitiveParameter]string `$secret_key`, string `$public_key`): string

Esta función existe para satisfacer los requisitos de la API de crypto_box(). Pasar la clave secreta de una parte y la clave pública de la otra, y se obtendrá una "pareja de claves" para la conversación.

### Parámetros

`secret_key`
  La clave secreta.
`public_key`
  La clave pública.

### Valores devueltos

Una pareja de claves X25519.

# sodium_crypto_box_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_open — Desencriptación autenticada con clave pública

### Descripción

function sodium_crypto_box_open(string `$ciphertext`, string `$nonce`, #[\SensitiveParameter]string `$key_pair`): string|false

Desencripta un mensaje utilizando criptografía asimétrica (clave pública).

### Parámetros

`ciphertext`
  El mensaje cifrado a desencriptar.
`nonce`
  Un número que debe ser utilizado una sola vez, por mensaje. 24 bytes de longitud. Es un límite suficientemente grande para ser generado aleatoriamente (i.e. random_bytes()).
`key_pair`
  Ver sodium_crypto_box_keypair_from_secretkey_and_publickey(). Debe incluir la clave pública del remitente y la clave secreta del destinatario.

### Valores devueltos

Devuelve el mensaje en claro en caso de éxito, o `false` si ocurre un error.

# sodium_crypto_box_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_publickey — Extrae la clave pública de un par de claves crypto_box

### Descripción

function sodium_crypto_box_publickey(#[\SensitiveParameter]string `$key_pair`): string

Dado un par de claves, se extrae únicamente la clave pública.

### Parámetros

`key_pair`
  Un par de claves, tal como el generado por sodium_crypto_box_keypair() o sodium_crypto_box_seed_keypair()

### Valores devueltos

La clave pública X25519.

# sodium_crypto_box_publickey_from_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_publickey_from_secretkey — Calcula la clave pública a partir de una clave secreta

### Descripción

function sodium_crypto_box_publickey_from_secretkey(#[\SensitiveParameter]string `$secret_key`): string

Dada una clave secreta, se calcula la clave pública correspondiente.

Esto solo funciona con el tipo de claves destinadas a ser utilizadas con crypto_box() (que utiliza el intercambio de claves de Diffie-Hellman sobre la curva de Montgomery, Curve25519; abreviado X25519), no con crypto_sign() (que utiliza el algoritmo de firma digital de Edwards sobre la curva de Edwards con los parámetros correspondientes; abreviado Ed25519).

### Parámetros

`secret_key`
  La clave secreta X25519

### Valores devueltos

La clave pública X25519.

# sodium_crypto_box_seal

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seal — Cifrado anónimo con clave pública

### Descripción

function sodium_crypto_box_seal(#[\SensitiveParameter]string `$message`, string `$public_key`): string

Cifra un mensaje de tal manera que solo el destinatario pueda descifrarlo.

A diferencia de sodium_crypto_box(), solo se necesita la clave pública del destinatario para utilizar sodium_crypto_box_seal(). Una consecuencia de esta comodidad, sin embargo, es que el texto cifrado no está vinculado a una clave pública estática, y por lo tanto no está autenticado. De ahí el cifrado anónimo con clave pública.

sodium_crypto_box_seal() siempre proporciona la integridad del texto cifrado. Solo que no la autenticación de la identidad del remitente.

Si también se necesita la autenticación del remitente, las funciones sodium_crypto_sign() son probablemente el mejor punto de partida.

### Parámetros

`message`
  El mensaje a cifrar.
`public_key`
  La clave pública que corresponde a la única clave que puede descifrar el mensaje.

### Valores devueltos

Un texto cifrado en forma de (clave pública única, mensaje cifrado, etiqueta de autenticación).

### Ejemplos

Ejemplo #1 Ejemplo de sodium_crypto_box_seal()

    <?php
    $keypair = sodium_crypto_box_keypair();
    $public_key = sodium_crypto_box_publickey($keypair);

    // El texto en claro obfuscado para hacer el ejemplo más divertido
    $plaintext_b64 = "V3JpdGluZyBzb2Z0d2FyZSBpbiBQSFAgY2FuIGJlIGEgZGVsaWdodCE=";
    $decoded_plaintext = sodium_base642bin($plaintext_b64, SODIUM_BASE64_VARIANT_ORIGINAL);

    $sealed = sodium_crypto_box_seal($decoded_plaintext, $public_key);
    var_dump(base64_encode($sealed));

    $opened = sodium_crypto_box_seal_open($sealed, $keypair);
    var_dump($opened);
    ?>

Resultado del ejemplo anterior es similar a:

    string(120) "oRBXXAV4iQBrxlV4A21Bord8Yo/D8ZlrIIGNyaRCcGBfpz0map52I3xq6l+CST+1NSgQkbV+HiYyFjXWiWiaCGupGf+zl4bgWj/A9Adtem7Jt3h3emrMsLw="
    string(41) "Writing software in PHP can be a delight!"

# sodium_crypto_box_seal_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seal_open — Desencriptación anónima con clave pública

### Descripción

function sodium_crypto_box_seal_open(string `$ciphertext`, #[\SensitiveParameter]string `$key_pair`): string|false

Desencripta un mensaje que ha sido encriptado con sodium_crypto_box_seal()

### Parámetros

`ciphertext`
  El mensaje encriptado
`key_pair`
  La pareja de claves del destinatario. Debe incluir la clave secreta.

### Valores devueltos

El texto en claro en caso de éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de sodium_crypto_box_seal_open()

    <?php
    // El texto encriptado no es sensible; base64_decode es suficiente
    $sealed_b64 = "oRBXXAV4iQBrxlV4A21Bord8Yo/D8ZlrIIGNyaRCcGBfpz0map52I3xq6l+CST+1NSgQkbV+HiYyFjXWiWiaCGupGf+zl4bgWj/A9Adtem7Jt3h3emrMsLw=";
    $sealed = base64_decode($sealed_b64);

    // La pareja de claves contiene un secreto criptográfico; utilice un decodificador seguro en tiempo
    $keypair_b64 = "KZkF8wnB7bnC2aXB3lFOqCTc0Z6MllvaQb9ASVG8o2/MsewkuE4u1uaEgTzSakeiYyIW8DGj+02/L3cWIbs9bQ==";
    $keypair = sodium_base642bin($keypair_b64, SODIUM_BASE64_VARIANT_ORIGINAL);

    $opened = sodium_crypto_box_seal_open($sealed, $keypair);
    var_dump($opened);
    ?>

Resultado del ejemplo anterior es similar a:

    string(41) "Writing software in PHP can be a delight!"

# sodium_crypto_box_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_secretkey — Extrae la clave secreta de un par de claves crypto_box

### Descripción

function sodium_crypto_box_secretkey(#[\SensitiveParameter]string `$key_pair`): string

Dado un par de claves, extrae únicamente la clave secreta.

### Parámetros

`key_pair`
  Un par de claves, tal como el generado por sodium_crypto_box_keypair() o sodium_crypto_box_seed_keypair()

### Valores devueltos

La clave secreta X25519

# sodium_crypto_box_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seed_keypair — Deriva de manera determinista el par de claves a partir de una sola clave

### Descripción

function sodium_crypto_box_seed_keypair(#[\SensitiveParameter]string `$seed`): string

Adjunta la semilla para formar una clave secreta, deriva la clave pública y devuelve ambas como un par de claves.

Las funciones `*_seed_keypair` son ideales para generar un par de claves a partir de una contraseña y una sal. Utilice el resultado como `seed` para generar las claves deseadas.

### Parámetros

`seed`
  Una entrada criptográfica. Debe ser de 32 bytes.

### Valores devueltos

Un par de claves X25519 (clave secreta y clave pública).

# sodium_crypto_core_ristretto255_add

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_add — Añade un elemento

### Descripción

function sodium_crypto_core_ristretto255_add(string `$p`, string `$q`): string

Añade un elemento `q` a `p`. Disponible a partir de libsodium 1.0.18.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`p`
  Un elemento.
`q`
  Un elemento.

### Valores devueltos

Devuelve una string aleatoria de 32 bytes.

### Ejemplos

Ejemplo #1 Ejemplo de sodium_crypto_core_ristretto255_add()

    <?php

    $foo = sodium_crypto_core_ristretto255_random();
    $bar = sodium_crypto_core_ristretto255_random();

    $value = sodium_crypto_core_ristretto255_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

El ejemplo anterior mostrará:

    bool(true)

### Ver también

- sodium_crypto_core_ristretto255_random() - Genera una clave aleatoria
- sodium_crypto_core_ristretto255_sub() - Sustrae un elemento

# sodium_crypto_core_ristretto255_from_hash

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_from_hash — Mapea un vector

### Descripción

function sodium_crypto_core_ristretto255_from_hash(string `$s`): string

Mapea un vector `s` de 64 bytes a un elemento de grupo. Disponible a partir de libsodium 1.0.18.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`s`
  Un vector de 64 bytes.

### Valores devueltos

Devuelve una string aleatoria de 32 bytes.

### Ejemplos

Ejemplo #1 Ejemplo de sodium_crypto_core_ristretto255_from_hash()

    <?php

    $hashes = sodium_hex2bin(
        '5d1be09e3d0c82fc538112490e35701979d99e06ca3e2b5b54bffe8b4dc772c1' .
        '4d98b696a1bbfb5ca32c436cc61c16563790306c79eaca7705668b47dffe5bb6'
    );
    var_dump(sodium_bin2hex(sodium_crypto_core_ristretto255_from_hash($hashes)));
    ?>

El ejemplo anterior mostrará:

    string(64) "3066f82a1a747d45120d1740f14358531a8f04bbffe6a819f86dfe50f44a0a46"

### Ver también

- sodium_hex2bin() - Decodifica una cadena binaria codificada en hexadecimal
- sodium_bin2hex() - Codificar en hexadecimal
- sodium_crypto_core_ristretto255_from_hash()

# sodium_crypto_core_ristretto255_is_valid_point

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_is_valid_point — Determina si un punto está en la curva ristretto255

### Descripción

function sodium_crypto_core_ristretto255_is_valid_point(string `$s`): bool

Determina si un punto está en la curva ristretto255, en forma canónica, en el subgrupo principal, y que el punto no tiene un orden pequeño. Disponible a partir de libsodium 1.0.18.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`s`
  Un punto en la curva elíptica.

### Valores devueltos

Devuelve `true` si `s` está en la curva ristretto255, `false` en caso contrario.

### Ejemplos

Ejemplo #1 Ejemplo de sodium_crypto_core_ristretto255_is_valid_point()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();
    $bar = sodium_crypto_scalarmult_ristretto255_base($foo);

    var_dump(sodium_crypto_core_ristretto255_is_valid_point($bar));
    ?>

El ejemplo anterior mostrará:

    bool(true)

### Ver también

- sodium_crypto_core_ristretto255_scalar_random() - Genera una clave aleatoria
- sodium_crypto_scalarmult_ristretto255_base() - Calcula la clave pública a partir de una clave secreta

# sodium_crypto_core_ristretto255_random

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_random — Genera una clave aleatoria

### Descripción

function sodium_crypto_core_ristretto255_random(): string

Genera una clave aleatoria. Disponible a partir de libsodium 1.0.18.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una string aleatoria de 32 bytes.

### Ejemplos

Ejemplo #1 Ejemplo de sodium_crypto_core_ristretto255_random()

    <?php

    $foo = sodium_crypto_core_ristretto255_random();
    $bar = sodium_crypto_core_ristretto255_random();

    $value = sodium_crypto_core_ristretto255_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

El ejemplo anterior mostrará:

    bool(true)

### Ver también

- sodium_crypto_core_ristretto255_add() - Añade un elemento
- sodium_crypto_core_ristretto255_sub() - Sustrae un elemento

# sodium_crypto_core_ristretto255_scalar_add

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_add — Añade un valor escalar

### Descripción

function sodium_crypto_core_ristretto255_scalar_add(string `$x`, string `$y`): string

Añade un elemento `y` a `x`. Disponible a partir de libsodium 1.0.18.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`x`
  Escalar que representa la coordenada X.
`y`
  Escalar que representa la coordenada Y.

### Valores devueltos

Devuelve una string aleatoria de 32 bytes.

### Ejemplos

Ejemplo #1 Ejemplo de sodium_crypto_core_ristretto255_scalar_add()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();
    $bar = sodium_crypto_core_ristretto255_scalar_random();

    $value = sodium_crypto_core_ristretto255_scalar_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_scalar_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

El ejemplo anterior mostrará:

    bool(true)

### Ver también

- sodium_crypto_core_ristretto255_scalar_random() - Genera una clave aleatoria
- sodium_crypto_core_ristretto255_scalar_sub() - Sustrae un valor escalar

# sodium_crypto_core_ristretto255_scalar_complement

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_complement — El propósito de sodium_crypto_core_ristretto255_scalar_complement

### Descripción

function sodium_crypto_core_ristretto255_scalar_complement(string `$s`): string

Disponible a partir de libsodium 1.0.18.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`s`
  Valor escalar.

### Valores devueltos

Devuelve una string aleatoria de 32 bytes.

### Ver también

- sodium_crypto_core_ristretto255_scalar_random() - Genera una clave aleatoria

# sodium_crypto_core_ristretto255_scalar_invert

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_invert — Invierte un valor escalar

### Descripción

function sodium_crypto_core_ristretto255_scalar_invert(string `$s`): string

Invierte un valor escalar. Disponible a partir de libsodium 1.0.18.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`s`
  Valor escalar.

### Valores devueltos

Devuelve una string aleatoria de 32 bytes.

### Ejemplos

Ejemplo #1 Ejemplo de sodium_crypto_core_ristretto255_scalar_invert()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();

    $inverted = sodium_crypto_core_ristretto255_scalar_invert($foo);
    $reInverted = sodium_crypto_core_ristretto255_scalar_invert($inverted);

    var_dump(hash_equals($foo, $reInverted));
    ?>

El ejemplo anterior mostrará:

    bool(true)

### Ver también

- sodium_crypto_core_ristretto255_scalar_random() - Genera una clave aleatoria

# sodium_crypto_core_ristretto255_scalar_mul

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_mul — Multiplica un valor escalar

### Descripción

function sodium_crypto_core_ristretto255_scalar_mul(string `$x`, string `$y`): string

Multiplica un valor escalar. Disponible a partir de libsodium 1.0.18.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`x`
  Escalar que representa la coordenada X.
`y`
  Escalar que representa la coordenada Y.

### Valores devueltos

Devuelve una string aleatoria de 32 bytes.

### Ver también

- sodium_crypto_core_ristretto255_scalar_random() - Genera una clave aleatoria

# sodium_crypto_core_ristretto255_scalar_negate

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_negate — Invierte el signo de un valor escalar

### Descripción

function sodium_crypto_core_ristretto255_scalar_negate(string `$s`): string

Invierte el signo de un valor escalar. Disponible a partir de libsodium 1.0.18.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`s`
  Valor escalar.

### Valores devueltos

Devuelve una string aleatoria de 32 bytes.

### Ejemplos

Ejemplo #1 Ejemplo de sodium_crypto_core_ristretto255_scalar_negate()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();

    $negate = sodium_crypto_core_ristretto255_scalar_negate($foo);
    $reNegate = sodium_crypto_core_ristretto255_scalar_negate($negate);

    var_dump(hash_equals($foo, $reNegate));
    ?>

El ejemplo anterior mostrará:

    bool(true)

### Ver también

- sodium_crypto_core_ristretto255_scalar_random() - Genera una clave aleatoria

# sodium_crypto_core_ristretto255_scalar_random

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_random — Genera una clave aleatoria

### Descripción

function sodium_crypto_core_ristretto255_scalar_random(): string

Genera una clave aleatoria. Disponible a partir de libsodium 1.0.18.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una string aleatoria de 32 bytes.

### Ejemplos

Ejemplo #1 Ejemplo de sodium_crypto_core_ristretto255_scalar_random()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();
    $bar = sodium_crypto_core_ristretto255_scalar_random();

    $value = sodium_crypto_core_ristretto255_scalar_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_scalar_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

El ejemplo anterior mostrará:

    bool(true)

### Ver también

- sodium_crypto_core_ristretto255_scalar_add() - Añade un valor escalar
- sodium_crypto_core_ristretto255_scalar_sub() - Sustrae un valor escalar

# sodium_crypto_core_ristretto255_scalar_reduce

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_reduce — Reduce un valor escalar

### Descripción

function sodium_crypto_core_ristretto255_scalar_reduce(string `$s`): string

Reduce un valor escalar. Disponible a partir de libsodium 1.0.18.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`s`
  Un valor escalar.

### Valores devueltos

Devuelve una string aleatoria de 32 bytes.

### Ver también

- sodium_crypto_core_ristretto255_scalar_random() - Genera una clave aleatoria

# sodium_crypto_core_ristretto255_scalar_sub

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_sub — Sustrae un valor escalar

### Descripción

function sodium_crypto_core_ristretto255_scalar_sub(string `$x`, string `$y`): string

Sustrae un escalar `y` de `x`. Disponible a partir de libsodium 1.0.18.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`x`
  Escalar, representando la coordenada X.
`y`
  Escalar, representando la coordenada Y.

### Valores devueltos

Devuelve una string aleatoria de 32 bytes.

### Ejemplos

Ejemplo #1 Ejemplo de sodium_crypto_core_ristretto255_scalar_sub()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();
    $bar = sodium_crypto_core_ristretto255_scalar_random();

    $value = sodium_crypto_core_ristretto255_scalar_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_scalar_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

El ejemplo anterior mostrará:

    bool(true)

### Ver también

- sodium_crypto_core_ristretto255_scalar_random() - Genera una clave aleatoria
- sodium_crypto_core_ristretto255_scalar_add() - Añade un valor escalar

# sodium_crypto_core_ristretto255_sub

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_sub — Sustrae un elemento

### Descripción

function sodium_crypto_core_ristretto255_sub(string `$p`, string `$q`): string

Sustrae un elemento `q` de `p`. Disponible a partir de libsodium 1.0.18.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`p`
  Un elemento.
`q`
  Un elemento.

### Valores devueltos

Devuelve una string aleatoria de 32 bytes.

### Ejemplos

Ejemplo #1 Ejemplo de sodium_crypto_core_ristretto255_sub()

    <?php

    $foo = sodium_crypto_core_ristretto255_random();
    $bar = sodium_crypto_core_ristretto255_random();

    $value = sodium_crypto_core_ristretto255_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

El ejemplo anterior mostrará:

    bool(true)

### Ver también

- sodium_crypto_core_ristretto255_random() - Genera una clave aleatoria
- sodium_crypto_core_ristretto255_add() - Añade un elemento

# sodium_crypto_generichash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash — Devuelve un hash del mensaje

### Descripción

function sodium_crypto_generichash(string `$message`, #[\SensitiveParameter]string `$key` = "", int `$length` = `SODIUM_CRYPTO_GENERICHASH_BYTES`): string

Hachea un mensaje con BLAKE2b.

### Parámetros

`message`
  El mensaje a hachear.
`key`
  (Opcional) Clave criptográfica. Sirve para la misma función que una clave HMAC, pero se utiliza como una sección reservada del estado interno de BLAKE2.
`length`
  El tamaño de la salida.

### Valores devueltos

El hash criptográfico como una cadena binaria bruta. Si se desea una salida hexadecimal, el resultado puede ser pasado a sodium_bin2hex().

# sodium_crypto_generichash_final

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_final — Completa el hash

### Descripción

function sodium_crypto_generichash_final(string `&$state`, int `$length` = `SODIUM_CRYPTO_GENERICHASH_BYTES`): string

El método de finalización para la API de hash genérico en streaming.

### Parámetros

`state`
  El estado de hash devuelto por sodium_crypto_generichash_init()
`length`
  La longitud de la salida.

### Valores devueltos

El hash criptográfico.

### Ejemplos

Ejemplo #1 Ejemplo de sodium_crypto_generichash_final()

    <?php
    $messages = [random_bytes(32), random_bytes(32), random_bytes(16)];
    $state = sodium_crypto_generichash_init('', 32);
    foreach ($messages as $message) {
        sodium_crypto_generichash_update($state, $message);
    }

    $final = sodium_crypto_generichash_final($state, 32);
    var_dump(sodium_bin2hex($final));

    $allAtOnce = sodium_crypto_generichash(implode('', $messages));
    var_dump(sodium_bin2hex($allAtOnce));
    ?>

Resultado del ejemplo anterior es similar a:

    string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"
    string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"

# sodium_crypto_generichash_init

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_init — Inicializa un hash para el streaming

### Descripción

function sodium_crypto_generichash_init(#[\SensitiveParameter]string `$key` = "", int `$length` = `SODIUM_CRYPTO_GENERICHASH_BYTES`): string

El método de inicialización para la API de hash genérico en streaming.

### Parámetros

`key`
  La clave de hash genérico.
`length`
  El tamaño de la salida esperada de la función de hash.

### Valores devueltos

Devuelve un estado de hash, serializado en forma de una string binaria bruta.

### Ejemplos

Ejemplo #1 Ejemplo de sodium_crypto_generichash_init()

    <?php
    $messages = [random_bytes(32), random_bytes(32), random_bytes(16)];
    $state = sodium_crypto_generichash_init('', 32);
    foreach ($messages as $message) {
        sodium_crypto_generichash_update($state, $message);
    }
    $final = sodium_crypto_generichash_final($state, 32);
    var_dump(sodium_bin2hex($final));
    $allAtOnce = sodium_crypto_generichash(implode('', $messages));
    var_dump(sodium_bin2hex($allAtOnce));
    ?>

Resultado del ejemplo anterior es similar a:

    string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"
    string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"

# sodium_crypto_generichash_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_keygen — Genera una clave de hash genérico aleatoria

### Descripción

function sodium_crypto_generichash_keygen(): string

Genera una clave aleatoria para su uso con la API de hash genérico.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Una clave aleatoria de 256 bits.

# sodium_crypto_generichash_update

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_update — Añade un mensaje a un hash

### Descripción

function sodium_crypto_generichash_update(string `&$state`, string `$message`): true

Añade un mensaje al estado de hash interno.

### Parámetros

`state`
  El valor de retorno de sodium_crypto_generichash_init().
`message`
  Los datos a añadir al estado de hash.

### Valores devueltos

Retorna siempre `true`.

### Ejemplos

Ejemplo #1 Ejemplo de sodium_crypto_generichash_update()

    <?php
    $messages = [random_bytes(32), random_bytes(32), random_bytes(16)];
    $state = sodium_crypto_generichash_init();
    foreach ($messages as $message) {
        sodium_crypto_generichash_update($state, $message);
    }
    $final = sodium_crypto_generichash_final($state);
    var_dump(sodium_bin2hex($final));

    $allAtOnce = sodium_crypto_generichash(implode('', $messages));
    var_dump(sodium_bin2hex($allAtOnce));
    ?>

Resultado del ejemplo anterior es similar a:

    string(64) "e16e28bbbbcc39d9f5b1cbc33c41f1d217808640103e57a41f24870f79831e04"
    string(64) "e16e28bbbbcc39d9f5b1cbc33c41f1d217808640103e57a41f24870f79831e04"

# sodium_crypto_kdf_derive_from_key

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kdf_derive_from_key — Deriva una subclave

### Descripción

function sodium_crypto_kdf_derive_from_key(
int `$subkey_length`,
int `$subkey_id`,
string `$context`,
#[\SensitiveParameter]string `$key`
): string

Deriva una subclave a partir de una clave raíz y un contexto adicional.

Similar a hash_hkdf().

### Parámetros

`subkey_length`
  La longitud de la clave a devolver (en bytes).
`subkey_id`
  Devuelve la subclave N-ésima de una clave raíz dada. Útil para la búsqueda.
`context`
  El contexto específico de la aplicación.
`key`
  La clave raíz a partir de la cual se deriva la subclave.

### Valores devueltos

Una cadena de bytes pseudorandom (binario sin tratar).

# sodium_crypto_kdf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kdf_keygen — Genera una clave raíz aleatoria para la interfaz KDF

### Descripción

function sodium_crypto_kdf_keygen(): string

Genera una clave aleatoria adecuada para servir como clave raíz para sodium_crypto_kdf_derive_from_key().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Una clave aleatoria de 256 bits.

# sodium_crypto_kx_client_session_keys

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_client_session_keys — Calcula las claves de sesión del lado del cliente.

### Descripción

function sodium_crypto_kx_client_session_keys(#[\SensitiveParameter]string `$client_key_pair`, string `$server_key`): array

Calcula las claves de sesión del lado del cliente, utilizando el método de intercambio de claves X25519 + BLAKE2b.

### Parámetros

`client_key_pair`
  Un par de claves crypto_kx, como las generadas por sodium_crypto_kx_keypair().
`server_key`
  Una clave pública crypto_kx.

### Valores devueltos

Un array compuesto de dos strings. La primera debe ser utilizada para recibir datos del servidor. La segunda debe ser utilizada para enviar datos al servidor.

# sodium_crypto_kx_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_keypair — Crear una nueva pareja de claves sodium

### Descripción

function sodium_crypto_kx_keypair(): string

Crear una nueva pareja de claves sodium compuesta por la clave secreta (32 bytes) seguida de la clave pública (32 bytes). Las claves pueden ser recuperadas llamando a sodium_crypto_kx_secretkey() y sodium_crypto_kx_publickey(), respectivamente.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la nueva pareja de claves en caso de éxito; lanza una excepción en caso contrario.

### Ejemplos

Ejemplo #1 Uso de sodium_crypto_kx_keypair()

Crear una nueva pareja de claves y recuperar la clave secreta y la clave pública asociada.

    <?php
    $keypair = sodium_crypto_kx_keypair();
    $secret = sodium_crypto_kx_secretkey($keypair);
    $public = sodium_crypto_kx_publickey($keypair);
    printf("secret: %s\npublic: %s", sodium_bin2hex($secret), sodium_bin2hex($public));
    ?>

Resultado del ejemplo anterior es similar a:

    secret: e7c5c918fdc40762e6000542c0118f4368ce8fd242b0e48c1e17202797a25daf
    public: d1f59fda8652caf40ed1a01d2b6f3802b60846986372cd8fa337b7c12c428b18

# sodium_crypto_kx_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_publickey — Extrae la clave pública de un par de claves crypto_kx

### Descripción

function sodium_crypto_kx_publickey(#[\SensitiveParameter]string `$key_pair`): string

Extrae la clave pública de un par de claves crypto_kx.

### Parámetros

`key_pair`
  Un par de claves X25519, tal como el generado por sodium_crypto_kx_keypair().

### Valores devueltos

Una clave pública X25519.

# sodium_crypto_kx_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_secretkey — Extrae la clave secreta de un par de claves crypto_kx

### Descripción

function sodium_crypto_kx_secretkey(#[\SensitiveParameter]string `$key_pair`): string

Extrae la clave secreta de un par de claves crypto_kx.

### Parámetros

`key_pair`
  Un par de claves X25519, tal como el generado por sodium_crypto_kx_keypair().

### Valores devueltos

La clave secreta X25519.

# sodium_crypto_kx_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_seed_keypair — Descripción

### Descripción

function sodium_crypto_kx_seed_keypair(#[\SensitiveParameter]string `$seed`): string

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`seed`

### Valores devueltos

# sodium_crypto_kx_server_session_keys

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_server_session_keys — Calcula las claves de sesión del lado del servidor.

### Descripción

function sodium_crypto_kx_server_session_keys(#[\SensitiveParameter]string `$server_key_pair`, string `$client_key`): array

Calcula las claves de sesión del lado del servidor, utilizando el método de intercambio de claves X25519 + BLAKE2b.

### Parámetros

`server_key_pair`
  Un par de claves crypto_kx, como el generado por sodium_crypto_kx_keypair().
`client_key`
  Una clave pública crypto_kx.

### Valores devueltos

Un array compuesto de dos strings. La primera debe ser utilizada para recibir datos del cliente. La segunda debe ser utilizada para enviar datos al cliente.

# sodium_crypto_pwhash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash — Deriva una clave a partir de una contraseña, utilizando Argon2

### Descripción

function sodium_crypto_pwhash(
int `$length`,
#[\SensitiveParameter]string `$password`,
string `$salt`,
int `$opslimit`,
int `$memlimit`,
int `$algo` = `SODIUM_CRYPTO_PWHASH_ALG_DEFAULT`
): string

Esta función proporciona acceso de bajo nivel a la función de derivación de clave crypto_pwhash de libsodium. A menos que haya una razón específica para utilizar esta función, se deben utilizar las funciones sodium_crypto_pwhash_str() o password_hash() en su lugar.

Una razón común para utilizar esta función es derivar las semillas para las claves criptográficas a partir de una contraseña y un salt, y luego utilizar estas semillas para generar las claves reales necesarias para un uso específico (por ejemplo, sodium_crypto_sign_detached()).

### Parámetros

`length`
  int; La longitud del hash de la contraseña a generar, en bytes.
`password`
  string; La contraseña para la cual generar un hash.
`salt`
  Un salt para añadir a la contraseña antes del hash. El salt debe ser impredecible, idealmente generado a partir de una buena fuente de números aleatorios como random_bytes(), y tener una longitud de al menos `SODIUM_CRYPTO_PWHASH_SALTBYTES` bytes.
`opslimit`
  Representa una cantidad máxima de cálculos a realizar. Aumentar este número hará que la función requiera más ciclos de CPU para calcular una clave. Existen constantes disponibles para definir el límite de operaciones a valores adecuados según el uso previsto, en orden de fuerza: `SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE` y `SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE`.
`memlimit`
  La cantidad máxima de RAM que la función utilizará, en bytes. Existen constantes para ayudar a elegir un valor adecuado, en orden de tamaño: `SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE` y `SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE`. Típicamente, estos valores deberían asociarse con los valores opslimit correspondientes.
`algo`
  int Un número que indica el algoritmo de hash a utilizar. Por defecto `SODIUM_CRYPTO_PWHASH_ALG_DEFAULT` (el algoritmo actualmente recomendado, que puede cambiar de una versión de libsodium a otra), o explícitamente utilizando `SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13`, representando el algoritmo Argon2id versión 1.3.

### Valores devueltos

Devuelve la clave derivada. El valor de retorno es una cadena binaria del hash, no una representación codificada en ASCII, y no contiene información adicional sobre los parámetros utilizados para crear el hash, por lo que se deberá conservar esta información si alguna vez se necesita verificar la contraseña en el futuro. Utilice sodium_crypto_pwhash_str() para evitar tener que hacer todo esto.

### Ejemplos

Ejemplo #1 Ejemplo de sodium_crypto_pwhash()

    <?php
    //Requerido para conservar el salt si alguna vez necesitamos verificar esta contraseña
    $salt = random_bytes(SODIUM_CRYPTO_PWHASH_SALTBYTES);
    //Utilizar bin2hex para mantener la salida legible
    echo bin2hex(
        sodium_crypto_pwhash(
            16, // == 128 bits
            'password',
            $salt,
            SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
            SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE,
            SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13
        )
    );
    ?>

Resultado del ejemplo anterior es similar a:

    a18f346ba57992eb7e4ae6abf3fd30ee

# sodium_crypto_pwhash_scryptsalsa208sha256

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256 — Deriva una clave a partir de una contraseña, utilizando scrypt

### Descripción

function sodium_crypto_pwhash_scryptsalsa208sha256(
int `$length`,
#[\SensitiveParameter]string `$password`,
string `$salt`,
int `$opslimit`,
int `$memlimit`
): string

Esta es la contraparte scrypt de sodium_crypto_pwhash().

Una razón común para utilizar esta función es derivar las semillas para las claves criptográficas a partir de una contraseña y un salt, y luego utilizar estas semillas para generar las claves reales necesarias para un uso específico (por ejemplo, sodium_crypto_sign_detached()).

### Parámetros

`length`
  La longitud del hash de la contraseña a generar, en bytes.
`password`
  La contraseña para la cual se generará un hash.
`salt`
  Un salt que se añadirá a la contraseña antes del hash. El salt debe ser impredecible, idealmente generado a partir de una buena fuente de números aleatorios como random_bytes(), y tener una longitud de al menos `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_SALTBYTES` bytes.
`opslimit`
  Representa una cantidad máxima de cálculos a realizar. Aumentar este número hará que la función requiera más ciclos de CPU para calcular una clave. Existen constantes disponibles para definir el límite de operaciones a valores apropiados según el uso previsto, en orden de fuerza: `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE` y `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_SENSITIVE`.
`memlimit`
  La cantidad máxima de RAM que la función utilizará, en bytes. Existen constantes para ayudar a elegir un valor apropiado, en orden de tamaño: `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE` y `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_SENSITIVE`. Típicamente, estas deberían asociarse con los valores `opslimit` correspondientes.

### Valores devueltos

Una cadena de bytes de la longitud deseada.

# sodium_crypto_pwhash_scryptsalsa208sha256_str

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256_str — Devuelve un hash codificado en ASCII

### Descripción

function sodium_crypto_pwhash_scryptsalsa208sha256_str(#[\SensitiveParameter]string `$password`, int `$opslimit`, int `$memlimit`): string

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`password`
`opslimit`
`memlimit`

### Valores devueltos

# sodium_crypto_pwhash_scryptsalsa208sha256_str_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256_str_verify — Verifica si la contraseña corresponde a una cadena de hash de contraseña

### Descripción

function sodium_crypto_pwhash_scryptsalsa208sha256_str_verify(string `$hash`, #[\SensitiveParameter]string `$password`): bool

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`hash`
`password`

### Valores devueltos

# sodium_crypto_pwhash_str

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str — Devuelve un hash codificado en ASCII

### Descripción

function sodium_crypto_pwhash_str(#[\SensitiveParameter]string `$password`, int `$opslimit`, int `$memlimit`): string

Utiliza un algoritmo de hash intensivo en CPU y memoria con una sal generada aleatoriamente, y límites de memoria y CPU para generar un hash codificado en ASCII adecuado para el almacenamiento de contraseñas.

### Parámetros

`password`
  string; La contraseña para la cual se generará un hash.
`opslimit`
  Representa una cantidad máxima de cálculos a realizar. Aumentar este número hará que la función requiera más ciclos de CPU para calcular una clave. Existen constantes disponibles para definir el límite de operaciones a valores apropiados según el uso previsto, en orden de fuerza: `SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE` y `SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE`.
`memlimit`
  La cantidad máxima de RAM que la función utilizará, en bytes. Existen constantes para ayudar a elegir un valor apropiado, en orden de tamaño: `SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE` y `SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE`. Típicamente, estos valores deberían asociarse con los valores opslimit correspondientes.

### Valores devueltos

Devuelve el hash de la contraseña.

Para producir el mismo hash de contraseña a partir de la misma contraseña, los mismos valores para `opslimit` y `memlimit` deben ser utilizados. Estos valores están integrados en el hash generado, por lo que todo lo necesario para verificar el hash está incluido. Esto permite a la función sodium_crypto_pwhash_str_verify() verificar el hash sin necesidad de almacenamiento separado para los otros parámetros.

### Ejemplos

Ejemplo #1 Ejemplo de sodium_crypto_pwhash_str()

    <?php
    $password = 'password';
    echo sodium_crypto_pwhash_str(
        $password,
        SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
        SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
    );

Resultado del ejemplo anterior es similar a:

    $argon2id$v=19$m=65536,t=2,p=1$oWIfdaXwWwhVmovOBc2NAQ$EbsZ+JnZyyavkafS0hoc4HdaOB0ILWZESAZ7kVGa+Iw

### Notas

> Nota: Los hashes son calculados utilizando el algoritmo Argon2ID, proporcionando resistencia tanto a ataques GPU como a ataques por canales laterales. A diferencia de la función password_hash(), no hay parámetro de sal (una sal es generada automáticamente), y los parámetros `opslimit` y `memlimit` no son opcionales.

### Ver también

- sodium_crypto_pwhash_str_verify() - Verifica que una contraseña corresponde a un hash
- sodium_crypto_pwhash() - Deriva una clave a partir de una contraseña, utilizando Argon2
- password_hash() - Crea una clave de hash para una contraseña
- password_verify() - Verifica que una contraseña coincide con un hash
- » Libsodium Argon2 docs

# sodium_crypto_pwhash_str_needs_rehash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str_needs_rehash — Determina si una contraseña debe ser rehacheada

### Descripción

function sodium_crypto_pwhash_str_needs_rehash(string `$password`, int `$opslimit`, int `$memlimit`): bool

Determina si una contraseña debe ser rehacheada, basado en el hash actual `opslimit` y `memlimit`.

### Parámetros

`password`
  El hash de la contraseña
`opslimit`
  La opslimit; ver sodium_crypto_pwhash_str()
`memlimit`
  La memlimit; ver sodium_crypto_pwhash_str()

### Valores devueltos

Devuelve `true` si el memlimit/opslimit proporcionado no corresponde a lo que está almacenado en el hash. Devuelve `false` si corresponden.

# sodium_crypto_pwhash_str_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str_verify — Verifica que una contraseña corresponde a un hash

### Descripción

function sodium_crypto_pwhash_str_verify(string `$hash`, #[\SensitiveParameter]string `$password`): bool

Verifica que un hash de contraseña creado utilizando sodium_crypto_pwhash_str() corresponde a una contraseña en texto claro dada. Tenga en cuenta que los argumentos están en el orden inverso de los mismos argumentos en la función similar password_verify().

### Parámetros

`hash`
  Un hash creado por la función password_hash().
`password`
  La contraseña del usuario.

### Valores devueltos

Devuelve `true` si la contraseña y el hash coinciden, o `false` en caso contrario.

### Notas

> Nota: Los hashes se calculan utilizando el algoritmo Argon2ID, proporcionando resistencia tanto a los ataques GPU como a los ataques por canales laterales.

### Ver también

- sodium_crypto_pwhash_str() - Devuelve un hash codificado en ASCII
- password_hash() - Crea una clave de hash para una contraseña
- password_verify() - Verifica que una contraseña coincide con un hash

# sodium_crypto_scalarmult

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_scalarmult — Calcula un secreto compartido a partir de una clave secreta y una clave pública

### Descripción

function sodium_crypto_scalarmult(string `$n`, string `$p`): string

Curva elíptica Diffie-Hellman. Calcula el escalar n veces el punto p, sobre una curva elíptica.

### Parámetros

`n`
  Escalar, que es típicamente una clave secreta.
`p`
  Un punto (coordenada x), que es típicamente una clave pública.

### Valores devueltos

Una string aleatoria de 32 bytes.

# sodium_crypto_scalarmult_base

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_scalarmult_base — Alias de sodium_crypto_box_publickey_from_secretkey()

### Descripción

Esta función es un alias de: sodium_crypto_box_publickey_from_secretkey().

# sodium_crypto_scalarmult_ristretto255

(PHP 8 >= 8.1.1)

sodium_crypto_scalarmult_ristretto255 — Calcula un secreto compartido

### Descripción

function sodium_crypto_scalarmult_ristretto255(string `$n`, string `$p`): string

Calcula el escalar `n` veces el punto `p`. Disponible a partir de libsodium 1.0.18.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`n`
  Un escalar, que típicamente es una clave secreta.
`p`
  Un punto (coordenada x), que típicamente es una clave pública.

### Valores devueltos

Devuelve una string aleatoria de 32 bytes.

### Ver también

- sodium_crypto_scalarmult_ristretto255_base() - Calcula la clave pública a partir de una clave secreta

# sodium_crypto_scalarmult_ristretto255_base

(PHP 8 >= 8.1.1)

sodium_crypto_scalarmult_ristretto255_base — Calcula la clave pública a partir de una clave secreta

### Descripción

function sodium_crypto_scalarmult_ristretto255_base(string `$n`): string

Dada una clave secreta, calcula la clave pública correspondiente. Disponible a partir de libsodium 1.0.18.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`n`
  Una clave secreta.

### Valores devueltos

Devuelve una string aleatoria de 32 bytes.

### Ver también

- sodium_crypto_scalarmult_ristretto255() - Calcula un secreto compartido

# sodium_crypto_secretbox

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox — Cifrado autenticado con una clave compartida

### Descripción

function sodium_crypto_secretbox(#[\SensitiveParameter]string `$message`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Cifra un mensaje con una clave simétrica (compartida).

### Parámetros

`message`
  El mensaje en claro a cifrar.
`nonce`
  Un número que debe ser utilizado una sola vez, por mensaje. 24 bytes de largo. Este es un límite suficientemente grande para ser generado aleatoriamente (i.e. random_bytes()).
`key`
  La clave de cifrado (256 bits).

### Valores devueltos

Devuelve la cadena cifrada.

### Errores/Excepciones

- Si `nonce` tiene una longitud de bytes diferente de `SODIUM_CRYPTO_SECRETBOX_NONCEBYTES` (24 bytes), una SodiumException será lanzada.
- Si `key` tiene una longitud de bytes diferente de `SODIUM_CRYPTO_SECRETBOX_KEYBYTES` (32 bytes), una SodiumException será lanzada.
- Lanza una SodiumException en caso de fallo.

### Ejemplos

Ejemplo #1 Ejemplo de sodium_crypto_secretbox()

    <?php
    // La $key debe ser mantenida confidencial
    $key = sodium_crypto_secretbox_keygen();
    // No reutilizar $nonce con la misma clave
    $nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
    $plaintext = "mensaje a ser cifrado";
    $ciphertext = sodium_crypto_secretbox($plaintext, $nonce, $key);

    var_dump(bin2hex($ciphertext));
    // El mismo nonce y la misma clave son necesarios para descifrar el $ciphertext
    var_dump(sodium_crypto_secretbox_open($ciphertext, $nonce, $key));
    ?>

Resultado del ejemplo anterior es similar a:

    string(78) "3a1fa3e9f7b72ef8be51d40abf8e296c6899c185d07b18b4c93e7f26aa776d24c50852cd6b1076"
    string(23) "mensaje a ser cifrado"

### Ver también

- sodium_crypto_secretbox_open() - Desencriptación autenticada con una clave compartida
- sodium_crypto_secretbox_keygen() - Genera una clave aleatoria para sodium_crypto_secretbox
- random_bytes() - Obtiene bytes aleatorios criptográficamente seguros

# sodium_crypto_secretbox_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox_keygen — Genera una clave aleatoria para sodium_crypto_secretbox

### Descripción

function sodium_crypto_secretbox_keygen(): string

Genera una clave para ser utilizada con sodium_crypto_secretbox() y sodium_crypto_secretbox_open().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la string generada de bytes aleatorios criptográficamente seguros.

### Ejemplos

Ejemplo #1 Ejemplo de sodium_crypto_secretbox_keygen()

    <?php
    $key = sodium_crypto_secretbox_keygen();
    var_dump( sodium_bin2hex( $key ) );
    ?>

Resultado del ejemplo anterior es similar a:

    string(64) "88bd1dc51ec81984f3ddc5a8f59a3d95b647e2da3e879f1b9ceb0abd89e7286c"

Ejemplo #2 Comparar sodium_crypto_secretbox_keygen() con random_bytes()

    <?php
    $key = sodium_crypto_secretbox_keygen();
    $bytes = random_bytes( SODIUM_CRYPTO_SECRETBOX_KEYBYTES );
    var_dump( mb_strlen( $key, '8bit' ) === mb_strlen( $bytes, '8bit' ) );
    ?>

El ejemplo anterior mostrará:

    bool(true)

### Ver también

- sodium_bin2hex() - Codificar en hexadecimal
- random_bytes() - Obtiene bytes aleatorios criptográficamente seguros

# sodium_crypto_secretbox_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox_open — Desencriptación autenticada con una clave compartida

### Descripción

function sodium_crypto_secretbox_open(string `$ciphertext`, string `$nonce`, #[\SensitiveParameter]string `$key`): string|false

Desencriptación de un mensaje cifrado con una clave simétrica (compartida).

### Parámetros

`ciphertext`
  Debe estar en el formato proporcionado por sodium_crypto_secretbox() (concatenación del texto cifrado y del tag).
`nonce`
  Un número que debe ser utilizado una sola vez, por mensaje. 24 bytes de longitud. Este es un límite suficientemente grande para ser generado aleatoriamente (i.e. random_bytes()).
`key`
  La clave de cifrado (256 bits).

### Valores devueltos

La cadena desencriptada en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

- Si `nonce` tiene una longitud de bytes diferente de `SODIUM_CRYPTO_SECRETBOX_NONCEBYTES` (24 bytes), se lanzará una SodiumException.
- Si `key` tiene una longitud de bytes diferente de `SODIUM_CRYPTO_SECRETBOX_KEYBYTES` (32 bytes), se lanzará una SodiumException.

### Ejemplos

Ejemplo #1 Ejemplo de sodium_crypto_secretbox_open()

    <?php
    // La $key debe ser mantenida confidencial
    $key = random_bytes(SODIUM_CRYPTO_SECRETBOX_KEYBYTES);
    // No reutilizar $nonce con la misma clave
    $nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
    $ciphertext = sodium_crypto_secretbox('mensaje a ser cifrado', $nonce, $key);

    // El mismo nonce y la misma clave son necesarios para desencriptar el $ciphertext
    $plaintext = sodium_crypto_secretbox_open($ciphertext, $nonce, $key);
    if ($plaintext !== false) {
        echo $plaintext . PHP_EOL;
    }
    ?>

El ejemplo anterior mostrará:

    mensaje a ser cifrado

### Ver también

- sodium_crypto_secretbox() - Cifrado autenticado con una clave compartida
- sodium_crypto_secretbox_keygen() - Genera una clave aleatoria para sodium_crypto_secretbox
- random_bytes() - Obtiene bytes aleatorios criptográficamente seguros

# sodium_crypto_secretstream_xchacha20poly1305_init_pull

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_init_pull — Inicializa un contexto secretstream para el descifrado

### Descripción

function sodium_crypto_secretstream_xchacha20poly1305_init_pull(string `$header`, #[\SensitiveParameter]string `$key`): string

Inicializa un contexto secretstream para el descifrado.

### Parámetros

`header`
  La cabecera del secretstream. Debe ser uno de los valores producidos por sodium_crypto_secretstream_xchacha20poly1305_init_push().
`key`
  La clave de cifrado (256 bits).

### Valores devueltos

El estado del secretstream.

### Ejemplos

Ejemplo #1 Ejemplo de sodium_crypto_secretstream_xchacha20poly1305_init_pull()

    <?php
    function decrypt_file(string $inputFilePath, string $outputFilePath, string $key): void
    {
        $inputFile = fopen($inputFilePath, 'rb');
        $outputFile = fopen($outputFilePath, 'wb');
        $header = fread($inputFile, 24);

        $state = sodium_crypto_secretstream_xchacha20poly1305_init_pull($header, $key);
        $inputFileSize = fstat($inputFile)['size'];

        // Descifra el fichero y escribe su contenido en el fichero de salida:
        for ($i = 24; $i < $inputFileSize; $i += 8192) {
            $ctxt_chunk = fread($inputFile, 8192);

            // No se utiliza $tag, pero en protocolos reales, puede ser utilizado para cifrar, por ejemplo
            // desencadenar una nueva clave o indicar el final del fichero. Luego, durante el descifrado, se puede
            // verificar este comportamiento.
            [$ptxt_chunk, $tag] = sodium_crypto_secretstream_xchacha20poly1305_pull($state, $ctxt_chunk);
            fwrite($outputFile, $ptxt_chunk);
        }

        sodium_memzero($state);
        fclose($inputFile);
        fclose($outputFile);
    }

    // sodium_crypto_secretstream_xchacha20poly1305_keygen()
    $key = sodium_base642bin('MS0lzb7HC+thY6jY01pkTE/cwsQxnRq0/2L1eL4Hxn8=', SODIUM_BASE64_VARIANT_ORIGINAL);

    $example = sodium_hex2bin('971e33b255f0990ef3931caf761c59136efa77b434832f28ec719e3ff73f5aec38b3bba1574ab5b70a8844d8da36a668e802cfea2c');
    file_put_contents('hello.enc', $example);
    decrypt_file('hello.enc', 'hello.txt.decrypted', $key);
    var_dump(file_get_contents('hello.txt.decrypted'));
    ?>

Resultado del ejemplo anterior es similar a:

    string(12) "Hello world!"

# sodium_crypto_secretstream_xchacha20poly1305_init_push

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_init_push — Inicializa un contexto secretstream para el cifrado

### Descripción

function sodium_crypto_secretstream_xchacha20poly1305_init_push(#[\SensitiveParameter]string `$key`): array

Inicializa un contexto secretstream para el cifrado.

### Parámetros

`key`
  La clave de cifrado. Ver sodium_crypto_secretstream_xchacha20poly1305_keygen().

### Valores devueltos

Un array con dos valores de string:

- El estado del secretstream, necesario para las próximas llamadas
- El encabezado del secretstream, que debe ser proporcionado al destinatario para que pueda extraer los datos

### Ejemplos

Ejemplo #1 Ejemplo de sodium_crypto_secretstream_xchacha20poly1305_init_push()

    <?php
    function encrypt_file(string $inputFilePath, string $outputFilePath, string $key): void
    {
        [$state, $header] = sodium_crypto_secretstream_xchacha20poly1305_init_push($key);

        $inputFile = fopen($inputFilePath, 'rb');
        $outputFile = fopen($outputFilePath, 'wb');
        // Escribe el encabezado:
        fwrite($outputFile, $header);
        $inputFileSize = fstat($inputFile)['size'];

        // Cifra el fichero y escribe su contenido en el fichero de salida:
        for ($i = 0; $i < $inputFileSize; $i += 8175) {
            $ptxt_chunk = fread($inputFile, 8175);
            $ctxt_chunk = sodium_crypto_secretstream_xchacha20poly1305_push($state, $ptxt_chunk);
            fwrite($outputFile, $ctxt_chunk);
        }

        sodium_memzero($state);
        fclose($inputFile);
        fclose($outputFile);
    }

    // sodium_crypto_secretstream_xchacha20poly1305_keygen()
    $key = sodium_base642bin('MS0lzb7HC+thY6jY01pkTE/cwsQxnRq0/2L1eL4Hxn8=', SODIUM_BASE64_VARIANT_ORIGINAL);

    file_put_contents('hello.txt', 'Hello world!');
    encrypt_file('hello.txt', 'hello.txt.encrypted', $key);
    var_dump(sodium_bin2hex(file_get_contents('hello.txt.encrypted')));
    ?>

Resultado del ejemplo anterior es similar a:

    string(106) "971e33b255f0990ef3931caf761c59136efa77b434832f28ec719e3ff73f5aec38b3bba1574ab5b70a8844d8da36a668e802cfea2c"

# sodium_crypto_secretstream_xchacha20poly1305_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_keygen — Genera una clave secretstream aleatoria.

### Descripción

function sodium_crypto_secretstream_xchacha20poly1305_keygen(): string

Genera una clave secretstream aleatoria.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una string de bytes aleatorios.

# sodium_crypto_secretstream_xchacha20poly1305_pull

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_pull — Desencripta un fragmento de datos de un flujo cifrado

### Descripción

function sodium_crypto_secretstream_xchacha20poly1305_pull(string `&$state`, string `$ciphertext`, string `$additional_data` = ""): array|false

Desencripta un fragmento de datos de un flujo cifrado.

### Parámetros

`state`
  Ver sodium_crypto_secretstream_xchacha20poly1305_init_pull() y sodium_crypto_secretstream_xchacha20poly1305_init_push()
`ciphertext`
  El fragmento de texto cifrado a desencriptar.
`additional_data`
  Opcional de datos adicionales a incluir en la etiqueta de autenticación.

### Valores devueltos

Un array con dos valores:

- string; el fragmento de texto desencriptado.

- int; Una etiqueta opcional (si se proporciona al enviar). Valores posibles:

  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE`: la etiqueta más común, que no añade información sobre la naturaleza del mensaje.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL`: indica que el mensaje marca el final del flujo, y borra la clave secreta utilizada para cifrar la secuencia anterior.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_PUSH`: indica que el mensaje marca el final de un conjunto de mensajes, pero no el final del flujo. Por ejemplo, una enorme cadena JSON enviada en varios fragmentos puede utilizar esta etiqueta para indicar a la aplicación que la cadena está completa y que puede ser decodificada. Pero el flujo mismo no está cerrado, y otros datos pueden seguir.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_REKEY`: "olvidar" la clave utilizada para cifrar este mensaje y los anteriores, y derivar una nueva clave secreta.

# sodium_crypto_secretstream_xchacha20poly1305_push

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_push — Cifra un fragmento de datos para que pueda ser descifrado en una API de streaming

### Descripción

function sodium_crypto_secretstream_xchacha20poly1305_push(
string `&$state`,
#[\SensitiveParameter]string `$message`,
string `$additional_data` = "",
int `$tag` = `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE`
): string

Cifra un fragmento de datos para que pueda ser descifrado en una API de streaming.

### Parámetros

`state`
  Ver sodium_crypto_secretstream_xchacha20poly1305_init_pull() y sodium_crypto_secretstream_xchacha20poly1305_init_push()
`message`
`additional_data`
`tag`
  Opcional. Puede ser utilizado para afirmar el comportamiento de descifrado (es decir, el reordenamiento o la indicación del último fragmento en un flujo).
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE`: la etiqueta más común, que no añade información sobre la naturaleza del mensaje.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL`: indica que el mensaje marca el final del flujo, y borra la clave secreta utilizada para cifrar la secuencia anterior.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_PUSH`: indica que el mensaje marca el final de un conjunto de mensajes, pero no el final del flujo. Por ejemplo, una enorme cadena JSON enviada en varios fragmentos puede utilizar esta etiqueta para indicar a la aplicación que la cadena está completa y que puede ser decodificada. Pero el flujo mismo no está cerrado, y otros datos pueden seguir.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_REKEY`: "olvidar" la clave utilizada para cifrar este mensaje y los anteriores, y derivar una nueva clave secreta.

### Valores devueltos

Devuelve el fragmento de texto cifrado.

# sodium_crypto_secretstream_xchacha20poly1305_rekey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_rekey — Pivota explícitamente la clave en el estado secretstream

### Descripción

function sodium_crypto_secretstream_xchacha20poly1305_rekey(string `&$state`): void

Pivota explícitamente la clave en el estado secretstream. Reemplaza el valor pasado como argumento.

### Parámetros

`state`
  El estado del secretstream.

### Valores devueltos

No se retorna ningún valor.

# sodium_crypto_shorthash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_shorthash — Calcula un hash corto de un mensaje y una clave

### Descripción

function sodium_crypto_shorthash(string `$message`, #[\SensitiveParameter]string `$key`): string

sodium_crypto_shorthash() envuelve una función hash llamada SipHash-2-4, que es ideal para implementar tablas hash que no son susceptibles a ataques de denegación de servicio por colisión de hash (Hash-DoS).

SipHash-2-4 no es una función hash criptográfica general.

### Parámetros

`message`
  El mensaje a hachear.
`key`
  La clave de hash.

### Valores devueltos

# sodium_crypto_shorthash_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_shorthash_keygen — Devuelve bytes aleatorios para la clave

### Descripción

function sodium_crypto_shorthash_keygen(): string

Devuelve una clave para su uso con sodium_crypto_shorthash().

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# sodium_crypto_sign

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign — Firma un mensaje

### Descripción

function sodium_crypto_sign(string `$message`, #[\SensitiveParameter]string `$secret_key`): string

Firma un mensaje con una clave secreta, que puede ser verificada por la clave pública correspondiente. Esta función adjunta la firma al mensaje. Ver sodium_crypto_sign_detached() para las firmas desvinculadas.

### Parámetros

`message`
  El mensaje a firmar.
`secret_key`
  La clave secreta. Ver sodium_crypto_sign_secretkey()

### Valores devueltos

El mensaje firmado (no cifrado).

# sodium_crypto_sign_detached

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_detached — Firma el mensaje

### Descripción

function sodium_crypto_sign_detached(string `$message`, #[\SensitiveParameter]string `$secret_key`): string

Firma un mensaje con una clave secreta, que puede ser verificada por la clave pública correspondiente. Esta función devuelve una firma desvinculada.

### Parámetros

`message`
  El mensaje a firmar.
`secret_key`
  La clave secreta. Ver sodium_crypto_sign_secretkey()

### Valores devueltos

La firma criptográfica.

# sodium_crypto_sign_ed25519_pk_to_curve25519

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_ed25519_pk_to_curve25519 — Convierte una clave pública Ed25519 en una clave pública Curve25519

### Descripción

function sodium_crypto_sign_ed25519_pk_to_curve25519(string `$public_key`): string

Dada una clave pública Ed25519, calcula la clave pública X25519 biracionalmente equivalente.

### Parámetros

`public_key`
  La clave pública adecuada para las funciones crypto_sign.

### Valores devueltos

La clave pública adecuada para las funciones crypto_box.

# sodium_crypto_sign_ed25519_sk_to_curve25519

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_ed25519_sk_to_curve25519 — Convierte una clave secreta Ed25519 en una clave secreta Curve25519

### Descripción

function sodium_crypto_sign_ed25519_sk_to_curve25519(#[\SensitiveParameter]string `$secret_key`): string

Dada una clave secreta Ed25519, se calcula la clave secreta X25519 birationnelmente equivalente.

### Parámetros

`secret_key`
  La clave secreta apropiada para las funciones crypto_sign.

### Valores devueltos

La clave secreta apropiada para las funciones crypto_box.

# sodium_crypto_sign_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_keypair — Genera aleatoriamente una clave secreta y una clave pública correspondiente

### Descripción

function sodium_crypto_sign_keypair(): string

Genera un par de claves Ed25519 aleatorias.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El par de claves Ed25519.

# sodium_crypto_sign_keypair_from_secretkey_and_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_keypair_from_secretkey_and_publickey — Reúne una clave secreta y una clave pública

### Descripción

function sodium_crypto_sign_keypair_from_secretkey_and_publickey(#[\SensitiveParameter]string `$secret_key`, string `$public_key`): string

Reúne una clave secreta y una clave pública.

### Parámetros

`secret_key`
  La clave secreta Ed25519
`public_key`
  La clave pública

### Valores devueltos

Un par de claves

# sodium_crypto_sign_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_open — Verifica que el mensaje firmado posee una firma válida

### Descripción

function sodium_crypto_sign_open(string `$signed_message`, string `$public_key`): string|false

Verifica la firma adjunta a un mensaje y devuelve el mensaje

### Parámetros

`signed_message`
  Un mensaje firmado con sodium_crypto_sign()
`public_key`
  Una clave pública Ed25519

### Valores devueltos

Devuelve el mensaje firmado original en caso de éxito, o `false` si ocurre un error.

# sodium_crypto_sign_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_publickey — Extrae la clave pública Ed25519 de un par de claves

### Descripción

function sodium_crypto_sign_publickey(#[\SensitiveParameter]string `$key_pair`): string

Extrae la clave pública Ed25519 de un par de claves

### Parámetros

`key_pair`
  Un par de claves Ed25519 (ver: sodium_crypto_sign_keypair())

### Valores devueltos

La clave pública Ed25519

# sodium_crypto_sign_publickey_from_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_publickey_from_secretkey — Extrae la clave pública Ed25519 de la clave secreta

### Descripción

function sodium_crypto_sign_publickey_from_secretkey(#[\SensitiveParameter]string `$secret_key`): string

Extrae la clave pública Ed25519 de la clave secreta

### Parámetros

`secret_key`
  La clave secreta Ed25519

### Valores devueltos

La clave pública Ed25519

# sodium_crypto_sign_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_secretkey — Extrae la clave secreta Ed25519 de un par de claves

### Descripción

function sodium_crypto_sign_secretkey(#[\SensitiveParameter]string `$key_pair`): string

Extrae la clave secreta Ed25519 de un par de claves

### Parámetros

`key_pair`
  El par de claves Ed25519 (ver: sodium_crypto_sign_keypair())

### Valores devueltos

La clave secreta Ed25519

# sodium_crypto_sign_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_seed_keypair — Deriva de manera determinista el par de claves a partir de una sola clave

### Descripción

function sodium_crypto_sign_seed_keypair(#[\SensitiveParameter]string `$seed`): string

Adjunta la semilla para formar una clave secreta, deriva la clave pública y devuelve ambas como un par de claves.

Las funciones `*_seed_keypair` son ideales para generar un par de claves a partir de una contraseña y una sal. Utilice el resultado como `seed` para generar las claves deseadas.

### Parámetros

`seed`
  Algunos datos criptográficos. Debe ser de 32 bytes.

### Valores devueltos

Un par de claves (clave secreta y clave pública)

# sodium_crypto_sign_verify_detached

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_verify_detached — Verifica la firma de un mensaje

### Descripción

function sodium_crypto_sign_verify_detached(string `$signature`, string `$message`, string `$public_key`): bool

Verifica la firma de un mensaje

### Parámetros

`signature`
  La firma criptográfica obtenida a partir de sodium_crypto_sign_detached()
`message`
  El mensaje a verificar
`public_key`
  La clave pública Ed25519

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# sodium_crypto_stream

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream — Genera una secuencia de bytes determinista a partir de una semilla

### Descripción

function sodium_crypto_stream(int `$length`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Genera una secuencia de bytes determinista a partir de una semilla, utilizando el cifrado de flujo XSalsa20.

### Parámetros

`length`
  El número de bytes a devolver.
`nonce`
  Un número que debe ser utilizado una sola vez, por mensaje. 24 bytes de largo. Es un límite lo suficientemente grande como para ser generado aleatoriamente (i.e. random_bytes()).
`key`
  La clave de cifrado (256 bits).

### Valores devueltos

Una cadena de bytes pseudoaleatorios.

# sodium_crypto_stream_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream_keygen — Genera una clave de cifrado aleatoria para sodium_crypto_stream

### Descripción

function sodium_crypto_stream_keygen(): string

Genera una clave para ser utilizada con sodium_crypto_stream() y sodium_crypto_stream_xor().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

La clave de cifrado (256 bits).

# sodium_crypto_stream_xchacha20

(PHP 8 >= 8.1.0)

sodium_crypto_stream_xchacha20 — Desarrolla la clave y el nonce en un flujo de claves de bytes pseudoaleatorios

### Descripción

function sodium_crypto_stream_xchacha20(int `$length`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Desarrolla la `clave` y el `nonce` en un flujo de claves de bytes pseudoaleatorios.

### Parámetros

`length`
  El número de bytes deseado.
`nonce`
  Un nonce de 24 bytes.
`key`
  Clave, posiblemente generada por la función sodium_crypto_stream_xchacha20_keygen().

### Valores devueltos

Devuelve un flujo pseudoaleatorio que puede ser utilizado con sodium_crypto_stream_xchacha20_xor().

# sodium_crypto_stream_xchacha20_keygen

(PHP 8 >= 8.1.0)

sodium_crypto_stream_xchacha20_keygen — Devuelve una clave aleatoria segura

### Descripción

function sodium_crypto_stream_xchacha20_keygen(): string

Devuelve una clave aleatoria segura para ser utilizada con sodium_crypto_stream_xchacha20().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una clave segura de 32 bytes para ser utilizada con sodium_crypto_stream_xchacha20().

# sodium_crypto_stream_xchacha20_xor

(PHP 8 >= 8.1.0)

sodium_crypto_stream_xchacha20_xor — Cifra un dato utilizando un nonce y una clave secreta (sin autenticación)

### Descripción

function sodium_crypto_stream_xchacha20_xor(#[\SensitiveParameter]string `$message`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Cifra un `message` utilizando un `nonce` y una clave secreta `key` (sin autenticación).

Precaución

Este cifrado no es autenticado y no previene ataques de texto cifrado elegido. Asegúrese de combinar el texto cifrado con un código de autenticación de mensaje, por ejemplo con la función sodium_crypto_aead_xchacha20poly1305_ietf_encrypt(), o sodium_crypto_auth().

### Parámetros

`message`
  El mensaje a cifrar.
`nonce`
  Un nonce de 24 bytes.
`key`
  Clave, posiblemente generada por la función sodium_crypto_stream_xchacha20_keygen().

### Valores devueltos

El texto cifrado.

### Ver también

- sodium_crypto_stream_xchacha20_xor_ic() - Cifra un mensaje utilizando un nonce y una clave secreta (sin autenticación)

# sodium_crypto_stream_xchacha20_xor_ic

(PHP 8 >= 8.2.0)

sodium_crypto_stream_xchacha20_xor_ic — Cifra un mensaje utilizando un nonce y una clave secreta (sin autenticación)

### Descripción

function sodium_crypto_stream_xchacha20_xor_ic(
#[\SensitiveParameter]string `$message`,
string `$nonce`,
int `$counter`,
#[\SensitiveParameter]string `$key`
): string

Esta función es similar a sodium_crypto_stream_xchacha20_xor() pero añade la posibilidad de establecer el valor inicial del contador de bloques a un valor distinto de cero. Esto permite acceder directamente a cualquier bloque sin tener que calcular los anteriores.

Precaución

Este cifrado no está autenticado y no previene los ataques de texto cifrado elegido. Asegúrese de combinar el texto cifrado con un código de autenticación de mensaje, por ejemplo, con la función sodium_crypto_aead_xchacha20poly1305_ietf_encrypt(), o sodium_crypto_auth().

### Parámetros

`message`
  El mensaje a cifrar.
`nonce`
  Un nonce de 24 bytes.
`counter`
  El valor inicial del contador de bloques.
`key`
  Clave, posiblemente generada por la función sodium_crypto_stream_xchacha20_keygen().

### Valores devueltos

El texto cifrado, o o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de sodium_crypto_stream_xchacha20_xor_ic()

    <?php
    $n2 = random_bytes(SODIUM_CRYPTO_STREAM_XCHACHA20_NONCEBYTES);
    $left  = str_repeat("\x01", 64);
    $right = str_repeat("\xfe", 64);

    // Todo en una vez:
    $stream7_unified = sodium_crypto_stream_xchacha20_xor($left . $right, $n2, $key);

    // Por partes, con un contador inicial:
    $stream7_left  = sodium_crypto_stream_xchacha20_xor_ic($left, $n2, 0, $key);
    $stream7_right = sodium_crypto_stream_xchacha20_xor_ic($right, $n2, 1, $key);
    $stream7_concat = $stream7_left . $stream7_right;

    var_dump(strlen($stream7_concat));
    var_dump($stream7_unified === $stream7_concat);
    ?>

Resultado del ejemplo anterior es similar a:

    int(128)
    bool(true)

### Ver también

- sodium_crypto_stream_xchacha20_xor() - Cifra un dato utilizando un nonce y una clave secreta (sin autenticación)

# sodium_crypto_stream_xor

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream_xor — Cifra un mensaje sin autenticación

### Descripción

function sodium_crypto_stream_xor(#[\SensitiveParameter]string `$message`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Esta función cifra un mensaje con XSalsa20, pero no proporciona ninguna garantía sobre el texto cifrado.

### Parámetros

`message`
  El mensaje a cifrar.
`nonce`
  Un número que debe ser utilizado una sola vez, por mensaje. 24 bytes de largo. Es un límite suficientemente grande para ser generado aleatoriamente (i.e. random_bytes()).
`key`
  La clave de cifrado (256 bits).

### Valores devueltos

El mensaje cifrado.

# sodium_hex2bin

(PHP 7 >= 7.2.0, PHP 8)

sodium_hex2bin — Decodifica una cadena binaria codificada en hexadecimal

### Descripción

function sodium_hex2bin(#[\SensitiveParameter]string `$string`, string `$ignore` = ""): string

Decodifica una cadena binaria codificada en hexadecimal.

Al igual que sodium_bin2hex(), sodium_hex2bin() son resistentes a ataques por canales secundarios, mientras que hex2bin() no lo es.

### Parámetros

`string`
  La representación hexadecimal de los datos.
`ignore`
  Una cadena de caracteres opcional para los caracteres a ignorar.

### Valores devueltos

Devuelve la representación binaria de los datos de la cadena `string`.

# sodium_increment

(PHP 7 >= 7.2.0, PHP 8)

sodium_increment — Incrementa un número grande

### Descripción

function sodium_increment(string `&$string`): void

Trata la string como un entero sin signo en little-endian, luego la incrementa en 1. Tiempo constante.

### Parámetros

`string`
  La string a incrementar.

### Valores devueltos

No se retorna ningún valor.

# sodium_memcmp

(PHP 7 >= 7.2.0, PHP 8)

sodium_memcmp — Prueba la igualdad en tiempo constante

### Descripción

function sodium_memcmp(#[\SensitiveParameter]string `$string1`, #[\SensitiveParameter]string `$string2`): int

Compara dos strings en tiempo constante.

En la práctica, casi siempre se desea utilizar hash_equals() en su lugar, ya que proporciona la misma lógica pero devuelve un bool en lugar de un int. Sin embargo, si se utiliza el valor de retorno de una comparación en un cálculo que es sensible al tiempo, y se teme que las conversiones bool-to-int provoquen fugas de tiempo, sodium_memcmp() es un reemplazo ideal.

### Parámetros

`string1`
  La string a comparar
`string2`
  La otra string a comparar

### Valores devueltos

Devuelve `0` si las dos strings son iguales; `-1` en caso contrario.

# sodium_memzero

(PHP 7 >= 7.2.0, PHP 8)

sodium_memzero — Sobrescribe una string con caracteres NUL

### Descripción

function sodium_memzero(#[\SensitiveParameter]string `&$string`): void

sodium_memzero() reemplaza por ceros la string pasada por referencia.

### Parámetros

`string`
  String.

### Valores devueltos

No se retorna ningún valor.

# sodium_pad

(PHP 7 >= 7.2.0, PHP 8)

sodium_pad — Añade datos de relleno

### Descripción

function sodium_pad(#[\SensitiveParameter]string `$string`, int `$block_size`): string

Rellena a la derecha una string hasta la longitud deseada. Seguro en términos de tiempo.

### Parámetros

`string`
  La string sin rellenar.
`block_size`
  La string será rellenada hasta que sea un múltiplo par del tamaño del bloque.

### Valores devueltos

La string rellenada.

# sodium_unpad

(PHP 7 >= 7.2.0, PHP 8)

sodium_unpad — Elimina los datos de relleno

### Descripción

function sodium_unpad(#[\SensitiveParameter]string `$string`, int `$block_size`): string

Elimina los datos de relleno de una string. Seguro en términos de tiempo.

### Parámetros

`string`
  La string rellena.
`block_size`
  El tamaño del bloque para el relleno.

### Valores devueltos

La string sin relleno.

## Tabla de contenidos

- sodium_add — Suma grandes números
- sodium_base642bin — Decodifica una cadena codificada en base64 en binario sin tratar.
- sodium_bin2base64 — Codifica una string binaria bruta en base64.
- sodium_bin2hex — Codificar en hexadecimal
- sodium_compare — Comparar grandes números
- sodium_crypto_aead_aegis128l_decrypt — Verifica y luego descifra un mensaje con AEGIS-128L
- sodium_crypto_aead_aegis128l_encrypt — Cifra y autentica un mensaje con AEGIS-128L
- sodium_crypto_aead_aegis128l_keygen — Genera una clave AEGIS-128L aleatoria
- sodium_crypto_aead_aegis256_decrypt — Verifica y luego descifra un mensaje con AEGIS-256
- sodium_crypto_aead_aegis256_encrypt — Cifra y autentica un mensaje con AEGIS-256
- sodium_crypto_aead_aegis256_keygen — Genera una clave AEGIS-256 aleatoria
- sodium_crypto_aead_aes256gcm_decrypt — Verifica y luego descifra un mensaje con AES-256-GCM
- sodium_crypto_aead_aes256gcm_encrypt — Cifra y autentica con AES-256-GCM
- sodium_crypto_aead_aes256gcm_is_available — Verifica si el hardware soporta AES256-GCM
- sodium_crypto_aead_aes256gcm_keygen — Genera una clave AES-256-GCM aleatoria
- sodium_crypto_aead_chacha20poly1305_decrypt — Verifica y luego descifra con ChaCha20-Poly1305
- sodium_crypto_aead_chacha20poly1305_encrypt — Cifra y autentica con ChaCha20-Poly1305
- sodium_crypto_aead_chacha20poly1305_ietf_decrypt — Verifica que el texto cifrado incluye una etiqueta válida
- sodium_crypto_aead_chacha20poly1305_ietf_encrypt — Cifra un mensaje
- sodium_crypto_aead_chacha20poly1305_ietf_keygen — Genera una clave ChaCha20-Poly1305 (IETF) aleatoria
- sodium_crypto_aead_chacha20poly1305_keygen — Genera una clave ChaCha20-Poly1305 aleatoria
- sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — (Preferido) Verificar y luego descifrar con XChaCha20-Poly1305
- sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — (Preferido) Cifra y luego autentica con XChaCha20-Poly1305
- sodium_crypto_aead_xchacha20poly1305_ietf_keygen — Genera una clave ChaCha20-Poly1305 aleatoria
- sodium_crypto_auth — Calcula una etiqueta para el mensaje
- sodium_crypto_auth_keygen — Genera una clave aleatoria para sodium_crypto_auth
- sodium_crypto_auth_verify — Verifica que la etiqueta es válida para el mensaje
- sodium_crypto_box — Cifrado asimétrico autenticado
- sodium_crypto_box_keypair — Genera aleatoriamente una clave secreta y una clave pública correspondiente
- sodium_crypto_box_keypair_from_secretkey_and_publickey — Crear una pareja de claves unificada a partir de una clave secreta y una clave pública
- sodium_crypto_box_open — Desencriptación autenticada con clave pública
- sodium_crypto_box_publickey — Extrae la clave pública de un par de claves crypto_box
- sodium_crypto_box_publickey_from_secretkey — Calcula la clave pública a partir de una clave secreta
- sodium_crypto_box_seal — Cifrado anónimo con clave pública
- sodium_crypto_box_seal_open — Desencriptación anónima con clave pública
- sodium_crypto_box_secretkey — Extrae la clave secreta de un par de claves crypto_box
- sodium_crypto_box_seed_keypair — Deriva de manera determinista el par de claves a partir de una sola clave
- sodium_crypto_core_ristretto255_add — Añade un elemento
- sodium_crypto_core_ristretto255_from_hash — Mapea un vector
- sodium_crypto_core_ristretto255_is_valid_point — Determina si un punto está en la curva ristretto255
- sodium_crypto_core_ristretto255_random — Genera una clave aleatoria
- sodium_crypto_core_ristretto255_scalar_add — Añade un valor escalar
- sodium_crypto_core_ristretto255_scalar_complement — El propósito de sodium_crypto_core_ristretto255_scalar_complement
- sodium_crypto_core_ristretto255_scalar_invert — Invierte un valor escalar
- sodium_crypto_core_ristretto255_scalar_mul — Multiplica un valor escalar
- sodium_crypto_core_ristretto255_scalar_negate — Invierte el signo de un valor escalar
- sodium_crypto_core_ristretto255_scalar_random — Genera una clave aleatoria
- sodium_crypto_core_ristretto255_scalar_reduce — Reduce un valor escalar
- sodium_crypto_core_ristretto255_scalar_sub — Sustrae un valor escalar
- sodium_crypto_core_ristretto255_sub — Sustrae un elemento
- sodium_crypto_generichash — Devuelve un hash del mensaje
- sodium_crypto_generichash_final — Completa el hash
- sodium_crypto_generichash_init — Inicializa un hash para el streaming
- sodium_crypto_generichash_keygen — Genera una clave de hash genérico aleatoria
- sodium_crypto_generichash_update — Añade un mensaje a un hash
- sodium_crypto_kdf_derive_from_key — Deriva una subclave
- sodium_crypto_kdf_keygen — Genera una clave raíz aleatoria para la interfaz KDF
- sodium_crypto_kx_client_session_keys — Calcula las claves de sesión del lado del cliente.
- sodium_crypto_kx_keypair — Crear una nueva pareja de claves sodium
- sodium_crypto_kx_publickey — Extrae la clave pública de un par de claves crypto_kx
- sodium_crypto_kx_secretkey — Extrae la clave secreta de un par de claves crypto_kx
- sodium_crypto_kx_seed_keypair — Descripción
- sodium_crypto_kx_server_session_keys — Calcula las claves de sesión del lado del servidor.
- sodium_crypto_pwhash — Deriva una clave a partir de una contraseña, utilizando Argon2
- sodium_crypto_pwhash_scryptsalsa208sha256 — Deriva una clave a partir de una contraseña, utilizando scrypt
- sodium_crypto_pwhash_scryptsalsa208sha256_str — Devuelve un hash codificado en ASCII
- sodium_crypto_pwhash_scryptsalsa208sha256_str_verify — Verifica si la contraseña corresponde a una cadena de hash de contraseña
- sodium_crypto_pwhash_str — Devuelve un hash codificado en ASCII
- sodium_crypto_pwhash_str_needs_rehash — Determina si una contraseña debe ser rehacheada
- sodium_crypto_pwhash_str_verify — Verifica que una contraseña corresponde a un hash
- sodium_crypto_scalarmult — Calcula un secreto compartido a partir de una clave secreta y una clave pública
- sodium_crypto_scalarmult_base — Alias de sodium_crypto_box_publickey_from_secretkey
- sodium_crypto_scalarmult_ristretto255 — Calcula un secreto compartido
- sodium_crypto_scalarmult_ristretto255_base — Calcula la clave pública a partir de una clave secreta
- sodium_crypto_secretbox — Cifrado autenticado con una clave compartida
- sodium_crypto_secretbox_keygen — Genera una clave aleatoria para sodium_crypto_secretbox
- sodium_crypto_secretbox_open — Desencriptación autenticada con una clave compartida
- sodium_crypto_secretstream_xchacha20poly1305_init_pull — Inicializa un contexto secretstream para el descifrado
- sodium_crypto_secretstream_xchacha20poly1305_init_push — Inicializa un contexto secretstream para el cifrado
- sodium_crypto_secretstream_xchacha20poly1305_keygen — Genera una clave secretstream aleatoria.
- sodium_crypto_secretstream_xchacha20poly1305_pull — Desencripta un fragmento de datos de un flujo cifrado
- sodium_crypto_secretstream_xchacha20poly1305_push — Cifra un fragmento de datos para que pueda ser descifrado en una API de streaming
- sodium_crypto_secretstream_xchacha20poly1305_rekey — Pivota explícitamente la clave en el estado secretstream
- sodium_crypto_shorthash — Calcula un hash corto de un mensaje y una clave
- sodium_crypto_shorthash_keygen — Devuelve bytes aleatorios para la clave
- sodium_crypto_sign — Firma un mensaje
- sodium_crypto_sign_detached — Firma el mensaje
- sodium_crypto_sign_ed25519_pk_to_curve25519 — Convierte una clave pública Ed25519 en una clave pública Curve25519
- sodium_crypto_sign_ed25519_sk_to_curve25519 — Convierte una clave secreta Ed25519 en una clave secreta Curve25519
- sodium_crypto_sign_keypair — Genera aleatoriamente una clave secreta y una clave pública correspondiente
- sodium_crypto_sign_keypair_from_secretkey_and_publickey — Reúne una clave secreta y una clave pública
- sodium_crypto_sign_open — Verifica que el mensaje firmado posee una firma válida
- sodium_crypto_sign_publickey — Extrae la clave pública Ed25519 de un par de claves
- sodium_crypto_sign_publickey_from_secretkey — Extrae la clave pública Ed25519 de la clave secreta
- sodium_crypto_sign_secretkey — Extrae la clave secreta Ed25519 de un par de claves
- sodium_crypto_sign_seed_keypair — Deriva de manera determinista el par de claves a partir de una sola clave
- sodium_crypto_sign_verify_detached — Verifica la firma de un mensaje
- sodium_crypto_stream — Genera una secuencia de bytes determinista a partir de una semilla
- sodium_crypto_stream_keygen — Genera una clave de cifrado aleatoria para sodium_crypto_stream
- sodium_crypto_stream_xchacha20 — Desarrolla la clave y el nonce en un flujo de claves de bytes pseudoaleatorios
- sodium_crypto_stream_xchacha20_keygen — Devuelve una clave aleatoria segura
- sodium_crypto_stream_xchacha20_xor — Cifra un dato utilizando un nonce y una clave secreta (sin autenticación)
- sodium_crypto_stream_xchacha20_xor_ic — Cifra un mensaje utilizando un nonce y una clave secreta (sin autenticación)
- sodium_crypto_stream_xor — Cifra un mensaje sin autenticación
- sodium_hex2bin — Decodifica una cadena binaria codificada en hexadecimal
- sodium_increment — Incrementa un número grande
- sodium_memcmp — Prueba la igualdad en tiempo constante
- sodium_memzero — Sobrescribe una string con caracteres NUL
- sodium_pad — Añade datos de relleno
- sodium_unpad — Elimina los datos de relleno

# La clase SodiumException

(PHP 7 >= 7.2.0, PHP 8)

## Introducción

Excepción lanzada por las funciones sodium.

## Sinopsis de la Clase

class SodiumException extends Exception {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

- Instalación/Configuración
  - Requerimientos
  - Instalación
- Constantes predefinidas
- Sodium Funciones
  - sodium_add — Suma grandes números
  - sodium_base642bin — Decodifica una cadena codificada en base64 en binario sin tratar.
  - sodium_bin2base64 — Codifica una string binaria bruta en base64.
  - sodium_bin2hex — Codificar en hexadecimal
  - sodium_compare — Comparar grandes números
  - sodium_crypto_aead_aegis128l_decrypt — Verifica y luego descifra un mensaje con AEGIS-128L
  - sodium_crypto_aead_aegis128l_encrypt — Cifra y autentica un mensaje con AEGIS-128L
  - sodium_crypto_aead_aegis128l_keygen — Genera una clave AEGIS-128L aleatoria
  - sodium_crypto_aead_aegis256_decrypt — Verifica y luego descifra un mensaje con AEGIS-256
  - sodium_crypto_aead_aegis256_encrypt — Cifra y autentica un mensaje con AEGIS-256
  - sodium_crypto_aead_aegis256_keygen — Genera una clave AEGIS-256 aleatoria
  - sodium_crypto_aead_aes256gcm_decrypt — Verifica y luego descifra un mensaje con AES-256-GCM
  - sodium_crypto_aead_aes256gcm_encrypt — Cifra y autentica con AES-256-GCM
  - sodium_crypto_aead_aes256gcm_is_available — Verifica si el hardware soporta AES256-GCM
  - sodium_crypto_aead_aes256gcm_keygen — Genera una clave AES-256-GCM aleatoria
  - sodium_crypto_aead_chacha20poly1305_decrypt — Verifica y luego descifra con ChaCha20-Poly1305
  - sodium_crypto_aead_chacha20poly1305_encrypt — Cifra y autentica con ChaCha20-Poly1305
  - sodium_crypto_aead_chacha20poly1305_ietf_decrypt — Verifica que el texto cifrado incluye una etiqueta válida
  - sodium_crypto_aead_chacha20poly1305_ietf_encrypt — Cifra un mensaje
  - sodium_crypto_aead_chacha20poly1305_ietf_keygen — Genera una clave ChaCha20-Poly1305 (IETF) aleatoria
  - sodium_crypto_aead_chacha20poly1305_keygen — Genera una clave ChaCha20-Poly1305 aleatoria
  - sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — (Preferido) Verificar y luego descifrar con XChaCha20-Poly1305
  - sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — (Preferido) Cifra y luego autentica con XChaCha20-Poly1305
  - sodium_crypto_aead_xchacha20poly1305_ietf_keygen — Genera una clave ChaCha20-Poly1305 aleatoria
  - sodium_crypto_auth — Calcula una etiqueta para el mensaje
  - sodium_crypto_auth_keygen — Genera una clave aleatoria para sodium_crypto_auth
  - sodium_crypto_auth_verify — Verifica que la etiqueta es válida para el mensaje
  - sodium_crypto_box — Cifrado asimétrico autenticado
  - sodium_crypto_box_keypair — Genera aleatoriamente una clave secreta y una clave pública correspondiente
  - sodium_crypto_box_keypair_from_secretkey_and_publickey — Crear una pareja de claves unificada a partir de una clave secreta y una clave pública
  - sodium_crypto_box_open — Desencriptación autenticada con clave pública
  - sodium_crypto_box_publickey — Extrae la clave pública de un par de claves crypto_box
  - sodium_crypto_box_publickey_from_secretkey — Calcula la clave pública a partir de una clave secreta
  - sodium_crypto_box_seal — Cifrado anónimo con clave pública
  - sodium_crypto_box_seal_open — Desencriptación anónima con clave pública
  - sodium_crypto_box_secretkey — Extrae la clave secreta de un par de claves crypto_box
  - sodium_crypto_box_seed_keypair — Deriva de manera determinista el par de claves a partir de una sola clave
  - sodium_crypto_core_ristretto255_add — Añade un elemento
  - sodium_crypto_core_ristretto255_from_hash — Mapea un vector
  - sodium_crypto_core_ristretto255_is_valid_point — Determina si un punto está en la curva ristretto255
  - sodium_crypto_core_ristretto255_random — Genera una clave aleatoria
  - sodium_crypto_core_ristretto255_scalar_add — Añade un valor escalar
  - sodium_crypto_core_ristretto255_scalar_complement — El propósito de sodium_crypto_core_ristretto255_scalar_complement
  - sodium_crypto_core_ristretto255_scalar_invert — Invierte un valor escalar
  - sodium_crypto_core_ristretto255_scalar_mul — Multiplica un valor escalar
  - sodium_crypto_core_ristretto255_scalar_negate — Invierte el signo de un valor escalar
  - sodium_crypto_core_ristretto255_scalar_random — Genera una clave aleatoria
  - sodium_crypto_core_ristretto255_scalar_reduce — Reduce un valor escalar
  - sodium_crypto_core_ristretto255_scalar_sub — Sustrae un valor escalar
  - sodium_crypto_core_ristretto255_sub — Sustrae un elemento
  - sodium_crypto_generichash — Devuelve un hash del mensaje
  - sodium_crypto_generichash_final — Completa el hash
  - sodium_crypto_generichash_init — Inicializa un hash para el streaming
  - sodium_crypto_generichash_keygen — Genera una clave de hash genérico aleatoria
  - sodium_crypto_generichash_update — Añade un mensaje a un hash
  - sodium_crypto_kdf_derive_from_key — Deriva una subclave
  - sodium_crypto_kdf_keygen — Genera una clave raíz aleatoria para la interfaz KDF
  - sodium_crypto_kx_client_session_keys — Calcula las claves de sesión del lado del cliente.
  - sodium_crypto_kx_keypair — Crear una nueva pareja de claves sodium
  - sodium_crypto_kx_publickey — Extrae la clave pública de un par de claves crypto_kx
  - sodium_crypto_kx_secretkey — Extrae la clave secreta de un par de claves crypto_kx
  - sodium_crypto_kx_seed_keypair — Descripción
  - sodium_crypto_kx_server_session_keys — Calcula las claves de sesión del lado del servidor.
  - sodium_crypto_pwhash — Deriva una clave a partir de una contraseña, utilizando Argon2
  - sodium_crypto_pwhash_scryptsalsa208sha256 — Deriva una clave a partir de una contraseña, utilizando scrypt
  - sodium_crypto_pwhash_scryptsalsa208sha256_str — Devuelve un hash codificado en ASCII
  - sodium_crypto_pwhash_scryptsalsa208sha256_str_verify — Verifica si la contraseña corresponde a una cadena de hash de contraseña
  - sodium_crypto_pwhash_str — Devuelve un hash codificado en ASCII
  - sodium_crypto_pwhash_str_needs_rehash — Determina si una contraseña debe ser rehacheada
  - sodium_crypto_pwhash_str_verify — Verifica que una contraseña corresponde a un hash
  - sodium_crypto_scalarmult — Calcula un secreto compartido a partir de una clave secreta y una clave pública
  - sodium_crypto_scalarmult_base — Alias de sodium_crypto_box_publickey_from_secretkey
  - sodium_crypto_scalarmult_ristretto255 — Calcula un secreto compartido
  - sodium_crypto_scalarmult_ristretto255_base — Calcula la clave pública a partir de una clave secreta
  - sodium_crypto_secretbox — Cifrado autenticado con una clave compartida
  - sodium_crypto_secretbox_keygen — Genera una clave aleatoria para sodium_crypto_secretbox
  - sodium_crypto_secretbox_open — Desencriptación autenticada con una clave compartida
  - sodium_crypto_secretstream_xchacha20poly1305_init_pull — Inicializa un contexto secretstream para el descifrado
  - sodium_crypto_secretstream_xchacha20poly1305_init_push — Inicializa un contexto secretstream para el cifrado
  - sodium_crypto_secretstream_xchacha20poly1305_keygen — Genera una clave secretstream aleatoria.
  - sodium_crypto_secretstream_xchacha20poly1305_pull — Desencripta un fragmento de datos de un flujo cifrado
  - sodium_crypto_secretstream_xchacha20poly1305_push — Cifra un fragmento de datos para que pueda ser descifrado en una API de streaming
  - sodium_crypto_secretstream_xchacha20poly1305_rekey — Pivota explícitamente la clave en el estado secretstream
  - sodium_crypto_shorthash — Calcula un hash corto de un mensaje y una clave
  - sodium_crypto_shorthash_keygen — Devuelve bytes aleatorios para la clave
  - sodium_crypto_sign — Firma un mensaje
  - sodium_crypto_sign_detached — Firma el mensaje
  - sodium_crypto_sign_ed25519_pk_to_curve25519 — Convierte una clave pública Ed25519 en una clave pública Curve25519
  - sodium_crypto_sign_ed25519_sk_to_curve25519 — Convierte una clave secreta Ed25519 en una clave secreta Curve25519
  - sodium_crypto_sign_keypair — Genera aleatoriamente una clave secreta y una clave pública correspondiente
  - sodium_crypto_sign_keypair_from_secretkey_and_publickey — Reúne una clave secreta y una clave pública
  - sodium_crypto_sign_open — Verifica que el mensaje firmado posee una firma válida
  - sodium_crypto_sign_publickey — Extrae la clave pública Ed25519 de un par de claves
  - sodium_crypto_sign_publickey_from_secretkey — Extrae la clave pública Ed25519 de la clave secreta
  - sodium_crypto_sign_secretkey — Extrae la clave secreta Ed25519 de un par de claves
  - sodium_crypto_sign_seed_keypair — Deriva de manera determinista el par de claves a partir de una sola clave
  - sodium_crypto_sign_verify_detached — Verifica la firma de un mensaje
  - sodium_crypto_stream — Genera una secuencia de bytes determinista a partir de una semilla
  - sodium_crypto_stream_keygen — Genera una clave de cifrado aleatoria para sodium_crypto_stream
  - sodium_crypto_stream_xchacha20 — Desarrolla la clave y el nonce en un flujo de claves de bytes pseudoaleatorios
  - sodium_crypto_stream_xchacha20_keygen — Devuelve una clave aleatoria segura
  - sodium_crypto_stream_xchacha20_xor — Cifra un dato utilizando un nonce y una clave secreta (sin autenticación)
  - sodium_crypto_stream_xchacha20_xor_ic — Cifra un mensaje utilizando un nonce y una clave secreta (sin autenticación)
  - sodium_crypto_stream_xor — Cifra un mensaje sin autenticación
  - sodium_hex2bin — Decodifica una cadena binaria codificada en hexadecimal
  - sodium_increment — Incrementa un número grande
  - sodium_memcmp — Prueba la igualdad en tiempo constante
  - sodium_memzero — Sobrescribe una string con caracteres NUL
  - sodium_pad — Añade datos de relleno
  - sodium_unpad — Elimina los datos de relleno
- SodiumException — La clase SodiumException

# Xpass

# Introducción

Esta extensión proporciona algoritmos hash de contraseñas utilizados por las distribuciones de Linux, utilizando la biblioteca extendida crypt.

También proporciona funciones libxcrypt adicionales que faltan en PHP.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación vía PECL

## Requerimientos

Esta extensión requiere » libxcrypt versión 4.4 o superior.

## Instalación vía PECL

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/xpass.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

La extensión Xpass proporciona diversos conjuntos de constantes. Métodos de hash (`CRYPT_PREFIX_*`) para el parámetro prefix de crypt_gensalt(). Códigos de error (`CRYPT_SALT_*`) devueltos por crypt_checksalt(). Algoritmos de contraseña (`PASSWORD_*`) para el parámetro algo de password_hash().

Métodos de hash
`CRYPT_PREFIX_STD_DES` (string)
  El método de hash original de Unix V7, basado en el cifrado por bloques DES. Dado que DES es poco costoso en el hardware moderno, solo hay `4096` salts posibles y 2**56 contraseñas distintas, que se truncan a 8 caracteres, es posible encontrar cualquier contraseña hasheada con este método. No debería usarse excepto para soportar sistemas operativos antiguos que no soportan ningún otro algoritmo de generación de hash, debido a la debilidad de los hashes DES.
`CRYPT_PREFIX_EXT_DES` (string)
  Una extensión del DES tradicional, que elimina el límite de longitud, aumenta el tamaño del salt y hace el costo temporal ajustable. Proviene de BSDI BSD/OS y también está disponible en al menos NetBSD, OpenBSD y FreeBSD debido al uso de la biblioteca FreeSec de David Burren. Es mucho mejor que los hashes DES tradicionales y bigcrypt, pero aún no debería usarse para nuevos hashes.
`CRYPT_PREFIX_MD5` (string)
  Un hash basado en el algoritmo MD5, desarrollado originalmente por Poul-Henning Kamp para FreeBSD. Soportado en la mayoría de los Unix libres y versiones más recientes de Solaris. No tan débil como los hashes basados en DES, pero MD5 es tan poco costoso en el hardware moderno que no debería usarse para nuevos hashes. El costo de procesamiento no es ajustable.
`CRYPT_PREFIX_BLOWFISH` (string)
  Un hash basado en el cifrado por bloques Blowfish, modificado para tener un calendario de claves extra-costoso. Desarrollado originalmente por Niels Provos y David Mazieres para OpenBSD y también soportado en versiones recientes de FreeBSD y NetBSD, en Solaris 10 y más reciente, y en varias distribuciones GNU/*/Linux.
`CRYPT_PREFIX_SHA256` (string)
  Un hash basado en SHA-2 con una salida de 256 bits, desarrollado originalmente por Ulrich Drepper para GNU libc. Soportado en Linux pero no común en otros lugares. Aceptable para nuevos hashes. El parámetro de costo de procesamiento por defecto es `5000`, lo cual es demasiado bajo para el hardware moderno.
`CRYPT_PREFIX_SHA512` (string)
  Un hash basado en SHA-2 con una salida de 512 bits, desarrollado originalmente por Ulrich Drepper para GNU libc. Soportado en Linux pero no común en otros lugares. Aceptable para nuevos hashes. El parámetro de costo de procesamiento por defecto es `5000`, lo cual es demasiado bajo para el hardware moderno.
`CRYPT_PREFIX_SCRYPT` (string)
  Scrypt es una función de derivación de clave basada en contraseña creada por Colin Percival, originalmente para el servicio de respaldo en línea Tarsnap. El algoritmo fue diseñado específicamente para hacer costosas las ataques de hardware personalizados a gran escala al requerir grandes cantidades de memoria. En 2016, el algoritmo scrypt fue publicado por el IETF como RFC 7914.
`CRYPT_PREFIX_GOST_YESCRYPT` (string)
  Gost-yescrypt usa la salida de yescrypt como mensaje de entrada para HMAC con la función de hash GOST R 34.11-2012 (Streebog) con un resumen de 256 bits. Así, las propiedades criptográficas de yescrypt son suplantadas por las de la función de hash GOST. Este método de hash es útil en aplicaciones que requieren un hash de contraseña moderno, pero deben basarse en algoritmos GOST. La función de hash GOST R 34.11-2012 (Streebog) fue publicada por el IETF como RFC 6986. Aceptable para nuevos hashes si es necesario.
`CRYPT_PREFIX_YESCRYPT` (string)
  Yescrypt es un esquema de hash de contraseña escalable diseñado por Solar Designer, que se basa en el scrypt de Colin Percival. Aunque la fuerza de yescrypt contra los ataques de adivinación de contraseñas proviene de su diseño de algoritmo, su seguridad criptográfica está garantizada por su uso de SHA-256 en la capa externa. La función de hash SHA-256 fue publicada por el NIST en el FIPS PUB 180-2 (y sus revisiones posteriores como el FIPS PUB 180-4) y por el IETF como RFC 4634 (y posteriormente RFC 6234). Recomendado para nuevos hashes.
`CRYPT_PREFIX_SM3CRYPT` (string)
  Un hash basado en la función de hash ShangMi 3 con una salida de 256 bits, que usa el mismo diseño que sha256crypt y/o sha512crypt. Soportado en EulerOS, Kylin, openEuler y openKylin, pero no es común en otros lugares. Aceptable para nuevos hashes si es necesario. El parámetro de costo de procesamiento por defecto es 5000, lo cual es demasiado bajo para el hardware moderno. Disponible a partir de 1.2.0 con libcxcrypt >= 4.5.0.
`CRYPT_PREFIX_SM3_YESCRYPT` (string)
  Sm3-yescrypt usa la salida de yescrypt como mensaje de entrada para HMAC con la función de hash ShangMi 3 con un resumen de 256 bits. Así, las propiedades criptográficas de yescrypt son suplantadas por las de la función de hash ShangMi 3. Este método de hash es útil en aplicaciones que necesitan un hash de contraseña moderno, pero deben basarse en algoritmos aprobados por la Oficina de Administración de Criptografía Comercial del Estado de China (OSCCA). La función de hash ShangMi 3 ha sido publicada en la Parte 3: "Dedicated hash-functions" de la ISO/IEC 10118-3:2018. Aceptable para nuevos hashes si es necesario. Disponible a partir de 1.2.0 con libcxcrypt >= 4.5.0.

Códigos de error
`CRYPT_SALT_OK` (int)
  No hay error.
`CRYPT_SALT_INVALID` (int)
  Método de hash desconocido o parámetros inválidos.
`CRYPT_SALT_METHOD_DISABLED` (int)
  El método de hash ya no está permitido para ser usado.
`CRYPT_SALT_METHOD_LEGACY` (int)
  El método de hash ya no se considera lo suficientemente fuerte.
`CRYPT_SALT_TOO_CHEAP` (int)
  El costo de los parámetros se considera demasiado bajo.

Algoritmos de contraseña
`PASSWORD_SHA512` (string)
  `PASSWORD_SHA512` se usa para crear nuevos hashes de contraseña usando el algoritmo `CRYPT_PREFIX_SHA512`.
`PASSWORD_YESCRYPT` (string)
  `PASSWORD_YESCRYPT` se usa para crear nuevos hashes de contraseña usando el algoritmo `CRYPT_PREFIX_YESCRYPT`.
`PASSWORD_SM3CRYPT` (string)
  `PASSWORD_SM3CRYPT` se usa para crear nuevos hashes de contraseña usando el algoritmo `CRYPT_PREFIX_SM3CRYPT`. Disponible a partir de 1.2.0 con libcxcrypt >= 4.5.0.
`PASSWORD_SM3_YESCRYPT` (string)
  `PASSWORD_SM3_YESCRYPT` se usa para crear nuevos hashes de contraseña usando el algoritmo `CRYPT_PREFIX_SM3_YESCRYPT`. Disponible a partir de 1.2.0 con libcxcrypt >= 4.5.0.

# Funciones Xpass

# crypt_checksalt

(PECL xpass >= 1.1.0)

crypt_checksalt — Valida un parámetro de hash de contraseña

### Descripción

function crypt_checksalt(string `$salt`): ?string

Verifica si la cadena de sal cumple con la configuración del sistema y señala si el método de hash y los parámetros que especifica son aceptables. Está destinado a ser utilizado para determinar si la contraseña del usuario debe ser rehasheada utilizando el método de hash actualmente preferido.

### Parámetros

`salt`
  La cadena de sal a verificar.

### Valores devueltos

Devuelve una de las constantes `CRYPT_SALT_*` como int.

### Ejemplos

Ejemplo #1 Un ejemplo de crypt_checksalt()

    <?php
    // Genera una sal para un método obsoleto
    $salt = crypt_gensalt(CRYPT_PREFIX_STD_DES);
    // Verifica la sal
    $test = crypt_checksalt($salt);
    var_dump($test === CRYPT_SALT_METHOD_LEGACY);

    // Genera una sal para un método por defecto
    $salt = crypt_gensalt();
    // Verifica la sal
    $test = crypt_checksalt($salt);
    var_dump($test === CRYPT_SALT_OK);
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(true)

### Ver también

- crypt_gensalt() - Compila una cadena para usar como argumento de sal para crypt

# crypt_gensalt

(PECL xpass >= 1.1.0)

crypt_gensalt — Compila una cadena para usar como argumento de sal para crypt

### Descripción

function crypt_gensalt(string `$prefix` = `null`, int `$count` = 0): ?string

Compila una cadena para usar como argumento de sal para crypt().

### Parámetros

`prefix`
  El método de hash a usar. Una de las constantes `CRYPT_PREFIX_*`. Si es `null`, se seleccionará el mejor método de hash disponible.
`count`
  Controla el costo de procesamiento del hash; el rango válido y el significado exacto de count dependen del método de hash, pero números más grandes corresponden a hashes más costosos en términos de tiempo de CPU y posiblemente de uso de memoria. Si count es `0`, se seleccionará un costo bajo por defecto.

### Valores devueltos

Devuelve una cadena con el parámetro, o `null` en caso de error.

### Ejemplos

Ejemplo #1 Un ejemplo de crypt_gensalt()

    <?php
    // Genera la sal
    $salt = crypt_gensalt(CRYPT_PREFIX_BLOWFISH);
    // Hashea la contraseña
    $hash = crypt("secret", $salt);
    // Verifica el hash
    $test = hash_equals(crypt("secret", $hash), $hash);
    var_dump($salt, $hash, $test);
    ?>

El ejemplo anterior mostrará:

    string(29) "$2y$05$GcPykP.Am8C1.dGamdpwW."
    string(60) "$2y$05$GcPykP.Am8C1.dGamdpwW.1RR.7uicWvJPZfJfCEizZHqVWwuaJLm"
    bool(true)

### Ver también

- crypt_preferred_method() - Devuelve el prefijo del método de hash preferido
- crypt() - Hash de un solo sentido (indescifrable)
- hash_equals() - Comparación de strings resistente a ataques temporales

# crypt_preferred_method

(PECL xpass >= 1.1.0)

crypt_preferred_method — Devuelve el prefijo del método de hash preferido

### Descripción

function crypt_preferred_method(): ?string

Devuelve el prefijo del método de hash preferido.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una cadena con el prefijo, o `null` en caso de error.

### Ejemplos

Ejemplo #1 Un ejemplo de crypt_preferred_method()

    <?php
    var_dump(crypt_preferred_method());
    ?>

El ejemplo anterior mostrará:

    string(3) "$y$"

### Ver también

- crypt_gensalt() - Compila una cadena para usar como argumento de sal para crypt

## Tabla de contenidos

- crypt_checksalt — Valida un parámetro de hash de contraseña
- crypt_gensalt — Compila una cadena para usar como argumento de sal para crypt
- crypt_preferred_method — Devuelve el prefijo del método de hash preferido

- Instalación/Configuración
  - Requerimientos
  - Instalación vía PECL
- Constantes predefinidas
- Funciones Xpass
  - crypt_checksalt — Valida un parámetro de hash de contraseña
  - crypt_gensalt — Compila una cadena para usar como argumento de sal para crypt
  - crypt_preferred_method — Devuelve el prefijo del método de hash preferido

- Hash — HASH (framework de resúmenes de mensaje)
  - Instalación/Configuración
  - Constantes predefinidas
  - HashContext — La clase HashContext
  - Funciones de hash
- Mcrypt
  - Instalación/Configuración
  - Constantes predefinidas
  - Modos de cifrado Mcrypt
  - Funciones Mcrypt
- Mhash
  - Instalación/Configuración
  - Constantes predefinidas
  - Ejemplos
  - Funciones Mhash
- OpenSSL
  - Instalación/Configuración
  - Constantes predefinidas
  - Parámetros de claves/certificados
  - Verificación de certificados
  - Funciones de OpenSSL
  - OpenSSLCertificate — La clase OpenSSLCertificate
  - OpenSSLCertificateSigningRequest — La clase OpenSSLCertificateSigningRequest
  - OpenSSLAsymmetricKey — La clase OpenSSLAsymmetricKey
- Tabla de hachaje de contraseñas
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones de hash de contraseñas
- Rnp
  - Instalación/Configuración
  - Constantes predefinidas
  - Ejemplos
  - Funciones de Rnp
  - RnpFFI — La clase RnpFFI
- Sodium
  - Instalación/Configuración
  - Constantes predefinidas
  - Sodium Funciones
  - SodiumException — La clase SodiumException
- Xpass
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones Xpass

# Extensiones de bases de datos

# Capas abstractas

# Capa de abstracción de base de datos (estilo dbm)

# Introducción

Estas funciones permiten el acceso a las bases de datos del estilo Berkeley DB.

Se trata de una capa de abstracción general para varias bases de datos, basadas en ficheros. Por esta razón las funcionalidades se limitan a acciones comunes soportadas por las bases de datos modernas, como » Oracle Berkeley DB.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución
- Tipos de recursos

## Requerimientos

El comportamiento de ciertos aspectos depende de la implementación de la base de datos subyacente. Las funciones como dba_optimize() y dba_sync() funcionan como se espera para una base de datos, mientras que pueden no hacer nada en otras. Deben descargarse e instalarse los gestores DBA soportados.

Lista de gestores DBA
Gestor | Notas
--- | ---
`dbm` | DBM es la más antigua (la original) de las bases de datos de estilo Berkeley DB. Debería evitarse su uso si es posible. No se proporciona soporte para la compatibilidad de las funciones internas a DB2 y gdbm, ya que solo son compatibles a nivel de código fuente, pero no pueden manejar el formato original DBM.
`ndbm` | Ndbm es un nuevo tipo y más flexible que dbm. Sin embargo, presenta limitaciones arbitrarias de dbm (y por lo tanto, está obsoleto).
`gdbm` | Gdbm es un » gestor de bases de datos GNU.
`db2` | » Oracle Berkeley DB 2. Se describe como "un toolkit que proporciona soporte de alto rendimiento para bases de datos, tanto del lado cliente como del lado servidor."
`db3` | » Oracle Berkeley DB 3.
`db4` | » Oracle Berkeley DB 4 o 5. Esta opción puede utilizarse con BDB 5 a partir de PHP 5.3.3.
`cdb` | Cdb es un paquete rápido, ligero y fiable para crear y leer bases de datos constantes. Fue creado por el autor de qmail y puede encontrarse en » http://cr.yp.to/cdb.html. Dado que es "constante", solo se soportarán las operaciones de lectura. También se soporta la escritura (y no la actualización) mediante la biblioteca interna cdb.
`cdb_make` | Se soporta la escritura (y no la actualización) de archivos cdb cuando se utiliza la biblioteca cdb.
`flatfile` | Esto está disponible por razones de compatibilidad con la extensión obsoleta `dbm`. Sin embargo, puede utilizarse cuando los archivos han sido creados en este formato. Ocurre cuando la configuración no ha logrado encontrar una biblioteca externa.
`inifile` | Esto está disponible para permitir la modificación de los archivos php.ini desde scripts PHP. Al utilizar archivos ini, pueden pasarse arrays de la forma (0=>grupo,1=>nombre_valor) o strings de la forma "[grupo]nombre_valor" donde el grupo es opcional. Dado que las funciones dba_firstkey() y dba_nextkey() devuelven un string representando la clave, existe una nueva función, dba_key_split(), que permite convertir las claves en arrays sin pérdida.
`qdbm` | La biblioteca qdbm puede descargarse desde » http://fallabs.com/qdbm/index.html.
`tcadb` | La biblioteca Tokyo Cabinet puede ser descargada desde » http://fallabs.com/tokyocabinet/.
`lmdb` | Disponible a partir de PHP 7.2.0. La biblioteca Lightning Memory-Mapped Database puede ser descargada desde » https://symas.com/lmdb/.

Al llamar a la función dba_open() o la función dba_popen(), debe proporcionarse uno de los nombres de gestor como argumento. La lista de gestores disponibles puede mostrarse utilizando la función phpinfo() o la función dba_handlers().

## Instalación

Al utilizar la opción de compilación --enable-dba=shared, puede compilarse un módulo dinámico que active el soporte de las bases de datos de estilo DBM para PHP. Asimismo, debe añadirse el soporte de al menos uno de los siguientes gestores, especificando la opción de configuración --with-XXXX o --enable-XXXX durante la configuración de PHP.

Advertencia

Tras configurar y compilar PHP, deben ejecutarse las siguientes pruebas desde la línea de comandos: `php run-tests.php ext/dba`. Esto muestra si la combinación de controladores funciona. Los más problemáticos son `dbm` y `ndbm` que entran en conflicto con numerosas instalaciones. Esto se debe a que en muchos sistemas, estas bibliotecas forman parte de más de una biblioteca. La prueba de configuración impide simplemente configurar descriptores cuya combinación es defectuosa aunque funcionen correctamente por separado.

Gestores DBA soportados
Gestor | Opción de configuración
--- | ---
`dbm` | Para activar el soporte de dbm, añada la opción de compilación --with-dbm[=DIR]. Nota: dbm es una sobrecarga que suele dar lugar a fallos. Por tanto, solo debe utilizarse dbm si se está seguro de que funciona y se necesita este formato.
`ndbm` | Para activar el soporte de ndbm, añada la opción de compilación --with-ndbm[=DIR]. Nota: ndbm es una sobrecarga que suele dar lugar a fallos. Por tanto, solo debe utilizarse ndbm si se está seguro de que funciona y se necesita este formato.
`gdbm` | Para activar el soporte de gdbm, añada la opción de compilación --with-gdbm[=DIR].
`db2` | Para activar el soporte de Oracle Berkeley DB 2, añada la opción de compilación --with-db2[=DIR]. Nota: db2 entra en conflicto con db3 y db4.
`db3` | Para activar el soporte de Oracle Berkeley DB 3, añada la opción de compilación --with-db3[=DIR]. Nota: db3 entra en conflicto con db2 y db4.
`db4` | Para activar el soporte de Oracle Berkeley DB 4, añada la opción de compilación --with-db4[=DIR]. Nota: db4 entra en conflicto con db2 y db3. Nota: Las bibliotecas db con versiones comprendidas entre 4.1 y 4.1.24 no pueden utilizarse con ninguna versión de PHP. El soporte DB5 se añadió en PHP 5.3.3.
`cdb` | Para activar el soporte de cdb, añada la opción de compilación --with-cdb[=DIR]. Nota: Puede omitirse el uso de DIR, para aprovechar la biblioteca cdb proporcionada con PHP, que añade un gestor cdb_make, permite la creación de fichero cdb y permite el acceso a los ficheros cbd a través de la red con los flujos de PHP.
`flatfile` | Para activar el soporte de ficheros, añada la opción de compilación --enable-flatfile. Anteriormente a PHP 5.2.1 debía utilizarse la opción --with-flatfile en su lugar. Nota: Esto se añadió para asegurar la compatibilidad con la extensión `dbm` que está obsoleta. Úsese este gestor solo cuando no pueda instalarse ningún otro gestor y no pueda utilizarse el gestor cdb integrado.
`inifile` | Para activar el soporte de `inifile`, añada la opción de compilación --enable-inifile. Anteriormente a PHP 5.2.1 debía utilizarse la opción --with-inifile en su lugar. Nota: Esta opción se añadió para permitir leer y escribir en ficheros de inicialización de tipo Microsoft (.ini), como el php.ini por ejemplo.
`qdbm` | Para activar el soporte de qdbm, añada la opción de compilación --with-qdbm[=DIR]. Nota: qdbm entra en conflicto con dbm y gdbm. Nota: La biblioteca qdbm puede descargarse desde » http://fallabs.com/qdbm/index.html.
`tcadb` | Para activar el soporte de Tokyo Cabinet, añada la opción de compilación --with-tcadb[=DIR]. Nota: La biblioteca Tokyo Cabinet puede ser descargada desde » http://fallabs.com/tokyocabinet/.
`lmdb` | Para activar el soporte de Lightning Memory-Mapped Database añada la opción de configuración --with-lmdb[=DIR]. Nota: Esto se añadió en PHP 7.2.0. La biblioteca Lightning Memory-Mapped Database puede descargarse desde » https://symas.com/lmdb/.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración DBA
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
dba.default_handler | DBA_DEFAULT | `INI_ALL` |

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`dba.default_handler` string
  El nombre del gestor por defecto

## Tipos de recursos

A partir de PHP 8.4.0, la mayoría de las funciones DBA operan sobre o devuelven recursos (por ejemplo, dba_open() devuelve un identificador de enlace DBA positivo requerido por la mayoría de las funciones DBA).

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`DBA_LMDB_USE_SUB_DIR` (int)
  Flag del controlador LMDB para permitir la creación de un subdirectorio para los ficheros de base de datos. Disponible a partir de PHP 8.2.0.
`DBA_LMDB_NO_SUB_DIR` (int)
  Flag del controlador LMDB para prohibir la creación de un subdirectorio para los ficheros de base de datos. Disponible a partir de PHP 8.2.0.

# Ejemplos

## Tabla de contenidos

- Utilización

## Utilización

Ejemplo #1 Ejemplo con DBA

    <?php

    $id = dba_open("/tmp/test.db", "n", "db2");

    if (!$id) {
        echo "dba_open ha fallado\n";
        exit;
    }

    dba_replace("key", "¡Esto es un ejemplo!", $id);

    if (dba_exists("key", $id)) {
        echo dba_fetch("key", $id);
        dba_delete("key", $id);
    }

    dba_close($id);
    ?>

DBA gestiona datos binarios y no tiene límites arbitrarios. Sin embargo, hereda todas las limitaciones definidas por la implementación de la base de datos accedida.

Todas las bases de datos basadas en ficheros deben proporcionar una forma de definir el modo de fichero de las nuevas bases creadas. Este modo se pasa generalmente como cuarto argumento de las funciones dba_open() o dba_popen().

Se puede acceder a todas las entradas de la base de datos de forma lineal, utilizando las funciones dba_firstkey() y dba_nextkey(). No se puede modificar la base de datos mientras se está leyendo.

Ejemplo #2 Lectura de una base de datos

    <?php

    // ...apertura de la base de datos...

    $key = dba_firstkey($id);

    while ($key !== false) {
        if (true) {          // se retiene la clave para realizar otras acciones más tarde
            $handle_later[] = $key;
        }
        $key = dba_nextkey($id);
    }

    foreach ($handle_later as $val) {
        dba_delete($val, $id);
    }

    ?>

# La clase Dba\Connection

(PHP 8 >= 8.4.0)

## Introducción

Una clase totalmente opaca que reemplaza un recurso `dba` a partir de PHP 8.4.0.

## Sinopsis de la Clase

namespace Dba;
final class Connection {
}

# Funciones de DBA

# dba_close

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_close — Cierra una base DBA

### Descripción

function dba_close(Dba\Connection `$dba`): void

dba_close() cierra la base de datos establecida y libera todos los recursos del gestor de base de datos especificado.

### Parámetros

`dba`
  Una instancia de Dba\Connection, devuelta por dba_open() o dba_popen().

### Valores devueltos

No se retorna ningún valor.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | El parámetro `dba` ahora espera una instancia de Dba\Connection; anteriormente, se esperaba un resource `dba` válido.

### Ver también

- dba_open() - Abre una base de datos DBA
- dba_popen() - Establece una conexión persistente a una base de datos DBA

# dba_delete

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_delete — Elimina una línea en una base DBA

### Descripción

function dba_delete(string|array `$key`, Dba\Connection `$dba`): bool

dba_delete() elimina la entrada especificada de la base de datos.

### Parámetros

`key`
  La clave de la entrada a eliminar.
`dba`
  Una instancia de Dba\Connection, devuelta por dba_open() o dba_popen().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | El parámetro `dba` ahora espera una instancia de Dba\Connection; anteriormente, se esperaba un resource `dba` válido.

### Ver también

- dba_exists() - Verifica si una clave DBA existe
- dba_fetch() - Lee los datos asociados a una clave DBA
- dba_insert() - Inserta una entrada DBA
- dba_replace() - Reemplaza o inserta una línea DBA

# dba_exists

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_exists — Verifica si una clave DBA existe

### Descripción

function dba_exists(string|array `$key`, Dba\Connection `$dba`): bool

dba_exists() verifica si la `key` especificada existe en la base de datos.

### Parámetros

`key`
  La clave a verificar.
`dba`
  Una instancia de Dba\Connection, devuelta por dba_open() o dba_popen().

### Valores devueltos

Retorna `true` si la clave existe, `false` en caso contrario.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | El parámetro `dba` ahora espera una instancia de Dba\Connection; anteriormente, se esperaba un resource `dba` válido.

### Ver también

- dba_delete() - Elimina una línea en una base DBA
- dba_fetch() - Lee los datos asociados a una clave DBA
- dba_insert() - Inserta una entrada DBA
- dba_replace() - Reemplaza o inserta una línea DBA

# dba_fetch

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_fetch — Lee los datos asociados a una clave DBA

### Descripción

function dba_fetch(string|array `$key`, Dba\Connection `$dba`, int `$skip` = 0): string|false

Firma sobrecargada obsoleta a partir de 8.3.0:

function dba_fetch(string|array `$key`, int `$skip`, resource `$dba`): string

dba_fetch() lee los datos especificados por la clave `key` en la base identificada por `dba`.

### Parámetros

`key`
  La clave correspondiente a los datos.

  > Nota: Al trabajar con ficheros .ini, esta función acepta arrays como claves donde el índice 0 es el grupo y el índice 1 es el nombre del valor. Ver la función dba_key_split().

`dba`
  Una instancia de Dba\Connection, devuelta por dba_open() o dba_popen().
`skip`
  El número de pares clave-valor a ignorar al utilizar bases de datos cdb. Este valor es ignorado para todas las demás bases de datos que no admiten claves múltiples con el mismo nombre.

### Valores devueltos

Devuelve la cadena asociada si se encuentra el par clave/valor, `false` en caso contrario.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | El parámetro `dba` ahora espera una instancia de Dba\Connection; anteriormente, se esperaba un resource `dba` válido.
8.3.0 | La llamada a dba_fetch() con `dba` como tercer argumento es ahora obsoleta.
8.2.0 | El argumento opcional "skip" de la función dba_fetch() ahora se coloca al final, conforme a la semántica PHP lado-usuario. La firma sobrecargada previamente sigue siendo aceptada pero desaconsejada.

### Ver también

- dba_exists() - Verifica si una clave DBA existe
- dba_delete() - Elimina una línea en una base DBA
- dba_insert() - Inserta una entrada DBA
- dba_replace() - Reemplaza o inserta una línea DBA
- dba_key_split() - Transforma una representación de clave DBA por cadena en una representación por array

# dba_firstkey

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_firstkey — Lee la primera clave DBA

### Descripción

function dba_firstkey(Dba\Connection `$dba`): string|false

dba_firstkey() devuelve la primera clave de la base de datos y reinicia el puntero interno de clave. Esto permite una búsqueda lineal a través de toda la base de datos.

### Parámetros

`dba`
  Una instancia de Dba\Connection, devuelta por dba_open() o dba_popen().

### Valores devueltos

Devuelve la clave en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | El parámetro `dba` ahora espera una instancia de Dba\Connection; anteriormente, se esperaba un resource `dba` válido.

### Ver también

- dba_nextkey() - Lee la clave DBA siguiente
- dba_key_split() - Transforma una representación de clave DBA por cadena en una representación por array
- Ejemplo 2 en los ejemplos DBA

# dba_handlers

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

dba_handlers — Listar todos los gestores disponibles

### Descripción

function dba_handlers(bool `$full_info` = `false`): array

dba_handlers() lista todos los gestores soportados por esta extensión.

### Parámetros

`full_info`
  Activa/desactiva la mostración de la información completa en el resultado.

### Valores devueltos

Devuelve un array de gestores de bases de datos. Si `full_info` está establecido a `true`, el array será asociativo con los nombres de los gestores como claves y la información de su versión com valor. De otro modo, el resultado será un array indexado de nombres de gestores.

> Nota: Cuando se usa la biblioteca cdb interna verá `cdb` y `cdb_make`.

### Ejemplos

Ejemplo #1 Ejemplo de dba_handlers()

    <?php

    echo "Gestores de DBA disponibles:\n";
    foreach (dba_handlers(true) as $nombre_gestor => $versión_gestor) {
      // limpiar las versiones
      $versión_gestor = str_replace('$', '', $versión_gestor);
      echo " - $nombre_gestor: $versión_gestor\n";
    }

    ?>

Resultado del ejemplo anterior es similar a:

    Gestores de DBA disponibles:
     - cdb: 0.75, Revision: 1.3.2.3
     - cdb_make: 0.75, Revision: 1.2.2.4
     - db2: Sleepycat Software: Berkeley DB 2.7.7: (08/20/99)
     - inifile: 1.0, Revision: 1.6.2.3
     - flatfile: 1.0, Revision: 1.5.2.4

# dba_insert

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_insert — Inserta una entrada DBA

### Descripción

function dba_insert(string|array `$key`, string `$value`, Dba\Connection `$dba`): bool

dba_insert() inserta la entrada descrita con `key` y `value` en la base de datos.

### Parámetros

`key`
  La clave de la entrada a insertar. Si esta clave ya existe en la base de datos, esta función fallará. Utilice la función dba_replace() si se debe reemplazar una clave existente.
`value`
  El valor a insertar.
`dba`
  Una instancia de Dba\Connection, devuelta por dba_open() o dba_popen().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | El parámetro `dba` ahora espera una instancia de Dba\Connection; anteriormente, se esperaba un resource `dba` válido.

### Ver también

- dba_exists() - Verifica si una clave DBA existe
- dba_delete() - Elimina una línea en una base DBA
- dba_fetch() - Lee los datos asociados a una clave DBA
- dba_replace() - Reemplaza o inserta una línea DBA

# dba_key_split

(PHP 5, PHP 7, PHP 8)

dba_key_split — Transforma una representación de clave DBA por cadena en una representación por array

### Descripción

function dba_key_split(string|false|null `$key`): array|false

dba_key_split() transforma una representación de clave DBA por cadena en una representación por array.

### Parámetros

`key`
  La clave en forma de string.

### Valores devueltos

Devuelve un array en la forma `array(0 => grupo, 1 => nombre_valor)`. Esta función devuelve `false` si `key` es `null` o `false`.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Pasar `null` o `false` a `key` está ahora deprecado.

### Ver también

- dba_firstkey() - Lee la primera clave DBA
- dba_nextkey() - Lee la clave DBA siguiente
- dba_fetch() - Lee los datos asociados a una clave DBA

# dba_list

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

dba_list — Lista todos los ficheros de bases de datos DBA abiertos

### Descripción

function dba_list(): array

dba_list() lista todos los ficheros de bases de datos DBA abiertos.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array asociativo, bajo la forma `idressource => nomfichier`.

# dba_nextkey

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_nextkey — Lee la clave DBA siguiente

### Descripción

function dba_nextkey(Dba\Connection `$dba`): string|false

dba_nextkey() devuelve la clave siguiente de la base de datos y avanza el puntero interno de clave.

### Parámetros

`dba`
  Una instancia de Dba\Connection, devuelta por dba_open() o dba_popen().

### Valores devueltos

Devuelve la clave en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | El parámetro `dba` ahora espera una instancia de Dba\Connection; anteriormente, se esperaba un resource `dba` válido.

### Ver también

- dba_firstkey() - Lee la primera clave DBA
- dba_key_split() - Transforma una representación de clave DBA por cadena en una representación por array
- Ejemplo 2 en los ejemplos DBA

# dba_open

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_open — Abre una base de datos DBA

### Descripción

function dba_open(
string `$path`,
string `$mode`,
?string `$handler` = `null`,
int `$permission` = 0644,
int `$map_size` = 0,
?int `$flags` = `null`
): Dba\Connection|false

dba_open() establece una conexión a la base identificada por `path` con el modo `mode` y el identificador `handler`.

### Parámetros

`path`
  Ruta en el sistema de archivos.
`mode`
  Puede ser `r` para solo lectura, `w` para lectura/escritura, `c` para lectura/escritura y creación si la base no existe, y `n` para creación, sobrescritura y acceso en lectura/escritura. La base de datos se crea en modo BTree; los otros modos (como Hash o Queue) no son soportados. Además, se puede elegir el método de bloqueo de la base con el carácter siguiente. Utilice `l` para bloquear la base con un fichero .lck, o `d` para bloquear la base misma. Es importante que las aplicaciones utilicen estas opciones de manera coherente. Si se desea probar la posibilidad de acceso sin esperar la disponibilidad del bloqueo, se puede añadir la letra `t` como tercer carácter. Cuando se está absolutamente seguro de que la base no requiere bloqueo, se puede utilizar el guión `-` en lugar de `l` o `d`. Cuando no se utiliza ni `d`, ni `l` ni `-`, dba bloqueará en modo `d`.

  > Nota:

  > Solo puede haber un tipo de escritura en la base. Cuando se utiliza dba en un servidor web, y varias peticiones HTTP realizan escrituras, estas solo pueden realizarse una tras otra. De igual manera, la lectura durante la escritura no es posible. La extensión dba utiliza un bloqueo para evitar estos problemas. A continuación se muestra la tabla de bloqueo:

  > Bloqueo DBA
  > ya abierta | `mode` = "rl" | `mode` = "rlt" | `mode` = "wl" | `mode` = "wlt" | `mode` = "rd" | `mode` = "rdt" | `mode` = "wd" | `mode` = "wdt"
  > --- | --- | --- | --- | --- | --- | --- | --- | ---
  > no abierta | ok | ok | ok | ok | ok | ok | ok | ok
  > `mode` = "rl" | ok | ok | esperando | `false` | ilegal | ilegal | ilegal | ilegal
  > `mode` = "wl" | esperando | `false` | esperando | `false` | ilegal | ilegal | ilegal | ilegal
  > `mode` = "rd" | ilegal | ilegal | ilegal | ilegal | ok | ok | esperando | `false`
  > `mode` = "wd" | ilegal | ilegal | ilegal | ilegal | esperando | `false` | esperando | `false`

  > - ok: La segunda llamada tiene éxito.
  > - esperando: La segunda llamada espera a que dba_close() sea llamada por el primer script.
  > - false: La segunda llamada devuelve `false`.
  > - ilegal: No se deben mezclar las opciones `"l"` y `"d"` para el parámetro `mode`.

`handler`
  El nombre del gestor que debe ser utilizado para acceder a `path`. Se pasa a todos los parámetros opcionales dados a dba_open() y puede actuar en su nombre. Si el parámetro `handler` es `null`, entonces se invoca el gestor por defecto.
`permission`
  Parámetro opcional de tipo int que se pasa al controlador. Tiene el mismo significado que el parámetro `permissions` de la función chmod(), y tiene un valor por omisión de `0644`. Los controladores `db1`, `db2`, `db3`, `db4`, `dbm`, `gdbm`, Los controladores `ndbm` y `lmdb` soportan el parámetro `permission`. El controlador `lmdb` soporta dos parámetros adicionales. El primero permite definir el `$filemode` (ver descripción anterior), y el segundo permite definir la `$mapsize`, cuyo valor debería ser un múltiplo del tamaño de página del sistema operativo, o cero para utilizar la mapsize por defecto. El parámetro `$mapsize` es soportado a partir de PHP 7.3.14 y 7.4.2, respectivamente.
`map_size`
  Parámetro opcional de tipo int que se pasa al controlador. Su valor debe ser un múltiplo del tamaño de página del sistema operativo, o cero para utilizar el tamaño de mappage por defecto. Solo el controlador `lmdb` acepta el parámetro `map_size`.
`flags`
  Bandera a pasar a los controladores de base de datos. Si es `null`, se proporcionarán las banderas por defecto. Actualmente, solo el controlador LMDB soporta las siguientes banderas: `DBA_LMDB_USE_SUB_DIR` y `DBA_LMDB_NO_SUB_DIR`.

### Valores devueltos

Devuelve una instancia Dba\Connection en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

`false` es devuelto y se emite un error de nivel `E_WARNING` cuando el parámetro `handler` es `null`, pero no hay ningún gestor por defecto disponible.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Ahora devuelve una instancia de Dba\Connection; anteriormente se devolvía un resource.
8.2.0 | Se añade el parámetro `flags`.
8.2.0 | El parámetro `handler` ahora es nullable.
7.3.14, 7.4.2 | El controlador `lmdb` ahora soporta un parámetro adicional `map_size`.

### Ver también

- dba_popen() - Establece una conexión persistente a una base de datos DBA
- dba_close() - Cierra una base DBA

# dba_optimize

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_optimize — Optimiza una base DBA

### Descripción

function dba_optimize(Dba\Connection `$dba`): bool

dba_optimize() optimiza la base de datos subyacente.

### Parámetros

`dba`
  Una instancia de Dba\Connection, devuelta por dba_open() o dba_popen().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | El parámetro `dba` ahora espera una instancia de Dba\Connection; anteriormente, se esperaba un resource `dba` válido.

### Ver también

- dba_sync() - Sincroniza una base de datos DBA

# dba_popen

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_popen — Establece una conexión persistente a una base de datos DBA

### Descripción

function dba_popen(
string `$path`,
string `$mode`,
?string `$handler` = `null`,
int `$permission` = 0644,
int `$map_size` = 0,
?int `$flags` = `null`
): Dba\Connection|false

dba_popen() establece una conexión persistente a la base identificada por `path` con el modo `mode`, utilizando el identificador `handler`.

### Parámetros

`path`
  Ruta en el sistema de ficheros.
`mode`
  Puede ser `r` para solo lectura, `w` para lectura/escritura, `c` para lectura/escritura y creación si la base no existe, y `n` para creación, sobrescritura y acceso en lectura/escritura.
`handler`
  El nombre del gestor que debe ser utilizado para acceder a `path`. El gestor recibe todos los argumentos adicionales pasados a la función dba_popen(). Si el argumento `handler` es `null`, entonces se invoca el gestor por defecto.
`permission`
  Argumento opcional de tipo entero (int) que se pasa al controlador. Tiene el mismo significado que el argumento `permissions` de la función chmod(), y su valor por omisión es `0644`. Los controladores `db1`, `db2`, `db3`, `db4`, `dbm`, `gdbm`, `ndbm` y `lmdb` admiten el argumento `permission`.
`map_size`
  Argumento opcional de tipo int que se pasa al controlador. Su valor debe ser un múltiplo de la tamaño de página del sistema operativo, o cero para utilizar el tamaño de mapa por omisión. El controlador `lmdb` acepta el argumento `map_size`.
`flags`
  Permite pasar banderas a los controladores de base de datos. Actualmente, solo el controlador LMDB con las banderas `DBA_LMDB_USE_SUB_DIR` y `DBA_LMDB_NO_SUB_DIR` es soportado.

### Valores devueltos

Devuelve una instancia de Dba\Connection en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

El valor `false` es devuelto y un error de nivel `E_WARNING` es emitido cuando el argumento `handler` es `null`, pero no hay ningún gestor por defecto disponible.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Ahora devuelve una instancia de Dba\Connection; anteriormente se devolvía un resource.
8.2.0 | Se añadió el argumento `flags`.
8.2.0 | El argumento `handler` ahora es nullable.
7.3.14, 7.4.2 | El controlador `lmdb` ahora soporta un argumento adicional `map_size`.

### Ver también

- dba_open() - Abre una base de datos DBA
- dba_close() - Cierra una base DBA

# dba_replace

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_replace — Reemplaza o inserta una línea DBA

### Descripción

function dba_replace(string|array `$key`, string `$value`, Dba\Connection `$dba`): bool

dba_replace() reemplaza o inserta una entrada, para la clave `key` y con el valor `value` en la base identificada por `dba`.

### Parámetros

`key`
  La clave de la entrada a reemplazar.
`value`
  El valor utilizado para el reemplazo.
`dba`
  Una instancia de Dba\Connection, devuelta por dba_open() o dba_popen().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | El parámetro `dba` ahora espera una instancia de Dba\Connection; anteriormente, se esperaba un resource `dba` válido.

### Ver también

- dba_exists() - Verifica si una clave DBA existe
- dba_delete() - Elimina una línea en una base DBA
- dba_fetch() - Lee los datos asociados a una clave DBA
- dba_insert() - Inserta una entrada DBA

# dba_sync

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_sync — Sincroniza una base de datos DBA

### Descripción

function dba_sync(Dba\Connection `$dba`): bool

dba_sync() sincroniza la base de datos. Esto probablemente iniciará una escritura física en el disco, si es admisible.

### Parámetros

`dba`
  Una instancia de Dba\Connection, devuelta por dba_open() o dba_popen().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | El parámetro `dba` ahora espera una instancia de Dba\Connection; anteriormente, se esperaba un resource `dba` válido.

### Ver también

- dba_optimize() - Optimiza una base DBA

## Tabla de contenidos

- dba_close — Cierra una base DBA
- dba_delete — Elimina una línea en una base DBA
- dba_exists — Verifica si una clave DBA existe
- dba_fetch — Lee los datos asociados a una clave DBA
- dba_firstkey — Lee la primera clave DBA
- dba_handlers — Listar todos los gestores disponibles
- dba_insert — Inserta una entrada DBA
- dba_key_split — Transforma una representación de clave DBA por cadena en una representación por array
- dba_list — Lista todos los ficheros de bases de datos DBA abiertos
- dba_nextkey — Lee la clave DBA siguiente
- dba_open — Abre una base de datos DBA
- dba_optimize — Optimiza una base DBA
- dba_popen — Establece una conexión persistente a una base de datos DBA
- dba_replace — Reemplaza o inserta una línea DBA
- dba_sync — Sincroniza una base de datos DBA

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
  - Tipos de recursos
- Constantes predefinidas
- Ejemplos
  - Utilización
- Dba\Connection — La clase Dba\Connection
- Funciones de DBA
  - dba_close — Cierra una base DBA
  - dba_delete — Elimina una línea en una base DBA
  - dba_exists — Verifica si una clave DBA existe
  - dba_fetch — Lee los datos asociados a una clave DBA
  - dba_firstkey — Lee la primera clave DBA
  - dba_handlers — Listar todos los gestores disponibles
  - dba_insert — Inserta una entrada DBA
  - dba_key_split — Transforma una representación de clave DBA por cadena en una representación por array
  - dba_list — Lista todos los ficheros de bases de datos DBA abiertos
  - dba_nextkey — Lee la clave DBA siguiente
  - dba_open — Abre una base de datos DBA
  - dba_optimize — Optimiza una base DBA
  - dba_popen — Establece una conexión persistente a una base de datos DBA
  - dba_replace — Reemplaza o inserta una línea DBA
  - dba_sync — Sincroniza una base de datos DBA

# ODBC (Unificada)

# Introducción

Además del soporte habitual para ODBC, las funciones de ODBC Unificada de PHP permiten acceder a varias bases de datos que toman prestada la semántica de la API ODBC para implementar su propia API. En lugar de mantener múltiples controladores de bases de datos que son casi idénticos, éstos han sido unificados en un único conjunto de funciones ODBC.

Las siguientes bases de datos están soportadas por la funciones de ODBC Unificada: » Adabas D, » IBM DB2, » iODBC, » Solid, y » Sybase SQL Anywhere.

> Nota: Con la excepción de iODBC, no está involucrada ninguna ODBC al conectarse a las bases de datos mencionadas. Ocurre que las funciones que se usan para comunicarse de forma nativa con las bases de datos comparten los mismos nombres y la misma sintaxis que las funciones de ODBC. Sin embargo, al construir PHP con soporte para iODBC, se permite el uso de cualquier controlador que cumpla con ODBC en las aplicaciones de PHP. Hay más información disponible sobre iODBC en » www.iodbc.org con la alternativa unixODBC disponible en » www.unixodbc.org.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución
- Tipos de recursos

## Requerimientos

Para acceder a cualquiera de las bases de datos soportadas se necesitan tener instaladas las bibliotecas requeridas.

## Instalación

--with-adabas[=DIR]

  Incluye el soporte para Adabas D. DIR es el directorio de instalación de Adabas D. Por omisión, es /usr/local.

--with-sapdb[=DIR]

  Incluye el soporte para SAP DB. DIR es el directorio de instalación de SAP DB. Por omisión, es /usr/local.

--with-solid[=DIR]

  Incluye el soporte para Solid. DIR es el directorio de instalación de Solid. Por omisión, es /usr/local/solid.

--with-ibm-db2[=DIR]

  Incluye el soporte para IBM DB2. DIR es el directorio de instalación de DB2. Por omisión, es /home/db2inst1/sqllib.

--with-empress[=DIR]

  Incluye el soporte para Empress. DIR es el directorio de instalación de Empress. Por omisión, es $EMPRESSPATH. Esta opción solo soporta Empress versión 8.60 y posteriores.

--with-empress-bcs[=DIR]

  Incluye el soporte para `"Empress Local Access"`. DIR es el directorio de instalación de Empress. Por omisión, es $EMPRESSPATH. Esta opción solo soporta Empress versión 8.60 y posteriores.

--with-birdstep[=DIR]

  Incluye el soporte para Birdstep. DIR es el directorio de instalación de Birdstep. Por omisión, es /usr/local/birdstep.

--with-custom-odbc[=DIR]

  Incluye el soporte para un ODBC definido por el usuario. DIR es el directorio de instalación de ODBC. Por omisión, es /usr/local. Asegúrese de que la variable CUSTOM_ODBC_LIBS esté definida y de que el fichero odbc.h esté en la ruta de inclusión, es decir, que se deban definir las siguientes líneas para `Sybase SQL Anywhere 5.5.00` bajo QNX, antes de utilizar el script de configuración:

         CPPFLAGS="-DODBC_QNX -DSQLANY_BUG"
         LDFLAGS=-lunix
         CUSTOM_ODBC_LIBS="-ldblib -lodbc".

--with-iodbc[=DIR]

  Incluye el soporte para iODBC. DIR es el directorio de instalación de iODBC. Por omisión, es /usr/local.

--with-esoob[=DIR]

  Incluye el soporte para Easysoft OOB. DIR es el directorio de instalación de OOB. Por omisión, es /usr/local/easysoft/oob/client.

--with-unixodbc[=DIR]

  Incluye el soporte para UnixODBC. DIR es el directorio de instalación de UnixODBC. Por omisión, es /usr/local.

--with-openlink[=DIR]

  Incluye el soporte para OpenLink ODBC. DIR es el directorio de instalación de OpenLink. Por omisión, es /usr/local. Es el mismo que para iODBC.

--with-dbmaker[=DIR]

  Incluye el soporte para DBMaker. DIR es el directorio de instalación de DBMaker. Por omisión, es la ruta de la última instalación de DBMaker (por ejemplo /home/dbmaker/3.6).

Los usuarios de Windows deben habilitar php_odbc.dll para utilizar esta extensión.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración UODBC
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
odbc.allow_persistent | "1" | `INI_SYSTEM` |
odbc.check_persistent | "1" | `INI_SYSTEM` |
odbc.max_persistent | "-1" | `INI_SYSTEM` |
odbc.max_links | "-1" | `INI_SYSTEM` |
odbc.defaultlrl | "4096" | `INI_ALL` |
odbc.defaultbinmode | "1" | `INI_ALL` |
odbc.default_cursortype | "3" | `INI_ALL` |

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`odbc.default_db` string

  La fuente de datos ODBC si no se especifica ninguna en las funciones odbc_connect() o odbc_pconnect().

`odbc.default_user` string

  Nombre de usuario a utilizar si no se especifica ninguno en las funciones odbc_connect() o odbc_pconnect().

`odbc.default_pw` string

  Contraseña a utilizar si no se especifica ninguna en las funciones odbc_connect() o odbc_pconnect().

`odbc.allow_persistent` bool

  ¿Se permiten las conexiones ODBC persistentes o no?

`odbc.check_persistent` bool

  Verifica que la conexión sea válida antes de utilizarla.

`odbc.max_persistent` int

  Número máximo de conexiones persistentes por proceso.

`odbc.max_links` int

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

`odbc.defaultlrl` int

  Gestión de campos de tipo LONG. Especifica el número de bytes devueltos en las variables. Consulte odbc_longreadlen() para más información.

  Cuando un int es utilizado, su valor es medido en bytes. También puede utilizar la notación abreviada como se describe en esta entrada de la FAQ..
`odbc.defaultbinmode` int

  Gestión de datos binarios. Consulte odbc_binmode() para más información.

`odbc.default_cursortype` int

  Controla el modelo de cursor ODBC. Valores posibles: `SQL_CURSOR_FORWARD_ONLY`, `SQL_CURSOR_KEYSET_DRIVEN`, `SQL_CURSOR_DYNAMIC` y `SQL_CURSOR_STATIC` (por defecto).

## Tipos de recursos

Antes de PHP 8.4.0, esta extensión definía dos tipos de recursos: un identificador de conexión ODBC y un identificador de resultado ODBC.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`ODBC_TYPE` (string)
`ODBC_BINMODE_PASSTHRU` (int)
`ODBC_BINMODE_RETURN` (int)
`ODBC_BINMODE_CONVERT` (int)
`SQL_ODBC_CURSORS` (int)
`SQL_CUR_USE_DRIVER` (int)
`SQL_CUR_USE_IF_NEEDED` (int)
`SQL_CUR_USE_ODBC` (int)
`SQL_CONCURRENCY` (int)
`SQL_CONCUR_READ_ONLY` (int)
`SQL_CONCUR_LOCK` (int)
`SQL_CONCUR_ROWVER` (int)
`SQL_CONCUR_VALUES` (int)
`SQL_CURSOR_TYPE` (int)
`SQL_CURSOR_FORWARD_ONLY` (int)
`SQL_CURSOR_KEYSET_DRIVEN` (int)
`SQL_CURSOR_DYNAMIC` (int)
`SQL_CURSOR_STATIC` (int)
`SQL_KEYSET_SIZE` (int)
`SQL_CHAR` (int)
`SQL_VARCHAR` (int)
`SQL_LONGVARCHAR` (int)
`SQL_WCHAR` (int)
  String Unicode de longitud fija.
`SQL_WVARCHAR` (int)
  String Unicode de longitud variable.
`SQL_WLONGVARCHAR` (int)
  Datos de caracteres Unicode de longitud variable. La longitud máxima depende de la fuente de datos.
`SQL_DECIMAL` (int)
`SQL_NUMERIC` (int)
`SQL_BIT` (int)
`SQL_TINYINT` (int)
`SQL_SMALLINT` (int)
`SQL_INTEGER` (int)
`SQL_BIGINT` (int)
`SQL_REAL` (int)
`SQL_FLOAT` (int)
`SQL_DOUBLE` (int)
`SQL_BINARY` (int)
`SQL_VARBINARY` (int)
`SQL_LONGVARBINARY` (int)
`SQL_DATE` (int)
`SQL_TIME` (int)
`SQL_TIMESTAMP` (int)
`SQL_TYPE_DATE` (int)
`SQL_TYPE_TIME` (int)
`SQL_TYPE_TIMESTAMP` (int)
`SQL_BEST_ROWID` (int)
`SQL_ROWVER` (int)
`SQL_SCOPE_CURROW` (int)
`SQL_SCOPE_TRANSACTION` (int)
`SQL_SCOPE_SESSION` (int)
`SQL_NO_NULLS` (int)
`SQL_NULLABLE` (int)
`SQL_INDEX_UNIQUE` (int)
`SQL_INDEX_ALL` (int)
`SQL_ENSURE` (int)
`SQL_QUICK` (int)
`SQL_FETCH_FIRST` (int)
  Devuelve el primer conjunto de filas.
`SQL_FETCH_NEXT` (int)
  Devuelve el siguiente conjunto de filas.

# Funciones ODBC

# odbc_autocommit

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_autocommit — Activa el modo de autovalidación

### Descripción

function odbc_autocommit(Odbc\Connection `$odbc`, ?bool `$enable` = `null`): int|bool

Sin el argumento `enable`, odbc_autocommit() devuelve el estado de autovalidación

Por omisión, la autovalidación está activada. Desactivar la autovalidación es equivalente a iniciar una transacción.

### Parámetros

`odbc`
  El objeto de conexión ODBC, ver la documentación de la función odbc_connect() para más detalles.
`enable`

  Si `enable` es `true`, la autovalidación está activada. Si es `false`, la autovalidación está desactivada. Si se pasa `null`, esta función devuelve el estado de autovalidación para `odbc`.

### Valores devueltos

Con un argumento `enable` igual a `null`, odbc_autocommit() devuelve el estado de autovalidación de la conexión `odbc`. Un valor diferente de 0 si el modo está activado, 0 si no lo está, o `false` si ocurre un error.

Si `enable` no es null, esta función devuelve `true` en caso de éxito, y `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `odbc` ahora espera una instancia de Odbc\Connection; anteriormente, se esperaba un resource.
8.3.0 | `enable` es ahora nullable.

### Ver también

- odbc_commit() - Valida una transacción ODBC
- odbc_rollback() - Anula una transacción

# odbc_binmode

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_binmode — Modifica la gestión de columnas de datos binarios

### Descripción

function odbc_binmode(Odbc\Result `$statement`, int `$mode`): true

odbc_binmode() controla la gestión de las columnas de datos binarios. Los tipos ODBC SQL afectados son `BINARY`, `VARBINARY` y `LONGVARBINARY`. El modo predeterminado puede definirse utilizando la directiva php.ini uodbc.defaultbinmode

Cuando un dato SQL se convierte en carácter C, (`ODBC_BINMODE_CONVERT`) los 8 bits del carácter fuente se representan por dos caracteres ASCII. Estos caracteres son representaciones ASCII de los números en formato hexadecimal. Por ejemplo, el binario `00000001` se convierte en `"01"` y el binario `11111111` se convierte en `"FF"`.

Mientras que la gestión de las columnas `BINARY` y `VARBINARY` depende únicamente del binmode, la gestión de las columnas `LONGVARBINARY` depende también de longreadlen, como se muestra a continuación:

Conversión de `LONGVARBINARY`
Modo | Longitud | Resultado
--- | --- | ---
`ODBC_BINMODE_PASSTHRU` | 0 | `passthru`
`ODBC_BINMODE_RETURN` | 0 | `passthru`
`ODBC_BINMODE_CONVERT` | 0 | `passthru`
`ODBC_BINMODE_PASSTHRU` | >0 | `passthru`
`ODBC_BINMODE_RETURN` | >0 | Tal cual
`ODBC_BINMODE_CONVERT` | >0 | Carácter

Si se utiliza odbc_fetch_into(), `passthru` significa que se devolverá una cadena vacía para estas columnas. Si se utiliza la función odbc_result(), passthru significa que los datos se envían directamente al cliente (es decir, se imprimen).

### Parámetros

`statement`

  El objeto de resultado ODBC.

`mode`

  Valores posibles para el parámetro `mode`:

  - `ODBC_BINMODE_PASSTHRU`: devolver los datos en binario
  - `ODBC_BINMODE_RETURN`: devolver sin conversión
  - `ODBC_BINMODE_CONVERT`: convertir en carácter

  > Nota: La gestión de columnas de tipo binary long también se ve afectada por la función odbc_longreadlen().

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `statement` ahora espera una instancia de Odbc\Result; anteriormente, se esperaba un resource.

# odbc_close

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_close — Cierra una conexión ODBC

### Descripción

function odbc_close(Odbc\Connection `$odbc`): void

Cierra la conexión con la base de datos del servidor.

### Parámetros

`odbc`
  El objeto de conexión ODBC, ver la documentación de la función odbc_connect() para más detalles.

### Valores devueltos

No se retorna ningún valor.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `odbc` ahora espera una instancia de Odbc\Connection; anteriormente, se esperaba un resource.

### Notas

> Nota:

> odbc_close() fallará si hay transacciones en curso en esta conexión. En este caso, la conexión permanecerá abierta.

# odbc_close_all

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_close_all — Cierra todas las conexiones ODBC

### Descripción

function odbc_close_all(): void

odbc_close_all() cierra todas las conexiones ODBC a fuentes de datos.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

### Notas

> Nota:

> odbc_close_all() fallará si hay transacciones en curso en esta conexión. En este caso, la conexión permanecerá abierta.

# odbc_columnprivileges

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_columnprivileges — Lista las columnas y sus derechos asociados

### Descripción

function odbc_columnprivileges(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`,
string `$column`
): Odbc\Result|false

Lista las columnas y sus derechos asociados.

### Parámetros

`odbc`
  El objeto de conexión ODBC, ver la documentación de la función odbc_connect() para más detalles.
`catalog`

  El catálogo ('calificativo' en el argot ODBC 2).

`schema`

  El esquema ('propietario' en el argot ODBC 2). Este parámetro acepta los siguientes patrones de búsqueda: `%` para buscar cero o más caracteres, y `_` para buscar un solo carácter.

`table`

  El nombre de la tabla. Este parámetro acepta los siguientes patrones de búsqueda: `%` para buscar cero o más caracteres, y `_` para buscar un solo carácter.

`column`

  El nombre de la columna. Este parámetro acepta los siguientes patrones de búsqueda: `%` para buscar cero o más caracteres, y `_` para buscar un solo carácter.

### Valores devueltos

Devuelve un objeto de resultado ODBC o `false` si ocurre un error. Este objeto resultado puede ser utilizado para recuperar una lista de columnas y los derechos asociados.

El conjunto de resultados contiene las siguientes columnas:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `COLUMN_NAME`
- `GRANTOR`
- `GRANTEE`
- `PRIVILEGE`
- `IS_GRANTABLE`

Los controladores pueden indicar columnas adicionales.

El conjunto de resultados está ordenado por `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME`, `COLUMN_NAME` y `PRIVILEGE`.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `odbc` ahora espera una instancia de Odbc\Connection; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Listar los Privilegios para una Columna

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $privileges = odbc_columnprivileges($conn, 'TutorialDB', 'dbo', 'test', 'id');
    while (($row = odbc_fetch_array($privileges))) {
        print_r($row);
        break; // further rows omitted for brevity
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [TABLE_CAT] => TutorialDB
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => test
        [COLUMN_NAME] => id
        [GRANTOR] => dbo
        [GRANTEE] => dbo
        [PRIVILEGE] => INSERT
        [IS_GRANTABLE] => YES
    )

# odbc_columns

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_columns — Lista las columnas de una tabla

### Descripción

function odbc_columns(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$table` = `null`,
?string `$column` = `null`
): Odbc\Result|false

Lista las columnas de una tabla.

### Parámetros

`odbc`
  El objeto de conexión ODBC, ver la documentación de la función odbc_connect() para más detalles.
`catalog`

  El catálogo ('calificativo' en el argot ODBC 2).

`schema`

  El esquema ('propietario' en el argot ODBC 2). Este parámetro acepta los siguientes patrones de búsqueda: `%` para buscar cero o más caracteres, y `_` para buscar un solo carácter.

`table`

  El nombre de la tabla. Este parámetro acepta los siguientes patrones de búsqueda: `%` para buscar cero o más caracteres, y `_` para buscar un solo carácter.

`column`

  El nombre de la columna. Este parámetro acepta los siguientes patrones de búsqueda: `%` para buscar cero o más caracteres, y `_` para buscar un solo carácter.

### Valores devueltos

Devuelve un objeto de resultado ODBC o `false` si ocurre un error.

El conjunto de resultados contiene las siguientes columnas:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `COLUMN_NAME`
- `DATA_TYPE`
- `TYPE_NAME`
- `COLUMN_SIZE`
- `BUFFER_LENGTH`
- `DECIMAL_DIGITS`
- `NUM_PREC_RADIX`
- `NULLABLE`
- `REMARKS`
- `COLUMN_DEF`
- `SQL_DATA_TYPE`
- `SQL_DATETIME_SUB`
- `CHAR_OCTET_LENGTH`
- `ORDINAL_POSITION`
- `IS_NULLABLE`

Los controladores pueden indicar columnas adicionales.

El conjunto de resultados está ordenado por `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME` y `ORDINAL_POSITION`.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `odbc` ahora espera una instancia de Odbc\Connection; anteriormente, se esperaba un resource.
8.0.0 | `schema`, `table` y `column` ahora son anulables.

### Ejemplos

Ejemplo #1 Listar las Columnas de una Tabla

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $columns = odbc_columns($conn, 'TutorialDB', 'dbo', 'test', '%');
    while (($row = odbc_fetch_array($columns))) {
        print_r($row);
        break; // filas adicionales omitidas por brevedad
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [TABLE_CAT] => TutorialDB
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => TEST
        [COLUMN_NAME] => id
        [DATA_TYPE] => 4
        [TYPE_NAME] => int
        [COLUMN_SIZE] => 10
        [BUFFER_LENGTH] => 4
        [DECIMAL_DIGITS] => 0
        [NUM_PREC_RADIX] => 10
        [NULLABLE] => 0
        [REMARKS] =>
        [COLUMN_DEF] =>
        [SQL_DATA_TYPE] => 4
        [SQL_DATETIME_SUB] =>
        [CHAR_OCTET_LENGTH] =>
        [ORDINAL_POSITION] => 1
        [IS_NULLABLE] => NO
    )

### Ver también

- odbc_columnprivileges() - Lista las columnas y sus derechos asociados
- odbc_procedurecolumns() - Lista los parámetros de los procedimientos

# odbc_commit

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_commit — Valida una transacción ODBC

### Descripción

function odbc_commit(Odbc\Connection `$odbc`): bool

Valida todas las transacciones en curso en la conexión.

### Parámetros

`odbc`
  El objeto de conexión ODBC, ver la documentación de la función odbc_connect() para más detalles.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `odbc` ahora espera una instancia de Odbc\Connection; anteriormente, se esperaba un resource.

# odbc_connect

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_connect — Conectar a una fuente de datos

### Descripción

function odbc_connect(
string `$dsn`,
?string `$user` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
int `$cursor_option` = `SQL_CUR_USE_DRIVER`
): Odbc\Connection|false

El identificador de conexión devuelto por esta función es necesario para otras funciones ODBC. Puede tener múltiples conexiones abiertas a la vez siempre que utilicen diferentes bases de datos o diferentes credenciales.

Con algunos controladores ODBC, ejecutar un procedimiento almacenado complejo puede fallar con un error similar a: "No se puede abrir un cursor en un procedimiento almacenado que tenga algo más que una única sentencia SELECT". Usar SQL_CUR_USE_ODBC puede evitar ese error. Además, algunos controladores no soportan el parámetro opcional row_number en odbc_fetch_row(). SQL_CUR_USE_ODBC podría ayudar en ese caso también.

### Parámetros

`dsn`

  El nombre de la fuente de datos para la conexión. Alternativamente, se puede usar una cadena de conexión sin DSN.

`user`

  El nombre de usuario. Este parámetro se ignora si `dsn` contiene `uid`. Para conectar sin especificar un `user`, use `null`.

`password`

  La contraseña. Este parámetro se ignora si `dsn` contiene `pwd`. Para conectar sin especificar una `password`, use `null`.

`cursor_option`

  Esto establece el tipo de cursor a utilizar para esta conexión. Este parámetro normalmente no es necesario, pero puede ser útil para solucionar problemas con algunos controladores ODBC.

  Las siguientes constantes están definidas para cursortype:

  - SQL_CUR_USE_IF_NEEDED
  - SQL_CUR_USE_ODBC
  - SQL_CUR_USE_DRIVER

### Valores devueltos

Devuelve una conexión ODBC, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `odbc` ahora espera una instancia de Odbc\Connection; anteriormente, se esperaba un resource.
8.4.0 | Esta función ahora devuelve una instancia de Odbc\Connection; anteriormente, se devolvía un resource.
8.4.0 | `user` y `password` ahora pueden ser nulos, también son opcionales y valen por omisión `null`.
8.4.0 | Anteriormente, el uso de una cadena vacía para `password` no incluía `pwd` en la cadena de conexión generada para `dsn`. Ahora, `pwd` se incluye en la cadena de conexión, con un valor de cadena vacía. Para restaurar el comportamiento anterior, `password` puede ser definido como `null`.
8.4.0 | Anteriormente, si `dsn` contenía `uid` o `pwd`, entonces los parámetros `user` y `password` eran ignorados. Ahora, `user` solo es ignorado si `dsn` contiene `uid`, y `password` solo es ignorado si `dsn` contiene `pwd`.

### Ejemplos

Ejemplo #1 Conexiones sin DSN

    <?php
    // Microsoft SQL Server usando el controlador ODBC SQL Native Client 10.0 - permite conexión a SQL 7, 2000, 2005 y 2008
    $connection = odbc_connect("Driver={SQL Server Native Client 10.0};Server=$server;Database=$database;", $user, $password);

    // Microsoft Access
    $connection = odbc_connect("Driver={Microsoft Access Driver (*.mdb)};Dbq=$mdbFilename", $user, $password);

    // Microsoft Excel
    $excelFile = realpath('C:/ExcelData.xls');
    $excelDir = dirname($excelFile);
    $connection = odbc_connect("Driver={Microsoft Excel Driver (*.xls)};DriverId=790;Dbq=$excelFile;DefaultDir=$excelDir" , '', '');
    ?>

### Ver también

- Para conexiones persistentes: odbc_pconnect() - Abre una conexión de base de datos persistente

# odbc_connection_string_is_quoted

(PHP 8 >= 8.2.0)

odbc_connection_string_is_quoted — Determina si un valor de string de conexión ODBC está entre comillas

### Descripción

function odbc_connection_string_is_quoted(string `$str`): bool

Determina si un string está correctamente entre comillas para un string de conexión ODBC. La colocación entre comillas de strings de conexión ODBC se realiza utilizando llaves, y las llaves de cierre en un string deben ser escapadas repitiéndolas dos veces, similar a la colocación entre comillas SQL.

### Parámetros

`str`

  El string a verificar para la colocación entre comillas.

### Valores devueltos

`true` si el string está correctamente entre comillas, `false` en caso contrario.

### Ver también

- odbc_connection_string_quote() - Pone entre comillas un valor de string de conexión ODBC
- odbc_connection_string_should_quote() - Determina si un valor de string de conexión ODBC debe ser puesto entre comillas

# odbc_connection_string_quote

(PHP 8 >= 8.2.0)

odbc_connection_string_quote — Pone entre comillas un valor de string de conexión ODBC

### Descripción

function odbc_connection_string_quote(string `$str`): string

Pone entre comillas un valor de string de conexión, según las reglas ODBC. Es decir, se rodeará de comillas, y cualquier llave de cierre será escapada. Esto debería hacerse para todos los valores de string de conexión que provienen de la entrada del usuario. No hacerlo puede provocar problemas durante el análisis de la string de conexión, o valores inyectados en la string de conexión.

Tenga en cuenta que esta función no verifica si la string ya está entre comillas, ni si la string necesita ser puesta entre comillas. Para ello, llamar a odbc_connection_string_is_quoted() y a odbc_connection_string_should_quote().

### Parámetros

`str`

  La string sin comillas.

### Valores devueltos

Una string, rodeada de comillas, y correctamente escapada.

### Ejemplos

Ejemplo #1 Ejemplo de odbc_connection_string_quote()

Este ejemplo pone entre comillas una string, luego la coloca en una string de conexión. Tenga en cuenta que la string está entre comillas, y el carácter de comilla de cierre en medio de la string ha sido escapado.

    <?php
    $value = odbc_connection_string_quote("foo}bar");
    $connection_string = "DSN=PHP;UserValue=$value";
    echo $connection_string;
    ?>

Resultado del ejemplo anterior es similar a:

    DSN=PHP;UserValue={foo}}bar}

### Ver también

- odbc_connection_string_is_quoted() - Determina si un valor de string de conexión ODBC está entre comillas
- odbc_connection_string_should_quote() - Determina si un valor de string de conexión ODBC debe ser puesto entre comillas

# odbc_connection_string_should_quote

(PHP 8 >= 8.2.0)

odbc_connection_string_should_quote — Determina si un valor de string de conexión ODBC debe ser puesto entre comillas

### Descripción

function odbc_connection_string_should_quote(string `$str`): bool

Determina si un string debe ser puesto entre comillas para una conexión ODBC. Es decir, si contiene caracteres especiales.

Tenga en cuenta que esta función no verifica si el string ya está entre comillas; un string ya entre comillas contendrá caracteres que harán que esta función devuelva verdadero. Se debería llamar a odbc_connection_string_is_quoted() para verificar.

### Parámetros

`str`

  El string a verificar.

### Valores devueltos

`true` si el string debe estar entre comillas, de lo contrario `false`.

### Ver también

- odbc_connection_string_quote() - Pone entre comillas un valor de string de conexión ODBC
- odbc_connection_string_is_quoted() - Determina si un valor de string de conexión ODBC está entre comillas

# odbc_cursor

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_cursor — Lee el nombre del puntero de resultado actual

### Descripción

function odbc_cursor(Odbc\Result `$statement`): string|false

Lee el nombre del puntero del resultado actual.

### Parámetros

`statement`

  El objeto de resultado ODBC.

### Valores devueltos

Devuelve el nombre del cursor, en forma de string, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `statement` ahora espera una instancia de Odbc\Result; anteriormente, se esperaba un resource.

# odbc_data_source

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

odbc_data_source — Devuelve información sobre los DSNs disponibles

### Descripción

function odbc_data_source(Odbc\Connection `$odbc`, int `$fetch_type`): array|null|false

Devuelve una lista de DSN disponibles (tras haberla llamado varias veces).

### Parámetros

`odbc`
  El objeto de conexión ODBC, ver la documentación de la función odbc_connect() para más detalles.
`fetch_type`

  El parámetro `fetch_type` puede ser una de las dos constantes siguientes: `SQL_FETCH_FIRST` o `SQL_FETCH_NEXT`. Utilice `SQL_FETCH_FIRST` la primera vez que se llama a la función, luego `SQL_FETCH_NEXT`.

### Valores devueltos

Devuelve `false` si ocurre un error, un array en caso de éxito, y `null` tras haber recuperado el último DSN disponible.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `odbc` ahora espera una instancia de Odbc\Connection; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Listar los DSNs disponibles

    <?php
    $conn = odbc_connect('dsn', 'user', 'pass');
    $dsn_info = odbc_data_source($conn, SQL_FETCH_FIRST);
    while ($dsn_info) {
        print_r($dsn_info);
        $dsn_info = odbc_data_source($conn, SQL_FETCH_NEXT);
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [server] => dsn
        [description] => ODBC Driver 17 for SQL Server
    )
    Array
    (
        [server] => other_dsn
        [description] => Microsoft Access Driver (*.mdb, *.accdb)
    )

# odbc_do

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_do — Alias de odbc_exec()

### Descripción

Esta función es un alias de: odbc_exec().

# odbc_error

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_error — Lee el último código de error

### Descripción

function odbc_error(?Odbc\Connection `$odbc` = `null`): string

Devuelve un estado ODBC de 6 dígitos, o una cadena vacía si no había más errores.

### Parámetros

`odbc`
  El objeto de conexión ODBC, ver la documentación de la función odbc_connect() para más detalles.

### Valores devueltos

Si `odbc` está especificado, se devuelve el último estado de esa conexión, de lo contrario se devuelve el último estado de cualquier conexión.

Esta función devuelve un valor significativo únicamente si la última consulta ODBC ha fallado (es decir, la función odbc_exec() ha devuelto `false`).

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `odbc` ahora espera una instancia de Odbc\Connection; anteriormente, se esperaba un resource.
8.0.0 | `odbc` es ahora nullable.

### Ver también

- odbc_errormsg() - Lee el último mensaje de error
- odbc_exec() - Ejecuta directamente una consulta SQL

# odbc_errormsg

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_errormsg — Lee el último mensaje de error

### Descripción

function odbc_errormsg(?Odbc\Connection `$odbc` = `null`): string

Devuelve un string que contiene el último mensaje de error ODBC, o un string vacío si no hubo error.

### Parámetros

`odbc`
  El objeto de conexión ODBC, ver la documentación de la función odbc_connect() para más detalles.

### Valores devueltos

Si `odbc` está especificado, el último estado ODBC de esta conexión es devuelto.

Esta función devuelve un valor significativo únicamente si la última consulta ODBC falló (i.e. la función odbc_exec() devolvió `false`).

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `odbc` ahora espera una instancia de Odbc\Connection; anteriormente, se esperaba un resource.
8.0.0 | `odbc` es ahora nullable.

### Ver también

- odbc_error() - Lee el último código de error
- odbc_exec() - Ejecuta directamente una consulta SQL

# odbc_exec

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_exec — Ejecuta directamente una consulta SQL

### Descripción

function odbc_exec(Odbc\Connection `$odbc`, string `$query`): Odbc\Result|false

Envía una sentencia SQL al servidor de base de datos.

### Parámetros

`odbc`
  El objeto de conexión ODBC, ver la documentación de la función odbc_connect() para más detalles.
`query`

  La consulta SQL.

### Valores devueltos

Devuelve un objeto de resultado ODBC si el comando SQL se ejecutó con éxito `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `odbc` ahora espera una instancia de Odbc\Connection; anteriormente, se esperaba un resource.
8.4.0 | Esta función ahora devuelve una instancia de Odbc\Result; anteriormente, se devolvía un resource.
8.0.0 | `flags` fue eliminado.

### Ver también

- odbc_prepare() - Prepara una orden para su ejecución
- odbc_execute() - Ejecuta una consulta SQL preparada

# odbc_execute

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_execute — Ejecuta una consulta SQL preparada

### Descripción

function odbc_execute(Odbc\Result `$statement`, array `$params` = []): bool

Ejecuta una consulta SQL preparada por odbc_prepare().

### Parámetros

`statement`

  El objeto de resultado ODBC desde odbc_prepare().

`params`

  Los valores del parámetro `params` serán sustituidos en las variables de consulta de la consulta preparada. Los elementos de este array serán convertidos a string al llamar a esta función.

  Todo parámetro de `params` que comience y termine con comillas simples será considerado como un nombre de fichero a leer y enviado a la base de datos, con la variable de consulta apropiada.

  Si se desea almacenar un string que comience y termine realmente con comillas, se debe añadir un espacio al inicio o al final del string, para evitar que este parámetro sea confundido con un nombre de fichero. Si esto no es posible en el contexto de la aplicación, se deberá utilizar la función odbc_exec().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Esta función ahora devuelve una instancia de Odbc\Result; anteriormente, se devolvía un resource.
8.0.0 | El parámetro `flags`, sin uso, ha sido eliminado.

### Ejemplos

Ejemplo #1 Ejemplo con odbc_execute() y odbc_prepare()

En el script siguiente, $success solo será posible si los tres parámetros de myproc son parámetros de tipo IN:

    <?php
    $a = 1;
    $b = 2;
    $c = 3;
    $stmt    = odbc_prepare($conn, 'CALL myproc(?,?,?)');
    $success = odbc_execute($stmt, array($a, $b, $c));
    ?>

Si se necesita llamar a un procedimiento almacenado utilizando parámetros INOUT o OUT, la solución es utilizar una extensión nativa de la base de datos (por ejemplo oci8 para Oracle).

### Ver también

- odbc_prepare() - Prepara una orden para su ejecución

# odbc_fetch_array

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

odbc_fetch_array — Lee una línea de resultado en un array asociativo

### Descripción

function odbc_fetch_array(Odbc\Result `$statement`, ?int `$row` = `null`): array|false

Lee un array asociativo desde una consulta ODBC.

### Parámetros

`statement`

  El objeto de resultado ODBC desde odbc_exec().

`row`

  El número de la línea que debe ser leída, opcional.

### Valores devueltos

Devuelve un array correspondiente a la línea recuperada, o `false` si no hay más líneas disponibles.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `statement` ahora espera una instancia de Odbc\Result; anteriormente, se esperaba un resource.
8.4.0 | `row` es ahora nullable.

### Notas

> Nota: Esta función está disponible cuando PHP es compilado con el soporte IBM DB2 o UnixODBC.

### Ver también

- odbc_fetch_row() - Lee una línea de resultado
- odbc_fetch_object() - Lee una línea de resultado en un objeto
- odbc_num_rows() - Número de filas en un resultado

# odbc_fetch_into

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_fetch_into — Lee una línea de resultado y la coloca en un array

### Descripción

function odbc_fetch_into(Odbc\Result `$statement`, array `&$array`, ?int `$row` = `null`): int|false

Lee una línea de resultado y la coloca en un array.

### Parámetros

`statement`

  El objeto de resultado ODBC.

`array`

  El array de resultado que puede ser de cualquier tipo, ya que será convertido en array. El array contendrá los valores de las columnas, estas últimas están numeradas a partir de 0.

`row`

  El número de la línea.

### Valores devueltos

Devuelve el número de columnas del resultado, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `statement` ahora espera una instancia de Odbc\Result; anteriormente, se esperaba un resource.
8.4.0 | `row` es ahora nullable.

### Ejemplos

Ejemplo #1 Ejemplo con odbc_fetch_into()

    <?php
    $rc = odbc_fetch_into($res_id, $my_array);
    ?>

o

    <?php
    $rc = odbc_fetch_into($res_id, $my_array, 2);
    ?>

# odbc_fetch_object

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

odbc_fetch_object — Lee una línea de resultado en un objeto

### Descripción

function odbc_fetch_object(Odbc\Result `$statement`, ?int `$row` = `null`): stdClass|false

Lee un object desde una consulta ODBC.

### Parámetros

`statement`

  El objeto de resultado ODBC desde odbc_exec().

`row`

  El número de línea a recuperar, opcional.

### Valores devueltos

Devuelve un objeto que corresponde a la línea recuperada, o `false` si no hay más líneas disponibles.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `statement` ahora espera una instancia de Odbc\Result; anteriormente, se esperaba un resource.
8.4.0 | `row` es ahora nullable.

### Notas

> Nota: Esta función está disponible cuando PHP es compilado con soporte IBM DB2 o UnixODBC.

### Ver también

- odbc_fetch_row() - Lee una línea de resultado
- odbc_fetch_array() - Lee una línea de resultado en un array asociativo
- odbc_num_rows() - Número de filas en un resultado

# odbc_fetch_row

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_fetch_row — Lee una línea de resultado

### Descripción

function odbc_fetch_row(Odbc\Result `$statement`, ?int `$row` = `null`): bool

Lee una línea de los datos devueltos por odbc_do() o odbc_exec(). Tras odbc_fetch_row(), los campos serán accesibles con la función odbc_result().

### Parámetros

`statement`

  El objeto de resultado ODBC.

`row`

  Si `row` es omitido, `row` intentará leer la siguiente línea en el resultado. Llamadas repetidas a odbc_fetch_row() con y sin parámetro `row` pueden ser combinadas libremente.

  Para revisar todas las líneas de un resultado varias veces, se puede llamar a odbc_fetch_row() con row_number = 1, luego continuar llamando a odbc_fetch_row() sin el parámetro `row` para revisar todo el resultado. Si un controlador no soporta la lectura de líneas por número, el parámetro será ignorado.

### Valores devueltos

Devuelve `true` si la línea existe, `false` en caso contrario.

### Errores/Excepciones

Se emite un `E_WARNING` cuando `row` es igual o inferior a cero.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `statement` ahora espera una instancia de Odbc\Result; anteriormente, se esperaba un resource.
8.4.0 | Ahora se emite un `E_WARNING` cuando `row` es igual o inferior a cero.
8.0.0 | `row` ahora es nullable.

# odbc_field_len

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_len — Lee la longitud de un campo

### Descripción

function odbc_field_len(Odbc\Result `$statement`, int `$field`): int|false

Lee la longitud del campo identificado por su número.

### Parámetros

`statement`

  El objeto de resultado ODBC.

`field`

  El número del campo. La numeración comienza en 1.

### Valores devueltos

Devuelve la longitud del campo o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `statement` ahora espera una instancia de Odbc\Result; anteriormente, se esperaba un resource.

### Ver también

- odbc_field_scale() - Lee la escala de un campopara conocer la escala de un número de coma flotante

# odbc_field_name

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_name — Lee el nombre de la columna

### Descripción

function odbc_field_name(Odbc\Result `$statement`, int `$field`): string|false

Obtiene el nombre del campo que ocupa el número de columna dado en el objeto resultado especificado.

### Parámetros

`statement`

  El objeto de resultado ODBC.

`field`

  El número de la columna. La numeración comienza en 1.

### Valores devueltos

Devuelve el nombre de la columna, como un string, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `statement` ahora espera una instancia de Odbc\Result; anteriormente, se esperaba un resource.

# odbc_field_num

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_num — Número de columna

### Descripción

function odbc_field_num(Odbc\Result `$statement`, string `$field`): int|false

Obtiene el número de la columna correspondiente al campo nombrado en el objeto resultado especificado.

### Parámetros

`statement`

  El objeto de resultado ODBC.

`field`

  El nombre del campo.

### Valores devueltos

Devuelve el número del campo, en forma de int, o `false` si ocurre un error. La numeración comienza en 1.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `statement` ahora espera una instancia de Odbc\Result; anteriormente, se esperaba un resource.

# odbc_field_precision

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_precision — Alias de odbc_field_len()

### Descripción

Esta función es un alias de: odbc_field_len().

### Ver también

- odbc_field_scale() - Lee la escala de un campo para conocer la escala de un número de coma flotante.

# odbc_field_scale

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_scale — Lee la escala de un campo

### Descripción

function odbc_field_scale(Odbc\Result `$statement`, int `$field`): int|false

Lee la escala del campo referenciado por número en el resultado ODBC dado.

### Parámetros

`statement`

  El objeto de resultado ODBC.

`field`

  El número del campo. La numeración comienza en 1.

### Valores devueltos

Devuelve la escala del campo, en forma de int, o `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `statement` ahora espera una instancia de Odbc\Result; anteriormente, se esperaba un resource.

# odbc_field_type

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_type — Tipo de datos de un campo

### Descripción

function odbc_field_type(Odbc\Result `$statement`, int `$field`): string|false

Lee el tipo de datos SQL de un campo, identificado por su número.

### Parámetros

`statement`

  El objeto de resultado ODBC.

`field`

  El número del campo. La numeración comienza en 1.

### Valores devueltos

Devuelve el tipo del campo, en forma de string, o `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `statement` ahora espera una instancia de Odbc\Result; anteriormente, se esperaba un resource.

# odbc_foreignkeys

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_foreignkeys — Lista las claves foráneas

### Descripción

function odbc_foreignkeys(
Odbc\Connection `$odbc`,
?string `$pk_catalog`,
string `$pk_schema`,
string `$pk_table`,
string `$fk_catalog`,
string `$fk_schema`,
string `$fk_table`
): Odbc\Result|false

Devuelve una lista de claves foráneas en la tabla especificada o una lista de claves foráneas en otras tablas que hacen referencia a la clave primaria en la tabla especificada.

### Parámetros

`odbc`
  El objeto de conexión ODBC, ver la documentación de la función odbc_connect() para más detalles.
`fk_catalog`

  El catálogo ('qualifier' en terminología ODBC 2) de la clave primaria de la tabla.

`pk_schema`

  El esquema ('qualifier' en terminología ODBC 2) de la clave primaria de la tabla.

`pk_table`

  La tabla de clave primaria.

`pk_catalog`

  El catálogo ('qualifier' en terminología ODBC 2) de la clave foránea de la tabla.

`fk_schema`

  El esquema ('qualifier' en terminología ODBC 2) de la clave foránea de la tabla.

`fk_table`

  La tabla de clave foránea.

### Valores devueltos

Devuelve un objeto de resultado ODBC o `false` si ocurre un error.

El conjunto de resultados contiene las siguientes columnas:

- `PKTABLE_CAT`
- `PKTABLE_SCHEM`
- `PKTABLE_NAME`
- `PKCOLUMN_NAME`
- `FKTABLE_CAT`
- `FKTABLE_SCHEM`
- `FKTABLE_NAME`
- `FKCOLUMN_NAME`
- `KEY_SEQ`
- `UPDATE_RULE`
- `DELETE_RULE`
- `FK_NAME`
- `PK_NAME`
- `DEFERRABILITY`

Los controladores pueden indicar columnas adicionales.

Si las claves foráneas asociadas con una clave primaria son solicitadas, el conjunto de resultados está ordenado por `FKTABLE_CAT`, `FKTABLE_SCHEM`, `FKTABLE_NAME` y `KEY_SEQ`. Si las claves primarias asociadas con una clave foránea son solicitadas, el conjunto de resultados está ordenado por `PKTABLE_CAT`, `PKTABLE_SCHEM`, `PKTABLE_NAME` y `KEY_SEQ`.

Si `pk_table` contiene un nombre de tabla, odbc_foreignkeys() retorna la clave primaria de la tabla `pk_table`, y todas las claves foráneas que hacen referencia a ella.

Si `fk_table` contiene un nombre de tabla, odbc_foreignkeys() retorna la lista de claves foráneas de la tabla `fk_table`, y las claves primarias (de otras tablas) que hacen referencia a ella.

Si `pk_table` y `fk_table` contienen nombres de tablas, odbc_foreignkeys() retorna la lista de claves foráneas de la tabla `fk_table` que utilizan la clave primaria de la tabla `pk_table`. Esta lista debería contener como máximo una clave.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `odbc` ahora espera una instancia de Odbc\Connection; anteriormente, se esperaba un resource.
8.4.0 | Esta función ahora devuelve una instancia de Odbc\Result; anteriormente, se devolvía un resource.

### Ver también

- odbc_tables() - Lista las tablas de una fuente
- odbc_primarykeys() - Lista las columnas utilizadas en una clave primaria

# odbc_free_result

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_free_result — Libera los objetos asociados a un resultado

### Descripción

function odbc_free_result(Odbc\Result `$statement`): true

Libera los objetos asociados a un resultado.

odbc_free_result() solo es necesario si se teme utilizar demasiada memoria durante la ejecución del script. Todos los resultados en memoria se liberarán al final del script.

### Parámetros

`statement`

  El objeto de resultado ODBC.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `statement` ahora espera una instancia de Odbc\Result; anteriormente, se esperaba un resource.

### Notas

> Nota:

> Si la autovalidación está desactivada (ver odbc_autocommit()) y se llama a odbc_free_result() antes de validar las consultas, todas las transacciones preparadas se cancelarán.

# odbc_gettypeinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_gettypeinfo — Lista los tipos de datos soportados por un origen

### Descripción

function odbc_gettypeinfo(Odbc\Connection `$odbc`, int `$data_type` = 0): Odbc\Result|false

Lista los tipos de datos soportados por un origen.

### Parámetros

`odbc`
  El objeto de conexión ODBC, ver la documentación de la función odbc_connect() para más detalles.
`data_type`

  Puede ser utilizado para restringir la información a un solo tipo de datos.

### Valores devueltos

Devuelve un objeto de resultado ODBC o `false` si ocurre un error.

El resultado posee las columnas siguientes:

- TYPE_NAME
- DATA_TYPE
- PRECISION
- LITERAL_PREFIX
- LITERAL_SUFFIX
- CREATE_PARAMS
- NULLABLE
- CASE_SENSITIVE
- SEARCHABLE
- UNSIGNED_ATTRIBUTE
- MONEY
- AUTO_INCREMENT
- LOCAL_TYPE_NAME
- MINIMUM_SCALE
- MAXIMUM_SCALE

El resultado está ordenado por DATA_TYPE y TYPE_NAME.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `odbc` ahora espera una instancia de Odbc\Connection; anteriormente, se esperaba un resource.
8.4.0 | Esta función ahora devuelve una instancia de Odbc\Result; anteriormente, se devolvía un resource.

# odbc_longreadlen

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_longreadlen — Gestión de columnas de tipo LONG

### Descripción

function odbc_longreadlen(Odbc\Result `$statement`, int `$length`): true

Activa la gestión de columnas de tipo `LONG`, `LONGVARCHAR` y `LONGVARBINARY`. La longitud por defecto puede ser definida utilizando la directiva php.ini uodbc.defaultlrl.

### Parámetros

`statement`

  El objeto de resultado ODBC.

`length`

  El número de bytes retornado a PHP. Si se define como `0`, los datos de las columnas de tipo LONG son pasados al cliente (es decir, impresos) cuando son recuperados con la función odbc_result().

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `statement` ahora espera una instancia de Odbc\Result; anteriormente, se esperaba un resource.

### Notas

> Nota:

> La gestión de tipos `LONGVARBINARY` también es afectada por odbc_binmode().

# odbc_next_result

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_next_result — Verifica si hay múltiples resultados disponibles

### Descripción

function odbc_next_result(Odbc\Result `$statement`): bool

Verifica si hay más conjuntos de resultados disponibles accesibles mediante las funciones odbc_fetch_array(), odbc_fetch_row(), odbc_result(), etc.

### Parámetros

`statement`

  El objeto de resultado ODBC.

### Valores devueltos

Devuelve `true` si hay más conjuntos de resultados, `false` en caso contrario.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `statement` ahora espera una instancia de Odbc\Result; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con odbc_next_result()

    <?php
    $r_Connection = odbc_connect($dsn, $username, $password);

    $s_SQL = <<<END_SQL
    SELECT 'A'
    SELECT 'B'
    SELECT 'C'
    END_SQL;

    $r_Results = odbc_exec($r_Connection, $s_SQL);

    $a_Row1 = odbc_fetch_array($r_Results);
    $a_Row2 = odbc_fetch_array($r_Results);
    echo "Muestra el primer conjunto de resultados: ";
    var_dump($a_Row1, $a_Row2);

    echo "Recuperación del segundo conjunto de resultados: ";
    var_dump(odbc_next_result($r_Results));

    $a_Row1 = odbc_fetch_array($r_Results);
    $a_Row2 = odbc_fetch_array($r_Results);
    echo "Muestra el segundo conjunto de resultados: ";
    var_dump($a_Row1, $a_Row2);

    echo "Recuperación del tercer conjunto de resultados: ";
    var_dump(odbc_next_result($r_Results));

    $a_Row1 = odbc_fetch_array($r_Results);
    $a_Row2 = odbc_fetch_array($r_Results);
    echo "Muestra el tercer conjunto de resultados: ";
    var_dump($a_Row1, $a_Row2);

    echo "Intento de recuperar un cuarto conjunto de resultados: ";
    var_dump(odbc_next_result($r_Results));
    ?>

El ejemplo anterior mostrará:

    Muestra el primer conjunto de resultados: array(1) {
      ["A"]=>
      string(1) "A"
    }
    bool(false)
    Recuperación del segundo conjunto de resultados:bool(true)
    Muestra el segundo conjunto de resultados: array(1) {
      ["B"]=>
      string(1) "B"
    }
    bool(false)
    Recuperación del tercer conjunto de resultados: bool(true)
    Muestra el tercer conjunto de resultados: array(1) {
      ["C"]=>
      string(1) "C"
    }
    bool(false)
    Intento de recuperar un cuarto conjunto de resultados: bool(false)

# odbc_num_fields

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_num_fields — Número de columnas en un resultado

### Descripción

function odbc_num_fields(Odbc\Result `$statement`): int

Obtiene el número de columnas en un resultado ODBC.

### Parámetros

`statement`

  El objeto de resultado ODBC devuelto por la función odbc_exec().

### Valores devueltos

Devuelve el número de columnas, o -1 en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `statement` ahora espera una instancia de Odbc\Result; anteriormente, se esperaba un resource.

# odbc_num_rows

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_num_rows — Número de filas en un resultado

### Descripción

function odbc_num_rows(Odbc\Result `$statement`): int

Lee el número de filas en un resultado. Para los comandos INSERT, UPDATE y DELETE, odbc_num_rows() devuelve el número de filas afectadas. Para los comandos SELECT, esto PUEDE ser el número de filas disponibles, pero no es seguro.

### Parámetros

`statement`

  El objeto de resultado ODBC devuelto por la función odbc_exec().

### Valores devueltos

Devuelve el número de filas en el resultado ODBC. Esta función devolverá -1 si ocurre un error.

### Notas

> Nota:

> El uso de la función odbc_num_rows() para determinar el número de filas disponibles después de un SELECT devolverá -1 con la mayoría de los controladores.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `statement` ahora espera una instancia de Odbc\Result; anteriormente, se esperaba un resource.

# odbc_pconnect

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_pconnect — Abre una conexión de base de datos persistente

### Descripción

function odbc_pconnect(
string `$dsn`,
?string `$user` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
int `$cursor_option` = `SQL_CUR_USE_DRIVER`
): Odbc\Connection|false

Abre una conexión de base de datos persistente.

Esta función es similar a odbc_connect(), excepto que la conexión no se cierra realmente cuando el script ha terminado. Las futuras solicitudes de conexión con la misma combinación de `dsn`, `user`, `password` (a través de odbc_connect() y odbc_pconnect()) pueden reutilizar la conexión persistente.

### Parámetros

Consulte odbc_connect() para obtener detalles.

### Valores devueltos

Devuelve una conexión ODBC, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `odbc` ahora espera una instancia de Odbc\Connection; anteriormente, se esperaba un resource.
8.4.0 | Esta función ahora devuelve una instancia de Odbc\Connection; anteriormente, se devolvía un resource.
8.4.0 | `user` y `password` ahora pueden ser nulos, también son opcionales y valen por omisión `null`.
8.4.0 | Anteriormente, el uso de una cadena vacía para `password` no incluía `pwd` en la cadena de conexión generada para `dsn`. Ahora, `pwd` se incluye en la cadena de conexión, con un valor de cadena vacía. Para restaurar el comportamiento anterior, `password` puede ser definido como `null`.
8.4.0 | Anteriormente, si `dsn` contenía `uid` o `pwd`, entonces los parámetros `user` y `password` eran ignorados. Ahora, `user` solo es ignorado si `dsn` contiene `uid`, y `password` solo es ignorado si `dsn` contiene `pwd`.

### Notas

> Nota: Las conexiones persistentes no tienen efecto si PHP se usa como un programa CGI.

### Ver también

- odbc_connect() - Conectar a una fuente de datos
- Conexiones de base de datos persistentes

# odbc_prepare

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_prepare — Prepara una orden para su ejecución

### Descripción

function odbc_prepare(Odbc\Connection `$odbc`, string `$query`): Odbc\Result|false

Prepara una orden para su ejecución. El objeto de resultado ODBC puede ser utilizado más tarde para ejecutar la orden con odbc_execute().

Algunas bases de datos (como IBM DB2, MS SQL Server y Oracle) soportan los procedimientos almacenados que aceptan los tipos de parámetros IN, INOUT y OUT como se definen en las especificaciones ODBC. Sin embargo, el driver unificado ODBC soporta actualmente únicamente el tipo de parámetros IN para los procedimientos almacenados.

### Parámetros

`odbc`
  El objeto de conexión ODBC, ver la documentación de la función odbc_connect() para más detalles.
`query`

  La consulta a preparar.

### Valores devueltos

Devuelve un objeto de resultado ODBC si la orden SQL ha sido preparada con éxito. Retorna `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `odbc` ahora espera una instancia de Odbc\Connection; anteriormente, se esperaba un resource.
8.4.0 | Esta función ahora devuelve una instancia de Odbc\Result; anteriormente, se devolvía un resource.

### Ejemplos

Ejemplo #1 Ejemplo con odbc_prepare() y odbc_execute()

En el código siguiente, $res solo será válido si los tres parámetros para myproc son parámetros IN:

    <?php
    $a = 1;
    $b = 2;
    $c = 3;
    $stmt = odbc_prepare($conn, 'CALL myproc(?,?,?)');
    $res  = odbc_execute($stmt, array($a, $b, $c));
    ?>

Si necesita llamar a un procedimiento almacenado que utilice parámetros INOUT o OUT, se recomienda utilizar la extensión nativa de su base de datos (por ejemplo oci8 para Oracle).

### Ver también

- odbc_execute() - Ejecuta una consulta SQL preparada

# odbc_primarykeys

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_primarykeys — Lista las columnas utilizadas en una clave primaria

### Descripción

function odbc_primarykeys(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`
): Odbc\Result|false

Devuelve un objeto resultado que puede ser utilizado para recuperar los nombres de las columnas que componen la clave primaria de una tabla.

### Parámetros

`odbc`
  El objeto de conexión ODBC, ver la documentación de la función odbc_connect() para más detalles.
`catalog`

  El catálogo ('calificativo' en el argot ODBC 2).

`schema`

  El esquema ('propietario' en el argot ODBC 2).

`table`

### Valores devueltos

Devuelve un objeto de resultado ODBC o `false` si ocurre un error.

El conjunto de resultados contiene las siguientes columnas:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `COLUMN_NAME`
- `KEY_SEQ`
- `PK_NAME`

Los controladores pueden indicar columnas adicionales.

El conjunto de resultados está ordenado por `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME` y `KEY_SEQ`.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `odbc` ahora espera una instancia de Odbc\Connection; anteriormente, se esperaba un resource.
8.4.0 | Esta función ahora devuelve una instancia de Odbc\Result; anteriormente, se devolvía un resource.

### Ejemplos

Ejemplo #1 Listar las Claves primarias de una Columna

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $primarykeys = odbc_primarykeys($conn, 'TutorialDB', 'dbo', 'TEST');
    while (($row = odbc_fetch_array($primarykeys))) {
        print_r($row);
        break; // filas adicionales omitidas por brevedad
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [TABLE_CAT] => TutorialDB
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => TEST
        [COLUMN_NAME] => id
        [KEY_SEQ] => 1
        [PK_NAME] => PK__TEST__3213E83FE141F843
    )

### Ver también

- odbc_tables() - Lista las tablas de una fuente
- odbc_foreignkeys() - Lista las claves foráneas

# odbc_procedurecolumns

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_procedurecolumns — Lista los parámetros de los procedimientos

### Descripción

function odbc_procedurecolumns(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$procedure` = `null`,
?string `$column` = `null`
): Odbc\Result|false

Lista los parámetros de los procedimientos.

### Parámetros

`odbc`
  El objeto de conexión ODBC, ver la documentación de la función odbc_connect() para más detalles.
`catalog`

  El catálogo ('calificativo' en el argot ODBC 2).

`schema`

  El esquema ('propietario' en el argot ODBC 2). Este parámetro acepta los siguientes patrones de búsqueda: `%` para buscar cero o más caracteres, y `_` para buscar un solo carácter.

`procedure`

  El procedimiento. Este parámetro acepta los siguientes patrones de búsqueda: `%` para buscar cero o más caracteres, y `_` para buscar un solo carácter.

`column`

  La columna. Este parámetro acepta los siguientes patrones de búsqueda: `%` para buscar cero o más caracteres, y `_` para buscar un solo carácter.

### Valores devueltos

Devuelve los parámetros de entrada y salida, así como las columnas utilizadas en los procedimientos designados por los argumentos. Devuelve un objeto de resultado ODBC o `false` si ocurre un error.

El conjunto de resultados contiene las siguientes columnas:

- `PROCEDURE_CAT`
- `PROCEDURE_SCHEM`
- `PROCEDURE_NAME`
- `COLUMN_NAME`
- `COLUMN_TYPE`
- `DATA_TYPE`
- `TYPE_NAME`
- `COLUMN_SIZE`
- `BUFFER_LENGTH`
- `DECIMAL_DIGITS`
- `NUM_PREC_RADIX`
- `NULLABLE`
- `REMARKS`
- `COLUMN_DEF`
- `SQL_DATA_TYPE`
- `SQL_DATETIME_SUB`
- `CHAR_OCTET_LENGTH`
- `ORDINAL_POSITION`
- `IS_NULLABLE`

Los controladores pueden indicar columnas adicionales.

El conjunto de resultados está ordenado por `PROCEDURE_CAT`, `PROCEDURE_SCHEM`, `PROCEDURE_NAME` y `COLUMN_TYPE`.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `odbc` ahora espera una instancia de Odbc\Connection; anteriormente, se esperaba un resource.
8.4.0 | Esta función ahora devuelve una instancia de Odbc\Result; anteriormente, se devolvía un resource.
8.0.0 | Antes de esta versión, la función solo podía ser llamada con uno o cinco argumentos.

### Ejemplos

Ejemplo #1 Lista las columnas de un procedimiento almacenado

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $columns = odbc_procedurecolumns($conn, 'TutorialDB', 'dbo', 'GetEmployeeSalesYTD;1', '%');
    while (($row = odbc_fetch_array($columns))) {
        print_r($row);
        break; // filas adicionales omitidas por brevedad
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [PROCEDURE_CAT] => TutorialDB
        [PROCEDURE_SCHEM] => dbo
        [PROCEDURE_NAME] => GetEmployeeSalesYTD;1
        [COLUMN_NAME] => @SalesPerson
        [COLUMN_TYPE] => 1
        [DATA_TYPE] => -9
        [TYPE_NAME] => nvarchar
        [COLUMN_SIZE] => 50
        [BUFFER_LENGTH] => 100
        [DECIMAL_DIGITS] =>
        [NUM_PREC_RADIX] =>
        [NULLABLE] => 1
        [REMARKS] =>
        [COLUMN_DEF] =>
        [SQL_DATA_TYPE] => -9
        [SQL_DATETIME_SUB] =>
        [CHAR_OCTET_LENGTH] => 100
        [ORDINAL_POSITION] => 1
        [IS_NULLABLE] => YES
    )

### Ver también

- odbc_columns() - Lista las columnas de una tabla

# odbc_procedures

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_procedures — Lista los procedimientos almacenados

### Descripción

function odbc_procedures(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$procedure` = `null`
): Odbc\Result|false

Lista los procedimientos almacenados.

### Parámetros

`odbc`
  El objeto de conexión ODBC, ver la documentación de la función odbc_connect() para más detalles.
`catalog`

  El catálogo ('calificativo' en el argot ODBC 2).

`schema`

  El esquema ('propietario' en el argot ODBC 2). Este parámetro acepta los siguientes patrones de búsqueda: `%` para buscar cero o más caracteres, y `_` para buscar un solo carácter.

`procedure`

  El nombre. Este parámetro acepta los siguientes patrones de búsqueda: `%` para buscar cero o más caracteres, y `_` para buscar un solo carácter.

### Valores devueltos

Devuelve un objeto de resultado ODBC que contiene las informaciones o `false` si ocurre un error.

El conjunto de resultados contiene las columnas siguientes:

- `PROCEDURE_CAT`
- `PROCEDURE_SCHEM`
- `PROCEDURE_NAME`
- `NUM_INPUT_PARAMS`
- `NUM_OUTPUT_PARAMS`
- `NUM_RESULT_SETS`
- `REMARKS`
- `PROCEDURE_TYPE`

Los controladores pueden indicar columnas adicionales.

El conjunto de resultados está ordenado por `PROCEDURE_CAT`, `PROCEDURE_SCHEMA` y `PROCEDURE_NAME`.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `odbc` ahora espera una instancia de Odbc\Connection; anteriormente, se esperaba un resource.
8.4.0 | Esta función ahora devuelve una instancia de Odbc\Result; anteriormente, se devolvía un resource.
8.0.0 | Antes de esta versión, la función solo podía ser llamada con uno o cuatro argumentos.

### Ejemplos

Ejemplo #1 Lista los procedimientos almacenados de una base de datos

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $procedures = odbc_procedures($conn, $catalog, $schema, '%');
    while (($row = odbc_fetch_array($procedures))) {
        print_r($row);
        break; // filas adicionales omitidas por brevedad
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [PROCEDURE_CAT] => TutorialDB
        [PROCEDURE_SCHEM] => dbo
        [PROCEDURE_NAME] => GetEmployeeSalesYTD;1
        [NUM_INPUT_PARAMS] => -1
        [NUM_OUTPUT_PARAMS] => -1
        [NUM_RESULT_SETS] => -1
        [REMARKS] =>
        [PROCEDURE_TYPE] => 2
    )

### Ver también

- odbc_procedurecolumns() - Lista los parámetros de los procedimientos
- odbc_tables() - Lista las tablas de una fuente

# odbc_result

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_result — Lee un campo de resultado UODBC

### Descripción

function odbc_result(Odbc\Result `$statement`, string|int `$field`): string|bool|null

Lee un campo de resultado UODBC.

### Parámetros

`statement`

  El objeto de resultado ODBC.

`field`

  El nombre del campo a recuperar. Puede ser tanto un entero, que contiene el número de columna del campo, en el resultado, como una cadena de caracteres, que representa el nombre del campo.

### Valores devueltos

Devuelve el contenido del campo, `false` si ocurre un error, `null` para datos NULL, o `true` para datos binarios.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `statement` ahora espera una instancia de Odbc\Result; anteriormente, se esperaba un resource.

### Ejemplos

La primera llamada a odbc_result() devuelve el valor del tercer campo de la fila actual del resultado de la consulta. La segunda llamada a odbc_result() devuelve el valor del tercer campo cuyo nombre es "val" de la fila actual del resultado de la consulta. Se produce un error si el parámetro de columna es inferior a 1, o supera el número de columnas del resultado. De la misma manera, se produce un error si el nombre del campo pasado no corresponde a ningún campo en el resultado.

Ejemplo #1 Ejemplo con odbc_result()

    <?php
    $item_3   = odbc_result($Query_ID, 3);
    $item_val = odbc_result($Query_ID, "val");
    ?>

### Notas

Los índices de campos comienzan en 1. Para más información sobre cómo leer columnas de tipo binario o largo, consulte odbc_binmode() y odbc_longreadlen().

# odbc_result_all

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_result_all — Muestra el resultado en forma de tabla HTML

Advertencia

Esta función está OBSOLETA a partir de PHP 8.1.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function odbc_result_all(Odbc\Result `$statement`, string `$format` = ""): int|false

Muestra todas las filas de un resultado producido por odbc_exec(). La visualización se realiza en formato HTML. Los datos no están escapados.

Esta función no está destinada a ser utilizada en un entorno de producción; está prevista para el desarrollo para mostrar rápidamente un conjunto de resultados.

### Parámetros

`statement`

  El objeto de resultado ODBC.

`format`

  Permite modificar el aspecto global de la tabla.

### Valores devueltos

Devuelve el número de filas del resultado, o `false` si se produce un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `statement` ahora espera una instancia de Odbc\Result; anteriormente, se esperaba un resource.
8.1.0 | Esta función ha sido declarada obsoleta.

# odbc_rollback

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_rollback — Anula una transacción

### Descripción

function odbc_rollback(Odbc\Connection `$odbc`): bool

Anula todas las transacciones en la conexión.

### Parámetros

`odbc`
  El objeto de conexión ODBC, ver la documentación de la función odbc_connect() para más detalles.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `odbc` ahora espera una instancia de Odbc\Connection; anteriormente, se esperaba un resource.

# odbc_setoption

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_setoption — Modifica los parámetros ODBC

### Descripción

function odbc_setoption(
Odbc\Connection|Odbc\Result `$odbc`,
int `$which`,
int `$option`,
int `$value`
): bool

odbc_setoption() permite acceder a las opciones ODBC para una conexión particular o un resultado de consulta. Fue escrita para ayudar a la resolución de problemas relacionados con los controladores ODBC problemáticos. Será necesario utilizar odbc_setoption() si se es un programador ODBC y se comprenden los diversos efectos de las opciones disponibles. Asimismo, se necesitará un buen manual de referencia para comprender las opciones y su uso. Diferentes versiones de controladores admiten diferentes versiones de opciones.

Dado que los efectos pueden variar de un controlador a otro, el uso de odbc_setoption() en scripts destinados a ser entregados al público está muy fuertemente desaconsejado. Además, ciertas opciones ODBC no están disponibles porque deben ser fijadas antes del establecimiento de la conexión. Sin embargo, si en un caso bien específico, odbc_setoption() permite utilizar PHP sin que el jefe obligue a usar un producto comercial, entonces no importa.

### Parámetros

`odbc`

  Un identificador de conexión, o un identificador de resultado, para el cual se desea modificar opciones. Para SQLSetConnectOption(), es un identificador de conexión. Para SQLSetStmtOption(), es un identificador de resultado.

`which`

  Función ODBC a utilizar. El valor debe ser 1 para SQLSetConnectOption() y 2 para SQLSetStmtOption().

`option`

  La opción a definir.

`value`

  El valor para el parámetro `option` dado.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `odbc` espera ahora una instancia de Odbc\Connection o de Odbc\Result; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con odbc_setoption()

    <?php
    // 1. La opción 102 de SQLSetConnectOption() es SQL_AUTOCOMMIT.
    // 1 de SQL_AUTOCOMMIT es SQL_AUTOCOMMIT_ON.
    //    Este ejemplo tiene el mismo efecto que
    //    odbc_autocommit($conn, true);

    odbc_setoption($conn, 1, 102, 1);

    // 2. Opción 0 de SQLSetStmtOption() es SQL_QUERY_TIMEOUT.
    //    Este ejemplo fija el tiempo límite a 30 segundos.

    $result = odbc_prepare($conn, $sql);
    odbc_setoption($result, 2, 0, 30);
    odbc_execute($result);
    ?>

# odbc_specialcolumns

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_specialcolumns — Devuelve el conjunto óptimo de columnas

### Descripción

function odbc_specialcolumns(
Odbc\Connection `$odbc`,
int `$type`,
?string `$catalog`,
string `$schema`,
string `$table`,
int `$scope`,
int `$nullable`
): Odbc\Result|false

Devuelve el conjunto óptimo de columnas que identifica de manera única una fila de una tabla, o las columnas que se actualizan automáticamente cuando alguno de los valores de la fila es modificado por una transacción.

### Parámetros

`odbc`
  El objeto de conexión ODBC, ver la documentación de la función odbc_connect() para más detalles.
`type`
  Cuando el tipo es `SQL_BEST_ROWID`, odbc_specialcolumns() devuelve la o las columnas que permiten identificar de manera única cada fila de una tabla. Cuando el tipo es `SQL_ROWVER`, odbc_specialcolumns() devuelve la columna o las columnas de la tabla especificada, si las hay, que se actualizan automáticamente por los datos de origen cuando cada valor de la fila es modificado por cualquier transacción.
`catalog`

  El catálogo ('calificativo' en el argot ODBC 2).

`schema`

  El esquema ('propietario' en el argot ODBC 2).

`table`

  La tabla.

`scope`

  El `scope`, que ordena el conjunto de resultados. Uno de `SQL_SCOPE_CURROW`, `SQL_SCOPE_TRANSACTION` o `SQL_SCOPE_SESSION`.

`nullable`

  Determina si las columnas especiales que pueden tener un valor NULL deben ser devueltas o no. Uno de `SQL_NO_NULLS` o `SQL_NULLABLE`.

### Valores devueltos

Devuelve un objeto de resultado ODBC o `false` si ocurre un error.

El conjunto de resultados contiene las siguientes columnas:

- `SCOPE`
- `COLUMN_NAME`
- `DATA_TYPE`
- `TYPE_NAME`
- `COLUMN_SIZE`
- `BUFFER_LENGTH`
- `DECIMAL_DIGITS`
- `PSEUDO_COLUMN`

Los controladores pueden indicar columnas adicionales.

El conjunto de resultados está ordenado por `SCOPE`.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `odbc` ahora espera una instancia de Odbc\Connection; anteriormente, se esperaba un resource.
8.4.0 | Esta función ahora devuelve una instancia de Odbc\Result; anteriormente, se devolvía un resource.

### Ver también

- odbc_tables() - Lista las tablas de una fuente

# odbc_statistics

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_statistics — Cálculo de estadísticas sobre una tabla

### Descripción

function odbc_statistics(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`,
int `$unique`,
int `$accuracy`
): Odbc\Result|false

Cálculo de estadísticas sobre una tabla.

### Parámetros

`odbc`
  El objeto de conexión ODBC, ver la documentación de la función odbc_connect() para más detalles.
`catalog`

  El catálogo ('calificativo' en el argot ODBC 2).

`schema`

  El esquema ('propietario' en el argot ODBC 2).

`table`

  El nombre de la tabla.

`unique`

  El tipo del índice. Uno de `SQL_INDEX_UNIQUE` o `SQL_INDEX_ALL`.

`accuracy`

  Uno de `SQL_ENSURE` o `SQL_QUICK`. Este último solicita al controlador que recupere `CARDINALITY` y `PAGES` solo si están inmediatamente disponibles desde el servidor.

### Valores devueltos

Devuelve un objeto de resultado ODBC o `false` si ocurre un error.

El conjunto de resultados contiene las siguientes columnas:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `NON_UNIQUE`
- `INDEX_QUALIFIER`
- `INDEX_NAME`
- `TYPE`
- `ORDINAL_POSITION`
- `COLUMN_NAME`
- `ASC_OR_DESC`
- `CARDINALITY`
- `PAGES`
- `FILTER_CONDITION`

Los controladores pueden indicar columnas adicionales.

El conjunto de resultados está ordenado por `NON_UNIQUE`, `TYPE`, `INDEX_QUALIFIER`, `INDEX_NAME` y `ORDINAL_POSITION`.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `odbc` ahora espera una instancia de Odbc\Connection; anteriormente, se esperaba un resource.
8.4.0 | Esta función ahora devuelve una instancia de Odbc\Result; anteriormente, se devolvía un resource.

### Ejemplos

Ejemplo #1 Lista las estadísticas de una tabla

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $statistics = odbc_statistics($conn, 'TutorialDB', 'dbo', 'TEST', SQL_INDEX_UNIQUE, SQL_QUICK);
    while (($row = odbc_fetch_array($statistics))) {
        print_r($row);
        break; // filas adicionales omitidas por brevedad
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [TABLE_CAT] => TutorialDB
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => TEST
        [NON_UNIQUE] =>
        [INDEX_QUALIFIER] =>
        [INDEX_NAME] =>
        [TYPE] => 0
        [ORDINAL_POSITION] =>
        [COLUMN_NAME] =>
        [ASC_OR_DESC] =>
        [CARDINALITY] => 15
        [PAGES] => 3
        [FILTER_CONDITION] =>
    )

### Ver también

- odbc_tables() - Lista las tablas de una fuente

# odbc_tableprivileges

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_tableprivileges — Lista las tablas y sus privilegios

### Descripción

function odbc_tableprivileges(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`
): Odbc\Result|false

Lista las tablas y sus privilegios.

### Parámetros

`odbc`
  El objeto de conexión ODBC, ver la documentación de la función odbc_connect() para más detalles.
`catalog`

  El catálogo ('calificativo' en el argot ODBC 2).

`schema`

  El esquema ('propietario' en el argot ODBC 2). Este parámetro acepta los siguientes patrones de búsqueda: `%` para buscar cero o más caracteres, y `_` para buscar un solo carácter.

`table`

  El nombre. Este parámetro acepta los siguientes patrones de búsqueda: `%` para buscar cero o más caracteres, y `_` para buscar un solo carácter.

### Valores devueltos

Devuelve un objeto de resultado ODBC o `false` si ocurre un error.

El conjunto de resultados contiene las siguientes columnas:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `GRANTOR`
- `GRANTEE`
- `PRIVILEGE`
- `IS_GRANTABLE`

Los controladores pueden indicar columnas adicionales.

El conjunto de resultados está ordenado por `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME`, `PRIVILEGE` y `GRANTEE`.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `odbc` ahora espera una instancia de Odbc\Connection; anteriormente, se esperaba un resource.
8.4.0 | Esta función ahora devuelve una instancia de Odbc\Result; anteriormente, se devolvía un resource.

### Ejemplos

Ejemplo #1 Lista los Privilegios de una Tabla

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $privileges = odbc_tableprivileges($conn, 'SalesOrders', 'dbo', 'Orders');
    while (($row = odbc_fetch_array($privileges))) {
        print_r($row);
        break; // se omiten filas adicionales por brevedad
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [TABLE_CAT] => SalesOrders
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => Orders
        [GRANTOR] => dbo
        [GRANTEE] => dbo
        [PRIVILEGE] => DELETE
        [IS_GRANTABLE] => YES
    )

### Ver también

- odbc_tables() - Lista las tablas de una fuente

# odbc_tables

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_tables — Lista las tablas de una fuente

### Descripción

function odbc_tables(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$table` = `null`,
?string `$types` = `null`
): Odbc\Result|false

Lista las tablas de una fuente.

Para soportar las enumeraciones de calificadores propietarios y tipos de tabla, la siguiente semántica para los parámetros `catalog`, `schema`, `table` y `table_type` está disponible:

- Si `catalog` es un signo de porcentaje (%), y `schema` y `table` son strings vacíos, entonces el resultado contiene la lista de calificadores válidos para la fuente (todas las columnas excepto TABLE_QUALIFIER contienen NULL).
- Si `schema` es un signo de porcentaje (%), y `catalog` y `table` son strings vacíos, entonces el resultado contiene la lista de propietarios de la fuente (todas las columnas excepto TABLE_OWNER contienen NULL).
- Si `table_type` es un signo de porcentaje (%), y `catalog`, `schema` y `table` son strings vacíos, entonces el resultado contiene la lista de tipos de tablas de la fuente (todas las columnas excepto TABLE_TYPE contienen NULL).

### Parámetros

`odbc`
  El objeto de conexión ODBC, ver la documentación de la función odbc_connect() para más detalles.
`catalog`

  El catálogo ('calificativo' en el argot ODBC 2).

`schema`

  El esquema ('propietario' en el argot ODBC 2). Este parámetro acepta los siguientes patrones de búsqueda: `%` para buscar cero o más caracteres, y `_` para buscar un solo carácter.

`table`

  El nombre. Este parámetro acepta los siguientes patrones de búsqueda: `%` para buscar cero o más caracteres, y `_` para buscar un solo carácter.

`types`

  Si `table_type` no es un string vacío, debe contener una lista de valores, separados por comas, que representan los tipos buscados. Cada valor puede estar entre comillas simples (`'`), o sin comillas. Por ejemplo, `'TABLE','VIEW'` o `TABLE, VIEW`. Si la fuente de datos no soporta un tipo de tabla dado, odbc_tables() no devolverá ningún resultado para ese tipo.

### Valores devueltos

Devuelve un objeto de resultado ODBC que contiene las informaciones o `false` si ocurre un error.

El conjunto de resultados contiene las siguientes columnas:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `TABLE_TYPE`
- `REMARKS`

Los controladores pueden indicar columnas adicionales.

El conjunto de resultados está ordenado por `TABLE_TYPE`, `TABLE_CAT`, `TABLE_SCHEM` y `TABLE_NAME`.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `odbc` ahora espera una instancia de Odbc\Connection; anteriormente, se esperaba un resource.
8.4.0 | Esta función ahora devuelve una instancia de Odbc\Result; anteriormente, se devolvía un resource.
8.0.0 | `schema`, `table` y `types` ahora son anulables.

### Ejemplos

Ejemplo #1 Lista las Tablas en un Catálogo

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $tables = odbc_tables($conn, 'SalesOrders', 'dbo', '%', 'TABLE');
    while (($row = odbc_fetch_array($tables))) {
        print_r($row);
        break; // filas adicionales omitidas por brevedad
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [TABLE_CAT] => SalesOrders
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => Orders
        [TABLE_TYPE] => TABLE
        [REMARKS] =>
    )

### Ver también

- odbc_tableprivileges() - Lista las tablas y sus privilegios
- odbc_columns() - Lista las columnas de una tabla
- odbc_specialcolumns() - Devuelve el conjunto óptimo de columnas
- odbc_statistics() - Cálculo de estadísticas sobre una tabla
- odbc_procedures() - Lista los procedimientos almacenados

## Tabla de contenidos

- odbc_autocommit — Activa el modo de autovalidación
- odbc_binmode — Modifica la gestión de columnas de datos binarios
- odbc_close — Cierra una conexión ODBC
- odbc_close_all — Cierra todas las conexiones ODBC
- odbc_columnprivileges — Lista las columnas y sus derechos asociados
- odbc_columns — Lista las columnas de una tabla
- odbc_commit — Valida una transacción ODBC
- odbc_connect — Conectar a una fuente de datos
- odbc_connection_string_is_quoted — Determina si un valor de string de conexión ODBC está entre comillas
- odbc_connection_string_quote — Pone entre comillas un valor de string de conexión ODBC
- odbc_connection_string_should_quote — Determina si un valor de string de conexión ODBC debe ser puesto entre comillas
- odbc_cursor — Lee el nombre del puntero de resultado actual
- odbc_data_source — Devuelve información sobre los DSNs disponibles
- odbc_do — Alias de odbc_exec
- odbc_error — Lee el último código de error
- odbc_errormsg — Lee el último mensaje de error
- odbc_exec — Ejecuta directamente una consulta SQL
- odbc_execute — Ejecuta una consulta SQL preparada
- odbc_fetch_array — Lee una línea de resultado en un array asociativo
- odbc_fetch_into — Lee una línea de resultado y la coloca en un array
- odbc_fetch_object — Lee una línea de resultado en un objeto
- odbc_fetch_row — Lee una línea de resultado
- odbc_field_len — Lee la longitud de un campo
- odbc_field_name — Lee el nombre de la columna
- odbc_field_num — Número de columna
- odbc_field_precision — Alias de odbc_field_len
- odbc_field_scale — Lee la escala de un campo
- odbc_field_type — Tipo de datos de un campo
- odbc_foreignkeys — Lista las claves foráneas
- odbc_free_result — Libera los objetos asociados a un resultado
- odbc_gettypeinfo — Lista los tipos de datos soportados por un origen
- odbc_longreadlen — Gestión de columnas de tipo LONG
- odbc_next_result — Verifica si hay múltiples resultados disponibles
- odbc_num_fields — Número de columnas en un resultado
- odbc_num_rows — Número de filas en un resultado
- odbc_pconnect — Abre una conexión de base de datos persistente
- odbc_prepare — Prepara una orden para su ejecución
- odbc_primarykeys — Lista las columnas utilizadas en una clave primaria
- odbc_procedurecolumns — Lista los parámetros de los procedimientos
- odbc_procedures — Lista los procedimientos almacenados
- odbc_result — Lee un campo de resultado UODBC
- odbc_result_all — Muestra el resultado en forma de tabla HTML
- odbc_rollback — Anula una transacción
- odbc_setoption — Modifica los parámetros ODBC
- odbc_specialcolumns — Devuelve el conjunto óptimo de columnas
- odbc_statistics — Cálculo de estadísticas sobre una tabla
- odbc_tableprivileges — Lista las tablas y sus privilegios
- odbc_tables — Lista las tablas de una fuente

# La clase Odbc\Connection

(PHP 8 >= 8.4.0)

## Introducción

Una clase completamente opaca que reemplaza el resource `odbc_connection` a partir de PHP 8.4.0.

## Sinopsis de la Clase

namespace Odbc;
class Connection {
}

# La clase Odbc\Result

(PHP 8 >= 8.4.0)

## Introducción

Una clase completamente opaca que reemplaza el resource `odbc_result` a partir de PHP 8.4.0.

## Sinopsis de la Clase

namespace Odbc;
class Result {
}

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
  - Tipos de recursos
- Constantes predefinidas
- Funciones ODBC
  - odbc_autocommit — Activa el modo de autovalidación
  - odbc_binmode — Modifica la gestión de columnas de datos binarios
  - odbc_close — Cierra una conexión ODBC
  - odbc_close_all — Cierra todas las conexiones ODBC
  - odbc_columnprivileges — Lista las columnas y sus derechos asociados
  - odbc_columns — Lista las columnas de una tabla
  - odbc_commit — Valida una transacción ODBC
  - odbc_connect — Conectar a una fuente de datos
  - odbc_connection_string_is_quoted — Determina si un valor de string de conexión ODBC está entre comillas
  - odbc_connection_string_quote — Pone entre comillas un valor de string de conexión ODBC
  - odbc_connection_string_should_quote — Determina si un valor de string de conexión ODBC debe ser puesto entre comillas
  - odbc_cursor — Lee el nombre del puntero de resultado actual
  - odbc_data_source — Devuelve información sobre los DSNs disponibles
  - odbc_do — Alias de odbc_exec
  - odbc_error — Lee el último código de error
  - odbc_errormsg — Lee el último mensaje de error
  - odbc_exec — Ejecuta directamente una consulta SQL
  - odbc_execute — Ejecuta una consulta SQL preparada
  - odbc_fetch_array — Lee una línea de resultado en un array asociativo
  - odbc_fetch_into — Lee una línea de resultado y la coloca en un array
  - odbc_fetch_object — Lee una línea de resultado en un objeto
  - odbc_fetch_row — Lee una línea de resultado
  - odbc_field_len — Lee la longitud de un campo
  - odbc_field_name — Lee el nombre de la columna
  - odbc_field_num — Número de columna
  - odbc_field_precision — Alias de odbc_field_len
  - odbc_field_scale — Lee la escala de un campo
  - odbc_field_type — Tipo de datos de un campo
  - odbc_foreignkeys — Lista las claves foráneas
  - odbc_free_result — Libera los objetos asociados a un resultado
  - odbc_gettypeinfo — Lista los tipos de datos soportados por un origen
  - odbc_longreadlen — Gestión de columnas de tipo LONG
  - odbc_next_result — Verifica si hay múltiples resultados disponibles
  - odbc_num_fields — Número de columnas en un resultado
  - odbc_num_rows — Número de filas en un resultado
  - odbc_pconnect — Abre una conexión de base de datos persistente
  - odbc_prepare — Prepara una orden para su ejecución
  - odbc_primarykeys — Lista las columnas utilizadas en una clave primaria
  - odbc_procedurecolumns — Lista los parámetros de los procedimientos
  - odbc_procedures — Lista los procedimientos almacenados
  - odbc_result — Lee un campo de resultado UODBC
  - odbc_result_all — Muestra el resultado en forma de tabla HTML
  - odbc_rollback — Anula una transacción
  - odbc_setoption — Modifica los parámetros ODBC
  - odbc_specialcolumns — Devuelve el conjunto óptimo de columnas
  - odbc_statistics — Cálculo de estadísticas sobre una tabla
  - odbc_tableprivileges — Lista las tablas y sus privilegios
  - odbc_tables — Lista las tablas de una fuente
- Odbc\Connection — La clase Odbc\Connection
- Odbc\Result — La clase Odbc\Result

# PHP Data Objects

# Introducción

La extensión `PHP Data Objects` (PDO) define una excelente interfaz para acceder a una base de datos desde PHP. Cada controlador de base de datos implementado en la interfaz PDO puede utilizar funcionalidades específicas de cada una de las bases de datos mediante extensiones de funciones. Tenga en cuenta que no se puede ejecutar ninguna función de base de datos utilizando la extensión PDO por sí misma; debe utilizarse un controlador PDO específico de la base de datos para acceder al servidor de base de datos.

PDO proporciona una interfaz de abstracción al acceso a datos, lo que significa que se utilizan las mismas funciones para ejecutar consultas o recuperar los datos independientemente de la base de datos utilizada. PDO no proporciona ninguna abstracción de base de datos : no reescribe el SQL, ni emula funcionalidades ausentes. Debería utilizarse una interfaz de abstracción completa si se necesita esto.

PDO se proporciona con PHP.

# Instalación/Configuración

## Tabla de contenidos

- Instalación
- Configuración en tiempo de ejecución

## Instalación

Esta extensión está activada por omisión. Puede ser desactivada utilizando la opción de configuración: --disable-pdo

Instalar PDO en sistemas Unix

1. PDO y el controlador PDO_SQLITE están activados por defecto. Se debe activar el controlador PDO de la base de datos de su elección; consulte la documentación para los controladores específicos de su base de datos para obtener más información.

   > Nota:

   > Tenga en cuenta que al compilar PDO como extensión compartida (no recomendado), entonces todos los controladores PDO deben ser cargados después de cargar PDO.

2. Al instalar PDO como módulo compartido, el archivo php.ini debe ser actualizado para cargar la extensión PDO automáticamente cuando PHP se inicie. Asimismo, se deben activar los controladores específicos de su base de datos; asegúrese de que estos controladores estén listados después de la línea extension=pdo, ya que PDO debe ser inicializado antes de cargar las extensiones específicas de las bases de datos. Si compila PDO y las extensiones relativas a las bases de datos de forma estática, puede omitir este paso.

       extension=pdo

Usuarios de Windows

1. PDO está activado por defecto. Seleccione los otros archivos DLL específicos de su base de datos y utilice la función dl() para cargarlos en tiempo de ejecución o actívelos en el archivo php.ini. Por ejemplo, esto carga el controlador PDO_SQLITE pero deja el controlador PDO_ODBC comentado:

       ;extension=pdo_odbc
       extension=pdo_sqlite

   Estas librerías DLL deben existir en el directorio del sistema extension_dir.

> Nota:

> Tenga en cuenta que después de modificar su php.ini, debe reiniciar PHP para que las nuevas directivas de configuración tengan efecto.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración de PDO
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
pdo.dsn.* |  | php.ini sólo |

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`pdo.dsn.*` string

  Define un alias DSN. Véase PDO::__construct() para una explicación completa.

# Constantes predefinidas

## Tabla de contenidos

- Modos de recuperación

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

## Modos de recuperación

Véase constantes de cursor para las constantes de cursor `PDO::FETCH_ORI_*`.

## Modos básicos de recuperación

Modo de recuperación | Resumen
--- | ---
`PDO::FETCH_DEFAULT` | Valor especial para usar el modo de recuperación por omisión actual.
`PDO::FETCH_ASSOC` | Array indexado solo por el nombre de la columna.
`PDO::FETCH_BOTH` (por defecto) | Array indexado tanto por el número de columna como por el nombre.
`PDO::FETCH_NAMED` | Variante de `PDO::FETCH_ASSOC` que conserva las columnas duplicadas.
`PDO::FETCH_NUM` | Array indexado solo por el número de columna.
`PDO::FETCH_COLUMN` | Una sola columna.
`PDO::FETCH_KEY_PAIR` | Pares clave-valor, indexados por la primera columna.
`PDO::FETCH_FUNC` | Una una función para crear el valor de retorno. (solamente con PDOStatement::fetchAll())
`PDO::FETCH_OBJ` | Objeto anónimo (stdClass).
`PDO::FETCH_CLASS` | Un objeto de la clase especificada.

## Opciones de PDO::FETCH_CLASS

Estos modos se utilizan para implementar opciones al usar `PDO::FETCH_CLASS`.

Modo de recuperación | Resumen
--- | ---
`PDO::FETCH_CLASSTYPE` | Usa la primera columna como nombre de la clase.
`PDO::FETCH_PROPS_LATE` | Llama al constructor antes de establecer las propiedades.
`PDO::FETCH_SERIALIZE` | Usa datos serializados de PHP. Obsoleto a partir de PHP 8.1.0.

## Modos de resultado único

Los siguientes modos no pueden ser utilizados con PDOStatement::fetchAll().

Modo de recuperación | Resumen
--- | ---
`PDO::FETCH_BOUND` | Asigna valores a las variables especificadas.
`PDO::FETCH_INTO` | Actualiza un objeto existente.
`PDO::FETCH_LAZY` | Recuperación diferida mediante PDORow para acceso similar a arrays y objetos.

## Flags de comportamiento especiales para PDOStatement::fetchAll()

Los siguientes modos especiales para resultados múltiples solo funcionan con PDOStatement::fetchAll() y no funcionan con algunos otros modos de recuperación. Consulta la documentación completa para más detalles.

Modo de recuperación | Resumen
--- | ---
`PDO::FETCH_GROUP` | Los resultados se agrupan por la primera columna.
`PDO::FETCH_UNIQUE` | Los resultados se indexan (únicamente) por la primera columna.

## Manejo de nombres duplicados de columnas

Es posible que los resultados contengan varias columnas con el mismo nombre. Por ejemplo, al combinar dos tablas que contienen una columna con el mismo nombre.

Debido a que las estructuras de PHP, como los arrays y los objetos, no admiten varias claves o propiedades con el mismo nombre, el array o el objeto devuelto contendrá solo uno de los valores con el mismo nombre.

El valor que se devuelve para un nombre duplicado determinado debe considerarse indefinido.

Para evitar este problema, asigne nombres explícitos a las columnas mediante un alias. Por ejemplo:

    SELECT table1.created_at AS t1_created_at,
           table2.created_at AS t2_created_at
    FROM table1
    JOIN table2 ON table1.table2id = table2.id

Véase también `PDO::FETCH_NAMED`, `PDO::ATTR_FETCH_TABLE_NAMES` y `PDO::ATTR_FETCH_CATALOG_NAMES`.

## Estableciendo el modo de recuperación predeterminado

Es posible establecer el modo de recuperación predeterminado para todas las consultas usando `PDO::ATTR_DEFAULT_FETCH_MODE` con PDO::__construct() o PDO::setAttribute().

El modo de recuperación predeterminado para una sentencia específica se puede establecer usando PDOStatement::setFetchMode(). Esto afecta a la reutilización como sentencia preparada y a la iteración (usando `foreach`).

Precaución

PDOStatement::setAttribute() no se puede usar para establecer el modo de recuperación predeterminado. Solo acepta atributos específicos del controlador y, de forma silenciosa, ignora los atributos que no reconoce.

## PDO::FETCH_DEFAULT (int)

Disponible a partir de PHP 8.0.7.

Este es un valor especial que utiliza el modo de recuperación predeterminado actual para un PDOStatement. Es especialmente útil como valor predeterminado para los parámetros de método al extender PDOStatement para su uso con `PDO::ATTR_STATEMENT_CLASS`.

Este valor no se puede usar con `PDO::ATTR_DEFAULT_FETCH_MODE`.

## PDO::FETCH_ASSOC (int)

`PDO::FETCH_ASSOC` devuelve un array indexada únicamente por nombre de columna.

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_ASSOC);
    print_r($row);

El ejemplo anterior mostrará:

    Array
    (
        [userid] => 104
        [name] => Chris
        [country] => Ukraine
    )

## PDO::FETCH_BOTH (int)

Este es el modo de recuperación predeterminado.

`PDO::FETCH_BOTH` devuelve un array indexada tanto por número de columna como por nombre. Esto significa que cada valor devuelto se duplica para cada fila de resultados.

El número de columna comienza en 0 y se determina por el orden de las columnas de la consulta, no (por ejemplo) por el orden en que se definen las columnas en la tabla.

> Nota: No se recomienda utilizar el índice de columna numérico, ya que esto puede cambiar cuando se cambie la consulta, o cuando se cambie el esquema de la tabla al usar `SELECT *`.

> Nota: Es posible que el número de entradas indexadas por nombre no coincida con el número de entradas indexadas por número en los casos en que varias columnas devueltas utilicen el mismo nombre.

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_BOTH);
    print_r($row);

El ejemplo anterior mostrará:

    Array
    (
        [id] => 104,
        [0] => 104,
        [name] => Chris,
        [1] => Chris,
        [country] => Ukraine,
        [2] => Ukraine
    )

## PDO::FETCH_NAMED (int)

`PDO::FETCH_NAMED` devuelve resultados en el mismo formato que `PDO::FETCH_ASSOC` excepto que, cuando varias columnas usan el mismo nombre, todos los valores se devuelven como una lista.

Para obtener más información sobre el manejo de nombres de columnas duplicados y alternativas, consulte la sección manejo de nombres duplicados anterior.

El orden en el que se devuelven los valores duplicados debe considerarse indefinido. No hay forma de saber de dónde proviene cada valor.

    <?php
    $stmt = $pdo->query(
        "SELECT users.*, referrer.name
         FROM users
         LEFT JOIN users AS referrer ON users.referred_by = referrer.userid
         WHERE userid = 109"
    );
    $row = $stmt->fetch(\PDO::FETCH_NUM);
    print_r($row);

El ejemplo anterior mostrará:

    Array
    (
        [userid] => 109
        [name] => Array
            (
                [0] => Toni
                [1] => Chris
            )
        [country] => Germany
        [referred_by] = 104
    )

## PDO::FETCH_NUM (int)

`PDO::FETCH_NUM` devuelve un array indexada únicamente por número de columna. El número de columna comienza en 0 y se determina por el orden de las columnas de resultados en la consulta, no (por ejemplo) por el orden en que se definen las columnas en la tabla.

> Nota: No se recomienda utilizar el índice de columna numérico, ya que esto puede cambiar cuando se cambie la consulta, o cuando se cambie el esquema de la tabla al usar `SELECT *`.

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_NUM);
    print_r($row);

El ejemplo anterior mostrará:

    Array
    (
        [0] => 104
        [1] => Chris
        [2] => Ukraine
    )

## PDO::FETCH_COLUMN (int)

`PDO::FETCH_COLUMN` devuelve los valores de una sola columna. Utilice el segundo argumento de PDOStatement::setFetchMode() o PDOStatement::fetchAll() para especificar la columna que se devuelve.

Si la columna especificada no existe, se lanzará un ValueError.

    <?php
    $stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_COLUMN);
    print_r($row);

    $stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_COLUMN, 1);
    print_r($row);

El ejemplo anterior mostrará:

    Array
    (
        [0] => Chris
        [1] => Jamie
        [2] => Robin
    )

    Array
    (
        [0] => Ukraine
        [1] => England
        [2] => Germany
    )

## PDO::FETCH_KEY_PAIR (int)

`PDO::FETCH_KEY_PAIR` devuelve pares de valores, indexados por la primera columna. Los resultados deben contener solo dos columnas. Este modo de recuperación solo tiene sentido con PDOStatement::fetchAll().

> Nota: Si la primera columna no es única, se perderán valores. Qué valor(es) se perderán debe considerarse indefinido.

    <?php
    $stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_KEY_PAIR);
    print_r($row);

El ejemplo anterior mostrará:

    Array
    (
        [Chris] => Ukraine
        [Jamie] => England
        [Robin] => Germany
    )

## PDO::FETCH_FUNC (int)

Especifique una función para crear el valor devuelto. Este modo solo se puede usar con PDOStatement::fetchAll().

La función recibe los valores como parámetros. No es posible recuperar el nombre de la columna a la que estaba asociado un valor dado. Es crucial asegurarse de que el orden de las columnas en la consulta coincida con el orden de los parámetros de la función.

> Nota: Los efectos de `PDO::FETCH_GROUP` y `PDO::FETCH_UNIQUE` se aplican a los resultados antes de que se llame a la función.

    <?php
    function valueCreator($col1, $col2, $col3)
    {
        return [
            'col1' => $col1,
            'col2' => strtoupper($col2),
            'col3' => $col3,
            'customKey' => 'customValue',
        ];
    }

    $stmt = $pdo->query("SELECT userid, name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_FUNC, valueCreator(...));
    print_r($row);

El ejemplo anterior mostrará:

    Array
    (
        [0] => Array
            (
                [col1] => 104
                [col2] => SAM
                [col3] => Ukraine
                [customKey] => customValue
            )

        [1] => Array
            (
                [col1] => 105
                [col2] => JAMIE
                [col3] => England
                [customKey] => customValue
            )

        [2] => Array
            (
                [col1] => 107
                [col2] => ROBIN
                [col3] => Germany
                [customKey] => customValue
            )

    )

## PDO::FETCH_OBJ (int)

`PDO::FETCH_OBJ` devuelve un objeto stdClass.

Véase también PDOStatement::fetchObject() y `PDO::FETCH_CLASS`.

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_OBJ);
    print_r($row);

El ejemplo anterior mostrará:

    stdClass Object
    (
        [userid] => 104
        [name] => Chris
        [country] => Ukraine
    )

## PDO::FETCH_CLASS (int)

Devuelve un objeto de una clase específica. Para conocer comportamientos adicionales, consulte las opciones flags.

Si una propiedad no existe con el nombre de una columna devuelta, se declarará dinámicamente. Este comportamiento está obsoleto y provocará un error a partir de PHP 9.0.

Véase también PDOStatement::fetchObject().

    <?php
    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Constructor called with ". count(func_get_args()) ." args\n";
            print "Properties set when constructor called? "
                . (isset($this->name) ? 'Yes' : 'No') . "\n";
        }
    }

    $stmt = $db->query(
        "SELECT userid, name, country, referred_by_userid FROM users"
    );
    $stmt->setFetchMode(PDO::FETCH_CLASS, TestEntity::class);
    $result = $stmt->fetch();
    var_dump($result);

Resultado del ejemplo anterior es similar a:

    Constructor called with 0 args
    Properties set when constructor called? Yes
    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_CLASSTYPE (int)

Este modo de recuperación solo se puede usar combinado con `PDO::FETCH_CLASS` (y sus otras opciones).

Cuando se utiliza este modo de recuperación, PDO utilizará la primera columna devuelta como nombre de la clase que se devolverá.

Si no se encuentra la clase especificada, se devolverá un objeto stdClass, sin advertencia ni error.

    <?php
    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Constructor called with ". count(func_get_args()) ." args\n";
            print "Properties set when constructor called? "
                . (isset($this->name) ? 'Yes' : 'No') . "\n";
        }
    }

    $stmt = $db->query(
        "SELECT 'TestEntity', userid, name, country, referred_by_userid FROM users"
    );
    $stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE);
    $result = $stmt->fetch();
    var_dump($result);

Resultado del ejemplo anterior es similar a:

    Constructor called with 0 args
    Properties set when constructor called? Yes
    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_PROPS_LATE (int)

Este modo de recuperación solo se puede usar combinado con `PDO::FETCH_CLASS` (y sus otras opciones).

Cuando se utiliza este modo de recuperación, se llamará al constructor antes de que se establezcan las propiedades.

    <?php
    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Constructor called with ". count(func_get_args()) ." args\n";
            print "Properties set when constructor called? "
                . (isset($this->name) ? 'Yes' : 'No') . "\n";
        }
    }

    $stmt = $db->query(
        "SELECT userid, name, country, referred_by_userid FROM users"
    );
    $stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_PROPS_LATE, TestEntity::class);
    $result = $stmt->fetch();
    var_dump($result);

Resultado del ejemplo anterior es similar a:

    Constructor called with 0 args
    Properties set when constructor called? No
    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_SERIALIZE (int)

Advertencia

Esta característica está OBSOLETA a partir de PHP 8.0.0. Depender de esta característica está altamente desaconsejado.

Este modo de recuperación solo se puede usar combinado con `PDO::FETCH_CLASS` (y sus otras opciones).

Cuando se utiliza este modo de recuperación, la clase especificada debe ser Serializable.

Precaución

Esta función no admite un string que contenga un objeto serializado completo (con serialize()).

Precaución

Este modo de recuperación no llama al constructor.

    <?php
    class TestEntity implements Serializable
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Constructor llamado con " . count(func_get_args()) . " argumentos\n";
            print "¿Propiedades establecidas cuando se llama al constructor? "
                . (isset($this->name) ? 'Sí' : 'No') . "\n";
        }

        public function serialize()
        {
            return join(
                "|",
                [$this->userid, $this->name, $this->country, $this->referred_by_userid]
            );
        }

        public function unserialize(string $data)
        {
            $parts = explode("|", $data);
            $this->userid = (int) $parts[0];
            $this->name = $parts[1];
            $this->country = $parts[2];

            $refId = $parts[3];
            $this->referred_by_userid = ($refId === "" ? null : (int) $refId);
        }
    }

    print "Establecer registro (constructor llamado manualmente):\n";
    $db->exec(
        "CREATE TABLE serialize (
            sdata TEXT
        )"
    );

    $origObj = new TestEntity();
    $origObj->userid = 200;
    $origObj->name = 'Seri';
    $origObj->country = 'Syria';
    $origObj->referred_by_userid = null;

    $insert = $db->prepare("INSERT INTO serialize (sdata) VALUES (:sdata)");
    $insert->execute(['sdata' => $origObj->serialize()]);

    print "\nObtener resultados:\n";
    $query = "SELECT sdata FROM serialize";
    $stmt = $db->query($query);
    // NOTA: El constructor nunca se llama!
    $stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_SERIALIZE, TestEntity::class);
    $result = $stmt->fetch();
    var_dump($result);

Resultado del ejemplo anterior es similar a:

    Deprecated: TestEntity implements the Serializable interface, which is deprecated. Implement __serialize() and __unserialize() instead (or in addition, if support for old PHP versions is necessary) in Standard input code on line 2
    Establecer registro (constructor llamado manualmente):
    Constructor llamado con 0 argumentos
    ¿Propiedades establecidas cuando se llama al constructor? No

    Obtener resultados:
    Deprecated: PDOStatement::setFetchMode(): The PDO::FETCH_SERIALIZE mode is deprecated in Standard input code on line 58

    Deprecated: PDOStatement::fetch(): The PDO::FETCH_SERIALIZE mode is deprecated in Standard input code on line 59
    object(TestEntity)#5 (4) {
      ["userid"]=>
      int(200)
      ["name"]=>
      string(4) "Seri"
      ["country"]=>
      string(5) "Syria"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_BOUND (int)

Este modo de recuperación no se puede utilizar con PDOStatement::fetchAll().

Este modo de recuperación no devuelve directamente un resultado, sino que asigna valores a las variables especificadas con PDOStatement::bindColumn(). El método de recuperación llamado devuelve `true`.

> Nota: Cuando se utilizan sentencias preparadas, para que funcionen correctamente, las variables deben enlazarse después de que se ejecute la consulta.

    <?php
    $query = "SELECT users.userid, users.name, users.country, referrer.name
        FROM users
        LEFT JOIN users AS referrer ON users.referred_by_userid = referrer.userid";
    $stmt = $db->prepare($query);
    $stmt->execute();

    $stmt->bindColumn('userid', $userId);
    $stmt->bindColumn('name', $name);
    $stmt->bindColumn('country', $country);
    // Se utiliza la posición de la columna para resolver nombres de columna duplicados.
    // Para evitar que esto falle si se modifica la consulta, se recomienda usar un alias SQL.
    // Por ejemplo: referrer.name AS referrer_name
    $stmt->bindColumn(4, $referrerName);

    while ($stmt->fetch(\PDO::FETCH_BOUND)) {
        print join("\t", [$userId, $name, $country, ($referrerName ?? 'NULL')]) . "\n";
    }

El ejemplo anterior mostrará:

    104	Chris	Ukraine	NULL
    105	Jamie	England	NULL
    107	Robin	Germany	Chris
    108	Sean	Ukraine	NULL
    109	Toni	Germany	NULL
    110	Toni	Germany	NULL

## PDO::FETCH_INTO (int)

Este modo de recuperación no se puede utilizar con PDOStatement::fetchAll().

Este modo de recuperación actualiza las propiedades del objeto especificado. El objeto se devuelve si la operación se realiza correctamente.

Si una propiedad no existe con el nombre de una columna devuelta, se declarará dinámicamente. Este comportamiento está obsoleto y provocará un error a partir de PHP 9.0.

Las propiedades deben ser `public` y no pueden ser `readonly`.

Precaución

No hay forma de cambiar el objeto que se va a actualizar sin usar PDOStatement::setFetchMode() entre la recuperación de cada registro.

    <?php

    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;
    }

    $obj = new TestEntity();

    $stmt = $db->query("SELECT userid, name, country, referred_by_userid FROM users");

    $stmt->setFetchMode(\PDO::FETCH_INTO, $obj);
    $result = $stmt->fetch();

    var_dump($result);

Resultado del ejemplo anterior es similar a:

    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_LAZY (int)

Este modo de recuperación no se puede utilizar con PDOStatement::fetchAll().

Este modo de obtención recuperación un objeto PDORow que proporciona acceso a los valores tanto como arrays como objetos (es decir, combina el comportamiento de `PDO::FETCH_BOTH` y `PDO::FETCH_OBJ`), recuperados de forma diferida.

Esto permite un acceso eficiente en memoria (en el lado de PHP) a los resultados sin almacenar en búfer en el servidor de la base de datos. El uso o no de almacenamiento en búfer del lado del cliente por parte de PDO depende del controlador específico de la base de datos que se utilice (y de su configuración).

Precaución

PDORow devolverá `NULL` sin mostrar ningún error ni advertencia al acceder a propiedades o claves no definidas. Esto puede dificultar la detección y depuración de errores como erratas o consultas que no devuelven los datos esperados.

Precaución

El objeto PDORow devuelto se actualiza cada vez que se recupera un resultado.

    <?php
    $stmt = $db->query("SELECT userid, name, country, referred_by_userid FROM users");
    $result = $stmt->fetch(\PDO::FETCH_LAZY);

    print "ID: ". $result[0] ."\n";
    print "Nombre: {$result->name}\n";
    print "País: " . $result['country'] ."\n";
    // Devuelve NULL. No se genera ninguna advertencia ni error.
    print "No existe: " . var_export($result->does_not_exist, true) . "\n";

    $differentResult = $stmt->fetch(\PDO::FETCH_LAZY);
    // El PDOrow recuperado previamente ahora apunta al resultado recién recuperado.
    print "ID: ". $result[0] ."\n";

El ejemplo anterior mostrará:

    ID: 104
    Nombre: Chris
    País: Ukraine
    No existe: NULL
    ID: 105

## PDO::FETCH_GROUP (int)

`PDO::FETCH_GROUP` devuelve listas de arrays asociativos, indexados por una columna (no única). Este modo de obtención solo funciona con PDOStatement::fetchAll().

Cuando se combina con `PDO::FETCH_UNIQUE`, ambos modos utilizarán la misma columna, lo que hace que la combinación de estos modos sea inútil.

Esta recuperación debe combinarse con una de `PDO::FETCH_ASSOC`, `PDO::FETCH_BOTH`, `PDO::FETCH_NAMED`, `PDO::FETCH_NUM`, `PDO::FETCH_COLUMN` o `PDO::FETCH_FUNC`.

Si no se proporciona ningún modo de recuperación de la lista anterior, se utilizará el modo de recuperación predeterminado actual para PDOStatement.

    <?php
    $stmt = $pdo->query("SELECT country, userid, name FROM users");
    $row = $stmt->fetchAll(\PDO::FETCH_GROUP | \PDO::FETCH_ASSOC);
    print_r($row);

El ejemplo anterior mostrará:

    Array
    (
        [Ukraine] => Array
            (
                [0] => Array
                    (
                        [userid] => 104
                        [name] => Chris
                    )

                [1] => Array
                    (
                        [userid] => 108
                        [name] => Sean
                    )

            )
        [England] => Array
            (
                [0] => Array
                    (
                        [userid] => 105
                        [name] => Jamie
                    )

            )

        [Germany] => Array
            (
                [0] => Array
                    (
                        [userid] => 107
                        [name] => Robin
                    )

                [1] => Array
                    (
                        [userid] => 109
                        [name] => Toni
                    )
            )
    )

En el ejemplo anterior, cabe señalar que la primera columna se omite del array en cada fila y solo está disponible como clave. Se puede incluir repitiendo la columna, como en el siguiente ejemplo:

    <?php
    $stmt = $pdo->query("SELECT country, userid, name, country FROM users");
    $row = $stmt->fetchAll(\PDO::FETCH_GROUP | \PDO::FETCH_ASSOC);
    print_r($row);

El ejemplo anterior mostrará:

    Array
    (
        [Ukraine] => Array
            (
                [0] => Array
                    (
                        [userid] => 104
                        [name] => Chris
                        [country] => Ukraine
                    )

                [1] => Array
                    (
                        [userid] => 108
                        [name] => Sean
                        [country] => Ukraine
                    )

            )
        [England] => Array
            (
                [0] => Array
                    (
                        [userid] => 105
                        [name] => Jamie
                        [country] => England
                    )

            )

        [Germany] => Array
            (
                [0] => Array
                    (
                        [userid] => 107
                        [name] => Robin
                        [country] => Germany
                    )

                [1] => Array
                    (
                        [userid] => 109
                        [name] => Toni
                        [country] => Germany
                    )
            )
    )

## PDO::FETCH_UNIQUE (int)

`PDO::FETCH_UNIQUE` utiliza la primera columna para indexar los registros, devolviendo un registro por cada valor de índice. Este modo de recuperación solo funciona con PDOStatement::fetchAll().

Cuando se combina con `PDO::FETCH_GROUP`, ambos modos utilizarán la misma columna, lo que hace que la combinación de estos modos sea inútil.

Esta recuperación debe combinarse con uno de `PDO::FETCH_ASSOC`, `PDO::FETCH_BOTH`, `PDO::FETCH_NAMED`, `PDO::FETCH_NUM`, `PDO::FETCH_COLUMN` o `PDO::FETCH_FUNC`.

Si no se proporciona ningún modo de recuperación de la lista anterior, se utilizará el modo de recuperación predeterminado actual para PDOStatement.

Cuando se utiliza con una columna que se sabe que es única (como el ID del registro), este modo proporciona la capacidad de devolver rápidamente resultados indexados por ese valor.

> Nota: Si la primera columna no es única, se perderán valores. Qué valor(es) se perderán se considera indefinido.

Precaución

Siempre que sea posible, se recomienda filtrar los registros mediante SQL. La base de datos utilizará índices para optimizar este proceso y devolver únicamente los registros necesarios. Seleccionar más registros de los necesarios puede aumentar significativamente el uso de memoria y el tiempo de consulta para conjuntos de resultados grandes.

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_UNIQUE | \PDO::FETCH_ASSOC);
    print_r($row);

El ejemplo anterior mostrará:

    Array
    (
        [104] => Array
            (
                [name] => Chris
                [country] => Ukraine
            )

        [105] => Array
            (
                [name] => Jamie
                [country] => England
            )

        [107] => Array
            (
                [name] => Robin
                [country] => Germany
            )

    )

En el ejemplo anterior, cabe señalar que la primera columna se omite del array en cada fila y solo está disponible como clave. Se puede incluir repitiendo la columna, como en el siguiente ejemplo:

    <?php
    $stmt = $pdo->query("SELECT userid, userid, name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_UNIQUE | \PDO::FETCH_ASSOC);
    print_r($row);

El ejemplo anterior mostrará:

    Array
    (
        [104] => Array
            (
                [userid] => 104
                [name] => Chris
                [country] => Ukraine
            )

        [105] => Array
            (
                [userid] => 105
                [name] => Jamie
                [country] => England
            )

        [107] => Array
            (
                [userid] => 107
                [name] => Robin
                [country] => Germany
            )

    )

## Cursores

Véase también `PDO::ATTR_CURSOR_NAME`.

`PDO::FETCH_ORI_NEXT` (int)
  Recupera la próxima línea de un conjunto de resultados. Válido solo para los cursores desplazables.
`PDO::FETCH_ORI_PRIOR` (int)
  Recupera la línea anterior de un conjunto de resultados. Válido solo para los cursores desplazables.
`PDO::FETCH_ORI_FIRST` (int)
  Recupera la primera línea de un conjunto de resultados. Válido solo para los cursores desplazables.
`PDO::FETCH_ORI_LAST` (int)
  Recupera la última línea de un conjunto de resultados. Válido solo para los cursores desplazables.
`PDO::FETCH_ORI_ABS` (int)
  Recupera la línea solicitada por un número de línea de un conjunto de resultados. Válido solo para los cursores desplazables.
`PDO::FETCH_ORI_REL` (int)
  Recupera la línea solicitada por una posición relativa a la posición actual del cursor de un conjunto de resultados. Válido solo para los cursores desplazables.
`PDO::CURSOR_FWDONLY` (int)
  Crea un objeto PDOStatement con un cursor solo de avance. Es la opción por defecto para el cursor, ya que es el patrón de acceso a datos más rápido y común en PHP.
`PDO::CURSOR_SCROLL` (int)
  Crea un objeto PDOStatement con un cursor desplazable. Pasar las constantes `PDO::FETCH_ORI_*` para controlar las líneas recuperadas del conjunto de resultados.

## Otras Constantes

`PDO::PARAM_BOOL` (int)
  Representa el tipo de datos booleano.
`PDO::PARAM_NULL` (int)
  Representa el tipo de datos NULL SQL.
`PDO::PARAM_INT` (int)
  Representa el tipo de datos INTEGER SQL.
`PDO::PARAM_STR` (int)
  Representa los tipos de datos CHAR, VARCHAR o los otros tipos de datos en forma de string SQL.
`PDO::PARAM_STR_NATL` (int)
  Indicador para designar un string que utiliza el juego de caracteres nacional. Disponible a partir de PHP 7.2.0
`PDO::PARAM_STR_CHAR` (int)
  Indicador para designar un string que utiliza el juego de caracteres normal. Disponible a partir de PHP 7.2.0
`PDO::PARAM_LOB` (int)
  Representa el tipo de datos "objeto grande" SQL.
`PDO::PARAM_STMT` (int)
  Representa un tipo de conjunto de resultados. Actualmente no es soportado por ningún controlador.
`PDO::PARAM_INPUT_OUTPUT` (int)
  Especifica que el argumento es un argumento INOUT para un procedimiento almacenado. Esta constante debe combinarse con el operador OR a nivel de bits con una de las constantes `PDO::PARAM_*`.
`PDO::ATTR_AUTOCOMMIT` (bool)
  Si el valor es `false`, PDO intenta desactivar la validación automática cuando la conexión comienza una transacción. A partir de PHP 8.4.0 esta constante es de tipo bool; anteriormente, era de tipo int.
`PDO::ATTR_PREFETCH` (int)
  Definir el tamaño de precarga permite equilibrar la velocidad con el uso de memoria de una aplicación. No todas las combinaciones bases de datos / controladores soportan la configuración del tamaño de precarga. Un mayor tamaño de precarga resulta en un mayor rendimiento a costa de un mayor uso de memoria.
`PDO::ATTR_TIMEOUT` (int)
  Define el valor de espera en segundos para las comunicaciones con la base de datos.
`PDO::ATTR_ERRMODE` (int)
  Ver la sección sobre los errores y la gestión de errores para más información sobre este atributo.
`PDO::ATTR_SERVER_VERSION` (int)
  Atributo de solo lectura; devuelve información sobre la versión de la base de datos a la que PDO está conectado.
`PDO::ATTR_CLIENT_VERSION` (int)
  Atributo de solo lectura; devuelve información sobre la versión de la biblioteca cliente utilizada por PDO.
`PDO::ATTR_SERVER_INFO` (int)
  Atributo de solo lectura; devuelve algunas meta-informaciones sobre el servidor de base de datos al que PDO está conectado.
`PDO::ATTR_CONNECTION_STATUS` (int)
`PDO::ATTR_CASE` (int)
  Fuerza los nombres de columna a un formato específico especificado por las constantes `PDO::CASE_*`.
`PDO::ATTR_CURSOR_NAME` (int)
  Recupera o define el nombre a utilizar para un cursor. Muy útil al utilizar cursores desplazables y actualizaciones posicionadas.
`PDO::ATTR_CURSOR` (int)
  Selecciona el tipo de cursor. PDO actualmente soporta `PDO::CURSOR_FWDONLY` o `PDO::CURSOR_SCROLL`. A menos que se necesiten cursores desplazables, se debe usar el modo de cursor `PDO::CURSOR_FWDONLY`.
`PDO::ATTR_DRIVER_NAME` (int)
  Devuelve el nombre del controlador.

  Ejemplo #1 Uso de `PDO::ATTR_DRIVER_NAME`

      <?php
      if ($db->getAttribute(PDO::ATTR_DRIVER_NAME) == 'mysql') {
         echo "Uso de mysql; hacer algo específico de mysql aquí\n";
      }
      ?>

`PDO::ATTR_ORACLE_NULLS` (int)
  Convierte las cadenas vacías en valores NULL SQL en los datos recuperados.
`PDO::ATTR_PERSISTENT` (int)
  Solicita una conexión persistente, en lugar de crear una nueva conexión. Ver las conexiones y el gestor de conexión para más información sobre este atributo.
`PDO::ATTR_STATEMENT_CLASS` (int)
  Define el nombre de la clase bajo la cual los datos son devueltos.
`PDO::ATTR_FETCH_CATALOG_NAMES` (int)
  Añade el contenido del catálogo de nombres en cada nombre de columna devuelto en el conjunto de resultados. El catálogo de nombres y los nombres de columnas están separados por un punto (.). El soporte de este atributo es a nivel de controlador; puede no estar disponible por el controlador en uso.
`PDO::ATTR_FETCH_TABLE_NAMES` (int)
  Añade el contenido de la tabla de nombres en cada nombre de columna devuelto en el conjunto de resultados. La tabla de nombres y los nombres de columnas están separados por un punto (.). El soporte de este atributo es a nivel de controlador; puede no estar disponible por el controlador en uso.
`PDO::ATTR_STRINGIFY_FETCHES` (int)
  Fuerza todas las valores recuperados (excepto `null`) a ser tratados como strings. Los valores `null` permanecen sin cambios, a menos que `PDO::ATTR_ORACLE_NULLS` esté definido en `PDO::NULL_TO_STRING`.
`PDO::ATTR_MAX_COLUMN_LEN` (int)
  Define la longitud máxima del nombre de columna.
`PDO::ATTR_DEFAULT_FETCH_MODE` (int)
`PDO::ATTR_EMULATE_PREPARES` (bool)
  Indica si se debe activar o desactivar la emulación de las sentencias preparadas. Algunos controladores no soportan las sentencias preparadas nativas o solo tienen un soporte limitado de ellas. Cuando se define a `true`, PDO siempre emula las sentencias preparadas; cuando se define a `false`, utiliza las sentencias preparadas nativas del controlador. A partir de PHP 8.4.0 esta constante es de tipo bool; anteriormente, era de tipo int.
`PDO::ATTR_DEFAULT_STR_PARAM` (int)
  Define el tipo de argumento de string por defecto, esto puede ser `PDO::PARAM_STR_NATL` o `PDO::PARAM_STR_CHAR`. Disponible a partir de PHP 7.2.0
`PDO::ERRMODE_SILENT` (int)
  No envía error ni excepción si ocurre un error. El desarrollador debe verificar explícitamente los errores. Antes de PHP 8.0.0, este era el modo predeterminado. Ver los errores y la gestión de errores para más información sobre este atributo.
`PDO::ERRMODE_WARNING` (int)
  Envía un error de nivel `E_WARNING` si ocurre un error. Ver los errores y la gestión de errores para más información sobre este atributo.
`PDO::ERRMODE_EXCEPTION` (int)
  Lanza una excepción PDOException si ocurre un error. Ver los errores y la gestión de errores para más información sobre este atributo.
`PDO::CASE_NATURAL` (int)
  Deja los nombres de columnas como se devuelven por el controlador de base de datos.
`PDO::CASE_LOWER` (int)
  Fuerza los nombres de columnas en minúsculas.
`PDO::CASE_UPPER` (int)
  Fuerza los nombres de columnas en mayúsculas.
`PDO::NULL_NATURAL` (int)
`PDO::NULL_EMPTY_STRING` (int)
`PDO::NULL_TO_STRING` (int)
`PDO::ERR_NONE` (string)
  Corresponde a SQLSTATE `'00000'`, lo que significa que la consulta SQL ha tenido éxito sin error ni advertencia. Esta constante es útil para ayudar al verificar PDO::errorCode() o PDOStatement::errorCode() para determinar si ha ocurrido un error. Esto suele conocerse examinando el código de retorno del método que generó la condición de error de todos modos.
`PDO::PARAM_EVT_ALLOC` (int)
  Asigna un evento
`PDO::PARAM_EVT_FREE` (int)
  Elimina un evento
`PDO::PARAM_EVT_EXEC_PRE` (int)
  Evento desencadenado antes de la ejecución de una sentencia preparada.
`PDO::PARAM_EVT_EXEC_POST` (int)
  Evento desencadenado tras la ejecución de una sentencia preparada.
`PDO::PARAM_EVT_FETCH_PRE` (int)
  Evento desencadenado antes de recuperar un resultado de un conjunto de resultados.
`PDO::PARAM_EVT_FETCH_POST` (int)
  Evento desencadenado tras recuperar un resultado de un conjunto de resultados.
`PDO::PARAM_EVT_NORMALIZE` (int)
  Evento activado durante el registro de parámetros vinculados permitiendo al controlador normalizar el nombre del parámetro.
`PDO::SQLITE_DETERMINISTIC` (int)
  Especifica que una función creada con PDO::PDO::sqliteCreateFunction() es determinista, es decir, siempre devuelve el mismo resultado por las mismas entradas en una sola instrucción SQL. (Disponible a partir de PHP 7.1.4.)

# Conexiones y gestor de conexión

Las conexiones se establecen creando instancias de la clase base de PDO. No importa qué controlador se desee utilizar; siempre se utiliza el nombre de la clase PDO. El constructor acepta argumentos para especificar la fuente de la base de datos (conocida como DSN) y opcionalmente, el nombre de usuario y la contraseña (si los hay).

Ejemplo #1 Conexión a MySQL

    <?php
    $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
    ?>

Si existen errores de conexión, se lanza un objeto `PDOException`. Este error puede ser capturado si se desea gestionar la excepción, o bien puede ser tratado por el gestor global de excepciones definido mediante la función set_exception_handler().

Ejemplo #2 Gestión de errores de conexión

    <?php
    try {
        $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
    } catch (PDOException $e) {
        // intentar reintentar la conexión después de un cierto tiempo, por ejemplo
    }

Advertencia

Al igual que todas las demás excepciones, PDOException puede ser capturada ya sea explícitamente, mediante una instrucción `catch`, o implícitamente a través de set_exception_handler(). De lo contrario, se producirá el comportamiento por defecto de convertir una excepción no capturada en una `E_FATAL_ERROR`. El error fatal contendrá un backtrace que podría revelar detalles sobre la conexión. Por lo tanto, la opción php.ini `display_errors` debe estar configurada a `0` en un servidor de producción.

Cuando la conexión a la base de datos tiene éxito, se devuelve una instancia de la clase PDO al script. La conexión permanece activa mientras el objeto PDO lo esté. Para cerrar la conexión, se debe destruir el objeto asegurándose de que todas sus referencias sean eliminadas. Esto puede hacerse asignando `null` a la variable que gestiona el objeto. Si no se hace explícitamente, PHP cerrará automáticamente la conexión cuando el script llegue al final.

> Nota: Si aún existen otras referencias a esta instancia PDO (por ejemplo, desde una instancia PDOStatement u otras variables que referencian la misma instancia PDO), estas también deben ser eliminadas (por ejemplo, asignando `null` a la variable que referencia el PDOStatement).

Ejemplo #3 Cierre de una conexión

    <?php
    $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
    // usar la conexión aquí
    $sth = $dbh->query('SELECT * FROM foo');

    // y ahora, cerrarla !
    $sth = null;
    $dbh = null;
    ?>

Muchas aplicaciones web utilizan conexiones persistentes a los servidores de base de datos. Las conexiones persistentes no se cierran al final del script, sino que se almacenan en caché y se reutilizan cuando otro script solicita una conexión utilizando los mismos parámetros. La caché de conexiones persistentes permite evitar establecer una nueva conexión cada vez que un script necesita acceder a una base de datos, lo que hace que la aplicación web sea más rápida.

Ejemplo #4 Conexiones persistentes

    <?php
    $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass, array(
        PDO::ATTR_PERSISTENT => true
    ));
    ?>

El valor de la opción `PDO::ATTR_PERSISTENT` se convierte en bool (activar/desactivar conexiones persistentes), a menos que sea una string no numérica, en cuyo caso esto permite el uso de varios grupos de conexiones persistentes. Esto es útil si las conexiones diferentes utilizan parámetros incompatibles, por ejemplo, valores diferentes de `PDO::MYSQL_ATTR_USE_BUFFERED_QUERY`.

> Nota:

> Si se desea utilizar conexiones persistentes, se debe utilizar el valor `PDO::ATTR_PERSISTENT` en el array de opciones del controlador pasado al constructor PDO. Si se establece este atributo con el método PDO::setAttribute() después de la instanciación del objeto, el controlador no utilizará las conexiones persistentes.

Advertencia

PDO no realiza ninguna limpieza de las conexiones persistentes. Las tablas temporales, los bloqueos, las transacciones y otros cambios con estado pueden permanecer de usos anteriores de la conexión, causando problemas inesperados. Consulte la sección Conexiones persistentes a bases de datos para más información.

> Nota:

> Si se utiliza el controlador PDO ODBC y si su librería ODBC soporta el pool de conexiones ODBC (tanto unixODBC como Windows lo soportan; puede ser más), entonces se recomienda no utilizar las conexiones persistentes PDO, sino dejar que el pool de conexiones ODBC almacene en caché las conexiones. El pool de conexiones ODBC es compartido con otros módulos en el proceso; si PDO almacena en caché la conexión, entonces esta conexión nunca será devuelta por el pool de conexiones ODBC, lo que hace que se creen múltiples conexiones para otros módulos.

# Transacciones y validación automática (autocommit)

Ahora que se ha establecido la conexión mediante PDO, es necesario comprender cómo PDO gestiona las transacciones antes de ejecutar consultas. Si nunca se han utilizado transacciones, estas ofrecen 4 características principales: Atomicidad, Consistencia, Aislamiento y Durabilidad (ACID). En otras palabras, cualquier trabajo realizado en una transacción, incluso si se efectúa por etapas, está garantizado de aplicarse a la base de datos sin riesgo y sin interferencia para otras conexiones, cuando se valida. El trabajo de las transacciones también puede ser automáticamente anulado a solicitud, siempre que no se haya validado nada aún, lo que facilita considerablemente la gestión de errores en los scripts.

Las transacciones se implementan típicamente para aplicar todas las modificaciones de una sola vez; esto tiene el efecto de mejorar radicalmente la eficiencia de las actualizaciones. En otras palabras, las transacciones hacen que los scripts sean más rápidos y potencialmente más robustos (deben usarse correctamente para disfrutar de estos beneficios).

Desafortunadamente, no todas las bases de datos soportan transacciones, por lo que PDO debe ejecutarse en modo "autocommit" al abrir la conexión por primera vez. El modo "autocommit" significa que todas las consultas que se ejecutan tienen sus transacciones implícitas, si la base de datos las soporta, o ninguna transacción si la base de datos no las soporta. Si se necesita una transacción, debe usarse el método PDO::beginTransaction() para inicializarla. Si el controlador utilizado no soporta transacciones, se lanzará una excepción PDO (de acuerdo con el gestor de errores: esto siempre es un error grave). Una vez dentro de una transacción, debe usarse la función PDO::commit() o la función PDO::rollBack() para terminarla, según el éxito del código durante la transacción.

Advertencia

PDO solo verifica la posibilidad de usar transacciones al nivel del controlador. Si ciertas condiciones durante la ejecución impiden que las transacciones funcionen, PDO::beginTransaction() devolverá `true` sin error si el servidor acepta iniciar una transacción.

Un ejemplo sería usar transacciones en tablas con formato MyISAM del servidor de base de datos MySQL.

Advertencia

Commit implícito con declaraciones DDL: Algunas bases de datos emiten automáticamente un `COMMIT` implícito cuando se ejecuta una declaración de lenguaje de definición de base de datos (DDL), como `DROP TABLE` o `CREATE TABLE`, dentro de una transacción. Esto significa que todas las modificaciones anteriores realizadas en la misma transacción serán automáticamente validadas y no pueden ser anuladas.

`MySQL` y `Oracle` son ejemplos de bases de datos que presentan este comportamiento.

Ejemplo #1 Ejemplo de Commit implícito

    <?php
    $pdo->beginTransaction();
    $pdo->exec("INSERT INTO users (name) VALUES ('Rasmus')");
    $pdo->exec("CREATE TABLE test (id INT PRIMARY KEY)"); // Un COMMIT implícito ocurre aquí
    $pdo->rollBack(); // Esto NO anulará el INSERT/CREATE para MySQL o Oracle
    ?>

Mejor práctica: Evite ejecutar declaraciones DDL dentro de transacciones si se usan bases de datos que imponen este comportamiento. Si es necesario, separe las operaciones DDL de la lógica transaccional.

Cuando el script finaliza o cuando la conexión está a punto de cerrarse, si hay una transacción en curso, PDO la anulará automáticamente. Esta es una medida de seguridad para garantizar la integridad de los datos en caso de que el script finalice de manera inesperada. Si no se valida explícitamente la transacción, entonces se presume que algo salió mal y la anulación de la transacción ocurre para garantizar la seguridad de los datos.

Advertencia

La anulación automática ocurre si se inició la transacción mediante PDO::beginTransaction(). Si se ejecutó manualmente una consulta que comienza una transacción, PDO no tiene forma de saberlo y por lo tanto, no anulará automáticamente esa transacción si algo salió mal.

Ejemplo #2 Ejecución de un grupo en una transacción

En el siguiente ejemplo, supongamos que vamos a crear un conjunto de entradas para un nuevo empleado, cuyo número de ID será 23. Además de los datos básicos sobre esta persona, también se debe registrar su salario. Es muy simple realizar dos actualizaciones separadas, pero al encerrarlas en las llamadas a las funciones PDO::beginTransaction() y PDO::commit(), se garantiza que nadie pueda ver estas modificaciones hasta que estén completas. Si algo sale mal, el bloque de captura anulará todas las modificaciones realizadas desde el inicio de la transacción y mostrará un mensaje de error.

    <?php
    try {
      $dbh = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2',
          array(PDO::ATTR_PERSISTENT => true));
      echo "Conectado\n";
    } catch (Exception $e) {
      die("No se pudo conectar: " . $e->getMessage());
    }

    try {
      $dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

      $dbh->beginTransaction();
      $dbh->exec("insert into staff (id, first, last) values (23, 'Joe', 'Bloggs')");
      $dbh->exec("insert into salarychange (id, amount, changedate)
          values (23, 50000, NOW())");
      $dbh->commit();

    } catch (Exception $e) {
      $dbh->rollBack();
      echo "Falló: " . $e->getMessage();
    }
    ?>

No hay límite en el número de actualizaciones en una transacción; también pueden realizarse consultas complejas y, por supuesto, usar estas informaciones para construir otras actualizaciones y consultas; durante la actividad de la transacción, se está seguro de que nadie más puede realizar modificaciones mientras se está en medio de las propias modificaciones. Para más información sobre transacciones, consulte la documentación proporcionada por su base de datos.

# Consultas preparadas y procedimientos almacenados

La mayoría de las bases de datos soportan el concepto de consultas preparadas. ¿Qué son? Pueden verse como una especie de plantilla compilada para el SQL que se desea ejecutar, que puede ser personalizada utilizando variables como parámetros. Las consultas preparadas ofrecen dos funcionalidades esenciales:

- La consulta solo debe ser analizada (o preparada) una vez, pero puede ser ejecutada múltiples veces con parámetros idénticos o diferentes. Cuando la consulta es preparada, la base de datos analizará, compilará y optimizará su plan para ejecutar la consulta. Para consultas complejas, este proceso puede tomar bastante tiempo, lo que puede ralentizar las aplicaciones si se debe repetir la misma consulta múltiples veces con diferentes parámetros. Al utilizar consultas preparadas, se evita repetir el ciclo análisis/compilación/optimización. En resumen, las consultas preparadas utilizan menos recursos y se ejecutan más rápidamente.
- Los parámetros para preparar las consultas no necesitan estar entre comillas; el controlador gestiona esto. Si la aplicación utiliza exclusivamente consultas preparadas, se puede estar seguro de que no es posible ninguna inyección SQL (Sin embargo, si se construyen otras partes de la consulta basándose en entradas de usuario, se sigue asumiendo un riesgo).

Las consultas preparadas son tan prácticas que es la única funcionalidad que PDO emula para los controladores que no las soportan. Esto asegura poder utilizar la misma técnica para acceder a los datos, sin preocuparse por las capacidades de la base de datos.

Ejemplo #1 Inserciones repetitivas utilizando consultas preparadas

Este ejemplo realiza una consulta INSERT sustituyendo un `nombre` y un `valor` para los marcadores nombrados.

    <?php
    $stmt = $dbh->prepare("INSERT INTO REGISTRY (name, value) VALUES (:name, :value)");
    $stmt->bindParam(':name', $name);
    $stmt->bindParam(':value', $value);

    // inserción de una fila
    $name = 'one';
    $value = 1;
    $stmt->execute();

    // inserción de otra fila con valores diferentes
    $name = 'two';
    $value = 2;
    $stmt->execute();
    ?>

Ejemplo #2 Inserciones repetidas utilizando consultas preparadas

Este ejemplo realiza una consulta INSERT sustituyendo un `nombre` y un `valor` para los marcadores `?`.

    <?php
    $stmt = $dbh->prepare("INSERT INTO REGISTRY (name, value) VALUES (?, ?)");
    $stmt->bindParam(1, $name);
    $stmt->bindParam(2, $value);

    // inserción de una fila
    $name = 'one';
    $value = 1;
    $stmt->execute();

    // inserción de otra fila con diferentes valores
    $name = 'two';
    $value = 2;
    $stmt->execute();
    ?>

Ejemplo #3 Recuperación de datos utilizando consultas preparadas

Este ejemplo recupera datos basados en el valor de una clave proporcionada por un formulario. La entrada del usuario es automáticamente escapada, por lo que no hay riesgo de ataque por inyección SQL.

    <?php
    $stmt = $dbh->prepare("SELECT * FROM REGISTRY where name = ?");
    $stmt->execute([$_GET['name']]);
    foreach ($stmt as $row) {
      print_r($row);
    }
    ?>

Ejemplo #4 Llamada a un procedimiento almacenado con un parámetro de salida

Si el controlador de la base de datos lo soporta, también se pueden vincular parámetros tanto para entrada como para salida. Los parámetros de salida se utilizan típicamente para recuperar valores de un procedimiento almacenado. Los parámetros de salida son un poco más complejos de usar que los parámetros de entrada ya que se debe conocer la longitud que un parámetro dado podrá alcanzar cuando se vincule. Si el valor devuelto es más largo que el tamaño sugerido, se emitirá un error.

    <?php
    $stmt = $dbh->prepare("CALL sp_returns_string(?)");
    $stmt->bindParam(1, $return_value, PDO::PARAM_STR, 4000);

    // Llamada al procedimiento almacenado
    $stmt->execute();

    print "El procedimiento ha devuelto: $return_value\n";
    ?>

Ejemplo #5 Llamada a un procedimiento almacenado con un parámetro de entrada/salida

También se deben especificar los parámetros que gestionan valores tanto para entrada como para salida; la sintaxis es similar a los parámetros de salida. En el siguiente ejemplo, la cadena 'Hola' es pasada al procedimiento almacenado y cuando devuelve el valor, 'Hola' es reemplazada por el valor devuelto por el procedimiento.

    <?php
    $stmt = $dbh->prepare("CALL sp_takes_string_returns_string(?)");
    $value = 'hello';
    $stmt->bindParam(1, $value, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT, 4000);

    // llamada al procedimiento almacenado
    $stmt->execute();

    print "El procedimiento ha devuelto: $value\n";
    ?>

Ejemplo #6 Uso inválido de marcador

    <?php
    $stmt = $dbh->prepare("SELECT * FROM REGISTRY where name LIKE '%?%'");
    $stmt->execute([$_GET['name']]);

    // un marcador debe ser utilizado en lugar de un valor completo
    $stmt = $dbh->prepare("SELECT * FROM REGISTRY where name LIKE ?");
    $stmt->execute(["%$_GET[name]%"]);
    ?>

# Los errores y su gestión

PDO ofrece 3 formas diferentes de gestionar los errores para adaptarse mejor a la aplicación.

- `PDO::ERRMODE_SILENT`

  Anterior a PHP 8.0.0, este es el modo por omisión. PDO define simplemente el código de error para ser inspeccionado mediante los métodos PDO::errorCode() y PDO::errorInfo() en los objetos que representan las consultas, así como en los que representan las bases de datos; si el error resulta de una llamada al objeto que representa la consulta, se puede llamar al método PDOStatement::errorCode() o al método PDOStatement::errorInfo() en el objeto. Si el error resulta de una llamada al objeto que representa una base de datos, también se pueden llamar estos dos mismos métodos en el objeto.

- `PDO::ERRMODE_WARNING`

  Además de definir el código de error, PDO emitirá un mensaje E_WARNING tradicional. Esta configuración es útil durante las pruebas y el depurado, si se desea ver el problema sin interrumpir la aplicación.

- `PDO::ERRMODE_EXCEPTION`

  A partir de PHP 8.0.0, este es el modo por omisión. Además de definir el código de error, PDO lanzará una excepción PDOException y definirá las propiedades para representar el código de error y la información complementaria. Esta configuración es igualmente útil durante el depurado, ya que permitirá "saltar" el punto crítico del código, mostrando rápidamente el problema encontrado (recuerde: las transacciones son automáticamente revertidas si la excepción hace que el script termine).

  El modo "excepción" es también muy útil ya que permite estructurar el gestor de errores de forma más clara que con las alertas tradicionales de PHP y, además, con menos código que cuando se ejecuta el código en modo silencio, y se verifica sistemáticamente los valores devueltos después de cada llamada a la base de datos.

  Ver el capítulo sobre las excepciones para más información sobre las excepciones en PHP.

PDO utiliza los códigos de error SQL-92 SQLSTATE; cada controlador PDO es responsable de vincular sus códigos nativos a los códigos SQLSTATE apropiados. El método PDO::errorCode() devuelve un código SQLSTATE único. Si se necesitan información específica sobre el error, PDO también ofrece el método PDO::errorInfo() que devuelve un array conteniendo el código SQLSTATE, el código de error específico del controlador y la cadena describiendo el error proveniente del controlador.

Ejemplo #1 Creación de una instancia PDO y definición del modo de error

    <?php
    $dsn = 'mysql:dbname=testdb;host=127.0.0.1';
    $user = 'dbuser';
    $password = 'dbpass';

    $dbh = new PDO($dsn, $user, $password);
    $dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

    // Esto provocará una PDOException (cuando la tabla no existe).
    $dbh->query("SELECT wrongcolumn FROM wrongtable");
    ?>

El ejemplo anterior mostrará:

    Fatal error: Uncaught PDOException: SQLSTATE[42S02]: Base table or view not found: 1146 Table 'testdb.wrongtable' doesn't exist in /tmp/pdo_test.php:10
    Stack trace:
    #0 /tmp/pdo_test.php(10): PDO->query('SELECT wrongcol...')
    #1 {main}
      thrown in /tmp/pdo_test.php on line 10

> Nota:

> PDO::__construct() siempre lanza una excepción PDOException si la conexión falla, independientemente de la configuración de `PDO::ATTR_ERRMODE`.

Ejemplo #2 Crea una instancia PDO y define el modo de error desde el constructor

    <?php
    $dsn = 'mysql:dbname=test;host=127.0.0.1';
    $user = 'googleguy';
    $password = 'googleguy';

    $dbh = new PDO($dsn, $user, $password, array(PDO::ATTR_ERRMODE => PDO::ERRMODE_WARNING));

    // Esto hará que PDO lance un error de nivel E_WARNING en lugar de una excepción (cuando la tabla no existe)
    $dbh->query("SELECT wrongcolumn FROM wrongtable");
    ?>

El ejemplo anterior mostrará:

    Warning: PDO::query(): SQLSTATE[42S02]: Base table or view not found: 1146 Table 'test.wrongtable' doesn't exist in
    /tmp/pdo_test.php on line 9

# Los objetos grandes (LOB)

En algún momento de su aplicación, podría ser necesario almacenar grandes cantidades de datos en la base de datos. « Grande » significa típicamente datos de aproximadamente 4 ko o más, aunque algunas bases de datos pueden manejar más de 32 ko antes de que los datos se consideren « grandes ». Los objetos grandes pueden ser de naturaleza textual o binaria. PDO permite trabajar con este tipo de grandes datos utilizando el código tipo `PDO::PARAM_LOB` en las llamadas a las funciones PDOStatement::bindParam() o PDOStatement::bindColumn(). `PDO::PARAM_LOB` solicita a PDO que transforme los datos en un flujo que pueda ser manipulado utilizando la API PHP de flujos.

Ejemplo #1 Mostrar una imagen desde una base de datos

Este ejemplo vincula un LOB en una variable llamada $lob y lo envía al navegador utilizando la función fpassthru(). Dado que un LOB se representa como un flujo, las funciones como fgets(), fread() y stream_get_contents() pueden ser utilizadas en este flujo.

    <?php
    $db = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2');
    $stmt = $db->prepare("select contenttype, imagedata from images where id=?");
    $stmt->execute(array($_GET['id']));
    $stmt->bindColumn(1, $type, PDO::PARAM_STR, 256);
    $stmt->bindColumn(2, $lob, PDO::PARAM_LOB);
    $stmt->fetch(PDO::FETCH_BOUND);

    header("Content-Type: $type");
    fpassthru($lob);
    ?>

Ejemplo #2 Insertar una imagen en una base de datos

Este ejemplo abre un fichero y pasa el puntero de fichero a PDO para insertarlo como LOB. PDO hará lo posible por recuperar el contenido del fichero e insertarlo en la base de datos de la manera más eficiente posible.

    <?php
    $db = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2');
    $stmt = $db->prepare("insert into images (id, contenttype, imagedata) values (?, ?, ?)");
    $id = get_new_id(); // función para asignar un nuevo ID

    // asumamos que obtenemos un fichero desde un formulario
    // puede encontrar más detalles en la documentación de PHP

    $fp = fopen($_FILES['file']['tmp_name'], 'rb');

    $stmt->bindParam(1, $id);
    $stmt->bindParam(2, $_FILES['file']['type']);
    $stmt->bindParam(3, $fp, PDO::PARAM_LOB);

    $db->beginTransaction();
    $stmt->execute();
    $db->commit();
    ?>

Ejemplo #3 Insertar una imagen en una base de datos Oracle

Oracle requiere una sintaxis ligeramente diferente para insertar un LOB desde un fichero. Asimismo, es esencial realizar la inserción dentro de una transacción, de lo contrario, el nuevo LOB será insertado con una longitud de cero:

    <?php
    $db = new PDO('oci:', 'scott', 'tiger');
    $stmt = $db->prepare("insert into images (id, contenttype, imagedata) " .
    "VALUES (?, ?, EMPTY_BLOB()) RETURNING imagedata INTO ?");
    $id = get_new_id(); // función para asignar un nuevo ID

    // asumamos que obtenemos un fichero desde un formulario
    // puede encontrar más detalles en la documentación de PHP

    $fp = fopen($_FILES['file']['tmp_name'], 'rb');

    $stmt->bindParam(1, $id);
    $stmt->bindParam(2, $_FILES['file']['type']);
    $stmt->bindParam(3, $fp, PDO::PARAM_LOB);

    $db->beginTransaction();
    $stmt->execute();
    $db->commit();
    ?>

# La clase PDO

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

## Introducción

Representa una conexión entre PHP y un servidor de base de datos.

## Sinopsis de la Clase

class PDO {
/* Constantes */
public const int PARAM_NULL;
public const int PARAM_BOOL = 5;
public const int PARAM_INT = 1;
public const int PARAM_STR = 2;
public const int PARAM_LOB = 3;
public const int PARAM_STMT = 4;
public const int PARAM_INPUT_OUTPUT;
public const int PARAM_STR_NATL;
public const int PARAM_STR_CHAR;
public const int PARAM_EVT_ALLOC;
public const int PARAM_EVT_FREE;
public const int PARAM_EVT_EXEC_PRE;
public const int PARAM_EVT_EXEC_POST;
public const int PARAM_EVT_FETCH_PRE;
public const int PARAM_EVT_FETCH_POST;
public const int PARAM_EVT_NORMALIZE;
public const int FETCH_DEFAULT;
public const int FETCH_LAZY;
public const int FETCH_ASSOC;
public const int FETCH_NUM;
public const int FETCH_BOTH;
public const int FETCH_OBJ;
public const int FETCH_BOUND;
public const int FETCH_COLUMN;
public const int FETCH_CLASS;
public const int FETCH_INTO;
public const int FETCH_FUNC;
public const int FETCH_GROUP;
public const int FETCH_UNIQUE;
public const int FETCH_KEY_PAIR;
public const int FETCH_CLASSTYPE;
public const int FETCH_SERIALIZE;
public const int FETCH_PROPS_LATE;
public const int FETCH_NAMED;
public const int ATTR_AUTOCOMMIT;
public const int ATTR_PREFETCH;
public const int ATTR_TIMEOUT;
public const int ATTR_ERRMODE;
public const int ATTR_SERVER_VERSION;
public const int ATTR_CLIENT_VERSION;
public const int ATTR_SERVER_INFO;
public const int ATTR_CONNECTION_STATUS;
public const int ATTR_CASE;
public const int ATTR_CURSOR_NAME;
public const int ATTR_CURSOR;
public const int ATTR_ORACLE_NULLS;
public const int ATTR_PERSISTENT;
public const int ATTR_STATEMENT_CLASS;
public const int ATTR_FETCH_TABLE_NAMES;
public const int ATTR_FETCH_CATALOG_NAMES;
public const int ATTR_DRIVER_NAME;
public const int ATTR_STRINGIFY_FETCHES;
public const int ATTR_MAX_COLUMN_LEN;
public const int ATTR_EMULATE_PREPARES;
public const int ATTR_DEFAULT_FETCH_MODE;
public const int ATTR_DEFAULT_STR_PARAM;
public const int ERRMODE_SILENT;
public const int ERRMODE_WARNING;
public const int ERRMODE_EXCEPTION;
public const int CASE_NATURAL;
public const int CASE_LOWER;
public const int CASE_UPPER;
public const int NULL_NATURAL;
public const int NULL_EMPTY_STRING;
public const int NULL_TO_STRING;
public const string ERR_NONE;
public const int FETCH_ORI_NEXT;
public const int FETCH_ORI_PRIOR;
public const int FETCH_ORI_FIRST;
public const int FETCH_ORI_LAST;
public const int FETCH_ORI_ABS;
public const int FETCH_ORI_REL;
public const int CURSOR_FWDONLY;
public const int CURSOR_SCROLL;
/* Métodos */
public function __construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function beginTransaction(): bool
public function commit(): bool
public static function connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function errorCode(): ?string
public function errorInfo(): array
public function exec(string `$statement`): int|false
public function getAttribute(int `$attribute`): mixed
public static function getAvailableDrivers(): array
public function inTransaction(): bool
public function lastInsertId(?string `$name` = `null`): string|false
public function prepare(string `$query`, array `$options` = []): PDOStatement|false
public function query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function rollBack(): bool
public function setAttribute(int `$attribute`, mixed `$value`): bool
}

## Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Las constantes de clase ahora están tipadas.

# PDO::beginTransaction

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::beginTransaction — Inicia una transacción

### Descripción

public function PDO::beginTransaction(): bool

Desactiva el modo autocommit. Mientras el autocommit está desactivado, las modificaciones realizadas en la base de datos mediante las instancias de los objetos PDO no se aplican hasta que se finaliza la transacción llamando a la función PDO::commit(). La llamada a PDO::rollBack() anulará todas las modificaciones realizadas en la base de datos y restablecerá la conexión en modo autocommit.

Algunas bases de datos, incluyendo MySQL, ejecutarán automáticamente un COMMIT cuando se ejecute una consulta de definición de lenguaje de base de datos (DDL) como DROP TABLE o CREATE TABLE dentro de una transacción. Este COMMIT implícito impedirá anular otras modificaciones realizadas en esta transacción.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Se lanza la excepción PDOException si ya se ha iniciado una transacción o si el controlador no soporta transacciones.

> Nota: Una excepción será emitida incluso si el atributo `PDO::ATTR_ERRMODE` no vale `PDO::ERRMODE_EXCEPTION`.

### Ejemplos

Ejemplo #1 Anular una transacción

El siguiente ejemplo inicia una transacción y ejecuta dos consultas que modifican la base de datos antes de anular las modificaciones. En MySQL, sin embargo, la consulta DROP TABLE validará automáticamente la transacción, por lo que ninguna de las modificaciones de la transacción será anulada.

    <?php
    /* Inicia una transacción, desactivando el auto-commit */
    $dbh->beginTransaction();

    /* Modificación del esquema de la base de datos y de los datos */
    $sth = $dbh->exec("DROP TABLE fruit");
    $sth = $dbh->exec("UPDATE dessert
    SET name = 'hamburger'");

    /* Se detecta un error y se anulan las modificaciones */
    $dbh->rollBack();

    /* La conexión a la base de datos está ahora de vuelta en modo auto-commit */
    ?>

### Ver también

- PDO::commit() - Valida una transacción
- PDO::rollBack() - Anula una transacción
- Transacciones y auto-commit

# PDO::commit

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::commit — Valida una transacción

### Descripción

public function PDO::commit(): bool

Valida una transacción, restableciendo la conexión en modo autocommit hasta que se llame a la función PDO::beginTransaction() para iniciar una nueva transacción.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Se lanzará una excepción PDOException si no hay ninguna transacción activa.

> Nota: Una excepción será emitida incluso si el atributo `PDO::ATTR_ERRMODE` no vale `PDO::ERRMODE_EXCEPTION`.

### Ejemplos

Ejemplo #1 Valida una transacción básica

    <?php
    /* Inicia una transacción, desactivando el autocommit */
    $dbh->beginTransaction();

    /* Insertar múltiples registros en una base de todo-o-nada */
    $sql = 'INSERT INTO fruit
        (name, colour, calories)
        VALUES (?, ?, ?)';

    $sth = $dbh->prepare($sql);

    foreach ($fruits as $fruit) {
        $sth->execute(array(
            $fruit->name,
            $fruit->colour,
            $fruit->calories,
        ));
    }

    /* Validar los cambios */
    $dbh->commit();

    /* La conexión a la base de datos está ahora de vuelta en modo autocommit */
    ?>

Ejemplo #2 Confirmando una transacción DDL

    <?php
    /* Inicia una transacción, desactivando el autocommit */
    $dbh->beginTransaction();

    /* Modificación del esquema de la base de datos */
    $sth = $dbh->exec("DROP TABLE fruit");

    /* Validar los cambios */
    $dbh->commit();

    /* La conexión a la base de datos está ahora de vuelta en modo autocommit */
    ?>

> Nota: No todas las bases de datos permiten que las transacciones funcionen sobre declaraciones DDL: algunas generarán errores, mientras que otras (incluyendo MySQL) validarán automáticamente la transacción después de que la primera declaración DDL haya sido encontrada.

### Ver también

- PDO::beginTransaction() - Inicia una transacción
- PDO::rollBack() - Anula una transacción
- Transacciones y autocommit

# PDO::connect

(PHP 8 >= 8.4.0)

PDO::connect — Conecta a una base de datos y devuelve una subclase PDO para los controladores que lo soportan

### Descripción

public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static

Crea una instancia de una subclase de PDO para la base de datos a la que se conecta, si existe, de lo contrario devuelve una instancia genérica de PDO.

### Parámetros

`dsn`

  El Data Source Name, o DSN, que contiene las informaciones requeridas para conectarse a la base de datos.

  Generalmente, un DSN está compuesto por el nombre del controlador PDO, seguido de una sintaxis específica del controlador. Más detalles están disponibles en la documentación PDO de cada controlador.

  El parámetro `dsn` soporta tres métodos diferentes para especificar los argumentos necesarios para la creación de la base de datos:

  Invocación de controlador

    `dsn` contiene el DSN completo.

  Invocación URI

    `dsn` está compuesto por `uri:` seguido por una URI que define la localización del fichero que contiene la cadena DSN. La URI puede especificar un fichero local o remoto.

    `uri:file:///path/to/dsnfile`

  Alias

    `dsn` está compuesto por un nombre `name` que corresponde a `pdo.dsn.`name`` en el fichero php.ini, y que define la cadena DSN.

    > Nota:

    > El alias debe ser definido en el fichero php.ini, y no en un fichero .htaccess o httpd.conf

`username`

  El nombre de usuario para la cadena DSN. Este parámetro es opcional para algunos controladores PDO.

`password`

  La contraseña de la cadena DSN. Este parámetro es opcional para algunos controladores PDO.

`options`

  Un array clave=>valor con las opciones específicas de conexión.

### Valores devueltos

Devuelve una instancia de una subclase de PDO para el controlador PDO correspondiente si existe, o una instancia genérica de PDO.

### Errores/Excepciones

Se lanza una excepción PDOException si el intento de conexión a la base de datos solicitada falla, independientemente del `PDO::ATTR_ERRMODE` actualmente definido.

### Ver también

- Pdo\Dblib
- Pdo\Firebird
- Pdo\Mysql
- Pdo\Odbc
- Pdo\Pgsql
- Pdo\Sqlite
- PDO::__construct() - Crea una instancia PDO que representa una conexión a la base de datos

# PDO::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::__construct — Crea una instancia PDO que representa una conexión a la base de datos

### Descripción

public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)

Crea un objeto PDO que representa una conexión a la base de datos.

### Parámetros

`dsn`

  El Data Source Name, o DSN, que contiene las informaciones requeridas para conectarse a la base de datos.

  Generalmente, un DSN está compuesto por el nombre del controlador PDO, seguido de una sintaxis específica del controlador. Más detalles están disponibles en la documentación PDO de cada controlador.

  El parámetro `dsn` soporta tres métodos diferentes para especificar los argumentos necesarios para la creación de la base de datos:

  Invocación de controlador

    `dsn` contiene el DSN completo.

  Invocación URI

    `dsn` está compuesto por `uri:` seguido por una URI que define la localización del fichero que contiene la cadena DSN. La URI puede especificar un fichero local o remoto.

    `uri:file:///path/to/dsnfile`

  Alias

    `dsn` está compuesto por un nombre `name` que corresponde a `pdo.dsn.`name`` en el fichero php.ini, y que define la cadena DSN.

    > Nota:

    > El alias debe ser definido en el fichero php.ini, y no en un fichero .htaccess o httpd.conf

`username`

  El nombre de usuario para la cadena DSN. Este parámetro es opcional para algunos controladores PDO.

`password`

  La contraseña de la cadena DSN. Este parámetro es opcional para algunos controladores PDO.

`options`

  Un array clave=>valor con las opciones específicas de conexión.

### Errores/Excepciones

Se lanza una excepción PDOException si el intento de conexión a la base de datos solicitada falla, independientemente del `PDO::ATTR_ERRMODE` actualmente definido.

### Ejemplos

Ejemplo #1 Crea una instancia PDO mediante una invocación de controlador

    <?php

    $dsn = 'mysql:dbname=testdb;host=127.0.0.1';
    $user = 'dbuser';
    $password = 'dbpass';

    $dbh = new PDO($dsn, $user, $password);

    ?>

Ejemplo #2 Crea una instancia PDO mediante una invocación URI

El ejemplo siguiente supone que el fichero /usr/local/dbconnect existe con permisos de acceso que permiten a PHP acceder a él. El fichero contiene entonces el DSN de PDO, para conectarse a una base de datos DB2, con el controlador PDO_ODBC:

    odbc:DSN=SAMPLE;UID=john;PWD=mypass

El script PHP puede entonces crear una conexión a la base de datos, pasando en la URL el parámetro `uri:` y apuntando a la URI del fichero:

    <?php

    $dsn = 'uri:file:///usr/local/dbconnect';
    $user = '';
    $password = '';

    $dbh = new PDO($dsn, $user, $password);

    ?>

Ejemplo #3 Crea una instancia PDO con un alias

El ejemplo siguiente supone que el fichero php.ini contiene la directiva siguiente para activar una conexión a un servidor MySQL, con el alias `mydb`:

    [PDO]
    pdo.dsn.mydb="mysql:dbname=testdb;host=localhost"

    <?php

    $dsn = 'mydb';
    $user = '';
    $password = '';

    $dbh = new PDO($dsn, $user, $password);

    ?>

# PDO::errorCode

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::errorCode — Devuelve el SQLSTATE asociado con la última operación sobre la base de datos

### Descripción

public function PDO::errorCode(): ?string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un SQLSTATE, un identificador alfanumérico de cinco caracteres definido en el estándar ANSI SQL. Brevemente, un SQLSTATE consiste en un valor de clase de dos caracteres seguido por un valor de subclase de tres caracteres. Un valor de clase de 01 indica una alerta y es acompañado por un código de retorno SQL_SUCCESS_WITH_INFO. Los valores de clases distintos a '01', a excepción de la clase 'IM', indican un error. La clase 'IM' es específica para alertas y errores que provienen de la implementación misma de PDO (o quizás ODBC, si se utiliza el driver ODBC). El valor de subclase '000' en cualquier clase, indica que no hay subclase para este SQLSTATE.

PDO::errorCode() devuelve únicamente los códigos de error para operaciones ejecutadas directamente sobre el manejador de la base de datos. Si se crea un objeto PDOStatement con la función PDO::prepare() o la función PDO::query() y se invoca un error sobre el manejador de consulta, PDO::errorCode() no devolverá este error. Se debe llamar PDOStatement::errorCode() para devolver el código de error para una operación ejecutada sobre un manejador de consulta particular.

Devuelve `null` si ninguna operación ha sido ejecutada sobre la base de datos.

### Ejemplos

Ejemplo #1 Obtención de un código SQLSTATE

    <?php
    /* Provoca un error -- la tabla BONES no existe */
    $dbh->exec("INSERT INTO bones(skull) VALUES ('lucy')");

    echo "\nPDO::errorCode(): ", $dbh->errorCode();
    ?>

El ejemplo anterior mostrará:

    PDO::errorCode(): 42S02

### Ver también

- PDO::errorInfo() - Devuelve las informaciones asociadas al error durante la última operación sobre la base de datos
- PDOStatement::errorCode() - Recupera las informaciones sobre el error asociado durante la última operación sobre la consulta
- PDOStatement::errorInfo() - Recupera las informaciones sobre el error asociado durante la última operación sobre la consulta

# PDO::errorInfo

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::errorInfo — Devuelve las informaciones asociadas al error durante la última operación sobre la base de datos

### Descripción

public function PDO::errorInfo(): array

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

PDO::errorInfo() devuelve un array que contiene informaciones sobre el error ocurrido durante la última operación ejecutada por este manejador de base de datos. El array contiene los siguientes campos:

Elemento | Información
--- | ---
0 | Código de error SQLSTATE (un identificador alfanumérico de cinco caracteres definido en el estándar ANSI SQL).
1 | Código de error específico del driver.
2 | Mensaje de error específico del driver.

> Nota:

> Si el código de error SQLSTATE no está definido o si no hay un error específico del driver, el elemento siguiente al elemento 0 será definido a `null`.

PDO::errorInfo() devuelve únicamente las informaciones de los errores para las operaciones ejecutadas directamente sobre un manejador de base de datos. Si se crea un objeto PDOStatement con la función PDO::prepare() o la función PDO::query() y se invoca un error sobre el manejador de consulta, PDO::errorInfo() no devolverá el error desde el manejador de consulta. Se debe llamar a la función PDOStatement::errorInfo() para devolver las informaciones sobre el error para una operación ejecutada sobre un manejador de consulta particular.

### Ejemplos

Ejemplo #1 Muestra los campos de errores para una conexión PDO_ODBC sobre una base de datos DB2

    <?php
    /* Provoca un error -- sintaxis SQL incorrecta */
    $stmt = $dbh->prepare('sintaxis sql incorrecta');
    if (!$stmt) {
       echo "\nPDO::errorInfo():\n";
       print_r($dbh->errorInfo());
    }
    ?>

El ejemplo anterior mostrará:

    PDO::errorInfo():
    Array
    (
        [0] => 42S02
        [1] => -204
        [2] => [IBM][CLI Driver][DB2/LINUX] SQL0204N  "DANIELS.BONES" is an undefined name.  SQLSTATE=42704
    )

### Ver también

- PDO::errorCode() - Devuelve el SQLSTATE asociado con la última operación sobre la base de datos
- PDOStatement::errorCode() - Recupera las informaciones sobre el error asociado durante la última operación sobre la consulta
- PDOStatement::errorInfo() - Recupera las informaciones sobre el error asociado durante la última operación sobre la consulta

# PDO::exec

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::exec — Ejecuta una consulta SQL y devuelve el número de filas afectadas

### Descripción

public function PDO::exec(string `$statement`): int|false

PDO::exec() ejecuta una consulta SQL en una sola llamada de función, devuelve el número de filas afectadas por la consulta.

PDO::exec() no devuelve resultados para una consulta SELECT. Para una consulta SELECT que se necesite una sola vez en el programa, utilice en su lugar la función PDO::query(). Para una consulta que se necesite varias veces, prepare un objeto PDOStatement con la función PDO::prepare() y ejecute la consulta con la función PDOStatement::execute().

### Parámetros

`statement`

  La consulta a preparar y ejecutar.

  Los datos contenidos en la consulta deben ser properamente escapados.

### Valores devueltos

PDO::exec() devuelve el número de filas que han sido modificadas o eliminadas por la consulta SQL ejecutada. Si ninguna fila es afectada, la función PDO::exec() devolverá `0`.

Advertencia

Esta función puede retornar `false`, pero también puede retornar un valor equivalente a `false`. Por favor, lea la sección sobre los booleanos para más información. Utilice el operador === para probar el valor de retorno exacto de esta función.

El siguiente ejemplo se basa incorrectamente en el valor devuelto por PDO::exec(), donde una consulta que no afecta ninguna fila equivale a llamar a die():

    <?php
    $db->exec() or die(print_r($db->errorInfo(), true)); // incorrecto
    ?>

### Errores/Excepciones

Emite un error de nivel `E_WARNING` si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_WARNING`.

Lanza una excepción PDOException si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_EXCEPTION`.

### Ejemplos

Ejemplo #1 Ejecutar una consulta DELETE

Cuenta el número de filas eliminadas para una consulta DELETE con ninguna cláusula WHERE.

    <?php
    $dbh = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');

    /* Eliminación de todas las filas de la tabla FRUIT */
    $count = $dbh->exec("DELETE FROM fruit");

    /* Devuelve el número de filas eliminadas */
    print "Eliminación de $count filas.\n";
    ?>

El ejemplo anterior mostrará:

    Eliminación de 1 filas.

### Ver también

- PDO::prepare() - Prepara una consulta para su ejecución y devuelve un objeto
- PDO::query() - Prepara y ejecuta una consulta SQL sin marcadores de sustitución
- PDOStatement::execute() - Ejecuta una consulta preparada

# PDO::getAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDO::getAttribute — Recupera un atributo de una conexión a una base de datos

### Descripción

public function PDO::getAttribute(int `$attribute`): mixed

Esta función devuelve el valor de un atributo de una conexión a una base de datos. Para recuperar los atributos PDOStatement, consúltese la función PDOStatement::getAttribute().

Tenga en cuenta que algunas bases de datos/drivers combinados no soportan todos los atributos de conexión.

### Parámetros

`attribute`

  Una de las constantes `PDO::ATTR_*`. Los atributos genéricos que se aplican a las conexiones son los siguientes:

  - `PDO::ATTR_AUTOCOMMIT`
  - `PDO::ATTR_CASE`
  - `PDO::ATTR_CLIENT_VERSION`
  - `PDO::ATTR_CONNECTION_STATUS`
  - `PDO::ATTR_DRIVER_NAME`
  - `PDO::ATTR_ERRMODE`
  - `PDO::ATTR_ORACLE_NULLS`
  - `PDO::ATTR_PERSISTENT`
  - `PDO::ATTR_PREFETCH`
  - `PDO::ATTR_SERVER_INFO`
  - `PDO::ATTR_SERVER_VERSION`
  - `PDO::ATTR_TIMEOUT`
  Algunos controladores pueden hacer uso de atributos adicionales específicos del controlador. Tenga en cuenta que los atributos específicos del controlador no deben ser utilizados con otros controladores.

### Valores devueltos

Una llamada exitosa devuelve el valor del atributo PDO solicitado. Una llamada que ha fallado devuelve el valor `null`.

### Errores/Excepciones

El método PDO::getAttribute() puede generar una excepción PDOException cuando el controlador subyacente no soporta el `attribute` solicitado.

### Ejemplos

Ejemplo #1 Recuperación de los atributos de conexión a una base de datos

    <?php
    $conn = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');
    $attributes = array(
    "AUTOCOMMIT", "ERRMODE", "CASE", "CLIENT_VERSION", "CONNECTION_STATUS",
    "ORACLE_NULLS", "PERSISTENT", "PREFETCH", "SERVER_INFO", "SERVER_VERSION",
    "TIMEOUT"
    );

    foreach ($attributes as $val) {
       echo "PDO::ATTR_$val: ";
       echo $conn->getAttribute(constant("PDO::ATTR_$val")) . "\n";
    }
    ?>

### Ver también

- PDO::setAttribute() - Configura un atributo PDO
- PDOStatement::getAttribute() - Recupera un atributo de consulta
- PDOStatement::setAttribute() - Establece un atributo de consulta

# PDO::getAvailableDrivers

# pdo_drivers

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.3)

PDO::getAvailableDrivers -- pdo_drivers — Devuelve la lista de controladores PDO disponibles

### Descripción

public static function PDO::getAvailableDrivers(): array
function pdo_drivers(): array

Esta función devuelve la lista de todos los controladores PDO disponibles que pueden ser utilizados con el argumento `DSN` de la función PDO::__construct().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

PDO::getAvailableDrivers() devuelve un array de nombres de controladores. Si no hay controladores disponibles, devuelve un array vacío.

### Ejemplos

Ejemplo #1 Ejemplo con PDO::getAvailableDrivers()

    <?php
    print_r(PDO::getAvailableDrivers());
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => mysql
        [1] => sqlite
    )

# PDO::inTransaction

(PHP 5 >= 5.3.3, Bundled pdo_pgsql, PHP 7, PHP 8)

PDO::inTransaction — Verifica si se encuentra en una transacción

### Descripción

public function PDO::inTransaction(): bool

Verifica si una transacción está actualmente activa en el driver. Este método solo funciona para los drivers de bases de datos que soportan transacciones.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si una transacción está actualmente activa, `false` en caso contrario.

# PDO::lastInsertId

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::lastInsertId — Devuelve el identificador de la última fila insertada o el valor de una secuencia

### Descripción

public function PDO::lastInsertId(?string `$name` = `null`): string|false

Devuelve el identificador de la última fila insertada, o el último valor de una secuencia de objetos, dependiendo del driver utilizado. Por ejemplo, PDO_PGSQL permite especificar el nombre de cualquier objeto secuencia para el argumento `name`.

> Nota:

> Este método puede no devolver un resultado significativo según los drivers PDO utilizados, ya que la base de datos empleada puede no soportar la noción de campos auto-incrementados o de secuencias.

### Parámetros

`name`

  Nombre de la secuencia de objetos desde la cual debe devolverse el identificador.

### Valores devueltos

Si no se especifica un nombre de secuencia para el argumento `name`, PDO::lastInsertId() devuelve una cadena que representa el identificador de la última fila insertada en la base de datos.

Si se especifica un nombre de secuencia para el argumento `name`, PDO::lastInsertId() devuelve una cadena que representa el último valor de la secuencia de objetos especificada.

Si el driver PDO no soporta esta funcionalidad, PDO::lastInsertId() lanzará un SQLSTATE `IM001`.

### Errores/Excepciones

Emite un error de nivel `E_WARNING` si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_WARNING`.

Lanza una excepción PDOException si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_EXCEPTION`.

# PDO::prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PHP 8,PECL pdo >= 0.1.0)

PDO::prepare — Prepara una consulta para su ejecución y devuelve un objeto

### Descripción

public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false

Prepara una consulta SQL para ser ejecutada por el método PDOStatement::execute(). El modelo de declaración puede contener cero o más parámetros nombrados (:nombre) o marcadores (?) para los cuales los valores reales serán sustituidos cuando la consulta sea ejecutada. El uso tanto de parámetros nombrados como de marcadores es imposible en un modelo de declaración; solo uno u otro estilo de parámetro. Utilícese estos parámetros para ligar las entradas del usuario, no se incluyan directamente en la consulta.

Debe incluirse un marcador con un nombre único para cada valor que se desee pasar en la consulta al llamar a PDOStatement::execute(). No puede utilizarse un marcador con dos nombres idénticos en una consulta preparada, a menos que el modo de emulación esté activo.

> Nota:

> Los marcadores de parámetros pueden representar únicamente un literal de datos completo. Ni una parte de literal, ni una palabra clave, ni un identificador, ni cualquier otra consulta arbitraria pueden ser ligados utilizando los parámetros. Por ejemplo, no puede asociarse múltiples valores a un solo marcador de nombre entrante, en la cláusula IN() de una consulta SQL.

Llamar a PDO::prepare() y PDOStatement::execute() para las consultas que deben ser ejecutadas varias veces con diferentes valores de parámetros optimiza el rendimiento de la aplicación permitiendo al controlador negociar del lado del cliente y/o servidor con la caché de consultas y las meta-informaciones. Además, llamar a PDO::prepare() y PDOStatement::execute() ayuda a prevenir ataques por inyección SQL eliminando la necesidad de proteger los parámetros manualmente.

PDO emula las consultas preparadas / los parámetros ligados para los controladores que no los soportan nativamente, y puede también reescribir los parámetros nombrados o los marcadores en algo más apropiado, si el controlador soporta un estilo y no el otro.

> Nota: El analizador utilizado para las declaraciones preparadas emuladas y para reescribir los parámetros nombrados o del estilo de punto de interrogación soporta el escape backslash no estándar para las comillas simples y dobles. Esto significa que las comillas finales que son precedidas por un backslash no serán reconocidas como tales, lo que puede resultar en una mala detección de los parámetros causando que la declaración preparada falle al ser ejecutada. Un contorno es no utilizar las consultas emuladas para tales consultas SQL, y evitar reescribir los parámetros utilizando un estilo de parámetro que es soportado nativamente por el controlador.

A partir de PHP 7.4.0, los puntos de interrogación pueden ser escapados duplicándolos. Esto significa que la cadena `??` será traducida en `?` al enviar la consulta a la base de datos.

### Parámetros

`query`

  Debe ser un modelo de consulta SQL válido para el servidor de base de datos objetivo.

`options`

  Este array contiene una o más parejas clave=>valor para definir los valores de los atributos para el objeto PDOStatement que esta método devuelve. Puede utilizarse esto para definir el valor `PDO::ATTR_CURSOR` a `PDO::CURSOR_SCROLL` para solicitar un cursor desplazable. Algunos controladores tienen opciones específicas que pueden ser definidas en el momento de la preparación.

### Valores devueltos

Si el servidor de base de datos prepara con éxito esta consulta, PDO::prepare() devuelve un objeto PDOStatement. Si el servidor de base de datos no logra preparar la consulta, PDO::prepare() devuelve `false` o emite una excepción PDOException (siguiendo el gestor de errores).

> Nota:

> La emulación de consultas preparadas no comunica con el servidor de base de datos. También, la función PDO::prepare() no verifica la consulta.

### Errores/Excepciones

Emite un error de nivel `E_WARNING` si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_WARNING`.

Lanza una excepción PDOException si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_EXCEPTION`.

### Ejemplos

Ejemplo #1 Modelo de declaración SQL con parámetros nombrados

    <?php
    /* Ejecuta una consulta preparada pasando un array de valores */
    $sql = 'SELECT nombre, color, calorias
        FROM fruta
    WHERE calorias < :calorias AND color = :color';
    $sth = $dbh->prepare($sql, [PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY]);
    $sth->execute(['calorias' => 150, 'color' => 'red']);
    $red = $sth->fetchAll();
    /* Las claves del array pueden ser prefijadas con dos puntos ":" también (opcional) */
    $sth->execute([':calorias' => 175, ':color' => 'yellow']);
    $yellow = $sth->fetchAll();
    ?>

Ejemplo #2 Modelo de declaración SQL con marcadores

    <?php
    /* Ejecuta una consulta preparada pasando un array de valores */
    $sth = $dbh->prepare('SELECT nombre, color, calorias
        FROM fruta
        WHERE calorias < ? AND color = ?');
    $sth->execute([150, 'rojo']);
    $red = $sth->fetchAll();
    $sth->execute([175, 'amarillo']);
    $yellow = $sth->fetchAll();
    ?>

Ejemplo #3 Modelo de declaración SQL con un punto de interrogación escapado

    <?php
    /* nota: esto solo es válido para bases de datos PostgreSQL */
    $sth = $dbh->prepare('SELECT * FROM issues WHERE tag::jsonb ?? ?');
    $sth->execute(['feature']);
    $featureIssues = $sth->fetchAll();
    $sth->execute(['performance']);
    $performanceIssues = $sth->fetchAll();
    ?>

### Ver también

- PDO::exec() - Ejecuta una consulta SQL y devuelve el número de filas afectadas
- PDO::query() - Prepara y ejecuta una consulta SQL sin marcadores de sustitución
- PDOStatement::execute() - Ejecuta una consulta preparada

# PDO::query

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDO::query — Prepara y ejecuta una consulta SQL sin marcadores de sustitución

### Descripción

public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false

PDO::query() prepara y ejecuta una consulta SQL en una sola llamada de función, retornando la consulta como objeto PDOStatement.

Para una consulta que debe ejecutarse varias veces, se obtendrán mejores resultados si se prepara el objeto PDOStatement utilizando la función PDO::prepare() y se ejecuta la consulta mediante múltiples llamadas a la función PDOStatement::execute().

Si no se recuperan todos los datos del conjunto de resultados antes de ejecutar la siguiente llamada a PDO::query(), la llamada puede fallar. Llamar a PDOStatement::closeCursor() para liberar los recursos de la base de datos asociados al objeto PDOStatement antes de ejecutar la siguiente llamada a la función PDO::query().

> Nota:

> Si `query` contiene marcadores de sustitución, la consulta debe prepararse y ejecutarse por separado utilizando las funciones PDO::prepare() y PDOStatement::execute().

### Parámetros

`query`

  La consulta SQL a preparar y ejecutar.

  Si el SQL contiene marcadores de sustitución, PDO::prepare() y PDOStatement::execute() deben ser utilizados en su lugar. Alternativamente, el SQL puede ser preparado manualmente antes de llamar a PDO::query(), con los datos correctamente formateados utilizando PDO::quote() si el controlador lo soporta.

`fetchMode`

  El modo de recuperación por omisión para el PDOStatement retornado. Esto debe ser una de las constantes `PDO::FETCH_*`.

  Si este argumento es pasado a la función, el resto de los argumentos serán tratados como si PDOStatement::setFetchMode() hubiera sido llamado sobre el objeto de la consulta resultante. Los argumentos siguientes dependen del modo de recuperación seleccionado.

### Valores devueltos

Retorna un objeto PDOStatement o `false` si ocurre un error.

### Errores/Excepciones

Emite un error de nivel `E_WARNING` si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_WARNING`.

Lanza una excepción PDOException si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_EXCEPTION`.

### Ejemplos

Ejemplo #1 SQL sin marcadores de sustitución puede ser ejecutado utilizando PDO::query()

    <?php
    $sql =  'SELECT name, color, calories FROM fruit ORDER BY name';
    foreach  ($conn->query($sql) as $row) {
        print $row['name'] . "\t";
        print  $row['color'] . "\t";
        print $row['calories'] . "\n";
    }
    ?>

El ejemplo anterior mostrará:

    apple   red     150
    banana  yellow  250
    kiwi    brown   75
    lemon   yellow  25
    orange  orange  300
    pear    green   150
    watermelon      pink    90

### Ver también

- PDO::exec() - Ejecuta una consulta SQL y devuelve el número de filas afectadas
- PDO::prepare() - Prepara una consulta para su ejecución y devuelve un objeto
- PDOStatement::execute() - Ejecuta una consulta preparada

# PDO::quote

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.1)

PDO::quote — Protege una cadena para usarla en una consulta SQL PDO

### Descripción

public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false

PDO::quote() coloca comillas simples alrededor de una cadena de entrada y protege los caracteres especiales presentes en la cadena de entrada, utilizando el estilo de protección apropiado al controlador actual.

Si se utiliza esta función para construir consultas SQL, se recomienda encarecidamente usar PDO::prepare() para preparar las consultas SQL con parámetros vinculados en lugar de usar PDO::quote() para interpretar las entradas del usuario en la consulta SQL. Las consultas preparadas con parámetros vinculados no solo son más portables, flexibles y seguras, sino también más rápidas de ejecutar que interpretar las consultas, ya que los lados cliente y servidor pueden almacenar en caché una versión compilada de la consulta.

No todos los controladores PDO implementan este método (como PDO_ODBC). Utilice consultas preparadas en su lugar.

Precaución

# Seguridad: el juego de caracteres por defecto

El juego de caracteres debe ser definido ya sea a nivel del servidor, o durante la conexión a la base de datos (dependiendo del driver utilizado) para que afecte al método PDO::quote(). Ver la documentación específica del driver para más información.

### Parámetros

`string`

  La cadena a proteger.

`type`

  El tipo de datos para los drivers que tienen estilos particulares de protección. Proporciona una pista al tipo de dato para los controladores que tienen un estilo de escape diferente. Por ejemplo `PDO_PARAM_LOB` indica al controlador que escape datos binarios.

### Valores devueltos

Devuelve una cadena protegida, que es teóricamente segura para usar en una consulta SQL. Devuelve `false` si el controlador no soporta este tipo de protecciones.

### Ejemplos

Ejemplo #1 Protección de una cadena normal

    <?php
    $conn = new PDO('sqlite:/home/lynn/music.sql3');

    /* Cadena simple */
    $string = 'Nice';
    print "Cadena no escapada : $string\n";
    print "Cadena escapada : " . $conn->quote($string) . "\n";
    ?>

El ejemplo anterior mostrará:

    Cadena no escapada : Nice
    Cadena escapada: 'Nice'

Ejemplo #2 Protección de una cadena peligrosa

    <?php
    $conn = new PDO('sqlite:/home/lynn/music.sql3');

    /* Cadena peligrosa */
    $string = 'Cadena \' particular';
    print "Cadena no escapada : $string\n";
    print "Cadena escapada :" . $conn->quote($string) . "\n";
    ?>

El ejemplo anterior mostrará:

    Cadena no escapada : Cadena ' particular
    Cadena escapada : 'Cadena '' particular'

Ejemplo #3 Protección de una cadena compleja

    <?php
    $conn = new PDO('sqlite:/home/lynn/music.sql3');

    /* Cadena compleja */
    $string = "Co'mpl''exe \"ch'\"aîne";
    print "Cadena no escapada : $string\n";
    print "Cadena escapada : " . $conn->quote($string) . "\n";
    ?>

El ejemplo anterior mostrará:

    Cadena no escapada: Co'mpl''exe "ch'"aîne
    Cadena escapada: 'Co''mpl''''exe "ch''"aîne'

### Ver también

- PDO::prepare() - Prepara una consulta para su ejecución y devuelve un objeto
- PDOStatement::execute() - Ejecuta una consulta preparada

# PDO::rollBack

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::rollBack — Anula una transacción

### Descripción

public function PDO::rollBack(): bool

Anula la transacción actual, iniciada por la función PDO::beginTransaction().

Si la base de datos está en modo autocommit, esta función restaurará el modo autocommit después de la anulación de la transacción.

Algunas bases de datos, incluyendo MySQL, ejecutarán automáticamente un COMMIT cuando se ejecute una consulta de definición de lenguaje de base de datos (DDL) como DROP TABLE o CREATE TABLE en una transacción. Este COMMIT implícito impedirá anular cualquier otra modificación realizada en esta transacción.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Se lanzará una excepción PDOException si no hay ninguna transacción activa.

> Nota: Una excepción será emitida incluso si el atributo `PDO::ATTR_ERRMODE` no vale `PDO::ERRMODE_EXCEPTION`.

### Ejemplos

Ejemplo #1 Anulación de una transacción

El siguiente ejemplo comienza una transacción y ejecuta dos consultas que modifican la base de datos antes de anular las modificaciones. En MySQL, sin embargo, la consulta DROP TABLE validará automáticamente la transacción, por lo que ninguna de las modificaciones de la transacción será anulada.

    <?php
    /* Inicio de una transacción, desactivación del modo autocommit */
    $dbh->beginTransaction();

    /* Modifica el esquema de la base de datos así como los datos */
    $sth = $dbh->exec("DROP TABLE fruit");
    $sth = $dbh->exec("UPDATE dessert
        SET name = 'hamburger'");

    /* Se detecta un error y se anulan las modificaciones */
    $dbh->rollBack();

    /* La conexión a la base de datos vuelve al modo autocommit */
    ?>

### Ver también

- PDO::beginTransaction() - Inicia una transacción
- PDO::commit() - Valida una transacción
- Transacciones y auto-commit

# PDO::setAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::setAttribute — Configura un atributo PDO

### Descripción

public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool

Configura un atributo del gestor de base de datos. Algunos de los atributos genéricos se listan a continuación; algunos controladores disponen de configuraciones adicionales. Cabe señalar que los atributos específicos de un controlador no deben ser utilizados con otros controladores.

`PDO::ATTR_CASE`

  Fuerza los nombres de columnas a una casilla particular. Puede tomar una de las siguientes valores:

  `PDO::CASE_LOWER`
    Fuerza los nombres de columnas en minúsculas.
  `PDO::CASE_NATURAL`
    Deja los nombres de columnas tal como son devueltos por el controlador de base de datos.
  `PDO::CASE_UPPER`
    Fuerza los nombres de columnas en mayúsculas.
`PDO::ATTR_ERRMODE`

  El modo para reportar los errores de PDO. Puede tomar una de las siguientes valores:

  `PDO::ERRMODE_SILENT`
    Define solo los códigos de error.
  `PDO::ERRMODE_WARNING`
    Emite diagnósticos `E_WARNING`.
  `PDO::ERRMODE_EXCEPTION`
    Lanza excepciones PDOException.
`PDO::ATTR_ORACLE_NULLS`

  > Nota: Este atributo está disponible con todos los controladores, no solo Oracle.

  Determina si y cómo `null` y las cadenas vacías deben ser convertidas. Puede tomar una de las siguientes valores:

  `PDO::NULL_NATURAL`
    No se realiza ninguna conversión.
  `PDO::NULL_EMPTY_STRING`
    Las cadenas vacías son convertidas en `null`.
  `PDO::NULL_TO_STRING`
    `null` es convertido en cadena vacía.
`PDO::ATTR_STRINGIFY_FETCHES`

  Controla si los valores recuperados (excepto `null`) son convertidos en strings. Acepta un valor de tipo bool: `true` para activar y `false` para desactivar (valor por omisión). Los valores `null` permanecen inalterados, excepto si `PDO::ATTR_ORACLE_NULLS` está definido en `PDO::NULL_TO_STRING`.

`PDO::ATTR_STATEMENT_CLASS`

  Configura la clase de resultado derivada de PDOStatement y definida por el usuario. Requiere `array(string classname, array(mixed constructor_args))`.

  Precaución

  No puede ser utilizado con las instancias persistentes de PDO.

`PDO::ATTR_TIMEOUT`

  Especifica la duración del tiempo límite en segundos. Toma un valor de tipo int.

  > Nota:

  > No todos los controladores soportan esta opción, y su significado puede diferir en función de los controladores. Por ejemplo, SQLite esperará durante este período para obtener un bloqueo de escritura, pero otros controladores pueden interpretar esto como un tiempo límite de conexión o de lectura.

`PDO::ATTR_AUTOCOMMIT`

  > Nota: Disponible únicamente para los controladores OCI, Firebird y MySQL.

  Determina si cada consulta es autocommit. Toma un valor de tipo bool: `true` para activar y `false` para desactivar. Por omisión, `true`.

`PDO::ATTR_EMULATE_PREPARES`

  > Nota: Disponible únicamente para los controladores OCI, Firebird y MySQL.

  Configura la activación o desactivación de las consultas preparadas emuladas. Algunos controladores no soportan las consultas preparadas nativamente o tienen un soporte limitado. Si se define en `true` PDO siempre emulará las consultas preparadas, de lo contrario PDO intentará utilizar las consultas preparadas nativas. En el caso de que el controlador no pueda preparar la consulta actual, PDO siempre recaerá en la emulación de consultas preparadas.

`PDO::MYSQL_ATTR_USE_BUFFERED_QUERY`

  > Nota: Disponible únicamente para el controlador MySQL.

  Configura el uso de consultas con búfer. Toma un valor de tipo bool: `true` para activar y `false` para desactivar. Por omisión, `true`.

`PDO::ATTR_DEFAULT_FETCH_MODE`

  Define el modo de recuperación. Una descripción de los modos y cómo utilizarlos está disponible en la documentación de PDOStatement::fetch().

### Parámetros

`attribute`

  El atributo a modificar.

`value`

  El valor al que definir el `attribute`, esto puede requerir un tipo específico dependiendo del atributo.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- PDO::getAttribute() - Recupera un atributo de una conexión a una base de datos
- PDOStatement::getAttribute() - Recupera un atributo de consulta
- PDOStatement::setAttribute() - Establece un atributo de consulta

## Tabla de contenidos

- PDO::beginTransaction — Inicia una transacción
- PDO::commit — Valida una transacción
- PDO::connect — Conecta a una base de datos y devuelve una subclase PDO para los controladores que lo soportan
- PDO::__construct — Crea una instancia PDO que representa una conexión a la base de datos
- PDO::errorCode — Devuelve el SQLSTATE asociado con la última operación sobre la base de datos
- PDO::errorInfo — Devuelve las informaciones asociadas al error durante la última operación sobre la base de datos
- PDO::exec — Ejecuta una consulta SQL y devuelve el número de filas afectadas
- PDO::getAttribute — Recupera un atributo de una conexión a una base de datos
- PDO::getAvailableDrivers — Devuelve la lista de controladores PDO disponibles
- PDO::inTransaction — Verifica si se encuentra en una transacción
- PDO::lastInsertId — Devuelve el identificador de la última fila insertada o el valor de una secuencia
- PDO::prepare — Prepara una consulta para su ejecución y devuelve un objeto
- PDO::query — Prepara y ejecuta una consulta SQL sin marcadores de sustitución
- PDO::quote — Protege una cadena para usarla en una consulta SQL PDO
- PDO::rollBack — Anula una transacción
- PDO::setAttribute — Configura un atributo PDO

# La clase PDOStatement

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.0)

## Introducción

Representa una consulta preparada y, una vez ejecutada, el conjunto de resultados asociado.

## Sinopsis de la Clase

class PDOStatement implements IteratorAggregate {
/* Propiedades */
public string $queryString;
/* Métodos */
public function bindColumn(
string|int `$column`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool
public function bindParam(
string|int `$param`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool
public function bindValue(string|int `$param`, mixed `$value`, int `$type` = `PDO::PARAM_STR`): bool
public function closeCursor(): bool
public function columnCount(): int
public function debugDumpParams(): ?bool
public function errorCode(): ?string
public function errorInfo(): array
public function execute(?array `$params` = `null`): bool
public function fetch(int `$mode` = `PDO::FETCH_DEFAULT`, int `$cursorOrientation` = `PDO::FETCH_ORI_NEXT`, int `$cursorOffset` = 0): mixed
public function fetchAll(int `$mode` = PDO::FETCH_DEFAULT): array
public function fetchAll(int `$mode` = PDO::FETCH_COLUMN, int `$column`): array
public function fetchAll(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs`): array
public function fetchAll(int `$mode` = PDO::FETCH_FUNC, callable `$callback`): array
public function fetchColumn(int `$column` = 0): mixed
public function fetchObject(?string `$class` = "stdClass", array `$constructorArgs` = []): object|false
public function getAttribute(int `$name`): mixed
public function getColumnMeta(int `$column`): array|false
public function getIterator(): Iterator
public function nextRowset(): bool
public function rowCount(): int
public function setAttribute(int `$attribute`, mixed `$value`): bool
public function setFetchMode(int `$mode`): true
public function setFetchMode(int `$mode` = PDO::FETCH_COLUMN, int `$colno`): true
public function setFetchMode(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs` = `null`): true
public function setFetchMode(int `$mode` = PDO::FETCH_INTO, object `$object`): true
}

## Propiedades

queryString

  Cadena de consulta utilizada.

## Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | La clase PDOStatement implementa ahora IteratorAggregate en lugar de Traversable.

# PDOStatement::bindColumn

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::bindColumn — Vincula una columna a una variable PHP

### Descripción

public function PDOStatement::bindColumn(
string|int `$column`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool

PDOStatement::bindColumn() permite que una variable PHP se vincule a una columna específica en el conjunto de resultados de una consulta. Cada llamada a la función PDOStatement::fetch() o PDOStatement::fetchAll() actualiza todas las variables vinculadas a las columnas.

> Nota:

> Dado que la información sobre las columnas no siempre está disponible para PDO hasta que la consulta se ejecuta, las aplicaciones portables deben llamar a esta función después de la función PDOStatement::execute().

> Sin embargo, para vincular una columna de tipo LOB con un flujo al utilizar el controlador PostGreSQL, las aplicaciones deben llamar a este método antes de llamar PDOStatement::execute(), de lo contrario se recibirá el objeto OID en forma de un entero.

### Parámetros

`column`

  Número de la columna (comenzando en 1) o nombre de la columna en el conjunto de resultados. Si se utilizan los nombres de columnas, asegúrese de que el nombre coincida con la casilla de la columna, como se devuelve por el controlador.

`var`

  Nombre de la variable PHP a la que se debe vincular la columna.

`type`

  Tipo del argumento, especificado por las constantes `PDO::PARAM_*`.

`maxLength`

  Una sugerencia para la preasignación.

`driverOptions`

  Argumentos opcionales para la biblioteca.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Emite un error de nivel `E_WARNING` si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_WARNING`.

Lanza una excepción PDOException si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_EXCEPTION`.

### Ejemplos

Ejemplo #1 Vincula la visualización del conjunto de resultados a variables PHP

Vincular las columnas del conjunto de resultados a variables PHP es una forma conveniente de hacer que los datos contenidos en cada fila estén inmediatamente disponibles para la aplicación. El siguiente ejemplo muestra cómo PDO permite vincular y recuperar las columnas con una variedad de opciones.

    <?php
    $stmt = $dbh->prepare('SELECT name, colour, calories FROM fruit');
    $stmt->execute();

    /* Vincula por los números de columnas */
    $stmt->bindColumn(1, $name);
    $stmt->bindColumn(2, $colour);

    /* Vincula por los nombres de columnas */
    $stmt->bindColumn('calories', $cals);
    while ($stmt->fetch(PDO::FETCH_BOUND)) {
        print $name . "\t" . $colour . "\t" . $cals . "\n";
    }
    readData($dbh);
    ?>

Resultado del ejemplo anterior es similar a:

    pomme   rouge     150
    banane  jaune  175
    kiwi    vert   75
    orange  orange  150
    mangue   rouge     200
    fraise      rouge     25

### Ver también

- PDOStatement::execute() - Ejecuta una consulta preparada
- PDOStatement::fetch() - Recupera la siguiente línea de un conjunto de resultados PDO
- PDOStatement::fetchAll() - Recupera las líneas restantes de un conjunto de resultados
- PDOStatement::fetchColumn() - Devuelve una columna de la siguiente fila de un conjunto de resultados

# PDOStatement::bindParam

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::bindParam — Vincula un parámetro a una variable específica

### Descripción

public function PDOStatement::bindParam(
string|int `$param`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool

Vincula una variable PHP a un marcador nombrado o interrogativo correspondiente en una consulta SQL utilizada para preparar la consulta. A diferencia de PDOStatement::bindValue(), la variable es vinculada como referencia y solo será evaluada en el momento de la llamada a la función PDOStatement::execute().

La mayoría de los parámetros son parámetros de entrada, y son utilizados en modo solo lectura para construir la consulta (aunque pueden ser convertidos según el `data_type`). Algunos drivers soportan la invocación de procedimientos almacenados que retornan datos como parámetros de salida, y algunos otros como parámetros de entrada/salida que son enviados juntos y actualizados para recibirlos.

### Parámetros

`param`

  Identificador. Para una consulta preparada utilizando marcadores nombrados, será el nombre del parámetro en la forma :name. Para una consulta preparada utilizando marcadores interrogativos, será la posición indexada +1 del parámetro.

`var`

  Nombre de la variable PHP a vincular al parámetro de la consulta SQL.

`type`

  Tipo explícito de datos para el parámetro utilizando las constantes `PDO::PARAM_*`. Para retornar un parámetro INOUT desde un procedimiento almacenado, se utiliza el operador OR para definir el byte `PDO::PARAM_INPUT_OUTPUT` para el parámetro `type`.

`maxLength`

  Longitud del tipo de datos. Para indicar que un parámetro es un parámetro OUT desde un procedimiento almacenado, se debe definir explícitamente la longitud. Significativo únicamente cuando el parámetro `type` es `PDO::PARAM_INPUT_OUTPUT`.

`driverOptions`

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Emite un error de nivel `E_WARNING` si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_WARNING`.

Lanza una excepción PDOException si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_EXCEPTION`.

### Ejemplos

Ejemplo #1 Ejecución de una consulta preparada con emplazamientos nombrados

    <?php
    /* Ejecución de una consulta preparada vinculando variables PHP */
    $calories = 150;
    $couleur = 'rouge';
    $sth = $dbh->prepare('SELECT nom, couleur, calories
        FROM fruit
        WHERE calories < :calories AND couleur = :couleur');
    $sth->bindParam('calories', $calories, PDO::PARAM_INT);
    /* Los nombres también pueden ser prefijados con dos puntos ":" (opcional) */
    $sth->bindParam(':couleur', $couleur, PDO::PARAM_STR);
    $sth->execute();
    ?>

Ejemplo #2 Ejecución de una consulta preparada con marcadores de posicionamiento

    <?php
    /* Ejecución de una consulta preparada vinculando variables PHP */
    $calories = 150;
    $couleur = 'rouge';
    $sth = $dbh->prepare('SELECT nom, couleur, calories
        FROM fruit
        WHERE calories < ? AND couleur = ?');
    $sth->bindParam(1, $calories, PDO::PARAM_INT);
    $sth->bindParam(2, $couleur, PDO::PARAM_STR);
    $sth->execute();
    ?>

Ejemplo #3 Llamada a un procedimiento almacenado con un parámetro INOUT

    <?php
    /* Llamada a un procedimiento almacenado con un parámetro INOUT */
    $couleur = 'rouge';
    $sth = $dbh->prepare('CALL puree_fruit(?)');
    $sth->bindParam(1, $couleur, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT, 12);
    $sth->execute();
    print "Después de haber prensado la fruta, el color es: $couleur";
    ?>

### Ver también

- PDO::prepare() - Prepara una consulta para su ejecución y devuelve un objeto
- PDOStatement::execute() - Ejecuta una consulta preparada
- PDOStatement::bindValue() - Asocia un valor a un parámetro

# PDOStatement::bindValue

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.0)

PDOStatement::bindValue — Asocia un valor a un parámetro

### Descripción

public function PDOStatement::bindValue(string|int `$param`, mixed `$value`, int `$type` = `PDO::PARAM_STR`): bool

Asocia un valor a un nombre correspondiente o a un punto de interrogación (como parámetro ficticio) en la consulta SQL que se ha utilizado para preparar la consulta.

### Parámetros

`param`

  Identificador del parámetro. Para una consulta preparada utilizando los marcadores, esto será un nombre de parámetro de la forma :nombre. Para una consulta preparada utilizando los puntos de interrogación (como parámetro ficticio), esto será un array indexado numéricamente que comienza en la posición 1 del parámetro.

`value`

  El valor a asociar al parámetro.

`type`

  Tipo de datos explícito para el parámetro utilizando las constantes `PDO::PARAM_*`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Emite un error de nivel `E_WARNING` si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_WARNING`.

Lanza una excepción PDOException si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_EXCEPTION`.

### Ejemplos

Ejemplo #1 Ejecutar una consulta preparada con marcadores nombrados

    <?php
    /* Ejecutar una consulta preparada asociando variables PHP */
    $calorias = 150;
    $color = 'rojo';
    $sth = $dbh->prepare('SELECT nombre, color, calorias
        FROM fruta
        WHERE calorias < :calorias AND color = :color');

    /* Definir el valor de un parámetro utilizando su nombre */
    $sth->bindValue('calorias', $calorias, PDO::PARAM_INT);
    /* Opcionalmente, los nombres de los parámetros pueden ser prefijados con dos puntos ": " */
    $sth->bindValue(':color', $color, PDO::PARAM_STR);
    $sth->execute();
    ?>

Ejemplo #2 Ejecutar una consulta preparada con puntos de interrogación como parámetro ficticio

    <?php
    /* Ejecutar una consulta preparada asociando variables PHP */
    $calorias = 150;
    $color = 'rojo';
    $sth = $dbh->prepare('SELECT nombre, color, calorias
        FROM fruta
        WHERE calorias < ? AND color = ?');
    $sth->bindValue(1, $calorias, PDO::PARAM_INT);
    $sth->bindValue(2, $color, PDO::PARAM_STR);
    $sth->execute();
    ?>

### Ver también

- PDO::prepare() - Prepara una consulta para su ejecución y devuelve un objeto
- PDOStatement::execute() - Ejecuta una consulta preparada
- PDOStatement::bindParam() - Vincula un parámetro a una variable específica

# PDOStatement::closeCursor

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::closeCursor — Cierra el cursor, permitiendo que la consulta pueda ser ejecutada de nuevo

### Descripción

public function PDOStatement::closeCursor(): bool

PDOStatement::closeCursor() libera la conexión al servidor, permitiendo así que otras consultas SQL puedan ser ejecutadas, pero deja la consulta en un estado que permite su ejecución posterior.

Este método es útil para los drivers de bases de datos que no soportan la ejecución de objetos PDOStatement cuando un objeto PDOStatement ejecutado previamente aún tiene filas no recuperadas. Si su driver de base de datos sufre de esta limitación, el problema se manifestará por sí mismo en un error fuera de secuencia.

PDOStatement::closeCursor() se implementa bien como un método específico del driver con máxima eficiencia, o como una solución genérica si no se ha instalado ninguna función específica del driver. Semánticamente, la función genérica PDO equivale a escribir el siguiente código en su script PHP:

    <?php
    do {
        while ($stmt->fetch())
            ;
        if (!$stmt->nextRowset())
            break;
    } while (true);
    ?>

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Emite un error de nivel `E_WARNING` si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_WARNING`.

Lanza una excepción PDOException si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_EXCEPTION`.

### Ejemplos

Ejemplo #1 Ejemplo con PDOStatement::closeCursor()

En el siguiente ejemplo, el objeto PDOStatement $stmt devuelve múltiples filas, pero la aplicación recupera únicamente la primera fila, dejando el objeto PDOStatement en un estado donde aún quedan filas no recuperadas. Para asegurar que la aplicación funcione con todos los drivers de bases de datos, el autor inserta una llamada a la función PDOStatement::closeCursor() en $stmt antes de la ejecución del objeto PDOStatement $otherStmt.

    <?php
    /* Creación de un objeto PDOStatement */
    $stmt = $dbh->prepare('SELECT foo FROM bar');

    /* Creación de un segundo objeto PDOStatement */
    $otherStmt = $dbh->prepare('SELECT foobaz FROM foobar');

    /* Ejecución de la primera consulta */
    $stmt->execute();

    /* Recuperación de la primera fila únicamente desde el resultado */
    $stmt->fetch();

    /* La siguiente llamada a closeCursor() puede ser requerida por algunos drivers */
    $stmt->closeCursor();

    /* Ahora, podemos ejecutar la segunda consulta */
    $otherStmt->execute();
    ?>

### Ver también

- PDOStatement::execute() - Ejecuta una consulta preparada

# PDOStatement::columnCount

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::columnCount — Devuelve el número de columnas en el conjunto de resultados

### Descripción

public function PDOStatement::columnCount(): int

Utilice la función PDOStatement::columnCount() para devolver el número de columnas en el conjunto de resultados representado por el objeto PDOStatement.

Si el objeto PDOStatement ha sido devuelto por la función PDO::query(), el número de columnas es inmediatamente disponible.

Si el objeto PDOStatement ha sido devuelto por la función PDO::prepare(), un conteo preciso de las columnas no estará disponible hasta que se invoque la función PDOStatement::execute().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de columnas en el conjunto de resultados representado por el objeto PDOStatement, incluso si el conjunto de resultados está vacío. Si no hay conjunto de resultados, PDOStatement::columnCount() devolverá `0`.

### Errores/Excepciones

Emite un error de nivel `E_WARNING` si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_WARNING`.

Lanza una excepción PDOException si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_EXCEPTION`.

### Ejemplos

Ejemplo #1 Conteo de columnas

Este ejemplo demuestra cómo PDOStatement::columnCount() funciona con o sin conjunto de resultados.

    <?php
    $dbh = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');

    $sth = $dbh->prepare("SELECT nom, couleur FROM fruit");

    /* Cuenta el número de columnas en el conjunto de resultados (no existente) */
    $colcount = $sth->columnCount();
    print "Antes de execute(), el conjunto de resultados tenía $colcount columnas (debería ser 0)\n";

    $sth->execute();

    /* Cuenta el número de columnas en el conjunto de resultados */
    $colcount = $sth->columnCount();
    print "Después de execute(), el conjunto de resultados tiene $colcount columnas (debería ser 2)\n";

    ?>

El ejemplo anterior mostrará:

    Antes de execute(), el conjunto de resultados tenía 0 columnas (debería ser 0)
    Después de execute(), el conjunto de resultados tiene 2 columnas (debería ser 2)

### Ver también

- PDO::prepare() - Prepara una consulta para su ejecución y devuelve un objeto
- PDOStatement::execute() - Ejecuta una consulta preparada
- PDOStatement::rowCount() - Devuelve el número de filas afectadas por la última llamada a la función PDOStatement::execute()

# PDOStatement::debugDumpParams

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::debugDumpParams — Detalla una instrucción SQL preparada

### Descripción

public function PDOStatement::debugDumpParams(): ?bool

Detalla la información contenida en una instrucción preparada, directamente en la salida estándar. La información incluye la consulta `SQL` utilizada, el número de parámetros usados (`Params`), la lista de parámetros, con el nombre de clave o su posición, su nombre, su posición en la consulta (si esta última información no es soportada por el controlador PDO, es siempre -1), un tipo (`param_type`) en forma de entero, y un valor booleano `is_param`.

Esta es una función de depuración, que muestra directamente información en la salida estándar.

Sugerencia

Al igual que con todas las funciones que muestran directamente resultados al navegador, las funciones de gestión de salida pueden ser utilizadas para capturar la salida de esta función y almacenarla en un string (por ejemplo).

Los parámetros mostrados son aquellos que han sido añadidos en la consulta hasta el momento de la llamada. Los parámetros adicionales son ignorados.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `null`, o `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
7.2.0 | PDOStatement::debugDumpParams() ahora devuelve el SQL enviado a la base de datos, incluyendo la consulta completa, RAW (incluyendo los marcadores de posición reemplazados con sus valores delimitados). Tenga en cuenta que esto solo estará disponible si las instrucciones preparadas emuladas están activadas.

### Ejemplos

Ejemplo #1 Ejemplo con PDOStatement::debugDumpParams() y parámetros nombrados

    <?php
    /* ejecución de una instrucción preparada con enlace a variables PHP */
    $calories = 150;
    $colour = 'red';
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour = :colour');
    $sth->bindParam(':calories', $calories, PDO::PARAM_INT);
    $sth->bindValue(':colour', $colour, PDO::PARAM_STR, 12);
    $sth->execute();

    $sth->debugDumpParams();

    ?>

El ejemplo anterior mostrará:

    SQL: [96] SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour = :colour
    Params:  2
    Key: Name: [9] :calories
    paramno=-1
    name=[9] ":calories"
    is_param=1
    param_type=1
    Key: Name: [7] :colour
    paramno=-1
    name=[7] ":colour"
    is_param=1
    param_type=2

Ejemplo #2 Ejemplo con PDOStatement::debugDumpParams() y parámetros anónimos

    <?php

    /* ejecución de una instrucción preparada con enlace a variables PHP */
    $calories = 150;
    $colour = 'red';
    $name = 'apple';

    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?');
    $sth->bindParam(1, $calories, PDO::PARAM_INT);
    $sth->bindValue(2, $colour, PDO::PARAM_STR);
    $sth->execute();

    $sth->debugDumpParams();

    ?>

El ejemplo anterior mostrará:

    SQL: [82] SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?
    Params:  2
    Key: Position #0:
    paramno=0
    name=[0] ""
    is_param=1
    param_type=1
    Key: Position #1:
    paramno=1
    name=[0] ""
    is_param=1
    param_type=2

### Ver también

- PDO::prepare() - Prepara una consulta para su ejecución y devuelve un objeto
- PDOStatement::bindParam() - Vincula un parámetro a una variable específica
- PDOStatement::bindValue() - Asocia un valor a un parámetro

# PDOStatement::errorCode

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::errorCode — Recupera las informaciones sobre el error asociado durante la última operación sobre la consulta

### Descripción

public function PDOStatement::errorCode(): ?string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Idéntico a PDO::errorCode(), excepto que PDOStatement::errorCode() recupera únicamente los códigos de error para las operaciones sobre los objetos PDOStatement.

### Ejemplos

Ejemplo #1 Determina la categoría del error que ocurre

    <?php
    /* Provoca un error -- la tabla BONES no existe */
    $err = $dbh->prepare('SELECT skull FROM bones');
    $err->execute();

    echo "\nPDOStatement::errorCode(): ";
    print $err->errorCode();
    ?>

El ejemplo anterior mostrará:

    PDOStatement::errorCode(): 42S02

### Ver también

- PDO::errorCode() - Devuelve el SQLSTATE asociado con la última operación sobre la base de datos
- PDO::errorInfo() - Devuelve las informaciones asociadas al error durante la última operación sobre la base de datos
- PDOStatement::errorInfo() - Recupera las informaciones sobre el error asociado durante la última operación sobre la consulta

# PDOStatement::errorInfo

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::errorInfo — Recupera las informaciones sobre el error asociado durante la última operación sobre la consulta

### Descripción

public function PDOStatement::errorInfo(): array

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

PDOStatement::errorInfo() devuelve un array que contiene informaciones sobre el error ocurrido durante la última operación ejecutada por este gestor de consultas. El array contiene los siguientes campos:

Elemento | Información
--- | ---
0 | Código de error SQLSTATE (un identificador de cinco caracteres alfanuméricos definido en el estándar ANSI SQL)
1 | Código de error específico del driver.
2 | Mensaje de error específico del driver.

### Ejemplos

Ejemplo #1 Muestra los campos de errorInfo() para una conexión PDO_ODBC sobre una base de datos DB2

    <?php
    /* Provoca un error -- la tabla BONES no existe */
    $sth = $dbh->prepare('SELECT skull FROM bones');
    $sth->execute();

    echo "\nPDOStatement::errorInfo():\n";
    $arr = $sth->errorInfo();
    print_r($arr);
    ?>

El ejemplo anterior mostrará:

    PDOStatement::errorInfo():
    Array
    (
        [0] => 42S02
        [1] => -204
        [2] => [IBM][CLI Driver][DB2/LINUX] SQL0204N  "DANIELS.BONES" is an undefined name.  SQLSTATE=42704
    )

### Ver también

- PDO::errorCode() - Devuelve el SQLSTATE asociado con la última operación sobre la base de datos
- PDO::errorInfo() - Devuelve las informaciones asociadas al error durante la última operación sobre la base de datos
- PDOStatement::errorCode() - Recupera las informaciones sobre el error asociado durante la última operación sobre la consulta

# PDOStatement::execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::execute — Ejecuta una consulta preparada

### Descripción

public function PDOStatement::execute(?array `$params` = `null`): bool

Ejecuta una consulta preparada. Si la consulta preparada incluye marcadores de posición, se puede:

- PDOStatement::bindParam() y/o PDOStatement::bindValue() debe ser llamado para vincular variables o valores (respectivamente) a los marcadores de parámetros. Las variables vinculadas pasan sus valores en entrada y reciben los valores de salida, si los hay, de sus respectivos marcadores de posición

- o pasar un array de valores de parámetros, solo en entrada

### Parámetros

`params`

  Un array de valores con tantos elementos como parámetros a asociar en la consulta SQL que será ejecutada. Todos los valores son tratados como constantes `PDO::PARAM_STR`.

  Los valores múltiples no pueden ser vinculados a un solo parámetro; por ejemplo, no está permitido vincular dos valores a un solo parámetro nombrado en una cláusula IN().

  Vincular más valores de los especificados no es posible; si hay más claves en `params` que en el código SQL utilizado para PDO::prepare(), entonces la consulta preparada fallará y se generará un error.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Emite un error de nivel `E_WARNING` si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_WARNING`.

Lanza una excepción PDOException si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_EXCEPTION`.

### Ejemplos

Ejemplo #1 Ejecuta una consulta preparada con variables y valores vinculados

    <?php
    /* Ejecuta una consulta preparada vinculando variables y valores */
    $calories = 150;
    $couleur = 'ver';
    $sth = $dbh->prepare('SELECT nom, couleur, calories
        FROM fruit
        WHERE calories < :calories AND couleur LIKE :couleur');
    $sth->bindParam('calories', $calories, PDO::PARAM_INT);
    /* Los nombres también pueden ser prefijados con dos puntos ":" (opcional) */
    $sth->bindValue(':colour', "%$colour%");
    $sth->execute();
    ?>

Ejemplo #2 Ejecuta una consulta preparada con un array de valores nombrados

    <?php
    /* Ejecuta una consulta preparada pasando un array de valores */
    $calories = 150;
    $couleur = 'rouge';
    $sth = $dbh->prepare('SELECT nom, couleur, calories
        FROM fruit
        WHERE calories < :calories AND couleur = :couleur');
    $sth->execute(array('calories' => $calories, 'colour' => $couleur));
    /* Las claves del array también pueden ser prefijadas con dos puntos ":" (opcional) */
    $sth->execute(array(':calories' => $calories, ':couleur' => $couleur));
    ?>

Ejemplo #3 Ejecuta una consulta preparada con un array de valores posicionales

    <?php
    /* Ejecuta una consulta preparada pasando un array de valores */
    $calories = 150;
    $colour = 'rouge';
    $sth = $dbh->prepare('SELECT nom, couleur, calories
        FROM fruit
        WHERE calories < ? AND couleur = ?');
    $sth->execute(array($calories, $colour));
    ?>

Ejemplo #4 Ejecuta una consulta preparada con variables vinculadas a un marcador de posición

    <?php
    /* Ejecuta una consulta preparada vinculando variables PHP */
    $calories = 150;
    $couleur = 'rouge';
    $sth = $dbh->prepare('SELECT nom, couleur, calories
        FROM fruit
        WHERE calories < ? AND couleur = ?');
    $sth->bindParam(1, $calories, PDO::PARAM_INT);
    $sth->bindParam(2, $couleur, PDO::PARAM_STR, 12);
    $sth->execute();
    ?>

Ejemplo #5 Ejecuta una consulta preparada utilizando un array para las cláusulas IN

    <?php
    /* Ejecuta una consulta preparada utilizando un array de valores para las cláusulas IN */
    $params = array(1, 21, 63, 171);
    /* Crea una cadena para los marcadores */
    $place_holders = '?' . str_repeat(', ?', count($params) - 1);

    /*
        Este fragmento de código prepara la consulta con suficientes marcadores para cada valor
        del array $params. Los valores del array $params son luego vinculados a los marcadores
        de la consulta preparada cuando la consulta es ejecutada. Esto no es lo mismo
        que utilizar el método PDOStatement::bindParam() ya que este impone una referencia
        hacia los valores. El método PDOStatement::execute() solo vincula por valor.
    */
    $sth = $dbh->prepare("SELECT id, name FROM contacts WHERE id IN ($place_holders)");
    $sth->execute($params);
    ?>

### Notas

> Nota:

> Algunos drivers requieren cerrar el cursor antes de ejecutar la siguiente consulta.

### Ver también

- PDO::prepare() - Prepara una consulta para su ejecución y devuelve un objeto
- PDOStatement::bindParam() - Vincula un parámetro a una variable específica
- PDOStatement::fetch() - Recupera la siguiente línea de un conjunto de resultados PDO
- PDOStatement::fetchAll() - Recupera las líneas restantes de un conjunto de resultados
- PDOStatement::fetchColumn() - Devuelve una columna de la siguiente fila de un conjunto de resultados

# PDOStatement::fetch

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::fetch — Recupera la siguiente línea de un conjunto de resultados PDO

### Descripción

public function PDOStatement::fetch(int `$mode` = `PDO::FETCH_DEFAULT`, int `$cursorOrientation` = `PDO::FETCH_ORI_NEXT`, int `$cursorOffset` = 0): mixed

Recupera una línea desde un conjunto de resultados asociado al objeto PDOStatement. El argumento `mode` determina la forma en que PDO devuelve la línea.

### Parámetros

`mode`

  Controla cómo se devolverá la siguiente línea al llamante. Este valor debe ser una de las constantes `PDO::FETCH_*`, y por omisión, vale la constante `PDO::ATTR_DEFAULT_FETCH_MODE` (que por omisión vale la constante `PDO::FETCH_BOTH`).

  - `PDO::FETCH_ASSOC`: devuelve un array indexado por el nombre de la columna como se devuelve en el conjunto de resultados

  - `PDO::FETCH_BOTH` (por omisión): devuelve un array indexado por los nombres de columnas y también por los números de columnas, comenzando en el índice 0, como se devuelve en el conjunto de resultados

  - `PDO::FETCH_BOUND`: devuelve `true` y asigna los valores de las columnas de su conjunto de resultados en las variables PHP a las que están vinculadas con el método PDOStatement::bindColumn()

  - `PDO::FETCH_CLASS`: devuelve una nueva instancia de la clase solicitada. El objeto se inicializa mapeando las columnas del conjunto de resultados a las propiedades de la clase. Este proceso ocurre antes de que se llame al constructor, permitiendo la población de las propiedades, independientemente de su visibilidad o de su marca como `readonly`. Si una propiedad no existe en la clase, se invocará el método mágico __set() si existe; de lo contrario, se creará una propiedad pública dinámica. Sin embargo, cuando `PDO::FETCH_PROPS_LATE` también está especificado, el constructor se llama antes de que las propiedades sean pobladas. Si `mode` incluye `PDO::FETCH_CLASSTYPE` (p.ej. `PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE`), el nombre de la clase se determina a partir del valor de la primera columna.

  - `PDO::FETCH_INTO` : actualiza una instancia existente de la clase solicitada, vinculando las columnas del conjunto de resultados a los nombres de las propiedades de la clase

  - `PDO::FETCH_LAZY` : combina `PDO::FETCH_BOTH` y `PDO::FETCH_OBJ`, y devuelve un objeto PDORow que crea los nombres de propiedad del objeto a medida que se acceden.

  - `PDO::FETCH_NAMED` : devuelve un array de la misma forma que `PDO::FETCH_ASSOC`, excepto que si hay múltiples columnas con los mismos nombres, el valor apuntado por esta clave será un array de todas las valores de la línea que tiene ese nombre como columna

  - `PDO::FETCH_NUM` : devuelve un array indexado por el número de la columna como se devuelve en su conjunto de resultados, comenzando en 0

  - `PDO::FETCH_OBJ` : devuelve un objeto anónimo con los nombres de propiedades que corresponden a los nombres de las columnas devueltas en el conjunto de resultados

  - `PDO::FETCH_PROPS_LATE` : cuando se usa con `PDO::FETCH_CLASS`, el constructor de la clase es llamado antes de que las propiedades sean asignadas a partir de los valores de columna respectivos.

`cursorOrientation`

  Para un objeto PDOStatement que representa un cursor desplazable, este valor determina qué línea se devolverá al llamante. Este valor debe ser una de las constantes `PDO::FETCH_ORI_*`, y por omisión, vale `PDO::FETCH_ORI_NEXT`. Para solicitar un cursor desplazable para su objeto PDOStatement, debe definir el atributo `PDO::ATTR_CURSOR` a `PDO::CURSOR_SCROLL` cuando prepare la consulta SQL con la función PDO::prepare().

`cursorOffset`

  Para un objeto PDOStatement que representa un cursor desplazable para el cual el argumento `cursorOrientation` está definido a `PDO::FETCH_ORI_ABS`, este valor especifica el número absoluto de la línea en el conjunto de resultados que debe ser recuperada.

  Para un objeto PDOStatement que representa un cursor desplazable para el cual el argumento `cursorOrientation` está definido a `PDO::FETCH_ORI_REL`, este valor especifica la línea a recuperar relativamente a la posición del cursor antes de la llamada a la función PDOStatement::fetch().

### Valores devueltos

El valor devuelto por esta función en caso de éxito depende del tipo recuperado. En todos los casos, `false` se devuelve si ocurre un error o si no hay más líneas.

### Errores/Excepciones

Emite un error de nivel `E_WARNING` si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_WARNING`.

Lanza una excepción PDOException si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_EXCEPTION`.

### Ejemplos

Ejemplo #1 Recuperación de líneas utilizando diferentes métodos

    <?php
    $sth = $dbh->prepare("SELECT nom, couleur FROM fruit");
    $sth->execute();

    /* estilos PDOStatement::fetch */
    print "PDO::FETCH_ASSOC: ";
    print "Devuelve la siguiente línea como un array indexado por el nombre de las columnas\n";
    $result = $sth->fetch(PDO::FETCH_ASSOC);
    print_r($result);
    print "\n";

    print "PDO::FETCH_BOTH: ";
    print "Devuelve la siguiente línea como un array indexado por el nombre y el número de la columna\n";
    $result = $sth->fetch(PDO::FETCH_BOTH);
    print_r($result);
    print "\n";

    print "PDO::FETCH_LAZY: ";
    print "Devuelve la siguiente línea como objeto PDORow con los nombres de columnas como propiedades\n";
    $result = $sth->fetch(PDO::FETCH_LAZY);
    print_r($result);
    print "\n";

    print "PDO::FETCH_OBJ: ";
    print "Devuelve la siguiente línea como objeto anónimo con los nombres de columnas como propiedades\n";
    $result = $sth->fetch(PDO::FETCH_OBJ);
    print $result->name;
    print "\n";
    ?>

El ejemplo anterior mostrará:

    PDO::FETCH_ASSOC: Devuelve la siguiente línea como un array indexado por el nombre de las columnas
    Array
    (
        [nom] => apple
        [couleur] => red
    )

    PDO::FETCH_BOTH: Devuelve la siguiente línea como un array indexado por el nombre y el número de la columna
    Array
    (
        [nom] => banana
        [0] => banana
        [couleur] => yellow
        [1] => yellow
    )

    PDO::FETCH_LAZY: Devuelve la siguiente línea como objeto PDORow con los nombres de columnas como propiedades PDORow Object
    (
        [nom] => orange
        [couleur] => orange
    )

    PDO::FETCH_OBJ: Devuelve la siguiente línea como objeto anónimo con los nombres de columnas como propiedades kiwi

Ejemplo #2 Recuperación de líneas con un cursor desplazable

    <?php
    function readDataForwards($dbh) {
        $sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY BET';
        $stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
        $stmt->execute();
        while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_NEXT)) {
            $data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
            print $data;
        }
    }
    function readDataBackwards($dbh) {
        $sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY bet';
        $stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
        $stmt->execute();
        $row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_LAST);
        do {
            $data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
            print $data;
        } while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_PRIOR));
    }

    print "Lectura hacia adelante :\n";
    readDataForwards($conn);

    print "Lectura hacia atrás :\n";
    readDataBackwards($conn);
    ?>

El ejemplo anterior mostrará:

    Lectura hacia adelante :
    21    10    5
    16    0     5
    19    20    10

    Lectura hacia atrás :
    19    20    10
    16    0     5
    21    10    5

Ejemplo #3 Orden de construcción

Cuando los objetos son recuperados mediante `PDO::FETCH_CLASS`, las propiedades del objeto se asignan primero, luego se llama al constructor de la clase. Sin embargo, cuando `PDO::FETCH_PROPS_LATE` también está especificado, este orden se invierte, es decir, el constructor se llama primero, luego las propiedades son asignadas.

    <?php
    class Person
    {
        private $name;

        public function __construct()
        {
            $this->tell();
        }

        public function tell()
        {
            if (isset($this->name)) {
                echo "Soy {$this->name}.\n";
            } else {
                echo "Aún no tengo nombre.\n";
            }
        }
    }

    $sth = $dbh->query("SELECT * FROM people");
    $sth->setFetchMode(PDO::FETCH_CLASS, 'Person');
    $person = $sth->fetch();
    $person->tell();
    $sth->setFetchMode(PDO::FETCH_CLASS|PDO::FETCH_PROPS_LATE, 'Person');
    $person = $sth->fetch();
    $person->tell();
    ?>

Resultado del ejemplo anterior es similar a:

    Soy Alice.
    Soy Alice.
    Aún no tengo nombre.
    Soy Bob.

### Ver también

- PDO::prepare() - Prepara una consulta para su ejecución y devuelve un objeto
- PDOStatement::execute() - Ejecuta una consulta preparada
- PDOStatement::fetchAll() - Recupera las líneas restantes de un conjunto de resultados
- PDOStatement::fetchColumn() - Devuelve una columna de la siguiente fila de un conjunto de resultados
- PDOStatement::fetchObject() - Recupera la siguiente línea y la devuelve como objeto
- PDOStatement::setFetchMode() - Establece el modo de recuperación por defecto para esta consulta

# PDOStatement::fetchAll

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::fetchAll — Recupera las líneas restantes de un conjunto de resultados

### Descripción

public function PDOStatement::fetchAll(int `$mode` = PDO::FETCH_DEFAULT): array
public function PDOStatement::fetchAll(int `$mode` = PDO::FETCH_COLUMN, int `$column`): array
public function PDOStatement::fetchAll(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs`): array
public function PDOStatement::fetchAll(int `$mode` = PDO::FETCH_FUNC, callable `$callback`): array

### Parámetros

`mode`

  Controla el contenido del array retornado como se documenta en la función PDOStatement::fetch(). Valor por omisión: `PDO::ATTR_DEFAULT_FETCH_MODE` (que toma su valor por omisión de `PDO::FETCH_BOTH`).

  Para retornar un array que contenga todos los valores de una sola columna desde el conjunto de resultados, se especifica `PDO::FETCH_COLUMN`. Puede especificarse qué columna se desea con el argumento `column`.

  Para indexar el array resultante por el valor de una cierta columna (en lugar de por números consecutivos), se coloca el nombre de esta columna en primer lugar en la lista de columnas en SQL, y se utiliza `PDO::FETCH_UNIQUE`. Esta columna debe contener únicamente valores únicos, de lo contrario se perderán algunos datos.

  Para agrupar los resultados en forma de un array de tres dimensiones indexado por los valores de una columna especificada, se coloca el nombre de esta columna en primer lugar en la lista de columnas en SQL y se utiliza `PDO::FETCH_GROUP`.

  Para agrupar los resultados en forma de un array de dos dimensiones, se utiliza un OU a nivel de bits con `PDO::FETCH_GROUP` y `PDO::FETCH_COLUMN`. Los resultados serán agrupados por la primera columna, el valor del elemento del array siendo una lista de entradas correspondientes de la segunda columna.

Los argumentos siguientes son dinámicos y dependen del modo de recuperación. No pueden ser utilizados con argumentos nombrados.

`column`

  Utilizado con `PDO::FETCH_COLUMN`. Retorna la columna indicada indexada a 0.

`class`

  Utilizado con `PDO::FETCH_CLASS`. Retorna instancias de la clase especificada, haciendo corresponder las columnas de cada línea a propiedades nombradas en la clase.

`constructorArgs`

  Argumentos del constructor personalizado de la clase cuando el argumento `mode` es `PDO::FETCH_CLASS`.

`callback`

  Utilizado con `PDO::FETCH_FUNC`. Retorna los resultados de la llamada de la función especificada, utilizando las columnas de cada línea como argumentos en la llamada.

### Valores devueltos

PDOStatement::fetchAll() retorna un array que contiene todas las líneas del conjunto de registros. El array representa cada línea como un array de valores de las columnas, o un objeto con propiedades correspondientes a cada nombre de columna. Un array vacío es retornado si no hay resultados.

El uso de este método para recuperar grandes conjuntos de resultados puede aumentar el uso de recursos del sistema, pero también estos recursos. En lugar de recuperar todas las datos y manipularlas con PHP, se utiliza el servidor de base de datos para manipular los conjuntos de resultados. Por ejemplo, se utilizan las cláusulas WHERE y ORDER BY en las consultas SQL para restringir los resultados antes de recuperarlos y procesarlos con PHP.

### Errores/Excepciones

Emite un error de nivel `E_WARNING` si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_WARNING`.

Lanza una excepción PDOException si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_EXCEPTION`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Este método retorna ahora siempre un array, anteriormente `false` podía ser retornado en caso de fallo.

### Ejemplos

Ejemplo #1 Recuperación de todas las líneas de un conjunto de resultados

    <?php
    $sth = $dbh->prepare("SELECT nom, couleur FROM fruit");
    $sth->execute();

    /* Recuperación de todas las líneas de un conjunto de resultados */
    print "Recuperación de todas las líneas de un conjunto de resultados :\n";
    $result = $sth->fetchAll();
    print_r($result);
    ?>

Resultado del ejemplo anterior es similar a:

    Recuperación de todas las líneas de un conjunto de resultados :
    Array
    (
        [0] => Array
            (
                [nom] => apple
                [0] => apple
                [couleur] => red
                [1] => red
            )

        [1] => Array
            (
                [nom] => pear
                [0] => pear
                [couleur] => green
                [1] => green
            )

        [2] => Array
            (
                [nom] => watermelon
                [0] => watermelon
                [couleur] => pink
                [1] => pink
            )

    )

Ejemplo #2 Recuperación de todos los valores de una sola columna desde un conjunto de resultados

El siguiente ejemplo muestra cómo retornar todos los valores de una sola columna desde un conjunto de resultados, incluso si la consulta SQL retorna varias columnas por líneas.

    <?php
    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    /* Recuperación de todos los valores de la primera columna */
    $result = $sth->fetchAll(PDO::FETCH_COLUMN, 0);
    var_dump($result);
    ?>

Resultado del ejemplo anterior es similar a:

    Array(3)
    (
        [0] =>
        string(5) => apple
        [1] =>
        string(4) => pear
        [2] =>
        string(10) => watermelon
    )

Ejemplo #3 Agrupar todos los valores de una sola columna

El siguiente ejemplo muestra cómo retornar un array asociativo agrupado por los valores de la columna especificada de un conjunto de resultados. El array contiene tres claves: los valores `apple` y `pear` son retornados en forma de arrays que contienen dos colores diferentes, mientras que `watermelon` es retornado en forma de un array que contiene únicamente un solo color.

    <?php
    $insert = $dbh->prepare("INSERT INTO fruit(name, colour) VALUES (?, ?)");
    $insert->execute(array('apple', 'green'));
    $insert->execute(array('pear', 'yellow'));

    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    /* Agrupar los valores de la primera columna */
    var_dump($sth->fetchAll(PDO::FETCH_COLUMN|PDO::FETCH_GROUP));
    ?>

Resultado del ejemplo anterior es similar a:

    array(3) {
      ["apple"]=>
        array(2) {
          [0]=>
            string(5) "green"
          [1]=>
            string(3) "red"
        }
      ["pear"]=>
        array(2) {
          [0]=>
            string(5) "green"
          [1]=>
            string(6) "yellow"
        }
      ["watermelon"]=>
        array(1) {
          [0]=>
            string(5) "pink"
        }
    }

Ejemplo #4 Instanciar una clase para cada resultado

El siguiente ejemplo muestra el comportamiento de `PDO::FETCH_CLASS`.

    <?php
    class fruit {
        public $name;
        public $colour;
    }

    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    $result = $sth->fetchAll(PDO::FETCH_CLASS, "fruit");
    var_dump($result);
    ?>

Resultado del ejemplo anterior es similar a:

    array(3) {
      [0]=>
      object(fruit)#1 (2) {
        ["name"]=>
        string(5) "apple"
        ["colour"]=>
        string(5) "green"
      }
      [1]=>
      object(fruit)#2 (2) {
        ["name"]=>
        string(4) "pear"
        ["colour"]=>
        string(6) "yellow"
      }
      [2]=>
      object(fruit)#3 (2) {
        ["name"]=>
        string(10) "watermelon"
        ["colour"]=>
        string(4) "pink"
      }
      [3]=>
      object(fruit)#4 (2) {
        ["name"]=>
        string(5) "apple"
        ["colour"]=>
        string(3) "red"
      }
      [4]=>
      object(fruit)#5 (2) {
        ["name"]=>
        string(4) "pear"
        ["colour"]=>
        string(5) "green"
      }
    }

Ejemplo #5 Llamada de una función para cada resultado

El siguiente ejemplo muestra el comportamiento de `PDO::FETCH_FUNC`.

    <?php
    function fruit($name, $colour) {
        return "{$name}: {$colour}";
    }

    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    $result = $sth->fetchAll(PDO::FETCH_FUNC, "fruit");
    var_dump($result);
    ?>

Resultado del ejemplo anterior es similar a:

    array(3) {
      [0]=>
      string(12) "apple: green"
      [1]=>
      string(12) "pear: yellow"
      [2]=>
      string(16) "watermelon: pink"
      [3]=>
      string(10) "apple: red"
      [4]=>
      string(11) "pear: green"
    }

### Ver también

- PDO::query() - Prepara y ejecuta una consulta SQL sin marcadores de sustitución
- PDOStatement::fetch() - Recupera la siguiente línea de un conjunto de resultados PDO
- PDOStatement::fetchColumn() - Devuelve una columna de la siguiente fila de un conjunto de resultados
- PDO::prepare() - Prepara una consulta para su ejecución y devuelve un objeto
- PDOStatement::setFetchMode() - Establece el modo de recuperación por defecto para esta consulta

# PDOStatement::fetchColumn

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::fetchColumn — Devuelve una columna de la siguiente fila de un conjunto de resultados

### Descripción

public function PDOStatement::fetchColumn(int `$column` = 0): mixed

Devuelve una columna de la siguiente fila de un conjunto de resultados o `false` si no hay más filas.

> Nota:

> PDOStatement::fetchColumn() no debe usarse para recuperar columnas que contengan valores booleanos, ya que no es posible distinguir un valor `false` de un retorno sin filas para recuperar. Utilice PDOStatement::fetch() en su lugar.

### Parámetros

`column`

  Número de la columna que se desea recuperar de la fila (comenzando en 0). Si no se proporciona ningún valor, PDOStatement::fetchColumn() recuperará la primera columna.

### Valores devueltos

PDOStatement::fetchColumn() devuelve una columna de la siguiente fila de un conjunto de resultados o `false` si no hay más filas.

Advertencia

No existe solución para recuperar otra columna de la misma fila si se utiliza la función PDOStatement::fetchColumn() para obtener los datos.

### Errores/Excepciones

Emite un error de nivel `E_WARNING` si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_WARNING`.

Lanza una excepción PDOException si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_EXCEPTION`.

### Ejemplos

Ejemplo #1 Devuelve la primera columna de la siguiente fila

    <?php
    $sth = $dbh->prepare("SELECT nom, couleur FROM fruit");
    $sth->execute();

    /* Recupera la primera columna de la primera fila de un conjunto de resultados */
    print "Recupera la primera columna de la primera fila de un conjunto de resultados :\n";
    $result = $sth->fetchColumn();
    print "nom=$result\n");

    print "Recupera la segunda columna de la segunda fila de un conjunto de resultados :\n";
    $result = $sth->fetchColumn(1);
    print "couleur=$result\n";
    ?>

El ejemplo anterior mostrará:

    Recupera la primera columna de la primera fila de un conjunto de resultados :
    nom=lemon
    Recupera la segunda columna de la segunda fila de un conjunto de resultados :
    couleur=orange

### Ver también

- PDO::query() - Prepara y ejecuta una consulta SQL sin marcadores de sustitución
- PDOStatement::fetch() - Recupera la siguiente línea de un conjunto de resultados PDO
- PDOStatement::fetchAll() - Recupera las líneas restantes de un conjunto de resultados
- PDO::prepare() - Prepara una consulta para su ejecución y devuelve un objeto
- PDOStatement::setFetchMode() - Establece el modo de recuperación por defecto para esta consulta

# PDOStatement::fetchObject

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.4)

PDOStatement::fetchObject — Recupera la siguiente línea y la devuelve como objeto

### Descripción

public function PDOStatement::fetchObject(?string `$class` = "stdClass", array `$constructorArgs` = []): object|false

Recupera la siguiente línea y la devuelve como objeto. Esta función es una alternativa a PDOStatement::fetch() con `PDO::FETCH_CLASS` o el estilo `PDO::FETCH_OBJ`.

Cuando se recupera un objeto, sus propiedades son asignadas a partir de los valores de columna respectivos, y luego se llama a su constructor.

### Parámetros

`class`

  Nombre de la clase creada.

`constructorArgs`

  Los elementos de este array son pasados al constructor.

### Valores devueltos

Devuelve una instancia de la clase solicitada con propiedades de nombres que corresponden a los nombres de las columnas o `false` si ocurre un error.

### Errores/Excepciones

Emite un error de nivel `E_WARNING` si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_WARNING`.

Lanza una excepción PDOException si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_EXCEPTION`.

### Ver también

- PDOStatement::fetch() - Recupera la siguiente línea de un conjunto de resultados PDO

# PDOStatement::getAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::getAttribute — Recupera un atributo de consulta

### Descripción

public function PDOStatement::getAttribute(int `$name`): mixed

Recupera un atributo de la consulta. Actualmente, no existen atributos genéricos, sino especificaciones del driver:

- `PDO::ATTR_CURSOR_NAME` (especificación de Firebird y ODBC): Recupera el nombre del cursor para `UPDATE ... WHERE CURRENT OF`.

Tenga en cuenta que los atributos específicos del controlador no deben utilizarse con otros controladores.

### Parámetros

`name`

  El atributo a consultar.

### Valores devueltos

Devuelve el valor del atributo.

### Ver también

- PDO::getAttribute() - Recupera un atributo de una conexión a una base de datos
- PDO::setAttribute() - Configura un atributo PDO
- PDOStatement::setAttribute() - Establece un atributo de consulta

# PDOStatement::getColumnMeta

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::getColumnMeta — Devuelve las metadatos para una columna de un conjunto de resultados

### Descripción

public function PDOStatement::getColumnMeta(int `$column`): array|false

Recupera las metadatos para una columna de un conjunto de resultados en un array asociativo.

Advertencia

Algunos controladores pueden no implementar la función PDOStatement::getColumnMeta(), ya que es opcional. Sin embargo, todos los controladores PDO documentados en el manual implementan esta función.

### Parámetros

`column`

  El nombre de la columna en el conjunto de resultados.

### Valores devueltos

Devuelve un array asociativo que contiene los siguientes valores representando las metadatos para una columna:

Metadatos de una columna
Nombre | Valor
--- | ---
`native_type` | El tipo nativo de PHP utilizado para representar el valor de la columna.
`driver:decl_type` | El tipo SQL utilizado para representar el valor de la columna en la base de datos. Si la columna del conjunto de resultados es el resultado de una función, este valor no es devuelto por la función PDOStatement::getColumnMeta().
`flags` | Cualquier flag definido para esta columna.
`name` | El nombre de esta columna, como es devuelto por la base de datos.
`table` | El nombre de la tabla de esta columna, tal como es devuelto por la base de datos.
`len` | La longitud de esta columna. Normalmente, `-1` para tipos distintos a los números decimales de punto flotante.
`precision` | La precisión numérica para esta columna. Normalmente, `0` para tipos distintos a los números decimales de punto flotante.
`pdo_type` | El tipo de esta columna como es representado por la constante `PDO::PARAM_*`.

Devuelve `false` si la columna solicitada no existe en el conjunto de resultados, o si no existe ningún conjunto de resultados.

### Ejemplos

Ejemplo #1 Recuperación de las metadatos para una columna

El siguiente ejemplo muestra el resultado de la recuperación de las metadatos para una columna generada por una función (COUNT) en un controlador PDO_SQLITE.

    <?php
    $select = $DB->query('SELECT COUNT(*) FROM fruit');
    $meta = $select->getColumnMeta(0);
    var_dump($meta);
    ?>

El ejemplo anterior mostrará:

    array(6) {
       ["native_type"]=>
       string(7) "integer"
       ["flags"]=>
          array(0) {
          }
       ["name"]=>
       string(8) "COUNT(*)"
       ["len"]=>
       int(-1)
       ["precision"]=>
       int(0)
       ["pdo_type"]=>
       int(2)
    }

### Ver también

- PDOStatement::columnCount() - Devuelve el número de columnas en el conjunto de resultados
- PDOStatement::rowCount() - Devuelve el número de filas afectadas por la última llamada a la función PDOStatement::execute()

# PDOStatement::getIterator

(PHP 8)

PDOStatement::getIterator — Devuelve un iterador sobre el conjunto de resultados

### Descripción

public function PDOStatement::getIterator(): Iterator

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# PDOStatement::nextRowset

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::nextRowset — Avance al siguiente conjunto de resultados de un manejador de conjuntos de resultados múltiples

### Descripción

public function PDOStatement::nextRowset(): bool

Algunas bases de datos soportan procedimientos almacenados que retornan más de un conjunto de resultados (también conocido como juegos de resultados). PDOStatement::nextRowset() permite acceder al segundo y siguientes conjuntos de resultados asociados con el objeto PDOStatement. Cada conjunto de resultados tiene diferentes juegos de columnas desde el conjunto de resultados.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Recuperación de múltiples conjuntos de resultados retornados por un procedimiento almacenado

El siguiente ejemplo muestra cómo llamar a un procedimiento almacenado, `MULTIPLE_ROWSETS`, que retorna tres conjuntos de resultados. Un ciclo do-while es utilizado para recorrer el método PDOStatement::nextRowset(), que retorna `false` y termina el ciclo cuando no hay más conjuntos de resultados disponibles.

    <?php
    $sql = 'CALL multiple_rowsets()';
    $stmt = $conn->query($sql);
    $i = 1;
    do {
        $rowset = $stmt->fetchAll(PDO::FETCH_NUM);
        if ($rowset) {
            printResultSet($rowset, $i);
        }
        $i++;
    } while ($stmt->nextRowset());

    function printResultSet(&$rowset, $i) {
        print "Conjunto de resultados $i:\n";
        foreach ($rowset as $row) {
            foreach ($row as $col) {
                print $col . "\t";
            }
            print "\n";
        }
        print "\n";
    }
    ?>

El ejemplo anterior mostrará:

    Conjunto de resultados 1:
    apple    red
    banana   yellow

    Conjunto de resultados 2:
    orange   orange    150
    banana   yellow    175

    Conjunto de resultados 3:
    lime     green
    apple    red
    banana   yellow

### Ver también

- PDOStatement::columnCount() - Devuelve el número de columnas en el conjunto de resultados
- PDOStatement::execute() - Ejecuta una consulta preparada
- PDOStatement::getColumnMeta() - Devuelve las metadatos para una columna de un conjunto de resultados
- PDO::query() - Prepara y ejecuta una consulta SQL sin marcadores de sustitución

# PDOStatement::rowCount

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::rowCount — Devuelve el número de filas afectadas por la última llamada a la función PDOStatement::execute()

### Descripción

public function PDOStatement::rowCount(): int

PDOStatement::rowCount() devuelve el número de filas afectadas por la última consulta DELETE, INSERT o UPDATE ejecutada por el objeto `PDOStatement` correspondiente.

Si la última consulta SQL ejecutada por el objeto `PDOStatement` asociado es una consulta de tipo SELECT, algunas bases de datos devolverán el número de filas devueltas por dicha consulta. No obstante, este comportamiento no está garantizado para todas las bases de datos y no debería ser utilizado para aplicaciones portables.

> Nota:

> Este método siempre devuelve "0" (cero) con el controlador PostgreSQL, cuando el atributo de declaración `PDO::ATTR_CURSOR` está definido como `PDO::CURSOR_SCROLL`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de filas.

### Errores/Excepciones

Emite un error de nivel `E_WARNING` si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_WARNING`.

Lanza una excepción PDOException si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_EXCEPTION`.

### Ejemplos

Ejemplo #1 Devuelve el número de filas eliminadas

PDOStatement::rowCount() devuelve el número de filas afectadas por una consulta DELETE, INSERT, o UPDATE.

    <?php
    /* Eliminación de todas las filas de la tabla FRUIT */
    $del = $dbh->prepare('DELETE FROM fruit');
    $del->execute();

    /* Devuelve el número de filas eliminadas */
    print "Devuelve el número de filas eliminadas :\n";
    $count = $del->rowCount();
    print "Eliminación de $count filas.\n";
    ?>

Resultado del ejemplo anterior es similar a:

    Devuelve el número de filas eliminadas :
    Eliminación de 9 filas.

Ejemplo #2 Conteo de filas devueltas por una consulta SELECT

Para la mayoría de las bases de datos, PDOStatement::rowCount() no devuelve el número de filas afectadas por una consulta SELECT. En su lugar, utilice PDO::query() para hacer una consulta SELECT COUNT(*), luego utilice PDOStatement::fetchColumn() para recuperar el número de filas correspondientes.

    <?php
    $sql = "SELECT COUNT(*) FROM fruit WHERE calories > 100";
    $res = $conn->query($sql);
    $count = $res->fetchColumn();

    print "Hay " .  $count . " fila(s) correspondiente(s).";
    ?>

Resultado del ejemplo anterior es similar a:

    Hay  2 fila(s) correspondiente(s).

### Ver también

- PDOStatement::columnCount() - Devuelve el número de columnas en el conjunto de resultados
- PDOStatement::fetchColumn() - Devuelve una columna de la siguiente fila de un conjunto de resultados
- PDO::query() - Prepara y ejecuta una consulta SQL sin marcadores de sustitución

# PDOStatement::setAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::setAttribute — Establece un atributo de consulta

### Descripción

public function PDOStatement::setAttribute(int `$attribute`, mixed `$value`): bool

Establece un atributo de la consulta. Actualmente, no se definen atributos genéricos, sino especificaciones del driver:

- `PDO::ATTR_CURSOR_NAME` (especificidad de Firebird y ODBC): Establece el nombre del cursor para `UPDATE ... WHERE CURRENT OF`.

Tenga en cuenta que los atributos específicos del controlador no deben utilizarse con otros controladores.

### Parámetros

`attribute`

  El atributo a modificar.

`value`

  El valor para establecer el `attribute`, puede requerir un tipo específico según el atributo.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- PDO::getAttribute() - Recupera un atributo de una conexión a una base de datos
- PDO::setAttribute() - Configura un atributo PDO
- PDOStatement::getAttribute() - Recupera un atributo de consulta

# PDOStatement::setFetchMode

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::setFetchMode — Establece el modo de recuperación por defecto para esta consulta

### Descripción

public function PDOStatement::setFetchMode(int `$mode`): true
public function PDOStatement::setFetchMode(int `$mode` = PDO::FETCH_COLUMN, int `$colno`): true
public function PDOStatement::setFetchMode(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs` = `null`): true
public function PDOStatement::setFetchMode(int `$mode` = PDO::FETCH_INTO, object `$object`): true

### Parámetros

`mode`

  El modo de recuperación debe ser una de las constantes `PDO::FETCH_*`.

`colno`

  Número de la columna.

`class`

  Nombre de la clase.

`constructorArgs`

  Argumentos del constructor.

`object`

  Objeto.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | El tipo de retorno es ahora `true`, anteriormente era bool.

### Ejemplos

Ejemplo #1 Definición del modo de recuperación

El siguiente ejemplo muestra cómo PDOStatement::setFetchMode() modifica el modo de recuperación por defecto para un objeto PDOStatement.

    <?php
    $stmt = $dbh->query('SELECT name, colour, calories FROM fruit');
    $stmt->setFetchMode(PDO::FETCH_NUM);
    foreach ($stmt as $row) {
        print $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
    }
    ?>

Resultado del ejemplo anterior es similar a:

    apple   red     150
    banana  yellow  250
    orange  orange  300
    kiwi    brown   75
    lemon   yellow  25
    pear    green   150

## Tabla de contenidos

- PDOStatement::bindColumn — Vincula una columna a una variable PHP
- PDOStatement::bindParam — Vincula un parámetro a una variable específica
- PDOStatement::bindValue — Asocia un valor a un parámetro
- PDOStatement::closeCursor — Cierra el cursor, permitiendo que la consulta pueda ser ejecutada de nuevo
- PDOStatement::columnCount — Devuelve el número de columnas en el conjunto de resultados
- PDOStatement::debugDumpParams — Detalla una instrucción SQL preparada
- PDOStatement::errorCode — Recupera las informaciones sobre el error asociado durante la última operación sobre la consulta
- PDOStatement::errorInfo — Recupera las informaciones sobre el error asociado durante la última operación sobre la consulta
- PDOStatement::execute — Ejecuta una consulta preparada
- PDOStatement::fetch — Recupera la siguiente línea de un conjunto de resultados PDO
- PDOStatement::fetchAll — Recupera las líneas restantes de un conjunto de resultados
- PDOStatement::fetchColumn — Devuelve una columna de la siguiente fila de un conjunto de resultados
- PDOStatement::fetchObject — Recupera la siguiente línea y la devuelve como objeto
- PDOStatement::getAttribute — Recupera un atributo de consulta
- PDOStatement::getColumnMeta — Devuelve las metadatos para una columna de un conjunto de resultados
- PDOStatement::getIterator — Devuelve un iterador sobre el conjunto de resultados
- PDOStatement::nextRowset — Avance al siguiente conjunto de resultados de un manejador de conjuntos de resultados múltiples
- PDOStatement::rowCount — Devuelve el número de filas afectadas por la última llamada a la función PDOStatement::execute()
- PDOStatement::setAttribute — Establece un atributo de consulta
- PDOStatement::setFetchMode — Establece el modo de recuperación por defecto para esta consulta

# La clase PDORow

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.0)

## Introducción

Representa una línea de un conjunto de resultados devuelto por PDOStatement::fetch() llamado con el modo de recuperación `PDO::FETCH_LAZY`.

Los objetos de esta clase no pueden ser instanciados y no son serializables.

La clase PDORow permite acceder a los datos devueltos como si los modos `PDO::FETCH_OBJ` y `PDO::FETCH_BOTH` fueran utilizados. Esto significa que los datos devueltos pueden ser accedidos como propiedades de objeto, y como un array indexado por el nombre de la columna y un número de posición de columna.

Precaución

Acceder a una propiedad no definida devuelve `null` sin emitir un mensaje de advertencia.

## Sinopsis de la Clase

final class PDORow {
/* Propiedades */
public string $queryString;
}

## Propiedades

queryString

  La consulta utilizada por PDOStatement que ha devuelto el objeto PDORow.

## Errores/Excepciones

Genera un error de tipo Error cuando se intenta escribir o unset() una propiedad.

# La clase PDOException

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## Introducción

Representa un error emitido por PDO. No debe lanzarse una excepción PDOException desde el propio código. Ver el capítulo sobre las excepciones para obtener más información sobre las excepciones en PHP.

## Sinopsis de la Clase

class PDOException extends RuntimeException {
/* Propiedades */
protected int|string $code;
public ?array $errorInfo = null;
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propiedades

errorInfo

  Corresponde a PDO::errorInfo() o PDOStatement::errorInfo()

code

  Código de error `SQLSTATE`. Utilice el método Exception::getCode() para acceder a él.

# Controladores PDO

## Tabla de contenidos

- Controlador PDO CUBRID
- Controlador PDO MS SQL Server
- Pdo\Dblib
- Controlador PDO Firebird
- Pdo\Firebird
- Controlador PDO IBM
- Controlador PDO Informix
- Controlador PDO MySQL
- Pdo\Mysql
- Controlador PDO MS SQL Server
- Controlador PDO Oracle
- Controladores PDO ODBC y DB2
- Pdo\Odbc
- Controlador PDO PostgreSQL
- Pdo\Pgsql
- Controlador PDO SQLite
- Pdo\Sqlite

Los siguientes controladores están actualmente implementados en la interfaz PDO:

Nombre del controlador | Bases de datos soportadas
--- | ---
PDO_CUBRID | Cubrid
PDO_DBLIB | FreeTDS / Microsoft SQL Server / Sybase
PDO_FIREBIRD | Firebird
PDO_IBM | IBM DB2
PDO_INFORMIX | IBM Informix Dynamic Server
PDO_MYSQL | MySQL 3.x/4.x/5.x/8.x
PDO_OCI | Oracle Call Interface
PDO_ODBC | ODBC v3 (IBM DB2, unixODBC y win32 ODBC)
PDO_PGSQL | PostgreSQL
PDO_SQLITE | SQLite 3 y SQLite 2
PDO_SQLSRV | Microsoft SQL Server / SQL Azure

# Funciones del controlador PDO CUBRID (PDO_CUBRID)

## Introducción

PDO_CUBRID es un controlador que implementa la interfaz PHP Data Objects (PDO) para permitir el acceso desde PHP a las bases de datos CUBRID.

> Nota: La versión actual de PDO_CUBRID no soporta la conexión persistente en este momento.

## Instalación

Para construir la extensión PDO_CUBRID, el sistema de gestión de bases de datos CUBRID debe estar instalado en el mismo sistema que PHP. PDO_CUBRID es una extensión » PECL, por lo tanto, debe seguirse las instrucciones de Instalación de extensiones PECL para instalar la extensión PDO_CUBRID. Ejecute el comando configure para localizar el directorio base de CUBRID de la siguiente manera:

       $ ./configure --with-pdo-cubrid=/path/to/CUBRID[,shared]

El comando configure tomará por omisión el valor de la variable de entorno CUBRID.

No hay biblioteca DLL para esta extensión PECL actualmente disponible. Consulte la sección Compilación en Windows. Información sobre la instalación manual en Linux y Windows puede encontrarse en el archivo build-guide.html del paquete CUBRID de PECL.

## Características de PDO_CUBRID

## Cursores desplazables

PDO_CUBRID soporta los cursores desplazables. El tipo de cursor por omisión es de solo avance, y se puede utilizar el argumento driver_options en PDO::prepare() para cambiar el tipo de cursor.

## Tiempo límite

PDO_CUBRID soporta la configuración del tiempo límite de ejecución de la instrucción SQL; se puede utilizar PDO::setAttribute() para definir el valor del tiempo límite.

## Modo autocommit y transacción

PDO_CUBRID soporta tanto el modo autocommit como la transacción, y el modo autocommit está activado por omisión. Se puede utilizar PDO::setAttribute() para cambiar su estado.

Si se utiliza PDO::beginTransaction() para comenzar una transacción, esto desactivará automáticamente el modo autocommit y lo restaurará después de PDO::commit() o PDO::rollBack().

> Nota: Antes de desactivar el modo autocommit, todo trabajo pendiente es validado automáticamente.

## Instrucciones SQL múltiples

PDO_CUBRID soporta las instrucciones SQL múltiples. Las instrucciones SQL múltiples están separadas por puntos y coma (`;`).

## Información sobre el esquema

PDO_CUBRID implementa PDO::cubrid_schema() para obtener información sobre el esquema.

## LOBs

PDO_CUBRID soporta los tipos de datos BLOB/CLOB. El LOB en PDO es representado como un flujo, por lo que se pueden insertar LOBs vinculando un flujo, y obtener LOBs leyendo un flujo devuelto por CUBRID PDO. Por ejemplo:

Ejemplo #1 Insertar LOBs en CUBRID PDO

    <?php
    $fp = fopen('lob_test.png', 'rb');

    $sql_stmt = "INSERT INTO lob_test(name, content) VALUES('lob_test.png', ?)";

    $stmt = $dbh->prepare($sql_stmt);
    $ret = $stmt->bindParam(1, $fp, PDO::PARAM_LOB);
    $ret = $stmt->execute();
    ?>

Ejemplo #2 Recuperar LOBs en CUBRID PDO

    <?php
    $sql_stmt = "SELECT content FROM lob_test WHERE name='lob_test.png'";

    $stmt = $dbh->prepare($sql_stmt);
    $stmt->execute();
    $result = $stmt->fetch(PDO::FETCH_NUM);

    header("Content-Type: image/png");
    fpassthru($result[0]);
    ?>

## Meta-columna

El método PDOStatement::getColumnMeta() en CUBRID PDO devolverá un array asociativo que contiene los siguientes valores:

- type
- name
- table
- def
- precision
- scale
- not_null
- auto_increment
- unique_key
- multiple_key
- primary_key
- foreign_key
- reverse_index
- reverse_unique

## Tipo de datos Colección

PDO_CUBRID soporta los tipos de datos SET/MULTISET/SEQUENCE. Si no se especifica el tipo de datos, el tipo de datos por omisión es char. Por ejemplo:

Ejemplo #3 Insertar un conjunto en CUBRID PDO con el tipo de datos por omisión.

    <?php
    $conn_str ="cubrid:dbname=demodb;host=localhost;port=33000";
    $cubrid_pdo = new PDO($conn_str, 'dba', '');

    $cubrid_pdo->exec("DROP TABLE if exists test_tbl");
    $cubrid_pdo->exec("CREATE TABLE test_tbl (col_1 SET(VARCHAR))");

    $sql_stmt_insert = "INSERT INTO test_tbl VALUES (?);";
    $stmt = $cubrid_pdo->prepare($sql_stmt_insert);
    $data = array("abc","def","ghi");
    $ret = $stmt->bindParam(1, $data, PDO::PARAM_NULL);
    $ret = $stmt->execute();
    var_Dump($ret);
    ?>

Ejemplo #4 Especificar el tipo de datos al insertar un conjunto en CUBRID PDO

    <?php
    $conn_str ="cubrid:dbname=demodb;host=localhost;port=33000";
    $cubrid_pdo = new PDO($conn_str, 'dba', '');

    $cubrid_pdo->exec("DROP TABLE if exists test_tbl");
    $cubrid_pdo->exec("CREATE TABLE test_tbl (col_1 SET(int))");

    $sql_stmt_insert = "INSERT INTO test_tbl VALUES (?);";
    $stmt = $cubrid_pdo->prepare($sql_stmt_insert);
    $data = array(1,2,3,4);
    $ret = $stmt->bindParam(1, $data, 0,0,"int");
    $ret = $stmt->execute();
    var_Dump($ret);
    ?>

Tipos de datos de enlace CUBRID para el quinto argumento de PDOStatement::bindParam():

- CHAR
- STRING
- NCHAR
- VARNCHAR
- BIT
- VARBIT
- NUMERIC
- NUMBER
- INT
- SHORT
- BIGINT
- MONETARY
- FLOAT
- DOUBLE
- DATE
- TIME
- DATETIME
- TIMESTAMP

## Constantes predefinidas

Las constantes a continuación son definidas por este controlador y solo estarán disponibles cuando la extensión haya sido compilada en PHP o cargada dinámicamente del motor de ejecución. Además, estas constantes específicas del controlador deberían ser usadas solo si se usa este controlador. Usar atributos específicos de un controlador con otro controlador podría causar un comportamiento inesperado. PDO::getAttribute() podría ser usado para obtener el atributo `PDO::ATTR_DRIVER_NAME` para verificar el controlador, si su código puede funcionar en múltiples controladores.

Las constantes siguientes pueden ser utilizadas para configurar los atributos de la base de datos. Pueden ser pasadas al método PDO::getAttribute() o al método PDO::setAttribute().

Banderas para los atributos PDO::CUBRID
Constante | Descripción
--- | ---
`PDO::CUBRID_ATTR_ISOLATION_LEVEL` | El nivel de aislamiento de la transacción para la conexión a la base de datos.
`PDO::CUBRID_ATTR_LOCK_TIMEOUT` | Tiempo de expiración de la transacción en segundos.
`PDO::CUBRID_ATTR_MAX_STRING_LENGTH` | Solo lectura. La longitud máxima del string para los tipos de datos bit, varbit, char, varchar, nchar, nvarchar al utilizar la API CUBRID PDO.

Las constantes siguientes pueden ser utilizadas al configurar el nivel de aislamiento de la transacción. Pueden ser pasadas al método PDO::getAttribute() o al método PDO::setAttribute().

Banderas para el nivel de aislamiento PDO::CUBRID
Constante | Descripción
--- | ---
`PDO::TRAN_COMMIT_CLASS_UNCOMMIT_INSTANCE` | El nivel de aislamiento más bajo (1). Una lectura no fiable, no reproducible o fantasma puede ocurrir sobre el tuple, pero también una lectura no reproducible puede ocurrir para la tabla.
`PDO::TRAN_COMMIT_CLASS_COMMIT_INSTANCE` | Un nivel de aislamiento relativamente bajo (2). Una lectura no fiable no puede ocurrir, pero una lectura no reproducible o fantasma puede ocurrir.
`PDO::TRAN_REP_CLASS_UNCOMMIT_INSTANCE` | El nivel de aislamiento por defecto para CUBRID (3). Una lectura no fiable o fantasma puede ocurrir sobre el tuple, pero la reproducibilidad de la lectura está asegurada sobre la tabla.
`PDO::TRAN_REP_CLASS_COMMIT_INSTANCE` | Un nivel de aislamiento relativamente bajo (4). Una lectura no fiable no puede ocurrir, pero las lecturas no reproducibles o fantasma pueden ocurrir.
`PDO::TRAN_REP_CLASS_REP_INSTANCE` | Un nivel de aislamiento relativamente alto (5). Las lecturas no fiables o no reproducibles no pueden ocurrir, pero una lectura fantasma es posible.
`PDO::TRAN_SERIALIZABLE` | El nivel de aislamiento más alto (6). Los problemas relacionados con la concurrencia (i.e. lectura no fiable, lectura no reproducible, lectura fantasma, etc...) no pueden ocurrir.

Las constantes siguientes pueden ser utilizadas para recuperar la información sobre el esquema. Pueden ser pasadas a la función PDO::cubrid_schema().

Banderas para el esquema CUBRID
Constante | Descripción
--- | ---
`PDO::CUBRID_SCH_TABLE` | Recupera el nombre y el tipo de tabla CUBRID.
`PDO::CUBRID_SCH_VIEW` | Recupera el nombre y el tipo de vista en CUBRID.
`PDO::CUBRID_SCH_QUERY_SPEC` | Recupera la definición de la consulta de la vista.
`PDO::CUBRID_SCH_ATTRIBUTE` | Recupera los atributos de la columna de la tabla.
`PDO::CUBRID_SCH_TABLE_ATTRIBUTE` | Recupera los atributos de la tabla.
`PDO::CUBRID_SCH_METHOD` | Recupera el método de la instancia. Es un método llamado por la instancia de la clase. Se utiliza más a menudo que el método de la clase ya que la mayoría de las operaciones se ejecutan en la instancia.
`PDO::CUBRID_SCH_TABLE_METHOD` | Recupera el método de la clase. Es un método llamado por un objeto de la clase. Se utiliza habitualmente para crear una nueva instancia de la clase o para inicializarla. También se utiliza para acceder o actualizar los atributos de la clase.
`PDO::CUBRID_SCH_METHOD_FILE` | Recupera la información sobre el archivo donde el método de la tabla está definido.
`PDO::CUBRID_SCH_SUPER_TABLE` | Recupera el nombre y el tipo de la tabla de la que los atributos heredan.
`PDO::CUBRID_SCH_SUB_TABLE` | Recupera el nombre y el tipo de la tabla de la que los atributos heredan.
`PDO::CUBRID_SCH_CONSTRAINT` | Recupera las restricciones de la tabla.
`PDO::CUBRID_SCH_TRIGGER` | Recupera los triggers de la tabla.
`PDO::CUBRID_SCH_TABLE_PRIVILEGE` | Recupera la información sobre los privilegios de la tabla.
`PDO::CUBRID_SCH_COL_PRIVILEGE` | Recupera la información sobre los privilegios de una columna.
`PDO::CUBRID_SCH_DIRECT_SUPER_TABLE` | Recupera la tabla directamente superior a la tabla.
`PDO::CUBRID_SCH_PRIMARY_KEY` | Recupera la clave primaria de la tabla.
`PDO::CUBRID_SCH_IMPORTED_KEYS` | Recupera las claves importadas de una tabla.
`PDO::CUBRID_SCH_EXPORTED_KEYS` | Recupera las claves exportadas de una tabla.
`PDO::CUBRID_SCH_CROSS_REFERENCE` | Recupera las relaciones de referencia entre 2 tablas.

# DSN PDO_CUBRID

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

DSN PDO_CUBRID — Conexión a las bases de datos CUBRID

### Descripción

El DSN PDO_CUBRID está compuesto por los siguientes elementos, delimitados por un punto y coma:

prefijo DSN

  El prefijo DSN es `cubrid:`.

`host`
  El nombre de host donde se encuentra el servidor de base de datos.
`port`
  El puerto en el que funciona el servidor de base de datos.
`dbname`
  El nombre de la base de datos.

### Notas

> Nota: Al establecer la conexión a CUBRID, se debe proporcionar el nombre de usuario y la contraseña, pero no el DSN.

### Ejemplos

Ejemplo #1 Ejemplos de DSN PDO_CUBRID

El siguiente ejemplo muestra un DSN PDO_CUBRID para una conexión a una base de datos CUBRID:

    cubrid:host=localhost;port=33000;dbname=demodb

# PDO::cubrid_schema

(PECL PDO_CUBRID >= 8.3.0.0001)

PDO::cubrid_schema — Recupera el esquema de información solicitado

### Descripción

public function PDO::cubrid_schema(int `$schema_type`, string `$table_name` = ?, string `$col_name` = ?): array

Esta función se utiliza para recuperar el esquema de información solicitado desde la base de datos. Debe designarse el argumento `table_name`, si se desea recuperar las informaciones de una cierta tabla, el argumento `col_name`, si se desea recuperar las informaciones de una cierta columna (solo puede ser utilizado con PDO::CUBRID_SCH_COL_PRIVILEGE).

El resultado de esta función es devuelto en forma de un array de 2 dimensiones (columna(array asociativo) * fila (array numérico)). Las tablas siguientes muestran los tipos de esquema y la estructura de la columna del array resultante.

Composición del resultado para cada tipo
Esquema | Número de la columna | Nombre de la columna | Valor
--- | --- | --- | ---
PDO::CUBRID_SCH_TABLE | 1 | NAME |
| 2 | TYPE | 0:tabla del sistema 1:vista 2:tabla
PDO::CUBRID_SCH_VIEW | 1 | NAME |
| 2 | TYPE | 1:vista
PDO::CUBRID_SCH_QUERY_SPEC | 1 | QUERY_SPEC |
PDO::CUBRID_SCH_ATTRIBUTE / PDO::CUBRID_SCH_TABLE_ATTRIBUTE | 1 | ATTR_NAME |
| 2 | DOMAIN |
| 3 | SCALE |
| 4 | PRECISION |
| 5 | INDEXED | 1:indexado
| 6 | NOT NULL | 1:no nulo
| 7 | SHARED | 1:compartido
| 8 | UNIQUE | 1:único
| 9 | DEFAULT |
| 10 | ATTR_ORDER | base:1
| 11 | CLASS_NAME |
| 12 | SOURCE_CLASS |
| 13 | IS_KEY | 1:clave
PDO::CUBRID_SCH_METHOD / PDO::CUBRID_SCH_TABLE_METHOD | 1 | NAME |
| 2 | RET_DOMAIN |
| 3 | ARG_DOMAIN |
PDO::CUBRID_SCH_METHOD_FILE | 1 | METHOD_FILE |
PDO::CUBRID_SCH_SUPER_TABLE / PDO::CUBRID_SCH_DIRECT_SUPER_TABLE / PDO::CUBRID_SCH_SUB_TABLE | 1 | CLASS_NAME |
| 2 | TYPE | 0:tabla del sistema 1:vista 2:tabla
PDO::CUBRID_SCH_CONSTRAINT | 1 | TYPE | 0:único 1:índice 2:único inverso 3:índice inverso
| 2 | NAME |
| 3 | ATTR_NAME |
| 4 | NUM_PAGES |
| 5 | NUM_KEYS |
| 6 | PRIMARY_KEY | 1:clave primaria
| 7 | KEY_ORDER | base:1
PDO::CUBRID_SCH_TRIGGER | 1 | NAME |
| 2 | STATUS |
| 3 | EVENT |
| 4 | TARGET_CLASS |
| 5 | TARGET_ATTR |
| 6 | ACTION_TIME |
| 7 | ACTION |
| 8 | PRIORITY |
| 9 | CONDITION_TIME |
| 10 | CONDITION |
PDO::CUBRID_SCH_TABLE_PRIVILEGE / PDO::CUBRID_SCH_COL_PRIVILEGE | 1 | CLASS_NAME / ATTR_NAME |
| 2 | PRIVILEGE |
| 3 | GRANTABLE |
PDO::CUBRID_SCH_PRIMARY_KEY | 1 | CLASS_NAME |
| 2 | ATTR_NAME |
| 3 | KEY_SEQ | base:1
| 4 | KEY_NAME |
PDO::CUBRID_SCH_IMPORTED_KEYS / PDO::CUBRID_SCH_EXPORTED_KEYS / PDO::CUBRID_SCH_CROSS_REFERENCE | 1 | PKTABLE_NAME |
| 2 | PKCOLUMN_NAME |
| 3 | FKTABLE_NAME | base:1
| 4 | FKCOLUMN_NAME |
| 5 | KEY_SEQ | base:1
| 6 | UPDATE_ACTION | 0:cascada 1:restringir 2:sin acción 3:establecer nulo
| 7 | DELETE_ACTION | 0:cascada 1:restringir 2:sin acción 3:establecer nulo
| 8 | FK_NAME |
| 9 | PK_NAME |

### Parámetros

`schema_type`
  El tipo de esquema que se desea recuperar.
`table_name`
  La tabla de la cual se desea recuperar el esquema.
`col_name`
  La columna de la cual se desea recuperar el esquema.

### Valores devueltos

Un array que contiene las informaciones relativas al esquema, cuando el proceso se ha ejecutado con éxito.

FALSE será devuelto si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con PDO::cubrid_schema()

Este ejemplo muestra cómo recuperar las claves primarias y extranjeras de la tabla "game".

    <?php
    $pk_list = $dbh->cubrid_schema(PDO::CUBRID_SCH_PRIMARY_KEY, "game");
    print_r($pk_list);

    $fk_list = $dbh->cubrid_schema(PDO::CUBRID_SCH_IMPORTED_KEYS, "game");
    print_r($fk_list);
    ?>

El ejemplo anterior mostrará:

    Resultado:
    Array
    (
        [0] => Array
            (
                [CLASS_NAME] => game
                [ATTR_NAME] => athlete_code
                [KEY_SEQ] => 3
                [KEY_NAME] => pk_game_host_year_event_code_athlete_code
            )

        [1] => Array
            (
                [CLASS_NAME] => game
                [ATTR_NAME] => event_code
                [KEY_SEQ] => 2
                [KEY_NAME] => pk_game_host_year_event_code_athlete_code
            )

        [2] => Array
            (
                [CLASS_NAME] => game
                [ATTR_NAME] => host_year
                [KEY_SEQ] => 1
                [KEY_NAME] => pk_game_host_year_event_code_athlete_code
            )

    )
    Array
    (
        [0] => Array
            (
                [PKTABLE_NAME] => athlete
                [PKCOLUMN_NAME] => code
                [FKTABLE_NAME] => game
                [FKCOLUMN_NAME] => athlete_code
                [KEY_SEQ] => 1
                [UPDATE_RULE] => 1
                [DELETE_RULE] => 1
                [FK_NAME] => fk_game_athlete_code
                [PK_NAME] => pk_athlete_code
            )

        [1] => Array
            (
                [PKTABLE_NAME] => event
                [PKCOLUMN_NAME] => code
                [FKTABLE_NAME] => game
                [FKCOLUMN_NAME] => event_code
                [KEY_SEQ] => 1
                [UPDATE_RULE] => 1
                [DELETE_RULE] => 1
                [FK_NAME] => fk_game_event_code
                [PK_NAME] => pk_event_code
            )

    )

## Tabla de contenidos

- DSN PDO_CUBRID — Conexión a las bases de datos CUBRID
- PDO::cubrid_schema — Recupera el esquema de información solicitado

# Microsoft SQL Server y Funciones del Controlador PDO Sybase (PDO_DBLIB)

## Introducción

PDO_DBLIB es un controlador que implementa la interfaz de PHP Data Objects (PDO) para permitir el acceso de PHP a Microsoft SQL Server y bases de datos Sybase mediante la biblioteca FreeTDS.

Esta extensión ya no está disponible en Windows.

En Windows, se debe utilizar SqlSrv, un controlador alternativo para MS SQL disponible en Microsoft : » http://msdn.microsoft.com/en-us/sqlserver/ff657782.aspx .

Si no es posible utilizar SqlSrv, puede emplearse el controlador PDO_ODBC para conectarse a un servidor de bases de datos Microsoft SQL y Sybase, teniendo en cuenta que el controlador nativo de Windows DB-LIB es antiguo, no seguro a nivel de hilos y ya no es soportado por Microsoft.

# PDO_DBLIB DSN

(PECL PDO_DBLIB >= 0.9.0)

PDO_DBLIB DSN — Conexión al Servidor Microsoft SQL y bases de datos Sybase

### Descripción

El Data Source Name (DSN) de PDO_DBLIB se compone de los siguientes elementos:

Prefijo DSN

  El prefijo DSN es `sybase:` si PDO_DBLIB fue vinculado con las bibliotecas Sybase ct-lib, `mssql:` si PDO_DBLIB fue vinculado con las bibliotecas de Microsoft SQL Server, o `dblib:` si PDO_DBLIB fue vinculado con las bibliotecas FreeTDS.

`host`

  El host donde se encuentra el servidor de base de datos.

`dbname`

  El nombre de la base de datos.

`charset`

  El juego de caracteres del cliente.

`appname`

  El nombre de la aplicación (utilizado en sysprocesses). Por omisión, "PHP Generic DB-lib" o "PHP freetds".

`secure`

  Actualmente no utilizado.

### Ejemplos

Ejemplo #1 Ejemplos con PDO_DBLIB DSN

Los ejemplos siguientes muestran PDO_DBLIB DSN para conectarse a Microsoft SQL Server y bases de datos Sybase:

    mssql:host=localhost;dbname=testdb
    sybase:host=localhost;dbname=testdb
    dblib:host=localhost;dbname=testdb

## Tabla de contenidos

- PDO_DBLIB DSN — Conexión al Servidor Microsoft SQL y bases de datos Sybase

# La clase Pdo\Dblib

(PHP 8 >= 8.4.0)

## Introducción

Una subclase de PDO que representa una conexión utilizando el controlador PDO DBLib.

## Sinopsis de la Clase

namespace Pdo;
class Dblib extends PDO {
/* Constantes heredadas */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Constantes */
public const int ATTR_CONNECTION_TIMEOUT;
public const int ATTR_QUERY_TIMEOUT;
public const bool ATTR_STRINGIFY_UNIQUEIDENTIFIER;
public const int ATTR_VERSION;
public const int ATTR_TDS_VERSION;
public const int ATTR_SKIP_EMPTY_ROWSETS;
public const bool ATTR_DATETIME_CONVERT;
/* Métodos heredados */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Constantes predefinidas

`Pdo\Dblib::ATTR_CONNECTION_TIMEOUT`
`Pdo\Dblib::ATTR_QUERY_TIMEOUT`
`Pdo\Dblib::ATTR_STRINGIFY_UNIQUEIDENTIFIER`
  A partir de PHP 8.4.0 esta constante es de tipo bool; anteriormente, era de tipo int.
`Pdo\Dblib::ATTR_VERSION`
`Pdo\Dblib::ATTR_TDS_VERSION`
`Pdo\Dblib::ATTR_SKIP_EMPTY_ROWSETS`
`Pdo\Dblib::ATTR_DATETIME_CONVERT`
  Este atributo de conexión controla el formato de las cadenas para los tipos datetime. Cuando es `false`, PDO_DBLIB devolverá un tipo datetime como una cadena en el formato que SQL Server lo devuelve (es decir, `"2017-10-27 10:22:44"`). Cuando es `true`, PDO_DBLIB convertirá el tipo datetime en una cadena utilizando un formato definido por el usuario o por la configuración regional, según se especifica en el archivo locales.conf de FreeTDS. Por defecto, este atributo es `false`. A partir de PHP 8.4.0 esta constante es de tipo bool; anteriormente, era de tipo int.

# Funciones del controlador PDO Firebird (PDO_FIREBIRD)

## Introducción

PDO_FIREBIRD es un controlador que implementa la interfaz de PHP Data Objects (PDO) para permitir el acceso de PHP a las bases de datos Firebird.

## Instalación

Use --with-pdo-firebird[=DIR] para instalar la extensión PDO Firebird, donde `[=DIR]` es el directorio base de intalación de Firebird.

    $ ./configure --with-pdo-firebird

## Constantes predefinidas

Las constantes a continuación son definidas por este controlador y solo estarán disponibles cuando la extensión haya sido compilada en PHP o cargada dinámicamente del motor de ejecución. Además, estas constantes específicas del controlador deberían ser usadas solo si se usa este controlador. Usar atributos específicos de un controlador con otro controlador podría causar un comportamiento inesperado. PDO::getAttribute() podría ser usado para obtener el atributo `PDO::ATTR_DRIVER_NAME` para verificar el controlador, si su código puede funcionar en múltiples controladores.

`PDO::FB_ATTR_DATE_FORMAT` (int)

  Alias de `Pdo\Firebird::ATTR_DATE_FORMAT`.

`PDO::FB_ATTR_TIME_FORMAT` (int)

  Alias de `Pdo\Firebird::ATTR_TIME_FORMAT`.

`PDO::FB_ATTR_TIMESTAMP_FORMAT` (int)

  Alias de `Pdo\Firebird::ATTR_TIMESTAMP_FORMAT`.

# PDO_FIREBIRD DSN

(PECL PDO_FIREBIRD >= 0.1.0)

PDO_FIREBIRD DSN — Conexión a las bases de datos Firebird

### Descripción

El Data Source Name (DSN) de PDO_FIREBIRD se compone de los siguientes elementos:

Prefijo DSN

  El prefijo DNS es `firebird:`.

`dbname`

  El nombre de la base de datos.

`charset`

  El juego de caracteres.

`role`

  El nombre del rol SQL.

`dialect`

  El dialecto de la base de datos; sea `1` o `3`. Si no se especifica, el dialecto por omisión es `3`. Disponible a partir de PHP 7.4.0.

### Ejemplos

Ejemplo #1 Ejemplos con PDO_FIREBIRD DSN

El siguiente ejemplo muestra PDO_FIREBIRD DSN para conectarse a las bases de datos Firebird:

    firebird:dbname=/ruta/vers/DATABASE.FDB

Ejemplo #2 Ejemplo con un DSN PDO_FIREBIRD con un puerto y una ruta

El siguiente ejemplo muestra un DSN PDO_FIREBIRD para la conexión a una base de datos Firebird, utilizando un nombre de host, un puerto y una ruta:

    firebird:dbname=hostname/port:/path/to/DATABASE.FDB

Ejemplo #3 Ejemplo con un DSN PDO_FIREBIRD en local y una ruta hacia el fichero employee.fdb en un sistema Debian

El siguiente ejemplo muestra un DSN PDO_FIREBIRD para conectarse a una base de datos Firebird employee.fdb en local:

    firebird:dbname=localhost:/var/lib/firebird/2.5/data/employee.fdb

Ejemplo #4 Un DSN PDO_FIREBIRD para conectarse a una base de datos en dialecto 1

El siguiente ejemplo muestra un DSN PDO_FIREBIRD para conectarse a una base de datos Firebird test.fdb que ha sido creada utilizando el dialecto 1. Esto es únicamente soportado a partir de PHP 7.4.0.

    firebird:dbname=localhost:/var/lib/firebird/2.5/data/test.fdb;charset=utf-8;dialect=1

## Tabla de contenidos

- PDO_FIREBIRD DSN — Conexión a las bases de datos Firebird

# La clase Pdo\Firebird

(PHP 8 >= 8.4.0)

## Introducción

Una subclase de PDO que representa una conexión utilizando el controlador PDO de Firebird.

## Sinopsis de la Clase

namespace Pdo;
class Firebird extends PDO {
/* Constantes heredadas */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Constantes */
public const int ATTR_DATE_FORMAT;
public const int ATTR_TIME_FORMAT;
public const int ATTR_TIMESTAMP_FORMAT;
public const int TRANSACTION_ISOLATION_LEVEL;
public const int READ_COMMITTED;
public const int REPEATABLE_READ;
public const int SERIALIZABLE;
public const int WRITABLE_TRANSACTION;
/* Métodos */
public static function getApiVersion(): int
/* Métodos heredados */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Constantes predefinidas

`Pdo\Firebird::ATTR_DATE_FORMAT`
  Define el formato de fecha.
`Pdo\Firebird::ATTR_TIME_FORMAT`
  Define el formato de hora.
`Pdo\Firebird::ATTR_TIMESTAMP_FORMAT`
  Define el formato de la marca de tiempo.
`Pdo\Firebird::TRANSACTION_ISOLATION_LEVEL`
  Los atributos de transacción definen el nivel de aislamiento de la transacción. Puede ser uno de los siguientes: `Pdo\Firebird::READ_COMMITTED`, `Pdo\Firebird::REPEATABLE_READ`, o `Pdo\Firebird::SERIALIZABLE`.
`Pdo\Firebird::READ_COMMITTED`
  Bandera que indica que el nivel de aislamiento de la transacción ANSI es read committed. Este es el comportamiento por omisión.
`Pdo\Firebird::REPEATABLE_READ`
  Bandera que indica que el nivel de aislamiento de la transacción ANSI es repeatable read. Esto corresponde al nivel de aislamiento "snapshot" de Firebird.
`Pdo\Firebird::SERIALIZABLE`
  Bandera que indica que el nivel de aislamiento de la transacción ANSI es serializable. Esto corresponde al nivel de aislamiento "snapshot table stability" de Firebird.
`Pdo\Firebird::WRITABLE_TRANSACTION`
  El atributo booleano utilizado para cambiar el modo de acceso a la transacción entre `READ ONLY` y `READ WRITE`. Por omisión, es `true` indicando `READ WRITE`.

# Pdo\Firebird::getApiVersion

(PHP 8 >= 8.4.0)

Pdo\Firebird::getApiVersion — Devuelve la versión de la API

### Descripción

public static function Pdo\Firebird::getApiVersion(): int

Devuelve la versión de la API Firebird tal como está definida por la constante C `FB_API_VER` en ibase.h.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la API Firebird como int.

## Tabla de contenidos

- Pdo\Firebird::getApiVersion — Devuelve la versión de la API

# Funciones del controlador PDO IBM (PDO_IBM)

## Introducción

PDO_IBM es un driver que implementa la interfaz PHP Data Objects (PDO) para habilitar el acceso desde PHP a las bases de datos IBM.

## Instalación

Para compilar la extensión PDO_IBM, el cliente DB2 v9.1 o superior debe ser instalado en el mismo sistema que PHP. El cliente DB2 puede ser descargado desde el sitio de IBM de » desarrollo de aplicaciones.

> Nota: Nota

> El cliente DB2 v9.1 o superior soporta los accesos directos a DB2 para los sistemas Linux, UNIX y los servidores Windows v8 y v9.1.

> El cliente DB2 v9.1 soporta asimismo los accesos a DB2 UDB para i5 y DB2 UDB para los servidores z/OS utilizando el » producto de conexión DB2 de pago.

PDO_IBM es una extensión » PECL; por lo tanto, las instrucciones de Instalación de extensiones PECL deben ser seguidas para instalar la extensión PDO_IBM. Ejecute el comando configure para que apunte hacia el directorio que contiene los ficheros de encabezado y las bibliotecas del cliente DB2 de la siguiente manera:

     bash$ ./configure --with-pdo-ibm=/path/to/sqllib[,shared]

El comando configure utiliza por omisión el valor de la variable de entorno DB2DIR.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración PDO_IBM
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
pdo_ibm.i5_dbcs_alloc | "0" | `INI_SYSTEM` | Añadido en PDO_IBM 1.5.0
pdo_ibm.i5_override_ccsid | "0" | `INI_SYSTEM` | Añadido en PDO_IBM 1.5.0

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`pdo_ibm.i5_dbcs_alloc` int

  Esta opción afecta a la estrategia de asignación de memoria interna en IBM i. Por omisión, esta opción es 0. Cuando esta opción está definida, se asignan búferes con un tamaño mucho mayor, por si la base de datos engañara sobre el tamaño de los caracteres durante la conversión entre codificaciones. Esta opción utiliza seis veces más memoria para los búferes (para tener en cuenta las secuencias UTF-8 más largas), pero puede ser necesaria si se devuelven datos truncados.

  - 0 - Se asigna el tamaño mínimo de los búferes.

  - 1 - Se asigna un tamaño mayor de los búferes.

`pdo_ibm.i5_override_ccsid` int

  El CCSID ASCII a utilizar para la conversión de EBCDIC en IBM i. Al definirlo como 1208, se utilizará UTF-8. Por omisión es 0, lo que seleccionará el CCSID ASCII de trabajo predeterminado.

  Para obtener más información sobre los CCSID en IBM i, consulte la » documentación de IBM.

# PDO_IBM DSN

(PECL PDO_IBM >= 0.9.0)

PDO_IBM DSN — Conexión a las bases de datos IBM

### Descripción

El nombre de la fuente de datos PDO_IBM (DSN) se basa en el IBM CLI DSN. Los componentes principales de PDO_IBM DSN son :

Prefijo DSN

  El prefijo DSN es `ibm:`.

DSN

  El DSN puede ser uno de los siguientes :

  - a) Configuración de la fuente de datos utilizando el archivo db2cli.ini o odbc.ini

  - b) Nombre de base de datos catalogado, es decir, alias de base de datos contenidos en el catálogo del cliente DB2

  - c) Cadena de conexión completa en el siguiente formato : `DRIVER={IBM DB2 ODBC DRIVER};DATABASE=`database`;HOSTNAME=`hostname`;PORT=`port`;PROTOCOL=TCPIP;UID=`username`;PWD=`password`;` donde los parámetros representan los siguientes valores :

    `database`

      El nombre de la base de datos.

    `hostname`

      El nombre del host o la dirección IP del servidor de base de datos.

    `port`

      El puerto TCP/IP en el que la base de datos escucha las consultas.

    `username`

      El nombre de usuario utilizado para la conexión a la base de datos.

    `password`

      La contraseña utilizada para la conexión a la base de datos.

### Ejemplos

Ejemplo #1 Ejemplo con PDO_IBM DSN utilizando db2cli.ini

El siguiente ejemplo muestra el uso de PDO_IBM DSN para la conexión a una base de datos DB2 catalogada como DB2_9 en el archivo db2cli.ini :

    $db = new PDO("ibm:DSN=DB2_9", "", "");

    [DB2_9]
    Database=testdb
    Protocol=tcpip
    Hostname=11.22.33.444
    Servicename=56789

Ejemplo #2 Ejemplo con PDO_IBM DSN utilizando una cadena completa de conexión

El siguiente ejemplo muestra el uso de PDO_IBM DSN para la conexión a una base de datos DB2 llamada `testdb` utilizando la cadena completa de conexión DB2 CLI :

    $db = new PDO("ibm:DRIVER={IBM DB2 ODBC DRIVER};DATABASE=testdb;" .
    "HOSTNAME=11.22.33.444;PORT=56789;PROTOCOL=TCPIP;", "testuser", "tespass");

## Tabla de contenidos

- PDO_IBM DSN — Conexión a las bases de datos IBM

# Funciones del controlador PDO Informix (PDO_INFORMIX)

## Introducción

PDO_INFORMIX es un controlador que implementa la interfaz de PHP Data Objects (PDO) para permitir el acceso de PHP a las bases de datos Informix.

## Instalación

Para compilar la extensión PDO_INFORMIX, debe estar instalado el SDK Client Informix 2.81 UC1 o superior en el mismo sistema que PHP. El SDK Client Informix está disponible en el » Sitio de Soporte IBM Informix.

PDO_INFORMIX es una extensión » PECL, por lo que se deben seguir las instrucciones en Instalación de extensiones PECL para instalar la extensión PDO_INFORMIX. Se debe escribir el comando configure para indicar la ruta de los ficheros de encabezado del SDK Client Informix así como las bibliotecas de la siguiente manera:

       bash$ ./configure --with-pdo-informix=/path/to/SDK[,shared]

El comando configure utiliza por omisión la variable de entorno INFORMIXDIR.

## Cursores flotantes

PDO_INFORMIX soporta los cursores flotantes; sin embargo, no están activados por omisión. Para activar el soporte de los cursores flotantes, debe establecer `ENABLESCROLLABLECURSORS=1` en las configuraciones de la conexión ODBC correspondiente en odbc.ini o pasar la cláusula `EnableScrollableCursors=1` en la cadena de conexión DSN.

# PDO_INFORMIX DSN

(PECL PDO_INFORMIX >= 0.1.0)

PDO_INFORMIX DSN — Conexión a las bases de datos Informix

### Descripción

El Data Source Name (DSN) de PDO_INFORMIX se basa en la cadena de caracteres DSN de Informix ODBC. Los detalles sobre la configuración de un DSN Informix ODBC están disponibles en » Informix Dynamic Server Information Center. Los componentes principales del DSN de PDO_INFORMIX son:

Prefijo DSN

  El prefijo DSN es `informix:`.

DSN

  El DSN puede ser una fuente de datos de configuración utilizando odbc.ini o una » cadena de conexión completa.

### Ejemplos

Ejemplo #1 Ejemplo de DSN de PDO_INFORMIX con odbc.ini

El siguiente ejemplo muestra el DSN de PDO_INFORMIX para conectarse a una base de datos Informix catalogada como Infdrv33 en odbc.ini:

    $db = new PDO("informix:DSN=Infdrv33", "", "");

    [ODBC Data Sources]
    Infdrv33=INFORMIX 3.3 32-BIT

    [Infdrv33]
    Driver=/opt/informix/csdk_2.81.UC1G2/lib/cli/iclis09b.so
    Description=INFORMIX 3.3 32-BIT
    Database=common_db
    LogonID=testuser
    pwd=testpass
    Servername=ids_server
    DB_LOCALE=en_US.819
    OPTIMIZEAUTOCOMMIT=1
    ENABLESCROLLABLECURSORS=1

Ejemplo #2 Ejemplo de DSN de PDO_INFORMIX con una cadena de conexión

El siguiente ejemplo muestra el DSN de PDO_INFORMIX para conectarse a una base de datos Informix llamada `common_db` utilizando la sintaxis de cadena de conexión de Informix.

    $db = new PDO("informix:host=host.domain.com; service=9800;
        database=common_db; server=ids_server; protocol=onsoctcp;
        EnableScrollableCursors=1", "testuser", "tespass");

## Tabla de contenidos

- PDO_INFORMIX DSN — Conexión a las bases de datos Informix

# Funciones del controlador PDO MySQL (PDO_MYSQL)

## Introducción

PDO_MYSQL es un controlador que implementa la PHP Data Objects (PDO) para permitir el acceso de PHP a las bases de datos MySQL.

PDO_MYSQL utiliza consultas preparadas emuladas por omisión.

MySQL 8

Si PHP se utiliza en una versión 7.1 anterior a la versión 7.1.16, o PHP 7.2 anterior a 7.2.4, el complemento de contraseña debe establecerse en mysql_native_password para MySQL 8 Server, ya que de lo contrario pueden aparecer errores similares a The server requested authentication method unknown to the client [caching_sha2_password], incluso si caching_sha2_password no se utiliza.

Esto se debe a que MySQL 8 utiliza por omisión caching_sha2_password, un complemento que no es reconocido por las versiones antiguas de PHP (mysqlnd). En su lugar, debe modificarse el parámetro `default_authentication_plugin=mysql_native_password` en my.cnf. El complemento caching_sha2_password es completamente soportado a partir de PHP 7.4.4. Para versiones anteriores, la extensión mysql_xdevapi lo soporta.

Advertencia

Tenga en cuenta: ciertos tipos de tablas MySQL (motor de registro) no soportan transacciones. Cuando se escribe código de base de datos transaccional utilizando un tipo de tabla que no soporta transacciones, MySQL afirmará que una transacción fue iniciada correctamente. Además, cualquier consulta DLL publicada enviará implícitamente todas las transacciones pendientes.

> Nota:

> El controlador MySQL no soporta adecuadamente `PDO::PARAM_INPUT_OUTPUT` a través de PDOStatement::bindParam(); aunque tales parámetros pueden ser utilizados, no serán actualizados (es decir, la salida actual es ignorada).

## Instalación

Las distribuciones Linux incluyen versiones binarias de PHP que pueden ser instaladas. Incluso si estos binarios son construidos con las extensiones MySQL, las bibliotecas clientes deben ser a menudo instaladas mediante un paquete adicional. Verifique si es el caso para su distribución.

Por ejemplo, en Ubuntu el paquete `php5-mysql` instala las extensiones PHP ext/mysql, ext/mysqli, y pdo_mysql. En CentOS, el paquete `php-mysql` también instala estas tres extensiones PHP.

Alternativamente, puede compilar esta extensión usted mismo. Construir PHP desde las fuentes permite especificar las extensiones MySQL a incluir, así como las bibliotecas clientes de cada extensión.

Durante la compilación utilice --with-pdo-mysql[=DIR] para instalar la extensión PDO MySQL, donde `[=DIR]` es la ruta de la biblioteca base de MySQL. Mysqlnd y la biblioteca por defecto. Para más detalles sobre la elección de la biblioteca, ver Elegir una biblioteca MySQL.

Opcionalmente, la opción --with-mysql-sock[=DIR] define la ruta hacia el socket Unix MySQL para todas las extensiones MySQL, incluyendo PDO_MYSQL. Si no se especifica, se utilizarán las rutas por defecto.

Opcionalmente, la opción --with-zlib-dir[=DIR] será utilizada para definir el prefijo de instalación zlib.

    $ ./configure --with-pdo-mysql --with-mysql-sock=/var/mysql/mysql.sock

El soporte SSL es activado utilizando las constantes `Pdo\Mysql::ATTR_SSL_*`, lo cual equivale a llamar a la función API C » mysql_ssl_set(). Además, SSL no puede ser activado con PDO::setAttribute() ya que la conexión ya existe. Ver también la documentación MySQL sobre » la conexión a MySQL con SSL.

## Constantes predefinidas

Las constantes a continuación son definidas por este controlador y solo estarán disponibles cuando la extensión haya sido compilada en PHP o cargada dinámicamente del motor de ejecución. Además, estas constantes específicas del controlador deberían ser usadas solo si se usa este controlador. Usar atributos específicos de un controlador con otro controlador podría causar un comportamiento inesperado. PDO::getAttribute() podría ser usado para obtener el atributo `PDO::ATTR_DRIVER_NAME` para verificar el controlador, si su código puede funcionar en múltiples controladores.

`PDO::MYSQL_ATTR_USE_BUFFERED_QUERY` (int)
  Alias de `Pdo\Mysql::ATTR_USE_BUFFERED_QUERY`
`PDO::MYSQL_ATTR_LOCAL_INFILE` (int)
  Alias de `Pdo\Mysql::ATTR_LOCAL_INFILE`
`PDO::MYSQL_ATTR_LOCAL_INFILE_DIRECTORY` (int)
  Alias de `Pdo\Mysql::ATTR_LOCAL_INFILE_DIRECTORY`. Disponible a partir de PHP 8.1.0.
`PDO::MYSQL_ATTR_INIT_COMMAND` (int)
  Alias de `Pdo\Mysql::ATTR_INIT_COMMAND`
`PDO::MYSQL_ATTR_READ_DEFAULT_FILE` (int)
  Alias de `Pdo\Mysql::ATTR_READ_DEFAULT_FILE`
`PDO::MYSQL_ATTR_READ_DEFAULT_GROUP` (int)
  Alias de `Pdo\Mysql::ATTR_READ_DEFAULT_GROUP`
`PDO::MYSQL_ATTR_MAX_BUFFER_SIZE` (int)
  Alias de `Pdo\Mysql::ATTR_MAX_BUFFER_SIZE`
`PDO::MYSQL_ATTR_DIRECT_QUERY` (bool)
  Alias de `PDO::ATTR_EMULATE_PREPARES` A partir de PHP 8.4.0 esta constante es de tipo bool; anteriormente, era de tipo int.
`PDO::MYSQL_ATTR_FOUND_ROWS` (int)
  Alias de `Pdo\Mysql::ATTR_FOUND_ROWS`
`PDO::MYSQL_ATTR_IGNORE_SPACE` (int)
  Alias de `Pdo\Mysql::ATTR_IGNORE_SPACE`
`PDO::MYSQL_ATTR_COMPRESS` (int)
  Alias de `Pdo\Mysql::ATTR_COMPRESS`
`PDO::MYSQL_ATTR_SERVER_PUBLIC_KEY` (int)
  Alias de `Pdo\Mysql::ATTR_SERVER_PUBLIC_KEY`
`PDO::MYSQL_ATTR_SSL_CA` (int)
  Alias de `Pdo\Mysql::ATTR_SSL_CA`
`PDO::MYSQL_ATTR_SSL_CAPATH` (int)
  Alias de `Pdo\Mysql::ATTR_SSL_CAPATH`
`PDO::MYSQL_ATTR_SSL_CERT` (int)
  Alias de `Pdo\Mysql::ATTR_SSL_CERT`
`PDO::MYSQL_ATTR_SSL_CIPHER` (int)
  Alias de `Pdo\Mysql::ATTR_SSL_CIPHER`
`PDO::MYSQL_ATTR_SSL_KEY` (int)
  Alias de `Pdo\Mysql::ATTR_SSL_KEY`
`PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT` (int)
  Alias de `Pdo\Mysql::ATTR_SSL_VERIFY_SERVER_CERT` Disponible a partir de PHP 7.0.18 y PHP 7.1.4.
`PDO::MYSQL_ATTR_MULTI_STATEMENTS` (int)
  Alias de `Pdo\Mysql::ATTR_MULTI_STATEMENTS`

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración del controlador PDO_MYSQL
Nombre | Por defecto | Cambiable
--- | --- | ---
pdo_mysql.default_socket | "/tmp/mysql.sock" | `INI_SYSTEM`
pdo_mysql.debug | NULL | `INI_SYSTEM`

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`pdo_mysql.default_socket` string

  Se define un socket de dominio Unix. El valor puede ser también definido en el momento de la compilación si se encuentra un socket de dominio Unix durante la configuración. Esta configuración INI solo está disponible bajo Unix.

`pdo_mysql.debug` bool

  Se activa el depurado para el controlador PDO_MYSQL. Esta configuración solo está disponible cuando el controlador PDO_MYSQL es compilado con mysqlnd y en modo de depurado PDO.

# PDO_MYSQL DSN

(PECL PDO_MYSQL >= 0.1.0)

PDO_MYSQL DSN — Conexión a las bases de datos MySQL

### Descripción

El Data Source Name (DSN) de PDO_MYSQL se compone de los siguientes elementos:

Prefijo DSN

  El prefijo DSN es `mysql:`.

`host`

  El host donde se encuentra el servidor de base de datos.

`port`

  El número de puerto donde el servidor de base de datos está escuchando.

`dbname`

  El nombre de la base de datos.

`unix_socket`

  El socket Unix de MySQL (no debe utilizarse con `host` o `port`).

`charset`

  El juego de caracteres. Consulte la documentación sobre los conceptos de los juegos de caracteres para obtener más información.

### Ejemplos

Ejemplo #1 Ejemplos con el DSN de PDO_MYSQL

El siguiente ejemplo muestra el DSN PDO_MYSQL para conectarse a las bases de datos MySQL:

    mysql:host=localhost;dbname=testdb

Ejemplos más completos:

    mysql:host=localhost;port=3307;dbname=testdb
    mysql:unix_socket=/tmp/mysql.sock;dbname=testdb

### Notas

> Nota: Solo Unix:

> Cuando el nombre de host es `"localhost"`, la conexión se realiza a través de un socket Unix. Si PDO_MYSQL está compilado con libmysqlclient, entonces el archivo de socket es el especificado durante la compilación de libmysqlclient. Si PDO_MYSQL está compilado con mysqlnd, un socket por omisión puede ser indicado a través del parámetro pdo_mysql.default_socket.

## Tabla de contenidos

- PDO_MYSQL DSN — Conexión a las bases de datos MySQL

# La clase Pdo\Mysql

(PHP 8 >= 8.4.0)

## Introducción

Una subclase de PDO que representa una conexión utilizando el controlador PDO MySQL.

Este controlador admite un analizador de consultas SQL dedicado para el dialecto MySQL. Puede gestionar los siguientes elementos:

- Literales entre comillas simples y dobles con duplicación y barra invertida como mecanismos de escape
- Literales con acento grave con duplicación como mecanismo de escape
- Dos guiones, comentarios de estilo C y comentarios de tipo hash

## Sinopsis de la Clase

class Pdo\Mysql extends PDO {
/* Constantes heredadas */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Constantes */
public const int ATTR_USE_BUFFERED_QUERY;
public const int ATTR_LOCAL_INFILE;
public const int ATTR_LOCAL_INFILE_DIRECTORY;
public const int ATTR_INIT_COMMAND;
public const int ATTR_MAX_BUFFER_SIZE;
public const int ATTR_READ_DEFAULT_FILE;
public const int ATTR_READ_DEFAULT_GROUP;
public const int ATTR_COMPRESS;
public const int ATTR_DIRECT_QUERY;
public const int ATTR_FOUND_ROWS;
public const int ATTR_IGNORE_SPACE;
public const int ATTR_MULTI_STATEMENTS;
public const int ATTR_SERVER_PUBLIC_KEY;
public const int ATTR_SSL_KEY;
public const int ATTR_SSL_CERT;
public const int ATTR_SSL_CA;
public const int ATTR_SSL_CAPATH;
public const int ATTR_SSL_CIPHER;
public const int ATTR_SSL_VERIFY_SERVER_CERT;
/* Métodos */
public function getWarningCount(): int
/* Métodos heredados */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Constantes predefinidas

`Pdo\Mysql::ATTR_USE_BUFFERED_QUERY`
  Por omisión, todas las consultas se ejecutan en modo almacenado en búfer. Si este atributo se define como `false` en un objeto Pdo\Mysql, el controlador MySQL utilizará el modo sin búfer.

  Ejemplo #1 Activación del modo sin búfer MySQL

      <?php
      $pdo = new Pdo\Mysql("mysql:host=localhost;dbname=world", 'my_user', 'my_password');
      $pdo->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, false);

      $unbufferedResult = $pdo->query("SELECT Name FROM City");
      foreach ($unbufferedResult as $row) {
          echo $row['Name'] . PHP_EOL;
      }
      ?>

`Pdo\Mysql::ATTR_LOCAL_INFILE`
  Activa `LOAD LOCAL INFILE`.

  > Nota: Puede utilizarse únicamente en el array `driver_options` al construir una nueva conexión a la base de datos.

`Pdo\Mysql::ATTR_LOCAL_INFILE_DIRECTORY`
  Permite restringir la carga de datos locales a los ficheros situados en este directorio designado.

  > Nota: Puede utilizarse únicamente en el array `driver_options` al construir una nueva conexión a la base de datos.

`Pdo\Mysql::ATTR_INIT_COMMAND`
  El comando a ejecutar al conectarse al servidor MySQL. Se reejecutará automáticamente al reconectar.

  > Nota: Puede utilizarse únicamente en el array `driver_options` al construir una nueva conexión a la base de datos.

`Pdo\Mysql::ATTR_READ_DEFAULT_FILE`
  Leer las opciones del fichero de opciones nombrado en lugar de my.cnf.

  > Nota: Esta opción no está disponible si se utiliza mysqlnd, ya que mysqlnd no lee los ficheros de configuración mysql.

`Pdo\Mysql::ATTR_READ_DEFAULT_GROUP`
  Lee las opciones del grupo nombrado del fichero my.cnf o el fichero especificado con `Pdo\Mysql::ATTR_READ_DEFAULT_FILE`.

  > Nota: Esta opción no está disponible si se utiliza mysqlnd, ya que mysqlnd no lee los ficheros de configuración mysql.

`Pdo\Mysql::ATTR_COMPRESS`
  Activa la compresión de la comunicación de red.
`Pdo\Mysql::ATTR_DIRECT_QUERY`
  Alias de `PDO::ATTR_EMULATE_PREPARES`.
`Pdo\Mysql::ATTR_FOUND_ROWS`
  Devuelve el número de filas encontradas (coincidentes), no el número de filas modificadas.

  > Nota: Puede utilizarse únicamente en el array `driver_options` al construir una nueva conexión a la base de datos.

`Pdo\Mysql::ATTR_IGNORE_SPACE`
  Permite espacios después de los nombres de funciones SQL. Convierte todos los nombres de funciones SQL en palabras reservadas.

  > Nota: Puede utilizarse únicamente en el array `driver_options` al construir una nueva conexión a la base de datos.

`Pdo\Mysql::ATTR_MAX_BUFFER_SIZE`
  El tamaño máximo del búfer. Por omisión, 1 MB.

  > Nota: Esta constante no está soportada cuando se compila sin mysqlnd.

`Pdo\Mysql::ATTR_MULTI_STATEMENTS`
  Desactiva la ejecución de consultas múltiples en PDO::prepare() y PDO::query() cuando se define como `false`.

  > Nota: Puede utilizarse únicamente en el array `driver_options` al construir una nueva conexión a la base de datos.

`Pdo\Mysql::ATTR_SERVER_PUBLIC_KEY`
  RSA la ruta del fichero de clave pública utilizada con la autenticación basada en SHA-256.

  > Nota: Puede utilizarse únicamente en el array `driver_options` al construir una nueva conexión a la base de datos.

`Pdo\Mysql::ATTR_SSL_KEY`
  La ruta del fichero de clave SSL.

  > Nota: Puede utilizarse únicamente en el array `driver_options` al construir una nueva conexión a la base de datos.

`Pdo\Mysql::ATTR_SSL_CERT`
  La ruta del certificado SSL.

  > Nota: Puede utilizarse únicamente en el array `driver_options` al construir una nueva conexión a la base de datos.

`Pdo\Mysql::ATTR_SSL_CA`
  La ruta del certificado de autoridad SSL.

  > Nota: Puede utilizarse únicamente en el array `driver_options` al construir una nueva conexión a la base de datos.

`Pdo\Mysql::ATTR_SSL_CAPATH`
  La ruta del directorio que contiene los certificados de autoridad SSL CA, almacenados en formato PEM.

  > Nota: Puede utilizarse únicamente en el array `driver_options` al construir una nueva conexión a la base de datos.

`Pdo\Mysql::ATTR_SSL_CIPHER`
  Una lista de uno o más cifrados autorizados para utilizar con SSL, en un formato comprendido por OpenSSL. Por ejemplo: `DHE-RSA-AES256-SHA:AES128-SHA`

  > Nota: Puede utilizarse únicamente en el array `driver_options` al construir una nueva conexión a la base de datos.

`Pdo\Mysql::ATTR_SSL_VERIFY_SERVER_CERT`
  Proporciona un medio para desactivar la verificación del certificado del servidor SSL.

  > Nota: Esta opción está disponible únicamente con mysqlnd.

  > Nota: Puede utilizarse únicamente en el array `driver_options` al construir una nueva conexión a la base de datos.

# Pdo\Mysql::getWarningCount

(PHP 8 >= 8.4.0)

Pdo\Mysql::getWarningCount — Devuelve el número de advertencias de la última consulta ejecutada

### Descripción

public function Pdo\Mysql::getWarningCount(): int

Devuelve el número de advertencias de la última consulta ejecutada.

> Nota: Para recuperar los mensajes de advertencia, puede utilizarse el siguiente comando SQL: `SHOW WARNINGS [limit row_count]`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un int que representa el número de advertencias generadas por la última consulta.

### Ejemplos

Ejemplo #1 Ejemplo de Pdo\Mysql::getWarningCount()

    <?php

    $conn = PDO::connect("mysql:host=localhost;dbname=test;charset=utf8mb4", 'user', 'password');

    $conn->query('SELECT 42/0');
    if ($conn->getWarningCount() > 0) {
        $result = $conn->query("SHOW WARNINGS");
        $row = $result->fetch();
        printf("%s (%d): %s\n", $row[0], $row[1], $row[2]);
    }

    ?>

El ejemplo anterior mostrará:

    Warning (1365): Division by 0

## Tabla de contenidos

- Pdo\Mysql::getWarningCount — Devuelve el número de advertencias de la última consulta ejecutada

# Funciones Microsoft del controlador PDO SQL Server (PDO_SQLSRV)

## Introducción

PDO_SQLSRV es un controlador que implementa la interfaz PDO (PHP Data Objects) para permitir el acceso desde PHP a las bases de datos MS SQL Server (versión SQL Server 2005 y superiores) y SQL Azure.

## Instalación

La versión más reciente del controlador está disponible para su descarga aquí: » descarga SQLSRV. Las fuentes del controlador se alojan en un » repositorio público.

Para obtener más información acerca de los requisitos del sistema, consúltese el capítulo sobre los » requisitos del sistema SQLSRV.

En Windows, la extensión PDO_SQLSRV se activa descargando y añadiendo los archivos DLL correspondientes en el directorio de extensiones de PHP y la entrada correspondiente en el archivo php.ini.

En Linux y macOS, la extensión PDO_SQLSRV puede ser instalada utilizando » PECL. Consúltese el » tutorial de instalación para más detalles.

## Constantes predefinidas

Las constantes a continuación son definidas por este controlador y solo estarán disponibles cuando la extensión haya sido compilada en PHP o cargada dinámicamente del motor de ejecución. Además, estas constantes específicas del controlador deberían ser usadas solo si se usa este controlador. Usar atributos específicos de un controlador con otro controlador podría causar un comportamiento inesperado. PDO::getAttribute() podría ser usado para obtener el atributo `PDO::ATTR_DRIVER_NAME` para verificar el controlador, si su código puede funcionar en múltiples controladores.

`PDO::SQLSRV_TXN_READ_UNCOMMITTED` (int)
  Esta constante es un valor posible para la clave "TransactionIsolation" del DSN para SQLSRV. Esta constante establece el nivel de aislamiento de la transacción a "Read Uncommitted".
`PDO::SQLSRV_TXN_READ_COMMITTED` (int)
  Esta constante es un valor posible para la clave "TransactionIsolation" del DSN para SQLSRV. Esta constante establece el nivel de aislamiento de la transacción a "Read Committed".
`PDO::SQLSRV_TXN_REPEATABLE_READ` (int)
  Esta constante es un valor posible para la clave "TransactionIsolation" del DSN para SQLSRV. Esta constante establece el nivel de aislamiento de la transacción a "Repeatable Read".
`PDO::SQLSRV_TXN_SNAPSHOT` (int)
  Esta constante es un valor posible para la clave "TransactionIsolation" del DSN para SQLSRV. Esta constante establece el nivel de aislamiento de la transacción a "Snapshot".
`PDO::SQLSRV_TXN_SERIALIZABLE` (int)
  Esta constante es un valor posible para la clave "TransactionIsolation" del DSN para SQLSRV. Esta constante establece el nivel de aislamiento de la transacción a "Serializable".
`PDO::SQLSRV_ENCODING_BINARY` (int)
  Especifica que estos datos son enviados al (o recibidos del) servidor como un flujo de bytes, sin realizar codificación o traducción. Esta constante puede ser utilizada en las llamadas a PDOStatement::setAttribute, PDO::prepare, PDOStatement::bindColumn, y PDOStatement::bindParam.
`PDO::SQLSRV_ENCODING_SYSTEM` (int)
  Especifica que estos datos son enviados al (o recibidos del) servidor como un flujo de caracteres 8 bits, como se especifica en la página de código de la configuración local de Windows activa en el sistema. Todo carácter multibyte, o carácter que no existe en esta página de código, es sustituido por un simple signo de interrogación (?). Esta constante puede ser utilizada en las llamadas a PDOStatement::setAttribute, PDO::setAttribute, PDO::prepare, PDOStatement::bindColumn, y PDOStatement::bindParam.
`PDO::SQLSRV_ENCODING_UTF8` (int)
  Especifica que estos datos son enviados al (o recibidos del) servidor como un flujo de caracteres UTF-8. Se trata de la codificación por defecto. Esta constante puede ser utilizada en las llamadas a PDOStatement::setAttribute, PDO::setAttribute, PDO::prepare, PDOStatement::bindColumn, y PDOStatement::bindParam.
`PDO::SQLSRV_ENCODING_DEFAULT` (int)
  Especifica que estos datos son enviados al (o recibidos del) servidor utilizando la codificación PDO::SQLSRV_ENCODING_SYSTEM si es especificada durante la conexión. Si es especificada en una instrucción "prepare", se utiliza la codificación de la conexión. Esta constante puede ser utilizada en las llamadas a PDOStatement::setAttribute, PDO::setAttribute, PDO::prepare, PDOStatement::bindColumn, y PDOStatement::bindParam.
`PDO::SQLSRV_ATTR_QUERY_TIMEOUT` (int)
  Un entero positivo o nulo que representa la duración del tiempo límite, en segundos. Cero (0) es el valor por omisión y significa que no hay tiempo límite. Esta constante puede ser utilizada en las llamadas a PDOStatement::setAttribute, PDO::setAttribute, y PDO::prepare.
`PDO::SQLSRV_ATTR_DIRECT_QUERY` (int)
  Indica una consulta que debe ser ejecutada directamente, sin ser preparada. Esta constante puede ser utilizada en las llamadas a PDO::setAttribute, y PDO::prepare. Para más información, ver (en inglés) » Direct and Prepared Statement Execution.

# PDO_SQLSRV DSN

(PECL pdo_sqlsrv >= 2.0.1)

PDO_SQLSRV DSN — Conexión a bases de datos MS SQL Server y SQL Azure

### Descripción

El archivo DSN (Data Source Name) PDO_SQLSRV se compone de los siguientes elementos:

prefijo DSN

  El prefijo DSN es `sqlsrv:`.

`APP`
  El nombre de la aplicación, utilizado para las trazas.
`ConnectionPooling`
  Especifica si la conexión está asignada a un pool de conexiones (1 o `true`) o no (0 o `false`).
`Database`
  El nombre de la base de datos.
`Encrypt`
  Especifica si la comunicación con el servidor SQL Server está cifrada (1 o `true`) o no cifrada (0 o `false`).
`Failover_Partner`
  Especifica el servidor y la instancia de la base de datos espejo (si está activada y configurada) a utilizar cuando el servidor principal es inaccesible.
`LoginTimeout`
  Especifica el número de segundos de espera antes de detener y poner en error el intento de conexión.
`MultipleActiveResultSets`
  Desactiva, o activa explícitamente, el soporte para juegos de resultados múltiples (Multiple Active Result Sets, MARS).
`QuotedId`
  Especifica si se deben utilizar las reglas SQL-92 para los identificadores entre comillas (1 o `true`) o si se deben utilizar las reglas Transact-SQL estándar (0 o `false`).
`Server`
  El nombre del servidor de base de datos.
`TraceFile`
  La ruta del archivo utilizado para las trazas.
`TraceOn`
  Especifica si las trazas ODBC están activadas (1 o `true`) o desactivadas (0 o `false`) al activar la conexión.
`TransactionIsolation`
  Especifica el nivel de aislamiento de la transacción. Los valores posibles para esta opción son PDO::SQLSRV_TXN_READ_UNCOMMITTED, PDO::SQLSRV_TXN_READ_COMMITTED, PDO::SQLSRV_TXN_REPEATABLE_READ, PDO::SQLSRV_TXN_SNAPSHOT, y PDO::SQLSRV_TXN_SERIALIZABLE.
`TrustServerCertificate`
  Especifica si el cliente debe confiar (1 o `true`) o rechazar (0 o `false`) un certificado servidor autosignado.
`WSID`
  Especifica el nombre de la computadora para las trazas.

### Ejemplos

Ejemplo #1 Ejemplos de DSN PDO_SQLSRV

El siguiente ejemplo muestra cómo conectarse a la base de datos MS SQL Server especificada:

    $c = new PDO("sqlsrv:Server=localhost;Database=bddtest", "Utilisateur", "MotDePasse");

El siguiente ejemplo muestra cómo conectarse a la base de datos MS SQL Server especificada en un puerto específico:

    $c = new PDO("sqlsrv:Server=localhost,1521;Database=bddtest", "Utilisateur", "MotDePasse");

El siguiente ejemplo muestra cómo conectarse a una base de datos SQL Azure con el ID servidor 12345abcde. Tenga en cuenta que, al conectarse a Azure con PDO, su nombre de usuario será Usuario@12345abcde (Usuario@IdServidor).

    $c = new PDO("sqlsrv:Server=12345abcde.database.windows.net;Database=bddtest", "Utilisateur@12345abcde", "MotDePasse");

## Tabla de contenidos

- PDO_SQLSRV DSN — Conexión a bases de datos MS SQL Server y SQL Azure

# Funciones del controlador PDO Oracle (PDO_OCI)

## Instalación

Si la base de datos Oracle se encuentra en la misma máquina que PHP, el software de la base de datos contiene ya las bibliotecas necesarias. Cuando PHP se encuentra en una máquina diferente, utilícense las bibliotecas gratuitas » Oracle Instant Client. Para más detalles consúltese la sección sobre Requisitos OCI8.

## PHP 8.4

Esta extensión ha sido movida al módulo » PECL y no será integrada en PHP a partir de PHP 8.4.0

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/PDO_OCI.

## PHP < 8.4

Utilícese --with-pdo-oci[=DIR] para instalar la extensión PDO Oracle OCI, donde la opción `[=DIR]` es el directorio Oracle Home. `[=DIR]` corresponde por omisión a la variable de entorno $ORACLE_HOME.

Utilícese --with-pdo-oci=instantclient,prefix,version para un SDK Oracle Instant Client, donde prefix y version están configurados.

    // Utilización de $ORACLE_HOME
    $ ./configure --with-pdo-oci

    // Utilización de OIC para Linux con 10.2.0.3 RPMs con el prefijo /usr
    $ ./configure --with-pdo-oci=instantclient,/usr,10.2.0.3

## Constantes predefinidas

Las constantes a continuación son definidas por este controlador y solo estarán disponibles cuando la extensión haya sido compilada en PHP o cargada dinámicamente del motor de ejecución. Además, estas constantes específicas del controlador deberían ser usadas solo si se usa este controlador. Usar atributos específicos de un controlador con otro controlador podría causar un comportamiento inesperado. PDO::getAttribute() podría ser usado para obtener el atributo `PDO::ATTR_DRIVER_NAME` para verificar el controlador, si su código puede funcionar en múltiples controladores.

`PDO::OCI_ATTR_ACTION` (int)

  Proporciona un medio para especificar la acción sobre la sesión de la base de datos.

  Existe a partir de PHP 7.2.16 y 7.3.3

`PDO::OCI_ATTR_CLIENT_INFO` (int)

  Proporciona un medio para especificar la información del cliente sobre la sesión de la base de datos.

  Existe a partir de PHP 7.2.16 y 7.3.3

`PDO::OCI_ATTR_CLIENT_IDENTIFIER` (int)

  Proporciona un medio para especificar el identificador del cliente sobre la sesión de la base de datos.

  Existe a partir de PHP 7.2.16 y 7.3.3

`PDO::OCI_ATTR_MODULE` (int)

  Proporciona un medio para especificar el módulo sobre la sesión de la base de datos.

  Existe a partir de PHP 7.2.16 y 7.3.3

# PDO_OCI DSN

(PECL PDO_OCI >= 0.1.0)

PDO_OCI DSN — Conexión a bases de datos Oracle

### Descripción

El Data Source Name (DSN) de PDO_OCI se compone de los siguientes elementos:

Prefijo DSN

  El prefijo DSN es `oci:`.

`dbname` (Oracle Instant Client)

  El URI de conexión de Oracle Instant Client tiene la forma de `dbname=//hostname:port-number/database`. Si se conecta a una base de datos definida en tnsnames.ora, utilice solo el nombre de la base de datos: `dbname=database`.

`charset`

  El juego de caracteres del lado cliente para el entorno actual.

### Ejemplos

Ejemplo #1 Ejemplos con PDO_OCI DSN

Los siguientes ejemplos muestran PDO_OCI DSN para conectarse a bases de datos Oracle:

    // Conexión a una base de datos definida en tnsnames.ora
    oci:dbname=mydb

    // Conexión utilizando el cliente Oracle Instant
    oci:dbname=//localhost:1521/mydb

## Tabla de contenidos

- PDO_OCI DSN — Conexión a bases de datos Oracle

# Funciones del controlador PDO ODBC y DB2 (PDO_ODBC)

## Introducción

PDO_ODBC es un controlador que implementa la PHP Data Objects (PDO) para permitir el acceso de PHP a las bases de datos mediante los controladores de ODBC o mediante la biblioteca de interfaz IBM DB2 Call Level (DB2 CLI). PDO_ODBC actualmente soporta tres "sabores" diferentes de los controladores de bases de datos:

ibm-db2

  Permite el acceso a IBM DB2 Universal Database, Cloudscape y Apache Derby Server utilizando el cliente gratuito DB2 express-C.

unixODBC

  Permite el acceso a los servidores de bases de datos mediante el controlador de gestión unixODBC y las bases de datos poseídas por los controladores ODBC.

generic

  Ofrece una opción de compilación para los controladores de gestión ODBC que no son explícitamente soportados por PDO_ODBC.

En Windows, php_pdo_odbc.dll debe ser activado como extensión en php.ini. Está vinculado con el Windows ODBC Driver Manager, por lo que PHP puede conectarse a cualquier base de datos catalogada como un System DSN.

## Instalación

PDO_ODBC en sistemas UNIX

1. PDO_ODBC está incluido en las fuentes de PHP. Puede compilarse la extensión PDO_ODBC ya sea de forma estática o como módulo compartido utilizando los siguientes comandos configure.

   ibm_db2

         ./configure --with-pdo-odbc=ibm-db2,/opt/IBM/db2/V8.1/

     Para construir PDO_ODBC con el sabor ibm-db2, deben haberse instalado previamente los encabezados de desarrollo de la aplicación DB2 en la misma máquina donde se compila PDO_ODBC. Los encabezados de desarrollo de la aplicación DB2 son una opción de instalación en los servidores DB2 y también están disponibles como parte de DB2 Application Development Client gratuitamente disponibles para descarga desde el IBM developerWorks » sitio.

     Si no se especifica una ubicación para las bibliotecas y los encabezados de DB2 en el comando configure, PDO_ODBC tomará por omisión /home/db2inst1/sqllib.

   unixODBC

         ./configure --with-pdo-odbc=unixODBC,/usr/local

     Si no se especifica una ubicación para las bibliotecas y los encabezados de unixODBC en el comando configure, PDO_ODBC tomará por omisión /usr/local.
   generic

         ./configure --with-pdo-odbc=generic,/usr/local,libname,ldflags,cflags

## Constantes predefinidas

Las constantes a continuación son definidas por este controlador y solo estarán disponibles cuando la extensión haya sido compilada en PHP o cargada dinámicamente del motor de ejecución. Además, estas constantes específicas del controlador deberían ser usadas solo si se usa este controlador. Usar atributos específicos de un controlador con otro controlador podría causar un comportamiento inesperado. PDO::getAttribute() podría ser usado para obtener el atributo `PDO::ATTR_DRIVER_NAME` para verificar el controlador, si su código puede funcionar en múltiples controladores.

`PDO_ODBC_TYPE` (string)

`PDO::ODBC_ATTR_USE_CURSOR_LIBRARY` (int)
  Alias de `Pdo\Odbc::ATTR_USE_CURSOR_LIBRARY`.
`PDO::ODBC_SQL_USE_IF_NEEDED` (int)
  Alias de `Pdo\Odbc::SQL_USE_IF_NEEDED`.
`PDO::ODBC_SQL_USE_DRIVER` (int)
  Alias de `Pdo\Odbc::SQL_USE_DRIVER`.
`PDO::ODBC_SQL_USE_ODBC` (int)
  Alias de `Pdo\Odbc::SQL_USE_ODBC`.
`PDO::ODBC_ATTR_ASSUME_UTF8` (bool)
  Alias de `Pdo\Odbc::ATTR_ASSUME_UTF8`.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración de PDO_ODBC
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
pdo_odbc.connection_pooling | "strict" | `INI_ALL` |
pdo_odbc.db2_instance_name | NULL | `INI_SYSTEM` | Esta funcionalidad obsoleta será ciertamente eliminada en el futuro.

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`pdo_odbc.connection_pooling` string

  Si agrupar conexiones de ODBC. Se puede usar `"strict"`, `"relaxed"` o `"off"` (que es igual a `""`). El parámetro describe cómo de estricta debería ser el administrador de conexiones cuando coincidan los parámetros de conexión con conexiones existentes en la agrupación. `strict` es el valor predetermiando recomendado, y dará como resultado en el uso de conexiones almacenadas en caché solamente cuando todos los parámetros de conexión coincidan exactamente. `relaxed` dará como resultado el uso de conexiones almacenadas en caché cuando se utilicen parámetros de conexión similares. Esto puede resultar en el aumento del uso de la caché, con el riesgo de perder información de conexión entre (por ejemplo) hosts virtuales.

  Este ajuste solamente se puede cambiar desde el fichero php.ini, y afecta al proceso completo; cualquier otro módulo dentro del proceso que utilice las mismas bibliotecas de ODBC también se verá afectado, incluyendo la Extensión ODBC Unificada.

  Advertencia

  `relaxed` no debería usarse en servidores compartidos, por razones de seguridad.

  Sugerencia

  Deje este ajuste a la configuración `strict` predeterminada a menos que tenga una buena razón para cambiarlo.

`pdo_odbc.db2_instance_name` string

  Si se compila PDO_ODBC usando el sabor `db2`, este ajuste establece el valor de la variable de entorno DB2INSTANCE en sistemas operativos Linux y UNIX al nombre especificado de la instancia de DB2. También habilita PDO_ODBC para resolver la ubicación de las bibliotecas de DB2 y realizar conexiones catalogadas a bases de datos DB2.

  Este ajuste solamente se puede cambiar desde el fichero php.ini, y afecta al proceso completo; cualquier otro módulo dentro del proceso que utilice las mismas bibliotescas de ODBC también se verá afectado, incluyendo la Extensión ODBC Unificada.

  Este ajuste no tiene efecto en Windows.

# PDO_ODBC DSN

(PECL PDO_ODBC >= 0.1.0)

PDO_ODBC DSN — Conexión a bases de datos ODBC o DB2

### Descripción

El Data Source Name (DSN) de PDO_ODBC se compone de los siguientes elementos:

Prefijo DSN

  El prefijo DSN es `odbc:`. Si se conecta a una base de datos catalogada en el controlador de ODBC Manager o en el catálogo de DB2, se puede añadir el nombre del catálogo de la base de datos al DSN.

DSN

  El nombre de la base de datos catalogada en el controlador ODBC Manager o el catálogo DB2. Alternativamente, se puede proporcionar una cadena de conexión completa para ODBC para conectarse a una base de datos como se describe en » http://www.connectionstrings.com/.

`UID`

  El nombre de usuario para la conexión. Si se especifica el usuario en el DSN, PDO ignorará el valor del usuario en el argumento en el constructor PDO.

`PWD`

  La contraseña del usuario para la conexión. Si se especifica la contraseña en el DSN, PDO ignorará el valor de la contraseña en el argumento en el constructor PDO.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Al pasar una string vacía al argumento de contraseña en el constructor PDO, `pwd` no se incluía en la cadena de conexión creada hasta ahora, pero el comportamiento ha sido modificado para incluirla como una cadena vacía. Pasar `null` para el argumento de contraseña en el constructor PDO produce el mismo comportamiento que antes.
8.4.0 | Cambio de comportamiento para ignorar por separado el argumento de nombre de usuario y el argumento de contraseña en el constructor PDO cuando el DSN contiene `uid` o `pwd`. Anteriormente, si cualquiera de `uid` o `pwd` estaba incluido en el DSN, los argumentos de nombre de usuario y contraseña en el constructor PDO eran ignorados.

### Ejemplos

Ejemplo #1 Ejemplo con PDO_ODBC DSN (controlador ODBC Manager)

El siguiente ejemplo muestra PDO_ODBC DSN para conectarse a una base de datos ODBC catalogada como testdb en el controlador ODBC Manager:

    odbc:testdb

Ejemplo #2 Ejemplo con PDO_ODBC DSN (conexión no catalogada IBM DB2)

El siguiente ejemplo muestra PDO_ODBC DSN para conectarse a una base de datos IBM DB2 llamada `SAMPLE` utilizando la sintaxis completa de ODBC DSN:

    odbc:DRIVER={IBM DB2 ODBC DRIVER};HOSTNAME=localhost;PORT=50000;DATABASE=SAMPLE;PROTOCOL=TCPIP;UID=db2inst1;PWD=ibmdb2;

Ejemplo #3 Ejemplo con PDO_ODBC DSN (conexión no catalogada Microsoft Access)

El siguiente ejemplo muestra PDO_ODBC DSN para conectarse a una base de datos Microsoft Access registrada en `C:\db.mdb` utilizando la sintaxis completa de ODBC DSN:

    odbc:Driver={Microsoft Access Driver (*.mdb)};Dbq=C:\\db.mdb;Uid=Admin

## Tabla de contenidos

- PDO_ODBC DSN — Conexión a bases de datos ODBC o DB2

# La clase Pdo\Odbc

(PHP 8 >= 8.4.0)

## Introducción

Una subclase de PDO que representa una conexión utilizando el controlador PDO ODBC.

## Sinopsis de la Clase

namespace Pdo;
class Odbc extends PDO {
/* Constantes heredadas */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Constantes */
public const int ATTR_USE_CURSOR_LIBRARY;
public const int ATTR_ASSUME_UTF8;
public const int SQL_USE_IF_NEEDED;
public const int SQL_USE_DRIVER;
public const int SQL_USE_ODBC;
/* Métodos heredados */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Constantes predefinidas

`Pdo\Odbc::ATTR_USE_CURSOR_LIBRARY`

  Esta opción controla el uso de la biblioteca de cursoes ODBC. La biblioteca de cursoes ODBC admite ciertas funcionalidades avanzadas de ODBC (por ejemplo, cursoes desplazables por bloques), que pueden no estar implementadas por el controlador. Se admiten los siguientes valores:

  `Pdo\Odbc::SQL_USE_IF_NEEDED`
    Utiliza la biblioteca de cursoes ODBC si es necesario. Este es el valor por omisión.
  `Pdo\Odbc::SQL_USE_DRIVER`
    No utilizar nunca la biblioteca de cursoes ODBC.
  `Pdo\Odbc::SQL_USE_ODBC`
    Utilizar siempre la biblioteca de cursoes ODBC.
`Pdo\Odbc::ATTR_ASSUME_UTF8`
  Solo para Windows. Si `true`, los datos de caracteres codificados en UTF-16 (`CHAR`, `VARCHAR` y `LONGVARCHAR`) se convierten a UTF-8 al leer o escribir datos en la base de datos. Si `false` (el valor por omisión), la conversión de la codificación de caracteres puede ser realizada por el controlador.

# Funciones del controlador PDO PostgreSQL (PDO_PGSQL)

## Introducción

PDO_PGSQL es un controlador que implementa la PHP Data Objects (PDO) para permitir el acceso de PHP a las bases de datos PostgreSQL.

## Tipos de recursos

Esta extensión define un recurso de flujo, devuelto por la función PDO::pgsqlLOBOpen().

## Instalación

Utilice --with-pdo-pgsql[=DIR] para instalar la extensión PDO PostgreSQL, donde el opcional `[=DIR]` es el directorio base de la instalación de PostgreSQL o la ruta a pg_config.

    $ ./configure --with-pdo-pgsql

## Constantes predefinidas

Las constantes a continuación son definidas por este controlador y solo estarán disponibles cuando la extensión haya sido compilada en PHP o cargada dinámicamente del motor de ejecución. Además, estas constantes específicas del controlador deberían ser usadas solo si se usa este controlador. Usar atributos específicos de un controlador con otro controlador podría causar un comportamiento inesperado. PDO::getAttribute() podría ser usado para obtener el atributo `PDO::ATTR_DRIVER_NAME` para verificar el controlador, si su código puede funcionar en múltiples controladores.

`PDO::PGSQL_ATTR_DISABLE_PREPARES` (int)
  Alias de `Pdo\Pgsql::ATTR_DISABLE_PREPARES`.

## Notas generales

> Nota:

> Los campos `bytea` se devuelven en forma de flujo.

# PDO_PGSQL DSN

(PHP 5 >= 5.1.0, PHP 7, PECL PDO_PGSQL >= 0.1.0)

PDO_PGSQL DSN — Conexión a las bases de datos PostgreSQL

### Descripción

El Data Source Name (DSN) de PDO_PGSQL se compone de los siguientes elementos, delimitados por espacios o puntos y comas :

Prefijo DSN

  El prefijo DSN es `pgsql:`.

`host`

  El host donde se encuentra el servidor de base de datos.

`port`

  El puerto donde se encuentra el servidor de base de datos.

`dbname`

  El nombre de la base de datos.

`user`

  El nombre de usuario para la conexión. Si se especifica el usuario en el DSN, PDO ignorará el valor del usuario en el argumento del constructor PDO.

`password`

  La contraseña del usuario para la conexión. Si se especifica la contraseña en el DSN, PDO ignorará el valor de la contraseña en el argumento del constructor PDO.

`sslmode`

  El modo SSL. Los valores admitidos y su significado se listan en la sección » Documentación PostgreSQL.

> Nota: Todos los puntos y comas en la cadena DSN son reemplazados por espacios, porque PostgreSQL espera este formato. Esto implica que los puntos y comas en uno de los componentes (por ejemplo `password` o `dbname`) no son soportados.

### Ejemplos

Ejemplo #1 Ejemplos con PDO_PGSQL DSN

El siguiente ejemplo muestra un PDO_PGSQL DSN para conectarse a una base de datos PostgreSQL :

    pgsql:host=localhost;port=5432;dbname=testdb;user=bruce;password=mypass

El siguiente ejemplo muestra un PDO_PGSQL DSN para conectarse a una base de datos PostgreSQL a través del socket Unix /tmp/.s.PGSQL.5432 :

    pgsql:host=/tmp;port=5432;dbname=testdb;user=bruce;password=mypass

# PDO::pgsqlCopyFromArray

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyFromArray — Alias de Pdo\Pgsql::copyFromArray()

### Descripción

public function PDO::pgsqlCopyFromArray(
string `$tableName`,
array `$rows`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

Este método es un alias de: Pdo\Pgsql::copyFromArray().

# PDO::pgsqlCopyFromFile

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyFromFile — Alias de Pdo\Pgsql::copyFromFile()

### Descripción

public function PDO::pgsqlCopyFromFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

Este método es un alias de: Pdo\Pgsql::copyFromFile().

# PDO::pgsqlCopyToArray

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyToArray — Alias de Pdo\Pgsql::copyToArray()

### Descripción

public function PDO::pgsqlCopyToArray(
string `$tableName`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): array|false

Este método es un alias de: Pdo\Pgsql::copyToArray().

# PDO::pgsqlCopyToFile

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyToFile — Alias de Pdo\Pgsql::copyToFile()

### Descripción

public function PDO::pgsqlCopyToFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

Este método es un alias de: Pdo\Pgsql::copyToFile().

# PDO::pgsqlGetNotify

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

PDO::pgsqlGetNotify — Alias de Pdo\Pgsql::getNotify()

### Descripción

public function PDO::pgsqlGetNotify(int `$fetchMode` = PDO::FETCH_DEFAULT, int `$timeoutMilliseconds` = 0): array|false

Este método es un alias de: Pdo\Pgsql::getNotify().

# PDO::pgsqlGetPid

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

PDO::pgsqlGetPid — Alias de Pdo\Pgsql::getPid()

### Descripción

public function PDO::pgsqlGetPid(): int

Este método es un alias de: Pdo\Pgsql::getPid().

# PDO::pgsqlLOBCreate

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBCreate — Alias de Pdo\Pgsql::lobCreate()

### Descripción

public function PDO::pgsqlLOBCreate(): string

Este método es un alias de: Pdo\Pgsql::lobCreate().

# PDO::pgsqlLOBOpen

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBOpen — Alias de Pdo\Pgsql::lobOpen()

### Descripción

public function PDO::pgsqlLOBOpen(string `$oid`, string `$mode` = "rb"): resource|false

Este método es un alias de: Pdo\Pgsql::lobOpen().

# PDO::pgsqlLOBUnlink

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBUnlink — Alias de Pdo\Pgsql::lobUnlink()

### Descripción

public function PDO::pgsqlLOBUnlink(string `$oid`): bool

Este método es un alias de: Pdo\Pgsql::lobUnlink().

## Tabla de contenidos

- PDO_PGSQL DSN — Conexión a las bases de datos PostgreSQL
- PDO::pgsqlCopyFromArray — Alias de Pdo\Pgsql::copyFromArray
- PDO::pgsqlCopyFromFile — Alias de Pdo\Pgsql::copyFromFile
- PDO::pgsqlCopyToArray — Alias de Pdo\Pgsql::copyToArray
- PDO::pgsqlCopyToFile — Alias de Pdo\Pgsql::copyToFile
- PDO::pgsqlGetNotify — Alias de Pdo\Pgsql::getNotify
- PDO::pgsqlGetPid — Alias de Pdo\Pgsql::getPid
- PDO::pgsqlLOBCreate — Alias de Pdo\Pgsql::lobCreate
- PDO::pgsqlLOBOpen — Alias de Pdo\Pgsql::lobOpen
- PDO::pgsqlLOBUnlink — Alias de Pdo\Pgsql::lobUnlink

# La clase Pdo\Pgsql

(PHP 8 >= 8.4.0)

## Introducción

Una subclase de PDO que representa una conexión utilizando el controlador PDO PostgreSQL.

Este controlador admite un analizador de consultas SQL dedicado para el dialecto PostgreSQL. Puede gestionar los siguientes elementos:

- Los literales de string simples y dobles, con el duplicado como mecanismo de escape
- Los literales de string "escapados" de estilo C
- Los literales de string en dólares
- Dos guiones y los comentarios de estilo C (no anidados)
- El soporte de `??` como secuencia de escape para el operador `?`.

## Sinopsis de la Clase

namespace Pdo;
class Pgsql extends PDO {
/* Constantes heredadas */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Constantes */
public const int ATTR_DISABLE_PREPARES;
public const int ATTR_RESULT_MEMORY_SIZE;
public const int TRANSACTION_IDLE;
public const int TRANSACTION_ACTIVE;
public const int TRANSACTION_INTRANS;
public const int TRANSACTION_INERROR;
public const int TRANSACTION_UNKNOWN;
/* Métodos */
public function copyFromArray(
string `$tableName`,
array `$rows`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool
public function copyFromFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool
public function copyToArray(
string `$tableName`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): array|false
public function copyToFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool
public function escapeIdentifier(string `$input`): string
public function getNotify(int `$fetchMode` = `PDO::FETCH_DEFAULT`, int `$timeoutMilliseconds` = 0): array|false
public function getPid(): int
public function lobCreate(): string|false
public function lobOpen(string `$oid`, string `$mode` = "rb"): resource|false
public function lobUnlink(string `$oid`): bool
public function setNoticeCallback(?callable `$callback`): void
/* Métodos heredados */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Constantes predefinidas

`Pdo\Pgsql::ATTR_DISABLE_PREPARES`
  Envía la consulta y los argumentos al servidor en una sola vez, evitando la necesidad de crear una sentencia preparada nombrada por separado. Si la consulta va a ser ejecutada una sola vez, esto puede reducir la latencia evitando un viaje de ida y vuelta innecesario al servidor.
`Pdo\Pgsql::ATTR_RESULT_MEMORY_SIZE`
  Devuelve la cantidad de memoria, en bytes, asignada a la instancia de PDOStatement del resultado de la consulta especificada, o `null` si no existe ningún resultado antes de la ejecución de la consulta.
`Pdo\Pgsql::TRANSACTION_IDLE`
`Pdo\Pgsql::TRANSACTION_ACTIVE`
`Pdo\Pgsql::TRANSACTION_INTRANS`
`Pdo\Pgsql::TRANSACTION_INERROR`
`Pdo\Pgsql::TRANSACTION_UNKNOWN`

# Pdo\Pgsql::copyFromArray

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyFromArray — Copia datos de un array PHP a una tabla

### Descripción

public function Pdo\Pgsql::copyFromArray(
string `$tableName`,
array `$rows`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

Copia datos del array `rows` a la tabla `tableName` utilizando `separator` como delimitador de campos y la lista `fields`.

### Parámetros

`tableName`
  Una cadena de caracteres que contiene el nombre de la tabla.
`rows`
  Un array indexado de strings con los campos separados por `separator`.
`separator`
  Un delimitador utilizado para separar los campos en una entrada del array `rows`.
`nullAs`
  Cómo interpretar los valores `NULL`.
`fields`
  La lista de campos a insertar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- Pdo\Pgsql::copyToArray() - Copia datos de una tabla a un array PHP
- Pdo\Pgsql::copyFromFile() - Copia datos de un fichero a una tabla
- Pdo\Pgsql::copyToFile() - Copia datos de una tabla a un fichero

# Pdo\Pgsql::copyFromFile

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyFromFile — Copia datos de un fichero a una tabla

### Descripción

public function Pdo\Pgsql::copyFromFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

Copia datos de un fichero especificado por `filename` a la tabla `tableName` utilizando `separator` como delimitador de campos y la lista `fields`

### Parámetros

`tableName`
  Una cadena de caracteres que contiene el nombre de la tabla.
`filename`
  El nombre del fichero desde el cual importar los datos.
`separator`
  Un delimitador utilizado para separar los campos en una entrada del array `rows`.
`nullAs`
  Cómo interpretar los valores `NULL`.
`fields`
  La lista de campos a insertar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- Pdo\Pgsql::copyToFile() - Copia datos de una tabla a un fichero
- Pdo\Pgsql::copyFromArray() - Copia datos de un array PHP a una tabla
- Pdo\Pgsql::copyToArray() - Copia datos de una tabla a un array PHP

# Pdo\Pgsql::copyToArray

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyToArray — Copia datos de una tabla a un array PHP

### Descripción

public function Pdo\Pgsql::copyToArray(
string `$tableName`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): array|false

Copia datos de `tableName` a un array utilizando `separator` como delimitador de campos y la lista `fields`.

### Parámetros

`tableName`
  Una cadena de caracteres que contiene el nombre de la tabla.
`separator`
  Un delimitador utilizado para separar los campos en una entrada del array `rows`.
`nullAs`
  Cómo interpretar los valores `NULL`.
`fields`
  La lista de campos a exportar.

### Valores devueltos

Devuelve un array de filas, o `false` si ocurre un error.

### Ver también

- Pdo\Pgsql::copyFromArray() - Copia datos de un array PHP a una tabla
- Pdo\Pgsql::copyFromFile() - Copia datos de un fichero a una tabla
- Pdo\Pgsql::copyToFile() - Copia datos de una tabla a un fichero

# Pdo\Pgsql::copyToFile

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyToFile — Copia datos de una tabla a un fichero

### Descripción

public function Pdo\Pgsql::copyToFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

Copia datos de la tabla al fichero especificado por `filename` utilizando `separator` como delimitador de campos y la lista `fields`.

### Parámetros

`tableName`
  Una cadena de caracteres que contiene el nombre de la tabla.
`filename`
  El nombre del fichero donde exportar los datos.
`separator`
  Un delimitador utilizado para separar los campos en una entrada del array `rows`.
`nullAs`
  Cómo interpretar los valores `NULL`.
`fields`
  La lista de campos a exportar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- Pdo\Pgsql::copyFromFile() - Copia datos de un fichero a una tabla
- Pdo\Pgsql::copyFromArray() - Copia datos de un array PHP a una tabla
- Pdo\Pgsql::copyToArray() - Copia datos de una tabla a un array PHP

# Pdo\Pgsql::escapeIdentifier

(PHP 8 >= 8.4.0)

Pdo\Pgsql::escapeIdentifier — Escapa una string para su uso como identificador SQL

### Descripción

public function Pdo\Pgsql::escapeIdentifier(string `$input`): string

Escapa una string para su uso como identificador SQL, como una tabla, una columna o un nombre de función. Esto es útil cuando el identificador proporcionado por el usuario podría contener caracteres especiales que no serían interpretados como parte del identificador por el analizador SQL, o cuando el identificador podría contener caracteres en mayúsculas cuya capitalización debería preservarse.

### Parámetros

`input`
  Una string que contiene el texto a escapar.

### Valores devueltos

Una string que contiene los datos escapados.

### Ejemplos

Ejemplo #1 Ejemplo de Pdo\Pgsql::escapeIdentifier()

    <?php
    $pdo = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);

    $unescapedTableName = 'UnescapedTableName';
    $pdo->exec("CREATE TABLE $unescapedTableName ()");

    $escapedTableName = $pdo->escapeIdentifier('EscapedTableName');
    $pdo->exec("CREATE TABLE $escapedTableName ()");

    $statement = $pdo->query(
      "SELECT relname FROM pg_stat_user_tables WHERE relname ilike '%tablename'"
    );

    var_export($statement->fetchAll(PDO::FETCH_COLUMN, 0));

    $tableNameWithSymbols = 'Table-Name-With-Symbols';
    $pdo->exec("CREATE TABLE $tableNameWithSymbols ()");
    ?>

Resultado del ejemplo anterior es similar a:

    array (
      0 => 'unescapedtablename',
      1 => 'EscapedTableName',
    )
    Fatal error: Uncaught PDOException: SQLSTATE[42601]: Syntax error: 7 ERROR:  syntax error at or near "Table"
    LINE 1: CREATE TABLE Table-Name-With-Symbols ()

### Ver también

- PDO::quote() - Protege una cadena para usarla en una consulta SQL PDO

# Pdo\Pgsql::getNotify

(PHP 8 >= 8.4.0)

Pdo\Pgsql::getNotify — Devuelve una notificación asíncrona

### Descripción

public function Pdo\Pgsql::getNotify(int `$fetchMode` = `PDO::FETCH_DEFAULT`, int `$timeoutMilliseconds` = 0): array|false

Devuelve un conjunto de resultados que representa una notificación asíncrona pendiente.

### Parámetros

`fetchMode`

  El formato en el que debe estar el conjunto de resultados, una de las constantes siguientes:

  - `PDO::FETCH_DEFAULT`
  - `PDO::FETCH_BOTH`
  - `PDO::FETCH_ASSOC`
  - `PDO::FETCH_NUM`
`timeoutMilliseconds`
  El tiempo de espera para una respuesta, en milisegundos.

### Valores devueltos

Si una o varias notificaciones están pendientes, devuelve una sola fila, con los campos `message` y `pid`, en caso contrario devuelve `false`.

### Errores/Excepciones

Se lanza una ValueError si `fetchMode` no es una de las constantes `PDO::FETCH_*` válidas.

Se lanza una ValueError si `timeoutMilliseconds` es inferior a `0`.

Se lanza una `E_WARNING` cuando `timeoutMilliseconds` es superior al valor que puede contener un entero firmado de 32 bits, en cuyo caso será el valor máximo de un entero firmado de 32 bits.

### Ver también

- PDO::query() - Prepara y ejecuta una consulta SQL sin marcadores de sustitución
- PDOStatement::fetch() - Recupera la siguiente línea de un conjunto de resultados PDO
- PDOStatement::fetchAll() - Recupera las líneas restantes de un conjunto de resultados

# Pdo\Pgsql::getPid

(PHP 8 >= 8.4.0)

Pdo\Pgsql::getPid — Devuelve el PID del proceso backend que gestiona esta conexión

### Descripción

public function Pdo\Pgsql::getPid(): int

Devuelve el PID del proceso backend que gestiona esta conexión. Cabe señalar que el PID pertenece a un proceso que se ejecuta en el host del servidor, y no en el host local.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el PID en forma de un int.

# Pdo\Pgsql::lobCreate

(PHP 8 >= 8.4.0)

Pdo\Pgsql::lobCreate — Crear un nuevo objeto grande

### Descripción

public function Pdo\Pgsql::lobCreate(): string|false

Pdo\Pgsql::lobCreate() crea un objeto grande y devuelve el OID que lo referencia. Puede abrirse para leer o escribir datos con Pdo\Pgsql::lobOpen().

El OID puede almacenarse en columnas de tipo OID y utilizarse para referenciar el objeto grande, sin que la fila crezca de manera arbitraria. El objeto grande continuará existiendo en la base de datos hasta que sea eliminado mediante la llamada a Pdo\Pgsql::lobUnlink().

Los objetos grandes son objetos voluminosos para utilizar. De hecho, es necesario llamar a Pdo\Pgsql::lobUnlink() antes de eliminar la última fila que referencia el OID en toda la base de datos; de lo contrario, los objetos grandes no referenciados permanecerán en el servidor indefinidamente. Además, los objetos grandes no tienen controles de acceso. Una alternativa es el tipo de columna bytea, que puede ser de hasta 1 GB de tamaño, y este tipo de columna gestiona de manera transparente el almacenamiento para un tamaño de fila óptimo.

> Nota: Esta función, y todas las manipulaciones del objeto grande, deben ser llamadas y realizadas dentro de una transacción.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el OID del nuevo objeto grande creado en caso de éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de Pdo\Pgsql::lobCreate()

Este ejemplo crea un nuevo objeto grande y copia el contenido de un fichero dentro. El OID es almacenado posteriormente en una tabla.

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->beginTransaction();
    $oid = $db->lobCreate();
    $stream = $db->lobOpen($oid, 'w');
    $local = fopen($filename, 'rb');
    stream_copy_to_stream($local, $stream);
    $local = null;
    $stream = null;
    $stmt = $db->prepare("INSERT INTO BLOBS (ident, oid) VALUES (?, ?)");
    $stmt->execute([$some_id, $oid]);
    $db->commit();
    ?>

### Ver también

- Pdo\Pgsql::lobOpen() - Abre un flujo sobre un objeto grande existente
- Pdo\Pgsql::lobUnlink() - Elimina un objeto grande
- pg_lo_create() - Crea un objeto de gran tamaño de PostgreSQL
- pg_lo_open() - Abre un objeto de gran tamaño de PostgreSQL

# Pdo\Pgsql::lobOpen

(PHP 8 >= 8.4.0)

Pdo\Pgsql::lobOpen — Abre un flujo sobre un objeto grande existente

### Descripción

public function Pdo\Pgsql::lobOpen(string `$oid`, string `$mode` = "rb"): resource|false

Pdo\Pgsql::lobOpen() abre un flujo para acceder a los datos referenciados por `oid`. Todas las funciones habituales del sistema de ficheros, tales como fread(), fwrite() o fgets() pueden ser utilizadas para manipular el contenido del flujo.

> Nota: Esta función, y todas las manipulaciones del objeto grande, deben ser llamadas y realizadas dentro de una transacción.

### Parámetros

`oid`
  Un identificador de objeto grande.
`mode`
  Si el modo es `r`, abre el flujo en lectura. Si el modo es `w`, abre el flujo en escritura.

### Valores devueltos

Devuelve un recurso de flujo en caso de éxito, o `false` si ocurre un error

### Ejemplos

Ejemplo #1 Ejemplo de Pdo\Pgsql::lobOpen()

Según el ejemplo de Pdo\Pgsql::lobCreate(), este código extrae el objeto grande de la base de datos y lo devuelve al navegador.

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->beginTransaction();
    $stmt = $db->prepare("SELECT oid FROM BLOBS WHERE ident = ?");
    $stmt->execute(array($some_id));
    $stmt->bindColumn('oid', $oid, PDO::PARAM_STR);
    $stmt->fetch(PDO::FETCH_BOUND);
    $stream = $db->pgsqlLOBOpen($oid, 'r');
    header("Content-type: application/octet-stream");
    fpassthru($stream);
    ?>

### Ver también

- Pdo\Pgsql::lobCreate() - Crear un nuevo objeto grande
- Pdo\Pgsql::lobUnlink() - Elimina un objeto grande
- pg_lo_create() - Crea un objeto de gran tamaño de PostgreSQL
- pg_lo_open() - Abre un objeto de gran tamaño de PostgreSQL

# Pdo\Pgsql::lobUnlink

(PHP 8 >= 8.4.0)

Pdo\Pgsql::lobUnlink — Elimina un objeto grande

### Descripción

public function Pdo\Pgsql::lobUnlink(string `$oid`): bool

Elimina un objeto grande de la base de datos identificado por OID.

> Nota: Esta función, y todas las manipulaciones del objeto grande, deben ser llamadas y realizadas dentro de una transacción.

### Parámetros

`oid`
  Un identificador de objeto grande.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de Pdo\Pgsql::lobUnlink()

Este ejemplo elimina un objeto grande de la base de datos antes de eliminar la fila que lo referencia en la tabla blobs. Se utiliza en los ejemplos de Pdo\Pgsql::lobCreate() y Pdo\Pgsql::lobOpen().

    <?php
    $db = new PDO('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->beginTransaction();
    $db->pgsqlLOBUnlink($oid);
    $stmt = $db->prepare("DELETE FROM BLOBS where ident = ?");
    $stmt->execute(array($some_id));
    $db->commit();
    ?>

### Ver también

- Pdo\Pgsql::lobCreate() - Crear un nuevo objeto grande
- Pdo\Pgsql::lobOpen() - Abre un flujo sobre un objeto grande existente
- pg_lo_create() - Crea un objeto de gran tamaño de PostgreSQL
- pg_lo_open() - Abre un objeto de gran tamaño de PostgreSQL

# Pdo\Pgsql::setNoticeCallback

(PHP 8 >= 8.4.0)

Pdo\Pgsql::setNoticeCallback — Establece una función de retrollamada para gestionar los mensajes de aviso y advertencia generados por el servidor

### Descripción

public function Pdo\Pgsql::setNoticeCallback(?callable `$callback`): void

Establece una función de retrollamada para gestionar los mensajes de aviso y advertencia generados por el servidor. Esto incluye los mensajes emitidos por PostgreSQL, así como aquellos generados por las funciones SQL definidas por el usuario utilizando `RAISE`. Tenga en cuenta que la recepción efectiva de estos mensajes depende del parámetro del servidor `client_min_messages`.

### Parámetros

`callback`
  Si se pasa `null`, la función de retrollamada se reinicializa a su estado por omisión.

  De lo contrario, la función de retrollamada es una retrollamada con la siguiente firma:

  function handler(string `$message`): void
  `message`
    Un mensaje generado por el servidor.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo de Pdo\Pgsql::setNoticeCallback()

    <?php
    $pdo = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);

    $pdo->exec('CREATE TABLE parent(id int primary key)');
    $pdo->exec('CREATE TABLE child(id int references parent)');

    $pdo->setNoticeCallback(function ($message) {
        echo $message;
    });

    $pdo->exec('TRUNCATE parent CASCADE');
    ?>

Resultado del ejemplo anterior es similar a:

    NOTICE:  truncate cascades to table "child"

## Tabla de contenidos

- Pdo\Pgsql::copyFromArray — Copia datos de un array PHP a una tabla
- Pdo\Pgsql::copyFromFile — Copia datos de un fichero a una tabla
- Pdo\Pgsql::copyToArray — Copia datos de una tabla a un array PHP
- Pdo\Pgsql::copyToFile — Copia datos de una tabla a un fichero
- Pdo\Pgsql::escapeIdentifier — Escapa una string para su uso como identificador SQL
- Pdo\Pgsql::getNotify — Devuelve una notificación asíncrona
- Pdo\Pgsql::getPid — Devuelve el PID del proceso backend que gestiona esta conexión
- Pdo\Pgsql::lobCreate — Crear un nuevo objeto grande
- Pdo\Pgsql::lobOpen — Abre un flujo sobre un objeto grande existente
- Pdo\Pgsql::lobUnlink — Elimina un objeto grande
- Pdo\Pgsql::setNoticeCallback — Establece una función de retrollamada para gestionar los mensajes de aviso y advertencia generados por el servidor

# Funciones del controlador PDO SQLite (PDO_SQLITE)

## Introducción

PDO_SQLITE es un controlador que implementa la PHP Data Objects (PDO) para permitir el acceso de PHP a las bases de datos SQLite 3.

> Nota:

> PDO_SQLITE permite el uso de strings fuera de los flujos con `PDO::PARAM_LOB`.

## Instalación

El controlador PDO_SQLITE PDO está habilitado por omisión. Para deshabilitarlo, se puede usar --without-pdo-sqlite[=DIR], donde el parámetro opcional `[=DIR]` es el directorio base de instalación de sqlite. A partir de PHP 7.4.0 se requiere » libsqlite ≥ 3.5.0. Anteriormente, si libsqlite incluido podría haberse usado en su lugar, por omisión, si `[=DIR]` era omitido.

> Nota: Configuración adicional en Windows a partir de PHP 7.4.0

> Para hacer funcionar esta extensión, algunas bibliotecas DLL deben estar disponibles a través del PATH del sistema Windows. Lea la F.A.Q titulada "Cómo agregar mi carpeta PHP a mi PATH de Windows" para más información. Copiar las bibliotecas DLL desde la carpeta PHP a la carpeta del sistema de Windows también funciona (ya que la carpeta del sistema está por defecto en el PATH del sistema), pero este método no es recomendado. Esta extensión requiere que los siguientes archivos estén en el PATH: libsqlite3.dll.

# PDO_SQLITE DSN

(PHP 5 >= 5.1.0, PHP 7, PECL PDO_SQLITE >= 0.2.0)

PDO_SQLITE DSN — Conexión a bases de datos SQLite

### Descripción

El Data Source Name (DSN) de PDO_SQLITE se compone de los siguientes elementos:

Prefijo DSN (SQLite 3)

  El prefijo DSN es `sqlite:`.

  - Para acceder a una base de datos en el disco, debe añadirse la ruta absoluta al prefijo DSN.

  - Para crear una base de datos en memoria, debe añadirse `:memory:` al prefijo DSN.

  - Si el DSN contiene solo el prefijo DSN, se creará una base de datos temporal, la cual será eliminada cuando se cierre la conexión.

### Ejemplos

Ejemplo #1 Ejemplos con PDO_SQLITE DSN

Los ejemplos siguientes muestran PDO_SQLITE DSN para conectarse a las bases de datos SQLite:

    sqlite:/opt/databases/mydb.sq3
    sqlite::memory:
    sqlite:

# PDO::sqliteCreateAggregate

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo_sqlite >= 1.0.0)

PDO::sqliteCreateAggregate — Alias de Pdo\Sqlite::createAggregate()

### Descripción

public function PDO::sqliteCreateAggregate(
string `$name`,
callable `$step`,
callable `$finalize`,
int `$numArgs` = -1
): bool

Este método es un alias de: Pdo\Sqlite::createAggregate().

# PDO::sqliteCreateCollation

(PHP 5 >= 5.3.11, PHP 7, PHP 8)

PDO::sqliteCreateCollation — Alias de Pdo\Sqlite::createCollation()

### Descripción

public function PDO::sqliteCreateCollation(string `$name`, callable `$callback`): bool

Este método es un alias de: Pdo\Sqlite::createCollation().

# PDO::sqliteCreateFunction

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo_sqlite >= 1.0.0)

PDO::sqliteCreateFunction — Alias de Pdo\Sqlite::createFunction()

### Descripción

public function PDO::sqliteCreateFunction(
string `$function_name`,
callable `$callback`,
int `$num_args` = -1,
int `$flags` = 0
): bool

Este método es un alias de: Pdo\Sqlite::createFunction().

### Historial de cambios

Versión | Descripción
--- | ---
7.1.4 | El argumento `flags` ha sido añadido.

## Tabla de contenidos

- PDO_SQLITE DSN — Conexión a bases de datos SQLite
- PDO::sqliteCreateAggregate — Alias de Pdo\Sqlite::createAggregate
- PDO::sqliteCreateCollation — Alias de Pdo\Sqlite::createCollation
- PDO::sqliteCreateFunction — Alias de Pdo\Sqlite::createFunction

# La clase Pdo\Sqlite

(PHP 8 >= 8.4.0)

## Introducción

Una subclase de PDO que representa una conexión utilizando el controlador PDO SQLite.

Este controlador admite un analizador de consultas SQL dedicado para el dialecto SQLite. Puede gestionar los siguientes elementos:

- Los literales de string simples, dobles y en dólares, con el doblado como mecanismo de escape.
- Las comillas entre corchetes para los identificadores.
- Dos guiones y los comentarios de estilo C (no anidados).

## Sinopsis de la Clase

class Pdo\Sqlite extends PDO {
/* Constantes heredadas */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Constantes */
public const int DETERMINISTIC;
public const int OPEN_READONLY;
public const int OPEN_READWRITE;
public const int OPEN_CREATE;
public const int ATTR_OPEN_FLAGS;
public const int ATTR_READONLY_STATEMENT;
public const int ATTR_EXTENDED_RESULT_CODES;
/* Métodos */
public function createAggregate(
string `$name`,
callable `$step`,
callable `$finalize`,
int `$numArgs` = -1
): bool
public function createCollation(string `$name`, callable `$callback`): bool
public function createFunction(
string `$function_name`,
callable `$callback`,
int `$num_args` = -1,
int `$flags` = 0
): bool
public function loadExtension(string `$name`): void
public function openBlob(
string `$table`,
string `$column`,
int `$rowid`,
?string `$dbname` = "main",
int `$flags` = `Pdo\Sqlite::OPEN_READONLY`
): resource|false
/* Métodos heredados */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Constantes predefinidas

`Pdo\Sqlite::DETERMINISTIC`
`Pdo\Sqlite::OPEN_READONLY`
`Pdo\Sqlite::OPEN_READWRITE`
`Pdo\Sqlite::OPEN_CREATE`
`Pdo\Sqlite::ATTR_OPEN_FLAGS`
`Pdo\Sqlite::ATTR_READONLY_STATEMENT`
`Pdo\Sqlite::ATTR_EXTENDED_RESULT_CODES`

# Pdo\Sqlite::createAggregate

(PHP 8 >= 8.4.0)

Pdo\Sqlite::createAggregate — Registra una función de agregación definida por el usuario para su uso en instrucciones SQL

### Descripción

public function Pdo\Sqlite::createAggregate(
string `$name`,
callable `$step`,
callable `$finalize`,
int `$numArgs` = -1
): bool

Este método es similar a Pdo\Sqlite::createFunction() excepto que registra funciones que pueden ser utilizadas para calcular un resultado agregado sobre el conjunto de filas de una consulta.

La principal diferencia entre este método y Pdo\Sqlite::createFunction() es que se necesitan dos funciones para manejar la agregación.

Sugerencia

Utilizando este método, es posible reemplazar las funciones SQL nativas.

### Parámetros

`name`
  El nombre de la función utilizado en las instrucciones SQL.
`step`
  La función de retrollamada llamada para cada fila del conjunto de resultados. La función de retrollamada debe acumular el resultado y almacenarlo en el contexto de agregación.

  Esta función debe ser definida como sigue:

  function step(
  mixed `$context`,
  int `$rownumber`,
  mixed `$value`,
  mixed `...$values`
  ): mixed
  `context`
    `null` para la primera fila; en las filas siguientes, tendrá el valor que fue previamente retornado por la función de retrollamada; debe utilizarse esto para mantener el estado de la agregación.
  `rownumber`
    El número de la fila actual.
  `value`
    El primer argumento pasado a la agregación.
  `values`
    Los argumentos adicionales pasados a la agregación.
  El valor de retorno de esta función será utilizado como argumento `context` en la siguiente llamada a la función de retrollamada o de finalización.
`finalize`
  La función de retrollamada para agregar los datos "step" de cada fila. Una vez que todas las filas han sido procesadas, esta función será llamada, y debería entonces tomar los datos del contexto de agregación y retornar el resultado. Esta función de retrollamada debe retornar un tipo comprendido por SQLite (es decir, un tipo escalar).

  Esta función debe ser definida como sigue:

  function fini(mixed `$context`, int `$rowcount`): mixed
  `context`

    Contiene el valor de retorno de la última llamada a la función de retrollamada.

  `rowcount`

    Contiene el número de filas sobre las cuales se realizó la agregación.

  El valor de retorno de esta función será utilizado como valor de retorno para la agregación.
`numArgs`
  Indicación al analizador SQLite si la función de retrollamada acepta un número predeterminado de argumentos.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de Pdo\Sqlite::createAggregate()

En este ejemplo, se creará una función de agregación personalizada llamada `max_length` que puede ser utilizada en las consultas SQL.

En este ejemplo, se creará una función de agregación llamada `max_length` que calculará la longitud del string más largo en una de las columnas de la tabla. Para cada fila, la función `max_len_step` es llamada y pasa un parámetro `$context`. El parámetro de contexto es como cualquier otra variable PHP y puede ser definido para contener un array o incluso un object. En este ejemplo, se utiliza para contener la longitud máxima que se ha visto hasta el momento; si el $string tiene una longitud mayor que la longitud máxima actual, se actualiza el contexto para contener esta nueva longitud máxima.

Después de que todas las filas han sido procesadas, SQLite llama a la función `max_len_finalize` para determinar el resultado agregado. Es posible realizar algún tipo de cálculo basado en los datos en `$context`. En este ejemplo básico, el resultado fue calculado a medida que la consulta progresaba, por lo que el valor de contexto puede ser retornado directamente.

    <?php
    $data = [
       'one',
       'two',
       'three',
       'four',
       'five',
       'six',
       'seven',
       'eight',
       'nine',
       'ten',
    ];
    $db = new Pdo\Sqlite('sqlite::memory:');
    $db->exec("CREATE TABLE strings(a)");
    $insert = $db->prepare('INSERT INTO strings VALUES (?)');
    foreach ($data as $str) {
        $insert->execute(array($str));
    }
    $insert = null;

    function max_len_step($context, $row_number, $string)
    {
        if (strlen($string) > $context) {
            $context = strlen($string);
        }
        return $context;
    }

    function max_len_finalize($context, $row_count)
    {
        return $context === null ? 0 : $context;
    }

    $db->createAggregate('max_len', 'max_len_step', 'max_len_finalize');

    var_dump($db->query('SELECT max_len(a) from strings')->fetchAll());

    ?>

Sugerencia

NO se recomienda almacenar una copia de los valores en el contexto y procesarlos al final, ya que se obligaría a SQLite a utilizar mucha memoria para procesar la consulta - imagine cuánta memoria se necesitaría si un millón de filas fueran almacenadas en memoria, cada una conteniendo un string de 32 bytes de longitud.

### Ver también

- Pdo\Sqlite::createFunction() - Registra una función de usuario para su uso en las sentencias SQL
- Pdo\Sqlite::createCollation() - Registra una función de usuario de ordenación para su uso en las sentencias SQL
- sqlite_create_function()
- sqlite_create_aggregate()

# Pdo\Sqlite::createCollation

(PHP 8 >= 8.4.0)

Pdo\Sqlite::createCollation — Registra una función de usuario de ordenación para su uso en las sentencias SQL

### Descripción

public function Pdo\Sqlite::createCollation(string `$name`, callable `$callback`): bool

Este método es similar a Pdo\Sqlite::createFunction() salvo que registra funciones que se utilizan para ordenar strings.

### Parámetros

`name`
  El nombre de la función de ordenación SQL a crear o redefinir.
`callback`
  La retrollamada que define el comportamiento de una ordenación. Debe aceptar dos strings y devolver `-1`, `0`, o `1` si el primer string se ordena antes, es idéntico o después del segundo string respectivamente. Una función interna que se comporta de esta manera es strcmp().

  Esta función debe ser definida como sigue:

  function collation(string `$string1`, string `$string2`): int

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de Pdo\Sqlite::createCollation()

    <?php
    $db = new Pdo\Sqlite('sqlite::memory:');
    $db->exec("CREATE TABLE test (col1 string)");
    $db->exec("INSERT INTO test VALUES ('a1')");
    $db->exec("INSERT INTO test VALUES ('a10')");
    $db->exec("INSERT INTO test VALUES ('a2')");

    $db->sqliteCreateCollation('NATURAL_CMP', 'strnatcmp');
    foreach ($db->query("SELECT col1 FROM test ORDER BY col1") as $row) {
      echo $row['col1'] . "\n";
    }
    echo "\n";
    foreach ($db->query("SELECT col1 FROM test ORDER BY col1 COLLATE NATURAL_CMP") as $row) {
      echo $row['col1'] . "\n";
    }
    ?>

El ejemplo anterior mostrará:

    a1
    a10
    a2

    a1
    a2
    a10

### Ver también

- Pdo\Sqlite::createFunction() - Registra una función de usuario para su uso en las sentencias SQL
- Pdo\Sqlite::createAggregate() - Registra una función de agregación definida por el usuario para su uso en instrucciones SQL
- sqlite_create_function()
- sqlite_create_aggregate()

# Pdo\Sqlite::createFunction

(PHP 8 >= 8.4.0)

Pdo\Sqlite::createFunction — Registra una función de usuario para su uso en las sentencias SQL

### Descripción

public function Pdo\Sqlite::createFunction(
string `$function_name`,
callable `$callback`,
int `$num_args` = -1,
int `$flags` = 0
): bool

Este método permite que las funciones PHP sean registradas con SQLite como funciones definidas por el usuario, de modo que puedan ser llamadas en las consultas SQL. La función definida puede ser utilizada en cualquier consulta SQL que permita llamadas a funciones, por ejemplo `SELECT`, `UPDATE`, o disparadores.

Sugerencia

Utilizando este método, es posible reemplazar las funciones SQL nativas.

### Parámetros

`function_name`
  El nombre de la función utilizado en las sentencias SQL.
`callback`
  La retrollamada para gestionar la función SQL definida.

  > Nota: La retrollamada debe retornar un tipo comprendido por SQLite (es decir, tipo escalar).

  Esta función debe ser definida como:

  function callback(mixed `$value`, mixed `...$values`): mixed
  `value`

    El primer argumento pasado a la función SQL.

  `values`

    Los argumentos adicionales pasados a la función SQL.

`num_args`
  El número de argumentos que la función SQL toma. Si este parámetro es `-1`, entonces la función SQL puede tomar cualquier número de argumentos.
`flags`
  Una máscara de bits de flags. Actualmente, solo `Pdo\Sqlite::DETERMINISTIC` es soportado, lo que especifica que la función retorna siempre el mismo resultado dados los mismos valores de entrada en una sola sentencia SQL.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de Pdo\Sqlite::createFunction()

En este ejemplo, tenemos una función que calcula la suma SHA256 de una string, luego la invierte. Cuando la sentencia SQL es ejecutada, retorna el valor del nombre de fichero transformado por nuestra función. Los datos retornados en $rows contienen el resultado procesado.

La ventaja de esta técnica es que no es necesario procesar el resultado utilizando un bucle `foreach` después de la ejecución de la consulta.

    <?php
    function sha256_and_reverse($string)
    {
        return strrev(hash('sha256', $string));
    }

    $db = new Pdo\Sqlite('sqlite::sqlitedb');
    $db->createFunction('sha256rev', 'sha256_and_reverse', 1);
    $rows = $db->query('SELECT sha256rev(filename) FROM files')->fetchAll();
    ?>

### Ver también

- Pdo\Sqlite::createAggregate() - Registra una función de agregación definida por el usuario para su uso en instrucciones SQL
- Pdo\Sqlite::createCollation() - Registra una función de usuario de ordenación para su uso en las sentencias SQL
- sqlite_create_function()
- sqlite_create_aggregate()

# Pdo\Sqlite::loadExtension

(PHP 8 >= 8.4.0)

Pdo\Sqlite::loadExtension — Descripción

### Descripción

public function Pdo\Sqlite::loadExtension(string `$name`): void
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Descripción.

### Parámetros

`name`
  Descripción.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

En qué casos esta función emite errores de nivel `E_*`, y/o lanza Exceptions.

### Ejemplos

Ejemplo #1 Ejemplo de Pdo\Sqlite::loadExtension()

Descripción.

    <?php
    echo "Ejemplo de código";
    ?>

El ejemplo anterior mostrará:

    Ejemplo de código

### Notas

> Nota: Todas las notas que no encuentran su lugar en otra sección deben ser colocadas aquí.

### Ver también

- ClassName::otherMethodName()
- some_function()

# Pdo\Sqlite::openBlob

(PHP 8 >= 8.4.0)

Pdo\Sqlite::openBlob — Descripción

### Descripción

public function Pdo\Sqlite::openBlob(
string `$table`,
string `$column`,
int `$rowid`,
?string `$dbname` = "main",
int `$flags` = `Pdo\Sqlite::OPEN_READONLY`
): resource|false
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Descripción.

### Parámetros

`table`
  Descripción.
`column`
  Descripción.
`rowid`
  Descripción.
`dbname`
  Descripción.
`flags`
  Uno de los `Pdo\Sqlite::OPEN_*`

### Valores devueltos

Descripción.

### Errores/Excepciones

Cuando esta función emite errores de nivel `E_*`, y/o lanza Exception.

### Ejemplos

Ejemplo #1 Ejemplo de Pdo\Sqlite::openBlob()

Descripción.

    <?php
    echo "Ejemplo de código";
    ?>

El ejemplo anterior mostrará:

    Ejemplo de código

### Notas

> Nota: Todas las notas que no encuentran su lugar en otro lugar deben ser colocadas aquí.

### Ver también

- ClassName::otherMethodName()
- some_function()

## Tabla de contenidos

- Pdo\Sqlite::createAggregate — Registra una función de agregación definida por el usuario para su uso en instrucciones SQL
- Pdo\Sqlite::createCollation — Registra una función de usuario de ordenación para su uso en las sentencias SQL
- Pdo\Sqlite::createFunction — Registra una función de usuario para su uso en las sentencias SQL
- Pdo\Sqlite::loadExtension — Descripción
- Pdo\Sqlite::openBlob — Descripción

- Instalación/Configuración
  - Instalación
  - Configuración en tiempo de ejecución
- Constantes predefinidas
  - Modos de recuperación
- Conexiones y gestor de conexión
- Transacciones y validación automática (autocommit)
- Consultas preparadas y procedimientos almacenados
- Los errores y su gestión
- Los objetos grandes (LOB)
- PDO — La clase PDO
  - PDO::beginTransaction — Inicia una transacción
  - PDO::commit — Valida una transacción
  - PDO::connect — Conecta a una base de datos y devuelve una subclase PDO para los controladores que lo soportan
  - PDO::__construct — Crea una instancia PDO que representa una conexión a la base de datos
  - PDO::errorCode — Devuelve el SQLSTATE asociado con la última operación sobre la base de datos
  - PDO::errorInfo — Devuelve las informaciones asociadas al error durante la última operación sobre la base de datos
  - PDO::exec — Ejecuta una consulta SQL y devuelve el número de filas afectadas
  - PDO::getAttribute — Recupera un atributo de una conexión a una base de datos
  - PDO::getAvailableDrivers — Devuelve la lista de controladores PDO disponibles
  - PDO::inTransaction — Verifica si se encuentra en una transacción
  - PDO::lastInsertId — Devuelve el identificador de la última fila insertada o el valor de una secuencia
  - PDO::prepare — Prepara una consulta para su ejecución y devuelve un objeto
  - PDO::query — Prepara y ejecuta una consulta SQL sin marcadores de sustitución
  - PDO::quote — Protege una cadena para usarla en una consulta SQL PDO
  - PDO::rollBack — Anula una transacción
  - PDO::setAttribute — Configura un atributo PDO
- PDOStatement — La clase PDOStatement
  - PDOStatement::bindColumn — Vincula una columna a una variable PHP
  - PDOStatement::bindParam — Vincula un parámetro a una variable específica
  - PDOStatement::bindValue — Asocia un valor a un parámetro
  - PDOStatement::closeCursor — Cierra el cursor, permitiendo que la consulta pueda ser ejecutada de nuevo
  - PDOStatement::columnCount — Devuelve el número de columnas en el conjunto de resultados
  - PDOStatement::debugDumpParams — Detalla una instrucción SQL preparada
  - PDOStatement::errorCode — Recupera las informaciones sobre el error asociado durante la última operación sobre la consulta
  - PDOStatement::errorInfo — Recupera las informaciones sobre el error asociado durante la última operación sobre la consulta
  - PDOStatement::execute — Ejecuta una consulta preparada
  - PDOStatement::fetch — Recupera la siguiente línea de un conjunto de resultados PDO
  - PDOStatement::fetchAll — Recupera las líneas restantes de un conjunto de resultados
  - PDOStatement::fetchColumn — Devuelve una columna de la siguiente fila de un conjunto de resultados
  - PDOStatement::fetchObject — Recupera la siguiente línea y la devuelve como objeto
  - PDOStatement::getAttribute — Recupera un atributo de consulta
  - PDOStatement::getColumnMeta — Devuelve las metadatos para una columna de un conjunto de resultados
  - PDOStatement::getIterator — Devuelve un iterador sobre el conjunto de resultados
  - PDOStatement::nextRowset — Avance al siguiente conjunto de resultados de un manejador de conjuntos de resultados múltiples
  - PDOStatement::rowCount — Devuelve el número de filas afectadas por la última llamada a la función PDOStatement::execute()
  - PDOStatement::setAttribute — Establece un atributo de consulta
  - PDOStatement::setFetchMode — Establece el modo de recuperación por defecto para esta consulta
- PDORow — La clase PDORow
- PDOException — La clase PDOException
- Controladores PDO
  - Controlador PDO CUBRID — Funciones del controlador PDO CUBRID (PDO_CUBRID)
  - Controlador PDO MS SQL Server — Microsoft SQL Server y Funciones del Controlador PDO Sybase (PDO_DBLIB)
  - Pdo\Dblib — La clase Pdo\Dblib
  - Controlador PDO Firebird — Funciones del controlador PDO Firebird (PDO_FIREBIRD)
  - Pdo\Firebird — La clase Pdo\Firebird
  - Controlador PDO IBM — Funciones del controlador PDO IBM (PDO_IBM)
  - Controlador PDO Informix — Funciones del controlador PDO Informix (PDO_INFORMIX)
  - Controlador PDO MySQL — Funciones del controlador PDO MySQL (PDO_MYSQL)
  - Pdo\Mysql — La clase Pdo\Mysql
  - Controlador PDO MS SQL Server — Funciones Microsoft del controlador PDO SQL Server (PDO_SQLSRV)
  - Controlador PDO Oracle — Funciones del controlador PDO Oracle (PDO_OCI)
  - Controladores PDO ODBC y DB2 — Funciones del controlador PDO ODBC y DB2 (PDO_ODBC)
  - Pdo\Odbc — La clase Pdo\Odbc
  - Controlador PDO PostgreSQL — Funciones del controlador PDO PostgreSQL (PDO_PGSQL)
  - Pdo\Pgsql — La clase Pdo\Pgsql
  - Controlador PDO SQLite — Funciones del controlador PDO SQLite (PDO_SQLITE)
  - Pdo\Sqlite — La clase Pdo\Sqlite

- DBA — Capa de abstracción de base de datos (estilo dbm)
  - Instalación/Configuración
  - Constantes predefinidas
  - Ejemplos
  - Dba\Connection — La clase Dba\Connection
  - Funciones de DBA
- ODBC — ODBC (Unificada)
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones ODBC
  - Odbc\Connection — La clase Odbc\Connection
  - Odbc\Result — La clase Odbc\Result
- PDO — PHP Data Objects
  - Instalación/Configuración
  - Constantes predefinidas
  - Conexiones y gestor de conexión
  - Transacciones y validación automática (autocommit)
  - Consultas preparadas y procedimientos almacenados
  - Los errores y su gestión
  - Los objetos grandes (LOB)
  - PDO — La clase PDO
  - PDOStatement — La clase PDOStatement
  - PDORow — La clase PDORow
  - PDOException — La clase PDOException
  - Controladores PDO

# Extensiones de bases de datos específicas del proveedor

# CUBRID

# Introducción

Estas funciones permiten acceder a servidores de bases de datos CUBRID. Se puede encontrar más información sobre CUBRID en » CUBRID.

La documentación de CUBRID se puede encontrar en » Documentación de CUBRID.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución
- Tipos de recursos

## Requerimientos

Para que estas funciones estén disponibles, se debe instalar CUBRID, y compilar la Biblioteca de PHP de CUBRID con soporte para CUBRID.

## Instalación

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/cubrid.

No hay biblioteca DLL para esta extensión PECL actualmente disponible. Consulte la sección Compilación en Windows.

Para obtener información sobre la instalación manual en Linux y en Windows, por favor, lea el fichero build-guide.html incluido en el paquete.

## Configuración en tiempo de ejecución

No existe configuración en tiempo de ejecución.

## Tipos de recursos

En CUBRID se usan cuatro tipos de recursos. El primero es un identificador de enlace para una conexión de base de datos, el segundo es un recurso que guarda el resultado de una consulta, y los dos últimos son recursos que guardan los resultados de una consulta de tipos de datos BLOB/CLOB.

## identificador de conexión

Un identificador de conexión devuelto por cubrid_connect(), cubrid_connect_with_url(), cubrid_pconnect() y cubrid_pconnect_with_url().

## identificador de solicitud

Un identificador de solicitud devuelto por cubrid_prepare() y cubrid_execute().

## identificador LOB

Un identificador LOB devuelto por cubrid_lob_get().

## identificador LOB2

Un identificador LOB devuelto por cubrid_lob2_new() u obtenido de un conjunto de resultados.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

Las constantes siguientes pueden ser utilizadas durante la ejecución de consultas SQL. Pueden ser pasadas a las funciones cubrid_prepare() y cubrid_execute().

Flags de ejecución SQL CUBRID
Constante | Descripción
--- | ---
`CUBRID_INCLUDE_OID` | Determina si se debe recuperar el OID durante la ejecución de la consulta.
`CUBRID_ASYNC` | Ejecuta la consulta en modo asíncrono.
`CUBRID_EXEC_QUERY_ALL` | Ejecuta la consulta en modo síncrono. Este flag debe ser definido durante la ejecución de consultas SQL múltiples.

Las constantes siguientes pueden ser utilizadas durante la recuperación de los resultados para especificar su comportamiento. Pueden ser pasadas a las funciones cubrid_fetch() y cubrid_fetch_array().

Flags de recuperación CUBRID
Constante | Descripción
--- | ---
`CUBRID_NUM` | Recupera el resultado de la consulta en forma de array numérico (con índices comenzando en 0).
`CUBRID_ASSOC` | Recupera el resultado de la consulta en forma de array asociativo.
`CUBRID_BOTH` | Recupera el resultado de la consulta tanto en forma de array numérico como de array asociativo (valor por defecto).
`CUBRID_OBJECT` | Recupera el resultado de la consulta en forma de objeto.
`CUBRID_LOB` | La constante CUBRID_LOB puede ser utilizada cuando se desea utilizar un objeto LOB. Puede ser pasada a las funciones cubrid_fetch(), cubrid_fetch_row(), cubrid_fetch_array(), cubrid_fetch_assoc() y cubrid_fetch_object().

Las constantes siguientes pueden ser utilizadas durante el posicionamiento del cursor en los resultados de la consulta. Pueden ser pasadas a o retornadas por la función cubrid_move_cursor().

Flags de posicionamiento del cursor CUBRID
Constante | Descripción
--- | ---
`CUBRID_CURSOR_FIRST` | Mueve el cursor actual a la primera posición del resultado.
`CUBRID_CURSOR_CURRENT` | Mueve el cursor actual a un valor por defecto si el origen no está especificado.
`CUBRID_CURSOR_LAST` | Mueve el cursor actual a la última posición del resultado.
`CUBRID_CURSOR_SUCCESS` | El valor retornado por la función cubrid_move_cursor() en caso de éxito. Este flag fue eliminado desde la versión 8.4.1.
`CUBRID_NO_MORE_DATA` | El valor retornado por la función cubrid_move_cursor() si ocurre un error. Este flag fue eliminado desde la versión 8.4.1.
`CUBRID_CURSOR_ERROR` | El valor retornado por la función cubrid_move_cursor() si ocurre un error. Este flag fue eliminado desde la versión 8.4.1.

Las constantes siguientes pueden ser utilizadas durante la definición del modo auto-commit para la conexión a la base de datos. Pueden ser pasadas a la función cubrid_set_autocommit() o retornadas por la función cubrid_get_autocommit().

Flags CUBRID para el modo auto-commit
Constante | Descripción
--- | ---
`CUBRID_AUTOCOMMIT_TRUE` | Activa el modo auto-commit.
`CUBRID_AUTOCOMMIT_FALSE` | Desactiva el modo auto-commit.

Las constantes siguientes pueden ser utilizadas durante la definición de parámetros a la base de datos. Pueden ser pasadas a la función cubrid_set_db_parameter().

Flags de parámetros CUBRID
Constante | Descripción
--- | ---
`CUBRID_PARAM_ISOLATION_LEVEL` | Nivel de aislamiento de la transacción para la conexión a la base de datos.
`CUBRID_PARAM_LOCK_TIMEOUT` | Tiempo de expiración de la transacción en segundos.

Las constantes siguientes pueden ser utilizadas para definir el nivel de aislamiento de la transacción. Pueden ser pasadas a la función cubrid_set_db_parameter() o retornadas por la función cubrid_get_db_parameter().

Flags CUBRID para el nivel de aislamiento
Constante | Descripción
--- | ---
`TRAN_COMMIT_CLASS_UNCOMMIT_INSTANCE` | El nivel de aislamiento más bajo (1). Una lectura de datos modificados, no repetibles, o fantasmas puede ocurrir en el tuple y, además, una lectura no repetible puede ocurrir en la tabla.
`TRAN_COMMIT_CLASS_COMMIT_INSTANCE` | Un nivel de aislamiento relativamente bajo (2). Una lectura de datos modificados no puede ocurrir, pero una lectura de datos no repetibles o fantasmas puede ocurrir.
`TRAN_REP_CLASS_UNCOMMIT_INSTANCE` | El nivel de aislamiento por defecto para CUBRID (3). Una lectura de datos modificados, no repetibles o fantasmas puede ocurrir en el tuple, pero la lectura de datos repetibles está asegurada para la tabla.
`TRAN_REP_CLASS_COMMIT_INSTANCE` | Un nivel de aislamiento relativamente bajo (4). Una lectura de datos modificados no puede ocurrir, pero una lectura de datos no repetibles o fantasmas puede ocurrir.
`TRAN_REP_CLASS_REP_INSTANCE` | Un nivel de aislamiento relativamente alto (5). Una lectura de datos modificados o no repetibles no puede ocurrir, pero una lectura de datos fantasmas puede ocurrir.
`TRAN_SERIALIZABLE` | El nivel de aislamiento más alto (6). Los problemas relacionados con la concurrencia (i.e. lectura de datos modificados, no repetibles, fantasmas, etc...) no puede ocurrir.

Las constantes siguientes pueden ser utilizadas para recuperar las informaciones de esquema. Pueden ser pasadas a la función cubrid_schema().

Flags para los esquemas CUBRID
Constante | Descripción
--- | ---
`CUBRID_SCH_CLASS` | Recupera el nombre y el tipo de la tabla en CUBRID.
`CUBRID_SCH_VCLASS` | Recupera el nombre y el tipo de la vista en CUBRID.
`CUBRID_SCH_QUERY_SPEC` | Recupera la definición de la consulta para una vista.
`CUBRID_SCH_ATTRIBUTE` | Recupera los atributos de una columna de una tabla.
`CUBRID_SCH_CLASS_ATTRIBUTE` | Recupera los atributos de una tabla.
`CUBRID_SCH_METHOD` | Recupera el método de la instancia. El método de la instancia es el método llamado por una instancia de clase. Es más frecuentemente utilizado que un método de clase ya que la mayoría de las operaciones son ejecutadas en la instancia.
`CUBRID_SCH_CLASS_METHOD` | Recupera el método de clase. El método de clase es el método llamado por un objeto de la clase. Es habitualmente utilizado para crear una nueva instancia de la clase o para inicializarla. También es utilizado para acceder o actualizar los atributos de la clase.
`CUBRID_SCH_METHOD_FILE` | Recupera las informaciones del archivo que define el método de la tabla.
`CUBRID_SCH_SUPERCLASS` | Recupera el nombre y el tipo de la tabla de la cual la tabla hereda sus atributos.
`CUBRID_SCH_SUBCLASS` | Recupera el nombre y el tipo de la tabla que hereda los atributos.
`CUBRID_SCH_CONSTRAINT` | Recupera las restricciones de la tabla.
`CUBRID_SCH_TRIGGER` | Recupera los triggers de la tabla.
`CUBRID_SCH_CLASS_PRIVILEGE` | Recupera las informaciones sobre los privilegios de la tabla.
`CUBRID_SCH_ATTR_PRIVILEGE` | Recupera las informaciones de privilegios de una columna.
`CUBRID_SCH_DIRECT_SUPER_CLASS` | Recupera la tabla super directa de la tabla.
`CUBRID_SCH_PRIMARY_KEY` | Recupera la clave primaria de la tabla.
`CUBRID_SCH_IMPORTED_KEYS` | Recupera las claves importadas de la tabla.
`CUBRID_SCH_EXPORTED_KEYS` | Recupera las claves exportadas de la tabla.
`CUBRID_SCH_CROSS_REFERENCE` | Recupera las referencias de los enlaces de 2 tablas.

Las constantes siguientes pueden ser utilizadas durante el reporte de errores. Pueden ser retornadas por la función cubrid_error_code_facility().

Código de facilidad de errores CUBRID
Constante | Descripción
--- | ---
`CUBRID_FACILITY_DBMS` | El error ocurrió en la base de datos CUBRID.
`CUBRID_FACILITY_CAS` | El error ocurrió en el broker CUBRID.
`CUBRID_FACILITY_CCI` | El error ocurrió en el cci CUBRID.
`CUBRID_FACILITY_CLIENT` | El error ocurrió en el cliente PHP CUBRID.

# Ejemplos

El siguiente es un ejemplo sencillo que establece una conexión entre PHP y CUBRID. Esta conexión cubrirá la características más básicas y significativas. El siguiente código requiere conectarse a una base de datos CUBRID, lo que significa que CUBRID Server (servidor) y CUBRID Broker (agente) tienen que estar ejecutándose.

El ejemplo de abajo usa la base de datos demodb de ejemplo. Por defecto se crea durante la instalación. Asegúrese de que ha sido creada.

Ejemplo #1 Ejemplo de Recuperación de Datos

    <html>
        <head>
        <meta http-equiv="content-type" content="text/html; charset=euc-kr">
        </head>
        <body>
        <center>
        <table border=2>
        <?php
            /**
             * Establecer la información para conexión de CUBRID. ip_host es la direccion
             * IP donde el Agente de CUBRID está instalado (localhost en este
             * ejemplo), y puerto_host es el número de puerto del Agente de CUBRID.
             * El número de puerto es el predeterminado dado durante la instalación.
             * Para más detalles, véase "Guía del Administrador."
             */
            $ip_host = "localhost";
            $puerto_host = 33000;
            $nombre_bd = "demodb";
            /**
             * Conectar al Servidor CUBRID. No realiza la conexión,
             * sólo conserva la información de ésta. La razón de no realizar
             * la conexión actual es manejar la transacción de forma más eficaz
             * en la arquitectura de 3 capas.
             */
            $cubrid_con = @cubrid_connect($ip_host, $puerto_host, $nombre_bd);

            if (!$cubrid_con) {
                echo "Error de Conexión con la Base de Datos";
                exit;
            }
        ?>
        <?php
            $sql = "select sports, count(players) as players from event group by sports";
            /**
             * Solicitar al Servidor CUBRID los resultados de la declaración SQL.
             * Ahora se hace la conexión actual al Servidor CUBRID.
             */
            $resultado = cubrid_execute($cubrid_con, $sql);

            if ($resultado) {
                /**
                 * Obtener el nombre de las columnas del conjunto de resultados creado por la consulta SQL.
                 */
                $columnas = cubrid_column_names($resultado);
                /**
                 * Obtener el número de columnas del conjunto de resultados creado por la consulta SQL.
                 */
                $número_campos = cubrid_num_cols($resultado);
                /**
                 * Listar los nombres de las columnas del conjunto de resultados por la pantalla.
                 */
                echo "<tr>";

                while (list($clave, $nomcol) = each($columnas)) {
                    echo "<td align=center>$nomcol</td>";
                }

                echo "</tr>";

                /**
                 * Obtener los resultados del conjunto de resultados.
                 */
                while ($fila = cubrid_fetch($resultado)) {
                    echo "<tr>";

                    for ($i = 0; $i < $número_campos; $i++) {
                        echo "<td align=center>";
                        echo $fila[$i];
                        echo "</td>";
                    }

                    echo "</tr>";
                }
            }
            /**
             * El módulo de PHP en CUBRID se ejecuta en una arquitectura de 3 capas. Incluso cuando
             * se llama a SELECT para el procesamiento de la transacción, es pasado como parte
             * de la transacción. Por lo tanto, la transacción necesita ser reiniciada
             * llamando a commit o incluso cuando se llamó a SELECT para un rendimiento
             * pulido.
             */
            cubrid_commit($cubrid_con);
            cubrid_disconnect($cubrid_con);
        ?>
        </body>
        </html>

Ejemplo #2 Ejemplo de Inserción de Datos

    <html>
        <head>
        <meta http-equiv="content-type" content="text/html; charset=euc- kr">
        </head>
        <body>
        <center>
        <table border=2>
        <?php
            /**
             * ip_host es la dirección IP de donde está instalado el Agente de CUBRID
             * puerto_host es el número de puerto del Agente de CUBRID
             * nombre_bd es el nombre de la Base de Datos de CUBRID
             */
            $ip_host = "localhost";
            $puerto_host = 33000;
            $nombre_bd = "demodb";
            $cubrid_con = @cubrid_connect($ip_host, $puerto_host, $nombre_bd);

            if (!$cubrid_con) {
                echo "Error en la Conexión a la Base de Datos";
                exit;
            }
        ?>
        <?php
            $sql = "insert into olympic (host_year,host_nation,host_city,"
                . "opening_date,closing_date) values (2008, 'China', 'Beijing',"
                . "to_date('08-08-2008','mm-dd- yyyy'),to_date('08-24-2008','mm-dd-yyyy')) ;";
            $resultado = cubrid_execute($cubrid_con, $sql);
            if ($resultado) {
                /**
                 * Manejado con éxito, por lo que se envía.
                 */
                cubrid_commit($cubrid_con);
                echo "Insertado con éxito";
            } else {
                /**
                 * Ocurrió un error, por lo que el mensaje de error se imprime y se llama a rollback.
                 */
                echo cubrid_error_msg();
                cubrid_rollback($cubrid_con);
            }
            cubrid_disconnect($cubrid_con);
        ?>
        </body>
        </html>

# Funciones de CUBRID

# cubrid_bind

(PECL CUBRID >= 8.3.0)

cubrid_bind — Vincular variables para una sentencia preparada como parámetros

### Descripción

function cubrid_bind(
resource `$req_identifier`,
int `$bind_index`,
mixed `$bind_value`,
string `$bind_value_type` = ?
): bool

La función cubrid_bind() se usa para vincular valores a un marcador de posición nominado o signo de interrogación correspondiente en la sentencia SQL que fue pasada a cubrid_prepare(). Si no se da `bind_value_type`, string será lo predeterminado.

> Nota: Si el tipo de datos a ser vinculados es BLOB/CLOB, CUBRID intentará mapear la información como un flujo de PHP. Si el tipo real de valor vinculado no es un flujo, CUBRID intentará convertirlo a cadena, y usarlo como la ruta completa y el nombre de fichero de un fichero del sistema de ficheros cliente. Si el tipo de datos a ser vinculados explícitamente es ENUM, el argumento `bind_value` debería ser el elemento enum que esté en formato string. En un entorno fragmentado de CUBRID, se debe incluir de `bind_value_type` en la función cubrid_bind()

La siguiente tabla muestra los tipos de los valores sustitutos.

Tipos de Datos de Vinculación de CUBRID
Soporte | Tipo de Vinculación | Tipo SQL Correspondiente
--- | --- | ---
Soportado | STRING | CHAR, VARCHAR
| NCHAR | NCHAR, NVARCHAR
| BIT | BIT, VARBIT
| NUMERIC or NUMBER | SHORT, INT, NUMERIC
| FLOAT | FLOAT
| DOUBLE | DOUBLE
| TIME | TIME
| DATE | DATE
| TIMESTAMP | TIMESTAMP
| OBJECT | OBJECT
| ENUM | ENUM
| BLOB | BLOB
| CLOB | CLOB
| NULL | NULL
No soportado | SET | SET
| MULTISET | MULTISET
| SEQUENCE | SEQUENCE

### Parámetros

`req_identifier`
  Identificador de solicitud como resultado de cubrid_prepare()
`bind_index`
  Índice de ubicación de los parámetros de vinculación. Comienza con 1.
`bind_value`
  Valor actual para el vínculo.
`bind_index`
  Un tipo de valor a vincular. (Es omitido por defecto. Así, el sistema internamente usa una cadena por omisión. Sin embargo, se necesita especificar el tipo exacto del valor como argumento cuando son de tipo NCHAR, BIT, o BLOB/CLOB).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.1 | Añadido el soporte para tipos de datos BLOB/CLOB.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_bind()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $result = cubrid_execute($conn, "SELECT code FROM event WHERE sports='Basketball' and gender='M'");
    $row = cubrid_fetch_array($result, CUBRID_ASSOC);
    $event_code = $row["code"];

    cubrid_close_request($result);

    $game_req = cubrid_prepare($conn, "SELECT athlete_code FROM game WHERE host_year=1992 and event_code=? and nation_code='USA'");
    cubrid_bind($game_req, 1, $event_code, "number");
    cubrid_execute($game_req);

    printf("--- Dream Team (1992 United States men's Olympic basketball team) ---\n");
    while ($athlete_code = cubrid_fetch_array($game_req, CUBRID_NUM)) {
        $athlete_req  = cubrid_prepare($conn, "SELECT name FROM athlete WHERE code=? AND  nation_code='USA' AND event='Basketball' AND gender='M'");
        cubrid_bind($athlete_req, 1, $athlete_code[0], "number");
        cubrid_execute($athlete_req);
        $row = cubrid_fetch_assoc($athlete_req);
        printf("%s\n", $row["name"]);
    }

    cubrid_close_request($game_req);
    cubrid_close_request($athlete_req);

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    --- Dream Team (1992 United States men's Olympic basketball team) ---
    Stockton John
    Robinson David
    Pippen Scottie
    Mullin C.
    Malone Karl
    Laettner C.
    Jordan Michael
    Johnson Earvin
    Ewing Patrick
    Drexler Clyde
    Bird Larry
    Barkley Charles

Ejemplo #2 Ejemplo de BLOB/CLOB de cubrid_bind()

    <?php
    $con = cubrid_connect("localhost", 33000, "demodb", "dba", "");
    if ($con) {
        cubrid_execute($con,"DROP TABLE if exists php_cubrid_lob_test");
        cubrid_execute($con,"CREATE TABLE php_cubrid_lob_test (doc_content CLOB)");
        $sql = "INSERT INTO php_cubrid_lob_test(doc_content) VALUES(?)";
        $req = cubrid_prepare($con, $sql);

        $fp = fopen("book.txt", "rb");

        cubrid_bind($req, 1, $fp, "clob");
        cubrid_execute($req);
    }
    ?>

Ejemplo #3 Ejemplo de BLOB/CLOB de cubrid_bind()

    <?php
    $con = cubrid_connect("localhost", 33000, "foo");
    if ($con) {
        cubrid_execute($con,"DROP TABLE if exists php_cubrid_lob_test");
        cubrid_execute($con,"CREATE TABLE php_cubrid_lob_test (image BLOB)");
        $sql = "INSERT INTO php_cubrid_lob_test(image) VALUES(?)";
        $req = cubrid_prepare($con, $sql);

        cubrid_bind($req, 1, "cubrid_logo.png", "blob");
        cubrid_execute($req);
    }
    ?>

### Ver también

- cubrid_execute() - Ejecutar una sentencia SQL preparada
- cubrid_prepare() - Prepara una consulta SQL para su ejecución

# cubrid_close_prepare

(PECL CUBRID >= 8.3.0)

cubrid_close_prepare — Cerrar el gestor de solicitud

### Descripción

function cubrid_close_prepare(resource `$req_identifier`): bool

La función cubrid_close_prepare() cierra el gestor de solicitud dado por el argumento `req_identifier`, y libera la región de memoria relacionada con el gestor. Es un alias de cubrid_close_request().

### Parámetros

`req_identifier`
  Identificador de solicitud.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_close_prepare()

    <?php
    $con = cubrid_connect ("localhost", 33000, "demodb", "dba", "");
    if ($con) {
       echo "conectado con éxito";
       $req = cubrid_execute ( $con, "select * from members",
                               CUBRID_INCLUDE_OID | CUBRID_ASYNC);
       if ($req) {
          while ( list ($id, $nombre) = cubrid_fetch ($req) ){
             echo $id;
             echo $nombre;
          }
          cubrid_close_prepare($req); // o se puede usar cubrid_close_request($req)
       }
       cubrid_disconnect($con);
    }
    ?>

### Ver también

- cubrid_close_request() - Cerrar el gestor de solicitud

# cubrid_close_request

(PECL CUBRID >= 8.3.0)

cubrid_close_request — Cerrar el gestor de solicitud

### Descripción

function cubrid_close_request(resource `$req_identifier`): bool

La función cubrid_close_request() cierra el gestor de solicitud dado por el argumento `req_identifier`, y libera la región de memoria relacionada con el gestor. Es un alias de cubrid_close_prepare().

### Parámetros

`req_identifier`
  Identificador de solicitud.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_close_request()

    <?php
    $con = cubrid_connect ("localhost", 33000, "demodb", "dba", "");
    if ($con) {
       echo "conectado con éxito";
       $req = cubrid_execute ( $con, "select * from members",
                               CUBRID_INCLUDE_OID | CUBRID_ASYNC);
       if ($req) {
          while ( list ($id, $name) = cubrid_fetch ($req) ){
             echo $id;
             echo $name;
          }
          cubrid_close_request($req); // o se puede usar cubrid_close_prepare($req)
       }
       cubrid_disconnect($con);
    }
    ?>

### Ver también

- cubrid_execute() - Ejecutar una sentencia SQL preparada

# cubrid_col_get

(PECL CUBRID >= 8.3.0)

cubrid_col_get — Recupera el contenido de los elementos de un tipo de colección utilizando el OID

### Descripción

function cubrid_col_get(resource `$conn_identifier`, string `$oid`, string `$attr_name`): array

La función cubrid_col_get() se utiliza para recuperar el contenido de los atributos de los elementos de un tipo de colección (set, multiset, sequence), en forma de un array.

### Parámetros

`conn_identifier`
  Identificador de conexión.
`oid`
  OID de la instancia a utilizar para la lectura.
`attr_name`
  Nombre del atributo que se desea leer desde la instancia.

### Valores devueltos

Un array (numérico, comenzando en 0) que contiene los elementos deseados cuando la operación se ha realizado con éxito.

`false` (para distinguir los errores y el hecho de que los atributos tienen una colección vacía o nula; en caso de error, se mostrará un mensaje de alerta; en este caso, se puede recuperar el error utilizando la función cubrid_error_code()), cuando la operación ha fallado.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_col_get()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    $size = cubrid_col_size($conn, $oid, "b");
    var_dump($size);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    int(3)

# cubrid_col_size

(PECL CUBRID >= 8.3.0)

cubrid_col_size — Obtener el número de elementos de la columna del tipo de colección usando OID

### Descripción

function cubrid_col_size(resource `$conn_identifier`, string `$oid`, string `$attr_name`): int

La función cubrid_col_size() se usa para obtener el número de elementos de un atributo de tipo de colección (conjunto, multiconjunto, secuencia).

### Parámetros

`conn_identifier`
  Identificador de conexión.
`oid`
  El OID de la instancia con la que se quiere trabajar.
`attr_name`
  Nombre del atributo con el que se quiere trabajar.

### Valores devueltos

Número de elementos, cuando el proceso tiene éxito, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.1 | Cambio del valor devuelto: cuando el proceso no tiene éxito devuelve false, no -1.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_col_size()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    $size = cubrid_col_size($conn, $oid, "b");
    var_dump($size);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    int(3)

# cubrid_column_names

(PECL CUBRID >= 8.3.0)

cubrid_column_names — Obtener los nombres de las columnas del resultado

### Descripción

function cubrid_column_names(resource `$req_identifier`): array

La función cubrid_column_names() se usa para obtener los nombres de las columnas del resultado de la consulta usando `req_identifier`.

### Parámetros

`req_identifier`
  Identificador de solicitud.

### Valores devueltos

Un array de valores de tipo string que contiene los nombres de las columnas, cuando el proceso tiene éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_column_names()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $column_names = cubrid_column_names($result);
    $column_types = cubrid_column_types($result);

    printf("%-30s %-30s %-15s\n", "Column Names", "Column Types", "Column Maxlen");
    for($i = 0, $size = count($column_names); $i < $size; $i++) {
        $column_len = cubrid_field_len($result, $i);
        printf("%-30s %-30s %-15s\n", $column_names[$i], $column_types[$i], $column_len);
    }

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    Column Names                   Column Types                   Column Maxlen
    host_year                      integer                        11
    event_code                     integer                        11
    athlete_code                   integer                        11
    stadium_code                   integer                        11
    nation_code                    char                           3
    medal                          char                           1
    game_date                      date                           10

### Ver también

- cubrid_prepare() - Prepara una consulta SQL para su ejecución
- cubrid_execute() - Ejecutar una sentencia SQL preparada
- cubrid_column_types() - Obtener los tipos de columnas del resultado

# cubrid_column_types

(PECL CUBRID >= 8.3.0)

cubrid_column_types — Obtener los tipos de columnas del resultado

### Descripción

function cubrid_column_types(resource `$req_identifier`): array

La función cubrid_column_types() obtiene los tipos de columnas de los resultados de la consulta usando `req_identifier`.

### Parámetros

`req_identifier`
  Identificador de solicitud.

### Valores devueltos

Un array de valores de tipo string que contiene los tipos de las columnas, cuando el proceso tiene éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_column_types()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $column_names = cubrid_column_names($result);
    $column_types = cubrid_column_types($result);

    printf("%-30s %-30s %-15s\n", "Column Names", "Column Types", "Column Maxlen");
    for($i = 0, $size = count($column_names); $i < $size; $i++) {
        $column_len = cubrid_field_len($result, $i);
        printf("%-30s %-30s %-15s\n", $column_names[$i], $column_types[$i], $column_len);
    }

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    Column Names                   Column Types                   Column Maxlen
    host_year                      integer                        11
    event_code                     integer                        11
    athlete_code                   integer                        11
    stadium_code                   integer                        11
    nation_code                    char                           3
    medal                          char                           1
    game_date                      date                           10

### Ver también

- cubrid_column_names() - Obtener los nombres de las columnas del resultado
- cubrid_prepare() - Prepara una consulta SQL para su ejecución
- cubrid_execute() - Ejecutar una sentencia SQL preparada

# cubrid_commit

(PECL CUBRID >= 8.3.0)

cubrid_commit — Consigna una transacción

### Descripción

function cubrid_commit(resource `$conn_identifier`): bool

La función cubrid_commit() se usa para ejecutar el envío de la transacción a la que apunta `conn_handle`, actualmente en progreso. La conexión al servidor se cierra después de llamar a la función cubrid_commit(); sin embargo, el gestor de conexión todavía es válido.

En CUBRID PHP, se deshabilita un modo de auto consigna por omisión para la administración de transacciones. Se puede establecer usando cubrid_set_autocommit(). Se puede obtener su estado usando cubrid_get_autocommit(). Antes de comenzar una transacción, acuérdese de deshabilitar el modo de auto consigna.

### Parámetros

`conn_identifier`
  Identificador de conexión.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_commit()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE publishers");

    $sql = <<<EOD
    CREATE TABLE publishers(
    pub_id CHAR(3),
    pub_name VARCHAR(20),
    city VARCHAR(15),
    state CHAR(2),
    country VARCHAR(15)
    )
    EOD;
    cubrid_set_autocommit($conn,false);
    if (!cubrid_execute($conn, $sql)) {
        printf("Error  facility: %d\nError code: %d\nError msg: %s\n",  cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }

    $req = cubrid_prepare($conn, "INSERT INTO publishers VALUES(?, ?, ?, ?, ?)");

    $id_list = array("P01", "P02", "P03", "P04");
    $name_list = array("Abatis Publishers", "Core Dump Books", "Schadenfreude Press", "Tenterhooks Press");
    $city_list = array("New York", "San Francisco", "Hamburg", "Berkeley");
    $state_list = array("NY", "CA", NULL, "CA");
    $country_list = array("USA", "USA", "Germany", "USA");

    for ($i = 0, $size = count($id_list); $i < $size; $i++) {
        cubrid_bind($req, 1, $id_list[$i]);
        cubrid_bind($req, 2, $name_list[$i]);
        cubrid_bind($req, 3, $city_list[$i]);
        cubrid_bind($req, 4, $state_list[$i]);
        cubrid_bind($req, 5, $country_list[$i]);

        if (!($ret = cubrid_execute($req))) {
            break;
        }
    }

    if (!$ret) {
        cubrid_rollback($conn);
    } else {
        cubrid_commit($conn);

        $req = cubrid_execute($conn, "SELECT * FROM publishers");
        while ($result = cubrid_fetch_assoc($req)) {
            printf("%-3s %-20s %-15s %-3s %-15s\n",
                $result["pub_id"], $result["pub_name"], $result["city"], $result["state"], $result["country"]);
        }
    }

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    P01 Abatis Publishers    New York        NY  USA
    P02 Core Dump Books      San Francisco   CA  USA
    P03 Schadenfreude Press  Hamburg             Germany
    P04 Tenterhooks Press    Berkeley        CA  USA

### Ver también

- cubrid_rollback() - Anula una transacción
- cubrid_get_autocommit() - Recupera el modo auto-commit de la conexión
- cubrid_set_autocommit() - Define el modo auto-commit para la conexión

# cubrid_connect

(PECL CUBRID >= 8.3.1)

cubrid_connect — Abrir una conexión al servidor CUBRID

### Descripción

function cubrid_connect(
string `$host`,
int `$port`,
string `$dbname`,
string `$userid` = ?,
string `$passwd` = ?,
bool `$new_link` = `false`
): resource

La función cubrid_connect() se usa para establecer el entorno para la conexión al servidor usando la dirección del servidor, número de puerto, nombre de la base de datos, nombre de usuario, y contraseña. Si no se dan el nombre de usuario y la contraseña, se realizará la conexión "PUBLIC" por defecto.

### Parámetros

`host`
  Nombre del host o dirección IP del servidor CAS de CUBRID.
`port`
  Número de puerto del servidor CAS de CUBRID (BROKER_PORT configurado en $CUBRID/conf/cubrid_broker.conf).
`dbname`
  Nombre de la base de datos.
`userid`
  Nombre de usuario para la base de datos. Si no se da, el valor por omisión es "public".
`passwd`
  Contraseña del usuario. Si no se da, el valor por omisión es "".
`new_link`
  Si se hace una segunda llamada a cubrid_connect() con los mismos argumentos, no se establecerá una nueva conexión, en su lugar, se devolverá el identificador de conexión de la conexión ya abierta. El parámetro `new_link` modifica este comportamiento y hace que cubrid_connect() abra siempre una nueva conexión, incluso si cubrid_connect() fue llamada antes con los mismos parámetros.

### Valores devueltos

El identificador de conexión, cuando el proceso tiene éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_connect()

    <?php
    printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    if (!$conn) {
        die('Error de conexión ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Información del Servidor:", $server_info);
    printf("%-30s %s\n", "Información del Cliente:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "Conjunto de carac.:", $charset);

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    CUBRID PHP Version:            9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              0

    Información del Servidor:      9.1.0.0212
    Información del Cliente:       9.1.0

    Conjunto de carac. de CUBRID:  iso8859-1

### Ver también

- cubrid_pconnect() - Establece una conexión persistente con un servidor CUBRID
- cubrid_connect_with_url() - Establecer el entorno para la conexión al servidor de CUBRID
- cubrid_pconnect_with_url() - Establece una conexión persistente con un servidor CUBRID
- cubrid_disconnect() - Cerrar una conexión a una base de datos
- cubrid_close() - Cerrar la conexión de CUBRID

# cubrid_connect_with_url

(PECL CUBRID >= 8.3.1)

cubrid_connect_with_url — Establecer el entorno para la conexión al servidor de CUBRID

### Descripción

function cubrid_connect_with_url(
string `$conn_url`,
string `$userid` = ?,
string `$passwd` = ?,
bool `$new_link` = `false`
): resource

La función cubrid_connect_with_url() se usa para establecer el entorno de conexión a su servidor usando la información de conexión pasada con un argumento de cadena de url. Si la característica HA está habilitada en CUBRID, se debe especificar la información de conexión del servidor de emergencia, el cual se usa para la recuperación de fallos cuando sucede uno, en el argumento de cadena de url de esta función. Si el nombre de usuario y la contraseña no se dan se realizará la conexión "PUBLIC" por omisión.

<url> ::= CUBRID:<host>:<db_name>:<db_user>:<db_password>:[?<properties>]

<properties> ::= <property> [&<property>]

<properties> ::= alhosts=<alternative_hosts>[ &rctime=<time>]

<properties> ::= login_timeout=<milli_sec>

<properties> ::= query_timeout=<milli_sec>

<properties> ::= disconnect_on_query_timeout=true|false

<alternative_hosts> ::= <standby_broker1_host>:<port> [,<standby_broker2_host>:<port>]

<host> := HOSTNAME | IP_ADDR

<time> := SECOND

<milli_sec> := MILLI SECOND

- host : Un nombre de host o dirección IP de la base de datos maestra
- db_name : Un nombre de la base de datos
- db_user : Un nombre del usuario de la base de datos
- db_password : Una contraseña de usuario de la base de datos
- alhosts: Especifica la información del agente del servidor de emergencia, el cual se usa para la recuperación de fallos cuando es imposible conectar al servidor activo. Se pueden especificar múltiples agentes para la recuperación de fallos, y la conexión a los agentes se intenta en el orden listado en alhosts
- rctime : Un intervalo entre los intentos de conexión al agente activo en el que ocurrió el fallo. Después de que ocurra un fallo, el sistema se conecta al agente especificado por althosts (recuperación de fallos), finaliza la transacción, y después intenta conectarse al agente activo de la base de datos maestra cada rctime. El valor predeterminado es 600 segundos.
- login_timeout : Valor de tiempo de espera (unidad: mseg.) para la identificación en la base de datos. El valor predeterminado es 0, lo que significa un aplazamiento infinito.
- query_timeout : Valor de tiempo de espera (unidad: mseg.) para la solicitud de consulta. Cuando finaliza el tiempo de espera, se envía al servidor un mensaje para cancelar la transferencia de la consulta. El valor devuelto puede depender de de la configuración de disconnect_on_query_timeout; incluso si el mensaje para cancelar una petición es enviado al servidor, tal peticioón puede realizarse.
- disconnect_on_query_timeout : Configura un valor para establecer si devolver inmediantamente un error de función que está siendo ejecutada al finalizar el tiempo de espera. El valor predeterminado es false.

> Nota: `?` y `:`, que son usados como identificadores en el URL de conexión de PHP, no pueden ser incluidos en la contraseña. El siguiente es un ejemplo de una contraseña que no es válida para usarla como URL de conexión ya que contiene "`?:`". $url = "CUBRID:localhost:33000:tdb:dba:12?:?login_timeout=100"; Las contraseñas que contengan `?` o `:` se pueden pasar como un parámetro aparte. $url = "CUBRID:localhost:33000:tbd:::?login_timeout=100"; $conn = cubrid_connect_with_url($url, "dba", "12?"); Si el usuario o la contraseña están vacíos no se podrá borrar "`:`". He aquí un ejemplo: $url = "CUBRID:localhost:33000:demodb:::";

### Parámetros

`conn_url`
  Una cadena de caracteres que contiene la información de conexión al servidor.
`userid`
  El nombre de usuario de la base de datos.
`passwd`
  La contraseña del usuario.
`new_link`
  Si se hace una segunda llamada a cubrid_connect_with_url() con los mismos argumentos, no se establecerá una nueva conexión, en su lugar, se devolverá el identificador de conexión de la conexión ya abierta. El parámetro `new_link` modifica este comportamiento y hace que cubrid_connect_with_url() abra siempre una nueva conexión, incluso si cubrid_connect_with_url() fue llamada antes con los mismos parámetros.

### Valores devueltos

El identificador de conexión, cuando el proceso tiene éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_connect_with_url(), url sin propiedades

    <?php
    $conn_url = "CUBRID:localhost:33000:demodb:dba::";
    $con = cubrid_connect_with_url($conn_url);

    if ($con) {
       echo "Se conectó con éxito";
       cubrid_execute($con, "create table person(id int,name char(16))");
       $req =cubrid_execute($con, "insert into person values(1,'James')");

       if ($req) {
          cubrid_close_request($req);
          cubrid_commit($con);
       } else {
          cubrid_rollback($con);
       }
       cubrid_disconnect($con);
    }
    ?>

Ejemplo #2 Ejemplo de cubrid_connect_with_url(), url con propiedades

    <?php
    $conn_url = "CUBRID:127.0.0.1:33000:demodb:dba::?login_timeout=100";
    $con = cubrid_connect_with_url ($conn_url);

    if ($con) {
       echo "Se conectó con éxito";
       cubrid_execute($con, "create table person(id int,name char(16))");
       $req =cubrid_execute($con, "insert into person values(1,'James')");

       if ($req) {
          cubrid_close_request($req);
          cubrid_commit($con);
       } else {
          cubrid_rollback($con);
       }
       cubrid_disconnect($con);
    }
    ?>

### Ver también

- cubrid_connect() - Abrir una conexión al servidor CUBRID
- cubrid_pconnect() - Establece una conexión persistente con un servidor CUBRID
- cubrid_pconnect_with_url() - Establece una conexión persistente con un servidor CUBRID
- cubrid_disconnect() - Cerrar una conexión a una base de datos
- cubrid_close() - Cerrar la conexión de CUBRID

# cubrid_current_oid

(PECL CUBRID >= 8.3.0)

cubrid_current_oid — Obtener el OID de la posición del cursor actual

### Descripción

function cubrid_current_oid(resource `$req_identifier`): string

La función cubrid_current_oid() se usa para obtener el oid de la posición del cursor actual desde el resultado de la consulta. Para usar cubrid_current_oid(), la consulta ejecutada debe ser una consulta actualizable, y se debe incluir la opción `CUBRID_INCLUDE_OID` durante la ejecución de la consulta.

### Parámetros

`req_identifier`
  Identificador de solicitud.

### Valores devueltos

Oid de la posición del cursor actual, cuando el proceso tiene éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_current_oid()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code", CUBRID_INCLUDE_OID);
    $oid = cubrid_current_oid($req);
    $res = cubrid_get($conn, $oid);

    print_r($res);

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    Array
    (
        [s_name] => X
        [f_name] => Mixed
    )

### Ver también

- cubrid_execute() - Ejecutar una sentencia SQL preparada

# cubrid_disconnect

(PECL CUBRID >= 8.3.0)

cubrid_disconnect — Cerrar una conexión a una base de datos

### Descripción

function cubrid_disconnect(resource `$conn_identifier` = ?): bool

La función cubrid_disconnect() cierra el gestor de conexión y se desconecta del servidor. Si algún gestor de solicitud no se ha sido cerrado en este punto, será cerrado. Es similar a la función de CUBRID compatible con MySQL cubrid_close().

### Parámetros

`conn_identifier`
  Identificador de conexión.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_disconnect()

    <?php
    $con = cubrid_connect ("localhost", 33000, "demodb");
    if ($con) {
       echo "conectado con éxito";

       $req = cubrid_execute( $con, "create table person(id int,name char(10))");
       if ($req) {
          cubrid_close_request($req);
          cubrid_commit($con);
       } else {
          cubrid_rollback($con);
       }

       $req = cubrid_execute( $con, "insert into person values(1,'James')");
       if ($req) {
          cubrid_close_request($req);
          cubrid_commit($con);
       } else {
          cubrid_rollback($con);
       }
       cubrid_disconnect($con);
    }
    ?>

### Ver también

- cubrid_close() - Cerrar la conexión de CUBRID
- cubrid_connect() - Abrir una conexión al servidor CUBRID
- cubrid_connect_with_url() - Establecer el entorno para la conexión al servidor de CUBRID

# cubrid_drop

(PECL CUBRID >= 8.3.0)

cubrid_drop — Borrar una instancia usando OID

### Descripción

function cubrid_drop(resource `$conn_identifier`, string `$oid`): bool

La función cubrid_drop() se usa para borrar una instancia de la base de datos usando el `oid` de la instancia.

### Parámetros

`conn_identifier`
  Identificador de conexión.
`oid`
  Oid de la instancia que se quiere borrar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_drop()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    printf("--- Antes de Drop: ---\n");
    $attr = cubrid_get($conn, $oid);
    var_dump($attr);

    if (cubrid_drop($conn, $oid)) {
        cubrid_commit($conn);
    } else {
        cubrid_rollback($conn);
    }

    cubrid_close_request($req);

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    printf("\n--- Después de Drop: ---\n");
    $attr = cubrid_get($conn, $oid);
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    --- Antes de Drop: ---
    array(4) {
      ["a"]=>
      string(1) "1"
      ["b"]=>
      array(3) {
        [0]=>
        string(1) "1"
        [1]=>
        string(1) "2"
        [2]=>
        string(1) "3"
      }
      ["c"]=>
      array(4) {
        [0]=>
        string(2) "11"
        [1]=>
        string(2) "22"
        [2]=>
        string(2) "33"
        [3]=>
        string(3) "333"
      }
      ["d"]=>
      string(10) "a         "
    }

    --- Después de Drop: ---
    array(4) {
      ["a"]=>
      string(1) "2"
      ["b"]=>
      array(3) {
        [0]=>
        string(1) "4"
        [1]=>
        string(1) "5"
        [2]=>
        string(1) "7"
      }
      ["c"]=>
      array(4) {
        [0]=>
        string(2) "44"
        [1]=>
        string(2) "55"
        [2]=>
        string(2) "66"
        [3]=>
        string(3) "666"
      }
      ["d"]=>
      string(10) "b         "
    }

### Ver también

- cubrid_is_instance() - Comprobar si existe la instancia apuntada por OID

# cubrid_error_code

(PECL CUBRID >= 8.3.0)

cubrid_error_code — Obtener el código de error de la llamada a una función más reciente

### Descripción

function cubrid_error_code(): int

La función cubrid_error_code() se usa para obtener el código de error del error que ocurrión durante la ejecución de la API. Normalmente obtiene el código de error cuando la API devuelve false como valor de retorno.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Código de error del error que ocurrió, o `0` (cero) si no ocurre ningún error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_error_code()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_prepare($conn , "SELECT * FROM code WHERE s_name=?");

    $req = @cubrid_execute($req);
    if (!$req) {
        printf("Dispositivo del error: %d\nCódigo de error: %d\nMensaje de error: %s\n",
            cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }
    ?>

El ejemplo anterior mostrará:

    Dispositivo del error: 4
    Código de error: -30015
    Mensaje de error: Some parameter not binded

### Ver también

- cubrid_error_code_facility() - Obtener el código de error del dispositivo
- cubrid_error_msg() - Obtener el último mensaje de error de la llamada a la función más reciente

# cubrid_error_code_facility

(PECL CUBRID >= 8.3.0)

cubrid_error_code_facility — Obtener el código de error del dispositivo

### Descripción

function cubrid_error_code_facility(): int

La función cubrid_error_code_facility() se usa para obtener el código de dispositivo (nivel en el que ocurrió el error) desde el código de error del error que ocurrió durante la ejecución de la API. Normalmente, se puede obtener el código de error cuando la API devuelve false como valor de retorno.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Código de dispositivo del código de error que ocuriió: `CUBRID_FACILITY_DBMS`, `CUBRID_FACILITY_CAS`, `CUBRID_FACILITY_CCI`, `CUBRID_FACILITY_CLIENT`.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_error_code_facility()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = @cubrid_execute($conn, "SELECT * FROM unknown");
    if (!$req) {
        printf("Dispositivo del error: %d\nCódigo de error: %d\nMensaje de error: %s\n",
            cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }
    ?>

El ejemplo anterior mostrará:

    Dispositivo del error: 1
    Código de error: -493
    Mensaje de error: Syntax: In line 1, column 15 before END OF STATEMENT
    Syntax error: unexpected 'unknown'

### Ver también

- cubrid_error_code() - Obtener el código de error de la llamada a una función más reciente
- cubrid_error_msg() - Obtener el último mensaje de error de la llamada a la función más reciente

# cubrid_error_msg

(PECL CUBRID >= 8.3.0)

cubrid_error_msg — Obtener el último mensaje de error de la llamada a la función más reciente

### Descripción

function cubrid_error_msg(): string

La función cubrid_error_msg() se usa para obtener el mensaje de error que ocurrió durante la utilización de la API CUBRID. Normalmente obtiene el mensaje de error cuando la API devuelve false como valor de retorno.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El mensaje de error que ocurrió.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_error_msg()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    if (!@cubrid_schema($conn, 100000)) {
        printf("Dispositivo del error: %d\nCódigo de error: %d\nMensaje de error: %s\n",
            cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }
    ?>

El ejemplo anterior mostrará:

    Dispositivo del error: 2
    Código de error: -10015
    Mensaje de error: Invalid T_CCI_SCH_TYPE value

### Ver también

- cubrid_error_code() - Obtener el código de error de la llamada a una función más reciente
- cubrid_error_code_facility() - Obtener el código de error del dispositivo

# cubrid_execute

(PECL CUBRID >= 8.3.0)

cubrid_execute — Ejecutar una sentencia SQL preparada

### Descripción

function cubrid_execute(resource `$conn_identifier`, string `$sql`, int `$option` = 0): resource
function cubrid_execute(resource `$request_identifier`, int `$option` = 0): bool

La función cubrid_execute() se usa para ejecutar la sentencia SQL dada. Ejecuta la consulta usando `conn_identifier` y SQL, y luego devuelve el gestor de solicitud creado. Se usa para la simple ejecución de la consulta, donde el parámetro de enlace no es necesario. Además, la función cubrid_execute() se usa para ejecutar la sentencia preparada por medio de cubrid_prepare() y cubrid_bind(). En este momento se necesitan especificar los argumentos `request_identifier` y `option`.

El argumento `option` se usa para determinar si recibir el OID después de la ejecución de la consulta y si ejecutar la consulta en modo síncrono o asíncrono. Se pueden especificar `CUBRID_INCLUDE_OID` y `CUBRID_ASYNC` (o `CUBRID_EXEC_QUERY_ALL` si se desea ejecutar múltiples sentencias SQL) usando un operador OR a nivel de bit. Si no se especifica, ninguna de ellas será seleccionada. Si la bandera `CUBRID_EXEC_QUERY_ALL` está activa, el modo síncrono (sync_mode) se usa para devolver los resultados de la consulta, y en esos casos las siguientes reglas serán aplicadas:

- El valor devuelto es el resultado de la primera petición.
- Si sucede un error en la consulta, la ejecución se procesa como un fallo.
- En una consulta compuesta por c1, c2, c3, si sucede un error en c2 después del éxito de la ejecución de c1, el resultado de c1 permanece válido. Esto es, los éxitos previos en las ejecucuiones de consultas no se repiten cuando sucede un error.
- Si una consulta se ejecuta de forma satisfactoria, el resultado de la segunda consulta puede obtenerse usando la función cubrid_next_result().

Si el primer argumento es `request_identifier` para ejecutar la función cubrid_prepare(), se puede especificar una opción, solamente `CUBRID_ASYNC`.

### Parámetros

`conn_identifier`
  Identificador de conexión.
`sql`
  SQL a ser ejecutado.
`option`
  La opción de ejecución de la consulta CUBRID_INCLUDE_OID, CUBRID_ASYNC, CUBRID_EXEC_QUERY_ALL.
`request_identifier`
  Identificador de cubrid_prepare().

### Valores devueltos

Gestor de solicitud, cuando el proceso tiene éxito y el primer parámetro es conn_identifier; `true`, cuando el proceso tiene éxito y el primer argumento es request_identifier, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Añade `CUBRID_EXEC_QUERY_ALL` como opción nueva.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_execute()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $result = cubrid_execute($conn, "SELECT code FROM event WHERE name='100m Butterfly' and gender='M'", CUBRID_ASYNC);
    $row = cubrid_fetch_array($result, CUBRID_ASSOC);
    $event_code = $row["code"];

    cubrid_close_request($result);

    $history_req = cubrid_prepare($conn, "SELECT * FROM history WHERE event_code=?");
    cubrid_bind($history_req, 1, $event_code, "number");
    cubrid_execute($history_req);

    printf("%-20s %-9s %-10s %-5s\n", "athlete", "host_year", "score", "unit");
    while ($row = cubrid_fetch_array($history_req, CUBRID_ASSOC)) {
        printf("%-20s %-9s %-10s %-5s\n",
            $row["athlete"], $row["host_year"], $row["score"], $row["unit"]);
    }

    cubrid_close_request($history_req);

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    athlete              host_year score      unit
    Phelps Michael       2004      51.25      time

### Ver también

- cubrid_prepare() - Prepara una consulta SQL para su ejecución
- cubrid_bind() - Vincular variables para una sentencia preparada como parámetros
- cubrid_next_result() - Recupera el resultado de la siguiente consulta durante la ejecución de múltiples consultas SQL
- cubrid_close_request() - Cerrar el gestor de solicitud
- cubrid_commit() - Consigna una transacción
- cubrid_rollback() - Anula una transacción

# cubrid_fetch

(PECL CUBRID >= 8.3.0)

cubrid_fetch — Obtener la siguiente fila de un conjunto de resultados

### Descripción

function cubrid_fetch(resource `$result`, int `$type` = CUBRID_BOTH): mixed

La función cubrid_fetch() se usa para obtener una única fila del resultado de la consulta. El cursor se mueve automáticamente a la siguiente columna después de obtener el resultado.

### Parámetros

`result`
  `result` proviene de una llamada a la función cubrid_execute().
`type`
  Tipo de array del resultado obtenido: CUBRID_NUM, CUBRID_ASSOC, CUBRID_BOTH, CUBRID_OBJECT. Si se operan con objetos lob, se puede usar CUBRID_LOB.

### Valores devueltos

Un array de resultados u objeto, cuando el proceso tiene éxito.

`false`, cuando no existen más filas; NULL, cuando el proceso no tiene éxito.

El resultado se puede recibir como array o como objeto, por lo que se puede decidir qué tipo de datos usar estableciendo el argumento `type`. La variable `type` se puede establecer a uno de los siguientes valores:

- CUBRID_NUM : Array numérico (basado en 0)
- CUBRID_ASSOC : Array asociativo
- CUBRID_BOTH : Array numérico y asociativo (predeterminado)
- CUBRID_OBJECT : Objeto que tiene el nombre del atributo como el nombre de la columna del resultado de la consulta

Cuando se omite el argumento `type`, el resultado será recibido usando la opción predeterminada CUBRID_BOTH. Cuando se quiere recibir el resultado de la consulta como objeto, el nombre de la columna del resultado debe obedecer las reglas de nombres de los identificadores de PHP. Por ejemplo, un nombre de columna como "count(*)" no puede ser recibido como objeto.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_fetch()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $solicitud = cubrid_execute($conexión, "SELECT * FROM stadium WHERE nation_code='GRE' AND seats > 10000");

    printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
    while ($fila = cubrid_fetch($solicitud)) {
        printf("%-40s %-10s %-6s %-20s\n",
            $fila["name"], $fila["area"], $fila["seats"], $fila["address"]);
    }

    // si se operan con objetos lob, se puede usar cubrid_fetch($solicitud, CUBRID_LOB)

    cubrid_close_request($solicitud);

    cubrid_disconnect($conexión);
    ?>

El ejemplo anterior mostrará:

    name                                     area       seats  address
    Panathinaiko Stadium                     86300.00   50000  Athens, Greece
    Olympic Stadium                          54700.00   13000  Athens, Greece
    Olympic Indoor Hall                      34100.00   18800  Athens, Greece
    Olympic Hall                             52400.00   21000  Athens, Greece
    Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
    Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
    Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
    Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
    Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

### Ver también

- cubrid_execute() - Ejecutar una sentencia SQL preparada
- cubrid_fetch_array() - Recupera una línea de resultado en forma de array asociativo, array numérico, o ambos
- cubrid_fetch_row() - Devuelve un array numérico con los valores de la fila actual
- cubrid_fetch_assoc() - Devuelve un array asociativo correspondiente a la fila recuperada
- cubrid_fetch_object() - Recupera la siguiente línea y la devuelve como un objeto

# cubrid_free_result

(PECL CUBRID >= 8.3.0)

cubrid_free_result — Liberar la memoria ocupada por los datos del resultado

### Descripción

function cubrid_free_result(resource `$req_identifier`): bool

Esta función libera la memoria ocupada por los datos del resultado. Devuelve `true` en caso de éxito o `false` en caso de error. Observe que sólo se puede liberar el buffer de obtención del cliente, y si se quiere liberar toda la memoria, use la función cubrid_close_request().

### Parámetros

`req_identifier`
  Éste es el identificador de solicitud.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_free_result()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $req = cubrid_execute($conn, "SELECT * FROM history WHERE host_year=2004 ORDER BY event_code");
    $row = cubrid_fetch_assoc($req);
    var_dump($row);

    cubrid_free_result($req);
    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    array(5) {
      ["event_code"]=>
      string(5) "20005"
      ["athlete"]=>
      string(12) "Hayes Joanna"
      ["host_year"]=>
      string(4) "2004"
      ["score"]=>
      string(5) "12.37"
      ["unit"]=>
      string(4) "time"
    }

# cubrid_get

(PECL CUBRID >= 8.3.0)

cubrid_get — Obtener una columna usando OID

### Descripción

function cubrid_get(resource `$conn_identifier`, string `$oid`, mixed `$attr` = ?): mixed

La función cubrid_get() se usa para obtener el atributo de la instancia del `oid` dado. Se puede obtener un solo atributo usando el tipo de datos de cadena para el argumento `attr`, o muchos atributos usando el tipo de datos array para el argumento `attr`.

### Parámetros

`conn_identifier`
  Identificador de conexión.
`oid`
  OID de la instancia que se quiere leer.
`attr`
  Nombre del atributo que se quiere leer.

### Valores devueltos

Contenido del atributo solicitado, cuando el proceso tiene éxito; Cuando `attr` se establece al tipo de datos de cadena, el resultado es devuelto como una cadena; cuando `attr` se establece como tipo de datos array (númerico basado en 0), el resultado es devuelto como un array asociativo. Cuanso se omite `attr`, entonces todos los atributos se reciben como array.

`false` cuando el proceso no tiene éxito o el resultado es NULL (Si ocurre un error para diferenciar una cadena vacía de NULL, se imprime un mensaje de advertencia. Se puede comprobar el error usando cubrid_error_code())

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_get()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_get($conn, $oid, "b");
    var_dump($attr);

    $attr = cubrid_get($conn, $oid);
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    string(9) "{1, 2, 3}"
    array(4) {
      ["a"]=>
      string(1) "1"
      ["b"]=>
      array(3) {
        [0]=>
        string(1) "1"
        [1]=>
        string(1) "2"
        [2]=>
        string(1) "3"
      }
      ["c"]=>
      array(4) {
        [0]=>
        string(2) "11"
        [1]=>
        string(2) "22"
        [2]=>
        string(2) "33"
        [3]=>
        string(3) "333"
      }
      ["d"]=>
      string(10) "a         "
    }

### Ver también

- cubrid_put() - Actualiza una columna según su OID

# cubrid_get_autocommit

(PECL CUBRID >= 8.4.0)

cubrid_get_autocommit — Recupera el modo auto-commit de la conexión

### Descripción

function cubrid_get_autocommit(resource `$conn_identifier`): bool

La función cubrid_get_autocommit() se utiliza para recuperar el estado del modo auto-commit de la conexión a la base de datos CUBRID.

En CUBRID 8.4.0, el modo auto-commit está desactivado por omisión para la gestión de las transacciones.

En CUBRID 8.4.1, el modo auto-commit está activado por omisión para la gestión de las transacciones.

### Parámetros

`conn_identifier`
  Identificador de conexión.

### Valores devueltos

`true`, cuando el modo auto-commit está activo.

`false`, cuando el modo auto-commit está inactivo.

`null` Si ocurre un error.

### Ver también

- cubrid_set_autocommit() - Define el modo auto-commit para la conexión
- cubrid_commit() - Consigna una transacción

# cubrid_get_charset

(PECL CUBRID >= 8.3.0)

cubrid_get_charset — Devolver el conjunto de caracteres de la conexión CUBRID actual

### Descripción

function cubrid_get_charset(resource `$conn_identifier`): string

Esta función devuelve el conjunto de caracteres de la conexión CUBRID actual y es similar a la función de CUBRID compatible con MySQL cubrid_client_encoding().

### Parámetros

`conn_identifier`
  La conexión CUBRID.

### Valores devueltos

Una cadena que representa el conjunto de caracteres de la conexión CUBRID; en caso de éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_get_charset()

    <?php

    $con = cubrid_connect("localhost", 33000, "demodb");
    if (!$con)
    {
        die('No se pudo realizar la conexión.');
    }

    printf("Conjunto de caracteres actual de CUBRID: %s\n", cubrid_get_charset($con));

    ?>

El ejemplo anterior mostrará:

    CUBRID current charset: iso8859-1

### Ver también

- cubrid_client_encoding() - Devuelve el actual conjunto de caracteres de la conexión a CUBRID

# cubrid_get_class_name

(PECL CUBRID >= 8.3.0)

cubrid_get_class_name — Obtener el nombre de la clase usando OID

### Descripción

function cubrid_get_class_name(resource `$conn_identifier`, string `$oid`): string

La función cubrid_get_class_name() se usa para obtener el nombre de la clase del `oid`. No funciona al seleccionar datos desde las tablas del sistema, por ejemplo db_class.

### Parámetros

`conn_identifier`
  Identificador de conexión.
`oid`
  Oid de la instancia de la que se quiere comprobar su existencia.

### Valores devueltos

El nombre de la clase cuando el proceso tiene éxito, o `false` si ocurre un error.

`false`, cuando el proceso no tiene éxito.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_get_class_name()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code", CUBRID_INCLUDE_OID);
    $oid = cubrid_current_oid($req);
    $class_name = cubrid_get_class_name($conn, $oid);

    print_r($class_name);

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    code

### Ver también

- cubrid_is_instance() - Comprobar si existe la instancia apuntada por OID
- cubrid_drop() - Borrar una instancia usando OID

# cubrid_get_client_info

(PECL CUBRID >= 8.3.0)

cubrid_get_client_info — Devolver la versión de la biblioteca cliente

### Descripción

function cubrid_get_client_info(): string

Esta función devuelve una cadena que representa la versión de la biblioteca cliente.

### Parámetros

### Valores devueltos

Una cadena que representa la versión de la biblioteca cliente; en caso de éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_get_client_info()

    <?php
    printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33088, "demodb");

    if (!$conn) {
        die('Error de conexión ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Server Info:", $server_info);
    printf("%-30s %s\n", "Client Info:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "CUBRID Charset:", $charset);

    cubrid_disconnect($conn);

    ?>

El ejemplo anterior mostrará:

    CUBRID PHP Version:            9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              0

    Server Info:                   9.1.0.0212
    Client Info:                   9.1.0

    CUBRID Charset:                iso8859-1

# cubrid_get_db_parameter

(PECL CUBRID >= 8.3.0)

cubrid_get_db_parameter — Devuelve los parámetros de la base de datos CUBRID

### Descripción

function cubrid_get_db_parameter(resource `$conn_identifier`): array

Esta función devuelve los parámetros de la base de datos CUBRID , o `false` si ocurre un error. Devuelve un array asociativo con los valores de los siguientes parámetros:

- `PARAM_ISOLATION_LEVEL`
- `PARAM_LOCK_TIMEOUT`
- `PARAM_MAX_STRING_LENGTH`
- `PARAM_AUTO_COMMIT`

Parámetros de la base de datos
Parámetro | Descripción
--- | ---
PARAM_ISOLATION_LEVEL | El nivel de aislamiento de la transacción.
LOCK_TIMEOUT | CUBRID proporciona la característica de bloqueo de tiempo de espera, que establece el tiempo de espera (en segundos) para el bloqueo hasta que el ajuste de bloqueo de transacción se permite. El valor predeterminado del parámetro lock_timeout_in_secs es -1, lo que significa que la aplicación cliente esperará indefinidamente hasta que se permita el bloqueo de transacción.
PARAM_AUTO_COMMIT | En CUBRID PHP, el modo de auto consigna es desabilitado por omisión por el gestor de transacciones. Puede establecerse usando la función cubrid_set_autocommit().

La siguiente tabla muestra los niveles de aislamiento desde 1 hasta 6. Consiste en esquema de tabla (fila) y nivel de aislamiento:

Niveles de Aislamiento Soportados por CUBRID
Nombre | Descripción
--- | ---
SERIALIZABLE (6) | En este nivel de aislamiento, los problemas concernientes a la concurrencia (p.ej. lectura basura, lectura no repetible, lectura fantasma, etc.) no ocurren.
CLASE DE LECTURA REPETIBLE con INSTANCIAS DE LECTURA REPETIBLE (5) | Otra transacción T2 no puede actualizar el esquema de una tabla A mientras la transacción T1 está viendo la tabla A. La transacción T1 puede experimentar lectura fantasma para el registro R que fue insertado por otra transacción T2 cuando está obtenido repetidamente un registro especificado.
CLASE DE LECTURA REPETIBLE con INSTANCIAS CONSIGNADAS DE LECTURA (o ESTABILIDAD DE CURSOR) (4) | Otra transacción T2 no puede actualizar el esquema de una tabla A mientras la transacción T1 está viendo la tabla A. La transacción T1 puede experimentar lectura R (lectura no repetible) que fue actualizada y consignada por otra transacción T2 cuando está obteniendo repetidamente el registro R.
CLASE DE LECTURA REPETIBLE con INSTANCIAS NO CONSIGNADAS DE LECTURA (3) | Nivel de aislamiento predeterminado. Otra transacción T2 no puede actualizar el esquema de la tabla A mientras la transacción T1 está viendo la tabla A. La transacción T1 puede experimentar lectura R' (lectura basura) para el registro que fue actualizado pero no consignado por otra transacción T2.
CLASE CONSIGNADA DE LECTURA con INSTANCIAS CONSIGNADAS DE LECTURA (2) | La transacción T1 puede experimentar lectura A' (lectura no repetible) para la tabla que fue actualizada y consignada por otra transacción T2 mientras que está viendo la tabla A repetidamente. La transacción T1 puede experimentar lectura R' (lectura no repetible) para el registro que fue actualizado y consignado por otra transacción T2 mientras se está obteniendo el registro R repetidamente.
CLASE CONSIGNADA DE LECTURA con INSTANCIAS NO CONSIGNADAS DE LECTURA (1) | La transacción T1 puede experimentar lectura A' (lectura no repetible) para la tabla que fue actualizada y consignada por otra transacción T2 mientras que se ve repetidamente la tabla A. La transacción T1 puede experimentar lectura R' (lectura basura) para el registro qeu fue actualizado pero no consignado por otra transacción T2.

### Parámetros

`conn_identifier`
  La conexión CUBRID. Si el identificador de conexión no se especifica, se asume el último enlace abierto por cubrid_connect().

### Valores devueltos

Una matriz asociativa con los parámetros de la base de datos CUBRID; en caso de éxito, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Cambia LOCK_TIMEOUT a PARAM_LOCK_TIMEOUT, y MAX_STRING_LENGTH a PARAM_MAX_STRING_LENGTH en el resultado.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_get_db_parameter()

    <?php
    printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33088, "demodb");

    if (!$conn) {
        die('Error de conexión ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Server Info:", $server_info);
    printf("%-30s %s\n", "Client Info:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "CUBRID Charset:", $charset);

    cubrid_disconnect($conn);

    ?>

El ejemplo anterior mostrará:

    CUBRID PHP Version:            9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Server Info:                   9.1.0.0212
    Client Info:                   9.1.0

    CUBRID Charset:                iso8859-1

### Ver también

- cubrid_set_db_parameter() - Define los parámetros de la base de datos CUBRID
- cubrid_get_autocommit() - Recupera el modo auto-commit de la conexión

# cubrid_get_query_timeout

(PECL CUBRID >= 8.4.1)

cubrid_get_query_timeout — Obtener el valor del tiempo de espera de consulta de la petición

### Descripción

function cubrid_get_query_timeout(resource `$req_identifier`): int

La función cubrid_get_query_timeout() se usa para obtener el tiempo de espera de consulta de la petición.

### Parámetros

`req_identifier`
  Identificador de petición.

### Valores devueltos

Devuelve el valor de tiempo de espera de la consulta en milisegundos de la petición actual en caso de éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_get_query_timeout()

    <?php

    $host = "localhost";
    $port = 33000;
    $db = "demodb";

    $conn =
    cubrid_connect_with_url("CUBRID:$host:$port:$db:::?login_timeout=50000&query_timeout=5000&disconnect_on_query_timeout=yes");

    $req = cubrid_prepare($conn, "SELECT * FROM code");

    $timeout = cubrid_get_query_timeout($req);
    var_dump($timeout);

    cubrid_set_query_timeout($req, 1000);
    $timeout = cubrid_get_query_timeout($req);
    var_dump($timeout);

    cubrid_close($conn);
    ?>

El ejemplo anterior mostrará:

    int(5000)
    int(1000)

### Ver también

- cubrid_set_query_timeout() - Define el tiempo máximo de ejecución de una consulta

# cubrid_get_server_info

(PECL CUBRID >= 8.3.0)

cubrid_get_server_info — Devolver la versión del servidor CUBRID

### Descripción

function cubrid_get_server_info(resource `$conn_identifier`): string

Esta función devuelve una cadena que representa la versión del servidor CUBRID.

### Parámetros

`conn_identifier`
  La conexión CUBRID.

### Valores devueltos

Una cadena que representa la versión del servidor CUBRID; en caso de éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_get_server_info()

    <?php
    printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33088, "demodb");

    if (!$conn) {
        die('Error de conexión ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Server Info:", $server_info);
    printf("%-30s %s\n", "Client Info:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "CUBRID Charset:", $charset);

    cubrid_disconnect($conn);

    ?>

El ejemplo anterior mostrará:

    CUBRID PHP Version:            9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Server Info:                   9.1.0.0212
    Client Info:                   9.1.0

    CUBRID Charset:                iso8859-1

# cubrid_insert_id

(PECL CUBRID >= 8.3.0)

cubrid_insert_id — Devuelve el ID generado por la última columna actualizada `AUTO_INCREMENT`

### Descripción

function cubrid_insert_id(resource `$conn_identifier` = ?): string

La función cubrid_insert_id() recupera el ID generado para la columna AUTO_INCREMENT que fue actualizada por la consulta INSERT previa. Devuelve 0 si la consulta previa no generó nuevas filas, o FALSE en caso de error.

> Nota: CUBRID soporta AUTO_INCREMENT para más de una columna en una tabla. En la mayoría de los casos, habrá una única columna AUTO_INCREMENT en una tabla. Si hay varias columnas AUTO_INCREMENT, esta función no debería ser usada aunque devuelva un valor.

### Parámetros

`conn_identifier`
  El Identificador de conexión previamente obtenido por una llamada a cubrid_connect().

### Valores devueltos

Un string representa el ID generado para una columna AUTO:INCREMENT por la consulta previa, en caso de éxito.

0, si la consulta previa no generó nuevas filas.

`false` en caso de fallo.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Cambia el valor devuelto de un array a un string; elimina el primer parámetro class_name.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_insert_id()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    @cubrid_execute($conn, "DROP TABLE cubrid_test");
    cubrid_execute($conn, "CREATE TABLE cubrid_test (d int AUTO_INCREMENT(1, 2), t varchar)");

    for ($i = 0; $i < 10; $i++) {
        cubrid_execute($conn, "INSERT INTO cubrid_test(t) VALUES('cubrid_test')");
    }

    $id = cubrid_insert_id();
    var_dump($id);

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    string(2) "19"

# cubrid_is_instance

(PECL CUBRID >= 8.3.0)

cubrid_is_instance — Comprobar si existe la instancia apuntada por OID

### Descripción

function cubrid_is_instance(resource `$conn_identifier`, string `$oid`): int

La función cubrid_is_instance() se usa para comprobar si existe la instancia apuntada por el `oid` dado o no.

### Parámetros

`conn_identifier`
  Identificador de conexión.
`oid`
  OID de la instancia que se quiere comprobar su existencia.

### Valores devueltos

1, si tal instancia existe;

0, si tal instancia no existe;

-1, en caso de error

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_is_instance()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $sql = <<<EOD
    SELECT host_year, medal, game_date
    FROM game
    WHERE athlete_code IN
        (SELECT code FROM athlete WHERE name='Thorpe Ian');
    EOD;

    $req = cubrid_execute($conn, $sql, CUBRID_INCLUDE_OID);
    $oid = cubrid_current_oid($req);

    $res = cubrid_is_instance ($conn, $oid);
    if ($res == 1) {
        echo "La instancia a puntada por $oid existe.\n";
    } else if ($res == 0){
        echo "La instancia a puntada por $oid no existe.\n";
    } else {
        echo "error\n";
    }

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    La instancia apuntada por @0|0|0 no existe.

### Ver también

- cubrid_drop() - Borrar una instancia usando OID
- cubrid_get_class_name() - Obtener el nombre de la clase usando OID

# cubrid_lob_close

(PECL CUBRID >= 8.3.1)

cubrid_lob_close — Cerrar información BLOB/CLOB

### Descripción

function cubrid_lob_close(array `$lob_identifier_array`): bool

cubrid_lob_close() se usa para cerrar todos los BLOB/CLOB devueltos desde cubrid_lob_get().

### Parámetros

`lob_identifier_array`
  Array de identificadores LOB devuelto desde cubrid_lob_get().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_lob_close()

    <?php
    $conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");
    echo "Tamaño del documento: ".cubrid_lob_size($lobs[0])." bytes";
    cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
    cubrid_lob_close($lobs);
    cubrid_disconnect($conn);
    ?>

### Ver también

- cubrid_lob_get() - Recupera los datos BLOB/CLOB
- cubrid_lob_size() - Recupera el tamaño de los datos BLOB/CLOB
- cubrid_lob_export() - Exporta datos BLOB/CLOB a un fichero
- cubrid_lob_send() - Lee los datos BLOB/CLOB y los envía al navegador

# cubrid_lob_export

(PECL CUBRID >= 8.3.1)

cubrid_lob_export — Exporta datos BLOB/CLOB a un fichero

### Descripción

function cubrid_lob_export(resource `$conn_identifier`, resource `$lob_identifier`, string `$path_name`): bool

La función cubrid_lob_export() se utiliza para recuperar los datos BLOB/CLOB desde la base de datos CUBRID, y guardar sus contenidos en un fichero. Para utilizar esta función, es necesario utilizar primero la función cubrid_lob_get() para recuperar las informaciones de los BLOB/CLOB desde CUBRID.

### Parámetros

`conn_identifier`
  Identificador de conexión.
`lob_identifier`
  Identificador LOB.
`path_name`
  Ruta hacia el fichero.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_lob_export()

    <?php
    $conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");
    echo "Tamaño del documento: ".cubrid_lob_size($lobs[0])." bytes";
    cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
    cubrid_lob_close($lobs);
    cubrid_disconnect($conn);
    ?>

### Ver también

- cubrid_lob_get() - Recupera los datos BLOB/CLOB
- cubrid_lob_close() - Cerrar información BLOB/CLOB
- cubrid_lob_size() - Recupera el tamaño de los datos BLOB/CLOB
- cubrid_lob_send() - Lee los datos BLOB/CLOB y los envía al navegador

# cubrid_lob_get

(PECL CUBRID >= 8.3.1)

cubrid_lob_get — Recupera los datos BLOB/CLOB

### Descripción

function cubrid_lob_get(resource `$conn_identifier`, string `$sql`): array

La función cubrid_lob_get() se utiliza para recuperar los datos de información meta BLOB/CLOB desde la base de datos CUBRID (CUBRID recupera los BLOB/CLOB ejecutando una consulta SQL), y devuelve todos los LOBs en forma de un array de recursos. Asegúrese de que el SQL recupere únicamente una columna y que el tipo de datos sea BLOB o CLOB.

Tenga en cuenta que el uso de la función cubrid_lob_close() libera los LOBs si ya no son necesarios.

### Parámetros

`conn_identifier`
  Identificador de conexión.
`sql`
  Consulta SQL a ejecutar.

### Valores devueltos

Devuelve un array de recursos LOB en caso de éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_lob_get()

    <?php
    $conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");
    echo "Tamaño del documento: ".cubrid_lob_size($lobs[0])." bytes";
    cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
    cubrid_lob_close($lobs);
    cubrid_disconnect($conn);
    ?>

### Ver también

- cubrid_lob_close() - Cerrar información BLOB/CLOB
- cubrid_lob_size() - Recupera el tamaño de los datos BLOB/CLOB
- cubrid_lob_export() - Exporta datos BLOB/CLOB a un fichero
- cubrid_lob_send() - Lee los datos BLOB/CLOB y los envía al navegador

# cubrid_lob_send

(PECL CUBRID >= 8.3.1)

cubrid_lob_send — Lee los datos BLOB/CLOB y los envía al navegador

### Descripción

function cubrid_lob_send(resource `$conn_identifier`, resource `$lob_identifier`): bool

La función cubrid_lob_send() lee datos BLOB/CLOB y los pasa al navegador. Para utilizar esta función, es necesario utilizar primero la función cubrid_lob_get() para recuperar las informaciones de los BLOB/CLOB desde CUBRID.

### Parámetros

`conn_identifier`
  Identificador de conexión.
`lob_identifier`
  Identificador LOB.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_lob_send()

    <?php
    $conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");

    cubrid_lob_send($conn, $lobs[0]);
    cubrid_lob_close($lobs);
    cubrid_disconnect($conn);
    ?>

### Ver también

- cubrid_lob_get() - Recupera los datos BLOB/CLOB
- cubrid_lob_close() - Cerrar información BLOB/CLOB
- cubrid_lob_size() - Recupera el tamaño de los datos BLOB/CLOB
- cubrid_lob_export() - Exporta datos BLOB/CLOB a un fichero

# cubrid_lob_size

(PECL CUBRID >= 8.3.1)

cubrid_lob_size — Recupera el tamaño de los datos BLOB/CLOB

### Descripción

function cubrid_lob_size(resource `$lob_identifier`): string

La función cubrid_lob_size() se utiliza para recuperar el tamaño de los datos BLOB/CLOB.

### Parámetros

`lob_identifier`
  Identificador LOB.

### Valores devueltos

Una cadena representando el tamaño de los datos LOB, cuando la operación ha tenido éxito, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | El tipo del valor devuelto ha cambiado. Antes era un entero, ahora es una cadena de caracteres.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_lob_size()

    <?php
    $lobs = cubrid_lob_get($con, "SELECT doc_content FROM doc WHERE doc_id=5");
    echo "Tamaño de la documentación :".cubrid_lob_size($lobs[0]);
    cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
    cubrid_lob_close($lobs);
    ?>

### Ver también

- cubrid_lob_get() - Recupera los datos BLOB/CLOB
- cubrid_lob_close() - Cerrar información BLOB/CLOB
- cubrid_lob_export() - Exporta datos BLOB/CLOB a un fichero
- cubrid_lob_send() - Lee los datos BLOB/CLOB y los envía al navegador

# cubrid_lob2_bind

(PECL CUBRID >= 8.4.1)

cubrid_lob2_bind — Asocia un objeto LOB o una cadena de caracteres a un objeto LOB como argumento de una consulta preparada

### Descripción

function cubrid_lob2_bind(
resource `$req_identifier`,
int `$bind_index`,
mixed `$bind_value`,
string `$bind_value_type` = ?
): bool

La función cubrid_lob2_bind() se utiliza para asociar datos BLOB/CLOB a un marcador correspondiente en una consulta SQL pasada a la función cubrid_prepare(). Si el argumento `bind_value_type` no se proporciona, la cadena será por omisión "BLOB". Pero si se utiliza primero la función cubrid_lob2_new(), el argumento `bind_value_type` será consistente con el argumento `type` en la función cubrid_lob2_new().

### Parámetros

`req_identifier`
  Identificador de la petición, resultado de la función cubrid_prepare().
`bind_index`
  Posición de los argumentos asociados. Comienza en 1.
`bind_value`
  Valor actual para la asociación.
`bind_value_type`
  Debe ser "BLOB" o "CLOB" y no es sensible a mayúsculas/minúsculas. Si no se proporciona, el valor por omisión será "BLOB".

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_lob2_bind()

    <?php
    // Tabla : test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES (?, ?)");

    cubrid_bind($req,1, 3);

    $lob = cubrid_lob2_new($conn, 'CLOB');
    cubrid_lob2_bind($req, 2, $lob);

    cubrid_execute($req);

    cubrid_bind($req, 1, 4);

    cubrid_lob2_bind($req, 2, 'CUBRID LOB2 TEST', 'CLOB');

    cubrid_execute($req);

    cubrid_disconnect($conn);
    ?>

### Ver también

- cubrid_lob2_new() - Crea un nuevo objeto LOB
- cubrid_lob2_close() - Cierra un objeto LOB

# cubrid_lob2_close

(PECL CUBRID >= 8.4.1)

cubrid_lob2_close — Cierra un objeto LOB

### Descripción

function cubrid_lob2_close(resource `$lob_identifier`): bool

La función cubrid_lob2_close() se utiliza para cerrar un objeto LOB, devuelto por la función cubrid_lob2_new() o recuperado desde el conjunto de resultados.

### Parámetros

`lob_identifier`
  Un identificador LOB, resultado de la función cubrid_lob2_new() o recuperado desde el conjunto de resultados.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- cubrid_lob2_new() - Crea un nuevo objeto LOB

# cubrid_lob2_export

(PECL CUBRID >= 8.4.1)

cubrid_lob2_export — Exporta un objeto LOB a un fichero

### Descripción

function cubrid_lob2_export(resource `$lob_identifier`, string `$file_name`): bool

La función cubrid_lob2_export() se utiliza para guardar los datos BLOB/CLOB en un fichero. Para utilizar esta función, primero debe utilizarse la función cubrid_lob2_new() o recuperarse un objeto LOB desde la base de datos CUBRID. Si el fichero no existe, la operación fallará. Esta función no modificará la posición del cursor del objeto LOB. Opera sobre el objeto LOB en su totalidad.

### Parámetros

`lob_identifier`
  Un identificador LOB resultante de la función cubrid_lob2_new() o recuperado desde el juego de resultados.
`filename`
  Nombre del fichero en el cual se desean guardar los datos BLOB/CLOB. La ruta hacia el fichero también puede ser especificada.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 cubrid_lob2_export() ejemplo

    <?php
    // Tabla : test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $req = cubrid_prepare($conn, "select * from doc");

    cubrid_execute($req);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);

    $row = cubrid_fetch($req, CUBRID_NUM | CUBRID_LOB);

    cubrid_lob2_export($row[1], "doc_3.txt");

    cubrid_lob2_close($row[1]);
    cubrid_disconnect($conn);
    ?>

### Ver también

- cubrid_lob2_new() - Crea un nuevo objeto LOB
- cubrid_lob2_close() - Cierra un objeto LOB
- cubrid_lob2_import() - Importa datos BLOB/CLOB desde un fichero
- cubrid_lob2_bind() - Asocia un objeto LOB o una cadena de caracteres a un objeto LOB como argumento de una consulta preparada

# cubrid_lob2_import

(PECL CUBRID >= 8.4.1)

cubrid_lob2_import — Importa datos BLOB/CLOB desde un fichero

### Descripción

function cubrid_lob2_import(resource `$lob_identifier`, string `$file_name`): bool

La función cubrid_lob2_import() se utiliza para importar datos BLOB/CLOB desde un fichero. Para utilizar esta función, primero debe utilizarse la función cubrid_lob2_new() o recuperarse un objeto LOB desde la base de datos CUBRID. Si el fichero no existe, la operación fallará. Esta función no afecta a la posición del cursor en el objeto LOB; opera sobre el objeto LOB en su totalidad.

### Parámetros

`lob_identifier`
  Un identificador LOB, resultado de la función cubrid_lob2_new() o recuperado desde el juego de resultados.
`filename`
  El nombre del fichero desde el cual los datos BLOB/CLOB deben ser importados. La ruta hacia el fichero también es soportada.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_lob2_export()

    <?php

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES (?, ?)");
    cubrid_bind($req, 1, 1);

    $lob = cubrid_lob2_new($conn, "clob");
    cubrid_lob2_import($lob, "doc_1.txt");
    cubrid_lob2_bind($req, 2, $lob, 'CLOB'); // o cubrid_lob2_bind($req, 2, $lob);

    cubrid_execute($req);

    cubrid_lob2_close($lob);
    cubrid_disconnect($conn);
    ?>

### Ver también

- cubrid_lob2_new() - Crea un nuevo objeto LOB
- cubrid_lob2_close() - Cierra un objeto LOB
- cubrid_lob2_export() - Exporta un objeto LOB a un fichero
- cubrid_lob2_bind() - Asocia un objeto LOB o una cadena de caracteres a un objeto LOB como argumento de una consulta preparada

# cubrid_lob2_new

(PECL CUBRID >= 8.4.1)

cubrid_lob2_new — Crea un nuevo objeto LOB

### Descripción

function cubrid_lob2_new(resource `$conn_identifier` = ?, string `$type` = "BLOB"): resource

La función cubrid_lob2_new() se utiliza para crear un nuevo objeto LOB (tanto BLOB como CLOB). Esta función debe ser utilizada antes de vincular un objeto LOB.

### Parámetros

`conn_identifier`
  Un identificador de conexión. Si no se especifica, se utilizará la última conexión abierta con la función cubrid_connect() o la función cubrid_connect_with_url().
`type`
  Puede ser "BLOB" o "CLOB", y no es sensible a mayúsculas/minúsculas. El valor por omisión es "BLOB".

### Valores devueltos

Un identificador LOB en caso de éxito, o `false` si ocurre un error.

### Ver también

- cubrid_lob2_close() - Cierra un objeto LOB

# cubrid_lob2_read

(PECL CUBRID >= 8.4.1)

cubrid_lob2_read — Lee datos BLOB/CLOB

### Descripción

function cubrid_lob2_read(resource `$lob_identifier`, int `$len`): string

La función cubrid_lob2_read() lee `len` bytes desde los datos LOB, y devuelve los bytes leídos.

### Parámetros

`lob_identifier`
  Un identificador LOB, resultado de la función cubrid_lob2_new() o recuperado desde el conjunto de resultados.
`len`
  Cantidad de datos a leer desde los datos LOB.

### Valores devueltos

Devuelve el contenido como string, `false` cuando no hay más datos, o `null` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo 1 con cubrid_lob2_read()

    <?php
    // test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "public", "");

    $req = cubrid_execute($conn, "select * from test_lob");

    $row = cubrid_fetch_row($req, CUBRID_LOB);

    print "position now is " . cubrid_lob2_tell($row[1]) . "\n";

    cubrid_lob2_seek($row[1], 10, CUBRID_CURSOR_FIRST);

    print "\nPosición después del desplazamiento: " . cubrid_lob2_tell($row[1]) . "\n";

    $data = cubrid_lob2_read($row[1], 12);

    print "\nPosición después de la lectura: " . cubrid_lob2_tell($row[1]) . "\n";

    print $data . "\n";

    cubrid_lob2_seek($row[1], 5, CUBRID_CURSOR_CURRENT);

    print "\nPosición después de un nuevo desplazamiento: " . cubrid_lob2_tell($row[1]) . "\n";

    $data = cubrid_lob2_read($row[1], 20);
    print $data . "\n";

    cubrid_disconnect($conn);
    ?>

Ejemplo #2 Ejemplo 2 con cubrid_lob2_read()

    <?php
    // test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    $req = cubrid_execute($conn, "select * from test_lob");

    $row = cubrid_fetch_row($req, CUBRID_LOB);

    while (true) {
        if ($data = cubrid_lob2_read($row[1], 1024)) {
            print $data . "\n";
        }
        elseif ($data === false) {
            print "No hay más datos\n";
            break;
        }
        else {
            print "Ha ocurrido un error\n";
            break;
        }
    }

    cubrid_disconnect($conn);
    ?>

### Ver también

- cubrid_lob2_write() - Escribe en un objeto LOB
- cubrid_lob2_seek() - Desplaza el cursor de un objeto LOB
- cubrid_lob2_seek64() - Desplaza el cursor de un objeto LOB
- cubrid_lob2_tell() - Recupera la posición del cursor en un objeto LOB
- cubrid_lob2_tell64() - Recupera la posición del cursor en el objeto LOB
- cubrid_lob2_size() - Obtiene el tamaño de un objeto LOB
- cubrid_lob2_size64() - Recupera el tamaño de un objeto LOB

# cubrid_lob2_seek

(PECL CUBRID >= 8.4.1)

cubrid_lob2_seek — Desplaza el cursor de un objeto LOB

### Descripción

function cubrid_lob2_seek(resource `$lob_identifier`, int `$offset`, int `$origin` = CUBRID_CURSOR_CURRENT): bool

La función cubrid_lob2_seek() se utiliza para desplazar la posición del cursor de un objeto LOB según el argumento `offset` especificado, y en la dirección indicada por el argumento `origin`.

Para definir el argumento `origin`, puede utilizarse la constante `CUBRID_CURSOR_FIRST` para desplazar la posición del cursor `offset` unidades hacia adelante desde el inicio. En este caso, `offset` debe ser un valor positivo.

Si se utiliza la constante `CUBRID_CURSOR_CURRENT` para el parámetro `origin`, puede desplazarse hacia adelante o hacia atrás. El argumento `offset` puede ser negativo o positivo.

Si se utiliza la constante `CUBRID_CURSOR_LAST` para el parámetro `origin`, puede desplazarse hacia atrás `offset` unidades desde el final del objeto LOB; el argumento `offset` solo puede ser positivo en este caso.

### Parámetros

`lob_identifier`
  Un identificador LOB, resultado de la función cubrid_lob2_new() o recuperado desde el conjunto de resultados.
`offset`
  Número de unidades a utilizar para desplazar el cursor.
`origin`
  Este parámetro puede tomar los siguientes valores: CUBRID_CURSOR_FIRST: Se desplaza hacia adelante desde el inicio. CUBRID_CURSOR_CURRENT: Se desplaza hacia adelante o hacia atrás, desde la posición actual. CUBRID_CURSOR_LAST: Se desplaza hacia atrás desde el final del objeto LOB.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_lob2_seek()

    <?php
    // test_lob (id INT, contents CLOB)
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");
    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES(2, ?)");

    $lob = cubrid_lob2_new($conn, 'CLOB');
    $len = cubrid_lob2_write($lob, "Hello world");

    cubrid_lob2_seek($lob, 0, CUBRID_CURSOR_LAST);
    cubrid_lob2_write($lob, "beautiful");

    cubrid_lob2_seek($lob, 15, CUBRID_CURSOR_FIRST);
    $data = cubrid_lob2_read($lob, 5);

    echo $data."\n";

    cubrid_lob2_bind($req, 1, $lob);
    cubrid_execute($req);

    cubrid_disconnect($conn);
    ?>

### Ver también

- cubrid_lob2_read() - Lee datos BLOB/CLOB
- cubrid_lob2_write() - Escribe en un objeto LOB
- cubrid_lob2_seek64() - Desplaza el cursor de un objeto LOB
- cubrid_lob2_tell() - Recupera la posición del cursor en un objeto LOB
- cubrid_lob2_tell64() - Recupera la posición del cursor en el objeto LOB
- cubrid_lob2_size() - Obtiene el tamaño de un objeto LOB
- cubrid_lob2_size64() - Recupera el tamaño de un objeto LOB

# cubrid_lob2_seek64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_seek64 — Desplaza el cursor de un objeto LOB

### Descripción

function cubrid_lob2_seek64(resource `$lob_identifier`, string `$offset`, int `$origin` = CUBRID_CURSOR_CURRENT): bool

La función cubrid_lob2_seek64() se utiliza para desplazar la posición del cursor en un objeto LOB de un valor proporcionado por el argumento `offset`, en la dirección proporcionada por el argumento `origin`. Si la posición `offset` es mayor que la capacidad de almacenamiento de un entero, puede utilizarse esta función.

Para definir el argumento `origin`, puede utilizarse la constante `CUBRID_CURSOR_FIRST` para definir la posición del cursor a la que se añaden `offset` unidades desde el principio. En este caso, `offset` debe ser un valor positivo.

Si se utiliza `CUBRID_CURSOR_CURRENT` para el argumento `origin`, puede desplazarse hacia atrás, así como hacia adelante. Y el argumento `offset` podrá ser positivo o negativo.

Si se utiliza la constante `CUBRID_CURSOR_LAST` para el argumento `origin`, puede desplazarse hacia atrás de `offset` unidades desde el final del objeto LOB y el argumento `offset` solo podrá ser positivo.

> Nota: Si se utiliza esta función para desplazar la posición del cursor de un objeto LOB, debe pasarse el argumento `offset` en forma de string.

### Parámetros

`lob_identifier`
  Un identificador LOB, recuperado desde la función cubrid_lob2_new() o desde el conjunto de resultados.
`offset`
  Número de unidades de desplazamiento del cursor.
`origin`
  Este argumento puede tomar los siguientes valores: CUBRID_CURSOR_FIRST: desplaza el cursor hacia adelante partiendo del principio. CUBRID_CURSOR_CURRENT: desplaza el cursor hacia atrás y hacia adelante desde la posición actual. CUBRID_CURSOR_LAST: desplaza el cursor hacia atrás desde el final del objeto LOB.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_lob2_seek64()

    <?php
    // test_lob (id INT, contents CLOB)
    // La longitud de los datos de doc_1.txt debe ser superior a 20101029056306120215.

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES (?, ?)");
    cubrid_bind($req, 1, 1);

    $lob = cubrid_lob2_new($conn, "clob");
    cubrid_lob2_import($lob, "doc_1.txt");
    cubrid_lob2_bind($req, 2, $lob, 'CLOB'); // o cubrid_lob2_bind($req, 2, $lob);

    cubrid_execute($req);

    cubrid_lob2_close($lob);

    $req = cubrid_execute($conn, "select * from test_lob");
    $row = cubrid_fetch_row($req, CUBRID_LOB);
    $lob = $row[1];

    cubrid_lob2_seek64($lob, "20101029056306120215", CUBRID_CURSOR_FIRST);
    $data = cubrid_lob2_read($lob, 20);
    echo $data."\n";
    cubrid_disconnect($conn);
    ?>

### Ver también

- cubrid_lob2_read() - Lee datos BLOB/CLOB
- cubrid_lob2_write() - Escribe en un objeto LOB
- cubrid_lob2_seek() - Desplaza el cursor de un objeto LOB
- cubrid_lob2_tell() - Recupera la posición del cursor en un objeto LOB
- cubrid_lob2_tell64() - Recupera la posición del cursor en el objeto LOB
- cubrid_lob2_size() - Obtiene el tamaño de un objeto LOB
- cubrid_lob2_size64() - Recupera el tamaño de un objeto LOB

# cubrid_lob2_size

(PECL CUBRID >= 8.4.1)

cubrid_lob2_size — Obtiene el tamaño de un objeto LOB

### Descripción

function cubrid_lob2_size(resource `$lob_identifier`): int

La función cubrid_lob2_size() se utiliza para obtener el tamaño de un objeto LOB.

### Parámetros

`lob_identifier`
  Un identificador LOB, obtenido desde la función cubrid_lob2_new() o desde el conjunto de resultados.

### Valores devueltos

Devuelve el tamaño del objeto LOB en caso de éxito, o `false` si ocurre un error.

### Ver también

- cubrid_lob2_read() - Lee datos BLOB/CLOB
- cubrid_lob2_write() - Escribe en un objeto LOB
- cubrid_lob2_seek() - Desplaza el cursor de un objeto LOB
- cubrid_lob2_seek64() - Desplaza el cursor de un objeto LOB
- cubrid_lob2_tell() - Recupera la posición del cursor en un objeto LOB
- cubrid_lob2_tell64() - Recupera la posición del cursor en el objeto LOB
- cubrid_lob2_size64() - Recupera el tamaño de un objeto LOB

# cubrid_lob2_size64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_size64 — Recupera el tamaño de un objeto LOB

### Descripción

function cubrid_lob2_size64(resource `$lob_identifier`): string

La función cubrid_lob2_size64() se utiliza para recuperar el tamaño de un objeto LOB. Si el tamaño del objeto LOB es mayor que la capacidad de almacenamiento de un entero, puede utilizarse esta función, y devolverá el tamaño en forma de string.

### Parámetros

`lob_identifier`
  Un identificador LOB, recuperado desde la función cubrid_lob2_new() o desde el conjunto de resultados.

### Valores devueltos

Devuelve el tamaño de un objeto LOB en forma de string en caso de éxito, o `false` si ocurre un error.

### Ver también

- cubrid_lob2_read() - Lee datos BLOB/CLOB
- cubrid_lob2_write() - Escribe en un objeto LOB
- cubrid_lob2_seek() - Desplaza el cursor de un objeto LOB
- cubrid_lob2_seek64() - Desplaza el cursor de un objeto LOB
- cubrid_lob2_tell() - Recupera la posición del cursor en un objeto LOB
- cubrid_lob2_tell64() - Recupera la posición del cursor en el objeto LOB
- cubrid_lob2_size() - Obtiene el tamaño de un objeto LOB

# cubrid_lob2_tell

(PECL CUBRID >= 8.4.1)

cubrid_lob2_tell — Recupera la posición del cursor en un objeto LOB

### Descripción

function cubrid_lob2_tell(resource `$lob_identifier`): int

La función cubrid_lob2_tell() se utiliza para recuperar la posición del cursor en el objeto LOB.

### Parámetros

`lob_identifier`
  Un identificador LOB, recuperado desde la función cubrid_lob2_new() o desde el juego de resultados.

### Valores devueltos

Devuelve la posición del cursor en el objeto LOB en caso de éxito, o `false` si ocurre un error.

### Ver también

- cubrid_lob2_read() - Lee datos BLOB/CLOB
- cubrid_lob2_write() - Escribe en un objeto LOB
- cubrid_lob2_seek() - Desplaza el cursor de un objeto LOB
- cubrid_lob2_seek64() - Desplaza el cursor de un objeto LOB
- cubrid_lob2_tell64() - Recupera la posición del cursor en el objeto LOB
- cubrid_lob2_size() - Obtiene el tamaño de un objeto LOB
- cubrid_lob2_size64() - Recupera el tamaño de un objeto LOB

# cubrid_lob2_tell64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_tell64 — Recupera la posición del cursor en el objeto LOB

### Descripción

function cubrid_lob2_tell64(resource `$lob_identifier`): string

La función cubrid_lob2_tell64() se utiliza para recuperar la posición del cursor en el objeto LOB. Si la longitud del objeto LOB es mayor que la capacidad de almacenamiento de un entero, puede utilizarse esta función y devolverá la información en forma de string.

### Parámetros

`lob_identifier`
  Un identificador LOB, recuperado desde la función cubrid_lob2_new() o desde el conjunto de resultados.

### Valores devueltos

Devuelve la posición del cursor en el objeto LOB, en forma de string en caso de éxito, o `false` si ocurre un error.

### Ver también

- cubrid_lob2_read() - Lee datos BLOB/CLOB
- cubrid_lob2_write() - Escribe en un objeto LOB
- cubrid_lob2_seek() - Desplaza el cursor de un objeto LOB
- cubrid_lob2_seek64() - Desplaza el cursor de un objeto LOB
- cubrid_lob2_tell() - Recupera la posición del cursor en un objeto LOB
- cubrid_lob2_size() - Obtiene el tamaño de un objeto LOB
- cubrid_lob2_size64() - Recupera el tamaño de un objeto LOB

# cubrid_lob2_write

(PECL CUBRID >= 8.4.1)

cubrid_lob2_write — Escribe en un objeto LOB

### Descripción

function cubrid_lob2_write(resource `$lob_identifier`, string `$buf`): bool

La función cubrid_lob2_write() lee los datos desde el argumento `buf` y los almacena en el objeto LOB. Tenga en cuenta que esta función solo puede añadir caracteres actualmente.

### Parámetros

`lob_identifier`
  Un identificador LOB, obtenido desde la función cubrid_lob2_new() o desde el conjunto de resultados.
`buf`
  Los datos que deben ser escritos en el objeto LOB.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo 1 con cubrid_lob2_write()

    <?php
    // test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES(2, ?)");

    $lob = cubrid_lob2_new($conn, 'CLOB');
    $len = cubrid_lob2_write($lob, "Hello world");

    cubrid_lob2_bind($req, 1, $lob);
    cubrid_execute($req);

    cubrid_disconnect($conn);
    ?>

Ejemplo #2 Ejemplo 2 con cubrid_lob2_write()

    <?php
    // test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES(1, ?)");
    $lob1 = cubrid_lob2_new($conn, 'CLOB');
    $len = cubrid_lob2_write($lob1, "cubrid php driver");
    cubrid_lob2_bind($req, 1, $lob1);
    cubrid_execute($req);

    $req = cubrid_execute($conn, "select * from test_lob");

    $row = cubrid_fetch_row($req, CUBRID_LOB);
    $lob2 = $row[1];
    cubrid_lob2_seek($lob2, 0, CUBRID_CURSOR_LAST);

    $pos = cubrid_lob2_tell($lob2);
    print "pos before write: $pos\n";

    cubrid_lob2_write($lob2, "Hello world");

    $pos = cubrid_lob2_tell($lob2);
    print "Posición después de escribir: $pos\n";

    cubrid_disconnect($conn);
    ?>

### Ver también

- cubrid_lob2_read() - Lee datos BLOB/CLOB
- cubrid_lob2_seek() - Desplaza el cursor de un objeto LOB
- cubrid_lob2_seek64() - Desplaza el cursor de un objeto LOB
- cubrid_lob2_tell() - Recupera la posición del cursor en un objeto LOB
- cubrid_lob2_tell64() - Recupera la posición del cursor en el objeto LOB
- cubrid_lob2_size() - Obtiene el tamaño de un objeto LOB
- cubrid_lob2_size64() - Recupera el tamaño de un objeto LOB

# cubrid_lock_read

(PECL CUBRID >= 8.3.0)

cubrid_lock_read — Coloca un bloqueo de lectura sobre el OID proporcionado

### Descripción

function cubrid_lock_read(resource `$conn_identifier`, string `$oid`): bool

La función cubrid_lock_read() se utiliza para colocar un bloqueo de lectura sobre la instancia apuntada por el `oid` proporcionado.

### Parámetros

`conn_identifier`
  Identificador de conexión.
`oid`
  OID de la instancia cuya lectura se desea bloquear.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_lock_read()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    cubrid_lock_read($conn, $oid);

    $attr = cubrid_get($conn, $oid, "b");
    var_dump($attr);

    $attr = cubrid_get($conn, $oid);
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    string(9) "{1, 2, 3}"
    array(4) {
      ["a"]=>
      string(1) "1"
      ["b"]=>
      array(3) {
        [0]=>
        string(1) "1"
        [1]=>
        string(1) "2"
        [2]=>
        string(1) "3"
      }
      ["c"]=>
      array(4) {
        [0]=>
        string(2) "11"
        [1]=>
        string(2) "22"
        [2]=>
        string(2) "33"
        [3]=>
        string(3) "333"
      }
      ["d"]=>
      string(10) "a         "
    }

### Ver también

- cubrid_lock_write() - Coloca un bloqueo de escritura en el OID proporcionado

# cubrid_lock_write

(PECL CUBRID >= 8.3.0)

cubrid_lock_write — Coloca un bloqueo de escritura en el OID proporcionado

### Descripción

function cubrid_lock_write(resource `$conn_identifier`, string `$oid`): bool

La función cubrid_lock_write() se utiliza para colocar un bloqueo de escritura en la instancia apuntada por el `oid` proporcionado.

### Parámetros

`conn_identifier`
  Identificador de conexión.
`oid`
  OID de la instancia sobre la que se desea colocar un bloqueo de escritura.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_lock_write()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    cubrid_lock_write($conn, $oid);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_put($conn, $oid, "b", array(2, 4, 8));

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    array(3) {
      [0]=>
      string(1) "2"
      [1]=>
      string(1) "4"
      [2]=>
      string(1) "8"
    }

### Ver también

- cubrid_lock_read() - Coloca un bloqueo de lectura sobre el OID proporcionado

# cubrid_move_cursor

(PECL CUBRID >= 8.3.0)

cubrid_move_cursor — Desplaza el cursor en el resultado

### Descripción

function cubrid_move_cursor(resource `$req_identifier`, int `$offset`, int `$origin` = CUBRID_CURSOR_CURRENT): bool

La función cubrid_move_cursor() se utiliza para desplazar el cursor actual según el parámetro `req_identifier` con el valor del parámetro `offset` y en la dirección definida por el parámetro `origin` argumento. Para definir el argumento `origin`, se puede utilizar `CUBRID_CURSOR_FIRST` para la primera parte del resultado, `CUBRID_CURSOR_CURRENT` para la posición actual del resultado, o `CUBRID_CURSOR_LAST` para la última parte del resultado. Si el argumento `origin` no es explícitamente designado, entonces la función utilizará `CUBRID_CURSOR_CURRENT` como valor por omisión.

Si el valor actual del desplazamiento del cursor está más allá de los límites válidos, entonces el cursor se desplaza a la siguiente posición después del intervalo válido del cursor. Por ejemplo, si se desplaza 20 unidades en el resultado cuyo tamaño es de 10, entonces el cursor se colocará en la 11ª posición y devolverá `CUBRID_NO_MORE_DATA`.

### Parámetros

`req_identifier`
  Identificador de la consulta.
`offset`
  Número de unidades que se desean utilizar para el desplazamiento.
`origin`
  Objetivo donde se desea desplazar el cursor, ya sea `CUBRID_CURSOR_FIRST`, `CUBRID_CURSOR_CURRENT`, `CUBRID_CURSOR_LAST`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_move_cursor()

    <?php
    $conn = cubrid_connect("127.0.0.1", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code");
    cubrid_move_cursor($req, 1, CUBRID_CURSOR_LAST);

    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_CURRENT);
    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    array(2) {
      [0]=>
      string(1) "G"
      [1]=>
      string(4) "Gold"
    }
    array(2) {
      [0]=>
      string(1) "X"
      [1]=>
      string(5) "Mixed"
    }
    array(2) {
      [0]=>
      string(1) "M"
      [1]=>
      string(3) "Man"
    }

### Ver también

- cubrid_execute() - Ejecutar una sentencia SQL preparada

# cubrid_next_result

(PECL CUBRID >= 8.4.0)

cubrid_next_result — Recupera el resultado de la siguiente consulta durante la ejecución de múltiples consultas SQL

### Descripción

function cubrid_next_result(resource `$result`): bool

La función cubrid_next_result() se utiliza para recuperar los resultados de la siguiente consulta si se ejecutan múltiples consultas SQL y el flag `CUBRID_EXEC_QUERY_ALL` está definido al utilizar la función cubrid_execute().

### Parámetros

`result`
  El argumento `result` proviene de la llamada a la función cubrid_execute()

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_next_result()

    <?php
    $conn = cubrid_connect("127.0.0.1", 33000, "demodb", "dba");

    $sql_stmt = "SELECT * FROM code; SELECT * FROM history WHERE host_year=2004 AND event_code=20281";
    $res = cubrid_execute($conn, $sql_stmt, CUBRID_EXEC_QUERY_ALL);

    get_result_info($res);
    cubrid_next_result($res);
    get_result_info($res);

    function get_result_info($req)
    {
        printf("\n------------ get_result_info --------------------\n");

        $row_num = cubrid_num_rows($req);
        $col_num = cubrid_num_cols($req);

        $column_name_list = cubrid_column_names($req);
        $column_type_list = cubrid_column_types($req);

        $column_last_name = cubrid_field_name($req, $col_num - 1);
        $column_last_table = cubrid_field_table($req, $col_num - 1);

        $column_last_type = cubrid_field_type($req, $col_num - 1);
        $column_last_len = cubrid_field_len($req, $col_num - 1);

        $column_1_flags = cubrid_field_flags($req, 1);

        printf("%-30s %d\n", "Row count:", $row_num);
        printf("%-30s %d\n", "Column count:", $col_num);
        printf("\n");

        printf("%-30s %-30s %-15s\n", "Column Names", "Column Types", "Column Len");
        printf("------------------------------------------------------------------------------\n");

        $size = count($column_name_list);
        for($i = 0; $i < $size; $i++) {
            $column_len = cubrid_field_len($req, $i);
            printf("%-30s %-30s %-15s\n", $column_name_list[$i], $column_type_list[$i], $column_len);
        }
        printf("\n\n");

        printf("%-30s %s\n", "Last Column Name:", $column_last_name);
        printf("%-30s %s\n", "Last Column Table:", $column_last_table);
        printf("%-30s %s\n", "Last Column Type:", $column_last_type);
        printf("%-30s %d\n", "Last Column Len:", $column_last_len);
        printf("%-30s %s\n", "Second Column Flags:", $column_1_flags);

        printf("\n\n");
    }
    ?>

El ejemplo anterior mostrará:

    ------------ get_result_info --------------------
    Row count:                     6
    Column count:                  2

    Column Names                   Column Types                   Column Len
    ------------------------------------------------------------------------------
    s_name                         char                           1
    f_name                         varchar                        6

    Last Column Name:              f_name
    Last Column Table:             code
    Last Column Type:              varchar
    Last Column Len:               6
    Second Column Flags:

    ------------ get_result_info --------------------
    Row count:                     4
    Column count:                  5

    Column Names                   Column Types                   Column Len
    ------------------------------------------------------------------------------
    event_code                     integer                        11
    athlete                        varchar                        40
    host_year                      integer                        11
    score                          varchar                        10
    unit                           varchar                        5

    Last Column Name:              unit
    Last Column Table:             history
    Last Column Type:              varchar
    Last Column Len:               5
    Second Column Flags:           not_null primary_key unique_key

### Ver también

- cubrid_execute() - Ejecutar una sentencia SQL preparada

# cubrid_num_cols

(PECL CUBRID >= 8.3.0)

cubrid_num_cols — Obtiene el número de columnas del conjunto de resultados

### Descripción

function cubrid_num_cols(resource `$result`): int

La función cubrid_num_cols() se utiliza para obtener el número de columnas desde el resultado de la consulta. Solo puede ser utilizada cuando la consulta es de tipo `SELECT`.

### Parámetros

`result`
  El resultado.

### Valores devueltos

Número de columnas en caso de éxito.

`false`, si la consulta SQL no es de tipo SELECT.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_num_cols()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code");

    $row_num = cubrid_num_rows($req);
    $col_num = cubrid_num_cols($req);

    printf("Row Num: %d\nColumn Num: %d\n", $row_num, $col_num);

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    Row Num: 6
    Column Num: 2

### Ver también

- cubrid_execute() - Ejecutar una sentencia SQL preparada
- cubrid_num_rows() - Obtiene el número de filas de un conjunto de resultados

# cubrid_num_rows

(PECL CUBRID >= 8.3.0)

cubrid_num_rows — Obtiene el número de filas de un conjunto de resultados

### Descripción

function cubrid_num_rows(resource `$result`): int

La función cubrid_num_rows() se utiliza para obtener el número de filas desde el conjunto de resultados. Solo puede ser utilizada cuando la consulta es de tipo `SELECT`. Cuando se desea obtener este tipo de valor para una consulta de tipo `INSERT`, `UPDATE` o `DELETE`, debe utilizarse la función cubrid_affected_rows().

Nota: La función cubrid_num_rows() solo puede ser utilizada en consultas síncronas; devuelve 0 en consultas asíncronas.

### Parámetros

`result`
  El argumento `result` proviene de una llamada a la función cubrid_execute(), la función cubrid_query() o la función cubrid_prepare().

### Valores devueltos

Número de filas en caso de éxito.

0 cuando la consulta se ha realizado en modo asíncrono.

-1, si la consulta SQL no es de tipo SELECT.

`false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_num_rows()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code");

    $row_num = cubrid_num_rows($req);
    $col_num = cubrid_num_cols($req);

    printf("Row Num: %d\nColumn Num: %d\n", $row_num, $col_num);

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    Row Num: 6
    Column Num: 2

### Ver también

- cubrid_execute() - Ejecutar una sentencia SQL preparada
- cubrid_num_cols() - Obtiene el número de columnas del conjunto de resultados
- cubrid_affected_rows() - Devolver el número de filas afectadas por la última sentencia SQL

# cubrid_pconnect

(PECL CUBRID >= 8.3.1)

cubrid_pconnect — Establece una conexión persistente con un servidor CUBRID

### Descripción

function cubrid_pconnect(
string `$host`,
int `$port`,
string `$dbname`,
string `$userid` = ?,
string `$passwd` = ?
): resource

Establece una conexión persistente con un servidor CUBRID.

cubrid_pconnect() funciona de manera similar a cubrid_connect() con dos diferencias principales.

En primer lugar, al establecer la conexión, la función intentará primero encontrar un enlace (persistente) ya abierto con el mismo nombre de host, en el mismo puerto, utilizando la misma base de datos dbname y el mismo userid. Si se encuentra un enlace de este tipo, su identificador será devuelto en lugar de abrir una nueva conexión.

En segundo lugar, la conexión con el servidor CUBRID no se cerrará cuando finalice el script. En su lugar, el enlace permanecerá abierto para su uso futuro (cubrid_close() o cubrid_disconnect() no cerrarán los enlaces establecidos con cubrid_pconnect()).

Este tipo de enlace se denominaba anteriormente 'persistente'.

### Parámetros

`host`
  Nombre del host o dirección IP del servidor CUBRID CAS.
`port`
  Número de puerto del servidor CUBRID CAS (BROKER_PORT configurado en $CUBRID/conf/cubrid_broker.conf).
`dbname`
  Nombre de la base de datos.
`userid`
  Nombre de usuario para la base de datos.
`passwd`
  Contraseña asociada al nombre de usuario.

### Valores devueltos

Identificador de conexión en caso de éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_pconnect()

    <?php
    printf("%-30s %s\n", "Versión de CUBRID PHP:", cubrid_version());

    printf("\n");

    $conn = cubrid_pconnect("localhost", 33000, "demodb", "dba");

    if (!$conn) {
        die('Error de conexión ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Información del servidor:", $server_info);
    printf("%-30s %s\n", "Información del cliente:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "Juego de caracteres CUBRID:", $charset);

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    Versión de CUBRID PHP:            9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Información del servidor:      9.1.0.0212
    Información del cliente:       9.1.0

    Juego de caracteres CUBRID:     iso8859-1

### Ver también

- cubrid_connect() - Abrir una conexión al servidor CUBRID
- cubrid_connect_with_url() - Establecer el entorno para la conexión al servidor de CUBRID
- cubrid_pconnect_with_url() - Establece una conexión persistente con un servidor CUBRID
- cubrid_disconnect() - Cerrar una conexión a una base de datos
- cubrid_close() - Cerrar la conexión de CUBRID

# cubrid_pconnect_with_url

(PECL CUBRID >= 8.3.1)

cubrid_pconnect_with_url — Establece una conexión persistente con un servidor CUBRID

### Descripción

function cubrid_pconnect_with_url(string `$conn_url`, string `$userid` = ?, string `$passwd` = ?): resource

Establece una conexión persistente con un servidor CUBRID.

cubrid_pconnect_with_url() funciona de manera similar a la función cubrid_connect_with_url(), con dos diferencias principales.

En primer lugar, al establecer la conexión, la función intentará encontrar un enlace (persistente) ya abierto con el mismo host, en el mismo puerto, en la misma base de datos dbname y utilizando el mismo userid. Si se encuentra una conexión de este tipo, su identificador será devuelto en lugar de abrir una nueva conexión.

A continuación, la conexión al servidor CUBRID no se cerrará cuando finalice el script. En su lugar, la conexión permanecerá abierta para su uso futuro (la función cubrid_close() o la función cubrid_disconnect() no cerrarán la conexión establecida por la función cubrid_pconnect_with_url()).

Este tipo de enlace se denominaba anteriormente 'persistente'.

<url> ::= CUBRID:<host>:<db_name>:<db_user>:<db_password>:[?<properties>]

<properties> ::= <property> [&<property>]

<properties> ::= alhosts=<alternative_hosts>[ &rctime=<time>]

<properties> ::= login_timeout=<milli_sec>

<properties> ::= query_timeout=<milli_sec>

<properties> ::= disconnect_on_query_timeout=true|false

<alternative_hosts> ::= <standby_broker1_host>:<port> [,<standby_broker2_host>:<port>]

<host> := HOSTNAME | IP_ADDR

<time> := SECOND

<milli_sec> := MILLI SECOND

- host : Un nombre de host o una dirección IP del servidor maestro de la base de datos
- db_name : Un nombre de base de datos
- db_user : Un nombre de usuario de la base de datos
- db_password : Una contraseña para el usuario de la base de datos
- autocommit : El modo auto-commit de la conexión a la base de datos
- alhosts : Especifica la información del broker del servidor, que será utilizado como punto de salida cuando no sea posible conectarse al servidor activo. Se pueden especificar varios brokers en este caso, y la conexión a los brokers se intentará en el orden de la configuración alhosts
- rctime : Un intervalo de tiempo para esperar antes de intentar una conexión con un broker cuando ocurre un error. Después de que ocurra un error, el sistema intentará conectarse a un broker especificado por althosts, terminará la transacción, y luego intentará conectarse al broker activo del servidor maestro de la base de datos. El valor por omisión es de 600 segundos.
- login_timeout : Valor del tiempo máximo de espera (unidad: milisegundo) para la identificación a la base de datos. Por omisión, este valor es 0, lo que significa que se espera indefinidamente.
- query_timeout : Valor del tiempo máximo de espera (unidad: milisegundo) para la ejecución de la consulta. Una vez alcanzado este valor, se envía un mensaje para cancelar la consulta enviada al servidor. El valor devuelto puede depender de la configuración de disconnect_on_query_timeout; incluso si el mensaje para cancelar la consulta ha sido enviado al servidor, la consulta puede tener éxito.
- disconnect_on_query_timeout : Configura un valor que determina si se debe devolver inmediatamente un error para las funciones ejecutadas después del tiempo máximo de espera. El valor por omisión es `false`.

> Nota: Los caracteres `?` y `:` utilizados como identificadores en las URLs de conexión PHP no pueden ser incluidos en la contraseña. A continuación se muestra un ejemplo de contraseña inválida, ya que utiliza los caracteres "`?:`" en la URL de conexión. $url = "CUBRID:localhost:33000:tdb:dba:12?:?login_timeout=100"; Las contraseñas que contienen el carácter `?` o el carácter `:` pueden ser pasadas como argumento separado. $url = "CUBRID:localhost:33000:tbd:::?login_timeout=100"; $conn = cubrid_pconnect_with_url ($url, "dba", "12?"); Si el nombre de usuario o la contraseña están vacíos, no se deben eliminar los "`:`"; a continuación se muestra un ejemplo: $url = "CUBRID:localhost:33000:demodb:::";

### Parámetros

`conn_url`
  Un string que contiene la información de conexión para el servidor.
`userid`
  Nombre de usuario para la base de datos.
`passwd`
  Contraseña para el usuario.

### Valores devueltos

Identificador de conexión, cuando el proceso tiene éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_pconnect_with_url() sin propiedades

    <?php
    $conn_url = "CUBRID:127.0.0.1:33000:demodb:dba::?althost=10.34.63.132:33088&rctime=100";
    $con = cubrid_pconnect_with_url ($conn_url);

    if ($con) {
       echo "Conexión exitosa";
       cubrid_execute($con, "create table person(id int,name char(16))");
       $req =cubrid_execute($con, "insert into person values(1,'James')");

       if ($req) {
          cubrid_close_request ($req);
          cubrid_commit ($con);
       } else {
          cubrid_rollback ($con);
       }
       cubrid_disconnect ($con);
    }
    ?>

Ejemplo #2 Ejemplo de cubrid_pconnect_with_url() con URL y propiedades

    <?php
    $conn_url = "CUBRID:127.0.0.1:33000:demodb:dba::?autocommit=off&althost=10.34.63.132:33088&rctime=100";
    $con = cubrid_pconnect_with_url ($conn_url);

    if ($con) {
       echo "Conexión exitosa";
       $req =cubrid_execute($con, "insert into person values(1,'James')");

       if ($req) {
          cubrid_close_request ($req);
          cubrid_commit ($con);
       } else {
          cubrid_rollback ($con);
       }
       cubrid_disconnect ($con);
    }
    ?>

### Ver también

- cubrid_connect() - Abrir una conexión al servidor CUBRID
- cubrid_connect_with_url() - Establecer el entorno para la conexión al servidor de CUBRID
- cubrid_pconnect() - Establece una conexión persistente con un servidor CUBRID
- cubrid_disconnect() - Cerrar una conexión a una base de datos
- cubrid_close() - Cerrar la conexión de CUBRID

# cubrid_prepare

(PECL CUBRID >= 8.3.0)

cubrid_prepare — Prepara una consulta SQL para su ejecución

### Descripción

function cubrid_prepare(resource `$conn_identifier`, string `$prepare_stmt`, int `$option` = 0): resource

La función cubrid_prepare() compila una consulta SQL para un gestor de conexión dado y devuelve un gestor que representa la consulta precompilada.

Una consulta preparada puede ser ejecutada varias veces, lo cual resulta eficiente para la ejecución repetida o para el procesamiento de grandes volúmenes de datos. Solo se puede utilizar una única consulta, y un parámetro puede marcarse con un signo de interrogación (`?`) en el lugar apropiado de la consulta SQL. Se añade un parámetro al vincular un valor en la cláusula `VALUES` de una sentencia `INSERT` o en la cláusula `WHERE`. Tenga en cuenta que un valor solo puede ser vinculado a un parámetro utilizando la función cubrid_bind().

### Parámetros

`conn_identifier`
  Identificador de conexión.
`prepare_stmt`
  Consulta preparada.
`option`
  OID devuelto por la opción `CUBRID_INCLUDE_OID`.

### Valores devueltos

Identificador de consulta en caso de éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_prepare()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $sql = <<<EOD
    SELECT g.event_code, e.name
    FROM game g
    JOIN event e ON g.event_code=e.code
    WHERE host_year = ? AND event_code NOT IN (SELECT event_code FROM game WHERE host_year=?) GROUP BY event_code;
    EOD;

    $req = cubrid_prepare($conn, $sql);

    cubrid_bind($req, 1, 2004);
    cubrid_bind($req, 2, 2000);
    cubrid_execute($req);

    $row_num = cubrid_num_rows($req);
    printf("There are %d event that exits in 2004 olympic but not in 2000. For example:\n\n", $row_num);

    printf("%-15s %s\n", "Event_code", "Event_name");
    printf("----------------------------\n");

    $row = cubrid_fetch_assoc($req);
    printf("%-15d %s\n", $row["event_code"], $row["name"]);
    $row = cubrid_fetch_assoc($req);
    printf("%-15d %s\n", $row["event_code"], $row["name"]);

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    There are 27 event that exits in 2004 olympic but not in 2000. For example:

    Event_code      Event_name
    ----------------------------
    20063           +91kg
    20070           64kg

### Ver también

- cubrid_execute() - Ejecutar una sentencia SQL preparada
- cubrid_bind() - Vincular variables para una sentencia preparada como parámetros

# cubrid_put

(PECL CUBRID >= 8.3.0)

cubrid_put — Actualiza una columna según su OID

### Descripción

function cubrid_put(
resource `$conn_identifier`,
string `$oid`,
string `$attr` = ?,
mixed `$value`
): bool

La función cubrid_put() se utiliza para actualizar un atributo de la instancia señalada por el `oid` proporcionado.

Puede actualizarse un solo atributo utilizando un string en el parámetro `attr`. En este caso, puede utilizarse un int, un número de punto flotante, o un string como `value`. Para actualizar varios atributos, debe omitirse el parámetro `attr` y definirse el argumento `value` utilizando un array asociativo.

### Parámetros

`conn_identifier`
  Identificador de conexión.
`oid`
  OID de la instancia que se desea actualizar.
`attr`
  Nombre del atributo que se desea actualizar.
`value`
  Nuevo valor que se desea asignar al atributo.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_put()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_put($conn, $oid, "b", array(2, 4, 8));

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    array(3) {
      [0]=>
      string(1) "2"
      [1]=>
      string(1) "4"
      [2]=>
      string(1) "8"
    }

### Ver también

- cubrid_get() - Obtener una columna usando OID
- cubrid_set_add() - Inserta un único elemento para definir el tipo de una columna
- cubrid_set_drop() - Elimina un elemento
- cubrid_seq_insert() - Inserta un elemento en una secuencia
- cubrid_seq_drop() - Elimina un elemento de una secuencia
- cubrid_seq_put() - Actualiza el valor de un elemento de una secuencia

# cubrid_rollback

(PECL CUBRID >= 8.3.0)

cubrid_rollback — Anula una transacción

### Descripción

function cubrid_rollback(resource `$conn_identifier`): bool

La función cubrid_rollback() anula la transacción en curso señalada por el argumento `conn_identifier`.

La conexión al servidor se cierra después de la llamada a la función cubrid_rollback(). Sin embargo, el gestor de conexión permanece activo.

### Parámetros

`conn_identifier`
  Identificador de conexión.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_rollback()

    <?php
    $conn = cubrid_connect("127.0.0.1", 33000, "demodb", "dba");
    cubrid_set_autocommit($conn,false);

    @cubrid_execute($conn, "DROP TABLE publishers");

    $sql = <<<EOD
    CREATE TABLE publishers(
    pub_id CHAR(3),
    pub_name VARCHAR(20),
    city VARCHAR(15),
    state CHAR(2),
    country VARCHAR(15)
    )
    EOD;

    if (!cubrid_execute($conn, $sql)) {
        printf("Error facility: %d\nError code: %d\nError msg: %s\n", cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }

    $req = cubrid_prepare($conn, "INSERT INTO publishers VALUES(?, ?, ?, ?, ?)");

    $id_list = array("P01", "P02", "P03", "P04");
    $name_list = array("Abatis Publishers", "Core Dump Books", "Schadenfreude Press", "Tenterhooks Press");
    $city_list = array("New York", "San Francisco", "Hamburg", "Berkeley");
    $state_list = array("NY", "CA", NULL, "CA");
    $country_list = array("USA", "USA", "Germany", "USA");

    for ($i = 0, $size = count($id_list); $i < $size; $i++) {
        cubrid_bind($req, 1, $id_list[$i]);
        cubrid_bind($req, 2, $name_list[$i]);
        cubrid_bind($req, 3, $city_list[$i]);
        cubrid_bind($req, 4, $state_list[$i]);
        cubrid_bind($req, 5, $country_list[$i]);

        if (!($ret = cubrid_execute($req))) {
            break;
        }
    }

    if (!$ret) {
        cubrid_rollback($conn);
    } else {
        cubrid_commit($conn);

        $req = cubrid_execute($conn, "SELECT * FROM publishers");
        while ($result = cubrid_fetch_assoc($req)) {
            printf("%-3s %-20s %-15s %-3s %-15s\n",
                $result["pub_id"], $result["pub_name"], $result["city"], $result["state"], $result["country"]);
        }
    }

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    P01 Abatis Publishers    New York        NY  USA
    P02 Core Dump Books      San Francisco   CA  USA
    P03 Schadenfreude Press  Hamburg             Germany
    P04 Tenterhooks Press    Berkeley        CA  USA

### Ver también

- cubrid_commit() - Consigna una transacción
- cubrid_disconnect() - Cerrar una conexión a una base de datos

# cubrid_schema

(PECL CUBRID >= 8.3.0)

cubrid_schema — Recupera información sobre un esquema

### Descripción

function cubrid_schema(
resource `$conn_identifier`,
int `$schema_type`,
string `$class_name` = ?,
string `$attr_name` = ?
): array

La función cubrid_schema() se utiliza para recuperar información de un esquema desde la base de datos. Para recuperar la información de una clase particular, debe definirse `class_name`, para recuperar la información sobre un atributo particular (solo utilizable con `CUBRID_SCH_ATTR_PRIVILEGE`), debe definirse `attr_name`.

El resultado de la función cubrid_schema() se devuelve en forma de un array de 2 dimensiones (columna (array asociativo) * filas (array numérico)). Las tablas siguientes muestran los tipos de un esquema así como la estructura de una columna del array resultante, según el tipo de esquema solicitado.

Composición del resultado para cada tipo
Esquema | Número de columna | Nombre de la columna | Valor
--- | --- | --- | ---
CUBRID_SCH_CLASS | 1 | NAME |
| 2 | TYPE | 0:system class 1:vclass 2:class
CUBRID_SCH_VCLASS | 1 | NAME |
| 2 | TYPE | 1:vclass
CUBRID_SCH_QUERY_SPEC | 1 | QUERY_SPEC |
CUBRID_SCH_ATTRIBUTE / CUBRID_SCH_CLASS_ATTRIBUTE | 1 | ATTR_NAME |
| 2 | DOMAIN |
| 3 | SCALE |
| 4 | PRECISION |
| 5 | INDEXED | 1:indexed
| 6 | NOT NULL | 1:not null
| 7 | SHARED | 1:shared
| 8 | UNIQUE | 1:unique
| 9 | DEFAULT |
| 10 | ATTR_ORDER | base:1
| 11 | CLASS_NAME |
| 12 | SOURCE_CLASS |
| 13 | IS_KEY | 1:key
CUBRID_SCH_METHOD / CUBRID_SCH_CLASS_METHOD | 1 | NAME |
| 2 | RET_DOMAIN |
| 3 | ARG_DOMAIN |
CUBRID_SCH_METHOD_FILE | 1 | METHOD_FILE |
CUBRID_SCH_SUPERCLASS / CUBRID_SCH_DIRECT_SUPER_CLASS / CUBRID_SCH_SUBCLASS | 1 | CLASS_NAME |
| 2 | TYPE | 0:system class 1:vclass 2:class
CUBRID_SCH_CONSTRAINT | 1 | TYPE | 0:unique 1:index 2:reverse unique 3:reverse index
| 2 | NAME |
| 3 | ATTR_NAME |
| 4 | NUM_PAGES |
| 5 | NUM_KEYS |
| 6 | PRIMARY_KEY | 1:primary key
| 7 | KEY_ORDER | base:1
CUBRID_SCH_TRIGGER | 1 | NAME |
| 2 | STATUS |
| 3 | EVENT |
| 4 | TARGET_CLASS |
| 5 | TARGET_ATTR |
| 6 | ACTION_TIME |
| 7 | ACTION |
| 8 | PRIORITY |
| 9 | CONDITION_TIME |
| 10 | CONDITION |
CUBRID_SCH_CLASS_PRIVILEGE / CUBRID_SCH_ATTR_PRIVILEGE | 1 | CLASS_NAME / ATTR_NAME |
| 2 | PRIVILEGE |
| 3 | GRANTABLE |
CUBRID_SCH_PRIMARY_KEY | 1 | CLASS_NAME |
| 2 | ATTR_NAME |
| 3 | KEY_SEQ | base:1
| 4 | KEY_NAME |
CUBRID_SCH_IMPORTED_KEYS / CUBRID_SCH_EXPORTED_KEYS / CUBRID_SCH_CROSS_REFERENCE | 1 | PKTABLE_NAME |
| 2 | PKCOLUMN_NAME |
| 3 | FKTABLE_NAME | base:1
| 4 | FKCOLUMN_NAME |
| 5 | KEY_SEQ | base:1
| 6 | UPDATE_ACTION | 0:cascade 1:restrict 2:no action 3:set null
| 7 | DELETE_ACTION | 0:cascade 1:restrict 2:no action 3:set null
| 8 | FK_NAME |
| 9 | PK_NAME |

### Parámetros

`conn_identifier`
  Identificador de conexión.
`schema_type`
  Datos del esquema a recuperar.
`class_name`
  Clase para la cual se desea conocer el esquema.
`attr_name`
  Atributo para el cual se desea conocer el esquema.

### Valores devueltos

Un array que contiene la información sobre el esquema en caso de éxito, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.1 | Modificación del valor devuelto: cuando la función falla, el valor devuelto es ahora `false` en lugar de -1.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_schema()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    printf("\n--- Primary Key ---\n");
    $pk = cubrid_schema($conn, CUBRID_SCH_PRIMARY_KEY, "game");
    var_dump($pk);

    printf("\n--- Foreign Keys ---\n");
    $fk = cubrid_schema($conn, CUBRID_SCH_IMPORTED_KEYS, "game");
    var_dump($fk);

    printf("\n--- Column Attribute ---\n");
    $attr = cubrid_schema($conn, CUBRID_SCH_ATTRIBUTE, "stadium", "area");
    var_dump($attr);

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    --- Primary Key ---
    array(3) {
      [0]=>
      array(4) {
        ["CLASS_NAME"]=>
        string(4) "game"
        ["ATTR_NAME"]=>
        string(12) "athlete_code"
        ["KEY_SEQ"]=>
        string(1) "3"
        ["KEY_NAME"]=>
        string(41) "pk_game_host_year_event_code_athlete_code"
      }
      [1]=>
      array(4) {
        ["CLASS_NAME"]=>
        string(4) "game"
        ["ATTR_NAME"]=>
        string(10) "event_code"
        ["KEY_SEQ"]=>
        string(1) "2"
        ["KEY_NAME"]=>
        string(41) "pk_game_host_year_event_code_athlete_code"
      }
      [2]=>
      array(4) {
        ["CLASS_NAME"]=>
        string(4) "game"
        ["ATTR_NAME"]=>
        string(9) "host_year"
        ["KEY_SEQ"]=>
        string(1) "1"
        ["KEY_NAME"]=>
        string(41) "pk_game_host_year_event_code_athlete_code"
      }
    }

    --- Foreign Keys ---
    array(2) {
      [0]=>
      array(9) {
        ["PKTABLE_NAME"]=>
        string(7) "athlete"
        ["PKCOLUMN_NAME"]=>
        string(4) "code"
        ["FKTABLE_NAME"]=>
        string(4) "game"
        ["FKCOLUMN_NAME"]=>
        string(12) "athlete_code"
        ["KEY_SEQ"]=>
        string(1) "1"
        ["UPDATE_RULE"]=>
        string(1) "1"
        ["DELETE_RULE"]=>
        string(1) "1"
        ["FK_NAME"]=>
        string(20) "fk_game_athlete_code"
        ["PK_NAME"]=>
        string(15) "pk_athlete_code"
      }
      [1]=>
      array(9) {
        ["PKTABLE_NAME"]=>
        string(5) "event"
        ["PKCOLUMN_NAME"]=>
        string(4) "code"
        ["FKTABLE_NAME"]=>
        string(4) "game"
        ["FKCOLUMN_NAME"]=>
        string(10) "event_code"
        ["KEY_SEQ"]=>
        string(1) "1"
        ["UPDATE_RULE"]=>
        string(1) "1"
        ["DELETE_RULE"]=>
        string(1) "1"
        ["FK_NAME"]=>
        string(18) "fk_game_event_code"
        ["PK_NAME"]=>
        string(13) "pk_event_code"
      }
    }

    --- Column Attribute ---
    array(1) {
      [0]=>
      array(13) {
        ["ATTR_NAME"]=>
        string(4) "area"
        ["DOMAIN"]=>
        string(1) "7"
        ["SCALE"]=>
        string(1) "2"
        ["PRECISION"]=>
        string(2) "10"
        ["INDEXED"]=>
        string(1) "0"
        ["NON_NULL"]=>
        string(1) "0"
        ["SHARED"]=>
        string(1) "0"
        ["UNIQUE"]=>
        string(1) "0"
        ["DEFAULT"]=>
        NULL
        ["ATTR_ORDER"]=>
        string(1) "4"
        ["CLASS_NAME"]=>
        string(7) "stadium"
        ["SOURCE_CLASS"]=>
        string(7) "stadium"
        ["IS_KEY"]=>
        string(1) "0"
      }
    }

# cubrid_seq_drop

(PECL CUBRID >= 8.3.0)

cubrid_seq_drop — Elimina un elemento de una secuencia

### Descripción

function cubrid_seq_drop(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
int `$index`
): bool

La función cubrid_seq_drop() se utiliza para eliminar un elemento de la base de datos basándose en la secuencia de tipos de atributos proporcionada.

### Parámetros

`conn_identifier`
  Identificador de conexión.
`oid`
  OID de la instancia a utilizar.
`attr_name`
  Nombre del atributo desde el cual debe eliminarse el elemento.
`index`
  Índice del elemento a eliminar (comenzando en 1).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_seq_drop()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c sequence(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_seq_drop($conn, $oid, "c", 4);

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    array(4) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
    }
    array(3) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
    }

### Ver también

- cubrid_seq_insert() - Inserta un elemento en una secuencia
- cubrid_seq_put() - Actualiza el valor de un elemento de una secuencia

# cubrid_seq_insert

(PECL CUBRID >= 8.3.0)

cubrid_seq_insert — Inserta un elemento en una secuencia

### Descripción

function cubrid_seq_insert(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
int `$index`,
string `$seq_element`
): bool

La función cubrid_seq_insert() se utiliza para insertar un elemento en una secuencia de tipos de atributos.

### Parámetros

`conn_identifier`
  Identificador de conexión.
`oid`
  OID de la instancia a utilizar.
`attr_name`
  Nombre del atributo a insertar.
`index`
  Posición del elemento para su inserción (comenzando en 1).
`seq_element`
  Contenido del elemento a insertar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_seq_insert()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c sequence(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_seq_insert($conn, $oid, "c", 5, "44");

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    array(4) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
    }
    array(5) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
      [4]=>
      string(2) "44"
    }

### Ver también

- cubrid_seq_drop() - Elimina un elemento de una secuencia
- cubrid_seq_put() - Actualiza el valor de un elemento de una secuencia

# cubrid_seq_put

(PECL CUBRID >= 8.3.0)

cubrid_seq_put — Actualiza el valor de un elemento de una secuencia

### Descripción

function cubrid_seq_put(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
int `$index`,
string `$seq_element`
): bool

La función cubrid_seq_put() se utiliza para actualizar el contenido de un elemento en una secuencia de tipos de atributos.

### Parámetros

`conn_identifier`
  Identificador de conexión.
`oid`
  OID de la instancia a utilizar.
`attr_name`
  Nombre del atributo a utilizar.
`index`
  Índice (comenzando en 1) del elemento a actualizar.
`seq_element`
  Nuevo contenido a colocar en el elemento.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_seq_put()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c sequence(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_seq_put($conn, $oid, "c", 1, "111");

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    array(4) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
    }
    array(4) {
      [0]=>
      string(3) "111"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
    }

### Ver también

- cubrid_seq_drop() - Elimina un elemento de una secuencia
- cubrid_seq_insert() - Inserta un elemento en una secuencia

# cubrid_set_add

(PECL CUBRID >= 8.3.0)

cubrid_set_add — Inserta un único elemento para definir el tipo de una columna

### Descripción

function cubrid_set_add(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
string `$set_element`
): bool

La función cubrid_set_add() se utiliza para insertar un único elemento en un conjunto de tipos de atributos.

### Parámetros

`conn_identifier`
  Identificador de conexión.
`oid`
  OID de la instancia a utilizar.
`attr_name`
  Nombre del atributo en el cual el nuevo elemento será insertado.
`set_element`
  Contenido del elemento a insertar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_set_add()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_set_add($conn, $oid, "b", "4");

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    array(4) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
      [3]=>
      string(1) "4"
    }

### Ver también

- cubrid_seq_drop() - Elimina un elemento de una secuencia

# cubrid_set_autocommit

(PECL CUBRID >= 8.4.0)

cubrid_set_autocommit — Define el modo auto-commit para la conexión

### Descripción

function cubrid_set_autocommit(resource `$conn_identifier`, bool `$mode`): bool

La función cubrid_set_autocommit() se utiliza para definir el modo auto-commit para la conexión a la base de datos CUBRID.

En CUBRID PHP, el modo auto-commit está desactivado por omisión para la gestión de transacciones. Cuando el modo auto-commit pasa de Off a On, todos los trabajos pendientes son automáticamente validados.

### Parámetros

`conn_identifier`
  Identificador de conexión.
`mode`
  El modo auto-commit. Las constantes siguientes pueden ser utilizadas:
  - `CUBRID_AUTOCOMMIT_FALSE`
  - `CUBRID_AUTOCOMMIT_TRUE`

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- cubrid_get_autocommit() - Recupera el modo auto-commit de la conexión
- cubrid_commit() - Consigna una transacción

# cubrid_set_db_parameter

(PECL CUBRID >= 8.4.0)

cubrid_set_db_parameter — Define los parámetros de la base de datos CUBRID

### Descripción

function cubrid_set_db_parameter(resource `$conn_identifier`, int `$param_type`, int `$param_value`): bool

La función cubrid_set_db_parameter() se utiliza para definir los parámetros de la base de datos CUBRID. Puede definir los siguientes parámetros de la base de datos CUBRID:

- `PARAM_ISOLATION_LEVEL`
- `PARAM_LOCK_TIMEOUT`

> Nota: El modo auto-commit puede ser definido utilizando la función cubrid_set_autocommit().

### Parámetros

`conn_identifier`
  La conexión CUBRID. Si el identificador de conexión no es especificado, se utilizará el último enlace abierto por la función cubrid_connect().
`param_type`
  Tipo de parámetro de la base de datos.
`param_value`
  Nivel de aislamiento (1-6) o el valor del tiempo de espera (en segundos).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_get_db_parameter()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $params = cubrid_get_db_parameter($conn);
    var_dump($params);

    cubrid_set_autocommit($conn, CUBRID_AUTOCOMMIT_TRUE);
    cubrid_set_db_parameter($conn, CUBRID_PARAM_ISOLATION_LEVEL, 2);

    $params_new = cubrid_get_db_parameter($conn);
    var_dump($params_new);

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    array(4) {
      ["PARAM_ISOLATION_LEVEL"]=>
      int(3)
      ["PARAM_LOCK_TIMEOUT"]=>
      int(-1)
      ["PARAM_MAX_STRING_LENGTH"]=>
      int(1073741823)
      ["PARAM_AUTO_COMMIT"]=>
      int(0)
    }
    array(4) {
      ["PARAM_ISOLATION_LEVEL"]=>
      int(2)
      ["PARAM_LOCK_TIMEOUT"]=>
      int(-1)
      ["PARAM_MAX_STRING_LENGTH"]=>
      int(1073741823)
      ["PARAM_AUTO_COMMIT"]=>
      int(1)
    }

### Ver también

- cubrid_get_db_parameter() - Devuelve los parámetros de la base de datos CUBRID
- cubrid_set_autocommit() - Define el modo auto-commit para la conexión

# cubrid_set_drop

(PECL CUBRID >= 8.3.0)

cubrid_set_drop — Elimina un elemento

### Descripción

function cubrid_set_drop(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
string `$set_element`
): bool

La función cubrid_set_drop() se utiliza para eliminar un elemento de un atributo dado de la base de datos.

### Parámetros

`conn_identifier`
  Identificador de conexión.
`oid`
  OID de la instancia a utilizar.
`attr_name`
  Nombre del atributo desde el cual se eliminará el elemento.
`set_element`
  Contenido del elemento a eliminar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_set_drop()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_set_drop($conn, $oid, "b", "1");

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    array(2) {
      [0]=>
      string(1) "2"
      [1]=>
      string(1) "3"
    }

### Ver también

- cubrid_set_add() - Inserta un único elemento para definir el tipo de una columna

# cubrid_set_query_timeout

(PECL CUBRID >= 8.4.1)

cubrid_set_query_timeout — Define el tiempo máximo de ejecución de una consulta

### Descripción

function cubrid_set_query_timeout(resource `$req_identifier`, int `$timeout`): bool

La función cubrid_set_query_timeout() se utiliza para definir el tiempo máximo de ejecución de una consulta.

### Parámetros

`req_identifier`
  Identificador de consulta.
`timeout`
  Tiempo máximo, en milisegundos.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- cubrid_get_query_timeout() - Obtener el valor del tiempo de espera de consulta de la petición

# cubrid_version

(PECL CUBRID >= 8.3.0)

cubrid_version — Obtener la versión del módulo de PHP de CUBRID

### Descripción

function cubrid_version(): string

La función cubrid_version() se usa para obtener la versión del módulo de PHP de CUBRID.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Información de la versión (p.ej. "8.3.1.0001").

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_version()

    <?php
    printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33088, "demodb", "dba");

    if (!$conn) {
        die('Error de conexión ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Server Info:", $server_info);
    printf("%-30s %s\n", "Client Info:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "CUBRID Charset:", $charset);

    cubrid_disconnect($conn);

    ?>

El ejemplo anterior mostrará:

    CUBRID PHP Version:            9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Server Info:                   9.1.0.0212
    Client Info:                   9.1.0

    CUBRID Charset:                iso8859-1

### Ver también

- cubrid_error_code() - Obtener el código de error de la llamada a una función más reciente
- cubrid_error_code_facility() - Obtener el código de error del dispositivo

## Tabla de contenidos

- cubrid_bind — Vincular variables para una sentencia preparada como parámetros
- cubrid_close_prepare — Cerrar el gestor de solicitud
- cubrid_close_request — Cerrar el gestor de solicitud
- cubrid_col_get — Recupera el contenido de los elementos de un tipo de colección utilizando el OID
- cubrid_col_size — Obtener el número de elementos de la columna del tipo de colección usando OID
- cubrid_column_names — Obtener los nombres de las columnas del resultado
- cubrid_column_types — Obtener los tipos de columnas del resultado
- cubrid_commit — Consigna una transacción
- cubrid_connect — Abrir una conexión al servidor CUBRID
- cubrid_connect_with_url — Establecer el entorno para la conexión al servidor de CUBRID
- cubrid_current_oid — Obtener el OID de la posición del cursor actual
- cubrid_disconnect — Cerrar una conexión a una base de datos
- cubrid_drop — Borrar una instancia usando OID
- cubrid_error_code — Obtener el código de error de la llamada a una función más reciente
- cubrid_error_code_facility — Obtener el código de error del dispositivo
- cubrid_error_msg — Obtener el último mensaje de error de la llamada a la función más reciente
- cubrid_execute — Ejecutar una sentencia SQL preparada
- cubrid_fetch — Obtener la siguiente fila de un conjunto de resultados
- cubrid_free_result — Liberar la memoria ocupada por los datos del resultado
- cubrid_get — Obtener una columna usando OID
- cubrid_get_autocommit — Recupera el modo auto-commit de la conexión
- cubrid_get_charset — Devolver el conjunto de caracteres de la conexión CUBRID actual
- cubrid_get_class_name — Obtener el nombre de la clase usando OID
- cubrid_get_client_info — Devolver la versión de la biblioteca cliente
- cubrid_get_db_parameter — Devuelve los parámetros de la base de datos CUBRID
- cubrid_get_query_timeout — Obtener el valor del tiempo de espera de consulta de la petición
- cubrid_get_server_info — Devolver la versión del servidor CUBRID
- cubrid_insert_id — Devuelve el ID generado por la última columna actualizada AUTO_INCREMENT
- cubrid_is_instance — Comprobar si existe la instancia apuntada por OID
- cubrid_lob_close — Cerrar información BLOB/CLOB
- cubrid_lob_export — Exporta datos BLOB/CLOB a un fichero
- cubrid_lob_get — Recupera los datos BLOB/CLOB
- cubrid_lob_send — Lee los datos BLOB/CLOB y los envía al navegador
- cubrid_lob_size — Recupera el tamaño de los datos BLOB/CLOB
- cubrid_lob2_bind — Asocia un objeto LOB o una cadena de caracteres a un objeto LOB como argumento de una consulta preparada
- cubrid_lob2_close — Cierra un objeto LOB
- cubrid_lob2_export — Exporta un objeto LOB a un fichero
- cubrid_lob2_import — Importa datos BLOB/CLOB desde un fichero
- cubrid_lob2_new — Crea un nuevo objeto LOB
- cubrid_lob2_read — Lee datos BLOB/CLOB
- cubrid_lob2_seek — Desplaza el cursor de un objeto LOB
- cubrid_lob2_seek64 — Desplaza el cursor de un objeto LOB
- cubrid_lob2_size — Obtiene el tamaño de un objeto LOB
- cubrid_lob2_size64 — Recupera el tamaño de un objeto LOB
- cubrid_lob2_tell — Recupera la posición del cursor en un objeto LOB
- cubrid_lob2_tell64 — Recupera la posición del cursor en el objeto LOB
- cubrid_lob2_write — Escribe en un objeto LOB
- cubrid_lock_read — Coloca un bloqueo de lectura sobre el OID proporcionado
- cubrid_lock_write — Coloca un bloqueo de escritura en el OID proporcionado
- cubrid_move_cursor — Desplaza el cursor en el resultado
- cubrid_next_result — Recupera el resultado de la siguiente consulta durante la ejecución de múltiples consultas SQL
- cubrid_num_cols — Obtiene el número de columnas del conjunto de resultados
- cubrid_num_rows — Obtiene el número de filas de un conjunto de resultados
- cubrid_pconnect — Establece una conexión persistente con un servidor CUBRID
- cubrid_pconnect_with_url — Establece una conexión persistente con un servidor CUBRID
- cubrid_prepare — Prepara una consulta SQL para su ejecución
- cubrid_put — Actualiza una columna según su OID
- cubrid_rollback — Anula una transacción
- cubrid_schema — Recupera información sobre un esquema
- cubrid_seq_drop — Elimina un elemento de una secuencia
- cubrid_seq_insert — Inserta un elemento en una secuencia
- cubrid_seq_put — Actualiza el valor de un elemento de una secuencia
- cubrid_set_add — Inserta un único elemento para definir el tipo de una columna
- cubrid_set_autocommit — Define el modo auto-commit para la conexión
- cubrid_set_db_parameter — Define los parámetros de la base de datos CUBRID
- cubrid_set_drop — Elimina un elemento
- cubrid_set_query_timeout — Define el tiempo máximo de ejecución de una consulta
- cubrid_version — Obtener la versión del módulo de PHP de CUBRID

# Funciones de compatibilidad CUBRID MySQL

# cubrid_affected_rows

(PECL CUBRID >= 8.3.0)

cubrid_affected_rows — Devolver el número de filas afectadas por la última sentencia SQL

### Descripción

function cubrid_affected_rows(resource `$conn_identifier` = ?): int
function cubrid_affected_rows(resource `$req_identifier` = ?): int

La función cubrid_affected_rows() se usa para obtener el número de filas afectadas por la última sentencia SQL (INSERT, DELETE, UPDATE).

### Parámetros

`conn_identifier`
  La conexión CUBRID. Si no se especifica el identificador de conexión, se asume el último enlace abierto por cubrid_connect().
`req_identifier`
  Identificador de petición. Podría ser devuelto desde cubrid_prepare() o cubrid_execute(). Si el identificador de petición no se especifica, se asume el último identificador solicitado por cubrid_prepare() o cubrid_execute().

### Valores devueltos

El número de filas afectadas por la sentencia SQL, cuando el proceso tiene éxito.

-1, cuando la sentencia SQL no es INSERT, DELETE o UPDATE.

`false`, cuando el identificador de solicitud no está especificado, y no existe una última petición.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_affected_rows()

    <?php
    $conn = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
    cubrid_execute($conn, "DROP TABLE IF EXISTS cubrid_test");
    cubrid_execute($conn, "CREATE TABLE cubrid_test (d varchar)");
    $sql_stmt = "INSERT INTO cubrid_test(d) VALUES('php-test')";
    $req = cubrid_prepare($conn, $sql_stmt);

    for ($i = 0; $i < 10; $i++) {
        cubrid_execute($req);
    }
    cubrid_commit($conn);

    $req = cubrid_execute($conn, "DELETE FROM cubrid_test WHERE d='php-test'", CUBRID_ASYNC);
    var_dump(cubrid_affected_rows());
    var_dump(cubrid_affected_rows($conn));
    var_dump(cubrid_affected_rows($req));

    cubrid_disconnect($conn);

    print "¡Hecho!";
    ?>

El ejemplo anterior mostrará:

    int(10)
    int(10)
    int(10)
    done!

### Ver también

- cubrid_execute() - Ejecutar una sentencia SQL preparada

# cubrid_client_encoding

(PECL CUBRID >= 8.3.1)

cubrid_client_encoding — Devuelve el actual conjunto de caracteres de la conexión a CUBRID

### Descripción

function cubrid_client_encoding(resource `$conn_identifier` = ?): string

Esta función devuelve el actual conjunto de caracteres de conexión a CUBRID y es similar a la función CUBRID cubrid_get_charset().

### Parámetros

`conn_identifier`
  Conexión CUBRID. Si no se especifica el identificador de conexión, se asumirá el último enlace abierto por cubrid_connect().

### Valores devueltos

Cadena que representa el conjunto de caracteres de la conexión a CUBRID; en caso de éxito.

`false` en caso de falla.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_client_encoding()

    <?php

    $con = cubrid_connect("localhost", 33000, "demodb");
    if (!$con)
    {
        die('No se pudo conectar.');
    }

    printf("Conjunto actual de caracteres de CUBRID: %s\n", cubrid_client_encoding($con));

    ?>

El ejemplo anterior mostrará:

    CUBRID current charset: iso8859-1

### Ver también

- cubrid_get_charset() - Devolver el conjunto de caracteres de la conexión CUBRID actual

# cubrid_close

(PECL CUBRID >= 8.3.1)

cubrid_close — Cerrar la conexión de CUBRID

### Descripción

function cubrid_close(resource `$conn_identifier` = ?): bool

La función cubrid_close() termina la transacción en proceso actual, cierra el gestor de conexión y se desconecta del servidor. Si existe cualquier gestor de petición que no se haya cerrado todavía em este punto, éste se cerrará. Es similar a la función de CUBRID cubrid_disconnect().

### Parámetros

`conn_identifier`
  El identificador de conexión de CUBRID. Si no se especifica el identificador de conexión, se asume la última conexión abierta por cubrid_connect().

### Valores devueltos

`true`, cuando el proceso es satisfactorio.

`false`, cuando el proceso es insatisfactorio.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_close()

    <?php
    $con = cubrid_connect ("localhost", 33000, "demodb");
    if ($con) {
       echo "conectado satisfactoriamente";
       $req = cubrid_execute ( $con, "insert into person values(1,'James')");
       if ($req) {
          cubrid_close_request ($req);
          cubrid_commit ($con);
       } else {
          cubrid_rollback ($con);
       }
       cubrid_close ($con);
    }
    ?>

### Ver también

- cubrid_disconnect() - Cerrar una conexión a una base de datos
- cubrid_connect() - Abrir una conexión al servidor CUBRID
- cubrid_connect_with_url() - Establecer el entorno para la conexión al servidor de CUBRID

# cubrid_data_seek

(PECL CUBRID >= 8.3.0)

cubrid_data_seek — Mueve el puntero interno de la fila del resultado CUBRID

### Descripción

function cubrid_data_seek(resource `$result`, int `$row_number`): bool

Esta función desplaza el puntero interno de las filas del resultado CUBRID (asociado con el identificador especificado) para apuntar al número de fila especificada. Hay funciones, como cubrid_fetch_assoc(), que utiliza el valor actualmente almacenado del número de fila.

### Parámetros

`result`
  El resultado.
`row_number`
  Éste es el número de fila deseado del puntero del nuevo resultado.

### Valores devueltos

Devuelve `true` en caso de éxito o `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_data_seek()

    <?php
    $conn = cubrid_connect("127.0.0.1", 33000, "demodb");

    $req = cubrid_execute($conn, "SELECT * FROM code");
    cubrid_data_seek($req, 0);

    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_data_seek($req, 2);
    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_data_seek($req, 4);
    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    array(2) {
      [0]=>
      string(1) "X"
      [1]=>
      string(5) "Mixed"
    }
    array(2) {
      [0]=>
      string(1) "M"
      [1]=>
      string(3) "Man"
    }
    array(2) {
      [0]=>
      string(1) "S"
      [1]=>
      string(6) "Silver"
    }

# cubrid_db_name

(PECL CUBRID >= 8.3.1)

cubrid_db_name — Obtener el nombre de la base de datos desde los resultados de cubrid_list_dbs

### Descripción

function cubrid_db_name(array `$result`, int `$index`): string

Recupera el nombre de la base de datos desde una llamada a cubrid_list_dbs().

### Parámetros

`result`
  El puntero resultado desde un llamada a cubrid_list_dbs().
`index`
  El índice dentro del conjunto resultado.

### Valores devueltos

Devuelve el nombre de la base de datos en caso de éxito, y `false` en caso de fallo. Si se devuelve `false`, use cubrid_error() para determinar la naturaleza del error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_db_name()

    <?php
    error_reporting(E_ALL);

    $conn = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
    $db_list = cubrid_list_dbs($conn);

    $i = 0;
    $cnt = count($db_list);
    while ($i < $cnt) {
        echo cubrid_db_name($db_list, $i) . "\n";
        $i++;
    }
    ?>

El ejemplo anterior mostrará:

    demodb

### Ver también

- cubrid_list_dbs() - Devuelve una matriz con la lista de todas las bases de datos Cubrid existentes

# cubrid_errno

(PECL CUBRID >= 8.3.1)

cubrid_errno — Devuelve el valor numérico del mensaje de error de la operación de CUBRID previa

### Descripción

function cubrid_errno(resource `$conn_identifier` = ?): int

Devuelve el número de error de la última función CUBRID.

La función cubrid_errno() se usa para obtener el código de error que ocurrió durante la ejecución de la API. Normalmente, obtiene el error cuando la API devuelve false como su valor de retorno.

### Parámetros

`conn_identifier`
  El identificador de conexión de CUBRID. Si el identificador de conexión no se especifica, se asume la última conexión abierta por cubrid_connect().

### Valores devueltos

Devuelve el número de error de la última función CUBRID, o `0` (cero) si no ocurrio ningún error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_errno()

    <?php
    $con = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
    $req = cubrid_execute($con, "select id, name from person");
    if ($req) {
        while (list ($id, $name) = cubrid_fetch($req))
        echo $id, $name;
    } else {
        echo "Código de error: ", cubrid_errno($con);
        echo "Mensaje de error: ", cubrid_error($con);
    }
    ?>

El ejemplo anterior mostrará:

    Código de error: -493 Mensaje de error:: Syntax: Unknown class "person". select id, [name] from person

### Ver también

- cubrid_error() - Se usa para obtener el mensaje de error
- cubrid_error_code() - Obtener el código de error de la llamada a una función más reciente
- cubrid_error_msg() - Obtener el último mensaje de error de la llamada a la función más reciente

# cubrid_error

(PECL CUBRID >= 8.3.1)

cubrid_error — Se usa para obtener el mensaje de error

### Descripción

function cubrid_error(resource `$connection` = ?): string

La función cubrid_error() se usa para obtener el mensaje de error que ocurrió durante el uso de la API CUBRID. Normalmente, obtiene el mensaje de error cuando la API devuelve false como su valor de retorno.

### Parámetros

`connection`
  La conexión CUBRID

### Valores devueltos

Mensaje de error que ocurrió.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_error()

    <?php
    $con = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
    $req = cubrid_execute($con, "select id, name from person");
    if ($req) {
        while (list ($id, $name) = cubrid_fetch($req))
        echo $id, $name;
    } else {
        echo "Código de error: ", cubrid_errno($con);
        echo "Mensaje de error: ", cubrid_error($con);
    }
    ?>

El ejemplo anterior mostrará:

    Código de error: -493 Mensaje de error: Syntax: Unknown class "person". select id, [name] from person

### Ver también

- cubrid_errno() - Devuelve el valor numérico del mensaje de error de la operación de CUBRID previa
- cubrid_error_code() - Obtener el código de error de la llamada a una función más reciente
- cubrid_error_msg() - Obtener el último mensaje de error de la llamada a la función más reciente

# cubrid_fetch_array

(PECL CUBRID >=8.3.0)

cubrid_fetch_array — Recupera una línea de resultado en forma de array asociativo, array numérico, o ambos

### Descripción

function cubrid_fetch_array(resource `$result`, int `$type` = CUBRID_BOTH): array

La función cubrid_fetch_array() se utiliza para recuperar una sola línea desde el resultado de la consulta y devuelve un array. El cursor se mueve automáticamente a la siguiente línea una vez que el resultado ha sido recuperado.

### Parámetros

`result`
  El parámetro `Result` proviene de una llamada a la función cubrid_execute()
`type`
  Tipo del array recuperado: CUBRID_NUM, CUBRID_ASSOC, CUBRID_BOTH. Si se necesita utilizar un objeto LOB, se puede utilizar CUBRID_LOB.

### Valores devueltos

Devuelve un array de strings correspondiente a la línea recuperada, cuando la operación tiene éxito.

`false` cuando no hay más líneas, NULL cuando ocurre un error.

El tipo del array devuelto depende del tipo que se haya definido. Utilizando CUBRID_BOTH (valor por defecto), se recuperará un array que contiene tanto índices asociativos como numéricos; se puede elegir explícitamente este tipo a través del argumento `type`. La variable `type` puede ser definida a uno de los siguientes valores:

- CUBRID_NUM: Array numérico (comenzando en el índice 0)
- CUBRID_ASSOC: Array asociativo
- CUBRID_BOTH: Array asociativo y numérico (valor por defecto)

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_fetch_array()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");

    printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
    while ($row = cubrid_fetch_array($req, CUBRID_NUM)) {
        printf("%-40s %-10s %-6s %-20s\n", $row[0], $row[1], $row[2], $row[3]);
    }

    // Si se desea utilizar un objeto LOB, se puede utilizar
    // cubrid_fetch_array($req, CUBRID_NUM | CUBRID_LOB)

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    name                                     area       seats  address
    Panathinaiko Stadium                     86300.00   50000  Athens, Greece
    Olympic Stadium                          54700.00   13000  Athens, Greece
    Olympic Indoor Hall                      34100.00   18800  Athens, Greece
    Olympic Hall                             52400.00   21000  Athens, Greece
    Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
    Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
    Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
    Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
    Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

### Ver también

- cubrid_execute() - Ejecutar una sentencia SQL preparada
- cubrid_fetch() - Obtener la siguiente fila de un conjunto de resultados
- cubrid_fetch_row() - Devuelve un array numérico con los valores de la fila actual
- cubrid_fetch_assoc() - Devuelve un array asociativo correspondiente a la fila recuperada
- cubrid_fetch_object() - Recupera la siguiente línea y la devuelve como un objeto

# cubrid_fetch_assoc

(PECL CUBRID >= 8.3.0)

cubrid_fetch_assoc — Devuelve un array asociativo correspondiente a la fila recuperada

### Descripción

function cubrid_fetch_assoc(resource `$result`, int `$type` = ?): array

Esta función devuelve un array asociativo correspondiente a la fila recuperada, luego, mueve el puntero de datos interno a la siguiente fila. La función devuelve `false` si no hay más resultados disponibles.

### Parámetros

`result`
  El parámetro `result` proviene de una llamada a la función cubrid_execute()
`type`
  El tipo solo puede ser CUBRID_LOB; este parámetro será utilizado únicamente cuando se necesite utilizar un objeto LOB.

### Valores devueltos

Un array asociativo, en caso de éxito.

`false` cuando no hay más filas, NULL si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_fetch_assoc()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");

    printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
    while ($row = cubrid_fetch_assoc($req)) {
        printf("%-40s %-10s %-6s %-20s\n",
            $row["name"], $row["area"], $row["seats"], $row["address"]);
    }

    // Si se desea utilizar un objeto LOB, se puede utilizar
    // cubrid_fetch_assoc($req, CUBRID_LOB)

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    name                                     area       seats  address
    Panathinaiko Stadium                     86300.00   50000  Athens, Greece
    Olympic Stadium                          54700.00   13000  Athens, Greece
    Olympic Indoor Hall                      34100.00   18800  Athens, Greece
    Olympic Hall                             52400.00   21000  Athens, Greece
    Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
    Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
    Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
    Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
    Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

### Ver también

- cubrid_execute() - Ejecutar una sentencia SQL preparada
- cubrid_fetch() - Obtener la siguiente fila de un conjunto de resultados
- cubrid_fetch_row() - Devuelve un array numérico con los valores de la fila actual
- cubrid_fetch_array() - Recupera una línea de resultado en forma de array asociativo, array numérico, o ambos
- cubrid_fetch_object() - Recupera la siguiente línea y la devuelve como un objeto

# cubrid_fetch_field

(PECL CUBRID >= 8.3.1)

cubrid_fetch_field — Devuelve un objeto con ciertas propiedades

### Descripción

function cubrid_fetch_field(resource `$result`, int `$field_offset` = 0): object

Esta función devuelve un objeto con ciertas propiedades de la columna especificada. Las propiedades del objeto son:

`name`
  nombre de la columna
`table`
  nombre de la tabla a la que pertenece la columna
`def`
  valor predeterminado de la columna
`max_length`
  longitud máxima de la columna
`not_null`
  1 si la columna no puede ser NULL
`primary_key`
  1 si la columna es una clave primaria
`unique_key`
  1 si la columna es clave única
`multiple_key`
  1 si la columna no es clave única
`numeri`
  1 si la columna es numérica
`blob`
  1 si la columna es un BLOB
`type`
  el tipo de la columna
`unsigned`
  1 si la columna no tiene signo
`zerofill`
  1 si la columna se rellena con ceros

### Parámetros

`result`
  `result` proviene de una llamada a la función cubrid_execute()
`field_offset`
  El índice del campo numérico. Si el índice del campo no se especifica, se recupera el siguiente campo (el que aún no ha sido recuperado por esta función). `field_offset` comienza en 0.

### Valores devueltos

Un objeto con ciertas propiedades de la columna especificada, cuando el proceso tuvo éxito.

`false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_fetch_field()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT event_code,athlete_code,nation_code,game_date FROM game WHERE host_year=1988 and event_code=20001;");

    var_dump(cubrid_fetch_row($req));

    cubrid_field_seek($req, 1);
    $field = cubrid_fetch_field($req);

    printf("\n--- Field Properties ---\n");
    printf("%-30s %s\n", "name:", $field->name);
    printf("%-30s %s\n", "table:", $field->table);
    printf("%-30s \"%s\"\n", "default value:", $field->def);
    printf("%-30s %d\n", "max length:", $field->max_length);
    printf("%-30s %d\n", "not null:", $field->not_null);
    printf("%-30s %d\n", "primary key:", $field->primary_key);
    printf("%-30s %d\n", "unique key:", $field->unique_key);
    printf("%-30s %d\n", "multiple key:", $field->multiple_key);
    printf("%-30s %d\n", "numeric:", $field->numeric);
    printf("%-30s %d\n", "blob:", $field->blob);
    printf("%-30s %s\n", "type:", $field->type);
    printf("%-30s %d\n", "unsigned:", $field->unsigned);
    printf("%-30s %d\n", "zerofill:", $field->zerofill);

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    array(4) {
      [0]=>
      string(5) "20001"
      [1]=>
      string(5) "16681"
      [2]=>
      string(3) "KOR"
      [3]=>
      string(9) "1988-9-30"
    }

    --- Field Properties ---
    name:                          athlete_code
    table:                         game
    default value:                 ""
    max length:                    0
    not null:                      1
    primary key:                   1
    unique key:                    1
    multiple key:                  0
    numeric:                       1
    blob:                          0
    type:                          integer
    unsigned:                      0
    zerofill:                      0

# cubrid_fetch_lengths

(PECL CUBRID >= 8.3.0)

cubrid_fetch_lengths — Devuelve una matriz con las longitudes de los valores de cada campo de la fila actual

### Descripción

function cubrid_fetch_lengths(resource `$result`): array

Esta función devuelve una matriz numérica con las longitudes de los valores de cada campo de la fila actual del conjunto de resultados o FALSE en caso de fallo.

> Nota: Si el tipo de información del campo es BLOB/CLOB, se debería tomar su longitud usando cubrid_lob_size().

### Parámetros

`result`
  `result` proviene de una llamada a la función cubrid_execute()

### Valores devueltos

Una matriz numérica, cuando el proceso tuvo éxito.

`false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_fetch_lengths()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $row = cubrid_fetch_row($result);
    print_r($row);

    $lens = cubrid_fetch_lengths($result);
    print_r($lens);

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    Array
    (
        [0] => 2004
        [1] => 20085
        [2] => 15118
        [3] => 30134
        [4] => AUS
        [5] => G
        [6] => 2004-8-20
    )
    Array
    (
        [0] => 4
        [1] => 5
        [2] => 5
        [3] => 5
        [4] => 3
        [5] => 1
        [6] => 10
    )

# cubrid_fetch_object

(PECL CUBRID >= 8.3.0)

cubrid_fetch_object — Recupera la siguiente línea y la devuelve como un objeto

### Descripción

function cubrid_fetch_object(
resource `$result`,
string `$class_name` = ?,
array `$params` = ?,
int `$type` = ?
): object

Esta función devuelve un objeto con los nombres de la columna del conjunto de resultados como propiedades. Los valores de estas propiedades se extraen de la línea actual del conjunto de resultados.

### Parámetros

`result`
  El parámetro `result` proviene de una llamada a la función cubrid_execute()
`class_name`
  El nombre de la clase a instanciar, definir las propiedades y devolver. Si no se especifica, se devuelve un objeto stdClass.
`params`
  Un array de parámetros opcionales a pasar al constructor de la clase `class_name`.
`type`
  El tipo solo puede ser CUBRID_LOB; este parámetro solo se utilizará cuando se necesite usar un objeto lob.

### Valores devueltos

Un objeto en caso de éxito.

`false` cuando no hay más líneas, NULL si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_fetch_object()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $res = cubrid_execute($conn, "SELECT * FROM code");

    var_dump(cubrid_fetch_object($res));

    // if you want to operate LOB object, you can use cubrid_fetch_object($res, CUBRID_LOB)

    class demodb_code {
        public $s_name = null;
        public $f_name = null;

        public function toString() {
            var_dump($this);
        }
    }

    var_dump(cubrid_fetch_object($res, "demodb_code"));

    // Si se desea utilizar un objeto LOB, se puede usar
    // cubrid_fetch_object($res, 'demodb_code_construct', array('s_name', 'f_name'), CUBRID_LOB)

    class demodb_code_construct extends demodb_code {
        public function __construct($s, $f) {
            $this->s_name = $s;
            $this->f_name = $f;
        }
    }

    var_dump(cubrid_fetch_object($res, 'demodb_code_construct', array('s_name', 'f_name')));

    // Si se desea utilizar un objeto LOB, se puede usar
    // cubrid_fetch_object($res, 'demodb_code_construct', array('s_name', 'f_name'), CUBRID_LOB)

    var_dump(cubrid_fetch_object($res));

    cubrid_close_request($res);
    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    object(stdClass)#1 (2) {
      ["s_name"]=>
      string(1) "X"
      ["f_name"]=>
      string(5) "Mixed"
    }
    object(demodb_code)#1 (2) {
      ["s_name"]=>
      string(1) "W"
      ["f_name"]=>
      string(5) "Woman"
    }
    object(demodb_code_construct)#1 (2) {
      ["s_name"]=>
      string(6) "s_name"
      ["f_name"]=>
      string(6) "f_name"
    }
    object(stdClass)#1 (2) {
      ["s_name"]=>
      string(1) "B"
      ["f_name"]=>
      string(6) "Bronze"
    }

### Ver también

- cubrid_execute() - Ejecutar una sentencia SQL preparada
- cubrid_fetch() - Obtener la siguiente fila de un conjunto de resultados
- cubrid_fetch_array() - Recupera una línea de resultado en forma de array asociativo, array numérico, o ambos
- cubrid_fetch_assoc() - Devuelve un array asociativo correspondiente a la fila recuperada
- cubrid_fetch_row() - Devuelve un array numérico con los valores de la fila actual

# cubrid_fetch_row

(PECL CUBRID >= 8.3.0)

cubrid_fetch_row — Devuelve un array numérico con los valores de la fila actual

### Descripción

function cubrid_fetch_row(resource `$result`, int `$type` = ?): array

Esta función devuelve un array numérico con los valores de la fila actual del conjunto de resultados, comenzando en 0 y desplaza el puntero interno de datos.

### Parámetros

`result`
  El argumento `result` proviene de una llamada a la función cubrid_execute()
`type`
  El tipo solo puede ser CUBRID_LOB; este argumento será utilizado únicamente cuando se necesite utilizar un objeto lob.

### Valores devueltos

Un array numérico en caso de éxito.

`false` cuando no hay más filas, NULL si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_fetch_row()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");

    printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
    while ($row = cubrid_fetch_row($req)) {
        printf("%-40s %-10s %-6s %-20s\n", $row[0], $row[1], $row[2], $row[3]);
    }

    // Si se desea utilizar un objeto lob, se puede utilizar
    // cubrid_fetch_row($req, CUBRID_LOB)

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    name                                     area       seats  address
    Panathinaiko Stadium                     86300.00   50000  Athens, Greece
    Olympic Stadium                          54700.00   13000  Athens, Greece
    Olympic Indoor Hall                      34100.00   18800  Athens, Greece
    Olympic Hall                             52400.00   21000  Athens, Greece
    Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
    Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
    Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
    Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
    Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

### Ver también

- cubrid_execute() - Ejecutar una sentencia SQL preparada
- cubrid_fetch() - Obtener la siguiente fila de un conjunto de resultados
- cubrid_fetch_array() - Recupera una línea de resultado en forma de array asociativo, array numérico, o ambos
- cubrid_fetch_assoc() - Devuelve un array asociativo correspondiente a la fila recuperada
- cubrid_fetch_object() - Recupera la siguiente línea y la devuelve como un objeto

# cubrid_field_flags

(PECL CUBRID >= 8.3.0)

cubrid_field_flags — Devuelve una string con los flags de la posición del campo proporcionado

### Descripción

function cubrid_field_flags(resource `$result`, int `$field_offset`): string

Esta función devuelve una string con los flags de la posición del campo proporcionado, separados por un espacio. Se puede utilizar la función explode() para obtener cada flag. Los flags disponibles son: `not_null`, `primary_key`, `unique_key`, `foreign_key`, `auto_increment`, `shared`, `reverse_index`, `reverse_unique` y `timestamp`.

### Parámetros

`result`
  El parámetro `result` proviene de la llamada a la función cubrid_execute()
`field_offset`
  La posición numérica del campo. `field_offset` comienza en cero (0). Si `field_offset` no existe, se emitirá un error de nivel `E_WARNING`.

### Valores devueltos

Una string con los flags, en caso de éxito.

`false` si el valor de field_offset es inválido.

-1 si la consulta SQL no es de tipo SELECT.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_field_flags()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $col_num = cubrid_num_cols($result);

    printf("%-30s %s\n", "Field Name", "Field Flags");
    for($i = 0; $i < $col_num; $i++) {
        printf("%-30s %s\n", cubrid_field_name($result, $i), cubrid_field_flags($result, $i));
    }

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    Field Name                     Field Flags
    host_year                      not_null primary_key unique_key
    event_code                     not_null primary_key unique_key foreign_key
    athlete_code                   not_null primary_key unique_key foreign_key
    stadium_code                   not_null
    nation_code
    medal
    game_date

# cubrid_field_len

(PECL CUBRID >= 8.3.0)

cubrid_field_len — Devuelve la longitud máxima del campo especificado

### Descripción

function cubrid_field_len(resource `$result`, int `$field_offset`): int

Esta función devuelve la longitud máxima del campo especificado en caso de éxito, o FALSE en caso de fallo.

### Parámetros

`result`
  `result` proviene de una llamada a la función cubrid_execute()
`field_offset`
  El índice de campo numérico. `field_offset` comienza en 0. Si `field_offset` no existe, se emitirá un error de nivel `E_WARNING`.

### Valores devueltos

La longitud máxima, cuando el proceso ha tenido éxito.

`false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_field_len()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $column_names = cubrid_column_names($result);
    $column_types = cubrid_column_types($result);

    printf("%-30s %-30s %-15s\n", "Column Names", "Column Types", "Column Maxlen");
    for($i = 0, $size = count($column_names); $i < $size; $i++) {
        $column_len = cubrid_field_len($result, $i);
        printf("%-30s %-30s %-15s\n", $column_names[$i], $column_types[$i], $column_len);
    }

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    Column Names                   Column Types                   Column Maxlen
    host_year                      integer                        11
    event_code                     integer                        11
    athlete_code                   integer                        11
    stadium_code                   integer                        11
    nation_code                    char                           3
    medal                          char                           1
    game_date                      date                           10

# cubrid_field_name

(PECL CUBRID >= 8.3.0)

cubrid_field_name — Devuelve el nombre del índice del campo especificado

### Descripción

function cubrid_field_name(resource `$result`, int `$field_offset`): string

Esta función devuelve el nombre del índice del campo especificado en caso de éxito o FALSE en caso de fallo.

### Parámetros

`result`
  `result` proviene de una llamada a la función cubrid_execute()
`field_offset`
  El índice de campo numérico. `field_offset` comienza en 0. Si `field_offset` no existe, se emitirá un error de nivel `E_WARNING`.

### Valores devueltos

El nombre del índice del campo especificado, en caso de éxito.

`false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_field_name()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $col_num = cubrid_num_cols($result);

    printf("%-30s %s\n", "Field Name", "Field Flags");
    for($i = 0; $i < $col_num; $i++) {
        printf("%-30s %s\n", cubrid_field_name($result, $i), cubrid_field_flags($result, $i));
    }

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    Field Name                     Field Flags
    host_year                      not_null primary_key unique_key
    event_code                     not_null primary_key unique_key foreign_key
    athlete_code                   not_null primary_key unique_key foreign_key
    stadium_code                   not_null
    nation_code
    medal
    game_date

# cubrid_field_seek

(PECL CUBRID >= 8.3.0)

cubrid_field_seek — Mueve el cursor del conjunto de resultados al índece del campo especificado

### Descripción

function cubrid_field_seek(resource `$result`, int `$field_offset` = 0): bool

Esta función mueve el cursor del conjunto de resultados al índece del campo especificado. Este índice es usado por cubrid_fetch_field() si no se incluye un índice de campo. Devuelve TRUE en caso de éxito o FALSE en caso de fallo.

### Parámetros

`result`
  `result` proviene de una llamada a la función cubrid_execute()
`field_offset`
  El índice de campo numérico. `field_offset` comienza en 0. Si `field_offset` no existe, se emitirá un error de nivel `E_WARNING`.

### Valores devueltos

`true` en caso de éxito.

`false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_field_seek()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT event_code,athlete_code,nation_code,game_date FROM game WHERE host_year=1988 and event_code=20001;");

    var_dump(cubrid_fetch_row($req));

    cubrid_field_seek($req, 1);
    $field = cubrid_fetch_field($req);

    printf("\n--- Field Properties ---\n");
    printf("%-30s %s\n", "name:", $field->name);
    printf("%-30s %s\n", "table:", $field->table);
    printf("%-30s \"%s\"\n", "default value:", $field->def);
    printf("%-30s %d\n", "max length:", $field->max_length);
    printf("%-30s %d\n", "not null:", $field->not_null);
    printf("%-30s %d\n", "unique key:", $field->unique_key);
    printf("%-30s %d\n", "multiple key:", $field->multiple_key);
    printf("%-30s %d\n", "numeric:", $field->numeric);
    printf("%-30s %s\n", "type:", $field->type);

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    array(4) {
      [0]=>
      string(5) "20001"
      [1]=>
      string(5) "16132"
      [2]=>
      string(3) "KOR"
      [3]=>
      string(9) "1988-09-30"
    }

    --- Field Properties ---
    name:                          athlete_code
    table:                         game
    default value:                 ""
    max length:                    0
    not null:                      1
    unique key:                    1
    multiple key:                  0
    numeric:                       1
    type:                          integer

# cubrid_field_table

(PECL CUBRID >= 8.3.0)

cubrid_field_table — Devuelve el nombre de la tabla del campo especificado

### Descripción

function cubrid_field_table(resource `$result`, int `$field_offset`): string

Esta función devuelve el nombre de la tabla del campo especificado. Esto es útil cuando se usan consultas SELECT largas con JOINS.

### Parámetros

`result`
  `result` proviene de una llamada a cubrid_execute()
`field_offset`
  El desplazamiento del campo numérico. El `field_offset` comienza en 0. Si `field_offset` no existe, también se emite un error de nivel `E_WARNING`.

### Valores devueltos

El nombre de la tabla del campo especificado, en caso de éxito.

`false` cuando field_offset tiene un valor no válido.

-1 si la sentencia SQL no es SELECT.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_field_table()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM code");

    $col_num = cubrid_num_cols($result);

    printf("%-15s %-15s %s\n", "Field Table", "Field Name", "Field Type");
    for($i = 0; $i < $col_num; $i++) {
        printf("%-15s %-15s %s\n",
            cubrid_field_table($result, $i), cubrid_field_name($result, $i), cubrid_field_type($result, $i));
    }

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    Field Table     Field Name      Field Type
    code            s_name          char
    code            f_name          varchar

# cubrid_field_type

(PECL CUBRID >= 8.3.0)

cubrid_field_type — Devuelve el tipo de columna que se corresponde con el índice del campo dado

### Descripción

function cubrid_field_type(resource `$result`, int `$field_offset`): string

Esta función devuelve el tipo de columna que se corresponde con el índice del campo dado. El tipo de campo devuelto debería ser uno de los siguientes: "int", "real", "string", etc.

### Parámetros

`result`
  `result` proviene de una llamada a cubrid_execute()
`field_offset`
  El índice de campo numérico. `field_offset` comienza en 0. Si `field_offset` no existe, se emitirá un error de nivel `E_WARNING`.

### Valores devueltos

El tipo de la columna, en caso de éxito.

`false` cuando field_offset no tiene un valor válido.

-1 si la sentencia SQL no es SELECT.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_field_type()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM code");

    $col_num = cubrid_num_cols($result);

    printf("%-15s %-15s %s\n", "Field Table", "Field Name", "Field Type");
    for($i = 0; $i < $col_num; $i++) {
        printf("%-15s %-15s %s\n",
            cubrid_field_table($result, $i), cubrid_field_name($result, $i), cubrid_field_type($result, $i));
    }

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    Field Table     Field Name      Field Type
    code            s_name          char
    code            f_name          varchar

# cubrid_list_dbs

(PECL CUBRID >= 8.3.0)

cubrid_list_dbs — Devuelve una matriz con la lista de todas las bases de datos Cubrid existentes

### Descripción

function cubrid_list_dbs(resource `$conn_identifier` = ?): array

Esta función devuelve una matriz con la lista de todas las bases de datos Cubrid existentes.

### Parámetros

`conn_identifier`
  La conexión CUBRID.

### Valores devueltos

Una matriz numérica con todas las bases de datos Cubrid existentes; en caso de éxito.

`false` en caso de fallo.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_list_dbs()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $db_list = cubrid_list_dbs($conn);
    var_dump($db_list);

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    array(1) {
      [0]=>
      string(6) "demodb"
    }

# cubrid_num_fields

(PECL CUBRID >= 8.3.0)

cubrid_num_fields — Devuelve el número de columnas en el conjunto de resultados

### Descripción

function cubrid_num_fields(resource `$result`): int

Esta función devuelve el número de columnas en el conjunto de resultados en caso de éxito, o `false` si ocurre un error.

### Parámetros

`result`
  El parámetro `result` proviene de una llamada a la función cubrid_execute(), cubrid_query() o cubrid_prepare()

### Valores devueltos

Número de columnas en caso de éxito.

-1 si la consulta SQL no es de tipo SELECT.

`false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_num_fields()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $req = cubrid_execute($conn, "SELECT * FROM code");

    $row_num = cubrid_num_rows($req);
    $col_num = cubrid_num_fields($req);

    printf("Row Num: %d\nColumn Num: %d\n", $row_num, $col_num);

    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    Row Num: 6
    Column Num: 2

# cubrid_ping

(PECL CUBRID >= 8.3.1)

cubrid_ping — Hacer ping en una conexión al servidor o reconectar si no hay conexión

### Descripción

function cubrid_ping(resource `$conn_identifier` = ?): bool

Verifica si la conexión al servidor está funcionando..

### Parámetros

`conn_identifier`
  El identificador de conexión de CUBRID. Si el identificador de conexión no se especifica, se asume la última conexión abierta por cubrid_connect().

### Valores devueltos

Devuelve `true` si la conexión al servidor CUBRID está funcionando, si no `false`.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_ping()

    <?php
    set_time_limit(0);

    $con = cubrid_connect('localhost', 33000, 'demodb');

    /* Se asume que esta consulta tomará mucho tiempo */
    $sql = "select * from athlete";
    $result = cubrid_query($sql);
    if (!$result) {
        echo 'La consulta #1 falló, saliendo.';
        exit;
    }

    /* Asegurarse de que la conexión todavía perdura, si no, intentar reconectar */
    if (!cubrid_ping($con)) {
        echo 'Conexión perdida, saliendo después de la consulta #1';
        exit;
    }
    cubrid_free_result($result);

    /* Ya que la conexión aún perdura, vamos a ejecutar otra consulta */
    $sql2 = "select * from code";
    $result2 = cubrid_query($sql2);
    ?>

# cubrid_query

(PECL CUBRID >= 8.3.1)

cubrid_query — Enviar una consulta CUBRID

### Descripción

function cubrid_query(string `$query`, resource `$conn_identifier` = ?): resource

cubrid_query() envía una consulta única (no están soportadas consultas múltiples) a la base de datos activa actual en el servidor que está asociado con el `conn_identifier` especificado.

### Parámetros

`query`
  Una consulta SQL La información dentro de la consulta debería estar adecuadamente escapada.
`conn_identifier`
  La conexión CUBRID. Si el identificador de conexión no se especifica, se asume la última conexión abierta por cubrid_connect().

### Valores devueltos

Para SELECT, SHOW, DESCRIBE, EXPLAIN y otras sentencias que devuelven conjuntos de resultadosa, cubrid_query() devuelve un resource en caso de éxito, o `false` en caso de error.

Para otros tipos de sentencias SQL, INSERT, UPDATE, DELETE, DROP, etc, cubrid_query() devuelve `true` en caso de éxito o `false` en caso de error.

El recurso resultado devuelto debería ser pasado a cubrid_fetch_array(), y a otras funciones para tratar con las tablas de resultados, para acceder a la información devuelta.

Use cubrid_num_rows() para averiguar cuántas filas fueron devueltas por una sentencia SELECT o cubrid_affected_rows() para averiguar cuántas filas fueron afectadas por una sentencia DELETE, INSERT, REPLACE, o UPDATE.

cubrid_query() también podrá fallar y devolver `false` si el usuario no tiene permiso para acceder a la/s tabla/s referenciada/s por la consulta.

### Ejemplos

Ejemplo #1 Consulta No Válida

La siguiente consulta no es válida sintácticamente, por lo que cubrid_query() fallará y devolverá `false`.

    <?php
    $conn = cubrid_connect('localhost', 33000, 'demodb');

    $result = cubrid_query('SELECT * WHERE 1=1');
    if (!$result) {
        die('Consulta inválida: ' . cubrid_error());
    }

    ?>

Ejemplo #2 Consulta Válida

La siguiente consulta es válida, por lo que cubrid_query() devolverá un resource.

    <?php
    // Esto podría ser proporcionado por el usuario, por ejemplo
    $nombre = 'fred';
    $apellido  = 'fox';

    cubrid_execute($conn,"DROP TABLE if exists friends");
    cubrid_execute($conn,"create table friends(firstname varchar,lastname varchar,address char(24),age int)");
    cubrid_execute($conn,"insert into friends values('fred','fox','home-1','20')");
    cubrid_execute($conn,"insert into friends values('blue','cat','home-2','21')");
    // Formular la Consulta
    // Esta es la mejor manera de realizar una consulta SQL
    // Para más ejemplos, véase cubrid_real_escape_string()
    $consulta = sprintf("SELECT firstname, lastname, address, age FROM friends WHERE firstname='%s' AND lastname='%s'",
    cubrid_real_escape_string($nombre),
    cubrid_real_escape_string($apellido));

    // Realizar la Constulta
    $result = cubrid_query($consulta);

    // Verificar el resultado
    // Esto muestra la consulta real enviada a CUBRID, y el error. Útil para depuración.
    if (!$result) {
        $mensaje  = 'Consulta no válida: ' . cubrid_error() . "\n";
        $mensaje .= 'Consulta completa: ' . $consulta;
        die($mensaje);
    }

    // Usar el resultado
    // Intentar imprimir $result no permitirá el acceso a la información en el recurso
    // Se debe usar una de las funciones de resultados de cubrid
    // Véase también cubrid_result(), cubrid_fetch_array(), cubrid_fetch_row(), etc.
    while ($fila = cubrid_fetch_assoc($result)) {
        echo $fila['firstname'];
        echo $fila['lastname'];
        echo $fila['address'];
        echo $fila['age'];
    }

    // Liberar los recursos asociados con el conjunto de resultados
    // Esto se hace automáticamente al final del script
    cubrid_free_result($result);
    ?>

### Ver también

- cubrid_connect() - Abrir una conexión al servidor CUBRID
- cubrid_error() - Se usa para obtener el mensaje de error
- cubrid_real_escape_string() - Escapar caracteres especiales en una cadena para usarla en una sentencia SQL
- cubrid_result() - Devuelve el valor de un campo específico de una fila específica
- cubrid_fetch_assoc() - Devuelve un array asociativo correspondiente a la fila recuperada
- cubrid_unbuffered_query() - Realiza una consulta sin traer los resultados a memoria

# cubrid_real_escape_string

(PECL CUBRID >= 8.3.0)

cubrid_real_escape_string — Escapar caracteres especiales en una cadena para usarla en una sentencia SQL

### Descripción

function cubrid_real_escape_string(string `$unescaped_string`, resource `$conn_identifier` = ?): string

Esta función devuelve la versión escapada de la cadena dada. Escapará los siguientes caracteres: `'`. En general, las comillas simples se usan para encerrar strings. Las comillas dobles se pueden usar también dependiendo del valor de ansi_quotes, que es un parámetro relacionado con sentencias SQL. Si el valor de ansi_quotes value está establecido a no, los strings encerrados entre comillas dobles se tratan como strings, no como identificadores. El valor predeterminado es yes. Si quiere incluir una comilla simple como parte de una cadena de caracteres, introduzca dos comillas simples en una fila.

### Parámetros

`unescaped_string`
  La cadena que va a ser escapada.
`conn_identifier`
  La conexión CUBRID. Si el identificador de conexión no se especifica, se asume el último enlace abierto por cubrid_connect().

### Valores devueltos

La versión escapada de la cadena dada, en caso de éxito.

`false` en caso de fallo.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_real_escape_string()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $unescaped_str = ' !"#$%&\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~';
    $escaped_str = cubrid_real_escape_string($unescaped_str);

    $len = strlen($unescaped_str);

    @cubrid_execute($conn, "DROP TABLE cubrid_test");
    cubrid_execute($conn, "CREATE TABLE cubrid_test (t char($len))");
    cubrid_execute($conn, "INSERT INTO cubrid_test (t) VALUES('$escaped_str')");

    $req = cubrid_execute($conn, "SELECT * FROM cubrid_test");
    $row = cubrid_fetch_assoc($req);

    var_dump($row);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    array(1) {
      ["t"]=>
      string(95) " !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~"
    }

# cubrid_result

(PECL CUBRID >= 8.3.0)

cubrid_result — Devuelve el valor de un campo específico de una fila específica

### Descripción

function cubrid_result(resource `$result`, int `$row`, mixed `$field` = 0): string

Esta función devuelve el valor de un campo específico de una fila específica de un conjunto de resultados.

### Parámetros

`result`
  `result` proviene de una llamada a la función cubrid_execute()
`row`
  El número de fila del resultado que está siendo traído. Los números de fila comienzan en 0.
`field`
  El nombre o índice del campo dado por `field` que está siendo obtenido. Puede ser el índice del campo, el nombre del campo, o la tabla del campo punto nombre del campo (nombretabla.nombrecampo). Si el nombre de la columna ha sido apodado ('select foo as bar from...'), use el alias en vez del nombre de la columna. Si no está definido se trae el primer campo.

### Valores devueltos

El valor de un campo específico, en caso de éxito (NULL si el valor es nulo).

`false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_result()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $req = cubrid_execute($conn, "SELECT * FROM code");

    $result = cubrid_result($req, 0);
    var_dump($result);

    $result = cubrid_result($req, 0, 1);
    var_dump($result);

    $result = cubrid_result($req, 5, "f_name");
    var_dump($result);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

El ejemplo anterior mostrará:

    string(1) "X"
    string(5) "Mixed"
    string(4) "Gold"

# cubrid_unbuffered_query

(PECL CUBRID >= 8.3.0)

cubrid_unbuffered_query — Realiza una consulta sin traer los resultados a memoria

### Descripción

function cubrid_unbuffered_query(string `$query`, resource `$conn_identifier` = ?): resource

Esta función realiza una consulta sin esperar a que todos los resultados de consulta hayan sido completados. Devolverá cuando los resultados están siendo generados.

### Parámetros

`query`
  Una consulta SQL.
`conn_identifier`
  La conexión CUBRID. Si el identificador de conexión no se especifica, se asume el último enlace abierto por cubrid_connect().

### Valores devueltos

Para sentencias SELECT, SHOW, DESCRIBE o EXPLAIN devuelve un recurso identificador de petición en caso de éxito.

Para otro tipo de sentencias SQL, UPDATE, DELETE, DROP, etc,, devuelve `true` en caso de éxito.

`false` en caso de fallo.

### Ejemplos

Ejemplo #1 Ejemplo de cubrid_unbuffered_query()

    <?php
        $enlace = cubrid_connect("localhost", 30000, "demodb", "dba", "");
        if (!$enlace)
        {
            die('No se pudo conectar.');
        }
        $consulta = "select * from code";
        $resultado = cubrid_unbuffered_query($consulta, $enlace);

        while ($fila = cubrid_fetch($resultado))
        {
            var_dump($fila);
        }

        cubrid_close_request($resultado);
        cubrid_disconnect($enlace);
    ?>

### Notas

> Nota: Los beneficios de cubrid_unbuffered_query() tienen un coste: no se puede usar cubrid_num_rows() y cubrid_data_seek() en un conjunto de resultados devueltos desde cubrid_unbuffered_query().

## Tabla de contenidos

- cubrid_affected_rows — Devolver el número de filas afectadas por la última sentencia SQL
- cubrid_client_encoding — Devuelve el actual conjunto de caracteres de la conexión a CUBRID
- cubrid_close — Cerrar la conexión de CUBRID
- cubrid_data_seek — Mueve el puntero interno de la fila del resultado CUBRID
- cubrid_db_name — Obtener el nombre de la base de datos desde los resultados de cubrid_list_dbs
- cubrid_errno — Devuelve el valor numérico del mensaje de error de la operación de CUBRID previa
- cubrid_error — Se usa para obtener el mensaje de error
- cubrid_fetch_array — Recupera una línea de resultado en forma de array asociativo, array numérico, o ambos
- cubrid_fetch_assoc — Devuelve un array asociativo correspondiente a la fila recuperada
- cubrid_fetch_field — Devuelve un objeto con ciertas propiedades
- cubrid_fetch_lengths — Devuelve una matriz con las longitudes de los valores de cada campo de la fila actual
- cubrid_fetch_object — Recupera la siguiente línea y la devuelve como un objeto
- cubrid_fetch_row — Devuelve un array numérico con los valores de la fila actual
- cubrid_field_flags — Devuelve una string con los flags de la posición del campo proporcionado
- cubrid_field_len — Devuelve la longitud máxima del campo especificado
- cubrid_field_name — Devuelve el nombre del índice del campo especificado
- cubrid_field_seek — Mueve el cursor del conjunto de resultados al índece del campo especificado
- cubrid_field_table — Devuelve el nombre de la tabla del campo especificado
- cubrid_field_type — Devuelve el tipo de columna que se corresponde con el índice del campo dado
- cubrid_list_dbs — Devuelve una matriz con la lista de todas las bases de datos Cubrid existentes
- cubrid_num_fields — Devuelve el número de columnas en el conjunto de resultados
- cubrid_ping — Hacer ping en una conexión al servidor o reconectar si no hay conexión
- cubrid_query — Enviar una consulta CUBRID
- cubrid_real_escape_string — Escapar caracteres especiales en una cadena para usarla en una sentencia SQL
- cubrid_result — Devuelve el valor de un campo específico de una fila específica
- cubrid_unbuffered_query — Realiza una consulta sin traer los resultados a memoria

# Alias y Funciones Obsoletas de CUBRID

# cubrid_load_from_glo

(PECL CUBRID >= 8.3.0)

cubrid_load_from_glo — Liga una donnée

### Descripción

function cubrid_load_from_glo(resource `$conn_identifier`, string `$oid`, string `$file_name`): int

La función cubrid_load_from_glo() se utiliza para leer una donnée desde una instancia glo, y la guarda en un fichero dado.

### Parámetros

`conn_identifier`
  Identificador de conexión.
`oid`
  Oid de la instancia glo desde la cual se desea leer la donnée.
`file_name`
  Nombre del fichero donde se debe realizar la guarda de la donnée.

### Valores devueltos

`true` cuando el proceso es un éxito.

`false` cuando el proceso ha fallado.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_load_from_glo()

    <?php
    $req = cubrid_execute ($con, "select image from person where id=1");
    if ($req) {
       list ($oid) = cubrid_fetch($req);
       cubrid_close_request($req);
       $res = cubrid_load_from_glo ($con, $oid, "output.jpg");
       if ($res) {
          echo "imagen cambiada con éxito";
       }
    }
    ?>

### Notas

> Nota: Por razones de compatibilidad ascendente, el siguiente alias obsoleto puede ser utilizado: cubrid_load_from_glo()

> Nota: Esta función ha sido eliminada desde CUBRID 3.1.

### Ver también

- cubrid_new_glo() - Crea una instancia glo
- cubrid_save_to_glo() - Guarda un fichero en una instancia glo
- cubrid_send_glo() - Lee los datos desde una instancia glo

# cubrid_new_glo

(PECL CUBRID >= 8.3.0)

cubrid_new_glo — Crea una instancia glo

### Descripción

function cubrid_new_glo(resource `$conn_identifier`, string `$class_name`, string `$file_name`): string

La función cubrid_new_glo() se utiliza para crear una instancia glo en la clase solicitada (clase glo). El glo creado es de tipo LO y se almacena en el fichero `file_name`.

### Parámetros

`conn_identifier`
  Identificador de conexión.
`class_name`
  Nombre de la clase en la que se desea crear el glo.
`file_name`
  El nombre del fichero en el que se desea guardar el nuevo glo creado.

### Valores devueltos

OID de la instancia creada en caso de éxito.

`false` en caso de fallo.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_new_glo()

    <?php
    $oid = cubrid_new_glo ($con, "glo", "input.jpg");
    if ($oid){
       // El tipo de la columna "image" es "object"
       $req = cubrid_execute ($con, "insert into person(image) values($oid)");
       if ($req) {
          echo "imagen insertada con éxito";
          cubrid_close_request ($req);
          cubrid_commit($con);
       }
    }
    ?>

### Notas

> Nota: Por razones de compatibilidad ascendente, el siguiente alias obsoleto puede ser utilizado: cubrid_new_glo()

> Nota: Esta función ha sido eliminada desde CUBRID 3.1.

### Ver también

- cubrid_save_to_glo() - Guarda un fichero en una instancia glo
- cubrid_load_from_glo() - Liga una donnée
- cubrid_send_glo() - Lee los datos desde una instancia glo

# cubrid_save_to_glo

(PECL CUBRID >= 8.3.0)

cubrid_save_to_glo — Guarda un fichero en una instancia glo

### Descripción

function cubrid_save_to_glo(resource `$conn_identifier`, string `$oid`, string `$file_name`): int

La función cubrid_save_to_glo() se utiliza para guardar un fichero en una instancia glo.

### Parámetros

`conn_identifier`
  Identificador de conexión.
`oid`
  Oid de la instancia glo en la que se guardará el fichero.
`file_name`
  El nombre del fichero a guardar.

### Valores devueltos

`true` en caso de éxito.

`false` en caso de fallo.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_save_to_glo()

    <?php
    $req = cubrid_execute ($con, "select image from person where id=1");
    if ($req) {
       list ($oid) = cubrid_fetch($req);
       cubrid_close_request($req);
       $res = cubrid_save_to_glo ($con, $oid, "input.jpg");
       if ($res) {
          echo "imagen cambiada con éxito";
       }
    }
    ?>

### Notas

> Nota: Por razones de compatibilidad ascendente, el siguiente alias obsoleto puede ser utilizado: cubrid_save_to_glo()

> Nota: Esta función ha sido eliminada desde CUBRID 3.1.

### Ver también

- cubrid_new_glo() - Crea una instancia glo
- cubrid_load_from_glo() - Liga una donnée
- cubrid_send_glo() - Lee los datos desde una instancia glo

# cubrid_send_glo

(PECL CUBRID >= 8.3.0)

cubrid_send_glo — Lee los datos desde una instancia glo

### Descripción

function cubrid_send_glo(resource `$conn_identifier`, string `$oid`): int

La función cubrid_send_glo() se utiliza para leer los datos desde una instancia glo y los envía a la salida estándar de PHP.

### Parámetros

`conn_identifier`
  Identificador de conexión.
`oid`
  Oid de la instancia glo desde la cual se leen los datos.

### Valores devueltos

`true` en caso de éxito.

`false` en caso de fallo.

### Ejemplos

Ejemplo #1 Ejemplo con cubrid_send_glo()

    <?php
    $req = cubrid_execute ($con, "select image from person where id =1");
    if ($req) {
      list ($oid) = cubrid_fetch($req);
      cubrid_close_request($req);
      Header ("Content-type: image/jpeg");
      cubrid_send_glo ($con, $oid);
    }
    ?>

### Notas

> Nota: Por razones de compatibilidad ascendente, el siguiente alias obsoleto puede ser utilizado: cubrid_send_glo()

> Nota: Esta función ha sido eliminada desde CUBRID 3.1.

### Ver también

- cubrid_new_glo() - Crea una instancia glo
- cubrid_save_to_glo() - Guarda un fichero en una instancia glo
- cubrid_load_from_glo() - Liga una donnée

## Tabla de contenidos

- cubrid_load_from_glo — Liga una donnée
- cubrid_new_glo — Crea una instancia glo
- cubrid_save_to_glo — Guarda un fichero en una instancia glo
- cubrid_send_glo — Lee los datos desde una instancia glo

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
  - Tipos de recursos
- Constantes predefinidas
- Ejemplos
- Funciones de CUBRID
  - cubrid_bind — Vincular variables para una sentencia preparada como parámetros
  - cubrid_close_prepare — Cerrar el gestor de solicitud
  - cubrid_close_request — Cerrar el gestor de solicitud
  - cubrid_col_get — Recupera el contenido de los elementos de un tipo de colección utilizando el OID
  - cubrid_col_size — Obtener el número de elementos de la columna del tipo de colección usando OID
  - cubrid_column_names — Obtener los nombres de las columnas del resultado
  - cubrid_column_types — Obtener los tipos de columnas del resultado
  - cubrid_commit — Consigna una transacción
  - cubrid_connect — Abrir una conexión al servidor CUBRID
  - cubrid_connect_with_url — Establecer el entorno para la conexión al servidor de CUBRID
  - cubrid_current_oid — Obtener el OID de la posición del cursor actual
  - cubrid_disconnect — Cerrar una conexión a una base de datos
  - cubrid_drop — Borrar una instancia usando OID
  - cubrid_error_code — Obtener el código de error de la llamada a una función más reciente
  - cubrid_error_code_facility — Obtener el código de error del dispositivo
  - cubrid_error_msg — Obtener el último mensaje de error de la llamada a la función más reciente
  - cubrid_execute — Ejecutar una sentencia SQL preparada
  - cubrid_fetch — Obtener la siguiente fila de un conjunto de resultados
  - cubrid_free_result — Liberar la memoria ocupada por los datos del resultado
  - cubrid_get — Obtener una columna usando OID
  - cubrid_get_autocommit — Recupera el modo auto-commit de la conexión
  - cubrid_get_charset — Devolver el conjunto de caracteres de la conexión CUBRID actual
  - cubrid_get_class_name — Obtener el nombre de la clase usando OID
  - cubrid_get_client_info — Devolver la versión de la biblioteca cliente
  - cubrid_get_db_parameter — Devuelve los parámetros de la base de datos CUBRID
  - cubrid_get_query_timeout — Obtener el valor del tiempo de espera de consulta de la petición
  - cubrid_get_server_info — Devolver la versión del servidor CUBRID
  - cubrid_insert_id — Devuelve el ID generado por la última columna actualizada AUTO_INCREMENT
  - cubrid_is_instance — Comprobar si existe la instancia apuntada por OID
  - cubrid_lob_close — Cerrar información BLOB/CLOB
  - cubrid_lob_export — Exporta datos BLOB/CLOB a un fichero
  - cubrid_lob_get — Recupera los datos BLOB/CLOB
  - cubrid_lob_send — Lee los datos BLOB/CLOB y los envía al navegador
  - cubrid_lob_size — Recupera el tamaño de los datos BLOB/CLOB
  - cubrid_lob2_bind — Asocia un objeto LOB o una cadena de caracteres a un objeto LOB como argumento de una consulta preparada
  - cubrid_lob2_close — Cierra un objeto LOB
  - cubrid_lob2_export — Exporta un objeto LOB a un fichero
  - cubrid_lob2_import — Importa datos BLOB/CLOB desde un fichero
  - cubrid_lob2_new — Crea un nuevo objeto LOB
  - cubrid_lob2_read — Lee datos BLOB/CLOB
  - cubrid_lob2_seek — Desplaza el cursor de un objeto LOB
  - cubrid_lob2_seek64 — Desplaza el cursor de un objeto LOB
  - cubrid_lob2_size — Obtiene el tamaño de un objeto LOB
  - cubrid_lob2_size64 — Recupera el tamaño de un objeto LOB
  - cubrid_lob2_tell — Recupera la posición del cursor en un objeto LOB
  - cubrid_lob2_tell64 — Recupera la posición del cursor en el objeto LOB
  - cubrid_lob2_write — Escribe en un objeto LOB
  - cubrid_lock_read — Coloca un bloqueo de lectura sobre el OID proporcionado
  - cubrid_lock_write — Coloca un bloqueo de escritura en el OID proporcionado
  - cubrid_move_cursor — Desplaza el cursor en el resultado
  - cubrid_next_result — Recupera el resultado de la siguiente consulta durante la ejecución de múltiples consultas SQL
  - cubrid_num_cols — Obtiene el número de columnas del conjunto de resultados
  - cubrid_num_rows — Obtiene el número de filas de un conjunto de resultados
  - cubrid_pconnect — Establece una conexión persistente con un servidor CUBRID
  - cubrid_pconnect_with_url — Establece una conexión persistente con un servidor CUBRID
  - cubrid_prepare — Prepara una consulta SQL para su ejecución
  - cubrid_put — Actualiza una columna según su OID
  - cubrid_rollback — Anula una transacción
  - cubrid_schema — Recupera información sobre un esquema
  - cubrid_seq_drop — Elimina un elemento de una secuencia
  - cubrid_seq_insert — Inserta un elemento en una secuencia
  - cubrid_seq_put — Actualiza el valor de un elemento de una secuencia
  - cubrid_set_add — Inserta un único elemento para definir el tipo de una columna
  - cubrid_set_autocommit — Define el modo auto-commit para la conexión
  - cubrid_set_db_parameter — Define los parámetros de la base de datos CUBRID
  - cubrid_set_drop — Elimina un elemento
  - cubrid_set_query_timeout — Define el tiempo máximo de ejecución de una consulta
  - cubrid_version — Obtener la versión del módulo de PHP de CUBRID
- Funciones de compatibilidad CUBRID MySQL
  - cubrid_affected_rows — Devolver el número de filas afectadas por la última sentencia SQL
  - cubrid_client_encoding — Devuelve el actual conjunto de caracteres de la conexión a CUBRID
  - cubrid_close — Cerrar la conexión de CUBRID
  - cubrid_data_seek — Mueve el puntero interno de la fila del resultado CUBRID
  - cubrid_db_name — Obtener el nombre de la base de datos desde los resultados de cubrid_list_dbs
  - cubrid_errno — Devuelve el valor numérico del mensaje de error de la operación de CUBRID previa
  - cubrid_error — Se usa para obtener el mensaje de error
  - cubrid_fetch_array — Recupera una línea de resultado en forma de array asociativo, array numérico, o ambos
  - cubrid_fetch_assoc — Devuelve un array asociativo correspondiente a la fila recuperada
  - cubrid_fetch_field — Devuelve un objeto con ciertas propiedades
  - cubrid_fetch_lengths — Devuelve una matriz con las longitudes de los valores de cada campo de la fila actual
  - cubrid_fetch_object — Recupera la siguiente línea y la devuelve como un objeto
  - cubrid_fetch_row — Devuelve un array numérico con los valores de la fila actual
  - cubrid_field_flags — Devuelve una string con los flags de la posición del campo proporcionado
  - cubrid_field_len — Devuelve la longitud máxima del campo especificado
  - cubrid_field_name — Devuelve el nombre del índice del campo especificado
  - cubrid_field_seek — Mueve el cursor del conjunto de resultados al índece del campo especificado
  - cubrid_field_table — Devuelve el nombre de la tabla del campo especificado
  - cubrid_field_type — Devuelve el tipo de columna que se corresponde con el índice del campo dado
  - cubrid_list_dbs — Devuelve una matriz con la lista de todas las bases de datos Cubrid existentes
  - cubrid_num_fields — Devuelve el número de columnas en el conjunto de resultados
  - cubrid_ping — Hacer ping en una conexión al servidor o reconectar si no hay conexión
  - cubrid_query — Enviar una consulta CUBRID
  - cubrid_real_escape_string — Escapar caracteres especiales en una cadena para usarla en una sentencia SQL
  - cubrid_result — Devuelve el valor de un campo específico de una fila específica
  - cubrid_unbuffered_query — Realiza una consulta sin traer los resultados a memoria
- Alias y Funciones Obsoletas de CUBRID
  - cubrid_load_from_glo — Liga una donnée
  - cubrid_new_glo — Crea una instancia glo
  - cubrid_save_to_glo — Guarda un fichero en una instancia glo
  - cubrid_send_glo — Lee los datos desde una instancia glo

# dBase

# Introducción

> Nota:

> Esta extensión ha sido movida al módulo » PECL y no será integrada en PHP a partir de PHP 5.3.0.

Estas funciones permiten acceder a los registros de las bases de datos en formato dBase (dbf).

Advertencia

Se recomienda no utilizar los ficheros dBase como base de datos de producción. Utilice » SQLite o mejor opte por un verdadero servidor SQL; » MySQL o » PostgreSQL son opciones comunes en PHP. El soporte dBase está presente en PHP únicamente para permitir la importación y exportación de datos desde y hacia su base de datos, ya que este formato de fichero es habitualmente comprendido por los programas de hoja de cálculo de Windows.

Precaución

A partir de dbase 7.0.0 las bases de datos son automáticamente bloqueadas via flock(). No había soporte para el bloqueo previamente, por lo que dos procesos de servidor web concurrentes modificando el mismo fichero dBase probablemente habrían arruinado su base de datos. Esto puede ocurrir incluso con dbase 7.0.0+ en sistemas que implementan el bloqueo a nivel de proceso con las SAPIs multithreaded.

Los ficheros dBase son simples ficheros secuenciales, con un número de registros fijo. Los registros son añadidos al final del fichero y los registros borrados son conservados hasta que se llame a la función dbase_pack().

Solo se soportan los ficheros dbf niveles 3 (dBASE III+) - 5 (dBASE V). Los tipos de campos dBase disponibles son:

Tipo de campos disponible
Campo | Tipo dBase | Formato | Información complementaria
--- | --- | --- | ---
`M` | Memo | n/a | Este tipo no es soportado por PHP, y será ignorado
`D` | Date | `YYYYMMDD` | El tamaño del campo está limitado a 8
`T` | DateTime | `YYYYMMDDhhmmss.uuu` | (FoxPro) No se realizan verificaciones de validez. Disponible a partir de dbase 7.0.0.
`N` | Number | Un número | Se debe declarar un tamaño y una precisión (el número de dígitos después del punto decimal).
`F` | Float | Un número flotante | Idéntico a `N`.
`C` | string | Una cadena de caracteres | Se debe declarar un tamaño. Al recuperar los datos, la cadena será completada con espacios para alcanzar el tamaño declarado. Las cadenas demasiado largas serán truncadas silenciosamente al guardar.
`L` | bool | `T` o `Y` para `true`, `F` o `N` para `false`, `?` para no inicializada. | A partir de dbase 7.0.0, devuelto como bool (`true` o `false`), o `null` para los campos no inicializados Anteriormente, devuelto como int (`1` o `0`).

> Nota:

> A partir de dbase 7.0.0 los campos nullable son soportados para las bases de datos `DBASE_TYPE_FOXPRO`. Si un campo es nullable, pasar `null` definirá el flag respectivo, y al recuperarlo el valor del campo será `null`.

> Nota:

> No hay soporte para índices o campos memo.

# Instalación/Configuración

## Tabla de contenidos

- Instalación
- Tipos de recursos

## Instalación

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/dbase.

## Tipos de recursos

A partir de dbase 7.0.0, el tipo de recurso `dbase` está definido, el cual es devuelto por dbase_open() y dbase_create().

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`DBASE_VERSION` (string)
  La versión de la extensión (Disponible a partir de dbase 7.0.0)
`DBASE_RDONLY` (int)
  Abre una base de datos en modo de solo lectura. Utilizado con dbase_open(). (Disponible a partir de dbase 7.0.0)
`DBASE_RDWR` (int)
  Abre una base de datos en modo de lectura y escritura. Utilizado con dbase_open(). (Disponible a partir de dbase 7.0.0)
`DBASE_TYPE_DBASE` (int)
  Crea una base de datos de estilo dBASE. Utilizado con dbase_create(). (Disponible a partir de dbase 7.0.0)
`DBASE_TYPE_FOXPRO` (int)
  Crea una base de datos de estilo FoxPro. Utilizado con dbase_create(). (Disponible a partir de dbase 7.0.0)

# Funciones dBase

## Ejemplos

La mayoría de los ejemplos de esta documentación requieren una base de datos dBase. Se utilizará /tmp/test.dbf que es creada en el ejemplo de la función dbase_create().

# dbase_add_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_add_record — Añade un registro en una base de datos dBase

### Descripción

function dbase_add_record(resource `$database`, array `$data`): bool

dbase_add_record() añade los datos proporcionados en la base de datos dBase especificada.

### Parámetros

`database`

  El recurso de base de datos, devuelto por dbase_open() o dbase_create().

`data`

  Un array de datos indexado. El número de elementos debe ser igual al número de campos en la base de datos, de lo contrario la función dbase_add_record() fallará.

  > Nota:

  > Si se utiliza dbase_get_record() para devolver un valor para este argumento, no se olvide de reinicializar la clave nombrada `deleted`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL dbase 7.0.0 | `database` es ahora un resource en lugar de un int.

### Ejemplos

Ejemplo #1 Inserción de un registro en una base de datos dBase

    <?php

    // Apertura en modo lectura-escritura
    $db = dbase_open('/tmp/test.dbf', 2);

    if ($db) {
      dbase_add_record($db, array(
        date('Ymd'),
        'Maxim Topolov',
        '23',
        'max@example.com',
        'T'));
      dbase_close($db);
    }

    ?>

### Ver también

- dbase_delete_record() - Borra un registro en una base dBase
- dbase_replace_record() - Reemplaza un registro en una base dBase

# dbase_close

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_close — Cierra una base dBase

### Descripción

function dbase_close(resource `$database`): bool

dbase_close() cierra la base de datos correspondiente al recurso `database`.

### Parámetros

`database`

  El recurso de base de datos, devuelto por dbase_open() o dbase_create().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL dbase 7.0.0 | `database` es ahora un resource en lugar de un int.

### Ejemplos

Ejemplo #1 Cierra un fichero de base de datos dBase

    <?php

    // Apertura en modo lectura-escritura
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
    // Lectura de datos ..

    dbase_close($db);
    }

    ?>

### Ver también

- dbase_open() - Abre una base dBase
- dbase_create() - Crea una base de datos dBase

# dbase_create

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_create — Crea una base de datos dBase

### Descripción

function dbase_create(string `$path`, array `$fields`, int `$type` = DBASE_TYPE_DBASE): resource

dbase_create() crea una base de datos dBase con la definición proporcionada. Si el fichero ya existe, no se trunca. dbase_pack() puede ser llamado para forzar una troncación.

> Nota: Esta función es afectada por la directiva de configuración open_basedir.

### Parámetros

`path`

  La ruta de acceso a la base de datos. Puede ser una ruta relativa o absoluta al fichero donde dBase almacenará sus datos.

`fields`

  Un array de arrays, cada array describe el formato de un campo de la base de datos. Cada campo está compuesto por un nombre, un carácter que indica el tipo de campo y opcionalmente, una longitud, una precisión y un flag nullable. Los campos soportados se enumeran en la sección de introducción.

  > Nota:

  > Los nombres de los campos están limitados en longitud y no deben exceder los 10 caracteres.

`type`

  El tipo de base de datos a crear. Puede ser `DBASE_TYPE_DBASE` o `DBASE_TYPE_FOXPRO`.

### Valores devueltos

Devuelve un recurso de base de datos si la base de datos ha sido creada con éxito, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL dbase 7.0.0 | El parámetro `type` ha sido añadido.
PECL dbase 7.0.0 | `dbase_identifier` es ahora un resource en lugar de un int.

### Ejemplos

Ejemplo #1 Creación de un fichero de base de datos dBase

    <?php

    // Definición de la base de datos
    $def = array(
      array("date",     "D"),
      array("name",     "C",  50),
      array("age",      "N",   3, 0),
      array("email",    "C", 128),
      array("ismember", "L")
    );

    // Creación
    if (!dbase_create('/tmp/test.dbf', $def)) {
      echo "Error, imposible crear la base de datos\n";
    }

    ?>

### Ver también

- dbase_open() - Abre una base dBase
- dbase_close() - Cierra una base dBase

# dbase_delete_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_delete_record — Borra un registro en una base dBase

### Descripción

function dbase_delete_record(resource `$database`, int `$number`): bool

dbase_delete_record() marca el registro `record` para el borrado, en la base `dbase_identifier`.

> Nota:

> Para borrar realmente el registro de la base de datos, se debe llamar a la función dbase_pack().

### Parámetros

`database`

  El recurso de base de datos, devuelto por dbase_open() o dbase_create().

`number`

  Un entero comprendido entre 1 y el número máximo de registros en la base de datos (tal como devuelto por la función dbase_numrecords()).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL dbase 7.0.0 | `database` es ahora un resource en lugar de un int.

### Ver también

- dbase_add_record() - Añade un registro en una base de datos dBase
- dbase_replace_record() - Reemplaza un registro en una base dBase

# dbase_get_header_info

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_header_info — Recupera información de encabezado de una base de datos dBase

### Descripción

function dbase_get_header_info(resource `$database`): array

dbase_get_header_info() devuelve información sobre la estructura de las columnas de la base de datos referenciada por el recurso `database`.

### Parámetros

`database`

  El recurso de base de datos, devuelto por dbase_open() o dbase_create().

### Valores devueltos

Un array indexado con una entrada para cada columna de la base de datos. El índice del array comienza en 0.

Cada elemento del array contiene un array asociativo que contiene la información sobre las columnas, como se describe aquí:

name
  El nombre de la columna
type
  El nombre legible del tipo de la columna (i.e. date, boolean, etc.) Los tipos de campos soportados están enumerados en la sección de introducción.
length
  El número de bytes que puede contener esta columna
precision
  El número de decimales para la columna
format
  Un formato printf() sugerido para la columna
offset
  La posición de la columna desde el inicio de la línea

Si la información de encabezado de la base de datos no puede ser leída, `false` es devuelto.

### Historial de cambios

Versión | Descripción
--- | ---
PECL dbase 7.0.0 | `database` es ahora un resource en lugar de un int.

### Ejemplos

Ejemplo #1 Muestra la información de encabezado para un fichero de base de datos dBase

    <?php
    // Ruta hacia el fichero dBase
    $db_path = "/tmp/test.dbf";

    // Abre el fichero dBase
    $dbh = dbase_open($db_path, 0)
    or die("¡Error! Imposible abrir el fichero dBase '$db_path'.");

    // Recuperación de la información de las columnas
    $column_info = dbase_get_header_info($dbh);

    // Muestra la información
    print_r($column_info);
    ?>

# dbase_get_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_record — Lee un registro en una base dBase

### Descripción

function dbase_get_record(resource `$database`, int `$number`): array

dbase_get_record() devuelve los datos del registro `record` en un array.

### Parámetros

`database`

  El recurso de la base de datos, devuelto por dbase_open() o dbase_create().

`number`

  El índice del registro entre `1` y `dbase_numrecords($dbase_identifier)`.

### Valores devueltos

Un array indexado con el registro. Este array incluye asimismo una clave asociada llamada `deleted` que se define a 1 si el registro ha sido marcado para eliminación (ver dbase_delete_record()).

Cada campo se convierte al tipo PHP apropiado, excepto:

- Las fechas se mantienen como cadenas.
- Los valores DateTime se convierten en cadenas.
- Los enteros fuera del rango `PHP_INT_MIN`..`PHP_INT_MAX` se devuelven como cadenas.
- Antes de dbase 7.0.0, los booleanos (`L`) se convertían en `1` o `0`.

En caso de error, dbase_get_record() devuelve `false`.

### Historial de cambios

Versión | Descripción
--- | ---
PECL dbase 7.0.0 | `database` es ahora un resource en lugar de un int.

### Ver también

- dbase_get_record_with_names() - Lee un registro en una base dBase, en forma de array asociativo

# dbase_get_record_with_names

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_record_with_names — Lee un registro en una base dBase, en forma de array asociativo

### Descripción

function dbase_get_record_with_names(resource `$database`, int `$number`): array

Recupera un registro de una base de datos dBase como un array asociativo.

### Parámetros

`database`

  El recurso de base de datos, devuelto por dbase_open() o dbase_create().

`number`

  El índice del registro entre `1` y `dbase_numrecords($dbase_identifier)`.

### Valores devueltos

El registro, en forma de array asociativo. Esto incluye también una clave llamada `deleted` que se define a 1 si el registro ha sido marcado para eliminación (ver la función dbase_delete_record()). Por consiguiente, no es posible recuperar el valor de un campo llamado `deleted` con esta función.

Cada campo se convierte al tipo PHP apropiado, excepto:

- Las fechas se mantienen como cadenas.
- Los valores DateTime se convierten en cadenas.
- Los enteros fuera del rango `PHP_INT_MIN`..`PHP_INT_MAX` se devuelven como cadenas.
- Antes de dbase 7.0.0, los booleanos (`L`) se convertían en `1` o `0`.

En caso de error, dbase_get_record_with_names() devuelve `false`.

### Historial de cambios

Versión | Descripción
--- | ---
PECl dbase 7.0.0 | `database` es ahora un resource en lugar de un int.

### Ejemplos

Ejemplo #1 Lista todos los miembros registrados en la base de datos

    <?php
    // Apertura en modo solo lectura
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
      $record_numbers = dbase_numrecords($db);
      for ($i = 1; $i <= $record_numbers; $i++) {
        $row = dbase_get_record_with_names($db, $i);
        if ($row['ismember'] == 1) {
          echo "Miembro #$i: " . trim($row['name']) . "\n";
        }
      }
    }
    ?>

### Ver también

- dbase_get_record() - Lee un registro en una base dBase

# dbase_numfields

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_numfields — Cuenta el número de campos de una base dBase

### Descripción

function dbase_numfields(resource `$database`): int

dbase_numfields() devuelve el número de campos (columnas) de la base de datos `dbase_identifier`.

> Nota:

> Los campos están numerados de 0 a `dbase_numfields($db)-1`, mientras que los registros están numerados de 1 a `dbase_numrecords($db)`.

### Parámetros

`database`

  El recurso de base de datos, devuelto por dbase_open() o dbase_create().

### Valores devueltos

El número de campos de la base de datos, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL dbase 7.0.0 | `database` es ahora un resource en lugar de un int.

### Ejemplos

Ejemplo #1 Ejemplo con dbase_numfields()

    <?php

    $rec = dbase_get_record($db, $recno);
    $nf  = dbase_numfields($db);
    for ($i = 0; $i < $nf; $i++) {
      echo $rec[$i], "\n";
    }

    ?>

### Ver también

- dbase_numrecords() - Cuenta el número de registros en una base dBase

# dbase_numrecords

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_numrecords — Cuenta el número de registros en una base dBase

### Descripción

function dbase_numrecords(resource `$database`): int

Recupera el número de registros (filas) en la base especificada.

> Nota:

> Los registros marcados como eliminados también se cuentan.

> Nota:

> Los números de campo están numerados de 0 a `dbase_numfields($db)-1`, mientras que los números de registros están numerados de 1 a `dbase_numrecords($db)`.

### Parámetros

`database`

  Un recurso de base de datos, devuelto por dbase_open() o dbase_create().

### Valores devueltos

El número de registros en la base de datos o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL dbase 7.0.0 | El parámetro `database` es ahora un resource en lugar de un int.

### Ejemplos

Ejemplo #1 Lectura de todos los registros de la base de datos

    <?php

    // Apertura en modo de solo lectura
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
        $record_numbers = dbase_numrecords($db);
        for ($i = 1; $i <= $record_numbers; $i++) {
            $record = dbase_get_record($db, $i);
            if (!$record['deleted']) {
                // hacer algo con el registro $record
            } else {
                // hacer algo con el registro eliminado $record o ignorarlo
            }
        }
    }

    ?>

### Ver también

- dbase_numfields() - Cuenta el número de campos de una base dBase

# dbase_open

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_open — Abre una base dBase

### Descripción

function dbase_open(string `$path`, int `$mode`): resource|false

dbase_open() abre una base de datos dBase con un modo de acceso dado.

> Nota: Esta función es afectada por la directiva de configuración open_basedir.

### Parámetros

`path`

  La ruta hacia la base de datos. Puede ser una ruta relativa o absoluta hacia el fichero donde dBase almacenará sus datos.

`mode`

  Un entero correspondiente al utilizado para la llamada al sistema open() (Típicamente, 0 significa solo lectura, 1 significa solo escritura, y 2 significa lectura y escritura).

  > Nota:

  > No se puede abrir un fichero dBase en modo solo escritura, ya que la función fallará al leer la información de encabezado y, por lo tanto, no se puede utilizar 1 como `mode`.

  A partir de dbase 7.0.0 `DBASE_RDONLY` y `DBASE_RDWR` pueden ser utilizados, respectivamente, para definir el `mode`.

### Valores devueltos

Devuelve un recurso de base de datos en caso de éxito, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL dbase 7.0.0 | El valor devuelto es ahora un resource en lugar de un int.

### Ejemplos

Ejemplo #1 Apertura de un fichero de base de datos dBase

    <?php

    // Apertura en modo solo lectura
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
    // lectura de datos ..

    dbase_close($db);
    }

    ?>

### Ver también

- dbase_create() - Crea una base de datos dBase
- dbase_close() - Cierra una base dBase

# dbase_pack

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_pack — Compacta una base dBase

### Descripción

function dbase_pack(resource `$database`): bool

dbase_pack() compacta la base de datos `dbase_identifier` (borrado definitivo de todos los registros marcados para el borrado utilizando la función dbase_delete_record()). Téngase en cuenta que el fichero será truncado después de una compactación exitosa (a diferencia del comando PACK de dBASE III).

### Parámetros

`database`

  El recurso database, devuelto por dbase_open() o dbase_create().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL dbase 7.0.0 | `database` es ahora un resource en lugar de un int.

### Ejemplos

Ejemplo #1 Vacía una base de datos dBase

    <?php

    // Apertura en modo lectura-escritura
    $db = dbase_open('/tmp/test.dbf', 2);

    if ($db) {
      $record_numbers = dbase_numrecords($db);
      for ($i = 1; $i <= $record_numbers; $i++) {
        dbase_delete_record($db, $i);
      }
    // Compacta la base de datos
    dbase_pack($db);
    }

    ?>

### Ver también

- dbase_delete_record() - Borra un registro en una base dBase

# dbase_replace_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_replace_record — Reemplaza un registro en una base dBase

### Descripción

function dbase_replace_record(resource `$database`, array `$data`, int `$number`): bool

Reemplaza el registro pasado en la base de datos con los datos proporcionados.

### Parámetros

`database`

  El recurso de la base de datos, devuelto por dbase_open() o dbase_create().

`data`

  Un array indexado de datos. El número de elementos debe ser igual al número de campos en la base de datos, de lo contrario la función dbase_replace_record() fallará.

  > Nota:

  > Si se utiliza dbase_get_record() para devolver el valor de este argumento, no se olvide de reinicializar la clave nombrada `deleted`.

`number`

  Un entero entre 1 y el número total de registros en la base de datos (como devuelto por la función dbase_numrecords()).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL dbase 7.0.0 | El argumento `database` es ahora una resource en lugar de un int.

### Ejemplos

Ejemplo #1 Actualización de un registro en una base de datos

    <?php

    // Apertura en modo lectura-escritura
    $db = dbase_open('/tmp/test.dbf', 2);

    if ($db) {
      // Recuperación de la antigua fila
      $row = dbase_get_record_with_names($db, 1);

      // Elimina la entrada borrada
      unset($row['deleted']);

      // Actualización de la fecha del campo con el timestamp actual
      $row['date'] = date('Ymd');

      // Reemplazar el registro
      dbase_replace_record($db, $row, 1);
      dbase_close($db);
    }

    ?>

### Notas

> Nota:

> Los resultados de los campos bool son elementos de valor de tipo int (`0` o `1`) cuando se recuperan mediante dbase_get_record() o dbase_get_record_with_names(). Si se reescriben, esto hará que el valor se convierta en `0`, por lo que se deben tomar precauciones para ajustar correctamente los valores.

### Ver también

- dbase_add_record() - Añade un registro en una base de datos dBase
- dbase_delete_record() - Borra un registro en una base dBase

## Tabla de contenidos

- dbase_add_record — Añade un registro en una base de datos dBase
- dbase_close — Cierra una base dBase
- dbase_create — Crea una base de datos dBase
- dbase_delete_record — Borra un registro en una base dBase
- dbase_get_header_info — Recupera información de encabezado de una base de datos dBase
- dbase_get_record — Lee un registro en una base dBase
- dbase_get_record_with_names — Lee un registro en una base dBase, en forma de array asociativo
- dbase_numfields — Cuenta el número de campos de una base dBase
- dbase_numrecords — Cuenta el número de registros en una base dBase
- dbase_open — Abre una base dBase
- dbase_pack — Compacta una base dBase
- dbase_replace_record — Reemplaza un registro en una base dBase

- Instalación/Configuración
  - Instalación
  - Tipos de recursos
- Constantes predefinidas
- Funciones dBase
  - dbase_add_record — Añade un registro en una base de datos dBase
  - dbase_close — Cierra una base dBase
  - dbase_create — Crea una base de datos dBase
  - dbase_delete_record — Borra un registro en una base dBase
  - dbase_get_header_info — Recupera información de encabezado de una base de datos dBase
  - dbase_get_record — Lee un registro en una base dBase
  - dbase_get_record_with_names — Lee un registro en una base dBase, en forma de array asociativo
  - dbase_numfields — Cuenta el número de campos de una base dBase
  - dbase_numrecords — Cuenta el número de registros en una base dBase
  - dbase_open — Abre una base dBase
  - dbase_pack — Compacta una base dBase
  - dbase_replace_record — Reemplaza un registro en una base dBase

# Firebird/InterBase

# Introducción

Advertencia

Esta extensión es considerada muerta y no mantenida. Sin embargo, el código fuente de esta extensión sigue disponible en el GIT de PECL: » https://github.com/php/pecl-database-interbase.

Firebird es una base de datos relacional que ofrece la mayoría de las funcionalidades descritas en la norma ISO SQL-2003, que funciona en entornos Linux, Windows, y la mayoría de los sistemas Unix. Firebird ofrece una excelente simultaneidad, alto rendimiento y un lenguaje eficiente para la escritura de procedimientos almacenados y disparadores. Se utiliza en sistemas de producción desde 1981.

Interbase es el nombre de la variante comercial de esta base de datos creada por Embarcadero/Inprise. Para más información sobre Interbase, vaya a » http://www.embarcadero.com/products/interbase.

Firebird es un proyecto comercialmente independiente (fundación) de programadores C++, asesores técnicos, que apoyan el desarrollo y aseguran la compatibilidad multiplataforma de la base de datos relacional basada en el código fuente ofrecido por Inprise Corp. (ahora conocido como Embarcadero) bajo la licencia "InterBase Public License v.1.0 el 25 de julio de 2000". Para más información sobre Firebird, vaya a » http://www.firebirdsql.org/.

> Nota: Esta extensión ha sido movida al módulo » PECL y no será integrada en PHP a partir de PHP 7.4.0 Esta extensión soporta Interbase versión 6 y posteriores, así como Firebird versión 2 y posteriores.

# Instalación/Configuración

## Tabla de contenidos

- Instalación
- Configuración en tiempo de ejecución

## Instalación

Esta extensión ha sido movida al módulo » PECL y no será integrada en PHP a partir de PHP 7.4.0

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://github.com/FirebirdSQL/php-firebird.

Para activar el soporte de Firebird/InterBase, es necesario compilar PHP con la opción --with-interbase[=DIR], donde DIR es el directorio de instalación de Firebird/InterBase (que por omisión es /usr).

> Nota: Nota para usuarios Win32/Win64
> Para hacer funcionar esta extensión, algunas bibliotecas DLL deben estar disponibles a través del PATH del sistema Windows. Lea la F.A.Q titulada "Cómo agregar mi carpeta PHP a mi PATH de Windows" para más información. Copiar las bibliotecas DLL desde la carpeta PHP a la carpeta del sistema de Windows también funciona (ya que la carpeta del sistema está por defecto en el PATH del sistema), pero este método no es recomendado. Esta extensión requiere que los siguientes archivos estén en el PATH: fbclient.dll,gds32.dll

> Si se instala un servidor Firebird/InterBase en la misma máquina que la que ejecuta PHP, ya se tendrá esta biblioteca y fbclient.dll,gds32.dll (gds32.dll se genera desde el instalador) debería estar ya en su PATH.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración iBase
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
ibase.allow_persistent | "1" | `INI_SYSTEM` |
ibase.max_persistent | "-1" | `INI_SYSTEM` |
ibase.max_links | "-1" | `INI_SYSTEM` |
ibase.default_db | NULL | `INI_SYSTEM` |
ibase.default_user | NULL | `INI_ALL` |
ibase.default_password | NULL | `INI_ALL` |
ibase.default_charset | NULL | `INI_ALL` |
ibase.timestampformat | "%Y-%m-%d %H:%M:%S" | `INI_ALL` |
ibase.dateformat | "%Y-%m-%d" | `INI_ALL` |
ibase.timeformat | "%H:%M:%S" | `INI_ALL` |

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`ibase.allow_persistent` bool
  Acepta o no las conexiones persistentes a Firebird/Interbase.
`ibase.max_persistent` int
  El número máximo de conexiones persistentes Firebird/Interbase por proceso. Las nuevas conexiones con ibase_pconnect() no serán persistentes si se alcanza este número máximo.
`ibase.max_links` int
  El número máximo de conexiones Firebird/Interbase por proceso, incluyendo las conexiones persistentes.
`ibase.default_db` string
  El nombre de la base de datos por defecto cuando ibase_[p]connect() es llamado sin una base de datos específica. Si este valor está definido y el modo seguro SQL está activado, no se permitirá la conexión a otras bases de datos que no sean esta.
`ibase.default_user` string
  El nombre de usuario utilizado al conectar a la base de datos cuando no se especifica ninguno.
`ibase.default_password` string
  La contraseña utilizada al conectar a la base de datos cuando no se especifica ninguna.
`ibase.default_charset` string
  El conjunto de caracteres utilizado al conectar a la base de datos cuando no se especifica ninguno.
`ibase.timestampformat` string
`ibase.dateformat` string
`ibase.timeformat` string
  Estas directivas se utilizan para definir los formatos de fechas y horas que serán utilizados cuando las fechas/horas sean devueltas de un conjunto de resultados, o cuando se procesen argumentos en parámetros de fechas/horas.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

Las constantes siguientes pueden ser pasadas a ibase_trans() para especificar el comportamiento de las transacciones.

Constantes Firebird/InterBase
Constante | Descripción
--- | ---
IBASE_DEFAULT | Define el comportamiento por omisión. Este comportamiento es determinado por la biblioteca cliente, que es definida como IBASE_WRITE|IBASE_CONCURRENCY|IBASE_WAIT en la mayoría de los casos.
IBASE_READ | Inicia una transacción en modo de solo lectura
IBASE_WRITE | Inicia una transacción en modo de lectura / escritura
IBASE_CONSISTENCY | Inicia una transacción con el nivel de aislamiento definido a 'consistency', lo que significa que la transacción actual no puede leer desde tablas que han sido modificadas por otras transacciones.
IBASE_CONCURRENCY | Inicia una transacción con el nivel de aislamiento definido a 'concurrency' (o 'snapshot'), lo que significa que la transacción puede acceder a todas las tablas, pero no puede ver las modificaciones realizadas por otras transacciones una vez que la transacción ha comenzado.
IBASE_COMMITTED | Inicia una transacción con el nivel de aislamiento definido a 'read committed'. Este flag debe ser asociado con la constante `IBASE_REC_VERSION` o la constante `IBASE_REC_NO_VERSION`. Este nivel de aislamiento permite acceder a las modificaciones realizadas después del inicio de la transacción. Si la constante `IBASE_REC_NO_VERSION` es especificada, solo la última versión de las filas podrá ser leída. Si la constante `IBASE_REC_VERSION` es especificada, una fila puede ser leída siempre que una modificación esté pendiente en una transacción concurrente.
IBASE_WAIT | Indica que la transacción puede esperar y luego reintentar cuando aparece un conflicto.
IBASE_NOWAIT | Indica que la transacción fallará inmediatamente cuando aparece un conflicto.

Las constantes siguientes pueden ser pasadas a las funciones ibase_fetch_row(), ibase_fetch_assoc() o ibase_fetch_object() para especificar sus comportamientos.

Constantes Firebird/InterBase
Constante | Descripción
--- | ---
IBASE_FETCH_BLOBS | También disponible bajo el nombre `IBASE_TEXT` por razones de compatibilidad ascendente. Permite leer el contenido de un BLOB "inline" en lugar de recorrerlo utilizando un identificador de BLOB.
IBASE_FETCH_ARRAYS | Permite leer un array "inline". De lo contrario, los identificadores de arrays son devueltos. Los identificadores de arrays solo pueden ser pasados como argumentos a las consultas INSERT, ya que ninguna función para manejar los identificadores de arrays está actualmente disponible.
IBASE_UNIXTIME | Permite devolver los campos de fecha y hora no como strings sino como timestamps UNIX (el número de segundos desde la época UNIX, que es el 1-Jan-1970 0:00 UTC). Esto puede ser problemático si se utilizan fechas anteriores a 1970 en algunos sistemas.

Las constantes siguientes son utilizadas para pasar consultas y opciones a la API (ibase_server_info(), ibase_db_info(), ibase_backup(), ibase_restore() y ibase_maintain_db()). Consulte el manual de Firebird/InterBase para más información sobre el significado de estas opciones.

`IBASE_BKP_IGNORE_CHECKSUMS`
  Opciones para ibase_backup()
`IBASE_BKP_IGNORE_LIMBO`
  Opciones para ibase_backup()
`IBASE_BKP_METADATA_ONLY`
  Opciones para ibase_backup()
`IBASE_BKP_NO_GARBAGE_COLLECT`
  Opciones para ibase_backup()
`IBASE_BKP_OLD_DESCRIPTIONS`
  Opciones para ibase_backup()
`IBASE_BKP_NON_TRANSPORTABLE`
  Opciones para ibase_backup()
`IBASE_BKP_CONVERT`
  Opciones para ibase_backup()
`IBASE_RES_DEACTIVATE_IDX`
  Opciones para ibase_restore()
`IBASE_RES_NO_SHADOW`
  Opciones para ibase_restore()
`IBASE_RES_NO_VALIDITY`
  Opciones para ibase_restore()
`IBASE_RES_ONE_AT_A_TIME`
  Opciones para ibase_restore()
`IBASE_RES_REPLACE`
`IBASE_RES_CREATE`
  Opciones para ibase_restore()
`IBASE_RES_USE_ALL_SPACE`
  Opciones para ibase_restore()
`IBASE_PRP_PAGE_BUFFERS`
`IBASE_PRP_SWEEP_INTERVAL`
`IBASE_PRP_SHUTDOWN_DB`
`IBASE_PRP_DENY_NEW_TRANSACTIONS`
`IBASE_PRP_DENY_NEW_ATTACHMENTS`
`IBASE_PRP_RESERVE_SPACE`
`IBASE_PRP_RES_USE_FULL`
`IBASE_PRP_RES`
`IBASE_PRP_WRITE_MODE`
`IBASE_PRP_WM_ASYNC`
`IBASE_PRP_WM_SYNC`
`IBASE_PRP_ACCESS_MODE`
`IBASE_PRP_AM_READONLY`
`IBASE_PRP_AM_READWRITE`
`IBASE_PRP_SET_SQL_DIALECT`
`IBASE_PRP_ACTIVATE`
`IBASE_PRP_DB_ONLINE`
`IBASE_RPR_CHECK_DB`
`IBASE_RPR_IGNORE_CHECKSUM`
`IBASE_RPR_KILL_SHADOWS`
`IBASE_RPR_MEND_DB`
`IBASE_RPR_VALIDATE_DB`
`IBASE_RPR_FULL`
`IBASE_RPR_SWEEP_DB`
  Opciones de ibase_maintain_db()
`IBASE_STS_DATA_PAGES`
`IBASE_STS_DB_LOG`
`IBASE_STS_HDR_PAGES`
`IBASE_STS_IDX_PAGES`
`IBASE_STS_SYS_RELATIONS`
  Opciones de ibase_db_info()
`IBASE_SVC_SERVER_VERSION`
  Opciones para ibase_server_info()
`IBASE_SVC_IMPLEMENTATION`
  Opciones para ibase_server_info()
`IBASE_SVC_GET_ENV`
  Opciones para ibase_server_info()
`IBASE_SVC_GET_ENV_LOCK`
`IBASE_SVC_GET_ENV_MSG`
`IBASE_SVC_USER_DBPATH`
`IBASE_SVC_SVR_DB_INFO`
`IBASE_SVC_GET_USERS`
  Opciones para ibase_server_info()

# Funciones Firebird/InterBase

# fbird_add_user

(PHP 5, PHP 7 < 7.4.0)

fbird_add_user — Alias de ibase_add_user()

### Descripción

Esta función es un alias de: ibase_add_user().

### Ver también

- fbird_modify_user() - Alias de ibase_modify_user
- fbird_delete_user() - Alias de ibase_delete_user

# fbird_affected_rows

(PHP 5, PHP 7 < 7.4.0)

fbird_affected_rows — Alias de ibase_affected_rows()

### Descripción

Esta función es un alias de: ibase_affected_rows().

### Ver también

- fbird_query() - Alias de ibase_query
- fbird_execute() - Alias de ibase_execute

# fbird_backup

(PHP 5, PHP 7 < 7.4.0)

fbird_backup — Alias de ibase_backup()

### Descripción

Esta función es un alias de: ibase_backup().

# fbird_blob_add

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_add — Alias de ibase_blob_add()

### Descripción

Esta función es un alias de: ibase_blob_add().

### Ver también

- fbird_blob_cancel() - Cancela la creación de un blob
- fbird_blob_close() - Alias de ibase_blob_close
- fbird_blob_create() - Alias de ibase_blob_create
- fbird_blob_import() - Alias de ibase_blob_import

# fbird_blob_cancel

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_cancel — Cancela la creación de un blob

### Descripción

function fbird_blob_cancel(resource `$blob_handle`): bool

Esta función descartará un BLOB si no ha sido cerrado aún por fbird_blob_close().

### Parámetros

`blob_handle`
  Un gestor de BLOB abierto con fbird_blob_create().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- fbird_blob_close() - Alias de ibase_blob_close
- fbird_blob_create() - Alias de ibase_blob_create
- fbird_blob_import() - Alias de ibase_blob_import

# fbird_blob_close

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_close — Alias de ibase_blob_close()

### Descripción

Esta función es un alias de: ibase_blob_close().

### Ver también

- fbird_blob_create() - Alias de ibase_blob_create
- fbird_blob_cancel() - Cancela la creación de un blob
- fbird_blob_open() - Alias de ibase_blob_open
- fbird_blob_import() - Alias de ibase_blob_import

# fbird_blob_create

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_create — Alias de ibase_blob_create()

### Descripción

Esta función es un alias de: ibase_blob_create().

### Ver también

- fbird_blob_add() - Alias de ibase_blob_add
- fbird_blob_cancel() - Cancela la creación de un blob
- fbird_blob_close() - Alias de ibase_blob_close
- fbird_blob_import() - Alias de ibase_blob_import

# fbird_blob_echo

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_echo — Alias de ibase_blob_echo()

### Descripción

Esta función es un alias de: ibase_blob_echo().

### Ver también

- fbird_blob_open() - Alias de ibase_blob_open
- fbird_blob_close() - Alias de ibase_blob_close
- fbird_blob_get() - Alias de ibase_blob_get

# fbird_blob_get

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_get — Alias de ibase_blob_get()

### Descripción

Esta función es un alias de: ibase_blob_get().

### Ver también

- fbird_blob_open() - Alias de ibase_blob_open
- fbird_blob_close() - Alias de ibase_blob_close
- fbird_blob_echo() - Alias de ibase_blob_echo

# fbird_blob_import

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_import — Alias de ibase_blob_import()

### Descripción

Esta función es un alias de: ibase_blob_import().

### Ver también

- fbird_blob_add() - Alias de ibase_blob_add
- fbird_blob_cancel() - Cancela la creación de un blob
- fbird_blob_close() - Alias de ibase_blob_close
- fbird_blob_create() - Alias de ibase_blob_create

# fbird_blob_info

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_info — Alias de ibase_blob_info()

### Descripción

Esta función es un alias de: ibase_blob_info().

# fbird_blob_open

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_open — Alias de ibase_blob_open()

### Descripción

Esta función es un alias de: ibase_blob_open().

### Ver también

- fbird_blob_close() - Alias de ibase_blob_close
- fbird_blob_echo() - Alias de ibase_blob_echo
- fbird_blob_get() - Alias de ibase_blob_get

# fbird_close

(PHP 5, PHP 7 < 7.4.0)

fbird_close — Alias de ibase_close()

### Descripción

Esta función es un alias de: ibase_close().

### Ver también

- fbird_connect() - Alias de ibase_connect
- fbird_pconnect() - Alias de ibase_pconnect

# fbird_commit

(PHP 5, PHP 7 < 7.4.0)

fbird_commit — Alias de ibase_commit()

### Descripción

Esta función es un alias de: ibase_commit().

# fbird_commit_ret

(PHP 5, PHP 7 < 7.4.0)

fbird_commit_ret — Alias de ibase_commit_ret()

### Descripción

Esta función es un alias de: ibase_commit_ret().

# fbird_connect

(PHP 5, PHP 7 < 7.4.0)

fbird_connect — Alias de ibase_connect()

### Descripción

Esta función es un alias de: ibase_connect().

### Ver también

- fbird_pconnect() - Alias de ibase_pconnect
- fbird_close() - Alias de ibase_close

# fbird_db_info

(PHP 5, PHP 7 < 7.4.0)

fbird_db_info — Alias de ibase_db_info()

### Descripción

Esta función es un alias de: ibase_db_info().

# fbird_delete_user

(PHP 5, PHP 7 < 7.4.0)

fbird_delete_user — Alias de ibase_delete_user()

### Descripción

Esta función es un alias de: ibase_delete_user().

### Ver también

- fbird_add_user() - Alias de ibase_add_user
- fbird_modify_user() - Alias de ibase_modify_user

# fbird_drop_db

(PHP 5, PHP 7 < 7.4.0)

fbird_drop_db — Alias de ibase_drop_db()

### Descripción

Esta función es un alias de: ibase_drop_db().

### Ver también

- fbird_connect() - Alias de ibase_connect
- fbird_pconnect() - Alias de ibase_pconnect

# fbird_errcode

(PHP 5, PHP 7 < 7.4.0)

fbird_errcode — Alias de ibase_errcode()

### Descripción

Esta función es un alias de: ibase_errcode().

### Ver también

- fbird_errmsg() - Alias de ibase_errmsg

# fbird_errmsg

(PHP 5, PHP 7 < 7.4.0)

fbird_errmsg — Alias de ibase_errmsg()

### Descripción

Esta función es un alias de: ibase_errmsg().

### Ver también

- fbird_errcode() - Alias de ibase_errcode

# fbird_execute

(PHP 5, PHP 7 < 7.4.0)

fbird_execute — Alias de ibase_execute()

### Descripción

Esta función es un alias de: ibase_execute().

### Ver también

- fbird_query() - Alias de ibase_query

# fbird_fetch_assoc

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_assoc — Alias de ibase_fetch_assoc()

### Descripción

Esta función es un alias de: ibase_fetch_assoc().

### Ver también

- fbird_fetch_row() - Alias de ibase_fetch_row
- fbird_fetch_object() - Alias de ibase_fetch_object

# fbird_fetch_object

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_object — Alias de ibase_fetch_object()

### Descripción

Esta función es un alias de: ibase_fetch_object().

### Ver también

- fbird_fetch_row() - Alias de ibase_fetch_row
- fbird_fetch_assoc() - Alias de ibase_fetch_assoc

# fbird_fetch_row

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_row — Alias de ibase_fetch_row()

### Descripción

Esta función es un alias de: ibase_fetch_row().

### Ver también

- fbird_fetch_assoc() - Alias de ibase_fetch_assoc
- fbird_fetch_object() - Alias de ibase_fetch_object

# fbird_field_info

(PHP 5, PHP 7 < 7.4.0)

fbird_field_info — Alias de ibase_field_info()

### Descripción

Esta función es un alias de: ibase_field_info().

### Ver también

- fbird_num_fields() - Alias de ibase_num_fields

# fbird_free_event_handler

(PHP 5, PHP 7 < 7.4.0)

fbird_free_event_handler — Alias de ibase_free_event_handler()

### Descripción

Esta función es un alias de: ibase_free_event_handler().

### Ver también

- fbird_set_event_handler() - Alias de ibase_set_event_handler

# fbird_free_query

(PHP 5, PHP 7 < 7.4.0)

fbird_free_query — Alias de ibase_free_query()

### Descripción

Esta función es un alias de: ibase_free_query().

# fbird_free_result

(PHP 5, PHP 7 < 7.4.0)

fbird_free_result — Alias de ibase_free_result()

### Descripción

Esta función es un alias de: ibase_free_result().

# fbird_gen_id

(PHP 5, PHP 7 < 7.4.0)

fbird_gen_id — Alias de ibase_gen_id()

### Descripción

Esta función es un alias de: ibase_gen_id().

# fbird_maintain_db

(PHP 5, PHP 7 < 7.4.0)

fbird_maintain_db — Alias de ibase_maintain_db()

### Descripción

Esta función es un alias de: ibase_maintain_db().

# fbird_modify_user

(PHP 5, PHP 7 < 7.4.0)

fbird_modify_user — Alias de ibase_modify_user()

### Descripción

Esta función es un alias de: ibase_modify_user().

### Ver también

- fbird_add_user() - Alias de ibase_add_user
- fbird_delete_user() - Alias de ibase_delete_user

# fbird_name_result

(PHP 5, PHP 7 < 7.4.0)

fbird_name_result — Alias de ibase_name_result()

### Descripción

Esta función es un alias de: ibase_name_result().

### Ver también

- fbird_prepare() - Alias de ibase_prepare
- fbird_execute() - Alias de ibase_execute

# fbird_num_fields

(PHP 5, PHP 7 < 7.4.0)

fbird_num_fields — Alias de ibase_num_fields()

### Descripción

Esta función es un alias de: ibase_num_fields().

### Ver también

- fbird_field_info() - Alias de ibase_field_info

# fbird_num_params

(PHP 5, PHP 7 < 7.4.0)

fbird_num_params — Alias de ibase_num_params()

### Descripción

Esta función es un alias de: ibase_num_params().

### Ver también

- fbird_prepare() - Alias de ibase_prepare
- fbird_param_info() - Alias de ibase_param_info

# fbird_param_info

(PHP 5, PHP 7 < 7.4.0)

fbird_param_info — Alias de ibase_param_info()

### Descripción

Esta función es un alias de: ibase_param_info().

### Ver también

- fbird_field_info() - Alias de ibase_field_info
- fbird_num_params() - Alias de ibase_num_params

# fbird_pconnect

(PHP 5, PHP 7 < 7.4.0)

fbird_pconnect — Alias de ibase_pconnect()

### Descripción

Esta función es un alias de: ibase_pconnect().

### Ver también

- fbird_close() - Alias de ibase_close
- fbird_connect() - Alias de ibase_connect

# fbird_prepare

(PHP 5, PHP 7 < 7.4.0)

fbird_prepare — Alias de ibase_prepare()

### Descripción

Esta función es un alias de: ibase_prepare().

# fbird_query

(PHP 5, PHP 7 < 7.4.0)

fbird_query — Alias de ibase_query()

### Descripción

Esta función es un alias de: ibase_query().

### Ver también

- fbird_errmsg() - Alias de ibase_errmsg
- fbird_fetch_row() - Alias de ibase_fetch_row
- fbird_fetch_object() - Alias de ibase_fetch_object
- fbird_free_result() - Alias de ibase_free_result

# fbird_restore

(PHP 5, PHP 7 < 7.4.0)

fbird_restore — Alias de ibase_restore()

### Descripción

Esta función es un alias de: ibase_restore().

# fbird_rollback

(PHP 5, PHP 7 < 7.4.0)

fbird_rollback — Alias de ibase_rollback()

### Descripción

Esta función es un alias de: ibase_rollback().

# fbird_rollback_ret

(PHP 5, PHP 7 < 7.4.0)

fbird_rollback_ret — Alias de ibase_rollback_ret()

### Descripción

Esta función es un alias de: ibase_rollback_ret().

# fbird_server_info

(PHP 5, PHP 7 < 7.4.0)

fbird_server_info — Alias de ibase_server_info()

### Descripción

Esta función es un alias de: ibase_server_info().

# fbird_service_attach

(PHP 5, PHP 7 < 7.4.0)

fbird_service_attach — Alias de ibase_service_attach()

### Descripción

Esta función es un alias de: ibase_service_attach().

# fbird_service_detach

(PHP 5, PHP 7 < 7.4.0)

fbird_service_detach — Alias de ibase_service_detach()

### Descripción

Esta función es un alias de: ibase_service_detach().

# fbird_set_event_handler

(PHP 5, PHP 7 < 7.4.0)

fbird_set_event_handler — Alias de ibase_set_event_handler()

### Descripción

Esta función es un alias de: ibase_set_event_handler().

### Ver también

- fbird_free_event_handler() - Alias de ibase_free_event_handler
- fbird_wait_event() - Alias de ibase_wait_event

# fbird_trans

(PHP 5, PHP 7 < 7.4.0)

fbird_trans — Alias de ibase_trans()

### Descripción

Esta función es un alias de: ibase_trans().

# fbird_wait_event

(PHP 5, PHP 7 < 7.4.0)

fbird_wait_event — Alias de ibase_wait_event()

### Descripción

Esta función es un alias de: ibase_wait_event().

### Ver también

- fbird_set_event_handler() - Alias de ibase_set_event_handler
- fbird_free_event_handler() - Alias de ibase_free_event_handler

# ibase_add_user

(PHP 5, PHP 7 < 7.4.0)

ibase_add_user — Añade un usuario a una base de datos de seguridad

### Descripción

function ibase_add_user(
resource `$service_handle`,
string `$user_name`,
string `$password`,
string `$first_name` = ?,
string `$middle_name` = ?,
string `$last_name` = ?
): bool

### Parámetros

`service_handle`
  El gestor sobre el servicio del servidor de la base de datos.
`user_name`
  El identificador para el nuevo usuario de la base de datos.
`password`
  La contraseña para el nuevo usuario.
`first_name`
  El nombre para el nuevo usuario de la base de datos.
`middle_name`
  El segundo nombre para el nuevo usuario de la base de datos.
`last_name`
  El apellido para el nuevo usuario de la base de datos.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ibase_modify_user() - Modifica un usuario en una base de datos de seguridad
- ibase_delete_user() - Elimina un usuario de una base de datos de seguridad

# ibase_affected_rows

(PHP 5, PHP 7 < 7.4.0)

ibase_affected_rows — Devuelve el número de filas afectadas por la última consulta iBase

### Descripción

function ibase_affected_rows(resource `$link_identifier` = ?): int

Devuelve el número de filas que fueron afectadas por la última consulta (INSERT, UPDATE o DELETE) que fue ejecutada en el contexto de transacción especificado por `link_identifier`.

### Parámetros

`link_identifier`
  Un contexto de transacción. Si `link_identifier` es un recurso de conexión, se utiliza la transacción por omisión.

### Valores devueltos

Devuelve el número de filas, en forma de un int.

### Ver también

- ibase_query() - Ejecuta una consulta en una base iBase
- ibase_execute() - Ejecuta una consulta iBase preparada

# ibase_backup

(PHP 5, PHP 7 < 7.4.0)

ibase_backup — Inicia una tarea de respaldo en el gestor de servicios y devuelve inmediatamente

### Descripción

function ibase_backup(
resource `$service_handle`,
string `$source_db`,
string `$dest_file`,
int `$options` = 0,
bool `$verbose` = `false`
): mixed

Esta función transmite los argumentos al servidor de base de datos (remoto). Allí, comienza un nuevo proceso de respaldo. Por consiguiente, no se obtendrá ninguna respuesta.

### Parámetros

`service_handle`
  Una conexión al servidor de base de datos creada previamente.
`source_db`
  La ruta absoluta hacia la base de datos en el servidor de base de datos. También se puede utilizar un alias de base de datos.
`dest_file`
  La ruta absoluta hacia el fichero de respaldo en el servidor de base de datos.
`options`

  Opciones adicionales a transmitir al servidor de base de datos para el respaldo. El parámetro `options` puede ser una combinación de las siguientes constantes: `IBASE_BKP_IGNORE_CHECKSUMS`, `IBASE_BKP_IGNORE_LIMBO`, `IBASE_BKP_METADATA_ONLY`, `IBASE_BKP_NO_GARBAGE_COLLECT`, `IBASE_BKP_OLD_DESCRIPTIONS`, `IBASE_BKP_NON_TRANSPORTABLE` o `IBASE_BKP_CONVERT`. Leer la sección sobre Constantes predefinidas para más información.

`verbose`
  Dado que el proceso de respaldo se realiza en el servidor de base de datos, no se tiene ninguna posibilidad de obtener su salida. Este argumento es inútil.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

Dado que el proceso de respaldo se realiza en el servidor (remoto), esta función solo transmite los argumentos. Mientras los argumentos sean legales, no se obtendrá `false`.

### Ejemplos

Ejemplo #1 Ejemplo con ibase_backup()

    <?php

    // Adjuntar al servidor por dirección IP y puerto.
    $service = ibase_service_attach ('10.1.11.200/3050', 'sysdba', 'masterkey');

    // Iniciar el proceso de respaldo en el servidor de base de datos
    // Respaldar la base de datos employee utilizando la ruta completa hacia /srv/backup/employees.fbk
    // No utiliza argumentos especiales
    ibase_backup($service, '/srv/firebird/employees.fdb', '/srv/backup/employees.fbk');

    // Liberar la conexión adjunta
    ibase_service_detach ($service);
    ?>

Ejemplo #2 Ejemplo de ibase_backup() con argumentos

    <?php

    // Adjuntar al servidor por nombre y puerto por defecto
    $service = ibase_service_attach ('fb-server.contoso.local', 'sysdba', 'masterkey');

    // Iniciar el proceso de respaldo en el servidor de base de datos
    // Respaldar la base de datos employee utilizando un alias hacia /srv/backup/employees.fbk.
    // Respaldar solo los metadatos. No crear un respaldo transportable.
    ibase_backup($service, 'employees.fdb', '/srv/backup/employees.fbk', IBASE_BKP_METADATA_ONLY | IBASE_BKP_NON_TRANSPORTABLE);

    // Liberar la conexión adjunta
    ibase_service_detach ($service);
    ?>

### Ver también

- ibase_restore() - Inicia una tarea de restauración en el gestor de servicios y devuelve inmediatamente

# ibase_blob_add

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_add — Añade datos a un BLOB iBase recién creado

### Descripción

function ibase_blob_add(resource `$blob_handle`, string `$data`): void

ibase_blob_add() añade los datos `data` al BLOB `blob_handle`, creado con ibase_blob_create().

### Parámetros

`blob_handle`
  Un recurso blob, abierto con la función ibase_blob_create().
`data`
  Los datos a añadir.

### Valores devueltos

No se retorna ningún valor.

### Ver también

- ibase_blob_cancel() - Cancela la creación de un BLOB iBase
- ibase_blob_close() - Cierra un BLOB iBase
- ibase_blob_create() - Crea un BLOB iBase para añadir datos
- ibase_blob_import() - Crea un BLOB iBase, copia un fichero y lo cierra

# ibase_blob_cancel

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_cancel — Cancela la creación de un BLOB iBase

### Descripción

function ibase_blob_cancel(resource `$blob_handle`): bool

ibase_blob_cancel() cancela la creación del BLOB `blob_handle`, creado por ibase_blob_create() si no ha sido cerrado aún con ibase_blob_close().

### Parámetros

`blob_handle`
  Un recurso blob, abierto con la función ibase_blob_create().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ibase_blob_close() - Cierra un BLOB iBase
- ibase_blob_create() - Crea un BLOB iBase para añadir datos
- ibase_blob_import() - Crea un BLOB iBase, copia un fichero y lo cierra

# ibase_blob_close

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_close — Cierra un BLOB iBase

### Descripción

function ibase_blob_close(resource `$blob_handle`): mixed

ibase_blob_close() cierra el BLOB `blob_handle`, abierto en lectura con ibase_open_blob() o en escritura con ibase_blob_create().

### Parámetros

`blob_handle`
  Un recurso blob, abierto con la función ibase_blob_create() o la función ibase_blob_open().

### Valores devueltos

Si el BLOB fue leído, ibase_blob_close() devuelve `true` en caso de éxito, si estaba siendo modificado, ibase_blob_close() devuelve un string que contiene el identificador del BLOB que le fue asignado por la base de datos. En caso de fallo, esta función devolverá `false`.

### Ver también

- ibase_blob_cancel() - Cancela la creación de un BLOB iBase
- ibase_blob_open() - Abre un BLOB iBase para recuperar partes de datos

# ibase_blob_create

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_create — Crea un BLOB iBase para añadir datos

### Descripción

function ibase_blob_create(resource `$link_identifier` = `null`): resource|false

ibase_blob_create() crea un nuevo BLOB para llenar con datos, en la conexión InterBase `link_identifier`.

### Parámetros

`link_identifier`
  Un identificador de conexión a InterBase. Si se omite, se utilizará la última conexión abierta.

### Valores devueltos

Devuelve un identificador de BLOB para usar con ibase_blob_add() o `false` si ocurre un error.

### Ver también

- ibase_blob_add() - Añade datos a un BLOB iBase recién creado
- ibase_blob_cancel() - Cancela la creación de un BLOB iBase
- ibase_blob_close() - Cierra un BLOB iBase
- ibase_blob_import() - Crea un BLOB iBase, copia un fichero y lo cierra

# ibase_blob_echo

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_echo — Muestra el contenido de un BLOB iBase en el navegador

### Descripción

function ibase_blob_echo(string `$blob_id`): bool
function ibase_blob_echo(resource `$link_identifier`, string `$blob_id`): bool

ibase_blob_echo() abre el BLOB `blob_id` en lectura y envía su contenido directamente a la salida estándar (el navegador en la mayoría de los casos).

### Parámetros

`link_identifier`
  Un identificador de conexión a InterBase. Si se omite, se utilizará la última conexión abierta.
`blob_id`

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ibase_blob_open() - Abre un BLOB iBase para recuperar partes de datos
- ibase_blob_close() - Cierra un BLOB iBase
- ibase_blob_get() - Lee len bytes de datos en un BLOB iBase abierto

# ibase_blob_get

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_get — Lee `len` bytes de datos en un BLOB iBase abierto

### Descripción

function ibase_blob_get(resource `$blob_handle`, int `$len`): string

ibase_blob_get() devuelve como máximo `len` bytes del BLOB `blob_handle` que ha sido abierto en lectura por ibase_blob_open().

> Nota: No es posible leer en un BLOB abierto en escritura por ibase_blob_create().

### Parámetros

`blob_handle`
  Un recurso blob, abierto con la función ibase_blob_open().
`len`
  El tamaño de los datos devueltos.

### Valores devueltos

Devuelve como máximo, `len` bytes del BLOB, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con ibase_blob_get()

    <?php
    $result    = ibase_query("SELECT blob_value FROM table");
    $data      = ibase_fetch_object($result);
    $blob_data = ibase_blob_info($data->BLOB_VALUE);
    $blob_hndl = ibase_blob_open($data->BLOB_VALUE);
    echo         ibase_blob_get($blob_hndl, $blob_data[0]);
    ?>

Este ejemplo no hace más que un `ibase_blob_echo( $data->BLOB_VALUE )`, pero muestra cómo recuperar la información en una $variable para manipularla como se desee.

### Ver también

- ibase_blob_open() - Abre un BLOB iBase para recuperar partes de datos
- ibase_blob_close() - Cierra un BLOB iBase
- ibase_blob_echo() - Muestra el contenido de un BLOB iBase en el navegador

# ibase_blob_import

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_import — Crea un BLOB iBase, copia un fichero y lo cierra

### Descripción

function ibase_blob_import(resource `$link_identifier`, resource `$file_handle`): string
function ibase_blob_import(resource `$file_handle`): string

ibase_blob_import() crea un nuevo BLOB en la conexión iBase `link_identifier`, copia el fichero `file_handle` en su totalidad, lo cierra y devuelve el identificador asignado

### Parámetros

`link_identifier`
  Un identificador de conexión a InterBase. Si se omite, se utilizará la última conexión abierta.
`file_handle`
  El recurso de fichero, devuelto por la función fopen().

### Valores devueltos

Devuelve el identificador del BLOB en caso de éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con ibase_blob_import()

    <?php
    $dbh = ibase_connect($host, $username, $password);
    $filename = '/tmp/bar';

    $fd = fopen($filename, 'r');
    if ($fd) {

        $blob = ibase_blob_import($dbh, $fd);
        fclose($fd);

        if (!is_string($blob)) {
            // fallo en la importación
        } else {
            $query = "INSERT INTO foo (name, data) VALUES ('$filename', ?)";
            $prepared = ibase_prepare($dbh, $query);
            if (!ibase_execute($prepared, $blob)) {
                // fallo en la inserción del registro
            }
        }
    } else {
        // imposible abrir el fichero
    }
    ?>

### Ver también

- ibase_blob_add() - Añade datos a un BLOB iBase recién creado
- ibase_blob_cancel() - Cancela la creación de un BLOB iBase
- ibase_blob_close() - Cierra un BLOB iBase
- ibase_blob_create() - Crea un BLOB iBase para añadir datos

# ibase_blob_info

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_info — Devuelve el tamaño de un BLOB iBase y otra información útil

### Descripción

function ibase_blob_info(resource `$link_identifier`, string `$blob_id`): array
function ibase_blob_info(string `$blob_id`): array

Devuelve el tamaño de un BLOB iBase y otra información útil.

### Parámetros

`link_identifier`
  Un identificador de conexión a InterBase. Si se omite, se utilizará la última conexión abierta.
`blob_id`
  El identificador del BLOB.

### Valores devueltos

Devuelve un array que contiene información sobre el BLOB `blob_id`. La información incluye el tamaño del BLOB, el número de segmentos que contiene, el tamaño del segmento más grande y si se trata de un BLOB stream o segmentado.

# ibase_blob_open

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_open — Abre un BLOB iBase para recuperar partes de datos

### Descripción

function ibase_blob_open(resource `$link_identifier`, string `$blob_id`): resource|false
function ibase_blob_open(string `$blob_id`): resource|false

Abre un BLOB iBase para recuperar partes de datos.

### Parámetros

`link_identifier`
  Un identificador de conexión a InterBase. Si se omite, se utilizará la última conexión abierta.
`blob_id`
  El identificador del BLOB.

### Valores devueltos

Devuelve un recurso BLOB para su uso con la función ibase_blob_get() o `false` si ocurre un error.

### Ver también

- ibase_blob_close() - Cierra un BLOB iBase
- ibase_blob_echo() - Muestra el contenido de un BLOB iBase en el navegador
- ibase_blob_get() - Lee len bytes de datos en un BLOB iBase abierto

# ibase_close

(PHP 5, PHP 7 < 7.4.0)

ibase_close — Cierra una conexión a una base de datos Interbase

### Descripción

function ibase_close(resource `$connection_id` = `null`): bool

Cierra una conexión a una base de datos Interbase. Esta función toma como argumento el identificador de conexión `connection_id` devuelto por ibase_connect(). Las transacciones por omisión son validadas y las otras son anuladas.

### Parámetros

`connection_id`
  Un identificador de conexión a InterBase, devuelto por la función ibase_connect(). Si es omitido, la última conexión abierta será utilizada.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ibase_connect() - Abre una conexión a una base de datos
- ibase_pconnect() - Abre una conexión persistente a una base de datos InterBase

# ibase_commit

(PHP 5, PHP 7 < 7.4.0)

ibase_commit — Valida una transacción iBase

### Descripción

function ibase_commit(resource `$link_or_trans_identifier` = `null`): bool

Valida una transacción iBase.

### Parámetros

`link_or_trans_identifier`
  Llamada sin argumento, valida la transacción por omisión de la conexión por omisión. Si el argumento `link_or_trans_identifier` es un identificador de conexión, su transacción por omisión es validada. Si el argumento `link_or_trans_identifier` es un identificador de transacción, esta será validada. El contexto de la transacción será retenido y, por lo tanto, las consultas ejecutadas en esta transacción no serán invalidadas.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# ibase_commit_ret

(PHP 5, PHP 7 < 7.4.0)

ibase_commit_ret — Valida una transacción iBase sin cerrarla

### Descripción

function ibase_commit_ret(resource `$link_or_trans_identifier` = `null`): bool

Valida una transacción iBase sin cerrarla.

### Parámetros

`link_or_trans_identifier`
  Llamada sin argumento, valida la transacción por omisión de la conexión por omisión. Si el argumento `link_or_trans_identifier` es un identificador de conexión, su transacción por omisión es validada. Si el argumento `link_or_trans_identifier` es un identificador de transacción, esta será validada. El contexto de la transacción será retenido y, por lo tanto, las consultas ejecutadas en esta transacción no serán invalidadas.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# ibase_connect

(PHP 5, PHP 7 < 7.4.0)

ibase_connect — Abre una conexión a una base de datos

### Descripción

function ibase_connect(
string `$database` = ?,
string `$username` = ?,
string `$password` = ?,
string `$charset` = ?,
int `$buffers` = ?,
int `$dialect` = ?,
string `$role` = ?,
int `$sync` = ?
): resource

Abre una conexión a una base de datos Firebird/InterBase.

Si se realiza una segunda llamada con ibase_connect(), pasando los mismos argumentos, no se abrirá una nueva conexión, sino que se devolverá la conexión ya abierta. La conexión se cerrará cuando el script termine, a menos que se cierre explícitamente con ibase_close(), durante el script.

### Parámetros

`database`
  `database` debe ser una ruta válida hasta un fichero de base de datos en el servidor en el cual reside. Si el servidor es remoto, debe ser prefijado con un nombre de host 'hostname:' (TCP/IP), 'hostname/port:' (TCP/IP con un servidor interbase en un puerto TCP personalizado), '//hostname/' (NetBEUI) según el protocolo de comunicación utilizado.
`username`
  El nombre de usuario. Puede ser definido con la directiva `ibase.default_user` del fichero php.ini.
`password`
  La contraseña correspondiente al usuario `username`. Puede ser definida con la directiva `ibase.default_password` del fichero php.ini.
`charset`
  `charset` es el juego de caracteres por defecto para la base de datos.
`buffers`
  `buffers` es el número de buffers de base a asignar para la caché del servidor. Si se pasa a 0 o se omite, el servidor lo elegirá por sí mismo.
`dialect`
  `dialect` selecciona el dialecto SQL para las consultas ejecutadas con esta conexión y, por defecto, utiliza el mejor dialecto disponible.
`role`
  Funciona solo con InterBase 5 y superiores.
`sync`

### Valores devueltos

Devuelve un identificador de conexión Firebird/InterBase en caso de éxito, o `false` si ocurre un error.

### Errores/Excepciones

Si se encuentran errores como `"arithmetic exception, numeric overflow, or string truncation. Cannot transliterate character between character sets"` (esto ocurre cuando se intenta utilizar algunos caracteres acentuados) al utilizar ibase_connect() y después ibase_query(), se debe especificar un juego de caracteres correcto (i.e. `ISO8859_1` o su juego de caracteres actual).

### Ejemplos

Ejemplo #1 Ejemplo con ibase_connect()

    <?php
    $host = 'localhost:/path/to/your.gdb';

    $dbh = ibase_connect($host, $username, $password);
    $stmt = 'SELECT * FROM tblname';
    $sth = ibase_query($dbh, $stmt);
    while ($row = ibase_fetch_object($sth)) {
        echo $row->email, "\n";
    }
    ibase_free_result($sth);
    ibase_close($dbh);
    ?>

### Ver también

- ibase_pconnect() - Abre una conexión persistente a una base de datos InterBase
- ibase_close() - Cierra una conexión a una base de datos Interbase

# ibase_db_info

(PHP 5, PHP 7 < 7.4.0)

ibase_db_info — Solicita estadísticas sobre una base de datos Interbase

### Descripción

function ibase_db_info(
resource `$service_handle`,
string `$db`,
int `$action`,
int `$argumento` = 0
): string
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

# ibase_delete_user

(PHP 5, PHP 7 < 7.4.0)

ibase_delete_user — Elimina un usuario de una base de datos de seguridad

### Descripción

function ibase_delete_user(resource `$service_handle`, string `$user_name`): bool

### Parámetros

`service_handle`
  El gestor sobre el servicio del servidor de la base de datos.
`user_name`
  El identificador del usuario que debe ser eliminado de la base de datos.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ibase_add_user() - Añade un usuario a una base de datos de seguridad
- ibase_modify_user() - Modifica un usuario en una base de datos de seguridad

# ibase_drop_db

(PHP 5, PHP 7 < 7.4.0)

ibase_drop_db — Elimina una base de datos iBase

### Descripción

function ibase_drop_db(resource `$connection` = `null`): bool

ibase_drop_db() elimina una base de datos que ha sido abierta por ibase_connect() o ibase_pconnect(). La base de datos es cerrada y eliminada del servidor.

### Parámetros

`connection`
  Un identificador de conexión a InterBase. Si se omite, se utilizará la última conexión abierta.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ibase_connect() - Abre una conexión a una base de datos
- ibase_pconnect() - Abre una conexión persistente a una base de datos InterBase

# ibase_errcode

(PHP 5, PHP 7 < 7.4.0)

ibase_errcode — Devuelve el código de error iBase

### Descripción

function ibase_errcode(): int

Devuelve el código de error resultante de la llamada más reciente a una función InterBase.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el código de error, en forma de un int, o `false` si no ha ocurrido ningún error.

### Ver también

- ibase_errmsg() - Devuelve un mensaje de error

# ibase_errmsg

(PHP 5, PHP 7 < 7.4.0)

ibase_errmsg — Devuelve un mensaje de error

### Descripción

function ibase_errmsg(): string

Devuelve una string que contiene los mensajes de error.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el mensaje de error, en forma de string, o false si no ha ocurrido ningún error.

### Ver también

- ibase_errcode() - Devuelve el código de error iBase

# ibase_execute

(PHP 5, PHP 7 < 7.4.0)

ibase_execute — Ejecuta una consulta iBase preparada

### Descripción

function ibase_execute(resource `$query`, mixed `...$values`): resource

Ejecuta una consulta iBase preparada.

ibase_execute() es mucho más eficiente que ibase_query(), si se realiza la misma consulta varias veces cambiando solo algunos argumentos.

### Parámetros

`query`
  Una consulta InterBase, preparada con la función ibase_prepare().
`values`

### Valores devueltos

Si la consulta emite un error, la función devolverá `false`. Si la consulta tiene éxito, y hay un conjunto de resultados (que puede estar vacío), la función devuelve un identificador de resultados. Si la consulta tiene éxito y no hay resultados, la función devuelve `true`.

> Nota: ibase_execute() devuelve el número de registros afectados por la consulta (si es mayor que 0). Para una consulta que tiene éxito pero que no devuelve ningún registro (por ejemplo, un UPDATE en un registro inexistente), ibase_execute() devolverá `true`.

### Ejemplos

Ejemplo #1 Ejemplo con ibase_execute()

    <?php

    $dbh = ibase_connect($host, $username, $password);

    $updates = array(
        1 => 'Eric',
        5 => 'Filip',
        7 => 'Larry'
    );

    $query = ibase_prepare($dbh, "UPDATE FOO SET BAR = ? WHERE BAZ = ?");

    foreach ($updates as $baz => $bar) {
        ibase_execute($query, $bar, $baz);
    }

    ?>

### Ver también

- ibase_query() - Ejecuta una consulta en una base iBase

# ibase_fetch_assoc

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_assoc — Recupera una fila del resultado de una consulta en un array asociativo

### Descripción

function ibase_fetch_assoc(resource `$result`, int `$fetch_flag` = 0): array

Recupera una fila del resultado de una consulta en un array asociativo.

ibase_fetch_assoc() recupera una fila de datos a partir de `result`. Si dos o más columnas tienen el mismo nombre de campo, la última columna tendrá precedencia. Para acceder a las otras columnas con el mismo nombre, se debe hacer con sus índices numéricos utilizando ibase_fetch_row() o utilizando alias en la consulta.

### Parámetros

`result`
  El conjunto de resultados.
`fetch_flag`
  `fetch_flag` es una combinación de las constantes `IBASE_TEXT` y `IBASE_UNIXTIME`. Pasar `IBASE_TEXT` hace que se devuelva el contenido del BLOB en lugar del ID del BLOB. Pasar `IBASE_UNIXTIME` hace que se devuelvan las fechas/horas en forma de timestamps UNIX en lugar de strings formateados.

### Valores devueltos

Devuelve un array asociativo que corresponde a la fila recuperada. Las llamadas siguientes devuelven la fila siguiente en el conjunto de resultados, o `false` si no hay más filas.

### Ver también

- ibase_fetch_row() - Lee una línea de una base Interbase
- ibase_fetch_object() - Lee una línea en una base Interbase en un objeto

# ibase_fetch_object

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_object — Lee una línea en una base Interbase en un objeto

### Descripción

function ibase_fetch_object(resource `$result_id`, int `$fetch_flag` = 0): object

Lee una línea en una base Interbase y la coloca en un pseudo objeto.

Las siguientes llamadas a la función ibase_fetch_object() devolverán la siguiente línea del conjunto de resultados.

### Parámetros

`result_id`
  Un identificador de resultado InterBase, obtenido ya sea por la función ibase_query(), ya sea por la función ibase_execute().
`fetch_flag`
  `fetch_flag` es una combinación de las constantes `IBASE_TEXT` y `IBASE_UNIXTIME`. Pasar `IBASE_TEXT` hace que se devuelva el contenido del BLOB en lugar del ID del BLOB. Pasar `IBASE_UNIXTIME` hace que se devuelvan los valores de fecha/hora en forma de timestamps UNIX en lugar de strings formateados.

### Valores devueltos

Devuelve un objeto que contiene la información de la línea, o `false` si no hay más líneas.

### Ejemplos

Ejemplo #1 Ejemplo con ibase_fetch_object()

    <?php
    $dbh = ibase_connect($host, $username, $password);
    $stmt = 'SELECT * FROM tblname';
    $sth = ibase_query($dbh, $stmt);
    while ($row = ibase_fetch_object($sth)) {
        echo $row->email . "\n";
    }
    ibase_close($dbh);
    ?>

### Ver también

- ibase_fetch_row() - Lee una línea de una base Interbase
- ibase_fetch_assoc() - Recupera una fila del resultado de una consulta en un array asociativo

# ibase_fetch_row

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_row — Lee una línea de una base Interbase

### Descripción

function ibase_fetch_row(resource `$result_identifier`, int `$fetch_flag` = 0): array

ibase_fetch_row() recupera una línea de datos desde el conjunto de resultados dado.

Las llamadas siguientes a ibase_fetch_row() devolverán la próxima línea en el resultado, o bien `false` si no hay más líneas.

### Parámetros

`result_identifier`
  Un identificador de resultado InterBase.
`fetch_flag`
  `fetch_flag` es una combinación de las constantes `IBASE_TEXT` y `IBASE_UNIXTIME`. Pasar `IBASE_TEXT` hace que se devuelva el contenido del BLOB en lugar del ID del BLOB. Pasar `IBASE_UNIXTIME` hace que se devuelvan los valores de fecha/hora en forma de timestamps UNIX en lugar de strings formateadas.

### Valores devueltos

Devuelve un array correspondiente a la línea recuperada, o `false` si no hay más líneas. Cada columna del resultado se almacena en una posición del array, comenzando en 0.

### Ver también

- ibase_fetch_assoc() - Recupera una fila del resultado de una consulta en un array asociativo
- ibase_fetch_object() - Lee una línea en una base Interbase en un objeto

# ibase_field_info

(PHP 5, PHP 7 < 7.4.0)

ibase_field_info — Lee la información sobre un campo iBase

### Descripción

function ibase_field_info(resource `$result`, int `$field_number`): array

Devuelve un array que contiene la información de un campo, después de que una consulta de tipo selección haya sido ejecutada.

### Parámetros

`result`
  Un identificador de resultado InterBase.
`field_number`
  Posición del campo.

### Valores devueltos

Devuelve un array que contiene las siguientes claves: `name`, `alias`, `relation`, `length` y `type`.

### Ejemplos

Ejemplo #1 Ejemplo con ibase_field_info()

    <?php
    $rs = ibase_query("SELECT * FROM tablename");
    $coln = ibase_num_fields($rs);
    for ($i = 0; $i < $coln; $i++) {
        $col_info = ibase_field_info($rs, $i);
        echo "nombre : ". $col_info['name']. "\n";
        echo "alias : ". $col_info['alias']. "\n";
        echo "relación : ". $col_info['relation']. "\n";
        echo "tamaño : ". $col_info['length']. "\n";
        echo "tipo : ". $col_info['type']. "\n";
    }
    ?>

### Ver también

- ibase_num_fields() - Devuelve el número de columnas en un resultado iBase

# ibase_free_event_handler

(PHP 5, PHP 7 < 7.4.0)

ibase_free_event_handler — Libera un gestor de eventos iBase

### Descripción

function ibase_free_event_handler(resource `$event`): bool

ibase_free_event_handler() anula el gestor de eventos registrado, especificado por `event`. La función de retrollamada no será más ejecutada para los eventos que debía gestionar.

### Parámetros

`event`
  Un recurso de evento, creado por la función ibase_set_event_handler().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ibase_set_event_handler() - Registra una función de retrollamada para un evento interBase

# ibase_free_query

(PHP 5, PHP 7 < 7.4.0)

ibase_free_query — Libera la memoria reservada por una consulta preparada

### Descripción

function ibase_free_query(resource `$query`): bool

Libera la memoria reservada por una consulta preparada.

### Parámetros

`query`
  Una consulta preparada con la función ibase_prepare().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# ibase_free_result

(PHP 5, PHP 7 < 7.4.0)

ibase_free_result — Libera un resultado iBase

### Descripción

function ibase_free_result(resource `$result_identifier`): bool

Libera un resultado iBase.

### Parámetros

`result_identifier`
  Un conjunto de caracteres, creado por la función ibase_query() o por la función ibase_execute().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# ibase_gen_id

(PHP 5, PHP 7 < 7.4.0)

ibase_gen_id — Incrementa el generador dado y devuelve su nuevo valor

### Descripción

function ibase_gen_id(string `$generator`, int `$increment` = 1, resource `$link_identifier` = `null`): mixed
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Valores devueltos

Devuelve un nuevo valor generado en forma de int o de string si el valor es demasiado grande.

# ibase_maintain_db

(PHP 5, PHP 7 < 7.4.0)

ibase_maintain_db — Ejecuta un comando de mantenimiento en una base de datos Interbase

### Descripción

function ibase_maintain_db(
resource `$service_handle`,
string `$db`,
int `$action`,
int `$argumento` = 0
): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# ibase_modify_user

(PHP 5, PHP 7 < 7.4.0)

ibase_modify_user — Modifica un usuario en una base de datos de seguridad

### Descripción

function ibase_modify_user(
resource `$service_handle`,
string `$user_name`,
string `$password`,
string `$first_name` = ?,
string `$middle_name` = ?,
string `$last_name` = ?
): bool

### Parámetros

`service_handle`
  El gestor sobre el servicio del servidor de base de datos.
`user_name`
  El identificador del usuario de base de datos a modificar.
`password`
  La nueva contraseña del usuario.
`first_name`
  El nuevo nombre del usuario.
`middle_name`
  El nuevo segundo nombre del usuario.
`last_name`
  El nuevo apellido del usuario.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ibase_add_user() - Añade un usuario a una base de datos de seguridad
- ibase_delete_user() - Elimina un usuario de una base de datos de seguridad

# ibase_name_result

(PHP 5, PHP 7 < 7.4.0)

ibase_name_result — Asigna un nombre a un conjunto de resultados iBase

### Descripción

function ibase_name_result(resource `$result`, string `$name`): bool

Asigna un nombre a un conjunto de resultados. Este nombre puede ser utilizado más tarde en las consultas de tipo `UPDATE|DELETE ... WHERE CURRENT OF` `name`.

### Parámetros

`result`
  Un conjunto de resultados InterBase.
`name`
  El nombre a asignar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con ibase_name_result()

    <?php
    $result = ibase_query("SELECT field1,field2 FROM table FOR UPDATE");
    ibase_name_result($result, "my_cursor");

    $updateqry = ibase_prepare("UPDATE table SET field2 = ? WHERE CURRENT OF my_cursor");

    for ($i = 0; ibase_fetch_row($result); ++$i) {
        ibase_execute($updateqry, $i);
    }
    ?>

### Ver también

- ibase_prepare() - Prepara una consulta iBase para ligar los argumentos y ejecutarla posteriormente
- ibase_execute() - Ejecuta una consulta iBase preparada

# ibase_num_fields

(PHP 5, PHP 7 < 7.4.0)

ibase_num_fields — Devuelve el número de columnas en un resultado iBase

### Descripción

function ibase_num_fields(resource `$result_id`): int

Devuelve el número de columnas en un resultado iBase.

### Parámetros

`result_id`
  Un identificador de resultado InterBase.

### Valores devueltos

Devuelve el número de campos, en forma de un int.

### Ejemplos

Ejemplo #1 Ejemplo con ibase_num_fields()

    <?php
    $rs = ibase_query("SELECT * FROM tablename");
    $coln = ibase_num_fields($rs);
    for ($i = 0; $i < $coln; $i++) {
        $col_info = ibase_field_info($rs, $i);
        echo "nombre : " . $col_info['name'] . "\n";
        echo "alias : " . $col_info['alias'] . "\n";
        echo "relación : " . $col_info['relation'] . "\n";
        echo "tamaño : " . $col_info['length'] . "\n";
        echo "tipo : " . $col_info['type'] . "\n";
    }
    ?>

### Ver también

- ibase_field_info() - Lee la información sobre un campo iBase

# ibase_num_params

(PHP 5, PHP 7 < 7.4.0)

ibase_num_params — Devuelve el número de parámetros en una consulta preparada iBase

### Descripción

function ibase_num_params(resource `$query`): int

ibase_num_params() devuelve el número de parámetros en la consulta especificada por `query`. Es el número de argumentos de sustitución que deben estar presentes al llamar a ibase_execute().

### Parámetros

`query`
  La consulta preparada.

### Valores devueltos

Devuelve el número de parámetros, en forma de un int.

### Ver también

- ibase_prepare() - Prepara una consulta iBase para ligar los argumentos y ejecutarla posteriormente
- ibase_param_info() - Devuelve información sobre un argumento en una consulta preparada iBase

# ibase_param_info

(PHP 5, PHP 7 < 7.4.0)

ibase_param_info — Devuelve información sobre un argumento en una consulta preparada iBase

### Descripción

function ibase_param_info(resource `$query`, int `$param_number`): array

Devuelve un array con información sobre un argumento después de que una consulta haya sido preparada.

### Parámetros

`query`
  Un gestor de consulta preparada InterBase.
`param_number`
  La posición del argumento.

### Valores devueltos

Devuelve un array que contiene las siguientes claves: `name`, `alias`, `relation`, `length` y `type`.

### Ver también

- ibase_field_info() - Lee la información sobre un campo iBase
- ibase_num_params() - Devuelve el número de parámetros en una consulta preparada iBase

# ibase_pconnect

(PHP 5, PHP 7 < 7.4.0)

ibase_pconnect — Abre una conexión persistente a una base de datos InterBase

### Descripción

function ibase_pconnect(
string `$database` = ?,
string `$username` = ?,
string `$password` = ?,
string `$charset` = ?,
int `$buffers` = ?,
int `$dialect` = ?,
string `$role` = ?,
int `$sync` = ?
): resource

Abre una conexión persistente a una base de datos InterBase.

ibase_pconnect() se comporta de manera similar a ibase_connect(), con dos diferencias principales.

La primera es que, al conectar, la función intentará encontrar una conexión (persistente) ya abierta. Si la encuentra, esta última será devuelta, en lugar de una nueva conexión. De lo contrario, se abrirá una nueva conexión.

La segunda es que la conexión no se cerrará al final del script, sino que permanecerá abierta para su uso posterior. (ibase_close() no cerrará una conexión abierta con ibase_pconnect()). Este tipo de enlace se denomina 'persistente'.

### Parámetros

`database`
  El argumento `database` debe ser una ruta de acceso válida al fichero de la base de datos en el servidor donde reside. Si el servidor no es local, debe estar precedido por 'hostname:' (TCP/IP), '//hostname/' (NetBEUI) o 'hostname@' (IPX/SPX), según el protocolo utilizado.
`username`
  El nombre de usuario. Puede ser definido con la directiva `ibase.default_user` del php.ini.
`password`
  La contraseña para el usuario `username`. Puede ser definida con la directiva `ibase.default_password` del php.ini.
`charset`
  `charset` es el conjunto de caracteres por omisión para la base de datos.
`buffers`
  `buffers` es el número de buffers de la base de datos que se asignarán para la caché del lado del servidor. Si este parámetro vale 0 o si se omite, el servidor elegirá este número por sí mismo.
`dialect`
  `dialect` selecciona el dialecto SQL por omisión para todas las consultas ejecutadas en la conexión, y valdrá por omisión, el más alto soportado por la biblioteca cliente. Solo funciona con InterBase 6 y superiores.
`role`
  Solo funciona con InterBase 5 y superiores.
`sync`

### Valores devueltos

Devuelve un identificador de conexión InterBase en caso de éxito, o `false` si ocurre un error.

### Ver también

- ibase_close() - Cierra una conexión a una base de datos Interbase
- ibase_connect() - Abre una conexión a una base de datos

# ibase_prepare

(PHP 5, PHP 7 < 7.4.0)

ibase_prepare — Prepara una consulta iBase para ligar los argumentos y ejecutarla posteriormente

### Descripción

function ibase_prepare(string `$query`): resource
function ibase_prepare(resource `$link_identifier`, string `$query`): resource
function ibase_prepare(resource `$link_identifier`, string `$trans`, string `$query`): resource

Prepara una consulta para ligar posteriormente los argumentos y ejecutarla (a través de la función ibase_execute()).

### Parámetros

`query`
  Una consulta InterBase.
`link_identifier`
  Un enlace identificador InterBase devuelto por ibase_connect(). Si se omite, se adopta el último enlace abierto.
`trans`
  Un gestor de transacción InterBase con el cual la consulta debe ser asociada. Si se omite, se adopta la transacción por omisión de la conexión.

### Valores devueltos

Devuelve un gestor de consulta preparada, o `false` si ocurre un error.

# ibase_query

(PHP 5, PHP 7 < 7.4.0)

ibase_query — Ejecuta una consulta en una base iBase

### Descripción

function ibase_query(resource `$link_identifier` = ?, string `$query`, int `$bind_args` = ?): resource

Ejecuta una consulta en una base iBase.

### Parámetros

`link_identifier`
  Un identificador de conexión a InterBase. Si se omite, se utilizará la última conexión abierta.
`query`
  Una consulta InterBase.
`bind_args`

### Valores devueltos

Si la consulta emite un error, la función devolverá `false`. Si la consulta se ejecuta con éxito, y hay un conjunto de resultados (incluso vacío), la función devolverá un identificador de resultado. Si la consulta se ejecuta con éxito, y no hay resultado, la función devolverá `true`.

> Nota: En las versiones 5.0.0 de PHP y siguientes, ibase_query() devuelve el número de registros afectados por las consultas `INSERT`, `UPDATE` y `DELETE`. Por razones de compatibilidad ascendente, ibase_query() devolverá `true` si la consulta tiene éxito pero no devuelve ningún registro.

### Errores/Excepciones

Si se recibe un error del tipo `"arithmetic exception, numeric overflow, or string truncation. Cannot transliterate character between character sets"` (esto ocurre cuando se intenta utilizar caracteres acentuados) con la función ibase_query(), es necesario elegir un juego de caracteres (i.e. `ISO8859_1` o su juego actual).

### Ejemplos

Ejemplo #1 Ejemplo con ibase_query()

    <?php

    $host = 'localhost:/path/to/your.gdb';

    $dbh = ibase_connect($host, $username, $password);
    $stmt = 'SELECT * FROM tblname';

    $sth = ibase_query($dbh, $stmt) or die(ibase_errmsg());

    ?>

### Ver también

- ibase_errmsg() - Devuelve un mensaje de error
- ibase_fetch_row() - Lee una línea de una base Interbase
- ibase_fetch_object() - Lee una línea en una base Interbase en un objeto
- ibase_free_result() - Libera un resultado iBase

# ibase_restore

(PHP 5, PHP 7 < 7.4.0)

ibase_restore — Inicia una tarea de restauración en el gestor de servicios y devuelve inmediatamente

### Descripción

function ibase_restore(
resource `$service_handle`,
string `$source_file`,
string `$dest_db`,
int `$options` = 0,
bool `$verbose` = `false`
): mixed

Esta función transmite los argumentos al servidor de base de datos (remoto). Allí, comienza un nuevo proceso de restauración. Por lo tanto, no se obtendrá ninguna respuesta.

### Parámetros

`service_handle`
  Una conexión al servidor de base de datos creada previamente.
`source_file`
  La ruta absoluta en el servidor donde se encuentra el fichero de respaldo.
`dest_db`
  La ruta para crear la nueva base de datos en el servidor. También se puede utilizar un alias de base de datos.
`options`

  Opciones adicionales a transmitir al servidor de base de datos para la restauración. El parámetro `options` puede ser una combinación de las siguientes constantes: `IBASE_RES_DEACTIVATE_IDX`, `IBASE_RES_NO_SHADOW`, `IBASE_RES_NO_VALIDITY`, `IBASE_RES_ONE_AT_A_TIME`, `IBASE_RES_REPLACE`, `IBASE_RES_CREATE`, `IBASE_RES_USE_ALL_SPACE`, `IBASE_PRP_PAGE_BUFFERS`, `IBASE_PRP_SWEEP_INTERVAL`, `IBASE_RES_CREATE`. Leer la sección sobre Constantes predefinidas para más información.

`verbose`
  Dado que el proceso de restauración se realiza en el servidor de base de datos, no hay posibilidad de obtener su salida. Este argumento es inútil.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

Dado que el proceso de restauración se realiza en el servidor (remoto), esta función solo transmite los argumentos. Mientras los argumentos sean legales, no se obtendrá `false`.

### Ejemplos

Ejemplo #1 Ejemplo con ibase_restore()

    <?php
    // Adjuntar al servidor por dirección IP y puerto.
    $service = ibase_service_attach ('10.1.11.200/3050', 'sysdba', 'masterkey');

    // Iniciar el proceso de restauración en el servidor de base de datos
    // Restaurar el respaldo de employee a la nueva base de datos emps.fdb
    // No utiliza argumentos especiales
    ibase_restore($service, '/srv/backup/employees.fbk', '/srv/firebird/emps.fdb');

    // Libera la conexión adjunta
    ibase_service_detach ($service);
    ?>

Ejemplo #2 Ejemplo de ibase_restore() con argumentos

    <?php

    // Adjuntar al servidor por nombre y puerto por defecto
    $service = ibase_service_attach ('fb-server.contoso.local', 'sysdba', 'masterkey');

    // Iniciar el proceso de restauración en el servidor de base de datos
    // Restaurar la base de datos employee utilizando un alias.
    // Restaurar sin índice, Reemplazar la base de datos existente.
    ibase_restore($service, '/srv/backup/employees.fbk', 'employees.fdb', IBASE_RES_DEACTIVATE_IDX | IBASE_RES_REPLACE);

    // Libera la conexión adjunta
    ibase_service_detach ($service);
    ?>

### Ver también

- ibase_backup() - Inicia una tarea de respaldo en el gestor de servicios y devuelve inmediatamente

# ibase_rollback

(PHP 5, PHP 7 < 7.4.0)

ibase_rollback — Anula una transacción interBase

### Descripción

function ibase_rollback(resource `$link_or_trans_identifier` = `null`): bool

Anula una transacción interBase.

### Parámetros

`link_or_trans_identifier`
  Cuando ibase_rollback() es llamada sin argumento, anula la transacción por omisión del enlace por omisión. Si el argumento `link_or_trans_identifier` es un identificador de conexión, la transacción por omisión de dicha conexión será anulada. Si el argumento `link_or_trans_identifier` es un identificador de transacción, esta será anulada.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# ibase_rollback_ret

(PHP 5, PHP 7 < 7.4.0)

ibase_rollback_ret — Anula una transacción sin cerrarla

### Descripción

function ibase_rollback_ret(resource `$link_or_trans_identifier` = `null`): bool

Anula una transacción sin cerrarla.

### Parámetros

`link_or_trans_identifier`
  Si ibase_rollback_ret() es llamada sin argumento, anula la transacción por omisión del enlace por omisión. Si el argumento `link_or_trans_identifier` es un identificador de conexión, la transacción por omisión de esta conexión será anulada. Si el argumento `link_or_trans_identifier` es un identificador de transacción, esta será anulada. El contexto de la transacción será retenido y, por lo tanto, las consultas ejecutadas en esta transacción no serán invalidadas.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# ibase_server_info

(PHP 5, PHP 7 < 7.4.0)

ibase_server_info — Solicita información sobre un servidor de base de datos

### Descripción

function ibase_server_info(resource `$service_handle`, int `$action`): string

### Parámetros

`service_handle`
  Una conexión al servidor de base de datos creada previamente.
`action`
  Una constante válida.

### Valores devueltos

Devuelve diferentes tipos dependiendo del contexto.

### Ejemplos

Ejemplo #1 Ejemplo con ibase_service_attach()

    <?php
        // Adjuntar al servidor Firebird remoto
        if (($service = ibase_service_attach('10.1.1.254/3050', 'sysdba', 'masterkey')) != FALSE) {

            // Adjuntado con éxito.

            // Mostrar la información
            echo "Versión del servidor: " . ibase_server_info($service, IBASE_SVC_SERVER_VERSION) . "\n";
            echo "Implementación del servidor: " . ibase_server_info($service, IBASE_SVC_IMPLEMENTATION) . "\n";
            echo "Usuarios del servidor: " . print_r(ibase_server_info($service, IBASE_SVC_GET_USERS), true) . "\n";
            echo "Directorio del servidor: " . ibase_server_info($service, IBASE_SVC_GET_ENV) . "\n";
            echo "Ruta de bloqueo del servidor: " . ibase_server_info($service, IBASE_SVC_GET_ENV_LOCK) . "\n";
            echo "Ruta de la biblioteca del servidor: " . ibase_server_info($service, IBASE_SVC_GET_ENV_MSG) . "\n";
            echo "Ruta de la base de datos del usuario: " . ibase_server_info($service, IBASE_SVC_USER_DBPATH) . "\n";
            echo "Conexiones establecidas: " . print_r(ibase_server_info($service, IBASE_SVC_SVR_DB_INFO),true) . "\n";

            // Desadjuntar del servidor (desconexión)
            ibase_service_detach($service);

        }
        else {
            // Mostrar un mensaje en caso de error
            $conn_error = ibase_errmsg();
            die($conn_error);
        }
    ?>

El ejemplo anterior mostrará:

    Versión del servidor: LI-V3.0.4.33054 Firebird 3.0
    Implementación del servidor: Firebird/Linux/AMD/Intel/x64
    Usuarios del servidor: Array
    (
        [0] => Array
            (
                [user_name] => SYSDBA
                [first_name] => Sql
                [middle_name] => Server
                [last_name] => Administrator
                [user_id] => 0
                [group_id] => 0
            )

    )

    Directorio del servidor: /etc/firebird/
    Ruta de bloqueo del servidor: /tmp/firebird/
    Ruta de la biblioteca del servidor: /usr/lib64/firebird/lib/
    Ruta de la base de datos del usuario: /var/lib/firebird/secdb/security3.fdb
    Conexiones establecidas: Array
    (
        [attachments] => 3
        [databases] => 2
        [0] => /srv/firebird/poss.fdb
        [1] => /srv/firebird/employees.fdb
    )

# ibase_service_attach

(PHP 5, PHP 7 < 7.4.0)

ibase_service_attach — Conexión al gestor de servicio

### Descripción

function ibase_service_attach(string `$host`, string `$dba_username`, string `$dba_password`): resource|false

### Parámetros

`host`
  El nombre o la dirección IP del host de la base de datos. El puerto puede ser definido añadiendo '/' y el número del puerto. Si no se especifica ningún puerto, se utilizará el puerto 3050.
`dba_username`
  El nombre de cualquier usuario válido.
`dba_password`
  La contraseña del usuario.

### Valores devueltos

Devuelve un identificador de enlace Interbase / Firebird en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con ibase_service_attach()

    <?php
        // Conectarse al servidor Firebird remoto por una dirección IP
        if (($service = ibase_service_attach('10.1.1.199', 'sysdba', 'masterkey')) != FALSE) {

            // Conectado con éxito.
            // Obtener la versión del servidor (algo como 'LI-V3.0.4.33054 Firebird 3.0')
            $server_version  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

            // Obtener la implementación del servidor (algo como 'Firebird/Linux/AMD/Intel/x64')
            $server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

            // Desconectarse del servidor
            ibase_service_detach($service);

            // Mostrar la información
            echo "Versión del servidor: " . $server_version . "<br/>";
            echo "Implementación del servidor: " . $server_implementation;
        }
        else {
            // Mostrar un mensaje en caso de error
            $conn_error = ibase_errmsg();
            die($conn_error);
        }

    ?>

Ejemplo #2 Ejemplo deibase_service_attach() utilizando la sintaxis `hostname/port`

    <?php
        // Conectarse al servidor Firebird remoto por nombre. Utiliza el puerto 3050.
        if (($service = ibase_service_attach('FB-SRV-01.contoso.local/3050', 'sysdba', 'masterkey')) != FALSE) {

            // Conectado con éxito.
            // Obtener la versión del servidor (algo como 'LI-V3.0.4.33054 Firebird 3.0')
            $server_version  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

            // Obtener la implementación del servidor (algo como 'Firebird/Linux/AMD/Intel/x64')
            $server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

            // Desconectarse del servidor
            ibase_service_detach($service);

            // Mostrar la información
            echo "Versión del servidor: " . $server_version . "<br/>";
            echo "Implementación del servidor: " . $server_implementation;
        }
        else {
            // Mostrar un mensaje en caso de error
            $conn_error = ibase_errmsg();
            die($conn_error);
        }

    ?>

### Ver también

- ibase_service_detach() - Desconexión del gestor de servicio

# ibase_service_detach

(PHP 5, PHP 7 < 7.4.0)

ibase_service_detach — Desconexión del gestor de servicio

### Descripción

function ibase_service_detach(resource `$service_handle`): bool

### Parámetros

`service_handle`
  Una conexión al servidor de base de datos creada previamente.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con ibase_service_detach()

    <?php
        // Adjuntar al servidor Firebird remoto por una dirección IP
        if (($service = ibase_service_attach('10.1.1.199', 'sysdba', 'masterkey')) != FALSE) {

            // Adjuntado con éxito.
            // Recuperar la versión del servidor (algo como 'LI-V3.0.4.33054 Firebird 3.0')
            $server_version  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

            // Recuperar la implementación del servidor (algo como 'Firebird/Linux/AMD/Intel/x64')
            $server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

            // Desconectar del servidor (desconexión)
            if(ibase_service_detach($service) == FALSE) {
                echo "Error en la desconexión del servicio.";
            }
            else {
                echo "Desconexión del servicio realizada con éxito.";
            }

        }
        else {
            // Mostrar un mensaje en caso de error
            $conn_error = ibase_errmsg();
            die($conn_error);
        }

    ?>

# ibase_set_event_handler

(PHP 5, PHP 7 < 7.4.0)

ibase_set_event_handler — Registra una función de retrollamada para un evento interBase

### Descripción

function ibase_set_event_handler(callable `$event_handler`, string `$event_name`, string `...$event_names`): resource
function ibase_set_event_handler(
resource `$connection`,
callable `$event_handler`,
string `$event_name`,
string `...$event_names`
): resource

ibase_set_event_handler() registra la función PHP `event_handler` como gestor de eventos para los eventos especificados.

### Parámetros

`event_handler`
  Función de retrollamada llamada con el nombre del evento y la conexión de recurso como argumentos cuando un evento especificado es publicado en la base de datos. La función de retrollamada `event_handler` debe devolver `false` si el gestor debe ser cancelado. Cualquier otro valor de retorno es ignorado. Esta función acepta hasta 15 argumentos de evento.
`event_name`
  El nombre del evento.
`event_names`
  15 eventos como máximo están permitidos.

### Valores devueltos

El valor devuelto es un recurso de evento. Puede ser utilizado para liberar el gestor de eventos utilizando ibase_free_event_handler().

### Ejemplos

Ejemplo #1 Ejemplo con ibase_set_event_handler()

    <?php

    function event_handler($event_name, $link)
    {
        if ($event_name == "NEW ORDER") {
            // Procesamiento del nuevo pedido
            ibase_query($link, "UPDATE orders SET status='handled'");
        } else if ($event_name == "DB_SHUTDOWN") {
            // Liberación del gestor
            return false;
        }
    }

    ibase_set_event_handler($link, "event_handler", "NEW_ORDER", "DB_SHUTDOWN");
    ?>

### Ver también

- ibase_free_event_handler() - Libera un gestor de eventos iBase
- ibase_wait_event() - Espera un evento interBase

# ibase_trans

(PHP 5, PHP 7 < 7.4.0)

ibase_trans — Prepara una transacción interBase

### Descripción

function ibase_trans(int `$trans_args` = ?, resource `$link_identifier` = ?): resource
function ibase_trans(resource `$link_identifier` = ?): resource

Prepara una transacción interBase.

> Nota: La primera llamada a ibase_trans() devolverá la transacción por omisión para la conexión actual. Todas las transacciones iniciadas por ibase_trans() serán anuladas al final de la ejecución del script si no han sido validadas o anuladas por las funciones ibase_commit() o ibase_rollback() respectivamente.

> Nota: ibase_trans() acepta varios argumentos `trans_args` y `link_identifier`. Esto permite realizar transacciones en varias conexiones a diferentes bases de datos, que serán validadas utilizando el algoritmo `2-phase`. Esto significa que se pueden actualizar varias bases de datos. Esto NO significa que se puedan utilizar varias bases de datos en una misma consulta. Si se utilizan las transacciones en varias bases de datos, se debe especificar `link_id` y `transaction_id` en las funciones ibase_query() y ibase_prepare().

### Parámetros

`trans_args`
  `trans_args` puede ser una combinación de las siguientes constantes: `IBASE_READ`, `IBASE_WRITE`, `IBASE_COMMITTED`, `IBASE_CONSISTENCY`, `IBASE_CONCURRENCY`, `IBASE_REC_VERSION`, `IBASE_REC_NO_VERSION`, `IBASE_WAIT` y `IBASE_NOWAIT`.
`link_identifier`
  Un identificador de conexión a InterBase. Si se omite, se utilizará la última conexión abierta.

### Valores devueltos

Devuelve un recurso de transacción, o `false` si ocurre un error.

# ibase_wait_event

(PHP 5, PHP 7 < 7.4.0)

ibase_wait_event — Espera un evento interBase

### Descripción

function ibase_wait_event(string `$event_name`, string `...$event_names`): string
function ibase_wait_event(resource `$connection`, string `$event_name`, string `...$event_names`): string

ibase_wait_event() suspende la ejecución del script hasta que uno de los eventos especificados sea publicado por la base de datos. El nombre del evento que ha sido publicado es entonces devuelto. Esta función acepta hasta 15 argumentos de eventos.

### Parámetros

`event_name`
  El nombre del evento.
`event_names`

### Valores devueltos

Devuelve el nombre del evento que ha sido publicado.

### Ver también

- ibase_set_event_handler() - Registra una función de retrollamada para un evento interBase
- ibase_free_event_handler() - Libera un gestor de eventos iBase

## Tabla de contenidos

- fbird_add_user — Alias de ibase_add_user
- fbird_affected_rows — Alias de ibase_affected_rows
- fbird_backup — Alias de ibase_backup
- fbird_blob_add — Alias de ibase_blob_add
- fbird_blob_cancel — Cancela la creación de un blob
- fbird_blob_close — Alias de ibase_blob_close
- fbird_blob_create — Alias de ibase_blob_create
- fbird_blob_echo — Alias de ibase_blob_echo
- fbird_blob_get — Alias de ibase_blob_get
- fbird_blob_import — Alias de ibase_blob_import
- fbird_blob_info — Alias de ibase_blob_info
- fbird_blob_open — Alias de ibase_blob_open
- fbird_close — Alias de ibase_close
- fbird_commit — Alias de ibase_commit
- fbird_commit_ret — Alias de ibase_commit_ret
- fbird_connect — Alias de ibase_connect
- fbird_db_info — Alias de ibase_db_info
- fbird_delete_user — Alias de ibase_delete_user
- fbird_drop_db — Alias de ibase_drop_db
- fbird_errcode — Alias de ibase_errcode
- fbird_errmsg — Alias de ibase_errmsg
- fbird_execute — Alias de ibase_execute
- fbird_fetch_assoc — Alias de ibase_fetch_assoc
- fbird_fetch_object — Alias de ibase_fetch_object
- fbird_fetch_row — Alias de ibase_fetch_row
- fbird_field_info — Alias de ibase_field_info
- fbird_free_event_handler — Alias de ibase_free_event_handler
- fbird_free_query — Alias de ibase_free_query
- fbird_free_result — Alias de ibase_free_result
- fbird_gen_id — Alias de ibase_gen_id
- fbird_maintain_db — Alias de ibase_maintain_db
- fbird_modify_user — Alias de ibase_modify_user
- fbird_name_result — Alias de ibase_name_result
- fbird_num_fields — Alias de ibase_num_fields
- fbird_num_params — Alias de ibase_num_params
- fbird_param_info — Alias de ibase_param_info
- fbird_pconnect — Alias de ibase_pconnect
- fbird_prepare — Alias de ibase_prepare
- fbird_query — Alias de ibase_query
- fbird_restore — Alias de ibase_restore
- fbird_rollback — Alias de ibase_rollback
- fbird_rollback_ret — Alias de ibase_rollback_ret
- fbird_server_info — Alias de ibase_server_info
- fbird_service_attach — Alias de ibase_service_attach
- fbird_service_detach — Alias de ibase_service_detach
- fbird_set_event_handler — Alias de ibase_set_event_handler
- fbird_trans — Alias de ibase_trans
- fbird_wait_event — Alias de ibase_wait_event
- ibase_add_user — Añade un usuario a una base de datos de seguridad
- ibase_affected_rows — Devuelve el número de filas afectadas por la última consulta iBase
- ibase_backup — Inicia una tarea de respaldo en el gestor de servicios y devuelve inmediatamente
- ibase_blob_add — Añade datos a un BLOB iBase recién creado
- ibase_blob_cancel — Cancela la creación de un BLOB iBase
- ibase_blob_close — Cierra un BLOB iBase
- ibase_blob_create — Crea un BLOB iBase para añadir datos
- ibase_blob_echo — Muestra el contenido de un BLOB iBase en el navegador
- ibase_blob_get — Lee len bytes de datos en un BLOB iBase abierto
- ibase_blob_import — Crea un BLOB iBase, copia un fichero y lo cierra
- ibase_blob_info — Devuelve el tamaño de un BLOB iBase y otra información útil
- ibase_blob_open — Abre un BLOB iBase para recuperar partes de datos
- ibase_close — Cierra una conexión a una base de datos Interbase
- ibase_commit — Valida una transacción iBase
- ibase_commit_ret — Valida una transacción iBase sin cerrarla
- ibase_connect — Abre una conexión a una base de datos
- ibase_db_info — Solicita estadísticas sobre una base de datos Interbase
- ibase_delete_user — Elimina un usuario de una base de datos de seguridad
- ibase_drop_db — Elimina una base de datos iBase
- ibase_errcode — Devuelve el código de error iBase
- ibase_errmsg — Devuelve un mensaje de error
- ibase_execute — Ejecuta una consulta iBase preparada
- ibase_fetch_assoc — Recupera una fila del resultado de una consulta en un array asociativo
- ibase_fetch_object — Lee una línea en una base Interbase en un objeto
- ibase_fetch_row — Lee una línea de una base Interbase
- ibase_field_info — Lee la información sobre un campo iBase
- ibase_free_event_handler — Libera un gestor de eventos iBase
- ibase_free_query — Libera la memoria reservada por una consulta preparada
- ibase_free_result — Libera un resultado iBase
- ibase_gen_id — Incrementa el generador dado y devuelve su nuevo valor
- ibase_maintain_db — Ejecuta un comando de mantenimiento en una base de datos Interbase
- ibase_modify_user — Modifica un usuario en una base de datos de seguridad
- ibase_name_result — Asigna un nombre a un conjunto de resultados iBase
- ibase_num_fields — Devuelve el número de columnas en un resultado iBase
- ibase_num_params — Devuelve el número de parámetros en una consulta preparada iBase
- ibase_param_info — Devuelve información sobre un argumento en una consulta preparada iBase
- ibase_pconnect — Abre una conexión persistente a una base de datos InterBase
- ibase_prepare — Prepara una consulta iBase para ligar los argumentos y ejecutarla posteriormente
- ibase_query — Ejecuta una consulta en una base iBase
- ibase_restore — Inicia una tarea de restauración en el gestor de servicios y devuelve inmediatamente
- ibase_rollback — Anula una transacción interBase
- ibase_rollback_ret — Anula una transacción sin cerrarla
- ibase_server_info — Solicita información sobre un servidor de base de datos
- ibase_service_attach — Conexión al gestor de servicio
- ibase_service_detach — Desconexión del gestor de servicio
- ibase_set_event_handler — Registra una función de retrollamada para un evento interBase
- ibase_trans — Prepara una transacción interBase
- ibase_wait_event — Espera un evento interBase

- Instalación/Configuración
  - Instalación
  - Configuración en tiempo de ejecución
- Constantes predefinidas
- Funciones Firebird/InterBase
  - fbird_add_user — Alias de ibase_add_user
  - fbird_affected_rows — Alias de ibase_affected_rows
  - fbird_backup — Alias de ibase_backup
  - fbird_blob_add — Alias de ibase_blob_add
  - fbird_blob_cancel — Cancela la creación de un blob
  - fbird_blob_close — Alias de ibase_blob_close
  - fbird_blob_create — Alias de ibase_blob_create
  - fbird_blob_echo — Alias de ibase_blob_echo
  - fbird_blob_get — Alias de ibase_blob_get
  - fbird_blob_import — Alias de ibase_blob_import
  - fbird_blob_info — Alias de ibase_blob_info
  - fbird_blob_open — Alias de ibase_blob_open
  - fbird_close — Alias de ibase_close
  - fbird_commit — Alias de ibase_commit
  - fbird_commit_ret — Alias de ibase_commit_ret
  - fbird_connect — Alias de ibase_connect
  - fbird_db_info — Alias de ibase_db_info
  - fbird_delete_user — Alias de ibase_delete_user
  - fbird_drop_db — Alias de ibase_drop_db
  - fbird_errcode — Alias de ibase_errcode
  - fbird_errmsg — Alias de ibase_errmsg
  - fbird_execute — Alias de ibase_execute
  - fbird_fetch_assoc — Alias de ibase_fetch_assoc
  - fbird_fetch_object — Alias de ibase_fetch_object
  - fbird_fetch_row — Alias de ibase_fetch_row
  - fbird_field_info — Alias de ibase_field_info
  - fbird_free_event_handler — Alias de ibase_free_event_handler
  - fbird_free_query — Alias de ibase_free_query
  - fbird_free_result — Alias de ibase_free_result
  - fbird_gen_id — Alias de ibase_gen_id
  - fbird_maintain_db — Alias de ibase_maintain_db
  - fbird_modify_user — Alias de ibase_modify_user
  - fbird_name_result — Alias de ibase_name_result
  - fbird_num_fields — Alias de ibase_num_fields
  - fbird_num_params — Alias de ibase_num_params
  - fbird_param_info — Alias de ibase_param_info
  - fbird_pconnect — Alias de ibase_pconnect
  - fbird_prepare — Alias de ibase_prepare
  - fbird_query — Alias de ibase_query
  - fbird_restore — Alias de ibase_restore
  - fbird_rollback — Alias de ibase_rollback
  - fbird_rollback_ret — Alias de ibase_rollback_ret
  - fbird_server_info — Alias de ibase_server_info
  - fbird_service_attach — Alias de ibase_service_attach
  - fbird_service_detach — Alias de ibase_service_detach
  - fbird_set_event_handler — Alias de ibase_set_event_handler
  - fbird_trans — Alias de ibase_trans
  - fbird_wait_event — Alias de ibase_wait_event
  - ibase_add_user — Añade un usuario a una base de datos de seguridad
  - ibase_affected_rows — Devuelve el número de filas afectadas por la última consulta iBase
  - ibase_backup — Inicia una tarea de respaldo en el gestor de servicios y devuelve inmediatamente
  - ibase_blob_add — Añade datos a un BLOB iBase recién creado
  - ibase_blob_cancel — Cancela la creación de un BLOB iBase
  - ibase_blob_close — Cierra un BLOB iBase
  - ibase_blob_create — Crea un BLOB iBase para añadir datos
  - ibase_blob_echo — Muestra el contenido de un BLOB iBase en el navegador
  - ibase_blob_get — Lee len bytes de datos en un BLOB iBase abierto
  - ibase_blob_import — Crea un BLOB iBase, copia un fichero y lo cierra
  - ibase_blob_info — Devuelve el tamaño de un BLOB iBase y otra información útil
  - ibase_blob_open — Abre un BLOB iBase para recuperar partes de datos
  - ibase_close — Cierra una conexión a una base de datos Interbase
  - ibase_commit — Valida una transacción iBase
  - ibase_commit_ret — Valida una transacción iBase sin cerrarla
  - ibase_connect — Abre una conexión a una base de datos
  - ibase_db_info — Solicita estadísticas sobre una base de datos Interbase
  - ibase_delete_user — Elimina un usuario de una base de datos de seguridad
  - ibase_drop_db — Elimina una base de datos iBase
  - ibase_errcode — Devuelve el código de error iBase
  - ibase_errmsg — Devuelve un mensaje de error
  - ibase_execute — Ejecuta una consulta iBase preparada
  - ibase_fetch_assoc — Recupera una fila del resultado de una consulta en un array asociativo
  - ibase_fetch_object — Lee una línea en una base Interbase en un objeto
  - ibase_fetch_row — Lee una línea de una base Interbase
  - ibase_field_info — Lee la información sobre un campo iBase
  - ibase_free_event_handler — Libera un gestor de eventos iBase
  - ibase_free_query — Libera la memoria reservada por una consulta preparada
  - ibase_free_result — Libera un resultado iBase
  - ibase_gen_id — Incrementa el generador dado y devuelve su nuevo valor
  - ibase_maintain_db — Ejecuta un comando de mantenimiento en una base de datos Interbase
  - ibase_modify_user — Modifica un usuario en una base de datos de seguridad
  - ibase_name_result — Asigna un nombre a un conjunto de resultados iBase
  - ibase_num_fields — Devuelve el número de columnas en un resultado iBase
  - ibase_num_params — Devuelve el número de parámetros en una consulta preparada iBase
  - ibase_param_info — Devuelve información sobre un argumento en una consulta preparada iBase
  - ibase_pconnect — Abre una conexión persistente a una base de datos InterBase
  - ibase_prepare — Prepara una consulta iBase para ligar los argumentos y ejecutarla posteriormente
  - ibase_query — Ejecuta una consulta en una base iBase
  - ibase_restore — Inicia una tarea de restauración en el gestor de servicios y devuelve inmediatamente
  - ibase_rollback — Anula una transacción interBase
  - ibase_rollback_ret — Anula una transacción sin cerrarla
  - ibase_server_info — Solicita información sobre un servidor de base de datos
  - ibase_service_attach — Conexión al gestor de servicio
  - ibase_service_detach — Desconexión del gestor de servicio
  - ibase_set_event_handler — Registra una función de retrollamada para un evento interBase
  - ibase_trans — Prepara una transacción interBase
  - ibase_wait_event — Espera un evento interBase

# Funciones IBM DB2, Cloudscape y Apache Derby

# Introducción

Estas funciones permiten el acceso a IBM DB2 Universal Database, IBM Cloudscape y Apache Derby que utilizan `DB2 Call Level Interface` (CLI).

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución
- Tipos de recursos

## Requerimientos

Para conectar a IBM DB2 Universal Database para Linux, Unix y Windows, o a IBM Cloudscape, o a Apache Derby, se debe instalar el cliente de IBM DB2 Universal Database en el mismo equipo en que se ejecuta PHP. Esta extensión se ha desarrollado y probado con DB2 Version 8.2.

Para conectar a IBM DB2 Universal Database en z/OS o iSeries, es necesario también IBM DB2 Connect o un software enrutador DRDA equivalente.

## Requisitos en Linux y Unix

El usuario que invoca el ejecutable de PHP o el SAPI debe especificar la instancia de DB2 antes de acceder a estas funciones. Se puede establecer el nombre de la instancia de DB2 en php.ini utilizando la opción de configuración `ibm_db2.instance_name`, o se puede cargar el perfil de la instancia de DB2 antes de invocar el ejecutable de PHP.

Si se ha creado una instancia de DB2 llamada `db2inst1` en /home/db2inst1/, por ejemplo, se puede añadir la siguiente línea a php.ini:

    ibm_db2.instance_name=db2inst1

Si no se establece esta opción en php.ini, se debe ejecutar el siguiente comando para modificar las variables de entorno y habilitar el acceso a DB2:

    bash$ source /home/db2inst1/sqllib/db2profile

Para permitir que el servidor web con PHP acceda a estas funciones, se debe establecer la opción de configuración `ibm_db2.instance_name` en php.ini, o cargar el entorno de la instancia de DB2 en el script de inicio del servidor web (típicamente /etc/init.d/httpd o /etc/init.d/apache).

## Instalación

Para compilar la extensión ibm_db2, los archivos de encabezado y de biblioteca de la aplicación de desarrollo de DB2 deben estar presentes en el sistema. DB2 no los instala por omisión, por lo que podría ser necesario volver a la instalación de DB2 y añadir esta opción. El cliente de desarrollo de aplicación DB2 incluye los archivos de encabezado y está disponible libremente para su descarga desde el » sitio de soporte de la base de datos universal.

Si los archivos de encabezado y de biblioteca de la aplicación de desarrollo de DB2 se añaden en un sistema Linux o Unix donde DB2 ya está instalado, el comando db2iupdt -e deberá ejecutarse para actualizar los enlaces simbólicos hacia los archivos de encabezado y de biblioteca de las instancias DB2.

ibm_db2 es una extensión » PECL, por lo que se deben seguir las instrucciones presentes en Instalación de extensiones PECL para instalar la extensión ibm_db2 para PHP. Ejecute el comando configure para indicar la ubicación de los archivos de encabezado y de biblioteca de DB2 de la siguiente manera:

    bash$ ./configure --with-IBM_DB2=/ruta/versus/DB2

El comando configure toma el valor por omisión de /opt/IBM/db2/V8.1.

> Nota: Nota para los usuarios de IIS
> Si el controlador ibm_db2 se utiliza con IIS (Microsoft Internet Information Server), podría ser necesario tomar las siguientes medidas:

> - Instalar DB2 con el sistema de seguridad extendido.
> - Añadir la ruta hacia el binario PHP a la variable de entorno PATH del sistema (Por omisión: `C:\php\`).
> - Crear otra variable de entorno que contenga la ruta hacia el archivo PHP.INI (p. ej.: `PHPRC = C:\php\`).
> - Añadir el usuario IUSR_COMPUTERNAME al grupo DB2USERS.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración DB2
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
ibm_db2.binmode | "1" | `INI_ALL` |
ibm_db2.i5_all_pconnect | "0" | `INI_SYSTEM` | Disponible a partir de ibm_db2 1.6.5.
ibm_db2.i5_allow_commit | "0" | `INI_SYSTEM` | Disponible a partir de ibm_db2 1.4.9.
ibm_db2.i5_blank_userid | "0" | `INI_SYSTEM` | Disponible a partir de ibm_db2 1.9.7.
ibm_db2.i5_char_trim | "0" | `INI_SYSTEM` | Disponible a partir de ibm_db2 2.1.0.
ibm_db2.i5_dbcs_alloc | "0" | `INI_SYSTEM` | Disponible a partir de ibm_db2 1.5.0.
ibm_db2.i5_guard_profile | "0" | `INI_SYSTEM` | Disponible a partir de ibm_db2 1.9.7.
ibm_db2.i5_ignore_userid | "0" | `INI_SYSTEM` | Disponible a partir de ibm_db2 1.8.0.
ibm_db2.i5_job_sort | "0" | `INI_SYSTEM` | Disponible a partir de ibm_db2 1.8.4.
ibm_db2.i5_log_verbose | "0" | `INI_SYSTEM` | Disponible a partir de ibm_db2 1.9.7.
ibm_db2.i5_max_pconnect | "0" | `INI_SYSTEM` | Disponible a partir de ibm_db2 1.9.7.
ibm_db2.i5_override_ccsid | "0" | `INI_SYSTEM` | Disponible a partir de ibm_db2 1.9.7.
ibm_db2.i5_servermode_subsystem | NULL | `INI_SYSTEM` | Disponible a partir de ibm_db2 1.9.7.
ibm_db2.i5_sys_naming | "0" | `INI_SYSTEM` | Disponible a partir de ibm_db2 1.9.7.
ibm_db2.instance_name | NULL | `INI_SYSTEM` | Disponible a partir de ibm_db2 1.0.2.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`ibm_db2.binmode` (int)

  Esta opción controla el modo utilizado para convertir desde o hacia los datos binarios en la aplicación PHP.

  - 1 (DB2_BINARY)
  - 2 (DB2_CONVERT)
  - 3 (DB2_PASSTHRU)
`ibm_db2.i5_all_pconnect` (int)

  Esta opción fuerza todas las conexiones a ser persistentes en IBM i. Fundamentalmente, todas las llamadas a db2_connect() se convierten automáticamente en llamadas a db2_pconnect(). Por omisión, esta opción es `0`. Esta opción se proporciona por conveniencia en los casos donde las conexiones persistentes son más rápidas. No debería utilizarse en nuevas aplicaciones.

  - 0 - Se pueden establecer conexiones persistentes y no persistentes.
  - 1 - Todas las conexiones son persistentes.
`ibm_db2.i5_allow_commit` int

  Esta opción controla el modo de aislamiento de la transacción utilizado. Por omisión, esta opción es `0`, por lo que no se utiliza el control de compromiso. Esta opción puede ser reemplazada durante la conexión si la clave del array `i5_commit` está definida en el array de opciones de conexión pasado a db2_connect() o db2_pconnect().

  - 0 - No se utiliza el control de compromiso.
  - 1 - Lectura no comprometida, lectura sucia posible.
  - 2 - Lectura comprometida, lectura sucia imposible.
  - 3 - Lectura repetible, lectura sucia y lectura no repetible son imposibles.
  - 4 - Serializable, lectura sucia, lectura no repetible y fantasma son imposibles.
`ibm_db2.i5_blank_userid` int

  Esto controla si se debe permitir un identificador de usuario vacío en IBM i. Por omisión, esta opción es `0`. A diferencia de `ibm_db2.i5_ignore_userid`, esta opción no fuerza a que todos los identificadores de usuario sean vacíos o a modificar el comportamiento del trabajo, sino que simplemente permite pasar un identificador de usuario vacío, para conectarse a Db2 como usuario actual.

  - 0 - No permite pasar un identificador de usuario vacío.
  - 1 - Permite pasar un identificador de usuario vacío.
`ibm_db2.i5_char_trim` int

  Esta opción controla si se recorta el final de las cadenas en IBM i. Dado que muchas tablas utilizan tamaños de columnas fijos rellenos de espacios, esto se proporciona por conveniencia. Por omisión, esta opción es `0`.

  - 0 - Las columnas no se recortan.
  - 1 - Los espacios al final de las columnas de caracteres devueltas se eliminan.
`ibm_db2.i5_dbcs_alloc` (int)

  Esta opción afecta a la estrategia de asignación de memoria de búfer interno en IBM i. Por omisión, esta opción es `0`. Cuando esta opción está definida, los búferes se asignan con un tamaño mucho mayor, en caso de que la base de datos subestime el tamaño de una cadena durante la conversión entre codificaciones. Esta opción utiliza seis veces más memoria para los búferes (para tener en cuenta las secuencias UTF-8 más grandes posibles), pero puede ser necesaria si se devuelven datos truncados.

  - 0 - Se asignan búferes de tamaño mínimo.
  - 1 - Se asignan búferes de tamaño mayor.
`ibm_db2.i5_guard_profile` int

  Esta opción verifica si el perfil de usuario de la base de datos ha sido cambiado durante la conexión a una conexión de base de datos persistente en IBM i, y si es así, se desconecta de la base de datos. Por omisión, esta opción está definida en `0`.

  - 0 - No verificar cambios de perfil.
  - 1 - Verificar cambios de perfil y desconectarse en caso necesario.
`ibm_db2.i5_log_verbose` int

  Esta opción define si los mensajes de diagnóstico SQL como advertencias y errores son siempre enviados al registro de errores PHP en IBM i. Normalmente, solo se envía un breve mensaje en caso de fallo (como "la ejecución de la sentencia falló") en el registro de errores PHP, ya que esta opción está definida en `0` por omisión. Tenga en cuenta que siempre y cuando debe llamar, por ejemplo, db2_stmt_errormsg() manualmente para verificar si las funciones fallan.

  - 0 - Solo se registran mensajes breves.
  - 1 - Se registra el mensaje de diagnóstico SQL además del mensaje breve.
`ibm_db2.i5_ignore_userid` (int)

  Esta opción ignora el ID de usuario al conectarse a la base de datos al ejecutarse en IBM i, y ejecuta la funcionalidad SQL/CLI dentro del trabajo PHP, en lugar de un trabajo separado. Por omisión, esta opción es `0`. Cuando está activada, ya no utiliza un trabajo de servidor de base de datos separado, y siempre utiliza el perfil de usuario actual para la base de datos, ignorando el nombre de usuario y la contraseña pasados a db2_connect() y db2_pconnect().

  - 0 : db2_(p)connect con un identificador de usuario y contraseña específicos 0 - Utiliza las credenciales especificadas y utiliza un trabajo de servidor SQL/CLI.
  - 1 : db2_(p)connect con un identificador de usuario y contraseña vacíos 1 - Siempre utiliza credenciales vacías y ejecuta SQL/CLI en el trabajo PHP.
`ibm_db2.i5_job_sort` int

  Controla la opción de ordenación de trabajos en IBM i. Por omisión, esta opción es `0`. Esto corresponde al atributo `SQL_ATTR_CONN_SORT_SEQUENCE` de IBM i SQL/CLI.

  - 0 - Utiliza la opción de ordenación `*HEX`, ordenando por bytes.
  - 1 - Utiliza la secuencia de ordenación de trabajo definida para el trabajo PHP.
  - 2 - Utiliza la secuencia de ordenación de trabajo definida para el trabajo de base de datos.
`ibm_db2.i5_max_pconnect` int
  Esto afectará cuántas veces se puede reutilizar una conexión persistente al ejecutarse en IBM i. Por omisión, esto está configurado en `0`, lo que significa que una conexión persistente siempre puede ser reutilizada. Esta opción puede ayudar a evitar problemas en un trabajo de base de datos de larga duración (es decir, si un procedimiento pierde memoria), pero obviamente no es una solución a largo plazo.
`ibm_db2.i5_override_ccsid` int
  El CCSID PASE a utilizar para las conversiones de caracteres EBCDIC en IBM i. Por omisión, es `0`, lo que seleccionará el CCSID de trabajo PASE por defecto, procedente de los parámetros de localización PASE. Por ejemplo, al configurarlo en `1208`, se utilizará el UTF-8. Solo debe modificarse si el CCSID del trabajo PASE no es el CCSID esperado, y la localización no puede ser modificada. Para obtener más información sobre los CCSID en IBM i, consulte la » documentación de IBM. Para saber cómo las localizaciones en IBM i PASE se mapean a los CCSID, consulte la » documentación de IBM.
`ibm_db2.i5_sys_naming` int

  Esta opción controla el modo de nombrado al conectarse a un sistema IBM i. Por omisión, esta opción es `0`. El modo de nombrado afecta a la resolución de nombres y la sintaxis permitida para los nombres. Cuando está configurado en `0`, utiliza puntos para calificar los nombres y utiliza la biblioteca o el identificador de usuario por defecto para resolver los nombres. Cuando está configurado en `1`, utiliza barras diagonales para calificar los nombres y utiliza la lista de bibliotecas de trabajo para resolver los nombres.

  - 0 - Utiliza el modo de nombrado SQL ("SCHEMA.TABLE").
  - 1 - Utiliza el modo de nombrado del sistema ("LIBRARY/FILE").
  Para obtener más información sobre los modos de nombrado en IBM i, consulte la » documentación de IBM.
`ibm_db2.i5_servermode-subsystem` string
  Esta opción modifica el subsistema bajo el cual se ejecutan los trabajos del servidor de base de datos en IBM i. Por omisión, esta opción es `null`, por lo que los trabajos se ejecutarán bajo el subsistema por defecto para los trabajos QSQSRVR.
`ibm_db2.instance_name` string

  En los sistemas operativos Linux y UNIX, esta opción define el nombre de la instancia a utilizar para las conexiones de base de datos catalogadas. Por omisión, esta opción es `null`. Si esta opción está definida, su valor reemplaza la configuración de la variable de entorno DB2INSTANCE.

  Esta opción se ignora en los sistemas operativos Windows.

## Tipos de recursos

La extensión ibm_db2 devuelve recursos de conexión, recursos de sentencias, y recursos de juegos de resultados.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`DB2_BINARY` (int)
  Especifica que los datos binarios serán devueltos tal cual. Este es el modo por defecto.
`DB2_CONVERT` (int)
  Especifica que los datos binarios serán convertidos a hexadecimal y devueltos como una cadena ASCII.
`DB2_PASSTHRU` (int)
  Especifica que los datos binarios serán convertidos a valor `null`.
`DB2_SCROLLABLE` (int)
  Especifica el cursor flotante para una declaración de recurso. Este modo permite un acceso aleatorio a las filas del juego de resultados, pero actualmente, solo es soportado por IBM DB2 Universal Database.
`DB2_FORWARD_ONLY` (int)
  Especifica un cursor de avance único para una declaración de recurso. Este es el valor por defecto de este tipo de cursor, y es soportado por todos los servidores de base de datos.
`DB2_PARAM_IN` (int)
  Especifica que la variable PHP debe ser vinculada como un parámetro ENTRADA para un procedimiento de registro.
`DB2_PARAM_OUT` (int)
  Especifica que la variable PHP debe ser vinculada como un parámetro SALIDA para un procedimiento de registro.
`DB2_PARAM_INOUT` (int)
  Especifica que la variable PHP debe ser vinculada como un parámetro ENTRADA/SALIDA para un procedimiento de registro.
`DB2_PARAM_FILE` (int)
  Especifica que la columna debe ser vinculada directamente a un fichero para entrada.
`DB2_AUTOCOMMIT_ON` (int)
  Especifica que autocommit debe ser activado.
`DB2_AUTOCOMMIT_OFF` (int)
  Especifica que autocommit debe ser desactivado.
`DB2_DOUBLE` (int)
  Especifica que la variable debe ser vinculada a un tipo DOUBLE, FLOAT o REAL.
`DB2_LONG` (int)
  Especifica que la variable debe ser vinculada a un tipo SMALLINT, INTEGER o BIGINT.
`DB2_CHAR` (int)
  Especifica que la variable debe ser vinculada a un tipo CHAR o VARCHAR
`DB2_CASE_NATURAL` (int)
  Especifica que los nombres de columnas deben ser devueltos en sus casos naturales.
`DB2_CASE_LOWER` (int)
  Especifica que los nombres de columnas deben ser devueltos en minúsculas.
`DB2_CASE_UPPER` (int)
  Especifica que los nombres de columnas deben ser devueltos en mayúsculas.
`DB2_DEFERRED_PREPARE_ON` (int)
  Especifica que la preparación diferida debe ser activada para el recurso de consulta especificado.
`DB2_DEFERRED_PREPARE_OFF` (int)
  Especifica que la preparación diferida debe ser desactivada para el recurso de consulta especificado.

# Funciones de IBM DB2

# db2_autocommit

(PECL ibm_db2 >= 1.0.0)

db2_autocommit — Devuelve o modifica el estado AUTOCOMMIT de la conexión a la base de datos

### Descripción

function db2_autocommit(resource `$connection`, int `$value` = ?): int|bool

Modifica o lee el comportamiento de AUTOCOMMIT de la conexión especificada.

### Parámetros

`connection`
  Una variable de conexión a una base de datos válida devuelta por db2_connect() o db2_pconnect().
`value`

  Una de las constantes siguientes :

  `DB2_AUTOCOMMIT_OFF`
    Desactiva AUTOCOMMIT.
  `DB2_AUTOCOMMIT_ON`
    Activa AUTOCOMMIT.

### Valores devueltos

Cuando db2_autocommit() recibe solo `connection` como argumento, la función devuelve un entero representando el estado actual de AUTOCOMMIT de la conexión proporcionada. Un valor de `DB2_AUTOCOMMIT_OFF` indica que AUTOCOMMIT está desactivado, mientras que un valor de `DB2_AUTOCOMMIT_ON` indica que AUTOCOMMIT está activado.

Cuando db2_autocommit() recibe ambos argumentos `connection` y `autocommit`, la función intenta modificar el estado AUTOCOMMIT al estado `autocommit` de la conexión proporcionada. Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Obtención del valor de AUTOCOMMIT para una conexión

En el siguiente ejemplo, se prueba una conexión que fue inicializada con el estado AUTOCOMMIT desactivado utilizando la función db2_autocommit().

    <?php
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF);
    $conn = db2_connect($database, $user, $password, $options);
    $ac = db2_autocommit($conn);
    if ($ac == DB2_AUTOCOMMIT_OFF) {
        print "$ac -- AUTOCOMMIT está desactivado.";
    } else {
        print "$ac -- AUTOCOMMIT está activado.";
    }
    ?>

El ejemplo anterior mostrará:

    0 -- AUTOCOMMIT está desactivado.

Ejemplo #2 Modificación del valor de AUTOCOMMIT para una conexión

En el siguiente ejemplo, se cambia el comportamiento de una conexión que fue previamente inicializada con el estado AUTOCOMMIT desactivado al activar el estado AUTOCOMMIT.

    <?php
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF);
    $conn = db2_connect($database, $user, $password, $options);

    // Activa AUTOCOMMIT
    $rc = db2_autocommit($conn, DB2_AUTOCOMMIT_ON);
    if ($rc) {
        print "Activación AUTOCOMMIT exitosa.\n";
    }

    // Verificación del estado AUTOCOMMIT
    $ac = db2_autocommit($conn);
    if ($ac == DB2_AUTOCOMMIT_OFF) {
        print "$ac -- AUTOCOMMIT está desactivado.";
    } else {
        print "$ac -- AUTOCOMMIT está activado.";
    }
    ?>

El ejemplo anterior mostrará:

    Activación AUTOCOMMIT exitosa.
    1 -- AUTOCOMMIT está activado.

### Ver también

- db2_connect() - Devuelve una conexión a una base de datos
- db2_pconnect() - Devuelve una conexión persistente a una base de datos

# db2_bind_param

(PECL ibm_db2 >= 1.0.0)

db2_bind_param — Asocia una variable PHP a un parámetro de una consulta SQL

### Descripción

function db2_bind_param(
resource `$stmt`,
int `$parameter_number`,
string `$variable_name`,
int `$parameter_type` = `DB2_PARAM_IN`,
int `$data_type` = 0,
int `$precision` = -1,
int `$scale` = 0
): bool

Asocia una variable PHP a un parámetro en la consulta SQL devuelta por db2_prepare(). Esta función permite mayor control sobre los tipos de los parámetros, los tipos de datos, la precisión y la escala para el parámetro que al pasarle simplemente una variable dentro del array de entrada opcional de la función db2_execute().

### Parámetros

`stmt`
  Una consulta preparada devuelta por db2_prepare().
`parameter_number`
  Especifica la posición del parámetro comenzando en el índice 1 en la consulta preparada.
`variable_name`
  Una cadena que especifica el nombre de la variable PHP a asociar al parámetro especificado por `parameter_number`.
`parameter_type`
  Una constante que especifica si la variable PHP debe ser asociada al parámetro SQL como parámetro de entrada (`DB2_PARAM_IN`), como parámetro de salida (`DB2_PARAM_OUT`) o como parámetro que acepta entradas y salidas (`DB2_PARAM_INOUT`). Para evitar un exceso de consumo de memoria, también puede especificarse `DB2_PARAM_FILE` para asociar la variable PHP al nombre del archivo que contiene los datos del objeto grande (BLOB, CLOB o DBCLOB).
`data_type`
  Una constante que especifica el tipo de datos SQL que la variable PHP debe ser asociada. El parámetro debe tomar uno de los siguientes valores: `DB2_BINARY`, `DB2_CHAR`, `DB2_DOUBLE` o `DB2_LONG`.
`precision`
  Especifica la precisión con la que la variable debe ser asociada a la base de datos. Este parámetro también puede ser utilizado para recuperar valores de salida XML para procedimientos almacenados. Un valor no negativo especifica el tamaño máximo de los datos XML que serán recuperados desde la base de datos. Si este parámetro no es utilizado, se definirá un tamaño por defecto de 1 MB para recuperar los valores de tipo XML desde el procedimiento almacenado.
`scale`
  Especifica la escala con la que la variable debe ser asociada a la base de datos.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Asociación de variables PHP a una consulta preparada

La consulta SQL en el siguiente ejemplo utiliza dos parámetros de entrada en la sección WHERE. Se llama a db2_bind_param() para asociar dos variables que no han sido declaradas o asignadas antes de la llamada a db2_bind_param(); en este ejemplo, `$lower_limit` es asignada antes de ser llamada a db2_bind_param(), pero `$upper_limit` es asignada después de la llamada a db2_bind_param(). Las variables deben ser asociadas y, para los parámetros que aceptan entradas, se les debe asignar un valor antes de llamar a db2_execute().

    <?php

    $sql = 'SELECT nom, race, poids FROM animaux
        WHERE poids > ? AND poids < ?';
    $conn = db2_connect($database, $user, $password);
    $stmt = db2_prepare($conn, $sql);

    // Se puede declarar la variable antes de llamar a db2_bind_param()
    $lower_limit = 1;

    db2_bind_param($stmt, 1, "lower_limit", DB2_PARAM_IN);
    db2_bind_param($stmt, 2, "upper_limit", DB2_PARAM_IN);

    // También se puede declarar la variable después de llamar a db2_bind_param()
    $upper_limit = 15.0;

    if (db2_execute($stmt)) {
        while ($row = db2_fetch_array($stmt)) {
            print "{$row[0]}, {$row[1]}, {$row[2]}\n";
        }
    }
    ?>

El ejemplo anterior mostrará:

    Pook, chat, 3.2
    Rickety Ride, chèvre, 9.7
    Peaches, chien, 12.3

Ejemplo #2 Llamada a procedimientos de registro con parámetros IN y OUT

El procedimiento de registro concorde_animal en el siguiente ejemplo acepta tres diferentes parámetros:

1. un parámetro de entrada (IN) que acepta el nombre del primer animal en entrada
2. un parámetro de entrada-salida (INOUT) que acepta el nombre del segundo animal en entrada y devuelve un string `TRUE` si un animal en la base de datos coincide con este nombre
3. un parámetro de salida (OUT) que devuelve la suma de los pesos de los dos animales identificados

Además, el procedimiento de registro devuelve un conjunto de resultados que contiene los animales listados en orden alfabético comenzando con el animal correspondiente al valor de entrada del primer parámetro y terminando con el animal correspondiente al valor de entrada del segundo parámetro.

    <?php

    $sql = 'CALL concorde_animal(?, ?, ?)';
    $conn = db2_connect($database, $user, $password);
    $stmt = db2_prepare($conn, $sql);

    $nom = "Peaches";
    $second_nom = "Rickety Ride";
    $poids = 0;

    db2_bind_param($stmt, 1, "nom", DB2_PARAM_IN);
    db2_bind_param($stmt, 2, "second_nom", DB2_PARAM_INOUT);
    db2_bind_param($stmt, 3, "poids", DB2_PARAM_OUT);

    print "Valores de los parámetros _antes_ de CALL :\n";
    print "  1: {$nom} 2: {$second_nom} 3: {$poids}\n\n";

    if (db2_execute($stmt)) {
        print "Valores de los parámetros _después_ de CALL :\n";
        print "  1: {$nom} 2: {$second_nom} 3: {$poids}\n\n";

        print "Resultados :\n";
        while ($row = db2_fetch_array($stmt)) {
            print "  {$row[0]}, {$row[1]}, {$row[2]}\n";
        }
    }
    ?>

El ejemplo anterior mostrará:

    Valores de los parámetros _antes_ de CALL :
      1: Peaches 2: Rickety Ride 3: 0

    Valores de los parámetros _después_ de CALL :
      1: Peaches 2: TRUE 3: 22

    Resultados :
      Peaches, chien, 12.3
      Pook, chat, 3.2
      Rickety Ride, chèvre, 9.7

Ejemplo #3 Inserción de un objeto grande binario (BLOB) directamente desde un archivo

Los datos para los objetos grandes normalmente se almacenan en archivos, como documentos XML o archivos de audio. En lugar de leer el archivo completo en una variable de PHP y luego asociar la variable PHP en la consulta SQL, se puede evitar cierto sobrecoste de memoria asociando el archivo directamente al parámetro de entrada de su consulta SQL. El siguiente ejemplo demuestra cómo asociar un archivo directamente en una columna BLOB.

    <?php
    $stmt = db2_prepare($conn, "INSERT INTO animal_pictures(photo) VALUES (?)");

    $picture = "/opt/albums/spook/grooming.jpg";
    $rc = db2_bind_param($stmt, 1, "picture", DB2_PARAM_FILE);
    $rc = db2_execute($stmt);
    ?>

### Ver también

- db2_execute() - Ejecuta una consulta SQL preparada
- db2_prepare() - Prepara una consulta SQL para ser ejecutada

# db2_client_info

(PECL ibm_db2 >= 1.1.1)

db2_client_info — Devuelve un objeto con propiedades que describen el cliente de base de datos DB2

### Descripción

function db2_client_info(resource `$connection`): stdClass|false

Esta función devuelve un objeto con propiedades en solo lectura que proporcionan información sobre el cliente de base de datos DB2. La tabla siguiente lista las propiedades del cliente DB2:

Propiedades del cliente DB2
Nombre Propiedad | Tipo de retorno | Descripción
--- | --- | ---
APPL_CODEPAGE | int | La aplicación es un código de página.
CONN_CODEPAGE | int | El código de página para la conexión actual.
DATA_SOURCE_NAME | string | El nombre de la fuente de datos (DSN) utilizado para crear la conexión actual a la base de datos.
DRIVER_NAME | string | El nombre de la biblioteca que implementa la especificación `DB2 Call Level Interface` (CLI).
DRIVER_ODBC_VER | string | La versión de ODBC que el cliente DB2 soporta. Esto devuelve una string `"MM.mm"` donde MM es la versión mayor y mm es la versión menor. El cliente DB2 siempre devuelve `"03.51"`.
DRIVER_VER | string | La versión del cliente, en la forma de una string `"MM.mm.uuuu"` donde MM es la versión mayor, mm es la versión menor y uuuu es la actualización. Por ejemplo, `"08.02.0001"` representa la versión mayor 8, la versión menor 2, y la actualización 1.
ODBC_SQL_CONFORMANCE | string | El nivel de sintaxis soportado por el cliente: MINIMUM Soporta el mínimo de sintaxis SQL de ODBC. CORE Soporta el núcleo de sintaxis SQL de ODBC. EXTENDED Soporta la sintaxis extendida SQL de ODBC.
ODBC_VER | string | La versión de ODBC que el administrador de controladores ODBC soporta. Esto devuelve una string `"MM.mm.rrrr"` donde MM es la versión mayor, mm es la versión menor y rrrr es la actualización. El cliente DB2 siempre devuelve `"03.01.0000"`.

### Parámetros

`connection`
  Especifica la conexión cliente DB2 activa.

### Valores devueltos

Devuelve un objeto si la llamada es exitosa, o `false` si ocurre un error

### Ejemplos

Ejemplo #1 Ejemplo con db2_client_info()

Para obtener información sobre el cliente, se debe pasar un recurso de conexión de base de datos válido a la función db2_client_info().

    <?php
    $conn = db2_connect( 'SAMPLE', 'db2inst1', 'ibmdb2' );
    $client = db2_client_info( $conn );

    if ($client) {
        echo "DRIVER_NAME: ";   var_dump( $client->DRIVER_NAME );
        echo "DRIVER_VER: ";   var_dump( $client->DRIVER_VER );
        echo "DATA_SOURCE_NAME: ";   var_dump( $client->DATA_SOURCE_NAME );
        echo "DRIVER_ODBC_VER: ";   var_dump( $client->DRIVER_ODBC_VER );
        echo "ODBC_VER: ";    var_dump( $client->ODBC_VER );
        echo "ODBC_SQL_CONFORMANCE: ";  var_dump( $client->ODBC_SQL_CONFORMANCE );
        echo "APPL_CODEPAGE: ";   var_dump( $client->APPL_CODEPAGE );
        echo "CONN_CODEPAGE: ";   var_dump( $client->CONN_CODEPAGE );
    }
    else {
        echo "Error al obtener la información del cliente.
         Quizás su conexión a la base de datos era inválida.";
    }
    db2_close($conn);

    ?>

El ejemplo anterior mostrará:

    DRIVER_NAME: string(8) "libdb2.a"
    DRIVER_VER: string(10) "08.02.0001"
    DATA_SOURCE_NAME: string(6) "SAMPLE"
    DRIVER_ODBC_VER: string(5) "03.51"
    ODBC_VER: string(10) "03.01.0000"
    ODBC_SQL_CONFORMANCE: string(8) "EXTENDED"
    APPL_CODEPAGE: int(819)
    CONN_CODEPAGE: int(819)

### Ver también

- db2_server_info() - Devuelve un objeto con propiedades que describen el servidor de base de datos DB2

# db2_close

(PECL ibm_db2 >= 1.0.0)

db2_close — Cierra una conexión a base de datos

### Descripción

function db2_close(resource `$connection`): bool

Esta función cierra una conexión cliente DB2 creada con db2_connect() y devuelve el recurso correspondiente al servidor de base de datos.

Si se tratara de cerrar una conexión de cliente DB2 persistente creada con db2_pconnect(), la petición de cierre se ignoraría y la conexión de cliente DB2 permanecería disponible para la siguiente llamada.

### Parámetros

`connection`
  Especifica la conexión a cliente DB2 activa.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Cierre de una conexión

El siguiente ejemplo demuestra un intento de cierre exitoso de una conexión a una base de datos IBM DB2, Cloudscape, o Apache Derby.

    <?php
    $conn = db2_connect('SAMPLE', 'db2inst1', 'ibmdb2');
    $rc = db2_close($conn);
    if ($rc) {
        echo "Conexión cerrada con éxito.";
    }
    ?>

El ejemplo anterior mostrará:

    Conexión cerrada con éxito.

### Ver también

- db2_connect() - Devuelve una conexión a una base de datos
- db2_pclose() - Cierra una conexión persistente a la base de datos
- db2_pconnect() - Devuelve una conexión persistente a una base de datos

# db2_column_privileges

(PECL ibm_db2 >= 1.0.0)

db2_column_privileges — Devuelve un conjunto de resultados que lista las columnas y sus privilegios de una tabla

### Descripción

function db2_column_privileges(
resource `$connection`,
?string `$qualifier` = `null`,
?string `$schema` = `null`,
?string `$table_name` = `null`,
?string `$column_name` = `null`
): resource

Devuelve un conjunto de resultados que lista las columnas y sus privilegios de una tabla.

### Parámetros

`connection`
  Una conexión válida a una base de datos IBM DB2, Cloudscape o Apache Derby.
`qualifier`
  Un calificador para las bases de datos DB2 que funcionan en los servidores OS/390 o z/OS. Para otras bases de datos, pase `null` o una cadena vacía.
`schema`
  El esquema que contiene las tablas. Para coincidir con todos los esquemas, pase `null` o una cadena vacía.
`table_name`
  El nombre de la tabla. Para obtener todas las tablas en la base de datos, pase `null` o una cadena vacía.
`column_name`
  El nombre de la columna. Para obtener todas las columnas de la tabla, pase `null` o una cadena vacía.

### Valores devueltos

Devuelve un recurso con el conjunto de resultados que contiene las filas que describen los privilegios de las columnas que coinciden con los parámetros especificados. Las filas están compuestas por las siguientes columnas:

Nombre de la columna | Descripción
--- | ---
TABLE_CAT | Nombre del catálogo. El valor es `null` si la tabla no posee catálogo.
TABLE_SCHEM | Nombre del esquema.
TABLE_NAME | Nombre de la tabla.
COLUMN_NAME | Nombre de la columna.
GRANTOR | ID de autorización del usuario que concedió el privilegio.
GRANTEE | ID de autorización del usuario al que se le concedió el privilegio.
PRIVILEGE | El privilegio para la columna.
IS_GRANTABLE | Si GRANTEE está permitido para conceder este privilegio a otros usuarios.

### Ver también

- db2_columns() - Devuelve un conjunto de resultados que lista las columnas y sus metadatos de una tabla
- db2_foreign_keys() - Devuelve un conjunto de resultados que lista las claves externas de una tabla
- db2_primary_keys() - Devuelve un conjunto de resultados que lista las claves de una tabla
- db2_procedure_columns() - Devuelve un conjunto de resultados que lista los argumentos de procedimiento de registro
- db2_procedures() - Devuelve un conjunto de resultados que lista las proceduras de registro almacenadas en la base de datos
- db2_special_columns() - Devuelve un conjunto de resultados que lista los identificadores únicos de las filas de una tabla
- db2_statistics() - Devuelve un conjunto de resultados que enumera los índices y estadísticas de una tabla
- db2_table_privileges() - Devuelve un conjunto de resultados que lista las tablas y sus privilegios asociados en una base de datos
- db2_tables() - Devuelve la lista de tablas y sus metadatos

# db2_columns

(PECL ibm_db2 >= 1.0.0)

db2_columns — Devuelve un conjunto de resultados que lista las columnas y sus metadatos de una tabla

### Descripción

function db2_columns(
resource `$connection`,
?string `$qualifier` = `null`,
?string `$schema` = `null`,
?string `$table_name` = `null`,
?string `$column_name` = `null`
): resource

Devuelve un conjunto de resultados que lista las columnas y sus metadatos de una tabla.

### Parámetros

`connection`
  Una conexión válida a una base de datos IBM DB2, Cloudscape o Apache Derby.
`qualifier`
  Un calificador para las bases de datos DB2 que funcionan en los servidores OS/390 o z/OS. Para otras bases de datos, se debe pasar `null` o una cadena vacía.
`schema`
  El esquema que contiene las tablas. Para coincidir con todos los esquemas, se debe pasar `'%'`.
`table_name`
  El nombre de la tabla. Para obtener todas las tablas en la base de datos, se debe pasar `null` o una cadena vacía.
`column_name`
  El nombre de la columna. Para obtener todas las columnas de la tabla, se debe pasar `null` o una cadena vacía.

### Valores devueltos

Devuelve un recurso con el conjunto de resultados que contiene las filas que describen los privilegios de las columnas que coinciden con los parámetros especificados. Las filas están compuestas por las siguientes columnas:

Nombre de la columna | Descripción
--- | ---
TABLE_CAT | Nombre del catálogo. El valor es `null` si la tabla no posee catálogo.
TABLE_SCHEM | Nombre del esquema.
TABLE_NAME | Nombre de la tabla.
COLUMN_NAME | Nombre de la columna.
DATA_TYPE | El tipo de datos SQL para la columna, representado como un integer.
TYPE_NAME | Una cadena que representa el tipo de datos para la columna.
COLUMN_SIZE | Un integer que representa el tamaño de la columna.
BUFFER_LENGTH | Número máximo de bytes necesarios para almacenar datos de esta columna.
DECIMAL_DIGITS | La escala de la columna o `null` donde la escala no es aplicable.
NUM_PREC_RADIX | Un integer que puede ser `10` (que representa un tipo de datos numérico exacto), `2` (que representa un tipo de datos numéricos aproximado) o `null` (que representa un tipo de datos para el cual la base no es aplicable).
NULLABLE | Un integer que representa si la columna puede ser nula o no.
REMARKS | Descripción de la columna.
COLUMN_DEF | Valor por defecto de la columna.
SQL_DATA_TYPE | Un integer que representa el tamaño de la columna.
SQL_DATETIME_SUB | Devuelve un integer que representa un código de subtipo `datetime` o `null` si los tipos de datos SQL no aplican.
CHAR_OCTET_LENGTH | Tamaño máximo en bytes para los tipos de datos de carácter de la columna, que coincide con COLUMN_SIZE para un solo byte de datos o `null` para un tipo de datos que no son caracteres.
ORDINAL_POSITION | La posición de la columna comenzando desde 1 en la tabla.
IS_NULLABLE | Una cadena cuyo valor es 'YES' significa que la columna es nula y 'NO' significa que la columna no puede ser nula.

### Ver también

- db2_column_privileges() - Devuelve un conjunto de resultados que lista las columnas y sus privilegios de una tabla
- db2_foreign_keys() - Devuelve un conjunto de resultados que lista las claves externas de una tabla
- db2_primary_keys() - Devuelve un conjunto de resultados que lista las claves de una tabla
- db2_procedure_columns() - Devuelve un conjunto de resultados que lista los argumentos de procedimiento de registro
- db2_procedures() - Devuelve un conjunto de resultados que lista las proceduras de registro almacenadas en la base de datos
- db2_special_columns() - Devuelve un conjunto de resultados que lista los identificadores únicos de las filas de una tabla
- db2_statistics() - Devuelve un conjunto de resultados que enumera los índices y estadísticas de una tabla
- db2_table_privileges() - Devuelve un conjunto de resultados que lista las tablas y sus privilegios asociados en una base de datos
- db2_tables() - Devuelve la lista de tablas y sus metadatos

# db2_commit

(PECL ibm_db2 >= 1.0.0)

db2_commit — Confirmar una transacción

### Descripción

function db2_commit(resource `$connection`): bool

Confirma una transacción en progreso en la conexión especificada e inicia una nueva transacción. Las aplicaciones en PHP normalmente confirman las transacciones automáticamente debido a que el modo AUTOCOMMIT por defecto está activado, por lo que el uso de db2_commit() no es necesario a menos que el modo AUTOCOMMIT haya sido desactivado en la conexión especificada.

### Parámetros

`connection`
  Es la conexión válida devuelta por db2_connect() o db2_pconnect().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- db2_autocommit() - Devuelve o modifica el estado AUTOCOMMIT de la conexión a la base de datos
- db2_rollback() - Cancelar una transacción

# db2_conn_error

(PECL ibm_db2 >= 1.0.0)

db2_conn_error — Devuelve un string que contiene el valor de SQLSTATE devuelto por el último intento de conexión

### Descripción

function db2_conn_error(?resource `$connection` = `null`): string

db2_conn_error() devuelve el valor de SQLSTATE que representa la razón por la cual el último intento de conexión a la base de datos ha fallado. Cuando db2_connect() devuelve `false` en caso de un intento de conexión fallido, no se debe pasar ningún argumento a db2_conn_error() para obtener el valor de SQLSTATE.

Si por el contrario la conexión fue exitosa pero se ha vuelto inválida con el tiempo, se puede pasar el argumento de conexión `connection` para obtener el valor de SQLSTATE para la conexión específica.

Para entender los valores de SQLSTATE, se puede ingresar el siguiente comando en el procesador de línea de comandos de DB2: `db2 '? `sqlstate-value`'`. También se puede llamar a la función db2_conn_errormsg() para obtener un mensaje de error explícito junto con el valor de SQLCODE asociado.

### Parámetros

`connection`
  Un recurso de conexión asociado a la conexión que previamente fue exitosa, pero que se ha vuelto inválida con el tiempo.

### Valores devueltos

Devuelve el valor de SQLSTATE resultante de un intento de conexión fallido. Devuelve un string vacío si no hay error asociado con el último intento de conexión.

### Ejemplos

Ejemplo #1 Obtención del valor de SQLSTATE para un intento de conexión fallido

El siguiente ejemplo muestra cómo devolver un valor de SQLSTATE después de pasar un argumento inválido a la función db2_connect().

    <?php
    $conn = db2_connect('mauvaisnom', 'mauvaisutilisateur', 'mauvaismotdepasse');
    if (!$conn) {
        print "Valor de SQLSTATE: " . db2_conn_error();
    }
    ?>

El ejemplo anterior mostrará:

    Valor de SQLSTATE: 08001

### Ver también

- db2_conn_errormsg() - Devuelve el último mensaje de error de conexión junto con el valor de SQLCODE
- db2_connect() - Devuelve una conexión a una base de datos
- db2_stmt_error() - Devuelve un string que contiene el valor de SQLSTATE retornado por una consulta SQL
- db2_stmt_errormsg() - Devuelve el último mensaje de error de una consulta SQL

# db2_conn_errormsg

(PECL ibm_db2 >= 1.0.0)

db2_conn_errormsg — Devuelve el último mensaje de error de conexión junto con el valor de SQLCODE

### Descripción

function db2_conn_errormsg(?resource `$connection` = `null`): string

db2_conn_errormsg() devuelve un mensaje de error y el valor de SQLCODE que representa la razón por la cual el último intento de conexión a la base de datos ha fallado. Cuando db2_connect() devuelve `false` en caso de un intento de conexión fallido, no se debe pasar ningún argumento a db2_conn_errormsg() para obtener el mensaje de error y el valor de SQLCODE.

Si, por el contrario, la conexión fue exitosa pero se ha vuelto inválida con el tiempo, puede pasarse el argumento de conexión `connection` para obtener el mensaje de error y el valor de SQLCODE para la conexión específica.

### Parámetros

`connection`
  Un recurso de conexión asociado a la conexión que previamente fue exitosa, pero que se ha vuelto inválida con el tiempo.

### Valores devueltos

Devuelve una cadena que contiene el mensaje de error y el valor de SQLCODE resultante de un intento de conexión fallido. Devuelve una cadena vacía si no hay error asociado con el último intento de conexión.

### Ejemplos

Ejemplo #1 Obtención del mensaje de error devuelto por un intento de conexión fallido

El siguiente ejemplo muestra cómo devolver un mensaje de error junto con el valor de SQLCODE después de pasar un argumento inválido a la función db2_connect().

    <?php
    $conn = db2_connect('mauvaisnom', 'mauvaisutilisateur', 'mauvaismotdepasse');
    if (!$conn) {
        print db2_conn_errormsg();
    }
    ?>

El ejemplo anterior mostrará:

    [IBM][CLI Driver] SQL1013N  The database alias name
    or database name "MAUVAISNOM" could not be found.  SQLSTATE=42705
     SQLCODE=-1013

### Ver también

- db2_conn_error() - Devuelve un string que contiene el valor de SQLSTATE devuelto por el último intento de conexión
- db2_connect() - Devuelve una conexión a una base de datos
- db2_stmt_error() - Devuelve un string que contiene el valor de SQLSTATE retornado por una consulta SQL
- db2_stmt_errormsg() - Devuelve el último mensaje de error de una consulta SQL

# db2_connect

(PECL ibm_db2 >= 1.0.0)

db2_connect — Devuelve una conexión a una base de datos

### Descripción

function db2_connect(
string `$database`,
?string `$username`,
?string `$password`,
array `$options` = []
): resource|false

Crea una nueva conexión a una base de datos IBM DB2 Universal Database, IBM Cloudscape o Apache Derby.

### Parámetros

`database`
  Para una conexión catalogada de la base de datos, `database` representa el alias de la base de datos en el catálogo cliente DB2

  Para una conexión no catalogada de la base de datos, `database` representa una cadena completa de conexión que está en el formato siguiente :

      DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=password;

  > Nota:

  > Al conectarse a Db2 en IBM i, las llamadas al sistema subyacentes » SQLDriverConnect, solo aceptan DSN, UID y PWD para la » cadena de conexión. Como sigue :

  >     DSN=database;UID=username;PWD=password;

  donde los parámetros representan los siguientes valores :
  `database`
    El nombre de la base de datos.
  `hostname`
    La dirección Internet o IP del servidor de base de datos.
  `port`
    El puerto TCP/IP en el que la base de datos escucha las conexiones.
  `username`
    El nombre de usuario con el que se conecta a la base de datos.
  `password`
    La contraseña con la que se conecta a la base de datos.
`username`
  El nombre de usuario con el que se conecta a la base de datos. Para las conexiones no catalogadas, debe pasar un valor `null` o una cadena vacía.
`password`
  La contraseña con la que se conecta a la base de datos. Para las conexiones no catalogadas, debe pasar un valor `null` o una cadena vacía.
`options`

  Un array asociativo de opciones de conexión que afectarán el comportamiento de la conexión, donde los valores de las claves incluyen :

  `autocommit`
    El valor `DB2_AUTOCOMMIT_ON` activa el autocommit en esta conexión. El valor `DB2_AUTOCOMMIT_OFF` desactiva el autocommit para esta conexión.
  `DB2_ATTR_CASE`
    Pasar el valor `DB2_CASE_NATURAL` especifica que los nombres de columnas serán devueltos en sus casos naturales. Pasar el valor `DB2_CASE_LOWER` especifica que los nombres de columnas serán devueltos en minúsculas. Pasar el valor `DB2_CASE_UPPER` especifica que los nombres de columnas serán devueltos en mayúsculas.
  `CURSOR`
    Pasar el valor `DB2_FORWARD_ONLY` especifica un cursor solo hacia adelante para un recurso de consulta. Este es el tipo de cursor por defecto y es soportado en todos los servidores de base de datos. Pasar el valor `DB2_SCROLLABLE` especifica un cursor desplazable para un recurso de consulta. Este modo permite un acceso aleatorio a las filas en un conjunto de resultados, pero actualmente, solo es soportado por la base de datos IBM DB2 Universal.

  La siguiente nueva opción está disponible para las versiones ibm_db2 1.7.0 y posteriores.

  `trustedcontext`
    Pasar el valor DB2_TRUSTED_CONTEXT_ENABLE activa el contexto para este gestor de conexión. Este parámetro no puede ser definido con la función db2_set_option(). Esta clave solo funciona si la base de datos está catalogada (incluso si la base de datos es local), o si se especifica el DSN completo al crear la conexión. Para catalogar la base de datos, utilice los siguientes comandos :

        db2 catalog tcpip node loopback remote <SERVERNAME> server <SERVICENAME>
        db2 catalog database <LOCALDBNAME> as <REMOTEDBNAME> at node loopback
        db2 "update dbm cfg using svcename <SERVICENAME>"
        db2set DB2COMM=TCPIP

  Las siguientes nuevas opciones i5/OS están disponibles en las versiones ibm_db2 1.5.1 y posteriores.

  `i5_lib`
    Un carácter que indica la biblioteca por defecto que será utilizada para resolver las referencias a los ficheros no calificados. Esto no es válido si la conexión utiliza un modo de sistema de nombres.
  `i5_naming`
    El valor `DB2_I5_NAMING_ON` activa el modo sistema de nombres DB2 UDB CLI iSeries. Los ficheros son calificados utilizando el delimitador barra (/). Los ficheros no calificados son resueltos utilizando la lista de bibliotecas para el trabajo. El valor `DB2_I5_NAMING_OFF` desactiva el modo de nombres por defecto de DB2 UDB CLI, que es la escritura SQL. Los ficheros son calificados utilizando el delimitador punto (.). Los ficheros no calificados son resueltos utilizando la biblioteca por defecto o el ID del usuario actual.
  `i5_commit`
    El atributo `i5_commit` debe ser fijado antes de la llamada a db2_connect(). Si el valor es cambiado después de que la conexión haya sido establecida y la conexión es a una fuente de datos remota, el cambio solo tendrá efecto en la próxima llamada a db2_connect().

    > Nota: La configuración php.ini `ibm_db2.i5_allow_commit`==0 o `DB2_I5_TXN_NO_COMMIT` es por defecto, pero puede ser derivada con la opción `i5_commit`.

    `DB2_I5_TXN_NO_COMMIT` : no se utiliza el control de envío. `DB2_I5_TXN_READ_UNCOMMITTED` : lectura antigua, lectura no repetitiva y ficticia es posible. `DB2_I5_TXN_READ_COMMITTED` : lectura antigua no posible. La lectura repetitiva y ficticia es posible. `DB2_I5_TXN_REPEATABLE_READ` : lectura antigua y no repetitiva no es posible. Lectura ficticia es posible. `DB2_I5_TXN_SERIALIZABLE` : las transacciones son serializadas. Lectura antigua, no repetitiva y ficticia no es posible.
  `i5_query_optimize`
    `DB2_FIRST_IO` Todas las consultas son optimizadas con el objetivo de devolver la primera página tan rápido como sea posible. Este objetivo funciona bien cuando la visualización es controlada por un usuario que puede cancelar una consulta después de ver la primera página de los datos. Las consultas son codificadas con una cláusula `"OPTIMIZE nnn ROWS"` para cumplir el objetivo especificado por la cláusula. `DB2_ALL_IO` Todas las consultas son optimizadas con el objetivo de devolver la consulta completa en el menor intervalo de tiempo. Esta es una buena opción cuando la visualización de una consulta está siendo escrita hacia un fichero o un informe o cuando la interfaz pone en cola los datos. Las consultas son codificadas con una cláusula `"OPTIMIZE FOR nnn ROWS"` para cumplir el objetivo especificado por la cláusula. Esta es la operación por defecto.
  `i5_dbcs_alloc`
    El valor `DB2_I5_DBCS_ALLOC_ON` activa el esquema de asignación DB2 6X para el incremento de los tamaños de columnas. El valor `DB2_I5_DBCS_ALLOC_OFF` desactiva el esquema de asignación DB2 6X para el incremento de los tamaños de columnas. Nota : la configuración php.ini `ibm_db2.i5_dbcs_alloc`==0 o `DB2_I5_DBCS_ALLOC_OFF` es por defecto pero puede ser derivada con la opción `i5_dbcs_alloc`.
  `i5_date_fmt`
    `DB2_I5_FMT_ISO` : se utiliza el formato de fecha de la organización internacional de normalización (ISO) `"yyyy-mm-dd"`. Este es el valor por defecto. `DB2_I5_FMT_USA` : se utiliza el formato de fecha de los Estados Unidos `"mm/dd/yyyy"`. `DB2_I5_FMT_EUR` : se utiliza el formato de fecha Europeo `"dd.mm.yyyy"`. `DB2_I5_FMT_JIS` : se utiliza el formato de fecha de la industria japonesa de estándares `"yyyy-mm-dd"`. `DB2_I5_FMT_MDY` : se utiliza el formato de fecha `"mm/dd/yyyy"`. `DB2_I5_FMT_DMY` : se utiliza el formato de fecha `"dd/mm/yyyy"`. `DB2_I5_FMT_YMD` : se utiliza el formato de fecha `"yy/mm/dd"`. `DB2_I5_FMT_JUL` : se utiliza el formato de fecha Juliano `"yy/ddd"`. `DB2_I5_FMT_JOB` : se utiliza el valor por defecto.
  `i5_date_sep`
    `DB2_I5_SEP_SLASH` : se utiliza una barra ( / ) como separador de fecha. Este es el valor por defecto. `DB2_I5_SEP_DASH` : se utiliza un guión ( - ) como separador de fecha. `DB2_I5_SEP_PERIOD` : se utiliza un punto ( . ) como separador de fecha. `DB2_I5_SEP_COMMA` : se utiliza una coma ( , ) como separador de fecha. `DB2_I5_SEP_BLANK` : se utiliza un espacio en blanco como separador de fecha. `DB2_I5_SEP_JOB` : se utiliza el valor por defecto.
  `i5_time_fmt`
    `DB2_I5_FMT_ISO` : se utiliza el formato de hora de la organización internacional de normalización `"hh.mm.ss"`. Este es el valor por defecto. `DB2_I5_FMT_USA` : se utiliza el formato de hora de los Estados Unidos `"hh:mmxx"`, donde `"xx"` vale `"AM"` o `"PM"`. `DB2_I5_FMT_EUR` : se utiliza el formato de hora Europeo `"hh.mm.ss"`. `DB2_I5_FMT_JIS` : se utiliza el formato de hora de la industria japonesa de estándares `"hh:mm:ss"`. `DB2_I5_FMT_HMS` : se utiliza el formato `"hh:mm:ss"`.
  `i5_time_sep`
    `DB2_I5_SEP_COLON` : se utiliza un dos puntos ( : ) como separador de tiempo. Este es el valor por defecto. `DB2_I5_SEP_PERIOD` : se utiliza un punto ( . ) como separador de tiempo. `DB2_I5_SEP_COMMA` : se utiliza una coma ( , ) como separador de tiempo. `DB2_I5_SEP_BLANK` : se utiliza un espacio en blanco como separador de tiempo. `DB2_I5_SEP_JOB` : se utiliza el valor por defecto.
  `i5_decimal_sep`
    `DB2_I5_SEP_PERIOD` : se utiliza un punto ( . ) como separador decimal. Este es el valor por defecto. `DB2_I5_SEP_COMMA` : se utiliza una coma ( , ) como separador decimal. `DB2_I5_SEP_JOB` : se utiliza el valor por defecto.

  La siguiente nueva opción i5/OS está disponible desde la versión ibm_db2 1.8.0 y posteriores.

  `i5_libl`
    Una cadena que indica la lista a utilizar para resolver las referencias de ficheros no calificados. Especifique la lista separando los valores con un espacio, como sigue : 'i5_libl'=>"MYLIB YOURLIB ANYLIB".

    > Nota: `i5_libl` llama a `qsys2/qcmdexc('cmd',cmdlen)`, que solo está disponible desde i5/OS V5R4.

### Valores devueltos

Devuelve el recurso de conexión si la tentativa de conexión tiene éxito. Si la tentativa de conexión falla, db2_connect() devuelve `false`.

### Ejemplos

Ejemplo #1 Creación de una conexión catalogada

Las conexiones catalogadas requieren que haya catalogado previamente la base de datos especificada utilizando el procesador de línea de comandos DB2 (`"Command Line Processor"` : cLP) o con el asistente de configuración de DB2.

    <?php
    $database = 'EJEMPLO';
    $user = 'db2inst1';
    $password = 'ibmdb2';

    $conn = db2_connect($database, $user, $password);

    if ($conn) {
        echo "Conexión exitosa.";
        db2_close($conn);
    }
    else {
        echo "Conexión fallida.";
    }
    ?>

El ejemplo anterior mostrará:

    Conexión exitosa.

Ejemplo #2 Creación de una conexión no catalogada

Una conexión no catalogada permite conectarse dinámicamente a una base de datos.

    <?php
    $database = 'EJEMPLO';
    $user = 'db2inst1';
    $password = 'ibmdb2';
    $hostname = 'localhost';
    $port = 50000;

    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;" .
      "HOSTNAME=$hostname;PORT=$port;PROTOCOL=TCPIP;UID=$user;PWD=$password;";
    $conn = db2_connect($conn_string, '', '');

    if ($conn) {
        echo "Conexión exitosa.";
        db2_close($conn);
    }
    else {
        echo "Conexión fallida.";
    }
    ?>

El ejemplo anterior mostrará:

    Conexión exitosa.

Ejemplo #3 Creación de una conexión con autocommit desactivado por defecto

Pasar un array de opciones a db2_connect() permite modificar el comportamiento por defecto de la conexión.

    <?php
    $database = 'EJEMPLO';
    $user = 'db2inst1';
    $password = 'ibmdb2';
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF);

    $conn = db2_connect($database, $user, $password, $options);

    if ($conn) {
        echo "Conexión exitosa.\n";
        if (db2_autocommit($conn)) {
             echo "Autocommit está activado.\n";
        }
        else {
             echo "Autocommit está desactivado.\n";
        }
        db2_close($conn);
    }
    else {
        echo "Conexión fallida.";
    }
    ?>

El ejemplo anterior mostrará:

    Conexión exitosa.
    Autocommit está desactivado.

Ejemplo #4 Mejor rendimiento i5/OS

Para lograr utilizar el mejor rendimiento de su i5/OS ibm_db2 1.5.1, la aplicación PHP utiliza el host por defecto, el userid y la contraseña para su db2_connect().

    <?php
      $library = "ADC";
      $i5 = db2_connect("", "", "", array("i5_lib"=>"qsys2"));
      $result = db2_exec($i5,
           "select * from systables where table_schema = '$library'");
      while ($row = db2_fetch_both($result)) {
         echo $row['TABLE_NAME']."</br>";
      }
      db2_close($i5);
    ?>

El ejemplo anterior mostrará:

    ANIMALS
    NAMES
    PICTURES

Ejemplo #5 Utilización del contexto

El siguiente ejemplo muestra cómo activar el contexto, cambiar de usuario y recuperar el ID del usuario actual.

    <?php

    $database = "SAMPLE";
    $hostname = "localhost";
    $port = 50000;
    $authID = "db2inst1";
    $auth_pass = "ibmdb2";

    $tc_user = "tcuser";
    $tc_pass = "tcpassword";

    $dsn = "DATABASE=$database;HOSTNAME=$hostname;PORT=$port;
      PROTOCOL=TCPIP;UID=$authID;PWD=$auth_pass;";
    $options = array ("trustedcontext" => DB2_TRUSTED_CONTEXT_ENABLE);

    $tc_conn = db2_connect($dsn, "", "", $options);
    if($tc_conn) {
        echo "Conexión de confianza explícita exitosa.\n";

        if(db2_get_option($tc_conn, "trustedcontext")) {
            $userBefore = db2_get_option($tc_conn, "trusted_user");

            //Código como usuario 1.

            //Cambio al usuario de confianza.
            $parameters = array("trusted_user" => $tc_user,
              "trusted_password" => $tcuser_pass);
            $res = db2_set_option ($tc_conn, $parameters, 1);

            $userAfter = db2_get_option($tc_conn, "trusted_user");
            //Código como usuario de confianza.

            if($userBefore != $userAfter) {
                echo "El usuario ha cambiado." . "\n";
            }
        }

        db2_close($tc_conn);
    }
    else {
        echo "El cambio de contexto de conexión ha fallado.\n";
    }
    ?>

El ejemplo anterior mostrará:

    El cambio de contexto de conexión ha fallado.
    El usuario ha cambiado.

### Ver también

- db2_close() - Cierra una conexión a base de datos
- db2_pconnect() - Devuelve una conexión persistente a una base de datos

# db2_cursor_type

(PECL ibm_db2 >= 1.0.0)

db2_cursor_type — Devuelve el tipo de cursor utilizado por un recurso

### Descripción

function db2_cursor_type(resource `$stmt`): int

Devuelve el tipo de cursor utilizado por un recurso. Utilice esta función para determinar si se trabaja con un cursor de avance solo o un cursor flotante.

### Parámetros

`stmt`
  Un recurso válido.

### Valores devueltos

Devuelve `DB2_FORWARD_ONLY` si el recurso utiliza un cursor de avance solo o `DB2_SCROLLABLE` si el recurso utiliza un cursor flotante.

### Ver también

- db2_prepare() - Prepara una consulta SQL para ser ejecutada

# db2_escape_string

(PECL ibm_db2 >= 1.6.0)

db2_escape_string — Escapar ciertos caracteres especiales

### Descripción

function db2_escape_string(string `$string_literal`): string

Agrega un caracter de escape (barra invertida) antes de cada caracter especial de la cadena enviada como parámetro.

### Parámetros

`string_literal`
  La cadena que contiene los caracteres especiales y que necesita ser escapada. Los caracteres especiales a los que se les agrega el caracter de escape son `\x00`, `\n`, `\r`, `\`, `'`, `"` y `\x1a`.

### Valores devueltos

Devuelve `string_literal` con todos los caracteres especiales ya escapados.

### Ejemplos

Ejemplo #1 Ejemplo de db2_escape_string()

Resultado del uso de la función db2_escape_string()

    <?php

    $conn = db2_connect($database, $user, $password);

    if ($conn) {
        $str[0] = "Todos los caracteres: \x00 , \n , \r , \ , ' , \" , \x1a .";
        $str[1] = "Barra invertida (\). Comilla simple ('). Comilla doble (\")";
        $str[2] = "El caracter NULL \0 debe ser citado también";
        $str[3] = "Caracteres interesantes: \x1a , \x00 .";
        $str[4] = "Nada que citar";
        $str[5] = 200676;
        $str[6] = "";

        foreach( $str as $string ) {
            echo "db2_escape_string: " . db2_escape_string($string). "\n";
        }
    }
    ?>

El ejemplo anterior mostrará:

    db2_escape_string: Todos los caracteres: \0 , \n , \r , \\ , \' , \" , \Z .
    db2_escape_string: Barra invertida (\\). Comilla simple (\'). Comilla doble (\")
    db2_escape_string: El caracter NULL \0 debe ser citado también
    db2_escape_string: Caracteres interesantes: \Z , \0 .
    db2_escape_string: Nada que citar
    db2_escape_string: 200676
    db2_escape_string:

### Ver también

- db2_prepare() - Prepara una consulta SQL para ser ejecutada

# db2_exec

(PECL ibm_db2 >= 1.0.0)

db2_exec — Ejecuta una consulta SQL directamente

### Descripción

function db2_exec(resource `$connection`, string `$statement`, array `$options` = []): resource|false

Ejecuta una consulta SQL directamente.

Si se prevé insertar variables PHP en la consulta SQL, debe entenderse que esto es una de las fallas de seguridad más comunes. Se recomienda llamar a la función db2_prepare() para preparar una consulta SQL que contenga marcadores para variables de entrada. Posteriormente, puede llamarse a la función db2_execute() para pasar los valores de entrada y así evitar ataques por inyección SQL.

Si se prevé llamar repetidamente a la misma consulta SQL con diferentes parámetros, se recomienda utilizar las funciones db2_prepare() y db2_execute() para permitir que el servidor de base de datos reutilice su plan de acceso y así mejorar la eficiencia del acceso a la base de datos.

### Parámetros

`connection`
  Una variable de tipo resource de conexión válida devuelta por db2_connect() o db2_pconnect().
`statement`
  Una consulta SQL. La consulta no puede contener marcadores.
`options`
  Un array asociativo que contiene las opciones de la consulta. Este parámetro puede utilizarse para solicitar un cursor flotante en los servidores de base de datos que soportan esta funcionalidad. Para obtener una descripción de las opciones válidas, consulte la función db2_set_option().

### Valores devueltos

Devuelve una variable de tipo resource si la consulta SQL fue enviada correctamente o `false` si la base de datos no pudo ejecutar la consulta SQL.

### Ejemplos

Ejemplo #1 Creación de una tabla con db2_exec()

El siguiente ejemplo utiliza la función db2_exec() para enviar un conjunto de consultas DDL con el fin de crear una tabla.

    <?php
    $conn = db2_connect($database, $user, $password);

    // Crear la tabla de prueba
    $create = 'CREATE TABLE animales (id INTEGER, raza VARCHAR(32),
        nombre CHAR(16), peso DECIMAL(7,2))';
    $result = db2_exec($conn, $create);
    if ($result) {
        print "La tabla se ha creado correctamente.\n";
    }

    // Rellenar la tabla de prueba
    $animales = array(
        array(0, 'gato', 'Pook', 3.2),
        array(1, 'perro', 'Peaches', 12.3),
        array(2, 'caballo', 'Smarty', 350.0),
        array(3, 'pez dorado', 'Bubbles', 0.1),
        array(4, 'periquito', 'Gizmo', 0.2),
        array(5, 'cabra', 'Rickety Ride', 9.7),
        array(6, 'llama', 'Sweater', 150)
    );

    foreach ($animales as $animal) {
        $rc = db2_exec($conn, "INSERT INTO animales (id, raza, nombre, peso)
          VALUES ({$animal[0]}, '{$animal[1]}', '{$animal[2]}', {$animal[3]})");
        if ($rc) {
            print "Inserción... ";
        }
    }
    ?>

El ejemplo anterior mostrará:

    La tabla se ha creado correctamente.
    Inserción... Inserción... Inserción... Inserción... Inserción... Inserción... Inserción...

Ejemplo #2 Ejecución de una consulta SELECT con un cursor flotante

El siguiente ejemplo muestra cómo solicitar un cursor flotante para una consulta SQL enviada con la función db2_exec().

    <?php
    $conn = db2_connect($database, $user, $password);
    $sql = "SELECT nombre FROM animales
        WHERE peso < 10.0
        ORDER BY nombre";
    if ($conn) {
        require_once 'prepare.inc';
        $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
        while ($row = db2_fetch_array($stmt)) {
            print "$row[0]\n";
        }
    }
    ?>

El ejemplo anterior mostrará:

    Bubbles
    Gizmo
    Pook
    Rickety Ride

Ejemplo #3 Devuelve datos XML como ResultSet SQL

El siguiente ejemplo demuestra cómo utilizar documentos almacenados en una columna XML utilizando la base de datos SAMPLE. Mediante un simple SQL/XML, este ejemplo devuelve algunos nodos en un documento XML en un formato ResultSet SQL con el que la mayoría de los usuarios están familiarizados.

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = 'SELECT * FROM XMLTABLE(
        XMLNAMESPACES (DEFAULT \'http://posample.org\'),
        \'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
        COLUMNS
        "CID" VARCHAR (50) PATH \'@Cid\',
        "NAME" VARCHAR (50) PATH \'name\',
        "PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
        ) AS T
        WHERE NAME = \'Kathy Smith\'
        ';
    $stmt = db2_exec($conn, $query);

    while($row = db2_fetch_object($stmt)){
        printf("$row->CID     $row->NAME     $row->PHONE\n");
    }
    db2_close($conn);

    ?>

El ejemplo anterior mostrará:

    1000     Kathy Smith     416-555-1358
    1001     Kathy Smith     905-555-7258

Ejemplo #4 Ejecutar un "JOIN" con datos XML

El siguiente ejemplo trabaja con documentos almacenados en dos columnas diferentes en la base de datos SAMPLE. Esto crea dos tablas temporales provenientes de los documentos XML de dos columnas XML diferentes y devuelve un ResultSet SQL con la información que contiene el estado de envío para un cliente.

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = '
        SELECT A.CID, A.NAME, A.PHONE, C.PONUM, C.STATUS
        FROM
        XMLTABLE(
        XMLNAMESPACES (DEFAULT \'http://posample.org\'),
        \'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
        COLUMNS
        "CID" BIGINT PATH \'@Cid\',
        "NAME" VARCHAR (50) PATH \'name\',
        "PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
        ) as A,
        PURCHASEORDER AS B,
        XMLTABLE (
        XMLNAMESPACES (DEFAULT \'http://posample.org\'),
        \'db2-fn:xmlcolumn("PURCHASEORDER.PORDER")/PurchaseOrder\'
        COLUMNS
        "PONUM"  BIGINT PATH \'@PoNum\',
        "STATUS" VARCHAR (50) PATH \'@Status\'
        ) as C
        WHERE A.CID = B.CUSTID AND
     B.POID = C.PONUM AND
     A.NAME = \'Kathy Smith\'
    ';

    $stmt = db2_exec($conn, $query);

    while($row = db2_fetch_object($stmt)){
        printf("$row->CID     $row->NAME     $row->PHONE     $row->PONUM     $row->STATUS\n");
    }

    db2_close($conn);

    ?>

El ejemplo anterior mostrará:

    1001     Kathy Smith     905-555-7258     5002     Shipped

Ejemplo #5 Devuelve datos SQL que forman parte de un documento XML grande

El siguiente ejemplo utiliza una porción de los documentos de PRODUCT.DESCRIPTION en la base de datos SAMPLE. Esto crea un documento XML que contiene la descripción del producto (datos XML) y la información sobre el precio (datos SQL).

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = '
    SELECT
    XMLSERIALIZE(
    XMLQUERY(\'
        declare boundary-space strip;
        declare default element namespace "http://posample.org";
        <promoList> {
            for $prod in $doc/product
            where $prod/description/price < 10.00
            order by $prod/description/price ascending
            return(
                <promoitem> {
                    $prod,
                    <startdate> {$start} </startdate>,
                    <enddate> {$end} </enddate>,
                    <promoprice> {$promo} </promoprice>
                } </promoitem>
            )
        } </promoList>
    \' passing by ref DESCRIPTION AS "doc",
    PROMOSTART as "start",
    PROMOEND as "end",
    PROMOPRICE as "promo"
    RETURNING SEQUENCE)
    AS CLOB (32000))
    AS NEW_PRODUCT_INFO
    FROM PRODUCT
    WHERE PID = \'100-100-01\'
    ';

    $stmt = db2_exec($conn, $query);

    while($row = db2_fetch_array($stmt)){
     printf("$row[0]\n");
    }
    db2_close($conn);

    ?>

El ejemplo anterior mostrará:

    <promoList xmlns="http://posample.org">
        <promoitem>
        <product pid="100-100-01">
            <description>
                <name>Snow Shovel, Basic 22 inch</name>
                <details>Basic Snow Shovel, 22 inches wide, straight handle with D-Grip</details>
                <price>9.99</price>
                <weight>1 kg</weight>
            </description>
        </product>
        <startdate>2004-11-19</startdate>
        <enddate>2004-12-19</enddate>
        <promoprice>7.25</promoprice>
        </promoitem>
    </promoList>

### Ver también

- db2_execute() - Ejecuta una consulta SQL preparada
- db2_prepare() - Prepara una consulta SQL para ser ejecutada

# db2_execute

(PECL ibm_db2 >= 1.0.0)

db2_execute — Ejecuta una consulta SQL preparada

### Descripción

function db2_execute(resource `$stmt`, array `$parameters` = []): bool

db2_execute() ejecuta una consulta SQL que ha sido preparada por db2_prepare().

Si la consulta SQL devuelve un conjunto de resultados, por ejemplo, una consulta SELECT o CALL a un procedimiento de registro devuelve uno o varios conjuntos de resultados, puede recuperar una fila como un array a partir de la recurso `stmt` utilizando db2_fetch_assoc(), db2_fetch_both() o db2_fetch_array(). Alternativamente, puede utilizar db2_fetch_row() para mover el puntero a la fila siguiente y recuperar una columna a la vez de esta fila con la función db2_result().

Consúltese db2_prepare() para una breve discusión sobre las ventajas de utilizar db2_prepare() y db2_execute() en lugar de db2_exec().

### Parámetros

`stmt`
  Una consulta preparada devuelta por db2_prepare().
`parameters`
  Un array de parámetros de entrada que contiene los marcadores de variables contenidos en la consulta preparada.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Preparación y ejecución de una consulta SQL con marcadores

El siguiente ejemplo prepara una consulta INSERT que acepta cuatro marcadores, luego itera sobre el array que contiene los valores de entrada que será pasado a la función db2_execute().

    <?php
    $pet = array(0, 'chat', 'Pook', 3.2);

    $insert = 'INSERT INTO animales (id, raza, nombre, peso)
        VALUES (?, ?, ?, ?)';

    $stmt = db2_prepare($conn, $insert);
    if ($stmt) {
        $result = db2_execute($stmt, $pet);
        if ($result) {
            print "Añadido un nuevo animal con éxito.";
        }
    }
    ?>

El ejemplo anterior mostrará:

    Añadido un nuevo animal con éxito.

Ejemplo #2 Llamada a un procedimiento de registro con un parámetro de SALIDA

El siguiente ejemplo prepara una consulta CALL que acepta un marcador que representa un parámetro de SALIDA, vincula la variable PHP `$my_pets` al parámetro utilizando la función db2_bind_param() y llama a la función db2_execute() para ejecutar la consulta CALL. Una vez que la consulta CALL ha sido ejecutada, el valor de `$num_pets` cambia para reflejar el valor devuelto por el procedimiento de registro para este parámetro de SALIDA.

    <?php
    $num_pets = 0;
    $res = db2_prepare($conn, "CALL count_my_pets(?)");
    $rc = db2_bind_param($res, 1, "num_pets", DB2_PARAM_OUT);
    $rc = db2_execute($res);
    print "Tengo $num_pets animales !";
    ?>

El ejemplo anterior mostrará:

    Tengo 7 animales !

Ejemplo #3 Devuelve datos XML como ResultSet SQL

El siguiente ejemplo demuestra cómo utilizar documentos almacenados en una columna XML utilizando la base de datos SAMPLE. Utilizando un simple SQL/XML, este ejemplo devuelve algunos nodos en un documento XML en un formato ResultSet SQL con el que la mayoría de los usuarios están familiarizados.

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = 'SELECT * FROM XMLTABLE(
        XMLNAMESPACES (DEFAULT \'http://posample.org\'),
        \'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
        COLUMNS
        "CID" VARCHAR (50) PATH \'@Cid\',
        "NAME" VARCHAR (50) PATH \'name\',
        "PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
        ) AS T
        WHERE NAME = ?
        ';

    $stmt = db2_prepare($conn, $query);

    $name = 'Kathy Smith';

    if ($stmt) {
        db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
        db2_execute($stmt);

        while($row = db2_fetch_object($stmt)){
            printf("$row->CID     $row->NAME     $row->PHONE\n");
        }
    }
    db2_close($conn);

    ?>

El ejemplo anterior mostrará:

    1000     Kathy Smith     416-555-1358
    1001     Kathy Smith     905-555-7258

Ejemplo #4 Ejecutar un "JOIN" con datos XML

El siguiente ejemplo trabaja con documentos almacenados en dos columnas diferentes en la base de datos SAMPLE. Esto crea dos tablas temporales a partir de los documentos XML de dos diferentes columnas XML y devuelve un ResultSet SQL con la información que contiene el estado de envío para un cliente.

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = '
    SELECT A.CID, A.NAME, A.PHONE, C.PONUM, C.STATUS
    FROM
    XMLTABLE(
    XMLNAMESPACES (DEFAULT \'http://posample.org\'),
    \'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
    COLUMNS
    "CID" BIGINT PATH \'@Cid\',
    "NAME" VARCHAR (50) PATH \'name\',
    "PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
    ) as A,
    PURCHASEORDER AS B,
    XMLTABLE (
    XMLNAMESPACES (DEFAULT \'http://posample.org\'),
    \'db2-fn:xmlcolumn("PURCHASEORDER.PORDER")/PurchaseOrder\'
    COLUMNS
    "PONUM"  BIGINT PATH \'@PoNum\',
    "STATUS" VARCHAR (50) PATH \'@Status\'
    ) as C
    WHERE A.CID = B.CUSTID AND
            B.POID = C.PONUM AND
            A.NAME = ?
    ';

    $stmt = db2_prepare($conn, $query);

    $name = 'Kathy Smith';

    if ($stmt) {
        db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
        db2_execute($stmt);

        while($row = db2_fetch_object($stmt)){
            printf("$row->CID     $row->NAME     $row->PHONE     $row->PONUM     $row->STATUS\n");
        }
    }

    db2_close($conn);

    ?>

El ejemplo anterior mostrará:

    1001     Kathy Smith     905-555-7258     5002     Shipped

Ejemplo #5 Devuelve datos SQL que forman parte de un documento XML grande

El siguiente ejemplo utiliza una porción de los documentos de PRODUCT.DESCRIPTION en la base de datos SAMPLE. Esto crea un documento XML que contiene la descripción del producto (datos XML) y las informaciones concernientes al precio (datos SQL).

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = '
    SELECT
    XMLSERIALIZE(
    XMLQUERY(\'
        declare boundary-space strip;
        declare default element namespace "http://posample.org";
        <promoList> {
            for $prod in $doc/product
            where $prod/description/price < 10.00
            order by $prod/description/price ascending
            return(
                <promoitem> {
                    $prod,
                    <startdate> {$start} </startdate>,
                    <enddate> {$end} </enddate>,
                    <promoprice> {$promo} </promoprice>
                } </promoitem>
            )
        } </promoList>
    \' passing by ref DESCRIPTION AS "doc",
    PROMOSTART as "start",
    PROMOEND as "end",
    PROMOPRICE as "promo"
    RETURNING SEQUENCE)
    AS CLOB (32000))
    AS NEW_PRODUCT_INFO
    FROM PRODUCT
    WHERE PID = ?
    ';

    $stmt = db2_prepare($conn, $query);

    $pid = "100-100-01";

    if ($stmt) {
        db2_bind_param($stmt, 1, "pid", DB2_PARAM_IN);
        db2_execute($stmt);

        while($row = db2_fetch_array($stmt)){
            printf("$row[0]\n");
        }
    }

    db2_close($conn);

    ?>

El ejemplo anterior mostrará:

    <promoList xmlns="http://posample.org">
        <promoitem>
        <product pid="100-100-01">
            <description>
                <name>Snow Shovel, Basic 22 inch</name>
                <details>Basic Snow Shovel, 22 inches wide, straight handle with D-Grip</details>
                <price>9.99</price>
                <weight>1 kg</weight>
            </description>
        </product>
        <startdate>2004-11-19</startdate>
        <enddate>2004-12-19</enddate>
        <promoprice>7.25</promoprice>
        </promoitem>
    </promoList>

### Ver también

- db2_exec() - Ejecuta una consulta SQL directamente
- db2_fetch_array() - Devuelve un array, indexado por la posición de las columnas, que representa una línea del conjunto de resultados
- db2_fetch_assoc() - Devuelve un array, indexado por nombre de columna, que representa una fila del conjunto de resultados
- db2_fetch_both() - Devuelve un array, indexado por nombre de columna y posición, que representa una fila del conjunto de resultados
- db2_fetch_row() - Modifica el puntero del conjunto de resultados a la siguiente línea o a la línea solicitada
- db2_prepare() - Prepara una consulta SQL para ser ejecutada
- db2_result() - Devuelve un valor de una columna de una fila de un conjunto de resultados

# db2_fetch_array

(PECL ibm_db2 >= 1.0.1)

db2_fetch_array — Devuelve un array, indexado por la posición de las columnas, que representa una línea del conjunto de resultados

### Descripción

function db2_fetch_array(resource `$stmt`, int `$row_number` = -1): array|false

Devuelve un array, indexado por la posición de las columnas, que representa una línea del conjunto de resultados. Los índices del array son numéricos y comienzan por cero.

### Parámetros

`stmt`
  Un recurso `stmt` válido que contiene el conjunto de resultados.
`row_number`
  Solicita una línea específica indexada numéricamente que comienza con el valor 1 en el conjunto de resultados. Al proporcionar este argumento, se generará una advertencia PHP si el conjunto de resultados utiliza un cursor de avance solo.

### Valores devueltos

Devuelve un array con índices numéricos comenzando en 0 indexado con la posición de las columnas. Este índice apunta a los datos de la siguiente línea o la línea solicitada en el conjunto de resultados. Devuelve `false` si no hay una línea disponible en el conjunto de resultados o si la línea solicitada por `row_number` no existe en el conjunto de resultados.

### Ejemplos

Ejemplo #1 Iteración con un cursor de avance solo

Si se llama a db2_fetch_array() sin el número de una línea específica, la siguiente línea se recuperará automáticamente en el conjunto de resultados.

    <?php

    $sql = "SELECT id, nom, race, poids FROM animaux ORDER BY race";
    $stmt = db2_prepare($conn, $sql);
    $result = db2_execute($stmt);

    while ($row = db2_fetch_array($stmt)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row[0], $row[1], $row[2], $row[3]);
    }
    ?>

El ejemplo anterior mostrará:

    0     Pook             chat                                   3.20
    5     Rickety Ride     chèvre                                 9.70
    2     Smarty           cheval                               350.00

Ejemplo #2 Recuperación de líneas específicas con db2_fetch_array() a partir de un cursor flotante

Si su conjunto de resultados utiliza un cursor flotante, puede llamar a la función db2_fetch_array() con un número de línea específico. El siguiente ejemplo recupera cada línea par en el conjunto de resultados, comenzando con la segunda línea.

    <?php

    $sql = "SELECT id, nom, race, poids FROM animaux ORDER BY race";
    $result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));

    $i=2;
    while ($row = db2_fetch_array($result, $i)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row[0], $row[1], $row[2], $row[3]);
        $i = $i + 2;
    }
    ?>

El ejemplo anterior mostrará:

    0     Pook             chat                                   3.20
    5     Rickety Ride     chèvre                                 9.70
    2     Smarty           cheval                               350.00

### Ver también

- db2_fetch_assoc() - Devuelve un array, indexado por nombre de columna, que representa una fila del conjunto de resultados
- db2_fetch_both() - Devuelve un array, indexado por nombre de columna y posición, que representa una fila del conjunto de resultados
- db2_fetch_object() - Devuelve un objeto con las propiedades que representan columnas en la fila extraída
- db2_fetch_row() - Modifica el puntero del conjunto de resultados a la siguiente línea o a la línea solicitada
- db2_result() - Devuelve un valor de una columna de una fila de un conjunto de resultados

# db2_fetch_assoc

(PECL ibm_db2 >= 1.0.0)

db2_fetch_assoc — Devuelve un array, indexado por nombre de columna, que representa una fila del conjunto de resultados

### Descripción

function db2_fetch_assoc(resource `$stmt`, int `$row_number` = -1): array|false

Devuelve un array, indexado por nombre de columna, que representa una fila del conjunto de resultados.

### Parámetros

`stmt`
  Un recurso `stmt` válido que contiene el conjunto de resultados.
`row_number`
  Solicita una fila específica indexada numéricamente que comienza con el valor 1 en el conjunto de resultados. Al proporcionar este argumento, se generará una advertencia PHP si el conjunto de resultados utiliza un cursor de avance solo.

### Valores devueltos

Devuelve un array asociativo con los valores de las columnas indexados por el nombre de las columnas que representan la siguiente fila o la fila solicitada en el conjunto de resultados. Devuelve `false` si no hay una fila disponible en el conjunto de resultados o si la fila solicitada por `row_number` no existe en el conjunto de resultados.

### Ejemplos

Ejemplo #1 Iteración con un cursor de avance solo

Si se llama a db2_fetch_assoc() sin el número de una fila específica, se recuperará automáticamente la siguiente fila en el conjunto de resultados.

    <?php

    $sql = "SELECT id, nom, race, poids FROM animaux ORDER BY race";
    $stmt = db2_prepare($conn, $sql);
    $result = db2_execute($stmt);

    while ($row = db2_fetch_assoc($stmt)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row['ID'], $row['NOM'], $row['RACE'], $row['POIDS']);
    }
    ?>

El ejemplo anterior mostrará:

    0     Pook             chat                                   3.20
    5     Rickety Ride     chèvre                                 9.70
    2     Smarty           cheval                               350.00

Ejemplo #2 Recuperación de filas específicas con db2_fetch_assoc() desde un cursor flotante

Si su conjunto de resultados utiliza un cursor flotante, puede llamar a la función db2_fetch_assoc() con un número de fila específico. El siguiente ejemplo recupera cada fila par en el conjunto de resultados, comenzando con la segunda fila.

    <?php

    $sql = "SELECT id, nom, race, poids FROM animaux ORDER BY race";
    $result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));

    $i=2;
    while ($row = db2_fetch_assoc($result, $i)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row['ID'], $row['NOM'], $row['RACE'], $row['POIDS']);
        $i = $i + 2;
    }
    ?>

El ejemplo anterior mostrará:

    0     Pook             chat                                   3.20
    5     Rickety Ride     chèvre                                 9.70
    2     Smarty           cheval                               350.00

### Ver también

- db2_fetch_array() - Devuelve un array, indexado por la posición de las columnas, que representa una línea del conjunto de resultados
- db2_fetch_both() - Devuelve un array, indexado por nombre de columna y posición, que representa una fila del conjunto de resultados
- db2_fetch_object() - Devuelve un objeto con las propiedades que representan columnas en la fila extraída
- db2_fetch_row() - Modifica el puntero del conjunto de resultados a la siguiente línea o a la línea solicitada
- db2_result() - Devuelve un valor de una columna de una fila de un conjunto de resultados

# db2_fetch_both

(PECL ibm_db2 >= 1.0.0)

db2_fetch_both — Devuelve un array, indexado por nombre de columna y posición, que representa una fila del conjunto de resultados

### Descripción

function db2_fetch_both(resource `$stmt`, int `$row_number` = -1): array|false

Devuelve un array, indexado por nombre de columna y posición, que representa una fila del conjunto de resultados. Tenga en cuenta que la fila devuelta por db2_fetch_both() requiere más memoria que los arrays simplemente indexados devueltos por db2_fetch_assoc() o db2_fetch_array().

### Parámetros

`stmt`
  Un recurso `stmt` válido que contiene el conjunto de resultados.
`row_number`
  Solicita una fila específica indexada numéricamente que comienza con el valor 1 en el conjunto de resultados. Al proporcionar este argumento, se generará una alerta PHP si el conjunto de resultados utiliza un cursor de avance solo.

### Valores devueltos

Devuelve un array asociativo con los valores de las columnas indexados por el nombre de las columnas y el número de las columnas comenzando por 0. El array representa la siguiente fila o la fila solicitada del conjunto de resultados. Devuelve `false` si no hay una fila disponible en el conjunto de resultados o si la fila solicitada por `row_number` no existe en el conjunto de resultados.

### Ejemplos

Ejemplo #1 Iteración con un cursor de avance solo

Si se llama a db2_fetch_both() sin el número de una fila específica, se recuperará automáticamente la siguiente fila del conjunto de resultados. El siguiente ejemplo accede a las columnas devueltas en el array mediante el método de nombres de columna y por índice numérico.

    <?php

    $sql = "SELECT id, nom, race, poids FROM animaux ORDER BY race";
    $stmt = db2_prepare($conn, $sql);
    $result = db2_execute($stmt);

    while ($row = db2_fetch_both($stmt)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row['ID'], $row[0], $row['RACE'], $row[3]);
    }
    ?>

El ejemplo anterior mostrará:

    0     Pook             chat                                   3.20
    5     Rickety Ride     chèvre                                 9.70
    2     Smarty           cheval                               350.00

Ejemplo #2 Recuperación de filas específicas con db2_fetch_both() a partir de un cursor flotante

Si su conjunto de resultados utiliza un cursor flotante, puede llamar a la función db2_fetch_assoc() con un número de fila específico. El siguiente ejemplo recupera cada fila par en el conjunto de resultados, comenzando con la segunda fila.

    <?php

    $sql = "SELECT id, nom, race, poids FROM animaux ORDER BY race";
    $result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));

    $i=2;
    while ($row = db2_fetch_both($result, $i)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row[0], $row['NOM'], $row[2], $row['POIDS']);
        $i = $i + 2;
    }
    ?>

El ejemplo anterior mostrará:

    0     Pook             chat                                   3.20
    5     Rickety Ride     chèvre                                 9.70
    2     Smarty           cheval                               350.00

### Ver también

- db2_fetch_array() - Devuelve un array, indexado por la posición de las columnas, que representa una línea del conjunto de resultados
- db2_fetch_assoc() - Devuelve un array, indexado por nombre de columna, que representa una fila del conjunto de resultados
- db2_fetch_object() - Devuelve un objeto con las propiedades que representan columnas en la fila extraída
- db2_fetch_row() - Modifica el puntero del conjunto de resultados a la siguiente línea o a la línea solicitada
- db2_result() - Devuelve un valor de una columna de una fila de un conjunto de resultados

# db2_fetch_object

(PECL ibm_db2 >= 1.0.0)

db2_fetch_object — Devuelve un objeto con las propiedades que representan columnas en la fila extraída

### Descripción

function db2_fetch_object(resource `$stmt`, int `$row_number` = -1): stdClass|false

Devuelve un objeto en el que cada propiedad representa una columna devuelta en la fila extraída del conjunto de resultados.

### Parámetros

`stmt`
  Un recurso `stmt` válido que contiene el conjunto de resultados.
`row_number`
  Solicita una fila específica comenzando en el índice 1 del conjunto de resultados. Si se pasa este argumento, se generará una advertencia de PHP si el resultado utiliza un cursor de desplazamiento solo.

### Valores devueltos

Devuelve un objeto que representa una sola fila en el conjunto de resultados. Las propiedades del objeto corresponden al nombre de las columnas en el conjunto de resultados.

Los servidores IBM DB2, Cloudscape y Apache Derby normalmente rellenan los nombres de las columnas con mayúsculas, por lo tanto, las propiedades del objeto reflejarán este caso.

Si su consulta SELECT llama a una función escalar para modificar el valor de una columna, los servidores de base de datos devuelven el número de columna como nombre de columna en el conjunto de resultados. Si se prefiere una descripción más detallada del nombre de las columnas y las propiedades del objeto, se puede utilizar la cláusula AS para asignar un nombre a la columna en el conjunto de resultados.

Devuelve `false` si no se ha recuperado ninguna fila.

### Ejemplos

Ejemplo #1 Ejemplo con db2_fetch_object()

El ejemplo siguiente envía una consulta SELECT con una función escalar, RTRIM, que elimina los espacios al final de la columna. En lugar de crear un objeto con las propiedades "RACE" y "2", se utiliza la cláusula AS en la consulta SELECT para asignar el nombre "nom" a la columna modificada. El servidor de base de datos rellena el nombre de las columnas con mayúsculas, por lo que el objeto tendrá las propiedades "RACE" y "NOM".

    <?php
    $conn = db2_connect($database, $user, $password);

    $sql = "SELECT race, RTRIM(nom) AS nom
        FROM animaux
        WHERE id = ?";

    if ($conn) {
        $stmt = db2_prepare($conn, $sql);
        db2_execute($stmt, array(0));

        while ($pet = db2_fetch_object($stmt)) {
            echo "Viens ici, {$pet->NOM}, mon petit {$pet->RACE} !";
        }
        db2_close($conn);
    }
    ?>

El ejemplo anterior mostrará:

    Viens ici, Pook, mon petit chat !

### Ver también

- db2_fetch_array() - Devuelve un array, indexado por la posición de las columnas, que representa una línea del conjunto de resultados
- db2_fetch_assoc() - Devuelve un array, indexado por nombre de columna, que representa una fila del conjunto de resultados
- db2_fetch_both() - Devuelve un array, indexado por nombre de columna y posición, que representa una fila del conjunto de resultados
- db2_fetch_row() - Modifica el puntero del conjunto de resultados a la siguiente línea o a la línea solicitada
- db2_result() - Devuelve un valor de una columna de una fila de un conjunto de resultados

# db2_fetch_row

(PECL ibm_db2 >= 1.0.0)

db2_fetch_row — Modifica el puntero del conjunto de resultados a la siguiente línea o a la línea solicitada

### Descripción

function db2_fetch_row(resource `$stmt`, int `$row_number` = -1): bool

Utilice db2_fetch_row() para iterar a través de un conjunto de resultados o para apuntar a una línea específica de un conjunto de resultados si se ha solicitado un cursor flotante.

Para obtener campos individuales del conjunto de resultados, llame a la función db2_result().

En lugar de llamar a las funciones db2_fetch_row() y db2_result(), la mayoría de las aplicaciones van a llamar a la función db2_fetch_assoc(), db2_fetch_both() o db2_fetch_array() para avanzar el puntero en el conjunto de resultados y devolver una línea completa como array.

### Parámetros

`stmt`
  Un recurso `stmt` válido que contiene el conjunto de resultados.
`row_number`
  Con cursores flotantes, puede solicitar un número de línea específico del conjunto de resultados. Los números de líneas comienzan con el índice 1

### Valores devueltos

Devuelve `true` si la línea solicitada existe en el conjunto de resultados. Devuelve `false` si la línea solicitada no existe en el conjunto de resultados.

### Ejemplos

Ejemplo #1 Iterar a través de un conjunto de resultados

El siguiente ejemplo demuestra cómo iterar a través de un conjunto de resultados con la función db2_fetch_row() y recuperar las columnas del conjunto de resultados con db2_result().

    <?php
    $sql = 'SELECT nom, race FROM animales WHERE peso < ?';
    $stmt = db2_prepare($conn, $sql);
    db2_execute($stmt, array(10));
    while (db2_fetch_row($stmt)) {
        $nom = db2_result($stmt, 0);
        $race = db2_result($stmt, 1);
        print "$nom $race";
    }
    ?>

El ejemplo anterior mostrará:

    gato Pook
    carpa dorada Bubbles
    periquito Gizmo
    cabra Rickety Ride

Ejemplo #2 Alternativas recomendadas i5/OS para db2_fetch_row/db2_result

En i5/OS, se recomienda que utilice db2_fetch_both(), db2_fetch_array() o db2_fetch_object() en lugar de db2_fetch_row()/db2_result(). En general db2_fetch_row()/db2_result() tiene más problemas con tipos de columna variados en la traducción de `EBCDIC` a `ASCII`, incluyendo posible truncamiento en aplicaciones `DBCS`. También podría encontrar una mejor performance utilizando db2_fetch_both(), db2_fetch_array() y db2_fetch_object() en lugar de db2_fetch_row()/db2_result().

    <?php
      $conn = db2_connect("","","");
      $sql = 'SELECT SPECIFIC_SCHEMA, SPECIFIC_NAME, ROUTINE_SCHEMA, ROUTINE_NAME, ROUTINE_TYPE, ROUTINE_CREATED, ROUTINE_BODY, IN_PARMS, OUT_PARMS, INOUT_PARMS, PARAMETER_STYLE, EXTERNAL_NAME, EXTERNAL_LANGUAGE FROM QSYS2.SYSROUTINES FETCH FIRST 2 ROWS ONLY';
      $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
      while ($row = db2_fetch_both($stmt)){
        echo "<br>db2_fetch_both {$row['SPECIFIC_NAME']} {$row['ROUTINE_CREATED']} {$row[5]}";
      }
      $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
      while ($row = db2_fetch_array($stmt)){
        echo "<br>db2_fetch_array {$row[1]}  {$row[5]}";
      }
      $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
      while ($row = db2_fetch_object($stmt)){
        echo "<br>db2_fetch_object {$row->SPECIFIC_NAME} {$row->ROUTINE_CREATED}";
      }
      db2_close($conn);
    ?>

El ejemplo anterior mostrará:

    db2_fetch_both MATCH_ANIMAL 2006-08-25-17.10.23.775000 2006-08-25-17.10.23.775000
    db2_fetch_both MULTIRESULTS 2006-10-17-10.11.05.308000 2006-10-17-10.11.05.308000
    db2_fetch_array MATCH_ANIMAL 2006-08-25-17.10.23.775000
    db2_fetch_array MULTIRESULTS 2006-10-17-10.11.05.308000
    db2_fetch_object MATCH_ANIMAL 2006-08-25-17.10.23.775000
    db2_fetch_object MULTIRESULTS 2006-10-17-10.11.05.308000

### Ver también

- db2_fetch_array() - Devuelve un array, indexado por la posición de las columnas, que representa una línea del conjunto de resultados
- db2_fetch_assoc() - Devuelve un array, indexado por nombre de columna, que representa una fila del conjunto de resultados
- db2_fetch_both() - Devuelve un array, indexado por nombre de columna y posición, que representa una fila del conjunto de resultados
- db2_fetch_object() - Devuelve un objeto con las propiedades que representan columnas en la fila extraída
- db2_result() - Devuelve un valor de una columna de una fila de un conjunto de resultados

# db2_field_display_size

(PECL ibm_db2 >= 1.0.0)

db2_field_display_size — Devuelve el máximo de octetos requeridos para mostrar una columna

### Descripción

function db2_field_display_size(resource `$stmt`, int|string `$column`): int|false

Devuelve el máximo de octetos requeridos para mostrar una columna en un conjunto de resultados.

### Parámetros

`stmt`
  Especifica el recurso que contiene el conjunto de resultados.
`column`
  Especifica la columna en el conjunto de resultados. Puede ser un entero comenzando en la posición 0 que representa el número de la columna o un string que contiene el nombre de la columna.

### Valores devueltos

Devuelve un valor entero con el máximo de octetos requeridos para mostrar la columna especificada. Si la columna no existe en el conjunto de resultados, db2_field_display_size() devuelve `false`.

### Ver también

- db2_field_name() - Devuelve el nombre de la columna del conjunto de resultados
- db2_field_num() - Devuelve la posición del nombre de la columna del conjunto de resultados
- db2_field_precision() - Devuelve la precisión de la columna indicada del conjunto de resultados
- db2_field_scale() - Devuelve la escala de la columna indicada del conjunto de resultados
- db2_field_type() - Devuelve el tipo de dato de la columna indicada del conjunto de resultados
- db2_field_width() - Devuelve el ancho de la columna indicada en el conjunto de resultados

# db2_field_name

(PECL ibm_db2 >= 1.0.0)

db2_field_name — Devuelve el nombre de la columna del conjunto de resultados

### Descripción

function db2_field_name(resource `$stmt`, int|string `$column`): string|false

Devuelve el nombre de la columna del conjunto de resultados

### Parámetros

`stmt`
  Especifica el recurso que contiene el conjunto de resultados.
`column`
  Especifica la columna en el conjunto de resultados. Puede ser un entero comenzando en la posición 0 que representa el número de la columna o un string que contiene el nombre de la columna.

### Valores devueltos

Devuelve un string que contiene el nombre de la columna especificada. Si la columna especificada no existe en el conjunto de resultados, db2_field_name() devuelve `false`.

### Ver también

- db2_field_display_size() - Devuelve el máximo de octetos requeridos para mostrar una columna
- db2_field_num() - Devuelve la posición del nombre de la columna del conjunto de resultados
- db2_field_precision() - Devuelve la precisión de la columna indicada del conjunto de resultados
- db2_field_scale() - Devuelve la escala de la columna indicada del conjunto de resultados
- db2_field_type() - Devuelve el tipo de dato de la columna indicada del conjunto de resultados
- db2_field_width() - Devuelve el ancho de la columna indicada en el conjunto de resultados

# db2_field_num

(PECL ibm_db2 >= 1.0.0)

db2_field_num — Devuelve la posición del nombre de la columna del conjunto de resultados

### Descripción

function db2_field_num(resource `$stmt`, int|string `$column`): int|false

Devuelve la posición del nombre de la columna del conjunto de resultados

### Parámetros

`stmt`
  Especifica un recurso que contiene un conjunto de resultados.
`column`
  Especifica la columna en el conjunto de resultados. Esto puede ser un entero comenzando en la posición 0 que representa el número de la columna o un string que contiene el nombre de la columna.

### Valores devueltos

Devuelve un entero que contiene la posición comenzando en 0 del nombre de la columna en el conjunto de resultados. Si la columna especificada no existe en el conjunto de resultados, db2_field_num() devuelve `false`.

### Ver también

- db2_field_display_size() - Devuelve el máximo de octetos requeridos para mostrar una columna
- db2_field_name() - Devuelve el nombre de la columna del conjunto de resultados
- db2_field_precision() - Devuelve la precisión de la columna indicada del conjunto de resultados
- db2_field_scale() - Devuelve la escala de la columna indicada del conjunto de resultados
- db2_field_type() - Devuelve el tipo de dato de la columna indicada del conjunto de resultados
- db2_field_width() - Devuelve el ancho de la columna indicada en el conjunto de resultados

# db2_field_precision

(PECL ibm_db2 >= 1.0.0)

db2_field_precision — Devuelve la precisión de la columna indicada del conjunto de resultados

### Descripción

function db2_field_precision(resource `$stmt`, int|string `$column`): int|false

Devuelve la precisión de la columna indicada del conjunto de resultados.

### Parámetros

`stmt`
  Especifica el recurso que contiene el conjunto de resultados.
`column`
  Especifica la columna en el conjunto de resultados. Esto puede ser un entero que comienza en la posición 0 representando el número de la columna o un string que contiene el nombre de la columna.

### Valores devueltos

Devuelve un integer que contiene la precisión de la columna especificada. Si la columna especificada no existe en el conjunto de resultados, db2_field_precision() devuelve `false`.

### Ver también

- db2_field_display_size() - Devuelve el máximo de octetos requeridos para mostrar una columna
- db2_field_name() - Devuelve el nombre de la columna del conjunto de resultados
- db2_field_num() - Devuelve la posición del nombre de la columna del conjunto de resultados
- db2_field_scale() - Devuelve la escala de la columna indicada del conjunto de resultados
- db2_field_type() - Devuelve el tipo de dato de la columna indicada del conjunto de resultados
- db2_field_width() - Devuelve el ancho de la columna indicada en el conjunto de resultados

# db2_field_scale

(PECL ibm_db2 >= 1.0.0)

db2_field_scale — Devuelve la escala de la columna indicada del conjunto de resultados

### Descripción

function db2_field_scale(resource `$stmt`, int|string `$column`): int|false

Devuelve la escala de la columna indicada del conjunto de resultados.

### Parámetros

`stmt`
  Especifica el recurso que contiene el conjunto de resultados.
`column`
  Especifica la columna en el conjunto de resultados. Esto puede ser un entero comenzando en la posición 0 que representa el número de la columna o una cadena que contiene el nombre de la columna.

### Valores devueltos

Devuelve un entero que contiene la escala de la columna especificada. Si la columna especificada no existe en el conjunto de resultados, db2_field_scale() devuelve `false`.

### Ver también

- db2_field_display_size() - Devuelve el máximo de octetos requeridos para mostrar una columna
- db2_field_name() - Devuelve el nombre de la columna del conjunto de resultados
- db2_field_num() - Devuelve la posición del nombre de la columna del conjunto de resultados
- db2_field_precision() - Devuelve la precisión de la columna indicada del conjunto de resultados
- db2_field_type() - Devuelve el tipo de dato de la columna indicada del conjunto de resultados
- db2_field_width() - Devuelve el ancho de la columna indicada en el conjunto de resultados

# db2_field_type

(PECL ibm_db2 >= 1.0.0)

db2_field_type — Devuelve el tipo de dato de la columna indicada del conjunto de resultados

### Descripción

function db2_field_type(resource `$stmt`, int|string `$column`): string|false

Devuelve el tipo de dato de la columna indicada del conjunto de resultados.

### Parámetros

`stmt`
  Especifica el recurso que contiene el conjunto de resultados.
`column`
  Especifica la columna en el conjunto de resultados. Esto puede ser un entero comenzando en la posición 0 que representa el número de la columna o una cadena que contiene el nombre de la columna.

### Valores devueltos

Devuelve una cadena que contiene el tipo de dato definido de la columna especificada. Si la columna especificada no existe en el conjunto de resultados, db2_field_type() devuelve `false`.

### Ver también

- db2_field_display_size() - Devuelve el máximo de octetos requeridos para mostrar una columna
- db2_field_name() - Devuelve el nombre de la columna del conjunto de resultados
- db2_field_num() - Devuelve la posición del nombre de la columna del conjunto de resultados
- db2_field_precision() - Devuelve la precisión de la columna indicada del conjunto de resultados
- db2_field_scale() - Devuelve la escala de la columna indicada del conjunto de resultados
- db2_field_width() - Devuelve el ancho de la columna indicada en el conjunto de resultados

# db2_field_width

(PECL ibm_db2 >= 1.0.0)

db2_field_width — Devuelve el ancho de la columna indicada en el conjunto de resultados

### Descripción

function db2_field_width(resource `$stmt`, int|string `$column`): int|false

Devuelve el ancho de la columna indicada en el conjunto de resultados. Esto es el ancho máximo de la columna para un tipo de datos de longitud fija o el ancho actual de la columna para un tipo de datos de longitud variable.

### Parámetros

`stmt`
  Especifica el recurso que contiene el conjunto de resultados.
`column`
  Especifica la columna en el conjunto de resultados. Esto puede ser un entero comenzando en la posición 0 que representa el número de la columna o un string que contiene el nombre de la columna.

### Valores devueltos

Devuelve un integer que contiene el ancho del carácter especificado o de la columna de tipo binario en el conjunto de resultados. Si la columna especificada no existe en el conjunto de resultados, db2_field_width() devuelve `false`.

### Ver también

- db2_field_display_size() - Devuelve el máximo de octetos requeridos para mostrar una columna
- db2_field_name() - Devuelve el nombre de la columna del conjunto de resultados
- db2_field_num() - Devuelve la posición del nombre de la columna del conjunto de resultados
- db2_field_precision() - Devuelve la precisión de la columna indicada del conjunto de resultados
- db2_field_scale() - Devuelve la escala de la columna indicada del conjunto de resultados
- db2_field_type() - Devuelve el tipo de dato de la columna indicada del conjunto de resultados

# db2_foreign_keys

(PECL ibm_db2 >= 1.0.0)

db2_foreign_keys — Devuelve un conjunto de resultados que lista las claves externas de una tabla

### Descripción

function db2_foreign_keys(
resource `$connection`,
?string `$qualifier`,
?string `$schema`,
string `$table_name`
): resource

Devuelve un conjunto de resultados que lista las claves externas de una tabla.

### Parámetros

`connection`
  Una conexión válida a una base de datos IBM DB2, Cloudscape o Apache Derby.
`qualifier`
  Un calificador para las bases de datos DB2 que funcionan en los servidores OS/390 o z/OS. Para otras bases de datos, pase `null` o una cadena vacía.
`schema`
  El esquema que contiene las tablas. Si `schema` es `null`, db2_foreign_keys() hace coincidir el esquema para la conexión actual.
`table_name`
  El nombre de la tabla.

### Valores devueltos

Devuelve un recurso con el conjunto de resultados que contiene filas que describen las claves externas de la tabla especificada. El conjunto de resultados está compuesto por las siguientes columnas:

Nombre de la columna | Descripción
--- | ---
PKTABLE_CAT | Nombre del catálogo de la tabla que contiene la clave primaria. El valor es `null` si la tabla no tiene catálogo.
PKTABLE_SCHEM | Nombre del esquema de la tabla que contiene la clave primaria.
PKTABLE_NAME | Nombre de la tabla que contiene la clave primaria.
PKCOLUMN_NAME | Nombre de la columna que contiene la clave primaria.
FKTABLE_CAT | Nombre del catálogo de la tabla que contiene la clave externa. El valor es `null` si la tabla no tiene catálogo.
FKTABLE_SCHEM | Nombre del esquema de la tabla que contiene la clave externa.
FKTABLE_NAME | Nombre de la tabla que contiene la clave externa.
FKCOLUMN_NAME | Nombre de la columna que contiene la clave externa.
KEY_SEQ | Posición, comenzando en 1, de la columna en la clave.
UPDATE_RULE | Entero que representa la acción aplicada a la clave externa cuando una operación es de tipo UPDATE.
DELETE_RULE | Entero que representa la acción aplicada a la clave externa cuando una operación es de tipo DELETE.
FK_NAME | Nombre de la clave externa.
PK_NAME | Nombre de la clave primaria.
DEFERRABILITY | Un entero que representa si el modo diferido de la clave externa es SQL_INITIALLY_DEFERRED, SQL_INITIALLY_IMMEDIATE o SQL_NOT_DEFERRABLE.

### Ver también

- db2_column_privileges() - Devuelve un conjunto de resultados que lista las columnas y sus privilegios de una tabla
- db2_columns() - Devuelve un conjunto de resultados que lista las columnas y sus metadatos de una tabla
- db2_primary_keys() - Devuelve un conjunto de resultados que lista las claves de una tabla
- db2_procedure_columns() - Devuelve un conjunto de resultados que lista los argumentos de procedimiento de registro
- db2_procedures() - Devuelve un conjunto de resultados que lista las proceduras de registro almacenadas en la base de datos
- db2_special_columns() - Devuelve un conjunto de resultados que lista los identificadores únicos de las filas de una tabla
- db2_statistics() - Devuelve un conjunto de resultados que enumera los índices y estadísticas de una tabla
- db2_table_privileges() - Devuelve un conjunto de resultados que lista las tablas y sus privilegios asociados en una base de datos
- db2_tables() - Devuelve la lista de tablas y sus metadatos

# db2_free_result

(PECL ibm_db2 >= 1.0.0)

db2_free_result — Liberar los recursos asociados con un resultado

### Descripción

function db2_free_result(resource `$stmt`): bool

Libera los recursos del Sistema y de la Base de Datos que están asociados con un resultado. Los recursos se liberan automáticamente cuando un script finaliza, pero se puede llamar a db2_free_result() para liberarlos en ese momento y no hasta que el script finalice.

### Parámetros

`stmt`
  Un recurso válido.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- db2_free_stmt() - Liberar un recurso indicado

# db2_free_stmt

(PECL ibm_db2 >= 1.0.0)

db2_free_stmt — Liberar un recurso indicado

### Descripción

function db2_free_stmt(resource `$stmt`): bool

Libera los recursos del Sistema y de la Base de Datos que están asociados con un determinado recurso (de sentencias). Los recursos son liberados automáticamente cuando un script finaliza, pero se puede llamar a db2_free_stmt() para liberarlos en ese momento y no hasta que el script finalice.

### Parámetros

`stmt`
  Un recurso (de sentencias) válido.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- db2_free_result() - Liberar los recursos asociados con un resultado

# db2_get_option

(PECL ibm_db2 >= 1.6.0)

db2_get_option — Recupera el valor de una opción para una consulta o conexión

### Descripción

function db2_get_option(resource `$resource`, string `$option`): string|false

Recupera el valor de una opción especificada para un recurso de consulta o un recurso de conexión.

### Parámetros

`resource`
  Un recurso de consulta válido devuelto por db2_prepare() o un recurso de conexión válido devuelto por db2_connect() o db2_pconnect().
`option`

  Opciones de consulta o conexión válidas. Las siguientes opciones nuevas están disponibles desde la versión 1.6.0 de ibm_db2. Proporcionan información de seguimiento útil que puede ser establecida durante la ejecución con db2_get_option().

  > Nota: Las versiones anteriores de ibm_db no soportan estas nuevas opciones. Cuando un valor en cada opción es establecido, algunos servidores pueden no soportar el valor total proporcionado y pueden truncar este valor. Para asegurar que los datos especificados en cada opción sean convertidos correctamente durante la transmisión hacia una base de datos, utilice solo los caracteres de A a Z, 0 a 9 y los caracteres de subrayado (_) o punto (.).

  `userid`

    `SQL_ATTR_INFO_USERID` : un puntero hacia un string utilizado para identificar el identificador de usuario (ID) enviado hacia el servidor de base de datos durante la conexión a DB2.

    > Nota: DB2 para servidores z/OS y OS/390 soportan hasta 16 caracteres. El user-id no debe ser confundido con la identificación user-id; se trata solamente de un propósito de identificación y no debe ser autorizado para permisos.

  `acctstr`

    `SQL_ATTR_INFO_ACCTSTR` : un puntero hacia un string utilizado para identificar la cuenta del cliente enviada hacia el servidor de base de datos durante la conexión a DB2.

    > Nota: DB2 para servidores z/OS y OS/390 soportan hasta 200 caracteres.

  `applname`

    `SQL_ATTR_INFO_APPLNAME` : un puntero hacia un string utilizado para identificar el nombre de la aplicación del cliente enviada hacia el servidor de base de datos durante la conexión a DB2.

    > Nota: DB2 para servidores z/OS y OS/390 soportan hasta 32 caracteres.

  `wrkstnname`

    `SQL_ATTR_INFO_WRKSTNNAME` : un puntero hacia un string utilizado para identificar el nombre de la máquina del cliente enviada hacia el servidor de base de datos durante la conexión a DB2.

    > Nota: DB2 para servidores z/OS y OS/390 soportan hasta 18 caracteres.

La siguiente tabla especifica qué opciones son compatibles con el tipo de recurso disponible:

Matriz recurso parámetro
Clave | Valor | Tipo de recurso
--- | --- | ---
|  | Conexión | Consulta | Conjunto de resultados
userid | `SQL_ATTR_INFO_USERID` | X | X | -
acctstr | `SQL_ATTR_INFO_ACCTSTR` | X | X | -
applname | `SQL_ATTR_INFO_APPLNAME` | X | X | -
wrkstnname | `SQL_ATTR_INFO_WRKSTNNAME` | X | X | -

### Valores devueltos

Devuelve la configuración actual de la conexión proporcionada en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Establece y recupera los parámetros de un recurso de conexión

    <?php
    /* Parámetros de Conexión */
    $database = 'SAMPLE';
    $user     = 'db2inst1';
    $password = 'ibmdb2';

    /* Recuperación del Recurso de Conexión */
    $conn = db2_connect($database, $user, $password);

    echo "Atributos de conexión pasados con la cadena de caracteres de conexión :\n";

    /* Crea un array asociativo de opciones con los pares clave/valor válidos */
    /* Asigna los atributos a partir de la cadena de caracteres de conexión */
    /* Accede a las opciones especificadas */
    $options1 = array('userid' => 'db2inst1');
    $conn1 = db2_connect($database, $user, $password, $options1);
    $val = db2_get_option($conn1, 'userid');
    echo $val . "\n";

    $options2 = array('acctstr' => 'account');
    $conn2 = db2_connect($database, $user, $password, $options2);
    $val = db2_get_option($conn2, 'acctstr');
    echo $val . "\n";

    $options3 = array('applname' => 'myapp');
    $conn3 = db2_connect($database, $user, $password, $options3);
    $val = db2_get_option($conn3, 'applname');
    echo $val . "\n";

    $options4 = array('wrkstnname' => 'workstation');
    $conn4 = db2_connect($database, $user, $password, $options4);
    $val = db2_get_option($conn4, 'wrkstnname');
    echo $val . "\n";

    echo "Atributos después de la conexión :\n";

    /* Crea un array asociativo de opciones con los pares clave/valor válidos */
    /* Asigna los atributos después de que la conexión sea realizada */
    /* Accede a las opciones especificadas */
    $options5 = array('userid' => 'db2inst1');
    $conn5 = db2_connect($database, $user, $password);
    $rc = db2_set_option($conn5, $options5, 1);
    $val = db2_get_option($conn5, 'userid');
    echo $val . "\n";

    $options6 = array('acctstr' => 'account');
    $conn6 = db2_connect($database, $user, $password);
    $rc = db2_set_option($conn6, $options6, 1);
    $val = db2_get_option($conn6, 'acctstr');
    echo $val . "\n";

    $options7 = array('applname' => 'myapp');
    $conn7 = db2_connect($database, $user, $password);
    $rc = db2_set_option($conn7, $options7, 1);
    $val = db2_get_option($conn7, 'applname');
    echo $val . "\n";

    $options8 = array('wrkstnname' => 'workstation');
    $conn8 = db2_connect($database, $user, $password);
    $rc = db2_set_option($conn8, $options8, 1);
    $val = db2_get_option($conn8, 'wrkstnname');
    echo $val . "\n";
    ?>

El ejemplo anterior mostrará:

    Atributos de conexión pasados con la cadena de caracteres de conexión :
    db2inst1
    account
    myapp
    workstation
    Atributos después de la conexión :
    db2inst1
    account
    myapp
    workstation

### Ver también

- db2_connect() - Devuelve una conexión a una base de datos
- db2_cursor_type() - Devuelve el tipo de cursor utilizado por un recurso
- db2_exec() - Ejecuta una consulta SQL directamente
- db2_set_option() - Establece opciones para una conexión o recursos
- db2_pconnect() - Devuelve una conexión persistente a una base de datos
- db2_prepare() - Prepara una consulta SQL para ser ejecutada

# db2_last_insert_id

(PECL ibm_db2 >= 1.7.1)

db2_last_insert_id — Retorna el último ID generado por la última consulta de inserción

### Descripción

function db2_last_insert_id(resource `$resource`): ?string

Retorna el último identificador autogenerado por la última consulta de inserción para la conexión actual.

El resultado de esta función no se ve afectado por los siguientes eventos:

- Un comando INSERT único con una cláusula VALUES para una tabla que no dispone de columna de identidad.
- Un comando INSERT múltiple con cláusula VALUES.
- Un comando INSERT con un SELECT.
- Un comando ROLLBACK TO SAVEPOINT.

### Parámetros

`resource`
  Un recurso de conexión válido, creado por db2_connect() o db2_pconnect(). El valor de este argumento no puede ser un recurso de comando o de resultado.

### Valores devueltos

Retorna el identificador autogenerado que pudo ser ejecutado correctamente en esta conexión.

### Ejemplos

Ejemplo #1 Ejemplo con db2_last_insert_id()

El siguiente ejemplo muestra cómo retornar un identificador automático

    <?php

    $database = "SAMPLE";
    $user = "db2inst1";
    $password = "ibmdb2";

    $conn = db2_connect($database, $user, $password);
    if($conn) {
        $createTable = "CREATE TABLE lastInsertID
          (id integer GENERATED BY DEFAULT AS IDENTITY, name varchar(20))";
        $insertTable = "INSERT INTO lastInsertID (name) VALUES ('Temp Name')";

        $stmt = @db2_exec($conn, $createTable);

        /* Verificación de la inserción de una fila única */
        $stmt = db2_exec($conn, $insertTable);
        $ret =  db2_last_insert_id($conn);
        if($ret) {
            echo "Último ID insertado: " . $ret . "\n";
        } else {
            echo "No se ha insertado ningún ID recientemente.\n";
        }

        db2_close($conn);
    }
    else {
        echo "La conexión ha fallado.";
    }
    ?>

El ejemplo anterior mostrará:

    Último ID generado: 1

# db2_lob_read

(PECL ibm_db2 >= 1.6.0)

db2_lob_read — Recupera grandes objetos binarios de tamaños predefinidos en cada invocación

### Descripción

function db2_lob_read(resource `$stmt`, int `$colnum`, int `$length`): string|false

Utilice db2_lob_read() para recorrer una columna específica de un conjunto de resultados y recuperar los grandes objetos binarios de tamaño predefinido.

### Parámetros

`stmt`
  Un recurso `stmt` válido que contiene grandes objetos binarios.
`colnum`
  Un número de columna válido en el conjunto de resultados del recurso `stmt`.
`length`
  El tamaño de los grandes objetos binarios a recuperar del recurso `stmt`.

### Valores devueltos

Devuelve el número de datos especificados. Devuelve `false` si los datos no pueden ser recuperados.

### Ejemplos

Ejemplo #1 Iterar a través de diferentes tipos de datos

    <?php

    /* Parámetros de Conexión */
    $db = 'SAMPLE';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Recuperación del Recurso de Conexión */
    $conn = db2_connect($db,$username,$password);

    if ($conn) {
        $drop = 'DROP TABLE clob_stream';
        $result = @db2_exec( $conn, $drop );

        $create = 'CREATE TABLE clob_stream (id INTEGER, my_clob CLOB)';
        $result = db2_exec( $conn, $create );

        $variable = "";
        $stmt = db2_prepare($conn, "INSERT INTO clob_stream (id,my_clob) VALUES (1, ?)");
        $variable = "THIS IS A CLOB TEST. THIS IS A CLOB TEST.";
        db2_bind_param($stmt, 1, "variable", DB2_PARAM_IN);
        db2_execute($stmt);

        $sql = "SELECT id,my_clob FROM clob_stream";
        $result = db2_prepare($conn, $sql);
        db2_execute($result);
        db2_fetch_row($result);
        $i = 0;
        /* Lectura de grandes objetos */
        while ($data = db2_lob_read($result, 2, 6)) {
            echo "Bucle $i : $data\n";
            $i = $i + 1;
        }

        $drop = 'DROP TABLE blob_stream';
        $result = @db2_exec( $conn, $drop );

        $create = 'CREATE TABLE blob_stream (id INTEGER, my_blob CLOB)';
        $result = db2_exec( $conn, $create );

        $variable = "";
        $stmt = db2_prepare($conn, "INSERT INTO blob_stream (id,my_blob) VALUES (1, ?)");
        $variable = "THIS IS A BLOB TEST. THIS IS A BLOB TEST.";
        db2_bind_param($stmt, 1, "variable", DB2_PARAM_IN);
        db2_execute($stmt);

        $sql = "SELECT id,my_blob FROM blob_stream";
        $result = db2_prepare($conn, $sql);
        db2_execute($result);
        db2_fetch_row($result);
        $i = 0;
        /* Lectura de grandes objetos */
        while ($data = db2_lob_read($result, 2, 6)) {
            echo "Bucle $i : $data\n";
            $i = $i + 1;
        }
    } else {
        echo 'ninguna conexión : ' . db2_conn_errormsg();
    }

    ?>

El ejemplo anterior mostrará:

    Bucle 0 : THIS I
    Bucle 1 : S A CL
    Bucle 2 : OB TES
    Bucle 3 : T. THI
    Bucle 4 : S IS A
    Bucle 5 :  CLOB
    Bucle 6 : TEST.
    Bucle 0 : THIS I
    Bucle 1 : S A BL
    Bucle 2 : OB TES
    Bucle 3 : T. THI
    Bucle 4 : S IS A
    Bucle 5 :  BLOB
    Bucle 6 : TEST.

### Ver también

- db2_bind_param() - Asocia una variable PHP a un parámetro de una consulta SQL
- db2_exec() - Ejecuta una consulta SQL directamente
- db2_execute() - Ejecuta una consulta SQL preparada
- db2_fetch_row() - Modifica el puntero del conjunto de resultados a la siguiente línea o a la línea solicitada
- db2_prepare() - Prepara una consulta SQL para ser ejecutada
- db2_result() - Devuelve un valor de una columna de una fila de un conjunto de resultados

# db2_next_result

(PECL ibm_db2 >= 1.0.0)

db2_next_result — Solicita el siguiente conjunto de resultados de la recurso indicado

### Descripción

function db2_next_result(resource `$stmt`): resource|false

Un procedimiento de registro puede devolver ningún o múltiples conjuntos de resultados. El primer conjunto de resultados debe manejarse de la misma manera que los resultados devueltos por una simple consulta SELECT. Para obtener el segundo o los siguientes resultados, debe llamarse a la función db2_next_result() y almacenar el resultado en una variable PHP.

### Parámetros

`stmt`
  Una consulta preparada devuelta por db2_exec() o db2_execute().

### Valores devueltos

Devuelve un nuevo recurso que contiene el siguiente conjunto de resultados si el procedimiento contenía otro conjunto de resultados. Devuelve `false` si el procedimiento no tenía más conjuntos de resultados para devolver.

### Ejemplos

Ejemplo #1 Ejemplo con db2_next_result()

En el siguiente ejemplo, se llama a un procedimiento que devuelve tres conjuntos de resultados. El primer conjunto de resultados se recupera directamente de la misma recurso sobre la cual se invocó una consulta CALL, mientras que el segundo y tercer conjuntos de resultados se recuperan de las recursos devueltas por la llamada a la función db2_next_result().

    <?php
    $conn = db2_connect($database, $user, $password);

    if ($conn) {
      $stmt = db2_exec($conn, 'CALL multiResults()');

      print "Recuperación del primer conjunto de resultados\n";
      while ($row = db2_fetch_array($stmt)) {
        var_dump($row);
      }

      print "\nRecuperación del segundo conjunto de resultados\n";
      $res = db2_next_result($stmt);
      if ($res) {
        while ($row = db2_fetch_array($res)) {
          var_dump($row);
        }
      }

      print "\nRecuperación del tercer conjunto de resultados\n";
      $res2 = db2_next_result($stmt);
      if ($res2) {
        while ($row = db2_fetch_array($res2)) {
          var_dump($row);
        }
      }

      db2_close($conn);
    }
    ?>

El ejemplo anterior mostrará:

    Recuperación del primer conjunto de resultados
    array(2) {
      [0]=>
      string(16) "Bubbles         "
      [1]=>
      int(3)
    }
    array(2) {
      [0]=>
      string(16) "Gizmo           "
      [1]=>
      int(4)
    }

    Recuperación del segundo conjunto de resultados
    array(4) {
      [0]=>
      string(16) "Sweater         "
      [1]=>
      int(6)
      [2]=>
      string(5) "lama"
      [3]=>
      string(6) "150.00"
    }
    array(4) {
      [0]=>
      string(16) "Smarty          "
      [1]=>
      int(2)
      [2]=>
      string(5) "cheval"
      [3]=>
      string(6) "350.00"
    }

    Recuperación del tercer conjunto de resultados
    array(1) {
      [0]=>
      string(16) "Bubbles         "
    }
    array(1) {
      [0]=>
      string(16) "Gizmo           "
    }

# db2_num_fields

(PECL ibm_db2 >= 1.0.0)

db2_num_fields — Devuelve el número de campos contenido en el conjunto de resultados

### Descripción

function db2_num_fields(resource `$stmt`): int|false

Devuelve el número de campos contenidos en el conjunto de resultados. Esta función es muy útil cuando se gestionan conjuntos de resultados devueltos por consultas generadas dinámicamente o para conjuntos de resultados devueltos por procedimientos de registro, donde la aplicación no puede hacer otra cosa para obtener y utilizar estos resultados.

### Parámetros

`stmt`
  Un recurso válido que contiene un conjunto de resultados.

### Valores devueltos

Devuelve un entero que representa el número de campos en el conjunto de resultados asociado con el recurso especificado. Devuelve `false` si el recurso no es válido.

### Ejemplos

Ejemplo #1 Ejemplo con db2_num_fields()

El siguiente ejemplo demuestra cómo obtener el número de campos devueltos en el conjunto de resultados.

    <?php

    $sql = "SELECT id, nom, race, poids FROM animales ORDER BY race";
    $stmt = db2_prepare($conn, $sql);
    db2_execute($stmt, $sql);
    $columns = db2_num_fields($stmt);

    echo "Hay {$columns} columnas en el conjunto de resultados.";
    ?>

El ejemplo anterior mostrará:

    Hay 4 columnas en el conjunto de resultados.

### Ver también

- db2_execute() - Ejecuta una consulta SQL preparada
- db2_field_display_size() - Devuelve el máximo de octetos requeridos para mostrar una columna
- db2_field_name() - Devuelve el nombre de la columna del conjunto de resultados
- db2_field_num() - Devuelve la posición del nombre de la columna del conjunto de resultados
- db2_field_precision() - Devuelve la precisión de la columna indicada del conjunto de resultados
- db2_field_scale() - Devuelve la escala de la columna indicada del conjunto de resultados
- db2_field_type() - Devuelve el tipo de dato de la columna indicada del conjunto de resultados
- db2_field_width() - Devuelve el ancho de la columna indicada en el conjunto de resultados

# db2_num_rows

(PECL ibm_db2 >= 1.0.0)

db2_num_rows — Devuelve el número de filas afectadas por una consulta SQL

### Descripción

function db2_num_rows(resource `$stmt`): int|false

Devuelve el número de filas eliminadas, añadidas o actualizadas por una consulta SQL.

Para determinar el número de filas que devolverá una consulta SELECT, utilice la consulta SELECT COUNT(*) con los mismos atributos cuando se haya ejecutado la consulta SELECT y la recuperación de los valores.

Si la lógica de la aplicación verifica el número de filas devueltas por una consulta SELECT y salta si el número de filas es 0, modifique la aplicación para intentar devolver la primera fila con db2_fetch_assoc(), db2_fetch_both(), db2_fetch_array() o db2_fetch_row(), y salte si la función devuelve `false`.

> Nota: Si se envía una consulta SELECT con un cursor flotante, db2_num_rows() devolverá el número de filas devueltas por la consulta SELECT. Sin embargo, el tiempo de sistema asociado con los cursores flotantes degrada considerablemente el rendimiento de la aplicación, por lo que si esta es la única razón para utilizar cursores flotantes, se deberían utilizar cursores de avance solo y además llamar a SELECT COUNT(*) o confiar en los valores de retorno de las funciones de tipo bool para obtener la misma funcionalidad con un rendimiento mucho mejor.

### Parámetros

`stmt`
  Un recurso `stmt` válido que contiene el conjunto de resultados.

### Valores devueltos

Devuelve el número de filas afectadas por la última consulta SQL enviada por una función que ejecuta consultas SQL, o `false` si ocurre un error

# db2_pclose

(PECL ibm_db2 >= 1.8.0)

db2_pclose — Cierra una conexión persistente a la base de datos

### Descripción

function db2_pclose(resource `$connection`): bool

Esta función cierra una conexión DB2, creada con db2_pconnect() y libera los recursos correspondientes del servidor.

> Nota: Esta función no está disponible en i5/OS en respuesta a solicitudes de administración i5/OS.

Si se tiene una conexión persistente DB2 creada con la función db2_pconnect(), puede utilizarse esta función para cerrar la conexión. Para evitar costos significativos de conexión, esta función solo debe utilizarse en casos raros, donde la conexión se haya vuelto inactiva, o cuando la conexión persistente no será utilizada por un largo tiempo.

### Parámetros

`connection`
  Un recurso de conexión DB2 activo.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Cerrar una conexión DB2 persistente

El ejemplo a continuación muestra cómo cerrar una conexión en un servidor IBM DB2 i5/OS.

    <?php
    $conn = db2_pconnect('', '', '');
    $rc = db2_pclose($conn);
    if ($rc) {
        echo "La conexión fue cerrada correctamente.";
    }
    ?>

El ejemplo anterior mostrará:

    La conexión fue cerrada correctamente.

### Ver también

- db2_close() - Cierra una conexión a base de datos
- db2_pconnect() - Devuelve una conexión persistente a una base de datos

# db2_pconnect

(PECL ibm_db2 >= 1.0.0)

db2_pconnect — Devuelve una conexión persistente a una base de datos

### Descripción

function db2_pconnect(
string `$database`,
?string `$username`,
?string `$password`,
array `$options` = []
): resource|false

Devuelve una conexión persistente a una base de datos IBM DB2 Universal Database, IBM Cloudscape o Apache Derby.

Para más información sobre las conexiones persistentes, véase Conexiones persistentes a bases de datos.

Al llamar a db2_close() sobre una conexión persistente, siempre se recibirá `true`, pero las conexiones de los clientes DB2 permanecerán abiertas y esperarán para servir la próxima petición de la función db2_pconnect().

Los usuarios de versiones 1.9.0 o superiores de ibm_db2 deben saber que la extensión ejecutará un rollback sobre una transacción en una conexión persistente al final de la consulta, terminando así la transacción. Esto evita un bloqueo transaccional hacia la consulta siguiente sobre la misma conexión si la ejecución del script termina antes de la transacción.

### Parámetros

`database`
  Para una conexión catalogada a una base de datos, `database` representa el alias de la base de datos en el catálogo del cliente DB2.

  Para una conexión no catalogada a una base de datos, `database` representa una cadena de conexión completa en el siguiente formato :

      DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=password;

  > Nota:

  > Al conectarse a Db2 sobre IBM i, las llamadas al sistema subyacentes » SQLDriverConnect, solo aceptan DSN, UID y PWD para la » cadena de conexión. Como sigue :

  >     DSN=database;UID=username;PWD=password;

  donde los parámetros representan los siguientes valores :
  `database`
    El nombre de la base de datos.
  `hostname`
    El nombre de host o la dirección IP del servidor de la base de datos.
  `port`
    El puerto TCP/IP en el que la base de datos escucha las consultas.
  `username`
    El nombre de usuario con el que se conecta a la base de datos.
  `password`
    La contraseña con la que se conecta a la base de datos.
`username`
  El nombre de usuario con el que se conecta a la base de datos.
`password`
  La contraseña con la que se conecta a la base de datos.
`options`

  Un array asociativo de opciones de conexión que afectarán el comportamiento de la conexión, donde los valores de las claves incluyen :

  `autocommit`
    El valor `DB2_AUTOCOMMIT_ON` activa el autocommit en esta conexión. El valor `DB2_AUTOCOMMIT_OFF` desactiva el autocommit para esta conexión.
  `DB2_ATTR_CASE`
    Pasar el valor `DB2_CASE_NATURAL` especifica que los nombres de columnas serán devueltos en sus casos naturales. Pasar el valor `DB2_CASE_LOWER` especifica que los nombres de columnas serán devueltos en minúsculas. Pasar el valor `DB2_CASE_UPPER` especifica que los nombres de columnas serán devueltos en mayúsculas.
  `CURSOR`
    Pasar el valor `DB2_FORWARD_ONLY` especifica un cursor solo hacia adelante para un recurso de consulta. Este es el tipo de cursor por defecto y es soportado en todos los servidores de base de datos. Pasar el valor `DB2_SCROLLABLE` especifica un cursor desplazable para un recurso de consulta. Este modo permite un acceso aleatorio a las filas en un conjunto de resultados, pero actualmente, solo es soportado por la base de datos IBM DB2 Universal.

  Las siguientes opciones están disponibles desde ibm_db2 versión 1.7.0.

  `trustedcontext`
    Al pasar el valor DB2_TRUSTED_CONTEXT_ENABLE, el contexto de confianza es activado para esta conexión. Este parámetro no puede ser activado con db2_set_option(). Esta opción solo funciona si la base está catalogada, incluso si la base es local, o si se especifica un DSN completo al crear la conexión. Para catalogar la base, utilice el siguiente comando :

        db2 catalog tcpip node loopback remote <SERVERNAME> server <SERVICENAME>
        db2 catalog database <LOCALDBNAME> as <REMOTEDBNAME> at node loopback
        db2 "update dbm cfg using svcename <SERVICENAME>"
        db2set DB2COMM=TCPIP

  Las siguientes opciones i5/OS están disponibles desde ibm_db2 versión 1.5.1.

  Sugerencia

  Atributos de conexión contradictorios, en conjunción con una conexión persistente pueden producir resultados indeterminados en i5/OS. La política del sitio debe ser establecida para todas las aplicaciones que utilizan una conexión persistente. El valor por defecto de DB2_AUTOCOMMIT_ON es recomendado con las conexiones persistentes.

  `i5_lib`
    Un carácter que indica la biblioteca por defecto que será utilizada para resolver las referencias de ficheros no calificadas. Esta opción no es válida si la conexión utiliza el modo de nombramiento del sistema.
  `i5_naming`
    `DB2_I5_NAMING_ON` activa el modo de nombramiento del sistema de DB2 UDB CLI iSeries. Los ficheros son entonces calificados con el delimitador slash (/). Los ficheros no calificados son resueltos utilizando la lista de bibliotecas de la tarea. `DB2_I5_NAMING_OFF` activa el modo de nombramiento por defecto, que es el nombramiento SQL. Los ficheros son entonces calificados con el punto (.) . Los ficheros no calificados son resueltos con la biblioteca por defecto, o bien el identificador del usuario actual.
  `i5_commit`

    El atributo `i5_commit` debe ser configurado antes de la llamada a db2_pconnect(). Si el valor es cambiado después de la conexión, y la conexión se efectúa sobre datos remotos, entonces este cambio no tendrá efectos, hasta la próxima llamada exitosa a db2_pconnect().

    > Nota: La directiva del php.ini `ibm_db2.i5_allow_commit`==0 o `DB2_I5_TXN_NO_COMMIT` es el valor por defecto, pero puede ser reemplazado por la opción `i5_commit`.

    `DB2_I5_TXN_NO_COMMIT` : el control de validación no es utilizado. `DB2_I5_TXN_READ_UNCOMMITTED` : las lecturas inconsistentes, o no repetibles y los fantasmas son posibles. `DB2_I5_TXN_READ_COMMITTED` : las lecturas son consistentes. Las lecturas no repetibles y los fantasmas son posibles. `DB2_I5_TXN_REPEATABLE_READ` : las lecturas consistentes y repetibles, pero los fantasmas son posibles. `DB2_I5_TXN_SERIALIZABLE` : las transacciones son activadas. Las lecturas inconsistentes, o no repetibles y los fantasmas son imposibles.
  `i5_query_optimize`
    `DB2_FIRST_IO` : todas las consultas son optimizadas con el objetivo de devolver la primera página lo más rápidamente posible. Este objetivo funciona bien cuando el resultado es controlado por un usuario que tiene buenas probabilidades de cancelar la consulta después de ver las primeras respuestas. Las consultas codificadas con una cláusula `OPTIMIZE FOR nnn ROWS` respetan también este objetivo. `DB2_ALL_IO` : todas las consultas son optimizadas con el objetivo de procesar la consulta completa lo más rápidamente posible. Esta es una buena opción cuando el resultado de la consulta debe ser escrito en un fichero o un informe, o que la interfaz acumula todos los datos antes de exportarlos. Las consultas codificadas con la cláusula `OPTIMIZE FOR nnn ROWS` respetan también este objetivo. Este es el comportamiento por defecto.
  `i5_dbcs_alloc`
    `DB2_I5_DBCS_ALLOC_ON` activa el esquema de asignación DB2 6X para el crecimiento de las tallas de columnas de traducción DBCS.

    `DB2_I5_DBCS_ALLOC_OFF` desactiva el esquema de asignación DB2 6X para el crecimiento de las tallas de columnas de traducción DBCS.

    > Nota: La directiva del php.ini `ibm_db2.i5_dbcs_alloc`==0 o `DB2_I5_DBCS_ALLOC_OFF` es el valor por defecto, pero puede ser reemplazado por la opción `i5_dbcs_alloc`.

  `i5_date_fmt`
    `DB2_I5_FMT_ISO` : el formato de fecha ISO (`International Organization for Standardization`) es utilizado : `yyyy-mm-dd`. Este es el formato por defecto. `DB2_I5_FMT_USA` : el formato de los Estados Unidos de América es utilizado : `mm/dd/yyyy`. `DB2_I5_FMT_EUR` : el formato de fecha europeo `dd.mm.yyyy` es utilizado. `DB2_I5_FMT_JIS` : el formato estándar industrial japonés `yyyy-mm-dd` es utilizado. `DB2_I5_FMT_MDY` : el formato de fecha `mm/dd/yyyy` es utilizado. `DB2_I5_FMT_DMY` : el formato de fecha `dd/mm/yyyy` es utilizado. `DB2_I5_FMT_YMD` : el formato de fecha `yy/mm/dd` es utilizado. `DB2_I5_FMT_JUL` : El formato de fecha juliano `yy/ddd` es utilizado. `DB2_I5_FMT_JOB` : el formato de fecha por defecto es utilizado.
  `i5_date_sep`
    `DB2_I5_SEP_SLASH` : un slash ( / ) es utilizado como separador de fecha. Este es el formato por defecto. `DB2_I5_SEP_DASH` : un guión ( - ) es utilizado como separador de fecha. `DB2_I5_SEP_PERIOD` : un punto ( . ) es utilizado como separador de fecha. `DB2_I5_SEP_COMMA` : una coma ( , ) es utilizada como separador de fecha. `DB2_I5_SEP_BLANK` : un espacio es utilizado como separador de fecha. `DB2_I5_SEP_JOB` : la configuración por defecto es utilizada
  `i5_time_fmt`
    `DB2_I5_FMT_ISO` : el formato de hora ISO (`International Organization for Standardization`) es utilizado : `hh.mm.ss`. Este es el formato por defecto. `DB2_I5_FMT_USA` : el formato de los Estados Unidos de América es utilizado : `hh:mmxx` es utilizado, donde `xx` vale `AM` o `PM`. `DB2_I5_FMT_EUR` : el formato de hora europeo `hh.mm.ss` es utilizado. `DB2_I5_FMT_JIS` : el formato estándar industrial japonés es utilizado `hh:mm:ss`. `DB2_I5_FMT_HMS` : el formato `hh:mm:ss` es utilizado.
  `i5_time_sep`
    `DB2_I5_SEP_COLON` : un dos-puntos ( : ) es utilizado como separador de hora. Este es el defecto. `DB2_I5_SEP_PERIOD` : un punto ( . ) es utilizado como separador de hora. `DB2_I5_SEP_COMMA` : una coma ( , ) es utilizada como separador de hora. `DB2_I5_SEP_BLANK` : un espacio es utilizado como separador de hora. `DB2_I5_SEP_JOB` : el separador por defecto es utilizado.
  `i5_decimal_sep`
    `DB2_I5_SEP_PERIOD` : un punto ( . ) es utilizado como separador decimal. Este es el separador por defecto. `DB2_I5_SEP_COMMA` : una coma ( , ) es utilizada como separador decimal. `DB2_I5_SEP_JOB` : el separador por defecto es utilizado.

  Las siguientes opciones i5/OS están disponibles desde ibm_db2 versión 1.8.0.

  `i5_libl`

    Un carácter que indica la biblioteca que será utilizada para resolver las referencias de ficheros no calificadas. Especifique la lista de bibliotecas en la forma de elementos separados por espacios : `'i5_libl'=>"MYLIB YOURLIB ANYLIB"`.

    > Nota: i5_libl llama a `qsys2/qcmdexc('cmd',cmdlen)`, que está disponible desde i5/OS V5R4.

### Valores devueltos

Devuelve el recurso de conexión si la tentativa de conexión tiene éxito. db2_pconnect() intenta reutilizar un recurso de conexión existente que coincide perfectamente con los parámetros tales como la base de datos `database`, el usuario `username` y la contraseña `password`. Si la tentativa de conexión falla, db2_pconnect() devuelve `false`

### Historial de cambios

Versión | Descripción
--- | ---
PECL ibm_db2 1.9.0 | Las transacciones activas sobre conexiones persistentes serán anuladas al final de cada consulta.
PECL ibm_db2 1.8.0 | La opción `i5_libl` está disponible para los usuarios de i5/OS.
PECL ibm_db2 1.7.0 | La opción `trustedcontext` está disponible.
PECL ibm_db2 1.5.1 | Las opciones `i5_lib`, `i5_naming`, `i5_commit`, `i5_query_optimize`, `i5_dbcs_alloc`, `i5_date_fmt`, `i5_date_sep`, `i5_time_fmt`, `i5_time_sep` y `i5_decimal_sep` están disponibles para los usuarios de i5/OS.

### Ejemplos

Ejemplo #1 Ejemplo de uso de db2_pconnect()

En el siguiente ejemplo, la primera llamada a db2_pconnect() devuelve un nuevo recurso de conexión persistente. La segunda llamada a la función db2_pconnect() devuelve un recurso de conexión persistente que reutiliza el primer recurso de conexión.

    <?php
    $database = 'EJEMPLO';
    $user = 'db2inst1';
    $password = 'ibmdb2';

    $pconn = db2_pconnect($database, $user, $password);

    if ($pconn) {
        echo "Conexión persistente exitosa.";
    }
    else {
        echo "Conexión persistente fallida.";
    }

    $pconn2 = db2_pconnect($database, $user, $password);
    if ($pconn) {
        echo "Segunda conexión persistente exitosa.";
    }
    else {
        echo "Segunda conexión persistente fallida.";
    }
    ?>

El ejemplo anterior mostrará:

    Conexión persistente exitosa.
    Segunda conexión persistente exitosa.

Ejemplo #2 Uso de contextos de confianza DB2

El siguiente ejemplo muestra cómo activar un usuario de confianza, cambiar a él, y obtener un identificador de usuario.

    <?php

    $database = "SAMPLE";
    $hostname = "localhost";
    $port = 50000;
    $authID = "db2inst1";
    $auth_pass = "ibmdb2";

    $tc_user = "tcuser";
    $tc_pass = "tcpassword";

    $dsn = "DATABASE=$database;HOSTNAME=$hostname;PORT=$port;
      PROTOCOL=TCPIP;UID=$authID;PWD=$auth_pass;";
    $options = array ("trustedcontext" => DB2_TRUSTED_CONTEXT_ENABLE);

    $tc_conn = db2_pconnect($dsn, "", "", $options);
    if($tc_conn) {
        echo "Conexión de confianza exitosa.\n";

        if(db2_get_option($tc_conn, "trustedcontext")) {
            $userBefore = db2_get_option($tc_conn, "trusted_user");

            //Trabajo por el usuario 1.

            //Cambio al usuario de confianza.
            $parameters = array("trusted_user" => $tc_user,
              "trusted_password" => $tcuser_pass);
            $res = db2_set_option ($tc_conn, $parameters, 1);

            $userAfter = db2_get_option($tc_conn, "trusted_user");
            //Hacer más trabajo como usuario de confianza.

            if($userBefore != $userAfter) {
                echo "Usuario cambiado." . "\n";
            }
        }

        db2_close($tc_conn);
    }
    else {
        echo "Conexión de confianza fallida.\n";
    }
    ?>

El ejemplo anterior mostrará:

    Conexión de confianza exitosa.
    Usuario cambiado

### Ver también

- db2_connect() - Devuelve una conexión a una base de datos

# db2_prepare

(PECL ibm_db2 >= 1.0.0)

db2_prepare — Prepara una consulta SQL para ser ejecutada

### Descripción

function db2_prepare(resource `$connection`, string `$statement`, array `$options` = []): resource|false

db2_prepare() crea una consulta SQL preparada que puede incluir ningún o varios marcadores (caracteres `?`) representando los argumentos de entrada, salida o entrada/salida. Se pueden pasar argumentos a la consulta preparada utilizando la función db2_bind_param(), si solo hay entradas, se puede utilizar db2_execute().

Existen tres ventajas principales de utilizar consultas preparadas en la aplicación :

- Rendimiento : al preparar una consulta, el servidor de base de datos crea un plan de acceso optimizado para la recuperación de datos con la consulta. Posteriormente, el envío de la consulta preparada con db2_execute() permite a la consulta reutilizar el plan de acceso y así evitar sobrecargas del procesador en cada envío de consulta que crearía dinámicamente un nuevo plan de acceso.
- Seguridad : al preparar una consulta, se pueden incluir marcadores para los valores de entrada. Al ejecutar una consulta preparada con estos valores de entrada, el servidor de base de datos verifica cada valor de entrada para asegurarse de que los tipos coincidan con la definición de la columna o del parámetro de definición.
- Funcionalidad avanzada : Los marcadores permiten no solo pasar valores de entrada en las consultas SQL preparadas, sino también recuperar parámetros de SALIDA y de ENTRADA/SALIDA de los procedimientos de registro utilizando la función db2_bind_param().

### Parámetros

`connection`
  Una variable recurso de conexión válida devuelta por db2_connect() o db2_pconnect().
`statement`
  Una consulta SQL que puede contener uno o varios marcadores.
`options`
  Un array asociativo que contiene las opciones de la consulta. Se puede utilizar este parámetro para solicitar un cursor flotante en los servidores de base de datos que soportan esta funcionalidad. Para una descripción de las opciones válidas, consulte la función db2_set_option().

### Valores devueltos

Devuelve una variable recurso si la consulta SQL fue enviada correctamente o `false` si el servidor de base de datos ha devuelto un error. Se puede determinar qué error fue devuelto llamando a la función db2_stmt_error() o db2_stmt_errormsg().

### Ejemplos

Ejemplo #1 Preparación y ejecución de una consulta SQL con marcadores

El siguiente ejemplo prepara una consulta INSERT que acepta cuatro marcadores, luego itera sobre el array que contiene los valores de entrada que serán pasados a la función db2_execute().

    <?php
    $animales = array(
        array(0, 'gato', 'Pook', 3.2),
        array(1, 'perro', 'Peaches', 12.3),
        array(2, 'caballo', 'Smarty', 350.0),
    );

    $insert = 'INSERT INTO animales (id, raza, nombre, peso)
        VALUES (?, ?, ?, ?)';
    $stmt = db2_prepare($conn, $insert);
    if ($stmt) {
        foreach ($animales as $animal) {
            $result = db2_execute($stmt, $animal);
        }
    }
    ?>

### Ver también

- db2_bind_param() - Asocia una variable PHP a un parámetro de una consulta SQL
- db2_execute() - Ejecuta una consulta SQL preparada
- db2_stmt_error() - Devuelve un string que contiene el valor de SQLSTATE retornado por una consulta SQL
- db2_stmt_errormsg() - Devuelve el último mensaje de error de una consulta SQL

# db2_primary_keys

(PECL ibm_db2 >= 1.0.0)

db2_primary_keys — Devuelve un conjunto de resultados que lista las claves de una tabla

### Descripción

function db2_primary_keys(
resource `$connection`,
?string `$qualifier`,
?string `$schema`,
string `$table_name`
): resource

Devuelve un conjunto de resultados que lista las claves de una tabla.

### Parámetros

`connection`
  Una conexión válida a una base de datos IBM DB2, Cloudscape o Apache Derby.
`qualifier`
  Un calificador para las bases de datos DB2 que funcionan en los servidores OS/390 o z/OS. Para otras bases de datos, pase `null` o una cadena vacía.
`schema`
  El esquema que contiene las tablas. Si `schema` es `null`, db2_primary_keys() hace coincidir el esquema para la conexión actual.
`table_name`
  El nombre de la tabla.

### Valores devueltos

Devuelve un recurso con el conjunto de resultados que contiene filas que describen las claves primarias de la tabla especificada. El conjunto de resultados está compuesto por las siguientes columnas:

Nombre de la columna | Descripción
--- | ---
TABLE_CAT | Nombre del catálogo de la tabla que contiene la clave primaria. El valor es `null` si la tabla no tiene catálogo.
TABLE_SCHEM | Nombre del esquema de la tabla que contiene la clave primaria.
TABLE_NAME | Nombre de la tabla que contiene la clave primaria.
COLUMN_NAME | Nombre de la columna que contiene la clave primaria.
KEY_SEQ | Posición, comenzando en 1, de la columna en la clave.
PK_NAME | Nombre de la clave primaria.

### Ver también

- db2_column_privileges() - Devuelve un conjunto de resultados que lista las columnas y sus privilegios de una tabla
- db2_columns() - Devuelve un conjunto de resultados que lista las columnas y sus metadatos de una tabla
- db2_foreign_keys() - Devuelve un conjunto de resultados que lista las claves externas de una tabla
- db2_procedure_columns() - Devuelve un conjunto de resultados que lista los argumentos de procedimiento de registro
- db2_procedures() - Devuelve un conjunto de resultados que lista las proceduras de registro almacenadas en la base de datos
- db2_special_columns() - Devuelve un conjunto de resultados que lista los identificadores únicos de las filas de una tabla
- db2_statistics() - Devuelve un conjunto de resultados que enumera los índices y estadísticas de una tabla
- db2_table_privileges() - Devuelve un conjunto de resultados que lista las tablas y sus privilegios asociados en una base de datos
- db2_tables() - Devuelve la lista de tablas y sus metadatos

# db2_procedure_columns

(PECL ibm_db2 >= 1.0.0)

db2_procedure_columns — Devuelve un conjunto de resultados que lista los argumentos de procedimiento de registro

### Descripción

function db2_procedure_columns(
resource `$connection`,
?string `$qualifier`,
string `$schema`,
string `$procedure`,
?string `$parameter`
): resource

Devuelve un conjunto de resultados que lista los argumentos para uno o varios procedimientos de registro.

### Parámetros

`connection`
  Una conexión válida a una base de datos IBM DB2, Cloudscape o Apache Derby.
`qualifier`
  Un calificador para las bases de datos DB2 que funcionan en los servidores OS/390 o z/OS. Para otras bases de datos, pase `null` o una cadena vacía.
`schema`
  El esquema que contiene las tablas. El argumento acepta formas que contienen `_` y `%` como comodín.
`procedure`
  El nombre del procedimiento. El argumento acepta formas que contienen `_` y `%` como comodín.
`parameter`
  El nombre del argumento. Este argumento acepta un argumento de búsqueda que contiene `_` y `%` como comodín. Si este argumento es `null`, se devuelven todos los argumentos para el procedimiento de registro especificado.

### Valores devueltos

Devuelve un recurso con el conjunto de resultados que contiene las filas que describen los argumentos para los procedimientos de registro que coinciden con los argumentos especificados. Las filas están compuestas por las siguientes columnas:

Nombre de la columna | Descripción
--- | ---
PROCEDURE_CAT | Nombre del catálogo que contiene la tabla. El valor es `null` si la tabla no tiene catálogo.
PROCEDURE_SCHEM | Nombre del esquema que contiene el procedimiento de registro.
PROCEDURE_NAME | Nombre del procedimiento.
COLUMN_NAME | Nombre del argumento.
COLUMN_TYPE | Un integer que representa el tipo del argumento:
Valor de retorno | Tipo de argumento
--- | ---
1 (SQL_PARAM_INPUT) | Argumento de entrada (IN).
2 (SQL_PARAM_INPUT_OUTPUT) | Argumento de entrada/salida (INOUT).
3 (SQL_PARAM_OUTPUT) | Argumento de salida (OUT).
DATA_TYPE | El tipo de datos SQL para el argumento representado como integer.
TYPE_NAME | Una string que representa el tipo de datos para el argumento.
COLUMN_SIZE | Un integer que representa el tamaño del argumento.
BUFFER_LENGTH | Número máximo de bytes necesarios para almacenar datos de este argumento.
DECIMAL_DIGITS | La escala del argumento o `null` donde la escala no es aplicable.
NUM_PREC_RADIX | Un integer que puede ser `10` (que representa un tipo de datos numérico exacto), `2` (que representa una aproximación de tipo de datos numéricos) o `null` (que representa un tipo de datos para el cual la base no es aplicable).
NULLABLE | Un integer que representa si el argumento puede ser nulo o no.
REMARKS | Descripción del argumento.
COLUMN_DEF | Valor por defecto del argumento.
SQL_DATA_TYPE | Un integer que representa el tamaño del argumento.
SQL_DATETIME_SUB | Devuelve un integer que representa un código de subtipo `datetime` o `null` si los tipos de datos SQL no aplican.
CHAR_OCTET_LENGTH | Tamaño máximo en bytes para los tipos de datos de carácter del argumento, que coincide con COLUMN_SIZE para un solo byte de datos o `null` para un tipo de datos que no es de caracteres.
ORDINAL_POSITION | La posición del argumento comenzando en 1 en la consulta `CALL`.
IS_NULLABLE | Una string cuyo valor es `YES` significa que el argumento acepta o devuelve valores `null` y `NO` significa que el argumento no acepta ni devuelve valores `null`.

### Ver también

- db2_column_privileges() - Devuelve un conjunto de resultados que lista las columnas y sus privilegios de una tabla
- db2_columns() - Devuelve un conjunto de resultados que lista las columnas y sus metadatos de una tabla
- db2_foreign_keys() - Devuelve un conjunto de resultados que lista las claves externas de una tabla
- db2_primary_keys() - Devuelve un conjunto de resultados que lista las claves de una tabla
- db2_procedures() - Devuelve un conjunto de resultados que lista las proceduras de registro almacenadas en la base de datos
- db2_special_columns() - Devuelve un conjunto de resultados que lista los identificadores únicos de las filas de una tabla
- db2_statistics() - Devuelve un conjunto de resultados que enumera los índices y estadísticas de una tabla
- db2_table_privileges() - Devuelve un conjunto de resultados que lista las tablas y sus privilegios asociados en una base de datos
- db2_tables() - Devuelve la lista de tablas y sus metadatos

# db2_procedures

(PECL ibm_db2 >= 1.0.0)

db2_procedures — Devuelve un conjunto de resultados que lista las proceduras de registro almacenadas en la base de datos

### Descripción

function db2_procedures(
resource `$connection`,
?string `$qualifier`,
string `$schema`,
string `$procedure`
): resource

Devuelve un conjunto de resultados que lista las proceduras de registro almacenadas en la base de datos.

### Parámetros

`connection`
  Una conexión válida a una base de datos IBM DB2, Cloudscape o Apache Derby.
`qualifier`
  Un calificador para las bases de datos DB2 que funcionan en los servidores OS/390 o z/OS. Para otras bases de datos, pase `null` o una cadena vacía.
`schema`
  El esquema que contiene las tablas. El parámetro acepta las formas que contienen `_` y `%` como palabras clave.
`procedure`
  El nombre de la procedura. El parámetro acepta las formas que contienen `_` y `%` como palabras clave.

### Valores devueltos

Devuelve un recurso con el conjunto de resultados que contiene las filas que describen las proceduras de registro que coinciden con los parámetros especificados. Las filas están compuestas por las siguientes columnas:

Nombre de la columna | Descripción
--- | ---
PROCEDURE_CAT | Nombre del catálogo que contiene la tabla. El valor es `null` si la tabla no tiene catálogo.
PROCEDURE_SCHEM | Nombre del esquema que contiene la procedura de registro.
PROCEDURE_NAME | Nombre de la procedura.
NUM_INPUT_PARAMS | Número de parámetros de entrada (IN) para la procedura de registro.
NUM_OUTPUT_PARAMS | Número de parámetros de salida (OUT) para la procedura de registro.
NUM_RESULT_SETS | Número de conjuntos de resultados devueltos por la procedura de registro.
REMARKS | Comentarios sobre la procedura de registro.
PROCEDURE_TYPE | Siempre devuelve `1`, indicando que la procedura de registro no devuelve ningún valor de retorno.

### Ver también

- db2_column_privileges() - Devuelve un conjunto de resultados que lista las columnas y sus privilegios de una tabla
- db2_columns() - Devuelve un conjunto de resultados que lista las columnas y sus metadatos de una tabla
- db2_foreign_keys() - Devuelve un conjunto de resultados que lista las claves externas de una tabla
- db2_primary_keys() - Devuelve un conjunto de resultados que lista las claves de una tabla
- db2_procedure_columns() - Devuelve un conjunto de resultados que lista los argumentos de procedimiento de registro
- db2_special_columns() - Devuelve un conjunto de resultados que lista los identificadores únicos de las filas de una tabla
- db2_statistics() - Devuelve un conjunto de resultados que enumera los índices y estadísticas de una tabla
- db2_table_privileges() - Devuelve un conjunto de resultados que lista las tablas y sus privilegios asociados en una base de datos
- db2_tables() - Devuelve la lista de tablas y sus metadatos

# db2_result

(PECL ibm_db2 >= 1.0.0)

db2_result — Devuelve un valor de una columna de una fila de un conjunto de resultados

### Descripción

function db2_result(resource `$stmt`, int|string `$column`): ?mixed

Utilice db2_result() para devolver un valor de una columna específica en la fila actual de un conjunto de resultados. Debe llamarse a db2_fetch_row() antes de llamar a db2_result() para almacenar los valores apuntados del conjunto de resultados.

### Parámetros

`stmt`
  Un recurso `stmt` válido.
`column`
  Un array de enteros que comienza con el índice 0 que apunta a los campos del conjunto de resultados o una cadena que representa el nombre de la columna.

### Valores devueltos

Devuelve el valor del campo solicitado si el campo existe en el conjunto de resultados. Devuelve `null` si el campo no existe y genera una alerta PHP.

### Ejemplos

Ejemplo #1 Ejemplo de uso de db2_result()

El siguiente ejemplo demuestra cómo iterar a través de un conjunto de resultados con la función db2_fetch_row() y recuperar las columnas del conjunto de resultados con db2_result().

    <?php
    $sql = 'SELECT nom, race FROM animales WHERE poids < ?';
    $stmt = db2_prepare($conn, $sql);
    db2_execute($stmt, array(10));
    while (db2_fetch_row($stmt)) {
        $nom = db2_result($stmt, 0);
        $race = db2_result($stmt, 'RACE');
        print "$nom $race";
    }
    ?>

El ejemplo anterior mostrará:

    chat Pook
    cyprin doré Bubbles
    perruche Gizmo
    chèvre Rickety Ride

### Ver también

- db2_fetch_array() - Devuelve un array, indexado por la posición de las columnas, que representa una línea del conjunto de resultados
- db2_fetch_assoc() - Devuelve un array, indexado por nombre de columna, que representa una fila del conjunto de resultados
- db2_fetch_both() - Devuelve un array, indexado por nombre de columna y posición, que representa una fila del conjunto de resultados
- db2_fetch_object() - Devuelve un objeto con las propiedades que representan columnas en la fila extraída
- db2_fetch_row() - Modifica el puntero del conjunto de resultados a la siguiente línea o a la línea solicitada

# db2_rollback

(PECL ibm_db2 >= 1.0.0)

db2_rollback — Cancelar una transacción

### Descripción

function db2_rollback(resource `$connection`): bool

Cancela una transacción en progreso en el recurso de conexión especificado y comienza una nueva transacción. Comunmente las aplicaciones de PHP confirman las transacciones de manera automática por lo que la función db2_rollback() no tendría efecto a menos que este modo haya sido desactivado para este recurso.

### Parámetros

`connection`
  Un recurso de conexión válido devuelto por db2_connect() o db2_pconnect().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Cancelando una sentencia DELETE

En el siguiente ejemplo se cuenta el número de filas en una tabla, se cancelan las confirmaciones automáticas en la conexión, se eliminan todas las filas de la tabla y devuelve el total de `0` para confirmar que las filas se han borrado. Cuando se llama a db2_rollback() y se devuelve el total actualizado de filas en la tabla para demostrar que el número es igual al original (antes de ejecutar la sentancia DELETE). Esto demuestra que la cancelación de la transacción fue correcto.

    <?php
    $conn = db2_connect($database, $user, $password);

    if ($conn) {
        $stmt = db2_exec($conn, "SELECT count(*) FROM animals");
        $res = db2_fetch_array( $stmt );
        echo $res[0] . "\n";

        // Desactivar AUTOCOMMIT
        db2_autocommit($conn, DB2_AUTOCOMMIT_OFF);

        // Eliminar todas las filas de ANIMALS
        db2_exec($conn, "DELETE FROM animals");

        $stmt = db2_exec($conn, "SELECT count(*) FROM animals");
        $res = db2_fetch_array( $stmt );
        echo $res[0] . "\n";

        // Deshacer la sentencia DELETE
        db2_rollback( $conn );

        $stmt = db2_exec( $conn, "SELECT count(*) FROM animals" );
        $res = db2_fetch_array( $stmt );
        echo $res[0] . "\n";
        db2_close($conn);
    }
    ?>

El ejemplo anterior mostrará:

    7
    0
    7

### Ver también

- db2_autocommit() - Devuelve o modifica el estado AUTOCOMMIT de la conexión a la base de datos
- db2_commit() - Confirmar una transacción

# db2_server_info

(PECL ibm_db2 >= 1.1.1)

db2_server_info — Devuelve un objeto con propiedades que describen el servidor de base de datos DB2

### Descripción

function db2_server_info(resource `$connection`): stdClass|false

Esta función devuelve un objeto con propiedades de solo lectura que proporcionan información sobre el servidor de base de datos IBM DB2, Cloudscape o Apache Derby. La tabla siguiente lista las propiedades del servidor de base de datos:

Propiedades del servidor de base de datos
Nombre de la propiedad | Tipo de retorno | Descripción
--- | --- | ---
DBMS_NAME | string | El nombre del servidor de base de datos al que se está conectado. Para servidores DB2, es una combinación de `DB2` seguido del sistema operativo en el que funciona el servidor de base de datos.
DBMS_VER | string | La versión del servidor de base de datos, en formato de string `"MM.mm.uuuu"` donde MM es la versión mayor, mm es la versión menor y uuuu es la actualización. Por ejemplo, `"08.02.0001"` representa la versión mayor 8, la versión menor 2, la actualización 1.
DB_CODEPAGE | int | La página de código de la base de datos a la que se está conectado.
DB_NAME | string | El nombre de la base de datos a la que se está conectado.
DFT_ISOLATION | string | El nivel predeterminado de aislamiento de transacción soportado por el servidor: UR Lectura no confirmada (`Uncommitted read`): los cambios son inmediatamente visibles para todas las transacciones concurrentes. CS Estabilidad del cursor (`Cursor stability`): una fila leída por una transacción puede ser modificada y confirmada por una segunda transacción concurrente. RS Estabilidad de lectura (`Read stability`): una transacción puede agregar o eliminar filas que coincidan con una condición de búsqueda o una transacción pendiente. RR Lectura repetible (`Repeatable read`): los datos afectados por las transacciones pendientes no están disponibles para otras transacciones. NC Sin confirmación (`No commit`): todo cambio es visible al final de una operación exitosa. Las confirmaciones explícitas y los retrocesos no están permitidos.
IDENTIFIER_QUOTE_CHAR | string | El carácter utilizado para delimitar un identificador.
INST_NAME | string | La instancia en el servidor de base de datos que contiene la base de datos.
ISOLATION_OPTION | array | Un array de opciones de aislamiento soportadas por el servidor de base de datos. Las opciones de aislamiento se describen en la propiedad DFT_ISOLATION.
KEYWORDS | array | Un array de palabras clave reservadas por el servidor de base de datos.
LIKE_ESCAPE_CLAUSE | bool | `true` si el servidor de base de datos soporta el uso de los caracteres comodín `%` y `_`. `false` si el servidor de base de datos no soporta estos caracteres comodín.
MAX_COL_NAME_LEN | int | Tamaño máximo de un nombre de columna soportado por el servidor de base de datos, expresado en bytes.
MAX_IDENTIFIER_LEN | int | Tamaño máximo de un identificador SQL soportado por los servidores de base de datos, expresado en caracteres.
MAX_INDEX_SIZE | int | Tamaño máximo de las columnas combinadas en un índice soportado por el servidor de base de datos, expresado en bytes.
MAX_PROC_NAME_LEN | int | Tamaño máximo de un nombre de procedimiento soportado por el servidor de base de datos, expresado en bytes.
MAX_ROW_SIZE | int | Tamaño máximo de una fila en la tabla de base soportada por el servidor de base de datos, expresado en bytes.
MAX_SCHEMA_NAME_LEN | int | Tamaño máximo de un nombre de esquema soportado por el servidor de base de datos, expresado en bytes.
MAX_STATEMENT_LEN | int | Tamaño máximo de una consulta SQL soportada por el servidor de base de datos, expresado en bytes.
MAX_TABLE_NAME_LEN | int | Tamaño máximo de un nombre de tabla soportado por el servidor de base de datos, expresado en bytes.
NON_NULLABLE_COLUMNS | bool | `true` si el servidor de base de datos soporta las columnas que pueden ser definidas como NOT NULL, `false` si el servidor de base de datos no soporta las columnas definidas como NOT NULL.
PROCEDURES | bool | `true` si el servidor de base de datos soporta el uso de la consulta CALL para llamar a los procedimientos almacenados, `false` si el servidor de base de datos no soporta la consulta CALL.
SPECIAL_CHARS | string | Un string que contiene todos los caracteres distintos de las letras (mayúsculas y minúsculas), los dígitos y el carácter de subrayado que pueden ser utilizados como nombre de identificador.
SQL_CONFORMANCE | string | El nivel de conformidad con la especificación ANSI/ISO SQL-92 ofrecido por el servidor de base de datos: ENTRY Nivel de conformidad SQL-92. FIPS127 Conformidad tradicional FIPS-127-2. FULL Nivel completo de conformidad SQL-92. INTERMEDIATE Nivel intermedio de conformidad SQL-92.

### Parámetros

`connection`
  Especifica la conexión cliente DB2 activa.

### Valores devueltos

Devuelve un objeto si la llamada es exitosa, o `false` si ocurre un error

### Ejemplos

Ejemplo #1 Ejemplo con db2_server_info()

Para recuperar información sobre el servidor, se debe pasar un recurso de conexión de base de datos válido a la función db2_server_info().

    <?php

    $conn = db2_connect('sample', 'db2inst1', 'ibmdb2');

    $server = db2_server_info( $conn );

    if ($server) {
        echo "DBMS_NAME: ";                 var_dump( $server->DBMS_NAME );
        echo "DBMS_VER: ";                  var_dump( $server->DBMS_VER );
        echo "DB_CODEPAGE: ";               var_dump( $server->DB_CODEPAGE );
        echo "DB_NAME: ";                   var_dump( $server->DB_NAME );
        echo "INST_NAME: ";                 var_dump( $server->INST_NAME );
        echo "SPECIAL_CHARS: ";             var_dump( $server->SPECIAL_CHARS );
        echo "KEYWORDS: ";                  var_dump( sizeof($server->KEYWORDS) );
        echo "DFT_ISOLATION: ";             var_dump( $server->DFT_ISOLATION );
        echo "ISOLATION_OPTION: ";
        $il = '';
        foreach( $server->ISOLATION_OPTION as $opt )
        {
           $il .= $opt." ";
        }
        var_dump( $il );
        echo "SQL_CONFORMANCE: ";           var_dump( $server->SQL_CONFORMANCE );
        echo "PROCEDURES: ";                var_dump( $server->PROCEDURES );
        echo "IDENTIFIER_QUOTE_CHAR: ";     var_dump( $server->IDENTIFIER_QUOTE_CHAR );
        echo "LIKE_ESCAPE_CLAUSE: ";        var_dump( $server->LIKE_ESCAPE_CLAUSE );
        echo "MAX_COL_NAME_LEN: ";          var_dump( $server->MAX_COL_NAME_LEN );
        echo "MAX_ROW_SIZE: ";              var_dump( $server->MAX_ROW_SIZE );
        echo "MAX_IDENTIFIER_LEN: ";        var_dump( $server->MAX_IDENTIFIER_LEN );
        echo "MAX_INDEX_SIZE: ";            var_dump( $server->MAX_INDEX_SIZE );
        echo "MAX_PROC_NAME_LEN: ";         var_dump( $server->MAX_PROC_NAME_LEN );
        echo "MAX_SCHEMA_NAME_LEN: ";       var_dump( $server->MAX_SCHEMA_NAME_LEN );
        echo "MAX_STATEMENT_LEN: ";         var_dump( $server->MAX_STATEMENT_LEN );
        echo "MAX_TABLE_NAME_LEN: ";        var_dump( $server->MAX_TABLE_NAME_LEN );
        echo "NON_NULLABLE_COLUMNS: ";      var_dump( $server->NON_NULLABLE_COLUMNS );

        db2_close($conn);
    }
    ?>

El ejemplo anterior mostrará:

    DBMS_NAME: string(9) "DB2/LINUX"
    DBMS_VER: string(10) "08.02.0000"
    DB_CODEPAGE: int(1208)
    DB_NAME: string(6) "SAMPLE"
    INST_NAME: string(8) "db2inst1"
    SPECIAL_CHARS: string(2) "@#"
    KEYWORDS: int(179)
    DFT_ISOLATION: string(2) "CS"
    ISOLATION_OPTION: string(12) "UR CS RS RR "
    SQL_CONFORMANCE: string(7) "FIPS127"
    PROCEDURES: bool(true)
    IDENTIFIER_QUOTE_CHAR: string(1) """
    LIKE_ESCAPE_CLAUSE: bool(true)
    MAX_COL_NAME_LEN: int(30)
    MAX_ROW_SIZE: int(32677)
    MAX_IDENTIFIER_LEN: int(18)
    MAX_INDEX_SIZE: int(1024)
    MAX_PROC_NAME_LEN: int(128)
    MAX_SCHEMA_NAME_LEN: int(30)
    MAX_STATEMENT_LEN: int(2097152)
    MAX_TABLE_NAME_LEN: int(128)
    NON_NULLABLE_COLUMNS: bool(true)

### Ver también

- db2_client_info() - Devuelve un objeto con propiedades que describen el cliente de base de datos DB2

# db2_set_option

(PECL ibm_db2 >= 1.0.0)

db2_set_option — Establece opciones para una conexión o recursos

### Descripción

function db2_set_option(resource `$resource`, array `$options`, int `$type`): bool

Establece opciones para un recurso o una conexión. No se pueden establecer opciones para un conjunto de resultados.

### Parámetros

`resource`
  Un recurso válido como el devuelto por db2_prepare() o una conexión válida como la devuelta por db2_connect() o db2_pconnect().
`options`

  Un array asociativo que contiene opciones de recursos o de conexión válidas. Este parámetro puede ser utilizado para cambiar los valores de autocommit, tipos de cursor (flotante o de avance único) y especificar la capitalización de los nombres de columna (minúscula, mayúscula o natural) que aparecerá en el conjunto de resultados.

  `autocommit`
    Pasar `DB2_AUTOCOMMIT_ON` activa el autocommit para la conexión especificada. Pasar `DB2_AUTOCOMMIT_OFF` desactiva el autocommit para la conexión especificada.
  `cursor`
    Pasar `DB2_FORWARD_ONLY` especifica un cursor de avance único para un recurso. Este es el tipo por defecto para un cursor y es soportado por todos los servidores de base de datos. Pasar `DB2_SCROLLABLE` especifica un cursor flotante para un recurso. Los cursores flotantes permiten que las filas de resultados sean accesibles en un orden no secuencial. Este tipo de cursor es soportado solo por las bases de datos IBM DB2 Universal Database.
  `binmode`
    Pasar `DB2_BINARY` especifica que los datos binarios serán devueltos como tales. Este es el modo por defecto. Esto es equivalente a la configuración `ibm_db2.binmode=1` en php.ini. Pasar `DB2_CONVERT` especifica que los datos binarios serán convertidos a codificación hexadecimal y serán devueltos así. Esto es equivalente a la configuración `ibm_db2.binmode=2` en php.ini. Pasar `DB2_PASSTHRU` especifica que los datos binarios serán convertidos a `null`. Esto es equivalente a la configuración `ibm_db2.binmode=3` en php.ini.
  `db2_attr_case`
    Pasar `DB2_CASE_LOWER` especifica que los nombres de las columnas en el conjunto de resultados serán devueltos en minúsculas. Pasar `DB2_CASE_UPPER` especifica que los nombres de las columnas en el conjunto de resultados serán devueltos en mayúsculas. Pasar `DB2_CASE_NATURAL` especifica que los nombres de columnas en el conjunto de resultados serán devueltos en su capitalización natural.
  `deferred_prepare`
    Pasar `DB2_DEFERRED_PREPARE_ON` activa la preparación diferida en el recurso de consulta especificado. Pasar `DB2_DEFERRED_PREPARE_OFF` desactiva la preparación diferida en el recurso de consulta especificado.

  Las siguientes nuevas opciones i5/OS están disponibles desde la versión 1.5.1 de ibm_db2. Estas opciones se aplican únicamente cuando PHP e ibm_db2 funcionan de forma nativa en un sistema i5.

  `i5_fetch_only`
    `DB2_I5_FETCH_ON`: los cursores son de solo lectura y no pueden ser utilizados para posicionar actualizaciones y eliminaciones. Este es el valor por defecto a menos que la variable de entorno `SQL_ATTR_FOR_FETCH_ONLY` haya sido establecida a `SQL_FALSE`. `DB2_I5_FETCH_OFF`: los cursores pueden ser posicionados para actualizaciones y eliminaciones.

  Las siguientes nuevas opciones están disponibles desde ibm_db2 versión 1.8.0 y posteriores.

  `rowcount`
    `DB2_ROWCOUNT_PREFETCH_ON` - El cliente puede solicitar un conteo completo de las filas antes de recuperarlas, lo que significa que la función db2_num_rows() devuelve el número de filas seleccionadas incluso si se utiliza un cursor `ROLLFORWARD_ONLY`. `DB2_ROWCOUNT_PREFETCH_OFF` - El cliente no puede solicitar un conteo completo de las filas antes de recuperarlas.

  Las siguientes opciones son nuevas y están disponibles desde ibm_db2 versión 1.7.0.

  `trusted_user`
    Para cambiar al usuario a un usuario de confianza, indique el identificador de usuario como string del usuario de confianza que desea utilizar. Esta opción puede ser configurada solo a nivel de conexión. Para utilizar esta opción, un contexto de confianza debe estar activado en el recurso de conexión.
  `trusted_password`
    La contraseña, como string, que corresponde al usuario de confianza.

  Las siguientes opciones son nuevas y están disponibles desde ibm_db2 versión 1.6.0. Estas opciones son útiles para obtener información de seguimiento, accesible a través de db2_get_option().

  > Nota: Cuando el valor de cada opción está a punto de ser definido, algunos servidores pueden no manejar toda la longitud proporcionada y pueden truncar el valor. Para asegurarse de que los datos especificados en cada opción se convertirán correctamente cuando se transmitan al sistema, utilice solo los caracteres de A a Z, 0 a 9, los guiones bajos (`_`) y los puntos (`.`).

  `userid`

    `SQL_ATTR_INFO_USERID`: un puntero a un string terminado por `null` utilizado para identificar el ID de usuario del cliente enviado al servidor de base de datos, durante la conexión DB2.

    > Nota: DB2 para servidores z/OS y OS/390 soporta una longitud mayor a 16 caracteres. El ID de usuario no debe confundirse con el ID de usuario de identificación, se utiliza para los procesos de identificación únicamente y no para los de autorización.

  `acctstr`

    `SQL_ATTR_INFO_ACCTSTR`: un puntero a un string terminado por `null` utilizado para identificar la cuenta del cliente a enviar al servidor de base de datos durante la conexión DB2.

    > Nota: DB2 para servidores z/OS y OS/390 soporta una longitud mayor a 200 caracteres.

  `applname`

    `SQL_ATTR_INFO_APPLNAME`: un puntero a un string terminado por `null` utilizado para identificar el nombre de la aplicación cliente a enviar al servidor de base de datos durante la conexión DB2.

    > Nota: DB2 para servidores z/OS y OS/390 soporta una longitud mayor a 32 caracteres.

  `wrkstnname`

    `SQL_ATTR_INFO_WRKSTNNAME`: un puntero a un string terminado por `null` utilizado para identificar el nombre de la estación a enviar al servidor de base de datos durante la conexión DB2.

    > Nota: DB2 para servidores z/OS y OS/390 soporta una longitud mayor a 18 caracteres.

`type`
  Un int que especifica el tipo de recurso que ha sido pasado a la función. El tipo de recurso y valor deben coincidir. Pasar `1` como valor especifica que un recurso de conexión ha sido pasado a la función. Pasar cualquier int diferente de `1` como valor especifica que un recurso ha sido pasado a la función.

La siguiente tabla especifica qué opciones son compatibles con qué tipos de recursos:

Matriz de parámetros de recurso
Clave | Valor | Tipo de recurso
--- | --- | ---
|  | Conexión | Consulta | Conjunto de resultados
autocommit | `DB2_AUTOCOMMIT_ON` | X | - | -
autocommit | `DB2_AUTOCOMMIT_OFF` | X | - | -
cursor | `DB2_SCROLLABLE` | - | X | -
cursor | `DB2_FORWARD_ONLY` | - | X | -
binmode | `DB2_BINARY` | X | X | -
binmode | `DB2_CONVERT` | X | X | -
binmode | `DB2_PASSTHRU` | X | X | -
db2_attr_case | `DB2_CASE_LOWER` | X | X | -
db2_attr_case | `DB2_CASE_UPPER` | X | X | -
db2_attr_case | `DB2_CASE_NATURAL` | X | X | -
deferred_prepare | `DB2_DEFERRED_PREPARE_ON` | - | X | -
deferred_prepare | `DB2_DEFERRED_PREPARE_OFF` | - | X | -
i5_fetch_only | `DB2_I5_FETCH_ON` | - | X | -
rowcount | `DB2_ROWCOUNT_PREFETCH_ON` | - | X | -
rowcount | `DB2_ROWCOUNT_PREFETCH_OFF` | - | X | -
trusted_user | `<USER NAME> (String)` | X | - | -
trusted_password | `<PASSWORD> (String)` | X | - | -
i5_fetch_only | `DB2_I5_FETCH_OFF` | - | X | -
userid | `SQL_ATTR_INFO_USERID` | X | X | -
acctstr | `SQL_ATTR_INFO_ACCTSTR` | X | X | -
applname | `SQL_ATTR_INFO_APPLNAME` | X | X | -
wrkstnname | `SQL_ATTR_INFO_WRKSTNNAME` | X | X | -

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Establecer un parámetro en un recurso de conexión

    <?php
    /* Parámetros de Conexión */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Cadenas de Conexión */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Obtención del Recurso de Conexión */
    $conn = db2_connect($conn_string, '', '');

    /* Crea el array asociativo de opciones con pares clave-valor válidos */
    $options = array('autocommit' => DB2_AUTOCOMMIT_ON);

    /* Llamada a la función utilizando el tipo correcto de recurso, el array
    * de opciones y el valor type */
    $result = db2_set_option($conn, $options, 1);

    /* Verifica si todas las opciones pueden ser establecidas correctamente */
    if($result)
    {
       echo 'Opciones establecidas correctamente';
    }
    else
    {
       echo 'No se pueden establecer las opciones';
    }
    ?>

El ejemplo anterior mostrará:

    Opciones establecidas correctamente

Ejemplo #2 Establece múltiples parámetros con un recurso de conexión

    <?php
    /* Parámetros de Conexión */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Cadenas de Conexión */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Obtención del Recurso de Conexión */
    $conn = db2_connect($conn_string, '', '');

    /* Crea el array asociativo de opciones con pares clave-valor válidos */
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
    'binmode' => DB2_PASSTHRU,
    'db2_attr_case' => DB2_CASE_UPPER,
    'cursor' => DB2_SCROLLABLE);

    /* Llamada a la función utilizando el tipo correcto de recurso, el array
    * de opciones y el valor type */
    $result = db2_set_option($conn, $options, 1);

    /* Verifica si todas las opciones pueden ser establecidas correctamente */
    if($result)
    {
      echo 'Opciones establecidas correctamente';
    }
    else
    {
      echo 'No se pueden establecer las opciones';
    }
    ?>

El ejemplo anterior mostrará:

    Opciones establecidas correctamente

Ejemplo #3 Establece múltiples parámetros con una clave inválida

    <?php
    /* Parámetros de Conexión */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Cadenas de Conexión */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Obtención del Recurso de Conexión */
    $conn = db2_connect($conn_string, '', '');

    /* Crea el array asociativo de opciones con pares clave-valor válidos */
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
    'MI_CLAVE_INVÁLIDA' => DB2_PASSTHRU,
    'db2_attr_case' => DB2_CASE_UPPER,
    'cursor' => DB2_SCROLLABLE);

    /* Llamada a la función utilizando el tipo correcto de recurso, el array
    * de opciones y el valor type */
    $result = db2_set_option($conn, $options, 1);

    /* Verifica si todas las opciones pueden ser establecidas correctamente */
    if($result)
    {
       echo 'Opciones establecidas correctamente';
    }
    else
    {
       echo 'No se pueden establecer las opciones';
    }
    ?>

El ejemplo anterior mostrará:

    No se pueden establecer las opciones

Ejemplo #4 Establece múltiples parámetros con un valor inválido

    <?php
    /* Parámetros de Conexión */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Cadenas de Conexión */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Obtención del Recurso de Conexión */
    $conn = db2_connect($conn_string, '', '');

    /* Crea el array asociativo de opciones con pares clave-valor válidos */
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
    'binmode' => 'VALOR_INVÁLIDO',
    'db2_attr_case' => DB2_CASE_UPPER,
    'cursor' => DB2_SCROLLABLE);

    /* Llamada a la función utilizando el tipo correcto de recurso, el array
    * de opciones y el valor type */
    $result = db2_set_option($conn, $options, 1);

    /* Verifica si todas las opciones pueden ser establecidas correctamente */
    if($result)
    {
       echo 'Opciones establecidas correctamente';
    }
    else
    {
       echo 'No se pueden establecer las opciones';
    }
    ?>

El ejemplo anterior mostrará:

    No se pueden establecer las opciones

Ejemplo #5 Establece múltiples parámetros con un recurso de conexión y un tipo incorrecto

    <?php
    /* Parámetros de Conexión */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Cadenas de Conexión */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Obtención del Recurso de Conexión */
    $conn = db2_connect($conn_string, '', '');

    /* Crea el array asociativo de opciones con pares clave-valor válidos */
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
    'binmode' => DB2_PASSTHRU,
    'db2_attr_case' => DB2_CASE_UPPER,
    'cursor' => DB2_SCROLLABLE);

    /* Llamada a la función utilizando el tipo incorrecto de recurso, el array
    * de opciones y el valor type inválido */
    $result = db2_set_option($conn, $options, 2);

    /* Verifica si todas las opciones pueden ser establecidas correctamente */
    if($result)
    {
      echo 'Opciones establecidas correctamente';
    }
    else
    {
      echo 'No se pueden establecer las opciones';
    }
    ?>

El ejemplo anterior mostrará:

    No se pueden establecer las opciones

Ejemplo #6 Establece múltiples parámetros con un recurso incorrecto

    <?php
    /* Parámetros de Conexión */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Cadenas de Conexión */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Obtención del Recurso de Conexión */
    $conn = db2_connect($conn_string, '', '');

    /* Crea el array asociativo de opciones con pares clave-valor válidos */
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
    'binmode' => DB2_PASSTHRU,
    'db2_attr_case' => DB2_CASE_UPPER,
    'cursor' => DB2_SCROLLABLE);

    $stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE');

    /* Llamada a la función utilizando el tipo incorrecto de recurso, pero el array
    * de opciones y el valor type válido */
    $result = db2_set_option($stmt, $options, 1);

    /* Verifica si todas las opciones pueden ser establecidas correctamente */
    if($result)
    {
      echo 'Opciones establecidas correctamente';
    }
    else
    {
      echo 'No se pueden establecer las opciones';
    }
    ?>

El ejemplo anterior mostrará:

    No se pueden establecer las opciones

Ejemplo #7 Todo junto

    <?php
    /* Parámetros de Conexión */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Cadenas de Conexión */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Obtención del Recurso de Conexión */
    $conn = db2_connect($conn_string, '', '');

    /* Crea el array asociativo de opciones con pares clave-valor válidos */
    $options = array('db2_attr_case' => DB2_CASE_LOWER,
    'cursor' => DB2_SCROLLABLE);

    $stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE WHERE EMPNO = ? OR EMPNO = ?');

    /* Llamada a la función utilizando el tipo correcto de recurso, el array
    * de opciones y el valor type */
    $option_result = db2_set_option($stmt, $options, 2);
    $result = db2_execute($stmt, array('000130', '000140'));

    /* Obtiene la fila 2 antes que la fila 1 ya que tenemos un cursor flotante */
    print_r(db2_fetch_assoc($stmt, 2));
    print '<br /><br />';
    print_r(db2_fetch_assoc($stmt, 1));

    ?>

El ejemplo anterior mostrará:

    Array
    (
         [empno] => 000140
         [firstnme] => HEATHER
         [midinit] => A
         [lastname] => NICHOLLS
         [workdept] => C01
         [phoneno] => 1793
         [hiredate] => 1976-12-15
         [job] => ANALYST
         [edlevel] => 18
         [sex] => F
         [birthdate] => 1946-01-19
         [salary] => 28420.00
         [bonus] => 600.00
         [comm] => 2274.00
    )

    Array
    (
         [empno] => 000130
         [firstnme] => DELORES
         [midinit] => M
         [lastname] => QUINTANA
         [workdept] => C01
         [phoneno] => 4578
         [hiredate] => 1971-07-28
         [job] => ANALYST
         [edlevel] => 16
         [sex] => F
         [birthdate] => 1925-09-15
         [salary] => 23800.00
         [bonus] => 500.00
         [comm] => 1904.00
    )

Ejemplo #8 Los cursores i5/OS son de solo lectura

    <?php
    $conn = db2_connect("", "", "", array("i5_lib"=>"nobody"));
    $stmt = db2_prepare($conn, 'select * from names where first = ?');
    $name = "first2";
    db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
    $options = array("i5_fetch_only"=>DB2_I5_FETCH_ON);
    db2_set_option($stmt,$options,0);
    if (db2_execute($stmt)) {
       while ($row = db2_fetch_array($stmt)) {
          echo "{$row[0]} {$row[1]}";
       }
    }
    ?>

El ejemplo anterior mostrará:

    first2 last2

### Ver también

- db2_connect() - Devuelve una conexión a una base de datos
- db2_pconnect() - Devuelve una conexión persistente a una base de datos
- db2_exec() - Ejecuta una consulta SQL directamente
- db2_prepare() - Prepara una consulta SQL para ser ejecutada
- db2_cursor_type() - Devuelve el tipo de cursor utilizado por un recurso

# db2_special_columns

(PECL ibm_db2 >= 1.0.0)

db2_special_columns — Devuelve un conjunto de resultados que lista los identificadores únicos de las filas de una tabla

### Descripción

function db2_special_columns(
resource `$connection`,
?string `$qualifier`,
string `$schema`,
string `$table_name`,
int `$scope`
): resource

Devuelve un conjunto de resultados que lista los identificadores únicos de las filas de una tabla.

### Parámetros

`connection`
  Una conexión válida a una base de datos IBM DB2, Cloudscape o Apache Derby.
`qualifier`
  Un calificador para las bases de datos DB2 que funcionan en servidores OS/390 o z/OS. Para otras bases de datos, se debe pasar `null` o una cadena vacía.
`schema`
  El esquema que contiene las tablas.
`table_name`
  El nombre de la tabla.
`scope`

  Un entero que representa el tiempo mínimo para el cual el identificador único de la fila es válido. Puede ser uno de los siguientes valores:

  Valor entero | Constante SQL | Descripción
  --- | --- | ---
  0 | SQL_SCOPE_CURROW | El identificador de la fila es válido solo cuando el cursor está posicionado en la fila.
  1 | SQL_SCOPE_TRANSACTION | El identificador de la fila es válido durante la duración de la transacción.
  2 | SQL_SCOPE_SESSION | El identificador de la fila es válido durante la duración de la conexión.

### Valores devueltos

Devuelve un recurso con un conjunto de resultados que contiene filas con información única para una tabla. Las filas están compuestas por las siguientes columnas:

Nombre de la columna | Descripción
--- | ---
SCOPE |
Valor entero | Constante SQL | Descripción
--- | --- | ---
0 | SQL_SCOPE_CURROW | El identificador de la fila es válido solo cuando el cursor está posicionado en la fila.
1 | SQL_SCOPE_TRANSACTION | El identificador de la fila es válido durante la duración de la transacción.
2 | SQL_SCOPE_SESSION | El identificador de la fila es válido durante la duración de la conexión.
COLUMN_NAME | Nombre de la columna única.
DATA_TYPE | El tipo de datos SQL para la columna.
TYPE_NAME | Una cadena que representa el tipo de datos para la columna.
COLUMN_SIZE | Un entero que representa el tamaño de la columna.
BUFFER_LENGTH | Número máximo de bytes necesarios para almacenar datos de esta columna.
DECIMAL_DIGITS | La escala de la columna o `null` donde la escala no es aplicable.
NUM_PREC_RADIX | Un entero que puede ser `10` (representando un tipo de datos numérico exacto), `2` (representando un tipo de datos numéricos aproximados) o `null` (representando un tipo de datos para el cual la base no es aplicable).
PSEUDO_COLUMN | Siempre devuelve 1.

### Ver también

- db2_column_privileges() - Devuelve un conjunto de resultados que lista las columnas y sus privilegios de una tabla
- db2_columns() - Devuelve un conjunto de resultados que lista las columnas y sus metadatos de una tabla
- db2_foreign_keys() - Devuelve un conjunto de resultados que lista las claves externas de una tabla
- db2_primary_keys() - Devuelve un conjunto de resultados que lista las claves de una tabla
- db2_procedure_columns() - Devuelve un conjunto de resultados que lista los argumentos de procedimiento de registro
- db2_procedures() - Devuelve un conjunto de resultados que lista las proceduras de registro almacenadas en la base de datos
- db2_statistics() - Devuelve un conjunto de resultados que enumera los índices y estadísticas de una tabla
- db2_table_privileges() - Devuelve un conjunto de resultados que lista las tablas y sus privilegios asociados en una base de datos
- db2_tables() - Devuelve la lista de tablas y sus metadatos

# db2_statistics

(PECL ibm_db2 >= 1.0.0)

db2_statistics — Devuelve un conjunto de resultados que enumera los índices y estadísticas de una tabla

### Descripción

function db2_statistics(
resource `$connection`,
?string `$qualifier`,
?string `$schema`,
string `$table_name`,
bool `$unique`
): resource

Devuelve un conjunto de resultados que enumera los índices y estadísticas de una tabla.

### Parámetros

`connection`
  Una conexión válida a una base de datos IBM DB2, Cloudscape o Apache Derby.
`qualifier`
  Un calificador para las bases de datos DB2 que funcionan en servidores OS/390 o z/OS. Para otras bases de datos, se debe pasar `null` o una string vacía.
`schema`
  El esquema que contiene las tablas objetivo. Si el argumento es `null`, se devuelven las estadísticas y los índices para el esquema del usuario actual.
`table_name`
  El nombre de la tabla.
`unique`
  Cuando `unique` es `true`, se devuelve la información relativa a todos los índices de la tabla. De lo contrario, solo se devuelve la información relativa a los índices únicos de la tabla.

### Valores devueltos

Devuelve un recurso de sentencia con un conjunto de resultados que contiene filas que describen las estadísticas e índices para las tablas base que coinciden con los parámetros especificados. Las filas están compuestas por las columnas siguientes:

Nombre de la columna | Descripción
--- | ---
TABLE_CAT | Nombre del catálogo que contiene la tabla. El valor es `null` si la tabla no tiene catálogo.
TABLE_SCHEM | Nombre del esquema que contiene la tabla.
TABLE_NAME | Nombre de la tabla.
NON_UNIQUE | Un integer que representa si el índice prohíbe valores únicos o si la fila contiene estadísticas sobre la tabla misma:
Valor de retorno | Tipo de argumento
--- | ---
0 (SQL_FALSE) | El índice permite valores duplicados.
1 (SQL_TRUE) | Los valores del índice deben ser únicos.
`null` | La fila contiene información estadística sobre la tabla.
INDEX_QUALIFIER | Una string que representa un calificador que debería haber sido previamente fijado a INDEX_NAME para calificar completamente el índice.
INDEX_NAME | Una string que representa el nombre del índice.
TYPE | Un integer que representa el tipo de información contenida en esta fila del conjunto de resultados:
Valor de retorno | Tipo de argumento
--- | ---
0 (SQL_TABLE_STAT) | La fila contiene información estadística sobre la tabla.
1 (SQL_INDEX_CLUSTERED) | La fila contiene información sobre un índice agrupado.
2 (SQL_INDEX_HASH) | La fila contiene información sobre un índice hash.
3 (SQL_INDEX_OTHER) | La fila contiene información sobre un tipo de índice que no es agrupado ni hash.
ORDINAL_POSITION | Un array que comienza en el índice 1 indicando la columna en el índice. `null` si la fila contiene información estadística sobre la tabla.
COLUMN_NAME | El nombre de la columna en el índice. `null` si la fila contiene información estadística sobre la tabla.
ASC_OR_DESC | `A` si la columna está ordenada en orden alfabético, `D` si la columna está ordenada en orden alfabético inverso, `null` si la fila contiene información estadística sobre la tabla.
CARDINALITY | Si la fila contiene información sobre un índice, esta columna contendrá un integer que representa el número de valores únicos en el índice. Si la fila contiene información sobre la tabla, esta columna contendrá un integer que representa el número de filas en la tabla.
PAGES | Si la fila contiene información sobre un índice, esta columna contendrá un integer que representa el número de páginas utilizadas para registrar el índice. Si la fila contiene información sobre la tabla, esta columna contendrá un integer que representa el número de páginas utilizadas para registrar la tabla.
FILTER_CONDITION | Siempre devuelve `null`.

### Ver también

- db2_column_privileges() - Devuelve un conjunto de resultados que lista las columnas y sus privilegios de una tabla
- db2_columns() - Devuelve un conjunto de resultados que lista las columnas y sus metadatos de una tabla
- db2_foreign_keys() - Devuelve un conjunto de resultados que lista las claves externas de una tabla
- db2_primary_keys() - Devuelve un conjunto de resultados que lista las claves de una tabla
- db2_procedure_columns() - Devuelve un conjunto de resultados que lista los argumentos de procedimiento de registro
- db2_procedures() - Devuelve un conjunto de resultados que lista las proceduras de registro almacenadas en la base de datos
- db2_special_columns() - Devuelve un conjunto de resultados que lista los identificadores únicos de las filas de una tabla
- db2_table_privileges() - Devuelve un conjunto de resultados que lista las tablas y sus privilegios asociados en una base de datos
- db2_tables() - Devuelve la lista de tablas y sus metadatos

# db2_stmt_error

(PECL ibm_db2 >= 1.0.0)

db2_stmt_error — Devuelve un string que contiene el valor de SQLSTATE retornado por una consulta SQL

### Descripción

function db2_stmt_error(?resource `$stmt` = `null`): string

Devuelve un string que contiene el valor de SQLSTATE retornado por una consulta SQL.

Si no se pasa un recurso como argumento a la función db2_stmt_error(), esta retornará el mensaje de error asociado con el último intento de retorno de una consulta SQL, por ejemplo, proveniente de db2_prepare() o db2_exec().

Para comprender los valores de SQLSTATE, se puede ingresar el siguiente comando en el procesador de línea de comandos de DB2: `db2 '? `sqlstate-value`'`. Asimismo, se puede llamar a la función db2_conn_errormsg() para obtener un mensaje de error explícito junto con el valor de SQLCODE asociado.

### Parámetros

`stmt`
  Un recurso válido.

### Valores devueltos

Devuelve un string que contiene el valor de SQLSTATE.

### Ver también

- db2_conn_error() - Devuelve un string que contiene el valor de SQLSTATE devuelto por el último intento de conexión
- db2_conn_errormsg() - Devuelve el último mensaje de error de conexión junto con el valor de SQLCODE
- db2_stmt_errormsg() - Devuelve el último mensaje de error de una consulta SQL

# db2_stmt_errormsg

(PECL ibm_db2 >= 1.0.0)

db2_stmt_errormsg — Devuelve el último mensaje de error de una consulta SQL

### Descripción

function db2_stmt_errormsg(?resource `$stmt` = `null`): string

Devuelve el último mensaje de error de una consulta SQL.

Si no se pasa un recurso como argumento a la función db2_stmt_errormsg(), devolverá el mensaje de error asociado con el último intento de retorno de una consulta SQL, por ejemplo, proveniente de db2_prepare() o db2_exec().

### Parámetros

`stmt`
  Un recurso válido.

### Valores devueltos

Devuelve un string que contiene el error del mensaje y el SQLCODE para el último error que se produjo tras la ejecución de una consulta SQL.

### Ver también

- db2_conn_error() - Devuelve un string que contiene el valor de SQLSTATE devuelto por el último intento de conexión
- db2_conn_errormsg() - Devuelve el último mensaje de error de conexión junto con el valor de SQLCODE
- db2_stmt_error() - Devuelve un string que contiene el valor de SQLSTATE retornado por una consulta SQL

# db2_table_privileges

(PECL ibm_db2 >= 1.0.0)

db2_table_privileges — Devuelve un conjunto de resultados que lista las tablas y sus privilegios asociados en una base de datos

### Descripción

function db2_table_privileges(
resource `$connection`,
?string `$qualifier` = `null`,
?string `$schema` = `null`,
?string `$table_name` = `null`
): resource

Devuelve un conjunto de resultados que lista las tablas y sus privilegios asociados en una base de datos.

### Parámetros

`connection`
  Una conexión válida a una base de datos IBM DB2, Cloudscape o Apache Derby.
`qualifier`
  Un calificador para las bases de datos DB2 que funcionan en servidores OS/390 o z/OS. Para otras bases de datos, se debe pasar `null` o una cadena vacía.
`schema`
  El esquema que contiene las tablas. El argumento acepta formas que contienen `_` y `%` como comodines.
`table-name`
  El nombre de la tabla. El argumento acepta formas que contienen `_` y `%` como comodines.

### Valores devueltos

Devuelve un recurso con el conjunto de resultados que contiene las filas que describen los privilegios para las tablas que coinciden con los argumentos especificados. Las filas están compuestas por las siguientes columnas:

Nombre de la columna | Descripción
--- | ---
TABLE_CAT | Nombre del catálogo que contiene la tabla. El valor es `null` si la tabla no tiene catálogo.
TABLE_SCHEM | Nombre del esquema que contiene la tabla.
TABLE_NAME | Nombre de la tabla.
GRANTOR | ID de autorización del usuario que otorgó el privilegio.
GRANTEE | ID de autorización del usuario al que se otorgó el privilegio.
PRIVILEGE | El privilegio que se otorgó. Puede ser uno de los siguientes: ALTER, CONTROL, DELETE, INDEX, INSERT, REFERENCES, SELECT o UPDATE.
IS_GRANTABLE | Una cadena que contiene "YES" o "NO" que indica si el usuario al que se otorgó el privilegio puede otorgar el privilegio a otros usuarios.

### Ver también

- db2_column_privileges() - Devuelve un conjunto de resultados que lista las columnas y sus privilegios de una tabla
- db2_columns() - Devuelve un conjunto de resultados que lista las columnas y sus metadatos de una tabla
- db2_foreign_keys() - Devuelve un conjunto de resultados que lista las claves externas de una tabla
- db2_primary_keys() - Devuelve un conjunto de resultados que lista las claves de una tabla
- db2_procedure_columns() - Devuelve un conjunto de resultados que lista los argumentos de procedimiento de registro
- db2_procedures() - Devuelve un conjunto de resultados que lista las proceduras de registro almacenadas en la base de datos
- db2_special_columns() - Devuelve un conjunto de resultados que lista los identificadores únicos de las filas de una tabla
- db2_statistics() - Devuelve un conjunto de resultados que enumera los índices y estadísticas de una tabla
- db2_tables() - Devuelve la lista de tablas y sus metadatos

# db2_tables

(PECL ibm_db2 >= 1.0.0)

db2_tables — Devuelve la lista de tablas y sus metadatos

### Descripción

function db2_tables(
resource `$connection`,
?string `$qualifier` = `null`,
?string `$schema` = `null`,
?string `$table_name` = `null`,
?string `$table_type` = `null`
): resource

Devuelve un conjunto de resultados que lista las tablas y sus metadatos asociados de una base de datos.

### Parámetros

`connection`
  Una conexión válida a una base de datos IBM DB2, Cloudscape o Apache Derby.
`qualifier`
  Un calificador para las bases de datos DB2 que funcionan en servidores OS/390 o z/OS. Para otras bases de datos, se debe pasar `null` o una cadena vacía.
`schema`
  El esquema que contiene las tablas. El argumento acepta formas que contienen `_` y `%` como comodines.
`table_name`
  El nombre de la tabla. El argumento acepta formas que contienen `_` y `%` como comodines.
`table_type`
  Una lista de identificadores de tipos de tabla delimitada por comas. Para coincidir con todos los esquemas, se debe pasar `null` o una cadena vacía. Los identificadores válidos son: ALIAS, HIERARCHY TABLE, INOPERATIVE VIEW, NICKNAME, MATERIALIZED QUERY TABLE, SYSTEM TABLE, TABLE, TYPED TABLE, TYPED VIEW y VIEW.

### Valores devueltos

Devuelve un recurso con el conjunto de resultados que contiene las filas que describen las tablas que coinciden con los argumentos especificados. Las filas están compuestas por las siguientes columnas:

Nombre de la columna | Descripción
--- | ---
TABLE_CAT | Nombre del catálogo que contiene la tabla. El valor es `null` si la tabla no tiene catálogo.
TABLE_SCHEM | Nombre del esquema que contiene la tabla.
TABLE_NAME | Nombre de la tabla.
TABLE_TYPE | Identificador de la tabla.
REMARKS | Descripción de la tabla.

### Ver también

- db2_column_privileges() - Devuelve un conjunto de resultados que lista las columnas y sus privilegios de una tabla
- db2_columns() - Devuelve un conjunto de resultados que lista las columnas y sus metadatos de una tabla
- db2_foreign_keys() - Devuelve un conjunto de resultados que lista las claves externas de una tabla
- db2_primary_keys() - Devuelve un conjunto de resultados que lista las claves de una tabla
- db2_procedure_columns() - Devuelve un conjunto de resultados que lista los argumentos de procedimiento de registro
- db2_procedures() - Devuelve un conjunto de resultados que lista las proceduras de registro almacenadas en la base de datos
- db2_special_columns() - Devuelve un conjunto de resultados que lista los identificadores únicos de las filas de una tabla
- db2_statistics() - Devuelve un conjunto de resultados que enumera los índices y estadísticas de una tabla
- db2_table_privileges() - Devuelve un conjunto de resultados que lista las tablas y sus privilegios asociados en una base de datos

## Tabla de contenidos

- db2_autocommit — Devuelve o modifica el estado AUTOCOMMIT de la conexión a la base de datos
- db2_bind_param — Asocia una variable PHP a un parámetro de una consulta SQL
- db2_client_info — Devuelve un objeto con propiedades que describen el cliente de base de datos DB2
- db2_close — Cierra una conexión a base de datos
- db2_column_privileges — Devuelve un conjunto de resultados que lista las columnas y sus privilegios de una tabla
- db2_columns — Devuelve un conjunto de resultados que lista las columnas y sus metadatos de una tabla
- db2_commit — Confirmar una transacción
- db2_conn_error — Devuelve un string que contiene el valor de SQLSTATE devuelto por el último intento de conexión
- db2_conn_errormsg — Devuelve el último mensaje de error de conexión junto con el valor de SQLCODE
- db2_connect — Devuelve una conexión a una base de datos
- db2_cursor_type — Devuelve el tipo de cursor utilizado por un recurso
- db2_escape_string — Escapar ciertos caracteres especiales
- db2_exec — Ejecuta una consulta SQL directamente
- db2_execute — Ejecuta una consulta SQL preparada
- db2_fetch_array — Devuelve un array, indexado por la posición de las columnas, que representa una línea del conjunto de resultados
- db2_fetch_assoc — Devuelve un array, indexado por nombre de columna, que representa una fila del conjunto de resultados
- db2_fetch_both — Devuelve un array, indexado por nombre de columna y posición, que representa una fila del conjunto de resultados
- db2_fetch_object — Devuelve un objeto con las propiedades que representan columnas en la fila extraída
- db2_fetch_row — Modifica el puntero del conjunto de resultados a la siguiente línea o a la línea solicitada
- db2_field_display_size — Devuelve el máximo de octetos requeridos para mostrar una columna
- db2_field_name — Devuelve el nombre de la columna del conjunto de resultados
- db2_field_num — Devuelve la posición del nombre de la columna del conjunto de resultados
- db2_field_precision — Devuelve la precisión de la columna indicada del conjunto de resultados
- db2_field_scale — Devuelve la escala de la columna indicada del conjunto de resultados
- db2_field_type — Devuelve el tipo de dato de la columna indicada del conjunto de resultados
- db2_field_width — Devuelve el ancho de la columna indicada en el conjunto de resultados
- db2_foreign_keys — Devuelve un conjunto de resultados que lista las claves externas de una tabla
- db2_free_result — Liberar los recursos asociados con un resultado
- db2_free_stmt — Liberar un recurso indicado
- db2_get_option — Recupera el valor de una opción para una consulta o conexión
- db2_last_insert_id — Retorna el último ID generado por la última consulta de inserción
- db2_lob_read — Recupera grandes objetos binarios de tamaños predefinidos en cada invocación
- db2_next_result — Solicita el siguiente conjunto de resultados de la recurso indicado
- db2_num_fields — Devuelve el número de campos contenido en el conjunto de resultados
- db2_num_rows — Devuelve el número de filas afectadas por una consulta SQL
- db2_pclose — Cierra una conexión persistente a la base de datos
- db2_pconnect — Devuelve una conexión persistente a una base de datos
- db2_prepare — Prepara una consulta SQL para ser ejecutada
- db2_primary_keys — Devuelve un conjunto de resultados que lista las claves de una tabla
- db2_procedure_columns — Devuelve un conjunto de resultados que lista los argumentos de procedimiento de registro
- db2_procedures — Devuelve un conjunto de resultados que lista las proceduras de registro almacenadas en la base de datos
- db2_result — Devuelve un valor de una columna de una fila de un conjunto de resultados
- db2_rollback — Cancelar una transacción
- db2_server_info — Devuelve un objeto con propiedades que describen el servidor de base de datos DB2
- db2_set_option — Establece opciones para una conexión o recursos
- db2_special_columns — Devuelve un conjunto de resultados que lista los identificadores únicos de las filas de una tabla
- db2_statistics — Devuelve un conjunto de resultados que enumera los índices y estadísticas de una tabla
- db2_stmt_error — Devuelve un string que contiene el valor de SQLSTATE retornado por una consulta SQL
- db2_stmt_errormsg — Devuelve el último mensaje de error de una consulta SQL
- db2_table_privileges — Devuelve un conjunto de resultados que lista las tablas y sus privilegios asociados en una base de datos
- db2_tables — Devuelve la lista de tablas y sus metadatos

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
  - Tipos de recursos
- Constantes predefinidas
- Funciones de IBM DB2
  - db2_autocommit — Devuelve o modifica el estado AUTOCOMMIT de la conexión a la base de datos
  - db2_bind_param — Asocia una variable PHP a un parámetro de una consulta SQL
  - db2_client_info — Devuelve un objeto con propiedades que describen el cliente de base de datos DB2
  - db2_close — Cierra una conexión a base de datos
  - db2_column_privileges — Devuelve un conjunto de resultados que lista las columnas y sus privilegios de una tabla
  - db2_columns — Devuelve un conjunto de resultados que lista las columnas y sus metadatos de una tabla
  - db2_commit — Confirmar una transacción
  - db2_conn_error — Devuelve un string que contiene el valor de SQLSTATE devuelto por el último intento de conexión
  - db2_conn_errormsg — Devuelve el último mensaje de error de conexión junto con el valor de SQLCODE
  - db2_connect — Devuelve una conexión a una base de datos
  - db2_cursor_type — Devuelve el tipo de cursor utilizado por un recurso
  - db2_escape_string — Escapar ciertos caracteres especiales
  - db2_exec — Ejecuta una consulta SQL directamente
  - db2_execute — Ejecuta una consulta SQL preparada
  - db2_fetch_array — Devuelve un array, indexado por la posición de las columnas, que representa una línea del conjunto de resultados
  - db2_fetch_assoc — Devuelve un array, indexado por nombre de columna, que representa una fila del conjunto de resultados
  - db2_fetch_both — Devuelve un array, indexado por nombre de columna y posición, que representa una fila del conjunto de resultados
  - db2_fetch_object — Devuelve un objeto con las propiedades que representan columnas en la fila extraída
  - db2_fetch_row — Modifica el puntero del conjunto de resultados a la siguiente línea o a la línea solicitada
  - db2_field_display_size — Devuelve el máximo de octetos requeridos para mostrar una columna
  - db2_field_name — Devuelve el nombre de la columna del conjunto de resultados
  - db2_field_num — Devuelve la posición del nombre de la columna del conjunto de resultados
  - db2_field_precision — Devuelve la precisión de la columna indicada del conjunto de resultados
  - db2_field_scale — Devuelve la escala de la columna indicada del conjunto de resultados
  - db2_field_type — Devuelve el tipo de dato de la columna indicada del conjunto de resultados
  - db2_field_width — Devuelve el ancho de la columna indicada en el conjunto de resultados
  - db2_foreign_keys — Devuelve un conjunto de resultados que lista las claves externas de una tabla
  - db2_free_result — Liberar los recursos asociados con un resultado
  - db2_free_stmt — Liberar un recurso indicado
  - db2_get_option — Recupera el valor de una opción para una consulta o conexión
  - db2_last_insert_id — Retorna el último ID generado por la última consulta de inserción
  - db2_lob_read — Recupera grandes objetos binarios de tamaños predefinidos en cada invocación
  - db2_next_result — Solicita el siguiente conjunto de resultados de la recurso indicado
  - db2_num_fields — Devuelve el número de campos contenido en el conjunto de resultados
  - db2_num_rows — Devuelve el número de filas afectadas por una consulta SQL
  - db2_pclose — Cierra una conexión persistente a la base de datos
  - db2_pconnect — Devuelve una conexión persistente a una base de datos
  - db2_prepare — Prepara una consulta SQL para ser ejecutada
  - db2_primary_keys — Devuelve un conjunto de resultados que lista las claves de una tabla
  - db2_procedure_columns — Devuelve un conjunto de resultados que lista los argumentos de procedimiento de registro
  - db2_procedures — Devuelve un conjunto de resultados que lista las proceduras de registro almacenadas en la base de datos
  - db2_result — Devuelve un valor de una columna de una fila de un conjunto de resultados
  - db2_rollback — Cancelar una transacción
  - db2_server_info — Devuelve un objeto con propiedades que describen el servidor de base de datos DB2
  - db2_set_option — Establece opciones para una conexión o recursos
  - db2_special_columns — Devuelve un conjunto de resultados que lista los identificadores únicos de las filas de una tabla
  - db2_statistics — Devuelve un conjunto de resultados que enumera los índices y estadísticas de una tabla
  - db2_stmt_error — Devuelve un string que contiene el valor de SQLSTATE retornado por una consulta SQL
  - db2_stmt_errormsg — Devuelve el último mensaje de error de una consulta SQL
  - db2_table_privileges — Devuelve un conjunto de resultados que lista las tablas y sus privilegios asociados en una base de datos
  - db2_tables — Devuelve la lista de tablas y sus metadatos

# La extensión MongoDB

Esta extensión se desarrolla sobre las bibliotecas » libmongoc y » libbson. Proporciona una API mínima para las funcionalidades básicas del controlador: comandos, consultas, escrituras, gestión de conexión, y serialización BSON.

Las bibliotecas PHP del lado del usuario que dependen de esta extensión pueden proporcionar API de nivel más alto, tales como constructores de consultas, métodos de ayuda para comandos individuales, y GridFS. Los desarrolladores de aplicaciones deberían considerar utilizar esta extensión en conjunción con la » biblioteca MongoDB PHP, que implementa las mismas API de nivel más alto que se encuentran en los controladores MongoDB para otros lenguajes. Esta separación de preocupaciones permite a la extensión concentrarse en las funcionalidades esenciales para las cuales una implementación de extensión es primordial para el rendimiento.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución

## Requerimientos

A partir de la versión 1.21.0, la extensión requiere PHP 8.1 o superior. Las versiones anteriores de la extensión permiten la compatibilidad con versiones más antiguas de PHP.

La extensión requiere » libbson y » libmongoc, y usará por omisión las versiones incluidas de ambas bibliotecas. También se pueden usar bibliotecas del sistema, como se explica en la documentación de instalación manual.

La extensión, a través de libmongoc, depende opcionalmente de una biblioteca TLS (por ejemplo, OpenSSL) y la usará si está disponible. Si el proceso de compilación no logra encontrar una biblioteca TLS, los usuarios deben verificar que el paquete de desarrollo apropiado (por ejemplo, `libssl-dev`) y » pkg-config estén instalados. El proceso para detectar y configurar bibliotecas TLS se explica con más detalle en la documentación de instalación manual.

» Cyrus SASL es una dependencia opcional para admitir la autenticación Kerberos y se usará si está disponible.

> Nota: Debido a posibles problemas para representar enteros de 64 bits en plataformas de 32 bits, se recomienda a los usuarios emplear entornos de 64 bits. Al usar una plataforma de 32 bits, tenga en cuenta que cualquier entero de 64 bits leído desde la base de datos se devolverá como una instancia de MongoDB\BSON\Int64 en lugar de un tipo entero de PHP.

## Instalación

## Instalación de la extensión MongoDB PHP con PIE

> Nota: El instalador de Extensiones para PHP (PHP Installer for Extensions - PIE) es una nueva herramienta que reemplazará PECL. Recomendamos usar PIE para instalar extensiones. Más información en » https://github.com/php/pie

Para instalar la extensión MongoDB usando PIE, ejecute el siguiente comando:

    pie install mongodb/mongodb-extension

## Instalación de la extensión MongoDB PHP con PECL

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/mongodb

Los usuarios de Linux, Unix y macOS pueden ejecutar el siguiente comando para instalar la extensión:

    $ sudo pecl install mongodb

En sistemas con múltiples versiones de PHP instaladas (por ejemplo, la versión predeterminada de macOS, Homebrew, » XAMPP), cada versión de PHP tendrá su propio comando pecl y archivo(s) php.ini. Además, cada entorno de PHP (por ejemplo, CLI, web) puede usar archivos php.ini separados.

A partir de la versión 1.17.0 de la extensión, PECL solicitará varias opciones de `configure`. Para instalar la extensión con las opciones predeterminadas en un script no interactivo, se puede enviar una entrada de cadena vacía a `pecl install` usando el comando `yes`:

    $ yes '' | sudo pecl install mongodb

Se puede encontrar una lista completa de las opciones de `configure` admitidas en el archivo `package.xml` incluido en el paquete PECL. Para instalar la extensión con opciones específicas de `configure` en un script no interactivo, se puede usar la opción `--configureoptions` para `pecl install`:

    $ sudo pecl install --configureoptions='with-mongodb-system-libs="yes" enable-mongodb-developer-flags="no"' mongodb

Por omisión, instalar la extensión mediante PECL usará versiones integradas de » libbson, » libmongoc y » libmongocrypt e intentará configurarlas automáticamente.

> Nota: Si el proceso de compilación no logra encontrar una biblioteca SSL, verifique que los paquetes de desarrollo (por ejemplo, `libssl-dev`) y » pkg-config estén ambos instalados. Si esto no resuelve el problema, considere usar el proceso de instalación manual.

Finalmente, agregue la siguiente línea al archivo php.ini para cada entorno que necesite usar la extensión:

    extension=mongodb.so

## Instalación de la extensión MongoDB PHP en macOS con Homebrew

» Homebrew 1.5.0 dejó de dar soporte al » Homebrew/php tap y eliminó las fórmulas para extensiones individuales de PHP. A partir de ahora, los usuarios de macOS deben instalar la fórmula » php y seguir las instrucciones estándar de instalación con PECL usando el comando pecl proporcionado por la instalación de PHP de Homebrew.

Alternativamente, el » repositorio shivammathur/extensions proporciona fórmulas para extensiones individuales de PHP. Por ejemplo, para instalar la extensión para PHP 8.4, ejecute:

    $ brew install shivammathur/extensions/mongodb@8.4

Tenga en cuenta que solo está disponible la versión más reciente de la extensión en brew.

> Nota: Instalar las dependencias requeridas
> Para garantizar que el soporte SSL pueda configurarse correctamente, asegúrese de que las fórmulas `openssl` y `pkgconf` estén instaladas. Si falta alguno de estos paquetes, la extensión se compilará con Secure Transport, lo que puede generar problemas de compatibilidad.

## Instalación de la extensión MongoDB PHP en Windows

Se adjuntan binarios precompilados a los » lanzamientos del proyecto en Github. Se publican archivos para varias combinaciones de versión de PHP, seguridad de subprocesos (TS o NTS) y arquitectura (x86 o x64). Determine el archivo correcto para el entorno de PHP y extraiga el archivo php_mongodb.dll al directorio de extensiones ("ext" por omisión).

Agregue la siguiente línea al archivo php.ini para cada entorno que necesite usar la extensión:

    extension=php_mongodb.dll

Si no selecciona el binario correcto, se producirá un error al intentar cargar la DLL de la extensión en tiempo de ejecución:

    PHP Warning:  PHP Startup: Unable to load dynamic library 'mongodb'

Asegúrese de que la DLL descargada corresponda a las siguientes propiedades del entorno de ejecución de PHP:

- Versión de PHP (`PHP_VERSION`)
- Seguridad de subprocesos (`PHP_ZTS`)
- Arquitectura (`PHP_INT_SIZE`)

Además de las constantes mencionadas anteriormente, estas propiedades también pueden inferirse desde la función phpinfo(). Si un sistema tiene múltiples entornos de ejecución de PHP instalados, verifique que la salida de phpinfo() corresponda al entorno correcto.

> Nota: Dependencias adicionales de DLL para usuarios de Windows
> Para hacer funcionar esta extensión, algunas bibliotecas DLL deben estar disponibles a través del PATH del sistema Windows. Lea la F.A.Q titulada "Cómo agregar mi carpeta PHP a mi PATH de Windows" para más información. Copiar las bibliotecas DLL desde la carpeta PHP a la carpeta del sistema de Windows también funciona (ya que la carpeta del sistema está por defecto en el PATH del sistema), pero este método no es recomendado. Esta extensión requiere que los siguientes archivos estén en el PATH: libsasl.dll

## Compilación del controlador MongoDB PHP desde el código fuente

Para desarrolladores y usuarios interesados en las correcciones más recientes de errores, la extensión puede compilarse desde el código fuente más reciente en » Github. Ejecute los siguientes comandos para clonar y compilar el proyecto:

    $ git clone https://github.com/mongodb/mongo-php-driver.git
    $ cd mongo-php-driver
    $ git submodule update --init
    $ phpize
    $ ./configure
    $ make all
    $ sudo make install

En sistemas con múltiples versiones de PHP instaladas (por ejemplo, la versión predeterminada de macOS, Homebrew, » XAMPP), cada versión de PHP tendrá su propio comando phpize y archivo(s) php.ini. Además, cada entorno de PHP (por ejemplo, CLI, web) puede usar archivos php.ini separados.

Por omisión, la extensión usará versiones integradas de » libbson, » libmongoc y » libmongocrypt e intentará configurarlas automáticamente. Si estas bibliotecas ya están instaladas como bibliotecas del sistema, la extensión puede utilizarlas especificando `--with-mongodb-system-libs=yes` como opción para `configure`.

Para obtener una lista completa de las opciones de `configure`, ejecute configure --help.

Al usar versiones integradas de libmongoc y libmongocrypt, la extensión también intentará seleccionar una biblioteca SSL según la opción `--with-mongodb-ssl` de `configure`. A partir de la versión 1.17.0 de la extensión, OpenSSL siempre se prefiere por omisión. Anteriormente, Secure Transport era la opción predeterminada en macOS y OpenSSL era la opción predeterminada en todas las demás plataformas.

> Nota: Si el proceso de compilación no logra encontrar una biblioteca SSL, verifique que los paquetes de desarrollo (por ejemplo, `libssl-dev`) y » pkg-config estén ambos instalados. Al usar Homebrew en macOS, es común que un sistema tenga instaladas múltiples versiones de OpenSSL. Para garantizar que se seleccione la versión deseada de OpenSSL, se puede usar la variable de entorno `PKG_CONFIG_PATH` para controlar la ruta de búsqueda de `pkg-config`.

El paso final de compilación, make install, informará dónde se ha instalado mongodb.so, similar a:

    Installing shared extensions:     /usr/lib/php/extensions/debug-non-zts-20220829/

Asegúrese de que la opción extension_dir en php.ini apunte al directorio donde se instaló mongodb.so. La opción puede consultarse ejecutando:

    $ php -i | grep extension_dir
      extension_dir => /usr/lib/php/extensions/debug-non-zts-20220829 =>
                       /usr/lib/php/extensions/debug-non-zts-20220829

Si los directorios difieren, cambie extension_dir en php.ini o mueva manualmente mongodb.so al directorio correcto.

Finalmente, agregue la siguiente línea al archivo php.ini para cada entorno que necesite usar la extensión:

    extension=mongodb.so

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

mongodb Opciones de configuración
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
mongodb.debug | "" | `INI_ALL` |

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`mongodb.debug` string
  Esta opción puede usarse para activar o desactivar el registro de depuración a nivel de traza en la extensión (y en libmongoc). Especifique una cadena vacía, `"0"`, `"off"`, `"no"` o `"false"` para desactivar el registro. Especifique `"stderr"` o `"stdout"` para registrar en `stderr` o `stdout`, respectivamente. Especifique `"1"`, `"on"`, `"yes"` o `"true"` para registrar en un nuevo fichero temporal dentro del directorio temporal del sistema por omisión (es decir, sys_get_temp_dir()). Especifique cualquier otra cadena para registrar en un nuevo fichero temporal dentro de ese directorio. Si el directorio no puede usarse, se usará el directorio temporal del sistema por omisión.

  > Nota: Tenga en cuenta que el registro de depuración puede contener información sensible, como credenciales del servidor MongoDB y documentos completos escritos o leídos del servidor. Revise cualquier registro de depuración antes de compartirlos con otras personas.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`MONGODB_VERSION` (string)
  Número de versión estilo x.y.z de la extensión
`MONGODB_STABILITY` (string)
  Estabilidad actual (alpha/beta/stable)

# Tutoriales

## Tabla de contenidos

- Utilizar la biblioteca PHP para MongoDB (PHPLIB)
- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

En esta sección encontrará varios tutoriales sobre cómo utilizar el controlador de MongoDB para PHP.

## Utilizar la biblioteca PHP para MongoDB (PHPLIB)

Después de la configuración inicial de la extensión, se continuará explicando cómo comenzar con la biblioteca de usuario correspondiente para escribir nuestro primer proyecto.

## Instalar la biblioteca PHP con Composer

La última cosa que se debe instalar para comenzar la aplicación en sí es la biblioteca PHP.

La biblioteca debe ser instalada con » Composer, un gestor de paquetes para PHP. Las instrucciones para instalar Composer en diferentes plataformas pueden encontrarse en su sitio web.

Instalar la biblioteca ejecutando:

    $ composer require mongodb/mongodb

Esto producirá una salida similar a:

    ./composer.json has been created
    Loading composer repositories with package information
    Updating dependencies (including require-dev)
      - Installing mongodb/mongodb (1.0.0)
        Downloading: 100%

    Writing lock file
    Generating autoload files

Composer creará varios ficheros: `composer.json`, `composer.lock`, y un directorio `vendor` que contendrá la biblioteca y todas las otras dependencias que su proyecto podría necesitar.

## Utilizar la biblioteca PHP

Además de gestionar sus dependencias, Composer también le proporcionará un autocargador (para las clases de estas dependencias). Asegúrese de que esté incluido al inicio de su script o en el código de arranque de su aplicación:

    <?php
    // Esta ruta debe apuntar al autocargador de Composer
    require 'vendor/autoload.php';

Con esto hecho, ahora puede utilizar cualquier funcionalidad como se describe en la » documentación de la biblioteca.

Si ha utilizado controladores MongoDB en otros lenguajes, la API de la biblioteca debería resultarle familiar. Contiene una clase » Client para conectarse a MongoDB, una clase » Database para las operaciones a nivel de la base de datos (por ejemplo, los comandos, la gestión de las colecciones), y una clase » Collection para las operaciones a nivel de la colección (por ejemplo, los métodos » CRUD, la gestión de los índices).

Como ejemplo, aquí se muestra cómo insertar un documento en la colección beers de la base de datos demo:

    <?php
    require 'vendor/autoload.php'; // incluir el autocargador de Composer

    $client = new MongoDB\Client("mongodb://localhost:27017");
    $collection = $client->demo->beers;

    $result = $collection->insertOne( [ 'name' => 'Hinterland', 'brewery' => 'BrewDog' ] );

    echo "Inserted with Object ID '{$result->getInsertedId()}'";
    ?>

Dado que el documento insertado no contenía un campo `_id`, la extensión generará un MongoDB\BSON\ObjectId para que el servidor lo utilice como `_id`. Este valor también está disponible para el llamador a través del objeto de resultado devuelto por el método `insertOne`.

Después de la inserción, se pueden consultar los datos que acaba de insertar. Para ello, se utiliza el método `find`, que devuelve un cursor iterable:

    <?php
    require 'vendor/autoload.php'; // incluir el autocargador de Composer

    $client = new MongoDB\Client("mongodb://localhost:27017");
    $collection = $client->demo->beers;

    $result = $collection->find( [ 'name' => 'Hinterland', 'brewery' => 'BrewDog' ] );

    foreach ($result as $entry) {
        echo $entry['_id'], ': ', $entry['name'], "\n";
    }
    ?>

Aunque los ejemplos no lo muestran, los documentos BSON y los arrays son deserializados como clases especiales en la biblioteca por defecto. Estas clases extienden ArrayObject para facilidad de uso e implementan las interfaces MongoDB\BSON\Serializable y MongoDB\BSON\Unserializable de la extensión para garantizar que los valores conserven su tipo cuando se serializan nuevamente en BSON. Esto evita un inconveniente de la antigua extensión `mongo` donde los arrays podrían convertirse en documentos, y viceversa. Ver la especificación Persistir datos para más información sobre cómo se convierten los valores entre PHP y BSON.

## Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

La extensión contiene una API de observaciones de eventos, que permite a las aplicaciones monitorear las órdenes y las actividades internas relacionadas con la » Especificación de descubrimiento y monitoreo del servidor. Este tutorial demostrará el monitoreo de las órdenes utilizando la interfaz MongoDB\Driver\Monitoring\CommandSubscriber.

La interfaz MongoDB\Driver\Monitoring\CommandSubscriber define tres métodos: `commandStarted`, `commandSucceeded`, y `commandFailed`. Cada uno de estos tres métodos acepta un solo argumento `event` de una clase específica para el evento respectivo. Por ejemplo, el argumento `$event` de `commandSucceeded` es un objeto MongoDB\Driver\Monitoring\CommandSucceededEvent.

En este tutorial, se implementará un observador que crea una lista de todos los perfiles de solicitud y el tiempo promedio que han tomado.

## Estructura de las clases de observaciones

Se comienza con el marco del observador:

    <?php

    class QueryTimeCollector implements \MongoDB\Driver\Monitoring\CommandSubscriber
    {
        public function commandStarted( \MongoDB\Driver\Monitoring\CommandStartedEvent $event ): void
        {
        }

        public function commandSucceeded( \MongoDB\Driver\Monitoring\CommandSucceededEvent $event ): void
        {
        }

        public function commandFailed( \MongoDB\Driver\Monitoring\CommandFailedEvent $event ): void
        {
        }
    }

    ?>

## Registro del observador

Una vez que un objeto observador es instanciado, debe ser registrado con el sistema de monitoreo de la extensión. Esto se hace llamando a MongoDB\Driver\Monitoring\addSubscriber() o MongoDB\Driver\Manager::addSubscriber() para registrar el observador globalmente o con un Manager específico, respectivamente.

    <?php

    \MongoDB\Driver\Monitoring\addSubscriber( new QueryTimeCollector() );

    ?>

## Implementar la lógica

Con el objeto registrado, la única cosa que queda es implementar la lógica en la clase observadora. Para correlacionar los dos eventos que componen una orden ejecutada con éxito (commandStarted y commandSucceeded), cada objeto de evento expone un campo `requestId`.

Para registrar el tiempo promedio por forma de solicitud, se comenzará verificando una orden `find` en el evento commandStarted. Luego, se añadirá un elemento a la propiedad `pendingCommands` indexado por su `requestId` y con su valor representando la forma de solicitud.

Si se recibe un evento commandSucceeded correspondiente con el mismo `requestId`, se añade la duración del evento (desde `durationMicros`) al tiempo total e incrementa el contador de operaciones.

Si se encuentra un evento commandFailed correspondiente, simplemente se elimina la entrada de la propiedad `pendingCommands`.

    <?php

    class QueryTimeCollector implements \MongoDB\Driver\Monitoring\CommandSubscriber
    {
        private $pendingCommands = [];
        private $queryShapeStats = [];

        /* Crear una forma de solicitud a partir del argumento de filtro. Por ahora, solo se consideran
         * los campos de primer nivel */
        private function createQueryShape( array $filter )
        {
            return json_encode( array_keys( $filter ) );
        }

        public function commandStarted( \MongoDB\Driver\Monitoring\CommandStartedEvent $event ): void
        {
            if ( 'find' === $event->getCommandName() )
            {
                $queryShape = $this->createQueryShape( (array) $event->getCommand()->filter );
                $this->pendingCommands[$event->getRequestId()] = $queryShape;
            }
        }

        public function commandSucceeded( \MongoDB\Driver\Monitoring\CommandSucceededEvent $event ): void
        {
            $requestId = $event->getRequestId();
            if ( array_key_exists( $requestId, $this->pendingCommands ) )
            {
                $this->queryShapeStats[$this->pendingCommands[$requestId]]['count']++;
                $this->queryShapeStats[$this->pendingCommands[$requestId]]['duration'] += $event->getDurationMicros();
                unset( $this->pendingCommands[$requestId] );
            }
        }

        public function commandFailed( \MongoDB\Driver\Monitoring\CommandFailedEvent $event ): void
        {
            if ( array_key_exists( $event->getRequestId(), $this->pendingCommands ) )
            {
                unset( $this->pendingCommands[$event->getRequestId()] );
            }
        }

        public function __destruct()
        {
            foreach( $this->queryShapeStats as $shape => $stats )
            {
                echo "Shape: ", $shape, " (", $stats['count'], ")\n  ",
                    $stats['duration'] / $stats['count'], "µs\n\n";
            }
        }
    }

    $m = new \MongoDB\Driver\Manager( 'mongodb://localhost:27016' );

    /* Añadir el observador */
    \MongoDB\Driver\Monitoring\addSubscriber( new QueryTimeCollector() );

    /* Realizar una serie de solicitudes */
    $query = new \MongoDB\Driver\Query( [
        'region_slug' => 'scotland-highlands', 'age' => [ '$gte' => 20 ]
    ] );
    $cursor = $m->executeQuery( 'dramio.whisky', $query );

    $query = new \MongoDB\Driver\Query( [
        'region_slug' => 'scotland-lowlands', 'age' => [ '$gte' => 15 ]
    ] );
    $cursor = $m->executeQuery( 'dramio.whisky', $query );

    $query = new \MongoDB\Driver\Query( [ 'region_slug' => 'scotland-lowlands' ] );
    $cursor = $m->executeQuery( 'dramio.whisky', $query );

    ?>

# Explicaciones de la arquitectura del controlador y de las funcionalidades especiales

## Tabla de contenidos

- Arquitectura
- Conexiones
- Persistir datos

## Visión general de la arquitectura

Este artículo explica cómo se integran todos los diferentes componentes del controlador PHP, desde las bibliotecas del sistema base, hasta la extensión, y las bibliotecas PHP en la parte superior.

En la parte superior de esta pila se encuentra una » biblioteca PHP, que distribuye un » paquete Composer. Esta biblioteca proporciona una API coherente con otros » controladores MongoDB e implementa diversas » especificaciones cruzadas. Aunque la extensión puede ser utilizada directamente, la biblioteca tiene un sobrecoste mínimo y debería ser una dependencia común para la mayoría de las aplicaciones construidas con MongoDB.

Debajo de esta biblioteca se encuentra una extensión PHP, que se distribuye a través de » PECL. La extensión forma la cola entre PHP y nuestras bibliotecas del sistema (» libmongoc, » libbson, y » libmongocrypt). Su API pública proporciona únicamente las funcionalidades más esenciales:

- Gestión de conexiones
- Codificación y decodificación BSON
- Serialización y deserialización de documentos (soporte de bibliotecas ODM)
- Ejecución de comandos, consultas y operaciones de escritura
- Gestión de cursores para los resultados de comandos y consultas

Código fuente del controlador y proyectos JIRA
Proyecto | GitHub | JIRA
--- | --- | ---
Bibliotecas PHP | » mongodb/mongo-php-library | » PHPLIB
Extensiones PHP | » mongodb/mongo-php-driver | » PHPC

## Gestión de la conexión y de la persistencia

> Nota: En las plataformas Unix, la extensión MongoDB es sensible a los scripts que utilizan la llamada al sistema fork() sin llamar a exec(). No se deben reutilizar instancias MongoDB\Driver\Manager en un proceso hijo derivado de un fork.

## Conexiones y topología persistente (versión PHP desde 1.2.0)

Todas las versiones de la extensión desde 1.2.0 conservan el objeto cliente » libmongoc en el proceso PHP, lo que le permite reutilizar las conexiones de base de datos, los estados de autenticación, y la información de topología a través de múltiples consultas.

Cuando MongoDB\Driver\Manager::__construct() es invocado, se crea un hash a partir de sus argumentos (es decir, la cadena URI y el array de opciones). La extensión intentará encontrar un objeto cliente » libmongoc persistido previamente para este hash. Si no se puede encontrar un cliente existente para el hash, se creará un nuevo cliente y se persistirá para su uso futuro. Este comportamiento puede ser desactivado a través de la opción del controlador `"disableClientPersistence"`.

Cada cliente contiene sus propias conexiones de base de datos y una vista de la topología del servidor (por ejemplo, autónomo, conjunto de réplicas, grupo de fragmentos). Al persistir el cliente entre las consultas PHP, la extensión es capaz de reutilizar las conexiones de base de datos establecidas y eliminar la necesidad de » descubrir la topología del servidor en cada consulta.

Considere el siguiente ejemplo:

    <?php

    $managers = [
        new MongoDB\Driver\Manager('mongodb://127.0.0.1'),
        new MongoDB\Driver\Manager('mongodb://127.0.0.1'),
        new MongoDB\Driver\Manager('mongodb://127.0.0.1:27017'),
        new MongoDB\Driver\Manager('mongodb://rs1.example.com,rs2.example.com/', ['replicaSet' => 'myReplicaSet']),
    ];

    foreach ($managers as $manager) {
        $manager->executeCommand('test', new MongoDB\Driver\Command(['ping' => 1]));
    }

    ?>

Los dos primeros objetos Manager compartirán el mismo cliente » libmongoc ya que sus argumentos de constructor son idénticos. Los tercer y cuarto objetos utilizarán cada uno su propio cliente. En total, se crearán tres clientes y el proceso PHP ejecutando este script abrirá dos conexiones a `127.0.0.1` y una conexión a cada uno de `rs1.example.com` y `rs2.example.com`. Si la extensión descubre miembros adicionales del conjunto de réplicas después de emitir comandos `hello`, abrirá conexiones adicionales a estos servidores también.

Si las mismas conexiones son reutilizadas por el mismo proceso PHP, los tres clientes serán reutilizados y no se establecerá ninguna nueva conexión. En función del tiempo transcurrido desde la última consulta servida, la extensión puede necesitar emitir comandos `hello` adicionales para actualizar su vista de las topologías.

## Persistencia de sockets (versiones PHP antes de 1.2.0)

Las versiones de la extensión antes de 1.2.0 utilizan la API de flujos PHP para las conexiones de base de datos, utilizando una API en » libmongoc para designar gestores personalizados para la comunicación por socket; sin embargo, se crea un nuevo cliente libmongoc para cada MongoDB\Driver\Manager. En consecuencia, la extensión persiste las conexiones de base de datos individuales pero no el estado de autentificación o la información de topología. Esto significa que la extensión debe emitir comandos al inicio de cada consulta para autenticarse y » descubrir la topología del servidor.

Las conexiones de base de datos son persistidas por un hash derivado del host del servidor, del puerto y de la cadena URI utilizada para construir el MongoDB\Driver\Manager. Las opciones del array del constructor no están incluidas en este hash.

> Nota: Las versiones de la extensión >= 1.1.8 y < 1.2.0 no persisten los sockets para las conexiones SSL. Ver » PHPC-720 para más información.

A pesar de sus carencias con las conexiones SSL persistentes y la información de topología, esta versión de la extensión soporta todas las opciones de contexto SSL ya que utiliza la API de flujos PHP.

## Serialización y deserialización de variables PHP en MongoDB

Este documento explica cómo se convierten las estructuras compuestas (es decir, los documentos, los arrays y los objetos) entre los valores BSON y PHP.

## Serialización en BSON

## Arrays

Si un array es un array compacto — es decir, un array vacío o las claves comienzan en 0 y son secuenciales sin huecos : array BSON.

Si el array no es compacto — es decir, que tiene claves asociativas (cadenas), que las claves no comienzan en 0, o que hay huecos : objeto BSON.

Un documento de nivel superior (raíz), siempre serializado como documento BSON.

## Ejemplos

Estos ejemplos se serializan como array BSON :

    [ 8, 5, 2, 3 ] => [ 8, 5, 2, 3 ]
    [ 0 => 4, 1 => 9 ] => [ 4, 9 ]

Estos ejemplos se serializan como objeto BSON :

    [ 0 => 1, 2 => 8, 3 => 12 ] => { "0" : 1, "2" : 8, "3" : 12 }
    [ "foo" => 42 ] => { "foo" : 42 }
    [ 1 => 9, 0 => 10 ] => { "1" : 9, "0" : 10 }

Es de notar que los cinco ejemplos son extractos de un documento completo, y solo representan un valor dentro de un documento.

## Objetos

Si un objeto es de la clase stdClass, serializar como documento BSON.

Si un objeto es una clase soportada que implementa MongoDB\BSON\Type, entonces utilizar la lógica de serialización BSON para este tipo específico. Las instancias de MongoDB\BSON\Type (a excepción de MongoDB\BSON\Serializable) solo pueden ser serializadas como valor de campo de documento. Intentar serializar tal objeto como documento raíz lanzará una MongoDB\Driver\Exception\UnexpectedValueException.

Si un objeto es de una clase desconocida que implementa la interfaz MongoDB\BSON\Type, entonces se lanza una MongoDB\Driver\Exception\UnexpectedValueException.

Si un objeto es de otra clase, sin implementar una interfaz especial, serializar como documento BSON. Mantener solo las propiedades públicas, e ignorar las propiedades protegidas y privadas.

Si un objeto es de una clase que implementa MongoDB\BSON\Serializable, llamar MongoDB\BSON\Serializable::bsonSerialize() y utilizar el array o stdClass devuelto para serializar como documento BSON o array. El tipo BSON será determinado por las siguientes reglas :

1. Los documentos raíz deben ser serializados como documento BSON.
2. Los objetos MongoDB\BSON\Persistable deben ser serializados como documento BSON.
3. Si MongoDB\BSON\Serializable::bsonSerialize() devuelve un array compacto, serializar como array BSON.
4. Si MongoDB\BSON\Serializable::bsonSerialize() devuelve un array no compacto o stdClass, serializar como objeto BSON.
5. Si MongoDB\BSON\Serializable::bsonSerialize() no devuelve un array o stdClass, lanzar una excepción MongoDB\Driver\Exception\UnexpectedValueException.

Si un objeto es de una clase que implementa la interfaz MongoDB\BSON\Persistable (lo que implica MongoDB\BSON\Serializable), obtener las propiedades de manera similar a los párrafos anteriores, pero también añadir una propiedad __pclass como valor binario, con un subtipo `0x80` y datos que llevan el nombre de la clase completamente calificado del objeto que se serializa.

La propiedad __pclass se añade al array o al objeto devuelto por MongoDB\BSON\Serializable::bsonSerialize(), lo que significa que sobrescribirá cualquier clave/propiedad __pclass en el valor de retorno de MongoDB\BSON\Serializable::bsonSerialize(). Si se desea evitar este comportamiento y definir su propio valor __pclass, no se debe implementar MongoDB\BSON\Persistable y se debería implementar MongoDB\BSON\Serializable directamente.

## Ejemplos

    <?php

    class stdClass
    {
        public $foo = 42;
    } // => {"foo": 42}

    class MyClass
    {
        public $foo = 42;
        protected $prot = 'wine';
        private $fpr = 'cheese';
    } // => {"foo": 42}

    class AnotherClass1 implements MongoDB\BSON\Serializable
    {
        public $foo = 42;
        protected $prot = 'wine';
        private $fpr = 'cheese';

        public function bsonSerialize(): array
        {
            return ['foo' => $this->foo, 'prot' => $this->prot];
        }
    } // => {"foo": 42, "prot": "wine"}

    class AnotherClass2 implements MongoDB\BSON\Serializable
    {
        public $foo = 42;

        public function bsonSerialize(): self
        {
            return $this;
        }
    } // => MongoDB\Driver\Exception\UnexpectedValueException("bsonSerialize() did not return an array or stdClass")

    class AnotherClass3 implements MongoDB\BSON\Serializable
    {
        private $elements = ['foo', 'bar'];

        public function bsonSerialize(): array
        {
            return $this->elements;
        }
    } // => {"0": "foo", "1": "bar"}

    /**
     * Nesting Serializable classes
     */

    class AnotherClass4 implements MongoDB\BSON\Serializable
    {
        private $elements = [0 => 'foo', 2 => 'bar'];

        public function bsonSerialize(): array
        {
            return $this->elements;
        }
    } // => {"0": "foo", "2": "bar"}

    class ContainerClass1 implements MongoDB\BSON\Serializable
    {
        public $things;

        public function __construct()
        {
            $this->things = new AnotherClass4();
        }

        function bsonSerialize(): array
        {
            return ['things' => $this->things];
        }
    } // => {"things": {"0": "foo", "2": "bar"}}

    class AnotherClass5 implements MongoDB\BSON\Serializable
    {
        private $elements = [0 => 'foo', 2 => 'bar'];

        public function bsonSerialize(): array
        {
            return array_values($this->elements);
        }
    } // => {"0": "foo", "1": "bar"} como clase raíz
      //        ["foo", "bar"] como valor anidado

    class ContainerClass2 implements MongoDB\BSON\Serializable
    {
        public $things;

        public function __construct()
        {
            $this->things = new AnotherClass5();
        }

        public function bsonSerialize(): array
        {
            return ['things' => $this->things];
        }
    } // => {"things": ["foo", "bar"]}

    class AnotherClass6 implements MongoDB\BSON\Serializable
    {
        private $elements = ['foo', 'bar'];

        function bsonSerialize(): object
        {
            return (object) $this->elements;
        }
    } // => {"0": "foo", "1": "bar"}

    class ContainerClass3 implements MongoDB\BSON\Serializable
    {
        public $things;

        public function __construct()
        {
            $this->things = new AnotherClass6();
        }

        public function bsonSerialize(): array
        {
            return ['things' => $this->things];
        }
    } // => {"things": {"0": "foo", "1": "bar"}}

    class UpperClass implements MongoDB\BSON\Persistable
    {
        public $foo = 42;
        protected $prot = 'wine';
        private $fpr = 'cheese';

        private $data;

        public function bsonUnserialize(array $data): void
        {
            $this->data = $data;
        }

        public function bsonSerialize(): array
        {
            return ['foo' => $this->foo, 'prot' => $this->prot];
        }
    } // => {"foo": 42, "prot": "wine", "__pclass": {"$type": "80", "$binary": "VXBwZXJDbGFzcw=="}}

    ?>

## Deserialización desde BSON

Advertencia

Los documentos BSON pueden contener técnicamente claves duplicadas ya que los documentos se almacenan como una lista de pares clave-valor; sin embargo, las aplicaciones deben abstenerse de generar documentos con claves duplicadas ya que el comportamiento del servidor y del controlador puede ser indefinido. Dado que los objetos y arrays de PHP no pueden tener claves duplicadas, los datos también podrían perderse al decodificar un documento BSON con claves duplicadas.

La extensión `mongodb` deserializa los documentos BSON y los arrays BSON como arrays PHP. Aunque los arrays PHP son prácticos de usar, este comportamiento era problemático ya que diferentes tipos BSON podían ser deserializados en el mismo valor PHP (por ejemplo `{"0": "foo"}` y `["foo"]`) y hacía imposible inferir el tipo BSON original. Por defecto, la extensión `mongodb` aborda esta preocupación asegurándose de que los arrays BSON y los documentos BSON se conviertan en arrays y objetos PHP, respectivamente.

Para los tipos compuestos, existen tres tipos de datos :

raíz
  se refiere a un documento BSON de nivel superior solo
documento
  se refiere a documentos BSON anidados solo
array
  se refiere a un array BSON

Además de los tres tipos colectivos, también es posible configurar campos específicos en su documento para mapear los tipos de datos mencionados a continuación. Por ejemplo, el siguiente tipo de mapa le permite mapear cada documento incrustado en un array `"addresses"` a una clase Address y cada campo `"city"` en estos documentos de dirección incrustados a una clase City:

    [
        'fieldPaths' => [
            'addresses.$' => 'MyProject\Address',
            'addresses.$.city' => 'MyProject\City',
        ],
    ]

Cada uno de estos tres tipos de datos, así como los mapeos específicos de los campos, pueden ser mapeados contra diferentes tipos PHP. Los valores de mapeo posibles son:

no definido o NULL (por defecto)

  - Un array BSON será deserializado en un array PHP.
  - Un documento BSON (raíz o anidado) sin propiedad __pclass [1]

    Una propiedad __pclass solo se considera existente si una propiedad con ese nombre existe, y es un valor binario, y el subtipo del valor binario es 0x80. Si alguna de estas tres condiciones no se cumple, la propiedad __pclass no existe y debe ser tratada como cualquier otra propiedad normal.

    se convierte en un objeto stdClass, con cada clave de documento BSON definida como una propiedad de stdClass pública.
  - Un documento BSON (raíz o anidado) con una propiedad __pclass se convierte en un objeto PHP de la clase nombrada por la propiedad __pclass. Si la clase nombrada implementa la interfaz MongoDB\BSON\Persistable, entonces las propiedades del documento BSON, incluyendo la propiedad __pclass, se envían como array asociativo a la función MongoDB\BSON\Unserializable::bsonUnserialize() para inicializar las propiedades del objeto. Si la clase nombrada no existe o no implementa la interfaz MongoDB\BSON\Persistable, stdClass será utilizado y cada clave de documento BSON (incluyendo __pclass) será definida como una propiedad pública de stdClass. La funcionalidad __pclass se basa en el hecho de que la propiedad sea parte de un documento MongoDB recuperado. Si utiliza una proyección al buscar documentos, debe incluir el campo __pclass en la proyección para que esta funcionalidad funcione.
`"array"`
  Transforma un array BSON en un array PHP. No habrá tratamiento especial de una propiedad __pclass [1] pero puede ser definida como un elemento en el array devuelto si estaba presente en el documento BSON.
`"object"` o `"stdClass"`
  Transforma un array BSON o un documento BSON en un objeto stdClass. No habrá tratamiento especial de una propiedad __pclass [1] pero puede ser definida como una propiedad pública en el objeto devuelto si estaba presente en el documento BSON.
`"bson"`
  Transforma un array BSON en un MongoDB\BSON\PackedArray y un documento BSON en un MongoDB\BSON\Document, independientemente de si el documento BSON tiene una propiedad __pclass [1].

  > Nota: El valor `bson` solo está disponible para los tres tipos raíz, y no en los mapeos específicos de los campos.

todas las otras cadenas de caracteres
  Define el nombre de la clase a la que el documento BSON debe ser deserializado. Para los documentos BSON que incluyen propiedades __pclass, esta clase tendrá prioridad. Si la clase nombrada no existe o no implementa la interfaz MongoDB\BSON\Unserializable, se lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException. Si el objeto BSON tiene una propiedad __pclass y esta clase existe e implementa MongoDB\BSON\Persistable, tendrá prioridad sobre la clase proporcionada en el mapa de tipos. Las propiedades del documento BSON, incluyendo la propiedad __pclass, serán enviadas como array asociativo a la función MongoDB\BSON\Unserializable::bsonUnserialize() para inicializar las propiedades del objeto.

## TypeMaps

Los TypeMaps pueden ser definidos a través del método MongoDB\Driver\Cursor::setTypeMap() en un objeto MongoDB\Driver\Cursor, o el argumento `$typeMap` de MongoDB\BSON\toPHP(), MongoDB\BSON\Document::toPHP(), y MongoDB\BSON\PackedArray::toPHP(). Cada una de las tres clases (raíz, documento, y array) puede ser definida individualmente, además de los tipos específicos de los campos.

Si el valor en el TypeMap es NULL, esto significa lo mismo que el valor por defecto para este elemento.

## Ejemplos

Estos ejemplos utilizan las siguientes clases:

MyClass
  que no implementa ninguna interfaz
YourClass
  que implementa MongoDB\BSON\Unserializable
OurClass
  que implementa MongoDB\BSON\Persistable
TheirClass
  que extiende OurClass

El método MongoDB\BSON\Unserializable::bsonUnserialize() de YourClass, OurClass, TheirClass itera sobre el array y define las propiedades sin modificaciones. También añade la propiedad `$unserialized` a `true`:

    <?php

    function bsonUnserialize( array $map )
    {
        foreach ( $map as $k => $value )
        {
            $this->$k = $value;
        }
        $this->unserialized = true;
    }

    /* typemap: [] (todos los valores por defecto) */
    { "foo": "yes", "bar" : false }
      -> stdClass { $foo => 'yes', $bar => false }

    { "foo": "no", "array" : [ 5, 6 ] }
      -> stdClass { $foo => 'no', $array => [ 5, 6 ] }

    { "foo": "no", "obj" : { "embedded" : 3.14 } }
      -> stdClass { $foo => 'no', $obj => stdClass { $embedded => 3.14 } }

    { "foo": "yes", "__pclass": "MyClass" }
      -> stdClass { $foo => 'yes', $__pclass => 'MyClass' }

    { "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "MyClass" } }
      -> stdClass { $foo => 'yes', $__pclass => Binary(0x80, 'MyClass') }

    { "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "YourClass") }
      -> stdClass { $foo => 'yes', $__pclass => Binary(0x80, 'YourClass') }

    { "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "OurClass") }
      -> OurClass { $foo => 'yes', $__pclass => Binary(0x80, 'OurClass'), $unserialized => true }

    { "foo": "yes", "__pclass": { "$type" : "44", "$binary" : "YourClass") }
      -> stdClass { $foo => 'yes', $__pclass => Binary(0x44, 'YourClass') }

    /* typemap: [ "root" => "MissingClass" ] */
    { "foo": "yes" }
      -> MongoDB\Driver\Exception\InvalidArgumentException("MissingClass does not exist")

    /* typemap: [ "root" => "MyClass" ] */
    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
      -> MongoDB\Driver\Exception\InvalidArgumentException("MyClass does not implement Unserializable interface")

    /* typemap: [ "root" => "MongoDB\BSON\Unserializable" ] */
    { "foo": "yes" }
      -> MongoDB\Driver\Exception\InvalidArgumentException("Unserializable is not a concrete class")

    /* typemap: [ "root" => "YourClass" ] */
    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MongoDB\BSON\Unserializable" } }
      -> YourClass { $foo => "yes", $__pclass => Binary(0x80, "MongoDB\BSON\Unserializable"), $unserialized => true }

    /* typemap: [ "root" => "YourClass" ] */
    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
      -> YourClass { $foo => "yes", $__pclass => Binary(0x80, "MyClass"), $unserialized => true }

    /* typemap: [ "root" => "YourClass" ] */
    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "OurClass" } }
      -> OurClass { $foo => "yes", $__pclass => Binary(0x80, "OurClass"), $unserialized => true }

    /* typemap: [ "root" => "YourClass" ] */
    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "TheirClass" } }
      -> TheirClass { $foo => "yes", $__pclass => Binary(0x80, "TheirClass"), $unserialized => true }

    /* typemap: [ "root" => "OurClass" ] */
    { foo: "yes", "__pclass" : { "$type": "80", "$binary": "TheirClass" } }
      -> TheirClass { $foo => "yes", $__pclass => Binary(0x80, "TheirClass"), $unserialized => true }

    /* typemap: [ 'root' => 'YourClass' ] */
    { foo: "yes", "__pclass" : { "$type": "80", "$binary": "YourClass" } }
      -> YourClass { $foo => 'yes', $__pclass => Binary(0x80, 'YourClass'), $unserialized => true }

    /* typemap: [ 'root' => 'array', 'document' => 'array' ] */
    { "foo": "yes", "bar" : false }
      -> [ "foo" => "yes", "bar" => false ]

    { "foo": "no", "array" : [ 5, 6 ] }
      -> [ "foo" => "no", "array" => [ 5, 6 ] ]

    { "foo": "no", "obj" : { "embedded" : 3.14 } }
      -> [ "foo" => "no", "obj" => [ "embedded => 3.14 ] ]

    { "foo": "yes", "__pclass": "MyClass" }
      -> [ "foo" => "yes", "__pclass" => "MyClass" ]

    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
      -> [ "foo" => "yes", "__pclass" => Binary(0x80, "MyClass") ]

    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "OurClass" } }
      -> [ "foo" => "yes", "__pclass" => Binary(0x80, "OurClass") ]

    /* typemap: [ 'root' => 'object', 'document' => 'object' ] */
    { "foo": "yes", "__pclass": { "$type": "80", "$binary": "MyClass" } }
      -> stdClass { $foo => "yes", "__pclass" => Binary(0x80, "MyClass") }

# Seguridad

## Tabla de contenidos

- Ataques por inyección de peticiones
- Ataques por inyección de scripts

## Ataques por inyección de peticiones

Si está pasando parámetros de `$_GET` (o `$_POST`) a sus consultas, asegúrese de que primero se conviertan a strings. Los usuarios pueden insertar arrays asociativos en peticiones GET y POST, lo que podría convertirse en consultas no deseadas con operadores $-.

Un ejemplo bastante inocuo: supongamos que está buscando la información de un usuario con la petición http://www.example.com?username=bob. Su aplicación crea la consulta `$q = new \MongoDB\Driver\Query( [ 'username' => $_GET['username'] ])`.

Alguien podría subvertir esto mediante http://www.example.com?username[$ne]=foo, que PHP convertirá mágicamente en un array asociativo, convirtiendo su consulta en `$q = new \MongoDB\Driver\Query( [ 'username' => [ '$ne' => 'foo' ] ] )`, lo que devolverá todos los usuarios que no se llamen "foo" (probablemente todos sus usuarios).

Este es un ataque bastante fácil de defender: asegúrese de que los parámetros de $_GET y $_POST sean del tipo que espera antes de enviarlos a la base de datos. PHP tiene la función filter_var() para ayudar con esto.

Tenga en cuenta que este tipo de ataque puede usarse con cualquier interacción con la base de datos que localice un documento, incluyendo actualizaciones, upserts, eliminaciones y comandos findAndModify.

Consulte » la documentación principal para obtener más información sobre problemas similares a la inyección SQL con MongoDB.

## Ataques por inyección de scripts

Si está usando JavaScript, asegúrese de que cualquier variable que cruce el límite entre PHP y JavaScript se pase en el campo `scope` de MongoDB\BSON\Javascript, no interpolada en la cadena de JavaScript. Esto puede ocurrir al usar cláusulas `$where` en consultas, comandos mapReduce y group, y cualquier otro momento en que pase JavaScript a la base de datos.

Por ejemplo, supongamos que tenemos algo de JavaScript para saludar a un usuario en los registros de la base de datos. Podríamos hacer:

    <?php
    $m = new MongoDB\Driver\Manager;

    // ¡No haga esto!
    $username = $_GET['field'];

    $cmd = new \MongoDB\Driver\Command( [
        'eval' => "print('Hola, $username!');"
    ] );

    $r = $m->executeCommand( 'dramio', $cmd );
    ?>

Sin embargo, ¿qué pasaría si un usuario malicioso pasa algo de JavaScript?

    <?php
    $m = new MongoDB\Driver\Manager;

    // ¡No haga esto!
    $username = $_GET['field'];
    // $username se establece en "'); db.users.drop(); print('"

    $cmd = new \MongoDB\Driver\Command( [
        'eval' => "print('Hola, $username!');"
    ] );

    $r = $m->executeCommand( 'dramio', $cmd );
    ?>

Ahora MongoDB ejecuta la cadena de JavaScript `"print('Hola, '); db.users.drop(); print('!');"`. Este ataque es fácil de evitar: use `args` para pasar variables de PHP a JavaScript:

    <?php
    $m = new MongoDB\Driver\Manager;

    $_GET['field'] = 'derick';
    $args = [ $_GET['field'] ];

    $cmd = new \MongoDB\Driver\Command( [
        'eval' => "function greet(username) { print('Hola, ' + username + '!'); }",
        'args' => $args,
    ] );

    $r = $m->executeCommand( 'dramio', $cmd );
    ?>

Esto añade un argumento al ámbito de JavaScript, que se usa como argumento para la función `greet`. Ahora si alguien intenta enviar código malicioso, MongoDB imprimirá inocuamente `Hola, '); db.dropDatabase(); print('!`.

Usar argumentos ayuda a prevenir que la entrada maliciosa se ejecute en la base de datos. Sin embargo, debe asegurarse de que su código no vuelva a ejecutar la entrada de todos modos. Lo mejor es evitar ejecutar cualquier JavaScript en el servidor desde el principio.

Se recomienda encarecidamente evitar el uso de la cláusula » `$where` en consultas, ya que afecta significativamente al rendimiento. Siempre que sea posible, use operadores de consulta normales o el » Marco de Agregación.

Como alternativa al » MapReduce, que usa JavaScript, considere usar el » Marco de Agregación. A diferencia de Map/Reduce, usa un lenguaje idiomático para construir consultas, sin tener que escribir y usar el enfoque más lento de JavaScript que requiere Map/Reduce.

El comando » eval ha sido deprecado desde MongoDB 3.0 y también debe evitarse.

# Clases de la extensión MongoDB

## Tabla de contenidos

- MongoDB\Driver\Manager
- MongoDB\Driver\Command
- MongoDB\Driver\Query
- MongoDB\Driver\BulkWrite
- MongoDB\Driver\BulkWriteCommand
- MongoDB\Driver\Session
- MongoDB\Driver\ClientEncryption
- MongoDB\Driver\ServerApi
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\ReadPreference
- MongoDB\Driver\ReadConcern
- MongoDB\Driver\Cursor
- MongoDB\Driver\CursorId
- MongoDB\Driver\CursorInterface
- MongoDB\Driver\Server
- MongoDB\Driver\ServerDescription
- MongoDB\Driver\TopologyDescription
- MongoDB\Driver\WriteConcernError
- MongoDB\Driver\WriteError
- MongoDB\Driver\WriteResult
- MongoDB\Driver\BulkWriteCommandResult

# La clase MongoDB\Driver\Manager

(mongodb >=1.0.0)

## Introducción

La clase MongoDB\Driver\Manager es el punto de entrada principal a la extensión. Es responsable de mantener las conexiones a MongoDB (ya sea un servidor independiente, un conjunto de réplicas o un clúster particionado).

No se realiza ninguna conexión a MongoDB al instanciar el Manager. Esto significa que el MongoDB\Driver\Manager siempre puede ser construido, incluso si uno o más servidores de MongoDB están caídos.

Cualquier escritura o consulta puede lanzar excepciones de conexión ya que las conexiones se crean de forma perezosa. Un servidor de MongoDB también puede volverse no disponible durante la ejecución del script. Por lo tanto, es importante envolver todas las acciones sobre el Manager en sentencias try/catch.

## Sinopsis de la Clase

final class MongoDB\Driver\Manager {
/* Métodos */
final public function addSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void
final public function __construct(?string `$uri` = `null`, ?array `$uriOptions` = `null`, ?array `$driverOptions` = `null`)
final public function createClientEncryption(array `$options`): MongoDB\Driver\ClientEncryption
final public function executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$options` = `null`): MongoDB\Driver\WriteResult
final public function executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult
final public function executeCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function getEncryptedFieldsMap(): array|object|null
final public function getReadConcern(): MongoDB\Driver\ReadConcern
final public function getReadPreference(): MongoDB\Driver\ReadPreference
final public function getServers(): array
final public function getWriteConcern(): MongoDB\Driver\WriteConcern
final public function removeSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void
final public function selectServer(?MongoDB\Driver\ReadPreference `$readPreference` = `null`): MongoDB\Driver\Server
final public function startSession(?array `$options` = `null`): MongoDB\Driver\Session
}

## Ejemplos

Ejemplo #1 Ejemplo básico de MongoDB\Driver\Manager::__construct()

Realizar un var_dump() de un MongoDB\Driver\Manager mostrará varios detalles sobre el gestor que normalmente no están expuestos. Esto puede ser útil para depurar cómo el controlador visualiza su configuración de MongoDB y qué opciones se están utilizando.

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    var_dump($manager);

    ?>

Resultado del ejemplo anterior es similar a:

    object(MongoDB\Driver\Manager)#1 (2) {
      ["uri"]=>
      string(26) "mongodb://127.0.0.1:27017/"
      ["cluster"]=>
      array(0) {
      }
    }

# MongoDB\Driver\Manager::addSubscriber

(mongodb >=1.10.0)

MongoDB\Driver\Manager::addSubscriber — Registra un observador de eventos de monitoreo con este manager

### Descripción

final public function MongoDB\Driver\Manager::addSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void

Registra un observador de eventos de monitoreo con este Manager. El observador será notificado de todos los eventos para este Manager.

> Nota: Si `subscriber` ya está registrado con este manager, esta función no hace nada. Si `subscriber` también está registrado globalmente, solo será notificado una vez de cada evento para este manager.

### Parámetros

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  Un observador de eventos de monitoreo a registrar con este Manager.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una MongoDB\Driver\Exception\InvalidArgumentException si `subscriber` es un MongoDB\Driver\Monitoring\LogSubscriber, ya que los observadores solo pueden ser registrados globalmente.

### Ver también

- MongoDB\Driver\Manager::removeSubscriber() - Elimina un observador de eventos de supervisión de este Manager
- MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Monitoring\addSubscriber() - Registra un suscriptor de eventos de monitorización de forma global
- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

# MongoDB\Driver\Manager::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Manager::__construct — Crea un nuevo Manager MongoDB

### Descripción

final public function MongoDB\Driver\Manager::__construct(?string `$uri` = `null`, ?array `$uriOptions` = `null`, ?array `$driverOptions` = `null`)

Construye un nuevo objeto MongoDB\Driver\Manager con las opciones especificadas.

> Nota: Con la » Especificación de descubrimiento y supervisión del servidor, este constructor no realiza E/S. Las conexiones se inicializarán bajo demanda, durante la ejecución de la primera operación.

> Nota: Cuando se especifican opciones de URI SSL o TLS a través de la cadena de conexión o el parámetro `uriOptions`, la extensión activará implícitamente TLS para sus conexiones. Para evitar esto, desactive explícitamente la opción `tls` o no especifique ninguna opción TLS.

> Nota: En las plataformas Unix, la extensión MongoDB es sensible a los scripts que utilizan la llamada al sistema fork() sin llamar a exec(). No se deben reutilizar instancias MongoDB\Driver\Manager en un proceso hijo derivado de un fork.

### Parámetros

`uri`

  Una URI de conexión » mongodb://:

      mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[defaultAuthDb][?options]]

  Para los detalles sobre las opciones de URI admitidas, ver » Opciones de cadena de conexión en el manual MongoDB. » Opciones de pool de conexiones no son admitidas, ya que la extensión no implementa pools de conexiones.

  Por omisión, `"mongodb://127.0.0.1:27017"` si no se especifica.

  El `uri` es una URL, por lo que todos los caracteres especiales en sus componentes deben estar codificados en URL según la » RFC 3986. Esto es particularmente relevante para el nombre de usuario y la contraseña, que pueden incluir caracteres especiales tales como `@`, `:` o `%`. Al conectarse a través de un socket de dominio Unix, la ruta del socket puede contener caracteres especiales como barras diagonales y debe estar codificada. La función rawurlencode() puede ser utilizada para codificar las partes constitutivas de la URI.

  El componente `defaultAuthDb` puede ser utilizado para especificar la base de datos asociada a las credenciales del usuario; sin embargo, la opción de URI `authSource` tendrá prioridad si se especifica. Si ni `defaultAuthDb` ni `authSource` se especifican, la base de datos `admin` será utilizada por omisión. El componente `defaultAuthDb` no tiene ningún efecto en ausencia de credenciales de usuario.

`uriOptions`

  Opciones adicionales » de cadena de conexión, que sobrescribirán cualquier opción con el mismo nombre en el parámetro `uri`.

  uriOptions
  Opción | Tipo | Descripción
  --- | --- | ---
  appname | string | MongoDB 3.4+ tiene la capacidad de anotar las conexiones con metadatos proporcionados por el cliente conectado. Estos metadatos se incluyen en los registros del servidor al establecer una conexión y también se registran en los registros de consultas lentas cuando el perfilado de la base de datos está activado. Esta opción puede ser utilizada para especificar un nombre de aplicación, que será incluido en los metadatos. El valor no puede exceder 128 caracteres de longitud.
  authMechanism | string | El mecanismo de autenticación que MongoDB utilizará para autenticar la conexión. Para más detalles y una lista de los valores admitidos, ver » Opciones de autenticación en el manual MongoDB.
  authMechanismProperties | array | Las propiedades específicas del mecanismo de autenticación seleccionado. Para más detalles y una lista de las propiedades admitidas, ver la » Especificación de autenticación del controlador. Nota: Cuando no se especifica en la cadena de URI, esta opción se expresa como un array de pares clave/valor. Las claves y valores de este array deben ser strings.
  authSource | string | El nombre de la base de datos asociada a las credenciales del usuario. Por omisión al componente de la base de datos de la URI de conexión, o a la base de datos `admin` si ambos no se especifican. Para los mecanismos de autenticación que no admiten la noción de base de datos (por ejemplo, GSSAPI), esto debería ser `"$external"`.
  compressors | string | Una lista priorizada y delimitada por comas de compresores que el cliente desea utilizar. Los mensajes solo se comprimen si el cliente y el servidor comparten compresores en común, y el compresor utilizado en cada dirección dependerá de la configuración individual del servidor o del controlador. Ver la » Especificación de compresión del controlador para más información.
  connectTimeoutMS | int | El tiempo en milisegundos para intentar una conexión antes de expirar. Por omisión, 10 000 milisegundos.
  directConnection | bool | Esta opción puede ser utilizada para controlar el comportamiento de descubrimiento del conjunto de réplicas cuando solo se proporciona un host en la cadena de conexión. Por omisión, proporcionar un solo miembro en la cadena de conexión establecerá una conexión directa o descubrirá miembros adicionales según si la opción de URI `"replicaSet"` está omitida o presente, respectivamente. Especifique `false` para forzar el descubrimiento a que ocurra (si `"replicaSet"` está omitido) o especifique `true` para forzar una conexión directa (si `"replicaSet"` está presente).
  enableOverloadRetargeting | bool | Cuando se establece a `true`, fuerza la selección del servidor tras un `SystemOverloadedError`. Por omisión, `false`.
  heartbeatFrequencyMS | int | Especifica el intervalo en milisegundos entre las verificaciones de la topología MongoDB, contado desde el final de la verificación previa hasta el inicio de la siguiente. Por omisión, 60 000 milisegundos. Para la » Especificación de descubrimiento y supervisión del servidor, este valor no puede ser inferior a 500 milisegundos.
  journal | bool | Corresponde a la opción `journal` del write concern por omisión. Si `true`, las escrituras requerirán un acuse de recibo de MongoDB indicando que la operación ha sido escrita en el diario. Para más detalles, ver MongoDB\Driver\WriteConcern.
  loadBalanced | bool | Especifica si el controlador se conecta a un clúster MongoDB a través de un equilibrador de carga. Si `true`, el controlador solo puede conectarse a un solo host (especificado por la cadena de conexión o la búsqueda SRV), la opción de URI `"directConnection"` no puede ser `true`, y la opción de URI `"replicaSet"` debe ser omitida. Por omisión, `false`.
  localThresholdMS | int | El tamaño en milisegundos de la ventana de latencia para la selección entre múltiples instancias MongoDB apropiadas al resolver una preferencia de lectura. Por omisión, 15 milisegundos.
  maxAdaptiveRetries | int | Esta opción puede ser utilizada para cambiar el número máximo de reintentos cuando se produce un `SystemOverloadedError`. Debe ser un entero positivo; por omisión, `2`.
  maxStalenessSeconds | int | Corresponde a la opción `maxStalenessSeconds` de la preferencia de lectura. Especifica, en segundos, la duración máxima de validez de una instancia secundaria antes de que el cliente deje de usarla para las operaciones de lectura. Por omisión, no hay una duración máxima de validez y los clientes no tendrán en cuenta el retraso de una instancia secundaria al elegir la dirección de una operación de lectura. Para más detalles, ver MongoDB\Driver\ReadPreference. Si se especifica, la duración máxima de validez debe ser un entero de 32 bits firmado superior o igual a `MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS` (por ejemplo, 90 segundos).
  password | string | La contraseña del usuario en proceso de autenticación. Esta opción es útil si la contraseña contiene caracteres especiales, que de otro modo deberían estar codificados en URL para la URI de conexión.
  readConcernLevel | string | Corresponde a la opción `level` de la preferencia de lectura. Especifica el nivel de aislamiento de lectura. Para más detalles, ver MongoDB\Driver\ReadConcern.
  readPreference | string | Corresponde a la opción `mode` de la preferencia de lectura. Por omisión, `"primary"`. Para más detalles, ver MongoDB\Driver\ReadPreference.
  readPreferenceTags | array | Corresponde a la opción `tagSets` de la preferencia de lectura. Los conjuntos de etiquetas permiten dirigir las operaciones de lectura a miembros específicos de un conjunto de réplicas. Para más detalles, ver MongoDB\Driver\ReadPreference. Nota: Cuando no se especifica en la cadena de URI, esta opción se expresa como un array conforme al formato esperado por MongoDB\Driver\ReadPreference::__construct().
  replicaSet | string | Especifica el nombre del conjunto de réplicas.
  retryReads | bool | Especifica si el controlador debe reintentar automáticamente ciertas operaciones de lectura que fallan debido a errores de red transitorios o elecciones de conjunto de réplicas. Esta funcionalidad requiere MongoDB 3.6+. Por omisión, `true`. Ver la » Especificación de lectura reintentable para más información.
  retryWrites | bool | Especifica si el controlador debe reintentar automáticamente ciertas operaciones de escritura que fallan debido a errores de red transitorios o elecciones de conjunto de réplicas. Esta funcionalidad requiere MongoDB 3.6+. Por omisión, `true`. Ver » Escrituras reintentables en el manual MongoDB para más información.
  serverSelectionTimeoutMS | int | Especifica cuánto tiempo en milisegundos bloquear para la selección del servidor antes de lanzar una excepción. Por omisión, 30 000 milisegundos.
  serverSelectionTryOnce | bool | Cuando `true`, indica al controlador que escanee el despliegue MongoDB exactamente una vez después de un fallo de selección del servidor, luego seleccione un servidor o lance una excepción. Cuando `false`, el controlador bloquea y busca un servidor hasta el valor de `"serverSelectionTimeoutMS"`. Por omisión, `true`.
  socketCheckIntervalMS | int | Si un socket no ha sido utilizado recientemente, el controlador debe verificarlo a través de un comando `hello` antes de usarlo para cualquier operación. Por omisión, 5 000 milisegundos.
  socketTimeoutMS | int | El tiempo en milisegundos para intentar un envío o recepción en un socket antes de expirar. Por omisión, 300 000 milisegundos (es decir, cinco minutos).
  srvMaxHosts | int | El número máximo de resultados SRV a seleccionar aleatoriamente durante la primera población de la lista de semillas o, durante la consulta SRV, la adición de nuevos hosts a la topología. Por omisión, `0` (es decir, sin máximo).
  srvServiceName | string | El nombre de servicio a utilizar para la búsqueda SRV en la lista de semillas inicial y la consulta SRV. Por omisión, `"mongodb"`.
  tls | bool | Inicializa la conexión con TLS/SSL si `true`. Por omisión, `false`.
  tlsAllowInvalidCertificates | bool | Especifica si el controlador debe generar un error cuando el certificado TLS del servidor es inválido. Por omisión, `false`. Advertencia Desactivar la validación del certificado crea una vulnerabilidad.
  tlsAllowInvalidHostnames | bool | Especifica si el controlador debe generar un error cuando hay un desacuerdo entre el nombre de host del servidor y el nombre de host especificado por el certificado TLS. Por omisión, `false`. Advertencia Desactivar la validación del certificado crea una vulnerabilidad. Permitir nombres de host inválidos puede exponer al controlador a una » ataque del hombre del medio.
  tlsCAFile | string | La ruta del archivo que contiene un solo certificado o un conjunto de certificados de autoridades a considerar confiables al establecer una conexión TLS. Se utilizará el almacén de certificados del sistema por omisión.
  tlsCertificateKeyFile | string | La ruta del archivo de certificado del cliente o del archivo de clave privada del cliente; en el caso de que ambos sean necesarios, los archivos deben estar concatenados.
  tlsCertificateKeyFilePassword | string | La contraseña para descifrar la clave privada del cliente (es decir, la opción de URI `"tlsCertificateKeyFile"`) a utilizar para las conexiones TLS.
  tlsDisableCertificateRevocationCheck | bool | Si `true`, el controlador no intentará verificar el estado de revocación del certificado (por ejemplo, OCSP, CRL). Por omisión, `false`.
  tlsDisableOCSPEndpointCheck | bool | Si `true`, el controlador no intentará contactar un punto de extremo de responso OCSP si es necesario (es decir, una respuesta OCSP no está grapada). Por omisión, `false`.
  tlsInsecure | bool | Relaja las restricciones TLS tanto como sea posible. Especificar `true` para que esta opción tenga el mismo efecto que especificar `true` para las opciones de URI `"tlsAllowInvalidCertificates"` y `"tlsAllowInvalidHostnames"`. Por omisión, `false`. Advertencia Desactivar la validación del certificado crea una vulnerabilidad. Permitir nombres de host inválidos puede exponer al controlador a una » ataque del hombre del medio.
  username | string | El nombre de usuario del usuario en proceso de autenticación. Esta opción es útil si el nombre de usuario contiene caracteres especiales, que de otro modo deberían estar codificados en URL para la URI de conexión.
  w | int|string | Corresponde a la opción `w` del write concern por omisión. Para más detalles, ver MongoDB\Driver\WriteConcern.
  wTimeoutMS | int|string | Corresponde a la opción `wtimeout` del write concern por omisión. Especifica un límite de tiempo, en milisegundos, para el write concern. Para más detalles, ver MongoDB\Driver\WriteConcern. Si se especifica, `wTimeoutMS` debe ser un entero de 32 bits firmado superior o igual a cero.
  zlibCompressionLevel | int | Especifica el nivel de compresión a utilizar para el compresor zlib. Esta opción no tiene ningún efecto si `zlib` no está incluido en la opción de URI `"compressors"`. Ver la » Especificación de compresión del controlador para más información.

`driverOptions`

  driverOptions
  Opción | Tipo | Descripción
  --- | --- | ---
  autoEncryption | array | Proporciona opciones para activar el cifrado automático a nivel de campo. La lista de opciones se describe en la tabla de abajo. Nota: El cifrado automático es una funcionalidad empresarial que solo se aplica a las operaciones sobre una colección. El cifrado automático no es admitido para las operaciones sobre una base de datos o una vista, y las operaciones que no son sorteadas resultarán en un error (ver » libmongocrypt: La lista de autorización de cifrado automático). Para sortear el cifrado automático para todas las operaciones, establezca `bypassAutoEncryption` a `true`. El cifrado automático requiere que el usuario autenticado tenga el privilegio de acción » listCollections. El cifrado explícito y automático es una funcionalidad de la comunidad. El controlador siempre puede descifrar automáticamente cuando `bypassAutoEncryption` es `true`.
  ca_dir | string | La ruta del directorio de certificados correctamente hashados. Se utilizará el almacén de certificados del sistema por omisión.
  crl_file | string | La ruta del archivo de lista de revocación de certificados.
  disableClientPersistence | bool | Si `true`, este Manager utilizará un nuevo cliente libmongoc, que no será persistido ni compartido con otros objetos Manager. Cuando este objeto Manager es liberado, su cliente será destruido y todas las conexiones serán cerradas. Por omisión, `false`. Nota: Desactivar la persistencia del cliente no es generalmente recomendado.
  driver | array | Permite a un nivel superior de biblioteca añadir sus propias metadatos al apretón de manos del servidor. Por omisión, la extensión envía su propio nombre, versión y plataforma (es decir, versión PHP) en el apretón de manos. Las cadenas pueden ser especificadas para las claves `"name"`, `"version"` y `"platform"` de este array, y serán añadidas al campo respectivo(s) del apretón de manos del servidor. Nota: Las informaciones del apretón de manos están limitadas a 512 bytes. La extensión truncará los datos del apretón de manos para adaptarse a esta cadena de 512 bytes. Las bibliotecas de nivel superior están animadas a mantener sus propias metadatos concisas.
  serverApi | MongoDB\Driver\ServerApi | Esta opción se utiliza para declarar una versión de API de servidor para el Manager. Si se omite, no se declara ninguna versión de API.

  Las siguientes opciones son admitidas:

  Opciones para el cifrado automático
  Opción | Tipo | Descripción
  --- | --- | ---
  keyVaultClient | MongoDB\Driver\Manager | El Manager utilizado para enrutar las peticiones de claves de datos a un cluster MongoDB diferente. Por omisión, el Manager y cluster actual es utilizado.
  keyVaultNamespace | string | Un nombre de espacio completamente calificado (por ejemplo `"databaseName.collectionName"`) denotando la colección que contiene todas las claves de datos utilizadas para el cifrado y descifrado. Esta opción es requerida.
  kmsProviders | array | Un documento que contiene la configuración de uno o varios proveedores KMS, que se utilizan para cifrar las claves de datos. Los proveedores soportados son `"aws"`, `"azure"`, `"gcp"` y `"local"`, y al menos uno debe ser especificado. Si se especifica un documento vacío para `"aws"`, `"azure"`, o `"gcp"`, el controlador intentará configurar el proveedor utilizando » Automatic Credentials. El formato para `"aws"` es el siguiente:
      aws: {
          accessKeyId: <string>,
          secretAccessKey: <string>,
          sessionToken: <optional string>
      }
  El formato para `"azure"` es el siguiente:
      azure: {
          tenantId: <string>,
          clientId: <string>,
          clientSecret: <string>,
          identityPlatformEndpoint: <optional string> // Defaults to "login.microsoftonline.com"

      }
  El formato para `"gcp"` es el siguiente:
      gcp: {
          email: <string>,
          privateKey: <base64 string>|<MongoDB\BSON\Binary>,
          endpoint: <optional string> // Defaults to "oauth2.googleapis.com"

      }
  El formato para `"kmip"` es el siguiente:
      kmip: {
          endpoint: <string>
      }
  El formato para `"local"` es el siguiente:
      local: {
          // 96-byte master key used to encrypt/decrypt data keys
          key: <base64 string>|<MongoDB\BSON\Binary>
      }
  tlsOptions | array | Un documento que contiene la configuración TLS de uno o varios proveedores KMS. Los proveedores soportados son `"aws"`, `"azure"`, `"gcp"` y `"kmip"`. Todos los proveedores soportan las siguientes opciones:
      <provider>: {
          tlsCaFile: <optional string>,
          tlsCertificateKeyFile: <optional string>,
          tlsCertificateKeyFilePassword: <optional string>,
          tlsDisableOCSPEndpointCheck: <optional bool>
      }
  schemaMap | array|object | Mapea los espacios de nombres de colección a un esquema JSON local. Esto se utiliza para configurar el cifrado automático. Ver » Reglas de cifrado automático en el manual MongoDB para más información. Es un error especificar una colección tanto en `schemaMap` como en `encryptedFieldsMap`. Nota: Proporcionar un `schemaMap` proporciona más seguridad que confiar en los esquemas JSON obtenidos del servidor. Esto protege contra un servidor malintencionado anunciando un falso esquema JSON, que podría engañar al cliente para enviar datos no cifrados que deberían estar cifrados. Nota: Los esquemas proporcionados en el `schemaMap` solo se aplican a la configuración del cifrado automático para el cifrado del lado del cliente. Otras reglas de validación en el esquema JSON no serán aplicadas por el controlador y resultarán en un error.
  bypassAutoEncryption | bool | Si `true`, `mongocryptd` no será lanzado automáticamente. Esto se utiliza para desactivar el cifrado automático. Por omisión, `false`.
  bypassQueryAnalysis | bool | Si `true`, el análisis automático de las comandos salientes será desactivado y `mongocryptd` no será lanzado automáticamente. Esto permite el caso de uso del cifrado explícito para consultar campos indexados sin requerir la biblioteca `crypt_shared` bajo licencia empresarial o el proceso `mongocryptd`. Por omisión, `false`.
  encryptedFieldsMap | array|object | Mapea los espacios de nombres de colección a un documento `encryptedFields`. Esto se utiliza para configurar el cifrado consultable. Ver » Cifrado de campo y consultabilidad en el manual MongoDB para más información. Es un error especificar una colección tanto en `encryptedFieldsMap` como en `schemaMap`. Nota: Proporcionar un `encryptedFieldsMap` proporciona más seguridad que confiar en los `encryptedFields` obtenidos del servidor. Esto protege contra un servidor malintencionado anunciando un falso `encryptedFields`.
  extraOptions | array | El `extraOptions` se refieren al proceso `mongocryptd`. Las siguientes opciones son admitidas: `mongocryptdURI` (string): URI para conectarse a un proceso `mongocryptd` existente. Por omisión, `"mongodb://localhost:27020"`. `mongocryptdBypassSpawn` (bool): Si `true`, impide que el controlador lance `mongocryptd`. Por omisión, `false`. `mongocryptdSpawnPath` (string): Ruta absoluta para buscar el binario `mongocryptd`. Por omisión, una cadena vacía y consulta las rutas del sistema. `mongocryptdSpawnArgs` (array): Array de argumentos de cadena a pasar a `mongocryptd` al lanzarlo. Por omisión, `["--idleShutdownTimeoutSecs=60"]`. `cryptSharedLibPath` (string): Ruta absoluta hacia la biblioteca compartida `crypt_shared`. Por omisión, una cadena vacía y consulta las rutas del sistema. `cryptSharedLibRequired` (bool): Si `true`, exige que el controlador cargue `crypt_shared`. Por omisión, `false`. Ver la » Especificación de cifrado del lado del cliente para más información.

  > Nota: El cifrado automático es una funcionalidad empresarial que solo se aplica a las operaciones sobre una colección. El cifrado automático no es admitido para las operaciones sobre una base de datos o una vista, y las operaciones que no son sorteadas resultarán en un error. Para sortear el cifrado automático para todas las operaciones, establezca `bypassAutoEncryption=true` en `autoEncryption`. Para más información sobre las operaciones admitidas, ver la » Especificación de cifrado del lado del cliente.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si un parámetro es de tipo incorrecto

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | La opción de URI `"authMechanismProperties"` ha sido eliminada. Utilizar la propiedad `"CANONICALIZE_HOST_NAME"` de la opción de URI `"authMechanismProperties"` en su lugar. La opción de URI `"authMechanism"` ha sido eliminada. Utilizar la propiedad `"SERVICE_NAME"` de la opción de URI `"authMechanismProperties"` en su lugar. La opción de URI `"authSource"` ha sido eliminada. Utilizar las opciones de URI `"w"` y `"wTimeoutMS"` en su lugar. La opción de URI `"ssl"` ha sido eliminada. Utilizar la opción de URI `"tls"` en su lugar. La opción de controlador `"allow_invalid_hostname"` ha sido eliminada. Utilizar la opción de URI `"tlsAllowInvalidHostnames"` en su lugar. La opción de controlador `"ca_file"` ha sido eliminada. Utilizar la opción de URI `"tlsCAFile"` en su lugar. La opción de controlador `"context"` ha sido eliminada. Todas las opciones de contexto han sido deprecadas en favor de las diversas opciones de URI relacionadas con TLS. La opción de controlador `"pem_file"` ha sido eliminada. Utilizar la opción de URI `"tlsCertificateKeyFile"` en su lugar. La opción de controlador `"pem_pwd"` ha sido eliminada. Utilizar la opción de URI `"tlsCertificateKeyFilePassword"` en su lugar. La opción de controlador `"weak_cert_validation"` ha sido eliminada. Utilizar la opción de URI `"tlsAllowInvalidCertificates"` en su lugar.
PECL mongodb 1.16.0 | El proveedor AWS KMS para el cifrado del lado del cliente ahora acepta una opción `"sessionToken"`, que puede ser utilizada para autenticarse con credenciales AWS temporales. Añadido `"tlsDisableOCSPEndpointCheck"` al campo `"tlsOptions"` de la opción de controlador `"autoEncryption"`. Si se especifica un documento vacío para el proveedor KMS `"azure"` o `"gcp"`, el controlador intentará configurar el proveedor utilizando » las credenciales automáticas.
PECL mongodb 1.15.0 | Si se especifica un documento vacío para el proveedor KMS `"aws"`, el controlador intentará configurar el proveedor utilizando » las credenciales automáticas.
PECL mongodb 1.14.0 | Añadidas las opciones de cifrado del lado del cliente `"bypassQueryAnalysis"` y `"encryptedFieldsMap"`. Opciones adicionales relacionadas con `crypt_shared` son ahora admitidas en la opción de cifrado del lado del cliente `"extraOptions"`.
PECL mongodb 1.13.0 | Añadidas las opciones de URI `"srvMaxHosts"` y `"srvServiceName"`.
PECL mongodb 1.12.0 | KMIP es ahora admitido como proveedor KMS para el cifrado del lado del cliente y puede ser configurado en el campo `"kmsProviders"` de la opción de controlador `"autoEncryption"`. Además, las opciones TLS para los proveedores KMS pueden ahora ser configuradas en el campo `"tlsOptions"` de la opción de controlador `"autoEncryption"`.
PECL mongodb 1.11.0 | Añadida la opción de URI `"loadBalanced"`.
PECL mongodb 1.10.0 | Añadida la opción de controlador `"disableClientPersistence"`. Azure y GCP son ahora admitidos como proveedores KMS para el cifrado del lado del cliente y pueden ser configurados en el campo `"kmsProviders"` de la opción de controlador `"autoEncryption"`. Las cadenas codificadas en base64 son ahora aceptadas como alternativa a MongoDB\BSON\Binary para las opciones en `"kmsProviders"`.
PECL mongodb 1.8.0 | Añadidas las opciones de URI `"directConnection"`, `"tlsDisableCertificateRevocationCheck"` y `"tlsDisableOCSPEndpointCheck"`. Añadida la opción de controlador `"driver"`.
PECL mongodb 1.7.0 | Añadida la opción de controlador `"autoEncryption"`. Especificar cualquier opción SSL o TLS a través del parámetro `driverOptions` activará ahora implícitamente TLS, como ocurre con las opciones de URI correspondientes.
PECL mongodb 1.6.0 | Añadidas las opciones de URI `"retryReads"`, `"tls"`, `"tlsAllowInvalidCertificates"`, `"tlsAllowInvalidHostnames"`, `"tlsCAFile"`, `"tlsCertificateKeyFile"`, `"tlsCertificateKeyFilePassword"`, y `"tlsInsecure"`. La opción de URI `"retryWrites"` está ahora a `true` por omisión. Especificar una opción de URI SSL o TLS a través de la cadena de conexión o el parámetro `uriOptions` activará ahora implícitamente TLS a menos que `ssl` o `tls` sea `false`. TLS no es implícitamente activado para las opciones en el parámetro `driverOptions`, lo que es inalterado con respecto a las versiones anteriores.
PECL mongodb 1.5.0 | `"wtimeoutMS"` es ahora siempre validado y aplicado al write concern. Anteriormente, la opción era ignorada si `"w"` era <= 1, ya que el tiempo de espera solo se aplica a la replicación.
PECL mongodb 1.4.0 | Añadidas las opciones de URI `"compressors"`, `"retryWrites"`, y `"zlibCompressionLevel"`.
PECL mongodb 1.3.0 | El argumento `uriOptions` ahora acepta las opciones `"authMechanism"` y `"authMechanismProperties"`. Anteriormente, estas opciones solo eran admitidas en el argumento `uri`.
PECL mongodb 1.2.0 | El argumento `uri` es ahora opcional y por omisión `"mongodb://`. El puerto por omisión sigue siendo `27017`. Añadida la opción de URI `"appname"`. Añadidas las opciones de controlador `"allow_invalid_hostname"`, `"ca_file"`, `"ca_dir"`, `"clr_file"`, `"pem_file"`, `"pem_pwd"`, y `"weak_cert_validation"`. La API de flujos PHP ya no se utiliza para la comunicación por socket. La opción `"connectTimeoutMS"` de la URI es ahora por omisión 10 segundos en lugar de default_socket_timeout en versiones anteriores. Además, la extensión ya no admite todas las opciones de contexto SSL a través de la opción de controlador `"context"`.
PECL mongodb 1.1.0 | El argumento `uri` es ahora opcional y por omisión a `"mongodb://localhost:27017/"`.

### Ejemplos

Ejemplo #1 Ejemplos básicos MongoDB\Driver\Manager::__construct()

Conexión a un nodo MongoDB autónomo:

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://example.com:27017");

    ?>

Conexión a un nodo MongoDB autónomo a través de un socket de dominio Unix. La ruta del socket puede incluir caracteres especiales como barras diagonales y debe ser codificada con rawurlencode().

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://" . rawurlencode("/tmp/mongodb-27017.sock"));

    ?>

Conexión a un conjunto de réplicas:

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    ?>

Conexión a un clúster fragmentado (es decir, una o más instancias mongos):

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://mongos1.example.com,mongos2.example.com/");

    ?>

Conexión a MongoDB con credenciales de autenticación para un usuario y una base de datos específicos:

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://myusername:mypassword@example.com/?authSource=databaseName");

    ?>

Conexión a MongoDB con credenciales de autenticación para un usuario y una base de datos específicos, donde el nombre de usuario o la contraseña incluye caracteres especiales (por ejemplo `@`, `:`, `%`). En el ejemplo siguiente, la cadena de contraseña `myp@ss:w%rd` ha sido manualmente escapada; sin embargo, rawurlencode() también puede ser utilizada para escapar los componentes de la URI que pueden contener caracteres especiales.

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://myusername:myp%40ss%3Aw%25rd@example.com/?authSource=databaseName");

    ?>

Conexión a MongoDB con autenticación X509:

    <?php

    $manager = new MongoDB\Driver\Manager(
        "mongodb://example.com/?ssl=true&authMechanism=MONGODB-X509",
        [],
        [
            "pem_file" => "/path/to/client.pem",
        ]
    );
    ?>

### Ver también

- Manejo de la conexión y persistencia
- » Formato de cadena de conexión MongoDB

# MongoDB\Driver\Manager::createClientEncryption

(mongodb >=1.7.0)

MongoDB\Driver\Manager::createClientEncryption — Crear un nuevo objeto ClientEncryption

### Descripción

final public function MongoDB\Driver\Manager::createClientEncryption(array `$options`): MongoDB\Driver\ClientEncryption

Construye un nuevo objeto MongoDB\Driver\ClientEncryption con las opciones especificadas.

### Parámetros

`options`

  options
  Opción | Tipo | Descripción
  --- | --- | ---
  keyVaultClient | MongoDB\Driver\Manager | El Manager utilizado para enrutar las peticiones de claves de datos a un cluster MongoDB diferente. Por omisión, el Manager y cluster actual es utilizado.
  keyVaultNamespace | string | Un nombre de espacio completamente calificado (por ejemplo `"databaseName.collectionName"`) denotando la colección que contiene todas las claves de datos utilizadas para el cifrado y descifrado. Esta opción es requerida.
  kmsProviders | array | Un documento que contiene la configuración de uno o varios proveedores KMS, que se utilizan para cifrar las claves de datos. Los proveedores soportados son `"aws"`, `"azure"`, `"gcp"` y `"local"`, y al menos uno debe ser especificado. Si se especifica un documento vacío para `"aws"`, `"azure"`, o `"gcp"`, el controlador intentará configurar el proveedor utilizando » Automatic Credentials. El formato para `"aws"` es el siguiente:
      aws: {
          accessKeyId: <string>,
          secretAccessKey: <string>,
          sessionToken: <optional string>
      }
  El formato para `"azure"` es el siguiente:
      azure: {
          tenantId: <string>,
          clientId: <string>,
          clientSecret: <string>,
          identityPlatformEndpoint: <optional string> // Defaults to "login.microsoftonline.com"

      }
  El formato para `"gcp"` es el siguiente:
      gcp: {
          email: <string>,
          privateKey: <base64 string>|<MongoDB\BSON\Binary>,
          endpoint: <optional string> // Defaults to "oauth2.googleapis.com"

      }
  El formato para `"kmip"` es el siguiente:
      kmip: {
          endpoint: <string>
      }
  El formato para `"local"` es el siguiente:
      local: {
          // 96-byte master key used to encrypt/decrypt data keys
          key: <base64 string>|<MongoDB\BSON\Binary>
      }
  tlsOptions | array | Un documento que contiene la configuración TLS de uno o varios proveedores KMS. Los proveedores soportados son `"aws"`, `"azure"`, `"gcp"` y `"kmip"`. Todos los proveedores soportan las siguientes opciones:
      <provider>: {
          tlsCaFile: <optional string>,
          tlsCertificateKeyFile: <optional string>,
          tlsCertificateKeyFilePassword: <optional string>,
          tlsDisableOCSPEndpointCheck: <optional bool>
      }

### Valores devueltos

Devuelve una nueva instancia de MongoDB\Driver\ClientEncryption.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\Exception\RuntimeException si la extensión ha sido compilada sin el soporte de libmongocrypt

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.16.0 | El proveedor AWS KMS para el cifrado del lado del cliente acepta ahora una opción `"sessionToken"`, que puede ser utilizada para autenticarse con credenciales AWS temporales. Añadido `"tlsDisableOCSPEndpointCheck"` a la opción `"tlsOptions"`. Si se especifica un documento vacío para el proveedor KMS `"azure"` o `"gcp"`, el controlador intentará configurar el proveedor utilizando » Las credenciales automáticas.
PECL mongodb 1.15.0 | Si se especifica un documento vacío para el proveedor KMS `"aws"`, el controlador intentará configurar el proveedor utilizando » Las credenciales automáticas.
PECL mongodb 1.12.0 | KMIP es ahora soportado como proveedor KMS para el cifrado del lado del cliente y puede ser configurado en la opción `"kmsProviders"`. Añadida la opción `"tlsOptions"`.
PECL mongodb 1.10.0 | Azure y GCP son ahora soportados como proveedores KMS para el cifrado del lado del cliente y pueden ser configurados en la opción `"kmsProviders"`. Las cadenas codificadas en base64 son ahora aceptadas como alternativa a MongoDB\BSON\Binary para las opciones en `"kmsProviders"`.

### Ver también

- MongoDB\Driver\ClientEncryption::__construct() - Crea un nuevo objeto ClientEncryption
- » Cifrado del lado del cliente explícito (manual) en el manual de MongoDB

# MongoDB\Driver\Manager::executeBulkWrite

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeBulkWrite — Ejecuta una o varias operaciones de escritura

### Descripción

final public function MongoDB\Driver\Manager::executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$options` = `null`): MongoDB\Driver\WriteResult

Ejecuta una o varias operaciones de escritura en el servidor primario.

Un MongoDB\Driver\BulkWrite puede ser construido con una o varias operaciones de escritura de tipos variados (por ejemplo, actualizaciones, eliminaciones e inserciones). El controlador intentará enviar las operaciones del mismo tipo al servidor en el menor número de solicitudes posible para optimizar los intercambios.

El valor por omisión de la opción `"writeConcern"` será deducido a partir de una transacción activa (indicada por la opción `"session"`), seguida de la URI de conexión.

### Parámetros

`namespace` (string)
  Un espacio de nombres completamente calificado (ej. `"databaseName.collectionName"`)
`bulk` (MongoDB\Driver\BulkWrite)
  Escritura(s) a ejecutar.
`options`

  options
  Opción | Tipo | Descripción
  --- | --- | ---
  session | MongoDB\Driver\Session | Una sesión a asociar a la operación.
  writeConcern | MongoDB\Driver\WriteConcern | Una preocupación de escritura a aplicar a la operación.

### Valores devueltos

Retorna un MongoDB\Driver\WriteResult en caso de éxito.

### Errores/Excepciones

- Lanza una MongoDB\Driver\Exception\InvalidArgumentException si `bulk` no contiene ninguna operación de escritura.
- Lanza una MongoDB\Driver\Exception\InvalidArgumentException si `bulk` ya ha sido ejecutado. Los objetos MongoDB\Driver\BulkWrite no pueden ser ejecutados varias veces.
- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si la opción `"session"` se utiliza junto con una preocupación de escritura no reconocida.
- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza una excepción MongoDB\Driver\BulkWriteException en caso de error de una operación de escritura (un error WriteError y WriteConcern)
- Lanza una MongoDB\Driver\Exception\RuntimeException en caso de otros errores.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | El parámetro `options` ya no acepta una instancia de MongoDB\Driver\WriteConcern.
PECL mongodb 1.21.0 | Pasar un objeto MongoDB\Driver\WriteConcern como `options` está obsoleto y será eliminado en la versión 2.0.
PECL mongodb 1.4.4 | Se lanzará una MongoDB\Driver\Exception\InvalidArgumentException si la opción `"session"` se utiliza en combinación con un `"writeConcern"` no-acknowledged.
PECL mongodb 1.4.0 | El tercer parámetro es ahora un array de `options`. Por razones de compatibilidad ascendente, este parámetro siempre aceptará un objeto MongoDB\Driver\WriteConcern.
PECL mongodb 1.3.0 | Se lanza una MongoDB\Driver\Exception\InvalidArgumentException si `bulk` no contiene ninguna operación de escritura. Anteriormente, se lanzaba una MongoDB\Driver\Exception\BulkWriteException.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\Manager::executeBulkWrite()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite();

    $bulk->insert(['_id' => 1, 'x' => 1]);
    $bulk->insert(['_id' => 2, 'x' => 2]);

    $bulk->update(['x' => 2], ['$set' => ['x' => 1]], ['multi' => false, 'upsert' => false]);
    $bulk->update(['x' => 3], ['$set' => ['x' => 3]], ['multi' => false, 'upsert' => true]);
    $bulk->update(['_id' => 3], ['$set' => ['x' => 3]], ['multi' => false, 'upsert' => true]);

    $bulk->insert(['_id' => 4, 'x' => 2]);

    $bulk->delete(['x' => 1], ['limit' => 1]);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $writeConcern = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 100);
    $result = $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);

    printf("Inserted %d document(s)\n", $result->getInsertedCount());
    printf("Matched  %d document(s)\n", $result->getMatchedCount());
    printf("Updated  %d document(s)\n", $result->getModifiedCount());
    printf("Upserted %d document(s)\n", $result->getUpsertedCount());
    printf("Deleted  %d document(s)\n", $result->getDeletedCount());

    foreach ($result->getUpsertedIds() as $index => $id) {
        printf('upsertedId[%d]: ', $index);
        var_dump($id);
    }

    /* Si el WriteConcern no ha podido ser satisfecho */
    if ($writeConcernError = $result->getWriteConcernError()) {
        printf("%s (%d): %s\n", $writeConcernError->getMessage(), $writeConcernError->getCode(), var_export($writeConcernError->getInfo(), true));
    }

    /* Si una escritura no ha podido hacerse en absoluto */
    foreach ($result->getWriteErrors() as $writeError) {
        printf("Operation#%d: %s (%d)\n", $writeError->getIndex(), $writeError->getMessage(), $writeError->getCode());
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Inserted 3 document(s)
    Matched  1 document(s)
    Updated  1 document(s)
    Upserted 2 document(s)
    Deleted  1 document(s)
    upsertedId[3]: object(MongoDB\BSON\ObjectId)#5 (1) {
      ["oid"]=>
      string(24) "54d3adc3ce7a792f4d703756"
    }
    upsertedId[4]: int(3)

### Ver también

- MongoDB\Driver\BulkWrite
- MongoDB\Driver\WriteResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Server::executeBulkWrite() - Ejecuta una o varias operaciones de escritura en este servidor

# MongoDB\Driver\Manager::executeBulkWriteCommand

(mongodb >=2.1.0)

MongoDB\Driver\Manager::executeBulkWriteCommand — Ejecuta operaciones de escritura utilizando el comando bulkWrite

### Descripción

final public function MongoDB\Driver\Manager::executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult

Ejecuta una o varias operaciones de escritura en el servidor primario utilizando el comando » bulkWrite introducido en MongoDB 8.0.

Una MongoDB\Driver\BulkWriteCommand puede ser construida con una o varias operaciones de escritura de tipos variados (por ejemplo, inserciones, actualizaciones y eliminaciones). Cada operación de escritura puede apuntar a una colección diferente.

El valor por omisión para la opción `"writeConcern"` será deducido de una transacción activa (indicada por la opción `"session"`), seguida por la URI de conexión.

### Parámetros

`bulk` (MongoDB\Driver\BulkWriteCommand)
  Escritura(s) a ejecutar.
`options`

  options
  Opción | Tipo | Descripción
  --- | --- | ---
  session | MongoDB\Driver\Session | Una sesión a asociar a la operación.
  writeConcern | MongoDB\Driver\WriteConcern | Una preocupación de escritura a aplicar a la operación.

### Valores devueltos

Retorna un MongoDB\Driver\BulkWriteCommandResult en caso de éxito.

### Errores/Excepciones

- Lanza una MongoDB\Driver\Exception\InvalidArgumentException si `bulk` no contiene operaciones de escritura válidas.
- Lanza una MongoDB\Driver\Exception\InvalidArgumentException si `bulk` ya ha sido ejecutada. Los objetos MongoDB\Driver\BulkWriteCommand no pueden ser ejecutados múltiples veces.
- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si la opción `"session"` se utiliza junto con una preocupación de escritura no reconocida.
- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza una excepción MongoDB\Driver\Exception\BulkWriteCommandException en caso de error de escritura (por ejemplo, fallo de comando, error de escritura o preocupación de escritura)
- Lanza MongoDB\Driver\Exception\RuntimeException en caso de otro error.

### Ejemplos

Ejemplo #1 Operaciones de escritura mixtas

Las operaciones de escritura mixtas (por ejemplo, inserción, actualización y eliminación) serán enviadas al servidor utilizando una sola comando » bulkWrite

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    // Elimina documentos de dos colecciones
    $bulk->deleteMany('db.coll_one', []);
    $bulk->deleteMany('db.coll_two', []);

    // Añade documentos a dos colecciones
    $bulk->insertOne('db.coll_one', ['_id' => 1]);
    $bulk->insertOne('db.coll_two', ['_id' => 2]);
    $bulk->insertOne('db.coll_two', ['_id' => 3]);

    // Actualiza un documento en "coll_one"
    $bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    printf("Insertados %d documento(s)\n", $result->getInsertedCount());
    printf("Actualizados %d documento(s)\n", $result->getModifiedCount());

    ?>

El ejemplo anterior mostrará:

    Insertados 3 documento(s)
    Actualizados 1 documento(s)

Ejemplo #2 Operación de escritura ordenada que provoca un error

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 2]);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 3]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();

        var_dump($e->getWriteErrors());
    }

    printf("Insertados %d documento(s)\n", $result->getInsertedCount());

    ?>

Resultado del ejemplo anterior es similar a:

    array(1) {
      [3]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(3)
        ["info"]=>
        object(stdClass)#6 (0) {
        }
      }
    }
    Insertados 2 documento(s)

### Ver también

- MongoDB\Driver\BulkWriteCommand
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Server::executeBulkWriteCommand() - Ejecuta operaciones de escritura en este servidor utilizando el comando bulkWrite

# MongoDB\Driver\Manager::executeCommand

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeCommand — Ejecuta un comando de base de datos

### Descripción

final public function MongoDB\Driver\Manager::executeCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Selecciona un servidor en función de la opción `"readPreference"` y ejecuta el comando en ese servidor.

Este método no aplica ninguna lógica especial al comando. Los valores por defecto de las opciones `"readPreference"`, `"readConcern"` y `"writeConcern"` serán deducidos a partir de una transacción activa (indicada por la opción `"session"`). Si no hay una transacción activa, se utilizará una preferencia de lectura primaria para la selección del servidor.

Los valores por defecto no serán no deducidos a partir de la URI de conexión. Por lo tanto, se recomienda a los usuarios utilizar métodos de comando de lectura y/o escritura específicos si es posible.

### Parámetros

`db` (string)
  El nombre de la base de datos sobre la cual se ejecutará el comando.
`command` (MongoDB\Driver\Command)
  El comando a ejecutar.
`options`

  options
  Opción | Tipo | Descripción
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Una preocupación de lectura a aplicar a la operación. Esta opción está disponible en MongoDB 3.2+ y se traducirá en una excepción en el momento de la ejecución si se especifica para una versión más antigua del servidor.
  readPreference | MongoDB\Driver\ReadPreference | Una preferencia de lectura a utilizar para seleccionar un servidor para la operación.
  session | MongoDB\Driver\Session | Una sesión a asociar a la operación.
  writeConcern | MongoDB\Driver\WriteConcern | Una preocupación de escritura a aplicar a la operación.

  Advertencia

  Si se utiliza una `"session"` que tiene una transacción en curso, no se puede especificar la opción `"readConcern"` o `"writeConcern"`. Intentar hacer esto lanzará una excepción MongoDB\Driver\Exception\InvalidArgumentException. En su lugar, debe definir estas opciones cuando se crea la transacción con MongoDB\Driver\Session::startTransaction().

### Valores devueltos

Retorna un MongoDB\Driver\Cursor en caso de éxito.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si la opción `"session"` se utiliza con una transacción asociada en combinación con una opción `"readConcern"` o `"writeConcern"`.
- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si la opción `"session"` se utiliza junto con una preocupación de escritura no reconocida.
- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza una MongoDB\Driver\Exception\RuntimeException en otros errores (por ejemplo: comando inválido, entrega de un comando de escritura a un secundario).

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | El parámetro `options` ya no acepta una instancia de MongoDB\Driver\ReadPreference.
PECL mongodb 1.21.0 | Pasar un objeto MongoDB\Driver\ReadPreference como `options` está obsoleto y será eliminado en la 2.0.
PECL mongodb 1.4.4 | Se lanzará una MongoDB\Driver\Exception\InvalidArgumentException si la opción `"session"` se utiliza en combinación con una preferencia de escritura no reconocida.
PECL mongodb 1.4.0 | Este tercer parámetro es ahora un array de `options`. Por razones de compatibilidad ascendente, este parámetro siempre aceptará un objeto MongoDB\Driver\ReadPreference.

### Ejemplos

Ejemplo #1 MongoDB\Driver\Manager::executeCommand() con un comando que devuelve un solo documento de resultado

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $command = new MongoDB\Driver\Command(['ping' => 1]);

    try {
        $cursor = $manager->executeCommand('admin', $command);
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }

    /* El comando ping devuelve un solo documento de resultado, por lo que
     * se debe acceder al primer resultado en el cursor. */
    $response = $cursor->toArray()[0];

    var_dump($response);

    ?>

El ejemplo anterior mostrará:

    array(1) {
      ["ok"]=>
      float(1)
    }

Ejemplo #2 MongoDB\Driver\Manager::executeCommand() con un comando que devuelve un cursor

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1, 'y' => 'foo']);
    $bulk->insert(['x' => 2, 'y' => 'bar']);
    $bulk->insert(['x' => 3, 'y' => 'bar']);
    $manager->executeBulkWrite('db.collection', $bulk);

    $command = new MongoDB\Driver\Command([
        'aggregate' => 'collection',
        'pipeline' => [
            ['$group' => ['_id' => '$y', 'sum' => ['$sum' => '$x']]],
        ],
        'cursor' => new stdClass,
    ]);
    $cursor = $manager->executeCommand('db', $command);

    /* El comando de agregación puede eventualmente devolver sus resultados en
     * un cursor en lugar de un solo documento de resultado. En este caso, se puede
     * iterar directamente sobre el cursor para acceder a estos resultados. */
    foreach ($cursor as $document) {
        var_dump($document);
    }

    ?>

El ejemplo anterior mostrará:

    object(stdClass)#6 (2) {
      ["_id"]=>
      string(3) "bar"
      ["sum"]=>
      int(10)
    }
    object(stdClass)#7 (2) {
      ["_id"]=>
      string(3) "foo"
      ["sum"]=>
      int(2)
    }

Ejemplo #3 Limitar el tiempo de ejecución de un comando

El tiempo de ejecución de un comando puede ser limitado especificando un valor para `"maxTimeMS"` en el documento MongoDB\Driver\Command. Tenga en cuenta que este límite de tiempo se aplica en el lado del servidor y no tiene en cuenta la latencia de la red. Ver » Terminar las operaciones en curso en el manual de MongoDB para más información.

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');

    $command = new MongoDB\Driver\Command([
        'count' => 'collection',
        'query' => ['x' => ['$gt' => 1]],
        'maxTimeMS' => 1000,
    ]);

    $cursor = $manager->executeCommand('db', $command);

    var_dump($cursor->toArray()[0]);

    ?>

Si el comando no logra completarse después de un segundo de ejecución en el servidor, se lanzará una MongoDB\Driver\Exception\ExecutionTimeoutException.

### Notas

> Nota: Si se utiliza una segunda `readPreference`, es responsabilidad del llamante asegurarse de que el `comando` pueda ser ejecutado en un secundario. No se realiza ninguna validación por parte del controlador.

> Nota: Este método no utiliza por defecto la preferencia de lectura de la URI de conexión MongoDB. Las aplicaciones que lo necesiten deberían considerar el uso de MongoDB\Driver\Manager::executeReadCommand().

### Ver también

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Manager::executeReadCommand() - Ejecuta un comando de base de datos que lee
- MongoDB\Driver\Manager::executeReadWriteCommand() - Ejecuta un comando de base de datos que lee y escribe
- MongoDB\Driver\Manager::executeWriteCommand() - Ejecuta un comando de base de datos que escribe
- MongoDB\Driver\Server::executeCommand() - Ejecuta un comando de base de datos en este servidor

# MongoDB\Driver\Manager::executeQuery

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeQuery — Ejecuta una consulta de base de datos

### Descripción

final public function MongoDB\Driver\Manager::executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Selecciona un servidor en función de la opción `"readPreference"` y ejecuta la consulta en ese servidor.

Los valores por omisión de la opción `"readPreference"` y de la opción `"readConcern"` de la consulta serán deducidos a partir de una transacción activa (indicada por la opción `"session"`), seguida de la URI de conexión.

### Parámetros

`namespace` (string)
  Un espacio de nombres completamente calificado (ej. `"databaseName.collectionName"`)
`query` (MongoDB\Driver\Query)
  La consulta a ejecutar.
`options`

  options
  Opción | Tipo | Descripción
  --- | --- | ---
  readPreference | MongoDB\Driver\ReadPreference | Una preferencia de lectura a utilizar para seleccionar un servidor para la operación.
  session | MongoDB\Driver\Session | Una sesión a asociar a la operación.

### Valores devueltos

Retorna un MongoDB\Driver\Cursor en caso de éxito.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza una MongoDB\Driver\Exception\RuntimeException en caso de otro error (por ejemplo: operadores de consulta inválidos).

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | El parámetro `options` ya no acepta una instancia de MongoDB\Driver\ReadPreference.
PECL mongodb 1.21.0 | Pasar un objeto MongoDB\Driver\ReadPreference como `options` está obsoleto y será eliminado en la 2.0.
PECL mongodb 1.4.0 | El tercer parámetro es ahora un array `options`. Por razones de compatibilidad ascendente, este parámetro siempre aceptará un objeto MongoDB\Driver\ReadPreference.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\Manager::executeQuery()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $filter = ['x' => ['$gt' => 1]];
    $options = [
        'projection' => ['_id' => 0],
        'sort' => ['x' => -1],
    ];

    $query = new MongoDB\Driver\Query($filter, $options);
    $cursor = $manager->executeQuery('db.collection', $query);

    foreach ($cursor as $document) {
        var_dump($document);
    }

    ?>

El ejemplo anterior mostrará:

    object(stdClass)#6 (1) {
      ["x"]=>
      int(3)
    }
    object(stdClass)#7 (1) {
      ["x"]=>
      int(2)
    }

Ejemplo #2 Limitar el tiempo de ejecución de una consulta

La opción `"maxTimeMS"` de la clase MongoDB\Driver\Query puede ser utilizada para limitar el tiempo de ejecución de una consulta. Tenga en cuenta que este límite de tiempo es aplicado en el lado del servidor y no tiene en cuenta la latencia de la red. Ver » Terminar las operaciones en curso en el manual de MongoDB para más información.

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');

    $filter = ['x' => ['$gt' => 1]];
    $options = [
        'maxTimeMS' => 1000,
    ];

    $query = new MongoDB\Driver\Query($filter, $options);
    $cursor = $manager->executeQuery('db.collection', $query);

    foreach ($cursor as $document) {
        var_dump($document);
    }

    ?>

Si la consulta no logra terminar después de un segundo de ejecución en el servidor, una MongoDB\Driver\Exception\ExecutionTimeoutException será lanzada.

### Ver también

- MongoDB\Driver\Cursor
- MongoDB\Driver\Query
- MongoDB\Driver\ReadPreference
- MongoDB\Driver\Server::executeQuery() - Ejecuta una consulta de base de datos en este servidor

# MongoDB\Driver\Manager::executeReadCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeReadCommand — Ejecuta un comando de base de datos que lee

### Descripción

final public function MongoDB\Driver\Manager::executeReadCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Selecciona un servidor en función de la opción `"readPreference"` y ejecuta el comando en este servidor.

Este método aplicará una lógica específica a los comandos que leen (por ejemplo » distinct). Los valores por omisión de las opciones `"readPreference"` y `"readConcern"` serán deducidos a partir de una transacción activa (indicada por la opción `"session"`), seguida de la URI de conexión.

### Parámetros

`db` (string)
  El nombre de la base de datos sobre la cual se ejecutará el comando.
`command` (MongoDB\Driver\Command)
  El comando a ejecutar.
`options`

  options
  Opción | Tipo | Descripción
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Una preocupación de lectura a aplicar a la operación. Esta opción está disponible en MongoDB 3.2+ y se traducirá en una excepción en el momento de la ejecución si se especifica para una versión más antigua del servidor.
  readPreference | MongoDB\Driver\ReadPreference | Una preferencia de lectura a utilizar para seleccionar un servidor para la operación.
  session | MongoDB\Driver\Session | Una sesión a asociar a la operación.

  Advertencia

  Si se utiliza una `"session"` que tiene una transacción en curso, no se puede especificar la opción `"readConcern"` o `"writeConcern"`. Intentar hacer esto lanzará una excepción MongoDB\Driver\Exception\InvalidArgumentException. En su lugar, debe definir estas opciones cuando se crea la transacción con MongoDB\Driver\Session::startTransaction().

### Valores devueltos

Retorna un MongoDB\Driver\Cursor en caso de éxito.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si la opción `"session"` se utiliza con una transacción asociada en combinación con una opción `"readConcern"` o `"writeConcern"`.
- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza una MongoDB\Driver\Exception\RuntimeException en caso de otros errores (por ejemplo: comando inválido).

### Ver también

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Manager::executeCommand() - Ejecuta un comando de base de datos
- MongoDB\Driver\Manager::executeReadWriteCommand() - Ejecuta un comando de base de datos que lee y escribe
- MongoDB\Driver\Manager::executeWriteCommand() - Ejecuta un comando de base de datos que escribe
- MongoDB\Driver\Server::executeReadCommand() - Ejecuta un comando de base de datos que lee en este servidor

# MongoDB\Driver\Manager::executeReadWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeReadWriteCommand — Ejecuta un comando de base de datos que lee y escribe

### Descripción

final public function MongoDB\Driver\Manager::executeReadWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Ejecuta un comando en el servidor primario.

Este método aplicará una lógica específica a los comandos que leen y escriben (por ejemplo » aggregate). Los valores por omisión de las opciones `"readConcern"` y `"writeConcern"` serán deducidos a partir de una transacción activa (indicada por la opción `"session"`), seguida de la URI de conexión.

### Parámetros

`db` (string)
  El nombre de la base de datos sobre la cual se ejecutará el comando.
`command` (MongoDB\Driver\Command)
  El comando a ejecutar.
`options`

  options
  Opción | Tipo | Descripción
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Una preocupación de lectura a aplicar a la operación. Esta opción está disponible en MongoDB 3.2+ y se traducirá en una excepción en el momento de la ejecución si se especifica para una versión más antigua del servidor.
  session | MongoDB\Driver\Session | Una sesión a asociar a la operación.
  writeConcern | MongoDB\Driver\WriteConcern | Una preocupación de escritura a aplicar a la operación.

  Advertencia

  Si se utiliza una `"session"` que tiene una transacción en curso, no se puede especificar la opción `"readConcern"` o `"writeConcern"`. Intentar hacer esto lanzará una excepción MongoDB\Driver\Exception\InvalidArgumentException. En su lugar, debe definir estas opciones cuando se crea la transacción con MongoDB\Driver\Session::startTransaction().

### Valores devueltos

Retorna un MongoDB\Driver\Cursor en caso de éxito.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si la opción `"session"` se utiliza con una transacción asociada en combinación con una opción `"readConcern"` o `"writeConcern"`.
- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si la opción `"session"` se utiliza junto con una preocupación de escritura no reconocida.
- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza una MongoDB\Driver\Exception\RuntimeException en caso de otros errores (por ejemplo: comando inválido).

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.4.4 | Una MongoDB\Driver\Exception\InvalidArgumentException será lanzada si la opción `"session"` es utilizada en combinación con un criterio de lectura o escritura no reconocido.

### Ver también

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Manager::executeCommand() - Ejecuta un comando de base de datos
- MongoDB\Driver\Manager::executeReadCommand() - Ejecuta un comando de base de datos que lee
- MongoDB\Driver\Manager::executeWriteCommand() - Ejecuta un comando de base de datos que escribe
- MongoDB\Driver\Server::executeReadWriteCommand() - Ejecuta un comando de base de datos que lee y escribe en este servidor

# MongoDB\Driver\Manager::executeWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeWriteCommand — Ejecuta un comando de base de datos que escribe

### Descripción

final public function MongoDB\Driver\Manager::executeWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Ejecuta el comando en el servidor primario.

Este método aplicará una lógica específica a los comandos que escriben (por ejemplo » drop). Los valores por omisión de la opción `"writeConcern"` serán deducidos a partir de una transacción activa (indicada por la opción `"session"`), seguida de la URI de conexión.

> Nota: Este método no está destinado a ser utilizado para ejecutar » insert, » update, o » delete. Se recomienda a los usuarios utilizar MongoDB\Driver\Manager::executeBulkWrite() para estas operaciones.

### Parámetros

`db` (string)
  El nombre de la base de datos sobre la cual se ejecutará el comando.
`command` (MongoDB\Driver\Command)
  El comando a ejecutar.
`options`

  options
  Opción | Tipo | Descripción
  --- | --- | ---
  session | MongoDB\Driver\Session | Una sesión a asociar a la operación.
  writeConcern | MongoDB\Driver\WriteConcern | Una preocupación de escritura a aplicar a la operación.

  Advertencia

  Si se utiliza una `"session"` que tiene una transacción en curso, no se puede especificar la opción `"readConcern"` o `"writeConcern"`. Intentar hacer esto lanzará una excepción MongoDB\Driver\Exception\InvalidArgumentException. En su lugar, debe definir estas opciones cuando se crea la transacción con MongoDB\Driver\Session::startTransaction().

### Valores devueltos

Retorna un MongoDB\Driver\Cursor en caso de éxito.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si la opción `"session"` se utiliza con una transacción asociada en combinación con una opción `"readConcern"` o `"writeConcern"`.
- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si la opción `"session"` se utiliza junto con una preocupación de escritura no reconocida.
- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza una MongoDB\Driver\Exception\RuntimeException en caso de otros errores (por ejemplo: comando inválido).

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.4.4 | Una MongoDB\Driver\Exception\InvalidArgumentException será lanzada si la opción `"session"` es utilizada en combinación con un `"writeConcern"` no reconocido.

### Ver también

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Manager::executeCommand() - Ejecuta un comando de base de datos
- MongoDB\Driver\Manager::executeReadCommand() - Ejecuta un comando de base de datos que lee
- MongoDB\Driver\Manager::executeReadWriteCommand() - Ejecuta un comando de base de datos que lee y escribe
- MongoDB\Driver\Server::executeWriteCommand() - Ejecuta un comando de base de datos que escribe en este servidor

# MongoDB\Driver\Manager::getEncryptedFieldsMap

(mongodb >=1.14.0)

MongoDB\Driver\Manager::getEncryptedFieldsMap — Devuelve la opción de cifrado automático encryptedFieldsMap para el Manager

### Descripción

final public function MongoDB\Driver\Manager::getEncryptedFieldsMap(): array|object|null

Devuelve la opción de cifrado automático `encryptedFieldsMap` para el Manager, si se ha especificado.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

La opción de cifrado automático `encryptedFieldsMap` para el Manager, o `null` si no se ha especificado.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Manager::__construct() - Crea un nuevo Manager MongoDB

# MongoDB\Driver\Manager::getReadConcern

(mongodb >=1.1.0)

MongoDB\Driver\Manager::getReadConcern — Devuelve el ReadConcern para el Manager

### Descripción

final public function MongoDB\Driver\Manager::getReadConcern(): MongoDB\Driver\ReadConcern

Devuelve el MongoDB\Driver\ReadConcern para el Manager, que se deriva de sus opciones URI. Es el ReadConcern por omisión para las peticiones y comandos ejecutados en el Manager.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El MongoDB\Driver\ReadConcern para el Manager.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo MongoDB\Driver\Manager::getReadConcern()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    var_dump($manager->getReadConcern());

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/?readConcernLevel=local');
    var_dump($manager->getReadConcern());

    ?>

Resultado del ejemplo anterior es similar a:

    object(MongoDB\Driver\ReadConcern)#2 (0) {
    }
    object(MongoDB\Driver\ReadConcern)#1 (1) {
      ["level"]=>
      string(5) "local"
    }

### Ver también

- MongoDB\Driver\ReadConcern
- MongoDB\Driver\Manager::__construct() - Crea un nuevo Manager MongoDB

# MongoDB\Driver\Manager::getReadPreference

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getReadPreference — Devuelve el ReadPreference para el Manager

### Descripción

final public function MongoDB\Driver\Manager::getReadPreference(): MongoDB\Driver\ReadPreference

Devuelve el MongoDB\Driver\ReadPreference para el Manager, que se deriva de sus opciones URI. Es el ReadPreference por omisión para las peticiones y comandos ejecutados en el Manager.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El MongoDB\Driver\ReadPreference para el Manager.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\Manager::getReadPreference()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    var_dump($manager->getReadPreference());

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/?readPreference=secondaryPreferred&readPreferenceTags=dc:ny,rack:1&readPreferenceTags=dc:ny&readPreferenceTags=');
    var_dump($manager->getReadPreference());

    ?>

Resultado del ejemplo anterior es similar a:

    object(MongoDB\Driver\ReadPreference)#2 (1) {
      ["mode"]=>
      string(7) "primary"
    }
    object(MongoDB\Driver\ReadPreference)#1 (2) {
      ["mode"]=>
      string(18) "secondaryPreferred"
      ["tags"]=>
      array(3) {
        [0]=>
        object(stdClass)#3 (2) {
          ["dc"]=>
          string(2) "ny"
          ["rack"]=>
          string(1) "1"
        }
        [1]=>
        object(stdClass)#4 (1) {
          ["dc"]=>
          string(2) "ny"
        }
        [2]=>
        object(stdClass)#5 (0) {
        }
      }
    }

### Ver también

- MongoDB\Driver\ReadPreference
- MongoDB\Driver\Manager::__construct() - Crea un nuevo Manager MongoDB

# MongoDB\Driver\Manager::getServers

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getServers — Devolver los servidores a los que está conectado este gestor

### Descripción

final public function MongoDB\Driver\Manager::getServers(): array

Devuelve un array de instancias MongoDB\Driver\Server a las que está conectado este gestor.

> Nota: Dado que el controlador se conecta perezosamente a la base de datos, este método puede devolver un array vacío si se llama antes de ejecutar una operación en el MongoDB\Driver\Manager.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array de instancias MongoDB\Driver\Server a las que está conectado este gestor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\Driver\Manager::getServers()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    /* El controlador se conecta al servidor de la base de datos de manera perezosa, por lo que Manager::getServers()
     * puede devolver inicialmente un array vacío. */
    var_dump($manager->getServers());

    $command = new MongoDB\Driver\Command(['ping' => 1]);
    $manager->executeCommand('db', $command);

    var_dump($manager->getServers());

    ?>

Resultado del ejemplo anterior es similar a:

    array(0) {
    }
    array(1) {
      [0]=>
      object(MongoDB\Driver\Server)#3 (10) {
        ["host"]=>
        string(9) "localhost"
        ["port"]=>
        int(27017)
        ["type"]=>
        int(1)
        ["is_primary"]=>
        bool(false)
        ["is_secondary"]=>
        bool(false)
        ["is_arbiter"]=>
        bool(false)
        ["is_hidden"]=>
        bool(false)
        ["is_passive"]=>
        bool(false)
        ["last_hello_response"]=>
        array(8) {
          ["isWritablePrimary"]=>
          bool(true)
          ["maxBsonObjectSize"]=>
          int(16777216)
          ["maxMessageSizeBytes"]=>
          int(48000000)
          ["maxWriteBatchSize"]=>
          int(1000)
          ["localTime"]=>
          object(MongoDB\BSON\UTCDateTime)#4 (1) {
            ["milliseconds"]=>
            int(1447267964517)
          }
          ["maxWireVersion"]=>
          int(3)
          ["minWireVersion"]=>
          int(0)
          ["ok"]=>
          float(1)
        }
        ["round_trip_time"]=>
        int(554)
      }
    }

### Ver también

- MongoDB\Driver\Server
- MongoDB\Driver\Manager::selectServer() - Selecciona un servidor correspondiente a una preferencia de lectura

# MongoDB\Driver\Manager::getWriteConcern

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getWriteConcern — Devuelve el WriteConcern para el Manager

### Descripción

final public function MongoDB\Driver\Manager::getWriteConcern(): MongoDB\Driver\WriteConcern

Devuelve el MongoDB\Driver\WriteConcern para el Manager, que se deriva de sus opciones URI. Es el WriteConcern por omisión para las escrituras y comandos ejecutados en el Manager.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El MongoDB\Driver\WriteConcern para el Manager.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\Manager::getWriteConcern()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    var_dump($manager->getWriteConcern());

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/?w=majority&wtimeoutMS=2000');
    var_dump($manager->getWriteConcern());

    ?>

Resultado del ejemplo anterior es similar a:

    object(MongoDB\Driver\WriteConcern)#2 (0) {
    }
    object(MongoDB\Driver\WriteConcern)#1 (2) {
      ["w"]=>
      string(8) "majority"
      ["wtimeout"]=>
      int(2000)
    }

### Ver también

- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Manager::__construct() - Crea un nuevo Manager MongoDB

# MongoDB\Driver\Manager::removeSubscriber

(mongodb >=1.10.0)

MongoDB\Driver\Manager::removeSubscriber — Elimina un observador de eventos de supervisión de este Manager

### Descripción

final public function MongoDB\Driver\Manager::removeSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void

Elimina un observador de eventos de supervisión de este Manager.

> Nota: Si `subscriber` no está ya registrado con este Manager, esta función no hace nada.

### Parámetros

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  Un observador de eventos de supervisión a eliminar de este Manager.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Manager::addSubscriber() - Registra un observador de eventos de monitoreo con este manager
- MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Monitoring\removeSubscriber() - Deregistra un suscriptor de eventos de supervisión globalmente
- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

# MongoDB\Driver\Manager::selectServer

(mongodb >=1.0.0)

MongoDB\Driver\Manager::selectServer — Selecciona un servidor correspondiente a una preferencia de lectura

### Descripción

final public function MongoDB\Driver\Manager::selectServer(?MongoDB\Driver\ReadPreference `$readPreference` = `null`): MongoDB\Driver\Server

Selecciona un MongoDB\Driver\Server correspondiente a `readPreference`. Si `readPreference` es `null` o se omite, el servidor primario será seleccionado por omisión. Esto puede ser utilizado para preseleccionar un servidor a fin de realizar una verificación de versión antes de ejecutar una operación.

> Nota: A diferencia de MongoDB\Driver\Manager::getServers(), este método inicializará las conexiones de base de datos y realizará el descubrimiento de servidores si es necesario. Ver la » Especificación de selección de servidor para más información.

### Parámetros

`readPreference` (MongoDB\Driver\ReadPreference)
  Las preferencias de lectura a utilizar para seleccionar un servidor. Si `null` o se omite, el servidor primario será seleccionado por omisión.

### Valores devueltos

Devuelve un MongoDB\Driver\Server correspondiente a la preferencia de lectura.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza una MongoDB\Driver\Exception\RuntimeException si un servidor correspondiente a la preferencia de lectura no ha podido ser encontrado.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.11.0 | El `readPreference` es ahora opcional. Si `null` o se omite, el servidor primario será seleccionado por omisión.

### Ver también

- MongoDB\Driver\Server
- MongoDB\Driver\Manager::getServers() - Devolver los servidores a los que está conectado este gestor
- » Especificación de selección de servidor

# MongoDB\Driver\Manager::startSession

(mongodb >=1.4.0)

MongoDB\Driver\Manager::startSession — Inicia una nueva sesión de cliente para ser utilizada con este cliente

### Descripción

final public function MongoDB\Driver\Manager::startSession(?array `$options` = `null`): MongoDB\Driver\Session

Crear una MongoDB\Driver\Session para las opciones dadas. La sesión puede luego ser especificada durante la ejecución de comandos, consultas y operaciones de escritura.

> Nota: Una MongoDB\Driver\Session solo puede ser utilizada con el MongoDB\Driver\Manager desde el cual fue creada.

### Parámetros

`options`

  options
  Opción | Tipo | Descripción | Por defecto
  --- | --- | --- | ---
  causalConsistency | bool | Configura la coherencia causal en una sesión. Si `true`, cada operación en la sesión será ordenada de manera causal después de la operación de lectura o escritura previa. Definir a `false` para desactivar la coherencia causal. Ver » Consistencia causal en el manual de MongoDB para más información. | `true`
  defaultTransactionOptions | array | Las opciones por defecto a aplicar a las transacciones recién creadas. Estas opciones se utilizan a menos que sean reemplazadas cuando una transacción es iniciada con un valor diferente para cada opción.
  options
  Opción | Tipo | Descripción
  --- | --- | ---
  maxCommitTimeMS | integer | El tiempo máximo en milisegundos para permitir que una sola comando `commitTransaction` se ejecute. Si se especifica, `maxCommitTimeMS` debe ser un entero 32 bits con signo superior o igual a cero.
  readConcern | MongoDB\Driver\ReadConcern | Una preocupación de lectura a aplicar a la operación. Esta opción está disponible en MongoDB 3.2+ y se traducirá en una excepción en el momento de la ejecución si se especifica para una versión más antigua del servidor.
  readPreference | MongoDB\Driver\ReadPreference | Una preferencia de lectura a utilizar para seleccionar un servidor para la operación.
  writeConcern | MongoDB\Driver\WriteConcern | Una preocupación de escritura a aplicar a la operación.
  Esta opción está disponible en MongoDB 4.0+. | `[]`
  snapshot | bool | Configura las lecturas instantáneas en una sesión. Si `true`, un timestamp será obtenido de la primera operación de lectura soportada en la sesión (es decir, `find`, `aggregate`, o `distinct` no fragmentado). Las operaciones de lectura posteriores en la sesión utilizarán luego un nivel de coherencia de lectura `"snapshot"` para leer datos mayoritariamente comprometidos desde ese timestamp. Definir a `false` para desactivar las lecturas instantáneas. Las lecturas instantáneas requieren MongoDB 5.0+ y no pueden ser utilizadas con la coherencia causal, transacciones o operaciones de escritura. Si `"snapshot"` es `true`, `"causalConsistency"` será por defecto `false`. Ver » Read Concern "instantáneas" en el manual de MongoDB para más información. | `false`

### Valores devueltos

Devuelve una MongoDB\Driver\Session.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una MongoDB\Driver\Exception\InvalidArgumentException si las opciones `"causalConsistency"` y `"snapshot"` son ambas `true`.
- Lanza una MongoDB\Driver\Exception\RuntimeException si la sesión no puede ser creada (por ejemplo, libmongoc no soporta el cifrado).

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.11.0 | La opción `"snapshot"` fue añadida.
PECL mongodb 1.6.0 | La opción `"maxCommitTimeMS"` fue añadida a `"defaultTransactionOptions"`.
PECL mongodb 1.5.0 | La opción `"defaultTransactionOptions"` fue añadida.

### Ver también

- MongoDB\Driver\Session
- » Consistencia causal en el manual de MongoDB

## Tabla de contenidos

- MongoDB\Driver\Manager::addSubscriber — Registra un observador de eventos de monitoreo con este manager
- MongoDB\Driver\Manager::__construct — Crea un nuevo Manager MongoDB
- MongoDB\Driver\Manager::createClientEncryption — Crear un nuevo objeto ClientEncryption
- MongoDB\Driver\Manager::executeBulkWrite — Ejecuta una o varias operaciones de escritura
- MongoDB\Driver\Manager::executeBulkWriteCommand — Ejecuta operaciones de escritura utilizando el comando bulkWrite
- MongoDB\Driver\Manager::executeCommand — Ejecuta un comando de base de datos
- MongoDB\Driver\Manager::executeQuery — Ejecuta una consulta de base de datos
- MongoDB\Driver\Manager::executeReadCommand — Ejecuta un comando de base de datos que lee
- MongoDB\Driver\Manager::executeReadWriteCommand — Ejecuta un comando de base de datos que lee y escribe
- MongoDB\Driver\Manager::executeWriteCommand — Ejecuta un comando de base de datos que escribe
- MongoDB\Driver\Manager::getEncryptedFieldsMap — Devuelve la opción de cifrado automático encryptedFieldsMap para el Manager
- MongoDB\Driver\Manager::getReadConcern — Devuelve el ReadConcern para el Manager
- MongoDB\Driver\Manager::getReadPreference — Devuelve el ReadPreference para el Manager
- MongoDB\Driver\Manager::getServers — Devolver los servidores a los que está conectado este gestor
- MongoDB\Driver\Manager::getWriteConcern — Devuelve el WriteConcern para el Manager
- MongoDB\Driver\Manager::removeSubscriber — Elimina un observador de eventos de supervisión de este Manager
- MongoDB\Driver\Manager::selectServer — Selecciona un servidor correspondiente a una preferencia de lectura
- MongoDB\Driver\Manager::startSession — Inicia una nueva sesión de cliente para ser utilizada con este cliente

# La clase MongoDB\Driver\Command

(mongodb >=1.0.0)

## Introducción

La clase MongoDB\Driver\Command es un objeto valor que representa un comando de base de datos.

Para proporcionar asistentes de comandos el objeto MongoDB\Driver\Command debe estar compuesto.

## Sinopsis de la Clase

final class MongoDB\Driver\Command {
/* Métodos */
final public function __construct(array|object `$documento`, ?array `$opcionesComando` = `null`)
}

## Ejemplos

Ejemplo #1 Composición de MongoDB\Driver\Command para proporcionar un asistente para crear colecciones

    <?php
    class CreateCollection {
        protected $cmd = array();

        function __construct($collectionName) {
            $this->cmd["create"] = (string) $collectionName;
        }
        function setCappedCollection($maxBytes, $maxDocuments = false) {
            $this->cmd["capped"] = true;
            $this->cmd["size"]   = (int) $maxBytes;

            if ($maxDocuments) {
                $this->cmd["max"] = (int) $maxDocuments;
            }
        }
        function usePowerOf2Sizes($bool) {
            if ($bool) {
                $this->cmd["flags"] = 1;
            } else {
                $this->cmd["flags"] = 0;
            }
        }
        function setFlags($flags) {
            $this->cmd["flags"] = (int) $flags;
        }
        function getCommand() {
            return new MongoDB\Driver\Command($this->cmd);
        }
        function getCollectionName() {
            return $this->cmd["create"];
        }
    }

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $createCollection = new CreateCollection("cappedCollection");
    $createCollection->setCappedCollection(64 * 1024);

    try {
        $command = $createCollection->getCommand();
        $cursor = $manager->executeCommand("databaseName", $command);
        $response = $cursor->toArray()[0];
        var_dump($response);

        $collstats = ["collstats" => $createCollection->getCollectionName()];
        $cursor = $manager->executeCommand("databaseName", new MongoDB\Driver\Command($collstats));
        $response = $cursor->toArray()[0];
        var_dump($response);
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }

    ?>

El ejemplo anterior mostrará:

    object(MongoDB\Driver\Command)#3 (1) {
      ["command"]=>
      array(3) {
        ["create"]=>
        string(16) "cappedCollection"
        ["capped"]=>
        bool(true)
        ["size"]=>
        int(65536)
      }
    }
    array(1) {
      ["ok"]=>
      float(1)
    }
    array(16) {
      ["ns"]=>
      string(29) "databaseName.cappedCollection"
      ["count"]=>
      int(0)
      ["size"]=>
      int(0)
      ["numExtents"]=>
      int(1)
      ["storageSize"]=>
      int(65536)
      ["nindexes"]=>
      int(1)
      ["lastExtentSize"]=>
      float(65536)
      ["paddingFactor"]=>
      float(1)
      ["paddingFactorNote"]=>
      string(101) "paddingFactor is unused and unmaintained in 2.8. It remains hard coded to 1.0 for compatibility only."
      ["userFlags"]=>
      int(0)
      ["capped"]=>
      bool(true)
      ["max"]=>
      int(9223372036854775807)
      ["maxSize"]=>
      int(65536)
      ["totalIndexSize"]=>
      int(8176)
      ["indexSizes"]=>
      object(stdClass)#4 (1) {
        ["_id_"]=>
        int(8176)
      }
      ["ok"]=>
      float(1)
    }

# MongoDB\Driver\Command::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Command::__construct — Crea un nuevo Command

### Descripción

final public function MongoDB\Driver\Command::__construct(array|object `$documento`, ?array `$opcionesComando` = `null`)

Construye un nuevo MongoDB\Driver\Command, que es un objeto de valor inmutable que representa un comando de base de datos. El comando puede entonces ser ejecutado con MongoDB\Driver\Manager::executeCommand().

El documento de comando completo, que incluye el nombre del comando y sus opciones, debe ser expresado en el parámetro `documento`. El parámetro `opcionesComando` solo se utiliza para especificar opciones relacionadas con la ejecución del comando y el MongoDB\Driver\Cursor resultante.

### Parámetros

`documento`
  El documento de comando completo, que será enviado al servidor.
`opcionesComando`

  > Nota: No utilice este parámetro para especificar opciones descritas en la referencia del comando en el manual de MongoDB. Este parámetro solo debe ser utilizado para las opciones listadas explícitamente a continuación.

  opcionesComando
  Opción | Tipo | Descripción
  --- | --- | ---
  maxAwaitTimeMS | int | Entero positivo que denota el límite de tiempo en milisegundos para que el servidor bloquee una operación getMore si no hay datos disponibles. Esta opción solo debe ser utilizada en conjunto con comandos que devuelven un cursor rastreable (p. ej. » Streams de Cambios).

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.4.0 | Se añadió un segundo argumento `opcionesComando`, que soporta la opción `"maxAwaitTimeMS"`.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\Command::__construct()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $command = new MongoDB\Driver\Command(array("buildinfo" => 1));

    try {
        $cursor = $manager->executeCommand("admin", $command);
        $response = $cursor->toArray()[0];
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }
    var_dump($response);

    ?>

Resultado del ejemplo anterior es similar a:

    array(13) {
      ["version"]=>
      string(14) "2.8.0-rc2-pre-"
      ["gitVersion"]=>
      string(62) "b743d7158f7642f4da6b7eac8320374b3b88dc2e modules: subscription"
      ["OpenSSLVersion"]=>
      string(25) "OpenSSL 1.0.1f 6 Jan 2014"
      ["sysInfo"]=>
      string(104) "Linux infant 3.16.0-24-generic #32-Ubuntu SMP Tue Oct 28 13:07:32 UTC 2014 x86_64 BOOST_LIB_VERSION=1_49"
      ["loaderFlags"]=>
      string(91) "-fPIC -pthread -Wl,-z,now -rdynamic -Wl,-Bsymbolic-functions -Wl,-z,relro -Wl,-z,now -Wl,-E"
      ["compilerFlags"]=>
      string(301) "-Wnon-virtual-dtor -Woverloaded-virtual -std=c++11 -fPIC -fno-strict-aliasing -ggdb -pthread -Wall -Wsign-compare -Wno-unknown-pragmas -Winvalid-pch -pipe -Werror -O3 -Wno-unused-local-typedefs -Wno-unused-function -Wno-deprecated-declarations -Wno-unused-but-set-variable -fno-builtin-memcmp -std=c99"
      ["allocator"]=>
      string(8) "tcmalloc"
      ["versionArray"]=>
      array(4) {
        [0]=>
        int(2)
        [1]=>
        int(8)
        [2]=>
        int(0)
        [3]=>
        int(-8)
      }
      ["javascriptEngine"]=>
      string(2) "V8"
      ["bits"]=>
      int(64)
      ["debug"]=>
      bool(false)
      ["maxBsonObjectSize"]=>
      int(16777216)
      ["ok"]=>
      float(1)
    }

Ejemplo #2 Ejemplo de MongoDB\Driver\Command::__construct()

Los comandos pueden aceptar opciones también, como parte de la estructura normal que se crea para enviar al servidor. Por ejemplo, la opción `maxTimeMS` puede ser pasada con la mayoría de comandos para restringir la cantidad de tiempo que un comando específico puede ejecutarse en el servidor.

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $command = new MongoDB\Driver\Command(
        array(
            "distinct" => "beer",
            "key" => "beer_name",
            "maxTimeMS" => 10,
        )
    );

    try {
        $cursor = $manager->executeCommand("beerdb", $command);
        $response = $cursor->toArray()[0];
    } catch(MongoDB\Driver\Exception\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }
    var_dump($response);

    ?>

Resultado del ejemplo anterior es similar a:

la operación excedió el límite de tiempo

### Ver también

- MongoDB\Driver\Manager::executeCommand() - Ejecuta un comando de base de datos
- MongoDB\Driver\Cursor

## Tabla de contenidos

- MongoDB\Driver\Command::__construct — Crea un nuevo Command

# La clase MongoDB\Driver\Query

(mongodb >=1.0.0)

## Introducción

La clase MongoDB\Driver\Query es un objeto de valor que representa una consulta a la base de datos.

## Sinopsis de la Clase

final class MongoDB\Driver\Query {
/* Métodos */
final public function __construct(array|object `$filter`, ?array `$queryOptions` = `null`)
}

# MongoDB\Driver\Query::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Query::__construct — Crear una nueva consulta

### Descripción

final public function MongoDB\Driver\Query::__construct(array|object `$filter`, ?array `$queryOptions` = `null`)

Construye un nuevo objeto MongoDB\Driver\Query, que es un objeto de valor inmutable que representa una consulta de base de datos. La consulta puede luego ser ejecutada con MongoDB\Driver\Manager::executeQuery().

### Parámetros

`filter` (array|object)
  El » atributo de la consulta. Un atributo vacío hará coincidir todos los documentos de la colección.

  > Nota: Al evaluar los criterios de consulta, MongoDB compara los tipos y los valores según sus propias » reglas de comparación para los tipos BSON, que difieren de las reglas de comparación y de manipulación de tipos de PHP. Al hacer coincidir un tipo BSON especial, los criterios de consulta deben utilizar la clase BSON (ej.: utilizar MongoDB\BSON\ObjectId para hacer coincidir un » ObjectId).

`queryOptions`

  queryOptions
  Opción | Tipo | Descripción
  --- | --- | ---
  allowDiskUse | bool | Autoriza a MongoDB a utilizar ficheros temporales en el disco para almacenar datos que excedan el límite de memoria del sistema de 100 megabytes al procesar una operación de clasificación bloqueante.
  allowPartialResults | bool | Para las consultas en una colección fragmentada, devuelve resultados parciales del mongos si algunos fragmentos no están disponibles en lugar de generar un error. Retoma la opción deprecada `"partial"` si no se especifica.
  awaitData | bool | Utilizar en conjunción con la opción `"tailable"` para bloquear temporalmente una operación getMore en el cursor si al final de los datos en lugar de no devolver datos. Después de un período de espera, la consulta termina normalmente.
  batchSize | int | El número de documentos a devolver en el primer lote. Por omisión a 101. Un tamaño de lote de 0 significa que el cursor será establecido, pero ningún documento será devuelto en el primer lote. En las versiones de MongoDB anteriores a 3.2, donde las consultas utilizan el protocolo de filaire heredado OP_QUERY, un tamaño de lote de 1 cerrará el cursor independientemente del número de documentos.
  collation | array|object | » Collation permite a los usuarios especificar reglas específicas del lenguaje para la comparación de cadenas, por ejemplo, reglas para mayúsculas o acentos. Al especificar una collation, el campo `"locale"` es obligatorio; todos los demás campos de la collation son opcionales. Para la descripción de estos campos, consúltese el » documento Collation. Si la collation no es especificada pero la colección tiene una collation por omisión, la operación utilizará la collation especificada para la colección. Si ninguna collation es especificada para la colección o para la operación, MongoDB utilizará el binario simple de comparación utilizado en versiones anteriores para las comparaciones de cadenas. Esta opción está disponible en MongoDB 3.4+ y una excepción será emitida en tiempo de ejecución si es especificada en una versión anterior.
  comment | mixed | Un comentario arbitrario para ayudar a rastrear la operación a través del perfil de la base de datos, la salida currentOp y los registros. El comentario puede ser cualquier tipo BSON válido para MongoDB 4.4+. Las versiones de servidor anteriores solo admiten valores de cadena. Retoma la opción deprecada `"$comment"` si no se especifica.
  exhaust | bool | El flujo de datos aguas abajo a plena potencia en varios paquetes "more", asumiendo que el cliente leerá completamente todos los datos consultados. Más rápido cuando se extraen muchos datos y se sabe que se quiere extraer todo. Nota: el cliente no está autorizado a no leer todos los datos a menos que cierre la conexión. Esta opción no es admitida por el comando find en MongoDB 3.2+ y forzará al controlador a utilizar la versión del protocolo de filaire heredado (es decir, OP_QUERY).
  explain | bool | Si `true` el cursor MongoDB\Driver\Cursor devuelto contendrá un solo documento que describe el proceso y los índices utilizados para devolver la consulta. Retoma la opción deprecada `"$explain"` si no se especifica. Esta opción no es admitida por el comando find en MongoDB 3.2+ y solo será respetada al utilizar la versión del protocolo de filaire heredado (es decir, OP_QUERY). El comando » explain debe ser utilizado en MongoDB 3.0+.
  hint | string|array|object | Especificación del índice. Especifique el nombre del índice como cadena, o el patrón de clave de índice. Si se especifica, el sistema de consulta solo considerará los planes que utilicen el índice sugerido. Retoma la opción deprecada `"hint"` si no se especifica.
  let | array|object | Diccionario de nombres y valores de parámetros. Los valores deben ser constantes o expresiones cerradas que no hagan referencia a campos del documento. Los parámetros pueden ser accedidos luego como variables en un contexto de expresión agregada (por ejemplo `$$var`). Esta opción está disponible en MongoDB 5.0+ y resultará en una excepción en tiempo de ejecución si es especificada para una versión anterior del servidor.
  limit | int | El número máximo de documentos a devolver. Si no se especifica, entonces por omisión a ningún límite. Un límite de 0 es equivalente a no establecer un límite.
  max | array|object | El límite superior exclusivo para un índice específico. Retoma la opción deprecada `"$max"` si no se especifica.
  maxAwaitTimeMS | int | Entero positivo que indica el límite de tiempo en milisegundos para que el servidor bloquee una operación getMore si no hay datos disponibles. Esta opción solo debe ser utilizada en conjunción con las opciones `"tailable"` y `"awaitData"`.
  maxTimeMS | int | El límite de tiempo acumulativo en milisegundos para el procesamiento de las operaciones en el cursor. MongoDB detiene la operación en el primer punto de interrupción más cercano. Retoma la opción deprecada `"$maxTimeMS"` si no se especifica.
  min | array|object | El límite inferior inclusivo para un índice específico. Retoma la opción deprecada `"$min"` si no se especifica.
  noCursorTimeout | bool | Evita que el servidor finalice los cursores inactivos después de un período de inactividad (10 minutos).
  projection | array|object | Las » especificaciones de proyección para determinar qué campos incluir en los documentos devueltos. Si se utiliza la funcionalidad ODM para deserializar los documentos como su clase PHP original, asegúrese de incluir el campo __pclass en la proyección. Esto es necesario para que la deserialización funcione y sin ello, la extensión devolverá (por omisión) un objeto stdClass en su lugar.
  readConcern | MongoDB\Driver\ReadConcern | Un read concern a aplicar a la operación. Por omisión, el read concern de la URI de conexión MongoDB será utilizado. Esta opción está disponible en MongoDB 3.2+ y provocará una excepción en el momento de la ejecución si se especifica para una versión de servidor más antigua.
  returnKey | bool | Si `true`, solo devuelve las claves de índice en los documentos resultantes. El valor por omisión es `false`. Si `true` y la comando find no utiliza un índice, los documentos devueltos estarán vacíos. Retoma la opción deprecada `"$returnKey"` si no se especifica.
  showRecordId | bool | Determina si el identificador de registro debe ser devuelto para cada documento. Si `true`, añade un campo `"$recordId"` de primer nivel a los documentos devueltos. Retoma la opción deprecada `"$showDiskLoc"` si no se especifica.
  singleBatch | bool | Determina si el cursor debe ser cerrado después del primer lote. Por omisión a `false`.
  skip | int | Número de documentos a saltar. Por omisión a 0.
  sort | array|object | La especificación de clasificación para el ordenamiento de los resultados. Retoma la opción deprecada `"$orderby"` si no se especifica.
  tailable | bool | Devuelve un cursor tailable para una colección acotada.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | La opción `"partial"` ha sido eliminada. Utilice `"allowPartialResults"` en su lugar. La opción `"maxScan"` ha sido eliminada. El soporte para esta opción ha sido eliminado en MongoDB 4.2. La opción `"modifiers"` ha sido eliminada. Esta opción era utilizada para los modificadores de consulta antigua, que están todos deprecados. La opción `"oplogReplay"` ha sido eliminada. Esto es ignorado en MongoDB 4.4 y versiones más recientes. La opción `"snapshot"` ha sido eliminada. Su soporte ha sido eliminado en MongoDB 4.0. Un valor negativo para la opción `"limit"` ya no implica `true` para la opción `"singleBatch"`. Para recibir solo un lote de resultados, combine un valor positivo `"limit"` con la opción `"singleBatch"`.
PECL mongodb 1.14.0 | Añadida la opción `"let"`. La opción `"comment"` ahora acepta cualquier tipo.
PECL mongodb 1.8.0 | Añadida la opción `"allowDiskUse"`. La opción `"oplogReplay"` está deprecada.
PECL mongodb 1.5.0 | Las opciones `"maxScan"` y `"snapshot"` están deprecadas.
PECL mongodb 1.3.0 | Añadida la opción `"maxAwaitTimeMS"`
PECL mongodb 1.2.0 | Añadidas las opciones `"allowPartialResults"`, `"collation"`, `"comment"`, `"hint"`, `"max"`, `"maxScan"`, `"maxTimeMS"`, `"min"`, `"returnKey"`, `"showRecordId"`, y `"snapshot"`. Renombrada la opción `"partial"` a `"allowPartialResults"`. Por compatibilidad ascendente, `"partial"` será siempre leído si `"allowPartialResults"` no está especificado. Eliminada la opción `"secondaryOk"` obsoleta. Para las consultas que utilizan el protocolo de filaire heredado OP_QUERY, el controlador establecerá el bit `secondaryOk` según sea necesario conforme a la » Especificación de selección del servidor.
PECL mongodb 1.1.0 | Añadida la opción `"readConcern"`.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\Query::__construct()

    <?php
    /* Selecciona solo los documentos escritos por "bjori" con al menos 100 vistas */
    $filter = [
        'author' => 'bjori',
        'views' => [
            '$gte' => 100,
        ],
    ];

    $options = [
        /* Devuelve solo los siguientes campos en los documentos correspondientes */
        'projection' => [
            'title' => 1,
            'article' => 1,
        ],
        /* Devuelve los documentos en orden descendente de vistas */
        'sort' => [
            'views' => -1
        ],
    ];

    $query = new MongoDB\Driver\Query($filter, $options);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $readPreference = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
    $cursor = $manager->executeQuery('databaseName.collectionName', $query, ['readPreference' => $readPreference]);

    foreach($cursor as $document) {
        var_dump($document);
    }

    ?>

### Ver también

- MongoDB\Driver\Manager::executeQuery() - Ejecuta una consulta de base de datos
- MongoDB\Driver\Cursor

## Tabla de contenidos

- MongoDB\Driver\Query::__construct — Crear una nueva consulta

# La clase MongoDB\Driver\BulkWrite

(mongodb >=1.0.0)

## Introducción

La clase MongoDB\Driver\BulkWrite recopila una o más operaciones de escritura que deben enviarse al servidor. Tras añadir cualquier número de operaciones de inserción, actualización y eliminación, la colección puede ejecutarse mediante MongoDB\Driver\Manager::executeBulkWrite().

Las operaciones de escritura pueden ser ordenadas (por omisión) o no ordenadas. Las operaciones de escritura ordenadas se envían al servidor, en el orden proporcionado, para su ejecución secuencial. Si una escritura falla, las operaciones restantes se abortarán. Las operaciones no ordenadas se envían al servidor en un orden arbitrario donde pueden ejecutarse en paralelo. Cualquier error que ocurra se notificará después de que se hayan intentado todas las operaciones.

## Sinopsis de la Clase

final class MongoDB\Driver\BulkWrite implements Countable {
/* Métodos */
public function __construct(?array `$options` = `null`)
public function count(): int
public function delete(array|object `$filter`, ?array `$deleteOptions` = `null`): void
public function insert(array|object `$documento`): mixed
public function update(array|object `$filter`, array|object `$newObj`, ?array `$updateOptions` = `null`): void
}

## Ejemplos

Ejemplo #1 Las operaciones de escritura mixtas se agrupan por tipo

Las operaciones de escritura mixtas (es decir, inserciones, actualizaciones y eliminaciones) se ensamblarán en comandos de escritura tipificados para enviarse secuencialmente al servidor.

    <?php

    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
    $bulk->insert(['_id' => 1, 'x' => 1]);
    $bulk->insert(['_id' => 2, 'x' => 2]);
    $bulk->update(['x' => 2], ['$set' => ['x' => 1]]);
    $bulk->insert(['_id' => 3, 'x' => 3]);
    $bulk->delete(['x' => 1]);

    ?>

Dará como resultado la ejecución de cuatro comandos de escritura (es decir, viajes de ida y vuelta). Dado que las operaciones están ordenadas, la tercera inserción no puede enviarse hasta que se ejecute la actualización precedente.

Ejemplo #2 Operaciones de escritura ordenadas que causan un error

    <?php

    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
    $bulk->delete([]);
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 3, 'hello' => 'world']);
    $bulk->update(['_id' => 3], ['$set' => ['hello' => 'earth']]);
    $bulk->insert(['_id' => 4, 'hello' => 'pluto']);
    $bulk->update(['_id' => 4], ['$set' => ['hello' => 'moon']]);
    $bulk->insert(['_id' => 3]);
    $bulk->insert(['_id' => 4]);
    $bulk->insert(['_id' => 5]);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $writeConcern = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 1000);

    try {
        $result = $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        $result = $e->getWriteResult();

        // Comprobar si la preocupación de escritura no pudo cumplirse
        if ($writeConcernError = $result->getWriteConcernError()) {
            printf("%s (%d): %s\n",
                $writeConcernError->getMessage(),
                $writeConcernError->getCode(),
                var_export($writeConcernError->getInfo(), true)
            );
        }

        // Comprobar si alguna operación de escritura no se completó en absoluto
        foreach ($result->getWriteErrors() as $writeError) {
            printf("Operación#%d: %s (%d)\n",
                $writeError->getIndex(),
                $writeError->getMessage(),
                $writeError->getCode()
            );
        }
    } catch (MongoDB\Driver\Exception\Exception $e) {
        printf("Otro error: %s\n", $e->getMessage());
        exit;
    }

    printf("Insertados %d documento(s)\n", $result->getInsertedCount());
    printf("Actualizados %d documento(s)\n", $result->getModifiedCount());

    ?>

El ejemplo anterior mostrará:

    Operación#7: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 3 } (11000)
    Insertados 4 documento(s)
    Actualizados  2 documento(s)

Si la preocupación de escritura no pudiera cumplirse, el ejemplo anterior mostraría algo como:

    waiting for replication timed out (64): array (
      'wtimeout' => true,
    )
    Operación#7: E11000 duplicate key error index: databaseName.collectionName.$_id_ dup key: { : 3 } (11000)
    Insertados 4 documento(s)
    Actualizados  2 documento(s)

Si ejecutamos el ejemplo anterior, pero permitimos escrituras no ordenadas:

    <?php

    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => false]);
    /* ... */

    ?>

El ejemplo anterior mostrará:

    Operación#7: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 3 } (11000)
    Operación#8: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 4 } (11000)
    Insertados 5 documento(s)
    Actualizados  2 documento(s)

## Ver también

- MongoDB\Driver\Manager::executeBulkWrite()
- MongoDB\Driver\WriteResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\WriteConcernError
- MongoDB\Driver\WriteError

# MongoDB\Driver\BulkWrite::__construct

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::__construct — Crea un nuevo BulkWrite

### Descripción

public function MongoDB\Driver\BulkWrite::__construct(?array `$options` = `null`)

Construye un nuevo MongoDB\Driver\BulkWrite, que es un objeto mutable al cual se pueden añadir una o más operaciones de escritura. Las escritura(s) pueden entonces ser ejecutadas con MongoDB\Driver\Manager::executeBulkWrite().

### Parámetros

`options` (array)

  options
  Opción | Tipo | Descripción | Valor por omisión
  --- | --- | --- | ---
  bypassDocumentValidation | bool | Si es `true`, permite que las operaciones de inserción y actualización eviten la validación a nivel de documento. Esta opción está disponible en MongoDB 3.2+ y es ignorada en versiones anteriores del servidor, que no soportan validación a nivel de documento. | `false`
  comment | mixed | Un comentario arbitrario para ayudar a rastrear la operación a través del perfilador de la base de datos, la salida currentOp y los registros. Esta opción está disponible en MongoDB 4.4+ y generará una excepción en tiempo de ejecución si se especifica para una versión anterior del servidor.
  let | array|object | Diccionario de nombres y valores de parámetros. Los valores deben ser constantes o expresiones cerradas que no hagan referencia a campos del documento. Los parámetros pueden ser accedidos luego como variables en un contexto de expresión agregada (por ejemplo `$$var`). Esta opción está disponible en MongoDB 5.0+ y resultará en una excepción en tiempo de ejecución si es especificada para una versión anterior del servidor.
  ordered | bool | Las operaciones ordenadas (`true`) se ejecutan de forma serial en el servidor de MongoDB, mientras que las operaciones no ordenadas (`false`) son enviadas al servidor en un orden arbitrario y pueden ser ejecutadas en paralelo. | `true`

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.14.0 | Se añadieron las opciones `"comment"` y `"let"`.
PECL mongodb 1.1.0 | Se añadió la opción `"bypassDocumentValidation"`.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\BulkWrite::__construct()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
    $bulk->delete([]);
    $bulk->insert(['_id' => 1, 'x' => 1]);
    $bulk->insert(['_id' => 2, 'x' => 2]);
    $bulk->update(
        ['x' => 2],
        ['$set' => ['x' => 1]],
        ['limit' => 1, 'upsert' => false]
    );
    $bulk->delete(['x' => 1], ['limit' => 1]);
    $bulk->update(
        ['_id' => 3],
        ['$set' => ['x' => 3]],
        ['limit' => 1, 'upsert' => true]
    );

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $writeConcern = new MongoDB\Driver\WriteConcern(1);

    try {
        $result = $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        $result = $e->getWriteResult();

        // Comprobar si la preocupación de escritura no pudo ser cumplida
        if ($writeConcernError = $result->getWriteConcernError()) {
            printf("%s (%d): %s\n",
                $writeConcernError->getMessage(),
                $writeConcernError->getCode(),
                var_export($writeConcernError->getInfo(), true)
            );
        }

        // Comprobar si alguna operación de escritura no se completó en absoluto
        foreach ($result->getWriteErrors() as $writeError) {
            printf("Operación#%d: %s (%d)\n",
                $writeError->getIndex(),
                $writeError->getMessage(),
                $writeError->getCode()
            );
        }
    } catch (MongoDB\Driver\Exception\Exception $e) {
        printf("Otro error: %s\n", $e->getMessage());
        exit;
    }

    printf("Insertados %d documento(s)\n", $result->getInsertedCount());
    printf("Actualizados %d documento(s)\n", $result->getModifiedCount());
    printf("Incluidos %d documento(s)\n", $result->getUpsertedCount());
    printf("Eliminados %d documento(s)\n", $result->getDeletedCount());

    ?>

El ejemplo anterior mostrará:

    Insertados 2 documento(s)
    Actualizados  1 documento(s)
    Incluidos 1 documento(s)
    Eliminados  1 documento(s)

### Ver también

- MongoDB\Driver\Manager::executeBulkWrite() - Ejecuta una o varias operaciones de escritura
- MongoDB\Driver\WriteResult

# MongoDB\Driver\BulkWrite::count

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::count — Cuenta el número de operaciones de escritura en la operación masiva

### Descripción

public function MongoDB\Driver\BulkWrite::count(): int

Devuelve el número de operaciones de escritura añadidas al objeto MongoDB\Driver\BulkWrite.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de operaciones de escritura añadidas al objeto MongoDB\Driver\BulkWrite.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.2.0 | Devuelve el número de operaciones de escritura añadidas al objeto MongoDB\Driver\BulkWrite. Las versiones anteriores devolvían el número esperado de viajes de ida y vuelta del cliente al servidor necesarios para ejecutar todas las operaciones de escritura.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\BulkWrite::count()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1, 'x' => 1]);
    $bulk->insert(['_id' => 2, 'x' => 2]);
    $bulk->update(['x' => 2], ['$set' => ['x' => 1]]);
    $bulk->delete(['x' => 1]);

    var_dump(count($bulk));

    ?>

El ejemplo anterior mostrará:

    int(4)

# MongoDB\Driver\BulkWrite::delete

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::delete — Añade una operación de eliminación al lote masivo

### Descripción

public function MongoDB\Driver\BulkWrite::delete(array|object `$filter`, ?array `$deleteOptions` = `null`): void

Añade una operación de eliminación al MongoDB\Driver\BulkWrite.

### Parámetros

`filter` (array|object)
  El » atributo de la consulta. Un atributo vacío hará coincidir todos los documentos de la colección.

  > Nota: Al evaluar los criterios de consulta, MongoDB compara los tipos y los valores según sus propias » reglas de comparación para los tipos BSON, que difieren de las reglas de comparación y de manipulación de tipos de PHP. Al hacer coincidir un tipo BSON especial, los criterios de consulta deben utilizar la clase BSON (ej.: utilizar MongoDB\BSON\ObjectId para hacer coincidir un » ObjectId).

`deleteOptions`

  deleteOptions
  Opción | Tipo | Descripción | Valor por omisión
  --- | --- | --- | ---
  collation | array|object | » Collation permite a los usuarios especificar reglas específicas del lenguaje para la comparación de cadenas, por ejemplo, reglas para mayúsculas o acentos. Al especificar una collation, el campo `"locale"` es obligatorio; todos los demás campos de la collation son opcionales. Para la descripción de estos campos, consúltese el » documento Collation. Si la collation no es especificada pero la colección tiene una collation por omisión, la operación utilizará la collation especificada para la colección. Si ninguna collation es especificada para la colección o para la operación, MongoDB utilizará el binario simple de comparación utilizado en versiones anteriores para las comparaciones de cadenas. Esta opción está disponible en MongoDB 3.4+ y una excepción será emitida en tiempo de ejecución si es especificada en una versión anterior.
  hint | string|array|object | Especificación del índice. Especifique ya sea el nombre del índice como un string o el patrón de clave del índice. Si se especifica, entonces el sistema de consultas solo considerará planes que utilicen el índice indicado. Esta opción está disponible en MongoDB 4.4+ y generará una excepción en tiempo de ejecución si se especifica para una versión anterior del servidor.
  limit | bool | Eliminar todos los documentos coincidentes (`false`), o solo el primer documento coincidente (`true`) | `false`

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.8.0 | Se añadió la opción `"hint"`.
PECL mongodb 1.2.0 | Se añadió la opción `"collation"`.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\BulkWrite::delete()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->delete(['x' => 1], ['limit' => 1]);
    $bulk->delete(['x' => 2], ['limit' => 0]);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $result = $manager->executeBulkWrite('db.collection', $bulk);

    ?>

### Ver también

- MongoDB\Driver\Manager::executeBulkWrite() - Ejecuta una o varias operaciones de escritura
- MongoDB\Driver\WriteResult

# MongoDB\Driver\BulkWrite::insert

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::insert — Añade una operación de inserción al lote masivo

### Descripción

public function MongoDB\Driver\BulkWrite::insert(array|object `$documento`): mixed

Añade una operación de inserción a la MongoDB\Driver\BulkWrite.

### Parámetros

`documento` (array|object)
  Un documento a insertar.

### Valores devueltos

Devuelve el `_id` del documento insertado. Si el `documento` no tenía un `_id`, se devolverá el MongoDB\BSON\ObjectId generado para la inserción.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.3.0 | Siempre se devuelve el `_id` del documento insertado. Anteriormente, el método solo devolvía un valor si se generaba un MongoDB\BSON\ObjectId.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\BulkWrite::insert()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite;

    $doc1 = ['x' => 1];
    $doc2 = ['_id' => 'id-personalizado', 'x' => 2];
    $doc3 = ['_id' => new MongoDB\BSON\ObjectId('0123456789abcdef01234567'), 'x' => 3];

    $id1 = $bulk->insert($doc1);
    $id2 = $bulk->insert($doc2);
    $id3 = $bulk->insert($doc3);

    var_dump($id1, $id2, $id3);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $result = $manager->executeBulkWrite('db.collection', $bulk);

    ?>

Resultado del ejemplo anterior es similar a:

    object(MongoDB\BSON\ObjectId)#3 (1) {
      ["oid"]=>
      string(24) "67f58058d1a0aa2fd80d55d0"
    }
    string(18) "id-personalizado"
    object(MongoDB\BSON\ObjectId)#4 (1) {
      ["oid"]=>
      string(24) "0123456789abcdef01234567"
    }

### Ver también

- MongoDB\Driver\Manager::executeBulkWrite() - Ejecuta una o varias operaciones de escritura
- MongoDB\Driver\WriteResult
- MongoDB\BSON\ObjectId
- MongoDB\BSON\Persistable

# MongoDB\Driver\BulkWrite::update

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::update — Añade una operación de actualización al lote

### Descripción

public function MongoDB\Driver\BulkWrite::update(array|object `$filter`, array|object `$newObj`, ?array `$updateOptions` = `null`): void

Añade una operación de actualización al MongoDB\Driver\BulkWrite.

### Parámetros

`filter` (array|object)
  El » atributo de la consulta. Un atributo vacío hará coincidir todos los documentos de la colección.

  > Nota: Al evaluar los criterios de consulta, MongoDB compara los tipos y los valores según sus propias » reglas de comparación para los tipos BSON, que difieren de las reglas de comparación y de manipulación de tipos de PHP. Al hacer coincidir un tipo BSON especial, los criterios de consulta deben utilizar la clase BSON (ej.: utilizar MongoDB\BSON\ObjectId para hacer coincidir un » ObjectId).

`newObj` (array|object)
  Un documento que contiene operadores de actualización (por ejemplo, `$set`), un documento de reemplazo (es decir, únicamente expresiones `campo:valor`), o una » tubería de agregación.
`updateOptions`

  updateOptions
  Opción | Tipo | Descripción | Valor por omisión
  --- | --- | --- | ---
  arrayFilters | array | Un array de documentos de filtro que determina qué elementos de array modificar para una operación de actualización en un campo de array. Consulte » Especificar arrayFilters para operaciones de actualización de arrays en el manual de MongoDB para más información. Esta opción está disponible en MongoDB 3.6+ y generará una excepción en tiempo de ejecución si se especifica para una versión anterior del servidor.
  collation | array|object | » Collation permite a los usuarios especificar reglas específicas del lenguaje para la comparación de cadenas, por ejemplo, reglas para mayúsculas o acentos. Al especificar una collation, el campo `"locale"` es obligatorio; todos los demás campos de la collation son opcionales. Para la descripción de estos campos, consúltese el » documento Collation. Si la collation no es especificada pero la colección tiene una collation por omisión, la operación utilizará la collation especificada para la colección. Si ninguna collation es especificada para la colección o para la operación, MongoDB utilizará el binario simple de comparación utilizado en versiones anteriores para las comparaciones de cadenas. Esta opción está disponible en MongoDB 3.4+ y una excepción será emitida en tiempo de ejecución si es especificada en una versión anterior.
  hint | string|array|object | Especificación de índice. Especifique ya sea el nombre del índice como string o el patrón de clave de índice. Si se especifica, entonces el sistema de consultas solo considerará planes que usen el índice indicado. Esta opción está disponible en MongoDB 4.2+ y generará una excepción en tiempo de ejecución si se especifica para una versión anterior del servidor.
  multi | bool | Actualizar solo el primer documento coincidente si `false`, o todos los documentos coincidentes `true`. Esta opción no puede ser `true` si `newObj` es un documento de reemplazo. | `false`
  sort | array|object | Especifica qué documento actualizará la operación si la consulta coincide con múltiples documentos. Se actualizará el primer documento coincidente según el orden de clasificación. Esta opción no puede usarse si `"multi"` es `true`. Esta opción está disponible en MongoDB 8.0+ y generará una excepción en tiempo de ejecución si se especifica para una versión anterior del servidor.
  upsert | bool | Si `filter` no coincide con un documento existente, inserta un único documento. El documento se creará a partir de `newObj` si es un documento de reemplazo (es decir, sin operadores de actualización); de lo contrario, los operadores en `newObj` se aplicarán a `filter` para crear el nuevo documento. | `false`

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.21.0 | Se añadió la opción `"sort"`.
PECL mongodb 1.7.0 | Se añadió la opción `"hint"`.
PECL mongodb 1.6.0 | El parámetro `newObj` ahora acepta una tubería de agregación. Esta característica requiere MongoDB 4.2+ y generará una excepción en tiempo de ejecución si se especifica para una versión anterior del servidor.
PECL mongodb 1.5.0 | Usar la opción `"arrayFilters"` generará una excepción en tiempo de ejecución si el servidor no la soporta. Anteriormente, no se generaba ninguna excepción y la opción podía ignorarse.
PECL mongodb 1.4.0 | Se añadió la opción `"arrayFilters"`.
PECL mongodb 1.2.0 | Se añadió la opción `"collation"`.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\BulkWrite::update()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->update(
        ['x' => 2],
        ['$set' => ['y' => 3]],
        ['multi' => false, 'upsert' => false]
    );

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $result = $manager->executeBulkWrite('db.collection', $bulk);

    ?>

### Ver también

- MongoDB\Driver\Manager::executeBulkWrite() - Ejecuta una o varias operaciones de escritura
- MongoDB\Driver\WriteResult

## Tabla de contenidos

- MongoDB\Driver\BulkWrite::__construct — Crea un nuevo BulkWrite
- MongoDB\Driver\BulkWrite::count — Cuenta el número de operaciones de escritura en la operación masiva
- MongoDB\Driver\BulkWrite::delete — Añade una operación de eliminación al lote masivo
- MongoDB\Driver\BulkWrite::insert — Añade una operación de inserción al lote masivo
- MongoDB\Driver\BulkWrite::update — Añade una operación de actualización al lote

# La clase MongoDB\Driver\BulkWriteCommand

(mongodb >=2.1.0)

## Introducción

La clase MongoDB\Driver\BulkWriteCommand recopila una o más operaciones de escritura que deben enviarse al servidor usando el » comando bulkWrite introducido en MongoDB 8.0. Tras añadir cualquier número de operaciones de inserción, actualización y eliminación, el comando puede ejecutarse mediante MongoDB\Driver\Manager::executeBulkWriteCommand().

A diferencia de MongoDB\Driver\BulkWrite, donde todas las operaciones de escritura deben dirigirse a la misma colección, cada operación de escritura dentro de MongoDB\Driver\BulkWriteCommand puede dirigirse a una colección diferente.

Las operaciones de escritura pueden ser ordenadas (por omisión) o no ordenadas. Las operaciones de escritura ordenadas se envían al servidor, en el orden proporcionado, para su ejecución serial. Si una escritura falla, las operaciones restantes se abortarán. Las operaciones no ordenadas se envían al servidor en un orden arbitrario donde pueden ejecutarse en paralelo. Cualquier error que ocurra se reporta después de que se hayan intentado todas las operaciones.

## Sinopsis de la Clase

final class MongoDB\Driver\BulkWriteCommand implements Countable {
/* Métodos */
public function __construct(?array `$options` = `null`)
public function count(): int
public function deleteMany(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void
public function deleteOne(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void
public function insertOne(string `$namespace`, array|object `$document`): mixed
public function replaceOne(
string `$namespace`,
array|object `$filter`,
array|object `$replacement`,
?array `$options` = `null`
): void
public function updateMany(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void
public function updateOne(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void
}

## Ejemplos

Ejemplo #1 Operaciones de escritura mixtas

Las operaciones de escritura mixtas (es decir, inserciones, actualizaciones y eliminaciones) se enviarán al servidor usando un único » comando bulkWrite.

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    // Eliminar documentos de ambas colecciones
    $bulk->deleteMany('db.coll_one', []);
    $bulk->deleteMany('db.coll_two', []);

    // Insertar documentos en dos colecciones
    $bulk->insertOne('db.coll_one', ['_id' => 1]);
    $bulk->insertOne('db.coll_two', ['_id' => 2]);
    $bulk->insertOne('db.coll_two', ['_id' => 3]);

    // Actualizar un documento en "coll_one"
    $bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    printf("Insertados %d documento(s)\n", $result->getInsertedCount());
    printf("Actualizados %d documento(s)\n", $result->getModifiedCount());

    ?>

El ejemplo anterior mostrará:

    Insertados 3 documento(s)
    Actualizados  1 documento(s)

Ejemplo #2 Operaciones de escritura ordenadas que causan un error

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 2]);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 3]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();

        var_dump($e->getWriteErrors());
    }

    printf("Insertados %d documento(s)\n", $result->getInsertedCount());

    ?>

Resultado del ejemplo anterior es similar a:

    array(1) {
      [3]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(3)
        ["info"]=>
        object(stdClass)#6 (0) {
        }
      }
    }
    Insertados 2 documento(s)

## Ver también

- MongoDB\Driver\Manager::executeBulkWriteCommand()
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\Exception\BulkWriteCommandException
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\WriteConcernError
- MongoDB\Driver\WriteError

# MongoDB\Driver\BulkWriteCommand::__construct

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::__construct — Crea un nuevo BulkWriteCommand

### Descripción

public function MongoDB\Driver\BulkWriteCommand::__construct(?array `$options` = `null`)

Construye un nuevo MongoDB\Driver\BulkWriteCommand, que puede usarse para realizar muchas operaciones de inserción, actualización y eliminación en múltiples colecciones en una sola petición usando el » comando bulkWrite introducido en MongoDB 8.0. Esto difiere de MongoDB\Driver\BulkWrite, que es compatible con todas las versiones del servidor pero limitado a una sola colección.

Después de añadir todas las operaciones de escritura, este objeto puede ejecutarse con MongoDB\Driver\Manager::executeBulkWriteCommand().

### Parámetros

`options` (array)

  options
  Opción | Tipo | Descripción | Valor por omisión
  --- | --- | --- | ---
  bypassDocumentValidation | bool | Si es `true`, permite que las operaciones de inserción y actualización eviten la validación a nivel de documento. | `false`
  comment | mixed | Un comentario arbitrario para ayudar a rastrear la operación a través del perfilador de la base de datos, la salida de currentOp y los registros.
  let | array|object | Diccionario de nombres y valores de parámetros. Los valores deben ser constantes o expresiones cerradas que no hagan referencia a campos del documento. Los parámetros pueden ser accedidos luego como variables en un contexto de expresión agregada (por ejemplo `$$var`). Esta opción está disponible en MongoDB 5.0+ y resultará en una excepción en tiempo de ejecución si es especificada para una versión anterior del servidor.
  ordered | bool | Si las operaciones en esta escritura masiva deben ejecutarse en el orden en que fueron especificadas. Si es `false`, las escrituras continuarán ejecutándose si una escritura individual falla. Si es `true`, las escrituras se detendrán si una escritura individual falla. | `true`
  verboseResults | bool | Si los resultados detallados de cada operación exitosa deben incluirse en el MongoDB\Driver\BulkWriteCommandResult devuelto. | `false`

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\BulkWriteCommand::__construct()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    // Eliminar documentos de ambas colecciones
    $bulk->deleteMany('db.coll_one', []);
    $bulk->deleteMany('db.coll_two', []);

    // Insertar documentos en dos colecciones
    $bulk->insertOne('db.coll_one', ['_id' => 1]);
    $bulk->insertOne('db.coll_two', ['_id' => 2]);
    $bulk->insertOne('db.coll_two', ['_id' => 3]);

    // Actualizar un documento en "coll_one"
    $bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    printf("Insertados %d documento(s)\n", $result->getInsertedCount());
    printf("Actualizados %d documento(s)\n", $result->getModifiedCount());

    ?>

El ejemplo anterior mostrará:

    Insertados 3 documento(s)
    Actualizados 1 documento(s)

### Ver también

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Ejecuta operaciones de escritura utilizando el comando bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::count

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::count — Cuenta el número de operaciones de escritura en el BulkWriteCommand

### Descripción

public function MongoDB\Driver\BulkWriteCommand::count(): int

Devuelve el número de operaciones de escritura añadidas al objeto MongoDB\Driver\BulkWriteCommand.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de operaciones de escritura añadidas al objeto MongoDB\Driver\BulkWriteCommand.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\BulkWriteCommand::count()

    <?php

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['_id' => 1, 'x' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 2, 'x' => 2]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['x' => 1]]);
    $bulk->deleteMany('db.coll', ['x' => 1]);

    var_dump(count($bulk));

    ?>

El ejemplo anterior mostrará:

    int(4)

# MongoDB\Driver\BulkWriteCommand::deleteMany

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::deleteMany — Añade una operación deleteMany

### Descripción

public function MongoDB\Driver\BulkWriteCommand::deleteMany(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void

Añade una operación deleteMany a la MongoDB\Driver\BulkWriteCommand. Todos los documentos que coincidan con `filter` en la colección identificada por `namespace` serán eliminados.

### Parámetros

`namespace` (string)
  Un espacio de nombres completamente calificado (ej. `"databaseName.collectionName"`)
`filter` (array|object)
  El » atributo de la consulta. Un atributo vacío hará coincidir todos los documentos de la colección.

  > Nota: Al evaluar los criterios de consulta, MongoDB compara los tipos y los valores según sus propias » reglas de comparación para los tipos BSON, que difieren de las reglas de comparación y de manipulación de tipos de PHP. Al hacer coincidir un tipo BSON especial, los criterios de consulta deben utilizar la clase BSON (ej.: utilizar MongoDB\BSON\ObjectId para hacer coincidir un » ObjectId).

`options`

  options
  Opción | Tipo | Descripción | Valor por omisión
  --- | --- | --- | ---
  collation | array|object | » Collation permite a los usuarios especificar reglas específicas del lenguaje para la comparación de cadenas, por ejemplo, reglas para mayúsculas o acentos. Al especificar una collation, el campo `"locale"` es obligatorio; todos los demás campos de la collation son opcionales. Para la descripción de estos campos, consúltese el » documento Collation. Si la collation no es especificada pero la colección tiene una collation por omisión, la operación utilizará la collation especificada para la colección. Si ninguna collation es especificada para la colección o para la operación, MongoDB utilizará el binario simple de comparación utilizado en versiones anteriores para las comparaciones de cadenas. Esta opción está disponible en MongoDB 3.4+ y una excepción será emitida en tiempo de ejecución si es especificada en una versión anterior.
  hint | string|array|object | Especificación de índice. Especifique ya sea el nombre del índice como string o el patrón de clave de índice. Si se especifica, entonces el sistema de consultas solo considerará planes que usen el índice indicado.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\BulkWriteCommand::deleteMany()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->deleteMany('db.coll', ['x' => ['$gt' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Ver también

- MongoDB\Driver\BulkWriteCommand::deleteOne() - Añade una operación deleteOne
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Ejecuta operaciones de escritura utilizando el comando bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::deleteOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::deleteOne — Añade una operación deleteOne

### Descripción

public function MongoDB\Driver\BulkWriteCommand::deleteOne(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void

Añade una operación deleteOne a la MongoDB\Driver\BulkWriteCommand. El primer documento que coincida con `filter` en la colección identificada por `namespace` será eliminado.

### Parámetros

`namespace` (string)
  Un espacio de nombres completamente calificado (ej. `"databaseName.collectionName"`)
`filter` (array|object)
  El » atributo de la consulta. Un atributo vacío hará coincidir todos los documentos de la colección.

  > Nota: Al evaluar los criterios de consulta, MongoDB compara los tipos y los valores según sus propias » reglas de comparación para los tipos BSON, que difieren de las reglas de comparación y de manipulación de tipos de PHP. Al hacer coincidir un tipo BSON especial, los criterios de consulta deben utilizar la clase BSON (ej.: utilizar MongoDB\BSON\ObjectId para hacer coincidir un » ObjectId).

`options`

  options
  Opción | Tipo | Descripción | Valor por omisión
  --- | --- | --- | ---
  collation | array|object | » Collation permite a los usuarios especificar reglas específicas del lenguaje para la comparación de cadenas, por ejemplo, reglas para mayúsculas o acentos. Al especificar una collation, el campo `"locale"` es obligatorio; todos los demás campos de la collation son opcionales. Para la descripción de estos campos, consúltese el » documento Collation. Si la collation no es especificada pero la colección tiene una collation por omisión, la operación utilizará la collation especificada para la colección. Si ninguna collation es especificada para la colección o para la operación, MongoDB utilizará el binario simple de comparación utilizado en versiones anteriores para las comparaciones de cadenas. Esta opción está disponible en MongoDB 3.4+ y una excepción será emitida en tiempo de ejecución si es especificada en una versión anterior.
  hint | string|array|object | Especificación de índice. Especifique ya sea el nombre del índice como string o el patrón de clave del índice. Si se especifica, entonces el sistema de consultas solo considerará planes que usen el índice indicado.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\BulkWriteCommand::deleteOne()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->deleteOne('db.coll', ['x' => 1]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Ver también

- MongoDB\Driver\BulkWriteCommand::deleteMany() - Añade una operación deleteMany
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Ejecuta operaciones de escritura utilizando el comando bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::insertOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::insertOne — Añade una operación insertOne

### Descripción

public function MongoDB\Driver\BulkWriteCommand::insertOne(string `$namespace`, array|object `$document`): mixed

Añade una operación insertOne al MongoDB\Driver\BulkWriteCommand. El documento se insertará en la colección identificada por `namespace`.

### Parámetros

`namespace` (string)
  Un espacio de nombres completamente calificado (ej. `"databaseName.collectionName"`)
`document` (array|object)
  Un documento a insertar.

### Valores devueltos

Devuelve el `_id` del documento insertado. Si el `document` no tenía un `_id`, se devolverá el MongoDB\BSON\ObjectId generado para la inserción.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\BulkWriteCommand::insertOne()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    $doc1 = ['x' => 1];
    $doc2 = ['_id' => 'custom-id', 'x' => 2];
    $doc3 = ['_id' => new MongoDB\BSON\ObjectId('0123456789abcdef01234567'), 'x' => 3];

    $id1 = $bulk->insertOne('db.coll', $doc1);
    $id2 = $bulk->insertOne('db.coll', $doc2);
    $id3 = $bulk->insertOne('db.coll', $doc3);

    var_dump($id1, $id2, $id3);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

Resultado del ejemplo anterior es similar a:

    object(MongoDB\BSON\ObjectId)#3 (1) {
      ["oid"]=>
      string(24) "67f58058d1a0aa2fd80d55d0"
    }
    string(9) "custom-id"
    object(MongoDB\BSON\ObjectId)#4 (1) {
      ["oid"]=>
      string(24) "0123456789abcdef01234567"
    }

### Ver también

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Ejecuta operaciones de escritura utilizando el comando bulkWrite
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\BSON\ObjectId

# MongoDB\Driver\BulkWriteCommand::replaceOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::replaceOne — Añade una operación replaceOne

### Descripción

public function MongoDB\Driver\BulkWriteCommand::replaceOne(
string `$namespace`,
array|object `$filter`,
array|object `$replacement`,
?array `$options` = `null`
): void

Añade una operación replaceOne al MongoDB\Driver\BulkWriteCommand. El primer documento que coincida con `filter` en la colección identificada por `namespace` será reemplazado.

### Parámetros

`namespace` (string)
  Un espacio de nombres completamente calificado (ej. `"databaseName.collectionName"`)
`filter` (array|object)
  El » atributo de la consulta. Un atributo vacío hará coincidir todos los documentos de la colección.

  > Nota: Al evaluar los criterios de consulta, MongoDB compara los tipos y los valores según sus propias » reglas de comparación para los tipos BSON, que difieren de las reglas de comparación y de manipulación de tipos de PHP. Al hacer coincidir un tipo BSON especial, los criterios de consulta deben utilizar la clase BSON (ej.: utilizar MongoDB\BSON\ObjectId para hacer coincidir un » ObjectId).

`replacement` (array|object)
  Un documento de reemplazo.
`options`

  options
  Opción | Tipo | Descripción | Valor por omisión
  --- | --- | --- | ---
  collation | array|object | » Collation permite a los usuarios especificar reglas específicas del lenguaje para la comparación de cadenas, por ejemplo, reglas para mayúsculas o acentos. Al especificar una collation, el campo `"locale"` es obligatorio; todos los demás campos de la collation son opcionales. Para la descripción de estos campos, consúltese el » documento Collation. Si la collation no es especificada pero la colección tiene una collation por omisión, la operación utilizará la collation especificada para la colección. Si ninguna collation es especificada para la colección o para la operación, MongoDB utilizará el binario simple de comparación utilizado en versiones anteriores para las comparaciones de cadenas. Esta opción está disponible en MongoDB 3.4+ y una excepción será emitida en tiempo de ejecución si es especificada en una versión anterior.
  hint | string|array|object | Especificación de índice. Especifique ya sea el nombre del índice como string o el patrón de clave del índice. Si se especifica, entonces el sistema de consultas solo considerará planes que usen el índice indicado.
  sort | array|object | Especifique qué documento reemplaza la operación si la consulta coincide con múltiples documentos. El primer documento coincidente según el orden de clasificación será reemplazado.
  upsert | bool | Si `filter` no coincide con un documento existente, inserta un único documento. El documento será creado a partir de `replacement`. | `false`

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\BulkWriteCommand::replaceOne()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->replaceOne('db.coll', ['x' => 1], ['x' => 1, 'y' => 2]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Ver también

- MongoDB\Driver\BulkWriteCommand::updateOne() - Añadir una operación updateOne
- MongoDB\Driver\BulkWriteCommand::updateMany() - Añade una operación updateMany
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Ejecuta operaciones de escritura utilizando el comando bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::updateMany

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::updateMany — Añade una operación updateMany

### Descripción

public function MongoDB\Driver\BulkWriteCommand::updateMany(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void

Añade una operación updateMany a la MongoDB\Driver\BulkWriteCommand. Todos los documentos que coincidan con `filter` en la colección identificada por `namespace` serán actualizados.

### Parámetros

`namespace` (string)
  Un espacio de nombres completamente calificado (ej. `"databaseName.collectionName"`)
`filter` (array|object)
  El » atributo de la consulta. Un atributo vacío hará coincidir todos los documentos de la colección.

  > Nota: Al evaluar los criterios de consulta, MongoDB compara los tipos y los valores según sus propias » reglas de comparación para los tipos BSON, que difieren de las reglas de comparación y de manipulación de tipos de PHP. Al hacer coincidir un tipo BSON especial, los criterios de consulta deben utilizar la clase BSON (ej.: utilizar MongoDB\BSON\ObjectId para hacer coincidir un » ObjectId).

`update` (array|object)
  Un documento que contiene ya sea operadores de actualización (por ejemplo `$set`) o un » pipeline de agregación.
`options`

  options
  Opción | Tipo | Descripción | Valor por omisión
  --- | --- | --- | ---
  arrayFilters | array | Un array de documentos de filtro que determina qué elementos de array modificar para una operación de actualización en un campo de array. Consulte » Especificar arrayFilters para operaciones de actualización de arrays en el manual de MongoDB para más información.
  collation | array|object | » Collation permite a los usuarios especificar reglas específicas del lenguaje para la comparación de cadenas, por ejemplo, reglas para mayúsculas o acentos. Al especificar una collation, el campo `"locale"` es obligatorio; todos los demás campos de la collation son opcionales. Para la descripción de estos campos, consúltese el » documento Collation. Si la collation no es especificada pero la colección tiene una collation por omisión, la operación utilizará la collation especificada para la colección. Si ninguna collation es especificada para la colección o para la operación, MongoDB utilizará el binario simple de comparación utilizado en versiones anteriores para las comparaciones de cadenas. Esta opción está disponible en MongoDB 3.4+ y una excepción será emitida en tiempo de ejecución si es especificada en una versión anterior.
  hint | string|array|object | Especificación de índice. Especifique ya sea el nombre del índice como string o el patrón de clave de índice. Si se especifica, entonces el sistema de consultas solo considerará planes que usen el índice indicado.
  upsert | bool | Si `filter` no coincide con un documento existente, inserta un único documento. El documento se creará aplicando los operadores en `update` a cualquier valor de campo en `filter`. | `false`

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\BulkWriteCommand::updateMany()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->updateMany('db.coll', ['x' => ['$gt' => 1]], ['$set' => ['y' => 2]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Ver también

- MongoDB\Driver\BulkWriteCommand::replaceOne() - Añade una operación replaceOne
- MongoDB\Driver\BulkWriteCommand::updateMany()
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Ejecuta operaciones de escritura utilizando el comando bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::updateOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::updateOne — Añadir una operación updateOne

### Descripción

public function MongoDB\Driver\BulkWriteCommand::updateOne(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void

Añade una operación updateOne al MongoDB\Driver\BulkWriteCommand. El primer documento que coincida con `filter` en la colección identificada por `namespace` será actualizado.

### Parámetros

`namespace` (string)
  Un espacio de nombres completamente calificado (ej. `"databaseName.collectionName"`)
`filter` (array|object)
  El » atributo de la consulta. Un atributo vacío hará coincidir todos los documentos de la colección.

  > Nota: Al evaluar los criterios de consulta, MongoDB compara los tipos y los valores según sus propias » reglas de comparación para los tipos BSON, que difieren de las reglas de comparación y de manipulación de tipos de PHP. Al hacer coincidir un tipo BSON especial, los criterios de consulta deben utilizar la clase BSON (ej.: utilizar MongoDB\BSON\ObjectId para hacer coincidir un » ObjectId).

`update` (array|object)
  Un documento que contiene ya sea operadores de actualización (por ejemplo `$set`) o un » pipeline de agregación.
`options`

  options
  Opción | Tipo | Descripción | Valor por omisión
  --- | --- | --- | ---
  arrayFilters | array | Un array de documentos de filtro que determina qué elementos de array modificar para una operación de actualización en un campo de array. Consulte » Especificar arrayFilters para operaciones de actualización de arrays en el manual de MongoDB para más información.
  collation | array|object | » Collation permite a los usuarios especificar reglas específicas del lenguaje para la comparación de cadenas, por ejemplo, reglas para mayúsculas o acentos. Al especificar una collation, el campo `"locale"` es obligatorio; todos los demás campos de la collation son opcionales. Para la descripción de estos campos, consúltese el » documento Collation. Si la collation no es especificada pero la colección tiene una collation por omisión, la operación utilizará la collation especificada para la colección. Si ninguna collation es especificada para la colección o para la operación, MongoDB utilizará el binario simple de comparación utilizado en versiones anteriores para las comparaciones de cadenas. Esta opción está disponible en MongoDB 3.4+ y una excepción será emitida en tiempo de ejecución si es especificada en una versión anterior.
  hint | string|array|object | Especificación de índice. Especifique ya sea el nombre del índice como string o el patrón de clave de índice. Si se especifica, entonces el sistema de consultas solo considerará planes que usen el índice indicado.
  sort | array|object | Especifica qué documento actualizará la operación si la consulta coincide con múltiples documentos. El primer documento coincidente según el orden de ordenación será actualizado.
  upsert | bool | Si `filter` no coincide con un documento existente, inserta un único documento. El documento será creado aplicando operadores en `update` a cualquier valor de campo en `filter`. | `false`

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\BulkWriteCommand::updateOne()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 2]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Ver también

- MongoDB\Driver\BulkWriteCommand::replaceOne() - Añade una operación replaceOne
- MongoDB\Driver\BulkWriteCommand::updateMany() - Añade una operación updateMany
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Ejecuta operaciones de escritura utilizando el comando bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

## Tabla de contenidos

- MongoDB\Driver\BulkWriteCommand::__construct — Crea un nuevo BulkWriteCommand
- MongoDB\Driver\BulkWriteCommand::count — Cuenta el número de operaciones de escritura en el BulkWriteCommand
- MongoDB\Driver\BulkWriteCommand::deleteMany — Añade una operación deleteMany
- MongoDB\Driver\BulkWriteCommand::deleteOne — Añade una operación deleteOne
- MongoDB\Driver\BulkWriteCommand::insertOne — Añade una operación insertOne
- MongoDB\Driver\BulkWriteCommand::replaceOne — Añade una operación replaceOne
- MongoDB\Driver\BulkWriteCommand::updateMany — Añade una operación updateMany
- MongoDB\Driver\BulkWriteCommand::updateOne — Añadir una operación updateOne

# La clase MongoDB\Driver\Session

(mongodb >=1.4.0)

## Introducción

La clase MongoDB\Driver\Session representa una sesión de cliente y es devuelta por MongoDB\Driver\Manager::startSession(). Los comandos, consultas y operaciones de escritura pueden entonces asociarse a la sesión.

## Sinopsis de la Clase

final class MongoDB\Driver\Session {
/* Constantes */
const string TRANSACTION_NONE = none;
const string TRANSACTION_STARTING = starting;
const string TRANSACTION_IN_PROGRESS = in_progress;
const string TRANSACTION_COMMITTED = committed;
const string TRANSACTION_ABORTED = aborted;
/* Métodos */
final public function abortTransaction(): void
final public function advanceClusterTime(array|object `$clusterTime`): void
final public function advanceOperationTime(MongoDB\BSON\TimestampInterface `$operationTime`): void
final public function commitTransaction(): void
final private function __construct()
final public function endSession(): void
final public function getClusterTime(): ?object
final public function getLogicalSessionId(): object
final public function getOperationTime(): ?MongoDB\BSON\Timestamp
final public function getServer(): ?MongoDB\Driver\Server
final public function getTransactionOptions(): ?array
final public function getTransactionState(): string
final public function isDirty(): bool
final public function isInTransaction(): bool
final public function startTransaction(?array `$options` = `null`): void
}

## Constantes predefinidas

`MongoDB\Driver\Session::TRANSACTION_NONE`
  No hay ninguna transacción en curso.
`MongoDB\Driver\Session::TRANSACTION_STARTING`
  Se ha iniciado una transacción, pero no se ha enviado ninguna operación al servidor.
`MongoDB\Driver\Session::TRANSACTION_IN_PROGRESS`
  Hay una transacción en curso.
`MongoDB\Driver\Session::TRANSACTION_COMMITTED`
  La transacción se ha confirmado.
`MongoDB\Driver\Session::TRANSACTION_ABORTED`
  La transacción se ha abortado.

# MongoDB\Driver\Session::abortTransaction

(mongodb >=1.5.0)

MongoDB\Driver\Session::abortTransaction — Anula una transacción

### Descripción

final public function MongoDB\Driver\Session::abortTransaction(): void

Termina la transacción multi-documento y anula todas las modificaciones de datos realizadas por las operaciones en la transacción. Es decir, la transacción se termina sin guardar ninguna de las modificaciones realizadas por las operaciones en la transacción.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una MongoDB\Driver\Exception\RuntimeException si la transacción no puede ser anulada (por ejemplo, una transacción no ha sido iniciada).

### Ver también

- MongoDB\Driver\Manager::startSession() - Inicia una nueva sesión de cliente para ser utilizada con este cliente
- MongoDB\Driver\Session::commitTransaction() - Valida la transacción
- MongoDB\Driver\Session::startTransaction() - Inicia una transacción

# MongoDB\Driver\Session::advanceClusterTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::advanceClusterTime — Avance el tiempo del cluster para esta sesión

### Descripción

final public function MongoDB\Driver\Session::advanceClusterTime(array|object `$clusterTime`): void

Avance el tiempo del cluster para esta sesión. Si el tiempo del cluster es inferior o igual al tiempo del cluster actual de la sesión, esta función no hace nada.

Al utilizar este método en conjunción con MongoDB\Driver\Session::advanceOperationTime() para copiar los tiempos del cluster y de las operaciones de otra sesión se puede asegurar que las operaciones en esta sesión sean coherentes con la última operación en la otra sesión.

### Parámetros

`clusterTime`
  El tiempo del cluster es un documento que contiene un horodatage lógico y una firma de servidor. Típicamente, este valor se obtendrá llamando a MongoDB\Driver\Session::getClusterTime() en otro objeto de sesión.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Session::advanceOperationTime() - Avance el tiempo de operación para esta sesión
- MongoDB\Driver\Session::getClusterTime() - Devuelve el tiempo del cluster para esta sesión

# MongoDB\Driver\Session::advanceOperationTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::advanceOperationTime — Avance el tiempo de operación para esta sesión

### Descripción

final public function MongoDB\Driver\Session::advanceOperationTime(MongoDB\BSON\TimestampInterface `$operationTime`): void

Avance el tiempo de operación para esta sesión. Si el tiempo de operación es inferior o igual al tiempo de operación actual de la sesión, esta función no hace nada.

Al utilizar este método en conjunción con MongoDB\Driver\Session::advanceClusterTime() para copiar los tiempos de operación y de cluster de otra sesión se puede asegurar que las operaciones en esta sesión sean coherentes con la última operación en la otra sesión.

### Parámetros

`operationTime`
  La operación es un timestamp lógico. Típicamente, este valor será obtenido llamando a MongoDB\Driver\Session::getOperationTime() en otro objeto de sesión.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Session::advanceClusterTime() - Avance el tiempo del cluster para esta sesión
- MongoDB\Driver\Session::getClusterTime() - Devuelve el tiempo del cluster para esta sesión

# MongoDB\Driver\Session::commitTransaction

(mongodb >=1.5.0)

MongoDB\Driver\Session::commitTransaction — Valida la transacción

### Descripción

final public function MongoDB\Driver\Session::commitTransaction(): void

Guarda los cambios realizados por las operaciones en la transacción multi-documento y finaliza la transacción. Hasta la validación, ninguno de los cambios de datos realizados por las operaciones en la transacción es visible fuera de la transacción.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una MongoDB\Driver\Exception\CommandException si el servidor no puede validar la transacción (por ejemplo, debido a conflictos, problemas de red). Si la excepción contiene un elemento `"errorLabels"` y este array contiene un valor `"TransientTransactionError"` o `"UnknownTransactionCommitResult"`, es seguro reintentar la totalidad de la transacción. En versiones más recientes de la extensión, MongoDB\Driver\Exception\RuntimeException::hasErrorLabel() debería ser utilizado para probar esta situación en su lugar.
- Lanza una MongoDB\Driver\Exception\RuntimeException si la transacción no puede ser validada (por ejemplo, una transacción no ha sido iniciada).

### Ver también

- MongoDB\Driver\Manager::startSession() - Inicia una nueva sesión de cliente para ser utilizada con este cliente
- MongoDB\Driver\Session::abortTransaction() - Anula una transacción
- MongoDB\Driver\Session::startTransaction() - Inicia una transacción
- MongoDB\Driver\Exception\RuntimeException::hasErrorLabel() - Devuelve si un label de error está asociado con una excepción

# MongoDB\Driver\Session::__construct

(mongodb >=1.4.0)

MongoDB\Driver\Session::__construct — Crear una nueva sesión (sin usar)

### Descripción

final private function MongoDB\Driver\Session::__construct()

Los objetos MongoDB\Driver\Session son devueltos por MongoDB\Driver\Manager::startSession() y no pueden ser construidos directamente.

### Parámetros

Esta función no contiene ningún parámetro.

### Ver también

- MongoDB\Driver\Manager::startSession() - Inicia una nueva sesión de cliente para ser utilizada con este cliente

# MongoDB\Driver\Session::endSession

(mongodb >=1.5.0)

MongoDB\Driver\Session::endSession — Termina una sesión

### Descripción

final public function MongoDB\Driver\Session::endSession(): void

Este método cierra una sesión existente. Si una transacción estaba asociada a esta sesión, la transacción será anulada. Después de llamar a este método, las aplicaciones no deben invocar otros métodos en la sesión.

> Nota: Las sesiones también se cierran durante la recolección de basura. No debería ser necesario llamar a este método en circunstancias normales.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Manager::startSession() - Inicia una nueva sesión de cliente para ser utilizada con este cliente
- MongoDB\Driver\Session::abortTransaction() - Anula una transacción
- MongoDB\Driver\Session::commitTransaction() - Valida la transacción
- MongoDB\Driver\Session::startTransaction() - Inicia una transacción

# MongoDB\Driver\Session::getClusterTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::getClusterTime — Devuelve el tiempo del cluster para esta sesión

### Descripción

final public function MongoDB\Driver\Session::getClusterTime(): ?object

Devuelve el tiempo del cluster para esta sesión. Si la sesión no ha sido utilizada para una operación y MongoDB\Driver\Session::advanceClusterTime() no ha sido llamado, el tiempo del cluster será `null`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el tiempo del cluster para esta sesión, o `null` si la sesión no tiene tiempo del cluster.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Session::advanceClusterTime() - Avance el tiempo del cluster para esta sesión

# MongoDB\Driver\Session::getLogicalSessionId

(mongodb >=1.4.0)

MongoDB\Driver\Session::getLogicalSessionId — Devuelve el identificador de sesión lógica para esta sesión

### Descripción

final public function MongoDB\Driver\Session::getLogicalSessionId(): object

Devuelve el identificador de sesión lógica para esta sesión, que puede ser utilizado para identificar las operaciones de esta sesión en el servidor.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el identificador de sesión lógica para esta sesión.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Session::getOperationTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::getOperationTime — Devuelve el tiempo de operación para esta sesión

### Descripción

final public function MongoDB\Driver\Session::getOperationTime(): ?MongoDB\BSON\Timestamp

Devuelve el tiempo de operación para esta sesión. Si la sesión no ha sido utilizada para una operación y MongoDB\Driver\Session::advanceOperationTime() no ha sido llamado, el tiempo de operación será `null`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el tiempo de operación para esta sesión, o `null` si la sesión no tiene tiempo de operación.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Session::advanceOperationTime() - Avance el tiempo de operación para esta sesión

# MongoDB\Driver\Session::getServer

(mongodb >=1.6.0)

MongoDB\Driver\Session::getServer — Devuelve el servidor al que esta sesión está fijada

### Descripción

final public function MongoDB\Driver\Session::getServer(): ?MongoDB\Driver\Server

Devuelve el MongoDB\Driver\Server al que esta sesión está fijada. Si la sesión no está fijada a un servidor, `null` será devuelto.

La fijación de la sesión se utiliza principalmente para las transacciones distribuidas, ya que todas las órdenes en una transacción distribuida deben ser enviadas a la misma instancia mongos. Este método está destinado a ser utilizado por bibliotecas construidas sobre la extensión para permitir el uso de un servidor fijado en lugar de invocar la selección del servidor.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el MongoDB\Driver\Server al que esta sesión está fijada, o `null` si la sesión no está fijada a un servidor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Session::getTransactionOptions

(mongodb >=1.7.0)

MongoDB\Driver\Session::getTransactionOptions — Devuelve las opciones para la transacción en curso

### Descripción

final public function MongoDB\Driver\Session::getTransactionOptions(): ?array

Devuelve las opciones para la transacción en curso.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array que contiene las opciones de transacción actuales, o `null` si no hay ninguna transacción en curso.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Session::getTransactionState() - Devuelve el estado de la transacción actual para esta sesión

# MongoDB\Driver\Session::getTransactionState

(mongodb >=1.7.0)

MongoDB\Driver\Session::getTransactionState — Devuelve el estado de la transacción actual para esta sesión

### Descripción

final public function MongoDB\Driver\Session::getTransactionState(): string

Devuelve el estado de la transacción para esta sesión.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el estado de la transacción actual para esta sesión.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Session::isInTransaction() - Indica si una transacción multi-documento está en curso
- MongoDB\Driver\Session::getTransactionOptions() - Devuelve las opciones para la transacción en curso

# MongoDB\Driver\Session::isDirty

(mongodb >=1.13.0)

MongoDB\Driver\Session::isDirty — Indica si la sesión ha sido marcada como sucia

### Descripción

final public function MongoDB\Driver\Session::isDirty(): bool

Indica si la sesión ha sido marcada como sucia (es decir, que ha sido utilizada con un comando que ha encontrado un error de red).

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Indica si la sesión ha sido marcada como sucia.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Session::isInTransaction

(mongodb >=1.6.0)

MongoDB\Driver\Session::isInTransaction — Indica si una transacción multi-documento está en curso

### Descripción

final public function MongoDB\Driver\Session::isInTransaction(): bool

Indica si una transacción multi-documento está actualmente en curso para esta sesión. Una transacción se considera "en curso" si ha sido iniciada pero no ha sido confirmada o anulada.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si una transacción está actualmente en curso para esta sesión, y `false` en caso contrario.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Session::getTransactionState() - Devuelve el estado de la transacción actual para esta sesión

# MongoDB\Driver\Session::startTransaction

(mongodb >=1.5.0)

MongoDB\Driver\Session::startTransaction — Inicia una transacción

### Descripción

final public function MongoDB\Driver\Session::startTransaction(?array `$options` = `null`): void

Inicia una transacción multi-documento asociada a la sesión. En un momento dado, solo se puede tener una transacción abierta para una sesión. Después de iniciar una transacción, el objeto de sesión debe ser pasado a cada operación a través de la opción `"session"` (por ejemplo MongoDB\Driver\Manager::executeBulkWrite()) para asociar esta operación a la transacción.

Las transacciones pueden ser confirmadas a través de MongoDB\Driver\Session::commitTransaction(), y anuladas con MongoDB\Driver\Session::abortTransaction(). Las transacciones también se anulan automáticamente cuando la sesión se cierra por la recolección de basura o al llamar explícitamente a MongoDB\Driver\Session::endSession().

### Parámetros

`options`
  Las opciones pueden ser pasadas como argumento a este método. Cada elemento de este array de opciones reemplaza la opción correspondiente de la opción `"defaultTransactionOptions"`, si se define al iniciar la sesión con MongoDB\Driver\Manager::startSession().

  options
  Opción | Tipo | Descripción
  --- | --- | ---
  maxCommitTimeMS | integer | El tiempo máximo en milisegundos para permitir que una sola comando `commitTransaction` se ejecute. Si se especifica, `maxCommitTimeMS` debe ser un entero 32 bits con signo superior o igual a cero.
  readConcern | MongoDB\Driver\ReadConcern | Una preocupación de lectura a aplicar a la operación. Esta opción está disponible en MongoDB 3.2+ y se traducirá en una excepción en el momento de la ejecución si se especifica para una versión más antigua del servidor.
  readPreference | MongoDB\Driver\ReadPreference | Una preferencia de lectura a utilizar para seleccionar un servidor para la operación.
  writeConcern | MongoDB\Driver\WriteConcern | Una preocupación de escritura a aplicar a la operación.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una MongoDB\Driver\Exception\CommandException si la transacción no pudo ser iniciada debido a un problema en el lado del servidor (por ejemplo, un bloqueo no pudo ser obtenido).
- Lanza una MongoDB\Driver\Exception\RuntimeException si la transacción no pudo ser iniciada (por ejemplo, una transacción ya estaba en curso).

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.6.0 | La opción `"maxCommitTimeMS"` fue añadida.

### Ver también

- MongoDB\Driver\Manager::startSession() - Inicia una nueva sesión de cliente para ser utilizada con este cliente
- MongoDB\Driver\Session::commitTransaction() - Valida la transacción
- MongoDB\Driver\Session::abortTransaction() - Anula una transacción

## Tabla de contenidos

- MongoDB\Driver\Session::abortTransaction — Anula una transacción
- MongoDB\Driver\Session::advanceClusterTime — Avance el tiempo del cluster para esta sesión
- MongoDB\Driver\Session::advanceOperationTime — Avance el tiempo de operación para esta sesión
- MongoDB\Driver\Session::commitTransaction — Valida la transacción
- MongoDB\Driver\Session::__construct — Crear una nueva sesión (sin usar)
- MongoDB\Driver\Session::endSession — Termina una sesión
- MongoDB\Driver\Session::getClusterTime — Devuelve el tiempo del cluster para esta sesión
- MongoDB\Driver\Session::getLogicalSessionId — Devuelve el identificador de sesión lógica para esta sesión
- MongoDB\Driver\Session::getOperationTime — Devuelve el tiempo de operación para esta sesión
- MongoDB\Driver\Session::getServer — Devuelve el servidor al que esta sesión está fijada
- MongoDB\Driver\Session::getTransactionOptions — Devuelve las opciones para la transacción en curso
- MongoDB\Driver\Session::getTransactionState — Devuelve el estado de la transacción actual para esta sesión
- MongoDB\Driver\Session::isDirty — Indica si la sesión ha sido marcada como sucia
- MongoDB\Driver\Session::isInTransaction — Indica si una transacción multi-documento está en curso
- MongoDB\Driver\Session::startTransaction — Inicia una transacción

# La clase MongoDB\Driver\ClientEncryption

(mongodb >=1.7.0)

## Introducción

La clase MongoDB\Driver\ClientEncryption gestiona la creación de claves de datos para la cifrado lado-cliente, así como el cifrado y descifrado manual de valores.

## Sinopsis de la Clase

final class MongoDB\Driver\ClientEncryption {
/* Constantes */
const string AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC = AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic;
const string AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM = AEAD_AES_256_CBC_HMAC_SHA_512-Random;
const string ALGORITHM_INDEXED = Indexed;
const string ALGORITHM_UNINDEXED = Unindexed;
const string ALGORITHM_RANGE = Range;
const string QUERY_TYPE_EQUALITY = equality;
const string QUERY_TYPE_RANGE = range;
/* Métodos */
final public function addKeyAltName(MongoDB\BSON\Binary `$keyId`, string `$keyAltName`): ?object
final public function __construct(array `$options`)
final public function createDataKey(string `$kmsProvider`, ?array `$options` = `null`): MongoDB\BSON\Binary
final public function decrypt(MongoDB\BSON\Binary `$value`): mixed
final public function deleteKey(MongoDB\BSON\Binary `$keyId`): object
final public function encrypt(mixed `$value`, ?array `$options` = `null`): MongoDB\BSON\Binary
final public function encryptExpression(array|object `$expr`, ?array `$options` = `null`): object
final public function getKey(MongoDB\BSON\Binary `$keyId`): ?object
final public function getKeyByAltName(string `$keyAltName`): ?object
final public function getKeys(): MongoDB\Driver\Cursor
final public function removeKeyAltName(MongoDB\BSON\Binary `$keyId`, string `$keyAltName`): ?object
final public function rewrapManyDataKey(array|object `$filter`, ?array `$options` = `null`): object
}

## Constantes predefinidas

`MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC`
  Especifica un algoritmo para el » cifrado determinista, que es adecuado para consultas.
`MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM`
  Especifica un algoritmo para el » cifrado aleatorio
`MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED`
  Especifica un algoritmo para un contenido cifrado indexado, que puede usarse con cifrado consultable. Para insertar o consultar con un contenido cifrado indexado, el MongoDB\Driver\Manager debe configurarse con la opción de controlador `"autoEncryption"`. La opción de auto-cifrado `"bypassQueryAnalysis"` puede ser `true`. La opción de auto-cifrado `"bypassAutoEncryption"` debe ser `false`.
`MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED`
  Especifica un algoritmo para un contenido cifrado no indexado.
`MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`
  Especifica un algoritmo para un contenido cifrado de rango, que puede usarse con cifrado consultable. Para consultar con un contenido cifrado de rango, el MongoDB\Driver\Manager debe configurarse con la opción de controlador `"autoEncryption"`. La opción de auto-cifrado `"bypassQueryAnalysis"` puede ser `true`. La opción de auto-cifrado `"bypassAutoEncryption"` debe ser `false`.

  > Nota: La extensión aún no admite consultas de rango para tipos de campo BSON Decimal128.

`MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY`
  Especifica un tipo de consulta de igualdad, que se usa en conjunto con `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED`.
`MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE`
  Especifica un tipo de consulta de rango, que se usa en conjunto con `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Se eliminó `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW` y `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW`.
PECL mongodb 1.20.0 | Se añadió `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE` y `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE`. Se declaró obsoleto `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW` y `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW`.
PECL mongodb 1.16.0 | Se añadió `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW` y `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW`.
PECL mongodb 1.14.0 | Se añadió `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED`, `MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED`, y `MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY`.

## Ver también

- MongoDB\Driver\Manager::createClientEncryption()

# MongoDB\Driver\ClientEncryption::addKeyAltName

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::addKeyAltName — Añade un nombre alternativo a un documento de clave

### Descripción

final public function MongoDB\Driver\ClientEncryption::addKeyAltName(MongoDB\BSON\Binary `$keyId`, string `$keyAltName`): ?object

Añade `keyAltName` al conjunto de nombres alternativos para el documento de clave con el UUID dado `keyId`.

### Parámetros

`keyId`
  Una instancia de MongoDB\BSON\Binary con subtipo 4 (UUID) que identifica el documento de clave.
`keyAltName`
  Nombre alternativo que se añadirá al documento de clave.

### Valores devueltos

Devuelve la versión anterior del documento de clave, o `null` si no se encontró ningún documento coincidente.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza MongoDB\Driver\Exception\RuntimeException en caso de otros errores.

### Ver también

- MongoDB\Driver\ClientEncryption::getKeyByAltName() - Obtiene un documento de clave por un nombre alternativo
- MongoDB\Driver\ClientEncryption::removeKeyAltName() - Elimina un nombre alternativo de un documento de clave

# MongoDB\Driver\ClientEncryption::__construct

(mongodb >=1.14.0)

MongoDB\Driver\ClientEncryption::__construct — Crea un nuevo objeto ClientEncryption

### Descripción

final public function MongoDB\Driver\ClientEncryption::__construct(array `$options`)

Construye un nuevo objeto MongoDB\Driver\ClientEncryption con las opciones especificadas.

### Parámetros

`options`

  options
  Opción | Tipo | Descripción
  --- | --- | ---
  keyVaultClient | MongoDB\Driver\Manager | El gestor utilizado para enrutar las consultas de claves de datos. Esta opción es obligatoria (a diferencia de MongoDB\Driver\Manager::createClientEncryption()).
  keyVaultNamespace | string | Un nombre de espacio completamente calificado (por ejemplo `"databaseName.collectionName"`) denotando la colección que contiene todas las claves de datos utilizadas para el cifrado y descifrado. Esta opción es requerida.
  kmsProviders | array | Un documento que contiene la configuración de uno o varios proveedores KMS, que se utilizan para cifrar las claves de datos. Los proveedores soportados son `"aws"`, `"azure"`, `"gcp"` y `"local"`, y al menos uno debe ser especificado. Si se especifica un documento vacío para `"aws"`, `"azure"`, o `"gcp"`, el controlador intentará configurar el proveedor utilizando » Automatic Credentials. El formato para `"aws"` es el siguiente:
      aws: {
          accessKeyId: <string>,
          secretAccessKey: <string>,
          sessionToken: <optional string>
      }
  El formato para `"azure"` es el siguiente:
      azure: {
          tenantId: <string>,
          clientId: <string>,
          clientSecret: <string>,
          identityPlatformEndpoint: <optional string> // Defaults to "login.microsoftonline.com"

      }
  El formato para `"gcp"` es el siguiente:
      gcp: {
          email: <string>,
          privateKey: <base64 string>|<MongoDB\BSON\Binary>,
          endpoint: <optional string> // Defaults to "oauth2.googleapis.com"

      }
  El formato para `"kmip"` es el siguiente:
      kmip: {
          endpoint: <string>
      }
  El formato para `"local"` es el siguiente:
      local: {
          // 96-byte master key used to encrypt/decrypt data keys
          key: <base64 string>|<MongoDB\BSON\Binary>
      }
  tlsOptions | array | Un documento que contiene la configuración TLS de uno o varios proveedores KMS. Los proveedores soportados son `"aws"`, `"azure"`, `"gcp"` y `"kmip"`. Todos los proveedores soportan las siguientes opciones:
      <provider>: {
          tlsCaFile: <optional string>,
          tlsCertificateKeyFile: <optional string>,
          tlsCertificateKeyFilePassword: <optional string>,
          tlsDisableOCSPEndpointCheck: <optional bool>
      }

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza MongoDB\Driver\Exception\RuntimeException si la extensión fue compilada sin soporte para libmongocrypt

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.16.0 | El proveedor de KMS de AWS para la cifrado lado-cliente ahora acepta una opción `"sessionToken"`, que puede usarse para autenticarse con credenciales temporales de AWS. Se añadió `"tlsDisableOCSPEndpointCheck"` a la opción `"tlsOptions"`. Si se especifica un documento vacío para el proveedor de KMS de `"azure"` o `"gcp"`, el controlador intentará configurar el proveedor usando » Credenciales Automáticas.
PECL mongodb 1.15.0 | Si se especifica un documento vacío para el proveedor de KMS de `"aws"`, el controlador intentará configurar el proveedor usando » Credenciales Automáticas.

### Ver también

- MongoDB\Driver\Manager::createClientEncryption() - Crear un nuevo objeto ClientEncryption
- » Cifrado Explícito (Manual) de Nivel de Campo del Lado del Cliente en el manual de MongoDB

# MongoDB\Driver\ClientEncryption::createDataKey

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::createDataKey — Crea un documento de clave

### Descripción

final public function MongoDB\Driver\ClientEncryption::createDataKey(string `$kmsProvider`, ?array `$options` = `null`): MongoDB\BSON\Binary

Crea un nuevo documento de clave e inserta en la colección de almacén de claves.

### Parámetros

`kmsProvider`
  El proveedor KMS (por ejemplo `"local"`, `"aws"`) que se utilizará para cifrar la nueva clave de datos.
`options`

  Opciones de clave de datos
  Opción | Tipo | Descripción
  --- | --- | ---
  masterKey | array | El documento masterKey identifica una clave específica del KMS utilizada para cifrar la nueva clave de datos. Esta opción es obligatoria a menos que `kmsProvider` sea `"local"`.
  Opciones del proveedor `"aws"`
  Opción | Tipo | Descripción
  --- | --- | ---
  region | string | Requis.
  key | string | Requis. El nombre de recurso Amazon (ARN) de la clave maestra del cliente AWS (CMK).
  endpoint | string | Opcional. Un identificador de host alternativo para enviar las solicitudes KMS. Puede incluir el número de puerto.
  Opciones del proveedor `"azure"`
  Opción | Tipo | Descripción
  --- | --- | ---
  keyVaultEndpoint | string | Requis. Host con puerto opcional (por ejemplo, "example.vault.azure.net").
  keyName | string | Requis.
  keyVersion | string | Opcional. Una versión específica de la clave nombrada. Por omisión, se utiliza la versión primaria de la clave.
  Opciones del proveedor `"gcp"`
  Opción | Tipo | Descripción
  --- | --- | ---
  projectId | string | Requis.
  location | string | Requis.
  keyRing | string | Requis.
  keyName | string | Requis.
  keyVersion | string | Opcional. Una versión específica de la clave nombrada. Por omisión, se utiliza la versión primaria de la clave.
  endpoint | string | Opcional. Host con puerto opcional. El valor por omisión es "cloudkms.googleapis.com".
  Opciones del proveedor `"kmip"`
  Opción | Tipo | Descripción
  --- | --- | ---
  keyId | string | Opcional. Identificador único de un objeto gestionado de 96 bytes de datos secretos KMIP. Si no se especifica, el controlador crea un objeto gestionado aleatorio de 96 bytes de datos secretos KMIP.
  endpoint | string | Opcional. Host con puerto opcional.
  delegated | bool | Opcional. Si es verdadero, esta clave debe ser descifrada por el servidor KMIP.
  keyAltNames | array | Una lista opcional de nombres alternativos de tipo string utilizados para referenciar una clave. Si se crea una clave con nombres alternativos, entonces el cifrado puede referirse a la clave mediante el nombre alternativo único en lugar de por `_id`.
  keyMaterial | MongoDB\BSON\Binary | Un valor opcional de 96 bytes para usar como material de clave personalizado para la clave de datos que se está creando. Si se proporciona keyMaterial, el material de clave personalizado se utiliza para cifrar y descifrar datos. De lo contrario, el material de la nueva clave de datos se genera a partir de un dispositivo criptográficamente seguro aleatorio.

### Valores devueltos

Devuelve el identificador de la nueva clave como un objeto MongoDB\BSON\Binary con subtipo 4 (UUID).

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza MongoDB\Driver\Exception\RuntimeException en caso de otros errores.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.20.0 | Añadido `"delegated"` a las opciones de masterKey del proveedor KMIP.
PECL mongodb 1.15.0 | Añadida la opción `"keyMaterial"`.
PECL mongodb 1.10.0 | Azure y GCP ahora son compatibles como proveedores KMS para cifrado lado-cliente.

# MongoDB\Driver\ClientEncryption::decrypt

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::decrypt — Descifra un valor

### Descripción

final public function MongoDB\Driver\ClientEncryption::decrypt(MongoDB\BSON\Binary `$value`): mixed

Descifra el valor.

### Parámetros

`value`
  Una instancia de MongoDB\BSON\Binary con subtipo 6 que contiene el valor cifrado.

### Valores devueltos

Devuelve el valor descifrado tal como fue pasado a MongoDB\Driver\ClientEncryption::encrypt().

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza MongoDB\Driver\Exception\EncryptionException si ocurre un error durante el descifrado del valor

### Ver también

- MongoDB\Driver\ClientEncryption::encrypt() - Cifra un valor

# MongoDB\Driver\ClientEncryption::deleteKey

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::deleteKey — Elimina un documento de clave

### Descripción

final public function MongoDB\Driver\ClientEncryption::deleteKey(MongoDB\BSON\Binary `$keyId`): object

Elimina el documento de clave con el UUID `keyId` dado de la colección de almacén de claves.

### Parámetros

`keyId`
  Una instancia de MongoDB\BSON\Binary con subtipo 4 (UUID) que identifica el documento de clave.

### Valores devueltos

Devuelve el resultado de la operación interna `deleteOne` en la colección de almacén de claves.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza MongoDB\Driver\Exception\RuntimeException en caso de otros errores.

# MongoDB\Driver\ClientEncryption::encrypt

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::encrypt — Cifra un valor

### Descripción

final public function MongoDB\Driver\ClientEncryption::encrypt(mixed `$value`, ?array `$options` = `null`): MongoDB\BSON\Binary

Cifra el valor.

### Parámetros

`value`
  El valor a cifrar. Cualquier valor que pueda insertarse en MongoDB puede cifrarse utilizando este método.
`options`

  Opciones de cifrado
  Opción | Tipo | Descripción
  --- | --- | ---
  algorithm | string | El algoritmo de cifrado a utilizar. Esta opción es requerida. Especifique una de las siguientes constantes de ClientEncryption: `MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC` `MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM` `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` `MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED` `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`
  contentionFactor | int | El factor de contención para evaluar las consultas con cargas útiles cifradas indexadas. Esta opción se aplica únicamente y solo puede ser especificada cuando `algorithm` es `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` o `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.
  keyAltName | string | Identifica un documento de colección de cofre de claves por `keyAltName`. Esta opción es mutuamente exclusiva con `keyId` y una de las dos es requerida.
  keyId | MongoDB\BSON\Binary | Identifica una clave de datos por `_id`. El valor es un UUID (subtipo binario 4). Esta opción es mutuamente exclusiva con `keyAltName` y una de las dos es requerida.
  queryType | string | El tipo de consulta para evaluar las consultas con cargas útiles cifradas indexadas. Especifique una de las siguientes constantes de ClientEncryption: `MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY` `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE` Esta opción se aplica únicamente y solo puede ser especificada cuando `algorithm` es `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` o `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.
  rangeOpts | array | Opciones de índice para un campo de cifrado interrogeable que soporta consultas "range". Las opciones a continuación deben coincidir con los valores definidos en `encryptedFields` de la colección objetivo. Para los tipos de campo BSON double y decimal128, `min`, `max` y `precision` deben ser todos definidos o todos no definidos.
  Opciones de índice de rango
  Opción | Tipo | Descripción
  --- | --- | ---
  min | mixed | Requisito si `precision` está definido. El valor BSON mínimo del rango.
  max | mixed | Requisito si `precision` está definido. El valor BSON máximo del rango.
  sparsity | int | Opcional. Entero positivo de 64 bits.
  precision | int | Opcional. Entero positivo de 32 bits que especifica la precisión a utilizar para el cifrado explícito. Solo puede ser definido para los tipos de campo BSON double o decimal128.
  trimFactor | int | Opcional. Entero positivo de 32 bits.

### Valores devueltos

Devuelve el valor cifrado como objeto MongoDB\BSON\Binary con subtipo 6.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza MongoDB\Driver\Exception\EncryptionException si ocurre un error durante el cifrado del valor

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.20.0 | Se añadió la opción de rango `"trimFactor"`. La opción de rango `"sparsity"` ahora es opcional.
PECL mongodb 1.16.0 | Se añadió la opción `"rangeOpts"`.
PECL mongodb 1.14.0 | Se añadieron las opciones `"contentionFactor"` y `"queryType"`.

### Ver también

- MongoDB\Driver\ClientEncryption::decrypt() - Descifra un valor
- MongoDB\Driver\ClientEncryption::encryptExpression() - Cifra una expresión de coincidencia o agregación

# MongoDB\Driver\ClientEncryption::encryptExpression

(mongodb >=1.16.0)

MongoDB\Driver\ClientEncryption::encryptExpression — Cifra una expresión de coincidencia o agregación

### Descripción

final public function MongoDB\Driver\ClientEncryption::encryptExpression(array|object `$expr`, ?array `$options` = `null`): object

Cifra una expresión de coincidencia o agregación para consultar un índice de rango.

Para consultar con una carga cifrada de rango, el MongoDB\Driver\Manager debe estar configurado con la opción del controlador `"autoEncryption"`. La opción de auto-cifrado `"bypassQueryAnalysis"` puede ser `true`. La opción de auto-cifrado `"bypassAutoEncryption"` debe ser `false`.

> Nota: La extensión aún no admite consultas de rango para tipos de campo BSON Decimal128.

### Parámetros

`expr`
  La expresión de coincidencia o agregación a cifrar. Las expresiones deben usar al menos uno de los operadores `$gt`, `$gte`, `$lt` o `$lte`. Se requiere un operador `$and` de nivel superior, incluso si solo se usa un único operador de comparación. A continuación se muestra un ejemplo de una expresión de coincidencia admitida (se aplica a consultas y a la etapa de agregación `$match`):

      [
          '$and' => [
              [ '<field>' => [ '$gt'  => '<value1>' ] ],
              [ '<field>' => [ '$lte' => '<value2>' ] ],
          ],
      ]

  A continuación se muestra un ejemplo de una expresión de agregación admitida:

      [
          '$and' => [
              [ '$gte' => [ '<fieldPath>', '<value1>' ] ],
              [ '$lt'  => [ '<fieldPath>', '<value2>' ] ],
          ],
      ]

`options`

  Opciones de cifrado
  Opción | Tipo | Descripción
  --- | --- | ---
  algorithm | string | El algoritmo de cifrado a utilizar. Esta opción es requerida. Especifique una de las siguientes constantes de ClientEncryption: `MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC` `MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM` `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` `MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED` `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`
  contentionFactor | int | El factor de contención para evaluar las consultas con cargas útiles cifradas indexadas. Esta opción se aplica únicamente y solo puede ser especificada cuando `algorithm` es `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` o `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.
  keyAltName | string | Identifica un documento de colección de cofre de claves por `keyAltName`. Esta opción es mutuamente exclusiva con `keyId` y una de las dos es requerida.
  keyId | MongoDB\BSON\Binary | Identifica una clave de datos por `_id`. El valor es un UUID (subtipo binario 4). Esta opción es mutuamente exclusiva con `keyAltName` y una de las dos es requerida.
  queryType | string | El tipo de consulta para evaluar las consultas con cargas útiles cifradas indexadas. Especifique una de las siguientes constantes de ClientEncryption: `MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY` `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE` Esta opción se aplica únicamente y solo puede ser especificada cuando `algorithm` es `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` o `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.
  rangeOpts | array | Opciones de índice para un campo de cifrado interrogeable que soporta consultas "range". Las opciones a continuación deben coincidir con los valores definidos en `encryptedFields` de la colección objetivo. Para los tipos de campo BSON double y decimal128, `min`, `max` y `precision` deben ser todos definidos o todos no definidos.
  Opciones de índice de rango
  Opción | Tipo | Descripción
  --- | --- | ---
  min | mixed | Requisito si `precision` está definido. El valor BSON mínimo del rango.
  max | mixed | Requisito si `precision` está definido. El valor BSON máximo del rango.
  sparsity | int | Opcional. Entero positivo de 64 bits.
  precision | int | Opcional. Entero positivo de 32 bits que especifica la precisión a utilizar para el cifrado explícito. Solo puede ser definido para los tipos de campo BSON double o decimal128.
  trimFactor | int | Opcional. Entero positivo de 32 bits.

### Valores devueltos

Devuelve la expresión cifrada como un objeto.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza MongoDB\Driver\Exception\EncryptionException si ocurre un error al cifrar la expresión

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.20.0 | Se añadió la opción de rango `"trimFactor"`. La opción de rango `"sparsity"` ahora es opcional.

### Ver también

- MongoDB\Driver\Manager::__construct() - Crea un nuevo Manager MongoDB
- MongoDB\Driver\ClientEncryption::encrypt() - Cifra un valor

# MongoDB\Driver\ClientEncryption::getKey

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::getKey — Obtiene un documento de clave

### Descripción

final public function MongoDB\Driver\ClientEncryption::getKey(MongoDB\BSON\Binary `$keyId`): ?object

Busca un único documento de clave en la colección de almacén de claves con el UUID `keyId` proporcionado.

### Parámetros

`keyId`
  Una instancia de MongoDB\BSON\Binary con subtipo 4 (UUID) que identifica el documento de clave.

### Valores devueltos

Devuelve el documento de clave, o `null` si no se encontró ningún documento.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza MongoDB\Driver\Exception\RuntimeException en caso de otros errores.

# MongoDB\Driver\ClientEncryption::getKeyByAltName

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::getKeyByAltName — Obtiene un documento de clave por un nombre alternativo

### Descripción

final public function MongoDB\Driver\ClientEncryption::getKeyByAltName(string `$keyAltName`): ?object

Busca un único documento de clave en la colección de almacén de claves con el nombre alternativo `keyAltName` proporcionado.

### Parámetros

`keyAltName`
  Nombre alternativo para el documento de clave.

### Valores devueltos

Devuelve el documento de clave, o `null` si no se encontró ningún documento.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza MongoDB\Driver\Exception\RuntimeException en caso de otros errores.

### Ver también

- MongoDB\Driver\ClientEncryption::addKeyAltName() - Añade un nombre alternativo a un documento de clave
- MongoDB\Driver\ClientEncryption::removeKeyAltName() - Elimina un nombre alternativo de un documento de clave

# MongoDB\Driver\ClientEncryption::getKeys

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::getKeys — Obtiene todos los documentos de claves

### Descripción

final public function MongoDB\Driver\ClientEncryption::getKeys(): MongoDB\Driver\Cursor

Busca todos los documentos de claves en la colección de almacén de claves.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Retorna un MongoDB\Driver\Cursor en caso de éxito.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza MongoDB\Driver\Exception\RuntimeException en caso de otros errores.

# MongoDB\Driver\ClientEncryption::removeKeyAltName

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::removeKeyAltName — Elimina un nombre alternativo de un documento de clave

### Descripción

final public function MongoDB\Driver\ClientEncryption::removeKeyAltName(MongoDB\BSON\Binary `$keyId`, string `$keyAltName`): ?object

Elimina `keyAltName` del conjunto de nombres alternativos para el documento de clave con el UUID especificado mediante `keyId`.

### Parámetros

`keyId`
  Una instancia de MongoDB\BSON\Binary con subtipo 4 (UUID) que identifica el documento de clave.
`keyAltName`
  Nombre alternativo que se eliminará del documento de clave.

### Valores devueltos

Devuelve la versión anterior del documento de clave, o `null` si no se encontró ningún documento coincidente.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza MongoDB\Driver\Exception\RuntimeException en caso de otros errores.

### Ver también

- MongoDB\Driver\ClientEncryption::addKeyAltName() - Añade un nombre alternativo a un documento de clave
- MongoDB\Driver\ClientEncryption::getKeyByAltName() - Obtiene un documento de clave por un nombre alternativo

# MongoDB\Driver\ClientEncryption::rewrapManyDataKey

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::rewrapManyDataKey — Reenvuelve claves de datos

### Descripción

final public function MongoDB\Driver\ClientEncryption::rewrapManyDataKey(array|object `$filter`, ?array `$options` = `null`): object

Reenvuelve (es decir, descifra y vuelve a cifrar) cero o más claves de datos en la colección de claves maestras que coincidan con el `filter` proporcionado.

Si no se especifica la opción `"provider"`, las claves de datos coincidentes se reenvuelven con su proveedor KMS actual. De lo contrario, las claves de datos coincidentes se volverán a cifrar según las opciones `"provider"` y `"masterKey"` especificadas.

### Parámetros

`filter` (array|object)
  El » atributo de la consulta. Un atributo vacío hará coincidir todos los documentos de la colección.

  > Nota: Al evaluar los criterios de consulta, MongoDB compara los tipos y los valores según sus propias » reglas de comparación para los tipos BSON, que difieren de las reglas de comparación y de manipulación de tipos de PHP. Al hacer coincidir un tipo BSON especial, los criterios de consulta deben utilizar la clase BSON (ej.: utilizar MongoDB\BSON\ObjectId para hacer coincidir un » ObjectId).

`options`

  Opciones de RewrapManyDataKey
  Opción | Tipo | Descripción
  --- | --- | ---
  provider | string | El proveedor KMS (por ejemplo, `"local"`, `"aws"`) que se utilizará para volver a cifrar las claves de datos coincidentes. Si no se especifica un proveedor KMS, las claves de datos coincidentes se volverán a cifrar con su proveedor KMS actual.
  masterKey | array | La clave maestra identifica una clave específica del KMS utilizada para cifrar la nueva clave de datos. Esta opción no debe especificarse sin la opción `"provider"`. Esta opción es obligatoria si se especifica `"provider"` y no es `"local"`.
  Opciones del proveedor `"aws"`
  Opción | Tipo | Descripción
  --- | --- | ---
  region | string | Requis.
  key | string | Requis. El nombre de recurso Amazon (ARN) de la clave maestra del cliente AWS (CMK).
  endpoint | string | Opcional. Un identificador de host alternativo para enviar las solicitudes KMS. Puede incluir el número de puerto.
  Opciones del proveedor `"azure"`
  Opción | Tipo | Descripción
  --- | --- | ---
  keyVaultEndpoint | string | Requis. Host con puerto opcional (por ejemplo, "example.vault.azure.net").
  keyName | string | Requis.
  keyVersion | string | Opcional. Una versión específica de la clave nombrada. Por omisión, se utiliza la versión primaria de la clave.
  Opciones del proveedor `"gcp"`
  Opción | Tipo | Descripción
  --- | --- | ---
  projectId | string | Requis.
  location | string | Requis.
  keyRing | string | Requis.
  keyName | string | Requis.
  keyVersion | string | Opcional. Una versión específica de la clave nombrada. Por omisión, se utiliza la versión primaria de la clave.
  endpoint | string | Opcional. Host con puerto opcional. El valor por omisión es "cloudkms.googleapis.com".
  Opciones del proveedor `"kmip"`
  Opción | Tipo | Descripción
  --- | --- | ---
  keyId | string | Opcional. Identificador único de un objeto gestionado de 96 bytes de datos secretos KMIP. Si no se especifica, el controlador crea un objeto gestionado aleatorio de 96 bytes de datos secretos KMIP.
  endpoint | string | Opcional. Host con puerto opcional.
  delegated | bool | Opcional. Si es verdadero, esta clave debe ser descifrada por el servidor KMIP.

### Valores devueltos

Devuelve un objeto que tendrá una propiedad opcional `bulkWriteResult` que contiene el resultado de la operación interna `bulkWrite` como un objeto. Si ninguna clave de datos coincidió con el filtro o la escritura no fue reconocida, la propiedad `bulkWriteResult` será `null`.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza MongoDB\Driver\Exception\EncryptionException si ocurre un error al descifrar o volver a cifrar una clave de datos.
- Lanza MongoDB\Driver\Exception\RuntimeException en otros errores.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.20.0 | Se añadió `"delegated"` a las opciones de clave maestra del proveedor KMIP.

## Tabla de contenidos

- MongoDB\Driver\ClientEncryption::addKeyAltName — Añade un nombre alternativo a un documento de clave
- MongoDB\Driver\ClientEncryption::__construct — Crea un nuevo objeto ClientEncryption
- MongoDB\Driver\ClientEncryption::createDataKey — Crea un documento de clave
- MongoDB\Driver\ClientEncryption::decrypt — Descifra un valor
- MongoDB\Driver\ClientEncryption::deleteKey — Elimina un documento de clave
- MongoDB\Driver\ClientEncryption::encrypt — Cifra un valor
- MongoDB\Driver\ClientEncryption::encryptExpression — Cifra una expresión de coincidencia o agregación
- MongoDB\Driver\ClientEncryption::getKey — Obtiene un documento de clave
- MongoDB\Driver\ClientEncryption::getKeyByAltName — Obtiene un documento de clave por un nombre alternativo
- MongoDB\Driver\ClientEncryption::getKeys — Obtiene todos los documentos de claves
- MongoDB\Driver\ClientEncryption::removeKeyAltName — Elimina un nombre alternativo de un documento de clave
- MongoDB\Driver\ClientEncryption::rewrapManyDataKey — Reenvuelve claves de datos

# La clase MongoDB\Driver\ServerApi

(mongodb >=1.10.0)

## Introducción

## Sinopsis de la Clase

final class MongoDB\Driver\ServerApi implements MongoDB\BSON\Serializable, Serializable {
/* Constantes */
const string MongoDB\Driver\ServerAPI::V1 = "1";
/* Métodos */
final public function bsonSerialize(): stdClass
final public function __construct(string `$version`, ?bool `$strict` = `null`, ?bool `$deprecationErrors` = `null`)
}

## Constantes predefinidas

`MongoDB\Driver\ServerApi::V1`
  Versión 1 de la API del servidor.

## Ejemplos

Ejemplo #1 Declarar una versión de API en un gestor

    <?php

    use MongoDB\Driver\Manager;
    use MongoDB\Driver\ServerApi;

    $v1 = new ServerApi(ServerApi::v1);
    $manager = new Manager('mongodb://localhost:27017', [], ['serverApi' => $v1]);

    $command = new MongoDB\Driver\Command(['buildInfo' => 1]);

    try {
        $cursor = $manager->executeCommand('admin', $command);
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }

    /* El comando buildInfo devuelve un único documento de resultado, por lo que
     * necesitamos acceder al primer resultado en el cursor. */
    $buildInfo = $cursor->toArray()[0];

    echo $buildInfo->version, "\n";

    ?>

El ejemplo anterior mostrará:

    4.9.0-alpha7-49-gb968ca0

Ejemplo #2 Declarar una versión estricta de API en un gestor

El siguiente ejemplo establece la `strict` flag, que indica al servidor que rechace cualquier comando que no forme parte de la versión de API declarada. Esto genera un error al ejecutar el comando buildInfo.

    <?php

    use MongoDB\Driver\Manager;
    use MongoDB\Driver\ServerApi;

    $v1 = new ServerApi(ServerApi::v1, true);
    $manager = new Manager('mongodb://localhost:27017', [], ['serverApi' => $v1]);

    $command = new MongoDB\Driver\Command(['buildInfo' => 1]);

    try {
        $cursor = $manager->executeCommand('admin', $command);
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }

    /* El comando buildInfo devuelve un único documento de resultado, por lo que
     * necesitamos acceder al primer resultado en el cursor. */
    $buildInfo = $cursor->toArray()[0];

    echo $buildInfo->version, "\n";

    ?>

El ejemplo anterior mostrará:

    Provided apiStrict:true, but the command buildInfo is not in API Version 1

# MongoDB\Driver\ServerApi::bsonSerialize

(mongodb >=1.10.0)

MongoDB\Driver\ServerApi::bsonSerialize — Devuelve un objeto para la serialización BSON

### Descripción

final public function MongoDB\Driver\ServerApi::bsonSerialize(): stdClass

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un objeto para la serialización del ServerApi en BSON.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\BSON\Serializable::bsonSerialize() - Proporciona un array o documento para serializar como BSON

# MongoDB\Driver\ServerApi::__construct

(mongodb >=1.10.0)

MongoDB\Driver\ServerApi::__construct — Crear una nueva instancia de ServerApi

### Descripción

final public function MongoDB\Driver\ServerApi::__construct(string `$version`, ?bool `$strict` = `null`, ?bool `$deprecationErrors` = `null`)

Crear una nueva instancia de MongoDB\Driver\ServerApi utilizada para declarar una versión de API al crear un MongoDB\Driver\Manager.

### Parámetros

`version`
  Una versión de API de servidor. Las versiones de API admitidas se proporcionan como constantes en MongoDB\Driver\ServerApi. La única versión de API admitida es `MongoDB\Driver\ServerApi::V1`.
`strict`
  Si el parámetro `strict` se establece en `true`, el servidor devolverá un error para cualquier comando que no forme parte de la versión de API especificada. Si no se proporciona ningún valor, se utiliza el valor predeterminado del servidor (`false`).
`deprecationErrors`
  Si el parámetro `deprecationErrors` se establece en `true`, el servidor devolverá un error al utilizar un comando que está obsoleto en la versión de API especificada. Si no se proporciona ningún valor, se utiliza el valor predeterminado del servidor (`false`).

## Tabla de contenidos

- MongoDB\Driver\ServerApi::bsonSerialize — Devuelve un objeto para la serialización BSON
- MongoDB\Driver\ServerApi::__construct — Crear una nueva instancia de ServerApi

# La clase MongoDB\Driver\WriteConcern

(mongodb >=1.0.0)

## Introducción

MongoDB\Driver\WriteConcern describe el nivel de acuse de recibo solicitado por MongoDB para las operaciones de escritura a un `mongod` autónomo o a conjuntos de réplicas o a clusters fragmentados. En los clusters fragmentados, las instancias de `mongos` transmiten el control de escritura a los fragmentos.

## Sinopsis de la Clase

final class MongoDB\Driver\WriteConcern implements MongoDB\BSON\Serializable, Serializable {
/* Constantes */
const string MAJORITY = "majority";
/* Propiedades */
public readonly string|int|null $w;
public readonly ?bool $j;
public readonly int $wtimeout;
/* Métodos */
final public function bsonSerialize(): stdClass
final public function __construct(string|int `$w`, ?int `$wtimeout` = `null`, ?bool `$journal` = `null`)
final public function getJournal(): ?bool
final public function getW(): string|int|null
final public function getWtimeout(): int
final public function isDefault(): bool
}

## Propiedades

w
  El número de réplicas necesarias (entero correspondiente al número de nodos, la cadena `"majority"`, o el nombre de un tag de write concern personalizado), o `null` si no está definido.
j
  Indica si el journal es requerido, es decir, si las operaciones de escritura deben ser confirmadas en el journal antes de ser reconocidas, o `null` si no se especificó.
wtimeout
  El timeout de espera en milisegundos para el reconocimiento del write concern. Un valor de `0` significa esperar indefinidamente.

## Constantes predefinidas

`MongoDB\Driver\WriteConcern::MAJORITY`

  La mayoría de todos los miembros del conjunto; árbitros, los mismos no votantes, los miembros pasivos, los miembros ocultos y los miembros en espera están todos incluidos en la definición de una preocupación de escritura de la mayoría.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.3.0 | Se añadieron las propiedades públicas readonly.
PECL mongodb 1.7.0 | Implementa Serializable.
PECL mongodb 1.2.0 | Implementa MongoDB\BSON\Serializable.

# MongoDB\Driver\WriteConcern::bsonSerialize

(mongodb >=1.2.0)

MongoDB\Driver\WriteConcern::bsonSerialize — Devuelve un objeto para la serialización BSON

### Descripción

final public function MongoDB\Driver\WriteConcern::bsonSerialize(): stdClass

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un objeto para la serialización del WriteConcern en BSON.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 MongoDB\Driver\WriteConcern::bsonSerialize() con el write concern majority

    <?php

    $wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY);
    var_dump($wc->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($wc)->toRelaxedExtendedJSON();

    ?>

Resultado del ejemplo anterior es similar a:

    object(stdClass)#2 (1) {
      ["w"]=>
      string(8) "majority"
    }

    { "w" : "majority" }

Ejemplo #2 MongoDB\Driver\WriteConcern::bsonSerialize() con el wtimeout y el journal

    <?php

    $wc = new MongoDB\Driver\WriteConcern(2, 1000, true);
    var_dump($wc->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($wc)->toRelaxedExtendedJSON();

    ?>

Resultado del ejemplo anterior es similar a:

    object(stdClass)#2 (3) {
      ["w"]=>
      int(2)
      ["j"]=>
      bool(true)
      ["wtimeout"]=>
      int(1000)
    }

    { "w" : 2, "j" : true, "wtimeout" : 1000 }

### Ver también

- MongoDB\BSON\Serializable::bsonSerialize() - Proporciona un array o documento para serializar como BSON
- » Referencia de Write Concern

# MongoDB\Driver\WriteConcern::__construct

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::__construct — Construye un WriteConcern

### Descripción

final public function MongoDB\Driver\WriteConcern::__construct(string|int `$w`, ?int `$wtimeout` = `null`, ?bool `$journal` = `null`)

Construye un nuevo MongoDB\Driver\WriteConcern, que es un objeto de valor inmutable.

### Parámetros

`w`

  Preocupación de escritura
  Valor | Descripción
  --- | ---
  1 | Solicita el acuse de recibo de que la operación de escritura se ha propagado al `mongod` autónomo o al principal en un conjunto de réplicas. Es la preocupación de escritura por omisión para MongoDB.
  0 | No solicita ningún acuse de recibo de la operación de escritura. Sin embargo, puede devolver información sobre las excepciones de socket y los errores de red a la aplicación.
  <entero superior a 1> | Los números superiores a 1 son válidos únicamente para los conjuntos de réplicas para solicitar el acuse de recibo del número especificado de miembros, incluyendo el principal.
  `MongoDB\Driver\WriteConcern::MAJORITY` | Solicita el acuse de recibo de que las operaciones de escritura se han propagado a la mayoría de los nodos votantes, incluyendo el principal, y han sido escritas en el journal en disco para esos nodos. Antes de MongoDB 3.0, es la mayoría de los miembros del conjunto de réplicas (y no solo de los nodos votantes).
  string | Un valor de string es interpretado como un conjunto de etiquetas. Solicita el acuse de recibo de que las operaciones de escritura se han propagado a un miembro del conjunto de réplicas con la etiqueta especificada.

`wtimeout`
  Tiempo máximo de espera (en milisegundos) antes de que los secundarios fallen. `wtimeout` hará que las operaciones de escritura devuelvan un error (WriteConcernError) después del tiempo especificado. Cuando estas operaciones de escritura devuelvan, MongoDB no cancelará los datos modificados antes de que las preocupaciones de escritura alcancen el tiempo límite `wtimeout`. Si se especifica, `wtimeout` debe ser un entero con signo de 64 bits mayor o igual a cero.

  Tiempo máximo de espera de las preocupaciones de escritura
  Valor | Descripción
  --- | ---
  0 | Bloquea indefinidamente. Es el comportamiento por omisión.
  <entero superior a 0> | Número de milisegundos a esperar antes de devolver.

`journal`
  Espera antes de que mongod aplique la escritura al journal.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si `w` es inválido o `wtimeout` es negativo o superior a los límites de un entero con signo de 32 bits.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.7.0 | El parámetro `wTimeout` acepta ahora valores de 64 bits.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\Driver\WriteConcern::__construct()

    <?php

    /* Solicita una confirmación de las solicitudes de escritura para la mayoría de los nodos
       del conjunto de réplicas */
    $wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 500);

    /* Solicita una confirmación de las solicitudes de escritura, configurada por la etiqueta
       "MultipleDC" */
    $wc = new MongoDB\Driver\WriteConcern("MultipleDC", 500);

    ?>

### Ver también

- » Write Concern reference

# MongoDB\Driver\WriteConcern::getJournal

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getJournal — Devuelve la opción "journal" del WriteConcern

### Descripción

final public function MongoDB\Driver\WriteConcern::getJournal(): ?bool

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la opción "journal" del WriteConcern.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\WriteConcern::getJournal()

    <?php

    $wc = new MongoDB\Driver\WriteConcern(1);
    var_dump($wc->getJournal());

    $wc = new MongoDB\Driver\WriteConcern(1, 0, true);
    var_dump($wc->getJournal());

    $wc = new MongoDB\Driver\WriteConcern(1, 0, false);
    var_dump($wc->getJournal());

    ?>

El ejemplo anterior mostrará:

    NULL
    bool(true)
    bool(false)

### Ver también

- » Referencia de Write Concern

# MongoDB\Driver\WriteConcern::getW

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getW — Devuelve la opción "w" del WriteConcern

### Descripción

final public function MongoDB\Driver\WriteConcern::getW(): string|int|null

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la opción "w" del WriteConcern.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\WriteConcern::getW()

    <?php

    $wc = new MongoDB\Driver\WriteConcern(1);
    var_dump($wc->getW());

    $wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY);
    var_dump($wc->getW());

    ?>

El ejemplo anterior mostrará:

    int(1)
    string(8) "majority"

### Ver también

- » Referencia de Write Concern

# MongoDB\Driver\WriteConcern::getWtimeout

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getWtimeout — Devuelve la opción "wtimeout" del WriteConcern

### Descripción

final public function MongoDB\Driver\WriteConcern::getWtimeout(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la opción "wtimeout" del WriteConcern.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.7.0 | En sistemas de 32 bits, este método siempre truncará el valor `wTimeout` si excede el rango de 32 bits. En tal caso, se emitirá una advertencia.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\WriteConcern::getWtimeout()

    <?php

    $wc = new MongoDB\Driver\WriteConcern(1);
    var_dump($wc->getWtimeout());

    $wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 3000);
    var_dump($wc->getWtimeout());

    ?>

El ejemplo anterior mostrará:

    int(0)
    int(3000)

### Ver también

- » Referencia de Write Concern

# MongoDB\Driver\WriteConcern::isDefault

(mongodb >=1.3.0)

MongoDB\Driver\WriteConcern::isDefault — Verifica si es el WriteConcern por omisión

### Descripción

final public function MongoDB\Driver\WriteConcern::isDefault(): bool

Devuelve si es el WriteConcern por omisión (es decir, sin opciones especificadas). Este método está principalmente destinado a ser utilizado en conjunción con MongoDB\Driver\Manager::getWriteConcern() para determinar si el Manager ha sido construido sin ninguna opción de WriteConcern.

El controlador no incluirá un WriteConcern por omisión en sus operaciones de escritura (por ejemplo MongoDB\Driver\Manager::executeBulkWrite()) para permitir que el servidor aplique su propio WriteConcern por omisión, que puede haber sido » modificado. Las bibliotecas que acceden al WriteConcern del Manager para incluirlo en sus propios comandos de escritura deberían utilizar este método para asegurarse de que los WriteConcern por omisión no están definidos.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si es el WriteConcern por omisión y `false` en caso contrario.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\WriteConcern::isDefault()

    <?php

    $wc = new MongoDB\Driver\WriteConcern(1);
    var_dump($wc->isDefault());

    $manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/?w=majority');
    $wc = $manager->getWriteConcern();
    var_dump($wc->isDefault());

    $manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/');
    $wc = $manager->getWriteConcern();
    var_dump($wc->isDefault());

    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(false)
    bool(true)

### Ver también

- MongoDB\Driver\Manager::getWriteConcern() - Devuelve el WriteConcern para el Manager
- » Modificar el Write Concern por omisión en el manual de MongoDB
- » Referencia de Write Concern

## Tabla de contenidos

- MongoDB\Driver\WriteConcern::bsonSerialize — Devuelve un objeto para la serialización BSON
- MongoDB\Driver\WriteConcern::__construct — Construye un WriteConcern
- MongoDB\Driver\WriteConcern::getJournal — Devuelve la opción "journal" del WriteConcern
- MongoDB\Driver\WriteConcern::getW — Devuelve la opción "w" del WriteConcern
- MongoDB\Driver\WriteConcern::getWtimeout — Devuelve la opción "wtimeout" del WriteConcern
- MongoDB\Driver\WriteConcern::isDefault — Verifica si es el WriteConcern por omisión

# La clase MongoDB\Driver\ReadPreference

(mongodb >=1.0.0)

## Introducción

## Sinopsis de la Clase

final class MongoDB\Driver\ReadPreference implements MongoDB\BSON\Serializable, Serializable {
/* Propiedades */
public readonly string $mode;
public readonly ?array $tags;
public readonly int $maxStalenessSeconds;
public readonly ?object $hedge;
/* Constantes */
const string PRIMARY = primary;
const string PRIMARY_PREFERRED = primaryPreferred;
const string SECONDARY = secondary;
const string SECONDARY_PREFERRED = secondaryPreferred;
const string NEAREST = nearest;
const int NO_MAX_STALENESS = -1;
const int SMALLEST_MAX_STALENESS_SECONDS = 90;
/* Métodos */
final public function bsonSerialize(): stdClass
final public function __construct(string `$mode`, ?array `$tagSets` = `null`, ?array `$options` = `null`)
final public function getHedge(): ?object
final public function getMaxStalenessSeconds(): int
final public function getMode(): int
final public function getModeString(): string
final public function getTagSets(): array
}

## Propiedades

mode
  El modo de preferencia de lectura como cadena (por ejemplo `"primary"`, `"secondary"`).
tags
  La lista de conjuntos de tags utilizada por la preferencia de lectura, o `null` si no se especificó ningún conjunto de tags.
maxStalenessSeconds
  La duración máxima de obsolescencia en segundos para las lecturas, o `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS` si no se especificó ninguna duración máxima de obsolescencia.
hedge
  Un documento que especifica las opciones de hedge para la preferencia de lectura, o `null` si no se especificó ninguna opción de hedge.
  Advertencia

  Esta propiedad está obsoleta ya que las lecturas con hedge están obsoletas en MongoDB 8.0.

## Constantes predefinidas

`MongoDB\Driver\ReadPreference::PRIMARY`

  Todas las operaciones se leen desde el primario actual del conjunto de réplicas. Esta es la preferencia de lectura por omisión para MongoDB.

`MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED`

  En la mayoría de las situaciones, las operaciones se leen desde el primario, pero si no está disponible, las operaciones se leen desde los miembros secundarios.

`MongoDB\Driver\ReadPreference::SECONDARY`

  Todas las operaciones se leen desde los miembros secundarios del conjunto de réplicas.

`MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED`

  En la mayoría de los casos, las operaciones se leen desde los miembros secundarios, pero si ningún miembro secundario está disponible, las operaciones se leen desde el primario.

`MongoDB\Driver\ReadPreference::NEAREST`

  Las operaciones se leen desde el miembro del conjunto de réplicas con la menor latencia de red, independientemente del tipo de miembro.

`MongoDB\Driver\ReadPreference::NO_MAX_STALENESS`

  El valor por omisión de la opción `"maxStalenessSeconds"` es no especificar ningún límite sobre la obsolescencia máxima, lo que significa que el controlador no tendrá en cuenta el desfase de un secundario al elegir dónde dirigir una operación de lectura.

`MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS`

  El valor mínimo de la opción `"maxStalenessSeconds"` es de 90 segundos. El controlador estima la obsolescencia de los segundos verificando periódicamente la última fecha de escritura de cada miembro del conjunto de réplicas. Como estos controles son poco frecuentes, la estimación de la obsolescencia es aproximada. Por lo tanto, el controlador no puede aplicar un valor de obsolescencia máxima inferior a 90 segundos.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.3.0 | Se añadieron las propiedades públicas readonly.
PECL mongodb 2.0.0 | Eliminar las constantes `MongoDB\Driver\ReadPreference::RP_PRIMARY`, `MongoDB\Driver\ReadPreference::RP_PRIMARY_PREFERRED`, `MongoDB\Driver\ReadPreference::RP_SECONDARY`, `MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED`, y `MongoDB\Driver\ReadPreference::RP_NEAREST`. El método getMode() también fue eliminado.
PECL mongodb 1.7.0 | Añadir las constantes `MongoDB\Driver\ReadPreference::PRIMARY`, `MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED`, `MongoDB\Driver\ReadPreference::SECONDARY`, `MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED`, `MongoDB\Driver\ReadPreference::NEAREST`. Implementa Serializable.
PECL mongodb 1.2.0 | Añadir las constantes `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS` y `MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS`. Implementa MongoDB\BSON\Serializable.

# MongoDB\Driver\ReadPreference::bsonSerialize

(mongodb >=1.2.0)

MongoDB\Driver\ReadPreference::bsonSerialize — Devuelve un objeto para la serialización BSON

### Descripción

final public function MongoDB\Driver\ReadPreference::bsonSerialize(): stdClass

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un objeto para la serialización de la ReadPreference en BSON.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 MongoDB\Driver\ReadPreference::bsonSerialize() con una preferencia de lectura primaria

    <?php

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
    var_dump($rp->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rp)->toRelaxedExtendedJSON();

    ?>

Resultado del ejemplo anterior es similar a:

    object(stdClass)#2 (1) {
      ["mode"]=>
      string(7) "primary"
    }

    { "mode" : "primary" }

Ejemplo #2 MongoDB\Driver\ReadPreference::bsonSerialize() con una preferencia de lectura secundaria

    <?php

    $rp = new MongoDB\Driver\ReadPreference(
        MongoDB\Driver\ReadPreference::SECONDARY,
        [
            ['dc' => 'ny'],
            ['dc' => 'sf', 'use' => 'reporting'],
            []
        ]
    );
    var_dump($rp->bsonSerialize());

    echo "\n", MongoDB\BSON\toJSON(MongoDB\BSON\fromPHP($rp));

    ?>

Resultado del ejemplo anterior es similar a:

    object(stdClass)#2 (2) {
      ["mode"]=>
      string(9) "secondary"
      ["tags"]=>
      array(3) {
        [0]=>
        object(stdClass)#1 (1) {
          ["dc"]=>
          string(2) "ny"
        }
        [1]=>
        object(stdClass)#5 (2) {
          ["dc"]=>
          string(2) "sf"
          ["use"]=>
          string(9) "reporting"
        }
        [2]=>
        object(stdClass)#4 (0) {
        }
      }
    }

    { "mode" : "secondary", "tags" : [ { "dc" : "ny" }, { "dc" : "sf", "use" : "reporting" }, {  } ] }

Ejemplo #3 MongoDB\Driver\ReadPreference::bsonSerialize() con una preferencia de lectura secundaria y un tiempo máximo de retraso

    <?php

    $rp = new MongoDB\Driver\ReadPreference(
        MongoDB\Driver\ReadPreference::SECONDARY,
        null,
        ['maxStalenessSeconds' => 120]
    );
    var_dump($rp->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rp)->toRelaxedExtendedJSON();

    ?>

Resultado del ejemplo anterior es similar a:

    object(stdClass)#2 (2) {
      ["mode"]=>
      string(9) "secondary"
      ["maxStalenessSeconds"]=>
      int(120)
    }

    { "mode" : "secondary", "maxStalenessSeconds" : 120 }

### Ver también

- MongoDB\BSON\Serializable::bsonSerialize() - Proporciona un array o documento para serializar como BSON
- » Referencia de Read Preference

# MongoDB\Driver\ReadPreference::__construct

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::__construct — Crear una nueva ReadPreference

### Descripción

final public function MongoDB\Driver\ReadPreference::__construct(string `$mode`, ?array `$tagSets` = `null`, ?array `$options` = `null`)

Construye un nuevo MongoDB\Driver\ReadPreference, que es un objeto de valor inmutable.

### Parámetros

`mode`

  Modo de preferencia de lectura
  Valor | Descripción
  --- | ---
  `"primary"` | Todas las operaciones leídas desde el conjunto de réplicas actual primario. Este es el modo de preferencia de lectura por omisión para MongoDB.
  `"primaryPreferred"` | En la mayoría de las situaciones, las operaciones son leídas desde el primario, pero si no está disponible, las operaciones son leídas desde un miembro secundario.
  `"secondary"` | Todas las operaciones son leídas desde los miembros secundarios del conjunto de réplicas.
  `"secondaryPreferred"` | En la mayoría de los casos, las operaciones son leídas por miembros secundarios, pero si ningún miembro secundario está disponible, las operaciones son leídas desde el primario.
  `"nearest"` | Operaciones leídas desde el miembro del conjunto de réplicas con la latencia de red más baja, independientemente del tipo de miembro.

`tagSets`
  Los conjuntos de etiquetas permiten dirigir las operaciones de lectura a miembros específicos de un conjunto de réplicas. Este parámetro debe ser un array de arrays asociativos, que contienen cada uno cero o más pares clave/valor. Al seleccionar un servidor para una operación de lectura, el controlador intenta seleccionar un nodo que contenga todas las etiquetas de un conjunto (es decir, el array asociativo de pares clave/valor). Si la selección falla, el controlador intentará con los siguientes conjuntos. Un conjunto de etiquetas vacío (`array()`) corresponde a cualquier nodo y puede ser utilizado como respaldo. Las etiquetas no son compatibles con el modo `"primary"` y, en general, solo se aplican cuando se selecciona un miembro secundario de un conjunto para una operación de lectura. Sin embargo, el modo `"nearest"`, cuando se combina con un conjunto de etiquetas, selecciona el miembro correspondiente con la latencia de red más baja. Este miembro puede ser primario o secundario.
`options`

  options
  Opción | Tipo | Descripción
  --- | --- | ---
  hedge | object|array | Especifica si se debe utilizar o no » las lecturas cruzadas, que son soportadas desde MongoDB 4.4+ para las consultas compartidas. El servidor de lecturas cruzadas está disponible para todas las lecturas de referencias no primarias, y está activado por omisión al utilizar el modo `"nearest"`. Esta opción permite activar explícitamente el servidor de lecturas cruzadas para las lecturas de referencias no primarias especificando `['enabled' => true]`, o desactivar explícitamente el servidor de lecturas cruzadas para las lecturas de referencias `"nearest"` especificando `['enabled' => false]`.
  maxStalenessSeconds | int | Especifica un desfase de replicación máximo, o "obsolescencia", para las lecturas de los secundarios. Cuando la obsolescencia estimada de un secundario supera este valor, el controlador deja de utilizarlo para las operaciones de lectura. Si se especifica, la obsolescencia máxima debe ser un entero signado de 32 bits mayor o igual a `MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS`. Por omisión, `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS`, lo que significa que el controlador no tendrá en cuenta el desfase de un secundario al elegir dónde dirigir una operación de lectura. Esta opción no es compatible con el modo `"primary"`. La especificación de una obsolescencia máxima requiere asimismo que todas las instancias de MongoDB del despliegue utilicen MongoDB 3.4+. Se lanzará una excepción en tiempo de ejecución si todas las instancias de MongoDB en el despliegue son de una versión de servidor más antigua.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si `mode` es incorrecto.
- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si `tagSets` es proporcionado para una preferencia de lectura primaria o es incorrecto (es decir, no es un array de cero o más documentos).
- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si la opción `"maxStalenessSeconds"` es proporcionada para una preferencia de lectura primaria o está fuera de rango.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Pasar un int para el argumento `mode` ya no es soportado.
PECL mongodb 1.20.0 | Pasar un int para el argumento `mode` está DEPRECADO.
PECL mongodb 1.8.0 | Añadida la opción `"hedge"`.
PECL mongodb 1.3.0 | El argumento `mode` acepta ahora un valor de string, que es compatible con la opción URI `"readPreference"` para MongoDB\Driver\Manager::__construct()
PECL mongodb 1.2.0 | Añadido un tercer argumento de `options`, que soporta la opción `"maxStalenessSeconds"`.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\Driver\ReadPreference::__construct()

    <?php

    /* Prefiera un nodo secundario pero recurra a un primario. */
    var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED));

    /* Prefiera un nodo en el centro de datos de Nueva York con la latencia más baja. */
    var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::NEAREST, [['dc' => 'ny']]));

    /* Requiere un nodo secundario cuyo desfase de replicación se encuentre dentro de los dos minutos */
    var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, ['maxStalenessSeconds' => 120]));

    /* Activa explícitamente el servidor de lecturas cruzadas */
    var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, ['hedge' => ['enabled' => true]]));
    ?>

Resultado del ejemplo anterior es similar a:

    object(MongoDB\Driver\ReadPreference)#1 (1) {
      ["mode"]=>
      string(18) "secondaryPreferred"
    }
    object(MongoDB\Driver\ReadPreference)#1 (2) {
      ["mode"]=>
      string(7) "nearest"
      ["tags"]=>
      array(1) {
        [0]=>
        object(stdClass)#2 (1) {
          ["dc"]=>
          string(2) "ny"
        }
      }
    }
    object(MongoDB\Driver\ReadPreference)#1 (2) {
      ["mode"]=>
      string(9) "secondary"
      ["maxStalenessSeconds"]=>
      int(120)
    }
    object(MongoDB\Driver\ReadPreference)#1 (2) {
      ["mode"]=>
      string(9) "secondary"
      ["hedge"]=>
      object(stdClass)#1 (1) {
        ["enabled"]=>
        bool(true)
      }
    }

### Ver también

- » Read Preference reference

# MongoDB\Driver\ReadPreference::getHedge

(mongodb >=1.8.0)

MongoDB\Driver\ReadPreference::getHedge — Devuelve la opción "hedge" del ReadPreference

### Descripción

final public function MongoDB\Driver\ReadPreference::getHedge(): ?object

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la opción "hedge" del ReadPreference.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- » Referencia de Read Preference

# MongoDB\Driver\ReadPreference::getMaxStalenessSeconds

(mongodb >=1.2.0)

MongoDB\Driver\ReadPreference::getMaxStalenessSeconds — Devuelve la opción "maxStalenessSeconds" del ReadPreference

### Descripción

final public function MongoDB\Driver\ReadPreference::getMaxStalenessSeconds(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la opción "maxStalenessSeconds" del ReadPreference. Si no se ha especificado ningún tiempo máximo, `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS` será devuelto.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\ReadPreference::getMaxStalenessSeconds()

    <?php

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY);
    var_dump($rp->getMaxStalenessSeconds());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, [
        'maxStalenessSeconds' => MongoDB\Driver\ReadPreference::NO_MAX_STALENESS,
    ]);
    var_dump($rp->getMaxStalenessSeconds());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, [
        'maxStalenessSeconds' => MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS,
    ]);
    var_dump($rp->getMaxStalenessSeconds());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, [
        'maxStalenessSeconds' => 1000,
    ]);
    var_dump($rp->getMaxStalenessSeconds());

    ?>

El ejemplo anterior mostrará:

    int(-1)
    int(-1)
    int(90)
    int(1000)

### Ver también

- » Referencia de Read Preference

# MongoDB\Driver\ReadPreference::getMode

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::getMode — Devuelve la opción "mode" del ReadPreference

Advertencia

Esta función ha sido DEPRECADA desde la versión 1.20.0 de la extensión y ha sido eliminada en la versión 2.0. Las aplicaciones deberían utilizar MongoDB\Driver\ReadPreference::getModeString() en su lugar.

### Descripción

final public function MongoDB\Driver\ReadPreference::getMode(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la opción "mode" del ReadPreference.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Este método ha sido eliminado.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\ReadPreference::getMode()

    <?php

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::NEAREST);
    var_dump($rp->getMode());

    ?>

El ejemplo anterior mostrará:

    int(1)
    int(5)
    int(2)
    int(6)
    int(10)

### Ver también

- MongoDB\Driver\ReadPreference::getModeString() - Devuelve la opción "mode" del ReadPreference
- » Referencia de Read Preference

# MongoDB\Driver\ReadPreference::getModeString

(mongodb >=1.7.0)

MongoDB\Driver\ReadPreference::getModeString — Devuelve la opción "mode" del ReadPreference

### Descripción

final public function MongoDB\Driver\ReadPreference::getModeString(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la opción "mode" del ReadPreference como string.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\ReadPreference::getModeString()

    <?php

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
    var_dump($rp->getModeString());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED);
    var_dump($rp->getModeString());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY);
    var_dump($rp->getModeString());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED);
    var_dump($rp->getModeString());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::NEAREST);
    var_dump($rp->getModeString());

    ?>

El ejemplo anterior mostrará:

    string(7) "primary"
    string(16) "primaryPreferred"
    string(9) "secondary"
    string(18) "secondaryPreferred"
    string(7) "nearest"

### Ver también

- MongoDB\Driver\ReadPreference::getMode() - Devuelve la opción "mode" del ReadPreference
- » Referencia de Read Preference

# MongoDB\Driver\ReadPreference::getTagSets

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::getTagSets — Devuelve la opción "tagSets" de ReadPreference

### Descripción

final public function MongoDB\Driver\ReadPreference::getTagSets(): array

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la opción "tagSets" de ReadPreference.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\ReadPreference::getTagSets()

    <?php

    $mode = MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED;

    /* Null y un array vacío indican ambos la ausencia de preferencia de conjunto de etiquetas. */
    $rp = new MongoDB\Driver\ReadPreference($mode, null);
    var_dump($rp->getTagSets());

    $rp = new MongoDB\Driver\ReadPreference($mode, []);
    var_dump($rp->getTagSets());

    /* Preferir un nodo en Nueva York, pero volver a cualquier nodo disponible. */
    $rp = new MongoDB\Driver\ReadPreference($mode, [['dc' => 'ny']]);
    var_dump($rp->getTagSets());

    /* Preferir un nodo en Nueva York, seguido de un nodo en San Francisco
       etiquetado para el reporting, y finalmente volver a cualquier nodo disponible. */
    $rp = new MongoDB\Driver\ReadPreference($mode, [
      ['dc' => 'ny'],
      ['dc' => 'sf', 'use' => 'reporting'],
      [],
    ]);
    var_dump($rp->getTagSets());

    ?>

El ejemplo anterior mostrará:

    array(0) {
    }
    array(0) {
    }
    array(2) {
      [0]=>
      array(1) {
        ["dc"]=>
        string(2) "ny"
      }
      [1]=>
      array(0) {
      }
    }
    array(3) {
      [0]=>
      array(1) {
        ["dc"]=>
        string(2) "ny"
      }
      [1]=>
      array(2) {
        ["dc"]=>
        string(2) "sf"
        ["use"]=>
        string(9) "reporting"
      }
      [2]=>
      array(0) {
      }
    }

### Ver también

- » Referencia de Read Preference

## Tabla de contenidos

- MongoDB\Driver\ReadPreference::bsonSerialize — Devuelve un objeto para la serialización BSON
- MongoDB\Driver\ReadPreference::__construct — Crear una nueva ReadPreference
- MongoDB\Driver\ReadPreference::getHedge — Devuelve la opción "hedge" del ReadPreference
- MongoDB\Driver\ReadPreference::getMaxStalenessSeconds — Devuelve la opción "maxStalenessSeconds" del ReadPreference
- MongoDB\Driver\ReadPreference::getMode — Devuelve la opción "mode" del ReadPreference
- MongoDB\Driver\ReadPreference::getModeString — Devuelve la opción "mode" del ReadPreference
- MongoDB\Driver\ReadPreference::getTagSets — Devuelve la opción "tagSets" de ReadPreference

# La clase MongoDB\Driver\ReadConcern

(mongodb >=1.1.0)

## Introducción

MongoDB\Driver\ReadConcern controla el nivel de aislamiento para las operaciones de lectura para los conjuntos de réplicas y las réplicas de réplicas. Esta opción requiere MongoDB 3.2 o posterior.

## Sinopsis de la Clase

final class MongoDB\Driver\ReadConcern implements MongoDB\BSON\Serializable, Serializable {
/* Propiedades */
public readonly ?string $level;
/* Constantes */
const string AVAILABLE = "available";
const string LINEARIZABLE = "linearizable";
const string LOCAL = "local";
const string MAJORITY = "majority";
const string SNAPSHOT = "snapshot";
/* Métodos */
final public function bsonSerialize(): stdClass
final public function __construct(?string `$level` = `null`)
final public function getLevel(): ?string
final public function isDefault(): bool
}

## Propiedades

level
  El nivel del read concern. `null` si no se especificó ningún nivel.

## Constantes predefinidas

`MongoDB\Driver\ReadConcern::AVAILABLE`

  Por omisión para las lecturas en los secundarios cuando `afterClusterTime` y `level` no están especificados.

  La consulta devuelve los datos más recientes de la instancia. No garantiza que los datos hayan sido escritos en la mayoría de los miembros del conjunto de réplicas (es decir, que puedan ser anulados).

  Para las colecciones no fragmentadas (incluyendo las colecciones en un despliegue autónomo o un despliegue de réplicas), las lecturas `"local"` y `"available"` se comportan de manera idéntica.

  Para un clúster compartido, la lectura `"available"` proporciona una mayor tolerancia a las particiones ya que no espera para garantizar garantías de coherencia. Sin embargo, una consulta con una lectura `"available"` puede devolver documentos huérfanos si el fragmento está en proceso de migración de piezas ya que la lectura `"available"`, a diferencia de la lectura `"local"`, no contacta al primario del fragmento ni a los servidores de configuración para obtener metadatos actualizados.

`MongoDB\Driver\ReadConcern::LINEARIZABLE`

  La consulta devuelve los datos que reflejan todas las escrituras exitosas emitidas con un nivel de escritura de `"majority"` y reconocido antes del inicio de la operación de lectura. Para los conjuntos de réplicas que funcionan con `writeConcernMajorityJournalDefault` definido en `true`, la lectura linealizable devuelve datos que nunca serán anulados.

  Con `writeConcernMajorityJournalDefault` definido en `false`, MongoDB no esperará que las escrituras `w: "majority"` sean durables antes de acusar recibo de las escrituras. En consecuencia, las operaciones de escritura `"majority"` podrían eventualmente ser anuladas en caso de pérdida de un miembro del conjunto de réplicas.

  Se puede especificar un nivel de lectura linealizable para las operaciones de lectura en el primario únicamente.

  La lectura linealizable garantiza que las operaciones de lectura especifiquen un filtro de consulta que identifique de manera única un solo documento.

  Sugerencia

  Siempre utilizar `maxTimeMS` con una lectura linealizable en caso de no disponibilidad de la mayoría de los miembros portadores de datos. `maxTimeMS` garantiza que la operación no bloquee indefinidamente y garantiza que la operación devuelva un error si el nivel de lectura no puede ser satisfecho.

  La lectura linealizable requiere MongoDB 3.4.

`MongoDB\Driver\ReadConcern::LOCAL`

  Por omisión para las lecturas en el primario si `level` no está especificado y para las lecturas en los secundarios si `level` no está especificado pero `afterClusterTime` está especificado.

  La consulta devuelve los datos más recientes de la instancia. No garantiza que los datos hayan sido escritos en la mayoría de los miembros del conjunto de réplicas (es decir, que puedan ser anulados).

`MongoDB\Driver\ReadConcern::MAJORITY`

  La consulta devuelve los datos más recientes reconocidos como haber sido escritos en la mayoría de los miembros del conjunto de réplicas.

  Para utilizar el nivel de lectura `"majority"`, los conjuntos de réplicas deben utilizar el motor de almacenamiento WiredTiger y el protocolo de elección versión 1.

`MongoDB\Driver\ReadConcern::SNAPSHOT`

  La lectura `"snapshot"` está disponible para las transacciones multi-documentos, y a partir de MongoDB 5.0, para ciertas operaciones de lectura fuera de las transacciones multi-documentos.

  Si la transacción no forma parte de una sesión coherente, al validar la transacción con un nivel de escritura `"majority"`, las operaciones de transacción están garantizadas de haber leído desde una instantánea de datos mayoritariamente comprometidos.

  Si la transacción forma parte de una sesión coherente, al validar la transacción con un nivel de escritura `"majority"`, las operaciones de transacción están garantizadas de haber leído desde una instantánea de datos mayoritariamente comprometidos que aseguran la coherencia causal con la operación inmediatamente anterior al inicio de la transacción.

  Fuera de las transacciones multi-documentos, el nivel de lectura `"snapshot"` está disponible en los primarios y los secundarios para las siguientes operaciones de lectura: `find`, `aggregate` y `distinct` (en colecciones no fragmentadas). Todas las demás órdenes de lectura prohíben `"snapshot"`.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.3.0 | Se añadieron las propiedades públicas readonly.
PECL mongodb 1.11.0 | Adición de la constante `MongoDB\Driver\ReadConcern::SNAPSHOT`.
PECL mongodb 1.7.0 | Implementa Serializable.
PECL mongodb 1.4.0 | Adición de la constante `MongoDB\Driver\ReadConcern::MAJORITY`.
PECL mongodb 1.2.0 | Adición de la constante `MongoDB\Driver\ReadConcern::LINEARIZABLE` Implementa MongoDB\BSON\Serializable.

## Ver también

- » Referencia de lectura

# MongoDB\Driver\ReadConcern::bsonSerialize

(mongodb >=1.2.0)

MongoDB\Driver\ReadConcern::bsonSerialize — Devuelve un objeto para la serialización BSON

### Descripción

final public function MongoDB\Driver\ReadConcern::bsonSerialize(): stdClass

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un objeto para la serialización del ReadConcern en BSON.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 MongoDB\Driver\ReadConcern::bsonSerialize() con un read concern vacío

    <?php

    $rc = new MongoDB\Driver\ReadConcern;
    var_dump($rc->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rc)->toRelaxedExtendedJSON();

    ?>

Resultado del ejemplo anterior es similar a:

    object(stdClass)#2 (0) {
    }

    { }

Ejemplo #2 MongoDB\Driver\ReadConcern::bsonSerialize() con un read concern local

    <?php

    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::LOCAL);
    var_dump($rc->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rc)->toRelaxedExtendedJSON();

    ?>

Resultado del ejemplo anterior es similar a:

    object(stdClass)#2 (1) {
      ["level"]=>
      string(5) "local"
    }

    { "level" : "local" }

### Ver también

- MongoDB\BSON\Serializable::bsonSerialize() - Proporciona un array o documento para serializar como BSON
- » Referencia de Read Concern

# MongoDB\Driver\ReadConcern::__construct

(mongodb >=1.0.0)

MongoDB\Driver\ReadConcern::__construct — Crear un nuevo ReadConcern

### Descripción

final public function MongoDB\Driver\ReadConcern::__construct(?string `$level` = `null`)

Construye un nuevo MongoDB\Driver\ReadConcern, que es un objeto de valor inmutable.

### Parámetros

`level`
  El » nivel del read concern. Se puede utilizar, pero no se limita a, una de las constantes de clase.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\ReadConcern::__construct()

    <?php

    /* Nivel de lectura aislado no especificado (utiliza el comportamiento por omisión del servidor) */
    $rc = new MongoDB\Driver\ReadConcern();

    /* Consulta con un nivel de lectura aislado a partir de un solo nodo del conjunto de réplicas */
    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::LOCAL);

    /* Consulta con un nivel de lectura aislado a partir de una mayoría de los nodos del conjunto de réplicas */
    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY);

    ?>

### Ver también

- » Referencia de Read Concern

# MongoDB\Driver\ReadConcern::getLevel

(mongodb >=1.0.0)

MongoDB\Driver\ReadConcern::getLevel — Devuelve la opción "level" del ReadConcern

### Descripción

final public function MongoDB\Driver\ReadConcern::getLevel(): ?string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la opción "level" del ReadConcern.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\ReadConcern::getLevel()

    <?php

    $rc = new MongoDB\Driver\ReadConcern();
    var_dump($rc->getLevel());

    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::LOCAL);
    var_dump($rc->getLevel());

    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY);
    var_dump($rc->getLevel());

    ?>

El ejemplo anterior mostrará:

    NULL
    string(5) "local"
    string(8) "majority"

### Ver también

- » Referencia de Read Concern

# MongoDB\Driver\ReadConcern::isDefault

(mongodb >=1.3.0)

MongoDB\Driver\ReadConcern::isDefault — Verifica si es el read concern por omisión

### Descripción

final public function MongoDB\Driver\ReadConcern::isDefault(): bool

Devuelve si es el read concern por omisión (es decir, sin opciones especificadas). Este método está principalmente destinado a ser utilizado en conjunción con MongoDB\Driver\Manager::getReadConcern() para determinar si el Manager ha sido construido sin ninguna opción de read concern.

El controlador no incluirá un read concern por omisión en sus operaciones de lectura (por ejemplo MongoDB\Driver\Manager::executeQuery()) para permitir que el servidor aplique su propio valor por omisión. Las bibliotecas que acceden al read concern del Manager para incluirlo en sus propios comandos de lectura deberían utilizar este método para asegurarse de que los read concerns por omisión se dejan sin definir.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si es el read concern por omisión y `false` en caso contrario.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\ReadConcern::isDefault()

    <?php

    $rc = new MongoDB\Driver\ReadConcern(null);
    var_dump($rc->isDefault());

    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY);
    var_dump($rc->isDefault());

    $manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/?readConcernLevel=majority');
    $rc = $manager->getReadConcern();
    var_dump($rc->isDefault());

    $manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/');
    $rc = $manager->getReadConcern();
    var_dump($rc->isDefault());

    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(false)
    bool(false)
    bool(true)

### Ver también

- MongoDB\Driver\Manager::getReadConcern() - Devuelve el ReadConcern para el Manager
- » Referencia de Read Concern

## Tabla de contenidos

- MongoDB\Driver\ReadConcern::bsonSerialize — Devuelve un objeto para la serialización BSON
- MongoDB\Driver\ReadConcern::__construct — Crear un nuevo ReadConcern
- MongoDB\Driver\ReadConcern::getLevel — Devuelve la opción "level" del ReadConcern
- MongoDB\Driver\ReadConcern::isDefault — Verifica si es el read concern por omisión

# La clase MongoDB\Driver\Cursor

(mongodb >=1.0.0)

## Introducción

La clase MongoDB\Driver\Cursor encapsula los resultados de un comando o consulta de MongoDB y puede ser devuelta por MongoDB\Driver\Manager::executeCommand() o MongoDB\Driver\Manager::executeQuery(), respectivamente.

## Sinopsis de la Clase

final class MongoDB\Driver\Cursor implements MongoDB\Driver\CursorInterface {
/* Métodos */
final private function __construct()
public function current(): array|object|null
final public function getId(): MongoDB\BSON\Int64
final public function getServer(): MongoDB\Driver\Server
final public function isDead(): bool
public function key(): int
public function next(): void
public function rewind(): void
final public function setTypeMap(array `$typemap`): void
final public function toArray(): array
public function valid(): bool
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.9.0 | Implementa Iterator.
PECL mongodb 1.6.0 | Implementa MongoDB\Driver\CursorInterface, que extiende Traversable.

## Ejemplos

Ejemplo #1 Lectura de un conjunto de resultados

MongoDB\Driver\Manager::executeCommand() y MongoDB\Driver\Manager::executeQuery() devuelven sus resultados como un objeto MongoDB\Driver\Cursor. Este objeto puede usarse para iterar sobre el conjunto de resultados del comando o consulta.

Dado que MongoDB\Driver\Cursor implementa la interfaz Traversable, puede simplemente iterar sobre el conjunto de resultados con `foreach`.

    <?php

    $manager = new MongoDB\Driver\Manager();

    /* Insertar algunos documentos para que nuestra consulta devuelva información */
    $bulkWrite = new MongoDB\Driver\BulkWrite;
    $bulkWrite->insert(['name' => 'Ceres', 'size' => 946, 'distance' => 2.766]);
    $bulkWrite->insert(['name' => 'Vesta', 'size' => 525, 'distance' => 2.362]);
    $manager->executeBulkWrite("test.asteroids", $bulkWrite);

    /* Consultar todos los elementos de la colección */
    $query = new MongoDB\Driver\Query( [] );

    /* Consultar la colección "asteroids" de la base de datos "test" */
    $cursor = $manager->executeQuery("test.asteroids", $query);

    /* $cursor ahora contiene un objeto que envuelve el conjunto de resultados. Usar
     * foreach() para iterar sobre todos los resultados */
    foreach($cursor as $document) {
        print_r($document);
    }

    ?>

Resultado del ejemplo anterior es similar a:

    stdClass Object
    (
        [_id] => MongoDB\BSON\ObjectId Object
            (
                [oid] => 5a4cff2f122d3321565d8cc2
            )

        [name] => Ceres
        [size] => 946
        [distance] => 2.766
    )
    stdClass Object
    (
        [_id] => MongoDB\BSON\ObjectId Object
            (
                [oid] => 5a4cff2f122d3321565d8cc3
            )

        [name] => Vesta
        [size] => 525
        [distance] => 2.362
    )

Ejemplo #2 Lectura de un conjunto de resultados para un cursor rastreable

Los » cursores rastreables son un tipo especial de cursor de MongoDB que permite al cliente leer algunos resultados y luego esperar hasta que haya más documentos disponibles. Estos cursores se usan principalmente con » colecciones limitadas y » flujos de cambios.

Mientras que los cursores normales pueden iterarse una vez con `foreach`, ese enfoque no funcionará con cursores rastreables. Cuando se usa `foreach` con un cursor rastreable, el bucle terminará al llegar al final del conjunto de resultados inicial. Intentar continuar la iteración en el cursor con un segundo `foreach` lanzaría una excepción, ya que PHP intenta retroceder el cursor. Al igual que los objetos de resultado en otros controladores de bases de datos, los cursores en MongoDB solo admiten la iteración hacia adelante, lo que significa que no pueden retrocederse.

Para leer de forma continua desde un cursor rastreable, el objeto Cursor debe envolverse con un IteratorIterator. Esto permite que la aplicación controle directamente la iteración del cursor, evite retroceder el cursor sin querer y decida cuándo esperar nuevos resultados o detener completamente la iteración.

Para demostrar un cursor rastreable en acción, se usarán dos scripts: un "productor" y un "consumidor". El script productor creará una nueva colección limitada usando el comando » create e insertará un nuevo documento en esa colección cada segundo.

    <?php

    $manager = new MongoDB\Driver\Manager;

    $manager->executeCommand('test', new MongoDB\Driver\Command([
        'create' => 'asteroids',
        'capped' => true,
        'size' => 1048576,
    ]));

    while (true) {
        $bulkWrite = new MongoDB\Driver\BulkWrite;
        $bulkWrite->insert(['createdAt' => new MongoDB\BSON\UTCDateTime]);
        $manager->executeBulkWrite('test.asteroids', $bulkWrite);

        sleep(1);
    }

    ?>

Con el script productor aún en ejecución, puede ejecutarse un segundo script consumidor para leer los documentos insertados usando un cursor rastreable, indicado por las opciones `tailable` y `awaitData` en MongoDB\Driver\Query::__construct().

    <?php

    $manager = new MongoDB\Driver\Manager;

    $query = new MongoDB\Driver\Query([], [
        'tailable' => true,
        'awaitData' => true,
    ]);

    $cursor = $manager->executeQuery('test.asteroids', $query);

    $iterator = new IteratorIterator($cursor);

    $iterator->rewind();

    while (true) {
        if ($iterator->valid()) {
            $document = $iterator->current();
            printf("Documento consumido creado en: %s\n", $document->createdAt);
        }

        $iterator->next();
    }

    ?>

El script consumidor comenzará imprimiendo rápidamente todos los documentos disponibles en la colección limitada (como si se hubiera usado `foreach`); sin embargo, no terminará al llegar al final del conjunto de resultados inicial. Dado que el cursor es rastreable, llamar a IteratorIterator::next() bloqueará y esperará resultados adicionales. IteratorIterator::valid() también se usa para verificar si hay realmente datos disponibles para leer en cada paso.

> Nota: Este ejemplo usa la opción de consulta `awaitData` para instruir al servidor que bloquee durante un breve período (por ejemplo, un segundo) al final del conjunto de resultados antes de devolver una respuesta al controlador. Esto se usa para evitar que el controlador consulte agresivamente al servidor cuando no hay resultados disponibles. La opción `maxAwaitTimeMS` puede usarse junto con `tailable` y `awaitData` para especificar la cantidad de tiempo que el servidor debe bloquearse cuando llega al final del conjunto de resultados.

## Errores/Excepciones

Al iterar sobre el objeto cursor, los datos BSON se convierten en variables PHP. Esta iteración puede causar las siguientes Excepciones:

- Lanza MongoDB\Driver\Exception\InvalidArgumentException si una clase en el mapa de tipos no puede ser instanciada o no implementa MongoDB\BSON\Unserializable.
- Lanza una excepción MongoDB\Driver\Exception\UnexpectedValueException si la entrada no contiene exactamente un documento BSON. Las razones posibles incluyen, pero no se limitan a, BSON inválido, datos adicionales (después de leer un documento BSON), o un error inesperado de » libbson.

# MongoDB\Driver\Cursor::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::__construct — Crear un nuevo Cursor (no utilizado)

### Descripción

final private function MongoDB\Driver\Cursor::__construct()

Los objetos MongoDB\Driver\Cursor son devueltos como resultado de un comando o consulta ejecutada y no pueden ser construidos directamente.

### Parámetros

Esta función no contiene ningún parámetro.

### Ver también

- MongoDB\Driver\Manager::executeCommand() - Ejecuta un comando de base de datos
- MongoDB\Driver\Manager::executeQuery() - Ejecuta una consulta de base de datos
- MongoDB\Driver\Server::executeCommand() - Ejecuta un comando de base de datos en este servidor
- MongoDB\Driver\Server::executeQuery() - Ejecuta una consulta de base de datos en este servidor

# MongoDB\Driver\Cursor::current

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::current — Devuelve el elemento actual

### Descripción

public function MongoDB\Driver\Cursor::current(): array|object|null

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el documento de resultado actual como un array u objeto, dependiendo del mapa de tipos del cursor. Si la iteración no ha comenzado o la posición actual no es válida, se devolverá `null`.

### Ver también

- Iterator::current() - Devuelve el elemento actual

# MongoDB\Driver\Cursor::getId

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::getId — Devuelve el ID del cursor

### Descripción

final public function MongoDB\Driver\Cursor::getId(): MongoDB\BSON\Int64

Devuelve el ID de este cursor, que identifica de manera única al cursor en el servidor.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el ID de este cursor. El ID se devolverá como un objeto MongoDB\BSON\Int64.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Se cambió el tipo de retorno a MongoDB\BSON\Int64. Se eliminó el parámetro `asInt64`.
PECL mongodb 1.20.0 | Se desaconsejó devolver un MongoDB\Driver\CursorId. Se añadió el argumento `asInt64` para facilitar la migración en versiones futuras. Si `asInt64` es `true`, el ID se devolverá como un MongoDB\BSON\Int64.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\Cursor::getId()

    <?php

    /* En este ejemplo, insertamos varios documentos en la colección y especificamos
     * un batchSize más pequeño para asegurar que el primer lote contenga solo un
     * subconjunto de nuestros resultados y el cursor permanezca abierto en el servidor. */
    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $query = new MongoDB\Driver\Query([], ['batchSize' => 2]);

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $cursor = $manager->executeQuery('db.collection', $query);
    var_dump($cursor->getId(true));

    ?>

Resultado del ejemplo anterior es similar a:

    object(MongoDB\BSON\Int64)#5 (1) {
      ["integer"]=>
      string(11) "94810124093"
    }

### Ver también

- MongoDB\BSON\Int64

# MongoDB\Driver\Cursor::getServer

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::getServer — Devuelve el servidor asociado con este cursor

### Descripción

final public function MongoDB\Driver\Cursor::getServer(): MongoDB\Driver\Server

Devuelve el MongoDB\Driver\Server asociado con este cursor. Este es el servidor que ejecutó la MongoDB\Driver\Query o la MongoDB\Driver\Command.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el MongoDB\Driver\Server asociado con este cursor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\Cursor::getServer()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $query = new MongoDB\Driver\Query([]);

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $cursor = $manager->executeQuery('db.collection', $query);
    var_dump($cursor->getServer());

    ?>

Resultado del ejemplo anterior es similar a:

    object(MongoDB\Driver\Server)#5 (10) {
      ["host"]=>
      string(9) "localhost"
      ["port"]=>
      int(27017)
      ["type"]=>
      int(1)
      ["is_primary"]=>
      bool(false)
      ["is_secondary"]=>
      bool(false)
      ["is_arbiter"]=>
      bool(false)
      ["is_hidden"]=>
      bool(false)
      ["is_passive"]=>
      bool(false)
      ["last_hello_response"]=>
      array(8) {
        ["isWritablePrimary"]=>
        bool(true)
        ["maxBsonObjectSize"]=>
        int(16777216)
        ["maxMessageSizeBytes"]=>
        int(48000000)
        ["maxWriteBatchSize"]=>
        int(1000)
        ["localTime"]=>
        object(MongoDB\BSON\UTCDateTime)#6 (1) {
          ["milliseconds"]=>
          int(1446505367907)
        }
        ["maxWireVersion"]=>
        int(3)
        ["minWireVersion"]=>
        int(0)
        ["ok"]=>
        float(1)
      }
      ["round_trip_time"]=>
      int(584)
    }

### Ver también

- MongoDB\Driver\Server

# MongoDB\Driver\Cursor::isDead

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::isDead — Comprueba si el cursor está agotado o puede tener resultados adicionales

### Descripción

final public function MongoDB\Driver\Cursor::isDead(): bool

Comprueba si no hay definitivamente más resultados disponibles en el cursor. Este método es similar al método » cursor.isExhausted() en el MongoDB shell y es principalmente útil al iterar » cursores persistentes.

Un cursor no tiene más resultados y se considera "agotado" cuando se cumple una de las siguientes condiciones:

- La actual serie de resultados se ha iterado completamente y el identificador del cursor es cero (es decir, no se puede emitir un » getMore).
- Se encontró un error al iterar el cursor.
- El cursor alcanzó su límite configurado.

Por diseño, no siempre es posible determinar si un cursor tiene resultados adicionales. Los casos en los que un cursor puede tener más datos disponibles son los siguientes:

- Hay documentos adicionales en la actual serie de resultados, que están almacenados en el lado-cliente. Iterar obtendrá un documento del búfer local.
- No hay documentos adicionales en la actual serie de resultados (es decir, búfer local), pero el identificador del cursor no es cero. Iterar solicitará más documentos al servidor mediante una operación » getMore, que puede o no devolver más resultados y/o indicar que el cursor ha sido cerrado en el servidor al devolver cero para su identificador.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si no hay definitivamente más resultados disponibles en el cursor, y `false` en caso contrario.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\Cursor::isDead()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $query = new MongoDB\Driver\Query([]);

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $cursor = $manager->executeQuery('db.collection', $query);

    $iterator = new IteratorIterator($cursor);

    $iterator->rewind();
    var_dump($cursor->isDead());

    $iterator->next();
    var_dump($cursor->isDead());

    $iterator->next();
    var_dump($cursor->isDead());

    $iterator->next();
    var_dump($cursor->isDead());

    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(false)
    bool(false)
    bool(true)

### Ver también

- » Cursores persistentes en el manual de MongoDB
- » cursor.isExhausted() en el manual de MongoDB

# MongoDB\Driver\Cursor::key

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::key — Devuelve el índice del resultado actual dentro del cursor

### Descripción

public function MongoDB\Driver\Cursor::key(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El índice numérico del resultado actual dentro del cursor.

### Ver también

- Iterator::key() - Devuelve la clave del elemento actual

# MongoDB\Driver\Cursor::next

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::next — Avanza el cursor al siguiente resultado

### Descripción

public function MongoDB\Driver\Cursor::next(): void

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Mueve la posición actual al siguiente elemento del cursor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla

### Ver también

- Iterator::next() - Avanza al siguiente elemento

# MongoDB\Driver\Cursor::rewind

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::rewind — Rebobinar el cursor a la primera posición

### Descripción

public function MongoDB\Driver\Cursor::rewind(): void

Si el cursor ha avanzado más allá de su primera posición, ya no podrá rebobinarse.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

`null`.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza MongoDB\Driver\Exception\LogicException si este método se invoca después de que el cursor haya avanzado más allá de su primera posición.

### Ver también

- Iterator::rewind() - Rebobine la Iterator al primer elemento

# MongoDB\Driver\Cursor::setTypeMap

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::setTypeMap — Establece un mapa de tipos para usar en la deserialización BSON

### Descripción

final public function MongoDB\Driver\Cursor::setTypeMap(array `$typemap`): void

Establece la configuración del mapa de tipos que se usará al deserializar los resultados BSON en valores de PHP.

### Parámetros

`typeMap` (array)
  Configuración del mapa de tipos.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

Al iterar sobre el cursor, también se pueden lanzar las siguientes excepciones debido a una configuración incorrecta del mapa de tipos:

- Lanza MongoDB\Driver\Exception\InvalidArgumentException si una clase en el mapa de tipos no puede ser instanciada o no implementa MongoDB\BSON\Unserializable.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\Cursor::setTypeMap()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $bulk = new MongoDB\Driver\BulkWrite;
    $id = $bulk->insert(['x' => 1]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $query = new MongoDB\Driver\Query(['_id' => $id]);
    $cursor = $manager->executeQuery('db.collection', $query);
    $cursor->setTypeMap(['root' => 'array']);

    foreach ($cursor as $document) {
        var_dump($document);
    }

    ?>

Resultado del ejemplo anterior es similar a:

    array(2) {
      ["_id"]=>
      object(MongoDB\BSON\ObjectId)#6 (1) {
        ["oid"]=>
        string(24) "56424fb76118fd3267180741"
      }
      ["x"]=>
      int(1)
    }

### Ver también

- Persistir datos

# MongoDB\Driver\Cursor::toArray

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::toArray — Devuelve un array que contiene todos los resultados de este cursor

### Descripción

final public function MongoDB\Driver\Cursor::toArray(): array

Itera el cursor y devuelve sus resultados en un array. Se puede usar MongoDB\Driver\Cursor::setTypeMap() para controlar cómo se deserializan los documentos en valores de PHP.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array que contiene todos los resultados de este cursor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\Cursor::toArray()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $query = new MongoDB\Driver\Query([]);
    $cursor = $manager->executeQuery('db.collection', $query);

    var_dump($cursor->toArray());

    ?>

Resultado del ejemplo anterior es similar a:

    array(3) {
      [0]=>
      object(stdClass)#6 (2) {
        ["_id"]=>
        object(MongoDB\BSON\ObjectId)#5 (1) {
          ["oid"]=>
          string(24) "564259a96118fd40b41bcf61"
        }
        ["x"]=>
        int(1)
      }
      [1]=>
      object(stdClass)#8 (2) {
        ["_id"]=>
        object(MongoDB\BSON\ObjectId)#7 (1) {
          ["oid"]=>
          string(24) "564259a96118fd40b41bcf62"
        }
        ["x"]=>
        int(2)
      }
      [2]=>
      object(stdClass)#10 (2) {
        ["_id"]=>
        object(MongoDB\BSON\ObjectId)#9 (1) {
          ["oid"]=>
          string(24) "564259a96118fd40b41bcf63"
        }
        ["x"]=>
        int(3)
      }
    }

### Ver también

- MongoDB\Driver\Cursor::setTypeMap() - Establece un mapa de tipos para usar en la deserialización BSON

# MongoDB\Driver\Cursor::valid

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::valid — Comprueba si la posición actual en el cursor es válida

### Descripción

public function MongoDB\Driver\Cursor::valid(): bool

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

`true` si la posición actual del cursor es válida, `false` en caso contrario.

### Ver también

- Iterator::valid() - Comprueba si la posición actual es válido

## Tabla de contenidos

- MongoDB\Driver\Cursor::__construct — Crear un nuevo Cursor (no utilizado)
- MongoDB\Driver\Cursor::current — Devuelve el elemento actual
- MongoDB\Driver\Cursor::getId — Devuelve el ID del cursor
- MongoDB\Driver\Cursor::getServer — Devuelve el servidor asociado con este cursor
- MongoDB\Driver\Cursor::isDead — Comprueba si el cursor está agotado o puede tener resultados adicionales
- MongoDB\Driver\Cursor::key — Devuelve el índice del resultado actual dentro del cursor
- MongoDB\Driver\Cursor::next — Avanza el cursor al siguiente resultado
- MongoDB\Driver\Cursor::rewind — Rebobinar el cursor a la primera posición
- MongoDB\Driver\Cursor::setTypeMap — Establece un mapa de tipos para usar en la deserialización BSON
- MongoDB\Driver\Cursor::toArray — Devuelve un array que contiene todos los resultados de este cursor
- MongoDB\Driver\Cursor::valid — Comprueba si la posición actual en el cursor es válida

# La clase MongoDB\Driver\CursorId

(mongodb >=1.0.0)

## Introducción

La clase MongoDB\Driver\CursorID es un objeto de valor que representa un identificador de cursor. Las instancias de esta clase son devueltas por MongoDB\Driver\Cursor::getId().

Advertencia

Esta clase ha sido DEPRECADA a partir de la versión 1.20.0 de la extensión y fue eliminada en la versión 2.0. Las aplicaciones deben actualizar su uso de MongoDB\Driver\Cursor::getId() para devolver MongoDB\BSON\Int64 en su lugar.

## Sinopsis de la Clase

final class MongoDB\Driver\CursorId implements Serializable, Stringable {
/* Métodos */
final private function __construct()
final public function __toString(): string
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Esta clase ha sido eliminada.
PECL mongodb 1.20.0 | Esta clase ha sido deprecada y será eliminada en la versión 2.0.
PECL mongodb 1.12.0 | Implementa Stringable para PHP 8.0+.
PECL mongodb 1.7.0 | Implementa Serializable.

# MongoDB\Driver\CursorId::__construct

(mongodb >=1.0.0)

MongoDB\Driver\CursorId::__construct — Crear un nuevo CursorId (no utilizado)

### Descripción

final private function MongoDB\Driver\CursorId::__construct()

Los objetos MongoDB\Driver\CursorId son devueltos por MongoDB\Driver\Cursor::getId() y no pueden ser construidos directamente.

### Parámetros

Esta función no contiene ningún parámetro.

### Ver también

- MongoDB\Driver\Cursor::getId() - Devuelve el ID del cursor

# MongoDB\Driver\CursorId::__toString

(mongodb >=1.0.0)

MongoDB\Driver\CursorId::__toString — Representación en forma de string del identificador del cursor

### Descripción

final public function MongoDB\Driver\CursorId::__toString(): string

Devuelve la representación en forma de string del identificador del cursor.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la representación en forma de string del identificador del cursor.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\CursorId::__toString()

    <?php

    /* En este ejemplo, insertamos varios documentos en la colección y especificamos
     * un tamaño de lote (batchSize) más pequeño para asegurarnos de que el primer lote
     * contenga solo un subconjunto de nuestros resultados y el cursor permanezca abierto
     * en el servidor. */
    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $query = new MongoDB\Driver\Query([], ['batchSize' => 2]);

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $cursor = $manager->executeQuery('db.collection', $query);
    var_dump((string) $cursor->getId());

    ?>

Resultado del ejemplo anterior es similar a:

    string(11) "98061641158"

### Ver también

- MongoDB\Driver\Cursor::getId() - Devuelve el ID del cursor

## Tabla de contenidos

- MongoDB\Driver\CursorId::__construct — Crear un nuevo CursorId (no utilizado)
- MongoDB\Driver\CursorId::__toString — Representación en forma de string del identificador del cursor

# La interfaz `MongoDB\Driver\CursorInterface`

(mongodb >=1.6.0)

## Introducción

Esta interfaz es implementada por MongoDB\Driver\Cursor para ser usada como un parámetro, retorno, o tipo de propiedad en clases de usuario.

## Sinopsis de la Clase

class MongoDB\Driver\CursorInterface implements Iterator {
/* Métodos */
abstract public function getId(): MongoDB\BSON\Int64
abstract public function getServer(): MongoDB\Driver\Server
abstract public function isDead(): bool
abstract public function setTypeMap(array `$typemap`): void
abstract public function toArray(): array
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Esta interfaz ahora extiende Iterator. Los tipos de retorno declarados previamente como provisionales ahora están obligados.
PECL mongodb 1.15.0 | Los tipos de retorno de los métodos son declarados como provisionales en PHP 8.0 y posteriores, lo que desencadena avisos de depreciación en el código que implementa esta interfaz sin declarar los tipos de retorno apropiados. El atributo `#[ReturnTypeWillChange]` puede ser añadido para ignorar la notificación de depreciación.

# MongoDB\Driver\CursorInterface::getId

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::getId — Devuelve el ID de este cursor

### Descripción

abstract public function MongoDB\Driver\CursorInterface::getId(): MongoDB\BSON\Int64

Devuelve el ID de este cursor, que identifica de manera única el cursor en el servidor.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el ID de este cursor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.20.0 | Se añadió MongoDB\BSON\Int64 al tipo de retorno tentativo de este método. MongoDB\Driver\CursorId será eliminado del tipo de retorno en la versión 2.0.

### Ver también

- MongoDB\Driver\Cursor::getId() - Devuelve el ID del cursor
- MongoDB\Driver\CursorId
- MongoDB\BSON\Int64

# MongoDB\Driver\CursorInterface::getServer

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::getServer — Devuelve el servidor asociado a este cursor

### Descripción

abstract public function MongoDB\Driver\CursorInterface::getServer(): MongoDB\Driver\Server

Devuelve el MongoDB\Driver\Server asociado a este cursor. Este es el servidor que ejecutó la MongoDB\Driver\Query o la MongoDB\Driver\Command.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el MongoDB\Driver\Server asociado a este cursor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Cursor::getServer() - Devuelve el servidor asociado con este cursor
- MongoDB\Driver\Server

# MongoDB\Driver\CursorInterface::isDead

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::isDead — Comprueba si el cursor puede tener resultados adicionales

### Descripción

abstract public function MongoDB\Driver\CursorInterface::isDead(): bool

Comprueba si el cursor puede tener resultados adicionales disponibles para leer. Un cursor está inicialmente "activo" pero puede volverse "inactivo" por cualquiera de las siguientes razones:

- Avanzar un cursor no orientable no devolvió un documento
- El cursor encontró un error
- El cursor leyó su último lote hasta completarse
- El cursor alcanzó su límite configurado

Esto es principalmente útil con cursores orientables.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si no hay resultados adicionales disponibles, y `false` en caso contrario.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Cursor::isDead() - Comprueba si el cursor está agotado o puede tener resultados adicionales

# MongoDB\Driver\CursorInterface::setTypeMap

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::setTypeMap — Establece un mapa de tipos para usar en la deserialización BSON

### Descripción

abstract public function MongoDB\Driver\CursorInterface::setTypeMap(array `$typemap`): void

Establece la configuración del mapa de tipos que se usará al deserializar los resultados BSON en valores PHP.

### Parámetros

`typeMap` (array)
  Configuración del mapa de tipos.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Cursor::setTypeMap() - Establece un mapa de tipos para usar en la deserialización BSON
- Persistir datos

# MongoDB\Driver\CursorInterface::toArray

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::toArray — Devuelve un array que contiene todos los resultados de este cursor

### Descripción

abstract public function MongoDB\Driver\CursorInterface::toArray(): array

Itera el cursor y devuelve sus resultados en un array. Se puede usar MongoDB\Driver\CursorInterface::setTypeMap() para controlar cómo los documentos son deserializados en valores de PHP.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array que contiene todos los resultados de este cursor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Cursor::toArray() - Devuelve un array que contiene todos los resultados de este cursor
- MongoDB\Driver\CursorInterface::setTypeMap() - Establece un mapa de tipos para usar en la deserialización BSON

## Tabla de contenidos

- MongoDB\Driver\CursorInterface::getId — Devuelve el ID de este cursor
- MongoDB\Driver\CursorInterface::getServer — Devuelve el servidor asociado a este cursor
- MongoDB\Driver\CursorInterface::isDead — Comprueba si el cursor puede tener resultados adicionales
- MongoDB\Driver\CursorInterface::setTypeMap — Establece un mapa de tipos para usar en la deserialización BSON
- MongoDB\Driver\CursorInterface::toArray — Devuelve un array que contiene todos los resultados de este cursor

# La clase MongoDB\Driver\Server

(mongodb >=1.0.0)

## Introducción

## Sinopsis de la Clase

final class MongoDB\Driver\Server {
/* Constantes */
const int TYPE_UNKNOWN = 0;
const int TYPE_STANDALONE = 1;
const int TYPE_MONGOS = 2;
const int TYPE_POSSIBLE_PRIMARY = 3;
const int TYPE_RS_PRIMARY = 4;
const int TYPE_RS_SECONDARY = 5;
const int TYPE_RS_ARBITER = 6;
const int TYPE_RS_OTHER = 7;
const int TYPE_RS_GHOST = 8;
const int TYPE_LOAD_BALANCER = 9;
/* Métodos */
final private function __construct()
final public function executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$options` = `null`): MongoDB\Driver\WriteResult
final public function executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult
final public function executeCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function getHost(): string
final public function getInfo(): array
final public function getLatency(): ?integer
final public function getPort(): int
final public function getServerDescription(): MongoDB\Driver\ServerDescription
final public function getTags(): array
final public function getType(): int
final public function isArbiter(): bool
final public function isHidden(): bool
final public function isPassive(): bool
final public function isPrimary(): bool
final public function isSecondary(): bool
}

## Constantes predefinidas

`MongoDB\Driver\Server::TYPE_UNKNOWN`
  Tipo de servidor desconocido, devuelto por MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_STANDALONE`
  Tipo de servidor independiente, devuelto por MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_MONGOS`
  Tipo de servidor Mongos, devuelto por MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_POSSIBLE_PRIMARY`
  Tipo de servidor posible primario de conjunto de réplicas, devuelto por MongoDB\Driver\Server::getType(). Un servidor puede identificarse como posible primario si aún no ha sido verificado pero otro miembro del conjunto de réplicas cree que es el primario.
`MongoDB\Driver\Server::TYPE_RS_PRIMARY`
  Tipo de servidor primario de conjunto de réplicas, devuelto por MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_RS_SECONDARY`
  Tipo de servidor secundario de conjunto de réplicas, devuelto por MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_RS_ARBITER`
  Tipo de servidor árbitro de conjunto de réplicas, devuelto por MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_RS_OTHER`
  Tipo de servidor de conjunto de réplicas de otro tipo, devuelto por MongoDB\Driver\Server::getType(). Estos servidores pueden estar ocultos, iniciándose o recuperándose. No pueden ser consultados, pero sus listas de hosts son útiles para descubrir la configuración actual del conjunto de réplicas.
`MongoDB\Driver\Server::TYPE_RS_GHOST`
  Tipo de servidor fantasma de conjunto de réplicas, devuelto por MongoDB\Driver\Server::getType(). Los servidores pueden identificarse como tales en al menos tres situaciones: brevemente durante el inicio del servidor; en un conjunto de réplicas no inicializado; o cuando el servidor es rechazado (es decir, eliminado de la configuración del conjunto de réplicas). No pueden ser consultados, ni se puede usar su lista de hosts para descubrir la configuración actual del conjunto de réplicas; sin embargo, el cliente puede monitorear este servidor con la esperanza de que pase a un estado más útil.
`MongoDB\Driver\Server::TYPE_LOAD_BALANCER`
  Tipo de servidor equilibrador de carga, devuelto por MongoDB\Driver\Server::getType().

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.11.0 | Se añadió la constante `MongoDB\Driver\Server::TYPE_LOAD_BALANCER`.

# MongoDB\Driver\Server::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Server::__construct — Crear un nuevo servidor (no utilizado)

### Descripción

final private function MongoDB\Driver\Server::__construct()

Los objetos MongoDB\Driver\Server son creados internamente por MongoDB\Driver\Manager cuando se establece una conexión de base de datos y pueden ser devueltos por MongoDB\Driver\Manager::getServers() y MongoDB\Driver\Manager::selectServer().

### Parámetros

Esta función no contiene ningún parámetro.

### Ver también

- MongoDB\Driver\Manager::getServers() - Devolver los servidores a los que está conectado este gestor
- MongoDB\Driver\Manager::selectServer() - Selecciona un servidor correspondiente a una preferencia de lectura

# MongoDB\Driver\Server::executeBulkWrite

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeBulkWrite — Ejecuta una o varias operaciones de escritura en este servidor

### Descripción

final public function MongoDB\Driver\Server::executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$options` = `null`): MongoDB\Driver\WriteResult

Ejecuta una o varias operaciones de escritura en este servidor.

Un objeto MongoDB\Driver\BulkWrite puede ser construido con una o varias operaciones de diferentes tipos (i.e. actualización, eliminación, e inserción). El driver intentará enviar las operaciones del mismo tipo al servidor en un mínimo de solicitudes posibles para optimizar los viajes de ida y vuelta.

El valor por omisión para la opción `"writeConcern"` será deducido de una transacción activa (indicada por la opción `"session"`), luego por el URI de conexión.

### Parámetros

`namespace` (string)
  Un espacio de nombres completamente calificado (ej. `"databaseName.collectionName"`)
`bulk` (MongoDB\Driver\BulkWrite)
  Escritura(s) a ejecutar.
`options`

  options
  Opción | Tipo | Descripción
  --- | --- | ---
  session | MongoDB\Driver\Session | Una sesión a asociar a la operación.
  writeConcern | MongoDB\Driver\WriteConcern | Una preocupación de escritura a aplicar a la operación.

### Valores devueltos

Retorna un MongoDB\Driver\WriteResult en caso de éxito.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si `bulk` no contiene ninguna operación de escritura.
- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si `bulk` ya ha sido ejecutado. Los objetos MongoDB\Driver\BulkWrite no pueden ser ejecutados varias veces.
- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si la opción `"session"` se utiliza junto con una preocupación de escritura no reconocida.
- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza una excepción MongoDB\Driver\BulkWriteException en caso de error de una operación de escritura (un error WriteError y WriteConcern)
- Lanza una excepción MongoDB\Driver\Exception\RuntimeException si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | El parámetro `options` ya no acepta instancias MongoDB\Driver\WriteConcern.
PECL mongodb 1.21.0 | Pasar un objeto MongoDB\Driver\WriteConcern como `options` está obsoleto y será eliminado en la 2.0.
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException será lanzado si la opción `"session"` es utilizada conjuntamente con una preocupación de escritura no reconocida.
PECL mongodb 1.4.0 | El tercer parámetro es ahora un array de `options`. Para la compatibilidad ascendente, este parámetro siempre aceptará un objeto MongoDB\Driver\WriteConcern.
PECL mongodb 1.3.0 | MongoDBDriverExceptionInvalidArgumentException es ahora lanzado si `Bulk` no contiene operaciones de escritura. Anteriormente, una MongoDB\Driver\Exception\BulkWriteException era lanzada.

### Notas

> Nota: Es responsabilidad del llamante asegurarse de que el servidor sea capaz de ejecutar la operación de escritura. Por ejemplo, la ejecución de una operación de escritura en un secundario (excluyendo su base de datos "local") fallará.

### Ver también

- MongoDB\Driver\BulkWrite
- MongoDB\Driver\WriteResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Manager::executeBulkWrite() - Ejecuta una o varias operaciones de escritura

# MongoDB\Driver\Server::executeBulkWriteCommand

(mongodb >=2.1.0)

MongoDB\Driver\Server::executeBulkWriteCommand — Ejecuta operaciones de escritura en este servidor utilizando el comando bulkWrite

### Descripción

final public function MongoDB\Driver\Server::executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult

Ejecuta una o varias operaciones de escritura en el servidor primario utilizando el comando » bulkWrite introducido en MongoDB 8.0.

Una MongoDB\Driver\BulkWriteCommand puede ser construida con una o varias operaciones de escritura de tipos variados (por ejemplo, inserciones, actualizaciones y eliminaciones). Cada operación de escritura puede apuntar a una colección diferente.

El valor por omisión para la opción `"writeConcern"` será deducido de una transacción activa (indicada por la opción `"session"`), seguida de la URI de conexión.

### Parámetros

`bulk` (MongoDB\Driver\BulkWriteCommand)
  Escritura(s) a ejecutar.
`options`

  options
  Opción | Tipo | Descripción
  --- | --- | ---
  session | MongoDB\Driver\Session | Una sesión a asociar a la operación.
  writeConcern | MongoDB\Driver\WriteConcern | Una preocupación de escritura a aplicar a la operación.

### Valores devueltos

Retorna un MongoDB\Driver\BulkWriteCommandResult en caso de éxito.

### Errores/Excepciones

- Lanza una MongoDB\Driver\Exception\InvalidArgumentException si `bulk` no contiene operaciones de escritura válidas.
- Lanza una MongoDB\Driver\Exception\InvalidArgumentException si `bulk` ya ha sido ejecutada. Los objetos MongoDB\Driver\BulkWriteCommand no pueden ser ejecutados múltiples veces.
- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si la opción `"session"` se utiliza junto con una preocupación de escritura no reconocida.
- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza una excepción MongoDB\Driver\Exception\BulkWriteCommandException en caso de error de escritura (por ejemplo, fallo de comando, error de escritura o preocupación de escritura)
- Lanza MongoDB\Driver\Exception\RuntimeException en caso de otro error.

### Ver también

- MongoDB\Driver\BulkWriteCommand
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Ejecuta operaciones de escritura utilizando el comando bulkWrite

# MongoDB\Driver\Server::executeCommand

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeCommand — Ejecuta un comando de base de datos en este servidor

### Descripción

final public function MongoDB\Driver\Server::executeCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Ejecuta un comando en este servidor.

Este método no aplica ninguna lógica especial al comando. Los valores por omisión para las opciones `"readPreference"`, `"readConcern"` y `"writeConcern"` serán deducidos de una transacción activa (indicada por la opción `"session"`). Si no hay una transacción activa, se utilizará una preferencia de lectura primaria para la selección del servidor.

Los valores por omisión no serán deducidos de la URI de conexión. Por lo tanto, se recomienda a los usuarios utilizar métodos de comando de lectura y/o escritura específicos si es posible.

> Nota: La opción `readPreference` no controla el servidor hacia el cual el controlador emite la operación; siempre se ejecutará en este objeto servidor. En su lugar, puede ser utilizado al emitir la operación a un secundario (desde una conexión de conjunto de réplicas, no autónoma) o el nodo Mongos para asegurarse de que el controlador defina el protocolo de fila en consecuencia o añada la preferencia de lectura a la operación, respectivamente.

### Parámetros

`db` (string)
  El nombre de la base de datos sobre la cual se ejecutará el comando.
`command` (MongoDB\Driver\Command)
  El comando a ejecutar.
`options`

  options
  Opción | Tipo | Descripción
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Una preocupación de lectura a aplicar a la operación. Esta opción está disponible en MongoDB 3.2+ y se traducirá en una excepción en el momento de la ejecución si se especifica para una versión más antigua del servidor.
  readPreference | MongoDB\Driver\ReadPreference | Una preferencia de lectura a utilizar para seleccionar un servidor para la operación.
  session | MongoDB\Driver\Session | Una sesión a asociar a la operación.
  writeConcern | MongoDB\Driver\WriteConcern | Una preocupación de escritura a aplicar a la operación.

  Advertencia

  Si se utiliza una `"session"` que tiene una transacción en curso, no se puede especificar la opción `"readConcern"` o `"writeConcern"`. Intentar hacer esto lanzará una excepción MongoDB\Driver\Exception\InvalidArgumentException. En su lugar, debe definir estas opciones cuando se crea la transacción con MongoDB\Driver\Session::startTransaction().

### Valores devueltos

Retorna un MongoDB\Driver\Cursor en caso de éxito.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si la opción `"session"` se utiliza con una transacción asociada en combinación con una opción `"readConcern"` o `"writeConcern"`.
- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si la opción `"session"` se utiliza junto con una preocupación de escritura no reconocida.
- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza una excepción MongoDB\Driver\Exception\RuntimeException si ocurre un error (i.e. comando inválido, envío de un comando de escritura a un secundario).

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | El parámetro `options` ya no acepta instancias de MongoDB\Driver\WriteConcern.
PECL mongodb 1.21.0 | Pasar un objeto MongoDB\Driver\ReadPreference como `options` está obsoleto y será eliminado en la versión 2.0.
PECL mongodb 1.4.4 | Se lanzará MongoDB\Driver\Exception\InvalidArgumentException si la opción `"session"` se utiliza conjuntamente con una preocupación de escritura no reconocida.
PECL mongodb 1.4.0 | El tercer parámetro es ahora un array de `options`. Para la compatibilidad ascendente, este parámetro siempre aceptará un objeto MongoDB\Driver\ReadPreference.

### Notas

> Nota: Es responsabilidad del llamante asegurarse de que el servidor sea capaz de ejecutar la operación de escritura. Por ejemplo, la ejecución de una operación de escritura en un secundario (excluyendo su base de datos "local") fallará.

### Ver también

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Server::executeReadCommand() - Ejecuta un comando de base de datos que lee en este servidor
- MongoDB\Driver\Server::executeReadWriteCommand() - Ejecuta un comando de base de datos que lee y escribe en este servidor
- MongoDB\Driver\Server::executeWriteCommand() - Ejecuta un comando de base de datos que escribe en este servidor
- MongoDB\Driver\Manager::executeCommand() - Ejecuta un comando de base de datos

# MongoDB\Driver\Server::executeQuery

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeQuery — Ejecuta una consulta de base de datos en este servidor

### Descripción

final public function MongoDB\Driver\Server::executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Ejecuta la consulta en este servidor.

Los valores por omisión para la opción `"readPreference"` y la opción `"readConcern"` de la consulta se deducirán de una transacción activa (indicada por la opción `"session"`), luego por la URI de conexión.

> Nota: La opción `readPreference` no controla el servidor hacia el cual el controlador emite la operación; siempre se ejecutará en este objeto servidor. En su lugar, puede ser utilizado al emitir la operación a un secundario (desde una conexión de conjunto de réplicas, no autónoma) o el nodo Mongos para asegurarse de que el controlador defina el protocolo de fila en consecuencia o añada la preferencia de lectura a la operación, respectivamente.

### Parámetros

`namespace` (string)
  Un espacio de nombres completamente calificado (ej. `"databaseName.collectionName"`)
`query` (MongoDB\Driver\Query)
  La consulta a ejecutar.
`options`

  options
  Opción | Tipo | Descripción
  --- | --- | ---
  readPreference | MongoDB\Driver\ReadPreference | Una preferencia de lectura a utilizar para seleccionar un servidor para la operación.
  session | MongoDB\Driver\Session | Una sesión a asociar a la operación.

### Valores devueltos

Retorna un MongoDB\Driver\Cursor en caso de éxito.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza una excepción MongoDB\Driver\Exception\RuntimeException si ocurre un error (i.e. operadores de consulta inválidos).

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | El parámetro `options` ya no acepta una instancia MongoDB\Driver\WriteConcern.
PECL mongodb 1.21.0 | Pasar un objeto MongoDB\Driver\ReadPreference como `options` está obsoleto y será eliminado en la 2.0.
PECL mongodb 1.4.0 | El tercer parámetro es ahora un array de `options`. Para la compatibilidad ascendente, este parámetro siempre aceptará un objeto MongoDB\Driver\ReadPreference.

### Ver también

- MongoDB\Driver\Cursor
- MongoDB\Driver\Query
- MongoDB\Driver\ReadPreference
- MongoDB\Driver\Manager::executeQuery() - Ejecuta una consulta de base de datos

# MongoDB\Driver\Server::executeReadCommand

(mongodb >=1.4.0)

MongoDB\Driver\Server::executeReadCommand — Ejecuta un comando de base de datos que lee en este servidor

### Descripción

final public function MongoDB\Driver\Server::executeReadCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Ejecuta el comando en este servidor, independientemente de la opción `"readPreference"`.

Este método aplicará una lógica específica a los comandos de lectura (por ejemplo » distinct). Los valores por omisión para las opciones `"readPreference"` y `"readConcern"` serán deducidos de una transacción activa (indicada por la opción `"session"`), seguida de la URI de conexión.

> Nota: La opción `readPreference` no controla el servidor hacia el cual el controlador emite la operación; siempre se ejecutará en este objeto servidor. En su lugar, puede ser utilizado al emitir la operación a un secundario (desde una conexión de conjunto de réplicas, no autónoma) o el nodo Mongos para asegurarse de que el controlador defina el protocolo de fila en consecuencia o añada la preferencia de lectura a la operación, respectivamente.

### Parámetros

`db` (string)
  El nombre de la base de datos sobre la cual se ejecutará el comando.
`command` (MongoDB\Driver\Command)
  El comando a ejecutar.
`options`

  options
  Opción | Tipo | Descripción
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Una preocupación de lectura a aplicar a la operación. Esta opción está disponible en MongoDB 3.2+ y se traducirá en una excepción en el momento de la ejecución si se especifica para una versión más antigua del servidor.
  readPreference | MongoDB\Driver\ReadPreference | Una preferencia de lectura a utilizar para seleccionar un servidor para la operación.
  session | MongoDB\Driver\Session | Una sesión a asociar a la operación.

  Advertencia

  Si se utiliza una `"session"` que tiene una transacción en curso, no se puede especificar la opción `"readConcern"` o `"writeConcern"`. Intentar hacer esto lanzará una excepción MongoDB\Driver\Exception\InvalidArgumentException. En su lugar, debe definir estas opciones cuando se crea la transacción con MongoDB\Driver\Session::startTransaction().

### Valores devueltos

Retorna un MongoDB\Driver\Cursor en caso de éxito.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si la opción `"session"` se utiliza con una transacción asociada en combinación con una opción `"readConcern"` o `"writeConcern"`.
- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza una MongoDB\Driver\Exception\RuntimeException en caso de otros errores (por ejemplo: comando inválido).

### Ver también

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Server::executeCommand() - Ejecuta un comando de base de datos en este servidor
- MongoDB\Driver\Server::executeReadWriteCommand() - Ejecuta un comando de base de datos que lee y escribe en este servidor
- MongoDB\Driver\Server::executeWriteCommand() - Ejecuta un comando de base de datos que escribe en este servidor
- MongoDB\Driver\Manager::executeReadCommand() - Ejecuta un comando de base de datos que lee

# MongoDB\Driver\Server::executeReadWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Server::executeReadWriteCommand — Ejecuta un comando de base de datos que lee y escribe en este servidor

### Descripción

final public function MongoDB\Driver\Server::executeReadWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Ejecuta el comando en este servidor.

Este método aplicará una lógica específica a los comandos de lectura y escritura (por ejemplo » aggregate). Los valores por omisión para las opciones `"readConcern"` y `"writeConcern"` serán deducidos de una transacción activa (indicada por la opción `"session"`), seguida de la URI de conexión.

### Parámetros

`db` (string)
  El nombre de la base de datos sobre la cual se ejecutará el comando.
`command` (MongoDB\Driver\Command)
  El comando a ejecutar.
`options`

  options
  Opción | Tipo | Descripción
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Una preocupación de lectura a aplicar a la operación. Esta opción está disponible en MongoDB 3.2+ y se traducirá en una excepción en el momento de la ejecución si se especifica para una versión más antigua del servidor.
  session | MongoDB\Driver\Session | Una sesión a asociar a la operación.
  writeConcern | MongoDB\Driver\WriteConcern | Una preocupación de escritura a aplicar a la operación.

  Advertencia

  Si se utiliza una `"session"` que tiene una transacción en curso, no se puede especificar la opción `"readConcern"` o `"writeConcern"`. Intentar hacer esto lanzará una excepción MongoDB\Driver\Exception\InvalidArgumentException. En su lugar, debe definir estas opciones cuando se crea la transacción con MongoDB\Driver\Session::startTransaction().

### Valores devueltos

Retorna un MongoDB\Driver\Cursor en caso de éxito.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si la opción `"session"` se utiliza con una transacción asociada en combinación con una opción `"readConcern"` o `"writeConcern"`.
- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si la opción `"session"` se utiliza junto con una preocupación de escritura no reconocida.
- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza una MongoDB\Driver\Exception\RuntimeException en caso de otros errores (por ejemplo: comando inválido).

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.4.4 | Una MongoDB\Driver\Exception\InvalidArgumentException será lanzada si la opción `"session"` es utilizada en combinación con un writeConcern no reconocido.

### Notas

> Nota: Es responsabilidad del llamante asegurarse de que el servidor sea capaz de ejecutar la operación de escritura. Por ejemplo, la ejecución de una operación de escritura en un secundario (excluyendo su base de datos "local") fallará.

### Ver también

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Server::executeCommand() - Ejecuta un comando de base de datos en este servidor
- MongoDB\Driver\Server::executeReadCommand() - Ejecuta un comando de base de datos que lee en este servidor
- MongoDB\Driver\Server::executeWriteCommand() - Ejecuta un comando de base de datos que escribe en este servidor
- MongoDB\Driver\Manager::executeReadWriteCommand() - Ejecuta un comando de base de datos que lee y escribe

# MongoDB\Driver\Server::executeWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Server::executeWriteCommand — Ejecuta un comando de base de datos que escribe en este servidor

### Descripción

final public function MongoDB\Driver\Server::executeWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Ejecuta el comando en este servidor.

Este método aplicará una lógica específica a los comandos que escriben (por ejemplo » drop). El valor por omisión para la opción `"writeConcern"` será deducido de una transacción activa (indicada por la opción `"session"`), seguida de la URI de conexión.

> Nota: Este método no está destinado a ser utilizado para ejecutar » insert, » update, o » delete comandos. Se recomienda a los usuarios utilizar MongoDB\Driver\Server::executeBulkWrite() para estas operaciones.

### Parámetros

`db` (string)
  El nombre de la base de datos sobre la cual se ejecutará el comando.
`command` (MongoDB\Driver\Command)
  El comando a ejecutar.
`options`

  options
  Opción | Tipo | Descripción
  --- | --- | ---
  session | MongoDB\Driver\Session | Una sesión a asociar a la operación.
  writeConcern | MongoDB\Driver\WriteConcern | Una preocupación de escritura a aplicar a la operación.

  Advertencia

  Si se utiliza una `"session"` que tiene una transacción en curso, no se puede especificar la opción `"readConcern"` o `"writeConcern"`. Intentar hacer esto lanzará una excepción MongoDB\Driver\Exception\InvalidArgumentException. En su lugar, debe definir estas opciones cuando se crea la transacción con MongoDB\Driver\Session::startTransaction().

### Valores devueltos

Retorna un MongoDB\Driver\Cursor en caso de éxito.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si la opción `"session"` se utiliza con una transacción asociada en combinación con una opción `"readConcern"` o `"writeConcern"`.
- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si la opción `"session"` se utiliza junto con una preocupación de escritura no reconocida.
- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\ConnectionException si la conexión al servidor falla por una razón distinta a un problema de identificación
- Lanza una excepción MongoDB\Driver\AuthenticationException si se requiere una identificación pero falla
- Lanza una MongoDB\Driver\Exception\RuntimeException en caso de otros errores (por ejemplo: comando inválido).

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.4.4 | Una MongoDB\Driver\Exception\InvalidArgumentException será lanzada si la opción `"session"` es utilizada en combinación con un writeConcern no reconocido.

### Notas

> Nota: Es responsabilidad del llamante asegurarse de que el servidor sea capaz de ejecutar la operación de escritura. Por ejemplo, la ejecución de una operación de escritura en un secundario (excluyendo su base de datos "local") fallará.

### Ver también

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Server::executeCommand() - Ejecuta un comando de base de datos en este servidor
- MongoDB\Driver\Server::executeReadCommand() - Ejecuta un comando de base de datos que lee en este servidor
- MongoDB\Driver\Server::executeReadWriteCommand() - Ejecuta un comando de base de datos que lee y escribe en este servidor
- MongoDB\Driver\Manager::executeWriteCommand() - Ejecuta un comando de base de datos que escribe

# MongoDB\Driver\Server::getHost

(mongodb >=1.0.0)

MongoDB\Driver\Server::getHost — Devuelve el nombre del host del servidor

### Descripción

final public function MongoDB\Driver\Server::getHost(): string

Devuelve el nombre del host del servidor.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el nombre del host del servidor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\Driver\Server::getHost()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");

    $server = $manager->selectServer();

    var_dump($server->getHost());

    ?>

El ejemplo anterior mostrará:

    string(9) "localhost"

### Ver también

- MongoDB\Driver\Server::getInfo() - Devuelve un array de información que describe este servidor
- MongoDB\Driver\ServerDescription::getHost() - Devuelve el nombre de host de este servidor

# MongoDB\Driver\Server::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\Server::getInfo — Devuelve un array de información que describe este servidor

### Descripción

final public function MongoDB\Driver\Server::getInfo(): array

Devuelve un array de información que describe el servidor. Este array se deriva de la respuesta más reciente a la comando » hello obtenida por la » supervisión del servidor.

> Nota: Cuando el controlador está conectado a un balanceador de carga, este método devuelve la respuesta al comando » hello del servidor de respaldo durante el apretón de manos inicial de la conexión. Esto contrasta con otros métodos (por ejemplo, MongoDB\Driver\Server::getType()), que devolverán información sobre el balanceador de carga mismo.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array de información que describe este servidor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\Driver\Server::getInfo()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/');

    $rp = new MongoDB\Driver\ReadPreference('primary');
    $server = $manager->selectServer($rp);

    var_dump($server->getInfo());

    ?>

Resultado del ejemplo anterior es similar a:

    array(23) {
      ["helloOk"]=>
      bool(true)
      ["topologyVersion"]=>
      array(2) {
        ["processId"]=>
        object(MongoDB\BSON\ObjectId)#4 (1) {
          ["oid"]=>
          string(24) "617b6d696a3a89d2f77e6df0"
        }
        ["counter"]=>
        int(6)
      }
      ["hosts"]=>
      array(1) {
        [0]=>
        string(15) "localhost:27017"
      }
      ["setName"]=>
      string(3) "rs0"
      ["setVersion"]=>
      int(1)
      ["ismaster"]=>
      bool(true)
      ["secondary"]=>
      bool(false)
      ["primary"]=>
      string(15) "localhost:27017"
      ["me"]=>
      string(15) "localhost:27017"
      ["electionId"]=>
      object(MongoDB\BSON\ObjectId)#5 (1) {
        ["oid"]=>
        string(24) "7fffffff0000000000000001"
      }
      ["lastWrite"]=>
      array(4) {
        ["opTime"]=>
        array(2) {
          ["ts"]=>
          object(MongoDB\BSON\Timestamp)#6 (2) {
            ["increment"]=>
            string(1) "1"
            ["timestamp"]=>
            string(10) "1635478989"
          }
          ["t"]=>
          int(1)
        }
        ["lastWriteDate"]=>
        object(MongoDB\BSON\UTCDateTime)#7 (1) {
          ["milliseconds"]=>
          string(13) "1635478989000"
        }
        ["majorityOpTime"]=>
        array(2) {
          ["ts"]=>
          object(MongoDB\BSON\Timestamp)#8 (2) {
            ["increment"]=>
            string(1) "1"
            ["timestamp"]=>
            string(10) "1635478989"
          }
          ["t"]=>
          int(1)
        }
        ["majorityWriteDate"]=>
        object(MongoDB\BSON\UTCDateTime)#9 (1) {
          ["milliseconds"]=>
          string(13) "1635478989000"
        }
      }
      ["maxBsonObjectSize"]=>
      int(16777216)
      ["maxMessageSizeBytes"]=>
      int(48000000)
      ["maxWriteBatchSize"]=>
      int(100000)
      ["localTime"]=>
      object(MongoDB\BSON\UTCDateTime)#10 (1) {
        ["milliseconds"]=>
        string(13) "1635478992136"
      }
      ["logicalSessionTimeoutMinutes"]=>
      int(30)
      ["connectionId"]=>
      int(3)
      ["minWireVersion"]=>
      int(0)
      ["maxWireVersion"]=>
      int(13)
      ["readOnly"]=>
      bool(false)
      ["ok"]=>
      float(1)
      ["$clusterTime"]=>
      array(2) {
        ["clusterTime"]=>
        object(MongoDB\BSON\Timestamp)#11 (2) {
          ["increment"]=>
          string(1) "1"
          ["timestamp"]=>
          string(10) "1635478989"
        }
        ["signature"]=>
        array(2) {
          ["hash"]=>
          object(MongoDB\BSON\Binary)#12 (2) {
            ["data"]=>
            string(20) ""
            ["type"]=>
            int(0)
          }
          ["keyId"]=>
          int(0)
        }
      }
      ["operationTime"]=>
      object(MongoDB\BSON\Timestamp)#13 (2) {
        ["increment"]=>
        string(1) "1"
        ["timestamp"]=>
        string(10) "1635478989"
      }
    }

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.11.0 | Cuando el controlador está conectado a un balanceador de carga, este método devuelve la respuesta al comando `hello` del servidor de respaldo a partir del apretón de manos de conexión inicial.

### Ver también

- MongoDB\Driver\ServerDescription::getHelloResponse() - Devuelve la respuesta "hello" más reciente del servidor
- Comando » hello en el manual de MongoDB
- » Especificación de la detección y supervisión de servidores

# MongoDB\Driver\Server::getLatency

(mongodb >=1.0.0)

MongoDB\Driver\Server::getLatency — Devuelve la latencia de este servidor en milisegundos

### Descripción

final public function MongoDB\Driver\Server::getLatency(): ?integer

Devuelve la latencia de este servidor en milisegundos. Es la medida del cliente del tiempo de » ida y vuelta de un comando `hello`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la latencia del servidor en milisegundos, o `null` si no se ha medido ninguna latencia (por ejemplo, el cliente está conectado a un balanceador de carga).

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.11.0 | Este método devolverá `null` si no se ha medido ninguna latencia. En versiones anteriores, siempre se devolvía un número entero y un valor no definido podía ser señalado como `-1`.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\Driver\Server::getLatency()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");

    $server = $manager->selectServer();

    var_dump($server->getLatency());

    ?>

Resultado del ejemplo anterior es similar a:

    int(592)

### Ver también

- MongoDB\Driver\Server::getInfo() - Devuelve un array de información que describe este servidor
- MongoDB\Driver\ServerDescription::getRoundTripTime() - Devuelve el tiempo de ida y vuelta del servidor en milisegundos
- » La especificación sobre el descubrimiento y la supervisión de un servidor

# MongoDB\Driver\Server::getPort

(mongodb >=1.0.0)

MongoDB\Driver\Server::getPort — Devuelve el puerto en el que el servidor está escuchando

### Descripción

final public function MongoDB\Driver\Server::getPort(): int

Devuelve el puerto en el que el servidor está escuchando.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el puerto en el que el servidor está escuchando.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\Driver\Server::getPort()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");

    $server = $manager->selectServer();

    var_dump($server->getPort());

    ?>

El ejemplo anterior mostrará:

    int(27017)

### Ver también

- MongoDB\Driver\Server::getInfo() - Devuelve un array de información que describe este servidor
- MongoDB\Driver\ServerDescription::getPort() - Devuelve el puerto en el que este servidor escucha

# MongoDB\Driver\Server::getServerDescription

(mongodb >=1.13.0)

MongoDB\Driver\Server::getServerDescription — Devuelve una ServerDescription para este servidor

### Descripción

final public function MongoDB\Driver\Server::getServerDescription(): MongoDB\Driver\ServerDescription

Devuelve una MongoDB\Driver\ServerDescription para este servidor. Es un objeto de valor inmutable que describirá el servidor en el momento en que se llame a este método.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una MongoDB\Driver\ServerDescription para este servidor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Server::getTags

(mongodb >=1.0.0)

MongoDB\Driver\Server::getTags — Devuelve un array de tags que describen este servidor en un conjunto de réplicas

### Descripción

final public function MongoDB\Driver\Server::getTags(): array

Devuelve un array de » tags utilizados para describir este servidor en un conjunto de réplicas. El array contendrá cero o más pares clave y valor de tipo string.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array de tags utilizados para describir este servidor en un conjunto de réplicas.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Server::getInfo() - Devuelve un array de información que describe este servidor

# MongoDB\Driver\Server::getType

(mongodb >=1.0.0)

MongoDB\Driver\Server::getType — Devuelve un integer que representa el tipo del servidor

### Descripción

final public function MongoDB\Driver\Server::getType(): int

Devuelve un int que representa el tipo del servidor. El valor corresponderá a una constante MongoDB\Driver\Server.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un int que representa el tipo del servidor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Server::getInfo() - Devuelve un array de información que describe este servidor
- MongoDB\Driver\ServerDescription::getType() - Devuelve un string que indica el tipo de este servidor

# MongoDB\Driver\Server::isArbiter

(mongodb >=1.0.0)

MongoDB\Driver\Server::isArbiter — Verifica si este servidor es un miembro árbitro de un conjunto de réplicas

### Descripción

final public function MongoDB\Driver\Server::isArbiter(): bool

Devuelve si este servidor es un » miembro árbitro de un conjunto de réplicas.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si este servidor es un miembro árbitro de un conjunto de réplicas, y `false` en caso contrario.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Server::getInfo() - Devuelve un array de información que describe este servidor

# MongoDB\Driver\Server::isHidden

(mongodb >=1.0.0)

MongoDB\Driver\Server::isHidden — Indica si este servidor es un miembro oculto de un conjunto de réplicas

### Descripción

final public function MongoDB\Driver\Server::isHidden(): bool

Indica si este servidor es un » miembro oculto de un conjunto de réplicas.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si este servidor es un miembro oculto de un conjunto de réplicas, y `false` en caso contrario.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Server::getInfo() - Devuelve un array de información que describe este servidor

# MongoDB\Driver\Server::isPassive

(mongodb >=1.0.0)

MongoDB\Driver\Server::isPassive — Verifica si el servidor es un miembro pasivo del conjunto de réplicas

### Descripción

final public function MongoDB\Driver\Server::isPassive(): bool

Devuelve si el servidor es un » miembro pasivo de un conjunto de réplicas (i.e. su prioridad es `0`).

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si el servidor es un miembro pasivo de un conjunto de réplicas, y `false` en caso contrario.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Server::getInfo() - Devuelve un array de información que describe este servidor

# MongoDB\Driver\Server::isPrimary

(mongodb >=1.0.0)

MongoDB\Driver\Server::isPrimary — Verifica si este servidor es un miembro principal de un conjunto de réplicas

### Descripción

final public function MongoDB\Driver\Server::isPrimary(): bool

Devuelve si este servidor es un » miembro principal de un conjunto de réplicas.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si este servidor es un miembro principal de un conjunto de réplicas, y `false` en caso contrario.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Server::getInfo() - Devuelve un array de información que describe este servidor

# MongoDB\Driver\Server::isSecondary

(mongodb >=1.0.0)

MongoDB\Driver\Server::isSecondary — Verifica si este servidor es un miembro secundario de un conjunto de réplicas

### Descripción

final public function MongoDB\Driver\Server::isSecondary(): bool

Devuelve si este servidor es un » miembro secundario de un conjunto de réplicas.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si este servidor es un miembro secundario de un conjunto de réplicas, y `false` en caso contrario.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Server::getInfo() - Devuelve un array de información que describe este servidor

## Tabla de contenidos

- MongoDB\Driver\Server::__construct — Crear un nuevo servidor (no utilizado)
- MongoDB\Driver\Server::executeBulkWrite — Ejecuta una o varias operaciones de escritura en este servidor
- MongoDB\Driver\Server::executeBulkWriteCommand — Ejecuta operaciones de escritura en este servidor utilizando el comando bulkWrite
- MongoDB\Driver\Server::executeCommand — Ejecuta un comando de base de datos en este servidor
- MongoDB\Driver\Server::executeQuery — Ejecuta una consulta de base de datos en este servidor
- MongoDB\Driver\Server::executeReadCommand — Ejecuta un comando de base de datos que lee en este servidor
- MongoDB\Driver\Server::executeReadWriteCommand — Ejecuta un comando de base de datos que lee y escribe en este servidor
- MongoDB\Driver\Server::executeWriteCommand — Ejecuta un comando de base de datos que escribe en este servidor
- MongoDB\Driver\Server::getHost — Devuelve el nombre del host del servidor
- MongoDB\Driver\Server::getInfo — Devuelve un array de información que describe este servidor
- MongoDB\Driver\Server::getLatency — Devuelve la latencia de este servidor en milisegundos
- MongoDB\Driver\Server::getPort — Devuelve el puerto en el que el servidor está escuchando
- MongoDB\Driver\Server::getServerDescription — Devuelve una ServerDescription para este servidor
- MongoDB\Driver\Server::getTags — Devuelve un array de tags que describen este servidor en un conjunto de réplicas
- MongoDB\Driver\Server::getType — Devuelve un integer que representa el tipo del servidor
- MongoDB\Driver\Server::isArbiter — Verifica si este servidor es un miembro árbitro de un conjunto de réplicas
- MongoDB\Driver\Server::isHidden — Indica si este servidor es un miembro oculto de un conjunto de réplicas
- MongoDB\Driver\Server::isPassive — Verifica si el servidor es un miembro pasivo del conjunto de réplicas
- MongoDB\Driver\Server::isPrimary — Verifica si este servidor es un miembro principal de un conjunto de réplicas
- MongoDB\Driver\Server::isSecondary — Verifica si este servidor es un miembro secundario de un conjunto de réplicas

# La clase MongoDB\Driver\ServerDescription

(mongodb >=1.13.0)

## Introducción

La clase MongoDB\Driver\ServerDescription es un objeto valor que representa un servidor al que el controlador está conectado. Las instancias de esta clase son devueltas por los métodos MongoDB\Driver\Server::getServerDescription() y MongoDB\Driver\Monitoring\ServerChangedEvent.

## Sinopsis de la Clase

final class MongoDB\Driver\ServerDescription {
/* Constantes */
const string TYPE_UNKNOWN = "Unknown";
const string TYPE_STANDALONE = "Standalone";
const string TYPE_MONGOS = "Mongos";
const string TYPE_POSSIBLE_PRIMARY = "PossiblePrimary";
const string TYPE_RS_PRIMARY = "RSPrimary";
const string TYPE_RS_SECONDARY = "RSSecondary";
const string TYPE_RS_ARBITER = "RSArbiter";
const string TYPE_RS_OTHER = "RSOther";
const string TYPE_RS_GHOST = "RSGhost";
const string TYPE_LOAD_BALANCER = "LoadBalancer";
/* Métodos */
final public function getHelloResponse(): array
final public function getHost(): string
final public function getLastUpdateTime(): int
final public function getPort(): int
final public function getRoundTripTime(): ?int
final public function getType(): string
}

## Constantes predefinidas

`MongoDB\Driver\ServerDescription::TYPE_UNKNOWN`
  Tipo de servidor desconocido, devuelto por MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_STANDALONE`
  Tipo de servidor independiente, devuelto por MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_MONGOS`
  Tipo de servidor Mongos, devuelto por MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_POSSIBLE_PRIMARY`
  Tipo de servidor posible primario de conjunto de réplicas, devuelto por MongoDB\Driver\ServerDescription::getType(). Un servidor puede ser identificado como posible primario si aún no ha sido verificado pero otro miembro del conjunto de réplicas considera que es el primario.
`MongoDB\Driver\ServerDescription::TYPE_RS_PRIMARY`
  Tipo de servidor primario de conjunto de réplicas, devuelto por MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_RS_SECONDARY`
  Tipo de servidor secundario de conjunto de réplicas, devuelto por MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_RS_ARBITER`
  Tipo de servidor árbitro de conjunto de réplicas, devuelto por MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::ServerDescription::TYPE_RS_OTHER`
  Tipo de servidor de conjunto de réplicas de otro tipo, devuelto por MongoDB\Driver\ServerDescription::getType(). Estos servidores pueden estar ocultos, iniciándose o en recuperación. No pueden ser consultados, pero sus listas de hosts son útiles para descubrir la configuración actual del conjunto de réplicas.
`MongoDB\Driver\ServerDescription::TYPE_RS_GHOST`
  Tipo de servidor fantasma de conjunto de réplicas, devuelto por MongoDB\Driver\ServerDescription::getType(). Los servidores pueden ser identificados como tales en al menos tres situaciones: brevemente durante el inicio del servidor; en un conjunto de réplicas no inicializado; o cuando el servidor es excluido (es decir, eliminado de la configuración del conjunto de réplicas). No pueden ser consultados, ni su lista de hosts puede usarse para descubrir la configuración actual del conjunto de réplicas; sin embargo, el cliente puede monitorear este servidor con la esperanza de que pase a un estado más útil.
`MongoDB\Driver\ServerDescription::TYPE_LOAD_BALANCER`
  Tipo de servidor equilibrador de carga, devuelto por MongoDB\Driver\ServerDescription::getType().

# MongoDB\Driver\ServerDescription::getHelloResponse

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getHelloResponse — Devuelve la respuesta "hello" más reciente del servidor

### Descripción

final public function MongoDB\Driver\ServerDescription::getHelloResponse(): array

Devuelve un array de información que describe el servidor. Este array se deriva de la respuesta » hello más reciente (en el momento en que la MongoDB\Driver\ServerDescription fue construida) obtenida a través de » la supervisión del servidor.

> Nota: Cuando el controlador está conectado a un balanceador de carga, este método devolverá un array vacío porque los balanceadores de carga no son supervisados. Esto contrasta con MongoDB\Driver\Server::getInfo(), que devolvería la respuesta del » hello de la comando de apretón de manos de conexión inicial del servidor base.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array de información que describe este servidor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Server::getInfo() - Devuelve un array de información que describe este servidor
- » hello comando en el manual de MongoDB
- » Descubrimiento y supervisión de servidores

# MongoDB\Driver\ServerDescription::getHost

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getHost — Devuelve el nombre de host de este servidor

### Descripción

final public function MongoDB\Driver\ServerDescription::getHost(): string

Devuelve el nombre de host de este servidor.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el nombre de host de este servidor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Server::getHost() - Devuelve el nombre del host del servidor

# MongoDB\Driver\ServerDescription::getLastUpdateTime

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getLastUpdateTime — Devuelve la hora de la última actualización del servidor en microsegundos

### Descripción

final public function MongoDB\Driver\ServerDescription::getLastUpdateTime(): int

Devuelve la hora de la última actualización del servidor en microsegundos.

> Nota: El valor devuelto es un timestamp monotónico, que comienza en un punto arbitrario. Por lo tanto, es únicamente adecuado para ser comparado con otros valores de retorno de MongoDB\Driver\ServerDescription::getLastUpdateTime().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la hora de la última actualización del servidor en microsegundos.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\ServerDescription::getPort

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getPort — Devuelve el puerto en el que este servidor escucha

### Descripción

final public function MongoDB\Driver\ServerDescription::getPort(): int

Devuelve el puerto en el que este servidor escucha.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el puerto en el que este servidor escucha.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Server::getPort() - Devuelve el puerto en el que el servidor está escuchando

# MongoDB\Driver\ServerDescription::getRoundTripTime

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getRoundTripTime — Devuelve el tiempo de ida y vuelta del servidor en milisegundos

### Descripción

final public function MongoDB\Driver\ServerDescription::getRoundTripTime(): ?int

Devuelve el tiempo de ida y vuelta del servidor en milisegundos. Se trata de la medida del cliente de la duración de una comando » hello.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el tiempo de ida y vuelta del servidor en milisegundos.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Server::getLatency() - Devuelve la latencia de este servidor en milisegundos

# MongoDB\Driver\ServerDescription::getType

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getType — Devuelve un string que indica el tipo de este servidor

### Descripción

final public function MongoDB\Driver\ServerDescription::getType(): string

Devuelve un string que indica el tipo de este servidor. El valor estará correlacionado con una constante MongoDB\Driver\ServerDescription.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un string que indica el tipo de este servidor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Server::getType() - Devuelve un integer que representa el tipo del servidor

## Tabla de contenidos

- MongoDB\Driver\ServerDescription::getHelloResponse — Devuelve la respuesta "hello" más reciente del servidor
- MongoDB\Driver\ServerDescription::getHost — Devuelve el nombre de host de este servidor
- MongoDB\Driver\ServerDescription::getLastUpdateTime — Devuelve la hora de la última actualización del servidor en microsegundos
- MongoDB\Driver\ServerDescription::getPort — Devuelve el puerto en el que este servidor escucha
- MongoDB\Driver\ServerDescription::getRoundTripTime — Devuelve el tiempo de ida y vuelta del servidor en milisegundos
- MongoDB\Driver\ServerDescription::getType — Devuelve un string que indica el tipo de este servidor

# La clase MongoDB\Driver\TopologyDescription

(mongodb >=1.13.0)

## Introducción

La clase MongoDB\Driver\TopologyDescription es un objeto valor que representa una topología a la que el controlador está conectado. Las instancias de esta clase son devueltas por los métodos de MongoDB\Driver\Monitoring\TopologyChangedEvent.

## Sinopsis de la Clase

final class MongoDB\Driver\TopologyDescription {
/* Constantes */
const string TYPE_UNKNOWN = "Unknown";
const string TYPE_SINGLE = "Single";
const string TYPE_SHARDED = "Sharded";
const string TYPE_REPLICA_SET_NO_PRIMARY = "ReplicaSetNoPrimary";
const string TYPE_REPLICA_SET_WITH_PRIMARY = "ReplicaSetWithPrimary";
const string TYPE_LOAD_BALANCED = "LoadBalanced";
/* Métodos */
final public function getServers(): array
final public function getType(): string
final public function hasReadableServer(?MongoDB\Driver\ReadPreference `$readPreference` = `null`): bool
final public function hasWritableServer(): bool
}

## Constantes predefinidas

`MongoDB\Driver\TopologyDescription::TYPE_UNKNOWN`
  Tipo de topología desconocido, devuelto por MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_SINGLE`
  Servidor único (es decir, conexión directa), devuelto por MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_SHARDED`
  Agrupación particionada, devuelto por MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_REPLICA_SET_NO_PRIMARY`
  Conjunto de réplicas sin servidor primario, devuelto por MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_REPLICA_SET_WITH_PRIMARY`
  Conjunto de réplicas con un servidor primario, devuelto por MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_LOAD_BALANCED`
  Topología con equilibrio de carga, devuelto por MongoDB\Driver\TopologyDescription::getType().

# MongoDB\Driver\TopologyDescription::getServers

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::getServers — Devuelve los servidores de la topología

### Descripción

final public function MongoDB\Driver\TopologyDescription::getServers(): array

Devuelve un array de objetos MongoDB\Driver\ServerDescription correspondiente a los servidores conocidos en la topología.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array de objetos MongoDB\Driver\ServerDescription correspondiente a los servidores conocidos en la topología.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\TopologyDescription::getType

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::getType — Devuelve un string que denota el tipo de esta topología

### Descripción

final public function MongoDB\Driver\TopologyDescription::getType(): string

Devuelve un string que denota el tipo de esta topología. El valor estará correlacionado con una constante de MongoDB\Driver\TopologyDescription.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un string que denota el tipo de esta topología.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\TopologyDescription::hasReadableServer

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::hasReadableServer — Indica si la topología tiene un servidor legible

### Descripción

final public function MongoDB\Driver\TopologyDescription::hasReadableServer(?MongoDB\Driver\ReadPreference `$readPreference` = `null`): bool

Indica si la topología tiene un servidor legible o, si `readPreference` está especificado, un servidor que corresponde a la preferencia de lectura especificada.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Indica si la topología tiene un servidor legible o, si `readPreference` está especificado, un servidor que corresponde a la preferencia de lectura especificada.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\TopologyDescription::hasWritableServer

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::hasWritableServer — Indica si la topología dispone de un servidor en escritura

### Descripción

final public function MongoDB\Driver\TopologyDescription::hasWritableServer(): bool

Indica si la topología dispone de un servidor en escritura.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Indica si la topología dispone de un servidor en escritura.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

## Tabla de contenidos

- MongoDB\Driver\TopologyDescription::getServers — Devuelve los servidores de la topología
- MongoDB\Driver\TopologyDescription::getType — Devuelve un string que denota el tipo de esta topología
- MongoDB\Driver\TopologyDescription::hasReadableServer — Indica si la topología tiene un servidor legible
- MongoDB\Driver\TopologyDescription::hasWritableServer — Indica si la topología dispone de un servidor en escritura

# La clase MongoDB\Driver\WriteConcernError

(mongodb >=1.0.0)

## Introducción

La clase MongoDB\Driver\WriteConcernError contiene información relativa a un error de escritura y puede ser devuelta por MongoDB\Driver\WriteResult::getWriteConcernError().

## Sinopsis de la Clase

final class MongoDB\Driver\WriteConcernError {
/* Propiedades */
public readonly string $message;
public readonly int $code;
public readonly ?object $info;
/* Métodos */
final public function getCode(): int
final public function getInfo(): ?object
final public function getMessage(): string
}

## Propiedades

message
  El mensaje de error.
code
  El código de error.
info
  El documento de información adicional sobre el error, o `null` si no está disponible.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.3.0 | Las propiedades public readonly han sido añadidas.

# MongoDB\Driver\WriteConcernError::getCode

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getCode — Devuelve el código de error de WriteConcernError

### Descripción

final public function MongoDB\Driver\WriteConcernError::getCode(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el código de error de WriteConcernError

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\Driver\WriteConcernError::getCode()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

    try {
        $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteConcernError()->getCode());
    }

    ?>

Resultado del ejemplo anterior es similar a:

    int(64)

### Ver también

- » Referencia Write Concern

# MongoDB\Driver\WriteConcernError::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getInfo — Devuelve el documento de metadatos para WriteConcernError

### Descripción

final public function MongoDB\Driver\WriteConcernError::getInfo(): ?object

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el documento de metadatos para WriteConcernError, o `null` si no hay metadatos disponibles.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\Driver\WriteConcernError::getInfo()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

    try {
        $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteConcernError()->getInfo());
    }

    ?>

Resultado del ejemplo anterior es similar a:

    object(stdClass)#1 (1) {
      ["wtimeout"]=>
      bool(true)
    }

### Ver también

- » Referencia Write Concern

# MongoDB\Driver\WriteConcernError::getMessage

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getMessage — Devuelve el mensaje de error del WriteConcernError

### Descripción

final public function MongoDB\Driver\WriteConcernError::getMessage(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el mensaje de error del WriteConcernError

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\Driver\WriteConcernError::getMessage()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

    try {
        $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteConcernError()->getMessage());
    }

    ?>

Resultado del ejemplo anterior es similar a:

    string(33) "waiting for replication timed out"

### Ver también

- » Referencia Write Concern

## Tabla de contenidos

- MongoDB\Driver\WriteConcernError::getCode — Devuelve el código de error de WriteConcernError
- MongoDB\Driver\WriteConcernError::getInfo — Devuelve el documento de metadatos para WriteConcernError
- MongoDB\Driver\WriteConcernError::getMessage — Devuelve el mensaje de error del WriteConcernError

# La clase MongoDB\Driver\WriteError

(mongodb >=1.0.0)

## Introducción

La clase MongoDB\Driver\WriteError contiene información sobre un error de escritura y puede ser devuelta como elemento de un array a partir de MongoDB\Driver\WriteResult::getWriteErrors().

## Sinopsis de la Clase

final class MongoDB\Driver\WriteError {
/* Propiedades */
public readonly string $message;
public readonly int $code;
public readonly int $index;
public readonly ?object $info;
/* Métodos */
final public function getCode(): int
final public function getIndex(): int
final public function getInfo(): ?object
final public function getMessage(): string
}

## Propiedades

message
  El mensaje de error.
code
  El código de error.
index
  El índice de la operación de escritura dentro del MongoDB\Driver\BulkWrite que ha provocado el error.
info
  El documento de información adicional sobre el error, o `null` si no está disponible.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.3.0 | Las propiedades public readonly han sido añadidas.

# MongoDB\Driver\WriteError::getCode

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getCode — Devuelve el código de error de WriteError

### Descripción

final public function MongoDB\Driver\WriteError::getCode(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el código de error de WriteError

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\Driver\WriteError::getCode()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors()[0]->getCode());
    }

    ?>

Resultado del ejemplo anterior es similar a:

    int(11000)

# MongoDB\Driver\WriteError::getIndex

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getIndex — Devuelve el índice de la operación de escritura correspondiente a este WriteError

### Descripción

final public function MongoDB\Driver\WriteError::getIndex(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el índice de la operación de escritura (a partir de MongoDBDriverBulkWrite) correspondiente a este WriteError.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\Driver\WriteError::getIndex()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors()[0]->getIndex());
    }

    ?>

Resultado del ejemplo anterior es similar a:

    int(1)

### Ver también

- MongoDB\Driver\BulkWrite

# MongoDB\Driver\WriteError::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getInfo — Devuelve el documento de metadatos para WriteError

### Descripción

final public function MongoDB\Driver\WriteError::getInfo(): ?object

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el documento de metadatos para WriteError, o `null` si no hay metadatos disponibles.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\WriteError::getMessage

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getMessage — Devuelve el mensaje de error del WriteError

### Descripción

final public function MongoDB\Driver\WriteError::getMessage(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el mensaje de error del WriteError.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\Driver\WriteError::getMessage()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors()[0]->getMessage());
    }

    ?>

Resultado del ejemplo anterior es similar a:

    string(70) "E11000 duplicate key error index: db.collection.$_id_ dup key: { : 1 }"

## Tabla de contenidos

- MongoDB\Driver\WriteError::getCode — Devuelve el código de error de WriteError
- MongoDB\Driver\WriteError::getIndex — Devuelve el índice de la operación de escritura correspondiente a este WriteError
- MongoDB\Driver\WriteError::getInfo — Devuelve el documento de metadatos para WriteError
- MongoDB\Driver\WriteError::getMessage — Devuelve el mensaje de error del WriteError

# La clase MongoDB\Driver\WriteResult

(mongodb >=1.0.0)

## Introducción

La clase MongoDB\Driver\WriteResult contiene las informaciones sobre una ejecución MongoDB\Driver\BulkWrite y puede ser retornado por MongoDB\Driver\Manager::executeBulkWrite().

## Sinopsis de la Clase

final class MongoDB\Driver\WriteResult {
/* Propiedades */
public readonly ?int $insertedCount;
public readonly ?int $matchedCount;
public readonly ?int $modifiedCount;
public readonly ?int $deletedCount;
public readonly ?int $upsertedCount;
public readonly MongoDB\Driver\Server $server;
public readonly array $upsertedIds;
public readonly array $writeErrors;
public readonly ?MongoDB\Driver\WriteConcernError $writeConcernError;
public readonly ?MongoDB\Driver\WriteConcern $writeConcern;
public readonly array $errorReplies;
/* Métodos */
final public function getDeletedCount(): int
final public function getInsertedCount(): int
final public function getMatchedCount(): int
final public function getModifiedCount(): int
final public function getServer(): MongoDB\Driver\Server
final public function getUpsertedCount(): int
final public function getUpsertedIds(): array
final public function getWriteConcernError(): ?MongoDB\Driver\WriteConcernError
final public function getWriteErrors(): array
final public function isAcknowledged(): bool
}

## Propiedades

insertedCount
  El número de documentos insertados (excluyendo los upserts), o `null` si el write concern no ha solicitado acuse de recibo.
matchedCount
  El número de documentos coincidentes con las operaciones de actualización y reemplazo, o `null` si el write concern no ha solicitado acuse de recibo.
modifiedCount
  El número de documentos modificados por las operaciones de actualización y reemplazo, o `null` si el write concern no ha solicitado acuse de recibo o si el servidor no ha proporcionado esta información.
deletedCount
  El número de documentos eliminados, o `null` si el write concern no ha solicitado acuse de recibo.
upsertedCount
  El número de documentos upserted, o `null` si el write concern no ha solicitado acuse de recibo.
server
  El servidor que ha ejecutado el bulk write.
upsertedIds
  Un array de valores `_id` para los documentos upserted. Las claves del array corresponden al índice de la operación de escritura de MongoDB\Driver\BulkWrite.
writeErrors
  Un array de MongoDB\Driver\WriteError para los errores de escritura producidos durante la ejecución.
writeConcernError
  El MongoDB\Driver\WriteConcernError que ha ocurrido, o `null` si no ha ocurrido ningún error de write concern.
writeConcern
  El MongoDB\Driver\WriteConcern utilizado para el bulk write, o `null` si no está disponible.
errorReplies
  Un array de documentos de respuesta de error procedentes del servidor.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.3.0 | Las propiedades public readonly han sido añadidas.

# MongoDB\Driver\WriteResult::getDeletedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getDeletedCount — Devuelve el número de documentos eliminados

### Descripción

final public function MongoDB\Driver\WriteResult::getDeletedCount(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de documentos eliminados.

### Errores/Excepciones

- Levanta una excepción MongoDB\Driver\Exception\LogicException si la escritura no ha sido reconocida.
- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Este método ahora lanza una excepción cuando es llamado para una escritura no reconocida, en lugar de retornar `null`.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\Driver\WriteResult::getDeletedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getDeletedCount());

    ?>

Resultado del ejemplo anterior es similar a:

    int(1)

### Ver también

- MongoDB\Driver\WriteResult::isAcknowledged() - Indica si la escritura ha sido reconocida

# MongoDB\Driver\WriteResult::getInsertedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getInsertedCount — Devuelve el número de documentos insertados (excepto Upserts)

### Descripción

final public function MongoDB\Driver\WriteResult::getInsertedCount(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de documentos insertados (excepto Upserts permitidos).

### Errores/Excepciones

- Levanta una excepción MongoDB\Driver\Exception\LogicException si la escritura no ha sido reconocida.
- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Este método ahora lanza una excepción cuando es llamado para una escritura no reconocida, en lugar de retornar `null`.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\Driver\WriteResult::getInsertedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getInsertedCount());

    ?>

Resultado del ejemplo anterior es similar a:

    int(1)

### Ver también

- MongoDB\Driver\WriteResult::isAcknowledged() - Indica si la escritura ha sido reconocida

# MongoDB\Driver\WriteResult::getMatchedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getMatchedCount — Devuelve el número de documentos seleccionados para la actualización

### Descripción

final public function MongoDB\Driver\WriteResult::getMatchedCount(): int

Si la operación de actualización no resulta en ninguna modificación del documento (por ejemplo, al establecer el valor de un campo en su valor actual), el número correspondiente puede ser mayor que el valor devuelto por MongoDB\Driver\WriteResult::getModifiedCount().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de documentos seleccionados para la actualización.

### Errores/Excepciones

- Levanta una excepción MongoDB\Driver\Exception\LogicException si la escritura no ha sido reconocida.
- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Este método ahora lanza una excepción cuando es llamado para una escritura no reconocida, en lugar de retornar `null`.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\Driver\WriteResult::getMatchedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getMatchedCount());

    ?>

Resultado del ejemplo anterior es similar a:

    int(1)

### Ver también

- MongoDB\Driver\WriteResult::getModifiedCount() - Devuelve el número de documentos existentes actualizados
- MongoDB\Driver\WriteResult::isAcknowledged() - Indica si la escritura ha sido reconocida

# MongoDB\Driver\WriteResult::getModifiedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getModifiedCount — Devuelve el número de documentos existentes actualizados

### Descripción

final public function MongoDB\Driver\WriteResult::getModifiedCount(): int

Si la operación de actualización no resulta en ninguna modificación del documento (por ejemplo, al establecer el valor de un campo en su valor actual), el número modificado puede ser inferior al valor devuelto por MongoDB\Driver\WriteResult::getMatchedCount().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de documentos existentes actualizados.

### Errores/Excepciones

- Levanta una excepción MongoDB\Driver\Exception\LogicException si la escritura no ha sido reconocida.
- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Este método ahora lanza una excepción cuando es llamado para una escritura no reconocida, en lugar de retornar `null`.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\Driver\WriteResult::getModifiedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getModifiedCount());

    ?>

Resultado del ejemplo anterior es similar a:

    int(1)

### Ver también

- MongoDB\Driver\WriteResult::getMatchedCount() - Devuelve el número de documentos seleccionados para la actualización
- MongoDB\Driver\WriteResult::isAcknowledged() - Indica si la escritura ha sido reconocida

# MongoDB\Driver\WriteResult::getServer

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getServer — Devuelve el servidor asociado a este resultado de escritura

### Descripción

final public function MongoDB\Driver\WriteResult::getServer(): MongoDB\Driver\Server

Devuelve el MongoDB\Driver\Server asociado a este resultado de escritura. Se trata del servidor que ejecutó el MongoDB\Driver\BulkWrite.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el MongoDB\Driver\Server asociado a este resultado de escritura.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\Driver\WriteResult::getServer()

    <?php

    $manager = new MongoDB\Driver\Manager;
    $server = $manager->selectServer();

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $result = $server->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getServer() == $server);

    ?>

Resultado del ejemplo anterior es similar a:

    bool(true)

### Ver también

- MongoDB\Driver\Server

# MongoDB\Driver\WriteResult::getUpsertedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getUpsertedCount — Devuelve el número de documentos insertados por un upsert

### Descripción

final public function MongoDB\Driver\WriteResult::getUpsertedCount(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de documentos insertados por un upsert.

### Errores/Excepciones

- Levanta una excepción MongoDB\Driver\Exception\LogicException si la escritura no ha sido reconocida.
- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Este método ahora lanza una excepción cuando es llamado para una escritura no reconocida, en lugar de retornar `null`.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\Driver\WriteResult::getUpsertedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getUpsertedCount());

    ?>

Resultado del ejemplo anterior es similar a:

    int(2)

### Ver también

- MongoDB\Driver\WriteResult::getUpsertedIds() - Devuelve un array de identificadores para los documentos upserted
- MongoDB\Driver\WriteResult::isAcknowledged() - Indica si la escritura ha sido reconocida

# MongoDB\Driver\WriteResult::getUpsertedIds

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getUpsertedIds — Devuelve un array de identificadores para los documentos upserted

### Descripción

final public function MongoDB\Driver\WriteResult::getUpsertedIds(): array

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array de identificadores (por ejemplo, el valor del campo `"_id"`) para los documentos upserted. Las claves del array corresponden al índice de la operación de escritura (desde MongoDBDriverBulkWrite) responsable del upsert.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\Driver\WriteResult::getUpsertedIds()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getUpsertedIds());

    ?>

Resultado del ejemplo anterior es similar a:

    array(2) {
      [2]=>
      object(MongoDB\BSON\ObjectId)#4 (1) {
        ["oid"]=>
        string(24) "580e62a224f2302f191b880b"
      }
      [3]=>
      object(MongoDB\BSON\ObjectId)#5 (1) {
        ["oid"]=>
        string(24) "580e62a224f2302f191b880c"
      }
    }

### Ver también

- MongoDB\Driver\WriteResult::getUpsertedCount() - Devuelve el número de documentos insertados por un upsert
- MongoDB\Driver\WriteResult::isAcknowledged() - Indica si la escritura ha sido reconocida

# MongoDB\Driver\WriteResult::getWriteConcernError

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getWriteConcernError — Devuelve cualquier error de WriteConcern que haya ocurrido

### Descripción

final public function MongoDB\Driver\WriteResult::getWriteConcernError(): ?MongoDB\Driver\WriteConcernError

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un MongoDBDriverWriteConcernError si se encontró un error de preocupación de escritura durante la operación de escritura, y `null` en caso contrario.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\Driver\WriteResult::getWriteConcernError()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

    try {
        $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteConcernError());
    }

    ?>

Resultado del ejemplo anterior es similar a:

    object(MongoDB\Driver\WriteConcernError)#6 (3) {
      ["message"]=>
      string(33) "waiting for replication timed out"
      ["code"]=>
      int(64)
      ["info"]=>
      object(stdClass)#7 (1) {
        ["wtimeout"]=>
        bool(true)
      }
    }

### Ver también

- MongoDB\Driver\WriteConcern
- » Referencia Write Concern

# MongoDB\Driver\WriteResult::getWriteErrors

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getWriteErrors — Devuelve todos los errores de escritura que se han producido

### Descripción

final public function MongoDB\Driver\WriteResult::getWriteErrors(): array

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array de objetos MongoDBDriverWriteError para todos los errores de escritura encontrados durante la operación de escritura. El array estará vacío si no se ha producido ningún error de escritura.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 MongoDB\Driver\WriteResult::getWriteErrors() con un solo error

    <?php

    $manager = new MongoDB\Driver\Manager;

    /* Por omisión, las operaciones de escritura en bloque se ejecutan en serie en
     * el orden y la ejecución se detendrá después del primer error.
     */
    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 3]);
    $bulk->insert(['_id' => 4]);
    $bulk->insert(['_id' => 4]);

    try {
        $result = $manager->executeBulkWrite('db.collection', $bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors());
    }

    ?>

Resultado del ejemplo anterior es similar a:

    array(1) {
      [0]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(81) "E11000 duplicate key error collection: db.collection index: _id_ dup key: { : 2 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(2)
        ["info"]=>
        NULL
      }
    }

Ejemplo #2 MongoDB\Driver\WriteResult::getWriteErrors() con múltiples errores

    <?php

    $manager = new MongoDB\Driver\Manager;

    /* La opción "ordered" puede ser utilizada para permitir que las operaciones
     * de escritura en bloque continúen ejecutándose después del primer error.
     */
    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => false]);
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 3]);
    $bulk->insert(['_id' => 4]);
    $bulk->insert(['_id' => 4]);

    try {
        $result = $manager->executeBulkWrite('db.collection', $bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors());
    }

    ?>

Resultado del ejemplo anterior es similar a:

    array(2) {
      [0]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(81) "E11000 duplicate key error collection: db.collection index: _id_ dup key: { : 2 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(2)
        ["info"]=>
        NULL
      }
      [1]=>
      object(MongoDB\Driver\WriteError)#6 (4) {
        ["message"]=>
        string(81) "E11000 duplicate key error collection: db.collection index: _id_ dup key: { : 4 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(5)
        ["info"]=>
        NULL
      }
    }

### Ver también

- MongoDB\Driver\WriteError

# MongoDB\Driver\WriteResult::isAcknowledged

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::isAcknowledged — Indica si la escritura ha sido reconocida

### Descripción

final public function MongoDB\Driver\WriteResult::isAcknowledged(): bool

Si la escritura ha sido reconocida, otros campos de conteo estarán disponibles para el objeto MongoDB\Driver\WriteResult.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si la escritura ha sido reconocida, y `false` en caso contrario.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 MongoDB\Driver\WriteResult::isAcknowledged() con la preocupación de escritura reconocida

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->isAcknowledged());

    ?>

El ejemplo anterior mostrará:

    bool(true)

Ejemplo #2 MongoDB\Driver\WriteResult::isAcknowledged() con la preocupación de escritura no reconocida

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(0);

    $result = $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);

    var_dump($result->isAcknowledged());

    ?>

El ejemplo anterior mostrará:

    bool(false)

### Ver también

- MongoDB\Driver\WriteConcern
- » Referencia sobre la Preocupación de Escritura

## Tabla de contenidos

- MongoDB\Driver\WriteResult::getDeletedCount — Devuelve el número de documentos eliminados
- MongoDB\Driver\WriteResult::getInsertedCount — Devuelve el número de documentos insertados (excepto Upserts)
- MongoDB\Driver\WriteResult::getMatchedCount — Devuelve el número de documentos seleccionados para la actualización
- MongoDB\Driver\WriteResult::getModifiedCount — Devuelve el número de documentos existentes actualizados
- MongoDB\Driver\WriteResult::getServer — Devuelve el servidor asociado a este resultado de escritura
- MongoDB\Driver\WriteResult::getUpsertedCount — Devuelve el número de documentos insertados por un upsert
- MongoDB\Driver\WriteResult::getUpsertedIds — Devuelve un array de identificadores para los documentos upserted
- MongoDB\Driver\WriteResult::getWriteConcernError — Devuelve cualquier error de WriteConcern que haya ocurrido
- MongoDB\Driver\WriteResult::getWriteErrors — Devuelve todos los errores de escritura que se han producido
- MongoDB\Driver\WriteResult::isAcknowledged — Indica si la escritura ha sido reconocida

# La clase MongoDB\Driver\BulkWriteCommandResult

(mongodb >=2.1.0)

## Introducción

La clase MongoDB\Driver\BulkWriteCommandResult encapsula información sobre un MongoDB\Driver\BulkWriteCommand ejecutado y es devuelta por MongoDB\Driver\Manager::executeBulkWriteCommand().

## Sinopsis de la Clase

final class MongoDB\Driver\BulkWriteCommandResult {
/* Métodos */
final public function getDeletedCount(): int
final public function getDeleteResults(): ?MongoDB\BSON\Document
final public function getInsertedCount(): int
final public function getInsertResults(): ?MongoDB\BSON\Document
final public function getMatchedCount(): int
final public function getModifiedCount(): int
final public function getUpdateResults(): ?MongoDB\BSON\Document
final public function getUpsertedCount(): int
final public function isAcknowledged(): bool
}

# MongoDB\Driver\BulkWriteCommandResult::getDeletedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getDeletedCount — Devuelve el número de documentos eliminados

### Descripción

final public function MongoDB\Driver\BulkWriteCommandResult::getDeletedCount(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número total de documentos eliminados por todas las operaciones.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Levanta una excepción MongoDB\Driver\Exception\LogicException si la escritura no ha sido reconocida.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\BulkWriteCommandResult::getDeletedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getDeletedCount());

    ?>

El ejemplo anterior mostrará:

    int(3)

### Ver también

- MongoDB\Driver\BulkWriteCommandResult::getDeleteResults() - Devuelve resultados detallados para eliminaciones exitosas
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Devuelve si la escritura fue reconocida

# MongoDB\Driver\BulkWriteCommandResult::getDeleteResults

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getDeleteResults — Devuelve resultados detallados para eliminaciones exitosas

### Descripción

final public function MongoDB\Driver\BulkWriteCommandResult::getDeleteResults(): ?MongoDB\BSON\Document

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un documento que contiene el resultado de cada operación de eliminación exitosa, o `null` si no se solicitaron resultados detallados. Las claves del documento corresponderán al índice de la operación de escritura desde MongoDB\Driver\BulkWriteCommand.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Levanta una excepción MongoDB\Driver\Exception\LogicException si la escritura no ha sido reconocida.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\BulkWriteCommandResult::getDeleteResults()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['verboseResults' => true]);
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getDeleteResults()->toPHP());

    ?>

Resultado del ejemplo anterior es similar a:

    object(stdClass)#7 (1) {
      ["4"]=>
      object(stdClass)#6 (1) {
        ["deletedCount"]=>
        object(MongoDB\BSON\Int64)#5 (1) {
          ["integer"]=>
          string(1) "3"
        }
      }
    }

### Ver también

- MongoDB\Driver\BulkWriteCommandResult::getDeletedCount() - Devuelve el número de documentos eliminados
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Devuelve si la escritura fue reconocida

# MongoDB\Driver\BulkWriteCommandResult::getInsertedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getInsertedCount — Devuelve el número de documentos insertados

### Descripción

final public function MongoDB\Driver\BulkWriteCommandResult::getInsertedCount(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número total de documentos insertados (excluyendo los upserts) por todas las operaciones.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Levanta una excepción MongoDB\Driver\Exception\LogicException si la escritura no ha sido reconocida.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\BulkWriteCommandResult::getInsertedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getInsertedCount());

    ?>

El ejemplo anterior mostrará:

    int(1)

### Ver también

- MongoDB\Driver\BulkWriteCommandResult::getInsertResults() - Devuelve resultados detallados para las inserciones exitosas
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Devuelve si la escritura fue reconocida

# MongoDB\Driver\BulkWriteCommandResult::getInsertResults

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getInsertResults — Devuelve resultados detallados para las inserciones exitosas

### Descripción

final public function MongoDB\Driver\BulkWriteCommandResult::getInsertResults(): ?MongoDB\BSON\Document

Dado que los campos `_id` para los documentos insertados son generados por la extensión, el valor de `insertedId` en cada resultado coincidirá con el valor de retorno de MongoDB\Driver\BulkWriteCommand::insertOne() para la operación de inserción correspondiente.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un documento que contiene el resultado de cada operación de inserción exitosa, o `null` si no se solicitaron resultados detallados. Las claves del documento corresponderán al índice de la operación de escritura de MongoDB\Driver\BulkWriteCommand.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Levanta una excepción MongoDB\Driver\Exception\LogicException si la escritura no ha sido reconocida.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\BulkWriteCommandResult::getInsertResults()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['verboseResults' => true]);

    $generatedId = $bulk->insertOne('db.coll', ['x' => 1]);

    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($generatedId);

    var_dump($result->getInsertResults()->toPHP());

    ?>

Resultado del ejemplo anterior es similar a:

    object(MongoDB\BSON\ObjectId)#3 (1) {
      ["oid"]=>
      string(24) "67f7ee69783dcce702097b41"
    }
    object(stdClass)#8 (1) {
      ["0"]=>
      object(stdClass)#7 (1) {
        ["insertedId"]=>
        object(MongoDB\BSON\ObjectId)#6 (1) {
          ["oid"]=>
          string(24) "67f7ee69783dcce702097b41"
        }
      }
    }

### Ver también

- MongoDB\Driver\BulkWriteCommandResult::getInsertedCount() - Devuelve el número de documentos insertados
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Devuelve si la escritura fue reconocida
- MongoDB\Driver\BulkWriteCommand::insertOne() - Añade una operación insertOne

# MongoDB\Driver\BulkWriteCommandResult::getMatchedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getMatchedCount — Devuelve el número de documentos seleccionados para actualización

### Descripción

final public function MongoDB\Driver\BulkWriteCommandResult::getMatchedCount(): int

Si la operación de actualización no produce cambios en el documento (por ejemplo, establecer el valor de un campo a su valor actual), el conteo de coincidencias puede ser mayor que el valor devuelto por MongoDB\Driver\BulkWriteCommandResult::getModifiedCount().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número total de documentos seleccionados para actualización por todas las operaciones.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Levanta una excepción MongoDB\Driver\Exception\LogicException si la escritura no ha sido reconocida.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\BulkWriteCommandResult::getMatchedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getMatchedCount());

    ?>

El ejemplo anterior mostrará:

    int(1)

### Ver también

- MongoDB\Driver\BulkWriteCommandResult::getModifiedCount() - Devuelve el número de documentos existentes que se actualizaron
- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults() - Devuelve resultados detallados para las actualizaciones exitosas
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Devuelve si la escritura fue reconocida

# MongoDB\Driver\BulkWriteCommandResult::getModifiedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getModifiedCount — Devuelve el número de documentos existentes que se actualizaron

### Descripción

final public function MongoDB\Driver\BulkWriteCommandResult::getModifiedCount(): int

Si la operación de actualización no produce cambios en el documento (por ejemplo, establecer el valor de un campo a su valor actual), el recuento de documentos modificados puede ser menor que el valor devuelto por MongoDB\Driver\BulkWriteCommandResult::getMatchedCount().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número total de documentos existentes que fueron actualizados por todas las operaciones.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Levanta una excepción MongoDB\Driver\Exception\LogicException si la escritura no ha sido reconocida.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\BulkWriteCommandResult::getModifiedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getModifiedCount());

    ?>

El ejemplo anterior mostrará:

    int(1)

### Ver también

- MongoDB\Driver\BulkWriteCommandResult::getMatchedCount() - Devuelve el número de documentos seleccionados para actualización
- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults() - Devuelve resultados detallados para las actualizaciones exitosas
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Devuelve si la escritura fue reconocida

# MongoDB\Driver\BulkWriteCommandResult::getUpdateResults

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getUpdateResults — Devuelve resultados detallados para las actualizaciones exitosas

### Descripción

final public function MongoDB\Driver\BulkWriteCommandResult::getUpdateResults(): ?MongoDB\BSON\Document

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un documento que contiene el resultado de cada operación de actualización exitosa, o `null` si no se solicitaron resultados detallados. Las claves del documento corresponderán al índice de la operación de escritura de MongoDB\Driver\BulkWriteCommand.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Levanta una excepción MongoDB\Driver\Exception\LogicException si la escritura no ha sido reconocida.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\BulkWriteCommandResult::getUpdateResults()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['verboseResults' => true]);
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getUpdateResults()->toPHP());

    ?>

Resultado del ejemplo anterior es similar a:

    object(stdClass)#16 (3) {
      ["1"]=>
      object(stdClass)#7 (2) {
        ["matchedCount"]=>
        object(MongoDB\BSON\Int64)#5 (1) {
          ["integer"]=>
          string(1) "1"
        }
        ["modifiedCount"]=>
        object(MongoDB\BSON\Int64)#6 (1) {
          ["integer"]=>
          string(1) "1"
        }
      }
      ["2"]=>
      object(stdClass)#11 (3) {
        ["matchedCount"]=>
        object(MongoDB\BSON\Int64)#8 (1) {
          ["integer"]=>
          string(1) "1"
        }
        ["modifiedCount"]=>
        object(MongoDB\BSON\Int64)#9 (1) {
          ["integer"]=>
          string(1) "0"
        }
        ["upsertedId"]=>
        object(MongoDB\BSON\ObjectId)#10 (1) {
          ["oid"]=>
          string(24) "67f7eb9b1f198bbcb880d575"
        }
      }
      ["3"]=>
      object(stdClass)#15 (3) {
        ["matchedCount"]=>
        object(MongoDB\BSON\Int64)#12 (1) {
          ["integer"]=>
          string(1) "1"
        }
        ["modifiedCount"]=>
        object(MongoDB\BSON\Int64)#13 (1) {
          ["integer"]=>
          string(1) "0"
        }
        ["upsertedId"]=>
        object(MongoDB\BSON\Int64)#14 (1) {
          ["oid"]=>
          string(24) "67f7eb9b1f198bbcb880d576"
        }
      }
    }

### Ver también

- MongoDB\Driver\BulkWriteCommandResult::getMatchedCount() - Devuelve el número de documentos seleccionados para actualización
- MongoDB\Driver\BulkWriteCommandResult::getModifiedCount() - Devuelve el número de documentos existentes que se actualizaron
- MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount() - Devuelve el número de documentos insertados o actualizados (upserted)
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Devuelve si la escritura fue reconocida

# MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount — Devuelve el número de documentos insertados o actualizados (upserted)

### Descripción

final public function MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número total de documentos insertados o actualizados (upserted) por todas las operaciones.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Levanta una excepción MongoDB\Driver\Exception\LogicException si la escritura no ha sido reconocida.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getUpsertedCount());

    ?>

El ejemplo anterior mostrará:

    int(2)

### Ver también

- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults() - Devuelve resultados detallados para las actualizaciones exitosas
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Devuelve si la escritura fue reconocida

# MongoDB\Driver\BulkWriteCommandResult::isAcknowledged

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::isAcknowledged — Devuelve si la escritura fue reconocida

### Descripción

final public function MongoDB\Driver\BulkWriteCommandResult::isAcknowledged(): bool

Si la escritura es reconocida, otros campos estarán disponibles en el objeto MongoDB\Driver\BulkWriteCommandResult.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si la escritura fue reconocida, y `false` en caso contrario.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() con preocupación de escritura reconocida

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->isAcknowledged());

    ?>

El ejemplo anterior mostrará:

    bool(true)

Ejemplo #2 MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() con preocupación de escritura no reconocida

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['ordered' => false]);
    $bulk->insertOne('db.coll', ['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(0);

    $result = $manager->executeBulkWriteCommand($bulk, ['writeConcern' => $writeConcern]);

    var_dump($result->isAcknowledged());

    ?>

El ejemplo anterior mostrará:

    bool(false)

### Ver también

- MongoDB\Driver\WriteConcern
- » Referencia de preocupación de escritura

## Tabla de contenidos

- MongoDB\Driver\BulkWriteCommandResult::getDeletedCount — Devuelve el número de documentos eliminados
- MongoDB\Driver\BulkWriteCommandResult::getDeleteResults — Devuelve resultados detallados para eliminaciones exitosas
- MongoDB\Driver\BulkWriteCommandResult::getInsertedCount — Devuelve el número de documentos insertados
- MongoDB\Driver\BulkWriteCommandResult::getInsertResults — Devuelve resultados detallados para las inserciones exitosas
- MongoDB\Driver\BulkWriteCommandResult::getMatchedCount — Devuelve el número de documentos seleccionados para actualización
- MongoDB\Driver\BulkWriteCommandResult::getModifiedCount — Devuelve el número de documentos existentes que se actualizaron
- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults — Devuelve resultados detallados para las actualizaciones exitosas
- MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount — Devuelve el número de documentos insertados o actualizados (upserted)
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged — Devuelve si la escritura fue reconocida

# Clases y funciones BSON de MongoDB

## Tabla de contenidos

- Funciones
- MongoDB\BSON\Document
- MongoDB\BSON\PackedArray
- MongoDB\BSON\Iterator
- MongoDB\BSON\Binary
- MongoDB\BSON\VectorType
- MongoDB\BSON\Decimal128
- MongoDB\BSON\Javascript
- MongoDB\BSON\MaxKey
- MongoDB\BSON\MinKey
- MongoDB\BSON\ObjectId
- MongoDB\BSON\Regex
- MongoDB\BSON\Timestamp
- MongoDB\BSON\UTCDateTime
- MongoDB\BSON\Type
- MongoDB\BSON\Persistable
- MongoDB\BSON\Serializable
- MongoDB\BSON\Unserializable
- MongoDB\BSON\BinaryInterface
- MongoDB\BSON\Decimal128Interface
- MongoDB\BSON\JavascriptInterface
- MongoDB\BSON\MaxKeyInterface
- MongoDB\BSON\MinKeyInterface
- MongoDB\BSON\ObjectIdInterface
- MongoDB\BSON\RegexInterface
- MongoDB\BSON\TimestampInterface
- MongoDB\BSON\UTCDateTimeInterface
- MongoDB\BSON\DBPointer
- MongoDB\BSON\Int64
- MongoDB\BSON\Symbol
- MongoDB\BSON\Undefined

# Funciones

# MongoDB\BSON\fromJSON

(mongodb >=1.0.0)

MongoDB\BSON\fromJSON — Devuelve la representación BSON de un valor JSON

Advertencia

Esta función ha sido DEPRECADA a partir de la versión 1.20.0 de la extensión y fue eliminada en la versión 2.0. Las aplicaciones deben usar MongoDB\BSON\Document::fromJSON() en su lugar.

### Descripción

function MongoDB\BSON\fromJSON(string `$json`): string

Convierte una cadena de » JSON extendido a su representación BSON.

### Parámetros

`json` (string)
  Valor JSON que se desea convertir.

### Valores devueltos

El documento BSON serializado como una cadena binaria.

### Errores/Excepciones

- Lanza MongoDB\Driver\Exception\UnexpectedValueException si el valor JSON no puede convertirse a BSON (por ejemplo, debido a un error de sintaxis).

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Esta función ha sido eliminada.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\BSON\fromJSON()

    <?php

    $json = '{ "_id": { "$oid": "563143b280d2387c91807965" } }';
    $bson = MongoDB\BSON\fromJSON($json);
    $value = MongoDB\BSON\toPHP($bson);
    var_dump($value);

    ?>

El ejemplo anterior mostrará:

    object(stdClass)#2 (1) {
      ["_id"]=>
      object(MongoDB\BSON\ObjectId)#1 (1) {
        ["oid"]=>
        string(24) "563143b280d2387c91807965"
      }
    }

### Ver también

- MongoDB\BSON\Document::fromJSON() - Construye una nueva instancia de documento desde un string JSON
- MongoDB\BSON\toJSON() - Devuelve la representación en JSON Extendido Legado de un valor BSON
- » JSON Extendido de MongoDB
- » BSON de MongoDB

# MongoDB\BSON\fromPHP

(mongodb >=1.0.0)

MongoDB\BSON\fromPHP — Devuelve la representación BSON de un valor PHP

Advertencia

Esta función ha sido DEPRECADA a partir de la versión 1.20.0 de la extensión y fue eliminada en la versión 2.0. Las aplicaciones deben usar MongoDB\BSON\Document::fromPHP() en su lugar.

### Descripción

function MongoDB\BSON\fromPHP(array|object `$valor`): string

Serializa un array o objeto PHP (por ejemplo, un documento) a su representación » BSON. La cadena binaria devuelta describirá un documento BSON.

### Parámetros

`valor` (array|object)
  Valor PHP que se serializará.

### Valores devueltos

El documento BSON serializado como una cadena binaria.

### Errores/Excepciones

- Lanza MongoDB\Driver\Exception\UnexpectedValueException si el valor PHP no puede convertirse a BSON. Las razones posibles incluyen, entre otras, encontrar una instancia inesperada de MongoDB\BSON\Type o que MongoDB\BSON\Serializable::bsonSerialize() no devuelva un array o un stdClass.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Esta función ha sido eliminada.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\BSON\fromPHP()

    <?php

    $bson = MongoDB\BSON\fromPHP(['foo' => 1]);
    echo bin2hex($bson), "\n";

    ?>

El ejemplo anterior mostrará:

    0e00000010666f6f000100000000

### Ver también

- MongoDB\BSON\Document::fromPHP() - Construye una nueva instancia de documento a partir de datos PHP
- MongoDB\BSON\toPHP() - Devuelve la representación en PHP de un valor BSON
- » MongoDB BSON
- Persistir datos

# MongoDB\BSON\toCanonicalExtendedJSON

(mongodb >=1.3.0)

MongoDB\BSON\toCanonicalExtendedJSON — Devuelve la representación en Canonical Extended JSON de un valor BSON

Advertencia

Esta función ha sido DEPRECADA a partir de la versión 1.20.0 de la extensión y fue eliminada en la versión 2.0. Las aplicaciones deben usar en su lugar MongoDB\BSON\Document::toCanonicalExtendedJSON().

### Descripción

function MongoDB\BSON\toCanonicalExtendedJSON(string `$bson`): string

Convierte una cadena BSON a su representación en » Canonical Extended JSON. El formato canónico prioriza la fidelidad de tipos a costa de una salida menos concisa y es más adecuado para producir salidas que puedan convertirse de vuelta a BSON sin pérdida de información de tipos (por ejemplo, los tipos numéricos permanecerán diferenciados).

### Parámetros

`bson` (string)
  Valor BSON que se convertirá.

### Valores devueltos

El valor JSON convertido.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\Exception\UnexpectedValueException si la entrada no contiene exactamente un documento BSON. Las razones posibles incluyen, pero no se limitan a, BSON inválido, datos adicionales (después de leer un documento BSON), o un error inesperado de » libbson.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Esta función ha sido eliminada.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\BSON\toCanonicalExtendedJSON()

    <?php

    $documents = [
        [ 'null' => null ],
        [ 'boolean' => true ],
        [ 'string' => 'foo' ],
        [ 'int32' => 123 ],
        [ 'int64' => 4294967295 ],
        [ 'double' => 1.0, ],
        [ 'nan' => NAN ],
        [ 'pos_inf' => INF ],
        [ 'neg_inf' => -INF ],
        [ 'array' => [ 'foo', 'bar' ]],
        [ 'document' => [ 'foo' => 'bar' ]],
        [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
        [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
        [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
        [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
        [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
        [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
        [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
        [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
        [ 'minkey' => new MongoDB\BSON\MinKey ],
        [ 'maxkey' => new MongoDB\BSON\MaxKey ],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\fromPHP($document);
        echo MongoDB\BSON\toCanonicalExtendedJSON($bson), "\n";
    }

    ?>

El ejemplo anterior mostrará:

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : { "$numberInt" : "123" } }
    { "int64" : { "$numberLong" : "4294967295"} }
    { "double" : { "$numberDouble" : "1.0" } }
    { "nan" : { "$numberDouble" : "NaN" } }
    { "pos_inf" : { "$numberDouble" : "Infinity" } }
    { "neg_inf" : { "$numberDouble" : "-Infinity" } }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
    { "date" : { "$date" : { "$numberLong" : "1445990400000" } } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : { "$numberInt" : "1" } } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Ver también

- MongoDB\BSON\Document::fromJSON() - Construye una nueva instancia de documento desde un string JSON
- MongoDB\BSON\Document::toCanonicalExtendedJSON() - Devuelve la representación Canónica Extendida JSON del documento BSON
- MongoDB\BSON\fromJSON() - Devuelve la representación BSON de un valor JSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Devuelve la representación en Relaxed Extended JSON de un valor BSON
- » Especificación de JSON Extendido
- » MongoDB BSON

# MongoDB\BSON\toJSON

(mongodb >=1.0.0)

MongoDB\BSON\toJSON — Devuelve la representación en JSON Extendido Legado de un valor BSON

Advertencia

Esta función ha sido DEPRECADA a partir de la versión 1.20.0 de la extensión y fue eliminada en la versión 2.0. Las aplicaciones deben usar en su lugar MongoDB\BSON\Document::toCanonicalExtendedJSON() o MongoDB\BSON\Document::toRelaxedExtendedJSON().

### Descripción

function MongoDB\BSON\toJSON(string `$bson`): string

Convierte una cadena BSON a su representación en » JSON Extendido Legado.

> Nota: Existen varios formatos JSON para representar BSON. Esta función implementa el "modo estricto" definido en » JSON Extendido de MongoDB, que ha sido reemplazado por los formatos canónico y relajado definidos en la » Especificación de JSON Extendido e implementados por MongoDB\BSON\toCanonicalExtendedJSON() y MongoDB\BSON\toRelaxedExtendedJSON(), respectivamente.

Advertencia

» JSON no admite `NAN` ni `INF`, y el formato de JSON Extendido Legado de MongoDB no define una representación alternativa para estos valores (» libbson generará literales `nan` e `inf`, que pueden no ser analizados como JSON válido). Si está trabajando con BSON que puede contener números no finitos, utilice MongoDB\BSON\toCanonicalExtendedJSON() o MongoDB\BSON\toRelaxedExtendedJSON().

### Parámetros

`bson` (string)
  Valor BSON a convertir.

### Valores devueltos

El valor JSON convertido.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\Exception\UnexpectedValueException si la entrada no contiene exactamente un documento BSON. Las razones posibles incluyen, pero no se limitan a, BSON inválido, datos adicionales (después de leer un documento BSON), o un error inesperado de » libbson.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Esta función ha sido eliminada.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\BSON\toJSON()

    <?php

    $documents = [
        [ 'null' => null ],
        [ 'boolean' => true ],
        [ 'string' => 'foo' ],
        [ 'int32' => 123 ],
        [ 'int64' => 4294967295 ],
        [ 'double' => 1.0, ],
        [ 'nan' => NAN ],
        [ 'pos_inf' => INF ],
        [ 'neg_inf' => -INF ],
        [ 'array' => [ 'foo', 'bar' ]],
        [ 'document' => [ 'foo' => 'bar' ]],
        [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
        [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
        [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
        [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
        [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
        [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
        [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
        [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
        [ 'minkey' => new MongoDB\BSON\MinKey ],
        [ 'maxkey' => new MongoDB\BSON\MaxKey ],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\fromPHP($document);
        echo MongoDB\BSON\toJSON($bson), "\n";
    }

    ?>

El ejemplo anterior mostrará:

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : 123 }
    { "int64" : 4294967295 }
    { "double" : 1.0 }
    { "nan" : nan }
    { "pos_inf" : inf }
    { "neg_inf" : -inf }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : "Zm9v", "$type" : "00" } }
    { "date" : { "$date" : 1445990400000 } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regex" : "pattern", "$options" : "i" } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : 1 } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Ver también

- MongoDB\BSON\fromJSON() - Devuelve la representación BSON de un valor JSON
- MongoDB\BSON\toCanonicalExtendedJSON() - Devuelve la representación en Canonical Extended JSON de un valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Devuelve la representación en Relaxed Extended JSON de un valor BSON
- » JSON Extendido de MongoDB
- » BSON de MongoDB

# MongoDB\BSON\toPHP

(mongodb >=1.0.0)

MongoDB\BSON\toPHP — Devuelve la representación en PHP de un valor BSON

Advertencia

Esta función ha sido DEPRECADA a partir de la versión 1.20.0 de la extensión y fue eliminada en la versión 2.0. Las aplicaciones deben usar MongoDB\BSON\Document::toPHP() en su lugar.

### Descripción

function MongoDB\BSON\toPHP(string `$bson`, array `$typeMap` = array()): array|object

Deserializa un documento BSON (es decir, una cadena binaria) a su representación en PHP. El parámetro `typeMap` puede usarse para controlar los tipos de PHP utilizados para convertir matrices y documentos BSON (tanto raíz como incrustados).

Advertencia

Los documentos BSON pueden contener técnicamente claves duplicadas ya que los documentos se almacenan como una lista de pares clave-valor; sin embargo, las aplicaciones deben abstenerse de generar documentos con claves duplicadas ya que el comportamiento del servidor y del controlador puede ser indefinido. Dado que los objetos y arrays de PHP no pueden tener claves duplicadas, los datos también podrían perderse al decodificar un documento BSON con claves duplicadas.

### Parámetros

`bson` (string)
  Valor BSON a deserializar.
`typeMap` (array)
  Configuración del mapa de tipos.

### Valores devueltos

El valor en PHP deserializado.

### Errores/Excepciones

- Lanza MongoDB\Driver\Exception\InvalidArgumentException si una clase en el mapa de tipos no puede ser instanciada o no implementa MongoDB\BSON\Unserializable.
- Lanza una excepción MongoDB\Driver\Exception\UnexpectedValueException si la entrada no contiene exactamente un documento BSON. Las razones posibles incluyen, pero no se limitan a, BSON inválido, datos adicionales (después de leer un documento BSON), o un error inesperado de » libbson.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Esta función ha sido eliminada.
PECL mongodb 1.4.0 | Si la entrada contiene un tipo BSON obsoleto no admitido, la extensión ya no registrará una advertencia en el registro de depuración, sino que creará un objeto que represente este tipo.
PECL mongodb 1.3.2 | Ya no se lanza MongoDB\Driver\Exception\UnexpectedValueException si la entrada contiene un tipo BSON obsoleto no admitido. Tales tipos serán ignorados (como lo eran en versiones anteriores a 1.3.0), aunque la extensión registrará ahora una advertencia en el registro de depuración (ver: mongodb.debug).
PECL mongodb 1.3.0 | Se lanza MongoDB\Driver\Exception\UnexpectedValueException si la entrada contiene un tipo BSON obsoleto no admitido. Anteriormente, tales tipos eran ignorados.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\BSON\toPHP()

    <?php

    $bson = hex2bin('0e00000010666f6f000100000000');
    $value = MongoDB\BSON\toPHP($bson);
    var_dump($value);

    ?>

El ejemplo anterior mostrará:

    object(stdClass)#1 (1) {
      ["foo"]=>
      int(1)
    }

### Ver también

- MongoDB\BSON\Document::toPHP() - Devuelve la representación PHP del documento BSON
- MongoDB\BSON\fromPHP() - Devuelve la representación BSON de un valor PHP
- » MongoDB BSON
- Persistir datos

# MongoDB\BSON\toRelaxedExtendedJSON

(mongodb >=1.3.0)

MongoDB\BSON\toRelaxedExtendedJSON — Devuelve la representación en Relaxed Extended JSON de un valor BSON

Advertencia

Esta función ha sido DEPRECADA a partir de la versión 1.20.0 de la extensión y fue eliminada en la versión 2.0. Las aplicaciones deben usar MongoDB\BSON\Document::toRelaxedExtendedJSON() en su lugar.

### Descripción

function MongoDB\BSON\toRelaxedExtendedJSON(string `$bson`): string

Convierte una cadena BSON a su representación en » Relaxed Extended JSON. El formato relajado prefiere el uso de primitivas de tipo JSON a costa de la fidelidad de tipos y es más adecuado para producir salidas que puedan ser consumidas fácilmente por APIs web y humanos.

### Parámetros

`bson` (string)
  Valor BSON que se convertirá.

### Valores devueltos

El valor JSON convertido.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\Exception\UnexpectedValueException si la entrada no contiene exactamente un documento BSON. Las razones posibles incluyen, pero no se limitan a, BSON inválido, datos adicionales (después de leer un documento BSON), o un error inesperado de » libbson.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Esta función ha sido eliminada.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\BSON\toRelaxedExtendedJSON()

    <?php

    $documents = [
        [ 'null' => null ],
        [ 'boolean' => true ],
        [ 'string' => 'foo' ],
        [ 'int32' => 123 ],
        [ 'int64' => 4294967295 ],
        [ 'double' => 1.0, ],
        [ 'nan' => NAN ],
        [ 'pos_inf' => INF ],
        [ 'neg_inf' => -INF ],
        [ 'array' => [ 'foo', 'bar' ]],
        [ 'document' => [ 'foo' => 'bar' ]],
        [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
        [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
        [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
        [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
        [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
        [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
        [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
        [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
        [ 'minkey' => new MongoDB\BSON\MinKey ],
        [ 'maxkey' => new MongoDB\BSON\MaxKey ],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\fromPHP($document);
        echo MongoDB\BSON\toRelaxedExtendedJSON($bson), "\n";
    }

    ?>

El ejemplo anterior mostrará:

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : 123 }
    { "int64" : 4294967295 }
    { "double" : 1.0 }
    { "nan" : { "$numberDouble" : "NaN" } }
    { "pos_inf" : { "$numberDouble" : "Infinity" } }
    { "neg_inf" : { "$numberDouble" : "-Infinity" } }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
    { "date" : { "$date" : "2015-10-28T00:00:00Z" } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : 1 } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Ver también

- MongoDB\BSON\Document::fromJSON() - Construye una nueva instancia de documento desde un string JSON
- MongoDB\BSON\Document::toRelaxedExtendedJSON() - Devuelve la representación relajada extendida JSON del documento BSON
- MongoDB\BSON\fromJSON() - Devuelve la representación BSON de un valor JSON
- MongoDB\BSON\toCanonicalExtendedJSON() - Devuelve la representación en Canonical Extended JSON de un valor BSON
- » JSON Extendido
- » MongoDB BSON

## Tabla de contenidos

- MongoDB\BSON\fromJSON — Devuelve la representación BSON de un valor JSON
- MongoDB\BSON\fromPHP — Devuelve la representación BSON de un valor PHP
- MongoDB\BSON\toCanonicalExtendedJSON — Devuelve la representación en Canonical Extended JSON de un valor BSON
- MongoDB\BSON\toJSON — Devuelve la representación en JSON Extendido Legado de un valor BSON
- MongoDB\BSON\toPHP — Devuelve la representación en PHP de un valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON — Devuelve la representación en Relaxed Extended JSON de un valor BSON

# la clase MongoDB\BSON\Document

(mongodb >=1.16.0)

## Introducción

Representa un documento BSON. Esta clase se utiliza al leer datos como BSON sin tratar y no puede ser modificada.

## Sinopsis de la Clase

final class MongoDB\BSON\Document implements MongoDB\BSON\Type, ArrayAccess, IteratorAggregate {
/* Métodos */
final private function __construct()
final static public function fromBSON(string `$bson`): MongoDB\BSON\Document
final static public function fromJSON(string `$json`): MongoDB\BSON\Document
final static public function fromPHP(object|array `$value`): MongoDB\BSON\Document
final public function get(string `$key`): mixed
final public function getIterator(): MongoDB\BSON\Iterator
final public function has(string `$key`): bool
final public function offsetExists(mixed `$key`): bool
final public function offsetGet(mixed `$key`): mixed
final public function offsetSet(mixed `$key`, mixed `$value`): void
final public function offsetUnset(mixed `$key`): void
final public function toCanonicalExtendedJSON(): string
final public function toPHP(?array `$typeMap` = `null`): array|object
final public function toRelaxedExtendedJSON(): string
final public function __toString(): string
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Esta clase ya no implementa la interfaz Serializable.
PECL mongodb 1.17.0 | Implementa MongoDB\BSON\Type.

# MongoDB\BSON\Document::__construct

(mongodb >=1.16.0)

MongoDB\BSON\Document::__construct — Construye un nuevo documento BSON (no utilizado)

### Descripción

final private function MongoDB\BSON\Document::__construct()

Los objetos MongoDB\BSON\Document son creados a través de métodos de fábrica estáticos y no pueden ser instanciados directamente.

### Parámetros

Esta función no contiene ningún parámetro.

### Ver también

- MongoDB\BSON\Document::fromPHP() - Construye una nueva instancia de documento a partir de datos PHP
- MongoDB\BSON\Document::fromBSON() - Construye una nueva instancia de documento a partir de un string BSON
- MongoDB\BSON\Document::fromJSON() - Construye una nueva instancia de documento desde un string JSON
- » Tipos BSON

# MongoDB\BSON\Document::fromBSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::fromBSON — Construye una nueva instancia de documento a partir de un string BSON

### Descripción

final static public function MongoDB\BSON\Document::fromBSON(string `$bson`): MongoDB\BSON\Document

### Parámetros

`bson` (string)
  Un string que contiene un documento en formato BSON.

### Valores devueltos

Devuelve una nueva instancia de MongoDB\BSON\Document.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una MongoDB\Driver\Exception\UnexpectedValueException si `bson` es un string inválido o contiene más de un documento

### Ver también

- MongoDB\BSON\Document::fromPHP() - Construye una nueva instancia de documento a partir de datos PHP
- MongoDB\BSON\Document::fromJSON() - Construye una nueva instancia de documento desde un string JSON
- » BSON Types

# MongoDB\BSON\Document::fromJSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::fromJSON — Construye una nueva instancia de documento desde un string JSON

### Descripción

final static public function MongoDB\BSON\Document::fromJSON(string `$json`): MongoDB\BSON\Document

Convierte un string » JSON extendido a su representación BSON.

### Parámetros

`json` (string)
  El valor JSON a convertir.

### Valores devueltos

Retorna una nueva instancia de MongoDB\BSON\Document.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza MongoDB\Driver\Exception\UnexpectedValueException si el valor JSON no puede ser convertido a un documento BSON (por ejemplo, debido a un error de sintaxis).

### Ver también

- MongoDB\BSON\Document::fromPHP() - Construye una nueva instancia de documento a partir de datos PHP
- MongoDB\BSON\Document::fromBSON() - Construye una nueva instancia de documento a partir de un string BSON
- » MongoDB JSON extendido
- » Tipo BSON

# MongoDB\BSON\Document::fromPHP

(mongodb >=1.16.0)

MongoDB\BSON\Document::fromPHP — Construye una nueva instancia de documento a partir de datos PHP

### Descripción

final static public function MongoDB\BSON\Document::fromPHP(object|array `$value`): MongoDB\BSON\Document

### Parámetros

`value` (object|array)
  Un objeto PHP o un array que contiene el documento. Cuando se pasa un array con claves numéricas, los valores numéricos se convierten en strings y se utilizan como claves del documento.

### Valores devueltos

Devuelve una nueva instancia de MongoDB\BSON\Document.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\BSON\Document::fromBSON() - Construye una nueva instancia de documento a partir de un string BSON
- MongoDB\BSON\Document::fromJSON() - Construye una nueva instancia de documento desde un string JSON
- » Tipos BSON

# MongoDB\BSON\Document::get

(mongodb >=1.16.0)

MongoDB\BSON\Document::get — Devuelve el valor de una clave en un documento

### Descripción

final public function MongoDB\BSON\Document::get(string `$key`): mixed

### Parámetros

`key` (string)
  La clave a recuperar en el documento.

### Valores devueltos

Devuelve el valor asociado a la clave dada. Si la clave no está presente en el documento, se lanza una excepción.

> Nota: Cuando se encuentra un valor codificado como un entero de 64 bits en el documento BSON, el valor de retorno de este método será una instancia de MongoDB\BSON\Int64.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una MongoDB\Driver\Exception\RuntimeException si la clave no está presente en el documento.

### Ver también

- MongoDB\BSON\Document::has() - Indica si una clave está presente en el documento
- » Tipos BSON

# MongoDB\BSON\Document::getIterator

(mongodb >=1.16.0)

MongoDB\BSON\Document::getIterator — Devuelve un iterador para el documento BSON

### Descripción

final public function MongoDB\BSON\Document::getIterator(): MongoDB\BSON\Iterator

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una instancia de MongoDB\BSON\Iterator que puede ser utilizada para iterar sobre todas las claves del documento.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una MongoDB\Driver\Exception\UnexpectedValueException si el iterador BSON no puede ser inicializado.

### Ver también

- » Tipos BSON

# MongoDB\BSON\Document::has

(mongodb >=1.16.0)

MongoDB\BSON\Document::has — Indica si una clave está presente en el documento

### Descripción

final public function MongoDB\BSON\Document::has(string `$key`): bool

### Parámetros

`key` (string)
  La clave a buscar en el documento.

### Valores devueltos

Devuelve `true` si la clave está presente en el documento, de lo contrario `false`.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\BSON\Document::get() - Devuelve el valor de una clave en un documento
- » Tipos BSON

# MongoDB\BSON\Document::offsetExists

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetExists — Indica si una clave está presente en el documento

### Descripción

final public function MongoDB\BSON\Document::offsetExists(mixed `$key`): bool

### Parámetros

`key`
  La clave a buscar en el documento.

### Valores devueltos

Devuelve `true` si la clave está presente en el documento, de lo contrario `false`.

### Ver también

- ArrayAccess::offsetExists() - Comprobar si existe un índice
- MongoDB\BSON\Document::has() - Indica si una clave está presente en el documento

# MongoDB\BSON\Document::offsetGet

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetGet — Devuelve el valor de una clave en un documento

### Descripción

final public function MongoDB\BSON\Document::offsetGet(mixed `$key`): mixed

### Parámetros

`key`
  La clave a recuperar en el documento.

### Valores devueltos

Devuelve el valor asociado a la clave dada. Si la clave no está presente en el documento, se lanza una excepción.

> Nota: Cuando se encuentra un valor codificado como un entero de 64 bits en el documento BSON, el valor de retorno de este método será una instancia de MongoDB\BSON\Int64.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una MongoDB\Driver\Exception\RuntimeException si la clave no está presente en el documento.

### Ver también

- ArrayAccess::offsetGet() - Offset para recuperar
- MongoDB\BSON\Document::get() - Devuelve el valor de una clave en un documento

# MongoDB\BSON\Document::offsetSet

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetSet — Implementación de ArrayAccess

### Descripción

final public function MongoDB\BSON\Document::offsetSet(mixed `$key`, mixed `$value`): void

Cambia el valor en la `key` especificada por `value`.

### Parámetros

`key`
  El índice a definir.
`value`
  El nuevo valor para la `key`.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Siempre lanza una MongoDB\Driver\Exception\LogicException.

# MongoDB\BSON\Document::offsetUnset

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetUnset — Implementación de ArrayAccess

### Descripción

final public function MongoDB\BSON\Document::offsetUnset(mixed `$key`): void

Elimina el valor en el índice especificado.

### Parámetros

`key`
  El índice a eliminar.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Siempre lanza una MongoDB\Driver\Exception\LogicException.

# MongoDB\BSON\Document::toCanonicalExtendedJSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::toCanonicalExtendedJSON — Devuelve la representación Canónica Extendida JSON del documento BSON

### Descripción

final public function MongoDB\BSON\Document::toCanonicalExtendedJSON(): string

Convierte el documento BSON en su representación » Canónica Extendida JSON. El formato canónico prefiere la fidelidad de los tipos a la salida concisa y es el más adecuado para producir una salida que puede ser convertida en BSON sin pérdida de información de tipo (por ejemplo, los tipos numéricos permanecerán diferenciados).

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un string que contiene la » representación Canonical Extended JSON del documento BSON.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\BSON\Document::toCanonicalExtendedJSON()

    <?php

    $documents = [
        [ 'null' => null ],
        [ 'boolean' => true ],
        [ 'string' => 'foo' ],
        [ 'int32' => 123 ],
        [ 'int64' => 4294967295 ],
        [ 'double' => 1.0 ],
        [ 'nan' => NAN ],
        [ 'pos_inf' => INF ],
        [ 'neg_inf' => -INF ],
        [ 'array' => [ 'foo', 'bar' ]],
        [ 'document' => [ 'foo' => 'bar' ]],
        [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
        [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
        [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
        [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
        [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
        [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
        [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
        [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
        [ 'minkey' => new MongoDB\BSON\MinKey ],
        [ 'maxkey' => new MongoDB\BSON\MaxKey ],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\Document::fromPHP($document);
        echo $bson->toCanonicalExtendedJSON(), "\n";
    }

    ?>

El ejemplo anterior mostrará:

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : { "$numberInt" : "123" } }
    { "int64" : { "$numberLong" : "4294967295"} }
    { "double" : { "$numberDouble" : "1.0" } }
    { "nan" : { "$numberDouble" : "NaN" } }
    { "pos_inf" : { "$numberDouble" : "Infinity" } }
    { "neg_inf" : { "$numberDouble" : "-Infinity" } }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
    { "date" : { "$date" : { "$numberLong" : "1445990400000" } } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : { "$numberInt" : "1" } } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Ver también

- MongoDB\BSON\Document::fromJSON() - Construye una nueva instancia de documento desde un string JSON
- MongoDB\BSON\Document::toRelaxedExtendedJSON() - Devuelve la representación relajada extendida JSON del documento BSON
- MongoDB\BSON\toCanonicalExtendedJSON() - Devuelve la representación en Canonical Extended JSON de un valor BSON
- » Canónica Extendida JSON
- » Tipos BSON

# MongoDB\BSON\Document::toPHP

(mongodb >=1.16.0)

MongoDB\BSON\Document::toPHP — Devuelve la representación PHP del documento BSON

### Descripción

final public function MongoDB\BSON\Document::toPHP(?array `$typeMap` = `null`): array|object

Deserializa el documento BSON en su representación PHP. El parámetro `typeMap` puede ser utilizado para controlar los tipos PHP utilizados para convertir los arrays y documentos BSON (raíz e integrados).

Advertencia

Los documentos BSON pueden contener técnicamente claves duplicadas ya que los documentos se almacenan como una lista de pares clave-valor; sin embargo, las aplicaciones deben abstenerse de generar documentos con claves duplicadas ya que el comportamiento del servidor y del controlador puede ser indefinido. Dado que los objetos y arrays de PHP no pueden tener claves duplicadas, los datos también podrían perderse al decodificar un documento BSON con claves duplicadas.

### Parámetros

`typeMap` (array)
  Configuración del mapa de tipos.

### Valores devueltos

El valor decodificado PHP.

> Nota: Cuando se encuentra un valor codificado como un entero de 64 bits en el documento BSON, el valor de retorno de este método será una instancia de MongoDB\BSON\Int64.

### Errores/Excepciones

- Lanza una MongoDB\Driver\Exception\InvalidArgumentException si un tipo en el mapa de tipos no puede ser instanciado o no implementa MongoDB\BSON\Unserializable.

### Ver también

- MongoDB\BSON\toPHP() - Devuelve la representación en PHP de un valor BSON
- » Tipos BSON

# MongoDB\BSON\Document::toRelaxedExtendedJSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::toRelaxedExtendedJSON — Devuelve la representación relajada extendida JSON del documento BSON

### Descripción

final public function MongoDB\BSON\Document::toRelaxedExtendedJSON(): string

Convierte el documento BSON en su representación » Relajada Extendida JSON. El formato relajado prefiere el uso de las primitivas de tipo JSON en detrimento de la fidelidad de los tipos y es el más adecuado para producir una salida que puede ser fácilmente consumida por las API web y los humanos.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un string que contiene la » representación Relaxed Extended JSON del documento BSON.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\BSON\Document::toRelaxedExtendedJSON()

    <?php

    $documents = [
        [ 'null' => null ],
        [ 'boolean' => true ],
        [ 'string' => 'foo' ],
        [ 'int32' => 123 ],
        [ 'int64' => 4294967295 ],
        [ 'double' => 1.0 ],
        [ 'nan' => NAN ],
        [ 'pos_inf' => INF ],
        [ 'neg_inf' => -INF ],
        [ 'array' => [ 'foo', 'bar' ]],
        [ 'document' => [ 'foo' => 'bar' ]],
        [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
        [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
        [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
        [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
        [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
        [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
        [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
        [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
        [ 'minkey' => new MongoDB\BSON\MinKey ],
        [ 'maxkey' => new MongoDB\BSON\MaxKey ],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\Document::fromPHP($document);
        echo $bson->toRelaxedExtendedJSON(), "\n";
    }

    ?>

El ejemplo anterior mostrará:

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : 123 }
    { "int64" : 4294967295 }
    { "double" : 1.0 }
    { "nan" : { "$numberDouble" : "NaN" } }
    { "pos_inf" : { "$numberDouble" : "Infinity" } }
    { "neg_inf" : { "$numberDouble" : "-Infinity" } }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
    { "date" : { "$date" : "2015-10-28T00:00:00Z" } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : 1 } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Ver también

- MongoDB\BSON\Document::fromJSON() - Construye una nueva instancia de documento desde un string JSON
- MongoDB\BSON\Document::toCanonicalExtendedJSON() - Devuelve la representación Canónica Extendida JSON del documento BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Devuelve la representación en Relaxed Extended JSON de un valor BSON
- » Especificación JSON extendida
- » Tipos BSON

# MongoDB\BSON\Document::__toString

(mongodb >=1.16.0)

MongoDB\BSON\Document::__toString — Devuelve la representación en string de este documento BSON

### Descripción

final public function MongoDB\BSON\Document::__toString(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la representación en string de este documento BSON.

### Ver también

- » Tipos BSON

## Tabla de contenidos

- MongoDB\BSON\Document::__construct — Construye un nuevo documento BSON (no utilizado)
- MongoDB\BSON\Document::fromBSON — Construye una nueva instancia de documento a partir de un string BSON
- MongoDB\BSON\Document::fromJSON — Construye una nueva instancia de documento desde un string JSON
- MongoDB\BSON\Document::fromPHP — Construye una nueva instancia de documento a partir de datos PHP
- MongoDB\BSON\Document::get — Devuelve el valor de una clave en un documento
- MongoDB\BSON\Document::getIterator — Devuelve un iterador para el documento BSON
- MongoDB\BSON\Document::has — Indica si una clave está presente en el documento
- MongoDB\BSON\Document::offsetExists — Indica si una clave está presente en el documento
- MongoDB\BSON\Document::offsetGet — Devuelve el valor de una clave en un documento
- MongoDB\BSON\Document::offsetSet — Implementación de ArrayAccess
- MongoDB\BSON\Document::offsetUnset — Implementación de ArrayAccess
- MongoDB\BSON\Document::toCanonicalExtendedJSON — Devuelve la representación Canónica Extendida JSON del documento BSON
- MongoDB\BSON\Document::toPHP — Devuelve la representación PHP del documento BSON
- MongoDB\BSON\Document::toRelaxedExtendedJSON — Devuelve la representación relajada extendida JSON del documento BSON
- MongoDB\BSON\Document::__toString — Devuelve la representación en string de este documento BSON

# La clase MongoDB\BSON\PackedArray

(mongodb >=1.16.0)

## Introducción

Representa un array BSON. Esta clase se utiliza al leer datos como BSON sin tratar y no puede ser modificada.

## Sinopsis de la Clase

final class MongoDB\BSON\PackedArray implements MongoDB\BSON\Type, ArrayAccess, IteratorAggregate {
/* Métodos */
final private function __construct()
final static public function fromJSON(string `$json`): MongoDB\BSON\PackedArray
final static public function fromPHP(array `$value`): MongoDB\BSON\PackedArray
final public function get(int `$key`): mixed
final public function getIterator(): MongoDB\BSON\Iterator
final public function has(int `$index`): bool
final public function offsetExists(mixed `$key`): bool
final public function offsetGet(mixed `$key`): mixed
final public function offsetSet(mixed `$key`, mixed `$value`): void
final public function offsetUnset(mixed `$key`): void
final public function toCanonicalExtendedJSON(): string
final public function toPHP(?array `$typeMap` = `null`): array|object
final public function toRelaxedExtendedJSON(): string
final public function __toString(): string
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Esta clase ya no implementa la interfaz Serializable.
PECL mongodb 1.17.0 | Implementa MongoDB\BSON\Type.
PECL mongodb 1.17.0 | MongoDB\BSON\PackedArray no puede ser serializado en contextos donde se espera un documento BSON. En versiones anteriores, el array BSON habría sido convertido en documento.

# MongoDB\BSON\PackedArray::__construct

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::__construct — Construye un nuevo array BSON (no utilizado)

### Descripción

final private function MongoDB\BSON\PackedArray::__construct()

Los objetos MongoDB\BSON\PackedArray se crean con métodos de fábrica estáticos y no pueden ser instanciados directamente.

### Parámetros

Esta función no contiene ningún parámetro.

### Ver también

- MongoDB\BSON\PackedArray::fromPHP() - Construye una nueva instancia de array BSON a partir de datos PHP
- » Tipos BSON

# MongoDB\BSON\PackedArray::fromJSON

(mongodb >=1.20.0)

MongoDB\BSON\PackedArray::fromJSON — Construye una nueva instancia de array BSON a partir de un string JSON

### Descripción

final static public function MongoDB\BSON\PackedArray::fromJSON(string `$json`): MongoDB\BSON\PackedArray

Convierte un string » JSON extendido en su representación BSON.

### Parámetros

`json` (string)
  El valor JSON a convertir.

### Valores devueltos

Devuelve una nueva instancia de MongoDB\BSON\PackedArray.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una MongoDB\Driver\Exception\UnexpectedValueException si el valor JSON no puede ser convertido en un array BSON (por ejemplo, debido a un error de sintaxis).

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\BSON\PackedArray::fromJSON()

    <?php

    $json = '[ "foo", { "$numberInt" : "123" }, { "$numberLong" : "4294967295" }, { "$oid" : "56315a7c6118fd1b920270b1" } ]';
    $packedArray = MongoDB\BSON\PackedArray::fromJSON($json);
    var_dump($packedArray);

    ?>

El ejemplo anterior mostrará:

    object(MongoDB\BSON\PackedArray)#1 (2) {
      ["data"]=>
      string(68) "MQAAAAIwAAQAAABmb28AEDEAewAAABIyAP////8AAAAABzMAVjFafGEY/RuSAnCxAA=="
      ["value"]=>
      array(4) {
        [0]=>
        string(3) "foo"
        [1]=>
        int(123)
        [2]=>
        int(4294967295)
        [3]=>
        object(MongoDB\BSON\ObjectId)#2 (1) {
          ["oid"]=>
          string(24) "56315a7c6118fd1b920270b1"
        }
      }
    }

### Ver también

- MongoDB\BSON\PackedArray::fromPHP() - Construye una nueva instancia de array BSON a partir de datos PHP
- » Json extendido de MongoDB
- » Tipos BSON

# MongoDB\BSON\PackedArray::fromPHP

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::fromPHP — Construye una nueva instancia de array BSON a partir de datos PHP

### Descripción

final static public function MongoDB\BSON\PackedArray::fromPHP(array `$value`): MongoDB\BSON\PackedArray

### Parámetros

`value` (array)
  El array PHP a convertir en array BSON. El array debe ser una lista (es decir, tener claves numéricas secuenciales comenzando por `0`).

### Valores devueltos

Devuelve una nueva instancia de MongoDB\BSON\PackedArray.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una MongoDB\Driver\Exception\InvalidArgumentException si el array dado no es una lista (por ejemplo, tiene secuencias numéricas comenzando por `0`).

### Ver también

- » Tipos BSON

# MongoDB\BSON\PackedArray::get

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::get — Devuelve el valor de un índice del array

### Descripción

final public function MongoDB\BSON\PackedArray::get(int `$key`): mixed

### Parámetros

`key` (int)
  El índice a recuperar del array.

### Valores devueltos

Devuelve el valor asociado al índice dado. Si el índice no está presente en el array, se lanza una excepción.

> Nota: Cuando se encuentra un valor codificado como un entero de 64 bits en el array BSON, el valor de retorno de este método será una instancia de MongoDB\BSON\Int64.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una MongoDB\Driver\Exception\RuntimeException si el índice no está presente en el array.

### Ver también

- MongoDB\BSON\PackedArray::has() - Indica si un índice está presente en el array
- » Tipos BSON

# MongoDB\BSON\PackedArray::getIterator

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::getIterator — Devuelve el iterador para el array BSON

### Descripción

final public function MongoDB\BSON\PackedArray::getIterator(): MongoDB\BSON\Iterator

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una instancia de MongoDB\BSON\Iterator que puede ser utilizada para iterar sobre todos los índices del array.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una MongoDB\Driver\Exception\UnexpectedValueException si el iterador BSON no puede ser instanciado.

### Ver también

- » Tipos BSON

# MongoDB\BSON\PackedArray::has

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::has — Indica si un índice está presente en el array

### Descripción

final public function MongoDB\BSON\PackedArray::has(int `$index`): bool

### Parámetros

`index` (int)
  El índice a buscar en el array.

### Valores devueltos

Devuelve `true` si el índice está presente en el array, de lo contrario `false`.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\BSON\PackedArray::get() - Devuelve el valor de un índice del array
- » Tipos BSON

# MongoDB\BSON\PackedArray::offsetExists

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetExists — Indica si un índice está presente en el array

### Descripción

final public function MongoDB\BSON\PackedArray::offsetExists(mixed `$key`): bool

### Parámetros

`key`
  El índice a buscar en el array.

### Valores devueltos

Devuelve `true` si el índice está presente en el array, de lo contrario `false`.

### Ver también

- ArrayAccess::offsetExists() - Comprobar si existe un índice
- MongoDB\BSON\PackedArray::has() - Indica si un índice está presente en el array

# MongoDB\BSON\PackedArray::offsetGet

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetGet — Devuelve el valor de un índice del array

### Descripción

final public function MongoDB\BSON\PackedArray::offsetGet(mixed `$key`): mixed

### Parámetros

`key`
  El índice a recuperar del array. Solo int es soportado.

### Valores devueltos

Devuelve el valor asociado al índice dado. Si el índice no está presente en el array, se lanza una excepción.

> Nota: Cuando se encuentra un valor codificado como un entero de 64 bits en el array BSON, el valor de retorno de este método será una instancia de MongoDB\BSON\Int64.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una MongoDB\Driver\Exception\RuntimeException si el índice no está presente en el array.

### Ver también

- ArrayAccess::offsetGet() - Offset para recuperar
- MongoDB\BSON\PackedArray::get() - Devuelve el valor de un índice del array

# MongoDB\BSON\PackedArray::offsetSet

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetSet — Implementación de ArrayAccess

### Descripción

final public function MongoDB\BSON\PackedArray::offsetSet(mixed `$key`, mixed `$value`): void

Cambia el valor de `key` a `value`.

### Parámetros

`key`
  El índice a modificar.
`value`
  El nuevo valor de `key`.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Siempre lanza una MongoDB\Driver\Exception\LogicException.

# MongoDB\BSON\PackedArray::offsetUnset

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetUnset — Implementación de ArrayAccess

### Descripción

final public function MongoDB\BSON\PackedArray::offsetUnset(mixed `$key`): void

Elimina el valor en el índice dado.

### Parámetros

`key`
  El valor a eliminar.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Siempre lanza una MongoDB\Driver\Exception\LogicException.

# MongoDB\BSON\PackedArray::toCanonicalExtendedJSON

(mongodb >=1.20.0)

MongoDB\BSON\PackedArray::toCanonicalExtendedJSON — Devuelve la representación JSON extendida canónica del array BSON

### Descripción

final public function MongoDB\BSON\PackedArray::toCanonicalExtendedJSON(): string

Convierte el array BSON en su representación » JSON extendida canónica. El formato canónico privilegia la fidelidad de los tipos en detrimento de la concisión de la salida y es el más adecuado para producir una salida que puede ser convertida en BSON sin pérdida de información de tipo (por ejemplo, los tipos numéricos permanecerán diferenciados).

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un string que contiene la representación » JSON extendida canónica del array BSON.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\BSON\PackedArray::toCanonicalExtendedJSON()

    <?php

    $array = [
        'foo',
        123,
        4294967295,
        new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1'),
    ];

    $packedArray = MongoDB\BSON\PackedArray::fromPHP($array);
    echo $packedArray->toCanonicalExtendedJSON(), "\n";

    ?>

El ejemplo anterior mostrará:

    [ "foo", { "$numberInt" : "123" }, { "$numberLong" : "4294967295" }, { "$oid" : "56315a7c6118fd1b920270b1" } ]

### Ver también

- MongoDB\BSON\PackedArray::fromJSON() - Construye una nueva instancia de array BSON a partir de un string JSON
- MongoDB\BSON\PackedArray::toRelaxedExtendedJSON() - Devuelve la representación JSON extendida relajada del array BSON
- MongoDB\BSON\toCanonicalExtendedJSON() - Devuelve la representación en Canonical Extended JSON de un valor BSON
- » Especificación del JSON extendido
- » Tipos BSON

# MongoDB\BSON\PackedArray::toPHP

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::toPHP — Devuelve la representación PHP del array BSON

### Descripción

final public function MongoDB\BSON\PackedArray::toPHP(?array `$typeMap` = `null`): array|object

### Parámetros

`typeMap` (array)
  Configuración del mapa de tipos.

### Valores devueltos

El valor decodificado en PHP.

> Nota: Cuando se encuentra un valor codificado como un entero de 64 bits en el array BSON, el valor de retorno de este método será una instancia de MongoDB\BSON\Int64.

### Errores/Excepciones

- Lanza una MongoDB\Driver\Exception\InvalidArgumentException si una clase en el type map no puede ser instanciada o no implementa MongoDB\BSON\Unserializable.

### Ver también

- MongoDB\BSON\toPHP() - Devuelve la representación en PHP de un valor BSON
- » Tipos BSON

# MongoDB\BSON\PackedArray::toRelaxedExtendedJSON

(mongodb >=1.20.0)

MongoDB\BSON\PackedArray::toRelaxedExtendedJSON — Devuelve la representación JSON extendida relajada del array BSON

### Descripción

final public function MongoDB\BSON\PackedArray::toRelaxedExtendedJSON(): string

Convierte el array BSON en su representación » JSON extendida relajada. El formato relajado prefiere el uso de los tipos primitivos JSON en detrimento de la fidelidad de los tipos y es el más adecuado para producir una salida que puede ser fácilmente consumida por APIs web y humanos.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un string que contiene la representación » JSON extendida relajada del array BSON.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\BSON\PackedArray::toRelaxedExtendedJSON()

    <?php

    $array = [
        'foo',
        123,
        4294967295,
        new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1'),
    ];

    $packedArray = MongoDB\BSON\PackedArray::fromPHP($array);
    echo $packedArray->toRelaxedExtendedJSON(), "\n";

    ?>

El ejemplo anterior mostrará:

    [ "foo", 123, 4294967295, { "$oid" : "56315a7c6118fd1b920270b1" } ]

### Ver también

- MongoDB\BSON\PackedArray::fromJSON() - Construye una nueva instancia de array BSON a partir de un string JSON
- MongoDB\BSON\PackedArray::toCanonicalExtendedJSON() - Devuelve la representación JSON extendida canónica del array BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Devuelve la representación en Relaxed Extended JSON de un valor BSON
- » Especificación del JSON extendido
- » Tipos BSON

# MongoDB\BSON\PackedArray::__toString

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::__toString — Devuelve la representación en string para este array BSON

### Descripción

final public function MongoDB\BSON\PackedArray::__toString(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la representación en string de este array BSON.

### Ver también

- » Tipos BSON

## Tabla de contenidos

- MongoDB\BSON\PackedArray::__construct — Construye un nuevo array BSON (no utilizado)
- MongoDB\BSON\PackedArray::fromJSON — Construye una nueva instancia de array BSON a partir de un string JSON
- MongoDB\BSON\PackedArray::fromPHP — Construye una nueva instancia de array BSON a partir de datos PHP
- MongoDB\BSON\PackedArray::get — Devuelve el valor de un índice del array
- MongoDB\BSON\PackedArray::getIterator — Devuelve el iterador para el array BSON
- MongoDB\BSON\PackedArray::has — Indica si un índice está presente en el array
- MongoDB\BSON\PackedArray::offsetExists — Indica si un índice está presente en el array
- MongoDB\BSON\PackedArray::offsetGet — Devuelve el valor de un índice del array
- MongoDB\BSON\PackedArray::offsetSet — Implementación de ArrayAccess
- MongoDB\BSON\PackedArray::offsetUnset — Implementación de ArrayAccess
- MongoDB\BSON\PackedArray::toCanonicalExtendedJSON — Devuelve la representación JSON extendida canónica del array BSON
- MongoDB\BSON\PackedArray::toPHP — Devuelve la representación PHP del array BSON
- MongoDB\BSON\PackedArray::toRelaxedExtendedJSON — Devuelve la representación JSON extendida relajada del array BSON
- MongoDB\BSON\PackedArray::__toString — Devuelve la representación en string para este array BSON

# La clase MongoDB\BSON\Iterator

(mongodb >=1.16.0)

## Introducción

Iterador utilizado para recorrer un documento o un array BSON.

## Sinopsis de la Clase

final class MongoDB\BSON\Iterator implements Iterator {
/* Métodos */
final private function __construct()
public function current(): mixed
public function key(): string|int
public function next(): void
public function rewind(): void
public function valid(): bool
}

# MongoDB\BSON\Iterator::__construct

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::__construct — Construye un nuevo iterador BSON (no utilizado)

### Descripción

final private function MongoDB\BSON\Iterator::__construct()

Los objetos MongoDB\BSON\Iterator se crean llamando a MongoDB\BSON\Document::getIterator() o MongoDB\BSON\PackedArray::getIterator() y no pueden ser instanciados directamente.

### Parámetros

Esta función no contiene ningún parámetro.

### Ver también

- MongoDB\BSON\Document::getIterator() - Devuelve un iterador para el documento BSON
- MongoDB\BSON\PackedArray::getIterator() - Devuelve el iterador para el array BSON
- » Tipos BSON

# MongoDB\BSON\Iterator::current

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::current — Devuelve el elemento actual/corriente

### Descripción

public function MongoDB\BSON\Iterator::current(): mixed

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el valor del elemento actual/corriente.

> Nota: Cuando un valor es codificado como un integer de 64 bits en la estructura BSON es encontrado, el valor de retorno de este método será una instancia de MongoDB\BSON\Int64.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una MongoDB\Driver\Exception\LogicException si el iterador no es válido.

### Ver también

- Iterator::current() - Devuelve el elemento actual

# MongoDB\BSON\Iterator::key

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::key — Devuelve la clave del elemento actual/corriente

### Descripción

public function MongoDB\BSON\Iterator::key(): string|int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la clave del elemento actual/corriente. Durante la iteración de un documento BSON, la clave será siempre una string. Durante la iteración de un array BSON, la clave será un int.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una MongoDB\Driver\Exception\LogicException si el iterador no es válido.

### Ver también

- Iterator::key() - Devuelve la clave del elemento actual

# MongoDB\BSON\Iterator::next

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::next — Avance el iterador al siguiente elemento

### Descripción

public function MongoDB\BSON\Iterator::next(): void

### Parámetros

Esta función no contiene ningún parámetro.

### Ver también

- Iterator::next() - Avanza al siguiente elemento

# MongoDB\BSON\Iterator::rewind

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::rewind — Rebobina el iterador al elemento anterior

### Descripción

public function MongoDB\BSON\Iterator::rewind(): void

### Parámetros

Esta función no contiene ningún parámetro.

### Ver también

- Iterator::rewind() - Rebobine la Iterator al primer elemento

# MongoDB\BSON\Iterator::valid

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::valid — Verifica si la posición actual es válida

### Descripción

public function MongoDB\BSON\Iterator::valid(): bool

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si la posición actual del iterador es válida, de lo contrario `false`.

### Ver también

- Iterator::valid() - Comprueba si la posición actual es válido

## Tabla de contenidos

- MongoDB\BSON\Iterator::__construct — Construye un nuevo iterador BSON (no utilizado)
- MongoDB\BSON\Iterator::current — Devuelve el elemento actual/corriente
- MongoDB\BSON\Iterator::key — Devuelve la clave del elemento actual/corriente
- MongoDB\BSON\Iterator::next — Avance el iterador al siguiente elemento
- MongoDB\BSON\Iterator::rewind — Rebobina el iterador al elemento anterior
- MongoDB\BSON\Iterator::valid — Verifica si la posición actual es válida

# La clase MongoDB\BSON\Binary

(mongodb >=1.0.0)

## Introducción

Tipo BSON para datos binarios (i.e. array de bytes). Los valores binarios también tienen un subtipo, que se utiliza para indicar qué tipo de datos se encuentra en el array de bytes. Los subtipos de cero a 127 están predefinidos o reservados. Los subtipos de 128-255 son definidos por el usuario.

## Sinopsis de la Clase

final class MongoDB\BSON\Binary implements MongoDB\BSON\BinaryInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Constantes */
const int TYPE_GENERIC = 0;
const int TYPE_FUNCTION = 1;
const int TYPE_OLD_BINARY = 2;
const int TYPE_OLD_UUID = 3;
const int TYPE_UUID = 4;
const int TYPE_MD5 = 5;
const int TYPE_ENCRYPTED = 6;
const int TYPE_COLUMN = 7;
const int TYPE_SENSITIVE = 8;
const int TYPE_VECTOR = 9;
const int TYPE_USER_DEFINED = 128;
/* Métodos */
final public function __construct(string `$data`, int `$type` = MongoDB\BSON\Binary::TYPE_GENERIC)
final public static function fromVector(array `$vector`, MongoDB\BSON\VectorType `$vectorType`): MongoDB\BSON\Binary
final public function getData(): string
final public function getType(): int
final public function getVectorType(): MongoDB\BSON\VectorType
final public function jsonSerialize(): mixed
final public function toArray(): array
final public function __toString(): string
}

## Constantes predefinidas

`MongoDB\BSON\Binary::TYPE_GENERIC`
  Datos binarios genéricos.
`MongoDB\BSON\Binary::TYPE_FUNCTION`
  Función.
`MongoDB\BSON\Binary::TYPE_OLD_BINARY`
  Datos binarios genéricos (desaconsejados en favor de `MongoDB\BSON\Binary::TYPE_GENERIC`).
`MongoDB\BSON\Binary::TYPE_OLD_UUID`
  Identificador universalmente único (desaconsejado en favor de `MongoDB\BSON\Binary::TYPE_UUID`). Al utilizar este tipo, los datos del binario deben tener una longitud de 16 bytes. Históricamente, otros controladores codifican valores con este tipo según sus convenciones lingüísticas (por ejemplo, variable indianness), lo que lo hace no portable. El controlador PHP no aplica ninguna manipulación especial para codificar o decodificar datos con este tipo.
`MongoDB\BSON\Binary::TYPE_UUID`
  Identificador universalmente único. Al utilizar este tipo, los datos del binario deben tener una longitud de 16 bytes y estar codificados según » RFC 4122.
`MongoDB\BSON\Binary::TYPE_MD5`
  Hash MD5. Al utilizar este tipo, los datos del binario deben tener una longitud de 16 bytes.
`MongoDB\BSON\Binary::TYPE_ENCRYPTED`
  Valor cifrado. Este subtipo se utiliza para el cifrado del lado del cliente.
`MongoDB\BSON\Binary::TYPE_COLUMN`
  Dato de columna. Este subtipo se utiliza para las colecciones de series temporales.
`MongoDB\BSON\Binary::TYPE_SENSITIVE`
  Datos sensibles. Este subtipo se utiliza para los datos sensibles que deberían ser excluidos de los registros de eventos del lado del servidor si es posible.
`MongoDB\BSON\Binary::TYPE_VECTOR`
  Datos de vector. Este subtipo se utiliza para almacenar eficientemente datos de vector para su uso con la búsqueda de vectores de MongoDB.
`MongoDB\BSON\Binary::TYPE_USER_DEFINED`
  Tipo definido por el usuario. Mientras que los tipos entre 0 y 127 están predefinidos o reservados, los tipos entre 128 y 255 son definidos por el usuario y pueden ser utilizados para cualquier cosa.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.2.0 | Adición de `MongoDB\BSON\Binary::TYPE_VECTOR`, así como las funciones MongoDB\BSON\Binary::fromVector(), MongoDB\BSON\Binary::getVectorType() y MongoDB\BSON\Binary::toArray().
PECL mongodb 2.0.0 | Esta clase ya no implementa la interfaz Serializable.
PECL mongodb 1.17.0 | Adición de `MongoDB\BSON\Binary::TYPE_SENSITIVE`.
PECL mongodb 1.12.0 | Implementa Stringable para PHP 8.0+. Adición de `MongoDB\BSON\Binary::TYPE_COLUMN`.
PECL mongodb 1.7.0 | Adición de `MongoDB\BSON\Binary::TYPE_ENCRYPTED`.
PECL mongodb 1.3.0 | Implementa MongoDB\BSON\BinaryInterface.
PECL mongodb 1.2.0 | Implementa Serializable y JsonSerializable.

# MongoDB\BSON\Binary::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Binary::__construct — Construye un nuevo binario

### Descripción

final public function MongoDB\BSON\Binary::__construct(string `$data`, int `$type` = MongoDB\BSON\Binary::TYPE_GENERIC)

### Parámetros

`data` (string)
  Los datos binarios.
`type` (int)
  Entero de 8 bits sin signo que indica el tipo de datos. Por omisión, el valor es `MongoDB\BSON\Binary::TYPE_GENERIC` si no se especifica.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si `type` no es un entero sin signo de 8 bits.
- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si `type` es `MongoDB\BSON\Binary::TYPE_UUID` o `MongoDB\BSON\Binary::TYPE_OLD_UUID` y `data` no tiene exactamente 16 bytes de longitud.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.15.0 | El parámetro `type` es ahora opcional y tiene el valor por omisión `MongoDB\BSON\Binary::TYPE_GENERIC` si no se especifica.
PECL mongodb 1.3.0 | MongoDB\Driver\Exception\InvalidArgumentException se lanza si `type` es `MongoDB\BSON\Binary::TYPE_UUID` o `MongoDB\BSON\Binary::TYPE_OLD_UUID` y `data` no tiene exactamente 16 bytes de longitud.
PECL mongodb 1.1.3 | MongoDB\Driver\Exception\InvalidArgumentException se lanza si `type` no es un entero sin signo de 8 bits.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\BSON\Binary::__construct()

    <?php

    $binary = new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC);
    var_dump($binary);

    ?>

El ejemplo anterior mostrará:

    object(MongoDB\BSON\Binary)#1 (2) {
      ["data"]=>
      string(3) "foo"
      ["type"]=>
      int(0)
    }

### Ver también

- » Los tipos BSON

# MongoDB\BSON\Binary::fromVector

(mongodb >=2.2.0)

MongoDB\BSON\Binary::fromVector — Crea un nuevo binario con subtipo `MongoDB\BSON\Binary::SUBTYPE_VECTOR` a partir del array y tipo de vector dados

### Descripción

final public static function MongoDB\BSON\Binary::fromVector(array `$vector`, MongoDB\BSON\VectorType `$vectorType`): MongoDB\BSON\Binary

### Parámetros

`vector` (array)

  Un array de valores que representa los datos del vector. El tipo de cada valor debe coincidir con el tipo indicado por el parámetro `vectorType`:

  - para `MongoDB\BSON\VectorType::Float32`, cada valor debe ser un float
  - para `MongoDB\BSON\VectorType::Int8`, cada valor debe ser un int de 8 bits, es decir, de `-127` a `128`
  - para `MongoDB\BSON\VectorType::PackedBit`, cada valor debe ser un bool o un int de 1 bit, es decir, `0` o `1`
`vectorType` (MongoDB\BSON\VectorType)
  El tipo de datos del vector.

### Valores devueltos

Devuelve un nuevo Binary con subtipo `MongoDB\BSON\Binary::SUBTYPE_VECTOR`.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\BSON\Binary::toArray() - Devuelve el vector como un array para un Binary con subtipo MongoDB\BSON\Binary::SUBTYPE_VECTOR
- MongoDB\BSON\Binary::getVectorType() - Devuelve el tipo de datos para un Binary con el subtipo vector
- MongoDB\BSON\VectorType
- » BSON Types

# MongoDB\BSON\Binary::getData

(mongodb >=1.0.0)

MongoDB\BSON\Binary::getData — Devuelve los datos de Binary

### Descripción

final public function MongoDB\BSON\Binary::getData(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve los datos de Binary.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\BSON\Binary::getData()

    <?php

    $binary = new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC);
    var_dump($binary->getData());

    ?>

El ejemplo anterior mostrará:

    string(3) "foo"

### Ver también

- » Tipos BSON

# MongoDB\BSON\Binary::getType

(mongodb >=1.0.0)

MongoDB\BSON\Binary::getType — Devuelve el tipo de Binary

### Descripción

final public function MongoDB\BSON\Binary::getType(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el tipo de Binary.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\BSON\Binary::getType()

    <?php

    $binary = new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC);
    var_dump($binary->getType());

    ?>

El ejemplo anterior mostrará:

    int(0)

### Ver también

- » Tipos BSON

# MongoDB\BSON\Binary::getVectorType

(mongodb >=2.2.0)

MongoDB\BSON\Binary::getVectorType — Devuelve el tipo de datos para un Binary con el subtipo vector

### Descripción

final public function MongoDB\BSON\Binary::getVectorType(): MongoDB\BSON\VectorType

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el tipo de datos del vector Binary.

### Errores/Excepciones

- Lanza MongoDB\Driver\Exception\LogicException si el subtipo no es `MongoDB\BSON\Binary::SUBTYPE_VECTOR`.
- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- » BSON Types
- MongoDB\BSON\VectorType

# MongoDB\BSON\Binary::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Binary::jsonSerialize — Devuelve una representación que puede ser convertida en JSON

### Descripción

final public function MongoDB\BSON\Binary::jsonSerialize(): mixed

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve datos que pueden ser serializados por json_encode() para producir una representación JSON extendida de MongoDB\BSON\Binary.

> Nota: La salida es coherente con la función MongoDB\BSON\toJSON(), que utiliza el formato JSON extendido específico del controlador. Esto no corresponde necesariamente a las representaciones JSON extendidas » relajadas o » canónicas utilizadas por MongoDB\BSON\toRelaxedExtendedJSON() y MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- JsonSerializable::jsonSerialize() - Especifica los datos que deben ser serializados en JSON
- json_encode() - Retorna la representación JSON de un valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Devuelve la representación en Canonical Extended JSON de un valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Devuelve la representación en Relaxed Extended JSON de un valor BSON
- » MongoDB JSON Extendido

# MongoDB\BSON\Binary::toArray

(mongodb >=2.2.0)

MongoDB\BSON\Binary::toArray — Devuelve el vector como un array para un Binary con subtipo `MongoDB\BSON\Binary::SUBTYPE_VECTOR`

### Descripción

final public function MongoDB\BSON\Binary::toArray(): array

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array que contiene los datos del vector.

### Errores/Excepciones

- Lanza MongoDB\Driver\Exception\LogicException si el subtipo no es `MongoDB\BSON\Binary::SUBTYPE_VECTOR`.
- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\BSON\Binary::fromVector() - Crea un nuevo binario con subtipo MongoDB\BSON\Binary::SUBTYPE_VECTOR a partir del array y tipo de vector dados
- » BSON Types

# MongoDB\BSON\Binary::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Binary::__toString — Devuelve los datos de Binary

### Descripción

final public function MongoDB\BSON\Binary::__toString(): string

Este método es un alias de: MongoDB\BSON\Binary::getData().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve los datos de Binary.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\BSON\Binary::__toString()

    <?php

    var_dump((string) new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC));

    ?>

El ejemplo anterior mostrará:

    string(3) "foo"

### Ver también

- MongoDB\BSON\Binary::getData() - Devuelve los datos de Binary
- » Tipos BSON

## Tabla de contenidos

- MongoDB\BSON\Binary::__construct — Construye un nuevo binario
- MongoDB\BSON\Binary::fromVector — Crea un nuevo binario con subtipo MongoDB\BSON\Binary::SUBTYPE_VECTOR a partir del array y tipo de vector dados
- MongoDB\BSON\Binary::getData — Devuelve los datos de Binary
- MongoDB\BSON\Binary::getType — Devuelve el tipo de Binary
- MongoDB\BSON\Binary::getVectorType — Devuelve el tipo de datos para un Binary con el subtipo vector
- MongoDB\BSON\Binary::jsonSerialize — Devuelve una representación que puede ser convertida en JSON
- MongoDB\BSON\Binary::toArray — Devuelve el vector como un array para un Binary con subtipo MongoDB\BSON\Binary::SUBTYPE_VECTOR
- MongoDB\BSON\Binary::__toString — Devuelve los datos de Binary

# La enumeración MongoDB\BSON\VectorType

(mongodb >=2.2.0)

## Introducción

La enumeración MongoDB\BSON\VectorType se utiliza para especificar el tipo de datos vectoriales almacenados en un MongoDB\BSON\Binary con subtipo `MongoDB\BSON\Binary::TYPE_VECTOR`.

## Sinopsis del Enum

enum MongoDB\BSON\VectorType
{
case Float32 ; // Cada elemento en el vector es un valor de punto flotante de 32 bits.
case Int8 ; // Cada elemento en el vector es un valor entero de 8 bits.
case PackedBit ; // Cada elemento en el vector es un valor de 1 bit. Al crear vectores de este tipo, puede pasar valores bool o valores int de 1 bit, es decir, `0` o `1`.
}

# La clase MongoDB\BSON\Decimal128

(mongodb >=1.2.0)

## Introducción

Tipo BSON para el » formato de coma flotante Decimal128, que soporta números con hasta 34 dígitos decimales (i.e. dígitos significativos) y un rango de exponentes de −6143 a +6144.

A diferencia del tipo BSON double (i.e. float en PHP), que solo almacena una aproximación de los valores decimales, el tipo de datos decimal almacena el valor exacto. Por ejemplo, `MongoDB\BSON\Decimal128('9.99')` tiene un valor preciso de 9.99 mientras que un double 9.99 tendría un valor aproximado de 9.9900000000000002131628….

> Nota: MongoDB\BSON\Decimal128 solo es compatible con MongoDB 3.4+. Si se intenta utilizar el tipo BSON con una versión antigua de MongoDB, se emitirá un error.

## Sinopsis de la Clase

final class MongoDB\BSON\Decimal128 implements MongoDB\BSON\Decimal128Interface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Métodos */
final public function __construct(string `$value`)
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Esta clase ya no implementa la interfaz Serializable.
PECL mongodb 1.12.0 | Implementa Stringable para PHP 8.0+.
PECL mongodb 1.3.0 | Implementa MongoDB\BSON\Decimal128Interface.
PECL mongodb 1.2.0 | Implementa Serializable y JsonSerializable.

# MongoDB\BSON\Decimal128::__construct

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::__construct — Construye un nuevo Decimal128

### Descripción

final public function MongoDB\BSON\Decimal128::__construct(string `$value`)

> Nota: MongoDB\BSON\Decimal128 solo es compatible con MongoDB 3.4+. Si se intenta utilizar el tipo BSON con una versión antigua de MongoDB, se emitirá un error.

### Parámetros

`value` (string)
  Una cadena decimal

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza MongoDB\Driver\Exception\InvalidArgumentException si `value` no es una cadena decimal válida.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\BSON\Decimal128::__construct()

    <?php

    var_dump(new MongoDB\BSON\Decimal128(1234.5678));
    var_dump(new MongoDB\BSON\Decimal128(NAN));
    var_dump(new MongoDB\BSON\Decimal128(INF));

    ?>

Resultado del ejemplo anterior es similar a:

    object(MongoDB\BSON\Decimal128)#1 (1) {
      ["dec"]=>
      string(9) "1234.5678"
    }
    object(MongoDB\BSON\Decimal128)#1 (1) {
      ["dec"]=>
      string(3) "NaN"
    }
    object(MongoDB\BSON\Decimal128)#1 (1) {
      ["dec"]=>
      string(8) "Infinity"
    }

### Ver también

- » Formato de coma flotante Decimal128
- » Tipos BSON

# MongoDB\BSON\Decimal128::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::jsonSerialize — Devuelve una representación que puede ser convertida en JSON

### Descripción

final public function MongoDB\BSON\Decimal128::jsonSerialize(): mixed

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve datos que pueden ser serializados por json_encode() para producir una representación JSON extendida de MongoDB\BSON\Decimal128.

> Nota: La salida es coherente con la función MongoDB\BSON\toJSON(), que utiliza el formato JSON extendido específico del controlador. Esto no corresponde necesariamente a las representaciones JSON extendidas » relajadas o » canónicas utilizadas por MongoDB\BSON\toRelaxedExtendedJSON() y MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- JsonSerializable::jsonSerialize() - Especifica los datos que deben ser serializados en JSON
- json_encode() - Retorna la representación JSON de un valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Devuelve la representación en Canonical Extended JSON de un valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Devuelve la representación en Relaxed Extended JSON de un valor BSON
- » MongoDB JSON Extendido

# MongoDB\BSON\Decimal128::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::__toString — Devuelve la representación en forma de string de Decimal128

### Descripción

final public function MongoDB\BSON\Decimal128::__toString(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la representación en forma de string de Decimal128.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\BSON\Decimal128::__toString()

    <?php

    var_dump((string) new MongoDB\BSON\Decimal128(1234.5678));
    var_dump((string) new MongoDB\BSON\Decimal128(NAN));
    var_dump((string) new MongoDB\BSON\Decimal128(INF));

    ?>

Resultado del ejemplo anterior es similar a:

    string(9) "1234.5678"
    string(3) "NaN"
    string(8) "Infinity"

### Ver también

- » Formato de coma flotante Decimal128
- » Tipos BSON

## Tabla de contenidos

- MongoDB\BSON\Decimal128::__construct — Construye un nuevo Decimal128
- MongoDB\BSON\Decimal128::jsonSerialize — Devuelve una representación que puede ser convertida en JSON
- MongoDB\BSON\Decimal128::__toString — Devuelve la representación en forma de string de Decimal128

# La clase MongoDB\BSON\Javascript

(mongodb >=1.0.0)

## Introducción

Tipo BSON para el código JavaScript. Un documento de ámbito opcional puede ser especificado que mapea los identificadores a los valores y define el ámbito en el cual el código debe ser evaluado por el servidor.

> Nota: Este tipo BSON es principalmente utilizado durante la ejecución de comandos de base de datos que toman una función JavaScript como argumento, tal como » mapReduce.

## Sinopsis de la Clase

final class MongoDB\BSON\Javascript implements MongoDB\BSON\JavascriptInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Métodos */
final public function __construct(string `$code`, array|object|null `$scope` = `null`)
final public function getCode(): string
final public function getScope(): ?object
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Esta clase ya no implementa la interfaz Serializable.
PECL mongodb 1.12.0 | Implementa Stringable para PHP 8.0+.
PECL mongodb 1.3.0 | Implementa MongoDB\BSON\JavascriptInterface.
PECL mongodb 1.2.0 | Implementa Serializable y JsonSerializable.

# MongoDB\BSON\Javascript::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Javascript::__construct — Construye un nuevo objeto Javascript

### Descripción

final public function MongoDB\BSON\Javascript::__construct(string `$code`, array|object|null `$scope` = `null`)

### Parámetros

`code` (string)
  El código Javascript.
`scope` (array|object)
  El ámbito del Javascript.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza MongoDB\Driver\Exception\InvalidArgumentException si `code` contiene un byte nulo.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.2.0 | MongoDB\Driver\Exception\InvalidArgumentException se lanza si `code` contiene un byte nulo. Anteriormente, los valores eran truncados en el primer byte nulo.

### Ejemplos

Ejemplo #1 MongoDB\BSON\Javascript::__construct() example

    <?php

    $code = new MongoDB\BSON\Javascript('function() { return 1; }');
    var_dump($code);

    $codews = new MongoDB\BSON\Javascript('function() { return foo; }', ['foo' => 'bar']);
    var_dump($codews);

    ?>

El ejemplo anterior mostrará:

    object(MongoDB\BSON\Javascript)#1 (2) {
      ["javascript"]=>
      string(24) "function() { return 1; }"
      ["scope"]=>
      object(stdClass)#2 (0) {
      }
    }
    object(MongoDB\BSON\Javascript)#2 (2) {
      ["javascript"]=>
      string(26) "function() { return foo; }"
      ["scope"]=>
      object(stdClass)#1 (1) {
        ["foo"]=>
        string(3) "bar"
      }
    }

### Ver también

- » Los tipos BSON

# MongoDB\BSON\Javascript::getCode

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::getCode — Devuelve el código Javascript

### Descripción

final public function MongoDB\BSON\Javascript::getCode(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el código Javascript.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\BSON\Javascript::getCode()

    <?php

    $js = new MongoDB\BSON\Javascript('function foo(bar) { return bar; }');
    var_dump($js->getCode());

    ?>

El ejemplo anterior mostrará:

    string(33) "function foo(bar) { return bar; }"

### Ver también

- » Tipos BSON

# MongoDB\BSON\Javascript::getScope

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::getScope — Devuelve el documento de ámbito de Javascript

### Descripción

final public function MongoDB\BSON\Javascript::getScope(): ?object

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el documento de ámbito de Javascript, o `null` si no tiene ámbito.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\BSON\Javascript::getScope()

    <?php

    $js = new MongoDB\BSON\Javascript('function foo(bar) { return bar; }');
    var_dump($js->getScope());

    $js = new MongoDB\BSON\Javascript('function foo() { return foo; }', ['foo' => 42]);
    var_dump($js->getScope());

    ?>

El ejemplo anterior mostrará:

    NULL
    object(stdClass)#1 (1) {
      ["foo"]=>
      int(42)
    }

### Ver también

- » Tipos BSON

# MongoDB\BSON\Javascript::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::jsonSerialize — Devuelve una representación que puede ser convertida en JSON

### Descripción

final public function MongoDB\BSON\Javascript::jsonSerialize(): mixed

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve datos que pueden ser serializados por json_encode() para producir una representación JSON extendida de MongoDB\BSON\Javascript.

> Nota: La salida es coherente con la función MongoDB\BSON\toJSON(), que utiliza el formato JSON extendido específico del controlador. Esto no corresponde necesariamente a las representaciones JSON extendidas » relajadas o » canónicas utilizadas por MongoDB\BSON\toRelaxedExtendedJSON() y MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- JsonSerializable::jsonSerialize() - Especifica los datos que deben ser serializados en JSON
- json_encode() - Retorna la representación JSON de un valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Devuelve la representación en Canonical Extended JSON de un valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Devuelve la representación en Relaxed Extended JSON de un valor BSON
- » MongoDB JSON Extendido

# MongoDB\BSON\Javascript::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::__toString — Devuelve el código Javascript

### Descripción

final public function MongoDB\BSON\Javascript::__toString(): string

Este método es un alias de: MongoDB\BSON\Javascript::getCode().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el código Javascript.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\BSON\Javascript::__toString()

    <?php

    var_dump((string) new MongoDB\BSON\Javascript('function foo(bar) { return bar; }'));

    ?>

El ejemplo anterior mostrará:

    string(33) "function foo(bar) { return bar; }"

### Ver también

- MongoDB\BSON\Javascript::getCode() - Devuelve el código Javascript
- » Tipos BSON

## Tabla de contenidos

- MongoDB\BSON\Javascript::__construct — Construye un nuevo objeto Javascript
- MongoDB\BSON\Javascript::getCode — Devuelve el código Javascript
- MongoDB\BSON\Javascript::getScope — Devuelve el documento de ámbito de Javascript
- MongoDB\BSON\Javascript::jsonSerialize — Devuelve una representación que puede ser convertida en JSON
- MongoDB\BSON\Javascript::__toString — Devuelve el código Javascript

# La clase MongoDB\BSON\MaxKey

(mongodb >=1.0.0)

## Introducción

Tipo BSON especial que compara el valor más grande posible de todos los otros valores de elementos BSON posibles.

> Nota: Se trata de un tipo interno de MongoDB utilizado para la indexación y la desfragmentación.

## Sinopsis de la Clase

final class MongoDB\BSON\MaxKey implements MongoDB\BSON\MaxKeyInterface, MongoDB\BSON\Type, JsonSerializable {
/* Métodos */
final public function __construct()
final public function jsonSerialize(): mixed
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Esta clase ya no implementa la interfaz Serializable.
PECL mongodb 1.3.0 | Implementa MongoDB\BSON\MaxKeyInterface.
PECL mongodb 1.2.0 | Implementa Serializable y JsonSerializable.

# MongoDB\BSON\MaxKey::__construct

(mongodb >=1.0.0)

MongoDB\BSON\MaxKey::__construct — Construye un nuevo MaxKey

### Descripción

final public function MongoDB\BSON\MaxKey::__construct()

### Parámetros

Esta función no contiene ningún parámetro.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\BSON\MaxKey::__construct()

    <?php

    var_dump(new MongoDB\BSON\MaxKey());

    ?>

El ejemplo anterior mostrará:

    object(MongoDB\BSON\MaxKey)#1 (0) {
    }

### Ver también

- » Tipos BSON

# MongoDB\BSON\MaxKey::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\MaxKey::jsonSerialize — Devuelve una representación que puede ser convertida en JSON

### Descripción

final public function MongoDB\BSON\MaxKey::jsonSerialize(): mixed

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve datos que pueden ser serializados por json_encode() para producir una representación JSON extendida de MongoDB\BSON\MaxKey.

> Nota: La salida es coherente con la función MongoDB\BSON\toJSON(), que utiliza el formato JSON extendido específico del controlador. Esto no corresponde necesariamente a las representaciones JSON extendidas » relajadas o » canónicas utilizadas por MongoDB\BSON\toRelaxedExtendedJSON() y MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- JsonSerializable::jsonSerialize() - Especifica los datos que deben ser serializados en JSON
- json_encode() - Retorna la representación JSON de un valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Devuelve la representación en Canonical Extended JSON de un valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Devuelve la representación en Relaxed Extended JSON de un valor BSON
- » MongoDB JSON Extendido

## Tabla de contenidos

- MongoDB\BSON\MaxKey::__construct — Construye un nuevo MaxKey
- MongoDB\BSON\MaxKey::jsonSerialize — Devuelve una representación que puede ser convertida en JSON

# La clase MongoDB\BSON\MinKey

(mongodb >=1.0.0)

## Introducción

Tipo BSON especial que compara el valor más pequeño posible de todos los demás valores de elementos BSON posibles.

> Nota: Se trata de un tipo interno de MongoDB utilizado para la indexación y la desfragmentación.

## Sinopsis de la Clase

final class MongoDB\BSON\MinKey implements MongoDB\BSON\MinKeyInterface, MongoDB\BSON\Type, JsonSerializable {
/* Métodos */
final public function __construct()
final public function jsonSerialize(): mixed
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Esta clase ya no implementa la interfaz Serializable.
PECL mongodb 1.3.0 | Implementa MongoDB\BSON\MinKeyInterface.
PECL mongodb 1.2.0 | Implementa Serializable y JsonSerializable.

# MongoDB\BSON\MinKey::__construct

(mongodb >=1.0.0)

MongoDB\BSON\MinKey::__construct — Construye un nuevo MinKey

### Descripción

final public function MongoDB\BSON\MinKey::__construct()

### Parámetros

Esta función no contiene ningún parámetro.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\BSON\MinKey::__construct()

    <?php

    var_dump(new MongoDB\BSON\MinKey());

    ?>

El ejemplo anterior mostrará:

    object(MongoDB\BSON\MinKey)#1 (0) {
    }

### Ver también

- » Tipos BSON

# MongoDB\BSON\MinKey::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\MinKey::jsonSerialize — Devuelve una representación que puede ser convertida en JSON

### Descripción

final public function MongoDB\BSON\MinKey::jsonSerialize(): mixed

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve datos que pueden ser serializados por json_encode() para producir una representación JSON extendida de MongoDB\BSON\MinKey.

> Nota: La salida es coherente con la función MongoDB\BSON\toJSON(), que utiliza el formato JSON extendido específico del controlador. Esto no corresponde necesariamente a las representaciones JSON extendidas » relajadas o » canónicas utilizadas por MongoDB\BSON\toRelaxedExtendedJSON() y MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- JsonSerializable::jsonSerialize() - Especifica los datos que deben ser serializados en JSON
- json_encode() - Retorna la representación JSON de un valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Devuelve la representación en Canonical Extended JSON de un valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Devuelve la representación en Relaxed Extended JSON de un valor BSON
- » MongoDB JSON Extendido

## Tabla de contenidos

- MongoDB\BSON\MinKey::__construct — Construye un nuevo MinKey
- MongoDB\BSON\MinKey::jsonSerialize — Devuelve una representación que puede ser convertida en JSON

# La clase MongoDB\BSON\ObjectId

(mongodb >=1.0.0)

## Introducción

Tipo BSON para un » ObjectId. El valor se compone de 12 bytes, donde los primeros cuatro bytes son un timestamp que refleja la creación del ObjectId. Más precisamente, el valor se compone de :

- un valor de 4 bytes representando los segundos desde la época UNIX,
- un número aleatorio de 5 bytes único a una máquina y un proceso, y
- un contador de 3 bytes, comenzando por un valor aleatorio.

En MongoDB, cada documento almacenado en una colección requiere un campo `_id` único que actúa como clave primaria. Si un documento insertado omite el campo `_id`, la extensión genera automáticamente un ObjectId para el campo `_id`.

El uso de ObjectId para el campo `_id` proporciona las siguientes ventajas adicionales:

- La hora de creación del ObjectId puede ser accedida utilizando el método MongoDB\BSON\ObjectId::getTimestamp().
- La ordenación en un campo `_id` que almacena valores ObjectId equivale aproximadamente a la ordenación por fecha de creación.

## Sinopsis de la Clase

final class MongoDB\BSON\ObjectId implements MongoDB\BSON\ObjectIdInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Métodos */
final public function __construct(?string `$id` = `null`)
final public function getTimestamp(): int
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Esta clase ya no implementa la interfaz Serializable.
PECL mongodb 1.12.0 | Implementa Stringable para PHP 8.0+.
PECL mongodb 1.3.0 | Renombrado de `MongoDB\BSON\ObjectID` a `MongoDB\BSON\ObjectId`. Implementa MongoDB\BSON\ObjectIdInterface.
PECL mongodb 1.2.0 | Implementa Serializable y JsonSerializable.

# MongoDB\BSON\ObjectId::__construct

(mongodb >=1.0.0)

MongoDB\BSON\ObjectId::__construct — Construye un nuevo ObjectId

### Descripción

final public function MongoDB\BSON\ObjectId::__construct(?string `$id` = `null`)

### Parámetros

`id` (string)
  Una cadena hexadecimal de 24 caracteres. Si no se proporciona, la extensión generará un ObjectId.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si `id` no es una cadena hexadecimal de 24 caracteres.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\BSON\ObjectId::__construct()

    <?php

    var_dump(new MongoDB\BSON\ObjectId());

    var_dump(new MongoDB\BSON\ObjectId('000000000000000000000001'));

    ?>

Resultado del ejemplo anterior es similar a:

    object(MongoDB\BSON\ObjectId)#1 (1) {
      ["oid"]=>
      string(24) "56732d3dda14d81214634921"
    }
    object(MongoDB\BSON\ObjectId)#1 (1) {
      ["oid"]=>
      string(24) "000000000000000000000001"
    }

### Ver también

- » La referencia ObjectId
- » El tipo BSON : ObjectId

# MongoDB\BSON\ObjectId::getTimestamp

(mongodb >=1.2.0)

MongoDB\BSON\ObjectId::getTimestamp — Devuelve el componente de timestamp de ObjectId

### Descripción

final public function MongoDB\BSON\ObjectId::getTimestamp(): int

El componente de timestamp de un ObjectId son sus 32 bits más significativos, que denotan el número de segundos desde el epoch Unix. Este valor se lee como un entero de 32 bits sin signo con un orden de bytes big-endian.

> Nota: Dado que el tipo entero de PHP es firmado, algunos valores devueltos por este método pueden aparecer como enteros negativos en las plataformas de 32 bits. El formateador "%u" de sprintf() puede ser utilizado para obtener una representación en forma de string del valor decimal no firmado.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el componente de timestamp de ObjectId.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\BSON\ObjectId::getTimestamp()

    <?php

    var_dump((new MongoDB\BSON\ObjectId())->getTimestamp());

    var_dump((new MongoDB\BSON\ObjectId('0000002a0000000000000000'))->getTimestamp());

    ?>

Resultado del ejemplo anterior es similar a:

    integer(1484854719)
    integer(42)

### Ver también

- » Referencia ObjectId
- » Tipos BSON : ObjectId

# MongoDB\BSON\ObjectId::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\ObjectId::jsonSerialize — Devuelve una representación que puede ser convertida en JSON

### Descripción

final public function MongoDB\BSON\ObjectId::jsonSerialize(): mixed

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve datos que pueden ser serializados por json_encode() para producir una representación JSON extendida de MongoDB\BSON\ObjectId.

> Nota: La salida es coherente con la función MongoDB\BSON\toJSON(), que utiliza el formato JSON extendido específico del controlador. Esto no corresponde necesariamente a las representaciones JSON extendidas » relajadas o » canónicas utilizadas por MongoDB\BSON\toRelaxedExtendedJSON() y MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- JsonSerializable::jsonSerialize() - Especifica los datos que deben ser serializados en JSON
- json_encode() - Retorna la representación JSON de un valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Devuelve la representación en Canonical Extended JSON de un valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Devuelve la representación en Relaxed Extended JSON de un valor BSON
- » MongoDB JSON Extendido

# MongoDB\BSON\ObjectId::__toString

(mongodb >=1.0.0)

MongoDB\BSON\ObjectId::__toString — Devuelve la representación hexadecimal de este ObjectId

### Descripción

final public function MongoDB\BSON\ObjectId::__toString(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la representación hexadecimal de este ObjectId.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\BSON\ObjectId::__toString()

    <?php

    var_dump((string) new MongoDB\BSON\ObjectId());
    var_dump((string) new MongoDB\BSON\ObjectId('000000000000000000000001'));

    ?>

Resultado del ejemplo anterior es similar a:

    string(24) "56731b49da14d8747d701211"
    string(24) "000000000000000000000001"

### Ver también

- » La referencia ObjectId
- » El tipo BSON : ObjectId

## Tabla de contenidos

- MongoDB\BSON\ObjectId::__construct — Construye un nuevo ObjectId
- MongoDB\BSON\ObjectId::getTimestamp — Devuelve el componente de timestamp de ObjectId
- MongoDB\BSON\ObjectId::jsonSerialize — Devuelve una representación que puede ser convertida en JSON
- MongoDB\BSON\ObjectId::__toString — Devuelve la representación hexadecimal de este ObjectId

# La clase MongoDB\BSON\Regex

(mongodb >=1.0.0)

## Introducción

Tipo BSON para un patrón de expresión regular y » flag opcional.

> Nota: Este tipo BSON se utiliza principalmente durante la consulta de la base de datos. Alternativamente, el operador de consulta » $regex puede ser utilizado.

## Sinopsis de la Clase

final class MongoDB\BSON\Regex implements MongoDB\BSON\RegexInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Métodos */
final public function __construct(string `$pattern`, string `$flags` = "")
final public function getFlags(): string
final public function getPattern(): string
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Esta clase ya no implementa la interfaz Serializable.
PECL mongodb 1.12.0 | Implementa Stringable para PHP 8.0+.
PECL mongodb 1.3.0 | Implementa MongoDB\BSON\RegexInterface.
PECL mongodb 1.2.0 | Implementa Serializable y JsonSerializable.

# MongoDB\BSON\Regex::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Regex::__construct — Construye una nueva REGEX

### Descripción

final public function MongoDB\BSON\Regex::__construct(string `$pattern`, string `$flags` = "")

### Parámetros

`pattern` (string)
  La máscara de la expresión regular.

  > Nota: La máscara no debe estar rodeada de caracteres delimitadores.

`flags` (string)
  Los » flags de la expresión regular.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una excepción MongoDB\Driver\Exception\InvalidArgumentException si `pattern` o `flags` contiene un byte nulo.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.2.0 | El argumento `flags` es opcional y el valor por omisión es una cadena vacía. Los caracteres en el argumento `flags` serán ordenados alfabéticamente cuando se construya una Regex. Anteriormente, los caracteres se almacenaban en el orden proporcionado. MongoDB\Driver\Exception\InvalidArgumentException es lanzada si `pattern` o `flags` contiene un byte nulo. Anteriormente, los valores eran truncados en el primer byte nulo.

### Ejemplos

Ejemplo #1 MongoDB\BSON\Regex::__construct() ejemplo

    <?php

    $regex = new MongoDB\BSON\Regex('^foo', 'i');
    var_dump($regex);

    ?>

El ejemplo anterior mostrará:

    object(MongoDB\BSON\Regex)#1 (2) {
      ["pattern"]=>
      string(4) "^foo"
      ["flags"]=>
      string(1) "i"
    }

### Ver también

- » Los tipos BSON
- » Los flags soportados para las expresiones regulares

# MongoDB\BSON\Regex::getFlags

(mongodb >=1.0.0)

MongoDB\BSON\Regex::getFlags — Devuelve los flags de la REGEX

### Descripción

final public function MongoDB\BSON\Regex::getFlags(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve los flags de la REGEX.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo con BSON\Regex::getFlags()

    <?php

    $regex = new MongoDB\BSON\Regex('regex', 'i');
    var_dump($regex->getFlags());

    ?>

Resultado del ejemplo anterior es similar a:

    string(1) "i"

### Ver también

- » Los tipos BSON
- » Los flags soportados de las expresiones regulares

# MongoDB\BSON\Regex::getPattern

(mongodb >=1.0.0)

MongoDB\BSON\Regex::getPattern — Devuelve la máscara del REGEX

### Descripción

final public function MongoDB\BSON\Regex::getPattern(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la máscara del REGEX.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo con BSON\Regex::getPattern()

    <?php

    $regex = new MongoDB\BSON\Regex('regex', 'i');
    var_dump($regex->getPattern());

    ?>

Resultado del ejemplo anterior es similar a:

    string(5) "regex"

### Ver también

- » Los tipos BSON

# MongoDB\BSON\Regex::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Regex::jsonSerialize — Devuelve una representación que puede ser convertida en JSON

### Descripción

final public function MongoDB\BSON\Regex::jsonSerialize(): mixed

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve datos que pueden ser serializados por json_encode() para producir una representación JSON extendida de MongoDB\BSON\Regex.

> Nota: La salida es coherente con la función MongoDB\BSON\toJSON(), que utiliza el formato JSON extendido específico del controlador. Esto no corresponde necesariamente a las representaciones JSON extendidas » relajadas o » canónicas utilizadas por MongoDB\BSON\toRelaxedExtendedJSON() y MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- JsonSerializable::jsonSerialize() - Especifica los datos que deben ser serializados en JSON
- json_encode() - Retorna la representación JSON de un valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Devuelve la representación en Canonical Extended JSON de un valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Devuelve la representación en Relaxed Extended JSON de un valor BSON
- » MongoDB JSON Extendido

# MongoDB\BSON\Regex::__toString

(mongodb >=1.0.0)

MongoDB\BSON\Regex::__toString — Devuelve el string que representa esta REGEX

### Descripción

final public function MongoDB\BSON\Regex::__toString(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el string que representa esta REGEX.

### Ejemplos

Ejemplo #1 Ejemplo con BSON\Regex::__toString()

    <?php

    $regex = new MongoDB\BSON\Regex('regex', 'i');
    var_dump((string) $regex);

    ?>

Resultado del ejemplo anterior es similar a:

    string(8) "/regex/i"

### Ver también

- » Los tipos BSON

## Tabla de contenidos

- MongoDB\BSON\Regex::__construct — Construye una nueva REGEX
- MongoDB\BSON\Regex::getFlags — Devuelve los flags de la REGEX
- MongoDB\BSON\Regex::getPattern — Devuelve la máscara del REGEX
- MongoDB\BSON\Regex::jsonSerialize — Devuelve una representación que puede ser convertida en JSON
- MongoDB\BSON\Regex::__toString — Devuelve el string que representa esta REGEX

# La clase MongoDB\BSON\Timestamp

(mongodb >=1.0.0)

## Introducción

Representa un » timestamp BSON. El valor consiste en un timestamp de 4 bytes (es decir, segundos desde la época) y un incremento de 4 bytes.

> Nota: Este es un tipo interno de MongoDB utilizado para replicación y particionamiento. No está destinado al almacenamiento general de fechas (debería usarse MongoDB\BSON\UTCDateTime en su lugar).

## Sinopsis de la Clase

final class MongoDB\BSON\Timestamp implements MongoDB\BSON\TimestampInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Métodos */
final public function __construct(int `$increment`, int `$timestamp`)
final public function getIncrement(): int
final public function getTimestamp(): int
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Esta clase ya no implementa la interfaz Serializable.
PECL mongodb 1.12.0 | Implementa Stringable para PHP 8.0+.
PECL mongodb 1.3.0 | Implementa MongoDB\BSON\TimestampInterface.
PECL mongodb 1.2.0 | Implementa Serializable y JsonSerializable.

# MongoDB\BSON\Timestamp::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Timestamp::__construct — Construye una nueva marca de tiempo (Timestamp)

### Descripción

final public function MongoDB\BSON\Timestamp::__construct(int `$increment`, int `$timestamp`)

### Parámetros

`increment` (int)
  Entero de 32 bits que denota el ordinal de incremento para operaciones dentro de un mismo segundo.
`timestamp` (int)
  Entero de 32 bits que denota los segundos transcurridos desde la época Unix.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\BSON\Timestamp::__construct()

    <?php

    $timestamp = new MongoDB\BSON\Timestamp(1234, 5678);

    ?>

El ejemplo anterior mostrará:

    object(MongoDB\BSON\Timestamp)#1 (2) {
      ["increment"]=>
      int(1234)
      ["timestamp"]=>
      int(5678)
    }

### Ver también

- » Tipos BSON: Marcas de tiempo (Timestamps)

# MongoDB\BSON\Timestamp::getIncrement

(mongodb >=1.3.0)

MongoDB\BSON\Timestamp::getIncrement — Devuelve el componente de incremento de este Timestamp

### Descripción

final public function MongoDB\BSON\Timestamp::getIncrement(): int

El componente de incremento de un Timestamp son sus 32 bits menos significativos, que denotan el ordinal de incremento para operaciones dentro de un mismo segundo. Este valor se lee como un entero sin signo de 32 bits con orden de bytes big-endian.

> Nota: Dado que el tipo entero de PHP es firmado, algunos valores devueltos por este método pueden aparecer como enteros negativos en las plataformas de 32 bits. El formateador "%u" de sprintf() puede ser utilizado para obtener una representación en forma de string del valor decimal no firmado.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el componente de incremento de este Timestamp.

Advertencia

En sistemas de 32 bits este método puede devolver un número negativo. Aunque las partes de incremento y marca de tiempo del tipo BSON timestamp consisten en dos valores sin signo de 32 bits, PHP no puede representarlos en plataformas de 32 bits.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- » Tipos BSON: Marcas de tiempo

# MongoDB\BSON\Timestamp::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\Timestamp::getTimestamp — Devuelve el componente de marca temporal de este Timestamp

### Descripción

final public function MongoDB\BSON\Timestamp::getTimestamp(): int

El componente de marca temporal de un Timestamp es sus 32 bits más significativos, que denota el número de segundos transcurridos desde la época Unix. Este valor se lee como un entero sin signo de 32 bits con orden de bytes big-endian.

> Nota: Dado que el tipo entero de PHP es firmado, algunos valores devueltos por este método pueden aparecer como enteros negativos en las plataformas de 32 bits. El formateador "%u" de sprintf() puede ser utilizado para obtener una representación en forma de string del valor decimal no firmado.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el componente de marca temporal de este Timestamp.

Advertencia

En sistemas de 32 bits este método puede devolver un número negativo. Aunque las partes de incremento y marca temporal del tipo de marca temporal BSON consisten en dos valores enteros sin signo de 32 bits, PHP no puede representarlos en plataformas de 32 bits.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- » Tipos BSON: Marcas temporales

# MongoDB\BSON\Timestamp::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Timestamp::jsonSerialize — Devuelve una representación que puede convertirse a JSON

### Descripción

final public function MongoDB\BSON\Timestamp::jsonSerialize(): mixed

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve datos que pueden ser serializados por json_encode() para producir una representación JSON extendida de la MongoDB\BSON\Timestamp.

> Nota: La salida es coherente con la función MongoDB\BSON\toJSON(), que utiliza el formato JSON extendido específico del controlador. Esto no corresponde necesariamente a las representaciones JSON extendidas » relajadas o » canónicas utilizadas por MongoDB\BSON\toRelaxedExtendedJSON() y MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- JsonSerializable::jsonSerialize() - Especifica los datos que deben ser serializados en JSON
- json_encode() - Retorna la representación JSON de un valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Devuelve la representación en Canonical Extended JSON de un valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Devuelve la representación en Relaxed Extended JSON de un valor BSON
- » MongoDB Extended JSON

# MongoDB\BSON\Timestamp::__toString

(mongodb >=1.0.0)

MongoDB\BSON\Timestamp::__toString — Devuelve la representación en string de este Timestamp

### Descripción

final public function MongoDB\BSON\Timestamp::__toString(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la representación en string de este Timestamp.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\BSON\Timestamp::__toString()

    <?php

    $timestamp = new MongoDB\BSON\Timestamp(1234, 5678);
    var_dump((string) $timestamp);

    ?>

Resultado del ejemplo anterior es similar a:

    string(11) "[1234:5678]"

### Ver también

- » Tipos BSON: Timestamps

## Tabla de contenidos

- MongoDB\BSON\Timestamp::__construct — Construye una nueva marca de tiempo (Timestamp)
- MongoDB\BSON\Timestamp::getIncrement — Devuelve el componente de incremento de este Timestamp
- MongoDB\BSON\Timestamp::getTimestamp — Devuelve el componente de marca temporal de este Timestamp
- MongoDB\BSON\Timestamp::jsonSerialize — Devuelve una representación que puede convertirse a JSON
- MongoDB\BSON\Timestamp::__toString — Devuelve la representación en string de este Timestamp

# La clase MongoDB\BSON\UTCDateTime

(mongodb >=1.0.0)

## Introducción

Representa una » fecha BSON. El valor es un entero de 64 bits que representa el número de milisegundos transcurridos desde la época Unix (1 de enero de 1970). Los valores negativos representan fechas anteriores a 1970.

## Sinopsis de la Clase

final class MongoDB\BSON\UTCDateTime implements MongoDB\BSON\UTCDateTimeInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Métodos */
final public function __construct(int|MongoDB\BSON\Int64|DateTimeInterface|null `$milliseconds` = `null`)
final public function jsonSerialize(): mixed
final public function toDateTime(): DateTime
final public function toDateTimeImmutable(): DateTimeImmutable
final public function __toString(): string
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Esta clase ya no implementa la interfaz Serializable.
PECL mongodb 1.12.0 | Implementa Stringable para PHP 8.0+.
PECL mongodb 1.3.0 | Implementa MongoDB\BSON\UTCDateTimeInterface.
PECL mongodb 1.2.0 | Implementa Serializable y JsonSerializable.

# MongoDB\BSON\UTCDateTime::__construct

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::__construct — Construye un nuevo objeto UTCDateTime

### Descripción

final public function MongoDB\BSON\UTCDateTime::__construct(int|MongoDB\BSON\Int64|DateTimeInterface|null `$milliseconds` = `null`)

### Parámetros

`milliseconds` (int|MongoDB\BSON\Int64|DateTimeInterface|null)
  Número de milisegundos transcurridos desde la época Unix (1 de enero de 1970). Los valores negativos representan fechas anteriores a 1970. Este valor puede proporcionarse como un int de 64 bits. Para compatibilidad en sistemas de 32 bits, este parámetro también puede proporcionarse como un MongoDB\BSON\Int64. Si el argumento es un DateTimeInterface, el número de milisegundos transcurridos desde la época Unix se derivará de ese valor. Si este argumento es `null`, por omisión se utilizará la hora actual.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | El parámetro `milliseconds` ya no acepta un argumento de tipo string o float.
PECL mongodb 1.20.0 | El argumento `milliseconds` ahora acepta un objeto MongoDB\BSON\Int64 (para compatibilidad en plataformas de 32 bits). Especificar un string o float está obsoleto.
PECL mongodb 1.2.0 | El argumento `milliseconds` es opcional y por omisión es `null` (es decir, hora actual). El argumento también acepta un DateTimeInterface, que puede usarse para derivar el número de milisegundos transcurridos desde la época Unix. Anteriormente, solo se aceptaban tipos int, float y string.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\BSON\UTCDateTime::__construct()

    <?php

    var_dump(new MongoDB\BSON\UTCDateTime);

    var_dump(new MongoDB\BSON\UTCDateTime(new DateTime));

    var_dump(new MongoDB\BSON\UTCDateTime(1416445411987));

    ?>

Resultado del ejemplo anterior es similar a:

    object(MongoDB\BSON\UTCDateTime)#1 (1) {
      ["milliseconds"]=>
      string(13) "1484852905560"
    }
    object(MongoDB\BSON\UTCDateTime)#1 (1) {
      ["milliseconds"]=>
      string(13) "1484852905560"
    }
    object(MongoDB\BSON\UTCDateTime)#1 (1) {
      ["milliseconds"]=>
      string(13) "1416445411987"
    }

### Ver también

- » Tipos BSON: Fecha

# MongoDB\BSON\UTCDateTime::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\UTCDateTime::jsonSerialize — Devuelve una representación que puede convertirse a JSON

### Descripción

final public function MongoDB\BSON\UTCDateTime::jsonSerialize(): mixed

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve datos que pueden ser serializados por json_encode() para producir una representación JSON extendida de la MongoDB\BSON\UTCDateTime.

> Nota: La salida es coherente con la función MongoDB\BSON\toJSON(), que utiliza el formato JSON extendido específico del controlador. Esto no corresponde necesariamente a las representaciones JSON extendidas » relajadas o » canónicas utilizadas por MongoDB\BSON\toRelaxedExtendedJSON() y MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- JsonSerializable::jsonSerialize() - Especifica los datos que deben ser serializados en JSON
- json_encode() - Retorna la representación JSON de un valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Devuelve la representación en Canonical Extended JSON de un valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Devuelve la representación en Relaxed Extended JSON de un valor BSON
- » MongoDB Extended JSON

# MongoDB\BSON\UTCDateTime::toDateTime

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::toDateTime — Devuelve la representación DateTime de este UTCDateTime

### Descripción

final public function MongoDB\BSON\UTCDateTime::toDateTime(): DateTime

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la representación DateTime de este UTCDateTime. El DateTime devuelto utilizará la zona horaria UTC.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\BSON\UTCDatetime::toDateTime()

    <?php

    $utcdatetime = new MongoDB\BSON\UTCDateTime(1416445411987);
    $datetime = $utcdatetime->toDateTime();
    var_dump($datetime->format('r'));
    var_dump($datetime->format('U.u'));
    var_dump($datetime->getTimezone());

    ?>

Resultado del ejemplo anterior es similar a:

    string(31) "Thu, 20 Nov 2014 01:03:31 +0000"
    string(17) "1416445411.987000"
    object(DateTimeZone)#3 (2) {
      ["timezone_type"]=>
      int(1)
      ["timezone"]=>
      string(6) "+00:00"
    }

### Ver también

- MongoDB\BSON\UTCDateTime::toDateTimeImmutable() - Devuelve la representación DateTimeImmutable de este UTCDateTime
- » Tipos BSON: Fecha

# MongoDB\BSON\UTCDateTime::toDateTimeImmutable

(mongodb >=1.20.0)

MongoDB\BSON\UTCDateTime::toDateTimeImmutable — Devuelve la representación DateTimeImmutable de este UTCDateTime

### Descripción

final public function MongoDB\BSON\UTCDateTime::toDateTimeImmutable(): DateTimeImmutable

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la representación DateTimeImmutable de este UTCDateTime. El DateTimeImmutable devuelto utilizará la zona horaria UTC.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\BSON\UTCDatetime::toDateTimeImmutable()

    <?php

    $utcdatetime = new MongoDB\BSON\UTCDateTime(1416445411987);
    $datetime = $utcdatetime->toDateTimeImmutable();
    var_dump($datetime->format('r'));
    var_dump($datetime->format('U.u'));
    var_dump($datetime->getTimezone());

    ?>

Resultado del ejemplo anterior es similar a:

    string(31) "Thu, 20 Nov 2014 01:03:31 +0000"
    string(17) "1416445411.987000"
    object(DateTimeZone)#3 (2) {
      ["timezone_type"]=>
      int(1)
      ["timezone"]=>
      string(6) "+00:00"
    }

### Ver también

- MongoDB\BSON\UTCDateTime::toDateTime() - Devuelve la representación DateTime de este UTCDateTime
- » Tipos BSON: Fecha

# MongoDB\BSON\UTCDateTime::__toString

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::__toString — Devuelve la representación en forma de string de este UTCDateTime

### Descripción

final public function MongoDB\BSON\UTCDateTime::__toString(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la representación en forma de string de este UTCDateTime.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\BSON\UTCDateTime::__toString()

    <?php

    $utcdatetime = new MongoDB\BSON\UTCDateTime(1416445411987);
    var_dump((string) $utcdatetime);

    ?>

El ejemplo anterior mostrará:

    string(13) "1416445411987"

### Ver también

- » Tipos BSON: Fecha

## Tabla de contenidos

- MongoDB\BSON\UTCDateTime::__construct — Construye un nuevo objeto UTCDateTime
- MongoDB\BSON\UTCDateTime::jsonSerialize — Devuelve una representación que puede convertirse a JSON
- MongoDB\BSON\UTCDateTime::toDateTime — Devuelve la representación DateTime de este UTCDateTime
- MongoDB\BSON\UTCDateTime::toDateTimeImmutable — Devuelve la representación DateTimeImmutable de este UTCDateTime
- MongoDB\BSON\UTCDateTime::__toString — Devuelve la representación en forma de string de este UTCDateTime

# La interfaz MongoDB\BSON\Type

(mongodb >=1.0.0)

## Introducción

Interfaz base abstracta que no debe implementarse directamente.

## Sinopsis de la Interfaz

class MongoDB\BSON\Type {
}

Esta interfaz no tiene métodos. Su único propósito es ser la interfaz base para todas las clases de tipos BSON.

# La clase MongoDB\BSON\Persistable

(mongodb >=1.0.0)

## Introducción

Las clases pueden implementar esta interfaz para tener la posibilidad de utilizar los ODM automáticos (los objetos de mapeo de documentos) de esta extensión. Durante la serialización, la extensión inyectará una propiedad __pclass que contiene el nombre de la clase PHP en los datos devueltos por MongoDB\BSON\Serializable::bsonSerialize(). Durante la deserialización, la misma propiedad __pclass se utilizará para solicitar a la clase PHP (independientemente de la configuración type map) que se construya antes de que se invoque MongoDB\BSON\Unserializable::bsonUnserialize(). Ver Persistir datos para más información.

> Nota: Aunque MongoDB\BSON\Serializable::bsonSerialize() quiera devolver un array secuencial, la inyección de la propiedad __pclass hará que el objeto se serialice como documento BSON.

## Sinopsis de la Interfaz

class MongoDB\BSON\Persistable implements MongoDB\BSON\Unserializable, MongoDB\BSON\Serializable {
/* Métodos */
abstract public function bsonSerialize(): array|stdClass|MongoDB\BSON\Document
/* Métodos heredados */
abstract public function MongoDB\BSON\Serializable::bsonSerialize(): array|stdClass|MongoDB\BSON\Document|MongoDB\BSON\PackedArray
abstract public function MongoDB\BSON\Unserializable::bsonUnserialize(array `$data`): void
}

# MongoDB\BSON\Persistable::bsonSerialize

(mongodb >=1.0.0)

MongoDB\BSON\Persistable::bsonSerialize — Proporciona un array o un documento a serializar como BSON

### Descripción

abstract public function MongoDB\BSON\Persistable::bsonSerialize(): array|stdClass|MongoDB\BSON\Document

Se invoca durante la serialización del objeto en BSON. El método debe devolver un array, stdClass, o MongoDB\BSON\Document.

El valor devuelto será siempre serializado como documento BSON. El documento serializado incluirá un campo que contiene el nombre de la clase del objeto. Por esta razón, no es posible devolver una instancia de MongoDB\BSON\PackedArray en este método.

Se recomienda incluir una propiedad _id (por ejemplo un MongoDB\BSON\ObjectId inicializado en el constructor) al devolver datos para un documento BSON raíz. En ausencia de una propiedad _id, la extensión o el servidor generará un MongoDB\BSON\ObjectId para las operaciones de inserción o upsert, respectivamente.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array, stdClass, o MongoDB\BSON\Document a serializar como documento BSON.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Los tipos de retorno previamente declarados como provisionales ahora son aplicados.
PECL mongodb 1.17.0 | Este método puede ahora también devolver instancias de MongoDB\BSON\Document además de array y stdClass.

### Ver también

- MongoDB\BSON\Serializable::bsonSerialize() - Proporciona un array o documento para serializar como BSON
- MongoDB\BSON\Unserializable::bsonUnserialize() - Construye el objeto a partir de un array o documento BSON
- MongoDB\BSON\Persistable
- Persistir datos

## Tabla de contenidos

- MongoDB\BSON\Persistable::bsonSerialize — Proporciona un array o un documento a serializar como BSON

# La interfaz MongoDB\BSON\Serializable

(mongodb >=1.0.0)

## Introducción

Las clases que implementan esta interfaz pueden devolver datos para ser serializados como un array BSON o un documento BSON en lugar de las propiedades públicas del objeto.

## Sinopsis de la Interfaz

class MongoDB\BSON\Serializable implements MongoDB\BSON\Type {
/* Métodos */
abstract public function bsonSerialize(): array|stdClass|MongoDB\BSON\Document|MongoDB\BSON\PackedArray
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Los tipos de retorno previamente declarados como provisionales ahora son aplicados.
PECL mongodb 1.15.0 | Los tipos de retorno de los métodos son declarados como provisionales en PHP 8.0 y posteriores, lo que desencadena avisos de depreciación en el código que implementa esta interfaz sin declarar los tipos de retorno apropiados. El atributo `#[ReturnTypeWillChange]` puede ser añadido para ignorar la notificación de depreciación.

# MongoDB\BSON\Serializable::bsonSerialize

(mongodb >=1.0.0)

MongoDB\BSON\Serializable::bsonSerialize — Proporciona un array o documento para serializar como BSON

### Descripción

abstract public function MongoDB\BSON\Serializable::bsonSerialize(): array|stdClass|MongoDB\BSON\Document|MongoDB\BSON\PackedArray

Se invoca durante la serialización del objeto a BSON. El método debe devolver un array, stdClass, MongoDB\BSON\Document, o MongoDB\BSON\PackedArray.

Los documentos raíz (por ejemplo, un MongoDB\BSON\Serializable pasado a MongoDB\BSON\Document::fromPHP()) siempre se serializarán como un documento BSON. Para los valores de campo, los arrays asociativos y las instancias de stdClass se serializarán como un documento BSON y los arrays secuenciales (es decir, índices numéricos secuenciales que comienzan en `0`) se serializarán como un array BSON.

Se recomienda a los usuarios incluir una propiedad _id (por ejemplo, un MongoDB\BSON\ObjectId inicializado en el constructor) al devolver datos para un documento raíz BSON. En ausencia de una propiedad _id, la extensión o el servidor generará un MongoDB\BSON\ObjectId para operaciones de inserción o actualización (upsert), respectivamente.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array, stdClass, MongoDB\BSON\Document, o MongoDB\BSON\PackedArray que se serializará como un array o documento BSON.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Los tipos de retorno previamente declarados como provisionales ahora son aplicados.
PECL mongodb 1.17.0 | El tipo de retorno se cambió de array|object. En lugar de object, el tipo de retorno ahora especifica stdClass. Las clases que implementan esta interfaz deben modificarse para dejar de declarar un tipo de retorno object. Como el tipo de retorno es tentativo, se emite una advertencia de obsolescencia en PHP 8.1 y versiones posteriores. Además de los cambios anteriores, la extensión ahora también admite devolver instancias de MongoDB\BSON\Document y MongoDB\BSON\PackedArray. Tenga en cuenta que cualquier instancia de MongoDB\BSON\PackedArray devuelta se convierte silenciosamente en objetos cuando se almacenan como documentos raíz. Se almacenan como arrays cuando se utilizan como valor de campo incrustado.

### Ejemplos

Ejemplo #1 MongoDB\BSON\Serializable::bsonSerialize() que devuelve un array asociativo para documento raíz

    <?php

    class MyDocument implements MongoDB\BSON\Serializable
    {
        private $id;

        function __construct()
        {
            $this->id = new MongoDB\BSON\ObjectId;
        }

        function bsonSerialize(): array
        {
            return ['_id' => $this->id, 'foo' => 'bar'];
        }
    }

    echo MongoDB\BSON\Document::fromPHP(new MyDocument)->toRelaxedExtendedJSON(), "\n";

    ?>

Resultado del ejemplo anterior es similar a:

    { "_id" : { "$oid" : "56cccdcada14d8755a58c591" }, "foo" : "bar" }

Ejemplo #2 MongoDB\BSON\Serializable::bsonSerialize() que devuelve un array secuencial para documento raíz

    <?php

    class MyArray implements MongoDB\BSON\Serializable
    {
        function bsonSerialize(): array
        {
            return [1, 2, 3];
        }
    }

    echo MongoDB\BSON\Document::fromPHP(new MyArray)->toRelaxedExtendedJSON(), "\n";

    ?>

El ejemplo anterior mostrará:

    { "0" : 1, "1" : 2, "2" : 3 }

Ejemplo #3 MongoDB\BSON\Serializable::bsonSerialize() que devuelve un array asociativo para campo de documento

    <?php

    class MyDocument implements MongoDB\BSON\Serializable
    {
        function bsonSerialize(): array
        {
            return ['foo' => 'bar'];
        }
    }

    $value = ['document' => new MyDocument];

    echo MongoDB\BSON\Document::fromPHP($value)->toRelaxedExtendedJSON(), "\n";

    ?>

El ejemplo anterior mostrará:

    { "document" : { "foo" : "bar" } }

Ejemplo #4 MongoDB\BSON\Serializable::bsonSerialize() que devuelve un array secuencial para campo de documento

    <?php

    class MyArray implements MongoDB\BSON\Serializable
    {
        function bsonSerialize(): array
        {
            return [1, 2, 3];
        }
    }

    $value = ['array' => new MyArray];

    echo MongoDB\BSON\Document::fromPHP($value)->toRelaxedExtendedJSON(), "\n";

    ?>

El ejemplo anterior mostrará:

    { "array" : [ 1, 2, 3 ] }

### Ver también

- MongoDB\BSON\Unserializable::bsonUnserialize() - Construye el objeto a partir de un array o documento BSON
- MongoDB\BSON\Persistable
- Persistir datos

## Tabla de contenidos

- MongoDB\BSON\Serializable::bsonSerialize — Proporciona un array o documento para serializar como BSON

# La interfaz MongoDB\BSON\Unserializable

(mongodb >=1.0.0)

## Introducción

Las clases que implementan esta interfaz pueden especificarse en un mapa de tipos para deserializar arrays y documentos BSON (tanto raíz como incrustados).

## Sinopsis de la Interfaz

class MongoDB\BSON\Unserializable {
/* Métodos */
abstract public function bsonUnserialize(array `$data`): void
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Los tipos de retorno previamente declarados como provisionales ahora son aplicados.
PECL mongodb 1.15.0 | Los tipos de retorno de los métodos son declarados como provisionales en PHP 8.0 y posteriores, lo que desencadena avisos de depreciación en el código que implementa esta interfaz sin declarar los tipos de retorno apropiados. El atributo `#[ReturnTypeWillChange]` puede ser añadido para ignorar la notificación de depreciación.

# MongoDB\BSON\Unserializable::bsonUnserialize

(mongodb >=1.0.0)

MongoDB\BSON\Unserializable::bsonUnserialize — Construye el objeto a partir de un array o documento BSON

### Descripción

abstract public function MongoDB\BSON\Unserializable::bsonUnserialize(array `$data`): void

Se invoca durante la deserialización del objeto desde BSON. Las propiedades del array o documento BSON se pasarán a este método como un array.

Recuerde verificar la existencia de una propiedad _id al procesar datos de un documento BSON.

> Nota: Este método actúa como el constructor del objeto. El método __construct() no será llamado después de este método.

### Parámetros

`data` (array)
  Propiedades dentro del array o documento BSON.

### Valores devueltos

El valor de retorno de este método se ignora.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Los tipos de retorno previamente declarados como provisionales ahora son aplicados.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\BSON\Unserializable::bsonUnserialize()

    <?php

    class MyDocument implements MongoDB\BSON\Unserializable
    {
        private $data = [];

        function bsonUnserialize(array $data): void
        {
            $this->data = $data;
        }
    }

    $bson = MongoDB\BSON\Document::fromJSON('{ "foo": "bar" }');

    var_dump($bson->toPHP(['root' => 'MyDocument']));

    ?>

El ejemplo anterior mostrará:

    object(MyDocument)#1 (1) {
      ["data":"MyDocument":private]=>
      array(1) {
        ["foo"]=>
        string(3) "bar"
      }
    }

### Ver también

- MongoDB\BSON\Serializable::bsonSerialize() - Proporciona un array o documento para serializar como BSON
- MongoDB\BSON\Persistable
- Persistir datos

## Tabla de contenidos

- MongoDB\BSON\Unserializable::bsonUnserialize — Construye el objeto a partir de un array o documento BSON

# La interfaz MongoDB\BSON\BinaryInterface

(mongodb >=1.3.0)

## Introducción

Esta interfaz es implementada por MongoDB\BSON\Binary para ser utilizada como tipo de argumento, de retorno o de propiedad en las clases de usuario.

## Sinopsis de la Clase

class MongoDB\BSON\BinaryInterface {
/* Métodos */
abstract public function getData(): string
abstract public function getType(): int
abstract public function __toString(): string
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Los tipos de retorno previamente declarados como provisionales ahora son aplicados.
PECL mongodb 1.15.0 | Los tipos de retorno de los métodos son declarados como provisionales en PHP 8.0 y posteriores, lo que desencadena avisos de depreciación en el código que implementa esta interfaz sin declarar los tipos de retorno apropiados. El atributo `#[ReturnTypeWillChange]` puede ser añadido para ignorar la notificación de depreciación.

# MongoDB\BSON\BinaryInterface::getData

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::getData — Devuelve los datos de BinaryInterface

### Descripción

abstract public function MongoDB\BSON\BinaryInterface::getData(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve los datos de BinaryInterface.

### Ver también

- MongoDB\BSON\Binary::getData() - Devuelve los datos de Binary

# MongoDB\BSON\BinaryInterface::getType

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::getType — Devuelve el tipo de BinaryInterface

### Descripción

abstract public function MongoDB\BSON\BinaryInterface::getType(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el tipo de BinaryInterface.

### Ver también

- MongoDB\BSON\Binary::getType() - Devuelve el tipo de Binary

# MongoDB\BSON\BinaryInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::__toString — Devuelve los datos de BinaryInterface

### Descripción

abstract public function MongoDB\BSON\BinaryInterface::__toString(): string

Este método es un alias de: MongoDB\BSON\BinaryInterface::getData().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve los datos de BinaryInterface.

### Ver también

- MongoDB\BSON\BinaryInterface::getData() - Devuelve los datos de BinaryInterface
- MongoDB\BSON\Binary::__toString() - Devuelve los datos de Binary

## Tabla de contenidos

- MongoDB\BSON\BinaryInterface::getData — Devuelve los datos de BinaryInterface
- MongoDB\BSON\BinaryInterface::getType — Devuelve el tipo de BinaryInterface
- MongoDB\BSON\BinaryInterface::__toString — Devuelve los datos de BinaryInterface

# La interfaz MongoDB\BSON\Decimal128Interface

(mongodb >=1.3.0)

## Introducción

Esta interfaz es implementada por MongoDB\BSON\Decimal128 para ser utilizada como tipo de argumento, de retorno o de propiedad en las clases de usuario.

## Sinopsis de la Clase

class MongoDB\BSON\Decimal128Interface {
/* Métodos */
abstract public function __toString(): string
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Los tipos de retorno previamente declarados como provisionales ahora son aplicados.
PECL mongodb 1.15.0 | Los tipos de retorno de los métodos son declarados como provisionales en PHP 8.0 y posteriores, lo que desencadena avisos de depreciación en el código que implementa esta interfaz sin declarar los tipos de retorno apropiados. El atributo `#[ReturnTypeWillChange]` puede ser añadido para ignorar la notificación de depreciación.

# MongoDB\BSON\Decimal128Interface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\Decimal128Interface::__toString — Devuelve una representación en string de Decimal128Interface

### Descripción

abstract public function MongoDB\BSON\Decimal128Interface::__toString(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una representación en string de Decimal128Interface.

### Ver también

- MongoDB\BSON\Decimal128::__toString() - Devuelve la representación en forma de string de Decimal128

## Tabla de contenidos

- MongoDB\BSON\Decimal128Interface::__toString — Devuelve una representación en string de Decimal128Interface

# La interfaz MongoDB\BSON\JavascriptInterface

(mongodb >=1.3.0)

## Introducción

Esta interfaz es implementada por MongoDB\BSON\Javascript para ser utilizada como tipo de argumento, de retorno o de propiedad en las clases de usuario.

## Sinopsis de la Clase

class MongoDB\BSON\JavascriptInterface {
/* Métodos */
abstract public function getCode(): string
abstract public function getScope(): ?object
abstract public function __toString(): string
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Los tipos de retorno previamente declarados como provisionales ahora son aplicados.
PECL mongodb 1.15.0 | Los tipos de retorno de los métodos son declarados como provisionales en PHP 8.0 y posteriores, lo que desencadena avisos de depreciación en el código que implementa esta interfaz sin declarar los tipos de retorno apropiados. El atributo `#[ReturnTypeWillChange]` puede ser añadido para ignorar la notificación de depreciación.

# MongoDB\BSON\JavascriptInterface::getCode

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::getCode — Devuelve el código de JavascriptInterface

### Descripción

abstract public function MongoDB\BSON\JavascriptInterface::getCode(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el código de JavascriptInterface.

### Ver también

- MongoDB\BSON\Javascript::getCode() - Devuelve el código Javascript

# MongoDB\BSON\JavascriptInterface::getScope

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::getScope — Devuelve el documento de ámbito de JavascriptInterface

### Descripción

abstract public function MongoDB\BSON\JavascriptInterface::getScope(): ?object

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el documento de ámbito de JavascriptInterface.

### Ver también

- MongoDB\BSON\Javascript::getScope() - Devuelve el documento de ámbito de Javascript

# MongoDB\BSON\JavascriptInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::__toString — Devuelve el código de JavascriptInterface

### Descripción

abstract public function MongoDB\BSON\JavascriptInterface::__toString(): string

Este método es un alias de: MongoDB\BSON\JavascriptInterface::getCode().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el código de JavascriptInterface.

### Ver también

- MongoDB\BSON\JavascriptInterface::getCode() - Devuelve el código de JavascriptInterface
- MongoDB\BSON\Javascript::__toString() - Devuelve el código Javascript

## Tabla de contenidos

- MongoDB\BSON\JavascriptInterface::getCode — Devuelve el código de JavascriptInterface
- MongoDB\BSON\JavascriptInterface::getScope — Devuelve el documento de ámbito de JavascriptInterface
- MongoDB\BSON\JavascriptInterface::__toString — Devuelve el código de JavascriptInterface

# La interfaz MongoDB\BSON\MaxKeyInterface

(mongodb >=1.3.0)

## Introducción

Esta interfaz es implementada por MongoDB\BSON\MaxKey para ser utilizada como tipo de argumento, de retorno o de propiedad en las clases de usuario.

## Sinopsis de la Clase

class MongoDB\BSON\MaxKeyInterface {
}

Esta interfaz no contiene métodos.

# La interfaz MongoDB\BSON\MinKeyInterface

(mongodb >=1.3.0)

## Introducción

Esta interfaz es implementada por MongoDB\BSON\MinKey para ser utilizada como tipo de argumento, de retorno o de propiedad en las clases de usuario.

## Sinopsis de la Clase

class MongoDB\BSON\MinKeyInterface {
}

Esta interfaz no contiene métodos.

# La interfaz MongoDB\BSON\ObjectIdInterface

(mongodb >=1.3.0)

## Introducción

Esta interfaz es implementada por MongoDB\BSON\ObjectId para ser utilizada como tipo de argumento, de retorno o de propiedad en las clases de usuario.

## Sinopsis de la Clase

class MongoDB\BSON\ObjectIdInterface {
/* Métodos */
abstract public function getTimestamp(): int
abstract public function __toString(): string
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Los tipos de retorno previamente declarados como provisionales ahora son aplicados.
PECL mongodb 1.15.0 | Los tipos de retorno de los métodos son declarados como provisionales en PHP 8.0 y posteriores, lo que desencadena avisos de depreciación en el código que implementa esta interfaz sin declarar los tipos de retorno apropiados. El atributo `#[ReturnTypeWillChange]` puede ser añadido para ignorar la notificación de depreciación.

# MongoDB\BSON\ObjectIdInterface::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\ObjectIdInterface::getTimestamp — Devuelve el componente de timestamp de ObjectIdInterface

### Descripción

abstract public function MongoDB\BSON\ObjectIdInterface::getTimestamp(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el componente de timestamp de ObjectIdInterface.

### Ver también

- MongoDB\BSON\ObjectId::getTimestamp() - Devuelve el componente de timestamp de ObjectId

# MongoDB\BSON\ObjectIdInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\ObjectIdInterface::__toString — Devuelve la representación hexadecimal de ObjectIdInterface

### Descripción

abstract public function MongoDB\BSON\ObjectIdInterface::__toString(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la representación hexadecimal de ObjectIdInterface.

### Ver también

- MongoDB\BSON\ObjectId::__toString() - Devuelve la representación hexadecimal de este ObjectId

## Tabla de contenidos

- MongoDB\BSON\ObjectIdInterface::getTimestamp — Devuelve el componente de timestamp de ObjectIdInterface
- MongoDB\BSON\ObjectIdInterface::__toString — Devuelve la representación hexadecimal de ObjectIdInterface

# La interfaz MongoDB\BSON\RegexInterface

(mongodb >=1.3.0)

## Introducción

Esta interfaz es implementada por MongoDB\BSON\Regex para ser utilizada como tipo de argumento, de retorno o de propiedad en las clases de usuario.

## Sinopsis de la Clase

class MongoDB\BSON\RegexInterface {
/* Métodos */
abstract public function getFlags(): string
abstract public function getPattern(): string
abstract public function __toString(): string
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Los tipos de retorno previamente declarados como provisionales ahora son aplicados.
PECL mongodb 1.15.0 | Los tipos de retorno de los métodos son declarados como provisionales en PHP 8.0 y posteriores, lo que desencadena avisos de depreciación en el código que implementa esta interfaz sin declarar los tipos de retorno apropiados. El atributo `#[ReturnTypeWillChange]` puede ser añadido para ignorar la notificación de depreciación.

# MongoDB\BSON\RegexInterface::getFlags

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::getFlags — Devuelve los flags de RegexInterface

### Descripción

abstract public function MongoDB\BSON\RegexInterface::getFlags(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve los flags de RegexInterface.

### Ver también

- MongoDB\BSON\Regex::getFlags() - Devuelve los flags de la REGEX

# MongoDB\BSON\RegexInterface::getPattern

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::getPattern — Devuelve el patrón de RegexInterface

### Descripción

abstract public function MongoDB\BSON\RegexInterface::getPattern(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el patrón de RegexInterface.

### Ver también

- MongoDB\BSON\Regex::getPattern() - Devuelve la máscara del REGEX

# MongoDB\BSON\RegexInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::__toString — Devuelve la representación en forma de string de esta RegexInterface

### Descripción

abstract public function MongoDB\BSON\RegexInterface::__toString(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la representación en forma de string de esta RegexInterface.

### Ver también

- MongoDB\BSON\Regex::__toString() - Devuelve el string que representa esta REGEX

## Tabla de contenidos

- MongoDB\BSON\RegexInterface::getFlags — Devuelve los flags de RegexInterface
- MongoDB\BSON\RegexInterface::getPattern — Devuelve el patrón de RegexInterface
- MongoDB\BSON\RegexInterface::__toString — Devuelve la representación en forma de string de esta RegexInterface

# La interfaz `MongoDB\BSON\TimestampInterface`

(mongodb >=1.3.0)

## Introducción

Esta interfaz es implementada por MongoDB\BSON\Timestamp para ser utilizada como un parámetro, retorno o tipo de propiedad en clases de usuario.

## Sinopsis de la Clase

class MongoDB\BSON\TimestampInterface {
/* Métodos */
abstract public function getIncrement(): int
abstract public function getTimestamp(): int
abstract public function __toString(): string
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Los tipos de retorno previamente declarados como provisionales ahora son aplicados.
PECL mongodb 1.15.0 | Los tipos de retorno de los métodos son declarados como provisionales en PHP 8.0 y posteriores, lo que desencadena avisos de depreciación en el código que implementa esta interfaz sin declarar los tipos de retorno apropiados. El atributo `#[ReturnTypeWillChange]` puede ser añadido para ignorar la notificación de depreciación.

# MongoDB\BSON\TimestampInterface::getIncrement

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::getIncrement — Devuelve el componente de incremento de este TimestampInterface

### Descripción

abstract public function MongoDB\BSON\TimestampInterface::getIncrement(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el componente de incremento de este TimestampInterface.

Advertencia

En sistemas de 32 bits este método puede devolver un número negativo. Aunque las partes de incremento y marca de tiempo del tipo BSON timestamp consisten en dos valores de 32 bits sin signo, PHP no puede representar estos en plataformas de 32 bits.

### Ver también

- MongoDB\BSON\Timestamp::getIncrement() - Devuelve el componente de incremento de este Timestamp

# MongoDB\BSON\TimestampInterface::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::getTimestamp — Devuelve el componente de marca de tiempo de este TimestampInterface

### Descripción

abstract public function MongoDB\BSON\TimestampInterface::getTimestamp(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el componente de marca de tiempo de este TimestampInterface.

Advertencia

En sistemas de 32 bits este método puede devolver un número negativo. Aunque las partes de incremento y marca de tiempo del tipo de marca de tiempo BSON consisten en dos valores de 32 bits sin signo, PHP no puede representarlos en plataformas de 32 bits.

### Ver también

- MongoDB\BSON\Timestamp::getTimestamp() - Devuelve el componente de marca temporal de este Timestamp

# MongoDB\BSON\TimestampInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::__toString — Devuelve la representación en string de este TimestampInterface

### Descripción

abstract public function MongoDB\BSON\TimestampInterface::__toString(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la representación en string de este TimestampInterface.

### Ver también

- MongoDB\BSON\Timestamp::__toString() - Devuelve la representación en string de este Timestamp

## Tabla de contenidos

- MongoDB\BSON\TimestampInterface::getIncrement — Devuelve el componente de incremento de este TimestampInterface
- MongoDB\BSON\TimestampInterface::getTimestamp — Devuelve el componente de marca de tiempo de este TimestampInterface
- MongoDB\BSON\TimestampInterface::__toString — Devuelve la representación en string de este TimestampInterface

# La interfaz MongoDB\BSON\UTCDateTimeInterface

(mongodb >=1.3.0)

## Introducción

Esta interfaz es implementada por MongoDB\BSON\UTCDateTime para ser utilizada como un parámetro, retorno, o tipo de propiedad en clases de usuario.

## Sinopsis de la Clase

class MongoDB\BSON\UTCDateTimeInterface {
/* Métodos */
abstract public function toDateTime(): DateTime
abstract public function toDateTimeImmutable(): DateTimeImmutable
abstract public function __toString(): string
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Los tipos de retorno previamente declarados como provisionales ahora son aplicados.
PECL mongodb 1.15.0 | Los tipos de retorno de los métodos son declarados como provisionales en PHP 8.0 y posteriores, lo que desencadena avisos de depreciación en el código que implementa esta interfaz sin declarar los tipos de retorno apropiados. El atributo `#[ReturnTypeWillChange]` puede ser añadido para ignorar la notificación de depreciación.

# MongoDB\BSON\UTCDateTimeInterface::toDateTime

(mongodb >=1.3.0)

MongoDB\BSON\UTCDateTimeInterface::toDateTime — Devuelve la representación DateTime de esta UTCDateTimeInterface

### Descripción

abstract public function MongoDB\BSON\UTCDateTimeInterface::toDateTime(): DateTime

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la representación DateTime de esta UTCDateTimeInterface. El DateTime devuelto debe usar la zona horaria UTC.

### Ver también

- MongoDB\BSON\UTCDateTime::toDateTime() - Devuelve la representación DateTime de este UTCDateTime

# MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable

(mongodb >=2.0.0)

MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable — Devuelve la representación DateTimeImmutable de esta interfaz UTCDateTimeInterface

### Descripción

abstract public function MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable(): DateTimeImmutable

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la representación DateTimeImmutable de esta interfaz UTCDateTimeInterface. El DateTimeImmutable devuelto utilizará la zona horaria UTC.

### Ver también

- MongoDB\BSON\UTCDateTime::toDateTimeImmutable() - Devuelve la representación DateTimeImmutable de este UTCDateTime

# MongoDB\BSON\UTCDateTimeInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\UTCDateTimeInterface::__toString — Devuelve la representación en string de esta UTCDateTimeInterface

### Descripción

abstract public function MongoDB\BSON\UTCDateTimeInterface::__toString(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la representación en string de esta UTCDateTimeInterface.

### Ver también

- MongoDB\BSON\UTCDateTime::__toString() - Devuelve la representación en forma de string de este UTCDateTime

## Tabla de contenidos

- MongoDB\BSON\UTCDateTimeInterface::toDateTime — Devuelve la representación DateTime de esta UTCDateTimeInterface
- MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable — Devuelve la representación DateTimeImmutable de esta interfaz UTCDateTimeInterface
- MongoDB\BSON\UTCDateTimeInterface::__toString — Devuelve la representación en string de esta UTCDateTimeInterface

# La clase MongoDB\BSON\DBPointer

(mongodb >=1.4.0)

## Introducción

El tipo BSON para el tipo "DBPointer". Este tipo BSON está deprecado, y esta clase no puede ser instanciada. Será creada a partir de un tipo BSON DBPointer durante la conversión BSON a PHP, y puede también ser convertida en BSON durante el almacenamiento de documentos en la base de datos.

## Sinopsis de la Clase

final class MongoDB\BSON\DBPointer implements MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Métodos */
final private function __construct()
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Esta clase ya no implementa la interfaz Serializable.
PECL mongodb 1.12.0 | Implementa Stringable para PHP 8.0+.

# MongoDB\BSON\DBPointer::__construct

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::__construct — Construye un nuevo DBPointer (no utilizado)

### Descripción

final private function MongoDB\BSON\DBPointer::__construct()

Los objetos MongoDB\BSON\DBPointer son creados a través de una conversión desde un tipo BSON obsoleto y no pueden ser construidos directamente.

### Parámetros

Esta función no contiene ningún parámetro.

### Ver también

- » Tipos BSON

# MongoDB\BSON\DBPointer::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::jsonSerialize — Devuelve una representación que puede ser convertida en JSON

### Descripción

final public function MongoDB\BSON\DBPointer::jsonSerialize(): mixed

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve datos que pueden ser serializados por json_encode() para producir una representación JSON extendida de MongoDB\BSON\DBPointer.

> Nota: La salida es coherente con la función MongoDB\BSON\toJSON(), que utiliza el formato JSON extendido específico del controlador. Esto no corresponde necesariamente a las representaciones JSON extendidas » relajadas o » canónicas utilizadas por MongoDB\BSON\toRelaxedExtendedJSON() y MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- JsonSerializable::jsonSerialize() - Especifica los datos que deben ser serializados en JSON
- json_encode() - Retorna la representación JSON de un valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Devuelve la representación en Canonical Extended JSON de un valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Devuelve la representación en Relaxed Extended JSON de un valor BSON
- » MongoDB JSON Extendido

# MongoDB\BSON\DBPointer::__toString

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::__toString — Devuelve un string vacío

### Descripción

final public function MongoDB\BSON\DBPointer::__toString(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un string vacío.

### Ver también

- » Tipos BSON

## Tabla de contenidos

- MongoDB\BSON\DBPointer::__construct — Construye un nuevo DBPointer (no utilizado)
- MongoDB\BSON\DBPointer::jsonSerialize — Devuelve una representación que puede ser convertida en JSON
- MongoDB\BSON\DBPointer::__toString — Devuelve un string vacío

# La clase MongoDB\BSON\Int64

(mongodb >=1.5.0)

## Introducción

Tipo BSON para un entero de 64 bits. Al decodificar BSON en datos PHP, esta clase se utiliza cuando un entero de 64 bits no puede ser representado como un entero PHP en plataformas de 32 bits. Estos objetos soportan los operadores aritméticos, a nivel de bits, y comparación sobrecargados.

Al trabajar con datos BSON sin tratar a través de las clases MongoDB\BSON\Document, MongoDB\BSON\PackedArray, y MongoDB\BSON\Iterator, cualquier entero de 64 bits será devuelto como una instancia de esta clase, independientemente de la plataforma y de la posibilidad de representar el valor como un entero PHP. Esto garantiza que los valores pueden ser recorridos sin cambiar el tipo.

Al codificar BSON, los objetos de esta clase serán convertidos en un tipo entero 64 bits, incluso cuando el valor podría caber en un entero de 32 bits. Esto permite almacenar explícitamente valores como enteros de 64 bits en BSON.

## Sinopsis de la Clase

final class MongoDB\BSON\Int64 implements MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Métodos */
final public function __construct(int|string `$value`)
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Esta clase ya no implementa la interfaz Serializable.
PECL mongodb 1.16.0 | Esta clase puede ahora ser instanciada en todas las plataformas. Se añade soporte para los operadores aritméticos, a nivel de bits, y de comparación sobrecargados.
PECL mongodb 1.12.0 | Implementa Stringable para PHP 8.0+.

# MongoDB\BSON\Int64::__construct

(mongodb >=1.5.0)

MongoDB\BSON\Int64::__construct — Construye un nuevo Int64

### Descripción

final public function MongoDB\BSON\Int64::__construct(int|string `$value`)

Crea una nueva instancia de MongoDB\BSON\Int64 para el valor entero dado.

### Parámetros

`value` (int|string)
  El valor a asignar a la instancia de Int64. Este valor puede ser proporcionado como int o string, siendo este último requerido en plataformas de 32 bits para representar valores de 64 bits.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.16.0 | Este método se hizo público para soportar la creación de instancias Int64 durante la manipulación de BSON sin tratar.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.
- Lanza una MongoDB\Driver\Exception\InvalidArgumentException si el string `value` no puede ser analizado como un entero de 64 bits.

### Ver también

- » Tipos BSON

# MongoDB\BSON\Int64::jsonSerialize

(mongodb >=1.5.0)

MongoDB\BSON\Int64::jsonSerialize — Devuelve una representación que puede ser convertida a JSON

### Descripción

final public function MongoDB\BSON\Int64::jsonSerialize(): mixed

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve datos que pueden ser serializados por json_encode() para producir una representación JSON extendida de MongoDB\BSON\Int64.

> Nota: La salida es concordante con la función MongoDB\BSON\toCanonicalExtendedJSON(), que utiliza el formato JSON extendido » canonical. Esto difiere de otras clases BDON, que utilizan el formato JSON extendido heredado del controlador específico (MongoDB\BSON\toJSON()), para asegurar que los valores enteros de 64 bits sean correctamente representados en plataformas de 32 bits.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- JsonSerializable::jsonSerialize() - Especifica los datos que deben ser serializados en JSON
- json_encode() - Retorna la representación JSON de un valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Devuelve la representación en Canonical Extended JSON de un valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Devuelve la representación en Relaxed Extended JSON de un valor BSON
- » MongoDB JSON Extendido

# MongoDB\BSON\Int64::__toString

(mongodb >=1.5.0)

MongoDB\BSON\Int64::__toString — Devuelve la representación en forma de string de Int64

### Descripción

final public function MongoDB\BSON\Int64::__toString(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la representación en forma de string de Int64.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\BSON\Int64::__toString()

    <?php

    $int64 = new MongoDB\BSON\Int64('9223372036854775807');

    var_dump((string) $int64);

    ?>

Resultado del ejemplo anterior es similar a:

    string(19) "9223372036854775807"

### Ver también

- » Tipos BSON

## Tabla de contenidos

- MongoDB\BSON\Int64::__construct — Construye un nuevo Int64
- MongoDB\BSON\Int64::jsonSerialize — Devuelve una representación que puede ser convertida a JSON
- MongoDB\BSON\Int64::__toString — Devuelve la representación en forma de string de Int64

# La clase MongoDB\BSON\Symbol

(mongodb >=1.4.0)

## Introducción

Tipo BSON para el tipo "Symbol". Este tipo BSON está deprecado, y esta clase no puede ser instanciada. Será creada a partir de un tipo BSON symbol al convertir BSON a PHP, y también puede ser convertida de vuelta a BSON al almacenar documentos en la base de datos.

## Sinopsis de la Clase

final class MongoDB\BSON\Symbol implements MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Métodos */
final private function __construct()
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Esta clase ya no implementa la interfaz Serializable.
PECL mongodb 1.12.0 | Implementa Stringable para PHP 8.0+.

# MongoDB\BSON\Symbol::__construct

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::__construct — Construir un nuevo Symbol (no utilizado)

### Descripción

final private function MongoDB\BSON\Symbol::__construct()

Los objetos de MongoDB\BSON\Symbol se crean mediante conversión desde un tipo BSON obsoleto y no pueden construirse directamente.

### Parámetros

Esta función no contiene ningún parámetro.

### Ver también

- » Tipos BSON

# MongoDB\BSON\Symbol::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::jsonSerialize — Devuelve una representación que puede convertirse a JSON

### Descripción

final public function MongoDB\BSON\Symbol::jsonSerialize(): mixed

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve datos que pueden ser serializados por json_encode() para producir una representación JSON extendida del MongoDB\BSON\Symbol.

> Nota: La salida es coherente con la función MongoDB\BSON\toJSON(), que utiliza el formato JSON extendido específico del controlador. Esto no corresponde necesariamente a las representaciones JSON extendidas » relajadas o » canónicas utilizadas por MongoDB\BSON\toRelaxedExtendedJSON() y MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- JsonSerializable::jsonSerialize() - Especifica los datos que deben ser serializados en JSON
- json_encode() - Retorna la representación JSON de un valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Devuelve la representación en Canonical Extended JSON de un valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Devuelve la representación en Relaxed Extended JSON de un valor BSON
- » MongoDB Extended JSON

# MongoDB\BSON\Symbol::__toString

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::__toString — Devuelve el Symbol como un string

### Descripción

final public function MongoDB\BSON\Symbol::__toString(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la representación en string de este Symbol.

### Ver también

- » Tipos BSON

## Tabla de contenidos

- MongoDB\BSON\Symbol::__construct — Construir un nuevo Symbol (no utilizado)
- MongoDB\BSON\Symbol::jsonSerialize — Devuelve una representación que puede convertirse a JSON
- MongoDB\BSON\Symbol::__toString — Devuelve el Symbol como un string

# La clase MongoDB\BSON\Undefined

(mongodb >=1.4.0)

## Introducción

Tipo BSON para el tipo "Undefined" (Indefinido). Este tipo BSON está deprecado, y esta clase no puede ser instanciada. Será creada a partir de un tipo BSON undefined al convertir BSON a PHP, y también puede ser convertido de vuelta a BSON al almacenar documentos en la base de datos.

## Sinopsis de la Clase

final class MongoDB\BSON\Undefined implements MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Métodos */
final private function __construct()
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Esta clase ya no implementa la interfaz Serializable.
PECL mongodb 1.12.0 | Implementa Stringable para PHP 8.0+.

# MongoDB\BSON\Undefined::__construct

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::__construct — Construye una nueva Undefined (no utilizada)

### Descripción

final private function MongoDB\BSON\Undefined::__construct()

Los objetos MongoDB\BSON\Undefined se crean mediante conversión desde un tipo BSON obsoleto y no pueden construirse directamente.

### Parámetros

Esta función no contiene ningún parámetro.

### Ver también

- » Tipos BSON

# MongoDB\BSON\Undefined::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::jsonSerialize — Devuelve una representación que puede convertirse a JSON

### Descripción

final public function MongoDB\BSON\Undefined::jsonSerialize(): mixed

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve datos que pueden ser serializados por json_encode() para producir una representación JSON extendida de la MongoDB\BSON\Undefined.

> Nota: La salida es coherente con la función MongoDB\BSON\toJSON(), que utiliza el formato JSON extendido específico del controlador. Esto no corresponde necesariamente a las representaciones JSON extendidas » relajadas o » canónicas utilizadas por MongoDB\BSON\toRelaxedExtendedJSON() y MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- JsonSerializable::jsonSerialize() - Especifica los datos que deben ser serializados en JSON
- json_encode() - Retorna la representación JSON de un valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Devuelve la representación en Canonical Extended JSON de un valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Devuelve la representación en Relaxed Extended JSON de un valor BSON
- » MongoDB Extended JSON

# MongoDB\BSON\Undefined::__toString

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::__toString — Devuelve una cadena vacía

### Descripción

final public function MongoDB\BSON\Undefined::__toString(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una cadena vacía.

### Ver también

- » Tipos BSON

## Tabla de contenidos

- MongoDB\BSON\Undefined::__construct — Construye una nueva Undefined (no utilizada)
- MongoDB\BSON\Undefined::jsonSerialize — Devuelve una representación que puede convertirse a JSON
- MongoDB\BSON\Undefined::__toString — Devuelve una cadena vacía

# Monitorización de clases y funciones de suscriptor

## Tabla de contenidos

- Funciones
- MongoDB\Driver\Monitoring\CommandFailedEvent
- MongoDB\Driver\Monitoring\CommandStartedEvent
- MongoDB\Driver\Monitoring\CommandSucceededEvent
- MongoDB\Driver\Monitoring\ServerChangedEvent
- MongoDB\Driver\Monitoring\ServerClosedEvent
- MongoDB\Driver\Monitoring\ServerOpeningEvent
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent
- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent
- MongoDB\Driver\Monitoring\TopologyChangedEvent
- MongoDB\Driver\Monitoring\TopologyClosedEvent
- MongoDB\Driver\Monitoring\TopologyOpeningEvent
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Monitoring\SDAMSubscriber
- MongoDB\Driver\Monitoring\Subscriber

# Funciones

# MongoDB\Driver\Monitoring\addSubscriber

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\addSubscriber — Registra un suscriptor de eventos de monitorización de forma global

### Descripción

function MongoDB\Driver\Monitoring\addSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void

Registra un suscriptor de eventos de monitorización de forma global. El suscriptor será notificado de todos los eventos en la extensión para cualquier Manager.

> Nota: Si el `subscriber` ya está registrado de forma global, esta función no realiza ninguna acción. Si el `subscriber` también está registrado con uno o más Managers, solo será notificado una vez de cada evento para cada Manager.

### Parámetros

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  Un suscriptor de eventos de monitorización para registrar de forma global.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Monitoring\removeSubscriber() - Deregistra un suscriptor de eventos de supervisión globalmente
- MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Manager::addSubscriber() - Registra un observador de eventos de monitoreo con este manager
- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\removeSubscriber

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\removeSubscriber — Deregistra un suscriptor de eventos de supervisión globalmente

### Descripción

function MongoDB\Driver\Monitoring\removeSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void

Deregistra un suscriptor de eventos de supervisión globalmente.

> Nota: Si el `subscriber` no está registrado globalmente, esta función no realiza ninguna acción.

### Parámetros

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  Un suscriptor de eventos de supervisión que se desregistrará globalmente.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Monitoring\addSubscriber() - Registra un suscriptor de eventos de monitorización de forma global
- MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Manager::removeSubscriber() - Elimina un observador de eventos de supervisión de este Manager
- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

## Tabla de contenidos

- MongoDB\Driver\Monitoring\addSubscriber — Registra un suscriptor de eventos de monitorización de forma global
- MongoDB\Driver\Monitoring\removeSubscriber — Deregistra un suscriptor de eventos de supervisión globalmente

# La clase MongoDB\Driver\Monitoring\CommandFailedEvent

(mongodb >=1.3.0)

## Introducción

La clase MongoDB\Driver\Monitoring\CommandFailedEvent contiene la información sobre una comando que ha fallado.

## Sinopsis de la Clase

final class MongoDB\Driver\Monitoring\CommandFailedEvent {
/* Propiedades */
public readonly string $host;
public readonly int $port;
public readonly string $commandName;
public readonly string $databaseName;
public readonly int $duration;
public readonly Exception $error;
public readonly object $reply;
public readonly string $operationId;
public readonly string $requestId;
public readonly ?MongoDB\BSON\ObjectId $serviceId;
public readonly ?int $serverConnectionId;
/* Métodos */
final public function getCommandName(): string
final public function getDatabaseName(): string
final public function getDurationMicros(): int
final public function getError(): Exception
final public function getHost(): string
final public function getOperationId(): string
final public function getPort(): int
final public function getReply(): object
final public function getRequestId(): string
final public function getServer(): MongoDB\Driver\Server
final public function getServerConnectionId(): ?int
final public function getServiceId(): ?MongoDB\BSON\ObjectId
}

## Propiedades

host
  El nombre del host del servidor que ejecutó el comando.
port
  El puerto del servidor que ejecutó el comando.
commandName
  El nombre del comando.
databaseName
  El nombre de la base de datos.
duration
  La duración del comando en microsegundos. La duración es un valor calculado que incluye el tiempo necesario para enviar el mensaje y recibir la respuesta del servidor.
error
  La excepción lanzada cuando el comando falló.
reply
  El documento de respuesta de error devuelto por el servidor.
operationId
  El identificador de operación. Puede usarse para vincular eventos entre sí, como en escrituras en bloque, que pueden despachar varios comandos.
requestId
  El identificador de la petición. Puede usarse para asociar este MongoDB\Driver\Monitoring\CommandFailedEvent con un MongoDB\Driver\Monitoring\CommandStartedEvent correspondiente.
serviceId
  El identificador de servicio, o `null` si el servidor no lo soporta (es decir, cuando no se utiliza el modo de balanceo de carga).
serverConnectionId
  El identificador de la conexión al servidor, o `null` si no está disponible.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.3.0 | Se añadieron propiedades públicas readonly. La propiedad duration reemplaza al método getDurationMicros().

# MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName — Devuelve el nombre de la orden

### Descripción

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName(): string

Devuelve el nombre de la orden (por ejemplo `"find"`, `"aggregate"`).

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el nombre de la orden.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName

(mongodb >=1.19.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName — Devuelve el nombre de la base de datos sobre la cual se ejecutó el comando

### Descripción

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la base de datos sobre la cual se ejecutó el comando.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros — Devuelve la duración de la orden en microsegundos

### Descripción

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros(): int

La duración de la orden es un valor calculado que incluye el tiempo para enviar el mensaje y recibir la respuesta del servidor.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la duración de la orden en microsegundos.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getError

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getError — Devuelve la excepción asociada al comando fallido

### Descripción

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getError(): Exception

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la Exception asociada al comando fallido.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getHost

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getHost — Devuelve el nombre de host del servidor para la orden

### Descripción

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getHost(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el nombre de host del servidor en el que se ejecutó la orden.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId — Devuelve el identificador de la operación de la orden

### Descripción

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId(): string

El ID de la operación es generado por la extensión y puede ser utilizado para ligar eventos juntos, como operaciones de escritura masiva, que pueden haber sido divididas en varias órdenes a nivel de protocolo.

> Nota: Dado que varias órdenes pueden compartir el mismo ID de operación, no es fiable utilizar este valor para asociar objetos de evento entre sí. El ID de petición devuelto por MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId() debería ser utilizado en su lugar.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el identificador de la operación de la orden.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId() - Devuelve el identificador de la operación de la orden
- MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId() - Devuelve el identificador de la petición de la orden
- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getPort

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getPort — Devuelve el puerto del servidor para la orden

### Descripción

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getPort(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el puerto del servidor en el cual la orden fue ejecutada.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\CommandFailedEvent::getReply

(mongodb >=1.5.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getReply — Devuelve el documento de respuesta del comando

### Descripción

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getReply(): object

El documento de respuesta será convertido de BSON a PHP utilizando las reglas de deserialización por omisión (por ejemplo, los documentos BSON serán convertidos en stdClass).

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el documento de respuesta del comando en forma de un objeto stdClass.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)
- Persistir datos

# MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId — Devuelve el identificador de la petición de la orden

### Descripción

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId(): string

El identificador de la petición es generado por la extensión y puede ser utilizado para asociar este MongoDB\Driver\Monitoring\CommandFailedEvent con un MongoDB\Driver\Monitoring\CommandStartedEvent anterior.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el identificador de la petición de la orden.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() - Devuelve el identificador de la solicitud de la orden
- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getServer — Devuelve el servidor en el cual se ejecutó el comando

Advertencia

Este método ha sido DEPRECADO a partir de la versión 1.20.0 de la extensión y ha sido eliminado en la versión 2.0. Las aplicaciones deben utilizar MongoDB\Driver\Monitoring\CommandFailedEvent::getHost() y MongoDB\Driver\Monitoring\CommandFailedEvent::getPort() en su lugar.

### Descripción

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getServer(): MongoDB\Driver\Server

Devuelve el MongoDB\Driver\Server en el cual se ejecutó el comando.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el MongoDB\Driver\Server en el cual se ejecutó el comando.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Este método ha sido eliminado.

### Ver también

- MongoDB\Driver\Monitoring\CommandStartedEvent::getServer() - Devuelve el servidor en el que se ejecutó el comando
- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId

(mongodb >=1.14.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId — Devuelve el identificador de conexión del servidor para la orden

### Descripción

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId(): ?int

Devuelve el identificador de conexión del servidor para la orden. El identificador de conexión del servidor es distinto del servidor (es decir, MongoDB\Driver\Monitoring\CommandFailedEvent::getServer()) y es devuelto en el campo "connectionId" de una respuesta de orden `hello` MongoDB 4.2+.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el identificador de conexión del servidor, o `null` si no está disponible.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId

(mongodb >=1.11.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId — Devuelve el identificador del servicio del equilibrador de carga para la comanda

### Descripción

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId(): ?MongoDB\BSON\ObjectId

Cuando el controlador está conectado a un clúster MongoDB a través de un equilibrador de carga, el identificador del servicio corresponde al campo `serviceId` en la respuesta de la comanda `hello`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el identificador del servicio del equilibrador de carga, o `null` si el controlador no está conectado a un equilibrador de carga.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

## Tabla de contenidos

- MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName — Devuelve el nombre de la orden
- MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName — Devuelve el nombre de la base de datos sobre la cual se ejecutó el comando
- MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros — Devuelve la duración de la orden en microsegundos
- MongoDB\Driver\Monitoring\CommandFailedEvent::getError — Devuelve la excepción asociada al comando fallido
- MongoDB\Driver\Monitoring\CommandFailedEvent::getHost — Devuelve el nombre de host del servidor para la orden
- MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId — Devuelve el identificador de la operación de la orden
- MongoDB\Driver\Monitoring\CommandFailedEvent::getPort — Devuelve el puerto del servidor para la orden
- MongoDB\Driver\Monitoring\CommandFailedEvent::getReply — Devuelve el documento de respuesta del comando
- MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId — Devuelve el identificador de la petición de la orden
- MongoDB\Driver\Monitoring\CommandFailedEvent::getServer — Devuelve el servidor en el cual se ejecutó el comando
- MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId — Devuelve el identificador de conexión del servidor para la orden
- MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId — Devuelve el identificador del servicio del equilibrador de carga para la comanda

# La clase MongoDB\Driver\Monitoring\CommandStartedEvent

(mongodb >=1.3.0)

## Introducción

La clase MongoDB\Driver\Monitoring\CommandStartedEvent contiene la información sobre una orden que ha comenzado.

## Sinopsis de la Clase

final class MongoDB\Driver\Monitoring\CommandStartedEvent {
/* Propiedades */
public readonly string $host;
public readonly int $port;
public readonly string $commandName;
public readonly string $databaseName;
public readonly object $command;
public readonly string $operationId;
public readonly string $requestId;
public readonly ?MongoDB\BSON\ObjectId $serviceId;
public readonly ?int $serverConnectionId;
/* Métodos */
final public function getCommand(): object
final public function getCommandName(): string
final public function getDatabaseName(): string
final public function getHost(): string
final public function getOperationId(): string
final public function getPort(): int
final public function getRequestId(): string
final public function getServer(): MongoDB\Driver\Server
final public function getServerConnectionId(): ?int
final public function getServiceId(): ?MongoDB\BSON\ObjectId
}

## Propiedades

host
  El nombre del host del servidor que ejecutó el comando.
port
  El puerto del servidor que ejecutó el comando.
commandName
  El nombre del comando.
databaseName
  El nombre de la base de datos.
command
  El documento del comando.
operationId
  El identificador de operación. Puede usarse para vincular eventos entre sí, como en escrituras en bloque, que pueden despachar varios comandos.
requestId
  El identificador de la petición. Puede usarse para asociar este MongoDB\Driver\Monitoring\CommandStartedEvent con un MongoDB\Driver\Monitoring\CommandSucceededEvent o MongoDB\Driver\Monitoring\CommandFailedEvent correspondiente.
serviceId
  El identificador de servicio, o `null` si el servidor no lo soporta (es decir, cuando no se utiliza el modo de balanceo de carga).
serverConnectionId
  El identificador de la conexión al servidor, o `null` si no está disponible.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.3.0 | Se añadieron propiedades públicas readonly.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand — Devuelve el documento de comando

### Descripción

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand(): object

El documento devuelto será convertido de BSON a PHP utilizando las reglas de deserialización por omisión (por ejemplo, los documentos BSON serán convertidos en stdClass).

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el documento de comando en forma de objeto stdClass.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)
- Persistir datos

# MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName — Devuelve el nombre del comando

### Descripción

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName(): string

Devuelve el nombre del comando (por ejemplo, `"find"`, `"aggregate"`).

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el nombre del comando.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName — Devuelve la base de datos sobre la cual se ejecutó el comando

### Descripción

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la base de datos sobre la cual se ejecutó el comando.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getHost

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getHost — Devuelve el nombre del host del servidor para el comando

### Descripción

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getHost(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el nombre del host del servidor en el que se ejecutó el comando.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId — Devuelve el identificador de la operación de la orden

### Descripción

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId(): string

El identificador de la operación es generado por la extensión y puede ser utilizado para vincular eventos juntos, tales como operaciones de escritura en masa, que pueden haber sido divididas en varias órdenes a nivel del protocolo.

> Nota: Dado que varias órdenes pueden compartir el mismo identificador de operación, no es fiable utilizar este valor para asociar objetos de evento entre sí. El identificador de la petición devuelto por MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() debería ser utilizado en su lugar.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el identificador de la operación de la orden.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId() - Devuelve el identificador de la operación de la orden
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId() - Devuelve el identificador de la operación de la orden
- MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() - Devuelve el identificador de la solicitud de la orden
- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getPort

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getPort — Devuelve el puerto del servidor para la orden

### Descripción

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getPort(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el puerto del servidor en el que se ejecutó la orden.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId — Devuelve el identificador de la solicitud de la orden

### Descripción

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId(): string

El identificador de la solicitud es generado por la extensión y puede ser utilizado para asociar este evento MongoDB\Driver\Monitoring\CommandStartedEvent con un MongoDB\Driver\Monitoring\CommandFailedEvent o MongoDB\Driver\Monitoring\CommandSucceededEvent posterior.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el identificador de la solicitud de la orden.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId() - Devuelve el identificador de la petición de la orden
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId() - Devuelve el identificador de la solicitud de la orden
- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getServer — Devuelve el servidor en el que se ejecutó el comando

Advertencia

Este método ha sido DEPRECADO a partir de la versión 1.20.0 de la extensión y ha sido eliminado en la versión 2.0. Las aplicaciones deben utilizar MongoDB\Driver\Monitoring\CommandStartedEvent::getHost() y MongoDB\Driver\Monitoring\CommandStartedEvent::getPort() en su lugar.

### Descripción

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getServer(): MongoDB\Driver\Server

Devuelve el MongoDB\Driver\Server en el que se ejecutó el comando.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el MongoDB\Driver\Server en el que se ejecutó el comando.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Este método ha sido eliminado.

### Ver también

- MongoDB\Driver\Monitoring\CommandFailedEvent::getServer() - Devuelve el servidor en el cual se ejecutó el comando
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer() - Devuelve el servidor en el cual el comando fue ejecutado
- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId

(mongodb >=1.14.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId — Devuelve el identificador de conexión del servidor para la orden

### Descripción

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId(): ?int

Devuelve el identificador de conexión del servidor para la orden. El identificador de conexión del servidor es distinto del servidor (es decir, MongoDB\Driver\Monitoring\CommandFailedEvent::getServer()) y es devuelto en el campo "connectionId" de una respuesta de orden `hello` MongoDB 4.2+.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el identificador de conexión del servidor, o `null` si no está disponible.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId

(mongodb >=1.11.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId — Devuelve el identificador del servicio del equilibrador de carga para la orden

### Descripción

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId(): ?MongoDB\BSON\ObjectId

Cuando el controlador está conectado a un clúster MongoDB a través de un equilibrador de carga, el identificador del servicio corresponde al campo `serviceId` en la respuesta de la orden `hello`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el identificador del servicio del equilibrador de carga, o `null` si el controlador no está conectado a un equilibrador de carga.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

## Tabla de contenidos

- MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand — Devuelve el documento de comando
- MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName — Devuelve el nombre del comando
- MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName — Devuelve la base de datos sobre la cual se ejecutó el comando
- MongoDB\Driver\Monitoring\CommandStartedEvent::getHost — Devuelve el nombre del host del servidor para el comando
- MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId — Devuelve el identificador de la operación de la orden
- MongoDB\Driver\Monitoring\CommandStartedEvent::getPort — Devuelve el puerto del servidor para la orden
- MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId — Devuelve el identificador de la solicitud de la orden
- MongoDB\Driver\Monitoring\CommandStartedEvent::getServer — Devuelve el servidor en el que se ejecutó el comando
- MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId — Devuelve el identificador de conexión del servidor para la orden
- MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId — Devuelve el identificador del servicio del equilibrador de carga para la orden

# La clase MongoDB\Driver\Monitoring\CommandSucceededEvent

(mongodb >=1.3.0)

## Introducción

La clase MongoDB\Driver\Monitoring\CommandSucceededEvent encapsula información sobre un comando exitoso.

## Sinopsis de la Clase

final class MongoDB\Driver\Monitoring\CommandSucceededEvent {
/* Propiedades */
public readonly string $host;
public readonly int $port;
public readonly string $commandName;
public readonly string $databaseName;
public readonly int $duration;
public readonly object $reply;
public readonly string $operationId;
public readonly string $requestId;
public readonly ?MongoDB\BSON\ObjectId $serviceId;
public readonly ?int $serverConnectionId;
/* Métodos */
final public function getCommandName(): string
final public function getDatabaseName(): string
final public function getDurationMicros(): int
final public function getHost(): string
final public function getOperationId(): string
final public function getPort(): int
final public function getReply(): object
final public function getRequestId(): string
final public function getServer(): MongoDB\Driver\Server
final public function getServerConnectionId(): ?int
final public function getServiceId(): ?MongoDB\BSON\ObjectId
}

## Propiedades

host
  El nombre del host del servidor que ejecutó el comando.
port
  El puerto del servidor que ejecutó el comando.
commandName
  El nombre del comando.
databaseName
  El nombre de la base de datos.
duration
  La duración del comando en microsegundos. La duración es un valor calculado que incluye el tiempo necesario para enviar el mensaje y recibir la respuesta del servidor.
reply
  El documento de respuesta devuelto por el servidor.
operationId
  El identificador de operación. Puede usarse para vincular eventos entre sí, como en escrituras en bloque, que pueden despachar varios comandos.
requestId
  El identificador de la petición. Puede usarse para asociar este MongoDB\Driver\Monitoring\CommandSucceededEvent con un MongoDB\Driver\Monitoring\CommandStartedEvent correspondiente.
serviceId
  El identificador de servicio, o `null` si el servidor no lo soporta (es decir, cuando no se utiliza el modo de balanceo de carga).
serverConnectionId
  El identificador de la conexión al servidor, o `null` si no está disponible.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.3.0 | Se añadieron propiedades públicas readonly. La propiedad duration reemplaza al método getDurationMicros().

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName — Devuelve el nombre del comando

### Descripción

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName(): string

Devuelve el nombre del comando (por ejemplo `"find"`, `"aggregate"`).

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el nombre del comando.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName

(mongodb >=1.19.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName — Devuelve el nombre de la base de datos sobre la cual se ejecutó el comando

### Descripción

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el nombre de la base de datos sobre la cual se ejecutó el comando.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros — Devuelve la duración del comando en microsegundos

### Descripción

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros(): int

La duración del comando es un valor calculado que incluye el tiempo para enviar el mensaje y recibir la respuesta del servidor.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la duración del comando en microsegundos.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost — Devuelve el nombre de host del servidor para el comando

### Descripción

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el nombre de host del servidor en el que se ejecutó el comando.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId — Devuelve el identificador de la operación de la orden

### Descripción

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId(): string

El identificador de la operación es generado por la extensión y puede ser utilizado para vincular eventos juntos tales como operaciones de escritura en masa, que pueden haber sido divididas en varias órdenes a nivel del protocolo.

> Nota: Dado que varias órdenes pueden compartir el mismo identificador de operación, no es fiable utilizar este valor para asociar objetos de evento entre sí. El identificador de la petición devuelto por MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId() debería ser utilizado en su lugar.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el identificador de la operación de la orden.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId() - Devuelve el identificador de la operación de la orden
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId() - Devuelve el identificador de la solicitud de la orden
- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort — Devuelve el puerto del servidor para la orden

### Descripción

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el puerto del servidor en el cual la orden fue ejecutada.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply — Devuelve el documento de respuesta de la orden

### Descripción

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply(): object

El documento de respuesta será convertido de BSON a PHP utilizando las reglas de deserialización por omisión (por ejemplo, los documentos BSON serán convertidos en stdClass).

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el documento de respuesta de la orden en forma de un objeto stdClass.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)
- Persistir datos

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId — Devuelve el identificador de la solicitud de la orden

### Descripción

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId(): string

El identificador de la solicitud es generado por la extensión y puede ser utilizado para asociar este MongoDB\Driver\Monitoring\CommandSucceededEvent con un MongoDB\Driver\Monitoring\CommandStartedEvent anterior.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el identificador de la solicitud de la orden.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() - Devuelve el identificador de la solicitud de la orden
- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer — Devuelve el servidor en el cual el comando fue ejecutado

Advertencia

Este método ha sido DEPRECADO a partir de la versión 1.20.0 de la extensión y ha sido eliminado en la versión 2.0. Las aplicaciones deben utilizar MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost() y MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort() en su lugar.

### Descripción

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer(): MongoDB\Driver\Server

Devuelve el MongoDB\Driver\Server en el cual el comando fue ejecutado.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el MongoDB\Driver\Server en el cual el comando fue ejecutado.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Este método ha sido eliminado.

### Ver también

- MongoDB\Driver\Monitoring\CommandStartedEvent::getServer() - Devuelve el servidor en el que se ejecutó el comando
- MongoDB\Driver\Cursor::getServer() - Devuelve el servidor asociado con este cursor
- MongoDB\Driver\WriteResult::getServer() - Devuelve el servidor asociado a este resultado de escritura
- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId

(mongodb >=1.14.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId — Devuelve el identificador de conexión del servidor para la orden

### Descripción

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId(): ?int

Devuelve el identificador de conexión del servidor para la orden. El identificador de conexión del servidor es distinto del servidor (es decir, MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer()) y es devuelto en el campo "connectionId" de una respuesta de orden `hello` MongoDB 4.2+.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el identificador de conexión del servidor, o `null` si no está disponible.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId

(mongodb >=1.11.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId — Devuelve el identificador del servicio del balanceador de carga para la orden

### Descripción

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId(): ?MongoDB\BSON\ObjectId

Cuando el controlador está conectado a un clúster MongoDB a través de un balanceador de carga, el identificador del servicio corresponde al campo `serviceId` en la respuesta de la orden `hello`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el identificador del servicio del balanceador de carga, o `null` si el controlador no está conectado a un balanceador de carga.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

## Tabla de contenidos

- MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName — Devuelve el nombre del comando
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName — Devuelve el nombre de la base de datos sobre la cual se ejecutó el comando
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros — Devuelve la duración del comando en microsegundos
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost — Devuelve el nombre de host del servidor para el comando
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId — Devuelve el identificador de la operación de la orden
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort — Devuelve el puerto del servidor para la orden
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply — Devuelve el documento de respuesta de la orden
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId — Devuelve el identificador de la solicitud de la orden
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer — Devuelve el servidor en el cual el comando fue ejecutado
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId — Devuelve el identificador de conexión del servidor para la orden
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId — Devuelve el identificador del servicio del balanceador de carga para la orden

# La clase MongoDB\Driver\Monitoring\ServerChangedEvent

(mongodb >=1.13.0)

## Introducción

La clase MongoDB\Driver\Monitoring\ServerChangedEvent encapsula información sobre una descripción de servidor modificada. Por ejemplo, el tipo de un servidor pasando de secundario a primario entraînerait un cambio en la descripción de este servidor.

## Sinopsis de la Clase

final class MongoDB\Driver\Monitoring\ServerChangedEvent {
/* Propiedades */
public readonly string $host;
public readonly int $port;
public readonly MongoDB\BSON\ObjectId $topologyId;
public readonly MongoDB\Driver\ServerDescription $newDescription;
public readonly MongoDB\Driver\ServerDescription $previousDescription;
/* Métodos */
final public function getHost(): string
final public function getNewDescription(): MongoDB\Driver\ServerDescription
final public function getPort(): int
final public function getPreviousDescription(): MongoDB\Driver\ServerDescription
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Propiedades

host
  El nombre de host del servidor.
port
  El puerto del servidor.
topologyId
  El identificador de la topología.
newDescription
  La nueva descripción del servidor.
previousDescription
  La descripción previa del servidor.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.3.0 | Se añadieron propiedades públicas readonly.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getHost — Devuelve el nombre del host del servidor

### Descripción

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getHost(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el nombre del host del servidor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription — Devuelve la nueva descripción del servidor

### Descripción

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription(): MongoDB\Driver\ServerDescription

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la nueva MongoDB\Driver\ServerDescription del servidor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getPort — Devuelve el puerto en el que este servidor está escuchando

### Descripción

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getPort(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el puerto en el que este servidor está escuchando.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription — Devuelve la descripción anterior del servidor

### Descripción

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription(): MongoDB\Driver\ServerDescription

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la MongoDB\Driver\ServerDescription anterior del servidor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId — Devuelve el ID de topología asociado a este servidor

### Descripción

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el ID de topología.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

## Tabla de contenidos

- MongoDB\Driver\Monitoring\ServerChangedEvent::getHost — Devuelve el nombre del host del servidor
- MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription — Devuelve la nueva descripción del servidor
- MongoDB\Driver\Monitoring\ServerChangedEvent::getPort — Devuelve el puerto en el que este servidor está escuchando
- MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription — Devuelve la descripción anterior del servidor
- MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId — Devuelve el ID de topología asociado a este servidor

# La clase MongoDB\Driver\Monitoring\ServerClosedEvent

(mongodb >=1.13.0)

## Introducción

La clase MongoDB\Driver\Monitoring\ServerClosedEvent encapsula información sobre un servidor cerrado. Esto corresponde a un servidor existente que ha sido retirado de la topología.

## Sinopsis de la Clase

final class MongoDB\Driver\Monitoring\ServerClosedEvent {
/* Propiedades */
public readonly string $host;
public readonly int $port;
public readonly MongoDB\BSON\ObjectId $topologyId;
/* Métodos */
final public function getHost(): string
final public function getPort(): int
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Propiedades

host
  El nombre de host del servidor.
port
  El puerto del servidor.
topologyId
  El identificador de la topología.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.3.0 | Se añadieron propiedades públicas readonly.

# MongoDB\Driver\Monitoring\ServerClosedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerClosedEvent::getHost — Devuelve el nombre de host del servidor

### Descripción

final public function MongoDB\Driver\Monitoring\ServerClosedEvent::getHost(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el nombre de host del servidor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\ServerClosedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerClosedEvent::getPort — Devuelve el puerto en el que este servidor escucha

### Descripción

final public function MongoDB\Driver\Monitoring\ServerClosedEvent::getPort(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el puerto en el que este servidor escucha.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId — Devuelve el ID de topología asociado a este servidor

### Descripción

final public function MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el ID de topología.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

## Tabla de contenidos

- MongoDB\Driver\Monitoring\ServerClosedEvent::getHost — Devuelve el nombre de host del servidor
- MongoDB\Driver\Monitoring\ServerClosedEvent::getPort — Devuelve el puerto en el que este servidor escucha
- MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId — Devuelve el ID de topología asociado a este servidor

# La clase MongoDB\Driver\Monitoring\ServerOpeningEvent

(mongodb >=1.13.0)

## Introducción

La clase MongoDB\Driver\Monitoring\ServerOpeningEvent encapsula información sobre un servidor abierto. Esto corresponde a un nuevo servidor que se añade a la topología.

## Sinopsis de la Clase

final class MongoDB\Driver\Monitoring\ServerOpeningEvent {
/* Propiedades */
public readonly string $host;
public readonly int $port;
public readonly MongoDB\BSON\ObjectId $topologyId;
/* Métodos */
final public function getHost(): string
final public function getPort(): int
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Propiedades

host
  El host del servidor.
port
  El puerto del servidor.
topologyId
  El identificador de la topología.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.3.0 | Se añadieron propiedades públicas readonly.

# MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost — Devuelve el nombre de host del servidor

### Descripción

final public function MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el nombre de host del servidor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort — Devuelve el puerto en el que este servidor está escuchando

### Descripción

final public function MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el puerto en el que este servidor está escuchando.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId — Devuelve el ID de topología asociado a este servidor

### Descripción

final public function MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el ID de topología.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

## Tabla de contenidos

- MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost — Devuelve el nombre de host del servidor
- MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort — Devuelve el puerto en el que este servidor está escuchando
- MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId — Devuelve el ID de topología asociado a este servidor

# La clase MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent

(mongodb >=1.13.0)

## Introducción

La clase MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent encapsula información sobre un fallo de latido de servidor (es decir, » hello comando emitido por » monitoreo del servidor).

## Sinopsis de la Clase

final class MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent {
/* Propiedades */
public readonly string $host;
public readonly int $port;
public readonly bool $awaited;
public readonly int $duration;
public readonly Exception $error;
/* Métodos */
final public function getDurationMicros(): int
final public function getError(): Exception
final public function getHost(): string
final public function getPort(): int
final public function isAwaited(): bool
}

## Propiedades

host
  El nombre de host del servidor.
port
  El puerto del servidor.
awaited
  Indica si el latido utilizó un protocolo de streaming. La extensión no utiliza el protocolo de streaming para la monitorización, por lo que este método siempre devolverá `false`.
duration
  La duración del latido en microsegundos. La duración es un valor calculado que incluye el tiempo de envío del mensaje y de recepción de la respuesta del servidor.
error
  La excepción lanzada cuando el latido falló.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.3.0 | Se añadieron propiedades públicas readonly. La propiedad duration reemplaza al método getDurationMicros().

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros — Devuelve la duración del latido en microsegundos

### Descripción

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros(): int

La duración del latido es un valor calculado que incluye el tiempo para enviar el mensaje y recibir la respuesta del servidor.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la duración del latido en microsegundos.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError — Devuelve la excepción asociada al fallo del latido periódico

### Descripción

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError(): Exception

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la Exception asociada al fallo del latido periódico.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost — Devuelve el nombre de host del servidor

### Descripción

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el nombre de host del servidor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort — Devuelve el puerto en el que este servidor escucha

### Descripción

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el puerto en el que este servidor escucha.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited — Indica si el latido periódico ha utilizado un protocolo de difusión de flujo

### Descripción

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited(): bool

Indica si el latido periódico ha utilizado un protocolo de difusión de flujo. La extensión no utiliza el protocolo de difusión de flujo para la supervisión, por lo tanto, este método siempre devolverá `false`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `false`.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

## Tabla de contenidos

- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros — Devuelve la duración del latido en microsegundos
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError — Devuelve la excepción asociada al fallo del latido periódico
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost — Devuelve el nombre de host del servidor
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort — Devuelve el puerto en el que este servidor escucha
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited — Indica si el latido periódico ha utilizado un protocolo de difusión de flujo

# La clase MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent

(mongodb >=1.13.0)

## Introducción

La clase MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent encapsula información sobre un latido de servidor iniciado (es decir, » comando hello emitido a través de » la supervisión del servidor).

## Sinopsis de la Clase

final class MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent {
/* Propiedades */
public readonly string $host;
public readonly int $port;
public readonly bool $awaited;
/* Métodos */
final public function getHost(): string
final public function getPort(): int
final public function isAwaited(): bool
}

## Propiedades

host
  El host del servidor.
port
  El puerto del servidor.
awaited
  Indica si el latido utilizó un protocolo de transmisión continua. La extensión no utiliza el protocolo de transmisión continua para la supervisión, por lo que este método siempre devolverá `false`.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.3.0 | Se añadieron propiedades públicas readonly.

# MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost — Devuelve el nombre del host del servidor

### Descripción

final public function MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el nombre del host del servidor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort — Devuelve el puerto en el que este servidor está escuchando

### Descripción

final public function MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el puerto en el que este servidor está escuchando.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited — Indica si el latido periódico ha utilizado un protocolo de difusión de flujo

### Descripción

final public function MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited(): bool

Indica si el latido periódico ha utilizado un protocolo de difusión de flujo. La extensión no utiliza el protocolo de difusión de flujo para la monitorización, por lo que este método siempre devolverá `false`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `false`.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

## Tabla de contenidos

- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost — Devuelve el nombre del host del servidor
- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort — Devuelve el puerto en el que este servidor está escuchando
- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited — Indica si el latido periódico ha utilizado un protocolo de difusión de flujo

# La clase MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent

(mongodb >=1.13.0)

## Introducción

La clase MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent encapsula información sobre un latido de servidor exitoso (es decir, » comando hello emitido a través de » la supervisión del servidor).

## Sinopsis de la Clase

final class MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent {
/* Propiedades */
public readonly string $host;
public readonly int $port;
public readonly bool $awaited;
public readonly int $duration;
public readonly object $reply;
/* Métodos */
final public function getDurationMicros(): int
final public function getHost(): string
final public function getPort(): int
final public function getReply(): object
final public function isAwaited(): bool
}

## Propiedades

host
  El host del servidor.
port
  El puerto del servidor.
awaited
  Indica si el latido utilizó un protocolo de transmisión continua. La extensión no utiliza el protocolo de transmisión continua para la supervisión, por lo que este método siempre devolverá `false`.
duration
  La duración del latido en microsegundos. La duración es un valor calculado que incluye el tiempo necesario para enviar el mensaje y recibir la respuesta del servidor.
reply
  El documento de respuesta devuelto por el servidor.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.3.0 | Se añadieron propiedades públicas readonly. La propiedad duration reemplaza al método getDurationMicros().

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros — Devuelve la duración del latido en microsegundos

### Descripción

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros(): int

La duración del latido es un valor calculado que incluye el tiempo para enviar el mensaje y recibir la respuesta del servidor.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la duración del latido en microsegundos.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost — Devuelve el nombre de host del servidor

### Descripción

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost(): string

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el nombre de host del servidor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort — Devuelve el puerto en el que este servidor escucha

### Descripción

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort(): int

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el puerto en el que este servidor escucha.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply — Devuelve el documento de respuesta del heartbeat

### Descripción

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply(): object

El documento de respuesta será convertido de BSON a PHP utilizando las reglas de deserialización por omisión (por ejemplo, los documentos BSON serán convertidos en stdClass).

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el documento de respuesta del heartbeat en forma de un objeto stdClass.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)
- Persistir datos

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited — Indica si el latido periódico ha utilizado un protocolo de difusión de flujo

### Descripción

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited(): bool

Indica si el latido periódico ha utilizado un protocolo de difusión de flujo. La extensión no utiliza el protocolo de difusión de flujo para la supervisión, por lo que este método siempre devolverá `false`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `false`.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

## Tabla de contenidos

- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros — Devuelve la duración del latido en microsegundos
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost — Devuelve el nombre de host del servidor
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort — Devuelve el puerto en el que este servidor escucha
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply — Devuelve el documento de respuesta del heartbeat
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited — Indica si el latido periódico ha utilizado un protocolo de difusión de flujo

# La clase MongoDB\Driver\Monitoring\TopologyChangedEvent

(mongodb >=1.13.0)

## Introducción

La clase MongoDB\Driver\Monitoring\TopologyChangedEvent encapsula información sobre una descripción de topología modificada. Por ejemplo, el descubrimiento de un nuevo primario en un conjunto de réplicas resultaría en un cambio en la descripción de la topología.

## Sinopsis de la Clase

final class MongoDB\Driver\Monitoring\TopologyChangedEvent {
/* Propiedades */
public readonly MongoDB\BSON\ObjectId $topologyId;
public readonly MongoDB\Driver\TopologyDescription $newDescription;
public readonly MongoDB\Driver\TopologyDescription $previousDescription;
/* Métodos */
final public function getNewDescription(): MongoDB\Driver\TopologyDescription
final public function getPreviousDescription(): MongoDB\Driver\TopologyDescription
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Propiedades

topologyId
  El identificador de la topología.
newDescription
  La nueva descripción de la topología.
previousDescription
  La descripción previa de la topología.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.3.0 | Se añadieron propiedades públicas readonly.

# MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription — Devuelve la nueva descripción de la topología

### Descripción

final public function MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription(): MongoDB\Driver\TopologyDescription

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la nueva MongoDB\Driver\TopologyDescription para la topología.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription — Devuelve la descripción anterior de la topología

### Descripción

final public function MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription(): MongoDB\Driver\TopologyDescription

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la descripción anterior MongoDB\Driver\TopologyDescription para la topología.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

# MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId — Devuelve el identificador de la topología

### Descripción

final public function MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el identificador de la topología.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

## Tabla de contenidos

- MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription — Devuelve la nueva descripción de la topología
- MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription — Devuelve la descripción anterior de la topología
- MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId — Devuelve el identificador de la topología

# La clase MongoDB\Driver\Monitoring\TopologyClosedEvent

(mongodb >=1.13.0)

## Introducción

La clase MongoDB\Driver\Monitoring\TopologyClosedEvent encapsula información sobre una topología cerrada.

> Nota: Debido al comportamiento de gestión y persistencia de las conexiones del controlador, este evento solo puede ser observado cuando un MongoDB\Driver\Manager es creado con la opción del controlador `"disableClientPersistence"` y liberado antes del cierre de la solicitud (RSHUTDOWN).

## Sinopsis de la Clase

final class MongoDB\Driver\Monitoring\TopologyClosedEvent {
/* Propiedades */
public readonly MongoDB\BSON\ObjectId $topologyId;
/* Métodos */
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Propiedades

topologyId
  El identificador de la topología.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.3.0 | Se añadieron propiedades públicas readonly.

# MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId — Devuelve el identificador de la topología

### Descripción

final public function MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el identificador de la topología.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

## Tabla de contenidos

- MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId — Devuelve el identificador de la topología

# La clase MongoDB\Driver\Monitoring\TopologyOpeningEvent

(mongodb >=1.13.0)

## Introducción

La clase MongoDB\Driver\Monitoring\TopologyOpeningEvent encapsula información sobre una topología abierta.

> Nota: Debido al comportamiento de gestión y persistencia de las conexiones del controlador, este evento puede no ser observado si un MongoDB\Driver\Manager utiliza un cliente » libmongoc previamente persistente.

## Sinopsis de la Clase

final class MongoDB\Driver\Monitoring\TopologyOpeningEvent {
/* Propiedades */
public readonly MongoDB\BSON\ObjectId $topologyId;
/* Métodos */
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Propiedades

topologyId
  El identificador de la topología.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.3.0 | Se añadieron propiedades públicas readonly.

# MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId — Devuelve el identificador de la topología

### Descripción

final public function MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el identificador de la topología.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

## Tabla de contenidos

- MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId — Devuelve el identificador de la topología

# La interfaz MongoDB\Driver\Monitoring\CommandSubscriber

(mongodb >=1.3.0)

## Introducción

Las clases pueden implementar esta interfaz para registrar un observador de eventos que es notificado para cada evento de comando iniciado, Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM) para más información.

## Sinopsis de la Interfaz

class MongoDB\Driver\Monitoring\CommandSubscriber implements MongoDB\Driver\Monitoring\Subscriber {
/* Métodos */
abstract public function commandFailed(MongoDB\Driver\Monitoring\CommandFailedEvent `$event`): void
abstract public function commandStarted(MongoDB\Driver\Monitoring\CommandStartedEvent `$event`): void
abstract public function commandSucceeded(MongoDB\Driver\Monitoring\CommandSucceededEvent `$event`): void
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Los tipos de retorno previamente declarados como provisionales ahora son aplicados.
PECL mongodb 1.15.0 | Los tipos de retorno de los métodos son declarados como provisionales en PHP 8.0 y posteriores, lo que desencadena avisos de depreciación en el código que implementa esta interfaz sin declarar los tipos de retorno apropiados. El atributo `#[ReturnTypeWillChange]` puede ser añadido para ignorar la notificación de depreciación.

# MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed — Método de notificación para una orden fallida

### Descripción

abstract public function MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed(MongoDB\Driver\Monitoring\CommandFailedEvent `$event`): void

Si el observador está registrado, este método es llamado cuando una orden falla.

### Parámetros

`event` (MongoDB\Driver\Monitoring\CommandFailedEvent)
  Un objeto de evento que encapsula información sobre la orden fallida.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Monitoring\CommandFailedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra un suscriptor de eventos de monitorización de forma global
- MongoDB\Driver\Manager::addSubscriber() - Registra un observador de eventos de monitoreo con este manager
- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted — Método de notificación para una orden iniciada

### Descripción

abstract public function MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted(MongoDB\Driver\Monitoring\CommandStartedEvent `$event`): void

Si el observador está registrado, este método es llamado cuando una orden es enviada al servidor.

### Parámetros

`event` (MongoDB\Driver\Monitoring\CommandStartedEvent)
  Un objeto de evento que encapsula información sobre la orden iniciada.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Monitoring\CommandStartedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra un suscriptor de eventos de monitorización de forma global
- MongoDB\Driver\Manager::addSubscriber() - Registra un observador de eventos de monitoreo con este manager
- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded — Método de notificación para un comando exitoso

### Descripción

abstract public function MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded(MongoDB\Driver\Monitoring\CommandSucceededEvent `$event`): void

Si el observador está registrado, este método es llamado cuando un comando tiene éxito.

### Parámetros

`event` (MongoDB\Driver\Monitoring\CommandSucceededEvent)
  Un objeto de evento que encapsula información sobre el comando exitoso.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Monitoring\CommandSucceededEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra un suscriptor de eventos de monitorización de forma global
- MongoDB\Driver\Manager::addSubscriber() - Registra un observador de eventos de monitoreo con este manager
- Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)

## Tabla de contenidos

- MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed — Método de notificación para una orden fallida
- MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted — Método de notificación para una orden iniciada
- MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded — Método de notificación para un comando exitoso

# La interfaz MongoDB\Driver\Monitoring\SDAMSubscriber

(mongodb >=1.13.0)

## Introducción

Las clases pueden implementar esta interfaz para registrar un observador de eventos que es notificado para diversos eventos SDAM. Ver las especificaciones » Descubrimiento y supervisión de server y » Supervisión de SDAM para más información.

## Sinopsis de la Interfaz

class MongoDB\Driver\Monitoring\SDAMSubscriber implements MongoDB\Driver\Monitoring\Subscriber {
/* Métodos */
abstract public function serverChanged(MongoDB\Driver\Monitoring\ServerChangedEvent `$event`): void
abstract public function serverClosed(MongoDB\Driver\Monitoring\ServerClosedEvent `$event`): void
abstract public function serverHeartbeatFailed(MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent `$event`): void
abstract public function serverHeartbeatStarted(MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent `$event`): void
abstract public function serverHeartbeatSucceeded(MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent `$event`): void
abstract public function serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent `$event`): void
abstract public function topologyChanged(MongoDB\Driver\Monitoring\TopologyChangedEvent `$event`): void
abstract public function topologyClosed(MongoDB\Driver\Monitoring\TopologyClosedEvent `$event`): void
abstract public function topologyOpening(MongoDB\Driver\Monitoring\TopologyOpeningEvent `$event`): void
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Los tipos de retorno previamente declarados como provisionales ahora son aplicados.
PECL mongodb 1.15.0 | Los tipos de retorno de los métodos son declarados como provisionales en PHP 8.0 y posteriores, lo que desencadena avisos de depreciación en el código que implementa esta interfaz sin declarar los tipos de retorno apropiados. El atributo `#[ReturnTypeWillChange]` puede ser añadido para ignorar la notificación de depreciación.

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged — Método de notificación para un cambio de descripción de servidor

### Descripción

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged(MongoDB\Driver\Monitoring\ServerChangedEvent `$event`): void

Si un observador está registrado, este método es llamado cuando una descripción de servidor cambia. Por ejemplo, el tipo de un servidor pasando de secundario a primario resultaría en un cambio de la descripción de ese servidor.

### Parámetros

`event` (MongoDB\Driver\Monitoring\ServerChangedEvent)
  Un objeto de evento que encapsula información sobre la descripción de servidor modificada.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Monitoring\ServerChangedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra un suscriptor de eventos de monitorización de forma global
- MongoDB\Driver\Manager::addSubscriber() - Registra un observador de eventos de monitoreo con este manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed — Método de notificación para el cierre de un servidor

### Descripción

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed(MongoDB\Driver\Monitoring\ServerClosedEvent `$event`): void

Si un observador está registrado, este método es llamado cuando un servidor existente es retirado de la topología.

### Parámetros

`event` (MongoDB\Driver\Monitoring\ServerClosedEvent)
  Un objeto de evento que encapsula información sobre el servidor cerrado.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Monitoring\ServerClosedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra un suscriptor de eventos de monitorización de forma global
- MongoDB\Driver\Manager::addSubscriber() - Registra un observador de eventos de monitoreo con este manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed — Método de notificación para un fallo de latido de servidor

### Descripción

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed(MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent `$event`): void

Si un observador está registrado, este método es llamado cuando un latido de servidor (es decir, un comando » hello emitido mediante » monitoreo de servidor) falla.

### Parámetros

`event` (MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent)
  Un objeto de evento que encapsula información sobre el fallo de latido de servidor.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra un suscriptor de eventos de monitorización de forma global
- MongoDB\Driver\Manager::addSubscriber() - Registra un observador de eventos de monitoreo con este manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted — Método de notificación para un latido de servidor iniciado

### Descripción

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted(MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent `$event`): void

Si un observador está registrado, este método es llamado cuando un latido de servidor (es decir, un comando » hello emitido a través de » monitoreo de servidor) es enviado al servidor.

### Parámetros

`event` (MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent)
  Un objeto de evento que encapsula información sobre el latido de servidor iniciado.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra un suscriptor de eventos de monitorización de forma global
- MongoDB\Driver\Manager::addSubscriber() - Registra un observador de eventos de monitoreo con este manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded — Método de notificación para un latido de servidor exitoso

### Descripción

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded(MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent `$event`): void

Si un observador está registrado, este método es llamado cuando un latido de servidor (es decir, una comando » hello emitido a través de » monitoreo de servidor) tiene éxito.

### Parámetros

`event` (MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent)
  Un objeto de evento que encapsula información sobre el latido de servidor exitoso.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra un suscriptor de eventos de monitorización de forma global
- MongoDB\Driver\Manager::addSubscriber() - Registra un observador de eventos de monitoreo con este manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening — Método de notificación para la apertura de un servidor

### Descripción

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent `$event`): void

Si un observador está registrado, este método es llamado cuando un servidor existente es retirado de la topología.

### Parámetros

`event` (MongoDB\Driver\Monitoring\ServerOpeningEvent)
  Un objeto de evento que encapsula información sobre el servidor abierto.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Monitoring\ServerOpeningEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra un suscriptor de eventos de monitorización de forma global
- MongoDB\Driver\Manager::addSubscriber() - Registra un observador de eventos de monitoreo con este manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged — Método de notificación para un cambio de descripción de topología

### Descripción

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged(MongoDB\Driver\Monitoring\TopologyChangedEvent `$event`): void

Si un observador está registrado, este método es llamado cuando una descripción de topología cambia. Por ejemplo, el descubrimiento de un nuevo primario en un conjunto de réplicas resultaría en un cambio de la descripción de la topología.

### Parámetros

`event` (MongoDB\Driver\Monitoring\TopologyChangedEvent)
  Un objeto de evento que encapsula información sobre la descripción de topología modificada.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Monitoring\TopologyChangedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra un suscriptor de eventos de monitorización de forma global
- MongoDB\Driver\Manager::addSubscriber() - Registra un observador de eventos de monitoreo con este manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed — Método de notificación para el cierre de topología

### Descripción

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed(MongoDB\Driver\Monitoring\TopologyClosedEvent `$event`): void

Si un observador está registrado, este método es llamado cuando una topología es cerrada.

> Nota: Debido al comportamiento del controlador de gestión y persistencia de conexiones, este evento solo puede ser observado cuando un MongoDB\Driver\Manager es creado con la opción del controlador `"disableClientPersistence"` y liberado antes del cierre de la solicitud (RSHUTDOWN).

### Parámetros

`event` (MongoDB\Driver\Monitoring\TopologyClosedEvent)
  Un objeto de evento que encapsula información sobre la topología cerrada.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Monitoring\TopologyClosedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra un suscriptor de eventos de monitorización de forma global
- MongoDB\Driver\Manager::addSubscriber() - Registra un observador de eventos de monitoreo con este manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening — Método de notificación para la apertura de topología

### Descripción

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening(MongoDB\Driver\Monitoring\TopologyOpeningEvent `$event`): void

Si un observador está registrado, este método es llamado cuando una topología es abierta.

> Nota: Debido al comportamiento del controlador de gestión y persistencia de conexiones, este evento puede no ser observado si un MongoDB\Driver\Manager utiliza un cliente » libmongoc previamente persistente.

### Parámetros

`event` (MongoDB\Driver\Monitoring\TopologyOpeningEvent)
  Un objeto de evento que encapsula información sobre la topología abierta.

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

- Lanza una excepción MongoDB\Driver\InvalidArgumentException en caso de error durante el análisis de un argumento.

### Ver también

- MongoDB\Driver\Monitoring\TopologyOpeningEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra un suscriptor de eventos de monitorización de forma global
- MongoDB\Driver\Manager::addSubscriber() - Registra un observador de eventos de monitoreo con este manager

## Tabla de contenidos

- MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged — Método de notificación para un cambio de descripción de servidor
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed — Método de notificación para el cierre de un servidor
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed — Método de notificación para un fallo de latido de servidor
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted — Método de notificación para un latido de servidor iniciado
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded — Método de notificación para un latido de servidor exitoso
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening — Método de notificación para la apertura de un servidor
- MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged — Método de notificación para un cambio de descripción de topología
- MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed — Método de notificación para el cierre de topología
- MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening — Método de notificación para la apertura de topología

# La interfaz MongoDB\Driver\Monitoring\Subscriber

(mongodb >=1.3.0)

## Introducción

La interfaz base para los observadores de eventos. Es utilizada como tipo de argumento en las funciones MongoDB\Driver\Monitoring\addSubscriber() y MongoDB\Driver\Monitoring\removeSubscriber() y no debe ser implementada directamente.

## Sinopsis de la Interfaz

class MongoDB\Driver\Monitoring\Subscriber {
}

Esta interfaz no tiene métodos. Su único propósito es ser la interfaz base para todos los observadores de eventos.

# Clases de excepciones

## Tabla de contenidos

- MongoDB\Driver\Exception\AuthenticationException
- MongoDB\Driver\Exception\BulkWriteException
- MongoDB\Driver\Exception\BulkWriteCommandException
- MongoDB\Driver\Exception\CommandException
- MongoDB\Driver\Exception\ConnectionException
- MongoDB\Driver\Exception\ConnectionTimeoutException
- MongoDB\Driver\Exception\EncryptionException
- MongoDB\Driver\Exception\Exception
- MongoDB\Driver\Exception\ExecutionTimeoutException
- MongoDB\Driver\Exception\InvalidArgumentException
- MongoDB\Driver\Exception\LogicException
- MongoDB\Driver\Exception\RuntimeException
- MongoDB\Driver\Exception\ServerException
- MongoDB\Driver\Exception\SSLConnectionException
- MongoDB\Driver\Exception\UnexpectedValueException
- MongoDB\Driver\Exception\WriteException
- Jerarquía de clases

# La clase MongoDB\Driver\Exception\AuthenticationException

(mongodb >= 1.0.0)

## Introducción

Se lanza cuando el controlador no logra autenticarse con el servidor.

## Sinopsis de la Clase

class MongoDB\Driver\Exception\AuthenticationException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* Propiedades heredadas */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La clase MongoDB\Driver\Exception\BulkWriteException

(mongodb >= 1.0.0)

## Introducción

Se levanta cuando una operación de escritura en bloque falla.

## Sinopsis de la Clase

final class MongoDB\Driver\Exception\BulkWriteException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Propiedades */
public readonly MongoDB\Driver\WriteResult $writeResult;
/* Propiedades heredadas */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
final public function getWriteResult(): MongoDB\Driver\WriteResult
/* Métodos heredados */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propiedades

writeResult

  El MongoDB\Driver\WriteResult asociado a la operación de escritura fallida.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.3.0 | La propiedad writeResult ahora es public readonly.
PECL mongodb 2.0.0 | Esta clase extiende ahora MongoDB\Driver\Exception\ServerException en lugar de MongoDB\Driver\Exception\WriteException.

# MongoDB\Driver\Exception\BulkWriteException::getWriteResult

(mongodb >= 1.0.0)

MongoDB\Driver\Exception\BulkWriteException::getWriteResult — Devuelve el WriteResult para la operación de escritura fallida

### Descripción

final public function MongoDB\Driver\Exception\BulkWriteException::getWriteResult(): MongoDB\Driver\WriteResult

Devuelve el MongoDB\Driver\WriteResult para la operación de escritura fallida. Los métodos MongoDB\Driver\WriteResult::getWriteErrors() y MongoDB\Driver\WriteResult::getWriteConcernError() pueden ser utilizados para obtener detalles adicionales sobre el error.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El MongoDB\Driver\WriteResult para la operación de escritura fallida.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\Exception\BulkWriteException::getWriteResult()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost');
    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        $writeResult = $e->getWriteResult();

        if ($writeConcernError = $writeResult->getWriteConcernError()) {
            var_dump($writeConcernError);
        }

        if ($writeErrors = $writeResult->getWriteErrors()) {
            var_dump($writeErrors);
        }
    }

    ?>

Resultado del ejemplo anterior es similar a:

    array(1) {
      [0]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(70) "E11000 duplicate key error index: db.collection.$_id_ dup key: { : 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(1)
        ["info"]=>
        NULL
      }
    }

### Ver también

- MongoDB\Driver\WriteResult
- MongoDB\Driver\Manager::executeBulkWrite() - Ejecuta una o varias operaciones de escritura

## Tabla de contenidos

- MongoDB\Driver\Exception\BulkWriteException::getWriteResult — Devuelve el WriteResult para la operación de escritura fallida

# La clase MongoDB\Driver\Exception\BulkWriteCommandException

(mongodb >=2.1.0)

## Introducción

Excepción lanzada debido a la ejecución fallida de una MongoDB\Driver\BulkWriteCommand. Los métodos de esta clase proporcionan más detalles sobre el error que ocurrió, incluyendo la respuesta de error y los resultados parciales de la escritura masiva.

## Sinopsis de la Clase

class MongoDB\Driver\Exception\BulkWriteCommandException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Propiedades */
private ?MongoDB\BSON\Document $errorReply;
private ?MongoDB\Driver\BulkWriteCommandResult $partialResult;
private array $writeConcernErrors;
private array $writeErrors;
/* Propiedades heredadas */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
final public function getErrorReply(): ?MongoDB\BSON\Document
final public function getPartialResult(): ?MongoDB\Driver\BulkWriteCommandResult
final public function getWriteConcernErrors(): array
final public function getWriteErrors(): array
/* Métodos heredados */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propiedades

errorReply
  Cualquier error de nivel superior que ocurrió al intentar comunicarse con el servidor o ejecutar la escritura masiva. Este valor puede ser `null` si la excepción se lanzó debido a errores que ocurrieron en escrituras individuales.
partialResult
  Un MongoDB\Driver\BulkWriteCommandResult que informa sobre el resultado de cualquier operación exitosa que se realizó antes de que se encontrara el error. Este valor puede ser `null` si no se puede determinar que al menos una escritura se realizó con éxito (y fue confirmada).
writeConcernErrors
  Un array de cualquier MongoDB\Driver\WriteConcernError que ocurrió al ejecutar la escritura masiva. Esta lista puede tener múltiples elementos si se requirieron más de un comando de servidor para ejecutar la escritura masiva.
writeErrors
  Un array de cualquier MongoDB\Driver\WriteError que ocurrió durante la ejecución de operaciones de escritura individuales. Las claves del array corresponderán al índice de la operación de escritura de MongoDB\Driver\BulkWriteCommand. Este mapa contendrá como máximo una entrada si la escritura masiva estaba ordenada.

# MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply — Devuelve un error de comando de nivel superior

### Descripción

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply(): ?MongoDB\BSON\Document

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un error de comando de nivel superior que ocurrió al intentar comunicarse con el servidor o al ejecutar la escritura masiva. Este valor puede ser `null` si la excepción fue lanzada debido a errores que ocurrieron en escrituras individuales.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply()

    <?php

    $manager = new MongoDB\Driver\Manager;

    // Este ejemplo utiliza configureFailPoint para simular un error de comando de nivel superior
    $manager->executeCommand('admin', new MongoDB\Driver\Command([
        'configureFailPoint' => 'failCommand',
        'mode' => ['times' => 1],
        'data' => [
            'failCommands' => ['bulkWrite'],
            'errorCode' => 8, /* UnknownError */
        ],
    ]));

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        var_dump($e->getErrorReply()?->toPHP());
    }

    ?>

Resultado del ejemplo anterior es similar a:

    object(stdClass)#12 (6) {
      ["ok"]=>
      float(0)
      ["errmsg"]=>
      string(43) "Failing command via 'failCommand' failpoint"
      ["code"]=>
      int(8)
      ["codeName"]=>
      string(12) "UnknownError"
      ["$clusterTime"]=>
      object(stdClass)#10 (2) {
        ["clusterTime"]=>
        object(MongoDB\BSON\Timestamp)#6 (2) {
          ["increment"]=>
          string(1) "7"
          ["timestamp"]=>
          string(10) "1744319389"
        }
        ["signature"]=>
        object(stdClass)#9 (2) {
          ["hash"]=>
          object(MongoDB\BSON\Binary)#7 (2) {
            ["data"]=>
            string(20) ""
            ["type"]=>
            int(0)
          }
          ["keyId"]=>
          object(MongoDB\BSON\Int64)#8 (1) {
            ["integer"]=>
            string(1) "0"
          }
        }
      }
      ["operationTime"]=>
      object(MongoDB\BSON\Timestamp)#11 (2) {
        ["increment"]=>
        string(1) "7"
        ["timestamp"]=>
        string(10) "1744319389"
      }
    }

### Ver también

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Ejecuta operaciones de escritura utilizando el comando bulkWrite

# MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult — Devuelve el resultado de todas las operaciones de escritura exitosas

### Descripción

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult(): ?MongoDB\Driver\BulkWriteCommandResult

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un MongoDB\Driver\BulkWriteCommandResult que proporciona los resultados de cada una de las operaciones exitosas que se realizaron antes de que se encontrara el error. El valor devuelto será `null` si no se puede determinar si al menos una escritura se realizó con éxito (y fue reconocida).

### Ejemplos

Ejemplo #1 Resultado parcial si al menos una escritura es exitosa

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();
    }

    var_dump($result?->getInsertedCount());

    ?>

El ejemplo anterior mostrará:

    int(1)

Ejemplo #2 Ningún resultado parcial si ninguna escritura es exitosa

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $manager->executeBulkWriteCommand($bulk);

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['_id' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();
    }

    var_dump($result?->getInsertedCount());

    ?>

El ejemplo anterior mostrará:

    NULL

### Ver también

- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Ejecuta operaciones de escritura utilizando el comando bulkWrite

# MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors — Devuelve los errores de preocupación de escritura

### Descripción

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors(): array

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array de cada uno de los MongoDB\Driver\WriteConcernErrors que se produjeron durante la ejecución de la escritura masiva. Esta lista puede tener múltiples entradas si se necesitó más de un comando de servidor para ejecutar la escritura masiva.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(50);

    try {
        $result = $manager->executeBulkWriteCommand($bulk, ['writeConcern' => $writeConcern]);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        var_dump($e->getWriteConcernErrors());
    }

    ?>

Resultado del ejemplo anterior es similar a:

    array(1) {
      [0]=>
      object(MongoDB\Driver\WriteConcernError)#6 (3) {
        ["message"]=>
        string(29) "Not enough data-bearing nodes"
        ["code"]=>
        int(100)
        ["info"]=>
        object(stdClass)#8 (1) {
          ["writeConcern"]=>
          object(stdClass)#7 (3) {
            ["w"]=>
            int(50)
            ["wtimeout"]=>
            int(0)
            ["provenance"]=>
            string(14) "clientSupplied"
          }
        }
      }
    }

### Ver también

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Ejecuta operaciones de escritura utilizando el comando bulkWrite
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\WriteConcernError

# MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors — Devuelve los errores de escritura

### Descripción

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors(): array

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array de MongoDB\Driver\WriteError que se produjeron durante la ejecución de la escritura individual. Las claves del array corresponden al índice de la operación de escritura en MongoDB\Driver\BulkWriteCommand. Esta lista contendrá como máximo una entrada si la escritura masiva estaba ordenada.

### Ejemplos

Ejemplo #1 Ejemplo de MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['ordered' => false]);
    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        var_dump($e->getWriteErrors());
    }

    ?>

Resultado del ejemplo anterior es similar a:

    array(2) {
      [2]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(2)
        ["info"]=>
        object(stdClass)#6 (0) {
        }
      }
      [3]=>
      object(MongoDB\Driver\WriteError)#7 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(3)
        ["info"]=>
        object(stdClass)#8 (0) {
        }
      }
    }

### Ver también

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Ejecuta operaciones de escritura utilizando el comando bulkWrite
- MongoDB\Driver\WriteError

## Tabla de contenidos

- MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply — Devuelve un error de comando de nivel superior
- MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult — Devuelve el resultado de todas las operaciones de escritura exitosas
- MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors — Devuelve los errores de preocupación de escritura
- MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors — Devuelve los errores de escritura

# La clase MongoDB\Driver\Exception\CommandException

(mongodb >= 1.5.0)

## Introducción

Lanzada cuando una orden falla.

## Sinopsis de la Clase

class MongoDB\Driver\Exception\CommandException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Propiedades */
public readonly object $resultDocument;
/* Propiedades heredadas */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
final public function getResultDocument(): object
/* Métodos heredados */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propiedades

resultDocument

  El resultado del documento asociado a la orden fallida.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.3.0 | La propiedad resultDocument ahora es public readonly.

# MongoDB\Driver\Exception\CommandException::getResultDocument

(mongodb >= 1.5.0)

MongoDB\Driver\Exception\CommandException::getResultDocument — Devuelve el documento resultante para el comando fallido

### Descripción

final public function MongoDB\Driver\Exception\CommandException::getResultDocument(): object

Devuelve el documento resultante para el comando fallido.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El documento resultante para el comando fallido.

### Ver también

- MongoDB\Driver\Manager::executeCommand() - Ejecuta un comando de base de datos

## Tabla de contenidos

- MongoDB\Driver\Exception\CommandException::getResultDocument — Devuelve el documento resultante para el comando fallido

# La clase MongoDB\Driver\Exception\ConnectionException

(mongodb >= 1.0.0)

## Introducción

Clase base para las excepciones lanzadas cuando el controlador no logra establecer una conexión con la base de datos.

## Sinopsis de la Clase

class MongoDB\Driver\Exception\ConnectionException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* Propiedades heredadas */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La clase MongoDB\Driver\Exception\ConnectionTimeoutException

(mongodb >= 1.0.0)

## Introducción

Se lanza cuando el controlador no logra establecer una conexión con la base de datos dentro del límite de tiempo especificado (connectTimeoutMS) o falla la selección del servidor (serverSelectionTimeoutMS).

## Sinopsis de la Clase

final class MongoDB\Driver\Exception\ConnectionTimeoutException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* Propiedades heredadas */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La clase MongoDB\Driver\Exception\EncryptionException

(mongodb >= 1.7.0)

## Introducción

Clase base para excepciones lanzadas durante la cifrado lado-cliente.

## Sinopsis de la Clase

class MongoDB\Driver\Exception\EncryptionException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* Propiedades heredadas */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La interfaz MongoDB\Driver\Exception\Exception

(mongodb >= 1.0.0)

## Introducción

Interfaz común para todas las excepciones de la extensión. Esta interfaz también es utilizada por la biblioteca y puede emplearse para identificar cualquier excepción originada en el controlador PHP de MongoDB (es decir, la extensión y la biblioteca).

## Sinopsis de la Clase

class MongoDB\Driver\Exception\Exception {
}

# La clase MongoDB\Driver\Exception\ExecutionTimeoutException

(mongodb >= 1.0.0)

## Introducción

Se lanza cuando una consulta o comando no logra completarse dentro del tiempo límite especificado (por ejemplo, » maxTimeMS).

## Sinopsis de la Clase

final class MongoDB\Driver\Exception\ExecutionTimeoutException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Propiedades heredadas */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.5.0 | Esta clase ahora extiende MongoDB\Driver\Exception\ServerException en lugar de MongoDB\Driver\Exception\RuntimeException.

# La clase MongoDB\Driver\Exception\InvalidArgumentException

(mongodb >= 1.0.0)

## Introducción

Se lanza cuando un método del controlador recibe argumentos no válidos (por ejemplo, tipos de opciones no válidos).

## Sinopsis de la Clase

class MongoDB\Driver\Exception\InvalidArgumentException extends InvalidArgumentException implements MongoDB\Driver\Exception\Exception {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La clase MongoDB\Driver\Exception\LogicException

(mongodb >= 1.0.0)

## Introducción

Se lanza cuando el controlador se usa incorrectamente (p. ej. retrocediendo un cursor).

## Sinopsis de la Clase

class MongoDB\Driver\Exception\LogicException extends LogicException implements MongoDB\Driver\Exception\Exception {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La clase MongoDB\Driver\Exception\RuntimeException

(mongodb >= 1.0.0)

## Introducción

Se lanza cuando el controlador encuentra un error en tiempo de ejecución (por ejemplo, error interno de » libmongoc).

## Sinopsis de la Clase

class MongoDB\Driver\Exception\RuntimeException extends RuntimeException implements MongoDB\Driver\Exception\Exception {
/* Propiedades */
protected ?array $errorLabels;
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
final public function hasErrorLabel(string `$errorLabel`): bool
/* Métodos heredados */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propiedades

errorLabels
  Contiene un array de etiquetas de error asociadas a una excepción. Por ejemplo, las etiquetas de error pueden usarse para detectar si una transacción puede volver a intentarse de forma segura si está presente la etiqueta `TransientTransactionError`. La existencia de una etiqueta de error específica debe verificarse con el método MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(), en lugar de interpretar manualmente esta propiedad `errorLabels`.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 1.6.0 | Se han añadido el método MongoDB\Driver\Exception\RuntimeException::hasErrorLabel() y la propiedad MongoDB\Driver\Exception\RuntimeException::errorLabels.

# MongoDB\Driver\Exception\RuntimeException::hasErrorLabel

(mongodb >= 1.6.0)

MongoDB\Driver\Exception\RuntimeException::hasErrorLabel — Devuelve si un label de error está asociado con una excepción

### Descripción

final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool

Devuelve si el `errorLabel` ha sido definido para esta excepción. Los labels de error son definidos por el servidor o por la extensión para indicar situaciones específicas donde se desea decidir cómo manejar una excepción específica. Una situación común sería determinar si se puede relanzar una transacción que ha fallado debido a un error pasajero (como un error de red o un conflicto de transacción) sin problemas. Ejemplos de labels de error son `TransientTransactionError` y `UnknownTransactionCommitResult`.

### Parámetros

`errorLabel`
  El nombre del `errorLabel` a verificar.

### Valores devueltos

Si el `errorLabel` proporcionado está asociado con esta excepción.

### Ver también

- MongoDB\Driver\Session::commitTransaction() - Valida la transacción
- » Documentación de MongoDB sobre las transacciones

## Tabla de contenidos

- MongoDB\Driver\Exception\RuntimeException::hasErrorLabel — Devuelve si un label de error está asociado con una excepción

# La clase MongoDB\Driver\Exception\ServerException

(mongodb >= 1.5.0)

## Introducción

Clase base para las excepciones lanzadas por el servidor. El código de esta excepción y sus subclases corresponderá al código de error original del servidor.

## Sinopsis de la Clase

class MongoDB\Driver\Exception\ServerException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* Propiedades heredadas */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La clase MongoDB\Driver\Exception\SSLConnectionException

(mongodb >= 1.0.0)

Advertencia

Esta clase de excepción está DEPRECADA a partir de la versión 1.5.0 de la extensión y fue eliminada en la versión 2.0. Esta excepción nunca fue lanzada por la extensión. Las aplicaciones deben usar MongoDB\Driver\Exception\ConnectionException en su lugar.

## Introducción

Se lanza cuando el controlador no puede establecer una conexión SSL con el servidor.

## Sinopsis de la Clase

final class MongoDB\Driver\Exception\SSLConnectionException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* Propiedades heredadas */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La clase MongoDB\Driver\Exception\UnexpectedValueException

(mongodb >= 1.0.0)

## Introducción

Lanzada cuando el controlador encuentra un valor inesperado (por ejemplo, durante la serialización o deserialización BSON).

## Sinopsis de la Clase

class MongoDB\Driver\Exception\UnexpectedValueException extends UnexpectedValueException implements MongoDB\Driver\Exception\Exception {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La clase MongoDB\Driver\Exception\WriteException

(mongodb >= 1.0.0)

Advertencia

Esta clase de excepción está DEPRECADA desde la versión 1.20.0 de la extensión y ha sido eliminada en la versión 2.0. Esta excepción nunca fue lanzada directamente por la extensión. Las aplicaciones deberían utilizar MongoDB\Driver\Exception\BulkWriteException en su lugar.

## Introducción

Clase base para las excepciones lanzadas por una operación de escritura fallida. La excepción encapsula un objeto MongoDB\Driver\WriteResult.

## Sinopsis de la Clase

abstract class MongoDB\Driver\Exception\WriteException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Propiedades */
protected MongoDB\Driver\WriteResult $writeResult;
/* Propiedades heredadas */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
final public function getWriteResult(): MongoDB\Driver\WriteResult
/* Métodos heredados */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propiedades

writeResult
  MongoDB\Driver\WriteResult asociado a la operación de escritura fallida.

## Historial de cambios

Versión | Descripción
--- | ---
PECL mongodb 2.0.0 | Esta clase ha sido eliminada.
PECL mongodb 1.20.0 | Esta clase ha sido deprecada y será eliminada en la versión 2.0.
PECL mongodb 1.5.0 | Esta clase ahora extiende MongoDB\Driver\Exception\ServerException en lugar de MongoDB\Driver\Exception\RuntimeException.

# MongoDB\Driver\Exception\WriteException::getWriteResult

(mongodb >= 1.0.0)

MongoDB\Driver\Exception\WriteException::getWriteResult — Devuelve el WriteResult para la operación de escritura que falló

### Descripción

final public function MongoDB\Driver\Exception\WriteException::getWriteResult(): MongoDB\Driver\WriteResult

Devuelve el MongoDB\Driver\WriteResult para la operación de escritura que falló. Los métodos MongoDB\Driver\WriteResult::getWriteErrors() y MongoDB\Driver\WriteResult::getWriteConcernError() pueden ser utilizados para recuperar más detalles sobre el fallo.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El MongoDB\Driver\WriteResult para la operación de escritura que falló.

### Ejemplos

Ejemplo #1 Ejemplo con MongoDB\Driver\Exception\WriteException::getWriteResult()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost');
    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch (MongoDB\Driver\Exception\WriteException $e) {
        $writeResult = $e->getWriteResult();

        if ($writeConcernError = $writeResult->getWriteConcernError()) {
            var_dump($writeConcernError);
        }

        if ($writeErrors = $writeResult->getWriteErrors()) {
            var_dump($writeErrors);
        }
    }

    ?>

Resultado del ejemplo anterior es similar a:

    array(1) {
      [0]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(70) "E11000 duplicate key error index: db.collection.$_id_ dup key: { : 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(1)
        ["info"]=>
        NULL
      }
    }

### Ver también

- MongoDB\Driver\WriteResult
- MongoDB\Driver\Manager::executeBulkWrite() - Ejecuta una o varias operaciones de escritura

## Tabla de contenidos

- MongoDB\Driver\Exception\WriteException::getWriteResult — Devuelve el WriteResult para la operación de escritura que falló

# Jerarquía de clases de excepciones de MongoDB

La jerarquía de clases para las excepciones de MongoDB está modelada siguiendo la de las excepciones SPL. Las clases base extienden su contraparte de SPL y todas las clases de excepciones en la extensión implementan la interfaz MongoDB\Driver\Exception\Exception.

- MongoDB\Driver\Exception\LogicException (extiende LogicException)
- MongoDB\Driver\Exception\InvalidArgumentException (extiende InvalidArgumentException)
- MongoDB\Driver\Exception\UnexpectedValueException (extiende UnexpectedValueException)
- MongoDB\Driver\Exception\RuntimeException (extiende RuntimeException)
  - MongoDB\Driver\Exception\ConnectionException
    - MongoDB\Driver\Exception\AuthenticationException
    - MongoDB\Driver\Exception\ConnectionTimeoutException
    - MongoDB\Driver\Exception\SSLConnectionException (obsoleto)
  - MongoDB\Driver\Exception\EncryptionException
  - MongoDB\Driver\Exception\ServerException
    - MongoDB\Driver\Exception\BulkWriteCommandException
    - MongoDB\Driver\Exception\CommandException
    - MongoDB\Driver\Exception\ExecutionTimeoutException
    - MongoDB\Driver\Exception\WriteException (obsoleto)
      - MongoDB\Driver\Exception\BulkWriteException

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
- Constantes predefinidas
- Tutoriales
  - Utilizar la biblioteca PHP para MongoDB (PHPLIB)
  - Monitoreo del rendimiento de la aplicación (Application Performance Monitoring - APM)
- Arquitectura y funcionalidades especiales — Explicaciones de la arquitectura del controlador y de las funcionalidades especiales
  - Arquitectura — Visión general de la arquitectura
  - Conexiones — Gestión de la conexión y de la persistencia
  - Persistir datos — Serialización y deserialización de variables PHP en MongoDB
- Seguridad
  - Ataques por inyección de peticiones
  - Ataques por inyección de scripts
- MongoDB\Driver — Clases de la extensión MongoDB
  - MongoDB\Driver\Manager — La clase MongoDB\Driver\Manager
  - MongoDB\Driver\Command — La clase MongoDB\Driver\Command
  - MongoDB\Driver\Query — La clase MongoDB\Driver\Query
  - MongoDB\Driver\BulkWrite — La clase MongoDB\Driver\BulkWrite
  - MongoDB\Driver\BulkWriteCommand — La clase MongoDB\Driver\BulkWriteCommand
  - MongoDB\Driver\Session — La clase MongoDB\Driver\Session
  - MongoDB\Driver\ClientEncryption — La clase MongoDB\Driver\ClientEncryption
  - MongoDB\Driver\ServerApi — La clase MongoDB\Driver\ServerApi
  - MongoDB\Driver\WriteConcern — La clase MongoDB\Driver\WriteConcern
  - MongoDB\Driver\ReadPreference — La clase MongoDB\Driver\ReadPreference
  - MongoDB\Driver\ReadConcern — La clase MongoDB\Driver\ReadConcern
  - MongoDB\Driver\Cursor — La clase MongoDB\Driver\Cursor
  - MongoDB\Driver\CursorId — La clase MongoDB\Driver\CursorId
  - MongoDB\Driver\CursorInterface — La interfaz MongoDB\Driver\CursorInterface
  - MongoDB\Driver\Server — La clase MongoDB\Driver\Server
  - MongoDB\Driver\ServerDescription — La clase MongoDB\Driver\ServerDescription
  - MongoDB\Driver\TopologyDescription — La clase MongoDB\Driver\TopologyDescription
  - MongoDB\Driver\WriteConcernError — La clase MongoDB\Driver\WriteConcernError
  - MongoDB\Driver\WriteError — La clase MongoDB\Driver\WriteError
  - MongoDB\Driver\WriteResult — La clase MongoDB\Driver\WriteResult
  - MongoDB\Driver\BulkWriteCommandResult — La clase MongoDB\Driver\BulkWriteCommandResult
- MongoDB\BSON — Clases y funciones BSON de MongoDB
  - Funciones
  - MongoDB\BSON\Document — la clase MongoDB\BSON\Document
  - MongoDB\BSON\PackedArray — La clase MongoDB\BSON\PackedArray
  - MongoDB\BSON\Iterator — La clase MongoDB\BSON\Iterator
  - MongoDB\BSON\Binary — La clase MongoDB\BSON\Binary
  - MongoDB\BSON\VectorType — La enumeración MongoDB\BSON\VectorType
  - MongoDB\BSON\Decimal128 — La clase MongoDB\BSON\Decimal128
  - MongoDB\BSON\Javascript — La clase MongoDB\BSON\Javascript
  - MongoDB\BSON\MaxKey — La clase MongoDB\BSON\MaxKey
  - MongoDB\BSON\MinKey — La clase MongoDB\BSON\MinKey
  - MongoDB\BSON\ObjectId — La clase MongoDB\BSON\ObjectId
  - MongoDB\BSON\Regex — La clase MongoDB\BSON\Regex
  - MongoDB\BSON\Timestamp — La clase MongoDB\BSON\Timestamp
  - MongoDB\BSON\UTCDateTime — La clase MongoDB\BSON\UTCDateTime
  - MongoDB\BSON\Type — La interfaz MongoDB\BSON\Type
  - MongoDB\BSON\Persistable — La clase MongoDB\BSON\Persistable
  - MongoDB\BSON\Serializable — La interfaz MongoDB\BSON\Serializable
  - MongoDB\BSON\Unserializable — La interfaz MongoDB\BSON\Unserializable
  - MongoDB\BSON\BinaryInterface — La interfaz MongoDB\BSON\BinaryInterface
  - MongoDB\BSON\Decimal128Interface — La interfaz MongoDB\BSON\Decimal128Interface
  - MongoDB\BSON\JavascriptInterface — La interfaz MongoDB\BSON\JavascriptInterface
  - MongoDB\BSON\MaxKeyInterface — La interfaz MongoDB\BSON\MaxKeyInterface
  - MongoDB\BSON\MinKeyInterface — La interfaz MongoDB\BSON\MinKeyInterface
  - MongoDB\BSON\ObjectIdInterface — La interfaz MongoDB\BSON\ObjectIdInterface
  - MongoDB\BSON\RegexInterface — La interfaz MongoDB\BSON\RegexInterface
  - MongoDB\BSON\TimestampInterface — La interfaz MongoDB\BSON\TimestampInterface
  - MongoDB\BSON\UTCDateTimeInterface — La interfaz MongoDB\BSON\UTCDateTimeInterface
  - MongoDB\BSON\DBPointer — La clase MongoDB\BSON\DBPointer
  - MongoDB\BSON\Int64 — La clase MongoDB\BSON\Int64
  - MongoDB\BSON\Symbol — La clase MongoDB\BSON\Symbol
  - MongoDB\BSON\Undefined — La clase MongoDB\BSON\Undefined
- MongoDB\Driver\Monitoring — Monitorización de clases y funciones de suscriptor
  - Funciones
  - MongoDB\Driver\Monitoring\CommandFailedEvent — La clase MongoDB\Driver\Monitoring\CommandFailedEvent
  - MongoDB\Driver\Monitoring\CommandStartedEvent — La clase MongoDB\Driver\Monitoring\CommandStartedEvent
  - MongoDB\Driver\Monitoring\CommandSucceededEvent — La clase MongoDB\Driver\Monitoring\CommandSucceededEvent
  - MongoDB\Driver\Monitoring\ServerChangedEvent — La clase MongoDB\Driver\Monitoring\ServerChangedEvent
  - MongoDB\Driver\Monitoring\ServerClosedEvent — La clase MongoDB\Driver\Monitoring\ServerClosedEvent
  - MongoDB\Driver\Monitoring\ServerOpeningEvent — La clase MongoDB\Driver\Monitoring\ServerOpeningEvent
  - MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent — La clase MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent
  - MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent — La clase MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent
  - MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent — La clase MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent
  - MongoDB\Driver\Monitoring\TopologyChangedEvent — La clase MongoDB\Driver\Monitoring\TopologyChangedEvent
  - MongoDB\Driver\Monitoring\TopologyClosedEvent — La clase MongoDB\Driver\Monitoring\TopologyClosedEvent
  - MongoDB\Driver\Monitoring\TopologyOpeningEvent — La clase MongoDB\Driver\Monitoring\TopologyOpeningEvent
  - MongoDB\Driver\Monitoring\CommandSubscriber — La interfaz MongoDB\Driver\Monitoring\CommandSubscriber
  - MongoDB\Driver\Monitoring\SDAMSubscriber — La interfaz MongoDB\Driver\Monitoring\SDAMSubscriber
  - MongoDB\Driver\Monitoring\Subscriber — La interfaz MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Exception — Clases de excepciones
  - MongoDB\Driver\Exception\AuthenticationException — La clase MongoDB\Driver\Exception\AuthenticationException
  - MongoDB\Driver\Exception\BulkWriteException — La clase MongoDB\Driver\Exception\BulkWriteException
  - MongoDB\Driver\Exception\BulkWriteCommandException — La clase MongoDB\Driver\Exception\BulkWriteCommandException
  - MongoDB\Driver\Exception\CommandException — La clase MongoDB\Driver\Exception\CommandException
  - MongoDB\Driver\Exception\ConnectionException — La clase MongoDB\Driver\Exception\ConnectionException
  - MongoDB\Driver\Exception\ConnectionTimeoutException — La clase MongoDB\Driver\Exception\ConnectionTimeoutException
  - MongoDB\Driver\Exception\EncryptionException — La clase MongoDB\Driver\Exception\EncryptionException
  - MongoDB\Driver\Exception\Exception — La interfaz MongoDB\Driver\Exception\Exception
  - MongoDB\Driver\Exception\ExecutionTimeoutException — La clase MongoDB\Driver\Exception\ExecutionTimeoutException
  - MongoDB\Driver\Exception\InvalidArgumentException — La clase MongoDB\Driver\Exception\InvalidArgumentException
  - MongoDB\Driver\Exception\LogicException — La clase MongoDB\Driver\Exception\LogicException
  - MongoDB\Driver\Exception\RuntimeException — La clase MongoDB\Driver\Exception\RuntimeException
  - MongoDB\Driver\Exception\ServerException — La clase MongoDB\Driver\Exception\ServerException
  - MongoDB\Driver\Exception\SSLConnectionException — La clase MongoDB\Driver\Exception\SSLConnectionException
  - MongoDB\Driver\Exception\UnexpectedValueException — La clase MongoDB\Driver\Exception\UnexpectedValueException
  - MongoDB\Driver\Exception\WriteException — La clase MongoDB\Driver\Exception\WriteException
  - Jerarquía de clases — Jerarquía de clases de excepciones de MongoDB

# Plugins y drivers MySQL

PHP ofrece varios drivers y plugins MySQL para acceder y gestionar MySQL.

Las diferencias y las funcionalidades de las extensiones MySQL se describen en el resumen de esta sección.

Las extensiones listadas soportan el protocolo MySQL. Algunos ejemplos de servidores de bases de datos compatibles son » MariaDB Server, » MySQL Server, » Percona Server para MySQL, y » TiDB.

# Visión general de los drivers PHP MySQL

# Introducción

Existen varias APIs PHP para acceder a una base de datos MySQL. Los usuarios pueden elegir entre las extensiones mysqli o PDO_MySQL.

Esta guía explica la terminología utilizada para describir cada una de ellas, proporciona información sobre la elección de la API a utilizar, así como información que ayuda a elegir la biblioteca MySQL a utilizar con la API.

# Visión general de la terminología

Esta sección proporciona una introducción a las opciones disponibles al desarrollar una aplicación PHP que debe interactuar con una base de datos MySQL.

¿Qué es una API?

Una interfaz de programación de aplicaciones, o API, define las clases, los métodos, las funciones y las variables que su aplicación necesita para realizar las tareas deseadas. En el caso de las aplicaciones PHP que necesitan comunicarse con bases de datos, las APIs necesarias suelen exponerse a través de extensiones PHP.

Las APIs pueden ser procedimentales u orientadas a objetos. Con una API procedimental, se llaman funciones para realizar las tareas, con una API orientada a objetos, se instancian las clases, luego se llaman los métodos en los objetos resultantes. La segunda interfaz es generalmente preferida ya que es más moderna y permite organizar mejor el código fuente.

Al escribir aplicaciones PHP que necesitan conectarse a un servidor MySQL, hay varias opciones de API disponibles. Este documento abordará lo que está disponible, y cómo elegir la mejor solución para su aplicación.

¿Qué es un conector?

En la documentación de MySQL, el término conector se refiere a la parte del programa que permite a su aplicación conectarse al servidor de base de datos MySQL. MySQL proporciona conectores para muchos lenguajes, incluyendo PHP.

Si su aplicación PHP necesita comunicarse con un servidor de base de datos, debe escribir su código PHP para realizar tareas como conectarse al servidor de base de datos, consultar la base de datos y otras tareas relacionadas con la base de datos. El programa es requerido para proporcionar la API a utilizar por su aplicación PHP, pero también para gestionar la comunicación entre su aplicación y el servidor de base de datos, utilizando bibliotecas intermedias si es necesario. Este programa suele denominarse conector, ya que permite a su aplicación conectarse al servidor de base de datos.

¿Qué es un driver?

Un driver es una parte de programa cuyo objetivo es comunicarse con un tipo específico de servidor de base de datos. El driver también puede llamar a una biblioteca, como la biblioteca cliente MySQL o el driver nativo MySQL. Estas bibliotecas implementan el protocolo de bajo nivel utilizado para comunicarse con el servidor de base de datos MySQL.

Por ejemplo, la capa de abstracción de base de datos PHP Data Objects (PDO) puede utilizar uno de los drivers específicos de base de datos. Uno de estos drivers disponibles es el driver PDO MYSQL, que proporciona una interfaz con el servidor MySQL.

A veces, las personas utilizan los términos conector y driver de manera intercambiable, lo que puede causar confusión. En la documentación de MySQL, el término driver se reserva al programa que proporciona la parte específica de la base de datos de un conector.

¿Qué es una extensión?

En la documentación de PHP, se encuentra otro término - extensión. El código PHP está compuesto por un núcleo, con extensiones opcionales que permiten extender las funcionalidades del núcleo. Las extensiones PHP relacionadas con bases de datos, como la extensión `mysqli` se implementan utilizando el framework de extensiones PHP.

Típicamente, una extensión expone una API al programador PHP, permitiéndole algunas facilidades durante la programación. Sin embargo, algunas extensiones que utilizan el framework de extensión PHP no exponen ninguna API al programador PHP.

La extensión driver PDO MySQL, por ejemplo, no expone ninguna API al programador PHP, pero proporciona una interfaz a la capa PDO.

Los términos API y extensión no deben considerarse como significando lo mismo, ya que una extensión no expone necesariamente una API al programador.

# Elegir una API

PHP ofrece diferentes APIs para conectarse a MySQL. A continuación, se encuentran las APIs proporcionadas por las extensiones mysqli y PDO. Cada ejemplo de código crea una conexión a un servidor MySQL que se ejecuta en el dominio "example.com", utilizando el nombre de usuario "user", la contraseña "password". Y se ejecuta una consulta para saludar al usuario.

Ejemplo #1 Comparación de las APIs MySQL

    <?php
    // mysqli
    $mysqli = new mysqli("example.com", "user", "password", "database");
    $result = $mysqli->query("SELECT '¡Hola, querido usuario de MySQL!' AS _message FROM DUAL");
    $row = $result->fetch_assoc();
    echo htmlentities($row['_message']);

    // PDO
    $pdo = new PDO('mysql:host=example.com;dbname=database', 'user', 'password');
    $statement = $pdo->query("SELECT '¡Hola, querido usuario de MySQL!' AS _message FROM DUAL");
    $row = $statement->fetch(PDO::FETCH_ASSOC);
    echo htmlentities($row['_message']);

Comparación de funcionalidades

El rendimiento global de las dos extensiones puede considerarse idéntico. Sin embargo, el rendimiento de la extensión constituye solo una fracción del tiempo total de ejecución de una solicitud web PHP. A menudo, el impacto es inferior al 0.1%.

| ext/mysqli | PDO_MySQL
--- | --- | ---
Introducida en la versión de PHP | 5.0 | 5.1
Incluida con PHP 7.x y 8.x | Sí | Sí
Estado de desarrollo | Activo | Activo
Ciclo de vida | Activo | Activo
Recomendado para nuevos proyectos | Sí | Sí
Interfaz orientada a objetos | Sí | Sí
Interfaz procedimental | Sí | No
La API soporta consultas no bloqueantes, asíncronas con mysqlnd | Sí | No
Conexiones persistentes disponibles | Sí | Sí
La API soporta juegos de caracteres | Sí | Sí
La API soporta consultas preparadas del lado del servidor | Sí | Sí
La API soporta consultas preparadas del lado del cliente | No | Sí
La API soporta procedimientos almacenados | Sí | Sí
La API soporta consultas múltiples | Sí | La mayoría
La API soporta transacciones | Sí | Sí
Las transacciones pueden controlarse con SQL | Sí | Sí
Soporta todas las funcionalidades de MySQL 5.1+ | Sí | La mayoría

# Elegir una biblioteca

Las extensiones PHP mysqli y PDO_MySQL son envolventes ligeras de una biblioteca cliente C. Las extensiones pueden utilizar la biblioteca mysqlnd, o la biblioteca `libmysqlclient`. La elección de la biblioteca se realiza en el momento de la compilación.

La biblioteca mysqlnd forma parte de la distribución de PHP. Ofrece funcionalidades como conexiones perezosas, caché de consultas, que no están disponibles con libmysqlclient, por lo que se recomienda utilizar la biblioteca interna mysqlnd. Ver la documentación de mysqlnd para obtener más información, así como una lista de las funcionalidades que ofrece.

Ejemplo #1 Comando de configuración para el uso de mysqlnd o libmysqlclient

    // Recomendado, compilación con mysqlnd
    $ ./configure --with-mysqli=mysqlnd --with-pdo-mysql=mysqlnd

    // Alternativamente recomendado, compilación con mysqlnd
    $ ./configure --with-mysqli --with-pdo-mysql

    // No recomendado, compilación con libmysqlclient
    $ ./configure --with-mysqli=/path/to/mysql_config --with-pdo-mysql=/path/to/mysql_config

Ejemplo #2 Comparación de las instrucciones preparadas

    <?php
    // mysqli
    $mysqli = new mysqli("example.com", "usuario", "contraseña", "base de datos");
    $statement = $mysqli->prepare("SELECT District FROM City WHERE Name=?");
    $statement->execute(["Amersfoort"]);
    $result = $statement->get_result();
    $row = $result->fetch_assoc();
    echo htmlentities($row['District']);

    // PDO
    $pdo = new PDO('mysql:host=example.com;dbname=base de datos', 'usuario', 'contraseña');
    $statement = $pdo->prepare("SELECT District FROM City WHERE Name=?");
    $statement->execute(["Amersfoort"]);
    $row = $statement->fetch(PDO::FETCH_ASSOC);
    echo htmlentities($row['District']);

Comparación de funcionalidades de las bibliotecas

Se recomienda utilizar la biblioteca mysqlnd en lugar de la biblioteca cliente servidor MySQL (libmysqlclient). Ambas bibliotecas son soportadas y mejoradas continuamente.

| Driver nativo MySQL (mysqlnd) | Biblioteca cliente servidor MySQL (`libmysqlclient`)
--- | --- | ---
Forma parte de la distribución de PHP | Sí | No
Introducido en versión de PHP | 5.3.0 | N/A
Licencia | Licencia PHP 3.01 | Doble licencia
Estado de desarrollo | Activo | Activo
Ciclo de vida | Sin fin anunciado | Sin fin anunciado
Compilado por defecto (para todas las extensiones MySQL) | Sí | No
Soporte del protocolo de compresión | Sí | Sí
Soporte de SSL | Sí | Sí
Soporte de pipes nombrados | Sí | Sí
Consultas no bloqueantes, asíncronas | Sí | No
Estadísticas de rendimiento | Sí | No
LOAD LOCAL INFILE respeta la directiva open_basedir | Sí | No
Uso del sistema de gestión de memoria nativo de PHP (es decir, sigue los límites de memoria de PHP) | Sí | No
Devuelve las columnas numéricas en forma de double (COM_QUERY) | Sí | No
Devuelve las columnas numéricas en forma de string (COM_QUERY) | Sí | Sí
API del plugin | Sí | Limitada
Reconexión automática | No | Opcional

# Conceptos

## Tabla de contenidos

- Consultas con o sin almacenamiento en memoria
- Juegos de caracteres

Estos conceptos son específicos para los drivers MySQL para PHP.

## Consultas con o sin almacenamiento en memoria

Las consultas utilizan por omisión el modo de almacenamiento en memoria. Esto significa que el resultado de las consultas se transfiere inmediatamente del servidor MySQL a PHP y se conserva en la memoria del proceso PHP. Esto permite operaciones complementarias como contar el número de resultados, y desplazar el puntero de resultado actual. También permite ejecutar consultas adicionales sobre la misma conexión mientras se trabaja con el conjunto de resultados. La desventaja del almacenamiento en memoria es que los conjuntos de resultados grandes pueden requerir mucha más memoria. La memoria permanecerá ocupada hasta que todas las referencias a los conjuntos de resultados sean desactivadas o que los conjuntos de resultados sean liberados explícitamente, lo cual ocurre de manera automática al final del proceso. La terminología "store result" también se utiliza con el modo de almacenamiento en memoria, ya que la totalidad de los resultados se almacenan a la vez.

> Nota: Cuando se utiliza libmysqlclient como biblioteca, el límite de memoria de PHP no contará la memoria utilizada para los conjuntos de resultados a menos que los datos sean leídos en las variables PHP. Con mysqlnd, la memoria utilizada incluirá el conjunto de resultados completo.

Las consultas sin almacenamiento en memoria, las consultas MySQL ejecutan su consulta y luego esperan que los datos del servidor MySQL sean recuperados. Esto utiliza menos memoria en el lado de PHP, pero puede aumentar la carga en el servidor. A menos que el conjunto de resultados completo haya sido recuperado desde el servidor, ninguna otra consulta puede ser enviada sobre la misma conexión. Las consultas sin almacenamiento en memoria también pueden hacer referencia a un "use result". Una vez que todas las líneas del conjunto de resultados han sido recuperadas, el conjunto de resultados desaparece y ya no es posible recorrerlo nuevamente.

Siguiendo estas características, las consultas sin almacenamiento en memoria deben ser utilizadas únicamente cuando se espera obtener un gran conjunto de resultados que será procesado secuencialmente. Las consultas sin almacenamiento en memoria presentan varias trampas que las hacen más difíciles de utilizar, por ejemplo el número de líneas en el conjunto de resultados no es conocido antes de que la última línea sea recuperada.

Debido a que las consultas son almacenadas en memoria por omisión, los ejemplos a continuación muestran cómo ejecutar consultas, con cada API, sin almacenamiento en memoria.

Ejemplo #1 Ejemplo de consultas sin almacenamiento en memoria: mysqli

    <?php
    $mysqli  = new mysqli("localhost", "my_user", "my_password", "world");
    $unbufferedResult = $mysqli->query("SELECT Name FROM City", MYSQLI_USE_RESULT);

    foreach ($unbufferedResult as $row) {
        echo $row['Name'] . PHP_EOL;
    }
    ?>

Ejemplo #2 Ejemplo de consultas sin almacenamiento en memoria: pdo_mysql

    <?php
    $pdo = new PDO("mysql:host=localhost;dbname=world", 'my_user', 'my_password');
    $pdo->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, false);

    $unbufferedResult = $pdo->query("SELECT Name FROM City");
    foreach ($unbufferedResult as $row) {
        echo $row['Name'] . PHP_EOL;
    }
    ?>

## Juegos de caracteres

Idealmente, un juego de caracteres adecuado debe ser definido a nivel del servidor, operación descrita en la sección » Configuración del juego de caracteres del manual del servidor MySQL. Alternativamente, cada API MySQL ofrece un método para definir el juego de caracteres durante la ejecución.

Precaución

# El juego de caracteres y el escape de caracteres

El juego de caracteres debe ser comprendido y definido, sabiendo que tiene un efecto en cada acción, y tiene implicaciones a nivel de seguridad. Por ejemplo, el mecanismo de escape (i.e. mysqli_real_escape_string() para mysqli, y PDO::quote() para PDO_MySQL) utilizará esta configuración. Es importante tener en cuenta que estas funciones no utilizarán el juego de caracteres definido con una consulta, por lo tanto, el ejemplo siguiente no tendrá ningún efecto sobre el juego de caracteres:

Ejemplo #1 Problemas al definir el juego de caracteres con SQL

    <?php

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    // NO afectará $mysqli->real_escape_string();
    $mysqli->query("SET NAMES utf8mb4");

    // NO afectará $mysqli->real_escape_string();
    $mysqli->query("SET CHARACTER SET utf8mb4");

    // Pero esto afectará $mysqli->real_escape_string();
    $mysqli->set_charset('utf8mb4');

    // Pero esto NO lo afectará (UTF-8 en comparación con utf8mb4) -- no utilice guiones aquí
    $mysqli->set_charset('UTF-8');
    ?>

A continuación, los ejemplos que demuestran cómo modificar correctamente el juego de caracteres durante la ejecución utilizando cada una de las APIs.

> Nota: Confusión posible con UTF-8
> Debido a que los nombres de los juegos de caracteres en MySQL no contienen guiones, la cadena "utf8" es correcta en MySQL y definirá el juego de caracteres en UTF-8. La cadena "UTF-8" no es correcta, y utilizar "utf-8" fallará al modificar el juego de caracteres.

Ejemplo #2 Ejemplo de definición del juego de caracteres: mysqli

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    echo 'Juego de caracteres inicial: ' . $mysqli->character_set_name() . "\n";

    if (!$mysqli->set_charset('utf8mb4')) {
        printf("Error al cargar el juego de caracteres utf8mb4: %s\n", $mysqli->error);
        exit;
    }

    echo 'Su juego de caracteres actual es: ' . $mysqli->character_set_name() . "\n";
    ?>

Ejemplo #3 Ejemplo de definición del juego de caracteres: pdo_mysql

    <?php
    $pdo = new PDO("mysql:host=localhost;dbname=world;charset=utf8mb4", 'my_user', 'my_pass');
    ?>

- Visión general de la terminología
- Elegir una API
- Elegir una biblioteca
- Conceptos
  - Consultas con o sin almacenamiento en memoria
  - Juegos de caracteres

# Extensión mysqli

# Introducción

La extensión `mysqli` permite acceder a las funcionalidades proporcionadas por MySQL 4.1 y superiores. Para más información sobre el servidor de base de datos MySQL, puede consultarse » http://www.mysql.com/

Una lista de los programas disponibles para utilizar MySQL desde PHP puede encontrarse en Introducción

La documentación de MySQL está disponible en » http://dev.mysql.com/doc/.

Fragmentos del manual de MySQL han sido incluidos en la documentación de PHP con el permiso de Oracle Corporation.

Los ejemplos utilizan ya sea la base de datos » world, ya sea la base de datos » sakila, que son de libre acceso.

# Introducción

Esta sección proporciona información sobre las soluciones disponibles al desarrollar una aplicación PHP que necesita interactuar con una base de datos MySQL.

¿Qué es una API?

Una Interfaz de Programación de Aplicaciones, o `Application Programming Interface` (API), define las clases, métodos, funciones y variables que su aplicación utilizará para ejecutar diferentes tareas. En el caso de las aplicaciones PHP, las comunicaciones con una base de datos se realizan generalmente a través de una API que está expuesta en una extensión PHP.

Las API pueden ser procedimentales u orientadas a objetos. Con una API procedimental, se pueden llamar funciones para ejecutar comandos; con una API orientada a objetos, es necesario crear objetos y llamar a los métodos de estos objetos. De las dos, esta última es generalmente preferida, ya que es más moderna y conduce a un código más organizado.

Al escribir aplicaciones PHP que deben conectarse a MySQL, hay varias API disponibles. Este documento presenta estas API y proporciona la información necesaria para elegir la mejor solución para su aplicación.

¿Qué es un conector?

En la documentación de MySQL, el término conector se refiere a un software que permite a una aplicación conectarse a una base de datos MySQL. MySQL proporciona conectores para una amplia colección de lenguajes, incluyendo PHP.

Si su aplicación PHP necesita comunicarse con un servidor de base de datos, es necesario escribir código para poder conectarse, enviar consultas al servidor, etc. Se requiere un software para proporcionar la interfaz que PHP utilizará y gestionar las comunicaciones entre su aplicación y el servidor de base de datos: eventualmente, se necesitan bibliotecas intermedias. Estos programas se denominan genéricamente conectores, ya que permiten conectarse a un servidor de base de datos.

¿Qué es un controlador?

Un controlador es un software diseñado para comunicarse con un tipo particular de base de datos. Un controlador también puede llamarse biblioteca, como la `MySQL Client Library` o el MySQL Native Driver. Estas bibliotecas implementan el protocolo de bajo nivel para comunicarse con un servidor MySQL.

Por ejemplo, la capa de abstracción de base de datos PHP Data Objects (PDO) utiliza uno o más controladores de base de datos. Uno de estos controladores es el controlador PDO MYSQL, que permite interactuar con MySQL.

A veces, los desarrolladores utilizan los términos conector y controlador de manera intercambiable, lo que puede resultar confuso. En la documentación de MySQL, el término controlador está reservado para los programas que son la interfaz específica con la base de datos del paquete.

¿Qué es una extensión?

En la documentación de PHP, se encontrará con otro término: extensión. El código PHP está compuesto por un núcleo, con extensiones opcionales. Las extensiones relacionadas con MySQL de PHP, como la extensión `mysqli` y la extensión de controlador PDO MySQL, están implementadas utilizando el framework de extensión de PHP.

Una extensión expone típicamente una API a un desarrollador PHP, para facilitar la programación. Sin embargo, algunas extensiones que utilizan el framework de PHP no exponen ninguna API al desarrollador PHP.

La extensión de controlador PDO MySQL, por ejemplo, no expone ninguna API al desarrollador PHP, pero proporciona una interfaz a la capa PDO.

Los términos API y extensión no deberían significar lo mismo, ya que una extensión PHP no proporciona necesariamente una API particular al desarrollador PHP.

¿Cuáles son las API de PHP para MySQL?

Hay dos API principales para conectarse a MySQL:

- La extensión mysqli

- PHP Data Objects (PDO)

Cada una tiene sus ventajas e inconvenientes. Las siguientes secciones ofrecen una presentación rápida de cada API.

¿Qué es la extensión mysqli de PHP?

La extensión `mysqli`, o como a veces se la denomina, la extensión MySQL mejorada (i para `improved` en inglés), fue desarrollada para aprovechar las nuevas características de los sistemas MySQL versión 4.1.3 y posteriores. La extensión `mysqli` está incluida en PHP desde la versión 5.

La extensión `mysqli` tiene una gran cantidad de ventajas y mejoras con respecto a la extensión `mysql`:

- Interfaz orientada a objetos

- Soporte para sentencias preparadas

- Soporte para múltiples sentencias

- Soporte para transacciones

- Capacidades avanzadas de depuración

Además de una interfaz orientada a objetos, la extensión también ofrece una interfaz procedimental.

La extensión `mysqli` está compilada con el framework de PHP, y su código fuente se encuentra en el directorio ext/mysqli.

Para más información sobre la extensión `mysqli`, consulte MySQLi.

¿Qué es la extensión PDO de PHP?

`PHP Data Objects`, o PDO, es una capa de abstracción de base de datos específica para PHP. PDO ofrece una API coherente para sus aplicaciones PHP, independientemente del tipo de base de datos con la que se trabaje. En teoría, si se utiliza PDO, se puede cambiar de base de datos, por ejemplo de Firebird a MySQL, y solo realizar cambios menores en el código PHP.

Otros ejemplos de capas de abstracción de base de datos incluyen JDBC para Java y DBI para Perl.

Si PDO tiene sus ventajas, como una API limpia, simple y portable, sus principales inconvenientes son que no permite utilizar todas las características avanzadas de las últimas versiones de MySQL. Por ejemplo, PDO no permite realizar consultas múltiples.

PDO está implementado utilizando el framework de PHP, y su código fuente se encuentra en el directorio ext/pdo.

Para más información sobre PDO, consulte PDO.

¿Qué es el controlador MySQL para PDO?

El controlador PDO MYSQL no es una API en sí mismo, al menos desde el punto de vista del desarrollador PHP. De hecho, el controlador PDO MYSQL forma parte de PDO, y proporciona las funcionalidades específicas de MySQL. El desarrollador llama a la API PDO, pero PDO utiliza el controlador PDO MYSQL para gestionar las comunicaciones con MySQL.

El controlador PDO MYSQL forma parte de la gran familia de controladores PDO. Otros controladores disponibles gestionan las comunicaciones con Firebird y PostgreSQL, entre otros.

El controlador PDO MYSQL está implementado con el framework de extensión de PHP. Su código fuente se encuentra en el directorio ext/pdo_mysql. No expone ninguna API al desarrollador PHP.

Para más detalles sobre el controlador PDO de MySQL, consulte Controlador PDO MySQL.

¿Qué es el controlador nativo MySQL de PHP?

Para comunicarse con el servidor MySQL, la extensión `mysqli` y el controlador PDO MYSQL utilizan una biblioteca de bajo nivel que implementa el protocolo MySQL. En el pasado, la única biblioteca disponible era la `MySQL Client Library`, también llamada `libmysqlclient`.

Sin embargo, la interfaz presentada por `libmysqlclient` no estaba optimizada para las comunicaciones con PHP, y `libmysqlclient` estaba diseñada originalmente en C, para aplicaciones de tipo similar. Por esta razón, el controlador MySQL nativo `mysqlnd` fue desarrollado como una alternativa a `libmysqlclient` para aplicaciones PHP.

La extensión `mysqli` y el controlador MySQL nativo pueden configurarse individualmente para utilizar `libmysqlclient` o `mysqlnd`. Como `mysqlnd` fue diseñado específicamente para el sistema PHP, ofrece numerosas ventajas y mejoras con respecto a `libmysqlclient`. Se recomienda encarecidamente su uso.

El MySQL Native Driver está implementado sobre la base del framework de extensión de PHP. El código fuente se encuentra en ext/mysqlnd. No expone ninguna nueva API al desarrollador PHP.

Comparación de características

La siguiente tabla compara las características de los métodos principales para conectarse a MySQL desde PHP:

Comparación de las opciones de API MySQL para PHP
| Extensión mysqli | PDO (con el controlador PDO MySQL Driver y MySQL Native Driver)
--- | --- | ---
Versión de introducción en PHP | 5.0 | 5.0
Estado de desarrollo de MySQL | Desarrollo activo | Desarrollo activo
La API soporta juegos de caracteres | Sí | Sí
La API soporta sentencias preparadas | Sí | Sí
La API soporta sentencias preparadas del lado del cliente | No | Sí
La API soporta procedimientos almacenados | Sí | Sí
La API soporta múltiples sentencias | Sí | La mayoría
Todas las características de MySQL 4.1 y posteriores | Sí | La mayoría

# Guía de inicio rápido

## Tabla de contenidos

- Interfaces procedimentales y orientadas a objetos
- Conexiones
- Ejecución de consultas
- Las consultas preparadas
- Los procedimientos almacenados
- Consultas múltiples
- Soporte API para las transacciones
- Las metadatos

Esta guía de inicio rápido ayudará a familiarizarse con la API PHP MySQL.

Proporciona una visión general de la extensión mysqli. Se proporcionan ejemplos de código para todos los aspectos importantes de la API. Los conceptos básicos de la base de datos se explican con la precisión necesaria para comprender las especificidades de los conceptos de MySQL.

Requisitos: Se debe estar familiarizado con el lenguaje de programación PHP, el lenguaje SQL y tener algunos conocimientos básicos con el servidor MySQL.

## Interfaces procedimentales y orientadas a objetos

La extensión mysqli proporciona 2 interfaces. Soporta la programación procedimental así como la programación orientada a objetos.

Los usuarios migrantes desde la antigua extensión mysql preferirán la interfaz procedimental. Esta interfaz es similar a la utilizada por la antigua extensión mysql. En la mayoría de los casos, los nombres de funciones solo difieren por sus prefijos. Algunas funciones mysqli toman un manejador de conexión como primer argumento, mientras que la función correspondiente de la antigua interfaz mysql lo tomaba como argumento opcional en última posición.

Ejemplo #1 Migración fácil desde la antigua extensión mysql

    <?php

    $mysqli = mysqli_connect("example.com", "user", "password", "database");
    $result = mysqli_query($mysqli, "SELECT 'No se debe usar la extensión mysql deprecada para nuevos desarrollos. ' AS _msg FROM DUAL");
    $row = mysqli_fetch_assoc($result);
    echo $row['_msg'];

    $mysql = mysql_connect("example.com", "user", "password");
    mysql_select_db("test");
    $result = mysql_query("SELECT 'USE la extensión mysqli en su lugar.' AS _msg FROM DUAL", $mysql);
    $row = mysql_fetch_assoc($result);
    echo $row['_msg'];

El ejemplo anterior mostrará:

    No se debe usar la extensión mysql deprecada para nuevos desarrollos. USE la extensión mysqli en su lugar.

La interfaz orientada a objetos

Además de la interfaz procedimental, los usuarios pueden elegir utilizar la interfaz orientada a objetos. La documentación está organizada utilizando esta interfaz. Muestra las funciones agrupadas por sus propósitos, facilitando el inicio de la programación. La sección de referencia proporciona ejemplos sobre las dos sintaxis.

No hay diferencia significativa en términos de rendimiento entre las dos interfaces. Los usuarios pueden hacer su elección según sus preferencias personales.

Ejemplo #2 Interfaces procedimentales y orientadas a objetos

    <?php

    $mysqli = mysqli_connect("example.com", "user", "password", "database");
    $result = mysqli_query($mysqli, "SELECT 'Un mundo lleno de ' AS _msg FROM DUAL");
    $row = mysqli_fetch_assoc($result);
    echo $row['_msg'];

    $mysqli = new mysqli("example.com", "user", "password", "database");
    $result = $mysqli->query("SELECT 'opciones para complacer a todos.' AS _msg FROM DUAL");
    $row = $result->fetch_assoc();
    echo $row['_msg'];

El ejemplo anterior mostrará:

    Un mundo lleno de opciones para complacer a todos.

La interfaz orientada a objetos se utiliza en el inicio rápido de la documentación debido a que la sección de referencia está organizada de esta manera.

Mezcla de estilos

Es posible cambiar de un estilo a otro en cualquier momento, aunque no se recomienda por razones de claridad y estilo de codificación.

Ejemplo #3 Malo estilo de codificación

    <?php

    $mysqli = new mysqli("example.com", "user", "password", "database");
    $result = mysqli_query($mysqli, "SELECT 'Posible pero mal estilo.' AS _msg FROM DUAL");

    if ($row = $result->fetch_assoc()) {
        echo $row['_msg'];
    }

El ejemplo anterior mostrará:

    Posible pero mal estilo.

Ver también

- mysqli::__construct()
- mysqli::query()
- mysqli_result::fetch_assoc()
- $mysqli::connect_errno
- $mysqli::connect_error
- $mysqli::errno
- $mysqli::error
- Resumen de las funciones de la extensión MySQLi

## Conexiones

El servidor MySQL soporta el uso de diferentes capas de transporte para las conexiones. Las conexiones pueden utilizar TCP/IP, los sockets de dominio Unix o los tubos nombrados de Windows.

El nombre de host `localhost` tiene un significado especial. Está vinculado al uso de los sockets de dominio Unix. Para abrir una conexión TCP/IP en el host local, `127.0.0.1` debe ser utilizado en lugar de `localhost`.

Ejemplo #1 Significado especial de localhost

    <?php

    $mysqli = new mysqli("localhost", "user", "password", "database");

    echo $mysqli->host_info . "\n";

    $mysqli = new mysqli("127.0.0.1", "user", "password", "database", 3306);

    echo $mysqli->host_info . "\n";

El ejemplo anterior mostrará:

    Localhost via UNIX socket
    127.0.0.1 via TCP/IP

Parámetros por omisión de una conexión

Dependiendo de la función de conexión utilizada, algunos parámetros pueden ser omitidos. Si un parámetro no es proporcionado, entonces la extensión intentará utilizar los valores por omisión definidos en el archivo de configuración de PHP.

Ejemplo #2 Parámetros por omisión

    mysqli.default_host=192.168.2.27
    mysqli.default_user=root
    mysqli.default_pw=""
    mysqli.default_port=3306
    mysqli.default_socket=/tmp/mysql.sock

Estos valores de parámetros son entonces pasados a la biblioteca cliente utilizada por la extensión. Si la biblioteca cliente detecta un parámetro vacío o no definido, entonces utilizará los valores por omisión internos a la biblioteca.

Valores por omisión internos a la biblioteca para la conexión

Si el valor del host no está definido o es vacío, entonces la biblioteca cliente utilizará por omisión una conexión de tipo socket Unix en `localhost`. Si el socket no está definido o es vacío, y se solicita una conexión de tipo socket Unix, entonces se intentará una conexión al socket por omisión `/tmp/mysql.sock`.

En los sistemas Windows, el nombre de host `.` es interpretado por la biblioteca cliente como un intento de abrir un tubo nombrado de Windows para la conexión. En este caso, el parámetro socket es interpretado como un tubo nombrado. Si no es proporcionado o está vacío, entonces el socket (tubo nombrado) valdrá por omisión `\\.\pipe\MySQL`.

Si ni un socket de dominio Unix ni un tubo nombrado de Windows es proporcionado, se establecerá una conexión básica y si el valor del puerto no está definido, la biblioteca utilizará el puerto `3306`.

La biblioteca mysqlnd y la biblioteca cliente MySQL (libmysqlclient) implementan la misma lógica para determinar los valores por omisión.

Opciones de conexión

Las opciones de conexión están disponibles para, por ejemplo, definir comandos de inicialización a ejecutar durante la conexión, o para solicitar el uso de un juego de caracteres específico. Las opciones de conexión deben ser definidas antes de la conexión a la red.

Para definir una opción de conexión, la operación de conexión debe ser realizada en 3 pasos: creación de un manejador de conexión con mysqli_init() o mysqli::__construct(), definición de las opciones solicitadas utilizando mysqli::options(), y conexión a la red con mysqli::real_connect().

Cola de conexión

La extensión mysqli soporta las conexiones persistentes a la base de datos, que son conexiones especiales. Por omisión, cada conexión a una base de datos abierta por un script es cerrada explícitamente por el usuario durante la ejecución, o liberada automáticamente al final del script. Esto no es el caso de una conexión persistente. En efecto, será colocada en una cola para una reutilización futura, si una conexión al mismo servidor, utilizando el mismo nombre de usuario, la misma contraseña, el mismo socket, el mismo puerto, así como la misma base de datos es abierta. Esta reutilización permite aligerar la carga indebida por las conexiones.

Cada proceso PHP utiliza su propia cola de conexiones mysqli. Dependiendo del modelo de despliegue del servidor web, un proceso PHP puede servir una o varias peticiones. Sin embargo, una conexión en cola puede ser utilizada por uno o varios scripts posteriormente.

Las conexiones persistentes

Si una conexión persistente para una combinación de host, nombre de usuario, contraseña, socket, puerto y base de datos no utilizada no puede ser encontrada en la cola de conexión, entonces mysqli abrirá una nueva conexión. El uso de las conexiones persistentes puede ser activado o desactivado utilizando la directiva PHP mysqli.allow_persistent. El número total de conexiones abiertas por un script puede ser limitado con la directiva mysqli.max_links. El número máximo de conexiones persistentes por proceso PHP puede ser restringido con la directiva mysqli.max_persistent. Tenga en cuenta que el servidor web puede generar varios procesos PHP.

Una queja común contra las conexiones persistentes es que su estado no es re-initializado antes de la reutilización. Por ejemplo, las transacciones abiertas y no terminadas no son automáticamente anuladas. Además, las modificaciones autorizadas que ocurren entre el momento en que la conexión es colocada en cola y su reutilización no serán tomadas en cuenta. Este comportamiento puede ser visto como un efecto de borde no deseado. Por el contrario, el nombre `persistent` puede ser comprendido como una promesa sobre el hecho de que el estado persiste realmente.

La extensión mysqli soporta dos interpretaciones de una conexión persistente : estado persistente, y un estado re-initializado antes de la reutilización. Por omisión, será re-initializado. Antes de que una conexión persistente sea reutilizada, la extensión mysqli llama implícitamente a la función mysqli::change_user() para re-initializar el estado. La conexión persistente aparece al usuario como si acabara de ser abierta. Ninguna traza de un uso anterior será visible.

La función mysqli::change_user() es una operación costosa. Para mejores rendimientos, los usuarios pueden querer re-compilar la extensión con el flag de compilación `MYSQLI_NO_CHANGE_USER_ON_PCONNECT`.

Así, se dejará al usuario la elección entre un comportamiento seguro y un rendimiento optimizado. Ambos tienen como objetivo la optimización. Para una utilización más sencilla, el comportamiento seguro ha sido colocado por omisión en detrimento de un rendimiento máximo.

Ver también

- mysqli_init()
- mysqli::__construct()
- mysqli::options()
- mysqli::real_connect()
- mysqli::change_user()
- $mysqli::host_info
- Las opciones de configuración MySQLi
- Las conexiones persistentes a las bases de datos

## Ejecución de consultas

Las consultas pueden ser ejecutadas con las funciones mysqli::query(), mysqli::real_query() y mysqli::multi_query(). La función mysqli::query() es la más común, y combina la ejecución de la consulta con una recuperación de su juego de resultados en memoria tamponada, si lo hay, en una sola llamada. Llamar a la función mysqli::query() es idéntico a llamar a la función mysqli::real_query() seguida de una llamada a la función mysqli::store_result().

Ejemplo #1 Ejecución de consultas

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");

Juegos de resultados en memoria tamponada

Después de la ejecución de la consulta, los resultados pueden ser recuperados completamente de una vez o bien ser leídos línea por línea. La memoria tamponada del juego de resultados del lado-cliente permite al servidor liberar los recursos asociados con el resultado de la consulta tan pronto como sea posible. En general, los clientes son lentos para recorrer los juegos de resultados. Sin embargo, se recomienda utilizar la memoria tamponada de los juegos de resultados. La función mysqli::query() combina tanto la ejecución de la consulta como la memoria tamponada del juego de resultados.

Las aplicaciones PHP pueden navegar libremente en los resultados en memoria tamponada. La navegación es rápida ya que los juegos de resultados están almacenados en la memoria del cliente. Tenga en cuenta que a menudo es más sencillo realizar esta operación por el cliente que por el servidor.

Ejemplo #2 Navegación en resultados en memoria tamponada

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");
    $mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

    $result = $mysqli->query("SELECT id FROM test ORDER BY id ASC");

    echo "Orden inverso...\n";
    for ($row_no = $result->num_rows - 1; $row_no >= 0; $row_no--) {
        $result->data_seek($row_no);
        $row = $result->fetch_assoc();
        echo " id = " . $row['id'] . "\n";
    }

    echo "Orden del juego de resultados...\n";
    foreach ($result as $row) {
        echo " id = " . $row['id'] . "\n";
    }

El ejemplo anterior mostrará:

    Orden inverso...
     id = 3
     id = 2
     id = 1
    Orden del juego de resultados...
     id = 1
     id = 2
     id = 3

Juegos de resultados no en memoria tamponada

Si la memoria del cliente es un recurso limitado, y la liberación de los recursos del servidor tan pronto como sea posible para mantener una carga del servidor baja no es necesaria, los resultados no en memoria tamponada pueden ser utilizados. La navegación a través de resultados no en memoria tamponada no es posible hasta que todas las líneas no hayan sido leídas.

Ejemplo #3 Navegación en resultados no en memoria tamponada

    <?php

    $mysqli->real_query("SELECT id FROM test ORDER BY id ASC");
    $result = $mysqli->use_result();

    echo "Orden del juego de resultados...\n";
    foreach ($result as $row) {
        echo " id = " . $row['id'] . "\n";
    }

Tipos de datos de los valores del juego de resultados

Las funciones mysqli::query(), mysqli::real_query() y mysqli::multi_query() se utilizan para ejecutar consultas no preparadas. A nivel del protocolo cliente-servidor MySQL, la orden `COM_QUERY` así como el protocolo texto son utilizados para la ejecución de la consulta. Con el protocolo texto, el servidor MySQL convierte todos los datos de un juego de resultados en cadenas de caracteres antes de enviarlos. La biblioteca cliente mysql recibe todos los valores de las columnas en forma de cadena de caracteres. Ninguna otra conversión del lado-cliente se realiza para recuperar el tipo nativo de las columnas. En su lugar, todas las valores son proporcionados en la forma de cadena de caracteres PHP.

Ejemplo #4 El protocolo texto devuelve cadenas de caracteres por omisión

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label CHAR(1))");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'a')");

    $result = $mysqli->query("SELECT id, label FROM test WHERE id = 1");
    $row = $result->fetch_assoc();

    printf("id = %s (%s)\n", $row['id'], gettype($row['id']));
    printf("label = %s (%s)\n", $row['label'], gettype($row['label']));

El ejemplo anterior mostrará:

    id = 1 (string)
    label = a (string)

Es posible convertir columnas de tipo enteros y números de punto flotante en números PHP definiendo la opción de conexión `MYSQLI_OPT_INT_AND_FLOAT_NATIVE`, si se utiliza la biblioteca mysqlnd. Si está definida, la biblioteca mysqlnd verificará las metadatos de los tipos de las columnas en el juego de resultados y convertirá las columnas SQL numéricas en números PHP, si el valor está dentro del intervalo permitido de PHP. De esta manera, por ejemplo, las columnas SQL INT son devueltas en la forma de entero.

Ejemplo #5 Tipos nativos de datos con mysqlnd y la opción de conexión

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = new mysqli();
    $mysqli->options(MYSQLI_OPT_INT_AND_FLOAT_NATIVE, 1);
    $mysqli->real_connect("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label CHAR(1))");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'a')");

    $result = $mysqli->query("SELECT id, label FROM test WHERE id = 1");
    $row = $result->fetch_assoc();

    printf("id = %s (%s)\n", $row['id'], gettype($row['id']));
    printf("label = %s (%s)\n", $row['label'], gettype($row['label']));

El ejemplo anterior mostrará:

    id = 1 (integer)
    label = a (string)

Ver también

- mysqli::__construct()
- mysqli::options()
- mysqli::real_connect()
- mysqli::query()
- mysqli::multi_query()
- mysqli::use_result()
- mysqli::store_result()

## Las consultas preparadas

La base de datos MySQL soporta las consultas preparadas. Una consulta preparada o consulta parametrizable es utilizada para ejecutar la misma consulta varias veces, con gran eficiencia y protege contra las inyecciones SQL.

Flujo de trabajo básico

La ejecución de una consulta preparada se realiza en dos pasos : la preparación y la ejecución. Durante la preparación, una plantilla de consulta es enviada al servidor de base de datos. El servidor realiza una verificación de la sintaxis, y inicializa los recursos internos del servidor para un uso posterior.

El servidor MySQL soporta el modo anónimo, con marcadores de posición utilizando el carácter `?`.

La preparación es seguida por la ejecución. Durante la ejecución, el cliente enlaza los valores de los parámetros y los envía al servidor. El servidor ejecuta la instrucción con los valores enlazados utilizando los recursos internos previamente creados.

Ejemplo #1 Primer paso: la preparación

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    // Consulta no preparada
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");

    // Consulta preparada, paso 1: preparación
    $stmt = $mysqli->prepare("INSERT INTO test(id, label) VALUES (?, ?)");

    // Consulta preparada, paso 2: enlaza los valores y ejecuta la consulta
    $id = 1;
    $label = 'PHP';
    $stmt->bind_param("is", $id, $label); // "is" significa que $id está enlazado como un integer y $label como un string

    $stmt->execute();

Ejecución repetida

Una consulta preparada puede ser ejecutada varias veces. En cada ejecución, el valor actual de la variable enlazada es evaluado, y enviado al servidor. La consulta no es analizada de nuevo. La plantilla de consulta no es enviada nuevamente al servidor.

Ejemplo #2 Consulta de tipo INSERT preparada una sola vez, y ejecutada varias veces

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    // Consulta no preparada
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");

    // Consulta preparada, paso 1: la preparación
    if (!($stmt = $mysqli->prepare("INSERT INTO test(id) VALUES (?)"))) {
         echo "Fallo durante la preparación: (" . $mysqli->errno . ") " . $mysqli->error;
    }

    // Consulta preparada, paso 2: enlaza los valores y ejecuta la consulta
    $id = 1;
    $stmt->bind_param("is", $id, $label); // "is" significa que $id está enlazado como un integer y $label como un string

    $data = [
        1 => 'PHP',
        2 => 'Java',
        3 => 'C++'
    ];

    foreach ($data as $id => $label) {
        $stmt->execute();
    }

    $result = $mysqli->query('SELECT id, label FROM test');
    var_dump($result->fetch_all(MYSQLI_ASSOC));

El ejemplo anterior mostrará:

    array(3) {
      array(2) {
        ["id"]=>
        string(1) "1"
        ["label"]=>
        string(3) "PHP"
      }
      [1]=>
      array(2) {
        ["id"]=>
        string(1) "2"
        ["label"]=>
        string(4) "Java"
      }
      [2]=>
      array(2) {
        ["id"]=>
        string(1) "3"
        ["label"]=>
        string(3) "C++"
      }
    }

Cada consulta preparada ocupa recursos en el servidor. Deben ser cerradas explícitamente inmediatamente después de su uso. Si no lo hace, la consulta será cerrada cuando el manejador de consulta sea liberado por PHP.

El uso de consultas preparadas no siempre es la forma más eficiente de ejecutar una consulta. Una consulta preparada ejecutada una sola vez provoca más idas y vueltas cliente-servidor que una consulta no preparada. Es por eso que la consulta de tipo `SELECT` no es ejecutada como consulta preparada en el ejemplo anterior.

Además, debe tener en cuenta el uso de las sintaxis multi-INSERT MySQL para los INSERTs. Por ejemplo, los multi-INSERTs requieren menos idas y vueltas cliente-servidor que la consulta preparada vista en el ejemplo anterior.

Ejemplo #3 Menos idas y vueltas utilizando los multi-INSERTs SQL

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");

    $values = [1, 2, 3, 4];

    $stmt = $mysqli->prepare("INSERT INTO test(id) VALUES (?), (?), (?), (?)");
    $stmt->bind_param('iiii', ...$values);
    $stmt->execute();

Tipos de datos de los valores del juego de resultados

El protocolo servidor cliente MySQL define un protocolo de transferencia de datos diferente para las consultas preparadas y para las consultas no preparadas. Las consultas preparadas utilizan un protocolo llamado binario. El servidor MySQL envía los datos del juego de resultados "tal cual", en formato binario. Los resultados no son serializados en cadenas de caracteres antes de ser enviados. La biblioteca cliente recibe datos binarios y intenta convertir los valores en un tipo de datos PHP apropiado. Por ejemplo, los resultados desde una columna `INT` SQL serán proporcionados como variables de tipo entero PHP.

Ejemplo #4 Tipos de datos nativos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    // Consulta no preparada
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP')");

    $stmt = $mysqli->prepare("SELECT id, label FROM test WHERE id = 1");
    $stmt->execute();
    $result = $stmt->get_result();
    $row = $result->fetch_assoc();

    printf("id = %s (%s)\n", $row['id'], gettype($row['id']));
    printf("label = %s (%s)\n", $row['label'], gettype($row['label']));

El ejemplo anterior mostrará:

    id = 1 (integer)
    label = PHP (string)

Este comportamiento difiere para las consultas no preparadas. Por omisión, las consultas no preparadas devuelven todos los resultados en forma de cadenas de caracteres. Este comportamiento por omisión puede ser modificado utilizando una opción durante la conexión. Si esta opción es utilizada, entonces no habrá diferencia entre una consulta preparada y una consulta no preparada.

Recuperación de los resultados utilizando variables enlazadas

Los resultados desde las consultas preparadas pueden ser recuperados enlazando las variables de salida, o interrogando el objeto mysqli_result.

Las variables de salida deben ser enlazadas después de la ejecución de la consulta. Una variable debe ser enlazada para cada columna del juego de resultados de la consulta.

Ejemplo #5 Enlace de las variables de salida

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    // Consulta no preparada
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP')");

    $stmt = $mysqli->prepare("SELECT id, label FROM test WHERE id = 1");
    $stmt->execute();

    $stmt->bind_result($out_id, $out_label);

    $out_id    = NULL;
    $out_label = NULL;
    if (!$stmt->bind_result($out_id, $out_label)) {
        echo "Fallo durante el enlace de los parámetros de salida: (" . $stmt->errno . ") " . $stmt->error;
    }

    while ($stmt->fetch()) {
        printf("id = %s (%s), label = %s (%s)\n", $out_id, gettype($out_id), $out_label, gettype($out_label));
    }

El ejemplo anterior mostrará:

    id = 1 (integer), label = a (string)

Las consultas preparadas devuelven juegos de resultados no en memoria tamponada por omisión. Los resultados de la consulta no son recuperados implícitamente y transferidos desde el servidor hacia el cliente para una memoria tamponada del lado-cliente. El juego de resultados ocupa recursos del servidor hasta que todos los resultados no sean recuperados por el cliente. Por lo tanto, es recomendable recuperarlos rápidamente. Si un cliente falla en la recuperación de todos los resultados, o si el cliente cierra la consulta antes de haber recuperado todos los datos, los datos deben ser recuperados implícitamente por `mysqli`.

También es posible poner en memoria tamponada los resultados de una consulta preparada utilizando la función mysqli_stmt::store_result().

Recuperación de los resultados utilizando la interfaz mysqli_result

En lugar de utilizar resultados enlazados, los resultados pueden también ser recuperados a través de la interfaz mysqli_result. La función mysqli_stmt::get_result() devuelve un juego de resultados en memoria tamponada.

Ejemplo #6 Uso de mysqli_result para recuperar los resultados

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    // Consulta no preparada
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP')");

    $stmt = $mysqli->prepare("SELECT id, label FROM test WHERE id = 1");
    $stmt->execute();

    $result = $stmt->get_result();

    var_dump($result->fetch_all(MYSQLI_ASSOC));

El ejemplo anterior mostrará:

    array(1) {
      [0]=>
      array(2) {
        ["id"]=>
        int(1)
        ["label"]=>
        string(3) "PHP"
      }
    }

El uso de la interfaz mysqli_result ofrece otras ventajas en términos de flexibilidad en la navegación en el juego de resultados del lado-cliente.

Ejemplo #7 Juego de resultados en memoria tamponada para más flexibilidad en la lectura

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    // Consulta no preparada
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP'), (2, 'Java'), (3, 'C++')");

    $stmt = $mysqli->prepare("SELECT id, label FROM test");
    $stmt->execute();

    $result = $stmt->get_result();

    for ($row_no = $result->num_rows - 1; $row_no >= 0; $row_no--) {
        $result->data_seek($row_no);
        var_dump($result->fetch_assoc());
    }

El ejemplo anterior mostrará:

    array(2) {
      ["id"]=>
      int(3)
      ["label"]=>
      string(1) "C++"
    }
    array(2) {
      ["id"]=>
      int(2)
      ["label"]=>
      string(1) "Java"
    }
    array(2) {
      ["id"]=>
      int(1)
      ["label"]=>
      string(1) "PHP"
    }

Escape y inyección SQL

Las variables enlazadas son enviadas al servidor separadamente de la consulta, no pudiendo así interferir con esta. El servidor utiliza estos valores directamente al momento de la ejecución, después de que la plantilla sea analizada. Los parámetros enlazados no necesitan ser escapados ya que nunca son colocados en la cadena de consulta directamente. Una pista debe ser proporcionada al servidor para especificar el tipo de variable enlazada, para realizar la conversión apropiada. Ver la función mysqli_stmt::bind_param() para más información.

Tal separación es a menudo considerada como la única funcionalidad para protegerse contra las inyecciones SQL, pero el mismo grado de seguridad puede ser alcanzado con las consultas no preparadas, si todas las valores son correctamente formateadas. Tenga en cuenta que un formateo correcto no es lo mismo que un escape y requiere más lógica que un simple escape. Por lo tanto, las consultas preparadas son simplemente un método más sencillo y menos propenso a errores en cuanto a este enfoque seguro.

Emulación del lado-cliente de la preparación de una consulta

La API no incluye una emulación del lado-cliente de la preparación de una consulta.

Ver también

- mysqli::__construct()
- mysqli::query()
- mysqli::prepare()
- mysqli_stmt::prepare()
- mysqli_stmt::execute()
- mysqli_stmt::bind_param()
- mysqli_stmt::bind_result()

## Los procedimientos almacenados

La base de datos MySQL soporta los procedimientos almacenados. Un procedimiento almacenado es una subrutina almacenada en el catálogo de la base de datos. Las aplicaciones pueden llamar y ejecutar un procedimiento almacenado. La consulta SQL `CALL` es utilizada para ejecutar un procedimiento almacenado.

Parámetro

Los procedimientos almacenados pueden tener parámetros `IN`, `INOUT` y `OUT`, dependiendo de la versión de MySQL. La interfaz mysqli no tiene una noción específica de los diferentes tipos de parámetros.

Parámetro IN

Los parámetros de entrada son proporcionados con la consulta `CALL`. Asegúrese de escapar correctamente los valores.

Ejemplo #1 Llamada a un procedimiento almacenado

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");

    $mysqli->query("DROP PROCEDURE IF EXISTS p");
    $mysqli->query("CREATE PROCEDURE p(IN id_val INT) BEGIN INSERT INTO test(id) VALUES(id_val); END;");

    $mysqli->query("CALL p(1)");

    $result = $mysqli->query("SELECT id FROM test");

    var_dump($result->fetch_assoc());

El ejemplo anterior mostrará:

    array(1) {
      ["id"]=>
      string(1) "1"
    }

Parámetro INOUT/OUT

Los valores de los parámetros `INOUT`/`OUT` son accedidos utilizando las variables de sesión.

Ejemplo #2 Uso de las variables de sesión

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP PROCEDURE IF EXISTS p");
    $mysqli->query('CREATE PROCEDURE p(OUT msg VARCHAR(50)) BEGIN SELECT "Hi!" INTO msg; END;');

    $mysqli->query("SET @msg = ''");
    $mysqli->query("CALL p(@msg)");

    $result = $mysqli->query("SELECT @msg as _p_out");

    $row = $result->fetch_assoc();
    echo $row['_p_out'];

El ejemplo anterior mostrará:

    Hi!

Los desarrolladores de aplicaciones y de frameworks pueden proporcionar una API más amigable utilizando una mezcla de las variables de sesión y una inspección del catálogo de la base de datos. Sin embargo, tenga en cuenta el impacto en el rendimiento debido a una solución personalizada basada en la inspección del catálogo.

Gestión de los juegos de resultados

Los procedimientos almacenados pueden devolver juegos de resultados. Los juegos de resultados devueltos desde un procedimiento almacenado no pueden ser recuperados correctamente utilizando la función mysqli::query(). La función mysqli::query() combina la ejecución de la consulta y la recuperación del primer juego de resultados en un juego de resultados en memoria tamponada, si lo hay. Sin embargo, existen otros juegos de resultados provenientes del procedimiento almacenado que están ocultos al usuario y que hacen que la función mysqli::query() falle al recuperar los juegos de resultados esperados por el usuario.

Los juegos de resultados devueltos desde un procedimiento almacenado son recuperados utilizando la función mysqli::real_query() o mysqli::multi_query(). Estas dos funciones permiten la recuperación de cualquier número de juegos de resultados devueltos por una consulta, como la consulta `CALL`. Fallar en la recuperación de todos los juegos de resultados devueltos por un procedimiento almacenado causa un error.

Ejemplo #3 Recuperación de los resultados provenientes de un procedimiento almacenado

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");
    $mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

    $mysqli->query("DROP PROCEDURE IF EXISTS p");
    $mysqli->query('CREATE PROCEDURE p() READS SQL DATA BEGIN SELECT id FROM test; SELECT id + 1 FROM test; END;');

    $mysqli->multi_query("CALL p()");

    do {
        if ($res = $mysqli->store_result()) {
            var_dump($result->fetch_all());
            $result->free();
        }
    } while ($mysqli->next_result());

El ejemplo anterior mostrará:

    ---
    array(3) {
      [0]=>
      array(1) {
        [0]=>
        string(1) "1"
      }
      [1]=>
      array(1) {
        [0]=>
        string(1) "2"
      }
      [2]=>
      array(1) {
        [0]=>
        string(1) "3"
      }
    }
    ---
    array(3) {
      [0]=>
      array(1) {
        [0]=>
        string(1) "2"
      }
      [1]=>
      array(1) {
        [0]=>
        string(1) "3"
      }
      [2]=>
      array(1) {
        [0]=>
        string(1) "4"
      }
    }

Uso de las consultas preparadas

No se requiere una gestión especial al utilizar la interfaz de preparación de consultas para recuperar los resultados desde el mismo procedimiento almacenado que el anterior. Las interfaces de consulta preparada y no preparada son similares. Tenga en cuenta que todas las versiones del servidor MySQL no soportan la preparación de las consultas SQL `CALL`.

Ejemplo #4 Procedimientos almacenados y consulta preparada

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");
    if ($mysqli->connect_errno) {
        echo "Fallo durante la conexión a MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
    }

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");
    $mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

    $mysqli->query("DROP PROCEDURE IF EXISTS p");
    $mysqli->query('CREATE PROCEDURE p() READS SQL DATA BEGIN SELECT id FROM test; SELECT id + 1 FROM test; END;');

    $stmt = $mysqli->prepare("CALL p()");

    if (!$stmt->execute()) {
        echo "Fallo durante la ejecución: (" . $stmt->errno . ") " . $stmt->error;
    }

    do {
        if ($result = $stmt->get_result()) {
            var_dump($result->fetch_all());
            $result->free();
        }
    } while ($stmt->next_results());

El ejemplo anterior mostrará:

    ---
    array(3) {
      [0]=>
      array(1) {
        [0]=>
        int(1)
      }
      [1]=>
      array(1) {
        [0]=>
        int(2)
      }
      [2]=>
      array(1) {
        [0]=>
        int(3)
      }
    }
    ---
    array(3) {
      [0]=>
      array(1) {
        [0]=>
        int(2)
      }
      [1]=>
      array(1) {
        [0]=>
        int(3)
      }
      [2]=>
      array(1) {
        [0]=>
        int(4)
      }
    }

Por supuesto, el uso de la API de enlace para la recuperación también es soportado.

Ejemplo #5 Procedimientos almacenados y consulta preparada utilizando la API de enlace

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");
    $mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

    $mysqli->query("DROP PROCEDURE IF EXISTS p");
    $mysqli->query('CREATE PROCEDURE p() READS SQL DATA BEGIN SELECT id FROM test; SELECT id + 1 FROM test; END;');

    $stmt = $mysqli->prepare("CALL p()");

    $stmt->execute();

    do {
        if ($stmt->store_result()) {
            $stmt->bind_result($id_out);
            while ($stmt->fetch()) {
                echo "id = $id_out\n";
            }
        }
    } while ($stmt->next_result());

El ejemplo anterior mostrará:

    id = 1
    id = 2
    id = 3
    id = 2
    id = 3
    id = 4

Ver también

- mysqli::query()
- mysqli::multi_query()
- mysqli::next_result()
- mysqli::more_results()

## Consultas múltiples

MySQL permite opcionalmente tener múltiples consultas en una sola cadena de consulta pero requiere una gestión especial.

Las consultas múltiples o multiconsultas deben ser ejecutadas con la función mysqli::multi_query(). Las consultas individuales en la cadena de consulta están separadas por un punto y coma. Luego, todos los juegos de resultados devueltos por la ejecución de las consultas deben ser recuperados.

El servidor MySQL permite tener consultas que devuelven juegos de resultados así como consultas que no devuelven ningún juego de resultados en la misma consulta múltiple.

Ejemplo #1 Consultas múltiples

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");

    $sql = "SELECT COUNT(*) AS _num FROM test;
            INSERT INTO test(id) VALUES (1);
            SELECT COUNT(*) AS _num FROM test; ";

    $mysqli->multi_query($sql);

    do {
        if ($result = $mysqli->store_result()) {
            var_dump($result->fetch_all(MYSQLI_ASSOC));
            $result->free();
        }
    } while ($mysqli->next_result());

El ejemplo anterior mostrará:

    array(1) {
      [0]=>
      array(1) {
        ["_num"]=>
        string(1) "0"
      }
    }
    array(1) {
      [0]=>
      array(1) {
        ["_num"]=>
        string(1) "1"
      }
    }

Desde un punto de vista de seguridad

Las funciones mysqli::query() y mysqli::real_query() de la API no definen un flag de conexión necesario para la activación de las multiconsultas en el servidor. Una llamada adicional a la API es utilizada para las multiconsultas para reducir la probabilidad de inyección SQL accidental. Un atacante puede intentar agregar consultas como `; DROP DATABASE mysql` o `; SELECT SLEEP(999)`. Si el atacante logra agregar este tipo de SQL en la cadena de consulta pero que mysqli::multi_query() no es utilizado, el servidor solo ejecutará la primera consulta, pero no la segunda que representa la consulta SQL maliciosa.

Ejemplo #2 Inyección SQL

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");
    $result = $mysqli->query("SELECT 1; DROP TABLE mysql.user");

El ejemplo anterior mostrará:

    PHP Fatal error:  Uncaught mysqli_sql_exception: You have an error in your SQL syntax;
    check the manual that corresponds to your MySQL server version for the right syntax to
    use near 'DROP TABLE mysql.user' at line 1

Consultas preparadas

El uso de consultas múltiples con consultas preparadas no es soportado.

Ver también

- mysqli::query()
- mysqli::multi_query()
- mysqli_result::next-result()
- mysqli_result::more-results()

## Soporte API para las transacciones

El servidor MySQL soporta las transacciones dependiendo del motor de almacenamiento utilizado. Desde MySQL 5.5, el motor de almacenamiento por omisión es InnoDB. InnoDB tiene un soporte completo de las transacciones ACID.

Las transacciones pueden ser controladas utilizando SQL, o mediante llamadas API. Se recomienda utilizar las llamadas API para activar o desactivar el modo `autocommit` y para validar y anular las transacciones.

Ejemplo #1 Definir el modo `autocommit` a través de SQL o a través de la API

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    // Recomendado: uso de la API para controlar la configuración de las transacciones
    $mysqli->autocommit(false);

    // No será monitoreado y reconocido por el plugin de replicación y balanceo de carga
    $mysqli->query('SET AUTOCOMMIT = 0');

Los paquetes de funcionalidades adicionales, como los plugins de replicación y balanceo de carga pueden monitorear las llamadas API. El plugin de replicación ofrece seguridad sobre las transacciones durante el balanceo de carga, si las transacciones son controladas con llamadas API. La seguridad de las transacciones durante el balanceo de carga no está disponible si las consultas SQL son utilizadas para definir el modo `autocommit`, para validar o anular una transacción.

Ejemplo #2 Validación y anulación de una transacción

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");
    $mysqli->autocommit(false);

    $mysqli->query("INSERT INTO test(id) VALUES (1)");
    $mysqli->rollback();

    $mysqli->query("INSERT INTO test(id) VALUES (2)");
    $mysqli->commit();

Tenga en cuenta que el servidor MySQL no puede anular todas las consultas. Algunas consultas requieren una validación implícita.

Ver también

- mysqli::autocommit()
- mysqli::begin_transaction()
- mysqli::commit()
- mysqli::rollback()

## Las metadatos

Un juego de resultados MySQL contiene metadatos. Estos describen las columnas encontradas en el juego de resultados. Todos los metadatos enviados por MySQL son accesibles a través de la interfaz `mysqli`. La extensión no realiza ninguna modificación sobre las informaciones que recibe. Las diferencias entre las versiones MySQL no son idénticas.

Los metadatos pueden ser consultados a través de la interfaz mysqli_result.

Ejemplo #1 Acceso a los metadatos del juego de resultados

    <?php

    $mysqli = new mysqli("example.com", "user", "password", "database");
    if ($mysqli->connect_errno) {
        echo "Fallo durante la conexión a MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
    }

    $res = $mysqli->query("SELECT 1 AS _one, 'Hello' AS _two FROM DUAL");
    var_dump($res->fetch_fields());

El ejemplo anterior mostrará:

    array(2) {
      [0]=>
      object(stdClass)#3 (13) {
        ["name"]=>
        string(4) "_one"
        ["orgname"]=>
        string(0) ""
        ["table"]=>
        string(0) ""
        ["orgtable"]=>
        string(0) ""
        ["def"]=>
        string(0) ""
        ["db"]=>
        string(0) ""
        ["catalog"]=>
        string(3) "def"
        ["max_length"]=>
        int(1)
        ["length"]=>
        int(1)
        ["charsetnr"]=>
        int(63)
        ["flags"]=>
        int(32897)
        ["type"]=>
        int(8)
        ["decimals"]=>
        int(0)
      }
      [1]=>
      object(stdClass)#4 (13) {
        ["name"]=>
        string(4) "_two"
        ["orgname"]=>
        string(0) ""
        ["table"]=>
        string(0) ""
        ["orgtable"]=>
        string(0) ""
        ["def"]=>
        string(0) ""
        ["db"]=>
        string(0) ""
        ["catalog"]=>
        string(3) "def"
        ["max_length"]=>
        int(5)
        ["length"]=>
        int(5)
        ["charsetnr"]=>
        int(8)
        ["flags"]=>
        int(1)
        ["type"]=>
        int(253)
        ["decimals"]=>
        int(31)
      }
    }

Consultas preparadas

Los metadatos de los juegos de resultados creados utilizando consultas preparadas son accesibles de la misma manera. Un manejador mysqli_result utilizable es devuelto por la función mysqli_stmt::result_metadata().

Ejemplo #2 Metadatos a través de consultas preparadas

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $stmt = $mysqli->prepare("SELECT 1 AS _one, 'Hello' AS _two FROM DUAL");
    $stmt->execute();

    $result = $stmt->result_metadata();
    var_dump($result->fetch_fields());

Ver también

- mysqli::query()
- mysqli_result::fetch_fields()

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución

## Requerimientos

Para que estas funciones estén disponibles, es necesario compilar PHP con el soporte de la extensión mysqli.

MySQL 8

Si PHP es utilizado en una versión anterior a la 7.1.16, o PHP 7.2 anterior a 7.2.4, el plugin de contraseña debe ser definido a mysql_native_password para MySQL 8 Server, ya que de lo contrario pueden aparecer errores similares a The server requested authentication method unknown to the client [caching_sha2_password] incluso si caching_sha2_password no es utilizado.

Esto se debe a que MySQL 8 utiliza por omisión caching_sha2_password, un plugin que no es reconocido por las versiones antiguas de PHP (mysqlnd). En su lugar, es necesario modificar el parámetro `default_authentication_plugin=mysql_native_password` en my.cnf. El plugin caching_sha2_password es completamente soportado a partir de PHP 7.4.4. Para versiones anteriores, la extensión mysql_xdevapi lo soporta.

## Instalación

La extensión `mysqli` fue introducida en PHP 5.0.0. El controlador nativo MySQL (MySQL Native Driver) fue introducido en PHP 5.3.0.

## Instalación en Linux

Las distribuciones Linux incluyen versiones binarias de PHP que pueden ser instaladas. Aunque estos binarios están construidos con las extensiones MySQL, las bibliotecas cliente deben ser instaladas a menudo mediante un paquete adicional. Verifique si este es el caso para su distribución.

Por ejemplo, en Ubuntu el paquete `php5-mysql` instala las extensiones PHP ext/mysql, ext/mysqli y pdo_mysql. En CentOS, el paquete `php-mysql` instala también estas tres extensiones PHP.

Alternativamente, es posible compilar esta extensión manualmente. Construir PHP desde las fuentes permite especificar las extensiones MySQL a incluir, así como las bibliotecas cliente de cada extensión.

El controlador nativo MySQL es la biblioteca cliente recomendada, ya que ofrece un aumento de rendimiento y proporciona acceso a características que no están disponibles al utilizar la biblioteca cliente MySQL. Consulte la sección ¿Qué es el controlador nativo MySQL de PHP? para una breve descripción de las ventajas del controlador nativo MySQL.

`/path/to/mysql_config` representa la ruta de acceso del programa `mysql_config` proporcionado con MySQL servidor.

Matriz de soporte para la compilación mysqli
Versión PHP | Por defecto | Opciones de configuración : mysqlnd | Opciones de configuración : `libmysqlclient` | Historial de cambios
--- | --- | --- | --- | ---
5.4.x y posteriores | mysqlnd | --with-mysqli | --with-mysqli=/path/to/mysql_config | mysqlnd por omisión
5.3.x | libmysqlclient | --with-mysqli=mysqlnd | --with-mysqli=/path/to/mysql_config | mysqlnd es soportado
5.0.x, 5.1.x, 5.2.x | libmysqlclient | No Disponible | --with-mysqli=/path/to/mysql_config | mysqlnd no es soportado

Cabe señalar que es posible mezclar las extensiones MySQL así como las bibliotecas cliente. Por ejemplo, es posible activar la extensión MySQL para utilizar la biblioteca cliente MySQL (libmysqlclient) mientras se configura la extensión `mysqli` para utilizar el controlador nativo MySQL. Todas las combinaciones de extensiones y bibliotecas cliente son posibles.

## Instalación en sistemas Windows

En Windows, la DLL php_mysqli.dll debe ser activada en el fichero php.ini.

Para activar una extensión PHP (tal como php_mysqli.dll), la directiva PHP extension_dir debe apuntar hacia el directorio que contiene las extensiones PHP. Consulte también Instalación manual en Windows . Por ejemplo, `extension_dir` podría tener el valor c:\php\ext.

> Nota:

> Si al iniciar el servidor web se produce un error como `"Unable to load dynamic library './php_mysqli.dll'"`, es porque php_mysqli.dll y/o libmysql.dll no pueden ser encontrados en el sistema.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración MySQLi
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
mysqli.allow_local_infile | "0" | `INI_SYSTEM` | Anterior a PHP 7.2.16 y 7.3.3 el valor por omisión era "1".
mysqli.local_infile_directory |  | `INI_SYSTEM` | Disponible a partir de PHP 8.1.0.
mysqli.allow_persistent | "1" | `INI_SYSTEM` |
mysqli.max_persistent | "-1" | `INI_SYSTEM` |
mysqli.max_links | "-1" | `INI_SYSTEM` |
mysqli.default_port | "3306" | `INI_ALL` |
mysqli.default_socket | NULL | `INI_ALL` |
mysqli.default_host | NULL | `INI_ALL` |
mysqli.default_user | NULL | `INI_ALL` |
mysqli.default_pw | NULL | `INI_ALL` |
mysqli.reconnect | "0" | `INI_SYSTEM` | Eliminada a partir de PHP 8.2.0
mysqli.rollback_on_cached_plink | "0" | `INI_SYSTEM` |

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Para más detalles y definiciones sobre las constantes INI_* anteriores, consulte el capítulo sobre modificaciones de configuración.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`mysqli.allow_local_infile` int

  Permite el acceso, desde PHP, a los ficheros locales cargados con LOAD DATA.

`mysqli.local_infile_directory` string

  Permite una carga restringida LOCAL DATA hacia ficheros que se encuentren en el directorio designado.

`mysqli.allow_persistent` int

  Activa la posibilidad de crear conexiones persistentes utilizando la función mysqli_connect().

`mysqli.max_persistent` int

  Número máximo de conexiones persistentes que pueden realizarse. Establecer a 0 para "ilimitado".

`mysqli.max_links` int

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

`mysqli.default_port` int

  El número de puerto TCP por omisión a utilizar al conectarse al servidor si no se proporciona otro puerto. Si no está definido, el puerto se obtendrá de la variable de entorno `MYSQL_TCP_PORT`, la entrada `mysql-tcp` en /etc/services o la constante de compilación `MYSQL_PORT`, en este orden. Win32 solo utilizará la constante `MYSQL_PORT`.

`mysqli.default_socket` string

  El nombre por omisión del socket a utilizar durante las conexiones locales al servidor si no se proporciona otro nombre.

`mysqli.default_host` string

  El servidor por omisión a utilizar al conectarse a un servidor si no se proporciona otro host.

`mysqli.default_user` string

  El nombre de usuario por omisión a utilizar al conectarse a un servidor si no se proporciona otro nombre.

`mysqli.default_pw` string

  La contraseña por omisión a utilizar al conectarse a un servidor si no se proporciona otra contraseña.

`mysqli.reconnect` int

  Reconexión automática si la conexión se interrumpe.

  > Nota: Esta directiva php.ini había sido ignorada por el controlador mysqlnd y fue eliminada a partir de PHP 8.2.0.

`mysqli.rollback_on_cached_plink` bool

  Si esta opción está activada, el cierre de una conexión permanente anula todas las transacciones pendientes de esta conexión antes de ser reemplazada en el grupo de conexiones persistentes. De lo contrario, las transacciones pendientes serán restauradas únicamente cuando la conexión es reutilizada o cuando se cierra realmente.

Los usuarios no pueden cambiar `MYSQL_OPT_READ_TIMEOUT` mediante una llamada a la API o en tiempo de ejecución. Tenga en cuenta que incluso si es posible, habrá diferencias en la manera en que `libmysqlclient` y los flujos van a interpretar el valor de `MYSQL_OPT_READ_TIMEOUT`.

# La extensión mysqli y las conexiones persistentes

La idea detrás de las conexiones persistentes es que las conexiones entre los clientes y la base de datos pueden ser reutilizadas por otro proceso cliente, en lugar de ser destruidas y recreadas numerosas veces. Esto reduce el coste de creación de conexiones cada vez que una de ellas es requerida, ya que las conexiones se almacenan en caché para ser recicladas.

A diferencia de la extensión MySQL, MySQLi no proporciona una función separada para abrir conexiones persistentes. Para abrir una conexión persistente, se debe añadir `p:` al nombre del host al conectar.

El problema de las conexiones persistentes es que pueden ser dejadas en un estado impredecible por los clientes. Por ejemplo, un bloqueo de tabla puede haber sido puesto antes de que el cliente se desconecte inesperadamente. Un nuevo cliente tomará entonces la conexión, pero tal cual. Sería necesario entonces que el nuevo cliente realice una limpieza en profundidad de la conexión antes de poder reutilizarla sin interferencias, lo cual es una desventaja para el programador.

La conexión persistente de la extensión `mysqli` proporciona un método de limpieza automática. La limpieza es realizada por `mysqli` e incluye:

- La cancelación de las transacciones activas.

- El cierre y destrucción de las tablas temporales.

- El desbloqueo de las tablas.

- La restauración de los valores por defecto de las variables de sesión.

- La liberación de las sentencias preparadas (esto siempre ocurre con PHP).

- El cierre del manejador.

- La liberación de los bloqueos puestos por GET_LOCK().

Esto asegura que la conexión persistente está en una condición correcta antes de ser devuelta al grupo de conexiones, y que un cliente diferente la retome.

La extensión `mysqli` realiza esta limpieza llamando automáticamente a la función C `mysql_change_user()`.

La limpieza automática tiene sus ventajas e inconvenientes. La ventaja es que el programador no necesita preocuparse por ello, ya que es llamada automáticamente. Sin embargo, el inconveniente es que este código puede finalmente ser un poco más lento, ya que debe ser llamado cada vez que la conexión es devuelta al grupo de espera.

Es posible desactivar la limpieza del código, compilando PHP con la opción `MYSQLI_NO_CHANGE_USER_ON_PCONNECT`.

> Nota:

> La extensión `mysqli` soporta las conexiones persistentes con el MySQL Native Driver y con la biblioteca MySQL.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`MYSQLI_READ_DEFAULT_GROUP` (int)

  Lee las opciones en el grupo my.cnf o en el archivo especificado por `MYSQLI_READ_DEFAULT_FILE`.

`MYSQLI_READ_DEFAULT_FILE` (int)

  Lee las opciones en el archivo especificado, en lugar de en my.cnf.

`MYSQLI_OPT_CAN_HANDLE_EXPIRED_PASSWORDS` (int)
  Indica al servidor que el cliente puede gestionar el modo sandbox para las contraseñas expiradas. Puede ser utilizado con mysqli_options().
`MYSQLI_OPT_LOAD_DATA_LOCAL_DIR` (int)
  Si está activada, esta opción especifica el directorio desde el cual la carga de datos `LOCAL` del lado del cliente está autorizada en las instrucciones `LOAD DATA LOCAL`.
`MYSQLI_OPT_CONNECT_TIMEOUT` (int)

  Tiempo de expiración de la conexión, en segundos.

`MYSQLI_OPT_READ_TIMEOUT` (int)

  Tiempo de expiración de la ejecución de un comando en segundos. Disponible a partir de PHP 7.2.0.

`MYSQLI_OPT_LOCAL_INFILE` (int)

  Activa el comando `LOAD LOCAL INFILE`.

`MYSQLI_OPT_INT_AND_FLOAT_NATIVE` (int)

  Convierte las columnas de tipo entero y número de coma flotante en números PHP. Solo válido para mysqlnd.

`MYSQLI_OPT_NET_CMD_BUFFER_SIZE` (int)

  El tamaño del buffer interno de comando/red. Solo válido para mysqlnd.

`MYSQLI_OPT_NET_READ_BUFFER_SIZE` (int)

  Tamaño en bytes de la porción máxima a leer, al leer el cuerpo de un paquete de comando MySQL. Solo válido para mysqlnd.

`MYSQLI_OPT_SSL_VERIFY_SERVER_CERT` (int)

`MYSQLI_INIT_COMMAND` (int)

  Comando a ejecutar al conectarse al servidor MySQL. Este comando se ejecutará automáticamente al reconectarse al servidor.

`MYSQLI_CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS` (int)
  Indica al servidor que el cliente puede gestionar el modo sandbox para las contraseñas expiradas. Puede ser utilizado con mysqli_real_connect().
`MYSQLI_CLIENT_FOUND_ROWS` (int)
  Devuelve el número de filas coincidentes, no el número de filas afectadas.
`MYSQLI_CLIENT_SSL_VERIFY_SERVER_CERT` (int)
  Verifica el certificado del servidor.
`MYSQLI_CLIENT_SSL` (int)

  Utiliza el protocolo SSL (cifrado). Esta opción no debe ser activada por un programa: debe ser activada internamente, por la biblioteca MySQL.

`MYSQLI_CLIENT_COMPRESS` (int)

  Utiliza el protocolo comprimido.

`MYSQLI_CLIENT_INTERACTIVE` (int)

  Permite `interactive_timeout` segundos (en lugar de `wait_timeout` segundos) de inactividad antes de cerrar la conexión. El valor de la variable `wait_timeout` del cliente tomará el valor de `interactive_timeout`.

`MYSQLI_CLIENT_IGNORE_SPACE` (int)

  Permite espacios después de un nombre de función. Esto hace que todos los nombres de funciones sean palabras reservadas.

`MYSQLI_CLIENT_NO_SCHEMA` (int)

  Prohíbe la sintaxis `db_name.tbl_name.col_name`.

`MYSQLI_CLIENT_MULTI_QUERIES`

  Permite múltiples consultas separadas por un punto y coma en una sola llamada a la función mysqli_query().

`MYSQLI_STORE_RESULT` (int)

  Para los resultados almacenados en búfer. Tiene un valor de `0`.

`MYSQLI_STORE_RESULT_COPY_DATA` (int)
  Desde PHP 8.1, esta constante ya no tiene ningún efecto. Antes de PHP 8.1, esta constante se utilizaba para copiar los resultados del búfer interno `mysqlnd` en las variables PHP recuperadas. Por defecto, `mysqlnd` utilizará una lógica de referencia para evitar copiar y duplicar los resultados mantenidos en memoria. Para ciertos conjuntos de resultados, por ejemplo, conjuntos de resultados con muchas filas pequeñas, el enfoque de copia puede reducir el uso global de la memoria ya que las variables PHP que contienen los resultados pueden ser liberadas antes. Disponible únicamente con `mysqlnd`. Obsoleto a partir de PHP 8.4.0.
`MYSQLI_USE_RESULT` (int)

  Para los resultados no almacenados en búfer. Tiene un valor de `1`.

`MYSQLI_ASSOC` (int)

  Las columnas se devuelven en el array, con sus nombres como índices.

`MYSQLI_NUM` (int)

  Las columnas se devuelven en el array, con sus números como índices.

`MYSQLI_BOTH` (int)

  Las columnas se devuelven en el array, con sus nombres y sus números como índices.

`MYSQLI_NOT_NULL_FLAG` (int)

  Indica que un campo está definido como `NOT NULL`.

`MYSQLI_PRI_KEY_FLAG` (int)

  El campo es una clave primaria.

`MYSQLI_UNIQUE_KEY_FLAG` (int)

  El campo es un índice único.

`MYSQLI_MULTIPLE_KEY_FLAG` (int)

  El campo forma parte de un índice.

`MYSQLI_BLOB_FLAG` (int)

  El campo es de tipo `BLOB`.

`MYSQLI_UNSIGNED_FLAG` (int)

  El campo es de tipo `UNSIGNED`.

`MYSQLI_ZEROFILL_FLAG` (int)

  El campo es de tipo `ZEROFILL`.

`MYSQLI_AUTO_INCREMENT_FLAG` (int)

  El campo es de tipo `AUTO_INCREMENT`.

`MYSQLI_TIMESTAMP_FLAG` (int)

  El campo es de tipo `TIMESTAMP`.

`MYSQLI_SET_FLAG` (int)

  El campo es de tipo `SET`.

`MYSQLI_NUM_FLAG` (int)

  El campo es de tipo `NUMERIC`.

`MYSQLI_PART_KEY_FLAG` (int)

  El campo forma parte de un índice múltiple.

`MYSQLI_GROUP_FLAG` (int)

  El campo forma parte de la cláusula `GROUP BY`.

`MYSQLI_NO_DEFAULT_VALUE_FLAG` (int)
  Una columna no tiene una cláusula `DEFAULT` en su definición. Esto no se aplica a las columnas `NULL` o `AUTO_INCREMENT` ya que estas columnas tienen respectivamente un valor por defecto de `NULL` y un valor por defecto implícito.
`MYSQLI_TYPE_DECIMAL` (int)

  El campo es de tipo `DECIMAL`.

`MYSQLI_TYPE_NEWDECIMAL` (int)

  El campo es de tipo `DECIMAL` o `NUMERIC`.

`MYSQLI_TYPE_BIT` (int)

  El campo es de tipo `BIT`.

`MYSQLI_TYPE_TINY` (int)

  El campo es de tipo `TINYINT`.

`MYSQLI_TYPE_SHORT` (int)

  El campo es de tipo `SMALLINT`.

`MYSQLI_TYPE_LONG` (int)

  El campo es de tipo `INT`.

`MYSQLI_TYPE_FLOAT` (int)

  El campo es de tipo `FLOAT`.

`MYSQLI_TYPE_DOUBLE` (int)

  El campo es de tipo `DOUBLE`.

`MYSQLI_TYPE_NULL` (int)

  El campo es de tipo `DEFAULT NULL`.

`MYSQLI_TYPE_TIMESTAMP` (int)

  El campo es de tipo `TIMESTAMP`.

`MYSQLI_TYPE_LONGLONG` (int)

  El campo es de tipo `BIGINT`.

`MYSQLI_TYPE_INT24` (int)

  El campo es de tipo `MEDIUMINT`.

`MYSQLI_TYPE_DATE` (int)

  El campo es de tipo `DATE`.

`MYSQLI_TYPE_TIME` (int)

  El campo es de tipo `TIME`.

`MYSQLI_TYPE_DATETIME` (int)

  El campo es de tipo `DATETIME`.

`MYSQLI_TYPE_YEAR` (int)

  El campo es de tipo `YEAR`.

`MYSQLI_TYPE_NEWDATE` (int)

  El campo es de tipo `DATE`.

`MYSQLI_TYPE_INTERVAL` (int)

  Alias de `MYSQLI_TYPE_ENUM`. Eliminado desde PHP 8.4.0.

`MYSQLI_TYPE_ENUM` (int)

  El campo es de tipo `ENUM`.

`MYSQLI_TYPE_SET` (int)

  El campo es de tipo `SET`.

`MYSQLI_TYPE_TINY_BLOB` (int)

  El campo es de tipo `TINYBLOB`.

`MYSQLI_TYPE_MEDIUM_BLOB` (int)

  El campo es de tipo `MEDIUMBLOB`.

`MYSQLI_TYPE_LONG_BLOB` (int)

  El campo es de tipo `LONGBLOB`.

`MYSQLI_TYPE_BLOB` (int)

  El campo es de tipo `BLOB`.

`MYSQLI_TYPE_VAR_STRING` (int)

  El campo es de tipo `VARCHAR`.

`MYSQLI_TYPE_STRING` (int)

  El campo es de tipo `STRING` o `BINARY`.

`MYSQLI_TYPE_CHAR` (int)

  El campo es de tipo `TINYINT`. Para `CHAR`, ver `MYSQLI_TYPE_STRING`.

`MYSQLI_TYPE_GEOMETRY` (int)

  El campo es de tipo `GEOMETRY`.

`MYSQLI_TYPE_JSON` (int)

  El campo es de tipo `JSON`. Únicamente válido para mysqlnd y MySQL 5.7.8 y posteriores.

`MYSQLI_TYPE_VECTOR` (int)

  El campo está definido como `VECTOR`.

`MYSQLI_NEED_DATA`

  Quedan variables por enlazar.

`MYSQLI_ENUM_FLAG` (int)

  El campo está definido como `ENUM`.

`MYSQLI_BINARY_FLAG` (int)

  El campo está definido como `BINARY`.

`MYSQLI_CURSOR_TYPE_FOR_UPDATE` (int)

`MYSQLI_CURSOR_TYPE_NO_CURSOR` (int)

  Eliminado a partir de PHP 8.4.0.

`MYSQLI_CURSOR_TYPE_READ_ONLY` (int)

  Eliminado a partir de PHP 8.4.0.

`MYSQLI_CURSOR_TYPE_SCROLLABLE` (int)

  Eliminado a partir de PHP 8.4.0.

`MYSQLI_STMT_ATTR_CURSOR_TYPE` (int)

`MYSQLI_STMT_ATTR_PREFETCH_ROWS` (int)

`MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH` (int)

`MYSQLI_SET_CHARSET_NAME` (int)

`MYSQLI_REPORT_INDEX` (int)

  Reporta si se utiliza un índice incorrecto o ningún índice en una consulta.

`MYSQLI_REPORT_ERROR` (int)

  Reporta los errores desde llamadas a funciones mysqli.

`MYSQLI_REPORT_STRICT` (int)

  Lanza una excepción `mysqli_sql_exception` para los errores en lugar de alertas.

`MYSQLI_REPORT_ALL` (int)

  Activa todas las opciones.

`MYSQLI_REPORT_OFF` (int)

  Desactiva todas las opciones.

`MYSQLI_DEBUG_TRACE_ENABLED` (int)

  Establecido en 1 si la funcionalidad mysqli_debug() está desactivada.

`MYSQLI_SERVER_PUBLIC_KEY` (int)

`MYSQLI_REFRESH_GRANT` (int)

  Refresca las tablas GRANT. Obsoleto a partir de PHP 8.4.0.

`MYSQLI_REFRESH_LOG` (int)

  Vacía los logs, idéntico a ejecutar la consulta SQL `FLUSH LOGS`. Obsoleto a partir de PHP 8.4.0.

`MYSQLI_REFRESH_TABLES` (int)

  Vacía la caché de las tablas, idéntico a ejecutar la consulta SQL `FLUSH TABLES`. Obsoleto a partir de PHP 8.4.0.

`MYSQLI_REFRESH_HOSTS` (int)

  Vacía la caché de los hosts, idéntico a ejecutar la consulta SQL `FLUSH HOSTS`. Obsoleto a partir de PHP 8.4.0.

`MYSQLI_REFRESH_REPLICA` (int)

  Alias de la constante `MYSQLI_REFRESH_SLAVE`. Disponible a partir de PHP 8.1.0. Obsoleto a partir de PHP 8.4.0.

`MYSQLI_REFRESH_STATUS` (int)

  Reinicia el estado de las variables, idéntico a ejecutar la consulta SQL `FLUSH STATUS`. Obsoleto a partir de PHP 8.4.0.

`MYSQLI_REFRESH_THREADS` (int)

  Vacía la caché de los hilos. Obsoleto a partir de PHP 8.4.0.

`MYSQLI_REFRESH_SLAVE` (int)

  En un servidor esclavo de replicación: reinicia las informaciones del servidor maestro, y reinicia el esclavo. Idéntico a ejecutar la consulta SQL `RESET SLAVE`. Obsoleto a partir de PHP 8.4.0.

`MYSQLI_REFRESH_MASTER` (int)

  En un servidor maestro de replicación: elimina los archivos binarios de logs listados en el índice binario de logs, y trunca el archivo índice. Idéntico a ejecutar la consulta SQL `RESET MASTER`. Obsoleto a partir de PHP 8.4.0.

`MYSQLI_REFRESH_BACKUP_LOG` (int)
  Cierra y reabre los archivos de registro de copia de seguridad. Obsoleto a partir de PHP 8.4.0.
`MYSQLI_TRANS_COR_AND_CHAIN` (int)

  Añade "AND CHAIN" a mysqli_commit() o mysqli_rollback().

`MYSQLI_TRANS_COR_AND_NO_CHAIN` (int)

  Añade "AND NO CHAIN" a mysqli_commit() o mysqli_rollback().

`MYSQLI_TRANS_COR_RELEASE` (int)

  Añade "RELEASE" a mysqli_commit() o mysqli_rollback().

`MYSQLI_TRANS_COR_NO_RELEASE` (int)

  Añade "NO RELEASE" a mysqli_commit() o mysqli_rollback().

`MYSQLI_TRANS_START_READ_ONLY` (int)

  Inicia la transacción como "START TRANSACTION READ ONLY".

`MYSQLI_TRANS_START_READ_WRITE` (int)

  Inicia la transacción como "START TRANSACTION READ WRITE" con mysqli_begin_transaction().

`MYSQLI_TRANS_START_WITH_CONSISTENT_SNAPSHOT` (int)

  Inicia la transacción como "START TRANSACTION WITH CONSISTENT SNAPSHOT" con mysqli_begin_transaction().

`MYSQLI_CLIENT_SSL_DONT_VERIFY_SERVER_CERT` (int)

  Requiere MySQL 5.6.5 o posterior.

`MYSQLI_IS_MARIADB` (bool)

  Si la extensión mysqli fue construida contra una biblioteca cliente MariaDB. Disponible a partir de PHP 8.1.2.

`MYSQLI_ASYNC` (int)
  La consulta se ejecuta de manera asíncrona y ningún conjunto de resultados es devuelto inmediatamente. Disponible únicamente con `mysqlnd`.
`MYSQLI_ON_UPDATE_NOW_FLAG` (int)
  Si un campo es actualizado, recibirá el valor temporal actual.

# Notas

Algunas notas sobre la implementación:

1. El soporte para `MYSQL_TYPE_GEOMETRY` fue añadido a la extensión MySQLI en PHP 5.3.

2. Cabe señalar que existen diferencias internas de implementación entre `libmysqlclient` y `mysqlnd` para gestionar las columnas de tipo `MYSQL_TYPE_GEOMETRY`. En términos generales, `mysqlnd` asigna considerablemente menos memoria. Por ejemplo, si existe una columna de tipo `POINT` en el conjunto de resultados, `libmysqlclient` asignará aproximadamente 4GB de RAM mientras que solo se requieren 50 bytes para gestionar una columna de tipo `POINT` en memoria. La asignación de memoria es aún menor que 50 bytes al utilizar `mysqlnd`.

# Resumen de las funciones de la extensión MySQLi

Resumen de los métodos mysqli
Clase mysqli
Interfaz POO | Interfaz procedural | Alias (No usar más) | Descripción
--- | --- | --- | ---
Propiedades
$mysqli::affected_rows | mysqli_affected_rows() | N/A | Devuelve el número de filas afectadas por la última operación MySQL
$mysqli::client_info | mysqli_get_client_info() | N/A | Devuelve la versión del cliente MySQL en forma de string
$mysqli::client_version | mysqli_get_client_version() | N/A | Devuelve la información sobre la versión del cliente MySQL en forma de un entero
$mysqli::connect_errno | mysqli_connect_errno() | N/A | Devuelve el código de error de la conexión MySQL
$mysqli::connect_error | mysqli_connect_error() | N/A | Devuelve el mensaje de error de la conexión MySQL
$mysqli::errno | mysqli_errno() | N/A | Devuelve el código de error de conexión MySQL
$mysqli::error | mysqli_error() | N/A | Devuelve el mensaje de error de conexión MySQL
$mysqli::field_count | mysqli_field_count() | N/A | Devuelve el número de columnas para la última consulta
$mysqli::host_info | mysqli_get_host_info() | N/A | Devuelve una cadena que contiene el tipo de conexión utilizada
$mysqli::protocol_version | mysqli_get_proto_info() | N/A | Devuelve la versión del protocolo MySQL utilizado
$mysqli::server_info | mysqli_get_server_info() | N/A | Devuelve un entero que representa la versión del servidor MySQL
$mysqli::server_version | mysqli_get_server_version() | N/A | Devuelve la versión del servidor MySQL
$mysqli::info | mysqli_info() | N/A | Devuelve información sobre la última consulta ejecutada
$mysqli::insert_id | mysqli_insert_id() | N/A | Devuelve el identificador generado automáticamente por la última consulta
$mysqli::sqlstate | mysqli_sqlstate() | N/A | Devuelve el error SQLSTATE de la última operación MySQL
$mysqli::warning_count | mysqli_warning_count() | N/A | Devuelve el número de advertencias generadas por la última consulta
Métodos
mysqli::autocommit() | mysqli_autocommit() | N/A | Activa o desactiva el modo auto-commit
mysqli::change_user() | mysqli_change_user() | N/A | Cambia el usuario de la conexión especificada
mysqli::character_set_name() | mysqli_character_set_name() | N/A() | Devuelve el juego de caracteres actual para la conexión
mysqli::close() | mysqli_close() | N/A | Cierra una conexión
mysqli::commit() | mysqli_commit() | N/A | Valida la transacción actual
mysqli::__construct() | mysqli_connect() | N/A | Abre una conexión a un servidor MySQL
mysqli::debug() | mysqli_debug() | N/A | Realiza acciones de depuración
mysqli::dump_debug_info() | mysqli_dump_debug_info() | N/A | Escribe la información de depuración en los registros
mysqli::get_charset() | mysqli_get_charset() | N/A | Devuelve un objeto que representa el juego de caracteres
mysqli::get_connection_stats() | mysqli_get_connection_stats() | N/A | Devuelve estadísticas sobre la conexión del cliente. Disponible solo con mysqlnd.
mysqli::get_client_info() | mysqli_get_client_info() | N/A | Devuelve una cadena que contiene la versión del cliente MySQL
N/A | mysqli_get_client_stats() | N/A | Devuelve las estadísticas del cliente MySQL. Disponible solo con mysqlnd.
mysqli::get_server_info() | mysqli_get_server_info() | N/A | Devuelve una cadena que representa la versión del servidor MySQL al que la extensión MySQLi está conectada
mysqli::get_warnings() | mysqli_get_warnings() | N/A | No documentado
mysqli::init() | mysqli_init() | N/A | Inicializa MySQLi y devuelve un objeto para usar con mysqli_real_connect()
mysqli::kill() | mysqli_kill() | N/A | Solicita al servidor que termine un hilo MySQL
mysqli::more_results() | mysqli_more_results() | N/A | Verifica si hay más conjuntos de resultados MySQL disponibles
mysqli::multi_query() | mysqli_multi_query() | N/A | Ejecuta una consulta múltiple MySQL
mysqli::next_result() | mysqli_next_result() | N/A | Prepara el siguiente resultado de una consulta múltiple
mysqli::options() | mysqli_options() | mysqli_set_opt() | Define las opciones
mysqli::ping() | mysqli_ping() | N/A | Hace ping a la conexión al servidor y se reconecta si ya no existe
mysqli::prepare() | mysqli_prepare() | N/A | Prepara una consulta SQL para su ejecución
mysqli::query() | mysqli_query() | N/A | Ejecuta una consulta en la base de datos
mysqli::real_connect() | mysqli_real_connect() | N/A | Abre una conexión a un servidor MySQL
mysqli::real_escape_string(), mysqli::escape_string() | mysqli_real_escape_string() | mysqli_escape_string() | Protege los caracteres especiales de una cadena para usarla en una consulta
mysqli::real_query() | mysqli_real_query() | N/A | Ejecuta una consulta SQL
mysqli::refresh() | mysqli_refresh() | N/A | Reinicializa las tablas o las cachés, o reinicializa la información de replicación del servidor
mysqli::rollback() | mysqli_rollback() | N/A | Revierte la transacción actual
mysqli::select_db() | mysqli_select_db() | N/A | Selecciona una base de datos por defecto para las consultas
mysqli::set_charset() | mysqli_set_charset() | N/A | Define el juego de caracteres por defecto del cliente
mysqli::ssl_set() | mysqli_ssl_set() | N/A | Utilizada para establecer una conexión segura con SSL
mysqli::stat() | mysqli_stat() | N/A | Obtiene el estado actual del sistema
mysqli::stmt_init() | mysqli_stmt_init() | N/A | Inicializa un comando MySQL
mysqli::store_result() | mysqli_store_result() | N/A | Transfiere un conjunto de resultados desde la última consulta
mysqli::thread_id() | mysqli_thread_id() | N/A | Devuelve el identificador del hilo para la conexión actual
mysqli::thread_safe() | mysqli_thread_safe() | N/A | Indica si el soporte de hilos está activado o no
mysqli::use_result() | mysqli_use_result() | N/A | Inicializa la recuperación de un conjunto de resultados

Resumen de los métodos mysqli_stmt
MySQL_STMT
Interfaz POO | Interfaz procedural | Alias (No usar más) | Descripción
--- | --- | --- | ---
Propiedades
$mysqli_stmt::affected_rows | mysqli_stmt_affected_rows() | N/A | El número total de filas modificadas, eliminadas o insertadas por la última
$mysqli_stmt::errno | mysqli_stmt_errno() | N/A | El código de error de la última consulta
$mysqli_stmt::error | mysqli_stmt_error() | N/A | El mensaje de error de la última consulta
$mysqli_stmt::field_count | mysqli_stmt_field_count() | N/A | El número de campos presente en la consulta dada
$mysqli_stmt::insert_id | mysqli_stmt_insert_id() | N/A | El ID generado por la última consulta INSERT
$mysqli_stmt::num_rows | mysqli_stmt_num_rows() | N/A | El número de filas de un resultado MySQL
$mysqli_stmt::param_count | mysqli_stmt_param_count() | N/A | El número de parámetros de un comando SQL
$mysqli_stmt::sqlstate | mysqli_stmt_sqlstate() | N/A | El código SQLSTATE de la última operación MySQL
Métodos
mysqli_stmt::attr_get() | mysqli_stmt_attr_get() | N/A | Recupera el valor actual de un atributo de consulta
mysqli_stmt::attr_set() | mysqli_stmt_attr_set() | N/A | Modifica el comportamiento de una consulta preparada
mysqli_stmt::bind_param() | mysqli_stmt_bind_param() | N/A | Vincula variables a una consulta MySQL
mysqli_stmt::bind_result() | mysqli_stmt_bind_result() | N/A | Vincula variables a un conjunto de resultados
mysqli_stmt::close() | mysqli_stmt_close() | N/A | Termina una consulta preparada
mysqli_stmt::data_seek() | mysqli_stmt_data_seek() | N/A | Mueve el puntero de resultado
mysqli_stmt::execute() | mysqli_stmt_execute() | mysqli_execute() | Ejecuta una consulta preparada
mysqli_stmt::fetch() | mysqli_stmt_fetch() | N/A | Lee resultados desde una consulta MySQL preparada en variables vinculadas
mysqli_stmt::free_result() | mysqli_stmt_free_result() | N/A | Libera el resultado MySQL de la memoria
mysqli_stmt::get_result() | mysqli_stmt_get_result() | N/A | Recupera el conjunto de resultados desde una consulta preparada. Disponible solo con mysqlnd.
mysqli_stmt::get_warnings() | mysqli_stmt_get_warnings() | N/A | No documentado
mysqli_stmt::more_results() | mysqli_stmt_more_results() | N/A | Verifica si hay más resultados de consulta desde una consulta múltiple
mysqli_stmt::next_result() | mysqli_stmt_next_result() | N/A | Lee el siguiente resultado desde una consulta múltiple
mysqli_stmt::num_rows() | mysqli_stmt_num_rows() | N/A | Ver también la propiedad $mysqli_stmt->num_rows
mysqli_stmt::prepare() | mysqli_stmt_prepare() | N/A | Prepara una consulta SQL para su ejecución
mysqli_stmt::reset() | mysqli_stmt_reset() | N/A | Anula una consulta preparada
mysqli_stmt::result_metadata() | mysqli_stmt_result_metadata() | N/A | Devuelve los metadatos de preparación de consulta MySQL
mysqli_stmt::send_long_data() | mysqli_stmt_send_long_data() | N/A | Envía datos MySQL por paquetes
mysqli_stmt::store_result() | mysqli_stmt_store_result() | N/A | Almacena un conjunto de resultados desde una consulta preparada

Resumen de los métodos mysqli_result
mysqli_result
Interfaz POO | Interfaz procedural | Alias (No usar más) | Descripción
--- | --- | --- | ---
Propiedades
$mysqli_result::current_field | mysqli_field_tell() | N/A | La posición actual de un campo en un puntero de resultado
$mysqli_result::field_count | mysqli_num_fields() | N/A | El número de campos en un resultado
$mysqli_result::lengths | mysqli_fetch_lengths() | N/A | Los tamaños de los campos en un resultado
$mysqli_result::num_rows | mysqli_num_rows() | N/A | El número de filas en un resultado
Métodos
mysqli_result::data_seek() | mysqli_data_seek() | N/A | Mueve el puntero interno de resultado
mysqli_result::fetch_all() | mysqli_fetch_all() | N/A | Lee todas las filas de resultados en un array asociativo, numérico, o ambos. Disponible solo con mysqlnd.
mysqli_result::fetch_array() | mysqli_fetch_array() | N/A | Devuelve una fila de resultado en forma de un array asociativo, un array indexado, o ambos
mysqli_result::fetch_assoc() | mysqli_fetch_assoc() | N/A | Recupera una fila de resultado en forma de array asociativo
mysqli_result::fetch_column() | mysqli_fetch_column() | N/A | Recupera una sola columna de la siguiente fila de un conjunto de resultados
mysqli_result::fetch_field_direct() | mysqli_fetch_field_direct() | N/A | Recupera los metadatos de un campo único
mysqli_result::fetch_field() | mysqli_fetch_field() | N/A | Devuelve el siguiente campo en el conjunto de resultados
mysqli_result::fetch_fields() | mysqli_fetch_fields() | N/A | Devuelve un array de objetos que representan los campos en el resultado
mysqli_result::fetch_object() | mysqli_fetch_object() | N/A | Devuelve la fila actual de un conjunto de resultados en forma de objeto
mysqli_result::fetch_row() | mysqli_fetch_row() | N/A | Recupera una fila de resultado en forma de array indexado
mysqli_result::field_seek() | mysqli_field_seek() | N/A | Mueve el puntero de resultado al campo especificado
mysqli_result::free(), mysqli_result::close, mysqli_result::free_result | mysqli_free_result() | N/A | Libera la memoria asociada a un resultado

Resumen de los métodos mysqli_driver
MySQL_Driver
Interfaz POO | Interfaz procedural | Alias (No usar más) | Descripción
--- | --- | --- | ---
Propiedades
$mysqli_driver::mysqli_report | mysqli_report() | N/A | Define el modo del informe de errores de mysqli
Métodos
mysqli_driver::embedded_server_end() | mysqli_embedded_server_end() | N/A | No documentado
mysqli_driver::embedded_server_start() | mysqli_embedded_server_start() | N/A | No documentado

> Nota:

> Los alias se proporcionan para asegurar la compatibilidad ascendente. No se deben usar en nuevos proyectos.

# La clase mysqli

(PHP 5, PHP 7, PHP 8)

## Introducción

Representa una conexión entre PHP y una base de datos MySQL.

## Sinopsis de la Clase

class mysqli {
/* Propiedades */
public readonly int|string $affected_rows;
public readonly string $client_info;
public readonly int $client_version;
public readonly int $connect_errno;
public readonly ?string $connect_error;
public readonly int $errno;
public readonly string $error;
public readonly array $error_list;
public readonly int $field_count;
public readonly string $host_info;
public readonly ?string $info;
public readonly int|string $insert_id;
public readonly string $server_info;
public readonly int $server_version;
public readonly string $sqlstate;
public readonly int $protocol_version;
public readonly int $thread_id;
public readonly int $warning_count;
/* Métodos */
public function __construct(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
)
public function autocommit(bool `$enable`): bool
public function begin_transaction(int `$flags` = 0, ?string `$name` = `null`): bool
public function change_user(string `$username`, #[\SensitiveParameter]string `$password`, ?string `$database`): bool
public function character_set_name(): string
public function close(): true
public function commit(int `$flags` = 0, ?string `$name` = `null`): bool
public function connect(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
): bool
public function debug(string `$options`): true
public function dump_debug_info(): bool
public function execute_query(string `$query`, ?array `$params` = `null`): mysqli_result|bool
public function get_charset(): ?object
#[\Deprecated]
public function get_client_info(): string
public function get_connection_stats(): array
public function get_server_info(): string
public function get_warnings(): mysqli_warning|false
#[\Deprecated]
public function init(): ?bool
#[\Deprecated]
public function kill(int `$process_id`): bool
public function more_results(): bool
public function multi_query(string `$query`): bool
public function next_result(): bool
public function options(int `$option`, string|int `$value`): bool
#[\Deprecated]
public function ping(): bool
public static function poll(
?array `&$read`,
?array `&$error`,
array `&$reject`,
int `$seconds`,
int `$microseconds` = 0
): int|false
public function prepare(string `$query`): mysqli_stmt|false
public function query(string `$query`, int `$result_mode` = MYSQLI_STORE_RESULT): mysqli_result|bool
public function real_connect(
?string `$hostname` = null,
?string `$username` = null,
#[\SensitiveParameter]?string `$password` = null,
?string `$database` = null,
?int `$port` = null,
?string `$socket` = null,
int `$flags` = 0
): bool
public function real_escape_string(string `$string`): string
public function real_query(string `$query`): bool
public function reap_async_query(): mysqli_result|bool
#[\Deprecated]
public function refresh(int `$flags`): bool
public function release_savepoint(string `$name`): bool
public function rollback(int `$flags` = 0, ?string `$name` = null): bool
public function savepoint(string `$name`): bool
public function select_db(string `$database`): bool
public function set_charset(string `$charset`): bool
public function ssl_set(
?string `$key`,
?string `$certificate`,
?string `$ca_certificate`,
?string `$ca_path`,
?string `$cipher_algos`
): true
public function stat(): string|false
public function stmt_init(): mysqli_stmt|false
public function store_result(int `$mode` = 0): mysqli_result|false
public function thread_safe(): bool
public function use_result(): mysqli_result|false
}

# mysqli::$affected_rows

# mysqli_affected_rows

(PHP 5, PHP 7, PHP 8)

mysqli::$affected_rows -- mysqli_affected_rows — Devuelve el número de filas afectadas por la última operación MySQL

### Descripción

Estilo orientado a objetos

int|string $mysqli->affected_rows;

Estilo procedimental

function mysqli_affected_rows(mysqli `$mysql`): int|string

Devuelve el número de filas afectadas por la última consulta `INSERT`, `UPDATE`, `REPLACE` o `DELETE` asociada al argumento `link`.

Funciona como mysqli_num_rows() para las consultas `SELECT`.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

Un entero mayor que cero indica el número de filas afectadas o recuperadas. Cero indica que ningún registro fue modificado por una consulta del tipo `UPDATE`, ninguna fila coincide con la cláusula `WHERE` en la consulta o que ninguna consulta fue ejecutada. `-1` indica que la consulta devolvió un error o que mysqli_affected_rows() fue llamado sobre una consulta `SELECT` no almacenada en búfer.

> Nota:

> Si el número de filas afectadas es mayor que el valor máximo (`PHP_INT_MAX`) que puede tomar un entero, el número de filas afectadas será devuelto como un string.

### Ejemplos

Ejemplo #1 Ejemplo con $mysqli->affected_rows

Estilo orientado a objetos

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Inserción de una fila */
    $mysqli->query("CREATE TABLE Language SELECT * from CountryLanguage");
    printf("Número de filas afectadas (INSERT): %d\n", $mysqli->affected_rows);

    $mysqli->query("ALTER TABLE Language ADD Status int default 0");

    /* Modificación de una fila */
    $mysqli->query("UPDATE Language SET Status=1 WHERE Percentage > 50");
    printf("Número de filas afectadas (UPDATE): %d\n", $mysqli->affected_rows);

    /* Eliminación de una fila */
    $mysqli->query("DELETE FROM Language WHERE Percentage < 50");
    printf("Número de filas afectadas (DELETE): %d\n", $mysqli->affected_rows);

    /* Selección de todas las filas */
    $result = $mysqli->query("SELECT CountryCode FROM Language");
    printf("Número de filas afectadas (SELECT): %d\n", $mysqli->affected_rows);

    /* Eliminación de la tabla Language */
    $mysqli->query("DROP TABLE Language");
    ?>

Estilo procedimental

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Inserción de una fila */
    mysqli_query($link, "CREATE TABLE Language SELECT * from CountryLanguage");
    printf("Número de filas afectadas (INSERT): %d\n", mysqli_affected_rows($link));

    mysqli_query($link, "ALTER TABLE Language ADD Status int default 0");

    /* Modificación de una fila */
    mysqli_query($link, "UPDATE Language SET Status=1 WHERE Percentage > 50");
    printf("Número de filas afectadas (UPDATE): %d\n", mysqli_affected_rows($link));

    /* Eliminación de una fila */
    mysqli_query($link, "DELETE FROM Language WHERE Percentage < 50");
    printf("Número de filas afectadas (DELETE): %d\n", mysqli_affected_rows($link));

    /* Selección de todas las filas */
    $result = mysqli_query($link, "SELECT CountryCode FROM Language");
    printf("Número de filas afectadas (SELECT): %d\n", mysqli_affected_rows($link));

    /* Eliminación de la tabla "language" */
    mysqli_query($link, "DROP TABLE Language");
    ?>

Los ejemplos anteriores mostrarán:

    Número de filas afectadas (INSERT): 984
    Número de filas afectadas (UPDATE): 168
    Número de filas afectadas (DELETE): 815
    Número de filas afectadas (SELECT): 169

### Ver también

- mysqli_num_rows() - Devuelve el número de filas en el conjunto de resultados
- mysqli_info() - Devuelve información acerca de la última consulta ejecutada

# mysqli::autocommit

# mysqli_autocommit

(PHP 5, PHP 7, PHP 8)

mysqli::autocommit -- mysqli_autocommit — Activa o desactiva el modo auto-commit

### Descripción

Estilo orientado a objetos

public function mysqli::autocommit(bool `$enable`): bool

Estilo procedimental

function mysqli_autocommit(mysqli `$mysql`, bool `$enable`): bool

Activa o desactiva el modo auto-commit para las consultas en la conexión.

Para verificar el estado del auto-commit, se puede utilizar el comando SQL `SELECT @@autocommit`.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()
`enable`

  Si se debe activar o no el auto-commit.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Ejemplos

Ejemplo #1 Ejemplo con mysqli::autocommit()

Estilo orientado a objetos

    <?php

    /* Solicita a mysqli que lance una excepción si ocurre un error */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* El motor de tabla soporta transacciones */
    $mysqli->query("CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* Desactiva el autocommit */
    $mysqli->autocommit(false);

    $result = $mysqli->query("SELECT @@autocommit");
    $row = $result->fetch_row();
    printf("El Autocommit vale %s\n", $row[0]);

    try {
        /* Prepara una consulta de inserción */
        $stmt = $mysqli->prepare('INSERT INTO language(Code, Speakers) VALUES (?,?)');
        $stmt->bind_param('ss', $language_code, $native_speakers);

        /* Inserta varios valores */
        $language_code = 'DE';
        $native_speakers = 50_123_456;
        $stmt->execute();
        $language_code = 'FR';
        $native_speakers = 40_546_321;
        $stmt->execute();

        /* Confirma los datos en la base de datos. Esto no activa el autocommit */
        $mysqli->commit();
        print "Confirmación de 2 líneas en la base de datos\n";

        $result = $mysqli->query("SELECT @@autocommit");
        $row = $result->fetch_row();
        printf("El autocommit vale %s\n", $row[0]);

        /* Intenta insertar varios valores */
        $language_code = 'PL';
        $native_speakers = 30_555_444;
        $stmt->execute();
        $language_code = 'DK';
        $native_speakers = 5_222_444;
        $stmt->execute();

        /* Establecer autocommit=true provocará el commit */
        $mysqli->autocommit(true);

        print "Confirmación de 2 líneas en la base de datos\n";
    } catch (mysqli_sql_exception $exception) {
        $mysqli->rollback();

        throw $exception;
    }

Estilo procedimental

    <?php

    /* Solicita a mysqli que lance una excepción si ocurre un error */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* El motor de tabla soporta transacciones */
    mysqli_query($mysqli, "CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* Desactiva el autocommit */
    mysqli_autocommit($mysqli, false);

    $result = mysqli_query($mysqli, "SELECT @@autocommit");
    $row = mysqli_fetch_row($result);
    printf("El Autocommit vale %s\n", $row[0]);

    try {
        /* Prepara una consulta de inserción */
        $stmt = mysqli_prepare($mysqli, 'INSERT INTO language(Code, Speakers) VALUES (?,?)');
        mysqli_stmt_bind_param($stmt, 'ss', $language_code, $native_speakers);

        /* Inserta varios valores */
        $language_code = 'DE';
        $native_speakers = 50_123_456;
        mysqli_stmt_execute($stmt);
        $language_code = 'FR';
        $native_speakers = 40_546_321;
        mysqli_stmt_execute($stmt);

        /* Confirma los datos en la base de datos. Esto no activa el autocommit */
        mysqli_commit($mysqli);
        print "Confirmación de 2 líneas en la base de datos\n";

        $result = mysqli_query($mysqli, "SELECT @@autocommit");
        $row = mysqli_fetch_row($result);
        printf("El autocommit vale %s\n", $row[0]);

        /* Intenta insertar varios valores */
        $language_code = 'PL';
        $native_speakers = 30_555_444;
        mysqli_stmt_execute($stmt);
        $language_code = 'DK';
        $native_speakers = 5_222_444;
        mysqli_stmt_execute($stmt);

        /* Establecer autocommit=true provocará el commit */
        mysqli_autocommit($mysqli, true);

        print "Confirmación de 2 líneas en la base de datos\n";
    } catch (mysqli_sql_exception $exception) {
        mysqli_rollback($mysqli);

        throw $exception;
    }

Los ejemplos anteriores mostrarán:

    El autocommit vale 0
    Confirmación de 2 líneas en la base de datos
    El autocommit vale 0
    Confirmación de 2 líneas en la base de datos
    El autocommit vale 0
    Confirmación de 2 líneas en la base de datos
    El autocommit vale 0
    Confirmación de 2 líneas en la base de datos

### Notas

> Nota:

> Esta función no funciona con los tipos de tablas no transaccionales, como MyISAM o ISAM.

### Ver también

- mysqli_begin_transaction() - Inicia una transacción
- mysqli_commit() - Valida la transacción actual
- mysqli_rollback() - Revierte la transacción actual

# mysqli::begin_transaction

# mysqli_begin_transaction

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::begin_transaction -- mysqli_begin_transaction — Inicia una transacción

### Descripción

Estilo orientado a objetos

public function mysqli::begin_transaction(int `$flags` = 0, ?string `$name` = `null`): bool

Estilo procedimental:

function mysqli_begin_transaction(mysqli `$mysql`, int `$flags` = 0, ?string `$name` = `null`): bool

Inicia una transacción. Requiere el motor InnoDB (está activo por omisión). Para más detalles sobre el funcionamiento de las transacciones MySQL, ver » http://dev.mysql.com/doc/mysql/en/commit.html.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()
`flags`

  Los flag válidos son:

  - `MYSQLI_TRANS_START_READ_ONLY`: Inicia la transacción como "START TRANSACTION READ ONLY". Requiere MySQL 5.6 o superior.

  - `MYSQLI_TRANS_START_READ_WRITE`: Inicia la transacción como "START TRANSACTION READ WRITE". Requiere MySQL 5.6 o superior.

  - `MYSQLI_TRANS_START_WITH_CONSISTENT_SNAPSHOT`: Inicia la transacción como "START TRANSACTION WITH CONSISTENT SNAPSHOT".

`name`

  Nombre del punto de guardado para la transacción.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `name` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con mysqli::begin_transaction()

Estilo orientado a objetos

    <?php

    /* Indica a mysqli que lance una excepción si ocurre un error */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* El motor de tabla soporta transacciones */
    $mysqli->query("CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* Inicia la transacción */
    $mysqli->begin_transaction();

    try {
        /* Inserta varios valores */
        $mysqli->query("INSERT INTO language(Code, Speakers) VALUES ('DE', 42000123)");

        /* Intenta insertar valores incorrectos */
        $language_code = 'FR';
        $native_speakers = 'Unknown';
        $stmt = $mysqli->prepare('INSERT INTO language(Code, Speakers) VALUES (?,?)');
        $stmt->bind_param('ss', $language_code, $native_speakers);
        $stmt->execute();

        /* Si el código llega a este punto sin errores, entonces se confirman los datos en
           la base de datos */
        $mysqli->commit();
    } catch (mysqli_sql_exception $exception) {
        $mysqli->rollback();

        throw $exception;
    }

Estilo procedimental

    <?php

    /* Indica a mysqli que lance una excepción si ocurre un error */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* El motor de tabla soporta transacciones */
    mysqli_query($mysqli, "CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* Inicia la transacción */
    mysqli_begin_transaction($mysqli);

    try {
        /* Inserta varios valores */
        mysqli_query($mysqli, "INSERT INTO language(Code, Speakers) VALUES ('DE', 42000123)");

        /* Intenta insertar valores incorrectos */
        $language_code = 'FR';
        $native_speakers = 'Unknown';
        $stmt = mysqli_prepare($mysqli, 'INSERT INTO language(Code, Speakers) VALUES (?,?)');
        mysqli_stmt_bind_param($stmt, 'ss', $language_code, $native_speakers);
        mysqli_stmt_execute($stmt);

        /* Si el código llega a este punto sin errores, entonces se confirman los datos en
           la base de datos */
        mysqli_commit($mysqli);
    } catch (mysqli_sql_exception $exception) {
        mysqli_rollback($mysqli);

        throw $exception;
    }

### Notas

> Nota:

> Esta función no funciona con tipos de tabla no transaccionales (como MyISAM o ISAM).

### Ver también

- mysqli_autocommit() - Activa o desactiva el modo auto-commit
- mysqli_commit() - Valida la transacción actual
- mysqli_rollback() - Revierte la transacción actual

# mysqli::change_user

# mysqli_change_user

(PHP 5, PHP 7, PHP 8)

mysqli::change_user -- mysqli_change_user — Cambia el usuario de la conexión

### Descripción

Estilo orientado a objetos

public function mysqli::change_user(string `$username`, #[\SensitiveParameter]string `$password`, ?string `$database`): bool

Estilo procedimental

function mysqli_change_user(
mysqli `$mysql`,
string `$username`,
#[\SensitiveParameter]string `$password`,
?string `$database`
): bool

Intenta conectarse a la base de datos especificada utilizando las credenciales proporcionadas.

A diferencia de mysqli::connect(), este método no desconectará la conexión actual si la nueva conexión no puede establecerse.

Para que esta función tenga éxito, los parámetros `username` y `password` deben ser válidos y el usuario en cuestión debe tener los permisos de acceso a la base de datos deseada. Si por alguna razón la autorización falla, el usuario actual se conservará.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()
`username`

  El nombre de usuario MySQL.

`password`

  La contraseña MySQL.

`database`

  El nombre de la base de datos. Si es `null` o una cadena vacía, la conexión al servidor se abrirá sin una base de datos por defecto.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Ejemplos

Ejemplo #1 Reinicio de la sesión de conexión

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    $mysqli->query("SET @a:=1");

    $mysqli->change_user("my_user", "my_password", "world");

    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("Base de datos por defecto: %s\n", $row[0]);

    $result = $mysqli->query("SELECT @a");
    $row = $result->fetch_row();
    if ($row[0] === NULL) {
        printf("El valor de la variable a es NULL\n");
    }

    ?>

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "test");
    mysqli_query($link, "SET @a:=1");

    $result = mysqli_query($link, "SELECT DATABASE()");
    $row = mysqli_fetch_row($result);
    printf("Base de datos por defecto: %s\n", $row[0]);

    $result = mysqli_query($link, "SELECT @a");
    $row = mysqli_fetch_row($result);
    if ($row[0] === NULL) {
        printf("El valor de la variable a es NULL\n");
    }

    ?>

Los ejemplos anteriores mostrarán:

    Base de datos por defecto: world
    El valor de la variable a es NULL

Ejemplo #2 Si `database` es `null` la conexión se abre sin seleccionar una base de datos por defecto

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    $mysqli->change_user("my_user", "my_password", null);

    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("Base de datos por defecto: %s\n", $row[0]);

Los ejemplos anteriores mostrarán:

    Base de datos por defecto:

### Notas

> Nota:

> El uso de este comando implica siempre que la conexión sea considerada como nueva, independientemente de si la función tiene éxito o no. Una llamada a esta función anulará por lo tanto todas las transacciones activas, cerrará las tablas temporales y desbloqueará las tablas bloqueadas.

### Ver también

- mysqli_connect() - Alias de mysqli::__construct
- mysqli_select_db() - Selecciona una base de datos por defecto para las consultas

# mysqli::character_set_name

# mysqli_character_set_name

(PHP 5, PHP 7, PHP 8)

mysqli::character_set_name -- mysqli_character_set_name — Devuelve el juego de caracteres actual para la conexión

### Descripción

Estilo orientado a objetos

public function mysqli::character_set_name(): string

Estilo procedimental

function mysqli_character_set_name(mysqli `$mysql`): string

Devuelve el juego de caracteres actual para la conexión especificada por el argumento `link`.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

El juego de caracteres actual para la conexión actual.

### Ejemplos

Ejemplo #1 Ejemplo de mysqli::character_set_name()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Establecer el juego de caracteres predeterminado */
    $mysqli->set_charset('utf8mb4');

    /* Mostrar el juego de caracteres actual */
    $charset = $mysqli->character_set_name();
    printf("El juego de caracteres actual es %s\n", $charset);

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Establecer el juego de caracteres predeterminado */
    mysqli_set_charset($mysqli, 'utf8mb4');

    /* Mostrar el juego de caracteres actual */
    $charset = mysqli_character_set_name($mysqli);
    printf("El juego de caracteres actual es %s\n", $charset);

Los ejemplos anteriores mostrarán:

    El juego de caracteres actual es utf8mb4

### Ver también

- mysqli_set_charset() - Define el juego de caracteres del cliente
- mysqli_real_escape_string() - Protege los caracteres especiales de un string para su uso en una consulta SQL, teniendo en cuenta el juego de caracteres actual de la conexión

# mysqli::close

# mysqli_close

(PHP 5, PHP 7, PHP 8)

mysqli::close -- mysqli_close — Cierra una conexión

### Descripción

Estilo orientado a objetos

public function mysqli::close(): true

Estilo procedimental

function mysqli_close(mysqli `$mysql`): true

Cierra la conexión especificada por el parámetro `link`.

Las conexiones MySQL no persistentes y los conjuntos de resultados serán cerrados automáticamente cuando sus objetos sean destruidos. Cerrar explícitamente las conexiones abiertas y liberar los conjuntos de resultados es opcional. Sin embargo, es una buena idea cerrar la conexión tan pronto como el script termine de realizar todas sus operaciones de base de datos, si aún tiene mucho procesamiento por hacer después de haber recuperado los resultados.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función ahora siempre devuelve `true`. Anteriormente, devolvía `false` en caso de fallo.

### Ejemplos

Ejemplo #1 Ejemplo de mysqli::close()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $result = $mysqli->query("SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3");

    /* Cerrar la conexión tan pronto como ya no sea necesaria */
    $mysqli->close();

    foreach ($result as $row) {
        /* Procesamiento de los datos recuperados de la base de datos */
    }

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $result = mysqli_query($mysqli, "SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3");

    /* Cerrar la conexión tan pronto como ya no sea necesaria */
    mysqli_close($mysqli);

    foreach ($result as $row) {
        /* Procesamiento de los datos recuperados de la base de datos */
    }

### Notas

> Nota:

> mysqli_close() no cierra las conexiones persistentes. Para más detalles, ver la página del manual sobre las conexiones persistentes.

### Ver también

- mysqli::__construct() - Abre una conexión a un servidor MySQL
- mysqli_init() - Inicializa MySQLi y devuelve un objeto para usar con mysqli_real_connect()
- mysqli_real_connect() - Establece una conexión con un servidor MySQL
- mysqli_free_result() - Libera la memoria asociada a un resultado

# mysqli::commit

# mysqli_commit

(PHP 5, PHP 7, PHP 8)

mysqli::commit -- mysqli_commit — Valida la transacción actual

### Descripción

Estilo orientado a objetos

public function mysqli::commit(int `$flags` = 0, ?string `$name` = `null`): bool

Estilo procedimental

function mysqli_commit(mysqli `$mysql`, int `$flags` = 0, ?string `$name` = `null`): bool

Valida la transacción actual para la base de datos especificada por el argumento `link`.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()
`flags`

  Una máscara de constantes `MYSQLI_TRANS_COR_*`.

`name`

  Si se proporciona, entonces `COMMIT/*name*/` es ejecutado.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `name` es ahora nullable.

### Ejemplos

Ver el ejemplo que se encuentra en la documentación del método mysqli::begin_transaction().

### Notas

> Nota:

> Esta función no funciona con los tipos de tabla no transaccionales (como MyISAM o ISAM).

### Ver también

- mysqli_autocommit() - Activa o desactiva el modo auto-commit
- mysqli_begin_transaction() - Inicia una transacción
- mysqli_rollback() - Revierte la transacción actual
- mysqli_savepoint() - Establece un punto de guardado nombrado de la transacción

# mysqli::$connect_errno

# mysqli_connect_errno

(PHP 5, PHP 7, PHP 8)

mysqli::$connect_errno -- mysqli_connect_errno — Devuelve el código de error de la última llamada de conexión

### Descripción

Estilo orientado a objetos

int $mysqli->connect_errno;

Estilo procedimental

function mysqli_connect_errno(): int

Devuelve el código de error del último intento de conexión.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un código de error para el último intento de conexión, si falla. Cero significa que no ha ocurrido ningún error.

Devuelve el último código de error de conexión, independientemente de la instancia en la que se llame.

### Ejemplos

Ejemplo #1 Ejemplo con $mysqli->connect_errno

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);

    /* @ se utiliza para suprimir las advertencias */
    $mysqli = @new mysqli('localhost', 'fake_user', 'wrong_password', 'does_not_exist');

    if ($mysqli->connect_errno) {
        /* Utilice su método preferido de registro de errores aquí */
        error_log('Error de conexión: ' . $mysqli->connect_errno);
    }

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);

    /* @ se utiliza para suprimir las advertencias */
    $link = @mysqli_connect('localhost', 'fake_user', 'wrong_password', 'does_not_exist');

    if (!$link) {
        /* Utilice su método preferido de registro de errores aquí */
        error_log('Error de conexión: ' . mysqli_connect_errno());
    }

### Ver también

- mysqli_connect() - Alias de mysqli::__construct
- mysqli_connect_error() - Devuelve una descripción del último error de conexión
- mysqli_errno() - Devuelve el último código de error producido
- mysqli_error() - Devuelve un string que describe el último error
- mysqli_sqlstate() - Devuelve el error SQLSTATE de la última operación MySQL

# mysqli::$connect_error

# mysqli_connect_error

(PHP 5, PHP 7, PHP 8)

mysqli::$connect_error -- mysqli_connect_error — Devuelve una descripción del último error de conexión

### Descripción

Estilo orientado a objetos

?string $mysqli->connect_error;

Estilo procedimental

function mysqli_connect_error(): ?string

Devuelve el mensaje de error del último intento de conexión.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Una cadena que describe el error o `null` si no se produce ningún error.

Devuelve el último código de error de conexión, independientemente de la instancia en la que se invoque.

### Ejemplos

Ejemplo #1 Ejemplo con $mysqli->connect_error

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);

    /* @ se utiliza para suprimir las advertencias */
    $mysqli = @new mysqli('localhost', 'fake_user', 'wrong_password', 'does_not_exist');

    if ($mysqli->connect_error) {
        /* Utilice su método preferido de registro de errores aquí */
        error_log('Connection error: ' . $mysqli->connect_error);
    }

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);

    /* @ se utiliza para suprimir las advertencias */
    $link = @mysqli_connect('localhost', 'fake_user', 'wrong_password', 'does_not_exist');

    if (!$link) {
        /* Utilice su método preferido de registro de errores aquí */
        error_log('Connection error: ' . mysqli_connect_error());
    }

### Ver también

- mysqli_connect() - Alias de mysqli::__construct
- mysqli_connect_errno() - Devuelve el código de error de la última llamada de conexión
- mysqli_errno() - Devuelve el último código de error producido
- mysqli_error() - Devuelve un string que describe el último error
- mysqli_sqlstate() - Devuelve el error SQLSTATE de la última operación MySQL

# mysqli::__construct

# mysqli::connect

# mysqli_connect

(PHP 5, PHP 7, PHP 8)

mysqli::__construct -- mysqli::connect -- mysqli_connect — Abre una conexión a un servidor MySQL

### Descripción

Estilo orientado a objetos

public function mysqli::__construct(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
)
public function mysqli::connect(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
): bool

Estilo procedimental

function mysqli_connect(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
): mysqli|false

Abre una conexión al servidor MySQL.

### Parámetros

`hostname`

  Puede ser un nombre de host o una dirección IP. Al pasar `null`, el valor se recupera desde mysqli.default_host. Si es posible, se utilizarán pipes en lugar del protocolo TCP/IP. El protocolo TCP/IP se utiliza si se proporciona un nombre de host y un número de puerto juntos, por ejemplo `localhost:3308`.

  Prefijar el host con `p:` abre una conexión persistente. mysqli_change_user() se llama automáticamente en las conexiones que se utilizan en el grupo de conexiones.

`username`

  El nombre de usuario MySQL o `null` para asumir el nombre de usuario según la opción ini mysqli.default_user.

`password`

  La contraseña MySQL o `null` para asumir la contraseña basándose en la opción ini mysqli.default_pw.

`database`

  La base de datos predeterminada a utilizar al ejecutar consultas o `null`.

`port`

  El número de puerto al que intentar conectarse al servidor MySQL o `null` para asumir el puerto según la opción ini mysqli.default_port.

`socket`

  El socket o el pipe nombrado que debe utilizarse, o `null` para asumir el socket según la opción ini mysqli.default_socket.

  > Nota:

  > Especificar el parámetro `socket` no determinará explícitamente el tipo de conexión que se utilizará al conectarse al servidor MySQL. Esto está determinado por el parámetro `hostname`.

### Valores devueltos

mysqli::__construct() siempre devuelve un objeto que representa la conexión a un servidor MySQL, incluso si la conexión ha fallado.

mysqli_connect() devuelve un objeto que representa la conexión al servidor MySQL, o `false` si ocurre un error.

mysqli::connect() devuelve `true` en caso de éxito o `false` si ocurre un error. Anterior a PHP 8.1.0, devuelve `null` en caso de éxito.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | mysqli::connect() ahora devuelve `true` en lugar de `null` en caso de éxito.
7.4.0 | Todos los parámetros ahora son nullable.

### Ejemplos

Ejemplo #1 Ejemplo mysqli::__construct()

Estilo orientado a objetos

    <?php
    /* Siempre se debe activar el informe de errores para mysqli antes de intentar una conexión */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'my_db');
    /* Establecer el juego de caracteres deseado después de establecer una conexión */
    $mysqli->set_charset('utf8mb4');
    printf("Éxito... %s\n", $mysqli->host_info);

Estilo procedimental

    <?php
    /* Siempre se debe activar el informe de errores para mysqli antes de intentar una conexión */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect('localhost', 'my_user', 'my_password', 'my_db');
    /* Establecer el juego de caracteres deseado después de establecer una conexión */
    mysqli_set_charset($mysqli, 'utf8mb4');
    printf("Éxito... %s\n", mysqli_get_host_info($mysqli));

Los ejemplos anteriores mostrarán algo similar a:

    Éxito... localhost via TCP/IP

Ejemplo #2 Extender la clase mysqli

    <?php
    class FooMysqli extends mysqli {
        public function __construct($host, $user, $pass, $db, $port, $socket, $charset) {
            mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
            parent::__construct($host, $user, $pass, $db, $port, $socket);
            $this->set_charset($charset);
        }
    }
    $db = new FooMysqli('localhost', 'my_user', 'my_password', 'my_db', 3306, null, 'utf8mb4');

Ejemplo #3 Manejo manual de errores

Si el informe de errores está desactivado, el desarrollador es responsable de verificar y manejar los fallos

Estilo orientado a objetos

    <?php
    error_reporting(0);
    mysqli_report(MYSQLI_REPORT_OFF);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'my_db');
    if ($mysqli->connect_errno) {
        throw new RuntimeException('error de conexión mysqli: ' . $mysqli->connect_error);
    }
    /* Establecer el juego de caracteres deseado después de establecer una conexión */
    $mysqli->set_charset('utf8mb4');
    if ($mysqli->errno) {
        throw new RuntimeException('error mysqli: ' . $mysqli->error);
    }

Estilo procedimental

    <?php
    error_reporting(0);
    mysqli_report(MYSQLI_REPORT_OFF);
    $mysqli = mysqli_connect('localhost', 'my_user', 'my_password', 'my_db');
    if (mysqli_connect_errno()) {
        throw new RuntimeException('error de conexión mysqli: ' . mysqli_connect_error());
    }
    /* Establecer el juego de caracteres deseado después de establecer una conexión */
    mysqli_set_charset($mysqli, 'utf8mb4');
    if (mysqli_errno($mysqli)) {
        throw new RuntimeException('error mysqli: ' . mysqli_error($mysqli));
    }

### Notas

> Nota: MySQLnd siempre asume el juego de caracteres predeterminado del servidor. Este juego de caracteres es enviado durante el intercambio de conexión/autenticación, el cual mysqlnd utilizará.Libmysqlclient utiliza el juego de caracteres predeterminado establecido en el my.cnf o mediante una llamada explícita a mysqli_options() antes de llamar a mysqli_real_connect(), pero después de mysqli_init().

> Nota:

> Estilo orientado a objetos solamente: si la conexión falla, se devuelve un objeto de todos modos. Para verificar si la conexión falló, utilice la función mysqli_connect_error() o la propiedad mysqli->connect_error como en el ejemplo anterior.

> Nota:

> Si es necesario configurar opciones, como el tiempo de espera de conexión, mysqli_real_connect() debe ser utilizado.

> Nota:

> Llamar al constructor sin parámetros tiene el mismo efecto que llamar mysqli_init().

> Nota:

> El error `"Can't create TCP/IP socket (10106)"` significa generalmente que la directiva de configuración variables_order no contiene el carácter `E`. En Windows, si el entorno no se copia, la variable de entorno `SYSTEMROOT` no estará disponible y PHP tendrá problemas para cargar Winsock.

### Ver también

- mysqli_real_connect() - Establece una conexión con un servidor MySQL
- mysqli_options() - Define las opciones
- mysqli_connect_errno() - Devuelve el código de error de la última llamada de conexión
- mysqli_connect_error() - Devuelve una descripción del último error de conexión
- mysqli_close() - Cierra una conexión

# mysqli::debug

# mysqli_debug

(PHP 5, PHP 7, PHP 8)

mysqli::debug -- mysqli_debug — Realiza acciones de depuración

### Descripción

Estilo orientado a objetos

public function mysqli::debug(string `$options`): true

Estilo procedimental

function mysqli_debug(string `$options`): true

Realiza acciones de depuración utilizando la biblioteca de depuración Fred Fish.

### Parámetros

`options`

  Un string que representa la operación de depuración a realizar.

  El string de control de depuración es una secuencia de campos separados por dos puntos, como sigue: ``

      <field_1>:<field_2>:<field_N>

  Cada campo se compone de un carácter flag obligatorio seguido de un `,` opcional y una lista de modificadores separados por comas: `flag[,modifier,modifier,...,modifier]`

  Caracteres flag reconocidos
  `options` carácter | Descripción
  --- | ---
  O | `MYSQLND_DEBUG_FLUSH`
  A/a | `MYSQLND_DEBUG_APPEND`
  F | `MYSQLND_DEBUG_DUMP_FILE`
  i | `MYSQLND_DEBUG_DUMP_PID`
  L | `MYSQLND_DEBUG_DUMP_LINE`
  m | `MYSQLND_DEBUG_TRACE_MEMORY_CALLS`
  n | `MYSQLND_DEBUG_DUMP_LEVEL`
  o | salida a fichero
  T | `MYSQLND_DEBUG_DUMP_TIME`
  t | `MYSQLND_DEBUG_DUMP_TRACE`
  x | `MYSQLND_DEBUG_PROFILE_CALLS`

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función devuelve ahora siempre `true`. Anteriormente, devolvía `false` en caso de error.

### Ejemplos

Ejemplo #1 Generación de un fichero de "traza"

    <?php

    /* Genera un fichero de "traza" en '/tmp/client.trace' en la máquina (cliente) local: */
    mysqli_debug("d:t:o,/tmp/client.trace");

    ?>

### Notas

> Nota:

> Para utilizar la función mysqli_debug(), se debe compilar la biblioteca cliente MySQL con soporte de depuración.

### Ver también

- mysqli_dump_debug_info() - Escribe la información de depuración en los registros
- mysqli_report() - Alias de mysqli_driver->report_mode

# mysqli::dump_debug_info

# mysqli_dump_debug_info

(PHP 5, PHP 7, PHP 8)

mysqli::dump_debug_info -- mysqli_dump_debug_info — Escribe la información de depuración en los registros

### Descripción

Estilo orientado a objetos

public function mysqli::dump_debug_info(): bool

Estilo procedimental

function mysqli_dump_debug_info(mysqli `$mysql`): bool

Esta función debe ser utilizada por un usuario con el privilegio SUPER y se emplea para escribir cierta información de depuración en el registro para el servidor MySQL relativo a la conexión especificada por el argumento `link`.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- mysqli_debug() - Realiza acciones de depuración

# mysqli::$errno

# mysqli_errno

(PHP 5, PHP 7, PHP 8)

mysqli::$errno -- mysqli_errno — Devuelve el último código de error producido

### Descripción

Estilo orientado a objetos

int $mysqli->errno;

Estilo procedimental

function mysqli_errno(mysqli `$mysql`): int

Devuelve el código de error para la última llamada a una función MySQLi que puede fallar o tener éxito, respetando la conexión definida por el parámetro `link`.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

El valor del código de error para la última llamada, si falla. `0` significa que no ha ocurrido ningún error.

### Ejemplos

Ejemplo #1 Ejemplo con $mysqli->errno

Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verificación de la conexión */
    if ($mysqli->connect_errno) {
        printf("Fallo en la conexión: %s\n", $mysqli->connect_error);
        exit();
    }

    if (!$mysqli->query("SET a=1")) {
        printf("Código de Error: %d\n", $mysqli->errno);
    }

    /* Cierre de la conexión */
    $mysqli->close();
    ?>

Estilo procedimental

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verificación de la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    if (!mysqli_query($link, "SET a=1")) {
        printf("Código de Error: %d\n", mysqli_errno($link));
    }

    /* Cierre de la conexión */
    mysqli_close($link);
    ?>

Los ejemplos anteriores mostrarán:

    Código de Error: 1193

### Ver también

- mysqli_connect_errno() - Devuelve el código de error de la última llamada de conexión
- mysqli_connect_error() - Devuelve una descripción del último error de conexión
- mysqli_error() - Devuelve un string que describe el último error
- mysqli_sqlstate() - Devuelve el error SQLSTATE de la última operación MySQL

# mysqli::$error

# mysqli_error

(PHP 5, PHP 7, PHP 8)

mysqli::$error -- mysqli_error — Devuelve un string que describe el último error

### Descripción

Estilo orientado a objetos

string $mysqli->error;

Estilo procedimental

function mysqli_error(mysqli `$mysql`): string

Devuelve el string que describe el error ocurrido durante la última llamada a una función MySQLi, ya sea que dicha llamada haya tenido éxito o haya fallado.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

Un string que describe el error. Un string vacío si no ha ocurrido ningún error.

### Ejemplos

Ejemplo #1 Ejemplo con $mysqli->error

Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verificación de la conexión */
    if ($mysqli->connect_errno) {
        printf("Fallo en la conexión: %s\n", $mysqli->connect_error);
        exit();
    }

    if (!$mysqli->query("SET a=1")) {
        printf("Mensaje de error: %s\n", $mysqli->error);
    }

    /* Cierre de la conexión */
    $mysqli->close();
    ?>

Estilo procedimental

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verificación de la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    if (!mysqli_query($link, "SET a=1")) {
        printf("Mensaje de error: %s\n", mysqli_error($link));
    }

    /* Cierre de la conexión */
    mysqli_close($link);
    ?>

Los ejemplos anteriores mostrarán:

    Mensaje de error: Unknown system variable 'a'

### Ver también

- mysqli_connect_errno() - Devuelve el código de error de la última llamada de conexión
- mysqli_connect_error() - Devuelve una descripción del último error de conexión
- mysqli_errno() - Devuelve el último código de error producido
- mysqli_sqlstate() - Devuelve el error SQLSTATE de la última operación MySQL

# mysqli::$error_list

# mysqli_error_list

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

mysqli::$error_list -- mysqli_error_list — Devuelve una lista de errores desde el último comando ejecutado

### Descripción

Estilo orientado a objetos

array $mysqli->error_list;

Estilo procedimental

function mysqli_error_list(mysqli `$mysql`): array

Devuelve un array de errores desde la llamada más reciente a una función MySQLi, ya sea que haya tenido éxito o no.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

Una lista de errores, cada uno en forma de un array asociativo que contiene el número de error (errno), el mensaje de error (error) y el estado SQL (sqlstate).

### Ejemplos

Ejemplo #1 Ejemplo con $mysqli->error_list

Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "nobody", "");

    /* Verifica la conexión */
    if (mysqli_connect_errno()) {
        printf("La conexión ha fallado: %s\n", mysqli_connect_error());
        exit();
    }

    if (!$mysqli->query("SET a=1")) {
        print_r($mysqli->error_list);
    }

    /* Cierra la conexión */
    $mysqli->close();
    ?>

Estilo procedimental

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verifica la conexión */
    if (mysqli_connect_errno()) {
        printf("La conexión ha fallado: %s\n", mysqli_connect_error());
        exit();
    }

    if (!mysqli_query($link, "SET a=1")) {
        print_r(mysqli_error_list($link));
    }

    /* Cierra la conexión */
    mysqli_close($link);
    ?>

Los ejemplos anteriores mostrarán:

    Array
    (
        [0] => Array
            (
                [errno] => 1193
                [sqlstate] => HY000
                [error] => Unknown system variable 'a'
            )

    )

### Ver también

- mysqli_connect_errno() - Devuelve el código de error de la última llamada de conexión
- mysqli_connect_error() - Devuelve una descripción del último error de conexión
- mysqli_error() - Devuelve un string que describe el último error
- mysqli_sqlstate() - Devuelve el error SQLSTATE de la última operación MySQL

# mysqli::execute_query

# mysqli_execute_query

(PHP 8 >= 8.2.0)

mysqli::execute_query -- mysqli_execute_query — Prepara, vincula los parámetros y ejecuta una sentencia SQL

### Descripción

Estilo orientado a objetos

public function mysqli::execute_query(string `$query`, ?array `$params` = `null`): mysqli_result|bool

Estilo procedimental

function mysqli_execute_query(mysqli `$mysql`, string `$query`, ?array `$params` = `null`): mysqli_result|bool

Prepara la consulta SQL, vincula los parámetros y la ejecuta. El método mysqli::execute_query() es un atajo para mysqli::prepare(), mysqli_stmt::bind_param(), mysqli_stmt::execute(), y mysqli_stmt::get_result().

El modelo de sentencia puede contener cero o más marcadores de parámetros (`?`) también llamados espacios reservados. Los valores de los parámetros deben ser proporcionados como un array utilizando el parámetro `params`.

Una sentencia preparada es creada internamente, pero nunca es expuesta fuera de la función. Es imposible acceder a las propiedades de la sentencia como se haría con el objeto mysqli_stmt. Debido a esta limitación, la información de estado es copiada al objeto mysqli y está disponible utilizando sus métodos, por ejemplo mysqli_affected_rows() o mysqli_error().

> Nota:

> En el caso en que una sentencia es pasada a mysqli_execute_query() que es más larga que `max_allowed_packet` del servidor, los códigos de error devueltos son diferentes dependiendo del sistema operativo. El comportamiento es el siguiente:

> - En Linux devuelve un código de error 1153. El mensaje de error significa recepción de un paquete más grande que `max_allowed_packet` bytes (got a packet bigger than `max_allowed_packet` bytes).

> - En Windows devuelve un código de error 2006. Este mensaje de error significa el servidor ha desaparecido (server has gone away).

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()
`query`

  La consulta, en forma de string. Debe consistir en una sola sentencia SQL.

  La sentencia SQL puede contener cero o más marcadores de parámetros representados por un signo de interrogación (`?`) en las posiciones apropiadas.

  > Nota:

  > Los marcadores de parámetros solo están permitidos en ciertos lugares de las sentencias SQL. Por ejemplo, están permitidos en la lista `VALUES()` de una sentencia `INSERT` (para especificar los valores de columnas para una fila), o en una comparación con una columna en una cláusula `WHERE` para especificar un valor de comparación. Sin embargo, no están permitidos para los identificadores (como nombres de tabla o columna).

`params`

  Una lista opcional con tantos elementos como parámetros vinculados en la sentencia SQL que se está ejecutando. Cada valor es tratado como un string.

### Valores devueltos

Devuelve `false` en caso de fallo. Para consultas exitosas que producen un conjunto de resultados, como `SELECT, SHOW, DESCRIBE` o `EXPLAIN`, devuelve un objeto mysqli_result. Para otras consultas exitosas, devuelve `true`.

### Ejemplos

Ejemplo #1 Ejemplo de mysqli::execute_query()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

    $query = 'SELECT Name, District FROM City WHERE CountryCode=? ORDER BY Name LIMIT 5';
    $result = $mysqli->execute_query($query, ['DEU']);
    foreach ($result as $row) {
        printf("%s (%s)\n", $row["Name"], $row["District"]);
    }

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = 'SELECT Name, District FROM City WHERE CountryCode=? ORDER BY Name LIMIT 5';
    $result = mysqli_execute_query($link, $query, ['DEU']);
    foreach ($result as $row) {
        printf("%s (%s)\n", $row["Name"], $row["District"]);
    }

Los ejemplos anteriores mostrarán algo similar a:

    Aachen (Nordrhein-Westfalen)
    Augsburg (Baijeri)
    Bergisch Gladbach (Nordrhein-Westfalen)
    Berlin (Berliini)
    Bielefeld (Nordrhein-Westfalen)

### Ver también

- mysqli_prepare() - Prepara una consulta SQL para su ejecución
- mysqli_stmt_execute() - Ejecuta una consulta preparada
- mysqli_stmt_bind_param() - Vincula variables a una consulta MySQL
- mysqli_stmt_get_result() - Obtiene un conjunto de resultados desde una consulta preparada como un objeto mysqli_result

# mysqli::$field_count

# mysqli_field_count

(PHP 5, PHP 7, PHP 8)

mysqli::$field_count -- mysqli_field_count — Devuelve el número de columnas para la última consulta

### Descripción

Estilo orientado a objetos

int $mysqli->field_count;

Estilo procedimental

function mysqli_field_count(mysqli `$mysql`): int

Devuelve el número de columnas para la última consulta en la conexión especificada por el parámetro `mysql`. Esta función puede ser útil al utilizar mysqli_store_result() para determinar si la consulta debería haber devuelto un resultado vacío o no, sin conocer su naturaleza.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

Un entero que representa el número de campos en un conjunto de resultados.

### Ejemplos

Ejemplo #1 Ejemplo con $mysqli->field_count

Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    $mysqli->query( "DROP TABLE IF EXISTS friends");
    $mysqli->query( "CREATE TABLE friends (id int, name varchar(20))");

    $mysqli->query( "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

    $mysqli->real_query("SELECT * FROM friends");

    if ($mysqli->field_count) {
        /* Una consulta SELECT, SHOW o DESCRIBE */
        $result = $mysqli->store_result();

        /* Obtención del conjunto de resultados */
        $row = $result->fetch_row();

        /* Liberación del conjunto de resultados */
        $result->close();
    }

    /* Cierre de la conexión */
    $mysqli->close();
    ?>

Estilo procedimental

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "test");

    mysqli_query($link, "DROP TABLE IF EXISTS friends");
    mysqli_query($link, "CREATE TABLE friends (id int, name varchar(20))");

    mysqli_query($link, "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

    mysqli_real_query($link, "SELECT * FROM friends");

    if (mysqli_field_count($link)) {
        /* Una consulta SELECT, SHOW o DESCRIBE */
        $result = mysqli_store_result($link);

        /* Obtención del conjunto de resultados */
        $row = mysqli_fetch_row($result);

        /* Liberación del conjunto de resultados */
        mysqli_free_result($result);
    }

    /* Cierre de la conexión */
    mysqli_close($link);
    ?>

# mysqli::get_charset

# mysqli_get_charset

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

mysqli::get_charset -- mysqli_get_charset — Devuelve un objeto que representa el juego de caracteres

### Descripción

Estilo orientado a objetos

public function mysqli::get_charset(): ?object

Estilo procedimental

function mysqli_get_charset(mysqli `$mysql`): ?object

Devuelve un objeto que representa el juego de caracteres, proporcionando diferentes propiedades del juego de caracteres actual.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

La función devuelve un juego de caracteres con las siguientes propiedades:

`charset`

  Nombre del juego de caracteres

`collation`

  Nombre de la interclasificación

`dir`

  El directorio en el que se busca la descripción del juego de caracteres o "" para los juegos de caracteres internos

`min_length`

  Longitud mínima de caracteres, en bytes

`max_length`

  Longitud máxima de caracteres, en bytes

`number`

  Número del juego de caracteres interno

`state`

  A partir de PHP 8.2.0, es siempre `1`

### Ejemplos

Ejemplo #1 Ejemplo con mysqli::get_charset()

Estilo orientado a objetos

    <?php
      $db = mysqli_init();
      $db->real_connect("localhost","root","","test");
      $db->set_charset('latin1');
      var_dump($db->get_charset());
    ?>

Estilo procedimental

    <?php
      $db = mysqli_init();
      mysqli_real_connect($db, "localhost","root","","test");
      mysqli_set_charset($db, 'latin1');
      var_dump(mysqli_get_charset($db));
    ?>

Los ejemplos anteriores mostrarán:

    object(stdClass)#2 (7) {
      ["charset"]=>
      string(6) "latin1"
      ["collation"]=>
      string(17) "latin1_swedish_ci"
      ["dir"]=>
      string(0) ""
      ["min_length"]=>
      int(1)
      ["max_length"]=>
      int(1)
      ["number"]=>
      int(8)
      ["state"]=>
      int(1)
    }

### Ver también

- mysqli_character_set_name() - Devuelve el juego de caracteres actual para la conexión
- mysqli_set_charset() - Define el juego de caracteres del cliente

# mysqli::$client_info

# mysqli::get_client_info

# mysqli_get_client_info

(PHP 5, PHP 7, PHP 8)

mysqli::$client_info -- mysqli::get_client_info -- mysqli_get_client_info — Obtiene información sobre el cliente MySQL

### Descripción

Estilo orientado a objetos

string $mysqli->client_info;
#[\Deprecated]
public function mysqli::get_client_info(): string

Estilo procedimental

function mysqli_get_client_info(?mysqli `$mysql` = null): string

Devuelve un string que representa la versión de la biblioteca cliente MySQL.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un string que representa la versión del cliente utilizado por la extensión MySQL.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | La llamada a la mysqli_get_client_info() con el argumento `mysql` ha sido deprecada. Esta función nunca ha requerido un parámetro, pero lo ha permitido de manera incorrecta como parámetro opcional.
8.1.0 | El estilo orientado a objetos mysqli::get_client_info() ha sido deprecado.

### Ejemplos

Ejemplo #1 Ejemplo con mysqli_get_client_info()

    <?php

    /* No es necesaria una conexión para determinar
        la versión del cliente utilizada por la extensión MySQL */

    printf("Versión de la biblioteca cliente: %s\n", mysqli_get_client_info());
    ?>

### Ver también

- mysqli_get_client_version() - Devuelve la versión del cliente MySQL como un entero
- mysqli_get_server_info() - Devuelve la versión del servidor MySQL
- mysqli_get_server_version() - Devuelve un integer que representa la versión del servidor MySQL

# mysqli::$client_version

# mysqli_get_client_version

(PHP 5, PHP 7, PHP 8)

mysqli::$client_version -- mysqli_get_client_version — Devuelve la versión del cliente MySQL como un entero

### Descripción

Estilo orientado a objetos

int $mysqli->client_version;

Estilo procedimental

function mysqli_get_client_version(): int

Devuelve la versión del cliente MySQL como un entero.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un número que representa la versión de la biblioteca cliente MySQL en este formato: `versión_principal*10000 + versión_menor *100 + subversión`. Por ejemplo, la versión 4.1.0 se devuelve como 40100.

Esta función es útil para determinar la versión de la biblioteca cliente para saber si existen características específicas.

### Ejemplos

Ejemplo #1 Ejemplo con mysqli_get_client_version()

    <?php

    /* No necesitamos una conexión para
       determinar la versión de la biblioteca cliente mysql */

    printf("Versión de la biblioteca cliente: %d\n", mysqli_get_client_version());
    ?>

### Ver también

- mysqli_get_client_info() - Obtiene información sobre el cliente MySQL
- mysqli_get_server_info() - Devuelve la versión del servidor MySQL
- mysqli_get_server_version() - Devuelve un integer que representa la versión del servidor MySQL

# mysqli::get_connection_stats

# mysqli_get_connection_stats

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::get_connection_stats -- mysqli_get_connection_stats — Devuelve estadísticas sobre la conexión

### Descripción

Estilo orientado a objetos

public function mysqli::get_connection_stats(): array

Estilo procedimental

function mysqli_get_connection_stats(mysqli `$mysql`): array

Devuelve estadísticas sobre la conexión del cliente.

> Nota:

> Disponible solo con mysqlnd.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

Devuelve un array con las estadísticas de conexión.

### Ejemplos

Ejemplo #1 Ejemplo con mysqli_get_connection_stats()

    <?php
    $link = mysqli_connect();
    print_r(mysqli_get_connection_stats($link));
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [bytes_sent] => 43
        [bytes_received] => 80
        [packets_sent] => 1
        [packets_received] => 2
        [protocol_overhead_in] => 8
        [protocol_overhead_out] => 4
        [bytes_received_ok_packet] => 11
        [bytes_received_eof_packet] => 0
        [bytes_received_rset_header_packet] => 0
        [bytes_received_rset_field_meta_packet] => 0
        [bytes_received_rset_row_packet] => 0
        [bytes_received_prepare_response_packet] => 0
        [bytes_received_change_user_packet] => 0
        [packets_sent_command] => 0
        [packets_received_ok] => 1
        [packets_received_eof] => 0
        [packets_received_rset_header] => 0
        [packets_received_rset_field_meta] => 0
        [packets_received_rset_row] => 0
        [packets_received_prepare_response] => 0
        [packets_received_change_user] => 0
        [result_set_queries] => 0
        [non_result_set_queries] => 0
        [no_index_used] => 0
        [bad_index_used] => 0
        [slow_queries] => 0
        [buffered_sets] => 0
        [unbuffered_sets] => 0
        [ps_buffered_sets] => 0
        [ps_unbuffered_sets] => 0
        [flushed_normal_sets] => 0
        [flushed_ps_sets] => 0
        [ps_prepared_never_executed] => 0
        [ps_prepared_once_executed] => 0
        [rows_fetched_from_server_normal] => 0
        [rows_fetched_from_server_ps] => 0
        [rows_buffered_from_client_normal] => 0
        [rows_buffered_from_client_ps] => 0
        [rows_fetched_from_client_normal_buffered] => 0
        [rows_fetched_from_client_normal_unbuffered] => 0
        [rows_fetched_from_client_ps_buffered] => 0
        [rows_fetched_from_client_ps_unbuffered] => 0
        [rows_fetched_from_client_ps_cursor] => 0
        [rows_skipped_normal] => 0
        [rows_skipped_ps] => 0
        [copy_on_write_saved] => 0
        [copy_on_write_performed] => 0
        [command_buffer_too_small] => 0
        [connect_success] => 1
        [connect_failure] => 0
        [connection_reused] => 0
        [reconnect] => 0
        [pconnect_success] => 0
        [active_connections] => 1
        [active_persistent_connections] => 0
        [explicit_close] => 0
        [implicit_close] => 0
        [disconnect_close] => 0
        [in_middle_of_command_close] => 0
        [explicit_free_result] => 0
        [implicit_free_result] => 0
        [explicit_stmt_close] => 0
        [implicit_stmt_close] => 0
        [mem_emalloc_count] => 0
        [mem_emalloc_ammount] => 0
        [mem_ecalloc_count] => 0
        [mem_ecalloc_ammount] => 0
        [mem_erealloc_count] => 0
        [mem_erealloc_ammount] => 0
        [mem_efree_count] => 0
        [mem_malloc_count] => 0
        [mem_malloc_ammount] => 0
        [mem_calloc_count] => 0
        [mem_calloc_ammount] => 0
        [mem_realloc_count] => 0
        [mem_realloc_ammount] => 0
        [mem_free_count] => 0
        [proto_text_fetched_null] => 0
        [proto_text_fetched_bit] => 0
        [proto_text_fetched_tinyint] => 0
        [proto_text_fetched_short] => 0
        [proto_text_fetched_int24] => 0
        [proto_text_fetched_int] => 0
        [proto_text_fetched_bigint] => 0
        [proto_text_fetched_decimal] => 0
        [proto_text_fetched_float] => 0
        [proto_text_fetched_double] => 0
        [proto_text_fetched_date] => 0
        [proto_text_fetched_year] => 0
        [proto_text_fetched_time] => 0
        [proto_text_fetched_datetime] => 0
        [proto_text_fetched_timestamp] => 0
        [proto_text_fetched_string] => 0
        [proto_text_fetched_blob] => 0
        [proto_text_fetched_enum] => 0
        [proto_text_fetched_set] => 0
        [proto_text_fetched_geometry] => 0
        [proto_text_fetched_other] => 0
        [proto_binary_fetched_null] => 0
        [proto_binary_fetched_bit] => 0
        [proto_binary_fetched_tinyint] => 0
        [proto_binary_fetched_short] => 0
        [proto_binary_fetched_int24] => 0
        [proto_binary_fetched_int] => 0
        [proto_binary_fetched_bigint] => 0
        [proto_binary_fetched_decimal] => 0
        [proto_binary_fetched_float] => 0
        [proto_binary_fetched_double] => 0
        [proto_binary_fetched_date] => 0
        [proto_binary_fetched_year] => 0
        [proto_binary_fetched_time] => 0
        [proto_binary_fetched_datetime] => 0
        [proto_binary_fetched_timestamp] => 0
        [proto_binary_fetched_string] => 0
        [proto_binary_fetched_blob] => 0
        [proto_binary_fetched_enum] => 0
        [proto_binary_fetched_set] => 0
        [proto_binary_fetched_geometry] => 0
        [proto_binary_fetched_other] => 0
    )

### Ver también

- Descripción de las estadísticas

# mysqli::$host_info

# mysqli_get_host_info

(PHP 5, PHP 7, PHP 8)

mysqli::$host_info -- mysqli_get_host_info — Devuelve un string que contiene el tipo de conexión utilizada

### Descripción

Estilo orientado a objetos

string $mysqli->host_info;

Estilo procedimental

function mysqli_get_host_info(mysqli `$mysql`): string

mysqli_get_host_info() devuelve un string de caracteres que describe la conexión representada por el argumento `mysql` (incluyendo el nombre de host del servidor).

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

Un string que representa el nombre de host del servidor y el tipo de conexión.

### Ejemplos

Ejemplo #1 Ejemplo con $mysqli->host_info

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Muestra información sobre el host */
    printf("Información sobre el host: %s\n", $mysqli->host_info);

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Muestra información sobre el host */
    printf("Información sobre el host: %s\n", mysqli_get_host_info($link));

Los ejemplos anteriores mostrarán:

    Información sobre el host: Localhost via UNIX socket

### Ver también

- mysqli_get_proto_info() - Devuelve la versión del protocolo MySQL utilizado

# mysqli::$protocol_version

# mysqli_get_proto_info

(PHP 5, PHP 7, PHP 8)

mysqli::$protocol_version -- mysqli_get_proto_info — Devuelve la versión del protocolo MySQL utilizado

### Descripción

Estilo orientado a objetos

string $mysqli->protocol_version;

Estilo procedimental

function mysqli_get_proto_info(mysqli `$mysql`): int

Devuelve un integer que representa la versión del protocolo MySQL utilizado por la conexión representada por el argumento `mysql`.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

Devuelve un integer que representa la versión del protocolo.

### Ejemplos

Ejemplo #1 Ejemplo con $mysqli->protocol_version

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password");

    /* Muestra la versión del protocolo */
    printf("Versión del protocolo: %d\n", $mysqli->protocol_version);

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password");

    /* Muestra la versión del protocolo */
    printf("Versión del protocolo: %d\n", mysqli_get_proto_info($link));

Los ejemplos anteriores mostrarán:

    Versión del protocolo: 10

### Ver también

- mysqli_get_host_info() - Devuelve un string que contiene el tipo de conexión utilizada

# mysqli::$server_info

# mysqli::get_server_info

# mysqli_get_server_info

(PHP 5, PHP 7, PHP 8)

mysqli::$server_info -- mysqli::get_server_info -- mysqli_get_server_info — Devuelve la versión del servidor MySQL

### Descripción

Estilo orientado a objetos

string $mysqli->server_info;
public function mysqli::get_server_info(): string

Estilo procedimental

function mysqli_get_server_info(mysqli `$mysql`): string

Devuelve un string que representa la versión del servidor MySQL al cual la extensión MySQLi está conectada (representado por el argumento `link`).

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

Un string que representa la versión del servidor.

### Ejemplos

Ejemplo #1 Ejemplo con $mysqli->server_info

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password");

    /* Muestra la versión del servidor */
    printf("Versión del servidor: %s\n", $mysqli->server_info);

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password");

    /* Muestra la versión del servidor */
    printf("Versión del servidor: %s\n", mysqli_get_server_info($link));

Los ejemplos anteriores mostrarán algo similar a:

    Versión del servidor: 8.0.21

### Ver también

- mysqli_get_client_info() - Obtiene información sobre el cliente MySQL
- mysqli_get_client_version() - Devuelve la versión del cliente MySQL como un entero
- mysqli_get_server_version() - Devuelve un integer que representa la versión del servidor MySQL

# mysqli::$server_version

# mysqli_get_server_version

(PHP 5, PHP 7, PHP 8)

mysqli::$server_version -- mysqli_get_server_version — Devuelve un integer que representa la versión del servidor MySQL

### Descripción

Estilo orientado a objetos

int $mysqli->server_version;

Estilo procedimental

function mysqli_get_server_version(mysqli `$mysql`): int

La función mysqli_get_server_version() devuelve un integer que representa la versión del servidor al que se está conectado (representado por el argumento `mysql`).

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

Un integer que representa la versión del servidor.

El formato de este número es `main_version * 10000 + minor_version * 100 + sub_version` (es decir, la versión 4.1.0 devolverá 40100).

### Ejemplos

Ejemplo #1 Ejemplo con $mysqli->server_version

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password");

    /* Muestra la versión del servidor */
    printf("Versión del servidor: %d\n", $mysqli->server_version);

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password");

    /* Muestra la versión del servidor */
    printf("Versión del servidor: %d\n", mysqli_get_server_version($link));

Los ejemplos anteriores mostrarán algo similar a:

    Versión del servidor: 80021

### Ver también

- mysqli_get_client_info() - Obtiene información sobre el cliente MySQL
- mysqli_get_client_version() - Devuelve la versión del cliente MySQL como un entero
- mysqli_get_server_info() - Devuelve la versión del servidor MySQL

# mysqli::get_warnings

# mysqli_get_warnings

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

mysqli::get_warnings -- mysqli_get_warnings — Lee el resultado de `SHOW WARNINGS`

### Descripción

Estilo orientado a objetos

public function mysqli::get_warnings(): mysqli_warning|false

Estilo procedimental

function mysqli_get_warnings(mysqli `$mysql`): mysqli_warning|false

Devuelve una lista simplemente enlazada compuesta de mysqli_warning o `false` si no hay advertencias. Cada objeto de la lista corresponde a una línea única del resultado de `SHOW WARNINGS`. Llamar a mysqli_warning::next() rellenará el objeto con los valores de la línea siguiente.

> Nota: Para recuperar los mensajes de advertencia, se recomienda utilizar el comando SQL `SHOW WARNINGS [LIMIT row_count]` en lugar de esta función.

Advertencia

La lista enlazada no puede ser reinicializada ni recuperada nuevamente.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

Devuelve una lista simplemente enlazada compuesta de mysqli_warning o `false` si no hay advertencias.

### Ejemplos

Ejemplo #1 Recorrer la lista enlazada para recuperar todas las advertencias

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("SELECT 1/0, CAST('NULL' AS UNSIGNED)");

    if ($mysqli->warning_count > 0) {
        $warning = $mysqli->get_warnings();
        if ($warning !== false) {
            do {
                printf("Número de error: %s\n", $warning->errno);
                printf("Mensaje: %s\n", $warning->message);
            } while ($warning->next());
        }
    }

Los ejemplos anteriores mostrarán:

    Número de error: 1365
    Mensaje: División por 0
    Número de error: 1292
    Mensaje: Valor INTEGER incorrecto truncado: 'NULL'

# mysqli::$info

# mysqli_info

(PHP 5, PHP 7, PHP 8)

mysqli::$info -- mysqli_info — Devuelve información acerca de la última consulta ejecutada

### Descripción

Estilo orientado a objetos

?string $mysqli->info;

Estilo procedimental

function mysqli_info(mysqli `$mysql`): ?string

La función mysqli_info() devuelve un string que proporciona información acerca de la última consulta ejecutada. La naturaleza de este string se detalla a continuación:

Valores de retorno posibles para mysqli_info()
Tipo de consulta | Ejemplo de retorno
--- | ---
INSERT INTO...SELECT... | Records: 100 Duplicates: 0 Warnings: 0
INSERT INTO...VALUES (...),(...),(...) | Records: 3 Duplicates: 0 Warnings: 0
LOAD DATA INFILE ... | Records: 1 Deleted: 0 Skipped: 0 Warnings: 0
ALTER TABLE ... | Records: 3 Duplicates: 0 Warnings: 0
UPDATE ... | Rows matched: 40 Changed: 40 Warnings: 0

> Nota:

> Las consultas que no forman parte de la lista anterior no están soportadas. En esta situación, mysqli_info() devolverá un string vacío.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

Un string que proporciona información adicional acerca de la última consulta ejecutada.

### Ejemplos

Ejemplo #1 Ejemplo con $mysqli->info

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("CREATE TEMPORARY TABLE t1 LIKE City");

    /* INSERT INTO ... SELECT */
    $mysqli->query("INSERT INTO t1 SELECT * FROM City ORDER BY ID LIMIT 150");
    printf("%s\n", $mysqli->info);

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    mysqli_query($link, "CREATE TEMPORARY TABLE t1 LIKE City");

    /* INSERT INTO ... SELECT */
    mysqli_query($link, "INSERT INTO t1 SELECT * FROM City ORDER BY ID LIMIT 150");
    printf("%s\n", mysqli_info($link));

Los ejemplos anteriores mostrarán:

    Records: 150  Duplicates: 0  Warnings: 0

### Ver también

- mysqli_affected_rows() - Devuelve el número de filas afectadas por la última operación MySQL
- mysqli_warning_count() - Devuelve el número de advertencias generadas por la última consulta ejecutada
- mysqli_num_rows() - Devuelve el número de filas en el conjunto de resultados

# mysqli::init

# mysqli_init

(PHP 5, PHP 7, PHP 8)

mysqli::init -- mysqli_init — Inicializa MySQLi y devuelve un objeto para usar con mysqli_real_connect()

### Descripción

Estilo orientado a objetos

#[\Deprecated]
public function mysqli::init(): ?bool

Estilo procedimental

function mysqli_init(): mysqli|false

Asigna o inicializa un objeto MySQL utilizable para las funciones mysqli_options() y mysqli_real_connect().

> Nota:

> Todas las llamadas siguientes a cualquier función MySQLi (excepto mysqli_options() y mysqli_ssl_set()) fallarán hasta que la función mysqli_real_connect() sea llamada.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

mysqli::init() devuelve `null` en caso de éxito, o `false` si ocurre un error. mysqli_init() devuelve un objeto en caso de éxito, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El método mysqli::init() de estilo orientado a objetos ha sido deprecado. Reemplace las llamadas a parent::init() por parent::__construct().

### Ejemplos

Ver mysqli_real_connect().

### Ver también

- mysqli_options() - Define las opciones
- mysqli_close() - Cierra una conexión
- mysqli_real_connect() - Establece una conexión con un servidor MySQL
- mysqli_connect() - Alias de mysqli::__construct

# mysqli::$insert_id

# mysqli_insert_id

(PHP 5, PHP 7, PHP 8)

mysqli::$insert_id -- mysqli_insert_id — Devuelve el valor generado para una columna AUTO_INCREMENT por la última consulta

### Descripción

Estilo orientado a objetos

int|string $mysqli->insert_id;

Estilo procedimental

function mysqli_insert_id(mysqli `$mysql`): int|string

Devuelve el ID generado por una consulta `INSERT` o `UPDATE` en una tabla con una columna que tiene el atributo `AUTO_INCREMENT`. En el caso de consultas multilínea `INSERT`, esto devuelve el primer valor generado automáticamente que fue insertado con éxito.

Ejecutar una consulta `INSERT` o `UPDATE` utilizando la función MySQL `LAST_INSERT_ID()` modificará también el valor devuelto por mysqli_insert_id(). Si `LAST_INSERT_ID(expr)` se ha utilizado para generar el valor de `AUTO_INCREMENT`, esto devuelve el valor de la última `expr` en lugar del valor generado de `AUTO_INCREMENT`.

Devuelve `0` si la consulta anterior no ha cambiado el valor de `AUTO_INCREMENT`. mysqli_insert_id() debe ser llamado inmediatamente después de que la consulta haya generado el valor.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

El valor del campo `AUTO_INCREMENT` modificado por la última consulta. Devuelve cero si no ha habido consulta en la conexión o si la última consulta no ha modificado el valor del `AUTO_INCREMENT`.

Solo las consultas emitidas por la conexión actual afectan el valor de retorno. El valor no se ve afectado por las consultas que utilizan otras conexiones o clientes.

> Nota:

> Si el número es mayor que el valor máximo de un integer, será devuelto como un string

### Ejemplos

Ejemplo #1 Ejemplo con $mysqli->insert_id

Estilo orientado a objetos

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("CREATE TABLE myCity LIKE City");

    $query = "INSERT INTO myCity VALUES (NULL, 'Stuttgart', 'DEU', 'Stuttgart', 617000)";
    $mysqli->query($query);

    printf("El nuevo registro tiene ID %d.\n", $mysqli->insert_id);

    /* eliminar tabla */
    $mysqli->query("DROP TABLE myCity");
    ?>

Estilo procedimental

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    mysqli_query($link, "CREATE TABLE myCity LIKE City");

    $query = "INSERT INTO myCity VALUES (NULL, 'Stuttgart', 'DEU', 'Stuttgart', 617000)";
    mysqli_query($link, $query);

    printf("El nuevo registro tiene ID %d.\n", mysqli_insert_id($link));

    /* eliminar tabla */
    mysqli_query($link, "DROP TABLE myCity");
    ?>

Los ejemplos anteriores mostrarán:

    El nuevo registro tiene ID 1.

# mysqli::kill

# mysqli_kill

(PHP 5, PHP 7, PHP 8)

mysqli::kill -- mysqli_kill — Solicita al servidor que finalice un hilo MySQL

Advertencia

Esta función está OBSOLETA a partir de PHP 8.4.0. Depender de esta función está altamente desaconsejado.

### Descripción

Estilo orientado a objetos

#[\Deprecated]
public function mysqli::kill(int `$process_id`): bool

Estilo procedimental

#[\Deprecated]
function mysqli_kill(mysqli `$mysql`, int `$process_id`): bool

mysqli_kill() se utiliza para solicitar al servidor que finalice un hilo MySQL especificado por el argumento `process_id`. Este valor debe obtenerse llamando a la función mysqli_thread_id().

Para detener una consulta en ejecución, se debe utilizar el comando SQL `KILL QUERY process_id`.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Los métodos mysqli::kill() y mysqli_kill() están ahora obsoletos. Se recomienda utilizar el comando SQL `KILL`.

### Ejemplos

Ejemplo #1 Ejemplo con mysqli::kill()

Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verificación de la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    /* Determina el id del hilo */
    $thread_id = $mysqli->thread_id;

    /* Finaliza el hilo */
    $mysqli->kill($thread_id);

    /* Esto debería producir un error */
    if (!$mysqli->query("CREATE TABLE myCity LIKE City")) {
        printf("Error: %s\n", $mysqli->error);
        exit;
    }

    /* Cierre de la conexión */
    $mysqli->close();
    ?>

Estilo procedimental

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verificación de la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    /* Determina el id del hilo */
    $thread_id = mysqli_thread_id($link);

    /* Finaliza el hilo */
    mysqli_kill($link, $thread_id);

    /* Esto debería producir un error */
    if (!mysqli_query($link, "CREATE TABLE myCity LIKE City")) {
        printf("Error: %s\n", mysqli_error($link));
        exit;
    }

    /* Cierre de la conexión */
    mysqli_close($link);
    ?>

Los ejemplos anteriores mostrarán:

    Error: MySQL server has gone away

### Ver también

- mysqli_thread_id() - Devuelve el identificador del hilo para la conexión actual

# mysqli::more_results

# mysqli_more_results

(PHP 5, PHP 7, PHP 8)

mysqli::more_results -- mysqli_more_results — Comprueba si hay más conjuntos de resultados MySQL disponibles

### Descripción

Estilo orientado a objetos

public function mysqli::more_results(): bool

Estilo procedimental

function mysqli_more_results(mysqli `$mysql`): bool

Indica si uno o más conjuntos de resultados están disponibles, generados por una llamada anterior a mysqli_multi_query().

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

Devuelve `true` si uno o más conjuntos de resultados (incluyendo errores) están disponibles a partir de una llamada previa a la función mysqli_multi_query(), `false` en caso contrario.

### Ejemplos

Ver mysqli_multi_query().

### Ver también

- mysqli_multi_query() - Ejecuta una o varias consultas en la base de datos
- mysqli_next_result() - Prepara el siguiente resultado de una consulta múltiple
- mysqli_store_result() - Transfiere un conjunto de resultados desde la última consulta
- mysqli_use_result() - Inicializa la recuperación de un conjunto de resultados

# mysqli::multi_query

# mysqli_multi_query

(PHP 5, PHP 7, PHP 8)

mysqli::multi_query -- mysqli_multi_query — Ejecuta una o varias consultas en la base de datos

### Descripción

Estilo orientado a objetos

public function mysqli::multi_query(string `$query`): bool

Estilo procedimental

function mysqli_multi_query(mysqli `$mysql`, string `$query`): bool

Ejecuta una o varias consultas, agrupadas en el parámetro `query` mediante puntos y comas.

Advertencia

# Advertencia de seguridad: Inyección SQL

Si la consulta contiene alguna entrada de variable, entonces se deben usar sentencias preparadas parametrizadas en su lugar. Alternativamente, los datos deben estar correctamente formateados y todas las cadenas deben ser escapadas usando la función mysqli_real_escape_string().

Las consultas se envían en una sola llamada a la base de datos y se procesan de manera secuencial. mysqli_multi_query() espera a que la primera consulta se complete antes de devolver el control a PHP. Mientras tanto, el servidor MySQL continuará procesando las consultas restantes de manera asíncrona respecto a PHP y pondrá los resultados a disposición para su recuperación.

Se recomienda utilizar una do-while para procesar varias consultas. La conexión estará ocupada hasta que todas las consultas se completen y sus resultados sean recuperados por PHP. Ninguna otra consulta puede ser emitida en la misma conexión, hasta que todas las consultas sean procesadas. Para procesar la siguiente consulta en la secuencia, utilizar mysqli_next_result(). Si el siguiente resultado no está aún listo, mysqli esperará la respuesta desde el servidor MySQL. Para verificar si hay más resultados, utilizar mysqli_more_results().

Para las consultas que producen un conjunto de resultados, como `SELECT, SHOW, DESCRIBE` o `EXPLAIN`, mysqli_use_result() o mysqli_store_result() pueden ser utilizados para recuperar el conjunto de resultados. Para las consultas que no producen un conjunto de resultados, las mismas funciones pueden ser utilizadas para recuperar información como el número de filas afectadas.

Sugerencia

Ejecutar una consulta `CALL` para procedimientos almacenados puede producir varios conjuntos de resultados. Si el procedimiento almacenado contiene consultas `SELECT`, los conjuntos de resultados son devueltos en el orden en que son producidos por la ejecución del procedimiento. En general, el llamador no puede saber cuántos conjuntos de resultados devolverá un procedimiento y debe estar preparado para recuperar varios resultados. El resultado final del procedimiento es un resultado de estado que no incluye un conjunto de resultados. El estado indica si el procedimiento tuvo éxito o si se produjo un error.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()
`query`

  Una string que contiene las consultas a ejecutar. Varias consultas deben estar separadas por un punto y coma.

### Valores devueltos

Devuelve `false` únicamente si la primera consulta falla. Para recuperar las subsecuencias de errores provenientes de otras consultas, se debe llamar primero a la función mysqli_next_result().

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Ejemplos

Ejemplo #1 Ejemplo con mysqli::multi_query()

Estilo orientado a objetos

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT CURRENT_USER();";
    $query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

    /* Ejecución de una consulta múltiple */
    $mysqli->multi_query($query);
    do {
        /* Almacenar el conjunto de resultados en PHP */
        if ($result = $mysqli->store_result()) {
            while ($row = $result->fetch_row()) {
                printf("%s\n", $row[0]);
            }
        }
        /* Imprimir divisor */
        if ($mysqli->more_results()) {
            printf("-----------------\n");
        }
    } while ($mysqli->next_result());
    ?>

Estilo procedimental

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT CURRENT_USER();";
    $query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

    /* Ejecución de una consulta múltiple */
    mysqli_multi_query($link, $query);
    do {
        /* Almacenar el conjunto de resultados en PHP */
        if ($result = mysqli_store_result($link)) {
            while ($row = mysqli_fetch_row($result)) {
                printf("%s\n", $row[0]);
            }
            /* Mostrar una separación */
            if (mysqli_more_results($link)) {
                printf("-----------------\n");
            }
        }
        /* Imprimir divisor */
        if (mysqli_more_results($link)) {
            printf("-----------------\n");
        }
    } while (mysqli_next_result($link));
    ?>

Los ejemplos anteriores mostrarán algo similar a:

    my_user@localhost
    -----------------
    Amersfoort
    Maastricht
    Dordrecht
    Leiden
    Haarlemmermeer

### Ver también

- mysqli_query() - Ejecuta una consulta en la base de datos
- mysqli_use_result() - Inicializa la recuperación de un conjunto de resultados
- mysqli_store_result() - Transfiere un conjunto de resultados desde la última consulta
- mysqli_next_result() - Prepara el siguiente resultado de una consulta múltiple
- mysqli_more_results() - Comprueba si hay más conjuntos de resultados MySQL disponibles

# mysqli::next_result

# mysqli_next_result

(PHP 5, PHP 7, PHP 8)

mysqli::next_result -- mysqli_next_result — Prepara el siguiente resultado de una consulta múltiple

### Descripción

Estilo orientado a objetos

public function mysqli::next_result(): bool

Estilo procedimental

function mysqli_next_result(mysqli `$mysql`): bool

Prepara el siguiente conjunto de resultados, inicializado por una llamada anterior a mysqli_multi_query(), y que puede ser leído por mysqli_store_result() o mysqli_use_result().

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error. Asimismo, devuelve `false` si la siguiente sentencia resulta en un error, a diferencia de mysqli_more_results().

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Ejemplos

Véase mysqli_multi_query().

### Ver también

- mysqli_multi_query() - Ejecuta una o varias consultas en la base de datos
- mysqli_more_results() - Comprueba si hay más conjuntos de resultados MySQL disponibles
- mysqli_store_result() - Transfiere un conjunto de resultados desde la última consulta
- mysqli_use_result() - Inicializa la recuperación de un conjunto de resultados

# mysqli::options

# mysqli_options

(PHP 5, PHP 7, PHP 8)

mysqli::options -- mysqli_options — Define las opciones

### Descripción

Estilo orientado a objetos

public function mysqli::options(int `$option`, string|int `$value`): bool

Estilo procedimental

function mysqli_options(mysqli `$mysql`, int `$option`, string|int `$value`): bool

Útil para definir opciones de conexión y así afectar el comportamiento de la conexión actual.

Esta función puede ser llamada múltiples veces para definir múltiples opciones.

mysqli_options() debe ser llamada después de mysqli_init() y antes de mysqli_real_connect().

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()
`option`

  La opción que se desea definir. Puede tomar uno de los siguientes valores:

  Opciones válidas
  Nombre | Descripción
  --- | ---
  `MYSQLI_OPT_CONNECT_TIMEOUT` | Tiempo máximo de conexión en segundos
  `MYSQLI_OPT_READ_TIMEOUT` | Tiempo de espera de ejecución de un comando en segundos. Disponible a partir de PHP 7.2.0.
  `MYSQLI_OPT_LOCAL_INFILE` | Activa/desactiva el uso de `LOAD LOCAL INFILE`
  `MYSQLI_OPT_LOAD_DATA_LOCAL_DIR` | Directorio a utilizar para `LOAD DATA LOCAL INFILE`.
  `MYSQLI_INIT_COMMAND` | Comando a ejecutar después de la conexión al servidor MySQL
  `MYSQLI_SET_CHARSET_NAME` | El juego de caracteres a definir por defecto.
  `MYSQLI_READ_DEFAULT_FILE` | Lee las opciones desde el nombre de la opción en lugar del archivo my.cnf No soportado por mysqlnd
  `MYSQLI_READ_DEFAULT_GROUP` | Lee las opciones del grupo desde my.cnf o desde el archivo especificado con `MYSQL_READ_DEFAULT_FILE`. No soportado por mysqlnd
  `MYSQLI_SERVER_PUBLIC_KEY` | Archivo que contiene la clave pública RSA utilizada con la autenticación basada en SHA-256.
  `MYSQLI_OPT_NET_CMD_BUFFER_SIZE` | El tamaño del buffer interno de comando/red. Únicamente válido para mysqlnd.
  `MYSQLI_OPT_NET_READ_BUFFER_SIZE` | Tamaño, en bytes, máximo de la parte a leer durante la lectura del cuerpo de un paquete de comando MySQL. Únicamente válido para mysqlnd.
  `MYSQLI_OPT_INT_AND_FLOAT_NATIVE` | Convierte las columnas enteras y de coma flotante en números PHP al utilizar declaraciones no preparadas. Válido únicamente para mysqlnd.
  `MYSQLI_OPT_SSL_VERIFY_SERVER_CERT` | Si se debe verificar o no el certificado del servidor.
  `MYSQLI_OPT_CAN_HANDLE_EXPIRED_PASSWORDS` | Si el cliente debe aceptar contraseñas expiradas.
  `1` | Si se debe utilizar la compresión de comunicación de red.

`value`

  El valor para la opción.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Ejemplos

Ver mysqli_real_connect().

### Notas

> Nota: MySQLnd siempre asume el juego de caracteres predeterminado del servidor. Este juego de caracteres es enviado durante el intercambio de conexión/autenticación, el cual mysqlnd utilizará.Libmysqlclient utiliza el juego de caracteres predeterminado establecido en el my.cnf o mediante una llamada explícita a mysqli_options() antes de llamar a mysqli_real_connect(), pero después de mysqli_init().

### Ver también

- mysqli_init() - Inicializa MySQLi y devuelve un objeto para usar con mysqli_real_connect()
- mysqli_real_connect() - Establece una conexión con un servidor MySQL

# mysqli::ping

# mysqli_ping

(PHP 5, PHP 7, PHP 8)

mysqli::ping -- mysqli_ping — Verifica la conexión al servidor y reconecta si ya no existe

Advertencia

Esta función está OBSOLETA a partir de PHP 8.4.0. Depender de esta función está altamente desaconsejado.

### Descripción

Estilo orientado a objetos

#[\Deprecated]
public function mysqli::ping(): bool

Estilo procedimental

#[\Deprecated]
function mysqli_ping(mysqli `$mysql`): bool

Verifica si la conexión al servidor funciona correctamente. Si ha sido cerrada y la opción global mysqli.reconnect está activada, se intenta una reconexión automática.

> Nota: El parámetro php.ini mysqli.reconnect es ignorado por el controlador mysqlnd, por lo tanto las reconexiones automáticas nunca se intentan.

Esta función puede ser utilizada para que los clientes que permanecen abiertos durante mucho tiempo sin actividad puedan verificar que la conexión no ha sido cerrada por el servidor y, en caso afirmativo, realizar una reconexión automática.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Los métodos mysqli::ping() y mysqli_ping() están ahora obsoletos. La funcionalidad `reconnect` ya no está disponible desde PHP 8.2.0, lo que hace que esta función sea obsoleta.

### Ejemplos

Ejemplo #1 Ejemplo con mysqli::ping()

Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verificación de la conexión */
    if ($mysqli->connect_errno) {
        printf("Conexión fallida: %s\n", $mysqli->connect_error);
        exit();
    }

    /* Verificación si la conexión sigue activa */
    if ($mysqli->ping()) {
        printf ("¡La conexión está bien!\n");
    } else {
        printf ("Error: %s\n", $mysqli->error);
    }

    /* Cierre de la conexión */
    $mysqli->close();
    ?>

Estilo procedimental

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verificación de la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    /* Verificación si la conexión sigue activa */
    if (mysqli_ping($link)) {
        printf ("¡La conexión está bien!\n");
    } else {
        printf ("Error: %s\n", mysqli_error($link));
    }

    /* Cierre de la conexión */
    mysqli_close($link);
    ?>

Los ejemplos anteriores mostrarán:

    ¡La conexión es válida!

# mysqli::poll

# mysqli_poll

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::poll -- mysqli_poll — Verifica el estado de la conexión

### Descripción

Estilo orientado a objetos

public static function mysqli::poll(
?array `&$read`,
?array `&$error`,
array `&$reject`,
int `$seconds`,
int `$microseconds` = 0
): int|false

Estilo procedimental

function mysqli_poll(
?array `&$read`,
?array `&$error`,
array `&$reject`,
int `$seconds`,
int `$microseconds` = 0
): int|false

Verifica el estado de la conexión. El método puede ser utilizado como estático.

> Nota:

> Disponible solo con mysqlnd.

### Parámetros

`read`

  Lista de conexiones para verificar resultados excepcionales que pueden ser leídos.

`error`

  Lista de conexiones en las que se ha producido un error, por ejemplo, fallos en consultas o pérdidas de conexión.

`reject`

  Lista de conexiones rechazadas porque se ejecutaron consultas no asíncronas y para las cuales la función podría devolver resultados.

`seconds`

  Número de segundos de espera máxima, debe ser positivo.

`microseconds`

  Número de microsegundos de espera máxima, debe ser positivo.

### Valores devueltos

Devuelve el número de conexiones disponibles en caso de éxito, `false` en caso contrario.

### Errores/Excepciones

Se lanza una ValueError cuando ni el argumento `read` ni el argumento `error` son transmitidos.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Ahora lanza una excepción ValueError cuando ni el argumento `read` ni el argumento `error` son transmitidos.

### Ejemplos

Ejemplo #1 Ejemplo con mysqli_poll()

    <?php
    $link1 = mysqli_connect();
    $link1->query("SELECT 'test'", MYSQLI_ASYNC);
    $all_links = array($link1);
    $processed = 0;
    do {
        $links = $errors = $reject = array();
        foreach ($all_links as $link) {
            $links[] = $errors[] = $reject[] = $link;
        }
        if (!mysqli_poll($links, $errors, $reject, 1)) {
            continue;
        }
        foreach ($links as $link) {
            if ($result = $link->reap_async_query()) {
                print_r($result->fetch_row());
                if (is_object($result))
                    mysqli_free_result($result);
            } else die(sprintf("Error MySQLi: %s", mysqli_error($link)));
            $processed++;
        }
    } while ($processed < count($all_links));
    ?>

El ejemplo anterior mostrará:

    Array
    (
        [0] => test
    )

### Ver también

- mysqli_query() - Ejecuta una consulta en la base de datos
- mysqli_reap_async_query() - Lee un resultado para una consulta asíncrona

# mysqli::prepare

# mysqli_prepare

(PHP 5, PHP 7, PHP 8)

mysqli::prepare -- mysqli_prepare — Prepara una consulta SQL para su ejecución

### Descripción

Estilo orientado a objetos

public function mysqli::prepare(string `$query`): mysqli_stmt|false

Estilo procedimental

function mysqli_prepare(mysqli `$mysql`, string `$query`): mysqli_stmt|false

Prepara la consulta SQL y devuelve un gestor de consulta para ser utilizado en futuras operaciones con la consulta. La consulta debe constar de una única consulta SQL.

Los parámetros de marcadores deben ser vinculados a variables utilizadas en las funciones mysqli_stmt_bind_param() y/o mysqli_stmt_bind_result() antes de ejecutar la consulta o recuperar las filas.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()
`query`

  La consulta, en forma de string.

  Este parámetro puede incluir uno o más parámetros de marcadores en la consulta SQL con el carácter "signo de interrogación" (`?`) en la posición apropiada.

  > Nota:

  > Los marcadores están permitidos únicamente en ciertos lugares de las consultas SQL. Por ejemplo, están permitidos en la lista `VALUES()` de una consulta `INSERT` (para especificar los valores de las columnas para una fila), o en una comparación de una cláusula `WHERE` para especificar un valor de comparación. Sin embargo, no están permitidos para los identificadores (de tablas o columnas).

### Valores devueltos

mysqli_prepare() devuelve un objeto de sentencia o `false` si ocurre un error.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Ejemplos

Ejemplo #1 Ejemplo con mysqli::prepare()

Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verificación de la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    $city = "Amersfoort";

    /* Crea una consulta preparada */
    if ($stmt = $mysqli->prepare("SELECT District FROM City WHERE Name=?")) {

        /* Vinculación de los marcadores */
        $stmt->bind_param("s", $city);

        /* Ejecución de la consulta */
        $stmt->execute();

        /* Vinculación de las variables resultantes */
        $stmt->bind_result($district);

        /* Obtención de los valores */
        $stmt->fetch();

        printf("%s está en el distrito de %s\n", $city, $district);

        /* Cierre de la sentencia */
        $stmt->close();
    }

    /* Cierre de la conexión */
    $mysqli->close();
    ?>

Estilo procedimental

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verificación de la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    $city = "Amersfoort";

    /* Crea una consulta preparada */
    if ($stmt = mysqli_prepare($link, "SELECT District FROM City WHERE Name=?")) {

        /* Vinculación de los marcadores */
        mysqli_stmt_bind_param($stmt, "s", $city);

        /* Ejecución de la consulta */
        mysqli_stmt_execute($stmt);

        /* Vinculación de las variables resultantes */
        mysqli_stmt_bind_result($stmt, $district);

        /* Obtención de los valores */
        mysqli_stmt_fetch($stmt);

        printf("%s está en el distrito de %s\n", $city, $district);

        /* Cierre de la sentencia */
        mysqli_stmt_close($stmt);
    }

    /* Cierre de la conexión */
    mysqli_close($link);
    ?>

Los ejemplos anteriores mostrarán:

    Amersfoort está en el distrito de Utrecht

### Ver también

- mysqli_stmt_execute() - Ejecuta una consulta preparada
- mysqli_stmt_fetch() - Lee los resultados de una consulta MySQL preparada en variables vinculadas
- mysqli_stmt_bind_param() - Vincula variables a una consulta MySQL
- mysqli_stmt_bind_result() - Vincula variables a un conjunto de resultados
- mysqli_stmt_get_result() - Obtiene un conjunto de resultados desde una consulta preparada como un objeto mysqli_result
- mysqli_stmt_close() - Termina una consulta preparada

# mysqli::query

# mysqli_query

(PHP 5, PHP 7, PHP 8)

mysqli::query -- mysqli_query — Ejecuta una consulta en la base de datos

### Descripción

Estilo orientado a objetos

public function mysqli::query(string `$query`, int `$result_mode` = `MYSQLI_STORE_RESULT`): mysqli_result|bool

Estilo procedimental

function mysqli_query(mysqli `$mysql`, string `$query`, int `$result_mode` = `MYSQLI_STORE_RESULT`): mysqli_result|bool

Ejecuta una consulta en la base de datos.

Advertencia

# Advertencia de seguridad: Inyección SQL

Si la consulta contiene alguna entrada de variable, entonces se deben usar sentencias preparadas parametrizadas en su lugar. Alternativamente, los datos deben estar correctamente formateados y todas las cadenas deben ser escapadas usando la función mysqli_real_escape_string().

Para consultas no-DML (que no son un INSERT, un UPDATE o un DELETE), esta función es similar a llamar a mysqli_real_query() seguida de mysqli_use_result() o mysqli_store_result().

> Nota:

> Si se pasa una consulta a mysqli_query() que es más larga que `max_allowed_packet`, los códigos de error devueltos serán diferentes según si se utiliza MySQL Native Driver (`mysqlnd`) o la MySQL Client Library (`libmysqlclient`). El comportamiento se define como sigue:

> - `mysqlnd` en Linux devuelve un código de error 1153. El mensaje de error será got a packet bigger than `max_allowed_packet` bytes.

> - `mysqlnd` en Windows devuelve un código de error 2006. El mensaje será del tipo server has gone away.

> - `libmysqlclient` en cualquier plataforma devuelve el código de error 2006. El mensaje será del tipo server has gone away.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()
`query`

  La consulta, en forma de string.

`result_mode`

  El modo de resultado puede ser una de las 3 constantes que indican cómo el resultado será devuelto por el servidor MySQL.

  `MYSQLI_STORE_RESULT` (por omisión) - devuelve un objeto mysqli_result con un conjunto de resultados almacenados en búfer.

  `MYSQLI_USE_RESULT` - devuelve un objeto mysqli_result con un conjunto de resultados no almacenados en búfer. Mientras haya registros pendientes de ser recuperados, la línea de conexión estará ocupada y todas las llamadas siguientes devolverán el error `Commands out of sync`. Para evitar el error, todos los registros deben ser recuperados del servidor o el conjunto de resultados debe ser descartado llamando a la mysqli_free_result().

  `MYSQLI_ASYNC` (disponible con mysqlnd) - la consulta se ejecuta de manera asíncrona y ningún conjunto de resultados es devuelto inmediatamente. mysqli_poll() se utiliza entonces para obtener los resultados de tales consultas. Utilizada en combinación con la constante `MYSQLI_STORE_RESULT` o `MYSQLI_USE_RESULT`.

### Valores devueltos

Devuelve `false` en caso de fallo. Para consultas exitosas que producen un conjunto de resultados como `SELECT, SHOW, DESCRIBE` o `EXPLAIN`, mysqli_query() devolverá un objeto mysqli_result. Para otros tipos de consultas exitosas, mysqli_query() devolverá `true`.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Ejemplos

Ejemplo #1 Ejemplo con mysqli::query()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* "Create table" no devolverá ningún conjunto de resultados */
    $mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City");
    printf("Tabla myCity creada con éxito.\n");

    /* Consulta "Select" devuelve un conjunto de resultados */
    $result = $mysqli->query("SELECT Name FROM City LIMIT 10");
    printf("Select ha devuelto %d líneas.\n", $result->num_rows);

    /* Si tenemos que recuperar muchos datos, utilizamos MYSQLI_USE_RESULT */
    $result = $mysqli->query("SELECT * FROM City", MYSQLI_USE_RESULT);

    /* Tenga en cuenta que no podemos ejecutar ninguna función que actúe en el servidor mientras
       el conjunto de resultados no esté cerrado. Todas las llamadas devolverán un 'out of sync' */
    $mysqli->query("SET @a:='this will not work'");

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* "Create table" no devolverá ningún conjunto de resultados */
    mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City");
    printf("Tabla myCity creada con éxito.\n");

    /* Consulta "Select" devuelve un conjunto de resultados */
    $result = mysqli_query($link, "SELECT Name FROM City LIMIT 10");
    printf("Select ha devuelto %d líneas.\n", mysqli_num_rows($result));

    /* Si tenemos que recuperar muchos datos, utilizamos MYSQLI_USE_RESULT */
    $result = mysqli_query($link, "SELECT * FROM City", MYSQLI_USE_RESULT);

    /* Tenga en cuenta que no podemos ejecutar ninguna función que actúe en el servidor mientras
       el conjunto de resultados no esté cerrado. Todas las llamadas devolverán un 'out of sync' */
    mysqli_query($link, "SET @a:='this will not work'");

Los ejemplos anteriores mostrarán:

    Tabla myCity creada con éxito.
    Select ha devuelto 10 líneas.
    Fatal error: Uncaught mysqli_sql_exception: Commands out of sync; you can't run this command now in...

### Ver también

- mysqli_execute_query() - Prepara, vincula los parámetros y ejecuta una sentencia SQL
- mysqli_real_query() - Ejecuta una consulta SQL
- mysqli_multi_query() - Ejecuta una o varias consultas en la base de datos
- mysqli_prepare() - Prepara una consulta SQL para su ejecución
- mysqli_free_result() - Libera la memoria asociada a un resultado

# mysqli::real_connect

# mysqli_real_connect

(PHP 5, PHP 7, PHP 8)

mysqli::real_connect -- mysqli_real_connect — Establece una conexión con un servidor MySQL

### Descripción

Estilo orientado a objetos

public function mysqli::real_connect(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`,
int `$flags` = 0
): bool

Estilo procedimental

function mysqli_real_connect(
mysqli `$mysql`,
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`,
int `$flags` = 0
): bool

Abre una conexión al servidor de base de datos MySQL con opciones de conexión opcionales.

Esta función difiere de mysqli_connect():

- mysqli_real_connect() requiere un objeto válido que debe ser creado por mysqli_init().

- Existe un parámetro adicional `flags`.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()
`hostname`

  Puede ser un nombre de host o una dirección IP. Al pasar `null`, el valor se recupera desde mysqli.default_host. Si es posible, se utilizarán pipes en lugar del protocolo TCP/IP. El protocolo TCP/IP se utiliza si se proporciona un nombre de host y un número de puerto juntos, por ejemplo `localhost:3308`.

`username`

  El nombre de usuario MySQL o `null` para asumir el nombre de usuario según la opción ini mysqli.default_user.

`password`

  La contraseña MySQL o `null` para asumir la contraseña según la opción ini mysqli.default_pw.

`database`

  La base de datos por defecto a utilizar al ejecutar consultas o `null`.

`port`

  El número de puerto al que intentar conectarse al servidor MySQL o `null` para asumir el puerto según la opción ini mysqli.default_port.

`socket`

  El socket o el pipe nombrado que debería utilizarse, o `null` para asumir el socket según la opción ini mysqli.default_socket.

  > Nota:

  > Especificar explícitamente el parámetro `socket` no determina el tipo de método utilizado al conectarse a MySQL. El método se determina por el parámetro `hostname`.

`flags`

  Con el parámetro `flags`, se pueden configurar diferentes directivas de conexión:

  Opciones soportadas
  Nombre | Descripción
  --- | ---
  `MYSQLI_CLIENT_COMPRESS` | Utiliza el protocolo comprimido
  `MYSQLI_CLIENT_FOUND_ROWS` | Devuelve el número de filas encontradas, no el número de filas afectadas.
  `MYSQLI_CLIENT_IGNORE_SPACE` | Permite espacios entre los nombres de funciones y los argumentos. Esto fuerza a que los nombres de funciones sean palabras reservadas.
  `MYSQLI_CLIENT_INTERACTIVE` | Permite `interactive_timeout` segundos (en lugar de `wait_timeout` segundos) de inactividad antes de cerrar la conexión.
  `MYSQLI_CLIENT_SSL` | Utiliza el cifrado SSL
  `MYSQLI_CLIENT_SSL_DONT_VERIFY_SERVER_CERT` | Igual que `MYSQLI_CLIENT_SSL`, pero desactiva la validación de los certificados SSL proporcionados. Esta constante está prevista solo para instalaciones que utilizan el driver MySQL nativo y MySQL 5.6 o superior.

  > Nota:

  > Por razones de seguridad, la opción `MULTI_STATEMENT` no es soportada en PHP. Si se desea ejecutar múltiples comandos, utilice la función mysqli_multi_query().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Historial de cambios

Versión | Descripción
--- | ---
7.4.0 | Todos los parámetros son ahora nullable.

### Ejemplos

Ejemplo #1 Ejemplo con mysqli::real_connect()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_init();

    $mysqli->options(MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0');
    $mysqli->options(MYSQLI_OPT_CONNECT_TIMEOUT, 5);

    $mysqli->real_connect('localhost', 'my_user', 'my_password', 'my_db', null, null, MYSQLI_CLIENT_COMPRESS|MYSQLI_CLIENT_FOUND_ROWS);

    echo 'Éxito... ' . $mysqli->host_info . "\n";

Estilo orientado a objetos, con extensión de la clase mysqli

    <?php

    class foo_mysqli extends mysqli {
        public function __construct($host, $user, $pass, $db)
        {
            parent::__construct();

            parent::options(MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0');
            parent::options(MYSQLI_OPT_CONNECT_TIMEOUT, 5);

            parent::real_connect($host, $user, $pass, $db, null, null, MYSQLI_CLIENT_COMPRESS|MYSQLI_CLIENT_FOUND_ROWS);
        }
    }

    $db = new foo_mysqli('localhost', 'my_user', 'my_password', 'my_db');

    echo 'Éxito... ' . $db->host_info . "\n";

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_init();

    mysqli_options($link, MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0');
    mysqli_options($link, MYSQLI_OPT_CONNECT_TIMEOUT, 5);

    mysqli_real_connect($link, 'localhost', 'my_user', 'my_password', 'my_db', null, null, MYSQLI_CLIENT_COMPRESS|MYSQLI_CLIENT_FOUND_ROWS);

    echo 'Éxito... ' . mysqli_get_host_info($link) . "\n";
    ?>

Los ejemplos anteriores mostrarán:

    Éxito... MySQL host info: localhost via TCP/IP

### Notas

> Nota: MySQLnd siempre asume el juego de caracteres predeterminado del servidor. Este juego de caracteres es enviado durante el intercambio de conexión/autenticación, el cual mysqlnd utilizará.Libmysqlclient utiliza el juego de caracteres predeterminado establecido en el my.cnf o mediante una llamada explícita a mysqli_options() antes de llamar a mysqli_real_connect(), pero después de mysqli_init().

### Ver también

- mysqli_connect() - Alias de mysqli::__construct
- mysqli_init() - Inicializa MySQLi y devuelve un objeto para usar con mysqli_real_connect()
- mysqli_options() - Define las opciones
- mysqli_ssl_set() - Utilizada para establecer una conexión segura con SSL
- mysqli_close() - Cierra una conexión

# mysqli::real_escape_string

# mysqli_real_escape_string

(PHP 5, PHP 7, PHP 8)

mysqli::real_escape_string -- mysqli_real_escape_string — Protege los caracteres especiales de un string para su uso en una consulta SQL, teniendo en cuenta el juego de caracteres actual de la conexión

### Descripción

Estilo orientado a objetos

public function mysqli::real_escape_string(string `$string`): string

Estilo procedimental

function mysqli_real_escape_string(mysqli `$mysql`, string `$string`): string

Esta función se utiliza para crear un string SQL válido que podrá ser utilizado en una consulta SQL. El string `string` se codifica para producir un string SQL escapado, teniendo en cuenta el juego de caracteres actual de la conexión.

Precaución

# Seguridad: El juego de caracteres por defecto

El juego de caracteres debe ser definido ya sea a nivel de servidor, o con la función API mysqli_set_charset() para que afecte a la función mysqli_real_escape_string(). Ver la sección sobre los conceptos de juegos de caracteres para más información.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()
`string`

  El string a escapar.

  Los caracteres codificados son `NUL (ASCII 0)`, `\n`, `\r`, `\`, `'`, `"`, y ``CTRL`+`Z``.

### Valores devueltos

Devuelve un string escapado.

### Ejemplos

Ejemplo #1 Ejemplo con mysqli::real_escape_string()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $city = "'s-Hertogenbosch";

    /* esta consulta con $city escapado funcionará */
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'",
        $mysqli->real_escape_string($city));
    $result = $mysqli->query($query);
    printf("La selección devolvió %d filas.\n", $result->num_rows);

    /* esta consulta fallará, porque no escapamos $city */
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'", $city);
    $result = $mysqli->query($query);

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $city = "'s-Hertogenbosch";

    /* esta consulta con $city escapado funcionará */
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'",
        mysqli_real_escape_string($mysqli, $city));
    $result = mysqli_query($mysqli, $query);
    printf("La selección devolvió %d filas.\n", mysqli_num_rows($result));

    /* esta consulta fallará, porque no escapamos $city */
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'", $city);
    $result = mysqli_query($mysqli, $query);

Los ejemplos anteriores mostrarán algo similar a:

    Select returned 1 rows.

    Fatal error: Uncaught mysqli_sql_exception: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 's-Hertogenbosch'' at line 1 in...

### Ver también

- mysqli_set_charset() - Define el juego de caracteres del cliente

# mysqli::real_query

# mysqli_real_query

(PHP 5, PHP 7, PHP 8)

mysqli::real_query -- mysqli_real_query — Ejecuta una consulta SQL

### Descripción

Estilo orientado a objetos

public function mysqli::real_query(string `$query`): bool

Estilo procedimental

function mysqli_real_query(mysqli `$mysql`, string `$query`): bool

Ejecuta una sola consulta en la conexión a la base de datos representada por el parámetro `link` cuyo resultado puede ser recuperado o almacenado utilizando las funciones mysqli_store_result() o mysqli_use_result().

Advertencia

# Advertencia de seguridad: Inyección SQL

Si la consulta contiene alguna entrada de variable, entonces se deben usar sentencias preparadas parametrizadas en su lugar. Alternativamente, los datos deben estar correctamente formateados y todas las cadenas deben ser escapadas usando la función mysqli_real_escape_string().

Para determinar si una consulta dada debería haber devuelto un conjunto de resultados o no, consulte la función mysqli_field_count().

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()
`query`

  La consulta string.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Ver también

- mysqli_query() - Ejecuta una consulta en la base de datos
- mysqli_store_result() - Transfiere un conjunto de resultados desde la última consulta
- mysqli_use_result() - Inicializa la recuperación de un conjunto de resultados

# mysqli::reap_async_query

# mysqli_reap_async_query

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::reap_async_query -- mysqli_reap_async_query — Lee un resultado para una consulta asíncrona

### Descripción

Estilo orientado a objetos

public function mysqli::reap_async_query(): mysqli_result|bool

Estilo procedimental

function mysqli_reap_async_query(mysqli `$mysql`): mysqli_result|bool

Lee el resultado para una consulta asíncrona.

> Nota:

> Disponible solo con mysqlnd.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

Devuelve `false` en caso de error. Para consultas exitosas que producen un conjunto de resultados como `SELECT, SHOW, DESCRIBE` o `EXPLAIN`, mysqli_reap_async_query() devolverá un objeto mysqli_result. Para otros tipos de consultas exitosas, mysqli_reap_async_query() devolverá `true`.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Ver también

- mysqli_poll() - Verifica el estado de la conexión

# mysqli::refresh

# mysqli_refresh

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::refresh -- mysqli_refresh — Actualiza

Advertencia

Esta función está OBSOLETA a partir de PHP 8.4.0. Depender de esta función está altamente desaconsejado.

### Descripción

Estilo orientado a objetos

#[\Deprecated]
public function mysqli::refresh(int `$flags`): bool

Estilo procedimental

#[\Deprecated]
function mysqli_refresh(mysqli `$mysql`, int `$flags`): bool

Actualiza las tablas o las cachés, o reinicia la información del servidor de réplica.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()
`flags`

  Las opciones de actualización, utilizando las constantes MYSQLI_REFRESH_* como se documenta en la documentación sobre las constantes MySQLi.

  Consulte también la documentación oficial sobre » la actualización en MySQL.

### Valores devueltos

`true` si la actualización se realizó con éxito, `false` en caso contrario.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Los métodos mysqli::refresh() y mysqli_refresh() están ahora obsoletos. Utilice los comandos SQL `FLUSH` en su lugar.

### Ver también

- mysqli_poll() - Verifica el estado de la conexión

# mysqli::release_savepoint

# mysqli_release_savepoint

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::release_savepoint -- mysqli_release_savepoint — Elimina el punto de guardado nombrado del conjunto de puntos de guardado de la transacción actual

### Descripción

Estilo orientado a objetos

public function mysqli::release_savepoint(string `$name`): bool

Estilo procedimental:

function mysqli_release_savepoint(mysqli `$mysql`, string `$name`): bool

Esta función equivale a ejecutar `$mysqli->query("RELEASE SAVEPOINT `$name`");`. Esta función no provocará un commit ni un rollback.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()
`name`

  El identificador del punto de guardado.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- mysqli_savepoint() - Establece un punto de guardado nombrado de la transacción

# mysqli::rollback

# mysqli_rollback

(PHP 5, PHP 7, PHP 8)

mysqli::rollback -- mysqli_rollback — Revierte la transacción actual

### Descripción

Estilo orientado a objetos

public function mysqli::rollback(int `$flags` = 0, ?string `$name` = `null`): bool

Estilo procedimental

function mysqli_rollback(mysqli `$mysql`, int `$flags` = 0, ?string `$name` = `null`): bool

Revierte la transacción actual para la base de datos.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()
`flags`

  Una máscara de constantes `MYSQLI_TRANS_COR_*`.

`name`

  Si se proporciona, entonces `ROLLBACK/*name*/` es ejecutado.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `name` ahora puede ser nullable.

### Ejemplos

Ver el ejemplo que se encuentra en la documentación del método mysqli::begin_transaction().

### Notas

> Nota:

> Esta función no funciona con los tipos de tabla no transaccionales (como MyISAM o ISAM).

### Ver también

- mysqli_begin_transaction() - Inicia una transacción
- mysqli_commit() - Valida la transacción actual
- mysqli_autocommit() - Activa o desactiva el modo auto-commit
- mysqli_release_savepoint() - Elimina el punto de guardado nombrado del conjunto de puntos de guardado de la transacción actual

# mysqli::savepoint

# mysqli_savepoint

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::savepoint -- mysqli_savepoint — Establece un punto de guardado nombrado de la transacción

### Descripción

Estilo orientado a objetos

public function mysqli::savepoint(string `$name`): bool

Estilo procedimental:

function mysqli_savepoint(mysqli `$mysql`, string `$name`): bool

Esta función equivale a ejecutar `$mysqli->query("SAVEPOINT `$name`");`

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()
`name`

  El identificador del punto de guardado

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- mysqli_release_savepoint() - Elimina el punto de guardado nombrado del conjunto de puntos de guardado de la transacción actual

# mysqli::select_db

# mysqli_select_db

(PHP 5, PHP 7, PHP 8)

mysqli::select_db -- mysqli_select_db — Selecciona una base de datos por defecto para las consultas

### Descripción

Estilo orientado a objetos

public function mysqli::select_db(string `$database`): bool

Estilo procedimental

function mysqli_select_db(mysqli `$mysql`, string `$database`): bool

Selecciona la base de datos por defecto (especificada por el argumento `database`) para ser utilizada al ejecutar consultas en la conexión representada por el argumento `mysql`.

> Nota:

> Esta función solo debe utilizarse para cambiar la base de datos por defecto para la conexión actual. La base de datos por defecto puede seleccionarse con el cuarto argumento de la función mysqli_connect().

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()
`database`

  El nombre de la base de datos.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Ejemplos

Ejemplo #1 Ejemplo con mysqli::select_db()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    /* obtener el nombre de la base de datos por defecto actual */
    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("La base de datos por defecto es %s.\n", $row[0]);

    /* cambiar la base de datos por defecto a "world" */
    $mysqli->select_db("world");

    /* obtener el nombre de la base de datos por defecto actual */
    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("La base de datos por defecto es %s.\n", $row[0]);

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "test");

    /* obtener el nombre de la base de datos por defecto actual */
    $result = mysqli_query($link, "SELECT DATABASE()");
    $row = mysqli_fetch_row($result);
    printf("La base de datos por defecto es %s.\n", $row[0]);

    /* cambiar la base de datos por defecto a "world" */
    mysqli_select_db($link, "world");

    /* obtener el nombre de la base de datos por defecto actual */
    $result = mysqli_query($link, "SELECT DATABASE()");
    $row = mysqli_fetch_row($result);
    printf("La base de datos por defecto es %s.\n", $row[0]);

Los ejemplos anteriores mostrarán:

    La base de datos por defecto es test.
    La base de datos por defecto es world.

### Ver también

- mysqli_connect() - Alias de mysqli::__construct
- mysqli_real_connect() - Establece una conexión con un servidor MySQL

# mysqli::set_charset

# mysqli_set_charset

(PHP 5 >= 5.0.5, PHP 7, PHP 8)

mysqli::set_charset -- mysqli_set_charset — Define el juego de caracteres del cliente

### Descripción

Estilo orientado a objetos

public function mysqli::set_charset(string `$charset`): bool

Estilo procedimental

function mysqli_set_charset(mysqli `$mysql`, string `$charset`): bool

Define el juego de caracteres a utilizar al enviar datos desde y hacia el servidor de base de datos.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()
`charset`

  El juego de caracteres a definir.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Ejemplos

Ejemplo #1 Ejemplo con mysqli::set_charset()

Estilo orientado a objetos

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    printf("Juego de caracteres inicial: %s\n", $mysqli->character_set_name());

    /* Cambio del juego de resultados a utf8mb4 */
    $mysqli->set_charset("utf8mb4");

    printf("Juego de caracteres actual: %s\n", $mysqli->character_set_name());
    ?>

Estilo procedimental

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect('localhost', 'my_user', 'my_password', 'test');

    printf("Juego de caracteres inicial: %s\n", mysqli_character_set_name($link));

    /* Cambio del juego de resultados a utf8mb4 */
    mysqli_set_charset($link, "utf8mb4");

    printf("Juego de caracteres actual: %s\n", mysqli_character_set_name($link));
    ?>

Los ejemplos anteriores mostrarán algo similar a:

    Juego de caracteres inicial: latin1
    Juego de caracteres actual: utf8mb4

### Notas

> Nota:

> Esta es la mejor forma de modificar el juego de caracteres. No se recomienda utilizar la función mysqli_query() para definirlo (como con la consulta `SET NAMES utf8`). Ver la sección Conceptos de juegos de caracteres de MySQL para más información.

### Ver también

- mysqli_character_set_name() - Devuelve el juego de caracteres actual para la conexión
- mysqli_real_escape_string() - Protege los caracteres especiales de un string para su uso en una consulta SQL, teniendo en cuenta el juego de caracteres actual de la conexión
- Conceptos de juegos de caracteres de MySQL
- » Lista de juegos de caracteres soportados por MySQL

# mysqli::$sqlstate

# mysqli_sqlstate

(PHP 5, PHP 7, PHP 8)

mysqli::$sqlstate -- mysqli_sqlstate — Devuelve el error SQLSTATE de la última operación MySQL

### Descripción

Estilo orientado a objetos

string $mysqli->sqlstate;

Estilo procedimental

function mysqli_sqlstate(mysqli `$mysql`): string

Devuelve un string que contiene el código de error SQLSTATE del último error. El código de error `'00000'` significa: "sin errores". Los valores están especificados por los estándares ANSI SQL y ODBC. Para una lista de los valores posibles, consulte: » http://dev.mysql.com/doc/mysql/en/error-handling.html.

> Nota:

> Tenga en cuenta que no todos los errores de MySQL tienen aún una correspondencia con los errores SQLSTATE. El valor `HY000` (error general) se utiliza para los errores sin correspondencia.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

Devuelve un string que contiene el código de error SQLSTATE del último error. El código está compuesto por 5 caracteres: `'00000'` representa la ausencia de errores.

### Ejemplos

Ejemplo #1 Ejemplo con $mysqli->sqlstate

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* La tabla Ciudad ya existe, deberíamos tener un error */
    try {
        $mysqli->query("CREATE TABLE City (ID INT, Name VARCHAR(30))");
    } catch (mysqli_sql_exception) {
        printf("Error - SQLSTATE %s.\n", $mysqli->sqlstate);
    }

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* La tabla Ciudad ya existe, deberíamos tener un error */
    try {
        mysqli_query($link, "CREATE TABLE City (ID INT, Name VARCHAR(30))");
    } catch (mysqli_sql_exception) {
        printf("Error - SQLSTATE %s.\n", mysqli_sqlstate($link));
    }

Los ejemplos anteriores mostrarán:

    Error - SQLSTATE 42S01.

### Ver también

- mysqli_errno() - Devuelve el último código de error producido
- mysqli_error() - Devuelve un string que describe el último error

# mysqli::ssl_set

# mysqli_ssl_set

(PHP 5, PHP 7, PHP 8)

mysqli::ssl_set -- mysqli_ssl_set — Utilizada para establecer una conexión segura con SSL

### Descripción

Estilo orientado a objetos

public function mysqli::ssl_set(
?string `$key`,
?string `$certificate`,
?string `$ca_certificate`,
?string `$ca_path`,
?string `$cipher_algos`
): true

Estilo procedimental

function mysqli_ssl_set(
mysqli `$mysql`,
?string `$key`,
?string `$certificate`,
?string `$ca_certificate`,
?string `$ca_path`,
?string `$cipher_algos`
): true

Utilizada para establecer una conexión segura con SSL. Debe ser llamada antes de mysqli_real_connect(). Esta función no hace nada si el soporte OpenSSL no está activado.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()
`key`

  La ruta hacia el fichero que contiene la clave.

`certificate`

  La ruta hacia el fichero que contiene el certificado.

`ca_certificate`

  La ruta hacia el fichero que contiene la autoridad del certificado.

`ca_path`

  La ruta hacia el directorio que contiene los certificados SSL CA en formato PEM.

`cipher_algos`

  La lista de cifrados autorizados para ser utilizados en el cifrado SSL.

### Valores devueltos

Retorna siempre `true`. Si SSL no está correctamente instalado, mysqli_real_connect() retornará un error cuando se intente una conexión.

### Ver también

- mysqli_options() - Define las opciones
- mysqli_real_connect() - Establece una conexión con un servidor MySQL

# mysqli::stat

# mysqli_stat

(PHP 5, PHP 7, PHP 8)

mysqli::stat -- mysqli_stat — Obtiene el estado actual del sistema

### Descripción

Estilo orientado a objetos

public function mysqli::stat(): string|false

Estilo procedimental

function mysqli_stat(mysqli `$mysql`): string|false

mysqli_stat() devuelve un string que contiene información similar al comando '`mysqladmin status`'. Esto incluye el tiempo de actividad, expresado en segundos y el número de hilos actuales, el número de comandos, las tablas recargadas y abiertas.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

Un string que describe el estado del servidor. `false` es devuelto si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con mysqli::stat()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    printf ("Estado del sistema: %s\n", $mysqli->stat());

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    printf("Estado del sistema: %s\n", mysqli_stat($link));

Los ejemplos anteriores mostrarán:

    Estado del sistema: Uptime: 272  Threads: 1  Questions: 5340  Slow queries: 0
    Opens: 13  Flush tables: 1  Open tables: 0  Queries per second avg: 19.632
    Memory in use: 8496K  Max memory used: 8560K

### Ver también

- mysqli_get_server_info() - Devuelve la versión del servidor MySQL

# mysqli::stmt_init

# mysqli_stmt_init

(PHP 5, PHP 7, PHP 8)

mysqli::stmt_init -- mysqli_stmt_init — Inicializa una sentencia MySQL

### Descripción

Estilo orientado a objetos

public function mysqli::stmt_init(): mysqli_stmt|false

Estilo procedimental

function mysqli_stmt_init(mysqli `$mysql`): mysqli_stmt|false

Asigna e inicializa un objeto de sentencia, para ser utilizado con mysqli_stmt_prepare().

> Nota:

> Todas las llamadas posteriores a las funciones mysqli_stmt_* fallarán, si mysqli_stmt_prepare() es llamada.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

Devuelve un objeto.

### Ver también

- mysqli_stmt_prepare() - Prepara una consulta SQL para su ejecución

# mysqli::store_result

# mysqli_store_result

(PHP 5, PHP 7, PHP 8)

mysqli::store_result -- mysqli_store_result — Transfiere un conjunto de resultados desde la última consulta

### Descripción

Estilo orientado a objetos

public function mysqli::store_result(int `$mode` = 0): mysqli_result|false

Estilo procedimental

function mysqli_store_result(mysqli `$mysql`, int `$mode` = 0): mysqli_result|false

Transfiere el conjunto de resultados desde la última consulta en la conexión a la base de datos especificada por el argumento `mysql` para su uso con mysqli_data_seek().

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()
`mode`

  La opción que se desea definir. A partir de PHP 8.1, este argumento no tiene ningún efecto. Puede tomar uno de los siguientes valores:

  Opciones válidas
  Nombre | Descripción
  --- | ---
  `MYSQLI_STORE_RESULT_COPY_DATA` | Copia los resultados recuperados de un buffer interno mysqlnd a variables PHP. Por omisión, mysqlnd utilizará una referencia lógica para evitar la copia y la duplicación de los resultados contenidos en memoria. Para ciertos conjuntos de resultados, por ejemplo, los conjuntos de resultados con muchas filas pequeñas, el enfoque de copia puede reducir el uso de memoria por las variables PHP que contienen los resultados pueden ser liberadas rápidamente (disponible únicamente con mysqlnd)

### Valores devueltos

Retorna un resultado almacenado en forma de objeto o `false` si ocurre un error.

> Nota:

> mysqli_store_result() retorna `false` en caso de que la consulta no retorne un conjunto de resultados (si la consulta es de tipo INSERT por ejemplo). Esta función retornará siempre `false` si el conjunto de resultados no puede ser leído. Se puede saber si hay un error utilizando la función mysqli_error() y mirando si retorna un string vacío, o si mysqli_errno() retorna cero, o bien si mysqli_field_count() retorna un valor diferente de cero. Otra razón para que esta función retorne `false` es que el conjunto de resultados retornado después de una consulta exitosa llamada por mysqli_query() es demasiado largo (la memoria para este no puede ser asignada). Si mysqli_field_count() retorna un valor diferente de cero, el procesamiento debería producir un conjunto de resultados no vacío.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | El paso del argumento `mode` está ahora obsoleto. Este argumento no ha tenido ningún efecto desde PHP 8.1.0.

### Ejemplos

Ver la función mysqli_multi_query().

### Notas

> Nota:

> Siempre se recomienda liberar la memoria asignada para el resultado utilizando la función mysqli_free_result(), al transferir grandes resultados utilizando la función mysqli_store_result() esto se vuelve particularmente importante.

### Ver también

- mysqli_real_query() - Ejecuta una consulta SQL
- mysqli_use_result() - Inicializa la recuperación de un conjunto de resultados

# mysqli::$thread_id

# mysqli_thread_id

(PHP 5, PHP 7, PHP 8)

mysqli::$thread_id -- mysqli_thread_id — Devuelve el identificador del hilo para la conexión actual

### Descripción

Estilo orientado a objetos

int $mysqli->thread_id;

Estilo procedimental

function mysqli_thread_id(mysqli `$mysql`): int

La función mysqli_thread_id() devuelve el identificador del hilo de la conexión actual que puede ser terminado posteriormente utilizando la función mysqli_kill(). Si la conexión se pierde y se reconecta con la función mysqli_ping(), el identificador del hilo será diferente. Por lo tanto, se debe recuperar el identificador del hilo únicamente cuando sea necesario.

> Nota:

> El identificador del hilo se asigna por conexión. Esto significa que si la conexión se interrumpe y luego se restablece, se le asignará un nuevo identificador de hilo.

> Para terminar una consulta en ejecución, se puede utilizar el comando SQL `KILL QUERY processid`.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

Devuelve el identificador del hilo para la conexión actual.

### Ejemplos

Ejemplo #1 Ejemplo con $mysqli->thread_id

Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verificación de la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    /* Determina el identificador del hilo */
    $thread_id = $mysqli->thread_id;

    /* Termina la conexión */
    $mysqli->kill($thread_id);

    /* Esto debe producir un error */
    if (!$mysqli->query("CREATE TABLE myCity LIKE City")) {
        printf("Error: %s\n", $mysqli->error);
        exit;
    }

    /* Cierre de la conexión */
    $mysqli->close();
    ?>

Estilo procedimental

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verificación de la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    /* Determina el identificador del hilo */
    $thread_id = mysqli_thread_id($link);

    /* Termina la conexión */
    mysqli_kill($link, $thread_id);

    /* Esto debe producir un error */
    if (!mysqli_query($link, "CREATE TABLE myCity LIKE City")) {
        printf("Error: %s\n", mysqli_error($link));
        exit;
    }

    /* Cierre de la conexión */
    mysqli_close($link);
    ?>

Los ejemplos anteriores mostrarán:

    Error: MySQL server has gone away

### Ver también

- mysqli_kill() - Solicita al servidor que finalice un hilo MySQL

# mysqli::thread_safe

# mysqli_thread_safe

(PHP 5, PHP 7, PHP 8)

mysqli::thread_safe -- mysqli_thread_safe — Indica si el soporte de hilos está activado o no

### Descripción

Estilo orientado a objetos

public function mysqli::thread_safe(): bool

Estilo procedimental

function mysqli_thread_safe(): bool

Indica si la biblioteca cliente está compilada con seguridad para hilos.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

`true` si la biblioteca cliente es thread-safe, `false` en caso contrario.

# mysqli::use_result

# mysqli_use_result

(PHP 5, PHP 7, PHP 8)

mysqli::use_result -- mysqli_use_result — Inicializa la recuperación de un conjunto de resultados

### Descripción

Estilo orientado a objetos

public function mysqli::use_result(): mysqli_result|false

Estilo procedimental

function mysqli_use_result(mysqli `$mysql`): mysqli_result|false

Se utiliza para inicializar la recuperación de un conjunto de resultados a partir de la última consulta ejecutada utilizando la función mysqli_real_query() en la conexión especificada por el parámetro `link`.

Esta función o la función mysqli_store_result() deben ser llamadas antes de que el resultado de una consulta pueda ser recuperado, y para evitar el fallo de la próxima consulta en la conexión a la base de datos.

> Nota:

> La función mysqli_use_result() no transfiere el conjunto de resultados completo desde la base de datos y por lo tanto no se pueden utilizar funciones como mysqli_data_seek() para moverse entre los registros. Para utilizar esta funcionalidad, se debe recuperar el conjunto de resultados utilizando mysqli_store_result().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un objeto de resultados no almacenados o `false` si ocurre un error.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Ejemplos

Ejemplo #1 Ejemplo con mysqli::use_result()

Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verificación de la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    $query  = "SELECT CURRENT_USER();";
    $query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

    /* Ejecución de múltiples consultas */
    if ($mysqli->multi_query($query)) {
        do {
            /* Almacenamiento del primer conjunto de resultados */
            if ($result = $mysqli->use_result()) {
                while ($row = $result->fetch_row()) {
                    printf("%s\n", $row[0]);
                }
                $result->close();
            }
            /* Visualización de una demarcación */
            if ($mysqli->more_results()) {
                printf("-----------------\n");
            }
        } while ($mysqli->next_result());
    }

    /* Cierre de la conexión */
    $mysqli->close();
    ?>

Estilo procedimental

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verificación de la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    $query  = "SELECT CURRENT_USER();";
    $query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

    /* Ejecución de múltiples consultas */
    if (mysqli_multi_query($link, $query)) {
        do {
            /* Almacenamiento del primer conjunto de resultados */
            if ($result = mysqli_use_result($link)) {
                while ($row = mysqli_fetch_row($result)) {
                    printf("%s\n", $row[0]);
                }
                mysqli_free_result($result);
            }
            /* Visualización de una demarcación */
            if (mysqli_more_results($link)) {
                printf("-----------------\n");
            }
        } while (mysqli_next_result($link));
    }

    /* Cierre de la conexión */
    mysqli_close($link);
    ?>

Los ejemplos anteriores mostrarán:

    my_user@localhost
    -----------------
    Amersfoort
    Maastricht
    Dordrecht
    Leiden
    Haarlemmermeer

### Ver también

- mysqli_real_query() - Ejecuta una consulta SQL
- mysqli_store_result() - Transfiere un conjunto de resultados desde la última consulta

# mysqli::$warning_count

# mysqli_warning_count

(PHP 5, PHP 7, PHP 8)

mysqli::$warning_count -- mysqli_warning_count — Devuelve el número de advertencias generadas por la última consulta ejecutada

### Descripción

Estilo orientado a objetos

int $mysqli->warning_count;

Estilo procedimental

function mysqli_warning_count(mysqli `$mysql`): int

Devuelve el número de advertencias generadas por la última consulta ejecutada.

> Nota: Para recuperar los mensajes de advertencia, se puede utilizar el siguiente comando SQL: `SHOW WARNINGS [LIMIT row_count]`.

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()

### Valores devueltos

El número de advertencias o `0` si no hay ninguna.

### Ejemplos

Ejemplo #1 Ejemplo con $mysqli->warning_count

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("SELECT 42/0");

    if ($mysqli->warning_count > 0) {
        $result = $mysqli->query("SHOW WARNINGS");
        $row = $result->fetch_row();
        printf("%s (%d): %s\n", $row[0], $row[1], $row[2]);
    }

    ?>

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    mysqli_query($link, "SELECT 42/0");

    if (mysqli_warning_count($link) > 0) {
        $result = mysqli_query($link, "SHOW WARNINGS");
        $row = mysqli_fetch_row($result);
        printf("%s (%d): %s\n", $row[0], $row[1], $row[2]);
    }
    ?>

Los ejemplos anteriores mostrarán:

    Warning (1365): Division by 0

### Ver también

- mysqli_errno() - Devuelve el último código de error producido
- mysqli_error() - Devuelve un string que describe el último error
- mysqli_sqlstate() - Devuelve el error SQLSTATE de la última operación MySQL

## Tabla de contenidos

- mysqli::$affected_rows — Devuelve el número de filas afectadas por la última operación MySQL
- mysqli::autocommit — Activa o desactiva el modo auto-commit
- mysqli::begin_transaction — Inicia una transacción
- mysqli::change_user — Cambia el usuario de la conexión
- mysqli::character_set_name — Devuelve el juego de caracteres actual para la conexión
- mysqli::close — Cierra una conexión
- mysqli::commit — Valida la transacción actual
- mysqli::$connect_errno — Devuelve el código de error de la última llamada de conexión
- mysqli::$connect_error — Devuelve una descripción del último error de conexión
- mysqli::__construct — Abre una conexión a un servidor MySQL
- mysqli::debug — Realiza acciones de depuración
- mysqli::dump_debug_info — Escribe la información de depuración en los registros
- mysqli::$errno — Devuelve el último código de error producido
- mysqli::$error — Devuelve un string que describe el último error
- mysqli::$error_list — Devuelve una lista de errores desde el último comando ejecutado
- mysqli::execute_query — Prepara, vincula los parámetros y ejecuta una sentencia SQL
- mysqli::$field_count — Devuelve el número de columnas para la última consulta
- mysqli::get_charset — Devuelve un objeto que representa el juego de caracteres
- mysqli::$client_info — Obtiene información sobre el cliente MySQL
- mysqli::$client_version — Devuelve la versión del cliente MySQL como un entero
- mysqli::get_connection_stats — Devuelve estadísticas sobre la conexión
- mysqli::$host_info — Devuelve un string que contiene el tipo de conexión utilizada
- mysqli::$protocol_version — Devuelve la versión del protocolo MySQL utilizado
- mysqli::$server_info — Devuelve la versión del servidor MySQL
- mysqli::$server_version — Devuelve un integer que representa la versión del servidor MySQL
- mysqli::get_warnings — Lee el resultado de SHOW WARNINGS
- mysqli::$info — Devuelve información acerca de la última consulta ejecutada
- mysqli::init — Inicializa MySQLi y devuelve un objeto para usar con mysqli_real_connect()
- mysqli::$insert_id — Devuelve el valor generado para una columna AUTO_INCREMENT por la última consulta
- mysqli::kill — Solicita al servidor que finalice un hilo MySQL
- mysqli::more_results — Comprueba si hay más conjuntos de resultados MySQL disponibles
- mysqli::multi_query — Ejecuta una o varias consultas en la base de datos
- mysqli::next_result — Prepara el siguiente resultado de una consulta múltiple
- mysqli::options — Define las opciones
- mysqli::ping — Verifica la conexión al servidor y reconecta si ya no existe
- mysqli::poll — Verifica el estado de la conexión
- mysqli::prepare — Prepara una consulta SQL para su ejecución
- mysqli::query — Ejecuta una consulta en la base de datos
- mysqli::real_connect — Establece una conexión con un servidor MySQL
- mysqli::real_escape_string — Protege los caracteres especiales de un string para su uso en una consulta SQL, teniendo en cuenta el juego de caracteres actual de la conexión
- mysqli::real_query — Ejecuta una consulta SQL
- mysqli::reap_async_query — Lee un resultado para una consulta asíncrona
- mysqli::refresh — Actualiza
- mysqli::release_savepoint — Elimina el punto de guardado nombrado del conjunto de puntos de guardado de la transacción actual
- mysqli::rollback — Revierte la transacción actual
- mysqli::savepoint — Establece un punto de guardado nombrado de la transacción
- mysqli::select_db — Selecciona una base de datos por defecto para las consultas
- mysqli::set_charset — Define el juego de caracteres del cliente
- mysqli::$sqlstate — Devuelve el error SQLSTATE de la última operación MySQL
- mysqli::ssl_set — Utilizada para establecer una conexión segura con SSL
- mysqli::stat — Obtiene el estado actual del sistema
- mysqli::stmt_init — Inicializa una sentencia MySQL
- mysqli::store_result — Transfiere un conjunto de resultados desde la última consulta
- mysqli::$thread_id — Devuelve el identificador del hilo para la conexión actual
- mysqli::thread_safe — Indica si el soporte de hilos está activado o no
- mysqli::use_result — Inicializa la recuperación de un conjunto de resultados
- mysqli::$warning_count — Devuelve el número de advertencias generadas por la última consulta ejecutada

# La clase mysqli_stmt

(PHP 5, PHP 7, PHP 8)

## Introducción

Representa una consulta preparada.

## Sinopsis de la Clase

class mysqli_stmt {
/* Propiedades */
public readonly int|string $affected_rows;
public readonly int|string $insert_id;
public readonly int|string $num_rows;
public readonly int $param_count;
public readonly int $field_count;
public readonly int $errno;
public readonly string $error;
public readonly array $error_list;
public readonly string $sqlstate;
public int $id;
/* Métodos */
public function __construct(mysqli `$mysql`, ?string `$query` = `null`)
public function attr_get(int `$attribute`): int
public function attr_set(int `$attribute`, int `$value`): bool
public function bind_param(string `$types`, mixed `&$var`, mixed `&...$vars`): bool
public function bind_result(mixed `&$var`, mixed `&...$vars`): bool
public function close(): true
public function data_seek(int `$offset`): void
public function execute(?array `$params` = `null`): bool
public function fetch(): ?bool
public function free_result(): void
public function get_result(): mysqli_result|false
public function get_warnings(): mysqli_warning|false
public function more_results(): bool
public function next_result(): bool
public function num_rows(): int|string
public function prepare(string `$query`): mixed
public function reset(): bool
public function result_metadata(): mysqli_result|false
public function send_long_data(int `$param_num`, string `$data`): bool
public function store_result(): bool
}

## Propiedades

id

  Almacena el ID de la sentencia.

# mysqli_stmt::$affected_rows

# mysqli_stmt_affected_rows

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$affected_rows -- mysqli_stmt_affected_rows — Devuelve el número total de filas modificadas, eliminadas, insertadas o coincidentes por la última consulta

### Descripción

Estilo orientado a objetos

int|string $mysqli_stmt->affected_rows;

Estilo procedimental

function mysqli_stmt_affected_rows(mysqli_stmt `$statement`): int|string

Devuelve el número de filas afectadas por una consulta `INSERT`, `UPDATE` o `DELETE`.

Funciona como mysqli_stmt_num_rows() para las consultas `SELECT`.

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().

### Valores devueltos

Un entero mayor que cero indica el número de filas afectadas o recuperadas. Cero indica que ningún registro fue modificado por una consulta de tipo `UPDATE`, ninguna fila coincide con la cláusula `WHERE` en la consulta o que ninguna consulta fue ejecutada. `-1` indica que la consulta devolvió un error o que, para una consulta `SELECT`, mysqli_stmt_affected_rows() fue llamado antes de llamar mysqli_stmt_store_result().

> Nota:

> Si el número de filas afectadas es mayor que el valor máximo de un entero PHP, el número de filas afectadas será devuelto como una cadena de caracteres.

### Ejemplos

Ejemplo #1 Ejemplo de mysqli_stmt_affected_rows()

Estilo orientado a objetos

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Creación de una tabla temporal */
    $mysqli->query("CREATE TEMPORARY TABLE myCountry LIKE Country");

    $query = "INSERT INTO myCountry SELECT * FROM Country WHERE Code LIKE ?";

    /* Preparación de la consulta */
    $stmt = $mysqli->prepare($query);

    /* Vincula una variable a un parámetro ficticio */
    $code = 'A%';
    $stmt->bind_param("s", $code);

    /* Ejecución de la consulta */
    $stmt->execute();

    printf("Filas insertadas: %d\n", $stmt->affected_rows);
    ?>

Estilo procedimental

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Creación de una tabla temporal */
    mysqli_query($link, "CREATE TEMPORARY TABLE myCountry LIKE Country");

    $query = "INSERT INTO myCountry SELECT * FROM Country WHERE Code LIKE ?";

    /* Preparación de la consulta */
    $stmt = mysqli_prepare($link, $query);

    /* Vincula una variable a un parámetro ficticio */
    $code = 'A%';
    mysqli_stmt_bind_param($stmt, "s", $code);

    /* Ejecución de la consulta */
    mysqli_stmt_execute($stmt);

    printf("Filas insertadas: %d\n", mysqli_stmt_affected_rows($stmt));
    ?>

El ejemplo anterior mostrará:

    Filas insertadas: 17

### Ver también

- mysqli_stmt_num_rows() - Devuelve el número de filas recuperadas del servidor
- mysqli_stmt_store_result() - Almacena un conjunto de resultados en un búfer interno

# mysqli_stmt::attr_get

# mysqli_stmt_attr_get

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::attr_get -- mysqli_stmt_attr_get — Obtiene el valor actual de un atributo de consulta

### Descripción

Estilo orientado a objetos

public function mysqli_stmt::attr_get(int `$attribute`): int

Estilo procedimental

function mysqli_stmt_attr_get(mysqli_stmt `$statement`, int `$attribute`): int

Obtiene el valor actual de un atributo de consulta.

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().
`attribute`

  El atributo que se desea recuperar.

### Valores devueltos

Devuelve el valor del atributo.

# mysqli_stmt::attr_set

# mysqli_stmt_attr_set

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::attr_set -- mysqli_stmt_attr_set — Modifica el comportamiento de una consulta preparada

### Descripción

Estilo orientado a objetos

public function mysqli_stmt::attr_set(int `$attribute`, int `$value`): bool

Estilo procedimental

function mysqli_stmt_attr_set(mysqli_stmt `$statement`, int `$attribute`, int `$value`): bool

Modifica el comportamiento de una consulta preparada. Esta función puede ser llamada varias veces para definir múltiples atributos.

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().
`attribute`

  El atributo que se desea definir. Puede tener uno de los siguientes valores:

  Valores de los atributos
  Caracteres | Descripción
  --- | ---
  MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH | Si se define como `true`, la función mysqli_stmt_store_result() actualizará el valor de los metadatos `MYSQL_FIELD->max_length`.
  MYSQLI_STMT_ATTR_CURSOR_TYPE | Tipo de cursor que permite abrir la consulta cuando se llama a la función mysqli_stmt_execute(). `value` puede ser `MYSQLI_CURSOR_TYPE_NO_CURSOR` (por omisión) o `MYSQLI_CURSOR_TYPE_READ_ONLY`.
  MYSQLI_STMT_ATTR_PREFETCH_ROWS | Número de filas a recuperar desde el servidor de una sola vez al utilizar un cursor. `value` puede estar comprendido entre 1 y el valor máximo de un tipo long sin signo. Por omisión, vale 1. Eliminado a partir de PHP 8.4.0.

  Si se utiliza la opción `MYSQLI_STMT_ATTR_CURSOR_TYPE` con `MYSQLI_CURSOR_TYPE_READ_ONLY`, se abrirá un cursor para la consulta al llamar a la función mysqli_stmt_execute(). Si ya existe un cursor abierto desde una llamada previa a la función mysqli_stmt_execute(), se cerrará antes de abrir uno nuevo. La función mysqli_stmt_reset() cierra asimismo todos los cursores antes de preparar la consulta para una nueva ejecución. La función mysqli_stmt_free_result() cierra cualquier cursor abierto.

  Si se abre un cursor para una consulta preparada, la función mysqli_stmt_store_result() no es necesaria.

`value`

  El valor a asignar al atributo.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Ver también

- » Conector / MySQL mysql_stmt_attr_set()

# mysqli_stmt::bind_param

# mysqli_stmt_bind_param

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::bind_param -- mysqli_stmt_bind_param — Vincula variables a una consulta MySQL

### Descripción

Estilo orientado a objetos

public function mysqli_stmt::bind_param(string `$types`, mixed `&$var`, mixed `&...$vars`): bool

Estilo procedimental

function mysqli_stmt_bind_param(
mysqli_stmt `$statement`,
string `$types`,
mixed `&$var`,
mixed `&...$vars`
): bool

Vincula variables para los marcadores de parámetro en la consulta preparada por mysqli_prepare() o mysqli_stmt_prepare().

> Nota:

> Si el tamaño de los datos supera el tamaño máximo de un paquete, (`max_allowed_packet`), se debe especificar el carácter `b` en el parámetro `types` y utilizar la función mysqli_stmt_send_long_data() para enviar el mensaje por paquetes.

> Nota:

> Se debe tener precaución al utilizar mysqli_stmt_bind_param() con la función call_user_func_array(). Tenga en cuenta que mysqli_stmt_bind_param() requiere que sus parámetros sean pasados por referencia, mientras que la función call_user_func_array() puede aceptar como parámetro una lista de variables que pueden representar referencias o valores.

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().
`types`

  Una string que contiene uno o más caracteres que especifican el tipo de la variable a vincular:

  Carácter de especificación de tipos
  Carácter | Descripción
  --- | ---
  i | corresponde a una variable de tipo int
  d | corresponde a una variable de tipo float
  s | corresponde a una variable de tipo string
  b | corresponde a una variable de tipo BLOB, que será enviada por paquetes

`var`
`vars`

  El número de variables y la longitud de la string `types` deben corresponder a los parámetros de la consulta.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Ejemplos

Ejemplo #1 Ejemplo con mysqli_stmt::bind_param()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

    $stmt = $mysqli->prepare("INSERT INTO CountryLanguage VALUES (?, ?, ?, ?)");
    $stmt->bind_param('sssd', $code, $language, $official, $percent);

    $code = 'DEU';
    $language = 'Bavarian';
    $official = "F";
    $percent = 11.2;

    $stmt->execute();

    printf("%d fila insertada.\n", $stmt->affected_rows);

    /* Limpiar tabla CountryLanguage */
    $mysqli->query("DELETE FROM CountryLanguage WHERE Language='Bavarian'");
    printf("%d fila eliminada.\n", $mysqli->affected_rows);

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world');

    $stmt = mysqli_prepare($link, "INSERT INTO CountryLanguage VALUES (?, ?, ?, ?)");
    mysqli_stmt_bind_param($stmt, 'sssd', $code, $language, $official, $percent);

    $code = 'DEU';
    $language = 'Bavarian';
    $official = "F";
    $percent = 11.2;

    mysqli_stmt_execute($stmt);

    printf("%d fila insertada.\n", mysqli_stmt_affected_rows($stmt));

    /* Limpiar tabla CountryLanguage */
    mysqli_query($link, "DELETE FROM CountryLanguage WHERE Language='Bavarian'");
    printf("%d fila eliminada.\n", mysqli_affected_rows($link));

Los ejemplos anteriores mostrarán:

    1 fila insertada.
    1 fila eliminada.

Ejemplo #2 Uso de `...` para proporcionar argumentos

El operador `...` puede ser utilizado para proporcionar una lista de argumentos de longitud variable, por ejemplo, en una cláusula `WHERE IN`.

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

    $stmt = $mysqli->prepare("SELECT Language FROM CountryLanguage WHERE CountryCode IN (?, ?)");
    /* Usando ... para proporcionar argumentos */
    $stmt->bind_param('ss', ...['DEU', 'POL']);
    $stmt->execute();
    $stmt->store_result();

    printf("%d filas encontradas.\n", $stmt->num_rows());

Los ejemplos anteriores mostrarán:

    10 filas encontradas.

### Ver también

- mysqli_stmt_bind_result() - Vincula variables a un conjunto de resultados
- mysqli_stmt_execute() - Ejecuta una consulta preparada
- mysqli_stmt_fetch() - Lee los resultados de una consulta MySQL preparada en variables vinculadas
- mysqli_prepare() - Prepara una consulta SQL para su ejecución
- mysqli_stmt_send_long_data() - Envía datos MySQL por paquetes
- mysqli_stmt_errno() - Devuelve un código de error para la última consulta
- mysqli_stmt_error() - Devuelve una descripción del último error de procesamiento

# mysqli_stmt::bind_result

# mysqli_stmt_bind_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::bind_result -- mysqli_stmt_bind_result — Vincula variables a un conjunto de resultados

### Descripción

Estilo orientado a objetos

public function mysqli_stmt::bind_result(mixed `&$var`, mixed `&...$vars`): bool

Estilo procedimental

function mysqli_stmt_bind_result(mysqli_stmt `$statement`, mixed `&$var`, mixed `&...$vars`): bool

Asocia columnas de un resultado a variables.

Cuando se llama a mysqli_stmt_fetch() para leer valores, el protocolo MySQL coloca los datos en las variables especificadas `var`/`vars`.

Una columna puede ser vinculada en cualquier momento, incluso después de que un conjunto de resultados haya sido parcialmente recuperado. La nueva vinculación entra en vigor la próxima vez que se llame a mysqli_stmt_fetch().

> Nota:

> Todas las columnas deben ser vinculadas después de la ejecución de la función mysqli_stmt_execute() y antes de la llamada a la función mysqli_stmt_fetch(). Dependiendo del tipo de valor de la columna, el tipo de variable PHP puede ser modificado automáticamente.

> Nota:

> Una columna puede ser asociada o reasociada en cualquier momento, incluso después de una lectura parcial del resultado. La nueva asociación entra en vigor en la próxima llamada a mysqli_stmt_fetch().

Sugerencia

Esta función es útil para resultados básicos. Para recuperar un conjunto de resultados iterable, o recuperar cada fila como array u objeto, utilice mysqli_stmt_get_result().

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().
`var`

  La primera variable a vincular.

`vars`

  Variables adicionales a vincular.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Preparación de la consulta */
    $stmt = $mysqli->prepare("SELECT Code, Name FROM Country ORDER BY Name LIMIT 5");
    $stmt->execute();

    /* Vincular variables a una declaración preparada */
    $stmt->bind_result($col1, $col2);

    /* Recuperación de los valores */
    while ($stmt->fetch()) {
        printf("%s %s\n", $col1, $col2);
    }
    ?>

Ejemplo #2 Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Preparación de la consulta */
    $stmt = mysqli_prepare($link, "SELECT Code, Name FROM Country ORDER BY Name LIMIT 5");
    mysqli_stmt_execute($stmt);

    /* Vincular variables a una declaración preparada */
    mysqli_stmt_bind_result($stmt, $col1, $col2);

    /* Recuperación de los valores */
    while (mysqli_stmt_fetch($stmt)) {
        printf("%s %s\n", $col1, $col2);
    }
    ?>

El ejemplo anterior mostrará:

    AFG Afghanistan
    ALB Albania
    DZA Algeria
    ASM American Samoa
    AND Andorra

### Ver también

- mysqli_stmt_get_result() - Obtiene un conjunto de resultados desde una consulta preparada como un objeto mysqli_result
- mysqli_stmt_bind_param() - Vincula variables a una consulta MySQL
- mysqli_stmt_execute() - Ejecuta una consulta preparada
- mysqli_stmt_fetch() - Lee los resultados de una consulta MySQL preparada en variables vinculadas
- mysqli_prepare() - Prepara una consulta SQL para su ejecución
- mysqli_stmt_prepare() - Prepara una consulta SQL para su ejecución

# mysqli_stmt::close

# mysqli_stmt_close

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::close -- mysqli_stmt_close — Termina una consulta preparada

### Descripción

Estilo orientado a objetos

public function mysqli_stmt::close(): true

Estilo procedimental

function mysqli_stmt_close(mysqli_stmt `$statement`): true

Cierra una consulta preparada. mysqli_stmt_close() libera el puntero utilizado por `stmt`. Si la consulta está pendiente o los resultados no han sido leídos aún, esta función los cancelará y, por lo tanto, la siguiente consulta podrá ser ejecutada.

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función ahora siempre devuelve `true`. Anteriormente, devolvía `false` en caso de fallo.

### Ver también

- mysqli_prepare() - Prepara una consulta SQL para su ejecución

# mysqli_stmt::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::__construct — Construye un nuevo objeto mysqli_stmt

### Descripción

public function mysqli_stmt::__construct(mysqli `$mysql`, ?string `$query` = `null`)

Este método construye un nuevo objeto mysqli_stmt.

### Parámetros

`link`

  Un objeto mysqli válido.

`query`

  La consulta, en forma de string. Si este argumento es `null`, entonces el constructor se comportará como la función mysqli_stmt_init(); de lo contrario, se comportará como la función mysqli_prepare().

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `query` ahora es nullable.

### Ver también

- mysqli_prepare() - Prepara una consulta SQL para su ejecución
- mysqli_stmt_init() - Inicializa una sentencia MySQL

# mysqli_stmt::data_seek

# mysqli_stmt_data_seek

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::data_seek -- mysqli_stmt_data_seek — Ajusta el puntero de resultado a una fila arbitraria en el resultado almacenado en el búfer.

### Descripción

Estilo orientado a objetos

public function mysqli_stmt::data_seek(int `$offset`): void

Estilo procedimental

function mysqli_stmt_data_seek(mysqli_stmt `$statement`, int `$offset`): void

Esta función mueve el puntero del conjunto de resultados almacenado en el búfer a una fila arbitraria especificada por el parámetro `offset`.

Esta función solo funciona en el conjunto de resultados interno almacenado en el búfer. mysqli_stmt_store_result() debe ser llamada antes de la función mysqli_stmt_data_seek().

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().
`offset`

  Debe tomar un valor entre cero y el número total de filas menos 1 (0..mysqli_stmt_num_rows() - 1).

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name";
    $stmt = $mysqli->prepare($query);
    $stmt->execute();

    /* Cierra la conexión */
    $mysqli->close();
    ?>

Ejemplo #2 Estilo procedimental

    <?php
    /* Abre la conexión */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verifica la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name";
    if ($stmt = mysqli_prepare($link, $query)) {

        /* Ejecuta la consulta */
        mysqli_stmt_execute($stmt);

        /* Vincula las variables de resultado */
        mysqli_stmt_bind_result($stmt, $name, $code);

        /* Almacena el resultado */
        mysqli_stmt_store_result($stmt);

        $stmt->bind_result($name, $code);

        $stmt->store_result();

        /* Lee la fila n°400 */
        $stmt->data_seek(399);

        /* Cierra la sentencia */
        mysqli_stmt_close($stmt);
    }

    printf("Ciudad: %s Código de País: %s\n", $name, $code);
    ?>

El ejemplo anterior mostrará:

    Ciudad: Benin City Código de País: NGA

### Ver también

- mysqli_prepare() - Prepara una consulta SQL para su ejecución

# mysqli_stmt::$errno

# mysqli_stmt_errno

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$errno -- mysqli_stmt_errno — Devuelve un código de error para la última consulta

### Descripción

Estilo orientado a objetos

int $mysqli_stmt->errno;

Estilo procedimental

function mysqli_stmt_errno(mysqli_stmt `$statement`): int

Devuelve el código de error para la última consulta llamada en el procesamiento que tuvo éxito o falló.

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().

### Valores devueltos

Un valor que representa un código de error. `0` significa que no ocurrió ningún error.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    /* Abre la conexión */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verifica la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    $mysqli->query("CREATE TABLE myCountry LIKE Country");
    $mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = $mysqli->prepare($query)) {

        /* Borrado de la tabla */
        $mysqli->query("DROP TABLE myCountry");

        /* Ejecuta la consulta */
        $stmt->execute();

        printf("Error: %d.\n", $stmt->errno);

        /* Cierra la sentencia */
        $stmt->close();
    }

    /* Cierra la conexión */
    $mysqli->close();
    ?>

Ejemplo #2 Estilo procedimental

    <?php
    /* Abre la conexión */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verifica la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
    mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = mysqli_prepare($link, $query)) {

        /* Borrado de la tabla */
        mysqli_query($link, "DROP TABLE myCountry");

        /* Ejecuta la consulta */
        mysqli_stmt_execute($stmt);

        printf("Error: %d.\n", mysqli_stmt_errno($stmt));

        /* Cierra la sentencia */
        mysqli_stmt_close($stmt);
    }

    /* Cierra la conexión */
    mysqli_close($link);
    ?>

Los ejemplos anteriores mostrarán:

    Error: 1146.

### Ver también

- mysqli_stmt_error() - Devuelve una descripción del último error de procesamiento
- mysqli_stmt_sqlstate() - Devuelve el código SQLSTATE de la última operación MySQL

# mysqli_stmt::$error

# mysqli_stmt_error

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$error -- mysqli_stmt_error — Devuelve una descripción del último error de procesamiento

### Descripción

Estilo orientado a objetos

string $mysqli_stmt->error;

Estilo procedimental

function mysqli_stmt_error(mysqli_stmt `$statement`): string

Devuelve un string que representa el mensaje de error más reciente llamado por una función de procesamiento, haya tenido éxito o no.

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().

### Valores devueltos

Un string que describe el error. Una cadena vacía si no ha ocurrido ningún error.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    /* Abre la conexión */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verifica la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    $mysqli->query("CREATE TABLE myCountry LIKE Country");
    $mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = $mysqli->prepare($query)) {

        /* Borrado de la tabla */
        $mysqli->query("DROP TABLE myCountry");

        /* Ejecuta la consulta */
        $stmt->execute();

        printf("Error: %s.\n", $stmt->error);

        /* Cierra la sentencia */
        $stmt->close();
    }

    /* Cierra la conexión */
    $mysqli->close();
    ?>

Ejemplo #2 Estilo procedimental

    <?php
    /* Abre la conexión */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verifica la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
    mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = mysqli_prepare($link, $query)) {

        /* Borrado de la tabla */
        mysqli_query($link, "DROP TABLE myCountry");

        /* Ejecuta la consulta */
        mysqli_stmt_execute($stmt);

        printf("Error: %s.\n", mysqli_stmt_error($stmt));

        /* Cierra la sentencia */
        mysqli_stmt_close($stmt);
    }

    /* Cierra la conexión */
    mysqli_close($link);
    ?>

Los ejemplos anteriores mostrarán:

    Error: Table 'world.myCountry' doesn't exist.

### Ver también

- mysqli_stmt_errno() - Devuelve un código de error para la última consulta
- mysqli_stmt_sqlstate() - Devuelve el código SQLSTATE de la última operación MySQL

# mysqli_stmt::$error_list

# mysqli_stmt_error_list

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

mysqli_stmt::$error_list -- mysqli_stmt_error_list — Devuelve una lista de errores para la última consulta ejecutada

### Descripción

Estilo orientado a objetos

array $mysqli_stmt->error_list;

Estilo procedimental

function mysqli_stmt_error_list(mysqli_stmt `$statement`): array

Devuelve un array de errores desde la última consulta ejecutada, haya tenido éxito o no.

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().

### Valores devueltos

Una lista de errores, cada uno en forma de array asociativo que contiene el número de error (errno), el mensaje de error (error) y el estado SQL (sqlstate).

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    /* Abre una conexión */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verifica la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo al conectar: %s\n", mysqli_connect_error());
        exit();
    }

    $mysqli->query("CREATE TABLE myCountry LIKE Country");
    $mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = $mysqli->prepare($query)) {

        /* Elimina la tabla */
        $mysqli->query("DROP TABLE myCountry");

        /* Ejecuta la consulta */
        $stmt->execute();

        echo "Error:\n";
        print_r($stmt->error_list);

        /* Cierra la consulta */
        $stmt->close();
    }

    /* Cierra la conexión */
    $mysqli->close();
    ?>

Ejemplo #2 Estilo procedimental

    <?php
    /* Abre una conexión */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verifica la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo al conectar: %s\n", mysqli_connect_error());
        exit();
    }

    mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
    mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = mysqli_prepare($link, $query)) {

        /* Elimina la tabla */
        mysqli_query($link, "DROP TABLE myCountry");

        /* Ejecuta la consulta */
        mysqli_stmt_execute($stmt);

        echo "Error:\n";
        print_r(mysqli_stmt_error_list($stmt));

        /* Cierra la consulta */
        mysqli_stmt_close($stmt);
    }

    /* Cierra la conexión */
    mysqli_close($link);
    ?>

Los ejemplos anteriores mostrarán:

    Error:
    Array
    (
        [0] => Array
            (
                [errno] => 1146
                [sqlstate] => 42S02
                [error] => Table 'world.myCountry' doesn't exist
            )

    )

### Ver también

- mysqli_stmt_error() - Devuelve una descripción del último error de procesamiento
- mysqli_stmt_errno() - Devuelve un código de error para la última consulta
- mysqli_stmt_sqlstate() - Devuelve el código SQLSTATE de la última operación MySQL

# mysqli_stmt::execute

# mysqli_stmt_execute

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::execute -- mysqli_stmt_execute — Ejecuta una consulta preparada

### Descripción

Estilo orientado a objetos

public function mysqli_stmt::execute(?array `$params` = `null`): bool

Estilo procedimental

function mysqli_stmt_execute(mysqli_stmt `$statement`, ?array `$params` = `null`): bool

Ejecuta una consulta que ha sido previamente preparada utilizando la función mysqli_prepare(), gracias al recurso `stmt`. Durante la ejecución, todas las variables de la consulta serán reemplazadas por los datos apropiados.

Si la consulta es `UPDATE`, `DELETE`, o `INSERT`, el número total de filas afectadas está disponible a través de la función mysqli_stmt_affected_rows(). Si la consulta produce un conjunto de resultados, puede ser recuperado utilizando la función mysqli_stmt_get_result() o recuperándolo línea por línea directamente desde la instrucción utilizando la función mysqli_stmt_fetch().

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().
`params`

  Una lista opcional, como array, con tantos elementos como parámetros enlazados haya en la instrucción SQL en curso de ejecución. Cada valor es tratado como una string.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro opcional `params` ha sido añadido.

### Ejemplos

Ejemplo #1 Ejecutar una instrucción preparada con variables enlazadas

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City");

    /* Preparación de la consulta */
    $stmt = $mysqli->prepare("INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)");

    /* Enlazar las variables a los parámetros */
    $stmt->bind_param("sss", $val1, $val2, $val3);
    $val1 = 'Stuttgart';
    $val2 = 'DEU';
    $val3 = 'Baden-Wuerttemberg';

    /* Ejecutar la instrucción */
    $stmt->execute();
    $val1 = 'Bordeaux';
    $val2 = 'FRA';
    $val3 = 'Aquitaine';

    /* Ejecutar la instrucción */
    $stmt->execute();

    /* Recuperación de todas las líneas de myCity */
    $query = "SELECT Name, CountryCode, District FROM myCity";
    $result = $mysqli->query($query);
    while ($row = $result->fetch_row()) {
        printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
    }

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City");

    /* Preparación de la consulta */
    $stmt = mysqli_prepare($link, "INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)");

    /* Enlazar las variables a los parámetros */
    mysqli_stmt_bind_param($stmt, "sss", $val1, $val2, $val3);
    $val1 = 'Stuttgart';
    $val2 = 'DEU';
    $val3 = 'Baden-Wuerttemberg';

    /* Ejecutar la instrucción */
    mysqli_stmt_execute($stmt);
    $val1 = 'Bordeaux';
    $val2 = 'FRA';
    $val3 = 'Aquitaine';

    /* Ejecutar la instrucción */
    mysqli_stmt_execute($stmt);

    /* Recuperación de todas las líneas de myCity */
    $query = "SELECT Name, CountryCode, District FROM myCity";
    $result = mysqli_query($link, $query);
    while ($row = mysqli_fetch_row($result)) {
        printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
    }

Los ejemplos anteriores mostrarán:

    Stuttgart (DEU,Baden-Wuerttemberg)
    Bordeaux (FRA,Aquitaine)

Ejemplo #2 Ejecutar una instrucción preparada con un array de valores

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

    $mysqli->query('CREATE TEMPORARY TABLE myCity LIKE City');

    /* Preparación de la consulta */
    $stmt = $mysqli->prepare('INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)');

    /* Ejecutar la instrucción */
    $stmt->execute(['Stuttgart', 'DEU', 'Baden-Wuerttemberg']);

    /* Recuperación de todas las líneas de myCity */
    $query = 'SELECT Name, CountryCode, District FROM myCity';
    $result = $mysqli->query($query);
    while ($row = $result->fetch_row()) {
        printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
    }

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world');

    mysqli_query($link, 'CREATE TEMPORARY TABLE myCity LIKE City');

    /* Preparación de la consulta */
    $stmt = mysqli_prepare($link, 'INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)');

    /* Ejecutar la instrucción */
    mysqli_stmt_execute($stmt, ['Stuttgart', 'DEU', 'Baden-Wuerttemberg']);

    /* Recuperación de todas las líneas de myCity */
    $query = 'SELECT Name, CountryCode, District FROM myCity';
    $result = mysqli_query($link, $query);
    while ($row = mysqli_fetch_row($result)) {
        printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
    }

Los ejemplos anteriores mostrarán:

    Stuttgart (DEU,Baden-Wuerttemberg)

### Ver también

- mysqli_execute_query() - Prepara, vincula los parámetros y ejecuta una sentencia SQL
- mysqli_prepare() - Prepara una consulta SQL para su ejecución
- mysqli_stmt_bind_param() - Vincula variables a una consulta MySQL
- mysqli_stmt_get_result() - Obtiene un conjunto de resultados desde una consulta preparada como un objeto mysqli_result

# mysqli_stmt::fetch

# mysqli_stmt_fetch

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::fetch -- mysqli_stmt_fetch — Lee los resultados de una consulta MySQL preparada en variables vinculadas

### Descripción

Estilo orientado a objetos

public function mysqli_stmt::fetch(): ?bool

Estilo procedimental

function mysqli_stmt_fetch(mysqli_stmt `$statement`): ?bool

Devuelve el resultado de una consulta preparada en una variable, vinculada por mysqli_stmt_bind_result().

> Nota:

> Tenga en cuenta que todas las columnas deben ser vinculadas por la aplicación antes de llamar a mysqli_stmt_fetch().

> Nota:

> Los datos se transfieren sin ser almacenados en búfer, sin llamar a la función mysqli_stmt_store_result(), lo que puede tener un impacto en el rendimiento (pero también, reducir el uso de memoria).

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().

### Valores devueltos

Valores devueltos
Valor | Descripción
--- | ---
`true` | Éxito. Los datos han sido leídos.
`false` | Se ha producido un error.
`null` | No hay más líneas para leer o los datos han sido truncados.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verifica la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 150,5";

    if ($stmt = $mysqli->prepare($query)) {

        /* Ejecución de la consulta */
        $stmt->execute();

        /* Vinculación de las variables de resultado */
        $stmt->bind_result($name, $code);

        /* Lectura de los valores */
        while ($stmt->fetch()) {
            printf ("%s (%s)\n", $name, $code);
        }

        /* Cierre de la sentencia */
        $stmt->close();
    }

    /* Cierre de la conexión */
    $mysqli->close();
    ?>

Ejemplo #2 Estilo procedimental

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verifica la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 150,5";

    if ($stmt = mysqli_prepare($link, $query)) {

        /* Ejecución de la consulta */
        mysqli_stmt_execute($stmt);

        /* Vinculación de las variables de resultado */
        mysqli_stmt_bind_result($stmt, $name, $code);

        /* Lectura de los valores */
        while (mysqli_stmt_fetch($stmt)) {
            printf ("%s (%s)\n", $name, $code);
        }

        /* Cierre de la sentencia */
        mysqli_stmt_close($stmt);
    }

    /* Cierre de la conexión */
    mysqli_close($link);
    ?>

Los ejemplos anteriores mostrarán:

    Rockford (USA)
    Tallahassee (USA)
    Salinas (USA)
    Santa Clarita (USA)
    Springfield (USA)

### Ver también

- mysqli_prepare() - Prepara una consulta SQL para su ejecución
- mysqli_stmt_errno() - Devuelve un código de error para la última consulta
- mysqli_stmt_error() - Devuelve una descripción del último error de procesamiento
- mysqli_stmt_bind_result() - Vincula variables a un conjunto de resultados

# mysqli_stmt::$field_count

# mysqli_stmt_field_count

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$field_count -- mysqli_stmt_field_count — Devuelve el número de columnas en la consulta dada

### Descripción

Estilo orientado a objetos

int $mysqli_stmt->field_count;

Estilo procedimental

function mysqli_stmt_field_count(mysqli_stmt `$statement`): int

Devuelve el número de columnas en la declaración preparada.

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().

### Valores devueltos

Devuelve un integer que representa el número de columnas.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $code = 'FR';

    $stmt = $mysqli->prepare("SELECT Name FROM Country WHERE Code=?");
    $stmt->bind_param('s', $code);
    $stmt->execute();
    $row = $stmt->get_result()->fetch_row();
    for ($i = 0; $i < $stmt->field_count; $i++) {
        printf("Value of column number %d is %s", $i, $row[$i]);
    }

Ejemplo #2 Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $code = 'FR';

    $stmt = mysqli_prepare($mysqli, "SELECT Name FROM Country WHERE Code=?");
    mysqli_stmt_bind_param($stmt, 's', $code);
    mysqli_stmt_execute($stmt);
    $result = mysqli_stmt_get_result($stmt);
    $row = mysqli_fetch_row($result);
    for ($i = 0; $i < mysqli_stmt_field_count($stmt); $i++) {
        printf("Value of column number %d is %s", $i, $row[$i]);
    }

Los ejemplos anteriores mostrarán algo similar a:

    Value of column number 0 is France

### Ver también

- mysqli_stmt_num_rows() - Devuelve el número de filas recuperadas del servidor

# mysqli_stmt::free_result

# mysqli_stmt_free_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::free_result -- mysqli_stmt_free_result — Libera el resultado MySQL de la memoria

### Descripción

Estilo orientado a objetos

public function mysqli_stmt::free_result(): void

Estilo procedimental

function mysqli_stmt_free_result(mysqli_stmt `$statement`): void

Libera el resultado `stmt` de la memoria. `stmt` ha sido obtenido de la función mysqli_stmt_store_result().

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().

### Valores devueltos

No se retorna ningún valor.

### Ver también

- mysqli_stmt_store_result() - Almacena un conjunto de resultados en un búfer interno

# mysqli_stmt::get_result

# mysqli_stmt_get_result

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_stmt::get_result -- mysqli_stmt_get_result — Obtiene un conjunto de resultados desde una consulta preparada como un objeto mysqli_result

### Descripción

Estilo orientado a objetos

public function mysqli_stmt::get_result(): mysqli_result|false

Estilo procedimental

function mysqli_stmt_get_result(mysqli_stmt `$statement`): mysqli_result|false

Obtiene un conjunto de resultados de una declaración preparada en forma de un objeto mysqli_result. Los datos serán recuperados desde el servidor MySQL hacia PHP. Este método solo debe ser llamado para las consultas que producen un conjunto de resultados.

> Nota:

> Disponible solo con mysqlnd.

> Nota:

> Esta función no puede ser utilizada conjuntamente con la mysqli_stmt_store_result(). Estas dos funciones recuperan el conjunto de resultados completo del servidor MySQL.

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().

### Valores devueltos

Retorna un conjunto de resultados para consultas SELECT exitosas, o `false` para otras consultas DML o en caso de fallo. La función mysqli_errno() puede ser utilizada para distinguir entre estos dos tipos de errores. Retorna `false` en caso de fallo. Para consultas exitosas que producen un conjunto de resultados como `SELECT, SHOW, DESCRIBE` o `EXPLAIN`, mysqli_stmt_get_result() retornará un objeto mysqli_result. Para otros tipos de consultas exitosas, mysqli_stmt_get_result() retornará `false`. La función mysqli_stmt_errno() puede ser utilizada para distinguir entre las dos razones para `false` ; debido a un error, anterior a PHP 7.4.13, mysqli_errno() debía ser utilizada para determinar esto.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, Population, Continent FROM Country WHERE Continent=? ORDER BY Name LIMIT 1";

    $stmt = $mysqli->prepare($query);
    $stmt->bind_param("s", $continent);

    $continentList = array('Europe', 'Africa', 'Asia', 'North America');

    foreach ($continentList as $continent) {
        $stmt->execute();
        $result = $stmt->get_result();
        while ($row = $result->fetch_array(MYSQLI_NUM)) {
            foreach ($row as $r) {
                print "$r ";
            }
            print "\n";
        }
    }
    ?>

Ejemplo #2 Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, Population, Continent FROM Country WHERE Continent=? ORDER BY Name LIMIT 1";

    $stmt = mysqli_prepare($link, $query);
    mysqli_stmt_bind_param($stmt, "s", $continent);

    $continentList= array('Europe', 'Africa', 'Asia', 'North America');

    foreach ($continentList as $continent) {
        mysqli_stmt_execute($stmt);
        $result = mysqli_stmt_get_result($stmt);
        while ($row = mysqli_fetch_array($result, MYSQLI_NUM)) {
            foreach ($row as $r) {
                print "$r ";
            }
            print "\n";
        }
    }
    ?>

Los ejemplos anteriores mostrarán algo similar a:

    Albania 3401200 Europe
    Algeria 31471000 Africa
    Afghanistan 22720000 Asia
    Anguilla 8000 North America

### Ver también

- mysqli_prepare() - Prepara una consulta SQL para su ejecución
- mysqli_stmt_result_metadata() - Devuelve las metadatos de preparación de consulta MySQL
- mysqli_stmt_fetch() - Lee los resultados de una consulta MySQL preparada en variables vinculadas
- mysqli_fetch_array() - Obtiene la siguiente fila de un conjunto de resultados como un array asociativo, numérico o ambos
- mysqli_stmt_store_result() - Almacena un conjunto de resultados en un búfer interno

# mysqli_stmt::get_warnings

# mysqli_stmt_get_warnings

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

mysqli_stmt::get_warnings -- mysqli_stmt_get_warnings — Obtiene el resultado de SHOW WARNINGS

### Descripción

Estilo orientado a objetos

public function mysqli_stmt::get_warnings(): mysqli_warning|false

Estilo procedimental

function mysqli_stmt_get_warnings(mysqli_stmt `$statement`): mysqli_warning|false
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

# mysqli_stmt::$insert_id

# mysqli_stmt_insert_id

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$insert_id -- mysqli_stmt_insert_id — Obtiene el ID generado por la última consulta INSERT

### Descripción

Estilo orientado a objetos

int|string $mysqli_stmt->insert_id;

Estilo procedimental

function mysqli_stmt_insert_id(mysqli_stmt `$statement`): int|string
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

# mysqli_stmt::more_results

# mysqli_stmt_more_results

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_stmt::more_results -- mysqli_stmt_more_results — Comprueba si hay más resultados desde una consulta múltiple

### Descripción

Estilo orientado a objetos

public function mysqli_stmt::more_results(): bool

Estilo procedimental:

function mysqli_stmt_more_results(mysql_stmt `$statement`): bool

Comprueba si hay más resultados desde una consulta múltiple.

> Nota:

> Disponible solo con mysqlnd.

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().

### Valores devueltos

Devuelve `true` si hay más resultados, `false` en caso contrario.

### Ver también

- mysqli_stmt::next_result() - Lee el resultado siguiente desde una consulta múltiple
- mysqli::multi_query() - Ejecuta una o varias consultas en la base de datos

# mysqli_stmt::next_result

# mysqli_stmt_next_result

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_stmt::next_result -- mysqli_stmt_next_result — Lee el resultado siguiente desde una consulta múltiple

### Descripción

Estilo orientado a objetos

public function mysqli_stmt::next_result(): bool

Estilo procedimental:

function mysqli_stmt_next_result(mysql_stmt `$statement`): bool

Lee el resultado siguiente desde una consulta múltiple.

> Nota:

> Anterior a PHP 8.1.0, disponible únicamente con mysqlnd.

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Ahora también disponible al enlazar con libmysqlclient.

### Ver también

- mysqli_stmt::more_results() - Comprueba si hay más resultados desde una consulta múltiple
- mysqli::multi_query() - Ejecuta una o varias consultas en la base de datos

# mysqli_stmt::$num_rows

# mysqli_stmt::num_rows

# mysqli_stmt_num_rows

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$num_rows -- mysqli_stmt::num_rows -- mysqli_stmt_num_rows — Devuelve el número de filas recuperadas del servidor

### Descripción

Estilo orientado a objetos

int|string $mysqli_stmt->num_rows;
public function mysqli_stmt::num_rows(): int|string

Estilo procedimental

function mysqli_stmt_num_rows(mysqli_stmt `$statement`): int|string

Devuelve el número de filas almacenadas en el búfer en la instrucción. Esta función solo funcionará después de llamar a mysqli_stmt_store_result() para almacenar en el búfer el conjunto completo de resultados en el gestor de la instrucción.

Esta función devuelve `0` a menos que todas las filas hayan sido recuperadas del servidor.

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().

### Valores devueltos

Un int que representa el número de filas almacenadas en el búfer. Devuelve `0` en modo no almacenado en búfer, excepto si todas las filas han sido recuperadas del servidor.

> Nota: Si el número de filas es mayor que `PHP_INT_MAX`, el número será devuelto como un string.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";

    $stmt = $mysqli->prepare($query);
    $stmt->execute();

    /* Almacenar el resultado en un búfer interno */
    $stmt->store_result();

    printf("Número de filas: %d.\n", $stmt->num_rows);
    ?>

Ejemplo #2 Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";

    $stmt = mysqli_prepare($link, $query);
    mysqli_stmt_execute($stmt);

    /* Almacenar el resultado en un búfer interno */
    mysqli_stmt_store_result($stmt);

    printf("Número de filas: %d.\n", mysqli_stmt_num_rows($stmt));
    ?>

Los ejemplos anteriores mostrarán:

    Número de filas: 20.

### Ver también

- mysqli_stmt_store_result() - Almacena un conjunto de resultados en un búfer interno
- mysqli_stmt_affected_rows() - Devuelve el número total de filas modificadas, eliminadas, insertadas o coincidentes por la última consulta
- mysqli_prepare() - Prepara una consulta SQL para su ejecución

# mysqli_stmt::$param_count

# mysqli_stmt_param_count

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$param_count -- mysqli_stmt_param_count — Devuelve el número de parámetros de un comando SQL

### Descripción

Estilo orientado a objetos

int $mysqli_stmt->param_count;

Estilo procedimental

function mysqli_stmt_param_count(mysqli_stmt `$statement`): int

Devuelve el número de variables esperadas por el comando preparado `stmt`.

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().

### Valores devueltos

Devuelve un int que representa el número de parámetros.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verifica la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    if ($stmt = $mysqli->prepare("SELECT Name FROM Country WHERE Name=? OR Code=?")) {

        $marker = $stmt->param_count;
        printf("La consulta tiene %d variables.\n", $marker);

        /* Cierre del comando */
        $stmt->close();
    }

    /* Cierre de la conexión */
    $mysqli->close();
    ?>

Ejemplo #2 Estilo procedimental

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verifica la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    if ($stmt = mysqli_prepare($link, "SELECT Name FROM Country WHERE Name=? OR Code=?")) {

        $marker = mysqli_stmt_param_count($stmt);
        printf("La consulta tiene %d variables.\n", $marker);

        /* Cierre del comando */
        mysqli_stmt_close($stmt);
    }

    /* Cierre de la conexión */
    mysqli_close($link);
    ?>

Los ejemplos anteriores mostrarán:

    La consulta tiene 2 variables.

### Ver también

- mysqli_prepare() - Prepara una consulta SQL para su ejecución

# mysqli_stmt::prepare

# mysqli_stmt_prepare

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::prepare -- mysqli_stmt_prepare — Prepara una consulta SQL para su ejecución

### Descripción

Estilo orientado a objetos

public function mysqli_stmt::prepare(string `$query`): mixed

Estilo procedimental

function mysqli_stmt_prepare(mysqli_stmt `$statement`, string `$query`): bool

Prepara la consulta SQL `query`, para la sesión de trabajo `stmt`.

Las variables SQL deben asociarse a una variable PHP mediante la función mysqli_stmt_bind_param() y/o mysqli_stmt_bind_result(), antes de ejecutar la consulta.

> Nota:

> Si se pasa una consulta a mysqli_stmt_prepare() que es más larga que `max_allowed_packet`, los códigos de error devueltos serán diferentes según si se utiliza MySQL Native Driver (`mysqlnd`) o MySQL Client Library (`libmysqlclient`). El comportamiento se define como sigue:

> - `mysqlnd` en Linux devuelve un código de error 1153. El mensaje de error será got a packet bigger than `max_allowed_packet` bytes.

> - `mysqlnd` en Windows devuelve un código de error 2006. El mensaje será del tipo server has gone away.

> - `libmysqlclient` en cualquier plataforma devuelve el código de error 2006. El mensaje será del tipo server has gone away.

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().
`query`

  La consulta, en forma de string. Debe consistir en un comando SQL válido y único.

  Este argumento puede incluir una o más variables SQL, utilizando signos de interrogación (`?`) en los lugares adecuados.

  > Nota:

  > Los marcadores están permitidos únicamente en ciertos lugares de las consultas SQL. Por ejemplo, lo están en la lista `VALUES()` de una consulta `INSERT` (para especificar los valores de las columnas para una fila), o en una comparación de una cláusula `WHERE` para especificar un valor de comparación. Sin embargo, no están permitidos para los identificadores (de tablas o columnas).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Ejemplos

Ejemplo #1 Ejemplo para mysqli_stmt::prepare()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $city = "Amersfoort";

    /* create a prepared statement */
    $stmt = $mysqli->stmt_init();
    $stmt->prepare("SELECT District FROM City WHERE Name=?");

    /* bind parameters for markers */
    $stmt->bind_param("s", $city);

    /* execute query */
    $stmt->execute();

    /* bind result variables */
    $stmt->bind_result($district);

    /* fetch value */
    $stmt->fetch();

    printf("%s is in district %s\n", $city, $district);

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $city = "Amersfoort";

    /* create a prepared statement */
    $stmt = mysqli_stmt_init($link);
    mysqli_stmt_prepare($stmt, "SELECT District FROM City WHERE Name=?");

    /* bind parameters for markers */
    mysqli_stmt_bind_param($stmt, "s", $city);

    /* execute query */
    mysqli_stmt_execute($stmt);

    /* bind result variables */
    mysqli_stmt_bind_result($stmt, $district);

    /* fetch value */
    mysqli_stmt_fetch($stmt);

    printf("%s is in district %s\n", $city, $district);

Los ejemplos anteriores mostrarán:

    Amersfoort is in district Utrecht

### Ver también

- mysqli_stmt_init() - Inicializa una sentencia MySQL
- mysqli_stmt_execute() - Ejecuta una consulta preparada
- mysqli_stmt_fetch() - Lee los resultados de una consulta MySQL preparada en variables vinculadas
- mysqli_stmt_bind_param() - Vincula variables a una consulta MySQL
- mysqli_stmt_bind_result() - Vincula variables a un conjunto de resultados
- mysqli_stmt_get_result() - Obtiene un conjunto de resultados desde una consulta preparada como un objeto mysqli_result
- mysqli_stmt_close() - Termina una consulta preparada

# mysqli_stmt::reset

# mysqli_stmt_reset

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::reset -- mysqli_stmt_reset — Anula una consulta preparada

### Descripción

Estilo orientado a objetos

public function mysqli_stmt::reset(): bool

Estilo procedimental

function mysqli_stmt_reset(mysqli_stmt `$statement`): bool

Anula una consulta preparada en el cliente y en el servidor después de haber sido preparada.

Esta función anula la consulta en el servidor, anula los datos enviados utilizando la función mysqli_stmt_send_long_data(), anula los conjuntos de resultados no almacenados en buffer, así como los errores actuales. Sin embargo, los conjuntos de resultados almacenados o vinculados no se anulan. Los conjuntos de resultados almacenados se borran al ejecutar la consulta preparada (o al cerrarlos).

Para preparar nuevamente una consulta, se debe utilizar la función mysqli_stmt_prepare().

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- mysqli_prepare() - Prepara una consulta SQL para su ejecución

# mysqli_stmt::result_metadata

# mysqli_stmt_result_metadata

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::result_metadata -- mysqli_stmt_result_metadata — Devuelve las metadatos de preparación de consulta MySQL

### Descripción

Estilo orientado a objetos

public function mysqli_stmt::result_metadata(): mysqli_result|false

Estilo procedimental

function mysqli_stmt_result_metadata(mysqli_stmt `$statement`): mysqli_result|false

Si una orden ha sido preparada por mysqli_prepare(), y producirá un resultado, mysqli_stmt_result_metadata() devuelve el objeto de resultado que será utilizado para leer las metadatos, como el número de campos y las informaciones de columnas.

Esta función devuelve un objeto mysqli_result vacío que permite acceder a la información de metadatos de la sentencia preparada sin necesidad de recuperar las filas de datos. No es necesario usar esta función si se utiliza mysqli_stmt_get_result() para recuperar el conjunto de resultados completo de una sentencia preparada como un objeto de resultado.

> Nota:

> Este conjunto de resultados solo se puede pasar como argumento a las funciones basadas en campos para procesar metadatos del conjunto de resultados, tales como:

> - mysqli_num_fields()

> - mysqli_fetch_field()

> - mysqli_fetch_field_direct()

> - mysqli_fetch_fields()

> - mysqli_field_count()

> - mysqli_field_seek()

> - mysqli_field_tell()

> - mysqli_free_result()

> Nota: El conjunto de resultados devuelto por mysqli_stmt_result_metadata() contiene únicamente metadatos. No contiene ninguna fila de resultado. Las filas se obtienen llamando a mysqli_stmt_get_result() en el manejador de la sentencia o con mysqli_stmt_fetch().

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().

### Valores devueltos

Devuelve un objeto de resultados, o `false` si ocurre un error. Si la sentencia no produce un conjunto de resultados, también se devuelve `false`.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    $mysqli->query("DROP TABLE IF EXISTS friends");
    $mysqli->query("CREATE TABLE friends (id int, name varchar(20))");

    $mysqli->query("INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

    $stmt = $mysqli->prepare("SELECT id, name FROM friends");
    $stmt->execute();

    /* Lee las metadatos de resultado */
    $result = $stmt->result_metadata();

    /* Lee las informaciones de un campo, desde las metadatos */
    $field = $result->fetch_field();

    printf("Nombre del campo : %s\n", $field->name);
    ?>

Ejemplo #2 Estilo procedimental

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "test");

    mysqli_query($link, "DROP TABLE IF EXISTS friends");
    mysqli_query($link, "CREATE TABLE friends (id int, name varchar(20))");

    mysqli_query($link, "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

    $stmt = mysqli_prepare($link, "SELECT id, name FROM friends");
    mysqli_stmt_execute($stmt);

    /* Lee las metadatos de resultado */
    $result = mysqli_stmt_result_metadata($stmt);

    /* Lee las informaciones de un campo, desde las metadatos */
    $field = mysqli_fetch_field($result);

    printf("Nombre del campo : %s\n", $field->name);
    ?>

### Ver también

- mysqli_prepare() - Prepara una consulta SQL para su ejecución
- mysqli_free_result() - Libera la memoria asociada a un resultado
- mysqli_stmt_get_result() - Obtiene un conjunto de resultados desde una consulta preparada como un objeto mysqli_result

# mysqli_stmt::send_long_data

# mysqli_stmt_send_long_data

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::send_long_data -- mysqli_stmt_send_long_data — Envía datos MySQL por paquetes

### Descripción

Estilo orientado a objetos

public function mysqli_stmt::send_long_data(int `$param_num`, string `$data`): bool

Estilo procedimental

function mysqli_stmt_send_long_data(mysqli_stmt `$statement`, int `$param_num`, string `$data`): bool

Envía los datos al servidor por paquetes, si el tamaño de los datos excede el límite de `max_allowed_packet`. Esta función puede ser llamada varias veces para enviar los datos de texto o binarios de campos como BLOB o TEXT.

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().
`param_num`

  Indica qué parámetro debe asociarse con qué datos. Los parámetros están numerados a partir de 0.

`data`

  Un string que contiene los datos a enviar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    $stmt = $mysqli->prepare("INSERT INTO messages (message) VALUES (?)");
    $null = NULL;
    $stmt->bind_param("b", $null);
    $fp = fopen("messages.txt", "r");
    while (!feof($fp)) {
        $stmt->send_long_data(0, fread($fp, 8192));
    }
    fclose($fp);
    $stmt->execute();
    ?>

### Ver también

- mysqli_prepare() - Prepara una consulta SQL para su ejecución
- mysqli_stmt_bind_param() - Vincula variables a una consulta MySQL

# mysqli_stmt::$sqlstate

# mysqli_stmt_sqlstate

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$sqlstate -- mysqli_stmt_sqlstate — Devuelve el código SQLSTATE de la última operación MySQL

### Descripción

Estilo orientado a objetos

string $mysqli_stmt->sqlstate;

Estilo procedimental

function mysqli_stmt_sqlstate(mysqli_stmt `$statement`): string

Devuelve un string que contiene el código de error SQLSTATE de la última sentencia preparada. El código de error consta de 5 caracteres `'00000'`. Los valores de los códigos de error están especificados por las normas ANSI SQL y ODBC. Para la lista completa de valores, consulte el archivo » http://dev.mysql.com/doc/mysql/en/error-handling.html.

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().

### Valores devueltos

Devuelve el string que contiene el código de error SQLSTATE. El código de error consta de 5 caracteres. `'00000'` representa la ausencia de error.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    /* Abre la conexión */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verifica la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    $mysqli->query("CREATE TABLE myCountry LIKE Country");
    $mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = $mysqli->prepare($query)) {

        /* Borrado de la tabla */
        $mysqli->query("DROP TABLE myCountry");

        /* Ejecución de la consulta */
        $stmt->execute();

        printf("Error: %s.\n", $stmt->sqlstate);

        /* Cierre de la consulta */
        $stmt->close();
    }

    /* Cierre de la conexión */
    $mysqli->close();
    ?>

Ejemplo #2 Estilo procedimental

    <?php
    /* Abre la conexión */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verifica la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
    mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = mysqli_prepare($link, $query)) {

        /* Borrado de la tabla */
        mysqli_query($link, "DROP TABLE myCountry");

        /* Ejecución de la consulta */
        mysqli_stmt_execute($stmt);

        printf("Error: %s.\n", mysqli_stmt_sqlstate($stmt));

        /* Cierre de la consulta */
        mysqli_stmt_close($stmt);
    }

    /* Cierre de la conexión */
    mysqli_close($link);
    ?>

Los ejemplos anteriores mostrarán:

    Error: 42S02.

### Notas

> Nota:

> Tenga en cuenta que no todos los errores MySQL tienen una correspondencia en SQLSTATE. El valor `HY000` (error general) se utiliza para los errores sin correspondencia.

### Ver también

- mysqli_stmt_errno() - Devuelve un código de error para la última consulta
- mysqli_stmt_error() - Devuelve una descripción del último error de procesamiento

# mysqli_stmt::store_result

# mysqli_stmt_store_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::store_result -- mysqli_stmt_store_result — Almacena un conjunto de resultados en un búfer interno

### Descripción

Estilo orientado a objetos

public function mysqli_stmt::store_result(): bool

Estilo procedimental

function mysqli_stmt_store_result(mysqli_stmt `$statement`): bool

Esta función debería ser llamada para consultas que produzcan un conjunto de resultados (por ejemplo, `SELECT, SHOW, DESCRIBE, EXPLAIN`) solo si el conjunto de resultados completo debe ser almacenado en búfer por PHP. Cada llamada sucesiva a mysqli_stmt_fetch() devolverá los datos almacenados en búfer.

> Nota:

> No es necesario llamar a mysqli_stmt_store_result() para otros tipos de consultas, pero si se hace, no hay problema y no causará ninguna pérdida notable de rendimiento en ningún caso. Puede detectarse en todos los casos si la consulta va a producir un conjunto de resultados observando si la función mysqli_stmt_result_metadata() devuelve `false`.

### Parámetros

`statement`
  Solo estilo procedimental: Un objeto mysqli_stmt devuelto por mysqli_stmt_init().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
    $stmt = $mysqli->prepare($query);
    $stmt->execute();

    /* Almacenar el resultado en un búfer interno */
    $stmt->store_result();

    printf("Número de filas: %d.\n", $stmt->num_rows);

Ejemplo #2 Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
    $stmt = mysqli_prepare($link, $query);
    mysqli_stmt_execute($stmt);

    /* Almacenar el resultado en un búfer interno */
    mysqli_stmt_store_result($stmt);

    printf("Número de filas: %d.\n", mysqli_stmt_num_rows($stmt));

Los ejemplos anteriores mostrarán:

    Número de filas: 20.

### Ver también

- mysqli_prepare() - Prepara una consulta SQL para su ejecución
- mysqli_stmt_result_metadata() - Devuelve las metadatos de preparación de consulta MySQL
- mysqli_stmt_fetch() - Lee los resultados de una consulta MySQL preparada en variables vinculadas

## Tabla de contenidos

- mysqli_stmt::$affected_rows — Devuelve el número total de filas modificadas, eliminadas, insertadas o coincidentes por la última consulta
- mysqli_stmt::attr_get — Obtiene el valor actual de un atributo de consulta
- mysqli_stmt::attr_set — Modifica el comportamiento de una consulta preparada
- mysqli_stmt::bind_param — Vincula variables a una consulta MySQL
- mysqli_stmt::bind_result — Vincula variables a un conjunto de resultados
- mysqli_stmt::close — Termina una consulta preparada
- mysqli_stmt::__construct — Construye un nuevo objeto mysqli_stmt
- mysqli_stmt::data_seek — Ajusta el puntero de resultado a una fila arbitraria en el resultado almacenado en el búfer.
- mysqli_stmt::$errno — Devuelve un código de error para la última consulta
- mysqli_stmt::$error — Devuelve una descripción del último error de procesamiento
- mysqli_stmt::$error_list — Devuelve una lista de errores para la última consulta ejecutada
- mysqli_stmt::execute — Ejecuta una consulta preparada
- mysqli_stmt::fetch — Lee los resultados de una consulta MySQL preparada en variables vinculadas
- mysqli_stmt::$field_count — Devuelve el número de columnas en la consulta dada
- mysqli_stmt::free_result — Libera el resultado MySQL de la memoria
- mysqli_stmt::get_result — Obtiene un conjunto de resultados desde una consulta preparada como un objeto mysqli_result
- mysqli_stmt::get_warnings — Obtiene el resultado de SHOW WARNINGS
- mysqli_stmt::$insert_id — Obtiene el ID generado por la última consulta INSERT
- mysqli_stmt::more_results — Comprueba si hay más resultados desde una consulta múltiple
- mysqli_stmt::next_result — Lee el resultado siguiente desde una consulta múltiple
- mysqli_stmt::$num_rows — Devuelve el número de filas recuperadas del servidor
- mysqli_stmt::$param_count — Devuelve el número de parámetros de un comando SQL
- mysqli_stmt::prepare — Prepara una consulta SQL para su ejecución
- mysqli_stmt::reset — Anula una consulta preparada
- mysqli_stmt::result_metadata — Devuelve las metadatos de preparación de consulta MySQL
- mysqli_stmt::send_long_data — Envía datos MySQL por paquetes
- mysqli_stmt::$sqlstate — Devuelve el código SQLSTATE de la última operación MySQL
- mysqli_stmt::store_result — Almacena un conjunto de resultados en un búfer interno

# La clase mysqli_result

(PHP 5, PHP 7, PHP 8)

## Introducción

Representa el conjunto de resultados obtenido desde una consulta.

## Sinopsis de la Clase

class mysqli_result implements IteratorAggregate {
/* Propiedades */
public readonly int $current_field;
public readonly int $field_count;
public readonly ?array $lengths;
public readonly int|string $num_rows;
public int $type;
/* Métodos */
public function __construct(mysqli `$mysql`, int `$result_mode` = `MYSQLI_STORE_RESULT`)
public function data_seek(int `$offset`): bool
public function fetch_all(int `$mode` = `MYSQLI_NUM`): array
public function fetch_array(int `$mode` = `MYSQLI_BOTH`): array|null|false
public function fetch_assoc(): array|null|false
public function fetch_column(int `$column` = 0): null|int|float|string|false
public function fetch_field(): object|false
public function fetch_field_direct(int `$index`): object|false
public function fetch_fields(): array
public function fetch_object(string `$class` = "stdClass", array `$constructor_args` = []): object|null|false
public function fetch_row(): array|null|false
public function field_seek(int `$index`): true
public function free(): void
public function close(): void
public function free_result(): void
public function getIterator(): Iterator
}

## Propiedades

type

  Registra si el resultado se almacena en el búfer o no en forma de int (`MYSQLI_STORE_RESULT` o `MYSQLI_USE_RESULT`, respectivamente).

## Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | La clase mysqli_result implementa ahora IteratorAggregate. Anteriormente, solo se implementaba Traversable.

# mysqli_result::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_result::__construct — Construye un objeto mysqli_result

### Descripción

public function mysqli_result::__construct(mysqli `$mysql`, int `$result_mode` = `MYSQLI_STORE_RESULT`)

Este método construye un nuevo objeto mysqli_result.

Esto puede ser utilizado para crear el objeto mysqli_result después de haber llamado a las funciones mysqli_real_query() o mysqli_multi_query(). Construir el objeto manualmente es equivalente a llamar a las funciones mysqli_store_result() o mysqli_use_result().

### Parámetros

`mysql`
  Solo estilo procedimental: Un objeto mysqli devuelto por mysqli_connect() o mysqli_init()
`result_mode`

  El modo de resultado puede ser una de las 2 constantes que indican cómo el resultado será devuelto por el servidor MySQL.

  `MYSQLI_STORE_RESULT` (por omisión) - crea un objeto mysqli_result con un juego de resultados almacenado en búfer.

  `MYSQLI_USE_RESULT` - crea un objeto mysqli_result con un juego de resultados no almacenado en búfer. Mientras queden registros pendientes de ser recuperados, la línea de conexión estará ocupada y todas las llamadas siguientes devolverán el error `Commands out of sync`. Para evitar el error, todos los registros deben ser recuperados del servidor o el juego de resultados debe ser descartado llamando a mysqli_free_result(). La conexión debe permanecer abierta para que las líneas sean recuperadas.

### Errores/Excepciones

Si el informe de errores de mysqli está habilitado (`MYSQLI_REPORT_ERROR`) y la operación solicitada falla, se genera una advertencia. Si, además, el modo está configurado como `MYSQLI_REPORT_STRICT`, se lanza una mysqli_sql_exception en su lugar.

### Ejemplos

Ejemplo #1 Creación de un objeto mysqli_result

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Consulta SELECT que devuelve un juego de resultados */
    $mysqli->real_query("SELECT Name FROM City LIMIT 10");

    $result = new mysqli_result($mysqli);
    printf("Select devolvió %d filas.\n", $result->num_rows);

Los ejemplos anteriores mostrarán algo similar a:

    Select devolvió 10 filas.

### Ver también

- mysqli_multi_query() - Ejecuta una o varias consultas en la base de datos
- mysqli_real_query() - Ejecuta una consulta SQL
- mysqli_store_result() - Transfiere un conjunto de resultados desde la última consulta
- mysqli_use_result() - Inicializa la recuperación de un conjunto de resultados

# mysqli_result::$current_field

# mysqli_field_tell

(PHP 5, PHP 7, PHP 8)

mysqli_result::$current_field -- mysqli_field_tell — Obtiene la posición actual de un campo en un puntero de resultado

### Descripción

Estilo orientado a objetos

int $mysqli_result->current_field;

Estilo procedimental

function mysqli_field_tell(mysqli_result `$result`): int

Devuelve la posición del cursor de campo utilizado por la última llamada a la función mysqli_fetch_field(). Este valor puede ser utilizado como argumento de la función mysqli_field_seek().

### Parámetros

`result`
  Solo estilo procedimental: Un objeto mysqli_result devuelto por mysqli_query(), mysqli_store_result(), mysqli_use_result() o mysqli_stmt_get_result().

### Valores devueltos

Devuelve la posición actual del cursor de campo.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verificación de la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = $mysqli->query($query)) {

        /* Obtención de información sobre el campo para todas las columnas */
        while ($finfo = $result->fetch_field()) {

            /* Obtención de la posición del puntero de campo */
            $currentfield = $result->current_field;

            printf("Columna %d:\n", $currentfield);
            printf("Nombre: %s\n", $finfo->name);
            printf("Tabla: %s\n", $finfo->table);
            printf("Longitud máx.: %d\n", $finfo->max_length);
            printf("Flags: %d\n", $finfo->flags);
            printf("Tipo: %d\n\n", $finfo->type);
        }
        $result->close();
    }

    /* Cierre de la conexión */
    $mysqli->close();
    ?>

Ejemplo #2 Estilo procedimental

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verificación de la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Obtención de información sobre el campo para todas las columnas */
        while ($finfo = mysqli_fetch_field($result)) {

            /* Obtención de la posición del puntero de campo */
            $currentfield = mysqli_field_tell($result);

            printf("Columna %d:\n", $currentfield);
            printf("Nombre: %s\n", $finfo->name);
            printf("Tabla: %s\n", $finfo->table);
            printf("Longitud máx.: %d\n", $finfo->max_length);
            printf("Flags: %d\n", $finfo->flags);
            printf("Tipo: %d\n\n", $finfo->type);
        }
        mysqli_free_result($result);
    }

    /* Cierre de la conexión */
    mysqli_close($link);
    ?>

Los ejemplos anteriores mostrarán:

    Columna 1:
    Nombre: Name
    Tabla: Country
    Longitud máx.: 11
    Flags: 1
    Tipo: 254

    Columna 2:
    Nombre: SurfaceArea
    Tabla: Country
    Longitud máx.: 10
    Flags: 32769
    Tipo: 4

### Ver también

- mysqli_fetch_field() - Devuelve el siguiente campo en el conjunto de resultados
- mysqli_field_seek() - Desplaza el puntero de resultado al campo especificado

# mysqli_result::data_seek

# mysqli_data_seek

(PHP 5, PHP 7, PHP 8)

mysqli_result::data_seek -- mysqli_data_seek — Mueve el puntero interno de resultado

### Descripción

Estilo orientado a objetos

public function mysqli_result::data_seek(int `$offset`): bool

Estilo procedimental

function mysqli_data_seek(mysqli_result `$result`, int `$offset`): bool

La función mysqli_data_seek() mueve el puntero interno de resultado asociado al conjunto de resultados representado por `result`, haciéndolo apuntar a la fila especificada por `offset`.

### Parámetros

`result`
  Solo estilo procedimental: Un objeto mysqli_result devuelto por mysqli_query(), mysqli_store_result(), mysqli_use_result() o mysqli_stmt_get_result().
`offset`

  El desplazamiento de la fila. El parámetro `offset` debe estar comprendido entre cero y mysqli_num_rows() - 1 (0..mysqli_num_rows() - 1).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con mysqli::data_seek()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name";
    $result = $mysqli->query($query);

    /* Busca la fila 401 */
    $result->data_seek(400);

    /* Obtención de esta fila */
    $row = $result->fetch_row();
    printf("Ciudad: %s  Código País: %s\n", $row[0], $row[1]);
    ?>

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name";
    $result = mysqli_query($link, $query);

    /* Busca la fila 401 */
    mysqli_data_seek($result, 400);

    /* Obtención de esta fila */
    $row = mysqli_fetch_row($result);
    printf("Ciudad: %s  Código País: %s\n", $row[0], $row[1]);

Los ejemplos anteriores mostrarán:

    Ciudad: Benin City  Código País: NGA

Ejemplo #2 Ajuste del puntero de resultado durante la iteración

Esta función puede ser útil durante la iteración sobre el conjunto de resultados para imponer un orden personalizado o para rebobinar el conjunto de resultados durante iteraciones múltiples.

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 15,4";
    $result = $mysqli->query($query);

    /* Consultar el conjunto de resultados en orden inverso */
    for ($row_no = $result->num_rows - 1; $row_no >= 0; $row_no--) {
        $result->data_seek($row_no);

        /* Obtención de esta fila */
        $row = $result->fetch_row();
        printf("Ciudad: %s  Código País: %s\n", $row[0], $row[1]);
    }

    /* Restablecer el puntero al inicio del conjunto de resultados */
    $result->data_seek(0);
    print "\n";

    /* Consultar nuevamente el mismo conjunto de resultados */
    while ($row = $result->fetch_row()) {
        printf("Ciudad: %s  Código País: %s\n", $row[0], $row[1]);
    }

Los ejemplos anteriores mostrarán:

    Ciudad: Acmbaro  Código País: MEX
    Ciudad: Abuja  Código País: NGA
    Ciudad: Abu Dhabi  Código País: ARE
    Ciudad: Abottabad  Código País: PAK
    Ciudad: Abottabad  Código País: PAK
    Ciudad: Abu Dhabi  Código País: ARE
    Ciudad: Abuja  Código País: NGA
    Ciudad: Acmbaro  Código País: MEX

### Notas

> Nota:

> Esta función solo puede ser utilizada con resultados obtenidos con la función mysqli_store_result(), mysqli_query() o mysqli_stmt_get_result().

### Ver también

- mysqli_store_result() - Transfiere un conjunto de resultados desde la última consulta
- mysqli_fetch_row() - Obtiene una fila de resultado como un array indexado
- mysqli_fetch_array() - Obtiene la siguiente fila de un conjunto de resultados como un array asociativo, numérico o ambos
- mysqli_fetch_assoc() - Recupera la siguiente fila de un conjunto de resultados como un array asociativo
- mysqli_fetch_object() - Devuelve la siguiente fila de un conjunto de resultados como objeto
- mysqli_query() - Ejecuta una consulta en la base de datos
- mysqli_num_rows() - Devuelve el número de filas en el conjunto de resultados

# mysqli_result::fetch_all

# mysqli_fetch_all

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_result::fetch_all -- mysqli_fetch_all — Recupera todas las filas de resultados en un array asociativo, numérico o ambos

### Descripción

Estilo orientado a objetos

public function mysqli_result::fetch_all(int `$mode` = `MYSQLI_NUM`): array

Estilo procedimental

function mysqli_fetch_all(mysqli_result `$result`, int `$mode` = `MYSQLI_NUM`): array

Devuelve un array bidimensional de todos los resultados en forma de un array asociativo, numérico o ambos.

> Nota:

> Anterior a PHP 8.1.0, disponible únicamente con mysqlnd.

### Parámetros

`result`
  Solo estilo procedimental: Un objeto mysqli_result devuelto por mysqli_query(), mysqli_store_result(), mysqli_use_result() o mysqli_stmt_get_result().
`mode`

  Este argumento opcional es una constante que indica el tipo de array que debe ser producido a partir del resultado. Los valores posibles son las constantes `MYSQLI_ASSOC`, `MYSQLI_NUM`, o `MYSQLI_BOTH`.

### Valores devueltos

Devuelve un array asociativo o numérico que contiene las filas de resultado.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Ahora también disponible al vincular con libmysqlclient.

### Ejemplos

Ejemplo #1 Ejemplo de mysqli_result::fetch_all()

Estilo orientado a objetos

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");
    $result = $mysqli->query("SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3");
    $rows = $result->fetch_all(MYSQLI_ASSOC);
    foreach ($rows as $row) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Estilo procedimental

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");
    $result = mysqli_query($mysqli, "SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3");
    $rows = mysqli_fetch_all($result, MYSQLI_ASSOC);
    foreach ($rows as $row) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Los ejemplos anteriores mostrarán:

    Kabul (AFG)
    Qandahar (AFG)
    Herat (AFG)

### Ver también

- mysqli_fetch_array() - Obtiene la siguiente fila de un conjunto de resultados como un array asociativo, numérico o ambos
- mysqli_fetch_column() - Recupera una sola columna de la siguiente fila de un conjunto de resultados
- mysqli_query() - Ejecuta una consulta en la base de datos

# mysqli_result::fetch_array

# mysqli_fetch_array

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_array -- mysqli_fetch_array — Obtiene la siguiente fila de un conjunto de resultados como un array asociativo, numérico o ambos

### Descripción

Estilo orientado a objetos

public function mysqli_result::fetch_array(int `$mode` = `MYSQLI_BOTH`): array|null|false

Estilo procedimental

function mysqli_fetch_array(mysqli_result `$result`, int `$mode` = `MYSQLI_BOTH`): array|null|false

Devuelve una fila de datos del conjunto de resultados y la retorna como un array. Cada llamada posterior a esta función retornará la siguiente fila en el conjunto de resultados, o `null` si no hay más filas.

Además de almacenar los datos como un array con índices numéricos, también puede almacenarlos en un array asociativo, utilizando los nombres de los campos como claves.

Si dos o más columnas del resultado tienen el mismo nombre, la última columna tendrá prioridad y sobrescribirá todos los datos anteriores. Para acceder a las otras columnas con el mismo nombre, se debe utilizar el índice numérico o crear un alias para cada columna.

> Nota: Los nombres de los campos devueltos por esta función son sensibles a la case.

> Nota: Esta función define los campos NULL al valor PHP `null`.

### Parámetros

`result`
  Solo estilo procedimental: Un objeto mysqli_result devuelto por mysqli_query(), mysqli_store_result(), mysqli_use_result() o mysqli_stmt_get_result().
`mode`

  El segundo argumento opcional es una constante que indica qué tipo de array debe ser retornado a partir de la fila de datos actual. Los valores posibles para este parámetro son las constantes `MYSQLI_ASSOC`, `MYSQLI_NUM`, y `MYSQLI_BOTH`.

  Al utilizar la constante `MYSQLI_ASSOC`, esta función se comportará como la función mysqli_fetch_assoc(), mientras que `MYSQLI_NUM` hará que actúe como la función mysqli_fetch_row(). La constante `MYSQLI_BOTH` creará un array que será tanto asociativo como indexado numéricamente.

### Valores devueltos

Retorna un array que representa la fila recuperada, `null` si no hay más filas en el conjunto de resultados, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de mysqli_result::fetch_array()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3";
    $result = $mysqli->query($query);

    /* Array numérico */
    $row = $result->fetch_array(MYSQLI_NUM);
    printf("%s (%s)\n", $row[0], $row[1]);

    /* Array asociativo */
    $row = $result->fetch_array(MYSQLI_ASSOC);
    printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);

    /* Array asociativo y numérico */
    $row = $result->fetch_array(MYSQLI_BOTH);
    printf("%s (%s)\n", $row[0], $row["CountryCode"]);

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER by ID LIMIT 3";
    $result = mysqli_query($mysqli, $query);

    /* Array numérico */
    $row = mysqli_fetch_array($result, MYSQLI_NUM);
    printf("%s (%s)\n", $row[0], $row[1]);

    /* Array asociativo */
    $row = mysqli_fetch_array($result, MYSQLI_ASSOC);
    printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);

    /* Array asociativo y numérico */
    $row = mysqli_fetch_array($result, MYSQLI_BOTH);
    printf("%s (%s)\n", $row[0], $row["CountryCode"]);

Los ejemplos anteriores mostrarán algo similar a:

    Kabul (AFG)
    Qandahar (AFG)
    Herat (AFG)

### Ver también

- mysqli_fetch_assoc() - Recupera la siguiente fila de un conjunto de resultados como un array asociativo
- mysqli_fetch_column() - Recupera una sola columna de la siguiente fila de un conjunto de resultados
- mysqli_fetch_row() - Obtiene una fila de resultado como un array indexado
- mysqli_fetch_object() - Devuelve la siguiente fila de un conjunto de resultados como objeto
- mysqli_query() - Ejecuta una consulta en la base de datos
- mysqli_data_seek() - Mueve el puntero interno de resultado

# mysqli_result::fetch_assoc

# mysqli_fetch_assoc

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_assoc -- mysqli_fetch_assoc — Recupera la siguiente fila de un conjunto de resultados como un array asociativo

### Descripción

Estilo orientado a objetos

public function mysqli_result::fetch_assoc(): array|null|false

Estilo procedimental

function mysqli_fetch_assoc(mysqli_result `$result`): array|null|false

Devuelve una fila de datos del conjunto de resultados y la retorna como un array asociativo. Cada llamada posterior a esta función retornará la siguiente fila en el conjunto de resultados, o `null` si no hay más filas.

Si dos o más columnas del resultado tienen el mismo nombre, la última columna tendrá prioridad y sobrescribirá todos los datos anteriores. Para acceder a múltiples columnas con el mismo nombre, puede utilizarse mysqli_fetch_row() para recuperar el array indexado numéricamente o pueden utilizarse alias en la lista de selección de la consulta SQL para dar nombres diferentes a las columnas.

> Nota: Los nombres de los campos devueltos por esta función son sensibles a la case.

> Nota: Esta función define los campos NULL al valor PHP `null`.

### Parámetros

`result`
  Solo estilo procedimental: Un objeto mysqli_result devuelto por mysqli_query(), mysqli_store_result(), mysqli_use_result() o mysqli_stmt_get_result().

### Valores devueltos

Devuelve un array asociativo que representa la fila recuperada, donde cada clave del array representa el nombre de una de las columnas del conjunto de resultados, `null` si no hay más filas en el conjunto de resultados, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo mysqli_result::fetch_assoc()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = $mysqli->query($query);

    /* fetch associative array */
    while ($row = $result->fetch_assoc()) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = mysqli_query($mysqli, $query);

    /* fetch associative array */
    while ($row = mysqli_fetch_assoc($result)) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Los ejemplos anteriores mostrarán algo similar a:

    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

Ejemplo #2 Comparación del uso de mysqli_result iterator y mysqli_result::fetch_assoc()

mysqli_result puede ser iterado utilizando un `foreach`. El conjunto de resultados siempre será iterado desde la primera fila, independientemente de la posición actual.

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = 'SELECT Name, CountryCode FROM City ORDER BY ID DESC';

    // Utiliza un iterador
    $result = $mysqli->query($query);
    foreach ($result as $row) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

    echo "\n==================\n";

    // No utiliza iterador
    $result = $mysqli->query($query);
    while ($row = $result->fetch_assoc()) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Resultado del ejemplo anterior es similar a:

    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

    ==================
    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

### Ver también

- mysqli_fetch_array() - Obtiene la siguiente fila de un conjunto de resultados como un array asociativo, numérico o ambos
- mysqli_fetch_column() - Recupera una sola columna de la siguiente fila de un conjunto de resultados
- mysqli_fetch_row() - Obtiene una fila de resultado como un array indexado
- mysqli_fetch_object() - Devuelve la siguiente fila de un conjunto de resultados como objeto
- mysqli_query() - Ejecuta una consulta en la base de datos
- mysqli_data_seek() - Mueve el puntero interno de resultado

# mysqli_result::fetch_column

# mysqli_fetch_column

(PHP 8 >= 8.1.0)

mysqli_result::fetch_column -- mysqli_fetch_column — Recupera una sola columna de la siguiente fila de un conjunto de resultados

### Descripción

Estilo orientado a objetos

public function mysqli_result::fetch_column(int `$column` = 0): null|int|float|string|false

Estilo procedimental

function mysqli_fetch_column(mysqli_result `$result`, int `$column` = 0): null|int|float|string|false

Recupera una fila de datos del conjunto de resultados y devuelve la columna indexada a 0. Cada llamada posterior a esta función devolverá el valor de la siguiente fila del conjunto de resultados, o `false` si no hay más filas.

> Nota: Esta función define los campos NULL al valor PHP `null`.

### Parámetros

`result`
  Solo estilo procedimental: Un objeto mysqli_result devuelto por mysqli_query(), mysqli_store_result(), mysqli_use_result() o mysqli_stmt_get_result().
`column`

  El número indexado a 0 de la columna que se desea recuperar de la fila. Si no se proporciona ningún valor, se devolverá la primera columna.

### Valores devueltos

Devuelve una sola columna de la siguiente fila de un conjunto de resultados o `false` si no hay más filas.

Advertencia

No hay forma de devolver otra columna de la misma fila si se utiliza esta función para recuperar datos.

### Ejemplos

Ejemplo #1 Ejemplo de mysqli_result::fetch_column()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT CountryCode, Name FROM City ORDER BY ID DESC LIMIT 5";

    $result = $mysqli->query($query);

    /* Recupera un solo valor de la segunda columna */
    while ($Name = $result->fetch_column(1)) {
        printf("%s\n", $Name);
    }

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT CountryCode, Name FROM City ORDER BY ID DESC LIMIT 5";

    $result = mysqli_query($mysqli, $query);

    /* Recupera un solo valor de la segunda columna */
    while ($Name = mysqli_fetch_column($result, 1)) {
        printf("%s\n", $Name);
    }

Los ejemplos anteriores mostrarán algo similar a:

    Rafah
    Nablus
    Jabaliya
    Hebron
    Khan Yunis

### Ver también

- mysqli_fetch_all() - Recupera todas las filas de resultados en un array asociativo, numérico o ambos
- mysqli_fetch_array() - Obtiene la siguiente fila de un conjunto de resultados como un array asociativo, numérico o ambos
- mysqli_fetch_assoc() - Recupera la siguiente fila de un conjunto de resultados como un array asociativo
- mysqli_fetch_object() - Devuelve la siguiente fila de un conjunto de resultados como objeto
- mysqli_fetch_row() - Obtiene una fila de resultado como un array indexado
- mysqli_data_seek() - Mueve el puntero interno de resultado

# mysqli_result::fetch_field

# mysqli_fetch_field

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_field -- mysqli_fetch_field — Devuelve el siguiente campo en el conjunto de resultados

### Descripción

Estilo orientado a objetos

public function mysqli_result::fetch_field(): object|false

Estilo procedimental

function mysqli_fetch_field(mysqli_result `$result`): object|false

Devuelve los atributos de la siguiente columna en el conjunto de resultados representado por el parámetro `result` como un objeto. Llame a esta función de forma repetitiva para recuperar la información de todas las columnas.

### Parámetros

`result`
  Solo estilo procedimental: Un objeto mysqli_result devuelto por mysqli_query(), mysqli_store_result(), mysqli_use_result() o mysqli_stmt_get_result().

### Valores devueltos

Devuelve un objeto que contiene la información de un campo o `false` si no hay información disponible para este campo.

Propiedades del objeto
Propiedad | Descripción
--- | ---
name | El nombre de la columna
orgname | El nombre original de la columna si se ha especificado un alias
table | El nombre de la tabla a la que pertenece este campo (si no ha sido calculado)
orgtable | El nombre original de la tabla si se ha especificado un alias
def | No utilizado. Siempre una string vacía
db | El nombre de la base de datos
catalog | No utilizado. Siempre `"def"`
max_length | La longitud máxima del campo para el conjunto de resultados. A partir de PHP 8.1, este valor es siempre `0`.
length | El ancho del campo en bytes. Para las columnas de tipo string, el valor de longitud varía en función del juego de caracteres de la conexión. Por ejemplo, si el juego de caracteres es `latin1`, un juego de caracteres de un byte, el valor de longitud para una consulta `SELECT 'abc'` es 3. Si el juego de caracteres es `utf8mb4`, un juego de caracteres multibyte en el que los caracteres ocupan hasta 4 bytes, el valor de longitud es 12.
charsetnr | El número del juego de caracteres para este campo
flags | Un integer que representa los bit-flags para este campo
type | El tipo de datos utilizados para este campo
decimals | El número de decimales para los campos numéricos y la precisión de los segundos fraccionarios para los campos temporales.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verificación de la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = $mysqli->query($query)) {

        /* Recupera la información de un campo para todas las columnas */
        while ($finfo = $result->fetch_field()) {

            printf("Name:     %s\n", $finfo->name);
            printf("Table:    %s\n", $finfo->table);
            printf("max. Len: %d\n", $finfo->max_length);
            printf("Flags:    %d\n", $finfo->flags);
            printf("Type:     %d\n\n", $finfo->type);
        }
        $result->close();
    }

    /* Cierre de la conexión */
    $mysqli->close();
    ?>

Ejemplo #2 Estilo procedimental

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verificación de la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Recupera la información de un campo para todas las columnas */
        while ($finfo = mysqli_fetch_field($result)) {

            printf("Name:     %s\n", $finfo->name);
            printf("Table:    %s\n", $finfo->table);
            printf("max. Len: %d\n", $finfo->max_length);
            printf("Flags:    %d\n", $finfo->flags);
            printf("Type:     %d\n\n", $finfo->type);
        }
        mysqli_free_result($result);
    }

    /* Cierre de la conexión */
    mysqli_close($link);
    ?>

Los ejemplos anteriores mostrarán:

    Name:     Name
    Table:    Country
    max. Len: 11
    Flags:    1
    Type:     254

    Name:     SurfaceArea
    Table:    Country
    max. Len: 10
    Flags:    32769
    Type:     4

### Ver también

- mysqli_num_fields() - Obtiene el número de campos en el conjunto de resultados
- mysqli_fetch_field_direct() - Obtiene los metadatos de un campo único
- mysqli_fetch_fields() - Devuelve un array de objetos que representan los campos en el resultado
- mysqli_field_seek() - Desplaza el puntero de resultado al campo especificado

# mysqli_result::fetch_field_direct

# mysqli_fetch_field_direct

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_field_direct -- mysqli_fetch_field_direct — Obtiene los metadatos de un campo único

### Descripción

Estilo orientado a objetos

public function mysqli_result::fetch_field_direct(int `$index`): object|false

Estilo procedimental

function mysqli_fetch_field_direct(mysqli_result `$result`, int `$index`): object|false

Devuelve un objeto que contiene los metadatos de un campo en el conjunto de resultados especificado.

### Parámetros

`result`
  Solo estilo procedimental: Un objeto mysqli_result devuelto por mysqli_query(), mysqli_store_result(), mysqli_use_result() o mysqli_stmt_get_result().
`index`

  El número del campo. Este valor debe estar en el intervalo `0` a `número de campos - 1`.

### Valores devueltos

Devuelve un objeto que contiene los metadatos de un campo o `false` si no se especifican metadatos para el campo `index`.

Propiedades del objeto
Propiedad | Descripción
--- | ---
name | El nombre de la columna
orgname | El nombre original de la columna si se ha especificado un alias
table | El nombre de la tabla a la que pertenece este campo (si no ha sido calculado)
orgtable | El nombre original de la tabla si se ha especificado un alias
def | No utilizado. Siempre una string vacía
db | El nombre de la base de datos
catalog | No utilizado. Siempre `"def"`
max_length | La longitud máxima del campo para el conjunto de resultados. A partir de PHP 8.1, este valor es siempre `0`.
length | El ancho del campo en bytes. Para las columnas de tipo string, el valor de longitud varía en función del juego de caracteres de la conexión. Por ejemplo, si el juego de caracteres es `latin1`, un juego de caracteres de un byte, el valor de longitud para una consulta `SELECT 'abc'` es 3. Si el juego de caracteres es `utf8mb4`, un juego de caracteres multibyte en el que los caracteres ocupan hasta 4 bytes, el valor de longitud es 12.
charsetnr | El número del juego de caracteres para este campo
flags | Un integer que representa los bit-flags para este campo
type | El tipo de datos utilizados para este campo
decimals | El número de decimales para los campos numéricos y la precisión de los segundos fraccionarios para los campos temporales.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verificación de la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Name LIMIT 5";

    if ($result = $mysqli->query($query)) {

        /* Obtener información del campo para la columna 'SurfaceArea' */
        $finfo = $result->fetch_field_direct(1);

        printf("Nombre      : %s\n", $finfo->name);
        printf("Tabla       : %s\n", $finfo->table);
        printf("Tamaño máx : %d\n", $finfo->max_length);
        printf("Flags       : %d\n", $finfo->flags);
        printf("Tipo        : %d\n", $finfo->type);

        $result->close();
    }

    /* Cierre de la conexión */
    $mysqli->close();
    ?>

Ejemplo #2 Estilo procedimental

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verificación de la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Name LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Obtener información del campo para la columna 'SurfaceArea' */
        $finfo = mysqli_fetch_field_direct($result, 1);

        printf("Nombre      : %s\n", $finfo->name);
        printf("Tabla       : %s\n", $finfo->table);
        printf("Tamaño máx : %d\n", $finfo->max_length);
        printf("Flags       : %d\n", $finfo->flags);
        printf("Tipo        : %d\n", $finfo->type);

        mysqli_free_result($result);
    }

    /* Cierre de la conexión */
    mysqli_close($link);
    ?>

Los ejemplos anteriores mostrarán:

    Nombre      : SurfaceArea
    Tabla       : Country
    Tamaño máx : 10
    Flags       : 32769
    Tipo        : 4

### Ver también

- mysqli_num_fields() - Obtiene el número de campos en el conjunto de resultados
- mysqli_fetch_field() - Devuelve el siguiente campo en el conjunto de resultados
- mysqli_fetch_fields() - Devuelve un array de objetos que representan los campos en el resultado

# mysqli_result::fetch_fields

# mysqli_fetch_fields

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_fields -- mysqli_fetch_fields — Devuelve un array de objetos que representan los campos en el resultado

### Descripción

Estilo orientado a objetos

public function mysqli_result::fetch_fields(): array

Estilo procedimental

function mysqli_fetch_fields(mysqli_result `$result`): array

Esta función opera como mysqli_fetch_field() con la diferencia de que, en lugar de devolver un objeto a la vez para cada campo, las columnas son devueltas como un array de objetos.

### Parámetros

`result`
  Solo estilo procedimental: Un objeto mysqli_result devuelto por mysqli_query(), mysqli_store_result(), mysqli_use_result() o mysqli_stmt_get_result().

### Valores devueltos

Devuelve un array de objetos que contiene información sobre la definición de los campos.

Propiedades del objeto
Propiedad | Descripción
--- | ---
name | El nombre de la columna
orgname | El nombre original de la columna si se ha especificado un alias
table | El nombre de la tabla a la que pertenece este campo (si no ha sido calculado)
orgtable | El nombre original de la tabla si se ha especificado un alias
def | No utilizado. Siempre una string vacía
db | El nombre de la base de datos
catalog | No utilizado. Siempre `"def"`
max_length | La longitud máxima del campo para el conjunto de resultados. A partir de PHP 8.1, este valor es siempre `0`.
length | El ancho del campo en bytes. Para las columnas de tipo string, el valor de longitud varía en función del juego de caracteres de la conexión. Por ejemplo, si el juego de caracteres es `latin1`, un juego de caracteres de un byte, el valor de longitud para una consulta `SELECT 'abc'` es 3. Si el juego de caracteres es `utf8mb4`, un juego de caracteres multibyte en el que los caracteres ocupan hasta 4 bytes, el valor de longitud es 12.
charsetnr | El número del juego de caracteres para este campo
flags | Un integer que representa los bit-flags para este campo
type | El tipo de datos utilizados para este campo
decimals | El número de decimales para los campos numéricos y la precisión de los segundos fraccionarios para los campos temporales.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("127.0.0.1", "root", "foofoo", "sakila");

    /* verificación de la conexión */
    if ($mysqli->connect_errno) {
        printf("Fallo en la conexión: %s\n", $mysqli->connect_error);
        exit();
    }

    foreach (array('latin1', 'utf8') as $charset) {

        // Establecer el juego de caracteres, para mostrar su impacto en ciertos valores (por ejemplo, longitudes en bytes)
        $mysqli->set_charset($charset);

        $query = "SELECT actor_id, last_name from actor ORDER BY actor_id";

        echo "============================\n";
        echo "Juego de caracteres: $charset\n";
        echo "============================\n";

        if ($result = $mysqli->query($query)) {

            /* Obtiene la información de los campos para todas las columnas */
            $finfo = $result->fetch_fields();

            foreach ($finfo as $val) {
                printf("Name:      %s\n",   $val->name);
                printf("Table:     %s\n",   $val->table);
                printf("Max. Len:  %d\n",   $val->max_length);
                printf("Length:    %d\n",   $val->length);
                printf("charsetnr: %d\n",   $val->charsetnr);
                printf("Flags:     %d\n",   $val->flags);
                printf("Type:      %d\n\n", $val->type);
            }
            $result->free();
        }
    }
    $mysqli->close();
    ?>

Ejemplo #2 Estilo procedimental

    <?php
    $link = mysqli_connect("127.0.0.1", "my_user", "my_password", "sakila");

    /* verificación de la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    foreach (array('latin1', 'utf8') as $charset) {

        // Establecer el juego de caracteres, para mostrar su impacto en ciertos valores (por ejemplo, longitudes en bytes)
        mysqli_set_charset($link, $charset);

        $query = "SELECT actor_id, last_name from actor ORDER BY actor_id";

        echo "============================\n";
        echo "Juego de caracteres: $charset\n";
        echo "============================\n";

        if ($result = mysqli_query($link, $query)) {

            /* Obtiene la información de los campos para todas las columnas */
            $finfo = mysqli_fetch_fields($result);

            foreach ($finfo as $val) {
                printf("Name:      %s\n",   $val->name);
                printf("Table:     %s\n",   $val->table);
                printf("Max. Len:  %d\n",   $val->max_length);
                printf("Length:    %d\n",   $val->length);
                printf("charsetnr: %d\n",   $val->charsetnr);
                printf("Flags:     %d\n",   $val->flags);
                printf("Type:      %d\n\n", $val->type);
            }
            mysqli_free_result($result);
        }
    }

    mysqli_close($link);
    ?>

Los ejemplos anteriores mostrarán:

    ============================
    Juego de caracteres: latin1
    ============================
    Name:      actor_id
    Table:     actor
    Max. Len:  3
    Length:    5
    charsetnr: 63
    Flags:     49699
    Type:      2

    Name:      last_name
    Table:     actor
    Max. Len:  12
    Length:    45
    charsetnr: 8
    Flags:     20489
    Type:      253

    ============================
    Juego de caracteres: utf8
    ============================
    Name:      actor_id
    Table:     actor
    Max. Len:  3
    Length:    5
    charsetnr: 63
    Flags:     49699
    Type:      2

    Name:      last_name
    Table:     actor
    Max. Len:  12
    Length:    135
    charsetnr: 33
    Flags:     20489

### Ver también

- mysqli_num_fields() - Obtiene el número de campos en el conjunto de resultados
- mysqli_fetch_field_direct() - Obtiene los metadatos de un campo único
- mysqli_fetch_field() - Devuelve el siguiente campo en el conjunto de resultados

# mysqli_result::fetch_object

# mysqli_fetch_object

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_object -- mysqli_fetch_object — Devuelve la siguiente fila de un conjunto de resultados como objeto

### Descripción

Estilo orientado a objetos

public function mysqli_result::fetch_object(string `$class` = "stdClass", array `$constructor_args` = []): object|null|false

Estilo procedimental

function mysqli_fetch_object(mysqli_result `$result`, string `$class` = "stdClass", array `$constructor_args` = []): object|null|false

Devuelve una fila de datos en el conjunto de resultados y la retorna como objeto, donde cada propiedad representa el nombre de la columna del conjunto de resultados. Cada llamada posterior a esta función retornará la siguiente fila en el conjunto de resultados, o `null` si no hay más filas.

Si dos o más columnas del resultado tienen el mismo nombre, la última columna tendrá prioridad y sobrescribirá todos los datos anteriores. Para acceder a múltiples columnas con el mismo nombre, la mysqli_fetch_row() puede ser utilizada para recuperar el array indexado numéricamente o se pueden usar alias en la lista de selección de la consulta SQL para dar nombres diferentes a las columnas.

> Nota: Esta función afecta las propiedades del objeto antes de llamar a su constructor.

> Nota: Los nombres de los campos devueltos por esta función son sensibles a la case.

> Nota: Esta función define los campos NULL al valor PHP `null`.

### Parámetros

`result`
  Solo estilo procedimental: Un objeto mysqli_result devuelto por mysqli_query(), mysqli_store_result(), mysqli_use_result() o mysqli_stmt_get_result().
`class`

  El nombre de la clase a instanciar. Si no se proporciona, se retornará un objeto stdClass.

`constructor_args`

  Un array de argumentos (opcional) a pasar al constructor de la clase `class`.

### Valores devueltos

Retorna un objeto que representa la fila recuperada, donde cada propiedad representa el nombre de la columna del conjunto de resultados, `null` si no hay más filas en el conjunto de resultados, o `false` si ocurre un error.

### Errores/Excepciones

Se lanza una ValueError cuando `constructor_args` no está vacío y la clase no tiene constructor.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Ahora se lanza una excepción ValueError cuando `constructor_args` no está vacío y la clase no tiene constructor; anteriormente, se lanzaba una excepción Exception.
8.0.0 | `constructor_args` ahora acepta `[]` para constructores con 0 parámetros; antes se lanzaba una excepción.

### Ejemplos

Ejemplo #1 Ejemplo mysqli_result::fetch_object()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = $mysqli->query($query);

    while ($obj = $result->fetch_object()) {
        printf("%s (%s)\n", $obj->Name, $obj->CountryCode);
    }

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = mysqli_query($link, $query);

    while ($obj = mysqli_fetch_object($result)) {
        printf("%s (%s)\n", $obj->Name, $obj->CountryCode);
    }

Los ejemplos anteriores mostrarán algo similar a:

    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

### Ver también

- mysqli_fetch_array() - Obtiene la siguiente fila de un conjunto de resultados como un array asociativo, numérico o ambos
- mysqli_fetch_assoc() - Recupera la siguiente fila de un conjunto de resultados como un array asociativo
- mysqli_fetch_column() - Recupera una sola columna de la siguiente fila de un conjunto de resultados
- mysqli_fetch_row() - Obtiene una fila de resultado como un array indexado
- mysqli_query() - Ejecuta una consulta en la base de datos
- mysqli_data_seek() - Mueve el puntero interno de resultado

# mysqli_result::fetch_row

# mysqli_fetch_row

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_row -- mysqli_fetch_row — Obtiene una fila de resultado como un array indexado

### Descripción

Estilo orientado a objetos

public function mysqli_result::fetch_row(): array|null|false

Estilo procedimental

function mysqli_fetch_row(mysqli_result `$result`): array|null|false

Obtiene una fila de datos del conjunto de resultados representado por `result` y la devuelve como un array indexado, donde cada columna es un elemento del array, comenzando en 0 (cero). Cada nueva llamada a mysqli_fetch_row() devolverá la siguiente fila en el conjunto de resultados, o `null` si no hay más filas.

> Nota: Esta función define los campos NULL al valor PHP `null`.

### Parámetros

`result`
  Solo estilo procedimental: Un objeto mysqli_result devuelto por mysqli_query(), mysqli_store_result(), mysqli_use_result() o mysqli_stmt_get_result().

### Valores devueltos

Devuelve un array enumerado que representa la fila obtenida, `null` si no hay más filas en el conjunto de resultados, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo mysqli_result::fetch_row()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = $mysqli->query($query);

    /* Obtiene un array de objetos */
    while ($row = $result->fetch_row()) {
        printf("%s (%s)\n", $row[0], $row[1]);
    }

Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = mysqli_query($mysqli, $query);

    /* Obtiene un array asociativo */
    while ($row = mysqli_fetch_row($result)) {
        printf("%s (%s)\n", $row[0], $row[1]);
    }

Los ejemplos anteriores mostrarán algo similar a:

    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

### Ver también

- mysqli_fetch_array() - Obtiene la siguiente fila de un conjunto de resultados como un array asociativo, numérico o ambos
- mysqli_fetch_assoc() - Recupera la siguiente fila de un conjunto de resultados como un array asociativo
- mysqli_fetch_column() - Recupera una sola columna de la siguiente fila de un conjunto de resultados
- mysqli_fetch_object() - Devuelve la siguiente fila de un conjunto de resultados como objeto
- mysqli_query() - Ejecuta una consulta en la base de datos
- mysqli_data_seek() - Mueve el puntero interno de resultado

# mysqli_result::$field_count

# mysqli_num_fields

(PHP 5, PHP 7, PHP 8)

mysqli_result::$field_count -- mysqli_num_fields — Obtiene el número de campos en el conjunto de resultados

### Descripción

Estilo orientado a objetos

int $mysqli_result->field_count;

Estilo procedimental

function mysqli_num_fields(mysqli_result `$result`): int

Devuelve el número de campos en el conjunto de resultados.

### Parámetros

`result`
  Solo estilo procedimental: Un objeto mysqli_result devuelto por mysqli_query(), mysqli_store_result(), mysqli_use_result() o mysqli_stmt_get_result().

### Valores devueltos

Un int que representa el número de campos.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $result = $mysqli->query("SELECT Name, CountryCode, District, Population FROM City ORDER BY ID LIMIT 1");

    /* Determina el número de campos en el conjunto de resultados */
    $field_cnt = $result->field_count;

    printf("El resultado tiene %d campos.\n", $field_cnt);
    ?>

Ejemplo #2 Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $result = mysqli_query($link, "SELECT Name, CountryCode, District, Population FROM City ORDER BY ID LIMIT 1");

    /* Determina el número de campos en el conjunto de resultados */
    $field_cnt = mysqli_num_fields($result);

    printf("El resultado tiene %d campos.\n", $field_cnt);
    ?>

Los ejemplos anteriores mostrarán:

    El resultado tiene 4 campos.

### Ver también

- mysqli_fetch_field() - Devuelve el siguiente campo en el conjunto de resultados

# mysqli_result::field_seek

# mysqli_field_seek

(PHP 5, PHP 7, PHP 8)

mysqli_result::field_seek -- mysqli_field_seek — Desplaza el puntero de resultado al campo especificado

### Descripción

Estilo orientado a objetos

public function mysqli_result::field_seek(int `$index`): true

Estilo procedimental

function mysqli_field_seek(mysqli_result `$result`, int `$index`): true

Coloca el cursor en el campo especificado por el número `index`. La próxima llamada a la función mysqli_fetch_field() devolverá la definición del campo de la columna asociada a esta posición.

> Nota:

> Para moverse al inicio de una fila, pase una posición con valor cero.

### Parámetros

`result`
  Solo estilo procedimental: Un objeto mysqli_result devuelto por mysqli_query(), mysqli_store_result(), mysqli_use_result() o mysqli_stmt_get_result().
`index`

  El número del campo. Este valor debe estar en el intervalo `0` a `número de campos - 1`.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función devuelve ahora siempre `true`. Anteriormente, devolvía `false` en caso de fallo.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verificación de la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = $mysqli->query($query)) {

        /* Obtención de información del campo para la 2ª columna */
        $result->field_seek(1);
        $finfo = $result->fetch_field();

        printf("Name:     %s\n", $finfo->name);
        printf("Table:    %s\n", $finfo->table);
        printf("max. Len: %d\n", $finfo->max_length);
        printf("Flags:    %d\n", $finfo->flags);
        printf("Type:     %d\n\n", $finfo->type);

        $result->close();
    }

    /* Cierra la conexión */
    $mysqli->close();
    ?>

Ejemplo #2 Estilo procedimental

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verificación de la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Obtención de información del campo para la 2ª columna */
        mysqli_field_seek($result, 1);
        $finfo = mysqli_fetch_field($result);

        printf("Name:     %s\n", $finfo->name);
        printf("Table:    %s\n", $finfo->table);
        printf("max. Len: %d\n", $finfo->max_length);
        printf("Flags:    %d\n", $finfo->flags);
        printf("Type:     %d\n\n", $finfo->type);

        mysqli_free_result($result);
    }

    /* Cierra la conexión */
    mysqli_close($link);
    ?>

Los ejemplos anteriores mostrarán:

    Name:     SurfaceArea
    Table:    Country
    max. Len: 10
    Flags:    32769
    Type:     4

### Ver también

- mysqli_fetch_field() - Devuelve el siguiente campo en el conjunto de resultados

# mysqli_result::free

# mysqli_result::close

# mysqli_result::free_result

# mysqli_free_result

(PHP 5, PHP 7, PHP 8)

mysqli_result::free -- mysqli_result::close -- mysqli_result::free_result -- mysqli_free_result — Libera la memoria asociada a un resultado

### Descripción

Estilo orientado a objetos

public function mysqli_result::free(): void
public function mysqli_result::close(): void
public function mysqli_result::free_result(): void

Estilo procedimental

function mysqli_free_result(mysqli_result `$result`): void

Libera la memoria asociada a un resultado.

### Parámetros

`result`
  Solo estilo procedimental: Un objeto mysqli_result devuelto por mysqli_query(), mysqli_store_result(), mysqli_use_result() o mysqli_stmt_get_result().

### Valores devueltos

No se retorna ningún valor.

### Ver también

- mysqli_query() - Ejecuta una consulta en la base de datos
- mysqli_stmt_get_result() - Obtiene un conjunto de resultados desde una consulta preparada como un objeto mysqli_result
- mysqli_store_result() - Transfiere un conjunto de resultados desde la última consulta
- mysqli_use_result() - Inicializa la recuperación de un conjunto de resultados

# mysqli_result::getIterator

(PHP 8)

mysqli_result::getIterator — Devuelve un iterador externo

### Descripción

public function mysqli_result::getIterator(): Iterator

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# mysqli_result::$lengths

# mysqli_fetch_lengths

(PHP 5, PHP 7, PHP 8)

mysqli_result::$lengths -- mysqli_fetch_lengths — Devuelve la longitud de las columnas de la fila actual del conjunto de resultados

### Descripción

Estilo orientado a objetos

?array $mysqli_result->lengths;

Estilo procedimental

function mysqli_fetch_lengths(mysqli_result `$result`): array|false

La función mysqli_fetch_lengths() devuelve un array que contiene la longitud de cada columna de la fila actual del conjunto de resultados representado por el argumento `result`.

### Parámetros

`result`
  Solo estilo procedimental: Un objeto mysqli_result devuelto por mysqli_query(), mysqli_store_result(), mysqli_use_result() o mysqli_stmt_get_result().

### Valores devueltos

Un array de integers que representan el tamaño de cada columna (sin incluir ningún carácter null de final). Devuelve `false` si ocurre un error.

mysqli_fetch_lengths() solo es válido para la fila actual del conjunto de resultados. Devuelve `false` si se llama antes de las funciones mysqli_fetch_row(), mysqli_fetch_array(), mysqli_fetch_object() o después de haber recuperado todas las filas del resultado.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "mon_user", "mon_mot_de_passe", "la_base");

    /* Verificación de la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT * from Country ORDER BY Code LIMIT 1";

    if ($result = $mysqli->query($query)) {

        $row = $result->fetch_row();

        /* Visualización de la longitud de las columnas */
        foreach ($result->lengths as $i => $val) {
            printf("El campo n°%2d tiene una longitud de %2d\n", $i+1, $val);
        }
        $result->close();
    }

    /* Cierra la conexión */
    $mysqli->close();
    ?>

Ejemplo #2 Estilo procedimental

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verificación de la conexión */
    if (mysqli_connect_errno()) {
        printf("Fallo en la conexión: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT * from Country ORDER BY Code LIMIT 1";

    if ($result = mysqli_query($link, $query)) {

        $row = mysqli_fetch_row($result);

        /* Visualización de la longitud de las columnas */
        foreach (mysqli_fetch_lengths($result) as $i => $val) {
            printf("El campo n°%2d tiene una longitud de %2d\n", $i+1, $val);
        }
        mysqli_free_result($result);
    }

    /* Cierra la conexión */
    mysqli_close($link);
    ?>

Los ejemplos anteriores mostrarán:

    El campo n° 1 tiene una longitud de  3
    El campo n° 2 tiene una longitud de  5
    El campo n° 3 tiene una longitud de 13
    El campo n° 4 tiene una longitud de  9
    El campo n° 5 tiene una longitud de  6
    El campo n° 6 tiene una longitud de  1
    El campo n° 7 tiene una longitud de  6
    El campo n° 8 tiene una longitud de  4
    El campo n° 9 tiene una longitud de  6
    El campo n°10 tiene una longitud de  6
    El campo n°11 tiene una longitud de  5
    El campo n°12 tiene una longitud de 44
    El campo n°13 tiene una longitud de  7
    El campo n°14 tiene una longitud de  3
    El campo n°15 tiene una longitud de  2

# mysqli_result::$num_rows

# mysqli_num_rows

(PHP 5, PHP 7, PHP 8)

mysqli_result::$num_rows -- mysqli_num_rows — Devuelve el número de filas en el conjunto de resultados

### Descripción

Estilo orientado a objetos

int|string $mysqli_result->num_rows;

Estilo procedimental

function mysqli_num_rows(mysqli_result `$result`): int|string

Devuelve el número de filas en un conjunto de resultados.

El comportamiento de mysqli_num_rows() depende del uso de conjuntos de resultados almacenados en búfer o no. Esta función devuelve `0` para conjuntos de resultados no almacenados en búfer, a menos que todas las filas hayan sido recuperadas del servidor.

### Parámetros

`result`
  Solo estilo procedimental: Un objeto mysqli_result devuelto por mysqli_query(), mysqli_store_result(), mysqli_use_result() o mysqli_stmt_get_result().

### Valores devueltos

Un int que representa el número de filas recuperadas. Devuelve `0` en modo no almacenado en búfer, a menos que todas las filas hayan sido recuperadas desde el servidor.

> Nota: Si el número de filas es mayor que `PHP_INT_MAX`, el número será devuelto como un string.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $result = $mysqli->query("SELECT Code, Name FROM Country ORDER BY Name");

    /* Determina el número de filas del conjunto de resultados */
    $row_cnt = $result->num_rows;

    printf("El conjunto de resultados tiene %d filas.\n", $row_cnt);

Ejemplo #2 Estilo procedimental

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $result = mysqli_query($link, "SELECT Code, Name FROM Country ORDER BY Name");

    /* Determina el número de filas del conjunto de resultados */
    $row_cnt = mysqli_num_rows($result);

    printf("El conjunto de resultados tiene %d filas.\n", $row_cnt);
    ?>

Los ejemplos anteriores mostrarán:

    El conjunto de resultados tiene 239 filas.

### Notas

> Nota:

> A diferencia de la función mysqli_stmt_num_rows(), esta función no tiene una variante de método orientado a objetos. En el estilo orientado a objetos, se debe utilizar el getter de la propiedad.

### Ver también

- mysqli_affected_rows() - Devuelve el número de filas afectadas por la última operación MySQL
- mysqli_store_result() - Transfiere un conjunto de resultados desde la última consulta
- mysqli_use_result() - Inicializa la recuperación de un conjunto de resultados
- mysqli_query() - Ejecuta una consulta en la base de datos
- mysqli_stmt_num_rows() - Devuelve el número de filas recuperadas del servidor

## Tabla de contenidos

- mysqli_result::__construct — Construye un objeto mysqli_result
- mysqli_result::$current_field — Obtiene la posición actual de un campo en un puntero de resultado
- mysqli_result::data_seek — Mueve el puntero interno de resultado
- mysqli_result::fetch_all — Recupera todas las filas de resultados en un array asociativo, numérico o ambos
- mysqli_result::fetch_array — Obtiene la siguiente fila de un conjunto de resultados como un array asociativo, numérico o ambos
- mysqli_result::fetch_assoc — Recupera la siguiente fila de un conjunto de resultados como un array asociativo
- mysqli_result::fetch_column — Recupera una sola columna de la siguiente fila de un conjunto de resultados
- mysqli_result::fetch_field — Devuelve el siguiente campo en el conjunto de resultados
- mysqli_result::fetch_field_direct — Obtiene los metadatos de un campo único
- mysqli_result::fetch_fields — Devuelve un array de objetos que representan los campos en el resultado
- mysqli_result::fetch_object — Devuelve la siguiente fila de un conjunto de resultados como objeto
- mysqli_result::fetch_row — Obtiene una fila de resultado como un array indexado
- mysqli_result::$field_count — Obtiene el número de campos en el conjunto de resultados
- mysqli_result::field_seek — Desplaza el puntero de resultado al campo especificado
- mysqli_result::free — Libera la memoria asociada a un resultado
- mysqli_result::getIterator — Devuelve un iterador externo
- mysqli_result::$lengths — Devuelve la longitud de las columnas de la fila actual del conjunto de resultados
- mysqli_result::$num_rows — Devuelve el número de filas en el conjunto de resultados

# La clase mysqli_driver

(PHP 5, PHP 7, PHP 8)

## Introducción

La clase mysqli_driver es una instancia del patrón monostate, es decir, solo hay un driver que puede ser accedido a través de un número arbitrario de instancias mysqli_driver.

## Sinopsis de la Clase

final class mysqli_driver {
/* Propiedades */
public readonly string $client_info;
public readonly int $client_version;
public readonly int $driver_version;
public int $report_mode;
}

## Propiedades

client_info

  La versión del encabezado de la API del cliente

client_version

  La versión del cliente

driver_version

  La versión del driver MySQLi

  Advertencia

  Esta propiedad está obsoleta a partir de PHP 8.1.0. Se desaconseja encarecidamente depender de esta propiedad.

embedded

  Si el soporte "MySQLi Embedded" está activado

  Advertencia

  Esta propiedad ha sido eliminada a partir de PHP 8.0.0.

reconnect

  Permite o no la reconexión (ver la directiva INI mysqli.reconnect)

  Advertencia

  Esta propiedad ha sido eliminada junto con la directiva INI mysqli.reconnect a partir de PHP 8.2.0.

report_mode

  Se establece en `MYSQLI_REPORT_OFF`, `MYSQLI_REPORT_ALL` o cualquier combinación de `MYSQLI_REPORT_STRICT` (lanza excepciones en caso de errores), `MYSQLI_REPORT_ERROR` (reporta errores) y `MYSQLI_REPORT_INDEX` (errores en los índices). Ver también mysqli_report().

## Historial de cambios

Versión | Descripción
--- | ---
8.2.0 | mysqli_driver::$reconnect fue eliminada.
8.1.0 | mysqli_driver::$driver_version ha sido marcada como obsoleta.
8.0.0 | mysqli_driver::$embedded fue eliminada.
7.4.0 | mysqli_driver::embedded_server_start() y mysqli_driver:embedded_server_end() fueron eliminadas.

# mysqli_driver::embedded_server_end

# mysqli_embedded_server_end

(PHP 5 >= 5.1.0, PHP 7 < 7.4.0)

mysqli_driver::embedded_server_end -- mysqli_embedded_server_end — Detiene el servidor embebido

Advertencia

Esta función ha sido ELIMINADA a partir de PHP 7.4.0.

### Descripción

Estilo orientado a objetos

public function mysqli_driver::embedded_server_end(): void

Estilo procedimental

function mysqli_embedded_server_end(): void
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

# mysqli_driver::embedded_server_start

# mysqli_embedded_server_start

(PHP 5 >= 5.1.0, PHP 7 < 7.4.0)

mysqli_driver::embedded_server_start -- mysqli_embedded_server_start — Inicializa e inicia el servidor embebido

Advertencia

Esta función ha sido ELIMINADA a partir de PHP 7.4.0.

### Descripción

Estilo orientado a objetos

public function mysqli_driver::embedded_server_start(int `$start`, array `$arguments`, array `$groups`): bool

Estilo procedimental

function mysqli_embedded_server_start(int `$start`, array `$arguments`, array `$groups`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

# mysqli_driver::$report_mode

# mysqli_report

(PHP 5, PHP 7, PHP 8)

mysqli_driver::$report_mode -- mysqli_report — Define el modo de informe de errores de mysqli

### Descripción

Estilo orientado a objetos

int $mysqli_driver->report_mode;

Estilo procedimental

function mysqli_report(int `$flags`): true

Según los flags, esto define el modo de informe de errores de mysqli a excepción, advertencia o ninguno. Cuando se define como `MYSQLI_REPORT_ALL` o `MYSQLI_REPORT_INDEX` esto también informará sobre consultas que no utilizan un índice (o un índice incorrecto).

A partir de PHP 8.1.0, el valor por omisión es `MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT`. Anteriormente, era `MYSQLI_REPORT_OFF`.

### Parámetros

`flags`

  Flags admitidos
  Nombre | Descripción
  --- | ---
  `MYSQLI_REPORT_OFF` | Desactiva los informes (valor por omisión)
  `MYSQLI_REPORT_ERROR` | Informa sobre errores desde llamadas a funciones mysqli
  `MYSQLI_REPORT_STRICT` | Lanza una excepción mysqli_sql_exception para errores, en lugar de emitir alertas
  `MYSQLI_REPORT_INDEX` | Informa si no se utiliza ningún índice o un índice incorrecto en una consulta
  `MYSQLI_REPORT_ALL` | Define todas las opciones (informa sobre todo)

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El valor por omisión es ahora `MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT`. Anteriormente, era `MYSQLI_REPORT_OFF`.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php

    /* Activación del informe de errores */
    $driver = new mysqli_driver();
    $driver->report_mode = MYSQLI_REPORT_ALL;

    try {
        /* si la conexión falla, se lanzará una mysqli_sql_exception */
        $mysqli = new mysqli("localhost", "my_user", "my_password", "my_db");

        /* esta consulta debería informar sobre un error */
        $result = $mysqli->query("SELECT Name FROM Nonexistingtable WHERE population > 50000");

        /* esta consulta debería informar sobre un índice incorrecto, si la columna population no tiene un índice */
        $result = $mysqli->query("SELECT Name FROM City WHERE population > 50000");
    } catch (mysqli_sql_exception $e) {
        error_log($e->__toString());
    }

Ejemplo #2 Estilo procedimental

    <?php

    /* Activación del informe de errores */
    mysqli_report(MYSQLI_REPORT_ALL);

    try {
        /* si la conexión falla, se lanzará una excepción mysqli_sql_exception */
        $link = mysqli_connect("localhost", "my_user", "my_password", "my_db");

        /* esta consulta debería informar sobre un error */
        $result = mysqli_query($link, "SELECT Name FROM Nonexistingtable WHERE population > 50000");

        /* esta consulta debería informar sobre un índice incorrecto, si la columna population no tiene un índice */
        $result = mysqli_query($link, "SELECT Name FROM City WHERE population > 50000");
    } catch (mysqli_sql_exception $e) {
        error_log($e->__toString());
    }

Ejemplo #3 Informe de errores a excepción de errores de índice incorrecto

    <?php

    /* Activación del informe de errores */
    $driver = new mysqli_driver();
    $driver->report_mode = MYSQLI_REPORT_ALL;

    try {
        /* si la conexión falla, se lanzará una mysqli_sql_exception */
        $mysqli = new mysqli("localhost", "my_user", "my_password", "my_db");

        /* esta consulta debería informar sobre un error */
        $result = $mysqli->query("SELECT Name FROM Nonexistingtable WHERE population > 50000");

        /* esto NO emitirá un error incluso si no hay ningún índice disponible */
        $result = $mysqli->query("SELECT Name FROM City WHERE population > 50000");
    } catch (mysqli_sql_exception $e) {
        error_log($e->__toString());
    }

### Ver también

- mysqli_sql_exception
- set_exception_handler() - Define una función de usuario para gestionar excepciones
- error_reporting() - Establece el nivel de reporte de errores de PHP

## Tabla de contenidos

- mysqli_driver::embedded_server_end — Detiene el servidor embebido
- mysqli_driver::embedded_server_start — Inicializa e inicia el servidor embebido
- mysqli_driver::$report_mode — Define el modo de informe de errores de mysqli

# La clase mysqli_warning

(PHP 5, PHP 7, PHP 8)

## Introducción

Representa una advertencia de MySQL.

## Sinopsis de la Clase

final class mysqli_warning {
/* Propiedades */
public string $message;
public string $sqlstate;
public int $errno;
/* Métodos */
private function __construct()
public function next(): bool
}

## Propiedades

message

  El mensaje

sqlstate

  El estado SQL

errno

  El número del error

# mysqli_warning::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_warning::__construct — Constructor privado para evitar la instanciación directa

### Descripción

private function mysqli_warning::__construct()

### Parámetros

Esta función no contiene ningún parámetro.

# mysqli_warning::next

(PHP 5, PHP 7, PHP 8)

mysqli_warning::next — Obtiene el siguiente aviso

### Descripción

public function mysqli_warning::next(): bool

Modifica la información del aviso al siguiente aviso si es posible.

Una vez que el aviso se ha establecido en el siguiente aviso, nuevos valores para las propiedades `message`, `sqlstate` y `errno` de mysqli_warning están disponibles.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Retorna `true` si el siguiente aviso se ha recuperado con éxito. Si no hay más avisos, retornará `false`.

## Tabla de contenidos

- mysqli_warning::__construct — Constructor privado para evitar la instanciación directa
- mysqli_warning::next — Obtiene el siguiente aviso

# La clase mysqli_sql_exception

(PHP 5, PHP 7, PHP 8)

## Introducción

La clase de gestión de excepciones mysqli.

## Sinopsis de la Clase

final class mysqli_sql_exception extends RuntimeException {
/* Propiedades */
protected string $sqlstate = "00000";
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
public function getSqlState(): string
/* Métodos heredados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propiedades

sqlstate

  El estado SQL con el error.

# mysqli_sql_exception::getSqlState

(PHP 8 >= 8.1.2)

mysqli_sql_exception::getSqlState — Devuelve el código de error SQLSTATE

### Descripción

public function mysqli_sql_exception::getSqlState(): string

Devuelve un string que contiene el código de error SQLSTATE para el último error. El código de error está compuesto por cinco caracteres. Los valores están especificados por ANSI SQL y ODBC. Para una lista de los valores posibles, ver » http://dev.mysql.com/doc/mysql/en/error-handling.html.

> Nota:

> Cabe señalar que no todos los errores de MySQL están mapeados a SQLSTATE. El valor `HY000` (error general) se utiliza para los errores no mapeados.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un string que contiene el código de error SQLSTATE para el último error. El código de error está compuesto por cinco caracteres.

## Tabla de contenidos

- mysqli_sql_exception::getSqlState — Devuelve el código de error SQLSTATE

# Funciones mysqli obsoletas y alias

# mysqli_connect

(PHP 5, PHP 7, PHP 8)

mysqli_connect — Alias de mysqli::__construct()

### Descripción

Esta función es un alias de: mysqli::__construct()

> Nota:

> Si el modo de excepción mysqli no está activado y una conexión falla, entonces mysqli_connect() retorna `false` en lugar de un objeto. La función mysqli_connect_error() puede ser utilizada para recuperar el error de conexión.

# mysqli::escape_string

# mysqli_escape_string

(PHP 5, PHP 7, PHP 8)

mysqli::escape_string -- mysqli_escape_string — Alias de mysqli_real_escape_string()

### Descripción

Esta función es un alias de: mysqli_real_escape_string().

# mysqli_execute

(PHP 5, PHP 7, PHP 8)

mysqli_execute — Alias de mysqli_stmt_execute()

Advertencia

Esta función está OBSOLETA a partir de PHP 8.5.0. Depender de esta función está altamente desaconsejado.

### Descripción

Esta función es un alias de: mysqli_stmt_execute().

### Ver también

- mysqli_stmt_execute() - Ejecuta una consulta preparada

# mysqli_get_client_stats

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_get_client_stats — Devuelve las estadísticas del cliente por proceso

### Descripción

function mysqli_get_client_stats(): array

Devuelve las estadísticas del cliente por proceso.

> Nota:

> Disponible solo con mysqlnd.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array con las estadísticas del cliente.

### Ejemplos

Ejemplo #1 Un ejemplo con mysqli_get_client_stats()

    <?php
    $link = mysqli_connect();
    print_r(mysqli_get_client_stats());
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [bytes_sent] => 43
        [bytes_received] => 80
        [packets_sent] => 1
        [packets_received] => 2
        [protocol_overhead_in] => 8
        [protocol_overhead_out] => 4
        [bytes_received_ok_packet] => 11
        [bytes_received_eof_packet] => 0
        [bytes_received_rset_header_packet] => 0
        [bytes_received_rset_field_meta_packet] => 0
        [bytes_received_rset_row_packet] => 0
        [bytes_received_prepare_response_packet] => 0
        [bytes_received_change_user_packet] => 0
        [packets_sent_command] => 0
        [packets_received_ok] => 1
        [packets_received_eof] => 0
        [packets_received_rset_header] => 0
        [packets_received_rset_field_meta] => 0
        [packets_received_rset_row] => 0
        [packets_received_prepare_response] => 0
        [packets_received_change_user] => 0
        [result_set_queries] => 0
        [non_result_set_queries] => 0
        [no_index_used] => 0
        [bad_index_used] => 0
        [slow_queries] => 0
        [buffered_sets] => 0
        [unbuffered_sets] => 0
        [ps_buffered_sets] => 0
        [ps_unbuffered_sets] => 0
        [flushed_normal_sets] => 0
        [flushed_ps_sets] => 0
        [ps_prepared_never_executed] => 0
        [ps_prepared_once_executed] => 0
        [rows_fetched_from_server_normal] => 0
        [rows_fetched_from_server_ps] => 0
        [rows_buffered_from_client_normal] => 0
        [rows_buffered_from_client_ps] => 0
        [rows_fetched_from_client_normal_buffered] => 0
        [rows_fetched_from_client_normal_unbuffered] => 0
        [rows_fetched_from_client_ps_buffered] => 0
        [rows_fetched_from_client_ps_unbuffered] => 0
        [rows_fetched_from_client_ps_cursor] => 0
        [rows_skipped_normal] => 0
        [rows_skipped_ps] => 0
        [copy_on_write_saved] => 0
        [copy_on_write_performed] => 0
        [command_buffer_too_small] => 0
        [connect_success] => 1
        [connect_failure] => 0
        [connection_reused] => 0
        [reconnect] => 0
        [pconnect_success] => 0
        [active_connections] => 1
        [active_persistent_connections] => 0
        [explicit_close] => 0
        [implicit_close] => 0
        [disconnect_close] => 0
        [in_middle_of_command_close] => 0
        [explicit_free_result] => 0
        [implicit_free_result] => 0
        [explicit_stmt_close] => 0
        [implicit_stmt_close] => 0
        [mem_emalloc_count] => 0
        [mem_emalloc_ammount] => 0
        [mem_ecalloc_count] => 0
        [mem_ecalloc_ammount] => 0
        [mem_erealloc_count] => 0
        [mem_erealloc_ammount] => 0
        [mem_efree_count] => 0
        [mem_malloc_count] => 0
        [mem_malloc_ammount] => 0
        [mem_calloc_count] => 0
        [mem_calloc_ammount] => 0
        [mem_realloc_count] => 0
        [mem_realloc_ammount] => 0
        [mem_free_count] => 0
        [proto_text_fetched_null] => 0
        [proto_text_fetched_bit] => 0
        [proto_text_fetched_tinyint] => 0
        [proto_text_fetched_short] => 0
        [proto_text_fetched_int24] => 0
        [proto_text_fetched_int] => 0
        [proto_text_fetched_bigint] => 0
        [proto_text_fetched_decimal] => 0
        [proto_text_fetched_float] => 0
        [proto_text_fetched_double] => 0
        [proto_text_fetched_date] => 0
        [proto_text_fetched_year] => 0
        [proto_text_fetched_time] => 0
        [proto_text_fetched_datetime] => 0
        [proto_text_fetched_timestamp] => 0
        [proto_text_fetched_string] => 0
        [proto_text_fetched_blob] => 0
        [proto_text_fetched_enum] => 0
        [proto_text_fetched_set] => 0
        [proto_text_fetched_geometry] => 0
        [proto_text_fetched_other] => 0
        [proto_binary_fetched_null] => 0
        [proto_binary_fetched_bit] => 0
        [proto_binary_fetched_tinyint] => 0
        [proto_binary_fetched_short] => 0
        [proto_binary_fetched_int24] => 0
        [proto_binary_fetched_int] => 0
        [proto_binary_fetched_bigint] => 0
        [proto_binary_fetched_decimal] => 0
        [proto_binary_fetched_float] => 0
        [proto_binary_fetched_double] => 0
        [proto_binary_fetched_date] => 0
        [proto_binary_fetched_year] => 0
        [proto_binary_fetched_time] => 0
        [proto_binary_fetched_datetime] => 0
        [proto_binary_fetched_timestamp] => 0
        [proto_binary_fetched_string] => 0
        [proto_binary_fetched_blob] => 0
        [proto_binary_fetched_enum] => 0
        [proto_binary_fetched_set] => 0
        [proto_binary_fetched_geometry] => 0
        [proto_binary_fetched_other] => 0
    )

### Ver también

- Descripción de las estadísticas

# mysqli_get_links_stats

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

mysqli_get_links_stats — Devuelve información sobre los enlaces abiertos y almacenados en caché

### Descripción

function mysqli_get_links_stats(): array

La función mysqli_get_links_stats() devuelve información sobre los enlaces MySQL abiertos y almacenados en caché.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

La función mysqli_get_links_stats() devuelve un array asociativo que contiene tres elementos, cuyas claves son las siguientes:

`total`

  Un int que indica el número total de enlaces abiertos, independientemente de su estado.

`active_plinks`

  Un int que representa el número de conexiones persistentes activas.

`cached_plinks`

  Un int que representa el número de conexiones persistentes inactivas.

# mysqli_report

(PHP 5, PHP 7, PHP 8)

mysqli_report — Alias de mysqli_driver->report_mode

### Descripción

Esta función es un alias de: mysqli_driver->report_mode

# mysqli::set_opt

# mysqli_set_opt

(PHP 5, PHP 7, PHP 8)

mysqli::set_opt -- mysqli_set_opt — Alias de mysqli_options()

### Descripción

Esta función es un alias de: mysqli_options().

## Tabla de contenidos

- mysqli_connect — Alias de mysqli::__construct
- mysqli::escape_string — Alias de mysqli_real_escape_string
- mysqli_execute — Alias de mysqli_stmt_execute
- mysqli_get_client_stats — Devuelve las estadísticas del cliente por proceso
- mysqli_get_links_stats — Devuelve información sobre los enlaces abiertos y almacenados en caché
- mysqli_report — Alias de mysqli_driver->report_mode
- mysqli::set_opt — Alias de mysqli_options

# Registro de cambios

A las clases/funciones/métodos de esta extensión se han realizado los siguientes cambios.

Version | Function | Description
--- | --- | ---
8.4.0 | mysqli::kill | Los métodos mysqli::kill y mysqli_kill están ahora obsoletos. Se recomienda utilizar el comando SQL KILL.
| mysqli::ping | Los métodos mysqli::ping y mysqli_ping están ahora obsoletos. La funcionalidad reconnect ya no está disponible desde PHP 8.2.0, lo que hace que esta función sea obsoleta.
| mysqli::refresh | Los métodos mysqli::refresh y mysqli_refresh están ahora obsoletos. Utilice los comandos SQL FLUSH en su lugar.
| mysqli::store_result | El paso del argumento mode está ahora obsoleto. Este argumento no ha tenido ningún efecto desde PHP 8.1.0.
8.3.0 | mysqli_result::fetch_object | Ahora se lanza una excepción ValueError cuando constructor_args no está vacío y la clase no tiene constructor; anteriormente, se lanzaba una excepción Exception.
| mysqli::poll | Ahora lanza una excepción ValueError cuando ni el argumento read ni el argumento error son transmitidos.
8.1.0 | mysqli_driver::$report_mode | El valor por omisión es ahora MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT. Anteriormente, era MYSQLI_REPORT_OFF.
| mysqli_result::fetch_all | Ahora también disponible al vincular con libmysqlclient.
| mysqli_stmt::execute | El parámetro opcional params ha sido añadido.
| mysqli_stmt::next_result | Ahora también disponible al enlazar con libmysqlclient.
| mysqli::__construct | mysqli::connect ahora devuelve true en lugar de null en caso de éxito.
| mysqli::$client_info | La llamada a la mysqli_get_client_info con el argumento mysql ha sido deprecada. Esta función nunca ha requerido un parámetro, pero lo ha permitido de manera incorrecta como parámetro opcional.
| mysqli::$client_info | El estilo orientado a objetos mysqli::get_client_info ha sido deprecado.
| mysqli::init | El método mysqli::init de estilo orientado a objetos ha sido deprecado. Reemplace las llamadas a parent::init por parent::__construct.
8.0.0 | mysqli_result::fetch_object | constructor_args ahora acepta [] para constructores con 0 parámetros; antes se lanzaba una excepción.
| mysqli_result::field_seek | Esta función devuelve ahora siempre true. Anteriormente, devolvía false en caso de fallo.
| mysqli_stmt::close | Esta función ahora siempre devuelve true. Anteriormente, devolvía false en caso de fallo.
| mysqli_stmt::__construct | query ahora es nullable.
| mysqli::begin_transaction | name ahora es nullable.
| mysqli::close | Esta función ahora siempre devuelve true. Anteriormente, devolvía false en caso de fallo.
| mysqli::commit | name es ahora nullable.
| mysqli::debug | Esta función devuelve ahora siempre true. Anteriormente, devolvía false en caso de error.
| mysqli::rollback | name ahora puede ser nullable.
7.4.0 | mysqli::__construct | Todos los parámetros ahora son nullable.
| mysqli::real_connect | Todos los parámetros son ahora nullable.

- Introducción
- Guía de inicio rápido
  - Interfaces procedimentales y orientadas a objetos
  - Conexiones
  - Ejecución de consultas
  - Las consultas preparadas
  - Los procedimientos almacenados
  - Consultas múltiples
  - Soporte API para las transacciones
  - Las metadatos
- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
- La extensión mysqli y las conexiones persistentes
- Constantes predefinidas
- Notas
- Resumen de las funciones de la extensión MySQLi
- mysqli — La clase mysqli
  - mysqli::$affected_rows — Devuelve el número de filas afectadas por la última operación MySQL
  - mysqli::autocommit — Activa o desactiva el modo auto-commit
  - mysqli::begin_transaction — Inicia una transacción
  - mysqli::change_user — Cambia el usuario de la conexión
  - mysqli::character_set_name — Devuelve el juego de caracteres actual para la conexión
  - mysqli::close — Cierra una conexión
  - mysqli::commit — Valida la transacción actual
  - mysqli::$connect_errno — Devuelve el código de error de la última llamada de conexión
  - mysqli::$connect_error — Devuelve una descripción del último error de conexión
  - mysqli::__construct — Abre una conexión a un servidor MySQL
  - mysqli::debug — Realiza acciones de depuración
  - mysqli::dump_debug_info — Escribe la información de depuración en los registros
  - mysqli::$errno — Devuelve el último código de error producido
  - mysqli::$error — Devuelve un string que describe el último error
  - mysqli::$error_list — Devuelve una lista de errores desde el último comando ejecutado
  - mysqli::execute_query — Prepara, vincula los parámetros y ejecuta una sentencia SQL
  - mysqli::$field_count — Devuelve el número de columnas para la última consulta
  - mysqli::get_charset — Devuelve un objeto que representa el juego de caracteres
  - mysqli::$client_info — Obtiene información sobre el cliente MySQL
  - mysqli::$client_version — Devuelve la versión del cliente MySQL como un entero
  - mysqli::get_connection_stats — Devuelve estadísticas sobre la conexión
  - mysqli::$host_info — Devuelve un string que contiene el tipo de conexión utilizada
  - mysqli::$protocol_version — Devuelve la versión del protocolo MySQL utilizado
  - mysqli::$server_info — Devuelve la versión del servidor MySQL
  - mysqli::$server_version — Devuelve un integer que representa la versión del servidor MySQL
  - mysqli::get_warnings — Lee el resultado de SHOW WARNINGS
  - mysqli::$info — Devuelve información acerca de la última consulta ejecutada
  - mysqli::init — Inicializa MySQLi y devuelve un objeto para usar con mysqli_real_connect()
  - mysqli::$insert_id — Devuelve el valor generado para una columna AUTO_INCREMENT por la última consulta
  - mysqli::kill — Solicita al servidor que finalice un hilo MySQL
  - mysqli::more_results — Comprueba si hay más conjuntos de resultados MySQL disponibles
  - mysqli::multi_query — Ejecuta una o varias consultas en la base de datos
  - mysqli::next_result — Prepara el siguiente resultado de una consulta múltiple
  - mysqli::options — Define las opciones
  - mysqli::ping — Verifica la conexión al servidor y reconecta si ya no existe
  - mysqli::poll — Verifica el estado de la conexión
  - mysqli::prepare — Prepara una consulta SQL para su ejecución
  - mysqli::query — Ejecuta una consulta en la base de datos
  - mysqli::real_connect — Establece una conexión con un servidor MySQL
  - mysqli::real_escape_string — Protege los caracteres especiales de un string para su uso en una consulta SQL, teniendo en cuenta el juego de caracteres actual de la conexión
  - mysqli::real_query — Ejecuta una consulta SQL
  - mysqli::reap_async_query — Lee un resultado para una consulta asíncrona
  - mysqli::refresh — Actualiza
  - mysqli::release_savepoint — Elimina el punto de guardado nombrado del conjunto de puntos de guardado de la transacción actual
  - mysqli::rollback — Revierte la transacción actual
  - mysqli::savepoint — Establece un punto de guardado nombrado de la transacción
  - mysqli::select_db — Selecciona una base de datos por defecto para las consultas
  - mysqli::set_charset — Define el juego de caracteres del cliente
  - mysqli::$sqlstate — Devuelve el error SQLSTATE de la última operación MySQL
  - mysqli::ssl_set — Utilizada para establecer una conexión segura con SSL
  - mysqli::stat — Obtiene el estado actual del sistema
  - mysqli::stmt_init — Inicializa una sentencia MySQL
  - mysqli::store_result — Transfiere un conjunto de resultados desde la última consulta
  - mysqli::$thread_id — Devuelve el identificador del hilo para la conexión actual
  - mysqli::thread_safe — Indica si el soporte de hilos está activado o no
  - mysqli::use_result — Inicializa la recuperación de un conjunto de resultados
  - mysqli::$warning_count — Devuelve el número de advertencias generadas por la última consulta ejecutada
- mysqli_stmt — La clase mysqli_stmt
  - mysqli_stmt::$affected_rows — Devuelve el número total de filas modificadas, eliminadas, insertadas o coincidentes por la última consulta
  - mysqli_stmt::attr_get — Obtiene el valor actual de un atributo de consulta
  - mysqli_stmt::attr_set — Modifica el comportamiento de una consulta preparada
  - mysqli_stmt::bind_param — Vincula variables a una consulta MySQL
  - mysqli_stmt::bind_result — Vincula variables a un conjunto de resultados
  - mysqli_stmt::close — Termina una consulta preparada
  - mysqli_stmt::__construct — Construye un nuevo objeto mysqli_stmt
  - mysqli_stmt::data_seek — Ajusta el puntero de resultado a una fila arbitraria en el resultado almacenado en el búfer.
  - mysqli_stmt::$errno — Devuelve un código de error para la última consulta
  - mysqli_stmt::$error — Devuelve una descripción del último error de procesamiento
  - mysqli_stmt::$error_list — Devuelve una lista de errores para la última consulta ejecutada
  - mysqli_stmt::execute — Ejecuta una consulta preparada
  - mysqli_stmt::fetch — Lee los resultados de una consulta MySQL preparada en variables vinculadas
  - mysqli_stmt::$field_count — Devuelve el número de columnas en la consulta dada
  - mysqli_stmt::free_result — Libera el resultado MySQL de la memoria
  - mysqli_stmt::get_result — Obtiene un conjunto de resultados desde una consulta preparada como un objeto mysqli_result
  - mysqli_stmt::get_warnings — Obtiene el resultado de SHOW WARNINGS
  - mysqli_stmt::$insert_id — Obtiene el ID generado por la última consulta INSERT
  - mysqli_stmt::more_results — Comprueba si hay más resultados desde una consulta múltiple
  - mysqli_stmt::next_result — Lee el resultado siguiente desde una consulta múltiple
  - mysqli_stmt::$num_rows — Devuelve el número de filas recuperadas del servidor
  - mysqli_stmt::$param_count — Devuelve el número de parámetros de un comando SQL
  - mysqli_stmt::prepare — Prepara una consulta SQL para su ejecución
  - mysqli_stmt::reset — Anula una consulta preparada
  - mysqli_stmt::result_metadata — Devuelve las metadatos de preparación de consulta MySQL
  - mysqli_stmt::send_long_data — Envía datos MySQL por paquetes
  - mysqli_stmt::$sqlstate — Devuelve el código SQLSTATE de la última operación MySQL
  - mysqli_stmt::store_result — Almacena un conjunto de resultados en un búfer interno
- mysqli_result — La clase mysqli_result
  - mysqli_result::__construct — Construye un objeto mysqli_result
  - mysqli_result::$current_field — Obtiene la posición actual de un campo en un puntero de resultado
  - mysqli_result::data_seek — Mueve el puntero interno de resultado
  - mysqli_result::fetch_all — Recupera todas las filas de resultados en un array asociativo, numérico o ambos
  - mysqli_result::fetch_array — Obtiene la siguiente fila de un conjunto de resultados como un array asociativo, numérico o ambos
  - mysqli_result::fetch_assoc — Recupera la siguiente fila de un conjunto de resultados como un array asociativo
  - mysqli_result::fetch_column — Recupera una sola columna de la siguiente fila de un conjunto de resultados
  - mysqli_result::fetch_field — Devuelve el siguiente campo en el conjunto de resultados
  - mysqli_result::fetch_field_direct — Obtiene los metadatos de un campo único
  - mysqli_result::fetch_fields — Devuelve un array de objetos que representan los campos en el resultado
  - mysqli_result::fetch_object — Devuelve la siguiente fila de un conjunto de resultados como objeto
  - mysqli_result::fetch_row — Obtiene una fila de resultado como un array indexado
  - mysqli_result::$field_count — Obtiene el número de campos en el conjunto de resultados
  - mysqli_result::field_seek — Desplaza el puntero de resultado al campo especificado
  - mysqli_result::free — Libera la memoria asociada a un resultado
  - mysqli_result::getIterator — Devuelve un iterador externo
  - mysqli_result::$lengths — Devuelve la longitud de las columnas de la fila actual del conjunto de resultados
  - mysqli_result::$num_rows — Devuelve el número de filas en el conjunto de resultados
- mysqli_driver — La clase mysqli_driver
  - mysqli_driver::embedded_server_end — Detiene el servidor embebido
  - mysqli_driver::embedded_server_start — Inicializa e inicia el servidor embebido
  - mysqli_driver::$report_mode — Define el modo de informe de errores de mysqli
- mysqli_warning — La clase mysqli_warning
  - mysqli_warning::__construct — Constructor privado para evitar la instanciación directa
  - mysqli_warning::next — Obtiene el siguiente aviso
- mysqli_sql_exception — La clase mysqli_sql_exception
  - mysqli_sql_exception::getSqlState — Devuelve el código de error SQLSTATE
- Funciones mysqli obsoletas y alias
  - mysqli_connect — Alias de mysqli::__construct
  - mysqli::escape_string — Alias de mysqli_real_escape_string
  - mysqli_execute — Alias de mysqli_stmt_execute
  - mysqli_get_client_stats — Devuelve las estadísticas del cliente por proceso
  - mysqli_get_links_stats — Devuelve información sobre los enlaces abiertos y almacenados en caché
  - mysqli_report — Alias de mysqli_driver->report_mode
  - mysqli::set_opt — Alias de mysqli_options
- Registro de cambios

# Mysql_xdevapi

# Introducción

Esta extensión proporciona acceso al Document Store de MySQL a través de la DevAPI X. La DevAPI X es una API común proporcionada por varios MySQL Connectors que permiten un acceso fácil a las tablas relacionales así como a las colecciones de documentos, que se representan en JSON, desde una API con operaciones de estilo CRUD.

La DevAPI de X utiliza el protocolo X, el protocolo de nueva generación cliente-servidor de MySQL servidor 8.0.

Para información general sobre MySQL Document Store, consulte el capítulo » MySQL Document Store del manual de MySQL.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución
- Compilar a partir de las fuentes

## Requerimientos

Esta extensión requiere un servidor MySQL 8+ con el complemento X activado (por omisión).

Las bibliotecas prerrequisitos para compilar esta extensión son: Boost (1.53.0 o superior), OpenSSL y Protobuf.

## Instalación

Esta extensión » PECL no está integrada en PHP.

Un ejemplo de procedimiento de instalación en Ubuntu 18.04 con PHP 7.2:

    // Dependencias
    $ apt install build-essential libprotobuf-dev libboost-dev openssl protobuf-compiler liblz4-tool zstd

    // PHP con las extensiones deseadas; php7.2-dev es requerido para compilar
    $ apt install php7.2-cli php7.2-dev php7.2-mysql php7.2-pdo php7.2-xml

    // Compilar esta extensión
    $ pecl install mysql_xdevapi

El comando `pecl install` no activa las extensiones PHP (por omisión) y activar las extensiones PHP puede hacerse de varias maneras. Otro ejemplo con PHP 7.2 en Ubuntu 18.04:

    // Crear su propio fichero ini
    $ echo "extension=mysql_xdevapi.so" > /etc/php/7.2/mods-available/mysql_xdevapi.ini

    // Utilizar el comando 'phpenmod' (nota: específico de Debian/Ubuntu)
    $ phpenmod -v 7.2 -s ALL mysql_xdevapi

    // Una alternativa a 'phpenmod' es crear un enlace simbólico manualmente
    // $ ln -s /etc/php/7.2/mods-available/mysql_xdevapi.ini /etc/php/7.2/cli/conf.d/20-mysql_xdevapi.ini

    // Veamos qué extensiones MySQL están activadas ahora
    $ php -m |grep mysql

    mysql_xdevapi
    mysqli
    mysqlnd
    pdo_mysql

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/mysql_xdevapi.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración Mysql_xdevapi
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
xmysqlnd.collect_memory_statistics | 0 | `INI_SYSTEM` |
xmysqlnd.collect_statistics | 1 | `INI_ALL` |
xmysqlnd.debug |  | `INI_SYSTEM` |
xmysqlnd.mempool_default_size | 16000 | `INI_ALL` |
xmysqlnd.net_read_timeout | 31536000 | `INI_SYSTEM` |
xmysqlnd.trace_alloc |  | `INI_SYSTEM` |

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`xmysqlnd.collect_memory_statistics` int

`xmysqlnd.collect_statistics` int

`xmysqlnd.debug` string

`xmysqlnd.mempool_default_size` int

`xmysqlnd.net_read_timeout` int

`xmysqlnd.trace_alloc` string

## Compilar a partir de las fuentes

Consideraciones para compilar esta extensión a partir de las fuentes.

- El nombre de la extensión es 'mysql_xdevapi', por lo tanto, utilice `--enable-mysql-xdevapi`.

- Boost; requerido, utilice opcionalmente la opción de configuración --with-boost=DIR o defina la variable de entorno MYSQL_XDEVAPI_BOOST_ROOT. Solo se requieren los ficheros de encabezado boost; no los binarios.

- Google Protocol Buffers (protobuf): requerido, utilice opcionalmente la opción de configuración --with-protobuf=DIR o defina la variable de entorno MYSQL_XDEVAPI_PROTOBUF_ROOT.

  Opcionalmente utilice `make protobufs` para generar los ficheros protobuf (*.pb.cc/.h), y `make clean-protobufs` para eliminar los ficheros protobuf generados.

  Nota específica para Windows: según su entorno, la biblioteca estática con un runtime DLL multi-thread puede ser necesaria. Para preparar, utilice las siguientes opciones: -Dprotobuf_MSVC_STATIC_RUNTIME=OFF -Dprotobuf_BUILD_SHARED_LIBS=OFF

- Google Protocol Buffers / protoc: requerido, asegúrese de que el correcto 'protoc' esté disponible en el PATH durante la compilación. Esto es particularmente importante ya que los scripts batch del SDK PHP Windows pueden sobrescribir el entorno.

- Bison: requerido, y disponible en el PATH.

  Nota específica para bison Windows: se recomienda encarecidamente utilizar bison proporcionado con el SDK PHP elegido, de lo contrario, un error similar a "zend_globals_macros.h(39): error C2375: 'zendparse': redefinition; different linkage Zend/zend_language_parser.h(214): note: see declaration of 'zendparse'" puede ser el resultado. Además, los scripts batch del SDK PHP Windows pueden sobrescribir el entorno.

- Nota específica para Windows: para preparar el entorno, consulte la documentación oficial de construcción de Windows para » el SDK actual.

  Se recomienda utilizar las barras invertidas '\\' en lugar de una barra '/' para todos los caminos.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`MYSQLX_CLIENT_SSL` (int)
`MYSQLX_TYPE_DECIMAL` (int)
`MYSQLX_TYPE_TINY` (int)
`MYSQLX_TYPE_SHORT` (int)
`MYSQLX_TYPE_SMALLINT` (int)
`MYSQLX_TYPE_MEDIUMINT` (int)
`MYSQLX_TYPE_INT` (int)
`MYSQLX_TYPE_BIGINT` (int)
`MYSQLX_TYPE_LONG` (int)
`MYSQLX_TYPE_FLOAT` (int)
`MYSQLX_TYPE_DOUBLE` (int)
`MYSQLX_TYPE_NULL` (int)
`MYSQLX_TYPE_TIMESTAMP` (int)
`MYSQLX_TYPE_LONGLONG` (int)
`MYSQLX_TYPE_INT24` (int)
`MYSQLX_TYPE_DATE` (int)
`MYSQLX_TYPE_TIME` (int)
`MYSQLX_TYPE_DATETIME` (int)
`MYSQLX_TYPE_YEAR` (int)
`MYSQLX_TYPE_NEWDATE` (int)
`MYSQLX_TYPE_ENUM` (int)
`MYSQLX_TYPE_SET` (int)
`MYSQLX_TYPE_TINY_BLOB` (int)
`MYSQLX_TYPE_MEDIUM_BLOB` (int)
`MYSQLX_TYPE_LONG_BLOB` (int)
`MYSQLX_TYPE_BLOB` (int)
`MYSQLX_TYPE_VAR_STRING` (int)
`MYSQLX_TYPE_STRING` (int)
`MYSQLX_TYPE_CHAR` (int)
`MYSQLX_TYPE_BYTES` (int)
`MYSQLX_TYPE_INTERVAL` (int)
`MYSQLX_TYPE_GEOMETRY` (int)
`MYSQLX_TYPE_JSON` (int)
`MYSQLX_TYPE_NEWDECIMAL` (int)
`MYSQLX_TYPE_BIT` (int)
`MYSQLX_LOCK_DEFAULT` (int)
`MYSQLX_LOCK_NOWAIT` (int)
`MYSQLX_LOCK_SKIP_LOCKED` (int)

# Registro de cambios

A las clases/funciones/métodos de esta extensión se han realizado los siguientes cambios.

### Historial de cambios general de la extensión ext/mysql_xdevapi

Este historial de cambios hace referencia a la extensión ext/mysql_xdevapi.

### Cambios globales de la extensión ext/mysql_xdevapi

Versión | Descripción
--- | ---
8.0.28 | Eliminación del soporte de TLSv1 y TLSv1.1. Los valores "TLSv1", "TLSv1.0" y "TLSv1.1" se consideran ahora inválidos para el atributo de conexión "tls-versions".
8.0.26 | Deprecación del soporte de TLSv1 y TLSv1.1.

# Ejemplos

El punto de entrada central de la API X es la función mysql_xdevapi\getSession(), que recibe una URI hacia un servidor MySQL 8.0 y devuelve un objeto mysql_xdevapi\Session.

Ejemplo #1 Conectar a un Servidor MySQL

    <?php
    try {
        $session = mysql_xdevapi\getSession("mysqlx://user:password@host");
    } catch(Exception $e) {
        die("La conexión no pudo ser establecida: " . $e->getMessage());
    }

    // ... usar $session
    ?>

La sesión proporciona acceso completo a la API. Para una nueva instalación de servidor MySQL, el primer paso es crear un esquema de base de datos con una colección para almacenar datos:

Ejemplo #2 Crear un Esquema y una Colección en el Servidor MySQL

    <?php
    $schema = $session->createSchema("test");
    $collection = $schema->createCollection("example");
    ?>

Al almacenar datos, generalmente json_encode() se utiliza para codificar los datos en JSON, que luego pueden ser almacenados en una colección.

Los siguientes ejemplos almacenan datos en la colección que hemos creado anteriormente, y luego recuperan partes de estos datos nuevamente.

Ejemplo #3 Almacenar y Recuperar Datos

    <?php
    $marco = [
      "name" => "Marco",
      "age"  => 19,
      "job"  => "Programmer"
    ];
    $mike = [
      "name" => "Mike",
      "age"  => 39,
      "job"  => "Manager"
    ];

    $schema = $session->getSchema("test");
    $collection = $schema->getCollection("example");

    $collection->add($marco, $mike)->execute();

    var_dump($collection->find("name = 'Mike'")->execute()->fetchOne());
    ?>

Resultado del ejemplo anterior es similar a:

    array(4) {
      ["_id"]=>
      string(28) "00005ad66aaf0000000000000003"
      ["age"]=>
      int(39)
      ["job"]=>
      string(7) "Manager"
      ["name"]=>
      string(4) "Mike"
    }

Este ejemplo demuestra que el servidor MySQL añade un campo adicional llamado `_id`, que sirve como clave primaria del documento.

Este ejemplo también demuestra que los datos recuperados están ordenados alfabéticamente. Este orden específico proviene del almacenamiento binario eficiente dentro del servidor MySQL, pero no debe confiarse en él. Consulte la documentación del tipo de datos JSON de MySQL para más detalles.

Opcionalmente, utilice los iteradores de PHP para recuperar múltiples documentos:

Ejemplo #4 Recuperar e Iterar sobre Múltiples Documentos

    <?php
    $result = $collection->find()->execute();
    foreach ($result as $doc) {
      echo "{$doc["name"]} es un {$doc["job"]}.\n";
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Marco es un Programmer.
    Mike es un Manager.

# Funciones Mysql_xdevapi

# expression

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

expression — Vincula una expresión a una variable de consulta preparada

### Descripción

function mysql_xdevapi\expression(string `$expression`): object

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`expression`

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Expression()

    <?php
    $expression = mysql_xdevapi\Expression("[age,job]");

    $res  = $coll->find("age > 30")->fields($expression)->limit(3)->execute();
    $data = $res->fetchAll();

    print_r($data);
    ?>

Resultado del ejemplo anterior es similar a:

    <?php

# getSession

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

getSession — Conecta a un servidor MySQL

### Descripción

function mysql_xdevapi\getSession(string `$uri`): mysql_xdevapi\Session

Conecta al servidor MySQL.

### Parámetros

`uri`

  El URI del servidor MySQL, tal como `mysqlx://user:password@host`.

  Formato de URI:

  `scheme://[user[:[password]]@]target[:port][?attribute1=value1&attribute2=value2...`

  - `scheme`: requerido, el protocolo de conexión

    En mysql_xdevapi es siempre 'mysqlx' (para el protocolo X)

  - `user`: opcional, la cuenta de usuario MySQL para la autenticación

  - `password`: opcional, la contraseña del usuario MySQL para la autenticación

  - `target`: requerido, la instancia del servidor a la que se refiere la conexión:

    * Conexión TCP (nombre de host, dirección IPv4 o dirección IPv6)

    * Ruta de socket Unix (ruta de fichero local)

    * Pipe nombrado Windows (ruta de fichero local)

  - `port`: opcional, el puerto de red del servidor MySQL.

    Por omisión, el puerto para el protocolo X es 33060

  - `?attribute=value`: este elemento es opcional y especifica un diccionario de datos que contiene diferentes opciones, incluyendo:

    - El atributo `auth` (mecanismo de autenticación) relacionado con las conexiones cifradas. Para más información, ver » Opciones de comando para las conexiones cifradas. Los siguientes valores 'auth' son soportados: `plain`, `mysql41`, `external`, y `sha256_mem`.

    - El atributo `connect-timeout` afecta la conexión y no las operaciones siguientes. Se define por conexión, ya sea en un solo host o en varios.

      Pasar un entero positivo para definir el tiempo límite de conexión en segundos, o pasar 0 (cero) para desactivar el tiempo límite (infinito). No definir connect-timeout utiliza el valor por omisión de 10.

      En relación, las variables de entorno MYSQLX_CONNECTION_TIMEOUT (tiempo límite en segundos) y MYSQLX_TEST_CONNECTION_TIMEOUT (utilizado durante la ejecución de pruebas) pueden ser definidas y utilizadas en lugar de connect-timeout en el URI. La opción connect-timeout del URI tiene prioridad sobre estas variables de entorno.

    - El atributo opcional `compression` acepta estos valores: `preferred` (el cliente negocia con el servidor para encontrar un algoritmo soportado; la conexión no está comprimida si no se encuentra un algoritmo soportado mutuamente), `required` (como "preferred", pero la conexión se termina si no se encuentra un algoritmo soportado mutuamente), o `disabled` (la conexión no está comprimida). Por omisión, `preferred`.

      Esta opción fue añadida en la versión 8.0.20.

    - El atributo opcional `compression-algorithms` define los algoritmos de compresión deseados (y su orden de uso preferido): `zstd_stream` (alias: zstd), `lz4_message` (alias: lz4), o `deflate_stream` (alias: deflate o zlib). Por omisión, el orden utilizado (según la disponibilidad del sistema) es lz4_message, zstd_stream, y luego deflate_stream. Por ejemplo, pasar compression-algorithms=[lz4,zstd_stream] utiliza lz4 si está disponible, de lo contrario se utiliza zstd_stream. Si ninguno de los dos está disponible, el comportamiento depende del valor de compression por ejemplo, si compression=required entonces fallará con un error.

      Esta opción fue añadida en la versión 8.0.22.

  Ejemplo #1 Ejemplo de URI

      mysqlx://foobar
      mysqlx://root@localhost?socket=%2Ftmp%2Fmysqld.sock%2F
      mysqlx://foo:bar@localhost:33060
      mysqlx://foo:bar@localhost:33160?ssl-mode=disabled
      mysqlx://foo:bar@localhost:33260?ssl-mode=required
      mysqlx://foo:bar@localhost:33360?ssl-mode=required&auth=mysql41
      mysqlx://foo:bar@(/path/to/socket)
      mysqlx://foo:bar@(/path/to/socket)?auth=sha256_mem
      mysqlx://foo:bar@[localhost:33060, 127.0.0.1:33061]
      mysqlx://foobar?ssl-ca=(/path/to/ca.pem)&ssl-crl=(/path/to/crl.pem)
      mysqlx://foo:bar@[localhost:33060, 127.0.0.1:33061]?ssl-mode=disabled
      mysqlx://foo:bar@localhost:33160/?connect-timeout=0
      mysqlx://foo:bar@localhost:33160/?connect-timeout=10&compression=required
      mysqlx://foo:bar@localhost:33160/?connect-timeout=10&compression=required&compression-algorithms=[lz4,zstd_stream]

  Para más información, ver conexión a MySQL Shell » utilizando una cadena de URI.

### Valores devueltos

Un objeto Session.

### Errores/Excepciones

Un error de conexión lanza una excepción Exception.

### Ejemplos

Ejemplo #2 Ejemplo de mysql_xdevapi\getSession()

    <?php
    try {
        $session = mysql_xdevapi\getSession("mysqlx://user:password@host");
    } catch(Exception $e) {
        die("La conexión no pudo ser establecida: " . $e->getMessage());
    }

    $schemas = $session->getSchemas();
    print_r($schemas);

    $mysql_version = $session->getServerVersion();
    print_r($mysql_version);

    var_dump($collection->find("name = 'Alfred'")->execute()->fetchOne());
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => mysql_xdevapi\Schema Object
            (
                [name] => helloworld
            )
        [1] => mysql_xdevapi\Schema Object
            (
                [name] => information_schema
            )
        [2] => mysql_xdevapi\Schema Object
            (
                [name] => mysql
            )
        [3] => mysql_xdevapi\Schema Object
            (
                [name] => performance_schema
            )
        [4] => mysql_xdevapi\Schema Object
            (
                [name] => sys
            )
    )

    80012

    array(4) {
      ["_id"]=>
      string(28) "00005ad66abf0001000400000003"
      ["age"]=>
      int(42)
      ["job"]=>
      string(7) "Butler"
      ["name"]=>
      string(4) "Alfred"
    }

## Tabla de contenidos

- expression — Vincula una expresión a una variable de consulta preparada
- getSession — Conecta a un servidor MySQL

# Interfaz BaseResult

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\BaseResult {
/* Métodos */
abstract public function getWarnings(): array
abstract public function getWarningsCount(): int
}

# BaseResult::getWarnings

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

BaseResult::getWarnings — Recupera los avisos de la última operación

### Descripción

abstract public function mysql_xdevapi\BaseResult::getWarnings(): array

Recupera los avisos generados por la última operación del servidor MySQL.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array de objetos Warning de la última operación. Cada objeto define un 'message' de error, un 'nivel' de error y un 'code' de error. Un array vacío es devuelto si no hay errores.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\RowResult::getWarnings()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();
    $warnings = $res->getWarnings();

    print_r($warnings);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
        [1] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
    )

# BaseResult::getWarningsCount

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

BaseResult::getWarningsCount — Recupera el número de advertencias de la última operación

### Descripción

abstract public function mysql_xdevapi\BaseResult::getWarningsCount(): int

Devuelve el número de advertencias generadas por la última operación. Más específicamente, estas advertencias son generadas por el servidor MySQL.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El número de advertencias de la última operación.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\RowResult::getWarningsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS foo")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();

    echo $res->getWarningsCount();
    ?>

Resultado del ejemplo anterior es similar a:

    2

## Tabla de contenidos

- BaseResult::getWarnings — Recupera los avisos de la última operación
- BaseResult::getWarningsCount — Recupera el número de advertencias de la última operación

# La clase Client

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

## Introducción

Proporciona acceso a la conexión a la base de datos.

## Sinopsis de la Clase

class mysql_xdevapi\Client {
/* Métodos */
public function close(): bool
public function getSession(): mysql_xdevapi\Session
}

# mysql_xdevapi\Client::close

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

mysql_xdevapi\Client::close — Cierra el cliente

### Descripción

public function mysql_xdevapi\Client::close(): bool

Cierra todas las conexiones del cliente con el servidor.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

`true` si las conexiones son cerradas.

# Client::__construct

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

Client::__construct — Constructor del cliente

### Descripción

private function mysql_xdevapi\Client::__construct()

Construye un objeto cliente.

### Parámetros

Esta función no contiene ningún parámetro.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Client::__construct()

    <?php
    $pooling_options = '{
      "enabled": true,
        "maxSize": 10,
        "maxIdleTime": 3600,
        "queueTimeOut": 1000
    }';
    $client = mysql_xdevapi\getClient($connection_uri, $pooling_options);
    $session = $client->getSession();

# Client::getClient

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

Client::getClient — Devuelve la sesión del cliente

### Descripción

public function mysql_xdevapi\Client::getSession(): mysql_xdevapi\Session

Devuelve la sesión asociada al cliente.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un objeto Session.

## Tabla de contenidos

- mysql_xdevapi\Client::close — Cierra el cliente
- Client::__construct — Constructor del cliente
- Client::getClient — Devuelve la sesión del cliente

# Clase Collection

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\Collection implements mysql_xdevapi\SchemaObject {
/* Propiedades */
public $name;
/* Métodos */
public function add(mixed `$document`): mysql_xdevapi\CollectionAdd
public function addOrReplaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result
public function count(): int
public function createIndex(string `$index_name`, string `$index_desc_json`): void
public function dropIndex(string `$index_name`): bool
public function existsInDatabase(): bool
public function find(string `$search_condition` = ?): mysql_xdevapi\CollectionFind
public function getName(): string
public function getOne(string `$id`): Document
public function getSchema(): Schema Object
public function getSession(): Session
public function modify(string `$search_condition`): mysql_xdevapi\CollectionModify
public function remove(string `$search_condition`): mysql_xdevapi\CollectionRemove
public function removeOne(string `$id`): mysql_xdevapi\Result
public function replaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result
}

## Propiedades

name

# Collection::add

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

Collection::add — Añade un documento a la colección

### Descripción

public function mysql_xdevapi\Collection::add(mixed `$document`): mysql_xdevapi\CollectionAdd

Desencadena la inserción del o de los documentos dados en la colección, y se admiten varias variantes de este método. Las opciones incluyen:

1. Añadir un solo documento en forma de string JSON.

2. Añadir un solo documento en forma de array como: `[ 'field' => 'value', 'field2' => 'value2' ... ]`

3. Una mezcla de ambos, y varios documentos pueden ser añadidos en la misma operación.

### Parámetros

`document`

  Uno o varios documentos, y esto puede ser tanto JSON como un array de campos con sus valores asociados. No puede ser un array vacío.

  El servidor MySQL genera automáticamente valores `_id` únicos para cada documento (recomendado), aunque esto también puede ser añadido manualmente. Este valor debe ser único, de lo contrario la operación de adición fallará.

### Valores devueltos

Una colección de objetos. Utilizar execute() para devolver un resultado que puede ser utilizado para consultar el número de elementos afectados, el número de advertencias generadas por la operación, o para recuperar una lista de identificadores generados para los documentos insertados.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Collection::add()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    // Añade dos documentos
    $collection->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
    $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    // Añade dos documentos utilizando un solo objeto JSON
    $result = $collection->add(
      '{"name": "Bernie",
        "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
        "hobbies": ["Sports","Making cupcakes"]}',
      '{"name": "Jane",
        "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
        "hobbies": ["Walking","Making pies"]}')->execute();

    // Recupera una lista de identificadores generados a partir del último add()
    $ids = $result->getGeneratedIds();
    print_r($ids);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => 00005b6b53610000000000000056
        [1] => 00005b6b53610000000000000057
    )

### Notas

> Nota:

> Un identificador único _id es generado por MySQL Server 8.0 o superior, como se demuestra en el ejemplo. El campo _id debe ser definido manualmente si se utiliza MySQL Server 5.7.

# Collection::addOrReplaceOne

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

Collection::addOrReplaceOne — Añade o reemplaza un documento de la colección

### Descripción

public function mysql_xdevapi\Collection::addOrReplaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result

Añade un nuevo documento, o reemplaza un documento si ya existe.

Existen varios escenarios para este método:

- Ni el id ni ningún valor de clave única están en conflicto con un documento de la colección, entonces el documento es añadido.

- Si el id no corresponde a ningún documento, pero uno o más valores de clave única entran en conflicto con un documento de la colección, entonces se lanza un error.

- Si el id corresponde a un documento existente y ninguna clave única está definida para la colección, entonces el documento es reemplazado.

- Si el id corresponde a un documento existente, y todas las claves únicas del documento de reemplazo corresponden a ese mismo documento o no están en conflicto con ningún otro documento de la colección, entonces el documento es reemplazado.

- Si el id corresponde a un documento existente, y una o más claves únicas corresponden a otro documento de la colección, entonces se lanza un error.

### Parámetros

`id`

  Este es el identificador del filtro. Si este identificador o cualquier otro campo que tiene un índice único ya existe en la colección, entonces actualizará el documento correspondiente.

  Por omisión, este identificador es generado automáticamente por el servidor MySQL cuando el documento ha sido añadido, y es referenciado como un campo nombrado '_id'.

`doc`

  Este es el documento a añadir o reemplazar, que es una cadena JSON.

### Valores devueltos

Un objeto Result.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Collection::addOrReplaceOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    // Utilizar add()
    $result = $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    // Utilizar addOrReplaceOne()
    // Nota: pasamos aquí un valor _id conocido
    $result = $collection->addOrReplaceOne('00005b6b53610000000000000056', '{"name": "Fred",  "age": 21, "job": "Construction"}');

    ?>

# Collection::__construct

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

Collection::__construct — Constructor de Collection

### Descripción

private function mysql_xdevapi\Collection::__construct()

Construye un objeto Collection.

### Parámetros

Esta función no contiene ningún parámetro.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Collection::getOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection->add('{"name": "Alfred", "age": 42, "job": "Butler"}')->execute();

    // Un identificador único _id es generado por MySQL Server
    // Esto recupera los _id generados; uno solo en este ejemplo, por lo tanto $ids[0]
    $ids        = $result->getGeneratedIds();
    $alfreds_id = $ids[0];

    // ...

    print_r($alfreds_id);
    print_r($collection->getOne($alfreds_id));
    ?>

Resultado del ejemplo anterior es similar a:

    00005b6b536100000000000000b1

    Array
    (
        [_id] => 00005b6b536100000000000000b1
        [age] => 42
        [job] => Butler
        [name] => Alfred
    )

# Collection::count

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

Collection::count — Devuelve el número de documentos

### Descripción

public function mysql_xdevapi\Collection::count(): int

Esta funcionalidad es similar a una operación SQL `SELECT COUNT(*)` en el servidor MySQL para el esquema y la colección actuales. En otras palabras, cuenta el número de documentos en la colección.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El número de documentos en la colección.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Collection::count()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    $result = $collection
      ->add(
      '{"name": "Bernie",
        "jobs": [
          {"title":"Cat Herder","Salary":42000},
          {"title":"Father","Salary":0}
        ],
        "hobbies": ["Sports","Making cupcakes"]}',
      '{"name": "Jane",
        "jobs": [
          {"title":"Scientist","Salary":18000},
          {"title":"Mother","Salary":0}
        ],
        "hobbies": ["Walking","Making pies"]}')
      ->execute();

    var_dump($collection->count());
    ?>

El ejemplo anterior mostrará:

    int(2)

# Collection::createIndex

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

Collection::createIndex — Crear un índice de colección

### Descripción

public function mysql_xdevapi\Collection::createIndex(string `$index_name`, string `$index_desc_json`): void

Crear un índice en la colección.

Se lanza una excepción si ya existe un índice con el mismo nombre, o si la definición del índice no está correctamente formada.

### Parámetros

`index_name`

  El nombre del índice a crear. Este nombre debe ser un nombre de índice válido tal como aceptado por la consulta SQL `CREATE INDEX`.

`index_desc_json`

  La definición del índice a crear. Contiene un array de objetos IndexField, y cada objeto describe un solo miembro de documento a incluir en el índice, y una cadena opcional para el tipo de índice que podría ser INDEX (por omisión) o SPATIAL.

  Una descripción única de IndexField se compone de los siguientes campos:

  - `field`: string, la ruta completa del documento hacia el miembro del documento o el campo a indexar.

  - `type`: string, uno de los tipos de columnas SQL admitidos para mapear el campo. Para los tipos numéricos, la palabra clave opcional UNSIGNED puede seguir. Para el tipo TEXT, la longitud a considerar para la indexación puede ser añadida.

  - `unique`: bool, (opcional) true si el campo debe ser existente en el documento. Por omisión es `false`, excepto para `GEOJSON` donde por omisión es `true`.

  - `options`: integer, (opcional) flags de opciones especiales a utilizar al decodificar datos `GEOJSON`.

  - `srid`: integer, (opcional) valor srid a utilizar al decodificar datos `GEOJSON`.

  Es un error incluir otros campos no descritos anteriormente en los documentos IndexDefinition o IndexField.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Collection::createIndex()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    // Crear un índice de texto
    $collection->createIndex(
      'myindex1',
      '{"fields": [{
        "field": "$.name",
        "type": "TEXT(25)",
        "required": true}],
        "unique": false}'
    );

    // Un índice espacial
    $collection->createIndex(
      'myindex2',
      '{"fields": [{
        "field": "$.home",
        "type": "GEOJSON",
        "required": true}],
        "type": "SPATIAL"}'
    );

    // Índice con múltiples campos
    $collection->createIndex(
      'myindex3',
      '{"fields": [
        {
          "field": "$.name",
          "type": "TEXT(20)",
          "required": true
        },
        {
          "field": "$.age",
          "type": "INTEGER"
        },
        {
          "field": "$.job",
          "type": "TEXT(30)",
          "required": false
        }
      ],
      "unique": true
      }'
    );

# Collection::dropIndex

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

Collection::dropIndex — Elimina un índice de colección

### Descripción

public function mysql_xdevapi\Collection::dropIndex(string `$index_name`): bool

Elimina un índice de colección.

Esta operación no lanza un error si el índice no existe, pero `false` es devuelto en este caso.

### Parámetros

`index_name`

  El nombre del índice de colección a eliminar.

### Valores devueltos

`true` si la operación DROP INDEX ha tenido éxito, de lo contrario `false`.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Collection::dropIndex()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    // ...

    $collection = $schema->getCollection("people");

    $collection->createIndex(
      'myindex',
      '{"fields": [{"field": "$.name", "type": "TEXT(25)", "required": true}], "unique": false}'
    );

    // ...

    if ($collection->dropIndex('myindex')) {
        echo "Un índice llamado 'myindex' fue encontrado y eliminado.";
    }
    ?>

El ejemplo anterior mostrará:

    Un índice llamado 'myindex' fue encontrado y eliminado.

# Collection::existsInDatabase

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

Collection::existsInDatabase — Verifica si la colección existe en la base de datos

### Descripción

public function mysql_xdevapi\Collection::existsInDatabase(): bool

Verifica si el objeto Collection hace referencia a una colección en la base de datos (esquema).

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si la colección existe en la base de datos, de lo contrario `false` si no existe.

Una tabla definida con dos columnas (doc y _id) se considera una colección, y una tercera columna _json_schema a partir de MySQL 8.0.21. Añadir una columna adicional significa que existsInDatabase() ya no la verá como una colección.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Collection::existsInDatabase()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    // ...

    $collection = $schema->getCollection("people");

    // ...

    if (!$collection->existsInDatabase()) {
        echo "La colección ya no existe en la base de datos llamada addressbook. ¿Qué pasó?";
    }
    ?>

# Collection::find

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

Collection::find — Búsqueda de documento

### Descripción

public function mysql_xdevapi\Collection::find(string `$search_condition` = ?): mysql_xdevapi\CollectionFind

Busca una colección de base de datos para un documento o un conjunto de documentos. Los documentos encontrados se devuelven en forma de un objeto CollectionFind para modificarlos o recuperar resultados adicionales.

### Parámetros

`search_condition`

  Aunque es opcional, normalmente se define una condición para limitar los resultados a un subconjunto de documentos.

  Varios elementos pueden construir la condición y la sintaxis soporta la ligadura de argumentos. La expresión utilizada como condición de búsqueda debe ser una expresión SQL válida. Si no se proporciona ninguna condición de búsqueda (campo vacío) entonces se supone find('true').

### Valores devueltos

Un objeto CollectionFind para verificar la operación, o recuperar los documentos encontrados.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Collection::find()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Alfred",     "age": 18, "job": "Butler"}')->execute();
    $collection->add('{"name": "Bob",        "age": 19, "job": "Swimmer"}')->execute();
    $collection->add('{"name": "Fred",       "age": 20, "job": "Construction"}')->execute();
    $collection->add('{"name": "Wilma",      "age": 21, "job": "Teacher"}')->execute();
    $collection->add('{"name": "Suki",       "age": 22, "job": "Teacher"}')->execute();

    $find   = $collection->find('job LIKE :job AND age > :age');
    $result = $find
      ->bind(['job' => 'Teacher', 'age' => 20])
      ->sort('age DESC')
      ->limit(2)
      ->execute();

    print_r($result->fetchAll());
    ?>

El ejemplo anterior mostrará:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b536100000000000000a8
                [age] => 22
                [job] => Teacher
                [name] => Suki
            )
        [1] => Array
            (
                [_id] => 00005b6b536100000000000000a7
                [age] => 21
                [job] => Teacher
                [name] => Wilma
            )
    )

# Collection::getName

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

Collection::getName — Devuelve el nombre de la colección

### Descripción

public function mysql_xdevapi\Collection::getName(): string

Devuelve el nombre de la colección.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El nombre de la colección, en forma de string.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Collection::getName()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    // ...

    var_dump($collection->getName());
    ?>

Resultado del ejemplo anterior es similar a:

    string(6) "people"

# Collection::getOne

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

Collection::getOne — Devuelve un documento

### Descripción

public function mysql_xdevapi\Collection::getOne(string `$id`): Document

Recupera un documento de la colección.

Esto es un atajo para: `Collection.find("_id = :id").bind("id", id).execute().fetchOne();`

### Parámetros

`id`

  El _id del documento en la colección.

### Valores devueltos

El objeto colección, o `null` si el _id no corresponde a un documento.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Collection::getOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection->add('{"name": "Alfred", "age": 42, "job": "Butler"}')->execute();

    // Un identificador único _id (por omisión, y recomendado) es generado por MySQL Server
    // Esto recupera los _id generados; uno solo en este ejemplo, por lo tanto $ids[0]
    $ids        = $result->getGeneratedIds();
    $alfreds_id = $ids[0];

    // ...

    print_r($alfreds_id);
    print_r($collection->getOne($alfreds_id));
    ?>

Resultado del ejemplo anterior es similar a:

    00005b6b536100000000000000b1

    Array
    (
        [_id] => 00005b6b536100000000000000b1
        [age] => 42
        [job] => Butler
        [name] => Alfred
    )

# Collection::getSchema

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

Collection::getSchema — Devuelve el objeto esquema

### Descripción

public function mysql_xdevapi\Collection::getSchema(): Schema Object

Devuelve el objeto esquema que contiene la colección.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El objeto esquema en caso de éxito, o `null` si el objeto no puede ser recuperado para la colección dada.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Collection::getSchema()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    var_dump($collection->getSchema());
    ?>

Resultado del ejemplo anterior es similar a:

    object(mysql_xdevapi\Schema)#9 (1) {
      ["name"]=>
      string(11) "addressbook"
    }

# Collection::getSession

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

Collection::getSession — Devuelve el objeto session

### Descripción

public function mysql_xdevapi\Collection::getSession(): Session

Devuelve un nuevo objeto Session a partir del objeto Collection.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un objeto Session.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Collection::getSession()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    // ...

    $newsession = $collection->getSession();

    var_dump($session);
    var_dump($newsession);
    ?>

Resultado del ejemplo anterior es similar a:

    object(mysql_xdevapi\Session)#1 (0) {
    }
    object(mysql_xdevapi\Session)#4 (0) {
    }

# Collection::modify

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

Collection::modify — Modifica los documentos de la colección

### Descripción

public function mysql_xdevapi\Collection::modify(string `$search_condition`): mysql_xdevapi\CollectionModify

Modifica los documentos de una colección que cumplen con condiciones de búsqueda específicas. Se permiten varias operaciones y se soporta la ligadura de argumentos.

### Parámetros

`search_condition`

  Debe ser una expresión SQL válida utilizada para hacer coincidir los documentos a modificar. Esta expresión puede ser tan simple como `true`, que coincide con todos los documentos, o puede utilizar funciones y operadores tales como `'CAST(_id AS SIGNED) >= 10'`, `'age MOD 2 = 0 OR age MOD 3 = 0'`, o `'_id IN ["2","5","7","10"]'`.

### Valores devueltos

SI la operación no se ejecuta, entonces la función devolverá un objeto Modify que puede ser utilizado para añadir operaciones de modificación adicionales.

Si la operación de modificación se ejecuta, entonces el objeto devuelto contendrá el resultado de la operación.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Collection::modify()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $collection->add('{"name": "Bob",    "age": 19, "job": "Painter"}')->execute();

    // Añade dos nuevos trabajos para todos los Painters: Artist y Crafter
    $collection
      ->modify("job in ('Butler', 'Painter')")
      ->arrayAppend('job', 'Artist')
      ->arrayAppend('job', 'Crafter')
      ->execute();

    // Elimina el campo 'beer' de todos los documentos con edad menor a 21
    $collection
      ->modify('age < 21')
      ->unset(['beer'])
      ->execute();
    ?>

# Collection::remove

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

Collection::remove — Elimina documentos de la colección

### Descripción

public function mysql_xdevapi\Collection::remove(string `$search_condition`): mysql_xdevapi\CollectionRemove

Elimina documentos de una colección que cumplen con condiciones de búsqueda específicas. Se permiten varias operaciones, y la ligadura de argumentos.

### Parámetros

`search_condition`

  Debe ser una expresión SQL válida utilizada para hacer coincidir los documentos a modificar. Esta expresión puede ser tan simple como `true`, que coincide con todos los documentos, o puede utilizar funciones y operadores tales como `'CAST(_id AS SIGNED) >= 10'`, `'age MOD 2 = 0 OR age MOD 3 = 0'`, o `'_id IN ["2","5","7","10"]'`.

### Valores devueltos

Si la operación no se ejecuta, entonces la función devolverá un objeto Remove que puede ser utilizado para añadir operaciones de eliminación adicionales.

SI la operación de eliminación se ejecuta, entonces el objeto devuelto contendrá el resultado de la operación.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Collection::remove()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $collection->add('{"name": "Bob",    "age": 19, "job": "Painter"}')->execute();

    // Elimina todos los painters
    $collection
      ->remove("job in ('Painter')")
      ->execute();

    // Elimina el butler más viejo
    $collection
      ->remove("job in ('Butler')")
      ->sort('age desc')
      ->limit(1)
      ->execute();

    // Elimina el registro con la edad más alta
    $collection
      ->remove('true')
      ->sort('age desc')
      ->limit(1)
      ->execute();
    ?>

# Collection::removeOne

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

Collection::removeOne — Elimina un documento de la colección

### Descripción

public function mysql_xdevapi\Collection::removeOne(string `$id`): mysql_xdevapi\Result

Elimina un documento de la colección con el ID correspondiente. Esto es un atajo para `Collection.remove("_id = :id").bind("id", id).execute()`.

### Parámetros

`id`

  El identificador del documento de la colección a eliminar. Generalmente es el _id generado por el servidor MySQL al añadir el registro.

### Valores devueltos

Un objeto Result que puede ser utilizado para consultar el número de elementos afectados o el número de advertencias generadas por la operación.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Collection::removeOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();

    // Normalmente el _id es conocido por otros medios,
    // pero para este ejemplo, recuperemos el identificador generado y utilicémoslo
    $ids       = $result->getGeneratedIds();
    $alfred_id = $ids[0];

    $result = $collection->removeOne($alfred_id);

    if(!$result->getAffectedItemsCount()) {
        echo "Alfred con id $alfred_id no fue eliminado.";
    } else {
        echo "Adiós, Alfred, puedes llevarte el _id $alfred_id contigo.";
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Adiós, Alfred, puedes llevarte el _id 00005b6b536100000000000000cb contigo.

# Collection::replaceOne

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

Collection::replaceOne — Reemplaza un documento de la colección

### Descripción

public function mysql_xdevapi\Collection::replaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result

Modifica (o reemplaza) el documento identificado por ID, si existe.

### Parámetros

`id`

  El identificador del documento a reemplazar o actualizar. Típicamente es el _id generado por el servidor MySQL al añadir el registro.

`doc`

  El documento de la colección a actualizar o reemplazar correspondiente al argumento id.

  Este documento puede ser un objeto documento o un string JSON válido que describa el nuevo documento.

### Valores devueltos

Un objeto Result que puede ser utilizado para consultar el número de elementos afectados y el número de advertencias generadas por la operación.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Collection::replaceOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();

    // Normalmente el _id es conocido por otros medios,
    // pero para este ejemplo, recuperemos el identificador generado y utilicémoslo
    $ids       = $result->getGeneratedIds();
    $alfred_id = $ids[0];

    // ...

    $alfred = $collection->getOne($alfred_id);
    $alfred['age'] = 81;
    $alfred['job'] = 'Guru';

    $collection->replaceOne($alfred_id, $alfred);

    ?>

## Tabla de contenidos

- Collection::add — Añade un documento a la colección
- Collection::addOrReplaceOne — Añade o reemplaza un documento de la colección
- Collection::__construct — Constructor de Collection
- Collection::count — Devuelve el número de documentos
- Collection::createIndex — Crear un índice de colección
- Collection::dropIndex — Elimina un índice de colección
- Collection::existsInDatabase — Verifica si la colección existe en la base de datos
- Collection::find — Búsqueda de documento
- Collection::getName — Devuelve el nombre de la colección
- Collection::getOne — Devuelve un documento
- Collection::getSchema — Devuelve el objeto esquema
- Collection::getSession — Devuelve el objeto session
- Collection::modify — Modifica los documentos de la colección
- Collection::remove — Elimina documentos de la colección
- Collection::removeOne — Elimina un documento de la colección
- Collection::replaceOne — Reemplaza un documento de la colección

# Clase CollectionAdd

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\CollectionAdd implements mysql_xdevapi\Executable {
/* Métodos */
public function execute(): mysql_xdevapi\Result
}

# CollectionAdd::__construct

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

CollectionAdd::__construct — Constructor de CollectionAdd

### Descripción

private function mysql_xdevapi\CollectionAdd::__construct()

Se utiliza para añadir un documento a una colección; se llama desde un objeto Collection.

### Parámetros

Esta función no contiene ningún parámetro.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionAdd::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    // Añade dos documentos
    $collection
      ->add('{"name": "Fred",  "age": 21, "job": "Construction"}')
      ->execute();

    $collection
      ->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')
      ->execute();

    // Añade dos documentos utilizando un solo objeto JSON
    $result = $collection
      ->add(
        '{"name": "Bernie",
          "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
          "hobbies": ["Sports","Making cupcakes"]}',
        '{"name": "Jane",
          "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
          "hobbies": ["Walking","Making pies"]}')
      ->execute();

    // Recupera una lista de ID generados por el último add()
    $ids = $result->getGeneratedIds();
    print_r($ids);

    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => 00005b6b53610000000000000056
        [1] => 00005b6b53610000000000000057
    )

### Notas

> Nota:

> Un identificador único _id es generado por MySQL Server 8.0 o superior, como se demuestra en el ejemplo. El campo _id debe ser definido manualmente si se utiliza MySQL Server 5.7.

# CollectionAdd::execute

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

CollectionAdd::execute — Ejecuta la declaración

### Descripción

public function mysql_xdevapi\CollectionAdd::execute(): mysql_xdevapi\Result

El método execute es requerido para enviar la solicitud de operación CRUD al servidor MySQL.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un objeto Result que puede ser utilizado para verificar el estado de la operación, como el número de filas afectadas.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionAdd::execute()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    // Añade dos documentos
    $collection
      ->add('{"name": "Fred",  "age": 21, "job": "Construction"}')
      ->execute();

    $collection
      ->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')
      ->execute();

    // Añade dos documentos utilizando un solo objeto JSON
    $result = $collection
      ->add(
        '{"name": "Bernie",
          "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
          "hobbies": ["Sports","Making cupcakes"]}',
        '{"name": "Jane",
          "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
          "hobbies": ["Walking","Making pies"]}')
      ->execute();

    // Recupera una lista de ID generados por el último add()
    $ids = $result->getGeneratedIds();
    print_r($ids);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => 00005b6b53610000000000000056
        [1] => 00005b6b53610000000000000057
    )

## Tabla de contenidos

- CollectionAdd::__construct — Constructor de CollectionAdd
- CollectionAdd::execute — Ejecuta la declaración

# Clase CollectionFind

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\CollectionFind implements mysql_xdevapi\Executable, mysql_xdevapi\CrudOperationBindable, mysql_xdevapi\CrudOperationLimitable, mysql_xdevapi\CrudOperationSortable {
/* Métodos */
public function bind(array `$placeholder_values`): mysql_xdevapi\CollectionFind
public function execute(): mysql_xdevapi\DocResult
public function fields(string `$projection`): mysql_xdevapi\CollectionFind
public function groupBy(string `$sort_expr`): mysql_xdevapi\CollectionFind
public function having(string `$sort_expr`): mysql_xdevapi\CollectionFind
public function limit(int `$rows`): mysql_xdevapi\CollectionFind
public function lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind
public function lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind
public function offset(int `$position`): mysql_xdevapi\CollectionFind
public function sort(string `$sort_expr`): mysql_xdevapi\CollectionFind
}

# CollectionFind::bind

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

CollectionFind::bind — Liga un valor a un argumento de consulta

### Descripción

public function mysql_xdevapi\CollectionFind::bind(array `$placeholder_values`): mysql_xdevapi\CollectionFind

Esto permite ligar un argumento al espacio reservado en la condición de búsqueda de la operación find. El espacio reservado tiene la forma de :NOMBRE donde ':' es un prefijo común que siempre debe existir antes de cualquier NOMBRE. NOMBRE es el nombre real del espacio reservado. La función bind acepta una lista de espacios reservados si varias entidades deben ser sustituidas en la condición de búsqueda.

### Parámetros

`placeholder_values`

  Los valores a sustituir en la condición de búsqueda; se permiten varios valores y se pasan en forma de array donde "NOMBRE_ESPACIO_RESERVADO => VALOR_ESPACIO_RESERVADO".

### Valores devueltos

Un objeto CollectionFind, o encadenado con execute() para devolver un objeto Result.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionFind::bind()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $result = $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->execute();

    var_dump($result->fetchAll());
    ?>

Resultado del ejemplo anterior es similar a:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000cf"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }
    }

# CollectionFind::__construct

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

CollectionFind::__construct — Constructor de CollectionFind

### Descripción

private function mysql_xdevapi\CollectionFind::__construct()

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Ejemplos

Ejemplo #1 Ejemplo de CollectionFind

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $result = $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->execute();

    var_dump($result->fetchAll());
    ?>

Resultado del ejemplo anterior es similar a:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000cf"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }
    }

# CollectionFind::execute

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

CollectionFind::execute — Ejecuta la declaración

### Descripción

public function mysql_xdevapi\CollectionFind::execute(): mysql_xdevapi\DocResult

Ejecuta la operación de búsqueda; esta funcionalidad permite el encadenamiento de métodos.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un objeto mysql_xdevapi\DocResult, que puede ser utilizado para recuperar los resultados, o para interrogar el estado de la operación.

### Ejemplos

Ejemplo #1 Ejemplo de CollectionFind

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->execute();

    var_dump($result->fetchAll());
    ?>

Resultado del ejemplo anterior es similar a:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000cf"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }
    }

# CollectionFind::fields

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

CollectionFind::fields — Define el filtro de campo de documento

### Descripción

public function mysql_xdevapi\CollectionFind::fields(string `$projection`): mysql_xdevapi\CollectionFind

Define las columnas para la consulta a devolver. Si no se define, se utilizan todas las columnas.

### Parámetros

`projection`

  Puede ser una cadena única o un array de cadenas identificando las columnas a devolver para cada documento que coincida con la condición de búsqueda.

### Valores devueltos

Un objeto CollectionFind que puede ser utilizado para un procesamiento posterior.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionFind::fields()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->fields('name')
      ->execute();

    var_dump($result->fetchAll());
    ?>

Resultado del ejemplo anterior es similar a:

    array(1) {
      [0]=>
      array(1) {
        ["name"]=>
        string(6) "Alfred"
      }
    }

# CollectionFind::groupBy

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

CollectionFind::groupBy — Define los criterios de agrupación

### Descripción

public function mysql_xdevapi\CollectionFind::groupBy(string `$sort_expr`): mysql_xdevapi\CollectionFind

Esta función puede ser utilizada para agrupar el conjunto de resultados por una o más columnas. Es a menudo utilizada con funciones de agregación tales como `COUNT`, `MAX`, `MIN`, `SUM` etc.

### Parámetros

`sort_expr`

  La o las columnas que deben ser utilizadas para la operación de agrupación, esto puede ser una cadena única o un array de argumentos de string, uno para cada columna.

### Valores devueltos

Un objeto CollectionFind que puede ser utilizado para un procesamiento posterior.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionFind::groupBy()

    <?php

    // Asumiendo que $coll es un objeto Collection válido

    // Extrae todos los documentos de la Collection y agrupa los resultados por el campo 'name'
    $res = $coll->find()->groupBy('name')->execute();

    ?>

# CollectionFind::having

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

CollectionFind::having — Define la condición para las funciones de agregación

### Descripción

public function mysql_xdevapi\CollectionFind::having(string `$sort_expr`): mysql_xdevapi\CollectionFind

Esta función puede ser utilizada después de la operación 'field' para hacer una selección sobre los documentos a extraer.

### Parámetros

`sort_expr`

  Debe ser una expresión SQL válida, el uso de funciones de agregación está permitido.

### Valores devueltos

Un objeto CollectionFind que puede ser utilizado para un procesamiento posterior.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionFind::having()

    <?php

    //Asumiendo que $coll es un objeto Collection válido

    //Encuentra todos los documentos para los cuales la edad es mayor que 40,
    //Solo las columnas 'name' y 'age' son devueltas en el objeto Result
    $res = $coll->find()->fields(['name','age'])->having('age > 40')->execute();

    ?>

# CollectionFind::limit

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

CollectionFind::limit — Limita el número de documentos devueltos

### Descripción

public function mysql_xdevapi\CollectionFind::limit(int `$rows`): mysql_xdevapi\CollectionFind

Define el número máximo de documentos a devolver.

### Parámetros

`rows`

  El número máximo de documentos.

### Valores devueltos

Un objeto mysql_xdevapi\CollectionFind que puede ser utilizado para un procesamiento posterior; encadene con el método execute() para devolver un objeto DocResult.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionFind::limit()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();
    $create
      ->add('{"name": "Reginald", "age": 42, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->limit(1)
      ->execute();

    var_dump($result->fetchAll());
    ?>

Resultado del ejemplo anterior es similar a:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000f3"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }
    }

# CollectionFind::lockExclusive

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

CollectionFind::lockExclusive — Ejecuta la operación con un BLOQUEO EXCLUSIVO

### Descripción

public function mysql_xdevapi\CollectionFind::lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind

Bloquea el documento de manera exclusiva. Mientras el documento está bloqueado, otras transacciones no pueden actualizar el documento, utilizar `SELECT ... LOCK IN SHARE MODE`, o leer los datos en ciertos niveles de aislamiento de transacción. Las lecturas coherentes ignoran los bloqueos establecidos en los registros que existen en la vista de lectura.

Para evitar problemas de concurrencia, es lógico utilizar esta función con el método mysql_xdevapi\Collection::modify(). Esencialmente, esta función utiliza bloqueos de línea para serializar el acceso a las líneas.

### Parámetros

`lock_waiting_option`

  Una opción de espera opcional. Por omisión, es `MYSQLX_LOCK_DEFAULT`. Los valores válidos son estas constantes:

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### Valores devueltos

Devuelve un objeto CollectionFind que puede ser utilizado para un procesamiento posterior.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionFind::lockExclusive()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $session->startTransaction();

    $result = $collection
      ->find("age > 50")
      ->lockExclusive()
      ->execute();

    // ... realizar una operación sobre el objeto

    // Validar la transacción y desbloquear el documento
    $session->commit();
    ?>

# CollectionFind::lockShared

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

CollectionFind::lockShared — Ejecuta la operación con un BLOQUEO COMPARTIDO

### Descripción

public function mysql_xdevapi\CollectionFind::lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind

Permite el compartimiento de documentos entre múltiples transacciones que están bloqueadas en modo compartido.

Otras sesiones pueden leer las filas, pero no pueden modificarlas hasta que su transacción no haya sido validada.

Si una de estas filas ha sido modificada por otra transacción que no ha sido validada, la consulta esperará a que esta transacción termine para poder utilizar los últimos valores.

### Parámetros

`lock_waiting_option`

  Una opción de espera opcional. Por omisión, es `MYSQLX_LOCK_DEFAULT`. Los valores válidos son estas constantes:

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### Valores devueltos

Un objeto CollectionFind que puede ser utilizado para un tratamiento ulterior.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionFind::lockShared()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $session->startTransaction();

    $result = $collection
      ->find("age > 50")
      ->lockShared()
      ->execute();

    // ... leer el objeto en modo compartido

    // Validar la transacción y desbloquear el documento
    $session->commit();
    ?>

# CollectionFind::offset

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

CollectionFind::offset — Ignorar un número dado de elementos a devolver

### Descripción

public function mysql_xdevapi\CollectionFind::offset(int `$position`): mysql_xdevapi\CollectionFind

Ignora (desplaza) un número dado de elementos que de otro modo serían devueltos por la operación find. Utilícese con el método limit().

Definir un desplazamiento mayor que el tamaño del conjunto de resultados da un conjunto vacío.

### Parámetros

`position`

  El número de elementos a ignorar para la operación limit().

### Valores devueltos

Un objeto CollectionFind que puede ser utilizado para un tratamiento ulterior.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionFind::offset()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();
    $create
      ->add('{"name": "Reginald", "age": 42, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find()
      ->sort('age asc')
      ->offset(1)
      ->limit(1)
      ->execute();

    var_dump($result->fetchAll());
    ?>

Resultado del ejemplo anterior es similar a:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000f3"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }
    }

# CollectionFind::sort

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

CollectionFind::sort — Define los criterios de ordenación

### Descripción

public function mysql_xdevapi\CollectionFind::sort(string `$sort_expr`): mysql_xdevapi\CollectionFind

Ordena el conjunto de resultados por el campo seleccionado en el argumento sort_expr. Los órdenes permitidos son ASC (Ascendente) o DESC (Descendente). Esta operación es equivalente a la operación 'ORDER BY' SQL y sigue el mismo conjunto de reglas.

### Parámetros

`sort_expr`

  Una o más expresiones de ordenación pueden ser proporcionadas. La evaluación se realiza de izquierda a derecha, y cada expresión está separada por una coma.

### Valores devueltos

Un objeto CollectionFind que puede ser utilizado para ejecutar el comando, o para añadir operaciones adicionales.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionFind::sort()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();
    $create
      ->add('{"name": "Reginald", "age": 42, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find()
      ->sort('job desc', 'age asc')
      ->execute();

    var_dump($result->fetchAll());
    ?>

Resultado del ejemplo anterior es similar a:

    array(2) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b53610000000000000106"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }
      [1]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b53610000000000000107"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }
    }

## Tabla de contenidos

- CollectionFind::bind — Liga un valor a un argumento de consulta
- CollectionFind::__construct — Constructor de CollectionFind
- CollectionFind::execute — Ejecuta la declaración
- CollectionFind::fields — Define el filtro de campo de documento
- CollectionFind::groupBy — Define los criterios de agrupación
- CollectionFind::having — Define la condición para las funciones de agregación
- CollectionFind::limit — Limita el número de documentos devueltos
- CollectionFind::lockExclusive — Ejecuta la operación con un BLOQUEO EXCLUSIVO
- CollectionFind::lockShared — Ejecuta la operación con un BLOQUEO COMPARTIDO
- CollectionFind::offset — Ignorar un número dado de elementos a devolver
- CollectionFind::sort — Define los criterios de ordenación

# Clase CollectionModify

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\CollectionModify implements mysql_xdevapi\Executable, mysql_xdevapi\CrudOperationBindable, mysql_xdevapi\CrudOperationLimitable, mysql_xdevapi\CrudOperationSkippable, mysql_xdevapi\CrudOperationSortable {
/* Métodos */
public function arrayAppend(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function arrayInsert(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function bind(array `$placeholder_values`): mysql_xdevapi\CollectionModify
public function execute(): mysql_xdevapi\Result
public function limit(int `$rows`): mysql_xdevapi\CollectionModify
public function patch(string `$document`): mysql_xdevapi\CollectionModify
public function replace(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function set(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function skip(int `$position`): mysql_xdevapi\CollectionModify
public function sort(string `$sort_expr`): mysql_xdevapi\CollectionModify
public function unset(array `$fields`): mysql_xdevapi\CollectionModify
}

# CollectionModify::arrayAppend

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

CollectionModify::arrayAppend — Añade un elemento a un campo de array

### Descripción

public function mysql_xdevapi\CollectionModify::arrayAppend(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Añade un elemento a un campo de un documento, ya que varios elementos de un campo se representan como un array. A diferencia de arrayInsert(), arrayAppend() siempre añade el nuevo elemento al final del array, mientras que arrayInsert() puede definir la ubicación.

### Parámetros

`collection_field`

  El identificador del campo donde se inserta el nuevo elemento.

`expression_or_literal`

  El nuevo elemento a insertar al final del array del campo del documento.

### Valores devueltos

Un objeto CollectionModify que puede ser utilizado para ejecutar el comando, o para añadir operaciones adicionales.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionModify::arrayAppend()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name in ('Bernie', 'Jane')")
      ->arrayAppend('traits', 'Happy')
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b5361000000000000010c
                [name] => Bernie
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                        [3] => Happy
                    )
            )
    )

# CollectionModify::arrayInsert

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

CollectionModify::arrayInsert — Inserta un elemento en un campo de array

### Descripción

public function mysql_xdevapi\CollectionModify::arrayInsert(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Añade un elemento a un campo de un documento, ya que varios elementos de un campo están representados en forma de array. A diferencia de mysql_xdevapi\CollectionModify::arrayAppend() este método permite especificar dónde se inserta el nuevo elemento definiendo después de qué elemento, mientras que mysql_xdevapi\CollectionModify::arrayAppend() siempre añade el nuevo elemento al final del array.

### Parámetros

`collection_field`

  Identifica el elemento del array después del cual se insertará el nuevo elemento. El formato de este parámetro es `FIELD_NAME[ INDEX ]` donde FIELD_NAME es el nombre del campo del documento donde se añadirá el elemento, y INDEX es el INDEX del elemento en el campo.

  El INDEX está basado en cero, por lo que el primer elemento del array tiene un índice de 0.

`expression_or_literal`

  El nuevo elemento a insertar después de FIELD_NAME[ INDEX ]

### Valores devueltos

Un objeto CollectionModify que puede ser utilizado para ejecutar el comando, o para añadir operaciones adicionales.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionModify::arrayInsert()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name in ('Bernie', 'Jane')")
      ->arrayInsert('traits[1]', 'Happy')
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b5361000000000000010d
                [name] => Bernie
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Happy
                        [2] => Brother
                        [3] => Human
                    )
            )
    )

# CollectionModify::bind

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

CollectionModify::bind — Liga un valor a un parámetro de consulta

### Descripción

public function mysql_xdevapi\CollectionModify::bind(array `$placeholder_values`): mysql_xdevapi\CollectionModify

Liga un parámetro a un espacio reservado en la condición de búsqueda de la operación de modificación.

El espacio reservado tiene la forma de :NOMBRE donde ':' es un prefijo común que siempre debe existir antes de cualquier NOMBRE donde NOMBRE es el nombre del espacio reservado. El método bind acepta una lista de espacios reservados si varias entidades deben ser sustituidas en la condición de búsqueda de la operación de modificación.

### Parámetros

`placeholder_values`

  Los valores de espacio reservado a sustituir en la condición de búsqueda. Se permiten varios valores y deben ser pasados en forma de array de mapeos NOMBRE_ESPACIO_RESERVADO->VALOR_ESPACIO_RESERVADO.

### Valores devueltos

Un objeto CollectionModify que puede ser utilizado para ejecutar el comando, o para añadir operaciones adicionales.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionModify::bind()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name = :name")
      ->bind(['name' => 'Bernie'])
      ->arrayAppend('traits', 'Happy')
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b53610000000000000110
                [name] => Bernie
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                        [3] => Happy
                    )
            )
    )

# CollectionModify::__construct

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

CollectionModify::__construct — Constructor de CollectionModify

### Descripción

private function mysql_xdevapi\CollectionModify::__construct()

Modifica (actualiza) una colección y es instanciado por el método mysql_xdevapi\Collection::modify().

### Parámetros

Esta función no contiene ningún parámetro.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionModify::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name in ('Bernie', 'Jane')")
      ->arrayAppend('traits', 'Happy')
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b5361000000000000010c
                [name] => Bernie
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                        [3] => Happy
                    )
            )
    )

# CollectionModify::execute

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

CollectionModify::execute — Ejecuta la operación de modificación

### Descripción

public function mysql_xdevapi\CollectionModify::execute(): mysql_xdevapi\Result

El método execute es requerido para enviar la solicitud de operación CRUD al servidor MySQL.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un objeto Result que puede ser utilizado para verificar el estado de la operación, como el número de filas afectadas.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionModify::execute()

    <?php

    /* ... */

    ?>

# CollectionModify::limit

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

CollectionModify::limit — Limita el número de documentos modificados

### Descripción

public function mysql_xdevapi\CollectionModify::limit(int `$rows`): mysql_xdevapi\CollectionModify

Limita el número de documentos modificados por esta operación. Combina eventualmente con skip() para definir un valor de desplazamiento.

### Parámetros

`rows`

  El número máximo de documentos a modificar.

### Valores devueltos

Un objeto CollectionModify.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionModify::limit()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
    $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();
    $collection->add('{"name": "Betty", "age": 24, "job": "Teacher"}')->execute();

    $collection
      ->modify("job = :job")
      ->bind(['job' => 'Teacher'])
      ->set('job', 'Principal')
      ->limit(1)
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b53610000000000000118
                [age] => 21
                [job] => Construction
                [name] => Fred
            )
        [1] => Array
            (
                [_id] => 00005b6b53610000000000000119
                [age] => 23
                [job] => Principal
                [name] => Wilma
            )
        [2] => Array
            (
                [_id] => 00005b6b5361000000000000011a
                [age] => 24
                [job] => Teacher
                [name] => Betty
            )
    )

# CollectionModify::patch

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

CollectionModify::patch — Corrige un documento

### Descripción

public function mysql_xdevapi\CollectionModify::patch(string `$document`): mysql_xdevapi\CollectionModify

Toma un objeto patch y lo aplica sobre uno o varios documentos, y puede actualizar varias propiedades del documento.

### Parámetros

`document`

  Un documento con las propiedades a aplicar a los documentos correspondientes.

### Valores devueltos

Un objeto CollectionModify.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionModify::patch()

    <?php

    $res = $coll->modify('"Programmatore" IN job')->patch('{"Hobby" : "Programmare"}')->execute();

    ?>

# CollectionModify::replace

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

CollectionModify::replace — Reemplaza un campo de documento

### Descripción

public function mysql_xdevapi\CollectionModify::replace(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Reemplaza (actualiza) un valor de campo dado por uno nuevo.

### Parámetros

`collection_field`

  La ruta de acceso del documento del elemento a definir.

`expression_or_literal`

  El valor a definir en el atributo especificado.

### Valores devueltos

Un objeto CollectionModify.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionModify::replace()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name = :name")
      ->bind(['name' => 'Bernie'])
      ->replace("name", "Bern")
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b5361000000000000011b
                [name] => Bern
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                    )
            )
    )

# CollectionModify::set

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

CollectionModify::set — Define un atributo de documento

### Descripción

public function mysql_xdevapi\CollectionModify::set(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Define o actualiza atributos en documentos de una colección.

### Parámetros

`collection_field`

  La ruta (nombre) del documento del elemento a definir.

`expression_or_literal`

  El valor a definir en el atributo especificado.

### Valores devueltos

Un objeto CollectionModify.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionModify::set()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name = :name")
      ->bind(['name' => 'Bernie'])
      ->set("name", "Bern")
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b53610000000000000111
                [name] => Bern
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                    )
            )
    )

# CollectionModify::skip

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

CollectionModify::skip — Ignorar los elementos

### Descripción

public function mysql_xdevapi\CollectionModify::skip(int `$position`): mysql_xdevapi\CollectionModify

Ignora los N primeros elementos que de otro modo serían devueltos por una operación de búsqueda. Si el número de elementos ignorados es superior al tamaño del conjunto de resultados, entonces la operación de búsqueda devuelve un conjunto vacío.

### Parámetros

`position`

  El número de elementos a ignorar.

### Valores devueltos

Un objeto CollectionModify para ser utilizado en un procesamiento posterior.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionModify::skip()

    <?php

    $coll->modify('age > :age')->sort('age desc')->unset(['age'])->bind(['age' => 20])->limit(4)->skip(1)->execute();

    ?>

# CollectionModify::sort

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

CollectionModify::sort — Define los criterios de ordenación

### Descripción

public function mysql_xdevapi\CollectionModify::sort(string `$sort_expr`): mysql_xdevapi\CollectionModify

Ordena el conjunto de resultados por el campo seleccionado en el argumento sort_expr. Los órdenes permitidos son ASC (Ascendente) o DESC (Descendente). Esta operación es equivalente a la operación SQL 'ORDER BY' y sigue el mismo conjunto de reglas.

### Parámetros

`sort_expr`

  Una o más expresiones de ordenación pueden ser proporcionadas. La evaluación se realiza de izquierda a derecha y cada expresión debe estar separada por una coma.

### Valores devueltos

Un objeto CollectionModify que puede ser utilizado para un procesamiento posterior.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionModify::sort()

    <?php

    $res = $coll->modify('true')->sort('name desc', 'age asc')->limit(4)->set('Married', 'NO')->execute();

    ?>

# CollectionModify::unset

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

CollectionModify::unset — Elimina el valor de los campos del documento

### Descripción

public function mysql_xdevapi\CollectionModify::unset(array `$fields`): mysql_xdevapi\CollectionModify

Elimina los atributos de los documentos en una colección.

### Parámetros

`fields`

  Los atributos a eliminar de los documentos en una colección.

### Valores devueltos

Un objeto CollectionModify que puede ser utilizado para un procesamiento posterior.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionModify::unset()

    <?php

    $res = $coll->modify('job like :job_name')->unset(["age", "name"])->bind(['job_name' => 'Plumber'])->execute();

    ?>

## Tabla de contenidos

- CollectionModify::arrayAppend — Añade un elemento a un campo de array
- CollectionModify::arrayInsert — Inserta un elemento en un campo de array
- CollectionModify::bind — Liga un valor a un parámetro de consulta
- CollectionModify::__construct — Constructor de CollectionModify
- CollectionModify::execute — Ejecuta la operación de modificación
- CollectionModify::limit — Limita el número de documentos modificados
- CollectionModify::patch — Corrige un documento
- CollectionModify::replace — Reemplaza un campo de documento
- CollectionModify::set — Define un atributo de documento
- CollectionModify::skip — Ignorar los elementos
- CollectionModify::sort — Define los criterios de ordenación
- CollectionModify::unset — Elimina el valor de los campos del documento

# Clase CollectionRemove

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\CollectionRemove implements mysql_xdevapi\Executable, mysql_xdevapi\CrudOperationBindable, mysql_xdevapi\CrudOperationLimitable, mysql_xdevapi\CrudOperationSortable {
/* Métodos */
public function bind(array `$placeholder_values`): mysql_xdevapi\CollectionRemove
public function execute(): mysql_xdevapi\Result
public function limit(int `$rows`): mysql_xdevapi\CollectionRemove
public function sort(string `$sort_expr`): mysql_xdevapi\CollectionRemove
}

# CollectionRemove::bind

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

CollectionRemove::bind — Liga un valor a un argumento

### Descripción

public function mysql_xdevapi\CollectionRemove::bind(array `$placeholder_values`): mysql_xdevapi\CollectionRemove

Liga un argumento al espacio reservado en la condición de búsqueda de la operación de eliminación.

El espacio reservado tiene la forma :NAME donde ':' es un prefijo común que siempre debe existir antes de cualquier NAME donde NAME es el nombre del espacio reservado. El método bind acepta una lista de espacios reservados si varias entidades deben ser sustituidas en la condición de búsqueda de la operación de eliminación.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`placeholder_values`

  El valor del espacio reservado a sustituir en la condición de búsqueda. Se permiten varios valores y deben ser pasados en forma de un array de mapeos NOMBRE_ESPACIO_RESERVADO->VALOR_ESPACIO_RESERVADO.

### Valores devueltos

Un objeto CollectionRemove que puede ser utilizado para ejecutar el comando, o para añadir operaciones adicionales.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionRemove::bind()

    <?php

    $res = $coll->remove('age > :age_from and age < :age_to')->bind(['age_from' => 20, 'age_to' => 50])->limit(7)->execute();

    ?>

# CollectionRemove::__construct

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

CollectionRemove::__construct — Constructor de CollectionRemove

### Descripción

private function mysql_xdevapi\CollectionRemove::__construct()

Elimina los documentos de la colección y es instanciado por el método mysql_xdevapi\Collection::remove().

### Parámetros

Esta función no contiene ningún parámetro.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Collection::remove()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $collection->add('{"name": "Bob",    "age": 19, "job": "Painter"}')->execute();

    // Elimina todos los pintores
    $collection
      ->remove("job in ('Painter')")
      ->execute();

    // Elimina el mayordomo más viejo
    $collection
      ->remove("job in ('Butler')")
      ->sort('age desc')
      ->limit(1)
      ->execute();

    // Elimina el registro con la edad más baja
    $collection
      ->remove('true')
      ->sort('age desc')
      ->limit(1)
      ->execute();
    ?>

# CollectionRemove::execute

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

CollectionRemove::execute — Ejecuta la operación de eliminación

### Descripción

public function mysql_xdevapi\CollectionRemove::execute(): mysql_xdevapi\Result

La función execute debe ser invocada para desencadenar el envío de la solicitud de operación CRUD al servidor por parte del cliente.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Objeto Result.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionRemove::execute()

    <?php

    $res = $coll->remove('true')->sort('age desc')->limit(2)->execute();

    ?>

# CollectionRemove::limit

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

CollectionRemove::limit — Limita el número de documentos a eliminar

### Descripción

public function mysql_xdevapi\CollectionRemove::limit(int `$rows`): mysql_xdevapi\CollectionRemove

Define el número máximo de documentos a eliminar.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`rows`

  El número máximo de documentos a eliminar.

### Valores devueltos

Devuelve un objeto CollectionRemove que puede ser utilizado para ejecutar el comando, o para añadir operaciones adicionales.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionRemove::limit()

    <?php

    $res = $coll->remove('job in (\'Barista\', \'Programmatore\', \'Ballerino\', \'Programmatrice\')')->limit(5)->sort(['age desc', 'name asc'])->execute();

    ?>

# CollectionRemove::sort

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

CollectionRemove::sort — Define el criterio de ordenación

### Descripción

public function mysql_xdevapi\CollectionRemove::sort(string `$sort_expr`): mysql_xdevapi\CollectionRemove

Ordena el conjunto de resultados por el campo seleccionado en el argumento sort_expr. Los órdenes permitidos son ASC (Ascending) o DESC (Descending). Esta operación es equivalente a la operación SQL 'ORDER BY' y sigue el mismo conjunto de reglas.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`sort_expr`

  Una o más expresiones de ordenación pueden ser proporcionadas. La evaluación se realiza de izquierda a derecha, y cada expresión está separada por una coma.

### Valores devueltos

Un objeto CollectionRemove que puede ser utilizado para ejecutar el comando, o para añadir operaciones adicionales.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CollectionRemove::sort()

    <?php

    $res = $coll->remove('true')->sort('age desc')->limit(2)->execute();

    ?>

## Tabla de contenidos

- CollectionRemove::bind — Liga un valor a un argumento
- CollectionRemove::__construct — Constructor de CollectionRemove
- CollectionRemove::execute — Ejecuta la operación de eliminación
- CollectionRemove::limit — Limita el número de documentos a eliminar
- CollectionRemove::sort — Define el criterio de ordenación

# Clase ColumnResult

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\ColumnResult {
/* Métodos */
public function getCharacterSetName(): string
public function getCollationName(): string
public function getColumnLabel(): string
public function getColumnName(): string
public function getFractionalDigits(): int
public function getLength(): int
public function getSchemaName(): string
public function getTableLabel(): string
public function getTableName(): string
public function getType(): int
public function isNumberSigned(): int
public function isPadded(): int
}

# ColumnResult::__construct

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

ColumnResult::__construct — Constructor de ColumnResult

### Descripción

private function mysql_xdevapi\ColumnResult::__construct()

Devuelve los metadatos de columna, tales como su conjunto de caracteres; esto es instanciado por el método mysql_xdevapi\RowResult::getColumns().

### Parámetros

Esta función no contiene ningún parámetro.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\ColumnResult::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS nonsense")->execute();
    $session->sql("CREATE DATABASE nonsense")->execute();
    $session->sql("CREATE TABLE nonsense.numbers (hello int, world float unsigned)")->execute();
    $session->sql("INSERT INTO  nonsense.numbers values (42, 42)")->execute();

    $schema = $session->getSchema("nonsense");
    $table  = $schema->getTable("numbers");

    $result1 = $table->select('hello','world')->execute();

    // Devuelve un array de objetos ColumnResult
    $columns = $result1->getColumns();

    foreach ($columns as $column) {
        echo "\nColumn label " , $column->getColumnLabel();
        echo " is type "       , $column->getType();
        echo " and is ", ($column->isNumberSigned() === 0) ? "unsigned." : "signed.";
    }

    // O bien
    $result2 = $session->sql("SELECT * FROM nonsense.numbers")->execute();

    // Devuelve un array de objetos FieldMetadata
    print_r($result2->getColumns());

Resultado del ejemplo anterior es similar a:

    Column label hello is type 19 and is signed.
    Column label world is type 4  and is unsigned.

    Array
    (
        [0] => mysql_xdevapi\FieldMetadata Object
            (
                [type] => 1
                [type_name] => SINT
                [name] => hello
                [original_name] => hello
                [table] => numbers
                [original_table] => numbers
                [schema] => nonsense
                [catalog] => def
                [collation] => 0
                [fractional_digits] => 0
                [length] => 11
                [flags] => 0
                [content_type] => 0
            )
        [1] => mysql_xdevapi\FieldMetadata Object
            (
                [type] => 6
                [type_name] => FLOAT
                [name] => world
                [original_name] => world
                [table] => numbers
                [original_table] => numbers
                [schema] => nonsense
                [catalog] => def
                [collation] => 0
                [fractional_digits] => 31
                [length] => 12
                [flags] => 1
                [content_type] => 0
            )
    )

# ColumnResult::getCharacterSetName

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

ColumnResult::getCharacterSetName — Devuelve el conjunto de caracteres

### Descripción

public function mysql_xdevapi\ColumnResult::getCharacterSetName(): string

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\ColumnResult::getCharacterSetName()

    <?php

    /* ... */

    ?>

# ColumnResult::getCollationName

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

ColumnResult::getCollationName — Devuelve el nombre de la intercalación

### Descripción

public function mysql_xdevapi\ColumnResult::getCollationName(): string

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\ColumnResult::getCollationName()

    <?php

    /* ... */

    ?>

# ColumnResult::getColumnLabel

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

ColumnResult::getColumnLabel — Devuelve la etiqueta de columna

### Descripción

public function mysql_xdevapi\ColumnResult::getColumnLabel(): string

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\ColumnResult::getColumnLabel()

    <?php

    /* ... */

    ?>

# ColumnResult::getColumnName

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

ColumnResult::getColumnName — Devuelve el nombre de la columna

### Descripción

public function mysql_xdevapi\ColumnResult::getColumnName(): string

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\ColumnResult::getColumnName()

    <?php

    /* ... */

    ?>

# ColumnResult::getFractionalDigits

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

ColumnResult::getFractionalDigits — Devuelve la longitud de los dígitos fraccionarios

### Descripción

public function mysql_xdevapi\ColumnResult::getFractionalDigits(): int

Recupera el número de dígitos fraccionarios para la columna.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\ColumnResult::getFractionalDigits()

    <?php

    /* ... */

    ?>

# ColumnResult::getLength

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

ColumnResult::getLength — Devuelve la longitud del campo

### Descripción

public function mysql_xdevapi\ColumnResult::getLength(): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\ColumnResult::getLength()

    <?php

    /* ... */

    ?>

# ColumnResult::getSchemaName

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

ColumnResult::getSchemaName — Devuelve el nombre del esquema

### Descripción

public function mysql_xdevapi\ColumnResult::getSchemaName(): string

Recupera el nombre del esquema donde la columna está almacenada.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\ColumnResult::getSchemaName()

    <?php

    /* ... */

    ?>

# ColumnResult::getTableLabel

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

ColumnResult::getTableLabel — Devuelve la etiqueta de la tabla

### Descripción

public function mysql_xdevapi\ColumnResult::getTableLabel(): string

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\ColumnResult::getTableLabel()

    <?php

    /* ... */

    ?>

# ColumnResult::getTableName

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

ColumnResult::getTableName — Devuelve el nombre de la tabla

### Descripción

public function mysql_xdevapi\ColumnResult::getTableName(): string

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El nombre de la tabla para la columna.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\ColumnResult::getTableName()

    <?php

    /* ... */

    ?>

# ColumnResult::getType

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

ColumnResult::getType — Devuelve el tipo de columna

### Descripción

public function mysql_xdevapi\ColumnResult::getType(): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\ColumnResult::getType()

    <?php

    /* ... */

    ?>

# ColumnResult::isNumberSigned

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

ColumnResult::isNumberSigned — Indica si el tipo es signado

### Descripción

public function mysql_xdevapi\ColumnResult::isNumberSigned(): int

Recupera la información de columna de una tabla e instancia el método mysql_xdevapi\RowResult::getColumns().

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

`true` si una columna dada es de tipo signado.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\ColumnResult::isNumberSigned()

    <?php

    /* ... */

    ?>

# ColumnResult::isPadded

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

ColumnResult::isPadded — Verifica si el campo tiene un relleno

### Descripción

public function mysql_xdevapi\ColumnResult::isPadded(): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

`true` si una columna dada tiene un relleno.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\ColumnResult::isPadded()

    <?php

    /* ... */

    ?>

## Tabla de contenidos

- ColumnResult::__construct — Constructor de ColumnResult
- ColumnResult::getCharacterSetName — Devuelve el conjunto de caracteres
- ColumnResult::getCollationName — Devuelve el nombre de la intercalación
- ColumnResult::getColumnLabel — Devuelve la etiqueta de columna
- ColumnResult::getColumnName — Devuelve el nombre de la columna
- ColumnResult::getFractionalDigits — Devuelve la longitud de los dígitos fraccionarios
- ColumnResult::getLength — Devuelve la longitud del campo
- ColumnResult::getSchemaName — Devuelve el nombre del esquema
- ColumnResult::getTableLabel — Devuelve la etiqueta de la tabla
- ColumnResult::getTableName — Devuelve el nombre de la tabla
- ColumnResult::getType — Devuelve el tipo de columna
- ColumnResult::isNumberSigned — Indica si el tipo es signado
- ColumnResult::isPadded — Verifica si el campo tiene un relleno

# Interfaz CrudOperationBindable

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\CrudOperationBindable {
/* Métodos */
abstract public function bind(array `$placeholder_values`): mysql_xdevapi\CrudOperationBindable
}

# CrudOperationBindable::bind

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

CrudOperationBindable::bind — Liga un valor a un espacio reservado

### Descripción

abstract public function mysql_xdevapi\CrudOperationBindable::bind(array `$placeholder_values`): mysql_xdevapi\CrudOperationBindable

Liga un valor a un espacio reservado específico.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`placeholder_values`

  El nombre de los espacios reservados y los valores a ligar.

### Valores devueltos

Un objeto CrudOperationBindable

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CrudOperationBindable::bind()

    <?php

    $res = $coll->modify('name like :name')->arrayInsert('job[0]', 'Calciatore')->bind(['name' => 'ENTITY'])->execute();
    $res = $table->delete()->orderby('age desc')->where('age < 20 and age > 12 and name != :name')->bind(['name' => 'Tierney'])->limit(2)->execute();

    ?>

## Tabla de contenidos

- CrudOperationBindable::bind — Liga un valor a un espacio reservado

# Interfaz CrudOperationLimitable

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\CrudOperationLimitable {
/* Métodos */
abstract public function limit(int `$rows`): mysql_xdevapi\CrudOperationLimitable
}

# CrudOperationLimitable::limit

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

CrudOperationLimitable::limit — Define el límite de resultados

### Descripción

abstract public function mysql_xdevapi\CrudOperationLimitable::limit(int `$rows`): mysql_xdevapi\CrudOperationLimitable

Define el número máximo de resultados o documentos a devolver.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`rows`

  El número máximo de resultados o documentos.

### Valores devueltos

Un objeto CrudOperationLimitable.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CrudOperationLimitable::limit()

    <?php

    $res = $coll->find()->fields(['name as n','age as a','job as j'])->groupBy('j')->limit(11)->execute();
    $res = $table->update()->set('age',69)->where('age > 15 and age < 22')->limit(4)->orderby(['age asc','name desc'])->execute();

    ?>

## Tabla de contenidos

- CrudOperationLimitable::limit — Define el límite de resultados

# Interfaz CrudOperationSkippable

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\CrudOperationSkippable {
/* Métodos */
abstract public function skip(int `$skip`): mysql_xdevapi\CrudOperationSkippable
}

# CrudOperationSkippable::skip

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

CrudOperationSkippable::skip — El número de operaciones a ignorar

### Descripción

abstract public function mysql_xdevapi\CrudOperationSkippable::skip(int `$skip`): mysql_xdevapi\CrudOperationSkippable

Ignora este número de registros en la operación devuelta.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`skip`

  El número de elementos a ignorar.

### Valores devueltos

Un objeto CrudOperationSkippable.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CrudOperationSkippable::skip()

    <?php

    $res = $coll->find('job like \'Programmatore\'')->limit(1)->skip(3)->sort('age asc')->execute();

    ?>

## Tabla de contenidos

- CrudOperationSkippable::skip — El número de operaciones a ignorar

# Interfaz CrudOperationSortable

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\CrudOperationSortable {
/* Métodos */
abstract public function sort(string `$sort_expr`): mysql_xdevapi\CrudOperationSortable
}

# CrudOperationSortable::sort

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

CrudOperationSortable::sort — Ordena los resultados

### Descripción

abstract public function mysql_xdevapi\CrudOperationSortable::sort(string `$sort_expr`): mysql_xdevapi\CrudOperationSortable

Ordena el conjunto de resultados por el campo seleccionado en el argumento sort_expr. Los órdenes permitidos son ASC (Ascendente) o DESC (Descendente). Esta operación es equivalente a la operación SQL 'ORDER BY' y sigue el mismo conjunto de reglas.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`sort_expr`

  Una o más expresiones de ordenación pueden ser proporcionadas. La evaluación se realiza de izquierda a derecha, y cada expresión está separada por una coma.

### Valores devueltos

Un objeto CrudOperationSortable.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\CrudOperationSortable::sort()

    <?php

    $res = $coll->find('job like \'Cavia\'')->sort('age desc', '_id desc')->execute();

    ?>

## Tabla de contenidos

- CrudOperationSortable::sort — Ordena los resultados

# Interfaz DatabaseObject

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\DatabaseObject {
/* Métodos */
abstract public function existsInDatabase(): bool
abstract public function getName(): string
abstract public function getSession(): mysql_xdevapi\Session
}

# DatabaseObject::existsInDatabase

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

DatabaseObject::existsInDatabase — Verifica si el objeto existe en la base de datos

### Descripción

abstract public function mysql_xdevapi\DatabaseObject::existsInDatabase(): bool

Verifica si el objeto de base de datos hace referencia a un objeto que existe en la base de datos.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si el objeto existe en la base de datos, de lo contrario `false` si no existe.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\DatabaseObject::existsInDatabase()

    <?php

    $existInDb = $dbObj->existsInDatabase();

    ?>

# DatabaseObject::getName

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

DatabaseObject::getName — Devuelve el nombre del objeto

### Descripción

abstract public function mysql_xdevapi\DatabaseObject::getName(): string

Recupera el nombre de este objeto de base de datos.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El nombre de este objeto de base de datos.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\DatabaseObject::getName()

    <?php

    $dbObjName = $dbObj->getName();

    ?>

# DatabaseObject::getSession

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

DatabaseObject::getSession — Devuelve el nombre de la sesión

### Descripción

abstract public function mysql_xdevapi\DatabaseObject::getSession(): mysql_xdevapi\Session

Recupera la sesión asociada al objeto de base de datos.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El objeto Session.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\DatabaseObject::getSession()

    <?php

    $session = $dbObj->getSession();

    ?>

## Tabla de contenidos

- DatabaseObject::existsInDatabase — Verifica si el objeto existe en la base de datos
- DatabaseObject::getName — Devuelve el nombre del objeto
- DatabaseObject::getSession — Devuelve el nombre de la sesión

# Clase DocResult

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\DocResult implements mysql_xdevapi\BaseResult, Traversable {
/* Métodos */
public function fetchAll(): array
public function fetchOne(): array
public function getWarnings(): Array
public function getWarningsCount(): int
}

# DocResult::__construct

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

DocResult::__construct — Constructor de DocResult

### Descripción

private function mysql_xdevapi\DocResult::__construct()

Recupera los resultados y las advertencias del documento, y es instanciado por CollectionFind.

### Parámetros

Esta función no contiene ningún parámetro.

### Ejemplos

Ejemplo #1 Un ejemplo de DocResult

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Devuelve un objeto DocResult
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->limit(1)
      ->execute();

    var_dump($result->fetchAll());
    ?>

Resultado del ejemplo anterior es similar a:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000f3"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }
    }

# DocResult::fetchAll

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

DocResult::fetchAll — Devuelve todas las filas

### Descripción

public function mysql_xdevapi\DocResult::fetchAll(): array

Devuelve todas las filas de un conjunto de resultados.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array numérico con todos los resultados de la consulta; cada resultado es un array asociativo. Un array vacío es devuelto si no hay filas presentes.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\DocResult::fetchAll()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Devuelve un objeto DocResult
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    var_dump($result->fetchAll());
    ?>

Resultado del ejemplo anterior es similar a:

    array(2) {

      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b53610000000000000123"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }

      [1]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b53610000000000000122"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }

    }

# DocResult::fetchOne

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

DocResult::fetchOne — Devuelve una fila

### Descripción

public function mysql_xdevapi\DocResult::fetchOne(): array

Recupera un resultado de un conjunto de resultados.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El resultado, en forma de array asociativo o `null` si no hay resultado presente.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\DocResult::fetchOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Devuelve un objeto DocResult
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    var_dump($result->fetchOne());
    ?>

Resultado del ejemplo anterior es similar a:

    array(4) {
      ["_id"]=>
      string(28) "00005b6b53610000000000000125"
      ["age"]=>
      int(42)
      ["job"]=>
      string(6) "Butler"
      ["name"]=>
      string(8) "Reginald"
    }

# DocResult::getWarnings

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

DocResult::getWarnings — Devuelve los avisos de la última operación

### Descripción

public function mysql_xdevapi\DocResult::getWarnings(): Array

Recupera los avisos generados por la última operación del servidor MySQL.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array de objetos Warning de la última operación. Cada objeto define un 'message' de error, un 'nivel' de error y un 'code' de error. Un array vacío es devuelto si no hay errores presentes.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\DocResult::getWarnings()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Devuelve un objeto DocResult
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    if (!$result->getWarningsCount()) {
        echo "Hubo un error:\n";
        print_r($result->getWarnings());
        exit;
    }

    var_dump($result->fetchOne());
    ?>

Resultado del ejemplo anterior es similar a:

    Hubo un error:

    Array
    (
        [0] => mysql_xdevapi\Warning Object
            (
                [message] => Algo malo y así sucesivamente
                [level] => 2
                [code] => 1365
            )
        [1] => mysql_xdevapi\Warning Object
            (
                [message] => Algo malo y así sucesivamente
                [level] => 2
                [code] => 1365
            )
    )

# DocResult::getWarningsCount

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

DocResult::getWarningsCount — Devuelve el número de advertencias de la última operación

### Descripción

public function mysql_xdevapi\DocResult::getWarningsCount(): int

Devuelve el número de advertencias generadas por la última operación. Más precisamente, estas advertencias son generadas por el servidor MySQL.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El número de advertencias de la última operación.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\DocResult::getWarningsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Devuelve un objeto DocResult
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    if (!$result->getWarningsCount()) {
        echo "Hubo un error:\n";
        print_r($result->getWarnings());
        exit;
    }

    var_dump($result->fetchOne());
    ?>

Resultado del ejemplo anterior es similar a:

    array(4) {
      ["_id"]=>
      string(28) "00005b6b53610000000000000135"
      ["age"]=>
      int(42)
      ["job"]=>
      string(6) "Butler"
      ["name"]=>
      string(8) "Reginald"
    }

## Tabla de contenidos

- DocResult::__construct — Constructor de DocResult
- DocResult::fetchAll — Devuelve todas las filas
- DocResult::fetchOne — Devuelve una fila
- DocResult::getWarnings — Devuelve los avisos de la última operación
- DocResult::getWarningsCount — Devuelve el número de advertencias de la última operación

# Clase Exception

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\Exception extends RuntimeException implements Throwable {
}

# Interfaz Executable

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\Executable {
/* Métodos */
abstract public function execute(): mysql_xdevapi\Result
}

# Executable::execute

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

Executable::execute — Ejecuta una declaración

### Descripción

abstract public function mysql_xdevapi\Executable::execute(): mysql_xdevapi\Result

Ejecuta la declaración a partir de una operación de colección o de una consulta de tabla; esta funcionalidad permite el encadenamiento de métodos.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Uno de los objetos Result, tales como Result o SqlStatementResult.

### Ejemplos

Ejemplo #1 Ejemplos de execute()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $result_sql = $session->sql("CREATE DATABASE addressbook")->execute();

    var_dump($result_sql);

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("humans");

    $result_collection = $collection->add(
      '{"name": "Jane",
        "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
        "hobbies": ["Walking","Making pies"]}');

    $result_collection_executed = $result_collection->execute();

    var_dump($result_collection);
    var_dump($result_collection_executed);
    ?>

Resultado del ejemplo anterior es similar a:

    object(mysql_xdevapi\SqlStatementResult)#3 (0) {
    }

    object(mysql_xdevapi\CollectionAdd)#5 (0) {
    }

    object(mysql_xdevapi\Result)#7 (0) {
    }

## Tabla de contenidos

- Executable::execute — Ejecuta una declaración

# Clase ExecutionStatus

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\ExecutionStatus {
/* Propiedades */
public $affectedItems;
public $matchedItems;
public $foundItems;
public $lastInsertId;
public $lastDocumentId;
/* Constructor */
private function __construct()
}

## Propiedades

affectedItems

matchedItems

foundItems

lastInsertId

lastDocumentId

# ExecutionStatus::__construct

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

ExecutionStatus::__construct — Constructor de ExecutionStatus

### Descripción

private function mysql_xdevapi\ExecutionStatus::__construct()

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\ExecutionStatus::__construct()

    <?php

    /* ... */

    ?>

## Tabla de contenidos

- ExecutionStatus::__construct — Constructor de ExecutionStatus

# Clase Expression

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\Expression {
/* Propiedades */
public $name;
/* Constructor */
public function __construct(string `$expression`)
}

## Propiedades

name

# Expression::__construct

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

Expression::__construct — Constructor de Expression

### Descripción

public function mysql_xdevapi\Expression::__construct(string `$expression`)

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`expression`

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Expression::__construct()

    <?php

    /* ... */

    ?>

## Tabla de contenidos

- Expression::__construct — Constructor de Expression

# Clase Result

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\Result implements mysql_xdevapi\BaseResult, Traversable {
/* Métodos */
public function getAffectedItemsCount(): int
public function getAutoIncrementValue(): int
public function getGeneratedIds(): array
public function getWarnings(): array
public function getWarningsCount(): int
}

# Result::__construct

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

Result::__construct — Constructor de Result

### Descripción

private function mysql_xdevapi\Result::__construct()

Un objeto que recupera los ID generados, los valores AUTO_INCREMENT y las advertencias, para un conjunto de resultados.

### Parámetros

Esta función no contiene ningún parámetro.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Result::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("
      CREATE TABLE addressbook.names
        (id INT NOT NULL AUTO_INCREMENT, name VARCHAR(30), age INT, PRIMARY KEY (id))
      ")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->insert("name", "age")->values(["Suzanne", 31],["Julie", 43])->execute();
    $result = $table->insert("name", "age")->values(["Suki", 34])->execute();

    $ai = $result->getAutoIncrementValue();
    var_dump($ai);
    ?>

El ejemplo anterior mostrará:

    int(3)

# Result::getAffectedItemsCount

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

Result::getAffectedItemsCount — Devuelve el número de filas afectadas

### Descripción

public function mysql_xdevapi\Result::getAffectedItemsCount(): int

Devuelve el número de filas afectadas por la operación anterior.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El número (como integer) de filas afectadas.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Result::getAffectedItemsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    $result = $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    var_dump( $res->getAffectedItemsCount() );
    ?>

El ejemplo anterior mostrará:

    int(1)

# Result::getAutoIncrementValue

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

Result::getAutoIncrementValue — Devuelve el valor auto-incrementado

### Descripción

public function mysql_xdevapi\Result::getAutoIncrementValue(): int

Devuelve el último valor AUTO_INCREMENT (último identificador insertado).

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El último valor AUTO_INCREMENT.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Result::getAutoIncrementValue()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("
      CREATE TABLE addressbook.names
        (id INT NOT NULL AUTO_INCREMENT, name VARCHAR(30), age INT, PRIMARY KEY (id))
      ")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->insert("name", "age")->values(["Suzanne", 31],["Julie", 43])->execute();
    $result = $table->insert("name", "age")->values(["Suki", 34])->execute();

    $ai = $result->getAutoIncrementValue();
    var_dump($ai);
    ?>

El ejemplo anterior mostrará:

    int(3)

# Result::getGeneratedIds

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

Result::getGeneratedIds — Devuelve los ID generados

### Descripción

public function mysql_xdevapi\Result::getGeneratedIds(): array

Recupera los valores _id generados por la última operación. El campo _id único es generado por el servidor MySQL.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array de _id generados por la última operación, o un array vacío si no hay ninguno.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Result::getGeneratedIds()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    $result = $collection->add(
      '{"name": "Bernie",
        "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
        "hobbies": ["Sports","Making cupcakes"]}',
      '{"name": "Jane",
        "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
        "hobbies": ["Walking","Making pies"]}')->execute();

    $ids = $result->getGeneratedIds();
    var_dump($ids);
    ?>

Resultado del ejemplo anterior es similar a:

    array(2) {
      [0]=>
      string(28) "00005b6b53610000000000000064"
      [1]=>
      string(28) "00005b6b53610000000000000065"
    }

# Result::getWarnings

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

Result::getWarnings — Devuelve las advertencias de la última operación

### Descripción

public function mysql_xdevapi\Result::getWarnings(): array

Devuelve las advertencias de la última operación Result.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array de objetos Warning de la última operación. Cada objeto define un mensaje de error, un nivel de error y un código de error. Se devuelve un array vacío si no hay errores.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\RowResult::getWarnings()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();
    $warnings = $res->getWarnings();

    print_r($warnings);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
        [1] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
    )

# Result::getWarningsCount

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

Result::getWarningsCount — Devuelve el número de advertencias de la última operación

### Descripción

public function mysql_xdevapi\Result::getWarningsCount(): int

Devuelve el número de advertencias generadas por la última operación.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El número de advertencias generadas por la última operación.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\RowResult::getWarningsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS foo")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();

    echo $res->getWarningsCount();
    ?>

Resultado del ejemplo anterior es similar a:

    2

## Tabla de contenidos

- Result::__construct — Constructor de Result
- Result::getAffectedItemsCount — Devuelve el número de filas afectadas
- Result::getAutoIncrementValue — Devuelve el valor auto-incrementado
- Result::getGeneratedIds — Devuelve los ID generados
- Result::getWarnings — Devuelve las advertencias de la última operación
- Result::getWarningsCount — Devuelve el número de advertencias de la última operación

# Clase RowResult

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\RowResult implements mysql_xdevapi\BaseResult, Traversable {
/* Métodos */
public function fetchAll(): array
public function fetchOne(): array
public function getColumnsCount(): int
public function getColumnNames(): array
public function getColumns(): array
public function getWarnings(): array
public function getWarningsCount(): int
}

# RowResult::__construct

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

RowResult::__construct — Constructor de RowResult

### Descripción

private function mysql_xdevapi\RowResult::__construct()

Representa el conjunto de resultados obtenidos a partir de la consulta de la base de datos.

### Parámetros

Esta función no contiene ningún parámetro.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\RowResult::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->where('age > 18')->execute()->fetchAll();

    print_r($row);

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# RowResult::fetchAll

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

RowResult::fetchAll — Devuelve todas las filas del resultado

### Descripción

public function mysql_xdevapi\RowResult::fetchAll(): array

Recupera todas las filas del conjunto de resultados.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array numérico con todos los resultados de la consulta; cada resultado es un array asociativo. Se devuelve un array vacío si no hay filas presentes.

### Ejemplos

Ejemplo #1 mysql_xdevapi\RowResult::fetchAll() example

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->execute()->fetchAll();

    print_r($row);

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# RowResult::fetchOne

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

RowResult::fetchOne — Devuelve una fila del resultado

### Descripción

public function mysql_xdevapi\RowResult::fetchOne(): array

Recupera una fila del conjunto de resultados.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El resultado, en forma de array asociativo o `null` si no hay resultado presente.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\RowResult::fetchOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->where('age < 40')->execute()->fetchOne();

    print_r($row);

Resultado del ejemplo anterior es similar a:

    Array
    (
        [name] => Sam
        [age] => 33
    )

# RowResult::getColumnsCount

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

RowResult::getColumnsCount — Devuelve el número de columnas

### Descripción

public function mysql_xdevapi\RowResult::getColumnsCount(): int

Devuelve el número de columnas presentes en el conjunto de resultados.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El número de columnas; 0 si no hay ninguna.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.14 | El método ha sido renombrado de getColumnCount() a getColumnsCount().

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\RowResult::getColumnsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $sql = $session->sql("SELECT * from addressbook.names")->execute();

    echo $sql->getColumnsCount();

Resultado del ejemplo anterior es similar a:

    2

# RowResult::getColumnNames

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

RowResult::getColumnNames — Devuelve el nombre de todas las columnas

### Descripción

public function mysql_xdevapi\RowResult::getColumnNames(): array

Devuelve el nombre de las columnas presentes en el conjunto de resultados.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array numérico de nombres de columnas de tabla, o un array vacío si el conjunto de resultados está vacío.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\RowResult::getColumnNames()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $sql = $session->sql("SELECT * from addressbook.names")->execute();

    $colnames = $sql->getColumnNames();

    print_r($colnames);

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => name
        [1] => age
    )

# RowResult::getColumns

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

RowResult::getColumns — Devuelve los metadatos de las columnas

### Descripción

public function mysql_xdevapi\RowResult::getColumns(): array

Devuelve los metadatos de las columnas presentes en el conjunto de resultados.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array de FieldMetadata que representa las columnas del resultado, o un array vacío si el conjunto de resultados está vacío.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\RowResult::getColumns()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $sql = $session->sql("SELECT * from addressbook.names")->execute();

    $cols = $sql->getColumns();

    print_r($cols);

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => mysql_xdevapi\FieldMetadata Object
            (
                [type] => 7
                [type_name] => BYTES
                [name] => name
                [original_name] => name
                [table] => names
                [original_table] => names
                [schema] => addressbook
                [catalog] => def
                [collation] => 255
                [fractional_digits] => 0
                [length] => 65535
                [flags] => 0
                [content_type] => 0
            )
        [1] => mysql_xdevapi\FieldMetadata Object
            (
                [type] => 1
                [type_name] => SINT
                [name] => age
                [original_name] => age
                [table] => names
                [original_table] => names
                [schema] => addressbook
                [catalog] => def
                [collation] => 0
                [fractional_digits] => 0
                [length] => 11
                [flags] => 0
                [content_type] => 0
            )
    )

# RowResult::getWarnings

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

RowResult::getWarnings — Devuelve las advertencias de la última operación

### Descripción

public function mysql_xdevapi\RowResult::getWarnings(): array

Devuelve las advertencias de la última operación RowResult.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array de objetos Warning de la última operación. Cada objeto define un mensaje de error 'message', un nivel de error 'level', y un código de error 'code'. Un array vacío es devuelto si no hay errores presentes.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\RowResult::getWarnings()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();
    $warnings = $res->getWarnings();

    print_r($warnings);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
        [1] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
    )

# RowResult::getWarningsCount

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

RowResult::getWarningsCount — Devuelve el número de advertencias de la última operación

### Descripción

public function mysql_xdevapi\RowResult::getWarningsCount(): int

Devuelve el número de advertencias generadas por la última operación.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El número de advertencias generadas por la última operación.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\RowResult::getWarningsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS foo")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();

    echo $res->getWarningsCount();
    ?>

Resultado del ejemplo anterior es similar a:

    2

## Tabla de contenidos

- RowResult::__construct — Constructor de RowResult
- RowResult::fetchAll — Devuelve todas las filas del resultado
- RowResult::fetchOne — Devuelve una fila del resultado
- RowResult::getColumnsCount — Devuelve el número de columnas
- RowResult::getColumnNames — Devuelve el nombre de todas las columnas
- RowResult::getColumns — Devuelve los metadatos de las columnas
- RowResult::getWarnings — Devuelve las advertencias de la última operación
- RowResult::getWarningsCount — Devuelve el número de advertencias de la última operación

# Clase Schema

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\Schema implements mysql_xdevapi\DatabaseObject {
/* Propiedades */
public $name;
/* Métodos */
public function createCollection(string `$name`, string `$validate` = ?): mysql_xdevapi\Collection
public function dropCollection(string `$collection_name`): bool
public function existsInDatabase(): bool
public function getCollection(string `$name`): mysql_xdevapi\Collection
public function getCollectionAsTable(string `$name`): mysql_xdevapi\Table
public function getCollections(): array
public function getName(): string
public function getSession(): mysql_xdevapi\Session
public function getTable(string `$name`): mysql_xdevapi\Table
public function getTables(): array
}

## Propiedades

name

# Schema::__construct

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

Schema::__construct — Constructor de schema

### Descripción

private function mysql_xdevapi\Schema::__construct()

El objeto Schema proporciona acceso completo al esquema (base de datos).

### Parámetros

Esta función no contiene ningún parámetro.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Schema::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();
    $session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

    $schema = $session->getSchema("food");
    $schema->createCollection("trees");

    print_r($schema->gettables());
    print_r($schema->getcollections());

Resultado del ejemplo anterior es similar a:

    Array
    (
        [fruit] => mysql_xdevapi\Table Object
            (
                [name] => fruit
            )
    )
    Array
    (
        [trees] => mysql_xdevapi\Collection Object
            (
                [name] => trees
            )
    )

# Schema::createCollection

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

Schema::createCollection — Añade una colección al esquema

### Descripción

public function mysql_xdevapi\Schema::createCollection(string `$name`, string `$validate` = ?): mysql_xdevapi\Collection

Crea una colección en el esquema.

### Parámetros

`name`

  El nombre de la colección.

`validate`

  La definición de validación, como un objeto JSON.

### Valores devueltos

El objeto Collection.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.20 | Adición del argumento opcional validate.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Schema::createCollection()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();
    $session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

    $schema = $session->getSchema("food");
    $schema->createCollection("trees");

    print_r($schema->gettables());
    print_r($schema->getcollections());

Resultado del ejemplo anterior es similar a:

    Array
    (
        [fruit] => mysql_xdevapi\Table Object
            (
                [name] => fruit
            )
    )
    Array
    (
        [trees] => mysql_xdevapi\Collection Object
            (
                [name] => trees
            )
    )

Ejemplo #2 Ejemplo de mysql_xdevapi\Schema::createCollection()

    <?php
     $collection = $schema->createCollection("mycollection", '{
        "validation": {
            "level": "strict",
            "schema": {
                "id": "http://json-schema.org/geo",
                "description": "A geographical coordinate",
                "type": "object",
                "properties": {
                    "latitude": {
                        "type": "number"
                    },
                    "longitude": {
                        "type": "number"
                    }
                },
                "required": ["latitude", "longitude"]
            }
        }
    }');
    // Éxito
    $collection->add('{"latitude": 10, "longitude": 20}')->execute();

    // Fallo, tipos inválidos (no son números)
    $collection->add('{"latitude": "lat", "longitude": "long"}')->execute();

# Schema::dropCollection

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

Schema::dropCollection — Elimina una colección del esquema

### Descripción

public function mysql_xdevapi\Schema::dropCollection(string `$collection_name`): bool

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`collection_name`

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Schema::dropCollection()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();
    $session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

    $schema = $session->getSchema("food");

    $schema->createCollection("trees");
    $schema->dropCollection("trees");
    $schema->createCollection("buildings");

    print_r($schema->gettables());
    print_r($schema->getcollections());

Resultado del ejemplo anterior es similar a:

    Array
    (
        [fruit] => mysql_xdevapi\Table Object
            (
                [name] => fruit
            )
    )
    Array
    (
        [buildings] => mysql_xdevapi\Collection Object
            (
                [name] => buildings
            )
    )

# Schema::existsInDatabase

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

Schema::existsInDatabase — Verifica si el objeto existe en la base de datos

### Descripción

public function mysql_xdevapi\Schema::existsInDatabase(): bool

Verifica si el objeto actual (esquema, tabla, colección o vista) existe en el objeto esquema.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

`true` si el esquema, la tabla, la colección o la vista aún existe en el esquema, de lo contrario `false`.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Schema::existsInDatabase()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();
    $session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

    $schema = $session->getSchema("food");
    $schema->createCollection("trees");

    // ...

    $trees = $schema->getCollection("trees");

    // ...

    // ¿Esta colección aún está en la base de datos (esquema)?
    if ($trees->existsInDatabase()) {
        echo "Yes, the 'trees' collection is still present.";
    }

Resultado del ejemplo anterior es similar a:

    Yes, the 'trees' collection is still present.

# Schema::getCollection

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

Schema::getCollection — Devuelve una colección del esquema

### Descripción

public function mysql_xdevapi\Schema::getCollection(string `$name`): mysql_xdevapi\Collection

Devuelve una colección del esquema.

### Parámetros

`name`

  El nombre de la colección a recuperar.

### Valores devueltos

El objeto Collection para la colección seleccionada.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Schema::getCollection()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();

    $schema = $session->getSchema("food");
    $schema->createCollection("trees");

    // ...

    $trees = $schema->getCollection("trees");

    var_dump($trees);

Resultado del ejemplo anterior es similar a:

    object(mysql_xdevapi\Collection)#3 (1) {
      ["name"]=>
      string(5) "trees"
    }

# Schema::getCollectionAsTable

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

Schema::getCollectionAsTable — Devuelve una colección como objeto Table

### Descripción

public function mysql_xdevapi\Schema::getCollectionAsTable(string `$name`): mysql_xdevapi\Table

Devuelve una colección, pero como objeto Table en lugar de un objeto Collection.

### Parámetros

`name`

  El nombre de la colección a partir de la cual instanciar un objeto Table.

### Valores devueltos

Un objeto mysql_xdevapi\Table para la colección.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Schema::getCollectionAsTable()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema  = $session->getSchema("addressbook");
    $collect = $schema->createCollection("people");
    $collect->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
    $collect->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    $table      = $schema->getCollectionAsTable("people");
    $collection = $schema->getCollection("people");

    var_dump($table);
    var_dump($collection);

Resultado del ejemplo anterior es similar a:

    object(mysql_xdevapi\Table)#4 (1) {
      ["name"]=>
      string(6) "people"
    }

    object(mysql_xdevapi\Collection)#5 (1) {
      ["name"]=>
      string(6) "people"
    }

# Schema::getCollections

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

Schema::getCollections — Devuelve todas las colecciones del esquema

### Descripción

public function mysql_xdevapi\Schema::getCollections(): array

Recupera una lista de colecciones para este esquema.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array de todas las colecciones de este esquema, donde cada elemento del array es una Collection con el nombre de la colección como clave.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Schema::getCollections()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema  = $session->getSchema("addressbook");
    $collect = $schema->createCollection("people");
    $collect->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
    $collect->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    $collections = $schema->getCollections();
    var_dump($collections);
    ?>

Resultado del ejemplo anterior es similar a:

    array(1) {
      ["people"]=>
      object(mysql_xdevapi\Collection)#4 (1) {
        ["name"]=>
        string(6) "people"
      }
    }

# Schema::getName

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

Schema::getName — Devuelve el nombre del esquema

### Descripción

public function mysql_xdevapi\Schema::getName(): string

Devuelve el nombre del esquema.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El nombre del esquema conectado al objeto esquema, en forma de string.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Schema::getName()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema  = $session->getSchema("addressbook");

    // ...

    var_dump($schema->getName());
    ?>

Resultado del ejemplo anterior es similar a:

    string(11) "addressbook"

# Schema::getSession

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

Schema::getSession — Devuelve la sesión del esquema

### Descripción

public function mysql_xdevapi\Schema::getSession(): mysql_xdevapi\Session

Devuelve un nuevo objeto Session a partir del objeto Schema.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un objeto Session.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Schema::getSession()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema  = $session->getSchema("addressbook");

    // ...

    $newsession = $schema->getSession();

    var_dump($session);
    var_dump($newsession);
    ?>

Resultado del ejemplo anterior es similar a:

    object(mysql_xdevapi\Session)#1 (0) {
    }

    object(mysql_xdevapi\Session)#3 (0) {
    }

# Schema::getTable

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

Schema::getTable — Devuelve la tabla del esquema

### Descripción

public function mysql_xdevapi\Schema::getTable(string `$name`): mysql_xdevapi\Table

Recupera un objeto Table para la tabla proporcionada en el esquema.

### Parámetros

`name`

  El nombre de la tabla.

### Valores devueltos

Un objeto table.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Schema::getTable()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->execute()->fetchAll();

    print_r($row);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# Schema::getTables

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

Schema::getTables — Devuelve las tablas del esquema

### Descripción

public function mysql_xdevapi\Schema::getTables(): array

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array de todas las tablas de este esquema, donde cada elemento del array es un objeto Table con el nombre de la tabla como clave.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Schema::getTables()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $session->sql("CREATE TABLE addressbook.cities(name text, population int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('Portland', 639863), ('Seattle', 704352)")->execute();

    $schema = $session->getSchema("addressbook");
    $tables = $schema->getTables();

    var_dump($tables);
    ?>

Resultado del ejemplo anterior es similar a:

    array(2) {
      ["cities"]=>
      object(mysql_xdevapi\Table)#3 (1) {
        ["name"]=>
        string(6) "cities"
      }

      ["names"]=>
      object(mysql_xdevapi\Table)#4 (1) {
        ["name"]=>
        string(5) "names"
      }
    }

## Tabla de contenidos

- Schema::__construct — Constructor de schema
- Schema::createCollection — Añade una colección al esquema
- Schema::dropCollection — Elimina una colección del esquema
- Schema::existsInDatabase — Verifica si el objeto existe en la base de datos
- Schema::getCollection — Devuelve una colección del esquema
- Schema::getCollectionAsTable — Devuelve una colección como objeto Table
- Schema::getCollections — Devuelve todas las colecciones del esquema
- Schema::getName — Devuelve el nombre del esquema
- Schema::getSession — Devuelve la sesión del esquema
- Schema::getTable — Devuelve la tabla del esquema
- Schema::getTables — Devuelve las tablas del esquema

# Interfaz SchemaObject

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\SchemaObject implements mysql_xdevapi\DatabaseObject {
/* Métodos */
abstract function getSchema(): mysql_xdevapi\Schema
}

# SchemaObject::getSchema

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

SchemaObject::getSchema — Devuelve el objeto esquema

### Descripción

abstract function mysql_xdevapi\SchemaObject::getSchema(): mysql_xdevapi\Schema

Utilizado por otros objetos para recuperar un objeto esquema.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El objeto esquema actual.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Session::getSchema()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $schema  = $session->getSchema("addressbook");

    print_r($schema);

Resultado del ejemplo anterior es similar a:

    mysql_xdevapi\Schema Object
    (
        [name] => addressbook
    )

## Tabla de contenidos

- SchemaObject::getSchema — Devuelve el objeto esquema

# Clase Session

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\Session {
/* Métodos */
public function close(): bool
public function commit(): Object
public function createSchema(string `$schema_name`): mysql_xdevapi\Schema
public function dropSchema(string `$schema_name`): bool
public function generateUUID(): string
public function getDefaultSchema(): ?mysql_xdevapi\Schema
public function getSchema(string `$schema_name`): mysql_xdevapi\Schema
public function getSchemas(): array
public function getServerVersion(): int
public function listClients(): array
public function quoteName(string `$name`): string
public function releaseSavepoint(string `$name`): void
public function rollback(): void
public function rollbackTo(string `$name`): void
public function setSavepoint(string `$name` = ?): string
public function sql(string `$query`): mysql_xdevapi\SqlStatement
public function startTransaction(): void
}

# Session::close

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

Session::close — Cierra la sesión

### Descripción

public function mysql_xdevapi\Session::close(): bool

Cierra la sesión con el servidor.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

`true` si la sesión ha sido cerrada.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Session::close()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $session->close();

# Session::commit

(PHP 4 >= 4.4.0, PHP 5, PHP 7, PHP 8)

Session::commit — Valida la transacción

### Descripción

public function mysql_xdevapi\Session::commit(): Object

Valida la transacción.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un objeto SqlStatementResult.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Session::commit()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("friends");

    $session->startTransaction();

    $collection->add('{"John":42, "Sam":33}')->execute();
    $savepoint = $session->setSavepoint();

    $session->commit();
    $session->close();

# Session::__construct

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

Session::__construct — Descripción del constructor

### Descripción

private function mysql_xdevapi\Session::__construct()

Un objeto Session, tal como iniciado por getSession().

### Parámetros

Esta función no contiene ningún parámetro.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Session::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->close();
    ?>

# Session::createSchema

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

Session::createSchema — Crear un nuevo esquema

### Descripción

public function mysql_xdevapi\Session::createSchema(string `$schema_name`): mysql_xdevapi\Schema

Crear un nuevo esquema.

### Parámetros

`schema_name`

  El nombre del esquema a crear.

### Valores devueltos

Un objeto Schema en caso de éxito, y lanza una excepción en caso de fallo.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Session::createSchema()

    <?php
    $uri  = 'mysqlx://happyuser:password@127.0.0.1:33060/';
    $sess = mysql_xdevapi\getSession($uri);

    try {

        if ($schema = $sess->createSchema('fruit')) {
            echo "Info: I created a schema named 'fruit'\n";
        }

    } catch (Exception $e) {

       echo $e->getMessage();

    }
    ?>

Resultado del ejemplo anterior es similar a:

    Info: I created a schema named 'fruit'

# Session::dropSchema

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

Session::dropSchema — Elimina un esquema

### Descripción

public function mysql_xdevapi\Session::dropSchema(string `$schema_name`): bool

Elimina un esquema (base de datos).

### Parámetros

`schema_name`

  El nombre del esquema a eliminar.

### Valores devueltos

`true` si el esquema es eliminado, o `false` si no existe o no puede ser eliminado.

Un nivel de error `E_WARNING` es generado si el esquema no existe.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Session::dropSchema()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->dropSchema("addressbook");

    $session->close();
    ?>

# Session::generateUUID

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

Session::generateUUID — Devuelve un nuevo UUID

### Descripción

public function mysql_xdevapi\Session::generateUUID(): string

Genera un identificador único universal (Universal Unique IDentifier - UUID) generado según la » RFC 4122.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El UUID; una cadena de 32 caracteres.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Session::generateUuid()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $uuid = $session->generateUuid();

    var_dump($uuid);

Resultado del ejemplo anterior es similar a:

    string(32) "484B18AC7980F8D4FE84613CDA5EE84B"

# Session::getDefaultSchema

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

Session::getDefaultSchema — Devuelve el nombre del esquema predeterminado

### Descripción

public function mysql_xdevapi\Session::getDefaultSchema(): ?mysql_xdevapi\Schema

Recupera el esquema por defecto que se suele establecer en el URI de conexión.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El esquema por defecto definido por la conexión, o `null` si no se ha establecido ninguno.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Session::getSchema()

    <?php
    $uri = "mysqlx://testuser:testpasswd@localhost:33160/testx?ssl-mode=disabled";
    $session = mysql_xdevapi\getSession($uri);

    $schema = $session->getDefaultSchema();
    echo $schema->getName();
    ?>

El ejemplo anterior mostrará:

    testx

# Session::getSchema

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

Session::getSchema — Devuelve un nuevo objeto esquema

### Descripción

public function mysql_xdevapi\Session::getSchema(string `$schema_name`): mysql_xdevapi\Schema

Un nuevo objeto Schema para el nombre de esquema proporcionado.

### Parámetros

`schema_name`

  El nombre del esquema (base de datos) para el cual se obtiene un objeto Schema.

### Valores devueltos

Un objeto Schema.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Session::getSchema()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $schema  = $session->getSchema("addressbook");

    print_r($schema);

Resultado del ejemplo anterior es similar a:

    mysql_xdevapi\Schema Object
    (
        [name] => addressbook
    )

# Session::getSchemas

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

Session::getSchemas — Devuelve los esquemas

### Descripción

public function mysql_xdevapi\Session::getSchemas(): array

Obtiene los objetos esquema para todos los esquemas disponibles para la sesión.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array que contiene objetos que representan todos los esquemas disponibles para la sesión.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Session::getSchemas()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $schemas  = $session->getSchemas();

    print_r($schemas);

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => mysql_xdevapi\Schema Object
            (
                [name] => addressbook
            )
        [1] => mysql_xdevapi\Schema Object
            (
                [name] => information_schema
            )
        ...

# Session::getServerVersion

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

Session::getServerVersion — Devuelve la versión del servidor

### Descripción

public function mysql_xdevapi\Session::getServerVersion(): int

Devuelve la versión del servidor MySQL para la sesión.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

La versión del servidor MySQL para la sesión, en forma de entero como "80012".

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Session::getServerVersion()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $version = $session->getServerVersion();

    var_dump($version);

Resultado del ejemplo anterior es similar a:

    int(80012)

# Session::listClients

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

Session::listClients — Devuelve la lista de clientes

### Descripción

public function mysql_xdevapi\Session::listClients(): array

Devuelve la lista de conexiones de clientes al servidor MySQL de la sesión.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array que contiene los clientes actualmente conectados. Los elementos del array son "client_id", "user", "host" y "sql_session".

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Session::listClients()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $ids = $session->listClients();

    var_dump($ids);
    ?>

Resultado del ejemplo anterior es similar a:

    array(1) {
      [0]=>
      array(4) {
        ["client_id"]=>
        int(61)
        ["user"]=>
        string(4) "root"
        ["host"]=>
        string(9) "localhost"
        ["sql_session"]=>
        int(72)
      }
    }

# Session::quoteName

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

Session::quoteName — Añade comillas

### Descripción

public function mysql_xdevapi\Session::quoteName(string `$name`): string

Una función que pone entre comillas para escapar los nombres e identificadores SQL. Es capaz de escapar el identificador dado conforme a los parámetros de la conexión actual. Esta función de escape no debe ser utilizada para escapar valores.

### Parámetros

`name`

  La cadena a poner entre comillas.

### Valores devueltos

La cadena puesta entre comillas.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Session::quoteName()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $first = "MySQL's test";
    var_dump($first);
    var_dump($session->quoteName($first));

    $second = 'Another `test` "like" `this`';
    var_dump($second);
    var_dump($session->quoteName($second));
    ?>

Resultado del ejemplo anterior es similar a:

    string(12) "MySQL's test"
    string(14) "`MySQL's test`"

    string(28) "Another `test` "like" `this`"
    string(34) "`Another ``test`` "like" ``this```"

# Session::releaseSavepoint

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

Session::releaseSavepoint — Libera el punto de salvaguarda

### Descripción

public function mysql_xdevapi\Session::releaseSavepoint(string `$name`): void

Libera un punto de salvaguarda previamente definido.

### Parámetros

`name`

  El nombre del punto de salvaguarda a liberar.

### Valores devueltos

Un objeto SqlStatementResult.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Session::releaseSavepoint()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("friends");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $session->releaseSavepoint($savepoint);
    $session->rollback();
    ?>

# Session::rollback

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

Session::rollback — Revierte la transacción

### Descripción

public function mysql_xdevapi\Session::rollback(): void

Revierte la transacción.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un objeto SqlStatementResult.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Session::rollback()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("names");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $session->releaseSavepoint($savepoint);
    $session->rollback();
    ?>

# Session::rollbackTo

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

Session::rollbackTo — Anula la transacción hasta el punto de salvaguarda

### Descripción

public function mysql_xdevapi\Session::rollbackTo(string `$name`): void

Anula la transacción hasta el punto de salvaguarda.

### Parámetros

`name`

  El nombre del punto de salvaguarda hasta el cual anular; no sensible a mayúsculas y minúsculas.

### Valores devueltos

Un objeto SqlStatementResult.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Session::rollbackTo()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("names");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint1 = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $savepoint2 = $session->setSavepoint();

    $session->rollbackTo($savepoint1);
    ?>

# Session::setSavepoint

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

Session::setSavepoint — Crear un punto de salvaguarda

### Descripción

public function mysql_xdevapi\Session::setSavepoint(string `$name` = ?): string

Crear un nuevo punto de salvaguarda para la transacción.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`name`

  El nombre del punto de salvaguarda. El nombre se genera automáticamente si el argumento opcional `name` no está definido como 'SAVEPOINT1', 'SAVEPOINT2', etc.

### Valores devueltos

El nombre del punto de salvaguarda.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Session::setSavepoint()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("names");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $session->releaseSavepoint($savepoint);
    $session->rollback();
    ?>

# Session::sql

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

Session::sql — Crear una consulta SQL

### Descripción

public function mysql_xdevapi\Session::sql(string `$query`): mysql_xdevapi\SqlStatement

Crear una declaración SQL nativa. Los espacios reservados son compatibles utilizando la sintaxis nativa "?". Utilizar el método `execute` para ejecutar la declaración SQL.

### Parámetros

`query`

  La declaración SQL a ejecutar.

### Valores devueltos

Un objeto SqlStatement.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Session::sql()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("CREATE DATABASE addressbook")->execute();
    ?>

# Session::startTransaction

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

Session::startTransaction — Inicia una transacción

### Descripción

public function mysql_xdevapi\Session::startTransaction(): void

Inicia una nueva transacción.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un objeto SqlStatementResult.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Session::startTransaction()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("friends");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $session->releaseSavepoint($savepoint);
    $session->rollback();
    ?>

## Tabla de contenidos

- Session::close — Cierra la sesión
- Session::commit — Valida la transacción
- Session::__construct — Descripción del constructor
- Session::createSchema — Crear un nuevo esquema
- Session::dropSchema — Elimina un esquema
- Session::generateUUID — Devuelve un nuevo UUID
- Session::getDefaultSchema — Devuelve el nombre del esquema predeterminado
- Session::getSchema — Devuelve un nuevo objeto esquema
- Session::getSchemas — Devuelve los esquemas
- Session::getServerVersion — Devuelve la versión del servidor
- Session::listClients — Devuelve la lista de clientes
- Session::quoteName — Añade comillas
- Session::releaseSavepoint — Libera el punto de salvaguarda
- Session::rollback — Revierte la transacción
- Session::rollbackTo — Anula la transacción hasta el punto de salvaguarda
- Session::setSavepoint — Crear un punto de salvaguarda
- Session::sql — Crear una consulta SQL
- Session::startTransaction — Inicia una transacción

# Clase SqlStatement

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\SqlStatement {
/* Constantes */
const int EXECUTE_ASYNC = 1;
const int BUFFERED = 2;
/* Propiedades */
public $statement;
/* Métodos */
public function bind(string `$param`): mysql_xdevapi\SqlStatement
public function execute(): mysql_xdevapi\Result
public function getNextResult(): mysql_xdevapi\Result
public function getResult(): mysql_xdevapi\Result
public function hasMoreResults(): bool
}

## Propiedades

statement

## Constantes predefinidas

`mysql_xdevapi\SqlStatement::EXECUTE_ASYNC`

`mysql_xdevapi\SqlStatement::BUFFERED`

# SqlStatement::bind

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

SqlStatement::bind — Liga los argumentos de la instrucción

### Descripción

public function mysql_xdevapi\SqlStatement::bind(string `$param`): mysql_xdevapi\SqlStatement

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`param`

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\SqlStatement::bind()

    <?php

    /* ... */

    ?>

# SqlStatement::__construct

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

SqlStatement::__construct — Descripción del constructor

### Descripción

private function mysql_xdevapi\SqlStatement::__construct()

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\SqlStatement::__construct()

    <?php

    /* ... */

    ?>

# SqlStatement::execute

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

SqlStatement::execute — Ejecuta la operación

### Descripción

public function mysql_xdevapi\SqlStatement::execute(): mysql_xdevapi\Result

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\SqlStatement::execute()

    <?php

    /* ... */

    ?>

# SqlStatement::getNextResult

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

SqlStatement::getNextResult — Devuelve el resultado siguiente

### Descripción

public function mysql_xdevapi\SqlStatement::getNextResult(): mysql_xdevapi\Result

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\SqlStatement::getNextResult()

    <?php

    /* ... */

    ?>

# SqlStatement::getResult

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

SqlStatement::getResult — Devuelve el resultado

### Descripción

public function mysql_xdevapi\SqlStatement::getResult(): mysql_xdevapi\Result

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\SqlStatement::getResult()

    <?php

    /* ... */

    ?>

# SqlStatement::hasMoreResults

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

SqlStatement::hasMoreResults — Verifica si hay más resultados

### Descripción

public function mysql_xdevapi\SqlStatement::hasMoreResults(): bool

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

`true` si quedan objetos por recuperar en el conjunto de resultados.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\SqlStatement::hasMoreResults()

    <?php

    /* ... */

    ?>

## Tabla de contenidos

- SqlStatement::bind — Liga los argumentos de la instrucción
- SqlStatement::__construct — Descripción del constructor
- SqlStatement::execute — Ejecuta la operación
- SqlStatement::getNextResult — Devuelve el resultado siguiente
- SqlStatement::getResult — Devuelve el resultado
- SqlStatement::hasMoreResults — Verifica si hay más resultados

# Clase SqlStatementResult

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\SqlStatementResult implements mysql_xdevapi\BaseResult, Traversable {
/* Métodos */
public function fetchAll(): array
public function fetchOne(): array
public function getAffectedItemsCount(): int
public function getColumnsCount(): int
public function getColumnNames(): array
public function getColumns(): Array
public function getGeneratedIds(): array
public function getLastInsertId(): String
public function getWarnings(): array
public function getWarningCounts(): int
public function hasData(): bool
public function nextResult(): mysql_xdevapi\Result
}

# SqlStatementResult::__construct

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

SqlStatementResult::__construct — Descripción del constructor

### Descripción

private function mysql_xdevapi\SqlStatementResult::__construct()

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\SqlStatementResult::__construct()

    <?php

    /* ... */

    ?>

# SqlStatementResult::fetchAll

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

SqlStatementResult::fetchAll — Devuelve todas las filas del resultado

### Descripción

public function mysql_xdevapi\SqlStatementResult::fetchAll(): array

Recupera todas las filas del conjunto de resultados.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array numérico con todos los resultados de la consulta; cada resultado es un array asociativo. Se devuelve un array vacío si no hay filas presentes.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\SqlStatementResult::fetchAll()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS dbtest")->execute();
    $session->sql("CREATE DATABASE dbtest")->execute();
    $session->sql("CREATE TABLE dbtest.workers(name text, age int, job text)")->execute();
    $session->sql("INSERT INTO dbtest.workers values ('John', 42, 'bricklayer'), ('Sam', 33, 'carpenter')")->execute();

    $schema = $session->getSchema("dbtest");
    $table  = $schema->getTable("workers");

    $rows = $session->sql("SELECT * FROM dbtest.workers")->execute()->fetchAll();

    print_r($rows);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# SqlStatementResult::fetchOne

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

SqlStatementResult::fetchOne — Devuelve una sola línea

### Descripción

public function mysql_xdevapi\SqlStatementResult::fetchOne(): array

Recupera una sola línea del conjunto de resultados.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El resultado, en forma de array asociativo. En caso de ausencia de resultado, null será devuelto.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\SqlStatementResult::fetchOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS dbtest")->execute();
    $session->sql("CREATE DATABASE dbtest")->execute();
    $session->sql("CREATE TABLE dbtest.workers(name text, age int, job text)")->execute();
    $session->sql("INSERT INTO dbtest.workers values ('John', 42, 'bricklayer'), ('Sam', 33, 'carpenter')")->execute();

    $schema = $session->getSchema("dbtest");
    $table  = $schema->getTable("workers");

    $rows = $session->sql("SELECT * FROM dbtest.workers")->execute()->fetchOne();

    print_r($rows);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [name] => John
        [age] => 42
        [job] => bricklayer
    )

# SqlStatementResult::getAffectedItemsCount

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

SqlStatementResult::getAffectedItemsCount — Devuelve el número de filas afectadas

### Descripción

public function mysql_xdevapi\SqlStatementResult::getAffectedItemsCount(): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\SqlStatementResult::getAffectedItemsCount()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getColumnsCount

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

SqlStatementResult::getColumnsCount — Devuelve el número de columnas

### Descripción

public function mysql_xdevapi\SqlStatementResult::getColumnsCount(): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El número de columnas; 0 si no hay ninguna.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.14 | El método fue renombrado de getColumnCount() a getColumnsCount().

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\SqlStatementResult::getColumnsCount()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getColumnNames

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

SqlStatementResult::getColumnNames — Devuelve el nombre de las columnas

### Descripción

public function mysql_xdevapi\SqlStatementResult::getColumnNames(): array

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\SqlStatementResult::getColumnNames()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getColumns

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

SqlStatementResult::getColumns — Devuelve las columnas

### Descripción

public function mysql_xdevapi\SqlStatementResult::getColumns(): Array

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\SqlStatementResult::getColumns()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getGeneratedIds

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

SqlStatementResult::getGeneratedIds — Devuelve los identificadores generados

### Descripción

public function mysql_xdevapi\SqlStatementResult::getGeneratedIds(): array

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array de identificadores generados a partir de la última operación, o un array vacío si no hay ninguno.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\SqlStatementResult::getGeneratedIds()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getLastInsertId

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

SqlStatementResult::getLastInsertId — Devuelve el ID de la última inserción

### Descripción

public function mysql_xdevapi\SqlStatementResult::getLastInsertId(): String

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El ID de la última operación de inserción.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\SqlStatementResult::getLastInsertId()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getWarnings

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

SqlStatementResult::getWarnings — Devuelve las advertencias de la última operación

### Descripción

public function mysql_xdevapi\SqlStatementResult::getWarnings(): array

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array de objetos Warning de la última operación. Cada objeto define un 'message' de error, un 'nivel' de error y un 'code' de error. Un array vacío es devuelto si no hay errores.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\SqlStatementResult::getWarnings()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getWarningsCount

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

SqlStatementResult::getWarningsCount — Devuelve el número de advertencias de la última operación

### Descripción

public function mysql_xdevapi\SqlStatementResult::getWarningCounts(): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El número de advertencias generadas durante la última operación CRUD.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\SqlStatementResult::getWarningsCount()

    <?php

    /* ... */

    ?>

# SqlStatementResult::hasData

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

SqlStatementResult::hasData — Verifica si el resultado contiene datos

### Descripción

public function mysql_xdevapi\SqlStatementResult::hasData(): bool

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

`true` si el resultado contiene datos.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\SqlStatementResult::hasData()

    <?php

    /* ... */

    ?>

# SqlStatementResult::nextResult

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

SqlStatementResult::nextResult — Devuelve el resultado siguiente

### Descripción

public function mysql_xdevapi\SqlStatementResult::nextResult(): mysql_xdevapi\Result

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El objeto Result siguiente del conjunto de resultados.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\SqlStatementResult::nextResult()

    <?php

    /* ... */

    ?>

## Tabla de contenidos

- SqlStatementResult::__construct — Descripción del constructor
- SqlStatementResult::fetchAll — Devuelve todas las filas del resultado
- SqlStatementResult::fetchOne — Devuelve una sola línea
- SqlStatementResult::getAffectedItemsCount — Devuelve el número de filas afectadas
- SqlStatementResult::getColumnsCount — Devuelve el número de columnas
- SqlStatementResult::getColumnNames — Devuelve el nombre de las columnas
- SqlStatementResult::getColumns — Devuelve las columnas
- SqlStatementResult::getGeneratedIds — Devuelve los identificadores generados
- SqlStatementResult::getLastInsertId — Devuelve el ID de la última inserción
- SqlStatementResult::getWarnings — Devuelve las advertencias de la última operación
- SqlStatementResult::getWarningsCount — Devuelve el número de advertencias de la última operación
- SqlStatementResult::hasData — Verifica si el resultado contiene datos
- SqlStatementResult::nextResult — Devuelve el resultado siguiente

# Clase Statement

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\Statement {
/* Constantes */
const int EXECUTE_ASYNC = 1;
const int BUFFERED = 2;
/* Métodos */
public function getNextResult(): mysql_xdevapi\Result
public function getResult(): mysql_xdevapi\Result
public function hasMoreResults(): bool
}

## Constantes predefinidas

`mysql_xdevapi\Statement::EXECUTE_ASYNC`

`mysql_xdevapi\Statement::BUFFERED`

# Statement::__construct

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

Statement::__construct — Descripción del constructor

### Descripción

private function mysql_xdevapi\Statement::__construct()

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Statement::__construct()

    <?php

    /* ... */

    ?>

# Statement::getNextResult

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

Statement::getNextResult — Devuelve el resultado siguiente

### Descripción

public function mysql_xdevapi\Statement::getNextResult(): mysql_xdevapi\Result

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Statement::getNextResult()

    <?php

    /* ... */

    ?>

# Statement::getResult

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

Statement::getResult — Devuelve el resultado

### Descripción

public function mysql_xdevapi\Statement::getResult(): mysql_xdevapi\Result

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Statement::getResult()

    <?php

    /* ... */

    ?>

# Statement::hasMoreResults

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

Statement::hasMoreResults — Verifica si hay más resultados

### Descripción

public function mysql_xdevapi\Statement::hasMoreResults(): bool

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Statement::hasMoreResults()

    <?php

    /* ... */

    ?>

## Tabla de contenidos

- Statement::__construct — Descripción del constructor
- Statement::getNextResult — Devuelve el resultado siguiente
- Statement::getResult — Devuelve el resultado
- Statement::hasMoreResults — Verifica si hay más resultados

# Clase Table

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

Proporciona acceso a la tabla a través de declaraciones INSERT/SELECT/UPDATE/DELETE.

## Sinopsis de la Clase

class mysql_xdevapi\Table implements mysql_xdevapi\SchemaObject {
/* Propiedades */
public $name;
/* Métodos */
public function count(): int
public function delete(): mysql_xdevapi\TableDelete
public function existsInDatabase(): bool
public function getName(): string
public function getSchema(): mysql_xdevapi\Schema
public function getSession(): mysql_xdevapi\Session
public function insert(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableInsert
public function isView(): bool
public function select(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableSelect
public function update(): mysql_xdevapi\TableUpdate
}

## Propiedades

name

# Table::__construct

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

Table::__construct — Constructor de Table

### Descripción

private function mysql_xdevapi\Table::__construct()

Construye un objeto table.

### Parámetros

Esta función no contiene ningún parámetro.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Table::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");
    ?>

# Table::count

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

Table::count — Devuelve el número de filas

### Descripción

public function mysql_xdevapi\Table::count(): int

Recupera el número de filas en la tabla.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El número total de filas en la tabla.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Table::count()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    var_dump($table->count());
    ?>

El ejemplo anterior mostrará:

    int(2)

# Table::delete

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

Table::delete — Elimina filas de la tabla

### Descripción

public function mysql_xdevapi\Table::delete(): mysql_xdevapi\TableDelete

Elimina filas de una tabla.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un objeto TableDelete; utilice el método execute() para ejecutar la consulta de eliminación.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Table::delete()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()->where("name = :name")->orderby("age DESC")->limit(1)->bind(['name' => 'John'])->execute();
    ?>

# Table::existsInDatabase

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

Table::existsInDatabase — Verifica si la tabla existe en la base de datos

### Descripción

public function mysql_xdevapi\Table::existsInDatabase(): bool

Verifica si esta tabla existe en la base de datos.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si la tabla existe en la base de datos, de lo contrario `false` si no existe.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Table::existsInDatabase()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    if ($table->existsInDatabase()) {
      echo "Yes, this table still exists in the session's schema.";
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Yes, this table still exists in the session's schema.

# Table::getName

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

Table::getName — Devuelve el nombre de la tabla

### Descripción

public function mysql_xdevapi\Table::getName(): string

Devuelve el nombre de este objeto base de datos.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El nombre de este objeto base de datos.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Table::getName()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    var_dump($table->getName());
    ?>

Resultado del ejemplo anterior es similar a:

    string(5) "names"

# Table::getSchema

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

Table::getSchema — Devuelve el esquema de la tabla

### Descripción

public function mysql_xdevapi\Table::getSchema(): mysql_xdevapi\Schema

Recupera el esquema asociado a la tabla.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un objeto Schema.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Table::getSchema()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    var_dump($table->getSchema());
    ?>

Resultado del ejemplo anterior es similar a:

    object(mysql_xdevapi\Schema)#9 (1) {
      ["name"]=>
      string(11) "addressbook"
    }

# Table::getSession

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

Table::getSession — Devuelve la sesión de la tabla

### Descripción

public function mysql_xdevapi\Table::getSession(): mysql_xdevapi\Session

Obtiene la sesión asociada a la tabla.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un objeto Session.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Table::getSession()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    var_dump($table->getSession());
    ?>

Resultado del ejemplo anterior es similar a:

    object(mysql_xdevapi\Session)#9 (0) {
    }

# Table::insert

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

Table::insert — Inserta filas en una tabla

### Descripción

public function mysql_xdevapi\Table::insert(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableInsert

Inserta filas en una tabla.

### Parámetros

`columns`

  Las columnas en las que insertar los datos. Puede ser un array con uno o más valores, o un string.

`more_columns`

  Definiciones de columnas adicionales.

### Valores devueltos

Un objeto TableInsert; utilice el método execute() para ejecutar la instrucción de inserción.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Table::insert()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table ->insert("name", "age")
      ->values(["Suzanne", 31],["Julie", 43])
      ->execute();
    ?>

# Table::isView

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

Table::isView — Devuelve si la tabla es una vista

### Descripción

public function mysql_xdevapi\Table::isView(): bool

Determina si el objeto subyacente es una vista o no.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

`true` si el objeto subyacente es una vista, de lo contrario `false`.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Table::isView()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    if ($table->isView()) {
        echo "This is a view.";
    } else {
        echo "This is not a view.";
    }
    ?>

El ejemplo anterior mostrará:

    This is not a view.

# Table::select

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

Table::select — Selecciona filas en una tabla

### Descripción

public function mysql_xdevapi\Table::select(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableSelect

Recupera datos de una tabla.

### Parámetros

`columns`

  Las columnas desde las cuales recuperar los datos. Puede ser un array con uno o más valores, o un string.

`more_columns`

  Definiciones de columnas adicionales.

### Valores devueltos

Un objeto TableSelect; utilice el método execute() para ejecutar la selección y devolver un objeto RowResult.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Table::count()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->execute()->fetchAll();

    print_r($row);

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# Table::update

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

Table::update — Actualiza las filas de la tabla

### Descripción

public function mysql_xdevapi\Table::update(): mysql_xdevapi\TableUpdate

Actualiza las columnas de una tabla.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un objeto TableUpdate; utilice el método execute() para ejecutar la instrucción de actualización.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Table::update()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->update()->set('age',34)->where('name = "Sam"')->limit(1)->execute();
    ?>

## Tabla de contenidos

- Table::__construct — Constructor de Table
- Table::count — Devuelve el número de filas
- Table::delete — Elimina filas de la tabla
- Table::existsInDatabase — Verifica si la tabla existe en la base de datos
- Table::getName — Devuelve el nombre de la tabla
- Table::getSchema — Devuelve el esquema de la tabla
- Table::getSession — Devuelve la sesión de la tabla
- Table::insert — Inserta filas en una tabla
- Table::isView — Devuelve si la tabla es una vista
- Table::select — Selecciona filas en una tabla
- Table::update — Actualiza las filas de la tabla

# Clase TableDelete

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

Una declaración para operaciones de eliminación en una Tabla.

## Sinopsis de la Clase

class mysql_xdevapi\TableDelete implements mysql_xdevapi\Executable {
/* Métodos */
public function bind(array `$placeholder_values`): mysql_xdevapi\TableDelete
public function execute(): mysql_xdevapi\Result
public function limit(int `$rows`): mysql_xdevapi\TableDelete
public function orderby(string `$orderby_expr`): mysql_xdevapi\TableDelete
public function where(string `$where_expr`): mysql_xdevapi\TableDelete
}

# TableDelete::bind

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

TableDelete::bind — Liga los argumentos de la petición de eliminación

### Descripción

public function mysql_xdevapi\TableDelete::bind(array `$placeholder_values`): mysql_xdevapi\TableDelete

Liga un valor a un espacio reservado.

### Parámetros

`placeholder_values`

  El nombre del espacio reservado y el valor a ligar.

### Valores devueltos

Un objeto TableDelete

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableDelete::bind()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("name = :name")
      ->bind(['name' => 'John'])
      ->orderby("age DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::__construct

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

TableDelete::__construct — Constructor de TableDelete

### Descripción

private function mysql_xdevapi\TableDelete::__construct()

Inicializado utilizando el método delete().

### Parámetros

Esta función no contiene ningún parámetro.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableDelete::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("name = :name")
      ->bind(['name' => 'John'])
      ->orderby("age DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::execute

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

TableDelete::execute — Ejecuta la consulta de eliminación

### Descripción

public function mysql_xdevapi\TableDelete::execute(): mysql_xdevapi\Result

Ejecuta la consulta de eliminación.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un objeto Result.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableDelete::execute()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("name = :name")
      ->bind(['name' => 'John'])
      ->orderby("age DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::limit

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

TableDelete::limit — Limita las filas eliminadas

### Descripción

public function mysql_xdevapi\TableDelete::limit(int `$rows`): mysql_xdevapi\TableDelete

Define el número máximo de registros o documentos a eliminar.

### Parámetros

`rows`

  El máximo de registros o documentos a eliminar.

### Valores devueltos

Un objeto TableDelete.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableDelete::limit()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("name = :name")
      ->bind(['name' => 'John'])
      ->orderby("age DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::orderby

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

TableDelete::orderby — Define los criterios de ordenación de la eliminación

### Descripción

public function mysql_xdevapi\TableDelete::orderby(string `$orderby_expr`): mysql_xdevapi\TableDelete

Define las opciones de ordenación para un conjunto de resultados.

### Parámetros

`orderby_expr`

  La definición de la ordenación.

### Valores devueltos

Un objeto TableDelete.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableDelete::orderBy()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("age = :age")
      ->bind(['age' => 42])
      ->orderby("name DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::where

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

TableDelete::where — Define la condición de búsqueda para la eliminación

### Descripción

public function mysql_xdevapi\TableDelete::where(string `$where_expr`): mysql_xdevapi\TableDelete

Define la condición de búsqueda para filtrar.

### Parámetros

`where_expr`

  Define la condición de búsqueda para filtrar los documentos o los registros.

### Valores devueltos

Un objeto TableDelete.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableDelete::where()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("id = :id")
      ->bind(['id' => 42])
      ->limit(1)
      ->execute();

    ?>

## Tabla de contenidos

- TableDelete::bind — Liga los argumentos de la petición de eliminación
- TableDelete::__construct — Constructor de TableDelete
- TableDelete::execute — Ejecuta la consulta de eliminación
- TableDelete::limit — Limita las filas eliminadas
- TableDelete::orderby — Define los criterios de ordenación de la eliminación
- TableDelete::where — Define la condición de búsqueda para la eliminación

# Clase TableInsert

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

Una declaración para operaciones de inserción en una Tabla.

## Sinopsis de la Clase

class mysql_xdevapi\TableInsert implements mysql_xdevapi\Executable {
/* Métodos */
public function execute(): mysql_xdevapi\Result
public function values(array `$row_values`): mysql_xdevapi\TableInsert
}

# TableInsert::__construct

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

TableInsert::__construct — Constructor de TableInsert

### Descripción

private function mysql_xdevapi\TableInsert::__construct()

Inicializado por el método insert().

### Parámetros

Esta función no contiene ningún parámetro.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableInsert::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table
      ->insert("name", "age")
      ->values(["Suzanne", 31],["Julie", 43])
      ->execute();
    ?>

# TableInsert::execute

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

TableInsert::execute — Ejecuta una consulta de inserción

### Descripción

public function mysql_xdevapi\TableInsert::execute(): mysql_xdevapi\Result

Ejecuta la declaración.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un objeto Result.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableInsert::execute()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table
      ->insert("name", "age")
      ->values(["Suzanne", 31],["Julie", 43])
      ->execute();
    ?>

# TableInsert::values

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

TableInsert::values — Añade valores de fila

### Descripción

public function mysql_xdevapi\TableInsert::values(array `$row_values`): mysql_xdevapi\TableInsert

Define los valores a insertar.

### Parámetros

`row_values`

  Los valores (un array) de las columnas a insertar.

### Valores devueltos

Un objeto TableInsert.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableInsert::values()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table
      ->insert("name", "age")
      ->values(["Suzanne", 31],["Julie", 43])
      ->execute();
    ?>

## Tabla de contenidos

- TableInsert::__construct — Constructor de TableInsert
- TableInsert::execute — Ejecuta una consulta de inserción
- TableInsert::values — Añade valores de fila

# Clase TableSelect

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

Una declaración para operaciones de recuperación de entradas en una Tabla.

## Sinopsis de la Clase

class mysql_xdevapi\TableSelect implements mysql_xdevapi\Executable {
/* Métodos */
public function bind(array `$placeholder_values`): mysql_xdevapi\TableSelect
public function execute(): mysql_xdevapi\RowResult
public function groupBy(mixed `$sort_expr`): mysql_xdevapi\TableSelect
public function having(string `$sort_expr`): mysql_xdevapi\TableSelect
public function limit(int `$rows`): mysql_xdevapi\TableSelect
public function lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect
public function lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect
public function offset(int `$position`): mysql_xdevapi\TableSelect
public function orderby(mixed `$sort_expr`, mixed `...$sort_exprs`): mysql_xdevapi\TableSelect
public function where(string `$where_expr`): mysql_xdevapi\TableSelect
}

# TableSelect::bind

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

TableSelect::bind — Liga los argumentos de la petición select

### Descripción

public function mysql_xdevapi\TableSelect::bind(array `$placeholder_values`): mysql_xdevapi\TableSelect

Liga un valor a un espacio reservado específico.

### Parámetros

`placeholder_values`

  El nombre del espacio reservado y el valor a ligar.

### Valores devueltos

Un objeto TableSelect.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableSelect::bind()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name','age')
      ->where('name like :name and age > :age')
      ->bind(['name' => 'John', 'age' => 42])
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::__construct

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

TableSelect::__construct — Constructor de TableSelect

### Descripción

private function mysql_xdevapi\TableSelect::__construct()

Un objeto devuelto por el método select(); utilice execute() para ejecutar la consulta.

### Parámetros

Esta función no contiene ningún parámetro.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableSelect::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name','age')
      ->where('name like :name and age > :age')
      ->bind(['name' => 'John', 'age' => 42])
      ->orderBy('age desc')
      ->execute();

    $row = $result->fetchAll();
    print_r($row);

    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::execute

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

TableSelect::execute — Ejecuta una declaración select

### Descripción

public function mysql_xdevapi\TableSelect::execute(): mysql_xdevapi\RowResult

Ejecuta la declaración select encadenándola con el método execute().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un objeto RowResult.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableSelect::execute()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name','age')
      ->where('name like :name and age > :age')
      ->bind(['name' => 'John', 'age' => 42])
      ->orderBy('age desc')
      ->execute();

    $row = $result->fetchAll();
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::groupBy

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

TableSelect::groupBy — Define los criterios de agrupación de la selección

### Descripción

public function mysql_xdevapi\TableSelect::groupBy(mixed `$sort_expr`): mysql_xdevapi\TableSelect

Define un criterio de agrupación para el conjunto de resultados.

### Parámetros

`sort_expr`

  El criterio de agrupación.

### Valores devueltos

Un objeto TableSelect.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableSelect::groupBy()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 42)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('Suki', 31)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('count(*) as count', 'age')
      ->groupBy('age')->orderBy('age asc')
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [count] => 1
                [age] => 31
            )
        [1] => Array
            (
                [count] => 2
                [age] => 42
            )
    )

# TableSelect::having

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

TableSelect::having — Define la condición de agrupamiento

### Descripción

public function mysql_xdevapi\TableSelect::having(string `$sort_expr`): mysql_xdevapi\TableSelect

Define una condición para los registros a considerar en las operaciones de función de agregación.

### Parámetros

`sort_expr`

  Una condición sobre las funciones de agregación utilizadas en los criterios de agrupamiento.

### Valores devueltos

Un objeto TableSelect.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableSelect::having()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 42)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('Suki', 31)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('count(*) as count', 'age')
      ->groupBy('age')->orderBy('age asc')
      ->having('count > 1')
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [count] => 2
                [age] => 42
            )
    )

# TableSelect::limit

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

TableSelect::limit — Limita las filas seleccionadas

### Descripción

public function mysql_xdevapi\TableSelect::limit(int `$rows`): mysql_xdevapi\TableSelect

Define el número máximo de registros o documentos a devolver.

### Parámetros

`rows`

  El número máximo de registros o documentos.

### Valores devueltos

Un objeto TableSelect.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableSelect::limit()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name', 'age')
      ->limit(1)
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::lockExclusive

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

TableSelect::lockExclusive — Ejecuta EXCLUSIVE LOCK

### Descripción

public function mysql_xdevapi\TableSelect::lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect

Ejecuta una operación de lectura con EXCLUSIVE LOCK. Solo un bloqueo puede estar activo a la vez.

### Parámetros

`lock_waiting_option`

  Una opción de espera opcional que está definida por omisión en `MYSQLX_LOCK_DEFAULT`. Los valores válidos son:

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### Valores devueltos

Un objeto TableSelect.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableSelect::lockExclusive()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $session->startTransaction();

    $result = $table->select('name', 'age')
      ->lockExclusive(MYSQLX_LOCK_NOWAIT)
      ->execute();

    $session->commit();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 42
            )
    )

# TableSelect::lockShared

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

TableSelect::lockShared — Ejecuta SHARED LOCK

### Descripción

public function mysql_xdevapi\TableSelect::lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect

Ejecuta una operación de lectura con SHARED LOCK. Solo un bloqueo puede estar activo a la vez.

### Parámetros

`lock_waiting_option`

  Una opción de espera opcional que se establece por omisión en `MYSQLX_LOCK_DEFAULT`. Los valores válidos son:

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### Valores devueltos

Un objeto TableSelect.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableSelect::lockShared()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $session->startTransaction();

    $result = $table->select('name', 'age')
      ->lockShared(MYSQLX_LOCK_NOWAIT)
      ->execute();

    $session->commit();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 42
            )
    )

# TableSelect::offset

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

TableSelect::offset — Define el desplazamiento del límite

### Descripción

public function mysql_xdevapi\TableSelect::offset(int `$position`): mysql_xdevapi\TableSelect

Ignora un número dado de filas en el resultado.

### Parámetros

`position`

  El desplazamiento del límite.

### Valores devueltos

Un objeto TableSelect.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableSelect::offset()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 42)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name', 'age')
      ->limit(1)
      ->offset(1)
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [name] => Sam
                [age] => 42
            )
    )

# TableSelect::orderby

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

TableSelect::orderby — Define los criterios de ordenación de la selección

### Descripción

public function mysql_xdevapi\TableSelect::orderby(mixed `$sort_expr`, mixed `...$sort_exprs`): mysql_xdevapi\TableSelect

Define los criterios de ordenación.

### Parámetros

`sort_expr`

  La expresión que define los criterios de ordenación. Puede ser un array con una o más expresiones, o un string.

`sort_exprs`

  Parámetros adicionales para sort_expr.

### Valores devueltos

Un objeto TableSelect.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableSelect::orderBy()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name', 'age')
      ->orderBy('name desc')
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [name] => Sam
                [age] => 42
            )
        [1] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::where

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

TableSelect::where — Define los criterios de búsqueda de la selección

### Descripción

public function mysql_xdevapi\TableSelect::where(string `$where_expr`): mysql_xdevapi\TableSelect

Define las condiciones de búsqueda para filtrar.

### Parámetros

`where_expr`

  Define la condición de búsqueda para filtrar los documentos o los registros.

### Valores devueltos

Un objeto TableSelect.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableSelect::where()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name','age')
      ->where('name like :name and age > :age')
      ->bind(['name' => 'John', 'age' => 42])
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

## Tabla de contenidos

- TableSelect::bind — Liga los argumentos de la petición select
- TableSelect::__construct — Constructor de TableSelect
- TableSelect::execute — Ejecuta una declaración select
- TableSelect::groupBy — Define los criterios de agrupación de la selección
- TableSelect::having — Define la condición de agrupamiento
- TableSelect::limit — Limita las filas seleccionadas
- TableSelect::lockExclusive — Ejecuta EXCLUSIVE LOCK
- TableSelect::lockShared — Ejecuta SHARED LOCK
- TableSelect::offset — Define el desplazamiento del límite
- TableSelect::orderby — Define los criterios de ordenación de la selección
- TableSelect::where — Define los criterios de búsqueda de la selección

# Clase TableUpdate

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

Una declaración para operaciones de actualización en una Tabla.

## Sinopsis de la Clase

class mysql_xdevapi\TableUpdate implements mysql_xdevapi\Executable {
/* Métodos */
public function bind(array `$placeholder_values`): mysql_xdevapi\TableUpdate
public function execute(): mysql_xdevapi\TableUpdate
public function limit(int `$rows`): mysql_xdevapi\TableUpdate
public function orderby(mixed `$orderby_expr`, mixed `...$orderby_exprs`): mysql_xdevapi\TableUpdate
public function set(string `$table_field`, string `$expression_or_literal`): mysql_xdevapi\TableUpdate
public function where(string `$where_expr`): mysql_xdevapi\TableUpdate
}

# TableUpdate::bind

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

TableUpdate::bind — Liga los argumentos de la solicitud de actualización

### Descripción

public function mysql_xdevapi\TableUpdate::bind(array `$placeholder_values`): mysql_xdevapi\TableUpdate

Liga un valor a un emplazamiento específico.

### Parámetros

`placeholder_values`

  El nombre del emplazamiento reservado y el valor a ligar, definidos como un array JSON.

### Valores devueltos

Un objeto TableUpdate.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableUpdate::bind()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->update()
      ->set('status', 'admin')
      ->where('name = :name and age > :age')
      ->bind(['name' => 'Bernie', 'age' => 2000])
      ->execute();

    ?>

# TableUpdate::__construct

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

TableUpdate::__construct — Constructor de TableUpdate

### Descripción

private function mysql_xdevapi\TableUpdate::__construct()

Inicializado por el método update().

### Parámetros

Esta función no contiene ningún parámetro.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableUpdate::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

# TableUpdate::execute

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

TableUpdate::execute — Ejecuta la consulta de actualización

### Descripción

public function mysql_xdevapi\TableUpdate::execute(): mysql_xdevapi\TableUpdate

Ejecuta la declaración de actualización.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un objeto TableUpdate.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableUpdate::execute()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

# TableUpdate::limit

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

TableUpdate::limit — Limita el número de filas actualizadas

### Descripción

public function mysql_xdevapi\TableUpdate::limit(int `$rows`): mysql_xdevapi\TableUpdate

Define el número máximo de filas o documentos a actualizar.

### Parámetros

`rows`

  El número máximo de filas o documentos a actualizar.

### Valores devueltos

Un objeto TableUpdate.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableUpdate::limit()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

# TableUpdate::orderby

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

TableUpdate::orderby — Define los criterios de ordenación

### Descripción

public function mysql_xdevapi\TableUpdate::orderby(mixed `$orderby_expr`, mixed `...$orderby_exprs`): mysql_xdevapi\TableUpdate

Define los criterios de ordenación.

### Parámetros

`orderby_expr`

  La expresión que define los criterios de ordenación. Puede ser un array con una o más expresiones, o un string.

`orderby_exprs`

  Parámetros adicionales para las expresiones de ordenación.

### Valores devueltos

Un objeto TableUpdate.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableUpdate::orderby()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();
    ?>

# TableUpdate::set

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

TableUpdate::set — Añade un campo a actualizar

### Descripción

public function mysql_xdevapi\TableUpdate::set(string `$table_field`, string `$expression_or_literal`): mysql_xdevapi\TableUpdate

Actualiza el valor de la columna en los registros de una tabla.

### Parámetros

`table_field`

  El nombre de la columna a actualizar.

`expression_or_literal`

  El valor a definir en la columna especificada.

### Valores devueltos

Un objeto TableUpdate.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableUpdate::set()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

# TableUpdate::where

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

TableUpdate::where — Define el filtro de búsqueda

### Descripción

public function mysql_xdevapi\TableUpdate::where(string `$where_expr`): mysql_xdevapi\TableUpdate

Define la condición de búsqueda para el filtro.

### Parámetros

`where_expr`

  La condición de búsqueda para filtrar los documentos o los registros.

### Valores devueltos

Un objeto TableUpdate.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\TableUpdate::where()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

## Tabla de contenidos

- TableUpdate::bind — Liga los argumentos de la solicitud de actualización
- TableUpdate::__construct — Constructor de TableUpdate
- TableUpdate::execute — Ejecuta la consulta de actualización
- TableUpdate::limit — Limita el número de filas actualizadas
- TableUpdate::orderby — Define los criterios de ordenación
- TableUpdate::set — Añade un campo a actualizar
- TableUpdate::where — Define el filtro de búsqueda

# Clase Warning

(PECL mysql-xdevapi >= 8.0.11)

## Introducción

## Sinopsis de la Clase

class mysql_xdevapi\Warning {
/* Propiedades */
public $message;
public $level;
public $code;
/* Constructor */
private function __construct()
}

## Propiedades

message

level

code

# Warning::__construct

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

Warning::__construct — Constructor de Warning

### Descripción

private function mysql_xdevapi\Warning::__construct()

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_xdevapi\Warning::__construct()

    <?php

    /* ... */

    ?>

## Tabla de contenidos

- Warning::__construct — Constructor de Warning

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
  - Compilar a partir de las fuentes
- Constantes predefinidas
- Registro de cambios
- Ejemplos
- Funciones Mysql_xdevapi
  - expression — Vincula una expresión a una variable de consulta preparada
  - getSession — Conecta a un servidor MySQL
- mysql_xdevapi\BaseResult — Interfaz BaseResult
  - BaseResult::getWarnings — Recupera los avisos de la última operación
  - BaseResult::getWarningsCount — Recupera el número de advertencias de la última operación
- mysql_xdevapi\Client — La clase Client
  - mysql_xdevapi\Client::close — Cierra el cliente
  - Client::__construct — Constructor del cliente
  - Client::getClient — Devuelve la sesión del cliente
- mysql_xdevapi\Collection — Clase Collection
  - Collection::add — Añade un documento a la colección
  - Collection::addOrReplaceOne — Añade o reemplaza un documento de la colección
  - Collection::__construct — Constructor de Collection
  - Collection::count — Devuelve el número de documentos
  - Collection::createIndex — Crear un índice de colección
  - Collection::dropIndex — Elimina un índice de colección
  - Collection::existsInDatabase — Verifica si la colección existe en la base de datos
  - Collection::find — Búsqueda de documento
  - Collection::getName — Devuelve el nombre de la colección
  - Collection::getOne — Devuelve un documento
  - Collection::getSchema — Devuelve el objeto esquema
  - Collection::getSession — Devuelve el objeto session
  - Collection::modify — Modifica los documentos de la colección
  - Collection::remove — Elimina documentos de la colección
  - Collection::removeOne — Elimina un documento de la colección
  - Collection::replaceOne — Reemplaza un documento de la colección
- mysql_xdevapi\CollectionAdd — Clase CollectionAdd
  - CollectionAdd::__construct — Constructor de CollectionAdd
  - CollectionAdd::execute — Ejecuta la declaración
- mysql_xdevapi\CollectionFind — Clase CollectionFind
  - CollectionFind::bind — Liga un valor a un argumento de consulta
  - CollectionFind::__construct — Constructor de CollectionFind
  - CollectionFind::execute — Ejecuta la declaración
  - CollectionFind::fields — Define el filtro de campo de documento
  - CollectionFind::groupBy — Define los criterios de agrupación
  - CollectionFind::having — Define la condición para las funciones de agregación
  - CollectionFind::limit — Limita el número de documentos devueltos
  - CollectionFind::lockExclusive — Ejecuta la operación con un BLOQUEO EXCLUSIVO
  - CollectionFind::lockShared — Ejecuta la operación con un BLOQUEO COMPARTIDO
  - CollectionFind::offset — Ignorar un número dado de elementos a devolver
  - CollectionFind::sort — Define los criterios de ordenación
- mysql_xdevapi\CollectionModify — Clase CollectionModify
  - CollectionModify::arrayAppend — Añade un elemento a un campo de array
  - CollectionModify::arrayInsert — Inserta un elemento en un campo de array
  - CollectionModify::bind — Liga un valor a un parámetro de consulta
  - CollectionModify::__construct — Constructor de CollectionModify
  - CollectionModify::execute — Ejecuta la operación de modificación
  - CollectionModify::limit — Limita el número de documentos modificados
  - CollectionModify::patch — Corrige un documento
  - CollectionModify::replace — Reemplaza un campo de documento
  - CollectionModify::set — Define un atributo de documento
  - CollectionModify::skip — Ignorar los elementos
  - CollectionModify::sort — Define los criterios de ordenación
  - CollectionModify::unset — Elimina el valor de los campos del documento
- mysql_xdevapi\CollectionRemove — Clase CollectionRemove
  - CollectionRemove::bind — Liga un valor a un argumento
  - CollectionRemove::__construct — Constructor de CollectionRemove
  - CollectionRemove::execute — Ejecuta la operación de eliminación
  - CollectionRemove::limit — Limita el número de documentos a eliminar
  - CollectionRemove::sort — Define el criterio de ordenación
- mysql_xdevapi\ColumnResult — Clase ColumnResult
  - ColumnResult::__construct — Constructor de ColumnResult
  - ColumnResult::getCharacterSetName — Devuelve el conjunto de caracteres
  - ColumnResult::getCollationName — Devuelve el nombre de la intercalación
  - ColumnResult::getColumnLabel — Devuelve la etiqueta de columna
  - ColumnResult::getColumnName — Devuelve el nombre de la columna
  - ColumnResult::getFractionalDigits — Devuelve la longitud de los dígitos fraccionarios
  - ColumnResult::getLength — Devuelve la longitud del campo
  - ColumnResult::getSchemaName — Devuelve el nombre del esquema
  - ColumnResult::getTableLabel — Devuelve la etiqueta de la tabla
  - ColumnResult::getTableName — Devuelve el nombre de la tabla
  - ColumnResult::getType — Devuelve el tipo de columna
  - ColumnResult::isNumberSigned — Indica si el tipo es signado
  - ColumnResult::isPadded — Verifica si el campo tiene un relleno
- mysql_xdevapi\CrudOperationBindable — Interfaz CrudOperationBindable
  - CrudOperationBindable::bind — Liga un valor a un espacio reservado
- mysql_xdevapi\CrudOperationLimitable — Interfaz CrudOperationLimitable
  - CrudOperationLimitable::limit — Define el límite de resultados
- mysql_xdevapi\CrudOperationSkippable — Interfaz CrudOperationSkippable
  - CrudOperationSkippable::skip — El número de operaciones a ignorar
- mysql_xdevapi\CrudOperationSortable — Interfaz CrudOperationSortable
  - CrudOperationSortable::sort — Ordena los resultados
- mysql_xdevapi\DatabaseObject — Interfaz DatabaseObject
  - DatabaseObject::existsInDatabase — Verifica si el objeto existe en la base de datos
  - DatabaseObject::getName — Devuelve el nombre del objeto
  - DatabaseObject::getSession — Devuelve el nombre de la sesión
- mysql_xdevapi\DocResult — Clase DocResult
  - DocResult::__construct — Constructor de DocResult
  - DocResult::fetchAll — Devuelve todas las filas
  - DocResult::fetchOne — Devuelve una fila
  - DocResult::getWarnings — Devuelve los avisos de la última operación
  - DocResult::getWarningsCount — Devuelve el número de advertencias de la última operación
- mysql_xdevapi\Exception — Clase Exception
- mysql_xdevapi\Executable — Interfaz Executable
  - Executable::execute — Ejecuta una declaración
- mysql_xdevapi\ExecutionStatus — Clase ExecutionStatus
  - ExecutionStatus::__construct — Constructor de ExecutionStatus
- mysql_xdevapi\Expression — Clase Expression
  - Expression::__construct — Constructor de Expression
- mysql_xdevapi\Result — Clase Result
  - Result::__construct — Constructor de Result
  - Result::getAffectedItemsCount — Devuelve el número de filas afectadas
  - Result::getAutoIncrementValue — Devuelve el valor auto-incrementado
  - Result::getGeneratedIds — Devuelve los ID generados
  - Result::getWarnings — Devuelve las advertencias de la última operación
  - Result::getWarningsCount — Devuelve el número de advertencias de la última operación
- mysql_xdevapi\RowResult — Clase RowResult
  - RowResult::__construct — Constructor de RowResult
  - RowResult::fetchAll — Devuelve todas las filas del resultado
  - RowResult::fetchOne — Devuelve una fila del resultado
  - RowResult::getColumnsCount — Devuelve el número de columnas
  - RowResult::getColumnNames — Devuelve el nombre de todas las columnas
  - RowResult::getColumns — Devuelve los metadatos de las columnas
  - RowResult::getWarnings — Devuelve las advertencias de la última operación
  - RowResult::getWarningsCount — Devuelve el número de advertencias de la última operación
- mysql_xdevapi\Schema — Clase Schema
  - Schema::__construct — Constructor de schema
  - Schema::createCollection — Añade una colección al esquema
  - Schema::dropCollection — Elimina una colección del esquema
  - Schema::existsInDatabase — Verifica si el objeto existe en la base de datos
  - Schema::getCollection — Devuelve una colección del esquema
  - Schema::getCollectionAsTable — Devuelve una colección como objeto Table
  - Schema::getCollections — Devuelve todas las colecciones del esquema
  - Schema::getName — Devuelve el nombre del esquema
  - Schema::getSession — Devuelve la sesión del esquema
  - Schema::getTable — Devuelve la tabla del esquema
  - Schema::getTables — Devuelve las tablas del esquema
- mysql_xdevapi\SchemaObject — Interfaz SchemaObject
  - SchemaObject::getSchema — Devuelve el objeto esquema
- mysql_xdevapi\Session — Clase Session
  - Session::close — Cierra la sesión
  - Session::commit — Valida la transacción
  - Session::__construct — Descripción del constructor
  - Session::createSchema — Crear un nuevo esquema
  - Session::dropSchema — Elimina un esquema
  - Session::generateUUID — Devuelve un nuevo UUID
  - Session::getDefaultSchema — Devuelve el nombre del esquema predeterminado
  - Session::getSchema — Devuelve un nuevo objeto esquema
  - Session::getSchemas — Devuelve los esquemas
  - Session::getServerVersion — Devuelve la versión del servidor
  - Session::listClients — Devuelve la lista de clientes
  - Session::quoteName — Añade comillas
  - Session::releaseSavepoint — Libera el punto de salvaguarda
  - Session::rollback — Revierte la transacción
  - Session::rollbackTo — Anula la transacción hasta el punto de salvaguarda
  - Session::setSavepoint — Crear un punto de salvaguarda
  - Session::sql — Crear una consulta SQL
  - Session::startTransaction — Inicia una transacción
- mysql_xdevapi\SqlStatement — Clase SqlStatement
  - SqlStatement::bind — Liga los argumentos de la instrucción
  - SqlStatement::__construct — Descripción del constructor
  - SqlStatement::execute — Ejecuta la operación
  - SqlStatement::getNextResult — Devuelve el resultado siguiente
  - SqlStatement::getResult — Devuelve el resultado
  - SqlStatement::hasMoreResults — Verifica si hay más resultados
- mysql_xdevapi\SqlStatementResult — Clase SqlStatementResult
  - SqlStatementResult::__construct — Descripción del constructor
  - SqlStatementResult::fetchAll — Devuelve todas las filas del resultado
  - SqlStatementResult::fetchOne — Devuelve una sola línea
  - SqlStatementResult::getAffectedItemsCount — Devuelve el número de filas afectadas
  - SqlStatementResult::getColumnsCount — Devuelve el número de columnas
  - SqlStatementResult::getColumnNames — Devuelve el nombre de las columnas
  - SqlStatementResult::getColumns — Devuelve las columnas
  - SqlStatementResult::getGeneratedIds — Devuelve los identificadores generados
  - SqlStatementResult::getLastInsertId — Devuelve el ID de la última inserción
  - SqlStatementResult::getWarnings — Devuelve las advertencias de la última operación
  - SqlStatementResult::getWarningsCount — Devuelve el número de advertencias de la última operación
  - SqlStatementResult::hasData — Verifica si el resultado contiene datos
  - SqlStatementResult::nextResult — Devuelve el resultado siguiente
- mysql_xdevapi\Statement — Clase Statement
  - Statement::__construct — Descripción del constructor
  - Statement::getNextResult — Devuelve el resultado siguiente
  - Statement::getResult — Devuelve el resultado
  - Statement::hasMoreResults — Verifica si hay más resultados
- mysql_xdevapi\Table — Clase Table
  - Table::__construct — Constructor de Table
  - Table::count — Devuelve el número de filas
  - Table::delete — Elimina filas de la tabla
  - Table::existsInDatabase — Verifica si la tabla existe en la base de datos
  - Table::getName — Devuelve el nombre de la tabla
  - Table::getSchema — Devuelve el esquema de la tabla
  - Table::getSession — Devuelve la sesión de la tabla
  - Table::insert — Inserta filas en una tabla
  - Table::isView — Devuelve si la tabla es una vista
  - Table::select — Selecciona filas en una tabla
  - Table::update — Actualiza las filas de la tabla
- mysql_xdevapi\TableDelete — Clase TableDelete
  - TableDelete::bind — Liga los argumentos de la petición de eliminación
  - TableDelete::__construct — Constructor de TableDelete
  - TableDelete::execute — Ejecuta la consulta de eliminación
  - TableDelete::limit — Limita las filas eliminadas
  - TableDelete::orderby — Define los criterios de ordenación de la eliminación
  - TableDelete::where — Define la condición de búsqueda para la eliminación
- mysql_xdevapi\TableInsert — Clase TableInsert
  - TableInsert::__construct — Constructor de TableInsert
  - TableInsert::execute — Ejecuta una consulta de inserción
  - TableInsert::values — Añade valores de fila
- mysql_xdevapi\TableSelect — Clase TableSelect
  - TableSelect::bind — Liga los argumentos de la petición select
  - TableSelect::__construct — Constructor de TableSelect
  - TableSelect::execute — Ejecuta una declaración select
  - TableSelect::groupBy — Define los criterios de agrupación de la selección
  - TableSelect::having — Define la condición de agrupamiento
  - TableSelect::limit — Limita las filas seleccionadas
  - TableSelect::lockExclusive — Ejecuta EXCLUSIVE LOCK
  - TableSelect::lockShared — Ejecuta SHARED LOCK
  - TableSelect::offset — Define el desplazamiento del límite
  - TableSelect::orderby — Define los criterios de ordenación de la selección
  - TableSelect::where — Define los criterios de búsqueda de la selección
- mysql_xdevapi\TableUpdate — Clase TableUpdate
  - TableUpdate::bind — Liga los argumentos de la solicitud de actualización
  - TableUpdate::__construct — Constructor de TableUpdate
  - TableUpdate::execute — Ejecuta la consulta de actualización
  - TableUpdate::limit — Limita el número de filas actualizadas
  - TableUpdate::orderby — Define los criterios de ordenación
  - TableUpdate::set — Añade un campo a actualizar
  - TableUpdate::where — Define el filtro de búsqueda
- mysql_xdevapi\Warning — Clase Warning
  - Warning::__construct — Constructor de Warning

# API MySQL original

# Introducción

Esta extensión está obsoleta desde PHP 5.5.0 y ha sido eliminada desde PHP 7.0.0. En su lugar, se debe utilizar la extensión mysqli o PDO_MySQL. Consulte también la visión general de la API MySQL para obtener más ayuda en la elección de una API MySQL.

Estas funciones permiten acceder a las bases de datos MySQL. El sitio oficial de esta base de datos es » http://www.mysql.com/.

La documentación de MySQL está disponible en » http://dev.mysql.com/doc/.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución
- Tipos de recursos

## Requerimientos

Para poder utilizarlos, es necesario compilar PHP con el soporte MySQL.

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

## Instalación

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

Para compilar, simplemente se debe utilizar la opción de configuración --with-mysql[=DIR] donde el parámetro opcional `[DIR]` apunta hacia el directorio de instalación de MySQL.

Aunque esta extensión MySQL sea compatible con MySQL 4.1.0 y superior, no soporta las funcionalidades adicionales que esta versión proporciona. Para ello, se recomienda utilizar la extensión MySQLi.

Si se desea instalar la extensión mysqli al mismo tiempo que la extensión mysql, se debe utilizar la misma biblioteca cliente para evitar conflictos.

## Instalación en sistemas Linux

Nota: `[DIR]` es la ruta hacia la biblioteca cliente MySQL (encabezados y bibliotecas), que puede ser descargada desde el sitio de » MySQL.

Matriz de soporte de ext/mysql
PHP Versión | Por defecto | Opciones de configuración: mysqlnd | Opciones de configuración: `libmysqlclient` | Historial de cambios
--- | --- | --- | --- | ---
4.x.x | libmysqlclient | No Disponible | --without-mysql para desactivar | MySQL está activo por omisión, las bibliotecas cliente MySQL están incluidas internamente
5.0.x, 5.1.x, 5.2.x | libmysqlclient | No Disponible | --with-mysql=[DIR] | MySQL no está activo por omisión, y las bibliotecas cliente MySQL ya no están incluidas internamente
5.3.x | libmysqlclient | --with-mysql=mysqlnd | --with-mysql=[DIR] | mysqlnd está ahora disponible
5.4.x | mysqlnd | --with-mysql | --with-mysql=[DIR] | mysqlnd está ahora incluido por omisión

## Instalación en sistemas Windows

## PHP 5.0.x, 5.1.x, 5.2.x

MySQL ya no está activado por omisión, por lo tanto, la biblioteca php_mysql.dll debe ser activada en el php.ini. Además, PHP debe tener acceso a la biblioteca cliente MySQL. Un fichero llamado libmysql.dll está incluido en la distribución de PHP para Windows y para que PHP pueda comunicarse con MySQL, este fichero debe estar disponible en el PATH del sistema Windows. Lea la FAQ titulada "¿Dónde debo añadir mi directorio PHP a la variable PATH en Windows?" para más información sobre cómo realizar esto. No obstante, copiar el fichero libmysql.dll en el directorio sistema de Windows funciona (ya que el directorio sistema está por omisión en el PATH del sistema), pero esto no es recomendado en absoluto.

Para activar cualquier extensión PHP (como php_mysql.dll), la directiva PHP extension_dir debe estar definida y debe apuntar hacia el directorio donde están almacenadas las extensiones PHP. Lea también el manual de instalación en Windows. Por ejemplo, aquí hay un valor posible para la directiva extension_dir en PHP 5: `c:\php\ext`

> Nota: Si al iniciar el servidor web aparece un error similar a este: `"Unable to load dynamic library './php_mysql.dll'"`, es porque php_mysql.dll y/o libmysql.dll no pudieron ser encontrados por el sistema.

## PHP 5.3.0+

El driver MySQL nativo está activado por omisión. Incluya php_mysql.dll, pero libmysql.dll ya no es necesario, ni utilizado.

## Notas sobre la instalación de MySQL

Advertencia

Pueden encontrarse fallos y problemas de inicio de PHP cuando se carga esta función al mismo tiempo que la extensión recode. Consulte la extensión recode para más detalles.

> Nota: Si se necesitan otros juegos de caracteres que el predeterminado (latino), se debe instalar la biblioteca externa libmysqlclient (no proporcionada), compilada con este juego de caracteres.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración MySQL
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
mysql.allow_local_infile | "1" | `INI_SYSTEM` |
mysql.allow_persistent | "1" | `INI_SYSTEM` |
mysql.max_persistent | "-1" | `INI_SYSTEM` |
mysql.max_links | "-1" | `INI_SYSTEM` |
mysql.trace_mode | "Off" | `INI_ALL` |
mysql.default_port | NULL | `INI_ALL` |
mysql.default_socket | NULL | `INI_ALL` |
mysql.default_host | NULL | `INI_ALL` |
mysql.default_user | NULL | `INI_ALL` |
mysql.default_password | NULL | `INI_ALL` |
mysql.connect_timeout | "60" | `INI_ALL` |

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`mysql.allow_local_infile` int
  Permite el acceso, desde el punto de vista de PHP, a los ficheros locales, con las consultas LOAD DATA.
`mysql.allow_persistent` bool
  Activa o desactiva las conexiones persistentes a la base de datos MySQL.
`mysql.max_persistent` int
  El número máximo de conexiones persistentes a las bases de datos MySQL, por proceso.
`mysql.max_links` int
  El número máximo de conexiones a las bases de datos MySQL, incluyendo las conexiones persistentes, por proceso.
`mysql.trace_mode` bool
  Modo de seguimiento. Cuando `mysql.trace_mode` está activado, se mostrarán alertas para escaneos de tabla o de índice, para olvidos de liberación de recursos o errores SQL. Esta opción fue introducida en PHP 4.3.0.
`mysql.default_port` string
  El número de puerto TCP por defecto, utilizado para conectarse a la base de datos, cuando no se especifica ningún puerto. Si no se especifica ningún puerto por defecto, el puerto se obtendrá entonces leyendo la variable de entorno MYSQL_TCP_PORT, la entrada `mysql-tcp` en el fichero /etc/services o la constante de compilación `MYSQL_PORT`, en este orden. Windows utilizará también solo la constante `MYSQL_PORT`.
`mysql.default_socket` string
  El nombre por defecto del socket cuando se conecta al servidor local, si no se especifica ningún otro socket.
`mysql.default_host` string
  Dirección por defecto del servidor, a utilizar al conectarse a un servidor MySQL, si no se especifica ningún host. No se aplica cuando el safe mode SQL está activado.
`mysql.default_user` string
  Usuario por defecto, a utilizar al conectarse a un servidor MySQL, si no se especifica ningún usuario. No se aplica cuando el safe mode SQL está activado.
`mysql.default_password` string
  Contraseña por defecto, a utilizar al conectarse a un servidor MySQL, si no se especifica ninguna contraseña. No se aplica cuando el safe mode SQL está activado.
`mysql.connect_timeout` int
  Tiempo máximo de espera de la respuesta de un servidor, en segundos. En Linux, este tiempo sirve también durante el intercambio del primero con el servidor.

## Tipos de recursos

Existen dos tipos de recursos utilizados por el módulo MySQL. El primero es un identificador de conexión al servidor, denominado `mysql link`, y el segundo es un identificador de resultado de consulta, denominado `mysql result`.

# Registro de cambios

A las clases/funciones/métodos de esta extensión se han realizado los siguientes cambios.

### Histórico de cambios general para la extensión ext/mysql

Este histórico de cambios hace referencia a la extensión ext/mysql.

### Cambios globales en ext/mysql

La siguiente lista presenta los cambios en toda la extensión ext/mysql.

Versión | Descripción
--- | ---
7.0.0 | Esta extensión ha sido eliminada de PHP. Para más detalles, ver Elegir una API.

### Cambios en las funciones existentes

La siguiente lista es una compilación de los cambios realizados en las funciones de la extensión ext/mysql.

Version | Function | Description
--- | --- | ---

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

Es posible especificar opciones de cliente adicionales para las funciones mysql_connect() y mysql_pconnect(). Estas constantes son las siguientes:

Constantes de cliente MySQL
Constante | Descripción
--- | ---
`MYSQL_CLIENT_COMPRESS` | Utiliza el protocolo con compresión
`MYSQL_CLIENT_IGNORE_SPACE` | Permite espacios después de los nombres de función
`MYSQL_CLIENT_INTERACTIVE` | Permite interactive_timeout segundos de inactividad en la conexión (en lugar de wait_timeout).
`MYSQL_CLIENT_SSL` | Utilización de cifrado SSL. Esta constante solo está disponible a partir de la versión 4.x y posteriores de la biblioteca cliente MySQL. La versión 3.23.x se proporciona con PHP 4 así como con los binarios para Windows de PHP 5.

La función mysql_fetch_array() utiliza una constante para especificar los diferentes tipos de formatos de respuesta. Las constantes siguientes son utilizadas:

Constantes de mysql_fetch_array()
Constante | Descripción
--- | ---
`MYSQL_ASSOC` | Las columnas son devueltas en un array cuyos índices son los nombres de columnas.
`MYSQL_BOTH` | Las columnas son devueltas en un array con indexación numérica y un sistema de índices correspondiente al nombre de las columnas.
`MYSQL_NUM` | Las columnas son devueltas en un array con un índice numérico. Las columnas están numeradas en su orden de aparición. El índice comienza en cero.

# Ejemplos

## Tabla de contenidos

- Ejemplo con la extensión MySQL

## Ejemplo con la extensión MySQL

Este ejemplo simple muestra cómo conectarse, ejecutar una consulta, leer la información obtenida y desconectarse de una base de datos MySQL.

Ejemplo #1 Ejemplo de presentación de la extensión MySQL

    <?php
    // Conexión y selección de la base de datos
    $link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')
        or die('Imposible conectarse: ' . mysql_error());
    echo 'Conectado correctamente';
    mysql_select_db('my_database') or die('Imposible seleccionar la base de datos');

    // Ejecución de consultas SQL
    $query = 'SELECT * FROM my_table';
    $result = mysql_query($query) or die('Fallo en la consulta: ' . mysql_error());

    // Visualización de los resultados en HTML
    echo "<table>\n";
    while ($line = mysql_fetch_array($result, MYSQL_ASSOC)) {
        echo "\t<tr>\n";
        foreach ($line as $col_value) {
            echo "\t\t<td>$col_value</td>\n";
        }
        echo "\t</tr>\n";
    }
    echo "</table>\n";

    // Liberación de los resultados
    mysql_free_result($result);

    // Cierre de la conexión
    mysql_close($link);
    ?>

# Funciones MySQL

## Notas

> Nota: La mayoría de las funciones MySQL aceptan `link_identifier` como último argumento opcional. Si no se proporciona, se utiliza la última conexión abierta. Si no existe, se intenta establecer una conexión con los parámetros por omisión definidos en php.ini. Si las funciones no tienen éxito, devuelven `false`.

# mysql_affected_rows

(PHP 4, PHP 5)

mysql_affected_rows — Obtiene el número de filas afectadas en la anterior operación de MySQL

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_affected_rows()
- PDOStatement::rowCount()

### Descripción

function mysql_affected_rows(resource `$link_identifier` = NULL): int

Obtiene el número de filas afectadas por la última consulta INSERT, UPDATE, REPLACE o DELETE asociada con `link_identifier`.

### Parámetros

`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Devuelve el número de filas afectadas en caso de éxito, y -1 si la última consulta falló.

Si la consulta anterior fue DELETE con ninguna cláusula WHERE, todos los registros habrán sido borrados de la tabla, aunque ésta función devolverá cero con una versión anterior a MySQL 4.1.2.

Al utilizar UPDATE, MySQL no actualiza las columnas donde el nuevo valor es el mismo que el anterior. Esto crea la posibilidad de que mysql_affected_rows() no pueda equivaler en realidad al número de filas encontradas, solamente el número de filas que estuvieron literalmente afectadas por la consulta.

La sentencia REPLACE primero borra el registro con la misma clave primaria y luego inserta el nuevo registro. Esta función devuelve el número de registros borrados más el número de registros insertados.

En el caso de consultas "INSERT ... ON DUPLICATE KEY UPDATE", el valor devuelto será `1` si se realizó una inserción, o `2` para una actualización de una fila existente.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_affected_rows()

    <?php
    $enlace = mysql_connect('localhost', 'usuario_mysql', 'contraseña_mysql');
    if (!$enlace) {
        die('No se pudo conectar: ' . mysql_error());
    }
    mysql_select_db('mibd');

    /* Esto debería devolver el número correcto de registros borrados */
    mysql_query('DELETE FROM mitabla WHERE id < 10');
    printf("Registros borrados: %d\n", mysql_affected_rows());

    /* con una clausula WHERE que nunca es verdad, debería devolver 0 */
    mysql_query('DELETE FROM mitabla WHERE 0');
    printf("Registros borrados: %d\n", mysql_affected_rows());
    ?>

Resultado del ejemplo anterior es similar a:

    Registros borrados: 10
    Registros borrados: 0

Ejemplo #2 Ejemplo de mysql_affected_rows() al utilizar transacciones

    <?php
    $enlace = mysql_connect('localhost', 'usuario_mysql', 'contraseña_mysql');
    if (!$enlace) {
        die('No se pudo conectar: ' . mysql_error());
    }
    mysql_select_db('mibd');

    /* Actualizar registros */
    mysql_query("UPDATE mitabla SET usado=1 WHERE id < 10");
    printf ("Registros actualizados: %d\n", mysql_affected_rows());
    mysql_query("COMMIT");
    ?>

Resultado del ejemplo anterior es similar a:

    Registros actualizados: 10

### Notas

> Nota: Transacciones
> Si se usan transacciones, es necesario llamar a mysql_affected_rows() después de una consulta INSERT, UPDATE, o DELETE, no después del COMMIT.

> Nota: Sentencias SELECT
> Para conocer el número de filas devueltas por un SELECT, es posible usar mysql_num_rows().

> Nota: Claves Foráneas en Cascada
> mysql_affected_rows() no cuenta la filas afectadas implícitamente a través del uso de ON DELETE CASCADE y/o ON UPDATE CASCADE en las restricciones de las claves foráneas.

### Ver también

- mysql_num_rows() - Obtener el número de filas de un conjunto de resultados
- mysql_info() - Obtiene información sobre la consulta más reciente

# mysql_client_encoding

(PHP 4 >= 4.3.0, PHP 5)

mysql_client_encoding — Devuelve el nombre del conjunto de caracteres

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_character_set_name()

### Descripción

function mysql_client_encoding(resource `$link_identifier` = NULL): string

Recupera la variable `character_set` de MySQL.

### Parámetros

`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Devuelve el nombre del conjunto de caracteres predeterminado de la conexión actual.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_client_encoding()

    <?php
    $enlace = mysql_connect('localhost', 'usuario_mysql', 'contraseña_mysql');
    $conjunto_caracteres = mysql_client_encoding($enlace);

    echo "El conjunto de caracteres actual es: $conjunto_caracteres\n";
    ?>

Resultado del ejemplo anterior es similar a:

    El conjunto de caracteres actual es: latin1

### Ver también

- mysql_set_charset() - Establece el conjunto de caracteres del cliente
- mysql_real_escape_string() - Escapa caracteres especiales en una cadena para su uso en una sentencia SQL

# mysql_close

(PHP 4, PHP 5)

mysql_close — Cerrar una conexión de MySQL

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_close()
- PDO: Asignar el valor de `null` al objeto PDO

### Descripción

function mysql_close(resource `$link_identifier` = NULL): bool

mysql_close() cierra la conexión no persistente al servidor de MySQL que está asociada con el identificador de enlace especificado. Si `link_identifier` no se especifica, se usará el último enlace abierto.

Las conexiones y los juegos de resultados abiertos de forma no persistente son automáticamente destruidos cuando un script PHP termina su ejecución. También, el hecho de cerrar una conexión y liberar los resultados siendo opcional, el hecho de hacerlo explícitamente es altamente recomendado. Esto devolverá los recursos inmediatamente a PHP y a MySQL, lo que mejorará las performance. Para más información, refiérase a la liberación de recursos

### Parámetros

`link_identifier`
  La conexión MySQL. Si el identificador del enlace no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_close()

    <?php
    $enlace = mysql_connect('localhost', 'usuario_mysql', 'contraseña_mysql');
    if (!$enlace) {
        die('No se pudo conectar: ' . mysql_error());
    }
    echo 'Conectado con éxito';
    mysql_close($enlace);
    ?>

El ejemplo anterior mostrará:

    Conectado con éxito

### Notas

> Nota: mysql_close() no cerrará los enlaces persistentes creados por mysql_pconnect(). Para más detalles, véase la página del manual sobre conexiones persistentes.

### Ver también

- mysql_connect() - Abre una conexión al servidor MySQL
- mysql_free_result() - Libera la memoria del resultado

# mysql_connect

(PHP 4, PHP 5)

mysql_connect — Abre una conexión al servidor MySQL

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_connect()
- PDO::__construct()

### Descripción

function mysql_connect(
string `$server` = ini_get("mysql.default_host"),
string `$username` = ini_get("mysql.default_user"),
string `$password` = ini_get("mysql.default_password"),
bool `$new_link` = `false`,
int `$client_flags` = 0
): resource|false

Abre o reutiliza una conexión a un servidor MySQL.

### Parámetros

`server`
  El servidor MySQL. También se puede incluir un número de puerto. P.ej. "nombre_anfitrión:puerto" o una ruta a un socket local, p.ej. ":/ruta/al/socket" para el servidor local. Si la directiva PHP mysql.default_host no está definida (por defecto), el valor por defecto es 'localhost:3306'. En safe mode SQL, éste parámetro es ignorado y siempre se usa el valor 'localhost:3306'.
`username`
  El nombre de usuario. El valor por defecto está definido por mysql.default_user. En safe mode SQL, éste parámetro es ignorado y se usa el nombre de usuario que posee el proceso del servidor.
`password`
  La contraseña. El valor por defecto está definido por mysql.default_password. En safe mode SQL, éste parámetro es ignorado y se usa la contraseña vacía.
`new_link`
  Si se realiza una segunda llamada a mysql_connect() con los mismos argumentos, un nuevo enlace no será establecido, pero en su lugar, será devuelto el identificador de enlace del enlace ya abierto. El parámetro `new_link` modifica éste comportamiento y hace que mysql_connect() siempre abra un nuevo enlace, aun si mysql_connect() fue llamada antes con los mismos parámetros. En safe mode SQL, éste parámetro es ignorado.
`client_flags`
  El parámetro `client_flags` puede ser una combinación de las siguientes constantes: 128 (habilita el manejo de `LOAD DATA LOCAL`), `MYSQL_CLIENT_SSL`, `MYSQL_CLIENT_COMPRESS`, `MYSQL_CLIENT_IGNORE_SPACE` o `MYSQL_CLIENT_INTERACTIVE`. Lea la sección sobre Constantes de cliente MySQL para más información. En safe mode SQL, éste parámetro es ignorado.

### Valores devueltos

Devuelve un identificador de enlace de MySQL en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_connect()

    <?php
    $enlace =  mysql_connect('localhost', 'usuario_mysql', 'contraseña_mysql');
    if (!$enlace) {
        die('No pudo conectarse: ' . mysql_error());
    }
    echo 'Conectado satisfactoriamente';
    mysql_close($enlace);
    ?>

Ejemplo #2 Ejemplo de mysql_connect() usando la sintaxis `nombre_anfitrión:puerto`

    <?php
    // nos  conectamos a ejemplo.com y al puerto 3307
    $enlace = mysql_connect('ejemplo.com:3307',  'usuario_mysql', 'contraseña_mysql');
    if  (!$enlace) {
        die('No pudo conectarse: ' . mysql_error());
    }
    echo 'Conectado satisfactoriamente';
    mysql_close($enlace);

    // nos conectamos a ejemplo.com y al puerto 3307
    $enlace = mysql_connect('127.0.0.1:3307', 'usuario_mysql',  'contraseña_mysql');
    if (!$enlace) {
        die('No pudo conectarse: ' . mysql_error());
    }
    echo 'Conectado satisfactoriamente';
    mysql_close($enlace);
    ?>

Ejemplo #3 Ejemplo de mysql_connect() usando la sintaxis ":/rota/al/socket"

    <?php
    // nos  conectamos a localhost y a la toma ej. /tmp/mysql.sock

    // variante 1: omitir el localhost
    $enlace = mysql_connect(':/tmp/mysql', 'usuario_mysql',  'contraseña_mysql');
    if (!$enlace) {
        die('No pudo conectarse: ' . mysql_error());
    }
    echo 'Conectado satisfactoriamente';
    mysql_close($enlace);

    // variante 2: con localhost
    $enlace = mysql_connect('localhost:/tmp/mysql.sock',  'usuario_mysql', 'contraseña_mysql');
    if  (!$enlace) {
        die('No pudo conectarse: ' . mysql_error());
    }
    echo 'Conectado  satisfactoriamente';
    mysql_close($enlace);
    ?>

### Notas

> Nota: Siempre que se especifique "localhost" o "localhost:puerto" como servidor, la biblioteca cliente de MySQL invalidará esto e intentará conectarse a un socket local (llamada tubería en Windows). Si se quiere usar TCP/IP, se ha de utilizar "127.0.0.1" en lugar de "localhost". Si la biblioteca cliente de MySQL intenta conectarse al socket local erróneo, se debería establecer el ruta correcta como mysql.default_host en php.ini y dejar el campo del servidor en blanco.

> Nota: El enlace al servidor se cerrará tan pronto finalice la ejecución del script, a menos que se cierre antes por una llamada explícita a mysql_close().

> Nota: El error "Can't create TCP/IP socket (10106)" normalmente significa que la directiva de configuración variables_order no contiene el carácter `E`. En Windows, si el entorno no es copiadola variable de entorno `SYSTEMROOT` no estará disponible y PHP tendrá problemas al cargar Winsock.

### Ver también

- mysql_pconnect() - Abre una conexión persistente a un servidor MySQL
- mysql_close() - Cerrar una conexión de MySQL

# mysql_create_db

(PHP 4, PHP 5)

mysql_create_db — Crea una base de datos MySQL

Advertencia

Esta función estaba obsoleta en PHP 4.3.0, y toda la extensión original MySQL fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_query()
- PDO::query()

### Descripción

function mysql_create_db(string `$database_name`, resource `$link_identifier` = NULL): bool

mysql_create_db() intenta crear una nueva base de datos en el servidor asociado con el identificador de enlace especificado.

### Parámetros

`database_name`
  El nombre de la base de datos a crear.
`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo alternativo de mysql_create_db()

La función mysql_create_db() está obsoleta. Es preferible el uso de mysql_query() para emitir una sentencia `CREATE DATABASE` de sql en su lugar.

    <?php
    $enlace = mysql_connect('localhost', 'usuario_mysql', 'contraseña_mysql');
    if (!$enlace) {
        die('No pudo conectarse: ' . mysql_error());
    }

    $sql = 'CREATE DATABASE mi_bd';
    if (mysql_query($sql, $enlace)) {
        echo "La base de datos mi_bd se creó correctamente\n";
    } else {
        echo 'Error al crear la base de datos: ' . mysql_error() . "\n";
    }
    ?>

Resultado del ejemplo anterior es similar a:

    La base de datos mi_bd se creó correctamente

### Notas

> Nota: Por razones de compatibilidad ascendente, el siguiente alias obsoleto puede ser utilizado: mysql_createdb()

> Nota: Ésta función no estará disponible si la extensión MySQL fue construida con una biblioteca cliente MySQL 4.x.

### Ver también

- mysql_query() - Enviar una consulta MySQL
- mysql_select_db() - Seleccionar una base de datos MySQL

# mysql_data_seek

(PHP 4, PHP 5)

mysql_data_seek — Mueve el puntero de resultados interno

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_data_seek()
- `PDO::FETCH_ORI_ABS`

### Descripción

function mysql_data_seek(resource `$result`, int `$row_number`): bool

mysql_data_seek() mueve el puntero de filas interno del resultado de MySQL asociado con el identificador de resultado especificado para apuntar al número de fila especificada. La siguiente llamada a una función de obtención de MySQL, tal como mysql_fetch_assoc(), devolverá esa fila.

`row_number` empieza en 0. `row_number` debería ser un valor en el rango de 0 a mysql_num_rows() -1. Sin embargo, si el conjunto de resultados esta vacío (mysql_num_rows() == 0), una búsqueda a 0 fallará con un `E_WARNING` y mysql_data_seek() devolverá `false`.

### Parámetros

`result`
  La resource de resultado que acaba de ser evaluada. Este resultado proviene de la llamada a la función mysql_query().
`row_number`
  Número de la fila deseada del puntero de resultados nuevo.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_data_seek()

    <?php
    $enlace = mysql_connect('localhost', 'usuario_mysql', 'contraseña_mysql');
    if (!$enlace) {
        die('No pudo conectarse: ' . mysql_error());
    }
    $bd_seleccionada = mysql_select_db('bd_muestra');
    if (!$bd_seleccionada) {
        die('La base de datos no pudo seleccionarse: ' . mysql_error());
    }
    $consulta = 'SELECT apellido, nombre FROM amigos';
    $resultado = mysql_query($consulta);
    if (!$resultado) {
        die('La consulta falló: ' . mysql_error());
    }
    /* obtención de filas en orden inverso */
    for ($i = mysql_num_rows($resultado) - 1; $i >= 0; $i--) {
        if (!mysql_data_seek($resultado, $i)) {
            echo "No se encuenta la fila $i: " . mysql_error() . "\n";
            continue;
        }

        if (!($fila = mysql_fetch_assoc($resultado))) {
            continue;
        }

        echo $fila['apellido'] . ' ' . $fila['nombre'] . "<br />\n";
    }

    mysql_free_result($resultado);
    ?>

### Notas

> Nota: La función mysql_data_seek() puede ser usada solamente junto con mysql_query(), y no con mysql_unbuffered_query().

### Ver también

- mysql_query() - Enviar una consulta MySQL
- mysql_num_rows() - Obtener el número de filas de un conjunto de resultados
- mysql_fetch_row() - Obtiene una fila de resultados como un array numérico
- mysql_fetch_assoc() - Recupera una fila de resultados como un array asociativo
- mysql_fetch_array() - Recupera una fila de resultados como un array asociativo, un array numérico o como ambos
- mysql_fetch_object() - Recupera una fila de resultados como un objeto

# mysql_db_name

(PHP 4, PHP 5)

mysql_db_name — Recupera el nombre de la base de datos desde una llamada a mysql_list_dbs()

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- Consulta: `SELECT DATABASE()`

### Descripción

function mysql_db_name(resource `$result`, int `$row`, mixed `$field` = NULL): string

Recupera el nombre de la base de datos de una llamada a mysql_list_dbs().

### Parámetros

`result`
  El puntero de resultados desde una llamada a mysql_list_dbs().
`row`
  El índice dentro del conjunto de resultados.
`field`
  El nombre del campo.

### Valores devueltos

Devuelve el nombre de la base de datos en caso de éxito, y `false` en caso de error. Si se devuelve `false`, se usa mysql_error() para determinar la naturaleza del error.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_db_name()

    <?php
    error_reporting(E_ALL);

    $enlace = mysql_connect('anfitrión_bd', 'nombre_usuario', 'contraseña');
    $lista_bd = mysql_list_dbs($enlace);

    $i = 0;
    $cuenta = mysql_num_rows($lista_bd);
    while ($i < $cuenta) {
        echo mysql_db_name($lista_bd, $i) . "\n";
        $i++;
    }
    ?>

### Notas

> Nota: Por razones de compatibilidad ascendente, el siguiente alias obsoleto puede ser utilizado: mysql_dbname()

### Ver también

- mysql_list_dbs() - Lista las bases de datos disponibles en un servidor MySQL
- mysql_tablename() - Obtiene el nombre de la tabla de un campo

# mysql_db_query

(PHP 4, PHP 5)

mysql_db_query — Selecciona una base de datos y ejecuta una consulta sobre la misma

Advertencia

Esta función estaba obsoleta en PHP 5.3.0, y toda la extensión original MySQL fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_select_db() y luego la consulta
- PDO::__construct()

### Descripción

function mysql_db_query(string `$database`, string `$query`, resource `$link_identifier` = NULL): resource|bool

mysql_db_query() selecciona una base de datos y ejecuta una consulta en ella.

### Parámetros

`database`
  El nombre de la base de datos que va a ser seleccionada.
`query`
  La consulta MySQL. Los datos dentro de la consulta deben ser escapados apropiadamente.
`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Devuelve un recurso de resultados de MySQL positivo al resultado de la consulta, o `false` en caso de error. La función también retorna `true`/`false` para las consultas `INSERT`/`UPDATE`/`DELETE` indicando éxito/fallo.

### Ejemplos

Ejemplo #1 Ejemplo alternativo de mysql_db_query()

    <?php

    if (!$enlace = mysql_connect('anfitrión_mysql', 'usuario_mysql', 'contraseña_mysql')) {
        echo 'No pudo conectarse a mysql';
        exit;
    }

    if (!mysql_select_db('nombre_bd_mysql', $enlace)) {
        echo 'No pudo seleccionar la base de datos';
        exit;
    }

    $sql       = 'SELECT foo FROM bar WHERE id = 42';
    $resultado = mysql_query($sql, $enlace);

    if (!$resultado) {
        echo "Error de BD, no se pudo consultar la base de datos\n";
        echo "Error MySQL: ' . mysql_error();
        exit;
    }

    while ($fila = mysql_fetch_assoc($resultado)) {
        echo $fila['foo'];
    }

    mysql_free_result($resultado);

    ?>

### Notas

> Nota: Se ha de tener en cuenta que ésta función NO vuelve a la base de datos a la que se estaba conectado anteriormente. En otras palabras, no se puede utilizar ésta función para ejecutar temporalmente una consulta SQL en otra base de datos; se tendría que hacer el cambio manualmente. Se recomienda encarecidamente usar la sintaxis `basedatos.tabla` en las consultas SQL o mysql_select_db() en lugar de esta función.

### Ver también

- mysql_query() - Enviar una consulta MySQL
- mysql_select_db() - Seleccionar una base de datos MySQL

# mysql_drop_db

(PHP 4, PHP 5)

mysql_drop_db — Elimina (DROP) una base de datos MySQL

Advertencia

Esta función estaba obsoleta en PHP 4.3.0, y toda la extensión original MySQL fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- Ejecutar una consulta `DROP DATABASE`

### Descripción

function mysql_drop_db(string `$database_name`, resource `$link_identifier` = NULL): bool

mysql_drop_db() intenta eliminar (remover) una base de datos entera del servidor asociado con el identificador de enlace especificado. Esta función es obsoleta; es preferible usar mysql_query() para ejecutar una sentencia SQL `DROP DATABASE` en su lugar.

### Parámetros

`database_name`
  El nombre de la base de datos que va a ser eliminada.
`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo alternativo de mysql_drop_db()

    <?php
    $enlace = mysql_connect('localhost', 'usuario_mysql', 'contraseña_mysql');
    if (!$enlace) {
        die('No pudo conectarse: ' . mysql_error());
    }

    $sql = 'DROP DATABASE mi_bd';
    if (mysql_query($sql, $enlace)) {
        echo "La base de datos mi_bd fue eliminada con éxito\n";
    } else {
        echo 'Error al eliminar la base de datos: ' . mysql_error() . "\n";
    }
    ?>

### Notas

Advertencia

Ésta función no estará disponible si la extensión MySQL fue construida con una biblioteca cliente MySQL 4.x.

> Nota: Por razones de compatibilidad ascendente, el siguiente alias obsoleto puede ser utilizado: mysql_dropdb()

### Ver también

- mysql_query() - Enviar una consulta MySQL

# mysql_errno

(PHP 4, PHP 5)

mysql_errno — Devuelve el valor numérico del mensaje de error de la última operación MySQL

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_errno()
- PDO::errorCode()

### Descripción

function mysql_errno(resource `$link_identifier` = NULL): int

Devuelve el número de error de la última función MySQL.

Los errores que provienen del procesamiento de la base de datos MySQL ya no emiten advertencias. En su lugar, utilice mysql_errno() para recuperar el código de error. Tenga en cuenta que ésta función solamente devolverá el código de error de la función MySQL ejecutada mas recientemente (sin incluir a mysql_error() y mysql_errno()), por lo que, si se quiere usar, hay que asegurarse de revisar el valor antes de llamar otra función MySQL.

### Parámetros

`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Devuelve el número de error de la última función de MySQL, o `0` (cero) si no ha ocurrido ningún error.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_errno()

    <?php
    $enlace = mysql_connect("localhost", "usuario_mysql", "contraseña_mysql");

    if (!mysql_select_db("bd_inexistente", $enlace)) {
        echo mysql_errno($enlace) . ": " . mysql_error($enlace). "\n";
    }

    mysql_select_db("kossu", $enlace);
    if (!mysql_query("SELECT * FROM tabla_inexistente", $enlace)) {
        echo mysql_errno($enlace) . ": " . mysql_error($enlace) . "\n";
    }
    ?>

Resultado del ejemplo anterior es similar a:

    1049: Unknown database 'bd_inexistente'
    1146: Table 'kossu.tabla_inexistente' doesn't exist

### Ver también

- mysql_error() - Devuelve el texto del mensaje de error de la operación MySQL anterior
- » Códigos de error de MySQL

# mysql_error

(PHP 4, PHP 5)

mysql_error — Devuelve el texto del mensaje de error de la operación MySQL anterior

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_error()
- PDO::errorInfo()

### Descripción

function mysql_error(resource `$link_identifier` = NULL): string

Devuelve el texto del error de la última función MySQL. Los errores que provienen del procesamiento de la base de datos MySQL ya no emiten advertencias. En su lugar, utilice mysql_errno() para recuperar el código de error. Tenga en cuenta que ésta función solamente devolverá el código de error de la función MySQL ejecutada mas recientemente (sin incluir a mysql_error() y mysql_errno()), por lo que, si se quiere usar, hay que asegurarse de revisar el valor antes de llamar otra función MySQL.

### Parámetros

`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Devuelve el texto del error de la última función MySQL, o `''` (una cadena vacía) si no ha ocurrido ningún error.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_error()

    <?php
    $enlace = mysql_connect("localhost", "usuario_mysql", "contraseña_mysql");

    mysql_select_db("bd_inexistente", $enlace);
    echo mysql_errno($enlace) . ": " . mysql_error($enlace). "\n";

    mysql_select_db("kossu", $enlace);
    mysql_query("SELECT * FROM tabla_inexistente", $enlace);
    echo mysql_errno($enlace) . ": " . mysql_error($enlace) . "\n";
    ?>

Resultado del ejemplo anterior es similar a:

    1049: Unknown database 'bd_inexistente'
    1146: Table 'kossu.tabla_inexistente' doesn't exist

### Ver también

- mysql_errno() - Devuelve el valor numérico del mensaje de error de la última operación MySQL
- » Códigos de error de MySQL

# mysql_escape_string

(PHP 4 >= 4.0.3, PHP 5)

mysql_escape_string — Escapa una cadena para ser usada en mysql_query

Advertencia

Esta función estaba obsoleta en PHP 4.3.0, y toda la extensión original MySQL fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_escape_string()
- PDO::quote()

### Descripción

function mysql_escape_string(string `$unescaped_string`): string

Esta función escapará `unescaped_string`, para que sea segura ponerla en una mysql_query(). Esta función está obsoleta.

Esta función es idéntica a mysql_real_escape_string() excepto que mysql_real_escape_string() toma un gestor de conexión y escapa la cadena de acuerdo con el juego de caracteres actual. mysql_escape_string() no toma un argumento de conexión y no respeta la configuración del juego de caracteres actual.

### Parámetros

`unescaped_string`
  La cadena que va a ser escapada.

### Valores devueltos

Devuelve la cadena escapada.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_escape_string()

    <?php
    $elemento = "Zak's Laptop";
    $elemento_escapado = mysql_escape_string($elemento);
    printf("Cadena escapada: %s\n", $elemento_escapado);
    ?>

El ejemplo anterior mostrará:

    Cadena escapada: Zak\'s Laptop

### Notas

> Nota: mysql_escape_string() no escapa los caracteres `%` y `_`.

### Ver también

- mysql_real_escape_string() - Escapa caracteres especiales en una cadena para su uso en una sentencia SQL

# mysql_fetch_array

(PHP 4, PHP 5)

mysql_fetch_array — Recupera una fila de resultados como un array asociativo, un array numérico o como ambos

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_fetch_array()
- PDOStatement::fetch()

### Descripción

function mysql_fetch_array(resource `$result`, int `$result_type` = MYSQL_BOTH): array

Devuelve un array que corresponde a la fila recuperada y mueve el puntero de datos interno hacia delante.

### Parámetros

`result`
  La resource de resultado que acaba de ser evaluada. Este resultado proviene de la llamada a la función mysql_query().
`result_type`
  El tipo de array que va a ser devuelto. Es una constante y puede tomar los siguientes valores: `MYSQL_ASSOC`, `MYSQL_NUM`, y `MYSQL_BOTH`.

### Valores devueltos

Devuelve un array de cadenas que corresponde a la fila recuperada, o `false` si no hay más filas. El tipo del array retornado depende de como esté definido `result_type`. Al utilizar `MYSQL_BOTH` (predeterminado), se obtendrá un array con ambos índices: asociativos y numéricos. Al utilizar `MYSQL_ASSOC`, se obtienen solo los índices asociativos (tal como funciona mysql_fetch_assoc()). Al utilizar `MYSQL_NUM`, se obtienen solo los índices numéricos (tal como funciona mysql_fetch_row()).

Si dos o más columnas del resultado tienen el mismo nombre de campo, la última columna tomará precedencia. Para acceder a la/s otra/s columna/s con el mismo nombre, se deberá usar el índice numérico de la columna o crear un alias para la columna. Para las columnas con alias, no se puede acceder al contenido con el nombre de la columna original.

### Ejemplos

Ejemplo #1 Consulta con nombres de campos duplicados con alias

    SELECT tabla1.campo AS foo, tabla2.campo AS bar FROM tabla1, tabla2

Ejemplo #2 mysql_fetch_array() con `MYSQL_NUM`

    <?php
    mysql_connect("localhost", "usuario_mysql", "contraseña_mysql") or
        die("No se pudo conectar: " . mysql_error());
    mysql_select_db("mibd");

    $resultado = mysql_query("SELECT id, nombre FROM mitabla");

    while ($fila = mysql_fetch_array($resultado, MYSQL_NUM)) {
        printf("ID: %s  Nombre: %s", $fila[0], $fila[1]);
    }

    mysql_free_result($resultado);
    ?>

Ejemplo #3 mysql_fetch_array() con `MYSQL_ASSOC`

    <?php
    mysql_connect("localhost", "usuario_mysql", "contraseña_mysql") or
        die("No se pudo conectar: " . mysql_error());
    mysql_select_db("mibd");

    $resultado = mysql_query("SELECT id, nombre FROM mitabla");

    while ($fila = mysql_fetch_array($resultado, MYSQL_ASSOC)) {
        printf("ID: %s  Nombre: %s", $fila["id"], $fila["nombre"]);
    }

    mysql_free_result($resultado);
    ?>

Ejemplo #4 mysql_fetch_array() con `MYSQL_BOTH`

    <?php
    mysql_connect("localhost", "usuario_mysql", "contraseña_mysql") or
        die("No se pudo conectar: " . mysql_error());
    mysql_select_db("mibd");

    $resultado = mysql_query("SELECT id, nombre FROM mitabla");

    while ($fila = mysql_fetch_array($resultado, MYSQL_BOTH)) {
        printf ("ID: %s  Nombre: %s", $fila[0], $fila["nombre"]);
    }

    mysql_free_result($resultado);
    ?>

### Notas

> Nota: Rendimiento
> Una cosa importante a tener en cuenta es que el uso de mysql_fetch_array() no es significativamente más lento que el uso de mysql_fetch_row(), aunque provee un valor añadido considerable.

> Nota: Los nombres de los campos devueltos por esta función son sensibles a la case.

> Nota: Esta función define los campos NULL al valor PHP `null`.

### Ver también

- mysql_fetch_row() - Obtiene una fila de resultados como un array numérico
- mysql_fetch_assoc() - Recupera una fila de resultados como un array asociativo
- mysql_data_seek() - Mueve el puntero de resultados interno
- mysql_query() - Enviar una consulta MySQL

# mysql_fetch_assoc

(PHP 4 >= 4.0.3, PHP 5)

mysql_fetch_assoc — Recupera una fila de resultados como un array asociativo

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_fetch_assoc()
- PDOStatement::fetch() con `mode` como `PDO::FETCH_ASSOC`

### Descripción

function mysql_fetch_assoc(resource `$result`): array

Devuelve un array asociativo que corresponde a la fila recuperada y mueve el puntero de datos interno hacia adelante. mysql_fetch_assoc() es equivalente a llamar a mysql_fetch_array() con MYSQL_ASSOC como segundo parámetro opcional. Únicamente devuelve un array asociativo.

### Parámetros

`result`
  La resource de resultado que acaba de ser evaluada. Este resultado proviene de la llamada a la función mysql_query().

### Valores devueltos

Devuelve un array asociativo de strings que corresponde a la fila recuperada, o `false` si no hay más filas disponibles.

Si dos o más columnas del resultado tienen los mismos nombres de campo, la última columna tomará precedencia. Para acceder a la/s otra/s columna/s con el mismo nombre, se tendrá que acceder al resultado con índices numéricos mediante el uso de mysql_fetch_row() o agregando sobrenombres. Véase el ejemplo en la descripción de mysql_fetch_array() respecto a los sobrenombres.

### Ejemplos

Ejemplo #1 Un ejemplo desarrolado de mysql_fetch_assoc()

    <?php

    $conexión = mysql_connect("localhost", "usuario_mysql", "contraseña_mysql");

    if (!$conexión) {
        echo "No pudo conectarse a la BD: " . mysql_error();
        exit;
    }

    if (!mysql_select_db("nombre_de_la_bd")) {
        echo "No ha sido posible seleccionar la BD: " . mysql_error();
        exit;
    }

    $sql = "SELECT id as id_usuario, nombre_completo, estatus_usuario
            FROM   alguna_tabla
            WHERE  estatus_usuario = 1";

    $resultado = mysql_query($sql);

    if (!$resultado) {
        echo "No se pudo ejecutar con exito la consulta ($sql) en la BD: " . mysql_error();
        exit;
    }

    if (mysql_num_rows($resultado) == 0) {
        echo "No se han encontrado filas, nada a imprimir, asi que voy a detenerme.";
        exit;
    }

    // Mientras exista una fila de datos, colocar esa fila en $fila como un array asociativo
    // Nota: Si solo espera una fila, no hay necesidad de usar un bucle
    // Nota: Si coloca extract($fila); dentro del siguiente bucle,
    //       estará creando $id_usuario, $nombre_completo, y $estatus_usuario
    while ($fila = mysql_fetch_assoc($resultado)) {
        echo $fila["id_usuario"];
        echo $fila["nombre_completo"];
        echo $fila["estatus_usuario"];
    }

    mysql_free_result($resultado);

    ?>

### Notas

> Nota: Rendimiento
> Algo importante a observar es que el uso de mysql_fetch_assoc() no es significativamente más lento que el uso de mysql_fetch_row(), aunque provee un valor añadido considerable.

> Nota: Los nombres de los campos devueltos por esta función son sensibles a la case.

> Nota: Esta función define los campos NULL al valor PHP `null`.

### Ver también

- mysql_fetch_row() - Obtiene una fila de resultados como un array numérico
- mysql_fetch_array() - Recupera una fila de resultados como un array asociativo, un array numérico o como ambos
- mysql_data_seek() - Mueve el puntero de resultados interno
- mysql_query() - Enviar una consulta MySQL
- mysql_error() - Devuelve el texto del mensaje de error de la operación MySQL anterior

# mysql_fetch_field

(PHP 4, PHP 5)

mysql_fetch_field — Obtiene la información de una columna de un resultado y la devuelve como un objeto

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_fetch_field()
- PDOStatement::getColumnMeta()

### Descripción

function mysql_fetch_field(resource `$result`, int `$field_offset` = 0): object

Devuelve un objeto que contiene la información de los campos. Esta función puede ser usada para obtener información sobre campos en el resultado de la consulta proporcionada.

### Parámetros

`result`
  La resource de resultado que acaba de ser evaluada. Este resultado proviene de la llamada a la función mysql_query().
`field_offset`
  El índice numérico del campo. Si el índice del campo no se especifica, se recuperará el siguiente campo que aún no haya recuperado esta función. Los índices de `field_offset` comienzan en `0`.

### Valores devueltos

Devuelve un object que contiene la información del campo. Las propiedades del objeto son:

- name - nombre de la columna
- table - nombre de la tabla a la que pertenece la columna, el cual es el sobrenombre si alguno está definido
- max_length - longitud máxima de la columna
- not_null - 1 si la columna no puede ser `null`
- primary_key - 1 si la columna es una clave primaria
- unique_key - 1 si la columna es una clave única
- multiple_key - 1 si la colmuna es una clave no única
- numeric - 1 si la columna es numérica
- blob - 1 si la columna es un BLOB
- type - el tipo de la columna
- unsigned - 1 si la columna es sin signo
- zerofill - 1 si la columna es rellena de ceros

### Ejemplos

Ejemplo #1 Ejemplo de mysql_fetch_field()

    <?php
    $conexión = mysql_connect('localhost', 'usuario_mysql', 'contraseña_mysql');
    if (!$conexión) {
        die('No se pudo conectar: ' . mysql_error());
    }
    mysql_select_db('basedatos');
    $resultado = mysql_query('select * from table');
    if (!$resultado) {
        die('Falló la consulta: ' . mysql_error());
    }
    /* obtener los metadatos de la columna */
    $i = 0;
    while ($i < mysql_num_fields($resultado)) {
        echo "Información de la columna $i:<br />\n";
        $metadatos = mysql_fetch_field($resultado, $i);
        if (!$metadatos) {
            echo "No hay información disponible<br />\n";
        }
        echo "<pre>
    blob:         $metadatos->blob
    max_length:   $metadatos->max_length
    multiple_key: $metadatos->multiple_key
    name:         $metadatos->name
    not_null:     $metadatos->not_null
    numeric:      $metadatos->numeric
    primary_key:  $metadatos->primary_key
    table:        $metadatos->table
    type:         $metadatos->type
    unique_key:   $metadatos->unique_key
    unsigned:     $metadatos->unsigned
    zerofill:     $metadatos->zerofill
    </pre>";
        $i++;
    }
    mysql_free_result($resultado);
    ?>

### Notas

> Nota: Los nombres de los campos devueltos por esta función son sensibles a la case.

> Nota: Si se usa un alias para los campos o los nombres de tablas en la consulta SQL se devolverá el nombre del alias. El nombre original se puede recuperar, por ejemplo, usando mysqli_result::fetch_field().

### Ver también

- mysql_field_seek() - Establece el puntero del resultado en un índice de campo específicado

# mysql_fetch_lengths

(PHP 4, PHP 5)

mysql_fetch_lengths — Obtiene la longitud de cada salida en un resultado

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_fetch_lengths()
- PDOStatement::getColumnMeta()

### Descripción

function mysql_fetch_lengths(resource `$result`): array|false

Devuelve un array que corresponde a las longitudes de cada campo de la última fila recuperada por MySQL.

mysql_fetch_lengths() almacena las longitudes de cada columna del resultado en la última fila devuelta mediante mysql_fetch_row(), mysql_fetch_assoc(), mysql_fetch_array(), y mysql_fetch_object() en un array, comenzando desde el índice 0.

### Parámetros

`result`
  La resource de resultado que acaba de ser evaluada. Este resultado proviene de la llamada a la función mysql_query().

### Valores devueltos

Un array de longitudes en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Un ejemplo de mysql_fetch_lengths()

    <?php
    $resultado = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$resultado) {
        echo 'No se pudo ejecutar la consulta: ' . mysql_error();
        exit;
    }
    $fila       = mysql_fetch_assoc($resultado);
    $longitudes = mysql_fetch_lengths($resultado);

    print_r($fila);
    print_r($longitudes);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [id] => 42
        [email] => user@example.com
    )
    Array
    (
        [0] => 2
        [1] => 16
     )

### Ver también

- mysql_field_len() - Devuelve la longitud del campo especificado
- mysql_fetch_row() - Obtiene una fila de resultados como un array numérico
- strlen() - Calcula el tamaño de un string

# mysql_fetch_object

(PHP 4, PHP 5)

mysql_fetch_object — Recupera una fila de resultados como un objeto

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_fetch_object()
- PDOStatement::fetch() con `mode` como `PDO::FETCH_OBJ`

### Descripción

function mysql_fetch_object(resource `$result`, string `$class_name` = ?, array `$params` = ?): object

Devuelve un objeto con propiedades que corresponden a la fila recuperada y mueve el puntero interno hacia delante.

### Parámetros

`result`
  La resource de resultado que acaba de ser evaluada. Este resultado proviene de la llamada a la función mysql_query().
`class_name`
  El nombre de la clase donde instanciar, configurar las propiedades y devolver. Si no se especifica, se devuelve un objeto stdClass.
`params`
  Un array opcional de parámetros para pasar al constructor de los objetos `class_name`.

### Valores devueltos

Devuelve un object con propiedades de tipo string que se corresponden con la fila recuperada, o `false` si no quedan más filas.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_fetch_object()

    <?php
    mysql_connect("nombre_anfitrión", "usuario", "contraseña");
    mysql_select_db("mibd");
    $resultado = mysql_query("select * from mitabla");
    while ($fila = mysql_fetch_object($resultado)) {
        echo $fila->id_usuario;
        echo $fila->nombre_completo;
    }
    mysql_free_result($resultado);
    ?>

Ejemplo #2 Ejemplo de mysql_fetch_object()

    <?php
    class foo {
        public $nombre;
    }

    mysql_connect("nombre_anfitrión", "usuario", "contraseña");
    mysql_select_db("mibd");

    $resultado = mysql_query("select nombre from mitabla limit 1");
    $objeto = mysql_fetch_object($resultado, 'foo');
    var_dump($objeto);
    ?>

### Notas

> Nota: Rendimiento
> En cuestión de velocidad, la función es idéntica a mysql_fetch_array(), y casi tan rápida como mysql_fetch_row() (la diferencia es insignificante).

> Nota: mysql_fetch_object() es similar a mysql_fetch_array(), con una diferencia: se devuelve un objeto, en lugar de un array. Indirectamente, esto significa que se puede acceder a los datos únicamente mediante los nombres de los campos, y no mediante sus índices (los números son ilegales como nombres de propiedades).

> Nota: Los nombres de los campos devueltos por esta función son sensibles a la case.

> Nota: Esta función define los campos NULL al valor PHP `null`.

### Ver también

- mysql_fetch_array() - Recupera una fila de resultados como un array asociativo, un array numérico o como ambos
- mysql_fetch_assoc() - Recupera una fila de resultados como un array asociativo
- mysql_fetch_row() - Obtiene una fila de resultados como un array numérico
- mysql_data_seek() - Mueve el puntero de resultados interno
- mysql_query() - Enviar una consulta MySQL

# mysql_fetch_row

(PHP 4, PHP 5)

mysql_fetch_row — Obtiene una fila de resultados como un array numérico

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_fetch_row()
- PDOStatement::fetch() con `mode` como `PDO::FETCH_NUM`

### Descripción

function mysql_fetch_row(resource `$result`): array

Devuelve un array numérico que corresponde a la fila recuperada y mueve el puntero de datos interno hacia delante.

### Parámetros

`result`
  La resource de resultado que acaba de ser evaluada. Este resultado proviene de la llamada a la función mysql_query().

### Valores devueltos

Devuelve un array numérico que corresponde a la fila recuperada, o `false` si no quedan más filas.

mysql_fetch_row() recupera una fila de datos del resultado asociado al identificador de resultados especificado. La fila es devuelta como un array. Cada columna del resultado es almacenada en un índice del array, empezando desde 0.

### Ejemplos

Ejemplo #1 Recuperar una fila con mysql_fetch_row()

    <?php
    $resultado = mysql_query("SELECT id, email FROM people WHERE id = '42'");
    if (!$resultado) {
        echo 'No se pudo ejecutar la consulta: ' . mysql_error();
        exit;
    }
    $fila = mysql_fetch_row($resultado);

    echo $fila[0]; // 42
    echo $fila[1]; // el valor de email
    ?>

### Notas

> Nota: Esta función define los campos NULL al valor PHP `null`.

### Ver también

- mysql_fetch_array() - Recupera una fila de resultados como un array asociativo, un array numérico o como ambos
- mysql_fetch_assoc() - Recupera una fila de resultados como un array asociativo
- mysql_fetch_object() - Recupera una fila de resultados como un objeto
- mysql_data_seek() - Mueve el puntero de resultados interno
- mysql_fetch_lengths() - Obtiene la longitud de cada salida en un resultado
- mysql_result() - Obtener datos de resultado

# mysql_field_flags

(PHP 4, PHP 5)

mysql_field_flags — Obtiene las banderas asociadas al campo especificado de un resultado

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_fetch_field_direct() [flags]
- PDOStatement::getColumnMeta() [flags]

### Descripción

function mysql_field_flags(resource `$result`, int `$field_offset`): string|false

mysql_field_flags() devuelve las banderas del campo especificado. Las banderas son reportadas como una sola palabra por bandera, separada por un solo espacio, por lo que se puede dividir el valor devuelto usando explode().

### Parámetros

`result`
  La resource de resultado que acaba de ser evaluada. Este resultado proviene de la llamada a la función mysql_query().
`field_offset`
  La posición numérica del campo. `field_offset` comienza en `0`. Si `field_offset` no existe, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Devuelve un string de banderas asociadas con el resultado o `false` si ocurre un error.

Las siguientes banderas son reportadas si la versión de MySQL es suficientemente actual para soportarlas: `"not_null"`, `"primary_key"`, `"unique_key"`, `"multiple_key"`, `"blob"`, `"unsigned"`, `"zerofill"`, `"binary"`, `"enum"`, `"auto_increment"` y `"timestamp"`.

### Ejemplos

Ejemplo #1 Un ejemplo de mysql_field_flags()

    <?php
    $resultado = mysql_query("SELECT id, email FROM people WHERE id = '42'");
    if (!$resultado) {
        echo 'No se pudo ejecutar la consulta: ' . mysql_error();
        exit;
    }
    $banderas = mysql_field_flags($resultado, 0);

    echo $banderas;
    print_r(explode(' ', $banderas));
    ?>

Resultado del ejemplo anterior es similar a:

    not_null primary_key auto_increment
    Array
    (
        [0] => not_null
        [1] => primary_key
        [2] => auto_increment
    )

### Notas

> Nota: Por razones de compatibilidad ascendente, el siguiente alias obsoleto puede ser utilizado: mysql_fieldflags()

### Ver también

- mysql_field_type() - Obtiene el tipo del campo especificado de un resultado
- mysql_field_len() - Devuelve la longitud del campo especificado

# mysql_field_len

(PHP 4, PHP 5)

mysql_field_len — Devuelve la longitud del campo especificado

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_fetch_field_direct() [length]
- PDOStatement::getColumnMeta() [len]

### Descripción

function mysql_field_len(resource `$result`, int `$field_offset`): int|false

mysql_field_len() devuelve la longitud del campo especificado.

### Parámetros

`result`
  La resource de resultado que acaba de ser evaluada. Este resultado proviene de la llamada a la función mysql_query().
`field_offset`
  La posición numérica del campo. `field_offset` comienza en `0`. Si `field_offset` no existe, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

La longitud del índice del campo especificado en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_field_len()

    <?php
    $resultado = mysql_query("SELECT id, email FROM people WHERE id = '42'");
    if (!$resultado) {
        echo 'No se pudo ejecutar la consulta: ' . mysql_error();
        exit;
    }

    // Se obtendrá la longitud del campo id tal como está especificado en el esquema
    // de la base de datos.
    $longitud = mysql_field_len($resultado, 0);
    echo $longitud;
    ?>

### Notas

> Nota: Por razones de compatibilidad ascendente, el siguiente alias obsoleto puede ser utilizado: mysql_fieldlen()

### Ver también

- mysql_fetch_lengths() - Obtiene la longitud de cada salida en un resultado
- strlen() - Calcula el tamaño de un string

# mysql_field_name

(PHP 4, PHP 5)

mysql_field_name — Obtiene el nombre del campo especificado de un resultado

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_fetch_field_direct() [name] o [orgname]
- PDOStatement::getColumnMeta() [name]

### Descripción

function mysql_field_name(resource `$result`, int `$field_offset`): string|false

mysql_field_name() devuelve el nombre del índice del campo especificado.

### Parámetros

`result`
  La resource de resultado que acaba de ser evaluada. Este resultado proviene de la llamada a la función mysql_query().
`field_offset`
  La posición numérica del campo. `field_offset` comienza en `0`. Si `field_offset` no existe, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

El nombre del índice del campo especificado en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_field_name()

    <?php
    /* La tabla usuarios consiste de tres campos:
     *   user_id
     *   username
     *   password.
     */
    $enlace = mysql_connect('localhost', 'usuario_mysql', 'contraseña_mysql');
    if (!$enlace) {
        die('No se pudo conectar al servidor MySQL: ' . mysql_error());
    }
    $nombre_bd = 'mibd';
    $bd_seleccionada = mysql_select_db($nombre_bd, $enlace);
    if (!$bd_seleccionada) {
        die("No se pudo establecer $nombre_bd: " . mysql_error());
    }
    $resultado = mysql_query('select * from usuarios', $enlace);

    echo mysql_field_name($resultado, 0) . "\n";
    echo mysql_field_name($resultado, 2);
    ?>

El ejemplo anterior mostrará:

    user_id
    password

### Notas

> Nota: Los nombres de los campos devueltos por esta función son sensibles a la case.

> Nota: Por razones de compatibilidad ascendente, el siguiente alias obsoleto puede ser utilizado: mysql_fieldname()

### Ver también

- mysql_field_type() - Obtiene el tipo del campo especificado de un resultado
- mysql_field_len() - Devuelve la longitud del campo especificado

# mysql_field_seek

(PHP 4, PHP 5)

mysql_field_seek — Establece el puntero del resultado en un índice de campo específicado

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_field_seek()
- PDOStatement::fetch() empleando los parámetros `cursor_orientation` y `offset`

### Descripción

function mysql_field_seek(resource `$result`, int `$field_offset`): bool

Busca el índice del campo especificado. Si la siguiente llamada a mysql_fetch_field() no incluye un índice de campo, será devuelto el índice del campo especificado en mysql_field_seek().

### Parámetros

`result`
  La resource de resultado que acaba de ser evaluada. Este resultado proviene de la llamada a la función mysql_query().
`field_offset`
  La posición numérica del campo. `field_offset` comienza en `0`. Si `field_offset` no existe, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- mysql_fetch_field() - Obtiene la información de una columna de un resultado y la devuelve como un objeto

# mysql_field_table

(PHP 4, PHP 5)

mysql_field_table — Obtiene el nombre de la tabla en la que está el campo especificado

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_fetch_field_direct() [table] o [orgtable]
- PDOStatement::getColumnMeta() [table]

### Descripción

function mysql_field_table(resource `$result`, int `$field_offset`): string

Devuelve el nombre de la tabla en la que está el campo especificado.

### Parámetros

`result`
  La resource de resultado que acaba de ser evaluada. Este resultado proviene de la llamada a la función mysql_query().
`field_offset`
  La posición numérica del campo. `field_offset` comienza en `0`. Si `field_offset` no existe, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

El nombre de la tabla en caso de éxito.

### Ejemplos

Ejemplo #1 Un ejemplo de mysql_field_table()

    <?php

    $consulta = "SELECT account.*, country.* FROM account, country WHERE country.name = 'Portugal' AND account.country_id = country.id";

    // obtener el resultado desde la BD
    $resultado = mysql_query($consulta);

    // Lista el nombre de la tabla y luego el nombre del campo
    for ($i = 0; $i < mysql_num_fields($resultado); ++$i) {
        $tabla = mysql_field_table($resultado, $i);
        $campo = mysql_field_name($resultado, $i);

        echo  "$tabla: $campo\n";
    }

    ?>

### Notas

> Nota: Por razones de compatibilidad ascendente, el siguiente alias obsoleto puede ser utilizado: mysql_fieldtable()

### Ver también

- mysql_list_tables() - Lista las tablas de una base de datos MySQL

# mysql_field_type

(PHP 4, PHP 5)

mysql_field_type — Obtiene el tipo del campo especificado de un resultado

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_fetch_field_direct() [type]
- PDOStatement::getColumnMeta() [driver:decl_type] o [pdo_type]

### Descripción

function mysql_field_type(resource `$result`, int `$field_offset`): string

mysql_field_type() es similar a la función mysql_field_name(). Los argumentos son idénticos, pero se devuelve en su lugar el tipo de campo.

### Parámetros

`result`
  La resource de resultado que acaba de ser evaluada. Este resultado proviene de la llamada a la función mysql_query().
`field_offset`
  La posición numérica del campo. `field_offset` comienza en `0`. Si `field_offset` no existe, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

El tipo de campo devuelto será uno de los siguientes: `"int"`, `"real"`, `"string"`, `"blob"`, y otros tal como se detalla en » la documentación de MySQL.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_field_type()

    <?php
    mysql_connect("localhost", "nombre_usuario_mysql", "cotraseña_mysql");
    mysql_select_db("mysql");
    $resultado = mysql_query("SELECT * FROM func");
    $campos    = mysql_num_fields($resultado);
    $filas     = mysql_num_rows($resultado);
    $tabla     = mysql_field_table($resultado, 0);
    echo "Su tabla '" . $tabla . "' tiene " . $campos . " campos y " . $filas . " registro/s\n";
    echo "La tabla tiene los siguientes campos:\n";
    for ($i=0; $i < $campos; $i++) {
        $tipo     = mysql_field_type($resultado, $i);
        $nombre   = mysql_field_name($resultado, $i);
        $longitud = mysql_field_len($resultado, $i);
        $banderas = mysql_field_flags($resultado, $i);
        echo $tipo . " " . $nombre . " " . $longitud . " " . $banderas . "\n";
    }
    mysql_free_result($resultado);
    mysql_close();
    ?>

Resultado del ejemplo anterior es similar a:

    Su tabla 'func' tiene 4 campos y 1 registro/s
    La tabla tiene los siguientes campos:
    string name 64 not_null primary_key binary
    int ret 1 not_null
    string dl 128 not_null
    string type 9 not_null enum

### Notas

> Nota: Por razones de compatibilidad ascendente, el siguiente alias obsoleto puede ser utilizado: mysql_fieldtype()

### Ver también

- mysql_field_name() - Obtiene el nombre del campo especificado de un resultado
- mysql_field_len() - Devuelve la longitud del campo especificado

# mysql_free_result

(PHP 4, PHP 5)

mysql_free_result — Libera la memoria del resultado

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_free_result()
- Asignar el valor de `null` al objeto PDO, o PDOStatement::closeCursor()

### Descripción

function mysql_free_result(resource `$result`): bool

mysql_free_result() liberará toda la memoria asociada con el identificador del resultado `result`.

mysql_free_result() solo necesita ser llamado si se está preocupado por la cantidad de memoria que está siendo usada por las consultas que devuelven conjuntos de resultados grandes. Toda la memoria de resultados asociada se liberará automaticamente al finalizar la ejecución del script.

### Parámetros

`result`
  La resource de resultado que acaba de ser evaluada. Este resultado proviene de la llamada a la función mysql_query().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

Si se utiliza un recurso no válido para `result`, se emitirá un error de nivel E_WARNING. Vale la pena señalar que mysql_query() solo devuelve un recurso para las consultas SELECT, SHOW, EXPLAIN, y DESCRIBE.

### Ejemplos

Ejemplo #1 Un ejemplo de mysql_free_result()

    <?php
    $resultado = mysql_query("SELECT id, email FROM people WHERE id = '42'");
    if (!$resultado) {
        echo 'No se pudo ejecutar la consulta: ' . mysql_error();
        exit;
    }
    /* Usamos el resultado, asumiendo que, acto seguido, hemos terminado con él */
    $fila = mysql_fetch_assoc($resultado);

    /* Ahora liberamos el resultado y continuamos con nuestro script */
    mysql_free_result($resultado);

    echo $fila['id'];
    echo $fila['email'];
    ?>

### Notas

> Nota: Por razones de compatibilidad ascendente, el siguiente alias obsoleto puede ser utilizado: mysql_freeresult()

### Ver también

- mysql_query() - Enviar una consulta MySQL
- is_resource() - Determina si una variable es un recurso

# mysql_get_client_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_client_info — Obtiene información del cliente MySQL

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_get_client_info()
- PDO::getAttribute() con `attribute` como `PDO::ATTR_CLIENT_VERSION`

### Descripción

function mysql_get_client_info(): string

mysql_get_client_info() devuelve un string que representa la versión de la biblioteca cliente.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

La versión del cliente MySQL.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_get_client_info()

    <?php
    printf("Información del cliente MySQL: %s\n", mysql_get_client_info());
    ?>

Resultado del ejemplo anterior es similar a:

    Información del cliente MySQL: 3.23.39

### Ver también

- mysql_get_host_info() - Obtener información del anfitrión de MySQL
- mysql_get_proto_info() - Obtener información del protocolo MySQL
- mysql_get_server_info() - Obtiene información del servidor MySQL

# mysql_get_host_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_host_info — Obtener información del anfitrión de MySQL

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_get_host_info()
- PDO::getAttribute() con `attribute` como `PDO::ATTR_CONNECTION_STATUS`

### Descripción

function mysql_get_host_info(resource `$link_identifier` = NULL): string|false

Describe el tipo de conexión en uso, incluyendo el nombre del servidor anfitrión.

### Parámetros

`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Devuelve un string que describe el tipo de conexión MySQL en uso, o o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_get_host_info()

    <?php
    $enlace = mysql_connect("localhost", "usuario_mysql", "contraseña_mysql");
    if (!$enlace) {
        die("No pudo conectarse: " . mysql_error());
    }
    printf("Información del anfitrión de MySQL: %s\n", mysql_get_host_info());
    ?>

Resultado del ejemplo anterior es similar a:

    Información del anfitrión de MySQL: Localhost via UNIX socket

### Ver también

- mysql_get_client_info() - Obtiene información del cliente MySQL
- mysql_get_proto_info() - Obtener información del protocolo MySQL
- mysql_get_server_info() - Obtiene información del servidor MySQL

# mysql_get_proto_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_proto_info — Obtener información del protocolo MySQL

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_get_proto_info()

### Descripción

function mysql_get_proto_info(resource `$link_identifier` = NULL): int|false

Recupera el protocolo MySQL.

### Parámetros

`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Devuelve el protocolo MySQL en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_get_proto_info()

    <?php
    $enlace = mysql_connect("localhost", "usuario_mysql", "contraseña_mysql");
    if (!$enlace) {
        die("No pudo conectarse: " . mysql_error());
    }
    printf("Versión del protocolo MySQL: %s\n", mysql_get_proto_info());
    ?>

Resultado del ejemplo anterior es similar a:

    Versión del protocolo MySQL: 10

### Ver también

- mysql_get_client_info() - Obtiene información del cliente MySQL
- mysql_get_host_info() - Obtener información del anfitrión de MySQL
- mysql_get_server_info() - Obtiene información del servidor MySQL

# mysql_get_server_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_server_info — Obtiene información del servidor MySQL

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_get_server_info()
- PDO::getAttribute() con `attribute` como `PDO::ATTR_SERVER_VERSION`

### Descripción

function mysql_get_server_info(resource `$link_identifier` = NULL): string|false

Recupera la versión del servidor MySQL.

### Parámetros

`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Devuelve la versión del servidor MySQL en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_get_server_info()

    <?php
    $enlace = mysql_connect("localhost", "usuario_mysql", "contraseña_mysql");
    if (!$enlace) {
        die("No pudo conectarse: " . mysql_error());
    }
    printf("Versión del servidor MySQL: %s\n", mysql_get_server_info());
    ?>

Resultado del ejemplo anterior es similar a:

    Versión del servidor MySQL: 4.0.1-alpha

### Ver también

- mysql_get_client_info() - Obtiene información del cliente MySQL
- mysql_get_host_info() - Obtener información del anfitrión de MySQL
- mysql_get_proto_info() - Obtener información del protocolo MySQL
- phpversion() - Devuelve el número de la versión actual de PHP

# mysql_info

(PHP 4 >= 4.3.0, PHP 5)

mysql_info — Obtiene información sobre la consulta más reciente

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_info()

### Descripción

function mysql_info(resource `$link_identifier` = NULL): string

Devuelve información detallada sobre la última consulta.

### Parámetros

`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Devuele información sobre la sentencia en caso de éxito, o `false` en caso de error. Vea el ejemplo siguiente para conocer qué sentencias proveen información, y cuál puede ser la apariencia del valor devuelto. Las sentencias que no están en la lista devolverán `false`.

### Ejemplos

Ejemplo #1 Sentencias MySQL Relevantes

Sentencias que devuelven valores de tipo cadena. Los números están únicamente por propósitos ilustrativos; sus valores corresponderán con la consulta.

    INSERT INTO ... SELECT ...
    String format: Records: 23 Duplicates: 0 Warnings: 0
    INSERT INTO ... VALUES (...),(...),(...)...
    String format: Records: 37 Duplicates: 0 Warnings: 0
    LOAD DATA INFILE ...
    String format: Records: 42 Deleted: 0 Skipped: 0 Warnings: 0
    ALTER TABLE
    String format: Records: 60 Duplicates: 0 Warnings: 0
    UPDATE
    String format: Rows matched: 65 Changed: 65 Warnings: 0

### Notas

> Nota: mysql_info() devuelve un valor diferente a `false` para la sentencia INSERT ... VALUES sólo si se indican múltiples listas de valores en la sentencia.

### Ver también

- mysql_affected_rows() - Obtiene el número de filas afectadas en la anterior operación de MySQL
- mysql_insert_id() - Obtiene el ID generado en la última consulta
- mysql_stat() - Obtiene el estado actual del sistema

# mysql_insert_id

(PHP 4, PHP 5)

mysql_insert_id — Obtiene el ID generado en la última consulta

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_insert_id()
- PDO::lastInsertId()

### Descripción

function mysql_insert_id(resource `$link_identifier` = NULL): int

Recupera el ID generado por la consulta anterior (normalmente INSERT) para una columna AUTO_INCREMENT.

### Parámetros

`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

El ID generado por la consulta anterior para una columna AUTO_INCREMENT en caso de éxito, `0` si la consulta anterior no genera un valor AUTO_INCREMENT, o `false` si no se estableció una conexión MySQL.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_insert_id()

    <?php
    $enlace = mysql_connect('localhost', 'usuario_mysql', 'contraseña_mysql');
    if (!$enlace) {
        die('No se pudo conectar: ' . mysql_error());
    }
    mysql_select_db('mibd');

    mysql_query("INSERT INTO mitabla (producto) values ('kossu')");
    printf("El último registro insertado tiene el id %d\n", mysql_insert_id());
    ?>

### Notas

Precaución

mysql_insert_id() convertirá el tipo devuelto de la función nativa `mysql_insert_id()` de la API de C de MySQL a un tipo `long` (llamado int en PHP). Si la columna AUTO_INCREMENT tiene un tipo BIGINT (64 bits) la conversión puede resultar en un valor incorrecto. En su lugar, use la función de SQL interna LAST_INSERT_ID() de MySQL en una consulta SQL. Para más información sobre los valores máximos de tipo integer, por favor vea la documentación de integer.

> Nota: Como mysql_insert_id() actúa en la última consulta realizada, asegúrese de llamar a mysql_insert_id() inmediatamente después de la consulta que genera el valor.

> Nota: El valor de la función de SQL `LAST_INSERT_ID()` de MySQL siempre contiene el valor AUTO_INCREMENT generado más recientientemente, y no se restablece entre consultas.

### Ver también

- mysql_query() - Enviar una consulta MySQL
- mysql_info() - Obtiene información sobre la consulta más reciente

# mysql_list_dbs

(PHP 4, PHP 5)

mysql_list_dbs — Lista las bases de datos disponibles en un servidor MySQL

Advertencia

Esta función estaba obsoleta en PHP 5.4.0, y toda la extensión original MySQL fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- Consulta SQL: `SHOW DATABASES`

### Descripción

function mysql_list_dbs(resource `$link_identifier` = NULL): resource

Devuelve un puntero de resultados que contiene las bases de datos disponibles en el demonio de mysql actual.

### Parámetros

`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Devuelve un resource de puntero de resultados en caso de éxito, o `false` en caso de error. Use la función mysql_tablename() para atravesar este puntero de resultado, o cualquier función para obtener tablas, tal como mysql_fetch_array().

### Ejemplos

Ejemplo #1 Ejemplo de mysql_list_dbs()

    <?php
    // Uso sin mysql_list_dbs()
    $enlace = mysql_connect('localhost', 'usuario_mysql', 'contraseña_mysql');
    $resultado = mysql_query("SHOW DATABASES");

    while ($fila = mysql_fetch_assoc($res)) {
        echo $fila['Database'] . "\n";
    }

    // Obsoleto a partir de PHP 5.4.0
    $enlace = mysql_connect('localhost', 'usuario_mysql', 'contraseña_mysql');
    $lista_bd = mysql_list_dbs($enlace);

    while ($fila = mysql_fetch_object($lista_bd)) {
         echo $fila->Database . "\n";
    }
    ?>

Resultado del ejemplo anterior es similar a:

    basedatos1
    basedatos2
    basedatos3

### Notas

> Nota: Por razones de compatibilidad ascendente, el siguiente alias obsoleto puede ser utilizado: mysql_listdbs()

### Ver también

- mysql_db_name() - Recupera el nombre de la base de datos desde una llamada a mysql_list_dbs
- mysql_select_db() - Seleccionar una base de datos MySQL

# mysql_list_fields

(PHP 4, PHP 5)

mysql_list_fields — Lista los campos de una tabla de MySQL

Advertencia

Esta función estaba obsoleta en PHP 5.4.0, y toda la extensión original MySQL fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- Consulta SQL: `SHOW COLUMNS FROM alguna_tabla`

### Descripción

function mysql_list_fields(string `$database_name`, string `$table_name`, resource `$link_identifier` = NULL): resource

Devuelve información sobre el nombre de la tabla dado.

Esta función está obsoleta. Es preferible usar mysql_query() para ejecutar una consulta SQL `SHOW COLUMNS FROM tabla [LIKE 'nombre']` en su lugar.

### Parámetros

`database_name`
  El nombre de la base de la base de datos que está siendo consultada.
`table_name`
  El nombre de la tabla que está siendo consultada.
`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Un resource del puntero del resultado en caso de éxito, o `false` en caso de error.

El resultado devuelto puede ser usado con mysql_field_flags(), mysql_field_len(), mysql_field_name() y mysql_field_type().

### Ejemplos

Ejemplo #1 Alternativa para la obsoleta mysql_list_fields()

    <?php
    $resultado = mysql_query("SHOW COLUMNS FROM alguna_tabla");
    if (!$resultado) {
        echo 'No se pudo ejecutar la consulta: ' . mysql_error();
        exit;
    }
    if (mysql_num_rows($resultado) > 0) {
        while ($fila = mysql_fetch_assoc($resultado)) {
            print_r($fila);
        }
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [Field] => id
        [Type] => int(7)
        [Null] =>
        [Key] => PRI
        [Default] =>
        [Extra] => auto_increment
    )
    Array
    (
        [Field] => email
        [Type] => varchar(100)
        [Null] =>
        [Key] =>
        [Default] =>
        [Extra] =>
    )

### Notas

> Nota: Por razones de compatibilidad ascendente, el siguiente alias obsoleto puede ser utilizado: mysql_listfields()

### Ver también

- mysql_field_flags() - Obtiene las banderas asociadas al campo especificado de un resultado
- mysql_info() - Obtiene información sobre la consulta más reciente

# mysql_list_processes

(PHP 4 >= 4.3.0, PHP 5)

mysql_list_processes — Lista los procesos de MySQL

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_thread_id()

### Descripción

function mysql_list_processes(resource `$link_identifier` = NULL): resource|false

Recupera los hilos del servidor MySQL actuales.

### Parámetros

`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Un puntero de resultados de tipo resource en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_list_processes()

    <?php
    $enlace = mysql_connect('localhost', 'usuario_mysql', 'contraseña_mysql');

    $resultado = mysql_list_processes($enlace);

    while ($fila = mysql_fetch_assoc($resultado)){
        printf("%s %s %s %s %s\n", $fila["Id"], $fila["Host"], $fila["db"],
            $fila["Command"], $fila["Time"]);
    }
    mysql_free_result($resultado);
    ?>

Resultado del ejemplo anterior es similar a:

    1 localhost test Processlist 0
    4 localhost mysql sleep 5

### Ver también

- mysql_thread_id() - Devuelve el ID del hilo actual
- mysql_stat() - Obtiene el estado actual del sistema

# mysql_list_tables

(PHP 4, PHP 5)

mysql_list_tables — Lista las tablas de una base de datos MySQL

Advertencia

Esta función estaba obsoleta en PHP 4.3.0, y toda la extensión original MySQL fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- Consulta SQL: `SHOW TABLES FROM dbname`

### Descripción

function mysql_list_tables(string `$database`, resource `$link_identifier` = NULL): resource|false

Lista las tablas de una base de datos MySQL especificada.

Esta función está deprecada. Es preferible utilizar la función mysql_query() para ejecutar la consulta SQL `SHOW TABLES [FROM db_name] [LIKE 'pattern']` en su lugar.

### Parámetros

`database`
  El nombre de la base de datos
`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Un puntero de resultados resource en caso de éxito o `false` si ocurre un error.

Utilice la función mysql_tablename() para recorrer este puntero de resultados o cualquier otra función para los resultados de tablas, como la función mysql_fetch_array().

### Ejemplos

Ejemplo #1 Ejemplo de alternativa a mysql_list_tables()

    <?php
    $dbname = 'mysql_dbname';

    if (!mysql_connect('mysql_host', 'mysql_user', 'mysql_password')) {
       echo 'No es posible conectarse a MySQL';
       exit;
    }

    $sql = "SHOW TABLES FROM $dbname";
    $result = mysql_query($sql);

    if (!$result) {
       echo "Error DB, no es posible listar las tablas\n";
       echo 'Error MySQL : ' . mysql_error();
       exit;
    }

    while ($row = mysql_fetch_row($result)) {
       echo "Tabla : {$row[0]}\n";
    }

    mysql_free_result($result);
    ?>

### Notas

> Nota: Por razones de compatibilidad ascendente, el siguiente alias obsoleto puede ser utilizado: mysql_listtables()

### Ver también

- mysql_list_dbs() - Lista las bases de datos disponibles en un servidor MySQL
- mysql_tablename() - Obtiene el nombre de la tabla de un campo

# mysql_num_fields

(PHP 4, PHP 5)

mysql_num_fields — Obtiene el número de campos de un resultado

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_num_fields()
- PDOStatement::columnCount()

### Descripción

function mysql_num_fields(resource `$result`): int|false

Obtiene el número de campos de una consulta.

### Parámetros

`result`
  La resource de resultado que acaba de ser evaluada. Este resultado proviene de la llamada a la función mysql_query().

### Valores devueltos

Devuelve el número de campos del resource de conjunto de resultados en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Un ejemplo de mysql_num_fields()

    <?php
    $resultado = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$resultado) {
        echo 'No se pudo ejecutar la consulta: ' . mysql_error();
        exit;
    }

    /* devuelve 2 ya que id,email === dos campos */
    echo mysql_num_fields($resultado);
    ?>

### Notas

> Nota: Por razones de compatibilidad ascendente, el siguiente alias obsoleto puede ser utilizado: mysql_numfields()

### Ver también

- mysql_select_db() - Seleccionar una base de datos MySQL
- mysql_query() - Enviar una consulta MySQL
- mysql_fetch_field() - Obtiene la información de una columna de un resultado y la devuelve como un objeto
- mysql_num_rows() - Obtener el número de filas de un conjunto de resultados

# mysql_num_rows

(PHP 4, PHP 5)

mysql_num_rows — Obtener el número de filas de un conjunto de resultados

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_num_rows()
- mysqli_stmt_num_rows()
- PDOStatement::rowCount()

### Descripción

function mysql_num_rows(resource `$result`): int|false

Recupera el número de filas de un conjunto de resultados. Este comando es únicamente válido para sentencias como SELECT o SHOW que retornan un conjunto de resultados real. Para recuperar el número de filas afectadas por una consulta INSERT, UPDATE, REPLACE o DELETE, use mysql_affected_rows().

### Parámetros

`result`
  La resource de resultado que acaba de ser evaluada. Este resultado proviene de la llamada a la función mysql_query().

### Valores devueltos

El número de filas de un conjunto de resultados en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_num_rows()

    <?php

    $enlace = mysql_connect("localhost", "usuario_mysql", "contraseña_mysql");
    mysql_select_db("basedatos", $enlace);

    $resultado = mysql_query("SELECT * FROM tabla1", $enlace);
    $número_filas = mysql_num_rows($resultado);

    echo "$número_filas Filas\n";

    ?>

### Notas

> Nota: Si se utiliza mysql_unbuffered_query(), mysql_num_rows() no retornará el valor correcto hasta que se hayan recuperado todas las filas del conjunto de resultados.

> Nota: Por razones de compatibilidad ascendente, el siguiente alias obsoleto puede ser utilizado: mysql_numrows()

### Ver también

- mysql_affected_rows() - Obtiene el número de filas afectadas en la anterior operación de MySQL
- mysql_connect() - Abre una conexión al servidor MySQL
- mysql_data_seek() - Mueve el puntero de resultados interno
- mysql_select_db() - Seleccionar una base de datos MySQL
- mysql_query() - Enviar una consulta MySQL

# mysql_pconnect

(PHP 4, PHP 5)

mysql_pconnect — Abre una conexión persistente a un servidor MySQL

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_connect() con el prefijo de host `p:`
- PDO::__construct() con `PDO::ATTR_PERSISTENT` como una opción de controlador

### Descripción

function mysql_pconnect(
string `$server` = ini_get("mysql.default_host"),
string `$username` = ini_get("mysql.default_user"),
string `$password` = ini_get("mysql.default_password"),
int `$client_flags` = 0
): resource

Establece una conexión persistente a un servidor MySQL.

mysql_pconnect() se parece mucho a mysql_connect() con dos grandes diferencias.

En primer lugar, cuando se conecta, la función primero intenta encontrar un enlace (persistente) que ya esté abierto con el mismo anfitrión, nombre de usuario y contraseña. Si se encuentra uno, se devolverá un identificador para él, en lugar de abrir una nueva conexión.

Segundo, la conexión al servidor SQL no será cerrada cuando la ejecución del script finalice. En su lugar, el enlace permanecerá abierto para su uso futuro (mysql_close() no cerrará los enlaces establecidos mediante mysql_pconnect()).

Por eso a este tipo de enlace se le llama 'persistente'.

### Parámetros

`server`
  El servidor de MySQL. También puede incluir un número de puerto. P.ej. "nombre_anfitrión:puerto" o una ruta a un socket local, p.ej. ":/ruta/al/socket" para el localhost. Si la directiva de PHP mysql.default_host no se ha definido (predeterminado), entonces el valor por defecto es 'localhost:3306'
`username`
  El nombre de usuario. El valor por defecto es el nombre del usuario al que pertenece el proceso del servidor.
`password`
  La contraseña. El valor por defecto es una contraseña vacia.
`client_flags`
  El parámetro `client_flags` puede ser una combinación de las siguientes constantes: 128 (habilita el manejo de `LOAD DATA LOCAL`), `MYSQL_CLIENT_SSL`, `MYSQL_CLIENT_COMPRESS`, `MYSQL_CLIENT_IGNORE_SPACE` o `MYSQL_CLIENT_INTERACTIVE`.

### Valores devueltos

Devuelve un identificador de enlace persistente a MySQL en caso de éxito o `false` en caso de error.

### Notas

> Nota: Tenga en cuenta que este tipo de enlaces solo funcionan si se está usando una versión de módulo de PHP. Véase la sección Conexiones persistentes a bases de datos para más información.

Advertencia

El uso de conexiones persistentes puede requerir ajustar un poco las configuraciones de Apache y de MySQL para asegurarse de que no se excede el número de conexiones permitidas por MySQL.

### Ver también

- mysql_connect() - Abre una conexión al servidor MySQL
- Conexiones persistentes a bases de datos

# mysql_ping

(PHP 4 >= 4.3.0, PHP 5)

mysql_ping — Efectuar un chequeo de respuesta (ping) sobre una conexión al servidor o reconectarse si no hay conexión

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_ping()

### Descripción

function mysql_ping(resource `$link_identifier` = NULL): bool

Chequea si está activa o no la conexión con el servidor. Si ésta se ha caído, se intenta una reconexión automática. Esta función puede ser usada por scripts que permanecen pasivos durante largos espacios de tiempo, para chequear si el servidor ha cerrado la conexión y reconectarse de ser necesario.

> Nota: La reconexión automática está deshabilitada de forma predeterminada en versiones de MySQL >= 5.0.3.

### Parámetros

`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Devuelve `true` si la conexión con el servidor MySQL está funcionando, o `false` si no.

### Ejemplos

Ejemplo #1 Un ejemplo de mysql_ping()

    <?php
    set_time_limit(0);

    $conexión = mysql_connect('localhost', 'usuario_mysql', 'contraseña');
    $bd  = mysql_select_db('mi_bd');

    /* Se asume que esta consulta toma mucho tiempo */
    $resultado = mysql_query($sql);
    if (!$resultado) {
        echo 'La consulta #1 falló; Saliendo.';
        exit;
    }

    /* Asegurarse de que la conexión sigue viva, si no, intentar una reconexión */
    if (!mysql_ping($conexión)) {
        echo 'Se ha perdido la conexión, saliendo después de la consulta #1';
        exit;
    }
    mysql_free_result($resultado);

    /* Ya que la conexión sigue viva, ejecutemos otra consulta */
    $resultado2 = mysql_query($sql2);
    ?>

### Ver también

- mysql_thread_id() - Devuelve el ID del hilo actual
- mysql_list_processes() - Lista los procesos de MySQL

# mysql_query

(PHP 4, PHP 5)

mysql_query — Enviar una consulta MySQL

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_query()
- PDO::query()

### Descripción

function mysql_query(string `$query`, resource `$link_identifier` = NULL): mixed

mysql_query() envía una única consulta (no hay soporte para múltiples consultas) a la base de datos actualmente activa en el servidor asociado con el identificador de enlace especificado por `link_identifier`.

### Parámetros

`query`
  Una consulta SQL El string de la consulta no debería terminar con un punto y coma. Los datos insertados en la consulta deberían estar correctamente escapados.
`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Para SELECT, SHOW, DESCRIBE, EXPLAIN y otras sentencias que retornan un conjunto de resultados, mysql_query() devuelve un resource en caso de éxito, o `false` en caso de error.

Para otros tipos de sentencias SQL, tales como INSERT, UPDATE, DELETE, DROP, etc, mysql_query() devuelve `true` en caso de éxito o `false` en caso de error.

El conjunto de resultados devuelto debería ser pasado a mysql_fetch_array(), y otras funciones para manejar las tablas del resultado, para acceder a los datos retornados.

Use mysql_num_rows() para averiguar cuántas filas fueron devueltas por la sentencia SELECT, o mysql_affected_rows() para averiguar cuántas filas fueron afectadas por las sentencias DELETE, INSERT, REPLACE, o UPDATE.

mysql_query() también fallará y retornará `false` si el usuario no está autorizado para acceder a la/s tabla/s a la/s que hace referencia la consulta.

### Ejemplos

Ejemplo #1 Consulta inválida

La siguiente consulta no es sintácticamente válida, por lo que mysql_query() fallará y retornará `false`.

    <?php
    $resultado = mysql_query('SELECT * WHERE 1=1');
    if (!$resultado) {
        die('Consulta no válida: ' . mysql_error());
    }

    ?>

Ejemplo #2 Consulta válida

La siguiente consulta es válida, por lo que mysql_query() retornará un resource.

    <?php
    // Lo siguiente podría ser proporcionado por un usuario, como por ejemplo
    $nombre = 'fred';
    $apellido  = 'fox';

    // Formular la consulta
    // Este es el mejor método para formular una consulta SQL
    // Para más ejemplos, consulte mysql_real_escape_string()
    $consulta = sprintf("SELECT nombre, apellido, direccion, edad FROM amigos
        WHERE nombre='%s' AND apellido='%s'",
        mysql_real_escape_string($nombre),
        mysql_real_escape_string($apellido));

    // Ejecutar la consulta
    $resultado = mysql_query($consulta);

    // Comprobar el resultado
    // Lo siguiente muestra la consulta real enviada a MySQL, y el error ocurrido. Útil para depuración.
    if (!$resultado) {
        $mensaje  = 'Consulta no válida: ' . mysql_error() . "\n";
        $mensaje .= 'Consulta completa: ' . $consulta;
        die($mensaje);
    }

    // Usar el resultado
    // Si se intenta imprimir $resultado no será posible acceder a la información del recurso
    // Se debe usar una de las funciones de resultados de mysql
    // Consulte también mysql_result(), mysql_fetch_array(), mysql_fetch_row(), etc.
    while ($fila = mysql_fetch_assoc($resultado)) {
        echo $fila['nombre'];
        echo $fila['apellido'];
        echo $fila['direccion'];
        echo $fila['edad'];
    }

    // Liberar los recursos asociados con el conjunto de resultados
    // Esto se ejecutado automáticamente al finalizar el script.
    mysql_free_result($resultado);
    ?>

### Ver también

- mysql_connect() - Abre una conexión al servidor MySQL
- mysql_error() - Devuelve el texto del mensaje de error de la operación MySQL anterior
- mysql_real_escape_string() - Escapa caracteres especiales en una cadena para su uso en una sentencia SQL
- mysql_result() - Obtener datos de resultado
- mysql_fetch_assoc() - Recupera una fila de resultados como un array asociativo
- mysql_unbuffered_query() - Envía una consulta SQL a MySQL, sin recuperar ni almacenar en búfer las filas de resultados

# mysql_real_escape_string

(PHP 4 >= 4.3.0, PHP 5)

mysql_real_escape_string — Escapa caracteres especiales en una cadena para su uso en una sentencia SQL

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_real_escape_string()
- PDO::quote()

### Descripción

function mysql_real_escape_string(string `$unescaped_string`, resource `$link_identifier` = NULL): string

Escapa caracteres especiales en la cadena dada por `unescaped_string`, teniendo en cuenta el conjunto de caracteres en uso de la conexión, para que sea seguro usarla en mysql_query(). Si se van a insertar datos binarios, se ha de usar esta función.

mysql_real_escape_string() llama a la función mysql_real_escape_string de la biblioteca de MySQL, la cual antepone barras invertidas a los siguientes caracteres: `\x00`, `\n`, `\r`, `\`, `'`, `"` y `\x1a`.

Esta función siempre debe usarse (con pocas excepciones) para hacer seguros los datos antes de enviar una consulta a MySQL.

Precaución

# Seguridad: el conjunto de caracters predeterminado

El conjunto de caracteres debe ser establecido o bien a nivel del servidor, o bien con la función mysql_set_charset() de la API para que afecte a mysql_real_escape_string(). Véase la sección sobre los conceptos de conjuntos de caracters para más información.

### Parámetros

`unescaped_string`
  La cadena a escapar.
`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Devuelve la cadena escapada, o `false` en caso de error.

### Errores/Excepciones

Ejecutar esta función sin una conexión de MySQL presente también emitirá errores de nivel `E_WARNING` de PHP. Solo se ha de ejecutar con una conexión de MySQL válida presente.

### Ejemplos

Ejemplo #1 Ejemplo sencillo de mysql_real_escape_string()

    <?php
    // Conexión
    $enlace = mysql_connect('anfitrión_mysql', 'usuario_mysql', 'contraseña_mysql')
        OR die(mysql_error());

    // Consulta
    $consulta = sprintf("SELECT * FROM users WHERE user='%s' AND password='%s'",
                mysql_real_escape_string($usuario),
                mysql_real_escape_string($contraseña));
    ?>

Ejemplo #2 mysql_real_escape_string() requiere una conexión

Este ejemplo muestra lo que sucede si no hay presente una conexión de MySQL al invocar a esta función.

    <?php
    // No nos hemos conectado a MySQL

    $apellido  = "O'Reilly";
    $_apellido = mysql_real_escape_string($apellido);

    $consulta = "SELECT * FROM actors WHERE last_name = '$_apellido'";

    var_dump($_apellido);
    var_dump($consulta);
    ?>

Resultado del ejemplo anterior es similar a:

    Warning: mysql_real_escape_string(): No such file or directory in /this/test/script.php on line 5
    Warning: mysql_real_escape_string(): A link to the server could not be established in /this/test/script.php on line 5

    bool(false)
    string(41) "SELECT * FROM actors WHERE last_name = ''"

Ejemplo #3 Un ejemplo de ataque de inyección de SQL

    <?php
    // No hemos comprobado $_POST['password'], ¡podría ser cualquier cosa que el usuario quisiera! Por ejemplo:
    $_POST['username'] = 'aidan';
    $_POST['password'] = "' OR ''='";

    // Consultar la base de datos para comprobar si existe algún usuario que coincida
    $consulta = "SELECT * FROM users WHERE user='{$_POST['username']}' AND password='{$_POST['password']}'";
    mysql_query($consulta);

    // Esto significa que la consulta enviada a MySQL sería:
    echo $consulta;
    ?>

La consulta enviada a MySQL:

    SELECT * FROM users WHERE user='aidan' AND password='' OR ''=''

Esto permitiría a alguien acceder a una sesión sin una contraseña válida.

### Notas

> Nota: Se requiere una conexión a MySQL antes de usar mysql_real_escape_string(), si no, se generará un error de nivel `E_WARNING`, y se devolverá `false`. Si `link_identifier` no está definido, se usará la última conexión a MySQL.

> Nota: Si esta función no se utiliza para escapar los datos, la consulta es vulnerable a Ataques de inyección SQL.

> Nota: mysql_real_escape_string() no escapa `%` ni `_`. Estos son comodines en MySQL si se combinan con `LIKE`, `GRANT`, o `REVOKE`.

### Ver también

- mysql_set_charset() - Establece el conjunto de caracteres del cliente
- mysql_client_encoding() - Devuelve el nombre del conjunto de caracteres

# mysql_result

(PHP 4, PHP 5)

mysql_result — Obtener datos de resultado

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_data_seek() junto con mysqli_field_seek() y mysqli_fetch_field()
- PDOStatement::fetchColumn()

### Descripción

function mysql_result(resource `$result`, int `$row`, mixed `$field` = 0): string

Recupera el contenido de una celda de un conjunto de resultados de MySQL.

Cuando se esté trabajando con conjuntos de resultados grandes, se debería considerar usar una de las funciones que obtienen una fila completa (especificadas más abajo). Debido a que estas funciones retornan el contenido de múltiples celdas en una única llamada a función, son MUCHO MÁS rápidas que mysql_result(). Además, se ha de tener en cuenta que la especificación de un índice numérico para el campo pasado como argumento es mucho más rápido que especificar un nombre de campo o el argumento nombre_tabla.nombre_campo.

### Parámetros

`result`
  La resource de resultado que acaba de ser evaluada. Este resultado proviene de la llamada a la función mysql_query().
`row`
  El número de fila del conjunto de resultados que está siendo recuperado. El número de filas empieza a partir de `0`.
`field`
  El nombre o el índice del campo que está siendo recuperado. Puede ser el índice del campo, el nombre del campo, o el nombre de la tabla punto nombre del campo (nombre_tabla.nombre_campo). Si se ha utilizado un alias para el nombre de la columna ('select foo as bar from...'), utilice el alias en lugar del nombre del campo. Si no está definido, se recuperará el primer campo.

### Valores devueltos

El contenido de una celda de un conjunto de resultados de MySQL en caso de éxito, o `false` en caso de fallo.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_result()

    <?php
    $enlace = mysql_connect('anfitrión_mysql', 'usuario_mysql', 'contraseña_mysql');
    if (!$enlace) {
        die('No se pudo conectar: ' . mysql_error());
    }
    if (!mysql_select_db('nombre_base_datos')) {
        die('No se pudo seleccionar la base de datos: ' . mysql_error());
    }
    $resultado = mysql_query('SELECT name FROM work.employee');
    if (!$resultado) {
        die('No se pudo consultar:' . mysql_error());
    }
    echo mysql_result($resultado, 2); // imprime el nombre del tercer empleado

    mysql_close($enlace);
    ?>

### Notas

> Nota: Las llamadas a mysql_result() no deberían ser mezcladas con llamadas a otras funciones que manejen conjuntos de resultados.

### Ver también

- mysql_fetch_row() - Obtiene una fila de resultados como un array numérico
- mysql_fetch_array() - Recupera una fila de resultados como un array asociativo, un array numérico o como ambos
- mysql_fetch_assoc() - Recupera una fila de resultados como un array asociativo
- mysql_fetch_object() - Recupera una fila de resultados como un objeto

# mysql_select_db

(PHP 4, PHP 5)

mysql_select_db — Seleccionar una base de datos MySQL

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_select_db()
- PDO::__construct() (parte de dsn)

### Descripción

function mysql_select_db(string `$database_name`, resource `$link_identifier` = NULL): bool

Establece la base de datos activa actual en el servidor asociado con el identificador de enlace especificado. Cada llamada posterior a mysql_query() será ejecutada en la base de datos activa.

### Parámetros

`database_name`
  El nombre de la base de datos que va a ser seleccionada.
`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo mysql_select_db()

    <?php

    $enlace = mysql_connect('localhost', 'usuario_mysql', 'contraseña_myql');
    if (!$enlace) {
        die('No se pudo conectar : ' . mysql_error());
    }

    // Hacer que foo sea la base de datos actual
    $bd_seleccionada = mysql_select_db('foo', $enlace);
    if (!$bd_seleccionada) {
        die ('No se puede usar foo : ' . mysql_error());
    }
    ?>

### Notas

> Nota: Por razones de compatibilidad ascendente, el siguiente alias obsoleto puede ser utilizado: mysql_selectdb()

### Ver también

- mysql_connect() - Abre una conexión al servidor MySQL
- mysql_pconnect() - Abre una conexión persistente a un servidor MySQL
- mysql_query() - Enviar una consulta MySQL

# mysql_set_charset

(PHP 5 >= 5.2.3)

mysql_set_charset — Establece el conjunto de caracteres del cliente

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_set_charset()
- PDO: Añadir `charset` al string de conexión, tal como `charset=utf8`

### Descripción

function mysql_set_charset(string `$charset`, resource `$link_identifier` = NULL): bool

Establece el conjunto de caracteres predeterminado para la conexión actual.

### Parámetros

`charset`
  Un nombre válido de un conjunto de caracteres.
`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Notas

> Nota: Esta función requiere MySQL 5.0.7 o posterior.

> Nota: Esta es la mejor forma de cambiar el conjunto de caracteres. El uso de mysql_query() para establecerlo (como `SET NAMES utf8`) no es recomendable. Véase la sección conceptos de conjuntos de caracteres de MySQL para más información.

### Ver también

- Establecer conjuntos de caracteres en MySQL
- » Listado de los conjuntos de caracteres admitidos por MySQL
- mysql_client_encoding() - Devuelve el nombre del conjunto de caracteres

# mysql_stat

(PHP 4 >= 4.3.0, PHP 5)

mysql_stat — Obtiene el estado actual del sistema

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_stat()
- PDO::getAttribute() con `attribute` como `PDO::ATTR_SERVER_INFO`

### Descripción

function mysql_stat(resource `$link_identifier` = NULL): string

mysql_stat() devuelve el estado actual del servidor.

### Parámetros

`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Devuelve un string con el estado del tiempo de funcionamiento, hilos, consultas, tablas abiertas, tablas de volcado y consultas por segundo. Para obtener una lista completa de variables de estado, es necesario usar el comando SQL `SHOW STATUS`. Si `link_identifier` no es válido, se devuelve `null`.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_stat()

    <?php
    $enlace = mysql_connect('localhost', 'usuario_mysql', 'contraseña_mysql');
    $estado = explode('  ', mysql_stat($enlace));
    print_r($estado);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Uptime: 5380
        [1] => Threads: 2
        [2] => Questions: 1321299
        [3] => Slow queries: 0
        [4] => Opens: 26
        [5] => Flush tables: 1
        [6] => Open tables: 17
        [7] => Queries per second avg: 245.595
    )

Ejemplo #2 Ejemplo alternativo de mysql_stat()

    <?php
    $enlace    = mysql_connect('localhost', 'usuario_mysql', 'contraseña_mysql');
    $resultado = mysql_query('SHOW STATUS', $enlace);
    while ($fila = mysql_fetch_assoc($resultado)) {
        echo $fila['Nombre_variable'] . ' = ' . $fila['Valor'] . "\n";
    }
    ?>

Resultado del ejemplo anterior es similar a:

    back_log = 50
    basedir = /usr/local/
    bdb_cache_size = 8388600
    bdb_log_buffer_size = 32768
    bdb_home = /var/db/mysql/
    bdb_max_lock = 10000
    bdb_logdir =
    bdb_shared_data = OFF
    bdb_tmpdir = /var/tmp/
    ...

### Ver también

- mysql_get_server_info() - Obtiene información del servidor MySQL
- mysql_list_processes() - Lista los procesos de MySQL

# mysql_tablename

(PHP 4, PHP 5)

mysql_tablename — Obtiene el nombre de la tabla de un campo

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- Consulta SQL: `SHOW TABLES`

### Descripción

function mysql_tablename(resource `$result`, int `$i`): string|false

Recupera el nombre de tabla desde un resultado dado por `result`.

Esta función está obsoleta. Es preferible usar mysql_query() para ejecutar una consulta SQL `SHOW TABLES [FROM nombre_bd] [LIKE 'patrón']` en su lugar.

### Parámetros

`result`
  Un resource de puntero de resultados que se devuelve desde mysql_list_tables().
`i`
  El índice de tipo integer (número de fila/tabla)

### Valores devueltos

El nombre de la tabla en caso de éxito o `false` si ocurre un error.

Use la función mysql_tablename() para atravesar este puntero de resultados, o cualquier función para obtener tablas, tal como mysql_fetch_array().

### Ejemplos

Ejemplo #1 Ejemplo de mysql_tablename()

    <?php
    mysql_connect("localhost", "usuario_mysql", "contraseña_mysql");
    $resultado = mysql_list_tables("mibd");
    $número_filas = mysql_num_rows($resultado);
    for ($i = 0; $i < $número_filas; $i++) {
        echo "Tabla: ", mysql_tablename($resultado, $i), "\n";
    }

    mysql_free_result($resultado);
    ?>

### Notas

> Nota: La función mysql_num_rows() puede ser usada para determinar el número de tablas del puntero de resultados.

### Ver también

- mysql_list_tables() - Lista las tablas de una base de datos MySQL
- mysql_field_table() - Obtiene el nombre de la tabla en la que está el campo especificado
- mysql_db_name() - Recupera el nombre de la base de datos desde una llamada a mysql_list_dbs

# mysql_thread_id

(PHP 4 >= 4.3.0, PHP 5)

mysql_thread_id — Devuelve el ID del hilo actual

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- mysqli_thread_id()

### Descripción

function mysql_thread_id(resource `$link_identifier` = NULL): int|false

Recupera el ID del hilo actual. Si la conexión se ha perdido, y se ejecuta una reconexión con mysql_ping(), el ID del hilo cambiará. Esto quiere decir que sólo se ha de recuperar el ID del hilo cuando sea necesario.

### Parámetros

`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

El ID del hilo en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de mysql_thread_id()

    <?php
    $enlace = mysql_connect('localhost', 'usuario_mysql', 'contraseña_mysql');
    $id_hilo = mysql_thread_id($enlace);
    if ($id_hilo){
        printf("El ID del hilo actual es %d\n", $id_hilo);
    }
    ?>

Resultado del ejemplo anterior es similar a:

    El ID del hilo actual es 73

### Ver también

- mysql_ping() - Efectuar un chequeo de respuesta (ping) sobre una conexión al servidor o reconectarse si no hay conexión
- mysql_list_processes() - Lista los procesos de MySQL

# mysql_unbuffered_query

(PHP 4 >= 4.0.6, PHP 5)

mysql_unbuffered_query — Envía una consulta SQL a MySQL, sin recuperar ni almacenar en búfer las filas de resultados

Advertencia

Esta extensión estaba obsoleta en PHP 5.5.0, y fue eliminada en PHP 7.0.0. En su lugar, se puede utilizar la extensión MySQLi o la extensión PDO_MySQL. Ver también MySQL: elegir una API de la guía. Alternativas a esta función:

- Véase: Consultas almacenadas y no almacenadas en buffer

### Descripción

function mysql_unbuffered_query(string `$query`, resource `$link_identifier` = NULL): resource

mysql_unbuffered_query() envía la consulta SQL `query` a MySQL, sin recuperar ni almacenar automáticamente en búfer las filas de resultados, como mysql_query() lo hace. Esto ahorra una considerable cantidad de memoria con las consultas SQL que producen conjuntos de resultados grandes, y se puede empezar a trabajar con el conjunto de resultados inmediatamente después de que la primera fila haya sido recuperada, ya que no es necesario esperar hasta que la consulta SQL completa haya sido ejecutada. Para usar mysql_unbuffered_query() mientras están abiertas múltiples conexiones a la base de datos, se debe especificar el parámetro opcional `link_identifier` para identificar qué conexión se desea utilizar.

### Parámetros

`query`
  La consulta SQL a ejecutar. Los datos dentro de la consulta deben estar propiamente escapados.
`link_identifier`
  La conexión MySQL. Si no se especifica, se utilizará la última conexión abierta con la función mysql_connect(). Si no se encuentra una conexión de este tipo, la función intentará abrir una conexión, como si la función mysql_connect() hubiera sido llamada sin argumento. Si no se encuentra o establece una conexión, se generará una alerta de nivel `E_WARNING`.

### Valores devueltos

Para sentencias SELECT, SHOW, DESCRIBE o EXPLAIN, mysql_unbuffered_query() devuelve un resource en caso de éxito, o `false` en caso de error.

Para otro tipo de sentencias SQL, UPDATE, DELETE, DROP, etc, mysql_unbuffered_query() devuelve `true` en caso de éxito o `false` en caso de error.

### Notas

> Nota: Los beneficios de mysql_unbuffered_query() tienen un precio: no se puede usar mysql_num_rows() ni mysql_data_seek() en un conjunto de resultados devuelto por mysql_unbuffered_query(), hasta que todas las filas sean recuperadas. También se tendrán que recuperar todas las filas de resultados de una consulta SQL no almacenada en búfer antes de poder enviar una nueva consulta SQL a MySQL, usando el mismo `link_identifier`.

### Ver también

- mysql_query() - Enviar una consulta MySQL

## Tabla de contenidos

- mysql_affected_rows — Obtiene el número de filas afectadas en la anterior operación de MySQL
- mysql_client_encoding — Devuelve el nombre del conjunto de caracteres
- mysql_close — Cerrar una conexión de MySQL
- mysql_connect — Abre una conexión al servidor MySQL
- mysql_create_db — Crea una base de datos MySQL
- mysql_data_seek — Mueve el puntero de resultados interno
- mysql_db_name — Recupera el nombre de la base de datos desde una llamada a mysql_list_dbs
- mysql_db_query — Selecciona una base de datos y ejecuta una consulta sobre la misma
- mysql_drop_db — Elimina (DROP) una base de datos MySQL
- mysql_errno — Devuelve el valor numérico del mensaje de error de la última operación MySQL
- mysql_error — Devuelve el texto del mensaje de error de la operación MySQL anterior
- mysql_escape_string — Escapa una cadena para ser usada en mysql_query
- mysql_fetch_array — Recupera una fila de resultados como un array asociativo, un array numérico o como ambos
- mysql_fetch_assoc — Recupera una fila de resultados como un array asociativo
- mysql_fetch_field — Obtiene la información de una columna de un resultado y la devuelve como un objeto
- mysql_fetch_lengths — Obtiene la longitud de cada salida en un resultado
- mysql_fetch_object — Recupera una fila de resultados como un objeto
- mysql_fetch_row — Obtiene una fila de resultados como un array numérico
- mysql_field_flags — Obtiene las banderas asociadas al campo especificado de un resultado
- mysql_field_len — Devuelve la longitud del campo especificado
- mysql_field_name — Obtiene el nombre del campo especificado de un resultado
- mysql_field_seek — Establece el puntero del resultado en un índice de campo específicado
- mysql_field_table — Obtiene el nombre de la tabla en la que está el campo especificado
- mysql_field_type — Obtiene el tipo del campo especificado de un resultado
- mysql_free_result — Libera la memoria del resultado
- mysql_get_client_info — Obtiene información del cliente MySQL
- mysql_get_host_info — Obtener información del anfitrión de MySQL
- mysql_get_proto_info — Obtener información del protocolo MySQL
- mysql_get_server_info — Obtiene información del servidor MySQL
- mysql_info — Obtiene información sobre la consulta más reciente
- mysql_insert_id — Obtiene el ID generado en la última consulta
- mysql_list_dbs — Lista las bases de datos disponibles en un servidor MySQL
- mysql_list_fields — Lista los campos de una tabla de MySQL
- mysql_list_processes — Lista los procesos de MySQL
- mysql_list_tables — Lista las tablas de una base de datos MySQL
- mysql_num_fields — Obtiene el número de campos de un resultado
- mysql_num_rows — Obtener el número de filas de un conjunto de resultados
- mysql_pconnect — Abre una conexión persistente a un servidor MySQL
- mysql_ping — Efectuar un chequeo de respuesta (ping) sobre una conexión al servidor o reconectarse si no hay conexión
- mysql_query — Enviar una consulta MySQL
- mysql_real_escape_string — Escapa caracteres especiales en una cadena para su uso en una sentencia SQL
- mysql_result — Obtener datos de resultado
- mysql_select_db — Seleccionar una base de datos MySQL
- mysql_set_charset — Establece el conjunto de caracteres del cliente
- mysql_stat — Obtiene el estado actual del sistema
- mysql_tablename — Obtiene el nombre de la tabla de un campo
- mysql_thread_id — Devuelve el ID del hilo actual
- mysql_unbuffered_query — Envía una consulta SQL a MySQL, sin recuperar ni almacenar en búfer las filas de resultados

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
  - Tipos de recursos
- Registro de cambios
- Constantes predefinidas
- Ejemplos
  - Ejemplo con la extensión MySQL
- Funciones MySQL
  - mysql_affected_rows — Obtiene el número de filas afectadas en la anterior operación de MySQL
  - mysql_client_encoding — Devuelve el nombre del conjunto de caracteres
  - mysql_close — Cerrar una conexión de MySQL
  - mysql_connect — Abre una conexión al servidor MySQL
  - mysql_create_db — Crea una base de datos MySQL
  - mysql_data_seek — Mueve el puntero de resultados interno
  - mysql_db_name — Recupera el nombre de la base de datos desde una llamada a mysql_list_dbs
  - mysql_db_query — Selecciona una base de datos y ejecuta una consulta sobre la misma
  - mysql_drop_db — Elimina (DROP) una base de datos MySQL
  - mysql_errno — Devuelve el valor numérico del mensaje de error de la última operación MySQL
  - mysql_error — Devuelve el texto del mensaje de error de la operación MySQL anterior
  - mysql_escape_string — Escapa una cadena para ser usada en mysql_query
  - mysql_fetch_array — Recupera una fila de resultados como un array asociativo, un array numérico o como ambos
  - mysql_fetch_assoc — Recupera una fila de resultados como un array asociativo
  - mysql_fetch_field — Obtiene la información de una columna de un resultado y la devuelve como un objeto
  - mysql_fetch_lengths — Obtiene la longitud de cada salida en un resultado
  - mysql_fetch_object — Recupera una fila de resultados como un objeto
  - mysql_fetch_row — Obtiene una fila de resultados como un array numérico
  - mysql_field_flags — Obtiene las banderas asociadas al campo especificado de un resultado
  - mysql_field_len — Devuelve la longitud del campo especificado
  - mysql_field_name — Obtiene el nombre del campo especificado de un resultado
  - mysql_field_seek — Establece el puntero del resultado en un índice de campo específicado
  - mysql_field_table — Obtiene el nombre de la tabla en la que está el campo especificado
  - mysql_field_type — Obtiene el tipo del campo especificado de un resultado
  - mysql_free_result — Libera la memoria del resultado
  - mysql_get_client_info — Obtiene información del cliente MySQL
  - mysql_get_host_info — Obtener información del anfitrión de MySQL
  - mysql_get_proto_info — Obtener información del protocolo MySQL
  - mysql_get_server_info — Obtiene información del servidor MySQL
  - mysql_info — Obtiene información sobre la consulta más reciente
  - mysql_insert_id — Obtiene el ID generado en la última consulta
  - mysql_list_dbs — Lista las bases de datos disponibles en un servidor MySQL
  - mysql_list_fields — Lista los campos de una tabla de MySQL
  - mysql_list_processes — Lista los procesos de MySQL
  - mysql_list_tables — Lista las tablas de una base de datos MySQL
  - mysql_num_fields — Obtiene el número de campos de un resultado
  - mysql_num_rows — Obtener el número de filas de un conjunto de resultados
  - mysql_pconnect — Abre una conexión persistente a un servidor MySQL
  - mysql_ping — Efectuar un chequeo de respuesta (ping) sobre una conexión al servidor o reconectarse si no hay conexión
  - mysql_query — Enviar una consulta MySQL
  - mysql_real_escape_string — Escapa caracteres especiales en una cadena para su uso en una sentencia SQL
  - mysql_result — Obtener datos de resultado
  - mysql_select_db — Seleccionar una base de datos MySQL
  - mysql_set_charset — Establece el conjunto de caracteres del cliente
  - mysql_stat — Obtiene el estado actual del sistema
  - mysql_tablename — Obtiene el nombre de la tabla de un campo
  - mysql_thread_id — Devuelve el ID del hilo actual
  - mysql_unbuffered_query — Envía una consulta SQL a MySQL, sin recuperar ni almacenar en búfer las filas de resultados

# Controlador Nativo de MySQL

# Introducción

El Controlador Nativo de MySQL (MySQL Native Driver en inglés) es un sustituto para la Biblioteca Cliente de MySQL (libmysqlclient). El Controlador Nativo de MySQL es parte de las fuentes oficiales de PHP a partir de PHP 5.3.0.

Las extensiones de base de datos de MySQL (la extensión MySQL, `mysqli` y PDO MYSQL), se comunican con el servidor de MySQL. En el pasado, esto lo realizaba la extensión utilizando los servicios prestados por la Biblioteca Cliente de MySQL. Las extensiones eran compiladas con la Biblioteca Cliente de MySQL con el fin de utilizar su protocolo cliente-servidor.

Ahora existe una alternativa con el Controlador Nativo de MySQL, ya que las extensiones de bases de datos MySQL puede ser compiladas para utilizar el Controlador Nativo de MySQL en lugar de la Biblioteca Cliente de MySQL.

El Controlador Nativo de MySQL está escrito en C, como una extensión de PHP.

# Introducción

Lo que no es

Aunque el driver nativo de MySQL está escrito como una extensión PHP, es importante señalar que no proporciona una nueva API al programador PHP. Las API para programadores son proporcionadas por la extensión MySQL, `mysqli` y PDO MySQL. Estas extensiones pueden ahora utilizar los servicios del driver nativo MySQL para comunicarse con el servidor MySQL. Por lo tanto, el driver nativo MySQL no debe ser considerado como una API.

¿Por qué utilizarlo?

Utilizar el driver nativo de MySQL ofrece numerosas ventajas en comparación con la biblioteca cliente de MySQL.

La antigua biblioteca cliente de MySQL fue escrita por MySQL AB (ahora parte de Oracle Corporation) y, por lo tanto, fue publicada bajo la licencia MySQL, lo que tuvo como consecuencia la desactivación del soporte de MySQL por defecto en PHP. Dado que el driver nativo de MySQL fue desarrollado como parte integral del proyecto PHP, se publica bajo la licencia PHP, lo que resuelve los problemas de licencia que existían en el pasado.

Además, anteriormente, era necesario compilar las extensiones de base de datos MySQL en relación con una copia de la biblioteca cliente de MySQL, lo que significaba que se debía tener instalado MySQL en la máquina donde se compilaba PHP a partir de los fuentes. Por lo tanto, cuando se ejecutaba la aplicación PHP, las extensiones MySQL llamaban a los archivos de la biblioteca cliente de MySQL al inicio, los cuales debían estar obligatoriamente instalados en el sistema. Con el driver nativo de MySQL, esto ya no es necesario ya que está incluido en la distribución estándar. Por lo tanto, ya no será necesario tener instalado MySQL para compilar PHP o ejecutar aplicaciones PHP que hagan uso de una base de datos.

Dado que el driver nativo de MySQL está escrito como una extensión PHP, está íntimamente ligado al núcleo de PHP. Esto implica una mejor eficiencia, especialmente en lo que respecta al uso de la memoria, ya que el driver utiliza la asignación de memoria de PHP y, por lo tanto, soporta los límites de memoria. Utilizar el driver nativo de MySQL resulta en un rendimiento igual o mejor que con la biblioteca cliente de MySQL, ya que el uso de la memoria es mucho más eficiente. El hecho de que, al utilizar la biblioteca cliente de MySQL, cada registro se almacene dos veces en memoria, mientras que el cliente nativo de MySQL solo lo almacena una vez, es un buen ejemplo de una buena gestión de la memoria.

> Nota: Supervisión del uso de memoria
> Debido a que el driver nativo de MySQL utiliza el sistema de gestión de memoria de PHP, su uso de memoria puede ser supervisado con la función memory_get_usage(). Esto no es posible con la biblioteca libmysqlclient ya que utiliza la función C malloc() en su lugar.

Funcionalidades especiales

El driver nativo de MySQL también proporciona algunas funcionalidades especiales no disponibles con la biblioteca cliente de MySQL, listadas a continuación:

- Conexiones persistentes mejoradas
- La función especial mysqli_fetch_all()
- Llamadas a las estadísticas de rendimiento: mysqli_get_client_stats(), mysqli_get_connection_stats()

Las estadísticas de rendimiento pueden ser muy útiles para identificar cuellos de botella de rendimiento.

El driver nativo de MySQL también proporciona conexiones persistentes al utilizarlo con la extensión `mysqli`.

Soporte de SSL

El driver nativo de MySQL (MySQL Native Driver) soporta SSL.

Soporte del protocolo comprimido

El driver nativo de MySQL soporta el protocolo cliente/servidor MySQL comprimido. La extensión `ext/mysqli`, si está configurada para utilizar el driver nativo de MySQL, también puede beneficiarse de esta funcionalidad. Es importante señalar que `PDO_MYSQL` no soporta EN ABSOLUTO la compresión cuando se utiliza con mysqlnd.

Soporte de pipes nombrados

Los pipes nombrados pueden ser utilizados para conectarse bajo Windows.

# Instalación

Instalación bajo Unix

Para utilizar el controlador nativo MySQL, PHP debe ser compilado especificando explícitamente que las extensiones de base de datos MySQL deben ser compiladas en relación con él. Esto se realiza mediante las opciones de configuración anteriores a la compilación de PHP en sí.

Por ejemplo, para compilar la extensión MySQL, `mysqli` y PDO MySQL utilizando el controlador nativo MySQL, la siguiente orden debe ser ejecutada:

    ./configure --with-mysql=mysqlnd \
    --with-mysqli=mysqlnd \
    --with-pdo-mysql=mysqlnd \
    [otras opciones]

Instalación bajo Windows

En las distribuciones oficiales de PHP para Windows, el controlador nativo MySQL está activado por defecto y no se requiere configuración adicional para su uso. Todas las extensiones de base de datos MySQL lo utilizarán entonces.

Soporte del plugin de autenticación SHA-256

El driver nativo MySQL requiere la carga de la funcionalidad OpenSSL de PHP, y la activación de la conexión a MySQL mediante cuentas que utilizan el plugin de autenticación MySQL SHA-256. Por ejemplo, PHP podría ser configurado utilizando la siguiente orden:

    ./configure --with-mysql=mysqlnd \
    --with-mysqli=mysqlnd \
    --with-pdo-mysql=mysqlnd \
    --with-openssl
    [otras opciones]

En Autotools, el soporte SSL extendido en `mysqlnd` es activado implícitamente durante la compilación con la extensión `openssl` utilizando la opción de configuración --with-openssl. Durante la compilación sin la extensión `openssl`, la opción de configuración --with-mysqlnd-ssl puede ser utilizada para activar explícitamente el soporte SSL extendido.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | La opción de configuración Autotools --with-mysqlnd-ssl fue añadida para activar explícitamente el soporte SSL extendido durante la compilación sin la extensión `openssl`.

# Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración de MySQL Native Driver
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
mysqlnd.collect_statistics | "1" | `INI_SYSTEM` |
mysqlnd.collect_memory_statistics | "0" | `INI_SYSTEM` |
mysqlnd.debug | "" | `INI_SYSTEM` |
mysqlnd.log_mask | 0 | `INI_ALL` |
mysqlnd.mempool_default_size | 16000 | `INI_ALL` |
mysqlnd.net_read_timeout | "86400" | `INI_ALL` | Antes de PHP 7.2.0 el valor por omisión era "31536000" y la variabilidad era `INI_SYSTEM`
mysqlnd.net_cmd_buffer_size | "4096" | `INI_SYSTEM` |
mysqlnd.net_read_buffer_size | "32768" | `INI_SYSTEM` |
mysqlnd.sha256_server_public_key | "" | `INI_PERDIR` |
mysqlnd.trace_alloc | "" | `INI_SYSTEM` |
mysqlnd.fetch_data_copy | 0 | `INI_ALL` | Eliminado a partir de PHP 8.1.0

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`mysqlnd.collect_statistics` bool
  Activa la recolección de diferentes estadísticas del cliente a las cuales se puede acceder mediante mysqli_get_client_stats(), mysqli_get_connection_stats(), y que también se describen en la sección `mysqlnd` de la salida de la función phpinfo(). Este parámetro activa todas las estadísticas de MySQL Native Driver excepto las relativas a la gestión de la memoria.
`mysqlnd.collect_memory_statistics` bool
  Activa la recolección de diferentes estadísticas concernientes a la memoria que pueden ser consultadas mediante mysqli_get_client_stats(), mysqli_get_connection_stats(), y que también se muestran en la sección `mysqlnd` de la salida de la función phpinfo(). Este parámetro activa las estadísticas de gestión de la memoria entre las estadísticas proporcionadas por MySQL Native Driver.
`mysqlnd.debug` string
  Registra las comunicaciones provenientes de cualquier extensión que utilice `mysqlnd`. El formato de esta directiva es `mysqlnd.debug = "option1[,parameter_option1][:option2[,parameter_option2]]"`. Las opciones de formato de strings son las siguientes:
  - A[,file] - Añade la traza a un fichero. Asegura que los datos son escritos después de cada escritura cerrando y volviendo a abrir el fichero de traza (lento). Esto ayuda a asegurar que el fichero de trazas será completo incluso si la aplicación falla.
  - a[,file] - Añade la traza a un fichero.
  - d - Activa la salida desde las macros DBUG_<N> para el estado actual. Puede ser seguido de una lista de palabras clave que seleccionan la salida solo para las macros DBUG con esa palabra clave (filtro). Una lista vacía de palabras clave seleccionará todo.
  - f[,functions] - Limita las acciones del depurador a una lista específica de funciones. Una lista vacía hará que todas las funciones sean utilizadas.
  - F - Marca cada línea de depuración con el nombre del fichero fuente que contiene la macro que causa esta salida.
  - i - Marca cada línea de depuración con el PID.
  - L - Marca cada línea de depuración con el nombre del fichero fuente así como la línea de la macro que causa esta salida.
  - n - Marca cada línea de depuración con la profundidad actual de la función.
  - o[,file] - Similar a a[,file] pero sobrescribe los ficheros en lugar de complementarlos.
  - O[,file] - Similar a A[,file] pero sobrescribe los ficheros en lugar de complementarlos.
  - t[,N] - Activa el trazado del flujo de control de las funciones. La profundidad máxima se especifica mediante N, por omisión 200.
  - x - Activa el perfilado.
  - m - Trazar las asignaciones y desasignaciones de memoria.
  Ejemplo:

      d:t:x:O,/tmp/mysqlnd.trace

  > Nota: Esta característica solo está disponible para las versiones de depuración de PHP.

`mysqlnd.log_mask` int
  Define qué consulta será historizada. Por omisión, vale 0, lo que significa que los logs están desactivados. Conviene definir esta opción utilizando un entero, y no una constante PHP. Por ejemplo, un valor de 48 (16 + 32) historizará las consultas lentas que utilicen 'no good index' (SERVER_QUERY_NO_GOOD_INDEX_USED = 16) o ningún índice en absoluto (SERVER_QUERY_NO_INDEX_USED = 32). Un valor de 2043 (1 + 2 + 8 + ... + 1024) historizará todo tipo de consultas lentas. Los tipos son los siguientes: SERVER_STATUS_IN_TRANS=1, SERVER_STATUS_AUTOCOMMIT=2, SERVER_MORE_RESULTS_EXISTS=8, SERVER_QUERY_NO_GOOD_INDEX_USED=16, SERVER_QUERY_NO_INDEX_USED=32, SERVER_STATUS_CURSOR_EXISTS=64, SERVER_STATUS_LAST_ROW_SENT=128, SERVER_STATUS_DB_DROPPED=256, SERVER_STATUS_NO_BACKSLASH_ESCAPES=512, y SERVER_QUERY_WAS_SLOW=1024.
`mysqlnd.mempool_default_size` int
  Tamaño por omisión de la cola de memoria mysqlnd, utilizada por los juegos de resultados.
`mysqlnd.net_read_timeout` int
  `mysqlnd` y la MySQL Client Library, `libmysqlclient` utilizan API de red diferentes. `mysqlnd` utiliza los flujos PHP, mientras que `libmysqlclient` utiliza su propia implementación basada en el sistema. PHP, por omisión, utiliza un timeout de lectura de 60s. Esto utilizando el parámetro de php.ini, `default_socket_timeout`. Esto se aplica a todos los flujos que no especifican un timeout por omisión. `mysqlnd` no afecta ningún otro valor y por lo tanto las consultas largas pueden verse desconectadas después de `default_socket_timeout` segundos con el resultado de un mensaje de error 2006 - MySQL Server has gone away. La MySQL Client Library afecta un timeout por omisión de 24 * 3600 segundos (1 día) y espera otros timeouts, como los de TCP/IP. `mysqlnd` utiliza ahora el mismo timeout muy largo. El valor es configurable mediante el parámetro php.ini `mysqlnd.net_read_timeout`. `mysqlnd.net_read_timeout` es por lo tanto utilizado por cualquier extensión (`ext/mysql`, `ext/mysqli`, `PDO_MySQL`) que se basa en `mysqlnd`. `mysqlnd` indica a los flujos PHP utilizar `mysqlnd.net_read_timeout`. Tenga en cuenta que puede haber diferencias sutiles entre `MYSQL_OPT_READ_TIMEOUT` de la MySQL Client Library y los flujos PHP, por ejemplo `MYSQL_OPT_READ_TIMEOUT` se dice funcional únicamente con conexiones TCP/IP y, antes de MySQL 5.1.2, solo en Windows. Los flujos PHP, ellos, no tienen esta limitación. Consulte la documentación de los flujos en caso de duda.
`mysqlnd.net_cmd_buffer_size` int
  `mysqlnd` asigna un buffer interno para la red de un tamaño de `mysqlnd.net_cmd_buffer_size` (en php.ini) bytes para cada conexión. Si una orden del protocolo MySQL Client Server, por ejemplo, `COM_QUERY` (consulta normal), no cabe en el buffer, `mysqlnd` aumentará aquel a la tamaño requerido. Cada vez que el buffer es aumentado para una conexión, `command_buffer_too_small` será incrementado en uno. Si `mysqlnd` debe aumentar el buffer más allá de su tamaño inicial de `mysqlnd.net_cmd_buffer_size` bytes para casi todas las conexiones, entonces debería aumentar este tamaño por omisión para evitar las reasignaciones. El tamaño por omisión del buffer es de 4096 bytes. El valor también puede ser cambiado mediante `mysqli_options(link, MYSQLI_OPT_NET_CMD_BUFFER_SIZE, size)`.
`mysqlnd.net_read_buffer_size` int
  Tamaño máximo del segmento en lectura al leer el cuerpo de un paquete de orden MySQL. El protocolo servidor de MySQL encapsula todas sus órdenes en paquetes. Los paquetes consisten en un encabezado corto seguido de un cuerpo que contiene las informaciones. El tamaño del cuerpo está codificado en el encabezado. `mysqlnd` lee el cuerpo en forma de segmentos de `MIN(header.size, mysqlnd.net_read_buffer_size)` bytes. Si el cuerpo de un paquete es más grande que `mysqlnd.net_read_buffer_size` bytes, `mysqlnd` debe entonces llamar a `read()` varias veces. El valor también puede ser cambiado mediante `mysqli_options(link, MYSQLI_OPT_NET_READ_BUFFER_SIZE, size)`.
`mysqlnd.sha256_server_public_key` string
  Relacionado con el plugin de autenticación SHA-256. Fichero que contiene la clave pública RSA en el servidor MySQL. Los clientes pueden omitir definir una clave pública RSA y especificar la clave mediante la directiva de configuración PHP, o bien, definir la clave en el momento de la ejecución utilizando la función mysqli_options(). Si ningún fichero de clave pública RSA es proporcionado por el cliente, entonces la clave será intercambiada conforme al procedimiento del plugin de autenticación estándar SHA-256.
`mysqlnd.trace_alloc` string
`mysqlnd.fetch_data_copy` int
  Obliga a copiar los juegos de resultados desde los buffers internos hacia variables PHP en lugar de utilizar el mecanismo por omisión de referencia y copia al escribir. Consulte las, notas de implementación sobre la gestión de memoria para más detalles. Copiar los juegos de resultados en lugar de tener variables PHP que los referencian permite liberar más pronto la memoria ocupada por las variables PHP. Dependiendo del código de la API cliente, las consultas actuales y el tamaño de sus juegos de resultados, esto puede reducir la huella de memoria de mysqlnd. No activar con PDO_MySQL. PDO_MySQL no soporta aún este modo.

  > Nota: Eliminado a partir de PHP 8.1.0

# Incompatibilidades

El Driver MySQL Native es compatible en muchos casos con la librería MySQL Client (`libmysql`). Esta sección documenta las incompatibilidades entre estas librerías.

- Los valores de tipo `bit` son devueltos como strings binarios (p.e. "\0" o "\x1F") con `libmysql` y como strings decimales (p.e. "0" o "31") con `mysqlnd`. Si se desea que el código sea compatible con ambas librerías entonces siempre se deberá devolver campos de tipo bit como números desde MySQL con una consulta como la siguiente: `SELECT bit + 0 FROM table`.

# Conexiones persistentes

Utilizar conexiones persistentes

Si `mysqli` se utiliza con `mysqlnd`, cuando se crea una conexión persistente, se genera una llamada `COM_CHANGE_USER` (`mysql_change_user()`) en el servidor. Esto asegura que la re-autenticación de la conexión se lleva a cabo.

Dado que hay una cierta sobrecarga asociada con la llamada `COM_CHANGE_USER`, es posible apagar esto en el tiempo de compilado. La reutilización de una conexión persistente entonces generará una llamada `COM_PING` (`mysql_ping`) para simplemente probar si la conexión es reusable.

La generación de `COM_CHANGE_USER` se puede apagar con el marcador de compilación `MYSQLI_NO_CHANGE_USER_ON_PCONNECT`. Por ejemplo:

    shell# CFLAGS="-DMYSQLI_NO_CHANGE_USER_ON_PCONNECT" ./configure --with-mysql=/usr/local/mysql/ --with-mysqli=/usr/local/mysql/bin/mysql_config --with-pdo-mysql=/usr/local/mysql/bin/mysql_config --enable-debug && make clean && make -j6

O, alternativamente:

    shell# export CFLAGS="-DMYSQLI_NO_CHANGE_USER_ON_PCONNECT"
    shell# configure --whatever-option
    shell# make clean
    shell# make

Observe que solamente `mysqli` sobre `mysqlnd` utiliza `COM_CHANGE_USER`. Otra combinación de extensión-controlador emplea `COM_PING` en el uso inicial de una conexión persistente.

# Estadísticas

El controlador nativo de MySQL contiene soporte para la recolección de estadísticas sobre la comunicación entre el cliente y el servidor. Las estadísticas recolectadas son de dos tipos principales:

- Estadísticas del cliente
- Estadísticas de la conexión

Cuando se utiliza la extensión mysqli, estas estadísticas pueden obtenerse mediante dos llamadas API:

- mysqli_get_client_stats()
- mysqli_get_connection_stats()

> Nota: Las estadísticas se agrupan entre todas las extensiones que utilizan el controlador nativo de MySQL. Por ejemplo, si la extensión mysqli y el controlador PDO MySQL están ambos configurados para usar MySQLnd, entonces las llamadas de funciones de mysqli y las llamadas de métodos de PDO afectarán las estadísticas. No hay manera de saber cuánto impacto ha tenido una cierta llamada API de una extensión que ha sido compilada sin el controlador nativo de MySQL en una cierta estadística.

## Recuperación de las estadísticas

Las estadísticas del cliente pueden recuperarse llamando a la función mysqli_get_client_stats().

Las estadísticas de conexión pueden recuperarse llamando a la función mysqli_get_connection_stats().

Las dos funciones devuelven un array asociativo, donde el nombre de una estadística es la clave para los datos estadísticos correspondientes.

## Estadísticas del controlador nativo de MySQL

La mayoría de las estadísticas están asociadas a una conexión, pero algunas están asociadas al proceso, en cuyo caso esto será mencionado.

Las siguientes estadísticas son producidas por el controlador nativo de MySQL:

Estadísticas relacionadas con la red
`bytes_sent`
  El número de bytes enviados de PHP al servidor MySQL.
`bytes_received`
  El número de bytes recibidos del servidor MySQL.
`packets_sent`
  El número de paquetes enviados por el protocolo cliente-servidor MySQL.
`packets_received`
  El número de paquetes recibidos del protocolo cliente-servidor MySQL.
`protocol_overhead_in`
  La sobrecarga del protocolo cliente-servidor MySQL en bytes para el tráfico entrante. Actualmente, solo el encabezado de paquete (4 bytes) se considera como sobrecarga. `protocol_overhead_in = packets_received * 4`
`protocol_overhead_out`
  La sobrecarga del protocolo cliente-servidor MySQL en bytes para el tráfico saliente. Actualmente, solo el encabezado de paquete (4 bytes) se considera como sobrecarga. `protocol_overhead_out = packets_received * 4`
`bytes_received_ok_packet`
  El tamaño total en bytes de los paquetes OK del protocolo cliente-servidor MySQL recibidos. Los paquetes OK pueden contener un mensaje de estado. La longitud del mensaje de estado puede variar y por lo tanto el tamaño de un paquete OK no es fijo.

  > Nota: El tamaño total en bytes incluye el tamaño del encabezado del paquete (4 bytes, ver la sobrecarga del protocolo).

`packets_received_ok`
  El número de paquetes OK del protocolo cliente-servidor MySQL recibidos.
`bytes_received_eof_packet`
  El tamaño total en bytes de los paquetes EOF del protocolo cliente-servidor MySQL recibidos. El tamaño de un paquete EOF puede variar dependiendo de la versión del servidor. Además, un paquete EOF puede transportar un mensaje de error.

  > Nota: El tamaño total en bytes incluye el tamaño del encabezado del paquete (4 bytes, ver la sobrecarga del protocolo).

`packets_received_eof`
  El número de paquetes EOF del protocolo cliente-servidor MySQL recibidos. Al igual que con otras estadísticas de paquetes, el número de paquetes será incrementado incluso si PHP no recibe el paquete esperado, sino, por ejemplo, un mensaje de error.
`bytes_received_rset_header_packet`
  El tamaño total en bytes de los encabezados de paquetes de resultados del protocolo cliente-servidor MySQL recibidos. El tamaño del encabezado del paquete puede variar dependiendo de la carga útil (`LOAD LOCAL INFILE`, `INSERT`, `UPDATE`, `SELECT`, mensaje de error).

  > Nota: El tamaño total en bytes incluye el tamaño del encabezado del paquete (4 bytes, ver la sobrecarga del protocolo).

`packets_received_rset_header`
  El número de paquetes de encabezados de resultados del protocolo cliente-servidor MySQL recibidos.
`bytes_received_rset_field_meta_packet`
  El tamaño total en bytes de los paquetes de metadatos de resultados del protocolo cliente-servidor (información de campo). Por supuesto, el tamaño varía con los campos del resultado. El paquete también puede transportar un error o un paquete EOF en caso de COM_LIST_FIELDS.

  > Nota: El tamaño total en bytes incluye el tamaño del encabezado del paquete (4 bytes, ver la sobrecarga del protocolo).

`packets_received_rset_field_meta`
  El número de paquetes de metadatos de resultados del protocolo cliente-servidor recibidos (información de campo).
`bytes_received_rset_row_packet`
  El tamaño total en bytes de los datos de fila de resultados del protocolo cliente-servidor MySQL recibidos. El paquete también puede transportar un error o un paquete EOF. Se puede calcular el número de errores y paquetes EOF restando `rows_fetched_from_server_normal` y `rows_fetched_from_server_ps` de `bytes_received_rset_row_packet`.

  > Nota: El tamaño total en bytes incluye el tamaño del encabezado del paquete (4 bytes, ver la sobrecarga del protocolo).

`packets_received_rset_row`
  El número de paquetes de datos de fila de resultados del protocolo cliente-servidor MySQL recibidos.
`bytes_received_prepare_response_packet`
  El tamaño total en bytes de los paquetes OK del protocolo cliente-servidor MySQL recibidos para la inicialización de declaraciones preparadas (paquetes de inicialización de declaración preparada). El paquete también puede transportar un error. El tamaño del paquete depende de la versión de MySQL.

  > Nota: El tamaño total en bytes incluye el tamaño del encabezado del paquete (4 bytes, ver la sobrecarga del protocolo).

`packets_received_prepare_response`
  El número de paquetes OK del protocolo cliente-servidor MySQL recibidos para la inicialización de declaraciones preparadas (paquetes de inicialización de declaración preparada).
`bytes_received_change_user_packet`
  El tamaño total en bytes de los paquetes COM_CHANGE_USER del protocolo cliente-servidor MySQL recibidos. El paquete también puede transportar un error o un paquete EOF.

  > Nota: El tamaño total en bytes incluye el tamaño del encabezado del paquete (4 bytes, ver la sobrecarga del protocolo).

`packets_received_change_user`
  El número de paquetes COM_CHANGE_USER del protocolo cliente-servidor MySQL recibidos.
`packets_sent_command`
  El número de comandos MySQL enviados por PHP al servidor MySQL. No hay manera de saber qué comandos específicos y cuántos de ellos han sido enviados.
`bytes_received_real_data_normal`
  El número de bytes de carga útil recuperados por el cliente PHP desde `mysqlnd` usando el protocolo de texto. Esto es el tamaño de los datos reales contenidos en los conjuntos de resultados que no provienen de declaraciones preparadas y que han sido recuperados por el cliente PHP. Es de notar que aunque un conjunto de resultados completo haya podido ser extraído de MySQL por `mysqlnd`, esta estadística solo cuenta los datos reales extraídos de `mysqlnd` por el cliente PHP.

  Un ejemplo de secuencia de código que incrementará el valor es el siguiente:

      $mysqli = new mysqli();
      $res = $mysqli->query("SELECT 'abc'");
      $res->fetch_assoc();
      $res->close();

  Cada operación de recuperación incrementará el valor.

  Sin embargo, la estadística no será incrementada si el conjunto de resultados es solo almacenado en búfer en el cliente, pero no extraído, como en el siguiente ejemplo:

      $mysqli = new mysqli();
      $res = $mysqli->query("SELECT 'abc'");
      $res->close();

`bytes_received_real_data_ps`
  El número de bytes de carga útil recuperados por el cliente PHP desde `mysqlnd` usando el protocolo de declaración preparada. Esto es el tamaño de los datos reales contenidos en los conjuntos de resultados que provienen de declaraciones preparadas y que han sido recuperados por el cliente PHP. El valor no será incrementado si el conjunto de resultados no es leído por el cliente PHP. Es de notar que aunque un conjunto de resultados completo haya podido ser extraído de MySQL por `mysqlnd`, esta estadística solo cuenta los datos reales extraídos de `mysqlnd` por el cliente PHP. Ver también `bytes_received_real_data_normal`.

Estadísticas relacionadas con los conjuntos de resultados
`result_set_queries`
  El número de consultas que han generado un conjunto de resultados. Ejemplos de consultas que generan un conjunto de resultados: `SELECT`, `SHOW`. La estadística no será incrementada si hay un error al leer el encabezado del paquete del conjunto de resultados.

  > Nota: Esta estadística puede ser utilizada como medida indirecta del número de Esto puede ayudar a identificar un cliente que provoca una carga alta en la base de datos. consultas que PHP ha enviado a MySQL.

`non_result_set_queries`
  El número de consultas que no han generado un conjunto de resultados. Ejemplos de consultas que no generan un conjunto de resultados: `INSERT`, `UPDATE`, `LOAD DATA`. Esta estadística no será incrementada si hay un error al leer el encabezado del paquete del conjunto de resultados.

  > Nota: Esta estadística puede ser utilizada como medida indirecta del número de Esto puede ayudar a identificar un cliente que provoca una carga alta en la base de datos. consultas que PHP ha enviado a MySQL.

`no_index_used`
  El número de consultas que han generado un conjunto de resultados pero no han utilizado un índice. (Ver también la opción de inicio de mysqld `--log-queries-not-using-indexes`).

  > Nota: Estas consultas pueden ser reportadas mediante una excepción llamando `mysqli_report(MYSQLI_REPORT_INDEX);`. Es posible reportarlas mediante un aviso llamando `mysqli_report(MYSQLI_REPORT_INDEX ^ MYSQLI_REPORT_STRICT);`.

`bad_index_used`
  El número de consultas que han generado un conjunto de resultados y no han utilizado un buen índice. (Ver también la opción de inicio de mysqld `--log-slow-queries`).

  > Nota: Estas consultas pueden ser reportadas mediante una excepción llamando `mysqli_report(MYSQLI_REPORT_INDEX);`. Es posible reportarlas mediante un aviso llamando `mysqli_report(MYSQLI_REPORT_INDEX ^ MYSQLI_REPORT_STRICT);`.

`slow_queries`
  Las declaraciones SQL que han tomado más de `long_query_time` segundos para ejecutarse y han necesitado al menos `min_examined_row_limit` filas para examinar.
  Precaución

  No reportado mediante mysqli_report().

`buffered_sets`
  El número de conjuntos de resultados almacenados en búfer devueltos por consultas normales (es decir, no mediante una declaración preparada).

  Ejemplos de llamadas API que almacenarán en búfer los conjuntos de resultados en el cliente: mysqli_query(), mysqli_store_result(), mysqli_stmt_get_result()

`unbuffered_sets`
  El número de conjuntos de resultados no almacenados en búfer devueltos por consultas normales (es decir, no mediante una declaración preparada).

  Ejemplos de llamadas API que no almacenarán en búfer los conjuntos de resultados en el cliente: mysqli_use_result()

`ps_buffered_sets`
  El número de conjuntos de resultados almacenados en búfer devueltos por declaraciones preparadas.

  Ejemplos de llamadas API que almacenarán en búfer los conjuntos de resultados en el cliente: mysqli_stmt_store_result()

`ps_unbuffered_sets`
  El número de conjuntos de resultados no almacenados en búfer devueltos por declaraciones preparadas. Por omisión, las declaraciones preparadas no son almacenadas en búfer, por lo que la mayoría de las declaraciones preparadas serán contabilizadas en esta estadística.
`flushed_normal_sets`
  El número de juegos de resultados devueltos por consultas normales (es decir, no mediante una declaración preparada) con datos no leídos que han sido silenciosamente vaciados.

  > Nota: El vaciado solo ocurre con conjuntos de resultados no almacenados en búfer. Los conjuntos de resultados no almacenados en búfer deben ser recuperados completamente antes de que una nueva consulta pueda ser ejecutada en la conexión, de lo contrario MySQL lanzará un error. Si la aplicación no recupera todas las filas de un conjunto de resultados no almacenado en búfer, mysqlnd recupera implícitamente el conjunto de resultados para vaciar la fila. Ver también `rows_skipped_normal`, `rows_skipped_ps`.

  > Algunas causas posibles para un vaciado implícito:

  > - Aplicación cliente defectuosa
  > - Cliente se detuvo de leer después de encontrar lo que buscaba pero hizo que MySQL calculara más filas de las necesarias
  > - La aplicación cliente se detuvo de manera inesperada

`flushed_ps_sets`
  El número de juegos de resultados devueltos por declaraciones preparadas con datos no leídos que han sido silenciosamente vaciados.

  > Nota: El vaciado solo ocurre con conjuntos de resultados no almacenados en búfer. Los conjuntos de resultados no almacenados en búfer deben ser recuperados completamente antes de que una nueva consulta pueda ser ejecutada en la conexión, de lo contrario MySQL lanzará un error. Si la aplicación no recupera todas las filas de un conjunto de resultados no almacenado en búfer, mysqlnd recupera implícitamente el conjunto de resultados para vaciar la fila. Ver también `rows_skipped_normal`, `rows_skipped_ps`.

  > Algunas causas posibles para un vaciado implícito:

  > - Aplicación cliente defectuosa
  > - Cliente se detuvo de leer después de encontrar lo que buscaba pero hizo que MySQL calculara más filas de las necesarias
  > - La aplicación cliente se detuvo de manera inesperada

`ps_prepared_never_executed`
  El número de declaraciones preparadas preparadas pero nunca ejecutadas.
`ps_prepared_once_executed`
  El número de declaraciones preparadas ejecutadas una sola vez.
`rows_fetched_from_server_normal`
`rows_fetched_from_server_ps`
  El número total de filas de conjunto de resultados recuperadas del servidor. Esto incluye las filas que no han sido leídas por el cliente pero han sido recuperadas implícitamente debido a conjuntos de resultados no almacenados en búfer vaciados. Ver también `packets_received_rset_row`.
`rows_buffered_from_client_normal`
  El número total de filas almacenadas en búfer provenientes de una consulta normal. Esto es el número de filas que han sido recuperadas de MySQL y almacenadas en búfer en el cliente.

  Ejemplos de consultas que almacenarán en búfer los conjuntos de resultados:

  - mysqli_query()
  - mysqli_store_result()
`rows_buffered_from_client_ps`
  Equivalente a `rows_buffered_from_client_normal` pero para las declaraciones preparadas.
`rows_fetched_from_client_normal_buffered`
  El número total de filas recuperadas por el cliente desde un conjunto de resultados almacenado en búfer creado por una consulta normal.
`rows_fetched_from_client_ps_buffered`
  El número total de filas recuperadas por el cliente desde un conjunto de resultados almacenado en búfer creado por una declaración preparada.
`rows_fetched_from_client_normal_unbuffered`
  El número total de filas recuperadas por el cliente desde un conjunto de resultados no almacenado en búfer creado por una consulta normal.
`rows_fetched_from_client_ps_unbuffered`
  El número total de filas recuperadas por el cliente desde un conjunto de resultados no almacenado en búfer creado por una declaración preparada.
`rows_fetched_from_client_ps_cursor`
  El número total de filas recuperadas por el cliente desde un cursor creado por una declaración preparada.
`rows_skipped_normal`
`rows_skipped_ps`
  Reservado para uso futuro (actualmente no soportado).
`copy_on_write_saved`
`copy_on_write_performed`
  Esto es una estadística de alcance de proceso. Con mysqlnd, las variables devueltas por las extensiones apuntan a mysqlnd búferes de resultados internos. Si los datos no son modificados, los datos extraídos solo se conservan una vez en memoria. Sin embargo, cualquier modificación de los datos requerirá que mysqlnd realice una operación de copia-al-escribir.
`explicit_free_result`
`implicit_free_result`
  Esto es una estadística de alcance de conexión y de proceso. El número total de resultados liberados.
`proto_text_fetched_null`
  El número total de columnas de tipo `MYSQL_TYPE_NULL` recuperadas desde una consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_null`
  El número total de columnas de tipo `MYSQL_TYPE_NULL` recuperadas desde una declaración preparada (protocolo binario MySQL).
`proto_text_fetched_bit`
  El número total de columnas de tipo `MYSQL_TYPE_BIT` recuperadas desde una consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_bit`
  El número total de columnas de tipo `MYSQL_TYPE_BIT` recuperadas desde una declaración preparada (protocolo binario MySQL).
`proto_text_fetched_tinyint`
  El número total de columnas de tipo `MYSQL_TYPE_TINY` recuperadas desde una consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_tinyint`
  El número total de columnas de tipo `MYSQL_TYPE_TINY` recuperadas desde una declaración preparada (protocolo binario MySQL).
`proto_text_fetched_short`
  El número total de columnas de tipo `MYSQL_TYPE_SHORT` recuperadas desde una consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_short`
  El número total de columnas de tipo `MYSQL_TYPE_SHORT` recuperadas desde una declaración preparada (protocolo binario MySQL).
`proto_text_fetched_int24`
  El número total de columnas de tipo `MYSQL_TYPE_INT24` recuperadas desde una consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_int24`
  El número total de columnas de tipo `MYSQL_TYPE_INT24` recuperadas desde una declaración preparada (protocolo binario MySQL).
`proto_text_fetched_int`
  El número total de columnas de tipo `MYSQL_TYPE_LONG` recuperadas desde una consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_int`
  El número total de columnas de tipo `MYSQL_TYPE_LONG` recuperadas desde una declaración preparada (protocolo binario MySQL).
`proto_text_fetched_bigint`
  El número total de columnas de tipo `MYSQL_TYPE_LONGLONG` recuperadas desde una consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_bigint`
  El número total de columnas de tipo `MYSQL_TYPE_LONGLONG` recuperadas desde una declaración preparada (protocolo binario MySQL).
`proto_text_fetched_decimal`
  El número total de columnas de tipo `MYSQL_TYPE_DECIMAL`, o `MYSQL_TYPE_NEWDECIMAL` recuperadas desde una consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_decimal`
  El número total de columnas de tipo `MYSQL_TYPE_DECIMAL`, o `MYSQL_TYPE_NEWDECIMAL` recuperadas desde una declaración preparada (protocolo binario MySQL).
`proto_text_fetched_float`
  El número total de columnas de tipo `MYSQL_TYPE_FLOAT` recuperadas desde una consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_float`
  El número total de columnas de tipo `MYSQL_TYPE_FLOAT` recuperadas desde una declaración preparada (protocolo binario MySQL).
`proto_text_fetched_double`
  El número total de columnas de tipo `MYSQL_TYPE_DOUBLE` recuperadas desde una consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_double`
  El número total de columnas de tipo `MYSQL_TYPE_DOUBLE` recuperadas desde una declaración preparada (protocolo binario MySQL).
`proto_text_fetched_date`
  El número total de columnas de tipo `MYSQL_TYPE_DATE`, o `MYSQL_TYPE_NEWDATE` recuperadas desde una consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_date`
  El número total de columnas de tipo `MYSQL_TYPE_DATE`, o `MYSQL_TYPE_NEWDATE` recuperadas desde una declaración preparada (protocolo binario MySQL).
`proto_text_fetched_year`
  El número total de columnas de tipo `MYSQL_TYPE_YEAR` recuperadas desde una consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_year`
  El número total de columnas de tipo `MYSQL_TYPE_YEAR` recuperadas desde una declaración preparada (protocolo binario MySQL).
`proto_text_fetched_time`
  El número total de columnas de tipo `MYSQL_TYPE_TIME` recuperadas desde una consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_time`
  El número total de columnas de tipo `MYSQL_TYPE_TIME` recuperadas desde una declaración preparada (protocolo binario MySQL).
`proto_text_fetched_datetime`
  El número total de columnas de tipo `MYSQL_TYPE_DATETIME` recuperadas desde una consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_datetime`
  El número total de columnas de tipo `MYSQL_TYPE_DATETIME` recuperadas desde una declaración preparada (protocolo binario MySQL).
`proto_text_fetched_timestamp`
  El número total de columnas de tipo `MYSQL_TYPE_TIMESTAMP` recuperadas desde una consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_timestamp`
  El número total de columnas de tipo `MYSQL_TYPE_TIMESTAMP` recuperadas desde una declaración preparada (protocolo binario MySQL).
`proto_text_fetched_string`
  El número total de columnas de tipo `MYSQL_TYPE_STRING`, `MYSQL_TYPE_VARSTRING` o `MYSQL_TYPE_VARCHAR` recuperadas desde una consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_string`
  El número total de columnas de tipo `MYSQL_TYPE_STRING`, `MYSQL_TYPE_VARSTRING` o `MYSQL_TYPE_VARCHAR` recuperadas desde una declaración preparada (protocolo binario MySQL).
`proto_text_fetched_blob`
  El número total de columnas de tipo `MYSQL_TYPE_TINY_BLOB`, `MYSQL_TYPE_MEDIUM_BLOB`, `MYSQL_TYPE_LONG_BLOB`, o `MYSQL_TYPE_BLOB` recuperadas desde una consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_blob`
  El número total de columnas de tipo `MYSQL_TYPE_TINY_BLOB`, `MYSQL_TYPE_MEDIUM_BLOB`, `MYSQL_TYPE_LONG_BLOB`, o `MYSQL_TYPE_BLOB` recuperadas desde una declaración preparada (protocolo binario MySQL).
`proto_text_fetched_enum`
  El número total de columnas de tipo `MYSQL_TYPE_ENUM` recuperadas desde una consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_enum`
  El número total de columnas de tipo `MYSQL_TYPE_ENUM` recuperadas desde una declaración preparada (protocolo binario MySQL).
`proto_text_fetched_set`
  El número total de columnas de tipo `MYSQL_TYPE_SET` recuperadas desde una consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_set`
  El número total de columnas de tipo `MYSQL_TYPE_SET` recuperadas desde una declaración preparada (protocolo binario MySQL).
`proto_text_fetched_geometry`
  El número total de columnas de tipo `MYSQL_TYPE_GEOMETRY` recuperadas desde una consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_geometry`
  El número total de columnas de tipo `MYSQL_TYPE_GEOMETRY` recuperadas desde una declaración preparada (protocolo binario MySQL).
`proto_text_fetched_other`
  El número total de columnas de tipos `MYSQL_TYPE_*` no listados anteriormente recuperadas desde una consulta normal (protocolo de texto MySQL).

  > Nota: En teoría, esto debería ser siempre `0`.

`proto_binary_fetched_other`
  El número total de columnas de tipo `MYSQL_TYPE_*` no listados anteriormente recuperadas desde una declaración preparada (protocolo binario MySQL).

  > Nota: En teoría, esto debería ser siempre `0`.

Estadísticas relacionadas con la conexión
`connect_success`
  El número total de intentos de conexión exitosos.

  > Nota: `connect_success` contiene la suma de los intentos de conexión persistentes y no persistentes exitosos. Por lo tanto, el número de intentos de conexión no persistentes exitosos es `connect_success - pconnect_success`.

`pconnect_success`
  El número total de intentos de conexión persistentes exitosos.
`connect_failure`
  El número total de intentos de conexión fallidos.
`reconnect`
  Esto es una estadística de alcance de proceso.
`active_connections`
  Esto es una estadística de alcance de proceso. El número total de conexiones persistentes y no persistentes activas.

  > Nota: El número total de conexiones no persistentes activas es `active_connections - active_persistent_connections`.

`active_persistent_connections`
  Esto es una estadística de alcance de proceso. El número total de conexiones persistentes activas.
`explicit_close`
  El número total de conexiones cerradas explícitamente.

  Ejemplo #1 Ejemplos de fragmentos de código que provocan un cierre explícito

  -     $link = new mysqli(/* ... */);
        $link->close(/* ... */);

  -     $link = new mysqli(/* ... */);
        $link->connect(/* ... */);

`implicit_close`
  El número total de conexiones cerradas implícitamente.

  Ejemplo #2 Ejemplos de fragmentos de código que provocan un cierre implícito

  -     $link = new mysqli(/* ... */);
        $link->real_connect(/* ... */);

  - `unset($link)`
  - Conexión persistente: una conexión agrupada ha sido creada con real_connect y puede haber opciones desconocidas definidas - cerrar implícitamente para evitar devolver una conexión con opciones desconocidas
  - Conexión persistente: ping/change_user falla y ext/mysqli cierra la conexión
  - Fin de la ejecución del script: cerrar conexiones que no han sido cerradas por el usuario
`disconnect_close`
  Fallos de conexión indicados por la llamada de API C `mysql_real_connect` durante un intento de establecer una conexión.
`in_middle_of_command_close`
  Esto es una estadística de alcance de proceso. Una conexión ha sido cerrada en medio de la ejecución de un comando (conjuntos de resultados no recuperados, después de enviar una consulta y antes de recuperar una respuesta, durante la recuperación de datos, durante la transferencia de datos con LOAD DATA).
  Advertencia

  A menos que se usen consultas asíncronas, esto solo debería ocurrir si la aplicación PHP terminó inesperadamente y PHP cierra automáticamente la conexión.

`init_command_executed_count`
  El número total de ejecuciones de comandos de inicialización. Por ejemplo: `mysqli_options(MYSQLI_INIT_COMMAND , $value)`. El número de ejecuciones exitosas es `init_command_executed_count - init_command_failed_count`.
`init_command_failed_count`
  El número total de fallos en la ejecución de comandos de inicialización.

Estadísticas relacionadas con los comandos `COM_*`
`com_quit`
`com_init_db`
`com_query`
`com_field_list`
`com_create_db`
`com_drop_db`
`com_refresh`
`com_shutdown`
`com_statistics`
`com_process_info`
`com_connect`
`com_process_kill`
`com_debug`
`com_ping`
`com_time`
`com_delayed_insert`
`com_change_user`
`com_binlog_dump`
`com_table_dump`
`com_connect_out`
`com_register_slave`
`com_stmt_prepare`
`com_stmt_execute`
`com_stmt_send_long_data`
`com_stmt_close`
`com_stmt_reset`
`com_stmt_set_option`
`com_stmt_fetch`
`com_daemon`
  El número total de intentos de enviar un cierto comando `COM_*` de PHP a MySQL. La estadística es incrementada después de verificar la línea y justo antes de enviar el paquete de protocolo cliente-servidor MySQL correspondiente.
  Precaución

  Si MySQLnd falla al enviar el paquete en la red, las estadísticas no serán decrementadas. En caso de fallo, MySQLnd emite un aviso PHP Error while sending %s packet. PID=%d.

  Ejemplo #3 Ejemplos de uso

  - Verificar si PHP envía ciertos comandos a MySQL, por ejemplo, verificar si un cliente envía `COM_PROCESS_KILL`
  - Calcular el número promedio de ejecuciones de comandos preparados comparando `COM_EXECUTE` con `COM_PREPARE`
  - Verificar si PHP ha ejecutado declaraciones SQL no preparadas verificando si `COM_QUERY` es cero
  - Identificar los scripts PHP que ejecutan un número excesivo de declaraciones SQL verificando `COM_QUERY` y `COM_EXECUTE`

Estadísticas diversas
`explicit_stmt_close`
`implicit_stmt_close`
  Esto es una estadística de alcance de proceso. El número total de declaraciones preparadas cerradas explícitamente.

  > Nota: Una declaración preparada siempre es cerrada explícitamente. La única vez que es cerrada implícitamente es cuando su preparación falla.

`mem_emalloc_count`
`mem_emalloc_ammount`
`mem_ecalloc_count`
`mem_ecalloc_ammount`
`mem_realloc_count`
`mem_realloc_ammount`
`mem_efree_count`
`mem_malloc_count`
`mem_malloc_ammount`
`mem_calloc_count`
`mem_calloc_ammount`
`mem_ealloc_count`
`mem_ealloc_ammount`
`mem_free_count`
  Esto es una estadística de alcance de proceso. Llamadas a la gestión de memoria.
`command_buffer_too_small`
  El número de extensiones de búfer de comando de red al enviar comandos de PHP a MySQL. MySQLnd asigna un búfer de comando/red interno de mysqlnd.net_cmd_buffer_size bytes para cada conexión. Si un protocolo de comando de servidor MySQL, por ejemplo `COM_QUERY` (consulta normal), no cabe en el búfer, MyQSLnd extenderá el búfer a lo que sea necesario para enviar el comando. Cada vez que el búfer es extendido para una conexión `command_buffer_too_small` será incrementado en uno. Si mysql es obligado a hacer crecer el búfer más allá de su tamaño inicial de mysqlnd.net_cmd_buffer_size bytes para casi cada conexión, se deberían considerar aumentar el tamaño por defecto para evitar las reasignaciones.
`connection_reused`
  El número total de veces que una conexión persistente ha sido reutilizada.

# Notas

En esta sección se ofrece una colección de diversas notas sobre el uso del Controlador Nativo de MySQL.

- Utilizar `mysqlnd` significa que se están utilizando flujos PHP para la conectividad subyacente. Para `mysqlnd`, se debe consultar la documentación de flujos de PHP (Flujos) para detalles como la configuración del tiempo de espera, y no la documentación para la Biblioteca Cliente de MySQL.

# Gestión de la memoria

Introducción

El driver nativo MySQL gestiona la memoria de forma diferente a la biblioteca cliente MySQL. Las bibliotecas difieren en la forma en que la memoria es asignada y liberada, en la forma en que la memoria es asignada por fragmentos durante la lectura de los resultados desde MySQL, qué opciones de depuración y desarrollo existen, y cómo los resultados leídos desde MySQL son vinculados a las variables de usuario PHP.

Las notas siguientes son una introducción y un resumen destinados a los usuarios interesados en comprender el driver nativo MySQL desde el punto de vista del código C.

Funciones utilizadas en la gestión de memoria

Todas las asignaciones y desasignaciones se realizan utilizando las funciones de gestión de memoria de PHP. Sin embargo, el consumo de memoria de mysqlnd puede ser monitoreado utilizando llamadas a APIs de PHP, como memory_get_usage(). Debido a que la memoria es asignada y liberada utilizando la gestión de memoria de PHP, las modificaciones pueden no ser inmediatamente visibles a nivel del sistema operativo. El gestor de memoria de PHP funciona como un proxy que puede tener un poco de retraso en la liberación de memoria del sistema. Además, la comparación del uso de memoria del driver nativo MySQL y de la biblioteca cliente MySQL se vuelve difícil. La biblioteca cliente MySQL llama directamente al gestor de memoria del sistema operativo, y por lo tanto, los efectos pueden ser vistos inmediatamente a nivel del sistema operativo.

Todas las limitaciones de memoria realizadas por PHP afectan también al driver nativo MySQL. Esto puede causar errores de excedente de memoria al recuperar juegos de resultados demasiado grandes, excediendo el tamaño de la memoria restante disponible para PHP. Debido a que la biblioteca cliente MySQL no utiliza las funciones de gestión de memoria de PHP, no tiene en cuenta ninguna limitación de memoria definida por PHP. Si se utiliza la biblioteca cliente MySQL, según el modelo de despliegue, la huella de memoria del proceso PHP puede aumentar y superar el límite de memoria impuesto por PHP. Además, los scripts PHP pueden analizar juegos de resultados más grandes, asignando así más memoria para el juego de resultados de la que el control del motor PHP permite.

Las funciones de gestión de memoria de PHP son llamadas por el driver nativo MySQL a través de un gestor ligero. Entre otras cosas, este gestor facilita el depuración.

Gestión de los juegos de resultados

Los diferentes servidores MySQL y las diferentes APIs de clientes se diferencian según el buffering o no de los juegos de resultados. Los juegos de resultados que no son bufferizados son transferidos línea por línea desde MySQL hacia el cliente, y el cliente recorrerá los resultados. Los resultados que son bufferizados son recuperados en su totalidad por la biblioteca cliente antes de pasarlos al cliente.

El driver nativo MySQL utiliza flujos PHP para la comunicación en red con el servidor MySQL. Los resultados enviados por MySQL son recuperados desde la memoria buffer de los flujos de red PHP hacia la memoria buffer de resultados de mysqlnd. La memoria buffer de resultados está compuesta por zvals. En una etapa siguiente, los resultados son puestos a disposición del script PHP. La transferencia final desde la memoria buffer de resultados hacia las variables PHP impacta el consumo de memoria y esto se vuelve muy visible al utilizar juegos de resultados bufferizados.

Por omisión, el driver nativo MySQL intenta no conservar en memoria dos veces los resultados bufferizados. Los resultados son conservados una sola vez en la memoria buffer interna de resultados, así como en sus zvals. Cuando los resultados son recuperados en las variables PHP por el script PHP, las variables referenciarán la memoria buffer interna de resultados. Los resultados de consultas de base de datos no son copiados y son conservados en memoria solo una vez. Cuando un usuario modifica el contenido de una variable que contiene un resultado de base de datos, una operación de copia-al-escritura debe ser realizada para evitar modificar la memoria buffer interna de resultado referenciada. El contenido de la memoria buffer no debe ser modificado porque el usuario puede decidir leer el juego de resultados una segunda vez. La operación de copia-al-escritura está implementada utilizando un gestor de lista de referencia adicional, así como el uso de los contadores de referencia zvals estándar. La operación de copia-al-escritura también debe ser realizada si el usuario lee un juego de resultados en las variables PHP y libera un juego de resultado antes de que las variables sean eliminadas.

En general, este mecanismo funciona bien para los scripts que leen un juego de resultados una sola vez, y no modifican las variables que contienen los resultados. Su principal desventaja es la sobrecarga de memoria causada por el gestor de referencia adicional, que proviene principalmente del hecho de que las variables de usuario que contienen los resultados no pueden ser liberadas completamente mientras el gestor de referencia mysqlnd las siga referenciando. El driver nativo MySQL elimina la referencia a las variables de usuario cuando el juego de resultados es liberado o cuando se realiza una operación de copia-al-escritura. Un observador puede ver que el consumo total de memoria aumenta mientras el juego de resultados no sea liberado. Utilice las estadísticas para verificar si un script libera el juego de resultados explícitamente, o si el driver lo libera implícitamente, haciendo que la memoria sea utilizada más tiempo del necesario. Las estadísticas también pueden ayudar a ver las operaciones de copia-al-escritura.

Un script PHP que lee muchas pequeñas líneas de un juego de resultados bufferizado utilizando líneas de código como `while ($row = $res->fetch_assoc()) { ... }` puede optimizar el consumo de memoria solicitando una copia en lugar de referencias. Aunque solicitar copias significa conservar dos veces el resultado en memoria, esto permite a PHP liberar la copia contenida en `$row` sabiendo que el juego de resultados está siendo recorrido y antes de liberar el juego de resultados en sí. En un servidor cargado, la optimización del uso de memoria puede mejorar el rendimiento del sistema en general, aunque para un script individual, el enfoque de la copia puede ser más lento debido a las operaciones adicionales de asignación y copia de memoria.

Supervisión y depuración

Existen varias formas de supervisar el uso de memoria del driver nativo MySQL. Si el objetivo es obtener una vista rápida de alto nivel, o verificar la eficiencia de memoria de los scripts PHP, entonces revise las estadísticas recopiladas por la biblioteca. Estas le permiten, por ejemplo, ver las consultas SQL que generan más resultados de los analizados por un script PHP.

El rastreo de depuración en el historial puede ser configurado para registrar las llamadas al gestor de memoria. Esto puede ayudar a ver cuándo la memoria es asignada o liberada. Sin embargo, el tamaño de los fragmentos de memoria solicitados puede no estar listado.

Las versiones recientes del driver nativo MySQL intentan emular situaciones de excedente de memoria aleatorio. Esto es útil únicamente para los desarrolladores C de la biblioteca, o para los desarrolladores del complemento mysqlnd. Consulte el código fuente para las opciones de configuración de PHP correspondientes, así como para obtener más detalles sobre este mecanismo. Esta funcionalidad se considera privada, y puede ser modificada en cualquier momento sin previo aviso.

# API del plugin del controlador nativo MySQL

## Tabla de contenidos

- Comparación de los plugins mysqlnd con proxy MySQL
- Obtener la API del plugin mysqlnd
- Arquitectura del plugin del controlador nativo
- La API del plugin mysqlnd
- Cómo comenzar a compilar un plugin mysqlnd

La API del plugin del controlador nativo MySQL es una funcionalidad del controlador nativo MySQL, o `mysqlnd`. El plugin `Mysqlnd` opera en la capa entre las aplicaciones PHP y el servidor MySQL. Es comparable a un proxy MySQL. Un proxy MySQL opera en una capa entre todas las aplicaciones cliente MySQL, por ejemplo, una aplicación PHP y un servidor MySQL. El plugin `Mysqlnd` puede realizar tareas típicas de proxy MySQL como el equilibrio de carga, así como el seguimiento y la optimización de las prestaciones. Debido a una arquitectura y una localización diferente, el plugin `mysqlnd` no tiene todos los inconvenientes de un proxy MySQL. Por ejemplo, con el plugin, no hay un único punto de fallo, no hay un servidor proxy dedicado que desplegar, y no hay un nuevo lenguaje que aprender (Lua).

Un plugin `mysqlnd` puede ejecutarse como una extensión a `mysqlnd`. Un plugin puede interceptar la mayoría de las funciones `mysqlnd`. Las funciones `mysqlnd` son llamadas por la extensión PHP MySQL como `ext/mysql`, `ext/mysqli`, y `PDO_MYSQL`. Como resultado, es posible para un plugin `mysqlnd` interceptar todas las llamadas realizadas por estas extensiones desde una aplicación cliente.

Las llamadas a las funciones internas `mysqlnd` pueden también ser interceptadas o reemplazadas. No hay ninguna restricción sobre la manipulación de las tablas de funciones internas `mysqlnd`. Es posible definir acciones para que cuando ciertas funciones `mysqlnd` sean llamadas por la extensión que utiliza `mysqlnd`, la llamada sea redirigida hacia la función apropiada del plugin `mysqlnd`. La posibilidad de manipular las tablas de funciones internas `mysqlnd` de este modo permite un máximo de flexibilidad.

El plugin `Mysqlnd` es, en realidad, una extensión PHP, escrita en C, que utiliza la API del plugin `mysqlnd` (que está compilada en el controlador nativo MySQL, `mysqlnd`). El plugin puede ser 100% transparente para las aplicaciones PHP. No se requiere ninguna modificación a las aplicaciones ya que el plugin opera en una capa diferente. El plugin `mysqlnd` puede ser utilizado en una capa por debajo de `mysqlnd`.

La lista siguiente representa algunas aplicaciones posibles del plugin `mysqlnd`.

- El equilibrio de carga.
  - Separación de lecturas y escrituras. Un ejemplo de esta funcionalidad es la extensión PECL/mysqlnd_ms (Maestro/esclavo). Esta extensión separa las consultas de lectura y escritura para una configuración de replicación.
  - Conmutación por error
  - Round-Robin, el menos cargado
- Supervisión
  - Registro de consultas
  - Análisis de consultas
  - Auditoría de consultas. Un ejemplo de esto es la extensión PECL/mysqlnd_sip (Protección contra Inyección SQL). Esta extensión inspecciona las consultas y ejecuta únicamente aquellas que son permitidas siguiendo conjuntos de reglas.
- Rendimiento
  - La caché. Un ejemplo de esto es la extensión PECL/mysqlnd_qc (Query Cache).
  - Limitación
  - Fragmentación. Un ejemplo de esto es la extensión PECL/mysqlnd_mc (Multi Connect). Esta extensión intenta separar una consulta SELECT en n partes, utilizando consultas del tipo SELECT ... LIMIT part_1, SELECT LIMIT part_n. La extensión envía las consultas a servidores MySQL distintos y luego fusiona el resultado hacia el cliente.

Plugins del controlador nativo MySQL disponibles

Ya hay varios plugins mysqlnd disponibles.

- PECL/mysqlnd_mc - Plugin Multi Conexión.
- PECL/mysqlnd_ms - Plugin Maestro Esclavo.
- PECL/mysqlnd_qc - Plugin de caché de consultas.
- PECL/mysqlnd_pscache - Plugin de caché de gestor de consultas preparadas.
- PECL/mysqlnd_sip - Plugin que permite la protección contra inyecciones SQL.
- PECL/mysqlnd_uh - Plugin de gestor de usuarios.

## Comparación de los plugins mysqlnd con proxy MySQL

Los plugins `Mysqlnd` y el proxy MySQL son tecnologías diferentes que utilizan diferentes enfoques. Ambos son herramientas válidas para resolver muchas tareas clásicas, como el equilibrio de carga, la supervisión, y la mejora de las prestaciones. Una diferencia importante es que el proxy MySQL funciona con todos los clientes MySQL mientras que los plugins `mysqlnd` son específicos para las aplicaciones PHP.

Como una extensión PHP, un plugin `mysqlnd` debe ser instalado en el servidor de aplicaciones PHP, además del resto de PHP. Un proxy MySQL puede funcionar tanto en el servidor de aplicaciones PHP como ser instalado en una máquina dedicada para gestionar varios servidores de aplicaciones PHP.

El despliegue de un proxy MySQL en un servidor de aplicaciones tiene 2 ventajas:

1. No hay un único punto de fallo
2. Fácil de escalar (escalado horizontal, escalado por el cliente)

Un proxy MySQL (y los plugins `mysqlnd`) puede resolver problemas fácilmente, que de otro modo habrían requerido modificaciones a las aplicaciones existentes.

Sin embargo, un proxy MySQL tiene algunos inconvenientes:

- Un proxy MySQL es un nuevo componente, una nueva tecnología a aplicar al maestro y desplegar.
- Un proxy MySQL requiere el conocimiento del lenguaje de script Lua.

Un proxy MySQL puede ser personalizado utilizando los lenguajes de programación C y Lua. Lua es el lenguaje preferido para un proxy MySQL. Para la mayoría de los expertos PHP, Lua es un nuevo lenguaje a aprender. Un plugin `mysqlnd` puede ser escrito en C. También es posible escribir un plugin en PHP utilizando » PECL/mysqlnd_uh.

Un proxy MySQL funciona como un demonio - un proceso en segundo plano. Un proxy MySQL puede recordar decisiones tomadas anteriormente, ya que todos los estados pueden ser conservados. Sin embargo, un plugin `mysqlnd` está ligado al ciclo de vida de una consulta PHP. Un proxy MySQL puede compartir también resultados calculados una sola vez entre varios servidores de aplicaciones. Un plugin `mysqlnd` puede necesitar almacenar datos en un medio persistente. Otro demonio puede ser utilizado con este propósito, como por ejemplo, Memcache. Este mecanismo da una ventaja al proxy MySQL.

Un proxy MySQL funciona por encima de la capa física. Con un proxy MySQL, debe analizar y realizar ingeniería inversa del protocolo cliente-servidor MySQL. Las acciones están limitadas a las que pueden ser realizadas mediante la manipulación del protocolo de comunicación. Si la capa física cambia (lo que ocurre muy raramente), los scripts del proxy MySQL pueden necesitar ser adaptados.

Los plugins `Mysqlnd` funcionan por encima de la API C, reflejando así las APIs cliente `libmysqlclient`. Esta API C es esencialmente una envoltura del protocolo Servidor Cliente MySQL, o de la capa física, ya que es llamada algunas veces. Puede interceptar todas las llamadas a la API C. PHP utiliza la API C, sin embargo, puede conectar todas las llamadas PHP, sin necesidad de programar a nivel de la capa física.

`Mysqlnd` implementa la capa física. Los plugins pueden analizar, realizar ingeniería inversa, manipular y siempre reemplazar el protocolo de comunicación. Sin embargo, esto no es generalmente necesario.

Dado que los plugins permiten crear implementaciones que utilizan los 2 niveles (API C y capa física), tienen más flexibilidad que el proxy MySQL. Si un plugin `mysqlnd` es implementado utilizando la API C, todos los cambios posteriores a la capa física no requerirán modificaciones al plugin en sí.

## Obtener la API del plugin mysqlnd

La API del plugin `mysqlnd` es simplemente una parte de la extensión del controlador PHP Nativo MySQL, `ext/mysqlnd`. El desarrollo de la API del plugin `mysqlnd` comenzó en Diciembre de 2009. Se desarrolla como parte del repositorio fuente de PHP, y por lo tanto, está disponible desde el repositorio público Git, o desde la descarga de las fuentes.

Los desarrolladores de plugins pueden determinar la versión de `mysqlnd` a través de la variable `MYSQLND_VERSION`, en el formato mysqlnd 8.3.17, o a través de `MYSQLND_VERSION_ID`, que es un entero como por ejemplo 50007. Los desarrolladores pueden calcular el número de versión de la siguiente manera:

Tabla de cálculo de MYSQLND_VERSION_ID
Versión (parte) | Ejemplo
--- | ---
Mayor*10000 | 5*10000 = 50000
Menor*100 | 0*100 = 0
Parche | 7 = 7
MYSQLND_VERSION_ID | 50007

Durante el desarrollo, los desarrolladores deben referirse al número de versión `mysqlnd` para pruebas de compatibilidad y de versión, sabiendo que varias versiones de `mysqlnd` pueden ocurrir durante un ciclo de vida de la rama de desarrollo de PHP.

## Arquitectura del plugin del controlador nativo

Esta sección proporciona una visión general de la arquitectura del plugin `mysqlnd`.

Visión general del controlador nativo MySQL

Antes de desarrollar plugins `mysqlnd`, es útil tener un conocimiento mínimo sobre la organización de `mysqlnd`. `Mysqlnd` está compuesto por los siguientes módulos:

Esquema de la organización mysqlnd, por módulo
Módulos de estadísticas | mysqlnd_statistics.c
--- | ---
Conexión | mysqlnd.c
Juego de resultados | mysqlnd_result.c
Datos méta del juego de resultados | mysqlnd_result_meta.c
Consulta | mysqlnd_ps.c
Red | mysqlnd_net.c
Capa física | mysqlnd_wireprotocol.c

Objeto C orientado a paradigma

A nivel de código, `mysqlnd` utiliza una máscara C para implementar la orientación al objeto.

En C, se utiliza una estructura (`struct`) para representar un objeto. Los miembros de esta estructura representan las propiedades del objeto. Los miembros de la estructura que apuntan hacia funciones representan los métodos.

A diferencia de otros lenguajes como C++ o Java, no hay reglas fijas sobre la herencia en los objetos C orientados a paradigma. Sin embargo, hay algunas convenciones que deben seguirse que serán abordadas posteriormente.

El ciclo de vida PHP

El ciclo de vida de PHP consta de 2 ciclos básicos:

- El ciclo de inicio y parada del motor PHP
- El ciclo de una petición

Cuando el motor PHP se inicia, llama a la función de inicialización del módulo (MINIT) de cada extensión registrada. Esto permite a cada módulo definir las variables y asignar los recursos que deben existir durante la vida del proceso correspondiente al motor PHP. Cuando el motor PHP se detiene, llama a la función de parada del módulo (MSHUTDOWN) para cada extensión.

Durante la vida del motor PHP, recibirá peticiones. Cada petición constituye otro ciclo de vida. Para cada petición, el motor PHP llamará a la función de inicialización de cada extensión. La extensión puede realizar todas las definiciones de variables así como las asignaciones de recursos necesarias para procesar la petición. Cuando el ciclo de la petición termina, el motor llama a la función de parada (RSHUTDOWN) para cada extensión, por lo que la extensión puede lanzar toda la limpieza necesaria.

Cómo funciona un plugin

Un plugin `mysqlnd` funciona interceptando las llamadas realizadas a `mysqlnd` por las extensiones que utilizan `mysqlnd`. Esto es posible obteniendo la tabla de función `mysqlnd`, guardándola, y reemplazándola por una tabla de función personalizada, que llama a las funciones del plugin.

El código siguiente muestra cómo se reemplaza la tabla de función `mysqlnd`:

    /* un lugar para almacenar la tabla de función original */
    struct st_mysqlnd_conn_methods org_methods;

    void minit_register_hooks(TSRMLS_D) {
      /* tabla de función activa */
      struct st_mysqlnd_conn_methods * current_methods
        = mysqlnd_conn_get_methods();

      /* guardar la tabla de función original */
      memcpy(&org_methods, current_methods,
        sizeof(struct st_mysqlnd_conn_methods));

      /* instalación de las nuevas métodos */
      current_methods->query = MYSQLND_METHOD(my_conn_class, query);
    }

Las manipulaciones de la tabla de función de conexión deben realizarse durante la inicialización del módulo (MINIT). La tabla de función es un recurso global compartido. En un entorno multihilo, con una compilación TSRM, la manipulación de un recurso global compartido durante un proceso de petición generalmente resultará en conflictos.

> Nota: No utilice ninguna lógica de tamaño fijo al manipular la tabla de función `mysqlnd`: las nuevas funciones pueden ser añadidas al final de la tabla de función. La tabla de función puede ser modificada en cualquier momento después.

Llamada a métodos padres

Si la tabla de función original se guarda, siempre es posible llamar a las entradas de la tabla de función original - los métodos padres.

En este caso, al igual que `Connection::stmt_init()`, es vital llamar al método padre antes de cualquier otra actividad en el método derivado.

    MYSQLND_METHOD(my_conn_class, query)(MYSQLND *conn,
      const char *query, unsigned int query_len TSRMLS_DC) {

      php_printf("my_conn_class::query(query = %s)\n", query);

      query = "SELECT 'query rewritten' FROM DUAL";
      query_len = strlen(query);

      return org_methods.query(conn, query, query_len); /* retorno con llamada al padre */
    }

Extender propiedades

Un objeto `mysqlnd` está representado por una estructura C. No es posible añadir un miembro a una estructura C en tiempo de ejecución. Los usuarios de objetos `mysqlnd` no pueden simplemente añadir propiedades a los objetos.

Datos arbitrarios (propiedades) pueden ser añadidos a los objetos `mysqlnd` utilizando una función apropiada de la familia `mysqlnd_plugin_get_plugin_<object>_data()`. Durante la asignación de un objeto, `mysqlnd` reserva un espacio al final del objeto para alojar un puntero `void *` hacia datos arbitrarios. `mysqlnd` reserva un espacio para un puntero `void *` por plugin.

La tabla siguiente muestra cómo calcular la posición de un puntero para un plugin específico:

Cálculo de punteros para mysqlnd
Dirección de memoria | Contenido
--- | ---
0 | Inicio de la estructura C del objeto mysqlnd
n | Fin de la estructura C del objeto mysqlnd
n + (m x sizeof(void*)) | void* hacia los datos del objeto del plugin m-ésimo

Si planea hacer subclases de los constructores de los objetos `mysqlnd`, lo cual está permitido, debe tener esto en cuenta.

El código siguiente muestra cómo se extienden propiedades:

    /* todos los datos que queremos asociar */
    typedef struct my_conn_properties {
      unsigned long query_counter;
    } MY_CONN_PROPERTIES;

    /* id del plugin */
    unsigned int my_plugin_id;

    void minit_register_hooks(TSRMLS_D) {
      /* obtenemos un ID único para el plugin */
      my_plugin_id = mysqlnd_plugin_register();
      /* snip - ver la extensión de la conexión: métodos */
    }

    static MY_CONN_PROPERTIES** get_conn_properties(const MYSQLND *conn TSRMLS_DC) {
      MY_CONN_PROPERTIES** props;
      props = (MY_CONN_PROPERTIES**)mysqlnd_plugin_get_plugin_connection_data(
        conn, my_plugin_id);
      if (!props || !(*props)) {
        *props = mnd_pecalloc(1, sizeof(MY_CONN_PROPERTIES), conn->persistent);
        (*props)->query_counter = 0;
      }
      return props;
    }

El desarrollador del plugin es responsable de la gestión de la memoria asociada a los datos del plugin.

Se recomienda el uso del asignador de memoria `mysqlnd` para los datos del plugin. Estas funciones son nombradas utilizando la siguiente convención: `mnd_*loc()`. El asignador `mysqlnd` tiene algunas características muy útiles, como la posibilidad de utilizar un asignador de depuración en una compilación no depurada.

Cuándo y cómo hacer una subclase
| ¿Cuándo hacer una subclase? | ¿Cada instancia tiene su propia tabla de funciones privada? | ¿Cómo hacer una subclase?
--- | --- | --- | ---
Conexión (MYSQLND) | MINIT | No | mysqlnd_conn_get_methods()
Juego de resultados (MYSQLND_RES) | MINIT o después | Sí | mysqlnd_result_get_methods() o método del objeto de manipulación de la tabla de funciones
Meta del juego de resultados (MYSQLND_RES_METADATA) | MINIT | No | mysqlnd_result_metadata_get_methods()
Consulta (MYSQLND_STMT) | MINIT | No | mysqlnd_stmt_get_methods()
Red (MYSQLND_NET) | MINIT o después | Sí | mysqlnd_net_get_methods() o método del objeto de manipulación de la tabla de funciones
Capa física (MYSQLND_PROTOCOL) | MINIT o después | Sí | mysqlnd_protocol_get_methods() o método del objeto de manipulación de la tabla de funciones

No debe manipular las tablas de funciones después de MINIT si no está permitido según la tabla anterior.

Algunas clases contienen un puntero hacia un método de la tabla de funciones. Todas las instancias de una clase de este tipo compartirán la misma tabla de funciones. Para evitar el caos, en particular en entornos multihilo, este tipo de tablas de funciones solo debe ser manipulado durante el MINIT.

Las otras clases utilizan una copia de la tabla de funciones global compartida. Esta copia se crea al mismo tiempo que el objeto. Cada objeto utiliza su propia tabla de funciones. Esto le da 2 opciones: puede manipular la tabla de funciones por defecto de un objeto durante el MINIT, y también puede afinar métodos de un objeto sin afectar a las otras instancias de la misma clase.

La ventaja del enfoque con una tabla de funciones compartida es el rendimiento. No es necesario copiar una tabla de funciones para cada objeto.

Estado del constructor
Tipo | Asignación, construcción, reinicialización | ¿Puede ser modificado? | Llamante
--- | --- | --- | ---
Conexión (MYSQLND) | mysqlnd_init() | No | mysqlnd_connect()
Juego de resultados (MYSQLND_RES) | Asignación: Connection::result_init() Reinicio y reinicialización durante: Result::use_result() Result::store_result | Sí, pero llamada al padre. | Connection::list_fields() Statement::get_result() Statement::prepare() (Meta-datos únicamente) Statement::resultMetaData()
Meta del juego de resultados (MYSQLND_RES_METADATA) | Connection::result_meta_init() | Sí, pero llamada al padre. | Result::read_result_metadata()
Consulta (MYSQLND_STMT) | Connection::stmt_init() | Sí, pero llamada al padre. | Connection::stmt_init()
Red (MYSQLND_NET) | mysqlnd_net_init() | No | Connection::init()
Capa física (MYSQLND_PROTOCOL) | mysqlnd_protocol_init() | No | Connection::init()

Se recomienda encarecidamente no reemplazar completamente un constructor. Los constructores realizan asignaciones de memoria. Las asignaciones de memoria son vitales para la API del plugin `mysqlnd` así como para la lógica del objeto `mysqlnd`. Si no se preocupa por las advertencias e insiste en reemplazar los constructores, debería al menos llamar al constructor padre antes de hacer cualquier cosa en su constructor.

A nivel de todas las advertencias, puede ser útil hacer subclases de los constructores. Los constructores son los lugares perfectos para modificar las tablas de funciones de los objetos con tablas de objetos no compartidas, como los juegos de resultados, la red o la capa física.

Estado del destructor
Tipo | ¿El método derivado debe llamar al padre? | Destructor
--- | --- | ---
Conexión | Sí, después de la ejecución del método | free_contents(), end_psession()
Juego de resultados | Sí, después de la ejecución del método | free_result()
Meta del juego de resultados | Sí, después de la ejecución del método | free()
Consulta | Sí, después de la ejecución del método | dtor(), free_stmt_content()
Red | Sí, después de la ejecución del método | free()
Capa física | Sí, después de la ejecución del método | free()

Los destructores son los lugares perfectos para liberar propiedades, `mysqlnd_plugin_get_plugin_<object>_data()`.

Los destructores listados pueden no ser los equivalentes a los métodos actuales `mysqlnd` que liberan el objeto mismo. Sin embargo, son los mejores lugares para liberar los datos de su plugin. Al igual que los constructores, puede reemplazar métodos completos pero no se recomienda. Si varios métodos están listados en la tabla anterior, debe modificar todos los métodos listados y liberar los datos de su plugin en el método llamado primero por `mysqlnd`.

El método recomendado para los plugins es simplemente modificar los métodos, liberar su memoria y llamar a la implementación del padre inmediatamente después.

## La API del plugin mysqlnd

A continuación se presenta la lista de funciones proporcionadas en la API plugin `mysqlnd`:

- mysqlnd_plugin_register()
- mysqlnd_plugin_count()
- mysqlnd_plugin_get_plugin_connection_data()
- mysqlnd_plugin_get_plugin_result_data()
- mysqlnd_plugin_get_plugin_stmt_data()
- mysqlnd_plugin_get_plugin_net_data()
- mysqlnd_plugin_get_plugin_protocol_data()
- mysqlnd_conn_get_methods()
- mysqlnd_result_get_methods()
- mysqlnd_result_meta_get_methods()
- mysqlnd_stmt_get_methods()
- mysqlnd_net_get_methods()
- mysqlnd_protocol_get_methods()

No hay una definición formal de qué es un plugin ni de cómo funciona un plugin.

Los componentes más frecuentemente encontrados en los mecanismos de plugin son:

- Un gestor de plugin
- Una API del plugin
- Los servicios aplicativos (o módulos)
- Las APIs de los servicios aplicativos (o APIs del módulo)

El concepto de un plugin `mysqlnd` utiliza estas características, así como otras joyas de arquitectura abierta.

Sin restricciones

Un plugin tiene acceso total a los trabajos internos de `mysqlnd`. No hay límites de seguridad ni restricciones. Todo puede ser sobrescrito para implementar algoritmos útiles o hostiles. Se recomienda desplegar solo plugins desde fuentes de confianza.

Tal como se ha discutido anteriormente, los plugins pueden utilizar libremente punteros. Estos punteros no están restringidos de ninguna manera, por lo que puede apuntar hacia los datos de otro plugin. Una simple posición aritmética puede ser utilizada para leer los datos de otro plugin.

Se recomienda escribir plugins cooperativos, y por lo tanto, siempre llamar al método padre. Los plugins deben cooperar siempre con `mysqlnd`.

Problemas: un ejemplo de encadenamiento y cooperación
Extensión | Puntero mysqlnd.query() | Pila de llamadas si se llama al padre
--- | --- | ---
ext/mysqlnd | mysqlnd.query() | mysqlnd.query
ext/mysqlnd_cache | mysqlnd_cache.query() | mysqlnd_cache.query() mysqlnd.query
ext/mysqlnd_monitor | mysqlnd_monitor.query() | mysqlnd_monitor.query() mysqlnd_cache.query() mysqlnd.query

En este escenario, un plugin de caché (`ext/mysqlnd_cache`) y un plugin de supervisión (`ext/mysqlnd_monitor`) están cargados. Ambos tienen una subclase de `Connection::query()`. El registro del plugin ocurre durante el `MINIT` utilizando la lógica mencionada anteriormente. PHP llama a las extensiones en un orden alfabético por defecto. Los plugins no están al tanto unos de otros y no pueden fijar dependencias.

Por defecto, los plugins llaman a la implementación del padre de la función de consulta en su versión de la función derivada.

Resumen de la extensión PHP

A continuación se presenta un resumen de lo que ocurre al utilizar un plugin de ejemplo, `ext/mysqlnd_plugin`, que expone la API C del plugin `mysqlnd` a PHP:

- Todas las aplicaciones PHP MySQL intentan establecer una conexión a la dirección 192.168.2.29
- La aplicación PHP utilizará `ext/mysql`, `ext/mysqli` o `PDO_MYSQL`. Estas 3 extensiones PHP MySQL utilizan `mysqlnd` para establecer la conexión a la dirección 192.168.2.29.
- `Mysqlnd` llama a su método de conexión, que ha sido subclaseado por `ext/mysqlnd_plugin`.
- `ext/mysqlnd_plugin` llama al método del espacio de usuario `proxy::connect()` registrado por el usuario.
- El espacio de usuario modifica el host de conexión de 192.168.2.29 a 127.0.0.1 y devuelve la conexión establecida por `parent::connect()`.
- `ext/mysqlnd_plugin` ejecuta el equivalente de `parent::connect(127.0.0.1)` llamando al método original de `mysqlnd` para establecer una conexión.
- `ext/mysqlnd` establece una conexión y devuelve el control a `ext/mysqlnd_plugin`. `ext/mysqlnd_plugin` también devuelve.
- Cualquier extensión PHP MySQL utilizada por la aplicación, recibe una conexión a 127.0.0.1. La extensión PHP MySQL devuelve el control a la aplicación PHP. El ciclo está cerrado.

## Cómo comenzar a compilar un plugin mysqlnd

Es importante recordar que un plugin `mysqlnd` es en sí mismo una extensión PHP.

El código siguiente muestra la estructura básica de una función MINIT utilizada en un plugin típico `mysqlnd`:

    /* my_php_mysqlnd_plugin.c */

     static PHP_MINIT_FUNCTION(mysqlnd_plugin) {
      /* globales, entradas ini, recursos, clases */

      /* registro del plugin mysqlnd */
      mysqlnd_plugin_id = mysqlnd_plugin_register();

      conn_m = mysqlnd_get_conn_methods();
      memcpy(org_conn_m, conn_m,
        sizeof(struct st_mysqlnd_conn_methods));

      conn_m->query = MYSQLND_METHOD(mysqlnd_plugin_conn, query);
      conn_m->connect = MYSQLND_METHOD(mysqlnd_plugin_conn, connect);
    }

    /* my_mysqlnd_plugin.c */

     enum_func_status MYSQLND_METHOD(mysqlnd_plugin_conn, query)(/* ... */) {
      /* ... */
    }
    enum_func_status MYSQLND_METHOD(mysqlnd_plugin_conn, connect)(/* ... */) {
      /* ... */
    }

Tarea de análisis: desde C hacia el espacio de usuario

     class proxy extends mysqlnd_plugin_connection {
      public function connect($host, ...) { .. }
    }
    mysqlnd_plugin_set_conn_proxy(new proxy());

Proceso:

1. PHP: el usuario registra una función de devolución de llamada para el plugin
2. PHP: el usuario llama a un método de la API PHP MySQL para conectarse a MySQL
3. C: ext/*mysql* llama al método mysqlnd
4. C: mysqlnd termina en ext/mysqlnd_plugin

5. C: ext/mysqlnd_plugin

   1. Llamada a la función de devolución de llamada del espacio de usuario
   2. O la función original `mysqlnd`, si el espacio de usuario no ha definido una función de devolución de llamada

Debe realizar las siguientes operaciones:

1. Escribir una clase "mysqlnd_plugin_connection" en C
2. Aceptar y registrar el objeto proxy a través de "mysqlnd_plugin_set_conn_proxy()"
3. Llamar a los métodos de proxy del espacio de usuario desde C (optimización - zend_interfaces.h)

Los métodos del objeto del espacio de usuario pueden ser llamados utilizando `call_user_function()`, o puede operar a un nivel por debajo del motor Zend y utilizar `zend_call_method()`.

Optimización: llamada a métodos desde C utilizando zend_call_method

El código siguiente muestra un prototipo para la función `zend_call_method`, obtenido de zend_interfaces.h.

     ZEND_API zval* zend_call_method(
      zval **object_pp, zend_class_entry *obj_ce,
      zend_function **fn_proxy, char *function_name,
      int function_name_len, zval **retval_ptr_ptr,
      int param_count, zval* arg1, zval* arg2 TSRMLS_DC
    );

La API Zend soporta 2 argumentos. Puede necesitar más, por ejemplo:

     enum_func_status (*func_mysqlnd_conn__connect)(
      MYSQLND *conn, const char *host,
      const char * user, const char * passwd,
      unsigned int passwd_len, const char * db,
      unsigned int db_len, unsigned int port,
      const char * socket, unsigned int mysql_flags TSRMLS_DC
    );

Para solucionar este problema, deberá hacer una copia de `zend_call_method()` y añadir funcionalidad para añadir parámetros. Puede lograr esto creando un conjunto de macros `MY_ZEND_CALL_METHOD_WRAPPER`.

Llamada al espacio de usuario PHP

El código siguiente muestra el método optimizado para realizar una llamada a una función del espacio de usuario desde C:

      /* my_mysqlnd_plugin.c */

    MYSQLND_METHOD(my_conn_class,connect)(
      MYSQLND *conn, const char *host /* ... */ TSRMLS_DC) {
      enum_func_status ret = FAIL;
      zval * global_user_conn_proxy = fetch_userspace_proxy();
      if (global_user_conn_proxy) {
        /* llamada al proxy del espacio de usuario */
        ret = MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, host, /*...*/);
      } else {
        /* o el método original mysqlnd = no hacer nada, ser transparente */
        ret = org_methods.connect(conn, host, user, passwd,
              passwd_len, db, db_len, port,
              socket, mysql_flags TSRMLS_CC);
      }
      return ret;
    }

Llamada al espacio de usuario: argumentos simples

    /* my_mysqlnd_plugin.c */

     MYSQLND_METHOD(my_conn_class,connect)(
      /* ... */, const char *host, /* ...*/) {
      /* ... */
      if (global_user_conn_proxy) {
        /* ... */
        zval* zv_host;
        MAKE_STD_ZVAL(zv_host);
        ZVAL_STRING(zv_host, host, 1);
        MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, zv_retval, zv_host /*, ...*/);
        zval_ptr_dtor(&zv_host);
        /* ... */
      }
      /* ... */
    }

Llamada al espacio de usuario: estructuras como argumentos

    /* my_mysqlnd_plugin.c */

    MYSQLND_METHOD(my_conn_class, connect)(
      MYSQLND *conn, /* ...*/) {
      /* ... */
      if (global_user_conn_proxy) {
        /* ... */
        zval* zv_conn;
        ZEND_REGISTER_RESOURCE(zv_conn, (void *)conn, le_mysqlnd_plugin_conn);
        MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, zv_retval, zv_conn, zv_host /*, ...*/);
        zval_ptr_dtor(&zv_conn);
        /* ... */
      }
      /* ... */
    }

El primer argumento de todas las funciones `mysqlnd` es un objeto C. Por ejemplo, el primer argumento de la función connect() es un puntero hacia `MYSQLND`. La estructura MYSQLND representa un objeto de conexión `mysqlnd`.

El puntero del objeto de conexión `mysqlnd` puede ser comparado a un puntero de archivo estándar I/O. Al igual que un puntero de archivo estándar I/O, un objeto de conexión `mysqlnd` debe ser vinculado al espacio de usuario utilizando una variable PHP de tipo recurso.

Desde C hacia el espacio de usuario, y luego de vuelta

     class proxy extends mysqlnd_plugin_connection {
      public function connect($conn, $host, ...) {
        /* "pre" hook */
        printf("Conexión al host = '%s'\n", $host);
        debug_print_backtrace();
        return parent::connect($conn);
      }

      public function query($conn, $query) {
        /* "post" hook */
        $ret = parent::query($conn, $query);
        printf("Consulta = '%s'\n", $query);
        return $ret;
      }
    }
    mysqlnd_plugin_set_conn_proxy(new proxy());

Los usuarios PHP deben poder llamar a la implementación del padre de un método sobrescrito.

Como resultado de una subclase, es posible redefinir únicamente los métodos seleccionados, y puede elegir tener acciones "pre" o "post".

Construcción de una clase: mysqlnd_plugin_connection::connect()

    /*  my_mysqlnd_plugin_classes.c */

     PHP_METHOD("mysqlnd_plugin_connection", connect) {
      /* ... simplificado! ... */
      zval* mysqlnd_rsrc;
      MYSQLND* conn;
      char* host; int host_len;
      if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "rs",
        &mysqlnd_rsrc, &host, &host_len) == FAILURE) {
        RETURN_NULL();
      }
      ZEND_FETCH_RESOURCE(conn, MYSQLND* conn, &mysqlnd_rsrc, -1,
        "Mysqlnd Connection", le_mysqlnd_plugin_conn);
      if (PASS == org_methods.connect(conn, host, /* simplificado! */ TSRMLS_CC))
        RETVAL_TRUE;
      else
        RETVAL_FALSE;
    }

- Introducción
- Instalación
- Configuración en tiempo de ejecución
- Incompatibilidades
- Conexiones persistentes
- Estadísticas
- Notas
- Gestión de la memoria
- API del plugin del controlador nativo MySQL
  - Comparación de los plugins mysqlnd con proxy MySQL
  - Obtener la API del plugin mysqlnd
  - Arquitectura del plugin del controlador nativo
  - La API del plugin mysqlnd
  - Cómo comenzar a compilar un plugin mysqlnd

- Visión general de los drivers PHP MySQL
  - Visión general de la terminología
  - Elegir una API
  - Elegir una biblioteca
  - Conceptos
- MySQLi — Extensión mysqli
  - Introducción
  - Guía de inicio rápido
  - Instalación/Configuración
  - La extensión mysqli y las conexiones persistentes
  - Constantes predefinidas
  - Notas
  - Resumen de las funciones de la extensión MySQLi
  - mysqli — La clase mysqli
  - mysqli_stmt — La clase mysqli_stmt
  - mysqli_result — La clase mysqli_result
  - mysqli_driver — La clase mysqli_driver
  - mysqli_warning — La clase mysqli_warning
  - mysqli_sql_exception — La clase mysqli_sql_exception
  - Funciones mysqli obsoletas y alias
  - Registro de cambios
- Mysql_xdevapi
  - Instalación/Configuración
  - Constantes predefinidas
  - Registro de cambios
  - Ejemplos
  - Funciones Mysql_xdevapi
  - mysql_xdevapi\BaseResult — Interfaz BaseResult
  - mysql_xdevapi\Client — La clase Client
  - mysql_xdevapi\Collection — Clase Collection
  - mysql_xdevapi\CollectionAdd — Clase CollectionAdd
  - mysql_xdevapi\CollectionFind — Clase CollectionFind
  - mysql_xdevapi\CollectionModify — Clase CollectionModify
  - mysql_xdevapi\CollectionRemove — Clase CollectionRemove
  - mysql_xdevapi\ColumnResult — Clase ColumnResult
  - mysql_xdevapi\CrudOperationBindable — Interfaz CrudOperationBindable
  - mysql_xdevapi\CrudOperationLimitable — Interfaz CrudOperationLimitable
  - mysql_xdevapi\CrudOperationSkippable — Interfaz CrudOperationSkippable
  - mysql_xdevapi\CrudOperationSortable — Interfaz CrudOperationSortable
  - mysql_xdevapi\DatabaseObject — Interfaz DatabaseObject
  - mysql_xdevapi\DocResult — Clase DocResult
  - mysql_xdevapi\Exception — Clase Exception
  - mysql_xdevapi\Executable — Interfaz Executable
  - mysql_xdevapi\ExecutionStatus — Clase ExecutionStatus
  - mysql_xdevapi\Expression — Clase Expression
  - mysql_xdevapi\Result — Clase Result
  - mysql_xdevapi\RowResult — Clase RowResult
  - mysql_xdevapi\Schema — Clase Schema
  - mysql_xdevapi\SchemaObject — Interfaz SchemaObject
  - mysql_xdevapi\Session — Clase Session
  - mysql_xdevapi\SqlStatement — Clase SqlStatement
  - mysql_xdevapi\SqlStatementResult — Clase SqlStatementResult
  - mysql_xdevapi\Statement — Clase Statement
  - mysql_xdevapi\Table — Clase Table
  - mysql_xdevapi\TableDelete — Clase TableDelete
  - mysql_xdevapi\TableInsert — Clase TableInsert
  - mysql_xdevapi\TableSelect — Clase TableSelect
  - mysql_xdevapi\TableUpdate — Clase TableUpdate
  - mysql_xdevapi\Warning — Clase Warning
- MySQL (Original) — API MySQL original
  - Instalación/Configuración
  - Registro de cambios
  - Constantes predefinidas
  - Ejemplos
  - Funciones MySQL
- Mysqlnd — Controlador Nativo de MySQL
  - Introducción
  - Instalación
  - Configuración en tiempo de ejecución
  - Incompatibilidades
  - Conexiones persistentes
  - Estadísticas
  - Notas
  - Gestión de la memoria
  - API del plugin del controlador nativo MySQL

# Oracle OCI8

# Introducción

Advertencia

Esta extensión está SEPARADA a partir de PHP 8.4.0.

Estas funciones permiten acceder a las bases de datos Oracle. Soportan las comandos SQL y PL/SQL. Las funciones básicas incluyen el control de transacción, la ligadura de variables PHP con contenedores Oracle, el soporte de los tipos de grandes objetos (LOB) y de las colecciones. Las funciones de extensibilidad de Oracle, tales como Database Resident Connection Pooling (DRCP) y el caché de resultados también son soportadas.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Pruebas
- Configuración en tiempo de ejecución

## Requerimientos

OCI8 3.0 está incluida con PHP 8. También está disponible desde » PECL. Para PHP 7, utilice OCI8 2.2 desde » PECL. OCI8 requiere Oracle 10g o bibliotecas cliente posteriores.

Si la base de datos Oracle está en la misma máquina que PHP, el software de base de datos ya contiene las bibliotecas y encabezados necesarios. Cuando PHP está en una máquina diferente, utilice las bibliotecas gratuitas » Oracle Instant Client.

Para utilizar Oracle Instant Client, instale el archivo comprimido ZIP `Basic` o `Basic Light` de Oracle Instant Client, el paquete RPM, o el paquete DMG. Al compilar OCI8 desde el código fuente, instale también el `SDK` de Instant Client.

Debe ejecutar PHP con la misma versión o una versión más reciente de las bibliotecas cliente de Oracle utilizadas para construir OCI8.

> Nota:

> La interoperabilidad estándar de red cliente-servidor de Oracle permite conexiones entre diferentes versiones de Oracle Client y Oracle Database. Para configuraciones certificadas, consulte la documentación Oracle Support ID ID 207303.1. En resumen, Oracle Client 19, 18 y 12.2 pueden conectarse a Oracle Database 11.2 o superior. Oracle Client 12.1 puede conectarse a Oracle Database 10.2 o superior. Oracle Client 11.2 puede conectarse a Oracle Database 9.2 o superior.

> Nota:

> El soporte de todas las funcionalidades de OCI8 solo está disponible al utilizar las versiones más recientes de las bibliotecas cliente de Oracle así como la base de datos más reciente.

## Instalación

## Configuración de PHP con OCI8

Revísese la sección anterior sobre los Requisitos previos antes de configurar OCI8.

Antes de iniciar el servidor web, OCI8, típicamente, requiere varias variables de entorno (ver a continuación) para localizar las bibliotecas, para apuntar a archivos de configuración, y para definir algunas propiedades básicas como el juego de caracteres utilizado por las bibliotecas OCI8. Las variables deben ser definidas antes del inicio de cualquier proceso PHP.

El binario PHP debe ser enlazado con las mismas (o versiones más recientes) de las bibliotecas Oracle para las cuales ha sido configurado. Por ejemplo, si se compila OCI8 con las bibliotecas Oracle 19, entonces PHP también debe ser desplegado y ejecutado con las bibliotecas Oracle 19. Las aplicaciones PHP pueden conectarse a otras versiones de bases de datos Oracle, sabiendo que Oracle contiene compatibilidades de versiones de los diferentes clientes - servidores.

## Instalación de OCI8 desde PECL utilizando el comando pecl

La extensión OCI8 puede ser añadida a una instalación PHP existente utilizando el repositorio » PECL.

- Si se encuentra detrás de un firewall, defínase el proxy de PEAR, por ejemplo:

      pear config-set http_proxy http://my-proxy.example.com:80/

- Ejecútese:

      pecl install oci8

  Para PHP 7, utilícese `pecl install oci8-2.2.0`.

- Cuando se le solicite, introdúzcase el valor de `$ORACLE_HOME` o `instantclient,/ruta/al/directorio/instant/client/lib`.

  Nota: No se introduzcan nombres de variables como `$ORACLE_HOME` o `$HOME` ya que `pecl` no los expandirá. En su lugar, introdúzcase una ruta expandida, por ejemplo `/opt/oracle/product/19c/dbhome_1` o `instantclient,/Users/monnom/Descargas/instantclient_19_8`.

- Si se obtiene un error `oci8_dtrace_gen.h: No existe el archivo o directorio`, esto significa que PHP ha sido compilado con DTrace Dynamic Tracing activado. Instálese utilizando el comando:

      $ export PHP_DTRACE=yes
      $ pecl install oci8

- Modifíquese el archivo php.ini y añádase la línea:

      extension=oci8.so

  Asegúrese de que la directiva php.ini extension_dir está definida en el directorio en el cual oci8.so ha sido instalado.

## Instalación de OCI8 desde PECL utilizando phpize

Para instalar OCI8 en una instalación PHP existente cuando el comando `pecl` no está disponible, descárguese manualmente el paquete OCI8 » PECL, por ejemplo oci8-3.0.0.tgz.

- Extraer el paquete:

      tar -zxf oci8-3.0.0.tgz
      cd oci8-3.0.0

- Preparar el paquete:

      phpize

- Configurar el paquete utilizando `$ORACLE_HOME` o Instant Client.

      ./configure -with-oci8=shared,$ORACLE_HOME

  o

      ./configure -with-oci8=shared,instantclient,/ruta/a/instant/client/lib

- Instalar el paquete:

      make install

- Si se obtiene un error `oci8_dtrace_gen.h: No existe el archivo o directorio`, esto significa que PHP ha sido compilado con DTrace Dynamic Tracing activado. Ejecútese nuevamente los comandos `configure` y `make` después de haber definido esta variable de entorno:

      $ export PHP_DTRACE=yes

- Modifíquese el archivo php.ini y añádase la línea:

      extension=oci8.so

  Asegúrese de que la directiva php.ini extension_dir está configurada en el directorio en el cual oci8.so ha sido instalado.

## Instalación de OCI8 como extensión compartida durante la compilación de PHP

Si se compila PHP a partir del código fuente, la opción de configuración `shared` puede ser utilizada para construir OCI8 como una biblioteca compartida que puede ser cargada dinámicamente en PHP. La construcción de una extensión compartida permite a OCI8 ser fácilmente actualizado sin afectar al resto de PHP.

Configúrese OCI8 utilizando una de las siguientes opciones de configuración.

- Si se utilizan las bibliotecas gratuitas » Oracle Instant Client, hágase lo siguiente:

      ./configure --with-oci8=shared,instantclient,/ruta/a/instant/client/lib

  Si Instant Client 12.2 (o una versión anterior) está instalado a partir de archivos ZIP, asegúrese de crear primero el enlace simbólico a la biblioteca, por ejemplo `ln -s libclntsh.so.12.1 libclntsh.so`.

  Si se utiliza una instalación basada en RPM de Oracle Instant Client, la línea de configuración se verá así:

      ./configure --with-oci8=shared,instantclient,/usr/lib/oracle/<version>/client/lib

  Por ejemplo, --with-oci8=shared,instantclient,/usr/lib/oracle/19.9/client/lib

- Si se utiliza una base de datos Oracle o una instalación completa de Oracle Client, procedase de la siguiente manera:

      ./configure --with-oci8=shared,$ORACLE_HOME

  Asegúrese de que el usuario del servidor web (`nobody`, `www`) tiene acceso a las bibliotecas, a los archivos de inicialización y al archivo tnsnames.ora (si se utiliza) bajo el directorio `$ORACLE_HOME`. Con Oracle 10gR2, puede que sea necesario ejecutar la utilidad $ORACLE_HOME/install/changePerm.sh para dar acceso al directorio.

Después de la configuración, sigase el procedimiento habitual de compilación de PHP, por ejemplo make install. La extensión compartida OCI8 oci8.so será creada. Puede ser necesario moverla manualmente al directorio de extensiones PHP, especificado por la opción extension_dir en su archivo php.ini.

Para completar la instalación de OCI8, modifíquese el archivo php.ini y añádase la línea:

    extension=oci8.so

## Instalación de OCI8 como extensión compilada estáticamente durante la compilación de PHP

Si se compila PHP a partir del código fuente, puede configurarse PHP para incluir OCI8 como una extensión estática utilizando una de las siguientes opciones de configuración.

- Si se utiliza Oracle Instant Client, hágase lo siguiente:

      ./configure --with-oci8=instantclient,/ruta/a/instant/client/lib

- Si se utiliza una base de datos Oracle o una instalación completa del cliente Oracle, hágase lo siguiente:

      ./configure --with-oci8=$ORACLE_HOME

Después de la configuración, sigase el procedimiento habitual de construcción de PHP, por ejemplo make install. Después de una compilación exitosa, no es necesario añadir oci8.so a su php.ini. No se requiere ningún paso adicional de construcción.

## Instalación de OCI8 bajo Windows

La biblioteca OCI8 puede ser añadida a una instalación existente de PHP utilizando las DLL del repositorio » PECL o las bibliotecas situadas en el directorio `ext` de su instalación PHP.

Con las bibliotecas Oracle 12c (o posteriores), descoméntese una de las siguientes líneas en su archivo php.ini `extension=php_oci8_12c.dll` o `extension=php_oci8_11g.dll`, o bien `extension=php_oci8.dll`. Solo una de estas DLLs debe estar activa al mismo tiempo. Las DLLs con versiones superiores pueden contener más funcionalidades. Todas las DLLs pueden no estar disponibles para todas las versiones de PHP. Asegúrese de que la opción extension_dir está definida en la carpeta que contiene las extensiones DLL de PHP.

Si se utiliza el cliente Oracle Instant, defínase la variable de entorno PATH del sistema a la carpeta que contiene las bibliotecas Oracle.

## Definición del entorno Oracle

Antes de utilizar esta extensión, asegúrese de que las variables de entorno Oracle están correctamente definidas para el usuario que ejecuta el servidor Web. Si su servidor Web se inicia automáticamente al arrancar el servidor, entonces asegúrese también de la correcta configuración de la variable de entorno utilizada en ese momento.

> Nota:

> No se definan las variables de entorno Oracle utilizando la función putenv() en sus scripts PHP, ya que las bibliotecas Oracle son cargadas e inicializadas antes de la ejecución de su script. Las variables definidas con putenv() podrían entrar en conflicto y provocar tanto fallos como comportamientos totalmente inesperados. Algunas funciones pueden reaccionar normalmente, otras pueden provocar errores. Las variables deben ser definidas antes del inicio del servidor.

En los sistemas Red Hat Linux y sus variantes, debe exportarse las variables al final del archivo /etc/sysconfig/httpd. En otros sistemas que utilicen Apache 2, debe utilizarse el script envvars que se encontrará en el directorio bin de Apache. Otra opción consiste en utilizar la directiva `SetEnv` del archivo httpd.conf, pero esto puede no ser suficiente en algunos sistemas.

Para verificar si las variables de entorno han sido definidas correctamente, utilícese la función phpinfo() y prestese atención a la sección Environment (y no a la sección Apache Environment); debe contener todas las variables definidas.

Las variables que se necesitan están incluidas en la tabla siguiente. Consúltese la documentación Oracle para más información sobre todas las variables.

Variables de entorno Oracle comunes
Nombre | Propósito
--- | ---
ORACLE_HOME | Ruta al directorio que contiene el software de base de datos Oracle. No se defina esta variable si se utiliza el cliente Oracle Instant. De hecho, no es necesaria pero puede causar problemas durante la instalación.
ORACLE_SID | El nombre de la base de datos en la máquina local. No es necesario definirla si se utiliza el cliente Oracle Instant, o entonces, pasarla siempre como argumento de conexión a la función oci_connect().
LD_LIBRARY_PATH | Defínase esta variable (o su equivalente en la plataforma actual, como `LIBPATH`, o `SHLIB_PATH`) como la ruta a las bibliotecas Oracle, por ejemplo $ORACLE_HOME/lib o /usr/lib/oracle/19/client/lib. Esta variable no es necesaria si las bibliotecas son localizadas por un mecanismo de búsqueda diferente, como con ldconfig o con `LD_PRELOAD` en lugar de `LD_LIBRARY_PATH`.
NLS_LANG | Es la variable principal para definir el juego de caracteres y las informaciones de globalización utilizadas por las bibliotecas Oracle.
ORA_SDTZ | Define el desplazamiento horario a utilizar por las sesiones Oracle.
TNS_ADMIN | Ruta al directorio que contiene los archivos de configuración Oracle Net Services (tnsnames.ora y sqlnet.ora). Innecesario si la cadena de conexión utilizada por la función oci_connect() está en formato de conexión fácil como `localhost/XE`. También innecesario si los archivos de configuración de red están en ubicaciones por defecto como /usr/lib/oracle/VERSION/client/lib/network/admin, $ORACLE_HOME/network/admin o /etc.

Existen otras variables de entorno Oracle menos frecuentemente utilizadas, como `TWO_TASK`, `ORA_TZFILE`, así como las diversas variables de globalización como `NLS*` y `ORA_NLS_*`.

## En caso de problemas

El problema más común durante la instalación de OCI8 es haber configurado incorrectamente el juego de variables de entorno. Es un problema típico cuando se recibe un mensaje de error al utilizar las funciones oci_connect() o oci_pconnect(). El error puede ser un error puramente PHP como Llamada a la función no definida oci_connect(), un error Oracle como ORA-12705 o incluso un fallo brusco de Apache. Verifíquese el contenido de los archivos de registro de Apache durante su inicio y refiérase a las secciones anteriores para resolver el problema.

Mientras que los errores de red como ORA-12154 o ORA-12514 indican un problema de nombramiento de red o un problema de configuración, muy a menudo, la causa principal es que el entorno PHP no está correctamente definido y que las bibliotecas Oracle son incapaces de encontrar el archivo de configuración tnsnames.ora.

En Windows, tener varias versiones de Oracle en la misma máquina puede hacer que la instalación falle fácilmente a menos que se asegure de que PHP no está utilizando únicamente la versión correcta de Oracle.

Una utilidad que permite examinar las bibliotecas buscadas y cargadas puede ayudar a resolver este tipo de problema, especialmente en Windows.

> Nota: Si el servidor Web no arranca o falla al inicio

> Verifíquese que Apache está enlazado con la biblioteca pthread:

>     # ldd /www/apache/bin/httpd
>       libpthread.so.0 => /lib/libpthread.so.0 (0x4001c000)
>       libm.so.6 => /lib/libm.so.6 (0x4002f000)
>       libcrypt.so.1 => /lib/libcrypt.so.1 (0x4004c000)
>       libdl.so.2 => /lib/libdl.so.2 (0x4007a000)
>       libc.so.6 => /lib/libc.so.6 (0x4007e000)
>       /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)

> Si la biblioteca libpthread no está listada, reinstálese Apache:

>     # cd /usr/src/apache_1.3.xx
>     # make clean
>     # LIBS=-lpthread ./config.status
>     # make
>     # make install

> Tenga en cuenta que en sistemas como UnixWare, la biblioteca se llama libthread en lugar de libpthread. PHP y Apache deben ser configurados con EXTRA_LIBS=-lthread.

## Pruebas

El conjunto de pruebas de OCI8 está en el directorio ext/oci8/tests. Después de ejecutar las pruebas de OCI8, este directorio también contendrá los registros de cualquier fallo.

Antes de ejecutar las pruebas de PHP, edite details.inc y establezca $user, $password y la cadena de conexión $dbase. El conjunto de pruebas de OCI8 ha sido desarrollado usando la cuenta `SYSTEM`. Algunas pruebas fallarán si el usuario de las mismas no tiene permisos equivalentes.

Si se está comprobando Oracle Database Resident Connection Pooling, establezca $test_drcp a `true` y asegúrese de que la cadena de conexión utiliza un servidor de la agrupación DRCP apropiado.

Una alternativa a editar details.inc es el establecimiento de variables de entorno, por ejemplo:

        $ export PHP_OCI8_TEST_USER=system
        $ export PHP_OCI8_TEST_PASS=oracle
        $ export PHP_OCI8_TEST_DB=localhost/XE
        $ export PHP_OCI8_TEST_DRCP=FALSE

Observe que en algunas shell, estas variables no se propagan correctamente por proceso de PHP y que las pruebas fallarán al conectar si se utiliza este método.

Lo siguiente es establecer cualquier entorno necesario para la base de datos de Oracle. Con Oracle 10gR2 XE, haga lo siguiente:

        $ . /usr/lib/oracle/xe/app/oracle/product/10.2.0/server/bin/oracle_env.sh

Con Oracle 11gR2 XE:

        $ . /u01/app/oracle/product/11.2.0/xe/bin/oracle_env.sh

Para otras versiones de la base de datos de Oracle, haga:

        $ . /usr/local/bin/oraenv

Algunas shells requieren que php.ini contenga `E` en el parámetro variables_order, por ejemplo:

        variables_order = "EGPCS"

Ejecute todas las pruebas de PHP con:

        $ cd your_php_src_directory
        $ make test

o ejecute únicamente las pruebas de OCI8 con

        $ cd your_php_src_directory
        $ make test TESTS=ext/oci8

Cuando hayan finalizado las pruebas, revise cualquier fallo. En sistemas lentos, algunas pruebas podrían tomar más tiempo que el tiempo de espera de prueba predeterminado de run-tests.php. Para corregir esto, establezca la variable de entorno `TEST_TIMEOUT` a un número mayor de segundos.

En máquinas rápidas con una base de datos local configurada para una carga ligera (p.ej. Oracle 11gR2 XE), algunas pruebas podrían ocasionar los errores ORA-12516 u ORA-12520. Para evitarlo, aumente el parámetro `PROCESSES` de la base de datos siguiendo estos pasos:

Conéctese como propietario del software de Oracle:

        $ su - oracle

Establezca el entorno de Oracle necesario con oracle_env.sh u oraenv, tal como está descrito arriba.

Inicie la herramienta de línea de comandos SQL*Plus y aumente `PROCESSES`

        $ sqlplus / as sysdba
        SQL> alter system set processes=100 scope=spfile

Reinicie la base de datos:

        SQL> startup force

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración OCI8
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
oci8.connection_class | "" | `INI_ALL` |
oci8.default_prefetch | "100" | `INI_SYSTEM` |
oci8.events | Off | `INI_SYSTEM` |
oci8.max_persistent | "-1" | `INI_SYSTEM` |
oci8.old_oci_close_semantics | Off | `INI_SYSTEM` | Deprecado a partir de PHP 8.1.0.
oci8.persistent_timeout | "-1" | `INI_SYSTEM` |
oci8.ping_interval | "60" | `INI_SYSTEM` |
oci8.prefetch_lob_size | "0" | `INI_SYSTEM` | Disponible a partir de PECL OCI8 3.2.
oci8.privileged_connect | Off | `INI_SYSTEM` |
oci8.statement_cache_size | "20" | `INI_SYSTEM` |

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`oci8.connection_class` string

  El texto definido por el usuario es utilizado por las conexiones del pool de conexiones residente de la base de datos Oracle 11g para particionar el pool. Esto permite a las conexiones persistentes OCI8 de una aplicación reutilizar las sesiones a la base de datos desde un script anterior, permitiendo así una mejor eficiencia. Cuando una aplicación utiliza un proceso de base de datos previamente utilizado con una clase de conexión diferente, las configuraciones de la sesión, como el formato de fecha por defecto de Oracle, serán reinicializadas. Este comportamiento permite evitar compartir accidentalmente información entre las diferentes aplicaciones.

  El valor puede ser definido en tiempo de ejecución gracias a la función ini_set(), llamada antes de la conexión.

  Para utilizar DRCP, OCI8 debe estar vinculado con las bibliotecas Oracle 11g y la base de datos debe ser Oracle 11g. El pool de conexión debe estar activado en la base de datos, la opción de configuración `oci8.connection_class` debe valer la misma cadena para todos los servidores web utilizando la misma aplicación, y la cadena de conexión OCI8 debe especificar el uso de un servidor con pool.

`oci8.default_prefetch` int

  Esta opción define el número por defecto de líneas adicionales que serán recuperadas y almacenadas en caché automáticamente cada vez que se realice una consulta de bajo nivel recuperando datos desde la base de datos. Definir un valor de `0` permite desactivar esta funcionalidad.

  El valor de pre-carga no altera el número de líneas que funciones como oci_fetch_array() devolverán al usuario; la pre-carga y el almacenamiento en caché de líneas es gestionado internamente por OCI8.

  El valor puede ser definido para cada consulta, ejecutando la función oci_set_prefetch() antes de ejecutar la consulta.

  Al utilizar Oracle 12c o posterior, el valor de pre-carga definido por PHP puede ser sobreescrito por el archivo de configuración del cliente Oracle: `oraaccess.xml`. Consulte la documentación de Oracle para más información.

  > Nota: Si se introduce un valor demasiado grande, esto puede conducir a una mejora de las prestaciones, a costa del uso de memoria. Para consultas que devuelven un gran número de datos, la ganancia de rendimiento puede ser realmente significativa.

`oci8.events` bool

  Definir esta opción a `On` permite a PHP ser notificado de los eventos de base de datos FAN (`Fast Application Notification`).

  Sin FAN, cuando una instancia de la base de datos o un nodo de máquinas falla bruscamente, las aplicaciones PHP pueden bloquearse esperando una respuesta de la base de datos, hasta el final del tiempo de espera TCP. Con los eventos FAN, las aplicaciones PHP son notificadas rápidamente de los errores que afectan a las conexiones a la base de datos. La extensión OCI8 limpiará las conexiones inutilizables en la caché de conexiones persistentes.

  Cuando se utiliza `On` como valor, la base de datos también debe estar configurada para emitir los eventos FAN.

  El soporte de FAN está disponible cuando OCI8 está vinculado a bibliotecas Oracle 10gR2 (y posteriores) y conectado a una base de datos Oracle 10gR2 (y posteriores).

`oci8.max_persistent` int

  El número máximo de conexiones persistentes OCI8 por proceso PHP. Definir esta opción a -1 significa que no hay límite.

`oci8.old_oci_close_semantics` bool

  Esta opción controla el comportamiento de la función oci_close(). Activar esta opción significa que oci_close() no hará nada; la conexión no será cerrada hasta que finalice el script. Esto es únicamente para asegurar la compatibilidad ascendente. Si se piensa que es necesario activar esta opción, se recomienda encarecidamente eliminar las llamadas a la función oci_close() de la aplicación en lugar de activar esta opción.

`oci8.persistent_timeout` int

  El tiempo máximo (en segundos) que un proceso PHP dado está autorizado a mantener una conexión persistente. Definir esta opción a -1 significa que las conexiones persistentes serán siempre mantenidas mientras el proceso PHP no termine o la conexión sea explícitamente cerrada usando la función oci_close().

  > Nota: En PHP, la expiración de los recursos persistentes no produce ninguna alerta. Ocurre cuando PHP termina un script y verifica el timestamp del último uso del recurso. Además, las conexiones persistentes solo pueden ser cerradas durante alguna actividad (no necesaria en OCI8) en el proceso PHP. Si hay más de un proceso PHP, entonces cada uno de ellos debe ser activado manualmente para iniciar la expiración de sus propios recursos. La introducción del pool de conexiones persistentes (DRCP) en Oracle 11g resuelve los problemas de memoria y recursos, que las opciones `oci8.max_persistent` y `oci8.persistent_timeout` intentaron resolver previamente.

`oci8.ping_interval` int

  El tiempo máximo (en segundos) a esperar antes de enviar un ping durante oci_pconnect(). Cuando se define a 0, las conexiones persistentes serán verificadas en cada reutilización. Para desactivar completamente los pings, defina esta opción a -1.

  > Nota: Desactivar los pings hace que las llamadas a oci_pconnect() sean altamente rentables, pero impide a PHP detectar problemas de conexión, como problemas de red, o si el servidor Oracle ha sido apagado desde la conexión de PHP, hasta que la conexión no sea utilizada más tarde en el script. Consulte la documentación de la función oci_pconnect() para más información.

`oci8.prefetch_lob_size` int

  Se trata de un parámetro de ajuste que afecta al almacenamiento en memoria interna de los datos LOB. Aumentar este valor puede mejorar el rendimiento de recuperación de pequeños LOB reduciendo los intercambios entre PHP y la base de datos. El uso de la memoria cambiará.

  El valor afecta a los LOB devueltos como instancias OCILob así como a aquellos devueltos usando `OCI_RETURN_LOBS`.

  El valor puede ser definido por instrucción con oci_set_prefetch_lob() antes de ejecutar la instrucción.

  > Nota: Para usar con Oracle Database 12.2 o posterior.

`oci8.privileged_connect` bool

  Esta opción activa las conexiones privilegiadas utilizando derechos externos (`OCI_SYSOPER`, `OCI_SYSDBA`).

  > Nota: Definir este valor a `On` permite a los scripts del servidor web ejecutando los privilegios de usuario del sistema apropiados conectarse a la base de datos utilizando estos privilegios, sin necesidad de proporcionar una contraseña a la base de datos. Esto puede tener consecuencias en términos de seguridad.

`oci8.statement_cache_size` int

  Esta opción activa la caché de consultas, y especifica el número de consultas a almacenar en caché. Para desactivar la caché de consultas, defina esta opción a 0.

  La caché de consultas permite no tener que transmitir el texto de la consulta a la base de datos, así como no tener que transmitir metadatos sobre la consulta a PHP. Esto permite aumentar significativamente el rendimiento del sistema en las aplicaciones, reutilizando las consultas durante toda la vida de la conexión. Los "cursores" de base de datos también pueden ayudar si se parte de la base de que las consultas serán reutilizadas.

  Defina este valor al tamaño de su conjunto de consultas comunes utilizadas por su aplicación. Definir un valor demasiado pequeño puede hacer que sus consultas sean eliminadas de la caché antes de que sean utilizadas.

  Esta opción es más utilizada con las conexiones persistentes.

  Con la base de datos Oracle 12c, este valor puede ser sobreescrito y ajustado automáticamente por el archivo `oraaccess.xml` del cliente Oracle. Consulte la documentación de Oracle para más explicaciones.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

Métodos y funciones OCI8
Constante | Descripción
--- | ---
`OCI_ASSOC` | Utilizado con oci_fetch_all() y oci_fetch_array() para recuperar los resultados en un array asociativo.
`OCI_BOTH` | Utilizado con oci_fetch_all() y oci_fetch_array() para recuperar los resultados en un array asociativo e indexado numéricamente.
`OCI_COMMIT_ON_SUCCESS` | Modo de ejecución de comandos para oci_execute(). El comando se valida automáticamente tras el éxito de la consulta.
`OCI_CRED_EXT` | Utilizado con oci_connect() para la identificación en un servidor Oracle externo o en el sistema operativo.
`OCI_DEFAULT` | Ver la constante `OCI_NO_AUTO_COMMIT`.
`OCI_DESCRIBE_ONLY` | Modo de ejecución de comandos para oci_execute(). Utilícelo si no desea ejecutar el comando, pero obtener descripciones.
`OCI_EXACT_FETCH` | Obsoleto. Modo de lectura de resultados. Utilizado cuando las aplicaciones conocen de antemano el número de líneas que se necesitarán leer. Este modo desactiva la lectura anticipada de Oracle versión 8 y posteriores. El cursor se anula una vez que se alcanza el número de líneas a leer, lo que reduce los recursos consumidos en el servidor.
`OCI_FETCHSTATEMENT_BY_COLUMN` | Modo por defecto de oci_fetch_all().
`OCI_FETCHSTATEMENT_BY_ROW` | Modo alternativo para oci_fetch_all().
`OCI_LOB_BUFFER_FREE` | Utilizado con OCILob::flush para liberar los buffers utilizados.
`OCI_NO_AUTO_COMMIT` | Modo de ejecución de la consulta para oci_execute(). La transacción no se valida automáticamente al utilizar este modo. Para mayor claridad en su código, utilice este valor en lugar del antiguo valor `OCI_DEFAULT`.
`OCI_NUM` | Utilizado con oci_fetch_all() y oci_fetch_array() para leer un array enumerado.
`OCI_RETURN_LOBS` | Utilizado con oci_fetch_array() para obtener la valor del LOB en lugar del puntero.
`OCI_RETURN_NULLS` | Utilizado con oci_fetch_array() para obtener elementos vacíos, si el valor del campo es `null`.
`OCI_SEEK_CUR` | Utilizado con OCILob::seek para definir la posición.
`OCI_SEEK_END` | Utilizado con OCILob::seek para definir la posición.
`OCI_SEEK_SET` | Utilizado con OCILob::seek para definir la posición.
`OCI_SYSDATE` | Obsoleto.
`OCI_SYSDBA` | Utilizado con oci_connect() para conectarse como SYSDBA utilizando credenciales externas (oci8.privileged_connect debe estar activado para utilizar esta constante).
`OCI_SYSOPER` | Utilizado con oci_connect() para conectarse como SYSOPER utilizando credenciales externas (oci8.privileged_connect debe estar activado para utilizar esta constante).
`OCI_TEMP_BLOB` | Utilizado con OCILob::writeTemporary para indicar explícitamente que debe crearse un BLOB temporal.
`OCI_TEMP_CLOB` | Utilizado con OCILob::writeTemporary para indicar explícitamente que debe crearse un CLOB temporal.

Tipos definidos y vinculados OCI8
Constante | Descripción
--- | ---
`OCI_B_BFILE` | Utilizado con oci_bind_by_name() para vincular BFILEs.
`OCI_B_BIN` | Utilizado con oci_bind_by_name() para vincular valores brutos (RAW).
`OCI_B_BLOB` | Utilizado con oci_bind_by_name() para vincular BLOB.
`OCI_B_BOL` | Utilizado con oci_bind_by_name() para vincular una variable booleana PL/SQL.
`OCI_B_CFILEE` | Utilizado con oci_bind_by_name() para vincular CFILEs.
`OCI_B_CLOB` | Utilizado con oci_bind_by_name() para vincular CLOB.
`OCI_B_CURSOR` | Utilizado con oci_bind_by_name() para vincular cursores, previamente asignados con oci_new_descriptor().
`OCI_B_INT` | Utilizado con oci_bind_array_by_name() para vincular arrays de enteros.
`OCI_B_NTY` | Utilizado con oci_bind_by_name() para vincular nombres de tipos de datos.
`OCI_B_NUM` | Utilizado con oci_bind_array_by_name() para vincular arrays de números.
`OCI_B_ROWID` | Utilizado con oci_bind_by_name() para vincular ROWID.
`SQLT_AFC` | Utilizado con oci_bind_array_by_name() para vincular arrays de CHAR.
`SQLT_AVC` | Utilizado con oci_bind_array_by_name() para vincular arrays de VARCHAR2.
`SQLT_BDOUBLE` | No soportado.
`SQLT_BFILEE` | Idéntico a `OCI_B_BFILE`.
`SQLT_BFLOAT` | No soportado.
`SQLT_BIN` | Idéntico a `OCI_B_BIN`.
`SQLT_BLOB` | Idéntico a `OCI_B_BLOB`.
`SQLT_BOL` | Idéntico a `OCI_B_BOL`.
`SQLT_CFILEE` | Idéntico a `OCI_B_CFILEE`.
`SQLT_CHR` | Utilizado con oci_bind_array_by_name() para vincular arrays de VARCHAR2. También utilizado con oci_bind_by_name().
`SQLT_CLOB` | Idéntico a `OCI_B_CLOB`.
`SQLT_FLT` | Utilizado con oci_bind_array_by_name() para vincular arrays de FLOAT.
`SQLT_INT` | Idéntico a `OCI_B_INT`.
`SQLT_LBI` | Utilizado con oci_bind_by_name() para vincular valores LONG RAW.
`SQLT_LNG` | Utilizado con oci_bind_by_name() para vincular valores LONG.
`SQLT_LVC` | Utilizado con oci_bind_array_by_name() para vincular arrays de LONG VARCHAR.
`SQLT_NTY` | Idéntico a `OCI_B_NTY`.
`SQLT_NUM` | Idéntico a `OCI_B_NUM`.
`SQLT_ODT` | Utilizado con oci_bind_array_by_name() para vincular arrays de LONG.
`SQLT_RDD` | Idéntico a `OCI_B_ROWID`.
`SQLT_RSET` | Idéntico a `OCI_B_CURSOR`.
`SQLT_STR` | Utilizado con oci_bind_array_by_name() para vincular arrays de string.
`SQLT_UIN` | No soportado.
`SQLT_VCS` | Utilizado con oci_bind_array_by_name() para vincular arrays de VARCHAR.

Tipos de descriptores OCI8
Constante | Descripción
--- | ---
`OCI_DTYPE_FILE` | Esta opción indica a oci_new_descriptor() que inicialice un nuevo puntero FILE.
`OCI_DTYPE_LOB` | Esta opción indica a oci_new_descriptor() que inicialice un nuevo descriptor LOB.
`OCI_DTYPE_ROWID` | Esta opción indica a oci_new_descriptor() que inicialice un nuevo puntero LOB.
`OCI_D_FILE` | Idéntico a `OCI_DTYPE_FILE`.
`OCI_D_LOB` | Idéntico a `OCI_DTYPE_LOB`.
`OCI_D_ROWID` | Idéntico a `OCI_DTYPE_ROWID`.

Constantes | Descripción
--- | ---
Constantes de OCI8 Transparent Application Failover (TAF)
`OCI_FO_ABORT` (int) | El failover ha fallado y no hay posibilidad de reintentar.
`OCI_FO_BEGIN` (int) | El failover ha detectado una conexión perdida y comienza el failover.
`OCI_FO_END` (int) | El failover ha finalizado con éxito.
`OCI_FO_ERROR` (int) | El failover ha fallado pero permite a la aplicación gestionar el error y devolver `OCI_FO_RETRY` para reintentar el failover.
`OCI_FO_NONE` (int) | El usuario no ha solicitado ningún tipo de failover.
`OCI_FO_REAUTH` (int) | Un usuario de Oracle ha sido reautenticado.
`OCI_FO_RETRY` (int) | El failover debe ser reintentado por Oracle. En caso de error durante el failover a una nueva conexión, TAF puede reintentar el failover. Típicamente, el código de la aplicación debe dormir durante un tiempo antes de devolver `OCI_FO_RETRY`.
`OCI_FO_SELECT` (int) | El usuario también ha solicitado el failover SELECT. Permite a los usuarios con cursores abiertos continuar utilizándolos tras una caída.
`OCI_FO_SESSION` (int) | El usuario ha solicitado únicamente el failover de sesión. Por ejemplo, si la conexión de un usuario se pierde, entonces se crea automáticamente una nueva sesión para el usuario en la copia de seguridad. Este tipo de failover no intenta recuperar los SELECT.
`OCI_FO_TXNAL` (int) | El usuario ha solicitado un failover de transacción.

# Ejemplos

Estos ejemplos utilizan, para conectarse a la base de datos, el usuario `HR` que es el esquema `"Human Resources"` proporcionado por la base de datos Oracle. Esta cuenta debe haber sido desbloqueada y la contraseña reestablecida antes de poder utilizarla.

Estos ejemplos se conectan a la base de datos `XE` de su máquina. Modifique la cadena de conexión para que corresponda a su base de datos antes de ejecutar los ejemplos de esta documentación.

Ejemplo #1 Consulta simple

Este ejemplo muestra la ejecución de una consulta y la visualización de los resultados. Las consultas OCI8 utilizan las etapas preparación/ejecución/recuperación de datos.

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Preparación de la consulta
    $stid = oci_parse($conn, 'SELECT * FROM departments');
    if (!$stid) {
        $e = oci_error($conn);
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Ejecución de la lógica de la consulta
    $r = oci_execute($stid);
    if (!$r) {
        $e = oci_error($stid);
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Recuperación de los resultados de la consulta
    print "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        print "<tr>\n";
        foreach ($row as $item) {
            print "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "") . "</td>\n";
        }
        print "</tr>\n";
    }
    print "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #2 Inserción de datos utilizando variables ligadas

Las variables ligadas aumentan el rendimiento permitiendo la reutilización del caché y el contexto de ejecución. Las variables ligadas aumentan también la seguridad previniendo muchos casos de inyección SQL.

    <?php

    // Antes de la ejecución, cree la siguiente tabla:
    //   CREATE TABLE MYTABLE (mid NUMBER, myd VARCHAR2(20));

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'INSERT INTO MYTABLE (mid, myd) VALUES(:myid, :mydata)');

    $id = 60;
    $data = 'Some data';

    oci_bind_by_name($stid, ':myid', $id);
    oci_bind_by_name($stid, ':mydata', $data);

    $r = oci_execute($stid);  // ejecución y validación

    if ($r) {
        print "Una fila insertada";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #3 Ligadura de una cláusula WHERE de una consulta

Esto muestra la ligadura simple.

    <?php

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = 'SELECT last_name FROM employees WHERE department_id = :didbv ORDER BY last_name';
    $stid = oci_parse($conn, $sql);
    $didbv = 60;
    oci_bind_by_name($stid, ':didbv', $didbv);
    oci_execute($stid);
    while (($row = oci_fetch_array($stid, OCI_ASSOC)) != false) {
        echo $row['LAST_NAME'] ."<br>\n";
    }

    // Muestra:
    //    Austin
    //    Ernst
    //    Hunold
    //    Lorentz
    //    Pataballa

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #4 Inserción de datos en una columna CLOB

Para datos grandes, utilice un objeto binario largo (BLOB) o un objeto de caracteres largo (CLOB). Este ejemplo utiliza los CLOB.

    <?php

    // Antes de la ejecución, cree la siguiente tabla:
    //     CREATE TABLE MYTABLE (mykey NUMBER, myclob CLOB);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $mykey = 12343;  // clave arbitraria para el ejemplo

    $sql = "INSERT INTO mytable (mykey, myclob)
            VALUES (:mykey, EMPTY_CLOB())
            RETURNING myclob INTO :myclob";

    $stid = oci_parse($conn, $sql);
    $clob = oci_new_descriptor($conn, OCI_D_LOB);
    oci_bind_by_name($stid, ":mykey", $mykey, 5);
    oci_bind_by_name($stid, ":myclob", $clob, -1, OCI_B_CLOB);
    oci_execute($stid, OCI_NO_AUTO_COMMIT);
    $clob->save("Una cadena realmente muy larga");

    oci_commit($conn);

    // Recuperación de datos CLOB

    $query = 'SELECT myclob FROM mytable WHERE mykey = :mykey';

    $stid = oci_parse ($conn, $query);
    oci_bind_by_name($stid, ":mykey", $mykey, 5);
    oci_execute($stid);

    print '<table border="1">';
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_LOBS)) {
        print '<tr><td>'.$row['MYCLOB'].'</td></tr>';
        // En un bucle, liberar la variable antes de recuperar la
        // segunda línea permite reducir el uso de memoria de PHP
        unset($row);
    }
    print '</table>';

    ?>

Ejemplo #5 Uso de una función almacenada PL/SQL

Debe ligar una variable para el valor devuelto y, opcionalmente, para todos los argumentos de la función PL/SQL.

    <?php

    /*
      Antes de ejecutar el programa PHP, cree una función almacenada
      en lenguaje SQL*Plus o SQL Developer:

      CREATE OR REPLACE FUNCTION myfunc(p IN NUMBER) RETURN NUMBER AS
      BEGIN
          RETURN p * 3;
      END;

    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $p = 8;

    $stid = oci_parse($conn, 'begin :r := myfunc(:p); end;');
    oci_bind_by_name($stid, ':p', $p);
    oci_bind_by_name($stid, ':r', $r, 40);

    oci_execute($stid);

    print "$r\n";   // Muestra 24

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #6 Uso de una procedimiento almacenado PL/SQL

Con los procedimientos almacenados, debe ligar las variables para todos los argumentos.

    <?php

    /*
      Antes de ejecutar el programa PHP, cree un procedimiento almacenado en
      lenguaje SQL*Plus o SQL Developer:

      CREATE OR REPLACE PROCEDURE myproc(p1 IN NUMBER, p2 OUT NUMBER) AS
      BEGIN
          p2 := p1 * 2;
      END;

    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $p1 = 8;

    $stid = oci_parse($conn, 'begin myproc(:p1, :p2); end;');
    oci_bind_by_name($stid, ':p1', $p1);
    oci_bind_by_name($stid, ':p2', $p2, 40);

    oci_execute($stid);

    print "$p2\n";   // muestra 16

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #7 Llamada a una función PL/SQL que devuelve un `REF CURSOR`

Cada valor devuelto por la consulta es un `REF CURSOR` a utilizar para recuperar los datos.

    <?php
    /*
      Cree una función almacenada PL/SQL de la siguiente manera:

      CREATE OR REPLACE FUNCTION myfunc(p1 IN NUMBER) RETURN SYS_REFCURSOR AS
          rc SYS_REFCURSOR;
      BEGIN
          OPEN rc FOR SELECT city FROM locations WHERE ROWNUM < p1;
          RETURN rc;
      END;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT myfunc(5) AS mfrc FROM dual');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while (($row = oci_fetch_array($stid, OCI_ASSOC))) {
        echo "<tr>\n";
        $rc = $row['MFRC'];
        oci_execute($rc);  // El valor de la columna devuelto desde la consulta es una referencia de cursor
        while (($rc_row = oci_fetch_array($rc, OCI_ASSOC))) {
            echo "    <td>" . $rc_row['CITY'] . "</td>\n";
        }
        oci_free_statement($rc);
        echo "</tr>\n";
    }
    echo "</table>\n";

    // Muestra:
    //   Beijing
    //   Bern
    //   Bombay
    //   Geneva

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# Gestión de la conexión OCI8 y la cola de espera

## Funciones de conexión

La extensión oci8 proporciona tres funciones diferentes para conectarse a Oracle. La función de conexión estándar es la función oci_connect(). Esta función crea una conexión a la base de datos Oracle y devuelve un recurso utilizado por las futuras llamadas a la base de datos.

La conexión a un servidor Oracle es una operación razonablemente costosa en términos de tiempo. La función oci_pconnect() utiliza un caché persistente de conexiones que puede ser reutilizado a través de diferentes scripts. Esto significa que una sola conexión será utilizada por proceso PHP (o un hijo Apache).

Si su aplicación se conecta a Oracle utilizando un juego diferente de derechos de base de datos para cada usuario web, el caché persistente utilizado por la función oci_pconnect() se vuelve menos apropiado ya que el aumento del número de usuarios concurrentes afectará el rendimiento del servidor Oracle, ya que deberá mantener demasiadas conexiones en caché. Si su aplicación es de este tipo, se recomienda optimizar su aplicación utilizando las opciones de configuración oci8.max_persistent y oci8.persistent_timeout (estas opciones le dan control sobre el tamaño y la vida útil del caché de conexiones persistentes) o utilizar el pool de conexiones residentes de Oracle (para las bases de datos Oracle 11g y posteriores), o bien, utilizar la función oci_connect().

Las funciones oci_connect() y oci_pconnect() emplean un caché de conexiones; si se realizan múltiples llamadas a oci_connect(), utilizando los mismos parámetros en un script dado, la segunda llamada y las siguientes devolverán el manejador de conexión existente. El caché utilizado por la función oci_connect() se limpia al final de la ejecución del script o cuando se cierra explícitamente el manejador de conexión. oci_pconnect() tiene un comportamiento sustancialmente idéntico, con la diferencia de que el caché se mantiene por separado y se conserva entre las peticiones HTTP.

Es importante recordar esta funcionalidad de caché, ya que da la apariencia de que los dos manejadores no están aislados a nivel de transacciones (en realidad representan el mismo manejador de conexión, por lo que no están aislados en absoluto). Si su conexión necesita dos conexiones separadas, aisladas a nivel de transacciones, debe utilizar la función oci_new_connect().

El caché de la función oci_pconnect() se borra y todas las conexiones a la base de datos se cierran cuando el proceso PHP termina, por lo que las conexiones persistentes solo tienen interés cuando PHP se utiliza como módulo Apache o con FPM o similar. Las conexiones persistentes no tienen ningún interés a través de oci_connect() cuando PHP se utiliza como CGI o en línea de comandos.

oci_new_connect() siempre crea una nueva conexión al servidor Oracle, independientemente de la existencia de otras conexiones. Las aplicaciones web de alto tráfico deben evitar utilizar oci_new_connect(), especialmente en las secciones más cargadas de la aplicación.

Las conexiones persistentes pueden ahora ser cerradas por el usuario, permitiendo un mejor control de los recursos de conexión. Las conexiones persistentes pueden ahora ser cerradas automáticamente cuando ninguna variable PHP las referencia, como podría ser el caso al final de un contexto de una función de usuario PHP. Esto invalidará todas las transacciones no confirmadas. Estos cambios en las conexiones persistentes hacen que funcionen como las funciones no persistentes, simplificando la interfaz, permitiendo una mayor coherencia de la aplicación y previsibilidad. Defina la directiva oci8.old_oci_close_semantics a On para recuperar el comportamiento histórico.

El restablecimiento automático de las conexiones persistentes PHP después del reinicio de un proceso Apache o FPM hace que los triggers `LOGON` sean únicamente recomendados para definir los atributos de sesión y no las peticiones de conexión de usuarios por aplicación.

## Pool de conexión DRCP

PHP soporta el pool de conexiones residentes Oracle (DRCP). DRCP permite utilizar más eficientemente la memoria de la base de datos y permite una mejor escalabilidad. Se requieren pocos o ningún cambio para aprovechar DRCP.

DRCP está previsto para aplicaciones que se conectan utilizando poco esquema de base de datos, y que mantienen las conexiones abiertas durante un corto período de tiempo. Las otras aplicaciones deben utilizar el proceso dedicado a la base de datos Oracle, o utilizar los servidores compartidos.

DRCP se beneficia de las 3 funciones de conexión, pero solo la función oci_pconnect() ofrece el mayor rendimiento.

Para hacer DRCP disponible con OCI8, la versión de las bibliotecas clientes Oracle utilizadas por PHP así como la versión de la base de datos Oracle deben ser 11g o superiores.

La documentación sobre DRCP puede encontrarse en los diferentes manuales Oracle. Por ejemplo, consulte la » configuración del pool de conexiones residentes a la base de datos de la documentación Oracle para un ejemplo de uso. Un » libro blanco sobre DRCP contiene varias informaciones internas sobre DRCP.

Para utilizar DRCP, instale la extensión OCI8 y las bibliotecas Oracle 11g (o posterior), luego, siga estos pasos:

- Utilizando los privilegios de administrador de la base de datos, utilice un programa como SQL*Plus para iniciar un pool de conexiones a la base de datos:

          SQL> execute dbms_connection_pool.start_pool;

- Opcionalmente, utilice `dbms_connection_pool.alter_param()` para configurar las opciones DRCP. Las opciones comunes del pool pueden encontrarse utilizando la vista `DBA_CPOOL_INFO`.

- Actualice las cadenas de conexión utilizadas. Para las aplicaciones PHP que actualmente se conectan mediante un nombre de conexión de red como `MYDB`:

          $c = oci_pconnect("myuser", "mypassword", "MYDB");

  modifique el archivo tnsnames.ora y añada una cláusula `(SERVER=POOLED)`, por ejemplo:

          MYDB = (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=myhost.dom.com)
                 (PORT=1521))(CONNECT_DATA=(SERVICE_NAME=sales)
                 (SERVER=POOLED)))

  De lo contrario, puede modificar la sintaxis de conexión fácil en PHP y añadir `:POOLED` después del nombre del servicio:

          $c = oci_pconnect("myuser", "mypassword", "myhost.dom.com:1521/sales:POOLED");

- Edite php.ini y elija el nombre de la clase de conexión. Este nombre indica una división lógica del pool de conexión y puede ser utilizado para aislar el pool de diferentes aplicaciones. Todas las aplicaciones PHP utilizando el mismo usuario así como el mismo valor de clase de conexión podrán compartir el pool de conexiones, permitiendo así obtener una mayor disponibilidad.

          oci8.connection_class = "MY_APPLICATION_NAME"

- Ejecute su aplicación, conéctese a la base de datos 11g (o superior).

> Nota:

> Las aplicaciones que utilizan las bibliotecas cliente Oracle 10g que necesitan el rendimiento de las conexiones persistentes, pueden reducir la cantidad de memoria asignada al servidor de la base de datos utilizando los servidores compartidos Oracle (conocidos anteriormente como servidores multihilo). Consulte la documentación Oracle para obtener más información.

> Nota:

> La modificación de una contraseña durante conexiones DRCP fallará con el error "ORA-56609: Usage not supported with DRCP". Esto es una restricción documentada de la base de datos Oracle 11g.

# Soporte de FAN (Fast Application Notification : Notificación Rápida de Aplicación) OCI8

El soporte de FAN proporciona un cambio de conexión rápido, una funcionalidad de alta disponibilidad para la base de datos Oracle. Permite a los scripts PHP OCI8 ser notificados cuando una máquina de base de datos o una instancia de base de datos se vuelve no disponible. Sin FAN, OCI8 puede bloquearse en caso de alcanzar el tiempo límite TCP, y se devuelve un error, lo cual puede tomar varios minutos. La activación de FAN en OCI8 permite a las aplicaciones detectar los errores y reconectarse a una instancia de conexión disponible sin que el servidor Web necesite conocerlo.

El soporte de FAN está disponible cuando las bibliotecas clientes Oracle vinculadas a PHP y la base de datos Oracle son de la versión 10gR2 o superiores.

FAN beneficia a los usuarios de la tecnología de clúster Oracle (RAC) ya que las conexiones sobrevivientes a las instancias de base de datos pueden realizarse inmediatamente. Los usuarios de Oracle Data Guard con un broker, verán los eventos FAN generados cuando una base de datos pasa a estar en línea. Las bases de datos que no forman parte de un clúster enviarán eventos FAN cuando la base de datos se reinicie.

Para las conexiones activas, cuando una máquina o una instancia de base de datos se vuelve indisponible, se devolverá un error de conexión por la función de la extensión OCI8 llamada. Durante la reconexión de un script PHP subyacente, se establecerá una conexión a una instancia de base de datos sobreviviente. La extensión OCI8 también, de forma transparente, limpiará todas las conexiones inactivas afectadas por una máquina de base de datos o una instancia en fallo, así, las llamadas de conexión PHP establecerán una nueva conexión sin que el script lo sepa, evitando así cualquier interrupción del servicio.

Cuando oci8.events vale `On`, se sugiere definir oci8.ping_interval a -1 para desactivar el ping, sabiendo que la activación de los eventos FAN proporciona un gestor de conexiones proactivo de las conexiones inactivas que se han vuelto inválidas por una interrupción del servicio.

Para activar el soporte FAN en PHP OCI8, compile PHP OCI8 con las bibliotecas Oracle 10gR2 o superiores, luego, siga estos pasos:

- Con los privilegios de administrador de la base de datos, utilice un programa como SQL*Plus para activar el servicio de base de datos para publicar los eventos FAN; por ejemplo:

          SQL> execute dbms_service.modify_service(
                         SERVICE_NAME        => 'sales',
                         AQ_HA_NOTIFICATIONS => TRUE);

- Edite el archivo php.ini y añada:

          oci8.events = On

- Si la aplicación no gestiona aún las condiciones de error OCI8, modifíquela para detectar los fallos. Esto puede requerir la reconexión y la re-ejecución de las consultas.
- Ejecute la aplicación, conéctese a la base de datos Oracle 10gR2 o superiores.

# El soporte de la reanudación transparente de aplicación (TAF) de OCI8

TAF es una funcionalidad de la base de datos Oracle que proporciona alta disponibilidad. Permite que las aplicaciones PHP OCI8 se reconecten automáticamente a una base de datos preconfigurada cuando la conectividad a la base de datos falla debido a una falla de instancia o de red.

En un sistema de base de datos Oracle configurado, TAF ocurre cuando la aplicación PHP detecta que la instancia de la base de datos está fuera de servicio o inalcanzable. Establece una conexión a otro nodo en una configuración Oracle » RAC, una base de datos de respaldo en caliente, o la misma instancia de la base de datos ella misma. Consulte el » Guía del programador de la interfaz de llamada Oracle para más información sobre OCI TAF.

Una función de retrollamada de aplicación puede ser registrada con oci_register_taf_callback(). Durante la reanudación, el procesamiento normal de la aplicación se detiene y la retrollamada registrada es invocada. La función de retrollamada notifica a la aplicación de los eventos de reanudación. Si la reanudación tiene éxito, el procesamiento normal se reanudará. Si la reanudación es abandonada, todas las operaciones de base de datos siguientes en la aplicación fallarán debido a la falta de una conexión disponible.

Cuando la conexión falla en otra base de datos, la función de retrollamada puede restablecer cualquier estado de conexión necesario, por ejemplo, rejugando los comandos ALTER SESSION necesarios si el servicio de base de datos no tenía -failover_restore activado.

Una función de retrollamada de aplicación puede ser eliminada llamando a oci_unregister_taf_callback().

## Configuración de la reanudación transparente de aplicación

TAF puede ser configurado del lado PHP OCI8 o en la configuración de la base de datos. Si ambos están configurados, los parámetros del lado de la base de datos tienen prioridad.

Configurar TAF en PHP OCI8 (el lado cliente) incluyendo el parámetro FAILOVER_MODE en la parte CONNECT_DATA de un descriptor de conexión. Consulte la sección Configuración de la reanudación transparente de aplicación del » Guía del administrador de Oracle Database Net Services para más información sobre la configuración del lado cliente de TAF.

Un ejemplo de tnsnames.ora para configurar TAF reconectando a la misma instancia de la base de datos:

        ORCL =
          (DESCRIPTION =
            (ADDRESS = (PROTOCOL = TCP)(HOST = 127.0.0.1)(PORT = 1521))
            (CONNECT_DATA =
              (SERVICE_NAME = orclpdb1)
              (FAILOVER_MODE =
                (TYPE = SELECT)
                (METHOD = BASIC)
                (RETRIES = 20)
                (DELAY = 15))))

También es posible configurar TAF del lado de la base de datos modificando el servicio objetivo con » srvctl (para RAC) o la procedimiento empaquetado » DBMS_SERVICE.MODIFY_SERVICE (para bases de datos de instancia única).

## Uso de las funciones de retrollamada TAF en OCI8

Una función de retrollamada TAF es una función de aplicación que puede ser registrada para ser llamada durante la reanudación. Es llamada varias veces durante la reanudación de la conexión de la aplicación.

La función de retrollamada es llamada por primera vez cuando se detecta una pérdida de conexión. Esto permite que la aplicación actúe en consecuencia para los retrasos venideros de la reanudación. Si la reanudación tiene éxito, la función de retrollamada es invocada después de que la conexión sea restablecida y utilizable. En ese momento, la aplicación puede resincronizar los parámetros de sesión y tomar acciones tales como informar al usuario que una reanudación ha ocurrido. Si la reanudación es infructuosa, una retrollamada ocurre para informar a la aplicación que una reanudación no ha ocurrido y que la conexión no es utilizable.

La interfaz de una función de retrollamada TAF definida por el usuario es la siguiente:

function userCallbackFn(resource `$connection`, int `$event`, int `$type`): int

`connection`

  La conexión Oracle en la que la retrollamada TAF ha sido registrada vía oci_register_taf_callback(). La conexión no es válida hasta que la reanudación no termine con éxito.

`event`

  El evento de reanudación indica el estado actual de la reanudación.

  - `OCI_FO_BEGIN` indica que la reanudación ha detectado una pérdida de conexión y que la reanudación comienza.

  - `OCI_FO_END` indica que la reanudación ha tenido éxito.

  - `OCI_FO_ABORT` indica que la reanudación ha fallado y que no hay opción de reintentar.

  - `OCI_FO_ERROR` indica asimismo que la reanudación ha fallado, pero da a la aplicación la oportunidad de manejar el error y devolver OCI_FO_RETRY para reintentar la reanudación.

  - `OCI_FO_REAUTH` indica que un usuario Oracle ha sido reautenticado.

`type`

  El tipo de reanudación. Esto permite a la retrollamada saber qué tipo de reanudación la aplicación ha solicitado. Los valores habituales son los siguientes:

  - `OCI_FO_SESSION` indica que el usuario ha solicitado únicamente la reanudación de sesión. Por ejemplo, si la conexión de un usuario se pierde, una nueva sesión es automáticamente creada para el usuario en la base de datos de respaldo. Este tipo de reanudación no intenta recuperar los SELECT.

  - `OCI_FO_SELECT` indica que el usuario ha solicitado la reanudación SELECT asimismo. Permite a los usuarios con cursores abiertos continuar recuperándolos después de una falla.

`valor de retorno`

  - `0` indica que los pasos de reanudación deben continuar normalmente.

  - `OCI_FO_RETRY` indica que la reanudación debe ser intentada nuevamente por Oracle. En caso de error al reanudar a una nueva conexión, TAF es capaz de reintentar la reanudación. En general, el código de la aplicación debe dormir durante un cierto tiempo antes de devolver OCI_FO_RETRY.

Ejemplo #1 Registro de una función de retrollamada TAF

    <?php

    // Definición de la función de retrollamada del espacio de usuario
    class MyClass {
        public static $retry_count;
        public static function TAFCallback($conn, $event, $type)
        {
            switch ($event) {
                case OCI_FO_BEGIN:
                    printf(" Reanudando ... Por favor, espere\n");
                    printf(" El tipo de reanudación se encontró que era %s \n",
                           (($type==OCI_FO_SESSION) ? "SESSION"
                            :(($type==OCI_FO_SELECT) ? "SELECT" : "UNKNOWN!")));
                    self::$retry_count = 0;
                    break;
                case OCI_FO_ABORT:
                    // La aplicación no puede continuar utilizando la base de datos
                    printf(" Reanudación abortada. La reanudación no tendrá lugar.\n");
                    break;
                case OCI_FO_END:
                    // Reanudación exitosa. Informar a los usuarios que una reanudación ha ocurrido.
                    printf(" Reanudación terminada ... reanudando servicios\n");
                    break;
                case OCI_FO_REAUTH:
                    printf(" Usuario reanudado ... reanudando servicios\n");
                    // Rejugar todas las comandos ALTER SESSION asociadas a esta conexión
                    // por ejemplo oci_parse($conn, 'ALTER SESSION ...');
                    break;
                case OCI_FO_ERROR:
                    // Detener los intentos si ya se ha intentado 20 veces.
                    if (self::$retry_count >= 20)
                        return 0;
                    printf(" Error de reanudación recibido. Durmiendo...\n");
                    sleep(10);
                    self::$retry_count++;
                    return OCI_FO_RETRY; // reintentar reanudación
                    break;
                default:
                    printf("Evento de reanudación incorrecto: %d.\n", $event);
                    break;
            }
            return 0;
        }
    }

    $fn_name = 'MyClass::TAFCallback';

    $conn = oci_connect('hr', 'welcome', 'orcl');
    $sysconn = oci_connect('system', 'oracle', 'orcl');

    // Usar una conexión privilegiada para construir una instrucción SQL que iniciará la reanudación
    $sql = <<< 'END'
    select unique 'alter system disconnect session '''||sid||','||serial#||''''
    from v$session_connect_info
    where sid = sys_context('USERENV', 'SID')
    END;

    $s = oci_parse($conn, $sql);
    oci_execute($s);
    $r = oci_fetch_array($s);
    $disconnectssql = $r[0];

    oci_register_taf_callback($conn, $fn_name); // Registrar TAFCallback a Oracle TAF

    print "Analizando consulta de usuario\n";
    $sql = "select systimestamp from dual";
    $stmt = oci_parse($conn, $sql);

    // Por ejemplo, si una pérdida de conexión ocurre en este momento, oci_execute() detectará
    // la pérdida y la reanudación comenzará. Durante la reanudación, oci_execute() invocará
    // la función de retrollamada TAF varias veces. Si la reanudación tiene éxito,
    // una nueva conexión es creada de manera transparente y oci_execute() continuará como
    // de costumbre. Los parámetros de sesión de la conexión pueden ser restablecidos en la función de retrollamada TAF.
    // Si la reanudación es abandonada, oci_execute() devolverá un error
    // ya que una conexión válida no está disponible.

    // Desconectar al usuario, lo que inicia la reanudación
    print "Desconectando al usuario\n";
    $discsql = oci_parse($sysconn, $disconnectssql);
    oci_execute($discsql);

    print "Ejecutando consulta de usuario\n";
    $e = oci_execute($stmt);
    if (!$e) {
        $m = oci_error($stmt);
        trigger_error("No se pudo ejecutar la sentencia: ". $m['message'], E_USER_ERROR);
    }
    $row = oci_fetch_array($stmt);
    print $row[0] . "\n";

    // hacer otras instrucciones SQL con la nueva conexión, si es válida
    // $stmt = oci_parse($conn,  . . .);

    ?>

## Ver también

- oci_register_taf_callback()
- oci_unregister_taf_callback()

# OCI8 y rastreo dinámico de DTrace

OCI8 2.0 sondeos de DTrace estáticos que se pueden usar en sistemas operativos que admiten DTrace. Véase Rastreo dinámico de DTrace para una visión general de PHP y DTrace.

## Instalar OCI8 con soporte para DTrace

Para habilitar el soporte para DTrace en OCI8 para PHP, construya OCI8 como una extensión compartida después de establecer `PHP_DTRACE`.

    $ export PHP_DTRACE=yes
    $ pecl install oci8

Edite php.ini, establezca extension_dir al directorio con el oci8.so creado y también habilite la extensión añadiendo:

    extension=oci8.so

Si instala PHP OCI8 2.0 desde PECL usando phpize y configure (en lugar de pecl), será necesario establecer `PHP_DTRACE=yes`. Esto es así debido a que la opción `--enable-dtrace` será ignorada por el script limitado configure de un PECL incluido.

Véase Instalación de extensiones PECL para las instrucciones generales de instalación de PECL.

## Sondeos estáticos de DTrace en OCI8 para PHP

Los siguientes sondeos estáticos están disponibles en OCI8 para PHP
Nombre del sondeo | Descripción del sondeo | Argumentos del sondeo
--- | --- | ---
`oci8-connect-entry` | Iniciado por oci_connect(), oci_pconnect() y oci_new_connect(). Lanzado antes de establecer una conexión con una base de datos. | char *username, char *dbname, char *charset, long session_mode, int persistent, int exclusive
`oci8-connect-return` | Lanzado al finallde una conexión. | void *connection
`oci8-check-connection` | Lanzado si un error de Oracle podría haber causado que la conexión sea inválida. | void *connection, char *client_id, int is_open, long errcode, unsigned long server_status
`oci8-sqltext` | Lanzado cuando oci_parse() se ejecuta. | void *connection, char *client_id, void *statement, char *sql
`oci8-connection-close` | Lanzado cuando la conexión a la base de datos está completamente destruida. | void *connection
`oci8-error` | Lanzado si ocurre un error de Oracle. | int status, long errcode
`oci8-execute-mode` | Lanzado en oci_execute() para mostrar el modo de ejecución. | void *connection, char *client_id, void *statement, unsigned int mode

Estos sondeos son útiles para rastrear scripts de OCI8.

connection y statement son los punteros a las estructuras internas usadas para rastrear conexiones de PHP y ejecutar sentencias.

client_id es el valor establecido por oci_set_client_identifier().

El núcleo de PHP también posee sondeos estáticos. Véase Sondeos estáticos de DTrace en el núcleo de PHP.

Sondeos de DTrace de depuración interna en OCI8
Nombre del sondeo
`oci8-connect-expiry`
`oci8-connect-lookup`
`oci8-connect-p-dtor-close`
`oci8-connect-p-dtor-release`
`oci8-connect-type`
`oci8-sesspool-create`
`oci8-sesspool-stats`
`oci8-sesspool-type`

Estos sondeos son útiles para mantenedores de OCI8. Consulte el código fuente de OCI8 para los argumentos y para ver cuando serán lanzados.

## Enumerar los Sondeos estáticos de DTrace en OCI8 para PHP

Para enumerar los sondeos disponibles, inicie un proceso de PHP y ejecute:

    # dtrace -l

La salida será similar a:

       ID   PROVIDER            MODULE                          FUNCTION NAME
       [ . . . ]
       17 phpoci22116           oci8.so   php_oci_dtrace_check_connection oci8-check-connection
       18 phpoci22116           oci8.so                php_oci_do_connect oci8-connect-entry
       19 phpoci22116           oci8.so         php_oci_persistent_helper oci8-connect-expiry
       20 phpoci22116           oci8.so             php_oci_do_connect_ex oci8-connect-lookup
       21 phpoci22116           oci8.so  php_oci_pconnection_list_np_dtor oci8-connect-p-dtor-close
       22 phpoci22116           oci8.so  php_oci_pconnection_list_np_dtor oci8-connect-p-dtor-release
       23 phpoci22116           oci8.so                php_oci_do_connect oci8-connect-return
       24 phpoci22116           oci8.so             php_oci_do_connect_ex oci8-connect-type
       25 phpoci22116           oci8.so          php_oci_connection_close oci8-connection-close
       26 phpoci22116           oci8.so                     php_oci_error oci8-error
       27 phpoci22116           oci8.so         php_oci_statement_execute oci8-execute-mode
       28 phpoci22116           oci8.so              php_oci_create_spool oci8-sesspool-create
       29 phpoci22116           oci8.so            php_oci_create_session oci8-sesspool-stats
       30 phpoci22116           oci8.so            php_oci_create_session oci8-sesspool-type
       31 phpoci22116           oci8.so          php_oci_statement_create oci8-sqltext

Los valores de la columna "Provider" (Proveedor) consisten en `phpoci` and el ID del proceso de PHP ejecutándose actualmente.

La columna "Function" (Función) se refiere a los nombres de funciones internas de la implementación en C de PHP donde cada proveedor está ubicado.

Si un proceso de PHP no se está ejecutando, no se mostrarán sondeos de PHP.

## Ejemplo de DTrace con OCI8 para PHP

Este ejemplo muestra lo básico del lenguaje de script D de DTrace.

Ejemplo #1 user_oci8_probes.d para rasrear todos los Sondeos estáticos de OCI8 para PHP al nivel de usuario con DTrace

    #!/usr/sbin/dtrace -Zs

    #pragma D option quiet

    php*:::oci8-connect-entry
    {
        printf("%lld: PHP connect-entry\n", walltimestamp);
        printf("  credentials=\"%s@%s\"\n", arg0 ? copyinstr(arg0) : "", arg1 ? copyinstr(arg1) : "");
        printf("  charset=\"%s\"\n", arg2 ? copyinstr(arg2) : "");
        printf("  session_mode=%ld\n", (long)arg3);
        printf("  persistent=%d\n", (int)arg4);
        printf("  exclusive=%d\n", (int)arg5);
    }

    php*:::oci8-connect-return
    {
        printf("%lld: PHP oci8-connect-return\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
    }

    php*:::oci8-connection-close
    {
        printf("%lld: PHP oci8-connect-close\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
    }

    php*:::oci8-error
    {
        printf("%lld: PHP oci8-error\n", walltimestamp);
        printf("  status=%d\n", (int)arg0);
        printf("  errcode=%ld\n", (long)arg1);
    }

    php*:::oci8-check-connection
    {
        printf("%lld: PHP oci8-check-connection\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
        printf("  client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
        printf("  is_open=%d\n", arg2);
        printf("  errcode=%ld\n", (long)arg3);
        printf("  server_status=%lu\n", (unsigned long)arg4);
    }

    php*:::oci8-sqltext
    {
        printf("%lld: PHP oci8-sqltext\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
        printf("  client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
        printf("  statement=0x%p\n", (void *)arg2);
        printf("  sql=\"%s\"\n", arg3 ? copyinstr(arg3) : "");
    }

    php*:::oci8-execute-mode
    {
        printf("%lld: PHP oci8-execute-mode\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
        printf("  client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
        printf("  statement=0x%p\n", (void *)arg2);
        printf("  mode=0x%x\n", arg3);
    }

Este script usa la opción `-Z` para dtrace, permitiéndole que sea ejecutado cuando no exista un procesode PHP en ejecución. Si esta opción fuera omitida, el script terminaría inmediatamente cuando no se ejecutara PHP porque no sabe de la existencia de sondeos a ser monitorizados.

En máquinas multi-CPU, el orden de los sondeos no parecerá ser sencuencial. Esto depende de cuál CPU estaba procesando los sondeos, y de cómo los hilos migran entre CPUs. Mostrar las marcas de tiempo de los sondeos atudará a reducir la confusión.

El script rastrea todos los sondeos estáticos de OCI8 para PHP a nivel de usuario que apuntan a lo largo de la duración de un script de PHP en ejecución. Ejecute el script D:

    # ./user_oci8_probes.d

Ejecute un script o aplicación de PHP. El script D de monitorización generará cada argumento del sondeo mientras se lanza. Por ejemplo, un sencillo script de PHP que requiere una tabla podría producir la siguiente salida de rastreo:

    1381794982092854582: PHP connect-entry
      credentials="hr@localhost/pdborcl"
      charset=""
      session_mode=0
      persistent=0
      exclusive=0
    1381794982183158766: PHP oci8-connect-return
      connection=0x7f4a7907bfb8
    1381794982183594576: PHP oci8-sqltext
      connection=0x7f4a7907bfb8
      client_id="Chris"
      statement=0x7f4a7907c2a0
      sql="select * from employees"
    1381794982183783706: PHP oci8-execute-mode
      connection=0x7f4a7907bfb8
      client_id="Chris"
      statement=0x7f4a7907c2a0
      mode=0x20
    1381794982444344390: PHP oci8-connect-close
      connection=0x7f4a7907bfb8

Cuando la monitorización está completa, el script D puede terminarse con ``CTRL`+`C``.

## Véase también

- Rastreo dinámico de DTrace

# Tipos de datos admitidos

El controlador admite los siguientes tipos cuando se vinculan parámetros usando la función oci_bind_by_name():
Tipo | Referencia
--- | ---
`SQLT_NTY` | Hace referencia a un tipo de colección nativo desde un objeto colección de PHP, tales como aquellos creados por oci_new_collection().
`SQLT_BFILEE` | Hace referencia a un descriptor nativo, tales como a aquellos creados por oci_new_descriptor().
`SQLT_CFILEE` | Hace referencia a un descriptor nativo, tales como a aquellos creados por oci_new_descriptor().
`SQLT_CLOB` | Hace referencia a un descriptor nativo, tales como a aquellos creados por oci_new_descriptor().
`SQLT_BLOB` | Hace referencia a un descriptor nativo, tales como a aquellos creados por oci_new_descriptor().
`SQLT_RDD` | Hace referencia a un descriptor nativo, tales como a aquellos creados por oci_new_descriptor().
`SQLT_NUM` | Convierte el parámetro de PHP al tipo long de 'C', y lo vincula a ese valor.
`SQLT_RSET` | Hace referencia a un gestor de sentencias nativo, tales como a aquellos creados por oci_parse() o aquellos recuperados desde otras consultas de OCI.
`SQLT_BOL` | Vincular el parámetro de PHP a un BOOLEAN de PL/SQL
`SQLT_CHR` y cualquier otro tipo | Convierte el parámetro de PHP al tipo string y lo vincula como string.

Los siguientes tipos son admitidos cuando se recuperan columnas desde un conjunto de resultados:
Tipo | Referencia
--- | ---
`SQLT_RSET` | Crea un recurso de sentencia de OCI para representar al cursor.
`SQLT_RDD` | Crea un objeto ROWID.
`SQLT_BLOB` | Crea un objeto LOB.
`SQLT_CLOB` | Crea un objeto LOB.
`SQLT_BFILE` | Crea un objeto LOB.
`SQLT_LNG` | Vinculado como SQLT_CHR, devuelto como string
`SQLT_LBI` | Vinculado como `SQLT_BIN`, devuelto como string
Cualquier otro tipo | Vinculado como `SQLT_CHR`, devuelto como string

# Funciones de OCI8

# oci_bind_array_by_name

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL OCI8 >= 1.2.0)

oci_bind_array_by_name — Asocia un array PHP a un parámetro de array Oracle PL/SQL

### Descripción

function oci_bind_array_by_name(
resource `$statement`,
string `$param`,
array `&$var`,
int `$max_array_length`,
int `$max_item_length` = -1,
int `$type` = `SQLT_AFC`
): bool

Asocia un array PHP `var` a un marcador Oracle `param`, que apunta a un array PL/SQL. Puede ser utilizado para entrada o salida, dependiendo de la configuración en tiempo de ejecución.

### Parámetros

`statement`

  Un identificador de consulta OCI válido.

`param`

  El marcador Oracle.

`var`

  Un array.

`max_array_length`

  Especifica la longitud máxima de los arrays de entrada y resultado.

`max_item_length`

  Define la longitud máxima para los elementos del array. Si `max_item_length` no se proporciona o si vale -1, oci_bind_array_by_name() buscará el elemento más largo en el array de entrada y lo utilizará como longitud máxima.

`type`

  Debe ser utilizado para definir el tipo de los elementos PL/SQL. Consulte la lista de tipos disponibles a continuación:

  - `SQLT_NUM` - para arrays de NUMBER.

  - `SQLT_INT` - para arrays INTEGER (Nota: INTEGER actualmente es un sinónimo de NUMBER(38), pero el tipo `SQLT_NUM` no funcionará en este caso aunque sean sinónimos).

  - `SQLT_FLT` - para arrays de FLOAT.

  - `SQLT_AFC` - para arrays de CHAR.

  - `SQLT_CHR` - para arrays de VARCHAR2.

  - `SQLT_VCS` - para arrays de VARCHAR.

  - `SQLT_AVC` - para arrays de CHARZ.

  - `SQLT_STR` - para arrays de STRING.

  - `SQLT_LVC` - para arrays de LONG VARCHAR.

  - `SQLT_ODT` - para arrays de DATE.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con oci_bind_array_by_name()

    <?php

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $create = "CREATE TABLE bind_example(name VARCHAR(20))";
    $stid = oci_parse($conn, $create);
    oci_execute($stid);

    $create_pkg = "
    CREATE OR REPLACE PACKAGE ARRAYBINDPKG1 AS
      TYPE ARRTYPE IS TABLE OF VARCHAR(20) INDEX BY BINARY_INTEGER;
      PROCEDURE iobind(c1 IN OUT ARRTYPE);
    END ARRAYBINDPKG1;";
    $stid = oci_parse($conn, $create_pkg);
    oci_execute($stid);

    $create_pkg_body = "
    CREATE OR REPLACE PACKAGE BODY ARRAYBINDPKG1 AS
      CURSOR CUR IS SELECT name FROM bind_example;
      PROCEDURE iobind(c1 IN OUT ARRTYPE) IS
        BEGIN
        -- Bulk Insert
        FORALL i IN INDICES OF c1
          INSERT INTO bind_example VALUES (c1(i));

        -- Fetch and reverse;
        IF NOT CUR%ISOPEN THEN
          OPEN CUR;
        END IF;
        FOR i IN REVERSE 1..5 LOOP
          FETCH CUR INTO c1(i);
          IF CUR%NOTFOUND THEN
            CLOSE CUR;
            EXIT;
          END IF;
        END LOOP;
      END iobind;
    END ARRAYBINDPKG1;";
    $stid = oci_parse($conn, $create_pkg_body);
    oci_execute($stid);

    $stid = oci_parse($conn, "BEGIN arraybindpkg1.iobind(:c1); END;");
    $array = array("one", "two", "three", "four", "five");
    oci_bind_array_by_name($stid, ":c1", $array, 5, -1, SQLT_CHR);
    oci_execute($stid);

    var_dump($array);

    ?>

# oci_bind_by_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_bind_by_name — Asocia una variable PHP a un marcador Oracle

### Descripción

function oci_bind_by_name(
resource `$statement`,
string `$param`,
mixed `&$var`,
int `$max_length` = -1,
int `$type` = 0
): bool

Vincula una variable PHP `var` al marcador Oracle `param`. El hecho de vincular una variable es importante en términos de rendimiento de la base de datos Oracle, pero también en términos de seguridad relativa a las inyecciones SQL.

El vínculo permite a las bases de datos reutilizar el contexto de ejecución de la consulta así como el caché asociado, incluso cuando otro usuario o proceso la ejecuta. El vínculo reduce el riesgo de inyección SQL ya que los datos asociados a una variable vinculada nunca son tratados como parte de la consulta SQL. Por lo tanto, no es necesario añadir comillas ni escapar estos datos.

Las variables PHP vinculadas pueden cambiarse y la consulta re-ejecutarse sin necesidad de analizar de nuevo la consulta o de vincular de nuevo las variables.

Con Oracle, las variables vinculadas suelen dividirse en vínculo `IN` para los valores pasados a la base de datos, y en vínculo `OUT` para los valores a devolver a PHP. Una variable vinculada puede ser a la vez en vínculo `IN` y `OUT`. En este caso, el hecho de saber si la variable vinculada debe ser utilizada para la entrada o la salida será determinado en el momento de la ejecución.

Debe especificarse el parámetro `max_length` al utilizar el vínculo `OUT` para que PHP asigne suficiente memoria para contener el valor de retorno.

Para los vínculos `IN`, se recomienda definir el parámetro `max_length` si la consulta se ejecuta varias veces con valores diferentes para las variables PHP. De lo contrario, Oracle puede truncar los datos a la longitud del valor inicial de la variable PHP. Si no se conoce la longitud máxima necesaria, entonces llame de nuevo a la función oci_bind_by_name() con los datos actuales, antes de cada llamada a la función oci_execute(). El hecho de asociar una longitud superior a la necesaria tiene un impacto en la memoria asociada al proceso para la base de datos.

Una llamada a la funcionalidad de asociación de variables proporciona a Oracle la dirección de memoria a utilizar para leer los datos. Para los vínculos `IN`, esta dirección debe contener datos válidos al llamar a la función oci_execute(). Esto significa que la variable vinculada debe permanecer en el contexto hasta la ejecución. Si no es así, pueden producirse resultados no esperados, así como errores de tipo "ORA-01460: unimplemented or unreasonable conversion requested". Para los vínculos `OUT`, un síntoma puede ser que no se haya definido ningún valor en la variable PHP.

Para una consulta que se ejecuta varias veces, los valores vinculados que nunca cambian pueden reducir la capacidad del optimizador de Oracle para elegir el mejor plan de ejecución. Para las consultas que tardan mucho tiempo, que rara vez se llaman varias veces, la asociación de variables no aporta ningún beneficio. Sin embargo, en los 2 casos, la asociación es más segura que colocar directamente las cadenas de caracteres en la consulta SQL, sabiendo que existe un riesgo de filtrado incorrecto de la entrada del usuario.

### Parámetros

`statement`

  Un identificador de consulta OCI8 válido.

`param`

  El marcador, prefijado por una coma, utilizado en la consulta. La coma es opcional en el parámetro `param`.

`var`

  La variable PHP a asociar con el marcador del parámetro `param`.

`max_length`

  Especifica la longitud máxima para los datos. Si el valor es -1, la función utilizará la longitud actual de los datos del parámetro `var` para definir la longitud máxima. En este caso, el parámetro `var` debe existir y contener datos al llamar a la función oci_bind_by_name().

`type`

  El tipo de datos a utilizar por Oracle para tratar los datos. Por omisión, vale `SQLT_CHR`. Oracle convertirá los datos entre este tipo y la columna de la base de datos (o las variables de tipo PL/SQL), cuando sea posible.

  Si debe vincular tipos abstractos de datos (LOB/ROWID/BFILE), deberá asignarlos en primer lugar, con oci_new_descriptor(). La longitud `length` no sirve para estos tipos y debería fijarse a -1.

  Los valores posibles para el parámetro `type` son :

  - `SQLT_FILE` o `OCI_B_BFILE` - para los BFILEs ;

  - `SQLT_CFILE` o `OCI_B_CFILEE` - para los CFILEs ;

  - `SQLT_CLOB` o `OCI_B_CLOB` - para los CLOBs ;

  - `SQLT_BLOB` o `OCI_B_BLOB` - para los BLOBs ;

  - `SQLT_RDD` o `OCI_B_ROWID` - para los ROWIDs ;

  - `SQLT_NTY` o `OCI_B_NTY` - para los tipos de datos nombrados ;

  - `SQLT_INT` o `OCI_B_INT` - para los enteros ;

  - `SQLT_CHR` - para los VARCHAR ;

  - `SQLT_BIN` o `OCI_B_BIN` - para las columnas RAW ;

  - `SQLT_LNG` - para las columnas LONG ;

  - `SQLT_LBI` - para las columnas LONG RAW ;

  - `SQLT_RSET` - para los cursores creados con la función oci_new_cursor();

  - `SQLT_BOL` o `OCI_B_BOL` - para los booleanos (requiere Oracle Database 12c)

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Inserción de datos con la función oci_bind_by_name()

    <?php

    // Creación de la tabla con :
    //   CREATE TABLE mytab (id NUMBER, text VARCHAR2(40));

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn,"INSERT INTO mytab (id, text) VALUES(:id_bv, :text_bv)");

    $id = 1;
    $text = "Datos a insertar     ";
    oci_bind_by_name($stid, ":id_bv", $id);
    oci_bind_by_name($stid, ":text_bv", $text);
    oci_execute($stid);

    // La tabla contiene ahora : 1, 'Datos a insertar

    ?>

Ejemplo #2 Una asociación con múltiples llamadas

    <?php

    // Creación de la tabla con :
    //   CREATE TABLE mytab (id NUMBER);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $a = array(1,3,5,7,11);  // Datos a insertar

    $stid = oci_parse($conn, 'INSERT INTO mytab (id) VALUES (:bv)');
    oci_bind_by_name($stid, ':bv', $v, 20);
    foreach ($a as $v) {
        $r = oci_execute($stid, OCI_DEFAULT);  // No validar automáticamente
    }
    oci_commit($conn); // Una sola validación

    // La tabla contiene ahora 5 líneas : 1, 3, 5, 7, 11

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #3 Asociación con un bucle `foreach`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = 'SELECT * FROM departments WHERE department_name = :dname AND location_id = :loc';
    $stid = oci_parse($conn, $sql);

    $ba = array(':dname' => 'IT Support', ':loc' => 1700);

    foreach ($ba as $key => $val) {

        // oci_bind_by_name($stid, $key, $val) no funciona porque
        // asocia cada marcador al mismo lugar : $val
        // en lugar de utilizar el lugar actual de la dato $ba[$key]
        oci_bind_by_name($stid, $key, $ba[$key]);
    }

    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);
    foreach ($row as $item) {
        print $item."<br>\n";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #4 Asociación en una cláusula WHERE

    <?php

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = 'SELECT last_name FROM employees WHERE department_id = :didbv ORDER BY last_name';
    $stid = oci_parse($conn, $sql);
    $didbv = 60;
    oci_bind_by_name($stid, ':didbv', $didbv);
    oci_execute($stid);
    while (($row = oci_fetch_array($stid, OCI_ASSOC)) != false) {
        echo $row['LAST_NAME'] ."<br>\n";
    }

    // Muestra :
    //    Austin
    //    Ernst
    //    Hunold
    //    Lorentz
    //    Pataballa

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #5 Asociación con una cláusula LIKE

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    // Encuentra todos los criterios que comienzan por 'South'
    $stid = oci_parse($conn, "SELECT city FROM locations WHERE city LIKE :bv");
    $city = 'South%';  // '%' es un comodín en SQL
    oci_bind_by_name($stid, ":bv", $city);
    oci_execute($stid);
    oci_fetch_all($stid, $res);

    foreach ($res['CITY'] as $c) {
        print $c . "<br>\n";
    }
    // Muestra :
    //   South Brunswick
    //   South San Francisco
    //   Southlake

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #6 Asociación con REGEXP_LIKE

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    // Encuentra todos los criterios que contienen 'ing'
    $stid = oci_parse($conn, "SELECT city FROM locations WHERE REGEXP_LIKE(city, :bv)");
    $city = '.*ing.*';
    oci_bind_by_name($stid, ":bv", $city);
    oci_execute($stid);
    oci_fetch_all($stid, $res);

    foreach ($res['CITY'] as $c) {
        print $c . "<br>\n";
    }
    // Muestra :
    //   Beijing
    //   Singapore

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Para algunas condiciones utilizadas en las cláusulas IN, utilice variables vinculadas individuales. Los valores desconocidos en el momento de la ejecución podrán definirse a NULL. Esto permite utilizar una sola consulta para todos los usuarios de la aplicación, maximizando así la eficacia del caché Oracle DB.

Ejemplo #7 Asociación de múltiples valores en una cláusula IN

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = 'SELECT last_name FROM employees WHERE employee_id in (:e1, :e2, :e3)';
    $stid = oci_parse($conn, $sql);
    $mye1 = 103;
    $mye2 = 104;
    $mye3 = NULL; // fingimos que no nos fue dado este valor
    oci_bind_by_name($stid, ':e1', $mye1);
    oci_bind_by_name($stid, ':e2', $mye2);
    oci_bind_by_name($stid, ':e3', $mye3);
    oci_execute($stid);
    oci_fetch_all($stid, $res);
    foreach ($res['LAST_NAME'] as $name) {
        print $name ."<br>\n";
    }

    // Muestra :
    //   Ernst
    //   Hunold

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #8 Asociación de un ROWID devuelto por una consulta

    <?php

    // Creación de la tabla con :
    //   CREATE TABLE mytab (id NUMBER, salary NUMBER, name VARCHAR2(40));
    //   INSERT INTO mytab (id, salary, name) VALUES (1, 100, 'Chris');
    //   COMMIT;

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT ROWID, name FROM mytab WHERE id = :id_bv FOR UPDATE');
    $id = 1;
    oci_bind_by_name($stid, ':id_bv', $id);
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);
    $rid = $row['ROWID'];
    $name = $row['NAME'];

    // Modificación del nombre en letra mayúscula & guardado de esta modificación
    $name = strtoupper($name);
    $stid = oci_parse($conn, 'UPDATE mytab SET name = :n_bv WHERE ROWID = :r_bv');
    oci_bind_by_name($stid, ':n_bv', $name);
    oci_bind_by_name($stid, ':r_bv', $rid, -1, OCI_B_ROWID);
    oci_execute($stid);

    // La tabla contiene ahora 1, 100, CHRIS

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #9 Asociación de un ROWID en un INSERT

    <?php

    // Este ejemplo inserta un id & un nombre, luego, actualiza el salario
    // Creación de la tabla con :
    //   CREATE TABLE mytab (id NUMBER, salary NUMBER, name VARCHAR2(40));
    //
    // Basado en el ejemplo original de ROWID, proporcionado por thies at thieso dot net (980221)

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = "INSERT INTO mytab (id, name) VALUES(:id_bv, :name_bv)
            RETURNING ROWID INTO :rid";

    $ins_stid = oci_parse($conn, $sql);

    $rowid = oci_new_descriptor($conn, OCI_D_ROWID);
    oci_bind_by_name($ins_stid, ":id_bv",   $id,    10);
    oci_bind_by_name($ins_stid, ":name_bv", $name,  32);
    oci_bind_by_name($ins_stid, ":rid",     $rowid, -1, OCI_B_ROWID);

    $sql = "UPDATE mytab SET salary = :salary WHERE ROWID = :rid";
    $upd_stid = oci_parse($conn, $sql);
    oci_bind_by_name($upd_stid, ":rid", $rowid, -1, OCI_B_ROWID);
    oci_bind_by_name($upd_stid, ":salary", $salary,   32);

    // ids y nombres a insertar
    $data = array(1111 => "Larry",
                  2222 => "Bill",
                  3333 => "Jim");

    // Salario de cada persona
    $salary = 10000;

    // Inserción y actualización inmediata de cada línea
    foreach ($data as $id => $name) {
        oci_execute($ins_stid);
        oci_execute($upd_stid);
    }

    $rowid->free();
    oci_free_statement($upd_stid);
    oci_free_statement($ins_stid);

    // Visualización de las nuevas líneas
    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid);
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        var_dump($row);
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #10 Asociación para una función almacenada PL/SQL

    <?php

    // Antes de ejecutar el programa PHP, una función almacenada debe ser creada
    // en formato SQL*Plus o SQL Developer :
    //
    //  CREATE OR REPLACE FUNCTION myfunc(p IN NUMBER) RETURN NUMBER AS
    //  BEGIN
    //      RETURN p * 3;
    //  END;

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $p = 8;

    $stid = oci_parse($conn, 'begin :r := myfunc(:p); end;');
    oci_bind_by_name($stid, ':p', $p);

    // El valor devuelto es un vínculo OUT. El tipo por omisión deberá ser
    // de tipo string, también, la asociación sobre una longitud de 40 significa
    // que la cadena devuelta tendrá como máximo 40 caracteres.
    oci_bind_by_name($stid, ':r', $r, 40);

    oci_execute($stid);

    print "$r\n";   // Muestra 24

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #11 Asociación de parámetros a un procedimiento almacenado PL/SQL

    <?php

    // Antes de ejecutar el programa PHP, un procedimiento almacenado debe ser creado
    // en formato SQL*Plus o SQL Developer :
    //
    //  CREATE OR REPLACE PROCEDURE myproc(p1 IN NUMBER, p2 OUT NUMBER) AS
    //  BEGIN
    //      p2 := p1 * 2;
    //  END;

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $p1 = 8;

    $stid = oci_parse($conn, 'begin myproc(:p1, :p2); end;');
    oci_bind_by_name($stid, ':p1', $p1);

    // El segundo parámetro del procedimiento almacenado es un vínculo OUT.
    // El tipo por omisión deberá ser de tipo string, también,
    // la asociación sobre una longitud de 40 significa
    // que la cadena devuelta tendrá como máximo 40 caracteres.

    oci_bind_by_name($stid, ':p2', $p2, 40);

    oci_execute($stid);

    print "$p2\n";   // Muestra 16

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #12 Asociación sobre una columna CLOB

    <?php

    // Antes de la ejecución, es necesario crear la tabla :
    //     CREATE TABLE mytab (mykey NUMBER, myclob CLOB);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $mykey = 12343;  // Clave arbitraria para el ejemplo ;

    $sql = "INSERT INTO mytab (mykey, myclob)
            VALUES (:mykey, EMPTY_CLOB())
            RETURNING myclob INTO :myclob";

    $stid = oci_parse($conn, $sql);
    $clob = oci_new_descriptor($conn, OCI_D_LOB);
    oci_bind_by_name($stid, ":mykey", $mykey, 5);
    oci_bind_by_name($stid, ":myclob", $clob, -1, OCI_B_CLOB);
    oci_execute($stid, OCI_DEFAULT);
    $clob->save("A very long string");

    oci_commit($conn);

    // Recuperación de los datos CLOB

    $query = 'SELECT myclob FROM mytab WHERE mykey = :mykey';

    $stid = oci_parse ($conn, $query);
    oci_bind_by_name($stid, ":mykey", $mykey, 5);
    oci_execute($stid);

    print '<table border="1">';
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_LOBS)) {
        print '<tr><td>'.$row['MYCLOB'].'</td></tr>';
        // En un bucle, el hecho de liberar la variable antes de la recuperación de
        // la línea siguiente reduce el uso de memoria de PHP
        unset($row);
    }
    print '</table>';

    ?>

Ejemplo #13 Asociación sobre un booleano en un script PL/SQL

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $plsql =
      "begin
        :output1 := true;
        :output2 := false;
       end;";

    $s = oci_parse($c, $plsql);
    oci_bind_by_name($s, ':output1', $output1, -1, OCI_B_BOL);
    oci_bind_by_name($s, ':output2', $output2, -1, OCI_B_BOL);
    oci_execute($s);
    var_dump($output1);  // true
    var_dump($output2);  // false

    ?>

### Notas

Advertencia

No utilice la función addslashes() y oci_bind_by_name() simultáneamente, ya que no es necesario añadir comillas. Si es así, entonces las comillas añadidas serán escritas en la base de datos ; de hecho, la función oci_bind_by_name() inserta los datos sin procesar y no elimina ni las comillas añadidas, ni los caracteres de escape.

> Nota:

> Si asocia una cadena de caracteres a una columna de tipo `CHAR` en una cláusula `WHERE`, recuerde que Oracle utiliza una comparación añadiendo caracteres vacíos para las columnas de tipo `CHAR`. Por lo tanto, su variable PHP debe ser completada con caracteres vacíos para alcanzar la misma longitud que la columna para que la cláusula `WHERE` funcione.

> Nota:

> El argumento PHP `var` es una referencia. Por lo tanto, algunos formatos de bucle pueden no funcionar como se espera :

>     <?php
>     foreach ($myarray as $key => $value)  {
>         oci_bind_by_name($stid, $key, $value);
>     }
>     ?>

> Esto asocia cada clave al valor apuntado por $value, por lo tanto, todas las variables asociadas apuntan hacia el valor de la última iteración del bucle. En su lugar, utilice esto :

>     <?php
>     foreach ($myarray as $key => $value) {
>         oci_bind_by_name($stid, $key, $myarray[$key]);
>     }
>     ?>

### Ver también

- oci_bind_array_by_name() - Asocia un array PHP a un parámetro de array Oracle PL/SQL
- oci_parse() - Prepara una consulta SQL con Oracle

# oci_cancel

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_cancel — Cancela la lectura del cursor

### Descripción

function oci_cancel(resource `$statement`): bool

Invalida un cursor, liberando todos los recursos asociados y cancela la capacidad para leer desde él.

### Parámetros

`statement`

  Una sentencia de OCI.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# oci_client_version

(PHP 5 >= 5.3.7, PHP 7, PHP 8, PECL OCI8 >= 1.4.6)

oci_client_version — Devuelve la versión de la biblioteca cliente Oracle

### Descripción

function oci_client_version(): string

Devuelve un string que contiene el número de versión de la biblioteca cliente Oracle C, a la cual PHP está ligada.

### Parámetros

Ninguno.

### Valores devueltos

Devuelve el número de versión, en forma de un string.

### Ejemplos

Ejemplo #1 Ejemplo con oci_client_version()

    <?php
        echo "Client Version: " . oci_client_version(); // Versión del cliente: 19.9.0.0.0
    ?>

### Notas

> Nota:

> Las bibliotecas Oracle anteriores a la 10gR2 no poseían funcionalidad interna para recuperar el número de versión de la biblioteca. La cadena "Unknow" será devuelta en este caso.

### Ver también

- oci_server_version() - Devuelve la versión del servidor Oracle

# oci_close

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_close — Cierra una conexión Oracle

### Descripción

function oci_close(resource `$connection`): ?bool

Cierra una conexión `connection` Oracle. La conexión será cerrada si ninguna recurso la utiliza y si fue creada con la función oci_connect() o la función oci_new_connect().

Se recomienda cerrar las conexiones que ya no sean necesarias, liberando así más recursos para otros usuarios.

### Parámetros

`connection`

  Un identificador de conexión Oracle, retornado por la función oci_connect(), oci_pconnect(), o oci_new_connect().

### Valores devueltos

Retorna `null` cuando oci8.old_oci_close_semantics está activado, `true` en caso contrario.

### Ejemplos

Ejemplo #1 Cierre de una conexión

Los recursos asociados con una conexión deben ser cerrados para asegurar a la base de datos subyacente el fin de las operaciones y así liberar los recursos.

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM departments');
    $r = oci_execute($stid);
    oci_fetch_all($stid, $res);
    var_dump($res);

    // Liberación del identificador de consulta al cerrar la conexión
    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #2 Las conexiones a la base de datos son cerradas cuando las referencias lo son

El identificador interno que cuenta las conexiones debe valer cero para poder cerrar la conexión.

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM departments');  // esto incrementa el contador interno $conn
    oci_execute($stid);
    oci_fetch_all($stid, $res);
    var_dump($res);

    oci_close($conn);

    // $conn ya no es utilizable en el script pero la conexión subyacente a
    // la base de datos sigue abierta mientras $stid no sea liberada.
    var_dump($conn);  // muestra NULL

    // Mientras PHP espera, el hecho de consultar la vista V$SESSION de Oracle
    // en un terminal mostrará que un usuario sigue conectado.
    sleep(10);

    // Cuando $stid es liberada, la conexión a la base de datos será físicamente cerrada
    oci_free_statement($stid);

    // Mientras PHP espera, el hecho de consultar la vista V$SESSION de Oracle
    // en un terminal mostrará que el usuario se ha desconectado.
    sleep(10);

    ?>

Ejemplo #3 Cierre de una conexión abierta más de una vez

Cuando se reutilizan identificadores de base de datos, todas las conexiones deben ser cerradas antes de que la conexión subyacente a la base de datos lo sea realmente.

    <?php

    $conn1 = oci_connect('hr', 'welcome', 'localhost/XE');

    // La utilización de los mismos identificadores reutiliza la misma conexión subyacente a la base de datos.
    // Todas las modificaciones no confirmadas realizadas sobre $conn1 serán visibles sobre $conn2.
    $conn2 = oci_connect('hr', 'welcome', 'localhost/XE');

    // Mientras PHP espera, el hecho de consultar la vista V$SESSION de Oracle
    // en un terminal mostrará que un solo usuario está conectado.
    sleep(10);

    oci_close($conn1); // no cierra la conexión subyacente a la base de datos
    var_dump($conn1);  // muestra NULL ya que la variable $conn1 ya no es utilizable
    var_dump($conn2);  // muestra que $conn2 sigue siendo un recurso de conexión válido

    ?>

Ejemplo #4 Las conexiones son cerradas cuando las variables salen del contexto

Cuando todas las variables que referencian una conexión salen del contexto y son liberadas por PHP, se produce un rollback (si es necesario) y la conexión subyacente a la base de datos es cerrada.

    <?php

    function myfunc() {
        $conn = oci_connect('hr', 'hrpwd', 'localhost/XE');
        if (!$conn) {
            $e = oci_error();
            trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
        }

        $stid = oci_parse($conn, 'UPDATE mytab SET id = 100');
        oci_execute($stid, OCI_NO_AUTO_COMMIT);
        return "Finished";
    }

    $r = myfunc();
    // En este momento, se produce un rollback y la conexión subyacente a la base de datos es cerrada.

    print $r;  // muestra el valor de retorno de la función "Finished"

    ?>

### Notas

> Nota:

> Las variables que dependen del identificador de conexión, como los identificadores de consulta retornados por la función oci_parse(), deben ser liberadas antes de intentar cerrar la conexión subyacente a la base de datos.

> Nota:

> La función oci_close() no cierra las conexiones subyacentes a la base de datos creadas por la función oci_pconnect().

### Ver también

- oci_connect() - Establece una conexión con un servidor Oracle
- oci_free_statement() - Libera todos los recursos asociados con una sentencia o cursor

# oci_commit

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_commit — Valida las transacciones Oracle en curso

### Descripción

function oci_commit(resource `$connection`): bool

Valida todas las transacciones en curso en la conexión Oracle `connection`. Una validación hace permanentes todas las modificaciones, liberando todos los bloqueos.

Una transacción comienza cuando se ejecuta la primera consulta SQL que modifica datos con la función oci_execute() utilizando el flag `OCI_NO_AUTO_COMMIT`. Las modificaciones siguientes realizadas por otras consultas forman parte de la misma transacción. Los datos modificados por una transacción son temporales hasta que la transacción sea validada o revertida. Otros usuarios de la base de datos no verán estas modificaciones hasta que la transacción sea validada.

Al insertar o actualizar datos, el uso de transacciones es recomendado para garantizar la consistencia relacional de los datos, así como para mejorar el rendimiento.

### Parámetros

`connection`

  Un identificador de conexión Oracle, devuelto por la función oci_connect(), oci_pconnect(), o oci_new_connect().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con oci_commit()

    <?php

    // Inserción en múltiples tablas, con cancelación de las modificaciones si ocurren errores

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, "INSERT INTO mysalary (id, name) VALUES (1, 'Chris')");

    // El flag OCI_NO_AUTO_COMMIT indica a Oracle que no valide las inserciones automáticamente.
    $r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
    if (!$r) {
        $e = oci_error($stid);
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'INSERT INTO myschedule (startday) VALUES (12)');
    $r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
    if (!$r) {
        $e = oci_error($stid);
        oci_rollback($conn);  // Cancelación de las modificaciones en las 2 tablas
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    // Valida las modificaciones en las 2 tablas
    $r = oci_commit($conn);
    if (!$r) {
        $e = oci_error($conn);
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    ?>

### Notas

> Nota:

> Las transacciones son automáticamente revertidas al cerrar la conexión, o cuando el script finaliza, cualquiera de los dos que ocurra primero. Debe llamarse explícitamente a la función oci_commit() para validar la transacción.

> Cada llamada a la función oci_execute() que utiliza el modo `OCI_COMMIT_ON_SUCCESS` explícitamente o por omisión, validará todas las transacciones no validadas hasta ese punto.

> Todas las consultas Oracle como `CREATE` o `DROP` también validarán todas las transacciones no validadas.

### Ver también

- oci_execute() - Ejecuta un comando SQL de Oracle
- oci_rollback() - Anula las transacciones Oracle en curso

# oci_connect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_connect — Establece una conexión con un servidor Oracle

### Descripción

function oci_connect(
string `$username`,
string `$password`,
?string `$connection_string` = `null`,
string `$encoding` = "",
int `$session_mode` = `OCI_DEFAULT`
): resource|false

Devuelve un identificador de conexión, necesario para la mayoría de las llamadas OCI8.

Para mejorar el rendimiento, la mayoría de las aplicaciones deberían utilizar conexiones persistentes con oci_pconnect() en lugar de oci_connect(). Consulte la sección sobre la gestión de conexiones para obtener información general sobre la gestión de conexiones y el agrupamiento de conexiones.

Las llamadas siguientes (tras la primera) a la función oci_connect() con los mismos parámetros devolverán el manejador de conexión devuelto en la primera llamada. Esto significa que las transacciones realizadas sobre un manejador estarán activas en los demás, siempre que utilicen la misma conexión subyacente. Si 2 manejadores deben tener transacciones aisladas, utilice en su lugar la función oci_new_connect().

### Parámetros

`username`

  El nombre de usuario de Oracle.

`password`

  La contraseña del usuario.

`connection_string`
  Contiene la instancia `Oracle` a la que debemos conectarnos. Esto puede ser una » cadena de conexión rápida, un nombre de conexión del archivo tnsnames.ora, o el nombre de una instancia local Oracle. Si no se especifica o es `null`, PHP utiliza variables de entorno como `TWO_TASK` (en Linux) o `LOCAL` (en Windows) y `ORACLE_SID` para determinar la instancia `Oracle` a la que debemos conectarnos. Para usar el método de conexión rápida, PHP debe estar vinculado con la biblioteca cliente Oracle 10g o superior. La cadena de conexión rápida para Oracle 10g o superior es de la forma: [//]host_name[:port][/service_name]. Desde Oracle 11g, la sintaxis es: [//]host_name[:port][/service_name][:server_type][/instance_name]. Opciones adicionales fueron introducidas con Oracle 19c Los nombres de los servicios pueden ser encontrados ejecutando la utilidad Oracle `lsnrctl status` en la máquina que ejecuta la base de datos. El archivo tnsnames.ora puede estar en el camino de búsqueda de Oracle Net, que incluye /your/path/to/instantclient/network/admin, $ORACLE_HOME/network/admin y /etc. Una solución alternativa sería definir `TNS_ADMIN` para que el archivo $TNS_ADMIN/tnsnames.ora sea leído. Asegúrese de que el demonio que ejecuta el servidor web tenga acceso de lectura a este archivo.
`encoding`
  Determina el juego de caracteres utilizado por la biblioteca cliente Oracle. El juego de caracteres no necesita ser idéntico al utilizado por la base de datos. Si no coincide, Oracle hará lo mejor posible para convertir los datos desde el juego de caracteres de la base de datos. Dependiendo de los juegos de caracteres, el resultado puede no ser perfecto. Además, esta conversión requiere un poco de tiempo del sistema. Si no se especifica, la biblioteca cliente Oracle determinará un juego de caracteres desde la variable de entorno `NLS_LANG`. Pasar este parámetro puede reducir el tiempo de conexión.
`session_mode`
  Este parámetro está disponible a partir de PHP 5 (PECL OCI8 1.1) y acepta los siguientes valores: `OCI_DEFAULT`, `OCI_SYSOPER` y `OCI_SYSDBA`. Si bien la constante `OCI_SYSOPER` o la constante `OCI_SYSDBA` es especificada, esta función intentará establecer una conexión privilegiada usando identidades externas. Las conexiones privilegiadas están desactivadas por omisión. Para activarlas, debe definir la opción oci8.privileged_connect a `On`. PHP 5.3 (PECL OCI8 1.3.4) introducen el valor de modo `OCI_CRED_EXT`. Este modo solicita a Oracle usar una identificación externa o bien del sistema operativo, que debe ser configurada en la base de datos. El flag `OCI_CRED_EXT` solo puede ser usado con el nombre de usuario "/" asociado a una contraseña vacía. La opción oci8.privileged_connect puede ser definida a `On` o `Off`. `OCI_CRED_EXT` puede ser combinado con el modo `OCI_SYSOPER` o el modo `OCI_SYSDBA`. `OCI_CRED_EXT` no es soportado en Windows por razones de seguridad.

### Valores devueltos

Devuelve un identificador de conexión o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | `connection_string` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con oci_connect() utilizando la sintaxis simplificada

    <?php

    // Conexión al servicio XE (es decir, la base de datos) en la máquina "localhost"
    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Ejemplo #2 Ejemplo con oci_connect() utilizando un nombre de conexión de red

    <?php

    // Conexión a la base de datos MYDB descrita en el archivo tnsnames.ora,
    // Un ejemplo de entrada tnsnames.ora para MYDB podría ser:
    //   MYDB =
    //     (DESCRIPTION =
    //       (ADDRESS = (PROTOCOL = TCP)(HOST = mymachine.oracle.com)(PORT = 1521))
    //       (CONNECT_DATA =
    //         (SERVER = DEDICATED)
    //         (SERVICE_NAME = XE)
    //       )
    //     )

    $conn = oci_connect('hr', 'welcome', 'MYDB');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Ejemplo #3 Ejemplo con oci_connect() utilizando un juego de caracteres específico

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE', 'AL32UTF8');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Ejemplo #4 Ejemplo con múltiples llamadas a la función oci_connect()

    <?php

    $c1 = oci_connect("hr", "welcome", 'localhost/XE');
    $c2 = oci_connect("hr", "welcome", 'localhost/XE');

    // Tanto $c1 como $c2 muestran el mismo identificador de recursos PHP, lo que significa
    // que se trata de la misma conexión a la base de datos
    echo "c1 is $c1<br>\n";
    echo "c2 is $c2<br>\n";

    function create_table($conn)
    {
        $stmt = oci_parse($conn, "create table hallo (test varchar2(64))");
        oci_execute($stmt);
        echo "Created table<br>\n";
    }

    function drop_table($conn)
    {
        $stmt = oci_parse($conn, "drop table hallo");
        oci_execute($stmt);
        echo "Dropped table<br>\n";
    }

    function insert_data($connname, $conn)
    {
        $stmt = oci_parse($conn, "insert into hallo
                  values(to_char(sysdate,'DD-MON-YY HH24:MI:SS'))");
        oci_execute($stmt, OCI_DEFAULT);
        echo "$connname inserted row without committing<br>\n";
    }

    function rollback($connname, $conn)
    {
        oci_rollback($conn);
        echo "$connname rollback<br>\n";
    }

    function select_data($connname, $conn)
    {
        $stmt = oci_parse($conn, "select * from hallo");
        oci_execute($stmt, OCI_DEFAULT);
        echo "$connname ----selecting<br>\n";
        while (oci_fetch($stmt)) {
            echo "    " . oci_result($stmt, "TEST") . "<br>\n";
        }
        echo "$connname ----done<br>\n";
    }

    create_table($c1);

    insert_data('c1', $c1);   // Inserta una fila utilizando c1
    sleep(2);                 // Se espera para ver un timestamp diferente para la segunda fila
    insert_data('c2', $c2);   // Inserta una fila utilizando c2

    select_data('c1', $c1);   // Se devuelven los resultados de las 2 inserciones
    select_data('c2', $c2);   // Se devuelven los resultados de las 2 inserciones

    rollback('c1', $c1);      // Revertir la transacción utilizando c1

    select_data('c1', $c1);   // Las 2 inserciones han sido revertidas
    select_data('c2', $c2);

    drop_table($c1);

    // El cierre de una conexión hace que las variables PHP sean inaccesibles, pero las demás
    // pueden seguir siendo utilizadas
    oci_close($c1);
    echo "c1 is $c1<br>\n";
    echo "c2 is $c2<br>\n";

    // Salida:
    //    c1 is Resource id #5
    //    c2 is Resource id #5
    //    Created table
    //    c1 inserted row without committing
    //    c2 inserted row without committing
    //    c1 ----selecting
    //        09-DEC-09 12:14:43
    //        09-DEC-09 12:14:45
    //    c1 ----done
    //    c2 ----selecting
    //        09-DEC-09 12:14:43
    //        09-DEC-09 12:14:45
    //    c2 ----done
    //    c1 rollback
    //    c1 ----selecting
    //    c1 ----done
    //    c2 ----selecting
    //    c2 ----done
    //    Dropped table
    //    c1 is
    //    c2 is Resource id #5

    ?>

### Notas

> Nota:

> Si ha ocurrido un problema durante la instalación de la extensión OCI8, una de las manifestaciones será un problema durante la conexión. Consulte la sección Instalación/Configuración para obtener más información en caso de errores.

### Ver también

- oci_pconnect() - Establece una conexión persistente a un servidor Oracle
- oci_new_connect() - Conexión al servidor Oracle utilizando una sola conexión
- oci_close() - Cierra una conexión Oracle

# oci_define_by_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_define_by_name — Asocia una variable PHP con una columna para una consulta de recuperación de datos

### Descripción

function oci_define_by_name(
resource `$statement`,
string `$column`,
mixed `&$var`,
int `$type` = 0
): bool

Asocia una variable PHP con una columna para una consulta de recuperación de datos utilizando la función oci_fetch().

La llamada a la función oci_define_by_name() debe realizarse antes de la ejecución de la función oci_execute().

### Parámetros

`statement`
  Un identificador de consulta OCI8 creado por la función oci_parse() y ejecutado por la función oci_execute(), o un identificador de consulta `REF CURSOR`.
`column`

  El nombre de la columna utilizado en la consulta.

  Utilice un nombre en mayúsculas para los nombres de columna no sensibles a la casilla (por omisión bajo Oracle). Utilice la casilla exacta del nombre de la columna para los nombres de columna sensibles a la casilla.

`var`

  La variable PHP que contendrá el valor devuelto por la columna.

`type`

  El tipo de datos a devolver. En general, este argumento no es necesario. Tenga en cuenta que el estilo Oracle de conversión de datos no se aplica aquí. Por ejemplo, `SQLT_INT` será ignorado y el tipo de datos devuelto será `SQLT_CHR`.

  Puede utilizar, opcionalmente, la función oci_new_descriptor() para asignar descriptores LOB/ROWID/BFILE.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con oci_define_by_name()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
    $stid = oci_parse($conn, $sql);

    // Las definiciones DEBEN realizarse antes de la ejecución de la consulta
    oci_define_by_name($stid, 'LOCATION_ID', $locid);
    oci_define_by_name($stid, 'CITY', $city);

    oci_execute($stid);

    // Cada recuperación poblará las variables previamente definidas con los datos de la siguiente línea
    while (oci_fetch($stid)) {
        echo "Location id $locid is $city<br>\n";
    }

    // Muestra:
    //   Location id 1000 is Roma
    //   Location id 1100 is Venice

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #2 Ejemplo con oci_define_by_name() y nombres de columna sensibles a la casilla

    <?php

    /*
      Antes de la ejecución, cree la tabla siguiente con un nombre de columna sensible a la casilla:
        CREATE TABLE mytab (id NUMBER, "MyDescription" VARCHAR2(30));
        INSERT INTO mytab (id, "MyDescription") values (1, 'Iced Coffee');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM mytab');

    // Utilice mayúsculas para los nombres de columna no sensibles a la casilla
    oci_define_by_name($stid, 'ID', $id);

    // Utilice la casilla exacta para los nombres de columnas sensibles a la casilla
    oci_define_by_name($stid, 'MyDescription', $mydesc);

    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo "id $id is $mydesc<br>\n";
    }

    // Muestra:
    //   id 1 is Iced Coffee

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #3 Ejemplo con oci_define_by_name() y columnas de tipo LOB

    <?php

    /*
      Antes de la ejecución, cree la tabla siguiente:
        CREATE TABLE mytab (id NUMBER, fruit CLOB);
        INSERT INTO mytab (id, fruit) values (1, 'apple');
        INSERT INTO mytab (id, fruit) values (2, 'orange');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM mytab');

    // Las definiciones DEBEN realizarse antes de la ejecución
    oci_define_by_name($stid, 'ID', $id);
    oci_define_by_name($stid, 'FRUIT', $fruit);  // $fruit se convertirá en un descriptor LOB

    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo $id . " is " . $fruit->load(100) . "<br>\n";
    }

    // Muestra:
    //   1 is apple
    //   2 is orange

    $fruit->free();
    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #4 Ejemplo con oci_define_by_name() y un tipo explícito

    <?php

    /*
      Antes de la ejecución, cree la tabla siguiente:
        CREATE TABLE mytab (id NUMBER, fruit CLOB);
        INSERT INTO mytab (id, fruit) values (1, 'apple');
        INSERT INTO mytab (id, fruit) values (2, 'orange');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM mytab');

    // Las definiciones DEBEN realizarse antes de la ejecución
    oci_define_by_name($stid, 'ID', $id);

    $fruit = oci_new_descriptor($conn, OCI_D_LOB);
    oci_define_by_name($stid, 'FRUIT', $fruit, OCI_D_CLOB);

    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo $id . " is " . $fruit->load(100) . "<br>\n";
    }

    // Muestra:
    //   1 is apple
    //   2 is orange

    $fruit->free();
    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Ver también

- oci_fetch() - Lee la siguiente línea de un resultado Oracle en un buffer interno
- oci_new_descriptor() - Inicializa un nuevo puntero vacío de LOB/FILE de Oracle

# oci_error

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_error — Devuelve el último error de Oracle

### Descripción

function oci_error(?resource `$connection_or_statement` = `null`): array|false

Devuelve el último error de Oracle.

La función debe ser llamada inmediatamente después de que ocurra un error. Los errores son reinicializados después de una consulta exitosa.

### Parámetros

`connection_or_statement`

  Para la mayoría de los errores, el argumento `connection_or_statement` representa un recurso de conexión. Para los errores de conexión con las funciones oci_connect(), oci_new_connect() o oci_pconnect(), `null` debe ser pasado.

### Valores devueltos

Si no se encuentra ningún error, oci_error() devuelve `false`. De lo contrario, oci_error() devuelve la información sobre el error en forma de un array asociativo.

Descripción del array devuelto por oci_error()
Clave del array | Tipo | Descripción
--- | --- | ---
`code` | int | El número de error de Oracle.
`message` | string | El texto del error de Oracle.
`offset` | int | La posición del byte del error en la consulta SQL. Si no hay consulta, `0` será colocado como valor.
`sqltext` | string | El texto de la consulta SQL. Si no hay consulta, será una cadena vacía.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | `connection_or_statement` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo de visualización de un mensaje de error de Oracle después de un error de conexión

    <?php
    $conn = oci_connect("hr", "welcome", "localhost/XE");
    if (!$conn) {
        $e = oci_error();   // Para los errores oci_connect, no se pasa un manejador de conexión
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }
    ?>

Ejemplo #2 Ejemplo de visualización de un mensaje de error de Oracle después de un error de análisis

    <?php
    $stid = oci_parse($conn, "select ' from dual");  // Note el error con las comillas
    if (!$stid) {
        $e = oci_error($conn);  // Para los errores oci_parse, se pasa el manejador de conexión
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }
    ?>

Ejemplo #3 Ejemplo de visualización de un mensaje de error de Oracle después de un error de ejecución encontrado en una consulta SQL

    <?php
    $stid = oci_parse($conn, "select does_not_exist from dual");
    $r = oci_execute($stid);
    if (!$r) {
        $e = oci_error($stid);  // Para los errores oci_execute, se pasa el manejador de conexión
        print htmlentities($e['message']);
        print "\n<pre>\n";
        print htmlentities($e['sqltext']);
        printf("\n%".($e['offset']+1)."s", "^");
        print  "\n</pre>\n";
    }
    ?>

# oci_execute

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_execute — Ejecuta un comando SQL de Oracle

### Descripción

function oci_execute(resource `$statement`, int `$mode` = `OCI_COMMIT_ON_SUCCESS`): bool

Ejecuta una consulta `statement` previamente devuelta por la función oci_parse().

Tras la ejecución, las consultas como `INSERT` tendrán por omisión los datos validados (cometidos) en la base de datos. Para consultas como `SELECT`, la ejecución realiza la lógica de la consulta. Los resultados de la consulta pueden ser recuperados por PHP con funciones como oci_fetch_array().

Cada consulta analizada puede ser ejecutada varias veces, por lo que no es necesario analizarlas de nuevo. Esto es práctico para consultas de tipo `INSERT` cuando los datos están vinculados mediante la función oci_bind_by_name().

### Parámetros

`statement`

  Un identificador de consulta OCI válido.

`mode`

  Un segundo argumento opcional puede tomar una de las constantes siguientes:

  Modos de ejecución
  Constante | Descripción
  --- | ---
  `OCI_COMMIT_ON_SUCCESS` | Validación automática en la conexión cuando la consulta ha sido ejecutada con éxito. Este es el comportamiento por omisión.
  `OCI_DESCRIBE_ONLY` | Hace disponibles los metadatos de la consulta a funciones como oci_field_name() pero no crea un conjunto de resultados. Cualquier llamada a funciones de recuperación como oci_fetch_array() fallará.
  `OCI_NO_AUTO_COMMIT` | No valida automáticamente las modificaciones.

  El uso del modo `OCI_NO_AUTO_COMMIT` inicia o continúa una transacción. Las transacciones son automáticamente anuladas cuando la conexión se cierra o cuando el script termina. Llame explícitamente a la función oci_commit() para validar la transacción o a la función oci_rollback() para anularla.

  Al insertar o actualizar datos, el uso de transacciones es altamente recomendado para garantizar la consistencia relacional de los datos, así como por un significativo aumento de rendimiento.

  Si el modo `OCI_NO_AUTO_COMMIT` es utilizado para todas las operaciones incluyendo consultas, y las funciones oci_commit() y oci_rollback() nunca son llamadas, OCI8 realizará una anulación al final del script incluso si los datos han cambiado. Para evitar este comportamiento, la mayoría de los scripts no utiliza el modo `OCI_NO_AUTO_COMMIT` para consultas o procedimientos almacenados PL/SQL. Asegúrese de la consistencia transaccional apropiada de sus aplicaciones al utilizar la función oci_execute() con diferentes modos en el mismo script.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con oci_execute() para consultas

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Ejemplo #2 Ejemplo con oci_execute() sin especificar modo

    <?php

    // Antes de la ejecución, cree la tabla:
    //   CREATE TABLE MYTABLE (col1 NUMBER);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (123)');

    oci_execute($stid); // La fila es validada y es inmediatamente visible por otros usuarios

    ?>

Ejemplo #3 Ejemplo con oci_execute() y `OCI_NO_AUTO_COMMIT`

    <?php

    // Antes de la ejecución, cree la tabla:
    //   CREATE TABLE MYTABLE (col1 NUMBER);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (:bv)');
    oci_bind_by_name($stid, ':bv', $i, 10);
    for ($i = 1; $i <= 5; ++$i) {
        oci_execute($stid, OCI_NO_AUTO_COMMIT);
    }
    oci_commit($conn);  // valida todos los nuevos valores: 1, 2, 3, 4, 5

    ?>

Ejemplo #4 Ejemplo con oci_execute() y diferentes modos en el mismo script

    <?php

    // Antes de la ejecución, cree la tabla:
    //   CREATE TABLE MYTABLE (col1 NUMBER);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (123)');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);  // datos no cometidos

    $stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (456)');
    oci_execute($stid);  // valida tanto los valores 123 como 456

    ?>

Ejemplo #5 Ejemplo con oci_execute() y `OCI_DESCRIBE_ONLY`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT * FROM locations');
    oci_execute($s, OCI_DESCRIBE_ONLY);
    for ($i = 1; $i <= oci_num_fields($stid); ++$i) {
        echo oci_field_name($stid, $i) . "<br>\n";
    }

    ?>

### Notas

> Nota:

> Las transacciones son automáticamente anuladas cuando las conexiones se cierran, o cuando el script termina, según lo que ocurra primero. Llame explícitamente a la función oci_commit() para validar una transacción.

> Cualquier llamada a la función oci_execute() que utilice el modo `OCI_COMMIT_ON_SUCCESS` explícita o implícitamente validará todas las transacciones en curso.

> Todas las consultas Oracle DDL como `CREATE` o `DROP` validarán todas las transacciones en curso.

> Nota:

> Debido a que la función oci_execute() generalmente envía la consulta a la base de datos, la función oci_execute() puede identificar errores de sintaxis de la consulta que la función oci_parse() pudo no detectar.

### Ver también

- oci_parse() - Prepara una consulta SQL con Oracle

# oci_fetch

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch — Lee la siguiente línea de un resultado Oracle en un buffer interno

### Descripción

function oci_fetch(resource `$statement`): bool

Lee la siguiente línea de una consulta en un buffer interno accesible bien mediante la función oci_result(), o utilizando las variables previamente definidas con la función oci_define_by_name().

Consulte la función oci_fetch_array() para obtener información genérica sobre la recuperación de datos.

### Parámetros

`statement`
  Un identificador de consulta OCI8 creado por la función oci_parse() y ejecutado por la función oci_execute(), o un identificador de consulta `REF CURSOR`.

### Valores devueltos

Devuelve `true` en caso de éxito, o `false` si no hay más líneas disponibles para la consulta `statement`.

### Ejemplos

Ejemplo #1 Ejemplo con oci_fetch() y variables definidas

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
    $stid = oci_parse($conn, $sql);

    // La definición debe realizarse ANTES de la ejecución
    oci_define_by_name($stid, 'LOCATION_ID', $locid);
    oci_define_by_name($stid, 'CITY', $city);

    oci_execute($stid);

    // Cada recuperación utiliza las variables previamente definidas con los datos de la siguiente línea
    while (oci_fetch($stid)) {
        echo "Location id $locid is $city<br>\n";
    }

    // Muestra:
    //   Location id 1000 is Roma
    //   Location id 1100 is Venice

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #2 Ejemplo con oci_fetch() y oci_result()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo oci_result($stid, 'LOCATION_ID') . " is ";
        echo oci_result($stid, 'CITY') . "<br>\n";
    }

    // Muestra:
    //   1000 is Roma
    //   1100 is Venice

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Notas

> Nota:

> Esta función no devolverá líneas desde el conjunto de resultados implícito de una base de datos Oracle. Utilice en su lugar la función oci_fetch_array().

### Ver también

- oci_define_by_name() - Asocia una variable PHP con una columna para una consulta de recuperación de datos
- oci_fetch_all() - Lee múltiples líneas de un resultado en un array multidimensional
- oci_fetch_array() - Lee una línea de un resultado en forma de array asociativo o numérico
- oci_fetch_assoc() - Lee una línea de un resultado en forma de array asociativo
- oci_fetch_object() - Lee una línea de un resultado en forma de objeto
- oci_fetch_row() - Lee la siguiente línea de una consulta en forma de array numérico
- oci_result() - Devuelve el valor de una columna en un resultado Oracle

# oci_fetch_all

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_all — Lee múltiples líneas de un resultado en un array multidimensional

### Descripción

function oci_fetch_all(
resource `$statement`,
array `&$output`,
int `$offset` = 0,
int `$limit` = -1,
int `$flags` = OCI_FETCHSTATEMENT_BY_COLUMN | OCI_ASSOC
): int

Lee todas las líneas de un resultado Oracle en un array de 2 dimensiones. Por omisión, se devuelven todas las líneas.

Esta función puede ser llamada una sola vez para cada consulta ejecutada mediante la función oci_execute().

### Parámetros

`statement`
  Un identificador de consulta OCI8 creado por la función oci_parse() y ejecutado por la función oci_execute(), o un identificador de consulta `REF CURSOR`.
`output`

  La variable que contendrá las líneas devueltas.

  Las columnas LOB se devuelven en forma de string cuando Oracle soporta la conversión.

  Ver la función oci_fetch_array() para más información sobre cómo se recuperan los datos y sus tipos.

`offset`

  Número de líneas iniciales a ignorar al leer el resultado. Por omisión, este parámetro vale 0, para comenzar la lectura en la primera línea.

`limit`

  Número máximo de líneas a devolver. Por omisión, vale -1, lo que significa que todas las líneas disponibles serán devueltas desde el parámetro `offset` + 1.

`flags`

  El parámetro `flags` indica la estructura del array pero también si deben usarse arrays asociativos.

  Modos de estructura de arrays para la función oci_fetch_all()
  Constante | Descripción
  --- | ---
  `OCI_FETCHSTATEMENT_BY_ROW` | El array devuelto contendrá un solo subarray por líneas.
  `OCI_FETCHSTATEMENT_BY_COLUMN` | El array devuelto contendrá un solo subarray por columnas. Este es el comportamiento por omisión.

  Los arrays pueden ser indexados ya sea por el encabezado de columna, o numéricamente.

  Modos de indexación de arrays para la función oci_fetch_all()
  Constante | Descripción
  --- | ---
  `OCI_NUM` | Se usan índices numéricos para cada array de columnas.
  `OCI_ASSOC` | Se usan índices asociativos para cada array de columnas. Este es el comportamiento por omisión.

  Utilice el operador de adición ""+"" para elegir una combinación de estructuras de arrays y modos de indexación.

  Los nombres de columnas que no son sensibles a mayúsculas/minúsculas (por omisión en Oracle), tendrán nombres de atributos en mayúsculas. Los nombres de columnas que son sensibles a mayúsculas/minúsculas, tendrán nombres de atributos usando exactamente la misma casilla de la columna. Utilice la función var_dump() en el objeto de resultado para verificar la casilla apropiada a usar para cada consulta.

  Las consultas que poseen más de una columna con el mismo nombre deben usar alias. De lo contrario, solo una de las columnas aparecerá en el array asociativo.

### Valores devueltos

Devuelve el número de líneas recuperadas en el parámetro `output` que puede ser 0 o más.

### Ejemplos

Ejemplo #1 Ejemplo con oci_fetch_all()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
    oci_execute($stid);

    $nrows = oci_fetch_all($stid, $res);

    echo "$nrows rows fetched<br>\n";
    var_dump($res);

    // var_dump mostrará:
    //    2 rows fetched
    //    array(2) {
    //      ["POSTAL_CODE"]=>
    //      array(2) {
    //        [0]=>
    //        string(6) "00989x"
    //        [1]=>
    //        string(6) "10934x"
    //      }
    //      ["CITY"]=>
    //      array(2) {
    //        [0]=>
    //        string(4) "Roma"
    //        [1]=>
    //        string(6) "Venice"
    //      }
    //    }

    // Mostrar resultados
    echo "<table border='1'>\n";
    foreach ($res as $col) {
        echo "<tr>\n";
        foreach ($col as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #2 Ejemplo con oci_fetch_all() y `OCI_FETCHSTATEMENT_BY_ROW`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
    oci_execute($stid);

    $nrows = oci_fetch_all($stid, $res, null, null, OCI_FETCHSTATEMENT_BY_ROW);

    echo "$nrows líneas recuperadas<br>\n";
    var_dump($res);

    // Muestra:
    //    2 líneas recuperadas
    //    array(2) {
    //      [0]=>
    //      array(2) {
    //        ["POSTAL_CODE"]=>
    //        string(6) "00989x"
    //        ["CITY"]=>
    //        string(4) "Roma"
    //      }
    //      [1]=>
    //      array(2) {
    //        ["POSTAL_CODE"]=>
    //        string(6) "10934x"
    //        ["CITY"]=>
    //        string(6) "Venice"
    //      }
    //    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #3 Ejemplo con oci_fetch_all() y `OCI_NUM`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
    oci_execute($stid);

    $nrows = oci_fetch_all($stid, $res, null, null, OCI_FETCHSTATEMENT_BY_ROW + OCI_NUM);

    echo "$nrows líneas recuperadas<br>\n";
    var_dump($res);

    // Muestra:
    //    2 líneas recuperadas
    //    array(2) {
    //      [0]=>
    //      array(2) {
    //        [0]=>
    //        string(6) "00989x"
    //        [1]=>
    //        string(4) "Roma"
    //      }
    //      [1]=>
    //      array(2) {
    //        [0]=>
    //        string(6) "10934x"
    //        [1]=>
    //        string(6) "Venice"
    //      }
    //    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Notas

> Nota:

> El uso del parámetro `offset` es realmente ineficiente. Todas las líneas a evitar están incluidas en el conjunto de resultados devuelto por la base de datos a PHP. Luego, son descartadas. Es más eficiente usar una consulta SQL para restringir el alcance de las líneas deseadas. Ver la función oci_fetch_array() para un ejemplo concreto.

> Nota:

> Las consultas que devuelven un número muy grande de líneas pueden ahorrar memoria al usar funciones que recuperan una sola línea, como hace la función oci_fetch_array().

> Nota: Para las consultas que devuelven un número muy grande de líneas, el rendimiento puede ser muy significativamente mejorado aumentando el valor de la opción oci8.default_prefetch o usando la función oci_set_prefetch().

> Nota:

> Esta función no devolverá líneas desde un conjunto de resultados implícito de una base de datos Oracle 12c. Utilice en su lugar la función oci_fetch_array().

### Ver también

- oci_fetch() - Lee la siguiente línea de un resultado Oracle en un buffer interno
- oci_fetch_array() - Lee una línea de un resultado en forma de array asociativo o numérico
- oci_fetch_assoc() - Lee una línea de un resultado en forma de array asociativo
- oci_fetch_object() - Lee una línea de un resultado en forma de objeto
- oci_fetch_row() - Lee la siguiente línea de una consulta en forma de array numérico
- oci_set_prefetch() - Indica el número de filas que deben leerse por adelantado por Oracle

# oci_fetch_array

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_array — Lee una línea de un resultado en forma de array asociativo o numérico

### Descripción

function oci_fetch_array(resource `$statement`, int `$mode` = OCI_BOTH | OCI_RETURN_NULLS): array|false

Devuelve un array que contiene la siguiente línea de una consulta. Cada entrada de este array corresponde a una columna de la línea. Esta función se utiliza típicamente en un ciclo que devuelve `false` cuando ya no hay más líneas disponibles.

Si el parámetro `statement` corresponde a un bloque PL/SQL devuelto por juegos de resultados implícitos de Oracle Database, entonces las líneas de todos los juegos de resultados serán recuperadas consecutivamente. Si `statement` es devuelto por la función oci_get_implicit_resultset(), entonces solo el subconjunto de líneas de una sola consulta hija será devuelto.

Para más detalles sobre el mapeo de tipos de datos realizado por la extensión OCI8, lea los tipos de datos soportados por el driver.

### Parámetros

`statement`
  Un identificador de consulta OCI8 creado por la función oci_parse() y ejecutado por la función oci_execute(), o un identificador de consulta `REF CURSOR`.

  Puede ser también un identificador de consulta devuelto por la función oci_get_implicit_resultset().

`mode`

  El parámetro opcional `mode` puede ser la combinación de las siguientes constantes:

  Modos para oci_fetch_array()
  Constante | Descripción
  --- | ---
  `OCI_BOTH` | Devuelve un array, indexado numéricamente y con los nombres de columnas. Idéntico a `OCI_ASSOC` + `OCI_NUM`). Este es el comportamiento por defecto.
  `OCI_ASSOC` | Devuelve un array asociativo.
  `OCI_NUM` | Devuelve un array indexado numéricamente.
  `OCI_RETURN_NULLS` | Crea elementos vacíos para los valores `null`. El valor de los elementos será el valor `null` de PHP.
  `OCI_RETURN_LOBS` | Devuelve el contenido del LOB en lugar de su descriptor.

  El `mode` por defecto es `OCI_BOTH`.

  Utilice el operador de adición ""+"" para especificar más de un modo a la vez.

### Valores devueltos

Devuelve un array con índices numéricos o asociativos. Si ya no hay más líneas disponibles para la consulta `statement` entonces `false` será devuelto.

Por defecto, las columnas `LOB` son devueltas en forma de descriptores LOB.

Las columnas `DATE` son devueltas en forma de una cadena con el formato de fecha actual. El formato por defecto puede ser modificado mediante las variables de entorno de Oracle, como `NLS_LANG` o mediante la ejecución del comando `ALTER SESSION SET NLS_DATE_FORMAT`.

Los nombres de columnas que no son sensibles a mayúsculas/minúsculas (por defecto en Oracle), tendrán nombres de atributos en mayúsculas. Los nombres de columnas que son sensibles a mayúsculas/minúsculas, tendrán nombres de atributos utilizando exactamente la misma mayúscula/minúscula de la columna. Utilice la función var_dump() sobre el objeto de resultado para verificar la mayúscula/minúscula apropiada a utilizar para cada consulta.

El nombre de la tabla no está incluido en el índice del array. Si su consulta contiene dos columnas diferentes con el mismo nombre, utilice la constante `OCI_NUM` o añada un alias a la columna en la consulta para asegurar la unicidad del nombre; ver el ejemplo #7. De lo contrario, solo una columna será devuelta mediante PHP.

### Ejemplos

Ejemplo #1 Ejemplo con oci_fetch_array() con `OCI_BOTH`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT department_id, department_name FROM departments');
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_BOTH)) != false) {
        // Utilice nombres de columna en mayúsculas para los índices del array asociativo
        echo $row[0] . " and " . $row['DEPARTMENT_ID']   . " son los mismos<br>\n";
        echo $row[1] . " and " . $row['DEPARTMENT_NAME'] . " son los mismos<br>\n";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #2 Ejemplo con oci_fetch_array() con `OCI_NUM`

    <?php

    /*
      Antes de la ejecución, cree la tabla:
          CREATE TABLE mytab (id NUMBER, description CLOB);
          INSERT INTO mytab (id, description) values (1, 'A very long string');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_NUM)) != false) {
        echo $row[0] . "<br>\n";
        echo $row[1]->read(11) . "<br>\n"; // esto mostrará los 11 primeros bytes desde DESCRIPTION
    }

    // Muestra:
    //    1
    //    A very long

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #3 Ejemplo con oci_fetch_array() con `OCI_ASSOC`

    <?php

    /*
      Antes de la ejecución, cree la tabla:
          CREATE TABLE mytab (id NUMBER, description CLOB);
          INSERT INTO mytab (id, description) values (1, 'A very long string');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_ASSOC)) != false) {
        echo $row['ID'] . "<br>\n";
        echo $row['DESCRIPTION']->read(11) . "<br>\n"; // esto mostrará los 11 primeros bytes desde DESCRIPTION
    }

    // Muestra:
    //    1
    //    A very long

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #4 Ejemplo con oci_fetch_array() con `OCI_RETURN_NULLS`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT 1, null FROM dual');
    oci_execute($stid);
    while (($row = oci_fetch_array ($stid, OCI_ASSOC)) != false) { // Ignora NULLs
        var_dump($row);
    }

    /*
    El código anterior muestra:
      array(1) {
        [1]=>
        string(1) "1"
      }
    */

    $stid = oci_parse($conn, 'SELECT 1, null FROM dual');
    oci_execute($stid);
    while (($row = oci_fetch_array ($stid, OCI_ASSOC+OCI_RETURN_NULLS)) != false) { // Recupera NULLs
        var_dump($row);
    }

    /*
    El código anterior muestra:
      array(2) {
        [1]=>
        string(1) "1"
        ["NULL"]=>
        NULL
      }
    */

    ?>

Ejemplo #5 oci_fetch_array() con `OCI_RETURN_LOBS`

    <?php

    /*
      Antes de la ejecución, cree la tabla:
          CREATE TABLE mytab (id NUMBER, description CLOB);
          INSERT INTO mytab (id, description) values (1, 'A very long string');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_LOBS)) != false) {
        echo $row['ID'] . "<br>\n";
        echo $row['DESCRIPTION'] . "<br>\n"; // contiene todo el contenido de DESCRIPTION

        // En un ciclo, liberar la variable antes de recuperar una segunda
        // línea permite reducir el uso de memoria de PHP
        unset($row);
    }

    // Muestra:
    //    1
    //    A very long string

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #6 Ejemplo con oci_fetch_array() con nombres de columnas sensibles a mayúsculas/minúsculas

    <?php

    /*
       Antes de la ejecución, cree la tabla:
          CREATE TABLE mytab ("Name" VARCHAR2(20), city VARCHAR2(20));
          INSERT INTO mytab ("Name", city) values ('Chris', 'Melbourne');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'select * from mytab');
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);

    // Dado que 'Name' fue creado como una columna sensible a mayúsculas/minúsculas, la misma mayúscula/minúscula
    // es utilizada para los índices del array. Sin embargo, 'CITY' debe ser utilizado
    // para los índices de columna no sensible a mayúsculas/minúsculas
    print $row['Name'] . "<br>\n";   //  muestra Chris
    print $row['CITY'] . "<br>\n";   //  muestra Melbourne

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #7 Ejemplo con oci_fetch_array() con columnas que poseen nombres duplicados

    <?php

    /*
      Antes de la ejecución, cree la tabla:
          CREATE TABLE mycity (id NUMBER, name VARCHAR2(20));
          INSERT INTO mycity (id, name) values (1, 'Melbourne');
          CREATE TABLE mycountry (id NUMBER, name VARCHAR2(20));
          INSERT INTO mycountry (id, name) values (1, 'Australia');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT mycity.name, mycountry.name
            FROM mycity, mycountry
            WHERE mycity.id = mycountry.id';
    $stid = oci_parse($conn, $sql);
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC);
    var_dump($row);

    // La salida contiene solo UNA entrada "NAME":
    //    array(1) {
    //      ["NAME"]=>
    //      string(9) "Australia"
    //    }

    // Para consultar un nombre de columna duplicado, utilice un alias de columna SQL
    // como "AS ctnm":
    $sql = 'SELECT mycity.name AS ctnm, mycountry.name
            FROM mycity, mycountry
            WHERE mycity.id = mycountry.id';
    $stid = oci_parse($conn, $sql);
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC);
    var_dump($row);

    // La salida contiene ahora 2 columnas:
    //    array(2) {
    //      ["CTNM"]=>
    //      string(9) "Melbourne"
    //      ["NAME"]=>
    //      string(9) "Australia"
    //    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #8 Ejemplo con oci_fetch_array() y columnas `DATE`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Define el formato utilizado para las fechas en esta conexión.
    // Por razones de rendimiento, debe modificar el formato mediante un disparador o
    // utilizando variables de entorno
    $stid = oci_parse($conn, "ALTER SESSION SET NLS_DATE_FORMAT = 'YYYY-MM-DD'");
    oci_execute($stid);

    $stid = oci_parse($conn, 'SELECT hire_date FROM employees WHERE employee_id = 188');
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC);
    echo $row['HIRE_DATE'] . "<br>\n";  // Muestra 1997-06-14

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #9 Ejemplo con oci_fetch_array() y `REF CURSOR`

    <?php
    /*
      Cree el procedimiento almacenado PL/SQL siguiente antes de la ejecución:

      CREATE OR REPLACE PROCEDURE myproc(p1 OUT SYS_REFCURSOR) AS
      BEGIN
        OPEN p1 FOR SELECT * FROM all_objects WHERE ROWNUM < 5000;
      END;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'BEGIN myproc(:rc); END;');
    $refcur = oci_new_cursor($conn);
    oci_bind_by_name($stid, ':rc', $refcur, -1, OCI_B_CURSOR);
    oci_execute($stid);

    // Ejecuta el REF CURSOR devuelto y recupera un identificador de consulta
    oci_execute($refcur);
    echo "<table border='1'>\n";
    while (($row = oci_fetch_array($refcur, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($refcur);
    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #10 Paginación con oci_fetch_array() utilizando una consulta que utiliza el parámetro `LIMIT`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Obtiene la versión de la base de datos
    preg_match('/Release ([0-9]+)\./', oci_server_version($conn), $matches);
    $oracleversion = $matches[1];

    // Consulta para la paginación
    $sql = 'SELECT city, postal_code FROM locations ORDER BY city';

    if ($oracleversion >= 12) {
        // Utilización de la sintaxis Oracle 12c OFFSET / FETCH NEXT
        $sql = $sql . ' OFFSET :offset ROWS FETCH NEXT :numrows ROWS ONLY';
    } else {
        // Las versiones antiguas de Oracle requieren una consulta anidada
        // para seleccionar un subconjunto desde $sql. O, si la consulta SQL
        // es conocida en el momento del desarrollo, utilice una función
        // row_number() en lugar de esta solución de anidación. En los
        // entornos de producción, asegúrese de evitar las inyecciones
        // SQL con la concatenación.
        $sql = "SELECT * FROM (SELECT a.*, ROWNUM AS my_rnum
                               FROM ($sql) a
                               WHERE ROWNUM <= :offset + :numrows)
                WHERE my_rnum > :offset";
    }

    $offset  = 0;  // No procesar las primeras líneas
    $numrows = 5;  // Devuelve 5 líneas
    $stid = oci_parse($conn, $sql);
    oci_bind_by_name($stid, ':numrows', $numrows);
    oci_bind_by_name($stid, ':offset', $offset);
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_ASSOC + OCI_RETURN_NULLS)) != false) {
        echo $row['CITY'] . " " . $row['POSTAL_CODE'] . "<br>\n";
    }

    // Muestra:
    //    Beijing 190518
    //    Bern 3095
    //    Bombay 490231
    //    Geneva 1730
    //    Hiroshima 6823

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #11 Ejemplo con oci_fetch_array() con Oracle Database

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Requiere OCI8 2.0 (o posterior) y Oracle Database 12c (o posterior)
    // Ver también oci_get_implicit_resultset()
    $sql = 'DECLARE
               c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
               OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    // Nota: oci_fetch_all y oci_fetch() no pueden ser utilizadas de esta manera
    echo "<table>\n";
    while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "  <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    // Muestra:
    //    Beijing 190518
    //    Bern    3095
    //    Bombay  490231
    //    CN
    //    CH
    //    IN

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Notas

> Nota:

> Los índices de los arrays asociativos deben estar en mayúsculas para las columnas estándar de Oracle que han sido creadas con nombres sensibles a mayúsculas/minúsculas.

> Nota: Para las consultas que devuelven un número muy grande de líneas, el rendimiento puede ser muy significativamente mejorado aumentando el valor de la opción oci8.default_prefetch o usando la función oci_set_prefetch().

> Nota:

> La función oci_fetch_array() es significativamente más lenta que la función oci_fetch_assoc() o oci_fetch_row(), pero es más flexible.

### Ver también

- oci_fetch() - Lee la siguiente línea de un resultado Oracle en un buffer interno
- oci_fetch_all() - Lee múltiples líneas de un resultado en un array multidimensional
- oci_fetch_assoc() - Lee una línea de un resultado en forma de array asociativo
- oci_fetch_object() - Lee una línea de un resultado en forma de objeto
- oci_fetch_row() - Lee la siguiente línea de una consulta en forma de array numérico
- oci_set_prefetch() - Indica el número de filas que deben leerse por adelantado por Oracle

# oci_fetch_assoc

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_assoc — Lee una línea de un resultado en forma de array asociativo

### Descripción

function oci_fetch_assoc(resource `$statement`): array|false

Devuelve un array asociativo que contiene la siguiente línea de resultado de una consulta. Cada elemento del array corresponde a una columna de la línea. Esta función es típicamente llamada en un ciclo mientras no devuelva `false`, lo que indica que no hay más líneas disponibles.

oci_fetch_assoc() es idéntica a la función oci_fetch_array() y al modo `OCI_ASSOC` + `OCI_RETURN_NULLS`.

### Parámetros

`statement`
  Un identificador de consulta OCI8 creado por la función oci_parse() y ejecutado por la función oci_execute(), o un identificador de consulta `REF CURSOR`.

### Valores devueltos

Devuelve un array asociativo o `false` si no hay más líneas disponibles para la consulta `statement`.

### Ejemplos

Ejemplo #1 Ejemplo con oci_fetch_assoc()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT department_id, department_name FROM departments');
    oci_execute($stid);

    while (($row = oci_fetch_assoc($stid)) != false) {
        echo $row['DEPARTMENT_ID'] . " " . $row['DEPARTMENT_NAME'] . "<br>\n";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Notas

> Nota:

> Ver oci_fetch_array() para más ejemplos sobre la recuperación de líneas.

### Ver también

- oci_fetch() - Lee la siguiente línea de un resultado Oracle en un buffer interno
- oci_fetch_all() - Lee múltiples líneas de un resultado en un array multidimensional
- oci_fetch_array() - Lee una línea de un resultado en forma de array asociativo o numérico
- oci_fetch_object() - Lee una línea de un resultado en forma de objeto
- oci_fetch_row() - Lee la siguiente línea de una consulta en forma de array numérico

# oci_fetch_object

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_object — Lee una línea de un resultado en forma de objeto

### Descripción

function oci_fetch_object(resource `$statement`, int `$mode` = OCI_ASSOC | OCI_RETURN_NULLS): stdClass|false

Devuelve un objeto que contiene la siguiente línea de resultado de una consulta. Cada atributo de este objeto corresponde a una columna de la línea. Esta función se utiliza típicamente en un ciclo mientras no devuelva `false`, lo que indica que no hay más líneas disponibles.

Para más detalles sobre el mapeo de tipos de datos realizado por la extensión OCI8, lea los tipos de datos soportados por el driver.

### Parámetros

`statement`
  Un identificador de consulta OCI8 creado por la función oci_parse() y ejecutado por la función oci_execute(), o un identificador de consulta `REF CURSOR`.

### Valores devueltos

Devuelve un objeto. Cada atributo de este objeto corresponde a una columna de la línea. Si no hay más líneas disponibles en la consulta `statement` entonces se devuelve `false`.

Todas las columnas `LOB` son devueltas en forma de descriptores LOB.

Las columnas `DATE` son devueltas en forma de strings formateados con el formato de fecha actual. El formato por omisión puede ser cambiado mediante las variables de entorno Oracle, como `NLS_LANG` o ejecutando el comando `ALTER SESSION SET NLS_DATE_FORMAT`.

Los nombres de columnas que no son sensibles a la casse (por omisión en Oracle), tendrán nombres de atributos en mayúsculas. Los nombres de columnas que son sensibles a la casse, tendrán nombres de atributos utilizando exactamente la misma casse de la columna. Utilice la función var_dump() sobre el objeto de resultado para verificar la casse apropiada para el acceso a los atributos.

Los valores de atributo serán `null` para cada campo de datos `NULL`.

### Ejemplos

Ejemplo #1 Ejemplo con oci_fetch_object()

    <?php

    /*
      Antes de la ejecución, cree la tabla:
        CREATE TABLE mytab (id NUMBER, description VARCHAR2(30));
        INSERT INTO mytab (id, description) values (1, 'Fish and Chips');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_object($stid)) != false) {
        // Utilice nombres de atributos sensibles a la casse para cada columna estándar de Oracle
        echo $row->ID . "<br>\n";
        echo $row->DESCRIPTION . "<br>\n";
    }

    // Muestra:
    //    1
    //    Fish and Chips

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #2 Ejemplo con oci_fetch_object() con nombres de columna sensibles a la casse

    <?php

    /*
      Antes de la ejecución, cree la tabla con una columna cuyo nombre es sensible a la casse:
        CREATE TABLE mytab (id NUMBER, "MyDescription" VARCHAR2(30));
        INSERT INTO mytab (id, "MyDescription") values (1, 'Iced Coffee');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, "MyDescription" FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_object($stid)) != false) {
        // Utilice nombres de atributos en mayúsculas para cada columna estándar de Oracle
        echo $row->ID . "<br>\n";
        // Utilice la casse exacta para los nombres de columnas sensibles a la casse
        echo $row->MyDescription . "<br>\n";
    }

    // Muestra:
    //    1
    //    Iced Coffee

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #3 Ejemplo con oci_fetch_object() con LOBs

    <?php

    /*
      Antes de la ejecución, cree la tabla:
        CREATE TABLE mytab (id NUMBER, description CLOB);
        INSERT INTO mytab (id, description) values (1, 'A very long string');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_object($stid)) != false) {
        echo $row->ID . "<br>\n";
        // Lo siguiente mostrará los 11 primeros bytes desde DESCRIPTION
        echo $row->DESCRIPTION->read(11) . "<br>\n";
    }

    // Muestra:
    //    1
    //    A very long

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Ver también

- oci_fetch() - Lee la siguiente línea de un resultado Oracle en un buffer interno
- oci_fetch_all() - Lee múltiples líneas de un resultado en un array multidimensional
- oci_fetch_assoc() - Lee una línea de un resultado en forma de array asociativo
- oci_fetch_array() - Lee una línea de un resultado en forma de array asociativo o numérico
- oci_fetch_row() - Lee la siguiente línea de una consulta en forma de array numérico

# oci_fetch_row

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_row — Lee la siguiente línea de una consulta en forma de array numérico

### Descripción

function oci_fetch_row(resource `$statement`): array|false

Devuelve un array indexado numéricamente que contiene la siguiente línea de una consulta. Cada elemento de este array corresponde a una columna de la línea. Esta función es llamada típicamente en un ciclo mientras no devuelva `false`, lo que indica que no hay más líneas disponibles.

oci_fetch_row() es idéntica a la función oci_fetch_array() y al modo `OCI_NUM` + `OCI_RETURN_NULLS`.

### Parámetros

`statement`
  Un identificador de consulta OCI8 creado por la función oci_parse() y ejecutado por la función oci_execute(), o un identificador de consulta `REF CURSOR`.

### Valores devueltos

Devuelve un array indexado numéricamente. Si no hay más líneas disponibles para la consulta `statement` entonces `false` será devuelto.

### Ejemplos

Ejemplo #1 Ejemplo con oci_fetch_row()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT department_id, department_name FROM departments');
    oci_execute($stid);

    while (($row = oci_fetch_row($stid)) != false) {
        echo $row[0] . " " . $row[1] . "<br>\n";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Notas

> Nota:

> Ver oci_fetch_array() para más ejemplos sobre la recuperación de líneas.

### Ver también

- oci_fetch() - Lee la siguiente línea de un resultado Oracle en un buffer interno
- oci_fetch_all() - Lee múltiples líneas de un resultado en un array multidimensional
- oci_fetch_array() - Lee una línea de un resultado en forma de array asociativo o numérico
- oci_fetch_assoc() - Lee una línea de un resultado en forma de array asociativo
- oci_fetch_object() - Lee una línea de un resultado en forma de objeto

# oci_field_is_null

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_is_null — Comprueba si un campo de la fila recuperada es nulo

### Descripción

function oci_field_is_null(resource `$statement`, string|int `$column`): bool

Verifica si el campo `column` dado de la fila actual de la consulta `statement` es nulo.

### Parámetros

`statement`

  Un identificador de consulta OCI válido.

`column`

  Puede ser el índice del campo (a partir de 1) o su nombre.

### Valores devueltos

Devuelve `true` si `column` es nulo, `false` en caso contrario.

### Ejemplos

Ejemplo #1 Ejemplo con oci_field_name()

    <?php

    // Creación de la tabla con:
    //   CREATE TABLE mytab (c1 NUMBER);
    //   INSERT INTO mytab VALUES (1);
    //   INSERT INTO mytab VALUES (NULL);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_RETURN_NULLS)) != false) {
        $ncols = oci_num_fields($stid);
        for ($col = 1; $col <= $ncols; $col++) {
            var_dump(oci_field_is_null($stid, $col));
        }
    }

    // Muestra:
    //    bool(false)
    //    bool(true)

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# oci_field_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_name — Devuelve el nombre de un campo Oracle

### Descripción

function oci_field_name(resource `$statement`, string|int `$column`): string|false

Devuelve el nombre del campo `column`.

### Parámetros

`statement`

  Un identificador de consulta OCI válido.

`column`

  Puede ser un índice de campo (comenzando en 1) o un nombre de campo.

### Valores devueltos

Devuelve el nombre, en forma de string, o `false` si ocurre un error

### Ejemplos

Ejemplo #1 Ejemplo con oci_field_name()

    <?php

    // Creación de la tabla con:
    //   CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1),
    //                       clob_col CLOB, date_col DATE);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Uso de OCI_DESCRIBE_ONLY si no se recuperan filas

    echo "<table border=\"1\">\n";
    echo "<tr>";
    echo "<th>Name</th>";
    echo "<th>Type</th>";
    echo "<th>Length</th>";
    echo "</tr>\n";

    $ncols = oci_num_fields($stid);

    for ($i = 1; $i <= $ncols; $i++) {
        $column_name  = oci_field_name($stid, $i);
        $column_type  = oci_field_type($stid, $i);

        echo "<tr>";
        echo "<td>$column_name</td>";
        echo "<td>$column_type</td>";
        echo "</tr>\n";
    }

    echo "</table>\n";

    // Muestra:
    //    Name           Type
    //    NUMBER_COL    NUMBER
    //    VARCHAR2_COL  VARCHAR2
    //    CLOB_COL      CLOB
    //    DATE_COL      DATE

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Ver también

- oci_num_fields() - Devuelve el número de columnas en un resultado Oracle
- oci_field_type() - Devuelve el tipo de datos de un campo Oracle
- oci_field_size() - Devuelve el tamaño de un campo Oracle

# oci_field_precision

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_precision — Lee la precisión de un campo Oracle

### Descripción

function oci_field_precision(resource `$statement`, string|int `$column`): int|false

Devuelve la precisión del campo `column`.

Para las columnas de tipo FLOAT, la precisión no es nula, y la escala es de -127. Si la precisión es 0, entonces la columna es de tipo NUMBER. De lo contrario, es de tipo `NUMBER(precision, scale)`.

### Parámetros

`statement`

  Un identificador de consulta OCI válido.

`column`

  Puede ser un índice de campo (comenzando en 1) o un nombre de campo.

### Valores devueltos

Devuelve la precisión, en forma de int, o `false` si ocurre un error

### Ejemplos

Ejemplo #1 Ejemplo con oci_field_precision()

    <?php

    // Creación de la tabla con:
    //   CREATE TABLE mytab (c1 NUMBER, c2 FLOAT, c3 NUMBER(4), c4 NUMBER(5,3));

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Uso de OCI_DESCRIBE_ONLY si ninguna fila es recuperada

    $ncols = oci_num_fields($stid);
    for ($i = 1; $i <= $ncols; $i++) {
        echo oci_field_name($stid, $i) . " "
            . oci_field_precision($stid, $i) . " "
            . oci_field_scale($stid, $i) . "<br>\n";
    }

    // Muestra:
    //   C1    0 -127
    //   C2  126 -127
    //   C3    4    0
    //   C4    5    3

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Ver también

- oci_field_scale() - Lee la escala de una columna Oracle
- oci_field_type() - Devuelve el tipo de datos de un campo Oracle

# oci_field_scale

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_scale — Lee la escala de una columna Oracle

### Descripción

function oci_field_scale(resource `$statement`, string|int `$column`): int|false

Lee la escala de una columna Oracle.

Para las columnas de tipo FLOAT, la precisión no es nula, y la escala es de -127. Si la precisión es 0, entonces la columna es de tipo NUMBER. De lo contrario, es de tipo `NUMBER(precision, scale)`.

### Parámetros

`statement`

  Un identificador de consulta OCI válido.

`column`

  Puede ser un índice de campo (comenzando en 1) o el nombre de un campo.

### Valores devueltos

Devuelve la escala, en forma de int, o `false` si ocurre un error

### Ejemplos

Ejemplo #1 Ejemplo con oci_field_scale()

    <?php

    // Creación de la tabla con:
    //   CREATE TABLE mytab (c1 NUMBER, c2 FLOAT, c3 NUMBER(4), c4 NUMBER(5,3));

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Uso de OCI_DESCRIBE_ONLY si no se recupera ninguna fila

    $ncols = oci_num_fields($stid);
    for ($i = 1; $i <= $ncols; $i++) {
        echo oci_field_name($stid, $i) . " "
            . oci_field_precision($stid, $i) . " "
            . oci_field_scale($stid, $i) . "<br>\n";
    }

    // Muestra:
    //   C1    0 -127
    //   C2  126 -127
    //   C3    4    0
    //   C4    5    3

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Ver también

- oci_field_precision() - Lee la precisión de un campo Oracle
- oci_field_type() - Devuelve el tipo de datos de un campo Oracle

# oci_field_size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_size — Devuelve el tamaño de un campo Oracle

### Descripción

function oci_field_size(resource `$statement`, string|int `$column`): int|false

Devuelve el tamaño del campo `column` Oracle.

### Parámetros

`statement`

  Un identificador de consulta OCI válido.

`column`

  Puede ser el índice del campo (la indexación comienza en 1) o el nombre del campo.

### Valores devueltos

Devuelve el tamaño del campo `field` en bytes, o `false` si ocurre un error

### Ejemplos

Ejemplo #1 Ejemplo con oci_field_size()

    <?php

    // Creación de la tabla con:
    //   CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1),
    //                       clob_col CLOB, date_col DATE);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Utilización de OCI_DESCRIBE_ONLY si ninguna fila es recuperada

    echo "<table border=\"1\">\n";
    echo "<tr>";
    echo "<th>Name</th>";
    echo "<th>Type</th>";
    echo "<th>Length</th>";
    echo "</tr>\n";

    $ncols = oci_num_fields($stid);

    for ($i = 1; $i <= $ncols; $i++) {
        $column_name  = oci_field_name($stid, $i);
        $column_type  = oci_field_type($stid, $i);
        $column_size  = oci_field_size($stid, $i);

        echo "<tr>";
        echo "<td>$column_name</td>";
        echo "<td>$column_type</td>";
        echo "<td>$column_size</td>";
        echo "</tr>\n";
    }

    echo "</table>\n";

    // Muestra:
    //    Name           Type       Length
    //    NUMBER_COL    NUMBER        22
    //    VARCHAR2_COL  VARCHAR2       1
    //    CLOB_COL      CLOB        4000
    //    DATE_COL      DATE           7

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Ver también

- oci_num_fields() - Devuelve el número de columnas en un resultado Oracle
- oci_field_name() - Devuelve el nombre de un campo Oracle

# oci_field_type

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_type — Devuelve el tipo de datos de un campo Oracle

### Descripción

function oci_field_type(resource `$statement`, string|int `$column`): string|int|false

Devuelve el nombre del tipo de datos de un campo.

### Parámetros

`statement`

  Un identificador de consulta OCI válido.

`column`

  Puede ser el índice del campo (la indexación comienza en 1) o el nombre.

### Valores devueltos

Devuelve el tipo de datos de un campo, en forma de string o un int, o `false` si ocurre un error

### Ejemplos

Ejemplo #1 Ejemplo con oci_field_type()

    // Creación de la tabla con:
    //   CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1),
    //                       clob_col CLOB, date_col DATE);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Uso de OCI_DESCRIBE_ONLY si no se recupera ninguna fila

    echo "<table border=\"1\">\n";
    echo "<tr>";
    echo "<th>Name</th>";
    echo "<th>Type</th>";
    echo "<th>Length</th>";
    echo "</tr>\n";

    $ncols = oci_num_fields($stid);

    for ($i = 1; $i <= $ncols; $i++) {
        $column_name  = oci_field_name($stid, $i);
        $column_type  = oci_field_type($stid, $i);
        $column_size  = oci_field_size($stid, $i);

        echo "<tr>";
        echo "<td>$column_name</td>";
        echo "<td>$column_type</td>";
        echo "<td>$column_size</td>";
        echo "</tr>\n";
    }

    echo "</table>\n";

    // Muestra:
    //    Name           Type       Length
    //    NUMBER_COL    NUMBER        22
    //    VARCHAR2_COL  VARCHAR2       1
    //    CLOB_COL      CLOB        4000
    //    DATE_COL      DATE           7

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Ver también

- oci_num_fields() - Devuelve el número de columnas en un resultado Oracle
- oci_field_name() - Devuelve el nombre de un campo Oracle
- oci_field_size() - Devuelve el tamaño de un campo Oracle

# oci_field_type_raw

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_type_raw — Lee los datos brutos del tipo de un campo

### Descripción

function oci_field_type_raw(resource `$statement`, string|int `$column`): int|false

Lee los datos brutos "SQLT" del tipo del campo `column`.

Si se desea obtener el nombre del tipo del campo, utilice la función oci_field_type().

### Parámetros

`statement`

  Un identificador de consulta OCI válido.

`column`

  Puede ser el índice de un campo (comenzando en 1) o el nombre de un campo.

### Valores devueltos

Devuelve el tipo de datos brutos de Oracle, para el campo, en forma de número, o `false` si ocurre un error

### Ejemplos

Ejemplo #1 Ejemplo con oci_field_type_raw()

    <?php

    // Creación de la tabla con:
    //   CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1), clob_col CLOB, date_col DATE);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'select * from mytab');
    oci_execute($stid, OCI_DESCRIBE_ONLY);  // Uso de OCI_DESCRIBE_ONLY si no se recupera ninguna fila

    $n = oci_num_fields($stid);
    for ($i = 1; $i <= $n; ++$i) {
        echo oci_field_name($stid, $i) . " is raw type: " . oci_field_type_raw($stid, $i) . "<br>\n";
    }

    // Muestra:
    //    NUMBER_COL is raw type: 2
    //    VARCHAR2_COL is raw type: 1
    //    CLOB_COL is raw type: 112
    //    DATE_COL is raw type: 12

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# oci_free_descriptor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_free_descriptor — Libera un descriptor

### Descripción

function oci_free_descriptor(OCILob `$lob`): bool

Libera un descriptor asignado por la función oci_new_descriptor().

### Parámetros

`lob`

  Descriptor asignado por oci_new_descriptor().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Notas

> Nota:

> Esta función es habitualmente utilizada como método OCILOB::free.

### Ver también

- OCILOB::free

# oci_free_statement

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_free_statement — Libera todos los recursos asociados con una sentencia o cursor

### Descripción

function oci_free_statement(resource `$statement`): bool

Libera los recursos asociados con un cursor o sentencia de Oracle, el cual fue recibido desde una resultado de oci_parse() u obtenido desde Oracle.

### Parámetros

`statement`

  Un identificador de sentecia válido de OCI.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# oci_get_implicit_resultset

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL OCI8 >= 2.0.0)

oci_get_implicit_resultset — Retorna el hijo siguiente de un recurso de consulta desde un recurso de consulta padre que tiene un juego de resultados implícito de Oracle Database

### Descripción

function oci_get_implicit_resultset(resource `$statement`): resource|false

Utilizado para recuperar juegos recursivos de resultados de consultas después de la ejecución de un bloque almacenado o anónimo Oracle PL/SQL donde este bloque retorna resultados de consultas con la función DBMS_SQL.RETURN_RESULT Oracle PL/SQL de la base de datos Oracle 12 (o posterior). Esto permite a los bloques PL/SQL retornar fácilmente resultados de consultas.

La consulta hija puede ser utilizada con cualquiera de las funciones de recuperación OCI8: oci_fetch(), oci_fetch_all(), oci_fetch_array(), oci_fetch_object(), oci_fetch_assoc() o oci_fetch_row()

Las consultas hijas heredan los valores pre-recuperados de sus padres, o pueden ser definidas explícitamente con la función oci_set_prefetch().

### Parámetros

`statement`

  Un identificador de consulta OCI8 válido creado por la función oci_parse() y ejecutado por la función oci_execute(). El identificador de consulta puede o no estar asociado con una consulta OCI8 que retorna juegos de resultados implícitos.

### Valores devueltos

Retorna un gestor de consulta para la próxima consulta hija disponible en `statement`. Retorna `false` cuando la consulta hija no existe, o cuando todas las consultas hijas han sido retornadas por llamados previos a la función oci_get_implicit_resultset().

### Ejemplos

Ejemplo #1 Recuperación de los juegos de resultados implícitos mediante un ciclo

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'DECLARE
                c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
               OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    while (($stid_c = oci_get_implicit_resultset($stid))) {
        echo "<h2>Nuevo juego de resultados implícito:</h2>\n";
        echo "<table>\n";
        while (($row = oci_fetch_array($stid_c, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
            echo "<tr>\n";
            foreach ($row as $item) {
                echo "  <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"")."</td>\n";
            }
            echo "</tr>\n";
        }
        echo "</table>\n";
    }

    // Muestra:
    //    Nuevo juego de resultados implícito:
    //     Beijing 190518
    //     Bern    3095
    //     Bombay  490231
    //    Nuevo juego de resultados implícito:
    //     CN
    //     CH
    //     IN

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #2 Recupera individualmente los gestores de consultas hijas

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'DECLARE
                c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
               OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    $stid_1 = oci_get_implicit_resultset($stid);
    $stid_2 = oci_get_implicit_resultset($stid);

    $row = oci_fetch_array($stid_1, OCI_ASSOC+OCI_RETURN_NULLS);
    var_dump($row);
    $row = oci_fetch_array($stid_2, OCI_ASSOC+OCI_RETURN_NULLS);
    var_dump($row);
    $row = oci_fetch_array($stid_1, OCI_ASSOC+OCI_RETURN_NULLS);
    var_dump($row);
    $row = oci_fetch_array($stid_2, OCI_ASSOC+OCI_RETURN_NULLS);
    var_dump($row);

    // Muestra:
    //    array(2) {
    //      ["CITY"]=>
    //      string(7) "Beijing"
    //      ["POSTAL_CODE"]=>
    //      string(6) "190518"
    //    }
    //    array(1) {
    //      ["COUNTRY_ID"]=>
    //      string(2) "CN"
    //    }
    //    array(2) {
    //      ["CITY"]=>
    //      string(4) "Bern"
    //      ["POSTAL_CODE"]=>
    //      string(4) "3095"
    //    }
    //    array(1) {
    //      ["COUNTRY_ID"]=>
    //      string(2) "CH"
    //    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #3 Definición explícita del contador de pre-recuperación

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'DECLARE
                c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    $stid_c = oci_get_implicit_resultset($stid);
    oci_set_prefetch($stid_c, 200);   // Establece la pre-recuperación antes de recuperar de la consulta hija
    echo "<table>\n";
    while (($row = oci_fetch_array($stid_c, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "  <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #4 Ejemplo de juego de resultados implícito sin utilizar la función oci_get_implicit_resultset()

Todos los resultados de todas las consultas son retornados consecutivamente.

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'DECLARE
                c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
               OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    // Nota: oci_fetch_all y oci_fetch() no pueden ser utilizados de esta manera
    echo "<table>\n";
    while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "  <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    // Muestra:
    //    Beijing 190518
    //    Bern 3095
    //    Bombay 490231
    //    CN
    //    CH
    //    IN

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Notas

> Nota: Para las consultas que devuelven un número muy grande de líneas, el rendimiento puede ser muy significativamente mejorado aumentando el valor de la opción oci8.default_prefetch o usando la función oci_set_prefetch().

# oci_lob_copy

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_lob_copy — Copia un LOB Oracle

### Descripción

function oci_lob_copy(OCILob `$to`, OCILob `$from`, ?int `$length` = `null`): bool

Copia un LOB o una parte de un LOB a otro LOB. Los datos antiguos del LOB de destino serán sobrescritos por los nuevos.

Si se debe copiar una parte específica de un LOB a una posición particular de otro LOB, utilice la función OCILob::seek() para mover el puntero interno de LOB.

### Parámetros

`to`

  El LOB de destino.

`from`

  El LOB copiado.

`length`

  Indica el tamaño de los datos a copiar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | `length` es ahora nullable.

### Notas

> Nota:

> La clase OCILob se llamaba OCI-Lob antes de PHP 8 y OCI8 3.0.0.

# oci_lob_is_equal

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_lob_is_equal — Comparar dos LOB/FILE de Oracle

### Descripción

function oci_lob_is_equal(OCILob `$lob1`, OCILob `$lob2`): bool

Compara dos LOB/FILE de Oracle.

### Parámetros

`lob1`

  Un identificador LOB.

`lob2`

  Un identificador LOB.

### Valores devueltos

Devuelve `true` si estos objetos son iguales, `false` en caso contrario.

### Notas

> Nota:

> La clase OCICollection se denominaba OCI-Collection antes de PHP 8 y OCI8 3.0.0.

# oci_new_collection

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_collection — Inicializa una nueva colección Oracle

### Descripción

function oci_new_collection(resource `$connection`, string `$type_name`, ?string `$schema` = `null`): OCICollection|false

Inicializa una nueva colección Oracle.

### Parámetros

`connection`

  Un identificador de conexión Oracle, devuelto por la función oci_connect() o la función oci_pconnect().

`type_name`

  Debe ser un tipo nombrado válido (en mayúsculas).

`schema`

  Debe apuntar al esquema de la base de datos, donde el tipo fue creado. El nombre del usuario actual es utilizado cuando `null` es proporcionado.

### Valores devueltos

Devuelve un nuevo objeto OCICollection, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | `schema` ahora es nullable.

### Notas

> Nota:

> La clase OCICollection se llamaba OCI-Collection antes de PHP 8 y OCI8 3.0.0.

# oci_new_connect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_connect — Conexión al servidor Oracle utilizando una sola conexión

### Descripción

function oci_new_connect(
string `$username`,
string `$password`,
?string `$connection_string` = `null`,
string `$encoding` = "",
int `$session_mode` = `OCI_DEFAULT`
): resource|false

Establece una nueva conexión al servidor Oracle e identifica.

A diferencia de las funciones oci_connect() y oci_pconnect(), oci_new_connect() no almacena en caché las conexiones y siempre devuelve un manejador de conexión recién abierto. Esto es muy útil si la aplicación necesita aislamiento transaccional entre dos conjuntos de consultas.

### Parámetros

`username`

  El nombre de usuario de Oracle.

`password`

  La contraseña para el usuario.

`connection_string`
  Contiene la instancia `Oracle` a la que debemos conectarnos. Esto puede ser una » cadena de conexión rápida, un nombre de conexión del archivo tnsnames.ora, o el nombre de una instancia local Oracle. Si no se especifica o es `null`, PHP utiliza variables de entorno como `TWO_TASK` (en Linux) o `LOCAL` (en Windows) y `ORACLE_SID` para determinar la instancia `Oracle` a la que debemos conectarnos. Para usar el método de conexión rápida, PHP debe estar vinculado con la biblioteca cliente Oracle 10g o superior. La cadena de conexión rápida para Oracle 10g o superior es de la forma: [//]host_name[:port][/service_name]. Desde Oracle 11g, la sintaxis es: [//]host_name[:port][/service_name][:server_type][/instance_name]. Opciones adicionales fueron introducidas con Oracle 19c Los nombres de los servicios pueden ser encontrados ejecutando la utilidad Oracle `lsnrctl status` en la máquina que ejecuta la base de datos. El archivo tnsnames.ora puede estar en el camino de búsqueda de Oracle Net, que incluye /your/path/to/instantclient/network/admin, $ORACLE_HOME/network/admin y /etc. Una solución alternativa sería definir `TNS_ADMIN` para que el archivo $TNS_ADMIN/tnsnames.ora sea leído. Asegúrese de que el demonio que ejecuta el servidor web tenga acceso de lectura a este archivo.
`encoding`
  Determina el juego de caracteres utilizado por la biblioteca cliente Oracle. El juego de caracteres no necesita ser idéntico al utilizado por la base de datos. Si no coincide, Oracle hará lo mejor posible para convertir los datos desde el juego de caracteres de la base de datos. Dependiendo de los juegos de caracteres, el resultado puede no ser perfecto. Además, esta conversión requiere un poco de tiempo del sistema. Si no se especifica, la biblioteca cliente Oracle determinará un juego de caracteres desde la variable de entorno `NLS_LANG`. Pasar este parámetro puede reducir el tiempo de conexión.
`session_mode`
  Este parámetro está disponible a partir de PHP 5 (PECL OCI8 1.1) y acepta los siguientes valores: `OCI_DEFAULT`, `OCI_SYSOPER` y `OCI_SYSDBA`. Si bien la constante `OCI_SYSOPER` o la constante `OCI_SYSDBA` es especificada, esta función intentará establecer una conexión privilegiada usando identidades externas. Las conexiones privilegiadas están desactivadas por omisión. Para activarlas, debe definir la opción oci8.privileged_connect a `On`. PHP 5.3 (PECL OCI8 1.3.4) introducen el valor de modo `OCI_CRED_EXT`. Este modo solicita a Oracle usar una identificación externa o bien del sistema operativo, que debe ser configurada en la base de datos. El flag `OCI_CRED_EXT` solo puede ser usado con el nombre de usuario "/" asociado a una contraseña vacía. La opción oci8.privileged_connect puede ser definida a `On` o `Off`. `OCI_CRED_EXT` puede ser combinado con el modo `OCI_SYSOPER` o el modo `OCI_SYSDBA`. `OCI_CRED_EXT` no es soportado en Windows por razones de seguridad.

### Valores devueltos

Devuelve un identificador de conexión, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | `connection_string` ahora es nullable.

### Ejemplos

A continuación se muestra cómo separar transacciones.

Ejemplo #1 Ejemplo con oci_new_connect()

    <?php

    // Creación de la tabla mytab (mycol number);

    function query($name, $c)
    {
        echo "Querying $name\n";
        $s = oci_parse($c, "select * from mytab");
        oci_execute($s, OCI_NO_AUTO_COMMIT);
        $row = oci_fetch_array($s, OCI_ASSOC);
        if (!$row) {
            echo "No rows\n";
        } else {
            do {
                foreach ($row as $item)
                    echo $item . " ";
                echo "\n";
            } while (($row = oci_fetch_array($s, OCI_ASSOC)) != false);
        }
    }

    $c1 = oci_connect("hr", "welcome", "localhost/orcl");
    $c2 = oci_new_connect("hr", "welcome", "localhost/orcl");

    $s = oci_parse($c1, "insert into mytab values(1234)");
    oci_execute($s, OCI_NO_AUTO_COMMIT);

    query("basic connection", $c1);
    query("new connection", $c2);
    oci_commit($c1);
    query("new connection after commit", $c2);

    // Muestra:
    //   Querying basic connection
    //   1234
    //   Querying new connection
    //   No rows
    //   Querying new connection after commit
    //   1234

    ?>

Ver la función oci_connect() para más ejemplos sobre el uso de este parámetro.

### Ver también

- oci_connect() - Establece una conexión con un servidor Oracle
- oci_pconnect() - Establece una conexión persistente a un servidor Oracle

# oci_new_cursor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_cursor — Asigna y devuelve un nuevo cursor Oracle

### Descripción

function oci_new_cursor(resource `$connection`): resource|false

Asigna un nuevo cursor Oracle en la conexión especificada.

### Parámetros

`connection`

  Un identificador de conexión Oracle, devuelto por la función oci_connect() o la función oci_pconnect().

### Valores devueltos

Devuelve un nuevo manejador de conexión, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Utilizar un REF CURSOR de un procedimiento almacenado

    <?php
    // Requisitos previos:
    //   crear o reemplazar el procedimiento myproc(myrc out sys_refcursor) de la siguiente manera:
    //   begin
    //     open myrc for select first_name from employees;
    //   end;

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $curs = oci_new_cursor($conn);
    $stid = oci_parse($conn, "begin myproc(:cursbv); end;");
    oci_bind_by_name($stid, ":cursbv", $curs, -1, OCI_B_CURSOR);
    oci_execute($stid);

    oci_execute($curs);  // Ejecutar el REF CURSOR como un identificador de sentencia normal
    while (($row = oci_fetch_array($curs, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo $row['FIRST_NAME'] . "<br />\n";
    }

    oci_free_statement($stid);
    oci_free_statement($curs);
    oci_close($conn);
    ?>

# oci_new_descriptor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_descriptor — Inicializa un nuevo puntero vacío de LOB/FILE de Oracle

### Descripción

function oci_new_descriptor(resource `$connection`, int `$type` = `OCI_DTYPE_LOB`): ?OCILob

Inicializa un nuevo puntero vacío de LOB/FILE de Oracle.

### Parámetros

`connection`

  Un identificador de conexión Oracle, devuelto por la función oci_connect() o la función oci_pconnect().

`type`

  Los valores admitidos para `type` son : `OCI_D_FILE`, `OCI_D_LOB` y `OCI_D_ROWID`.

### Valores devueltos

Devuelve un nuevo recurso LOB o FILE en caso de éxito, o `null` en caso de fallo.

### Ejemplos

Ejemplo #1 Ejemplo con oci_new_descriptor()

    <?php
    /* Este script está diseñado para ser llamado desde un formulario HTML
     * Espera las variables $user, $password, $table, $where, y $commitsize
     * El script elimina entonces las filas seleccionadas con ROWID y valida
     * la eliminación después de cada grupo de $commitsize filas.
     * (Utilícelo con precaución, ya que no hay posibilidad de deshacer).
     */
    $conn = oci_connect($user, $password);
    $stmt = oci_parse($conn, "select rowid from $table $where");
    $rowid = oci_new_descriptor($conn, OCI_D_ROWID);
    oci_define_by_name($stmt, "ROWID", $rowid);
    oci_execute($stmt);
    while (oci_fetch($stmt)) {
        $nrows = oci_num_rows($stmt);
        $delete = oci_parse($conn, "delete from $table where ROWID = :rid");
        oci_bind_by_name($delete, ":rid", $rowid, -1, OCI_B_ROWID);
        oci_execute($delete);
        echo "$nrows\n";
        if (($nrows % $commitsize) == 0) {
            oci_commit($conn);
        }
    }
    $nrows = oci_num_rows($stmt);
    echo "$nrows deleted...\n";
    oci_free_statement($stmt);
    oci_close($conn);
    ?>

    <?php
    /* Este script ilustra la carga de columnas de tipo LOB
     * El formulario utilizado en este ejemplo se parece a esto:
     * <form action="upload.php" method="post" enctype="multipart/form-data">
     * <input type="file" name="lob_upload" />
     * ...
     */
      if (!isset($lob_upload) || $lob_upload == 'none'){
    ?>
    <form action="upload.php" method="post" enctype="multipart/form-data">
    Upload file: <input type="file" name="lob_upload" /><br />
    <input type="submit" value="Upload" /> - <input type="reset" value="Reset" />
    </form>
    <?php
      } else {

         // $lob_upload contiene el fichero temporal

         // Consulte la sección sobre la subida de ficheros
         // para asegurar sus subidas

         $conn = oci_connect($user, $password);
         $lob = oci_new_descriptor($conn, OCI_D_LOB);
         $stmt = oci_parse($conn, "insert into $table (id, the_blob)
                   values(my_seq.NEXTVAL, EMPTY_BLOB()) returning the_blob into :the_blob");
         oci_bind_by_name($stmt, ':the_blob', $lob, -1, OCI_B_BLOB);
         oci_execute($stmt, OCI_DEFAULT);
         if ($lob->savefile($lob_upload)){
            oci_commit($conn);
            echo "BLOB cargado !\n";
         }else{
            echo "Imposible cargar el BLOB\n";
         }
         $lob->free();
         oci_free_statement($stmt);
         oci_close($conn);
      }
    ?>

Ejemplo #2 Ejemplo con oci_new_descriptor()

    <?php
    /* Llamada a un procedimiento PL/SQL almacenado que toma un clob
     * como entrada.
     * Ejemplo de firma de procedimiento almacenado PL/SQL:
     *
     * PROCEDURE save_data
     *   Argument Name                  Type                    In/Out Default?
     *   ------------------------------ ----------------------- ------ --------
     *   KEY                            NUMBER(38)              IN
     *   DATA                           CLOB                    IN
     *
     */

    $conn = oci_connect($user, $password);
    $stmt = oci_parse($conn, "begin save_data(:key, :data); end;");
    $clob = oci_new_descriptor($conn, OCI_D_LOB);
    oci_bind_by_name($stmt, ':key', $key);
    oci_bind_by_name($stmt, ':data', $clob, -1, OCI_B_CLOB);
    $clob->write($data);
    oci_execute($stmt, OCI_DEFAULT);
    oci_commit($conn);
    $clob->free();
    oci_free_statement($stmt);
    ?>

### Ver también

- oci_bind_by_name() - Asocia una variable PHP a un marcador Oracle

# oci_num_fields

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_num_fields — Devuelve el número de columnas en un resultado Oracle

### Descripción

function oci_num_fields(resource `$statement`): int

Devuelve el número de columnas en el resultado Oracle `statement`.

### Parámetros

`statement`

  Un identificador de consulta OCI válido.

### Valores devueltos

Devuelve el número de columnas, en forma de int.

### Ejemplos

Ejemplo #1 Ejemplo con oci_num_fields()

    <?php

    // Creación de la tabla con:
    //   CREATE TABLE mytab (id NUMBER, quantity NUMBER);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Uso de OCI_DESCRIBE_ONLY si no se recupera ninguna fila

    $ncols = oci_num_fields($stid);
    for ($i = 1; $i <= $ncols; $i++) {
        echo oci_field_name($stid, $i) . " " . oci_field_type($stid, $i) . "<br>\n";
    }

    // Muestra:
    //    ID NUMBER
    //    QUANTITY NUMBER

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# oci_num_rows

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_num_rows — Devuelve el número de filas afectadas durante el último comando Oracle

### Descripción

function oci_num_rows(resource `$statement`): int|false

Devuelve el número de filas afectadas durante el último comando Oracle.

### Parámetros

`statement`

  Un identificador de consulta OCI válido.

### Valores devueltos

Devuelve el número de filas afectadas, en forma de int, o `false` si ocurre un error

### Ejemplos

Ejemplo #1 Ejemplo con oci_num_rows()

    <?php
    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "create table emp2 as select * from employees");
    oci_execute($stid);
    echo oci_num_rows($stid) . " filas insertadas.<br />\n";
    oci_free_statement($stid);

    $stid = oci_parse($conn, "delete from emp2");
    oci_execute($stid, OCI_DEFAULT);
    echo oci_num_rows($stid) . " filas borradas.<br />\n";
    oci_commit($conn);
    oci_free_statement($stid);

    $stid = oci_parse($conn, "drop table emp2");
    oci_execute($stid);
    oci_free_statement($stid);

    oci_close($conn);
    ?>

### Notas

> Nota:

> Esta función no devuelve el número de filas seleccionadas. Para los comandos de tipo SELECT, esta función va a devolver el número de filas que han sido leídas en el buffer con oci_fetch*().

# oci_parse

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_parse — Prepara una consulta SQL con Oracle

### Descripción

function oci_parse(resource `$connection`, string `$sql`): resource|false

Prepara la consulta `sql` utilizando la conexión `connection` y devuelve el identificador de consulta que podrá ser utilizado con las funciones oci_bind_by_name(), oci_execute(), etc.

Los identificadores de consulta pueden ser liberados utilizando la función oci_free_statement() o definiendo la variable correspondiente al valor `null`.

### Parámetros

`connection`

  Un identificador de conexión Oracle, devuelto por la función oci_connect(), oci_pconnect() o oci_new_connect().

`sql`

  La consulta SQL o PL/SQL.

  Las consultas SQL no deben terminar con un punto y coma (";"). Las consultas PL/SQL deben terminar con un punto y coma (";").

### Valores devueltos

Devuelve un manejador de consulta en caso de éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con oci_parse()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    // Análisis de la consulta. Note que no hay un punto y coma al final de la consulta SQL
    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Ejemplo #2 Ejemplo con oci_parse() y una consulta PL/SQL

    <?php

    /*
      Antes de ejecutar este código PHP, debe crear un procedimiento almacenado en
      SQL*Plus o SQL Developer:

      CREATE OR REPLACE PROCEDURE myproc(p1 IN NUMBER, p2 OUT NUMBER) AS
      BEGIN
          p2 := p1 * 2;
      END;

    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $p1 = 8;

    // Al analizar PL/SQL, debe haber un punto y coma al final de la cadena
    $stid = oci_parse($conn, 'begin myproc(:p1, :p2); end;');
    oci_bind_by_name($stid, ':p1', $p1);
    oci_bind_by_name($stid, ':p2', $p2, 40);

    oci_execute($stid);

    print "$p2\n";   // muestra 16

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Notas

> Nota:

> Esta función no valida la consulta `sql`. La única forma de saber si la consulta `sql` es válida es ejecutándola.

### Ver también

- oci_execute() - Ejecuta un comando SQL de Oracle
- oci_free_statement() - Libera todos los recursos asociados con una sentencia o cursor

# oci_password_change

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_password_change — Modifica la contraseña de un usuario Oracle

### Descripción

function oci_password_change(
resource `$connection`,
string `$username`,
string `$old_password`,
string `$new_password`
): bool
function oci_password_change(
string `$database_name`,
string `$username`,
string `$old_password`,
string `$new_password`
): resource

Modifica la contraseña del usuario `username`.

La función oci_password_change() es más útil con scripts PHP en línea de comandos, o cuando se utilizan conexiones no persistentes en la aplicación PHP.

### Parámetros

`connection`

  Un identificador de conexión Oracle, devuelto por la función oci_connect() o la función oci_pconnect().

`username`

  El nombre de usuario Oracle.

`old_password`

  La contraseña antigua.

`new_password`

  La nueva contraseña a establecer.

`database_name`

  El nombre de la base de datos.

### Valores devueltos

Cuando `database_name` es proporcionado, oci_password_change() devuelve `true` en caso de éxito, o `false` si ocurre un error. Cuando `connection` es proporcionado, oci_password_change() devuelve el recurso de conexión en caso de éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con oci_password_change() para cambiar la contraseña de un usuario ya conectado

    <?php

    $dbase      = 'localhost/orcl';
    $user       = 'cj';
    $current_pw = 'welcome';
    $new_pw     = 'geelong';

    $c = oci_pconnect($user, $current_pw, $dbase);
    oci_password_change($c, $user, $current_pw, $new_pw);
    echo "La nueva contraseña es: " . $new_pw . "\n";

    ?>

Ejemplo #2 Ejemplo con oci_password_change() para conectarse y cambiar la contraseña en una sola etapa

    <?php

    $dbase      = 'localhost/orcl';
    $user       = 'cj';
    $current_pw = 'welcome';
    $new_pw     = 'geelong';

    $c = oci_pconnect($user, $current_pw, $dbase);
    if (!$c) {
        $m = oci_error();
        if ($m['code'] == 28001) { // "ORA-28001: La contraseña ha expirado"
            // Conexión y cambio de contraseña en una etapa
            $c = oci_password_change($dbase, $user, $current_pw, $new_pw);
            if ($c) {
                echo "La nueva contraseña es: " . $new_pw . "\n";
            }
        }
    }

    if (!$c) {  // El error original no era 28001, o el cambio de contraseña falló
        $m = oci_error();
        trigger_error('No se pudo conectar a la base de datos: '. $m['message'], E_USER_ERROR);
    }

    // Uso de la conexión $c
    // ...

    ?>

### Notas

> Nota:

> Cambiar la contraseña, con esta función, o directamente en Oracle debe hacerse con precaución. Esto se debe a que las aplicaciones PHP podrían seguir utilizando conexiones persistentes con la contraseña antigua. La mejor práctica es reiniciar todos los servidores web una vez que la contraseña ha sido cambiada.

> Nota:

> Si se actualizan las bibliotecas cliente o la base de datos Oracle desde una versión anterior a 11.2.0.3 a una versión 11.2.0.3 o superior, la función oci_password_change() puede devolver el error "ORA-1017: invalid username/password" hasta que las versiones del cliente y del servidor sean idénticas.

> Nota:

> La segunda sintaxis de oci_password_change() está disponible desde la versión de OCI8 1.1.

# oci_pconnect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_pconnect — Establece una conexión persistente a un servidor Oracle

### Descripción

function oci_pconnect(
string `$username`,
string `$password`,
?string `$connection_string` = `null`,
string `$encoding` = "",
int `$session_mode` = `OCI_DEFAULT`
): resource|false

Establece una conexión persistente a un servidor Oracle y se identifica.

Las conexiones persistentes se almacenan en caché y se reutilizan entre las consultas, reduciendo así la carga en cada carga de página; una aplicación PHP típica tiene una sola conexión persistente a un servidor Oracle por proceso hijo Apache (o proceso PHP FastCGI/CGI). Ver la sección sobre la Gestión de Conexiones y el Agrupamiento de Conexiones para más información.

### Parámetros

`username`

  El nombre de usuario de Oracle.

`password`

  La contraseña del usuario.

`connection_string`
  Contiene la instancia `Oracle` a la que debemos conectarnos. Esto puede ser una » cadena de conexión rápida, un nombre de conexión del archivo tnsnames.ora, o el nombre de una instancia local Oracle. Si no se especifica o es `null`, PHP utiliza variables de entorno como `TWO_TASK` (en Linux) o `LOCAL` (en Windows) y `ORACLE_SID` para determinar la instancia `Oracle` a la que debemos conectarnos. Para usar el método de conexión rápida, PHP debe estar vinculado con la biblioteca cliente Oracle 10g o superior. La cadena de conexión rápida para Oracle 10g o superior es de la forma: [//]host_name[:port][/service_name]. Desde Oracle 11g, la sintaxis es: [//]host_name[:port][/service_name][:server_type][/instance_name]. Opciones adicionales fueron introducidas con Oracle 19c Los nombres de los servicios pueden ser encontrados ejecutando la utilidad Oracle `lsnrctl status` en la máquina que ejecuta la base de datos. El archivo tnsnames.ora puede estar en el camino de búsqueda de Oracle Net, que incluye /your/path/to/instantclient/network/admin, $ORACLE_HOME/network/admin y /etc. Una solución alternativa sería definir `TNS_ADMIN` para que el archivo $TNS_ADMIN/tnsnames.ora sea leído. Asegúrese de que el demonio que ejecuta el servidor web tenga acceso de lectura a este archivo.
`encoding`
  Determina el juego de caracteres utilizado por la biblioteca cliente Oracle. El juego de caracteres no necesita ser idéntico al utilizado por la base de datos. Si no coincide, Oracle hará lo mejor posible para convertir los datos desde el juego de caracteres de la base de datos. Dependiendo de los juegos de caracteres, el resultado puede no ser perfecto. Además, esta conversión requiere un poco de tiempo del sistema. Si no se especifica, la biblioteca cliente Oracle determinará un juego de caracteres desde la variable de entorno `NLS_LANG`. Pasar este parámetro puede reducir el tiempo de conexión.
`session_mode`
  Este parámetro está disponible a partir de PHP 5 (PECL OCI8 1.1) y acepta los siguientes valores: `OCI_DEFAULT`, `OCI_SYSOPER` y `OCI_SYSDBA`. Si bien la constante `OCI_SYSOPER` o la constante `OCI_SYSDBA` es especificada, esta función intentará establecer una conexión privilegiada usando identidades externas. Las conexiones privilegiadas están desactivadas por omisión. Para activarlas, debe definir la opción oci8.privileged_connect a `On`. PHP 5.3 (PECL OCI8 1.3.4) introducen el valor de modo `OCI_CRED_EXT`. Este modo solicita a Oracle usar una identificación externa o bien del sistema operativo, que debe ser configurada en la base de datos. El flag `OCI_CRED_EXT` solo puede ser usado con el nombre de usuario "/" asociado a una contraseña vacía. La opción oci8.privileged_connect puede ser definida a `On` o `Off`. `OCI_CRED_EXT` puede ser combinado con el modo `OCI_SYSOPER` o el modo `OCI_SYSDBA`. `OCI_CRED_EXT` no es soportado en Windows por razones de seguridad.

### Valores devueltos

Devuelve un identificador de conexión, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con oci_pconnect()

    <?php

    // Conexión al servicio XE (i.e. base de datos) en la máquina "localhost"
    $conn = oci_pconnect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Ver la función oci_connect() para más ejemplos sobre el uso de este parámetro.

### Notas

> Nota: La duración y el número máximo de conexiones persistentes Oracle por proceso PHP pueden ajustarse definiendo los siguientes valores de configuración: oci8.persistent_timeout, oci8.ping_interval y oci8.max_persistent.

### Ver también

- oci_connect() - Establece una conexión con un servidor Oracle
- oci_new_connect() - Conexión al servidor Oracle utilizando una sola conexión

# oci_register_taf_callback

(PHP 7.0 >= 7.0.21, PHP 8, PHP 7 >= 7.1.7, PHP 8, PECL OCI8 >= 2.1.7)

oci_register_taf_callback — Registra una función de retrollamada definida por el usuario para Oracle Database TAF

### Descripción

function oci_register_taf_callback(resource `$connection`, ?callable `$callback`): bool

Se registra una función de retrollamada definida por el usuario para `connection`. Si `connection` falla debido a una falla de instancia o de red, la función de retrollamada registrada será invocada varias veces durante el basculement. Ver Soporte de basculement de aplicación transparente OCI8 (TAF) para más información.

Cuando oci_register_taf_callback() es llamada varias veces, cada registro sobrescribe al anterior.

Utilizar oci_unregister_taf_callback() para cancelar explícitamente un retrollamada definida por el usuario.

Los registros de retrollamada TAF NO serán guardados entre conexiones persistentes, por lo tanto, el retrollamada debe ser re-registrado para una nueva conexión persistente.

### Parámetros

`connection`

  Un identificador de conexión Oracle.

`callback`

  Una función de retrollamada definida por el usuario para registrar TAF Oracle. Puede ser una cadena de nombre de función o una clausura (función anónima).

  La interfaz para una función de retrollamada definida por el usuario TAF es la siguiente:

  function userCallbackFn(resource `$connection`, int `$event`, int `$type`): int

  Ver la descripción del parámetro y un ejemplo en la página Soporte de basculement de aplicación transparente OCI8 (TAF).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- oci_unregister_taf_callback() - Anular el registro de una función callback definida para Oracle Database TAF

# oci_result

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_result — Devuelve el valor de una columna en un resultado Oracle

### Descripción

function oci_result(resource `$statement`, string|int `$column`): mixed

Devuelve los datos de la columna `column` en la fila actual del resultado `statement`.

Para más detalles sobre el mapeo de tipos de datos realizado por la extensión OCI8, lea los tipos de datos soportados por el driver.

### Parámetros

`statement`

`column`

  Puede ser el número de la columna (empezando por 1), o el nombre de la columna. Si es el nombre de la columna, es porque las metadatos de Oracle lo presentan de esta manera, y estará en mayúsculas para las columnas creadas sin tener en cuenta la casilla.

### Valores devueltos

Devuelve todos los tipos, excepto los tipos abstractos (ROWIDs, LOBs y FILEs). Devuelve `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con oci_fetch() y oci_result()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo oci_result($stid, 'LOCATION_ID') . " es ";
        echo oci_result($stid, 'CITY') . "<br>\n";
    }

    // Muestra:
    //   1000 es Roma
    //   1100 es Venice

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Ver también

- oci_fetch_array() - Lee una línea de un resultado en forma de array asociativo o numérico
- oci_fetch_assoc() - Lee una línea de un resultado en forma de array asociativo
- oci_fetch_object() - Lee una línea de un resultado en forma de objeto
- oci_fetch_row() - Lee la siguiente línea de una consulta en forma de array numérico
- oci_fetch_all() - Lee múltiples líneas de un resultado en un array multidimensional

# oci_rollback

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_rollback — Anula las transacciones Oracle en curso

### Descripción

function oci_rollback(resource `$connection`): bool

Anula todas las modificaciones no confirmadas para una conexión `connection` Oracle y finaliza la transacción actual. Todos los bloqueos serán liberados asimismo. Todos los puntos de guardado Oracle (`SAVEPOINTS`) serán eliminados.

Una transacción comienza cuando la primera consulta SQL que modifica datos es ejecutada con la función oci_execute() utilizando el flag `OCI_NO_AUTO_COMMIT`. Las modificaciones siguientes realizadas por otras consultas se convierten en parte de la misma transacción. Las modificaciones realizadas durante una transacción son temporales hasta que la transacción sea confirmada o anulada. Los demás usuarios de la base de datos no verán estas modificaciones hasta la confirmación de la transacción.

Al insertar o actualizar datos, el uso de transacciones es altamente recomendado para garantizar la consistencia relacional de los datos, pero también por razones de rendimiento.

### Parámetros

`connection`

  Un identificador de conexión Oracle, devuelto por la función oci_connect(), oci_pconnect() o oci_new_connect().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con oci_rollback()

    <?php

    // Inserción en múltiples tablas, luego, anulación de las modificaciones si ocurren errores

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, "INSERT INTO mysalary (id, name) VALUES (1, 'Chris')");

    // El flag OCI_NO_AUTO_COMMIT indica a Oracle no confirmar la inserción inmediatamente.
    $r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
    if (!$r) {
        $e = oci_error($stid);
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'INSERT INTO myschedule (startday) VALUES (12)');
    $r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
    if (!$r) {
        $e = oci_error($stid);
        oci_rollback($conn);  // Anulación de las modificaciones en las 2 tablas
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    // Confirmación de las modificaciones en las 2 tablas
    $r = oci_commit($conn);
    if (!$r) {
        $e = oci_error($conn);
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    ?>

Ejemplo #2 Ejemplo de retorno a un punto de guardado (`SAVEPOINT`)

    <?php
    $stid = oci_parse($conn, 'UPDATE mytab SET id = 1111');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);

    // creación del punto de guardado
    $stid = oci_parse($conn, 'SAVEPOINT mysavepoint');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);

    $stid = oci_parse($conn, 'UPDATE mytab SET id = 2222');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);

    // utiliza una consulta SQL explícita para realizar el retorno al punto de guardado
    $stid = oci_parse($conn, 'ROLLBACK TO SAVEPOINT mysavepoint');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);

    oci_commit($conn);  // mytab tiene ahora un id de 1111
    ?>

### Notas

> Nota:

> Las transacciones son anuladas automáticamente al cerrar la conexión, o cuando el script finaliza, cualquiera de los dos que ocurra primero. Debe llamarse explícitamente a la función oci_commit() para confirmar la conexión.

> Todas las llamadas a la función oci_execute() que utilizan el modo `OCI_COMMIT_ON_SUCCESS`, ya sea por defecto o de forma explícita, confirmarán todas las transacciones pendientes.

> Todas las consultas Oracle como `CREATE` o `DROP` confirmarán asimismo, automáticamente, todas las transacciones pendientes.

### Ver también

- oci_commit() - Valida las transacciones Oracle en curso
- oci_execute() - Ejecuta un comando SQL de Oracle

# oci_server_version

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_server_version — Devuelve la versión del servidor Oracle

### Descripción

function oci_server_version(resource `$connection`): string|false

Devuelve una cadena que contiene la versión del servidor Oracle junto con las opciones disponibles.

### Parámetros

`connection`

### Valores devueltos

Devuelve la información sobre la versión, en forma de string, o `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con oci_server_version()

    <?php
    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    echo "Versión del servidor : " . oci_server_version($conn);

    // Muestra :
    // Versión del servidor : Oracle Database 11g Enterprise Edition Release 11.2.0.1.0 - 64bit Production
    // With the Partitioning, OLAP, Data Mining and Real Application Testing option

    oci_close($conn);
    ?>

### Ver también

- oci_client_version() - Devuelve la versión de la biblioteca cliente Oracle

# oci_set_action

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_action — Define el nombre de la acción

### Descripción

function oci_set_action(resource `$connection`, string `$action`): bool

Define el nombre de la acción para un seguimiento de Oracle.

El nombre de la acción se registra en la base de datos durante el próximo intercambio 'round-trip' desde PHP hacia la base de datos; típicamente, cuando se ejecuta una consulta SQL.

El nombre de la acción puede ser consultado posteriormente desde la vista de administración de la base de datos `V$SESSION`. Puede ser utilizado para rastrear y monitorear otras vistas como `V$SQLAREA` y `DBMS_MONITOR.SERV_MOD_ACT_STAT_ENABLE`.

El valor puede ser conservado a través de las conexiones persistentes.

### Parámetros

`connection`
  Un identificador de conexión Oracle, devuelto por la función oci_connect(), oci_pconnect() o la función oci_new_connect().
`action`

  String seleccionado por el usuario de hasta 32 caracteres de longitud.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Definición de una acción

    <?php

    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    // Registra la acción
    oci_set_action($c, 'Friend Lookup');

    // Código que genera un intercambio (round-trip), por ejemplo, una consulta:
    $s = oci_parse($c, 'select * from dual');
    oci_execute($s);
    oci_fetch_all($s, $res);

    sleep(30);

    ?>

    // Durante la ejecución del script, el administrador puede ver las acciones
    // en curso de ejecución:

    sqlplus system/welcome
    SQL> select action from v$session;

### Notas

> Nota: Requerido por la versión Oracle
> Esta función está disponible si PHP está vinculado a partir de la versión 10g de la biblioteca de la base de datos Oracle.

Sugerencia

# Rendimiento

Con versiones antiguas de OCI8 o bases de datos Oracle antiguas, la información del cliente puede ser definida usando el paquete Oracle `DBMS_APPLICATION_INFO`. Esto es menos eficiente que usar la función oci_set_client_info().

Precaución

# Ida y vuelta

Algunas funciones OCI8 requieren ida y vuelta con la base de datos. Estas ida y vuelta pueden ser evitadas al usar consultas cuyo resultado es almacenado en caché.

### Ver también

- oci_set_module_name() - Define el nombre del módulo
- oci_set_client_info() - Define la información del cliente
- oci_set_client_identifier() - Define el identificador del cliente
- oci_set_db_operation() - Establece la operación de base de datos

# oci_set_call_timeout

(PHP 7.2 >= 7.2.14, PHP 8, PHP 7 >= 7.3.1, PHP 8, PECL OCI8 >= 2.2.0)

oci_set_call_timeout — Define un tiempo de espera en milisegundos para las llamadas a la base de datos

### Descripción

function oci_set_call_timeout(resource `$connection`, int `$timeout`): bool

Define un tiempo de espera que limita el tiempo máximo que puede tomar un intercambio de base de datos utilizando esta conexión.

Cada operación OCI8 puede realizar cero o más llamadas a la biblioteca cliente de Oracle. Estas llamadas internas pueden luego realizar cero o más intercambios con la base de datos Oracle. Si alguno de estos intercambios toma más de `time_out` milisegundos, entonces la operación se cancela y se devuelve un error a la aplicación.

El valor `time_out` se aplica a cada intercambio individualmente, y no a la suma de todos los intercambios. El tiempo pasado procesando en PHP OCI8 antes o después de la finalización de cada intercambio no se cuenta.

Cuando una llamada es interrumpida, Oracle intentará limpiar la conexión para su reutilización. Esta operación está permitida para ejecutarse durante otro período de `time_out`. Dependiendo del resultado de la limpieza, la conexión puede o no ser reutilizable.

Cuando se utilizan conexiones persistentes, el valor del tiempo de espera será conservado entre las consultas PHP.

La función oci_set_call_timeout() está disponible cuando OCI8 utiliza las bibliotecas clientes de Oracle 18 (o posteriores).

### Parámetros

`connection`
  Un identificador de conexión Oracle, devuelto por la función oci_connect(), oci_pconnect() o la función oci_new_connect().
`timeout`

  El tiempo máximo en milisegundos que puede tomar un intercambio entre PHP y la base de datos Oracle.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Configuración del tiempo de espera

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    oci_set_call_timeout($conn, 5000);

    ?>

# oci_set_client_identifier

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_client_identifier — Define el identificador del cliente

### Descripción

function oci_set_client_identifier(resource `$connection`, string `$client_id`): bool

Define el identificador del cliente, utilizado por numerosos componentes de la base de datos para identificar a los usuarios de la aplicación que se autentican con el mismo nombre de usuario de la base de datos.

El identificador del cliente se registra en la base de datos durante el próximo intercambio 'round-trip' desde PHP hacia la base de datos; típicamente, la ejecución de una consulta SQL.

El identificador puede ser consultado posteriormente, por ejemplo, con la consulta `SELECT SYS_CONTEXT('USERENV','CLIENT_IDENTIFIER') FROM DUAL`. Una vista de administración de la base de datos, como la vista `V$SESSION` también contiene el valor. Puede ser utilizado con `DBMS_MONITOR.CLIENT_ID_TRACE_ENABLE` en el contexto de un trazado. Asimismo, puede ser utilizado en el marco de un audit.

El valor puede ser conservado a lo largo de las diferentes consultas de las páginas que utilizan la misma conexión persistente.

### Parámetros

`connection`
  Un identificador de conexión Oracle, devuelto por la función oci_connect(), oci_pconnect() o la función oci_new_connect().
`client_id`

  Cadena de caracteres elegida por el usuario de hasta 64 bytes de longitud.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Define el identificador del cliente como el usuario de la aplicación

    <?php

    // Recupera el nombre utilizado para la identificación del usuario de la aplicación
    session_start();
    $un = my_validate_session($_SESSION['username']);
    $c = oci_connect('myschema', 'welcome', 'localhost/XE');

    // Informa a Oracle sobre este usuario
    oci_set_client_identifier($c, $un);

    // El próximo intercambio (round-trip) hacia la base de datos validará este identificador
    $s = oci_parse($c, 'select mydata from mytable');
    oci_execute($s);

    // ...

    ?>

### Notas

Precaución

# Ida y vuelta

Algunas funciones OCI8 requieren ida y vuelta con la base de datos. Estas ida y vuelta pueden ser evitadas al usar consultas cuyo resultado es almacenado en caché.

### Ver también

- oci_set_module_name() - Define el nombre del módulo
- oci_set_action() - Define el nombre de la acción
- oci_set_client_info() - Define la información del cliente
- oci_set_db_operation() - Establece la operación de base de datos

# oci_set_client_info

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_client_info — Define la información del cliente

### Descripción

function oci_set_client_info(resource `$connection`, string `$client_info`): bool

Define la información del cliente para el trazado de Oracle.

La información del cliente se registra en la base de datos durante el próximo intercambio 'round-trip' desde PHP hacia la base de datos; típicamente, cuando se ejecuta una consulta SQL.

La información del cliente puede ser consultada posteriormente desde la vista de administración de la base de datos `V$SESSION`.

El valor se conserva mediante el mecanismo de conexiones persistentes.

### Parámetros

`connection`
  Un identificador de conexión Oracle, devuelto por la función oci_connect(), oci_pconnect() o la función oci_new_connect().
`client_info`

  Cadena de caracteres de hasta 64 bytes de longitud.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Define la información del cliente

    <?php

    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    // Registra la información del cliente
    oci_set_client_info($c, 'My Application Version 2');

    // Código que genera un intercambio (round-trip), por ejemplo, una consulta:
    $s = oci_parse($c, 'select * from dual');
    oci_execute($s);
    oci_fetch_all($s, $res);

    sleep(30);

    ?>

    // Durante la ejecución de este script, el administrador puede ver la información
    // del cliente:

    sqlplus system/welcome
    SQL> select client_info from v$session;

### Notas

> Nota: Requerido por la versión Oracle
> Esta función está disponible si PHP está vinculado a partir de la versión 10g de la biblioteca de la base de datos Oracle.

Sugerencia

# Rendimiento

Con versiones antiguas de OCI8 o bases de datos Oracle antiguas, la información del cliente puede ser definida usando el paquete Oracle `DBMS_APPLICATION_INFO`. Esto es menos eficiente que usar la función oci_set_client_info().

Precaución

# Ida y vuelta

Algunas funciones OCI8 requieren ida y vuelta con la base de datos. Estas ida y vuelta pueden ser evitadas al usar consultas cuyo resultado es almacenado en caché.

### Ver también

- oci_set_module_name() - Define el nombre del módulo
- oci_set_action() - Define el nombre de la acción
- oci_set_client_identifier() - Define el identificador del cliente
- oci_set_db_operation() - Establece la operación de base de datos

# oci_set_db_operation

(PHP 7 >= 7.2.14, PHP 8, PHP 7 >= 7.3.1, PHP 8, PECL OCI8 >= 2.2.0)

oci_set_db_operation — Establece la operación de base de datos

### Descripción

function oci_set_db_operation(resource `$connection`, string `$action`): bool

Establece el DBOP para el seguimiento de Oracle.

El nombre de la operación de la base de datos se registra en la base de datos cuando se produce el siguiente "ida y vuelta" de PHP a la base de datos, normalmente cuando se ejecuta una instrucción SQL.

La operación de la base de datos puede consultarse posteriormente desde las vistas de administración de la base de datos como `V$SQL_MONITOR`.

La función oci_set_db_operation() está disponible cuando OCI8 utiliza la biblioteca cliente de Oracle 12 (o posterior) y Oracle Database 12 (o posterior).

### Parámetros

`connection`
  Un identificador de conexión Oracle, devuelto por la función oci_connect(), oci_pconnect() o la función oci_new_connect().
`action`

  El string elegida por el usuario.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ajuste del DBOP

    <?php

    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    // Record the operation
    oci_set_db_operation($c, 'main query');

    // Code that causes a round-trip, for example a query:
    $s = oci_parse($c, 'select * from dual');
    oci_execute($s);
    oci_fetch_all($s, $res);

    sleep(30);

    ?>

    // While the script is running, the administrator can see the database operations
    // being performed:

    sqlplus system/welcome
    SQL> select dbop_name from v$sql_monitor;

### Notas

Precaución

# Ida y vuelta

Algunas funciones OCI8 requieren ida y vuelta con la base de datos. Estas ida y vuelta pueden ser evitadas al usar consultas cuyo resultado es almacenado en caché.

### Ver también

- oci_set_action() - Define el nombre de la acción
- oci_set_module_name() - Define el nombre del módulo
- oci_set_client_info() - Define la información del cliente
- oci_set_client_identifier() - Define el identificador del cliente

# oci_set_edition

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_edition — Define la edición de la base de datos

### Descripción

function oci_set_edition(string `$edition`): bool

Define la edición de los objetos de la base de datos a utilizar por las conexiones.

La edición Oracle permite que versiones concurrentes de las aplicaciones se ejecuten utilizando el mismo nombre de esquema y objetos. Esto es práctico para actualizar sistemas en vivo.

Llame a la función oci_set_edition() antes de llamar a una función como oci_connect(), oci_pconnect() o oci_new_connect().

Si se define una edición pero no es válida en la base de datos, cualquier intento de conexión fallará incluso si la función oci_set_edition() devuelve un estado de éxito.

Al utilizar conexiones persistentes, si una conexión con la edición solicitada ya existe, será reutilizada. De lo contrario, se creará una conexión persistente diferente.

### Parámetros

`edition`

  Nombre de la edición Oracle, previamente creada con el comando SQL "`CREATE EDITION`".

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 2 scripts pueden utilizar diferentes versiones de myfunc() al mismo momento

    <?php

    // Archivo 1

    echo "Versión 1 de la aplicación\n";

    oci_set_edition('ORA$BASE');
    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    $s = oci_parse($c, "begin :r := myfunc(); end;");
    oci_bind_by_name($s, ":r", $r, 20);
    oci_execute($s);
    echo "El resultado es $r\n";

    ?>

    <?php

    // Archivo 2

    echo "Versión 2 de la aplicación\n";

    oci_set_edition('E1');
    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    $s = oci_parse($c, "begin :r := myfunc(); end;");
    oci_bind_by_name($s, ":r", $r, 20);
    oci_execute($s);
    echo "El resultado es $r\n";

    ?>

### Notas

> Nota: Requisito de la versión Oracle

> Esta función está disponible para Oracle 11gR2 y versiones posteriores.

Precaución

# Conexiones persistentes

Para evitar inconsistencias de datos o errores inesperados, no se utilice la consulta ALTER SESSION SET EDITION para cambiar una edición en las conexiones persistentes.

Precaución

# Cola de conexiones DRCP

Para evitar inconsistencias de datos o errores inesperados al utilizar ediciones y DRCP con Oracle 11.2.0.1, mantenga una correspondencia uno-a-uno entre oci8.connection_class y el nombre de la edición utilizado por sus aplicaciones. Cada servidor para una clase de conexión dada debe ser utilizado con una sola edición. Esta restricción fue eliminada en Oracle 11.2.0.2.

# oci_set_module_name

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_module_name — Define el nombre del módulo

### Descripción

function oci_set_module_name(resource `$connection`, string `$name`): bool

Define el nombre del módulo para el trazado de Oracle.

El nombre del módulo se registra en la base de datos durante el próximo viaje de ida y vuelta 'round-trip' desde PHP hacia la base de datos; típicamente, cuando se ejecuta una consulta SQL.

El nombre podrá ser consultado posteriormente desde la vista de administración de la base de datos como `V$SESSION`. También podrá ser utilizado para el trazado y la supervisión, como con `V$SQLAREA` y `DBMS_MONITOR.SERV_MOD_ACT_STAT_ENABLE`.

El valor será retenido mediante el mecanismo de conexiones persistentes.

### Parámetros

`connection`
  Un identificador de conexión Oracle, devuelto por la función oci_connect(), oci_pconnect() o la función oci_new_connect().
`name`

  String seleccionado por el usuario con una longitud máxima de 48 caracteres.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Definición del nombre del módulo

    <?php

    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    // Registro del módulo
    oci_set_module_name($c, 'Home Page');

    // Código que genera un viaje de ida y vuelta (round-trip), por ejemplo, una consulta:
    $s = oci_parse($c, 'select * from dual');
    oci_execute($s);
    oci_fetch_all($s, $res);

    sleep(30);
    ?>

    // Durante la ejecución del script, el administrador puede ver los
    // módulos en uso:

    sqlplus system/welcome
    SQL> select module from v$session;

### Notas

> Nota: Requerido por la versión Oracle
> Esta función está disponible si PHP está vinculado a partir de la versión 10g de la biblioteca de la base de datos Oracle.

Sugerencia

# Rendimiento

Con versiones antiguas de OCI8 o bases de datos Oracle antiguas, la información del cliente puede ser definida usando el paquete Oracle `DBMS_APPLICATION_INFO`. Esto es menos eficiente que usar la función oci_set_client_info().

Precaución

# Ida y vuelta

Algunas funciones OCI8 requieren ida y vuelta con la base de datos. Estas ida y vuelta pueden ser evitadas al usar consultas cuyo resultado es almacenado en caché.

### Ver también

- oci_set_action() - Define el nombre de la acción
- oci_set_client_info() - Define la información del cliente
- oci_set_client_identifier() - Define el identificador del cliente
- oci_set_db_operation() - Establece la operación de base de datos

# oci_set_prefetch

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_set_prefetch — Indica el número de filas que deben leerse por adelantado por Oracle

### Descripción

function oci_set_prefetch(resource `$statement`, int `$rows`): bool

Define el número de filas a pre-cargar por las bibliotecas clientes de Oracle después de una llamada exitosa a la función oci_execute() pero también para cada llamada a las funciones internas de recuperación de filas en la base de datos. Para las consultas que devuelven un gran número de filas, el rendimiento puede mejorar significativamente aumentando el número de filas a pre-cargar respecto al valor por omisión definido por la opción de configuración oci8.default_prefetch.

La pre-carga es una forma eficiente de devolver más de una fila de datos desde la base de datos por cada envío de red. Esto permite una mejor utilización de la red y del CPU. La pre-carga de filas es interna a OCI8 y el comportamiento de las funciones de recuperación de datos permanece inalterado según el valor del contador de pre-carga. Por ejemplo, la función oci_fetch_row() siempre devolverá una fila. El buffer de pre-carga es específico de cada consulta y no será utilizado para re-ejecutar consultas o por otras conexiones.

Es conveniente llamar a la función oci_set_prefetch() antes de la función oci_execute().

Una forma de mejorar la eficiencia es definir el valor de pre-carga a un valor razonable según la red y la base de datos a gestionar. Para las consultas que devuelven un número muy grande de filas, es conveniente recuperar el conjunto de filas por partes (es decir, definir el valor de pre-carga a un valor inferior al número total de filas). Esto permite a la base de datos gestionar las consultas de otros usuarios mientras el script PHP gestiona el conjunto de filas actual.

La pre-carga fue introducida en Oracle 8i. La pre-carga `REF CURSOR` fue introducida en Oracle 11gR2 y está disponible cuando PHP está vinculado con las bibliotecas clientes de Oracle 11gR2 (o superior). Los cursores anidados de pre-carga fueron introducidos en Oracle 11gR2 y requieren tanto las bibliotecas clientes de Oracle, como una base de datos en versión 11gR2 (o superior).

La pre-carga no es soportada cuando las consultas contienen columnas de tipo LONG o LOB. El valor de pre-carga será utilizado en todas las situaciones donde la pre-carga es soportada.

Al utilizar la base de datos Oracle 12c, el conjunto de valores pre-cargados por PHP puede ser sobrescrito por el archivo de configuración cliente de Oracle `oraaccess.xml`. Consulte la documentación de Oracle para más detalles.

### Parámetros

`statement`
  Un identificador de consulta OCI8 creado por la función oci_parse() y ejecutado por la función oci_execute(), o un identificador de consulta `REF CURSOR`.
`rows`

  El número de filas a pre-cargar, >=0

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Modificación del valor de pre-carga para una consulta

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT * FROM myverybigtable');
    oci_set_prefetch($stid, 300);  // A definir antes de la llamada a la función oci_execute()
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Ejemplo #2 Modificación del valor de pre-carga para una recuperación REF CURSOR

    <?php
    /*
      Creación del procedimiento almacenado PL/SQL siguiente :

      CREATE OR REPLACE PROCEDURE myproc(p1 OUT SYS_REFCURSOR) AS
      BEGIN
        OPEN p1 FOR SELECT * FROM all_objects WHERE ROWNUM < 5000;
      END;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'BEGIN myproc(:rc); END;');
    $refcur = oci_new_cursor($conn);
    oci_bind_by_name($stid, ':rc', $refcur, -1, OCI_B_CURSOR);
    oci_execute($stid);

    // Modificación del valor de pre-carga antes de la ejecución del cursor.
    // La pre-carga REF CURSOR funciona cuando PHP está vinculado con las bibliotecas clientes
    // Oracle 11gR2 (o superior)
    oci_set_prefetch($refcur, 200);
    oci_execute($refcur);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($refcur, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($refcur);
    oci_free_statement($stid);
    oci_close($conn);

    ?>

Si PHP OCI8 recupera datos desde un cursor `REF CURSOR` y luego devuelve el cursor `REF CURSOR` a un segundo procedimiento almacenado para su procesamiento, entonces es conveniente definir la pre-carga de `REF CURSOR` a `0` para evitar perder filas del conjunto de resultados. El valor de pre-carga es el número de filas adicionales a recuperar para cada llamada interna OCI8 a la base de datos, por lo tanto, definirlo a `0` significa simplemente que se desea recuperar una sola fila a la vez.

Ejemplo #3 Definición del valor de pre-carga al devolver un cursor `REF CURSOR` a Oracle

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/orcl');

    // Recuperación del cursor REF CURSOR
    $stid = oci_parse($conn, 'BEGIN myproc(:rc_out); END;');
    $refcur = oci_new_cursor($conn);
    oci_bind_by_name($stid, ':rc_out', $refcur, -1, OCI_B_CURSOR);
    oci_execute($stid);

    // Muestra 2 filas, pero no pre-carga filas adicionales
    // de lo contrario, estas filas adicionales no serán pasadas a myproc_use_rc().
    oci_set_prefetch($refcur, 0);
    oci_execute($refcur);
    $row = oci_fetch_array($refcur);
    var_dump($row);
    $row = oci_fetch_array($refcur);
    var_dump($row);

    // pasa el cursor REF CURSOR a myproc_use_rc() para realizar otros
    // procesamientos en el conjunto de resultados
    $stid = oci_parse($conn, 'begin myproc_use_rc(:rc_in); end;');
    oci_bind_by_name($stid, ':rc_in', $refcur, -1, OCI_B_CURSOR);
    oci_execute($stid);

    ?>

### Ver también

- la opción de configuración oci8.default_prefetch

# oci_set_prefetch_lob

(PHP 8.2, PECL OCI8 >= 3.2)

oci_set_prefetch_lob — Define la cantidad de datos precargados para cada CLOB o BLOB.

### Descripción

function oci_set_prefetch_lob(resource `$statement`, int `$prefetch_lob_size`): bool

Define el tamaño del búfer interno utilizado para recuperar cada valor CLOB o BLOB cuando la implementación recupera el localizador LOB interno de Oracle de la base de datos después de una llamada exitosa a oci_execute() y para cada solicitud de recuperación interna posterior a la base de datos. Aumentar este valor puede mejorar el rendimiento de recuperación de los LOB más pequeños al reducir los viajes entre PHP y la base de datos. El uso de la memoria cambiará.

Este valor afecta a los LOB devueltos como instancias OCILob y también a aquellos devueltos utilizando `OCI_RETURN_LOBS`.

Llamar a oci_set_prefetch_lob() antes de llamar a oci_execute(). Si no se hace, se utiliza el valor de oci8.prefetch_lob_size.

El valor de prefetch LOB debe definirse únicamente con Oracle Database 12.2 o posterior.

### Parámetros

`statement`
  Un identificador de consulta OCI8 creado por la función oci_parse() y ejecutado por la función oci_execute(), o un identificador de consulta `REF CURSOR`.
`prefetch_lob_size`

  El número de bytes de cada LOB a precargar, >= 0

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Cambio del valor de prefetch LOB para una consulta

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT myclob FROM mytable');
    oci_set_prefetch_lob($stid, 100000);  // Establecer antes de llamar a oci_execute()
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS+OCI_RETURN_LOBS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Ver también

- La opción ini oci8.prefetch_lob_size

# oci_statement_type

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_statement_type — Devuelve el tipo de consulta Oracle

### Descripción

function oci_statement_type(resource `$statement`): string|false

Devuelve una palabra clave que identifica el tipo de la consulta `statement` OCI8.

### Parámetros

`statement`

  Un identificador de consulta OCI válido, devuelto por la función oci_parse().

### Valores devueltos

Devuelve el tipo de consulta `statement` en forma de una de las siguientes cadenas.

Tipo de consulta
Cadena devuelta | Notas
--- | ---
`ALTER` |
`BEGIN` |
`CALL` |
`CREATE` |
`DECLARE` |
`DELETE` |
`DROP` |
`INSERT` |
`SELECT` |
`UPDATE` |
`UNKNOWN` |

Devuelve `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con oci_statement_type()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'DELETE FROM departments WHERE department_id = 130;');
    if (oci_statement_type($stid) == "DELETE") {
        trigger_error('No se está autorizado a borrar líneas en esta tabla', E_USER_ERROR);
    }
    else {
        oci_execute($stid);  // borra la línea
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# oci_unregister_taf_callback

(PHP 7.0 >= 7.0.23, PHP 8, PHP 7 >= 7.1.9, PHP 8, PECL OCI8 >= 2.1.7)

oci_unregister_taf_callback — Anular el registro de una función callback definida para Oracle Database TAF

### Descripción

function oci_unregister_taf_callback(resource `$connection`): bool

Anula el registro de la función callback definida por el usuario registrada en la `conexión` por oci_register_taf_callback(). Véase Soporte para 'Transparent Application Failover' (TAF) de OCI8 para más información.

### Parámetros

`connection`

  Un identificador de conexión de Oracle.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- oci_register_taf_callback() - Registra una función de retrollamada definida por el usuario para Oracle Database TAF

## Tabla de contenidos

- oci_bind_array_by_name — Asocia un array PHP a un parámetro de array Oracle PL/SQL
- oci_bind_by_name — Asocia una variable PHP a un marcador Oracle
- oci_cancel — Cancela la lectura del cursor
- oci_client_version — Devuelve la versión de la biblioteca cliente Oracle
- oci_close — Cierra una conexión Oracle
- oci_commit — Valida las transacciones Oracle en curso
- oci_connect — Establece una conexión con un servidor Oracle
- oci_define_by_name — Asocia una variable PHP con una columna para una consulta de recuperación de datos
- oci_error — Devuelve el último error de Oracle
- oci_execute — Ejecuta un comando SQL de Oracle
- oci_fetch — Lee la siguiente línea de un resultado Oracle en un buffer interno
- oci_fetch_all — Lee múltiples líneas de un resultado en un array multidimensional
- oci_fetch_array — Lee una línea de un resultado en forma de array asociativo o numérico
- oci_fetch_assoc — Lee una línea de un resultado en forma de array asociativo
- oci_fetch_object — Lee una línea de un resultado en forma de objeto
- oci_fetch_row — Lee la siguiente línea de una consulta en forma de array numérico
- oci_field_is_null — Comprueba si un campo de la fila recuperada es nulo
- oci_field_name — Devuelve el nombre de un campo Oracle
- oci_field_precision — Lee la precisión de un campo Oracle
- oci_field_scale — Lee la escala de una columna Oracle
- oci_field_size — Devuelve el tamaño de un campo Oracle
- oci_field_type — Devuelve el tipo de datos de un campo Oracle
- oci_field_type_raw — Lee los datos brutos del tipo de un campo
- oci_free_descriptor — Libera un descriptor
- oci_free_statement — Libera todos los recursos asociados con una sentencia o cursor
- oci_get_implicit_resultset — Retorna el hijo siguiente de un recurso de consulta desde un recurso de consulta padre que tiene un juego de resultados implícito de Oracle Database
- oci_lob_copy — Copia un LOB Oracle
- oci_lob_is_equal — Comparar dos LOB/FILE de Oracle
- oci_new_collection — Inicializa una nueva colección Oracle
- oci_new_connect — Conexión al servidor Oracle utilizando una sola conexión
- oci_new_cursor — Asigna y devuelve un nuevo cursor Oracle
- oci_new_descriptor — Inicializa un nuevo puntero vacío de LOB/FILE de Oracle
- oci_num_fields — Devuelve el número de columnas en un resultado Oracle
- oci_num_rows — Devuelve el número de filas afectadas durante el último comando Oracle
- oci_parse — Prepara una consulta SQL con Oracle
- oci_password_change — Modifica la contraseña de un usuario Oracle
- oci_pconnect — Establece una conexión persistente a un servidor Oracle
- oci_register_taf_callback — Registra una función de retrollamada definida por el usuario para Oracle Database TAF
- oci_result — Devuelve el valor de una columna en un resultado Oracle
- oci_rollback — Anula las transacciones Oracle en curso
- oci_server_version — Devuelve la versión del servidor Oracle
- oci_set_action — Define el nombre de la acción
- oci_set_call_timeout — Define un tiempo de espera en milisegundos para las llamadas a la base de datos
- oci_set_client_identifier — Define el identificador del cliente
- oci_set_client_info — Define la información del cliente
- oci_set_db_operation — Establece la operación de base de datos
- oci_set_edition — Define la edición de la base de datos
- oci_set_module_name — Define el nombre del módulo
- oci_set_prefetch — Indica el número de filas que deben leerse por adelantado por Oracle
- oci_set_prefetch_lob — Define la cantidad de datos precargados para cada CLOB o BLOB.
- oci_statement_type — Devuelve el tipo de consulta Oracle
- oci_unregister_taf_callback — Anular el registro de una función callback definida para Oracle Database TAF

# La clase OCICollection

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

## Introducción

Funcionalidades de las colecciones OCI8 Collection.

> Nota:

> La clase OCI-Collection fue renombrada a OCICollection en PHP 8 OCI8 3.0.0 para alinearse con los estándares de nomenclatura de PHP.

## Sinopsis de la Clase

class OCICollection {
/* Métodos */
public function append(string `$value`): bool
public function assign(OCICollection `$from`): bool
public function assignElem(int `$index`, string `$value`): bool
public function free(): bool
public function getElem(int `$index`): string|float|null|false
public function max(): int|false
public function size(): int|false
public function trim(int `$num`): bool
}

# OCICollection::append

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::append — Añade un elemento a una colección Oracle

### Descripción

public function OCICollection::append(string `$value`): bool

Añade un elemento al final de una colección Oracle.

### Parámetros

`value`

  El valor a añadir a la colección.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Collection ha sido renombrada a OCICollection para alinear con los estándares de nomenclatura de PHP.

### Ver también

- OCICollection::assign

# OCICollection::assign

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::assign — Asigna un valor a una colección desde otra colección Oracle

### Descripción

public function OCICollection::assign(OCICollection `$from`): bool

Asigna un valor a una colección, a partir de la colección `from`. Las dos colecciones deben haber sido creadas con oci_new_collection() antes de utilizar esta función.

### Parámetros

`from`

  Una instancia OCICollection.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Collection ha sido renombrada a OCICollection para alinearse con los estándares de nomenclatura de PHP.

### Ver también

- OCICollection::append

# OCICollection::assignElem

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::assignElem — Asigna un valor a un elemento de una colección Oracle

### Descripción

public function OCICollection::assignElem(int `$index`, string `$value`): bool

Asigna un valor al elemento cuyo índice es `index`.

### Parámetros

`index`

  El índice del elemento. El primero vale 0.

`value`

  Puede ser una string o un número.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Collection ha sido renombrada a OCICollection para alinearse con los estándares de nomenclatura de PHP.

### Ver también

- OCICollection::getElem

# OCICollection::free

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::free — Libera los recursos asociados con un objeto de colección

### Descripción

public function OCICollection::free(): bool

Libera los recursos asociados con un objeto de colección.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Collection ha sido renombrada a OCICollection para alinearse con los estándares de nomenclatura de PHP.

### Ver también

- oci_new_collection

# OCICollection::getElem

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::getElem — Devuelve el valor de un elemento de una colección Oracle

### Descripción

public function OCICollection::getElem(int `$index`): string|float|null|false

Devuelve el valor del elemento en el índice `index` (comenzando en 0).

### Parámetros

`index`

  El índice del elemento. El primero vale 1.

### Valores devueltos

Devuelve `false` si este elemento no existe; `null`, si el elemento es `null`, un string si la columna es de tipo string, y un número si es un campo numérico.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Collection ha sido renombrada a OCICollection para alinearse con los estándares de nomenclatura de PHP.

### Ver también

- OCICollection::assignElem

# OCICollection::max

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::max — Retorna el número máximo de valores de una colección Oracle

### Descripción

public function OCICollection::max(): int|false

Retorna el número máximo de valores de una colección Oracle.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Retorna el número máximo, en forma de int, o `false` si ocurre un error.

Si el valor retornado es 0, entonces el número de elementos no está limitado.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Collection ha sido renombrada a OCICollection para alinearse con los estándares de nomenclatura de PHP.

### Ver también

- OCICollection::size

# OCICollection::size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::size — Devuelve el tamaño de una colección Oracle

### Descripción

public function OCICollection::size(): int|false

Devuelve el tamaño de una colección Oracle.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de elementos de la colección, o `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Collection ha sido renombrada a OCICollection para alinearse con los estándares de nomenclatura de PHP.

### Ver también

- OCICollection::max

# OCICollection::trim

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::trim — Elimina los últimos elementos de una colección Oracle

### Descripción

public function OCICollection::trim(int `$num`): bool

Elimina los `num` últimos elementos de una colección.

### Parámetros

`num`

  El número de elementos a eliminar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Collection ha sido renombrada a OCICollection para alinearse con los estándares de nomenclatura de PHP.

### Ver también

- OCICollection::size

## Tabla de contenidos

- OCICollection::append — Añade un elemento a una colección Oracle
- OCICollection::assign — Asigna un valor a una colección desde otra colección Oracle
- OCICollection::assignElem — Asigna un valor a un elemento de una colección Oracle
- OCICollection::free — Libera los recursos asociados con un objeto de colección
- OCICollection::getElem — Devuelve el valor de un elemento de una colección Oracle
- OCICollection::max — Retorna el número máximo de valores de una colección Oracle
- OCICollection::size — Devuelve el tamaño de una colección Oracle
- OCICollection::trim — Elimina los últimos elementos de una colección Oracle

# La clase OCILob

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

## Introducción

Funcionalidad OCI8 LOB para los objetos de datos binarios grandes (BLOB) y de caracteres (CLOB).

> Nota:

> La clase OCI-Lob fue renombrada a OCILob en PHP 8 y PECL OCI8 3.0.0 para alinearse con los estándares de nomenclatura de PHP.

## Sinopsis de la Clase

class OCILob {
/* Métodos */
public function append(OCILob `$from`): bool
public function close(): bool
public function eof(): bool
public function erase(?int `$offset` = `null`, ?int `$length` = `null`): int|false
public function export(string `$filename`, ?int `$offset` = `null`, ?int `$length` = `null`): bool
public function flush(int `$flag` = 0): bool
public function free(): bool
public function getBuffering(): bool
public function import(string `$filename`): bool
public function load(): string|false
public function read(int `$length`): string|false
public function rewind(): bool
public function save(string `$data`, int `$offset` = 0): bool
public function seek(int `$offset`, int `$whence` = `OCI_SEEK_SET`): bool
public function setBuffering(bool `$mode`): bool
public function size(): int|false
public function tell(): int|false
public function truncate(int `$length` = 0): bool
public function write(string `$data`, ?int `$length` = `null`): int|false
public function writeTemporary(string `$data`, int `$type` = `OCI_TEMP_CLOB`): bool
}

# OCILob::append

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::append — Añade datos a un LOB Oracle

### Descripción

public function OCILob::append(OCILob `$from`): bool

Añade datos a un LOB Oracle.

La escritura en un LOB con este método fallará si la bufferización ha sido previamente activada. Se debe desactivar la bufferización antes de añadir datos. Puede ser necesario vaciar los buffers con la función OCILob::flush antes de desactivarla.

### Parámetros

`from`

  El LOB copiado.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Lob ha sido renombrada a OCILob para alinearse con los estándares de nomenclatura de PHP.

### Ver también

- OCILob::flush
- OCILob::setBuffering
- OCILob::getBuffering

# OCILob::close

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::close — Cierra un LOB Oracle

### Descripción

public function OCILob::close(): bool

Cierra un LOB Oracle. Esta función debe ser utilizada únicamente con OCILob::writeTemporary.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Lob ha sido renombrada a OCILob para alinear con los estándares de nombramiento de PHP.

### Ver también

- OCILob::writeTemporary

# OCILob::eof

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::eof — Prueba el final del LOB Oracle

### Descripción

public function OCILob::eof(): bool

Verifica si el puntero interno de un LOB está al final.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si el puntero interno de LOB ha alcanzado el final del LOB, y `false` en caso contrario.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Lob ha sido renombrada a OCILob para alinearse con los estándares de nomenclatura de PHP.

### Notas

> Nota:

> Esta función devolverá un error de Oracle si OCILob::setBuffering está activo en el LOB.

### Ver también

- OCILob::size

# OCILob::erase

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::erase — Elimina una parte de un LOB Oracle

### Descripción

public function OCILob::erase(?int `$offset` = `null`, ?int `$length` = `null`): int|false

Elimina la parte del LOB Oracle comenzando en el desplazamiento `offset`, con una longitud de `length` bytes.

Para los BLOB, la eliminación significa que el valor existente del LOB es reemplazado por el carácter 0. Para los CLOB, se utilizan espacios.

### Parámetros

`offset`

`length`

### Valores devueltos

Devuelve el número de caracteres/bytes eliminados o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | `offset` y `length` ahora son nulos.
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Lob ha sido renombrada a OCILob para alinearse con los estándares de nomenclatura de PHP.

### Ver también

- OCILob::truncate

# OCILob::export

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::export — Exporta un LOB Oracle a un fichero

### Descripción

public function OCILob::export(string `$filename`, ?int `$offset` = `null`, ?int `$length` = `null`): bool

Exporta un LOB Oracle a un fichero.

### Parámetros

`filename`

  La ruta de acceso al fichero.

`offset`

  Indica la posición a partir de la cual debe comenzar la exportación.

`length`

  Indica el tamaño de los datos a exportar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | `offset` y `length` ahora son nulos.
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Lob ha sido renombrada a OCILob para alinearse con los estándares de nomenclatura de PHP.

### Ver también

- OCILob::import

# OCILob::flush

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::flush — Escribe los LOB Oracle en el disco

### Descripción

public function OCILob::flush(int `$flag` = 0): bool

OCILob::flush() escribe los datos en el servidor.

### Parámetros

`flag`

  Por omisión, los recursos no son liberados, pero utilizando la opción `flag` con el valor `OCI_LOB_BUFFER_FREE`, puede hacerse explícitamente. Asegúrese de saber bien lo que hace: la próxima lectura o escritura en el mismo LOB requerirá entonces una petición al servidor, y la reasignación de recursos. Se recomienda utilizar la opción `OCI_LOB_BUFFER_FREE` únicamente si ya no se necesita el LOB.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

Retorna `false` si la bufferización no ha sido activada, o si ha ocurrido un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Lob ha sido renombrada a OCILob para alinearse con los estándares de nomenclatura de PHP.

### Ver también

- OCILob::getBuffering
- OCILob::setBuffering

# OCILob::free

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::free — Destruye un puntero de LOB Oracle

### Descripción

public function OCILob::free(): bool

Libera los recursos asociados con el recurso, previamente asignado con oci_new_descriptor().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Lob ha sido renombrada a OCILob para alinearse con los estándares de nomenclatura de PHP.

# OCILob::getBuffering

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::getBuffering — Devuelve el estado de bufferización LOB de Oracle

### Descripción

public function OCILob::getBuffering(): bool

Devuelve el estado de bufferización LOB de Oracle.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `false` si la bufferización de los LOB está desactivada, y `true` si está activada.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Lob ha sido renombrada a OCILob para alinearse con los estándares de nomenclatura de PHP.

### Ver también

- OCILob::setBuffering

# OCILob::import

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::import — Importa un fichero en LOB Oracle

### Descripción

public function OCILob::import(string `$filename`): bool

Escribe los datos del fichero `filename` en el LOB, a partir de la posición actual.

### Parámetros

`filename`

  Ruta de acceso al fichero.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Lob ha sido renombrada a OCILob para alinearse con los estándares de nomenclatura de PHP.

### Ver también

- OCILob::export
- OCILob::write

# OCILob::load

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::load — Devuelve el contenido de un LOB

### Descripción

public function OCILob::load(): string|false

Lee el contenido de un LOB Oracle. El script puede ser interrumpido debido a memory_limit, si este último excede el límite. En la mayoría de los casos, se recomienda utilizar la función OCILob::read en su lugar.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el contenido del objeto, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Lob ha sido renombrada a OCILob para alinearse con los estándares de nomenclatura de PHP.

### Ver también

- OCILob::read

# OCILob::read

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::read — Lee una parte de un LOB Oracle

### Descripción

public function OCILob::read(int `$length`): string|false

Lee `length` bytes (BLOB) o caracteres (CLOB) a partir de la posición actual del LOB.

La lectura se detiene cuando `length` bytes han sido leídos para un BLOB, cuando `length` caracteres han sido leídos para un CLOB, o cuando se alcanza el final del LOB. El puntero del LOB será desplazado por esta lectura del número de bytes/caracteres leídos.

### Parámetros

`length`

  El tamaño de los datos a leer, en bytes para un BLOB, en caracteres para un CLOB. Los valores grandes serán redondeados al MB inferior.

### Valores devueltos

Devuelve el contenido, en forma de un string o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Lob ha sido renombrada a OCILob para alinearse con los estándares de nomenclatura de PHP.

### Ver también

- OCILob::load
- OCILob::write

# OCILob::rewind

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::rewind — Retorna el puntero interno de un LOB Oracle al inicio

### Descripción

public function OCILob::rewind(): bool

Retorna el puntero interno de un LOB Oracle al inicio.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Lob ha sido renombrada a OCILob para alinearse con los estándares de nomenclatura de PHP.

### Ver también

- OCILob::seek
- OCILob::tell

# OCILob::save

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::save — Guardado de datos en un LOB Oracle

### Descripción

public function OCILob::save(string `$data`, int `$offset` = 0): bool

Guardado de datos en un LOB Oracle.

### Parámetros

`data`

  Los datos a guardar.

`offset`

  Puede ser utilizado para indicar la posición desde el inicio del LOB.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Lob ha sido renombrada a OCILob para alinear con los estándares de nomenclatura de PHP.

### Ver también

- OCILob::write
- OCILob::import

# OCILob::saveFile

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::saveFile — Alias de OCILob::import()

### Descripción

Esta función es un alias de: OCILob::import().

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Lob ha sido renombrada a OCILob para ajustarse a los estándares de nomenclatura de PHP.

# OCILob::seek

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::seek — Desplaza el puntero interno de un LOB Oracle

### Descripción

public function OCILob::seek(int `$offset`, int `$whence` = `OCI_SEEK_SET`): bool

Desplaza el puntero interno de un LOB Oracle.

### Parámetros

`offset`

  Indica la distancia de desplazamiento. El tipo de desplazamiento se especifica con `whence`.

`whence`

  Puede ser una constante entre:

  - `OCI_SEEK_SET` - desplaza el puntero a la posición `offset`.
  - `OCI_SEEK_CUR` - añade `offset` bytes a la posición actual.
  - `OCI_SEEK_END` - añade `offset` bytes al final del LOB (utilice un valor negativo para obtener una posición antes del final del LOB).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Lob ha sido renombrada a OCILob para alinear con los estándares de nomenclatura de PHP.

### Ver también

- OCILob::rewind
- OCILob::tell
- OCILob::eof

# OCILob::setBuffering

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::setBuffering — Activa/desactiva la bufferización de los LOB Oracle

### Descripción

public function OCILob::setBuffering(bool `$mode`): bool

Activa o desactiva la bufferización de los LOB Oracle, en función del parámetro `mode`.

Utilizar esta función aporta mejoras de rendimiento mediante la bufferización de pequeñas lecturas y escrituras de LOB: el buffer limita los intercambios con el servidor. OCILob::flush() debe ser utilizado para vaciar los buffers una vez finalizado el trabajo con el LOB.

### Parámetros

`mode`

  `true` para activarlo, y `false` para desactivarlo.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error. Llamadas repetidas a lob->setbuffering() con el mismo valor de parámetro siempre devolverá `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Lob ha sido renombrada a OCILob para alinearse con los estándares de nomenclatura de PHP.

### Ver también

- OCILob::getBuffering

# OCILob::size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::size — Devuelve el tamaño de un LOB Oracle

### Descripción

public function OCILob::size(): int|false

Devuelve el tamaño de un LOB Oracle.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el tamaño del LOB o `false` si ocurre un error. Los objetos vacíos tienen un tamaño de 0.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Lob ha sido renombrada a OCILob para alinearse con los estándares de nomenclatura de PHP.

# OCILob::tell

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::tell — Devuelve la posición actual del puntero de LOB

### Descripción

public function OCILob::tell(): int|false

Devuelve la posición actual del puntero de LOB.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la posición actual del puntero interno del LOB, o bien `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Lob ha sido renombrada a OCILob para alinearse con los estándares de nomenclatura de PHP.

### Ver también

- OCILob::rewind
- OCILob::size
- OCILob::eof

# OCILob::truncate

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::truncate — Trunca un LOB Oracle

### Descripción

public function OCILob::truncate(int `$length` = 0): bool

Trunca un LOB Oracle.

### Parámetros

`length`

  Si `length` es proporcionado, este método truncará el LOB a `length` bytes. De lo contrario, vaciará completamente el LOB.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Lob ha sido renombrada a OCILob para alinearse con los estándares de nomenclatura de PHP.

### Ver también

- OCILob::erase

# OCILob::write

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::write — Escribe datos en un LOB Oracle

### Descripción

public function OCILob::write(string `$data`, ?int `$length` = `null`): int|false

Escribe los datos de la variable `data` en la posición actual del LOB.

### Parámetros

`data`

  Los datos a escribir en el LOB.

`length`

  Si este argumento es un entero, la escritura se detendrá después de `length` bytes, o al final de la variable `data`.

### Valores devueltos

Devuelve el número de bytes escritos o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | `length` ahora es nullable.
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Lob ha sido renombrada a OCILob para alinearse con los estándares de nomenclatura de PHP.

### Ver también

- OCILob::read

# OCILob::writeTemporary

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::writeTemporary — Escribe un LOB Oracle temporal

### Descripción

public function OCILob::writeTemporary(string `$data`, int `$type` = `OCI_TEMP_CLOB`): bool

Crea un LOB temporal y escribe los datos `data` en él.

Se debe utilizar la función OCILob::close cuando se ha terminado de trabajar con el LOB.

### Parámetros

`data`

  Los datos a escribir.

`type`

  Puede tomar uno de los siguientes valores:

  - `OCI_TEMP_BLOB` se utiliza para crear un BLOB temporal.
  - `OCI_TEMP_CLOB` se utiliza para crear un CLOB temporal.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Lob ha sido renombrada a OCILob para alinearse con los estándares de nomenclatura de PHP.

### Ver también

- OCILob::close

# OCILob::writeToFile

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::writeToFile — Alias de OCILob::export()

### Descripción

Esta función es un alias de: OCILob::export().

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0, PECL OCI8 3.0.0 | `offset` y `length` ahora son nullable.
8.0.0, PECL OCI8 3.0.0 | La clase OCI-Lob ha sido renombrada a OCILob para ajustarse a los estándares de nomenclatura de PHP.

## Tabla de contenidos

- OCILob::append — Añade datos a un LOB Oracle
- OCILob::close — Cierra un LOB Oracle
- OCILob::eof — Prueba el final del LOB Oracle
- OCILob::erase — Elimina una parte de un LOB Oracle
- OCILob::export — Exporta un LOB Oracle a un fichero
- OCILob::flush — Escribe los LOB Oracle en el disco
- OCILob::free — Destruye un puntero de LOB Oracle
- OCILob::getBuffering — Devuelve el estado de bufferización LOB de Oracle
- OCILob::import — Importa un fichero en LOB Oracle
- OCILob::load — Devuelve el contenido de un LOB
- OCILob::read — Lee una parte de un LOB Oracle
- OCILob::rewind — Retorna el puntero interno de un LOB Oracle al inicio
- OCILob::save — Guardado de datos en un LOB Oracle
- OCILob::saveFile — Alias de OCILob::import
- OCILob::seek — Desplaza el puntero interno de un LOB Oracle
- OCILob::setBuffering — Activa/desactiva la bufferización de los LOB Oracle
- OCILob::size — Devuelve el tamaño de un LOB Oracle
- OCILob::tell — Devuelve la posición actual del puntero de LOB
- OCILob::truncate — Trunca un LOB Oracle
- OCILob::write — Escribe datos en un LOB Oracle
- OCILob::writeTemporary — Escribe un LOB Oracle temporal
- OCILob::writeToFile — Alias de OCILob::export

# Funciones y alias de OCI8 obsoletos

# oci_internal_debug

(PHP 5, PHP 7, PECL OCI8 >= 1.1.0, PECL OCI8 <= 2.2.0)

oci_internal_debug — Activa o desactiva la salida de depuración interna

### Descripción

function oci_internal_debug(bool `$onoff`): void

Activa o desactiva la salida de depuración interna.

### Parámetros

`onoff`

  Establezca este valor a `false` para desactivar la salida de depuración o a `true` para activarla.

### Valores devueltos

No se retorna ningún valor.

### Notas

> Nota:

> Esta función fue eliminada en PHP 8 y PECL OCI8 3.0.

# ocibindbyname

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocibindbyname — Alias de oci_bind_by_name()

### Descripción

Alias de oci_bind_by_name()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocicancel

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicancel — Alias de oci_cancel()

### Descripción

Alias de oci_cancel()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocicloselob

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 1.0)

ocicloselob — Alias de OCILob::close()

### Descripción

Alias de OCILob::close()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocicollappend

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollappend — Alias de OCICollection::append()

### Descripción

Alias de OCICollection::append()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocicollassign

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 >= 1.0.0)

ocicollassign — Alias de OCICollection::assign()

### Descripción

Alias de OCICollection::assign()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocicollassignelem

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollassignelem — Alias de OCICollection::assignElem()

### Descripción

Alias de OCICollection::assignElem()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocicollgetelem

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollgetelem — Alias de OCICollection::getElem()

### Descripción

Alias de OCICollection::getElem()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocicollmax

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollmax — Alias de OCICollection::max()

### Descripción

Alias de OCICollection::max()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocicollsize

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollsize — Alias de OCICollection::size()

### Descripción

Alias de OCICollection::size()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocicolltrim

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolltrim — Alias de OCICollection::trim()

### Descripción

Alias de OCICollection::trim()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocicolumnisnull

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnisnull — Alias de oci_field_is_null()

### Descripción

Alias de oci_field_is_null()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocicolumnname

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnname — Alias de oci_field_name()

### Descripción

Alias de oci_field_name()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocicolumnprecision

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnprecision — Alias de oci_field_precision()

### Descripción

Alias de oci_field_precision()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocicolumnscale

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnscale — Alias de oci_field_scale()

### Descripción

Alias de oci_field_scale()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocicolumnsize

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnsize — Alias de oci_field_size()

### Descripción

Alias de oci_field_size()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocicolumntype

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumntype — Alias de oci_field_type()

### Descripción

Alias de oci_field_type()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocicolumntyperaw

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumntyperaw — Alias de oci_field_type_raw()

### Descripción

Alias de oci_field_type_raw()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocicommit

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicommit — Alias de oci_commit()

### Descripción

Alias de oci_commit()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocidefinebyname

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocidefinebyname — Alias de oci_define_by_name()

### Descripción

Alias de oci_define_by_name()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocierror

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocierror — Alias de oci_error()

### Descripción

Alias de oci_error()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ociexecute

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociexecute — Alias de oci_execute()

### Descripción

Alias de oci_execute()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocifetch

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetch — Alias de oci_fetch()

### Descripción

Alias de oci_fetch()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocifetchinto

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetchinto — Variante obsoleta de oci_fetch_array(), oci_fetch_object(), oci_fetch_assoc() y oci_fetch_row()

### Descripción

Variante absoleta de oci_fetch_array(), oci_fetch_object(), oci_fetch_assoc() y oci_fetch_row()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocifetchstatement

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetchstatement — Alias de oci_fetch_all()

### Descripción

Alias de oci_fetch_all()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocifreecollection

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreecollection — Alias de OCICollection::free()

### Descripción

Alias de OCICollection::free()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocifreecursor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreecursor — Alias de oci_free_statement()

### Descripción

Alias de oci_free_statement()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocifreedesc

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreedesc — Alias de OCILob::free()

### Descripción

Alias de OCILob::free()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocifreestatement

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreestatement — Alias de oci_free_statement()

### Descripción

Alias de oci_free_statement()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ociinternaldebug

(PHP 4, PHP 5, PHP 7, PECL OCI8 >= 1.0.0, PECL OCI8 <= 2.2.0)

ociinternaldebug — Alias de oci_internal_debug()

### Descripción

Alias de oci_internal_debug()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ociloadlob

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociloadlob — Alias de OCILob::load()

### Descripción

Alias de OCILob::load()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocilogoff

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocilogoff — Alias de oci_close()

### Descripción

Alias de oci_close()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocilogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocilogon — Alias de oci_connect()

### Descripción

Alias de oci_connect()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocinewcollection

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewcollection — Alias de oci_new_collection()

### Descripción

Alias de oci_new_collection()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocinewcursor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewcursor — Alias de oci_new_cursor()

### Descripción

Alias de oci_new_cursor()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocinewdescriptor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewdescriptor — Alias de oci_new_descriptor()

### Descripción

Alias de oci_new_descriptor()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocinlogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinlogon — Alias de oci_new_connect()

### Descripción

Alias de oci_new_connect()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocinumcols

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinumcols — Alias de oci_num_fields()

### Descripción

Alias de oci_num_fields()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ociparse

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociparse — Alias de oci_parse()

### Descripción

Alias de oci_parse()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ociplogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociplogon — Alias de oci_pconnect()

### Descripción

Alias de oci_pconnect()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ociresult

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociresult — Alias de oci_result()

### Descripción

Alias de oci_result()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocirollback

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocirollback — Alias de oci_rollback()

### Descripción

Alias de oci_rollback()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocirowcount

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocirowcount — Alias de oci_num_rows()

### Descripción

Alias de oci_num_rows()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocisavelob

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisavelob — Alias de OCILob::save()

### Descripción

Alias de OCILob::save()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocisavelobfile

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisavelobfile — Alias de OCILob::import()

### Descripción

Alias de OCILob::import()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ociserverversion

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociserverversion — Alias de oci_server_version()

### Descripción

Alias de oci_server_version()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocisetprefetch

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisetprefetch — Alias de oci_set_prefetch()

### Descripción

Alias de oci_set_prefetch()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ocistatementtype

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocistatementtype — Alias de oci_statement_type()

### Descripción

Alias de oci_statement_type()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ociwritelobtofile

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociwritelobtofile — Alias de OCILob::export()

### Descripción

Alias de OCILob::export()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

# ociwritetemporarylob

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 1.0)

ociwritetemporarylob — Alias de OCILob::writeTemporary()

### Descripción

Alias de OCILob::writeTemporary()

Advertencia

Este alias está OBSOLETO a partir de PHP 5.4.0. Depender de este alias está fuertemente desaconsejado.

## Tabla de contenidos

- oci_internal_debug — Activa o desactiva la salida de depuración interna
- ocibindbyname — Alias de oci_bind_by_name
- ocicancel — Alias de oci_cancel
- ocicloselob — Alias de OCILob::close
- ocicollappend — Alias de OCICollection::append
- ocicollassign — Alias de OCICollection::assign
- ocicollassignelem — Alias de OCICollection::assignElem
- ocicollgetelem — Alias de OCICollection::getElem
- ocicollmax — Alias de OCICollection::max
- ocicollsize — Alias de OCICollection::size
- ocicolltrim — Alias de OCICollection::trim
- ocicolumnisnull — Alias de oci_field_is_null
- ocicolumnname — Alias de oci_field_name
- ocicolumnprecision — Alias de oci_field_precision
- ocicolumnscale — Alias de oci_field_scale
- ocicolumnsize — Alias de oci_field_size
- ocicolumntype — Alias de oci_field_type
- ocicolumntyperaw — Alias de oci_field_type_raw
- ocicommit — Alias de oci_commit
- ocidefinebyname — Alias de oci_define_by_name
- ocierror — Alias de oci_error
- ociexecute — Alias de oci_execute
- ocifetch — Alias de oci_fetch
- ocifetchinto — Variante obsoleta de oci_fetch_array, oci_fetch_object, oci_fetch_assoc y oci_fetch_row
- ocifetchstatement — Alias de oci_fetch_all
- ocifreecollection — Alias de OCICollection::free
- ocifreecursor — Alias de oci_free_statement
- ocifreedesc — Alias de OCILob::free
- ocifreestatement — Alias de oci_free_statement
- ociinternaldebug — Alias de oci_internal_debug
- ociloadlob — Alias de OCILob::load
- ocilogoff — Alias de oci_close
- ocilogon — Alias de oci_connect
- ocinewcollection — Alias de oci_new_collection
- ocinewcursor — Alias de oci_new_cursor
- ocinewdescriptor — Alias de oci_new_descriptor
- ocinlogon — Alias de oci_new_connect
- ocinumcols — Alias de oci_num_fields
- ociparse — Alias de oci_parse
- ociplogon — Alias de oci_pconnect
- ociresult — Alias de oci_result
- ocirollback — Alias de oci_rollback
- ocirowcount — Alias de oci_num_rows
- ocisavelob — Alias de OCILob::save
- ocisavelobfile — Alias de OCILob::import
- ociserverversion — Alias de oci_server_version
- ocisetprefetch — Alias de oci_set_prefetch
- ocistatementtype — Alias de oci_statement_type
- ociwritelobtofile — Alias de OCILob::export
- ociwritetemporarylob — Alias de OCILob::writeTemporary

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Pruebas
  - Configuración en tiempo de ejecución
- Constantes predefinidas
- Ejemplos
- Gestión de la conexión OCI8 y la cola de espera
- Soporte de FAN (Fast Application Notification : Notificación Rápida de Aplicación) OCI8
- El soporte de la reanudación transparente de aplicación (TAF) de OCI8
- OCI8 y rastreo dinámico de DTrace
- Tipos de datos admitidos
- Funciones de OCI8
  - oci_bind_array_by_name — Asocia un array PHP a un parámetro de array Oracle PL/SQL
  - oci_bind_by_name — Asocia una variable PHP a un marcador Oracle
  - oci_cancel — Cancela la lectura del cursor
  - oci_client_version — Devuelve la versión de la biblioteca cliente Oracle
  - oci_close — Cierra una conexión Oracle
  - oci_commit — Valida las transacciones Oracle en curso
  - oci_connect — Establece una conexión con un servidor Oracle
  - oci_define_by_name — Asocia una variable PHP con una columna para una consulta de recuperación de datos
  - oci_error — Devuelve el último error de Oracle
  - oci_execute — Ejecuta un comando SQL de Oracle
  - oci_fetch — Lee la siguiente línea de un resultado Oracle en un buffer interno
  - oci_fetch_all — Lee múltiples líneas de un resultado en un array multidimensional
  - oci_fetch_array — Lee una línea de un resultado en forma de array asociativo o numérico
  - oci_fetch_assoc — Lee una línea de un resultado en forma de array asociativo
  - oci_fetch_object — Lee una línea de un resultado en forma de objeto
  - oci_fetch_row — Lee la siguiente línea de una consulta en forma de array numérico
  - oci_field_is_null — Comprueba si un campo de la fila recuperada es nulo
  - oci_field_name — Devuelve el nombre de un campo Oracle
  - oci_field_precision — Lee la precisión de un campo Oracle
  - oci_field_scale — Lee la escala de una columna Oracle
  - oci_field_size — Devuelve el tamaño de un campo Oracle
  - oci_field_type — Devuelve el tipo de datos de un campo Oracle
  - oci_field_type_raw — Lee los datos brutos del tipo de un campo
  - oci_free_descriptor — Libera un descriptor
  - oci_free_statement — Libera todos los recursos asociados con una sentencia o cursor
  - oci_get_implicit_resultset — Retorna el hijo siguiente de un recurso de consulta desde un recurso de consulta padre que tiene un juego de resultados implícito de Oracle Database
  - oci_lob_copy — Copia un LOB Oracle
  - oci_lob_is_equal — Comparar dos LOB/FILE de Oracle
  - oci_new_collection — Inicializa una nueva colección Oracle
  - oci_new_connect — Conexión al servidor Oracle utilizando una sola conexión
  - oci_new_cursor — Asigna y devuelve un nuevo cursor Oracle
  - oci_new_descriptor — Inicializa un nuevo puntero vacío de LOB/FILE de Oracle
  - oci_num_fields — Devuelve el número de columnas en un resultado Oracle
  - oci_num_rows — Devuelve el número de filas afectadas durante el último comando Oracle
  - oci_parse — Prepara una consulta SQL con Oracle
  - oci_password_change — Modifica la contraseña de un usuario Oracle
  - oci_pconnect — Establece una conexión persistente a un servidor Oracle
  - oci_register_taf_callback — Registra una función de retrollamada definida por el usuario para Oracle Database TAF
  - oci_result — Devuelve el valor de una columna en un resultado Oracle
  - oci_rollback — Anula las transacciones Oracle en curso
  - oci_server_version — Devuelve la versión del servidor Oracle
  - oci_set_action — Define el nombre de la acción
  - oci_set_call_timeout — Define un tiempo de espera en milisegundos para las llamadas a la base de datos
  - oci_set_client_identifier — Define el identificador del cliente
  - oci_set_client_info — Define la información del cliente
  - oci_set_db_operation — Establece la operación de base de datos
  - oci_set_edition — Define la edición de la base de datos
  - oci_set_module_name — Define el nombre del módulo
  - oci_set_prefetch — Indica el número de filas que deben leerse por adelantado por Oracle
  - oci_set_prefetch_lob — Define la cantidad de datos precargados para cada CLOB o BLOB.
  - oci_statement_type — Devuelve el tipo de consulta Oracle
  - oci_unregister_taf_callback — Anular el registro de una función callback definida para Oracle Database TAF
- OCICollection — La clase OCICollection
  - OCICollection::append — Añade un elemento a una colección Oracle
  - OCICollection::assign — Asigna un valor a una colección desde otra colección Oracle
  - OCICollection::assignElem — Asigna un valor a un elemento de una colección Oracle
  - OCICollection::free — Libera los recursos asociados con un objeto de colección
  - OCICollection::getElem — Devuelve el valor de un elemento de una colección Oracle
  - OCICollection::max — Retorna el número máximo de valores de una colección Oracle
  - OCICollection::size — Devuelve el tamaño de una colección Oracle
  - OCICollection::trim — Elimina los últimos elementos de una colección Oracle
- OCILob — La clase OCILob
  - OCILob::append — Añade datos a un LOB Oracle
  - OCILob::close — Cierra un LOB Oracle
  - OCILob::eof — Prueba el final del LOB Oracle
  - OCILob::erase — Elimina una parte de un LOB Oracle
  - OCILob::export — Exporta un LOB Oracle a un fichero
  - OCILob::flush — Escribe los LOB Oracle en el disco
  - OCILob::free — Destruye un puntero de LOB Oracle
  - OCILob::getBuffering — Devuelve el estado de bufferización LOB de Oracle
  - OCILob::import — Importa un fichero en LOB Oracle
  - OCILob::load — Devuelve el contenido de un LOB
  - OCILob::read — Lee una parte de un LOB Oracle
  - OCILob::rewind — Retorna el puntero interno de un LOB Oracle al inicio
  - OCILob::save — Guardado de datos en un LOB Oracle
  - OCILob::saveFile — Alias de OCILob::import
  - OCILob::seek — Desplaza el puntero interno de un LOB Oracle
  - OCILob::setBuffering — Activa/desactiva la bufferización de los LOB Oracle
  - OCILob::size — Devuelve el tamaño de un LOB Oracle
  - OCILob::tell — Devuelve la posición actual del puntero de LOB
  - OCILob::truncate — Trunca un LOB Oracle
  - OCILob::write — Escribe datos en un LOB Oracle
  - OCILob::writeTemporary — Escribe un LOB Oracle temporal
  - OCILob::writeToFile — Alias de OCILob::export
- Funciones y alias de OCI8 obsoletos
  - oci_internal_debug — Activa o desactiva la salida de depuración interna
  - ocibindbyname — Alias de oci_bind_by_name
  - ocicancel — Alias de oci_cancel
  - ocicloselob — Alias de OCILob::close
  - ocicollappend — Alias de OCICollection::append
  - ocicollassign — Alias de OCICollection::assign
  - ocicollassignelem — Alias de OCICollection::assignElem
  - ocicollgetelem — Alias de OCICollection::getElem
  - ocicollmax — Alias de OCICollection::max
  - ocicollsize — Alias de OCICollection::size
  - ocicolltrim — Alias de OCICollection::trim
  - ocicolumnisnull — Alias de oci_field_is_null
  - ocicolumnname — Alias de oci_field_name
  - ocicolumnprecision — Alias de oci_field_precision
  - ocicolumnscale — Alias de oci_field_scale
  - ocicolumnsize — Alias de oci_field_size
  - ocicolumntype — Alias de oci_field_type
  - ocicolumntyperaw — Alias de oci_field_type_raw
  - ocicommit — Alias de oci_commit
  - ocidefinebyname — Alias de oci_define_by_name
  - ocierror — Alias de oci_error
  - ociexecute — Alias de oci_execute
  - ocifetch — Alias de oci_fetch
  - ocifetchinto — Variante obsoleta de oci_fetch_array, oci_fetch_object, oci_fetch_assoc y oci_fetch_row
  - ocifetchstatement — Alias de oci_fetch_all
  - ocifreecollection — Alias de OCICollection::free
  - ocifreecursor — Alias de oci_free_statement
  - ocifreedesc — Alias de OCILob::free
  - ocifreestatement — Alias de oci_free_statement
  - ociinternaldebug — Alias de oci_internal_debug
  - ociloadlob — Alias de OCILob::load
  - ocilogoff — Alias de oci_close
  - ocilogon — Alias de oci_connect
  - ocinewcollection — Alias de oci_new_collection
  - ocinewcursor — Alias de oci_new_cursor
  - ocinewdescriptor — Alias de oci_new_descriptor
  - ocinlogon — Alias de oci_new_connect
  - ocinumcols — Alias de oci_num_fields
  - ociparse — Alias de oci_parse
  - ociplogon — Alias de oci_pconnect
  - ociresult — Alias de oci_result
  - ocirollback — Alias de oci_rollback
  - ocirowcount — Alias de oci_num_rows
  - ocisavelob — Alias de OCILob::save
  - ocisavelobfile — Alias de OCILob::import
  - ociserverversion — Alias de oci_server_version
  - ocisetprefetch — Alias de oci_set_prefetch
  - ocistatementtype — Alias de oci_statement_type
  - ociwritelobtofile — Alias de OCILob::export
  - ociwritetemporarylob — Alias de OCILob::writeTemporary

# PostgreSQL

# Introducción

La base de datos PostgreSQL es un producto Open Source, disponible sin costo alguno. PostgreSQL, desarrollado en el departamento de Ciencias de la Computación en UC Berkeley, implementa la mayoría de los conceptos de las bases de datos relacionales actualmente disponibles en el mercado. PostgreSQL acepta el lenguaje SQL92/SQL3, garantiza la integridad transaccional y la extensión de tipos. PostgreSQL es una evolución del código original de Berkeley.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución
- Tipos de recursos

## Requerimientos

Para utilizar el soporte PostgreSQL, se necesita libpq. A partir de PHP 8.0.0, se requiere libpq 9.1 o posterior. A partir de PHP 8.4.0, se requiere libpq 10.0 o posterior. PostgreSQL soporta numerosos juegos de caracteres, incluyendo los juegos multioctetos asiáticos. La versión actual y más detalles sobre PostgreSQL están disponibles en el sitio » http://www.postgresql.org/ y la » Documentación PostgreSQL.

## Instalación

Con el fin de habilitar el soporte de PostgreSQL, --with-pgsql[=DIR] es requerido cuando se compila PHP. `DIR` es el directorio base donde está instalado PostgreSQL, por defecto generalmente es /usr/local/pgsql en sistemas linux. Si el módulo de objetos compartidos está disponible, el módulo PostgreSQL puede ser cargado usando la directiva extension en php.ini o la función dl().

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración PostgreSQL
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
pgsql.allow_persistent | "1" | `INI_SYSTEM` |
pgsql.max_persistent | "-1" | `INI_SYSTEM` |
pgsql.max_links | "-1" | `INI_SYSTEM` |
pgsql.auto_reset_persistent | "0" | `INI_SYSTEM` |
pgsql.ignore_notice | "0" | `INI_ALL` |
pgsql.log_notice | "0" | `INI_ALL` |

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`pgsql.allow_persistent` bool

  Si se permiten conexiones Postgres persistentes.

`pgsql.max_persistent` int

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

`pgsql.max_links` int

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

`pgsql.auto_reset_persistent` int

  Detectar conexiones persitentes rotas con pg_pconnect(). Necesita un breve tiempo adicional.

`pgsql.ignore_notice` int

  Hacer caso o no a los mensajes de avisos del backend PostgreSQL.

`pgsql.log_notice` int

  Registrar o no los mensajes de aviso del backend PostgreSQL. La directiva PHP pgsql.ignore_notice debe estar apagada para registrar los mensajes de aviso

## Tipos de recursos

Antes de PHP 8.1.0, existían dos tipos de recursos utilizados en el módulo PostgreSQL. El primero es el identificador para la conexión a la base de datos y el segundo es un recurso que contiene el resultado de una consulta.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`PGSQL_LIBPQ_VERSION` (string)
  Versión corta de libpq que solo contiene números y puntos.
`PGSQL_LIBPQ_VERSION_STR` (string)
  Anterior a PHP 8.0.0, la versión larga de libpq que incluye las informaciones del compilador. A partir de PHP 8.0.0, el valor es idéntico a `PGSQL_LIBPQ_VERSION`, y el uso de `PGSQL_LIBPQ_VERSION_STR` es obsoleto.
`PGSQL_ASSOC` (int)
  Pasada a pg_fetch_array(). Devuelve un array asociativo de los nombres y valores de los campos.
`PGSQL_NUM` (int)
  Pasada a pg_fetch_array(). Devuelve un array con índice numérico de los números y valores de los campos.
`PGSQL_BOTH` (int)
  Pasada a pg_fetch_array(). Devuelve un array de los valores de los campos que está indexado numéricamente (por el número de los campos) y indexado literalmente (por el nombre de los campos).
`PGSQL_CONNECT_FORCE_NEW` (int)
  Pasada a pg_connect() para forzar la creación de una nueva conexión, en lugar de reutilizar una conexión existente idéntica.
`PGSQL_CONNECT_ASYNC` (int)
  Pasada a la función pg_connect() para crear una conexión asíncrona.
`PGSQL_CONNECTION_AUTH_OK` (int)
`PGSQL_CONNECTION_AWAITING_RESPONSE` (int)
`PGSQL_CONNECTION_BAD` (int)
  Retornada por pg_connection_status() indicando que la conexión a la base de datos es inválida.
`PGSQL_CONNECTION_MADE` (int)
`PGSQL_CONNECTION_OK` (int)
  Retornada por pg_connection_status() indicando que la conexión a la base de datos es válida.
`PGSQL_CONNECTION_SETENV` (int)
`PGSQL_CONNECTION_SSL_STARTUP` (int)
`PGSQL_CONNECTION_STARTED` (int)
`PGSQL_SEEK_SET` (int)
  Pasada a pg_lo_seek(). El posicionamiento comenzará al inicio del objeto.
`PGSQL_SEEK_CUR` (int)
  Pasada a pg_lo_seek(). El posicionamiento comenzará a la posición actual.
`PGSQL_SEEK_END` (int)
  Pasada a pg_lo_seek(). El posicionamiento comenzará al final del objeto.
`PGSQL_EMPTY_QUERY` (int)
  Retornada por pg_result_status(). La cadena de caracteres enviada al servidor estaba vacía.
`PGSQL_COMMAND_OK` (int)
  Retornada por pg_result_status(). Comando correctamente completado sin devolver datos.
`PGSQL_TUPLES_OK` (int)
  Retornada por pg_result_status(). Comando correctamente completado devolviendo datos (como `SELECT` o `SHOW`).
`PGSQL_TUPLES_CHUNK` (int)
  Retornado por pg_result_status(). Indica el éxito en la ejecución de un comando que devuelve datos en modo por bloques. Retornado para los comandos `SELECT` cuando pg_set_chunked_rows_size() está definido. El conjunto de resultados se divide en varios bloques, cada uno conteniendo un número predeterminado de filas. Disponible a partir de PHP 8.4.0 y libpq 17.
`PGSQL_COPY_OUT` (int)
  Retornada por pg_result_status(). Copia (desde el servidor) de transferencia de datos iniciada.
`PGSQL_COPY_IN` (int)
  Retornada por pg_result_status(). Copia (hacia el servidor) de transferencia de datos iniciada.
`PGSQL_BAD_RESPONSE` (int)
  Retornada por pg_result_status(). La respuesta del servidor no ha sido comprendida.
`PGSQL_NONFATAL_ERROR` (int)
  Retornada por pg_result_status(). Un error no fatal (de nivel notice o warning) ha ocurrido.
`PGSQL_FATAL_ERROR` (int)
  Retornada por pg_result_status(). Un error fatal ha ocurrido.
`PGSQL_TRANSACTION_IDLE` (int)
  Retornada por pg_transaction_Status(). La conexión está actualmente libre, sin transacción en curso.
`PGSQL_TRANSACTION_ACTIVE` (int)
  Retornada por pg_transaction_status(). Un comando está en curso en la conexión. Una consulta ha sido enviada a la conexión y aún no ha sido completada.
`PGSQL_TRANSACTION_INTRANS` (int)
  Retornada por pg_transaction_status(). La conexión está libre, dentro de un bloque de transacción.
`PGSQL_TRANSACTION_INERROR` (int)
  Retornada por pg_transaction_status(). La conexión está libre, dentro de un bloque de transacción fallido.
`PGSQL_TRANSACTION_UNKNOWN` (int)
  Retornada por pg_transaction_status(). La conexión es mala.
`PGSQL_DIAG_SEVERITY` (int)
  Pasada a pg_result_error_field(). La severidad; el contenido del campo es `ERROR`, `FATAL` o `PANIC` (en un mensaje de error) o `WARNING`, `NOTICE`, `DEBUG`, `INFO` o `LOG` (en un mensaje de advertencia) o una traducción localizada de estos. Siempre presente.
`PGSQL_DIAG_SQLSTATE` (int)
  Pasada a pg_result_error_field(). El código SQLSTATE para este error. El código SQLSTATE identifica el tipo de error que ha ocurrido; esto puede ser utilizado por aplicaciones de entrada para realizar operaciones específicas (como manejo de errores) en respuesta a un error particular de base de datos. Este campo no puede ser localizado y siempre está presente.
`PGSQL_DIAG_MESSAGE_PRIMARY` (int)
  Pasada a pg_result_error_field(). El campo de error principal interpretable para el usuario (normalmente una línea). Siempre presente.
`PGSQL_DIAG_MESSAGE_DETAIL` (int)
  Pasada a pg_result_error_field(). Detalle: un segundo mensaje de error opcional que aporta más detalles sobre el problema. Puede estar en varias líneas.
`PGSQL_DIAG_MESSAGE_HINT` (int)
  Pasada a pg_result_error_field(). Consejo: una sugerencia opcional que indica qué hacer sobre el problema. Esto está previsto para ser diferente del error ya que ofrece un consejo (potencialmente inadecuado) en lugar de hechos verídicos. Puede estar en varias líneas.
`PGSQL_DIAG_STATEMENT_POSITION` (int)
  Pasada a pg_result_error_field(). Una cadena de caracteres que contiene un valor entero decimal indicando una posición de error del cursor como índice en la consulta original. El primer carácter tiene el índice 1 y las posiciones son medidas en caracteres, no en bytes.
`PGSQL_DIAG_INTERNAL_POSITION` (int)
  Pasada a pg_result_error_field(). Esto está definido siendo lo mismo que el campo `PG_DIAG_STATEMENT_POSITION`, pero esto se utiliza cuando la posición del cursor se refiere a una consulta generada internamente en lugar de una enviada por el cliente. El campo `PG_DIAG_INTERNAL_QUERY` aparecerá siempre cuando este campo aparezca.
`PGSQL_DIAG_INTERNAL_QUERY` (int)
  Pasada a pg_result_error_field(). El texto de una consulta generada internamente fallida. Esto puede ser, por ejemplo, una consulta SQL enviada por una función PL/pgSQL.
`PGSQL_DIAG_CONTEXT` (int)
  Pasada a pg_result_error_field(). Una indicación del contexto en el que el error ocurrió. Actualmente, esto incluye una pila de llamadas de traceback de las funciones procedimentales activas así como consultas generadas internamente. El rastreo es una entrada por línea, las más recientes primero.
`PGSQL_DIAG_SOURCE_FILE` (int)
  Pasada a pg_result_error_field(). El nombre del archivo de la ubicación del código fuente de PostgreSQL donde el error fue reportado.
`PGSQL_DIAG_SOURCE_LINE` (int)
  Pasada a pg_result_error_field(). El número de línea de la ubicación del código fuente de PostgreSQL donde el error fue reportado.
`PGSQL_DIAG_SOURCE_FUNCTION` (int)
  Pasada a pg_result_error_field(). El nombre de la función del código fuente de PostgreSQL que reportó el error.
`PGSQL_DIAG_SCHEMA_NAME` (int)
  Disponible desde PHP 7.3.0.
`PGSQL_DIAG_TABLE_NAME` (int)
  Disponible desde PHP 7.3.0.
`PGSQL_DIAG_COLUMN_NAME` (int)
  Disponible desde PHP 7.3.0.
`PGSQL_DIAG_DATATYPE_NAME` (int)
  Disponible desde PHP 7.3.0.
`PGSQL_DIAG_CONSTRAINT_NAME` (int)
  Disponible desde PHP 7.3.0.
`PGSQL_ERRORS_TERSE` (int)
  Pasada a pg_set_error_verbosity(). Especifica que los mensajes retornados incluyen la severidad, el texto principal así como la posición solamente; esto debería entrar en una sola línea.
`PGSQL_ERRORS_DEFAULT` (int)
  Pasada a pg_set_error_verbosity(). El modo por omisión produce mensajes que incluyen lo anterior y detalles adicionales, consejos o campos de contexto (esto puede estar en varias líneas).
`PGSQL_ERRORS_VERBOSE` (int)
  Pasada a pg_set_error_verbosity(). El modo verboso incluye todos los campos disponibles.
`PGSQL_ERRORS_SQLSTATE` (int)
  Pasado a pg_set_error_verbosity(). Incluye únicamente la severidad del error y el código de error `SQLSTATE`. Si no hay código de error disponible, la salida es similar al modo `PGSQL_ERRORS_TERSE`. Antes de PostgreSQL 11.1, la salida es siempre la misma que en el modo `PGSQL_ERRORS_TERSE`.
`PGSQL_NOTICE_LAST` (int)
  Utilizado por pg_last_notice(). Disponible a partir de PHP 7.1.0.
`PGSQL_NOTICE_ALL` (int)
  Utilizado por pg_last_notice(). Disponible a partir de PHP 7.1.0.
`PGSQL_NOTICE_CLEAR` (int)
  Utilizado por pg_last_notice(). Disponible a partir de PHP 7.1.0.
`PGSQL_STATUS_LONG` (int)
  Pasada a pg_result_status(). Indica que el código de resultado es deseado numérico.
`PGSQL_STATUS_STRING` (int)
  Pasada a pg_result_status(). Indica que la etiqueta de resultado de comando es deseada textual.
`PGSQL_CONV_IGNORE_DEFAULT` (int)
  Pasada a pg_convert(). Ignora los valores por omisión en la tabla durante la conversión.
`PGSQL_CONV_FORCE_NULL` (int)
  Pasada a pg_convert(). Utiliza SQL `null` en lugar de una string vacía.
`PGSQL_CONV_IGNORE_NOT_NULL` (int)
  Pasada a pg_convert(). Ignora la conversión de `null` dentro de columnas `NOT NULL`.
`PGSQL_DML_NO_CONV` (int)
  Pasada a las funciones pg_insert(), pg_select(), pg_update() y pg_delete(). Todos los argumentos pasados tal cual. Un escape manual es necesario si los argumentos contienen datos proporcionados por el usuario. Utilice la función pg_escape_string() para esto.
`PGSQL_DML_EXEC` (int)
  Pasada a las funciones pg_insert(), pg_select(), pg_update() y pg_delete(). Ejecución de la consulta por estas funciones.
`PGSQL_DML_ASYNC` (int)
  Pasada a las funciones pg_insert(), pg_select(), pg_update() y pg_delete(). Ejecución asíncrona de la consulta por estas funciones.
`PGSQL_DML_STRING` (int)
  Pasada a las funciones pg_insert(), pg_select(), pg_update() y pg_delete(). Devuelve la cadena de consulta ejecutada.
`PGSQL_DML_ESCAPE` (int)
  Pasada a las funciones pg_insert(), pg_select(), pg_update() y pg_delete(). Aplica un escape interno a todos los argumentos en lugar de llamar a la función pg_convert(). Esta opción no maneja metadatos. La consulta debe ser tan rápida como con las funciones pg_query() y pg_send_query().
`PGSQL_POLLING_FAILED` (int)
  Retornada por la función pg_connect_poll() para indicar que el intento de conexión ha fallado.
`PGSQL_POLLING_READING` (int)
  Retornada por la función pg_connect_poll() para indicar que la conexión está esperando a que el socket de PostgreSQL esté accesible en lectura.
`PGSQL_POLLING_WRITING` (int)
  Retornada por la función pg_connect_poll() para indicar que la conexión está esperando a que el socket de PostgreSQL esté accesible en escritura.
`PGSQL_POLLING_OK` (int)
  Retornada por la función pg_connect_poll() para indicar que la conexión está lista para ser utilizada.
`PGSQL_POLLING_ACTIVE` (int)
  Retornada por la función pg_connect_poll() para indicar que la conexión está actualmente activa.
`PGSQL_DIAG_SEVERITY_NONLOCALIZED` (int)
  La severidad; los contenidos del campo son ERROR, FATAL, o PANIC (en un mensaje de error), o WARNING, NOTICE, DEBUG, INFO, o LOG (en un mensaje de aviso). Esto es idéntico al campo PG_DIAG_SEVERITY con la excepción de que los contenidos nunca son localizados. Esto está presente solo en las versiones 9.6 y posteriores / PHP 7.3.0 o superior.
`PGSQL_SHOW_CONTEXT_NEVER` (int)
  Para usar con pg_set_error_context_visibility(), el contexto nunca es mostrado. Disponible a partir de PHP 8.3.0.
`PGSQL_SHOW_CONTEXT_ERRORS` (int)
  Para usar con pg_set_error_context_visibility(), los campos del contexto son incluidos únicamente en los mensajes de error. Este es el comportamiento por omisión. Disponible a partir de PHP 8.3.0.
`PGSQL_SHOW_CONTEXT_ALWAYS` (int)
  Para usar con pg_set_error_context_visibility(), los campos del contexto son incluidos en los mensajes de error, avisos y advertencias. Disponible a partir de PHP 8.3.0.
`PGSQL_TRACE_SUPPRESS_TIMESTAMPS` (int)
  Para usar con pg_trace(), la marca de tiempo no es incluida en los mensajes de traza. Disponible a partir de PHP 8.4.20.
`PGSQL_TRACE_REGRESS_MODE` (int)
  Para usar con pg_trace(), campos como los OIDs son incluidos en los mensajes de traza. Disponible a partir de PHP 8.3.0.

# Ejemplos

## Tabla de contenidos

- Uso básico
- Uso básico

## Uso básico

Este simple ejemplo muestra cómo conectarse, ejecutar una consulta y mostrar las líneas resultantes y desconectarse de una base de datos PostgreSQL.

Ejemplo #1 Ejemplo general de la extensión PostgreSQL

    <?php

    // Conexión, selección de la base de datos
    $dbconn = pg_connect("host=localhost dbname=publishing user=www password=foo")
        or die('Conexión imposible : ' . pg_last_error());

    // Ejecución de la consulta SQL
    $query = 'SELECT * FROM authors';
    $result = pg_query($dbconn, $query) or die('Fallo en la consulta : ' . pg_last_error());

    // Mostrar los resultados en HTML
    echo "<table>\n";
    while ($line = pg_fetch_array($result, null, PGSQL_ASSOC)) {
        echo "\t<tr>\n";
        foreach ($line as $col_value) {
            echo "\t\t<td>$col_value</td>\n";
        }
        echo "\t</tr>\n";
    }
    echo "</table>\n";

    // Liberar el resultado
    pg_free_result($result);

    // Cerrar la conexión
    pg_close($dbconn);

    ?>

## Uso básico

Estos ejemplos contienen funciones definidas por el usuario similares a las funciones anteriores de MySQL.

Ejemplo #1 Ejemplo de funciones PostgreSQL definidas por el usuario

    <?php
    // Esta función debería ser necesaria, ya que una conexión PostgreSQL se
    // vincula a una base de datos.
    function pg_list_dbs($db)
    {
        assert(is_resource($db));
        $query = '
    SELECT
     d.datname as "Name",
     u.usename as "Owner",
     pg_encoding_to_char(d.encoding) as "Encoding"
    FROM
     pg_database d LEFT JOIN pg_user u ON d.datdba = u.usesysid
    ORDER BY 1;
    ';
        return pg_query($db, $query);
    }

    // Listar las tablas.
    function pg_list_tables($db)
    {
        assert(is_resource($db));
        $query = "
    SELECT
     c.relname as \"Name\",
     CASE c.relkind WHEN 'r' THEN 'table' WHEN 'v' THEN 'view' WHEN 'i' THEN 'index' WHEN 'S' THEN 'sequence' WHEN 's' THEN 'special' END as \"Type\",
      u.usename as \"Owner\"
    FROM
     pg_class c LEFT JOIN pg_user u ON c.relowner = u.usesysid
    WHERE
     c.relkind IN ('r','v','S','')
     AND c.relname !~ '^pg_'
    ORDER BY 1;
    ";
        return pg_query($db, $query);
    }

    // Ver también pg_meta_data(). Esto devuelve la definición de los campos como array.
    function pg_list_fields($db, $table)
    {
        assert(is_resource($db));
        $query = "
    SELECT
     a.attname,
     format_type(a.atttypid, a.atttypmod),
     a.attnotnull,
     a.atthasdef,
     a.attnum
    FROM
     pg_class c,
     pg_attribute a
    WHERE
     c.relname = '".$table."'
     AND a.attnum > 0 AND a.attrelid = c.oid
    ORDER BY a.attnum;
    ";
        return pg_query($db, $query);
    }
    ?>

# Funciones de PostgreSQL

## Notas

> Nota:

> No todas las funciones son compatibles con todas las versiones. Eso depende de la versión de libpq (librería cliente C de PostgreSQL) y cómo ha sido compilado libpq. Si las extensiones de PHP PostgreSQL faltan, entonces es porque su versión de libpq no los admite.

> Nota:

> La mayoría de las funciones PostgreSQL aceptan `connection` como primer parámetro opcional. Si no está siempre se usa la última conexión abierta. Si esta no existe las funciones retornarán `false`.

> Nota:

> PostgreSQL cambia automáticamente todos los identificadores (ejm. tablas/nombres de columnas) a minúsculas en el momento de la creación y al hacer las consultas. Para forzar el uso de mayúsculas se debe escapar el identificador usando comillas dobles ("").

> Nota:

> PostgresSQL no tiene comandos especiales para mostrar la información del esquema de la base de datos (ejm. todas las tablas de la actual base de datos). En cambio, hay un esquema estándar llamado `information_schema` que contiene las vistas del sistema con toda la información necesaria, es facilmente consultable. Vea la » Documentación de PostgreSQL para más detalles.

# pg_affected_rows

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_affected_rows — Devuelve el número de filas afectadas

### Descripción

function pg_affected_rows(PgSql\Result `$result`): int

pg_affected_rows() devuelve el número de filas afectadas por las consultas de tipo `INSERT`, `UPDATE` y `DELETE`.

El servidor devuelve el número de filas seleccionadas por SELECT.

> Nota:

> Anteriormente, esta función se llamaba pg_cmdtuples().

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).

### Valores devueltos

El número de filas afectadas por la consulta. Si no hay tuplas afectadas, la función devolverá `0`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_affected_rows()

    <?php
    $result = pg_query($conn, "INSERT INTO editeur VALUES ('Auteur')");

    $cmdtuples = pg_affected_rows($result);

    echo $cmdtuples . " filas han sido afectadas.\n";
    ?>

El ejemplo anterior mostrará:

    1 filas han sido afectadas.

### Ver también

- pg_query() - Ejecuta una consulta PostgreSQL
- pg_query_params() - Envía un comando al servidor y espera el resultado, con la capacidad de pasar parámetros por separado del texto SQL de la consulta
- pg_execute() - Ejecuta una consulta preparada de PostgreSQL
- pg_num_rows() - Devuelve el número de filas de PostgreSQL

# pg_cancel_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_cancel_query — Cancela una consulta asíncrona

### Descripción

function pg_cancel_query(PgSql\Connection `$connection`): bool

pg_cancel_query() cancela la consulta asíncrona, iniciada con pg_send_query(), pg_send_query_params() o pg_send_execute(). No es posible cancelar una consulta iniciada con pg_query().

### Parámetros

`connection`
  Una instancia PgSql\Connection.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_cancel_query()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Conexión imposible");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from autores; select count(*) from autores;");
      }

      $res1 = pg_get_result($dbconn);
      echo "Primera llamada a pg_get_result() : $res1\n";
      $rows1 = pg_num_rows($res1);
      echo "$res1 tiene $rows1 registros\n\n";

      // Cancela la consulta en curso de ejecución. Será la segunda consulta
      // que aún funciona.
      pg_cancel_query($dbconn);
    ?>

El ejemplo anterior mostrará:

    Primera llamada a pg_get_result() : Resource id #3
    Resource id #3 tiene 3 registros

### Ver también

- pg_send_query() - Ejecuta una consulta PostgreSQL asíncrona
- pg_connection_busy() - Verifica si la conexión PostgreSQL está ocupada

# pg_change_password

(PHP 8 >= 8.4.0)

pg_change_password — Cambia la contraseña de un usuario de PostgreSQL

### Descripción

function pg_change_password(PgSql\Connection `$connection`, string `$user`, string `$password`): bool

pg_change_password() cambia la contraseña de un usuario de PostgreSQL. Esta función utiliza la función de libpq `PQchangePassword`, que gestiona el cifrado de la contraseña automáticamente según la configuración del servidor.

### Parámetros

`connection`
  Una instancia PgSql\Connection.
`user`
  El nombre del usuario de PostgreSQL cuya contraseña se va a cambiar.
`password`
  La nueva contraseña.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- pg_connect() - Establece una conexión PostgreSQL

# pg_client_encoding

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_client_encoding — Lee la codificación del cliente

### Descripción

function pg_client_encoding(?PgSql\Connection `$connection` = `null`): string

PostgreSQL soporta la conversión automática entre el servidor y el cliente para ciertos juegos de caracteres. pg_client_encoding() devuelve la codificación del cliente. La cadena devuelta será una de las codificaciones estándar de PostgreSQL.

> Nota:

> Si la biblioteca libpq es compilada sin el soporte de codificaciones multibyte, pg_client_encoding() devolverá siempre `SQL_ASCII`. El soporte de codificaciones depende de la versión de PostgreSQL. Consúltese la documentación de PostgreSQL sobre las codificaciones soportadas.

> Anteriormente, esta función se llamaba pg_clientencoding().

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` es `null`, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

### Valores devueltos

La codificación del cliente.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.
8.0.0 | `connection` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con pg_client_encoding()

    <?php
    // Se asume que $conn es una conexión a una base de datos ISO-8859-1
    $encoding = pg_client_encoding($conn);

    echo "La codificación del cliente es: ", $encoding, "\n";
    ?>

El ejemplo anterior mostrará:

    La codificación del cliente es: ISO-8859-1

### Ver también

- pg_set_client_encoding() - Establece la codificación del cliente PostgreSQL

# pg_close

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_close — Finaliza una conexión PostgreSQL

### Descripción

function pg_close(?PgSql\Connection `$connection` = `null`): true

pg_close() cierra la conexión al servidor PostgreSQL asociada a `connection`.

> Nota:

> No es generalmente necesario cerrar una conexión no persistente, ya que estas son cerradas automáticamente al final de un script.

Si existen instancias de PgSql\Lob que han sido abiertas con esta conexión, no se debe cerrar la conexión antes de haber cerrado todas las instancias de PgSql\Lob.

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` es `null`, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.2.0 | El tipo de retorno es ahora `true`, anteriormente era bool.
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.
8.0.0 | `connection` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con pg_close()

    <?php
    $dbconn = pg_connect("host=localhost port=5432 dbname=marie")
          or die("Conexión imposible");
    echo 'Conexión exitosa';
    pg_close($dbconn);
    ?>

El ejemplo anterior mostrará:

    Conexión exitosa

### Ver también

- pg_connect() - Establece una conexión PostgreSQL

# pg_connect

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_connect — Establece una conexión PostgreSQL

### Descripción

function pg_connect(string `$connection_string`, int `$flags` = 0): PgSql\Connection|false

pg_connect() abre una conexión a una base de datos PostgreSQL mediante la cadena de conexión `connection_string`.

Si se realiza una segunda llamada a pg_connect() con los mismos argumentos, no se establecerá una nueva conexión a menos que se pase `PGSQL_CONNECT_FORCE_NEW` a `flags`, pero se devolverá la conexión anterior.

La antigua sintaxis $conn = pg_connect("host", "port", "options", "tty", "dbname") está obsoleta.

### Parámetros

`connection_string`

  La cadena `connection_string` puede estar vacía para utilizar todos los parámetros por omisión o puede contener uno o varios parámetros de configuración separados por espacios. Cada parámetro de configuración tiene la forma `code = valor`. Los espacios alrededor del signo igual son opcionales. Para escribir un valor vacío o un valor que contenga espacios, rodee este valor con comillas simples, por ejemplo: `code = 'un valor'`. Las comillas simples y las barras invertidas dentro del valor deben escapar con una barra invertida, es decir \' y \\.

  Las palabras clave actualmente reconocidas son : `host`, `hostaddr`, `port`, `dbname` (valor por omisión: `user`), `user`, `password`, `connect_timeout`, `options`, `tty` (ignorado), `sslmode`, `requiressl` (obsoleto, utilice `sslmode`) y `service`. La lista de estos argumentos depende de la versión del servidor PostgreSQL.

  El parámetro `options` puede utilizarse para pasar parámetros para la línea de comandos que invoca al servidor.

`flags`

  Si `PGSQL_CONNECT_FORCE_NEW` se pasa como argumento, entonces se creará una nueva conexión, incluso si la cadena `connection_string` es idéntica a la de la conexión existente.

  Si `PGSQL_CONNECT_ASYNC` se proporciona, la conexión se establecerá de forma asíncrona. El estado de la conexión puede verificarse mediante la función pg_connect_poll() o mediante la función pg_connection_status().

### Valores devueltos

Devuelve una instancia de PgSql\Connection en caso de éxito, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Ahora devuelve una instancia de PgSql\Connection ; anteriormente, se devolvía un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_connect()

    <?php
    $dbconn = pg_connect("dbname=marie");
    // conexión a una base de datos llamada "marie"

    $dbconn2 = pg_connect("host=localhost port=5432 dbname=marie");
    // conexión a una base de datos llamada "marie" en el host "localhost" en el puerto "5432"

    $dbconn3 = pg_connect("host=mouton port=5432 dbname=marie user=agneau password=foo");
    // conexión a una base de datos llamada "marie" en el host "mouton" con un
    // nombre de usuario y una contraseña

    $conn_string = "host=mouton port=5432 dbname=test user=agneau password=bar";
    $dbconn4 = pg_connect($conn_string);
    // conexión a una base de datos llamada "test" en el host "mouton" con un
    // nombre de usuario y una contraseña

    $dbconn5 = pg_connect("host=localhost options='--client_encoding=UTF8'");
    //conexión a la base en "localhost" y paso de un parámetro de la línea de
    // comandos relacionado con la codificación UTF-8
    ?>

### Ver también

- pg_pconnect() - Establece una conexión PostgreSQL persistente
- pg_close() - Finaliza una conexión PostgreSQL
- pg_host() - Devuelve el nombre de host
- pg_port() - Devuelve el número de puerto
- pg_tty() - Devuelve el nombre de TTY asociado a la conexión
- pg_options() - Devuelve las opciones de PostgreSQL
- pg_dbname() - Devuelve el nombre de la base de datos PostgreSQL

# pg_connect_poll

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_connect_poll — Prueba el estado de un intento de conexión asíncrona a PostgreSQL en curso

### Descripción

function pg_connect_poll(PgSql\Connection `$connection`): int

La función pg_connect_poll() prueba el estado de una conexión PostgreSQL creada al llamar a la función pg_connect() con la opción `PGSQL_CONNECT_ASYNC`.

### Parámetros

`connection`
  Una instancia PgSql\Connection.

### Valores devueltos

Devuelve la constante `PGSQL_POLLING_FAILED`, `PGSQL_POLLING_READING`, `PGSQL_POLLING_WRITING`, `PGSQL_POLLING_OK`, o la constante `PGSQL_POLLING_ACTIVE`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

# pg_connection_busy

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_busy — Verifica si la conexión PostgreSQL está ocupada

### Descripción

function pg_connection_busy(PgSql\Connection `$connection`): bool

pg_connection_busy() determina si la conexión está ocupada. Si está ocupada, una consulta ya ha sido lanzada y está en curso. Si pg_get_result() es utilizada, será entonces bloqueada.

### Parámetros

`connection`
  Una instancia PgSql\Connection.

### Valores devueltos

Devuelve `true` si la conexión está ocupada, de lo contrario `false`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_connection_busy()

    <?php
     $dbconn = pg_connect("dbname=publisher") or die("Conexión imposible");
     $bs = pg_connection_busy($dbconn);
     if ($bs) {
         echo 'La conexión está ocupada';
     } else {
         echo 'La conexión está libre';
     }
    ?>

### Ver también

- pg_connection_status() - Se lee el estado de la conexión PostgreSQL
- pg_get_result() - Lee un resultado asíncrono de PostgreSQL

# pg_connection_reset

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_reset — Reinicia la conexión al servidor PostgreSQL

### Descripción

function pg_connection_reset(PgSql\Connection `$connection`): bool

pg_connection_reset() realiza una reconexión al servidor, con los mismos parámetros que en la conexión previa con `connection`. Esta función es útil para el manejo de errores.

### Parámetros

`connection`
  Una instancia PgSql\Connection.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_connection_reset()

    <?php
     $dbconn = pg_connect("dbname=publisher") or die ("Conexión imposible");
     $dbconn2 = pg_connection_reset($dbconn);
     if ($dbconn2) {
         echo 'Reinicio exitoso';
     } else {
         echo 'Reinicio fallido';
     }
    ?>

### Ver también

- pg_connect() - Establece una conexión PostgreSQL
- pg_pconnect() - Establece una conexión PostgreSQL persistente
- pg_connection_status() - Se lee el estado de la conexión PostgreSQL

# pg_connection_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_status — Se lee el estado de la conexión PostgreSQL

### Descripción

function pg_connection_status(PgSql\Connection `$connection`): int

pg_connection_status() devuelve el estado de la conexión `connection`.

### Parámetros

`connection`
  Una instancia PgSql\Connection.

### Valores devueltos

`PGSQL_CONNECTION_OK` o `PGSQL_CONNECTION_BAD`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_connection_status()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Conexión imposible");
      $stat = pg_connection_status($dbconn);
      if ($stat === PGSQL_CONNECTION_OK) {
          echo 'Conexión ok';
      } else {
          echo 'Conexión errónea';
      }
    ?>

### Ver también

- pg_connection_busy() - Verifica si la conexión PostgreSQL está ocupada

# pg_consume_input

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_consume_input — Lee la entrada de la conexión

### Descripción

function pg_consume_input(PgSql\Connection `$connection`): bool

La función pg_consume_input() lee todas las entradas pendientes de ser leídas desde el servidor de base de datos.

### Parámetros

`connection`
  Una instancia PgSql\Connection.

### Valores devueltos

`true` en caso de éxito, o `false` si ocurre un error. Tenga en cuenta que `true` no indica necesariamente que la entrada esté pendiente de ser leída.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

# pg_convert

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_convert — Convierte valores de un array asociativo a una forma adecuada para consultas SQL

### Descripción

function pg_convert(
PgSql\Connection `$connection`,
string `$table_name`,
array `$values`,
int `$flags` = 0
): array|false

pg_convert() verifica y convierte el array asociativo `values` en una consulta SQL válida. Para que pg_convert() funcione, debe existir la tabla `table_name`, y debe contener al menos tantas columnas como elementos tenga el array `values`. Los nombres de los campos de `table_name` deben corresponder a los índices del array en `values`. Devuelve un array con los valores convertidos en caso de éxito, y de lo contrario, `false`.

> Nota:

> Los valores booleanos son admitidos y convertidos a booleanos PostgreSQL. Las representaciones de valores booleanos en forma de strings también son soportadas. `null` es convertido a NULL PostgreSQL.

### Parámetros

`connection`
  Una instancia PgSql\Connection.
`table_name`

  Nombre de la tabla para la cual se convertirán los tipos.

`values`

  Datos a ser convertidos.

`flags`

  Un número de `PGSQL_CONV_IGNORE_DEFAULT`, `PGSQL_CONV_FORCE_NULL` o `PGSQL_CONV_IGNORE_NOT_NULL`, combinados.

### Valores devueltos

Un array de valores convertidos, o `false` si ocurre un error.

### Errores/Excepciones

Se lanza una ValueError o TypeError cuando el valor o el tipo del campo no coincide correctamente con un tipo PostgreSQL.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Ahora lanza un error ValueError o TypeError cuando el valor o el tipo del campo no coincide correctamente con un tipo PostgreSQL; previamente, se emitía un `E_WARNING`.
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_convert()

    <?php
      $dbconn = pg_connect('dbname=foo');

      $tmp = array(
          'auteur' => 'Joe Thackery',
          'annee' => 2005,
          'titre' => 'Ma Vie, par Joe Thackery'
      );

      $vals = pg_convert($dbconn, 'auteurs', $tmp);
    ?>

### Ver también

- pg_meta_data() - Lee los metadatos de la tabla PostgreSQL
- pg_insert() - Inserta un array en una tabla
- pg_select() - Realiza una selección PostgreSQL
- pg_update() - Modifica las líneas de una tabla
- pg_delete() - Elimina filas de PostgreSQL

# pg_copy_from

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_copy_from — Inserta filas en una tabla a partir de un array

### Descripción

function pg_copy_from(
PgSql\Connection `$connection`,
string `$table_name`,
array|Traversable `$rows`,
string `$separator` = "\t",
string `$null_as` = "\\\\N"
): bool

pg_copy_from() inserta los elementos del array `rows` en una tabla. Esta función utiliza la orden SQL interna `COPY FROM`.

### Parámetros

`connection`
  Una instancia PgSql\Connection.
`table_name`

  Nombre de la tabla en la que `rows` será copiado.

`rows`

  Datos iterable a ser copiados dentro de `table_name`. Cada valor en `rows` se convierte en una fila en `table_name`. Cada valor en `rows` debería ser una cadena delimitada por valores a insertar dentro de cada campo. Los valores deben terminar con un salto de línea.

`separator`

  El marcador que separa los valores para cada campo en cada elemento de `rows`. Por omisión `\t`.

`null_as`

  Cómo se representan los valores `NULL` de SQL en `rows`. Por omisión `\\N` (`"\\\\N"`).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | `rows` es ahora de tipo iterable. Anteriormente, era de tipo array.
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_copy_from()

    <?php
       $db = pg_connect("dbname=publisher") or die("Conexión imposible");

       $rows = pg_copy_to($db, $table_name);

       pg_query($db, "DELETE FROM $table_name");

       pg_copy_from($db, $table_name, $rows);
    ?>

### Ver también

- pg_copy_to() - Copia una tabla en un array

# pg_copy_to

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_copy_to — Copia una tabla en un array

### Descripción

function pg_copy_to(
PgSql\Connection `$connection`,
string `$table_name`,
string `$separator` = "\t",
string `$null_as` = "\\\\N"
): array|false

pg_copy_to() copia la tabla `table_name` en un array. Esta función utiliza el comando interno SQL `COPY TO` para insertar los arrays.

### Parámetros

`connection`
  Una instancia PgSql\Connection.
`table_name`

  Nombre de la tabla a partir de la cual los datos en `rows` serán copiados.

`separator`

  El marcador que separa los valores para cada campo en cada elemento de `rows`. Por omisión `\t`.

`null_as`

  Cómo las valores `NULL` de SQL son representados en `rows`. Por omisión `\\N` (`"\\\\N"`).

### Valores devueltos

Un array con un elemento para cada línea de datos `COPY`, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_copy_to()

    <?php
       $db = pg_connect("dbname=publisher") or die("Conexión imposible");

       $rows = pg_copy_to($db, $table_name);

       pg_query($db, "DELETE FROM $table_name");

       pg_copy_from($db, $table_name, $rows);
    ?>

### Ver también

- pg_copy_from() - Inserta filas en una tabla a partir de un array

# pg_dbname

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_dbname — Devuelve el nombre de la base de datos PostgreSQL

### Descripción

function pg_dbname(?PgSql\Connection `$connection` = `null`): string

pg_dbname() devuelve el nombre de la base de datos PostgreSQL asociada a la conexión `connection`.

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` es `null`, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

### Valores devueltos

Una cadena de tipo string que contiene el nombre de la base de datos asociada a la conexión `connection`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.
8.0.0 | `connection` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con pg_dbname()

    <?php
     error_reporting(E_ALL);

     pg_connect ("host=localhost port=5432 dbname=marie");
     echo pg_dbname(); // muestra marie
    ?>

# pg_delete

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_delete — Elimina filas de PostgreSQL

### Descripción

function pg_delete(
PgSql\Connection `$connection`,
string `$table_name`,
array `$conditions`,
int `$flags` = `PGSQL_DML_EXEC`
): string|bool

pg_delete() elimina las filas de una tabla especificadas por las claves y valores del array asociativo `conditions`.

Si `flags` es proporcionado, pg_convert() es aplicado a `conditions` con los flags proporcionados.

Por omisión pg_delete() pasa valores sin tratar. Los valores deben ser escapados o el flag `PGSQL_DML_ESCAPE` debe ser especificado en `flags`. `PGSQL_DML_ESCAPE` añade comillas y escapa los parámetros/identificadores. Por lo tanto, los nombres de tablas/columnas se vuelven sensibles a mayúsculas/minúsculas.

Tenga en cuenta que ni el escape ni las consultas preparadas pueden proteger consultas LIKE, JSON, arrays, Regex, etc. Estos parámetros deben ser tratados según su contexto. Es decir, escapar/validar los valores.

### Parámetros

`connection`
  Una instancia PgSql\Connection.
`table_name`

  Nombre de la tabla desde la cual las filas serán eliminadas.

`conditions`

  Un array donde las claves son los nombres de los campos de la tabla `table_name` y donde los valores son los valores de estos campos que deben ser eliminados.

`flags`

  Cualquier combinación de los siguientes valores: `PGSQL_CONV_FORCE_NULL`, `PGSQL_DML_NO_CONV`, `PGSQL_DML_ESCAPE`, `PGSQL_DML_EXEC`, `PGSQL_DML_ASYNC` o `PGSQL_DML_STRING`. Si `PGSQL_DML_STRING` forma parte del parámetro `flags` entonces, la consulta será devuelta. Cuando la constante `PGSQL_DML_NO_CONV` o la constante `PGSQL_DML_ESCAPE` están definidas, ninguna llamada a la función pg_convert() será realizada internamente.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error. Devuelve un string si `PGSQL_DML_STRING` es pasado en el parámetro `flags`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_delete()

    <?php
     $db = pg_connect ('dbname=foo');
    // Esto es seguro en cierta medida, ya que todos los valores son escapados
    // Sin embargo PostgreSSQL soporta JSON/arrays. Estos no son
    // seguros ni por escape ni por consultas preparadas.
     $res = pg_delete($db, 'post_log', $_POST, PG_DML_ESCAPE);
     if ($res) {
         echo "Los datos POST han sido eliminados: $res\n";
     } else {
         echo "Los datos de entrada son incorrectos.\n";
     }
    ?>

### Ver también

- pg_convert() - Convierte valores de un array asociativo a una forma adecuada para consultas SQL

# pg_end_copy

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_end_copy — Sincroniza con el servidor PostgreSQL

### Descripción

function pg_end_copy(?PgSql\Connection `$connection` = `null`): bool

pg_end_copy() sincroniza el cliente PostgreSQL (normalmente un proceso del servidor web) con el servidor PostgreSQL, después de una operación de copia realizada por pg_put_line(). pg_end_copy() debe ser utilizado, de lo contrario el servidor PostgreSQL no estará sincronizado con el cliente y emitirá un error.

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` es `null`, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.
8.0.0 | `connection` es ahora nullable.

### Ejemplos

Ejemplo #1 Ejemplo con pg_end_copy()

    <?php
      $conn = pg_pconnect("dbname=foo");
      pg_query($conn, "create table bar (a int4, b char(16), d float8)");
      pg_query($conn, "copy bar from stdin");
      pg_put_line($conn, "3\tHola mundo\t4.5\n");
      pg_put_line($conn, "4\tAdiós mundo\t7.11\n");
      pg_put_line($conn, "\\.\n");
      pg_end_copy($conn);
    ?>

### Ver también

- pg_put_line() - Envía una string al servidor PostgreSQL

# pg_escape_bytea

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_escape_bytea — Protege una cadena para insertarla en un campo bytea

### Descripción

function pg_escape_bytea(PgSql\Connection `$connection` = ?, string `$string`): string

pg_escape_bytea() protege los caracteres de la cadena `string` con el modo bytea. La cadena protegida es devuelta.

> Nota:

> Cuando se utiliza una orden `SELECT` con datos de tipo bytea, PostgreSQL devuelve valores octales, prefijados con backslashs '\' (por ejemplo \032). Los usuarios deben realizar la conversión al formato binario manualmente.

> pg_escape_bytea() requiere PostgreSQL 7.2 o más reciente. Con PostgreSQL 7.2.0 y 7.2.1, los datos bytea deben ser transtipados cuando se activa el soporte de strings multioctetos. Es decir, `INSERT INTO test_table (image) VALUES ('$image_escaped'::bytea);`. PostgreSQL 7.2.2 o más reciente no requiere esta manipulación. Sin embargo, si el cliente y el servidor no utilizan el mismo juego de caracteres, pueden ocurrir errores. Entonces, se debe forzar el transtipado manualmente.

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` no es especificado, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

`string`

  Una string que contiene texto o datos binarios que serán insertados en la columna bytea.

### Valores devueltos

Una string que contiene los datos escapados.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_escape_bytea()

    <?php
    // Conexión a la base de datos
    $dbconn = pg_connect('dbname=foo');

    // Lectura de un fichero binario
    $data = file_get_contents('image1.jpg');

    // Escapado de los datos binarios
    $escaped = pg_escape_bytea($data);

    // Inserción en la base de datos
    pg_query("INSERT INTO gallery (name, data) VALUES ('Pine trees', '{$escaped}')");
    ?>

### Ver también

- pg_unescape_bytea() - Elimina la protección de una cadena de tipo bytea
- pg_escape_string() - Protege un string para una consulta SQL

# pg_escape_identifier

(PHP 5 >= 5.4.4, PHP 7, PHP 8)

pg_escape_identifier — Protege un identificador para su inserción en un campo de texto.

### Descripción

function pg_escape_identifier(PgSql\Connection `$connection` = ?, string `$string`): string|false

pg_escape_identifier() protege un identificador (ejemplo: tabla, nombre de campo) para una consulta en la base de datos. El resultado es una cadena de caracteres protegida para PostgreSQL. pg_escape_identifier() añade comillas antes y después de los datos. Los usuarios no deben, por lo tanto, añadir comillas. Se recomienda el uso de esta función para los identificadores de las consultas. Para los datos SQL sin tratar (es decir, los parámetros, excepto de tipo bytea), pg_escape_literal() o pg_escape_string() debe ser utilizado. Para los campos de tipo bytea es necesario utilizar pg_escape_bytea().

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` no es especificado, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

`string`

  Una string que contiene texto a proteger.

### Valores devueltos

Una string que contiene los datos protegidos, o `false` en caso de fallo.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_escape_identifier()

    <?php
      // Conexión a la base de datos
      $dbconn = pg_connect('dbname=foo');

      // Protección del nombre de la tabla
      $escaped = pg_escape_identifier($table_name);

      // Selección de las filas de la tabla $table_name
      pg_query("SELECT * FROM {$escaped};");
    ?>

### Ver también

- pg_escape_literal() - Protege una consulta SQL literal para insertar en un campo de texto
- pg_escape_bytea() - Protege una cadena para insertarla en un campo bytea
- pg_escape_string() - Protege un string para una consulta SQL

# pg_escape_literal

(PHP 5 >= 5.4.4, PHP 7, PHP 8)

pg_escape_literal — Protege una consulta SQL literal para insertar en un campo de texto

### Descripción

function pg_escape_literal(PgSql\Connection `$connection` = ?, string `$string`): string|false

pg_escape_literal() protege una consulta SQL literal para su ejecución en la base de datos PostgreSQL. El resultado devuelto es un string protegido en formato PostgreSQL. pg_escape_literal() añade comillas simples antes y después de los datos. Los usuarios no deben, por tanto, añadir comillas simples. Se recomienda el uso de esta función en lugar de pg_escape_string(). Si la columna es de tipo bytea, se debe utilizar en su lugar la función pg_escape_bytea(). Para proteger los identificadores (por ejemplo, nombres de tabla, nombres de campos), se debe utilizar la función pg_escape_identifier().

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` no es especificado, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

`string`

  Un string que contiene texto a proteger.

### Valores devueltos

Una string que contiene los datos protegidos, o `false` en caso de fallo.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_escape_literal()

    <?php
      // Conexión a la base de datos
      $dbconn = pg_connect('dbname=foo');

      // Lectura de un fichero (que contiene apóstrofes y barras invertidas)
      $data = file_get_contents('letter.txt');

      // Protección de los datos
      $escaped = pg_escape_literal($data);

      // Inserción en la base de datos. Observe que no hay comillas simples alrededor de {$escaped}
      pg_query("INSERT INTO correspondence (name, data) VALUES ('My letter', {$escaped})");
    ?>

### Ver también

- pg_escape_identifier() - Protege un identificador para su inserción en un campo de texto.
- pg_escape_bytea() - Protege una cadena para insertarla en un campo bytea
- pg_escape_string() - Protege un string para una consulta SQL

# pg_escape_string

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_escape_string — Protege un string para una consulta SQL

### Descripción

function pg_escape_string(PgSql\Connection `$connection` = ?, string `$string`): string

pg_escape_string() protege un string para insertarlo en la base de datos. Devuelve el string protegido en formato PostgreSQL. Se recomienda el uso de esta función en lugar de addslashes(). Si el tipo de la columna es bytea, pg_escape_bytea() debe ser utilizada en su lugar. La función pg_escape_identifier() debe ser utilizada para escapar identificadores (es decir, nombres de tablas, nombres de campos).

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` no es especificado, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

`string`

  Un string que contiene el texto a escapar.

### Valores devueltos

Un string que contiene los datos escapados.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_escape_string()

    <?php
    // Conexión a la base de datos
    $dbconn = pg_connect('dbname=foo');

    // Lectura de un fichero de texto (que contiene apóstrofes y barras invertidas)
    $data = file_get_contents('letter.txt');

    // Protección de los datos
    $escaped = pg_escape_string($data);

    // Inserción en la base de datos
    pg_query("INSERT INTO correspondence (name, data) VALUES ('Mi carta', '{$escaped}')");
    ?>

### Ver también

- pg_escape_bytea() - Protege una cadena para insertarla en un campo bytea

# pg_execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_execute — Ejecuta una consulta preparada de PostgreSQL

### Descripción

function pg_execute(PgSql\Connection `$connection` = ?, string `$statement_name`, array `$params`): PgSql\Result|false

Envía una consulta para ejecutar una consulta preparada con los argumentos dados y espera el resultado.

pg_execute() es similar a pg_query_params(), pero la consulta que será ejecutada se especifica nombrando una consulta previamente preparada, en lugar de proporcionar una cadena como consulta. Esta característica permite que las consultas que serán utilizadas repetidamente sean analizadas y planificadas una sola vez, en lugar de ser ejecutadas cada vez. La consulta debe haber sido previamente preparada en la sesión actual.

Los argumentos son idénticos a la función pg_query_params() excepto por el nombre de la consulta preparada que se proporciona en lugar de la consulta en forma de cadena.

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` no es especificado, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

`statement_name`

  El nombre de la consulta preparada a ejecutar. Si se especifica una cadena vacía (""), entonces se ejecuta la consulta sin nombre. El nombre debe haber sido previamente preparado utilizando pg_prepare(), pg_send_prepare() o una orden SQL `PREPARE`.

`params`

  Un array de valores de argumentos para sustituir las variables $1, $2, etc. en la consulta preparada original. El número de elementos presentes en el array debe coincidir con el número de variables a reemplazar.

  Advertencia

  Los elementos son convertidos en strings al llamar a esta función.

### Valores devueltos

Una instancia de PgSql\Result en caso de éxito, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Ahora devuelve una instancia de PgSql\Result ; anteriormente, se devolvía un resource.
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_execute()

    <?php
    // Conexión a una base de datos llamada "marie"
    $dbconn = pg_connect("dbname=marie");

    // Prepara una consulta para su ejecución
    $result = pg_prepare($dbconn, "my_query", 'SELECT * FROM magasins WHERE nom = $1');

    // Ejecuta la consulta preparada. Observe que no es necesario escapar
    // la cadena "Joe's Widgets"
    $result = pg_execute($dbconn, "my_query", array("Joe's Widgets"));

    // Ejecuta la misma consulta preparada, esta vez con un argumento diferente
    $result = pg_execute($dbconn, "my_query", array("Vêtements Vêtements Vêtements"));

    ?>

### Ver también

- pg_prepare() - Envía una solicitud al servidor para crear una sentencia preparada con los parámetros dados y espera la ejecución
- pg_send_prepare() - Envía una solicitud para crear una consulta preparada con los argumentos dados, sin esperar el final de su ejecución
- pg_query_params() - Envía un comando al servidor y espera el resultado, con la capacidad de pasar parámetros por separado del texto SQL de la consulta

# pg_fetch_all

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_fetch_all — Lee todas las líneas de un resultado

### Descripción

function pg_fetch_all(PgSql\Result `$result`, int `$mode` = `PGSQL_ASSOC`): array

pg_fetch_all() devuelve un array que contiene todas las filas (registros) de la instancia de PgSql\Result.

> Nota: Esta función define los campos NULL al valor PHP `null`.

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).
`mode`
  Un parámetro opcional que controla cómo el array devuelto es indexado. `mode` es una constante que puede tomar los siguientes valores: `PGSQL_ASSOC`, `PGSQL_NUM` y `PGSQL_BOTH`. Usando `PGSQL_NUM`, la función devolverá un array con índices numéricos, usando `PGSQL_ASSOC`, devolverá solo índices asociativos mientras que `PGSQL_BOTH` devolverá ambos índices numéricos y asociativos.

### Valores devueltos

Un array array de todas las líneas en el conjunto de resultados. Cada línea es un array de valores de los campos indexado por el nombre de los campos.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.
8.0.0 | pg_fetch_all() devolverá ahora un array vacío en lugar de `false` para los conjuntos de resultados con cero líneas.
7.1.0 | Se ha añadido el argumento `mode`.

### Ejemplos

Ejemplo #1 Ejemplo con pg_fetch_all()

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Se ha producido un error.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT * FROM autores");
    if (!$result) {
      echo "Se ha producido un error.\n";
      exit;
    }

    $arr = pg_fetch_all($result);

    print_r($arr);

    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [id] => 1
                [name] => Fred
            )

        [1] => Array
            (
                [id] => 2
                [name] => Bob
            )

    )

### Ver también

- pg_fetch_row() - Lee una fila en un array
- pg_fetch_array() - Lee una línea de resultado PostgreSQL en un array
- pg_fetch_object() - Lee una fila de resultado PostgreSQL en un objeto
- pg_fetch_result() - Devuelve los valores de un resultado

# pg_fetch_all_columns

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_fetch_all_columns — Recupera todas las filas de una columna particular de resultados como un array

### Descripción

function pg_fetch_all_columns(PgSql\Result `$result`, int `$field` = 0): array

pg_fetch_all_columns() devuelve un array que contiene todas las filas (registros) de una columna particular de una instancia de PgSql\Result.

> Nota: Esta función define los campos NULL al valor PHP `null`.

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).
`field`

  Número de la columna. Por omisión, la primera columna si no se especifica.

### Valores devueltos

Un array que contiene todos los valores de una columna del resultado.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_fetch_all_columns()

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Se ha producido un error.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT title, name, address FROM authors");
    if (!$result) {
      echo "Se ha producido un error.\n";
      exit;
    }

    // Recupera un array que contiene todos los nombres de autores
    $arr = pg_fetch_all_columns($result, 1);

    var_dump($arr);

    ?>

### Ver también

- pg_fetch_all() - Lee todas las líneas de un resultado

# pg_fetch_array

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_array — Lee una línea de resultado PostgreSQL en un array

### Descripción

function pg_fetch_array(PgSql\Result `$result`, ?int `$row` = `null`, int `$mode` = `PGSQL_BOTH`): array|false

pg_fetch_array() devuelve un array que contiene la línea solicitada.

pg_fetch_array() es una versión mejorada de pg_fetch_row(). Además de proporcionar un array con índice numérico, también puede almacenar los datos en un array asociativo, utilizando los nombres de los campos como claves. Estas dos funciones utilizan el array asociativo por omisión.

> Nota: Esta función define los campos NULL al valor PHP `null`.

pg_fetch_array() no es significativamente más lenta que pg_fetch_row() y aporta una comodidad de uso apreciable.

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).
`row`

  Número de la línea a recuperar. Las líneas están numeradas comenzando por 0. Si el argumento es omitido o si vale `null`, se recupera la línea siguiente.

`mode`
  Un parámetro opcional que controla cómo el array devuelto es indexado. `mode` es una constante que puede tomar los siguientes valores: `PGSQL_ASSOC`, `PGSQL_NUM` y `PGSQL_BOTH`. Usando `PGSQL_NUM`, la función devolverá un array con índices numéricos, usando `PGSQL_ASSOC`, devolverá solo índices asociativos mientras que `PGSQL_BOTH` devolverá ambos índices numéricos y asociativos.

### Valores devueltos

Un array con índice numérico (comenzando por 0), asociativo (indexado con el nombre de los campos) o ambos. Cada valor en el array está representado como un string. Los valores `null` de la base de datos son devueltos como `null`.

`false` es devuelto si `row` excede el número de líneas en el conjunto de resultados, no hay más líneas disponibles o cualquier otro error. Intentar recuperar el resultado de una consulta que no sea SELECT también devolverá `false`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_fetch_array()

    <?php

    $conn = pg_pconnect ("dbname=publisher");
    if (!$conn) {
      echo "Error de conexión.\n";
      exit;
    }

    $result = pg_query ($conn, "SELECT autor, email FROM autores");
    if (!$result) {
      echo "Error durante la consulta.\n";
      exit;
    }

    $arr = pg_fetch_array ($result, 0, PGSQL_NUM);
    echo $arr[0] . " <- Línea 1 Autor\n";
    echo $arr[1] . " <- Línea 1 Correo electrónico\n";

    // El parámetro row es opcional; NULL puede ser pasado en su lugar,
    // para pasar un modo. Las llamadas sucesivas a pg_fetch_array
    // devolverán la línea siguiente.
    $arr = pg_fetch_array($result, NULL, PGSQL_ASSOC);
    echo $arr["autor"] . " <- Línea 2 Autor\n";
    echo $arr["email"] . " <- Línea 2 Correo electrónico\n";

    $arr = pg_fetch_array($result);
    echo $arr["autor"] . " <- Línea 3 Autor\n";
    echo $arr[1] . " <- Línea 3 Correo electrónico\n";

    ?>

### Ver también

- pg_fetch_row() - Lee una fila en un array
- pg_fetch_object() - Lee una fila de resultado PostgreSQL en un objeto
- pg_fetch_result() - Devuelve los valores de un resultado

# pg_fetch_assoc

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_fetch_assoc — Lee una fila de resultado PostgreSQL como un array asociativo

### Descripción

function pg_fetch_assoc(PgSql\Result `$result`, ?int `$row` = `null`): array|false

pg_fetch_assoc() devuelve un array asociativo que contiene la fila actual en el resultado `result`.

pg_fetch_assoc() es equivalente a llamar pg_fetch_row() con `PGSQL_ASSOC` como tercer argumento (que es opcional). Esto devolverá solo un array asociativo. Si se necesitan índices numéricos, se debe utilizar pg_fetch_row().

> Nota: Esta función define los campos NULL al valor PHP `null`.

pg_fetch_assoc() no es significativamente más lenta que pg_fetch_row() y aporta una comodidad de uso apreciable.

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).
`row`

  Número de la fila a recuperar. Las filas están numeradas comenzando desde 0. Si el argumento es omitido o si es `null`, la siguiente fila es recuperada.

### Valores devueltos

Un array con índice asociativo (por nombre de campo). Cada valor en el array es representado como un string. Los valores `null` de la base de datos son devueltos `null`.

`false` es devuelto si `row` excede el número de filas en el conjunto de resultados, no hay más filas disponibles o cualquier otro error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_fetch_assoc()

    <?php
    $conn = pg_pconnect ("dbname=publisher");
    if (!$conn) {
      echo "Ha ocurrido un error.\n";
      exit;
    }

    $result = pg_query ($conn, "SELECT id, autor, email FROM autores");
    if (!$result) {
      echo "Ha ocurrido un error.\n";
      exit;
    }

    while ($row = pg_fetch_assoc($result)) {
      echo $row['id'];
      echo $row['autor'];
      echo $row['email'];
    }
    ?>

### Ver también

- pg_fetch_row() - Lee una fila en un array
- pg_fetch_array() - Lee una línea de resultado PostgreSQL en un array
- pg_fetch_object() - Lee una fila de resultado PostgreSQL en un objeto
- pg_fetch_result() - Devuelve los valores de un resultado

# pg_fetch_object

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_object — Lee una fila de resultado PostgreSQL en un objeto

### Descripción

function pg_fetch_object(
PgSql\Result `$result`,
?int `$row` = `null`,
string `$class` = "stdClass",
array `$constructor_args` = []
): object|false

pg_fetch_object() devuelve un objeto con sus propiedades que corresponden a los nombres de los campos de la fila. La función puede instanciar opcionalmente un objeto de una clase específica y pasar los argumentos al constructor de dicha clase.

> Nota: Esta función define los campos NULL al valor PHP `null`.

En cuanto a velocidad, la función es idéntica a pg_fetch_array() y es casi tan rápida como pg_fetch_row() (la diferencia es insignificante).

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).
`row`

  Número de la fila a recuperar. Las filas se numeran comenzando por 0. Si el argumento se omite o es `null`, se recupera la siguiente fila.

`class`

  El nombre de la clase a instanciar, fija las propiedades de esta y sus valores de retorno. Si no se especifica nada, se devuelve un objeto de tipo stdClass.

`constructor_args`

  Parámetro opcional de tipo array para pasar argumentos al constructor de la clase `class`.

### Valores devueltos

Un objeto de tipo object con los atributos para cada campo en el conjunto de resultados. Los valores `null` de la base de datos se devuelven como `null`.

`false` se devuelve si `row` excede el número de filas en el conjunto de resultados, no hay más filas disponibles o cualquier otro error.

### Errores/Excepciones

Se lanza una ValueError cuando el argumento `constructor_args` no está vacío y la clase no tiene constructor.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Ahora lanza una excepción ValueError cuando el argumento `constructor_args` no está vacío y la clase no tiene constructor; anteriormente, se lanzaba una excepción Exception.
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_fetch_object()

    <?php

    $database = 'store';

    $db_conn = pg_connect("host=localhost port=5432 dbname=$database");
    if (!$db_conn) {
      echo "La conexión a la base $database ha fallado\n";
      exit;
    }

    $qu = pg_query($db_conn, "SELECT * FROM libros ORDER BY autor");

    while ($data = pg_fetch_object($qu)) {
      echo $data->autor . " (";
      echo $data->anio . "): ";
      echo $data->titulo . "<br />";
    }

    pg_free_result($qu);
    pg_close($db_conn);

    ?>

### Ver también

- pg_query() - Ejecuta una consulta PostgreSQL
- pg_fetch_array() - Lee una línea de resultado PostgreSQL en un array
- pg_fetch_assoc() - Lee una fila de resultado PostgreSQL como un array asociativo
- pg_fetch_row() - Lee una fila en un array
- pg_fetch_result() - Devuelve los valores de un resultado

# pg_fetch_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_fetch_result — Devuelve los valores de un resultado

### Descripción

function pg_fetch_result(PgSql\Result `$result`, string|false|null `$row` , mixed `$field`): string|false|null
function pg_fetch_result(PgSql\Result `$result`, mixed `$field`): string|false|null

pg_fetch_result() devuelve el valor de una fila y un campo (columna) en particular a partir de una instancia PgSql\Result.

> Nota:

> Esta función puede llamarse pg_result().

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).
`row`

  Número de la fila a recuperar. Las filas están numeradas a partir de 0. Si el argumento es omitido, se recupera la siguiente fila.

`field`

  Una cadena de tipo string que representa el nombre del campo (columna) a recuperar, o un entero de tipo int que representa el número del campo a recuperar. Los campos están numerados a partir de 0.

### Valores devueltos

Los valores booleanos son devueltos como "t" o "f". Todos los otros tipos, incluyendo los arrays, son devueltos como cadenas formateadas, de la misma manera que PostgreSQL los mostraría en el cliente psql. Los valores NULL de la base de datos son devueltos como NULL.

`false` es devuelto si `row` excede el número de filas en el conjunto de resultados, no hay más filas disponibles o cualquier otro error.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | `row` ahora puede ser nullable.
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_fetch_result()

    <?php
    $db = pg_connect("dbname=users user=me");

    $res = pg_query($db, "SELECT 1 UNION ALL SELECT 2");

    $val = pg_fetch_result($res, 1, 0);

    echo "El primer campo en la segunda fila es: ", $val, "\n";
    ?>

El ejemplo anterior mostrará:

    El primer campo en la segunda fila es: 2

### Ver también

- pg_query() - Ejecuta una consulta PostgreSQL
- pg_fetch_array() - Lee una línea de resultado PostgreSQL en un array

# pg_fetch_row

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_row — Lee una fila en un array

### Descripción

function pg_fetch_row(PgSql\Result `$result`, ?int `$row` = `null`, int `$mode` = `PGSQL_NUM`): array|false

pg_fetch_row() lee una fila en el resultado asociado a la instancia `result`.

> Nota: Esta función define los campos NULL al valor PHP `null`.

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).
`row`

  Número de la fila a recuperar. Las filas están numeradas comenzando en 0. Si el argumento es omitido o si vale `null`, la siguiente fila es recuperada.

`mode`
  Un parámetro opcional que controla cómo el array devuelto es indexado. `mode` es una constante que puede tomar los siguientes valores: `PGSQL_ASSOC`, `PGSQL_NUM` y `PGSQL_BOTH`. Usando `PGSQL_NUM`, la función devolverá un array con índices numéricos, usando `PGSQL_ASSOC`, devolverá solo índices asociativos mientras que `PGSQL_BOTH` devolverá ambos índices numéricos y asociativos.

### Valores devueltos

Un array, indexado desde 0, con cada valor representado como un string. Los valores `null` de la base de datos son retornados como `null`.

`false` es retornado si `row` excede el número de filas en el conjunto de resultados, no tiene más filas disponibles o cualquier otro error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_fetch_row()

    <?php

    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Ha ocurrido un error.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT autor, email FROM autores");
    if (!$result) {
      echo "Ha ocurrido un error.\n";
      exit;
    }

    while ($row = pg_fetch_row($result)) {
      echo "Autor: $row[0]  E-mail: $row[1]";
      echo "<br />\n";
    }

    ?>

### Ver también

- pg_query() - Ejecuta una consulta PostgreSQL
- pg_fetch_array() - Lee una línea de resultado PostgreSQL en un array
- pg_fetch_object() - Lee una fila de resultado PostgreSQL en un objeto
- pg_fetch_result() - Devuelve los valores de un resultado

# pg_field_is_null

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_is_null — Comprueba si un campo PostgreSQL es `null`

### Descripción

function pg_field_is_null(PgSql\Result `$result`, string|false|null `$row` , mixed `$field`): int
function pg_field_is_null(PgSql\Result `$result`, mixed `$field`): int

pg_field_is_null() comprueba si un campo en una instancia PgSql\Result es un `NULL` SQL o no.

> Nota:

> Anteriormente, esta función se llamaba pg_fieldisnull().

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).
`row`

  Número de la fila a recuperar. Las filas están numeradas a partir de 0. Si el argumento es omitido, se recupera la fila siguiente.

`field`

  Número del campo (comenzando en 0) de tipo int o el nombre del campo de tipo string.

### Valores devueltos

Retorna `1` si el campo de la fila dada es `null`, `0` si no es `null`. `false` es retornado si la fila no está en el array o cualquier otro error.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | `row` es ahora nullable.
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_field_is_null()

    <?php
        $dbconn = pg_connect("dbname=publisher") or die ("Conexión imposible");
        $res = pg_query($dbconn, "select * from autores where autor = 'Orwell'");
        if ($res) {
            if (pg_field_is_null($res, 0, "año") == 1) {
                echo "El valor del campo \"año\" es null.\n";
            }
            if (pg_field_is_null($res, 0, "año") == 0) {
                echo "El valor del campo \"año\" no es null.\n";
            }
        }
    ?>

# pg_field_name

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_name — Devuelve el nombre de un campo PostgreSQL

### Descripción

function pg_field_name(PgSql\Result `$result`, int `$field`): string

pg_field_name() devuelve el nombre del campo que ocupa la columna número `field` en el resultado `result`. La numeración de los campos comienza en 0.

> Nota:

> Anteriormente, esta función se llamaba pg_fieldname().

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).
`field`

  Número del campo, comenzando en 0.

### Valores devueltos

El nombre del campo.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Obtención de información de los campos

    <?php
     $dbconn = pg_connect("dbname=publisher") or die("Conexión imposible");

     $res = pg_query($dbconn, "select * from autores where autor = 'Orwell'");
     $i = pg_num_fields($res);
     for ($j = 0; $j < $i; $j++) {
         echo "columna $j\n";
         $fieldname = pg_field_name($res, $j);
         echo "Campo: $fieldname\n";
         echo "Tamaño mostrado: ".pg_field_prtlen($res, $fieldname)." caracteres\n";
         echo "Tamaño de almacenamiento: ".pg_field_size($res, $j)." bytes\n";
         echo "Tipo de campo: ".pg_field_type($res, $j)." \n\n";
     }
    ?>

El ejemplo anterior mostrará:

    columna 0
    Campo: autor
    Tamaño mostrado: 6 caracteres
    Tamaño de almacenamiento: -1 bytes
    Tipo de campo: varchar

    columna 1
    Campo: año
    Tamaño mostrado: 4 caracteres
    Tamaño de almacenamiento: 2 bytes
    Tipo de campo: int2

    columna 2
    Campo: título
    Tamaño mostrado: 24 caracteres
    Tamaño de almacenamiento: -1 bytes
    Tipo de campo: varchar

### Ver también

- pg_field_num() - Devuelve el número de una columna

# pg_field_num

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_num — Devuelve el número de una columna

### Descripción

function pg_field_num(PgSql\Result `$result`, string `$field`): int

pg_field_num() devuelve el número de la columna, cuyo nombre es `field`, en el resultado `result`.

> Nota:

> Anteriormente, esta función se llamaba pg_fieldnum().

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).
`field`

  El nombre del campo. El nombre dado es tratado como un identificador en un comando SQL, es decir, que se convierte a minúsculas a menos que esté citado dos veces.

### Valores devueltos

El número del campo (comenzando en 0) o -1 en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Obtención de información de los campos

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Conexión imposible");

      $res = pg_query($dbconn, "select autor, año, título from autores where autor = 'Orwell'");

      echo "El número de la columna 'título' es: ", pg_field_num($res, 'título');
    ?>

El ejemplo anterior mostrará:

    El número de la columna 'título' es: 2

### Ver también

- pg_field_name() - Devuelve el nombre de un campo PostgreSQL

# pg_field_prtlen

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_prtlen — Devuelve el tamaño de impresión

### Descripción

function pg_field_prtlen(PgSql\Result `$result`, string|false|null `$row` , mixed `$field_name_or_number`): int
function pg_field_prtlen(PgSql\Result `$result`, mixed `$field_name_or_number`): int

pg_field_prtlen() devuelve el tamaño de impresión (número de caracteres) de un valor dado en un resultado PostgreSQL. La numeración de las líneas comienza en 0. pg_field_prtlen() devuelve `false` en caso de error.

El parámetro `field_name_or_number` puede ser pasado ya sea como int o como string. Si es pasado como int, PHP lo identifica como el número de un campo, de lo contrario, como el nombre de un campo.

Ver el ejemplo dado en la página de la documentación de la función pg_field_name().

> Nota:

> Anteriormente, esta función se llamaba pg_fieldprtlen().

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).
`row`

  Número de la línea en el resultado. Las líneas están numeradas a partir de 0 en adelante. Si este parámetro no es proporcionado, la línea en curso es recuperada.

### Valores devueltos

El número de caracteres impresos.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | `row` es ahora nullable.
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Recuperación de información acerca de los campos

    <?php
      $dbconn = pg_connect("dbname=editeur") or die("Conexión imposible");

      $res = pg_query($dbconn, "select * from autores where autor = 'Orwell'");
      $i = pg_num_fields($res);
      for ($j = 0; $j < $i; $j++) {
          echo "columna $j\n";
          $fieldname = pg_field_name($res, $j);
          echo "nombre campo: $fieldname\n";
          echo "tamaño visualización: " . pg_field_prtlen($res, $fieldname) . " caracteres\n";
          echo "tamaño registro: " . pg_field_size($res, $j) . " bytes\n";
          echo "tipo campo: " . pg_field_type($res, $j) . " \n\n";
      }
    ?>

El ejemplo anterior mostrará:

    columna 0
    nombre campo: autor
    tamaño visualización: 6 caracteres
    tamaño registro: -1 bytes
    tipo campo: varchar

    columna 1
    nombre campo: año
    tamaño visualización: 4 caracteres
    tamaño registro: 2 bytes
    tipo campo: int2

    columna 2
    nombre campo: título
    tamaño visualización: 24 caracteres
    tamaño registro: -1 bytes
    tipo campo: varchar

### Ver también

- pg_field_size() - Devuelve el tamaño interno de almacenamiento de un campo dado

# pg_field_size

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_size — Devuelve el tamaño interno de almacenamiento de un campo dado

### Descripción

function pg_field_size(PgSql\Result `$result`, int `$field`): int

pg_field_size() devuelve el tamaño interno de almacenamiento de un campo dado, en bytes.

> Nota:

> Anteriormente, esta función se llamaba pg_fieldsize().

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).
`field`

  Número del campo, comenzando en 0.

### Valores devueltos

El tamaño del almacenamiento interno de un campo (en bytes). -1 significa un campo de tamaño variable.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Recuperación de información de los campos

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Conexión imposible");

      $res = pg_query($dbconn, "select * from autores where autor = 'Orwell'");
      $i = pg_num_fields($res);
      for ($j = 0; $j < $i; $j++) {
          echo "columna $j\n";
          $fieldname = pg_field_name($res, $j);
          echo "Nombre del campo: $fieldname\n";
          echo "Tamaño para la visualización: " . pg_field_prtlen($res, $fieldname) . " caracteres\n";
          echo "Tamaño para el almacenamiento: " . pg_field_size($res, $j) . " bytes\n";
          echo "Tipo del campo: " . pg_field_type($res, $j) . " \n\n";
      }
    ?>

El ejemplo anterior mostrará:

    columna 0
    Nombre del campo: autor
    Tamaño para la visualización: 6 caracteres
    Tamaño para el almacenamiento: -1 bytes
    Tipo del campo: varchar

    columna 1
    Nombre del campo: año
    Tamaño para la visualización: 4 caracteres
    Tamaño para el almacenamiento: 2 bytes
    Tipo del campo: int2

    columna 2
    Nombre del campo: título
    Tamaño para la visualización: 24 caracteres
    Tamaño para el almacenamiento: -1 bytes
    Tipo del campo: varchar

### Ver también

- pg_field_prtlen() - Devuelve el tamaño de impresión
- pg_field_type() - Devuelve el tipo de un campo PostgreSQL dado por índice

# pg_field_table

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

pg_field_table — Devuelve el nombre o el oid de una tabla

### Descripción

function pg_field_table(PgSql\Result `$result`, int `$field`, bool `$oid_only` = `false`): string|int|false

pg_field_table() devuelve el nombre de la tabla a la que pertenece el campo o el oid de la tabla si el parámetro `oid_only` vale `true`.

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).
`field`

  Número del campo, comenzando en 0.

`oid_only`

  Por omisión, se devuelve el nombre de la tabla a la que pertenece el campo, pero si el parámetro `oid_only` se define como `true`, entonces, se devolverá el oid.

### Valores devueltos

En caso de éxito, el nombre de la tabla o el oid, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Recuperación de información de una tabla a partir de un campo

    <?php
    $dbconn = pg_connect("dbname=publisher") or die("Conexión imposible");

    $res = pg_query($dbconn, "SELECT bar FROM foo");

    echo pg_field_table($res, 0);
    echo pg_field_table($res, 0, true);

    $res = pg_query($dbconn, "SELECT version()");
    var_dump(pg_field_table($res, 0));
    ?>

Resultado del ejemplo anterior es similar a:

    foo
    14379580

    bool(false)

### Notas

> Nota:

> Devolver el oid es más rápido que devolver el nombre de la tabla, ya que la recuperación del nombre de la tabla requiere una consulta a la tabla del sistema de la base de datos.

### Ver también

- pg_field_name() - Devuelve el nombre de un campo PostgreSQL
- pg_field_type() - Devuelve el tipo de un campo PostgreSQL dado por índice

# pg_field_type

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_type — Devuelve el tipo de un campo PostgreSQL dado por índice

### Descripción

function pg_field_type(PgSql\Result `$result`, int `$field`): string

pg_field_type() devuelve una cadena que contiene el tipo base del campo dado por su índice `field`.

> Nota:

> Si el campo utiliza un dominio PostgreSQL (en lugar de un tipo básico), es el nombre del dominio subyacente el que se devuelve, en lugar del nombre del dominio en sí.

> Nota:

> Anteriormente, esta función se llamaba pg_fieldtype().

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).
`field`

  Número del campo, comenzando en 0.

### Valores devueltos

Una string que contiene el nombre base del tipo de campo.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Recuperación de información de los campos

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Conexión imposible");

      // Se asume que 'titre' es un tipo varchar
      $res = pg_query($dbconn, "select titre from autores where autor = 'Orwell'");

      echo "Tipo del campo titre : ", pg_field_type($res, 0);
    ?>

El ejemplo anterior mostrará:

    Tipo del campo titre : varchar

### Ver también

- pg_field_prtlen() - Devuelve el tamaño de impresión
- pg_field_name() - Devuelve el nombre de un campo PostgreSQL
- pg_field_type_oid() - Devuelve el ID de tipo (OID) para el número de campo correspondiente

# pg_field_type_oid

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_field_type_oid — Devuelve el ID de tipo (OID) para el número de campo correspondiente

### Descripción

function pg_field_type_oid(PgSql\Result `$result`, int `$field`): string|int

pg_field_type_oid() devuelve un entero que contiene el OID del tipo base del campo `field` dado en la instancia `result`.

Puede obtenerse más información acerca del tipo de campo consultando la tabla del sistema de PostgreSQL pg_type() con el OID obtenido por esta función.

> Nota:

> Si el campo utiliza un dominio PostgreSQL (en lugar de un tipo básico), es el OID del dominio subyacente el que se devuelve, en lugar del OID del dominio como tal.

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).
`field`

  Número del campo, comenzando en 0.

### Valores devueltos

El OID del tipo base del campo.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Recuperación de información de los campos

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Conexión imposible");

      // Se asume que 'título' es un tipo varchar
      $res = pg_query($dbconn, "select título from autores where autor = 'Orwell'");

      echo "Tipo del campo título OID: ", pg_field_type_oid($res, 0);
    ?>

El ejemplo anterior mostrará:

    Tipo del campo título OID: 1043

### Ver también

- pg_field_type() - Devuelve el tipo de un campo PostgreSQL dado por índice
- pg_field_prtlen() - Devuelve el tamaño de impresión
- pg_field_name() - Devuelve el nombre de un campo PostgreSQL

# pg_flush

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_flush — Envía los datos de la solicitud saliente a través de la conexión

### Descripción

function pg_flush(PgSql\Connection `$connection`): int|bool

La función pg_flush() envía todos los datos salientes de la solicitud pendientes de envío a través de la conexión.

### Parámetros

`connection`
  Una instancia PgSql\Connection.

### Valores devueltos

Devuelve `true` si el envío ha tenido éxito, o si no hay datos pendientes de envío, `0` si una parte de los datos pendientes han sido enviados pero aún quedan datos por enviar o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

# pg_free_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_free_result — Libera la memoria

### Descripción

function pg_free_result(PgSql\Result `$result`): bool

pg_free_result() libera la memoria y los datos asociados con la instancia PgSql\Result.

pg_free_result() solo es realmente útil si existe el riesgo de utilizar demasiada memoria durante el script. La memoria ocupada por los resultados se libera automáticamente al final del script.

> Nota:

> Anteriormente, esta función se llamaba pg_freeresult().

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_free_result()

    <?php
    $db = pg_connect("dbname=users user=me");

    $res = pg_query($db, "SELECT 1 UNION ALL SELECT 2");

    $val = pg_fetch_result($res, 1, 0);

    echo "El primer campo de la segunda línea es: ", $val, "\n";

    pg_free_result($res);
    ?>

El ejemplo anterior mostrará:

    El primer campo de la segunda línea es: 2

### Ver también

- pg_query() - Ejecuta una consulta PostgreSQL
- pg_query_params() - Envía un comando al servidor y espera el resultado, con la capacidad de pasar parámetros por separado del texto SQL de la consulta
- pg_execute() - Ejecuta una consulta preparada de PostgreSQL
- pg_result_memory_size() - Devuelve la cantidad de memoria asignada para un resultado de consulta

# pg_get_notify

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_get_notify — Lee el mensaje SQL NOTIFY

### Descripción

function pg_get_notify(PgSql\Connection `$connection`, int `$mode` = `PGSQL_ASSOC`): array|false

pg_get_notify() recibe el mensaje de NOTIFY enviado por un comando SQL `NOTIFY`. Para leer el mensaje asociado, se debe utilizar el comando `LISTEN`.

### Parámetros

`connection`
  Una instancia PgSql\Connection.
`mode`
  Un parámetro opcional que controla cómo el array devuelto es indexado. `mode` es una constante que puede tomar los siguientes valores: `PGSQL_ASSOC`, `PGSQL_NUM` y `PGSQL_BOTH`. Usando `PGSQL_NUM`, la función devolverá un array con índices numéricos, usando `PGSQL_ASSOC`, devolverá solo índices asociativos mientras que `PGSQL_BOTH` devolverá ambos índices numéricos y asociativos.

### Valores devueltos

Un array que contiene el nombre del mensaje `NOTIFY`. Si el servidor lo soporta, el array contiene también la versión del servidor y la carga útil (payload). De lo contrario, si no hay ningún `NOTIFY` pendiente, se devolverá `false`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_get_notify()

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Se ha producido un error.\n";
      exit;
    }

    // escucha el mensaje 'author_updated' de otros procesos
    pg_query($conn, 'LISTEN author_updated;');
    $notify = pg_get_notify($conn);
    if (!$notify) {
      echo "Ningún mensaje\n";
    } else {
      print_r($notify);
    }
    ?>

### Ver también

- pg_get_pid() - Lee el identificador de proceso del servidor PostgreSQL

# pg_get_pid

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_get_pid — Lee el identificador de proceso del servidor PostgreSQL

### Descripción

function pg_get_pid(PgSql\Connection `$connection`): int

pg_get_pid() lee el identificador de proceso del servidor PostgreSQL. El identificador de proceso es útil para verificar si un mensaje de `NOTIFY` ha sido enviado mediante pg_get_notify() por otro proceso o no.

### Parámetros

`connection`
  Una instancia PgSql\Connection.

### Valores devueltos

El identificador del proceso del servidor.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_get_pid()

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Se ha producido un error.\n";
      exit;
    }

    // PID del servidor. Utilice entonces el PID con pg_get_notify()
    $pid = pg_get_pid($conn);
    ?>

### Ver también

- pg_get_notify() - Lee el mensaje SQL NOTIFY

# pg_get_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_get_result — Lee un resultado asíncrono de PostgreSQL

### Descripción

function pg_get_result(PgSql\Connection `$connection`): PgSql\Result|false

pg_get_result() recupera la instancia PgSql\Result de una consulta asíncrona ejecutada por pg_send_query(), pg_send_query_params(), o pg_send_execute().

pg_send_query() y otras funciones de consulta asíncrona pueden enviar múltiples consultas a un servidor PostgreSQL y pg_get_result() se utiliza para obtener cada resultado de consulta, uno por uno.

### Parámetros

`connection`
  Una instancia PgSql\Connection.

### Valores devueltos

Una instancia de PgSql\Result, o `false` si no hay más resultados disponibles.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Ahora devuelve una instancia de PgSql\Result ; anteriormente, se devolvía un resource.
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_get_result()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Conexión imposible");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from autores; select count(*) from autores;");
      }

      $res1 = pg_get_result($dbconn);
      echo "Primera llamada a pg_get_result(): $res1\n";
      $rows1 = pg_num_rows($res1);
      echo "$res1 tiene $rows1 registros\n\n";

      $res2 = pg_get_result($dbconn);
      echo "Segunda llamada a pg_get_result(): $res2\n";
      $rows2 = pg_num_rows($res2);
      echo "$res2 tiene $rows2 registros\n";
    ?>

El ejemplo anterior mostrará:

    Primera llamada a pg_get_result(): Resource id #3
    Resource id #3 tiene 3 registros

    Segunda llamada a pg_get_result(): Resource id #4
    Resource id #4 tiene 1 registros

### Ver también

- pg_send_query() - Ejecuta una consulta PostgreSQL asíncrona

# pg_host

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_host — Devuelve el nombre de host

### Descripción

function pg_host(?PgSql\Connection `$connection` = `null`): string

pg_host() devuelve el nombre de host asociado a la instancia de conexión PostgreSQL.

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` es `null`, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

### Valores devueltos

Una string que contiene el nombre del host de `connection` o una cadena vacía en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.
8.0.0 | `connection` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con pg_host()

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       print "Correctamente conectado a : " . pg_host($pgsql_conn) . "<br/>\n";
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

### Ver también

- pg_connect() - Establece una conexión PostgreSQL
- pg_pconnect() - Establece una conexión PostgreSQL persistente

# pg_insert

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_insert — Inserta un array en una tabla

### Descripción

function pg_insert(
PgSql\Connection `$connection`,
string `$table_name`,
array `$values`,
int `$flags` = `PGSQL_DML_EXEC`
): PgSql\Result|string|bool

pg_insert() inserta los `values` en la tabla `table_name`.

Si `flags` está especificado, pg_convert() se aplica a `values` con los flags proporcionados.

Por omisión, pg_insert() pasa valores sin tratar. Los valores deben ser escapados o el flag `PGSQL_DML_ESCAPE` debe ser especificado en `flags`. `PGSQL_DML_ESCAPE` coloca comillas y escapa los parámetros/identificadores. Por consiguiente, los nombres de tabla/columnas se vuelven sensibles a mayúsculas y minúsculas.

Tenga en cuenta que ni el escape ni las consultas preparadas pueden proteger consultas LIKE, JSON, arrays, Regex, etc. Estos parámetros deben ser tratados de acuerdo con su contexto. Es decir, escapar/validar los valores.

### Parámetros

`connection`
  Una instancia PgSql\Connection.
`table_name`

  Nombre de la tabla en la que se insertarán las filas. La tabla `table_name` debe tener al menos tantas columnas como elementos tenga `values`.

`values`

  Un array cuyas claves son los nombres de los campos en la tabla `table_name`, y cuyos valores son los valores de esos campos que serán insertados.

`flags`

  Cualquier combinación de constantes entre `PGSQL_CONV_OPTS`, `PGSQL_DML_NO_CONV`, `PGSQL_DML_ESCAPE`, `PGSQL_DML_EXEC`, `PGSQL_DML_ASYNC` o `PGSQL_DML_STRING`. Si `PGSQL_DML_STRING` forma parte del parámetro `flags`, entonces la consulta será retornada. Cuando la constante `PGSQL_DML_NO_CONV` o la constante `PGSQL_DML_ESCAPE` está definida, no se realizará ninguna llamada a la función pg_convert() internamente.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.. O retorna un string si `PGSQL_DML_STRING` es proporcionado a través de `flags`.

### Errores/Excepciones

Se lanza una ValueError cuando la tabla especificada es inválida.

Se lanza una ValueError o TypeError cuando el valor o el tipo del campo no coincide correctamente con un tipo PostgreSQL.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Ahora lanza un error ValueError cuando la tabla especificada es inválida; anteriormente, se emitía un `E_WARNING`.
8.3.0 | Ahora lanza un error ValueError o TypeError cuando el valor o el tipo del campo no coincide correctamente con un tipo PostgreSQL; anteriormente, se emitía un `E_WARNING`.
8.1.0 | Ahora devuelve una instancia de PgSql\Result ; anteriormente, se devolvía un resource.
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_insert()

    <?php
      $db = pg_connect ('dbname=foo');
      // Esto es seguro en cierta medida, ya que todos los valores son escapados
      // Sin embargo, PostgreSQL soporta JSON/arrays. Estos no son
      // seguros ni por escape ni por consultas preparadas.
      $res = pg_insert($dbconn, 'post_log', $_POST, PGSQL_DML_ESCAPE);
      if ($res) {
          echo "Los datos POSTeados han podido ser registrados con éxito.\n";
      } else {
          echo "Hay un problema con los datos.\n";
      }
    ?>

### Ver también

- pg_convert() - Convierte valores de un array asociativo a una forma adecuada para consultas SQL

# pg_jit

(PHP 8 >= 8.4.0)

pg_jit — Devuelve la información JIT del servidor

### Descripción

function pg_jit(?PgSql\Connection `$connection` = `null`): array

pg_jit() devuelve un array con la información JIT (compilación Just-In-Time) del servidor PostgreSQL.

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` es `null`, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

### Valores devueltos

Devuelve un array que contiene la información JIT del servidor.

### Ver también

- pg_version() - Devuelve un array con las versiones del cliente, del protocolo y del servidor (si está disponible)

# pg_last_error

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_last_error — Lee el último mensaje de error en la conexión

### Descripción

function pg_last_error(?PgSql\Connection `$connection` = `null`): string

pg_last_error() devuelve el último mensaje de error para una conexión `connection`.

Los mensajes de error pueden ser sobrescritos por llamadas internas a la extensión PostgreSQL (libpq): es posible que el mensaje devuelto no sea apropiado, especialmente si han ocurrido múltiples errores en el módulo.

Utilícese pg_result_error(), pg_result_error_field(), pg_result_status() y pg_connection_status() para mejorar la gestión de errores.

> Nota:

> Anteriormente, esta función se llamaba pg_errormessage().

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` es `null`, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

### Valores devueltos

Una string que contiene el último mensaje de error en la conexión `connection`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.
8.0.0 | `connection` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con pg_last_error()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Conexión imposible");

      // Consulta que falla
      $res = pg_query($dbconn, "select * from doesnotexist");

      echo pg_last_error($dbconn);
    ?>

### Ver también

- pg_result_error() - Lee el mensaje de error asociado a un resultado
- pg_result_error_field() - Devuelve un campo individual de un informe de error

# pg_last_notice

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

pg_last_notice — Devuelve la última nota del servidor PostgreSQL

### Descripción

function pg_last_notice(PgSql\Connection `$connection`, int `$mode` = `PGSQL_NOTICE_LAST`): array|string|bool

pg_last_notice() devuelve la última nota del servidor PostgreSQL en la conexión `connection` especificada. El servidor PostgreSQL envía notas en varios casos, por ejemplo al crear una columna `SERIAL` en una tabla.

Con pg_last_notice(), se pueden evitar consultas innecesarias verificando si las notas están o no relacionadas con la transacción.

El seguimiento de las notas puede ser opcional estableciendo a 1 la directiva de configuración `pgsql.ignore_notice` del archivo php.ini.

El registro de las notas puede ser opcional estableciendo la directiva de configuración `pgsql.log_notice` del php.ini a 0. A menos que `pgsql.ignore_notice` esté a 0, las notas no serán registradas.

### Parámetros

`connection`
  Una instancia PgSql\Connection.
`mode`

  Uno de `PGSQL_NOTICE_LAST` (para devolver la última nota), `PGSQL_NOTICE_ALL` (para devolver todas las notas), o `PGSQL_NOTICE_CLEAR` (para borrar las notas).

### Valores devueltos

Una string que contiene la última nota en la conexión `connection` con `PGSQL_NOTICE_LAST`, un array con `PGSQL_NOTICE_ALL`, un bool con `PGSQL_NOTICE_CLEAR`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.
7.1.0 | Se añadió el parámetro `mode`.

### Ejemplos

Ejemplo #1 Ejemplo con pg_last_notice()

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    $res = pg_query("CREATE TABLE test (id SERIAL)");

    $notice = pg_last_notice($pgsql_conn);

    echo $notice;
    ?>

El ejemplo anterior mostrará:

    CREATE TABLE will create implicit sequence "test_id_seq" for "serial" column "test.id"

### Ver también

- pg_query() - Ejecuta una consulta PostgreSQL
- pg_last_error() - Lee el último mensaje de error en la conexión

# pg_last_oid

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_last_oid — Devuelve el identificador de la última línea

### Descripción

function pg_last_oid(PgSql\Result `$result`): string|int|false

pg_last_oid() sirve para recuperar el OID asignado a una línea insertada.

El campo OID se ha vuelto opcional desde PostgreSQL 7.2 y ya no estará presente por defecto en PostgreSQL 8.1. Cuando el campo OID no está presente en la tabla, el programador debe utilizar pg_result_status() para verificar si la línea ha sido correctamente insertada.

Para obtener el valor de un campo `SERIAL` en una línea insertada, es necesario utilizar la función `CURRVAL` de PostgreSQL nombrando la secuencia de la que se requiere la última valor. Si el nombre de la secuencia es desconocido, la función PostgreSQL 8.0 `pg_get_serial_sequence` es necesaria.

PostgreSQL 8.1 tiene una función `LASTVAL` que devuelve el valor de la secuencia más recientemente utilizada en la sesión. Esto permite evitar nombrar la secuencia, la tabla o la columna.

> Nota:

> Anteriormente, esta función se llamaba pg_getlastoid().

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).

### Valores devueltos

Un int o string que contiene el OID asignado a la línea más reciente insertada en la conexión `connection` especificada o `false` en caso de error o de OID no disponible.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_last_oid()

    <?php
      // Conectar a la base de datos
      pg_connect("dbname=mark host=localhost");

      // Crear una tabla de ejemplo
      pg_query("CREATE TABLE test (a INTEGER) WITH OIDS");

      // Insertar algunos datos
      $res = pg_query("INSERT INTO test VALUES (1)");

      $oid = pg_last_oid($res);
    ?>

### Ver también

- pg_query() - Ejecuta una consulta PostgreSQL
- pg_result_status() - Lee el estado del resultado

# pg_lo_close

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_close — Cierra un objeto grande de PostgreSQL

### Descripción

function pg_lo_close(PgSql\Lob `$lob`): bool

pg_lo_close() cierra un objeto grande.

Para utilizar un objeto grande (`lo`), es necesario hacerlo dentro de una transacción.

> Nota:

> Anteriormente, esta función se llamaba pg_loclose().

### Parámetros

`lob`
  Una instancia PgSql\Lob, devuelta por pg_lo_open().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `lob` ahora espera una instancia de PgSql\Lob ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_lo_close()

    <?php
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $oid = pg_lo_create($database);
       echo "$oid\n";
       $handle = pg_lo_open($database, $oid, "w");
       echo "$handle\n";
       pg_lo_write($handle, "datos de objeto grande");
       pg_lo_close($handle);
       pg_query($database, "commit");
    ?>

### Ver también

- pg_lo_open() - Abre un objeto de gran tamaño de PostgreSQL
- pg_lo_create() - Crea un objeto de gran tamaño de PostgreSQL
- pg_lo_import() - Importa un objeto grande desde un fichero

# pg_lo_create

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_create — Crea un objeto de gran tamaño de PostgreSQL

### Descripción

function pg_lo_create(PgSql\Connection `$connection` = ?, mixed `$object_id` = ?): int
function pg_lo_create(mixed `$object_id`): int

pg_lo_create() crea un objeto de gran tamaño y devuelve su OID. Los modos de acceso de PostgreSQL `INV_READ` y `INV_WRITE` no son soportados: el objeto siempre puede ser creado con permisos de lectura y escritura.

Para utilizar un objeto de gran tamaño, es necesario hacerlo dentro de una transacción.

En lugar de utilizar la interfaz de objetos de gran tamaño (que no tiene ningún control de acceso y es engorroso de usar), se recomienda utilizar la columna de tipo bytea de PostgreSQL y pg_escape_bytea().

> Nota:

> Anteriormente, esta función se llamaba pg_locreate().

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` no es especificado, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

`object_id`

  Si se proporciona el argumento `object_id`, la función intentará crear un objeto grande con este identificador; de lo contrario, se asignará un identificador de objeto disponible por el servidor.

### Valores devueltos

Un objeto grande OID, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_lo_create()

    <?php
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $oid = pg_lo_create($database);
       echo "$oid\n";
       $handle = pg_lo_open($database, $oid, "w");
       echo "$handle\n";
       pg_lo_write($handle, "datos de objeto de gran tamaño");
       pg_lo_close($handle);
       pg_query($database, "commit");
    ?>

# pg_lo_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_export — Exporta un objeto grande a un fichero

### Descripción

function pg_lo_export(PgSql\Connection `$connection` = ?, int `$oid`, string `$filename`): bool

pg_lo_export() toma un objeto grande de la base de datos PostgreSQL y guarda su contenido en un fichero local en el sistema.

Para utilizar un objeto grande (`lo`), es necesario hacerlo dentro de una transacción.

> Nota:

> Anteriormente, esta función se llamaba pg_loexport().

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` no es especificado, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

`oid`

  El OID del objeto grande en la base de datos.

`filename`

  La ruta de acceso completa y el fichero en el que se escribirá el objeto grande en el sistema del cliente.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_lo_export()

    <?php
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $oid = pg_lo_create($database);
       $handle = pg_lo_open($database, $oid, "w");
       pg_lo_write($handle, "datos objeto grande");
       pg_lo_close($handle);
       pg_lo_export($database, $oid, '/tmp/lob.dat');
       pg_query($database, "commit");
    ?>

### Ver también

- pg_lo_import() - Importa un objeto grande desde un fichero

# pg_lo_import

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_import — Importa un objeto grande desde un fichero

### Descripción

function pg_lo_import(PgSql\Connection `$connection` = ?, string `$filename`, int|string `$oid` = ?): int|string|false

pg_lo_import() crea un nuevo objeto grande en la base de datos usando un fichero en el sistema de ficheros como fuente de datos.

Para usar la interfaz de objetos grandes, es necesario encerrarla dentro de un bloque de transacción.

> Nota:

> Esta función antes se llamaba pg_loimport().

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` no es especificado, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

`filename`

  La ruta completa y nombre del fichero en el sistema de ficheros del cliente desde el cual leer los datos del objeto grande.

`oid`

  Si se proporciona un `oid`, la función intentará crear un objeto grande con este ID, de lo contrario, el servidor asignará un ID de objeto libre. Este parámetro depende de funcionalidad que apareció por primera vez en PostgreSQL 8.1.

### Valores devueltos

El OID del objeto grande recién creado, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo de pg_lo_import()

    <?php
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $oid = pg_lo_import($database, '/tmp/lob.dat');
       pg_query($database, "commit");
    ?>

### Ver también

- pg_lo_export() - Exporta un objeto grande a un fichero
- pg_lo_open() - Abre un objeto de gran tamaño de PostgreSQL

# pg_lo_open

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_open — Abre un objeto de gran tamaño de PostgreSQL

### Descripción

function pg_lo_open(PgSql\Connection `$connection`, int `$oid`, string `$mode`): PgSql\Lob|false

pg_lo_open() abre un objeto grande en la base de datos y devuelve una instancia de PgSql\Lob para que pueda ser manipulado.

Advertencia

No cerrar la conexión a la base de datos antes de cerrar la instancia PgSql\Lob.

Para utilizar un objeto de gran tamaño (`lo`), es necesario hacerlo dentro de una transacción.

> Nota:

> Anteriormente, esta función se llamaba pg_loopen().

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` no es especificado, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

`oid`

  El OID del objeto de gran tamaño en la base de datos.

`mode`

  Puede ser "r" para solo lectura, "w" para solo escritura o "rw" para lectura y escritura.

### Valores devueltos

Una instancia PgSql\Lob, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Ahora devuelve una instancia de PgSql\Lob; anteriormente, se devolvía un resource.
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_lo_open()

    <?php
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $oid = pg_lo_create($database);
       echo "$oid\n";
       $handle = pg_lo_open($database, $oid, "w");
       echo "$handle\n";
       pg_lo_write($handle, "datos de objeto de gran tamaño");
       pg_lo_close($handle);
       pg_query($database, "commit");
    ?>

### Ver también

- pg_lo_close() - Cierra un objeto grande de PostgreSQL
- pg_lo_create() - Crea un objeto de gran tamaño de PostgreSQL

# pg_lo_read

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_read — Lee un objeto de gran tamaño

### Descripción

function pg_lo_read(PgSql\Lob `$lob`, int `$length` = 8192): string|false

pg_lo_read() lee como máximo `length` bytes de un objeto de gran tamaño y devuelve los datos como un string.

Para utilizar un objeto de gran tamaño (`lo`), es necesario hacerlo dentro de una transacción.

> Nota:

> Anteriormente, esta función se llamaba pg_loread().

### Parámetros

`lob`
  Una instancia PgSql\Lob, devuelta por pg_lo_open().
`length`

  Un número máximo de bytes a devolver. Este argumento es opcional.

### Valores devueltos

Una string que contiene `length` bytes del objeto de gran tamaño o `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `lob` ahora espera una instancia de PgSql\Lob ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_lo_read()

    <?php
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "r");
       $data = pg_lo_read($handle, 50000);
       pg_query($database, "commit");
       echo $data;
    ?>

### Ver también

- pg_lo_read_all() - Lee un objeto de gran tamaño en su totalidad

# pg_lo_read_all

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_read_all — Lee un objeto de gran tamaño en su totalidad

### Descripción

function pg_lo_read_all(PgSql\Lob `$lob`): int

pg_lo_read_all() lee un objeto de gran tamaño en su totalidad y lo envía directamente al cliente, después de los encabezados adecuados. Esta función está prevista para transmitir sonidos o imágenes.

Para utilizar un objeto de gran tamaño (`lo`), es necesario hacerlo dentro de una transacción.

> Nota:

> Anteriormente, esta función se llamaba pg_loreadall().

### Parámetros

`lob`
  Una instancia PgSql\Lob, devuelta por pg_lo_open().

### Valores devueltos

Número de bytes leídos.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `lob` ahora espera una instancia de PgSql\Lob ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_lo_read_all()

    <?php
       header('Content-type: image/jpeg');
       $image_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $image_oid, "r");
       pg_lo_read_all($handle);
       pg_query($database, "commit");
    ?>

### Ver también

- pg_lo_read() - Lee un objeto de gran tamaño

# pg_lo_seek

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_seek — Modifica la posición en un objeto de gran tamaño

### Descripción

function pg_lo_seek(PgSql\Lob `$lob`, int `$offset`, int `$whence` = `SEEK_CUR`): bool

pg_lo_seek() modifica la posición del puntero en la instancia PgSql\Lob.

Para utilizar un objeto de gran tamaño (`lo`), es necesario hacerlo dentro de una transacción.

### Parámetros

`lob`
  Una instancia PgSql\Lob, devuelta por pg_lo_open().
`offset`

  El número de bytes de desplazamiento.

`whence`

  Una de estas constantes `PGSQL_SEEK_SET` (posiciona a partir del inicio del objeto), `PGSQL_SEEK_CUR` (posiciona a partir de la posición actual) o `PGSQL_SEEK_END` (posiciona a partir del final del objeto).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `lob` ahora espera una instancia de PgSql\Lob ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_lo_seek()

    <?php
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "r");
       // Salta los primeros 50000 bytes
       pg_lo_seek($handle, 50000, PGSQL_SEEK_SET);
       // Lee los siguientes 10000 bytes
       $data = pg_lo_read($handle, 10000);
       pg_query($database, "commit");
       echo $data;
    ?>

### Ver también

- pg_lo_tell() - Devuelve la posición actual en un objeto grande de PostgreSQL

# pg_lo_tell

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_tell — Devuelve la posición actual en un objeto grande de PostgreSQL

### Descripción

function pg_lo_tell(PgSql\Lob `$lob`): int

pg_lo_tell() devuelve la posición actual (desde el inicio) del puntero de lectura en el objeto grande `large_object`.

Para utilizar una interfaz con un objeto grande, es necesario incluirlo en un bloque de transacción.

### Parámetros

`lob`
  Una instancia PgSql\Lob, devuelta por pg_lo_open().

### Valores devueltos

La posición actual del puntero (en número de bytes) desde el inicio del objeto grande. Si hay un error, el valor devuelto será negativo.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `lob` ahora espera una instancia de PgSql\Lob ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_lo_tell()

    <?php
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "r");
       // Salta los primeros 50000 bytes
       pg_lo_seek($handle, 50000, PGSQL_SEEK_SET);
       // Se verifica cuántos bytes se han saltado
       $offset = pg_lo_tell($handle);
       echo "La posición del puntero es: $offset";
       pg_query($database, "commit");
    ?>

El ejemplo anterior mostrará:

    La posición del puntero es: 50000

### Ver también

- pg_lo_seek() - Modifica la posición en un objeto de gran tamaño

# pg_lo_truncate

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_lo_truncate — Trunca un objeto grande

### Descripción

function pg_lo_truncate(PgSql\Lob `$lob`, int `$size`): bool

pg_lo_truncate() trunca una instancia PgSql\Lob.

Para utilizar la interfaz de objetos grandes, es necesario encerrarla en un bloqueo de transacción.

### Parámetros

`lob`
  Una instancia PgSql\Lob, devuelta por pg_lo_open().
`size`

  El número de bytes a truncar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `lob` ahora espera una instancia de PgSql\Lob ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_lo_truncate()

    <?php
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "r");
       // Trunca a 0
       pg_lo_truncate($handle, 0);
       pg_query($database, "commit");
       echo $data;
    ?>

### Ver también

- pg_lo_tell() - Devuelve la posición actual en un objeto grande de PostgreSQL

# pg_lo_unlink

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_unlink — Elimina un objeto grande de PostgreSQL

### Descripción

function pg_lo_unlink(PgSql\Connection `$connection`, int `$oid`): bool

pg_lo_unlink() elimina el objeto grande cuyo identificador es `oid`, para la conexión `connection`. Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

Para utilizar un objeto grande (`lo`), es necesario hacerlo dentro de una transacción.

> Nota:

> Anteriormente, esta función se llamaba pg_lounlink().

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` no es especificado, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

`oid`

  El OID del objeto grande en la base de datos.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_lo_unlink()

    <?php
       // OID del objeto grande a eliminar
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       pg_lo_unlink($database, $doc_oid);
       pg_query($database, "commit");
    ?>

### Ver también

- pg_lo_create() - Crea un objeto de gran tamaño de PostgreSQL
- pg_lo_import() - Importa un objeto grande desde un fichero

# pg_lo_write

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_write — Escribe un objeto de gran tamaño de PostgreSQL

### Descripción

function pg_lo_write(PgSql\Lob `$lob`, string `$data`, ?int `$length` = `null`): int|false

pg_lo_write() escribe datos dentro de un objeto de gran tamaño en la posición actual.

Para manipular un objeto de gran tamaño (`lo`), es necesario colocar las operaciones dentro de un bloque de transacción.

> Nota:

> Anteriormente, esta función se llamaba pg_lowrite().

### Parámetros

`lob`
  Una instancia PgSql\Lob, devuelta por pg_lo_open().
`data`

  Los datos a ser escritos en el objeto de gran tamaño. Si `length` es un int y es inferior al tamaño de `data`, solo los primeros `length` bytes serán escritos.

`length`

  Un número máximo de bytes a escribir. Debe ser superior a cero y menor al tamaño de `data`. Este argumento es opcional; si se omite, tomará por defecto el tamaño de `data`.

### Valores devueltos

El número de bytes escritos en el objeto de gran tamaño o `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `lob` ahora espera una instancia de PgSql\Lob ; anteriormente, se esperaba un resource.
8.0.0 | `connection` es ahora nullable.

### Ejemplos

Ejemplo #1 Ejemplo con pg_lo_write()

    <?php
       $doc_oid = 189762345;
       $data = "Esto sobrescribirá el inicio del objeto de gran tamaño.";
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "w");
       $data = pg_lo_write($handle, $data);
       pg_query($database, "commit");
    ?>

### Ver también

- pg_lo_create() - Crea un objeto de gran tamaño de PostgreSQL
- pg_lo_open() - Abre un objeto de gran tamaño de PostgreSQL

# pg_meta_data

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_meta_data — Lee los metadatos de la tabla PostgreSQL

### Descripción

function pg_meta_data(PgSql\Connection `$connection`, string `$table_name`, bool `$extended` = `false`): array|false

pg_meta_data() devuelve la definición de la tabla `table_name` en forma de array.

### Parámetros

`connection`
  Una instancia PgSql\Connection.
`table_name`

  El nombre de la tabla.

`extended`

  Flag para devolver los metadatos extendidos. Por omisión, vale `false`.

### Valores devueltos

Un array de la definición de la tabla, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Recuperación de los metadatos de una tabla

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Conexión imposible");

      $meta = pg_meta_data($dbconn,'auteurs');
      if (is_array ($meta)) {
           echo '<pre>';
           var_dump ($meta);
           echo '</pre>';
      }
    ?>

El ejemplo anterior mostrará:

    array(3) {
    ["auteur"]=>
    array(5) {
      ["num"]=>
      int(1)
      ["type"]=>
      string(7) "varchar"
      ["len"]=>
      int(-1)
      ["not null"]=>
      bool(false)
      ["has default"]=>
      bool(false)
    }
    ["annee"]=>
    array(5) {
      ["num"]=>
      int(2)
      ["type"]=>
      string(4) "int2"
      ["len"]=>
      int(2)
      ["not null"]=>
      bool(false)
      ["has default"]=>
      bool(false)
    }
    ["titre"]=>
    array(5) {
      ["num"]=>
      int(3)
      ["type"]=>
      string(7) "varchar"
      ["len"]=>
      int(-1)
      ["not null"]=>
      bool(false)
      ["has default"]=>
      bool(false)
    }
    }

### Ver también

- pg_convert() - Convierte valores de un array asociativo a una forma adecuada para consultas SQL

# pg_num_fields

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_num_fields — Devuelve el número de campos

### Descripción

function pg_num_fields(PgSql\Result `$result`): int

pg_num_fields() devuelve el número de campos (o columnas) de una instancia PgSql\Result.

> Nota:

> Anteriormente, esta función se llamaba pg_numfields().

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).

### Valores devueltos

El número de campos (o columnas) en el conjunto de resultados. En caso de error, se devuelve -1.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_num_fields()

    <?php
    $result = pg_query($conn, "SELECT 1, 2");

    $num = pg_num_fields($result);

    echo $num . " campo(s) devuelto(s).\n";
    ?>

El ejemplo anterior mostrará:

    2 campo(s) devuelto(s).

### Ver también

- pg_num_rows() - Devuelve el número de filas de PostgreSQL
- pg_affected_rows() - Devuelve el número de filas afectadas

# pg_num_rows

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_num_rows — Devuelve el número de filas de PostgreSQL

### Descripción

function pg_num_rows(PgSql\Result `$result`): int

pg_num_rows() devuelve el número de filas de una instancia PgSql\Result.

> Nota:

> Anteriormente, esta función se llamaba pg_numrows().

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).

### Valores devueltos

El número de filas en el conjunto de resultados. En caso de error, se devuelve `-1`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_num_rows()

    <?php
    $result = pg_query($conn, "SELECT 1");

    $rows = pg_num_rows($result);

    echo $rows . " línea(s) devuelta(s).\n";
    ?>

El ejemplo anterior mostrará:

    1 línea(s) devuelta(s).

### Ver también

- pg_num_fields() - Devuelve el número de campos
- pg_affected_rows() - Devuelve el número de filas afectadas

# pg_options

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_options — Devuelve las opciones de PostgreSQL

### Descripción

function pg_options(?PgSql\Connection `$connection` = `null`): string

pg_options() devuelve un string que contiene las opciones de la conexión PostgreSQL `connection`.

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` es `null`, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

### Valores devueltos

Una string que contiene las opciones de `connection`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.
8.0.0 | `connection` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con pg_options()

    <?php
       $pgsql_conn = pg_connect("dbname=mark host=localhost");
       echo pg_options($pgsql_conn);
    ?>

### Ver también

- pg_connect() - Establece una conexión PostgreSQL

# pg_parameter_status

(PHP 5, PHP 7, PHP 8)

pg_parameter_status — Consulta un parámetro de configuración actual del servidor

### Descripción

function pg_parameter_status(PgSql\Connection `$connection` = ?, string `$name`): string|false

Consulta un parámetro de configuración actual del servidor.

Ciertos valores de parámetros son devueltos por el servidor automáticamente al inicio de la conexión o cuando un valor cambia. pg_parameter_status() puede ser utilizada para consultar estas configuraciones. La función devuelve el valor actual del parámetro si es conocido o `false` si el parámetro es desconocido.

Los parámetros devueltos por el servidor son `server_version`, `server_encoding`, `client_encoding`, `is_superuser`, `session_authorization`, `DateStyle`, `TimeZone` y `integer_datetimes`. Tenga en cuenta que `server_version`, `server_encoding` y `integer_datetimes` no pueden cambiar después del inicio de PostgreSQL.

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` no es especificado, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

`name`

  Los valores posibles de `name` son `server_version`, `server_encoding`, `client_encoding`, `is_superuser`, `session_authorization`, `DateStyle`, `TimeZone` y `integer_datetimes`. Cabe señalar que este valor es sensible a mayúsculas y minúsculas.

### Valores devueltos

Una string que contiene el valor del parámetro, `false` en caso de fallo o si el parámetro `name` es inválido.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_parameter_status()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Conexión imposible");

      echo "Codificación del servidor: ", pg_parameter_status($dbconn, "server_encoding");
    ?>

El ejemplo anterior mostrará:

    Codificación del servidor: SQL_ASCII

# pg_pconnect

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_pconnect — Establece una conexión PostgreSQL persistente

### Descripción

function pg_pconnect(string `$connection_string`, int `$flags` = 0): PgSql\Connection|false

pg_pconnect() devuelve una instancia PgSql\Connection de conexión persistente.

Si se realiza una segunda llamada a pg_pconnect() con el mismo `connection_string` como una conexión existente, se devolverá la conexión existente a menos que se pase `PGSQL_CONNECT_FORCE_NEW` a `flags`.

Para activar las conexiones persistentes, la directiva de configuración pgsql.allow_persistent del php.ini debe establecerse en `On` (que es su valor por omisión). El número máximo de conexiones puede limitarse mediante la directiva de configuración pgsql.max_persistent en el archivo php.ini (por omisión, su valor es `-1`, es decir, sin límite). El número total de conexiones puede configurarse con la directiva pgsql.max_links del archivo php.ini.

pg_close() no cerrará las conexiones persistentes generadas por pg_pconnect().

### Parámetros

`connection_string`

  La cadena `connection_string` puede estar vacía para utilizar todos los parámetros por omisión o puede contener uno o varios parámetros de configuración separados por espacios. Cada parámetro de configuración tiene la forma `code = valor`. Los espacios alrededor del signo igual son opcionales. Para escribir un valor vacío o un valor que contenga espacios, rodee este valor con comillas simples, por ejemplo: `code = 'un valor'`. Las comillas simples y las barras invertidas dentro del valor deben escaparse con una barra invertida, es decir `\'` y `\\`.

  Las palabras clave actualmente reconocidas son : `host`, `hostaddr`, `port`, `dbname`, `user`, `password`, `connect_timeout`, `options`, `tty` (ignorado), `sslmode`, `requiressl` (obsoleto, utilice `sslmode`) y `service`. La lista de estos argumentos depende de la versión del servidor PostgreSQL.

`flags`

  Si `PGSQL_CONNECT_FORCE_NEW` se pasa como argumento, entonces se creará una nueva conexión, incluso si la cadena `connection_string` es idéntica a la de la conexión existente.

### Valores devueltos

Devuelve una instancia de PgSql\Connection en caso de éxito, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Ahora devuelve una instancia de PgSql\Connection ; anteriormente, se devolvía un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_pconnect()

    <?php
    // conexión a una base de datos llamada "marie"
    $dbconn = pg_pconnect("dbname=marie");

    // conexión a una base de datos llamada "marie" en el host "localhost" en el puerto "5432"
    $dbconn2 = pg_pconnect("host=localhost port=5432 dbname=marie");

    // conexión a una base de datos llamada "marie" en el host "mouton" con un
    // nombre de usuario y una contraseña
    $dk

    // conexión a una base de datos llamada "test" en el host "mouton" con un
    // nombre de usuario y una contraseña
    $conn_string = "host=mouton port=5432 dbname=test user=agneau password=bar";
    $dbconn4 = pg_pconnect($conn_string);
    ?>

### Ver también

- pg_connect() - Establece una conexión PostgreSQL
- Conexiones Persistentes

# pg_ping

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_ping — Ping la conexión a la base de datos

### Descripción

function pg_ping(?PgSql\Connection `$connection` = `null`): bool

pg_ping() realiza un ping a la conexión a la base de datos y intenta reconectarse si la conexión se ha perdido.

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` es `null`, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.
8.0.0 | `connection` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con pg_ping()

    <?php
    $conn = pg_pconnect ("dbname=publisher");
    if (!$conn) {
      echo "Se ha producido un error.\n";
      exit;
    }

    if (!pg_ping($conn))
      die("La conexión se ha perdido\n");
    ?>

### Ver también

- pg_connection_status() - Se lee el estado de la conexión PostgreSQL
- pg_connection_reset() - Reinicia la conexión al servidor PostgreSQL

# pg_port

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_port — Devuelve el número de puerto

### Descripción

function pg_port(?PgSql\Connection `$connection` = `null`): string

pg_port() devuelve el número de puerto de la conexión dada por `connection`.

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` es `null`, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

### Valores devueltos

Una string que contiene el número de puerto del servidor de base de datos identificado por `connection` o una cadena vacía en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.
8.0.0 | `connection` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con pg_port()

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       print "Conectado correctamente al puerto : " . pg_port($pgsql_conn) . "<br/>\n";
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

# pg_prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_prepare — Envía una solicitud al servidor para crear una sentencia preparada con los parámetros dados y espera la ejecución

### Descripción

function pg_prepare(PgSql\Connection `$connection` = ?, string `$statement_name`, string `$query`): PgSql\Result|false

pg_prepare() crea una consulta preparada para una ejecución posterior con pg_execute() o pg_send_execute(). Esta característica permite que las órdenes que serán utilizadas repetidamente sean analizadas y planificadas una sola vez, en lugar de ser ejecutadas cada vez.

La función crea una consulta preparada llamada `statement_name` a partir de la cadena `query`, la cual debe contener una sola orden SQL. `statement_name` puede ser `""` para crear una consulta sin nombre. En este caso, las consultas que existían y que no tenían nombres son automáticamente sobrescritas; de lo contrario, habrá un error si el nombre de la consulta ya está definido en la sesión actual. Si se utilizan parámetros, estos son referenciados como `$1`, `$2`, etc. en `query`.

Las consultas preparadas para ser utilizadas con pg_prepare() también pueden ser creadas ejecutando la orden SQL `PREPARE`. (Sin embargo, pg_prepare() es más flexible ya que no requiere que los tipos de los parámetros sean preespecificados.) Además, aunque no existe una función PHP para eliminar una consulta preparada, la orden SQL `DEALLOCATE` puede ser utilizada para este propósito.

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` no es especificado, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

`statement_name`

  El nombre a dar a la consulta preparada. Debe ser único para cada sesión. Si se especifica una cadena vacía `""` entonces se crea una consulta sin nombre, sobrescribiendo las consultas sin nombres previamente definidas.

`query`

  La consulta SQL con sus parámetros. Debe contener solo una sola consulta. Varios comandos separados por punto y coma no son permitidos. Si se utilizan parámetros, estos son referenciados como `$1`, `$2`, etc.

### Valores devueltos

Una instancia PgSql\Result en caso de éxito, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Ahora devuelve una instancia de PgSql\Result ; anteriormente, se devolvía un resource.
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_prepare()

    <?php
    // Conexión a una base de datos llamada "marie"
    $dbconn = pg_connect("dbname=marie");

    // Prepara una consulta para la ejecución
    $result = pg_prepare($dbconn, "my_query", 'SELECT * FROM magasins WHERE nom = $1');

    // Ejecuta la consulta preparada. Note que no es necesario escapar
    // la cadena "Joe's Widgets"
    $result = pg_execute($dbconn, "my_query", array("Joe's Widgets"));

    // Ejecuta la misma consulta preparada, esta vez con un parámetro diferente
    $result = pg_execute($dbconn, "my_query", array("Vêtements Vêtements Vêtements"));

    ?>

### Ver también

- pg_execute() - Ejecuta una consulta preparada de PostgreSQL
- pg_send_execute() - Envía una consulta para ejecutar una consulta preparada con parámetros dados, sin esperar el(los) resultado(s)

# pg_put_copy_data

(PHP 8 >= 8.4.0)

pg_put_copy_data — Envía datos al servidor durante una operación COPY

### Descripción

function pg_put_copy_data(PgSql\Connection `$connection`, string `$cmd`): int

Envía datos al servidor durante una operación `COPY FROM STDIN`. Se debe haber emitido un comando `COPY` mediante pg_query() antes de llamar a esta función.

### Parámetros

`connection`
  Una instancia PgSql\Connection.
`cmd`
  Los datos a enviar al servidor. Se añade automáticamente un salto de línea final si no está presente. Los datos deben tener el formato correspondiente al formato del comando `COPY`.

### Valores devueltos

Devuelve `1` en caso de éxito, `0` si los datos no se pudieron poner en cola (solo en modo no bloqueante), o `-1` en caso de error.

### Ver también

- pg_put_copy_end() - Indica al servidor la finalización de una operación COPY
- pg_query() - Ejecuta una consulta PostgreSQL

# pg_put_copy_end

(PHP 8 >= 8.4.0)

pg_put_copy_end — Indica al servidor la finalización de una operación COPY

### Descripción

function pg_put_copy_end(PgSql\Connection `$connection`, ?string `$error` = `null`): int

Envía una indicación de fin de datos al servidor durante una operación `COPY FROM STDIN`.

### Parámetros

`connection`
  Una instancia PgSql\Connection.
`error`
  Si no es `null`, la operación `COPY` se fuerza a fallar con el mensaje de error indicado.

### Valores devueltos

Devuelve `1` en caso de éxito, `0` si los datos no se pudieron poner en cola (solo en modo no bloqueante), o `-1` en caso de error.

### Ver también

- pg_put_copy_data() - Envía datos al servidor durante una operación COPY
- pg_query() - Ejecuta una consulta PostgreSQL

# pg_put_line

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_put_line — Envía una string al servidor PostgreSQL

### Descripción

function pg_put_line(PgSql\Connection `$connection` = ?, string `$query`): bool

pg_put_line() envía una string (terminada por `null`) al servidor PostgreSQL. Esto es necesario en conjunción con un comando `COPY FROM` de PostgreSQL.

`COPY` es una carga muy rápida de datos soportada por PostgreSQL. Los datos se pasan sin ser analizados y en una simple transacción.

Una alternativa en lugar de usar el comando bruto pg_put_line() es usar pg_copy_from(). Es una interfaz mucho más simple.

> Nota:

> Tenga en cuenta que la aplicación debe agregar explícitamente los dos caracteres "\." al final de la string para indicar al servidor que ha terminado de enviar datos, antes de llamar a pg_end_copy().

Advertencia

El uso de pg_put_line() hace que fallen la mayoría de los objetos de gran tamaño, incluyendo pg_lo_read() y pg_lo_tell(). Puede usar pg_copy_from() y pg_copy_to() en su lugar.

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` no es especificado, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

`query`

  Una línea de texto para enviar directamente al servidor PostgreSQL. Un carácter de finalización `null` se agrega automáticamente.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_put_line()

    <?php
      $conn = pg_pconnect("dbname=foo");
      pg_query($conn, "create table bar (a int4, b char(16), d float8)");
      pg_query($conn, "copy bar from stdin");
      pg_put_line($conn, "3\tBonjour le monde\t4.5\n");
      pg_put_line($conn, "4\tAurevoir le monde\t7.11\n");
      pg_put_line($conn, "\\.\n");
      pg_end_copy($conn);
    ?>

### Ver también

- pg_end_copy() - Sincroniza con el servidor PostgreSQL

# pg_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_query — Ejecuta una consulta PostgreSQL

### Descripción

function pg_query(PgSql\Connection `$connection` = ?, string `$query`): PgSql\Result|false

pg_query() ejecuta la consulta `query` en la base de datos especificada `connection`. pg_query_params() debe preferirse en la mayoría de los casos.

Si ocurre un error y se devuelve `false`, los detalles del error pueden recuperarse utilizando la función pg_last_error() si la conexión es válida.

> Nota: Aunque `connection` puede omitirse, no se recomienda hacerlo, ya que puede resultar difícil encontrar errores en los scripts.

> Nota:

> Anteriormente, esta función se llamaba pg_exec(). pg_exec() sigue disponible por razones de compatibilidad, pero se recomienda a los usuarios utilizar el nuevo nombre.

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` no es especificado, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

`query`

  La consulta o consultas SQL a ejecutarse. Cuando se pasan varias consultas a la función, se ejecutan automáticamente como una transacción, a menos que se incluyan los comandos BEGIN/COMMIT en la consulta. Sin embargo, no se recomienda el uso de múltiples transacciones en una sola llamada de función.

  Advertencia

  La interpolación de strings proporcionados por el usuario es extremadamente peligrosa y debe tenerse en cuenta el conjunto de vulnerabilidades relacionadas con las inyecciones SQL. En la mayoría de los casos, debe preferirse la función pg_query_params(); es preferible pasar los valores proporcionados por el usuario como argumentos, en lugar de sustituirlos en la consulta.

  Todos los datos de usuario sustituidos directamente en el string de la consulta deben ser propiamente escapados.

### Valores devueltos

Una instancia PgSql\Result en caso de éxito, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Ahora devuelve una instancia de PgSql\Result ; anteriormente, se devolvía un resource.
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_query()

    <?php

    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Ocurrió un error.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT autor, email FROM autores");
    if (!$result) {
      echo "Ocurrió un error.\n";
      exit;
    }

    while ($row = pg_fetch_row($result)) {
      echo "Autor: $row[0]  E-mail: $row[1]";
      echo "<br />\n";
    }

    ?>

Ejemplo #2 Uso de pg_query() con múltiples consultas

    <?php

    $conn = pg_pconnect("dbname=publisher");

    // estas consultas se ejecutarán como una sola transacción

    $query = "UPDATE authors SET author=UPPER(author) WHERE id=1;";
    $query .= "UPDATE authors SET author=LOWER(author) WHERE id=2;";
    $query .= "UPDATE authors SET author=NULL WHERE id=3;";

    pg_query($conn, $query);

    ?>

### Ver también

- pg_connect() - Establece una conexión PostgreSQL
- pg_pconnect() - Establece una conexión PostgreSQL persistente
- pg_fetch_array() - Lee una línea de resultado PostgreSQL en un array
- pg_fetch_object() - Lee una fila de resultado PostgreSQL en un objeto
- pg_num_rows() - Devuelve el número de filas de PostgreSQL
- pg_affected_rows() - Devuelve el número de filas afectadas

# pg_query_params

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_query_params — Envía un comando al servidor y espera el resultado, con la capacidad de pasar parámetros por separado del texto SQL de la consulta

### Descripción

function pg_query_params(PgSql\Connection `$connection` = ?, string `$query`, array `$params`): PgSql\Result|false

Envía un comando al servidor y espera el resultado, con la capacidad de pasar parámetros por separado del texto SQL de la consulta.

pg_query_params() es como pg_query(), pero ofrece funcionalidades adicionales: los valores de los parámetros pueden especificarse por separado de la línea de comando propia.

Si se utilizan parámetros, se refieren a $1, $2, etc. en `query`. El mismo parámetro puede aparecer más de una vez en la consulta `query`; se utilizará el mismo valor en ese caso. `params` especifica los valores actuales de los parámetros. Un valor `null` en este array significa que el parámetro correspondiente es SQL `null`.

La principal ventaja de pg_query_params() sobre pg_query() es que los valores de los parámetros pueden separarse de la consulta `query`, por lo tanto, se evitan los escapes de caracteres tediosos y propensos a errores. A diferencia de pg_query(), pg_query_params() permite solo un comando SQL en la cadena dada. (Puede haber puntos y coma en el interior pero no más de un comando.)

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` no es especificado, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

`query`

  La consulta SQL con sus parámetros. Debe contener solo una consulta. Múltiples consultas separadas por puntos y coma no están permitidas. Si se utilizan parámetros, se refieren a $1, $2, etc.

  Los valores proporcionados por el usuario siempre deben pasarse como parámetros, y no interpolados en la cadena de consulta, donde pueden potencialmente formar inyecciones SQL e introducir errores cuando estos datos contienen comillas. Si por alguna razón no se pueden utilizar parámetros, asegúrese de que los valores interpolados estén correctamente escapados.

`params`

  Un array de valores de parámetros para sustituir las variables $1, $2, etc. en la consulta preparada original. El número de elementos presentes en el array debe coincidir con el número de variables a reemplazar.

  Los valores esperados para los campos `bytea` no son soportados como parámetros. Utilice en su lugar la función pg_escape_bytea() o utilice las funciones sobre los objetos grandes.

### Valores devueltos

Una instancia PgSql\Result en caso de éxito, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Ahora devuelve una instancia de PgSql\Result ; anteriormente, se devolvía un resource.
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_query_params()

    <?php
    // Conexión a una base de datos llamada "marie"
    $dbconn = pg_connect("dbname=marie");

    // Busca todas las tiendas llamadas Joe's Widgets. Note que no es
    // necesario escapar la cadena "Joe's Widgets"
    $result = pg_query_params($dbconn, 'SELECT * FROM tiendas WHERE nombre = $1', array("Joe's Widgets"));

    // Comparación usando pg_query
    $str = pg_escape_string("Joe's Widgets");
    $result = pg_query($dbconn, "SELECT * FROM tiendas WHERE nombre = '{$str}'");

    ?>

### Ver también

- pg_query() - Ejecuta una consulta PostgreSQL

# pg_result_error

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_result_error — Lee el mensaje de error asociado a un resultado

### Descripción

function pg_result_error(PgSql\Result `$result`): string|false

pg_result_error() devuelve el mensaje de error asociado al resultado `result`. Por consiguiente, es probable que se obtenga un mensaje de error más apropiado que mediante pg_last_error().

La función pg_result_error_field() puede proporcionar muchos más detalles sobre los errores que pg_result_error().

Dado que pg_query() devuelve `false` si la consulta falla, se debe utilizar pg_send_query() y pg_get_result() para recuperar el recurso de resultado.

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).

### Valores devueltos

Devuelve un string. Devuelve una cadena vacía si no hay ningún error. Si hay un error asociado con el parámetro `result`, se devolverá `false`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_result_error()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Conexión imposible");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from nexistepas;");
      }

      $res1 = pg_get_result($dbconn);
      echo pg_result_error($res1);
    ?>

### Ver también

- pg_result_error_field() - Devuelve un campo individual de un informe de error
- pg_query() - Ejecuta una consulta PostgreSQL
- pg_send_query() - Ejecuta una consulta PostgreSQL asíncrona
- pg_get_result() - Lee un resultado asíncrono de PostgreSQL
- pg_last_error() - Lee el último mensaje de error en la conexión
- pg_last_notice() - Devuelve la última nota del servidor PostgreSQL

# pg_result_error_field

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_result_error_field — Devuelve un campo individual de un informe de error

### Descripción

function pg_result_error_field(PgSql\Result `$result`, int `$field_code`): string|false|null

pg_result_error_field() devuelve uno de los campos detallados del mensaje de error asociados al recurso `result`. El campo de error se especifica mediante `field_code`.

Dado que pg_query() y pg_query_params() devuelven `false` si la consulta falla, se debe utilizar pg_send_query() y pg_get_result() para obtener el conjunto de resultados.

Si se necesita obtener más información sobre el error al fallar las consultas con pg_query(), se debe utilizar pg_set_error_verbosity() y pg_last_error() y analizar posteriormente el resultado.

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).
`field_code`

  Los valores posibles de `field_code` son: `PGSQL_DIAG_SEVERITY`, `PGSQL_DIAG_SQLSTATE`, `PGSQL_DIAG_MESSAGE_PRIMARY`, `PGSQL_DIAG_MESSAGE_DETAIL`, `PGSQL_DIAG_MESSAGE_HINT`, `PGSQL_DIAG_STATEMENT_POSITION`, `PGSQL_DIAG_INTERNAL_POSITION`, `PGSQL_DIAG_INTERNAL_QUERY`, `PGSQL_DIAG_CONTEXT`, `PGSQL_DIAG_SOURCE_FILE`, `PGSQL_DIAG_SOURCE_LINE` o `PGSQL_DIAG_SOURCE_FUNCTION`.

### Valores devueltos

Devuelve una string que contiene el contenido del campo de error, `null` si el campo no existe o `false` en caso de fallo.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_result_error_field()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Conexión imposible");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from nexistepas;");
      }

      $res1 = pg_get_result($dbconn);
      echo pg_result_error_field($res1, PGSQL_DIAG_SQLSTATE);
    ?>

### Ver también

- pg_result_error() - Lee el mensaje de error asociado a un resultado

# pg_result_memory_size

(PHP 8 >= 8.4.0)

pg_result_memory_size — Devuelve la cantidad de memoria asignada para un resultado de consulta

### Descripción

function pg_result_memory_size(PgSql\Result `$result`): int

Devuelve la cantidad de memoria, en bytes, asignada para la instancia de PgSql\Result especificada. Este valor es el mismo que el que sería liberado por pg_free_result().

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).

### Valores devueltos

Devuelve la cantidad de memoria en bytes.

### Ejemplos

Ejemplo #1 Ejemplo de pg_result_memory_size()

    <?php
    $db = pg_connect("dbname=users user=me");

    $res = pg_query($db, 'SELECT 1');

    $size = pg_result_memory_size($res);

    var_dump($size);
    ?>

Resultado del ejemplo anterior es similar a:

    int(3288)

### Ver también

- pg_free_result() - Libera la memoria

# pg_result_seek

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_result_seek — Establece la posición de la línea en un resultado

### Descripción

function pg_result_seek(PgSql\Result `$result`, int `$row`): bool

pg_result_seek() selecciona la línea `offset` como línea actual en el resultado `result`.

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).
`row`

  Línea a la que se moverá la posición interna en la instancia de PgSql\Result. Las líneas están numeradas a partir de cero.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_result_seek()

    <?php

    // Conexión a la base de datos
    $conn = pg_pconnect("dbname=publisher");

    // Ejecución de la consulta
    $result = pg_query($conn, "SELECT autor, email FROM autores");

    // Desplazamiento a la tercera línea (se asume que hay 3 líneas)
    pg_result_seek($result, 2);

    // Obtención de la tercera línea
    $row = pg_fetch_row($result);

    ?>

### Ver también

- pg_fetch_row() - Lee una fila en un array
- pg_fetch_assoc() - Lee una fila de resultado PostgreSQL como un array asociativo
- pg_fetch_array() - Lee una línea de resultado PostgreSQL en un array
- pg_fetch_object() - Lee una fila de resultado PostgreSQL en un objeto
- pg_fetch_result() - Devuelve los valores de un resultado

# pg_result_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_result_status — Lee el estado del resultado

### Descripción

function pg_result_status(PgSql\Result `$result`, int `$mode` = `PGSQL_STATUS_LONG`): string|int

pg_result_status() devuelve el estado de la instancia de PgSql\Result, o la etiqueta de comando PostgreSQL asociada al resultado.

### Parámetros

`result`
  Una instancia PgSql\Result, devuelta por pg_query(), pg_query_params(), o pg_execute() (entre otros).
`mode`

  Puede ser `PGSQL_STATUS_LONG` para devolver un estado numérico de `result` o `PGSQL_STATUS_STRING` para devolver la etiqueta del comando de `result`. Si el argumento no se especifica, `PGSQL_STATUS_LONG` es el valor por omisión.

### Valores devueltos

Los valores de retorno posibles son `PGSQL_EMPTY_QUERY`, `PGSQL_COMMAND_OK`, `PGSQL_TUPLES_OK`, `PGSQL_TUPLES_CHUNK`, `PGSQL_COPY_OUT`, `PGSQL_COPY_IN`, `PGSQL_BAD_RESPONSE`, `PGSQL_NONFATAL_ERROR` y `PGSQL_FATAL_ERROR` si `PGSQL_STATUS_LONG` se especifica. De lo contrario, se devuelve un string que contiene la etiqueta del comando PostgreSQL.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `result` ahora espera una instancia de PgSql\Result ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_result_status()

    <?php

    // Conexión a la base de datos
    $conn = pg_pconnect("dbname=publisher");

    // Ejecución de COPY
    $result = pg_query($conn, "COPY autores FROM STDIN;");

    // Obtención del estado
    $status = pg_result_status($result);

    // Determinación del estado
    if ($status == PGSQL_COPY_IN)
       echo "La copia se ha realizado.";
    else
       echo "La copia ha fallado.";

    ?>

El ejemplo anterior mostrará:

    La copia se ha realizado.

### Ver también

- pg_connection_status() - Se lee el estado de la conexión PostgreSQL

# pg_select

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_select — Realiza una selección PostgreSQL

### Descripción

function pg_select(
PgSql\Connection `$connection`,
string `$table_name`,
array `$conditions` = [],
int `$flags` = `PGSQL_DML_EXEC`,
int `$mode` = `PGSQL_ASSOC`
): array|string|false

pg_select() selecciona los registros por `conditions` que está en formato `campo=>valor`. Cuando la consulta tiene éxito, devuelve un array que contiene todos los registros y campos que cumplen la condición especificada por `conditions`.

Si `flags` está especificado, pg_convert() se aplica a `values` con los flags proporcionados.

Si el parámetro `mode` está definido, el valor de retorno será en forma de un array indexado con `PGSQL_NUM`, un array asociativo con `PGSQL_ASSOC` (por defecto), o ambos con `PGSQL_BOTH`.

Por defecto pg_delete() pasa valores sin tratar. Los valores deben ser escapados o la opción PGSQL_DML_ESCAPE debe ser proporcionada. PGSQL_DML_ESCAPE pone comillas y escapa los parámetros/identificadores. Por lo tanto, los nombres de tabla/columnas deben ser sensibles a mayúsculas y minúsculas.

Tenga en cuenta que ni el escape ni las consultas preparadas pueden proteger de consultas LIKE, JSON, Arrays, Regex, etc. Estos parámetros deberían ser tratados según su contexto. Es decir, escapar/validar los valores.

### Parámetros

`connection`
  Una instancia PgSql\Connection.
`table_name`

  Nombre de la tabla desde la cual seleccionar las filas.

`conditions`

  Un array cuyas claves son los nombres de los campos en la tabla `table_name`, y cuyos valores son las condiciones que una fila debe cumplir para ser recuperada. A partir de PHP 8.4.0, cuando se proporciona un array vacío, no se aplicará ninguna condición. Anteriormente, la función fallaba con un argumento `conditions` vacío.

`flags`

  Cualquier número de `PGSQL_CONV_FORCE_NULL`, `PGSQL_DML_NO_CONV`, `PGSQL_DML_ESCAPE`, `PGSQL_DML_EXEC`, `PGSQL_DML_ASYNC` o `PGSQL_DML_STRING` combinados. Si `PGSQL_DML_STRING` forma parte de los `flags`, entonces se devuelve la cadena de consulta. Cuando `PGSQL_DML_NO_CONV` o `PGSQL_DML_ESCAPE` está activado, pg_convert() no es llamado internamente.

`mode`

  Cualquier número de `PGSQL_ASSOC`, `PGSQL_NUM` o `PGSQL_BOTH`. Si `PGSQL_ASSOC` está definido, el valor de retorno será un array asociativo, con `PGSQL_NUM`, el valor de retorno será un array indexado numéricamente, y con `PGSQL_BOTH`, el valor de retorno será tanto un array asociativo como numéricamente indexado.

### Valores devueltos

Devuelve un string si `PGSQL_DML_STRING` es proporcionado a través de `flags`, de lo contrario esto devuelve un array en caso de éxito, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `conditions` ahora es opcional.
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.
7.1.0 | El parámetro `mode` ha sido añadido.

### Ejemplos

Ejemplo #1 Ejemplo con pg_select()

    <?php
      $db = pg_connect ('dbname=foo');
      // Esto es seguro en cierta medida, ya que todos los valores están escapados
      // Sin embargo PostgreSQL soporta JSON/Arrays. Estos no son
      // seguros ni por escape ni por consultas preparadas.
      $rec = pg_select($db, 'post_log', $_POST, PG_DML_ESCAPE);
      if ($rec) {
        echo "Filas leídas\n";
        var_dump($rec);
      } else {
        echo "Problema en los datos de usuario\n";
      }
    ?>

### Ver también

- pg_convert() - Convierte valores de un array asociativo a una forma adecuada para consultas SQL

# pg_send_execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_execute — Envía una consulta para ejecutar una consulta preparada con parámetros dados, sin esperar el(los) resultado(s)

### Descripción

function pg_send_execute(PgSql\Connection `$connection`, string `$statement_name`, array `$params`): int|bool

Envía una consulta para ejecutar una consulta preparada con parámetros dados, sin esperar el(los) resultado(s).

Esta función es similar a pg_send_query_params(), pero el comando que se ejecutará se especifica nombrando una consulta previamente preparada, en lugar de proporcionar un string como consulta. Los parámetros de la función se gestionan de la misma manera que pg_execute(). Al igual que pg_execute(), la función no funcionará en versiones anteriores a PostgreSQL 7.4.

### Parámetros

`connection`
  Una instancia PgSql\Connection.
`statement_name`

  El nombre de la consulta preparada a ejecutar. Si se especifica un string vacío (""), entonces se ejecuta la consulta sin nombre. El nombre debe haber sido previamente preparado utilizando pg_prepare(), pg_send_prepare() o un comando SQL `PREPARE`.

`params`

  Un array de valores de parámetros para sustituir las variables $1, $2, etc. en la consulta preparada original. El número de elementos presentes en el array debe coincidir con el número de variables a reemplazar.

### Valores devueltos

Devuelve `true` en caso de éxito, `false` o `0` en caso de fallo. Utilice pg_get_result() para determinar el resultado de la consulta.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_send_execute()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Conexión imposible");

      // Prepara una consulta para la ejecución
      if (!pg_connection_busy($dbconn)) {
        pg_send_prepare($dbconn, "my_query", 'SELECT * FROM tiendas WHERE nombre = $1');
        $res1 = pg_get_result($dbconn);
      }

      // Ejecuta la consulta preparada. Observe que no es necesario escapar el string "Joe's Widgets"
      if (!pg_connection_busy($dbconn)) {
        pg_send_execute($dbconn, "my_query", array("Joe's Widgets"));
        $res2 = pg_get_result($dbconn);
      }

      // Ejecuta la misma consulta preparada, esta vez con un parámetro diferente
      if (!pg_connection_busy($dbconn)) {
        pg_execute($dbconn, "my_query", array("Ropa Ropa Ropa"));
        $res3 = pg_get_result($dbconn);
      }

    ?>

### Ver también

- pg_prepare() - Envía una solicitud al servidor para crear una sentencia preparada con los parámetros dados y espera la ejecución
- pg_send_prepare() - Envía una solicitud para crear una consulta preparada con los argumentos dados, sin esperar el final de su ejecución
- pg_execute() - Ejecuta una consulta preparada de PostgreSQL

# pg_send_prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_prepare — Envía una solicitud para crear una consulta preparada con los argumentos dados, sin esperar el final de su ejecución

### Descripción

function pg_send_prepare(PgSql\Connection `$connection`, string `$statement_name`, string `$query`): int|bool

Envía una solicitud para crear una consulta preparada con los argumentos dados, sin esperar el final de su ejecución.

Esta función es la versión asíncrona de pg_prepare() : devuelve `true` si ha sido capaz de distribuir la consulta y `false` si no ha sido capaz. Tras una llamada exitosa, llame a pg_get_result() para determinar si el servidor ha creado correctamente la consulta preparada. Los argumentos de la función son gestionados de la misma manera que pg_execute(). Al igual que pg_execute(), la función no funcionará en versiones anteriores a PostgreSQL 7.4.

### Parámetros

`connection`
  Una instancia PgSql\Connection.
`statement_name`

  El nombre a dar a la consulta preparada. Debe ser único en cada sesión. Si se especifica una cadena vacía ("") entonces se crea una consulta sin nombre, sobrescribiendo las consultas sin nombre previamente definidas.

`query`

  La consulta SQL con sus argumentos. Debe contener solo una consulta. No se permiten múltiples consultas separadas por punto y coma. Si se utilizan argumentos, se refieren a $1, $2, etc.

### Valores devueltos

Devuelve `true` en caso de éxito, `false` o `0` en caso de error. Utilice pg_get_result() para determinar el resultado de la consulta.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo pg_send_prepare()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Conexión imposible");

      // Prepara una consulta para la ejecución
      if (!pg_connection_busy($dbconn)) {
        pg_send_prepare($dbconn, "my_query", 'SELECT * FROM magasins WHERE nom = $1');
        $res1 = pg_get_result($dbconn);
      }

      // Ejecuta la consulta preparada. Note que no es necesario escapar
      // la cadena "Joe's Widgets"
      if (!pg_connection_busy($dbconn)) {
        pg_send_execute($dbconn, "my_query", array("Joe's Widgets"));
        $res2 = pg_get_result($dbconn);
      }

      // Ejecuta la misma consulta preparada, esta vez con un argumento diferente
      if (!pg_connection_busy($dbconn)) {
        pg_send_execute($dbconn, "my_query", array("Vêtements Vêtements Vêtements"));
        $res3 = pg_get_result($dbconn);
      }

    ?>

### Ver también

- pg_connect() - Establece una conexión PostgreSQL
- pg_pconnect() - Establece una conexión PostgreSQL persistente
- pg_execute() - Ejecuta una consulta preparada de PostgreSQL
- pg_send_execute() - Envía una consulta para ejecutar una consulta preparada con parámetros dados, sin esperar el(los) resultado(s)
- pg_send_query_params() - Envía un comando y separa los parámetros al servidor sin esperar el/los resultado(s)

# pg_send_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_send_query — Ejecuta una consulta PostgreSQL asíncrona

### Descripción

function pg_send_query(PgSql\Connection `$connection`, string `$query`): int|bool

pg_send_query() envía una consulta o varias consultas de manera asíncrona a la conexión `connection`. A diferencia de pg_query(), puede enviar varias consultas al mismo tiempo al servidor PostgreSQL y obtener los resultados uno por uno utilizando pg_get_result().

La ejecución del script no se bloquea durante la ejecución de las consultas. Se puede utilizar pg_connection_busy() para verificar si la conexión está ocupada (es decir, si la consulta se está ejecutando). Las consultas pueden ser canceladas con pg_cancel_query().

Aunque se puedan enviar varias consultas al mismo tiempo, no es posible enviar varias consultas en una conexión ocupada. Si se envía una consulta cuando la conexión está ocupada, esperará a que la consulta anterior termine y perderá todos sus resultados.

### Parámetros

`connection`
  Una instancia PgSql\Connection.
`query`

  La consulta o las consultas SQL a ser ejecutadas.

  Los datos contenidos en la consulta deben ser escaped correctamente.

### Valores devueltos

Devuelve `true` en caso de éxito, `false` o `0` en caso de fallo. Utilice pg_get_result() para determinar el resultado de la consulta.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_send_query()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Conexión imposible");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn,"select * from autores; select count(*) from autores;");
      }

      $res1 = pg_get_result($dbconn);
      echo "Primera llamada a pg_get_result() : $res1\n";
      $rows1 = pg_num_rows($res1);
      echo "$res1 tiene $rows1 registros\n\n";

      $res2 = pg_get_result($dbconn);
      echo "Segunda llamada a pg_get_result() : $res2\n";
      $rows2 = pg_num_rows($res2);
      echo "$res2 tiene $rows2 registros\n";
    ?>

El ejemplo anterior mostrará:

    Primera llamada a pg_get_result() : Resource id #3
    Resource id #3 tiene 3 registros

    Segunda llamada a pg_get_result() : Resource id #4
    Resource id #4 tiene 1 registros

### Ver también

- pg_query() - Ejecuta una consulta PostgreSQL
- pg_cancel_query() - Cancela una consulta asíncrona
- pg_get_result() - Lee un resultado asíncrono de PostgreSQL
- pg_connection_busy() - Verifica si la conexión PostgreSQL está ocupada

# pg_send_query_params

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_query_params — Envía un comando y separa los parámetros al servidor sin esperar el/los resultado(s)

### Descripción

function pg_send_query_params(PgSql\Connection `$connection`, string `$query`, array `$params`): int|bool

Envía un comando y separa los parámetros al servidor sin esperar el/los resultado(s).

Esta función es equivalente a pg_send_query() con la excepción de que los parámetros de la consulta pueden especificarse por separado de la cadena de consulta `query`. Los parámetros de la función se gestionan de la misma manera que pg_execute(). Como pg_execute(), la función no funcionará en versiones anteriores a PostgreSQL 7.4 y solo permite un comando por consulta.

### Parámetros

`connection`
  Una instancia PgSql\Connection.
`query`

  La consulta SQL con sus parámetros. Debe contener solo una consulta. No se permiten múltiples consultas separadas por punto y coma. Si se utilizan parámetros, se hace referencia a ellos como $1, $2, etc.

`params`

  Un array de valores de parámetros para sustituir las variables $1, $2, etc. en la consulta preparada original. El número de elementos en el array debe coincidir con el número de variables a reemplazar.

### Valores devueltos

Devuelve `true` en caso de éxito, `false` o `0` en caso de fallo. Utilice pg_get_result() para determinar el resultado de la consulta.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_send_query_params()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Conexión imposible");

      // Con parámetros. Tenga en cuenta que no es necesario escapar la cadena del parámetro.
      pg_send_query_params($dbconn, 'select count(*) from autores where ciudad = $1', array('Perth'));

      // Comparar con el uso básico de pg_send_query
      $str = pg_escape_string('Perth');
      pg_send_query($dbconn, "select count(*) from autores where ciudad = '{$str}'");
    ?>

### Ver también

- pg_send_query() - Ejecuta una consulta PostgreSQL asíncrona

# pg_set_chunked_rows_size

(PHP 8 >= 8.4.0)

pg_set_chunked_rows_size — Establece los resultados de la consulta a recuperar en modo chunk

### Descripción

function pg_set_chunked_rows_size(PgSql\Connection `$connection`, int `$size`): bool

Establece los resultados de la consulta a recuperar en modo chunk. La consulta devuelta posteriormente se dividirá en varios fragmentos, cada uno conteniendo hasta `size` filas. Esta función debe ser llamada antes de recuperar los resultados con pg_get_result(). Esta función solo está disponible cuando libpq está en versión 17 o superior.

### Parámetros

`connection`
  Una instancia PgSql\Connection.
`size`
  El número de filas a recuperar en cada fragmento.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Si `size` es inferior a `1`, se lanzará un ValueError.

### Ejemplos

Ejemplo #1 Ejemplo de pg_result_memory_size()

    <?php

    $conn = pg_connect($conn_str);

    for ($i = 0; $i < 10; $i ++) {
      pg_query($conn, "INSERT INTO users DEFAULT VALUES");
    }

    pg_send_query($conn, "SELECT * FROM users");
    pg_set_chunked_rows_size($conn, 1);

    $result = pg_get_result($conn);
    var_dump(pg_num_rows($result));

    :: Sin efecto después de que el resultado sea recuperado
    var_dump(pg_set_chunked_rows_size($conn, 10));

El ejemplo anterior mostrará:

    int(1)
    bool(false)

### Ver también

- pg_get_result() - Lee un resultado asíncrono de PostgreSQL
- pg_result_status() - Lee el estado del resultado

# pg_set_client_encoding

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_set_client_encoding — Establece la codificación del cliente PostgreSQL

### Descripción

function pg_set_client_encoding(PgSql\Connection `$connection` = ?, string `$encoding`): int

pg_set_client_encoding() establece la codificación del cliente. Devuelve 0 en caso de éxito y -1 en caso de error.

PostgreSQL convertirá automáticamente los datos de la codificación de la base de datos a la codificación del cliente.

> Nota:

> Anteriormente, esta función se llamaba pg_setclientencoding().

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` no es especificado, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

`encoding`

  La codificación del cliente solicitada. Una de estas constantes: `SQL_ASCII`, `EUC_JP`, `EUC_CN`, `EUC_KR`, `EUC_TW`, `UNICODE`, `MULE_INTERNAL`, `LATINX` (X=1...9), `KOI8`, `WIN`, `ALT`, `SJIS`, `BIG5` o `WIN1250`.

  La lista exacta de codificaciones disponibles depende de la versión de PostgreSQL, por lo que se debe consultar el manual de PostgreSQL para obtener una lista más específica.

### Valores devueltos

Devuelve `0` en caso de éxito o `-1` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_set_client_encoding()

    <?php

    $conn = pg_pconnect("dbname=editeur");
    if (!$conn) {
      echo "Se ha producido un error.\n";
      exit;
    }

    // Establece la codificación del cliente a UNICODE. Los datos se convertirán automáticamente
    // de la codificación del servidor a la codificación del cliente.
    pg_set_client_encoding($conn, "UNICODE");

    $result = pg_query($conn, "SELECT autor, email FROM autores");
    if (!$result) {
      echo "Se ha producido un error.\n";
      exit;
    }

    // Escritura de datos UTF-8
    while ($row = pg_fetch_row($result)) {
      echo "Autor: $row[0]  E-mail: $row[1]";
      echo "<br />\n";
    }

    ?>

### Ver también

- pg_client_encoding() - Lee la codificación del cliente

# pg_set_error_context_visibility

(PHP 8 >= 8.3.0)

pg_set_error_context_visibility — Determina la visibilidad de los mensajes de error de contexto devueltos por pg_last_error() y pg_result_error()

### Descripción

function pg_set_error_context_visibility(PgSql\Connection `$connection`, int `$visibility`): int

Determina la visibilidad de los mensajes de error de contexto devueltos por pg_last_error() y pg_result_error()

### Parámetros

`connection`
  Una instancia PgSql\Connection.
`visibility`

  La visibilidad requerida: `PGSQL_SHOW_CONTEXT_NEVER`, `PGSQL_SHOW_CONTEXT_ERRORS` o `PGSQL_SHOW_CONTEXT_ALWAYS`.

### Valores devueltos

El nivel de visibilidad anterior: `PGSQL_SHOW_CONTEXT_NEVER`, `PGSQL_SHOW_CONTEXT_ERRORS` o `PGSQL_SHOW_CONTEXT_ALWAYS`.

### Ejemplos

Ejemplo #1 Ejemplo de pg_set_error_context_visibility()

    <?php
          $dbconn = pg_connect("dbname=publisher") or die("No se puede conectar");
          if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from doesnotexist;");
          }
          pg_set_error_context_visibility($dbconn, PGSQL_SHOW_CONTEXT_ALWAYS);
          $res1 = pg_get_result($dbconn);
          echo pg_result_error($res1);
          ?>

### Ver también

- pg_last_error() - Lee el último mensaje de error en la conexión
- pg_result_error() - Lee el mensaje de error asociado a un resultado

# pg_set_error_verbosity

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_set_error_verbosity — Determina el nivel de detalle de los mensajes devueltos por pg_last_error() y pg_result_error()

### Descripción

function pg_set_error_verbosity(PgSql\Connection `$connection` = ?, int `$verbosity`): int|false

Determina el nivel de detalle de los mensajes devueltos por pg_last_error() y pg_result_error().

pg_set_error_verbosity() establece el nivel de detalle de los errores y devuelve el parámetro anterior de la conexión. Con el modo `PGSQL_ERRORS_TERSE`, los mensajes devueltos incluyen la severidad, el texto principal y la posición solamente; normalmente, esto cabrá en una sola línea. El modo por defecto (`PGSQL_ERRORS_DEFAULT`) produce mensajes que incluyen los mensajes anteriores y detalles, sugerencias o campos contextuales (estos mensajes pueden extenderse en varias líneas). El modo `PGSQL_ERRORS_VERBOSE` incluye todos los campos disponibles. El cambio del nivel de detalle de los mensajes no afecta a los mensajes disponibles que provienen de resultados ya existentes, sino solo a los mensajes de los resultados creados posteriormente.

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` no es especificado, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

`verbosity`

  El nivel de detalle del mensaje de error: `PGSQL_ERRORS_TERSE`, `PGSQL_ERRORS_DEFAULT` o `PGSQL_ERRORS_VERBOSE`.

### Valores devueltos

El nivel de detalle del mensaje de error anterior: `PGSQL_ERRORS_TERSE`, `PGSQL_ERRORS_DEFAULT` o `PGSQL_ERRORS_VERBOSE`, o `false` en caso de fallo.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_set_error_verbosity()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Conexión imposible");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from nexistepas;");
      }

      pg_set_error_verbosity($dbconn, PGSQL_ERRORS_VERBOSE);
      $res1 = pg_get_result($dbconn);
      echo pg_result_error($res1);
    ?>

### Ver también

- pg_last_error() - Lee el último mensaje de error en la conexión
- pg_result_error() - Lee el mensaje de error asociado a un resultado

# pg_socket

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_socket — Obtiene un manejador de solo lectura sobre el socket subyacente de una conexión PostgreSQL

### Descripción

function pg_socket(PgSql\Connection `$connection`): resource|false

pg_socket() devuelve un resource de solo lectura correspondiente al socket subyacente de la conexión PostgreSQL proporcionada.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`connection`
  Una instancia PgSql\Connection.

### Valores devueltos

Un recurso de socket en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

# pg_socket_poll

(PHP 8 >= 8.4.0)

pg_socket_poll — Sondea un socket de conexión PostgreSQL para comprobar si está listo para lectura/escritura

### Descripción

function pg_socket_poll(
resource `$socket`,
int `$read`,
int `$write`,
int `$timeout` = -1
): int

Sondea un socket de conexión PostgreSQL para comprobar si está listo para lectura y/o escritura. El socket puede obtenerse mediante pg_socket(). Esta función es útil para implementar flujos de trabajo de consultas no bloqueantes y asíncronos.

### Parámetros

`socket`
  Un recurso de socket obtenido de pg_socket().
`read`
  Indica si se debe comprobar si está listo para lectura. Pase `1` para comprobarlo, `0` para omitirlo.
`write`
  Indica si se debe comprobar si está listo para escritura. Pase `1` para comprobarlo, `0` para omitirlo.
`timeout`
  El número máximo de milisegundos a esperar. Pase `-1` para esperar indefinidamente, o `0` para no esperar en absoluto.

### Valores devueltos

Devuelve un valor positivo si el socket está listo, `0` si se alcanzó el tiempo de espera, o `-1` en caso de error.

### Ver también

- pg_socket() - Obtiene un manejador de solo lectura sobre el socket subyacente de una conexión PostgreSQL
- pg_consume_input() - Lee la entrada de la conexión
- pg_send_query() - Ejecuta una consulta PostgreSQL asíncrona

# pg_trace

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

pg_trace — Activa el seguimiento de una conexión PostgreSQL

### Descripción

function pg_trace(
string `$filename`,
string `$mode` = "w",
?PgSql\Connection `$connection` = `null`,
int `$trace_mode` = 0
): bool

pg_trace() activa el seguimiento de las comunicaciones entre PHP y el servidor PostgreSQL. Este historial se registrará en un fichero. Para comprender estas líneas, es necesario estar familiarizado con el protocolo de comunicación interno de PostgreSQL.

Para quienes no lo estén, pueden ser útiles para seguir las consultas y los errores: con el comando grep '^To backend' trace.log, se podrán ver las consultas realmente enviadas al servidor PostgreSQL. Para más información, consulte la » Documentación PostgreSQL.

### Parámetros

`filename`

  La ruta completa y el nombre del fichero en el que se registrará el seguimiento. Como fopen().

`mode`

  El modo de acceso opcional, como fopen().

`connection`

  Una instancia PgSql\Connection. Cuando `connection` es `null`, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

`trace_mode`

  Un modo de seguimiento opcional con las constantes siguientes: `PGSQL_TRACE_SUPPRESS_TIMESTAMPS` y `PGSQL_TRACE_REGRESS_MODE`

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | `trace_mode` ha sido añadido.
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.
8.0.0 | `connection` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con pg_trace()

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       pg_trace('/tmp/trace.log', 'w', $pgsql_conn);
       pg_query("SELECT 1");
       pg_untrace($pgsql_conn);
       // Ahora /tmp/trace.log contendrá el seguimiento de las comunicaciones
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

### Ver también

- fopen() - Abre un fichero o un URL
- pg_untrace() - Finaliza el seguimiento de una conexión PostgreSQL

# pg_transaction_status

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_transaction_status — Retorna el estado de la transacción en curso del servidor

### Descripción

function pg_transaction_status(PgSql\Connection `$connection`): int

Retorna el estado de la transacción en curso del servidor.

Precaución

pg_transaction_status() proporcionará resultados incorrectos cuando se utilice con un servidor PostgreSQL 7.3 que tenga el parámetro `autocommit` desactivado. La funcionalidad de autocommit está obsoleta y ya no existe en las versiones más recientes del servidor.

### Parámetros

`connection`
  Una instancia PgSql\Connection.

### Valores devueltos

El estado puede ser `PGSQL_TRANSACTION_IDLE` (actualmente inactivo), `PGSQL_TRANSACTION_ACTIVE` (una orden está en curso), `PGSQL_TRANSACTION_INTRANS` (inactivo, dentro de un bloque de transacción válido), o `PGSQL_TRANSACTION_INERROR` (inactivo, dentro de un bloque de transacción fallido). `PGSQL_TRANSACTION_UNKNOWN` se retorna si la conexión es incorrecta. `PGSQL_TRANSACTION_ACTIVE` se retorna solo si la consulta ha sido enviada al servidor y esta aún no ha sido completada.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_transaction_status()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Conexión imposible");
      $stat = pg_transaction_status($dbconn);
      if ($stat === PGSQL_TRANSACTION_UNKNOWN) {
          echo 'Conexión incorrecta';
      } else if ($stat === PGSQL_TRANSACTION_IDLE) {
          echo 'Conexión actualmente inactiva';
      } else {
          echo 'Conexión está en curso de transacción';
      }
    ?>

# pg_tty

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_tty — Devuelve el nombre de TTY asociado a la conexión

### Descripción

function pg_tty(?PgSql\Connection `$connection` = `null`): string

pg_tty() devuelve el nombre de TTY de la conexión asociada a `connection`.

> Nota:

> pg_tty() está obsoleto, ya que el servidor no presta atención a la configuración TTY, pero se mantiene por razones de compatibilidad.

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` es `null`, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

### Valores devueltos

Una string que contiene el depurador TTY de la conexión `connection`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.
8.0.0 | `connection` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con pg_tty()

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       print "Depurador TTY del servidor es: " . pg_tty($pgsql_conn) . "<br/>\n";
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

# pg_unescape_bytea

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_unescape_bytea — Elimina la protección de una cadena de tipo bytea

### Descripción

function pg_unescape_bytea(string `$string`): string

pg_unescape_bytea() elimina la protección de los caracteres de tipo bytea. Devuelve el string protegido, que puede contener datos binarios.

> Nota:

> Al utilizar una sentencia `SELECT` con datos de tipo bytea, PostgreSQL devuelve valores octales, precedidos por barras invertidas \ (p. ej. \032). Los usuarios deben realizar la conversión al formato binario por sí mismos.

### Parámetros

`string`

  Una string que contiene los datos bytea de PostgreSQL a ser convertidos en string binario de PHP.

### Valores devueltos

Una string que contiene los datos protegidos.

### Ejemplos

Ejemplo #1 Ejemplo con pg_unescape_bytea()

    <?php
      // Conexión a la base de datos
      $dbconn = pg_connect('dbname=foo');

      // Recuperación de los datos bytea
      $res = pg_query("SELECT data FROM galeria WHERE nombre='Arboles Pino'");
      $raw = pg_fetch_result($res, 'data');

      // Convierte a binario y envía al navegador
      header('Content-type: image/jpeg');
      echo pg_unescape_bytea($raw);
    ?>

### Ver también

- pg_escape_bytea() - Protege una cadena para insertarla en un campo bytea
- pg_escape_string() - Protege un string para una consulta SQL

# pg_untrace

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

pg_untrace — Finaliza el seguimiento de una conexión PostgreSQL

### Descripción

function pg_untrace(?PgSql\Connection `$connection` = `null`): true

pg_untrace() finaliza el seguimiento de una conexión PostgreSQL, iniciado con pg_trace().

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` es `null`, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.2.0 | El tipo de retorno es ahora `true`, anteriormente era bool.
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.
8.0.0 | `connection` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con pg_untrace()

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       pg_trace('/tmp/trace.log', 'w', $pgsql_conn);
       pg_query("SELECT 1");
       pg_untrace($pgsql_conn);
       // Ahora el seguimiento de las comunicaciones está desactivado
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

### Ver también

- pg_trace() - Activa el seguimiento de una conexión PostgreSQL

# pg_update

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_update — Modifica las líneas de una tabla

### Descripción

function pg_update(
PgSql\Connection `$connection`,
string `$table_name`,
array `$values`,
array `$conditions`,
int `$flags` = `PGSQL_DML_EXEC`
): string|bool

pg_update() modifica las líneas de la tabla `table_name`, que cumplen la condición `conditions` con `values`.

Si `flags` está especificado, pg_convert() se aplica a `values` con los flags proporcionados.

Por omisión pg_update() pasa valores sin tratar. Los valores deben ser escapados o el flag `PGSQL_DML_ESCAPE` debe ser especificado en `flags`. `PGSQL_DML_ESCAPE` añade comillas y escapa los argumentos/identificadores. Por lo tanto, los nombres de tabla/columnas se vuelven sensibles a mayúsculas/minúsculas.

Tenga en cuenta que ni el escape ni las consultas preparadas pueden proteger de consultas LIKE, JSON, arrays, Regex, etc. Estos argumentos deben ser tratados según su contexto. Es decir, escapar/validar los valores.

### Parámetros

`connection`
  Una instancia PgSql\Connection.
`table_name`

  El nombre de la tabla en la que las líneas serán actualizadas.

`values`

  Un array cuyos claves son los nombres de los campos en la tabla `table_name`, y donde los valores son las líneas correspondientes que serán actualizadas.

`conditions`

  Un array cuyos claves son los nombres de los campos en la tabla `table_name`, y donde los valores son las condiciones que deben cumplir las líneas para ser actualizadas.

`flags`

  Cualquier combinación de constantes entre `PGSQL_CONV_FORCE_NULL`, `PGSQL_DML_NO_CONV`, `PGSQL_DML_ESCAPE`, `PGSQL_DML_EXEC`, `PGSQL_DML_ASYNC` o `PGSQL_DML_STRING`. Si `PGSQL_DML_STRING` forma parte del argumento `flags`, entonces la consulta será devuelta. Cuando la constante `PGSQL_DML_NO_CONV` o la constante `PGSQL_DML_ESCAPE` está definida, no se realizará ninguna llamada a la función pg_convert() internamente.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error. Devuelve una string si `PGSQL_DML_STRING` es pasado a través del argumento `flags`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pg_update()

    <?php
      $db = pg_connect ('dbname=foo');
      $data = array('field1'=>'AA', 'field2'=>'BB');

      // Esto es seguro en cierta medida, ya que todos los valores son escapados
      // Sin embargo PostgreSQL soporta JSON/arrays. Estos no
      // son seguros ni por escape ni por consultas preparadas.
      $res = pg_update($db, 'post_log', $_POST, $data);
      if ($res) {
          echo "Los datos han sido modificados: $res\n";
      } else {
          echo "Problema en los datos del usuario\n";
      }
    ?>

### Ver también

- pg_convert() - Convierte valores de un array asociativo a una forma adecuada para consultas SQL

# pg_version

(PHP 5, PHP 7, PHP 8)

pg_version — Devuelve un array con las versiones del cliente, del protocolo y del servidor (si está disponible)

### Descripción

function pg_version(?PgSql\Connection `$connection` = `null`): array

pg_version() devuelve un array con las versiones del cliente, del protocolo y del servidor.

Para obtener más información sobre el servidor, utilice pg_parameter_status().

### Parámetros

`connection`

  Una instancia PgSql\Connection. Cuando `connection` es `null`, se usa la conexión por defecto. La conexión por defecto es la última conexión hecha por pg_connect() o pg_pconnect()

  Advertencia

  Desde PHP 8.1.0, usar la conexión por defecto está obsoleto.

### Valores devueltos

Devuelve un array con las claves `client`, `protocol` y `server` y valores (si están disponibles).

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `connection` ahora espera una instancia de PgSql\Connection ; anteriormente, se esperaba un resource.
8.0.0 | `connection` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con pg_version()

    <?php
    $dbconn = pg_connect("host=localhost port=5432 dbname=marie")
       or die("Conexión imposible");

    $v = pg_version($dbconn);

    echo $v['client'];
    ?>

El ejemplo anterior mostrará:

    7.4

### Ver también

- pg_parameter_status() - Consulta un parámetro de configuración actual del servidor

## Tabla de contenidos

- pg_affected_rows — Devuelve el número de filas afectadas
- pg_cancel_query — Cancela una consulta asíncrona
- pg_change_password — Cambia la contraseña de un usuario de PostgreSQL
- pg_client_encoding — Lee la codificación del cliente
- pg_close — Finaliza una conexión PostgreSQL
- pg_connect — Establece una conexión PostgreSQL
- pg_connect_poll — Prueba el estado de un intento de conexión asíncrona a PostgreSQL en curso
- pg_connection_busy — Verifica si la conexión PostgreSQL está ocupada
- pg_connection_reset — Reinicia la conexión al servidor PostgreSQL
- pg_connection_status — Se lee el estado de la conexión PostgreSQL
- pg_consume_input — Lee la entrada de la conexión
- pg_convert — Convierte valores de un array asociativo a una forma adecuada para consultas SQL
- pg_copy_from — Inserta filas en una tabla a partir de un array
- pg_copy_to — Copia una tabla en un array
- pg_dbname — Devuelve el nombre de la base de datos PostgreSQL
- pg_delete — Elimina filas de PostgreSQL
- pg_end_copy — Sincroniza con el servidor PostgreSQL
- pg_escape_bytea — Protege una cadena para insertarla en un campo bytea
- pg_escape_identifier — Protege un identificador para su inserción en un campo de texto.
- pg_escape_literal — Protege una consulta SQL literal para insertar en un campo de texto
- pg_escape_string — Protege un string para una consulta SQL
- pg_execute — Ejecuta una consulta preparada de PostgreSQL
- pg_fetch_all — Lee todas las líneas de un resultado
- pg_fetch_all_columns — Recupera todas las filas de una columna particular de resultados como un array
- pg_fetch_array — Lee una línea de resultado PostgreSQL en un array
- pg_fetch_assoc — Lee una fila de resultado PostgreSQL como un array asociativo
- pg_fetch_object — Lee una fila de resultado PostgreSQL en un objeto
- pg_fetch_result — Devuelve los valores de un resultado
- pg_fetch_row — Lee una fila en un array
- pg_field_is_null — Comprueba si un campo PostgreSQL es null
- pg_field_name — Devuelve el nombre de un campo PostgreSQL
- pg_field_num — Devuelve el número de una columna
- pg_field_prtlen — Devuelve el tamaño de impresión
- pg_field_size — Devuelve el tamaño interno de almacenamiento de un campo dado
- pg_field_table — Devuelve el nombre o el oid de una tabla
- pg_field_type — Devuelve el tipo de un campo PostgreSQL dado por índice
- pg_field_type_oid — Devuelve el ID de tipo (OID) para el número de campo correspondiente
- pg_flush — Envía los datos de la solicitud saliente a través de la conexión
- pg_free_result — Libera la memoria
- pg_get_notify — Lee el mensaje SQL NOTIFY
- pg_get_pid — Lee el identificador de proceso del servidor PostgreSQL
- pg_get_result — Lee un resultado asíncrono de PostgreSQL
- pg_host — Devuelve el nombre de host
- pg_insert — Inserta un array en una tabla
- pg_jit — Devuelve la información JIT del servidor
- pg_last_error — Lee el último mensaje de error en la conexión
- pg_last_notice — Devuelve la última nota del servidor PostgreSQL
- pg_last_oid — Devuelve el identificador de la última línea
- pg_lo_close — Cierra un objeto grande de PostgreSQL
- pg_lo_create — Crea un objeto de gran tamaño de PostgreSQL
- pg_lo_export — Exporta un objeto grande a un fichero
- pg_lo_import — Importa un objeto grande desde un fichero
- pg_lo_open — Abre un objeto de gran tamaño de PostgreSQL
- pg_lo_read — Lee un objeto de gran tamaño
- pg_lo_read_all — Lee un objeto de gran tamaño en su totalidad
- pg_lo_seek — Modifica la posición en un objeto de gran tamaño
- pg_lo_tell — Devuelve la posición actual en un objeto grande de PostgreSQL
- pg_lo_truncate — Trunca un objeto grande
- pg_lo_unlink — Elimina un objeto grande de PostgreSQL
- pg_lo_write — Escribe un objeto de gran tamaño de PostgreSQL
- pg_meta_data — Lee los metadatos de la tabla PostgreSQL
- pg_num_fields — Devuelve el número de campos
- pg_num_rows — Devuelve el número de filas de PostgreSQL
- pg_options — Devuelve las opciones de PostgreSQL
- pg_parameter_status — Consulta un parámetro de configuración actual del servidor
- pg_pconnect — Establece una conexión PostgreSQL persistente
- pg_ping — Ping la conexión a la base de datos
- pg_port — Devuelve el número de puerto
- pg_prepare — Envía una solicitud al servidor para crear una sentencia preparada con los parámetros dados y espera la ejecución
- pg_put_copy_data — Envía datos al servidor durante una operación COPY
- pg_put_copy_end — Indica al servidor la finalización de una operación COPY
- pg_put_line — Envía una string al servidor PostgreSQL
- pg_query — Ejecuta una consulta PostgreSQL
- pg_query_params — Envía un comando al servidor y espera el resultado, con la capacidad de pasar parámetros por separado del texto SQL de la consulta
- pg_result_error — Lee el mensaje de error asociado a un resultado
- pg_result_error_field — Devuelve un campo individual de un informe de error
- pg_result_memory_size — Devuelve la cantidad de memoria asignada para un resultado de consulta
- pg_result_seek — Establece la posición de la línea en un resultado
- pg_result_status — Lee el estado del resultado
- pg_select — Realiza una selección PostgreSQL
- pg_send_execute — Envía una consulta para ejecutar una consulta preparada con parámetros dados, sin esperar el(los) resultado(s)
- pg_send_prepare — Envía una solicitud para crear una consulta preparada con los argumentos dados, sin esperar el final de su ejecución
- pg_send_query — Ejecuta una consulta PostgreSQL asíncrona
- pg_send_query_params — Envía un comando y separa los parámetros al servidor sin esperar el/los resultado(s)
- pg_set_chunked_rows_size — Establece los resultados de la consulta a recuperar en modo chunk
- pg_set_client_encoding — Establece la codificación del cliente PostgreSQL
- pg_set_error_context_visibility — Determina la visibilidad de los mensajes de error de contexto devueltos por pg_last_error y pg_result_error
- pg_set_error_verbosity — Determina el nivel de detalle de los mensajes devueltos por pg_last_error y pg_result_error
- pg_socket — Obtiene un manejador de solo lectura sobre el socket subyacente de una conexión PostgreSQL
- pg_socket_poll — Sondea un socket de conexión PostgreSQL para comprobar si está listo para lectura/escritura
- pg_trace — Activa el seguimiento de una conexión PostgreSQL
- pg_transaction_status — Retorna el estado de la transacción en curso del servidor
- pg_tty — Devuelve el nombre de TTY asociado a la conexión
- pg_unescape_bytea — Elimina la protección de una cadena de tipo bytea
- pg_untrace — Finaliza el seguimiento de una conexión PostgreSQL
- pg_update — Modifica las líneas de una tabla
- pg_version — Devuelve un array con las versiones del cliente, del protocolo y del servidor (si está disponible)

# La clase PgSql\Connection

(PHP 8 >= 8.1.0)

## Introducción

Una clase completamente opaca que reemplaza el resource `pgsql link` a partir de PHP 8.1.0.

## Sinopsis de la Clase

namespace PgSql;
final class Connection {
}

# La clase PgSql\Result

(PHP 8 >= 8.1.0)

## Introducción

Una clase completamente opaca que reemplaza el resource `pgsql result` a partir de PHP 8.1.0.

## Sinopsis de la Clase

namespace PgSql;
final class Result {
}

# La clase PgSql\Lob

(PHP 8 >= 8.1.0)

## Introducción

Una clase completamente opaca que reemplaza el resource `pgsql large object` a partir de PHP 8.1.0.

## Sinopsis de la Clase

namespace PgSql;
final class Lob {
}

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
  - Tipos de recursos
- Constantes predefinidas
- Ejemplos
  - Uso básico
  - Uso básico
- Funciones de PostgreSQL
  - pg_affected_rows — Devuelve el número de filas afectadas
  - pg_cancel_query — Cancela una consulta asíncrona
  - pg_change_password — Cambia la contraseña de un usuario de PostgreSQL
  - pg_client_encoding — Lee la codificación del cliente
  - pg_close — Finaliza una conexión PostgreSQL
  - pg_connect — Establece una conexión PostgreSQL
  - pg_connect_poll — Prueba el estado de un intento de conexión asíncrona a PostgreSQL en curso
  - pg_connection_busy — Verifica si la conexión PostgreSQL está ocupada
  - pg_connection_reset — Reinicia la conexión al servidor PostgreSQL
  - pg_connection_status — Se lee el estado de la conexión PostgreSQL
  - pg_consume_input — Lee la entrada de la conexión
  - pg_convert — Convierte valores de un array asociativo a una forma adecuada para consultas SQL
  - pg_copy_from — Inserta filas en una tabla a partir de un array
  - pg_copy_to — Copia una tabla en un array
  - pg_dbname — Devuelve el nombre de la base de datos PostgreSQL
  - pg_delete — Elimina filas de PostgreSQL
  - pg_end_copy — Sincroniza con el servidor PostgreSQL
  - pg_escape_bytea — Protege una cadena para insertarla en un campo bytea
  - pg_escape_identifier — Protege un identificador para su inserción en un campo de texto.
  - pg_escape_literal — Protege una consulta SQL literal para insertar en un campo de texto
  - pg_escape_string — Protege un string para una consulta SQL
  - pg_execute — Ejecuta una consulta preparada de PostgreSQL
  - pg_fetch_all — Lee todas las líneas de un resultado
  - pg_fetch_all_columns — Recupera todas las filas de una columna particular de resultados como un array
  - pg_fetch_array — Lee una línea de resultado PostgreSQL en un array
  - pg_fetch_assoc — Lee una fila de resultado PostgreSQL como un array asociativo
  - pg_fetch_object — Lee una fila de resultado PostgreSQL en un objeto
  - pg_fetch_result — Devuelve los valores de un resultado
  - pg_fetch_row — Lee una fila en un array
  - pg_field_is_null — Comprueba si un campo PostgreSQL es null
  - pg_field_name — Devuelve el nombre de un campo PostgreSQL
  - pg_field_num — Devuelve el número de una columna
  - pg_field_prtlen — Devuelve el tamaño de impresión
  - pg_field_size — Devuelve el tamaño interno de almacenamiento de un campo dado
  - pg_field_table — Devuelve el nombre o el oid de una tabla
  - pg_field_type — Devuelve el tipo de un campo PostgreSQL dado por índice
  - pg_field_type_oid — Devuelve el ID de tipo (OID) para el número de campo correspondiente
  - pg_flush — Envía los datos de la solicitud saliente a través de la conexión
  - pg_free_result — Libera la memoria
  - pg_get_notify — Lee el mensaje SQL NOTIFY
  - pg_get_pid — Lee el identificador de proceso del servidor PostgreSQL
  - pg_get_result — Lee un resultado asíncrono de PostgreSQL
  - pg_host — Devuelve el nombre de host
  - pg_insert — Inserta un array en una tabla
  - pg_jit — Devuelve la información JIT del servidor
  - pg_last_error — Lee el último mensaje de error en la conexión
  - pg_last_notice — Devuelve la última nota del servidor PostgreSQL
  - pg_last_oid — Devuelve el identificador de la última línea
  - pg_lo_close — Cierra un objeto grande de PostgreSQL
  - pg_lo_create — Crea un objeto de gran tamaño de PostgreSQL
  - pg_lo_export — Exporta un objeto grande a un fichero
  - pg_lo_import — Importa un objeto grande desde un fichero
  - pg_lo_open — Abre un objeto de gran tamaño de PostgreSQL
  - pg_lo_read — Lee un objeto de gran tamaño
  - pg_lo_read_all — Lee un objeto de gran tamaño en su totalidad
  - pg_lo_seek — Modifica la posición en un objeto de gran tamaño
  - pg_lo_tell — Devuelve la posición actual en un objeto grande de PostgreSQL
  - pg_lo_truncate — Trunca un objeto grande
  - pg_lo_unlink — Elimina un objeto grande de PostgreSQL
  - pg_lo_write — Escribe un objeto de gran tamaño de PostgreSQL
  - pg_meta_data — Lee los metadatos de la tabla PostgreSQL
  - pg_num_fields — Devuelve el número de campos
  - pg_num_rows — Devuelve el número de filas de PostgreSQL
  - pg_options — Devuelve las opciones de PostgreSQL
  - pg_parameter_status — Consulta un parámetro de configuración actual del servidor
  - pg_pconnect — Establece una conexión PostgreSQL persistente
  - pg_ping — Ping la conexión a la base de datos
  - pg_port — Devuelve el número de puerto
  - pg_prepare — Envía una solicitud al servidor para crear una sentencia preparada con los parámetros dados y espera la ejecución
  - pg_put_copy_data — Envía datos al servidor durante una operación COPY
  - pg_put_copy_end — Indica al servidor la finalización de una operación COPY
  - pg_put_line — Envía una string al servidor PostgreSQL
  - pg_query — Ejecuta una consulta PostgreSQL
  - pg_query_params — Envía un comando al servidor y espera el resultado, con la capacidad de pasar parámetros por separado del texto SQL de la consulta
  - pg_result_error — Lee el mensaje de error asociado a un resultado
  - pg_result_error_field — Devuelve un campo individual de un informe de error
  - pg_result_memory_size — Devuelve la cantidad de memoria asignada para un resultado de consulta
  - pg_result_seek — Establece la posición de la línea en un resultado
  - pg_result_status — Lee el estado del resultado
  - pg_select — Realiza una selección PostgreSQL
  - pg_send_execute — Envía una consulta para ejecutar una consulta preparada con parámetros dados, sin esperar el(los) resultado(s)
  - pg_send_prepare — Envía una solicitud para crear una consulta preparada con los argumentos dados, sin esperar el final de su ejecución
  - pg_send_query — Ejecuta una consulta PostgreSQL asíncrona
  - pg_send_query_params — Envía un comando y separa los parámetros al servidor sin esperar el/los resultado(s)
  - pg_set_chunked_rows_size — Establece los resultados de la consulta a recuperar en modo chunk
  - pg_set_client_encoding — Establece la codificación del cliente PostgreSQL
  - pg_set_error_context_visibility — Determina la visibilidad de los mensajes de error de contexto devueltos por pg_last_error y pg_result_error
  - pg_set_error_verbosity — Determina el nivel de detalle de los mensajes devueltos por pg_last_error y pg_result_error
  - pg_socket — Obtiene un manejador de solo lectura sobre el socket subyacente de una conexión PostgreSQL
  - pg_socket_poll — Sondea un socket de conexión PostgreSQL para comprobar si está listo para lectura/escritura
  - pg_trace — Activa el seguimiento de una conexión PostgreSQL
  - pg_transaction_status — Retorna el estado de la transacción en curso del servidor
  - pg_tty — Devuelve el nombre de TTY asociado a la conexión
  - pg_unescape_bytea — Elimina la protección de una cadena de tipo bytea
  - pg_untrace — Finaliza el seguimiento de una conexión PostgreSQL
  - pg_update — Modifica las líneas de una tabla
  - pg_version — Devuelve un array con las versiones del cliente, del protocolo y del servidor (si está disponible)
- PgSql\Connection — La clase PgSql\Connection
- PgSql\Result — La clase PgSql\Result
- PgSql\Lob — La clase PgSql\Lob

# SQLite3

# Introducción

Soporte para bases de datos SQLite versión 3.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución

## Requerimientos

Desde PHP 7.4.0, » libsqlite ≥ 3.7.4 es requerida. Anteriormente, la biblioteca libsqlite integrada podría haber sido utilizada en su lugar.

## Instalación

El soporte de SQLite3 se activa por omisión. Es posible desactivarlo mediante la opción `--without-sqlite3` durante la compilación.

Los usuarios de Windows deben activar la biblioteca php_sqlite3.dll para utilizar esta extensión. Esta DLL se incluye con las distribuciones de PHP para Windows.

> Nota: Instalación adicional en Windows a partir de PHP 7.4.0

> Para hacer funcionar esta extensión, algunas bibliotecas DLL deben estar disponibles a través del PATH del sistema Windows. Lea la F.A.Q titulada "Cómo agregar mi carpeta PHP a mi PATH de Windows" para más información. Copiar las bibliotecas DLL desde la carpeta PHP a la carpeta del sistema de Windows también funciona (ya que la carpeta del sistema está por defecto en el PATH del sistema), pero este método no es recomendado. Esta extensión requiere que los siguientes archivos estén en el PATH: libsqlite3.dll.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración Sqlite3
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
sqlite3.extension_dir | "" | `INI_SYSTEM` |
sqlite3.defensive | 1 | `INI_USER` | Disponible a partir de PHP 7.2.17 y 7.3.4 para libsqlite ≥ 3.26.0. Anterior a PHP 8.2.0 este parámetro solo podía ser modificado como `INI_SYSTEM`.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`sqlite3.extension_dir` string

  Ruta hacia el directorio donde se encuentran las extensiones cargables para SQLite.

`sqlite3.defensive` bool

  Cuando el flag defensivo está activado, las funcionalidades del lenguaje que permiten a SQL ordinario corromper deliberadamente los archivos de la base de datos son desactivadas. Esto impide escribir directamente en el esquema, las tablas sombra (como las tablas de datos FTS) o la tabla virtual sqlite_dbpage. Este parámetro php.ini solo es efectivo para libsqlite ≥ 3.26.0.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`SQLITE3_ASSOC` (int)
  Especifica que el método Sqlite3Result::fetchArray() debe devolver un array indexado por el nombre de la columna en el conjunto de resultados correspondiente.
`SQLITE3_NUM` (int)
  Especifica que el método Sqlite3Result::fetchArray() debe devolver un array indexado por el número de la columna en el conjunto de resultados correspondiente, comenzando por la columna 0.
`SQLITE3_BOTH` (int)
  Especifica que el método Sqlite3Result::fetchArray() debe devolver un array indexado por el nombre y el número de la columna en el conjunto de resultados correspondiente, comenzando por la columna 0.
`SQLITE3_INTEGER` (int)
  Representa la clase de almacenamiento INTEGER de SQLite3.
`SQLITE3_FLOAT` (int)
  Representa la clase de almacenamiento REAL (FLOAT) de SQLite3.
`SQLITE3_TEXT` (int)
  Representa la clase de almacenamiento TEXT de SQLite3.
`SQLITE3_BLOB` (int)
  Representa la clase de almacenamiento BLOB de SQLite3.
`SQLITE3_NULL` (int)
  Representa la clase de almacenamiento NULL de SQLite3.
`SQLITE3_OPEN_READONLY` (int)
  Especifica que la base de datos SQLite3 debe ser abierta en modo de solo lectura.
`SQLITE3_OPEN_READWRITE` (int)
  Especifica que la base de datos SQLite3 debe ser abierta en modo de lectura y escritura.
`SQLITE3_OPEN_CREATE` (int)
  Especifica que la base de datos SQLite3 debe ser creada si no existe previamente.
`SQLITE3_DETERMINISTIC` (int)
  Especifica que una función creada con SQLite3::createFunction() es determinista, es decir, que siempre devuelve el mismo resultado dado los mismos argumentos en una sola instrucción SQL. (disponible a partir de PHP 7.1.4)

# La clase SQLite3

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Introducción

Una clase de interfaz con las bases de datos SQLite3.

## Sinopsis de la Clase

class SQLite3 {
/* Constantes */
public const int OK;
public const int DENY;
public const int IGNORE;
public const int CREATE_INDEX;
public const int CREATE_TABLE;
public const int CREATE_TEMP_INDEX;
public const int CREATE_TEMP_TABLE;
public const int CREATE_TEMP_TRIGGER;
public const int CREATE_TEMP_VIEW;
public const int CREATE_TRIGGER;
public const int CREATE_VIEW;
public const int DELETE;
public const int DROP_INDEX;
public const int DROP_TABLE;
public const int DROP_TEMP_INDEX;
public const int DROP_TEMP_TABLE;
public const int DROP_TEMP_TRIGGER;
public const int DROP_TEMP_VIEW;
public const int DROP_TRIGGER;
public const int DROP_VIEW;
public const int INSERT;
public const int PRAGMA;
public const int READ;
public const int SELECT;
public const int TRANSACTION;
public const int UPDATE;
public const int ATTACH;
public const int DETACH;
public const int ALTER_TABLE;
public const int REINDEX;
public const int ANALYZE;
public const int CREATE_VTABLE;
public const int DROP_VTABLE;
public const int FUNCTION;
public const int SAVEPOINT;
public const int COPY;
public const int RECURSIVE;
/* Métodos */
public function __construct(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = "")
public function backup(SQLite3 `$destination`, string `$sourceDatabase` = "main", string `$destinationDatabase` = "main"): bool
public function busyTimeout(int `$milliseconds`): bool
public function changes(): int
public function close(): bool
public function createAggregate(
string `$name`,
callable `$stepCallback`,
callable `$finalCallback`,
int `$argCount` = -1
): bool
public function createCollation(string `$name`, callable `$callback`): bool
public function createFunction(
string `$name`,
callable `$callback`,
int `$argCount` = -1,
int `$flags` = 0
): bool
public function enableExceptions(bool `$enable` = `false`): bool
public static function escapeString(string `$string`): string
public function exec(string `$query`): bool
public function lastErrorCode(): int
public function lastErrorMsg(): string
public function lastInsertRowID(): int
public function loadExtension(string `$name`): bool
public function open(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = ""): void
public function openBlob(
string `$table`,
string `$column`,
int `$rowid`,
string `$database` = "main",
int `$flags` = `SQLITE3_OPEN_READONLY`
): resource|false
public function prepare(string `$query`): SQLite3Stmt|false
public function query(string `$query`): SQLite3Result|false
public function querySingle(string `$query`, bool `$entireRow` = `false`): mixed
public function setAuthorizer(?callable `$callback`): bool
public static function version(): array
}

## Constantes predefinidas

`SQLite3::OK`

`SQLite3::DENY`

`SQLite3::IGNORE`

`SQLite3::CREATE_INDEX`

`SQLite3::CREATE_TABLE`

`SQLite3::CREATE_TEMP_INDEX`

`SQLite3::CREATE_TEMP_TABLE`

`SQLite3::CREATE_TEMP_TRIGGER`

`SQLite3::CREATE_TEMP_VIEW`

`SQLite3::CREATE_TRIGGER`

`SQLite3::CREATE_VIEW`

`SQLite3::DELETE`

`SQLite3::DROP_INDEX`

`SQLite3::DROP_TABLE`

`SQLite3::DROP_TEMP_INDEX`

`SQLite3::DROP_TEMP_TABLE`

`SQLite3::DROP_TEMP_TRIGGER`

`SQLite3::DROP_TEMP_VIEW`

`SQLite3::DROP_TRIGGER`

`SQLite3::DROP_VIEW`

`SQLite3::INSERT`

`SQLite3::PRAGMA`

`SQLite3::READ`

`SQLite3::SELECT`

`SQLite3::TRANSACTION`

`SQLite3::UPDATE`

`SQLite3::ATTACH`

`SQLite3::DETACH`

`SQLite3::ALTER_TABLE`

`SQLite3::REINDEX`

`SQLite3::ANALYZE`

`SQLite3::CREATE_VTABLE`

`SQLite3::DROP_VTABLE`

`SQLite3::FUNCTION`

`SQLite3::SAVEPOINT`

`SQLite3::COPY`

`SQLite3::RECURSIVE`

# SQLite3::backup

(PHP 7 >= 7.4.0, PHP 8)

SQLite3::backup — Realiza una copia de seguridad de una base de datos en otra base de datos

### Descripción

public function SQLite3::backup(SQLite3 `$destination`, string `$sourceDatabase` = "main", string `$destinationDatabase` = "main"): bool

SQLite3::backup() copia el contenido de una base de datos en otra, sobrescribiendo el contenido de la base de datos de destino. Esto es útil para crear copias de seguridad de bases de datos o para copiar bases de datos en memoria hacia o desde ficheros persistentes.

Sugerencia

Desde SQLite 3.27.0 (2019-02-07), también es posible utilizar la instrucción `VACUUM INTO 'file.db';` para guardar la base de datos en un nuevo fichero.

### Parámetros

`destination`

  Una conexión a una base de datos SQLite3 abierta con SQLite3::open().

`sourceDatabase`

  El nombre de la base de datos es `"main"` para la base de datos principal, `"temp"` para la base de datos temporal, o el nombre especificado después del mot-clé `AS` en una instrucción `ATTACH` para una base de datos adjunta.

`destinationDatabase`

  Análogo a `sourceDatabase` pero para la `destination`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Realizar una copia de seguridad de una base de datos existente

    <?php
    // $conn es una conexión a una base de datos sqlite3 ya abierta

    $backup = new SQLite3('backup.sqlite');
    $conn->backup($backup);
    ?>

# SQLite3::busyTimeout

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

SQLite3::busyTimeout — Define el gestor de espera de la conexión

### Descripción

public function SQLite3::busyTimeout(int `$milliseconds`): bool

Define el gestor de espera que aguardará hasta que la base de datos no esté bloqueada o hasta que se alcance el tiempo límite.

### Parámetros

`milliseconds`

  Los milisegundos a esperar. Establecer este valor a cero o a un valor inferior desactivará un gestor de espera previamente definido.

### Valores devueltos

Devuelve `true` en caso de éxito, o `false` si ocurre un error.

# SQLite3::changes

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::changes — Devuelve el número de líneas modificadas (o insertadas, borradas) por la última consulta SQL

### Descripción

public function SQLite3::changes(): int

Devuelve el número de líneas modificadas (o insertadas, borradas) por la última consulta SQL.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un int correspondiente al número de líneas modificadas (o insertadas, borradas) por la última consulta SQL.

### Ejemplos

Ejemplo #1 Ejemplo con SQLite3::changes()

    <?php
    $db = new SQLite3('mysqlitedb.db');

    $query = $db->exec('UPDATE counter SET views=0 WHERE page="test"');
    if ($query) {
        echo 'Número de líneas modificadas : ', $db->changes();
    }
    ?>

# SQLite3::close

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::close — Cierra la conexión con la base de datos

### Descripción

public function SQLite3::close(): bool

Cierra la conexión con la base de datos.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con SQLite3::close()

    <?php
    $db = new SQLite3('mysqlitedb.db');
    $db->close();
    ?>

# SQLite3::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::__construct — Instancia un objeto SQLite3 y abre la base de datos SQLite 3

### Descripción

public function SQLite3::__construct(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = "")

Inicializa un objeto SQLite3 y abre una conexión a la base de datos SQLite 3. Si el cifrado ha sido incluido durante la compilación, entonces esta función intentará utilizar la clave correspondiente.

### Parámetros

`filename`

  Ruta hacia la base de datos SQLite, o `:memory:` para utilizar la base de datos que se encuentra en la memoria RAM. Si `filename` es una cadena vacía, se creará una base de datos temporal privada en el disco. Esta base de datos privada será automáticamente eliminada tan pronto como la conexión de la base de datos sea cerrada.

`flags`

  Bandera opcional utilizada para determinar la manera de apertura de la base de datos SQLite. Por omisión, la apertura se efectúa utilizando `SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE`.

  - `SQLITE3_OPEN_READONLY` : Abre la base de datos en modo solo lectura.

  - `SQLITE3_OPEN_READWRITE` : Abre la base de datos en modo lectura y escritura.

  - `SQLITE3_OPEN_CREATE` : Crea la base de datos si no existe.

`encryptionKey`

  Una clave de cifrado opcional, a utilizar durante el cifrado/descifrado de la base de datos SQLite. Si el módulo SQLite no está instalado, este parámetro no tendrá ningún efecto.

### Errores/Excepciones

Lanza una Exception en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
7.0.10 | El `filename` puede ahora estar vacío para utilizar una base de datos privada, temporal en disco.

### Ejemplos

Ejemplo #1 Ejemplo con SQLite3::__construct()

    <?php
    $db = new SQLite3('mysqlitedb.db');

    $db->exec('CREATE TABLE foo (bar TEXT)');
    $db->exec("INSERT INTO foo (bar) VALUES ('Esto es una prueba')");

    $result = $db->query('SELECT bar FROM foo');
    var_dump($result->fetchArray());
    ?>

# SQLite3::createAggregate

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::createAggregate — Registra una función PHP para ser utilizada como función de agregación SQLite

### Descripción

public function SQLite3::createAggregate(
string `$name`,
callable `$stepCallback`,
callable `$finalCallback`,
int `$argCount` = -1
): bool

Registra una función PHP o una función definida por el usuario para ser utilizada como función de agregación SQL, que será utilizada en las consultas SQL.

### Parámetros

`name`

  Nombre de la función de agregación SQL a crear o redefinir.

`stepCallback`

  Función de retrollamada llamada para cada fila en el conjunto de resultados. Su función PHP debería acumular el resultado y almacenar su contexto de agregación.

  Esta función debe ser definida como:

  function step(
  mixed `$context`,
  int `$rownumber`,
  mixed `$value`,
  mixed `...$values`
  ): mixed
  `context`

    `null` para la primera fila; en las filas siguientes esto tendrá el valor que previamente fue retornado por la función step; debería utilizarse esto para mantener el estado de agregación.

  `rownumber`

    El número de fila actual.

  `value`

    El primer argumento a pasar al agregador.

  `values`

    Argumentos adicionales a pasar al agregador.

  El valor retornado por esta función será utilizado como argumento `context` durante la próxima llamada a una función de paso o final.
`finalCallback`

  Función de retrollamada para agregar los "pasos" de datos de cada fila. Una vez que todas las filas han sido procesadas, la función será llamada, tomará los datos del contexto de agregación y retornará el resultado. La función de retrollamada debe retornar un tipo comprendido por SQLite (i.e. un tipo escalar).

  Esta función debe ser definida como:

  function fini(mixed `$context`, int `$rownumber`): mixed
  `context`

    Contiene el valor de retorno de la última llamada a la función step.

  `rownumber`

    Siempre `0`.

  El valor de retorno de esta función será utilizado como valor de retorno para la agregación.
`argCount`

  El número de argumentos tomados por la función de agregación SQL. Si este número es negativo, entonces la función de agregación SQL podrá tomar un número no definido de argumentos.

### Valores devueltos

Retorna `true` si la creación del agregado ha tenido éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de una función de agregación con max_length

    <?php
    $data = array(
       'one',
       'two',
       'three',
       'four',
       'five',
       'six',
       'seven',
       'eight',
       'nine',
       'ten',
       );
    $db = new SQLite3(':memory:');
    $db->exec("CREATE TABLE strings(a)");
    $insert = $db->prepare('INSERT INTO strings VALUES (?)');
    foreach ($data as $str) {
        $insert->bindValue(1, $str);
        $insert->execute();
    }
    $insert = null;

    function max_len_step($context, $rownumber, $string)
    {
        if (strlen($string) > $context) {
            $context = strlen($string);
        }
        return $context;
    }

    function max_len_finalize($context, $rownumber)
    {
        return $context === null ? 0 : $context;
    }

    $db->createAggregate('max_len', 'max_len_step', 'max_len_finalize');

    var_dump($db->querySingle('SELECT max_len(a) from strings'));
    ?>

El ejemplo anterior mostrará:

    int(5)

En este ejemplo, se crea una función agregativa que calculará la longitud de la cadena de caracteres más larga en una de las columnas de la tabla. Para cada fila, la función `max_len_step` es llamada y el parámetro `$context` es pasado. El parámetro de contexto es como cualquier otra variable PHP y debe ser fijado para contener un array o incluso, un objeto. En este ejemplo, se utiliza para contener la longitud máxima que se ha visto hasta el momento; si el parámetro `$string` tiene una longitud mayor que la actual, se actualiza el contexto para contener esta nueva longitud máxima.

Una vez que todas las filas han sido procesadas, SQLite llama a la función `max_len_finalize` para determinar el resultado agregativo. Aquí, se podrían realizar cálculos basados en los datos encontrados en `$context`. En nuestro ejemplo simple, hemos calculado el resultado como si la consulta estuviera progresando, aunque simplemente necesitamos retornar el valor de contexto.

Sugerencia

No se RECOMIENDA registrar una copia de los valores en el contexto para finalmente procesarlos. En este caso, SQLite utilizaría mucha memoria para procesar la consulta - imagine la cantidad de memoria necesaria si un millón de filas fueran registradas en memoria, sabiendo que cada fila contiene una cadena de caracteres (32 bytes por cadena).

Sugerencia

Puede utilizarse SQLite3::createAggregate() para sobrescribir las funciones nativas de SQLite.

# SQLite3::createCollation

(PHP 5 >= 5.3.11, PHP 7, PHP 8)

SQLite3::createCollation — Registra una función PHP para utilizarla como función de clasificación SQL

### Descripción

public function SQLite3::createCollation(string `$name`, callable `$callback`): bool

Registra una función PHP o una función definida por el usuario para utilizarla como función de clasificación en una consulta SQL.

### Parámetros

`name`

  Nombre de la función de clasificación SQL a crear o redefinir.

`callback`

  El nombre de una función PHP o de una función definida por el usuario a aplicar como función de retorno, definiendo el comportamiento de la clasificación. Debe aceptar dos argumentos y retornará lo mismo que la función strcmp(), es decir debe retornar -1, 1, o 0 si la primera cadena se clasifica antes, después, o es equivalente a la segunda.

  Esta función debe ser definida como:

  function collation(mixed `$value1`, mixed `$value2`): int

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con SQLite3::createCollation()

Registra la función PHP strnatcmp() como secuencia de clasificación en la base de datos SQLite3.

    <?php

    $db = new SQLite3(":memory:");
    $db->exec("CREATE TABLE test (col1 string)");
    $db->exec("INSERT INTO test VALUES ('a1')");
    $db->exec("INSERT INTO test VALUES ('a10')");
    $db->exec("INSERT INTO test VALUES ('a2')");

    $db->createCollation('NATURAL_CMP', 'strnatcmp');

    $defaultSort = $db->query("SELECT col1 FROM test ORDER BY col1");
    $naturalSort = $db->query("SELECT col1 FROM test ORDER BY col1 COLLATE NATURAL_CMP");

    echo "Por omisión :\n";
    while ($row = $defaultSort->fetchArray()){
        echo $row['col1'], "\n";
    }

    echo "\nNatural :\n";
    while ($row = $naturalSort->fetchArray()){
        echo $row['col1'], "\n";
    }

    $db->close();

    ?>

El ejemplo anterior mostrará:

    Por omisión :
    a1
    a10
    a2

    Natural :
    a1
    a2
    a10

### Ver también

- La documentación sobre la clasificación SQLite : » http://sqlite.org/datatype3.html#collation

# SQLite3::createFunction

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::createFunction — Registra una función PHP para su uso como función escalar SQL

### Descripción

public function SQLite3::createFunction(
string `$name`,
callable `$callback`,
int `$argCount` = -1,
int `$flags` = 0
): bool

Registra una función PHP o una función de usuario para su uso como función escalar SQL, para su utilización en las consultas SQL.

### Parámetros

`name`

  Nombre de la función SQL a crear o redefinir.

`callback`

  El nombre de la función PHP o la función de usuario a aplicar como callback, definiendo el comportamiento de la función SQL.

  Esta función debe ser definida como:

  function callback(mixed `$value`, mixed `...$values`): mixed
  `value`

    El primer argumento a pasar a la función SQL.

  `values`

    Argumentos adicionales a pasar a la función SQL.

`argCount`

  Número de argumentos que la función SQL acepta. Si este parámetro es `-1`, la función SQL puede aceptar cualquier número de argumentos.

`flags`

  Una conjunción de operaciones a nivel de bits de indicadores. Actualmente, solo `SQLITE3_DETERMINISTIC` es soportado, lo cual especifica que la función devuelve siempre el mismo resultado dado los mismos argumentos en una sola instrucción SQL.

### Valores devueltos

Devuelve `true` si la función fue creada con éxito, `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
7.1.4 | El parámetro `flags` fue añadido.

### Ejemplos

Ejemplo #1 Ejemplo con SQLite3::createFunction()

    <?php
    function my_udf_md5($string) {
        return hash('md5', $string);
    }

    $db = new SQLite3('mysqlitedb.db');
    $db->createFunction('my_udf_md5', 'my_udf_md5');

    var_dump($db->querySingle('SELECT my_udf_md5("test")'));
    ?>

Resultado del ejemplo anterior es similar a:

    string(32) "098f6bcd4621d373cade4e832627b4f6"

# SQLite3::enableExceptions

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::enableExceptions — Activa el lanzamiento de excepciones

### Descripción

public function SQLite3::enableExceptions(bool `$enable` = `false`): bool

Controla si la instancia SQLite3 lanzará excepciones o advertencias en caso de error.

### Parámetros

`enable`

  Si `true`, la instancia SQLite3, y las instancias derivadas de SQLite3Stmt y SQLite3Result, lanzarán excepciones en caso de errores.

  Si `false`, la instancia SQLite3, y las instancias derivadas de SQLite3Stmt y SQLite3Result, lanzarán advertencias en caso de errores.

  Para cada uno de los modos, el código y mensaje de error, si los hay, estarán disponibles gracias a SQLite3::lastErrorCode() y SQLite3::lastErrorMsg() respectivamente.

### Valores devueltos

Devuelve el valor anterior; `true` si las excepciones estaban activadas, `false` en caso contrario.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Llamar a SQLite3::enableExceptions() con `enable` a `false` desencadenará una advertencia `E_DEPRECATED`.

### Ejemplos

Ejemplo #1 Ejemplo con SQLite3::enableExceptions()

    <?php
    $sqlite = new SQLite3(':memory:');
    try {
        $sqlite->exec('create table foo');
        $sqlite->enableExceptions(true);
        $sqlite->exec('create table bar');
    } catch (Exception $e) {
        echo 'Caught exception: ' . $e->getMessage();
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Warning: SQLite3::exec(): near "foo": syntax error in example.php on line 4
    Caught exception: near "bar": syntax error

# SQLite3::escapeString

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::escapeString — Devuelve una cadena limpiada

### Descripción

public static function SQLite3::escapeString(string `$string`): string

Devuelve una cadena que ha sido limpiada para poder ser incluida de forma segura en las consultas SQL.

Advertencia

Esta función no es capaz de manejar strings binarios !

Para manejar correctamente los campos BLOB que contienen caracteres NUL, es preferible utilizar la función SQLite3Stmt::bindParam().

### Parámetros

`string`

  La cadena a limpiar.

### Valores devueltos

Devuelve una cadena limpiada, que podrá ser utilizada de forma segura en una consulta SQL.

### Notas

Advertencia

La función addslashes() no debe PAS ser utilizada para proteger la cadena en las consultas SQL; podrían observarse resultados extraños al recuperar los datos.

# SQLite3::exec

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::exec — Ejecuta una consulta en una base de datos

### Descripción

public function SQLite3::exec(string `$query`): bool

Ejecuta una consulta en una base de datos.

> Nota: SQLite3 puede necesitar crear » archivos temporales durante la ejecución de consultas, por lo que los directorios respectivos deben ser escribibles.

### Parámetros

`query`

  La consulta SQL a ejecutar (típicamente, una consulta de tipo INSERT, UPDATE o DELETE).

### Valores devueltos

Devuelve `true` si la consulta se ejecutó con éxito, `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con SQLite3::exec()

    <?php
    $db = new SQLite3('mysqlitedb.db');

    $db->exec('CREATE TABLE bar (bar TEXT)');
    ?>

# SQLite3::lastErrorCode

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastErrorCode — Devuelve el código de error de la última consulta SQL que ha fallado

### Descripción

public function SQLite3::lastErrorCode(): int

Devuelve el código de error de la última consulta SQL que ha fallado.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un entero que representa el código de error de la última consulta que ha fallado.

# SQLite3::lastErrorMsg

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastErrorMsg — Devuelve el mensaje de error, en inglés, de la última consulta que ha fallado

### Descripción

public function SQLite3::lastErrorMsg(): string

Devuelve el mensaje de error, en inglés, de la última consulta que ha fallado.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el mensaje de error, en inglés, de la última consulta que ha fallado.

# SQLite3::lastInsertRowID

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastInsertRowID — Devuelve el identificador de la fila correspondiente a la última consulta de tipo INSERT

### Descripción

public function SQLite3::lastInsertRowID(): int

Devuelve el identificador de la fila correspondiente a la última consulta de tipo INSERT ejecutada en la base de datos.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el identificador de la fila correspondiente a la última consulta de tipo INSERT ejecutada en la base de datos. Si ninguna consulta de tipo INSERT en las tablas rowid ha tenido éxito en esta conexión de base de datos, entonces SQLite3::lastInsertRowID() devuelve `0`.

# SQLite3::loadExtension

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::loadExtension — Intenta cargar una extensión de la biblioteca SQLite

### Descripción

public function SQLite3::loadExtension(string `$name`): bool

Intenta cargar una extensión de la biblioteca SQLite.

### Parámetros

`name`

  El nombre de la extensión a cargar. La extensión debe encontrarse en el directorio especificado por la opción de configuración sqlite3.extension_dir.

### Valores devueltos

Devuelve `true` si la extensión se cargó con éxito, `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con SQLite3::loadExtension()

    <?php
    $db = new SQLite3('mysqlitedb.db');
    $db->loadExtension('libagg.so');
    ?>

# SQLite3::open

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::open — Abre una base de datos SQLite

### Descripción

public function SQLite3::open(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = ""): void

Abre una base de datos SQLite 3. Si el cifrado fue incluido durante la construcción de la base de datos, la clave correspondiente será utilizada.

### Parámetros

`filename`

  Ruta hacia la base de datos SQLite, o `:memory:` para utilizar la base de datos que se encuentra en la memoria RAM.

`flags`

  Banderas opcionales para determinar la manera de abrir la base de datos SQLite. Por omisión, será `SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE`.

  - `SQLITE3_OPEN_READONLY` : Abre la base de datos en modo solo lectura.

  - `SQLITE3_OPEN_READWRITE` : Abre la base de datos en modo lectura y escritura.

  - `SQLITE3_OPEN_CREATE` : Crea la base de datos si no existe.

`encryptionKey`

  La clave opcional de cifrado utilizada durante el cifrado/descifrado de la base de datos SQLite. Si el módulo de cifrado de SQLite no está instalado, este parámetro no tendrá ningún efecto.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con SQLite3::open()

    <?php
    /**
     * Ejemplo simple que extiende la clase SQLite3 y cambia los parámetros
     * __construct, luego, utiliza el método de conexión para inicializar la
     * base de datos.
     */
    class MyDB extends SQLite3
    {
        function __construct()
        {
            $this->open('mysqlitedb.db');
        }
    }

    $db = new MyDB();

    $db->exec('CREATE TABLE foo (bar STRING)');
    $db->exec("INSERT INTO foo (bar) VALUES ('Esto es una prueba')");

    $result = $db->query('SELECT bar FROM foo');
    var_dump($result->fetchArray());
    ?>

# SQLite3::openBlob

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::openBlob — Abre un flujo de recurso para leer un BLOB

### Descripción

public function SQLite3::openBlob(
string `$table`,
string `$column`,
int `$rowid`,
string `$database` = "main",
int `$flags` = `SQLITE3_OPEN_READONLY`
): resource|false

Abre un flujo de recurso para leer o escribir un BLOB, que sería seleccionado por:

SELECT `column` FROM `database`.`table` WHERE rowid = `rowid`

> Nota: No es posible cambiar el tamaño de un BLOB escribiendo en el flujo. En su lugar, una declaración UPDATE debe ser ejecutada, utilizando, eventualmente, la función zeroblob() de SQLite para definir el tamaño del BLOB deseado.

### Parámetros

`table`

  El nombre de la tabla.

`column`

  El nombre de la columna.

`rowid`

  La ID de la fila.

`database`

  El nombre simbólico de la base de datos.

`flags`

  O bien `SQLITE3_OPEN_READONLY` o `SQLITE3_OPEN_READWRITE` para abrir el flujo en modo de solo lectura o de lectura y escritura, respectivamente.

### Valores devueltos

Devuelve un recurso de flujo, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
7.2.0 | El argumento `flags` fue añadido, permitiendo escribir BLOBs; anteriormente solo la lectura era soportada.

### Ejemplos

Ejemplo #1 Ejemplo con SQLite3::openBlob()

    <?php
    $conn = new SQLite3(':memory:');
    $conn->exec('CREATE TABLE test (text text)');
    $conn->exec("INSERT INTO test VALUES ('Lorem ipsum')");
    $stream = $conn->openBlob('test', 'text', 1);
    echo stream_get_contents($stream);
    fclose($stream); // obligatorio, de lo contrario la siguiente línea fallaría
    $conn->close();
    ?>

El ejemplo anterior mostrará:

    Lorem ipsum

Ejemplo #2 Escribir progresivamente un BLOB

    <?php
    $conn = new SQLite3(':memory:');
    $conn->exec('CREATE TABLE test (text text)');
    $conn->exec("INSERT INTO test VALUES (zeroblob(36))");
    $stream = $conn->openBlob('test', 'text', 1, 'main', SQLITE3_OPEN_READWRITE);
    for ($i = 0; $i < 3; $i++) {
        fwrite($stream,  "Lorem ipsum\n");
    }
    fclose($stream);
    echo $conn->querySingle("SELECT text FROM test");
    $conn->close();
    ?>

El ejemplo anterior mostrará:

    Lorem ipsum
    Lorem ipsum
    Lorem ipsum

# SQLite3::prepare

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::prepare — Prepara una consulta SQL para su ejecución

### Descripción

public function SQLite3::prepare(string `$query`): SQLite3Stmt|false

Prepara una consulta SQL para su ejecución y devuelve un objeto SQLite3Stmt.

### Parámetros

`query`

  La consulta SQL a preparar.

### Valores devueltos

Devuelve un objeto SQLite3Stmt en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con SQLite3::prepare()

    <?php
    unlink('mysqlitedb.db');
    $db = new SQLite3('mysqlitedb.db');

    $db->exec('CREATE TABLE foo (id INTEGER, bar STRING)');
    $db->exec("INSERT INTO foo (id, bar) VALUES (1, 'Ceci est un test')");

    $stmt = $db->prepare('SELECT bar FROM foo WHERE id=:id');
    $stmt->bindValue(':id', 1, SQLITE3_INTEGER);

    $result = $stmt->execute();
    var_dump($result->fetchArray());
    ?>

### Ver también

- SQLite3Stmt::paramCount() - Devuelve el número de argumentos de una consulta preparada
- SQLite3Stmt::bindValue() - Asocia el valor de un parámetro a una variable de declaración
- SQLite3Stmt::bindParam() - Asocia un parámetro a una variable de declaración

# SQLite3::query

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::query — Ejecuta una consulta SQL

### Descripción

public function SQLite3::query(string `$query`): SQLite3Result|false

Ejecuta una consulta SQL y devuelve un objeto SQLite3Result. Si la consulta no genera resultados (como las instrucciones DML), el objeto SQLite3Result devuelto no es realmente utilizable. Utilice sqlite3::exec() para estas consultas en su lugar.

### Parámetros

`query`

  La consulta SQL a ejecutar.

### Valores devueltos

Devuelve un objeto SQLite3Result, o `false` si ocurre un error

### Ejemplos

Ejemplo #1 Ejemplo con SQLite3::query()

    <?php
    $db = new SQLite3('mysqlitedb.db');

    $results = $db->query('SELECT bar FROM foo');
    while ($row = $results->fetchArray()) {
        var_dump($row);
    }
    ?>

# SQLite3::querySingle

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::querySingle — Ejecuta una consulta y devuelve un único resultado

### Descripción

public function SQLite3::querySingle(string `$query`, bool `$entireRow` = `false`): mixed

Ejecuta una consulta y devuelve un único resultado.

### Parámetros

`query`

  La consulta SQL a ejecutar.

`entireRow`

  Por omisión, esta función devuelve el valor de la primera columna devuelta por la consulta. Si `entireRow` es `true`, entonces la función devolverá un array que contiene toda la primera fila.

### Valores devueltos

Devuelve el valor de la primera columna del resultado, o un array que contiene toda la primera fila (si el argumento `entireRow` es `true`).

Si la consulta es válida pero no devuelve ningún resultado, `null` será devuelto si `entireRow` es `false`, de lo contrario se devuelve un array vacío.

Las consultas inválidas devolverán `false`.

### Ejemplos

Ejemplo #1 Ejemplo con SQLite3::querySingle()

    <?php
    $db = new SQLite3('mysqlitedb.db');

    var_dump($db->querySingle('SELECT username FROM user WHERE userid=1'));
    print_r($db->querySingle('SELECT username, email FROM user WHERE userid=1', true));
    ?>

Resultado del ejemplo anterior es similar a:

    string(5) "Scott"
    Array
    (
        [username] => Scott
        [email] => scott@example.com
    )

# SQLite3::setAuthorizer

(PHP 8)

SQLite3::setAuthorizer — Configura una función de retrollamada para utilizar como autorizador para limitar lo que una sentencia puede hacer

### Descripción

public function SQLite3::setAuthorizer(?callable `$callback`): bool

Define una función de retrollamada que será llamada por SQLite cada vez que se realiza una acción (lectura, eliminación, actualización, etc.). Esto se utiliza durante la preparación de una sentencia SQL a partir de una fuente no confiable para asegurarse de que las sentencias SQL no intenten acceder a datos a los que no están autorizadas a acceder, o que no intenten ejecutar sentencias maliciosas que dañen la base de datos. Por ejemplo, una aplicación puede autorizar a un usuario a introducir consultas SQL arbitrarias para evaluación por una base de datos. Pero la aplicación no quiere que el usuario pueda realizar modificaciones arbitrarias en la base de datos. Un autorizador podría entonces establecerse mientras el SQL introducido por el usuario es preparado para prohibir todo excepto las declaraciones SELECT.

La función de retrollamada del autorizador puede ser llamada varias veces para cada sentencia preparada por SQLite. Una consulta `SELECT` o `UPDATE` llamará al autorizador para cada columna que sería leída o actualizada.

La función de retrollamada del autorizador es llamada con hasta cinco parámetros. El primer parámetro siempre es proporcionado, y es un int (código de acción) correspondiente a una constante de `SQLite3`. Los otros parámetros solo se pasan para ciertas acciones. La tabla siguiente describe los parámetros segundo y tercero según la acción:

Lista de códigos de acción y parámetros
Acción | Segundo parámetro | Tercer parámetro
--- | --- | ---
`SQLite3::CREATE_INDEX` | Nombre del índice | Nombre de la tabla
`SQLite3::CREATE_TABLE` | Nombre de la tabla | `null`
`SQLite3::CREATE_TEMP_INDEX` | Nombre del índice | Nombre de la tabla
`SQLite3::CREATE_TEMP_TABLE` | Nombre de la tabla | `null`
`SQLite3::CREATE_TEMP_TRIGGER` | Nombre del disparador | Nombre de la tabla
`SQLite3::CREATE_TEMP_VIEW` | Nombre de la vista | `null`
`SQLite3::CREATE_TRIGGER` | Nombre del disparador | Nombre de la tabla
`SQLite3::CREATE_VIEW` | Nombre de la vista | `null`
`SQLite3::DELETE` | Nombre de la tabla | `null`
`SQLite3::DROP_INDEX` | Nombre del índice | Nombre de la tabla
`SQLite3::DROP_TABLE` | Nombre de la tabla | `null`
`SQLite3::DROP_TEMP_INDEX` | Nombre del índice | Nombre de la tabla
`SQLite3::DROP_TEMP_TABLE` | Nombre de la tabla | `null`
`SQLite3::DROP_TEMP_TRIGGER` | Nombre del disparador | Nombre de la tabla
`SQLite3::DROP_TEMP_VIEW` | Nombre de la vista | `null`
`SQLite3::DROP_TRIGGER` | Nombre del disparador | Nombre de la tabla
`SQLite3::DROP_VIEW` | Nombre de la vista | `null`
`SQLite3::INSERT` | Nombre de la tabla | `null`
`SQLite3::PRAGMA` | Nombre Pragma | El primer argumento pasado al pragma, o `null`
`SQLite3::READ` | Nombre de la tabla | Nombre de la columna
`SQLite3::SELECT` | `null` | `null`
`SQLite3::TRANSACTION` | Operación | `null`
`SQLite3::UPDATE` | Nombre de la tabla | Nombre de la columna
`SQLite3::ATTACH` | Nombre de fichero | `null`
`SQLite3::DETACH` | Nombre de la base de datos | `null`
`SQLite3::ALTER_TABLE` | Nombre de la base de datos | Nombre de la tabla
`SQLite3::REINDEX` | Nombre del índice | `null`
`SQLite3::ANALYZE` | Nombre de la tabla | `null`
`SQLite3::CREATE_VTABLE` | Nombre de la tabla | Nombre del módulo
`SQLite3::DROP_VTABLE` | Nombre de la tabla | Nombre del módulo
`SQLite3::FUNCTION` | `null` | Nombre de la función
`SQLite3::SAVEPOINT` | Operación | Nombre del punto de guardado
`SQLite3::RECURSIVE` | `null` | `null`

El cuarto parámetro será el nombre de la base de datos (`"main"`, `"temp"`, etc.) si es aplicable.

El quinto parámetro de la función de retrollamada del autorizador es el nombre del disparador o de la vista más interno que es responsable del intento de acceso o `null` si este intento de acceso proviene directamente del código SQL de nivel superior.

Cuando la función de retrollamada devuelve `SQLite3::OK`, significa que la operación solicitada es aceptada. Cuando la función de retrollamada devuelve `SQLite3::DENY`, la llamada que provocó el autorizador fallará con un mensaje de error explicando que el acceso es denegado.

Si el código de acción es `SQLite3::READ` y la función de retrollamada devuelve `SQLite3::IGNORE`, entonces la sentencia preparada se construye para sustituir un valor `null` en lugar de la columna de la tabla que se habría leído si `SQLite3::OK` se hubiera devuelto. Devolver `SQLite3::IGNORE` puede ser utilizado para denegar a un usuario no confiable el acceso a columnas individuales de una tabla.

Cuando una tabla es referenciada por un `SELECT` pero no se extrae ningún valor de columna de esa tabla (por ejemplo en una consulta como `"SELECT count(*) FROM table"`), entonces la función de retrollamada del autorizador se invoca una vez para esa tabla con un nombre de columna que es una cadena vacía.

Si el código de acción es `SQLite3::DELETE` y la función de retrollamada devuelve `SQLite3::IGNORE`, entonces la operación DELETE continúa pero la optimización de truncamiento es desactivada y todas las filas se eliminan individualmente.

Solo un autorizador puede estar activo en una conexión de base de datos a la vez. Cada llamada a SQLite3::setAuthorizer() reemplaza la llamada anterior. Desactive el autorizador instalando una retrollamada `null`. El autorizador está desactivado por omisión.

La función de retrollamada del autorizador no debe hacer nada que modifique la conexión de base de datos que ha invocado la función de retrollamada del autorizador.

Es importante señalar que el autorizador solo se llama cuando una sentencia es preparada, no cuando es ejecutada.

Más detalles pueden encontrarse en la » documentación de SQLite3.

### Parámetros

`callback`

  El callable a llamar.

  Si se pasa `null`, esto desactivará la retrollamada del autorizador actual.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Este método no lanza ningún error, pero si un autorizador está activado y devuelve un valor inválido, la preparación de la sentencia lanzará un error (o una excepción, según el uso del método SQLite3::enableExceptions()).

### Ejemplos

Ejemplo #1 Ejemplo de SQLite3::setAuthorizer()

Esto solo autoriza el acceso de lectura, y solo ciertas columnas de la tabla `users` serán devueltas. Las otras columnas serán reemplazadas por `null`.

    <?php
    $db = new SQLite3('data.sqlite');
    $db->exec('CREATE TABLE users (id, name, password);');
    $db->exec('INSERT INTO users VALUES (1, \'Pauline\', \'Snails4eva\');');

    $allowed_columns = ['id', 'name'];

    $db->setAuthorizer(function (int $action, ...$args) use ($allowed_columns) {
        if ($action === SQLite3::READ) {
            list($table, $column) = $args;

            if ($table === 'users' && in_array($column, $allowed_columns)) {
                return SQLite3::OK;
            }

            return SQLite3::IGNORE;
        }

        return SQLite3::DENY;
    });

    print_r($db->querySingle('SELECT * FROM users WHERE id = 1;'));

El ejemplo anterior mostrará:

    Array
    (
        [id] => 1
        [name] => Pauline
        [password] =>
    )

# SQLite3::version

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::version — Devuelve la versión de la biblioteca SQLite3

### Descripción

public static function SQLite3::version(): array

Devuelve la versión de la biblioteca SQLite3.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array asociativo que contiene las claves "versionString" y "versionNumber".

### Ejemplos

Ejemplo #1 Ejemplo con SQLite3::version()

    <?php
    print_r(SQLite3::version());
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [versionString] => 3.5.9
        [versionNumber] => 3005009
    )

## Tabla de contenidos

- SQLite3::backup — Realiza una copia de seguridad de una base de datos en otra base de datos
- SQLite3::busyTimeout — Define el gestor de espera de la conexión
- SQLite3::changes — Devuelve el número de líneas modificadas (o insertadas, borradas) por la última consulta SQL
- SQLite3::close — Cierra la conexión con la base de datos
- SQLite3::__construct — Instancia un objeto SQLite3 y abre la base de datos SQLite 3
- SQLite3::createAggregate — Registra una función PHP para ser utilizada como función de agregación SQLite
- SQLite3::createCollation — Registra una función PHP para utilizarla como función de clasificación SQL
- SQLite3::createFunction — Registra una función PHP para su uso como función escalar SQL
- SQLite3::enableExceptions — Activa el lanzamiento de excepciones
- SQLite3::escapeString — Devuelve una cadena limpiada
- SQLite3::exec — Ejecuta una consulta en una base de datos
- SQLite3::lastErrorCode — Devuelve el código de error de la última consulta SQL que ha fallado
- SQLite3::lastErrorMsg — Devuelve el mensaje de error, en inglés, de la última consulta que ha fallado
- SQLite3::lastInsertRowID — Devuelve el identificador de la fila correspondiente a la última consulta de tipo INSERT
- SQLite3::loadExtension — Intenta cargar una extensión de la biblioteca SQLite
- SQLite3::open — Abre una base de datos SQLite
- SQLite3::openBlob — Abre un flujo de recurso para leer un BLOB
- SQLite3::prepare — Prepara una consulta SQL para su ejecución
- SQLite3::query — Ejecuta una consulta SQL
- SQLite3::querySingle — Ejecuta una consulta y devuelve un único resultado
- SQLite3::setAuthorizer — Configura una función de retrollamada para utilizar como autorizador para limitar lo que una sentencia puede hacer
- SQLite3::version — Devuelve la versión de la biblioteca SQLite3

# La clase SQLite3Exception

(PHP 8 >= 8.3.0)

## Introducción

Representa una excepción específica de SQLite3.

## Sinopsis de la Clase

class SQLite3Exception extends Exception {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La clase SQLite3Stmt

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Introducción

La clase que representa los comandos preparados para una base de datos SQLite3.

## Sinopsis de la Clase

class SQLite3Stmt {
/* Métodos */
private function __construct(SQLite3 `$sqlite3`, string `$query`)
public function bindParam(string|int `$param`, mixed `&$var`, int `$type` = `SQLITE3_TEXT`): bool
public function bindValue(string|int `$param`, mixed `$value`, int `$type` = `SQLITE3_TEXT`): bool
public function clear(): bool
public function close(): true
public function execute(): SQLite3Result|false
public function getSQL(bool `$expand` = `false`): string|false
public function paramCount(): int
public function readOnly(): bool
public function reset(): bool
}

# SQLite3Stmt::bindParam

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::bindParam — Asocia un parámetro a una variable de declaración

### Descripción

public function SQLite3Stmt::bindParam(string|int `$param`, mixed `&$var`, int `$type` = `SQLITE3_TEXT`): bool

Asocia un parámetro a una variable de declaración.

Precaución

Antes de PHP 7.2.14 y 7.3.0, respectivamente, SQLite3Stmt::reset() debe ser llamado después del primer llamado a SQLite3Stmt::execute() si el valor asociado debe ser actualizado correctamente en los llamados siguientes a SQLite3Stmt::execute(). Si SQLite3Stmt::reset() no es llamado, los valores asociados no serán modificados, incluso si el valor asignado a la variable pasada a SQLite3Stmt::bindParam() ha sido modificado, o SQLite3Stmt::bindParam() ha sido llamado nuevamente.

### Parámetros

`param`
  Puede ser un string (para parámetros nombrados) o un int (para parámetros posicionales) que identifica la variable de declaración a la cual el valor debe ser asociado. Si un parámetro nombrado no comienza con un carácter "dos puntos" (`:`) o un arroba (`@`), "dos puntos" (`:`) serán automáticamente prefijados. Los parámetros posicionales comienzan con `1`.
`var`

  El parámetro a asociar a la variable de declaración.

`type`

  El tipo de datos del parámetro a asociar.

  - `SQLITE3_INTEGER` : El valor es un entero firmado, almacenado en 1, 2, 3, 4, 6, o 8 bytes, dependiendo del tamaño del valor.

  - `SQLITE3_FLOAT` : El valor es un número de punto flotante, almacenado en 8 bytes.

  - `SQLITE3_TEXT` : El valor es texto, almacenado utilizando la codificación de la base de datos (UTF-8, UTF-16BE o UTF-16-LE).

  - `SQLITE3_BLOB` : El valor es un BLOB, almacenado exactamente de la forma en que fue proporcionado.

  - `SQLITE3_NULL` : El valor es la valor NULL.

  A partir de PHP 7.0.7, si `type` es omitido, es automáticamente detectado desde el tipo de `var` : bool y int son tratados como `SQLITE3_INTEGER`, float como `SQLITE3_FLOAT`, `null` como `SQLITE3_NULL` y todos los demás como `SQLITE3_TEXT`. Anteriormente, si `type` era omitido, era por omisión `SQLITE3_TEXT`.

  > Nota:

  > Si `var` es `null`, siempre fue tratado como `SQLITE3_NULL`, independientemente del `type` proporcionado.

### Valores devueltos

Retorna `true` si el parámetro es asociado a la variable de declaración, `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
7.4.0 | `param` ahora soporta la notación `@param`.

### Ejemplos

Ejemplo #1 Uso de SQLite3Stmt::bindParam()

Este ejemplo muestra cómo una declaración preparada única con un solo parámetro asociado puede ser utilizada para insertar múltiples filas con valores diferentes.

    <?php
    $db = new SQLite3(':memory:');
    $db->exec("CREATE TABLE foo (bar TEXT)");

    $stmt = $db->prepare("INSERT INTO foo VALUES (:bar)");
    $stmt->bindParam(':bar', $bar, SQLITE3_TEXT);

    $bar = 'baz';
    $stmt->execute();

    $bar = 42;
    $stmt->execute();

    $res = $db->query("SELECT * FROM foo");
    while (($row = $res->fetchArray(SQLITE3_ASSOC))) {
        var_dump($row);
    }
    ?>

El ejemplo anterior mostrará:

    array(1) {
      ["bar"]=>
      string(3) "baz"
    }
    array(1) {
      ["bar"]=>
      string(2) "42"
    }

### Ver también

- SQLite3Stmt::bindValue() - Asocia el valor de un parámetro a una variable de declaración
- SQLite3::prepare() - Prepara una consulta SQL para su ejecución

# SQLite3Stmt::bindValue

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::bindValue — Asocia el valor de un parámetro a una variable de declaración

### Descripción

public function SQLite3Stmt::bindValue(string|int `$param`, mixed `$value`, int `$type` = `SQLITE3_TEXT`): bool

Asocia el valor de un parámetro a una variable de declaración.

Precaución

Antes de PHP 7.2.14 y 7.3.0, respectivamente, una vez que la declaración ha sido ejecutada SQLite3Stmt::reset() debe ser llamado para poder cambiar el valor de los parámetros asociados.

### Parámetros

`param`
  Puede ser un string (para parámetros nombrados) o un int (para parámetros posicionales) que identifica la variable de declaración a la cual el valor debe ser asociado. Si un parámetro nombrado no comienza con un carácter "dos puntos" (`:`) o un arroba (`@`), "dos puntos" (`:`) serán automáticamente prefijados. Los parámetros posicionales comienzan con `1`.
`value`

  El valor a asociar a la variable de declaración.

`type`

  El tipo de datos del valor a asociar.

  - `SQLITE3_INTEGER` : El valor es un entero firmado, almacenado en 1, 2, 3, 4, 6, o 8 bytes, según la magnitud del valor.

  - `SQLITE3_FLOAT` : El valor es un número de punto flotante, almacenado en 8 bytes.

  - `SQLITE3_TEXT` : El valor es texto, almacenado utilizando la codificación de la base de datos (UTF-8, UTF-16BE o UTF-16-LE).

  - `SQLITE3_BLOB` : El valor es un BLOB, almacenado exactamente de la forma en que fue proporcionado.

  - `SQLITE3_NULL` : El valor es la valor NULL.

  A partir de PHP 7.0.7, si `type` es omitido, es automáticamente detectado desde el tipo de `value` : bool y int son tratados como `SQLITE3_INTEGER`, float como `SQLITE3_FLOAT`, `null` como `SQLITE3_NULL` y todos los demás como `SQLITE3_TEXT`. Anteriormente, si `type` era omitido, era por omisión `SQLITE3_TEXT`.

  > Nota:

  > Si `value` es `null`, siempre fue tratado como `SQLITE3_NULL`, independientemente del `type` proporcionado.

### Valores devueltos

Retorna `true` si el valor fue asociado a la variable de declaración, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
7.4.0 | `param` ahora soporta la notación `@param`.

### Ejemplos

Ejemplo #1 Ejemplo con SQLite3Stmt::bindValue()

    <?php
    $db = new SQLite3(':memory:');

    $db->exec('CREATE TABLE foo (id INTEGER, bar STRING)');
    $db->exec("INSERT INTO foo (id, bar) VALUES (1, 'Esto es una prueba')");

    $stmt = $db->prepare('SELECT bar FROM foo WHERE id=:id');
    $stmt->bindValue(':id', 1, SQLITE3_INTEGER);

    $result = $stmt->execute();
    var_dump($result->fetchArray(SQLITE3_ASSOC));
    ?>

El ejemplo anterior mostrará:

    array(1) {
      ["bar"]=>
      string(18) "Esto es una prueba"
    }

### Ver también

- SQLite3Stmt::bindParam() - Asocia un parámetro a una variable de declaración
- SQLite3::prepare() - Prepara una consulta SQL para su ejecución

# SQLite3Stmt::clear

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::clear — Elimina todos los parámetros actualmente vinculados

### Descripción

public function SQLite3Stmt::clear(): bool

Elimina todos los parámetros actualmente vinculados (los define como `null`).

Precaución

Este método debe ser utilizado con SQLite3Stmt::reset(). Si se utiliza solo, cualquier llamada a SQLite3Stmt::bindValue() o SQLite3Stmt::bindParam() no tendrá efecto y todos los parámetros vinculados tendrán como valor `null`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si todos los parámetros actualmente vinculados han sido eliminados, `false` si ocurre un error.

# SQLite3Stmt::close

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::close — Cierra una consulta preparada

### Descripción

public function SQLite3Stmt::close(): true

Cierra una consulta preparada.

> Nota: Tenga en cuenta que todos los SQLite3Result que han sido recuperados al ejecutar esta instrucción serán invalidados cuando la instrucción sea cerrada.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

Se levanta una Error si el método es llamado sobre un objeto no inicializado.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Este método levanta ahora una excepción Error si el objeto no está correctamente inicializado. Anteriormente, retornaba `false`.

# SQLite3Stmt::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::__construct — Construye un objeto SQLite3Stmt

### Descripción

private function SQLite3Stmt::__construct(SQLite3 `$sqlite3`, string `$query`)

Las instancias de SQLite3Stmt son creadas por SQLite3::prepare().

### Parámetros

`sqlite3`

  El objeto SQLite3 al que pertenece la consulta.

`query`

  La consulta SQL a preparar.

# SQLite3Stmt::execute

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::execute — Ejecuta una consulta preparada

### Descripción

public function SQLite3Stmt::execute(): SQLite3Result|false

Ejecuta una consulta preparada y devuelve un objeto que representa el conjunto de resultados.

Precaución

Los objetos de conjunto de resultados recuperados mediante la llamada a este método sobre el mismo objeto de instrucción no son independientes, sino que comparten más bien la misma estructura subyacente. Por lo tanto, se recomienda llamar SQLite3Result::finalize(), antes de llamar de nuevo SQLite3Stmt::execute() sobre el mismo objeto de instrucción.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un objeto SQLite3Result si la consulta preparada se ha ejecutado con éxito, o `false` si ocurre un error.

### Ver también

- SQLite3::prepare() - Prepara una consulta SQL para su ejecución
- SQLite3Stmt::bindValue() - Asocia el valor de un parámetro a una variable de declaración
- SQLite3Stmt::bindParam() - Asocia un parámetro a una variable de declaración

# SQLite3Stmt::getSQL

(PHP 7 >= 7.4.0, PHP 8)

SQLite3Stmt::getSQL — Recupera el SQL de una declaración

### Descripción

public function SQLite3Stmt::getSQL(bool `$expand` = `false`): string|false

Recupera el SQL de una declaración preparada. Si `expand` es `false`, se recupera el SQL sin modificar. Si `expand` es `true`, todos los parámetros de la consulta son reemplazados con sus valores vinculados, o con un `NULL` SQL, si no están aún vinculados.

### Parámetros

`expand`

  Si se debe recuperar el código SQL extendido. Pasar `true` solo es soportado a partir de libsqlite 3.14.

### Valores devueltos

Devuelve el SQL de la declaración preparada, o `false` si ocurre un error.

### Errores/Excepciones

Si `expand` es `true`, pero la versión de libsqlite es menor que 3.14, se emite un error de nivel `E_WARNING` o una Exception, de acuerdo con SQLite3::enableExceptions().

### Ejemplos

Ejemplo #1 Inspeccionar el SQL extendido

    <?php
    $db = new SQLite3(':memory:');
    $stmt = $db->prepare("SELECT :a, ?, :c");
    $stmt->bindValue(':a', 'foo');
    $answer = 42;
    $stmt->bindParam(2, $answer);
    var_dump($stmt->getSQL(true));
    ?>

Resultado del ejemplo anterior es similar a:

    string(24) "SELECT 'foo', '42', NULL"

# SQLite3Stmt::paramCount

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::paramCount — Devuelve el número de argumentos de una consulta preparada

### Descripción

public function SQLite3Stmt::paramCount(): int

Devuelve el número de argumentos de una consulta preparada.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de argumentos de una consulta preparada.

### Ver también

- SQLite3::prepare() - Prepara una consulta SQL para su ejecución

# SQLite3Stmt::readOnly

(PHP 5 >= 5.3.6, PHP 7, PHP 8)

SQLite3Stmt::readOnly — Determina si una declaración es de solo lectura

### Descripción

public function SQLite3Stmt::readOnly(): bool

Determina si una declaración es de solo lectura. Una declaración es considerada de solo lectura si no realiza ningún cambio directo al contenido del archivo de la base de datos. Notar que las funciones SQL definidas por el usuario pueden indirectamente cambiar la base de datos como efecto secundario.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si la declaración es de solo lectura, `false` en caso contrario.

# SQLite3Stmt::reset

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::reset — Reinicia una consulta preparada

### Descripción

public function SQLite3Stmt::reset(): bool

Reinicia una consulta preparada, de tal manera que se recupera su estado inicial, antes de la ejecución. Todos los marcadores permanecerán intactos después de esta operación.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si la consulta preparada ha sido correctamente reiniciada, o `false` si ocurre un error.

## Tabla de contenidos

- SQLite3Stmt::bindParam — Asocia un parámetro a una variable de declaración
- SQLite3Stmt::bindValue — Asocia el valor de un parámetro a una variable de declaración
- SQLite3Stmt::clear — Elimina todos los parámetros actualmente vinculados
- SQLite3Stmt::close — Cierra una consulta preparada
- SQLite3Stmt::__construct — Construye un objeto SQLite3Stmt
- SQLite3Stmt::execute — Ejecuta una consulta preparada
- SQLite3Stmt::getSQL — Recupera el SQL de una declaración
- SQLite3Stmt::paramCount — Devuelve el número de argumentos de una consulta preparada
- SQLite3Stmt::readOnly — Determina si una declaración es de solo lectura
- SQLite3Stmt::reset — Reinicia una consulta preparada

# La clase SQLite3Result

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Introducción

Una clase que representa los resultados de una base de datos SQLite 3.

## Sinopsis de la Clase

class SQLite3Result {
/* Métodos */
private function __construct()
public function columnName(int `$column`): string|false
public function columnType(int `$column`): int|false
public function fetchArray(int `$mode` = `SQLITE3_BOTH`): array|false
public function finalize(): true
public function numColumns(): int
public function reset(): bool
}

# SQLite3Result::columnName

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::columnName — Devuelve el nombre de una columna

### Descripción

public function SQLite3Result::columnName(int `$column`): string|false

Devuelve el nombre de la columna identificada por el argumento `column`. Cabe señalar que el nombre de la columna de resultado y el valor de la cláusula `AS` para esta columna, si existe una cláusula `AS`. Si no hay cláusula, el nombre de la columna es no especificado y puede cambiar de una versión de libsqlite3 a otra.

### Parámetros

`column`

  El número de la columna, comenzando desde 0.

### Valores devueltos

Devuelve el nombre de la columna identificada por el argumento `column`, o `false` si la columna no existe.

# SQLite3Result::columnType

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::columnType — Devuelve el tipo de una columna

### Descripción

public function SQLite3Result::columnType(int `$column`): int|false

Devuelve el tipo de la columna identificada por el argumento `column`.

### Parámetros

`column`

  El número de la columna, comenzando por 0.

### Valores devueltos

Devuelve el tipo de datos de la columna identificada por `column` (uno de `SQLITE3_INTEGER`, `SQLITE3_FLOAT`, `SQLITE3_TEXT`, `SQLITE3_BLOB`, o `SQLITE3_NULL`), o `false` si la columna no existe.

# SQLite3Result::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::__construct — Construye un SQLite3Result

### Descripción

private function SQLite3Result::__construct()

Las instancias de SQLite3Result son creadas por SQLite3::query() y SQLite3Stmt::execute().

### Parámetros

Esta función no contiene ningún parámetro.

# SQLite3Result::fetchArray

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::fetchArray — Recupera un conjunto de resultados en forma de array

### Descripción

public function SQLite3Result::fetchArray(int `$mode` = `SQLITE3_BOTH`): array|false

Recupera un conjunto de resultados en forma de array asociativo o indexado numéricamente, o ambos. Por omisión, se obtienen ambos.

### Parámetros

`mode`

  Controla la forma en que la siguiente línea debe ser devuelta a la función llamante. Este valor puede ser `SQLITE3_ASSOC`, `SQLITE3_NUM`, o `SQLITE3_BOTH`.

  - `SQLITE3_ASSOC` : Devuelve un array indexado por el nombre de la columna, tal como se devuelve en el conjunto de resultados correspondiente.

  - `SQLITE3_NUM` : Devuelve un array indexado por el número de la columna, tal como se devuelve en el conjunto de resultados, comenzando por la columna 0.

  - `SQLITE3_BOTH` : Devuelve un array indexado por el nombre y el número de la columna, tal como se devuelve por el conjunto de resultados, comenzando por la columna 0.

### Valores devueltos

Devuelve una línea del conjunto de resultados, en forma de array asociativo, o en forma de array indexado, o ambos. Devuelve `false` si no hay más líneas.

Los tipos de los valores del array devuelto son mapeados desde tipos SQLite3 de la siguiente manera: los enteros son mapeados a int si se ajustan al rango `PHP_INT_MIN`.. `PHP_INT_MAX`, y a string en caso contrario. Los números de punto flotante son mapeados a float, los valores `null` son mapeados a null, y las cadenas y los objetos BLOB son mapeados a string.

# SQLite3Result::finalize

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::finalize — Cierra un conjunto de resultados

### Descripción

public function SQLite3Result::finalize(): true

Cierra un conjunto de resultados.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

Se produce una excepción Error si el método se invoca sobre un objeto no inicializado.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Este método genera ahora una excepción Error si el objeto no está correctamente inicializado. Anteriormente, devolvía `false`.

# SQLite3Result::numColumns

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::numColumns — Devuelve el número de columnas del conjunto de resultados

### Descripción

public function SQLite3Result::numColumns(): int

Devuelve el número de columnas del conjunto de resultados.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de columnas del conjunto de resultados.

# SQLite3Result::reset

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::reset — Reposiciona el puntero en la primera línea del conjunto de resultados

### Descripción

public function SQLite3Result::reset(): bool

Reposiciona el puntero en la primera línea del conjunto de resultados.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si el conjunto de resultados ha sido reestablecido con éxito, `false` si ocurre un error.

## Tabla de contenidos

- SQLite3Result::columnName — Devuelve el nombre de una columna
- SQLite3Result::columnType — Devuelve el tipo de una columna
- SQLite3Result::__construct — Construye un SQLite3Result
- SQLite3Result::fetchArray — Recupera un conjunto de resultados en forma de array
- SQLite3Result::finalize — Cierra un conjunto de resultados
- SQLite3Result::numColumns — Devuelve el número de columnas del conjunto de resultados
- SQLite3Result::reset — Reposiciona el puntero en la primera línea del conjunto de resultados

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
- Constantes predefinidas
- SQLite3 — La clase SQLite3
  - SQLite3::backup — Realiza una copia de seguridad de una base de datos en otra base de datos
  - SQLite3::busyTimeout — Define el gestor de espera de la conexión
  - SQLite3::changes — Devuelve el número de líneas modificadas (o insertadas, borradas) por la última consulta SQL
  - SQLite3::close — Cierra la conexión con la base de datos
  - SQLite3::__construct — Instancia un objeto SQLite3 y abre la base de datos SQLite 3
  - SQLite3::createAggregate — Registra una función PHP para ser utilizada como función de agregación SQLite
  - SQLite3::createCollation — Registra una función PHP para utilizarla como función de clasificación SQL
  - SQLite3::createFunction — Registra una función PHP para su uso como función escalar SQL
  - SQLite3::enableExceptions — Activa el lanzamiento de excepciones
  - SQLite3::escapeString — Devuelve una cadena limpiada
  - SQLite3::exec — Ejecuta una consulta en una base de datos
  - SQLite3::lastErrorCode — Devuelve el código de error de la última consulta SQL que ha fallado
  - SQLite3::lastErrorMsg — Devuelve el mensaje de error, en inglés, de la última consulta que ha fallado
  - SQLite3::lastInsertRowID — Devuelve el identificador de la fila correspondiente a la última consulta de tipo INSERT
  - SQLite3::loadExtension — Intenta cargar una extensión de la biblioteca SQLite
  - SQLite3::open — Abre una base de datos SQLite
  - SQLite3::openBlob — Abre un flujo de recurso para leer un BLOB
  - SQLite3::prepare — Prepara una consulta SQL para su ejecución
  - SQLite3::query — Ejecuta una consulta SQL
  - SQLite3::querySingle — Ejecuta una consulta y devuelve un único resultado
  - SQLite3::setAuthorizer — Configura una función de retrollamada para utilizar como autorizador para limitar lo que una sentencia puede hacer
  - SQLite3::version — Devuelve la versión de la biblioteca SQLite3
- SQLite3Exception — La clase SQLite3Exception
- SQLite3Stmt — La clase SQLite3Stmt
  - SQLite3Stmt::bindParam — Asocia un parámetro a una variable de declaración
  - SQLite3Stmt::bindValue — Asocia el valor de un parámetro a una variable de declaración
  - SQLite3Stmt::clear — Elimina todos los parámetros actualmente vinculados
  - SQLite3Stmt::close — Cierra una consulta preparada
  - SQLite3Stmt::__construct — Construye un objeto SQLite3Stmt
  - SQLite3Stmt::execute — Ejecuta una consulta preparada
  - SQLite3Stmt::getSQL — Recupera el SQL de una declaración
  - SQLite3Stmt::paramCount — Devuelve el número de argumentos de una consulta preparada
  - SQLite3Stmt::readOnly — Determina si una declaración es de solo lectura
  - SQLite3Stmt::reset — Reinicia una consulta preparada
- SQLite3Result — La clase SQLite3Result
  - SQLite3Result::columnName — Devuelve el nombre de una columna
  - SQLite3Result::columnType — Devuelve el tipo de una columna
  - SQLite3Result::__construct — Construye un SQLite3Result
  - SQLite3Result::fetchArray — Recupera un conjunto de resultados en forma de array
  - SQLite3Result::finalize — Cierra un conjunto de resultados
  - SQLite3Result::numColumns — Devuelve el número de columnas del conjunto de resultados
  - SQLite3Result::reset — Reposiciona el puntero en la primera línea del conjunto de resultados

# Controlador Microsoft SQL Server para PHP

# Introducción

La extensión SQLSRV permite acceder a un servidor de base de datos Microsoft SQL y SQL Azure. La versión 3.0 del controlador soporta SQL Server, comenzando por SQL Server 2005, e incluyendo SQL Server 2012 y SQL Server 2012 LocalDB (para más información acerca de LocalDB, ver » el controlador PHP para el soporte de SQL Server para LocalDB y » SQL Server 2012 Express LocalDB.)

La extensión SQLSRV es soportada por Microsoft y está disponible para descargar aquí : » http://msdn.microsoft.com/en-us/sqlserver/ff657782.aspx. SQL Server 2012 LocalDB puede ser descargado aquí : » http://go.microsoft.com/fwlink/?LinkID=237665.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución
- Tipos de recursos

## Requerimientos

La extensión SQLSRV puede ser utilizada en los siguientes sistemas operativos:

- Windows Vista Service Pack 2 o superior
- Windows Server 2008 Service Pack 2 o superior
- Windows Server 2008 R2
- Windows 7

La extensión SQLSRV requiere que el cliente nativo Microsoft SQL Server 2012 esté instalado en la misma máquina que la que ejecuta PHP. Si el cliente nativo Microsoft SQL Server 2012 no está instalado, haga clic en el enlace apropiado a continuación para descargarlo:

- » Descarga del paquete x86
- » Descarga del paquete x64

La descarga SQLSRV viene con 8 controladores, de los cuales 4 están dedicados al soporte de PDO.

La versión más reciente del controlador está disponible para descargar aquí: » descarga de SQLSRV.

Para más información sobre los requisitos previos de SQLSRV, consulte el capítulo sobre los » requisitos del sistema SQLSRV.

## Instalación

La extensión SQLSRV se activa añadiendo la biblioteca DLL correspondiente en el directorio de extensiones de PHP y añadiendo la entrada correspondiente en el archivo php.ini. La descarga de SQLSRV incluye 8 controladores, de los cuales 4 están dedicados al soporte de PDO.

La versión más reciente del controlador está disponible para su descarga aquí : » descarga de SQLSRV.

Para obtener más información sobre los requisitos previos de SQLSRV, consúltese el capítulo sobre los » requisitos del sistema SQLSRV.

A partir de la versión 4.0, la extensión SQLSRV solo es compatible cuando PHP 7.0 funciona en Linux o Windows.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

La tabla siguiente lista las opciones de configuración disponibles para la extensión. Para más información sobre estas opciones, consúltese el capítulo sobre la » gestión de errores y alertas SQLSRV.

Opciones de configuración SQLSRV
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
sqlsrv.WarningsReturnAsErrors | 1 (`true`) | `INI_ALL` | Disponible a partir de SQLSRV 1.0
sqlsrv.LogSubsystems | 0 | `INI_ALL` | Disponible a partir de SQLSRV 1.0
sqlsrv.LogSeverity | 1 | `INI_ALL` | Disponible a partir de SQLSRV 1.0

## Tipos de recursos

## Recurso de conexión

Un recurso de conexión devuelto por la función sqlsrv_connect().

## Recurso de consulta

Un recurso de consulta devuelto por la función sqlsrv_query() o la función sqlsrv_prepare().

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`SQLSRV_FETCH_ASSOC` (int)
  Obliga a sqlsrv_fetch_array() a devolver un array asociativo cuando se le pasa como argumento.
`SQLSRV_FETCH_NUMERIC` (int)
  Obliga a sqlsrv_fetch_array() a devolver un array indexado numéricamente cuando se le pasa como argumento.
`SQLSRV_FETCH_BOTH` (int)
  Obliga a sqlsrv_fetch_array() a devolver un array asociativo y un array indexado numéricamente cuando se le pasa como argumento (comportamiento por defecto).
`SQLSRV_ERR_ALL` (int)
  Obliga a sqlsrv_errors() a devolver los errores y advertencias cuando se le pasa como argumento (comportamiento por defecto).
`SQLSRV_ERR_ERRORS` (int)
  Obliga a sqlsrv_errors() a devolver solo los errores (no las advertencias) cuando se le pasa como argumento.
`SQLSRV_ERR_WARNINGS` (int)
  Obliga a sqlsrv_errors() a devolver solo las advertencias (no los errores) cuando se le pasa como argumento.
`SQLSRV_LOG_SYSTEM_ALL` (int)
  Activa los logs de todos los subsistemas cuando se le pasa a la función sqlsrv_configure() como argumento.
`SQLSRV_LOG_SYSTEM_CONN` (int)
  Activa los logs de toda la actividad de las conexiones cuando se le pasa a la función sqlsrv_configure() como argumento.
`SQLSRV_LOG_SYSTEM_INIT` (int)
  Activa los logs de toda la actividad de las inicializaciones cuando se le pasa a la función sqlsrv_configure() como argumento.
`SQLSRV_LOG_SYSTEM_OFF` (int)
  Desactiva los logs de todos los subsistemas cuando se le pasa a la función sqlsrv_configure() como argumento.
`SQLSRV_LOG_SYSTEM_STMT` (int)
  Activa los logs de las consultas cuando se le pasa a la función sqlsrv_configure() como argumento.
`SQLSRV_LOG_SYSTEM_UTIL` (int)
  Activa los logs de los errores de función cuando se le pasa a la función sqlsrv_configure() como argumento.
`SQLSRV_LOG_SEVERITY_ALL` (int)
  Activa los logs de los errores, advertencias y notas cuando se le pasa a la función sqlsrv_configure() como argumento.
`SQLSRV_LOG_SEVERITY_ERROR` (int)
  Especifica que los errores serán registrados cuando se le pasa a la función sqlsrv_configure() como argumento.
`SQLSRV_LOG_SEVERITY_NOTICE` (int)
  Especifica que las notas serán registradas cuando se le pasa a la función sqlsrv_configure() como argumento.
`SQLSRV_LOG_SEVERITY_WARNING` (int)
  Especifica que las advertencias serán registradas cuando se le pasa a la función sqlsrv_configure() como argumento.
`SQLSRV_NULLABLE_YES` (int)
  Indica que una columna puede ser nula.
`SQLSRV_NULLABLE_NO` (int)
  Indica que una columna no puede ser nula.
`SQLSRV_NULLABLE_UNKNOWN` (int)
  Indica si se conoce que una columna es nula.
`SQLSRV_PARAM_IN` (int)
  Indica un parámetro de entrada cuando se le pasa a la función sqlsrv_query() o a la función sqlsrv_prepare().
`SQLSRV_PARAM_INOUT` (int)
  Indica un parámetro de entrada o salida cuando se le pasa a la función sqlsrv_query() o a la función sqlsrv_prepare().
`SQLSRV_PARAM_OUT` (int)
  Indica un parámetro de salida cuando se le pasa a la función sqlsrv_query() o a la función sqlsrv_prepare().
`SQLSRV_PHPTYPE_INT` (int)
  Especifica un dato de tipo entero PHP. Para más información, ver » Cómo especificar los tipos PHP.
`SQLSRV_PHPTYPE_DATETIME` (int)
  Especifica un dato de tipo datetime (fecha y hora) PHP. Para más información, ver » Cómo especificar los tipos PHP.
`SQLSRV_PHPTYPE_FLOAT` (int)
  Especifica un dato de tipo número de punto flotante PHP. Para más información, ver » Cómo especificar los tipos PHP.
`SQLSRV_PHPTYPE_STREAM` (int)
  Especifica un dato de tipo flujo de PHP. Esta constante funciona como una función y acepta una constante codificada. Ver las constantes SQLSRV_ENC_*. Para más información, reportez-vous a » Cómo especificar los tipos PHP.
`SQLSRV_PHPTYPE_STRING` (int)
  Especifica un dato de tipo string PHP. Esta constante funciona como una función y acepta una constante codificada. Ver las constantes SQLSRV_ENC_*. Para más información, reportez-vous a » Cómo especificar los tipos PHP.
`SQLSRV_ENC_BINARY` (int)
  Especifica que el dato es devuelto en forma de flujo bruto de bytes desde el servidor sin realizar un codificación o transformación. Para más información, reportez-vous a » Cómo especificar los tipos PHP.
`SQLSRV_ENC_CHAR` (int)
  El dato es devuelto en forma de caracteres de 8 bits, tal como se especifica en la página de códigos Windows local, definida en el sistema. Cualquier carácter multibyte o caracteres que no correspondan a esta página de código serán sustituidos con un signo de interrogación de un byte (?). Es la codificación por defecto. Para más información, reportez-vous a » Cómo especificar los tipos PHP.
`SQLSRV_SQLTYPE_BIGINT` (int)
  Describe el tipo de datos bigint de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_BINARY` (int)
  Describe el tipo de datos binario de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_BIT` (int)
  Describe el tipo de datos bit de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_CHAR` (int)
  Describe el tipo de datos carácter de SQL Server. Esta constante funciona como una función y acepta un argumento indicando el número de caracteres. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_DATE` (int)
  Describe el tipo de datos date de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_DATETIME` (int)
  Describe el tipo de datos datetime de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_DATETIME2` (int)
  Describe el tipo de datos datetime2 de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_DATETIMEOFFSET` (int)
  Describe el tipo de datos datetimeoffset de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_DECIMAL` (int)
  Describe el tipo de datos decimal. Esta constante funciona como una función y acepta 2 argumentos indicando (en orden) la precisión y la escala. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_FLOAT` (int)
  Describe el tipo de datos número de punto flotante de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_IMAGE` (int)
  Describe el tipo de datos image de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_INT` (int)
  Describe el tipo de datos entero de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_MONEY` (int)
  Describe el tipo de datos moneda de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_NCHAR` (int)
  Describe el tipo de datos nchar de SQL Server. Esta constante funciona como una función y acepta un solo argumento indicando el número de caracteres. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_NUMERIC` (int)
  Describe el tipo de datos numérico de SQL Server. Esta constante funciona como una función y acepta 2 argumentos (en orden), la precisión y la escala. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_NVARCHAR` (int)
  Describe el tipo de datos nvarchar de SQL Server. Esta constante funciona como una función y acepta un solo argumento indicando el número de caracteres. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_NVARCHAR('max')` (int)
  Describe el tipo de datos nvarchar(MAX) de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_NTEXT` (int)
  Describe el tipo de datos ntext de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_REAL` (int)
  Describe el tipo de datos real de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_SMALLDATETIME` (int)
  Describe el tipo de datos smalldatetime de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_SMALLINT` (int)
  Describe el tipo de datos smallint de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_SMALLMONEY` (int)
  Describe el tipo de datos smallmoney de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_TEXT` (int)
  Describe el tipo de datos texto de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_TIME` (int)
  Describe el tipo de datos time de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_TIMESTAMP` (int)
  Describe el tipo de datos timestamp de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_TINYINT` (int)
  Describe el tipo de datos tinyint de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_UNIQUEIDENTIFIER` (int)
  Describe el tipo de datos uniqueidentifier de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_UDT` (int)
  Describe el tipo de datos UDT de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_VARBINARY` (int)
  Describe el tipo de datos varbinary de SQL Server. Esta constante funciona como una función y acepta un solo argumento indicando el número de bytes. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_VARBINARY('max')` (int)
  Describe el tipo de datos varbinary(MAX) de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_VARCHAR` (int)
  Describe el tipo de datos varchar de SQL Server. Esta constante funciona como una función y acepta un solo argumento indicando el número de caracteres. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_VARCHAR('max')` (int)
  Describe el tipo de datos varchar(MAX) de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_SQLTYPE_XML` (int)
  Describe el tipo de datos XML de SQL Server. Para más información, reportez-vous a » Cómo especificar los tipos SQL.
`SQLSRV_TXN_READ_UNCOMMITTED` (int)
  Indica un nivel de aislamiento de la transacción a READ UNCOMMITTED. Este valor se utiliza para definir el nivel de aislamiento de la transacción en el array $connectionOptions pasado a la función sqlsrv_connect().
`SQLSRV_TXN_READ_COMMITTED` (int)
  Indica un nivel de aislamiento de la transacción a READ COMMITTED. Este valor se utiliza para definir el nivel de aislamiento de la transacción en el array $connectionOptions pasado a la función sqlsrv_connect().
`SQLSRV_TXN_REPEATABLE_READ` (int)
  Indica un nivel de aislamiento de la transacción a REPEATABLE READ. Este valor se utiliza para definir el nivel de aislamiento de la transacción en el array $connectionOptions pasado a la función sqlsrv_connect().
`SQLSRV_TXN_SNAPSHOT` (int)
  Indica un nivel de aislamiento de la transacción a SNAPSHOT. Este valor se utiliza para definir el nivel de aislamiento de la transacción en el array $connectionOptions pasado a la función sqlsrv_connect().
`SQLSRV_TXN_READ_SERIALIZABLE` (int)
  Indica un nivel de aislamiento de la transacción a SERIALIZABLE. Este valor se utiliza para definir el nivel de aislamiento de la transacción en el array $connectionOptions pasado a la función sqlsrv_connect().
`SQLSRV_CURSOR_FORWARD` (int)
  Indica un cursor de tipo "solo hacia adelante". Para más información, reportez-vous a la sección sobre » la especificación de un tipo de cursor y la selección de filas.
`SQLSRV_CURSOR_STATIC` (int)
  Indica un cursor de tipo "estático". Para más información, reportez-vous a la sección sobre » la especificación de un tipo de cursor y la selección de filas.
`SQLSRV_CURSOR_DYNAMIC` (int)
  Indica un cursor de tipo "dinámico". Para más información, reportez-vous a la sección sobre » la especificación de un tipo de cursor y la selección de filas.
`SQLSRV_CURSOR_KEYSET` (int)
  Indica un cursor de tipo "keyset". Para más información, reportez-vous a la sección sobre » la especificación de un tipo de cursor y la selección de filas.
`SQLSRV_CURSOR_BUFFERED` (int)
  Crea una consulta de cursor del lado del cliente. Esto permite acceder a las filas en cualquier orden. Para más información sobre su uso, reportez-vous a la sección sobre » la especificación de un tipo de cursor y la selección de filas.
`SQLSRV_SCROLL_NEXT` (int)
  Especifica la fila a seleccionar en un conjunto de resultados. Para más información, reportez-vous a la sección sobre » la especificación de un tipo de cursor y la selección de filas.
`SQLSRV_SCROLL_PRIOR` (int)
  Especifica la fila a seleccionar en un conjunto de resultados. Para más información, reportez-vous a la sección sobre » la especificación de un tipo de cursor y la selección de filas.
`SQLSRV_SCROLL_FIRST` (int)
  Especifica la fila a seleccionar en un conjunto de resultados. Para más información, reportez-vous a la sección sobre » la especificación de un tipo de cursor y la selección de filas.
`SQLSRV_SCROLL_LAST` (int)
  Especifica la fila a seleccionar en un conjunto de resultados. Para más información, reportez-vous a la sección sobre » la especificación de un tipo de cursor y la selección de filas.
`SQLSRV_SCROLL_ABSOLUTE` (int)
  Especifica la fila a seleccionar en un conjunto de resultados. Para más información, reportez-vous a la sección sobre » la especificación de un tipo de cursor y la selección de filas.
`SQLSRV_SCROLL_RELATIVE` (int)
  Especifica la fila a seleccionar en un conjunto de resultados. Para más información, reportez-vous a la sección sobre » la especificación de un tipo de cursor y la selección de filas.

# SQLSRV Funciones

# sqlsrv_begin_transaction

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

sqlsrv_begin_transaction — Inicia una transacción de base de datos

### Descripción

function sqlsrv_begin_transaction(resource `$conn`): bool

La transacción iniciada por sqlsrv_begin_transaction() incluye todas las sentencias que fueron ejecutadas después de la llamada a sqlsrv_begin_transaction() y antes de llamar a sqlsrv_rollback() o sqlsrv_commit(). Las transacciones explícitas deben empezar y ser consolidadas (commit) o revertidas utilizando estas funciones en vez de ejecutar sentencias SQL que empiecen y consoliden/reviertan transacciones. Para más información, ver » SQLSRV Transactions.

### Parámetros

`conn`
  El recurso de la conexión devuelta por una llamada a sqlsrv_connect().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de sqlsrv_begin_transaction()

El siguiente ejemplo demuestra cómo utilizar sqlsrv_begin_transaction() junto con sqlsrv_commit() y sqlsrv_rollback().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true ));
    }

    /* Iniciar la transacción. */
    if ( sqlsrv_begin_transaction( $conn ) === false ) {
         die( print_r( sqlsrv_errors(), true ));
    }

    /* Inicializar los parámetros. */
    $orderId = 1; $qty = 10; $productId = 100;

    /* Preprar y ejecutar la primera sentencia . */
    $sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
              VALUES (?, ?, ?)";
    $params1 = array( $orderId, $qty, $productId );
    $stmt1 = sqlsrv_query( $conn, $sql1, $params1 );

    /* Preparar y ejecutar la segunda sentencia. */
    $sql2 = "UPDATE InventoryTable
              SET Quantity = (Quantity - ?)
              WHERE ProductID = ?";
    $params2 = array($qty, $productId);
    $stmt2 = sqlsrv_query( $conn, $sql2, $params2 );

    /* Si ambas sentencias finalizaran con éxito, consolidar la transacción. */
    /* En caso contrario, revertirla. */
    if( $stmt1 && $stmt2 ) {
         sqlsrv_commit( $conn );
         echo "Transaccion consolidada.<br />";
    } else {
         sqlsrv_rollback( $conn );
         echo "Transaccion revertida.<br />";
    }
    ?>

Resultado del ejemplo anterior es similar a:

### Ver también

- sqlsrv_commit() - Consolida una transacción que se inició con sqlsrv_begin_transaction
- sqlsrv_rollback() - Anula una transacción que ha sido iniciada gracias a la función sqlsrv_begin_transaction

# sqlsrv_cancel

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

sqlsrv_cancel — Cancela una sentencia de base de datos

### Descripción

function sqlsrv_cancel(resource `$stmt`): bool

Cancela una sentencia de base de datos. Cualquier resultado asociado con la sentencia que no haya sido utilizado será eliminado. Después de llamar a sqlsrv_cancel() , la sentencia especificada puede ser reejecutada si fue creada con sqlsrv_prepare(). No es necesario llamar a sqlsrv_cancel() si todos los resultados asociados se han utilizado.

### Parámetros

`stmt`
  El recurso de la sentencia que se va a cancelar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de sqlsrv_cancel()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT Sales FROM Table_1";

    $stmt = sqlsrv_prepare( $conn, $sql);

    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    if( sqlsrv_execute( $stmt ) === false) {
         die( print_r( sqlsrv_errors(), true));
    }

    $salesTotal = 0;
    $count = 0;

    while( ($row = sqlsrv_fetch_array( $stmt)) && $salesTotal <=100000)
    {
         $qty = $row[0];
         $price = $row[1];
         $salesTotal += ( $price * $qty);
         $count++;
    }

    echo "$count ventas suman los primeros $$salesTotal en ingresos.<br />";

    // Cancela los resultados pendientes. La sentencia se puede reutilizar.
    sqlsrv_cancel( $stmt);
    ?>

### Notas

La principal diferencia entre sqlsrv_cancel() y sqlsrv_free_stmt() es que una sentencia cancelada con sqlsrv_cancel() puede ser reejecutada si fue creada con sqlsrv_prepare(). Una sentencia cancelada con sqlsrv_free_statement() no puede ser reejecutada.

### Ver también

- sqlsrv_free_stmt() - Libera todos los recursos de la consulta especificada
- sqlsrv_prepare() - Prepara una consulta para su ejecución

# sqlsrv_client_info

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

sqlsrv_client_info — Devuelve información sobre el cliente y la conexión especificada

### Descripción

function sqlsrv_client_info(resource `$conn`): array

Devuelve información sobre el cliente y la conexión especificada

### Parámetros

`conn`
  La conexión sobre la que se va a retornar información.

### Valores devueltos

Devuelve un array asociativo con las claves que se describen en la tabla siguiente. Devuelve `false` en caso constrario.

Array devuelto por sqlsrv_client_info
Clave | Descripción
--- | ---
DriverDllName | SQLNCLI10.DLL
DriverODBCVer | Versión ODBC (xx.yy)
DriverVer | Versión de la DLL del cliente nativo SQL Server (10.5.xxx)
ExtensionVer | Versión de la biblioteca php_sqlsrv.dll (2.0.xxx.x)

### Ejemplos

Ejemplo #1 Ejemplo de sqlsrv_client_info()

    <?php
    $serverName = "serverName\sqlexpress";
    $connOptions = array("UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connOptions );

    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true));
    }

    if( $client_info = sqlsrv_client_info( $conn)) {
        foreach( $client_info as $key => $value) {
            echo $key.": ".$value."<br />";
        }
    } else {
        echo "Error al recuperar la información del cliente.<br />";
    }
    ?>

### Ver también

- sqlsrv_server_info() - Devuelve información sobre el servidor

# sqlsrv_close

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

sqlsrv_close — Cierra una conexión abierta y libera los recursos asociados a la conexión

### Descripción

function sqlsrv_close(resource `$conn`): bool

Cierra una conexión abierta y libera los recursos asociados a la conexión.

### Parámetros

`conn`
  La conexión que se va a cerrar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de sqlsrv_close()

    <?php
    $serverName = "serverName\sqlexpress";
    $connOptions = array("UID"=>"username", "PWD"=>"password", "Database"=>"dbname");
    $conn = sqlsrv_connect( $serverName, $connOptions );
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    //-------------------------------------
    // Realizar aquí las operaciones contra la base de datos.
    //-------------------------------------

    // Cerrar la conexión.
    sqlsrv_close( $conn );
    ?>

### Ver también

- sqlsrv_connect() - Establece una conexión con una base de datos Microsoft SQL Server

# sqlsrv_commit

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

sqlsrv_commit — Consolida una transacción que se inició con sqlsrv_begin_transaction()

### Descripción

function sqlsrv_commit(resource `$conn`): bool

Consolida una transacción que se inició con sqlsrv_begin_transaction(). La conexión retorna al modo auto-commit después de que se llame a sqlsrv_commit(). La transacción que se consolida incluye todas las sentencias que fueron ejecutadas después de la llamada a sqlsrv_begin_transaction(). Las transacciones explícitas deben iniciarse y consolidarse o revertirse utilizando estas funciones en vez de ejecutar las sentencias SQL que empiezan y consolidan/revierten transacciones. Para más información, ver » SQLSRV Transactions.

### Parámetros

`conn`
  La conexión en la que se va a consolidar la transacción.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de sqlsrv_commit()

El siguiente ejemplo demuestra cómo utilizar sqlsrv_commit() junto con sqlsrv_begin_transaction() y sqlsrv_rollback().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true ));
    }

    /* Empezar la transacción. */
    if ( sqlsrv_begin_transaction( $conn ) === false ) {
         die( print_r( sqlsrv_errors(), true ));
    }

    /* Inicializar los parámetros. */
    $orderId = 1; $qty = 10; $productId = 100;

    /* Preparar y ejecutar la primera sentencia. */
    $sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
             VALUES (?, ?, ?)";
    $params1 = array( $orderId, $qty, $productId );
    $stmt1 = sqlsrv_query( $conn, $sql1, $params1 );

    /* Preparar y ejecutar la segunda sentencia. */
    $sql2 = "UPDATE InventoryTable
             SET Quantity = (Quantity - ?)
             WHERE ProductID = ?";
    $params2 = array($qty, $productId);
    $stmt2 = sqlsrv_query( $conn, $sql2, $params2 );

    /* Si ambas sentencias finalizan con éxito, consolidar la transacción. */
    /* En caso contrario, revertir la transacción. */
    if( $stmt1 && $stmt2 ) {
         sqlsrv_commit( $conn );
         echo "Transacción consolidada.<br />";
    } else {
         sqlsrv_rollback( $conn );
         echo "Transacción revertida.<br />";
    }
    ?>

### Ver también

- sqlsrv_begin_transaction() - Inicia una transacción de base de datos
- sqlsrv_rollback() - Anula una transacción que ha sido iniciada gracias a la función sqlsrv_begin_transaction

# sqlsrv_configure

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

sqlsrv_configure — Cambia la configuración de los drivers del gestionador de errores y de log

### Descripción

function sqlsrv_configure(string `$setting`, mixed `$value`): bool

Cambia la configuración de los drivers del gestionador de errores y de log.

### Parámetros

`setting`
  El nombre de la propiedad a configurar. Los valores posibles son "WarningsReturnAsErrors", "LogSubsystems", and "LogSeverity".
`value`

  El valor de la propiedad especificada. La tabla siguiente muestra los valores posibles:

  Opciones de configuración de la gestión de errores y log
  Propiedades | Opciones
  --- | ---
  WarningsReturnAsErrors | 1 (`true`) o 0 (`false`)
  LogSubsystems | SQLSRV_LOG_SYSTEM_ALL (-1) SQLSRV_LOG_SYSTEM_CONN (2) SQLSRV_LOG_SYSTEM_INIT (1) SQLSRV_LOG_SYSTEM_OFF (0) SQLSRV_LOG_SYSTEM_STMT (4) SQLSRV_LOG_SYSTEM_UTIL (8)
  LogSeverity | SQLSRV_LOG_SEVERITY_ALL (-1) SQLSRV_LOG_SEVERITY_ERROR (1) SQLSRV_LOG_SEVERITY_NOTICE (4) SQLSRV_LOG_SEVERITY_WARNING (2)

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- » Gestionador de errores SQLSRV.
- » Actividad de log de SQLSRV.

# sqlsrv_connect

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

sqlsrv_connect — Establece una conexión con una base de datos Microsoft SQL Server

### Descripción

function sqlsrv_connect(string `$serverName`, array `$connectionInfo` = ?): resource

Establece una conexión con una base de datos Microsoft SQL Server. Por omisión, la conexión intenta utilizar la autenticación Windows. Para conectarse utilizando la autenticación SQL Server, se deben añadir los argumentos "UID" y "PWD" en el array de opciones de conexión.

### Parámetros

`serverName`
  El nombre del servidor con el que se desea establecer la conexión. Para conectarse a una instancia particular, se debe especificar el nombre del servidor, seguido de un backslash, y luego el nombre de la instancia (i.e. serverName\sqlexpress).
`connectionInfo`
  Un array asociativo que especifica las opciones para la conexión al servidor. Si los valores de las claves UID y PWD no están especificados, la conexión intentará utilizar la autenticación Windows. Para una lista completa de las claves soportadas, consulte las » opciones de conexión SQLSRV.

### Valores devueltos

Un recurso de conexión. Si la conexión no pudo ser abierta, se retornará `false`.

### Ejemplos

Ejemplo #1 Conexión utilizando la autenticación Windows.

    <?php
    $serverName = "serverName\\sqlexpress"; //serverName\instanceName

    // Dado que UID y PWD no están especificados en el array $connectionInfo,
    // la conexión intentará utilizar la autenticación Windows.
    $connectionInfo = array( "Database"=>"dbName");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);

    if( $conn ) {
         echo "Conexión establecida.<br />";
    }else{
         echo "La conexión no pudo ser establecida.<br />";
         die( print_r( sqlsrv_errors(), true));
    }
    ?>

Ejemplo #2 Conexión especificando un nombre de usuario y una contraseña.

    <?php
    $serverName = "serverName\\sqlexpress"; //serverName\instanceName
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);

    if( $conn ) {
         echo "Conexión establecida.<br />";
    }else{
         echo "La conexión no pudo ser establecida.<br />";
         die( print_r( sqlsrv_errors(), true));
    }
    ?>

Ejemplo #3 Conexión a un puerto específico.

    <?php
    $serverName = "serverName\\sqlexpress, 1542"; //serverName\instanceName, portNumber (default is 1433)
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);

    if( $conn ) {
         echo "Conexión establecida.<br />";
    }else{
         echo "La conexión no pudo ser establecida.<br />";
         die( print_r( sqlsrv_errors(), true));
    }
    ?>

### Notas

Por omisión, la función sqlsrv_connect() utiliza la cola de conexiones para aumentar el rendimiento. Para desactivar esta cola de conexiones (i.e. y así, forzar una nueva conexión en cada llamada a la función), se debe definir la opción "ConnectionPooling" en el array $connectionOptions a 0 (o `false`). Para más información, consulte el capítulo sobre la » cola de conexiones SQLSRV.

La extensión SQLSRV no tiene una función dedicada para modificar la base de datos a la que está conectada. La base de datos objetivo se especifica en el array $connectionOptions pasado a la función sqlsrv_connect. Para cambiar la base de datos en una conexión abierta, se debe ejecutar la siguiente consulta: "USE dbName" (i.e. sqlsrv_query($conn, "USE dbName")).

### Ver también

- sqlsrv_close() - Cierra una conexión abierta y libera los recursos asociados a la conexión
- sqlsrv_errors() - Devuelve información de errores y alertas (warnings) de la última operación SQLSRV realizada
- sqlsrv_query() - Prepara y ejecuta una consulta

# sqlsrv_errors

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

sqlsrv_errors — Devuelve información de errores y alertas (warnings) de la última operación SQLSRV realizada

### Descripción

function sqlsrv_errors(int `$errorsOrWarnings` = ?): mixed

Devuelve información de errores y alertas de la última operación SQLSRV realizada.

### Parámetros

`errorsOrWarnings`
  Determina si se ha de retornar información de error, alertas, o ambas. Si este parámetro no se informa, se devolverá tanto información de error como de alerta. Este parámetro puede tomar los siguientes valores: SQLSRV_ERR_ALL, SQLSRV_ERR_ERRORS, SQLSRV_ERR_WARNINGS.

### Valores devueltos

Si se produjeron errores y/o warnings en la última operación sqlsrv, se devolverá un array de arrays conteniendo información de error. Si no se produjeron errores y/o alertas en la última operación sqlsrv, se devolverá `null`. La siguiente tabla describe la estructura de los arrays devueltos:

Array devuelto por sqlsrv_errors
Clave | Descripción
--- | ---
SQLSTATE | Para errores que se originan en el driver ODBC driver, el SQLSTATE devuelto por ODBC. Para errores que se originan en los drivers de Microsoft para PHP para SQL Server, un SQLSTATE de IMSSP. Para alertas que se originan en los drivers de Microsoft para PHP para SQL Server, un SQLSTATE de 01SSP.
code | Para errores que se originan en SQL Server, el código de error SQL Server nativo. Para errores que se originan en el driver ODBC, el código de error devuelto por ODBC. Para errores que se originan en los Drivers de Microsoft para PHP para SQL Server, los códigos de error de SQL Server para los Drivers de Microsoft para PHP.
message | Una descripción del error.

### Ejemplos

Ejemplo #1 ejemplo de functionname()

    <?php
    $serverName = "serverName/sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    /* Query que selecciona un nombre de columna inválida. */
    $sql = "SELECT BadColumnName FROM Table_1";

    /* Ejecución de la query que fallará debido al nombre de columna incorrecto. */
    $stmt = sqlsrv_query( $conn, $sql );
    if( $stmt === false ) {
        if( ($errors = sqlsrv_errors() ) != null) {
            foreach( $errors as $error ) {
                echo "SQLSTATE: ".$error[ 'SQLSTATE']."<br />";
                echo "code: ".$error[ 'code']."<br />";
                echo "message: ".$error[ 'message']."<br />";
            }
        }
    }
    ?>

### Notas

Por defecto, las alertas generadas en una llamada a cualquier función SQLSRV se tratarán como errores. Esto significa que si una alerta ocurre en una llamada a una función SQLSRV, la función devolverá `false`. Sin embargo, las alertas correspondientes a los valores de SQLSTATE 01000, 01001, 01003, y 01S02 nunca se tratarán como errores. Para obtener información sobre cómo cambiar este comportamiento, ver sqlsrv_configure() y la configuración de WarningsReturnAsErrors.

### Ver también

- sqlsrv_configure() - Cambia la configuración de los drivers del gestionador de errores y de log

# sqlsrv_execute

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

sqlsrv_execute — Ejecuta una sentencia preparada con sqlsrv_prepare()

### Descripción

function sqlsrv_execute(resource `$stmt`): bool

Ejecuta una sentencia preparada con sqlsrv_prepare(). Esta función es ideal para ser ejecutar múltiples veces una sentencia preparada con diferentes valores de parámetros.

### Parámetros

`stmt`
  Un recurso de sentencia devuelto por sqlsrv_prepare().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 ejemplo de sqlsrv_execute()

Este ejemplo muestra como preparar una sentencia con sqlsrv_prepare() y reejecutarla múltiples veces (con diferentes valores de parámetros) utilizando sqlsrv_execute().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false) {
        die( print_r( sqlsrv_errors(), true));
    }

    $sql = "UPDATE Table_1
            SET OrderQty = ?
            WHERE SalesOrderID = ?";

    // Inicializar los parámetros y preparar la sentencia.
    // Las variables $qty y $id se pasan como parámetro a la sentencia $stmt.
    $qty = 0; $id = 0;
    $stmt = sqlsrv_prepare( $conn, $sql, array( &$qty, &$id));
    if( !$stmt ) {
        die( print_r( sqlsrv_errors(), true));
    }

    // Configurar la información de SalesOrderDetailID y OrderQty.
    // Este array liga el orden ID al orden de cantidad en las parejas  key=>value.
    $orders = array( 1=>10, 2=>20, 3=>30);

    // Ejecuta la sentencia para cada orden.
    foreach( $orders as $id => $qty) {
        // Como $id y $qty se pasan como parámetro a $stmt1, sus valores
        // actualizados se utilizan en cada ejecución de la sentencia.
        if( sqlsrv_execute( $stmt ) === false ) {
              die( print_r( sqlsrv_errors(), true));
        }
    }
    ?>

### Notas

Cuando se prepara una sentencia que utiliza variables como parámetros, las variables se pasan como parámetros a la sentencia. Esto significa que si se actualizan los valores de las variables, la próxima vez que se ejecute la sentencia lo hará con los nuevos valores de los parámetros. Para las sentencias que se quieran ejecutar únicamente una vez, utilizar sqlsrv_query().

### Ver también

- sqlsrv_prepare() - Prepara una consulta para su ejecución
- sqlsrv_query() - Prepara y ejecuta una consulta

# sqlsrv_fetch

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

sqlsrv_fetch — Hace que esté disponible para ser leída la siguiente fila del conjunto de resultado

### Descripción

function sqlsrv_fetch(resource `$stmt`, int `$row` = ?, int `$offset` = ?): mixed

Hace que esté disponible para ser leída la siguiente fila del conjunto de resultado. Utilizar sqlsrv_get_field() para leer los campos de la fila.

### Parámetros

`stmt`
  Un recurso de consulta creado por la ejecución de sqlsrv_query() o sqlsrv_execute().
`row`

  La fila que será accedida. Este parámetro puede utilizarse si la consulta especificada se preparó con un cursor con scroll. En ese caso, el parámetro puede tomar uno de los siguientes valores:

  - SQLSRV_SCROLL_NEXT
  - SQLSRV_SCROLL_PRIOR
  - SQLSRV_SCROLL_FIRST
  - SQLSRV_SCROLL_LAST
  - SQLSRV_SCROLL_ABSOLUTE
  - SQLSRV_SCROLL_RELATIVE
`offset`
  Especifica la fila que será accedida si el parámetro de fila se configura como `SQLSRV_SCROLL_ABSOLUTE` o `SQLSRV_SCROLL_RELATIVE`. Notar que la primera fila en el conjunto resultado tiene el índice 0.

### Valores devueltos

Devuelve `true` si la fila siguiente del conjunto de resultado se obtuvo satisfactoriamente, `false` si se produce un error, y `null` si no hay más filas en el conjunto de resultado.

### Ejemplos

Ejemplo #1 Ejemplo con sqlsrv_fetch()

El ejemplo siguiente demuestra como obtener una fila con sqlsrv_fetch() y los campos de la fila con sqlsrv_get_field().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT Name, Comment
            FROM Table_1
            WHERE ReviewID=1";
    $stmt = sqlsrv_query( $conn, $sql);
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Hacer que sea disponible para su lectura la primera (y en este caso única) fila del conjunto resultado.
    if( sqlsrv_fetch( $stmt ) === false) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Obtener los campos de la fila. Los índices de campo empiezan desde 0 y se deben obtener en orden.
    // Recuperar los nombres de campo por su nombre no está soportado por sqlsrv_get_field.
    $name = sqlsrv_get_field( $stmt, 0);
    echo "$name: ";

    $comment = sqlsrv_get_field( $stmt, 1);
    echo $comment;
    ?>

### Ver también

- sqlsrv_get_field() - Recupera los datos del campo desde la línea actualmente seleccionada
- sqlsrv_fetch_array() - Devuelve una fila como un array
- sqlsrv_fetch_object() - Devuelve la siguiente fila de datos de un conjunto resultado como un objeto

# sqlsrv_fetch_array

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

sqlsrv_fetch_array — Devuelve una fila como un array

### Descripción

function sqlsrv_fetch_array(
resource `$stmt`,
int `$fetchType` = ?,
int `$row` = ?,
int `$offset` = ?
): array

Devuelve la siguiente fila de datos disponible como un array asociativo, un array numérico, o ambos (por defecto).

### Parámetros

`stmt`
  Un recurso de sentencia devuelta por sqlsrv_query o sqlsrv_prepare.
`fetchType`
  Una constante predefinida con el tipo de array a devolver. Los valores posibles son `SQLSRV_FETCH_ASSOC`, `SQLSRV_FETCH_NUMERIC`, y `SQLSRV_FETCH_BOTH` (por defecto). El tipo de objeto devuelto SQLSRV_FETCH_ASSOC no debe utilizarse cuando se trate un conjunto de resultados con múltiples columnas con el mismo nombre.
`row`
  Especifica la fila para acceder a un conjunto de resultados que utiliza un cursor con scroll. Los valores posibles son `SQLSRV_SCROLL_NEXT`, `SQLSRV_SCROLL_PRIOR`, `SQLSRV_SCROLL_FIRST`, `SQLSRV_SCROLL_LAST`, `SQLSRV_SCROLL_ABSOLUTE` y, `SQLSRV_SCROLL_RELATIVE` (por defecto). Cuando se especifica este parámetro, el parámetro `fetchType` debe ser definido explícitamente.
`offset`
  Especifica la fila a la que se desea acceder si el parámetro de fila se define como `SQLSRV_SCROLL_ABSOLUTE` o `SQLSRV_SCROLL_RELATIVE`. Notar que la primera fila en un conjunto de resultado tiene el índice 0.

### Valores devueltos

Devuelve un array en caso de éxito, `null` si no hay más filas a devolver, y `false` si se produce un error.

### Ejemplos

Ejemplo #1 Devolver un array asociativo.

    <?php
    $serverName = "serverName\instanceName";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo );
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT FirstName, LastName FROM SomeTable";
    $stmt = sqlsrv_query( $conn, $sql );
    if( $stmt === false) {
        die( print_r( sqlsrv_errors(), true) );
    }

    while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_ASSOC) ) {
          echo $row['LastName'].", ".$row['FirstName']."<br />";
    }

    sqlsrv_free_stmt( $stmt);
    ?>

Ejemplo #2 Devolver un array numérico.

    <?php
    $serverName = "serverName\instanceName";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo );
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT FirstName, LastName FROM SomeTable";
    $stmt = sqlsrv_query( $conn, $sql );
    if( $stmt === false) {
        die( print_r( sqlsrv_errors(), true) );
    }

    while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_NUMERIC) ) {
          echo $row[0].", ".$row[1]."<br />";
    }

    sqlsrv_free_stmt( $stmt);
    ?>

### Notas

Cuando no se especifica el parámetro `fetchType` o se utiliza explícitamente la constante `SQLSRV_FETCH_TYPE` en los ejemplos anteriores, se devolverá un array que tiene tanto claves asociativas como claves nuéricas.

Si se devuelve más de una columna con el mismo nombre, la última columna tendrá prioridad para tomar el nombre. Para evitar colisiones de nombre de campo, utilizar alias.

Si se devuelve una columna sin nombre, la clave asociativa para ese elemento del array será un string vacío ("").

### Ver también

- sqlsrv_connect() - Establece una conexión con una base de datos Microsoft SQL Server
- sqlsrv_query() - Prepara y ejecuta una consulta
- sqlsrv_errors() - Devuelve información de errores y alertas (warnings) de la última operación SQLSRV realizada
- sqlsrv_fetch() - Hace que esté disponible para ser leída la siguiente fila del conjunto de resultado

# sqlsrv_fetch_object

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

sqlsrv_fetch_object — Devuelve la siguiente fila de datos de un conjunto resultado como un objeto

### Descripción

function sqlsrv_fetch_object(
resource `$stmt`,
string `$className` = ?,
array `$ctorParams` = ?,
int `$row` = ?,
int `$offset` = ?
): mixed

Devuelve la siguiente fila de datos de un conjunto resultado como una instancia de la clase especificada, donde las propiedades correspondientes a los nombres de los campos de la fila recuperada y los valores, se corresponden con los valores de la fila recuperada.

### Parámetros

`stmt`
  Un recurso de consulta creado por sqlsrv_query() o sqlsrv_execute().
`className`
  El nombre de la clase a instanciar. Si no se especifica el nombre de la clase, se instanciará la clase stdClass.
`ctorParams`
  Los valores pasados al constructor de la clase especificada. Si el constructor de la clase especificada tiene parámetros, se proporcionará el array ctorParams.
`row`

  La fila a la que se accederá. Este parámetro únicamente puede utilizarse si la consulta especificada se preparó con un cursor con scroll. En ese caso, este parámetro puede tomar uno de los siguientes valores:

  - SQLSRV_SCROLL_NEXT
  - SQLSRV_SCROLL_PRIOR
  - SQLSRV_SCROLL_FIRST
  - SQLSRV_SCROLL_LAST
  - SQLSRV_SCROLL_ABSOLUTE
  - SQLSRV_SCROLL_RELATIVE
`offset`
  Especifica la fila a la que se accederá si el parámetro de fila se ha especificado como `SQLSRV_SCROLL_ABSOLUTE` o `SQLSRV_SCROLL_RELATIVE`. Notar que la primera fila en un conjunto de resultado tiene el índice 0.

### Valores devueltos

Devuelve un objeto en caso de éxito, `null` si no hay más filas a devolver, y `false` si se produce un error o si la clase especificada no existe.

### Ejemplos

Ejemplo #1 Ejemplo con sqlsrv_fetch_object()

El siguiente ejemplo demuestra cómo devolver una columna como un objeto stdClass.

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT fName, lName FROM Table_1";
    $stmt = sqlsrv_query( $conn, $sql);
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Devolver cada fila como un objeto.
    // Puesto que no se especifica ninguna clase, cada fila devolverá un objeto stdClass.
    // Los nombres de propiedades corresponden a nombres de campo.
    while( $obj = sqlsrv_fetch_object( $stmt)) {
          echo $obj->fName.", ".$obj->lName."<br />";
    }
    ?>

### Notas

Si se especifica un nombre de clase con el parámetro opcional $className y la clase tiene propiedades cuyos nombres coinciden con los nombres de campos del conjunto de resultado, los valores correspondientes del conjunto de resultado se aplicarán a las propiedades. Si un nombre de campo del conjunto resultado no coincide con ninguna propiedad de clase, una propiedad con el nombre de campo se añadirá al objeto del conjunto resultado y el valor del resultado se aplicará a la propiedad. Se aplican las reglas siguientes cuando se utiliza el parámetro $className:

- El nombre de propiedad de campo coincidente es sensible al uso de mayúsculas y minúsculas (es case sensitive).
- La coincidencia con la propiedad de campo se da aunque se utilicen modificadores de acceso.
- Los tipos de datos de la propiedad de clase se ignoran cuando se aplica un valor de campo a la propiedad.
- Si la clase no existe, la función devuelve `false` y añade un error a la colección de errores.

A pesar de que se defina el parámetro $className, si se devuelve un campo sin nombre, el valor de campo será ignorado y se añadirá una alerta a la colección de errores.

Cuando se trate un conjunto de resultado que tenga varias columnas con el mismo nombre, podría ser mejor utilizar sqlsrv_fetch_array() o la combinación de sqlsrv_fetch() y sqlsrv_get_field().

### Ver también

- sqlsrv_fetch() - Hace que esté disponible para ser leída la siguiente fila del conjunto de resultado
- sqlsrv_fetch_array() - Devuelve una fila como un array

# sqlsrv_field_metadata

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

sqlsrv_field_metadata — Recupera los datos meta para los campos de una consulta preparada por la función sqlsrv_prepare() o la función sqlsrv_query()

### Descripción

function sqlsrv_field_metadata(resource `$stmt`): mixed

Recupera los datos meta para los campos de una consulta preparada por la función sqlsrv_prepare() o la función sqlsrv_query(). La función sqlsrv_field_metadata() puede ser llamada sobre una consulta antes o después de su ejecución.

### Parámetros

`stmt`
  Un recurso de consulta desde el cual los datos meta serán recuperados.

### Valores devueltos

Devuelve un array de arrays en caso de éxito. De lo contrario, `false` es devuelto. Cada array devuelto es descrito en la tabla siguiente:

Array devuelto por la función sqlsrv_field_metadata
Clave | Descripción
--- | ---
Name | El nombre del campo.
Type | El valor numérico para el tipo SQL.
Size | El número de caracteres para los campos de tipo caracteres, el número de bytes para los campos de tipo binario, o `null` para los otros tipos.
Precision | La precisión para las variables de tipo precisión, `null` para los otros tipos.
Scale | La escala para las variables de tipo scale, `null` para los otros tipos.
Nullable | Una enumeración indicando si la columna puede ser nula, no puede serlo, o si esta información no es conocida.

Para más información, consulte la documentación sobre la función » sqlsrv_field_metadata de la documentación Microsoft SQLSRV.

### Ejemplos

Ejemplo #1 Ejemplo con sqlsrv_field_metadata()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"AdventureWorks", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
       die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT * FROM Table_1";
    $stmt = sqlsrv_prepare( $conn, $sql );

    foreach( sqlsrv_field_metadata( $stmt ) as $fieldMetadata ) {
        foreach( $fieldMetadata as $name => $value) {
           echo "$name: $value<br />";
        }
          echo "<br />";
    }
    ?>

### Ver también

- sqlsrv_client_info() - Devuelve información sobre el cliente y la conexión especificada

# sqlsrv_free_stmt

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

sqlsrv_free_stmt — Libera todos los recursos de la consulta especificada

### Descripción

function sqlsrv_free_stmt(resource `$stmt`): bool

Libera todos los recursos para la consulta especificada. La consulta no podrá ser utilizada después de pasar a la función sqlsrv_free_stmt(). Si la función sqlsrv_free_stmt() es llamada mientras la consulta está en ejecución, la ejecución de la consulta es interrumpida y la consulta es cancelada.

### Parámetros

`stmt`
  La consulta cuyos recursos serán liberados. Tenga en cuenta que `null` es un valor de argumento válido. Este valor permite que la función sea llamada varias veces en un script.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con sqlsrv_free_stmt()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $stmt = sqlsrv_query( $conn, "SELECT * FROM Table_1");
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    /*-------------------------------
         Uso de la consulta aquí.
    -------------------------------*/

    /* Liberación de los recursos asociados a la consulta. */
    sqlsrv_free_stmt( $stmt);

    ?>

### Notas

La principal diferencia entre la función sqlsrv_free_stmt() y la función sqlsrv_cancel() es que un recurso de consulta cancelado con la función sqlsrv_cancel() puede ser re-ejecutado si ha sido creado con la función sqlsrv_prepare(). Un recurso de consulta cancelado con la función sqlsrv_free_statement() no puede ser re-ejecutado.

### Ver también

- sqlsrv_cancel() - Cancela una sentencia de base de datos

# sqlsrv_get_config

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

sqlsrv_get_config — Devuelve el valor de la configuración especificada

### Descripción

function sqlsrv_get_config(string `$setting`): mixed

Devuelve el valor de la configuración especificada.

### Parámetros

`setting`
  El nombre de la configuración para la cual se devolverá el valor. Para una lista de las configuraciones, ver la función sqlsrv_configure().

### Valores devueltos

Devuelve el valor de la configuración solicitada. Si se proporciona una configuración no válida, se devolverá `false`.

### Ver también

- sqlsrv_configure() - Cambia la configuración de los drivers del gestionador de errores y de log

# sqlsrv_get_field

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

sqlsrv_get_field — Recupera los datos del campo desde la línea actualmente seleccionada

### Descripción

function sqlsrv_get_field(resource `$stmt`, int `$fieldIndex`, int `$getAsType` = ?): mixed

Recupera los datos del campo desde la línea actualmente seleccionada. Los campos deben ser leídos en orden. Sus índices comienzan en 0.

### Parámetros

`stmt`
  Un recurso de consulta devuelto por la función sqlsrv_query() o la función sqlsrv_execute().
`fieldIndex`
  El índice del campo a recuperar. Los índices de los campos comienzan en 0. Los campos deben ser leídos en orden, es decir, si se accede al campo con índice 1, el campo con índice 0 ya no estará disponible.
`getAsType`
  El tipo de datos PHP para los datos del campo devuelto. Si este argumento no está definido, los datos del campo serán devueltos en forma de un tipo de datos PHP por omisión. Para más información sobre los tipos de datos PHP por omisión, consulte la sección sobre » los tipos de datos PHP por omisión de la documentación Microsoft SQLSRV.

### Valores devueltos

Devuelve los datos desde el campo especificado en caso de éxito. Devuelve `false` si ocurre un error.

### Ejemplos

Ejemplo #1 sqlsrv_get_field() example

El siguiente ejemplo muestra cómo recuperar una línea con la función sqlsrv_fetch() y recupera los campos de la línea con la función sqlsrv_get_field().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT Name, Comment
            FROM Table_1
            WHERE ReviewID=1";
    $stmt = sqlsrv_query( $conn, $sql);
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Hace disponible la primera (y en este caso, la única) línea del conjunto de resultados para lectura.
    if( sqlsrv_fetch( $stmt ) === false) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Recupera los campos de la línea. Los índices comienzan en 0 y deben ser recuperados en orden.
    // La recuperación de los campos de la línea por sus nombres no es soportada por la función sqlsrv_get_field.
    $name = sqlsrv_get_field( $stmt, 0);
    echo "$name: ";

    $comment = sqlsrv_get_field( $stmt, 1);
    echo $comment;
    ?>

### Ver también

- sqlsrv_fetch() - Hace que esté disponible para ser leída la siguiente fila del conjunto de resultado
- sqlsrv_fetch_array() - Devuelve una fila como un array
- sqlsrv_fetch_object() - Devuelve la siguiente fila de datos de un conjunto resultado como un objeto

# sqlsrv_has_rows

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

sqlsrv_has_rows — Indica si la consulta especificada contiene filas

### Descripción

function sqlsrv_has_rows(resource `$stmt`): bool

Indica si la consulta especificada contiene filas.

### Parámetros

`stmt`
  Un recurso de consulta devuelto por la función sqlsrv_query() o la función sqlsrv_execute().

### Valores devueltos

Devuelve `true` si la consulta especificada contiene filas, `false` si no contiene ninguna o si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con sqlsrv_has_rows()

    <?php
    $server = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $server, $connectionInfo );

    $stmt = sqlsrv_query( $conn, "SELECT * FROM Table_1");

    if ($stmt) {
       $rows = sqlsrv_has_rows( $stmt );
       if ($rows === true)
          echo "Hay filas. <br />";
       else
          echo "No hay filas. <br />";
    }
    ?>

### Ver también

- sqlsrv_num_rows() - Recupera el número de filas de un conjunto de resultados
- sqlsrv_query() - Prepara y ejecuta una consulta

# sqlsrv_next_result

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

sqlsrv_next_result — Activa el siguiente resultado de la consulta especificada

### Descripción

function sqlsrv_next_result(resource `$stmt`): mixed

Activa el siguiente resultado de la consulta especificada. Los resultados incluyen los conjuntos de resultados, el número de filas y los parámetros de salida.

### Parámetros

`stmt`
  La consulta sobre la cual se llamará el siguiente resultado.

### Valores devueltos

Devuelve `true` si el siguiente resultado ha sido recuperado con éxito, `false` si ocurre un error, y `null` si no hay más resultados para recuperar.

### Ejemplos

Ejemplo #1 Ejemplo con sqlsrv_next_result()

El siguiente ejemplo ejecuta una consulta batch que realiza inserciones en una tabla y luego realiza una selección de la tabla. Esto produce 2 resultados en la consulta: uno para las filas afectadas por el INSERT, y otro para las filas devueltas por el SELECT. Para recuperar las filas devueltas por el SELECT, la función sqlsrv_next_result() debe ser llamada para pasar el primer resultado.

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array("Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);

    $query = "INSERT INTO Table_1 (id, data) VALUES (?,?); SELECT * FROM TABLE_1;";
    $params = array(1, "some data");
    $stmt = sqlsrv_query($conn, $query, $params);

    // Consume el primer resultado (filas afectadas por el INSERT) sin llamar a la función sqlsrv_next_result.
    echo "Filas afectadas : ".sqlsrv_rows_affected($stmt)."<br />";

    // Se mueve al siguiente resultado y muestra los resultados.
    $next_result = sqlsrv_next_result($stmt);
    if( $next_result ) {
       while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_ASSOC)){
          echo $row['id']." : ".$row['data']."<br />";
       }
    } elseif( is_null($next_result)) {
         echo "No hay más resultados.<br />";
    } else {
         die(print_r(sqlsrv_errors(), true));
    }
    ?>

### Ver también

- sqlsrv_query() - Prepara y ejecuta una consulta
- sqlsrv_fetch_array() - Devuelve una fila como un array
- sqlsrv_rows_affected() - Devuelve el número de filas modificadas por la última consulta de tipo INSERT, UPDATE, o DELETE

# sqlsrv_num_fields

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

sqlsrv_num_fields — Recupera el número de campos (columnas) en una consulta

### Descripción

function sqlsrv_num_fields(resource `$stmt`): mixed

Recupera el número de campos (columnas) en una consulta.

### Parámetros

`stmt`
  La consulta desde la cual se devuelve el número de campos. La función sqlsrv_num_fields() puede ser llamada sobre una consulta antes o después de la ejecución de la consulta.

### Valores devueltos

Devuelve el número de campos en caso de éxito. Devuelve `false` en caso contrario.

### Ejemplos

Ejemplo #1 Ejemplo con sqlsrv_num_fields()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
       die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT * FROM Table_1";
    $stmt = sqlsrv_query($conn, $sql);
    if( $stmt === false) {
       die( print_r( sqlsrv_errors(), true));
    }

    $numFields = sqlsrv_num_fields( $stmt );

    while( sqlsrv_fetch( $stmt )) {
       // Iteración sobre los campos de cada fila.
       for($i = 0; $i < $numFields; $i++) {
          echo sqlsrv_get_field($stmt, $i)." ";
       }
       echo "<br />";
    }
    ?>

### Ver también

- sqlsrv_field_metadata() - Recupera los datos meta para los campos de una consulta preparada por la función sqlsrv_prepare o la función sqlsrv_query
- sqlsrv_fetch() - Hace que esté disponible para ser leída la siguiente fila del conjunto de resultado
- sqlsrv_get_field() - Recupera los datos del campo desde la línea actualmente seleccionada

# sqlsrv_num_rows

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

sqlsrv_num_rows — Recupera el número de filas de un conjunto de resultados

### Descripción

function sqlsrv_num_rows(resource `$stmt`): mixed

Recupera el número de filas de un conjunto de resultados. Esta función requiere que el recurso de consulta haya sido creado con un cursor estático o keyset. Para más información, consulte las funciones sqlsrv_query(), sqlsrv_prepare(), o el capítulo » Especificar un tipo de cursor y seleccionar filas en la documentación de Microsoft SQLSRV.

### Parámetros

`stmt`
  La consulta desde la cual se devuelve el número total de filas. El recurso de consulta debe haber sido creado con un cursor estático o keyset. Para más información, consulte las funciones sqlsrv_query(), sqlsrv_prepare(), o el capítulo » Especificar un tipo de cursor y seleccionar filas en la documentación de Microsoft SQLSRV.

### Valores devueltos

Devuelve el número total de filas recuperadas en caso de éxito, y `false` si ocurre un error. Si se utiliza un cursor anterior (por omisión), o un cursor dinámico, se devolverá `false`.

### Ejemplos

Ejemplo #1 Ejemplo con sqlsrv_num_rows()

    <?php
    $server = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $server, $connectionInfo );

    $sql = "SELECT * FROM Table_1";
    $params = array();
    $options =  array( "Scrollable" => SQLSRV_CURSOR_KEYSET );
    $stmt = sqlsrv_query( $conn, $sql , $params, $options );

    $row_count = sqlsrv_num_rows( $stmt );

    if ($row_count === false)
       echo "Error al recuperar el número de filas.";
    else
       echo $row_count;
    ?>

### Ver también

- sqlsrv_has_rows() - Indica si la consulta especificada contiene filas
- sqlsrv_rows_affected() - Devuelve el número de filas modificadas por la última consulta de tipo INSERT, UPDATE, o DELETE

# sqlsrv_prepare

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

sqlsrv_prepare — Prepara una consulta para su ejecución

### Descripción

function sqlsrv_prepare(
resource `$conn`,
string `$sql`,
array `$params` = ?,
array `$options` = ?
): mixed

Prepara una consulta para su ejecución. Esta función es ideal para preparar una consulta que será ejecutada varias veces con diferentes valores de argumentos.

### Parámetros

`conn`
  Un recurso de conexión devuelto por la función sqlsrv_connect().
`sql`
  La cadena que define la consulta a preparar y ejecutar.
`params`

  Un array especificando la información de los argumentos al ejecutar una consulta que contiene argumentos. Los elementos del array pueden ser cualquiera de los siguientes:

  - Un valor literal
  - Una variable PHP
  - Un array con la siguiente estructura: array($value [, $direction [, $phpType [, $sqlType]]])
  La tabla siguiente describe los elementos de la estructura del array anterior:

  Estructura del array
  Elemento | Descripción
  --- | ---
  $value | Un valor literal, una variable PHP o una variable PHP pasada por referencia.
  $direction (opcional) | Una de las constantes SQLSRV siguientes, utilizadas para indicar la dirección del argumento: SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT. El valor por defecto es SQLSRV_PARAM_IN.
  $phpType (opcional) | Una constante SQLSRV_PHPTYPE_* que especifica el tipo de datos PHP del valor devuelto.
  $sqlType (opcional) | Una constante SQLSRV_SQLTYPE_* que especifica el tipo de datos del servidor SQL del valor de entrada.

`options`
  Un array especificando las opciones de propiedades de la consulta. Las claves soportadas se describen en la tabla siguiente:

  Opciones de la consulta
  Clave | Valores | Descripción
  --- | --- | ---
  QueryTimeout | Un valor entero positivo. | Define el tiempo máximo de ejecución de la consulta, en segundos. Por defecto, el controlador esperará indefinidamente los resultados.
  SendStreamParamsAtExec | `true` o `false` (por defecto, `true`) | Configura el controlador para enviar los datos del flujo a la ejecución (`true`), o enviar los datos del flujo por partes (`false`). Por defecto, el valor está definido a `true`. Para más información, consulte la función sqlsrv_send_stream_data().
  Scrollable | SQLSRV_CURSOR_FORWARD, SQLSRV_CURSOR_STATIC, SQLSRV_CURSOR_DYNAMIC, o SQLSRV_CURSOR_KEYSET | Ver la sección sobre » la especificación de un tipo de cursor y la selección de filas de la documentación Microsoft SQLSRV.

### Valores devueltos

Devuelve un recurso de consulta en caso de éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con sqlsrv_prepare()

Este ejemplo muestra cómo preparar una consulta con la función sqlsrv_prepare() y su re-ejecución varias veces (con diferentes valores de argumentos) utilizando la función sqlsrv_execute().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false) {
        die( print_r( sqlsrv_errors(), true));
    }

    $sql = "UPDATE Table_1
            SET OrderQty = ?
            WHERE SalesOrderID = ?";

    // Inicializa los argumentos y prepara la consulta.
    // Las variables $qty y $id están ligadas a la consulta $stmt.
    $qty = 0; $id = 0;
    $stmt = sqlsrv_prepare( $conn, $sql, array( &$qty, &$id));
    if( !$stmt ) {
        die( print_r( sqlsrv_errors(), true));
    }

    // Define la información SalesOrderDetailID y OrderQty.
    // Este array liga el orden de los IDs con el orden de las cantidades con pares clave=>valor.
    $orders = array( 1=>10, 2=>20, 3=>30);

    // Ejecuta la consulta para cada orden.
    foreach( $orders as $id => $qty) {
        // Debido a que $id y $qty están ligados a $stmt1,
        // sus valores actualizados se utilizan en cada ejecución
        // de la consulta.
        if( sqlsrv_execute( $stmt ) === false ) {
              die( print_r( sqlsrv_errors(), true));
        }
    }
    ?>

### Notas

Cuando se prepara una consulta que utiliza variables como argumentos, las variables están ligadas a la consulta. Esto significa que si se actualizan los valores de estas variables, la próxima ejecución de la consulta tomará en cuenta estos nuevos valores. Para las consultas que se prevé ejecutar solo una vez, utilice la función sqlsrv_query().

### Ver también

- sqlsrv_execute() - Ejecuta una sentencia preparada con sqlsrv_prepare
- sqlsrv_query() - Prepara y ejecuta una consulta

# sqlsrv_query

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

sqlsrv_query — Prepara y ejecuta una consulta

### Descripción

function sqlsrv_query(
resource `$conn`,
string `$sql`,
array `$params` = ?,
array `$options` = ?
): mixed

Prepara y ejecuta una consulta.

### Parámetros

`conn`
  Un recurso de conexión devuelto por la función sqlsrv_connect().
`sql`
  El string que define la consulta a preparar y ejecutar.
`params`

  Un array especificando los parámetros al ejecutar una consulta que los permita. Los elementos del array pueden ser cualquiera de los siguientes:

  - Un valor literal
  - Una variable PHP
  - Un array con esta estructura: array($value [, $direction [, $phpType [, $sqlType]]])
  La tabla siguiente describe los elementos en la estructura del array anterior:

  Estructura del array
  Elemento | Descripción
  --- | ---
  $value | Un valor literal, una variable PHP o una variable PHP por referencia.
  $direction (opcional) | Una de las constantes SQLSRV siguientes utilizadas para indicar la dirección del parámetro: SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT. El valor por defecto es SQLSRV_PARAM_IN.
  $phpType (opcional) | Una constante SQLSRV_PHPTYPE_* que especifica el tipo de datos PHP del valor devuelto.
  $sqlType (opcional) | Una constante SQLSRV_SQLTYPE_* que especifica el tipo de datos del servidor SQL para el valor de entrada.

`options`
  Un array especificando las opciones de la consulta. Las claves soportadas son descritas en la tabla siguiente:

  Opciones de consulta
  Clave | Valor | Descripción
  --- | --- | ---
  QueryTimeout | Un valor entero positivo. | Define el tiempo máximo de ejecución de la consulta en segundos. Por defecto, el controlador esperará indefinidamente los resultados.
  SendStreamParamsAtExec | `true` o `false` (por defecto, vale `true`) | Configura el controlador para enviar todos los flujos de datos a la ejecución (`true`) o enviar los flujos de datos en fragmentos (`false`). Para más información, ver la función sqlsrv_send_stream_data().
  Scrollable | SQLSRV_CURSOR_FORWARD, SQLSRV_CURSOR_STATIC, SQLSRV_CURSOR_DYNAMIC, o SQLSRV_CURSOR_KEYSET | Ver el capítulo sobre » la especificación de un tipo de cursor y la selección de filas en la documentación Microsoft SQLSRV.

### Valores devueltos

Devuelve un recurso de consulta en caso de éxito, y `false` si ocurre un error.

### Ejemplos

Ejemplo #1 sqlsrv_query() ejemplo

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "INSERT INTO Table_1 (id, data) VALUES (?, ?)";
    $params = array(1, "some data");

    $stmt = sqlsrv_query( $conn, $sql, $params);
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }
    ?>

### Notas

Para las consultas que no se prevé ejecutar más de una vez, utilice la función sqlsrv_query(). Si se desea re-ejecutar una consulta con diferentes valores para sus parámetros, utilice la combinación de la función sqlsrv_prepare() y la función sqlsrv_execute().

### Ver también

- sqlsrv_prepare() - Prepara una consulta para su ejecución
- sqlsrv_execute() - Ejecuta una sentencia preparada con sqlsrv_prepare

# sqlsrv_rollback

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

sqlsrv_rollback — Anula una transacción que ha sido iniciada gracias a la función sqlsrv_begin_transaction()

### Descripción

function sqlsrv_rollback(resource `$conn`): bool

Anula una transacción que ha sido iniciada gracias a la función sqlsrv_begin_transaction() y devuelve la conexión en modo auto-validación.

### Parámetros

`conn`
  El recurso de conexión devuelto por una llamada a la función sqlsrv_connect().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con sqlsrv_rollback()

El siguiente ejemplo muestra la forma de utilizar la función sqlsrv_begin_transaction() con las funciones sqlsrv_commit() y sqlsrv_rollback().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true ));
    }

    /* Inicia la transacción. */
    if ( sqlsrv_begin_transaction( $conn ) === false ) {
         die( print_r( sqlsrv_errors(), true ));
    }

    /* Inicializa los valores de los argumentos. */
    $orderId = 1; $qty = 10; $productId = 100;

    /* Ejecución de la primera consulta. */
    $sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
             VALUES (?, ?, ?)";
    $params1 = array( $orderId, $qty, $productId );
    $stmt1 = sqlsrv_query( $conn, $sql1, $params1 );

    /* Ejecuta la segunda consulta. */
    $sql2 = "UPDATE InventoryTable
             SET Quantity = (Quantity - ?)
             WHERE ProductID = ?";
    $params2 = array($qty, $productId);
    $stmt2 = sqlsrv_query( $conn, $sql2, $params2 );

    /* Si las dos consultas han sido ejecutadas con éxito,
    se valida la transacción */
    /* De lo contrario, se anula la transacción. */
    if( $stmt1 && $stmt2 ) {
         sqlsrv_commit( $conn );
         echo "Transacción validada.<br />";
    } else {
         sqlsrv_rollback( $conn );
         echo "Transacción anulada.<br />";
    }
    ?>

### Ver también

- sqlsrv_begin_transaction() - Inicia una transacción de base de datos
- sqlsrv_commit() - Consolida una transacción que se inició con sqlsrv_begin_transaction

# sqlsrv_rows_affected

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

sqlsrv_rows_affected — Devuelve el número de filas modificadas por la última consulta de tipo INSERT, UPDATE, o DELETE

### Descripción

function sqlsrv_rows_affected(resource `$stmt`): int|false

Devuelve el número de filas modificadas por la última consulta de tipo INSERT, UPDATE, o DELETE. Para más información sobre el número de filas devueltas por una consulta SELECT, consulte la función sqlsrv_num_rows().

### Parámetros

`stmt`
  El recurso de la consulta ejecutada.

### Valores devueltos

Devuelve el número de filas afectadas por la última consulta INSERT, UPDATE, o DELETE. Si ninguna fila es afectada, se devolverá 0. Si el número de filas afectadas no puede ser determinado, se devolverá -1. Si ocurre un error, se devolverá `false`.

### Ejemplos

Ejemplo #1 Ejemplo con sqlsrv_rows_affected()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "UPDATE Table_1 SET data = ? WHERE id = ?";

    $params = array("updated data", 1);

    $stmt = sqlsrv_query( $conn, $sql, $params);

    $rows_affected = sqlsrv_rows_affected( $stmt);
    if( $rows_affected === false) {
         die( print_r( sqlsrv_errors(), true));
    } elseif( $rows_affected == -1) {
          echo "No hay información disponible.<br />";
    } else {
          echo $rows_affected." filas han sido actualizadas.<br />";
    }
    ?>

### Ver también

- sqlsrv_num_rows() - Recupera el número de filas de un conjunto de resultados

# sqlsrv_send_stream_data

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

sqlsrv_send_stream_data — Envía datos desde el flujo al servidor

### Descripción

function sqlsrv_send_stream_data(resource `$stmt`): bool

Envía datos desde el flujo al servidor. Hasta 8 Ko de datos son enviados en cada llamada.

### Parámetros

`stmt`
  Un recurso de petición devuelto por la función sqlsrv_query() o por la función sqlsrv_execute().

### Valores devueltos

Devuelve `true` si aún hay datos por enviar, y `false` si no hay más.

### Ejemplos

Ejemplo #1 Ejemplo con sqlsrv_send_stream_data()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "UPDATE Table_1 SET data = ( ?) WHERE id = 100";

    // Abre los datos como flujo y los coloca en el array $params.
    $data = fopen( "data://text/plain,[ Contenido largo aquí. ]", "r");
    $params = array( &$data);

    // Prepara la petición. Uso del array $options para desactivar
    // el comportamiento por omisión, que es enviar todos los datos del flujo
    // al momento de la ejecución de la petición.
    $options = array("SendStreamParamsAtExec"=>0);
    $stmt = sqlsrv_prepare( $conn, $sql, $params, $options);

    sqlsrv_execute( $stmt);

    // Envía hasta 8 Ko de datos al servidor
    // en cada llamada a la función sqlsrv_send_stream_data.
    $i = 1;
    while( sqlsrv_send_stream_data( $stmt)) {
          $i++;
    }
    echo "$i llamadas fueron realizadas.";
    ?>

### Ver también

- sqlsrv_prepare() - Prepara una consulta para su ejecución
- sqlsrv_query() - Prepara y ejecuta una consulta

# sqlsrv_server_info

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

sqlsrv_server_info — Devuelve información sobre el servidor

### Descripción

function sqlsrv_server_info(resource `$conn`): array

Devuelve información sobre el servidor.

### Parámetros

`conn`
  El recurso de conexión que conecta el cliente y el servidor.

### Valores devueltos

Devuelve un array como se describe en la tabla siguiente:

Array devuelto
CurrentDatabase | La base de datos conectada
--- | ---
SQLServerVersion | La versión del servidor SQL
SQLServerName | El nombre del servidor

### Ejemplos

Ejemplo #1 Ejemplo con sqlsrv_server_info()

    <?php
    $serverName = "serverName\sqlexpress";
    $conn = sqlsrv_connect( $serverName);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $server_info = sqlsrv_server_info( $conn);
    if( $server_info )
    {
        foreach( $server_info as $key => $value) {
           echo $key.": ".$value."<br />";
        }
    } else {
          die( print_r( sqlsrv_errors(), true));
    }
    ?>

### Ver también

- sqlsrv_client_info() - Devuelve información sobre el cliente y la conexión especificada

## Tabla de contenidos

- sqlsrv_begin_transaction — Inicia una transacción de base de datos
- sqlsrv_cancel — Cancela una sentencia de base de datos
- sqlsrv_client_info — Devuelve información sobre el cliente y la conexión especificada
- sqlsrv_close — Cierra una conexión abierta y libera los recursos asociados a la conexión
- sqlsrv_commit — Consolida una transacción que se inició con sqlsrv_begin_transaction
- sqlsrv_configure — Cambia la configuración de los drivers del gestionador de errores y de log
- sqlsrv_connect — Establece una conexión con una base de datos Microsoft SQL Server
- sqlsrv_errors — Devuelve información de errores y alertas (warnings) de la última operación SQLSRV realizada
- sqlsrv_execute — Ejecuta una sentencia preparada con sqlsrv_prepare
- sqlsrv_fetch — Hace que esté disponible para ser leída la siguiente fila del conjunto de resultado
- sqlsrv_fetch_array — Devuelve una fila como un array
- sqlsrv_fetch_object — Devuelve la siguiente fila de datos de un conjunto resultado como un objeto
- sqlsrv_field_metadata — Recupera los datos meta para los campos de una consulta preparada por la función sqlsrv_prepare o la función sqlsrv_query
- sqlsrv_free_stmt — Libera todos los recursos de la consulta especificada
- sqlsrv_get_config — Devuelve el valor de la configuración especificada
- sqlsrv_get_field — Recupera los datos del campo desde la línea actualmente seleccionada
- sqlsrv_has_rows — Indica si la consulta especificada contiene filas
- sqlsrv_next_result — Activa el siguiente resultado de la consulta especificada
- sqlsrv_num_fields — Recupera el número de campos (columnas) en una consulta
- sqlsrv_num_rows — Recupera el número de filas de un conjunto de resultados
- sqlsrv_prepare — Prepara una consulta para su ejecución
- sqlsrv_query — Prepara y ejecuta una consulta
- sqlsrv_rollback — Anula una transacción que ha sido iniciada gracias a la función sqlsrv_begin_transaction
- sqlsrv_rows_affected — Devuelve el número de filas modificadas por la última consulta de tipo INSERT, UPDATE, o DELETE
- sqlsrv_send_stream_data — Envía datos desde el flujo al servidor
- sqlsrv_server_info — Devuelve información sobre el servidor

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
  - Tipos de recursos
- Constantes predefinidas
- SQLSRV Funciones
  - sqlsrv_begin_transaction — Inicia una transacción de base de datos
  - sqlsrv_cancel — Cancela una sentencia de base de datos
  - sqlsrv_client_info — Devuelve información sobre el cliente y la conexión especificada
  - sqlsrv_close — Cierra una conexión abierta y libera los recursos asociados a la conexión
  - sqlsrv_commit — Consolida una transacción que se inició con sqlsrv_begin_transaction
  - sqlsrv_configure — Cambia la configuración de los drivers del gestionador de errores y de log
  - sqlsrv_connect — Establece una conexión con una base de datos Microsoft SQL Server
  - sqlsrv_errors — Devuelve información de errores y alertas (warnings) de la última operación SQLSRV realizada
  - sqlsrv_execute — Ejecuta una sentencia preparada con sqlsrv_prepare
  - sqlsrv_fetch — Hace que esté disponible para ser leída la siguiente fila del conjunto de resultado
  - sqlsrv_fetch_array — Devuelve una fila como un array
  - sqlsrv_fetch_object — Devuelve la siguiente fila de datos de un conjunto resultado como un objeto
  - sqlsrv_field_metadata — Recupera los datos meta para los campos de una consulta preparada por la función sqlsrv_prepare o la función sqlsrv_query
  - sqlsrv_free_stmt — Libera todos los recursos de la consulta especificada
  - sqlsrv_get_config — Devuelve el valor de la configuración especificada
  - sqlsrv_get_field — Recupera los datos del campo desde la línea actualmente seleccionada
  - sqlsrv_has_rows — Indica si la consulta especificada contiene filas
  - sqlsrv_next_result — Activa el siguiente resultado de la consulta especificada
  - sqlsrv_num_fields — Recupera el número de campos (columnas) en una consulta
  - sqlsrv_num_rows — Recupera el número de filas de un conjunto de resultados
  - sqlsrv_prepare — Prepara una consulta para su ejecución
  - sqlsrv_query — Prepara y ejecuta una consulta
  - sqlsrv_rollback — Anula una transacción que ha sido iniciada gracias a la función sqlsrv_begin_transaction
  - sqlsrv_rows_affected — Devuelve el número de filas modificadas por la última consulta de tipo INSERT, UPDATE, o DELETE
  - sqlsrv_send_stream_data — Envía datos desde el flujo al servidor
  - sqlsrv_server_info — Devuelve información sobre el servidor

- CUBRID
  - Instalación/Configuración
  - Constantes predefinidas
  - Ejemplos
  - Funciones de CUBRID
  - Funciones de compatibilidad CUBRID MySQL
  - Alias y Funciones Obsoletas de CUBRID
- dBase
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones dBase
- Firebird/InterBase
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones Firebird/InterBase
- IBM DB2 — Funciones IBM DB2, Cloudscape y Apache Derby
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones de IBM DB2
- MongoDB — La extensión MongoDB
  - Instalación/Configuración
  - Constantes predefinidas
  - Tutoriales
  - Arquitectura y funcionalidades especiales — Explicaciones de la arquitectura del controlador y de las funcionalidades especiales
  - Seguridad
  - MongoDB\Driver — Clases de la extensión MongoDB
  - MongoDB\BSON — Clases y funciones BSON de MongoDB
  - MongoDB\Driver\Monitoring — Monitorización de clases y funciones de suscriptor
  - MongoDB\Driver\Exception — Clases de excepciones
- MySQL — Plugins y drivers MySQL
  - Visión general de los drivers PHP MySQL
  - MySQLi — Extensión mysqli
  - Mysql_xdevapi
  - MySQL (Original) — API MySQL original
  - Mysqlnd — Controlador Nativo de MySQL
- OCI8 — Oracle OCI8
  - Instalación/Configuración
  - Constantes predefinidas
  - Ejemplos
  - Gestión de la conexión OCI8 y la cola de espera
  - Soporte de FAN (Fast Application Notification : Notificación Rápida de Aplicación) OCI8
  - El soporte de la reanudación transparente de aplicación (TAF) de OCI8
  - OCI8 y rastreo dinámico de DTrace
  - Tipos de datos admitidos
  - Funciones de OCI8
  - OCICollection — La clase OCICollection
  - OCILob — La clase OCILob
  - Funciones y alias de OCI8 obsoletos
- PostgreSQL
  - Instalación/Configuración
  - Constantes predefinidas
  - Ejemplos
  - Funciones de PostgreSQL
  - PgSql\Connection — La clase PgSql\Connection
  - PgSql\Result — La clase PgSql\Result
  - PgSql\Lob — La clase PgSql\Lob
- SQLite3
  - Instalación/Configuración
  - Constantes predefinidas
  - SQLite3 — La clase SQLite3
  - SQLite3Exception — La clase SQLite3Exception
  - SQLite3Stmt — La clase SQLite3Stmt
  - SQLite3Result — La clase SQLite3Result
- SQLSRV — Controlador Microsoft SQL Server para PHP
  - Instalación/Configuración
  - Constantes predefinidas
  - SQLSRV Funciones

- Capas abstractas
  - DBA — Capa de abstracción de base de datos (estilo dbm)
  - ODBC — ODBC (Unificada)
  - PDO — PHP Data Objects
- Extensiones de bases de datos específicas del proveedor
  - CUBRID
  - dBase
  - Firebird/InterBase
  - IBM DB2 — Funciones IBM DB2, Cloudscape y Apache Derby
  - MongoDB — La extensión MongoDB
  - MySQL — Plugins y drivers MySQL
  - OCI8 — Oracle OCI8
  - PostgreSQL
  - SQLite3
  - SQLSRV — Controlador Microsoft SQL Server para PHP

# Extensiones relacionadas con fecha y hora

# Calendario

# Introducción

La extensión Calendario presenta una serie de funciones para simplificar la conversión entre diferentes formatos de calendario. El intermediario o estádar está basado en la Fecha Juliana. La Fecha Juliana es una cuenta de días comenzando desde el 1 de Enero del 4713 A.C. Para hacer la conversión entre sistemas de calendario, primero debe convertir a la Fecha Juliana, y después al sistema de calendario de su elección. ¡La Fecha Juliana es muy diferente del Calendario Juliano! Para más información sobre la Fecha Juliana, visite » http://www.hermetic.ch/cal_stud/jdn.htm. Para más información sobre sistemas de calendario visite » http://www.fourmilab.ch/documents/calendar/. Los extractos de esta página están incluidos en estas instrucciones, y están entrecomillados.

# Instalación/Configuración

## Tabla de contenidos

- Instalación

## Instalación

Para que estas funciones estén disponibles tiene que compilar PHP con --enable-calendar.

La versión Windows de PHP dispone del soporte automático de esta extensión. No es necesario añadir ninguna biblioteca adicional para disponer de estas funciones.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`CAL_EASTER_DEFAULT` (int)
  Para easter_days() : calcula Pascua para los años anteriores a 1753 según el calendario juliano, y para los años posteriores según el calendario gregoriano.
`CAL_EASTER_ROMAN` (int)
  Para easter_days() : calcula Pascua para los años anteriores a 1583 según el calendario juliano, y para los años posteriores según el calendario gregoriano.
`CAL_EASTER_ALWAYS_GREGORIAN` (int)
  Para easter_days() : calcula Pascua según el calendario gregoriano proleptico.
`CAL_EASTER_ALWAYS_JULIAN` (int)
  Para easter_days() : calcula Pascua según el calendario juliano.
`CAL_GREGORIAN` (int)
  Para cal_days_in_month(), cal_from_jd(), cal_info() y cal_to_jd() : utiliza el calendario gregoriano proleptico.
`CAL_JULIAN` (int)
  Para cal_days_in_month(), cal_from_jd(), cal_info() y cal_to_jd() : utiliza el calendario juliano.
`CAL_JEWISH` (int)
  Para cal_days_in_month(), cal_from_jd(), cal_info() y cal_to_jd() : utiliza el calendario hebreo.
`CAL_FRENCH` (int)
  Para cal_days_in_month(), cal_from_jd(), cal_info() y cal_to_jd() : utiliza el calendario republicano.
`CAL_NUM_CALS` (int)
  El número de calendarios disponibles.
`CAL_JEWISH_ADD_ALAFIM_GERESH` (int)
  Para jdtojewish() : añade un símbolo geresh (que se parece a una apostrofe) como separador de miles al número del año.
`CAL_JEWISH_ADD_ALAFIM` (int)
  Para jdtojewish() : añade la palabra alafim como separador de miles al número del año.
`CAL_JEWISH_ADD_GERESHAYIM` (int)
  Para jdtojewish() : añade un símbolo gershayim (que se parece a una comilla) antes de la letra final de los números de día y año.
`CAL_DOW_DAYNO` (int)
  Para jddayofweek() : el día de la semana como int, donde `0` significa Domingo y `6` significa Sábado.
`CAL_DOW_SHORT` (int)
  Para jddayofweek() : el nombre inglés abreviado del día de la semana.
`CAL_DOW_LONG` (int)
  Para jddayofweek() : el nombre inglés del día de la semana.
`CAL_MONTH_GREGORIAN_SHORT` (int)
  Para jdmonthname() : el nombre de mes gregoriano abreviado.
`CAL_MONTH_GREGORIAN_LONG` (int)
  Para jdmonthname() : el nombre de mes gregoriano.
`CAL_MONTH_JULIAN_SHORT` (int)
  Para jdmonthname() : el nombre de mes juliano abreviado.
`CAL_MONTH_JULIAN_LONG` (int)
  Para jdmonthname() : el nombre de mes juliano.
`CAL_MONTH_JEWISH` (int)
  Para jdmonthname() : el nombre de mes hebreo.
`CAL_MONTH_FRENCH` (int)
  Para jdmonthname() : el nombre de mes republicano.

# Funciones de Calendario

# cal_days_in_month

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_days_in_month — Devolver el número de días de un mes para un año y un calendario dados

### Descripción

function cal_days_in_month(int `$calendar`, int `$month`, int `$year`): int

Esta función devolverá el número de días del mes `month` del año `year` para el calendario `calendar` especificado.

### Parámetros

`calendar`

  El calendario que se va a usar para el cálculo

`month`

  El mes del calendario seleccionado

`year`

  El año del calendario seleccionado

### Valores devueltos

La longitud en días del mes seleccionado en el calendario dado.

### Ejemplos

Ejemplo #1 Ejemplo de cal_days_in_month()

    <?php
    $número = cal_days_in_month(CAL_GREGORIAN, 8, 2003); // 31
    echo "Hubo {$número} días en agosto del 2003";
    ?>

# cal_from_jd

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_from_jd — Convierte el número de días Julianos a un calendario específico

### Descripción

function cal_from_jd(int `$julian_day`, int `$calendar`): array

cal_from_jd() convierte el número de días Julianos `julian_day` a una fecha del calendario `calendar`. Los valores posibles para `calendar` son `CAL_GREGORIAN`, `CAL_JULIAN`, `CAL_JEWISH` y `CAL_FRENCH`.

### Parámetros

`julian_day`

  Día Juliano, en forma de un int

`calendar`

  Calendario a utilizar

### Valores devueltos

Retorna un array que contiene información sobre el calendario, como el mes, el día, el año, el día de la semana (`dow`), los nombres abreviados y completos de los días de la semana y del mes, y la fecha, en forma de una string "mes/día/año". El intervalo del día de la semana va de `0` (Domingo) a `6` (Sábado).

### Ejemplos

Ejemplo #1 Ejemplo con cal_from_jd()

    <?php
    $today = unixtojd(mktime(0, 0, 0, 8, 16, 2003));
    print_r(cal_from_jd($today, CAL_GREGORIAN));
    ?>

El ejemplo anterior mostrará:

    Array
    (
       [date] => 8/16/2003
       [month] => 8
       [day] => 16
       [year] => 2003
       [dow] => 6
       [abbrevdayname] => Sat
       [dayname] => Saturday
       [abbrevmonth] => Aug
       [monthname] => August
    )

### Ver también

- cal_to_jd() - Convertir un calendario soportado a la Fecha Juliana
- jdtofrench() - Convierte el número de días del calendario juliano en fecha del calendario francés republicano
- jdtogregorian() - Convierte el número de días del calendario Juliano en fecha Gregoriana
- jdtojewish() - Convierte el número de días del calendario Juliano a fecha del calendario judío
- jdtojulian() - Convierte el número de días del calendario Juliano en fecha del calendario Juliano
- jdtounix() - Convierte un día Juliano en un timestamp UNIX

# cal_info

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_info — Devuelve información sobre un calendario en particular

### Descripción

function cal_info(int `$calendar` = -1): array

cal_info() devuelve información sobre el calendario `calendar` especificado.

La información del calendario es devuelta como una matriz que contiene los elementos `calname`, `calsymbol`, `month`, `abbrevmonth` y `maxdaysinmonth`. Los nombre de los diferentes calendarios que se pueden usar en `calendar` son los siguientes:

- 0 o `CAL_GREGORIAN` - Calendario Gregoriano
- 1 o `CAL_JULIAN` - Calendario Juliano
- 2 o `CAL_JEWISH` - Calendario Judío
- 3 o `CAL_FRENCH` - Calendario Republicano Francés

Si no se especifica `calendar` la información de todos los calendarios soportados es devuelta como un matriz.

### Parámetros

`calendar`

  El calendario del que se va a devolver la información. Si no se especifica ningún calendario se devolverá la información sobre todos los calendarios.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo de cal_info()

    <?php
    $info = cal_info(0);
    print_r($info);
    ?>

El ejemplo anterior mostrará:

    Array
    (
        [months] => Array
            (
                [1] => January
                [2] => February
                [3] => March
                [4] => April
                [5] => May
                [6] => June
                [7] => July
                [8] => August
                [9] => September
                [10] => October
                [11] => November
                [12] => December
            )

        [abbrevmonths] => Array
            (
                [1] => Jan
                [2] => Feb
                [3] => Mar
                [4] => Apr
                [5] => May
                [6] => Jun
                [7] => Jul
                [8] => Aug
                [9] => Sep
                [10] => Oct
                [11] => Nov
                [12] => Dec
            )

        [maxdaysinmonth] => 31
        [calname] => Gregorian
        [calsymbol] => CAL_GREGORIAN
    )

# cal_to_jd

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_to_jd — Convertir un calendario soportado a la Fecha Juliana

### Descripción

function cal_to_jd(
int `$calendar`,
int `$month`,
int `$day`,
int `$year`
): int

cal_to_jd() calcula la Fecha Juliana para una fecha en el calendario `calendar` especificado. Los calendarios `calendar` soportados son `CAL_GREGORIAN`, `CAL_JULIAN`, `CAL_JEWISH` y `CAL_FRENCH`.

### Parámetros

`calendar`

  El calendario desde el que se va a hacer la conversión, `CAL_GREGORIAN`, `CAL_JULIAN`, `CAL_JEWISH` o `CAL_FRENCH`.

`month`

  El mes como número, el rango válido depende de `calendar`

`day`

  El día como número, el rango válido depende de `calendar`

`year`

  El año como número, el rango válido depende de `calendar`

### Valores devueltos

Un número de día de la Fecha Juliana.

### Ver también

- cal_from_jd() - Convierte el número de días Julianos a un calendario específico
- frenchtojd() - Convierte una fecha del Calendario Republicano Francés a una fecha Juliana
- gregoriantojd() - Convierte una fecha gregoriana en número de días del calendario juliano
- jewishtojd() - Convierte una fecha del calendario judío en número de días del calendario juliano
- juliantojd() - Convierte una fecha del Calendario Juliano a una Fecha Juliana
- unixtojd() - Convierte un timestamp UNIX en un día Juliano

# easter_date

(PHP 4, PHP 5, PHP 7, PHP 8)

easter_date — Retorna el timestamp Unix para la medianoche local el día de Pascua de un año dado

### Descripción

function easter_date(?int `$year` = `null`, int `$mode` = `CAL_EASTER_DEFAULT`): int

Retorna un timestamp UNIX para Pascua, a medianoche, para un año dado.

La fecha de Pascua fue establecida por el concilio de Nicea, en 325 de nuestra era, como siendo el domingo después de la primera luna llena que sigue al equinoccio de primavera. El equinoccio de primavera es considerado como siendo siempre el 21 de marzo, lo cual reduce el problema al cálculo de la fecha de la luna llena que sigue, y el domingo siguiente. El algoritmo fue introducido hacia 532, por Dionysius Exiguus. Con el calendario Juliano, (para los años antes de 1753), un ciclo de 19 años es suficiente para conocer las fechas de las fases de la luna. Con el calendario Gregoriano, (a partir de los años 1753, diseñado por Clavius y Lilius, luego introducido por el papa Gregorio XIII en octubre de 1582, y en Gran Bretaña y sus colonias en septiembre de 1752), dos factores de corrección fueron añadidos para hacer el ciclo más preciso.

### Parámetros

`year`

  El año, debe ser un número comprendido entre 1970 y 2037 para los sistemas de 32 bits, o entre 1970 y 2 000 000 000 para los sistemas de 64 bits. Si se omite o es `null`, el valor por omisión será el año actual según la hora local.

`mode`

  Permite calcular la fecha de Pascua según el calendario Juliano cuando se define como `CAL_EASTER_ALWAYS_JULIAN`. Ver también las constantes de calendario.

### Valores devueltos

La fecha para Pascua, en forma de timestamp unix.

### Errores/Excepciones

Se genera una ValueError si el año es anterior a 1970 o posterior a 2037 al ejecutarse en un sistema de 32 bits, o posterior a 2 000 000 000 en un sistema de 64 bits.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | En los sistemas de 64 bits, el argumento `year` ahora acepta valores en el rango de 1970 a 2 000 000 000.
8.0.0 | `year` ahora es nullable.
8.0.0 | Ahora se genera una ValueError cuando `year` está fuera del rango permitido. Anteriormente, se generaba una advertencia `E_WARNING` y la función retornaba `false`.

### Ejemplos

Ejemplo #1 Ejemplo con easter_date()

    <?php

    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

    ?>

Ejemplo #2 Uso de easter_date() con DateTime

    <?php

    $timestamp = easter_date(2023);

    $datetime = new \DateTime();
    $datetime->setTimestamp($timestamp);

    echo $datetime->format('M-d-Y'); // Apr-09-2023

    ?>

### Notas

> Nota:

> La función easter_date() se basa en las funciones de la biblioteca C time del sistema, en lugar de las funciones date y time internas de PHP. Además, la función easter_date() utiliza la variable de entorno `TZ` para determinar la zona horaria a utilizar, en lugar de la zona horaria por defecto de PHP, lo cual puede llevar a un comportamiento no deseado al utilizar esta función con otras funciones date de PHP.

> Como solución alternativa, puede utilizarse la función easter_days() con las clases DateTime y DateInterval para calcular el día de Pascua en la zona horaria de PHP, de la siguiente manera:

>     <?php
>     function get_easter_datetime($year) {
>         $base = new DateTime("$year-03-21");
>         $days = easter_days($year);

>         return $base->add(new DateInterval("P{$days}D"));
>     }

>     foreach (range(2012, 2015) as $year) {
>         printf("Pascua, en %d, cae el %s\n",
>                $year,
>                get_easter_datetime($year)->format('d F'));
>     }
>     ?>

> El ejemplo anterior mostrará:

>     Pascua, en 2012, cae el 08 Abril
>     Pascua, en 2013, cae el 31 Marzo
>     Pascua, en 2014, cae el 20 Abril
>     Pascua, en 2015, cae el 05 Abril

### Ver también

- easter_days() - Retorna el número de días entre el 21 de marzo y Pascua, para un año dado para el cálculo de Pascua antes de 1970 y después de 2037

# easter_days

(PHP 4, PHP 5, PHP 7, PHP 8)

easter_days — Retorna el número de días entre el 21 de marzo y Pascua, para un año dado

### Descripción

function easter_days(?int `$year` = `null`, int `$mode` = `CAL_EASTER_DEFAULT`): int

Retorna el número de días entre el 21 de marzo y Pascua, para un año dado. Si el año no está especificado, se utilizará el año actual.

Esta función puede ser utilizada en lugar de easter_date() para calcular la fecha de Pascua, para los años que caen fuera del intervalo de validez de los timestamps UNIX (es decir, antes de 1970 o después de 2037).

La fecha de Pascua fue fijada por el concilio de Nicea, en 325 de nuestra era, como siendo el domingo después de la primera luna llena que sigue al equinoccio de primavera. El equinoccio de primavera es considerado como siendo siempre el 21 de marzo, lo que reduce el problema al cálculo de la fecha de la luna llena que sigue, y el domingo siguiente. El algoritmo fue introducido hacia 532, por Dionysius Exiguus. Con el calendario Juliano, (para los años antes de 1753), un ciclo de 19 años es suficiente para conocer las fechas de las fases de la luna. Con el calendario Gregoriano, (a partir de los años 1753, diseñado por Clavius y Lilius, luego introducido por el papa Gregorio XIII en octubre de 1582, y en Gran Bretaña y sus colonias en septiembre de 1752), dos factores de corrección fueron añadidos para hacer el ciclo más preciso.

### Parámetros

`year`

  El año, en forma de un número positivo. Si se omite o es `null`, el valor por defecto será el año actual según la hora local.

`mode`

  Permite el cálculo de las fechas de Pascua basándose en el calendario Gregoriano para los años entre 1582 y 1752 cuando se define como `CAL_EASTER_ROMAN`. Ver las constantes de los calendarios para más constantes válidas.

### Valores devueltos

El número de días entre el 21 de marzo y Pascua, para el año `year` proporcionado.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `year` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con easter_days()

    <?php

    echo easter_days(1999);        // 14, es decir, 4 de abril
    echo easter_days(1492);        // 32, es decir, 22 de abril
    echo easter_days(1913);        //  2, es decir, 23 de marzo

    ?>

### Ver también

- easter_date() - Retorna el timestamp Unix para la medianoche local el día de Pascua de un año dado

# frenchtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

frenchtojd — Convierte una fecha del Calendario Republicano Francés a una fecha Juliana

### Descripción

function frenchtojd(int `$month`, int `$day`, int `$year`): int

Convierte una fecha del Calendario Republicano Francés a una fecha Juliana.

Estas rutinas sólamente convierten fechas de los años 1 al 14 (fechas gregorianas desde el 22 de septiembre de 1792 hasta el 22 de septiembre de 1806). Esto cubre con creces el periodo cuando el calendario estaba en uso.

### Parámetros

`month`

  El mes como un número desde 1 (para Vendémiaire) hasta 13 (para el periodo de 5-6 días al final de cada año)

`day`

  El día como un número de 1 a 30

`year`

  El año como un número entre 1 y 14

### Valores devueltos

La fecha Juliana para la fecha de la Revolución Francesa dada como un entero.

### Ver también

- jdtofrench() - Convierte el número de días del calendario juliano en fecha del calendario francés republicano
- cal_to_jd() - Convertir un calendario soportado a la Fecha Juliana

# gregoriantojd

(PHP 4, PHP 5, PHP 7, PHP 8)

gregoriantojd — Convierte una fecha gregoriana en número de días del calendario juliano

### Descripción

function gregoriantojd(int `$month`, int `$day`, int `$year`): int

El intervalo de validez para el calendario gregoriano es del 25 de noviembre, 4714 a.C. al menos hasta el 31 de diciembre 9999 d.C.

Aunque es posible manipular fechas hasta el 4714 a.C., tal uso no es significativo. Este calendario fue creado el 18 de octubre de 1582 d.C. (o 5 de octubre 1582 en calendario juliano). Algunos países no lo aceptaron hasta mucho más tarde. Por ejemplo, los británicos no lo adoptaron hasta 1752, los rusos en 1918 y los griegos en 1923. La mayoría de los países europeos utilizaban el calendario juliano antes del gregoriano.

### Parámetros

`month`

  El mes, en forma de número comprendido entre 1 (para Enero) y 12 (para Diciembre)

`day`

  El día, en forma de número comprendido entre 1 y 31. Si el mes tiene menos días de los proporcionados, se produce un desbordamiento; ver ejemplo a continuación.

`year`

  El año, en forma de número comprendido entre -4714 y 9999. Los números negativos significan años antes de C., los números positivos significan después de C. Se observa que no existe el año `0`; 31 de diciembre, 1 a.C. es inmediatamente seguido por 1 de enero, 1 d.C.

### Valores devueltos

El día juliano para la fecha gregoriana proporcionada, en forma de int. Las fechas fuera del intervalo válido devuelven `0`.

### Ejemplos

Ejemplo #1 Funciones calendario

    <?php
    $jd = gregoriantojd(10, 11, 1970);
    echo "$jd\n";
    $gregorian = jdtogregorian($jd);
    echo "$gregorian\n";
    ?>

El ejemplo anterior mostrará:

    2440871
    10/11/1970

Ejemplo #2 Comportamiento de desbordamiento

    <?php
    echo gregoriantojd(2, 31, 2018), PHP_EOL,
         gregoriantojd(3,  3, 2018), PHP_EOL;
    ?>

El ejemplo anterior mostrará:

    2458181
    2458181

### Ver también

- jdtogregorian() - Convierte el número de días del calendario Juliano en fecha Gregoriana
- cal_to_jd() - Convertir un calendario soportado a la Fecha Juliana

# jddayofweek

(PHP 4, PHP 5, PHP 7, PHP 8)

jddayofweek — Devuelve el número del día de la semana

### Descripción

function jddayofweek(int `$julian_day`, int `$mode` = `CAL_DOW_DAYNO`): int|string

Devuelve el número del día de la semana. Puede devolver una cadena o un entero, dependiendo del modo.

### Parámetros

`julian_day`

  El número del día juliano, en forma de int.

`mode`

  Modos para la semana del calendario
  Modo | Significado
  --- | ---
  0 (por omisión) | Devuelve el número del día como un entero (0=domingo, 1=lunes, etc.)
  1 | Devuelve una cadena que contiene el nombre del día (inglés gregoriano)
  2 | Devuelve una cadena que contiene el nombre abreviado del día de la semana (inglés gregoriano)

### Valores devueltos

El día de la semana gregoriano, en forma de int o de string.

# jdmonthname

(PHP 4, PHP 5, PHP 7, PHP 8)

jdmonthname — Devuelve el nombre del mes

### Descripción

function jdmonthname(int `$julian_day`, int `$mode`): string

Devuelve una cadena que contiene el nombre del mes. `mode` indica de qué calendario depende este mes, y qué tipo de nombre debe ser devuelto.

Modos de calendario
Modo | Significado | Valores
--- | --- | ---
`CAL_MONTH_GREGORIAN_SHORT` | Gregoriano - abreviado | Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
`CAL_MONTH_GREGORIAN_LONG` | Gregoriano | January, February, March, April, May, June, July, August, September, October, November, December
`CAL_MONTH_JULIAN_SHORT` | Juliano - abreviado | Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
`CAL_MONTH_JULIAN_LONG` | Juliano | January, February, March, April, May, June, July, August, September, October, November, December
`CAL_MONTH_JEWISH` | Judío | Tishri, Heshvan, Kislev, Tevet, Shevat, Adar, Adar I, Adar II, Nisan, Iyyar, Sivan, Tammuz, Av, Elul
`CAL_MONTH_FRENCH` | Francés republicano | Vendemiaire, Brumaire, Frimaire, Nivose, Pluviose, Ventose, Germinal, Floreal, Prairial, Messidor, Thermidor, Fructidor, Extra

### Parámetros

`julian_day`

  El día juliano a analizar

`mode`

  El modo de calendario (ver tabla anterior).

### Valores devueltos

El nombre del mes para el día juliano y el `mode`.

# jdtofrench

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtofrench — Convierte el número de días del calendario juliano en fecha del calendario francés republicano

### Descripción

function jdtofrench(int `$julian_day`): string

Convierte el número de días del calendario juliano en fecha del calendario francés republicano.

### Parámetros

`julian_day`

  El número del día juliano, en forma de int

### Valores devueltos

La fecha francesa republicana, en forma de string "mes/día/año".

### Ver también

- frenchtojd() - Convierte una fecha del Calendario Republicano Francés a una fecha Juliana
- cal_from_jd() - Convierte el número de días Julianos a un calendario específico

# jdtogregorian

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtogregorian — Convierte el número de días del calendario Juliano en fecha Gregoriana

### Descripción

function jdtogregorian(int `$julian_day`): string

Convierte el número de días del calendario Juliano en una cadena que contiene una fecha del calendario Gregoriano, en formato "mes/día/año".

### Parámetros

`julian_day`

  El número del día Juliano, en forma de int

### Valores devueltos

La fecha Gregoriana, en forma de string "mes/día/año".

### Ver también

- gregoriantojd() - Convierte una fecha gregoriana en número de días del calendario juliano
- cal_from_jd() - Convierte el número de días Julianos a un calendario específico

# jdtojewish

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtojewish — Convierte el número de días del calendario Juliano a fecha del calendario judío

### Descripción

function jdtojewish(int `$julian_day`, bool `$hebrew` = `false`, int `$flags` = 0): string

Convierte un número de días del calendario Juliano a calendario judío.

### Parámetros

`julian_day`

  Un número de día Juliano en forma de int.

`hebrew`

  Si el argumento `hebrew` está definido como `true`, el argumento `flags` se utiliza para el hebreo, formato de salida basado en una string codificada ISO-8859-8.

`flags`

  Una máscara a nivel de bits que puede consistir en `CAL_JEWISH_ADD_ALAFIM_GERESH`, `CAL_JEWISH_ADD_ALAFIM` y `CAL_JEWISH_ADD_GERESHAYIM`.

### Valores devueltos

La fecha judía, en forma de string "mes/día/año", o una string de fecha hebrea codificada ISO-8859-8, dependiendo del argumento `hebrew`.

### Ejemplos

Ejemplo #1 Ejemplo con jdtojewish()

    <?php
    $jd = gregoriantojd(10, 8, 2002);
    echo jdtojewish($jd, true), PHP_EOL,
         jdtojewish($jd, true, CAL_JEWISH_ADD_GERESHAYIM), PHP_EOL,
         jdtojewish($jd, true, CAL_JEWISH_ADD_ALAFIM), PHP_EOL,
         jdtojewish($jd, true,CAL_JEWISH_ADD_ALAFIM_GERESH), PHP_EOL;
    ?>

El ejemplo anterior mostrará:

    ב חשון התשסג
    ב' חשון התשס"ג
    ב חשון ה אלפים תשסג
    ב חשון ה'תשסג

### Ver también

- jewishtojd() - Convierte una fecha del calendario judío en número de días del calendario juliano
- cal_from_jd() - Convierte el número de días Julianos a un calendario específico

# jdtojulian

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtojulian — Convierte el número de días del calendario Juliano en fecha del calendario Juliano

### Descripción

function jdtojulian(int `$julian_day`): string

Convierte el número de días del calendario Juliano en una cadena que contiene la fecha del calendario Juliano, en formato "mes/día/año".

### Parámetros

`julian_day`

  El número de días Julianos, en forma de int

### Valores devueltos

La fecha Juliana, en forma de string "mes/día/año".

### Ver también

- juliantojd() - Convierte una fecha del Calendario Juliano a una Fecha Juliana
- cal_from_jd() - Convierte el número de días Julianos a un calendario específico

# jdtounix

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtounix — Convierte un día Juliano en un timestamp UNIX

### Descripción

function jdtounix(int `$julian_day`): int

Esta función devuelve un timestamp UNIX correspondiente al día Juliano dado en `julian_day`. El tiempo devuelto es UTC.

### Parámetros

`julian_day`

  El número de días Julianos, comprendido entre `2440588` y `106751993607888` en sistemas de 64 bits, o comprendido entre `2440588` y `2465443` en sistemas de 32 bits.

### Valores devueltos

El timestamp UNIX para el inicio (medianoche, no mediodía) del día Juliano dado.

### Errores/Excepciones

Si `julian_day` está fuera del intervalo permitido, se lanza una ValueError.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función ya no devuelve `false` en caso de error, sino que lanza una ValueError en su lugar.
7.3.24, 7.4.12 | El límite superior del parámetro `julian_day` ha sido extendido. Antes, era de `2465342` según la arquitectura.

### Ver también

- unixtojd() - Convierte un timestamp UNIX en un día Juliano

# jewishtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

jewishtojd — Convierte una fecha del calendario judío en número de días del calendario juliano

### Descripción

function jewishtojd(int `$month`, int `$day`, int `$year`): int

Aunque es posible manipular fechas a partir del año 1 (3761 antes de J.C.), un uso de este tipo tiene poco sentido. El calendario judío ha sido utilizado durante varios siglos, pero en los primeros tiempos no existía una fórmula para determinar el inicio del mes. Un nuevo mes comenzaba cuando una nueva luna era observada.

### Parámetros

`month`

  El mes, en forma de número entre `1` y `13`, donde `1` significa `Tishri`, `13` significa `Eloul`, y `6` y `7` significa `Adar` en los años regulares, pero `Adar I` y `Adar II`, respectivamente, en los años bisiestos.

`day`

  El día, en forma de número entre `1` y `30`. Si el mes tiene solo 29 días, se asume el primer día del mes siguiente.

`year`

  El año, en forma de número entre 1 y 9999

### Valores devueltos

El día juliano para la fecha judía dada, en forma de int.

### Ver también

- jdtojewish() - Convierte el número de días del calendario Juliano a fecha del calendario judío
- cal_to_jd() - Convertir un calendario soportado a la Fecha Juliana

# juliantojd

(PHP 4, PHP 5, PHP 7, PHP 8)

juliantojd — Convierte una fecha del Calendario Juliano a una Fecha Juliana

### Descripción

function juliantojd(int `$month`, int `$day`, int `$year`): int

El rango válido para el Calendario Juliano es desde 4713 A.C. a 9999 D.C.

Aunque esta función puede manejar fechas que se remontan hasta 4713 A.C., tal uso puede no ser significativo. El calendario fue creado en el 46 A.C., pero los detalles no se estabilizaron hasta al menos el 8 D.C., y quizás hasta el siglo IV tardío. También, el comienzo de un año variaba de una cultura a otra - no todas aceptaron enero como el primer mes.

Precaución

Recuerde, el sistema de calendario actual que se usa mundialmente es el Calendario Gregoriano. gregoriantojd() se puede usar para convertir tales fechas a sus Fechas Julianas.

### Parámetros

`month`

  El mes como un número de 1 (para enero) a 12 (para diecienbre)

`day`

  El día como un número de 1 a 31

`year`

  El año como un número entre -4713 y 9999

### Valores devueltos

La Fecha Juliana para la fecha del Calendario Juliano dado como un entero.

### Ver también

- jdtojulian() - Convierte el número de días del calendario Juliano en fecha del calendario Juliano
- cal_to_jd() - Convertir un calendario soportado a la Fecha Juliana

# unixtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

unixtojd — Convierte un timestamp UNIX en un día Juliano

### Descripción

function unixtojd(?int `$timestamp` = `null`): int|false

Devuelve el día Juliano del timestamp UNIX `timestamp` (número de segundos desde el 1/1/1970), o para el día actual si `timestamp` es omitido. En cualquier caso, la hora es considerada como la hora local (no UTC).

### Parámetros

`timestamp`

  Un timestamp UNIX a convertir.

### Valores devueltos

Un número de días Julianos, en forma de int, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `timestamp` ahora es nullable.

### Ver también

- jdtounix() - Convierte un día Juliano en un timestamp UNIX

## Tabla de contenidos

- cal_days_in_month — Devolver el número de días de un mes para un año y un calendario dados
- cal_from_jd — Convierte el número de días Julianos a un calendario específico
- cal_info — Devuelve información sobre un calendario en particular
- cal_to_jd — Convertir un calendario soportado a la Fecha Juliana
- easter_date — Retorna el timestamp Unix para la medianoche local el día de Pascua de un año dado
- easter_days — Retorna el número de días entre el 21 de marzo y Pascua, para un año dado
- frenchtojd — Convierte una fecha del Calendario Republicano Francés a una fecha Juliana
- gregoriantojd — Convierte una fecha gregoriana en número de días del calendario juliano
- jddayofweek — Devuelve el número del día de la semana
- jdmonthname — Devuelve el nombre del mes
- jdtofrench — Convierte el número de días del calendario juliano en fecha del calendario francés republicano
- jdtogregorian — Convierte el número de días del calendario Juliano en fecha Gregoriana
- jdtojewish — Convierte el número de días del calendario Juliano a fecha del calendario judío
- jdtojulian — Convierte el número de días del calendario Juliano en fecha del calendario Juliano
- jdtounix — Convierte un día Juliano en un timestamp UNIX
- jewishtojd — Convierte una fecha del calendario judío en número de días del calendario juliano
- juliantojd — Convierte una fecha del Calendario Juliano a una Fecha Juliana
- unixtojd — Convierte un timestamp UNIX en un día Juliano

- Instalación/Configuración
  - Instalación
- Constantes predefinidas
- Funciones de Calendario
  - cal_days_in_month — Devolver el número de días de un mes para un año y un calendario dados
  - cal_from_jd — Convierte el número de días Julianos a un calendario específico
  - cal_info — Devuelve información sobre un calendario en particular
  - cal_to_jd — Convertir un calendario soportado a la Fecha Juliana
  - easter_date — Retorna el timestamp Unix para la medianoche local el día de Pascua de un año dado
  - easter_days — Retorna el número de días entre el 21 de marzo y Pascua, para un año dado
  - frenchtojd — Convierte una fecha del Calendario Republicano Francés a una fecha Juliana
  - gregoriantojd — Convierte una fecha gregoriana en número de días del calendario juliano
  - jddayofweek — Devuelve el número del día de la semana
  - jdmonthname — Devuelve el nombre del mes
  - jdtofrench — Convierte el número de días del calendario juliano en fecha del calendario francés republicano
  - jdtogregorian — Convierte el número de días del calendario Juliano en fecha Gregoriana
  - jdtojewish — Convierte el número de días del calendario Juliano a fecha del calendario judío
  - jdtojulian — Convierte el número de días del calendario Juliano en fecha del calendario Juliano
  - jdtounix — Convierte un día Juliano en un timestamp UNIX
  - jewishtojd — Convierte una fecha del calendario judío en número de días del calendario juliano
  - juliantojd — Convierte una fecha del Calendario Juliano a una Fecha Juliana
  - unixtojd — Convierte un timestamp UNIX en un día Juliano

# Fecha y Hora

# Introducción

DateTimeImmutable y las clases asociadas permiten representar las informaciones de fecha y hora. Los objetos pueden ser creados pasando las informaciones de fecha y hora mediante una cadena de caracteres, o a partir de la hora del sistema utilizado.

Un conjunto rico de métodos es proporcionado para modificar y formatear estas informaciones así como la gestión de los husos horarios y las transiciones DST.

Las funcionalidades de fecha/hora de PHP implementan el calendario ISO 8601, que es un » calendario Gregoriano proleptico implementando las reglas actuales de los días bisiestos antes de la puesta en marcha del calendario Gregoriano, e incluye también el año `0` como número de año comprendido entre `-1 antes de la era común` y `1 de la era común`. Los segundos intercalares no son soportados.

Las informaciones relativas a la fecha y la hora son almacenadas internamente como número de 64 bits, por lo tanto, todas las fechas imaginables (incluyendo las fechas negativas) son soportadas. El intervalo va de 292 mil millones de años en el pasado, y el mismo valor en el futuro.

> Nota: Los husos horarios referenciados en esta sección pueden ser encontrados en la sección Lista de Zonas Horarias Soportadas.

# Instalación/Configuración

## Tabla de contenidos

- Instalación
- Configuración en tiempo de ejecución

## Instalación

No hay instalación necesaria para usar estas funciones, son parte del núcleo de PHP.

> Nota: Recuperación de la última base de datos de los husos horarios

> La última versión de la base de datos de los husos horarios puede ser instalada mediante el paquete PECL » timezonedb.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración para fechas y horas
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
date.default_latitude | "31.7667" | `INI_ALL` |
date.default_longitude | "35.2333" | `INI_ALL` |
date.sunrise_zenith | "90.833333" | `INI_ALL` | Antes de PHP 8.0.0, el valor por omisión era "90.583333"
date.sunset_zenith | "90.833333" | `INI_ALL` | Antes de PHP 8.0.0, el valor por omisión era "90.583333"
date.timezone | "UTC" | `INI_ALL` | Desde PHP 8.2, se emite una advertencia si la opción se define con un valor inválido o una cadena vacía.

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`date.default_latitude` float

  La latitud por omisión que va desde `0` en el ecuador, hasta `+90` en dirección norte, y `-90` en dirección sur.

`date.default_longitude` float

  La longitud por omisión que va desde `0` en el meridiano de origen, hasta `+180` en dirección este, y `-180` en dirección oeste.

`date.sunrise_zenith` float

  La hora de salida del sol por omisión.

  El valor por omisión es 90°50'. Los 50' adicionales se deben a dos componentes: el radio del Sol, que es de 16', y la refracción atmosférica, que es de 34'.

`date.sunset_zenith` float

  La hora de puesta del sol por omisión.

`date.timezone` string

  La zona horaria por omisión utilizada por todas las funciones de fecha/hora. El orden de las zonas horarias utilizadas si ninguna se especifica está descrito explícitamente en la página de documentación de la función date_default_timezone_get(). Ver Lista de Zonas Horarias Soportadas para una lista completa de las zonas horarias soportadas.

> Nota: Las cuatro primeras opciones de configuración se utilizan actualmente únicamente por las funciones date_sunrise() y date_sunset().

# Constantes predefinidas

Las contantes `DATE_*` están definidas y ofrecen representaciones de fecha estándar que pueden ser empleadas por funciones de formato de fecha (como date()).

Disponibles como `returnFormat` para date_sunrise() y date_sunset()
Advertencia

Estas constantes están obsoletas desde PHP 8.4.0. Las funciones correspondientes date_sunrise() y date_sunset() están obsoletas desde PHP 8.1.0.

`SUNFUNCS_RET_TIMESTAMP` (int)
  Timestamp
`SUNFUNCS_RET_STRING` (int)
  Horas:minutos (ejemplo: `08:02`)
`SUNFUNCS_RET_DOUBLE` (int)
  Horas como número con decimales (ejemplo `8.75`)

Constantes `DATE_*`
`DATE_ATOM` (string)
  Atom (ejemplo: `2005-08-15T15:52:01+00:00`); compatible con ISO-8601, RFC 3339 y XML Schema
`DATE_COOKIE` (string)
  HTTP Cookies (ejemplo: `Monday, 15-Aug-2005 15:52:01 UTC`)
`DATE_ISO8601` (string)
  Similar a ISO-8601 (ejemplo: `2005-08-15T15:52:01+0000`)

  > Nota: Este formato no es compatible con el ISO-8601, aunque se deja por razones de retrocompatibilidad. Use `DATE_ISO8601_EXPANDED`, `DATE_ATOM` en su lugar para que sea compatible con el ISO-8601. (ref ISO8601:2004 section 4.3.3 clause d)

`DATE_ISO8601_EXPANDED` (string)
  ISO-8601 Extendido (ejemplo: `+10191-07-26T08:59:52+01:00`)

  > Nota: Este formato permite rangos de años fuera del rango normal de ISO-8601 de `0000`-`9999` al incluir siempre un carácter de signo. También asegura que la parte de la zona horaria (`+01:00`) sea compatible con ISO-8601.

`DATE_RFC822` (string)
  RFC 822 (ejemplo: `Mon, 15 Aug 05 15:52:01 +0000`)
`DATE_RFC850` (string)
  RFC 850 (ejemplo: `Monday, 15-Aug-05 15:52:01 UTC`)
`DATE_RFC1036` (string)
  RFC 1036 (ejemplo: `Mon, 15 Aug 05 15:52:01 +0000`)
`DATE_RFC1123` (string)
  RFC 1123 (ejemplo: `Mon, 15 Aug 2005 15:52:01 +0000`)
`DATE_RFC7231` (string)
  RFC 7231 (desde PHP 7.0.19 y 7.1.5) (ejemplo: `Sat, 30 Apr 2016 17:52:13 GMT`)
`DATE_RFC2822` (string)
  RFC 2822 (ejemplo: `Mon, 15 Aug 2005 15:52:01 +0000`)
`DATE_RFC3339` (string)
  Igual que `DATE_ATOM`.
`DATE_RFC3339_EXTENDED` (string)
  Formato RFC 3339 EXTENDED (ejemplo: `2005-08-15T15:52:01.000+00:00`)
`DATE_RSS` (string)
  RSS (ejemplo: `Mon, 15 Aug 2005 15:52:01 +0000`). Alias de `DATE_RFC1123`.
`DATE_W3C` (string)
  World Wide Web Consortium (ejemplo: `2005-08-15T15:52:01+00:00`). Alias de `DATE_RFC3339`.

# Ejemplos

## Tabla de contenidos

- Aritmética con DateTime

## Aritmética con DateTime

Los ejemplos siguientes muestran algunos problemas de la aritmética de DateTime en lo que respecta a las transiciones DST y los meses con diferente número de días.

Ejemplo #1 DateTimeImmutable::add/sub añadir un intervalo de tiempo transcurrido

Añadir PT24H más allá de una transición DST parecerá añadir 23/25 horas (para la mayoría de los husos horarios).

    <?php
    $dt = new DateTimeImmutable("2015-11-01 00:00:00", new DateTimeZone("America/New_York"));
    echo "Inicio: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->add(new DateInterval("PT3H"));
    echo "Fin:    ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

El ejemplo anterior mostrará:

    Inicio:2015-11-01 00:00:00 -04:00
    Fin:2015-11-01 02:00:00 -05:00

Ejemplo #2 DateTimeImmutable::modify y strtotime incrementar o decrementar valores individuales

Añadir +24 horas más allá de una transición DST puede añadir exactamente 24 horas como se ve con la cadena fecha/hora (excepto si la hora de inicio o fin está en un punto de transición).

    <?php
    $dt = new DateTimeImmutable("2015-11-01 00:00:00", new DateTimeZone("America/New_York"));
    echo "Inicio: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("+24 hours");
    echo "Fin:    ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

El ejemplo anterior mostrará:

    Inicio:2015-11-01 00:00:00 -04:00
    Fin:2015-11-02 00:00:00 -05:00

Ejemplo #3 La adición o sustracción de fechas/horas puede exceder (en más o en menos) fechas

Como para 31 de Enero + 1 mes dará como resultado 2 de Marzo (año bisiesto) o 3 de Marzo (año normal).

    <?php
    echo "Año normal:\n"; // febrero tiene 28 días
    $dt = new DateTimeImmutable("2015-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Inicio: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("+1 month");
    echo "Fin:    ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

    echo "Año bisiesto:\n"; // febrero tiene 29 días
    $dt = new DateTimeImmutable("2016-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Inicio: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("+1 month");
    echo "Fin:    ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

El ejemplo anterior mostrará:

    Año normal:
    Inicio:2015-01-31 00:00:00 -05:00
    Fin:2015-03-03 00:00:00 -05:00
    Año bisiesto:
    Inicio:2016-01-31 00:00:00 -05:00
    Fin:2016-03-02 00:00:00 -05:00

Para obtener el último día del mes próximo (es decir, para prever el excedente), el formato `last day of` está disponible.

    <?php
    echo "Año normal:\n"; // febrero tiene 28 días
    $dt = new DateTimeImmutable("2015-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Inicio: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("last day of next month");
    echo "Fin:    ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

    echo "Año bisiesto:\n"; // febrero tiene 29 días
    $dt = new DateTimeImmutable("2016-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Inicio: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("last day of next month");
    echo "Fin:    ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

El ejemplo anterior mostrará:

    Año normal:
    Inicio:2015-01-31 00:00:00 -05:00
    Fin:2015-02-28 00:00:00 -05:00
    Año bisiesto:
    Inicio:2016-01-31 00:00:00 -05:00
    Fin:2016-02-29 00:00:00 -05:00

# La clase DateTime

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

## Introducción

Representación de la fecha y la hora.

Esta clase se comporta igual que DateTimeImmutable, excepto que los objetos se modifican cuando se llaman métodos de modificación como DateTime::modify().

Advertencia

Llamando metodos en objetos de la clase DateTime cambiará la información encapsulada en ese objeto, si deseas prevenir eso tendrás que usar el operador `clone` para crear un nuevo objeto. Usa DateTimeImmutable en lugar de DateTime para obtener este comportamiento recomendado por defecto.

## Sinopsis de la Clase

class DateTime implements DateTimeInterface {
/* Constantes heredadas */
public const string DateTimeInterface::ATOM = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::COOKIE = "l, d-M-Y H:i:s T";
public const string DateTimeInterface::ISO8601 = "Y-m-d\\TH:i:sO";
public const string DateTimeInterface::ISO8601_EXPANDED = "X-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC822 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC850 = "l, d-M-y H:i:s T";
public const string DateTimeInterface::RFC1036 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC1123 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC7231 = "D, d M Y H:i:s \\G\\M\\T";
public const string DateTimeInterface::RFC2822 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC3339 = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC3339_EXTENDED = "Y-m-d\\TH:i:s.vP";
public const string DateTimeInterface::RSS = "D, d M Y H:i:s O";
public const string DateTimeInterface::W3C = "Y-m-d\\TH:i:sP";
/* Métodos */
public function __construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)
public function add(DateInterval `$interval`): DateTime
public static function createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTime|false
public static function createFromImmutable(DateTimeImmutable `$object`): static
public static function createFromInterface(DateTimeInterface `$object`): DateTime
public static function createFromTimestamp(int|float `$timestamp`): static
public function modify(string `$modifier`): DateTime
public static function __set_state(array `$array`): DateTime
public function setDate(int `$year`, int `$month`, int `$day`): DateTime
public function setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTime
public function setMicrosecond(int `$microsecond`): static
public function setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTime
public function setTimestamp(int `$timestamp`): DateTime
public function setTimezone(DateTimeZone `$timezone`): DateTime
public function sub(DateInterval `$interval`): DateTime
public function diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function format(string `$format`): string
public function getMicrosecond(): int
public function getOffset(): int
public function getTimestamp(): int
public function getTimezone(): DateTimeZone|false
public function __serialize(): array
public function __unserialize(array `$data`): void
#[\Deprecated]
public function __wakeup(): void
}

## Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Las constantes de clase ahora están tipadas.
7.2.0 | Las constantes de clase de DateTime ahora están definidas en DateTimeInterface.
7.1.0 | El constructor de DateTime ahora incluye los microsegundos actuales en el valor construido. Antes de esto, siempre inicializaría los microsegundos a `0`.

# DateTime::add

# date_add

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::add -- date_add — Modifica un objeto DateTime, añadiendo una cantidad de días, meses, años, horas, minutos y segundos

### Descripción

Estilo orientado a objetos

public function DateTime::add(DateInterval `$interval`): DateTime

Estilo procedimental

function date_add(DateTime `$object`, DateInterval `$interval`): DateTime

Añade el objeto DateInterval especificado al objeto DateTime especificado.

Igual que DateTimeImmutable::add(), pero funciona con DateTime.

La versión procedimental toma el objeto DateTime como su primer argumento.

### Parámetros

`object`
  Solo en estilo procedimental: Un objeto DateTime retornado por la función date_create(). Esta función modifica este objeto.
`interval`

  Un objeto DateInterval

### Valores devueltos

Retorna el objeto modificado DateTime para encadenar métodos.

### Ver también

- DateTimeImmutable::add() - Devuelve un nuevo objeto, con una cantidad añadida de días, meses, años, horas, minutos y segundos

# DateTime::__construct

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::__construct — Devuelve un nuevo objeto DateTime

### Descripción

public function DateTime::__construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)

Igual que DateTimeImmutable::__construct() pero funciona con DateTime. Considere usar DateTimeImmutable y sus características en su lugar.

Devuelve un nuevo objeto DateTime.

### Parámetros

`datetime`

  Una cadena de fecha/hora. Los formatos válidos son explicados en la documentación sobre los formatos de Fecha y Hora.

  Introduzca `"now"` aquí para obtener el instante actual cuando se emplee el parámetro `$timezone`.

`timezone`

  Un objeto DateTimeZone que representa la zona horaria de `$datetime`.

  Si se omite `$timezone` o es `null`, se usará la zona horaria actual.

  > Nota:

  > El parámetro `$timezone` y la zona horaria actuales se ignoran cuando el parámetro `$time` es una marca temporal de UNIX (p.ej. `@946684800`) o especifica una zona horaria (p.ej. `2010-01-28T15:00:00+02:00`).

### Valores devueltos

Devuelve una nueva instancia de DateTime.

### Errores/Excepciones

Si se pasa una cadena de fecha/hora incorrecta, lanza DateMalformedStringException. Hasta PHP 8.3, lanzaba Exception.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Ahora lanza DateMalformedStringException si se pasa una cadena incorrecta, en vez de Exception.

### Ver también

- DateTimeImmutable::__construct() - Devuelve un nuevo objeto DateTimeImmutable

# DateTime::createFromFormat

# date_create_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::createFromFormat -- date_create_from_format — Analiza una cadena con un instante según un formato especificado

### Descripción

Estilo orientado a objetos

public static function DateTime::createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTime|false

Estilo procedimental

function date_create_from_format(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTime|false

Devuelve un nuevo objeto DateTime que representa la fecha y la hora especificadas por la cadena `time`, la cual fue formateada en el formato indicado en `format`.

Igual que DateTimeImmutable::createFromFormat() y date_create_immutable_from_format(), respectivamente, pero crea un objeto DateTime.

Este método, incluyendo parámetros, ejemplos y consideraciones están documentados en la página DateTimeImmutable::createFromFormat.

### Parámetros

Vease DateTimeImmutable::createFromFormat.

### Valores devueltos

Devuelve una nueva instancia de DateTime o `false` si ocurre un error.

### Errores/Excepciones

Este método lanza ValueError cuando `datetime` contiene bytes nulos (NULL-bytes).

### Historial de cambios

Versión | Descripción
--- | ---
8.0.21, 8.1.8, 8.2.0 | Ahora lanza ValueError cuando se pasan bytes nulos (NULL-bytes) a `datetime`, cuando antes eran ignorados silenciosamente.

### Ejemplos

Para una lista extensa de ejemplos, vea DateTimeImmutable::createFromFormat.

### Ver también

- DateTimeImmutable::createFromFormat() - Analiza un string de tiempo según el formato especificado

# DateTime::createFromImmutable

(PHP 7 >= 7.3.0, PHP 8)

DateTime::createFromImmutable — Devuelve una nueva instancia de DateTime encapsulando el objeto DateTimeImmutable dado

### Descripción

public static function DateTime::createFromImmutable(DateTimeImmutable `$object`): static

### Parámetros

`object`

  El objeto DateTimeImmutable inmutable que necesita ser convertido a una versión mutable. Este objeto no es modificado, sino que en su lugar se crea una nueva instancia de DateTime que contiene la misma fecha, hora y zona horaria.

### Valores devueltos

Devuelve una nueva instancia de DateTime.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | El método ahora devuelve una instancia de la clase actualmente invocada. Anteriormente, creaba una nueva instancia de DateTime.

### Ejemplos

Ejemplo #1 Creando un objeto de fecha y hora mutable

    <?php
    $date = new DateTimeImmutable("2014-06-20 11:45 Europe/London");
    $mutable = DateTime::createFromImmutable( $date );

# DateTime::createFromInterface

(PHP 8)

DateTime::createFromInterface — RDevuelve un nuevo objeto DateTime que encapsula el objeto DateTimeInterface dado

### Descripción

public static function DateTime::createFromInterface(DateTimeInterface `$object`): DateTime

### Parámetros

`object`

  El objeto DateTimeInterface que necesita ser convertido a una versión mutable. Este objeto no se modifica, sino que en su lugar se crea un nuevo objeto DateTime que contiene la misma información de fecha, hora y zona horaria.

### Valores devueltos

Devuelve una nueva instancia de DateTime.

### Ejemplos

Ejemplo #1 Creando un objeto fecha y hora mutable

    <?php
    $date = new DateTimeImmutable("2014-06-20 11:45 Europe/London");
    $mutable = DateTime::createFromInterface($date);

    $date = new DateTime("2014-06-20 11:45 Europe/London");
    $also_mutable = DateTime::createFromInterface($date);

# DateTime::createFromTimestamp

(PHP 8 >= 8.4.0)

DateTime::createFromTimestamp — Crea una instancia a partir de una marca de tiempo Unix

### Descripción

public static function DateTime::createFromTimestamp(int|float `$timestamp`): static

Crea una instancia a partir de una marca de tiempo Unix.

### Parámetros

`timestamp`
  Marca de tiempo Unix que representa la fecha. También se acepta un valor float, lo que permite una precisión de microsegundos.

### Valores devueltos

Devuelve una nueva instancia de DateTime.

### Errores/Excepciones

Si `timestamp` está fuera del rango [`PHP_INT_MIN`, `PHP_INT_MAX`], se lanza una DateRangeError.

### Ejemplos

Ejemplo #1 Ejemplo de DateTime::createFromTimestamp()

    <?php
    $date = DateTime::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u');
    ?>

El ejemplo anterior mostrará:

    1970-01-01 00:02:03.456789

# DateTime::getLastErrors

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::getLastErrors — Alias de DateTimeImmutable::getLastErrors()

### Descripción

Esta función es un alias de: DateTimeImmutable::getLastErrors()

# DateTime::modify

# date_modify

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::modify -- date_modify — Altera la marca temporal

### Descripción

Estilo orientado a objetos

public function DateTime::modify(string `$modifier`): DateTime

Estilo procedimental

function date_modify(DateTime `$object`, string `$modifier`): DateTime|false

Altera la marca temporal de un objeto DateTime aumentando o disminuyendo en un formato aceptado por DateTimeImmutable::__construct().

### Parámetros

`object`
  Solo en estilo procedimental: Un objeto DateTime retornado por la función date_create(). Esta función modifica este objeto.
`modifier`

  Una cadena de fecha/hora. Los formatos válidos son explicados en la documentación sobre los formatos de Fecha y Hora.

### Valores devueltos

Devuelve DateTime en caso de éxito. Estilo procedimental retorna `false` en caso de error.

### Errores/Excepciones

Solo en la API Orientada a Objetos: Si se pasa una cadena de Fecha/Hora inválida, se lanza DateMalformedStringException.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Ahora tiene un tipo de retorno tentativo de DateTime. Anteriormente era DateTime|false.
8.3.0 | DateTime::modify() ahora lanza DateMalformedStringException si se pasa una cadena inválida. Anteriormente, devolvía `false`, y se emitía una advertencia. date_modify() no ha cambiado.

### Ejemplos

Ejemplo #1 Ejemplo de DateTime::modify()

Estilo orientado a objetos

    <?php
    $date = new DateTime('2006-12-12');
    $date->modify('+1 day');
    echo $date->format('Y-m-d');

El ejemplo anterior mostrará:

    2006-12-13

Estilo procedimental

    <?php
    $date = date_create('2006-12-12');
    date_modify($date, '+1 day');
    echo date_format($date, 'Y-m-d');

El ejemplo anterior mostrará:

    2006-12-13

Ejemplo #2 Cuidado al añadir o sustraer meses

    <?php
    $date = new DateTime('2000-12-31');

    $date->modify('+1 month');
    echo $date->format('Y-m-d') . "\n";

    $date->modify('+1 month');
    echo $date->format('Y-m-d') . "\n";

El ejemplo anterior mostrará:

    2001-01-31
    2001-03-03

Ejemplo #3 Todos los formatos de Fecha y Hora son admitidos

    <?php
    $date = new DateTime('2020-12-31');

    $date->modify('July 1st, 2023');
    echo $date->format('Y-m-d H:i') . "\n";

    $date->modify('Monday next week');
    echo $date->format('Y-m-d H:i') . "\n";

    $date->modify('17:30');
    echo $date->format('Y-m-d H:i') . "\n";

El ejemplo anterior mostrará:

    2023-07-01 00:00
    2023-07-03 00:00
    2023-07-03 17:30

### Ver también

- strtotime() - Transforma un texto inglés en timestamp
- DateTimeImmutable::modify() - Crea un nuevo objeto con la marca de tiempo modificada
- DateTime::add() - Modifica un objeto DateTime, añadiendo una cantidad de días, meses, años, horas, minutos y segundos
- DateTime::sub() - Sustrae una cantidad de días, meses, años, horas, minutos y segundos de un objeto DateTime
- DateTime::setDate() - Establece la fecha
- DateTime::setISODate() - Establece la fecha ISO
- DateTime::setTime() - Establece la hora
- DateTime::setTimestamp() - Establece la fecha y la hora basándose en una marca temporal de Unix

# DateTime::__set_state

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::__set_state — El gestor __set_state

### Descripción

public static function DateTime::__set_state(array `$array`): DateTime

El gestor __set_state().

Igual que DateTimeImmutable::__set_state() pero funciona con DateTime.

### Parámetros

`array`

  Array de inicialización.

### Valores devueltos

Devuelve una nueva instancia de un objeto DateTime.

# DateTime::setDate

# date_date_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setDate -- date_date_set — Establece la fecha

### Descripción

Estilo orientado a objetos

public function DateTime::setDate(int `$year`, int `$month`, int `$day`): DateTime

Estilo procedimental

function date_date_set(
DateTime `$object`,
int `$year`,
int `$month`,
int `$day`
): DateTime

Reinicia la fecha actual del objeto DateTime a una fecha diferente.

Igual que DateTimeImmutable::setDate() pero funciona con DateTime, y cambia el objeto existente.

La versión procedural toma el objeto DateTime como su primer argumento.

### Parámetros

`object`
  Solo en estilo procedimental: Un objeto DateTime retornado por la función date_create(). Esta función modifica este objeto.
`year`

  Año de la fecha.

`month`

  Mes de la fecha.

`day`

  Día de la fecha.

### Valores devueltos

Retorna el objeto modificado DateTime para encadenar métodos.

### Ver también

- DateTimeImmutable::setDate() - Establece la fecha

# DateTime::setISODate

# date_isodate_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setISODate -- date_isodate_set — Establece la fecha ISO

### Descripción

Estilo orientado a objetos

public function DateTime::setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTime

Estilo procedimental

function date_isodate_set(
DateTime `$object`,
int `$year`,
int `$week`,
int `$dayOfWeek` = 1
): DateTime

Establece una fecha según el estándar ISO 8601, empleando índices de semanas y días en vez de fechas específicas.

Igual que DateTimeImmutable::setISODate() pero funciona con DateTime.

La versión procedural toma el objeto DateTime como su primer argumento.

### Parámetros

`object`
  Solo en estilo procedimental: Un objeto DateTime retornado por la función date_create(). Esta función modifica este objeto.
`year`

  Año de la fecha.

`week`

  Semana de la fecha.

`dayOfWeek`

  Desplazamiento desde el primer día de la semana.

### Valores devueltos

Retorna el objeto modificado DateTime para encadenar métodos.

### Ver también

- DateTimeImmutable::setISODate() - Establece la fecha ISO

# DateTime::setMicrosecond

(PHP 8 >= 8.4.0)

DateTime::setMicrosecond — Establece la parte de microsegundos de la hora

### Descripción

public function DateTime::setMicrosecond(int `$microsecond`): static

Establece la parte de microsegundos de la hora.

Igual que DateTimeImmutable::setMicrosecond() pero funciona con DateTime.

### Parámetros

`microsecond`
  El valor de microsegundos a establecer (de `0` a `999999`).

### Valores devueltos

Retorna el objeto modificado DateTime para encadenar métodos.

### Errores/Excepciones

Si `microsecond` está fuera del rango [`0`, `999999`], se lanza una DateRangeError.

### Ejemplos

Ejemplo #1 Ejemplo de DateTime::setMicrosecond()

    <?php
    $date = DateTime::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    $date->setMicrosecond(987654);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    ?>

El ejemplo anterior mostrará:

    1970-01-01 00:02:03.456789
    1970-01-01 00:02:03.987654

### Ver también

- DateTimeInterface::getMicrosecond() - Obtiene la parte de microsegundos de la marca de tiempo Unix

# DateTime::setTime

# date_time_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setTime -- date_time_set — Establece la hora

### Descripción

Estilo orientado a objetos

public function DateTime::setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTime

Estilo procedimental

function date_time_set(
DateTime `$object`,
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTime

Reinicia la hora actual del objeto DateTime a una hora diferente.

Igual que DateTimeImmutable::setTime() pero funciona con DateTime.

La versión procedural toma el objeto DateTime como su primer argumento.

### Parámetros

`object`
  Solo en estilo procedimental: Un objeto DateTime retornado por la función date_create(). Esta función modifica este objeto.
`hour`

  Hora del instante.

`minute`

  Minuto de la hora.

`second`

  Segundo de la hora.

`microsecond`

  Microsegundo de la hora.

### Valores devueltos

Retorna el objeto modificado DateTime para encadenar métodos.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El comportamiento con horas dobles existentes (durante la transición de DST de retroceso) cambió. Anteriormente, PHP elegiría la segunda ocurrencia (después de la transición de DST), en lugar de la primera ocurrencia (antes de la transición de DST).
7.1.0 | Se ha añadido el parametro `microsecond`.

### Ver también

- DateTimeImmutable::setTime() - Establece la hora

# DateTime::setTimestamp

# date_timestamp_set

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::setTimestamp -- date_timestamp_set — Establece la fecha y la hora basándose en una marca temporal de Unix

### Descripción

Estilo orientado a objetos

public function DateTime::setTimestamp(int `$timestamp`): DateTime

Estilo procedimental

function date_timestamp_set(DateTime `$object`, int `$timestamp`): DateTime

Establece la fecha y la hora basándose en una marca temporal de Unix (Unix timestamp).

Igual que DateTimeImmutable::setTimestamp() pero funciona con DateTime.

La versión procedural toma el objeto DateTime como su primer argumento.

### Parámetros

`object`
  Solo en estilo procedimental: Un objeto DateTime retornado por la función date_create(). Esta función modifica este objeto.
`timestamp`

  La marca temporal de Unix que representa la fecha. Establecer marcas de tiempo fuera del rango de int es posible usando DateTimeImmutable::modify() con el formato `@`.

### Valores devueltos

Retorna el objeto modificado DateTime para encadenar métodos.

### Ver también

- DateTimeImmutable::setTimestamp() - Establece la fecha y hora basadas en una marca de tiempo Unix (Unix timestamp)
- DateTime::setMicrosecond() - Establece la parte de microsegundos de la hora

# DateTime::setTimezone

# date_timezone_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setTimezone -- date_timezone_set — Establece la zona horaria para el objeto DateTime

### Descripción

Estilo orientado a objetos

public function DateTime::setTimezone(DateTimeZone `$timezone`): DateTime

Estilo procedimental

function date_timezone_set(DateTime `$object`, DateTimeZone `$timezone`): DateTime

Establece una nueva zona horaria para un object de DateTime.

Igual que DateTimeImmutable::setTimezone() pero funciona con DateTime.

La versión procedural toma el objeto DateTime como su primer argumento.

### Parámetros

`object`
  Solo en estilo procedimental: Un objeto DateTime retornado por la función date_create(). Esta función modifica este objeto.
`timezone`

  Un objeto DateTimeZone que representa la zona horaria deseada.

### Valores devueltos

Devuelve el objeto DateTime para encadenar métodos. El punto en el tiempo subyacente no cambia al llamar a este método.

### Ejemplos

Ejemplo #1 Ejemplo de DateTime::setTimeZone()

Estilo orientado a objetos

    <?php
    $date = new DateTime('2000-01-01', new DateTimeZone('Pacific/Nauru'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

    $date->setTimezone(new DateTimeZone('Pacific/Chatham'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

El ejemplo anterior mostrará:

    2000-01-01 00:00:00+12:00
    2000-01-01 01:45:00+13:45

Estilo procedimental

    <?php
    $date = date_create('2000-01-01', timezone_open('Pacific/Nauru'));
    echo date_format($date, 'Y-m-d H:i:sP') . "\n";

    date_timezone_set($date, timezone_open('Pacific/Chatham'));
    echo date_format($date, 'Y-m-d H:i:sP') . "\n";

El ejemplo anterior mostrará:

    2000-01-01 00:00:00+12:00
    2000-01-01 01:45:00+13:45

### Ver también

- DateTimeImmutable::setTimezone() - Establece la zona horaria
- DateTime::getTimezone() - Devuelve la zona horaria relativa al DateTime proporcionado
- DateTimeZone::__construct() - Crea un nuevo objeto DateTimeZone

# DateTime::sub

# date_sub

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::sub -- date_sub — Sustrae una cantidad de días, meses, años, horas, minutos y segundos de un objeto DateTime

### Descripción

Estilo orientado a objetos

public function DateTime::sub(DateInterval `$interval`): DateTime

Estilo procedimental

function date_sub(DateTime `$object`, DateInterval `$interval`): DateTime

Modifica el objeto DateTime especificado, sustrayendo el objeto DateInterval especificado.

Igual que DateTimeImmutable::sub() pero funciona con DateTime.

La versión procedural toma el objeto DateTime como su primer argumento.

### Parámetros

`object`
  Solo en estilo procedimental: Un objeto DateTime retornado por la función date_create(). Esta función modifica este objeto.
`interval`

  Un objeto DateInterval

### Valores devueltos

Retorna el objeto modificado DateTime para encadenar métodos.

### Errores/Excepciones

Solo en la API Orientada a Objetos: Si se intenta realizar una operación no soportada, como usar un objeto DateInterval que represente especificaciones de tiempo relativas como `próximo día de la semana`, se lanzará una DateInvalidOperationException.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Ahora lanza una DateInvalidOperationException con DateTime::sub(), en lugar de una advertencia cuando se intenta realizar una operación no soportada. La función date_sub() no ha cambiado.

### Ver también

- DateTimeImmutable::sub() - Sustrae una cantidad de días, meses, años, horas, minutos y segundos

## Tabla de contenidos

- DateTime::add — Modifica un objeto DateTime, añadiendo una cantidad de días, meses, años, horas, minutos y segundos
- DateTime::__construct — Devuelve un nuevo objeto DateTime
- DateTime::createFromFormat — Analiza una cadena con un instante según un formato especificado
- DateTime::createFromImmutable — Devuelve una nueva instancia de DateTime encapsulando el objeto DateTimeImmutable dado
- DateTime::createFromInterface — RDevuelve un nuevo objeto DateTime que encapsula el objeto DateTimeInterface dado
- DateTime::createFromTimestamp — Crea una instancia a partir de una marca de tiempo Unix
- DateTime::getLastErrors — Alias de DateTimeImmutable::getLastErrors
- DateTime::modify — Altera la marca temporal
- DateTime::__set_state — El gestor __set_state
- DateTime::setDate — Establece la fecha
- DateTime::setISODate — Establece la fecha ISO
- DateTime::setMicrosecond — Establece la parte de microsegundos de la hora
- DateTime::setTime — Establece la hora
- DateTime::setTimestamp — Establece la fecha y la hora basándose en una marca temporal de Unix
- DateTime::setTimezone — Establece la zona horaria para el objeto DateTime
- DateTime::sub — Sustrae una cantidad de días, meses, años, horas, minutos y segundos de un objeto DateTime

# La clase DateTimeImmutable

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introducción

Representación de fecha y hora.

Esta clase se comporta igual que DateTime con la excepción de que devuelve nuevos objetos cuando se llaman a métodos de modificación como DateTime::modify().

## Sinopsis de la Clase

class DateTimeImmutable implements DateTimeInterface {
/* Constantes heredadas */
public const string DateTimeInterface::ATOM = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::COOKIE = "l, d-M-Y H:i:s T";
public const string DateTimeInterface::ISO8601 = "Y-m-d\\TH:i:sO";
public const string DateTimeInterface::ISO8601_EXPANDED = "X-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC822 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC850 = "l, d-M-y H:i:s T";
public const string DateTimeInterface::RFC1036 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC1123 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC7231 = "D, d M Y H:i:s \\G\\M\\T";
public const string DateTimeInterface::RFC2822 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC3339 = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC3339_EXTENDED = "Y-m-d\\TH:i:s.vP";
public const string DateTimeInterface::RSS = "D, d M Y H:i:s O";
public const string DateTimeInterface::W3C = "Y-m-d\\TH:i:sP";
/* Métodos */
public function __construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)
#[\NoDiscard(message: "as DateTimeImmutable::add() does not modify the object itself")]
public function add(DateInterval `$interval`): DateTimeImmutable
public static function createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = null): DateTimeImmutable|false
public static function createFromInterface(DateTimeInterface `$object`): DateTimeImmutable
public static function createFromMutable(DateTime `$object`): static
public static function createFromTimestamp(int|float `$timestamp`): static
public static function getLastErrors(): array|false
#[\NoDiscard(message: "as DateTimeImmutable::modify() does not modify the object itself")]
public function modify(string `$modifier`): DateTimeImmutable
public static function __set_state(array `$array`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setDate() does not modify the object itself")]
public function setDate(int `$year`, int `$month`, int `$day`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setISODate() does not modify the object itself")]
public function setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setMicrosecond() does not modify the object itself")]
public function setMicrosecond(int `$microsecond`): static
#[\NoDiscard(message: "as DateTimeImmutable::setTime() does not modify the object itself")]
public function setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setTimestamp() does not modify the object itself")]
public function setTimestamp(int `$timestamp`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setTimezone() does not modify the object itself")]
public function setTimezone(DateTimeZone `$timezone`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::sub() does not modify the object itself")]
public function sub(DateInterval `$interval`): DateTimeImmutable
public function diff(DateTimeInterface `$targetObject`, bool `$absolute` = false): DateInterval
public function format(string `$format`): string
public function getMicrosecond(): int
public function getOffset(): int
public function getTimestamp(): int
public function getTimezone(): DateTimeZone|false
public function __serialize(): array
public function __unserialize(array `$data`): void
#[\Deprecated]
public function __wakeup(): void
}

## Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Las constantes de clase ahora están tipadas.
7.1.0 | El constructor de DateTimeImmutable ahora incluye los microsegundos actuales en el valor construido. Antes de esto, siempre inicializaría los microsegundos a `0`.

# DateTimeImmutable::add

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::add — Devuelve un nuevo objeto, con una cantidad añadida de días, meses, años, horas, minutos y segundos

### Descripción

#[\NoDiscard(message: "as DateTimeImmutable::add() does not modify the object itself")]
public function DateTimeImmutable::add(DateInterval `$interval`): DateTimeImmutable

Crea un nuevo objeto DateTimeImmutable, y añade el objeto DateInterval especificado para representar el nuevo valor.

### Parámetros

`interval`

  Un objeto DateInterval

### Valores devueltos

Retorna un nuevo objeto DateTimeImmutable con los datos modificados.

### Ejemplos

Ejemplo #1 Ejemplo de DateTimeImmutable::add()

Estilo orientado a objetos

    <?php
    $date = new DateTimeImmutable('2000-01-01');
    $newDate = $date->add(new DateInterval('P10D'));
    echo $newDate->format('Y-m-d') . "\n";
    ?>

Ejemplo #2 Más ejemplos de DateTimeImmutable::add()

    <?php
    $date = new DateTimeImmutable('2000-01-01');
    $newDate = $date->add(new DateInterval('PT10H30S'));
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $date = new DateTimeImmutable('2000-01-01');
    $newDate = $date->add(new DateInterval('P7Y5M4DT4H3M2S'));
    echo $newDate->format('Y-m-d H:i:s') . "\n";
    ?>

El ejemplo anterior mostrará:

    2000-01-01 10:00:30
    2007-06-05 04:03:02

Ejemplo #3 Tenga cuidado al agregar meses

    <?php
    $date = new DateTimeImmutable('2000-12-31');
    $interval = new DateInterval('P1M');

    $newDate1 = $date->add($interval);
    echo $newDate1->format('Y-m-d') . "\n";

    $newDate2 = $newDate1->add($interval);
    echo $newDate2->format('Y-m-d') . "\n";
    ?>

El ejemplo anterior mostrará:

    2001-01-31
    2001-03-03

### Ver también

- DateTimeImmutable::sub() - Sustrae una cantidad de días, meses, años, horas, minutos y segundos
- DateTimeImmutable::diff() - Devuelve la diferencia entre dos objetos DateTime
- DateTimeImmutable::modify() - Crea un nuevo objeto con la marca de tiempo modificada

# DateTimeImmutable::__construct

# date_create_immutable

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::__construct -- date_create_immutable — Devuelve un nuevo objeto DateTimeImmutable

### Descripción

Estilo orientado a objetos

public function DateTimeImmutable::__construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)

Estilo procedimental

function date_create_immutable(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

Devuelve un nuevo objeto DateTimeImmutable.

### Parámetros

`datetime`

  Una cadena de fecha/hora. Los formatos válidos son explicados en la documentación sobre los formatos de Fecha y Hora.

  Introduzca `"now"` aquí para obtener el instante actual cuando se emplee el parámetro `$timezone`.

`timezone`

  Un objeto DateTimeZone que representa la zona horaria de `$datetime`.

  Si se omite `$timezone` o es `null`, se usará la zona horaria actual.

  > Nota:

  > El parámetro `$timezone` y la zona horaria actuales se ignoran cuando el parámetro `$time` es una marca temporal de UNIX (p.ej. `@946684800`) o especifica una zona horaria (p.ej. `2010-01-28T15:00:00+02:00`, o `2010-07-05T06:00:00Z`).

### Valores devueltos

Devuelve una nueva instancia de DateTimeImmutable.

### Errores/Excepciones

Si se pasa una cadena de fecha/hora incorrecta, lanza DateMalformedStringException. Hasta PHP 8.3, lanzaba Exception.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Ahora lanza DateMalformedStringException si se pasa una cadena incorrecta, en vez de Exception.
7.1.0 | Desde ahora los microsegundos se rellenan con el valor actual. No con '00000'.

### Ejemplos

Ejemplo #1 Ejemplo de DateTimeImmutable::__construct()

Estilo orientado a objetos

    <?php
    try {
        $date = new DateTimeImmutable('2000-01-01');
    } catch (Exception $e) {
        echo $e->getMessage();
        exit(1);
    }

    echo $date->format('Y-m-d');

El ejemplo anterior mostrará:

    2000-01-01

Estilo procedimental

    <?php
    $date = date_create('2000-01-01');
    if (!$date) {
        $e = date_get_last_errors();
        foreach ($e['errors'] as $error) {
            echo "$error\n";
        }
        exit(1);
    }

    echo date_format($date, 'Y-m-d');

El ejemplo anterior mostrará:

    2000-01-01

Ejemplo #2 Complejidades de DateTimeImmutable::__construct()

    <?php
    date_default_timezone_set('America/Jamaica');

    // Especificando una fecha/hora en la zona horaria por omisión
    $date = new DateTimeImmutable('2000-01-01');
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Especificando una fecha/hora en una zona horaria específica.
    $date = new DateTimeImmutable('2000-01-01', new DateTimeZone('Pacific/Nauru'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Fecha/hora actual en la zona horaria por omisión de PHP.
    $date = new DateTimeImmutable();
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Fecha/hora actual en la zona horaria especificada.
    $date = new DateTimeImmutable('now', new DateTimeZone('Pacific/Nauru'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Usando una marca temporal de UNIX (UNIX timestamp). Observe que el resultado está en la zona horaria UTC.
    $date = new DateTimeImmutable('@946684800');
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Completado de los valores inexistentes.
    $date = new DateTimeImmutable('2000-02-30');
    echo $date->format('Y-m-d H:i:sP') . "\n";

Resultado del ejemplo anterior es similar a:

    2000-01-01 00:00:00-05:00
    2000-01-01 00:00:00+12:00
    2010-04-24 10:24:16-04:00
    2010-04-25 02:24:16+12:00
    2000-01-01 00:00:00+00:00
    2000-03-01 00:00:00-05:00

> Nota:

> Las fechas desbordadas se pueden detectar comprobando las advertencias mediante DateTimeImmutable::getLastErrors().

Ejemplo #3 Cambiando la zona horaria asociada

    <?php
    $timeZone = new \DateTimeZone('Asia/Tokyo');

    $time = new \DateTimeImmutable();
    $time = $time->setTimezone($timeZone);

    echo $time->format('Y/m/d H:i:s e'), "\n";

Resultado del ejemplo anterior es similar a:

    2022/08/12 23:49:23 Asia/Tokyo

Ejemplo #4 Usando una fecha/hora relativas

    <?php
    $time = new \DateTimeImmutable("-1 year");

    echo $time->format('Y/m/d H:i:s'), "\n";

Resultado del ejemplo anterior es similar a:

    2021/08/12 15:43:51

# DateTimeImmutable::createFromFormat

# date_create_immutable_from_format

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::createFromFormat -- date_create_immutable_from_format — Analiza un string de tiempo según el formato especificado

### Descripción

Estilo orientado a objetos

public static function DateTimeImmutable::createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

Estilo procedimental

function date_create_immutable_from_format(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

Devuelve un nuevo objeto DateTimeImmutable representando la fecha y hora especificada por el string `datetime`, que tiene el formato indicado por `format`.

### Parámetros

`format`

  El formato en el cual se ha pasado el string. Consulta las opciones de formato a continuación. En la mayoría de los casos, pueden ser usadas las mismas letras que para la función date().

  Todos los campos son inicializados con la fecha y hora actual. En el caso de que quieras restablecerlos a "cero" (Unix epoch, `01/01/1970 00:00:00 UTC`). Puedes hacerlo incluyendo el carácter `!` al principio de `format`, o `|` al final. Por favor, consulta la documentación de cada carácter a continuación para más información.

  El formato es analizado de izquierda a derecha, lo que significa que en algunas situaciones el orden en el que los caracteres de formato están escritos afecta al resultado. En el caso de `z` (el día del año), es necesario que un año ya se haya analizado, por ejemplo mediante los caracteres `Y` o `y`.

  Las letras de formato que se usan para analizar números permiten un amplio rango de valores, fuera de lo que sería el rango lógico. Por ejemplo, el `d` (día del mes) acepta valores en el rango de `00` a `99`. La única restricción es en la cantidad de dígitos. El mecanismo de desbordamiento del analizador de fecha/hora se usa cuando se dan valores fuera de rango. Los ejemplos a continuación muestran algo de este comportamiento.

  Esto también significa que los datos analizados para una letra de formato son golosos, y leerán toda la cantidad de dígitos que su formato permite. Esto también puede significar que no hay suficientes caracteres en `datetime` para las letras de formato sucesivas. Un ejemplo en esta página también ilustra este problema.

  Los siguientes caracteres son reconocidos en la cadena del parámetro `format`
  Carácter `format` | Descripción | Ejemplo de valores analizables
  --- | --- | ---
  Día | --- | ---
  `d` y `j` | Día del mes, 2 dígitos con o sin ceros iniciales | `01` a `31` o `1` a `31`. (Se aceptan 2 dígitos numericos mayores que los días del mes, en cuyo caso harán que el mes se desborde. Por ejemplo usando 33 con enero, significará 2 de febrero)
  `D` y `l` | Nombre del día de la semana como texto, en inglés | `Mon` hasta `Sun` o `Sunday` hasta `Saturday`. Si el nombre del día indicado es diferente al nombre del día que pertenece la fecha analizada (o predeterminada) es diferente, entonces se produce un desbordamiento a la siguiente fecha con el nombre de indicado. Vea los ejemplos a continuación para obtener una explicación.
  `S` | Sufijo ordinal en inglés para el día del mes, 2 caracteres. Se ignora durante el procesamiento. | `st`, `nd`, `rd` o `th`.
  `z` | Día del año (comenzando en 0); debe estar precedido por `Y` o `y`. | `0` hasta `365`. (son aceptados 3 dígitos numéricos mayores que 365, en cuyo caso harán que el año se desborde. Por ejemplo usando 366 con 2022, significa 2 de enero de 2023)
  Mes | --- | ---
  `F` y `M` | Nombre del mes, en inglés, como January o Sept | `January` hasta `December` o `Jan` hasta `Dec`
  `m` y `n` | Representación numerica del mes, 2 dígitos con o sin ceros iniciales | `01` hasta `12` o `1` hasta `12`. (son aceptados 2 dígitos numéricos mayores que 12, en cuyo caso harán que el año se desborde. Por ejemplo usando 13 significa enero del siguiente año)
  Año | --- | ---
  `X` y `x` | Una representación completa del año, hasta 19 dígitos, opcionalmente con el prefijo `+` o `-` | Ejemplos: `0055`, `787`, `1999`, `-2003`, `+10191`
  `Y` | Una representación completa del año, hasta 4 dígitos | Ejemplos: `25` (igual que `0025`), `787`, `1999`, `2003`
  `y` | Una representación de dos dígitos de un año (que se asume que está en el rango 1970-2069, inclusive) | Ejemplos: `99` o `03` (que se interpretarán como `1999` y `2003`, respectivamente)
  Hora | --- | ---
  `a` y `A` | Ante meridiem y post meridiem | `am` or `pm`
  `g` y `h` | Hora en formato 12 horas, 2 dígitos con o sin ceros iniciales | `1` hasta `12` o `01` hasta `12` (son aceptados 2 dígitos numéricos mayores que 12, en cuyo caso harán que el día se desborde. Por ejemplo usando `14` significa `02` en el siguiente periodo AM/PM)
  `G` y `H` | Hora en formato 24 horas, 2 dígitos con o sin ceros iniciales | `0` hasta `23` o `00` hasta `23` (son aceptados 2 dígitos numéricos mayores que 24, en cuyo caso harán que el día se desborde. Por ejemplo usando `26` significa `02:00` en el siguiente día)
  `i` | Minutos, con ceros iniciales | `00` a `59`. (son aceptados 2 dígitos numéricos mayores que 59, en cuyo caso harán que la hora se desborde. Por ejemplo usando `66` significa `06` en la siguiente hora)
  `s` | Segundos, con ceros iniciales | `00` hastah `59` (son aceptados 2 dígitos numéricos mayores que 59, en cuyo caso harán que el minuto se desborde. Por ejemplo usando `90` significa `30` en el siguiente minuto)
  `v` | Fracción en milisengundos (hasta 3 digitos) | Ejemplos: `12` (`0.12` segundos), `345` (`0.345` segundos)
  `u` | Fracción en microsengundos (hasta 6 dígitos) | Ejemplos: `45` (`0.45` segundos), `654321` (`0.654321` segundos)
  Zona horaria | --- | ---
  `e`, `O`, `p`, `P` y `T` | Identificador de zona horaria, o diferencia a UTC en horas, o diferencia a UTC con dos puntos entre horas y minutos, o abreviatura de zona horaria | Ejemplos: `UTC`, `GMT`, `Atlantic/Azores` o `+0200` o `+02:00` o `EST`, `MDT`
  Fecha y hora completa | --- | ---
  `U` | Segundos desde Unix Epoch (1 de enero de 1970 00:00:00 GMT) | Ejemplo: `1292177455`
  Espacios en blanco y separadores | --- | ---
  `` (espacio) | Cero o más espacios, tabuladores, NBSP (U+A0) o NNBSP (U+202F) | Ejemplos: `"\t"` o `" "`
  `#` | Uno de los siguientes símbolos de separación: `;`, `:`, `/`, `.`, `,`, `-`, `(` o `)` | Ejemplo: `/`
  `;`, `:`, `/`, `.`, `,`, `-`, `(` o `)` | El carácter especificado | Ejemplo: `-`
  `?` | Un byte aleatorio | Ejemplo: `^` (Tenga en cuenta que los caracteres UTF-8 es posible que necesite más de uno `?`. En este caso, usar `*` es probablemente lo que desea en su lugar)
  `*` | Bytes aleatorios hasta el siguiente separador o dígito | Ejemplo: `*` en `Y-*-d` con la cadena `2009-aWord-08` coincidirá con `aWord`
  `!` | Restablece todos los campos (año, mes, día, hora, minuto, segundo, fracción e información de zona horaria) a valores similares a cero (`0` para hora, minuto, segundo y fracción, `1` para mes y día, `1970` para año y la zona horaria predeterminada) | Sin `!`, todos los campos se establecerán a la fecha y hora actual.
  `|` | Restablece todos los campos (año, mes, día, hora, minuto, segundo, fracción e información de zona horaria) a valores similares a cero si no han sido analizados todavía. | `Y-m-d|` establecerá el año, mes y día a la información encontrada en la cadena a analizar, y establecerá la hora, minuto y segundo a `0`.
  `+` | Si este especificador de formato está presente, los datos adicionales en la cadena no causarán un error, sino una advertencia en su lugar | Usa DateTimeImmutable::getLastErrors() para averiguar si había datos adicionales.

  Los caracteres no reconocidos en el string de formato causarán que el análisis falle y un mensaje de error se añadirá a la estructura devuelta. Puedes consultar los mensajes de error con DateTimeImmutable::getLastErrors().

  Para incluir caracteres literales en `format`, debes escaparlos con una barra invertida (`\`).

  Si `format` no contiene el carácter `!`, entonces las partes de la fecha/hora que no están especificadas en `format` se establecerán a la fecha actual del sistema.

  Si `format` contiene el carácter `!`, entonces las partes de la fecha/hora generadas que no están especificadas en `format`, así como los valores a la izquierda del `!`, se establecerán a los valores correspondientes de Unix epoch.

  Si cualquier carácter de tiempo es analizado, entonces todos los demás campos relacionados con el tiempo se establecerán a "0", a menos que también se analicen.

  Unix epoch es 01/01/1970 00:00:00 UTC.

`datetime`

  String representando la fecha y hora.

`timezone`

  Una instancia de DateTimeZone representando la zona horaria deseada.

  Si se omite `timezone` o pasado `null` y `datetime` no contiene zona horaria, se usará la zona horaria actual.

  > Nota:

  > El parámetro `timezone` y la zona horaria actual son ignorados cuando el parámetro `datetime` contiene un timestamp UNIX (por ejemplo, `946684800`) o especifica una zona horaria (por ejemplo, `2010-01-28T15:00:00+02:00`).

### Valores devueltos

Devuelve una nueva instancia de DateTimeImmutable o `false` si ocurre un error.

### Errores/Excepciones

Este método lanza ValueError cuando `datetime` contiene bytes nulos.

### Historial de cambios

Versión | Descripción
--- | ---
8.2.9 | El especificador `` (espacio) ahora también soporta los caracteres NBSP (U+A0) y NNBSP (U+202F).
8.2.0 | Se ha añadido los especificadores de `format` `X` y `x`.
8.0.21, 8.1.8, 8.2.0 | Ahora se lanza ValueError cuando se pasan bytes nulos a `datetime`, lo que anteriormente se ignoraba silenciosamente.
7.3.0 | Se ha añadido el especificador de `format` `v`.

### Ejemplos

Ejemplo #1 Ejemplo de DateTimeImmutable::createFromFormat()

Estilo orientado a objetos

    <?php
    $date = DateTimeImmutable::createFromFormat('j-M-Y', '15-Feb-2009');
    echo $date->format('Y-m-d');

Ejemplo #2 Usando constantes predefinidas con DateTimeImmutable::createFromFormat()

Estilo orientado a objetos

    <?php
    $date = DateTimeImmutable::createFromFormat(
        DateTimeInterface::ISO8601,
        '2004-02-12T15:19:21+00:00'
    );
    echo $date->format('c e') . "\n";

    $date = DateTimeImmutable::createFromFormat(
        DateTimeInterface::RFC3339_EXTENDED,
        '2013-10-14T09:00:00.000+02:00'
    );
    echo $date->format('c e') . "\n";

Las constantes de formato usadas en este ejemplo consisten en una cadena de caracteres para formatear un objeto DateTimeImmutable. En la mayoría de los casos, estas letras coinciden con los mismos elementos de información de fecha/hora que los definidos en los parámetros de la sección anterior, pero tienden a ser más permisivos.

Ejemplo #3 Complejidades de DateTimeImmutable::createFromFormat()

    <?php
    echo 'Hora actual: ' . date('Y-m-d H:i:s') . "\n";

    $format = 'Y-m-d';
    $date = DateTimeImmutable::createFromFormat($format, '2009-02-15');
    echo "Formato: $format; " . $date->format('Y-m-d H:i:s') . "\n";

    $format = 'Y-m-d H:i:s';
    $date = DateTimeImmutable::createFromFormat($format, '2009-02-15 15:16:17');
    echo "Formato: $format; " . $date->format('Y-m-d H:i:s') . "\n";

    $format = 'Y-m-!d H:i:s';
    $date = DateTimeImmutable::createFromFormat($format, '2009-02-15 15:16:17');
    echo "Formato: $format; " . $date->format('Y-m-d H:i:s') . "\n";

    $format = '!d';
    $date = DateTimeImmutable::createFromFormat($format, '15');
    echo "Formato: $format; " . $date->format('Y-m-d H:i:s') . "\n";

    $format = 'i';
    $date = DateTimeImmutable::createFromFormat($format, '15');
    echo "Formato: $format; " . $date->format('Y-m-d H:i:s') . "\n";

Resultado del ejemplo anterior es similar a:

    Hora actual: 2022-06-02 15:50:46
    Formato: Y-m-d; 2009-02-15 15:50:46
    Formato: Y-m-d H:i:s; 2009-02-15 15:16:17
    Formato: Y-m-!d H:i:s; 1970-01-15 15:16:17
    Formato: !d; 1970-01-15 00:00:00
    Formato: i; 2022-06-02 00:15:00

Ejemplo #4 Cadenas de formato con caracteres literales

    <?php
    echo DateTimeImmutable::createFromFormat('H\h i\m s\s','23h 15m 03s')->format('H:i:s');

Resultado del ejemplo anterior es similar a:

    23:15:03

Ejemplo #5 Comportamiento de desbordamiento

    <?php
    echo DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2021-17-35 16:60:97')->format(DateTimeImmutable::RFC2822);

Resultado del ejemplo anterior es similar a:

    Sat, 04 Jun 2022 17:01:37 +0000

Aunque el resultado parece extraño, es correcto, ya que ocurren los siguientes desbordamientos:

1. `97` segundos se desbordan a `1` minuto, dejando `37` segundos.
2. `61` minutos se desbordan a `1` hora, dejando `1` minuto.
3. `35` días se debordan a `1` mes, dejando `4` días. La cantidad de días que quedan depende del mes, ya que no todos los meses tienen la misma cantidad de días.
4. `18` meses se desbordan a `1` año, dejando `6` meses.

Ejemplo #6 Comportamiento de desbordamiento de nombres de días de la semana

    <?php
    $d = DateTime::createFromFormat(DateTimeInterface::RFC1123, 'Mon, 3 Aug 2020 25:00:00 +0000');
    echo $d->format(DateTime::RFC1123), "\n";

Resultado del ejemplo anterior es similar a:

    Mon, 10 Aug 2020 01:00:00 +0000

Aunque el resultado parece extraño, es correcto, ya que ocurren los siguientes desbordamientos:

1. `3 Aug 2020 25:00:00` se desborda a `(Tue) 4 Aug 2020 01:00`.
2. Se aplica `Mon`, el cual avanza la fecha a `Mon, 10 Aug 2020 01:00:00`. La explicación de palabras clave relativas como `Mon` se explica en la sección de formatos relativos.

Para detectar desbordamientos en fechas, puedes usar DateTimeImmutable::getLastErrors(), el cual incluirá una advertencia si ocurrió un desbordamiento.

Ejemplo #7 Detección de fechas desbordadas

    <?php
    $d = DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2021-17-35 16:60:97');
    echo $d->format(DateTimeImmutable::RFC2822), "\n\n";

    var_dump(DateTimeImmutable::getLastErrors());

Resultado del ejemplo anterior es similar a:

    Sat, 04 Jun 2022 17:01:37 +0000

    array(4) {
      'warning_count' =>
      int(2)
      'warnings' =>
      array(1) {
        [19] =>
        string(27) "The parsed date was invalid"
      }
      'error_count' =>
      int(0)
      'errors' =>
      array(0) {
      }
    }

Ejemplo #8 Comportamiento de análisis goloso

    <?php
    print_r(date_parse_from_format('Gis', '60101'));

Resultado del ejemplo anterior es similar a:

    Array
    (
        [year] =>
        [month] =>
        [day] =>
        [hour] => 60
        [minute] => 10
        [second] => 0
        [fraction] => 0
        [warning_count] => 1
        [warnings] => Array
            (
                [5] => The parsed time was invalid
            )

        [error_count] => 1
        [errors] => Array
            (
                [4] => A two digit second could not be found
            )

        [is_localtime] =>
    )

El formato `G` es para analizar horas en formato de 24 horas, con o sin cero inicial. Esto requiere analizar 1 o 2 dígitos. Debido a que hay dos dígitos siguientes, lo lee ávidamente como `60`.

Los siguientes caracteres de formato `i` y `s` requieren ambos dos dígitos. Esto significa que se pasa `10` como minutos (`i`), y que luego no quedan suficientes dígitos para analizar como segundos (`s`).

El array `errors` indica este problema.

Adicionalmente, una hora de `60` está fuera del rango `0`-`24`, lo que hace que el array `warnings` incluya una advertencia de que la hora es incorrecta.

### Ver también

- DateTimeImmutable::__construct() - Devuelve un nuevo objeto DateTimeImmutable
- DateTimeImmutable::getLastErrors() - Devuelve las advertencias y errores
- checkdate() - Valida una fecha gregoriana
- strptime() - Analiza una fecha/hora generada con strftime

# DateTimeImmutable::createFromInterface

(PHP 8)

DateTimeImmutable::createFromInterface — Devuelve un nuevo objeto DateTimeImmutable que encapsula el objeto DateTimeInterface dado

### Descripción

public static function DateTimeImmutable::createFromInterface(DateTimeInterface `$object`): DateTimeImmutable

### Parámetros

`object`

  El objeto DateTimeInterface que necesita ser convertido en una versión immutable. Este objeto no se modifica, sino que en su lugar se crea un nuevo objeto DateTimeImmutable que contiene la misma información de fecha, hora y zona horaria.

### Valores devueltos

Devuelve una nueva instancia de DateTimeImmutable.

### Ejemplos

Ejemplo #1 Creando un objeto fecha y hora inmutable

    <?php
    $date = new DateTime("2014-06-20 11:45 Europe/London");
    $immutable = DateTimeImmutable::createFromInterface($date);

    $date = new DateTimeImmutable("2014-06-20 11:45 Europe/London");
    $also_immutable = DateTimeImmutable::createFromInterface($date);

# DateTimeImmutable::createFromMutable

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

DateTimeImmutable::createFromMutable — Devuelve un nuevo objeto DateTimeImmutable que encapsula el objeto DateTime dado

### Descripción

public static function DateTimeImmutable::createFromMutable(DateTime `$object`): static

### Parámetros

`object`

  El objeto DateTime mutable para convertirlo en una versión immutable. Este objeto no se modifica, sino que en su lugar se crea un nuevo objeto DateTimeImmutable que contiene la misma información de fecha, hora y zona horaria.

### Valores devueltos

Devuelve una nueva instancia de DateTimeImmutable.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | El método ahora devuelve una instancia de la clase actualmente invocada. Anteriormente, creaba una nueva instancia de DateTimeImmutable.

### Ejemplos

Ejemplo #1 Creando un objeto de fecha y hora inmutable

    <?php
    $date = new DateTime("2014-06-20 11:45 Europe/London");
    $immutable = DateTimeImmutable::createFromMutable( $date );

# DateTimeImmutable::createFromTimestamp

(PHP 8 >= 8.4.0)

DateTimeImmutable::createFromTimestamp — Crea una instancia a partir de una marca de tiempo Unix

### Descripción

public static function DateTimeImmutable::createFromTimestamp(int|float `$timestamp`): static

Crea una instancia a partir de una marca de tiempo Unix.

### Parámetros

`timestamp`
  Marca de tiempo Unix que representa la fecha. También se acepta un valor float, lo que permite una precisión de microsegundos.

### Valores devueltos

Devuelve una nueva instancia de DateTimeImmutable.

### Errores/Excepciones

Si `timestamp` está fuera del rango [`PHP_INT_MIN`, `PHP_INT_MAX`], se lanza una DateRangeError.

### Ejemplos

Ejemplo #1 Ejemplo de DateTimeImmutable::createFromTimestamp()

    <?php
    $date = DateTimeImmutable::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u');
    ?>

El ejemplo anterior mostrará:

    1970-01-01 00:02:03.456789

# DateTimeImmutable::getLastErrors

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::getLastErrors — Devuelve las advertencias y errores

### Descripción

public static function DateTimeImmutable::getLastErrors(): array|false

Devuelve un array de advertencias y errores encontrados mientras se analizaba una cadena de fecha/hora.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array que contiene información sobre advertencias y errores, o `false` si no hay ni advertencias ni errores.

### Historial de cambios

Versión | Descripción
--- | ---
8.2.0 | Antes de PHP 8.2.0, esta función no devolvía `false` cuando no había advertencias ni errores. En su lugar, siempre devolvía la estructura de array documentada.

### Ejemplos

Ejemplo #1 DateTimeImmutable::getLastErrors() example

    <?php
    try {
        $date = new DateTimeImmutable('asdfasdf');
    } catch (Exception $e) {
        // Solo para fines de demostración...
        print_r(DateTimeImmutable::getLastErrors());

        // La forma correcta de hacer esto con programación orientada a objetos es
        echo $e->getMessage();
    }
    ?>

El ejemplo anterior mostrará:

    Array
    (
        [warning_count] => 1
        [warnings] => Array
            (
                [6] => Double timezone specification
            )

        [error_count] => 1
        [errors] => Array
            (
                [0] => The timezone could not be found in the database
            )
    )
    Failed to parse time string (asdfasdf) at position 0 (a): The timezone could not be found in the database

Los índices 6, y 0 en la salida de ejemplo se refieren al índice de caracteres en la cadena donde ocurrió el error.

Ejemplo #2 Detectando fechas desbordadas

    <?php
    $date = DateTimeImmutable::createFromFormat('!Y-m-d', '2020-02-30');
    print_r(DateTimeImmutable::getLastErrors());

El ejemplo anterior mostrará:

    Array
    (
        [warning_count] => 1
        [warnings] => Array
            (
                [10] => The parsed date was invalid
            )

        [error_count] => 0
        [errors] => Array
            (
            )
    )

# DateTimeImmutable::modify

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::modify — Crea un nuevo objeto con la marca de tiempo modificada

### Descripción

#[\NoDiscard(message: "as DateTimeImmutable::modify() does not modify the object itself")]
public function DateTimeImmutable::modify(string `$modifier`): DateTimeImmutable

Crea un nuevo objeto DateTimeImmutable con la marca de tiempo modificada. El objeto original no se modifica.

### Parámetros

`modifier`

  Una cadena de fecha/hora. Los formatos válidos son explicados en la documentación sobre los formatos de Fecha y Hora.

### Valores devueltos

Devuelve DateTimeImmutable en caso de éxito. Estilo procedimental retorna `false` en caso de error.

### Errores/Excepciones

Si se pasa una cadena de Fecha/Hora no válida, se lanza DateMalformedStringException. Antes de PHP 8.3, esto emitía una advertencia.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Ahora tiene un tipo de retorno tentativo de DateTimeImmutable. Anteriormente era DateTimeImmutable|false.
8.3.0 | DateTimeImmutable::modify() ahora lanzará DateMalformedStringException si es pasada una cadena no válida. Anteriormente, devolvía `false`, y se emitía una advertencia.

### Ejemplos

Ejemplo #1 Ejemplo de DateTimeImmutable::modify()

Estilo orientado a objetos

    <?php
    $date = new DateTimeImmutable('2006-12-12');
    $newDate = $date->modify('+1 day');
    echo $newDate->format('Y-m-d');

El ejemplo anterior mostrará:

    2006-12-13

Ejemplo #2 Tenga cuidado al añadir o restar meses

    <?php
    $date = new DateTimeImmutable('2000-12-31');

    $newDate1 = $date->modify('+1 month');
    echo $newDate1->format('Y-m-d') . "\n";

    $newDate2 = $newDate1->modify('+1 month');
    echo $newDate2->format('Y-m-d') . "\n";

El ejemplo anterior mostrará:

    2001-01-31
    2001-03-03

### Ver también

- DateTimeImmutable::add() - Devuelve un nuevo objeto, con una cantidad añadida de días, meses, años, horas, minutos y segundos
- DateTimeImmutable::sub() - Sustrae una cantidad de días, meses, años, horas, minutos y segundos
- DateTimeImmutable::setDate() - Establece la fecha
- DateTimeImmutable::setISODate() - Establece la fecha ISO
- DateTimeImmutable::setTime() - Establece la hora
- DateTimeImmutable::setTimestamp() - Establece la fecha y hora basadas en una marca de tiempo Unix (Unix timestamp)

# DateTimeImmutable::__set_state

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::__set_state — El gestor __set_state

### Descripción

public static function DateTimeImmutable::__set_state(array `$array`): DateTimeImmutable

El gestor __set_state().

### Parámetros

`array`

  Array de inicialización.

### Valores devueltos

Devuelve una nueva instancia de un objeto DateTimeImmutable.

# DateTimeImmutable::setDate

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setDate — Establece la fecha

### Descripción

#[\NoDiscard(message: "as DateTimeImmutable::setDate() does not modify the object itself")]
public function DateTimeImmutable::setDate(int `$year`, int `$month`, int `$day`): DateTimeImmutable

Devuelve un nuevo objeto DateTimeImmutable con la fecha actual del objeto DateTimeImmutable establecida a la fecha dada.

### Parámetros

`object`
  Solo en estilo procedimental: Un objeto DateTime retornado por la función date_create(). Esta función modifica este objeto.
`year`

  Año de la fecha.

`month`

  Mes de la fecha.

`day`

  Día de la fecha.

### Valores devueltos

Retorna un nuevo objeto DateTimeImmutable con los datos modificados.

### Ejemplos

Ejemplo #1 Ejemplo de DateTimeImmutable::setDate()

Estilo orientado a objetos

    <?php
    $date = new DateTimeImmutable();
    $newDate = $date->setDate(2001, 2, 3);
    echo $newDate->format('Y-m-d');

El ejemplo anterior mostrará:

    2001-02-03

Ejemplo #2 Valores que exceden los rangos se añaden a sus valores padres

    <?php
    $date = new DateTimeImmutable();

    $newDate = $date->setDate(2001, 2, 28);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setDate(2001, 2, 29);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setDate(2001, 14, 3);
    echo $newDate->format('Y-m-d') . "\n";

El ejemplo anterior mostrará:

    2001-02-28
    2001-03-01
    2002-02-03

### Ver también

- DateTimeImmutable::setISODate() - Establece la fecha ISO
- DateTimeImmutable::setTime() - Establece la hora

# DateTimeImmutable::setISODate

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setISODate — Establece la fecha ISO

### Descripción

#[\NoDiscard(message: "as DateTimeImmutable::setISODate() does not modify the object itself")]
public function DateTimeImmutable::setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTimeImmutable

Devuelve un nuevo objeto DateTimeImmutable con la fecha establecida de acuerdo al estándar ISO 8601 - usando semanas y desplazamientos de días en lugar de fechas específicas.

### Parámetros

`year`

  Año de la fecha.

`week`

  Semana de la fecha.

`dayOfWeek`

  Desplazamiento desde el primer día de la semana.

### Valores devueltos

Retorna un nuevo objeto DateTimeImmutable con los datos modificados.

### Ejemplos

Ejemplo #1 Ejemplo de DateTimeImmutable::setISODate()

Estilo orientado a objetos

    <?php
    $date = new DateTimeImmutable();

    $newDate = $date->setISODate(2008, 2);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setISODate(2008, 2, 7);
    echo $newDate->format('Y-m-d') . "\n";

El ejemplo anterior mostrará:

    2008-01-07
    2008-01-13

Estilo procedimental

    <?php

    $date = date_create();

    date_isodate_set($date, 2008, 2);
    echo date_format($date, 'Y-m-d') . "\n";

    date_isodate_set($date, 2008, 2, 7);
    echo date_format($date, 'Y-m-d') . "\n";

El ejemplo anterior mostrará:

    2008-01-07
    2008-01-13

Ejemplo #2 Valores que exceden los rangos se añaden a sus valores padres

    <?php

    $date = new DateTimeImmutable();

    $newDate = $date->setISODate(2008, 2, 7);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setISODate(2008, 2, 8);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setISODate(2008, 53, 7);
    echo $newDate->format('Y-m-d') . "\n";

El ejemplo anterior mostrará:

    2008-01-13
    2008-01-14
    2009-01-04

Ejemplo #3 Buscando el mes en el que se encuentra una semana

    <?php

    $date = new DateTimeImmutable();
    $newDate = $date->setISODate(2008, 14);
    echo $newDate->format('n');

El ejemplo anterior mostrará:

    3

### Ver también

- DateTimeImmutable::setDate() - Establece la fecha
- DateTimeImmutable::setTime() - Establece la hora

# DateTimeImmutable::setMicrosecond

(PHP 8 >= 8.4.0)

DateTimeImmutable::setMicrosecond — Establece la parte de microsegundos de la hora

### Descripción

#[\NoDiscard(message: "as DateTimeImmutable::setMicrosecond() does not modify the object itself")]
public function DateTimeImmutable::setMicrosecond(int `$microsecond`): static

Devuelve un nuevo objeto DateTimeImmutable construido a partir del antiguo, con la parte de microsegundos modificada.

### Parámetros

`microsecond`
  El valor de microsegundos a establecer (de `0` a `999999`).

### Valores devueltos

Retorna un nuevo objeto DateTimeImmutable con los datos modificados.

### Errores/Excepciones

Si `microsecond` está fuera del rango [`0`, `999999`], se lanza una DateRangeError.

### Ejemplos

Ejemplo #1 Ejemplo de DateTimeImmutable::setMicrosecond()

    <?php
    $date = DateTimeImmutable::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    $date = $date->setMicrosecond(987654);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    ?>

El ejemplo anterior mostrará:

    1970-01-01 00:02:03.456789
    1970-01-01 00:02:03.987654

### Ver también

- DateTimeInterface::getMicrosecond() - Obtiene la parte de microsegundos de la marca de tiempo Unix

# DateTimeImmutable::setTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTime — Establece la hora

### Descripción

#[\NoDiscard(message: "as DateTimeImmutable::setTime() does not modify the object itself")]
public function DateTimeImmutable::setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTimeImmutable

Devuelve un nuevo objeto DateTimeImmutable con la hora establecida a la hora dada.

### Parámetros

`hour`

  Hora de la hora.

`minute`

  Minuto de la hora.

`second`

  Segundo de la hora.

`microsecond`

  Microsegundo de la hora.

### Valores devueltos

Retorna un nuevo objeto DateTimeImmutable con los datos modificados.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El comportamiento con horas dobles existentes (durante la transición de DST de retroceso) cambió. Anteriormente, PHP elegiría la segunda ocurrencia (después de la transición de DST), en lugar de la primera ocurrencia (antes de la transición de DST).
7.1.0 | Se ha añadido el parametro `microsecond`.

### Ejemplos

Ejemplo #1 Ejemplo de DateTimeImmutable::setTime()

Estilo orientado a objetos

    <?php
    $date = new DateTimeImmutable('2001-01-01');

    $newDate = $date->setTime(14, 55);
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $newDate = $date->setTime(14, 55, 24);
    echo $newDate->format('Y-m-d H:i:s') . "\n";
    ?>

Resultado del ejemplo anterior es similar a:

    2001-01-01 14:55:00
    2001-01-01 14:55:24

Ejemplo #2 Valores que exceden los rangos se añaden a sus valores padres

    <?php
    $date = new DateTimeImmutable('2001-01-01');

    $newDate = $date->setTime(14, 55, 24);
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $newDate = $date->setTime(14, 55, 65);
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $newDate = $date->setTime(14, 65, 24);
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $newDate = $date->setTime(25, 55, 24);
    echo $newDate->format('Y-m-d H:i:s') . "\n";
    ?>

El ejemplo anterior mostrará:

    2001-01-01 14:55:24
    2001-01-01 14:56:05
    2001-01-01 15:05:24
    2001-01-02 01:55:24

### Ver también

- DateTimeImmutable::setDate() - Establece la fecha
- DateTimeImmutable::setISODate() - Establece la fecha ISO

# DateTimeImmutable::setTimestamp

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTimestamp — Establece la fecha y hora basadas en una marca de tiempo Unix (Unix timestamp)

### Descripción

#[\NoDiscard(message: "as DateTimeImmutable::setTimestamp() does not modify the object itself")]
public function DateTimeImmutable::setTimestamp(int `$timestamp`): DateTimeImmutable

Devuelve un nuevo objeto DateTimeImmutable construido a partir del antiguo, con la fecha y hora establecidas basadas en una marca de tiempo Unix.

### Parámetros

`timestamp`

  Una marca de tiempo Unix representando la fecha. Establecer marcas de tiempo fuera del rango de int es posible usando DateTimeImmutable::modify() con el formato `@`.

### Valores devueltos

Retorna un nuevo objeto DateTimeImmutable con los datos modificados.

### Ejemplos

Ejemplo #1 Ejemplo de DateTimeImmutable::setTimestamp()

Estilo orientado a objetos

    <?php
    $date = new DateTimeImmutable();
    echo $date->format('U = Y-m-d H:i:s') . "\n";

    $newDate = $date->setTimestamp(1171502725);
    echo $newDate->format('U = Y-m-d H:i:s') . "\n";

Resultado del ejemplo anterior es similar a:

    1272508903 = 2010-04-28 22:41:43
    1171502725 = 2007-02-14 20:25:25

### Ver también

- DateTimeImmutable::getTimestamp() - Obtiene el timestamp Unix
- DateTimeImmutable::setMicrosecond() - Establece la parte de microsegundos de la hora

# DateTimeImmutable::setTimezone

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTimezone — Establece la zona horaria

### Descripción

#[\NoDiscard(message: "as DateTimeImmutable::setTimezone() does not modify the object itself")]
public function DateTimeImmutable::setTimezone(DateTimeZone `$timezone`): DateTimeImmutable

Devuelve un nuevo objeto DateTimeImmutable con una nueva zona horaria establecida.

### Parámetros

`timezone`

  Un objeto DateTimeZone que representa la zona horaria deseada.

### Valores devueltos

Devuelve un nuevo objeto DateTimeImmutable modificado para encadenar métodos. El instante subyacente no se modifica al llamar a este método.

### Ejemplos

Ejemplo #1 Ejemplo de DateTimeImmutable::setTimeZone()

Estilo orientado a objetos

    <?php
    $date = new DateTimeImmutable('2000-01-01', new DateTimeZone('Pacific/Nauru'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

    $newDate = $date->setTimezone(new DateTimeZone('Pacific/Chatham'));
    echo $newDate->format('Y-m-d H:i:sP') . "\n";
    ?>

El ejemplo anterior mostrará:

    2000-01-01 00:00:00+12:00
    2000-01-01 01:45:00+13:45

### Ver también

- DateTimeImmutable::getTimezone() - Devuelve la zona horaria relativa al DateTime proporcionado
- DateTimeZone::__construct() - Crea un nuevo objeto DateTimeZone

# DateTimeImmutable::sub

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::sub — Sustrae una cantidad de días, meses, años, horas, minutos y segundos

### Descripción

#[\NoDiscard(message: "as DateTimeImmutable::sub() does not modify the object itself")]
public function DateTimeImmutable::sub(DateInterval `$interval`): DateTimeImmutable

Devuelve un nuevo objeto DateTimeImmutable, con el objeto DateInterval especificado sustraído del objeto DateTimeImmutable especificado.

### Parámetros

`interval`

  Un objeto DateInterval

### Valores devueltos

Retorna un nuevo objeto DateTimeImmutable con los datos modificados.

### Errores/Excepciones

Si se intenta realizar una operación no soportada, como usar un objeto DateInterval que represente especificaciones de tiempo relativas como `próximo día de la semana`, se lanzará una DateInvalidOperationException.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Ahora lanza una DateInvalidOperationException en lugar de una advertencia cuando se intenta realizar una operación no soportada.

### Ejemplos

Ejemplo #1 Ejemplo de DateTimeImmutable::sub()

Estilo orientado a objetos

    <?php
    $date = new DateTimeImmutable('2000-01-20');
    $newDate = $date->sub(new DateInterval('P10D'));
    echo $newDate->format('Y-m-d') . "\n";
    ?>

El ejemplo anterior mostrará:

    2000-01-10

Ejemplo #2 Más ejemplos de DateTimeImmutable::sub()

    <?php
    $date = new DateTimeImmutable('2000-01-20');
    $newDate = $date->sub(new DateInterval('PT10H30S'));
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $date = new DateTimeImmutable('2000-01-20');
    $newDate = $date->sub(new DateInterval('P7Y5M4DT4H3M2S'));
    echo $newDate->format('Y-m-d H:i:s') . "\n";
    ?>

El ejemplo anterior mostrará:

    2000-01-19 13:59:30
    1992-08-15 19:56:58

Ejemplo #3 Tenga cuidado al substraer meses

    <?php
    $date = new DateTimeImmutable('2001-04-30');
    $interval = new DateInterval('P1M');

    $newDate1 = $date->sub($interval);
    echo $newDate1->format('Y-m-d') . "\n";

    $newDate2 = $newDate1->sub($interval);
    echo $newDate2->format('Y-m-d') . "\n";
    ?>

El ejemplo anterior mostrará:

    2001-03-30
    2001-03-02

### Ver también

- DateTimeImmutable::add() - Devuelve un nuevo objeto, con una cantidad añadida de días, meses, años, horas, minutos y segundos
- DateTimeImmutable::diff() - Devuelve la diferencia entre dos objetos DateTime
- DateTimeImmutable::modify() - Crea un nuevo objeto con la marca de tiempo modificada

## Tabla de contenidos

- DateTimeImmutable::add — Devuelve un nuevo objeto, con una cantidad añadida de días, meses, años, horas, minutos y segundos
- DateTimeImmutable::__construct — Devuelve un nuevo objeto DateTimeImmutable
- DateTimeImmutable::createFromFormat — Analiza un string de tiempo según el formato especificado
- DateTimeImmutable::createFromInterface — Devuelve un nuevo objeto DateTimeImmutable que encapsula el objeto DateTimeInterface dado
- DateTimeImmutable::createFromMutable — Devuelve un nuevo objeto DateTimeImmutable que encapsula el objeto DateTime dado
- DateTimeImmutable::createFromTimestamp — Crea una instancia a partir de una marca de tiempo Unix
- DateTimeImmutable::getLastErrors — Devuelve las advertencias y errores
- DateTimeImmutable::modify — Crea un nuevo objeto con la marca de tiempo modificada
- DateTimeImmutable::__set_state — El gestor __set_state
- DateTimeImmutable::setDate — Establece la fecha
- DateTimeImmutable::setISODate — Establece la fecha ISO
- DateTimeImmutable::setMicrosecond — Establece la parte de microsegundos de la hora
- DateTimeImmutable::setTime — Establece la hora
- DateTimeImmutable::setTimestamp — Establece la fecha y hora basadas en una marca de tiempo Unix (Unix timestamp)
- DateTimeImmutable::setTimezone — Establece la zona horaria
- DateTimeImmutable::sub — Sustrae una cantidad de días, meses, años, horas, minutos y segundos

# La interfaz DateTimeInterface

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introducción

DateTimeInterface fue creada tanto como parametro de retorno, como para las declaraciones de tipo de propiedad puedan aceptar tanto DateTimeImmutable o DateTime como valor. No es posible que el usuario implemente esta interfaz en sus propias clases.

Las constantes comunes que permiten el formato de objetos DateTimeImmutable o DateTime mediante DateTimeImmutable::format() y DateTime::format() son también definidas en esta interfaz.

## Sinopsis de la Clase

interface DateTimeInterface {
/* Constantes */
public const string ATOM = "Y-m-d\\TH:i:sP";
public const string COOKIE = "l, d-M-Y H:i:s T";
public const string ISO8601 = "Y-m-d\\TH:i:sO";
public const string ISO8601_EXPANDED = "X-m-d\\TH:i:sP";
public const string RFC822 = "D, d M y H:i:s O";
public const string RFC850 = "l, d-M-y H:i:s T";
public const string RFC1036 = "D, d M y H:i:s O";
public const string RFC1123 = "D, d M Y H:i:s O";
public const string RFC7231 = "D, d M Y H:i:s \\G\\M\\T";
public const string RFC2822 = "D, d M Y H:i:s O";
public const string RFC3339 = "Y-m-d\\TH:i:sP";
public const string RFC3339_EXTENDED = "Y-m-d\\TH:i:s.vP";
public const string RSS = "D, d M Y H:i:s O";
public const string W3C = "Y-m-d\\TH:i:sP";
/* Métodos */
public function diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function format(string `$format`): string
public function getMicrosecond(): int
public function getOffset(): int
public function getTimestamp(): int
public function getTimezone(): DateTimeZone|false
public function __serialize(): array
public function __unserialize(array `$data`): void
#[\Deprecated]
public function __wakeup(): void
}

## Constantes predefinidas

DateTimeInterface::ATOM string
DATE_ATOM
  Atom (ejemplo: `2005-08-15T15:52:01+00:00`); compatible con ISO-8601, RFC 3339 y XML Schema
DateTimeInterface::COOKIE string
DATE_COOKIE
  HTTP Cookies (ejemplo: `Monday, 15-Aug-2005 15:52:01 UTC`)
DateTimeInterface::ISO8601 string
DATE_ISO8601
  Similar a ISO-8601 (ejemplo: `2005-08-15T15:52:01+0000`)

  > Nota: Este formato no es compatible con el ISO-8601, aunque se deja por razones de retrocompatibilidad. Use DateTimeInterface::ISO8601_EXPANDED, DateTimeInterface::ATOM en su lugar para que sea compatible con el ISO-8601. (ref ISO8601:2004 section 4.3.3 clause d)

DateTimeInterface::ISO8601_EXPANDED string
DATE_ISO8601_EXPANDED
  ISO-8601 Extendido (ejemplo: `+10191-07-26T08:59:52+01:00`)

  > Nota: Este formato permite rangos de años fuera del rango normal de ISO-8601 de `0000`-`9999` al incluir siempre un carácter de signo. También asegura que la parte de la zona horaria (`+01:00`) sea compatible con ISO-8601.

DateTimeInterface::RFC822 string
DATE_RFC822
  RFC 822 (ejemplo: `Mon, 15 Aug 05 15:52:01 +0000`)
DateTimeInterface::RFC850 string
DATE_RFC850
  RFC 850 (ejemplo: `Monday, 15-Aug-05 15:52:01 UTC`)
DateTimeInterface::RFC1036 string
DATE_RFC1036
  RFC 1036 (ejemplo: `Mon, 15 Aug 05 15:52:01 +0000`)
DateTimeInterface::RFC1123 string
DATE_RFC1123
  RFC 1123 (ejemplo: `Mon, 15 Aug 2005 15:52:01 +0000`)
DateTimeInterface::RFC7231 string
DATE_RFC7231
  RFC 7231 (desde PHP 7.0.19 y 7.1.5) (ejemplo: `Sat, 30 Apr 2016 17:52:13 GMT`)
DateTimeInterface::RFC2822 string
DATE_RFC2822
  RFC 2822 (ejemplo: `Mon, 15 Aug 2005 15:52:01 +0000`)
DateTimeInterface::RFC3339 string
DATE_RFC3339
  Igual que DATE_ATOM
DateTimeInterface::RFC3339_EXTENDED string
DATE_RFC3339_EXTENDED
  Formato RFC 3339 EXTENDED (ejemplo: `2005-08-15T15:52:01.000+00:00`)
DateTimeInterface::RSS string
DATE_RSS
  RSS (ejemplo: `Mon, 15 Aug 2005 15:52:01 +0000`).
DateTimeInterface::W3C string
DATE_W3C
  World Wide Web Consortium (ejemplo: `2005-08-15T15:52:01+00:00`).

## Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | Las constantes `DATE_RFC7231` y `DateTimeInterface::RFC7231` han sido obsoletas.
8.4.0 | Las constantes de clase ahora están tipadas.
8.2.0 | Se ha añadido la constante `DateTimeInterface::ISO8601_EXPANDED`.
7.2.0 | Las constantes de clase de DateTime ahora están definidas en DateTimeInterface.

# DateTimeInterface::diff

# DateTimeImmutable::diff

# DateTime::diff

# date_diff

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTimeInterface::diff -- DateTimeImmutable::diff -- DateTime::diff -- date_diff — Devuelve la diferencia entre dos objetos DateTime

### Descripción

Estilo orientado a objetos

public function DateTimeInterface::diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function DateTimeImmutable::diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function DateTime::diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval

Estilo procedimental

function date_diff(DateTimeInterface `$baseObject`, DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval

Devuelve la diferencia entre dos objetos DateTimeInterface.

### Parámetros

`datetime`

  La fecha a comparar.

`absolute`

  ¿Debería el intervalo forzado a ser positivo?

### Valores devueltos

El objeto DateInterval que representa la diferencia entre dos fechas.

El parámetro `absolute` solo afecta a la propiedad `invert` de un objeto DateInterval.

El valor devuelto más especificamente, representa el intervalo de tiempo que habría que aplicar al objeto original (`$this` o `$originObject`) para llegar a `$targetObject`. Este proceso no siempre es reversible.

El método tiene en cuenta los cambios de horario de verano y, por lo tanto, puede devolver un intervalo de `24 horas y 30 minutos`, como en uno de los ejemplos. Si quieres calcular un tiempo absoluto, debes comvertir ambos `$this`/`$baseObject`, y `$targetObject` primero a UTC.

### Ejemplos

Ejemplo #1 Ejemplo de DateTime::diff()

Estilo orientado a objetos

    <?php
    $origin = new DateTimeImmutable('2009-10-11');
    $target = new DateTimeImmutable('2009-10-13');
    $interval = $origin->diff($target);
    echo $interval->format('%R%a days');

El ejemplo anterior mostrará:

    +2 days

Estilo procedimental

    <?php
    $origin = date_create('2009-10-11');
    $target = date_create('2009-10-13');
    $interval = date_diff($origin, $target);
    echo $interval->format('%R%a days');

El ejemplo anterior mostrará:

    +2 days

Ejemplo #2 DateTimeInterface::diff() durante el cambio de horario de verano

    <?php
    $originalTime = new DateTimeImmutable("2021-10-30 09:00:00 Europe/London");
    $targetTime = new DateTimeImmutable("2021-10-31 08:30:00 Europe/London");
    $interval = $originalTime->diff($targetTime);
    echo $interval->format("%H:%I:%S (Días completos: %a)"), "\n";

El ejemplo anterior mostrará:

    24:30:00 (Días completos: 0)

Ejemplo #3 Rango de DateTimeInterface::diff()

El valor devuelto es la cantidad de tiempo exacto entre `$this` y `$targetObject`. Comparando del 1 de enero al 31 de diciembre devuelve 364 días, y no 365 (para años no bisiestos).

    <?php
    $originalTime = new DateTimeImmutable("2023-01-01 UTC");
    $targetTime = new DateTimeImmutable("2023-12-31 UTC");
    $interval = $originalTime->diff($targetTime);
    echo "Días completos: ", $interval->format("%a"), "\n";

El ejemplo anterior mostrará:

    Días completos: 364

Ejemplo #4 Comparación de objetos DateTime

> Nota:

> Los objetos DateTimeImmutable y DateTime se pueden comparar usando los operadores de comparación.

    <?php
    $date1 = new DateTime("now");
    $date2 = new DateTime("tomorrow");

    var_dump($date1 == $date2);
    var_dump($date1 < $date2);
    var_dump($date1 > $date2);

El ejemplo anterior mostrará:

    bool(false)
    bool(true)
    bool(false)

### Ver también

- DateInterval::format() - Formatea el intervalo
- DateTime::add() - Modifica un objeto DateTime, añadiendo una cantidad de días, meses, años, horas, minutos y segundos
- DateTime::sub() - Sustrae una cantidad de días, meses, años, horas, minutos y segundos de un objeto DateTime

# DateTimeInterface::format

# DateTimeImmutable::format

# DateTime::format

# date_format

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeInterface::format -- DateTimeImmutable::format -- DateTime::format -- date_format — Retorna una fecha formateada según el formato proporcionado

### Descripción

Estilo orientado a objetos

public function DateTimeInterface::format(string `$format`): string
public function DateTimeImmutable::format(string `$format`): string
public function DateTime::format(string `$format`): string

Estilo procedimental

function date_format(DateTimeInterface `$object`, string `$format`): string

Retorna una fecha formateada según el formato proporcionado.

### Parámetros

`object`
  Solo en estilo procedimental: un objeto DateTime retornado por date_create()
`format`

  El formato de la fecha deseada en forma de string. Ver las opciones de formato a continuación. Existen también numerosas constantes de fechas que pueden ser utilizadas, lo que hace que `DATE_RSS` reemplace el formato `"D, d M Y H:i:s"`.

  Los siguientes caracteres son reconocidos en el parámetro `format`
  Caracteres para el parámetro `format` | Descripción | Ejemplos de valores retornados
  --- | --- | ---
  Día | --- | ---
  `d` | Día del mes, en dos dígitos (con un cero inicial) | `01` a `31`
  `D` | Día de la semana, en tres letras (y en inglés - por defecto: en inglés, o sino, en el idioma local del servidor) | `Mon` a `Sun`
  `j` | Día del mes sin los ceros iniciales | `1` a `31`
  `l` ('L' minúscula) | Día de la semana, textual, versión larga, en inglés | `Sunday` a `Saturday`
  `N` | Representación numérica ISO 8601 del día de la semana | `1` (para Lunes) a `7` (para Domingo)
  `S` | Sufijo ordinal de un número para el día del mes, en inglés, en dos letras | `st`, `nd`, `rd` o `th`. Funciona bien con `j`
  `w` | Día de la semana en formato numérico | `0` (para domingo) a `6` (para sábado)
  `z` | Día del año | `0` a `365`
  Semana | --- | ---
  `W` | Número de semana en el año ISO 8601, las semanas comienzan el lunes | Ejemplo: `42` (la 42ª semana del año)
  Mes | --- | ---
  `F` | Mes, textual, versión larga; en inglés, como `January` o `December` | `January` a `December`
  `m` | Mes en formato numérico, con ceros iniciales | `01` a `12`
  `M` | Mes, en tres letras, en inglés | `Jan` a `Dec`
  `n` | Mes sin los ceros iniciales | `1` a `12`
  `t` | Número de días en el mes | `28` a `31`
  Año | --- | ---
  `L` | ¿Es el año bisiesto? | `1` si es bisiesto, `0` si no.
  `o` | Año de numeración de semanas ISO 8601. Es el mismo valor que `Y`, excepto si el número de semana ISO (`W`) pertenece al año anterior o siguiente, este año será utilizado en su lugar. | Ejemplos: `1999` o `2003`
  `X` | Una representación numérica completa extendida de un año, de al menos 4 dígitos, con un `-` para los años antes de la era común y un `+` para los años de la era común. | Ejemplos: `-0055`, `+0787`, `+1999`, `+10191`
  `x` | Una representación numérica completa extendida si es necesario, o una representación numérica completa estándar si es posible (como `Y`). Al menos cuatro dígitos. Los años anteriores a la era común son prefijados por un `-`. Los años más allá (y incluyendo) del `10000` son prefijados por un `+`. | Ejemplos: `-0055`, `0787`, `1999`, `+10191`
  `Y` | Una representación numérica completa de un año, al menos 4 dígitos, con `-` para los años av. J.-C. | Ejemplos: `-0055`, `0787`, `1999`, `2003`, `10191`
  `y` | Año en 2 dígitos | Ejemplos: `99` o `03`
  Hora | --- | ---
  `a` | Ante meridiem y Post meridiem en minúsculas | `am` o `pm`
  `A` | Ante meridiem y Post meridiem en mayúsculas | `AM` o `PM`
  `B` | Hora Internet Swatch | `000` a `999`
  `g` | Hora, en formato 12h, sin los ceros iniciales | `1` a `12`
  `G` | Hora, en formato 24h, sin los ceros iniciales | `0` a `23`
  `h` | Hora, en formato 12h, con los ceros iniciales | `01` a `12`
  `H` | Hora, en formato 24h, con los ceros iniciales | `00` a `23`
  `i` | Minutos con ceros iniciales | `00` a `59`
  `s` | Segundos con ceros iniciales | `00` a `59`
  `u` | Microsegundos. Tenga en cuenta que la función date() generará siempre `000000` ya que toma un parámetro de tipo int, mientras que el método DateTimeInterface::format() soporta microsegundos si un objeto de tipo DateTimeInterface fue creado con microsegundos. | Ejemplo: `654321`
  `v` | Milisegundos. Misma nota que para `u`. | Ejemplo: `654`
  Zona horaria | --- | ---
  `e` | El identificador de la zona horaria | Ejemplos: `UTC`, `GMT`, `Atlantic/Azores`
  `I` (i mayúscula) | La hora de verano está activada o no | `1` si sí, `0` si no.
  `O` | Diferencia de horas con la hora de Greenwich (GMT), sin dos puntos entre las horas y los minutos | Ejemplo: `+0200`
  `P` | Diferencia con la hora Greenwich (GMT) con un dos puntos entre las horas y los minutos | Ejemplo: `+02:00`
  `p` | Idéntico a `P`, pero retorna `Z` en lugar de `+00:00` (disponible a partir de PHP 8.0.0) | Ejemplos: `Z` o `+02:00`
  `T` | Abreviación de la zona horaria, si es conocida; sino, desplazamiento desde GMT | Ejemplos: `EST`, `MDT`, `+05`
  `Z` | Desplazamiento horario en segundos. El desplazamiento de zonas al oeste de la zona UTC es negativo, y al este, es positivo. | `-43200` a `50400`
  Fecha y Hora completa | --- | ---
  `c` | Fecha en formato ISO 8601. Solo compatible con el formato no expandido (hasta el año 9999). Las fechas posteriores generarán una cadena no válida. Para fechas posteriores y el formato expandido, consulte `x` y `X`. | 2004-02-12T15:19:21+00:00
  `r` | Formato de fecha » RFC 2822/» RFC 5322 | Ejemplo: `Thu, 21 Dec 2000 16:01:070200`
  `U` | Segundos desde la época Unix (1 de Enero de 1970, 0h00 00s GMT) | Ver también time()

  Los caracteres no reconocidos serán impresos tal cual. "`Z`" retornará siempre `0` cuando se utiliza con gmdate().

  > Nota:

  > Sabiendo que esta función solo acepta timestamps de tipo int, el carácter `u` solo es útil al utilizar la función date_format() con un timestamp de usuario creado con la función date_create().

### Valores devueltos

Retorna la fecha formateada, en forma de string, en caso de éxito.

### Historial de cambios

Versión | Descripción
--- | ---
8.2.0 | Los caracteres de formato `X` o `x` han sido añadidos.
8.0.0 | El carácter de formato `p` ha sido añadido.

### Ejemplos

Ejemplo #1 Ejemplo con DateTime::format()

Estilo orientado a objetos

    <?php
    $date = new DateTimeImmutable('2000-01-01');
    echo $date->format('Y-m-d H:i:s');
    ?>

El ejemplo anterior mostrará:

    2000-01-01 00:00:00

Estilo procedimental

    <?php
    $date = date_create('2000-01-01');
    echo date_format($date, 'Y-m-d H:i:s');
    ?>

El ejemplo anterior mostrará:

    2000-01-01 00:00:00

Ejemplo #2 Más ejemplos

    <?php
    // establece la zona horaria predeterminada a usar.
    date_default_timezone_set('UTC');

    // ahora
    $date = new DateTimeImmutable();

    // Imprime algo como: Wednesday
    echo $date->format('l'), "\n";

    // Imprime algo como: Wednesday 19th of October 2022 08:40:48 AM
    echo $date->format('l jS \o\f F Y h:i:s A'), "\n";

    /* usa las constantes en el parámetro de formato */
    // imprime algo como: Wed, 19 Oct 2022 08:40:48 +0000
    echo $date->format(DateTimeInterface::RFC2822), "\n";
    ?>

Es posible evitar que un carácter reconocido en la cadena de formato se expanda escapándolo con un backslash (barra invertida). Si el carácter con backslash es ya una secuencia especial, será necesario también escapar el backslash.

Ejemplo #3 Escape de caracteres durante el formato

    <?php
    $date = new DateTimeImmutable();

    // imprime algo como: Wednesday the 19th
    echo $date->format('l \t\h\e jS');
    ?>

Para formatear fechas en otros idiomas, IntlDateFormatter::format() puede ser utilizada en lugar de DateTimeInterface::format().

### Notas

Este método no utiliza locales. Todos los despliegues serán en inglés.

### Ver también

- IntlDateFormatter::format() - Formatea la fecha y la hora como string

# DateTimeInterface::getMicrosecond

# DateTimeImmutable::getMicrosecond

# DateTime::getMicrosecond

(PHP 8 >= 8.4.0)

DateTimeInterface::getMicrosecond -- DateTimeImmutable::getMicrosecond -- DateTime::getMicrosecond — Obtiene la parte de microsegundos de la marca de tiempo Unix

### Descripción

public function DateTimeInterface::getMicrosecond(): int
public function DateTimeImmutable::getMicrosecond(): int
public function DateTime::getMicrosecond(): int

Obtiene la parte de microsegundos de la marca de tiempo Unix.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la parte de microsegundos de la marca de tiempo Unix que representa la fecha.

### Ejemplos

Ejemplo #1 Ejemplo de DateTimeInterface::getMicrosecond()

    <?php
    $date = new DateTimeImmutable('2024-01-01 12:34:56.789123');
    var_dump($date->format('u'));
    var_dump($date->getMicrosecond());
    ?>

El ejemplo anterior mostrará:

    string(6) "789123"
    int(789123)

### Ver también

- DateTimeInterface::getTimestamp() - Obtiene el timestamp Unix
- DateTimeInterface::format() - Retorna una fecha formateada según el formato proporcionado

# DateTimeInterface::getOffset

# DateTimeImmutable::getOffset

# DateTime::getOffset

# date_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeInterface::getOffset -- DateTimeImmutable::getOffset -- DateTime::getOffset -- date_offset_get — Devuelve el desplazamiento horario

### Descripción

Estilo orientado a objetos

public function DateTimeInterface::getOffset(): int
public function DateTimeImmutable::getOffset(): int
public function DateTime::getOffset(): int

Estilo procedimental

function date_offset_get(DateTimeInterface `$object`): int

Devuelve el desplazamiento horario.

### Parámetros

`object`
  Solo en estilo procedimental: un objeto DateTime retornado por date_create()

### Valores devueltos

Devuelve el desplazamiento horario en segundos, desde UTC en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo con DateTime::getOffset()

Estilo orientado a objetos

    <?php
    $winter = new DateTimeImmutable('2010-12-21', new DateTimeZone('America/New_York'));
    $summer = new DateTimeImmutable('2008-06-21', new DateTimeZone('America/New_York'));

    echo $winter->getOffset() . "\n";
    echo $summer->getOffset() . "\n";

El ejemplo anterior mostrará:

    -18000
    -14400

Estilo procedimental

    <?php
    $winter = date_create('2010-12-21', timezone_open('America/New_York'));
    $summer = date_create('2008-06-21', timezone_open('America/New_York'));

    echo date_offset_get($winter) . "\n";
    echo date_offset_get($summer) . "\n";

El ejemplo anterior mostrará:

    -18000
    -14400

Nota: -18000 = -5 horas, -14400 = -4 horas.

# DateTimeInterface::getTimestamp

# DateTimeImmutable::getTimestamp

# DateTime::getTimestamp

# date_timestamp_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTimeInterface::getTimestamp -- DateTimeImmutable::getTimestamp -- DateTime::getTimestamp -- date_timestamp_get — Obtiene el timestamp Unix

### Descripción

Estilo orientado a objetos

public function DateTimeInterface::getTimestamp(): int
public function DateTimeImmutable::getTimestamp(): int
public function DateTime::getTimestamp(): int

Estilo procedimental

function date_timestamp_get(DateTimeInterface `$object`): int

Obtiene el timestamp Unix.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el timestamp Unix que representa la fecha.

### Errores/Excepciones

Si el sello de tiempo no puede ser representado como un int, se lanza una DateRangeError. Anterior a PHP 8.3.0, se lanzaba una ValueError. Y anterior a PHP 8.0.0, se devolvía `false` en este caso. Sin embargo, el sello de tiempo puede ser obtenido como un string utilizando DateTimeInterface::format() con el formato `U`.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | La excepción de fuera de rango ahora es una DateRangeError.
8.0.0 | Estas funciones ya no devuelven `false` en caso de fallo.

### Ejemplos

Ejemplo #1 Ejemplo con DateTime::getTimestamp()

Estilo orientado a objetos

    <?php
    $date = new DateTimeImmutable();
    echo $date->getTimestamp();

Resultado del ejemplo anterior es similar a:

    1272509157

Estilo procedimental

    <?php
    $date = date_create();
    echo date_timestamp_get($date);

Resultado del ejemplo anterior es similar a:

    1272509157

Para obtener el sello de tiempo con precisión en milisegundos o microsegundos, es posible utilizar la función DateTimeInterface::format().

Ejemplo #2 Obtención del sello de tiempo con precisión en milisegundos y microsegundos

Estilo orientado a objetos

    <?php
    $date = new DateTimeImmutable();
    $milli = (int) $date->format('Uv'); // Timestamp en milisegundos
    $micro = (int) $date->format('Uu'); // Timestamp en microsegundos

    echo $milli, "\n", $micro, "\n";

Resultado del ejemplo anterior es similar a:

    1674057635586
    1674057635586918

### Ver también

- DateTime::setTimestamp() - Establece la fecha y la hora basándose en una marca temporal de Unix
- DateTimeImmutable::setTimestamp() - Establece la fecha y hora basadas en una marca de tiempo Unix (Unix timestamp)
- DateTimeInterface::format() - Retorna una fecha formateada según el formato proporcionado
- DateTimeInterface::getMicrosecond() - Obtiene la parte de microsegundos de la marca de tiempo Unix

# DateTimeInterface::getTimezone

# DateTimeImmutable::getTimezone

# DateTime::getTimezone

# date_timezone_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeInterface::getTimezone -- DateTimeImmutable::getTimezone -- DateTime::getTimezone -- date_timezone_get — Devuelve la zona horaria relativa al DateTime proporcionado

### Descripción

Estilo orientado a objetos

public function DateTimeInterface::getTimezone(): DateTimeZone|false
public function DateTimeImmutable::getTimezone(): DateTimeZone|false
public function DateTime::getTimezone(): DateTimeZone|false

Estilo procedimental

function date_timezone_get(DateTimeInterface `$object`): DateTimeZone|false

Devuelve la zona horaria relativa al DateTime proporcionado.

### Parámetros

`object`
  Solo en estilo procedimental: un objeto DateTime retornado por date_create()

### Valores devueltos

Devuelve un objeto DateTimeZone en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con DateTime::getTimezone()

Estilo orientado a objetos

    <?php
    $date = new DateTimeImmutable("now", new DateTimeZone('Europe/London'));
    $tz = $date->getTimezone();
    echo $tz->getName();

El ejemplo anterior mostrará:

    Europe/London

Estilo procedimental

    <?php
    $date = date_create("now", timezone_open('Europe/London'));
    $tz = date_timezone_get($date);
    echo timezone_name_get($tz);

El ejemplo anterior mostrará:

    Europe/London

### Ver también

- DateTime::setTimezone() - Establece la zona horaria para el objeto DateTime

# DateTime::__serialize

# DateTimeImmutable::__serialize

# DateTimeInterface::__serialize

(PHP 8 >= 8.2.0)

DateTime::__serialize -- DateTimeImmutable::__serialize -- DateTimeInterface::__serialize — Deserializa un DateTime

### Descripción

public function DateTime::__serialize(): array
public function DateTimeImmutable::__serialize(): array
public function DateTimeInterface::__serialize(): array

El gestor __serialize().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

La representación serializada del objeto DateTime.

### Ejemplos

Ejemplo #1 Ejemplo de DateTime::serialize()

    <?php
    $date = new DateTime('2025-03-27');
    var_dump(serialize($date));

El ejemplo anterior mostrará:

    string(114) "O:8:"DateTime":3:{s:4:"date";s:26:"2025-03-27 00:00:00.000000";s:13:"timezone_type";i:3;s:8:"timezone";s:3:"UTC";}"

### Ver también

- DateTime::__unserialize() - Deserializar un DateTime

# DateTime::__unserialize

# DateTimeImmutable::__unserialize

# DateTimeInterface::__unserialize

(PHP 8 >= 8.2.0)

DateTime::__unserialize -- DateTimeImmutable::__unserialize -- DateTimeInterface::__unserialize — Deserializar un DateTime

### Descripción

public function DateTime::__unserialize(array `$data`): void
public function DateTimeImmutable::__unserialize(array `$data`): void
public function DateTimeInterface::__unserialize(array `$data`): void

El gestor __unserialize().

### Parámetros

`data`

  El DateTime serializado.

### Valores devueltos

El objeto DateTime.

### Ejemplos

Ejemplo #1 Ejemplo de DateTime::unserialize()

    <?php
    $serializedDate = 'O:8:"DateTime":3:{s:4:"date";s:26:"2025-03-27 00:00:00.000000";s:13:"timezone_type";i:3;s:8:"timezone";s:3:"UTC";}';
    var_dump(unserialize($serializedDate));

El ejemplo anterior mostrará:

    object(DateTime)#1 (3) {
      ["date"]=>
      string(26) "2025-03-27 00:00:00.000000"
      ["timezone_type"]=>
      int(3)
      ["timezone"]=>
      string(3) "UTC"
    }

### Ver también

- DateTime::__serialize() - Deserializa un DateTime

# DateTime::__wakeup

# DateTimeImmutable::__wakeup

# DateTimeInterface::__wakeup

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::__wakeup -- DateTimeImmutable::__wakeup -- DateTimeInterface::__wakeup — El manejador __wakeup

Advertencia

Esta función está OBSOLETA a partir de PHP 8.5.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
public function DateTime::__wakeup(): void
#[\Deprecated]
public function DateTimeImmutable::__wakeup(): void
#[\Deprecated]
public function DateTimeInterface::__wakeup(): void

El manejador __wakeup().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Inicializa un objeto DateTime.

## Tabla de contenidos

- DateTimeInterface::diff — Devuelve la diferencia entre dos objetos DateTime
- DateTimeInterface::format — Retorna una fecha formateada según el formato proporcionado
- DateTimeInterface::getMicrosecond — Obtiene la parte de microsegundos de la marca de tiempo Unix
- DateTimeInterface::getOffset — Devuelve el desplazamiento horario
- DateTimeInterface::getTimestamp — Obtiene el timestamp Unix
- DateTimeInterface::getTimezone — Devuelve la zona horaria relativa al DateTime proporcionado
- DateTime::__serialize — Deserializa un DateTime
- DateTime::__unserialize — Deserializar un DateTime
- DateTime::__wakeup — El manejador __wakeup

# La clase DateTimeZone

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

## Introducción

Representación de una zona horaria.

## Sinopsis de la Clase

class DateTimeZone {
/* Constantes */
public const int AFRICA;
public const int AMERICA;
public const int ANTARCTICA;
public const int ARCTIC;
public const int ASIA;
public const int ATLANTIC;
public const int AUSTRALIA;
public const int EUROPE;
public const int INDIAN;
public const int PACIFIC;
public const int UTC;
public const int ALL;
public const int ALL_WITH_BC;
public const int PER_COUNTRY;
/* Métodos */
public function __construct(string `$timezone`)
public function getLocation(): array|false
public function getName(): string
public function getOffset(DateTimeInterface `$datetime`): int
public function getTransitions(int `$timestampBegin` = `PHP_INT_MIN`, int `$timestampEnd` = 2147483647): array|false
public static function listAbbreviations(): array
public static function listIdentifiers(int `$timezoneGroup` = `DateTimeZone::ALL`, ?string `$countryCode` = `null`): array
}

## Constantes predefinidas

`DateTimeZone::AFRICA` int

  Zona africana.

`DateTimeZone::AMERICA` int

  Zona americana.

`DateTimeZone::ANTARCTICA` int

  Zona antártica.

`DateTimeZone::ARCTIC` int

  Zona ártica.

`DateTimeZone::ASIA` int

  Zona asiática.

`DateTimeZone::ATLANTIC` int

  Zona atlántica.

`DateTimeZone::AUSTRALIA` int

  Zona australiana.

`DateTimeZone::EUROPE` int

  Zona europea.

`DateTimeZone::INDIAN` int

  Zona india.

`DateTimeZone::PACIFIC` int

  Zona del Pacífico.

`DateTimeZone::UTC` int

  Zona UTC.

`DateTimeZone::ALL` int

  Todas las zonas.

`DateTimeZone::ALL_WITH_BC` int

  Todas las zonas, incluyendo las antiguas.

`DateTimeZone::PER_COUNTRY` int

  Zonas horarias por país.

## Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Las constantes de clase ahora están tipadas.

# DateTimeZone::__construct

# timezone_open

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::__construct -- timezone_open — Crea un nuevo objeto DateTimeZone

### Descripción

Estilo orientado a objetos

public function DateTimeZone::__construct(string `$timezone`)

Estilo procedimental

function timezone_open(string `$timezone`): DateTimeZone|false

Crea un nuevo objeto DateTimeZone.

Un objeto DateTimeZone proporciona acceso a tres tipos diferentes de reglas de zona horaria: un desplazamiento UTC (tipo `1`), una abreviatura de zona horaria (tipo `2`), y un identificador de zona horaria tal como se publica en la base de datos de zonas horarias IANA (tipo `3`).

El objeto DateTimeZone puede ser adjuntado a los objetos DateTime y DateTimeImmutable con el fin de poder representar la zona horaria encapsulada por estos objetos en una zona horaria local.

### Parámetros

`timezone`

  Una de las zonas horarias soportadas, un valor de desplazamiento (+0200), o una abreviatura de zona (BST).

### Valores devueltos

Devuelve un objeto DateTimeZone en caso de éxito. Estilo procedimental retorna `false` en caso de error..

### Errores/Excepciones

Este método lanza una DateInvalidTimeZoneException si la zona horaria proporcionada no es reconocida como una zona horaria válida. Anteriormente a PHP 8.3, esto era una Exception.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Los valores inválidos ahora lanzan una DateInvalidTimeZoneException en lugar de una Exception genérica.

### Ejemplos

Ejemplo #1 Creación y adjuntado de DateTimeZone a un DateTimeImmutable

    <?php
    $d = new DateTimeImmutable("2022-06-02 15:44:48 UTC");

    $timezones = [ 'Europe/London', 'GMT+04:45', '-06:00', 'CEST' ];

    foreach ($timezones as $tz) {
        $tzo = new DateTimeZone($tz);

        $local = $d->setTimezone($tzo);
        echo $local->format(DateTimeInterface::RFC2822 . ' — e') . "\n";
    }

El ejemplo anterior mostrará:

    Thu, 02 Jun 2022 16:44:48 +0100 — Europe/London
    Thu, 02 Jun 2022 20:29:48 +0445 — +04:45
    Thu, 02 Jun 2022 09:44:48 -0600 — -06:00
    Thu, 02 Jun 2022 17:44:48 +0200 — CEST

Ejemplo #2 Intercepción de errores con DateTimeZone

    <?php
    // Manejo de errores por intercepción de excepciones
    $timezones = array('Europe/London', 'Mars/Phobos', 'Jupiter/Europa');

    foreach ($timezones as $tz) {
        try {
            $mars = new DateTimeZone($tz);
            echo $mars->getName() . "\n";
        } catch(Exception $e) {
            echo $e->getMessage() . "\n";
        }
    }

El ejemplo anterior mostrará:

    Europe/London
    DateTimeZone::__construct() [datetimezone.--construct]: Unknown or bad timezone (Mars/Phobos)
    DateTimeZone::__construct() [datetimezone.--construct]: Unknown or bad timezone (Jupiter/Europa)

# DateTimeZone::getLocation

# timezone_location_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTimeZone::getLocation -- timezone_location_get — Devuelve las informaciones geográficas de una zona horaria

### Descripción

Estilo orientado a objetos

public function DateTimeZone::getLocation(): array|false

Estilo procedimental

function timezone_location_get(DateTimeZone `$object`): array|false

Devuelve las informaciones geográficas de una zona horaria, incluyendo el código del país, la latitud y longitud, y comentarios.

### Parámetros

`object`
  Solo en estilo procedimental: un objeto DateTimeZone retornado por timezone_open()

### Valores devueltos

Array que contiene las informaciones de localización de la zona horaria o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con DateTimeZone::getLocation()

    <?php
    $tz = new DateTimeZone("Asia/Jakarta");
    print_r($tz->getLocation());
    print_r(timezone_location_get($tz));

El ejemplo anterior mostrará:

    Array
    (
        [country_code] => ID
        [latitude] => -6.16667
        [longitude] => 106.8
        [comments] => Java, Sumatra
    )
    Array
    (
        [country_code] => ID
        [latitude] => -6.16667
        [longitude] => 106.8
        [comments] => Java, Sumatra
    )

Los elementos `country_code` contienen el código de país ISO 3166-1 alfa-2 correspondiente a cada entrada. Los elementos `latitude` y `longitude` indican las coordenadas de la ciudad nombrada en el identificador de zona horaria, y `comments` incluye (cuando no es `false`) una indicación de la región del país a la que se aplica dicha zona horaria. Esta información es adecuada para ser presentada a usuarios finales.

### Ver también

- DateTimeZone::listIdentifiers() - Devuelve un array numérico que contiene todos los identificadores de zonas horarias definidos para obtener una lista completa o parcial de todos los identificadores de zonas horarias soportadas

# DateTimeZone::getName

# timezone_name_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getName -- timezone_name_get — Devuelve el nombre de la zona horaria

### Descripción

Estilo orientado a objetos

public function DateTimeZone::getName(): string

Estilo procedimental

function timezone_name_get(DateTimeZone `$object`): string

Devuelve el nombre de la zona horaria.

### Parámetros

`object`

  El objeto DateTimeZone utilizado para recuperar el nombre de la zona horaria.

### Valores devueltos

Según el tipo de zona, el desplazamiento UTC (tipo 1), la abreviatura de zona horaria (tipo 2) y los identificadores de zona horaria tales como se publican en la base de datos de zonas horarias IANA (tipo 3), la cadena de descripción para crear un nuevo objeto DateTimeZone con el mismo desplazamiento y/o las mismas reglas. Por ejemplo `02:00`, `CEST` o uno de los nombres de zonas horarias en la lista de zonas horarias.

# DateTimeZone::getOffset

# timezone_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getOffset -- timezone_offset_get — Retorna el desplazamiento GMT de una zona horaria

### Descripción

Estilo orientado a objetos

public function DateTimeZone::getOffset(DateTimeInterface `$datetime`): int

Estilo procedimental

function timezone_offset_get(DateTimeZone `$object`, DateTimeInterface `$datetime`): int

Esta función retorna el desplazamiento GMT para la fecha/hora especificada en el parámetro `datetime`. El desplazamiento GMT se calcula a partir de las informaciones de zona horaria contenidas en el objeto DateTimeZone utilizado.

### Parámetros

`object`
  Solo en estilo procedimental: un objeto DateTimeZone retornado por timezone_open()
`datetime`

  DateTime que contiene la fecha/hora desde la cual se debe calcular el desplazamiento.

### Valores devueltos

Retorna el desplazamiento horario, expresado en segundos, en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo con DateTimeZone::getOffset()

    <?php
    // Crea dos objetos zona horaria, uno para Taipei (Taiwán) y uno para
    // Tokio (Japón)
    $dateTimeZoneTaipei = new DateTimeZone("Asia/Taipei");
    $dateTimeZoneJapan = new DateTimeZone("Asia/Tokyo");

    // Crea dos objetos DateTime que contienen el mismo timestamp Unix,
    // pero están situados en dos zonas horarias diferentes.
    $dateTimeTaipei = new DateTime("now", $dateTimeZoneTaipei);
    $dateTimeJapan = new DateTime("now", $dateTimeZoneJapan);

    // Calcula el desplazamiento horario GMT para el objeto $dateTimeTaipei
    // pero utilizando la zona horaria de Tokio
    // ($dateTimeZoneJapan).
    $timeOffset = $dateTimeZoneJapan->getOffset($dateTimeTaipei);

    // Debería mostrar int(32400) (para las fechas posteriores al Sat Sep 8 01:00:00 1951 JST).
    var_dump($timeOffset);

El ejemplo anterior mostrará:

    int(32400)

# DateTimeZone::getTransitions

# timezone_transitions_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getTransitions -- timezone_transitions_get — Devuelve todas las transiciones de una zona horaria

### Descripción

Estilo orientado a objetos

public function DateTimeZone::getTransitions(int `$timestampBegin` = `PHP_INT_MIN`, int `$timestampEnd` = 2147483647): array|false

Estilo procedimental

function timezone_transitions_get(DateTimeZone `$object`, int `$timestampBegin` = `PHP_INT_MIN`, int `$timestampEnd` = 2147483647): array|false

### Parámetros

`object`
  Solo en estilo procedimental: un objeto DateTimeZone retornado por timezone_open()
`timestampBegin`

  Inicio del timestamp.

`timestampEnd`

  Fin del timestamp.

### Valores devueltos

Devuelve un array indexado numéricamente de arrays de transición en caso de éxito, o `false` si ocurre un error. Los objetos DateTimeZone que envuelven zonas horarias de tipo 1 (desplazamiento UTC) y tipo 2 (abreviaturas) no contienen transiciones y llamar a este método sobre ellos devolverá `false`.

Si `timestampBegin` es proporcionado, la primera entrada en el array devuelto contendrá un elemento de transición al tiempo de `timestampBegin`.

Estructura de los arrays de transición
Clave | Tipo | Descripción
--- | --- | ---
`ts` | int | timestamp Unix
`time` | string | Cadena de tiempo `DateTimeInterface::ISO8601_EXPANDED` (PHP 8.2 y superior), o `DateTimeInterface::ISO8601` (PHP 8.1 e inferior)
`offset` | int | Desplazamiento horario hacia UTC en segundos
`isdst` | bool | Si la hora de verano está activada
`abbr` | string | Abreviatura de la zona horaria

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El valor predeterminado de `timestampEnd` se ha cambiado a 2147483647. Anteriormente, era `PHP_INT_MAX`.

### Ejemplos

Ejemplo #1 Ejemplo con timezone_transitions_get()

    <?php
    $timezone = new DateTimeZone("Europe/London");
    $transitions = $timezone->getTransitions();
    print_r(array_slice($transitions, 0, 3));
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [ts] => -2147483648
                [time] => 1901-12-13T20:45:52+00:00
                [offset] => -75
                [isdst] =>
                [abbr] => LMT
            )

        [1] => Array
            (
                [ts] => 442304971
                [time] => 1847-12-01T00:01:15+00:00
                [offset] => 0
                [isdst] =>
                [abbr] => GMT
            )

        [2] => Array
            (
                [ts] => -1691964000
                [time] => 1916-05-21T02:00:00+00:00
                [offset] => 3600
                [isdst] => 1
                [abbr] => BST
            )

    )

Ejemplo #2 Un ejemplo de timezone_transitions_get() con `timestampBegin` definido

    <?php
    $timezone = new DateTimeZone("Europe/London");
    $transitions = $timezone->getTransitions(time());
    print_r(array_slice($transitions, 0, 3));
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [ts] => 1759058251
                [time] => 2025-09-28T11:17:31+00:00
                [offset] => 3600
                [isdst] => 1
                [abbr] => BST
            )

        [1] => Array
            (
                [ts] => 1761440400
                [time] => 2025-10-26T01:00:00+00:00
                [offset] => 0
                [isdst] =>
                [abbr] => GMT
            )

        [2] => Array
            (
                [ts] => 1774746000
                [time] => 2026-03-29T01:00:00+00:00
                [offset] => 3600
                [isdst] => 1
                [abbr] => BST
            )

    )

# DateTimeZone::listAbbreviations

# timezone_abbreviations_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::listAbbreviations -- timezone_abbreviations_list — Devuelve un array asociativo que describe una zona horaria

### Descripción

Estilo orientado a objetos

public static function DateTimeZone::listAbbreviations(): array

Estilo procedimental

function timezone_abbreviations_list(): array

La lista de abreviaturas devuelta contiene todos los usos históricos de las abreviaturas, lo que puede dar lugar a entradas correctas, pero confusas. Asimismo, existen conflictos, ya que `PST` se utiliza tanto en Estados Unidos como en Filipinas.

La lista que devuelve esta función no es adecuada para construir un menú de opciones que presente una selección de zonas horarias a los usuarios.

> Nota:

> Los datos para esta función están precompilados por razones de rendimiento y no se actualizan al utilizar una » timezonedb más reciente.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el array de abreviaturas de zonas horarias.

### Ejemplos

Ejemplo #1 Ejemplo con timezone_abbreviations_list()

    <?php
    $timezone_abbreviations = DateTimeZone::listAbbreviations();
    print_r($timezone_abbreviations["acst"]);

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/Adelaide
            )

        [1] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/Broken_Hill
            )

        [2] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/Darwin
            )

        [3] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/North
            )

        [4] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/South
            )

        [5] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/Yancowinna
            )

    )

### Ver también

- timezone_identifiers_list() - Alias de DateTimeZone::listIdentifiers

# DateTimeZone::listIdentifiers

# timezone_identifiers_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::listIdentifiers -- timezone_identifiers_list — Devuelve un array numérico que contiene todos los identificadores de zonas horarias definidos

### Descripción

Estilo orientado a objetos

public static function DateTimeZone::listIdentifiers(int `$timezoneGroup` = `DateTimeZone::ALL`, ?string `$countryCode` = `null`): array

Estilo procedimental

function timezone_identifiers_list(int `$timezoneGroup` = `DateTimeZone::ALL`, ?string `$countryCode` = `null`): array

Devuelve la lista de » identificadores de zona horaria de IANA.

> Nota: Es posible detectar la zona horaria del cliente (navegador) con JavaScript usando » Intl.DateTimeFormat o » Temporal.ZonedDateTime.

### Parámetros

`timezoneGroup`

  Una (o una combinación) de las constantes de clase DateTimeZone.

`countryCode`

  Un código de país de dos letras (en mayúsculas), compatible con ISO 3166-1.

  > Nota: Esta opción solo está disponible cuando el argumento `timezoneGroup` toma el valor de `DateTimeZone::PER_COUNTRY`.

### Valores devueltos

Devuelve el array de identificadores de zonas horarias. Solo se devuelven los elementos no obsoletos. Para obtener todo, incluyendo los identificadores de zonas horarias obsoletos, utilice `DateTimeZone::ALL_WITH_BC` como valor para `timezoneGroup`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Anterior a esta versión, `false` se devolvía en caso de error.
7.1.0 | `countryCode` ahora es nullable.

### Ejemplos

Ejemplo #1 Lista de identificadores con comentarios de ubicación

    <?php
    $identifiers = DateTimeZone::listIdentifiers(DateTimeZone::ALL);

    foreach ($identifiers as $tzid) {
        $tz = new DateTimeZone($tzid);
        $comments = $tz->getLocation()['comments'];
        echo $tzid . " (" . ($comments ?: 'Toda la región') . ")\n";
    }

Resultado del ejemplo anterior es similar a:

    America/Antigua (Toda la región)
    America/Araguaina (Tocantins)
    America/Argentina/Buenos_Aires (Buenos Aires (BA, CF))
    America/Argentina/Catamarca (Catamarca (CT), Chubut (CH))
    America/Argentina/Cordoba (Argentina (most areas: CB, CC, CN, ER, FM, MN, SE, SF))
    // (Salida recortada debido a la longitud)

Ejemplo #2 Listar identificadores para una región específica

    <?php
    $timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::ASIA );
    for ($i=0; $i < 5; $i++) {
        echo "$timezone_identifiers[$i]\n";
    }

Resultado del ejemplo anterior es similar a:

    Asia/Aden
    Asia/Almaty
    Asia/Amman
    Asia/Anadyr
    Asia/Aqtau

Ejemplo #3 Listar identificadores de múltiples regiones

    <?php
    $timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::ASIA | DateTimeZone::PACIFIC );
    echo join( ', ', $timezone_identifiers );

Resultado del ejemplo anterior es similar a:

    Asia/Aden, Asia/Almaty, Asia/Amman, Asia/Anadyr, Asia/Aqtau, Asia/Aqtobe,
    Asia/Ashgabat, Asia/Atyrau, Asia/Baghdad, Asia/Bahrain, Asia/Baku,
    Asia/Bangkok, Asia/Barnaul, Asia/Beirut, Asia/Bishkek, Asia/Brunei,
    Asia/Chita, Asia/Choibalsan, Asia/Colombo, Asia/Damascus, Asia/Dhaka,
    Asia/Dili, Asia/Dubai, Asia/Dushanbe, Asia/Famagusta, Asia/Gaza, Asia/Hebron,
    Asia/Ho_Chi_Minh, Asia/Hong_Kong, Asia/Hovd, Asia/Irkutsk, Asia/Jakarta,
    Asia/Jayapura, Asia/Jerusalem, Asia/Kabul, Asia/Kamchatka, Asia/Karachi,
    Asia/Kathmandu, Asia/Khandyga, Asia/Kolkata, Asia/Krasnoyarsk,
    Asia/Kuala_Lumpur, Asia/Kuching, Asia/Kuwait, Asia/Macau, Asia/Magadan,
    Asia/Makassar, Asia/Manila, Asia/Muscat, Asia/Nicosia, Asia/Novokuznetsk,
    Asia/Novosibirsk, Asia/Omsk, Asia/Oral, Asia/Phnom_Penh, Asia/Pontianak,
    Asia/Pyongyang, Asia/Qatar, Asia/Qostanay, Asia/Qyzylorda, Asia/Riyadh,
    Asia/Sakhalin, Asia/Samarkand, Asia/Seoul, Asia/Shanghai, Asia/Singapore,
    Asia/Srednekolymsk, Asia/Taipei, Asia/Tashkent, Asia/Tbilisi, Asia/Tehran,
    Asia/Thimphu, Asia/Tokyo, Asia/Tomsk, Asia/Ulaanbaatar, Asia/Urumqi,
    Asia/Ust-Nera, Asia/Vientiane, Asia/Vladivostok, Asia/Yakutsk, Asia/Yangon,
    Asia/Yekaterinburg, Asia/Yerevan, Pacific/Apia, Pacific/Auckland,
    Pacific/Bougainville, Pacific/Chatham, Pacific/Chuuk, Pacific/Easter,
    Pacific/Efate, Pacific/Fakaofo, Pacific/Fiji, Pacific/Funafuti,
    Pacific/Galapagos, Pacific/Gambier, Pacific/Guadalcanal, Pacific/Guam,
    Pacific/Honolulu, Pacific/Kanton, Pacific/Kiritimati, Pacific/Kosrae,
    Pacific/Kwajalein, Pacific/Majuro, Pacific/Marquesas, Pacific/Midway,
    Pacific/Nauru, Pacific/Niue, Pacific/Norfolk, Pacific/Noumea,
    Pacific/Pago_Pago, Pacific/Palau, Pacific/Pitcairn, Pacific/Pohnpei,
    Pacific/Port_Moresby, Pacific/Rarotonga, Pacific/Saipan, Pacific/Tahiti,
    Pacific/Tarawa, Pacific/Tongatapu, Pacific/Wake, Pacific/Wallis

Ejemplo #4 Listar identificadores de un solo país

    <?php
    $timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::PER_COUNTRY, "UA" );
    foreach( $timezone_identifiers as $identifier ) {
        echo "$identifier\n";
    }

Resultado del ejemplo anterior es similar a:

    Europe/Kyiv
    Europe/Simferopol
    Europe/Uzhgorod
    Europe/Zaporozhye

### Ver también

- timezone_abbreviations_list() - Alias de DateTimeZone::listAbbreviations

## Tabla de contenidos

- DateTimeZone::__construct — Crea un nuevo objeto DateTimeZone
- DateTimeZone::getLocation — Devuelve las informaciones geográficas de una zona horaria
- DateTimeZone::getName — Devuelve el nombre de la zona horaria
- DateTimeZone::getOffset — Retorna el desplazamiento GMT de una zona horaria
- DateTimeZone::getTransitions — Devuelve todas las transiciones de una zona horaria
- DateTimeZone::listAbbreviations — Devuelve un array asociativo que describe una zona horaria
- DateTimeZone::listIdentifiers — Devuelve un array numérico que contiene todos los identificadores de zonas horarias definidos

# La clase DateInterval

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Introducción

Representa un intervalo de fechas.

Un intervalo de fechas almacena o bien una cantidad fija de instantes (en años, meses, días, horas, etc.) o bien una cadena con un instante relativo en el formato que admiten los constructores de DateTimeImmutable y DateTime.

Más especificamente, la información en un objeto de la clase DateInterval es una instrucción para llegar de un instante de fecha/hora a otro instante de fecha/hora. Este proceso no es siempre reversible.

Un modo común de crear un objeto DateInterval es calculando la diferencia entre dos objetos de fecha/hora a través de DateTimeInterface::diff().

Dado que no hay una forma bien definida de comparar intervalos de fechas, las instancias de DateInterval son incomparables.

## Sinopsis de la Clase

class DateInterval {
/* Propiedades */
public int $y;
public int $m;
public int $d;
public int $h;
public int $i;
public int $s;
public float $f;
public int $invert;
public mixed $days;
public bool $from_string;
public string $date_string;
/* Métodos */
public function __construct(string `$duration`)
public static function createFromDateString(string `$datetime`): DateInterval
public function format(string `$format`): string
}

## Propiedades

Advertencia

El listado de propiedades disponibles que se muestra a continuación depende de la versión de PHP, y deben considerarse como de solo lectura.

y

  Número de años.

m

  Número de meses.

d

  Número de días.

h

  Número de horas.

i

  Número de minutos.

s

  Número de segundos.

f

  Número de microsegundos, como fracción de un segundo.

invert

  Es `1` si el intervalo representa un periodo de tiempo negativo y `0` en caso contrario. Véase DateInterval::format().

days

  Si el objeto DateInterval fue creado por DateTimeImmutable::diff() o DateTime::diff(), entonces este es el número total de días completos entre las fechas de inicio y fin. En caso contrario, days será `false`.

from_string

  Si el objeto DateInterval fue creado por DateInterval::createFromDateString(), entonces esta propiedad tendrá el valor `true`, y será establecida la propiedad date_string. De lo contrario, el valor será `false`, y serán establecidas las propiedades y a f, invert, y days.

date_string

  La cadena usada como argumento en DateInterval::createFromDateString().

## Historial de cambios

Versión | Descripción
--- | ---
8.2.0 | Se han añadido las propiedades from_string y date_string para las instancias de DateInterval que fueron creadas usando el método DateInterval::createFromDateString().
8.2.0 | Solo las propiedades `y` a `f`, `invert`, y `days` serán visibles.
7.4.0 | Ahora las instancias de DateInterval son incomparables; anteriormente, todas las instancias de DateInterval se consideraban iguales.
7.1.0 | Se ha añadido la propiedad f.

# DateInterval::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::__construct — Crea un nuevo objeto DateInterval

### Descripción

public function DateInterval::__construct(string `$duration`)

Crea un nuevo objeto DateInterval.

### Parámetros

`duration`

  Una especificación de intervalo.

  El formato empieza con la letra `P`, de periodo. Cada periodo de duración está representado por un valor de tipo integer seguido de un indicador de periodo. Si la duración contiene elementos de hora, esa parte de la especificación estará precedida por una letra `T`.

  Indicadores de periodo de `duration`
  Indicador de periodo | Descripción
  --- | ---
  `Y` | años
  `M` | meses
  `D` | días
  `W` | semanas; estas se convierten a días, Antes de PHP 8.0.0, no se puede combinar con `D`.
  `H` | horas
  `M` | minutos
  `S` | segundos

  Algunos ejemplos sencillos: Dos días es `P2D`. Dos segundos es `PT2S`. Seis años y cinco minutos es `P6YT5M`.

  > Nota:

  > Los tipos de unidades deben ser escritos desde la unidad de escala más grande a la izquierda a la unidad de escala más pequeña a la derecha. Así los años van antes que los meses, meses antes que días, días antes que minutos, etc. Así un año y cuatro días debe representarse como `P1Y4D`, y no como `P4D1Y`.

  La especificación también puede ser representada como una fecha/hora. Un ejemplo de un año y cuatro días sería `P0001-00-04T00:00:00`. Pero los valores en este formato no pueden exceder el punto de desbordamiento de un periodo (p.ej. `25` horas no es válido).

  Estos formatos están basados en la » especificación de duración ISO 8601.

### Errores/Excepciones

Lanza una DateMalformedIntervalStringException cuando el `duration` no puede ser analizado como un intervalo. Antes de PHP 8.3, esto era Exception.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Ahora lanza DateMalformedIntervalStringException en lugar de Exception.
8.2.0 | Solo serán visibles las propiedades `y` a `f`, `invert` y `days`, incluyendo una nueva propiedad booleana `from_string`.
8.0.0 | `W` se puede combinar con `D`.

### Ejemplos

Ejemplo #1 Construyendo y usando objetos DateInterval

    <?php
    // Crea una fecha especifica
    $someDate = \DateTime::createFromFormat("Y-m-d H:i", "2022-08-25 14:18");

    // Crea un intervalo
    $interval = new \DateInterval("P7D");

    // Añade el intervalo
    $someDate->add($interval);

    // Convierte el intervalo a string
    echo $interval->format("%d");

El ejemplo anterior mostrará:

    7

Ejemplo #2 Ejemplo de DateInterval

    <?php
    $interval = new DateInterval('P1W2D');
    var_dump($interval);

Resultado del ejemplo anterior en PHP 8.2:

    object(DateInterval)#1 (10) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(0)
      ["d"]=>
      int(9)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["from_string"]=>
      bool(false)
    }

Resultado del ejemplo anterior en PHP 8:

    object(DateInterval)#1 (16) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(0)
      ["d"]=>
      int(9)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["weekday"]=>
      int(0)
      ["weekday_behavior"]=>
      int(0)
      ["first_last_day_of"]=>
      int(0)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["special_type"]=>
      int(0)
      ["special_amount"]=>
      int(0)
      ["have_weekday_relative"]=>
      int(0)
      ["have_special_relative"]=>
      int(0)
    }

Resultado del ejemplo anterior en PHP 7:

    object(DateInterval)#1 (16) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(0)
      ["d"]=>
      int(2)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["weekday"]=>
      int(0)
      ["weekday_behavior"]=>
      int(0)
      ["first_last_day_of"]=>
      int(0)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["special_type"]=>
      int(0)
      ["special_amount"]=>
      int(0)
      ["have_weekday_relative"]=>
      int(0)
      ["have_special_relative"]=>
      int(0)
    }

### Ver también

- DateInterval::format() - Formatea el intervalo
- DateTime::add() - Modifica un objeto DateTime, añadiendo una cantidad de días, meses, años, horas, minutos y segundos
- DateTime::sub() - Sustrae una cantidad de días, meses, años, horas, minutos y segundos de un objeto DateTime
- DateTime::diff() - Devuelve la diferencia entre dos objetos DateTime

# DateInterval::createFromDateString

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::createFromDateString — Establece un objeto DateInterval desde las partes relativas de una cadena

### Descripción

Estilo orientado a objetos

public static function DateInterval::createFromDateString(string `$datetime`): DateInterval

Estilo procedimental

function date_interval_create_from_date_string(string `$datetime`): DateInterval|false

Usas los analizadores de fecha/hora como los usados en el constructor de DateTimeImmutable para crear un DateInterval desde las partes relativas de la cadena analizada.

### Parámetros

`datetime`

  Una fecha con partes relativas. Específicamente, los formatos relativos admitidos por el analizador utilizados por DateTimeImmutable, DateTime, y strtotime() serán los empleados para construir el objeto DateInterval

  Para usar un string con formato ISO-8601 como `P7D`, debes usar DateInterval::__construct().

### Valores devueltos

Devuelve DateInterval en caso de éxito. Estilo procedimental retorna `false` en caso de error.

### Errores/Excepciones

Solo en la API Orientada a Objetos: Si se pasa una cadena de fecha/hora inválida, se lanza DateMalformedIntervalStringException.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Ahora tiene un tipo de retorno tentativo de DateInterval. Anteriormente era DateInterval|false.
8.3.0 | DateInterval::createFromDateString() ahora lanza DateMalformedIntervalStringException si se pasa una cadena inválida. Anteriormente, devolvía `false`, y emitía una advertencia. date_interval_create_from_date_string() no ha cambiado.
8.2.0 | Las propiedades `from_string` y `date_string` solo serán visibles cuando se crea un DateInterval con este método.

### Ejemplos

Ejemplo #1 Analizando intervalos de fechas válidos

    <?php
    // Cada conjunto de intervalos es equivalente.
    $i = new DateInterval('P1D');
    $i = DateInterval::createFromDateString('1 day');

    $i = new DateInterval('P2W');
    $i = DateInterval::createFromDateString('2 weeks');

    $i = new DateInterval('P3M');
    $i = DateInterval::createFromDateString('3 months');

    $i = new DateInterval('P4Y');
    $i = DateInterval::createFromDateString('4 years');

    $i = new DateInterval('P1Y1D');
    $i = DateInterval::createFromDateString('1 year + 1 day');

    $i = new DateInterval('P1DT12H');
    $i = DateInterval::createFromDateString('1 day + 12 hours');

    $i = new DateInterval('PT3600S');
    $i = DateInterval::createFromDateString('3600 seconds');

Ejemplo #2 Analizando combinaciones e intervalos negativos

    <?php
    $i = DateInterval::createFromDateString('62 weeks + 1 day + 2 weeks + 2 hours + 70 minutes');
    echo $i->format('%d %h %i'), "\n";

    $i = DateInterval::createFromDateString('1 year - 10 days');
    echo $i->format('%y %d'), "\n";

El ejemplo anterior mostrará:

    449 2 70
    1 -10

Ejemplo #3 Analizando intervalos de fechas relativas especiales

    <?php
    $i = DateInterval::createFromDateString('last day of next month');
    var_dump($i);

    $i = DateInterval::createFromDateString('last weekday');
    var_dump($i);

Resultado del ejemplo anterior en PHP 8.2:

    object(DateInterval)#1 (2) {
      ["from_string"]=>
      bool(true)
      ["date_string"]=>
      string(22) "last day of next month"
    }
    object(DateInterval)#2 (2) {
      ["from_string"]=>
      bool(true)
      ["date_string"]=>
      string(12) "last weekday"
    }

Resultado del ejemplo anterior en PHP 8 es similar a:

    object(DateInterval)#1 (16) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(1)
      ["d"]=>
      int(0)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["weekday"]=>
      int(0)
      ["weekday_behavior"]=>
      int(0)
      ["first_last_day_of"]=>
      int(2)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["special_type"]=>
      int(0)
      ["special_amount"]=>
      int(0)
      ["have_weekday_relative"]=>
      int(0)
      ["have_special_relative"]=>
      int(0)
    }
    object(DateInterval)#2 (16) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(0)
      ["d"]=>
      int(0)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["weekday"]=>
      int(0)
      ["weekday_behavior"]=>
      int(0)
      ["first_last_day_of"]=>
      int(0)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["special_type"]=>
      int(1)
      ["special_amount"]=>
      int(-1)
      ["have_weekday_relative"]=>
      int(0)
      ["have_special_relative"]=>
      int(1)
    }

# DateInterval::format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::format — Formatea el intervalo

### Descripción

public function DateInterval::format(string `$format`): string

Formatea el intervalo.

### Parámetros

`format`

  Los siguientes caracteres están reconocidos en el parámetro de cadena `format`. Cada carácter de formato debe ser prefijado con un signo de porcentaje (`%`).
  Carácter `format` | Descripción | Valores de ejemplo
  --- | --- | ---
  `%` | Literal `%` | `%`
  `Y` | Años, numérico, al menos 2 dígitos con 0 a la izquierda | `01`, `03`
  `y` | Años, numérico | `1`, `3`
  `M` | Meses, numérico, al menos 2 dígitos con 0 a la izquierda | `01`, `03`, `12`
  `m` | Meses, numérico | `1`, `3`, `12`
  `D` | Días, numérico, al menos 2 dígitos con 0 a la izquierda | `01`, `03`, `31`
  `d` | Días, numérico | `1`, `3`, `31`
  `a` | Número total de días como resultado de una operación con DateTime::diff(), o de lo contrario `(unknown)` | `4`, `18`, `8123`
  `H` | Horas, numérico, al menos 2 dígitos con 0 a la izquierda | `01`, `03`, `23`
  `h` | Horas, numérico | `1`, `3`, `23`
  `I` | Minutos, numérico, al menos 2 dígitos con 0 a la izquierda | `01`, `03`, `59`
  `i` | Minutos, numérico | `1`, `3`, `59`
  `S` | Segundos, numérico, al menos 2 dígitos con 0 a la izquierda | `01`, `03`, `57`
  `s` | Segundos, numérico | `1`, `3`, `57`
  `F` | Microsegundos, numérico, al menos 6 dígitos con 0 a la izquierda 0 | `007701`, `052738`, `428291`
  `f` | Microsegundos, numérico | `7701`, `52738`, `428291`
  `R` | Signo "`-`" cuando es negativo, "`+`" cuando es positivo | `-`, `+`
  `r` | Signo "`-`" cuando es negativo, vacío cuando es positivo | `-`, ``

### Valores devueltos

Devuelve el intervalo formateado.

### Historial de cambios

Versión | Descripción
--- | ---
7.2.12 | Los caracteres de formato `F` y `f` ahora siempre serán positivos.
7.1.0 | Se han añadido los caracteres de formato `F` y `f`.

### Ejemplos

Ejemplo #1 Ejemplo de DateInterval

    <?php
    $interval = new DateInterval('P2Y4DT6H8M');
    echo $interval->format('%d days');

El ejemplo anterior mostrará:

    4 days

Ejemplo #2 DateInterval y excesos

    <?php
    $interval = new DateInterval('P32D');
    echo $interval->format('%d days');

El ejemplo anterior mostrará:

    32 days

Ejemplo #3 DateInterval y DateTime::diff() con los modificadores %a y %d

    <?php
    $january = new DateTime('2010-01-01');
    $february = new DateTime('2010-02-01');
    $interval = $february->diff($january);

    // %a imprimirá el múmero total de días.
    echo $interval->format('%a total days')."\n";

    // Mientras que %d sólo imprimirá el múmero total de días no cubiertos por el
    // mes.
    echo $interval->format('%m month, %d days');

El ejemplo anterior mostrará:

    31 total days
    1 month, 0 days

### Notas

> Nota:

> El método DateInterval::format() no recalcula los desbordamientos en los strings de tiempo ni en los segmentos de fecha. Esto se espera porque no es posible desbordar valores como `"32 días"` que podrían interpretarse en algo como, desde `"1 mes y 4 días"` hasta `"1 mes y 1 día"`.

### Ver también

- DateTime::diff() - Devuelve la diferencia entre dos objetos DateTime

## Tabla de contenidos

- DateInterval::__construct — Crea un nuevo objeto DateInterval
- DateInterval::createFromDateString — Establece un objeto DateInterval desde las partes relativas de una cadena
- DateInterval::format — Formatea el intervalo

# La clase DatePeriod

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Introducción

Representa un período de fechas.

Un período de fechas permite iterar a través de un conjunto de fechas y horas, ocurriendo a intervalos regulares, durante un período determinado.

## Sinopsis de la Clase

class DatePeriod implements IteratorAggregate {
/* Constantes */
public const int EXCLUDE_START_DATE;
public const int INCLUDE_END_DATE;
/* Propiedades */
public readonly ?DateTimeInterface $start;
public readonly ?DateTimeInterface $current;
public readonly ?DateTimeInterface $end;
public readonly ?DateInterval $interval;
public readonly int $recurrences;
public readonly bool $include_start_date;
public readonly bool $include_end_date;
/* Métodos */
public function __construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
int `$recurrences`,
int `$options` = 0
)
public function __construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
DateTimeInterface `$end`,
int `$options` = 0
)
public function __construct(string `$isostr`, int `$options` = 0)
public static function createFromISO8601String(string `$specification`, int `$options` = 0): static
public function getDateInterval(): DateInterval
public function getEndDate(): ?DateTimeInterface
public function getRecurrences(): ?int
public function getStartDate(): DateTimeInterface
}

## Constantes predefinidas

`DatePeriod::EXCLUDE_START_DATE` int

  Excluye la fecha de inicio, utilizada por DatePeriod::__construct().

`DatePeriod::INCLUDE_END_DATE` int

  Incluye la fecha de fin, utilizada por DatePeriod::__construct().

## Propiedades

recurrences

  La cantidad mínima de instancias devueltas por el iterador.

  Si el número de recurrencias ha sido explícitamente pasado mediante el argumento `$recurrences` en el constructor de la instancia DatePeriod, entonces esta propiedad contiene ese valor, más uno si la fecha de inicio no ha sido desactivada por `DatePeriod::EXCLUDE_START_DATE`, más uno si la fecha de fin ha sido activada por `DatePeriod::INCLUDE_END_DATE`.

  Si el número de recurrencias no ha sido explícitamente pasado, entonces esta propiedad contiene el número mínimo de instancias devueltas. Esto sería `0`, más uno si la fecha de inicio no ha sido desactivada por `DatePeriod::EXCLUDE_START_DATE`, más uno si la fecha de fin ha sido activada por `DatePeriod::INCLUDE_END_DATE`.

      <?php
      $start = new DateTime('2018-12-31 00:00:00');
      $end   = new DateTime('2021-12-31 00:00:00');
      $interval = new DateInterval('P1M');
      $recurrences = 5;

      // recurrencias explícitamente definidas por el constructor
      $period = new DatePeriod($start, $interval, $recurrences, DatePeriod::EXCLUDE_START_DATE);
      echo $period->recurrences, "\n";

      $period = new DatePeriod($start, $interval, $recurrences);
      echo $period->recurrences, "\n";

      $period = new DatePeriod($start, $interval, $recurrences, DatePeriod::INCLUDE_END_DATE);
      echo $period->recurrences, "\n";

      // recurrencias no definidas en el constructor
      $period = new DatePeriod($start, $interval, $end);
      echo $period->recurrences, "\n";

      $period = new DatePeriod($start, $interval, $end, DatePeriod::EXCLUDE_START_DATE);
      echo $period->recurrences, "\n";

  El ejemplo anterior mostrará:

      5
      6
      7
      1
      0

  Ver también DatePeriod::getRecurrences().

include_end_date

  Incluye o no la fecha de fin en el conjunto de fechas recurrentes.

include_start_date

  Si se debe incluir la fecha de inicio en el conjunto de fechas recurrentes o no.

start

  La fecha de inicio del período.

current

  Durante la iteración, esto contendrá la fecha del día en el período.

end

  La fecha de fin del período.

interval

  Una especificación de intervalo repetitivo ISO 8601.

## Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Las constantes de clase ahora están tipadas.
8.2.0 | La constante `DatePeriod::INCLUDE_END_DATE` y la propiedad include_end_date han sido añadidas.
8.0.0 | La clase DatePeriod ahora implementa IteratorAggregate. Anteriormente, solo Traversable era implementada.

# DatePeriod::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DatePeriod::__construct — Crea un nuevo objeto DatePeriod

### Descripción

public function DatePeriod::__construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
int `$recurrences`,
int `$options` = 0
)
public function DatePeriod::__construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
DateTimeInterface `$end`,
int `$options` = 0
)
Advertencia

La siguiente variante del constructor ha quedado obsoleta:

public function DatePeriod::__construct(string `$isostr`, int `$options` = 0)

Esta variante del constructor ha quedado obsoleta a partir de PHP 8.4.0, utiliza DatePeriod::createFromISO8601String() en su lugar.

Crea un nuevo objeto DatePeriod.

Los objetos DatePeriod pueden ser utilizados como iterador para generar un cierto número de objetos DateTimeImmutable o DateTime a partir de una `start` fecha (fecha de inicio), un `interval`, y una `end` fecha (fecha de fin) o del número de `recurrences`.

La clase de los objetos devueltos es equivalente a la clase ancestro DateTimeImmutable o DateTime proporcionada por el objeto `start`.

### Parámetros

`start`

  La fecha de inicio del período. Incluida por omisión en el conjunto de resultados.

`interval`

  El intervalo entre las recurrencias del período.

`recurrences`

  El número de recurrencias. Debe ser mayor que `0`. El número de resultados devueltos es superior en una unidad, ya que la fecha de inicio está incluida en el conjunto de resultados por omisión.

`end`

  La fecha de fin del período. No incluida por omisión en el conjunto de resultados.

`isostr`

  Un subconjunto de la » especificación ISO 8601 de la repetición del intervalo.

  Ejemplos de algunas funcionalidades de especificación de intervalo ISO 8601 que PHP no soporta:

  1. Las ocurrencias cero (`R0/`)
  2. Desplazamientos horarios distintos de UTC (`Z`), tales como `+02:00`.
`options`

  Un campo de bits que puede ser utilizado para controlar ciertos comportamientos con las fechas de inicio y fin.

  Puede ser configurado a `DatePeriod::EXCLUDE_START_DATE` para excluir la fecha de inicio del conjunto de fechas de recursión en el período.

  Puede ser configurado a `DatePeriod::INCLUDE_END_DATE` para incluir la fecha de fin del conjunto de fechas de recursión en el período.

### Errores/Excepciones

Lanza una excepción DateMalformedPeriodStringException cuando el argumento `isostr` no puede ser analizado como una cadena de período ISO 8601 válida. Anteriormente a PHP 8.3, esto era una Exception.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | La firma que utiliza `isostr` ha quedado obsoleta, utiliza DatePeriod::createFromISO8601String() en su lugar.
8.3.0 | Ahora lanza una DateMalformedPeriodStringException en lugar de Exception.
8.2.0 | Se ha añadido la constante `DatePeriod::INCLUDE_END_DATE`.
7.2.19, 7.3.6, 7.4.0 | `recurrences` ahora debe ser mayor que `0`.

### Ejemplos

Ejemplo #1 Ejemplo con DatePeriod

    <?php
    $start = new DateTime('2012-07-01');
    $interval = new DateInterval('P7D');
    $end = new DateTime('2012-07-31');
    $recurrences = 4;
    $iso = 'R4/2012-07-01T00:00:00Z/P7D';

    // Todas estas fechas son equivalentes.
    $period = new DatePeriod($start, $interval, $recurrences);
    $period = new DatePeriod($start, $interval, $end);
    $period = new DatePeriod($iso);

    // Al recorrer el objeto DatePeriod, todas las
    // fechas de recursión para el período serán mostradas.
    foreach ($period as $date) {
        echo $date->format('Y-m-d')."\n";
    }

El ejemplo anterior mostrará:

    Deprecated: Calling DatePeriod::__construct(string $isostr, int $options = 0) is deprecated, use DatePeriod::createFromISO8601String() instead in script on line 11
    2012-07-01
    2012-07-08
    2012-07-15
    2012-07-22
    2012-07-29

Ejemplo #2 Ejemplo con DatePeriod y `DatePeriod::EXCLUDE_START_DATE`

    <?php
    $start = new DateTime('2012-07-01');
    $interval = new DateInterval('P7D');
    $end = new DateTime('2012-07-31');

    $period = new DatePeriod($start, $interval, $end,
                             DatePeriod::EXCLUDE_START_DATE);

    // Al recorrer el objeto DatePeriod,
    // todas las fechas de recursión para el período son mostradas.
    // Tenga en cuenta que, en este caso, 2012-07-01 no será mostrada.
    foreach ($period as $date) {
        echo $date->format('Y-m-d')."\n";
    }

El ejemplo anterior mostrará:

    2012-07-08
    2012-07-15
    2012-07-22
    2012-07-29

Ejemplo #3 DatePeriod mostrando todos los últimos jueves del mes durante un año

    <?php
    $begin = new DateTime('2021-12-31');
    $end = new DateTime('2022-12-31 23:59:59');

    $interval = DateInterval::createFromDateString('last thursday of next month');
    $period = new DatePeriod($begin, $interval, $end, DatePeriod::EXCLUDE_START_DATE);

    foreach ($period as $dt) {
        echo $dt->format('l Y-m-d'), "\n";
    }

El ejemplo anterior mostrará:

    Thursday 2022-01-27
    Thursday 2022-02-24
    Thursday 2022-03-31
    Thursday 2022-04-28
    Thursday 2022-05-26
    Thursday 2022-06-30
    Thursday 2022-07-28
    Thursday 2022-08-25
    Thursday 2022-09-29
    Thursday 2022-10-27
    Thursday 2022-11-24
    Thursday 2022-12-29

### Notas

Los números de repetición no vinculados especificados en la sección 4.5 "Intervalo de tiempo recurrente" de la norma ISO 8601 no son soportados, es decir, ni `"R/..."` como `isostr` ni `null` como `end` funcionaría.

# DatePeriod::createFromISO8601String

(PHP 8 >= 8.3.0)

DatePeriod::createFromISO8601String — Crea un nuevo objeto DatePeriod a partir de un string ISO8601

### Descripción

public static function DatePeriod::createFromISO8601String(string `$specification`, int `$options` = 0): static

Crea un nuevo objeto DatePeriod a partir de un string ISO8601, tal como se especifica con `specification`.

### Parámetros

`specification`

  Un subconjunto de la especificación » ISO 8601 de intervalos recurrentes.

  Un ejemplo de especificación de intervalo ISO 8601 aceptada es `R5/2008-03-01T13:00:00Z/P1Y2M10DT2H30M`, que especifica :

  - 5 iteraciones (`R5/`)
  - Comienza en `2008-03-01T13:00:00Z`.
  - Cada iteración es un intervalo de 1 año, 2 meses, 10 días, 2 horas y 30 minutos (`/P1Y2M10DT2H30M`).

  Los ejemplos de algunas funcionalidades de especificación de intervalo ISO 8601 que PHP no soporta son :

  1. cero ocurrencias (`R0/`)
  2. desplazamientos horarios distintos de UTC (`Z`), como `+02:00`.
`options`

  Un campo de bits que puede ser utilizado para controlar ciertos comportamientos con las fechas de inicio y fin.

  Con `DatePeriod::EXCLUDE_START_DATE` se excluye la fecha de inicio del conjunto de fechas recurrentes en el período.

  Con `DatePeriod::INCLUDE_END_DATE` se incluye la fecha de fin en el conjunto de fechas recurrentes en el período.

### Valores devueltos

Crea un nuevo objeto DatePeriod.

Los objetos DatePeriod creados con este método pueden ser utilizados como un iterador para generar un cierto número de objetos DateTimeImmutable.

### Errores/Excepciones

Lanza una DateMalformedPeriodStringException cuando la `specification` no puede ser analizada como un intervalo ISO 8601 válido.

### Ejemplos

Ejemplo #1 Ejemplo de DatePeriod::createFromISO8601String

    <?php
    $iso = 'R4/2023-07-01T00:00:00Z/P7D';
    $period = DatePeriod::createFromISO8601String($iso);

    // Al iterar sobre el objeto DatePeriod, todas las
    // fechas recurrentes en este período son mostradas.
    foreach ($period as $date) {
        echo $date->format('Y-m-d'), "\n";
    }

El ejemplo anterior mostrará:

    2023-07-01
    2023-07-08
    2023-07-15
    2023-07-22
    2023-07-29

# DatePeriod::getDateInterval

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getDateInterval — Devuelve el intervalo

### Descripción

Estilo orientado a objetos

public function DatePeriod::getDateInterval(): DateInterval

Devuelve un DateInterval object que representa el intervalo utilizado para el período.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un DateInterval object

### Ejemplos

Ejemplo #1 Ejemplo con DatePeriod::getDateInterval()

    <?php
    $period = DatePeriod::createFromIso8601String('R7/2016-05-16T00:00:00Z/P1D');
    $interval = $period->getDateInterval();
    echo $interval->format('%d day');

El ejemplo anterior mostrará:

    1 day

### Ver también

- DatePeriod::getStartDate() - Obtiene la fecha de inicio
- DatePeriod::getEndDate() - Devuelve la fecha de fin

# DatePeriod::getEndDate

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getEndDate — Devuelve la fecha de fin

### Descripción

Estilo orientado a objetos

public function DatePeriod::getEndDate(): ?DateTimeInterface

Devuelve la fecha de fin del período.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `null` si la DatePeriod no tiene fecha de fin. Por ejemplo, cuando se inicializa con el argumento `recurrences`, o con el argumento `isostr` sin fecha de fin.

Retorna un object DateTimeImmutable cuando la DatePeriod se inicializa con un object DateTimeImmutable como argumento `end`.

Devuelve un object DateTime clonado que representa la fecha de fin en caso contrario.

### Ejemplos

Ejemplo #1 Ejemplos con DatePeriod::getEndDate()

    <?php
    $period = new DatePeriod(
        new DateTime('2016-05-16T00:00:00Z'),
        new DateInterval('P1D'),
        new DateTime('2016-05-20T00:00:00Z')
    );
    $start = $period->getEndDate();
    echo $start->format(DateTime::ISO8601);

Los ejemplos anteriores mostrarán:

    2016-05-20T00:00:00+0000

Ejemplo #2 DatePeriod::getEndDate() sin fecha de fin

    <?php
    $period = new DatePeriod(
        new DateTime('2016-05-16T00:00:00Z'),
        new DateInterval('P1D'),
        7
    );
    var_dump($period->getEndDate());

El ejemplo anterior mostrará:

    NULL

### Ver también

- DatePeriod::getStartDate() - Obtiene la fecha de inicio
- DatePeriod::getDateInterval() - Devuelve el intervalo

# DatePeriod::getRecurrences

(PHP 7 >= 7.2.17/7.3.4, PHP 8)

DatePeriod::getRecurrences — Recupera el número de recurrencias

### Descripción

Estilo orientado a objetos

public function DatePeriod::getRecurrences(): ?int

Recupera el número de recurrencias.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El número de recurrencias se define pasando explícitamente las `$recurrences` al constructor de la clase DatePeriod, de lo contrario se define como `null`.

### Ejemplos

Ejemplo #1 Valores diferentes para DatePeriod::getRecurrences()

    <?php
    $start = new DateTime('2018-12-31 00:00:00');
    $end   = new DateTime('2021-12-31 00:00:00');
    $interval = new DateInterval('P1M');
    $recurrences = 5;
    // recurrencias definidas explícitamente a través del constructor
    $period = new DatePeriod($start, $interval, $recurrences, DatePeriod::EXCLUDE_START_DATE);
    echo $period->getRecurrences(), "\n";

    $period = new DatePeriod($start, $interval, $recurrences);
    echo $period->getRecurrences(), "\n";

    $period = new DatePeriod($start, $interval, $recurrences, DatePeriod::INCLUDE_END_DATE);
    echo $period->getRecurrences(), "\n\n";

    // recurrencias no definidas en el constructor
    $period = new DatePeriod($start, $interval, $end);
    var_dump($period->getRecurrences());

    $period = new DatePeriod($start, $interval, $end, DatePeriod::EXCLUDE_START_DATE);
    var_dump($period->getRecurrences());

El ejemplo anterior mostrará:

    5
    5
    5

    NULL
    NULL

### Ver también

- DatePeriod::$recurrences

# DatePeriod::getStartDate

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getStartDate — Obtiene la fecha de inicio

### Descripción

Estilo orientado a objetos

public function DatePeriod::getStartDate(): DateTimeInterface

Obtiene la fecha de inicio de un período.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un object DateTimeImmutable cuando la DatePeriod se inicializa con un object DateTimeImmutable como argumento `start`.

Devuelve un object DateTime en los demás casos.

### Ejemplos

Ejemplo #1 Ejemplo DatePeriod::getStartDate()

    <?php
    $period = DatePeriod::createFromIso8601String('R7/2016-05-16T00:00:00Z/P1D');
    $start = $period->getStartDate();
    echo $start->format(DateTime::ISO8601);

El ejemplo anterior mostrará:

    2016-05-16T00:00:00+0000

### Ver también

- DatePeriod::getEndDate() - Devuelve la fecha de fin
- DatePeriod::getDateInterval() - Devuelve el intervalo

## Tabla de contenidos

- DatePeriod::__construct — Crea un nuevo objeto DatePeriod
- DatePeriod::createFromISO8601String — Crea un nuevo objeto DatePeriod a partir de un string ISO8601
- DatePeriod::getDateInterval — Devuelve el intervalo
- DatePeriod::getEndDate — Devuelve la fecha de fin
- DatePeriod::getRecurrences — Recupera el número de recurrencias
- DatePeriod::getStartDate — Obtiene la fecha de inicio

# Funciones de Fecha/Hora

# checkdate

(PHP 4, PHP 5, PHP 7, PHP 8)

checkdate — Valida una fecha gregoriana

### Descripción

function checkdate(int `$month`, int `$day`, int `$year`): bool

Comprueba la validez de una fecha formada por los argumentos. Una fecha se considera válida si cada parámetro está propiamente definido.

### Parámetros

`month`

  El mes entre 1 y 12 inclusive.

`day`

  El día que está dentro del número de días del mes `month` dado. Los años `year` bisiestos son tomados en consideración.

`year`

  El año entre 1 y 32767 inclusive.

### Valores devueltos

Devuelve `true` si la fecha dada es válida, si no, devuelve `false`.

### Ejemplos

Ejemplo #1 Ejemplo de checkdate()

    <?php
    var_dump(checkdate(12, 31, 2000));
    var_dump(checkdate(2, 29, 2001));

El ejemplo anterior mostrará:

    bool(true)
    bool(false)

### Ver también

- mktime() - Obtener la marca de tiempo Unix de una fecha
- strtotime() - Transforma un texto inglés en timestamp

# date

(PHP 4, PHP 5, PHP 7, PHP 8)

date — Da formato a una marca de tiempo de Unix (Unix timestamp)

### Descripción

function date(string `$format`, ?int `$timestamp` = `null`): string

Devuelve una cadena formateada según el formato indicado usando el integer `timestamp` (Unix timestamp) dado, o el momento actual si no se da una marca de tiempo. En otras palabras, `timestamp` es opcional y por defecto es el valor de time().

Advertencia

Las marcas de tiempo de Unix no manejan zonas horarias. Usa la clase DateTimeImmutable, y su método DateTimeInterface::format() para formatear fecha/hora incluyendo la información de zona horaria.

### Parámetros

`format`

  Formato aceptado por DateTimeInterface::format().

  > Nota: date() generará siempre `000000` como microsegundos ya que toma un tipo int como parámetro, mientras que DateTimeInterface::format() soporta microsegundos, si el objeto del tipo DateTimeInterface es creado con microsegundos.

`timestamp`
  El parámetro opcional `timestamp` es un timestamp Unix de tipo int que por omisión es la hora actual local si `timestamp` es omitido o `null`. En otras palabras, es por omisión el valor de la función time().

### Valores devueltos

Devuelve una cadena de fecha formateada.

### Errores/Excepciones

Cada llamada a una función de fecha/hora generará un diagnóstico de tipo `E_WARNING` si la zona horaria no es válida. Ver también date_default_timezone_set()

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `timestamp` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplos de date()

    <?php
    // Establecer la zona horaria por omisión
    date_default_timezone_set('UTC');

    // Imprime algo como: Monday
    echo date("l") . "\n";

    // Imprime algo como: Monday 8th of August 2005 03:12:46 PM
    echo date('l jS \of F Y h:i:s A') . "\n";

    // Imprime: 1 de julio de 2000 cae en sábado
    echo "1 de julio de 2000 cae en " . date("l", mktime(0, 0, 0, 7, 1, 2000)) . "\n";

    /* Usar las constantes en el parámetro de formato */
    // Imprime algo como: Wed, 25 Sep 2013 15:28:57 -0700
    echo date(DATE_RFC2822) . "\n";

    // Imprime algo como: 2000-07-01T00:00:00+00:00
    echo date(DATE_ATOM, mktime(0, 0, 0, 7, 1, 2000));

Puede prevenir que un carácter reconocido en la cadena de formato sea expandido escapándolo con una barra invertida precedente. Si el carácter con una barra invertida es ya una secuencia especial, necesitará escapar también la barra invertida.

Ejemplo #2 Escapando caracteres en date()

    <?php
    // Imprime algo como: Wednesday the 15th
    echo date('l \t\h\e jS');

Algunos ejemplos de formatear date(). Observe que debería escapar cualesquiera otros caracteres, ya que cualquiera que tenga actualmente un significado especial producirá resultados no deseados, y a otros caracteres se les pueden asignar significado en futuras versiones de PHP. Cuando se escapa un carácter, asegúrese de usar comillas simples para prevenir que caracteres como \n se conviertan en nuevas líneas.

Ejemplo #3 Dando formato con date()

    <?php
    // Asumiendo que hoy es 10 de marzo de 2001, 5:16:18 pm, y que estamos en la
    // zona horaria Mountain Standard Time (MST)
    date_default_timezone_set("America/Phoenix");

    echo date("F j, Y, g:i a") . "\n";                 // March 10, 2001, 5:16 pm
    echo date("m.d.y") . "\n";                         // 03.10.01
    echo date("j, n, Y") . "\n";                       // 10, 3, 2001
    echo date("Ymd") . "\n";                           // 20010310
    echo date('h-i-s, j-m-y, it is w Day') . "\n";     // 05-16-18, 10-03-01, 1631 1618 6 Satpm01
    echo date('\i\t \i\s \t\h\e jS \d\a\y.') . "\n";   // es el día 10.
    echo date("D M j G:i:s T Y") . "\n";               // Sat Mar 10 17:16:18 MST 2001
    echo date('H:m:s \m \i\s\ \m\o\n\t\h') . "\n";     // 17:03:18 m es el mes
    echo date("H:i:s") . "\n";                         // 17:16:18
    echo date("Y-m-d H:i:s") . "\n";                   // 2001-03-10 17:16:18 (el formato DATETIME de MySQL)

Para formatear fechas en otros lenguajes, debería usar IntlDateFormatter::format() en vez de date().

### Notas

> Nota:

> Para generar una marca de tiempo desde una cadena que representa la fecha, puede usar strtotime(). Además, algunas bases de datos tienen funciones para convertir formatos de fecha en marcas de tiempo (como la función » UNIX_TIMESTAMP de MySQL).

Sugerencia

La marca de tiempo del inicio de una petición está disponible en $_SERVER['REQUEST_TIME'].

### Ver también

- DateTimeImmutable::__construct() - Devuelve un nuevo objeto DateTimeImmutable
- DateTimeInterface::format() - Retorna una fecha formateada según el formato proporcionado
- gmdate() - Formatea una fecha/hora GMT/TUC
- idate() - Formatea una parte de la hora/fecha local como un entero
- getdate() - Devuelve la fecha/hora
- getlastmod() - Devuelve la fecha de última modificación de la página
- mktime() - Obtener la marca de tiempo Unix de una fecha
- IntlDateFormatter::format() - Formatea la fecha y la hora como string
- time() - Devuelve el timestamp UNIX actual
- Constantes Predefinidas de DateTime

# date_add

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_add — Alias de DateTime::add()

### Descripción

Esta función es un alias de: DateTime::add()

# date_create

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_create — Creación de un objeto DateTime

### Descripción

function date_create(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`): DateTime|false

Versión procedimental de DateTime::__construct()

A diferencia del constructor de DateTime, devolverá `false` en lugar de una excepción si la cadena `datetime` no es válida.

### Parámetros

Ver DateTimeImmutable::__construct.

### Valores devueltos

Devuelve una nueva instancia DateTime o `false` si ocurre un error

### Ver también

- DateTimeImmutable::__construct() - Devuelve un nuevo objeto DateTimeImmutable
- DateTimeImmutable::createFromFormat() - Analiza un string de tiempo según el formato especificado
- DateTime::__construct() - Devuelve un nuevo objeto DateTime

# date_create_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_create_from_format — Alias de DateTime::createFromFormat()

### Descripción

Esta función es un alias de: DateTime::createFromFormat()

# date_create_immutable

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

date_create_immutable — Crea un nuevo objeto DateTimeImmutable

### Descripción

function date_create_immutable(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

Versión procedimental de DateTimeImmutable::__construct().

A diferencia del constructor de DateTimeImmutable, esta función devolverá `false` en lugar de una excepción si la cadena `datetime` proporcionada no es válida.

### Parámetros

Ver DateTimeImmutable::__construct.

### Valores devueltos

Devuelve una nueva instancia DateTimeImmutable o `false` si ocurre un error

### Ver también

- DateTimeImmutable::createFromFormat() - Analiza un string de tiempo según el formato especificado

# date_create_immutable_from_format

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

date_create_immutable_from_format — Alias de DateTimeImmutable::createFromFormat()

### Descripción

Esta función es un alias de: DateTimeImmutable::createFromFormat()

# date_date_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_date_set — Alias de DateTime::setDate()

### Descripción

Esta función es un alias de: DateTime::setDate()

# date_default_timezone_get

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

date_default_timezone_get — Recupera el huso horario por defecto utilizado por todas las funciones de fecha/hora de un script

### Descripción

function date_default_timezone_get(): string

Esta función devuelve el huso horario siguiendo el siguiente orden de preferencia:

- Lectura del huso horario definido utilizando la función date_default_timezone_set() (si existe)

- Lectura del valor de la opción de configuración date.timezone (si está definida)

Si todo lo anterior falla, date_default_timezone_get() devolverá el huso horario por defecto de `UTC`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un string.

### Ejemplos

Ejemplo #1 Recuperación del huso horario por defecto

    <?php
    date_default_timezone_set('Europe/London');

    if (date_default_timezone_get()) {
        echo 'date_default_timezone_set: ' . date_default_timezone_get() . "\n";
    }

    if (ini_get('date.timezone')) {
        echo 'date.timezone : ' . ini_get('date.timezone');
    }

Resultado del ejemplo anterior es similar a:

    date_default_timezone_set : Europe/London
    date.timezone : Europe/London

Ejemplo #2 Recuperación de la abreviatura de un huso horario

    <?php
    date_default_timezone_set('America/Los_Angeles');
    echo date_default_timezone_get() . ' => ' . date('e') . ' => ' . date('T');

El ejemplo anterior mostrará:

    America/Los_Angeles => America/Los_Angeles => PST

### Ver también

- date_default_timezone_set() - Establece la zona horaria por defecto para todas las funciones de fecha/hora
- Lista de Zonas Horarias Soportadas

# date_default_timezone_set

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

date_default_timezone_set — Establece la zona horaria por defecto para todas las funciones de fecha/hora

### Descripción

function date_default_timezone_set(string `$timezoneId`): bool

La función date_default_timezone_set() establece la zona horaria por defecto utilizada por todas las funciones de fecha/hora.

En lugar de utilizar esta función para establecer la zona horaria por defecto en su script, también puede utilizarse la configuración INI date.timezone.

### Parámetros

`timezoneId`

  El identificador de zona horaria, como `UTC`, `Africa/Lagos`, `Asia/Hong_Kong`, o `Europe/Lisbon`. La lista de identificadores válidos está disponible en el Lista de Zonas Horarias Soportadas.

### Valores devueltos

Esta función devuelve `false` si `timezoneId` no es válido, `true` en caso contrario.

### Ejemplos

Ejemplo #1 Obtención de la zona horaria por defecto

    <?php
    date_default_timezone_set('America/Los_Angeles');

    $script_tz = date_default_timezone_get();
    $ini_tz = ini_get('date.timezone');

    if (strcmp($script_tz, $ini_tz)){
        echo 'La zona horaria del script difiere de la zona horaria definida en el archivo ini.';
    } else {
        echo 'La zona horaria del script es equivalente a la definida en el archivo ini.';
    }

### Ver también

- date_default_timezone_get() - Recupera el huso horario por defecto utilizado por todas las funciones de fecha/hora de un script
- Lista de Zonas Horarias Soportadas

# date_diff

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_diff — Alias de DateTime::diff()

### Descripción

Esta función es un alias de: DateTime::diff()

# date_format

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_format — Alias de DateTime::format()

### Descripción

Esta función es un alias de: DateTime::format()

# date_get_last_errors

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_get_last_errors — Alias de DateTimeImmutable::getLastErrors()

### Descripción

Esta función es un alias de: DateTimeImmutable::getLastErrors()

# date_interval_create_from_date_string

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_interval_create_from_date_string — Alias de DateInterval::createFromDateString()

### Descripción

Esta función es un alias de: DateInterval::createFromDateString()

# date_interval_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_interval_format — Alias de DateInterval::format()

### Descripción

Esta función es un alias de: DateInterval::format()

# date_isodate_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_isodate_set — Alias de DateTime::setISODate()

### Descripción

Esta función es un alias de: DateTime::setISODate()

# date_modify

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_modify — Alias de DateTime::modify()

### Descripción

Esta función es un alias de: DateTime::modify()

# date_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_offset_get — Alias de DateTime::getOffset()

### Descripción

Esta función es un alias de: DateTime::getOffset()

# date_parse

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_parse — Retorna un array asociativo con información detallada sobre una fecha/hora dada

### Descripción

function date_parse(string `$datetime`): array

date_parse() analiza la cadena `datetime` dada según las mismas reglas strtotime() y DateTimeImmutable::__construct(). En lugar de devolver un timestamp Unix (con strtotime()) o un objeto DateTimeImmutable (con DateTimeImmutable::__construct()), devuelve un array asociativo con la información que podría detectar en la cadena `datetime` dada.

Si no se puede encontrar información sobre un cierto grupo de elementos, estos elementos del array serán definidos como `false` o estarán ausentes. Si es necesario para construir un timestamp o un objeto DateTimeImmutable a partir de la misma cadena `datetime`, varios campos pueden ser definidos con un valor no-`false`. Ver los ejemplos a continuación para los casos en que esto ocurre.

### Parámetros

`datetime`

  Fecha/hora en un formato aceptado por DateTimeImmutable::__construct().

### Valores devueltos

Retorna un array que contiene información sobre la fecha/hora analizada.

El array retornado tiene claves para `year`, `month`, `day`, `hour`, `minute`, `second`, `fraction`, y `is_localtime`.

Si `is_localtime` está presente, entonces `zone_type` indica el tipo de zona horaria. Para el tipo `1` (desplazamiento UTC) los campos `zone` y `is_dst` son añadidos. Para el tipo `2` (abreviatura) los campos `tz_abbr` y `is_dst` son añadidos. Para el tipo `3` (identificador de zona horaria) los campos `tz_abbr` y `tz_id` son añadidos.

Si elementos de tiempo relativo están presentes en la cadena `datetime`, como `+3 days`, el array retornado incluye un array anidado con la clave `relative`. Este array contiene entonces las claves `year`, `month`, `day`, `hour`, `minute`, `second`, y si es necesario `weekday`, y `weekdays`, dependiendo de la cadena pasada.

El array incluye los campos `warning_count` y `warnings`. El primero indica el número de advertencias. Las claves del array `warnings` indican la posición en el parámetro `datetime` donde ocurrió la advertencia, con el valor de cadena describiendo la advertencia misma. Un ejemplo a continuación muestra tal advertencia.

El array incluye también los campos `error_count` y `errors`. El primero indica el número de errores. Las claves del array `errors` indican la posición en el parámetro `datetime` donde ocurrió el error, con el valor de cadena describiendo la advertencia misma. Un ejemplo a continuación muestra tal advertencia.

Advertencia

El número de elementos de array en los arrays `warnings` y `errors` puede ser inferior a `warning_count` o `error_count` si ocurrieron en la misma posición.

### Errores/Excepciones

En el caso de que la función retorne un error, el elemento `"errors"` contendrá los mensajes de error.

### Historial de cambios

Versión | Descripción
--- | ---
7.2.0 | El elemento `zone` del array retornado ahora representa segundos en lugar de minutos, y su signo es invertido. Por ejemplo, `-120` ahora es `7200`.

### Ejemplos

Ejemplo #1 date_parse() con una cadena `datetime` completa

    <?php
    var_dump(date_parse("2006-12-12 10:00:00.5"));

El ejemplo anterior mostrará:

    array(12) {
      ["year"]=>
      int(2006)
      ["month"]=>
      int(12)
      ["day"]=>
      int(12)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0.5)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
    }

Los elementos de zona horaria solo aparecen si están incluidos en la cadena `datetime` dada. En este caso, siempre habrá un elemento `zone_type` y algunos otros dependiendo de su valor.

Ejemplo #2 date_parse() con información abreviada sobre la zona horaria

    <?php
    var_dump(date_parse("June 2nd, 2022, 10:28:17 BST"));

El ejemplo anterior mostrará:

    array(16) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(28)
      ["second"]=>
      int(17)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(true)
      ["zone_type"]=>
      int(2)
      ["zone"]=>
      int(0)
      ["is_dst"]=>
      bool(true)
      ["tz_abbr"]=>
      string(3) "BST"
    }

Ejemplo #3 date_parse() con información abreviada sobre la zona horaria

    <?php
    var_dump(date_parse("June 2nd, 2022, 10:28:17 Europe/London"));

El ejemplo anterior mostrará:

    array(14) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(28)
      ["second"]=>
      int(17)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(true)
      ["zone_type"]=>
      int(3)
      ["tz_id"]=>
      string(13) "Europe/London"
    }

Si se analiza una cadena `datetime` más mínima, hay menos información disponible. En este ejemplo, todas las partes temporales son retornadas como `false`.

Ejemplo #4 date_parse() con una cadena mínima

    <?php
    var_dump(date_parse("June 2nd, 2022"));

El ejemplo anterior mostrará:

    array(12) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      bool(false)
      ["minute"]=>
      bool(false)
      ["second"]=>
      bool(false)
      ["fraction"]=>
      bool(false)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
    }

Los formatos relativos no influyen en los valores analizados desde formatos absolutos, pero son analizados en el elemento "relativo".

Ejemplo #5 Ejemplo con date_parse() y formatos relativos

    <?php
    var_dump(date_parse("2006-12-12 10:00:00.5 +1 week +1 hour"));

El ejemplo anterior mostrará:

    array(13) {
      ["year"]=>
      int(2006)
      ["month"]=>
      int(12)
      ["day"]=>
      int(12)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0.5)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
      ["relative"]=>
      array(6) {
        ["year"]=>
        int(0)
        ["month"]=>
        int(0)
        ["day"]=>
        int(7)
        ["hour"]=>
        int(1)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
      }
    }

Algunas estrofas, tales como `Thursday` (jueves) definirán la parte hora de la cadena como `0`. Si `Thursday` (jueves) se pasa a DateTimeImmutable::__construct() la hora, el minuto, el segundo y la fracción también serán definidos como `0`. En el ejemplo a continuación, el elemento año sin embargo es dejado como `false`.

Ejemplo #6 date_parse() con efectos secundarios

    <?php
    var_dump(date_parse("Thursday, June 2nd"));

El ejemplo anterior mostrará:

    array(13) {
      ["year"]=>
      bool(false)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(0)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
      ["relative"]=>
      array(7) {
        ["year"]=>
        int(0)
        ["month"]=>
        int(0)
        ["day"]=>
        int(0)
        ["hour"]=>
        int(0)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
        ["weekday"]=>
        int(4)
      }
    }

### Ver también

- date_parse_from_format() - Recupera las informaciones de una fecha dada siguiendo un formato específico para analizar el parámetro `datetime` con un formato específico
- checkdate() - Valida una fecha gregoriana para una validación de fecha Gregoriana
- getdate() - Devuelve la fecha/hora

# date_parse_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_parse_from_format — Recupera las informaciones de una fecha dada siguiendo un formato específico

### Descripción

function date_parse_from_format(string `$format`, string `$datetime`): array

Devuelve un array asociativo que contiene informaciones detalladas sobre una fecha/hora dada.

### Parámetros

`format`

  Documentación sobre el uso del `format`, por favor referirse a la documentación de DateTimeImmutable::createFromFormat(). Las mismas reglas se aplican.

`datetime`

  Cadena que representa la fecha/hora.

### Valores devueltos

Devuelve un array asociativo con informaciones detalladas sobre la fecha/hora dada.

El array devuelto tiene claves para `year`, `month`, `day`, `hour`, `minute`, `second`, `fraction`, y `is_localtime`.

Si `is_localtime` está presente, entonces `zone_type` indica el tipo de zona horaria. Para el tipo `1` (desplazamiento UTC) se añaden los campos `zone` y `is_dst`. Para el tipo `2` (abreviatura) se añaden los campos `tz_abbr` y `is_dst`. Para el tipo `3` (identificador de zona horaria) se añaden los campos `tz_abbr` y `tz_id`.

El array incluye los campos `warning_count` y `warnings`. El primero indica el número de advertencias. Las claves del array `warnings` indican la posición en el parámetro `datetime` donde ocurrió la advertencia, con el valor de cadena que describe la advertencia misma. Un ejemplo a continuación muestra tal advertencia.

El array incluye también los campos `error_count` y `errors`. El primero indica el número de errores. Las claves del array `errors` indican la posición en el parámetro `datetime` donde ocurrió el error, con el valor de cadena que describe la advertencia misma. Un ejemplo a continuación muestra tal advertencia.

Advertencia

El número de elementos de array en los arrays `warnings` y `errors` puede ser inferior a `warning_count` o `error_count` si ocurrieron en la misma posición.

### Errores/Excepciones

Esta función lanza una ValueError cuando el `datetime` contiene bytes NULL.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.21, 8.1.8, 8.2.0 | Ahora lanza una ValueError cuando se pasan bytes NULL en `datetime`, lo cual antes era ignorado silenciosamente.
7.2.0 | El elemento `zone` del array devuelto representa segundos en lugar de minutos ahora, y su signo es invertido. Por ejemplo `-120` ahora es igual a `7200`.

### Ejemplos

Ejemplo #1 Ejemplo con date_parse_from_format()

    <?php
    $date = "6.1.2009 13:00+01:00";
    print_r(date_parse_from_format("j.n.Y H:iP", $date));

El ejemplo anterior mostrará:

    Array
    (
        [year] => 2009
        [month] => 1
        [day] => 6
        [hour] => 13
        [minute] => 0
        [second] => 0
        [fraction] => 0
        [warning_count] => 0
        [warnings] => Array
            (
            )

        [error_count] => 0
        [errors] => Array
            (
            )

        [is_localtime] => 1
        [zone_type] => 1
        [zone] => 3600
        [is_dst] =>
    )

Ejemplo #2 Ejemplo de date_parse_from_format() con advertencias

    <?php
    $date = "26 August 2022 22:30 pm";
    $parsed = date_parse_from_format("j F Y G:i a", $date);

    echo "Número de advertencias: ", $parsed['warning_count'], "\n";
    foreach ($parsed['warnings'] as $position => $message) {
        echo "\tEn la posición {$position}: {$message}\n";
    }

El ejemplo anterior mostrará:

    Número de advertencias: 1
    	En la posición 23: The parsed time was invalid

Ejemplo #3 Ejemplo de date_parse_from_format() con errores

    <?php
    $date = "26 August 2022 CEST";
    $parsed = date_parse_from_format("j F Y H:i", $date);

    echo "Número de errores: ", $parsed['error_count'], "\n";
    foreach ($parsed['errors'] as $position => $message) {
        echo "\tEn la posición {$position}: {$message}\n";
    }

El ejemplo anterior mostrará:

    Número de errores: 3
    	En la posición 15: A two digit hour could not be found
    	En la posición 19: Not enough data available to satisfy format

### Ver también

- DateTimeImmutable::createFromFormat() - Analiza un string de tiempo según el formato especificado
- checkdate() - Valida una fecha gregoriana

# date_sub

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_sub — Alias de DateTime::sub()

### Descripción

Esta función es un alias de: DateTime::sub()

### Ver también

- DateTimeImmutable::sub() - Sustrae una cantidad de días, meses, años, horas, minutos y segundos
- DateTime::sub() - Sustrae una cantidad de días, meses, años, horas, minutos y segundos de un objeto DateTime

# date_sun_info

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

date_sun_info — Retorna un array con las informaciones sobre el amanecer/atardecer así como el inicio y el fin del amanecer

### Descripción

function date_sun_info(int `$timestamp`, float `$latitude`, float `$longitude`): array

### Parámetros

`timestamp`

  Timestamp Unix.

`latitude`

  Latitud, en grados.

`longitude`

  Longitud, en grados.

### Valores devueltos

Retorna un array cuya estructura del array se detalla en la lista siguiente:

`sunrise`
  El timestamp del amanecer (ángulo de zenit = 90°35').
`sunset`
  El timestamp del atardecer (ángulo de zenit = 90°35').
`transit`
  El timestamp donde el sol está en su cenit, es decir ha alcanzado su punto más alto.
`civil_twilight_begin`
  El inicio del amanecer civil (ángulo de zenit = 96°). Termina en el `sunrise`.
`civil_twilight_end`
  El fin del crepúsculo civil (ángulo de zenit = 96°). Comienza en el `sunset`.
`nautical_twilight_begin`
  El inicio del amanecer náutico (ángulo de zenit = 102°). Termina en el `civil_twilight_begin`.
`nautical_twilight_end`
  El fin del crepúsculo náutico (ángulo de zenit = 102°). Comienza en `civil_twilight_end`.
`astronomical_twilight_begin`
  El inicio del amanecer astronómico (ángulo de zenit = 108°). Termina en el `nautical_twilight_begin`.
`astronomical_twilight_end`
  El fin del crepúsculo astronómico (ángulo de zenit = 108°). Comienza en `nautical_twilight_end`.

Los valores de los elementos del array son timestamps UNIX, `false`, si el sol está bajo el zenit respectivo durante todo el día, o `true`, si el sol está sobre el zenit respectivo durante todo el día.

### Historial de cambios

Versión | Descripción
--- | ---
7.2.0 | El cálculo ha sido corregido teniendo en cuenta la medianoche local en lugar del mediodía local, lo que modifica ligeramente los resultados.

### Ejemplos

Ejemplo #1 Ejemplo con date_sun_info()

    <?php
    $sun_info = date_sun_info(strtotime("2006-12-12"), 31.7667, 35.2333);
    foreach ($sun_info as $key => $val) {
      echo "$key: " . date("H:i:s", $val) . "\n";
    }

El ejemplo anterior mostrará:

    sunrise: 05:52:11
    sunset: 15:41:21
    transit: 10:46:46
    civil_twilight_begin: 05:24:08
    civil_twilight_end: 16:09:24
    nautical_twilight_begin: 04:52:25
    nautical_twilight_end: 16:41:06
    astronomical_twilight_begin: 04:21:32
    astronomical_twilight_end: 17:12:00

Ejemplo #2 Noche polar con un poco de tratamiento

    <?php
    $tz = new \DateTimeZone('America/Anchorage');

    $si = date_sun_info(strtotime("2022-12-21"), 70.21, -148.51);
    foreach ($si as $key => $value) {
        echo
            match ($value) {
                true => 'always',
                false => 'never',
                default => date_create("@{$value}")->setTimeZone($tz)->format( 'H:i:s T' ),
            },
            ": {$key}",
            "\n";
    }

El ejemplo anterior mostrará:

    never: sunrise
    never: sunset
    12:52:18 AKST: transit
    10:53:19 AKST: civil_twilight_begin
    14:51:17 AKST: civil_twilight_end
    09:01:47 AKST: nautical_twilight_begin
    16:42:48 AKST: nautical_twilight_end
    07:40:47 AKST: astronomical_twilight_begin
    18:03:49 AKST: astronomical_twilight_end

Ejemplo #3 Sol de medianoche (Tromso, Noruega)

    <?php
    $si = date_sun_info(strtotime("2022-06-26"), 69.68, 18.94);
    print_r($si);

El ejemplo anterior mostrará:

    Array
    (
        [sunrise] => 1
        [sunset] => 1
        [transit] => 1656240426
        [civil_twilight_begin] => 1
        [civil_twilight_end] => 1
        [nautical_twilight_begin] => 1
        [nautical_twilight_end] => 1
        [astronomical_twilight_begin] => 1
        [astronomical_twilight_end] => 1
    )

Ejemplo #4 Cálculo de la duración del día (Kiev)

    <?php
    $si = date_sun_info(strtotime('2022-08-26'), 50.45, 30.52);
    $diff = $si['sunset'] - $si['sunrise'];
    echo "Duración del día: ",
        floor($diff / 3600), "h ",
        floor(($diff % 3600) / 60), "s\n";

El ejemplo anterior mostrará:

    Duración del día: 13h 56s

# date_sunrise

(PHP 5, PHP 7, PHP 8)

date_sunrise — Devuelve la hora de salida del sol para un día y un lugar dados

Advertencia

Esta función está OBSOLETA a partir de PHP 8.1.0. Depender de esta función está altamente desaconsejado. Se recomienda el uso de date_sun_info() en su lugar.

### Descripción

#[\Deprecated]
function date_sunrise(
int `$timestamp`,
int `$returnFormat` = SUNFUNCS_RET_STRING,
?float `$latitude` = null,
?float `$longitude` = null,
?float `$zenith` = null,
?float `$utcOffset` = null
): string|int|float|false

date_sunrise() devuelve la hora de salida del sol para un día (especificado por el argumento `timestamp`) y un lugar dados.

### Parámetros

`timestamp`

  El timestamp Unix del día para el cual se proporciona la hora de salida del sol.

`returnFormat`

  Constantes para el argumento `format`
  Constante | Descripción | Ejemplo
  --- | --- | ---
  SUNFUNCS_RET_STRING | Devuelve el resultado como string | 16:46
  SUNFUNCS_RET_DOUBLE | Devuelve el resultado como float | 16.78243132
  SUNFUNCS_RET_TIMESTAMP | Devuelve el resultado como int (timestamp) | 1095034606

`latitude`

  Por defecto, es el Norte. Pase un valor negativo para el Sur. Ver también date.default_latitude.

`longitude`

  Por defecto, es el Este. Pase un valor negativo para el Oeste. Ver también date.default_longitude.

`zenith`

  `zenith` es el ángulo entre el centro del sol y la línea perpendicular a la superficie de la tierra. Por defecto date.sunrise_zenith

  Valores comunes del ángulo `zenith`
  Ángulo | Descripción
  --- | ---
  90°50' | Salida del sol: el punto donde el sol se vuelve visible.
  96° | Crepúsculo civil: convencionalmente utilizado para significar el inicio del amanecer.
  102° | Crepúsculo náutico: el punto donde el horizonte comienza a ser visible en el mar.
  108° | Crepúsculo astronómico: el punto donde el sol comienza a ser la fuente de toda iluminación.

`utcOffset`

  Especificado en horas. El `utcOffset` se ignora si `returnFormat` es `SUNFUNCS_RET_TIMESTAMP`.

### Valores devueltos

Devuelve la hora de salida del sol en el `returnFormat` especificado en caso de éxito o `false` si ocurre un error. Una razón posible del fallo es que el sol no salga en absoluto, lo cual ocurre dentro de los círculos polares durante parte del año.

### Errores/Excepciones

Cada llamada a una función de fecha/hora generará un diagnóstico de tipo `E_WARNING` si la zona horaria no es válida. Ver también date_default_timezone_set()

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Esta función ha sido marcada como obsoleta en favor de date_sun_info().
8.0.0 | `latitude`, `longitude`, `zenith` y `utcOffset` ahora son nullable.

### Ejemplos

Ejemplo #1 Ejemplo con date_sunrise()

    <?php

    /* Calcula la hora de salida del sol para Lisboa, Portugal
    Latitud: 38.4 Norte
    Longitud: 9 Oeste
    Zenith ~= 90
    offset: +1 GMT
    */

    echo date("D M d Y"). ', hora de salida del sol: ' .date_sunrise(time(), SUNFUNCS_RET_STRING, 38.4, -9, 90, 1);

Resultado del ejemplo anterior es similar a:

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 10
    Deprecated: Function date_sunrise() is deprecated since 8.1, use date_sun_info() instead in script on line 10
    Mon Dec 20 2004, sunrise time : 08:54

Ejemplo #2 Sin salida del sol

    <?php
    $solstice = strtotime('2017-12-21');
    var_dump(date_sunrise($solstice, SUNFUNCS_RET_STRING, 69.245833, -53.537222));

El ejemplo anterior mostrará:

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 3
    Deprecated: Function date_sunrise() is deprecated since 8.1, use date_sun_info() instead in script on line 3
    bool(false)

### Ver también

- date_sun_info() - Retorna un array con las informaciones sobre el amanecer/atardecer así como el inicio y el fin del amanecer

# date_sunset

(PHP 5, PHP 7, PHP 8)

date_sunset — Devuelve la hora de puesta del sol para un día y un lugar dados

Advertencia

Esta función está OBSOLETA a partir de PHP 8.1.0. Depender de esta función está altamente desaconsejo. Use date_sun_info() en su lugar.

### Descripción

#[\Deprecated]
function date_sunset(
int `$timestamp`,
int `$returnFormat` = SUNFUNCS_RET_STRING,
?float `$latitude` = null,
?float `$longitude` = null,
?float `$zenith` = null,
?float `$utcOffset` = null
): string|int|float|false

La función date_sunset() devuelve la hora de puesta del sol para un día (especificado como `timestamp` Unix) y un lugar dados.

### Parámetros

`timestamp`

  El `timestamp` Unix del día para el cual se proporciona la hora de puesta del sol.

`returnFormat`

  Constantes para el parámetro `returnFormat`
  Constante | Descripción | Ejemplo
  --- | --- | ---
  SUNFUNCS_RET_STRING | Devuelve el resultado en forma de string | 16:46
  SUNFUNCS_RET_DOUBLE | Devuelve el resultado en forma de float | 16.78243132
  SUNFUNCS_RET_TIMESTAMP | Devuelve el resultado en forma de int (timestamp) | 1095034606

`latitude`

  Por omisión, es el Norte. Pase un valor negativo para el Sur. Ver también date.default_latitude.

`longitude`

  Por omisión, es el Este. Pase un valor negativo para el Oeste. Ver también date.default_longitude.

`zenith`

  `zenith` es el ángulo entre el centro del sol y la línea perpendicular a la superficie de la tierra. Por omisión date.sunset_zenith

  Valores comunes de ángulo `zenith`
  Ángulo | Descripción
  --- | ---
  90°50' | Puesta del sol: El punto donde el sol se vuelve invisible.
  96° | Crepúsculo civil: convencionalmente utilizado para significar el fin del crepúsculo.
  102° | Crepúsculo náutico: el punto de fin del horizonte siendo visible en el mar.
  108° | Crepúsculo astronómico: el punto donde el sol deja de ser la fuente de toda iluminación.

`utcOffset`

  Especificado en horas. El `utcOffset` es ignorado, si `returnFormat` es `SUNFUNCS_RET_TIMESTAMP`.

### Valores devueltos

Devuelve la hora de puesta del sol en el `returnFormat` especificado o `false` si ocurre un error. Una razón posible del fallo es que el sol no se pone, lo cual ocurre dentro de los círculos polares durante parte del año.

### Errores/Excepciones

Cada llamada a una función de fecha/hora generará un diagnóstico de tipo `E_WARNING` si la zona horaria no es válida. Ver también date_default_timezone_set()

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Esta función ha sido marcada como obsoleta en favor de date_sun_info().
8.0.0 | `latitude`, `longitude`, `zenith` y `utcOffset` ahora son nullable.

### Ejemplos

Ejemplo #1 Ejemplo con date_sunset()

    <?php

         /* Calcula la hora de puesta del sol para Lisboa, Portugal
    Latitud: 38.4 Norte
    Longitud: 9 Oeste
    Zenith ~= 90
    offset:1 GMT
    */

    echo date("D M d Y"). ', hora de puesta del sol : ' .date_sunset(time(), SUNFUNCS_RET_STRING, 38.4, -9, 90, 1);

Resultado del ejemplo anterior es similar a:

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 10
    Deprecated: Function date_sunset() is deprecated since 8.1, use date_sun_info() instead in script on line 10
    Mon Dec 20 2004, sunset time : 18:13

Ejemplo #2 Sin puesta de sol

    <?php
    $solstice = strtotime('2017-12-21');
    var_dump(date_sunset($solstice, SUNFUNCS_RET_STRING, 69.245833, -53.537222));

El ejemplo anterior mostrará:

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 3
    Deprecated: Function date_sunset() is deprecated since 8.1, use date_sun_info() instead in script on line 3
    bool(false)

### Ver también

- date_sun_info() - Retorna un array con las informaciones sobre el amanecer/atardecer así como el inicio y el fin del amanecer

# date_time_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_time_set — Alias de DateTime::setTime()

### Descripción

Esta función es un alias de: DateTime::setTime()

# date_timestamp_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_timestamp_get — Alias de DateTime::getTimestamp()

### Descripción

Esta función es un alias de: DateTime::getTimestamp()

# date_timestamp_set

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_timestamp_set — Alias de DateTime::setTimestamp()

### Descripción

Esta función es un alias de: DateTime::setTimestamp()

# date_timezone_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_timezone_get — Alias de DateTime::getTimezone()

### Descripción

Esta función es un alias de: DateTime::getTimezone()

# date_timezone_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_timezone_set — Alias de DateTime::setTimezone()

### Descripción

Esta función es un alias de: DateTime::setTimezone()

# getdate

(PHP 4, PHP 5, PHP 7, PHP 8)

getdate — Devuelve la fecha/hora

### Descripción

function getdate(?int `$timestamp` = `null`): array

Devuelve un array asociativo que contiene las informaciones de fecha y hora del `timestamp`, o la fecha/hora actual local si `timestamp` es omitido o `null`.

### Parámetros

`timestamp`
  El parámetro opcional `timestamp` es un timestamp Unix de tipo int que por omisión es la hora actual local si `timestamp` es omitido o `null`. En otras palabras, es por omisión el valor de la función time().

### Valores devueltos

Devuelve un array asociativo que contiene las informaciones de fecha y hora del timestamp `timestamp`. Los elementos del array asociativo devuelto son los siguientes:

Nombres de las claves del array asociativo devuelto
Clave | Descripción | Ejemplo de valor devuelto
--- | --- | ---
`"seconds"` | Representación numérica de los segundos | `0` a `59`
`"minutes"` | Representación numérica de los minutos | `0` a `59`
`"hours"` | Representación numérica de las horas | `0` a `23`
`"mday"` | Representación numérica del día del mes actual | `1` a `31`
`"wday"` | Representación numérica del día de la semana actual | `0` (para Domingo) a `6` (para Sábado)
`"mon"` | Representación numérica del mes | `1` a `12`
`"year"` | Año, con 4 dígitos | Ejemplos: `1999` o `2003`
`"yday"` | Representación numérica del día del año | `0` a `365`
`"weekday"` | Versión en texto del día de la semana | `Sunday` a `Saturday`
`"month"` | Versión en texto del mes, como `January` o `March` | `January` a `December`
`0` | Número de segundos desde la época Unix, similar al valor devuelto por la función time() y utilizado por date(). | Depende del sistema, típicamente de `-2147483648` a `2147483647`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `timestamp` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con getdate()

    <?php
    $today = getdate();
    print_r($today);

Resultado del ejemplo anterior es similar a:

    Array
    (
        [seconds] => 40
        [minutes] => 58
        [hours] => 21
        [mday] => 17
        [wday] => 2
        [mon] => 6
        [year] => 2003
        [yday] => 167
        [weekday] => Tuesday
        [month] => June
        [0] => 1055901520
    )

### Ver también

- date() - Da formato a una marca de tiempo de Unix (Unix timestamp)
- idate() - Formatea una parte de la hora/fecha local como un entero
- localtime() - Obtiene la hora local
- time() - Devuelve el timestamp UNIX actual
- setlocale() - Establece la información de configuración local

# gettimeofday

(PHP 4, PHP 5, PHP 7, PHP 8)

gettimeofday — Devuelve la hora actual

### Descripción

function gettimeofday(bool `$as_float` = `false`): array|float

Es una interfaz con gettimeofday(2). Devuelve un array asociativo que contiene las informaciones devueltas por el sistema.

### Parámetros

`as_float`

  Cuando se define como `true`, se devuelve un float en lugar de un array.

### Valores devueltos

Por omisión, se devuelve un array. Si el argumento `as_float` está definido, entonces se devolverá un float.

Claves del array :

- "sec" : segundos desde la época Unix
- "usec" : microsegundos
- "minuteswest" : minutos de desfase respecto a Greenwich, hacia el Oeste.
- "dsttime" : tipo de corrección dst

### Ejemplos

Ejemplo #1 Ejemplo con gettimeofday()

    <?php
    print_r(gettimeofday());

    echo gettimeofday(true);

Resultado del ejemplo anterior es similar a:

    Array
    (
       [sec] => 1073504408
       [usec] => 238215
       [minuteswest] => 0
       [dsttime] => 1
    )
    1073504408.23910

# gmdate

(PHP 4, PHP 5, PHP 7, PHP 8)

gmdate — Formatea una fecha/hora GMT/TUC

### Descripción

function gmdate(string `$format`, ?int `$timestamp` = `null`): string

Idéntico a la función date(), excepto que el tiempo devuelto es Greenwich Mean Time (GMT).

### Parámetros

`format`

  El formato de la fecha de salida en forma de string. Ver las opciones de formato para la función date().

`timestamp`
  El parámetro opcional `timestamp` es un timestamp Unix de tipo int que por omisión es la hora actual local si `timestamp` es omitido o `null`. En otras palabras, es por omisión el valor de la función time().

### Valores devueltos

Devuelve una fecha formateada.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `timestamp` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con gmdate()

    <?php
    date_default_timezone_set("Europe/Helsinki");

    echo date("M d Y H:i:s e", mktime(0, 0, 0, 1, 1, 1998)) . "\n";
    echo gmdate("M d Y H:i:s e", mktime(0, 0, 0, 1, 1, 1998));

El ejemplo anterior mostrará:

    Jan 01 1998 00:00:00 Europe/Helsinki
    Dec 31 1997 22:00:00 UTC

### Ver también

- DateTimeImmutable::__construct() - Devuelve un nuevo objeto DateTimeImmutable
- DateTimeInterface::format() - Retorna una fecha formateada según el formato proporcionado
- date() - Da formato a una marca de tiempo de Unix (Unix timestamp)
- mktime() - Obtener la marca de tiempo Unix de una fecha
- gmmktime() - Retorna el timestamp UNIX de una fecha GMT
- IntlDateFormatter::format() - Formatea la fecha y la hora como string

# gmmktime

(PHP 4, PHP 5, PHP 7, PHP 8)

gmmktime — Retorna el timestamp UNIX de una fecha GMT

### Descripción

function gmmktime(
int `$hour`,
?int `$minute` = `null`,
?int `$second` = `null`,
?int `$month` = `null`,
?int `$day` = `null`,
?int `$year` = `null`
): int|false

Similar a la función mktime() excepto que los argumentos opcionales pasados son GMT. gmmktime() utiliza internamente la función mktime(), por lo tanto, solo los tiempos válidos en la zona horaria local derivada pueden ser utilizados.

Al igual que mktime(), los argumentos restantes pueden ser omitidos. En ese caso, tomarán los valores GMT actuales.

Llamar a gmmktime() sin argumentos no es soportado. Esto resultará en lanzar una ArgumentCountError. time() puede ser utilizado para obtener el timestamp actual.

### Parámetros

`hour`

  El número de horas desde el inicio del día establecido por los parámetros `month`, `day` y `year`. Los valores negativos hacen referencia a las horas antes de la medianoche del día en cuestión. Los valores superiores a 23 hacen referencia a las horas asociadas al(dos) día(s) siguiente(s).

`minute`

  El número de minutos desde el inicio de la hora `hour`. Los valores negativos hacen referencia a los minutos de la hora anterior. Los valores superiores a 59 hacen referencia a los minutos asociados a la(s) hora(s) siguiente(s).

`second`

  El número de segundos desde el inicio del minuto `minute`. Los valores negativos hacen referencia a los segundos del minuto anterior. Los valores superiores a 59 hacen referencia a los segundos asociados a el(la) minuto(s) siguiente(s).

`month`

  El número de meses desde el final del año anterior. Los valores comprendidos entre 1 y 12 hacen referencia a los meses del calendario normal del año en cuestión. Los valores inferiores a 1 (incluyendo los valores negativos) hacen referencia a los meses del año anterior en orden inverso, por lo tanto, 0 corresponde a diciembre, -1 a noviembre, etc. Los valores superiores a 12 hacen referencia al mes correspondiente en el(la) año(s) siguiente(s).

`day`

  El número de días desde el final del mes anterior. Los valores comprendidos entre 1 y 28, 29, 30, 31 (según el mes) hacen referencia a los días normales en el mes actual. Los valores inferiores a 1 (incluyendo los valores negativos) hacen referencia a los días del mes anterior, por lo tanto, 0 corresponde al último día del mes anterior, -1, el día anterior, etc. Los valores superiores al número de días del mes actual hacen referencia a los días correspondientes del(la) mes(es) siguiente(s).

`year`

  El año

### Valores devueltos

Retorna un timestamp Unix de tipo int, o `false` si el timestamp no cabe en un entero PHP.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `hour` ya no es opcional. Para obtener un timestamp unix, se deberá utilizar la función time().
8.0.0 | `minute`, `second`, `month`, `day` y `year` ahora son nullable.

### Ejemplos

Ejemplo #1 Ejemplo con gmmktime()

    <?php
    date_default_timezone_set("Indian/Maldives");

    echo "1 de julio de 2000 cae en " . date("l", gmmktime(0, 0, 0, 7, 1, 2000));

El ejemplo anterior mostrará:

    1 de julio de 2000 cae en Saturday

### Ver también

- La clase DateTimeImmutable
- mktime() - Obtener la marca de tiempo Unix de una fecha
- date() - Da formato a una marca de tiempo de Unix (Unix timestamp)
- time() - Devuelve el timestamp UNIX actual

# gmstrftime

(PHP 4, PHP 5, PHP 7, PHP 8)

gmstrftime — Formatea una fecha/hora GMT/TUC según la configuración local

Advertencia

Esta función está OBSOLETA a partir de PHP 8.1.0. Se recomienda evitar su uso.

Las alternativas a esta función incluyen:

- gmdate()
- IntlDateFormatter::format()

### Descripción

#[\Deprecated]
function gmstrftime(string `$format`, ?int `$timestamp` = null): string|false

Se comporta igual que strftime() excepto que la hora devuelta es la hora del meridiano de Greenwich (GMT). Por ejemplo, cuando se ejecuta en la hora estándar del este (GMT -0500), la primera línea a continuación imprime "Dec 31 1998 20:00:00", mientras que la segunda imprime "Jan 01 1999 01:00:00".

Advertencia

Esta función depende de la información local del sistema operativo, que puede ser inconsistente o no estar disponible. Se recomienda utilizar el método IntlDateFormatter::format().

### Parámetros

`format`

  Ver la descripción de la función strftime().

`timestamp`
  El parámetro opcional `timestamp` es un timestamp Unix de tipo int que por omisión es la hora actual local si `timestamp` es omitido o `null`. En otras palabras, es por omisión el valor de la función time().

### Valores devueltos

Devuelve un string formateado según el formato dado utilizando el argumento `timestamp` o la hora local actual si no se proporciona ningún timestamp. Los nombres de los meses, días de la semana y otras cadenas dependientes de una localización dada, respetan la localización actual definida por la función setlocale(). En caso de error, se devuelve `false`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `timestamp` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con gmstrftime()

    <?php

    setlocale(LC_TIME, 'es_ES.UTF-8');
    date_default_timezone_set('EST');

    echo strftime("%B %d %Y %H:%M:%S",   mktime(20, 0, 0, 12, 31, 98)) . "\n";
    echo gmstrftime("%B %d %Y %H:%M:%S", mktime(20, 0, 0, 12, 31, 98));

El ejemplo anterior mostrará:

    Deprecated: Function strftime() is deprecated since 8.1, use IntlDateFormatter::format() instead in script on line 6
    diciembre 31 1998 20:00:00

    Deprecated: Function gmstrftime() is deprecated since 8.1, use IntlDateFormatter::format() instead in script on line 7
    enero 01 1999 01:00:00

### Ver también

- IntlDateFormatter::format() - Formatea la fecha y la hora como string
- DateTimeInterface::format() - Retorna una fecha formateada según el formato proporcionado
- strftime() - Formatea una fecha/hora local con la configuración local

# idate

(PHP 5, PHP 7, PHP 8)

idate — Formatea una parte de la hora/fecha local como un entero

### Descripción

function idate(string `$format`, ?int `$timestamp` = `null`): int|false

Devuelve un número formateado según el formato `format` dado con el timestamp entero dado `timestamp` o la hora actual si no se da un timestamp. En otras palabras, `timestamp` es opcional y el valor por omisión es el valor devuelto por time().

A diferencia de la función date(), idate() acepta solo un carácter como parámetro `format`.

### Parámetros

`format`

  Los siguientes caracteres son reconocidos en el string del parámetro `format`
  Caracteres de `format` | Descripción
  --- | ---
  `B` | Tiempo Internet Swatch Beat
  `d` | El día del mes
  `h` | Hora (formato 12 horas)
  `H` | Hora (formato 24 horas)
  `i` | Minutos
  `I`(i, en mayúscula) | Devuelve `1` si el horario de verano está activado, `0` en caso contrario
  `L`(l, en mayúscula) | Devuelve `1` para un año bisiesto, `0` en caso contrario
  `m` | Número del mes
  `N` | Día de la semana ISO-8601 (`1` para el lunes a `7` para el domingo)
  `o` | Año ISO-8601 (4 dígitos)
  `s` | Segundos
  `t` | Día del mes actual
  `U` | Segundos desde la época Unix - 1 de Enero de 1970 00:00:00 UTC - esto es lo mismo que la función time()
  `w` | Día de la semana (`0` para Domingo)
  `W` | El número de semana del año; según ISO-8601, las semanas comienzan el Lunes
  `y` | Año en 1 o 2 dígitos, ver la nota más abajo
  `Y` | Año en 4 dígitos
  `z` | Día del año
  `Z` | Desplazamiento horario, en segundos

`timestamp`
  El parámetro opcional `timestamp` es un timestamp Unix de tipo int que por omisión es la hora actual local si `timestamp` es omitido o `null`. En otras palabras, es por omisión el valor de la función time().

### Valores devueltos

Devuelve un int en caso de éxito, o `false` si ocurre un error.

Dado que idate() siempre devuelve un int y no puede comenzar con `0`, idate() puede devolver menos dígitos de los que se podrían esperar. Ver el ejemplo a continuación.

### Errores/Excepciones

Cada llamada a una función de fecha/hora generará un diagnóstico de tipo `E_WARNING` si la zona horaria no es válida. Ver también date_default_timezone_set()

### Historial de cambios

Versión | Descripción
--- | ---
8.2.0 | Añade los caracteres de formato `N` (día de la semana ISO-8601) y `o` (año ISO-8601).
8.0.0 | `timestamp` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con idate()

    <?php
    $timestamp = strtotime('1st January 2004'); // 1072915200

    // esto muestra el año en dos dígitos
    // sin embargo, dado que este dígito comenzará con "0",
    // solo "4" será mostrado
    echo idate('y', $timestamp) . "\n";

    $timestamp = strtotime('1st January 2024'); // 1704067200
    echo idate('y', $timestamp);

El ejemplo anterior mostrará:

    4
    24

### Ver también

- DateTimeInterface::format() - Retorna una fecha formateada según el formato proporcionado
- date() - Da formato a una marca de tiempo de Unix (Unix timestamp)
- getdate() - Devuelve la fecha/hora
- time() - Devuelve el timestamp UNIX actual

# localtime

(PHP 4, PHP 5, PHP 7, PHP 8)

localtime — Obtiene la hora local

### Descripción

function localtime(?int `$timestamp` = `null`, bool `$associative` = `false`): array

localtime() devuelve un array idéntico a la estructura devuelta por la función C localtime.

### Parámetros

`timestamp`
  El parámetro opcional `timestamp` es un timestamp Unix de tipo int que por omisión es la hora actual local si `timestamp` es omitido o `null`. En otras palabras, es por omisión el valor de la función time().
`associative`

  Determina si la función debe devolver un array regular, indexado numéricamente, o un array asociativo.

### Valores devueltos

Si `associative` está definido como `false` o no se proporciona, entonces el array se devuelve como un array indexado numéricamente estándar. Si `associative` está definido como `true` entonces localtime() devuelve un array asociativo que contiene los elementos de la estructura devuelta por la llamada a la función localtime de C Las claves del array asociativo son las siguientes:

- "tm_sec" : segundos, de `0` a `59`
- "tm_min" : minutos, de `0` a `59`
- "tm_hour" : hora, de `0` a `23`
- "tm_mday" : día del mes, de `1` a `31`
- "tm_mon" : mes del año, de `0` (Ene) a `11` (Dic)
- "tm_year" : Año desde 1900
- "tm_wday" : Día de la semana, de `0` (Dom) a `6` (Sáb)
- "tm_yday" : Día del año, de `0` a `365`
- "tm_isdst" : ¿Está en vigor el horario de verano? Valor positivo si es así, `0` en caso contrario, valor negativo si el resultado no ha podido determinarse.

### Errores/Excepciones

Cada llamada a una función de fecha/hora generará un diagnóstico de tipo `E_WARNING` si la zona horaria no es válida. Ver también date_default_timezone_set()

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `timestamp` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con localtime()

    <?php
    $localtime = localtime();
    $localtime_assoc = localtime(time(), true);
    print_r($localtime);
    print_r($localtime_assoc);

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => 24
        [1] => 3
        [2] => 19
        [3] => 3
        [4] => 3
        [5] => 105
        [6] => 0
        [7] => 92
        [8] => 1
    )

    Array
    (
        [tm_sec] => 24
        [tm_min] => 3
        [tm_hour] => 19
        [tm_mday] => 3
        [tm_mon] => 3
        [tm_year] => 105
        [tm_wday] => 0
        [tm_yday] => 92
        [tm_isdst] => 1
    )

### Ver también

- getdate() - Devuelve la fecha/hora

# microtime

(PHP 4, PHP 5, PHP 7, PHP 8)

microtime — Devuelve el timestamp UNIX actual con microsegundos

### Descripción

function microtime(bool `$as_float` = `false`): string|float

microtime() devuelve el timestamp Unix, con microsegundos. Esta función está únicamente disponible en los sistemas que soportan la función gettimeofday().

Para medir el rendimiento, se recomienda el uso de hrtime().

### Parámetros

`as_float`

  Si se utiliza y se define como `true`, microtime() devolverá un float en lugar de un string, tal como se describe en la sección de valores devueltos a continuación.

### Valores devueltos

Por omisión, microtime() devuelve un string en el formato "msec sec", donde `sec` es el número de segundos desde la época Unix (1 de Enero de 1970, 00:00:00 GMT), y `msec` es el número de microsegundos que han transcurrido desde `sec`, expresado en segundos en forma de fracción decimal.

Si `as_float` se define como `true`, entonces microtime() devuelve un float, que representa el tiempo actual, en segundos, desde la época Unix, con precisión de microsegundo.

### Ejemplos

Ejemplo #1 Duración de ejecución de un script en PHP

    <?php
    $time_start = microtime(true);

    // Espera durante un momento
    usleep(10_000);

    $time_end = microtime(true);
    $time = $time_end - $time_start;

    print "No hacer nada durante $time segundos\n";

Ejemplo #2 Ejemplo con microtime() y `REQUEST_TIME_FLOAT`

    <?php
    // Duración de espera aleatoria
    usleep(random_int(10_000, 1_000_000));

    // REQUEST_TIME_FLOAT está disponible en el array superglobal $_SERVER.
    // Contiene el timestamp del inicio de la petición, con precisión de microsegundo.
    $time = microtime(true) - $_SERVER["REQUEST_TIME_FLOAT"];

    echo "No hacer nada durante $time segundos\n";

### Ver también

- time() - Devuelve el timestamp UNIX actual
- hrtime() - Devuelve el tiempo de alta resolución del sistema

# mktime

(PHP 4, PHP 5, PHP 7, PHP 8)

mktime — Obtener la marca de tiempo Unix de una fecha

### Descripción

function mktime(
int `$hour`,
?int `$minute` = `null`,
?int `$second` = `null`,
?int `$month` = `null`,
?int `$day` = `null`,
?int `$year` = `null`
): int|false

Devuelve la marca de tiempo Unix correspondiente a los argumentos dados. Esta marca de tiempo es un entero que contiene el número de segundos entre la Época Unix (1 de Enero del 1970 00:00:00 GMT) y el instante especificado.

Cualquier parámetro opcional omitido o a `null` se establecerá al valor actual según la fecha y hora locales.

Advertencia

Tenga en cuenta que el orden de los argumentos es extraño: `month`, `day`, `year`, y no en el orden más natural de `year`, `month`, `day`.

Llamar a mktime() sin argumentos no está soportado, y devolverá un ArgumentCountError. Puede usar time() para obtener la marca de tiempo actual.

### Parámetros

`hour`

  El número de la hora relativa al inicio del día determinado por `month`, `day` y `year`. Los valores negativos referencian la hora antes de la media noche del día en cuestión. Los valores mayores que 23 referencian la hora apropiada en el/los día/s siguiente/s.

`minute`

  El número de los minutos relativos al inicio de `hour`. Los valores negativos referencian el minuto en la hora previa. Los valores mayores que 59 referencian el minuto apropiado en la/s hora/s siguiente/s.

`second`

  El número de segundos relativos al inicio de `minute`. Los valores negativos referencian el segundo en el minuto previo. Los valores mayores que 59 referencian el segundo apropiado en el/los minuto/s siguiente/s.

`month`

  El número del mes relativo al final del año previo. Los valores de 1 a 12 referencian los meses del calendario normal del año en cuestión. Los valores menores que 1 (incluyendo valores negativos) referencian los meses del año previo en orden inverso, por lo que 0 es Diciembre, -1 es Noviembre, etc. Los valores mayores que 12 referencian el mes apropiado en el/los año/s siguiente/s.

`day`

  El número del día relativo al final del mes previo. Los valores del 1 al 28, 29, 30 o 31 (dependiendo del mes) referencian los días normales del mes relevante. Los valores menores que 1 (incluyendo valores negativos) referencian los días del mes previo por lo que 0 es el último día del mes previo, -1 es el día anterior a ese, etc. Los valores mayores que el número de días del mes relevante referencian el día apropiado en el/los mes/es siguiente/s.

`year`

  El número del año, puede ser un valor de dos o cuatro dígitos, con valores entre 0-69 mapeados a 2000-2069 y 70-100 a 1970-2000. En sistemas donde time_t es un entero con signo de 32 bits, como es lo más normal hoy en día, el rango válido para `year` es entre 1901 y 2038. Sin embargo, antes de PHP 5.1.0 este rango estaba limitado desde 1970 a 2038 en algunos sistemas (p.ej. Windows).

### Valores devueltos

mktime() devuelve la marca de tiempo Unix de los argumentos dados, o `false` si la marca de tiempo no cabe en un entero PHP.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `hour` ya no es opcional. Si necesita una marca de tiempo unix, utilice time().
8.0.0 | `minute`, `second`, `month`, `day` y `year` ahora pueden ser nulos.

### Ejemplos

Ejemplo #1 Ejemplo básico de mktime()

    <?php
    // Establece la zona horaria a utilizar.
    date_default_timezone_set('UTC');

    // Imprime: 1 de julio de 2000 cae en sábado
    echo "1 de julio de 2000 cae en " . date("l", mktime(0, 0, 0, 7, 1, 2000)) . "\n";

    // Imprime algo como: 2006-04-05T01:02:03+00:00
    echo date('c', mktime(1, 2, 3, 4, 5, 2006)) . "\n";

Resultado del ejemplo anterior es similar a:

    1 de julio de 2000 cae en Saturday
    2006-04-05T01:02:03+00:00

Ejemplo #2 Ejemplo mktime()

mktime() es útil para hacer cálculos con fechas y validaciones, ya que calculará automáticamente los valores correctos para entradas fuera de rango. Por ejemplo, cada una de las siguientes líneas devuelve la cadena: "Jan-01-1998".

    <?php
    date_default_timezone_set('America/New_York');

    echo date("c", mktime(0, 0, 0, 12, 32, 1997)) . "\n";
    echo date("c", mktime(0, 0, 0, 13, 1, 1997)) . "\n";
    echo date("c", mktime(0, 0, 0, 1, 1, 1998)) . "\n";
    echo date("c", mktime(0, 0, 0, 1, 1, 98)) . "\n";

Resultado del ejemplo anterior es similar a:

    1998-01-01T00:00:00-05:00
    1998-01-01T00:00:00-05:00
    1998-01-01T00:00:00-05:00
    1998-01-01T00:00:00-05:00

Ejemplo #3 Usando mktime para buscar fechas relativas

    <?php
    date_default_timezone_set('Asia/Tokyo');

    $tomorrow  = mktime(0, 0, 0, date("m")  , date("d")+1, date("Y"));
    print date('c', $tomorrow) . "\n";

    $lastmonth = mktime(0, 0, 0, date("m")-1, date("d"),   date("Y"));
    print date('c', $lastmonth) . "\n";

    $nextyear  = mktime(0, 0, 0, date("m"),   date("d"),   date("Y")+1) . "\n";
    print date('c', $nextyear) . "\n";

Resultado del ejemplo anterior es similar a:

    2025-09-30T00:00:00+09:00
    2025-08-29T00:00:00+09:00
    2026-09-29T00:00:00+09:00

> Nota:

> Esto puede ser más fiable que simplemente sumar o restar el número de segundos de un día o mes a una marca de tiempo debido al horario de verano.

Ejemplo #4 El último día del mes

El último día de cualquier mes dado se puede expresar como el día "0" del mes siguiente, no el día -1. Los dos ejemplos siguientes producirán la cadena "El último día en Feb 2000 es: 29".

    <?php

    $lastday = mktime(0, 0, 0, 3, 0, 2000);
    echo 'El último día en Feb 2000 es: ', date('d', $lastday) . "\n";

    $lastday = mktime(0, 0, 0, 4, -31, 2000);
    echo 'El último día en Feb 2000 es: ', date('d', $lastday) . "\n";

El ejemplo anterior mostrará:

    El último día en Feb 2000 es: 29
    El último día en Feb 2000 es: 29

### Ver también

- La clase DateTimeImmutable
- checkdate() - Valida una fecha gregoriana
- gmmktime() - Retorna el timestamp UNIX de una fecha GMT
- date() - Da formato a una marca de tiempo de Unix (Unix timestamp)
- time() - Devuelve el timestamp UNIX actual

# strftime

(PHP 4, PHP 5, PHP 7, PHP 8)

strftime — Formatea una fecha/hora local con la configuración local

Advertencia

Esta función está OBSOLETA a partir de PHP 8.1.0. Se recomienda evitar su uso.

Las alternativas a esta función incluyen:

- date()
- IntlDateFormatter::format()

### Descripción

#[\Deprecated]
function strftime(string `$format`, ?int `$timestamp` = null): string|false

Formatea una fecha y/o una hora según la localización local. Los nombres de los meses, de los días de la semana pero también de otras cadenas dependientes de la localización, respetarán la localización actual definida por la función setlocale().

Advertencia

Es posible que no todos los especificadores de conversión sean compatibles con su biblioteca C, en cuyo caso no serán compatibles con strftime() de PHP. Además, no todas las plataformas admiten marcas de tiempo negativas, por lo que su rango de fechas puede estar limitado a fechas no anteriores a la época Unix. Esto significa que `%e`, `%T`, `%R` y `%D` (y puede que otros) y las fechas anteriores al `1 de Enero de 1970` no funcionarán bajo Windows, en algunas distribuciones de Linux, y algunos otros sistemas operativos. Para Windows, una lista completa de las opciones de conversión está disponible en el » sitio de MSDN. Utilice en su lugar el método IntlDateFormatter::format().

### Parámetros

`format`

  Los siguientes caracteres son reconocidos en el argumento `format`
  `format` | Descripción | Ejemplo de valores devueltos
  --- | --- | ---
  Día | --- | ---
  `%a` | Nombre abreviado del día de la semana | De `Sun` a `Sat`
  `%A` | Nombre completo del día de la semana | De `Sunday` a `Saturday`
  `%d` | Día del mes en formato numérico, con 2 dígitos (con el cero inicial) | De `01` a `31`
  `%e` | Día del mes, con un espacio precediendo al primer dígito. La implementación de Windows es diferente, véase más abajo para más información. | De `1` a `31`
  `%j` | Día del año, con 3 dígitos con cero inicial | `001` a `366`
  `%u` | Representación ISO-8601 del día de la semana | De `1` (para Lunes) a `7` (para Domingo)
  `%w` | Representación numérica del día de la semana | De `0` (para Domingo) a `6` (para Sábado)
  Semana | --- | ---
  `%U` | Número de la semana del año dado, comenzando por el primer Lunes como primera semana | `13` (para la 13ª semana completa del año)
  `%V` | Número de la semana del año, siguiendo la norma ISO-8601:1988, comenzando como primera semana, la semana del año que contiene al menos 4 días, y donde Lunes es el inicio de la semana | De `01` a `53` (donde 53 cuenta como semana de solapamiento)
  `%W` | Una representación numérica de la semana del año, comenzando por el primer Lunes de la primera semana | `46` (para la 46ª semana de la semana comenzando por un Lunes)
  Mes | --- | ---
  `%b` | Nombre del mes, abreviado, según la localización | De `Jan` a `Dec`
  `%B` | Nombre completo del mes, según la localización | De `January` a `December`
  `%h` | Nombre del mes abreviado, según la localización (alias de %b) | De `Jan` a `Dec`
  `%m` | Mes, con 2 dígitos | De `01` (para Enero) a `12` (para Diciembre)
  Año | --- | ---
  `%C` | Representación, con 2 dígitos, del siglo (año dividido por 100, reducido a un entero) | `19` para el siglo 20
  `%g` | Representación, con 2 dígitos, del año, compatible con los estándares ISO-8601:1988 (véase %V) | Ejemplo: `09` para la semana del 6 de enero de 2009
  `%G` | La versión completa de 4 dígitos de %g | Ejemplo: `2009` para la semana del 3 de enero de 2009
  `%y` | El año, con 2 dígitos | Ejemplo: `09` para 2009, `79` para 1979
  `%Y` | El año, con 4 dígitos | Ejemplo: `2038`
  Hora | --- | ---
  `%H` | La hora, con 2 dígitos, en formato 24 horas | De `00` a `23`
  `%k` | La hora en formato 24 horas, con un espacio precediendo a un solo dígito | De `0` a `23`
  `%I` | Hora, con 2 dígitos, en formato 12 horas | De `01` a `12`
  `%l` ('L' minúscula) | Hora, en formato 12 horas, con un espacio precediendo a un solo dígito | De `1` a `12`
  `%M` | Minuto, con 2 dígitos | De `00` a `59`
  `%p` | 'AM' o 'PM', en mayúsculas, basado en la hora proporcionada | Ejemplo: `AM` para 00:31, `PM` para 22:23. El resultado exacto depende del sistema operativo, y pueden devolver también variantes en minúsculas, o variantes con puntos (como `a.m.`).
  `%P` | 'am' o 'pm', en minúsculas, basado en la hora proporcionada | Ejemplo: `am` para 00:31, `pm` para 22:23. No soportado por todos los sistemas operativos.
  `%r` | Idéntico a "%I:%M:%S %p" | Ejemplo: `09:34:17 PM` para 21:34:17
  `%R` | Idéntico a "`%H:%M`" | Ejemplo: `00:35` para 12:35 AM, `16:44` para 4:44 PM
  `%S` | Segundo, con 2 dígitos | De `00` a `59`
  `%T` | Idéntico a "`%H:%M:%S`" | Ejemplo: `21:34:17` para 09:34:17 PM
  `%X` | Representación de la hora, basada en la localización, sin la fecha | Ejemplo: `03:59:16` o `15:59:16`
  `%z` | El desplazamiento horario. No implementado tal como se describe en Windows. Ver más abajo para más información. | Ejemplo: `-0500` para la hora del este de EE.UU.
  `%Z` | La abreviación del desplazamiento horario. No implementado tal como se describe en Windows. Ver más abajo para más información. | Ejemplo: `EST` para la hora del este
  Hora y fecha | --- | ---
  `%c` | Fecha y hora preferidas, basadas en la localización | Ejemplo: `Tue Feb 5 00:45:10 2009` para el 5 de febrero de 2009 a las 12:45:10 AM
  `%D` | Idéntico a "`%m/%d/%y`" | Ejemplo: `02/05/09` para el 5 de febrero de 2009
  `%F` | Idéntico a "`%Y-%m-%d`" (usado habitualmente por las bases de datos) | Ejemplo: `2009-02-05` para el 5 de febrero de 2009
  `%s` | Timestamp de la época Unix (idéntico a la función time()) | Ejemplo: `305815200` para el 10 de septiembre de 1979 08:40:00 AM
  `%x` | Representación preferida de la fecha, basada en la localización, sin la hora | Ejemplo: `02/05/09` para el 5 de febrero de 2009
  Varios | --- | ---
  `%n` | Una nueva línea ("\n") | ---
  `%t` | Una tabulación ("\t") | ---
  `%%` | El carácter de porcentaje ("`%`") | ---

  Advertencia

  A diferencia de la norma `ISO-9899:1999`, Sun Solaris comienza con el Domingo a 1. También, el formato `%u` no funcionará tal como se describe en este manual.

  Advertencia

  Solo Windows:

  El modificador `%e` no es soportado bajo Windows. Para calcular el valor, el modificador `%#d` puede ser utilizado en su lugar. El ejemplo de abajo ilustra la manera de escribir un código multiplataforma.

  Los modificadores `%z` y `%Z` devuelven ambos el nombre de la zona horaria en lugar del desplazamiento o de la abreviación.

  Advertencia

  Solo macOS y musl: El modificador `%P` no es soportado por la implementación de esta función bajo macOS.

`timestamp`
  El parámetro opcional `timestamp` es un timestamp Unix de tipo int que por omisión es la hora actual local si `timestamp` es omitido o `null`. En otras palabras, es por omisión el valor de la función time().

### Valores devueltos

Devuelve una string formateada según el argumento `format` dado, utilizando el argumento `timestamp` o la fecha local actual si no se proporciona ningún timestamp. Los nombres de los meses, de los días de la semana pero también de otras cadenas dependientes de la localización, respetarán la localización actual definida por la función setlocale(). La función devuelve `false` si `format` está vacío, contiene especificadores de conversión no soportados, o si la longitud de la cadena devuelta sería mayor que `4095`.

### Errores/Excepciones

Cada llamada a una función de fecha/hora generará un diagnóstico de tipo `E_WARNING` si la zona horaria no es válida. Ver también date_default_timezone_set()

Dado que la salida depende de la biblioteca C subyacente, algunos especificadores de conversión no son soportados. Bajo Windows, el hecho de proporcionar un especificador de conversión desconocido devolverá 5 mensajes de nivel `E_WARNING` y devolverá `false` al final. Bajo otros sistemas operativos, no recibirá ningún mensaje de nivel `E_WARNING` y la salida contendrá los especificadores no convertidos.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `timestamp` ahora es nullable.

### Ejemplos

Este ejemplo solo funcionará si tiene las localizaciones respectivas instaladas en su sistema.

Ejemplo #1 Ejemplo con strftime()

    <?php
    setlocale(LC_TIME, "C");
    echo strftime("%A");
    setlocale(LC_TIME, "fi_FI");
    echo strftime(" in Finnish is %A,");
    setlocale(LC_TIME, "fr_FR");
    echo strftime(" in French %A and");
    setlocale(LC_TIME, "de_DE");
    echo strftime(" in German %A.\n");

Ejemplo #2 Ejemplo en formato de fecha ISO 8601:1988

    <?php
    /*     Diciembre 2002 / Enero 2003
    ISOWk  L   M   X   J   V   S   D
    ----- ----------------------------
    51     16  17  18  19  20  21  22
    52     23  24  25  26  27  28  29
    1      30  31   1   2   3   4   5
    2       6   7   8   9  10  11  12
    3      13  14  15  16  17  18  19   */

    // Muestra: 12/28/2002 - %V,%G,%Y = 52,2002,2002
    echo "12/28/2002 - %V,%G,%Y = " . strftime("%V,%G,%Y", strtotime("12/28/2002")) . "\n";

    // Muestra: 12/30/2002 - %V,%G,%Y = 1,2003,2002
    echo "12/30/2002 - %V,%G,%Y = " . strftime("%V,%G,%Y", strtotime("12/30/2002")) . "\n";

    // Muestra: 1/3/2003 - %V,%G,%Y = 1,2003,2003
    echo "1/3/2003 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/3/2003")) . "\n";

    // Muestra: 1/10/2003 - %V,%G,%Y = 2,2003,2003
    echo "1/10/2003 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/10/2003")) . "\n";

    /*     Diciembre 2004 / Enero 2005
    ISOWk  L   M   X   J   V   S   D
    ----- ----------------------------
    51     13  14  15  16  17  18  19
    52     20  21  22  23  24  25  26
    53     27  28  29  30  31   1   2
    1       3   4   5   6   7   8   9
    2      10  11  12  13  14  15  16   */

    // Muestra: 12/23/2004 - %V,%G,%Y = 52,2004,2004
    echo "12/23/2004 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("12/23/2004")) . "\n";

    // Muestra: 12/31/2004 - %V,%G,%Y = 53,2004,2004
    echo "12/31/2004 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("12/31/2004")) . "\n";

    // Muestra: 1/2/2005 - %V,%G,%Y = 53,2004,2005
    echo "1/2/2005 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/2/2005")) . "\n";

    // Muestra: 1/3/2005 - %V,%G,%Y = 1,2005,2005
    echo "1/3/2005 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/3/2005")) . "\n";

Ejemplo #3 `%e` funcionando en toda plataforma

    <?php

    // 1 de Enero: resultados en: '%e%1%' (%%, e, %%, %e, %%)
    $format = '%%e%%%e%%';

    // Verifica bajo Windows, para encontrar y reemplazar el modificador %e
    // correctamente
    if (strtoupper(substr(PHP_OS, 0, 3)) == 'WIN') {
        $format = preg_replace('#(?<!%)((?:%%)*)%e#', '\1%#d', $format);
    }

    echo strftime($format);

Ejemplo #4 Muestra todos los formatos conocidos o no

    <?php

    // Describe los formatos
    $strftimeFormats = array(
        'A' => 'Una representación textual completa del día',
        'B' => 'Nombre del mes completo, basado en la localización',
        'C' => 'Representación con 2 dígitos del año (año, dividido por 100, truncado a entero)',
        'D' => 'Idéntico a "%m/%d/%y"',
        'E' => '',
        'F' => 'Idéntico a "%Y-%m-%d"',
        'G' => 'La versión completa, con 4 dígitos de %g',
        'H' => 'Una representación con 2 dígitos de la hora en formato 24-horas',
        'I' => 'Una representación con 2 dígitos de la hora en formato 12-horas',
        'J' => '',
        'K' => '',
        'L' => '',
        'M' => 'Una representación con 2 dígitos de los minutos',
        'N' => '',
        'O' => '',
        'P' => '"am" o "pm" (en minúsculas) basado en la hora actual',
        'Q' => '',
        'R' => 'Idéntico a "%H:%M"',
        'S' => 'Una representación con 2 dígitos de los segundos',
        'T' => 'Idéntico a "%H:%M:%S"',
        'U' => 'Número de la semana para el año actual, comenzando por el primer Domingo como primera semana',
        'V'  => 'Número ISO-8601:1988 de la semana del año actual, comenzando por la primera semana del año con al menos 4 días de semana, con el Lunes como inicio de semana',
        'W' => 'Una representación numérica de la semana del año, comenzando por el primer Lunes como primera semana',
        'X' => 'Representación preferida para la hora, basada en la localización, sin la fecha',
        'Y' => 'Una representación con 4 dígitos del año',
        'Z' => 'La abreviación del desplazamiento horario, no proporcionada por %z (depende del sistema operativo)',
        'a' => 'La abreviación de la representación textual del día',
        'b' => 'La abreviación del nombre del mes, basada en la localización',
        'c' => 'Timestamp preferido basado en la localización',
        'd' => 'Día del mes con 2 dígitos (con el cero inicial)',
        'e' => 'Día del mes, con un espacio precediendo a un solo dígito',
        'f' => '',
        'g' => 'Una representación con 2 dígitos del año en formato ISO-8601:1988 (ver %V)',
        'h' => 'Abreviación del nombre del mes, basada en la localización (alias de %b)',
        'i' => '',
        'j' => 'Día del año, con 3 dígitos con cero inicial',
        'k' => 'Hora, en formato 24-horas, con un espacio precediendo a un solo dígito',
        'l' => 'Hora, en formato 12-horas, con un espacio precediendo a un solo dígito',
        'm' => 'Una representación del mes con 2 dígitos',
        'n' => 'Un carácter de nueva línea ("\n")',
        'o' => '',
        'p' => '"AM" o "PM" (en mayúsculas) basado en la hora actual',
        'q' => '',
        'r' => 'Idéntico a "%I:%M:%S %p"',
        's' => 'Timestamp respecto a la época Unix',
        't' => 'Un carácter de tabulación ("\t")',
        'u' => 'Representación numérica del día de la semana en formato ISO-8601',
        'v' => '',
        'w' => 'Representación numérica del día de la semana',
        'x' => 'Representación preferida de la fecha, basada en la localización, sin la hora',
        'y' => 'Representación del año con 2 dígitos',
        'z' => 'O bien el desplazamiento horario desde UTC o su abreviación (según el sistema operativo)',
        '%' => 'Un carácter porcentaje ("%")',
    );

    // Resultados
    $strftimeValues = array();

    // Evalúa los formatos suprimiendo los errores
    foreach ($strftimeFormats as $format => $description) {
        if (false !== ($value = @strftime("%{$format}"))) {
            $strftimeValues[$format] = $value;
        }
    }

    // Encuentra el valor más largo
    $maxValueLength = 2 + max(array_map('strlen', $strftimeValues));

    // Muestra todos los formatos conocidos
    foreach ($strftimeValues as $format => $value) {
        echo "Formato conocido: '{$format}' = ", str_pad("'{$value}'", $maxValueLength), " ( {$strftimeFormats[$format]} )\n";
    }

    // Muestra todos los formatos no conocidos
    foreach (array_diff_key($strftimeFormats, $strftimeValues) as $format => $description) {
        echo "Formato desconocido: '{$format}'   ", str_pad(' ', $maxValueLength), ($description ? " ( {$description} )" : ''), "\n";
    }

Resultado del ejemplo anterior es similar a:

    Formato conocido: 'A' = 'Friday'            ( Una representación textual completa del día )
    Formato conocido: 'B' = 'December'          ( Nombre del mes completo, basado en la localización )
    Formato conocido: 'H' = '11'                ( Una representación con 2 dígitos de la hora en formato 24-horas )
    Formato conocido: 'I' = '11'                ( Una representación con 2 dígitos de la hora en formato 12-horas )
    Formato conocido: 'M' = '24'                ( Una representación con 2 dígitos de los minutos )
    Formato conocido: 'S' = '44'                ( Una representación con 2 dígitos de los segundos )
    Formato conocido: 'U' = '48'                ( Número de la semana para el año actual, comenzando por el primer Domingo como primera semana )
    Formato conocido: 'W' = '48'                ( Una representación numérica de la semana del año, comenzando por el primer Lunes como primera semana )
    Formato conocido: 'X' = '11:24:44'          ( Representación preferida para la hora, basada en la localización, sin la fecha )
    Formato conocido: 'Y' = '2010'              ( Una representación con 4 dígitos del año )
    Formato conocido: 'Z' = 'GMT Standard Time' ( La abreviación del desplazamiento horario, no proporcionada por %z (depende del sistema operativo) )
    Formato conocido: 'a' = 'Fri'               ( La abreviación de la representación textual del día )
    Formato conocido: 'b' = 'Dec'               ( La abreviación del nombre del mes, basada en la localización )
    Formato conocido: 'c' = '12/03/10 11:24:44' ( Timestamp preferido basado en la localización )
    Formato conocido: 'd' = '03'                ( Día del mes con 2 dígitos (con el cero inicial) )
    Formato conocido: 'j' = '337'               ( Día del año, con 3 dígitos con cero inicial )
    Formato conocido: 'm' = '12'                ( Una representación del mes con 2 dígitos )
    Formato conocido: 'p' = 'AM'                ( "AM" o "PM" (en mayúsculas) basado en la hora actual )
    Formato conocido: 'w' = '5'                 ( Representación numérica del día de la semana )
    Formato conocido: 'x' = '12/03/10'          ( Representación preferida de la fecha, basada en la localización, sin la hora )
    Formato conocido: 'y' = '10'                ( Representación del año con 2 dígitos )
    Formato conocido: 'z' = 'GMT Standard Time' ( O bien el desplazamiento horario desde UTC o su abreviación (según el sistema operativo) )
    Formato conocido: '%' = '%'                 ( Un carácter porcentaje ("%") )
    Formato desconocido: 'C'                       ( Representación con 2 dígitos del año (año, dividido por 100, truncado a entero) )
    Formato desconocido: 'D'                       ( Idéntico a "%m/%d/%y" )
    Formato desconocido: 'E'
    Formato desconocido: 'F'                       ( Idéntico a "%Y-%m-%d" )
    Formato desconocido: 'G'                       ( La versión completa, con 4 dígitos de %g )
    Formato desconocido: 'J'
    Formato desconocido: 'K'
    Formato desconocido: 'L'
    Formato desconocido: 'N'
    Formato desconocido: 'O'
    Formato desconocido: 'P'                       ( "am" o "pm" (en minúsculas) basado en la hora actual )
    Formato desconocido: 'Q'
    Formato desconocido: 'R'                       ( Idéntico a "%H:%M" )
    Formato desconocido: 'T'                       ( Idéntico a "%H:%M:%S" )
    Formato desconocido: 'V'                       ( Número ISO-8601:1988 de la semana del año actual, comenzando por la primera semana del año con al menos 4 días de semana, con el Lunes como inicio de semana )
    Formato desconocido: 'e'                       ( Día del mes, con un espacio precediendo a un solo dígito )
    Formato desconocido: 'f'
    Formato desconocido: 'g'                       ( Una representación con 2 dígitos del año en formato ISO-8601:1988 (ver %V) )
    Formato desconocido: 'h'                       ( Abreviación del nombre del mes, basada en la localización (alias de %b) )
    Formato desconocido: 'i'
    Formato desconocido: 'k'                       ( Hora, en formato 24-horas, con un espacio precediendo a un solo dígito )
    Formato desconocido: 'l'                       ( Hora, en formato 12-horas, con un espacio precediendo a un solo dígito )
    Formato desconocido: 'n'                       ( Un carácter de nueva línea ("\n") )
    Formato desconocido: 'o'
    Formato desconocido: 'q'
    Formato desconocido: 'r'                       ( Idéntico a "%I:%M:%S %p" )
    Formato desconocido: 's'                       ( Timestamp respecto a la época Unix )
    Formato desconocido: 't'                       ( Un carácter de tabulación ("\t") )
    Formato desconocido: 'u'                       ( Representación numérica del día de la semana en formato ISO-8601 )
    Formato desconocido: 'v'

### Notas

> Nota: `%G` y `%V`, que están basadas en la semana `ISO 8601:1988`, pueden conducir a resultados inesperados (aunque correctos) si el sistema de numeración no es conocido. Ver el ejemplo `%V` de esta página.

### Ver también

- IntlDateFormatter::format() - Formatea la fecha y la hora como string
- DateTimeInterface::format() - Retorna una fecha formateada según el formato proporcionado
- » Herramienta de formato strftime() en línea
- setlocale() - Establece la información de configuración local
- mktime() - Obtener la marca de tiempo Unix de una fecha
- strptime() - Analiza una fecha/hora generada con strftime
- gmstrftime() - Formatea una fecha/hora GMT/TUC según la configuración local
- » grupo de especificaciones de strftime()

# strptime

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

strptime — Analiza una fecha/hora generada con strftime()

Advertencia

Esta función está OBSOLETA a partir de PHP 8.1.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function strptime(string `$timestamp`, string `$format`): array|false

strptime() devuelve un array con la fecha `timestamp` analizada, o false si se produjo un error.

Los nombres del mes y del día de la semana y otras cadenas dependientes del lenguaje están subordinados a la configuración regional local establecida con setlocale() (LC_TIME).

### Parámetros

`timestamp` (string)

  La cadena a analizar (p.ej. devuelta por strftime()).

`format` (string)

  El formato usado en `timestamp` (p.ej. el mismo que el usado en strftime()). Observe que algunas de las opciones de formato disponibles en strftime() pueden no tener ningún efecto en strptime(); el subconjunto exacto que está soportado variará según el sistema operativo y a la biblioteca de C que esté en uso.

  Para más información sobre las opciones de formato, lea la página de strftime().

### Valores devueltos

Devuelve un array o `false` si ocurre un error.

Los siguientes parámetros son devueltos en el array
parámetros | Descripción
--- | ---
`"tm_sec"` | Segundos después del minuto (0-61)
`"tm_min"` | Minutos después de la hora (0-59)
`"tm_hour"` | Hora desde la medianoche (0-23)
`"tm_mday"` | Día del mes (1-31)
`"tm_mon"` | Meses desde Enero (0-11)
`"tm_year"` | Años desde 1900
`"tm_wday"` | Días desde el Domingo (0-6)
`"tm_yday"` | Días desde el 1 de Enero (0-365)
`"unparsed"` | la parte de `timestamp` que no fue reconocida usando el formato `format` especificado

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Esta función ha sido marcada como obsoleta. Use date_parse_from_format() en su lugar (para análisis independiente de la localización), o IntlDateFormatter::parse() (para análisis dependiente de la localización)

### Ejemplos

Ejemplo #1 Ejemplo de strptime()

    <?php
    $format = '%d/%m/%Y %H:%M:%S';
    $strf = strftime($format);

    echo "$strf\n";

    print_r(strptime($strf, $format));

Resultado del ejemplo anterior es similar a:

    03/10/2004 15:54:19

    Array
    (
        [tm_sec] => 19
        [tm_min] => 54
        [tm_hour] => 15
        [tm_mday] => 3
        [tm_mon] => 9
        [tm_year] => 104
        [tm_wday] => 0
        [tm_yday] => 276
        [unparsed] =>
    )

### Notas

> Nota: Esta función no está implementada en las plataformas Windows.

> Nota:

> Internamente, esta función llama a la función `strptime()` proporcionada por la biblioteca C del sistema. Esta función puede presentar diferencias notables de comportamiento en diferentes sistemas operativos. Se recomienda el uso de date_parse_from_format(), a la cuál no le afectan estas cosas.

> Nota:

> `"tm_sec"` incluye segundos intercalares (actualmente hasta 2 por año). Para más información acerca de los segundos intercalares, vea el » artículo de Wikipedia sobre segundos intercalares.

### Ver también

- IntlDateFormatter::parse() - Analiza una cadena hacia un timestamp
- DateTime::createFromFormat() - Analiza una cadena con un instante según un formato especificado
- checkdate() - Valida una fecha gregoriana
- strftime() - Formatea una fecha/hora local con la configuración local
- date_parse_from_format() - Recupera las informaciones de una fecha dada siguiendo un formato específico

# strtotime

(PHP 4, PHP 5, PHP 7, PHP 8)

strtotime — Transforma un texto inglés en timestamp

### Descripción

function strtotime(string `$datetime`, ?int `$baseTimestamp` = `null`): int|false

La función espera recibir una cadena que contiene una fecha en inglés e intentará leerla y transformarla en un timestamp Unix (el número de segundos desde el 1 de enero de 1970 a 00:00:00 UTC), relativo al timestamp `baseTimestamp`, o a la fecha actual si este último es omitido. El análisis de la cadena de fecha está definido en los formatos de fecha y hora y presenta varias consideraciones sutiles. Se recomienda encarecidamente examinar todos los detalles.

Advertencia

El timestamp Unix que devuelve esta función no contiene información sobre los husos horarios. Para realizar cálculos con información de fecha/hora, es preferible utilizar DateTimeImmutable que es más capaz.

Cada parámetro de la función utiliza el desplazamiento horario por defecto a menos que se especifique explícitamente un desplazamiento horario. Tenga cuidado de no utilizar un desplazamiento horario diferente para cada parámetro a menos que sea lo que se necesita. Consulte la función date_default_timezone_get() para saber cómo definir un desplazamiento horario por defecto.

### Parámetros

`datetime`

  Una cadena de fecha/hora. Los formatos válidos son explicados en la documentación sobre los formatos de Fecha y Hora.

`baseTimestamp`

  El timestamp, que representa la fecha actual, utilizado para el cálculo relativo de fechas.

### Valores devueltos

Devuelve un timestamp en caso de éxito, `false` en caso contrario.

### Errores/Excepciones

Cada llamada a una función de fecha/hora generará un diagnóstico de tipo `E_WARNING` si la zona horaria no es válida. Ver también date_default_timezone_set()

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `baseTimestamp` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con strtotime()

    <?php
    echo strtotime("now"), "\n";
    echo strtotime("10 September 2000"), "\n";
    echo strtotime("+1 day"), "\n";
    echo strtotime("+1 week"), "\n";
    echo strtotime("+1 week 2 days 4 hours 2 seconds"), "\n";
    echo strtotime("next Thursday"), "\n";
    echo strtotime("last Monday"), "\n";

Ejemplo #2 Verificación de error

    <?php
    $str = 'No es válido';

    if (($timestamp = strtotime($str)) === false) {
       echo "La cadena ($str) está corrupta";
    } else {
       echo "$str == " . date('l dS \o\f F Y h:i:s A', $timestamp);
    }

### Notas

> Nota:

> En este caso, la fecha "relativa" significa también que si un componente particular del timestamp no es proporcionado, será extraído textualmente de `baseTimestamp`. En otras palabras, `strtotime('February')`, si se ejecuta el 31 de mayo de 2022, será interpretado como el `31 de febrero de 2022`, lo que desbordará a un timestamp el `3 de marzo`. (En un año bisiesto, sería el `2 de marzo`.) El uso de `strtotime('1 February')` o `strtotime('first day of February')` evitaría este problema.

> Nota:

> Si el número de años se especifica en dos dígitos, los valores entre 00-69 corresponden a 2000-2069 y 70-99 a 1970-1999. Consulte las notas posteriores sobre las posibles diferencias entre sistemas de 32 bits (las fechas pueden fallar después del 19/01/2038 a 03:14:07).

> Nota:

> El intervalo de validez de un timestamp va del Viernes 13 de diciembre de 1901 20:45:54 UTC al Martes 19 de enero de 2038 03:14:07 UTC. (Esto corresponde a las fechas máximas y mínimas para un entero de 32 bits firmado).

> Para las versiones de 64 bits de PHP, el intervalo válido de un timestamp es realmente infinito, sabiendo que 64 bits puede representar aproximadamente 293 mil millones de años en cualquier dirección.

> Nota:

> El uso de esta función en operaciones matemáticas no está recomendado. Es preferible utilizar en este caso DateTime::add() y DateTime::sub().

### Ver también

- DateTimeImmutable
- DateTimeImmutable::createFromFormat() - Analiza un string de tiempo según el formato especificado
- Los formatos sobre fechas
- checkdate() - Valida una fecha gregoriana
- strptime() - Analiza una fecha/hora generada con strftime

# time

(PHP 4, PHP 5, PHP 7, PHP 8)

time — Devuelve el timestamp UNIX actual

### Descripción

function time(): int

Devuelve la hora actual medida en el número de segundos desde el inicio de la época UNIX (1 de enero de 1970 00:00:00 GMT).

> Nota:

> Los timestamps Unix no contienen información alguna sobre el huso horario local. Se recomienda utilizar la clase DateTimeImmutable para manipular información relativa a la fecha y la hora, a fin de evitar los problemas asociados a los timestamps Unix.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el timestamp actual.

### Ejemplos

Ejemplo #1 Ejemplo con time()

    <?php
    echo 'Hoy : '. time();

Resultado del ejemplo anterior es similar a:

    Hoy : 1660338149

### Notas

Sugerencia

Un timestamp que representa el inicio de la petición está disponible en la variable $_SERVER['REQUEST_TIME'].

### Ver también

- DateTimeImmutable
- date() - Da formato a una marca de tiempo de Unix (Unix timestamp)
- microtime() - Devuelve el timestamp UNIX actual con microsegundos

# timezone_abbreviations_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_abbreviations_list — Alias de DateTimeZone::listAbbreviations()

### Descripción

Esta función es un alias de: DateTimeZone::listAbbreviations()

# timezone_identifiers_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_identifiers_list — Alias de DateTimeZone::listIdentifiers()

### Descripción

Esta función es un alias de: DateTimeZone::listIdentifiers()

# timezone_location_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

timezone_location_get — Alias de DateTimeZone::getLocation()

### Descripción

Esta función es un alias de: DateTimeZone::getLocation()

# timezone_name_from_abbr

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

timezone_name_from_abbr — Devuelve el nombre de una zona horaria a partir de su abreviatura y del desplazamiento UTC

### Descripción

function timezone_name_from_abbr(string `$abbr`, int `$utcOffset` = -1, int `$isDST` = -1): string|false

### Parámetros

`abbr`

  Abreviatura de la zona horaria.

`utcOffset`

  Desplazamiento respecto al GMT en segundos. El valor por omisión es -1 lo que significa que se devuelve la primera zona horaria encontrada que corresponda a `abbr`. De lo contrario, se busca el desplazamiento exacto y solo si no se encuentra, se devuelve la primera zona horaria con cualquier desplazamiento.

`isDST`

  Indicador de hora de verano/hora de invierno. Por omisión -1 que significa que el desplazamiento de hora de verano/hora de invierno no se tiene en cuenta en la búsqueda aunque la zona horaria lo gestione. Si se establece en 1, entonces el `utcOffset` se asume que incluye el desplazamiento de hora de verano /hora de invierno; si es 0 entonces `utcOffset` se asume que representa un desplazamiento que no tiene en cuenta la hora de verano/invierno. Si `abbr` no existe entonces la zona horaria se busca únicamente mediante `utcOffset` y `isDST`.

### Valores devueltos

Devuelve un nombre de zona horaria en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con timezone_name_from_abbr()

    <?php
    echo timezone_name_from_abbr("CET") . "\n";
    echo timezone_name_from_abbr("", 3600, 0) . "\n";

Resultado del ejemplo anterior es similar a:

    Europe/Berlin
    Europe/Paris

### Ver también

- timezone_abbreviations_list() - Alias de DateTimeZone::listAbbreviations

# timezone_name_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_name_get — Alias de DateTimeZone::getName()

### Descripción

Esta función es un alias de: DateTimeZone::getName()

# timezone_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_offset_get — Alias de DateTimeZone::getOffset()

### Descripción

Esta función es un alias de: DateTimeZone::getOffset()

# timezone_open

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_open — Alias de DateTimeZone::__construct()

### Descripción

Esta función es un alias de: DateTimeZone::__construct()

# timezone_transitions_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_transitions_get — Alias de DateTimeZone::getTransitions()

### Descripción

Esta función es un alias de: DateTimeZone::getTransitions()

# timezone_version_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

timezone_version_get — Lee la versión de la timezonedb

### Descripción

function timezone_version_get(): string

Devuelve la versión actual de la timezonedb.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un string en formato `YYYY.increment`, como `2022.2`.

Si se tiene una versión antigua de la base de datos de zonas horarias (por ejemplo, no muestra el año actual), se pueden actualizar las informaciones de zona horaria actualizando la versión de PHP o instalando el paquete PECL » timezonedb PECL.

Algunas distribuciones Linux corrigen el soporte de fecha/hora de PHP para usar una fuente alternativa para las informaciones de zona horaria. En este caso, esta función devolverá `0.system`. Asimismo, se recomienda instalar el paquete PECL » timezonedb en este caso.

### Ejemplos

Ejemplo #1 Lectura de la versión de la timezonedb

    <?php
    echo timezone_version_get();

Resultado del ejemplo anterior es similar a:

    2022.2

### Ver también

- Lista de zonas horarias válidas

## Tabla de contenidos

- checkdate — Valida una fecha gregoriana
- date — Da formato a una marca de tiempo de Unix (Unix timestamp)
- date_add — Alias de DateTime::add
- date_create — Creación de un objeto DateTime
- date_create_from_format — Alias de DateTime::createFromFormat
- date_create_immutable — Crea un nuevo objeto DateTimeImmutable
- date_create_immutable_from_format — Alias de DateTimeImmutable::createFromFormat
- date_date_set — Alias de DateTime::setDate
- date_default_timezone_get — Recupera el huso horario por defecto utilizado por todas las funciones de fecha/hora de un script
- date_default_timezone_set — Establece la zona horaria por defecto para todas las funciones de fecha/hora
- date_diff — Alias de DateTime::diff
- date_format — Alias de DateTime::format
- date_get_last_errors — Alias de DateTimeImmutable::getLastErrors
- date_interval_create_from_date_string — Alias de DateInterval::createFromDateString
- date_interval_format — Alias de DateInterval::format
- date_isodate_set — Alias de DateTime::setISODate
- date_modify — Alias de DateTime::modify
- date_offset_get — Alias de DateTime::getOffset
- date_parse — Retorna un array asociativo con información detallada sobre una fecha/hora dada
- date_parse_from_format — Recupera las informaciones de una fecha dada siguiendo un formato específico
- date_sub — Alias de DateTime::sub
- date_sun_info — Retorna un array con las informaciones sobre el amanecer/atardecer así como el inicio y el fin del amanecer
- date_sunrise — Devuelve la hora de salida del sol para un día y un lugar dados
- date_sunset — Devuelve la hora de puesta del sol para un día y un lugar dados
- date_time_set — Alias de DateTime::setTime
- date_timestamp_get — Alias de DateTime::getTimestamp
- date_timestamp_set — Alias de DateTime::setTimestamp
- date_timezone_get — Alias de DateTime::getTimezone
- date_timezone_set — Alias de DateTime::setTimezone
- getdate — Devuelve la fecha/hora
- gettimeofday — Devuelve la hora actual
- gmdate — Formatea una fecha/hora GMT/TUC
- gmmktime — Retorna el timestamp UNIX de una fecha GMT
- gmstrftime — Formatea una fecha/hora GMT/TUC según la configuración local
- idate — Formatea una parte de la hora/fecha local como un entero
- localtime — Obtiene la hora local
- microtime — Devuelve el timestamp UNIX actual con microsegundos
- mktime — Obtener la marca de tiempo Unix de una fecha
- strftime — Formatea una fecha/hora local con la configuración local
- strptime — Analiza una fecha/hora generada con strftime
- strtotime — Transforma un texto inglés en timestamp
- time — Devuelve el timestamp UNIX actual
- timezone_abbreviations_list — Alias de DateTimeZone::listAbbreviations
- timezone_identifiers_list — Alias de DateTimeZone::listIdentifiers
- timezone_location_get — Alias de DateTimeZone::getLocation
- timezone_name_from_abbr — Devuelve el nombre de una zona horaria a partir de su abreviatura y del desplazamiento UTC
- timezone_name_get — Alias de DateTimeZone::getName
- timezone_offset_get — Alias de DateTimeZone::getOffset
- timezone_open — Alias de DateTimeZone::__construct
- timezone_transitions_get — Alias de DateTimeZone::getTransitions
- timezone_version_get — Lee la versión de la timezonedb

# Errores y Excepciones Fecha/Hora

- DateError (extiende Error)
  - DateObjectError DateRangeError
- DateException (extiende Exception)
  - - DateInvalidOperationException
    - DateInvalidTimezoneException
    - DateMalformedIntervalStringException
    - DateMalformedPeriodStringException
    - DateMalformedStringException

# Formatos soportados de tiempo y fechas

Esta sección describe, en un formato de tipo BNF, todos los formatos diferentes que el analizador de DateTimeImmutable, DateTime, date_create_immutable(), date_create(), date_parse(), y strtotime() es capaz de comprender. Los formatos están agrupados por secciones. En la mayoría de los casos, los formatos de secciones diferentes, separados por caracteres de espacio en blanco, comas o puntos, pueden ser utilizados en la misma cadena fecha/hora. Para cada formato soportado, se dan uno o varios ejemplos así como una descripción del formato correspondiente. Los caracteres entre comillas simples para los formatos son insensibles a la mayúscula/minúscula (`'t'` podría escribirse `t` o `T`), los caracteres escritos entre comillas dobles, ellos, son sensibles a la mayúscula/minúscula (`"T"` y solo `T`).

Para formatear objetos DateTimeImmutable y DateTime, por favor refiérase a la documentación del método DateTimeInterface::format().

Un conjunto de reglas generales debería ser tenido en cuenta.

1. El analizador, permite a cada unidad (año, mes, día, hora, minuto, segundo) el rango completo de valores. Para un año son solo 4 dígitos, para un mes es 0-12, para un día 0-31 y para la hora y los minutos es 0-59.
2. 60 es permitido para los segundos, ya que a veces cadenas de fechas con este segundo intercalar aparecen. Pero PHP implementa el tiempo Unix donde "60" no es un número de segundos válido y, por tanto, desborda.
3. strtotime() devuelve `false` si un número está fuera del rango, y DateTimeImmutable::__construct() lanza una excepción.
4. Si una cadena contiene una fecha, todos los elementos son puestos a 0.
5. Todos los elementos de tiempo menos significativos son puestos a 0 si cualquier elemento de un tiempo está presente en la cadena dada.
6. El analizador es tonto, y no efectúa verificación para hacerlo más rápido (y más genérico).
7. Además de las reglas aplicables a los elementos temporales individuales, el analizador comprende también formatos compuestos más específicos, tales como el análisis de timestamps Unix (`@1690388256`) y fechas semanales ISO (`2008-W28-3`).

8. Hay una verificación adicional si una fecha inválida es proporcionada:

       <?php
       $res = date_parse("2015-09-31");
       var_dump($res["warnings"]);

   El ejemplo anterior mostrará:

       array(1) {
         [11] =>
         string(27) "The parsed date was invalid"
       }

9. Es ya posible manejar estos casos especiales, pero el uso de DateTimeImmutable::createFromFormat() es requerido proporcionando el formato deseado.

       <?php
       $res = DateTimeImmutable::createFromFormat("Y-m-d", "2015-09-34");
       var_dump($res);

   El ejemplo anterior mostrará:

       object(DateTimeImmutable)#1 (3) {
         ["date"] =>
         string(26) "2015-10-04 17:24:43.000000"
         ["timezone_type"] =>
         int(3)
         ["timezone"] =>
         string(13) "Europe/London"
       }

## Formatos para los tiempos (Time)

Esta página describe los diferentes formatos en una sintaxis de tipo BNF que los analizadores de DateTimeImmutable, DateTime, date_create(), date_create_immutable(), y strtotime() comprenden.

Para formatear objetos DateTimeImmutable y DateTime, por favor refiérase a la documentación del método DateTimeInterface::format().

Símbolos utilizados
Descripción | Formatos | Ejemplos
--- | --- | ---
`frac` | . [0-9]+ | ".21342", ".85"
`hh` | "0"?[1-9] | "1"[0-2] | "04", "7", "12"
`HH` | [01][0-9] | "2"[0-4] | "04", "07", "19"
`meridiem` | [AaPp] .? [Mm] .? [\0\t ] | "A.m.", "pM", "am."
`MM` | [0-5][0-9] | "00", "12", "59"
`II` | [0-5][0-9] | "00", "12", "59"
`espacio` | [ \t] |
`tz` | "("? [A-Za-z]{1,6} ")"? | [A-Z][a-z]+([_/][A-Z][a-z]+)+ | "CEST", "Europe/Amsterdam", "America/Indiana/Knox"
`tzcorrection` | "GMT"? [+-] `hh` ":"? `MM`? | "+0400", "GMT-07:00", "-07:00"

Notación de 12 horas
Descripción | Formato | Ejemplos
--- | --- | ---
Horas solas, con meridiem | `hh` `espacio`? `meridiem` | "4 am", "5PM"
Horas y minutos, con meridiem | `hh` [.:] `MM` `espacio`? `meridiem` | "4:08 am", "7:19P.M."
Horas, minutos y segundos con meridiem | `hh` [.:] `MM` [.:] `II` `espacio`? `meridiem` | "4:08:37 am", "7:19:19P.M."
MS SQL (Horas, minutos, segundos y fracción con meridiem) | `hh` ":" `MM` ":" `II` [.:] [0-9]+ `meridiem` | "4:08:39:12313am"

Notación de 24 horas
Descripción | Formato | Ejemplos
--- | --- | ---
Horas y minutos | 't'? `HH` [.:] `MM` | "04:08", "19.19", "T23:43"
Horas y minutos, sin dos puntos | 't'? `HH` `MM` | "0408", "t1919", "T2343"
Horas, minutos y segundos | 't'? `HH` [.:] `MM` [.:] `II` | "04.08.37", "t19:19:19"
Horas, minutos y segundos, sin dos puntos | 't'? `HH` `MM` `II` | "040837", "T191919"
Horas, minutos, segundos y zona horaria | 't'? `HH` [.:] `MM` [.:] `II` `espacio`? ( `tzcorrection` | `tz` ) | "040837CEST", "T191919-0700"
Horas, minutos, segundos y fracción | 't'? `HH` [.:] `MM` [.:] `II` `frac` | "04.08.37.81412", "19:19:19.532453"
Información de zona horaria | `tz` | `tzcorrection` | "CEST", "Europe/Amsterdam", "+0430", "GMT-06:00"

## Formatos de fechas

Esta página describe los diferentes formatos en una sintaxis de tipo BNF que los analizadores de DateTimeImmutable, DateTime, date_create(), date_create_immutable(), y strtotime() comprenden.

Para formatear objetos DateTimeImmutable y DateTime, por favor refiérase a la documentación del método DateTimeInterface::format().

Símbolos utilizados
Descripción | Formato | Ejemplos
--- | --- | ---
`sufijo de días` | "st" | "nd" | "rd" | "th" |
`dd` | ([0-2]?[0-9] | "3"[01]) `daysuf`? | "7th", "22nd", "31"
`DD` | "0" [0-9] | [1-2][0-9] | "3" [01] | "07", "31"
`m` | 'january' | 'february' | 'march' | 'april' | 'may' | 'june' | 'july' | 'august' | 'september' | 'october' | 'november' | 'december' | 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' | "I" | "II" | "III" | "IV" | "V" | "VI" | "VII" | "VIII" | "IX" | "X" | "XI" | "XII" |
`M` | 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' |
`mm` | "0"? [0-9] | "1"[0-2] | "0", "04", "7", "12"
`MM` | "0" [0-9] | "1"[0-2] | "00", "04", "07", "12"
`y` | [0-9]{1,4} | "00", "78", "08", "8", "2008"
`yy` | [0-9]{2} | "00", "08", "78"
`YY` | [0-9]{4} | "2000", "2008", "1978"
`YYY` | [0-9]{5,19} | "81412", "20192"

Formatos estándar
Descripción | Ejemplos
--- | ---
ATOM | "2022-06-02T16:58:35+00:00"
COOKIE | "Thursday, 02-Jun-2022 16:58:35 UTC"
ISO8601 | "2022-06-02T16:58:35+0000"
» RFC 822 | "Thu, 02 Jun 22 16:58:35 +0000"
» RFC 850 | "Thursday, 02-Jun-22 16:58:35 UTC"
» RFC 1036 | "Thu, 02 Jun 22 16:58:35 +0000"
» RFC 1123 | "Thu, 02 Jun 2022 16:58:35 +0000"
» RFC 2822 | "Thu, 02 Jun 2022 16:58:35 +0000"
» RFC 3339 | "2022-06-02T16:58:35+00:00"
» RFC 3339 Extended | "2022-06-02T16:58:35.698+00:00"
» RFC 7231 | "Thu, 02 Jun 2022 16:58:35 GMT"
RSS | "Thu, 02 Jun 2022 16:58:35 +0000"
W3C | "2022-06-02T16:58:35+00:00"

Notaciones localizadas
Descripción | Formato | Ejemplos
--- | --- | ---
Mes americano y día | `mm` "/" `dd` | "5/12", "10/27"
Mes americano, día y año | `mm` "/" `dd` "/" `y` | "12/22/78", "1/17/2006", "1/17/6"
Año de cuatro dígitos, mes y día con slashes | `YY` "/" `mm` "/" `dd` | "2008/6/30", "1978/12/22"
Año de cuatro dígitos y mes (GNU) | `YY` "-" `mm` | "2008-6", "2008-06", "1978-12"
Año, mes y día con guiones | `y` "-" `mm` "-" `dd` | "2008-6-30", "78-12-22", "8-6-21"
Día, mes y año de dos dígitos, con puntos, tabulaciones o guiones | `dd` [.\t-] `mm` [.-] `YY` | "30-6-2008", "22.12.1978"
Día, mes y año de dos dígitos, con puntos o tabulaciones | `dd` [.\t] `mm` "." `yy` | "30.6.08", "22\t12.78"
Día, mes textual y año | `dd` ([ \t.-])* `m` ([ \t.-])* `y` | "30-June 2008", "22DEC78", "14 III 1879"
Mes textual y año de cuatro dígitos (el día será el 1) | `m` ([ \t.-])* `YY` | "June 2008", "DEC1978", "March 1879"
Año de cuatro dígitos y mes textual (el día será el 1) | `YY` ([ \t.-])* `m` | "2008 June", "1978-XII", "1879.MArCH"
Mes textual, día y año | `m` ([ .\t-])* `dd` [,.stndrh\t ]+ `y` | "July 1st, 2008", "April 17, 1790", "May.9,78"
Mes textual y día | `m` ([ .\t-])* `dd` [,.stndrh\t ]* | "July 1st,", "Apr 17", "May.9"
Día y mes textual | `dd` ([ .\t-])* `m` | "1 July", "17 Apr", "9.May"
Mes abreviado, día y año | `M` "-" `DD` "-" `y` | "May-09-78", "Apr-17-1790"
Año, mes abreviado y día | `y` "-" `M` "-" `DD` | "78-Dec-22", "1814-MAY-17"
Año (y solo el año) | `YY` | "1978", "2008"
Año (desarrollado, 5-19 dígitos con signo) | [+-] `YYY` | "-81120", "+20192"
Mes textual (y solo el mes) | `m` | "March", "jun", "DEC"

Notaciones ISO8601
Descripción | Formato | Ejemplos
--- | --- | ---
Año, mes y día de ocho dígitos | `YY` `MM` `DD` | "15810726", "19780417", "18140517"
Año de cuatro dígitos, mes y día con slashes | `YY` "/" `MM` "/" `DD` | "2008/06/30", "1978/12/22"
Año de dos dígitos, mes y día con guiones | `yy` "-" `MM` "-" `DD` | "08-06-30", "78-12-22"
Año de cuatro dígitos con signo opcional, mes y día | [+-]? `YY` "-" `MM` "-" `DD` | "-0002-07-26", "+1978-04-17", "1814-05-17"
Año de cinco dígitos con signo, mes y día requeridos | [+-] `YYY` "-" `MM` "-" `DD` | "-81120-02-26", "+20192-04-17"

> Nota:

> Para los formatos `y` y `yy`, los años antes de 100 son considerados de una manera especial cuando los símbolos `y` o `yy` son utilizados. Si el año está entre 0 (inclusivo) y 69 (inclusivo), 2000 será añadido. Si el año está entre 70 (inclusivo) y 99 (inclusivo) entonces 1900 será añadido. Esto significa que "00-01-01" es interpretado como "2000-01-01".

> Nota:

> El formato "Día, mes y año de dos dígitos con tabulaciones o puntos" (`dd` [.\t] `mm` "." `yy`) solo funciona para valores de año de 61 (inclusivo) a 99 (inclusivo) - fuera de estos límites, el formato de tiempo "`HH` [.:] `MM` [.:] `SS`" tiene una precedencia más fuerte y prima.

> Nota:

> El formato "Año (y solo el año)" solo funciona de manera fiable si una cadena de tiempo ya ha sido encontrada. De lo contrario, si el año de cuatro dígitos coincide con `HH` `MM`, estos dos elementos de fecha son definidos en su lugar.

> Para analizar de manera coherente solo un año, utilice DateTimeImmutable::createFromFormat() con el especificador `Y`.

Precaución

Es posible añadir o restar un préstamo para los formatos `dd` y `DD`. El día 0 significa el último día del mes anterior, los préstamos positivos contarán el mes siguiente. Así, "2008-08-00" es equivalente a "2008-07-31" y "2008-06-31" es equivalente a "2008-07-01" (junio solo tiene 30 días).

Es de notar que el rango de día está limitado a 0-31 como indicado por la expresión regular anterior. Así, "2008-06-32" no es una cadena de fecha válida, por ejemplo.

También es posible jugar con los préstamos de los formatos `mm` y `MM` gracias al valor 0. Un valor de mes de 0 significa Diciembre del año anterior. Por ejemplo "2008-00-22" es equivalente a "2007-12-22".

Si combina las dos nociones anteriores y utiliza un préstamo negativo en el día y el mes, entonces ocurre esto: "2008-00-00" es convertido primero hacia "2007-12-00" luego hacia "2007-11-30". Esto también ocurre con la cadena "0000-00-00" que es entonces transformada hacia "-0001-11-30" (el año -1 en el calendario ISO 8601, que es 2 BC en el calendario Gregoriano).

## Formatos compuestos

Esta página describe los diferentes formatos en una sintaxis de tipo BNF que los analizadores de DateTimeImmutable, DateTime, date_create(), date_create_immutable(), y strtotime() comprenden.

Para formatear objetos DateTimeImmutable y DateTime, por favor refiérase a la documentación del método DateTimeInterface::format().

Símbolos utilizados
Descripción | Formatos | Ejemplos
--- | --- | ---
`DD` | "0" [0-9] | [1-2][0-9] | "3" [01] | "02", "12", "31"
`doy` | "00"[1-9] | "0"[1-9][0-9] | [1-2][0-9][0-9] | "3"[0-5][0-9] | "36"[0-6] | "001", "012", "180", "350", "366"
`frac` | . [0-9]+ | ".21342", ".85"
`hh` | "0"?[1-9] | "1"[0-2] | "04", "7", "12"
`HH` | [01][0-9] | "2"[0-4] | "04", "07", "19"
`meridiem` | [AaPp] .? [Mm] .? [\0\t ] | "A.m.", "pM", "am."
`ii` | [0-5]?[0-9] | "04", "8", "59"
`II` | [0-5][0-9] | "04", "08", "59"
`M` | 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' |
`MM` | [0-1][0-9] | "00", "12"
`espacio` | [ \t] |
`ss` | ([0-5]?[0-9])|60 | "04", "8", "59", "60" (segundo intercalar)
`SS` | [0-5][0-9] | "04", "08", "59"
`W` | "0"[1-9] | [1-4][0-9] | "5"[0-3] | "05", "17", "53"
`tzcorrection` | "GMT"? [+-] `hh` ":"? `II`? | "+0400", "GMT-07:00", "-07:00"
`YY` | [0-9]{4} | "2000", "2008", "1978"

Notaciones localizadas
Descripción | Formato | Ejemplos
--- | --- | ---
Formato de log común | `dd` "/" `M` "/" `YY` : `HH` ":" `II` ":" `SS` `espacio` `tzcorrection` | "10/Oct/2000:13:55:36 -0700"
EXIF | `YY` ":" `MM` ":" `DD` " " `HH` ":" `II` ":" `SS` | "2008:08:07 18:11:31"
Año ISO con semana ISO | `YY` "-"? "W" `W` | "2008W27", "2008-W28"
Año ISO con semana ISO y día | `YY` "-"? "W" `W` "-"? [0-7] | "2008W273", "2008-W28-3"
MySQL | `YY` "-" `MM` "-" `DD` " " `HH` ":" `II` ":" `SS` | "2008-08-07 18:11:31"
PostgreSQL: Año con día del año | `YY` "."? `doy` | "2008.197", "2008197"
SOAP | `YY` "-" `MM` "-" `DD` "T" `HH` ":" `II` ":" `SS` `frac` `tzcorrection`? | "2008-07-01T22:35:17.02", "2008-07-01T22:35:17.03+08:00"
Timestamp Unix | "@" "-"? [0-9]+ | "@1215282385"
Timestamp Unix con microsegundos | "@" "-"? [0-9]+ "." [0-9]{0,6} | "@1607974647.503686"
XMLRPC | `YY` `MM` `DD` "T" `hh` ":" `II` ":" `SS` | "20080701T22:38:07", "20080701T9:38:07"
XMLRPC (Compacto) | `YY` `MM` `DD` 't' `hh` `II` `SS` | "20080701t223807", "20080701T093807"
WDDX | `YY` "-" `mm` "-" `dd` "T" `hh` ":" `ii` ":" `ss` | "2008-7-1T9:3:37"

> Nota:

> El "W" en los formatos "Año ISO con semana ISO" y "Año ISO con semana ISO y día" es sensible a la mayúscula/minúscula; solo puede utilizarse la mayúscula "W".

> El "T" en los formatos SOAP, XMRPC y WDDX es sensible a la mayúscula/minúscula; utilice siempre la mayúscula "T".

> El formato timestamp Unix define la zona horaria a UTC.

## Formatos relativos

Esta página describe los diferentes formatos en una sintaxis de tipo BNF que los analizadores de DateTimeImmutable, DateTime, date_create(), date_create_immutable(), y strtotime() comprenden.

Para formatear objetos DateTimeImmutable y DateTime, por favor refiérase a la documentación del método DateTimeInterface::format().

Símbolos utilizados
Descripción | Formato
--- | ---
`dayname` | 'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
`daytext` | 'weekday' | 'weekdays'
`number` | [+-]?[0-9]+
`ordinal` | 'first' | 'second' | 'third' | 'fourth' | 'fifth' | 'sixth' | 'seventh' | 'eighth' | 'ninth' | 'tenth' | 'eleventh' | 'twelfth' | 'next' | 'last' | 'previous' | 'this'
`reltext` | 'next' | 'last' | 'previous' | 'this'
`espacio` | [ \t]+
`unit` | 'ms' | 'µs' | (( 'msec' | 'millisecond' | 'µsec' | 'microsecond' | 'usec' | 'sec' | 'second' | 'min' | 'minute' | 'hour' | 'day' | 'fortnight' | 'forthnight' | 'month' | 'year') 's'?) | 'weeks' | `daytext`

Notaciones basadas en el día
Formato | Descripción | Ejemplos
--- | --- | ---
'yesterday' | Medianoche de ayer | "yesterday 14:00"
'midnight' | El tiempo es puesto a 00:00:00 |
'today' | El tiempo es puesto a 00:00:00 |
'now' | Ahora |
'noon' | El tiempo es puesto a 12:00:00 | "yesterday noon"
'tomorrow' | Medianoche de mañana |
'back of' `hour` | 15 minutos antes de la hora especificada | "back of 7pm", "back of 15"
'front of' `hour` | 15 minutos después de la hora especificada | "front of 5am", "front of 23"
'first day of'? | Asigna el día del primer día del mes actual. Generalmente es preferible utilizar esta expresión con el nombre del mes que sigue, ya que solo se refiere al mes actual. | "first day of January 2008"
'last day of'? | Asigna el día del último día del mes actual. Generalmente es preferible utilizar esta expresión con el nombre del mes que sigue, ya que solo se refiere al mes actual. | "last day of next month"
`ordinal` `espacio` `dayname` `espacio` 'of' | Calcula el `x`-ésimo día de la semana del mes actual. | "first sat of July 2008"
'last' `espacio` `dayname` `espacio` 'of' | Calcula el último día de la semana del mes actual. | "last sat of July 2008"
`number` `espacio`? (`unit` | 'week') | Maneja tiempos relativos cuyo valor es numerado. | "+5 weeks", "12 day", "-7 weekdays"
(`ordinal` | `reltext`) `espacio` `unit` | Maneja elementos temporales relativos cuyo valor es textual. `last` y `previous` son equivalentes a `-1`, `this` a 0, y `next` a `+1`. | "fifth day", "second month", "last day", "previous year"
'ago' | Utiliza en el pasado cualquier descripción de tiempo relativo ('hace'). | "2 days ago", "8 days ago 14:00", "2 months 5 days ago", "2 months ago 5 days", "2 days ago"
`dayname` | Se mueve hacia el próximo día indicado.(Ver nota) | "Monday"
`reltext` `espacio` 'week' | Maneja el formato especial "weekday + last/this/next week". | "Monday next week"

> Nota:

> Las expresiones relativas son siempre tratadas después de las expresiones no relativas. Esto hace que "+1 week july 2008" y "july 2008 +1 week" sean equivalentes.

> "yesterday", "midnight", "today", "noon" y "tomorrow" son excepciones a esta regla. Note que "tomorrow 11:00" y "11:00 tomorrow" son diferentes. Si la fecha de hoy es "July 23rd, 2008", la primera expresión da "2008-07-24 11:00" mientras que la segunda dará "2008-07-24 00:00". La razón es que estas cinco expresiones influyen directamente en la fecha actual.

> Las palabras clave como "first day of" dependen del contexto en el cual la cadena de formato relativo es utilizada. Si se utiliza con un método estático o una función, el referente es el timestamp actual del sistema. Sin embargo, si se utiliza en DateTime::modify() o DateTimeImmutable::modify(), el referente es el objeto sobre el cual el método `modify()` es llamado.

> Nota:

> Note las observaciones que siguen cuando el día de la semana actual es el mismo que el día de la semana utilizado en la cadena fecha/hora. El día de la semana actual podría haber sido recalculado con respecto a las partes no relativas de la cadena fecha/hora.

> 1. "`dayname`" no avanza hacia otro día. (Ejemplo: "Wed July 23rd, 2008" significa "2008-07-23").
> 2. "`number` `dayname`" no avanza hacia otro día. (Ejemplo: "1 wednesday july 23rd, 2008" significa "2008-07-23").
> 3. "`number` week `dayname`" añadirá primero el número de semanas, pero no avanzará hacia otro día. En este caso "`number` week" y "`dayname`" son dos bloques distintos. (Ejemplo: "+1 week wednesday july 23rd, 2008" significa "2008-07-30").
> 4. "`ordinal` `dayname`" avanza hacia otro día. (Ejemplo: "first wednesday july 23rd, 2008" significa "2008-07-30").
> 5. "`number` week `ordinal` `dayname`" añadirá primero el número de semanas y luego avanzará hacia otro día. En este caso, "`number` week" y "`ordinal` `dayname`" son dos bloques distintos. (Ejemplo: "+1 week first wednesday july 23rd, 2008" significa "2008-08-06").
> 6. "`ordinal` `dayname` 'of' " no avanza hacia otro día. (Ejemplo: "first wednesday of july 23rd, 2008" significa "2008-07-02" ya que la frase con 'of' resetea el día del mes hacia '1' y el '23' será ignorado).

> Note también que el "of" en "`ordinal` `espacio` `dayname` `espacio` 'of' " y "'last' `espacio` `dayname` `espacio` 'of' " hace algo especial.

> 1. Asigna el día del mes a 1.
> 2. "`ordinal` `dayname` 'of' " no avanza hacia otro día. (Ejemplo: "first tuesday of july 2008" significa "2008-07-01").
> 3. "`ordinal` `dayname` " avanza hacia otro día. (Ejemplo: "first tuesday july 2008" significa "2008-07-08", ver también el punto número 4 de la lista anterior).
> 4. "'last' `dayname` 'of' " toma el último `dayname` del mes actual. (Ejemplo: "last wed of july 2008" significa "2008-07-30")
> 5. "'last' `dayname`" toma el último `dayname` a partir del día actual. (Ejemplo: "last wed july 2008" significa "2008-06-25"; "july 2008" asigna primero la fecha actual a "2008-07-01" y luego "last wed" retrocede al último miércoles que es el "2008-06-25").

> Nota:

> Los valores relativos de los meses calculados se basan en el número de días de los meses que se utilizan. Por ejemplo, "+2 month 2011-11-30", dará como resultado la fecha "2012-01-30". Esto se debe a que el mes de noviembre tiene 30 días, y que el mes de diciembre tiene 31, lo que suma un total de 61 días.

> Nota:

> `number` es un número entero; si un número decimal es dado, el punto (o la coma) será probablemente interpretado como un delimitador. Por ejemplo, `'+1.5 hours'` será analizado como `'+1 5 hours'`, y no como `'+1 hour +30 minutes'`.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `number` ahora acepta un signo más seguido de un signo menos, por ejemplo `+-2`, y otras combinaciones de varios signos.
8.2.0 | `number` ya no acepta un signo más seguido de un signo menos, ejemplo `+-2`.
7.0.8 | Las semanas siempre comienzan el lunes. Antes, el domingo también era considerado para comenzar una semana.

# Lista de Zonas Horarias Soportadas

## Tabla de contenidos

- África
- América
- Antártida
- Ártico
- Asia
- Atlántico
- Australia
- Europa
- Índico
- Pacífico
- Otros

Aquí, se encuentra una lista completa de las zonas horarias soportadas por PHP, que pueden ser utilizadas con, por ejemplo, date_default_timezone_set().

Precaución

El comportamiento de las zonas horarias que no están listadas aquí es indefinido.

> Nota: La última versión de la base de datos de zonas horarias puede ser instalada vía el comando PECL » timezonedb.

> Nota: Esta lista está basada en la versión de la base de datos de zonas horarias 2026.1.

## África

África
Africa/Abidjan | Africa/Accra | Africa/Addis_Ababa | Africa/Algiers
Africa/Asmara | Africa/Bamako | Africa/Bangui | Africa/Banjul
Africa/Bissau | Africa/Blantyre | Africa/Brazzaville | Africa/Bujumbura
Africa/Cairo | Africa/Casablanca | Africa/Ceuta | Africa/Conakry
Africa/Dakar | Africa/Dar_es_Salaam | Africa/Djibouti | Africa/Douala
Africa/El_Aaiun | Africa/Freetown | Africa/Gaborone | Africa/Harare
Africa/Johannesburg | Africa/Juba | Africa/Kampala | Africa/Khartoum
Africa/Kigali | Africa/Kinshasa | Africa/Lagos | Africa/Libreville
Africa/Lome | Africa/Luanda | Africa/Lubumbashi | Africa/Lusaka
Africa/Malabo | Africa/Maputo | Africa/Maseru | Africa/Mbabane
Africa/Mogadishu | Africa/Monrovia | Africa/Nairobi | Africa/Ndjamena
Africa/Niamey | Africa/Nouakchott | Africa/Ouagadougou | Africa/Porto-Novo
Africa/Sao_Tome | Africa/Tripoli | Africa/Tunis | Africa/Windhoek

## América

América
America/Adak | America/Anchorage | America/Anguilla | America/Antigua
America/Araguaina | America/Argentina/Buenos_Aires | America/Argentina/Catamarca | America/Argentina/Cordoba
America/Argentina/Jujuy | America/Argentina/La_Rioja | America/Argentina/Mendoza | America/Argentina/Rio_Gallegos
America/Argentina/Salta | America/Argentina/San_Juan | America/Argentina/San_Luis | America/Argentina/Tucuman
America/Argentina/Ushuaia | America/Aruba | America/Asuncion | America/Atikokan
America/Bahia | America/Bahia_Banderas | America/Barbados | America/Belem
America/Belize | America/Blanc-Sablon | America/Boa_Vista | America/Bogota
America/Boise | America/Cambridge_Bay | America/Campo_Grande | America/Cancun
America/Caracas | America/Cayenne | America/Cayman | America/Chicago
America/Chihuahua | America/Ciudad_Juarez | America/Costa_Rica | America/Coyhaique
America/Creston | America/Cuiaba | America/Curacao | America/Danmarkshavn
America/Dawson | America/Dawson_Creek | America/Denver | America/Detroit
America/Dominica | America/Edmonton | America/Eirunepe | America/El_Salvador
America/Fort_Nelson | America/Fortaleza | America/Glace_Bay | America/Goose_Bay
America/Grand_Turk | America/Grenada | America/Guadeloupe | America/Guatemala
America/Guayaquil | America/Guyana | America/Halifax | America/Havana
America/Hermosillo | America/Indiana/Indianapolis | America/Indiana/Knox | America/Indiana/Marengo
America/Indiana/Petersburg | America/Indiana/Tell_City | America/Indiana/Vevay | America/Indiana/Vincennes
America/Indiana/Winamac | America/Inuvik | America/Iqaluit | America/Jamaica
America/Juneau | America/Kentucky/Louisville | America/Kentucky/Monticello | America/Kralendijk
America/La_Paz | America/Lima | America/Los_Angeles | America/Lower_Princes
America/Maceio | America/Managua | America/Manaus | America/Marigot
America/Martinique | America/Matamoros | America/Mazatlan | America/Menominee
America/Merida | America/Metlakatla | America/Mexico_City | America/Miquelon
America/Moncton | America/Monterrey | America/Montevideo | America/Montserrat
America/Nassau | America/New_York | America/Nome | America/Noronha
America/North_Dakota/Beulah | America/North_Dakota/Center | America/North_Dakota/New_Salem | America/Nuuk
America/Ojinaga | America/Panama | America/Paramaribo | America/Phoenix
America/Port-au-Prince | America/Port_of_Spain | America/Porto_Velho | America/Puerto_Rico
America/Punta_Arenas | America/Rankin_Inlet | America/Recife | America/Regina
America/Resolute | America/Rio_Branco | America/Santarem | America/Santiago
America/Santo_Domingo | America/Sao_Paulo | America/Scoresbysund | America/Sitka
America/St_Barthelemy | America/St_Johns | America/St_Kitts | America/St_Lucia
America/St_Thomas | America/St_Vincent | America/Swift_Current | America/Tegucigalpa
America/Thule | America/Tijuana | America/Toronto | America/Tortola
America/Vancouver | America/Whitehorse | America/Winnipeg | America/Yakutat

## Antártida

Antártida
Antarctica/Casey | Antarctica/Davis | Antarctica/DumontDUrville | Antarctica/Macquarie
Antarctica/Mawson | Antarctica/McMurdo | Antarctica/Palmer | Antarctica/Rothera
Antarctica/Syowa | Antarctica/Troll | Antarctica/Vostok |

## Ártico

Ártico
Arctic/Longyearbyen

## Asia

Asia
Asia/Aden | Asia/Almaty | Asia/Amman | Asia/Anadyr
Asia/Aqtau | Asia/Aqtobe | Asia/Ashgabat | Asia/Atyrau
Asia/Baghdad | Asia/Bahrain | Asia/Baku | Asia/Bangkok
Asia/Barnaul | Asia/Beirut | Asia/Bishkek | Asia/Brunei
Asia/Chita | Asia/Colombo | Asia/Damascus | Asia/Dhaka
Asia/Dili | Asia/Dubai | Asia/Dushanbe | Asia/Famagusta
Asia/Gaza | Asia/Hebron | Asia/Ho_Chi_Minh | Asia/Hong_Kong
Asia/Hovd | Asia/Irkutsk | Asia/Jakarta | Asia/Jayapura
Asia/Jerusalem | Asia/Kabul | Asia/Kamchatka | Asia/Karachi
Asia/Kathmandu | Asia/Khandyga | Asia/Kolkata | Asia/Krasnoyarsk
Asia/Kuala_Lumpur | Asia/Kuching | Asia/Kuwait | Asia/Macau
Asia/Magadan | Asia/Makassar | Asia/Manila | Asia/Muscat
Asia/Nicosia | Asia/Novokuznetsk | Asia/Novosibirsk | Asia/Omsk
Asia/Oral | Asia/Phnom_Penh | Asia/Pontianak | Asia/Pyongyang
Asia/Qatar | Asia/Qostanay | Asia/Qyzylorda | Asia/Riyadh
Asia/Sakhalin | Asia/Samarkand | Asia/Seoul | Asia/Shanghai
Asia/Singapore | Asia/Srednekolymsk | Asia/Taipei | Asia/Tashkent
Asia/Tbilisi | Asia/Tehran | Asia/Thimphu | Asia/Tokyo
Asia/Tomsk | Asia/Ulaanbaatar | Asia/Urumqi | Asia/Ust-Nera
Asia/Vientiane | Asia/Vladivostok | Asia/Yakutsk | Asia/Yangon
Asia/Yekaterinburg | Asia/Yerevan |  |

## Atlántico

Atlántico
Atlantic/Azores | Atlantic/Bermuda | Atlantic/Canary | Atlantic/Cape_Verde
Atlantic/Faroe | Atlantic/Madeira | Atlantic/Reykjavik | Atlantic/South_Georgia
Atlantic/St_Helena | Atlantic/Stanley |  |

## Australia

Australia
Australia/Adelaide | Australia/Brisbane | Australia/Broken_Hill | Australia/Darwin
Australia/Eucla | Australia/Hobart | Australia/Lindeman | Australia/Lord_Howe
Australia/Melbourne | Australia/Perth | Australia/Sydney |

## Europa

Europa
Europe/Amsterdam | Europe/Andorra | Europe/Astrakhan | Europe/Athens
Europe/Belgrade | Europe/Berlin | Europe/Bratislava | Europe/Brussels
Europe/Bucharest | Europe/Budapest | Europe/Busingen | Europe/Chisinau
Europe/Copenhagen | Europe/Dublin | Europe/Gibraltar | Europe/Guernsey
Europe/Helsinki | Europe/Isle_of_Man | Europe/Istanbul | Europe/Jersey
Europe/Kaliningrad | Europe/Kirov | Europe/Kyiv | Europe/Lisbon
Europe/Ljubljana | Europe/London | Europe/Luxembourg | Europe/Madrid
Europe/Malta | Europe/Mariehamn | Europe/Minsk | Europe/Monaco
Europe/Moscow | Europe/Oslo | Europe/Paris | Europe/Podgorica
Europe/Prague | Europe/Riga | Europe/Rome | Europe/Samara
Europe/San_Marino | Europe/Sarajevo | Europe/Saratov | Europe/Simferopol
Europe/Skopje | Europe/Sofia | Europe/Stockholm | Europe/Tallinn
Europe/Tirane | Europe/Ulyanovsk | Europe/Vaduz | Europe/Vatican
Europe/Vienna | Europe/Vilnius | Europe/Volgograd | Europe/Warsaw
Europe/Zagreb | Europe/Zurich |  |

## Índico

Índico
Indian/Antananarivo | Indian/Chagos | Indian/Christmas | Indian/Cocos
Indian/Comoro | Indian/Kerguelen | Indian/Mahe | Indian/Maldives
Indian/Mauritius | Indian/Mayotte | Indian/Reunion |

## Pacífico

Pacífico
Pacific/Apia | Pacific/Auckland | Pacific/Bougainville | Pacific/Chatham
Pacific/Chuuk | Pacific/Easter | Pacific/Efate | Pacific/Fakaofo
Pacific/Fiji | Pacific/Funafuti | Pacific/Galapagos | Pacific/Gambier
Pacific/Guadalcanal | Pacific/Guam | Pacific/Honolulu | Pacific/Kanton
Pacific/Kiritimati | Pacific/Kosrae | Pacific/Kwajalein | Pacific/Majuro
Pacific/Marquesas | Pacific/Midway | Pacific/Nauru | Pacific/Niue
Pacific/Norfolk | Pacific/Noumea | Pacific/Pago_Pago | Pacific/Palau
Pacific/Pitcairn | Pacific/Pohnpei | Pacific/Port_Moresby | Pacific/Rarotonga
Pacific/Saipan | Pacific/Tahiti | Pacific/Tarawa | Pacific/Tongatapu
Pacific/Wake | Pacific/Wallis |  |

## Otros

Advertencia

No se utilice ninguna de las zonas horarias listadas aquí (excepto UTC), estas solo existen por razones de compatibilidad ascendente y su comportamiento puede provocar errores. Además, estas zonas horarias pueden ser eliminadas de la base de datos IANA de zonas horarias en cualquier momento.

Advertencia

Si se ignora la advertencia anterior, tenga en cuenta que la base de datos de la IANA que proporciona el soporte de zonas horarias en PHP utiliza los signos POSIX lo que significa que las zonas `Etc/GMT+n` y `Etc/GMT-n` están invertidas respecto al uso común.

Por ejemplo, la zona horaria 8 horas después de GMT que se utiliza en China y en Australia Occidental es actualmente `Etc/GMT-8` en esta base de datos, y no `Etc/GMT+8` como se podría esperar.

Una vez más, se recomienda encarecidamente que se utilice la zona horaria correcta para su ubicación, como `Asia/Shanghai` o `Australia/Perth` para los ejemplos anteriores.

Otros
Africa/Asmera | Africa/Timbuktu | America/Argentina/ComodRivadavia | America/Atka
America/Buenos_Aires | America/Catamarca | America/Coral_Harbour | America/Cordoba
America/Ensenada | America/Fort_Wayne | America/Godthab | America/Indianapolis
America/Jujuy | America/Knox_IN | America/Louisville | America/Mendoza
America/Montreal | America/Nipigon | America/Pangnirtung | America/Porto_Acre
America/Rainy_River | America/Rosario | America/Santa_Isabel | America/Shiprock
America/Thunder_Bay | America/Virgin | America/Yellowknife | Antarctica/South_Pole
Asia/Ashkhabad | Asia/Calcutta | Asia/Choibalsan | Asia/Chongqing
Asia/Chungking | Asia/Dacca | Asia/Harbin | Asia/Istanbul
Asia/Kashgar | Asia/Katmandu | Asia/Macao | Asia/Rangoon
Asia/Saigon | Asia/Tel_Aviv | Asia/Thimbu | Asia/Ujung_Pandang
Asia/Ulan_Bator | Atlantic/Faeroe | Atlantic/Jan_Mayen | Australia/ACT
Australia/Canberra | Australia/Currie | Australia/LHI | Australia/North
Australia/NSW | Australia/Queensland | Australia/South | Australia/Tasmania
Australia/Victoria | Australia/West | Australia/Yancowinna | Brazil/Acre
Brazil/DeNoronha | Brazil/East | Brazil/West | Canada/Atlantic
Canada/Central | Canada/Eastern | Canada/Mountain | Canada/Newfoundland
Canada/Pacific | Canada/Saskatchewan | Canada/Yukon | CET
Chile/Continental | Chile/EasterIsland | CST6CDT | Cuba
EET | Egypt | Eire | EST
EST5EDT | Etc/GMT | Etc/GMT+0 | Etc/GMT+1
Etc/GMT+10 | Etc/GMT+11 | Etc/GMT+12 | Etc/GMT+2
Etc/GMT+3 | Etc/GMT+4 | Etc/GMT+5 | Etc/GMT+6
Etc/GMT+7 | Etc/GMT+8 | Etc/GMT+9 | Etc/GMT-0
Etc/GMT-1 | Etc/GMT-10 | Etc/GMT-11 | Etc/GMT-12
Etc/GMT-13 | Etc/GMT-14 | Etc/GMT-2 | Etc/GMT-3
Etc/GMT-4 | Etc/GMT-5 | Etc/GMT-6 | Etc/GMT-7
Etc/GMT-8 | Etc/GMT-9 | Etc/GMT0 | Etc/Greenwich
Etc/UCT | Etc/Universal | Etc/UTC | Etc/Zulu
Europe/Belfast | Europe/Kiev | Europe/Nicosia | Europe/Tiraspol
Europe/Uzhgorod | Europe/Zaporozhye | Factory | GB
GB-Eire | GMT | GMT+0 | GMT-0
GMT0 | Greenwich | Hongkong | HST
Iceland | Iran | Israel | Jamaica
Japan | Kwajalein | Libya | MET
Mexico/BajaNorte | Mexico/BajaSur | Mexico/General | MST
MST7MDT | Navajo | NZ | NZ-CHAT
Pacific/Enderbury | Pacific/Johnston | Pacific/Ponape | Pacific/Samoa
Pacific/Truk | Pacific/Yap | Poland | Portugal
PRC | PST8PDT | ROC | ROK
Singapore | Turkey | UCT | Universal
US/Alaska | US/Aleutian | US/Arizona | US/Central
US/East-Indiana | US/Eastern | US/Hawaii | US/Indiana-Starke
US/Michigan | US/Mountain | US/Pacific | US/Samoa
UTC | W-SU | WET | Zulu

# La clase DateError

(PHP 8 >= 8.3.0)

## Introducción

Lanzada cuando la base de datos de los husos horarios no se encuentra, o contiene datos inválidos.

Este error no debería producirse nunca, y no depende del código. Hay dos excepciones hijas (DateObjectError y DateRangeError) que se lanzan en función de los errores del desarrollador o de los problemas de rango.

## Sinopsis de la Clase

class DateError extends Error {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

## Ver también

- DateObjectError
- DateRangeError

# La clase DateObjectError

(PHP 8 >= 8.3.0)

## Introducción

Lanzada cuando una de las clases Date/Hora no ha sido correctamente inicializada.

Dado que las clases Date/Hora no son finales, estas clases pueden ser heredadas. Cuando el constructor padre no es llamado, este error es lanzado. Siempre es un error de programación.

## Sinopsis de la Clase

class DateObjectError extends DateError {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

## Ver también

- DateError
- DateRangeError

# La clase DateRangeError

(PHP 8 >= 8.3.0)

## Introducción

Lanzada por DateTime::getTimestamp(), DateTimeImmutable::getTimestamp(), y date_timestamp_get(), en plataformas de 32 bits si el objeto date representa una fecha fuera del rango signado de 32 bits.

## Sinopsis de la Clase

class DateRangeError extends DateError {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

## Ver también

- DateError
- DateObjectError

# La clase DateException

(PHP 8 >= 8.3.0)

## Introducción

Clase padre de todas las excepciones Date/Time, para problemas relacionados con las entradas de usuario, o con los argumentos textuales libres que deben ser analizados.

Las siguientes excepciones hijas son lanzadas por la extensión:

- DateInvalidOperationException
- DateInvalidTimezoneException
- DateMalformedIntervalStringException
- DateMalformedPeriodStringException
- DateMalformedStringException

## Sinopsis de la Clase

class DateException extends Exception {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La clase DateInvalidOperationException

(PHP 8 >= 8.3.0)

## Introducción

Lanzada por DateTimeImmutable::sub() y DateTime::sub() cuando se intenta una operación no soportada.

Un ejemplo de operación no soportada es el uso de un objeto DateInterval que representa especificaciones de tiempo como `next weekday`, ya que no se puede construir ninguna declaración lógica inversa.

## Sinopsis de la Clase

class DateInvalidOperationException extends DateException {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La clase DateInvalidTimeZoneException

(PHP 8 >= 8.3.0)

## Introducción

Lanzada cuando un valor incorrecto es pasado a DateTimeZone::__construct().

## Sinopsis de la Clase

class DateInvalidTimeZoneException extends DateException {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La clase DateMalformedIntervalStringException

(PHP 8 >= 8.3.0)

## Introducción

Se lanza cuando un argumento `duration` inválido es pasado a DateInterval::__construct().

## Sinopsis de la Clase

class DateMalformedIntervalStringException extends DateException {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La clase DateMalformedPeriodStringException

(PHP 8 >= 8.3.0)

## Introducción

Se lanza cuando un argumento `isostr` inválido es pasado a DatePeriod::__construct().

## Sinopsis de la Clase

class DateMalformedPeriodStringException extends DateException {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La clase DateMalformedStringException

(PHP 8 >= 8.3.0)

## Introducción

Lanzada cuando se detecta una cadena de Fecha/Hora inválida.

Esto puede ser un valor pasado a DateTimeImmutable::__construct(), DateTimeImmutable::modify(), DateTime::__construct(), o DateTime::modify().

## Sinopsis de la Clase

class DateMalformedStringException extends DateException {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

- Instalación/Configuración
  - Instalación
  - Configuración en tiempo de ejecución
- Constantes predefinidas
- Ejemplos
  - Aritmética con DateTime
- DateTime — La clase DateTime
  - DateTime::add — Modifica un objeto DateTime, añadiendo una cantidad de días, meses, años, horas, minutos y segundos
  - DateTime::__construct — Devuelve un nuevo objeto DateTime
  - DateTime::createFromFormat — Analiza una cadena con un instante según un formato especificado
  - DateTime::createFromImmutable — Devuelve una nueva instancia de DateTime encapsulando el objeto DateTimeImmutable dado
  - DateTime::createFromInterface — RDevuelve un nuevo objeto DateTime que encapsula el objeto DateTimeInterface dado
  - DateTime::createFromTimestamp — Crea una instancia a partir de una marca de tiempo Unix
  - DateTime::getLastErrors — Alias de DateTimeImmutable::getLastErrors
  - DateTime::modify — Altera la marca temporal
  - DateTime::__set_state — El gestor __set_state
  - DateTime::setDate — Establece la fecha
  - DateTime::setISODate — Establece la fecha ISO
  - DateTime::setMicrosecond — Establece la parte de microsegundos de la hora
  - DateTime::setTime — Establece la hora
  - DateTime::setTimestamp — Establece la fecha y la hora basándose en una marca temporal de Unix
  - DateTime::setTimezone — Establece la zona horaria para el objeto DateTime
  - DateTime::sub — Sustrae una cantidad de días, meses, años, horas, minutos y segundos de un objeto DateTime
- DateTimeImmutable — La clase DateTimeImmutable
  - DateTimeImmutable::add — Devuelve un nuevo objeto, con una cantidad añadida de días, meses, años, horas, minutos y segundos
  - DateTimeImmutable::__construct — Devuelve un nuevo objeto DateTimeImmutable
  - DateTimeImmutable::createFromFormat — Analiza un string de tiempo según el formato especificado
  - DateTimeImmutable::createFromInterface — Devuelve un nuevo objeto DateTimeImmutable que encapsula el objeto DateTimeInterface dado
  - DateTimeImmutable::createFromMutable — Devuelve un nuevo objeto DateTimeImmutable que encapsula el objeto DateTime dado
  - DateTimeImmutable::createFromTimestamp — Crea una instancia a partir de una marca de tiempo Unix
  - DateTimeImmutable::getLastErrors — Devuelve las advertencias y errores
  - DateTimeImmutable::modify — Crea un nuevo objeto con la marca de tiempo modificada
  - DateTimeImmutable::__set_state — El gestor __set_state
  - DateTimeImmutable::setDate — Establece la fecha
  - DateTimeImmutable::setISODate — Establece la fecha ISO
  - DateTimeImmutable::setMicrosecond — Establece la parte de microsegundos de la hora
  - DateTimeImmutable::setTime — Establece la hora
  - DateTimeImmutable::setTimestamp — Establece la fecha y hora basadas en una marca de tiempo Unix (Unix timestamp)
  - DateTimeImmutable::setTimezone — Establece la zona horaria
  - DateTimeImmutable::sub — Sustrae una cantidad de días, meses, años, horas, minutos y segundos
- DateTimeInterface — La interfaz DateTimeInterface
  - DateTimeInterface::diff — Devuelve la diferencia entre dos objetos DateTime
  - DateTimeInterface::format — Retorna una fecha formateada según el formato proporcionado
  - DateTimeInterface::getMicrosecond — Obtiene la parte de microsegundos de la marca de tiempo Unix
  - DateTimeInterface::getOffset — Devuelve el desplazamiento horario
  - DateTimeInterface::getTimestamp — Obtiene el timestamp Unix
  - DateTimeInterface::getTimezone — Devuelve la zona horaria relativa al DateTime proporcionado
  - DateTime::__serialize — Deserializa un DateTime
  - DateTime::__unserialize — Deserializar un DateTime
  - DateTime::__wakeup — El manejador __wakeup
- DateTimeZone — La clase DateTimeZone
  - DateTimeZone::__construct — Crea un nuevo objeto DateTimeZone
  - DateTimeZone::getLocation — Devuelve las informaciones geográficas de una zona horaria
  - DateTimeZone::getName — Devuelve el nombre de la zona horaria
  - DateTimeZone::getOffset — Retorna el desplazamiento GMT de una zona horaria
  - DateTimeZone::getTransitions — Devuelve todas las transiciones de una zona horaria
  - DateTimeZone::listAbbreviations — Devuelve un array asociativo que describe una zona horaria
  - DateTimeZone::listIdentifiers — Devuelve un array numérico que contiene todos los identificadores de zonas horarias definidos
- DateInterval — La clase DateInterval
  - DateInterval::__construct — Crea un nuevo objeto DateInterval
  - DateInterval::createFromDateString — Establece un objeto DateInterval desde las partes relativas de una cadena
  - DateInterval::format — Formatea el intervalo
- DatePeriod — La clase DatePeriod
  - DatePeriod::__construct — Crea un nuevo objeto DatePeriod
  - DatePeriod::createFromISO8601String — Crea un nuevo objeto DatePeriod a partir de un string ISO8601
  - DatePeriod::getDateInterval — Devuelve el intervalo
  - DatePeriod::getEndDate — Devuelve la fecha de fin
  - DatePeriod::getRecurrences — Recupera el número de recurrencias
  - DatePeriod::getStartDate — Obtiene la fecha de inicio
- Funciones de Fecha/Hora
  - checkdate — Valida una fecha gregoriana
  - date — Da formato a una marca de tiempo de Unix (Unix timestamp)
  - date_add — Alias de DateTime::add
  - date_create — Creación de un objeto DateTime
  - date_create_from_format — Alias de DateTime::createFromFormat
  - date_create_immutable — Crea un nuevo objeto DateTimeImmutable
  - date_create_immutable_from_format — Alias de DateTimeImmutable::createFromFormat
  - date_date_set — Alias de DateTime::setDate
  - date_default_timezone_get — Recupera el huso horario por defecto utilizado por todas las funciones de fecha/hora de un script
  - date_default_timezone_set — Establece la zona horaria por defecto para todas las funciones de fecha/hora
  - date_diff — Alias de DateTime::diff
  - date_format — Alias de DateTime::format
  - date_get_last_errors — Alias de DateTimeImmutable::getLastErrors
  - date_interval_create_from_date_string — Alias de DateInterval::createFromDateString
  - date_interval_format — Alias de DateInterval::format
  - date_isodate_set — Alias de DateTime::setISODate
  - date_modify — Alias de DateTime::modify
  - date_offset_get — Alias de DateTime::getOffset
  - date_parse — Retorna un array asociativo con información detallada sobre una fecha/hora dada
  - date_parse_from_format — Recupera las informaciones de una fecha dada siguiendo un formato específico
  - date_sub — Alias de DateTime::sub
  - date_sun_info — Retorna un array con las informaciones sobre el amanecer/atardecer así como el inicio y el fin del amanecer
  - date_sunrise — Devuelve la hora de salida del sol para un día y un lugar dados
  - date_sunset — Devuelve la hora de puesta del sol para un día y un lugar dados
  - date_time_set — Alias de DateTime::setTime
  - date_timestamp_get — Alias de DateTime::getTimestamp
  - date_timestamp_set — Alias de DateTime::setTimestamp
  - date_timezone_get — Alias de DateTime::getTimezone
  - date_timezone_set — Alias de DateTime::setTimezone
  - getdate — Devuelve la fecha/hora
  - gettimeofday — Devuelve la hora actual
  - gmdate — Formatea una fecha/hora GMT/TUC
  - gmmktime — Retorna el timestamp UNIX de una fecha GMT
  - gmstrftime — Formatea una fecha/hora GMT/TUC según la configuración local
  - idate — Formatea una parte de la hora/fecha local como un entero
  - localtime — Obtiene la hora local
  - microtime — Devuelve el timestamp UNIX actual con microsegundos
  - mktime — Obtener la marca de tiempo Unix de una fecha
  - strftime — Formatea una fecha/hora local con la configuración local
  - strptime — Analiza una fecha/hora generada con strftime
  - strtotime — Transforma un texto inglés en timestamp
  - time — Devuelve el timestamp UNIX actual
  - timezone_abbreviations_list — Alias de DateTimeZone::listAbbreviations
  - timezone_identifiers_list — Alias de DateTimeZone::listIdentifiers
  - timezone_location_get — Alias de DateTimeZone::getLocation
  - timezone_name_from_abbr — Devuelve el nombre de una zona horaria a partir de su abreviatura y del desplazamiento UTC
  - timezone_name_get — Alias de DateTimeZone::getName
  - timezone_offset_get — Alias de DateTimeZone::getOffset
  - timezone_open — Alias de DateTimeZone::__construct
  - timezone_transitions_get — Alias de DateTimeZone::getTransitions
  - timezone_version_get — Lee la versión de la timezonedb
- Errores y Excepciones Fecha/Hora
- Formatos soportados de tiempo y fechas
- Lista de Zonas Horarias Soportadas
  - África
  - América
  - Antártida
  - Ártico
  - Asia
  - Atlántico
  - Australia
  - Europa
  - Índico
  - Pacífico
  - Otros
- DateError — La clase DateError
- DateObjectError — La clase DateObjectError
- DateRangeError — La clase DateRangeError
- DateException — La clase DateException
- DateInvalidOperationException — La clase DateInvalidOperationException
- DateInvalidTimeZoneException — La clase DateInvalidTimeZoneException
- DateMalformedIntervalStringException — La clase DateMalformedIntervalStringException
- DateMalformedPeriodStringException — La clase DateMalformedPeriodStringException
- DateMalformedStringException — La clase DateMalformedStringException

# Gestión del tiempo de alta resolución

# Introducción

La extensión HRTime implementa una clase StopWatch de alta resolución. Utiliza la mejor de las APIs en las diferentes plataformas, que proporcionará una resolución a la nanosegundo. Asimismo, es posible implementar un cronómetro personalizado utilizando los ticks de bajo nivel, entregados por las APIs subyacentes.

> Nota: A partir de PHP 7.3.0 la función relacionada hrtime() forma parte del núcleo.

# Ejemplos

## Tabla de contenidos

- Uso básico

## Uso básico

El ejemplo muestra el uso básico de la clase StopWatch

Ejemplo #1 Medir la ejecución de varios bloques de código y obtener el total

    <?php

    $c = new HRTime\StopWatch;

    $c->start();
    /* medir la ejecución de este bloque de código */
    for ($i = 0; $i < 1024*1024; $i++);
    $c->stop();
    $transcurrido0 = $c->getLastElapsedTime(HRTime\Unit::NANOSECOND);

    /* la medición no se ejecuta aquí */
    for ($i = 0; $i < 1024*1024; $i++);

    $c->start();
    /* medir la ejecución de este bloque de código */
    for ($i = 0; $i < 1024*1024; $i++);
    $c->stop();
    $transcurrido1 = $c->getLastElapsedTime(HRTime\Unit::NANOSECOND);

    $total_transcurrido = $c->getElapsedTime(HRTime\Unit::NANOSECOND);

    ?>

# La clase HRTime\PerformanceCounter

(PECL hrtime >= 0.4.3)

## Introducción

## Sinopsis de la Clase

class HRTime\PerformanceCounter {
/* Métodos */
public static function getFrequency(): int
public static function getTicks(): int
public static function getTicksSince(int `$start`): int
}

# HRTime\PerformanceCounter::getFrequency

(PECL hrtime >= 0.4.3)

HRTime\PerformanceCounter::getFrequency — Frecuencia del temporizador en ticks por segundo

### Descripción

public static function HRTime\PerformanceCounter::getFrequency(): int

Se devuelve la frecuencia del temporizador en ticks por segundo. Este valor es constante tras el inicio del sistema en la mayoría de los sistemas operativos.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Se devuelve un int que indica la frecuencia del temporizador.

# HRTime\PerformanceCounter::getTicks

(PECL hrtime >= 0.6.0)

HRTime\PerformanceCounter::getTicks — Ticks actuales desde el sistema

### Descripción

public static function HRTime\PerformanceCounter::getTicks(): int

Devuelve el recuento de ticks.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un int que indica el recuento de ticks.

# HRTime\PerformanceCounter::getTicksSince

(PECL hrtime >= 0.6.0)

HRTime\PerformanceCounter::getTicksSince — Ticks transcurridos desde el valor proporcionado

### Descripción

public static function HRTime\PerformanceCounter::getTicksSince(int `$start`): int

Devuelve el recuento de ticks transcurridos desde el valor de inicio proporcionado.

### Parámetros

`start`
  Valor de ticks de inicio.

### Valores devueltos

Devuelve un int que indica el recuento de ticks.

## Tabla de contenidos

- HRTime\PerformanceCounter::getFrequency — Frecuencia del temporizador en ticks por segundo
- HRTime\PerformanceCounter::getTicks — Ticks actuales desde el sistema
- HRTime\PerformanceCounter::getTicksSince — Ticks transcurridos desde el valor proporcionado

# La clase HRTime\StopWatch

(PECL hrtime >= 0.4.3)

## Introducción

## Sinopsis de la Clase

class HRTime\StopWatch extends HRTime\PerformanceCounter {
/* Métodos */
public function getElapsedTicks(): int
public function getElapsedTime(int `$unit` = ?): float
public function getLastElapsedTicks(): int
public function getLastElapsedTime(int `$unit` = ?): float
public function isRunning(): bool
public function start(): void
public function stop(): void
/* Métodos heredados */
public static function HRTime\PerformanceCounter::getFrequency(): int
public static function HRTime\PerformanceCounter::getTicks(): int
public static function HRTime\PerformanceCounter::getTicksSince(int `$start`): int
}

# HRTime\StopWatch::getElapsedTicks

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getElapsedTicks — Obtiene los ticks transcurridos para todos los intervalos

### Descripción

public function HRTime\StopWatch::getElapsedTicks(): int

Obtiene los ticks transcurridos para todos los intervalos cerrados anteriores.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un int que indica los ticks transcurridos.

# HRTime\StopWatch::getElapsedTime

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getElapsedTime — Obtiene el tiempo transcurrido para todos los intervalos

### Descripción

public function HRTime\StopWatch::getElapsedTime(int `$unit` = ?): float

Obtiene el tiempo transcurrido para todos los intervalos anteriores cerrados.

### Parámetros

`unit`
  Unidad de tiempo representada por una constante HRTime\Unit. Por omisión vale HRTime\Unit::SECOND.

### Valores devueltos

Devuelve un float que indica el tiempo transcurrido.

# HRTime\StopWatch::getLastElapsedTicks

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getLastElapsedTicks — Obtiene los ticks transcurridos para el último intervalo

### Descripción

public function HRTime\StopWatch::getLastElapsedTicks(): int

Obtiene los ticks transcurridos para el último intervalo cerrado.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un int que indica los ticks transcurridos.

# HRTime\StopWatch::getLastElapsedTime

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getLastElapsedTime — Obtiene el tiempo transcurrido para el último intervalo

### Descripción

public function HRTime\StopWatch::getLastElapsedTime(int `$unit` = ?): float

Obtiene el tiempo transcurrido para el último intervalo.

### Parámetros

`unit`
  Unidad de tiempo representada por una constante HRTime\Unit. Por omisión vale HRTime\Unit::SECOND.

### Valores devueltos

Devuelve un float que indica el tiempo transcurrido.

# HRTime\StopWatch::isRunning

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::isRunning — Comprueba si la medición del tiempo está en curso

### Descripción

public function HRTime\StopWatch::isRunning(): bool

Comprueba si la medición del tiempo ha sido iniciada.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un bool que indica si la medición del tiempo está en curso.

# HRTime\StopWatch::start

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::start — Inicia la medición del tiempo

### Descripción

public function HRTime\StopWatch::start(): void

Inicia la medición del tiempo. Este método no tiene ningún efecto si la medición ya ha sido iniciada. La medición continuará si ha sido detenida previamente.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No devuelve ningún valor.

# HRTime\StopWatch::stop

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::stop — Detiene la medición del tiempo

### Descripción

public function HRTime\StopWatch::stop(): void

Detiene la medición del tiempo para el intervalo anterior.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve void.

## Tabla de contenidos

- HRTime\StopWatch::getElapsedTicks — Obtiene los ticks transcurridos para todos los intervalos
- HRTime\StopWatch::getElapsedTime — Obtiene el tiempo transcurrido para todos los intervalos
- HRTime\StopWatch::getLastElapsedTicks — Obtiene los ticks transcurridos para el último intervalo
- HRTime\StopWatch::getLastElapsedTime — Obtiene el tiempo transcurrido para el último intervalo
- HRTime\StopWatch::isRunning — Comprueba si la medición del tiempo está en curso
- HRTime\StopWatch::start — Inicia la medición del tiempo
- HRTime\StopWatch::stop — Detiene la medición del tiempo

# La clase HRTime\Unit

(PECL hrtime >= 0.4.3)

## Introducción

## Sinopsis de la Clase

class HRTime\Unit {
/* Constantes */
const int SECOND = 0;
const int MILLISECOND = 1;
const int MICROSECOND = 2;
const int NANOSECOND = 3;
/* Métodos */
}

## Constantes predefinidas

`HRTime\Unit::SECOND`
`HRTime\Unit::MILLISECOND`
`HRTime\Unit::MICROSECOND`
`HRTime\Unit::NANOSECOND`

- Ejemplos
  - Uso básico
- HRTime\PerformanceCounter — La clase HRTime\PerformanceCounter
  - HRTime\PerformanceCounter::getFrequency — Frecuencia del temporizador en ticks por segundo
  - HRTime\PerformanceCounter::getTicks — Ticks actuales desde el sistema
  - HRTime\PerformanceCounter::getTicksSince — Ticks transcurridos desde el valor proporcionado
- HRTime\StopWatch — La clase HRTime\StopWatch
  - HRTime\StopWatch::getElapsedTicks — Obtiene los ticks transcurridos para todos los intervalos
  - HRTime\StopWatch::getElapsedTime — Obtiene el tiempo transcurrido para todos los intervalos
  - HRTime\StopWatch::getLastElapsedTicks — Obtiene los ticks transcurridos para el último intervalo
  - HRTime\StopWatch::getLastElapsedTime — Obtiene el tiempo transcurrido para el último intervalo
  - HRTime\StopWatch::isRunning — Comprueba si la medición del tiempo está en curso
  - HRTime\StopWatch::start — Inicia la medición del tiempo
  - HRTime\StopWatch::stop — Detiene la medición del tiempo
- HRTime\Unit — La clase HRTime\Unit

- Calendario
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones de Calendario
- Fecha/Hora — Fecha y Hora
  - Instalación/Configuración
  - Constantes predefinidas
  - Ejemplos
  - DateTime — La clase DateTime
  - DateTimeImmutable — La clase DateTimeImmutable
  - DateTimeInterface — La interfaz DateTimeInterface
  - DateTimeZone — La clase DateTimeZone
  - DateInterval — La clase DateInterval
  - DatePeriod — La clase DatePeriod
  - Funciones de Fecha/Hora
  - Errores y Excepciones Fecha/Hora
  - Formatos soportados de tiempo y fechas
  - Lista de Zonas Horarias Soportadas
  - DateError — La clase DateError
  - DateObjectError — La clase DateObjectError
  - DateRangeError — La clase DateRangeError
  - DateException — La clase DateException
  - DateInvalidOperationException — La clase DateInvalidOperationException
  - DateInvalidTimeZoneException — La clase DateInvalidTimeZoneException
  - DateMalformedIntervalStringException — La clase DateMalformedIntervalStringException
  - DateMalformedPeriodStringException — La clase DateMalformedPeriodStringException
  - DateMalformedStringException — La clase DateMalformedStringException
- HRTime — Gestión del tiempo de alta resolución
  - Ejemplos
  - HRTime\PerformanceCounter — La clase HRTime\PerformanceCounter
  - HRTime\StopWatch — La clase HRTime\StopWatch
  - HRTime\Unit — La clase HRTime\Unit

# Extensiones relacionadas con el sistema de ficheros

# Direct IO

# Introducción

PHP soporta las funciones Direct IO, tal como se describe en el estándar Posix (Sección 6) para realizar funciones I/O de bajo nivel en comparación con las funciones C-Language stream I/O (fopen(), fread(),..). El uso de las funciones DIO debe considerarse únicamente cuando se requiere un control directo de un dispositivo. En todos los demás casos, las funciones estándar del sistema de archivos son más adecuadas.

# Instalación/Configuración

## Tabla de contenidos

- Instalación
- Tipos de recursos

## Instalación

Esta extensión » PECL no está integrada en PHP.

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/dio.

## Tipos de recursos

Un tipo de recurso es definido por esta extensión: un puntero de fichero, retornado por la función dio_open().

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`F_DUPFD` (int)

`F_GETFD` (int)

`F_GETFL` (int)

`F_GETLK` (int)

`F_GETOWN` (int)

`F_RDLCK` (int)

`F_SETFL` (int)

`F_SETLK` (int)

`F_SETLKW` (int)

`F_SETOWN` (int)

`F_UNLCK` (int)

`F_WRLCK` (int)

`O_APPEND` (int)

`O_ASYNC` (int)

`O_CREAT` (int)

`O_EXCL` (int)

`O_NDELAY` (int)

`O_NOCTTY` (int)

`O_NONBLOCK` (int)

`O_RDONLY` (int)

`O_RDWR` (int)

`O_SYNC` (int)

`O_TRUNC` (int)

`O_WRONLY` (int)

`S_IRGRP` (int)

`S_IROTH` (int)

`S_IRUSR` (int)

`S_IRWXG` (int)

`S_IRWXO` (int)

`S_IRWXU` (int)

`S_IWGRP` (int)

`S_IWOTH` (int)

`S_IWUSR` (int)

`S_IXGRP` (int)

`S_IXOTH` (int)

`S_IXUSR` (int)

# Funciones de Direct IO

# dio_close

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_close — Cierra el descriptor de fichero fd

### Descripción

function dio_close(resource `$fd`): void

La función dio_close() cierra el descriptor de fichero `fd`.

### Parámetros

`fd`

  Descriptor de fichero devuelto por dio_open().

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Cerrando un descriptor de fichero

    <?php
    $fd = dio_open('/dev/ttyS0', O_RDWR);

    dio_close($fd);
    ?>

### Ver también

- dio_open() - Abre (crea si fuera necesario) un fichero a un nivel más bajo que el permitido por flujos de entrada y salida de las bibliotecas en C

# dio_fcntl

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_fcntl — Lleva a cabo la función fcntl de la biblioteca C en el fichero fd

### Descripción

function dio_fcntl(resource `$fd`, int `$cmd`, mixed `$args` = ?): mixed

La función dio_fcntl() realiza la operación especificada por `cmd` sobre el descriptor de fichero `fd`. Algunos comandos requieren que se proporcionen parámetros adicionales en `args`.

### Parámetros

`fd`

  Descriptor de fichero devuelto por dio_open().

`cmd`

  Puede ser una de las siguientes operaciones:

  - `F_SETLK` - Se asigna o quita el bloqueo. Si está bloqueado por otro proceso, dio_fcntl() devuelve -1.

  - `F_SETLKW` - como `F_SETLK`, pero en caso de que esté bloqueado por otro proceso, dio_fcntl() espera a que éste se libere.

  - `F_GETLK` - dio_fcntl() devuelve un array asociativo (como se describe a continuación) si algún proceso previene el bloqueo. Si no hubiera impedimento, se asignará la clave "type" a `F_UNLCK`.

  - `F_DUPFD` - encuentra el número de descriptor más bajo disponible que sea igual o superior a `args` y lo devuelve.

  - `F_SETFL` - Establece al descriptor de fichero las banderas especificadas en `args`, de entre `O_APPEND`, `O_NONBLOCK` o `O_ASYNC`. Para usar `O_ASYNC` debe usarse la extensión PCNTL.

`args`

  `args` es un array asociativo, cuando `cmd` sea `F_SETLK` o `F_SETLKW`, con las siguientes claves:

  - `start` - posición donde comienza el bloqueo

  - `length` - tamaño del area bloqueada. Cero significa hasta el final del fichero

  - `whence` - Desde dónde se contabiliza l_start: puede ser `SEEK_SET`, `SEEK_END` y `SEEK_CUR`

  - `type` - tipo de bloqueo: puede ser `F_RDLCK` (bloqueo de lectura), `F_WRLCK` (bloqueo de escritura) o `F_UNLCK` (desbloqueo)

### Valores devueltos

Devuelve el resultado de la llamada a C.

### Ejemplos

Ejemplo #1 Bloqueando y desbloqueando

    <?php

    $fd = dio_open('/dev/ttyS0', O_RDWR);

    if (dio_fcntl($fd, F_SETLK, Array("type"=>F_WRLCK)) == -1) {
       // parece el descriptor de fichero está bloqueado
       echo "No se puede desbloquear. Pertenece a algún otro proceso.";
    } else {
       echo "Bloqueo/desbloqueo con éxito";
    }

    dio_close($fd);
    ?>

### Notas

> Nota: Esta función no está implementada en las plataformas Windows.

# dio_open

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_open — Abre (crea si fuera necesario) un fichero a un nivel más bajo que el permitido por flujos de entrada y salida de las bibliotecas en C

### Descripción

function dio_open(string `$filename`, int `$flags`, int `$mode` = 0): resource

dio_open() abre un fichero y devuelve su descriptor de fichero.

### Parámetros

`filename`

  Ruta del fichero a abrir.

`flags`

  El parámetro `flags` es una máscara OR de bits compuesta a partir de las siguientes banderas. Estos valores tienen que incluir alguno de entre `O_RDONLY`, `O_WRONLY`, o `O_RDWR`. Además, podría incluir cualquier combinación del resto de banderas de la lista.

  - `O_RDONLY` - abre el fichero con acceso de lectura.

  - `O_WRONLY` - abre el fichero con acceso de escritura.

  - `O_RDWR` - abre el fichero con acceso de lectura y de escritura.

  - `O_CREAT` - crea el fichero, si no existiera ya.

  - `O_EXCL` - si tanto `O_CREAT` como `O_EXCL` están habilitados, y el fichero existe, dio_open() fallará.

  - `O_TRUNC` - si el fichero existe, y está abierto con sólo escritura, se truncará a cero.

  - `O_APPEND` - las operaciones de escritura añaden los datos al final del fichero.

  - `O_NONBLOCK` - asigna el modo no bloqueante.

  - `O_NOCTTY` - previene que el SO asigne al fichero abierto como el terminal controlador del proceso cuando se abra un fichero de dispositivo TTY.

`mode`

  Si `flags` contiene `O_CREAT`, `mode` establecerá los permisos del ficher (permisos de creación). `mode` es necesario para un correcto funcionamiento cuando `O_CREAT` se especifica en `flags`, y se ignorará en cualquier otro caso.

  Los permisos que realmente se asignan al fichero creado se verán afectados por el umask del proceso, como suele suceder.

### Valores devueltos

Descriptor de fichero o `false` en caso de error.

### Ejemplos

Ejemplo #1 Abrir un descriptor de fichero

    <?php

    $fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);

    dio_close($fd);
    ?>

### Ver también

- dio_close() - Cierra el descriptor de fichero fd

# dio_read

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_read — Leer bytes de un descriptor de fichero

### Descripción

function dio_read(resource `$fd`, int `$len` = 1024): string

La función dio_read() lee y devuelve `len` bytes de fichero con descriptor `fd`.

### Parámetros

`fd`

  El fichero descriptor devuelto pordio_open().

`len`

  El número de bytes a leer. Si no se especifica la lectura es de bloques de 1K dio_read()

### Valores devueltos

La bytes leídos desde `fd`.

### Ver también

- dio_write() - Escribe datos en el descriptor de fichero con un truncado opcional

# dio_seek

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_seek — Salta a una posición del descriptor de fichero desde donde proceda

### Descripción

function dio_seek(resource `$fd`, int `$pos`, int `$whence` = SEEK_SET): int

dio_seek() se usa para cambiar la posición del fichero del descriptor de fichero proporcionado.

### Parámetros

`fd`

  Descriptor de fichero devuelto por dio_open().

`pos`

  Nueva posición.

`whence`

  Indica cómo interpretar la posición `pos`:

  - `SEEK_SET` (por omisión) - indica que `pos` se contabiliza a partir del comienzo del fichero.

  - `SEEK_CUR` - indica que `pos` se contabiliza a partir de la posición actual del fichero. Este valor puede ser positivo o negativo.

  - `SEEK_END` - Indica que `pos` contabiliza caracteres a partir del final del fichero. Un valor negativo especifica una posición perteneciente al contenido del fichero; un valor positivo especifica una posición que supera el final. Si éste fuera el caso, y se escribieran datos, se rellenaría el fichero con ceros hasta alcanzar la posición que proceda.

### Valores devueltos

### Ejemplos

Ejemplo #1 Posicionamiento de un fichero

    <?php

    $fd = dio_open('/dev/ttyS0', O_RDWR);

    dio_seek($fd, 10, SEEK_SET);
    // la posición está a 10 caracteres del comienzo

    dio_seek($fd, -2, SEEK_CUR);
    // la posición está a 8 caracteres del comienzo

    dio_seek($fd, -5, SEEK_END);
    // la posición está a 5 caracteres del final

    dio_seek($fd, 10, SEEK_END);
    // la posición supera ahora 10 caracteres del final del fichero.
    // Los 10 caracteres intermedios entre el final y la posición actual
    // se rellenan con ceros.

    dio_close($fd);
    ?>

# dio_stat

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_stat — Consulta información de estado del descriptor de fichero fd

### Descripción

function dio_stat(resource `$fd`): array

dio_stat() devuelve información sobre el descriptor de fichero proporcionado.

### Parámetros

`fd`

  Descriptor de fichero devuelto por dio_open().

### Valores devueltos

Devuelve un array asociativo con las siguientes claves:

- "device" - dispositivo

- "inode" - nodo-i

- "mode" - modo

- "nlink" - número de enlaces duros

- "uid" - id de usuario

- "gid" - id de grupo

- "device_type" - tipo de dispositivo (si es un nodo-i de dispositivo)

- "size" - tamaño total en bytes

- "blocksize" - tamaño de bloque

- "blocks" - número de bloques asignados

- "atime" - fecha de último acceso

- "mtime" - fecha de última modificación

- "ctime" - fecha de último cambio

En caso de error, dio_stat() devuelve `null`.

# dio_tcsetattr

(PHP 4 >= 4.3.0, PHP 5 < 5.1.0)

dio_tcsetattr — Establece los atributos de terminal y la velocidad de transmisión para un puerto serie

### Descripción

function dio_tcsetattr(resource `$fd`, array `$options`): bool

dio_tcsetattr() establece los atributos de terminal y la velocidad de transmisión del `fd` abierto.

### Parámetros

`fd`

  El descriptor de fichero devuelto por dio_open().

`options`

  Las opciones disponibles actualmente son:

  - 'baud' - velocidad de transmisión del puerto - puede ser 38400,19200,9600,4800,2400,1800, 1200,600,300,200,150,134,110,75 o 50, el valor por omisión es 9600.

  - 'bits' - bits de datos - puede ser 8,7,6 o 5. El valor por omisión es 8.

  - 'stop' - bits de parada - puede ser 1 o 2. El valor por omisión es 1.

  - 'parity' - puede ser 0,1 o 2. El valor por omisión es 0.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Establecer la velocidad de transmisión en un puerto serie

    <?php

    $fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);

    dio_fcntl($fd, F_SETFL, O_SYNC);

    dio_tcsetattr($fd, array(
        'baud' => 9600,
        'bits' => 8,
        'stop'  => 1,
        'parity' => 0
    ));

    while (true) {
        $data = dio_read($fd, 256);
        if ($data !== null && $data !== '') {
            echo $data;
        }
    }

    ?>

### Notas

> Nota: Esta función no está implementada en las plataformas Windows.

# dio_truncate

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_truncate — Trunca un descriptor de fichero fd a un determinado número de bytes

### Descripción

function dio_truncate(resource `$fd`, int `$offset`): bool

dio_truncate() trunca un fichero a, como mucho, un tamaño de `offset` bytes.

Si el fichero excediera este tamaño, el contenido extra se perdería. Si fuera inferior en tamaño, no se especifica si el fichero se mantiene sin cambios o si se completa. En este último caso, la parte completada se haría con ceros.

### Parámetros

`fd`

  Descriptor de fichero devuelto por dio_open().

`offset`

  Tamaño en bytes.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Notas

> Nota: Esta función no está implementada en las plataformas Windows.

# dio_write

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_write — Escribe datos en el descriptor de fichero con un truncado opcional

### Descripción

function dio_write(resource `$fd`, string `$data`, int `$len` = 0): int

dio_write() escriba hasta `len` bytes de `data` al fichero `fd`.

### Parámetros

`fd`

  Descriptor de fichero devuelto por dio_open().

`data`

  Datos a escribir.

`len`

  Longitud en bytes de los datos a escribir. Si no se especifica, la función escribe todos los datos al fichero especificado.

### Valores devueltos

Devuelve el número de bytes escritos en `fd`.

### Ver también

- dio_read() - Leer bytes de un descriptor de fichero

## Tabla de contenidos

- dio_close — Cierra el descriptor de fichero fd
- dio_fcntl — Lleva a cabo la función fcntl de la biblioteca C en el fichero fd
- dio_open — Abre (crea si fuera necesario) un fichero a un nivel más bajo que el permitido por flujos de entrada y salida de las bibliotecas en C
- dio_read — Leer bytes de un descriptor de fichero
- dio_seek — Salta a una posición del descriptor de fichero desde donde proceda
- dio_stat — Consulta información de estado del descriptor de fichero fd
- dio_tcsetattr — Establece los atributos de terminal y la velocidad de transmisión para un puerto serie
- dio_truncate — Trunca un descriptor de fichero fd a un determinado número de bytes
- dio_write — Escribe datos en el descriptor de fichero con un truncado opcional

- Instalación/Configuración
  - Instalación
  - Tipos de recursos
- Constantes predefinidas
- Funciones de Direct IO
  - dio_close — Cierra el descriptor de fichero fd
  - dio_fcntl — Lleva a cabo la función fcntl de la biblioteca C en el fichero fd
  - dio_open — Abre (crea si fuera necesario) un fichero a un nivel más bajo que el permitido por flujos de entrada y salida de las bibliotecas en C
  - dio_read — Leer bytes de un descriptor de fichero
  - dio_seek — Salta a una posición del descriptor de fichero desde donde proceda
  - dio_stat — Consulta información de estado del descriptor de fichero fd
  - dio_tcsetattr — Establece los atributos de terminal y la velocidad de transmisión para un puerto serie
  - dio_truncate — Trunca un descriptor de fichero fd a un determinado número de bytes
  - dio_write — Escribe datos en el descriptor de fichero con un truncado opcional

# Directorios

# Constantes predefinidas

`DIRECTORY_SEPARATOR` (string)
`PATH_SEPARATOR` (string)
  Punto y coma en Windows, en caso contrario dos puntos.
`SCANDIR_SORT_ASCENDING` (int)
  Disponible desde PHP 5.4.0.
`SCANDIR_SORT_DESCENDING` (int)
  Disponible desde PHP 5.4.0.
`SCANDIR_SORT_NONE` (int)
  Disponible desde PHP 5.4.0.

# La clase Directory

(PHP 4, PHP 5, PHP 7, PHP 8)

## Introducción

Las instancias de Directory se crean llamando a la función dir(), no mediante el operador new.

## Sinopsis de la Clase

final class Directory {
/* Propiedades */
public readonly string $path;
public readonly resource $handle;
/* Métodos */
public function close(): void
public function read(): string|false
public function rewind(): void
}

## Propiedades

path

  El directorio que se abrió.

handle

  Puede usarse con otras funciones de directorios como readdir(), rewinddir() y closedir().

## Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | La clase ahora es final.
8.1.0 | Las propiedades path y handle ahora son de solo lectura.

# Directory::close

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::close — Cierra el manejador de directorio

### Descripción

public function Directory::close(): void

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | No se acepta ningún argumento. Anteriormente, un manejador de directorio podía ser pasado como argumento.

# Directory::read

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::read — Lee una entrada desde el manejador de directorio

### Descripción

public function Directory::read(): string|false

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | No se acepta ningún argumento. Anteriormente, un manejador de directorio podía ser pasado como argumento.

# Directory::rewind

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::rewind — Reinicia el manejador de directorio

### Descripción

public function Directory::rewind(): void

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | No se acepta ningún argumento. Anteriormente, un manejador de directorio podía ser pasado como argumento.

## Tabla de contenidos

- Directory::close — Cierra el manejador de directorio
- Directory::read — Lee una entrada desde el manejador de directorio
- Directory::rewind — Reinicia el manejador de directorio

# Funciones de directorio

# Ver también

Para funciones relacionadas, como dirname(), is_dir(), mkdir(), y rmdir(), visite la sección Sistema de ficheros.

# chdir

(PHP 4, PHP 5, PHP 7, PHP 8)

chdir — Cambia de directorio

### Descripción

function chdir(string `$directory`): bool

Cambia el directorio actual de PHP a `directorio`.

### Parámetros

`directorio`

  El nuevo directorio actual.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Emite un error de nivel `E_WARNING` en caso de error.

### Ejemplos

Ejemplo #1 chdir() ejemplo

    <?php

    // directorio actual
    echo getcwd() . "\n";

    chdir('public_html');

    // directorio actual
    echo getcwd() . "\n";

    ?>

Resultado del ejemplo anterior es similar a:

    /home/vincent
    /home/vincent/public_html

### Notas

Precaución

Si el intérprete de PHP ha sido compilado con ZTS (Seguridad de Hilos Zend) habilitada, cualquier cambio en el directorio actual realizado mediante chdir() será invisible para el sistema operativo. Todas las funciones integradas de PHP seguirán respetando el cambio en el directorio actual; pero las funciones de bibliotecas externas llamadas mediante FFI no lo harán. Puedes saber si la copia de PHP fue compilada con ZTS habilitada usando php -i o la constante incorporada `PHP_ZTS`.

### Ver también

- getcwd() - Devuelve el directorio de trabajo actual

# chroot

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

chroot — Cambia el directorio raíz

### Descripción

function chroot(string `$directory`): bool

Cambia el directorio raíz del proceso actual a `directory`, y cambia el directorio de trabajo actual a "/".

Esta función solo está disponible en sistemas GNU y BSD y cuando se utiliza la SAPI CLI, CGI o Embed. Además, esta función requiere privilegios de administrador.

Llamar a esta función no modifica los valores de las constantes mágicas `__DIR__` y `__FILE__`.

### Parámetros

`directory`

  El directorio al cual cambiar la raíz.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con chroot()

    <?php
    chroot("/path/to/your/chroot/");
    echo getcwd();
    ?>

El ejemplo anterior mostrará:

    /

### Notas

> Nota: Esta función no está implementada en las plataformas Windows.

> Nota: Esta función no está disponible en los intérpretes PHP compilados con ZTS (Zend Thread Safety) activado. Para verificar si su copia de PHP ha sido compilada con ZTS activado, utilice php -i o pruebe la constante incluida `PHP_ZTS`.

# closedir

(PHP 4, PHP 5, PHP 7, PHP 8)

closedir — Cerrar el gestor de directorio

### Descripción

function closedir(?resource `$dir_handle` = `null`): void

Cierra el flujo de directorio indicado por `dir_handle`.

### Parámetros

`dir_handle`
  Un gestor de directorio resource previamente abierto con opendir(). Si `dir_handle` es `null` se utilizará el último gestor abierto usando opendir().

### Valores devueltos

No se retorna ningún valor.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | Usar `null` para `dir_handle` ahora está obsoleto. En su lugar, debe proporcionarse explícitamente el último gestor de directorio abierto.
8.0.0 | `dir_handle` ahora es nullable.

### Ejemplos

Para un ejemplo completo, consulte la documentación de opendir().

### Ver también

- opendir() - Abrir un manejador de directorio
- readdir() - Leer entrada desde el manejador de directorio
- rewinddir() - Reinicia el gestor de directorio
- dir() - Devuelve una instancia de la clase Directory
- is_dir() - Indica si el fichero es un directorio
- glob() - Búsqueda de rutas que coinciden con un patrón
- scandir() - Lista los ficheros y directorios en un directorio

# dir

(PHP 4, PHP 5, PHP 7, PHP 8)

dir — Devuelve una instancia de la clase Directory

### Descripción

function dir(string `$directory`, ?resource `$context` = `null`): Directory|false

Un mecanismo pseudo-objeto permite la lectura de un directorio. El argumento `directory` es abierto.

### Parámetros

`directory`

  El directorio a abrir

`context`
  Un resource de contexto de flujo.

### Valores devueltos

Devuelve una instancia de la clase Directory en caso de éxito, o `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `context` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con dir()

Observe cómo se verifica el valor de retorno de Directory::read() en el siguiente ejemplo. Se comprueba si el valor es idéntico (igual y del mismo tipo que -- véase operadores de comparación para más detalles) `false` de lo contrario, cualquier entrada en el nombre se evaluaría a `false` causaría la interrupción del ciclo.

    <?php
    $d = dir("/etc/php5");
    echo "Manejador : " . $d->handle . "\n";
    echo "Ruta : " . $d->path . "\n";
    while (false !== ($entry = $d->read())) {
       echo $entry."\n";
    }
    $d->close();
    ?>

Resultado del ejemplo anterior es similar a:

    Manejador : Resource id #2
    Ruta : /etc/php5
    .
    ..
    apache
    cgi
    cli

### Notas

> Nota:

> El orden en el que las entradas del directorio son devueltas con el método read depende del sistema.

# getcwd

(PHP 4, PHP 5, PHP 7, PHP 8)

getcwd — Devuelve el directorio de trabajo actual

### Descripción

function getcwd(): string|false

Devuelve el directorio de trabajo actual.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el directorio de trabajo actual en caso de éxito o `false` en caso de fallo.

En algunas versiones de Unix, getcwd() puede devolver `false` si todos los directorios padres no tienen el modo escritura o el modo búsqueda definido, incluso si el directorio actual los tiene. Ver la función chmod() para más información sobre los modos de permisos.

### Ejemplos

Ejemplo #1 Ejemplo con getcwd()

    <?php

    // directorio actual
    echo getcwd() . "\n";

    chdir('cvs');

    // directorio actual
    echo getcwd() . "\n";

    ?>

Resultado del ejemplo anterior es similar a:

    /home/didou
    /home/didou/cvs

### Notas

Precaución

Si el intérprete PHP ha sido compilado con ZTS activado (Zend Thread Safety), el directorio de trabajo actual, devuelto por la función getcwd() puede ser diferente del devuelto por las interfaces del sistema. Las bibliotecas externas (llamadas a través de FFI), que dependen del directorio de trabajo actual, se verán afectadas.

### Ver también

- chdir() - Cambia de directorio
- chmod() - Cambia el modo del fichero

# opendir

(PHP 4, PHP 5, PHP 7, PHP 8)

opendir — Abrir un manejador de directorio

### Descripción

function opendir(string `$directory`, ?resource `$context` = `null`): resource|false

Abre un manejador de directorio para ser utilizado en llamadas posteriores a closedir(), readdir() y rewinddir().

### Parámetros

`directory`
  La ruta del directorio a abrir.
`context`
  Para una descripción del parámetro `context`, consulte la sección de flujos del manual.

### Valores devueltos

Devuelve un manejador de directorio en caso de éxito, o `false` si ocurre un error

### Errores/Excepciones

En caso de fallo, se emitirá una advertencia de tipo `E_WARNING`.

Esto puede ocurrir si `directory` no es un directorio válido, el directorio no puede abrirse debido a restricciones de permisos, o debido a errores del sistema de archivos.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `context` ahora es nullable.

### Ejemplos

Ejemplo #1 Listar todas las entradas en un directorio, omitiendo los directorios especiales `.` y `..`

Dado que los nombres de archivos y directorios pueden ser strings que PHP considera "falsos" (por ejemplo, un directorio llamado `"0"`) y readdir() devuelve `false` cuando ha leído todas las entradas en un directorio, se necesita usar el operador de `===` comparación para distinguir correctamente entre una entrada de directorio cuyo nombre es "falso" y haber leído todas las entradas del directorio.

    <?php

    if ($handle = opendir('/path/to/files')) {
        echo "Entradas:\n";

        /* Manejo correcto de las entradas de directorio que pueden ser consideradas falsas */
        while (false !== ($entry = readdir($handle))) {
            if ($entry === '.' || $entry === '..') {
                continue;
            }
            echo "$entry\n";
        }

        closedir($handle);
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Entradas:
    base
    en
    fr
    output.md
    test.php

### Ver también

- readdir() - Leer entrada desde el manejador de directorio
- rewinddir() - Reinicia el gestor de directorio
- closedir() - Cerrar el gestor de directorio
- dir() - Devuelve una instancia de la clase Directory
- is_dir() - Indica si el fichero es un directorio
- glob() - Búsqueda de rutas que coinciden con un patrón
- scandir() - Lista los ficheros y directorios en un directorio

# readdir

(PHP 4, PHP 5, PHP 7, PHP 8)

readdir — Leer entrada desde el manejador de directorio

### Descripción

function readdir(?resource `$dir_handle` = `null`): string|false

Devuelve el nombre de la siguiente entrada en el directorio. Las entradas se devuelven en el orden en que están almacenadas por el sistema de archivos.

### Parámetros

`dir_handle`
  Un manejador de directorio resource previamente abierto con opendir(). Si `dir_handle` es `null` se utilizará el último manejador abierto usando opendir().

### Valores devueltos

Devuelve el nombre de la entrada en caso de éxito, o `false` si ocurre un error.

Advertencia

Esta función puede retornar `false`, pero también puede retornar un valor equivalente a `false`. Por favor, lea la sección sobre los booleanos para más información. Utilice el operador === para probar el valor de retorno exacto de esta función.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | Usar `null` para `dir_handle` ahora está deprecado. En su lugar, debe proporcionarse explícitamente el último manejador de directorio abierto.
8.0.0 | `dir_handle` ahora es nullable.

### Ejemplos

Para un ejemplo completo, consulte la documentación de opendir().

### Ver también

- opendir() - Abrir un manejador de directorio
- rewinddir() - Reinicia el gestor de directorio
- closedir() - Cerrar el gestor de directorio
- dir() - Devuelve una instancia de la clase Directory
- is_dir() - Indica si el fichero es un directorio
- glob() - Búsqueda de rutas que coinciden con un patrón
- scandir() - Lista los ficheros y directorios en un directorio

# rewinddir

(PHP 4, PHP 5, PHP 7, PHP 8)

rewinddir — Reinicia el gestor de directorio

### Descripción

function rewinddir(?resource `$dir_handle` = `null`): void

Reinicia el flujo de directorio indicado por `dir_handle` al principio del directorio.

### Parámetros

`dir_handle`
  Un gestor de directorio resource previamente abierto con opendir(). Si `dir_handle` es `null` se utilizará el último gestor abierto usando opendir().

### Valores devueltos

No se retorna ningún valor.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | Usar `null` para `dir_handle` ahora está obsoleto. En su lugar, debe proporcionarse explícitamente el último gestor de directorio abierto.
8.0.0 | `dir_handle` ahora es nullable.

### Ejemplos

Para un ejemplo completo, consulte la documentación de opendir().

### Ver también

- opendir() - Abrir un manejador de directorio
- readdir() - Leer entrada desde el manejador de directorio
- closedir() - Cerrar el gestor de directorio
- dir() - Devuelve una instancia de la clase Directory
- is_dir() - Indica si el fichero es un directorio
- glob() - Búsqueda de rutas que coinciden con un patrón
- scandir() - Lista los ficheros y directorios en un directorio

# scandir

(PHP 5, PHP 7, PHP 8)

scandir — Lista los ficheros y directorios en un directorio

### Descripción

function scandir(string `$directory`, int `$sorting_order` = `SCANDIR_SORT_ASCENDING`, ?resource `$context` = `null`): array|false

Devuelve un array de ficheros y directorios provenientes de `directory`.

### Parámetros

`directory`

  El directorio que será analizado.

`sorting_order`

  Por omisión, el orden es alfabético ascendente. Si el parámetro opcional `sorting_order` es definido a `SCANDIR_SORT_DESCENDING`, entonces el orden será alfabético descendente. Si este parámetro es definido a `SCANDIR_SORT_NONE`, entonces el resultado no será ordenado.

`context`

  Para una descripción del parámetro `context`, consulte la sección flujo de datos del manual.

### Valores devueltos

Devuelve un array de nombres de ficheros en caso de éxito o `false` en caso de fallo. Si `directory` no es un directorio, entonces se devuelve un valor booleano `false` y se genera un error de nivel `E_WARNING`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `context` ahora es nullable.

### Ejemplos

Ejemplo #1 Un simple ejemplo con scandir()

    <?php
    $dir    = '/tmp';
    $files1 = scandir($dir);
    $files2 = scandir($dir, SCANDIR_SORT_DESCENDING);

    print_r($files1);
    print_r($files2);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => .
        [1] => ..
        [2] => bar.php
        [3] => foo.txt
        [4] => somedir
    )
    Array
    (
        [0] => somedir
        [1] => foo.txt
        [2] => bar.php
        [3] => ..
        [4] => .
    )

### Notas

Sugerencia

Puede utilizar una URL como nombre de archivo con esta función, si el gestor fopen ha sido activado. Véase fopen() para más detalles sobre cómo especificar el nombre del archivo. Consulte Protocolos y Envolturas soportados para más información sobre las capacidades de los diferentes gestores, las notas sobre su uso, así como la información sobre las variables predefinidas que proporcionan.

### Ver también

- opendir() - Abrir un manejador de directorio
- readdir() - Leer entrada desde el manejador de directorio
- glob() - Búsqueda de rutas que coinciden con un patrón
- is_dir() - Indica si el fichero es un directorio
- sort() - Ordena un array en orden creciente

## Tabla de contenidos

- chdir — Cambia de directorio
- chroot — Cambia el directorio raíz
- closedir — Cerrar el gestor de directorio
- dir — Devuelve una instancia de la clase Directory
- getcwd — Devuelve el directorio de trabajo actual
- opendir — Abrir un manejador de directorio
- readdir — Leer entrada desde el manejador de directorio
- rewinddir — Reinicia el gestor de directorio
- scandir — Lista los ficheros y directorios en un directorio

- Constantes predefinidas
- Directory — La clase Directory
  - Directory::close — Cierra el manejador de directorio
  - Directory::read — Lee una entrada desde el manejador de directorio
  - Directory::rewind — Reinicia el manejador de directorio
- Funciones de directorio
  - chdir — Cambia de directorio
  - chroot — Cambia el directorio raíz
  - closedir — Cerrar el gestor de directorio
  - dir — Devuelve una instancia de la clase Directory
  - getcwd — Devuelve el directorio de trabajo actual
  - opendir — Abrir un manejador de directorio
  - readdir — Leer entrada desde el manejador de directorio
  - rewinddir — Reinicia el gestor de directorio
  - scandir — Lista los ficheros y directorios en un directorio

# Información de un fichero

# Introducción

Las funciones en este módulo tratan de averiguar el tipo de contenido y la codificación de un fichero buscando ciertas secuencias de bytes mágicas en una posición específica del mismo. Aunque no es una estrategia "a prueba de balas", la heurística empleada realiza un trabajo realmente bueno.

# Instalación/Configuración

## Tabla de contenidos

- Instalación
- Tipos de recursos

## Instalación

Esta extensión está activada por omisión.

Los usuarios de Windows deben incluir la biblioteca DLL proporcionada php_fileinfo.dll en su php.ini para activar esta extensión.

La biblioteca libmagic se proporciona con PHP, pero incluye cambios específicos para PHP. Un parche de libmagic denominado libmagic.patch se mantiene y puede ser encontrado en el código fuente de la extensión fileinfo de PHP.

## Tipos de recursos

Antes de PHP 8.1.0, se utilizaba un recurso en la extensión Fileinfo: un descriptor mágico de base de datos devuelto por finfo_open().

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`FILEINFO_NONE` (int)
  No se realiza ningún tratamiento especial.
`FILEINFO_SYMLINK` (int)
  Sigue los enlaces simbólicos.
`FILEINFO_MIME_TYPE` (int)
  Devuelve el tipo MIME.
`FILEINFO_MIME_ENCODING` (int)
  Devuelve la codificación MIME del fichero.
`FILEINFO_MIME` (int)
  Devuelve el tipo MIME y la codificación MIME, tal como se describe en la RFC 2045.
`FILEINFO_COMPRESS` (int)
  Descomprime los ficheros comprimidos. Desactivado debido a las consecuencias en la seguridad de los hilos.
`FILEINFO_DEVICES` (int)
  Examina los contenidos de los bloques o dispositivos especiales de caracteres.
`FILEINFO_CONTINUE` (int)
  Devuelve todos los datos encontrados, no solo el primero.
`FILEINFO_PRESERVE_ATIME` (int)
  Si es posible, conserva el tiempo de acceso al fichero original.
`FILEINFO_RAW` (int)
  No traduce los caracteres no imprimibles a representación octal `\ooo`.
`FILEINFO_EXTENSION` (int)
  Devuelve la extensión de fichero apropiada para un tipo MIME detectado en el fichero. Para los tipos que generalmente tienen múltiples extensiones de fichero, tales como las imágenes `JPEG`, el valor devuelto es varias extensiones separadas por una barra oblicua, por ejemplo: `"jpeg/jpg/jpe/jfif"`. Para los tipos desconocidos no disponibles en la base de datos magic.mime, el valor devuelto es `"???"`. Disponible a partir de PHP 7.2.0.
`FILEINFO_APPLE` (int)
  Devuelve el creador y tipo de Apple.

# Funciones de Fileinfo

# finfo_buffer

# finfo::buffer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_buffer -- finfo::buffer — Devuelve información acerca de un string de buffer

### Descripción

Estilo procedimental

function finfo_buffer(
finfo `$finfo`,
string `$string`,
int `$flags` = `FILEINFO_NONE`,
?resource `$context` = `null`
): string|false

Estilo orientado a objetos

public function finfo::buffer(string `$string`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

Esta función se utiliza para obtener información acerca de datos binarios en un string.

### Parámetros

`finfo`
  Una instancia finfo, retornada por finfo_open().
`string`
  Contenido de un fichero a ser verificado.
`flags`
  Una o una unión de varias constantes Fileinfo.
`context`

### Valores devueltos

Devuelve una descripción textual del argumento `string` o `false` si ha ocurrido un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | El parámetro `context` ha quedado obsoleto puesto que es ignorado.
8.1.0 | El parámetro `finfo` ahora espera una instancia de finfo ; anteriormente, una resource era esperado.
8.0.0 | `context` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con finfo_buffer()

    <?php
    $finfo = new finfo(FILEINFO_MIME);
    echo $finfo->buffer($_POST["script"]) . "\n";
    ?>

Resultado del ejemplo anterior es similar a:

    application/x-sh; charset=us-ascii

### Ver también

- finfo_file() - Devuelve información acerca de un fichero

# finfo_close

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_close — Cierra una instancia finfo

Advertencia

Esta función está OBSOLETA a partir de PHP 8.5.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function finfo_close(finfo `$finfo`): true

Esta función se utilizaba para cerrar la instancia abierta por finfo_open() hasta PHP 7.4, pero es una operación sin efecto (no-op) desde la conversión del recurso finfo a objeto realizada en PHP 8.0, y ha sido declarada obsoleta en PHP 8.5.

### Parámetros

`finfo`
  Una instancia finfo, retornada por finfo_open().

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | Esta función ha sido declarada obsoleta.
8.5.0 | El tipo de retorno es ahora `true`; anteriormente, era bool.
8.1.0 | Esta función es ahora una NOP.
8.1.0 | El parámetro `finfo` ahora espera una instancia de finfo ; anteriormente, una resource era esperado.

# finfo_file

# finfo::file

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_file -- finfo::file — Devuelve información acerca de un fichero

### Descripción

Estilo procedimental

function finfo_file(
finfo `$finfo`,
string `$filename`,
int `$flags` = `FILEINFO_NONE`,
?resource `$context` = `null`
): string|false

Estilo orientado a objetos

public function finfo::file(string `$filename`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

Esta función se utiliza para obtener información acerca de un fichero.

### Parámetros

`finfo`
  Una instancia finfo, retornada por finfo_open().
`filename`
  Nombre de un fichero a verificar.
`flags`
  Una o una unión de varias constantes Fileinfo.
`context`
  Para una descripción de `contexts`, consúltese Funciones de Flujos.

### Valores devueltos

Devuelve una descripción textual del contenido del argumento `filename` o `false` si ha ocurrido un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `finfo` ahora espera una instancia de finfo ; anteriormente, una resource era esperado.
8.0.0 | `context` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con finfo_file()

    <?php
    $finfo = finfo_open(FILEINFO_MIME_TYPE); // Devuelve el tipo mime también llamado extensión mimetype
    foreach (glob("*") as $filename) {
        echo finfo_file($finfo, $filename) . "\n";
    }
    finfo_close($finfo);
    ?>

Resultado del ejemplo anterior es similar a:

    text/html
    image/gif
    application/vnd.ms-excel

### Ver también

- finfo_buffer() - Devuelve información acerca de un string de buffer

# finfo_open

# finfo::__construct

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_open -- finfo::__construct — Crea una nueva instancia finfo

### Descripción

Estilo procedimental

function finfo_open(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`): finfo|false

Estilo orientado a objetos (constructor):

public function finfo::__construct(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`)

Esta función abre una base de datos mágica y devuelve su instancia.

### Parámetros

`flags`
  Una o una unión de varias constantes Fileinfo.
`magic_database`
  Nombre de fichero de una base de datos mágica, normalmente algo como /path/to/magic.mime. Si no se especifica, se utiliza la variable de entorno `MAGIC`. Si la variable de entorno no está definida, se utilizará la base de datos mágica integrada en PHP. Pasar `null` o un string vacío equivale a utilizar el valor por omisión.

### Valores devueltos

(Únicamente en modo procedimental) Devuelve una instancia de finfo en caso de éxito, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Ahora devuelve una instancia de finfo ; anteriormente, se esperaba una resource.
8.0.3 | `magic_database` ahora es nullable.

### Ejemplos

Ejemplo #1 Estilo orientado a objetos

    <?php
    $finfo = new finfo(FILEINFO_MIME, "/usr/share/misc/magic"); // Devuelve el tipo mime

    /* Obtiene el mime-type de un fichero específico */
    $filename = "/usr/local/something.txt";
    echo $finfo->file($filename);

    ?>

Ejemplo #2 Estilo procedimental

    <?php
    $finfo = finfo_open(FILEINFO_MIME, "/usr/share/misc/magic"); // Devuelve el tipo mime

    if (!$finfo) {
        echo "Fallo al abrir la base de datos fileinfo";
        exit();
    }

    /* Obtiene el mime-type de un fichero específico */
    $filename = "/usr/local/something.txt";
    echo finfo_file($finfo, $filename);

    /* Cierre de la conexión */
    finfo_close($finfo);
    ?>

El ejemplo anterior mostrará:

    text/plain; charset=us-ascii

### Notas

> Nota: Generalmente, el uso de la base de datos mágica integrada (dejando las variables de entorno `magic_database` y `MAGIC` no definidas) es la mejor solución a menos que se necesite una base de datos mágica específica.

### Ver también

- finfo_close() - Cierra una instancia finfo

# finfo_set_flags

# finfo::set_flags

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_set_flags -- finfo::set_flags — Establece opciones de configuración de libmagic

### Descripción

Estilo procedimental

function finfo_set_flags(finfo `$finfo`, int `$flags`): true

Estilo orientado a objetos

public function finfo::set_flags(int `$flags`): true

Esta función establece diversas opciones de Fileinfo. Las opciones pueden ser también establecidas directamente en finfo_open() o por otras funciones Fileinfo.

### Parámetros

`finfo`
  Una instancia finfo, retornada por finfo_open().
`flags`
  Una o una unión de varias constantes Fileinfo.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `finfo` ahora espera una instancia de finfo ; anteriormente, una resource era esperado.

# mime_content_type

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mime_content_type — Detecta el tipo de contenido de un fichero

### Descripción

function mime_content_type(resource|string `$filename`): string|false

Devuelve el contenido MIME de un fichero utilizando las informaciones desde el fichero magic.mime.

### Parámetros

`filename`
  Ruta hacia el fichero a probar.

### Valores devueltos

Devuelve el tipo de contenido en formato MIME, como `text/plain` o `application/octet-stream`, o `false` si ocurre un error.

### Errores/Excepciones

En caso de fallo, se emitirá una advertencia de tipo `E_WARNING`.

### Ejemplos

Ejemplo #1 Ejemplo con mime_content_type()

    <?php
    echo mime_content_type('php.gif') . "\n";
    echo mime_content_type('test.php');
    ?>

El ejemplo anterior mostrará:

    image/gif
    text/plain

### Ver también

- finfo_file() - Devuelve información acerca de un fichero
- finfo_buffer() - Devuelve información acerca de un string de buffer

## Tabla de contenidos

- finfo_buffer — Devuelve información acerca de un string de buffer
- finfo_close — Cierra una instancia finfo
- finfo_file — Devuelve información acerca de un fichero
- finfo_open — Crea una nueva instancia finfo
- finfo_set_flags — Establece opciones de configuración de libmagic
- mime_content_type — Detecta el tipo de contenido de un fichero

# La clase finfo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

## Introducción

Esta clase proporciona una interfaz orientada a objetos para las funciones fileinfo.

## Sinopsis de la Clase

class finfo {
/* Métodos */
public function __construct(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`)
public function buffer(string `$string`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false
public function file(string `$filename`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false
public function set_flags(int `$flags`): true
}

# finfo::buffer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::buffer — Alias de finfo_buffer()

### Descripción

public function finfo::buffer(string `$string`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

Esta función es un alias de: finfo_buffer()

# finfo::__construct

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::__construct — Alias de finfo_open()

### Descripción

public function finfo::__construct(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`)

Esta función es un alias de: finfo_open()

### Historial de cambios

Versión | Descripción
--- | ---
8.0.3 | `magic_database` es ahora nullable.

# finfo::file

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::file — Alias de finfo_file()

### Descripción

public function finfo::file(string `$filename`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

Esta función es un alias de: finfo_file()

# finfo::set_flags

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::set_flags — Alias de finfo_set_flags()

### Descripción

public function finfo::set_flags(int `$flags`): true

Esta función es un alias de: finfo_set_flags()

## Tabla de contenidos

- finfo::buffer — Alias de finfo_buffer()
- finfo::__construct — Alias de finfo_open
- finfo::file — Alias de finfo_file()
- finfo::set_flags — Alias de finfo_set_flags()

- Instalación/Configuración
  - Instalación
  - Tipos de recursos
- Constantes predefinidas
- Funciones de Fileinfo
  - finfo_buffer — Devuelve información acerca de un string de buffer
  - finfo_close — Cierra una instancia finfo
  - finfo_file — Devuelve información acerca de un fichero
  - finfo_open — Crea una nueva instancia finfo
  - finfo_set_flags — Establece opciones de configuración de libmagic
  - mime_content_type — Detecta el tipo de contenido de un fichero
- finfo — La clase finfo
  - finfo::buffer — Alias de finfo_buffer()
  - finfo::__construct — Alias de finfo_open
  - finfo::file — Alias de finfo_file()
  - finfo::set_flags — Alias de finfo_set_flags()

# Sistema de Ficheros

# Introducción

No es necesaria ninguna biblioteca externa para compilar esta extensión, pero si quiere que PHP admita LFS (ficheros grandes) en Linux, necesita tener una versión reciente de glibc y compilar PHP con las siguientes banderas de compilación: `-D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64`.

# Instalación/Configuración

## Tabla de contenidos

- Configuración en tiempo de ejecución
- Tipos de recursos

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración del sistema de ficheros y flujos
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
allow_url_fopen | "1" | `INI_SYSTEM` |
allow_url_include | "0" | `INI_SYSTEM` | Obsoleto a partir de PHP 7.4.0.
user_agent | NULL | `INI_ALL` |
default_socket_timeout | "60" | `INI_ALL` |
from | "" | `INI_ALL` |
auto_detect_line_endings | "0" | `INI_ALL` | Obsoleto a partir de PHP 8.1.0.
sys_temp_dir | "" | `INI_SYSTEM` |

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`allow_url_fopen` bool

  Esta opción habilita las envolturas fopen de tipo URL que permiten el acceso a objetos URL como ficheros. Las envolturas predeterminadas están proporcionads para el acceso de ficheros remotos usando los protocolos ftp o http, algunas extensiones como zlib pueden registrar envolturas adicionales.

`allow_url_include` bool

  Esta opción permite es uso de envolturas fopen de tipo URL con las siguientes funciones: include, include_once, require, require_once.

  > Nota:

  > Esta opción requiere allow_url_fopen para ser activada.

`user_agent` string

  Define el agente de usuario de PHP para el envío.

`default_socket_timeout` int

  Tiempo de espera predeterminado (en segundos) para sockets basados en flujos. Especificar un valor negativo significa tiempo de espera infinito.

`from` string

  La dirección de email a usar en conexiones FTP no autenticadas y como valor de la cabecera From de conexiones HTTP, al usar las envolturas ftp y http, respectivamente.

`auto_detect_line_endings` bool

  Cuando se activa, PHP examinará la información leída por fgets() y file() para ver si se está usando las convenciones de final de línea de Unix, MS-Dos o Macintosh.

  Esto permite a PHP inter-operar con los sistemas Macintosh, pero por defecto está en Off, ya que hay una pérdida muy pequeña de rendimiento cuando se detectan las convenciones de EOL para la primera línea, y también porque la gente que usa retornos de carro como elementos serparadores bajo sistemas Unix podrían experimentar un comportamiento que no es compatible con versiones anteriores.

`sys_temp_dir` string

## Tipos de recursos

El sistema de ficheros usa `flujos` como su tipo de recursos. Los flujos están documentados en su propio capítulo de referencia, Flujos.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`SEEK_SET` (int)
`SEEK_CUR` (int)
`SEEK_END` (int)
`LOCK_SH` (int)
`LOCK_EX` (int)
`LOCK_UN` (int)
`LOCK_NB` (int)

`flags` disponibles para file()
`FILE_USE_INCLUDE_PATH` (int)
  Busca el `filename` en include_path.
`FILE_NO_DEFAULT_CONTEXT` (int)
`FILE_APPEND` (int)
  Añade contenido a un archivo existente.
`FILE_IGNORE_NEW_LINES` (int)
  Quita caracteres EOL.
`FILE_SKIP_EMPTY_LINES` (int)
  Salta líneas vacías.
`FILE_BINARY` (int)

  Modo texto

  Advertencia

  Esta constante no tiene efecto, y está obsoleta a partir de PHP 8.1.0.

`FILE_TEXT` (int)

  Text mode.

  Advertencia

  Esta constante no tiene efecto, y está obsoleta a partir de PHP 8.1.0.

`flags` disponibles para glob()
`GLOB_AVAILABLE_FLAGS` (int)
  Todas las flags `GLOB_*` combinadas. Equivalente a `0` | `GLOB_BRACE` | `GLOB_MARK` | `GLOB_NOSORT` | `GLOB_NOCHECK` | `GLOB_NOESCAPE` | `GLOB_ERR` | `GLOB_ONLYDIR`
`GLOB_BRACE` (int)
  Expande {a,b,c} para coincidir con 'a', 'b' o 'c'.

  > Nota: `GLOB_BRACE` no está disponible en algunos systemas non GNU, como Solaris o Alpine Linux.

`GLOB_ERR` (int)
  Detenerse ante errores de lectura (como directorios ilegibles), por defecto los errores son ignorados.
`GLOB_MARK` (int)
  Añade una barra (una barra invertida en Windows) a cada directorio devuelto.
`GLOB_NOCHECK` (int)
  Devolver el patrón de búsqueda si no se encontraron archivos que coincidan con él.
`GLOB_NOESCAPE` (int)
  Las barras invertidas no citan metacaracteres.
`GLOB_NOSORT` (int)
  Devolver los archivos tal como aparecen en el directorio (sin ordenar). Cuando no se usa este falg, los nombres de ruta se ordenan alfabéticamente.
`GLOB_ONLYDIR` (int)
  Devolver solo las entradas de directorio que coincidan con el patrón.

`flags` disponibles para pathinfo()
`PATHINFO_ALL` (int)
  Todas las partes de pathinfo son devueltas como un array asociativo.
`PATHINFO_DIRNAME` (int)
  La ruta del directorio o archivo.
`PATHINFO_BASENAME` (int)
  El nombre del directorio o el nombre y la extensión del archivo.
`PATHINFO_EXTENSION` (int)
  La extensión del archivo.
`PATHINFO_FILENAME` (int)
  El nombre del archivo (sin la extensión) o del directorio.

`scanner_mode`s disponibles para parse_ini_file() y parse_ini_string()
`INI_SCANNER_NORMAL` (int)
  Modo de escaneo INI normal.
`INI_SCANNER_RAW` (int)
  Modo de escaneo INI en bruto (RAW).
`INI_SCANNER_TYPED` (int)
  Modo de escaneo INI tipado.

`flags` disponibles para fnmatch()
`FNM_NOESCAPE` (int)
  Deshabilita el escapado de la barra invertida.
`FNM_PATHNAME` (int)
  Una barra en un string sólo concide con otra en el patrón dado.
`FNM_PERIOD` (int)
  Un punto en un string debe coincidir exactamente con otro en el patrón dado.
`FNM_CASEFOLD` (int)
  Comparación insensible a mayúsculas-minúsculas. Parte de la extensión GNU.

Constantes de subida de archivos en PHP
`UPLOAD_ERR_CANT_WRITE` (int)

  Error al escribir el archivo en el disco. El valor de la constante es `7`.

`UPLOAD_ERR_EXTENSION` (int)

  Una extensión de PHP detuvo la subida del archivo. PHP no proporciona una forma de determinar qué extensión causó la detención de la subida del archivo; examinar la lista de extensiones cargadas con phpinfo() puede ayudar. El valor de la constante es `8`.

`UPLOAD_ERR_FORM_SIZE` (int)

  El archivo subido excede la directiva MAX_FILE_SIZE especificada en el formulario HTML. El valor de la constante es `2`.

`UPLOAD_ERR_INI_SIZE` (int)

  El archivo subido excede la directiva upload_max_filesize en php.ini. El valor de la constante es `1`.

`UPLOAD_ERR_NO_FILE` (int)

  No se ha subido ningún archivo. El valor de la constante es `4`.

`UPLOAD_ERR_NO_TMP_DIR` (int)

  Directorio temporal no encontrado. El valor de la constante es `6`.

`UPLOAD_ERR_OK` (int)

  No hay error, el archivos se ha subido correctamente. El valor de la constante es `0`.

`UPLOAD_ERR_PARTIAL` (int)

  El archivo solo se ha subido parcialmente. El valor de la constante es `3`.

# Funciones del Sistema de Archivos

# Ver también

Para funciones relacionadas, vea también las secciones Directorio y Ejecución de Programas.

Para una lista y explicación de las distintas envolturas URL que se pueden usar como archivos remotos, vea también Protocolos y Envolturas soportados.

# basename

(PHP 4, PHP 5, PHP 7, PHP 8)

basename — Devuelve el nombre del componente final de una ruta

### Descripción

function basename(string `$path`, string `$suffix` = ""): string

Toma como argumento `path`, la ruta de un fichero o directorio y proporciona el nombre del último componente.

> Nota:

> basename() actúa de manera ingenua y no tiene conocimiento del sistema de archivos subyacente o de los componentes de una ruta tales como "`..`".

Precaución

basename() es sensible a la configuración local, por lo que si la ruta contiene caracteres multioctetos, la configuración local adecuada debe ser establecida mediante la función setlocale(). Si `path` contiene caracteres que son inválidos para la configuración local actual, el comportamiento de basename() es indefinido.

### Parámetros

`path`

  Una ruta.

  En Windows, los caracteres slash (`/`) y backslash (`\`) se utilizan como separadores de directorio. En otros sistemas operativos, solo el carácter slash (`/`) se utiliza.

`suffix`

  Si `suffix` es proporcionado, el sufijo también será eliminado.

### Valores devueltos

Devuelve el nombre base de la ruta `path` dada.

### Ejemplos

Ejemplo #1 Ejemplo con basename()

    <?php
    echo "1) ".basename("/etc/sudoers.d", ".d").PHP_EOL;
    echo "2) ".basename("/etc/sudoers.d").PHP_EOL;
    echo "3) ".basename("/etc/passwd").PHP_EOL;
    echo "4) ".basename("/etc/").PHP_EOL;
    echo "5) ".basename(".").PHP_EOL;
    echo "6) ".basename("/");
    ?>

El ejemplo anterior mostrará:

    1) sudoers
    2) sudoers.d
    3) passwd
    4) etc
    5) .
    6)

### Ver también

- dirname() - Devuelve la ruta de la carpeta padre
- pathinfo() - Devuelve información sobre una ruta del sistema

# chgrp

(PHP 4, PHP 5, PHP 7, PHP 8)

chgrp — Cambia el grupo de un fichero

### Descripción

function chgrp(string `$filename`, string|int `$group`): bool

Intenta reemplazar el grupo propietario actual del fichero `filename` por `group`.

Solo el superusuario (root) puede cambiar el grupo propietario de un fichero arbitrariamente; los usuarios comunes solo pueden cambiar el grupo propietario de un fichero si el usuario propietario del fichero es miembro del grupo.

### Parámetros

`filename`

  Ruta hacia el fichero.

`group`

  Un nombre o un número de grupo.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Modificación de grupo de un fichero

    <?php
    $filename = 'shared_file.txt';
    $format = "%s's Group ID @ %s: %d\n";
    printf($format, $filename, date('r'), filegroup($filename));
    chgrp($filename, 8);
    clearstatcache(); // no almacenar en caché el resultado de filegroup()
    printf($format, $filename, date('r'), filegroup($filename));
    ?>

### Notas

> Nota: Esta función no funciona con los archivos remotos, ya que el archivo examinado debe ser accesible en el sistema de archivos del servidor.

> Nota: En Windows, esta función falla silenciosamente cuando se aplica sobre un fichero ordinario.

### Ver también

- chown() - Cambia el propietario del fichero
- chmod() - Cambia el modo del fichero

# chmod

(PHP 4, PHP 5, PHP 7, PHP 8)

chmod — Cambia el modo del fichero

### Descripción

function chmod(string `$filename`, int `$permissions`): bool

Reemplaza el modo del fichero `filename` por el modo `permissions`.

### Parámetros

`filename`

  Ruta hacia el fichero.

`permissions`

  Se debe tener en cuenta que el modo `permissions` es considerado como un número en notación octal, por lo que, para asegurarse, se puede prefigurar el modo `permissions` con un cero. Las cadenas como "g+w" no funcionarán correctamente:

      <?php
      chmod("/somedir/somefile", 755);   // notación decimal: probablemente incorrecto
      chmod("/somedir/somefile", "u+rwx,go+rx"); // string: incorrecto
      chmod("/somedir/somefile", 0755);  // notación octal: valor del modo correcto
      ?>

  El argumento `permissions` se compone de tres valores octales que especifican los derechos para el propietario, el grupo del propietario y los demás, respectivamente. Cada componente puede ser calculado sumando los derechos deseados. El número 1 otorga los derechos de ejecución, el número 2 los derechos de escritura y el número 4 los derechos de lectura. Simplemente sume estos números para especificar los derechos deseados. También puede leer el manual de los sistemas Unix con man 1 chmod y man 2 chmod.

      <?php
      // Lectura y escritura para el propietario, nada para los demás
      chmod("/somedir/somefile", 0600);

      // Lectura y escritura para el propietario, lectura para los demás
      chmod("/somedir/somefile", 0644);

      // Todo para el propietario, lectura y ejecución para los demás
      chmod("/somedir/somefile", 0755);

      // Todo para el propietario, lectura y ejecución para el grupo, nada para los demás
      chmod("/somedir/somefile", 0750);
      ?>

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

En caso de error, se emite un error `E_WARNING`.

### Notas

> Nota:

> El usuario actual es el usuario con el que PHP funciona. Probablemente sea diferente del usuario que se utiliza en modo Shell o FTP. El modo solo puede ser modificado por el usuario al que pertenece el fichero en la mayoría de los sistemas.

> Nota: Esta función no funciona con los archivos remotos, ya que el archivo examinado debe ser accesible en el sistema de archivos del servidor.

### Ver también

- chown() - Cambia el propietario del fichero
- chgrp() - Cambia el grupo de un fichero
- fileperms() - Lee los permisos de un fichero
- stat() - Proporciona información sobre un fichero

# chown

(PHP 4, PHP 5, PHP 7, PHP 8)

chown — Cambia el propietario del fichero

### Descripción

function chown(string `$filename`, string|int `$user`): bool

Cambia el propietario del fichero `filename` a `user`. Solo el superusuario (root) puede cambiar arbitrariamente el propietario de un fichero.

### Parámetros

`filename`

  Ruta hacia el fichero.

`user`

  Un nombre o un número de usuario.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con chown()

    <?php

    // Nombre del fichero y nombre de usuario a utilizar
    $file_name= "foo.php";
    $path = "/home/sites/php.net/public_html/sandbox/" . $file_name ;
    $user_name = "root";

    // Define el usuario
    chown($path, $user_name);

    // Verificación del resultado
    $stat = stat($path);
    print_r(posix_getpwuid($stat['uid']));

    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [name] => root
        [passwd] => x
        [uid] => 0
        [gid] => 0
        [gecos] => root
        [dir] => /root
        [shell] => /bin/bash
    )

### Notas

> Nota: Esta función no funciona con los archivos remotos, ya que el archivo examinado debe ser accesible en el sistema de archivos del servidor.

> Nota: En Windows, esta función falla silenciosamente cuando se aplica sobre un fichero ordinario.

### Ver también

- chmod() - Cambia el modo del fichero
- chgrp() - Cambia el grupo de un fichero

# clearstatcache

(PHP 4, PHP 5, PHP 7, PHP 8)

clearstatcache — Elimina la caché de stat()

### Descripción

function clearstatcache(bool `$clear_realpath_cache` = `false`, string `$filename` = ""): void

La llamada a la función stat() o lstat() es relativamente costosa en términos de tiempo de ejecución. Por ello, el resultado de la última llamada a una de las funciones de estado (ver la lista a continuación) se guarda para su reutilización. Si se desea forzar la verificación del estado de un fichero, en el caso de que el fichero hubiera podido ser modificado o hubiera desaparecido, se debe utilizar la función clearstatcache() para borrar de la memoria los resultados de la última llamada a la función.

Tenga en cuenta que PHP no guarda en caché información sobre un fichero inexistente. Si se llama a file_exists() sobre un fichero que no existe, la función devolverá `false` hasta que se cree el fichero. Si se crea el fichero, la función devolverá `true` incluso si se borra el fichero.

> Nota:

> Esta función guarda en caché información sobre ficheros. Por lo tanto, solo es necesario llamar a clearstatcache() si se realizan múltiples operaciones sobre el directorio, y se desea tener una versión actualizada de la información.

Las funciones afectadas incluyen : stat(), lstat(), file_exists(), is_writable(), is_readable(), is_executable(), is_file(), is_dir(), is_link(), filectime(), fileatime(), filemtime(), fileinode(), filegroup(), fileowner(), filesize(), filetype(), y fileperms().

### Parámetros

`clear_realpath_cache`

  Si también debe vaciarse la caché de rutas reales.

`filename`

  Limpia la caché de ruta real de un fichero específico. Solo puede ser utilizado si el argumento `clear_realpath_cache` vale `true`.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con clearstatcache()

    <?php
    $file = 'output_log.txt';

    function get_owner($file)
    {
        $stat = stat($file);
        $user = posix_getpwuid($stat['uid']);
        return $user['name'];
    }

    $format = "UID @ %s: %s\n";

    printf($format, date('r'), get_owner($file));

    chown($file, 'ross');
    printf($format, date('r'), get_owner($file));

    clearstatcache();
    printf($format, date('r'), get_owner($file));
    ?>

Resultado del ejemplo anterior es similar a:

    UID @ Sun, 12 Oct 2008 20:48:28 +0100: root
    UID @ Sun, 12 Oct 2008 20:48:28 +0100: root
    UID @ Sun, 12 Oct 2008 20:48:28 +0100: ross

# copy

(PHP 4, PHP 5, PHP 7, PHP 8)

copy — Copia un fichero

### Descripción

function copy(string `$from`, string `$to`, ?resource `$context` = `null`): bool

Realiza una copia del fichero `from` hacia el fichero `to`.

Si se desea mover un fichero, utilice la función rename().

### Parámetros

`from`

  Ruta hacia el fichero origen.

`to`

  La ruta de destino. Si `to` es una URL, la copia puede fallar si este protocolo no soporta la sobrescritura de ficheros existentes.

  Advertencia

  Si el fichero de destino `to` ya existe, será sobrescrito.

`context`

  Un recurso de contexto válido, creado por la función stream_context_create().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con copy()

    <?php
    $file = 'example.txt';
    $newfile = 'example.txt.bak';

    if (!copy($file, $newfile)) {
        echo "La copia $file del fichero ha fallado...\n";
    }
    ?>

### Ver también

- move_uploaded_file() - Mueve un archivo subido a una nueva ubicación
- rename() - Renombra un fichero o un directorio
- La sección del manual relativa a la gestión de subidas de ficheros

# delete

delete — Ver unlink() o unset()

### Descripción

No existe una palabra clave o función delete en el lenguaje PHP. Si se ha llegado a esta página intentando eliminar un fichero, probar con unlink(). Para eliminar una variable del ámbito local, consultar unset().

### Ver también

- unlink() - Elimina un fichero
- unset() - unset destruye una variable

# dirname

(PHP 4, PHP 5, PHP 7, PHP 8)

dirname — Devuelve la ruta de la carpeta padre

### Descripción

function dirname(string `$path`, int `$levels` = 1): string

Devuelve la ruta padre de un camino que representa un fichero o una carpeta, que corresponde a `levels` nivel(es) más arriba que la carpeta actual.

> Nota:

> dirname() actúa de forma ingenua sobre la cadena de entrada y no está al tanto del sistema de archivos actual o de componentes eventuales como "`..`".

Precaución

En Windows, dirname() asume que la página de código actualmente definida, por lo que para que pueda ver el nombre de carpeta correcto con caracteres multioctetos en el camino, la página de código correspondiente debe estar definida. Si `path` contiene caracteres que son inválidos para la página de código actual, el comportamiento de dirname() es indefinido.

En otros sistemas, dirname() asume que `path` está codificado en un codificación compatible con ASCII. De lo contrario, el comportamiento de la función es indefinido.

### Parámetros

`path`

  Un camino.

  En Windows, las barras (/`/`) y backslash (`\`) se utilizan como separadores de carpeta. En otros entornos, solo la barra (`/`) se utiliza.

`levels`

  El número de carpetas padres más arriba.

  Debe ser un integer superior a 0.

### Valores devueltos

Devuelve la carpeta padre del camino. Si no hay ninguna barra en el camino `path`, un punto ('`.`') será devuelto, indicando la carpeta actual. De lo contrario, la cadena devuelta será el camino `path` del cual se habrán eliminado todos los `/component`.

Precaución

Se debe tener cuidado al utilizar esta función en un ciclo que pueda alcanzar la carpeta raíz, ya que esto puede producir un ciclo infinito.

    <?php
    dirname('.');    // Devolverá '.'.
    dirname('/');    // Devolverá `\` en Windows y '/' en sistemas *nix.
    dirname('\\');   // Devolverá `\` en Windows y '.' en sistemas *nix.
    dirname('C:\\'); // Devolverá 'C:\' en Windows y '.' en sistemas *nix.
    ?>

### Ejemplos

Ejemplo #1 Ejemplo con dirname()

    <?php
    echo dirname("/etc/passwd") . PHP_EOL;
    echo dirname("/etc/") . PHP_EOL;
    echo dirname(".") . PHP_EOL;
    echo dirname("C:\\") . PHP_EOL;
    echo dirname("/usr/local/lib", 2);

Resultado del ejemplo anterior es similar a:

    /etc
    / (o \ en Windows)
    .
    C:\
    /usr

### Ver también

- basename() - Devuelve el nombre del componente final de una ruta
- pathinfo() - Devuelve información sobre una ruta del sistema
- realpath() - Retorna la ruta de acceso canónica absoluta

# disk_free_space

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

disk_free_space — Devuelve el espacio en disco disponible en el sistema de archivos o partición

### Descripción

function disk_free_space(string `$directory`): float|false

Devuelve el espacio en disco disponible en el directorio o partición.

### Parámetros

`directory`

  Un directorio del sistema de archivos o una partición de disco.

  > Nota:

  > Si se proporciona un fichero en lugar de un directorio, el comportamiento de esta función puede ser aleatorio, dependiendo del sistema operativo y las versiones de PHP.

### Valores devueltos

Devuelve el número de bytes disponibles, en forma de float o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con disk_free_space()

    <?php
    // $df contiene el número de bytes libres en "/"
    $df = disk_free_space("/");

    // En Windows:
    $df_c = disk_free_space("C:");
    $df_d = disk_free_space("D:");
    ?>

### Notas

> Nota: Esta función no funciona con los archivos remotos, ya que el archivo examinado debe ser accesible en el sistema de archivos del servidor.

### Ver también

- disk_total_space() - Devuelve el tamaño de un directorio o partición

# disk_total_space

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

disk_total_space — Devuelve el tamaño de un directorio o partición

### Descripción

function disk_total_space(string `$directory`): float|false

Lee recursivamente todos los tamaños del directorio `directory` y devuelve la suma en bytes.

### Parámetros

`directory`

  Un directorio del sistema de archivos o la partición de un disco.

### Valores devueltos

Devuelve el tamaño en bytes, en forma de float o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con disk_total_space()

    <?php
    // $ds contiene el número de bytes del directorio "/"
    $ds = disk_total_space("/");

    // En Windows:
    $ds = disk_total_space("C:");
    $ds = disk_total_space("D:");
    ?>

### Notas

> Nota: Esta función no funciona con los archivos remotos, ya que el archivo examinado debe ser accesible en el sistema de archivos del servidor.

### Ver también

- disk_free_space() - Devuelve el espacio en disco disponible en el sistema de archivos o partición

# diskfreespace

(PHP 4, PHP 5, PHP 7, PHP 8)

diskfreespace — Alias de disk_free_space()

### Descripción

Esta función es un alias de: disk_free_space().

# fclose

(PHP 4, PHP 5, PHP 7, PHP 8)

fclose — Cierra un fichero

### Descripción

function fclose(resource `$stream`): bool

Cierra el fichero representado por el puntero `stream`.

### Parámetros

`stream`

  El puntero de fichero debe ser válido y debe haber sido correctamente abierto por la función fopen() o la función fsockopen().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con fclose()

    <?php

    $handle = fopen('somefile.txt', 'r');

    fclose($handle);

    ?>

### Ver también

- fopen() - Abre un fichero o un URL
- fsockopen() - Abre un socket de conexión Internet o Unix

# fdatasync

(PHP 8 >= 8.1.0)

fdatasync — Sincroniza los datos (pero no los metadatos) con el fichero

### Descripción

function fdatasync(resource `$stream`): bool

Esta función sincroniza el contenido del `stream` en el soporte de almacenamiento, al igual que fsync(), pero no sincroniza los metadatos de los ficheros. Cabe señalar que esta función es diferente solo en sistemas POSIX. En Windows, esta función es un alias de fsync().

### Parámetros

`stream`
  El puntero de archivo debe ser válido y apuntar a un archivo abierto con éxito por fopen() o fsockopen() (y no cerrado aún por fclose()).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de fdatasync()

    <?php
    $file = 'test.txt';
    $stream = fopen($file, 'w');
    fwrite($stream, 'test data');
    fwrite($stream, "\r\n");
    fwrite($stream, 'additional data');
    fdatasync($stream);
    fclose($stream);
    ?>

### Ver también

- fflush() - Envía todo el contenido generado en un fichero
- fsync() - Sincroniza los cambios realizados en el fichero (incluyendo los metadatos)

# feof

(PHP 4, PHP 5, PHP 7, PHP 8)

feof — Prueba el final del archivo

### Descripción

function feof(resource `$stream`): bool

Prueba el final del archivo.

### Parámetros

`stream`
  El puntero de archivo debe ser válido y apuntar a un archivo abierto con éxito por fopen() o fsockopen() (y no cerrado aún por fclose()).

### Valores devueltos

Retorna `true` si el puntero `handle` está al final del archivo o si ocurre un error, de lo contrario, retorna `false`.

### Notas

Advertencia

Si una conexión abierta con fsockopen() no es cerrada por el servidor, feof() se bloqueará. Para evitar este comportamiento, consulte el ejemplo a continuación:

Ejemplo #1 Gestión de tiempos de espera excedidos feof()

    <?php
    function safe_feof($fp, &$start = NULL) {
     $start = microtime(true);

     return feof($fp);
    }

    /* Supongamos que $fp fue previamente abierto por fsockopen() */

    $start = NULL;
    $timeout = ini_get('default_socket_timeout');

    while(!safe_feof($fp, $start) && (microtime(true) - $start) < $timeout)
    {
     /* Gestión */
    }
    ?>

Advertencia

Si el puntero de archivo pasado no es válido, se obtendrá un bucle infinito ya que feof() fallará al retornar `true`.

Ejemplo #2 Ejemplo con feof() y un puntero de archivo inválido

    <?php
    // Si el archivo no puede ser leído o no existe, la función fopen retorna FALSE
    $file = @fopen("no_such_file", "r");

    // FALSE proveniente de fopen emitirá una advertencia y causará un bucle infinito aquí
    while (!feof($file)) {
    }

    fclose($file);
    ?>

# fflush

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

fflush — Envía todo el contenido generado en un fichero

### Descripción

function fflush(resource `$stream`): bool

Fuerza la escritura de todos los datos bufferizados en el fichero designado por `stream`.

### Parámetros

`stream`
  El puntero de archivo debe ser válido y apuntar a un archivo abierto con éxito por fopen() o fsockopen() (y no cerrado aún por fclose()).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Escritura de un fichero utilizando fflush()

    <?php
    $filename = 'bar.txt';

    $file = fopen($filename, 'r+');
    rewind($file);
    fwrite($file, 'Foo');
    fflush($file);
    ftruncate($file, ftell($file));
    fclose($file);
    ?>

### Ver también

- clearstatcache() - Elimina la caché de stat
- fwrite() - Escribe en un fichero en modo binario

# fgetc

(PHP 4, PHP 5, PHP 7, PHP 8)

fgetc — Lee un carácter en un fichero

### Descripción

function fgetc(resource `$stream`): string|false

Lee un carácter en un fichero.

### Parámetros

`stream`
  El puntero de archivo debe ser válido y apuntar a un archivo abierto con éxito por fopen() o fsockopen() (y no cerrado aún por fclose()).

### Valores devueltos

Devuelve una cadena que contiene un solo carácter, leído desde el fichero apuntado por `stream`. Devuelve `false` al final del fichero.

Advertencia

Esta función puede retornar `false`, pero también puede retornar un valor equivalente a `false`. Por favor, lea la sección sobre los booleanos para más información. Utilice el operador === para probar el valor de retorno exacto de esta función.

### Ejemplos

Ejemplo #1 Ejemplo con fgetc()

    <?php
    $fp = fopen('somefile.txt', 'r');
    if (!$fp) {
        echo 'No es posible abrir el fichero somefile.txt';
    }
    while (false !== ($char = fgetc($fp))) {
        echo "$char\n";
    }
    ?>

### Notas

> Nota: Esta función es segura para sistemas binarios.

### Ver también

- fread() - Lectura del archivo en modo binario
- fopen() - Abre un fichero o un URL
- popen() - Crea un puntero de archivo de proceso
- fsockopen() - Abre un socket de conexión Internet o Unix
- fgets() - Recupera la línea actual a partir de la posición del puntero de archivo

# fgetcsv

(PHP 4, PHP 5, PHP 7, PHP 8)

fgetcsv — Obtiene una línea desde un puntero de archivo y la analiza para campos CSV

### Descripción

function fgetcsv(
resource `$stream`,
?int `$length` = `null`,
string `$separator` = ",",
string `$enclosure` = "\"",
string `$escape` = "\\"
): array|false

Similar a fgets() pero fgetcsv() analiza la línea que lee y busca los campos CSV, que devuelve en un array que los contiene.

> Nota: Los parámetros de configuración local son tenidos en cuenta por esta función. Por ejemplo, los datos codificados en ciertos juegos de caracteres de un byte pueden ser analizados incorrectamente si `LC_CTYPE` es `en_US.UTF-8`.

### Parámetros

`stream`

  Un puntero válido a un archivo abierto con fopen(), popen() o fsockopen().

`length`

  Debe ser mayor que la línea más larga (en términos de caracteres) a leer en el archivo (incluyendo el carácter de fin de línea). En caso contrario la línea será dividida en fragmentos de `length` caracteres, a menos que la división ocurra dentro de un encierro.

  Omitir este parámetro (o establecerlo a 0, o `null` en PHP 8.0.0 o versiones posteriores) hace que la longitud máxima de la línea no esté limitada, lo cual es ligeramente más lento.

`separator`

  El parámetro `separator` define el separador de campo. Debe tratarse de un carácter de un solo byte.

`enclosure`

  El parámetro `enclosure` define el carácter de encierro de los campos. Debe tratarse de un carácter de un solo byte.

`escape`

  El parámetro `escape` define el carácter de escape. Debe tratarse de un carácter de un solo byte o una cadena vacía. La cadena vacía (`""`) desactiva el mecanismo de escape propietario.

  Advertencia

  En el flujo de entrada, el carácter `enclosure` siempre puede ser escapado duplicándolo dentro de una cadena entrecomillada, lo que resulta en un único carácter `enclosure` en el resultado analizado. El carácter `escape` funciona de manera diferente: si una secuencia de caracteres `escape` y `enclosure` aparece en la entrada, ambos caracteres estarán presentes en el resultado analizado. Así, para los parámetros por defecto, una línea CSV como `"a""b","c\"d"` tendrá los campos analizados como `a"b` y `c\"d`, respectivamente.

  Advertencia

  A partir de PHP 8.4.0, el uso del valor por omisión de `escape` está deprecado. Debe ser proporcionado explícitamente ya sea por posición o mediante el uso de los argumentos nombrados.

Advertencia

Cuando `escape` se define con un valor diferente a una cadena vacía (`""`), puede resultar en un CSV que no sea compatible con » RFC 4180 o que no pueda sobrevivir a un ciclo de ida y vuelta a través de las funciones CSV de PHP. El valor predeterminado de `escape` es `"\\"`, por lo que se recomienda definirlo explícitamente como cadena vacía. El valor predeterminado cambiará en una futura versión de PHP, no antes de PHP 9.0.

### Valores devueltos

Devuelve un array indexado que contiene los campos leídos en caso de éxito, o `false` si ocurre un error.

> Nota:

> Una línea vacía en un archivo CSV será devuelta en forma de un array que contiene el valor `null` y no será tratada como un error.

> Nota: Si PHP no reconoce correctamente los finales de línea al leer archivos que han sido creados o leídos en un Macintosh, la activación de la opción de configuración auto_detect_line_endings puede resolver el problema.

### Errores/Excepciones

Genera una ValueError si `separator` o `enclosure` no tiene una longitud de un byte.

Genera una ValueError si `escape` no tiene una longitud de un byte o es una cadena vacía.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Confiar en el valor por omisión de `escape` está ahora deprecado.
8.3.0 | Una cadena vacía es devuelta en lugar de una cadena que contiene un solo byte nulo para el último campo si este contiene únicamente un delimitador no terminado.
8.0.0 | `length` ahora es nullable.
7.4.0 | El parámetro `escape` ahora acepta una cadena vacía para desactivar el mecanismo de escape propietario.

### Ejemplos

Ejemplo #1 Lee y muestra el contenido de un archivo CSV

    <?php
    $row = 1;
    if (($handle = fopen("test.csv", "r")) !== FALSE) {
        while (($data = fgetcsv($handle, 1000, ",")) !== FALSE) {
            $num = count($data);
            echo "<p> $num campos en la línea $row: <br /></p>\n";
            $row++;
            for ($c=0; $c < $num; $c++) {
                echo $data[$c] . "<br />\n";
            }
        }
        fclose($handle);
    }
    ?>

### Ver también

- fputcsv() - Formatea una línea en CSV y la escribe en un fichero
- str_getcsv() - Analiza una string CSV en un array
- SplFileObject::fgetcsv() - Recupera una línea del archivo y la analiza como datos CSV
- SplFileObject::fputcsv() - Escribe un array en forma de línea CSV
- SplFileObject::setCsvControl() - Define las opciones CSV
- SplFileObject::getCsvControl() - Recupera las opciones para CSV
- explode() - Divide una string en segmentos
- file() - Lee el fichero y devuelve el resultado en un array
- pack() - Compacta datos en una cadena binaria

# fgets

(PHP 4, PHP 5, PHP 7, PHP 8)

fgets — Recupera la línea actual a partir de la posición del puntero de archivo

### Descripción

function fgets(resource `$stream`, ?int `$length` = `null`): string|false

Recupera la línea actual a partir de la posición del puntero de archivo.

### Parámetros

`stream`
  El puntero de archivo debe ser válido y apuntar a un archivo abierto con éxito por fopen() o fsockopen() (y no cerrado aún por fclose()).
`length`

  Lee hasta la longitud `length` - 1 byte desde el puntero de archivo `stream`, o bien el final del archivo, o una nueva línea (que es incluida en el valor devuelto), o un EOF (el que llegue primero). Si no se proporciona longitud, la función leerá el flujo hasta el final de la línea.

### Valores devueltos

Devuelve un string que contiene los `length` primeros caracteres, menos 1 byte desde el puntero de archivo `stream`. `false` es devuelto si no hay más datos para leer.

Si ocurre un error, la función devuelve `false`.

### Ejemplos

Ejemplo #1 Lectura de un archivo línea por línea

    <?php

    $fp = @fopen("/tmp/inputfile.txt", "r");

    if ($fp) {
        while (($buffer = fgets($fp, 4096)) !== false) {
            echo $buffer, PHP_EOL;
        }
        if (!feof($fp)) {
            echo "Error: fgets() falló\n";
        }

        fclose($fp);
    }

    ?>

### Notas

> Nota: Si PHP no reconoce correctamente los finales de línea al leer archivos que han sido creados o leídos en un Macintosh, la activación de la opción de configuración auto_detect_line_endings puede resolver el problema.

> Nota:

> Los programadores acostumbrados a la programación 'C' notarán que fgets() no se comporta como su equivalente en C al encontrar el final del archivo.

### Ver también

- fgetss() - Obtiene un línea desde un puntero a un archivo y elimina las etiquetas HTML
- fread() - Lectura del archivo en modo binario
- fgetc() - Lee un carácter en un fichero
- stream_get_line() - Lee una línea en un flujo
- fopen() - Abre un fichero o un URL
- popen() - Crea un puntero de archivo de proceso
- fsockopen() - Abre un socket de conexión Internet o Unix
- stream_set_timeout() - Configura el tiempo de espera de un flujo

# fgetss

(PHP 4, PHP 5, PHP 7)

fgetss — Obtiene un línea desde un puntero a un archivo y elimina las etiquetas HTML

Advertencia

Esta función está OBSOLETA a partir de PHP 7.3.0, y ha sido ELIMINADA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

function fgetss(resource `$handle`, int `$length` = ?, string `$allowable_tags` = ?): string

Idéntica a fgets(), excepto que fgetss() intenta eliminar cualesquiera bytes NULL, etiquetas HTML y PHP del texto que lee.

### Parámetros

`handle`
  El puntero de archivo debe ser válido y apuntar a un archivo abierto con éxito por fopen() o fsockopen() (y no cerrado aún por fclose()).
`length`

  Longitud de la información que va a ser recuperada.

`allowable_tags`

  Puede usar el tercer parámetro opcional para especificar las etiquetas que no deberían ser eliminadas. Consulte strip_tags() para obtener más información sobre `allowable_tags`.

### Valores devueltos

Devuelve una cadena de hasta `length` - 1 bytes leídos desde el archivo apuntado por `handle`, con todo el código HTML y PHP eliminado.

Si se produjo un error devuelve `false`.

### Ejemplos

Ejemplo #1 Leer un archivo PHP línea a línea

    <?php
    $cadena = <<<EOD
    <html><body>
     <p>¡Bienvenido! Hoy es el <?php echo(date('jS')); ?> de <?= date('F'); ?>.</p>
    </body></html>
    Texto fuera del bloque HTML.
    EOD;
    file_put_contents('ejemplo.php', $cadena);

    $gestor = @fopen("ejemplo.php", "r");
    if ($gestor) {
        while (!feof($gestor)) {
            $buffer = fgetss($gestor, 4096);
            echo $buffer;
        }
        fclose($gestor);
    }
    ?>

Resultado del ejemplo anterior es similar a:

    ¡Bienvenido! Hoy es el  de .

    Texto fuera del bloque HTML.

### Notas

> Nota: Si PHP no reconoce correctamente los finales de línea al leer archivos que han sido creados o leídos en un Macintosh, la activación de la opción de configuración auto_detect_line_endings puede resolver el problema.

### Ver también

- fgets() - Recupera la línea actual a partir de la posición del puntero de archivo
- fopen() - Abre un fichero o un URL
- popen() - Crea un puntero de archivo de proceso
- fsockopen() - Abre un socket de conexión Internet o Unix
- strip_tags() - Elimina las etiquetas HTML y PHP de un string

# file

(PHP 4, PHP 5, PHP 7, PHP 8)

file — Lee el fichero y devuelve el resultado en un array

### Descripción

function file(string `$filename`, int `$flags` = 0, ?resource `$context` = `null`): array|false

Lee el fichero y devuelve el resultado en un array.

> Nota:

> Puede utilizarse la función file_get_contents() para devolver el contenido de un fichero en un string.

### Parámetros

`filename`

  Ruta de acceso al fichero.

  Sugerencia

  Puede utilizar una URL como nombre de archivo con esta función, si el gestor fopen ha sido activado. Véase fopen() para más detalles sobre cómo especificar el nombre del archivo. Consulte Protocolos y Envolturas soportados para más información sobre las capacidades de los diferentes gestores, las notas sobre su uso, así como la información sobre las variables predefinidas que proporcionan.

`flags`

  El argumento opcional `flags` puede ser una o más de las siguientes constantes:

  `FILE_USE_INCLUDE_PATH`
    Busca el fichero en el include_path.
  `FILE_IGNORE_NEW_LINES`
    No añade nueva línea al final de cada elemento del array.
  `FILE_SKIP_EMPTY_LINES`
    Ignora las líneas vacías.
  `FILE_NO_DEFAULT_CONTEXT`
    No utiliza el contexto por omisión.
`context`
  Un resource de contexto de flujo.

### Valores devueltos

Devuelve el fichero en un array. Cada elemento del array corresponde a una línea del fichero, y los retornos de carro se colocan al final de la línea. Si ocurre un error, file() devolverá `false`.

> Nota:

> Cada línea del array resultante incluirá un final de línea, a menos que se utilice `FILE_IGNORE_NEW_LINES`.

> Nota: Si PHP no reconoce correctamente los finales de línea al leer archivos que han sido creados o leídos en un Macintosh, la activación de la opción de configuración auto_detect_line_endings puede resolver el problema.

### Errores/Excepciones

A partir de PHP 8.3.0, se lanza una excepción ValueError si el `flags` contiene valores inválidos, como `FILE_APPEND`.

Emite un error de nivel `E_WARNING` si el fichero no existe.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Se lanza una excepción ValueError para cualquier valor inválido del `flags`.

### Ejemplos

Ejemplo #1 Ejemplo con file()

    <?php
    // Lee una página web en un array.
    $lines = file('http://www.example.com/');

    // Muestra todas las líneas del array como código HTML, con los números de línea
    foreach ($lines as $line_num => $line) {
        echo "Line #<b>{$line_num}</b> : " . htmlspecialchars($line) . "<br />\n";
    }

    // Uso de flag
    $trimmed = file('somefile.txt', FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
    ?>

### Notas

Advertencia

Cuando SSL es utilizado, el servidor IIS de Microsoft violará el protocolo al cerrar la conexión sin enviar un indicador `close_notify`. PHP lo reportará como "SSL: Fatal Protocol Error" cuando se llegue al final de los datos. Para evitar esto, el nivel de la directiva error_reporting debe ser bajado para no incluir los avisos. PHP puede detectar automáticamente los servidores IIS defectuosos al abrir el flujo utilizando `https://` y suprimirá el aviso. Al utilizar fsockopen() para crear un socket `ssl://`, es responsabilidad del desarrollador detectar y suprimir el aviso.

### Ver también

- file_get_contents() - Lee todo un fichero en una cadena
- readfile() - Muestra un fichero
- fopen() - Abre un fichero o un URL
- fsockopen() - Abre un socket de conexión Internet o Unix
- popen() - Crea un puntero de archivo de proceso
- include - include
- stream_context_create() - Crea un contexto de flujo

# file_exists

(PHP 4, PHP 5, PHP 7, PHP 8)

file_exists — Verifica si un fichero o un directorio existe

### Descripción

function file_exists(string `$filename`): bool

Verifica si un fichero o un directorio existe.

### Parámetros

`filename`

  Ruta de acceso al fichero o directorio.

  En Windows, utilice el formato de ruta //computername/share/filename o \\\\computername\share\filename para verificar que un fichero está disponible en el recurso compartido.

### Valores devueltos

Devuelve `true` si el fichero o directorio especificado por el argumento `filename` existe; `false` en caso contrario.

> Nota:

> Devuelve `false` para los enlaces simbólicos que apuntan a un fichero que no existe.

> Nota:

> La verificación se realiza utilizando el UID/GID real en lugar del efectivo.

> Nota: Como el tipo entero de PHP es firmado y que muchas plataformas utilizan enteros de 32 bits, algunas funciones relacionadas con el sistema de archivos pueden retornar resultados extraños para archivos de tamaño superior a 2 Go.

### Errores/Excepciones

En caso de fallo, se emitirá una advertencia de tipo `E_WARNING`.

### Ejemplos

Ejemplo #1 Prueba la existencia de un fichero

    <?php
    $filename = '/path/to/foo.txt';

    if (file_exists($filename)) {
        echo "El fichero $filename existe.";
    } else {
        echo "El fichero $filename no existe.";
    }
    ?>

### Notas

> Nota: Los resultados de esta función se almacenan en caché. Véase la función clearstatcache() para más detalles.

Sugerencia

A partir de PHP 5.0.0, esta función también puede ser utilizada con algunos protocolos url. Lea Protocolos y Envolturas soportados para conocer los protocolos que soportan la familia de funcionalidades de stat().

### Ver también

- is_readable() - Indica si un fichero existe y es accesible en lectura
- is_writable() - Indica si un fichero es accesible en escritura
- is_file() - Indica si el fichero es un fichero verdadero
- file() - Lee el fichero y devuelve el resultado en un array
- SplFileInfo

# file_get_contents

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

file_get_contents — Lee todo un fichero en una cadena

### Descripción

function file_get_contents(
string `$filename`,
bool `$use_include_path` = `false`,
?resource `$context` = `null`,
int `$offset` = 0,
?int `$length` = `null`
): string|false

Similar a la función file(), excepto que file_get_contents() devuelve el fichero `filename` en una cadena, comenzando desde la posición `offset` y hasta `length` bytes. En caso de error, file_get_contents() devuelve `false`.

file_get_contents() es el método recomendado para leer el contenido de un fichero en una string. Utilizará un buffer en memoria si este mecanismo es soportado por el sistema, con el fin de mejorar el rendimiento.

> Nota:

> Si se abre una URI con caracteres especiales, como espacios, es necesario codificar esta URI con la función urlencode().

### Parámetros

`filename`

  Nombre del fichero a leer.

`use_include_path`

  > Nota:

  > La constante `FILE_USE_INCLUDE_PATH` puede ser utilizada para activar la búsqueda en el ruta de inclusión. Esto no es posible si strict typing está activado, ya que `FILE_USE_INCLUDE_PATH` es un int. Utilice `true` en su lugar.

`context`

  Un recurso de contexto válido, creado con la función stream_context_create(). Si no es necesario utilizar un contexto específico, este parámetro puede ser omitido asignándole el valor `null`.

`offset`

  La posición desde la cual se comienza a leer en el flujo original. Una posición negativa cuenta desde el final del flujo.

  El desplazamiento en el fichero (`offset`) no es soportado en ficheros remotos. Si se intenta desplazarse en un fichero que no es local puede funcionar en pequeños desplazamientos, pero el comportamiento puede no ser el esperado ya que el proceso utiliza el flujo del buffer.

`length`

  El tamaño máximo de datos a leer. El comportamiento por defecto es leer hasta el final del fichero. Este parámetro se aplica al flujo procesado por los filtros.

### Valores devueltos

Devuelve los datos leídos o `false` si ocurre un error.

Advertencia

Esta función puede retornar `false`, pero también puede retornar un valor equivalente a `false`. Por favor, lea la sección sobre los booleanos para más información. Utilice el operador === para probar el valor de retorno exacto de esta función.

### Errores/Excepciones

Genera una advertencia de tipo `E_WARNING` si, `filename` no puede ser encontrado, si el parámetro `length` es menor que cero, o si el desplazamiento a la posición `offset` especificado en el flujo falla.

Cuando file_get_contents() es llamado sobre un directorio, se genera un error de nivel `E_WARNING` en Windows, y a partir de PHP 7.4 en otros sistemas operativos también.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `length` ahora es nullable.
7.1.0 | Se añade soporte para posiciones `offset` negativas.

### Ejemplos

Ejemplo #1 Lee y muestra el código HTML de un sitio web

    <?php
    $homepage = file_get_contents('http://www.example.com/');
    echo $homepage;
    ?>

Ejemplo #2 Busca un fichero en el include_path

    <?php
    // Si el tipado estricto está activado c.à.d. declare(strict_types=1);
    $file = file_get_contents('./people.txt', true);
    // De lo contrario
    $file = file_get_contents('./people.txt', FILE_USE_INCLUDE_PATH);
    ?>

Ejemplo #3 Lee una sección de un fichero

    <?php
    // Lee 14 caracteres a partir del 21º carácter
    $section = file_get_contents('./people.txt', FALSE, NULL, 20, 14);
    var_dump($section);
    ?>

Resultado del ejemplo anterior es similar a:

    string(14) "lle Bjori Ro"

Ejemplo #4 Uso de contextos de flujo

    <?php
    // Creación de un flujo
    $opts = [
      'http'=> [
        'method'=>"GET",
        'header'=>"Accept-language: en\r\n" .
                  "Cookie: foo=bar\r\n",
      ]
    ];

    $context = stream_context_create($opts);

    // Acceso a un fichero HTTP con los encabezados HTTP indicados arriba
    $file = file_get_contents('http://www.example.com/', false, $context);
    ?>

### Notas

> Nota: Esta función es segura para sistemas binarios.

Sugerencia

Puede utilizar una URL como nombre de archivo con esta función, si el gestor fopen ha sido activado. Véase fopen() para más detalles sobre cómo especificar el nombre del archivo. Consulte Protocolos y Envolturas soportados para más información sobre las capacidades de los diferentes gestores, las notas sobre su uso, así como la información sobre las variables predefinidas que proporcionan.

Advertencia

Cuando SSL es utilizado, el servidor IIS de Microsoft violará el protocolo al cerrar la conexión sin enviar un indicador `close_notify`. PHP lo reportará como "SSL: Fatal Protocol Error" cuando se llegue al final de los datos. Para evitar esto, el nivel de la directiva error_reporting debe ser bajado para no incluir los avisos. PHP puede detectar automáticamente los servidores IIS defectuosos al abrir el flujo utilizando `https://` y suprimirá el aviso. Al utilizar fsockopen() para crear un socket `ssl://`, es responsabilidad del desarrollador detectar y suprimir el aviso.

### Ver también

- file() - Lee el fichero y devuelve el resultado en un array
- fgets() - Recupera la línea actual a partir de la posición del puntero de archivo
- fread() - Lectura del archivo en modo binario
- readfile() - Muestra un fichero
- file_put_contents() - Escribe datos en un fichero
- stream_get_contents() - Lee todo un flujo en un string
- stream_context_create() - Crea un contexto de flujo
- $http_response_header

# file_put_contents

(PHP 5, PHP 7, PHP 8)

file_put_contents — Escribe datos en un fichero

### Descripción

function file_put_contents(
string `$filename`,
mixed `$data`,
int `$flags` = 0,
?resource `$context` = `null`
): int|false

Equivale a llamar a las funciones fopen(), fwrite() y fclose() sucesivamente.

Si el fichero `filename` no existe, será creado. De lo contrario, el fichero existente será sobrescrito, a menos que la opción `FILE_APPEND` esté definida.

### Parámetros

`filename`

  Ruta de acceso al fichero en el que se deben escribir los datos.

`data`

  Los datos a escribir. Puede ser un string, un array o un recurso de flujo (explicación más abajo).

  Si `data` es un recurso de tipo stream, el buffer restante de este flujo será copiado al fichero especificado. Esto equivale a utilizar la función stream_copy_to_stream().

  Asimismo, puede especificarse el argumento `data` como un array de una sola dimensión. Esto equivale a `file_put_contents($filename, implode('', $array))`.

`flags`

  El valor del argumento `flags` puede ser cualquier combinación de los siguientes flags, unidos por el operador OR binario (`|`).

  Flags disponibles
  Flag | Descripción
  --- | ---
  `FILE_USE_INCLUDE_PATH` | Busca el fichero `filename` en el directorio de inclusión. Ver include_path para más información.
  `FILE_APPEND` | Si el fichero `filename` ya existe, esta opción permite añadir los datos al fichero en lugar de sobrescribirlo.
  `LOCK_EX` | Adquiere un bloqueo exclusivo sobre el fichero durante la operación de escritura. En otras palabras, se realiza una llamada a la función flock() entre la llamada a la función fopen() y la llamada a la función fwrite(). Este comportamiento no es idéntico a una llamada a la función fopen() con el modo "x".

`context`

  Un recurso de contexto válido creado con la función stream_context_create().

### Valores devueltos

Devuelve el número de bytes que han sido escritos al fichero, o `false` si ocurre un error.

Advertencia

Esta función puede retornar `false`, pero también puede retornar un valor equivalente a `false`. Por favor, lea la sección sobre los booleanos para más información. Utilice el operador === para probar el valor de retorno exacto de esta función.

### Ejemplos

Ejemplo #1 Uso simple de file_put_contents

    <?php
    $file = 'people.txt';
    // Abre un fichero para leer un contenido existente
    $current = file_get_contents($file);
    // Añade una persona
    $current .= "Jean Dupond\n";
    // Escribe el resultado en el fichero
    file_put_contents($file, $current);
    ?>

Ejemplo #2 Uso de opciones para file_put_contents

    <?php
    $file = 'people.txt';
    // Una nueva persona a añadir
    $person = "Jean Dupond\n";
    // Escribe el contenido en el fichero, utilizando el flag
    // FILE_APPEND para añadir al final del fichero y
    // LOCK_EX para evitar que otros escriban en el fichero
    // al mismo tiempo
    file_put_contents($file, $person, FILE_APPEND | LOCK_EX);
    ?>

### Notas

> Nota: Esta función es segura para sistemas binarios.

Sugerencia

Puede utilizar una URL como nombre de archivo con esta función, si el gestor fopen ha sido activado. Véase fopen() para más detalles sobre cómo especificar el nombre del archivo. Consulte Protocolos y Envolturas soportados para más información sobre las capacidades de los diferentes gestores, las notas sobre su uso, así como la información sobre las variables predefinidas que proporcionan.

### Ver también

- fopen() - Abre un fichero o un URL
- fwrite() - Escribe en un fichero en modo binario
- file_get_contents() - Lee todo un fichero en una cadena
- stream_context_create() - Crea un contexto de flujo

# fileatime

(PHP 4, PHP 5, PHP 7, PHP 8)

fileatime — Devuelve la fecha en la que el fichero fue accedido por última vez

### Descripción

function fileatime(string `$filename`): int|false

Devuelve la fecha en la que el fichero fue accedido por última vez.

### Parámetros

`filename`

  Ruta hacia el fichero.

### Valores devueltos

Devuelve la fecha en la que el fichero fue accedido por última vez o `false` si ocurre un error. La fecha se devuelve en formato timestamp Unix.

### Errores/Excepciones

En caso de fallo, se emitirá una advertencia de tipo `E_WARNING`.

### Ejemplos

Ejemplo #1 Ejemplo con fileatime()

    <?php

    // Muestra: somefile.txt fue accedido el: December 29 2002 22:16:23.

    $filename = 'somefile.txt';
    if (file_exists($filename)) {
        echo "$filename fue accedido el: " . date("F d Y H:i:s.", fileatime($filename));
    }

    ?>

### Notas

> Nota:

> La fecha de última modificación de un fichero se supone que cambia cada vez que los bloques de datos del fichero comienzan a ser leídos. Esto puede ser muy costoso en términos de rendimiento cuando una aplicación accede regularmente a muchos ficheros o directorios.

> La mayoría de los sistemas de archivos Unix pueden ser montados con esta información desactivada para aumentar el rendimiento de una aplicación de este tipo; los nuevos `USENET` son un buen ejemplo. En tales sistemas de archivos, esta función se vuelve totalmente inútil.

> Nota: Tenga en cuenta que la precisión temporal puede variar según el sistema de archivos utilizado.

> Nota: Los resultados de esta función se almacenan en caché. Véase la función clearstatcache() para más detalles.

Sugerencia

A partir de PHP 5.0.0, esta función también puede ser utilizada con algunos protocolos url. Lea Protocolos y Envolturas soportados para conocer los protocolos que soportan la familia de funcionalidades de stat().

### Ver también

- filemtime() - Lee la fecha de última modificación del fichero
- fileinode() - Lee el número de inodo del fichero
- date() - Da formato a una marca de tiempo de Unix (Unix timestamp)

# filectime

(PHP 4, PHP 5, PHP 7, PHP 8)

filectime — Devuelve la fecha de última modificación del inodo de un fichero

### Descripción

function filectime(string `$filename`): int|false

Devuelve la fecha de última modificación del inodo de un fichero.

### Parámetros

`filename`

  Ruta de acceso al fichero.

### Valores devueltos

Devuelve la fecha en la que el inodo fue modificado por última vez o `false` si ocurre un error. La hora se devuelve en formato timestamp Unix.

### Errores/Excepciones

En caso de fallo, se emitirá una advertencia de tipo `E_WARNING`.

### Ejemplos

Ejemplo #1 Ejemplo con filectime()

    <?php

    // Muestra: somefile.txt fue modificado el: December 29 2002 22:16:23.

    $filename = 'somefile.txt';
    if (file_exists($filename)) {
        echo "$filename fue modificado el: " . date("F d Y H:i:s.", filectime($filename));
    }

    ?>

### Notas

> Nota:

> En la mayoría de servidores UNIX, un fichero se considera modificado si los datos de su inodo son modificados. Es decir, cuando los permisos (de usuario, grupo u otros) han sido modificados. Véase también filemtime() (que puede ser utilizado cuando se creen indicaciones como "Última modificación: " en las páginas web) y fileatime().

> Nota:

> Tenga en cuenta que en algunos sistemas UNIX, el `ctime` de un fichero de texto es considerado como su fecha de creación. ¡Esto es falso! No existe una fecha de creación de fichero en la mayoría de los sistemas UNIX.

> Nota: Tenga en cuenta que la precisión temporal puede variar según el sistema de archivos utilizado.

> Nota: Los resultados de esta función se almacenan en caché. Véase la función clearstatcache() para más detalles.

Sugerencia

A partir de PHP 5.0.0, esta función también puede ser utilizada con algunos protocolos url. Lea Protocolos y Envolturas soportados para conocer los protocolos que soportan la familia de funcionalidades de stat().

### Ver también

- filemtime() - Lee la fecha de última modificación del fichero

# filegroup

(PHP 4, PHP 5, PHP 7, PHP 8)

filegroup — Leer el nombre del grupo

### Descripción

function filegroup(string `$filename`): int|false

Lee el nombre del grupo. El identificador de grupo se devuelve en formato numérico, utilice posix_getgrgid() para recuperar el nombre del grupo.

### Parámetros

`filename`

  Ruta de acceso al fichero.

### Valores devueltos

Devuelve el grupo que posee el fichero `filename`, o `false` si ocurre un error. El identificador de grupo se devuelve en formato numérico, utilice posix_getgrgid() para recuperar el nombre del grupo. En caso de error, se devuelve `false`.

### Errores/Excepciones

Si ocurre un error, se emitirá una advertencia de tipo `E_WARNING`.

### Ejemplos

Ejemplo #1 Buscar el grupo de un fichero

    <?php
    $filename = 'index.php';
    print_r(posix_getgrgid(filegroup($filename)));
    ?>

### Notas

> Nota: Los resultados de esta función se almacenan en caché. Véase la función clearstatcache() para más detalles.

Sugerencia

A partir de PHP 5.0.0, esta función también puede ser utilizada con algunos protocolos url. Lea Protocolos y Envolturas soportados para conocer los protocolos que soportan la familia de funcionalidades de stat().

### Ver también

- fileowner() - Lee el identificador del propietario de un fichero
- posix_getgrgid() - Devolver información sobre un grupo mediante un id de grupo

# fileinode

(PHP 4, PHP 5, PHP 7, PHP 8)

fileinode — Lee el número de inodo del fichero

### Descripción

function fileinode(string `$filename`): int|false

Lee el número de inodo del fichero.

### Parámetros

`filename`

  Ruta de acceso al fichero.

### Valores devueltos

Devuelve el número de inodo del fichero, o `false` si ocurre un error.

### Errores/Excepciones

En caso de fallo, se emitirá una advertencia de tipo `E_WARNING`.

### Ejemplos

Ejemplo #1 Comparación del inodo de un fichero con el fichero actual

    <?php
    $filename = 'index.php';
    if (getmyinode() == fileinode($filename)) {
        echo 'Se verifica el fichero actual.';
    }
    ?>

### Notas

> Nota: Los resultados de esta función se almacenan en caché. Véase la función clearstatcache() para más detalles.

Sugerencia

A partir de PHP 5.0.0, esta función también puede ser utilizada con algunos protocolos url. Lea Protocolos y Envolturas soportados para conocer los protocolos que soportan la familia de funcionalidades de stat().

### Ver también

- getmyinode() - Devuelve el inodo del script
- stat() - Proporciona información sobre un fichero

# filemtime

(PHP 4, PHP 5, PHP 7, PHP 8)

filemtime — Lee la fecha de última modificación del fichero

### Descripción

function filemtime(string `$filename`): int|false

Lee la fecha en la que el fichero fue modificado por última vez.

### Parámetros

`filename`

  Ruta de acceso al fichero.

### Valores devueltos

Devuelve el timestamp Unix de última modificación del fichero `filename` o `false` si ocurre un error. Utilice date() sobre este resultado para obtener una fecha de modificación legible por humanos.

### Errores/Excepciones

En caso de fallo, se emitirá una advertencia de tipo `E_WARNING`.

### Ejemplos

Ejemplo #1 Ejemplo con filemtime()

    <?php
    // Mostrará: somefile.txt fue modificado el: December 29 2002 22:16:23.

    $filename = 'somefile.txt';
    if (file_exists($filename)) {
        echo "$filename fue modificado el: " . date ("F d Y H:i:s.", filemtime($filename));
    }
    ?>

### Notas

> Nota: Tenga en cuenta que la precisión temporal puede variar según el sistema de archivos utilizado.

> Nota: Los resultados de esta función se almacenan en caché. Véase la función clearstatcache() para más detalles.

Sugerencia

A partir de PHP 5.0.0, esta función también puede ser utilizada con algunos protocolos url. Lea Protocolos y Envolturas soportados para conocer los protocolos que soportan la familia de funcionalidades de stat().

### Ver también

- filectime() - Devuelve la fecha de última modificación del inodo de un fichero
- stat() - Proporciona información sobre un fichero
- touch() - Modifica la fecha de modificación y de último acceso de un fichero
- getlastmod() - Devuelve la fecha de última modificación de la página

# fileowner

(PHP 4, PHP 5, PHP 7, PHP 8)

fileowner — Lee el identificador del propietario de un fichero

### Descripción

function fileowner(string `$filename`): int|false

Lee el identificador del propietario de un fichero.

### Parámetros

`filename`

  Ruta de acceso al fichero.

### Valores devueltos

Devuelve el identificador del propietario del fichero `filename`, o `false` si ocurre un error. El identificador del propietario es numérico: es necesario utilizar posix_getpwuid() para obtener el nombre de usuario.

### Errores/Excepciones

En caso de fallo, se emitirá una advertencia de tipo `E_WARNING`.

### Ejemplos

Ejemplo #1 Búsqueda del propietario de un fichero

    <?php
    $filename = 'index.php';
    print_r(posix_getpwuid(fileowner($filename)));
    ?>

### Notas

> Nota: Los resultados de esta función se almacenan en caché. Véase la función clearstatcache() para más detalles.

Sugerencia

A partir de PHP 5.0.0, esta función también puede ser utilizada con algunos protocolos url. Lea Protocolos y Envolturas soportados para conocer los protocolos que soportan la familia de funcionalidades de stat().

### Ver también

- filegroup() - Leer el nombre del grupo
- stat() - Proporciona información sobre un fichero
- posix_getpwuid() - Devolver información sobre un usuario mediante su id de usuario

# fileperms

(PHP 4, PHP 5, PHP 7, PHP 8)

fileperms — Lee los permisos de un fichero

### Descripción

function fileperms(string `$filename`): int|false

Lee los permisos del fichero dado.

### Parámetros

`filename`

  Ruta de acceso al fichero.

### Valores devueltos

Devuelve los permisos del fichero en formato numérico. Los bits de menor peso son los mismos que los de los permisos en chmod(), sin embargo algunas plataformas incluyen en el retorno información sobre el tipo de fichero dado en `filename`. Los ejemplos siguientes muestran cómo probar el valor de retorno en cuanto a los permisos y el tipo de fichero en sistemas POSIX como Linux o macOS.

Para ficheros locales, se utiliza el valor específico `st_mode` de la estructura C devuelta por la función stat(). Los bits afectados pueden cambiar según la plataforma y se debe investigar al respecto si se deben analizar los bits que no concernen a la permisión.

Devuelve `false` en caso de error.

### Errores/Excepciones

En caso de fallo, se emitirá una advertencia de tipo `E_WARNING`.

### Ejemplos

Ejemplo #1 Mostrar los permisos en valor octal

    <?php
    echo substr(sprintf('%o', fileperms('/tmp')), -4);
    echo substr(sprintf('%o', fileperms('/etc/passwd')), -4);
    ?>

El ejemplo anterior mostrará:

    1777
    0644

Ejemplo #2 Mostrar todos los permisos

    <?php
    $perms = fileperms('/etc/passwd');

    switch ($perms & 0xF000) {
        case 0xC000: // Socket
            $info = 's';
            break;
        case 0xA000: // Enlace simbólico
            $info = 'l';
            break;
        case 0x8000: // Regular
            $info = 'r';
            break;
        case 0x6000: // Especial de bloque
            $info = 'b';
            break;
        case 0x4000: // Directorio
            $info = 'd';
            break;
        case 0x2000: // Especial de carácter
            $info = 'c';
            break;
        case 0x1000: // Pipe FIFO
            $info = 'p';
            break;
        default: // Desconocido
            $info = 'u';
    }

    // Propietario
    $info .= (($perms & 0x0100) ? 'r' : '-');
    $info .= (($perms & 0x0080) ? 'w' : '-');
    $info .= (($perms & 0x0040) ?
                (($perms & 0x0800) ? 's' : 'x' ) :
                (($perms & 0x0800) ? 'S' : '-'));

    // Grupo
    $info .= (($perms & 0x0020) ? 'r' : '-');
    $info .= (($perms & 0x0010) ? 'w' : '-');
    $info .= (($perms & 0x0008) ?
                (($perms & 0x0400) ? 's' : 'x' ) :
                (($perms & 0x0400) ? 'S' : '-'));

    // Todos
    $info .= (($perms & 0x0004) ? 'r' : '-');
    $info .= (($perms & 0x0002) ? 'w' : '-');
    $info .= (($perms & 0x0001) ?
                (($perms & 0x0200) ? 't' : 'x' ) :
                (($perms & 0x0200) ? 'T' : '-'));

    echo $info;
    ?>

El ejemplo anterior mostrará:

    -rw-r--r--

### Notas

> Nota: Los resultados de esta función se almacenan en caché. Véase la función clearstatcache() para más detalles.

Sugerencia

A partir de PHP 5.0.0, esta función también puede ser utilizada con algunos protocolos url. Lea Protocolos y Envolturas soportados para conocer los protocolos que soportan la familia de funcionalidades de stat().

### Ver también

- chmod() - Cambia el modo del fichero
- is_readable() - Indica si un fichero existe y es accesible en lectura
- stat() - Proporciona información sobre un fichero

# filesize

(PHP 4, PHP 5, PHP 7, PHP 8)

filesize — Obtiene el tamaño de un fichero

### Descripción

function filesize(string `$filename`): int|false

Obtiene el tamaño del fichero especificado.

### Parámetros

`filename`

  Ruta de acceso al fichero.

### Valores devueltos

Devuelve el tamaño del fichero `filename` en bytes, o `false` (y genera un error de nivel `E_WARNING`) en caso de error.

> Nota: Como el tipo entero de PHP es firmado y que muchas plataformas utilizan enteros de 32 bits, algunas funciones relacionadas con el sistema de archivos pueden retornar resultados extraños para archivos de tamaño superior a 2 Go.

### Errores/Excepciones

En caso de fallo, se emitirá una advertencia de tipo `E_WARNING`.

### Ejemplos

Ejemplo #1 Ejemplo con filesize()

    <?php

    // Muestra por ejemplo:  somefile.txt: 1024 bytes

    $filename = 'somefile.txt';
    echo $filename . ': ' . filesize($filename) . ' bytes';

    ?>

### Notas

> Nota: Los resultados de esta función se almacenan en caché. Véase la función clearstatcache() para más detalles.

Sugerencia

A partir de PHP 5.0.0, esta función también puede ser utilizada con algunos protocolos url. Lea Protocolos y Envolturas soportados para conocer los protocolos que soportan la familia de funcionalidades de stat().

### Ver también

- file_exists() - Verifica si un fichero o un directorio existe

# filetype

(PHP 4, PHP 5, PHP 7, PHP 8)

filetype — Devuelve el tipo de fichero

### Descripción

function filetype(string `$filename`): string|false

Devuelve el tipo de un fichero dado.

### Parámetros

`filename`

  Ruta de acceso al fichero.

### Valores devueltos

Devuelve el tipo del fichero. Las respuestas posibles son : `fifo`, `char`, `dir`, `block`, `link`, `file` `socket` y `unknown`.

Devuelve `false` en caso de error. filetype() también emite un error `E_NOTICE` si el llamado a stat falla, o si el tipo de fichero es desconocido.

### Errores/Excepciones

En caso de fallo, se emitirá una advertencia de tipo `E_WARNING`.

### Ejemplos

Ejemplo #1 Ejemplo con filetype()

    <?php

    echo filetype('/etc/passwd');
    echo "\n";
    echo filetype('/etc/');
    ?>

El ejemplo anterior mostrará:

    file
    dir

### Notas

> Nota: Los resultados de esta función se almacenan en caché. Véase la función clearstatcache() para más detalles.

Sugerencia

A partir de PHP 5.0.0, esta función también puede ser utilizada con algunos protocolos url. Lea Protocolos y Envolturas soportados para conocer los protocolos que soportan la familia de funcionalidades de stat().

### Ver también

- is_dir() - Indica si el fichero es un directorio
- is_file() - Indica si el fichero es un fichero verdadero
- is_link() - Indica si el fichero es un enlace simbólico
- file_exists() - Verifica si un fichero o un directorio existe
- mime_content_type() - Detecta el tipo de contenido de un fichero
- pathinfo() - Devuelve información sobre una ruta del sistema
- stat() - Proporciona información sobre un fichero

# flock

(PHP 4, PHP 5, PHP 7, PHP 8)

flock — Bloqueo de ficheros portátil y consultivo

### Descripción

function flock(resource `$stream`, int `$operation`, int `&$would_block` = `null`): bool

flock() permite realizar un modelo simple de lectura/escritura que puede usarse en casi cualquier plataforma (incluyendo la mayoría de derivados de Unix e incluso Windows).

El bloqueo también se libera mediante fclose(), o cuando el `stream` es recolectado por el recolector de basura.

PHP soporta una forma portátil de bloquear ficheros completos de manera consultiva (lo que significa que todos los programas que acceden deben usar el mismo método de bloqueo o no funcionará). Por omisión, esta función bloqueará hasta que se adquiera el bloqueo solicitado; esto puede controlarse con la opción `LOCK_NB` documentada más abajo.

### Parámetros

`stream`
  Un puntero del sistema de archivos de tipo resource que es habitualmente creado utilizando la función fopen().
`operation`

  `operation` es uno de los siguientes:

  - `LOCK_SH` para adquirir un bloqueo compartido (lector).
  - `LOCK_EX` para adquirir un bloqueo exclusivo (escritor).
  - `LOCK_UN` para liberar un bloqueo (compartido o exclusivo).

  También es posible añadir `LOCK_NB` como máscara de bits a una de las operaciones anteriores, si flock() no debe bloquear durante el intento de bloqueo.

`would_block`

  El tercer argumento opcional se establece a 1 si el bloqueo bloquearía (condición de error EWOULDBLOCK).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de flock()

    <?php

    $fp = fopen("/tmp/lock.txt", "r+");

    if (flock($fp, LOCK_EX)) {  // adquirir un bloqueo exclusivo
        ftruncate($fp, 0);      // truncar el fichero
        rewind($fp);
        fwrite($fp, "Escribir algo aquí\n");
        fflush($fp);            // volcar la salida antes de liberar el bloqueo
        flock($fp, LOCK_UN);    // liberar el bloqueo
    } else {
        echo "¡No se pudo obtener el bloqueo!";
    }

    fclose($fp);

    ?>

Ejemplo #2 flock() usando la opción `LOCK_NB`

    <?php
    $fp = fopen('/tmp/lock.txt', 'r+');

    /* Activar la opción LOCK_NB en una operación LOCK_EX */
    if(!flock($fp, LOCK_EX | LOCK_NB)) {
        echo 'No se pudo obtener el bloqueo';
        exit(-1);
    }

    /* ... */

    fclose($fp);
    ?>

### Notas

> Nota:

> flock() usa bloqueo obligatorio en lugar de bloqueo consultivo en Windows. El bloqueo obligatorio también es compatible en Linux y sistemas operativos basados en System V mediante el mecanismo habitual soportado por la llamada al sistema fcntl(): es decir, si el fichero en cuestión tiene establecido el bit de permiso setgid y el bit de ejecución del grupo desactivado. En Linux, el sistema de ficheros también deberá montarse con la opción mand para que esto funcione.

> Nota:

> Dado que flock() requiere un puntero a fichero, puede que necesite usar un fichero de bloqueo especial para proteger el acceso a un fichero que intente truncar abriéndolo en modo escritura (con un argumento "w" o "w+" a fopen()).

> Nota:

> Solo puede usarse en punteros a ficheros devueltos por fopen() para ficheros locales, o punteros a ficheros que apunten a flujos en espacio de usuario que implementen el método streamWrapper::stream_lock().

Advertencia

Asignar otro valor al argumento `stream` en el código posterior liberará el bloqueo.

Advertencia

En algunos sistemas operativos, flock() se implementa a nivel de proceso. ¡Cuando se usa una API de servidor multihilo, puede que no se pueda confiar en flock() para proteger ficheros contra otros scripts PHP que se ejecuten en paralelo en la misma instancia del servidor!

flock() no es compatible con sistemas de ficheros anticuados como `FAT` y sus derivados, y por lo tanto siempre devolverá `false` en estos entornos.

> Nota:

> En Windows, si el proceso de bloqueo abre el fichero una segunda vez, no podrá acceder al fichero a través de este segundo manejador hasta que desbloquee el fichero.

# fnmatch

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

fnmatch — Prueba un nombre de fichero mediante un patrón de búsqueda

### Descripción

function fnmatch(string `$pattern`, string `$filename`, int `$flags` = 0): bool

fnmatch() verifica si la cadena `filename` cumple con el patrón de shell `pattern`.

### Parámetros

`pattern`

  El `pattern` a comparar. Habitualmente, el `pattern` contendrá caracteres genéricos como `'?'` y `'*'`.

  Caracteres genéricos a utilizar en el parámetro `pattern`
  Carácter genérico | Descripción
  --- | ---
  `?` | El signo de interrogación coincidirá con cualquier carácter único. Por ejemplo, el patrón `"file?.txt"` coincidirá con `"file1.txt"` y `"fileA.txt"`, pero no coincidirá con `"file10.txt"`.
  `*` | El asterisco coincidirá con cero o más caracteres. Por ejemplo, el patrón `"foo*.xml"` coincidirá con `"foo.xml"` y `"foobar.xml"`.
  `[ ]` | Los corchetes se utilizan para crear rangos de puntos de código ASCII o conjuntos de caracteres. Por ejemplo, el patrón `"index.php[45]"` coincidirá con `"index.php4"` y `"index.php5"`, pero no coincidirá con `"index.phpt"`. Rangos conocidos son `[0-9]`, `[a-z]` y `[A-Z]`. Varios conjuntos y rangos pueden utilizarse simultáneamente, por ejemplo `[0-9a-zABC]`.
  `!` | El signo de exclamación se utiliza para negar caracteres dentro de los corchetes. Por ejemplo, `"[!A-Z]*.html"` coincidirá con `"demo.html"`, pero no coincidirá con `"Demo.html"`.
  `\` | La barra invertida se utiliza para escapar caracteres especiales. Por ejemplo, `"Name\?"` coincidirá con `"Name?"`, pero no coincidirá con `"Names"`.

`filename`

  La cadena a probar. Esta función es particularmente útil para los nombres de fichero, pero también puede utilizarse con cadenas regulares.

  El usuario medio de Shell puede estar familiarizado con los patrones de Shell, o al menos, sus expresiones más simples, como `'?'` y `'*'`. De esta manera, utilizar fnmatch() en lugar de preg_match() para búsquedas puede ser más práctico para los no iniciados.

`flags`

  El valor de `flags` puede ser una combinación de los siguientes flags, unidos con el operador binario OR (|).

  Lista de flags posibles para fnmatch()
  `Flag` | Descripción
  --- | ---
  `FNM_NOESCAPE` | Desactiva el escape de las barras invertidas.
  `FNM_PATHNAME` | Una barra diagonal en una cadena coincide únicamente con una barra diagonal en el patrón proporcionado.
  `FNM_PERIOD` | Un punto al inicio de la cadena debe coincidir exactamente con un punto en el patrón proporcionado.
  `FNM_CASEFOLD` | Las coincidencias no distinguen mayúsculas y minúsculas. Forma parte de la extensión GNU.

### Valores devueltos

Devuelve `true` si hay resultados, `false` en caso contrario.

### Ejemplos

Ejemplo #1 Verificar el nombre de un color con un patrón de Shell

    <?php
    if (fnmatch("*gr[ae]y", $color)) {
      echo "formas de gris ...";
    }
    ?>

### Notas

Advertencia

Actualmente, esta función no está disponible para sistemas no-POSIX, a excepción de Windows.

### Ver también

- glob() - Búsqueda de rutas que coinciden con un patrón
- preg_match() - Realiza una búsqueda de coincidencia con una expresión regular estándar
- sscanf() - Analiza una cadena utilizando un formato
- printf() - Muestra una string formateada
- sprintf() - Devuelve una string formateada

# fopen

(PHP 4, PHP 5, PHP 7, PHP 8)

fopen — Abre un fichero o un URL

### Descripción

function fopen(
string `$filename`,
string `$mode`,
bool `$use_include_path` = `false`,
?resource `$context` = `null`
): resource|false

fopen() asocia un recurso con nombre, especificado por `filename`, a un flujo.

### Parámetros

`filename`

  Si `filename` está en la forma "esquema://...", se asume que será un URL y PHP buscará un gestor de protocolos (también conocido como envoltura) para ese protocolo. Si no está registrada ninguna envoltura para ese protocolo, PHP emitirá un aviso para ayudar a rastrear problemas potenciales en el script y continuará como si `filename` especificara un fichero normal.

  Si PHP ha decidido que `filename` especifica un fichero local, intentará abrir un flujo para ese fichero. El fichero debe ser accesible para PHP, por lo que es necesario asegurarse de que los permisos de acceso del fichero permiten este acceso. Si está habilitado open_basedir se pueden aplicar más restricciones.

  Si PHP ha decidido que `filename` especifica un protocolo registrado, y ese protocolo está registrado como un URL de red, PHP se asegurará de que allow_url_fopen está habilitado. Si es desactivado, PHP emitirá un aviso y la llamada a fopen fallará.

  > Nota:

  > La lista de protocolos soportados se puede encontrar en Protocolos y Envolturas soportados. Algunos protocolos (también descritos como `envolturas`) soportan `contexto` y/u opciones de php.ini. Consulte la página específica del protocolo en uso para una lista de opciones que se pueden establecer. (p.ej. el valor `user_agent` en php.ini usado por la envoltura `http`).

  En la plataforma Windows, asegúrese de escapar cualquier barra invertida usada en la ruta de fichero, o use barras hacia delante.

      <?php
      $handle = fopen("c:\\folder\\resource.txt", "r");
      ?>

`mode`

  El parámetro `mode` especifica el tipo de acceso que se necesita para el flujo. Puede ser cualquiera de los siguientes:

  Una lista de los modos posibles de fopen() usando `mode`
  `mode` | Descripción
  --- | ---
  `'r'` | Apertura para sólo lectura; coloca el puntero al fichero al principio del fichero.
  `'r+'` | Apertura para lectura y escritura; coloca el puntero al fichero al principio del fichero.
  `'w'` | Apertura para sólo escritura; coloca el puntero al fichero al principio del fichero y trunca el fichero a longitud cero. Si el fichero no existe se intenta crear.
  `'w+'` | Abre para lectura y escritura; de otro modo, tiene el mismo comportamiento que `'w'`.
  `'a'` | Apertura para sólo escritura; coloca el puntero del fichero al final del mismo. Si el fichero no existe, se intenta crear. En este modo, fseek() no tiene efecto, escribe siempre agregando.
  `'a+'` | Apertura para lectura y escritura; coloca el puntero del fichero al final del mismo. Si el fichero no existe, se intenta crear. En este modo, fseek() solo afecta a la posición de lectura, escribe siempre agregando.
  `'x'` | Creación y apertura para sólo escritura; coloca el puntero del fichero al principio del mismo. Si el fichero ya existe, la llamada a fopen() fallará devolviendo `false` y generando un error de nivel `E_WARNING`. Si el fichero no existe se intenta crear. Esto es equivalente a especificar las flags `O_EXCL|O_CREAT` para la llamada al sistema de `open(2)` subyacente.
  `'x+'` | Creación y apertura para lectura y escritura; de otro modo tiene el mismo comportamiento que `'x'`.
  `'c'` | Abre el fichero para sólo escritura. Si el fichero no existe, se crea. Si existe no es truncado (a diferencia de `'w'`), ni la llamada a esta función falla (como en el caso con `'x'`). El puntero al fichero se posiciona en el principio del fichero. Esto puede ser útil si se desea obtener un bloqueo asistido (véase flock()) antes de intentar modificar el fichero, ya que al usar `'w'` se podría truncar el fichero antes de haber obtenido el bloqueo (si se desea truncar el fichero, se puede usar ftruncate() después de solicitar el bloqueo).
  `'c+'` | Abre el fichero para lectura y escritura; de otro modo tiene el mismo comportamiento que `'c'`.
  `'e'` | Establece el flag 'close-on-exec' en el descriptor de fichero abierto. Disponible solamente en PHP compilado en sistemas compatibles con POSIX.1-2008.
  `'n'` | Establecer el flag de no bloqueo en el descriptor de fichero abierto. Disponible solamente en PHP compilado en sistemas compatibles con POSIX.1-2008.

  > Nota:

  > Diferentes familias de sistemas operativos tienen diferentes convenciones para el final de línea. Cuando escribe un fichero de texto y quiere insertar un salto de línea, necesita usar el carácter o caracteres correctos de final de línea para su sistema operativo. Los sistemas basados en Unix usan `\n` como el carácter de final de línea, los sistemas basados en Windows usan `\r\n` como caracteres de final de línea y los sistemas basados en Macintosh usan `\r` como carácter de final de línea.

  > Si usa los caracteres de final de línea erróneos cuando escribe sus ficheros, se podrá encontrar con que otras aplicaciones que abran esos ficheros "parecerán raras".

  > Windows ofrece un flag de trasnformación en modo texto (`'t'`) que transformará de manera transparente `\n` a `\r\n` cuando se trabaja con el fichero. En contraste, puede usar `'b'` para forzar el modo binario, lo cual no transformará su información. Para usar estas flags, especifique `'b'` o `'t'` como el último carácter del parámetro `mode`.

  > El modo de transformación por omición es `'b'`. Puede usar el modo `'t'` si está trabajando con ficheros de texto plano y usa `\n` para delimitar los finales de línea es su script, pero espera que sus ficheros sean legibles con aplicaciones como versiones antiguas de notepad. Debería usar el `'b'` en todos los demás casos.

  > Si especifica el flag 't' cuando trabaja con archivos binarios, puede experimentar problemas extraños con sus datos, incluyendo archivos de imagen rotos y problemas extraños con los caracteres `\r\n`.

  > Nota:

  > Por portabilidad, También se recomienda encarecidamente que reescriba el código que usa o se basa en el modo `'t'` para que use las terminaciones de línea correctas y el modo `'b'` en su lugar.

  > Nota: El `mode` modo es ignorado para php://output, php://input, php://stdin, php://stdout, php://stderr Y envoluturas de flujo php://fd.

`use_include_path`

  El tercer parámetro opcional `use_include_path` puede ser establecido a '1' o `true` si se desea buscar un fichero también en include_path.

`context`
  Un resource de contexto de flujo.

### Valores devueltos

Devuelve un recurso de puntero a fichero si tiene éxito, o `false` si ocurre un error

### Errores/Excepciones

En caso de fallo, se emitirá una advertencia de tipo `E_WARNING`.

### Historial de cambios

Versión | Descripción
--- | ---
7.0.16, 7.1.2 | Se añadió la opción `'e'`.

### Ejemplos

Ejemplo #1 Ejemplos de fopen()

    <?php
    $handle = fopen("/home/rasmus/fichero.txt", "r");
    $handle = fopen("/home/rasmus/fichero.gif", "wb");
    $handle = fopen("http://www.ejemplo.com/", "r");
    $handle = fopen("ftp://user:password@example.com/fichero.txt", "w");
    ?>

### Notas

Advertencia

Cuando SSL es utilizado, el servidor IIS de Microsoft violará el protocolo al cerrar la conexión sin enviar un indicador `close_notify`. PHP lo reportará como "SSL: Fatal Protocol Error" cuando se llegue al final de los datos. Para evitar esto, el nivel de la directiva error_reporting debe ser bajado para no incluir los avisos. PHP puede detectar automáticamente los servidores IIS defectuosos al abrir el flujo utilizando `https://` y suprimirá el aviso. Al utilizar fsockopen() para crear un socket `ssl://`, es responsabilidad del desarrollador detectar y suprimir el aviso.

> Nota:

> Si está experimentando problemas al leer y escribir ficheros y está usando la versión de módulo de servidor de PHP, asegúrese de que los ficheros y directorios que está usando sean accesibles por el proceso del servidor.

> Nota:

> Esta función también podría tener éxito cuando `filename` es un directorio. Si no se está seguro de que `filename` sea un fichero o un directorio, podría ser necesario utilzar la función is_dir() antes de llamar a fopen().

### Ver también

- Protocolos y Envolturas soportados
- fclose() - Cierra un fichero
- fgets() - Recupera la línea actual a partir de la posición del puntero de archivo
- fread() - Lectura del archivo en modo binario
- fwrite() - Escribe en un fichero en modo binario
- fsockopen() - Abre un socket de conexión Internet o Unix
- file() - Lee el fichero y devuelve el resultado en un array
- file_exists() - Verifica si un fichero o un directorio existe
- is_readable() - Indica si un fichero existe y es accesible en lectura
- stream_set_timeout() - Configura el tiempo de espera de un flujo
- popen() - Crea un puntero de archivo de proceso
- stream_context_create() - Crea un contexto de flujo
- umask() - Cambia el "umask" actual
- SplFileObject

# fpassthru

(PHP 4, PHP 5, PHP 7, PHP 8)

fpassthru — Muestra el resto del fichero

### Descripción

function fpassthru(resource `$stream`): int

Lee todo el resto de un fichero hasta el final y dirige el resultado hacia la salida estándar.

Es necesario llamar a la función rewind() para reiniciar el puntero de fichero al principio si ya se han escrito datos en el fichero.

Si se desea únicamente copiar el contenido de un fichero en el buffer de salida, sin modificarlo previamente o colocar el puntero en un lugar particular, debe utilizarse la función readfile(), lo que evita tener que llamar a la función fopen().

### Parámetros

`stream`
  El puntero de archivo debe ser válido y apuntar a un archivo abierto con éxito por fopen() o fsockopen() (y no cerrado aún por fclose()).

### Valores devueltos

Devuelve el número de caracteres leídos desde `stream` y pasados a la salida estándar.

### Ejemplos

Ejemplo #1 Uso de fpassthru() con un fichero binario

    <?php

    // abre un fichero en modo binario
    $name = './img/ok.png';
    $fp = fopen($name, 'rb');

    // envía los encabezados correctos
    header("Content-Type: image/png");
    header("Content-Length: " . filesize($name));

    // envía el contenido del fichero, luego detiene el script
    fpassthru($fp);
    exit;

    ?>

### Notas

> Nota:

> Cuando se utiliza la función fpassthru() sobre un fichero binario en Windows, asegúrese de haber abierto el fichero en modo binario añadiendo la letra `b` al modo de acceso utilizado en fopen().

> Se recomienda utilizar la opción `b` al trabajar con ficheros binarios, incluso si el sistema no lo requiere, para garantizar la portabilidad de los scripts.

### Ver también

- readfile() - Muestra un fichero
- fopen() - Abre un fichero o un URL
- popen() - Crea un puntero de archivo de proceso
- fsockopen() - Abre un socket de conexión Internet o Unix

# fputcsv

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

fputcsv — Formatea una línea en CSV y la escribe en un fichero

### Descripción

function fputcsv(
resource `$stream`,
array `$fields`,
string `$separator` = ",",
string `$enclosure` = "\"",
string `$escape` = "\\",
string `$eol` = "\n"
): int|false

fputcsv() formatea la línea pasada como `fields` (array) como CSV y la escribe (terminada por un `eol`) en el `stream` especificado.

### Parámetros

`stream`
  El puntero de archivo debe ser válido y apuntar a un archivo abierto con éxito por fopen() o fsockopen() (y no cerrado aún por fclose()).
`fields`

  Un array de strings.

`separator`

  El parámetro `separator` define el separador de campo. Debe tratarse de un carácter de un solo byte.

`enclosure`

  El parámetro `enclosure` define el carácter de encierro de los campos. Debe tratarse de un carácter de un solo byte.

`escape`

  El parámetro `escape` define el carácter de escape. Debe tratarse de un carácter de un solo byte o una cadena vacía. La cadena vacía (`""`) desactiva el mecanismo de escape propietario.

  Advertencia

  En el flujo de entrada, el carácter `enclosure` siempre puede ser escapado duplicándolo dentro de una cadena entrecomillada, lo que resulta en un único carácter `enclosure` en el resultado analizado. El carácter `escape` funciona de manera diferente: si una secuencia de caracteres `escape` y `enclosure` aparece en la entrada, ambos caracteres estarán presentes en el resultado analizado. Así, para los parámetros por defecto, una línea CSV como `"a""b","c\"d"` tendrá los campos analizados como `a"b` y `c\"d`, respectivamente.

  Advertencia

  A partir de PHP 8.4.0, el uso del valor por omisión de `escape` está deprecado. Debe ser proporcionado explícitamente ya sea por posición o mediante el uso de los argumentos nombrados.

`eol`

  El parámetro opcional `eol` define una secuencia de fin de línea personalizada.

Advertencia

Cuando `escape` se define con un valor diferente a una cadena vacía (`""`), puede resultar en un CSV que no sea compatible con » RFC 4180 o que no pueda sobrevivir a un ciclo de ida y vuelta a través de las funciones CSV de PHP. El valor predeterminado de `escape` es `"\\"`, por lo que se recomienda definirlo explícitamente como cadena vacía. El valor predeterminado cambiará en una futura versión de PHP, no antes de PHP 9.0.

> Nota:

> Si un carácter `enclosure` está contenido en un campo, será escapado duplicándolo, a menos que esté inmediatamente precedido por un `escape`.

### Valores devueltos

Devuelve el tamaño de la cadena escrita o `false` si ocurre un error.

### Errores/Excepciones

Genera una ValueError si `separator` o `enclosure` no tiene una longitud de un byte.

Genera una ValueError si `escape` no tiene una longitud de un byte o es una cadena vacía.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Confiar en el valor por omisión de `escape` está ahora deprecado.
8.1.0 | Se añadió el parámetro opcional `eol`.
7.4.0 | El parámetro `escape` ahora acepta una cadena vacía para desactivar el mecanismo de escape propietario.

### Ejemplos

Ejemplo #1 Ejemplo con fputcsv()

    <?php

    $list = [
        ['aaa', 'bbb', 'ccc', 'dddd'],
        ['123', '456', '789'],
        ['"aaa"', '"bbb"']
    ];

    $fp = fopen('file.csv', 'w');

    foreach ($list as $fields) {
         fputcsv($fp, $fields, ',', '"', '');
    }

    fclose($fp);
    ?>

El ejemplo anterior escribirá lo siguiente en `file.csv`:

    aaa,bbb,ccc,dddd
    123,456,789
    """aaa""","""bbb"""

### Ver también

- fgetcsv() - Obtiene una línea desde un puntero de archivo y la analiza para campos CSV
- str_getcsv() - Analiza una string CSV en un array
- SplFileObject::fgetcsv() - Recupera una línea del archivo y la analiza como datos CSV
- SplFileObject::fputcsv() - Escribe un array en forma de línea CSV
- SplFileObject::setCsvControl() - Define las opciones CSV
- SplFileObject::getCsvControl() - Recupera las opciones para CSV

# fputs

(PHP 4, PHP 5, PHP 7, PHP 8)

fputs — Alias de fwrite()

### Descripción

Esta función es un alias de: fwrite().

# fread

(PHP 4, PHP 5, PHP 7, PHP 8)

fread — Lectura del archivo en modo binario

### Descripción

function fread(resource `$stream`, int `$length`): string|false

fread() lee hasta `length` bytes en el archivo referenciado por `stream`. La lectura se detiene cuando se presenta alguna de las siguientes condiciones:

- `length` bytes han sido leídos
- se alcanza el final del archivo
- un paquete se vuelve disponible o el tiempo socket timeout ha pasado (para flujos de red)
- si el flujo se lee desde el buffer, y no representa un archivo completo, entonces al menos una lectura de un número de bytes equivalente al tamaño del bloque (generalmente 8192) se realiza; siguiendo los datos del buffer anterior, el tamaño de los datos devueltos puede ser superior al tamaño del bloque.

### Parámetros

`stream`
  Un puntero del sistema de archivos de tipo resource que es habitualmente creado utilizando la función fopen().
`length`

  Tamaño `length` de bytes a leer.

### Valores devueltos

Devuelve la cadena leída, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con fread()

    <?php
    // Lee un archivo y lo coloca en una cadena
    $filename = "/usr/local/something.txt";
    $handle = fopen($filename, "r");
    $contents = fread($handle, filesize($filename));
    fclose($handle);
    ?>

Ejemplo #2 Ejemplo con fread() y un archivo binario

Advertencia

En los sistemas que diferencian los archivos de texto y binarios (por ejemplo, Windows) el archivo debe ser abierto con la letra 'b' añadida al parámetro de modo de la función fopen().

    <?php
    $filename = "c:\\files\\somepic.gif";
    $handle = fopen($filename, "rb");
    $contents = fread($handle, filesize($filename));
    fclose($handle);
    ?>

Ejemplo #3 Ejemplo con fread() y un archivo remoto

Advertencia

Cuando se lee desde cualquier fuente que no sea un archivo local, como flujos devueltos al leer archivos remotos o desde popen() y fsockopen(), la lectura se detiene después de recibir un paquete. Por lo tanto, se deben hacer bucles para recolectar los datos por paquete, como se presenta a continuación.

    <?php
    $handle = fopen("http://www.example.com/", "rb");
    $contents = stream_get_contents($handle);
    fclose($handle);
    ?>

    <?php
    $handle = fopen("http://www.example.com/", "rb");
    if (FALSE === $handle) {
        exit("Fallo al abrir el flujo hacia la URL");
    }

    $contents = '';

    while (!feof($handle)) {
        $contents .= fread($handle, 8192);
    }
    fclose($handle);
    ?>

### Notas

> Nota:

> Si se desea leer el contenido de un archivo en una cadena de caracteres, es preferible utilizar file_get_contents() que es mucho más rápido que el código anterior.

> Nota:

> Se observa que la función fread() lee la posición actual del puntero de archivo. Utilice la función ftell() para encontrar la posición actual del puntero y la función rewind() para reinicializar la posición del puntero.

### Ver también

- fwrite() - Escribe en un fichero en modo binario
- fopen() - Abre un fichero o un URL
- fsockopen() - Abre un socket de conexión Internet o Unix
- popen() - Crea un puntero de archivo de proceso
- fgets() - Recupera la línea actual a partir de la posición del puntero de archivo
- fgetss() - Obtiene un línea desde un puntero a un archivo y elimina las etiquetas HTML
- fscanf() - Analiza un archivo según un formato
- file() - Lee el fichero y devuelve el resultado en un array
- fpassthru() - Muestra el resto del fichero
- fseek() - Modifica la posición del puntero de archivo
- ftell() - Devuelve la posición actual del puntero de archivo
- rewind() - Reemplaza el puntero de fichero al inicio
- unpack() - Desempaqueta datos desde una cadena binaria

# fscanf

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

fscanf — Analiza un archivo según un formato

### Descripción

function fscanf(resource `$stream`, string `$format`, mixed `&...$vars`): array|int|false|null

La función fscanf() es similar a la función sscanf(), excepto que toma un archivo como entrada, representado por el recurso `stream` e interpreta la entrada según el formato `format` especificado.

Todos los caracteres en blanco de la cadena de formato corresponden a tantos espacios en el flujo de entrada. Esto significa que una tabulación (`\t`) en la cadena de formato puede reemplazar un espacio simple en el flujo de entrada.

Cada llamada a la función fscanf() lee una línea del archivo.

### Parámetros

`stream`
  Un puntero del sistema de archivos de tipo resource que es habitualmente creado utilizando la función fopen().
`format`

  El formato interpretado para `string` se describe en la documentación de la sprintf() con las siguientes diferencias:

  - La función no tiene en cuenta el contexto local.
  - `F`, `g`, `G` y `b` no son soportados.
  - `D` representa un número decimal.
  - `i` representa un número entero con detección de base.
  - `n` representa el número de caracteres tratados hasta este punto.
  - `s` detiene la lectura en cada carácter de espacio.
  - `*` en lugar de `argnum$` elimina la asignación de esta especificación de conversión.
`vars`
  Los valores opcionales a asignar.

### Valores devueltos

Si solo se pasan 2 argumentos a la función, el valor analizado será devuelto como un array. Si se pasan argumentos opcionales, la función devolverá el número de valores asignados. Los argumentos opcionales deben ser pasados por referencia.

Si se esperan más subcadenas en el `format` de las disponibles en `string`, `null` será devuelto. En otros casos de error, `false` será devuelto.

Cuando se usan parámetros opcionales y se alcanza el final de la entrada leída de `stream` antes de que se haya analizado ningún valor, se devuelve `-1`.

### Ejemplos

Ejemplo #1 Ejemplo con fscanf()

    <?php
    $handle = fopen("users.txt", "r");
    while ($userinfo = fscanf($handle, "%s\t%s\t%s\n")) {
        list ($name, $profession, $countrycode) = $userinfo;
        //... procesamiento de datos
    }
    fclose($handle);
    ?>

Ejemplo #2 Contenido del archivo users.txt

    javier  argonaut        pe
    hiroshi sculptor        jp
    robert  slacker us
    luigi   florist it

### Ver también

- fread() - Lectura del archivo en modo binario
- fgets() - Recupera la línea actual a partir de la posición del puntero de archivo
- fgetss() - Obtiene un línea desde un puntero a un archivo y elimina las etiquetas HTML
- sscanf() - Analiza una cadena utilizando un formato
- printf() - Muestra una string formateada
- sprintf() - Devuelve una string formateada

# fseek

(PHP 4, PHP 5, PHP 7, PHP 8)

fseek — Modifica la posición del puntero de archivo

### Descripción

function fseek(resource `$stream`, int `$offset`, int `$whence` = `SEEK_SET`): int

Modifica el cursor de posición en el archivo `stream`. La nueva posición, medida en bytes, desde el inicio del archivo, se obtiene sumando la distancia `offset` a la posición `whence`.

En general, es posible desplazarse más allá del final del flujo (eof); si se escriben datos en este caso, el espacio entre el final del flujo y la posición actual será rellenado con bytes nulos. Sin embargo, algunos flujos no soportan este comportamiento, en particular cuando el espacio de almacenamiento subyacente es de tamaño fijo.

### Parámetros

`stream`
  Un puntero del sistema de archivos de tipo resource que es habitualmente creado utilizando la función fopen().
`offset`

  La posición.

  Para desplazarse a una posición antes del final del archivo, debe pasarse un valor negativo en el `offset` y el parámetro `whence` debe establecerse en `SEEK_END`.

`whence`

  Los valores posibles para `whence` son :

  - `SEEK_SET` - Establecer la posición igual a `offset` bytes desde el inicio del archivo.
  - `SEEK_CUR` - Establecer la posición en el lugar actual más `offset` bytes.
  - `SEEK_END` - Establecer la posición al final del archivo más `offset` bytes.

### Valores devueltos

En caso de éxito, devuelve `0`; de lo contrario, devuelve `-1`.

Advertencia

Esta función ha sido creada para imitar la función del mismo nombre en lenguaje C. Tenga en cuenta los valores de retorno, ya que difieren de lo que podría esperarse en PHP.

### Ejemplos

Ejemplo #1 Ejemplo con fseek()

    <?php

    $fp = fopen('somefile.txt', 'r');

    // lee algunos datos
    $data = fgets($fp, 4096);

    // vuelve al inicio del archivo
    // equivalente a rewind($fp);
    fseek($fp, 0);

    ?>

### Notas

> Nota:

> Si abre el archivo con el modo `a` o `a+`, todos los datos que escriba en el archivo siempre serán añadidos, sin importar la posición en el archivo.

> Nota:

> No todos los flujos soportan el desplazamiento. Para aquellos que no lo soportan, el desplazamiento hacia adelante se realizará leyendo y liberando los bytes; otras formas de desplazamiento fallarán.

### Ver también

- ftell() - Devuelve la posición actual del puntero de archivo
- rewind() - Reemplaza el puntero de fichero al inicio

# fstat

(PHP 4, PHP 5, PHP 7, PHP 8)

fstat — Lee las informaciones sobre un fichero a partir de un puntero de fichero

### Descripción

function fstat(resource `$stream`): array|false

Recopila las informaciones sobre el fichero del cual se conoce el puntero `stream`. fstat() es similar a la función stat(), excepto que utiliza un puntero de fichero, en lugar de un nombre de fichero.

### Parámetros

`stream`
  Un puntero del sistema de archivos de tipo resource que es habitualmente creado utilizando la función fopen().

### Valores devueltos

Devuelve un array que contiene las estadísticas para el fichero; el formato de este array se describe en detalle en la página de documentación de la función stat(). Devuelve `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con fstat()

    <?php

    // abre un fichero
    $fp = fopen("/etc/passwd", "r");

    // lee las informaciones
    $fstat = fstat($fp);

    // cierra el fichero
    fclose($fp);

    // muestra el resultado
    print_r(array_slice($fstat, 13));

    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [dev] => 771
        [ino] => 488704
        [mode] => 33188
        [nlink] => 1
        [uid] => 0
        [gid] => 0
        [rdev] => 0
        [size] => 1114
        [atime] => 1061067181
        [mtime] => 1056136526
        [ctime] => 1056136526
        [blksize] => 4096
        [blocks] => 8
    )

### Notas

> Nota: Esta función no funciona con los archivos remotos, ya que el archivo examinado debe ser accesible en el sistema de archivos del servidor.

# fsync

(PHP 8 >= 8.1.0)

fsync — Sincroniza los cambios realizados en el fichero (incluyendo los metadatos)

### Descripción

function fsync(resource `$stream`): bool

Esta función sincroniza los cambios realizados en el fichero, incluyendo sus metadatos. Es similar a fflush(), pero además solicita al sistema operativo que escriba en el soporte de almacenamiento.

### Parámetros

`stream`
  El puntero de archivo debe ser válido y apuntar a un archivo abierto con éxito por fopen() o fsockopen() (y no cerrado aún por fclose()).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de fsync()

    <?php
    $file = 'test.txt';
    $stream = fopen($file, 'w');
    fwrite($stream, 'test data');
    fwrite($stream, "\r\n");
    fwrite($stream, 'additional data');
    fsync($stream);
    fclose($stream);
    ?>

### Ver también

- fdatasync() - Sincroniza los datos (pero no los metadatos) con el fichero
- fflush() - Envía todo el contenido generado en un fichero

# ftell

(PHP 4, PHP 5, PHP 7, PHP 8)

ftell — Devuelve la posición actual del puntero de archivo

### Descripción

function ftell(resource `$stream`): int|false

Devuelve la posición actual del puntero de archivo referenciado por `stream`.

### Parámetros

`stream`

  El puntero de archivo debe ser válido y haber sido abierto correctamente por fopen() o popen(). ftell() proporciona resultados no definidos para los flujos "`append-only`" (abiertos con el flag "a").

### Valores devueltos

Devuelve la posición actual del puntero en el archivo identificado por el puntero `stream` en forma de entero, es decir, su posición en el flujo del archivo.

Si ocurre un error, la función devolverá `false`.

> Nota: Como el tipo entero de PHP es firmado y que muchas plataformas utilizan enteros de 32 bits, algunas funciones relacionadas con el sistema de archivos pueden retornar resultados extraños para archivos de tamaño superior a 2 Go.

### Ejemplos

Ejemplo #1 Ejemplo con ftell()

    <?php

    // Abre un archivo y lee algunos datos
    $fp = fopen("/etc/passwd", "r");
    $data = fgets($fp, 12);

    // ¿Dónde estamos?
    echo ftell($fp); // 11

    fclose($fp);

    ?>

### Ver también

- fopen() - Abre un fichero o un URL
- popen() - Crea un puntero de archivo de proceso
- fseek() - Modifica la posición del puntero de archivo
- rewind() - Reemplaza el puntero de fichero al inicio

# ftruncate

(PHP 4, PHP 5, PHP 7, PHP 8)

ftruncate — Tronca un fichero

### Descripción

function ftruncate(resource `$stream`, int `$size`): bool

Se toma el puntero de fichero `stream` y se trunca a la longitud de `size`.

### Parámetros

`stream`

  El puntero de fichero.

  > Nota:

  > El puntero `stream` debe haber sido abierto en modo escritura.

`size`

  La longitud que debe conservarse.

  > Nota:

  > Si `size` es mayor que la longitud del fichero, este último será extendido con octetos nulos.

  > Si `size` es menor que la longitud del fichero, el resto de los datos se perderá.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con ftruncate()

    <?php
    $filename = 'lorem_ipsum.txt';

    $handle = fopen($filename, 'r+');
    ftruncate($handle, rand(1, filesize($filename)));
    rewind($handle);
    echo fread($handle, filesize($filename));
    fclose($handle);
    ?>

### Notas

> Nota:

> El puntero de fichero no es modificado.

### Ver también

- fopen() - Abre un fichero o un URL
- fseek() - Modifica la posición del puntero de archivo

# fwrite

(PHP 4, PHP 5, PHP 7, PHP 8)

fwrite — Escribe en un fichero en modo binario

### Descripción

function fwrite(resource `$stream`, string `$data`, ?int `$length` = `null`): int|false

fwrite() escribe el contenido de la cadena `data` en el fichero apuntado por `stream`.

### Parámetros

`stream`
  Un puntero del sistema de archivos de tipo resource que es habitualmente creado utilizando la función fopen().
`data`

  La cadena a escribir.

`length`

  Si se proporciona la longitud `length`, la escritura se detendrá después de `length` bytes, o al final de la cadena (lo que ocurra primero).

### Valores devueltos

fwrite() devuelve el número de bytes escritos o `false` si ocurre un error.

### Errores/Excepciones

La función fwrite() emite una `E_WARNING` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `length` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con fwrite()

    <?php
    $filename = 'test.txt';
    $somecontent = "Añadiendo cadena al fichero\n";

    // Asegurémonos de que el fichero es accesible en escritura
    if (is_writable($filename)) {

        // En nuestro ejemplo, abrimos el fichero $filename en modo de añadir
        // El puntero del fichero se coloca al final del fichero
        // es ahí donde $somecontent será colocado
        if (!$fp = fopen($filename, 'a')) {
             echo "No se puede abrir el fichero ($filename)";
             exit;
        }

        // Escribamos algo en nuestro fichero.
        if (fwrite($fp, $somecontent) === FALSE) {
            echo "No se puede escribir en el fichero ($filename)";
            exit;
        }

        echo "La escritura de ($somecontent) en el fichero ($filename) ha tenido éxito";

        fclose($fp);

    } else {
        echo "El fichero $filename no es accesible en escritura.";
    }
    ?>

### Notas

> Nota:

> La escritura en un flujo puede terminar antes de que la cadena completa sea escrita. El valor devuelto por la función fwrite() puede ser verificado de la siguiente manera:

>     <?php
>     function fwrite_stream($fp, $string) {
>         for ($written = 0; $written < strlen($string); $written += $fwrite) {
>             $fwrite = fwrite($fp, substr($string, $written));
>             if ($fwrite === false) {
>                 return $fwrite;
>             }
>         }
>         return $written;
>     }
>     ?>

> Nota:

> En los sistemas que hacen la distinción entre ficheros binarios y ficheros de texto (por ejemplo, Windows), el fichero debe ser abierto con la opción 'b' incluida en el parámetro de modo de fopen().

> Nota:

> Si `stream` está abierto en modo añadir (`append`), fwrite() será atómico (excepto si el tamaño de `data` excede el tamaño del bloque del sistema de ficheros, en algunas plataformas, y siempre que el fichero se encuentre en el sistema de ficheros local). Por lo tanto, no es necesario utilizar la función flock() en un recurso antes de llamar a la función fwrite(); todos los datos serán escritos sin interrupción.

> Nota:

> Si se escribe dos veces en el fichero, los datos serán añadidos al final del fichero; esto significa que el siguiente ejemplo no dará el resultado esperado:

>     <?php
>     $fp = fopen('data.txt', 'w');
>     fwrite($fp, '1');
>     fwrite($fp, '23');
>     fclose($fp);

>     // el contenido de 'data.txt' es ahora 123 y no 23 !
>     ?>

### Ver también

- fread() - Lectura del archivo en modo binario
- fopen() - Abre un fichero o un URL
- fsockopen() - Abre un socket de conexión Internet o Unix
- popen() - Crea un puntero de archivo de proceso
- file_get_contents() - Lee todo un fichero en una cadena
- pack() - Compacta datos en una cadena binaria

# glob

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

glob — Búsqueda de rutas que coinciden con un patrón

### Descripción

function glob(string `$pattern`, int `$flags` = 0): array|false

glob() busca todas las rutas que coinciden con el patrón `pattern`, siguiendo las reglas utilizadas por la función `glob()` de la libc, que son las mismas que las utilizadas por el Shell en general.

El comportamiento en sistemas Unix y macOS está determinado por la implementación de glob() del sistema. En Windows, se utiliza una implementación conforme a la definición POSIX 1003.2 de glob(), con una extensión para manejar la convención `[!...]` que permite negar un rango.

### Parámetros

`pattern`

  El patrón. No se realiza sustitución de tilde (`~`) ni de parámetro.

  Caracteres especiales:

  - `*` - Asocia cero o más caracteres.
  - `?` - Asocia exactamente un carácter (cualquier carácter).
  - `[...]` - Asocia un carácter de un conjunto de caracteres. Si el primer carácter es `!`, asocia cualquier carácter que no esté en este conjunto.
  - `{a,b,c}` - Asocia una cadena de un grupo de cadenas separadas por comas cuando se utiliza el flag `GLOB_BRACE`.
  - `\` - Escapa el carácter siguiente, excepto cuando se utiliza el flag `GLOB_NOESCAPE`.
`flags`

  Cualquiera de las constantes `GLOB_*`.

### Valores devueltos

Devuelve un array que contiene los ficheros y directorios que coinciden con el patrón, un array vacío si no hay coincidencias, o `false` si ocurre un error. A menos que se utilice `GLOB_NOSORT`, los nombres serán ordenados alfabéticamente.

### Ejemplos

Ejemplo #1 Un método práctico para reemplazar opendir() por glob()

    <?php
    foreach (glob("*.txt") as $filename) {
        echo "$filename ocupa " . filesize($filename) . "\n";
    }
    ?>

Resultado del ejemplo anterior es similar a:

    funclist.txt ocupa 44686
    funcsummary.txt ocupa 267625
    quickref.txt ocupa 137820

Ejemplo #2 Ejemplo con un patrón más complejo

    <?php
    foreach (glob("path/*/*.{txt,md}", \GLOB_BRACE) as $filename) {
        echo "$filename\n";
    }
    ?>

Resultado del ejemplo anterior es similar a:

    path/docs/mailinglist-rules.md
    path/docs/README.md
    path/docs/release-process.md
    path/pear/install-pear.txt
    path/Zend/README.md

### Notas

> Nota: Esta función no funciona con los archivos remotos, ya que el archivo examinado debe ser accesible en el sistema de archivos del servidor.

> Nota: Esta función no está disponible en algunos sistemas (por ejemplo, viejos Sun OS).

### Ver también

- opendir() - Abrir un manejador de directorio
- readdir() - Leer entrada desde el manejador de directorio
- closedir() - Cerrar el gestor de directorio
- fnmatch() - Prueba un nombre de fichero mediante un patrón de búsqueda

# is_dir

(PHP 4, PHP 5, PHP 7, PHP 8)

is_dir — Indica si el fichero es un directorio

### Descripción

function is_dir(string `$filename`): bool

Indica si el fichero es un directorio.

### Parámetros

`filename`

  Ruta de acceso al fichero. Si `filename` es un fichero relativo, será verificado relativamente al directorio de trabajo actual. Si `filename` es un enlace simbólico o un enlace convencional, el enlace será resuelto y verificado. Si se ha activado open_basedir, pueden aplicarse más restricciones.

### Valores devueltos

Devuelve `true` si el nombre de fichero existe y es un directorio, `false` en caso contrario.

### Errores/Excepciones

En caso de fallo, se emitirá una advertencia de tipo `E_WARNING`.

### Ejemplos

Ejemplo #1 Ejemplo con is_dir()

    <?php
    var_dump(is_dir('a_file.txt'));
    var_dump(is_dir('bogus_dir/abc'));

    var_dump(is_dir('..')); // un directorio superior
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(false)
    bool(true)

### Notas

> Nota: Los resultados de esta función se almacenan en caché. Véase la función clearstatcache() para más detalles.

Sugerencia

A partir de PHP 5.0.0, esta función también puede ser utilizada con algunos protocolos url. Lea Protocolos y Envolturas soportados para conocer los protocolos que soportan la familia de funcionalidades de stat().

### Ver también

- chdir() - Cambia de directorio
- dir() - Devuelve una instancia de la clase Directory
- opendir() - Abrir un manejador de directorio
- is_file() - Indica si el fichero es un fichero verdadero
- is_link() - Indica si el fichero es un enlace simbólico

# is_executable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_executable — Indica si el fichero es ejecutable

### Descripción

function is_executable(string `$filename`): bool

Indica si el fichero es ejecutable.

### Parámetros

`filename`

  Ruta de acceso al fichero.

### Valores devueltos

Devuelve `true` si el fichero existe y es ejecutable, `false` en caso contrario. En los sistemas POSIX, un fichero es ejecutable si el bit ejecutable de los permisos del fichero está definido. En Windows, véase la nota a continuación.

### Errores/Excepciones

En caso de fallo, se emitirá una advertencia de tipo `E_WARNING`.

### Ejemplos

Ejemplo #1 Ejemplo con is_executable()

    <?php

    $file = '/home/vincent/somefile.sh';

    if (is_executable($file)) {
        echo $file.' es ejecutable';
    } else {
        echo $file.' no es ejecutable';
    }

    ?>

### Notas

> Nota: Los resultados de esta función se almacenan en caché. Véase la función clearstatcache() para más detalles.

Sugerencia

A partir de PHP 5.0.0, esta función también puede ser utilizada con algunos protocolos url. Lea Protocolos y Envolturas soportados para conocer los protocolos que soportan la familia de funcionalidades de stat().

> Nota: En Windows, un fichero se considera ejecutable si es un fichero ejecutable propio según lo reportado por la API Win `GetBinaryType()`; por razones de retrocompatibilidad, los ficheros con extensión .bat o .cmd también se consideran ejecutables. Anterior a PHP 7.4.0, cualquier fichero no vacío con extensión .exe o .com se consideraba ejecutable. Cabe señalar que PATHEXT no es relevante para is_executable().

### Ver también

- is_file() - Indica si el fichero es un fichero verdadero
- is_link() - Indica si el fichero es un enlace simbólico

# is_file

(PHP 4, PHP 5, PHP 7, PHP 8)

is_file — Indica si el fichero es un fichero verdadero

### Descripción

function is_file(string `$filename`): bool

Indica si el fichero es un fichero verdadero. Si `filename` es un enlace simbólico, se resolverá el enlace y se proporcionará información sobre el fichero referenciado.

### Parámetros

`filename`

  Ruta de acceso al fichero.

### Valores devueltos

Devuelve `true` si el nombre de fichero existe y es un fichero regular, `false` en caso contrario.

> Nota: Como el tipo entero de PHP es firmado y que muchas plataformas utilizan enteros de 32 bits, algunas funciones relacionadas con el sistema de archivos pueden retornar resultados extraños para archivos de tamaño superior a 2 Go.

### Errores/Excepciones

En caso de fallo, se emitirá una advertencia de tipo `E_WARNING`.

### Ejemplos

Ejemplo #1 Ejemplo con is_file()

    <?php
    var_dump(is_file('a_file.txt')) . "\n";
    var_dump(is_file('/usr/bin/')) . "\n";
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(false)

### Notas

> Nota: Los resultados de esta función se almacenan en caché. Véase la función clearstatcache() para más detalles.

Sugerencia

A partir de PHP 5.0.0, esta función también puede ser utilizada con algunos protocolos url. Lea Protocolos y Envolturas soportados para conocer los protocolos que soportan la familia de funcionalidades de stat().

### Ver también

- is_dir() - Indica si el fichero es un directorio
- is_link() - Indica si el fichero es un enlace simbólico
- SplFileInfo

# is_link

(PHP 4, PHP 5, PHP 7, PHP 8)

is_link — Indica si el fichero es un enlace simbólico

### Descripción

function is_link(string `$filename`): bool

Indica si el fichero es un enlace simbólico.

### Parámetros

`filename`

  Ruta de acceso al fichero.

### Valores devueltos

Devuelve `true` si el nombre de fichero existe y es un enlace simbólico, `false` en caso contrario.

### Errores/Excepciones

En caso de fallo, se emitirá una advertencia de tipo `E_WARNING`.

### Ejemplos

Ejemplo #1 Creación y verificación de un enlace simbólico

    <?php
    $link = 'uploads';

    if (is_link($link)) {
        echo readlink($link);
    } else {
        symlink('uploads.php', $link);
    }
    ?>

### Notas

> Nota: Los resultados de esta función se almacenan en caché. Véase la función clearstatcache() para más detalles.

Sugerencia

A partir de PHP 5.0.0, esta función también puede ser utilizada con algunos protocolos url. Lea Protocolos y Envolturas soportados para conocer los protocolos que soportan la familia de funcionalidades de stat().

### Ver también

- is_dir() - Indica si el fichero es un directorio
- is_file() - Indica si el fichero es un fichero verdadero
- readlink() - Devuelve el contenido de un enlace simbólico
- symlink() - Crea un enlace simbólico

# is_readable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_readable — Indica si un fichero existe y es accesible en lectura

### Descripción

function is_readable(string `$filename`): bool

Indica si un fichero existe y es accesible en lectura.

### Parámetros

`filename`

  Ruta hacia el fichero.

### Valores devueltos

Devuelve `true` si el fichero o el directorio especificado por `filename` existe y es accesible en lectura, `false` en caso contrario.

### Errores/Excepciones

En caso de fallo, se emitirá una advertencia de tipo `E_WARNING`.

### Ejemplos

Ejemplo #1 Ejemplo con is_readable()

    <?php
    $filename = 'test.txt';
    if (is_readable($filename)) {
        echo 'El fichero es accesible en lectura';
    } else {
        echo 'El fichero no es accesible en lectura !';
    }
    ?>

### Notas

No se olvide que PHP accede a los ficheros con los mismos permisos que el usuario que ejecuta el servidor web (a menudo, es 'nobody', nadie).

> Nota: Los resultados de esta función se almacenan en caché. Véase la función clearstatcache() para más detalles.

Sugerencia

A partir de PHP 5.0.0, esta función también puede ser utilizada con algunos protocolos url. Lea Protocolos y Envolturas soportados para conocer los protocolos que soportan la familia de funcionalidades de stat().

> Nota:

> La verificación se realiza utilizando el UID/GID real en lugar del efectivo.

Esta función puede devolver `true` para los directorios. Utilice la función is_dir() para distinguir los ficheros y los directorios.

### Ver también

- is_writable() - Indica si un fichero es accesible en escritura
- file_exists() - Verifica si un fichero o un directorio existe
- fgets() - Recupera la línea actual a partir de la posición del puntero de archivo

# is_uploaded_file

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

is_uploaded_file — Indica si el archivo fue subido mediante HTTP POST

### Descripción

function is_uploaded_file(string `$filename`): bool

Devuelve `true` si el archivo nombrado por `filename` fue subido mediante HTTP POST. Esto es útil para intentar asegurarse de que un usuario malicioso no ha intentado engañar al script haciéndole trabajar con archivos con los que no debiera de estar trabajando--por ejemplo, /etc/passwd.

Este tipo de comprobación es especialmente importante si hay alguna posibilidad de que nada hecho con los archivos subidos pueda revelar su contenido al usuario, o incluso a otros usuarios en el mismo sistema.

Para un funcionamiento apropiado, la función is_uploaded_file() necesita un argumento como $_FILES['archivo_usuario']['tmp_name'], - el nombre del archivo subido de la máquina del cliente $_FILES['archivo_usuario']['name'] no funciona.

### Parámetros

`filename`

  El nombre de archivo que se va a comprobar.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de is_uploaded_file()

    <?php

    if (is_uploaded_file($_FILES['archivo_usuario']['tmp_name'])) {
       echo "Archivo ". $_FILES['archivo_usuario']['name'] ." subido con éxtio.\n";
       echo "Monstrar contenido\n";
       readfile($_FILES['archivo_usuario']['tmp_name']);
    } else {
       echo "Posible ataque del archivo subido: ";
       echo "nombre del archivo '". $_FILES['archivo_usuario']['tmp_name'] . "'.";
    }

    ?>

### Ver también

- move_uploaded_file() - Mueve un archivo subido a una nueva ubicación
- $_FILES
- Véase Manejo de subidas de archivos para un sencillo ejemplo de uso.

# is_writable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_writable — Indica si un fichero es accesible en escritura

### Descripción

function is_writable(string `$filename`): bool

devuelve `true` si `filename` existe y es accesible en escritura. El argumento puede ser el nombre de un directorio, permitiendo así verificar si el directorio es accesible en escritura.

No se olvide que PHP accede a los ficheros con los mismos permisos que el usuario que ejecuta el servidor web (a menudo, es '`nobody`', nadie).

### Parámetros

`filename`

  El nombre del fichero a verificar.

### Valores devueltos

Devuelve `true` si el fichero `filename` existe y es accesible en escritura.

### Errores/Excepciones

En caso de fallo, se emitirá una advertencia de tipo `E_WARNING`.

### Ejemplos

Ejemplo #1 Ejemplo con is_writable()

    <?php
    $filename = 'test.txt';
    if (is_writable($filename)) {
        echo 'El fichero es accesible en escritura.';
    } else {
        echo 'El fichero no es accesible en escritura !';
    }
    ?>

### Notas

> Nota: Los resultados de esta función se almacenan en caché. Véase la función clearstatcache() para más detalles.

Sugerencia

A partir de PHP 5.0.0, esta función también puede ser utilizada con algunos protocolos url. Lea Protocolos y Envolturas soportados para conocer los protocolos que soportan la familia de funcionalidades de stat().

### Ver también

- is_readable() - Indica si un fichero existe y es accesible en lectura
- file_exists() - Verifica si un fichero o un directorio existe
- fwrite() - Escribe en un fichero en modo binario

# is_writeable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_writeable — Alias de is_writable()

### Descripción

Esta función es un alias de: is_writable().

# lchgrp

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

lchgrp — Cambiar la pertenencia al grupo de un enlace simbólico

### Descripción

function lchgrp(string `$filename`, string|int `$group`): bool

Intenta reemplazar el grupo del enlace simbólico `filename` por el grupo `group`.

Solo el superusuario puede cambiar el grupo de un enlace simbólico arbitrariamente; los demás usuarios pueden cambiar el grupo de un enlace simbólico a un grupo del cual este usuario es miembro.

### Parámetros

`filename`

  Ruta hacia el enlace simbólico.

`group`

  El grupo, especificado por su nombre o su número.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Modificación del grupo de un enlace simbólico

    <?php
    $target = 'output.php';
    $link = 'output.html';
    symlink($target, $link);

    lchgrp($link, 8);
    ?>

### Notas

> Nota: Esta función no funciona con los archivos remotos, ya que el archivo examinado debe ser accesible en el sistema de archivos del servidor.

> Nota: Esta función no está implementada en las plataformas Windows.

### Ver también

- chgrp() - Cambia el grupo de un fichero
- lchown() - Cambia el propietario de un enlace simbólico
- chown() - Cambia el propietario del fichero
- chmod() - Cambia el modo del fichero

# lchown

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

lchown — Cambia el propietario de un enlace simbólico

### Descripción

function lchown(string `$filename`, string|int `$user`): bool

Intenta reemplazar el propietario del enlace simbólico `filename` por el usuario `user`

Solo el superusuario puede cambiar el propietario de un enlace simbólico.

### Parámetros

`filename`

  Ruta hacia el fichero.

`user`

  El usuario, por su nombre o su número.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Modificación del propietario de un enlace simbólico

    <?php
    $target = 'output.php';
    $link = 'output.html';
    symlink($target, $link);

    lchown($link, 8);
    ?>

### Notas

> Nota: Esta función no funciona con los archivos remotos, ya que el archivo examinado debe ser accesible en el sistema de archivos del servidor.

> Nota: Esta función no está implementada en las plataformas Windows.

### Ver también

- chown() - Cambia el propietario del fichero
- lchgrp() - Cambiar la pertenencia al grupo de un enlace simbólico
- chgrp() - Cambia el grupo de un fichero
- chmod() - Cambia el modo del fichero

# link

(PHP 4, PHP 5, PHP 7, PHP 8)

link — Crea un enlace

### Descripción

function link(string `$target`, string `$link`): bool

link() crea un enlace.

### Parámetros

`target`

  El destino del enlace.

`link`

  El nombre del enlace.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

La función falla y emite una `E_WARNING` si `link` ya existe, o si `target` no existe.

### Ejemplos

Ejemplo #1 Creación de un enlace

    <?php

    $target = 'source.ext'; // Este es el fichero que existe actualmente
    $link = 'newfile.ext';  // Este será el nombre del fichero que se desea enlazar

    link($target, $link);
    ?>

### Notas

> Nota: Esta función no funciona con los archivos remotos, ya que el archivo examinado debe ser accesible en el sistema de archivos del servidor.

> Nota: Windows únicamente: esta función requiere un nivel de funcionamiento con derechos elevados, o bien la desactivación de UAC.

### Ver también

- symlink() - Crea un enlace simbólico
- readlink() - Devuelve el contenido de un enlace simbólico
- linkinfo() - Devuelve la información de un enlace
- unlink() - Elimina un fichero

# linkinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

linkinfo — Devuelve la información de un enlace

### Descripción

function linkinfo(string `$path`): int|false

Devuelve la información de un enlace.

Esta función se utiliza para verificar si un enlace (indicado por la ruta `path`) existe realmente (utilizando el mismo método que la macro S_ISLNK, definida en stat.h).

### Parámetros

`path`

  Ruta hacia el enlace.

### Valores devueltos

linkinfo() devuelve el campo `st_dev` de la estructura stat de C Unix, devuelta por la llamada al sistema `lstat`. Devuelve un entero no negativo en caso de éxito, -1 en el caso de que el enlace no haya sido encontrado, o `false` si ocurre una violación open.base_dir.

### Ejemplos

Ejemplo #1 Ejemplo con linkinfo()

    <?php

    echo linkinfo('/vmlinuz'); // 835

    ?>

### Ver también

- symlink() - Crea un enlace simbólico
- link() - Crea un enlace
- readlink() - Devuelve el contenido de un enlace simbólico

# lstat

(PHP 4, PHP 5, PHP 7, PHP 8)

lstat — Devuelve información sobre un fichero o un enlace simbólico

### Descripción

function lstat(string `$filename`): array|false

Devuelve información sobre un fichero o un enlace simbólico.

### Parámetros

`filename`

  Ruta de acceso a un fichero o un enlace simbólico.

### Valores devueltos

Consúltese la página del manual de stat() para obtener más información sobre la estructura del array devuelto por lstat(). Esta función es idéntica a la función stat() excepto que si `filename` es un enlace simbólico, la información se basará en el enlace simbólico.

En caso de error, se devuelve `false`.

### Errores/Excepciones

En caso de fallo, se emitirá una advertencia de tipo `E_WARNING`.

### Ejemplos

Ejemplo #1 Comparación entre stat() y lstat()

    <?php
    symlink('uploads.php', 'uploads');

    // Se destaca la diferencia de información
    array_diff(stat('uploads'), lstat('uploads'));
    ?>

Resultado del ejemplo anterior es similar a:

Información que difiere entre los 2 ficheros.

    Array
    (
        [ino] => 97236376
        [mode] => 33188
        [size] => 34
        [atime] => 1223580003
        [mtime] => 1223581848
        [ctime] => 1223581848
        [blocks] => 8
    )

### Notas

> Nota: Los resultados de esta función se almacenan en caché. Véase la función clearstatcache() para más detalles.

Sugerencia

A partir de PHP 5.0.0, esta función también puede ser utilizada con algunos protocolos url. Lea Protocolos y Envolturas soportados para conocer los protocolos que soportan la familia de funcionalidades de stat().

### Ver también

- stat() - Proporciona información sobre un fichero

# mkdir

(PHP 4, PHP 5, PHP 7, PHP 8)

mkdir — Crea un directorio

### Descripción

function mkdir(
string `$directory`,
int `$permissions` = 0777,
bool `$recursive` = `false`,
?resource `$context` = `null`
): bool

Intenta crear el directorio especificado por `directory`.

### Parámetros

`directory`

  La ruta del directorio.

  Sugerencia

  Puede utilizar una URL como nombre de archivo con esta función, si el gestor fopen ha sido activado. Véase fopen() para más detalles sobre cómo especificar el nombre del archivo. Consulte Protocolos y Envolturas soportados para más información sobre las capacidades de los diferentes gestores, las notas sobre su uso, así como la información sobre las variables predefinidas que proporcionan.

`permissions`

  El modo predeterminado es 0777, lo que significa el acceso más amplio posible. Para más información sobre los modos, lea los detalles en la página de chmod().

  > Nota:

  > `permissions` es ignorado en Windows.

  Observe que probablemente se quiera especificar el modo como un número octal, lo que significa que debería de haber un cero inicial. El modo es modificado también por la actual máscara de usuario, la cual se puede cambiar usando umask().

`recursive`

  Si el valor es `true`, entonces cualquier directorio padre del directorio especificado en el parámetro `directory` también será creado, con los mismos permisos.

`context`
  Un resource de contexto de flujo.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

> Nota:

> Si el directorio a crear ya existe, se considerará un error y se devolverá `false`. Utilice is_dir() o file_exists() para comprobar si el directorio ya existe antes de intentar crearlo.

### Errores/Excepciones

Emite un error de nivel `E_WARNING` si el directorio ya existe.

Emite un error de nivel `E_WARNING` si los permisos relevantes impiden crear el directorio.

### Ejemplos

Ejemplo #1 Ejemplo de mkdir()

    <?php
    mkdir("/ruta/a/mi/directorio", 0700);
    ?>

Ejemplo #2 mkdir() usando el parámetro `recursive`

    <?php
    // Estructura de la carpeta deseada
    $estructura = './nivel1/nivel2/nivel3/';

    // Para crear una estructura anidada se debe especificar
    // el parámetro $recursive en mkdir().

    if(!mkdir($estructura, 0777, true)) {
        die('Fallo al crear las carpetas...');
    }

    // ...
    ?>

### Ver también

- is_dir() - Indica si el fichero es un directorio
- rmdir() - Elimina un directorio
- umask() - Cambia el "umask" actual

# move_uploaded_file

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

move_uploaded_file — Mueve un archivo subido a una nueva ubicación

### Descripción

function move_uploaded_file(string `$filename`, string `$destination`): bool

Esta función intenta asegurarse de que el archivo designado por `filename` es un archivo subido válido (lo que significa que fue subido mediante el mecanismo de subida HTTP POST de PHP). Si el archivo es válido, será movido al nombre de archivo dado por `destination`.

El orden de comprobación es especialmente importante si hay cualquier posibilidad de que cualquier cosa hecha con los archivos subidos pueda revelar su contenido al usuario, o incluso a otros usuarios en el mismo sistema.

### Parámetros

`filename`

  El nombre de archivo del archivo subido.

`destination`

  El destino del archivo movido.

### Valores devueltos

Devuelve `true` en caso de éxito.

Si `filename` no es un archivo válido subido, no sucederá ninguna acción, y move_uploaded_file() devolverá `false`.

Si `filename` es un archivo subido válido, pero no puede ser movido por algunas razones, no sucederá ninguna acción, y move_uploaded_file() devolverá `false`. Adicionalmente, se emitirá un aviso.

### Ejemplos

Ejemplo #1 Subida de múltiples archivos

    <?php
    $uploads_dir = '/uploads';
    foreach ($_FILES["pictures"]["error"] as $key => $error) {
        if ($error == UPLOAD_ERR_OK) {
            $tmp_name = $_FILES["pictures"]["tmp_name"][$key];
            // basename() puede evitar ataques de denegación de sistema de ficheros;
            // podría ser apropiada más validación/saneamiento del nombre del fichero
            $name = basename($_FILES["pictures"]["name"][$key]);
            move_uploaded_file($tmp_name, "$uploads_dir/$name");
        }
    }
    ?>

### Notas

> Nota:

> move_uploaded_file() es compatible con open_basedir. Sin embargo, las restricciones sólo están impuestas para la ruta `dest` para permitir mover los archivos subidos en los cuales `filename` pueda tener conflictos con tales restricciones. move_uploaded_file() garantiza la seguridad de esta operación permitiendo que sólo aquellos archivos subidos a través de PHP sean movidos.

Advertencia

Si el archivo destino ya existe se sobrescribirá.

### Ver también

- is_uploaded_file() - Indica si el archivo fue subido mediante HTTP POST
- rename() - Renombra un fichero o un directorio
- Véase Manejo de subidas de archivos para un sencillo ejemplo de uso

# parse_ini_file

(PHP 4, PHP 5, PHP 7, PHP 8)

parse_ini_file — Analiza un archivo de configuración

### Descripción

function parse_ini_file(string `$filename`, bool `$process_sections` = `false`, int `$scanner_mode` = `INI_SCANNER_NORMAL`): array|false

parse_ini_file() carga el archivo `filename` y devuelve las configuraciones que contiene como un array asociativo.

La estructura de los archivos de configuración leídos es similar a la de php.ini.

Advertencia

Esta función no debe ser utilizada con entradas no confiables, a menos que `scanner_mode` sea `INI_SCANNER_RAW`, ya que la salida analizada podría contener los valores de constantes sensibles, como constantes que contienen una contraseña de base de datos.

### Parámetros

`filename`

  El nombre del archivo de configuración a analizar. Si se utiliza una ruta relativa, se evalúa relativa a la carpeta actual, luego según el include_path.

`process_sections`

  Al pasar el argumento `process_sections` a `true`, se obtendrá un array multidimensional con los nombres de las secciones. El valor por omisión de este argumento es `false`

`scanner_mode`

  Puede ser `INI_SCANNER_NORMAL` (por omisión) o `INI_SCANNER_RAW`. Si se proporciona `INI_SCANNER_RAW`, entonces los valores en opción no serán analizados.

  A partir de PHP 5.6.1 también puede ser especificado como `INI_SCANNER_TYPED`. En este modo los booleanos, null y enteros son preservados tanto como sea posible. Las cadenas de caracteres `"true"`, `"on"` y `"yes"` son convertidas a `true`. `"false"`, `"off"`, `"no"` y `"none"` son considerados como `false`. `"null"` es convertido a `null` en este modo. Además todas las cadenas de caracteres numéricas son convertidas a entero si es posible.

### Valores devueltos

La configuración se devuelve en forma de un array asociativo en caso de éxito, y `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Contenido del archivo sample.ini

    ; Este es un archivo de configuración
    ; Los comentarios comienzan con ';', como en php.ini

    [first_section]
    one = 1
    five = 5
    animal = BIRD

    [second_section]
    path = "/usr/local/bin"
    URL = "http://www.example.com/~username"

    [third_section]
    phpversion[] = "5.0"
    phpversion[] = "5.1"
    phpversion[] = "5.2"
    phpversion[] = "5.3"

    urls[svn] = "http://svn.php.net"
    urls[git] = "http://git.php.net"

Ejemplo #2 Ejemplo con parse_ini_file()

Las constantes (pero no las "constantes mágicas" como `__FILE__`) también pueden ser utilizadas en el archivo .ini, por lo que si se define una constante antes de ejecutar parse_ini_file(), será integrada en los resultados. Solo se evalúan los valores de configuración, y el valor debe ser simplemente la constante. Por ejemplo:

    <?php

    define('BIRD', 'Dodo bird');

    // Análisis sin secciones
    $ini_array = parse_ini_file("sample.ini");
    print_r($ini_array);

    // Análisis con secciones
    $ini_array = parse_ini_file("sample.ini", true);
    print_r($ini_array);

    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [one] => 1
        [five] => 5
        [animal] => Dodo bird
        [path] => /usr/local/bin
        [URL] => http://www.example.com/~username
        [phpversion] => Array
            (
                [0] => 5.0
                [1] => 5.1
                [2] => 5.2
                [3] => 5.3
            )

        [urls] => Array
            (
                [svn] => http://svn.php.net
                [git] => http://git.php.net
            )

    )
    Array
    (
        [first_section] => Array
            (
                [one] => 1
                [five] => 5
                [animal] => Dodo bird
            )

        [second_section] => Array
            (
                [path] => /usr/local/bin
                [URL] => http://www.example.com/~username
            )

        [third_section] => Array
            (
                [phpversion] => Array
                    (
                        [0] => 5.0
                        [1] => 5.1
                        [2] => 5.2
                        [3] => 5.3
                    )
                [urls] => Array
                    (
                        [svn] => http://svn.php.net
                        [git] => http://git.php.net
                    )

    )

Ejemplo #3 parse_ini_file() para analizar un archivo php.ini

    <?php
    // Una función simple para comparar los resultados a continuación
    function yesno($expression)
    {
        return($expression ? 'Yes' : 'No');
    }

    // Lee la ruta del php.ini utilizando php_ini_loaded_file()
    $ini_path = php_ini_loaded_file();

    // Análisis de php.ini
    $ini = parse_ini_file($ini_path);

    // Visualización y comparativo de los valores. Observe que get_cfg_var()
    // dará los mismos resultados entre los resultados analizados y cargados
    echo '(analizado) magic_quotes_gpc = ' . yesno($ini['magic_quotes_gpc']) . PHP_EOL;
    echo '(cargado ) magic_quotes_gpc = ' . yesno(get_cfg_var('magic_quotes_gpc')) . PHP_EOL;
    ?>

Resultado del ejemplo anterior es similar a:

    (analizado) magic_quotes_gpc = Yes
    (cargado ) magic_quotes_gpc = Yes

Ejemplo #4 Interpolación de Valor

Además de evaluar las constantes, ciertos caracteres tienen un significado particular en un valor ini. Adicionalmente, las variables de entorno y opciones de configuración definidas previamente (ver get_cfg_var()) pueden ser leídas utilizando la sintaxis `${}`.

    ; | se utiliza para OR a nivel de bits
    three = 2|3

    ; & se utiliza para AND a nivel de bits
    four = 6&5

    ; ^ se utiliza para XOR a nivel de bits
    five = 3^6

    ; ~ se utiliza para negación a nivel de bits
    negative_two = ~1

    ; () se utiliza para agrupación
    seven = (8|7)&(6|5)

    ; Interpolar la variable de entorno PATH
    path = ${PATH}

    ; Interpolar la opción de configuración 'memory_limit'
    configured_memory_limit = ${memory_limit}

Ejemplo #5 Escapar Caracteres

Ciertos caracteres tienen un significado particular en las cadenas entre comillas dobles y deben ser escapados prefijándolos con un backslash. Primero, son las comillas dobles `"` como marcador de frontera, y el backslash `\` mismo (si está seguido de uno de los caracteres especiales):

    quoted = "She said \"Exactly my point\"." ; Resultados en una cadena con marcas de comillas en ella.
    hint = "Use \\\" to escape double quote" ; Resultados en: Use \" to escape double quote

Hay una excepción para las rutas estilo Windows: es posible no escapar el backslash final si la cadena citada es seguida directamente por un retorno de línea:

    save_path = "C:\Temp\"

Si se debe escapar una comilla doble seguida de un retorno de línea en un valor multilínea, es posible utilizar la concatenación de valor de la siguiente manera (hay una cadena de comillas dobles seguida directamente de otra):

    long_text = "Lorem \"ipsum\"""
     dolor" ; Resultados en: Lorem "ipsum"\n dolor

Otro carácter con un significado particular es `$` (el signo de dólar). Debe ser escapado si está seguido de una llave abierta:

    code = "\${test}"

El escape de caracteres no es soportado en el modo `INI_SCANNER_RAW` (en este modo todos los caracteres son tratados "tal cual").

Es de notar que el analizador INI no soporta las secuencias de escape estándar (`\n`, `\t`, etc.). Si es necesario, el resultado de parse_ini_file() debe ser post-procesado con la función stripcslashes().

### Notas

> Nota:

> Esta función no tiene nada que ver con el archivo php.ini. Este último ya ha sido procesado cuando se comienza a ejecutar el script. Esta función puede permitir leer sus propios archivos de configuración.

> Nota:

> Si un valor del archivo ini contiene datos no-alfanuméricos, debe ser protegido colocándolo entre comillas dobles (").

> Nota: Existen palabras reservadas que no deben ser utilizadas como claves en los archivos ini. Esto incluye: `null`, `yes`, `no`, `true`, `false`, `on` y `off`. Los valores `null`, `off`, `no` y `false` dan "" (cadena vacía). Los valores `on`, `yes` y `true` dan "1", a menos que se utilice el modo `INI_SCANNER_TYPED`. Los caracteres `?{}|&~!()^"` no deben ser utilizados en ninguna parte de la clave y tienen un significado especial en el valor.

> Nota:

> Las entradas sin un signo igual serán ignoradas. Por ejemplo, "foo" será ignorado mientras que "bar =" será analizado y añadido con un valor vacío. Por ejemplo, MySQL tiene una opción de configuración "no-auto-rehash" en el archivo my.cnf que no toma valor, por lo tanto, será ignorada.

> Nota:

> Los archivos ini son generalmente tratados como archivos de texto sin formato por los servidores web, y por lo tanto enviados al navegador si se solicita. Esto significa que para la seguridad, los archivos ini deben ser almacenados fuera de la raíz docroot, o reconfigurar el servidor web para no servirlos. El fracaso de realizar una de estas medidas puede introducir un riesgo de seguridad.

### Ver también

- parse_ini_string() - Analiza una cadena de configuración

# parse_ini_string

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

parse_ini_string — Analiza una cadena de configuración

### Descripción

function parse_ini_string(string `$ini_string`, bool `$process_sections` = `false`, int `$scanner_mode` = `INI_SCANNER_NORMAL`): array|false

parse_ini_string() devuelve la configuración en la cadena `ini_string` en un array asociativo.

La estructura de la cadena debe ser la misma que la del archivo php.ini.

Advertencia

Esta función no debe ser utilizada con entradas no confiables, a menos que `scanner_mode` sea `INI_SCANNER_RAW`, ya que la salida analizada podría contener los valores de constantes sensibles, como constantes que contienen una contraseña de base de datos.

### Parámetros

`ini_string`

  El contenido de tipo ini a analizar.

`process_sections`

  Al activar el argumento `process_sections` con `true`, se obtendrá un array multidimensional, con los nombres de secciones y directivas. El valor por omisión del argumento `process_sections` es `false`

`scanner_mode`

  Puede tomar los valores de las constantes `INI_SCANNER_NORMAL` (por omisión) o `INI_SCANNER_RAW`. Si `INI_SCANNER_RAW` es utilizado, los valores de las opciones no serán analizados.

  A partir de PHP 5.6.1 también puede ser especificado como `INI_SCANNER_TYPED`. En este modo los booleanos, null y enteros son preservados tanto como sea posible. Las cadenas de caracteres `"true"`, `"on"` y `"yes"` son convertidas a `true`. `"false"`, `"off"`, `"no"` y `"none"` son considerados como `false`. `"null"` es convertido a `null` en este modo. Además todas las cadenas de caracteres numéricas son convertidas a entero si es posible.

### Valores devueltos

Las directivas son devueltas en forma de array array en caso de éxito, y `false` en caso de error.

### Notas

> Nota: Existen varias palabras reservadas que no deben ser utilizadas como clave en los archivos .ini. Esto incluye: `null`, `yes`, `no`, `true`, `false`, `on`, `off`, `none`. Los valores `null`, `off`, `no` y `false` son devueltos como "" (cadena vacía) y los valores `on`, `yes` y `true` son devueltos como "1" a menos que el modo `INI_SCANNER_TYPED` sea utilizado. Los caracteres `?{}|&~![()^"` no deben ser utilizados en ninguna parte en las claves, y tienen un significado especial en los valores.

### Ver también

- parse_ini_file() - Analiza un archivo de configuración

# pathinfo

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pathinfo — Devuelve información sobre una ruta del sistema

### Descripción

function pathinfo(string `$path`, int `$flags` = `PATHINFO_ALL`): array|string

pathinfo() devuelve información sobre la ruta `path`, en forma de string o array asociativo, dependiendo del argumento `flags`.

> Nota:

> Para más información sobre la lectura de la ruta actual, consulte la sección sobre las variables predefinidas.

> Nota:

> pathinfo() opera de manera ingenua sobre la cadena de entrada, y no es consciente de los sistemas de archivos actuales, o de los componentes de rutas como "`..`".

> Nota:

> Solo en sistemas Windows, el carácter `\` será interpretado como separador de directorio. En otros sistemas, será tratado como cualquier otro carácter.

Precaución

La función pathinfo() es sensible a la configuración local, por lo tanto, si se desea que analice correctamente una ruta que contenga caracteres de varios bytes, la configuración local correspondiente debe ser definida utilizando la función setlocale().

### Parámetros

`path`

  La ruta a analizar.

`flags`

  Especifica qué elemento será devuelto. Puede pasar una de las constantes `PATHINFO_DIRNAME`, `PATHINFO_BASENAME`, `PATHINFO_EXTENSION` y `PATHINFO_FILENAME`.

  Si `flags` no es especificado, todos los elementos son devueltos.

### Valores devueltos

Si `flags` no es utilizado, esta función devolverá un array asociativo que contiene los siguientes elementos : `dirname`, `basename`, `extension` (si existe), y `filename`.

> Nota:

> Si `path` contiene más de una extensión, `PATHINFO_EXTENSION` devuelve únicamente la última y `PATHINFO_FILENAME` eliminará únicamente la última también (ver el primer ejemplo a continuación).

> Nota:

> Si `path` no tiene extensión, el elemento `extension` no será devuelto (ver el segundo ejemplo a continuación).

> Nota:

> Si `basename` del argumento `path` comienza con un punto, los caracteres siguientes son interpretados como la `extension`, y el `filename` estará vacío (ver el tercer ejemplo a continuación).

Si `flags` es utilizado, esta función devolverá una string que contiene los elementos.

### Ejemplos

Ejemplo #1 Ejemplo con pathinfo()

    <?php
    $path_parts = pathinfo('/www/htdocs/inc/lib.inc.php');

    echo $path_parts['dirname'], "\n";
    echo $path_parts['basename'], "\n";
    echo $path_parts['extension'], "\n";
    echo $path_parts['filename'], "\n";
    ?>

El ejemplo anterior mostrará:

    /www/htdocs/inc
    lib.inc.php
    php
    lib.inc

Ejemplo #2 Ejemplo pathinfo() sin extensión

    <?php
    $path_parts = pathinfo('/path/emptyextension.');
    var_dump($path_parts['extension']);

    $path_parts = pathinfo('/path/noextension');
    var_dump($path_parts['extension']);
    ?>

Resultado del ejemplo anterior es similar a:

    string(0) ""

    Notice: Undefined index: extension in test.php on line 6
    NULL

Ejemplo #3 Ejemplo con pathinfo()

    <?php
    print_r(pathinfo('/some/path/.test'));
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [dirname] => /some/path
        [basename] => .test
        [extension] => test
        [filename] =>
    )

Ejemplo #4 Ejemplo de pathinfo() con desestructuración de array

El argumento `flags` no es una máscara de bits. Solo un valor puede ser proporcionado. Para seleccionar únicamente un conjunto limitado de valores analizados, utilice la desestructuración de array como se muestra a continuación:

    <?php
         ['basename' => $basename, 'dirname' => $dirname] = pathinfo('/www/htdocs/inc/lib.inc.php');
         var_dump($basename, $dirname);
         ?>

Resultado del ejemplo anterior es similar a:

    string(11) "lib.inc.php"
         string(15) "/www/htdocs/inc"

### Ver también

- dirname() - Devuelve la ruta de la carpeta padre
- basename() - Devuelve el nombre del componente final de una ruta
- parse_url() - Analiza una URL y devuelve sus componentes
- realpath() - Retorna la ruta de acceso canónica absoluta

# pclose

(PHP 4, PHP 5, PHP 7, PHP 8)

pclose — Cierra un proceso de un puntero a un fichero

### Descripción

function pclose(resource `$handle`): int

Cierra un puntero a un fichero hacia una tubería abierta por popen().

### Parámetros

`handle`

  El puntero al fichero debe ser válido, y debe haber sido devuelto por una llamada exitosa a popen().

### Valores devueltos

Devuelve el estado de terminación del proceso que se estaba ejecutando. En caso de error, se devuelve `-1`.

> Nota: Si PHP ha sido compilado con la opción de configuración --enable-sigchild, el valor devuelto de esta función será indefinido.

### Ejemplos

Ejemplo #1 Ejemplo de pclose()

    <?php
    $gestor = popen('/bin/ls', 'r');
    pclose($gestor);
    ?>

### Notas

> Nota: Solamente Unix:

> pclose() está internamente implementada usando la llamada al sistema de `waitpid(3)`. Para obtener el código de estado de salida real debería usarse la función pcntl_wexitstatus().

### Ver también

- popen() - Crea un puntero de archivo de proceso

# popen

(PHP 4, PHP 5, PHP 7, PHP 8)

popen — Crea un puntero de archivo de proceso

### Descripción

function popen(string `$command`, string `$mode`): resource|false

Crea un puntero de archivo de proceso, ejecutado mediante un fork de la orden proporcionada por el argumento `command`.

### Parámetros

`command`

  La orden

`mode`

  El modo. Puede ser `'r'` para lectura, o `'w'` para escritura.

  En Windows, popen() utiliza el modo texto por defecto, es decir, todo carácter `\n` escrito o leído del pipe será traducido a `\r\n`. Si esto no es deseado, el modo binario puede ser forzado definiendo el `mode` a `'rb'` y `'wb'`, respectivamente.

### Valores devueltos

Devuelve un puntero de archivo idéntico al devuelto por fopen(), excepto que será unidireccional (solo lectura, o solo escritura), y debe ser cerrado mediante pclose(). Este puntero puede ser utilizado con fgets(), fgetss() y fwrite(). Cuando el modo es 'r', el puntero de archivo devuelto equivale al STDOUT de la orden, y cuando el modo es 'w', el puntero de archivo devuelto equivale al STDIN de la orden.

Si ocurre un error, la función devolverá `false`.

### Ejemplos

Ejemplo #1 Ejemplo con popen()

    <?php
    $handle = popen("/bin/ls", "r");
    ?>

Si la orden a ejecutar no ha podido ser encontrada, se devolverá un recurso válido. Esto puede parecer extraño, pero es práctico. Esto permite acceder a los mensajes de error que han sido devueltos por el Shell:

Ejemplo #2 Ejemplo con popen()

    <?php
    error_reporting(E_ALL);

    /* Añade una redirección para que pueda leer stderr. */
    $handle = popen('/path/to/executable 2>&1', 'r');
    echo "'$handle'; " . gettype($handle) . "\n";
    $read = fread($handle, 2096);
    echo $read;
    pclose($handle);
    ?>

### Notas

> Nota:

> Si se desea un soporte bidireccional (two-way), utilice la función proc_open().

### Ver también

- pclose() - Cierra un proceso de un puntero a un fichero
- fopen() - Abre un fichero o un URL
- proc_open() - Ejecuta un comando y abre los punteros de ficheros para las entradas / salidas

# readfile

(PHP 4, PHP 5, PHP 7, PHP 8)

readfile — Muestra un fichero

### Descripción

function readfile(string `$filename`, bool `$use_include_path` = `false`, ?resource `$context` = `null`): int|false

Lee un fichero y lo envía al buffer de salida.

### Parámetros

`filename`

  El fichero a leer.

`use_include_path`

  Puede utilizarse el segundo argumento opcional para explorar el directorio include_path, pasando el valor de `true`.

`context`
  Un resource de contexto de flujo.

### Valores devueltos

Devuelve el número de bytes leídos desde el fichero en caso de éxito, o `false` si ocurre un error

### Errores/Excepciones

En caso de fallo, se emitirá una advertencia de tipo `E_WARNING`.

### Ejemplos

Ejemplo #1 Forzar la descarga utilizando readfile()

    <?php
    $file = 'monkey.gif';

    if (file_exists($file)) {
        header('Content-Description: File Transfer');
        header('Content-Type: application/octet-stream');
        header('Content-Disposition: attachment; filename="'.basename($file).'"');
        header('Expires: 0');
        header('Cache-Control: must-revalidate');
        header('Pragma: public');
        header('Content-Length: ' . filesize($file));
        readfile($file);
        exit;
    }
    ?>

Resultado del ejemplo anterior es similar a:

### Notas

> Nota:

> readfile() no presentará problemas de memoria, incluso al enviar ficheros grandes. Si se encuentran este tipo de problemas, asegúrese de que el buffer de salida está desactivado con la función ob_get_level().

Sugerencia

Puede utilizar una URL como nombre de archivo con esta función, si el gestor fopen ha sido activado. Véase fopen() para más detalles sobre cómo especificar el nombre del archivo. Consulte Protocolos y Envolturas soportados para más información sobre las capacidades de los diferentes gestores, las notas sobre su uso, así como la información sobre las variables predefinidas que proporcionan.

### Ver también

- fpassthru() - Muestra el resto del fichero
- file() - Lee el fichero y devuelve el resultado en un array
- fopen() - Abre un fichero o un URL
- include - include
- require - require
- virtual() - Efectúa una subpetición Apache
- file_get_contents() - Lee todo un fichero en una cadena
- Protocolos y Envolturas soportados

# readlink

(PHP 4, PHP 5, PHP 7, PHP 8)

readlink — Devuelve el contenido de un enlace simbólico

### Descripción

function readlink(string `$path`): string|false

readlink() realiza la misma operación que la función C `readlink`.

### Parámetros

`path`

  La ruta hacia el enlace simbólico.

### Valores devueltos

Devuelve el contenido del enlace simbólico o `false` si ocurre un error.

> Nota: La función falla si el argumento `path` no es un enlace simbólico, excepto en Windows, donde se devolverá la ruta personalizada.

### Ejemplos

Ejemplo #1 Ejemplo con readlink()

    <?php

    // Muestra por ejemplo /boot/vmlinux-2.4.20-xfs
    echo readlink('/vmlinuz');

    ?>

### Ver también

- is_link() - Indica si el fichero es un enlace simbólico
- symlink() - Crea un enlace simbólico
- linkinfo() - Devuelve la información de un enlace

# realpath

(PHP 4, PHP 5, PHP 7, PHP 8)

realpath — Retorna la ruta de acceso canónica absoluta

### Descripción

function realpath(string `$path`): string|false

realpath() resuelve todos los enlaces simbólicos, y reemplaza todas las referencias `/./`, `/../` y `/` de `path` luego retorna la ruta de acceso canónica absoluta así encontrada.

### Parámetros

`path`

  La ruta de acceso a verificar.

  > Nota:

  > Debe ser proporcionada una ruta de acceso, el valor puede ser una cadena de caracteres vacía. En estos casos, el valor es interpretado como el directorio actual.

### Valores devueltos

Retorna la ruta de acceso canónica absoluta así encontrada. El resultado no contiene ningún enlace simbólico, `/./` o `/../`. Los delimitadores de fin como `\` y `/` son igualmente eliminados.

realpath() retorna `false` si ocurre un error, por ejemplo si el fichero no existe.

> Nota:

> El script que se ejecuta debe tener los permisos de ejecución sobre todos los directorios de la estructura, de lo contrario, la función realpath() retornará `false`.

> Nota:

> Para los sistemas de archivos insensibles a mayúsculas/minúsculas, realpath() puede o no normalizar la casilla de los caracteres.

> Nota:

> La función realpath() no funcionará para un fichero que se encuentra dentro de un phar ya que esta ruta sería una ruta de acceso virtual, no una real.

> Nota:

> En Windows, las uniones y los enlaces simbólicos a los directorios son únicamente extendidos a un nivel.

> Nota: Como el tipo entero de PHP es firmado y que muchas plataformas utilizan enteros de 32 bits, algunas funciones relacionadas con el sistema de archivos pueden retornar resultados extraños para archivos de tamaño superior a 2 Go.

### Ejemplos

Ejemplo #1 Ejemplo con realpath()

    <?php
    chdir('/var/www/');
    echo realpath('./../../etc/passwd') . PHP_EOL;

    echo realpath('/tmp/') . PHP_EOL;
    ?>

El ejemplo anterior mostrará:

    /etc/passwd
    /tmp

Ejemplo #2 Ejemplo con realpath() en Windows

En Windows, realpath() cambiará las rutas de estilo Unix a rutas de estilo Windows.

    <?php
    echo realpath('/windows/system32'), PHP_EOL;

    echo realpath('C:\Program Files\\'), PHP_EOL;
    ?>

El ejemplo anterior mostrará:

    C:\WINDOWS\System32
    C:\Program Files

### Ver también

- basename() - Devuelve el nombre del componente final de una ruta
- dirname() - Devuelve la ruta de la carpeta padre
- pathinfo() - Devuelve información sobre una ruta del sistema

# realpath_cache_get

(PHP 5 >= 5.3.2, PHP 7, PHP 8)

realpath_cache_get — Recupera las entradas del caché realpath

### Descripción

function realpath_cache_get(): array

Recupera las entradas del caché realpath.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array de entradas del caché realpath. Las claves son los caminos originales y los valores son arrays de datos que contienen el camino resuelto, la fecha de expiración y otros parámetros guardados en caché.

### Ejemplos

Ejemplo #1 Ejemplo con realpath_cache_get()

    <?php
    var_dump(realpath_cache_get());
    ?>

Resultado del ejemplo anterior es similar a:

    array(2) {
      ["/test"]=>
      array(4) {
        ["key"]=>
        int(123456789)
        ["is_dir"]=>
        bool(true)
        ["realpath"]=>
        string(5) "/test"
        ["expires"]=>
        int(1260318939)
      }
      ["/test/test.php"]=>
      array(4) {
        ["key"]=>
        int(987654321)
        ["is_dir"]=>
        bool(false)
        ["realpath"]=>
        string(12) "/root/test.php"
        ["expires"]=>
        int(1260318939)
      }
    }

### Ver también

- realpath_cache_size() - Obtiene el tamaño del caché realpath

# realpath_cache_size

(PHP 5 >= 5.3.2, PHP 7, PHP 8)

realpath_cache_size — Obtiene el tamaño del caché realpath

### Descripción

function realpath_cache_size(): int

Obtiene la cantidad de memoria utilizada por el caché realpath.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la cantidad de memoria utilizada por el caché realpath.

### Ejemplos

Ejemplo #1 Ejemplo con realpath_cache_size()

    <?php
    var_dump(realpath_cache_size());
    ?>

Resultado del ejemplo anterior es similar a:

    int(412)

### Ver también

- realpath_cache_get() - Recupera las entradas del caché realpath
- La opción de configuración realpath_cache_size

# rename

(PHP 4, PHP 5, PHP 7, PHP 8)

rename — Renombra un fichero o un directorio

### Descripción

function rename(string `$from`, string `$to`, ?resource `$context` = `null`): bool

Intenta renombrar `from` a `to`, moviéndolo de directorio si es necesario. Si se renombra un fichero y `to` existe, será sobrescrito. Si se renombra un directorio y `to` existe, esta función emite un aviso.

### Parámetros

`from`

  El nombre antiguo.

  > Nota:

  > El gestor utilizado en el argumento `from` DEBE ser el mismo que el utilizado en `to`.

`to`

  El nuevo nombre.

  > Nota: En Windows, si `to` ya existe, debe poder ser escrito. De lo contrario rename() falla y emite un `E_WARNING`.

`context`
  Un resource de contexto de flujo.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con rename()

    <?php
    rename("/tmp/tmp_file.txt", "/home/user/login/docs/my_file.txt");
    ?>

### Ver también

- copy() - Copia un fichero
- unlink() - Elimina un fichero
- move_uploaded_file() - Mueve un archivo subido a una nueva ubicación

# rewind

(PHP 4, PHP 5, PHP 7, PHP 8)

rewind — Reemplaza el puntero de fichero al inicio

### Descripción

function rewind(resource `$stream`): bool

Reemplaza el puntero de fichero `stream` al inicio del flujo.

> Nota:

> Si se ha abierto el fichero en modo de adición ("a" o "a+"), todos los datos que se escriban en este fichero serán siempre añadidos, sin importar la posición del puntero de fichero.

### Parámetros

`stream`

  El puntero de fichero debe ser válido y haber sido abierto correctamente por fopen().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con rewind()

    <?php
    $handle = fopen('output.txt', 'r+');

    fwrite($handle, 'Really long sentence.');
    rewind($handle);
    fwrite($handle, 'Foo');
    rewind($handle);

    echo fread($handle, filesize('output.txt'));

    fclose($handle);
    ?>

Resultado del ejemplo anterior es similar a:

    Foolly long sentence.

### Ver también

- fread() - Lectura del archivo en modo binario
- fseek() - Modifica la posición del puntero de archivo
- ftell() - Devuelve la posición actual del puntero de archivo
- fwrite() - Escribe en un fichero en modo binario

# rmdir

(PHP 4, PHP 5, PHP 7, PHP 8)

rmdir — Elimina un directorio

### Descripción

function rmdir(string `$directory`, ?resource `$context` = `null`): bool

Intenta eliminar el directorio cuyo camino es `directory`. El directorio debe estar vacío, y el script debe tener los permisos adecuados. Una advertencia de nivel `E_WARNING` será generada en caso de fallo.

### Parámetros

`directory`

  El camino hacia el directorio.

`context`
  Un resource de contexto de flujo.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con rmdir()

    <?php
    if (!is_dir('examples')) {
        mkdir('examples');
    }

    rmdir('examples');
    ?>

### Ver también

- is_dir() - Indica si el fichero es un directorio
- mkdir() - Crea un directorio
- unlink() - Elimina un fichero

# set_file_buffer

(PHP 4, PHP 5, PHP 7, PHP 8)

set_file_buffer — Alias de stream_set_write_buffer()

### Descripción

Esta función es un alias de: stream_set_write_buffer().

# stat

(PHP 4, PHP 5, PHP 7, PHP 8)

stat — Proporciona información sobre un fichero

### Descripción

function stat(string `$filename`): array|false

Proporciona información sobre el fichero `filename`. Si `filename` es un enlace simbólico, la información proviene del fichero en sí, y no del enlace simbólico. Antes de PHP 7.4.0, en Windows NTS compila los valores estáticos `size`, `atime`, `mtime` y `ctime` desde los enlaces simbólicos, en este caso.

lstat() es idéntico a stat() excepto que la información se basa en el enlace simbólico.

### Parámetros

`filename`

  La ruta al fichero.

### Valores devueltos

Formato del resultado de stat() y fstat()
Número | Nombre | Descripción
--- | --- | ---
0 | dev | volumen (***)
1 | ino | Número de inodo (****)
2 | mode | derechos de acceso al inodo *****
3 | nlink | número de enlaces
4 | uid | userid del propietario (*)
5 | gid | groupid del propietario (*)
6 | rdev | tipo de volumen, si el volumen es un inodo
7 | size | tamaño en bytes
8 | atime | fecha del último acceso (timestamp Unix)
9 | mtime | fecha de la última modificación (timestamp Unix)
10 | ctime | fecha del último cambio de inodo (timestamp Unix)
11 | blksize | tamaño de bloque (**)
12 | blocks | número de bloques de 512 bytes asignados (**)

* - En Windows, esto siempre será `0`.

** - Solo en sistemas que soportan el tipo `st_blksize`. Los otros sistemas (ej. Windows) devuelven `-1`.

*** - En Windows, desde PHP 7.4.0, será el número de serie del volumen que contiene el fichero, que será un entero 64-bit sin signo que puede desbordarse. Anteriormente, era la representación numérica de la letra del volumen (ej. `2` para `C:`) para la función stat(), y `0` para la función lstat().

**** - En Windows, desde PHP 7.4.0, es el identificador asociado con el fichero, que será un entero 64-bit sin signo que puede desbordarse. Anteriormente, siempre era `0`.

***** En Windows, el bit de permiso de escritura se define en función del atributo de solo lectura del fichero, y el mismo valor se reporta para todos los usuarios, grupo y propietario. El ACL no se tiene en cuenta, a diferencia de is_writable().

El valor de `mode` contiene información leída por varias funciones. Cuando se escribe en octal, comenzando por la derecha, los tres primeros dígitos son devueltos por chmod(). El siguiente dígito es ignorado por PHP. Los dos siguientes dígitos indican el tipo de fichero:

Los tipos de ficheros `mode`
`mode` en octal | Significado
--- | ---
`0140000` | socket
`0120000` | enlace simbólico
`0100000` | fichero regular
`0060000` | dispositivo de bloque
`0040000` | directorio
`0020000` | dispositivo de carácter
`0010000` | FIFO (un tubo nombrado)

Por ejemplo, un fichero regular podría ser `0100644` y un directorio podría `0040755`.

En caso de error, stat() devuelve `false`.

> Nota: Como el tipo entero de PHP es firmado y que muchas plataformas utilizan enteros de 32 bits, algunas funciones relacionadas con el sistema de archivos pueden retornar resultados extraños para archivos de tamaño superior a 2 Go.

### Errores/Excepciones

Si ocurre un error, se emite una advertencia de tipo `E_WARNING`.

### Historial de cambios

Versión | Descripción
--- | ---
7.4.0 | En Windows, el número del volumen es ahora el número de serie que contiene el fichero, y el número de inodo es el identificador asociado con el fichero.
7.4.0 | Los valores estáticos `size`, `atime`, `mtime` y `ctime` de los enlaces simbólicos son siempre los de la meta. Esto no era así previamente para los builds NTS en Windows.

### Ejemplos

Ejemplo #1 Ejemplo con stat()

    <?php
    /* Obtención de la información */
    $stat = stat('C:\php\php.exe');

    /*
     * Mostrar la fecha y hora del acceso a este fichero,
     * idéntico a la llamada a la función fileatime()
     */
    echo 'Fecha y hora de acceso : ' . $stat['atime'];

    /*
     * Mostrar la fecha y hora de modificación del fichero,
     * idéntico a la llamada a la función filemtime()
     */
    echo 'Fecha y hora de modificación : ' . $stat['mtime'];

    /* Mostrar el número del dispositivo */
    echo 'Número del dispositivo : ' . $stat['dev'];
    ?>

Ejemplo #2 Uso de la información obtenida de stat() junto con la función touch()

    <?php
    /* Obtención de la información de la función stat */
    $stat = stat('C:\php\php.exe');

    /* ¿Ha fallado el acceso a la información? */
    if (!$stat) {
        echo 'La llamada a stat() ha fallado...';
    } else {
        /*
         * Queremos que la fecha y hora de acceso sea una
         * semana después de la fecha actual.
         */
        $atime = $stat['atime'] + 604800;

        /* Modificamos el fichero */
        if(!touch('some_file.txt', time(), $atime)) {
            echo 'Fallo al llamar a la función touch()...';
        } else {
            echo 'La llamada a touch() ha tenido éxito...';
        }
    }
    ?>

### Notas

> Nota: Tenga en cuenta que la precisión temporal puede variar según el sistema de archivos utilizado.

> Nota: Los resultados de esta función se almacenan en caché. Véase la función clearstatcache() para más detalles.

Sugerencia

A partir de PHP 5.0.0, esta función también puede ser utilizada con algunos protocolos url. Lea Protocolos y Envolturas soportados para conocer los protocolos que soportan la familia de funcionalidades de stat().

### Ver también

- lstat() - Devuelve información sobre un fichero o un enlace simbólico
- fstat() - Lee las informaciones sobre un fichero a partir de un puntero de fichero
- filemtime() - Lee la fecha de última modificación del fichero
- filegroup() - Leer el nombre del grupo
- SplFileInfo

# symlink

(PHP 4, PHP 5, PHP 7, PHP 8)

symlink — Crea un enlace simbólico

### Descripción

function symlink(string `$target`, string `$link`): bool

symlink() crea un enlace simbólico para el objeto `target` con el nombre de `link`.

### Parámetros

`target`

  El objetivo del enlace.

`link`

  El nombre del enlace.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

La función falla, y emite una `E_WARNING`, si `link` ya existe. En Windows, esta función falla igualmente, y emite una `E_WARNING`, si `target` no existe.

### Ejemplos

Ejemplo #1 Creación de un enlace simbólico

    <?php
    $target = 'uploads.php';
    $link = 'uploads';
    symlink($target, $link);

    echo readlink($link);
    ?>

### Ver también

- is_link() - Indica si el fichero es un enlace simbólico
- link() - Crea un enlace
- readlink() - Devuelve el contenido de un enlace simbólico
- linkinfo() - Devuelve la información de un enlace
- unlink() - Elimina un fichero

# tempnam

(PHP 4, PHP 5, PHP 7, PHP 8)

tempnam — Crea un fichero con un nombre único

### Descripción

function tempnam(string `$directory`, string `$prefix`): string|false

Crea un fichero con un nombre único, con permisos de acceso 0600, en el directorio especificado. Si el directorio no existe o no es accesible en escritura, tempnam() intentará crear un fichero en el directorio temporal del sistema, y devolverá la ruta completa de dicho fichero, incluyendo su nombre.

### Parámetros

`directory`

  El directorio en el que se creará el fichero temporal.

`prefix`

  El prefijo del fichero temporal generado.

  > Nota: Solo se utilizan los 63 primeros caracteres del prefijo, el resto se ignora. Windows utiliza únicamente los 3 primeros caracteres del prefijo.

### Valores devueltos

Devuelve un nuevo fichero temporal (con su ruta), o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | El nombre de los archivos creados por tempnam() ahora es 13 bytes más largo. La longitud total sigue dependiendo de la plataforma.
7.1.0 | tempnam() ahora emite un aviso al recurrir al directorio temporal del sistema.

### Ejemplos

Ejemplo #1 Ejemplo con tempnam()

    <?php
    $tmpfname = tempnam("/tmp", "FOO");

    $handle = fopen($tmpfname, "w");
    fwrite($handle, "Escritura en el fichero temporal");
    fclose($handle);

    // procesamiento

    unlink($tmpfname);
    ?>

### Notas

> Nota: Si PHP no puede crear un fichero en el directorio especificado por el argumento `directory`, intentará hacerlo en el directorio por defecto del sistema. En sistemas de archivos NTFS, esto también ocurre si el directorio `directory` contiene más de 65534 ficheros.

### Ver también

- tmpfile() - Crea un fichero temporal
- sys_get_temp_dir() - Devuelve la ruta del directorio utilizado para los ficheros temporales
- unlink() - Elimina un fichero

# tmpfile

(PHP 4, PHP 5, PHP 7, PHP 8)

tmpfile — Crea un fichero temporal

### Descripción

function tmpfile(): resource|false

Crea un fichero temporal con un nombre único, abierto en escritura, lectura y binario (`w+b`), y devuelve un puntero de fichero.

Este fichero será automáticamente borrado cuando sea cerrado (por ejemplo, al llamar a la función fclose(), o cuando no haya más referencias al gestor de fichero devuelto por la función tmpfile()), o cuando el script finalice.

Precaución

Si el script termina de manera inesperada, es posible que el fichero temporal no sea eliminado.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un puntero de fichero, idéntico al devuelto por la función fopen(), para el nuevo fichero o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con tmpfile()

    <?php
    $temp = tmpfile();
    fwrite($temp, "Escritura en el fichero temporal");
    fseek($temp, 0);
    echo fread($temp, 1024);
    fclose($temp); // esto borrará el fichero
    ?>

El ejemplo anterior mostrará:

    Escritura en el fichero temporal

### Ver también

- tempnam() - Crea un fichero con un nombre único
- sys_get_temp_dir() - Devuelve la ruta del directorio utilizado para los ficheros temporales

# touch

(PHP 4, PHP 5, PHP 7, PHP 8)

touch — Modifica la fecha de modificación y de último acceso de un fichero

### Descripción

function touch(string `$filename`, ?int `$mtime` = `null`, ?int `$atime` = `null`): bool

Intenta forzar la fecha de modificación del fichero designado por el parámetro `filename` a la fecha especificada por el parámetro `mtime`. Tenga en cuenta que la fecha de último acceso se modifica, independientemente del número de argumentos.

Si el fichero no existe, PHP intentará crearlo.

### Parámetros

`filename`

  El nombre del fichero a crear.

`mtime`

  La fecha de creación. Si `mtime` es omitido, se utiliza la hora actual time().

`atime`

  Si no es `null`, la hora de acceso al fichero proporcionado se establecerá a la valor del parámetro `atime`. De lo contrario, se establecerá a la valor pasada al parámetro `mtime`. Si ambos son `null`, se utilizará la hora actual del sistema.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `mtime` y `atime` ahora son nullable.

### Ejemplos

Ejemplo #1 Ejemplo con touch()

    <?php
    if (touch($FileName)) {
        echo "La fecha de modificación de $FileName ha sido modificada a la fecha actual";
    } else {
        echo "Lo sentimos, no es posible cambiar la fecha de modificación de $FileName";
    }
    ?>

Ejemplo #2 Ejemplo con touch() utilizando el parámetro `mtime`

    <?php
    /*
     * Esta es la fecha y hora del último acceso, le añadimos 1 hora
     * en el pasado.
     */
    $time = time() - 3600;

    /* ¡Toquemos el fichero! */
    if (!touch('some_file.txt', $time)) {
        echo '¡Ups, ha ocurrido un error...';
    } else {
        echo 'La llamada a la función touch() ha tenido éxito';
    }
    ?>

### Notas

> Nota: Tenga en cuenta que la precisión temporal puede variar según el sistema de archivos utilizado.

# umask

(PHP 4, PHP 5, PHP 7, PHP 8)

umask — Cambia el "umask" actual

### Descripción

function umask(?int `$mask` = `null`): int

umask() cambia el umask de PHP y lo reemplaza por `mask`: `mask & 0777` y, a continuación, devuelve el viejo umask. Cuando PHP se utiliza como módulo de servidor, el umask recupera su valor al final de cada script.

### Parámetros

`mask`

  El nuevo umask.

### Valores devueltos

Si `mask` es `null`, umask() simplemente devuelve el umask actual de lo contrario se devuelve el antiguo umask.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `mask` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con umask()

    <?php
    $old = umask(0);
    chmod("/path/some_dir/some_file.txt", 0755);
    umask($old);

    // Verificación
    if ($old != umask()) {
        die('Ocurrió un error al modificar los permisos');
    }
    ?>

### Notas

> Nota:

> Evítese el uso de esta función en un servidor Web multithread. Es preferible cambiar los permisos de un directorio con la función chmod(), después de la creación del directorio. Al utilizar umask(), puede encontrarse con comportamientos indefinidos a nivel de otros scripts y del servidor, ya que todos utilizan el mismo umask.

# unlink

(PHP 4, PHP 5, PHP 7, PHP 8)

unlink — Elimina un fichero

### Descripción

function unlink(string `$filename`, ?resource `$context` = `null`): bool

Elimina `filename`. Similar a la función C Unix `unlink()`. En caso de error, se generará una advertencia de nivel `E_WARNING`.

### Parámetros

`filename`

  Ruta de acceso al fichero.

  Si el fichero es un enlace simbólico, se eliminará el enlace simbólico. En Windows, para eliminar un enlace simbólico a un directorio, debe utilizarse rmdir() en su lugar.

`context`
  Un resource de contexto de flujo.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
7.3.0 | En Windows, ahora es posible utilizar unlink() para eliminar ficheros cuyos gestores están en uso, lo cual antes fallaba. Sin embargo, aún no es posible recrear el fichero eliminado hasta que todos sus gestores sean cerrados.

### Ejemplos

Ejemplo #1 Ejemplo con unlink()

    <?php
    $fh = fopen('test.html', 'a');
    fwrite($fh, '<h1>Hello world!</h1>');
    fclose($fh);

    unlink('test.html');
    ?>

### Ver también

- rmdir() - Elimina un directorio

## Tabla de contenidos

- basename — Devuelve el nombre del componente final de una ruta
- chgrp — Cambia el grupo de un fichero
- chmod — Cambia el modo del fichero
- chown — Cambia el propietario del fichero
- clearstatcache — Elimina la caché de stat
- copy — Copia un fichero
- delete — Ver unlink o unset
- dirname — Devuelve la ruta de la carpeta padre
- disk_free_space — Devuelve el espacio en disco disponible en el sistema de archivos o partición
- disk_total_space — Devuelve el tamaño de un directorio o partición
- diskfreespace — Alias de disk_free_space
- fclose — Cierra un fichero
- fdatasync — Sincroniza los datos (pero no los metadatos) con el fichero
- feof — Prueba el final del archivo
- fflush — Envía todo el contenido generado en un fichero
- fgetc — Lee un carácter en un fichero
- fgetcsv — Obtiene una línea desde un puntero de archivo y la analiza para campos CSV
- fgets — Recupera la línea actual a partir de la posición del puntero de archivo
- fgetss — Obtiene un línea desde un puntero a un archivo y elimina las etiquetas HTML
- file — Lee el fichero y devuelve el resultado en un array
- file_exists — Verifica si un fichero o un directorio existe
- file_get_contents — Lee todo un fichero en una cadena
- file_put_contents — Escribe datos en un fichero
- fileatime — Devuelve la fecha en la que el fichero fue accedido por última vez
- filectime — Devuelve la fecha de última modificación del inodo de un fichero
- filegroup — Leer el nombre del grupo
- fileinode — Lee el número de inodo del fichero
- filemtime — Lee la fecha de última modificación del fichero
- fileowner — Lee el identificador del propietario de un fichero
- fileperms — Lee los permisos de un fichero
- filesize — Obtiene el tamaño de un fichero
- filetype — Devuelve el tipo de fichero
- flock — Bloqueo de ficheros portátil y consultivo
- fnmatch — Prueba un nombre de fichero mediante un patrón de búsqueda
- fopen — Abre un fichero o un URL
- fpassthru — Muestra el resto del fichero
- fputcsv — Formatea una línea en CSV y la escribe en un fichero
- fputs — Alias de fwrite
- fread — Lectura del archivo en modo binario
- fscanf — Analiza un archivo según un formato
- fseek — Modifica la posición del puntero de archivo
- fstat — Lee las informaciones sobre un fichero a partir de un puntero de fichero
- fsync — Sincroniza los cambios realizados en el fichero (incluyendo los metadatos)
- ftell — Devuelve la posición actual del puntero de archivo
- ftruncate — Tronca un fichero
- fwrite — Escribe en un fichero en modo binario
- glob — Búsqueda de rutas que coinciden con un patrón
- is_dir — Indica si el fichero es un directorio
- is_executable — Indica si el fichero es ejecutable
- is_file — Indica si el fichero es un fichero verdadero
- is_link — Indica si el fichero es un enlace simbólico
- is_readable — Indica si un fichero existe y es accesible en lectura
- is_uploaded_file — Indica si el archivo fue subido mediante HTTP POST
- is_writable — Indica si un fichero es accesible en escritura
- is_writeable — Alias de is_writable
- lchgrp — Cambiar la pertenencia al grupo de un enlace simbólico
- lchown — Cambia el propietario de un enlace simbólico
- link — Crea un enlace
- linkinfo — Devuelve la información de un enlace
- lstat — Devuelve información sobre un fichero o un enlace simbólico
- mkdir — Crea un directorio
- move_uploaded_file — Mueve un archivo subido a una nueva ubicación
- parse_ini_file — Analiza un archivo de configuración
- parse_ini_string — Analiza una cadena de configuración
- pathinfo — Devuelve información sobre una ruta del sistema
- pclose — Cierra un proceso de un puntero a un fichero
- popen — Crea un puntero de archivo de proceso
- readfile — Muestra un fichero
- readlink — Devuelve el contenido de un enlace simbólico
- realpath — Retorna la ruta de acceso canónica absoluta
- realpath_cache_get — Recupera las entradas del caché realpath
- realpath_cache_size — Obtiene el tamaño del caché realpath
- rename — Renombra un fichero o un directorio
- rewind — Reemplaza el puntero de fichero al inicio
- rmdir — Elimina un directorio
- set_file_buffer — Alias de stream_set_write_buffer
- stat — Proporciona información sobre un fichero
- symlink — Crea un enlace simbólico
- tempnam — Crea un fichero con un nombre único
- tmpfile — Crea un fichero temporal
- touch — Modifica la fecha de modificación y de último acceso de un fichero
- umask — Cambia el "umask" actual
- unlink — Elimina un fichero

- Instalación/Configuración
  - Configuración en tiempo de ejecución
  - Tipos de recursos
- Constantes predefinidas
- Funciones del Sistema de Archivos
  - basename — Devuelve el nombre del componente final de una ruta
  - chgrp — Cambia el grupo de un fichero
  - chmod — Cambia el modo del fichero
  - chown — Cambia el propietario del fichero
  - clearstatcache — Elimina la caché de stat
  - copy — Copia un fichero
  - delete — Ver unlink o unset
  - dirname — Devuelve la ruta de la carpeta padre
  - disk_free_space — Devuelve el espacio en disco disponible en el sistema de archivos o partición
  - disk_total_space — Devuelve el tamaño de un directorio o partición
  - diskfreespace — Alias de disk_free_space
  - fclose — Cierra un fichero
  - fdatasync — Sincroniza los datos (pero no los metadatos) con el fichero
  - feof — Prueba el final del archivo
  - fflush — Envía todo el contenido generado en un fichero
  - fgetc — Lee un carácter en un fichero
  - fgetcsv — Obtiene una línea desde un puntero de archivo y la analiza para campos CSV
  - fgets — Recupera la línea actual a partir de la posición del puntero de archivo
  - fgetss — Obtiene un línea desde un puntero a un archivo y elimina las etiquetas HTML
  - file — Lee el fichero y devuelve el resultado en un array
  - file_exists — Verifica si un fichero o un directorio existe
  - file_get_contents — Lee todo un fichero en una cadena
  - file_put_contents — Escribe datos en un fichero
  - fileatime — Devuelve la fecha en la que el fichero fue accedido por última vez
  - filectime — Devuelve la fecha de última modificación del inodo de un fichero
  - filegroup — Leer el nombre del grupo
  - fileinode — Lee el número de inodo del fichero
  - filemtime — Lee la fecha de última modificación del fichero
  - fileowner — Lee el identificador del propietario de un fichero
  - fileperms — Lee los permisos de un fichero
  - filesize — Obtiene el tamaño de un fichero
  - filetype — Devuelve el tipo de fichero
  - flock — Bloqueo de ficheros portátil y consultivo
  - fnmatch — Prueba un nombre de fichero mediante un patrón de búsqueda
  - fopen — Abre un fichero o un URL
  - fpassthru — Muestra el resto del fichero
  - fputcsv — Formatea una línea en CSV y la escribe en un fichero
  - fputs — Alias de fwrite
  - fread — Lectura del archivo en modo binario
  - fscanf — Analiza un archivo según un formato
  - fseek — Modifica la posición del puntero de archivo
  - fstat — Lee las informaciones sobre un fichero a partir de un puntero de fichero
  - fsync — Sincroniza los cambios realizados en el fichero (incluyendo los metadatos)
  - ftell — Devuelve la posición actual del puntero de archivo
  - ftruncate — Tronca un fichero
  - fwrite — Escribe en un fichero en modo binario
  - glob — Búsqueda de rutas que coinciden con un patrón
  - is_dir — Indica si el fichero es un directorio
  - is_executable — Indica si el fichero es ejecutable
  - is_file — Indica si el fichero es un fichero verdadero
  - is_link — Indica si el fichero es un enlace simbólico
  - is_readable — Indica si un fichero existe y es accesible en lectura
  - is_uploaded_file — Indica si el archivo fue subido mediante HTTP POST
  - is_writable — Indica si un fichero es accesible en escritura
  - is_writeable — Alias de is_writable
  - lchgrp — Cambiar la pertenencia al grupo de un enlace simbólico
  - lchown — Cambia el propietario de un enlace simbólico
  - link — Crea un enlace
  - linkinfo — Devuelve la información de un enlace
  - lstat — Devuelve información sobre un fichero o un enlace simbólico
  - mkdir — Crea un directorio
  - move_uploaded_file — Mueve un archivo subido a una nueva ubicación
  - parse_ini_file — Analiza un archivo de configuración
  - parse_ini_string — Analiza una cadena de configuración
  - pathinfo — Devuelve información sobre una ruta del sistema
  - pclose — Cierra un proceso de un puntero a un fichero
  - popen — Crea un puntero de archivo de proceso
  - readfile — Muestra un fichero
  - readlink — Devuelve el contenido de un enlace simbólico
  - realpath — Retorna la ruta de acceso canónica absoluta
  - realpath_cache_get — Recupera las entradas del caché realpath
  - realpath_cache_size — Obtiene el tamaño del caché realpath
  - rename — Renombra un fichero o un directorio
  - rewind — Reemplaza el puntero de fichero al inicio
  - rmdir — Elimina un directorio
  - set_file_buffer — Alias de stream_set_write_buffer
  - stat — Proporciona información sobre un fichero
  - symlink — Crea un enlace simbólico
  - tempnam — Crea un fichero con un nombre único
  - tmpfile — Crea un fichero temporal
  - touch — Modifica la fecha de modificación y de último acceso de un fichero
  - umask — Cambia el "umask" actual
  - unlink — Elimina un fichero

# Inotify

# Introducción

La extensión inotify expone las funciones inotify inotify_init(), inotify_add_watch() e inotify_rm_watch().

Así como la función inotify_init() de C devuelve un file descriptor, inotify_init() de PHP devuelve un recurso de flujo, que puede ser usado con las funciones de flujo estándar, como stream_select(), stream_set_blocking() y fclose(). inotify_read() sustituye la manera C de leer eventos inotify.

# Instalación/Configuración

## Tabla de contenidos

- Instalación/Configuración
- Tipos de recursos

## Instalación/Configuración

Esta extensión » PECL no está integrada en PHP.

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/inotify.

## Tipos de recursos

Esta extensión define un flujo de datos, retornado por inotify_init().

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

Constantes Inotify utilizables con inotify_add_watch() y/o devueltos por inotify_read()
`IN_ACCESS` (int)
  El fichero fue accedido (lectura) (*)
`IN_MODIFY` (int)
  El fichero fue modificado (*)
`IN_ATTRIB` (int)
  Metadatos cambiados (por ejemplo: permisos, mtime, etc) (*)
`IN_CLOSE_WRITE` (int)
  El fichero, previamente abierto para escritura, fue cerrado (*)
`IN_CLOSE_NOWRITE` (int)
  El fichero, no abierto para escritura, fue cerrado (*)
`IN_OPEN` (int)
  El fichero fue abierto (*)
`IN_MOVED_TO` (int)
  Un fichero fue movido dentro del directorio observado (*)
`IN_MOVED_FROM` (int)
  Un fichero fue movido fuera del directorio observado (*)
`IN_CREATE` (int)
  Un fichero o directorio fue creado en el directorio observado (*)
`IN_DELETE` (int)
  Fichero o directorio borrado en el directorio observado (*)
`IN_DELETE_SELF` (int)
  El fichero o directorio observado fue borrado
`IN_MOVE_SELF` (int)
  El fichero o directorio observado fue movido
`IN_CLOSE` (int)
  Similar a IN_CLOSE_WRITE | IN_CLOSE_NOWRITE
`IN_MOVE` (int)
  Similar a IN_MOVED_FROM | IN_MOVED_TO
`IN_ALL_EVENTS` (int)
  Máscara de bits de todas las constantes anteriores
`IN_UNMOUNT` (int)
  Sistema de ficheros que contiene objetos observados fue desmontado
`IN_Q_OVERFLOW` (int)
  Cola de eventos desbordada (wd es -1 para este evento)
`IN_IGNORED` (int)
  Seguimiento borrado (explicitamente indicado por inotify_rm_watch() o debido a que el fichero fue eliminado o el sistema de ficheros desmontado)
`IN_ISDIR` (int)
  El sujeto del evento es un directorio
`IN_ONLYDIR` (int)
  Observar la ruta solamente si se trata de un directorio (A partir de Linux 2.6.15)
`IN_DONT_FOLLOW` (int)
  No eliminar la ruta de referencia si es un enlace simbólico (A partir de Linux 2.6.15).
`IN_MASK_ADD` (int)
  Agregar eventos para observar la máscara de esta ruta de acceso si ya existe (en lugar de reemplazar la máscara).
`IN_ONESHOT` (int)
  Monitorea una ruta para un evento, a continuación elimina de la lista de vigilancia.

> Nota: Los eventos más arriba marcados con un asterisco (*) pueden producirse para ficheros en directorios observados.

# Funciones Inotify

# inotify_add_watch

(PECL inotify >= 0.1.2)

inotify_add_watch — Añade un punto de vigilancia a una instancia inotify

### Descripción

function inotify_add_watch(resource `$inotify_instance`, string `$pathname`, int `$mask`): int|false

inotify_add_watch() añade un punto de vigilancia a una instancia inotify o modifica un punto de vigilancia en curso hacia un nuevo fichero o directorio especificado por la ruta `pathname`.

Utilizar inotify_add_watch() sobre un objeto ya en vigilancia modifica la configuración. Utilizar la constante `IN_MASK_ADD` añade los eventos (operación OR lógica).

### Parámetros

`inotify_instance`
  Recurso retornado por inotify_init()
`pathname`
  Fichero o directorio a vigilar.
`mask`
  Eventos a vigilar. Véase Constantes predefinidas.

### Valores devueltos

El valor devuelto es un puntero inotify único (inotify instance wide), o `false` si ocurre un error.

### Ver también

- inotify_init() - Inicializa una instancia inotify

# inotify_init

(PECL inotify >= 0.1.2)

inotify_init — Inicializa una instancia inotify

### Descripción

function inotify_init(): resource|false

Inicializa una instancia inotify para ser utilizada con la función inotify_add_watch()

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un flujo o `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo de utilización de inotify

    <?php
    // Crea una instancia inotify
    $fd = inotify_init();

    // Vigila las modificaciones de los metadatos del fichero __FILE__ (e.g. mtime)
    $watch_descriptor = inotify_add_watch($fd, __FILE__, IN_ATTRIB);

    // Genera un evento
    touch(__FILE__);

    // Lee los eventos
    $events = inotify_read($fd);
    print_r($events);

    // Los métodos siguientes permiten utilizar las funciones inotify sin bloquear sobre inotify_read():

    // - Utilizar stream_select() sobre $fd:
    $read = array($fd);
    $write = null;
    $except = null;
    stream_select($read,$write,$except,0);

    // - Utilizar stream_set_blocking() sobre $fd
    stream_set_blocking($fd, 0);
    inotify_read($fd); // No bloquea, y devuelve false si no hay eventos pendientes

    // - Utilizar inotify_queue_len() para verificar el tamaño de la cola
    $queue_len = inotify_queue_len($fd); // Si > 0, inotify_read() no bloqueará

    // Detener la vigilancia de __FILE__
    inotify_rm_watch($fd, $watch_descriptor);

    // Destrucción de la instancia inotify
    // Esto habría detenido todas las vigilancias si no se hubiera hecho ya
    fclose($fd);

    ?>

Resultado del ejemplo anterior es similar a:

    array(
      array(
        'wd' => 1,     // Igual al $watch_descriptor
        'mask' => 4,   // El bit IN_ATTRIB está activado
        'cookie' => 0, // Identificador único para vincular eventos (e.g.
                       // IN_MOVE_FROM y IN_MOVE_TO)
        'name' => '',  // El nombre del fichero (e.g. si un directorio estaba bajo vigilancia)
      ),
    );

### Ver también

- inotify_add_watch() - Añade un punto de vigilancia a una instancia inotify
- inotify_rm_watch() - Elimina un seguimiento existente de una instancia inotify
- inotify_queue_len() - Devuelve un número superior a cero si hay eventos pendientes
- inotify_read() - Lee eventos de una instancia inotify
- fclose() - Cierra un fichero

# inotify_queue_len

(PECL inotify >= 0.1.2)

inotify_queue_len — Devuelve un número superior a cero si hay eventos pendientes

### Descripción

function inotify_queue_len(resource `$inotify_instance`): int

Esta función permite saber si inotify_read() bloqueará o no. Si un número superior a cero es devuelto, hay eventos pendientes e inotify_read() no bloqueará.

### Parámetros

`inotify_instance`
  Recurso retornado por inotify_init()

### Valores devueltos

Devuelve un número superior a cero si hay eventos pendientes.

### Ver también

- inotify_init() - Inicializa una instancia inotify
- stream_select() - Supervisa la modificación de uno o varios flujos
- stream_set_blocking() - Configura el modo de bloqueo de un flujo

# inotify_read

(PECL inotify >= 0.1.2)

inotify_read — Lee eventos de una instancia inotify

### Descripción

function inotify_read(resource `$inotify_instance`): array

Leer eventos inotify de una instancia inotify.

### Parámetros

`inotify_instance`
  Recurso retornado por inotify_init()

### Valores devueltos

Un array de eventos inotify o `false` si no hay eventos pendientes e `inotify_instance` no es de bloqueo. Cada evento es un array con las siguientes claves:

- wd es un descriptor de seguimiento devuelto por inotify_add_watch()
- mask es una máscara de bits de eventos
- cookie es un identificador único para conectar los eventos relacionados (por ejemplo: `IN_MOVE_FROM` e `IN_MOVE_TO`)
- name es el nombre de un fichero (por ejemplo: si un fichero se ha modificado en un directorio observado)

### Ver también

- inotify_init() - Inicializa una instancia inotify
- stream_select() - Supervisa la modificación de uno o varios flujos
- stream_set_blocking() - Configura el modo de bloqueo de un flujo
- inotify_queue_len() - Devuelve un número superior a cero si hay eventos pendientes

# inotify_rm_watch

(PECL inotify >= 0.1.2)

inotify_rm_watch — Elimina un seguimiento existente de una instancia inotify

### Descripción

function inotify_rm_watch(resource `$inotify_instance`, int `$watch_descriptor`): bool

inotify_rm_watch() elimina el seguimiento `watch_descriptor` de la instancia inotify `inotify_instance`.

### Parámetros

`inotify_instance`
  Recurso retornado por inotify_init()
`watch_descriptor`
  Seguimiento a eliminar de la instancia

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- inotify_init() - Inicializa una instancia inotify

## Tabla de contenidos

- inotify_add_watch — Añade un punto de vigilancia a una instancia inotify
- inotify_init — Inicializa una instancia inotify
- inotify_queue_len — Devuelve un número superior a cero si hay eventos pendientes
- inotify_read — Lee eventos de una instancia inotify
- inotify_rm_watch — Elimina un seguimiento existente de una instancia inotify

- Instalación/Configuración
  - Instalación/Configuración
  - Tipos de recursos
- Constantes predefinidas
- Funciones Inotify
  - inotify_add_watch — Añade un punto de vigilancia a una instancia inotify
  - inotify_init — Inicializa una instancia inotify
  - inotify_queue_len — Devuelve un número superior a cero si hay eventos pendientes
  - inotify_read — Lee eventos de una instancia inotify
  - inotify_rm_watch — Elimina un seguimiento existente de una instancia inotify

# xattr

# Introducción

La extensión xattr permite la manipulación de los atributos extendidos de un sistema de archivos.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación

## Requerimientos

Para utilizar xattr, se necesita tener libattr instalado. Este está disponible en » http://savannah.nongnu.org/projects/attr/.

> Nota:

> Estas funciones sólo funcionan en sistemas de archivos que soportan atributos extendidos, y haya activado durante la instalación. Algunos sistemas de ficheros comunes que soportan atributos extendidos son `ext2`, `ext3`, `reiserfs`, `jfs`, y `xfs`.

## Instalación

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/xattr.

No hay biblioteca DLL para esta extensión PECL actualmente disponible. Consulte la sección Compilación en Windows.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`XATTR_ROOT` (int)
  Establece atributos en la raíz (segura) de espacio de nombres. Requiere privilegios de administrador.
`XATTR_DONTFOLLOW` (int)
  No sigue el enlace simbólico pero se puede operar en este.
`XATTR_CREATE` (int)
  La función falla si el atributo extendido ya existe.
`XATTR_REPLACE` (int)
  La función falla si el atributo extendido no existe.

# Funciones de xattr

# xattr_get

(PECL xattr >= 0.9.0)

xattr_get — Obtener un atributo extendido

### Descripción

function xattr_get(string `$filename`, string `$name`, int `$flags` = 0): string|false

Esta función obtiene el valor de un atributo extendido del archivo.

Los atributos extendidos tienen dos espacios de nombres diferentes: `user` y `root`. El espacio de nombres `user` está disponible para todos los usuarios mientras que el espacio de nombres `root` solo está disponible para los usuarios con privilegios `root`. xattr opera sobre el espacio de nombres `user` por defecto, pero esto puede ser cambiado utilizando el argumento `flags`.

### Parámetros

`filename`

  El archivo de la cual obtenemos el atributo.

`name`

  El nombre del atributo.

`flags`

  Banderas xattr soportadas
  `XATTR_DONTFOLLOW` | No sigue el enlace simbólico pero se puede operar en este.
  `XATTR_ROOT` | Establece atributos en la raíz (segura) de espacio de nombres. Requiere privilegios de administrador.

### Valores devueltos

Devuelve un string que contiene el valor o `false` si el atributo no existe.

### Ejemplos

Ejemplo #1 Comprueba si el administrador del sistema firmó el archivo

    <?php
    $file = '/usr/local/sbin/some_binary';
    $firma = xattr_get($file, 'Root signature', XATTR_ROOT);

    /* ... Comprobar si la $firma es válida ... */

    ?>

### Ver también

- xattr_list() - Obtener una lista de atributos extendidos
- xattr_set() - Establece un atributo extendido
- xattr_remove() - Elimina un atributo extendido

# xattr_list

(PECL xattr >= 0.9.0)

xattr_list — Obtener una lista de atributos extendidos

### Descripción

function xattr_list(string `$filename`, int `$flags` = 0): array

Esta función obtiene una lista de nombres de los atributos extendidos de un archivo.

Los atributos extendidos tienen dos espacios de nombres diferentes: `user` y `root`. El espacio de nombres `user` está disponible para todos los usuarios mientras que el espacio de nombres `root` solo está disponible para los usuarios con privilegios `root`. xattr opera sobre el espacio de nombres `user` por defecto, pero esto puede ser cambiado utilizando el argumento `flags`.

### Parámetros

`filename`

  La ruta del archivo.

`flags`

  Banderas xattr soportadas
  `XATTR_DONTFOLLOW` | No sigue el enlace simbólico pero se puede operar en este.
  `XATTR_ROOT` | Establece atributos en la raíz (segura) de espacio de nombres. Requiere privilegios de administrador.

### Valores devueltos

Esta función devuelve un array con los nombres de los atributos extendidos.

### Ejemplos

Ejemplo #1 Imprime los nombres de todos los atributos extendidos del archivo

    <?php
    $file = 'some_file';
    $root_attributes = xattr_list($file, XATTR_ROOT);
    $user_attributes = xattr_list($file);

    echo "Atributos Root: \n";
    foreach ($root_attributes as $attr_name) {
        printf("%s\n", $attr_name);
    }

    echo "\n Atributos usuario: \n";
    foreach ($user_attributes as $attr_name) {
        printf("%s\n", $attr_name);
    }

    ?>

### Ver también

- xattr_get() - Obtener un atributo extendido

# xattr_remove

(PECL xattr >= 0.9.0)

xattr_remove — Elimina un atributo extendido

### Descripción

function xattr_remove(string `$filename`, string `$name`, int `$flags` = 0): bool

Esta función elimina un atributo extendido del archivo.

Los atributos extendidos tienen dos espacios de nombres diferentes: `user` y `root`. El espacio de nombres `user` está disponible para todos los usuarios mientras que el espacio de nombres `root` solo está disponible para los usuarios con privilegios `root`. xattr opera sobre el espacio de nombres `user` por defecto, pero esto puede ser cambiado utilizando el argumento `flags`.

### Parámetros

`filename`

  El archivo del que se elimina el atributo.

`name`

  El nombre del atributo a eliminar.

`flags`

  Banderas xattr soportadas
  `XATTR_DONTFOLLOW` | No sigue el enlace simbólico pero se puede operar en este.
  `XATTR_ROOT` | Establece atributos en la raíz (segura) de espacio de nombres. Requiere privilegios de administrador.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Elimina todos los atributos extendidos de un archivo

    <?php
    $file = 'some_file';
    $attributes = xattr_list($file);

    foreach ($attributes as $attr_name) {
        xattr_remove($file, $attr_name);
    }
    ?>

### Ver también

- xattr_list() - Obtener una lista de atributos extendidos
- xattr_set() - Establece un atributo extendido
- xattr_get() - Obtener un atributo extendido

# xattr_set

(PECL xattr >= 0.9.0)

xattr_set — Establece un atributo extendido

### Descripción

function xattr_set(
string `$filename`,
string `$name`,
string `$value`,
int `$flags` = 0
): bool

Esta función establece el valor de un atributo extendido del archivo.

Los atributos extendidos tienen dos espacios de nombres diferentes: `user` y `root`. El espacio de nombres `user` está disponible para todos los usuarios mientras que el espacio de nombres `root` solo está disponible para los usuarios con privilegios `root`. xattr opera sobre el espacio de nombres `user` por defecto, pero esto puede ser cambiado utilizando el argumento `flags`.

### Parámetros

`filename`

  El archivo en el que se establece el atributo.

`name`

  El nombre del atributo extendido. Este atributo se crea si no existe o reemplazado si ya existe. Puede cambiar este comportamiento mediante el uso de los parámetros `flags`.

`value`

  El valor del atributo.

`flags`

  Banderas xattr soportadas
  `XATTR_CREATE` | La función falla si el atributo extendido ya existe.
  `XATTR_REPLACE` | La función falla si el atributo extendido no existe.
  `XATTR_DONTFOLLOW` | No sigue el enlace simbólico pero se puede operar en este.
  `XATTR_ROOT` | Establece atributos en la raíz (segura) de espacio de nombres. Requiere privilegios de administrador.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Establece atributos extendidos en archivo .wav

    <?php
    $file = 'my_favourite_song.wav';
    xattr_set($file, 'Artist', 'Someone');
    xattr_set($file, 'My ranking', 'Good');
    xattr_set($file, 'Listen count', '34');

    /* ... other code ... */

    printf("You've played this song %d times", xattr_get($file, 'Listen count'));
    ?>

### Ver también

- xattr_get() - Obtener un atributo extendido
- xattr_remove() - Elimina un atributo extendido

# xattr_supported

(PECL xattr >= 1.0.0)

xattr_supported — Comprueba si soporta los atributos extendidos del sistema de archivos

### Descripción

function xattr_supported(string `$filename`, int `$flags` = 0): bool

Esta función comprueba si el sistema de archivos que contenía el fichero dado soporta los atributos extendidos. Es necesario tener acceso de lectura al archivo.

### Parámetros

`filename`

  La ruta del archivo de prueba.

`flags`

  Banderas xattr soportadas
  `XATTR_DONTFOLLOW` | No sigue el enlace simbólico pero se puede operar en este.

### Valores devueltos

Esta función devuelve `true` si sistema de archivo soporta los atributos extendidos, `false` si no soporta y `null` si no se puede determinar (Por ejemplo ruta incorrecta o le faltan permisos al archivo).

### Ejemplos

Ejemplo #1 Ejemplo de xattr_supported()

El siguiente código comprueba si se pueden utilizar los atributos extendidos.

    <?php
    $file = 'some_file';

    if (xattr_supported($file)) {
        /* ... make use of some xattr_* functions ... */
    }

    ?>

### Ver también

- xattr_get() - Obtener un atributo extendido
- xattr_list() - Obtener una lista de atributos extendidos

## Tabla de contenidos

- xattr_get — Obtener un atributo extendido
- xattr_list — Obtener una lista de atributos extendidos
- xattr_remove — Elimina un atributo extendido
- xattr_set — Establece un atributo extendido
- xattr_supported — Comprueba si soporta los atributos extendidos del sistema de archivos

- Instalación/Configuración
  - Requerimientos
  - Instalación
- Constantes predefinidas
- Funciones de xattr
  - xattr_get — Obtener un atributo extendido
  - xattr_list — Obtener una lista de atributos extendidos
  - xattr_remove — Elimina un atributo extendido
  - xattr_set — Establece un atributo extendido
  - xattr_supported — Comprueba si soporta los atributos extendidos del sistema de archivos

# xdiff

# Introducción

La extensión xdiff permite crear y aplicar archivos parche que contienen diferencias entre diferentes revisiones de archivos.

Esta extensión soporta dos modos de funcionamiento - sobre cadenas y sobre archivos, así como dos formatos de parches diferentes - unificado y binario. Los parches unificados son excelentes para archivos de texto, ya que son legibles y fáciles de revisar. Para los archivos binarios como archivos o imágenes, los parches binarios serán la opción adecuada, ya que ellos son binary safe y manejan caracteres no imprimibles.

A partir de la versión 1.5.0 hay dos diferentes conjuntos de funciones para la generación de parches binarios. Las nuevas funciones - xdiff_string_rabdiff() xdiff_file_rabdiff() generan salidas compatibles con funciones más antiguas pero suelen ser más rápidas y generan resultados más pequeños. Para más detalles sobre los métodos de la generación de parches binarios y diferencias entre ellos, por favor consulte el sitio web » libxdiff.

Esta extensión utiliza libxdiff para implementar estas funciones. Consulte » http://www.xmailserver.org/xdiff-lib.html para mayor información.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación

## Requerimientos

Para usar xdiff, es necesario contar con libxdiff instalado, disponible en la web de libxdiff » http://www.xmailserver.org/xdiff-lib.html.

> Nota:

> Para que estas funciones tengan en cuenta la directiva memory_limit es necesario contar con, al menos, libxdiff 0.7.

## Instalación

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/xdiff.

Los binarios Windows (los archivos DLL) para esta extensión PECL están disponibles en el sitio web PECL.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`XDIFF_PATCH_NORMAL` (int)
  Este indicador indica que las funciones xdiff_string_patch() y xdiff_file_patch() deben crear el resultado de aplicar el parche al contenido original, creando así una versión más reciente del archivo. Este es el modo por defecto de funcionamiento.
`XDIFF_PATCH_REVERSE` (int)
  Este indicador indica que las funciones xdiff_string_patch() y xdiff_file_patch() deben crear el resultado de revertir el parche de modificación desde el nuevo contenido, creando así la versión original.

# Funciones de xdiff

# xdiff_file_bdiff

(PECL xdiff >= 1.5.0)

xdiff_file_bdiff — Realiza una diferencia binaria de dos archivos

### Descripción

function xdiff_file_bdiff(string `$old_file`, string `$new_file`, string `$dest`): bool

Hace una diferencia binaria de dos archivos y almacena el resultado en un archivo de revisión. Esta función trabaja con archivos de texto y binarios. El archivo parche resultante puede ser aplicado posteriormente utilizando xdiff_file_bpatch()/xdiff_string_bpatch().

### Parámetros

`old_file`

  Ruta a el primer archivo. Este archivo actúa como "viejo" archivo.

`new_file`

  Ruta a el segundo archivo. Este archivo actúa como "nuevo" archivo.

`dest`

  Ruta de el archivo parche resultante. El archivo resultante contiene diferencias entre los archivos "viejo" y "nuevo". Este será en formato binario y no leible por humanos.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de xdiff_file_bdiff()

El siguiente código hace una diferencia binaria de dos archivos.

    <?php
    $old_version = 'my_script_1.0.tgz';
    $new_version = 'my_script_1.1.tgz';

    xdiff_file_bdiff($old_version, $new_version, 'my_script.bdiff');
    ?>

### Notas

> Nota:

> Ambos archivos serán cargados en memoria así que asegúrese que el valor de memory_limit es lo suficientemente alto.

### Ver también

- xdiff_file_bpatch() - Parchea un archivo con una diferencia binaria

# xdiff_file_bdiff_size

(PECL xdiff >= 1.5.0)

xdiff_file_bdiff_size — Lee el tamaño de un archivo creado tras aplicar una diferencia binaria

### Descripción

function xdiff_file_bdiff_size(string `$file`): int

Devuelve el tamaño de un archivo resultado que se creó después de aplicar el parche binario desde el archivo `file` a el archivo original.

### Parámetros

`file`

  La ruta al parche binario creado por la función xdiff_string_bdiff() o xdiff_string_rabdiff().

### Valores devueltos

Devuelve el tamaño del archivo que se creará.

### Ejemplos

Ejemplo #1 Ejemplo de xdiff_file_bdiff_size()

El siguiente código lee el tamaño de un archivo que se creará tras realizar una diferencia binaria.

    <?php
    $length = xdiff_string_bdiff_size('file.bdiff');
    echo "El archivo resultante tendrá $length bytes de longitud";
    ?>

### Ver también

- xdiff_file_bdiff() - Realiza una diferencia binaria de dos archivos
- xdiff_file_rabdiff() - Hacer una diferencia binaria de dos archivos utilizando el algoritmo polinomial de huella digital (fingerprinting) de Rabin
- xdiff_file_bpatch() - Parchea un archivo con una diferencia binaria

# xdiff_file_bpatch

(PECL xdiff >= 1.5.0)

xdiff_file_bpatch — Parchea un archivo con una diferencia binaria

### Descripción

function xdiff_file_bpatch(string `$file`, string `$patch`, string `$dest`): bool

Parchea un `file` con un `patch` binario y almacena el resultado en un archivo `dest`. Esta función acepta parches creados tanto a través de la funciones xdiff_file_bdiff() y xdiff_file_rabdiff() como de sus equivalentes de cadena.

### Parámetros

`file`

  El archivo original.

`patch`

  El archivo parche binario.

`dest`

  La ruta del archivo resultante.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de xdiff_file_bpatch()

El siguiente código aplica una diferencia binaria a un archivo.

    <?php
    $old_version = 'archive-1.0.tgz';
    $patch = 'archive.bpatch';

    $result = xdiff_file_bpatch($old_version, $patch, 'archive-1.1.tgz');
    if ($result) {
       echo "Archivo parcheado";
    } else {
       echo "El archivo no pudo ser parcheado";
    }

    ?>

### Notas

> Nota:

> Ambos archivos (`file` y `patch`) serán cargados en memoria así que asegúrese que el valor de memory_limit es lo suficientemente alto.

### Ver también

- xdiff_file_bdiff() - Realiza una diferencia binaria de dos archivos
- xdiff_file_rabdiff() - Hacer una diferencia binaria de dos archivos utilizando el algoritmo polinomial de huella digital (fingerprinting) de Rabin

# xdiff_file_diff

(PECL xdiff >= 0.2.0)

xdiff_file_diff — Hacer un diff unificado de dos archivos

### Descripción

function xdiff_file_diff(
string `$old_file`,
string `$new_file`,
string `$dest`,
int `$context` = 3,
bool `$minimal` = `false`
): bool

Hace un diff unificado que contiene las diferencias entre `old_file` y `new_file` y almacena este en el archivo `dest`. El archivo resultante es legible. Un parámetro opcional `context` especifica el número de líneas de contexto que hay que añadir alrededor de cada cambio. Establecer el parámetro `minimal` a true dará como resultado de salida el archivo parche más corto posible (puede tomar algo de tiempo).

### Parámetros

`old_file`

  Ruta a el primer archivo. Este archivo actúa como "viejo" archivo.

`new_file`

  Ruta a el segundo archivo. Este archivo actúa como "nuevo" archivo.

`dest`

  Ruta del archivo parche resultante.

`context`

  Indica el número de líneas de contexto que desea incluir en el resultado diff.

`minimal`

  Establezca este parámetro a `true` si desea reducir el tamaño del resultado (puede tomar algo de tiempo).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de xdiff_file_diff()

El siguiente código hace un diff unificado de dos archivos php con una longitud de contexto de 2.

    <?php
    $old_version = 'my_script.php';
    $new_version = 'my_new_script.php';

    xdiff_file_diff($old_version, $new_version, 'my_script.diff', 2);
    ?>

### Notas

> Nota:

> Esta función no funciona bien con archivos binarios. Para hacer una diferencia binaria de archivos utilice la xdiff_file_bdiff()/xdiff_file_rabdiff().

### Ver también

- xdiff_file_patch() - Parchea un archivo con un diff unificado

# xdiff_file_diff_binary

(PECL xdiff >= 0.2.0)

xdiff_file_diff_binary — Alias de xdiff_file_bdiff()

### Descripción

function xdiff_file_diff_binary(string `$old_file`, string `$new_file`, string `$dest`): bool

Hace una diferencia binaria de dos archivos y almacena el resultado en un archivo de revisión. Esta función trabaja con archivos de texto y binarios. El archivo parche resultante puede ser posteriormente aplicado con xdiff_file_bpatch().

Desde la versión 1.5.0 de esta función es un alias de xdiff_file_bdiff().

### Parámetros

`old_file`

  Ruta a el primer archivo. Este archivo actúa como "viejo" archivo.

`new_file`

  Ruta a el segundo archivo. Este archivo actúa como "nuevo" archivo.

`dest`

  Ruta de el archivo parche resultante. El archivo resultante contiene diferencias entre los archivos "viejo" y "nuevo". Este será en formato binario y no legible por humanos.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de xdiff_file_diff_binary()

El siguiente código hace una diferencia binaria de dos archivos.

    <?php
    $old_version = 'my_script_1.0.tgz';
    $new_version = 'my_script_1.1.tgz';

    xdiff_file_diff_binary($old_version, $new_version, 'my_script.bdiff');
    ?>

### Notas

> Nota:

> Ambos archivos serán cargados en memoria así que asegúrese que el valor de memory_limit es lo suficientemente alto.

### Ver también

- xdiff_file_bdiff() - Realiza una diferencia binaria de dos archivos
- xdiff_file_bpatch() - Parchea un archivo con una diferencia binaria

# xdiff_file_merge3

(PECL xdiff >= 0.2.0)

xdiff_file_merge3 — Une 3 archivos en uno

### Descripción

function xdiff_file_merge3(
string `$old_file`,
string `$new_file1`,
string `$new_file2`,
string `$dest`
): mixed

Une tres archivos en uno y almacena el resultado en un archivo `dest`. El `old_file` es una versión original mientras `new_file1` y `new_file2` son versiones modificadas de un original.

### Parámetros

`old_file`

  Ruta a el primer archivo. Este archivo actúa como "viejo" archivo.

`new_file1`

  Ruta a el segundo archivo. Este actúa como una versión modificada de `old_file`.

`new_file2`

  Ruta a el tercer archivo. Este actúa como una versión modificada de `old_file`.

`dest`

  La ruta del archivo resultante, contiene la unión modificada de `new_file1` y `new_file2`.

### Valores devueltos

Devuelve `true` si la unión fue satisfactoria, una cadena con fragmento erróneo si esta no lo fue o `false` si ocurrió un error interno.

### Ejemplos

Ejemplo #1 Ejemplo de xdiff_file_merge3()

El código siguiente combina tres archivos en uno.

    <?php
    $old_version = 'original_script.php';
    $fix1 = 'script_with_fix1.php';
    $fix2 = 'script_with_fix2.php';

    $errors = xdiff_file_merge3($old_version, $fix1, $fix2, 'fixed_script.php');
    if (is_string($errors)) {
        echo "Rejects:\n";
        echo $errors;
    }
    ?>

### Ver también

- xdiff_string_merge3() - Unir tres cadenas en una

# xdiff_file_patch

(PECL xdiff >= 0.2.0)

xdiff_file_patch — Parchea un archivo con un diff unificado

### Descripción

function xdiff_file_patch(
string `$file`,
string `$patch`,
string `$dest`,
int `$flags` = DIFF_PATCH_NORMAL
): mixed

Parchea un `file` con un `patch` y almacena el resultado en un archivo. `patch` tiene que ser un diff unificado creado por la función xdiff_file_diff()/xdiff_string_diff(). Un parámetro opcional `flags` especifica el modo de operación.

### Parámetros

`file`

  El archivo original.

`patch`

  El archivo de revisión unificado. Este tiene que ser creado con las funciones xdiff_string_diff(), xdiff_file_diff() o herramientas compatibles.

`dest`

  Ruta de el archivo resultante.

`flags`

  Puede ser `XDIFF_PATCH_NORMAL` (modo por defecto, parche normal) o `XDIFF_PATCH_REVERSE` (parche invertido).

  A partir de la versión 1.5.0, también puede utilizar binario OR para habilitar el indicador `XDIFF_PATCH_IGNORESPACE`.

### Valores devueltos

Devuelve `false` si ocurrió un error interno, una cadena con fragmento erróneo si el parche no pudo ser aplicado o `true` si el parche fue aplicado con éxito.

### Ejemplos

Ejemplo #1 Ejemplo de xdiff_file_patch()

El siguiente código aplica un diff unificado a un archivo.

    <?php
    $old_version = 'my_script-1.0.php';
    $patch = 'my_script.patch';

    $errors = xdiff_file_patch($old_version, $patch, 'my_script-1.1.php');
    if (is_string($errors)) {
       echo "Rejects:\n";
       echo $errors;
    }

    ?>

Ejemplo #2 Ejemplo de parche invertido

El código siguiente invierte un parche.

    <?php
    $new_version = 'my_script-1.1.php';
    $patch = 'my_script.patch';

    $errors = xdiff_file_patch($new_version, $patch, 'my_script-1.0.php', XDIFF_PATCH_REVERSE);
    if (is_string($errors)) {
       echo "Fragmentos erróneos:\n";
       echo $errors;
    }

    ?>

### Ver también

- xdiff_file_diff() - Hacer un diff unificado de dos archivos

# xdiff_file_patch_binary

(PECL xdiff >= 0.2.0)

xdiff_file_patch_binary — Alias de xdiff_file_bpatch()

### Descripción

function xdiff_file_patch_binary(string `$file`, string `$patch`, string `$dest`): bool

Parchea un `file` con un `patch` binario y almacena el resultado en un archivo `dest`. Esta función acepta parches creados tanto a través de funciones xdiff_file_bdiff() o xdiff_file_rabdiff() como de sus equivalentes de cadena.

Desde la versión 1.5.0 esta función es un alias de xdiff_file_bpatch().

### Parámetros

`file`

  El archivo original.

`patch`

  El archivo parche binario.

`dest`

  La ruta de el archivo resultante.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de xdiff_file_patch_binary()

El siguiente código aplica una diferencia binaria a un archivo.

    <?php
    $old_version = 'archive-1.0.tgz';
    $patch = 'archive.bpatch';

    $result = xdiff_file_patch_binary($old_version, $patch, 'archive-1.1.tgz');
    if ($result) {
       echo "Archivo parcheado";
    } else {
       echo "El archivo no pudo ser parcheado";
    }

    ?>

### Notas

> Nota:

> Ambos archivos (`file` y `patch`) serán cargados en memoria así que asegúrese que el valor de memory_limit es lo suficientemente alto.

### Ver también

- xdiff_string_patch_binary() - Alias de xdiff_string_bpatch

# xdiff_file_rabdiff

(PECL xdiff >= 1.5.0)

xdiff_file_rabdiff — Hacer una diferencia binaria de dos archivos utilizando el algoritmo polinomial de huella digital (fingerprinting) de Rabin

### Descripción

function xdiff_file_rabdiff(string `$old_file`, string `$new_file`, string `$dest`): bool

Hace una diferencia binaria de dos archivos y almacena el resultado en un archivo de revisión. La diferencia entre esta función y xdiff_file_bdiff() es el diferente algoritmo que se utiliza que debería traducirse en una ejecución más rápida y un diff producido menor. Esta función trabaja con archivos de texto y binarios. El archivo parche resultante puede ser posteriormente aplicado utilizando xdiff_file_bpatch()/xdiff_string_bpatch().

Para obtener más información sobre las diferencias entre el algoritmo utilizado por favor vea el sitio web » libxdiff

### Parámetros

`old_file`

  Ruta a el primer archivo. Este archivo actúa como "viejo" archivo.

`new_file`

  Ruta a el segundo archivo. Este archivo actúa como "nuevo" archivo.

`dest`

  Ruta de el archivo parche resultante. El archivo resultante contiene diferencias entre los archivos "viejo" y "nuevo". Este será en formato binario y no legible por humanos.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de xdiff_file_rabdiff()

El siguiente código hace una diferencia binaria de dos archivos.

    <?php
    $old_version = 'my_script_1.0.tgz';
    $new_version = 'my_script_1.1.tgz';

    xdiff_file_rabdiff($old_version, $new_version, 'my_script.bdiff');
    ?>

### Notas

> Nota:

> Ambos archivos serán cargados en memoria así que asegúrese que el valor de memory_limit es lo suficientemente alto.

### Ver también

- xdiff_file_bpatch() - Parchea un archivo con una diferencia binaria

# xdiff_string_bdiff

(PECL xdiff >= 1.5.0)

xdiff_string_bdiff — Hacer una diferencia binaria de dos cadenas

### Descripción

function xdiff_string_bdiff(string `$old_data`, string `$new_data`): string

Hace una diferencia binaria de dos cadenas y devuelve el resultado. Esta función trabaja con texto y datos binarios. El parche resultante puede ser posteriormente aplicado utilizando xdiff_string_bpatch()/xdiff_file_bpatch().

### Parámetros

`old_data`

  Primera cadena con información binaria. Esta actúa como "vieja" información.

`new_data`

  Segunda cadena con información binaria. Esta actúa como "nueva" información.

### Valores devueltos

Devuelve la cadena con la diferencia binaria conteniendo las diferencias entre "vieja" y "nueva" información o `false` si se producido un error interno.

### Ver también

- xdiff_string_bpatch() - Parchear una cadena con una diferencia binaria

# xdiff_string_bdiff_size

(PECL xdiff >= 1.5.0)

xdiff_string_bdiff_size — Lee el tamaño de un archivo creado tras aplicar una diferencia binaria

### Descripción

function xdiff_string_bdiff_size(string `$patch`): int

Devuelve el tamaño de un archivo resultante que será creado tras aplicar el `patch` binario a el archivo original.

### Parámetros

`patch`

  El parche binario creado por la función xdiff_string_bdiff() o xdiff_string_rabdiff().

### Valores devueltos

Devuelve el tamaño del archivo que fue creado.

### Ejemplos

Ejemplo #1 Ejemplo de xdiff_string_bdiff_size()

El siguiente código lee el tamaño de un archivo que fue creado tras aplicar una diferencia binaria.

    <?php
    $binary_patch = file_get_contents('file.bdiff');
    $length = xdiff_string_bdiff_size($binary_patch);
    echo "El archivo resultante tendrá $length bytes de longitud";
    ?>

### Ver también

- xdiff_string_bdiff() - Hacer una diferencia binaria de dos cadenas
- xdiff_string_rabdiff() - Hace una comparación binaria de dos strings utilizando el algoritmo polinomial de huella digital (fingerprinting) de Rabin
- xdiff_string_bpatch() - Parchear una cadena con una diferencia binaria

# xdiff_string_bpatch

(PECL xdiff >= 1.5.0)

xdiff_string_bpatch — Parchear una cadena con una diferencia binaria

### Descripción

function xdiff_string_bpatch(string `$str`, string `$patch`): string

Parchea una cadena `str` con un `patch` binario. Esta función acepta parches creados tanto a través de las funciones xdiff_string_bdiff() y xdiff_string_rabdiff() o su archivo homólogo equivalente.

### Parámetros

`str`

  La cadena binaria original.

`patch`

  La cadena parche binaria.

### Valores devueltos

Devuelve la cadena parcheada, o `false` en caso de error.

### Ver también

- xdiff_string_bdiff() - Hacer una diferencia binaria de dos cadenas
- xdiff_string_rabdiff() - Hace una comparación binaria de dos strings utilizando el algoritmo polinomial de huella digital (fingerprinting) de Rabin

# xdiff_string_diff

(PECL xdiff >= 0.2.0)

xdiff_string_diff — Hacer un diff unificado de dos strings

### Descripción

function xdiff_string_diff(
string `$old_data`,
string `$new_data`,
int `$context` = 3,
bool `$minimal` = `false`
): string

Hace un diff unificado que contiene diferencias entre el string `old_data` y el string `new_data` y devuelve este. El diff resultante es legible. Un parámetro opcional `context` especifica el número de líneas de contexto que hay que añadir alrededor de cada cambio. Establecer el parámetro `minimal` a true dará como resultado de salida el archivo parche más corto posible (puede tomar algo de tiempo).

### Parámetros

`old_data`

  Primera cadena con información. Esta actúa como "vieja" información.

`new_data`

  Segundo string con información. Esta actúa como "nueva" información.

`context`

  Indica el número de líneas de contexto que desea incluir en el diff resultado.

`minimal`

  Establezca este parámetro a `true` si desea reducir el tamaño del resultado (puede tomar algo de tiempo).

### Valores devueltos

Devuelve un string con el resultado diff o `false` si ocurriera un error interno.

### Ejemplos

Ejemplo #1 Ejemplo de xdiff_string_diff()

El siguiente código hace un diff unificado de dos artículos.

    <?php
    $old_article = file_get_contents('./old_article.txt');
    $new_article = $_REQUEST['article']; /* Supongamos que alguien pega un nuevo artículo en formato html */

    $diff = xdiff_string_diff($old_article, $new_article, 1);
    if (is_string($diff)) {
        echo "Diferencias entre los dos artículos:\n";
        echo $diff;
    }

    ?>

### Notas

> Nota:

> Esta función no funciona bien con string binarios. Para hacer un diff de string binario utilice xdiff_string_bdiff()/xdiff_string_rabdiff().

### Ver también

- xdiff_string_patch() - Parchear una cadena con un diff unificado

# xdiff_string_diff_binary

(PECL xdiff >= 0.2.0)

xdiff_string_diff_binary — Alias de xdiff_string_bdiff()

### Descripción

function xdiff_string_bdiff(string `$old_data`, string `$new_data`): string

Hace una diferencia binaria de dos cadenas y devuelve el resultado. Esta función trabaja con texto y datos binarios. El parche resultante puede ser posteriormente aplicado utilizando xdiff_string_bpatch()/xdiff_file_bpatch().

Desde la versión 1.5.0 esta función es un alias de xdiff_string_bdiff().

### Parámetros

`old_data`

  Primera cadena con información binaria. Esta actúa como "vieja" información.

`new_data`

  Segunda cadena con información binaria. Esta actúa como "nueva" información.

### Valores devueltos

Devuelve cadena con resultado o `false` si se produce un error interno.

### Ver también

- xdiff_string_bdiff() - Hacer una diferencia binaria de dos cadenas
- xdiff_string_bpatch() - Parchear una cadena con una diferencia binaria

# xdiff_string_merge3

(PECL xdiff >= 0.2.0)

xdiff_string_merge3 — Unir tres cadenas en una

### Descripción

function xdiff_string_merge3(
string `$old_data`,
string `$new_data1`,
string `$new_data2`,
string `&$error` = ?
): mixed

Une tres cadenas en una y devuelve el resultado. El parámetro `old_data` es una versión original de los datos mientras `new_data1` y `new_data2` son versiones modificadas de un original. El parámetro opcional `error` es utilizado para admitir cualquier fragmento erróneo durante el proceso de unión.

### Parámetros

`old_data`

  Primera cadena con información. Esta actúa como "vieja" información.

`new_data1`

  Segunda cadena con información. Esta actúa como versión modificada del `old_data`.

`new_data2`

  La tercera cadena con información. Esta actúa como versión modificada del `old_data`.

`error`

  Si se produce algún fragmento erróneo entonces se almacenan dentro de esta variable.

### Valores devueltos

Devuelve la cadena unida, `false` si se produce un error interno, o `true` si la cadena unida está vacía.

### Ver también

- xdiff_file_merge3() - Une 3 archivos en uno

# xdiff_string_patch

(PECL xdiff >= 0.2.0)

xdiff_string_patch — Parchear una cadena con un diff unificado

### Descripción

function xdiff_string_patch(
string `$str`,
string `$patch`,
int `$flags` = ?,
string `&$error` = ?
): string

Parchea una cadena `str` con un parche unificado en parámetro `patch` y devuelve el resultado. `patch` tiene que ser un diff unificado creado por la función xdiff_file_diff()/xdiff_string_diff(). Un parámetro opcional `flags` especifica el modo de operación. Cualquier fragmento erróneo del parche será almacenado en el interior de la variable `error` si si esta es proporcionada.

### Parámetros

`str`

  La cadena original.

`patch`

  La cadena parche unificada. Esta tiene que ser creada utilizando las funciones xdiff_string_diff(), xdiff_file_diff() o herramientas compatibles.

`flags`

  `flags` uede ser `XDIFF_PATCH_NORMAL` (modo por defecto, parche normal) o `XDIFF_PATCH_REVERSE` (parche invertido).

  A partir de la versión 1.5.0, también se puede utilizar binario OR para habilitar el indicador `XDIFF_PATCH_IGNORESPACE`.

`error`

  Si se proporciona entonces los fragmentos erróneos se almacenan dentro de esta variable.

### Valores devueltos

Devuelve la cadena parcheada, o `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo de xdiff_string_patch()

El siguiente código aplica cambios en algún artículo.

    <?php
    $old_article = file_get_contents('./old_article.txt');
    $diff = $_SERVER['patch']; /* Supongamos que alguien pega un parche para un formulario html */

    $errors = '';

    $new_article = xdiff_string_patch($old_article, $diff, XDIFF_PATCH_NORMAL, $errors);
    if (is_string($new_article)) {
        echo "Nuevo artículo:\n";
        echo $new_article;
    }

    if (strlen($errors)) {
        echo "Fragmentos erróneos: \n";
        echo $errors;
    }

    ?>

### Ver también

- xdiff_string_diff() - Hacer un diff unificado de dos strings

# xdiff_string_patch_binary

(PECL xdiff >= 0.2.0)

xdiff_string_patch_binary — Alias de xdiff_string_bpatch()

### Descripción

function xdiff_string_patch_binary(string `$str`, string `$patch`): string

Parchea una cadena `str` con un `patch` binario. Esta función acepta parches creados tanto a través de las funciones xdiff_string_bdiff() y xdiff_string_rabdiff() o de su archivo homólogo equivalente.

Desde la versión 1.5.0 esta función es un alias de xdiff_string_bpatch().

### Parámetros

`str`

  La cadena binaria original.

`patch`

  La cadena parche binaria.

### Valores devueltos

Devuelve la cadena parcheada, o `false` en caso de error.

### Ver también

- xdiff_string_bpatch() - Parchear una cadena con una diferencia binaria
- xdiff_string_bdiff() - Hacer una diferencia binaria de dos cadenas
- xdiff_string_rabdiff() - Hace una comparación binaria de dos strings utilizando el algoritmo polinomial de huella digital (fingerprinting) de Rabin

# xdiff_string_rabdiff

(PECL xdiff >= 1.5.0)

xdiff_string_rabdiff — Hace una comparación binaria de dos strings utilizando el algoritmo polinomial de huella digital (fingerprinting) de Rabin

### Descripción

function xdiff_string_rabdiff(string `$old_data`, string `$new_data`): string|false

Hace una comparación binaria de dos strings utilizando el algoritmo de huella digital polinomial de Rabin implementado por » libxdiff. En comparación con xdiff_string_bdiff(), este algoritmo generalmente produce diferencias más pequeñas y opera más rápido, manteniendo la compatibilidad total con xdiff_string_bpatch() y xdiff_file_bpatch() para la aplicación de parches.

Esta función puede utilizarse tanto con datos de texto como binarios. Los datos de comparación pueden aplicarse posteriormente para recrear la nueva versión a partir de la anterior.

Para obtener más información sobre el algoritmo, vea la » documentación de libxdiff.

### Parámetros

`old_data`

  El primer string que contiene los datos binarios "antiguos".

`new_data`

  El segundo string que contiene los "nuevos" datos binarios.

### Valores devueltos

Devuelve un string binario de comparación que contiene las diferencias entre los datos antiguos y nuevos, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Creación de una diferencia binaria entre dos cadenas

    <?php
    $old = file_get_contents('file_v1.txt');
    $new = file_get_contents('file_v2.txt');

    $diff = xdiff_string_rabdiff($old, $new);
    file_put_contents('patch.rdiff', $diff);
    ?>

### Ver también

- xdiff_string_bdiff() - Hacer una diferencia binaria de dos cadenas
- xdiff_string_bpatch() - Parchear una cadena con una diferencia binaria
- xdiff_file_bpatch() - Parchea un archivo con una diferencia binaria

## Tabla de contenidos

- xdiff_file_bdiff — Realiza una diferencia binaria de dos archivos
- xdiff_file_bdiff_size — Lee el tamaño de un archivo creado tras aplicar una diferencia binaria
- xdiff_file_bpatch — Parchea un archivo con una diferencia binaria
- xdiff_file_diff — Hacer un diff unificado de dos archivos
- xdiff_file_diff_binary — Alias de xdiff_file_bdiff
- xdiff_file_merge3 — Une 3 archivos en uno
- xdiff_file_patch — Parchea un archivo con un diff unificado
- xdiff_file_patch_binary — Alias de xdiff_file_bpatch
- xdiff_file_rabdiff — Hacer una diferencia binaria de dos archivos utilizando el algoritmo polinomial de huella digital (fingerprinting) de Rabin
- xdiff_string_bdiff — Hacer una diferencia binaria de dos cadenas
- xdiff_string_bdiff_size — Lee el tamaño de un archivo creado tras aplicar una diferencia binaria
- xdiff_string_bpatch — Parchear una cadena con una diferencia binaria
- xdiff_string_diff — Hacer un diff unificado de dos strings
- xdiff_string_diff_binary — Alias de xdiff_string_bdiff
- xdiff_string_merge3 — Unir tres cadenas en una
- xdiff_string_patch — Parchear una cadena con un diff unificado
- xdiff_string_patch_binary — Alias de xdiff_string_bpatch
- xdiff_string_rabdiff — Hace una comparación binaria de dos strings utilizando el algoritmo polinomial de huella digital (fingerprinting) de Rabin

- Instalación/Configuración
  - Requerimientos
  - Instalación
- Constantes predefinidas
- Funciones de xdiff
  - xdiff_file_bdiff — Realiza una diferencia binaria de dos archivos
  - xdiff_file_bdiff_size — Lee el tamaño de un archivo creado tras aplicar una diferencia binaria
  - xdiff_file_bpatch — Parchea un archivo con una diferencia binaria
  - xdiff_file_diff — Hacer un diff unificado de dos archivos
  - xdiff_file_diff_binary — Alias de xdiff_file_bdiff
  - xdiff_file_merge3 — Une 3 archivos en uno
  - xdiff_file_patch — Parchea un archivo con un diff unificado
  - xdiff_file_patch_binary — Alias de xdiff_file_bpatch
  - xdiff_file_rabdiff — Hacer una diferencia binaria de dos archivos utilizando el algoritmo polinomial de huella digital (fingerprinting) de Rabin
  - xdiff_string_bdiff — Hacer una diferencia binaria de dos cadenas
  - xdiff_string_bdiff_size — Lee el tamaño de un archivo creado tras aplicar una diferencia binaria
  - xdiff_string_bpatch — Parchear una cadena con una diferencia binaria
  - xdiff_string_diff — Hacer un diff unificado de dos strings
  - xdiff_string_diff_binary — Alias de xdiff_string_bdiff
  - xdiff_string_merge3 — Unir tres cadenas en una
  - xdiff_string_patch — Parchear una cadena con un diff unificado
  - xdiff_string_patch_binary — Alias de xdiff_string_bpatch
  - xdiff_string_rabdiff — Hace una comparación binaria de dos strings utilizando el algoritmo polinomial de huella digital (fingerprinting) de Rabin

- Direct IO
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones de Direct IO
- Directorios
  - Constantes predefinidas
  - Directory — La clase Directory
  - Funciones de directorio
- Fileinfo — Información de un fichero
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones de Fileinfo
  - finfo — La clase finfo
- Sistema de Ficheros
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones del Sistema de Archivos
- Inotify
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones Inotify
- xattr
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones de xattr
- xdiff
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones de xdiff

# Soporte para lenguaje humano y codificación de caracteres

# Biblioteca de ortografía Enchant

# Introducción

Enchant es una implementación PHP de la » biblioteca Enchant. Enchant proporciona uniformidad y conformidad para todas las bibliotecas de ortografía, e implementa ciertas funcionalidades que pueden estar ausentes en una biblioteca. Todo debe "funcionar simplemente".

Enchant soporta las siguientes bibliotecas :

- `Aspell/Pspell (previsto para reemplazar Ispell)`
- `Ispell (muy antiguo, puede ser considerado como estándar)`
- `MySpell/Hunspell (un proyecto orientado a objetos, también utilizado por Mozilla)`
- `Uspell (previsto originalmente para el yiddish, el hebreo y los idiomas de Europa del Este - alojado en el CVS de AbiWord bajo el módulo "uspell")`
- `Hspell (Hebreo)`
- `AppleSpell (Mac OSX)`

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Tipos de recursos

## Requerimientos

Esta versión utiliza las funciones de la » biblioteca Enchant por Dom Lachowicz. Se debe utilizar Enchant 1.2.4 o superior. Enchant 2.0.0 o superior es únicamente soportado a partir de PHP 8.0.0.

Enchant requiere asimismo » Glib 2.6 o superior. Las bibliotecas Windows pre-compiladas están disponibles desde » http://ftp.gnome.org/pub/gnome/binaries/win32/glib/.

## Instalación

Partiendo del principio de que las bibliotecas requeridas están instaladas, los usuarios pueden activar enchant añadiendo la opción --with-enchant[=dir] durante la compilación de PHP.

Los usuarios de Windows deben activar php_enchant.dll para poder utilizar esta extensión.

> Nota: Configuración adicional en Windows
> Para hacer funcionar esta extensión, algunas bibliotecas DLL deben estar disponibles a través del PATH del sistema Windows. Lea la F.A.Q titulada "Cómo agregar mi carpeta PHP a mi PATH de Windows" para más información. Copiar las bibliotecas DLL desde la carpeta PHP a la carpeta del sistema de Windows también funciona (ya que la carpeta del sistema está por defecto en el PATH del sistema), pero este método no es recomendado. Esta extensión requiere que los siguientes archivos estén en el PATH: libenchant.dll, glib-2.dll, gmodule-2.dll. Además, es necesario copiar al menos uno de los proveedores proporcionados en lib\enchant hacia \usr\local\lib\enchant-2, (que es una ruta absoluta a partir de la raíz del disco actual). Anterior a PHP 8.0.0, es decir, utilizando Enchant v1, los proveedores debían copiarse en C:\enchant_plugins en su lugar, donde esta ruta podía ser personalizada creando el valor de registro `HKEY_CURRENT_USER\SOFTWARE\Enchant\Config\Module_Dir` y estableciéndola en la ruta deseada.

## Tipos de recursos

Anterior a PHP 8.0.0, existen dos tipos de recursos en esta extensión. El primero es el broker (gestor de backends) y el segundo es para el diccionario.

# Constantes predefinidas

`LIBENCHANT_VERSION` (string)
  La versión de libenchant. Disponible a partir de PHP 8.0.0.
`ENCHANT_MYSPELL` (int)
  Tipo de diccionario para MySpell. Utilizado con enchant_broker_get_dict_path() y enchant_broker_set_dict_path(). Deprecado a partir de PHP 8.0.0.
`ENCHANT_ISPELL` (int)
  Tipo de diccionario para Ispell. Utilizado con enchant_broker_get_dict_path() y enchant_broker_set_dict_path(). Deprecado a partir de PHP 8.0.0.

# Ejemplos

Ejemplo #1 Ejemplos de Uso de Enchant

    <?php
    $etiqueta = 'en_US';
    $r = enchant_broker_init();
    $bprovides = enchant_broker_describe($r);
    echo "El agente actual proporciona los siguientes entornos:\n";
    print_r($bprovides);

    $diccionarios = enchant_broker_list_dicts($r);
    print_r($diccionarios);
    if (enchant_broker_dict_exists($r,$etiqueta)) {
        $d = enchant_broker_request_dict($r, $etiqueta);
        $dprovides = enchant_dict_describe($d);
        echo "el diccionario $etiqueta proporciona:\n";
        $palabra_correcta = enchant_dict_check($d, "soong");
        print_r($dprovides);
        if (!$palabra_correcta) {
            $sugerencias = enchant_dict_suggest($d, "soong");
            echo "Sugerencias para 'soong':";
            print_r($sugerencias);
        }
        enchant_broker_free_dict($d);
    } else {
    }
    enchant_broker_free($r);
    ?>

# Funciones de Enchant

# enchant_broker_describe

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0)

enchant_broker_describe — Enumera los proveedores Enchant

### Descripción

function enchant_broker_describe(EnchantBroker `$broker`): array

Enumera los proveedores Enchant y muestra algunas informaciones sobre ellos. Las mismas informaciones son proporcionadas mediante la función phpinfo().

### Parámetros

`broker`
  Un broker Enchant devuelto por enchant_broker_init().

### Valores devueltos

Devuelve un array de los proveedores Enchant disponibles con sus detalles.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `broker` ahora espera una instancia de EnchantBroker; anteriormente, se esperaba un resource.
8.0.0 | Anterior a esta versión, esta función devolvía `false` en caso de error.

### Ejemplos

Ejemplo #1 Lista las interfaces proporcionadas por un patrocinador dado

    <?php
    $r = enchant_broker_init();
    $bprovides = enchant_broker_describe($r);
    echo "El patrocinador actual proporciona las siguientes interfaces :\n";
    print_r($bprovides);

    ?>

Resultado del ejemplo anterior es similar a:

    El patrocinador actual proporciona las siguientes interfaces :
    Array
    (
        [0] => Array
            (
                [name] => aspell
                [desc] => Aspell Provider
                [file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [1] => Array
            (
                [name] => hspell
                [desc] => Hspell Provider
                [file] => /usr/lib/enchant/libenchant_hspell.so
            )

        [2] => Array
            (
                [name] => ispell
                [desc] => Ispell Provider
                [file] => /usr/lib/enchant/libenchant_ispell.so
            )

        [3] => Array
            (
                [name] => myspell
                [desc] => Myspell Provider
                [file] => /usr/lib/enchant/libenchant_myspell.so
            )

    )

# enchant_broker_dict_exists

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_dict_exists — Verifica si un diccionario existe

### Descripción

function enchant_broker_dict_exists(EnchantBroker `$broker`, string `$tag`): bool

Verifica si un diccionario existe.

### Parámetros

`broker`
  Un broker Enchant devuelto por enchant_broker_init().
`tag`
  lenguaje, en un formato como us_US, ch_DE, etc.

### Valores devueltos

Devuelve `true` si el lenguaje existe, `false` en caso contrario.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `broker` ahora espera una instancia de EnchantBroker; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con enchant_broker_dict_exists()

    <?php
    $tag = 'en_US';
    $r = enchant_broker_init();
    if (enchant_broker_dict_exists($r,$tag)) {
        echo "Diccionario " . $tag . " encontrado.\n";
    }
    ?>

### Ver también

- enchant_broker_describe() - Enumera los proveedores Enchant

# enchant_broker_free

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_free — Libera los recursos del patrocinador así como sus diccionarios

Advertencia

Esta función está OBSOLETA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function enchant_broker_free(EnchantBroker `$broker`): bool

Libera un patrocinador así como todos sus diccionarios. A partir de PHP 8.0.0, se recomienda destruir el objeto en lugar de llamar a esta función.

### Parámetros

`broker`
  Un broker Enchant devuelto por enchant_broker_init().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función ha sido deprecada en favor de la desinicialización del objeto.
8.0.0 | `broker` ahora espera una instancia de EnchantBroker; anteriormente, se esperaba un resource.

### Ver también

- enchant_broker_init() - Crea un nuevo objeto sponsor

# enchant_broker_free_dict

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_free_dict — Libera un recurso de diccionario

Advertencia

Esta función está OBSOLETA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function enchant_broker_free_dict(EnchantDictionary `$dictionary`): bool

Libera un diccionario. A partir de PHP 8.0.0, se recomienda destruir el objeto en lugar de llamar a esta función.

### Parámetros

`dictionary`
  Un diccionario Enchant devuelto por enchant_broker_request_dict() o enchant_broker_request_pwl_dict().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función está deprecada a favor de la desinicialización del objeto.
8.0.0 | `dictionary` ahora espera una EnchantDictionary; anteriormente, se esperaba un resource.

### Ver también

- enchant_broker_request_dict() - Crear un nuevo diccionario usando una etiqueta
- enchant_broker_request_pwl_dict() - Crea un diccionario utilizando un archivo PWL

# enchant_broker_get_dict_path

(PHP 5 >= 5.3.1, PHP 7, PHP 8, PECL enchant >= 1.0.1)

enchant_broker_get_dict_path — Obtiene la ruta del directorio para un backend proporcionado

Advertencia

Esta función está OBSOLETA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function enchant_broker_get_dict_path(EnchantBroker `$broker`, int `$type`): string|false

Obtiene la ruta del directorio para un backend proporcionado.

### Parámetros

`broker`
  Un broker Enchant devuelto por enchant_broker_init().
`type`
  El tipo de diccionarios, es decir, `ENCHANT_MYSPELL` o `ENCHANT_ISPELL`.

### Valores devueltos

Devuelve la ruta del directorio del diccionario en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función ha sido deprecada.
8.0.0 | `broker` ahora espera una instancia de EnchantBroker; anteriormente, se esperaba un resource.

### Notas

> Nota: Esta función solo está disponible si la extensión ha sido compilada con Enchant v1.

### Ver también

- enchant_broker_set_dict_path() - Define la ruta del directorio para un backend proporcionado

# enchant_broker_get_error

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_get_error — Devuelve el último error de un sponsor

### Descripción

function enchant_broker_get_error(EnchantBroker `$broker`): string|false

Devuelve el último error ocurrido para este sponsor.

### Parámetros

`broker`
  Un broker Enchant devuelto por enchant_broker_init().

### Valores devueltos

Devuelve el mensaje si se ha encontrado un error, o `false` en caso contrario.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `broker` ahora espera una instancia de EnchantBroker; anteriormente, se esperaba un resource.

# enchant_broker_init

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_init — Crea un nuevo objeto sponsor

### Descripción

function enchant_broker_init(): EnchantBroker|false

### Parámetros

### Valores devueltos

Devuelve un recurso de sponsor en caso de éxito, `false` en caso contrario.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de EnchantBroker; anteriormente se devolvía un resource.

### Ver también

- enchant_broker_free() - Libera los recursos del patrocinador así como sus diccionarios

# enchant_broker_list_dicts

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 1.0.1)

enchant_broker_list_dicts — Devuelve una lista de todos los diccionarios disponibles

### Descripción

function enchant_broker_list_dicts(EnchantBroker `$broker`): array

Devuelve una lista de todos los diccionarios disponibles junto con sus detalles.

### Parámetros

`broker`
  Un broker Enchant devuelto por enchant_broker_init().

### Valores devueltos

Devuelve un array de diccionarios disponibles con sus detalles.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `broker` ahora espera una instancia de EnchantBroker; anteriormente, se esperaba un resource.
8.0.0 | Antes de esta versión, la función devolvía `false` en caso de error.

### Ejemplos

Ejemplo #1 Lista todos los diccionarios disponibles para un sponsor

    <?php
    $r = enchant_broker_init();
    $dicts = enchant_broker_list_dicts($r);
    print_r($dicts);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => Array
            (
                [lang_tag] => de
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [1] => Array
            (
                [lang_tag] => de_DE
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [3] => Array
            (
                [lang_tag] => en
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [4] => Array
            (
                [lang_tag] => en_GB
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [5] => Array
            (
                [lang_tag] => en_US
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [6] => Array
            (
                [lang_tag] => hi_IN
                [provider_name] => myspell
                [provider_desc] => Myspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_myspell.so
            )

    )

### Ver también

- enchant_broker_describe() - Enumera los proveedores Enchant

# enchant_broker_request_dict

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_request_dict — Crear un nuevo diccionario usando una etiqueta

### Descripción

function enchant_broker_request_dict(EnchantBroker `$broker`, string `$tag`): EnchantDictionary|false

crea un nuevo diccionario usando una etiqueta, la etiqueta de idioma no vacía que desea solicitar para un diccionario ("en_US", "de_DE", ...)

### Parámetros

`broker`
  Un broker Enchant devuelto por enchant_broker_init().
`tag`
  Una etiqueta que describe la configuración local, por ejemplo en_US, de_DE

### Valores devueltos

Devuelve un recurso de diccionario en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `broker` ahora espera una instancia de EnchantBroker; anteriormente, se esperaba un resource.
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de EnchantDictionary; anteriormente, se devolvía un resource.

### Ejemplos

Ejemplo #1 Un ejemplo de enchant_broker_request_dict()

Comprueba si existe un diccionario usando enchant_broker_dict_exists() y solicítalo.

    <?php
    $tag = 'en_US';
    $broker = enchant_broker_init();
    if (enchant_broker_dict_exists($broker,$tag)) {
        $dict = enchant_broker_request_dict($broker, $tag);
        var_dump($dict);
    }
    ?>

### Ver también

- enchant_dict_describe() - Describe un diccionario individual
- enchant_broker_dict_exists() - Verifica si un diccionario existe
- enchant_broker_free_dict() - Libera un recurso de diccionario

# enchant_broker_request_pwl_dict

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_request_pwl_dict — Crea un diccionario utilizando un archivo PWL

### Descripción

function enchant_broker_request_pwl_dict(EnchantBroker `$broker`, string `$filename`): EnchantDictionary|false

Crea un diccionario utilizando un archivo PWL. Un archivo PWL es un archivo de palabras personales que contiene una palabra por línea.

### Parámetros

`broker`
  Un broker Enchant devuelto por enchant_broker_init().
`filename`
  Ruta de acceso al archivo PWL. Si el archivo no existe, se creará uno nuevo, si es posible.

### Valores devueltos

Devuelve un recurso de diccionario en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `broker` ahora espera una instancia de EnchantBroker; anteriormente, se esperaba un resource.
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de EnchantDictionary ; anteriormente se devolvía una resource.

### Ver también

- enchant_dict_describe() - Describe un diccionario individual
- enchant_broker_dict_exists() - Verifica si un diccionario existe
- enchant_broker_free_dict() - Libera un recurso de diccionario

# enchant_broker_set_dict_path

(PHP 5 >= 5.3.1, PHP 7, PHP 8, PECL enchant >= 1.0.1)

enchant_broker_set_dict_path — Define la ruta del directorio para un backend proporcionado

Advertencia

Esta función está OBSOLETA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function enchant_broker_set_dict_path(EnchantBroker `$broker`, int `$type`, string `$path`): bool

Define la ruta del directorio para un backend proporcionado.

### Parámetros

`broker`
  Un broker Enchant devuelto por enchant_broker_init().
`type`
  El tipo de los diccionarios, es decir, `ENCHANT_MYSPELL` o `ENCHANT_ISPELL`.
`path`
  La ruta del directorio del diccionario.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función ha sido deprecada.
8.0.0 | `broker` ahora espera una instancia de EnchantBroker; anteriormente, se esperaba un resource.

### Notas

> Nota: Esta función solo está disponible si la extensión ha sido compilada con Enchant v1.

### Ver también

- enchant_broker_get_dict_path() - Obtiene la ruta del directorio para un backend proporcionado

# enchant_broker_set_ordering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_set_ordering — Declara una preferencia para un diccionario de un idioma

### Descripción

function enchant_broker_set_ordering(EnchantBroker `$broker`, string `$tag`, string `$ordering`): bool

Declara una preferencia para un diccionario a utilizar para el idioma especificado por el argumento `tag`. El orden de los idiomas es una lista separada por comas. El carácter especial "*" puede ser utilizado como idioma para declarar un orden por defecto para todos los idiomas que no declaren explícitamente un orden.

### Parámetros

`broker`
  Un broker Enchant devuelto por enchant_broker_init().
`tag`
  El idioma. El carácter "*" puede ser utilizado como idioma para declarar un orden por defecto para todos los idiomas que no declaren explícitamente un orden.
`ordering`
  Lista de nombres de proveedores separada por comas

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `broker` ahora espera una instancia de EnchantBroker; anteriormente, se esperaba un resource.

# enchant_dict_add

(PHP 8)

enchant_dict_add — Añadir una palabra a la lista personal de palabras

### Descripción

function enchant_dict_add(EnchantDictionary `$dictionary`, string `$word`): void

Añade una palabra a la lista personal de palabras del diccionario dado.

### Parámetros

`dictionary`
  Un diccionario Enchant devuelto por enchant_broker_request_dict() o enchant_broker_request_pwl_dict().
`word`
  La palabra a añadir

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `dictionary` ahora espera una instancia de EnchantDictionary; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Añadir una palabra a una PWL

    <?php

    $filename = './my_word_list.pwl';
    $word = 'Supercalifragilisticexpialidocious';

    $broker = enchant_broker_init();
    $dict = enchant_broker_request_pwl_dict($broker, $filename);

    enchant_dict_add($dict, $word);

    ?>

### Ver también

- enchant_broker_request_pwl_dict() - Crea un diccionario utilizando un archivo PWL
- enchant_broker_request_dict() - Crear un nuevo diccionario usando una etiqueta

# enchant_dict_add_to_personal

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_add_to_personal — Alias de enchant_dict_add()

Advertencia

Este alias está OBSOLETO en PHP 8.0.0.

### Descripción

Esta función es un alias de: enchant_dict_add().

# enchant_dict_add_to_session

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_add_to_session — Añade una palabra a la sesión actual

### Descripción

function enchant_dict_add_to_session(EnchantDictionary `$dictionary`, string `$word`): void

Añade la palabra `word` al diccionario proporcionado. Solo será añadida para la sesión actual.

### Parámetros

`dictionary`
  Un diccionario Enchant devuelto por enchant_broker_request_dict() o enchant_broker_request_pwl_dict().
`word`
  La palabra a añadir

### Valores devueltos

No se retorna ningún valor.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `dictionary` ahora espera una instancia de EnchantDictionary; anteriormente, se esperaba un resource.

### Ver también

- enchant_broker_request_dict() - Crear un nuevo diccionario usando una etiqueta

# enchant_dict_check

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_check — Verifica si una palabra está correctamente escrita

### Descripción

function enchant_dict_check(EnchantDictionary `$dictionary`, string `$word`): bool

Devuelve `true` si la palabra `word` está correctamente escrita, `false` en caso contrario.

### Parámetros

`dictionary`
  Un diccionario Enchant devuelto por enchant_broker_request_dict() o enchant_broker_request_pwl_dict().
`word`
  La palabra a verificar

### Valores devueltos

Devuelve `true` si la palabra está correctamente escrita, `false` en caso contrario.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `dictionary` ahora espera una instancia de EnchantDictionary; anteriormente, se esperaba un resource.

# enchant_dict_describe

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_describe — Describe un diccionario individual

### Descripción

function enchant_dict_describe(EnchantDictionary `$dictionary`): array

Devuelve los detalles del diccionario.

### Parámetros

`dictionary`
  Un diccionario Enchant devuelto por enchant_broker_request_dict() o enchant_broker_request_pwl_dict().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `dictionary` ahora espera una instancia de EnchantDictionary; anteriormente, se esperaba un resource.
8.0.0 | Antes de esta versión, la función devolvía `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo de enchant_dict_describe()

Comprueba si existe un diccionario usando enchant_broker_dict_exists() y muestra sus detalles.

    <?php
    $tag = 'en_US';
    $broker = enchant_broker_init();
    if (enchant_broker_dict_exists($broker, $tag)) {
        $dict = enchant_broker_request_dict($broker, $tag);
        $dict_details = enchant_dict_describe($dict);
        print_r($dict_details);
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [lang] => en_US
        [name] => aspell
        [desc] => Proveedor Aspell
        [file] => /usr/lib/enchant/libenchant_aspell.so
    )

# enchant_dict_get_error

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_get_error — Devuelve el último error de la sesión actual

### Descripción

function enchant_dict_get_error(EnchantDictionary `$dictionary`): string|false

Devuelve el último error de la sesión actual.

### Parámetros

`dictionary`
  Un diccionario Enchant devuelto por enchant_broker_request_dict() o enchant_broker_request_pwl_dict().

### Valores devueltos

Devuelve el mensaje de error en forma de string, o `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `dictionary` ahora espera una instancia de EnchantDictionary; anteriormente, se esperaba un resource.

# enchant_dict_is_added

(PHP 8)

enchant_dict_is_added — Si la palabra existe o no en esta sesión de ortografía

### Descripción

function enchant_dict_is_added(EnchantDictionary `$dictionary`, string `$word`): bool

Informa si la palabra ya existe o no en la sesión actual.

### Parámetros

`dictionary`
  Un diccionario Enchant devuelto por enchant_broker_request_dict() o enchant_broker_request_pwl_dict().
`word`
  La palabra a buscar

### Valores devueltos

Devuelve `true` si la palabra existe o `false`

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `dictionary` ahora espera una instancia de EnchantDictionary; anteriormente, se esperaba un resource.

### Ver también

- enchant_dict_add_to_session() - Añade una palabra a la sesión actual

# enchant_dict_is_in_session

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_is_in_session — Alias de enchant_dict_is_added()

Advertencia

Este alias está OBSOLETO en PHP 8.0.0.

### Descripción

Esta función es un alias de: enchant_dict_is_added().

# enchant_dict_quick_check

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant:0.2.0-1.0.1)

enchant_dict_quick_check — Verifica si la palabra está correctamente escrita y proporciona sugerencias

### Descripción

function enchant_dict_quick_check(EnchantDictionary `$dictionary`, string `$word`, array `&$suggestions` = `null`): bool

Devuelve `true` si la palabra está correctamente escrita, `false` si la variable de sugerencias es proporcionada, y la llena con las sugerencias posibles.

### Parámetros

`dictionary`
  Un diccionario Enchant devuelto por enchant_broker_request_dict() o enchant_broker_request_pwl_dict().
`word`
  La palabra a verificar
`suggestions`
  Si la palabra no está correctamente escrita, esta variable contendrá un array de sugerencias.

### Valores devueltos

Devuelve `true` si la palabra está correctamente escrita, `false` en caso contrario.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `dictionary` ahora espera una instancia de EnchantDictionary; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con enchant_dict_quick_check()

    <?php
    $tag = 'en_US';
    $r = enchant_broker_init();

    if (enchant_broker_dict_exists($r,$tag)) {
        $d = enchant_broker_request_dict($r, $tag);
        enchant_dict_quick_check($d, 'soong', $suggs);
        print_r($suggs);
    }
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => song
        [1] => snog
        [2] => soon
        [3] => Sang
        [4] => Sung
        [5] => sang
        [6] => sung
        [7] => sponge
        [8] => spongy
        [9] => snag
        [10] => snug
        [11] => sonic
        [12] => sing
        [13] => songs
        [14] => Son
        [15] => Sonja
        [16] => Synge
        [17] => son
        [18] => Sejong
        [19] => sarong
        [20] => sooner
        [21] => Sony
        [22] => sown
        [23] => scone
        [24] => song's
    )

### Ver también

- enchant_dict_check() - Verifica si una palabra está correctamente escrita
- enchant_dict_suggest() - Sugerir ortografías para una palabra

# enchant_dict_store_replacement

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_store_replacement — Añade una ortografía para una palabra

### Descripción

function enchant_dict_store_replacement(EnchantDictionary `$dictionary`, string `$misspelled`, string `$correct`): void

Añade una ortografía para `misspelled` utilizando `correct`. Tenga en cuenta que si se reemplaza @mis por @cor, entonces es probable que las futuras ocurrencias de @mis sean reemplazadas por @cor. Así, @cor será añadido a la lista de sugerencias.

### Parámetros

`dictionary`
  Un diccionario Enchant devuelto por enchant_broker_request_dict() o enchant_broker_request_pwl_dict().
`misspelled`
  La palabra a tratar
`correct`
  La palabra correcta

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `dictionary` ahora espera una instancia de EnchantDictionary; anteriormente, se esperaba un resource.

# enchant_dict_suggest

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_suggest — Sugerir ortografías para una palabra

### Descripción

function enchant_dict_suggest(EnchantDictionary `$dictionary`, string `$word`): array

### Parámetros

`dictionary`
  Un diccionario Enchant devuelto por enchant_broker_request_dict() o enchant_broker_request_pwl_dict().
`word`
  Palabra para la que se generarán sugerencias.

### Valores devueltos

Devuelve un array de sugerencias si la palabra está mal escrita.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `dictionary` ahora espera una instancia de EnchantDictionary; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo de uso de enchant_dict_suggest()

    <?php
    $tag = 'en_US';
    $r = enchant_broker_init();
    if (enchant_broker_dict_exists($r,$tag)) {
        $d = enchant_broker_request_dict($r, $tag);

        $wordcorrect = enchant_dict_check($d, "soong");
        if (!$wordcorrect) {
            $suggs = enchant_dict_suggest($d, "soong");
            echo "Sugerencias para 'soong':";
            print_r($suggs);
        }
    }
    ?>

### Ver también

- enchant_dict_check() - Verifica si una palabra está correctamente escrita
- enchant_dict_quick_check() - Verifica si la palabra está correctamente escrita y proporciona sugerencias

## Tabla de contenidos

- enchant_broker_describe — Enumera los proveedores Enchant
- enchant_broker_dict_exists — Verifica si un diccionario existe
- enchant_broker_free — Libera los recursos del patrocinador así como sus diccionarios
- enchant_broker_free_dict — Libera un recurso de diccionario
- enchant_broker_get_dict_path — Obtiene la ruta del directorio para un backend proporcionado
- enchant_broker_get_error — Devuelve el último error de un sponsor
- enchant_broker_init — Crea un nuevo objeto sponsor
- enchant_broker_list_dicts — Devuelve una lista de todos los diccionarios disponibles
- enchant_broker_request_dict — Crear un nuevo diccionario usando una etiqueta
- enchant_broker_request_pwl_dict — Crea un diccionario utilizando un archivo PWL
- enchant_broker_set_dict_path — Define la ruta del directorio para un backend proporcionado
- enchant_broker_set_ordering — Declara una preferencia para un diccionario de un idioma
- enchant_dict_add — Añadir una palabra a la lista personal de palabras
- enchant_dict_add_to_personal — Alias de enchant_dict_add
- enchant_dict_add_to_session — Añade una palabra a la sesión actual
- enchant_dict_check — Verifica si una palabra está correctamente escrita
- enchant_dict_describe — Describe un diccionario individual
- enchant_dict_get_error — Devuelve el último error de la sesión actual
- enchant_dict_is_added — Si la palabra existe o no en esta sesión de ortografía
- enchant_dict_is_in_session — Alias de enchant_dict_is_added
- enchant_dict_quick_check — Verifica si la palabra está correctamente escrita y proporciona sugerencias
- enchant_dict_store_replacement — Añade una ortografía para una palabra
- enchant_dict_suggest — Sugerir ortografías para una palabra

# La clase EnchantBroker

(PHP 8)

## Introducción

Una clase totalmente opaca que reemplaza los recursos `enchant_broker` a partir de PHP 8.0.0.

## Sinopsis de la Clase

final class EnchantBroker {
}

# La clase EnchantDictionary

(PHP 8)

## Introducción

Una clase totalmente opaca que reemplaza los recursos `enchant_dict` a partir de PHP 8.0.0.

## Sinopsis de la Clase

final class EnchantDictionary {
}

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Tipos de recursos
- Constantes predefinidas
- Ejemplos
- Funciones de Enchant
  - enchant_broker_describe — Enumera los proveedores Enchant
  - enchant_broker_dict_exists — Verifica si un diccionario existe
  - enchant_broker_free — Libera los recursos del patrocinador así como sus diccionarios
  - enchant_broker_free_dict — Libera un recurso de diccionario
  - enchant_broker_get_dict_path — Obtiene la ruta del directorio para un backend proporcionado
  - enchant_broker_get_error — Devuelve el último error de un sponsor
  - enchant_broker_init — Crea un nuevo objeto sponsor
  - enchant_broker_list_dicts — Devuelve una lista de todos los diccionarios disponibles
  - enchant_broker_request_dict — Crear un nuevo diccionario usando una etiqueta
  - enchant_broker_request_pwl_dict — Crea un diccionario utilizando un archivo PWL
  - enchant_broker_set_dict_path — Define la ruta del directorio para un backend proporcionado
  - enchant_broker_set_ordering — Declara una preferencia para un diccionario de un idioma
  - enchant_dict_add — Añadir una palabra a la lista personal de palabras
  - enchant_dict_add_to_personal — Alias de enchant_dict_add
  - enchant_dict_add_to_session — Añade una palabra a la sesión actual
  - enchant_dict_check — Verifica si una palabra está correctamente escrita
  - enchant_dict_describe — Describe un diccionario individual
  - enchant_dict_get_error — Devuelve el último error de la sesión actual
  - enchant_dict_is_added — Si la palabra existe o no en esta sesión de ortografía
  - enchant_dict_is_in_session — Alias de enchant_dict_is_added
  - enchant_dict_quick_check — Verifica si la palabra está correctamente escrita y proporciona sugerencias
  - enchant_dict_store_replacement — Añade una ortografía para una palabra
  - enchant_dict_suggest — Sugerir ortografías para una palabra
- EnchantBroker — La clase EnchantBroker
- EnchantDictionary — La clase EnchantDictionary

# Determina el género de un nombre

# Introducción

La extensión PHP Gender es un puerto del programa gender.c originalmente escrito por Joerg Michael. El objetivo principal de este programa es encontrar el género de un nombre. La base de datos actual contiene más de 40000 nombres de 54 países.

# Instalación/Configuración

## Tabla de contenidos

- Instalación

## Instalación

Esta extensión » PECL no está integrada en PHP.

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/gender.

# Ejemplos

## Tabla de contenidos

- Ejemplo de uso.

## Ejemplo de uso.

Ejemplo de uso de la clase Gender.

Ejemplo #1 Ejemplo de uso.

    <?php

    namespace Gender;

    $género = new Gender;

    $nombre = "Milene";
    $país = Gender::FRANCE;

    $resultado = $género->get($nombre, $país);

    $datos = $género->country($país);

    switch($resultado) {
        case Gender::IS_FEMALE:
            printf("El nombre %s es femenino en %s\n", $nombre, $datos['country']);
        break;

        case Gender::IS_MOSTLY_FEMALE:
            printf("El nombre %s es habitualmente femenino en %s\n", $nombre, $datos['country']);
        break;

        case Gender::IS_MALE:
            printf("El nombre %s es masculino en %s\n", $nombre, $datos['country']);
        break;

        case Gender::IS_MOSTLY_MALE:
            printf("El nombre %s es habitualmente masculino en %s\n", $nombre, $datos['country']);
        break;

        case Gender::IS_UNISEX_NAME:
            printf("El nombre %s es unisex en %s\n", $nombre, $datos['country']);
        break;

        case Gender::IS_A_COUPLE:
            printf("El nombre %s es masculino y femenino en %s\n", $nombre, $datos['country']);
        break;

        case Gender::NAME_NOT_FOUND:
            printf("El nombre %s no se encontró en %s\n", $nombre, $datos['country']);
        break;

        case Gender::ERROR_IN_NAME:
            echo "¡Hay un error con el nombre proporcionado!\n";
        break;

        default:
            echo "¡Ocurrió un error!\n";
        break;

    }

# La clase Gender\Gender

(PECL gender >= 0.6.0)

## Introducción

## Sinopsis de la Clase

class Gender\Gender {
/* Constantes */
const int IS_FEMALE = 70;
const int IS_MOSTLY_FEMALE = 102;
const int IS_MALE = 77;
const int IS_MOSTLY_MALE = 109;
const int IS_UNISEX_NAME = 63;
const int IS_A_COUPLE = 67;
const int NAME_NOT_FOUND = 32;
const int ERROR_IN_NAME = 69;
const int ANY_COUNTRY = 0;
const int BRITAIN = 1;
const int IRELAND = 2;
const int USA = 3;
const int SPAIN = 4;
const int PORTUGAL = 5;
const int ITALY = 6;
const int MALTA = 7;
const int FRANCE = 8;
const int BELGIUM = 9;
const int LUXEMBOURG = 10;
const int NETHERLANDS = 11;
const int GERMANY = 12;
const int EAST_FRISIA = 13;
const int AUSTRIA = 14;
const int SWISS = 15;
const int ICELAND = 16;
const int DENMARK = 17;
const int NORWAY = 18;
const int SWEDEN = 19;
const int FINLAND = 20;
const int ESTONIA = 21;
const int LATVIA = 22;
const int LITHUANIA = 23;
const int POLAND = 24;
const int CZECH_REP = 25;
const int SLOVAKIA = 26;
const int HUNGARY = 27;
const int ROMANIA = 28;
const int BULGARIA = 29;
const int BOSNIA = 30;
const int CROATIA = 31;
const int KOSOVO = 32;
const int MACEDONIA = 33;
const int MONTENEGRO = 34;
const int SERBIA = 35;
const int SLOVENIA = 36;
const int ALBANIA = 37;
const int GREECE = 38;
const int RUSSIA = 39;
const int BELARUS = 40;
const int MOLDOVA = 41;
const int UKRAINE = 42;
const int ARMENIA = 43;
const int AZERBAIJAN = 44;
const int GEORGIA = 45;
const int KAZAKH_UZBEK = 46;
const int TURKEY = 47;
const int ARABIA = 48;
const int ISRAEL = 49;
const int CHINA = 50;
const int INDIA = 51;
const int JAPAN = 52;
const int KOREA = 53;
/* Métodos */
public function __construct(string `$dsn` = ?)
public function connect(string `$dsn`): bool
public function country(int `$country`): array|false
public function get(string `$name`, int `$country` = ?): int
public function isNick(string `$name0`, string `$name1`, int `$country` = ?): array
public function similarNames(string `$name`, int `$country` = ?): array
}

## Constantes predefinidas

`Gender\Gender::IS_FEMALE`
`Gender\Gender::IS_MOSTLY_FEMALE`
`Gender\Gender::IS_MALE`
`Gender\Gender::IS_MOSTLY_MALE`
`Gender\Gender::IS_UNISEX_NAME`
`Gender\Gender::IS_A_COUPLE`
`Gender\Gender::NAME_NOT_FOUND`
`Gender\Gender::ERROR_IN_NAME`
`Gender\Gender::ANY_COUNTRY`
`Gender\Gender::BRITAIN`
`Gender\Gender::IRELAND`
`Gender\Gender::USA`
`Gender\Gender::SPAIN`
`Gender\Gender::PORTUGAL`
`Gender\Gender::ITALY`
`Gender\Gender::MALTA`
`Gender\Gender::FRANCE`
`Gender\Gender::BELGIUM`
`Gender\Gender::LUXEMBOURG`
`Gender\Gender::NETHERLANDS`
`Gender\Gender::GERMANY`
`Gender\Gender::EAST_FRISIA`
`Gender\Gender::AUSTRIA`
`Gender\Gender::SWISS`
`Gender\Gender::ICELAND`
`Gender\Gender::DENMARK`
`Gender\Gender::NORWAY`
`Gender\Gender::SWEDEN`
`Gender\Gender::FINLAND`
`Gender\Gender::ESTONIA`
`Gender\Gender::LATVIA`
`Gender\Gender::LITHUANIA`
`Gender\Gender::POLAND`
`Gender\Gender::CZECH_REP`
`Gender\Gender::SLOVAKIA`
`Gender\Gender::HUNGARY`
`Gender\Gender::ROMANIA`
`Gender\Gender::BULGARIA`
`Gender\Gender::BOSNIA`
`Gender\Gender::CROATIA`
`Gender\Gender::KOSOVO`
`Gender\Gender::MACEDONIA`
`Gender\Gender::MONTENEGRO`
`Gender\Gender::SERBIA`
`Gender\Gender::SLOVENIA`
`Gender\Gender::ALBANIA`
`Gender\Gender::GREECE`
`Gender\Gender::RUSSIA`
`Gender\Gender::BELARUS`
`Gender\Gender::MOLDOVA`
`Gender\Gender::UKRAINE`
`Gender\Gender::ARMENIA`
`Gender\Gender::AZERBAIJAN`
`Gender\Gender::GEORGIA`
`Gender\Gender::KAZAKH_UZBEK`
`Gender\Gender::TURKEY`
`Gender\Gender::ARABIA`
`Gender\Gender::ISRAEL`
`Gender\Gender::CHINA`
`Gender\Gender::INDIA`
`Gender\Gender::JAPAN`
`Gender\Gender::KOREA`

# Gender\Gender::connect

(PECL gender >= 0.6.0)

Gender\Gender::connect — Conexión a un diccionario externo

### Descripción

public function Gender\Gender::connect(string `$dsn`): bool

Conexión a un diccionario externo. Actualmente, solo los flujos son soportados.

### Parámetros

`dsn`
  DSN a abrir.

### Valores devueltos

Un booleano en caso de éxito o de fracaso.

# Gender\Gender::__construct

(PECL gender >= 0.6.0)

Gender\Gender::__construct — Construye un objeto Gender

### Descripción

public function Gender\Gender::__construct(string `$dsn` = ?)

Crea un objeto Gender, conectándose, opcionalmente, a un diccionario externo. Cuando no se proporciona ninguna base de datos, se utilizarán los datos compilados internamente.

### Parámetros

`dsn`
  DSN a abrir.

# Gender\Gender::country

(PECL gender >= 0.8.0)

Gender\Gender::country — Obtiene la representación textual de un país

### Descripción

public function Gender\Gender::country(int `$country`): array|false

Obtiene la representación textual de un país desde la constante de la clase Gender.

### Parámetros

`country`
  Identificador del país (corresponde a una constante de la clase Gender\Gender).

### Valores devueltos

Devuelve un array que contiene los nombres cortos y largos del país en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con Gender\Gender::country()

    $gender = new Gender\Gender;
    var_dump($gender->country(Gender\Gender::BRITAIN));

El ejemplo anterior mostrará:

    array(2) {
      'country_short' =>
      string(2) "UK"
      'country' =>
      string(13) "Great Britain"
    }

# Gender\Gender::get

(PECL gender >= 0.6.0)

Gender\Gender::get — Obtiene el género de un nombre

### Descripción

public function Gender\Gender::get(string `$name`, int `$country` = ?): int

Obtiene el género de un nombre para un país específico.

### Parámetros

`name`
  El nombre a verificar.
`country`
  El identificador del país (una constante de la clase Gender).

### Valores devueltos

Devuelve el género del nombre.

# Gender\Gender::isNick

(PECL gender >= 0.9.0)

Gender\Gender::isNick — Verifica si name0 es un alias de name1

### Descripción

public function Gender\Gender::isNick(string `$name0`, string `$name1`, int `$country` = ?): array

Verifica si name0 es un alias de name1.

### Parámetros

`name0`
  Nombre a verificar.
`name1`
  Nombre a verificar.
`country`
  Identificador del país, identificado por la constante de la clase Gender. Si se omite, ANY_COUNTRY será utilizado.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# Gender\Gender::similarNames

(PECL gender >= 0.9.0)

Gender\Gender::similarNames — Obtiene nombres similares

### Descripción

public function Gender\Gender::similarNames(string `$name`, int `$country` = ?): array

Obtiene nombres similares para el nombre y el país proporcionados.

### Parámetros

`name`
  Nombre a verificar.
`country`
  Identificador del país, identificado por la constante de clase Gender. Si se omite, se utilizará ANY_COUNTRY.

### Valores devueltos

Devuelve un array que contiene los nombres similares encontrados.

## Tabla de contenidos

- Gender\Gender::connect — Conexión a un diccionario externo
- Gender\Gender::__construct — Construye un objeto Gender
- Gender\Gender::country — Obtiene la representación textual de un país
- Gender\Gender::get — Obtiene el género de un nombre
- Gender\Gender::isNick — Verifica si name0 es un alias de name1
- Gender\Gender::similarNames — Obtiene nombres similares

- Instalación/Configuración
  - Instalación
- Ejemplos
  - Ejemplo de uso.
- Gender\Gender — La clase Gender\Gender
  - Gender\Gender::connect — Conexión a un diccionario externo
  - Gender\Gender::__construct — Construye un objeto Gender
  - Gender\Gender::country — Obtiene la representación textual de un país
  - Gender\Gender::get — Obtiene el género de un nombre
  - Gender\Gender::isNick — Verifica si name0 es un alias de name1
  - Gender\Gender::similarNames — Obtiene nombres similares

# Gettext

# Introducción

Las funciones de gettext implementan una API de Soporte de Lenguaje Nativo (NLS de las siglas en inglés Native Language Support) la cual se puede utilizar para internacionalizar las aplicaciones de PHP. Por favor, consulte la documentación de gettext para su sistema para obtener una explicación detallada de estas funciones o vea la documentación en » http://www.gnu.org/software/gettext/manual/gettext.html.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación

## Requerimientos

Para utilizar estas funciones, es necesario descargar e instalar las bibliotecas GNU gettext desde » http://www.gnu.org/software/gettext/gettext.html.

## Instalación

Para incluir soporte para GNU gettext en su instalación de PHP, debe añadir la opción --with-gettext[=DIR] donde DIR es el directorio de la instalación de gettext, por omisión es /usr/local.

# Funciones de Gettext

# _

(PHP 4, PHP 5, PHP 7, PHP 8)

_ — Alias de gettext()

### Descripción

Esta función es un alias de: gettext().

# bind_textdomain_codeset

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

bind_textdomain_codeset — Especifica o recupera el juego de caracteres utilizado para los mensajes del dominio DOMAIN

### Descripción

function bind_textdomain_codeset(string `$domain`, ?string `$codeset` = `null`): string|false

bind_textdomain_codeset() permite recuperar o definir la codificación en la cual los mensajes de `domain` serán devueltos por gettext() y funciones similares.

### Parámetros

`domain`

  El dominio.

`codeset`

  El juego de caracteres. Si `null`, la codificación actualmente definida es devuelta.

### Valores devueltos

Una string en caso de éxito.

### Errores/Excepciones

Lanza una ValueError si `domain` es una string vacía.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Lanza ahora una ValueError si `domain` es una string vacía.
8.4.0 | `codeset` es ahora opcional. Anteriormente, este parámetro debía siempre ser especificado.
8.0.3 | `codeset` es ahora nullable. Anteriormente, no era posible recuperar la codificación actualmente definida.

### Notas

> Nota:

> La información bind_textdomain_codeset() es mantenida por proceso, y no por hilo.

# bindtextdomain

(PHP 4, PHP 5, PHP 7, PHP 8)

bindtextdomain — Especifica o recupera la ruta de un dominio

### Descripción

function bindtextdomain(string `$domain`, ?string `$directory` = `null`): string|false

La función bindtextdomain() define o recupera la ruta de un dominio.

### Parámetros

`domain`

  El dominio.

`directory`

  La ruta hacia el directorio. Una cadena vacía significa el directorio actual. Si `null`, se devuelve el directorio actualmente definido.

### Valores devueltos

La ruta completa para el `domain` actualmente definido, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | `directory` ahora es opcional. Anteriormente, este parámetro debía ser siempre especificado.
8.0.3 | `directory` ahora es nullable. Anteriormente, no era posible recuperar el directorio actualmente definido.

### Ejemplos

Ejemplo #1 Ejemplo con bindtextdomain()

    <?php

    $domain = 'myapp';
    echo bindtextdomain($domain, '/usr/share/myapp/locale');

    ?>

El ejemplo anterior mostrará:

    /usr/share/myapp/locale

### Notas

> Nota:

> La información bindtextdomain() se mantiene por proceso, y no por hilo.

# dcgettext

(PHP 4, PHP 5, PHP 7, PHP 8)

dcgettext — Reemplaza el dominio durante una búsqueda

### Descripción

function dcgettext(string `$domain`, string `$message`, int `$category`): string

Permite reemplazar el dominio actual durante la búsqueda de un mensaje.

### Parámetros

`domain`

  El dominio

`message`

  El mensaje

`category`

  La categoría

### Valores devueltos

Una string en caso de éxito.

### Ver también

- gettext() - Busca un mensaje en el dominio actual

# dcngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

dcngettext — Versión plural de dcgettext

### Descripción

function dcngettext(
string `$domain`,
string `$singular`,
string `$plural`,
int `$count`,
int `$category`
): string

Permite reemplazar el dominio actual para una búsqueda simple en plural de un mensaje.

### Parámetros

`domain`

  El dominio

`singular`

`plural`

`count`

`category`

### Valores devueltos

Una string en caso de éxito.

### Ver también

- ngettext() - Versión plural de gettext

# dgettext

(PHP 4, PHP 5, PHP 7, PHP 8)

dgettext — Reemplaza el dominio actual

### Descripción

function dgettext(string `$domain`, string `$message`): string

dgettext() reemplaza el dominio actual `domain` para una búsqueda simple en `message`.

### Parámetros

`domain`

  El dominio

`message`

  El mensaje

### Valores devueltos

Un string en caso de éxito.

### Errores/Excepciones

Lanza una ValueError si `domain` es un string vacío.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Ahora lanza una ValueError si `domain` es un string vacío.

### Ver también

- gettext() - Busca un mensaje en el dominio actual

# dngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

dngettext — Versión plural de dgettext

### Descripción

function dngettext(
string `$domain`,
string `$singular`,
string `$plural`,
int `$count`
): string

dngettext() permite reemplazar el dominio actual `domain` para una búsqueda simple en plural de un mensaje.

### Parámetros

`domain`

  El dominio

`singular`

`plural`

`count`

### Valores devueltos

Un string en caso de éxito.

### Errores/Excepciones

Genera una ValueError si `domain` es un string vacío.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Genera ahora una ValueError si `domain` es un string vacío.

### Ver también

- ngettext() - Versión plural de gettext

# gettext

(PHP 4, PHP 5, PHP 7, PHP 8)

gettext — Busca un mensaje en el dominio actual

### Descripción

function gettext(string `$message`): string

Busca un mensaje en el dominio actual.

### Parámetros

`message`

  El mensaje a traducir.

### Valores devueltos

Devuelve un string traducido, si se encuentra uno en la tabla de traducción, o bien el mensaje `message`, si no se encuentra.

### Ejemplos

Ejemplo #1 Ejemplo con gettext()

    <?php
    // Selección del alemán
    putenv('LC_ALL=de_DE');
    setlocale(LC_ALL, 'de_DE');

    // Especifica la localización de las tablas de traducción
    bindtextdomain("myPHPApp", "./locale");

    // Elige el dominio
    textdomain("myPHPApp");

    // La traducción se busca en ./locale/de_DE/LC_MESSAGES/myPHPApp.mo

    // Mostrar un mensaje de prueba
    echo gettext("Bienvenido a mi aplicación PHP");

    // O utiliza el alias _() para reemplazar gettext()
    echo _("Que tengas un buen día");
    ?>

### Notas

> Nota:

> Puede utilizarse el carácter guión bajo (_) como alias de esta función.

> Nota:

> Definir un idioma no es suficiente para algunos sistemas operativos y puede ser necesario utilizar la función putenv() para definir la configuración local actual.

### Ver también

- _() - Alias de gettext
- setlocale() - Establece la información de configuración local

# ngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ngettext — Versión plural de gettext

### Descripción

function ngettext(string `$singular`, string `$plural`, int `$count`): string

Versión plural de gettext(). Algunas lenguas tienen más de una forma de mensajes plurales dependiendo del contador.

### Parámetros

`singular`

  El ID singular del mensaje.

`plural`

  El ID plural del mensaje.

`count`

  El número (es decir, número de elementos) para determinar la traducción del número gramatical respectivo.

### Valores devueltos

Devuelve un mensaje plural identificado por `msgid1` y `msgid2` para el contador `n`.

### Ejemplos

Ejemplo #1 Ejemplo con ngettext()

    <?php

    setlocale(LC_ALL, 'cs_CZ');
    printf(ngettext("%d window", "%d windows", 1), 1); // 1 okno
    printf(ngettext("%d window", "%d windows", 2), 2); // 2 okna
    printf(ngettext("%d window", "%d windows", 5), 5); // 5 oken

    ?>

# textdomain

(PHP 4, PHP 5, PHP 7, PHP 8)

textdomain — Define el dominio por defecto

### Descripción

function textdomain(?string `$domain` = `null`): string

Esta función define el dominio de búsqueda a utilizar durante las llamadas a gettext(). Este dominio depende generalmente de la aplicación.

### Parámetros

`domain`

  El nuevo dominio de mensajes, o `null` para recuperar la configuración actual sin modificaciones.

### Valores devueltos

Esta función devuelve el mensaje actual del dominio en caso de éxito, después de una posible modificación.

### Errores/Excepciones

Genera una ValueError si `domain` es un string vacío.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Genera ahora una ValueError si `domain` es un string vacío.
8.4.0 | `domain` ahora es opcional. Anteriormente, este argumento debía especificarse siempre.

### Notas

> Nota:

> La información de textdomain() se mantiene por proceso, y no por hilo.

## Tabla de contenidos

- _ — Alias de gettext
- bind_textdomain_codeset — Especifica o recupera el juego de caracteres utilizado para los mensajes del dominio DOMAIN
- bindtextdomain — Especifica o recupera la ruta de un dominio
- dcgettext — Reemplaza el dominio durante una búsqueda
- dcngettext — Versión plural de dcgettext
- dgettext — Reemplaza el dominio actual
- dngettext — Versión plural de dgettext
- gettext — Busca un mensaje en el dominio actual
- ngettext — Versión plural de gettext
- textdomain — Define el dominio por defecto

- Instalación/Configuración
  - Requerimientos
  - Instalación
- Funciones de Gettext
  - _ — Alias de gettext
  - bind_textdomain_codeset — Especifica o recupera el juego de caracteres utilizado para los mensajes del dominio DOMAIN
  - bindtextdomain — Especifica o recupera la ruta de un dominio
  - dcgettext — Reemplaza el dominio durante una búsqueda
  - dcngettext — Versión plural de dcgettext
  - dgettext — Reemplaza el dominio actual
  - dngettext — Versión plural de dgettext
  - gettext — Busca un mensaje en el dominio actual
  - ngettext — Versión plural de gettext
  - textdomain — Define el dominio por defecto

# iconv

# Introducción

Este módulo es una interfaz hacia la biblioteca iconv. La extensión iconv convierte ficheros entre diversos juegos de caracteres. Los juegos soportados dependen de la implementación de la función `iconv()` en su sistema. Tenga en cuenta que esta función no siempre funciona correctamente en todos los sistemas. En ese caso, sería una buena idea instalar la biblioteca » GNU libiconv.

Esta extensión dispone de muchas funciones útiles para ayudar a escribir scripts multilingües. Consúltense las secciones siguientes para descubrir las nuevas funcionalidades.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución

## Requerimientos

No se requiere nada especial si el sistema es conforme al estándar POSIX, ya que la biblioteca estándar C proporciona iconv. En caso contrario, debe instalarse la biblioteca » libiconv en el sistema.

## Instalación

Esta extensión se encuentra activada por omisión, sin embargo, puede ser desactivada compilando PHP con la opción --without-iconv.

La directiva opcional --with-iconv[=DIR] se utiliza para especificar la ubicación de iconv en el sistema donde PHP es compilado. Si esta directiva no es especificada, únicamente se escanearán las ubicaciones por omisión.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración iconv
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
iconv.input_encoding | "" | `INI_ALL` | Deprecado en PHP 5.6.0.
iconv.output_encoding | "" | `INI_ALL` | Deprecado en PHP 5.6.0.
iconv.internal_encoding | "" | `INI_ALL` | Deprecado en PHP 5.6.0.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

Advertencia

Algunos sistemas (como IBM AIX) utilizan `"ISO8859-1"` en lugar de `"ISO-8859-1"`, por lo que este valor debe ser utilizado en las opciones de configuración así como en los argumentos de las funciones.

`iconv.input_encoding` string
  Advertencia

  Esta funcionalidad está OBSOLETA a partir de PHP 5.6.0. Depender de esta funcionalidad está altamente desaconsejado.

  Los usuarios de PHP 5.6 y versiones posteriores deben dejar esta opción vacía y definir en su lugar la opción input_encoding.

`iconv.output_encoding` string
  Advertencia

  Esta funcionalidad está OBSOLETA a partir de PHP 5.6.0. Depender de esta funcionalidad está altamente desaconsejado.

  Los usuarios de PHP 5.6 y versiones posteriores deben dejar esta opción vacía y definir en su lugar la opción output_encoding.

`iconv.internal_encoding` string
  Advertencia

  Esta funcionalidad está OBSOLETA a partir de PHP 5.6.0. Depender de esta funcionalidad está altamente desaconsejado.

  Los usuarios de PHP 5.6 y versiones posteriores deben dejar esta opción vacía y definir en su lugar la opción `default_charset`.

# Constantes predefinidas

Es posible identificar durante la ejecución, la versión de la biblioteca iconv que se utiliza.

Constantes de implementación `iconv`
Constante | Tipo | Descripción
--- | --- | ---
`ICONV_IMPL` (string) | string | El nombre de la biblioteca
`ICONV_VERSION` (string) | string | La versión de la biblioteca

> Nota:

> La programación de scripts dependientes de versiones específicas, con estas constantes, está fuertemente desaconsejada.

Las constantes siguientes también están disponibles :

Otras constantes `iconv`
Constante | Tipo | Descripción
--- | --- | ---
`ICONV_MIME_DECODE_STRICT` (int) | int | Una máscara utilizada por iconv_mime_decode()
`ICONV_MIME_DECODE_CONTINUE_ON_ERROR` (int) | int | Una máscara utilizada para iconv_mime_decode()

# Funciones de iconv

# Ver también

Ver también funciones de GNU Recode.

# iconv

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv — Convierte una cadena de caracteres de un encodaje a otro

### Descripción

function iconv(string `$from_encoding`, string `$to_encoding`, string `$string`): string|false

Convierte la cadena `string` desde `from_encoding` hacia el encodaje `to_encoding`.

### Parámetros

`from_encoding`

  El encodaje utilizado para interpretar `string`.

`to_encoding`

  El encodaje deseado del resultado.

  Si la cadena `//TRANSLIT` es añadida al argumento `to_encoding`, entonces la transliteración es activada. Esto significa que cuando un carácter no puede ser representado en el juego de caracteres destino, podría ser representado aproximadamente a partir de uno o varios caracteres que representen el mismo carácter. Si la cadena `//IGNORE` es añadida, los caracteres que no puedan ser representados en el juego de caracteres destino serán simplemente ignorados. De lo contrario, se generará una alerta de nivel `E_NOTICE` y la función retornará `false`.

  Precaución

  Si y cómo `//TRANSLIT` funciona exactamente depende de la implementación iconv() del sistema (cf. `ICONV_IMPL`). Algunas implementaciones son conocidas por ignorar `//TRANSLIT`, por lo que la conversión de caracteres ilegales probablemente fallará para `to_encoding`.

`string`

  La string a convertir.

### Valores devueltos

Retorna la string convertida, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con iconv()

    <?php
    $text = "Ceci est le symbole de l'Euro '€'.";

    echo 'Original : ', $text, PHP_EOL;
    echo 'TRANSLIT : ', iconv("UTF-8", "ISO-8859-1//TRANSLIT", $text), PHP_EOL;
    echo 'IGNORE   : ', iconv("UTF-8", "ISO-8859-1//IGNORE", $text), PHP_EOL;
    echo 'Brut     : ', iconv("UTF-8", "ISO-8859-1", $text), PHP_EOL;
    ?>

Resultado del ejemplo anterior es similar a:

    Original : Ceci est le symbole de l'Euro '€'.
    TRANSLIT : Ceci est le symbole de l'Euro 'EUR'.
    IGNORE   : Ceci est le symbole de l'Euro ''.
    Brut     : Ceci est le symbole de l'Euro '
    Notice: iconv(): Detected an illegal character in input string in /Users/macbook/Desktop/- on line 8
    Ceci est le symbole de l'Euro '

### Notas

> Nota:

> El encodaje de caracteres y las opciones disponibles dependen de la implementación de iconv. Si el argumento de `from_encoding` o `to_encoding` no es soportado en el sistema actual, `false` será retornado.

### Ver también

- mb_convert_encoding() - Convertir una cadena de un codificación de caracteres a otra
- UConverter::transcode() - Convierte una cadena de un juego de caracteres a otro

# iconv_get_encoding

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv_get_encoding — Lee el juego de caracteres actual

### Descripción

function iconv_get_encoding(string `$type` = "all"): array|string|false

Devuelve la configuración actual del gestor ob_iconv_handler().

### Parámetros

`type`

  Los valores posibles para el argumento opcional `type` son:

  - all
  - input_encoding
  - output_encoding
  - internal_encoding

### Valores devueltos

Devuelve el valor actual de la variable de configuración en caso de éxito o `false` si ocurre un error.

Si `type` es omitido o diferente de `all` (es decir "todos"), iconv_get_encoding() devuelve un array que contiene todos los valores de estas constantes.

### Ejemplos

Ejemplo #1 Ejemplo con iconv_get_encoding()

    <pre>
    <?php
    iconv_set_encoding("internal_encoding", "UTF-8");
    iconv_set_encoding("output_encoding", "ISO-8859-1");
    var_dump(iconv_get_encoding('all'));
    ?>
    </pre>

El ejemplo anterior mostrará:

    Array
    (
        [input_encoding] => ISO-8859-1
        [output_encoding] => ISO-8859-1
        [internal_encoding] => UTF-8
    )

### Ver también

- iconv_set_encoding() - Modifica el juego de caracteres de codificación actual
- ob_iconv_handler() - Convierte la codificación de caracteres al manejador del buffer de salida

# iconv_mime_decode

(PHP 5, PHP 7, PHP 8)

iconv_mime_decode — Decodifica un campo de encabezado MIME

### Descripción

function iconv_mime_decode(string `$string`, int `$mode` = 0, ?string `$encoding` = `null`): string|false

iconv_mime_decode() decodifica un campo de encabezado MIME.

### Parámetros

`string`

  El encabezado codificado, en forma de string.

`mode`

  `mode` determina una alternativa en caso de que iconv_mime_decode() encuentre un campo de encabezado `MIME` mal formado.

  Máscaras aceptables para la función iconv_mime_decode()
  Valor | Constante | Descripción
  --- | --- | ---
  1 | ICONV_MIME_DECODE_STRICT | Si está definido, el encabezado correspondiente será decodificado siguiendo estrictamente el estándar » RFC2047. Esta opción está desactivada por omisión, ya que existen muchos `clientes de correo` que no siguen este estándar y por lo tanto, producen malos encabezados `MIME`.
  2 | ICONV_MIME_DECODE_CONTINUE_ON_ERROR | Si está definido, iconv_mime_decode() intenta continuar decodificando el encabezado pasado, incluso si aparecen errores.

`encoding`

  El parámetro por omisión `encoding` especifica el juego de caracteres a utilizar para representar el resultado. Si se omite, iconv.internal_encoding será utilizado.

### Valores devueltos

Devuelve un campo `MIME` en caso de éxito, o `false` si ocurre un error durante la decodificación.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `encoding` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con iconv_mime_decode()

    <?php
    // Esto mostrará: "Subject: Prüfung Prüfung"
    echo iconv_mime_decode("Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=",
                           0, "ISO-8859-1");
    ?>

### Ver también

- iconv_mime_decode_headers() - Decodifica múltiples encabezados MIME
- mb_decode_mimeheader() - Decodifica un encabezado MIME
- imap_mime_header_decode() - Decodifica los elementos MIME de un encabezado
- imap_base64() - Decodifica un texto codificado en BASE64
- imap_qprint() - Convierte una string con comillas en una string de 8 bits

# iconv_mime_decode_headers

(PHP 5, PHP 7, PHP 8)

iconv_mime_decode_headers — Decodifica múltiples encabezados `MIME`

### Descripción

function iconv_mime_decode_headers(string `$headers`, int `$mode` = 0, ?string `$encoding` = `null`): array|false

iconv_mime_decode_headers() decodifica múltiples encabezados `MIME`.

### Parámetros

`headers`

  Los encabezados codificados, en forma de string.

`mode`

  `mode` determina el comportamiento de la función, si iconv_mime_decode_headers() encuentra un encabezado `MIME` malformado.

  Mascara aceptada por la función iconv_mime_decode_headers()
  Valor | Constante | Descripción
  --- | --- | ---
  1 | ICONV_MIME_DECODE_STRICT | Si se utiliza, los encabezados son decodificados respetando estrictamente el estándar de la » RFC2047. Esta opción está desactivada por omisión, ya que existen numerosos clientes de correo que no siguen estas especificaciones y que no producen encabezados `MIME` correctos.
  2 | ICONV_MIME_DECODE_CONTINUE_ON_ERROR | Si esta opción está activada, iconv_mime_decode_headers() intenta ignorar los errores de sintaxis y continúa procesando el encabezado dado.

`encoding`

  El parámetro opcional `encoding` especifica el juego de caracteres utilizado para representar el resultado. Si se omite, se utiliza el juego definido en el archivo php.ini iconv.internal_encoding.

### Valores devueltos

Devuelve un array asociativo que contiene los encabezados `MIME` especificados por el parámetro `headers`, o bien `false` si ocurre un error durante el decodificado.

Cada clave del array devuelto contiene un nombre de encabezado distinto, y su valor correspondiente. Si varios campos tienen el mismo nombre, iconv_mime_decode_headers() convierte ese campo en un array indexado, con los valores en su orden de aparición. Cabe señalar que los nombres de los encabezados no son insensibles a mayúsculas/minúsculas.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `encoding` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con iconv_mime_decode_headers()

    <?php
    $headers_string = <<<EOF
    Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=
    To: example@example.com
    Date: Thu, 1 Jan 1970 00:00:00 +0000
    Message-Id: <example@example.com>
    Received: from localhost (localhost [127.0.0.1]) by localhost
        with SMTP id example for <example@example.com>;
        Thu, 1 Jan 1970 00:00:00 +0000 (UTC)
        (envelope-from example-return-0000-example=example.com@example.com)
    Received: (qmail 0 invoked by uid 65534); 1 Thu 2003 00:00:00 +0000

    EOF;

    $headers =  iconv_mime_decode_headers($headers_string, 0, "ISO-8859-1");
    print_r($headers);
    ?>

El ejemplo anterior mostrará:

    Array
    (
        [Subject] => Prüfung Prüfung
        [To] => example@example.com
        [Date] => Thu, 1 Jan 1970 00:00:00 +0000
        [Message-Id] => <example@example.com>
        [Received] => Array
            (
                [0] => from localhost (localhost [127.0.0.1]) by localhost with SMTP id example for <example@example.com>; Thu, 1 Jan 1970 00:00:00 +0000 (UTC) (envelope-from example-return-0000-example=example.com@example.com)
                [1] => (qmail 0 invoked by uid 65534); 1 Thu 2003 00:00:00 +0000
            )

    )

### Ver también

- iconv_mime_decode() - Decodifica un campo de encabezado MIME
- mb_decode_mimeheader() - Decodifica un encabezado MIME
- imap_mime_header_decode() - Decodifica los elementos MIME de un encabezado
- imap_base64() - Decodifica un texto codificado en BASE64
- imap_qprint() - Convierte una string con comillas en una string de 8 bits

# iconv_mime_encode

(PHP 5, PHP 7, PHP 8)

iconv_mime_encode — Construye un encabezado MIME con los campos field_name y field_value

### Descripción

function iconv_mime_encode(string `$field_name`, string `$field_value`, array `$options` = []): string|false

iconv_mime_encode() compone y devuelve una cadena de caracteres que representa un campo encabezado `MIME` similar a:

    Subject: =?ISO-8859-1?Q?Pr=FCfung_f=FCr?= Entwerfen von einer MIME kopfzeile

En el ejemplo anterior, `"Subject"` es el nombre del campo y la parte que comienza por `"=?ISO-8859-1?..."` es el valor del campo.

### Parámetros

`field_name`

  El nombre del campo.

`field_value`

  El valor del campo.

`options`

  Puede controlarse el comportamiento de la función iconv_mime_encode() especificando un array asociativo que contenga la configuración de los elementos en el parámetro `options`. La lista de elementos soportados por iconv_mime_encode() se muestra a continuación. Tenga en cuenta que los nombres de los elementos son sensibles a mayúsculas/minúsculas.

  Lista de elementos soportados por iconv_mime_encode()
  Elemento | Tipo | Descripción | Valor por omisión | Ejemplo
  --- | --- | --- | --- | ---
  scheme | string | Especifica el método de codificación de un campo. Los valores posibles son `"B"` o `"Q"`, donde `"B"` indica que el esquema de codificación será `base64` y `"Q"`, `quoted-printable`. | B | B
  input-charset | string | Especifica el juego de caracteres para representar el primer parámetro `field_name` y el segundo parámetro `field_value`. Si se omite, iconv_mime_encode() utilizará la directiva de configuración iconv.internal_encoding de su php.ini para representarlos. | iconv.internal_encoding | ISO-8859-1
  output-charset | string | Especifica el juego de caracteres a utilizar para componer el encabezado `MIME`. | iconv.internal_encoding | UTF-8
  line-length | int | Especifica la longitud máxima de cada encabezado. Si el encabezado es mayor que la longitud definida por este parámetro, el encabezado resultante será un encabezado compuesto por varias líneas conforme al estándar » RFC2822 - Internet Message Format. Si se omite, la longitud máxima se establecerá en 76 caracteres. | 76 | 996
  line-break-chars | string | Especifica los caracteres de fin de línea. Si se omite, el valor por omisión será `"\r\n"` (`CR` `LF`). Tenga en cuenta que este parámetro siempre se representa como una cadena ASCII en relación con el valor del parámetro `input-charset`. | \r\n | \n

### Valores devueltos

Devuelve un campo `MIME` en caso de éxito, o `false` si ocurre un error durante la codificación.

### Ejemplos

Ejemplo #1 Ejemplo con iconv_mime_encode()

    <?php
    $preferences = array(
        "input-charset" => "ISO-8859-1",
        "output-charset" => "UTF-8",
        "line-length" => 76,
        "line-break-chars" => "\n"
    );
    $preferences["scheme"] = "Q";
    // Esto produce "Subject: =?UTF-8?Q?Pr=C3=BCfung=20Pr=C3=BCfung?="
    echo iconv_mime_encode("Subject", "Prüfung Prüfung", $preferences);

    $preferences["scheme"] = "B";
    // Esto produce "Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?="
    echo iconv_mime_encode("Subject", "Prüfung Prüfung", $preferences);
    ?>

### Ver también

- imap_binary() - Convierte una string de 8 bits en una string en base64
- mb_encode_mimeheader() - Codifica una cadena para un encabezado MIME
- imap_8bit() - Convierte un string de 8 bits en un string codificado en Quoted-Printable
- quoted_printable_encode() - Convierte un string de 8 bits en un string quoted-printable

# iconv_set_encoding

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv_set_encoding — Modifica el juego de caracteres de codificación actual

### Descripción

function iconv_set_encoding(string `$type`, string `$encoding`): bool

Modifica el juego de caracteres actual, y reemplaza el valor actual del argumento `type` por `encoding`.

### Parámetros

`type`

  Los valores posibles de `type` son :

  - input_encoding
  - output_encoding
  - internal_encoding
`encoding`

  El juego de caracteres.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con iconv_set_encoding()

    <?php
    iconv_set_encoding("internal_encoding", "UTF-8");
    iconv_set_encoding("output_encoding", "ISO-8859-1");
    ?>

### Ver también

- iconv_get_encoding() - Lee el juego de caracteres actual
- ob_iconv_handler() - Convierte la codificación de caracteres al manejador del buffer de salida

# iconv_strlen

(PHP 5, PHP 7, PHP 8)

iconv_strlen — Devuelve el número de caracteres de una cadena

### Descripción

function iconv_strlen(string `$string`, ?string `$encoding` = `null`): int|false

A diferencia de strlen(), el valor devuelto por iconv_strlen() es el número de caracteres que forman parte de la secuencia de bytes `string`, lo cual no siempre coincide con el tamaño en bytes de la cadena de caracteres.

### Parámetros

`string`

  La string.

`encoding`

  Si `encoding` es omitido o `null`, `string` se asume que está codificada en iconv.internal_encoding.

### Valores devueltos

Devuelve el número de caracteres de la cadena `string`, en forma de int, o `false` si ocurre un error durante la codificación.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `encoding` ahora es nullable.

### Ver también

- grapheme_strlen() - Lee la longitud de una cadena en número de grafemas
- mb_strlen() - Devuelve la longitud de una cadena
- strlen() - Calcula el tamaño de un string

# iconv_strpos

(PHP 5, PHP 7, PHP 8)

iconv_strpos — Encuentra la posición de la primera ocurrencia de una cadena en otra

### Descripción

function iconv_strpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

Encuentra la posición de la primera ocurrencia de `needle` en `haystack`.

A diferencia de strpos(), el valor devuelto por iconv_strpos() es el número de caracteres que se encuentran antes de `needle`, en lugar de la posición en bytes donde `needle` fue encontrado. Los caracteres son contados basándose en el juego de caracteres especificado por `encoding`.

### Parámetros

`haystack`

  El string completo.

`needle`

  El string a buscar.

`offset`

  El parámetro opcional `offset` especifica la posición desde la cual debe comenzar la búsqueda. Si la posición es negativa, se cuenta desde el final del string.

`encoding`

  Si el parámetro `encoding` es omitido o `null`, `string` será codificado de acuerdo con iconv.internal_encoding.

Si `haystack` o `needle` no son strings, son convertidos a enteros y aplicados como valor ordinal de un carácter.

### Valores devueltos

Devuelve la posición numérica de la primera ocurrencia de `needle` en `haystack`.

Si `needle` no es encontrado, iconv_strpos() devolverá `false`.

Advertencia

Esta función puede retornar `false`, pero también puede retornar un valor equivalente a `false`. Por favor, lea la sección sobre los booleanos para más información. Utilice el operador === para probar el valor de retorno exacto de esta función.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `encoding` ahora es nullable.
7.1.0 | Se añadió soporte para `offset`s negativos.

### Ver también

- strpos() - Busca la posición de la primera ocurrencia en un string
- iconv_strrpos() - Encuentra la posición de la última ocurrencia de un elemento en una cadena
- mb_strpos() - Localiza la primera ocurrencia de un carácter en una cadena

# iconv_strrpos

(PHP 5, PHP 7, PHP 8)

iconv_strrpos — Encuentra la posición de la última ocurrencia de un elemento en una cadena

### Descripción

function iconv_strrpos(string `$haystack`, string `$needle`, ?string `$encoding` = `null`): int|false

Encuentra la última ocurrencia de `needle` en `haystack`.

A diferencia de la función strpos(), el valor devuelto por iconv_strrpos() es el número de caracteres antes de `needle`, en lugar de la posición en bytes de `needle`. Los caracteres son contados basándose en el juego de caracteres `charset`. Los caracteres son contados sobre la base del juego de caracteres `encoding` especificado.

### Parámetros

`haystack`

  La string completa.

`needle`

  La string buscada.

`encoding`

  Si el parámetro opcional `encoding` es omitido o `null`, `string` se asume que está codificado en iconv.internal_encoding.

Si `haystack` o `needle` no son strings, serán convertidos a string y reconocidos como código ASCII de cada carácter.

### Valores devueltos

Devuelve la posición numérica de la última ocurrencia de `needle` en `haystack`.

Si `needle` no es encontrado, iconv_strrpos() devolverá `false`.

Advertencia

Esta función puede retornar `false`, pero también puede retornar un valor equivalente a `false`. Por favor, lea la sección sobre los booleanos para más información. Utilice el operador === para probar el valor de retorno exacto de esta función.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `encoding` ahora es nullable.

### Ver también

- strrpos() - Busca la posición de la última ocurrencia de una subcadena en una cadena
- iconv_strpos() - Encuentra la posición de la primera ocurrencia de una cadena en otra
- mb_strrpos() - Localiza la última ocurrencia de un carácter en una cadena

# iconv_substr

(PHP 5, PHP 7, PHP 8)

iconv_substr — Extrae una parte de una cadena

### Descripción

function iconv_substr(
string `$string`,
int `$offset`,
?int `$length` = `null`,
?string `$encoding` = `null`
): string|false

Extrae una parte de la cadena `string` a partir de la posición `offset` y con una longitud de `length`.

### Parámetros

`string`

  La string original.

`offset`

  Si `offset` no es negativo, iconv_substr() devuelve el segmento de `string` comenzando en el carácter número `offset`, contando desde cero.

  Si `offset` es negativo, iconv_substr() devuelve el segmento comenzando en la posición `offset` caracteres desde el final de la string `string`.

`length`

  Si el parámetro `length` se proporciona y es positivo, el valor devuelto contendrá como máximo `length` caracteres de la porción de cadena que comienza en `offset` (dependiendo del tamaño de la cadena `string`).

  Si `length` se proporciona y es negativo, iconv_substr() extrae la porción externa de `string` desde el carácter número `offset` hasta el carácter número `length`, contando desde el final de la string. En el caso de que `offset` también sea negativo, la posición de inicio se calcula hacia atrás, siguiendo la regla explicada anteriormente.

`encoding`

  Si `encoding` se omite o es `null`, `string` se asume que está codificada en iconv.internal_encoding.

  Tenga en cuenta que `offset` y `length` siempre se consideran como posiciones calculadas sobre la representación ASCII de los caracteres determinados por `encoding`, a diferencia de substr() que se basa siempre en la posición por byte.

### Valores devueltos

Devuelve la porción de `string` especificada por los parámetros `offset` y `length`.

Si `string` es más pequeño que `offset`, se devolverá `false`. Si `string` tiene exactamente `offset` caracteres de longitud, se devolverá una string vacía.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `length` y `encoding` ahora son nullable.
7.0.11 | Si `string` tiene exactamente `offset` caracteres de longitud, se devolverá una cadena vacía. Antes de esta versión, se devolvía `false` en este caso.

### Ver también

- substr() - Devuelve un segmento de string
- mb_substr() - Extrae una subcadena
- mb_strcut() - Corta una parte de string

# ob_iconv_handler

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

ob_iconv_handler — Convierte la codificación de caracteres al manejador del buffer de salida

### Descripción

function ob_iconv_handler(string `$contents`, int `$status`): string

Convierte el string codificado en `internal_encoding` a `output_encoding`.

`internal_encoding` y `output_encoding` deberían estar definidos en el fichero php.ini o en iconv_set_encoding().

### Parámetros

Ver ob_start() para más información sobre los parámetros del manejador.

### Valores devueltos

Ver ob_start() para mas información sobre los valores de retorno del manejador.

### Ejemplos

Ejemplo #1 Ejemplo de ob_iconv_handler()

    <?php
    iconv_set_encoding("internal_encoding", "UTF-8");
    iconv_set_encoding("output_encoding", "ISO-8859-1");
    ob_start("ob_iconv_handler"); // empieza a usarse el buffer de salida
    ?>

### Ver también

- iconv_get_encoding() - Lee el juego de caracteres actual
- iconv_set_encoding() - Modifica el juego de caracteres de codificación actual
- funciones de control de salida

## Tabla de contenidos

- iconv — Convierte una cadena de caracteres de un encodaje a otro
- iconv_get_encoding — Lee el juego de caracteres actual
- iconv_mime_decode — Decodifica un campo de encabezado MIME
- iconv_mime_decode_headers — Decodifica múltiples encabezados MIME
- iconv_mime_encode — Construye un encabezado MIME con los campos field_name y field_value
- iconv_set_encoding — Modifica el juego de caracteres de codificación actual
- iconv_strlen — Devuelve el número de caracteres de una cadena
- iconv_strpos — Encuentra la posición de la primera ocurrencia de una cadena en otra
- iconv_strrpos — Encuentra la posición de la última ocurrencia de un elemento en una cadena
- iconv_substr — Extrae una parte de una cadena
- ob_iconv_handler — Convierte la codificación de caracteres al manejador del buffer de salida

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
- Constantes predefinidas
- Funciones de iconv
  - iconv — Convierte una cadena de caracteres de un encodaje a otro
  - iconv_get_encoding — Lee el juego de caracteres actual
  - iconv_mime_decode — Decodifica un campo de encabezado MIME
  - iconv_mime_decode_headers — Decodifica múltiples encabezados MIME
  - iconv_mime_encode — Construye un encabezado MIME con los campos field_name y field_value
  - iconv_set_encoding — Modifica el juego de caracteres de codificación actual
  - iconv_strlen — Devuelve el número de caracteres de una cadena
  - iconv_strpos — Encuentra la posición de la primera ocurrencia de una cadena en otra
  - iconv_strrpos — Encuentra la posición de la última ocurrencia de un elemento en una cadena
  - iconv_substr — Extrae una parte de una cadena
  - ob_iconv_handler — Convierte la codificación de caracteres al manejador del buffer de salida

# Funciones de internacionalización

# Introducción

La extensión de Internationalization (también llamada Intl) es una interfaz para la biblioteca » ICU, que permite a los desarrolladores PHP realizar operaciones compatibles con configuraciones regionales incluyendo, pero no limitado a esta lista, el formato, la transliteración, la conversión de codificación, operaciones de calendario, la collation » UCA-conforme, la localización de límites de texto y el uso de identificadores de configuración regional, zonas horarias y glifos.

Esta extensión tiende a seguir de cerca la API ICU, lo que hace que quienes tengan experiencia con esta biblioteca en C, C++ o Java puedan encontrar fácilmente su camino en la API PHP. Además, la documentación ICU puede ser muy útil para comprender las funciones ICU.

Intl está constituido por varios módulos, cada uno exponiendo APIs de ICU:

- Collator: proporciona herramientas de comparación de strings, que soporta ordenaciones según convenciones locales.
- Number Formatter: permite mostrar números según convenciones locales, modelos particulares o reglas de visualización. Puede manejar plurales, números, divisas, condiciones y mucho más.
- Message Formatter: permite crear mensajes incorporando datos (como fechas o números) formateados según convenciones locales o particulares; también permite analizar textos para extraer estas informaciones.
- Normalizer: proporciona una función para normalizar un texto en una de las normalizaciones Unicode, y métodos para probar si un string ya está normalizado.
- Locale: proporciona herramientas de interacción con identificadores locales: análisis, composición, búsqueda y filtrado de identificadores locales.
- Calendar: proporciona una clase que puede ser utilizada para operaciones de regionalización de calendario, y obtener información variada como la zona horaria para la configuración local elegida, el primer día de la semana, o si el cambio de hora (verano/invierno) está activado.
- Timezone: proporciona un empaquetado alrededor de » la base de datos "Olson" que contiene información sobre todas las zonas horarias del mundo.
- Date formatter: permite mostrar la fecha y hora en relación con el formato localizado, o el esquema dado o las reglas definidas, y transformar un string en fecha y hora.
- Transliterator: permite obtener una representación latina de un string en diferentes lenguajes.

## Enlaces

- » Varias docs ICU

- » Guía de usuario ICU

- » Algoritmo de collation Unicode

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución

## Requerimientos

Para compilar esta extensión, es necesario instalar la biblioteca » ICU versión 4.0.0 o más reciente. A partir de PHP 7.4.0 se requiere ICU 50.1 o más reciente.

## Instalación

--enable-intl activará la extensión de manera integrada durante la compilación.

Si la biblioteca ICU está instalada en un directorio no estándar, puede ser necesario especificar su ubicación mediante la variable de entorno `LD_LIBRARY_PATH`, para que el compilador dinámico pueda encontrarla:

$ export LD_LIBRARY_PATH=/opt/icu/lib

De lo contrario, si PHP e ICU están instalados en sus directorios por defecto, entonces no se requieren opciones particulares para configure.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración de internacionalización
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
intl.default_locale |  | `INI_ALL` |
intl.error_level | 0 | `INI_ALL` |
intl.use_exceptions | 0 | `INI_ALL` | Disponible a partir de PECL 3.0.0a1

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`intl.default_locale` string

  La configuración local a utilizar con las funciones intl cuando ninguna está especificada (ya sea si se omite en el argumento correspondiente, o si el valor pasado es `NULL`). Estas son configuraciones locales ICU, y no configuraciones locales del sistema. Las configuraciones locales ICU internas así como sus datos pueden ser exploradas aquí » https://unicode-org.github.io/icu/userguide/locale/.

  Por omisión, está vacía, lo que fuerza el uso de la configuración local ICU por omisión. Una vez definida, la configuración ini no puede ser reestablecida a este valor por omisión. No se recomienda utilizar este valor por omisión, sabiendo que depende del entorno del servidor.

`intl.error_level` int

  El tipo de mensajes de error generados cuando ocurre un error en las funciones ICU. Es un nivel de error PHP, como `E_WARNING`. Puede valer `0` para inhibir los mensajes. Esto no afecta los valores devueltos que indican un error o los valores devueltos por la función intl_get_error_code() o por los métodos de clase específicos que permiten recuperar los códigos y mensajes de error.

  El valor por omisión es `0`.

`intl.use_exceptions` int

  Si vale `true`, se emitirá una excepción cuando ocurra un error en una función intl. La excepción será de tipo IntlException. La excepción se emitirá además del mensaje de error generado debido a la definición de la opción de configuración intl.error_level.

  Por omisión, vale `false`.

# Constantes predefinidas

`INTL_ICU_DATA_VERSION` (string)
  Versión de los datos en ICU4C.
`INTL_ICU_VERSION` (string)
  La versión actual de la biblioteca ICU como una cadena decimal separada con puntos.
`INTL_MAX_LOCALE_LEN` (int)
  Limita el tamaño de la configuración local, por defecto a 80 en PHP. Los nombres de configuraciones locales más grandes que este tamaño serán prohibidos.
`IDNA_DEFAULT` (int)
  Prohíbe el tratamiento de los codepoints no asignados en la entrada para las funciones IDN y no verifica si la entrada es conforme a las reglas de nombres de dominio ASCII.
`IDNA_ALLOW_UNASSIGNED` (int)
  Permite el tratamiento de los codepoints no asignados en la entrada para las funciones IDN.
`IDNA_USE_STD3_RULES` (int)
  Verifica si la entrada para las funciones IDN es conforme a las reglas de nombres de dominio ASCII.
`IDNA_CHECK_BIDI` (int)
  Verifica si la entrada es conforme a las reglas BiDi. Ignorado por la implementación IDNA2003, que siempre realiza esta verificación.
`IDNA_CHECK_CONTEXTJ` (int)
  Verifica si la entrada es conforme a las reglas CONTEXTJ. Ignorado por la implementación IDNA2003, ya que esta verificación es nueva en IDNA2008.
`IDNA_NONTRANSITIONAL_TO_ASCII` (int)
  Opción para una ejecución no transicional en la función idn_to_ascii(). La ejecución transicional está activada por defecto. Esta opción es ignorada por la implementación IDNA2003.
`IDNA_NONTRANSITIONAL_TO_UNICODE` (int)
  Opción para una ejecución no transicional en la función idn_to_utf8(). La ejecución transicional está activada por defecto. Esta opción es ignorada por la implementación IDNA2003.
`INTL_IDNA_VARIANT_2003` (int)
  Utiliza el algoritmo IDNA 2003 en la función idn_to_utf8() así como en la función idn_to_ascii(). Este es el comportamiento por defecto. Esta constante y el uso por defecto han sido depreciados a partir de la versión PHP 7.2.0.
`INTL_IDNA_VARIANT_UTS46` (int)
  Utiliza el algoritmo UTS #46 en la función idn_to_utf8() así como en la función idn_to_ascii(). Disponible a partir de ICU 4.6.
`GRAPHEME_EXTR_COUNT` (int)
  El número de graphemas por defecto a extraer.
`GRAPHEME_EXTR_MAXBYTES` (int)
  El número máximo de bytes devueltos.
`GRAPHEME_EXTR_MAXCHARS` (int)
  El número máximo de caracteres UTF-8 devueltos.

Los siguientes errores forman parte de una máscara de bits devuelta por el algoritmo UTS #46 en las funciones idn_to_utf8() y idn_to_ascii().

`IDNA_ERROR_EMPTY_LABEL` (int)
`IDNA_ERROR_LABEL_TOO_LONG` (int)
`IDNA_ERROR_DOMAIN_NAME_TOO_LONG` (int)
`IDNA_ERROR_LEADING_HYPHEN` (int)
`IDNA_ERROR_TRAILING_HYPHEN` (int)
`IDNA_ERROR_HYPHEN_3_4` (int)
`IDNA_ERROR_LEADING_COMBINING_MARK` (int)
`IDNA_ERROR_DISALLOWED` (int)
`IDNA_ERROR_PUNYCODE` (int)
`IDNA_ERROR_LABEL_HAS_DOT` (int)
`IDNA_ERROR_INVALID_ACE_LABEL` (int)
`IDNA_ERROR_BIDI` (int)
`IDNA_ERROR_CONTEXTJ` (int)
`ULOC_ACTUAL_LOCALE` (int)
  La configuración local de donde provienen realmente los datos.
`ULOC_VALID_LOCALE` (int)
  La configuración local más específica soportada por ICU.
`U_AMBIGUOUS_ALIAS_WARNING` (int)
  Este alias de convertidor puede ir a diferentes implementaciones de convertidor.
`U_BAD_VARIABLE_DEFINITION` (int)
  Falta de `'$'` o nombre de variable en doble.
`U_BRK_ASSIGN_ERROR` (int)
  Error de sintaxis en la instrucción de asignación de la regla RBBI.
`U_BRK_ERROR_LIMIT` (int)
  Esto debe ser siempre el último valor para indicar el límite de los fallos del iterador de cortes.
`U_BRK_ERROR_START` (int)
  Inicio de los códigos que indican los fallos del iterador de cortes.
`U_BRK_HEX_DIGITS_EXPECTED` (int)
  Se esperan dígitos hexadecimales como parte de un carácter escapado en una regla.
`U_BRK_INIT_ERROR` (int)
  Fallo en la inicialización. Probablemente faltan datos ICU.
`U_BRK_INTERNAL_ERROR` (int)
  Se ha detectado un error interno (bug).
`U_BRK_MALFORMED_RULE_TAG` (int)
  La etiqueta `{nnn}` en una regla está mal formada.
`U_BRK_MISMATCHED_PAREN` (int)
  Paréntesis no apareados en una regla RBBI.
`U_BRK_NEW_LINE_IN_QUOTED_STRING` (int)
  Falta comilla de cierre en una regla RBBI.
`U_BRK_RULE_EMPTY_SET` (int)
  La regla contiene un conjunto Unicode vacío.
`U_BRK_RULE_SYNTAX` (int)
  Error de sintaxis en la regla RBBI.
`U_BRK_SEMICOLON_EXPECTED` (int)
  Falta punto y coma `';'` al final de una regla RBBI.
`U_BRK_UNCLOSED_SET` (int)
  Conjunto Unicode en una regla RBBI faltando un `']'` de cierre.
`U_BRK_UNDEFINED_VARIABLE` (int)
  Uso de una `$Variable` no definida en una regla RBBI.
`U_BRK_UNRECOGNIZED_OPTION` (int)
  Opción en las reglas RBBI no reconocida.
`U_BRK_VARIABLE_REDFINITION` (int)
  Variable de regla RBBI redefinida.
`U_BUFFER_OVERFLOW_ERROR` (int)
  Un resultado no cabría en el búfer proporcionado.
`U_CE_NOT_FOUND_ERROR` (int)
  Actualmente utilizado únicamente durante el ajuste del tope variable, pero puede ser utilizado generalmente.
`U_COLLATOR_VERSION_MISMATCH` (int)
  La versión del colador no es compatible con la versión base.
`U_DIFFERENT_UCA_VERSION` (int)
  ucol_open encontró una incompatibilidad entre la versión UCA y la versión de la imagen del colador, por lo que el colador fue construido a partir de reglas. Sin impacto en la función posterior.
`U_ENUM_OUT_OF_SYNC_ERROR` (int)
  `UEnumeration` fuera de sincronización con la colección subyacente.
`U_ERROR_LIMIT` (int)
  Alias de `U_PLUGIN_ERROR_LIMIT`.
`U_ERROR_WARNING_LIMIT` (int)
  Debe ser siempre el último valor de advertencia para indicar el límite de las advertencias UErrorCode (último código de advertencia +1).
`U_ERROR_WARNING_START` (int)
  Inicio de los resultados de información (semánticamente exitosos).
`U_FILE_ACCESS_ERROR` (int)
  No se ha podido encontrar el fichero solicitado.
`U_FMT_PARSE_ERROR_LIMIT` (int)
  Límite de los errores de la biblioteca de formato.
`U_FMT_PARSE_ERROR_START` (int)
  Inicio de los errores de la biblioteca de formato.
`U_IDNA_ACE_PREFIX_ERROR` (int)
`U_IDNA_CHECK_BIDI_ERROR` (int)
`U_IDNA_DOMAIN_NAME_TOO_LONG_ERROR` (int)
`U_IDNA_ERROR_LIMIT` (int)
`U_IDNA_ERROR_START` (int)
`U_IDNA_LABEL_TOO_LONG_ERROR` (int)
`U_IDNA_PROHIBITED_ERROR` (int)
`U_IDNA_STD3_ASCII_RULES_ERROR` (int)
`U_IDNA_UNASSIGNED_ERROR` (int)
`U_IDNA_VERIFICATION_ERROR` (int)
`U_IDNA_ZERO_LENGTH_LABEL_ERROR` (int)
`U_ILLEGAL_ARGUMENT_ERROR` (int)
  Indica un valor de argumento incorrecto.
`U_ILLEGAL_CHAR_FOUND` (int)
  Conversión de caracteres: secuencia de entrada ilegal.
`U_ILLEGAL_CHAR_IN_SEGMENT` (int)
  No utilizado a partir de ICU 2.4.
`U_ILLEGAL_CHARACTER` (int)
  Un carácter especial está fuera de su contexto permitido.
`U_ILLEGAL_ESCAPE_SEQUENCE` (int)
  Secuencia de escape ilegal ISO-2022.
`U_ILLEGAL_PAD_POSITION` (int)
  Símbolo de relleno mal ubicado en el patrón numérico.
`U_INDEX_OUTOFBOUNDS_ERROR` (int)
  Intento de acceder a un índice fuera de rango.
`U_INTERNAL_PROGRAM_ERROR` (int)
  Indica un bug en el código de la biblioteca.
`U_INTERNAL_TRANSLITERATOR_ERROR` (int)
  Error interno del sistema de transliterator.
`U_INVALID_CHAR_FOUND` (int)
  Conversión de caracteres: secuencia de entrada no mapeable. En otras APIs: carácter inválido.
`U_INVALID_FORMAT_ERROR` (int)
  El formato de los datos no es el esperado.
`U_INVALID_FUNCTION` (int)
  Una regla `'&fn()'` especifica un transliterator desconocido.
`U_INVALID_ID` (int)
  Una regla `'::id'` especifica un transliterator desconocido.
`U_INVALID_PROPERTY_PATTERN` (int)
  No utilizado a partir de ICU 2.4.
`U_INVALID_RBT_SYNTAX` (int)
  Se pasó una regla `'::id'` al parser de RuleBasedTransliterator.
`U_INVALID_STATE_ERROR` (int)
  La operación solicitada no puede completarse con ICU en su estado actual.
`U_INVALID_TABLE_FILE` (int)
  Archivo de tabla de conversión no encontrado.
`U_INVALID_TABLE_FORMAT` (int)
  Archivo de tabla de conversión encontrado, pero corrupto.
`U_INVARIANT_CONVERSION_ERROR` (int)
  No se puede convertir una cadena `UChar*` a `char*` con el convertidor invariante.
`U_MALFORMED_EXPONENTIAL_PATTERN` (int)
  Símbolo de agrupación en el patrón de exponente.
`U_MALFORMED_PRAGMA` (int)
  Un pragma `'use'` es inválido.
`U_MALFORMED_RULE` (int)
  Los elementos de una regla están mal ubicados.
`U_MALFORMED_SET` (int)
  Un patrón `UnicodeSet` es inválido.
`U_MALFORMED_SYMBOL_REFERENCE` (int)
  No utilizado a partir de ICU 2.4.
`U_MALFORMED_UNICODE_ESCAPE` (int)
  Un patrón de escape Unicode es inválido.
`U_MALFORMED_VARIABLE_DEFINITION` (int)
  Una definición de variable es inválida.
`U_MALFORMED_VARIABLE_REFERENCE` (int)
  Una referencia de variable es inválida.
`U_MEMORY_ALLOCATION_ERROR` (int)
  Error de asignación de memoria.
`U_MESSAGE_PARSE_ERROR` (int)
  No se puede analizar un mensaje (formato de mensaje).
`U_MISMATCHED_SEGMENT_DELIMITERS` (int)
  No utilizado a partir de ICU 2.4.
`U_MISPLACED_ANCHOR_START` (int)
  Un ancla de inicio aparece en una posición ilegal.
`U_MISPLACED_COMPOUND_FILTER` (int)
  Un filtro compuesto está en una posición inválida.
`U_MISPLACED_CURSOR_OFFSET` (int)
  Un desplazamiento del cursor ocurre en una posición ilegal.
`U_MISPLACED_QUANTIFIER` (int)
  Un cuantificador aparece después de un delimitador de fin de segmento.
`U_MISSING_OPERATOR` (int)
  Una regla no contiene ningún operador.
`U_MISSING_RESOURCE_ERROR` (int)
  El recurso solicitado no se encuentra.
`U_MISSING_SEGMENT_CLOSE` (int)
  No utilizado desde ICU 2.4.
`U_MULTIPLE_ANTE_CONTEXTS` (int)
  Más de un contexto anterior.
`U_MULTIPLE_COMPOUND_FILTERS` (int)
  Más de un filtro compuesto.
`U_MULTIPLE_CURSORS` (int)
  Más de un cursor.
`U_MULTIPLE_DECIMAL_SEPARATORS` (int)
  Más de un separador decimal en el modelo numérico.
`U_MULTIPLE_DECIMAL_SEPERATORS` (int)
  Alias de `U_MULTIPLE_DECIMAL_SEPARATORS`.
`U_MULTIPLE_EXPONENTIAL_SYMBOLS` (int)
  Más de un símbolo exponencial en el modelo numérico.
`U_MULTIPLE_PAD_SPECIFIERS` (int)
  Más de un símbolo de relleno en el modelo numérico.
`U_MULTIPLE_PERCENT_SYMBOLS` (int)
  Más de un símbolo de porcentaje en el modelo numérico.
`U_MULTIPLE_PERMILL_SYMBOLS` (int)
  Más de un símbolo de por mil en el modelo numérico.
`U_MULTIPLE_POST_CONTEXTS` (int)
  Más de un contexto posterior.
`U_NO_SPACE_AVAILABLE` (int)
  No hay espacio disponible para la expansión en búfer para el formato árabe.
`U_NO_WRITE_PERMISSION` (int)
  Intento de modificar datos de solo lectura o datos constantes.
`U_PARSE_ERROR` (int)
  Equivalente a Java `ParseException`.
`U_PARSE_ERROR_LIMIT` (int)
  El límite para los errores del Transliterator.
`U_PARSE_ERROR_START` (int)
  Inicio de los errores del Transliterator.
`U_PATTERN_SYNTAX_ERROR` (int)
  Error de sintaxis en el modelo de formato.
`U_PRIMARY_TOO_LONG_ERROR` (int)
  El usuario intentó definir una variable superior a un valor primario de más de dos bytes.
`U_REGEX_BAD_ESCAPE_SEQUENCE` (int)
  Secuencia de escape no reconocida en el modelo.
`U_REGEX_BAD_INTERVAL` (int)
  Error en el intervalo `{min,max}`.
`U_REGEX_ERROR_LIMIT` (int)
  Este debe ser siempre el último valor para indicar el límite de los errores de regexp.
`U_REGEX_ERROR_START` (int)
  Inicio de los códigos que indican fallos de regexp.
`U_REGEX_INTERNAL_ERROR` (int)
  Se detectó un error interno (bug).
`U_REGEX_INVALID_BACK_REF` (int)
  Retro-referencia a un grupo de captura inexistente.
`U_REGEX_INVALID_FLAG` (int)
  Valor inválido para los flags del modo de coincidencia.
`U_REGEX_INVALID_STATE` (int)
  `RegexMatcher` en estado inválido para la operación solicitada.
`U_REGEX_LOOK_BEHIND_LIMIT` (int)
  Las coincidencias del patrón Look-Behind deben tener una longitud máxima acotada.
`U_REGEX_MAX_LT_MIN` (int)
  En `{min,max}`, max es menor que min.
`U_REGEX_MISMATCHED_PAREN` (int)
  Paréntesis anidados incorrectamente en el patrón regexp.
`U_REGEX_NUMBER_TOO_BIG` (int)
  El número decimal es demasiado grande.
`U_REGEX_PROPERTY_SYNTAX` (int)
  Propiedad Unicode incorrecta.
`U_REGEX_RULE_SYNTAX` (int)
  Error de sintaxis en el patrón regexp.
`U_REGEX_SET_CONTAINS_STRING` (int)
  Los regexps no pueden tener `UnicodeSet`s que contengan cadenas.
`U_REGEX_UNIMPLEMENTED` (int)
  Uso de una característica regexp que aún no está implementada.
`U_RESOURCE_TYPE_MISMATCH` (int)
  Se solicita una operación sobre un recurso que no la soporta.
`U_RULE_MASK_ERROR` (int)
  Una regla está oculta por una regla más general anterior.
`U_SAFECLONE_ALLOCATED_WARNING` (int)
  Una operación `SafeClone` requirió la asignación de memoria (solo informativo).
`U_SORT_KEY_TOO_SHORT_WARNING` (int)
  El número de niveles solicitados en `getBound` es mayor que el número de niveles en la clave de ordenación.
`U_STANDARD_ERROR_LIMIT` (int)
  Este debe ser siempre el último valor para indicar el límite de los errores estándar.
`U_STATE_OLD_WARNING` (int)
  ICU debe usar la capa de compatibilidad para construir el servicio. Se debe esperar una degradación del rendimiento/uso de memoria.
`U_STATE_TOO_OLD_ERROR` (int)
  ICU no puede construir un servicio a partir de este estado, ya que ya no es soportado.
`U_STRING_NOT_TERMINATED_WARNING` (int)
  Una cadena de salida no pudo ser terminada en NUL porque la salida `length==destCapacity`.
`U_STRINGPREP_CHECK_BIDI_ERROR` (int)
  Alias de `U_IDNA_CHECK_BIDI_ERROR`.
`U_STRINGPREP_PROHIBITED_ERROR` (int)
  Alias de `U_IDNA_PROHIBITED_ERROR`.
`U_STRINGPREP_UNASSIGNED_ERROR` (int)
  Alias de `U_IDNA_UNASSIGNED_ERROR`.
`U_TOO_MANY_ALIASES_ERROR` (int)
  Hay demasiados alias en la ruta al recurso solicitado. Es muy posible que haya ocurrido una definición de alias circular.
`U_TRAILING_BACKSLASH` (int)
  Una barra invertida colgante.
`U_TRUNCATED_CHAR_FOUND` (int)
  Conversión de caracteres: secuencia de entrada incompleta.
`U_UNCLOSED_SEGMENT` (int)
  Falta un `')'` de cierre.
`U_UNDEFINED_SEGMENT_REFERENCE` (int)
  Una referencia a un segmento no corresponde a un segmento definido.
`U_UNDEFINED_VARIABLE` (int)
  Una referencia a una variable no corresponde a una variable definida.
`U_UNEXPECTED_TOKEN` (int)
  Error de sintaxis en el patrón de formato.
`U_UNMATCHED_BRACES` (int)
  Las llaves no coinciden en el patrón del mensaje.
`U_UNQUOTED_SPECIAL` (int)
  Un carácter especial no fue entrecomillado ni escapado.
`U_UNSUPPORTED_ATTRIBUTE` (int)
  No utilizado a partir de ICU 2.4.
`U_UNSUPPORTED_ERROR` (int)
  La operación solicitada no está soportada en el contexto actual.
`U_UNSUPPORTED_ESCAPE_SEQUENCE` (int)
  Secuencia de escape ISO-2022 no soportada.
`U_UNSUPPORTED_PROPERTY` (int)
  No utilizado a partir de ICU 2.4.
`U_UNTERMINATED_QUOTE` (int)
  Falta una comilla simple de cierre.
`U_USELESS_COLLATOR_ERROR` (int)
  El collator solo tiene opciones y no se ha especificado una base.
`U_USING_DEFAULT_WARNING` (int)
  Una búsqueda en un resource bundle devolvió un resultado de la configuración local raíz (no es un error).
`U_USING_FALLBACK_WARNING` (int)
  Una búsqueda en un resource bundle devolvió un resultado de respaldo (no es un error).
`U_VARIABLE_RANGE_EXHAUSTED` (int)
  Se generaron demasiados sustitutos para el rango de variables dado.
`U_VARIABLE_RANGE_OVERLAP` (int)
  El rango de variables se superpone con caracteres utilizados en las reglas.
`U_ZERO_ERROR` (int)
  Sin error, sin advertencia.

# Ejemplos

## Tabla de contenidos

- Uso básico de esta extensión

## Uso básico de esta extensión

Cada módulo proporciona dos tipos de APIs: una procedimental y otra orientada a objetos. En realidad, ambas son idénticas y están descritas en su correspondiente documentación.

> Nota:

> Todos los strings de entrada deben estar codificados en UTF-8. Del mismo modo, todos los strings de salida deberán estar también en UTF-8.

Ejemplo #1 Ejemplo usando la API procedimental

    <?php
    $cotejamiento  = collator_create('en_US');
    $resultado = collator_compare($cotejamiento, "string#1", "string#2");
    ?>

Ejemplo #2 Ejemplo usando la API orientada a objetos

    <?php
    $cotejamiento = new Collator('en_US');
    $al = $cotejamiento->getLocale(Locale::ACTUAL_LOCALE);
    echo "Configuración regional real: $al\n";

    $formateador = new NumberFormatter('en_US', NumberFormatter::DECIMAL);
    echo $formateador->format(1234567);
    ?>

# La clase Collator

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Introducción

Proporciona herramientas de comparación de strings, con soporte para las convenciones locales en los ordenamientos.

## Sinopsis de la Clase

class Collator {
/* Constantes */
public const int DEFAULT_VALUE;
public const int PRIMARY;
public const int SECONDARY;
public const int TERTIARY;
public const int DEFAULT_STRENGTH;
public const int QUATERNARY;
public const int IDENTICAL;
public const int OFF;
public const int ON;
public const int SHIFTED;
public const int NON_IGNORABLE;
public const int LOWER_FIRST;
public const int UPPER_FIRST;
public const int FRENCH_COLLATION;
public const int ALTERNATE_HANDLING;
public const int CASE_FIRST;
public const int CASE_LEVEL;
public const int NORMALIZATION_MODE;
public const int STRENGTH;
public const int HIRAGANA_QUATERNARY_MODE;
public const int NUMERIC_COLLATION;
public const int SORT_REGULAR;
public const int SORT_STRING;
public const int SORT_NUMERIC;
/* Métodos */
public function __construct(string `$locale`)
public function asort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool
public function compare(string `$string1`, string `$string2`): int|false
public static function create(string `$locale`): ?Collator
public function getAttribute(int `$attribute`): int|false
public function getErrorCode(): int|false
public function getErrorMessage(): string|false
public function getLocale(int `$type`): string|false
public function getSortKey(string `$string`): string|false
public function getStrength(): int
public function setAttribute(int `$attribute`, int `$value`): bool
public function setStrength(int `$strength`): true
public function sort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool
public function sortWithSortKeys(array `&$array`): bool
}

## Constantes predefinidas

`Collator::FRENCH_COLLATION` int

  Se ordenan los strings con diferentes acentos, al final de la cadena. Este atributo se configura automáticamente a On para las locales francesas, y algunas otras. Los usuarios no necesitan configurar explícitamente este atributo. Existe un coste de rendimiento al comparar strings cuando este atributo está a On, pero el tamaño de las claves de ordenación permanece inalterado. Los valores posibles son:

  - `Collator::ON`
  - `Collator::OFF`(por omisión)
  - `Collator::DEFAULT_VALUE`

  Ejemplo #1 Reglas de FRENCH_COLLATION

  - F=OFF cote < coté < côte < côté
  - F=ON cote < côte < coté < côté
`Collator::ALTERNATE_HANDLING`

  El atributo alterno se utiliza para controlar el manejo de caracteres variables de UCA: espacios en blanco, puntuación y símbolos. Si Alternate está configurado a NonIgnorable (N), entonces las diferencias entre estos caracteres tienen la misma importancia que las diferencias entre letras. Si Alternate está configurado a Shifted (S), entonces estos caracteres tendrán una importancia menor. El valor Shifted se utiliza a menudo conjuntamente con Quaternary que vale Strength. En este caso, los espacios en blanco, la puntuación y los símbolos se consideran durante la comparación, pero únicamente si los otros aspectos de la cadena (letras base, acentos y mayúsculas) son todos idénticos. Si Alternate no está configurado a Shifted, no hay entonces diferencia entre una Strength de 3 y una Strength de 4. Para más información y ejemplos, véase Variable_Weighting en » UCA. La razón por la que los valores de Alternate no son simplemente On y Off es que valores adicionales para Alternate podrían ser añadidos en el futuro. La opción UCA Blanked se expresa con un valor de Strength a 3, y Alternate configurado a Shifted. El valor por omisión para la mayoría de locales es NonIgnorable. Si Shifted es seleccionado, puede ser más lento si hay muchas cadenas que son idénticas, excepto por la puntuación: el tamaño de la clave de ordenación permanecerá inalterado, a menos que el nivel de Strength sea elevado.

  Los valores posibles son:

  - `Collator::NON_IGNORABLE`(por omisión)
  - `Collator::SHIFTED`
  - `Collator::DEFAULT_VALUE`

  Ejemplo #2 Reglas ALTERNATE_HANDLING

  - S=3, A=N di Silva < Di Silva < diSilva < U.S.A. < USA
  - S=3, A=S di Silva = diSilva < Di Silva < U.S.A. = USA
  - S=4, A=S di Silva < diSilva < Di Silva < U.S.A. < USA
`Collator::CASE_FIRST` int

  El atributo Case_First se utiliza para controlar si las mayúsculas deben ser consideradas antes que las minúsculas, y viceversa, en ausencia de otros discriminantes. Los valores posibles son Uppercase_First (U) y Lowercase_First (L), más los valores estándar Default y Off. No hay casi diferencia entre Off y Lowercase_First en términos de resultados, por lo que los usuarios típicos no utilizarán Lowercase_First: únicamente Off o Uppercase_First. (Aquellos interesados en las diferencias entre X y L deberán consultar la sección `Collation Customization`). Especificar L o U no cambiará el rendimiento de comparación, pero afectará el tamaño de la clave de ordenación.

  Los valores posibles son:

  - `Collator::OFF`(por omisión)
  - `Collator::LOWER_FIRST`
  - `Collator::UPPER_FIRST`
  - `Collator:DEFAULT`

  Ejemplo #3 Reglas CASE_FIRST

  - C=X or C=L "china" < "China" < "denmark" < "Denmark"
  - C=U "China" < "china" < "Denmark" < "denmark"
`Collator::CASE_LEVEL` int

  El atributo Case_Level se utiliza para ignorar los acentos, pero no la casilla. En estas situaciones, póngase el atributo Strength a Primary, y Case_Level a On. En la mayoría de locales, este atributo está a Off por omisión. Existe un pequeño coste de rendimiento para la comparación de cadenas, e impacto en el tamaño de los índices de ordenación si este atributo está a On.

  Los valores posibles son:

  - `Collator::OFF`(por omisión)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`

  Ejemplo #4 Reglas CASE_LEVEL

  - S=1, E=X role = Role = rôle
  - S=1, E=O role = rôle < Role
`Collator::NORMALIZATION_MODE` int

  El atributo Normalization determina si se debe normalizar totalmente el texto o no, para la comparación. Aunque este atributo esté a Off (que es el caso por omisión para muchas locales), los textos comparados para un uso ordinario serán correctos (para detalles, véase UTN #5). Solo habrá un problema si las marcas de acento no son canónicas. Si este atributo está a On, entonces los mejores resultados están garantizados para todos los textos. Existe un coste de comparación medio si este atributo vale On, dependiendo de la frecuencia de las secuencias que requieren normalización. No hay efecto significativo en el tamaño de los índices de ordenación. Si el texto está en las formas de normalización NFD o NFKD, no es necesario activar la opción de Normalization.

  Los valores posibles son:

  - `Collator::OFF`(por omisión)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::STRENGTH` int

  El servicio de collation ICU soporta muchos niveles de comparación (llamados "Levels", pero también conocidos como "Strengths"). Con estas categorías, ICU puede ordenar strings con precisión, según las convenciones locales. Sin embargo, permitiendo el uso selectivo de los niveles, la búsqueda de un string en un texto puede ser realizada, a partir de diferentes condiciones. Para más información, véase el capítulo collator_set_strength().

  Los valores posibles son:

  - `Collator::PRIMARY`
  - `Collator::SECONDARY`
  - `Collator::TERTIARY`(por omisión)
  - `Collator::QUATERNARY`
  - `Collator::IDENTICAL`
  - `Collator::DEFAULT_VALUE`
`Collator::HIRAGANA_QUATERNARY_MODE` int

  La compatibilidad con JIS x 4061 requiere la introducción de un nivel adicional para distinguir caracteres Hiragana y Katakana. Si la compatibilidad con el estándar es necesaria, entonces este atributo debe ser utilizado a On, y la Strength debe tomar el valor de Quaternary. Esto afectará el tamaño de los índices de ordenación, y el rendimiento de comparaciones de strings.

  Los valores posibles son:

  - `Collator::OFF`(por omisión)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::NUMERIC_COLLATION` int

  Cuando está activado, este atributo genera una clave de collation para los valores numéricos de sub-cadenas. Es un método para que '100' sea ordenado después de '2'.

  Los valores posibles son:

  - `Collator::OFF`(por omisión)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::DEFAULT_VALUE` int
`Collator::PRIMARY` int
`Collator::SECONDARY` int
`Collator::TERTIARY` int
`Collator::DEFAULT_STRENGTH` int
`Collator::QUATERNARY` int
`Collator::IDENTICAL` int
`Collator::OFF` int
`Collator::ON` int
`Collator::SHIFTED` int
`Collator::NON_IGNORABLE` int
`Collator::LOWER_FIRST` int
`Collator::UPPER_FIRST` int
`Collator::SORT_REGULAR` int

`Collator::SORT_STRING` int

`Collator::SORT_NUMERIC` int

## Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Las constantes de clase ahora están tipadas.

# Collator::asort

# collator_asort

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::asort -- collator_asort — Ordena un array manteniendo la asociación de índices

### Descripción

Estilo orientado a objetos

public function Collator::asort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

Estilo procedimental

function collator_asort(Collator `$object`, array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

Esta función ordena un array de modo que los índices mantengan su correlación con los elementos del array con los que están asociados. Se usa principalmente al ordenar arrays asociativos donde el orden real de los elementos es significativo. Los elementos del array tendrán un orden de clasificación según las reglas de configuración regional actuales.

Equivalente a la función estándar de PHP asort().

### Parámetros

`object`

  Objeto Collator.

`array`

  Array de strings a ordenar.

`flags`

  Tipo de ordenación opcional, uno de los siguientes:

  - `Collator::SORT_REGULAR` - compara elementos normalmente (no cambia los tipos)

  - `Collator::SORT_NUMERIC` - compara elementos numéricamente

  - `Collator::SORT_STRING` - compara elementos como strings

  El valor por omisión de `flags` es `Collator::SORT_REGULAR`. También se usa si se especifica un valor de `flags` no válido.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de collator_asort()

    <?php
    $coll = collator_create( 'en_US' );
    $arr = array(
         'a' => '100',
         'b' => '50',
         'c' => '7'
    );
    collator_asort( $coll, $arr, Collator::SORT_NUMERIC );
    var_export( $arr );

    collator_asort( $coll, $arr, Collator::SORT_STRING );
    var_export( $arr );
    ?>

El ejemplo anterior mostrará:

    array (
      'c' => '7',
      'b' => '50',
      'a' => '100',
    )array (
      'a' => '100',
      'b' => '50',
      'c' => '7',
    )

### Ver también

- Constantes de Collator
- collator_sort() - Ordena un array usando el comparador especificado
- collator_sort_with_sort_keys() - Ordenar un array usando el comparador especificado y claves de ordenación

# Collator::compare

# collator_compare

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::compare -- collator_compare — Comparar dos strings Unicode

### Descripción

Estilo orientado a objetos

public function Collator::compare(string `$string1`, string `$string2`): int|false

Estilo procedimental

function collator_compare(Collator `$object`, string `$string1`, string `$string2`): int|false

Comparar dos strings Unicode según las reglas de collation.

### Parámetros

`object`

  Objeto Collator.

`string1`

  El primer string a comparar.

`string2`

  El segundo string a comparar.

### Valores devueltos

Resultados de comparación

- 1 si `string1` es mayor que `string2`;

- 0 si `string1` es igual a `string2`;

- -1 si `string1` es menor que `string2`.

Retorna `false` en caso de fallo.
Advertencia

Esta función puede retornar `false`, pero también puede retornar un valor equivalente a `false`. Por favor, lea la sección sobre los booleanos para más información. Utilice el operador === para probar el valor de retorno exacto de esta función.

### Ejemplos

Ejemplo #1 Ejemplo con collator_compare()

    <?php
    $s1 = 'Hello';
    $s2 = 'hello';

    $coll = collator_create( 'en_US' );
    $res  = collator_compare( $coll, $s1, $s2 );

    if ($res === false) {
        echo collator_get_error_message( $coll );
    } else if( $res > 0 ) {
        echo "s1 es mayor que s2\n";
    } else if( $res < 0 ) {
        echo "s1 es menor que s2\n";
    } else {
        echo "s1 es igual a s2\n";
    }
    ?>

El ejemplo anterior mostrará:

s1 es mayor que s2

Ejemplo #2 Comparar strings sin diacríticos o sensibilidad a mayúsculas/minúsculas

    <?php
    $c = new Collator( 'en' );
    $c->setStrength( Collator::PRIMARY );
    if ( $c->compare( 'Séan', 'Sean' ) == 0 )
    {
        echo "Iguales\n";
    }

El ejemplo anterior mostrará:

Iguales

Este ejemplo solicita al collator que compare solo teniendo en cuenta los caracteres base. La documentación para Collator->setStrength() explica las diferentes fuerzas.

### Ver también

- collator_sort() - Ordena un array usando el comparador especificado

# Collator::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::__construct — Creación de un collator

### Descripción

public function Collator::__construct(string `$locale`)

Creación de una nueva instancia de Collator.

### Parámetros

`locale`

  La configuración local cuyos reglas de ordenación deben ser respetadas. Valores especiales pueden ser pasados en este argumento: si un string vacío es pasado, la configuración local por omisión será utilizada. Si la palabra clave `"root"` es pasada, las reglas » UCA serán utilizadas.

  El atributo Locale es generalmente el atributo más importante para asegurar ordenaciones y comparaciones válidas, en función de las expectativas de los usuarios. El orden por omisión » UCA ordenará únicamente algunas lenguas, tales como holandés o portugués (correctamente significa que el resultado será conforme a las expectativas de los usuarios de estas lenguas). De otro modo, debe ser proporcionada una configuración local adaptada a los usuarios. Por consiguiente, un valor específico de configuración local debe ser proporcionado para asegurar un servicio correcto. La elección de la configuración local configurará los valores de todos sus atributos que son los más pertinentes para una configuración local. Por consiguiente, la mayoría del tiempo, los atributos no necesitan ser explícitamente atribuidos. Al mismo tiempo, la elección de la configuración local tendrá un impacto en las prestaciones de comparación y ordenación.

### Errores/Excepciones

Devuelve un objeto "vacío" en caso de error. Utilizar intl_get_error_code() y / o intl_get_error_message() para obtener más información.

### Ejemplos

Ejemplo #1 Ejemplo con Collator::__construct()

    <?php
    $coll = new Collator('en_CA');
    ?>

### Ver también

- Collator::create() - Creación de un collator
- collator_create() - Creación de un collator

# Collator::create

# collator_create

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::create -- collator_create — Creación de un collator

### Descripción

Estilo orientado a objetos

public static function Collator::create(string `$locale`): ?Collator

Estilo procedimental

function collator_create(string `$locale`): ?Collator

Las cadenas serán comparadas y ordenadas con convenciones locales.

### Parámetros

`locale`

  La configuración local cuya reglas de collation deben ser respetadas. Valores especiales pueden ser pasados en este argumento: si un `string` vacío es pasado, la configuración local por omisión será utilizada. Si la palabra clave `"root"` es pasada, las reglas » UCA serán utilizadas.

### Valores devueltos

Retorna una nueva instancia de la clase Collator, o `null` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con collator_create()

    <?php
    $coll = collator_create( 'en_US' );

    if( !isset( $coll ) ) {
        printf( "Fallo al crear el collator: %s\n", intl_get_error_message() );
        exit( 1 );
    }
    ?>

### Ver también

- Collator::__construct() - Creación de un collator

# Collator::getAttribute

# collator_get_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getAttribute -- collator_get_attribute — Obtener el valor de un atributo de ordenación

### Descripción

Estilo orientado a objetos

public function Collator::getAttribute(int `$attribute`): int|false

Estilo procedimental

function collator_get_attribute(Collator `$object`, int `$attribute`): int|false

Obtiene un valor de un atributo entero de ordenación.

### Parámetros

`object`

  Objeto Collator.

`attribute`

  Atributo para el cual obtener el valor.

### Valores devueltos

Valor del atributo, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de collator_get_attribute()

    <?php
    $coll = collator_create( 'en_CA' );
    $val = collator_get_attribute( $coll, Collator::NUMERIC_COLLATION );
    if( $val === false )
    {
        // Manejar error.
    }
    ?>

### Ver también

- Constantes de Collator
- collator_set_attribute() - Establece un atributo de ordenación
- collator_get_strength() - Obtener la fuerza de ordenación actual

# Collator::getErrorCode

# collator_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getErrorCode -- collator_get_error_code — Lee el último error del collator

### Descripción

Estilo orientado a objetos

public function Collator::getErrorCode(): int|false

Estilo procedimental

function collator_get_error_code(Collator `$object`): int|false

### Parámetros

`object`

  Objeto Collator.

### Valores devueltos

El código de error devuelto por la última llamada a un objeto de la API Collator, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con collator_get_error_code()

    <?php
    $coll = collator_create( 'en_US' );
    if( collator_get_attribute( $coll, Collator::FRENCH_COLLATION ) === false )
            handle_error( collator_get_error_code() );
    ?>

### Ver también

- collator_get_error_message() - Lee el último mensaje de error del collator

# Collator::getErrorMessage

# collator_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getErrorMessage -- collator_get_error_message — Lee el último mensaje de error del collator

### Descripción

Estilo orientado a objetos

public function Collator::getErrorMessage(): string|false

Estilo procedimental

function collator_get_error_message(Collator `$object`): string|false

Lee el último mensaje de error.

### Parámetros

`object`

  Objeto Collator.

### Valores devueltos

La descripción de un error ocurrido durante la última llamada a un método de la API Collator, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con collator_get_error_message()

    <?php
    $coll = collator_create( 'lt' );
    if( collator_compare( $coll, 'y', 'k' ) === false ) {
        echo collator_get_error_message( $coll );
    }
    ?>

### Ver también

- collator_get_error_code() - Lee el último error del collator

# Collator::getLocale

# collator_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getLocale -- collator_get_locale — Lee el nombre de la configuración local de un collator

### Descripción

Estilo orientado a objetos

public function Collator::getLocale(int `$type`): string|false

Estilo procedimental

function collator_get_locale(Collator `$object`, int `$type`): string|false

Lee el nombre de la configuración local de un collator

### Parámetros

`object`

  Objeto Collator.

`type`

  Puede seleccionarse entre un valor válido o un valor literal de la configuración local (utilizando las constantes `Locale::VALID_LOCALE` y `Locale::ACTUAL_LOCALE`, respectivamente).

### Valores devueltos

El nombre de la configuración local para la cual el collator está configurado. Si el collator ha sido configurado a partir de reglas, o si ha ocurrido un error se devuelve `false`.

### Ejemplos

Ejemplo #1 Ejemplo con collator_get_locale()

    <?php
    $coll    = collator_create( 'en_US_California' );
    $res_val = collator_get_locale( $coll, Locale::VALID_LOCALE );
    $res_act = collator_get_locale( $coll, Locale::ACTUAL_LOCALE );
    printf( "Valid locale name: %s\nActual locale name: %s\n",
             $res_val, $res_act );
    ?>

El ejemplo anterior mostrará:

    Requested locale name: en_US_California
    Valid locale name: en_US
    Actual locale name: en

### Ver también

- collator_create() - Creación de un collator

# Collator::getSortKey

# collator_get_sort_key

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 1.0.3)

Collator::getSortKey -- collator_get_sort_key — Obtiene la clave de ordenación para una cadena

### Descripción

Estilo orientado a objetos

public function Collator::getSortKey(string `$string`): string|false

Estilo procedimental

function collator_get_sort_key(Collator `$object`, string `$string`): string|false

Devuelve la clave de collation para una cadena. Las claves de collation pueden compararse directamente en lugar de cadenas, no obstante son específicas de la implementación y pueden cambiar entre versiones de la biblioteca ICU. Las claves de ordenación son generalmente útiles solo en bases de datos u otras circunstancias donde las llamadas a funciones son extremadamente costosas.

### Parámetros

`object`

  Objeto Collator.

`string`

  La cadena desde la cual producir la clave.

### Valores devueltos

Devuelve la clave de collation para la cadena, o `false` si ocurre un error.

Advertencia

Esta función puede retornar `false`, pero también puede retornar un valor equivalente a `false`. Por favor, lea la sección sobre los booleanos para más información. Utilice el operador === para probar el valor de retorno exacto de esta función.

### Ejemplos

Ejemplo #1 Ejemplo collator_get_sort_key()

    <?php

    $s1 = 'Hello';

    $coll = collator_create('en_US');
    $res  = collator_get_sort_key($coll, $s1);

    echo bin2hex($res);
    ?>

Resultado del ejemplo anterior es similar a:

3832404046010901dc08

Ejemplo #2 Collator::getSortKey() : ejemplo con usort()

    <?php

    $data = [
        [ 'name' => '🇳🇱 Derick Rethans', 'linked_account' => 'https://phpc.social/users/derickr' ],
        [ 'name' => 'Elephpant', 'linked_account' => 'https://phpc.social/phpc' ],
        [ 'name' => '🇫🇷 Marcus Bointon', 'linked_account' => 'https://phpc.social/users/Synchro' ],
    ];

    /* Crear el collator */
    $col = new Collator('en');

    /* Ordenar letras mayúsculas antes que minúsculas */
    $col->setAttribute(Collator::CASE_FIRST, Collator::UPPER_FIRST);

    /* Utilizar una función definida por el usuario con sort, que elimina los emojis */
    usort(
        $data,
        function($a, $b) use ($col) {
            /* Eliminar la clase de caracteres 'S' (Símbolos) y los espacios
             * (con trim) */
            $aName = trim(preg_replace('/\p{S}+/u', '', $a['name']));
            $bName = trim(preg_replace('/\p{S}+/u', '', $b['name']));

            /* Crear la clave de ordenación */
            $aKey = $col->getSortKey($aName);
            $bKey = $col->getSortKey($bName);

            /* Utilizar la clave de ordenación para determinar el orden de los elementos */
            return $aKey <=> $bKey;
        }
    );

    var_dump($data);
    ?>

Resultado del ejemplo anterior es similar a:

array(3) {
[0] =>
array(2) {
'name' =>
string(25) "🇳🇱 Derick Rethans"
'linked_account' =>
string(33) "https://phpc.social/users/derickr"
}
[1] =>
array(2) {
'name' =>
string(9) "Elephpant"
'linked_account' =>
string(24) "https://phpc.social/phpc"
}
[2] =>
array(2) {
'name' =>
string(25) "🇫🇷 Marcus Bointon"
'linked_account' =>
string(33) "https://phpc.social/users/Synchro"
}
}

### Ver también

- collator_sort() - Ordena un array usando el comparador especificado
- collator_sort_with_sort_keys() - Ordenar un array usando el comparador especificado y claves de ordenación

# Collator::getStrength

# collator_get_strength

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getStrength -- collator_get_strength — Obtener la fuerza de ordenación actual

### Descripción

Estilo orientado a objetos

public function Collator::getStrength(): int

Estilo procedimental

function collator_get_strength(Collator `$object`): int

### Parámetros

`object`

  Objeto Collator.

### Valores devueltos

Devuelve la fuerza de ordenación actual, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de collator_get_strength()

    <?php
    $coll     = collator_create( 'en_US' );
    $strength = collator_get_strength( $coll );
    ?>

### Ver también

- Constantes de Collator
- collator_set_strength() - Establecer la fuerza de la ordenación
- collator_get_attribute() - Obtener el valor de un atributo de ordenación

# Collator::setAttribute

# collator_set_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::setAttribute -- collator_set_attribute — Establece un atributo de ordenación

### Descripción

Estilo orientado a objetos

public function Collator::setAttribute(int `$attribute`, int `$value`): bool

Estilo procedimental

function collator_set_attribute(Collator `$object`, int `$attribute`, int `$value`): bool

### Parámetros

`object`

  Objeto Collator.

`attribute`

  Atributo.

`value`

  Valor del atributo.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de collator_set_attribute()

    <?php
    $coll = collator_create('en_CA');
    collator_set_attribute($coll, Collator::NORMALIZATION_MODE, Collator::ON);
    ?>

### Ver también

- Constantes de Collator
- collator_get_attribute() - Obtener el valor de un atributo de ordenación
- collator_set_strength() - Establecer la fuerza de la ordenación

# Collator::setStrength

# collator_set_strength

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::setStrength -- collator_set_strength — Establecer la fuerza de la ordenación

### Descripción

Estilo orientado a objetos

public function Collator::setStrength(int `$strength`): true

Estilo procedimental

function collator_set_strength(Collator `$object`, int `$strength`): true

El » Servicio de Ordenación ICU admite muchos niveles de comparación (denominados "Niveles", pero también conocidos como "Fuerzas"). Al permitir que estas categorías puedan emplearse de forma selectiva, la búsqueda de una cadena en un texto puede realizarse con diversas condiciones de coincidencia.

1. Nivel Primario: Normalmente, se utiliza para denotar diferencias entre caracteres base (por ejemplo, "a" < "b"). Es la diferencia más fuerte. Por ejemplo, los diccionarios se dividen en diferentes secciones según el carácter base. También se conoce como `fuerza nivel 1`.

2. Nivel Secundario: Las tildes en los caracteres se consideran diferencias secundarias (por ejemplo, "as" < "às" < "at"). Otras diferencias entre letras también pueden considerarse diferencias secundarias, dependiendo del idioma. Una diferencia secundaria se ignora cuando existe una diferencia primaria en cualquier parte de las cadenas. También se conoce como `fuerza nivel 2`.

   > Nota:

   > Nota: En algunos idiomas (como el danés), ciertas letras acentuadas se consideran caracteres base separados. Sin embargo, en la mayoría de los idiomas, una letra acentuada solo tiene una diferencia secundaria respecto a la versión sin acentuar de esa letra.

3. Nivel Terciario: Las diferencias entre mayúsculas y minúsculas en los caracteres se distinguen en el nivel terciario (por ejemplo, "ao" < "Ao" < "aò"). Además, una variante de una letra difiere de la forma base en el nivel terciario (como "a" y "𝒶"). Otro ejemplo es la diferencia entre Kana grande y pequeña. Una diferencia terciaria se ignora cuando existe una diferencia primaria o secundaria en cualquier parte de las cadenas. También se conoce como `fuerza nivel 3`.

4. Nivel Cuaternario: Cuando la puntuación se ignora (consulte Ignorar puntuaciones) en los niveles 1-3, puede utilizarse un nivel adicional para distinguir palabras con y sin puntuación (por ejemplo, "ab" < "a-b" < "aB"). Esta diferencia se ignora cuando existe una diferencia primaria, secundaria o terciaria. También se conoce como `fuerza nivel 4`. El nivel cuaternario solo debe utilizarse si se requiere ignorar la puntuación o al procesar texto en japonés (consulte Procesamiento de Hiragana).

5. Nivel Idéntico: Cuando todos los demás niveles son iguales, el nivel idéntico se utiliza como desempate. Los valores de punto de código Unicode de la forma NFD de cada cadena se comparan en este nivel, por si no hubiera diferencias en los niveles 1-4. Por ejemplo, los signos de entonación hebreos solo se distinguen en este nivel. Este nivel debe utilizarse con moderación, ya que la diferencia de valores de punto de código entre dos cadenas es un suceso extremadamente raro. El uso de este nivel reduce considerablemente el rendimiento tanto para la comparación incremental como para la generación de claves de ordenación (además de aumentar la longitud de la clave de ordenación). También se conoce como `fuerza nivel 5`.

Por ejemplo, las personas pueden optar por ignorar las tildes o ignorar las tildes y las mayúsculas/minúsculas al buscar texto. Casi todos los caracteres se distinguen por los tres primeros niveles, y en la mayoría de los entornos regionales el valor por omisión es, por tanto, el Terciario. Sin embargo, si Alternate se establece en Shifted, entonces la fuerza Cuaternaria puede utilizarse para desempatar entre espacios en blanco, puntuaciones y símbolos que, de otro modo, se ignorarían. Si se requieren distinciones muy finas entre caracteres, puede utilizarse la fuerza Idéntica (por ejemplo, la fuerza Idéntica distingue entre la A pequeña negrita matemática y la A pequeña cursiva matemática). No obstante, el uso de niveles superiores al Terciario o la fuerza Idéntica genera claves de ordenación significativamente más largas y un rendimiento más lento en la comparación de cadenas iguales.

### Parámetros

`object`

  Objeto Collator.

`strength`

  Fuerza a establecer.

  Los valores posibles son:

  - `Collator::PRIMARY`

  - `Collator::SECONDARY`

  - `Collator::TERTIARY`

  - `Collator::QUATERNARY`

  - `Collator::IDENTICAL`

  - `Collator::DEFAULT_STRENGTH`

### Valores devueltos

Retorna siempre `true`.

### Ejemplos

Ejemplo #1 Ejemplo de collator_set_strength()

    <?php
    $arr  = array( 'aò', 'Ao', 'ao' );
    $coll = collator_create( 'en_US' );

    // Ordenar el array usando la fuerza por omisión.
    collator_sort( $coll, $arr );
    var_export( $arr );

    // Ordenar el array usando la fuerza primaria.
    collator_set_strength( $coll, Collator::PRIMARY );
    collator_sort( $coll, $arr );
    var_export( $arr );
    ?>

El ejemplo anterior mostrará:

    array (
      0 => 'ao',
      1 => 'Ao',
      2 => 'aò',
    )
    array (
      0 => 'aò',
      1 => 'Ao',
      2 => 'ao',
    )

### Ver también

- Constantes de Collator
- collator_get_strength() - Obtener la fuerza de ordenación actual

# Collator::sort

# collator_sort

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::sort -- collator_sort — Ordena un array usando el comparador especificado

### Descripción

Estilo orientado a objetos

public function Collator::sort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

Estilo procedimental

function collator_sort(Collator `$object`, array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

Esta función ordena un array según las reglas de la configuración regional actual.

Equivalente a la función estándar de PHP sort().

### Parámetros

`object`

  Objeto Collator.

`array`

  Array de strings a ordenar.

`flags`

  Tipo de ordenación opcional, uno de los siguientes:

  - `Collator::SORT_REGULAR` - compara los elementos normalmente (no cambia los tipos)

  - `Collator::SORT_NUMERIC` - compara los elementos numéricamente

  - `Collator::SORT_STRING` - compara los elementos como strings

  El tipo de ordenación por omisión es `Collator::SORT_REGULAR`. También se utiliza si se especifica un valor no válido para `flags`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de collator_sort()

    <?php
    $coll = collator_create( 'en_US' );
    $arr  = array( 'at', 'às', 'as' );

    var_export( $arr );
    collator_sort( $coll, $arr );
    var_export( $arr );
    ?>

El ejemplo anterior mostrará:

    array (
      0 => 'at',
      1 => 'às',
      2 => 'as',
    )array (
      0 => 'as',
      1 => 'às',
      2 => 'at',
    )

### Ver también

- Constantes de Collator
- collator_asort() - Ordena un array manteniendo la asociación de índices
- collator_sort_with_sort_keys() - Ordenar un array usando el comparador especificado y claves de ordenación

# Collator::sortWithSortKeys

# collator_sort_with_sort_keys

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::sortWithSortKeys -- collator_sort_with_sort_keys — Ordenar un array usando el comparador especificado y claves de ordenación

### Descripción

Estilo orientado a objetos

public function Collator::sortWithSortKeys(array `&$array`): bool

Estilo procedimental

function collator_sort_with_sort_keys(Collator `$object`, array `&$array`): bool

Similar a collator_sort() pero utiliza claves de ordenación de ICU producidas por ucol_getSortKey() para ganar más velocidad en arrays grandes.

### Parámetros

`object`

  Objeto Collator.

`array`

  Array de strings a ordenar

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de collator_sort_with_sort_keys()

    <?php
    $arr  = array( 'Köpfe', 'Kypper', 'Kopfe' );
    $coll = collator_create( 'sv' );

    collator_sort_with_sort_keys( $coll, $arr );
    var_export( $arr );
    ?>

El ejemplo anterior mostrará:

    array (
      0 => 'Kopfe',
      1 => 'Kypper',
      2 => 'Köpfe',
    )

### Ver también

- Constantes de Collator
- collator_sort() - Ordena un array usando el comparador especificado
- collator_asort() - Ordena un array manteniendo la asociación de índices

## Tabla de contenidos

- Collator::asort — Ordena un array manteniendo la asociación de índices
- Collator::compare — Comparar dos strings Unicode
- Collator::__construct — Creación de un collator
- Collator::create — Creación de un collator
- Collator::getAttribute — Obtener el valor de un atributo de ordenación
- Collator::getErrorCode — Lee el último error del collator
- Collator::getErrorMessage — Lee el último mensaje de error del collator
- Collator::getLocale — Lee el nombre de la configuración local de un collator
- Collator::getSortKey — Obtiene la clave de ordenación para una cadena
- Collator::getStrength — Obtener la fuerza de ordenación actual
- Collator::setAttribute — Establece un atributo de ordenación
- Collator::setStrength — Establecer la fuerza de la ordenación
- Collator::sort — Ordena un array usando el comparador especificado
- Collator::sortWithSortKeys — Ordenar un array usando el comparador especificado y claves de ordenación

# La clase NumberFormatter

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Introducción

Los programas almacenan y manipulan números utilizando una representación local, binaria e independiente. Al mostrar un número, este se convierte en una versión particular. Por ejemplo, un número como 12345.67 se escribe "12,345.67" en los USA, "12 345,67" en Francia y "12.345,67" en Alemania.

Al llamar a los métodos proporcionados por NumberFormatter, se pueden formatear números, montos de divisas y porcentajes, según las convenciones locales. NumberFormatter tiene en cuenta las convenciones, por lo que debe crearse un nuevo objeto NumberFormatter para cada convención. Las métodos de NumberFormatter formatean tipos primitivos como números decimales, y producen un string.

Para las monedas, se puede utilizar el formato monetario para crear un formateador que devuelve un string, con el símbolo de divisa apropiado. Por supuesto, NumberFormatter no conoce los tipos de cambio, por lo que el formato se realizará, cualquiera sea la divisa solicitada. Esto significa que el mismo número tendrá diferentes valores monetarios según la configuración local. Por ejemplo, el número 9988776.65 se mostrará:

- 9 988 776,65 € en Francia
- 9.988.776,65 € en Alemania
- $9,988,776.65 en los USA

Para formatear porcentajes, debe crearse un formateador local, con un tipo de formato porcentaje. Con este formateador, una fracción decimal como 0.75 se mostrará como 75%.

Para formatos más complejos, como números escritos literalmente, se utilizan formateadores basados en reglas.

## Sinopsis de la Clase

class NumberFormatter {
/* Constantes */
public const int PATTERN_DECIMAL;
public const int DECIMAL;
public const int DECIMAL_COMPACT_SHORT;
public const int DECIMAL_COMPACT_LONG;
public const int CURRENCY;
public const int PERCENT;
public const int SCIENTIFIC;
public const int SPELLOUT;
public const int ORDINAL;
public const int DURATION;
public const int PATTERN_RULEBASED;
public const int IGNORE;
public const int CURRENCY_ISO;
public const int CURRENCY_PLURAL;
public const int CURRENCY_ACCOUNTING;
public const int CASH_CURRENCY;
public const int CURRENCY_STANDARD;
public const int DEFAULT_STYLE;
public const int ROUND_CEILING;
public const int ROUND_FLOOR;
public const int ROUND_DOWN;
public const int ROUND_UP;
public const int ROUND_TOWARD_ZERO;
public const int ROUND_AWAY_FROM_ZERO;
public const int ROUND_HALFEVEN;
public const int ROUND_HALFODD;
public const int ROUND_HALFDOWN;
public const int ROUND_HALFUP;
public const int PAD_BEFORE_PREFIX;
public const int PAD_AFTER_PREFIX;
public const int PAD_BEFORE_SUFFIX;
public const int PAD_AFTER_SUFFIX;
public const int PARSE_INT_ONLY;
public const int GROUPING_USED;
public const int DECIMAL_ALWAYS_SHOWN;
public const int MAX_INTEGER_DIGITS;
public const int MIN_INTEGER_DIGITS;
public const int INTEGER_DIGITS;
public const int MAX_FRACTION_DIGITS;
public const int MIN_FRACTION_DIGITS;
public const int FRACTION_DIGITS;
public const int MULTIPLIER;
public const int GROUPING_SIZE;
public const int ROUNDING_MODE;
public const int ROUNDING_INCREMENT;
public const int FORMAT_WIDTH;
public const int PADDING_POSITION;
public const int SECONDARY_GROUPING_SIZE;
public const int SIGNIFICANT_DIGITS_USED;
public const int MIN_SIGNIFICANT_DIGITS;
public const int MAX_SIGNIFICANT_DIGITS;
public const int LENIENT_PARSE;
public const int POSITIVE_PREFIX;
public const int POSITIVE_SUFFIX;
public const int NEGATIVE_PREFIX;
public const int NEGATIVE_SUFFIX;
public const int PADDING_CHARACTER;
public const int CURRENCY_CODE;
public const int DEFAULT_RULESET;
public const int PUBLIC_RULESETS;
public const int DECIMAL_SEPARATOR_SYMBOL;
public const int GROUPING_SEPARATOR_SYMBOL;
public const int PATTERN_SEPARATOR_SYMBOL;
public const int PERCENT_SYMBOL;
public const int ZERO_DIGIT_SYMBOL;
public const int DIGIT_SYMBOL;
public const int MINUS_SIGN_SYMBOL;
public const int PLUS_SIGN_SYMBOL;
public const int CURRENCY_SYMBOL;
public const int INTL_CURRENCY_SYMBOL;
public const int MONETARY_SEPARATOR_SYMBOL;
public const int EXPONENTIAL_SYMBOL;
public const int PERMILL_SYMBOL;
public const int PAD_ESCAPE_SYMBOL;
public const int INFINITY_SYMBOL;
public const int NAN_SYMBOL;
public const int SIGNIFICANT_DIGIT_SYMBOL;
public const int MONETARY_GROUPING_SEPARATOR_SYMBOL;
public const int TYPE_DEFAULT;
public const int TYPE_INT32;
public const int TYPE_INT64;
public const int TYPE_DOUBLE;
public const int TYPE_CURRENCY;
/* Métodos */
public function __construct(string `$locale`, int `$style`, ?string `$pattern` = `null`)
public static function create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter
public function format(int|float `$num`, int `$type` = `NumberFormatter::TYPE_DEFAULT`): string|false
public function formatCurrency(float `$amount`, string `$currency`): string|false
public function getAttribute(int `$attribute`): int|float|false
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false
public function getPattern(): string|false
public function getSymbol(int `$symbol`): string|false
public function getTextAttribute(int `$attribute`): string|false
public function parse(string `$string`, int `$type` = `NumberFormatter::TYPE_DOUBLE`, int `&$offset` = `null`): int|float|false
public function parseCurrency(string `$string`, string `&$currency`, int `&$offset` = `null`): float|false
public function setAttribute(int `$attribute`, int|float `$value`): bool
public function setPattern(string `$pattern`): bool
public function setSymbol(int `$symbol`, string `$value`): bool
public function setTextAttribute(int `$attribute`, string `$value`): bool
}

## Constantes predefinidas

## Tipos de formato

Estos estilos son utilizados por numfmt_create() para definir el tipo de formateador.

`NumberFormatter::PATTERN_DECIMAL` int
  Formato decimal definido por un patrón
`NumberFormatter::DECIMAL` int
  Formato decimal
`NumberFormatter::DECIMAL_COMPACT_SHORT` int
  Formato decimal expresado en notación compacta (forma corta), p.ej. "23K", "45B". Disponible a partir de PHP 8.5.0 e ICU 56.
`NumberFormatter::DECIMAL_COMPACT_LONG` int
  Formato decimal expresado en notación compacta (forma larga), p.ej. "23 thousand", "45 billion". Disponible a partir de PHP 8.5.0 e ICU 56.
`NumberFormatter::CURRENCY` int
  Formato monetario
`NumberFormatter::CURRENCY_ISO` int
  Formato monetario ISO (p.ej. "USD1.00"). Disponible a partir de PHP 8.5.0.
`NumberFormatter::CURRENCY_PLURAL` int
  Formato monetario plural (p.ej. "1.00 US dollar" y "3.00 US dollars"). Disponible a partir de PHP 8.5.0.
`NumberFormatter::CASH_CURRENCY` int
  Símbolo monetario dado el uso CASH, p.ej. "NT$3" en lugar de "NT$3.23". Disponible a partir de PHP 8.5.0 e ICU 54.
`NumberFormatter::CURRENCY_STANDARD` int
  Símbolo monetario, p.ej. "$1.00", utilizando estilo no contable para valores negativos (p.ej. signo menos). Disponible a partir de PHP 8.5.0 e ICU 56.
`NumberFormatter::PERCENT` int
  Formato porcentual
`NumberFormatter::SCIENTIFIC` int
  Formato científico
`NumberFormatter::SPELLOUT` int
  Formato literal, basado en reglas
`NumberFormatter::ORDINAL` int
  Formato ordinal, basado en reglas
`NumberFormatter::DURATION` int
  Formato de duración, basado en reglas
`NumberFormatter::PATTERN_RULEBASED` int
  Formato de patrón, basado en reglas
`NumberFormatter::CURRENCY_ACCOUNTING` int
  Formato monetario para contabilidad, por ejemplo, `($3.00)` para un monto de moneda negativo en lugar de `-$3.00`. Disponible a partir de PHP 7.4.1 y ICU 53.
`NumberFormatter::DEFAULT_STYLE` int
  Formato por defecto para las convenciones locales
`NumberFormatter::IGNORE` int
  Alias de PATTERN_DECIMAL

## Especificadores de formato de número

Estas constantes definen el método de análisis y formato de los números. Deben ser utilizadas como argumentos de las funciones numfmt_format() y numfmt_parse().

`NumberFormatter::TYPE_DEFAULT` int
  Deriva el tipo desde el tipo de variable
`NumberFormatter::TYPE_INT32` int
  Formatea/analiza un entero de 32 bits
`NumberFormatter::TYPE_INT64` int
  Formatea/analiza un entero de 64 bits
`NumberFormatter::TYPE_DOUBLE` int
  Formatea/analiza un número decimal
`NumberFormatter::TYPE_CURRENCY` int
  Formatea/analiza un valor monetario. Deprecado a partir de PHP 8.3.0

## Atributos de formato de número

Atributos de formatos de número utilizados por numfmt_get_attribute() y numfmt_set_attribute().

`NumberFormatter::PARSE_INT_ONLY` int
  Analiza únicamente los enteros.
`NumberFormatter::GROUPING_USED` int
  Separador de grupos.
`NumberFormatter::DECIMAL_ALWAYS_SHOWN` int
  Muestra siempre una coma decimal.
`NumberFormatter::MAX_INTEGER_DIGITS` int
  Número máximo de dígitos.
`NumberFormatter::MIN_INTEGER_DIGITS` int
  Número mínimo de dígitos.
`NumberFormatter::INTEGER_DIGITS` int
  Número de dígitos.
`NumberFormatter::MAX_FRACTION_DIGITS` int
  Número máximo de decimales.
`NumberFormatter::MIN_FRACTION_DIGITS` int
  Número mínimo de decimales.
`NumberFormatter::FRACTION_DIGITS` int
  Número de decimales.
`NumberFormatter::MULTIPLIER` int
  Multiplicador.
`NumberFormatter::GROUPING_SIZE` int
  Tamaño de agrupamiento.
`NumberFormatter::ROUNDING_MODE` int
  Modo de redondeo.
`NumberFormatter::ROUNDING_INCREMENT` int
  Incremento de redondeo.
`NumberFormatter::FORMAT_WIDTH` int
  El ancho de relleno para el formato de un número.
`NumberFormatter::PADDING_POSITION` int
  La posición en la que se realiza el relleno. Véase las constantes de relleno para tener los diferentes valores posibles.
`NumberFormatter::SECONDARY_GROUPING_SIZE` int
  Tamaño secundario de agrupamiento.
`NumberFormatter::SIGNIFICANT_DIGITS_USED` int
  Utiliza los dígitos significativos.
`NumberFormatter::MIN_SIGNIFICANT_DIGITS` int
  Número mínimo de dígitos significativos.
`NumberFormatter::MAX_SIGNIFICANT_DIGITS` int
  Número máximo de dígitos significativos.
`NumberFormatter::LENIENT_PARSE` int
  Modo de análisis utilizado por los formatos basados en reglas.

## Atributos de texto de formato de número

Atributos de texto para los formatos de números, utilizados por numfmt_get_text_attribute() y numfmt_set_text_attribute().

`NumberFormatter::POSITIVE_PREFIX` int
  Prefijo positivo.
`NumberFormatter::POSITIVE_SUFFIX` int
  Sufijo positivo.
`NumberFormatter::NEGATIVE_PREFIX` int
  Prefijo negativo.
`NumberFormatter::NEGATIVE_SUFFIX` int
  Sufijo negativo.
`NumberFormatter::PADDING_CHARACTER` int
  El carácter a utilizar para rellenar los formatos hasta el tamaño.
`NumberFormatter::CURRENCY_CODE` int
  El código de moneda ISO.
`NumberFormatter::DEFAULT_RULESET` int
  El conjunto de reglas por defecto. Solo es utilizable con los formateadores basados en reglas.
`NumberFormatter::PUBLIC_RULESETS` int
  El conjunto de reglas públicas. Esto solo está disponible con los formateadores basados en reglas. Es un atributo de solo lectura. Las reglas públicas se devuelven en forma de una sola cadena, y cada regla está delimitada por un punto y coma ';'.

## Especificación de los símbolos de formato

Los símbolos de formato utilizados por numfmt_get_symbol() y numfmt_set_symbol().

`NumberFormatter::DECIMAL_SEPARATOR_SYMBOL` int
  El separador decimal.
`NumberFormatter::GROUPING_SEPARATOR_SYMBOL` int
  El separador de grupos.
`NumberFormatter::PATTERN_SEPARATOR_SYMBOL` int
  El separador de patrón.
`NumberFormatter::PERCENT_SYMBOL` int
  El símbolo de porcentaje.
`NumberFormatter::ZERO_DIGIT_SYMBOL` int
  Cero.
`NumberFormatter::DIGIT_SYMBOL` int
  Un carácter que representa un dígito en un patrón.
`NumberFormatter::MINUS_SIGN_SYMBOL` int
  El signo menos.
`NumberFormatter::PLUS_SIGN_SYMBOL` int
  El signo más.
`NumberFormatter::CURRENCY_SYMBOL` int
  El símbolo de moneda.
`NumberFormatter::INTL_CURRENCY_SYMBOL` int
  El símbolo internacional de moneda.
`NumberFormatter::MONETARY_SEPARATOR_SYMBOL` int
  El separador monetario.
`NumberFormatter::EXPONENTIAL_SYMBOL` int
  El símbolo exponencial.
`NumberFormatter::PERMILL_SYMBOL` int
  El símbolo por mil.
`NumberFormatter::PAD_ESCAPE_SYMBOL` int
  El carácter de escape de símbolos.
`NumberFormatter::INFINITY_SYMBOL` int
  El símbolo de infinito.
`NumberFormatter::NAN_SYMBOL` int
  El símbolo "no es un número".
`NumberFormatter::SIGNIFICANT_DIGIT_SYMBOL` int
  El símbolo de dígitos significativos.
`NumberFormatter::MONETARY_GROUPING_SEPARATOR_SYMBOL` int
  El separador de grupos monetarios.

## Modos de redondeo

Los modos de redondeo utilizados por las funciones numfmt_get_attribute() y numfmt_set_attribute() con el atributo `NumberFormatter::ROUNDING_MODE`.

`NumberFormatter::ROUND_AWAY_FROM_ZERO`
  Alias de `NumberFormatter::ROUND_UP`.
`NumberFormatter::ROUND_CEILING`
  Modo de redondeo hacia el infinito positivo.
`NumberFormatter::ROUND_DOWN` int
  Modo de redondeo hacia cero.
`NumberFormatter::ROUND_FLOOR` int
  Modo de redondeo hacia el infinito negativo.
`NumberFormatter::ROUND_HALFDOWN` int
  Modo de redondeo hacia el entero más cercano, a menos que estén equidistantes: redondeo inferior en este caso.
`NumberFormatter::ROUND_HALFEVEN` int
  Modo de redondeo hacia el entero más cercano, a menos que estén equidistantes: redondeo hacia el número par en este caso.
`NumberFormatter::ROUND_HALFODD`
  Modo de redondeo hacia el « vecino impar ».
`NumberFormatter::ROUND_HALFUP`
  Modo de redondeo hacia el entero más cercano, a menos que estén equidistantes: redondeo superior en este caso.
`NumberFormatter::ROUND_TOWARD_ZERO`
  Alias de `NumberFormatter::ROUND_DOWN`.
`NumberFormatter::ROUND_UP` int
  Modo de redondeo que aleja de cero.

## Especificadores de relleno

Valores de relleno utilizados por numfmt_get_attribute() y numfmt_set_attribute() con el atributo `NumberFormatter::PADDING_POSITION`.

`NumberFormatter::PAD_AFTER_PREFIX` int
  Caracteres de relleno añadidos después del prefijo.
`NumberFormatter::PAD_AFTER_SUFFIX` int
  Caracteres de relleno añadidos después del sufijo.
`NumberFormatter::PAD_BEFORE_PREFIX` int
  Caracteres de relleno añadidos antes del prefijo.
`NumberFormatter::PAD_BEFORE_SUFFIX` int
  Caracteres de relleno añadidos antes del sufijo.

## Ver también

- » Documentación de formato ICU
- » Formateadores de números ICU
- » Formateador de números decimales ICU
- » Formateadores basados en reglas de ICU

## Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | Se añadieron `NumberFormatter::DECIMAL_COMPACT_SHORT`, `NumberFormatter::DECIMAL_COMPACT_LONG`, `NumberFormatter::CURRENCY_ISO`, `NumberFormatter::CURRENCY_PLURAL`, `NumberFormatter::CASH_CURRENCY`, `NumberFormatter::CURRENCY_STANDARD`.
8.4.0 | Las constantes de clase ahora están tipadas.

# NumberFormatter::create

# numfmt_create

# NumberFormatter::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::create -- numfmt_create -- NumberFormatter::__construct — Crea un formateador de números

### Descripción

Estilo orientado a objetos (método)

public static function NumberFormatter::create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter

Estilo procedimental

function numfmt_create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter

Estilo orientado a objetos (constructor)

public function NumberFormatter::__construct(string `$locale`, int `$style`, ?string `$pattern` = `null`)

Crea un formateador de números

### Parámetros

`locale`

  La configuración local con la cual los números serán formateados (i.e. en_CA).

`style`

  El estilo de formato, una de las constantes de estilo de formato. Si `NumberFormatter::PATTERN_DECIMAL` o `NumberFormatter::PATTERN_RULEBASED` es utilizado entonces el formato de número es abierto con el patrón proporcionado, que debe ser compatible con la sintaxis descrita por la » documentación ICU DecimalFormat o » documentación ICU RuleBasedNumberFormat, respectivamente.

`pattern`

  La cadena de patrón, en función del estilo de formato elegido.

### Valores devueltos

Devuelve un objeto NumberFormatter o `null` en caso de error.

### Errores/Excepciones

Se levanta una ValueError si `locale` es inválido.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Se levanta una ValueError si `locale` es inválido.
8.0.0 | `pattern` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con numfmt_create::create(), Estilo procedimental

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    $fmt = numfmt_create( 'it', NumberFormatter::SPELLOUT );
    echo numfmt_format($fmt, 1142)."\n";
    ?>

Ejemplo #2 Ejemplo con numfmt_create::create(), estilo POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt = new NumberFormatter( 'it', NumberFormatter::SPELLOUT );
    echo $fmt->format(1142)."\n";
    ?>

El ejemplo anterior mostrará:

    1.234.567,891
    millicentoquarantadue

### Ver también

- numfmt_format() - Formatear un número
- numfmt_parse() - Analiza un número

# NumberFormatter::format

# numfmt_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::format -- numfmt_format — Formatear un número

### Descripción

Estilo orientado a objetos

public function NumberFormatter::format(int|float `$num`, int `$type` = `NumberFormatter::TYPE_DEFAULT`): string|false

Estilo procedimental

function numfmt_format(NumberFormatter `$formatter`, int|float `$num`, int `$type` = `NumberFormatter::TYPE_DEFAULT`): string|false

Formatea un valor numérico según las reglas del formateador.

### Parámetros

`formatter`

  Objeto NumberFormatter.

`num`

  El valor a formatear. Puede ser int o float, otros valores serán convertidos a un valor numérico.

`type`

  El tipo de formato a usar. Tenga en cuenta que `NumberFormatter::TYPE_CURRENCY` no está soportado; use NumberFormatter::formatCurrency() en su lugar.

### Valores devueltos

Devuelve el string que contiene el valor formateado, o `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo de numfmt_format()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    $data = numfmt_format($fmt, 1234567.891234567890000);
    var_dump($data);
    ?>

Ejemplo #2 Ejemplo POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $data = $fmt->format(1234567.891234567890000);
    var_dump($data);
    ?>

El ejemplo anterior mostrará:

    string(13) "1.234.567,891"

### Notas

> Nota:

> Los formatos alcanzables por este método de formateo no pueden utilizar completamente las posibilidades de la biblioteca ICU subyacente, como por ejemplo formatear moneda con símbolo de moneda estrecho.

> Para utilizarlas completamente use msgfmt_format_message().

### Ver también

- numfmt_get_error_code() - Obtener el último código de error del formateador
- numfmt_format_currency() - Formatea un valor monetario
- numfmt_parse() - Analiza un número
- msgfmt_format_message() - Formatea rápidamente un mensaje

# NumberFormatter::formatCurrency

# numfmt_format_currency

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::formatCurrency -- numfmt_format_currency — Formatea un valor monetario

### Descripción

Estilo orientado a objetos

public function NumberFormatter::formatCurrency(float `$amount`, string `$currency`): string|false

Estilo procedimental

function numfmt_format_currency(NumberFormatter `$formatter`, float `$amount`, string `$currency`): string|false

Formatea un valor monetario, según las reglas del formateador.

### Parámetros

`formatter`

  El objeto NumberFormatter.

`amount`

  El valor numérico.

`currency`

  El código ISO 4217 de tres letras de la moneda a utilizar.

### Valores devueltos

La cadena que representa el valor monetario formateado, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con numfmt_format_currency(), Estilo procedimental

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::CURRENCY );
    echo numfmt_format_currency($fmt, 1234567.891234567890000, "EUR")."\n";
    echo numfmt_format_currency($fmt, 1234567.891234567890000, "RUR")."\n";
    $fmt = numfmt_create( 'ru_RU', NumberFormatter::CURRENCY );
    echo numfmt_format_currency($fmt, 1234567.891234567890000, "EUR")."\n";
    echo numfmt_format_currency($fmt, 1234567.891234567890000, "RUR")."\n";
    ?>

Ejemplo #2 Ejemplo con numfmt_format_currency(), estilo POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::CURRENCY );
    echo $fmt->formatCurrency(1234567.891234567890000, "EUR")."\n";
    echo $fmt->formatCurrency(1234567.891234567890000, "RUR")."\n";
    $fmt = new NumberFormatter( 'ru_RU', NumberFormatter::CURRENCY );
    echo $fmt->formatCurrency(1234567.891234567890000, "EUR")."\n";
    echo $fmt->formatCurrency(1234567.891234567890000, "RUR")."\n";
    ?>

El ejemplo anterior mostrará:

    1.234.567,89 €
    1.234.567,89 RUR
    1 234 567,89€
    1 234 567,89р.

### Notas

> Nota:

> Los formatos realizables por este método de formateo no pueden utilizar plenamente las posibilidades de la biblioteca ICU subyacente, como por ejemplo el formateo de moneda con un símbolo monetario corto.

> Para utilizarlas plenamente, utilice msgfmt_format_message().

### Ver también

- numfmt_get_error_code() - Obtener el último código de error del formateador
- numfmt_format() - Formatear un número
- numfmt_parse_currency() - Analiza un número monetario
- msgfmt_format_message() - Formatea rápidamente un mensaje

# NumberFormatter::getAttribute

# numfmt_get_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getAttribute -- numfmt_get_attribute — Lee un atributo

### Descripción

Estilo orientado a objetos

public function NumberFormatter::getAttribute(int `$attribute`): int|float|false

Estilo procedimental

function numfmt_get_attribute(NumberFormatter `$formatter`, int `$attribute`): int|float|false

Lee un atributo numérico del formateador. Un ejemplo de atributo numérico es el número de decimales que el formateador va a utilizar.

### Parámetros

`formatter`

  El objeto NumberFormatter.

`attribute`

  La constante de atributo, una de la lista de atributos numéricos.

### Valores devueltos

Devuelve el valor del atributo, en caso de éxito, y `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con numfmt_get_attribute(), Estilo procedimental

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Decimales :  ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS, 2);
    echo "Decimales :  ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Ejemplo #2 Ejemplo con numfmt_get_attribute(), estilo POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Decimales :  ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, 2);
    echo "Decimales :  ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

El ejemplo anterior mostrará:

    Decimales :  3
    1.234.567,891
    Decimales :  2
    1.234.567,89

### Ver también

- numfmt_get_error_code() - Obtener el último código de error del formateador
- numfmt_get_text_attribute() - Lee un atributo textual
- numfmt_set_attribute() - Asigna un atributo al formateador

# NumberFormatter::getErrorCode

# numfmt_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getErrorCode -- numfmt_get_error_code — Obtener el último código de error del formateador

### Descripción

Estilo orientado a objetos

public function NumberFormatter::getErrorCode(): int

Estilo procedimental

function numfmt_get_error_code(NumberFormatter `$formatter`): int

Obtiene el código de error de la última función ejecutada por el formateador.

### Parámetros

`formatter`

  Objeto NumberFormatter.

### Valores devueltos

Devuelve el código de error de la última llamada al formateador.

### Ejemplos

Ejemplo #1 Ejemplo de numfmt_get_error_code()

    <?php
    $fmt  = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    $data = numfmt_format($fmt, 1234567.891234567890000);
    if (intl_is_failure(numfmt_get_error_code($fmt))) {
        echo 'Error del formateador';
    }
    ?>

Ejemplo #2 Ejemplo OO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $fmt->format(1234567.891234567890000);
    if (intl_is_failure($fmt->getErrorCode())) {
        echo 'Error del formateador';
    }
    ?>

### Ver también

- numfmt_get_error_message() - Lee el último mensaje de error del formateador
- intl_get_error_code() - Lee el último código de error
- intl_is_failure() - Verifica si un código de error indica un fallo

# NumberFormatter::getErrorMessage

# numfmt_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getErrorMessage -- numfmt_get_error_message — Lee el último mensaje de error del formateador

### Descripción

Estilo orientado a objetos

public function NumberFormatter::getErrorMessage(): string

Estilo procedimental

function numfmt_get_error_message(NumberFormatter `$formatter`): string

Lee el mensaje de error generado por la última función del formateador.

### Parámetros

`formatter`

  El objeto NumberFormatter.

### Valores devueltos

Devuelve el mensaje de error de la última llamada al formateador.

### Ejemplos

Ejemplo #1 Ejemplo con numfmt_get_error_message(), Estilo procedimental

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    $data = numfmt_format($fmt, 1234567.891234567890000);
    if(intl_is_failure(numfmt_get_error_code($fmt))) {
        report_error("Error de formateador");
    }
    ?>

Ejemplo #2 Ejemplo con numfmt_get_error_code(), estilo POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $fmt->format(1234567.891234567890000);
    if(intl_is_failure($fmt->getErrorCode())) {
        report_error("Error de formateador");
    }
    ?>

### Ver también

- numfmt_get_error_code() - Obtener el último código de error del formateador
- intl_get_error_code() - Lee el último código de error
- intl_is_failure() - Verifica si un código de error indica un fallo

# NumberFormatter::getLocale

# numfmt_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getLocale -- numfmt_get_locale — Lee la configuración local del formateador

### Descripción

Estilo orientado a objetos

public function NumberFormatter::getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

Estilo procedimental

function numfmt_get_locale(NumberFormatter `$formatter`, int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

Lee el nombre de la configuración local del formateador.

### Parámetros

`formatter`

  El objeto NumberFormatter.

`type`

  Puede seleccionarse entre un valor válido o un valor literal `Locale::VALID_LOCALE`, `Locale::ACTUAL_LOCALE`, respectivamente. El valor por omisión es el valor literal.

### Valores devueltos

El nombre de la configuración local utilizada para crear el formateador, o `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con numfmt_get_error_code(), Estilo procedimental

    <?php
    $req     = 'fr_FR_PARIS';
    $fmt     = numfmt_create( $req,  NumberFormatter::DECIMAL);
    $res_val = numfmt_get_locale( $fmt, Locale::VALID_LOCALE );
    $res_act = numfmt_get_locale( $fmt, Locale::ACTUAL_LOCALE );
    printf( "Nombre de la configuración local solicitada : %s\nNombre válido de la configuración local : %s\nValor literal de la configuración local : %s\n",
             $req, $res_val, $res_act );
    ?>

El ejemplo anterior mostrará:

    Nombre de la configuración local solicitada : fr_FR_PARIS
    Nombre válido de la configuración local: fr_FR
    Valor literal de la configuración local : fr

### Ver también

- numfmt_create() - Crea un formateador de números
- numfmt_get_error_code() - Obtener el último código de error del formateador

# NumberFormatter::getPattern

# numfmt_get_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getPattern -- numfmt_get_pattern — Lee el modelo del formateador

### Descripción

Estilo orientado a objetos

public function NumberFormatter::getPattern(): string|false

Estilo procedimental

function numfmt_get_pattern(NumberFormatter `$formatter`): string|false

Extrae el modelo utilizado por el formateador.

### Parámetros

`formatter`

  El objeto NumberFormatter.

### Valores devueltos

El string de modelo, que es utilizado por el formateador, o `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con numfmt_get_pattern(), Estilo procedimental

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Modelo : ".numfmt_get_pattern($fmt)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_pattern($fmt, "#0.# kg");
    echo "Modelo : ".numfmt_get_pattern($fmt)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Ejemplo #2 Ejemplo con numfmt_get_pattern(), estilo POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Modelo : ".$fmt->getPattern()."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setPattern("#0.# kg");
    echo "Modelo : ".$fmt->getPattern()."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

El ejemplo anterior mostrará:

    Modelo : #,##0.###
    1.234.567,891
    Modelo : #0.# kg
    1234567,9 kg

### Ver también

- numfmt_get_error_code() - Obtener el último código de error del formateador
- numfmt_set_pattern() - Configura el patrón del formateador
- numfmt_create() - Crea un formateador de números

# NumberFormatter::getSymbol

# numfmt_get_symbol

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getSymbol -- numfmt_get_symbol — Lee el valor del símbolo

### Descripción

Estilo orientado a objetos

public function NumberFormatter::getSymbol(int `$symbol`): string|false

Estilo procedimental

function numfmt_get_symbol(NumberFormatter `$formatter`, int `$symbol`): string|false

Lee el símbolo asociado al formateador. El formateador utiliza símbolos para representar caracteres dependientes de las convenciones locales, como el signo de porcentaje. Esta API no es soportada por los formateadores basados en reglas.

### Parámetros

`formatter`

  El objeto NumberFormatter.

`symbol`

  La constante de símbolo, una de la lista de constantes de símbolos de formato.

### Valores devueltos

La cadena de símbolo o `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con numfmt_get_symbol(), Estilo procedimental

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Separador : ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
    echo "Separador : ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Ejemplo #2 Ejemplo con numfmt_get_symbol(), estilo POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Separador : ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
    echo "Separador : ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

El ejemplo anterior mostrará:

    Separador : .
    1.234.567,891
    Separador : *
    1*234*567,891

### Ver también

- numfmt_get_error_code() - Obtener el último código de error del formateador
- numfmt_set_symbol() - Configura el símbolo del formateador

# NumberFormatter::getTextAttribute

# numfmt_get_text_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getTextAttribute -- numfmt_get_text_attribute — Lee un atributo textual

### Descripción

Estilo orientado a objetos

public function NumberFormatter::getTextAttribute(int `$attribute`): string|false

Estilo procedimental

function numfmt_get_text_attribute(NumberFormatter `$formatter`, int `$attribute`): string|false

Lee un atributo textual asociado a un formateador. Un ejemplo de atributo textual es el sufijo para los números positivos. Si el formateador no comprende este atributo, se produce un error `U_UNSUPPORTED_ERROR`. Los formateadores de reglas comprenden únicamente `NumberFormatter::DEFAULT_RULESET` y `NumberFormatter::PUBLIC_RULESETS`.

### Parámetros

`formatter`

  El objeto NumberFormatter.

`attribute`

  El identificador del atributo: una de las constantes de atributo textual.

### Valores devueltos

Devuelve el valor del atributo en caso de éxito, y `false` en caso contrario.

### Ejemplos

Ejemplo #1 Ejemplo con numfmt_get_text_attribute(), Estilo procedimental

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Prefijo : ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo numfmt_format($fmt, -1234567.891234567890000)."\n";
    numfmt_set_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX, "MINUS");
    echo "Prefijo : ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo numfmt_format($fmt, -1234567.891234567890000)."\n";
    ?>

Ejemplo #2 Ejemplo con numfmt_get_text_attribute(), estilo POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Prefijo : ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo $fmt->format(-1234567.891234567890000)."\n";
    $fmt->setTextAttribute(NumberFormatter::NEGATIVE_PREFIX, "MINUS");
    echo "Prefijo : ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo $fmt->format(-1234567.891234567890000)."\n";
    ?>

El ejemplo anterior mostrará:

    Prefijo : -
    -1.234.567,891
    Prefijo : MINUS
    MINUS1.234.567,891

### Ver también

- numfmt_get_error_code() - Obtener el último código de error del formateador
- numfmt_get_attribute() - Lee un atributo
- numfmt_set_text_attribute() - Modifica un atributo de texto

# NumberFormatter::parse

# numfmt_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::parse -- numfmt_parse — Analiza un número

### Descripción

Estilo orientado a objetos

public function NumberFormatter::parse(string `$string`, int `$type` = `NumberFormatter::TYPE_DOUBLE`, int `&$offset` = `null`): int|float|false

Estilo procedimental

function numfmt_parse(
NumberFormatter `$formatter`,
string `$string`,
int `$type` = `NumberFormatter::TYPE_DOUBLE`,
int `&$offset` = `null`
): int|float|false

Analiza una cadena y extrae un número, utilizando las reglas del formateador.

### Parámetros

`formatter`

  El objeto NumberFormatter.

`string`

  La cadena a analizar para el número.

`type`

  El tipo de formato a utilizar. Por omisión, `NumberFormatter::TYPE_DOUBLE` es utilizada. Tenga en cuenta que `NumberFormatter::TYPE_CURRENCY` no es soportado; utilice NumberFormatter::parseCurrency() en su lugar.

`offset`

  La posición de inicio de análisis en la cadena. En retorno, este valor contendrá la posición de fin de análisis.

### Valores devueltos

El valor numérico analizado, o `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con numfmt_parse(), Estilo procedimental

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    $num = "1.234.567,891";
    echo numfmt_parse($fmt, $num)."\n";
    echo numfmt_parse($fmt, $num, NumberFormatter::TYPE_INT32)."\n";
    ?>

Ejemplo #2 Ejemplo con numfmt_parse(), estilo POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $num = "1.234.567,891";
    echo $fmt->parse($num)."\n";
    echo $fmt->parse($num, NumberFormatter::TYPE_INT32)."\n";
    ?>

El ejemplo anterior mostrará:

    1234567.891
    1234567

### Ver también

- numfmt_get_error_code() - Obtener el último código de error del formateador
- numfmt_format() - Formatear un número
- numfmt_parse_currency() - Analiza un número monetario

# NumberFormatter::parseCurrency

# numfmt_parse_currency

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::parseCurrency -- numfmt_parse_currency — Analiza un número monetario

### Descripción

Estilo orientado a objetos

public function NumberFormatter::parseCurrency(string `$string`, string `&$currency`, int `&$offset` = `null`): float|false

Estilo procedimental

function numfmt_parse_currency(
NumberFormatter `$formatter`,
string `$string`,
string `&$currency`,
int `&$offset` = `null`
): float|false

Analiza una cadena en un número flotante y una moneda, utilizando el formateador.

### Parámetros

`formatter`

  El objeto NumberFormatter.

`currency`

  El nombre de la moneda (el código ISO 4217 de 3 letras).

`offset`

  La posición de inicio de análisis en la cadena. A su vez, este valor contendrá la posición de fin de análisis.

### Valores devueltos

El número decimal así leído, o `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con numfmt_parse_currency(), Estilo procedimental

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::CURRENCY );
    $num = "1.234.567,89\xc2\xa0$";
    echo "Tenemos ".numfmt_parse_currency($fmt, $num, $curr)." en $curr\n";
    ?>

Ejemplo #2 Ejemplo con numfmt_parse_currency(), Estilo procedimental

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::CURRENCY );
    $num = "1.234.567,89\xc2\xa0$";
    echo "Tenemos ".$fmt->parseCurrency($num, $curr)." en $curr\n";
    ?>

El ejemplo anterior mostrará:

    Tenemos 1234567.89 en USD

### Ver también

- numfmt_get_error_code() - Obtener el último código de error del formateador
- numfmt_parse() - Analiza un número
- numfmt_format_currency() - Formatea un valor monetario

# NumberFormatter::setAttribute

# numfmt_set_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setAttribute -- numfmt_set_attribute — Asigna un atributo al formateador

### Descripción

Estilo orientado a objetos

public function NumberFormatter::setAttribute(int `$attribute`, int|float `$value`): bool

Estilo procedimental

function numfmt_set_attribute(NumberFormatter `$formatter`, int `$attribute`, int|float `$value`): bool

Asigna un atributo numérico al formateador. Un ejemplo de atributo numérico es el número de decimales a mostrar por el formateador.

### Parámetros

`formatter`

  El objeto NumberFormatter.

`attribute`

  El identificador de atributo: una de las constantes atributos numéricos.

`value`

  El valor del atributo.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con numfmt_set_attribute(), Estilo procedimental

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Digits: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS, 2);
    echo "Digits: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Ejemplo #2 Ejemplo con numfmt_set_attribute(), estilo POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Digits: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, 2);
    echo "Digits: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

El ejemplo anterior mostrará:

    Digits: 3
    1.234.567,891
    Digits: 2
    1.234.567,89

Ejemplo #3 Uso de `NumberFormatter::ROUNDING_MODE` para truncar valores

Por defecto, NumberFormatter redondea los valores. Usar `NumberFormatter::ROUND_DOWN` como `NumberFormatter::ROUNDING_MODE` trunca el valor al número especificado de dígitos fraccionarios sin redondear.

    <?php
    $fmt = new NumberFormatter('en_US', NumberFormatter::DECIMAL);
    $fmt->setAttribute(NumberFormatter::FRACTION_DIGITS, 2);

    echo "Modo de redondeo por defecto:\n";
    echo $fmt->format(3.789), "\n"; // 3.79 (redondeado hacia arriba)
    echo $fmt->format(3.781), "\n"; // 3.78 (redondeado hacia abajo)

    $fmt->setAttribute(NumberFormatter::ROUNDING_MODE, NumberFormatter::ROUND_DOWN);

    echo "\nCon ROUND_DOWN (truncar):\n";
    echo $fmt->format(3.789), "\n"; // 3.78 (truncado)
    echo $fmt->format(3.781), "\n"; // 3.78 (truncado)
    ?>

El ejemplo anterior mostrará:

    Modo de redondeo por defecto:
    3.79
    3.78

    Con ROUND_DOWN (truncar):
    3.78
    3.78

### Ver también

- numfmt_get_error_code() - Obtener el último código de error del formateador
- numfmt_get_attribute() - Lee un atributo
- numfmt_set_text_attribute() - Modifica un atributo de texto

# NumberFormatter::setPattern

# numfmt_set_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setPattern -- numfmt_set_pattern — Configura el patrón del formateador

### Descripción

Estilo orientado a objetos

public function NumberFormatter::setPattern(string `$pattern`): bool

Estilo procedimental

function numfmt_set_pattern(NumberFormatter `$formatter`, string `$pattern`): bool

Configura el patrón utilizado por el formateador. No puede ser utilizado con un formateador basado en reglas.

### Parámetros

`formatter`

  El objeto NumberFormatter.

`pattern`

  El patrón, en la sintaxis descrita en la » documentación ICU DecimalFormat.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con numfmt_set_pattern(), Estilo procedimental

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Patrón : ".numfmt_get_pattern($fmt)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_pattern($fmt, "#0.# kg");
    echo "Patrón : ".numfmt_get_pattern($fmt)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Ejemplo #2 Ejemplo con numfmt_set_pattern(), estilo POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Patrón : ".$fmt->getPattern()."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setPattern("#0.# kg");
    echo "Patrón : ".$fmt->getPattern()."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

El ejemplo anterior mostrará:

    Patrón : #,##0.###
    1.234.567,891
    Patrón : #0.# kg
    1234567,9 kg

### Ver también

- numfmt_get_error_code() - Obtener el último código de error del formateador
- numfmt_create() - Crea un formateador de números
- numfmt_get_pattern() - Lee el modelo del formateador

# NumberFormatter::setSymbol

# numfmt_set_symbol

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setSymbol -- numfmt_set_symbol — Configura el símbolo del formateador

### Descripción

Estilo orientado a objetos

public function NumberFormatter::setSymbol(int `$symbol`, string `$value`): bool

Estilo procedimental

function numfmt_set_symbol(NumberFormatter `$formatter`, int `$symbol`, string `$value`): bool

Configura el símbolo del formateador. El formateador utiliza el símbolo para caracterizar números, como el porcentaje. Esta API no es soportada para los formateadores basados en reglas.

### Parámetros

`formatter`

  El objeto NumberFormatter.

`symbol`

  El identificador de símbolo, entre las constantes de símbolos.

`value`

  El texto del símbolo.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con numfmt_set_symbol(), Estilo procedimental

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Separador decimal : ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
    echo "Separador decimal : ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Ejemplo #2 Ejemplo con numfmt_set_symbol(), estilo POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Separador decimal : ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
    echo "Separador decimal : ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

El ejemplo anterior mostrará:

    Separador decimal : .
    1.234.567,891
    Separador decimal : *
    1*234*567,891

### Ver también

- numfmt_get_error_code() - Obtener el último código de error del formateador
- numfmt_get_symbol() - Lee el valor del símbolo

# NumberFormatter::setTextAttribute

# numfmt_set_text_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setTextAttribute -- numfmt_set_text_attribute — Modifica un atributo de texto

### Descripción

Estilo orientado a objetos

public function NumberFormatter::setTextAttribute(int `$attribute`, string `$value`): bool

Estilo procedimental

function numfmt_set_text_attribute(NumberFormatter `$formatter`, int `$attribute`, string `$value`): bool

Modifica el atributo de texto asociado al formateador. Un ejemplo de atributo de texto es el sufijo de los números positivos. Si el formateador no comprende el atributo, se produce un error `U_UNSUPPORTED_ERROR`. Los formateadores basados en reglas solo comprenden `NumberFormatter::DEFAULT_RULESET` y `NumberFormatter::PUBLIC_RULESETS`.

### Parámetros

`formatter`

  Un objeto NumberFormatter.

`attribute`

  Un especificador de atributo: una de las constantes de atributo de texto.

`value`

  El valor del atributo de texto.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con numfmt_set_text_attribute(), Estilo procedimental

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Prefix: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo numfmt_format($fmt, -1234567.891234567890000)."\n";
    numfmt_set_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX, "MINUS");
    echo "Prefix: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo numfmt_format($fmt, -1234567.891234567890000)."\n";
    ?>

Ejemplo #2 Ejemplo con numfmt_set_text_attribute(), Estilo procedimental

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Prefix: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo $fmt->format(-1234567.891234567890000)."\n";
    $fmt->setTextAttribute(NumberFormatter::NEGATIVE_PREFIX, "MINUS");
    echo "Prefix: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo $fmt->format(-1234567.891234567890000)."\n";
    ?>

El ejemplo anterior mostrará:

    Prefix: -
    -1.234.567,891
    Prefix: MINUS
    MINUS1.234.567,891

### Ver también

- numfmt_get_error_code() - Obtener el último código de error del formateador
- numfmt_get_text_attribute() - Lee un atributo textual
- numfmt_set_attribute() - Asigna un atributo al formateador

## Tabla de contenidos

- NumberFormatter::create — Crea un formateador de números
- NumberFormatter::format — Formatear un número
- NumberFormatter::formatCurrency — Formatea un valor monetario
- NumberFormatter::getAttribute — Lee un atributo
- NumberFormatter::getErrorCode — Obtener el último código de error del formateador
- NumberFormatter::getErrorMessage — Lee el último mensaje de error del formateador
- NumberFormatter::getLocale — Lee la configuración local del formateador
- NumberFormatter::getPattern — Lee el modelo del formateador
- NumberFormatter::getSymbol — Lee el valor del símbolo
- NumberFormatter::getTextAttribute — Lee un atributo textual
- NumberFormatter::parse — Analiza un número
- NumberFormatter::parseCurrency — Analiza un número monetario
- NumberFormatter::setAttribute — Asigna un atributo al formateador
- NumberFormatter::setPattern — Configura el patrón del formateador
- NumberFormatter::setSymbol — Configura el símbolo del formateador
- NumberFormatter::setTextAttribute — Modifica un atributo de texto

# La clase Locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Introducción

Una "Locale" es un identificador utilizado para representar los comportamientos regionales de una API. Las locales de PHP están organizadas e identificadas de la misma manera que los CLDR de ICU (y que muchos otros editores de sistemas Unix, tales como Mac, Java, etc.). Las locales se identifican por los etiquetados de lenguaje de la RFC 4646 (que utiliza guiones y no subrayados) además de la notación tradicional con subrayados. Salvo indicación contraria, las funciones de esta clase son capaces de utilizar las dos notaciones.

Ejemplos de identificadores:

- en-US (Inglés, EE.UU.)
- zh-Hant-TW (Chino, tradicional, Taiwán)
- fr-CA, fr-FR (Francés para Canadá y Francia, respectivamente)

La clase Locale y los métodos asociados, son utilizados para interactuar con los identificadores locales: para verificar que un identificador está bien formado, válido, etc. Las extensiones utilizadas por CDR en UAX #35 y heredadas por ICU son válidas, y utilizadas siempre que sea posible en ICU.

Las locales no pueden ser instanciadas. Todas son funciones estáticas.

La cadena `null` o vacía permite obtener la locale raíz. La raíz es el equivalente de `"en_US_POSIX"` en CLDR. Los etiquetados de lenguaje (y por lo tanto, los identificadores) no son sensibles a mayúsculas/minúsculas. Existe una función de canonalización que permite obtener la especificación exacta.

## Sinopsis de la Clase

class Locale {
/* Constantes */
public const int ACTUAL_LOCALE;
public const int VALID_LOCALE;
public const null DEFAULT_LOCALE = null;
public const string LANG_TAG;
public const string EXTLANG_TAG;
public const string SCRIPT_TAG;
public const string REGION_TAG;
public const string VARIANT_TAG;
public const string GRANDFATHERED_LANG_TAG;
public const string PRIVATE_TAG;
/* Métodos */
public static function acceptFromHttp(string `$header`): string|false
public static function canonicalize(string `$locale`): ?string
public static function composeLocale(array `$subtags`): string|false
public static function filterMatches(string `$languageTag`, string `$locale`, bool `$canonicalize` = `false`): ?bool
public static function getAllVariants(string `$locale`): ?array
public static function getDefault(): string
public static function getDisplayLanguage(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayName(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayRegion(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayScript(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayVariant(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getKeywords(string `$locale`): array|false|null
public static function getPrimaryLanguage(string `$locale`): ?string
public static function getRegion(string `$locale`): ?string
public static function getScript(string `$locale`): ?string
public static function isRightToLeft( string `$locale` = "" ): bool
public static function lookup(
array `$languageTag`,
string `$locale`,
bool `$canonicalize` = `false`,
?string `$defaultLocale` = `null`
): ?string
public static function parseLocale(string `$locale`): ?array
public static function setDefault(string `$locale`): true
}

## Constantes predefinidas

Estas constantes definen el comportamiento de Locale

`Locale::DEFAULT_LOCALE` null
  Utilizada como argumento de configuración local con los métodos de las diferentes clases afectadas, tales como NumberFormatter. Esta constante hace que se utilicen los valores por omisión.

Estas constantes describen la elección de la configuración local para el método getLocale de diferentes clases.

`Locale::ACTUAL_LOCALE` int
  La configuración local utilizada por los datos entrantes.
`Locale::VALID_LOCALE` int
  Esta es la configuración local más específica soportada por ICU.

## Subetiqueta de idioma

Estas constantes definen cómo se analizan o componen las configuraciones locales. Deben ser utilizadas como claves en un array de argumentos pasado a locale_compose() y son devueltas por locale_parse() como claves de un array asociativo.

`Locale::LANG_TAG` string
  Subetiqueta de idioma
`Locale::EXTLANG_TAG` string
  Subetiqueta de idioma extendido
`Locale::SCRIPT_TAG` string
  Subetiqueta de script
`Locale::REGION_TAG` string
  Subetiqueta de región
`Locale::VARIANT_TAG` string
  Subetiqueta de variante
`Locale::GRANDFATHERED_LANG_TAG` string
  Subetiqueta de idioma heredado
`Locale::PRIVATE_TAG` string
  Subetiqueta privada

## Ver también

- » RFC 4646 : etiquetados para identificar los idiomas
- » RFC 4647 : Coincidencia de etiquetados de idiomas
- » Proyecto Unicode CLDR: Repositorio Común de Datos de Localización
- » Registro de subtags de idiomas de IANA
- » Guía del usuario de ICU: Locale
- » API de Locale de ICU

## Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Las constantes de clase ahora están tipadas.

# Locale::acceptFromHttp

# locale_accept_from_http

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::acceptFromHttp -- locale_accept_from_http — Determina la mejor configuración local a partir del encabezado HTTP `"Accept-Language"`

### Descripción

Estilo orientado a objetos

public static function Locale::acceptFromHttp(string `$header`): string|false

Estilo procedimental

function locale_accept_from_http(string `$header`): string|false

Intenta encontrar una configuración local que pueda satisfacer la lista de idiomas solicitada por el encabezado HTTP `"Accept-Language"`.

### Parámetros

`header`

  La cadena que contiene el encabezado `"Accept-Language"`, en el formato de la RFC 2616.

### Valores devueltos

El identificador de configuración local correspondiente.

Devuelve `false` cuando la longitud de `header` excede `INTL_MAX_LOCALE_LEN`.

### Ejemplos

Ejemplo #1 Ejemplo con locale_accept_from_http(), procedimental

    <?php
    $locale = locale_accept_from_http($_SERVER['HTTP_ACCEPT_LANGUAGE']);
    echo $locale;
    ?>

Ejemplo #2 Ejemplo con locale_accept_from_http(), POO

    <?php
    $locale = Locale::acceptFromHttp($_SERVER['HTTP_ACCEPT_LANGUAGE']);
    echo $locale;
    ?>

El ejemplo anterior mostrará:

    en_US

### Ver también

- locale_lookup() - Búsqueda en la lista de la mejor lengua

# Locale::canonicalize

# locale_canonicalize

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::canonicalize -- locale_canonicalize — Canoniza la cadena que representa la configuración local

### Descripción

public static function Locale::canonicalize(string `$locale`): ?string

Convierte el string de configuración regional pasada al formato ICU.

Esto no necesariamente indica ni devuelve una configuración regional válida. Es solo una versión de la entrada que se ha estandarizado según las reglas de ICU.

El comportamiento de esta función depende de la versión de ICU que PHP esté utilizando (`INTL_ICU_VERSION`).

### Parámetros

`locale`
  String de configuración regional original.

### Valores devueltos

Cadena canonicalizada en la configuración local.

Devuelve `null` cuando la longitud de `locale` excede `INTL_MAX_LOCALE_LEN`.

### Ejemplos

Ejemplo #1 Ejemplo de locale_canonicalize()

    echo Locale::canonicalize('en-US.utf8') . "\n";
    echo Locale::canonicalize('totally-not-valid') . "\n";

Resultado del ejemplo anterior es similar a:

    en_US
    totally_NOT_VALID

# Locale::composeLocale

# locale_compose

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::composeLocale -- locale_compose — Retorna un identificador de configuración regional correcto

### Descripción

Estilo orientado a objetos

public static function Locale::composeLocale(array `$subtags`): string|false

Estilo procedimental

function locale_compose(array `$subtags`): string|false

Retorna un identificador de configuración regional correcto, ordenado y delimitado, con las claves para identificar las particularidades regionales, y los valores asociados a estas subconfiguraciones regionales.

### Parámetros

`subtags`

  Un array que contiene la lista de pares clave-valor, donde las claves representan los identificadores de subconfiguraciones regionales, y sus valores asociados son los valores de los subtags.

  > Nota:

  > Los subtags `'variant'` y `'private'` pueden tomar hasta 15 valores mientras que `'extlang'` no puede tomar más de 3 valores. Por ejemplo, las variantes están permitidas con un sufijo que va de 0 a 14. Por lo tanto, las claves del array son `variant0`, `variant1`, …, `variant14`. En el identificador de configuración regional retornado, los subtags están ordenados por sufijo, con `variant0` seguido de `variant1` seguido de `variant2` y así sucesivamente.

  > Alternativamente, los valores de `'variant'`, `'private'` y `'extlang'` pueden ser especificados como un array bajo una clave específica (por ejemplo, `'variant'`). En este caso no se aplica ninguna limitación sobre el número de subtags reconocidos.

### Valores devueltos

El identificador de configuración regional correspondiente, o `false` cuando `subtags` está vacío.

### Ejemplos

Ejemplo #1 Ejemplo con locale_compose(), procedimental

    <?php
    $arr = array(
        'language'=>'en',
        'script'  =>'Hans',
        'region'  =>'CN',
        'variant2'=>'rozaj',
        'variant1'=>'nedis',
        'private1'=>'prv1',
        'private2'=>'prv2'
    );
    echo locale_compose($arr);
    ?>

Ejemplo #2 Ejemplo con locale_compose(), POO

    <?php
    $arr = array(
        'language'=>'en',
        'script'  =>'Hans',
        'region'  =>'CN',
        'variant2'=>'rozaj',
        'variant1'=>'nedis',
        'private1'=>'prv1',
        'private2'=>'prv2'
    );
    echo Locale::composeLocale($arr);
    ?>

El ejemplo anterior mostrará:

    Locale: en_Hans_CN_nedis_rozaj_x_prv1_prv2

Ejemplo #3 Límites de los Subtags

Si `subtags` se proporciona como claves diferentes con un sufijo numérico, las claves no soportadas son ignoradas silenciosamente (en este caso `'extlang3'`), y ordenadas en el resultado por el sufijo numérico. No hay límites, si los subtags se proporcionan como array; su orden es como se indica.

    <?php
    $arr = array(
        'language' => 'en',
        'script'   => 'Hans',
        'region'   => 'CN',
        'extlang3' => 'd',
        'extlang2' => 'c',
        'extlang1' => 'b',
        'extlang0' => 'a',
    );
    echo locale_compose($arr), PHP_EOL;
    $arr = array(
        'language' => 'en',
        'script'   => 'Hans',
        'region'   => 'CN',
        'extlang'  => ['a', 'b', 'c', 'd'],
    );
    echo locale_compose($arr), PHP_EOL;
    ?>

El ejemplo anterior mostrará:

    en_a_b_c_Hans_CN
    en_a_b_c_d_Hans_CN

### Ver también

- locale_parse() - Devuelve los subelementos de la configuración regional

# Locale::filterMatches

# locale_filter_matches

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::filterMatches -- locale_filter_matches — Verifica si el tag de idioma coincide con una configuración local

### Descripción

Estilo orientado a objetos

public static function Locale::filterMatches(string `$languageTag`, string `$locale`, bool `$canonicalize` = `false`): ?bool

Estilo procedimental

function locale_filter_matches(string `$languageTag`, string `$locale`, bool `$canonicalize` = `false`): ?bool

Verifica si el filtro `languageTag` coincide con la `locale` según la RFC 4647, y su algoritmo de filtrado simple.

### Parámetros

`languageTag`

  El tag de idioma a verificar

`locale`

  El intervalo de idioma objetivo

`canonicalize`

  Si `true`, los argumentos serán convertidos a su forma canónica antes de la búsqueda.

### Valores devueltos

`true` si `locale` acepta `languageTag`, y `false` de lo contrario.

Devuelve `null` cuando la longitud de `locale` excede `INTL_MAX_LOCALE_LEN`.

### Ejemplos

Ejemplo #1 Ejemplo con locale_filter_matches(), procedimental

    <?php
    echo (locale_filter_matches('de-DEVA','de-DE', false)) ? "Coincide" : "No coincide";
    echo '; ';
    echo (locale_filter_matches('de-DE_1996','de-DE', false)) ? "Coincide" : "No coincide";
    ?>

Ejemplo #2 Ejemplo con locale_filter_matches(), POO

    <?php
    echo (Locale::filterMatches('de-DEVA','de-DE', false)) ? "Coincide" : "No coincide";
    echo '; ';
    echo (Locale::filterMatches('de-DE-1996','de-DE', false)) ? "Coincide" : "No coincide";
    ?>

El ejemplo anterior mostrará:

    No coincide; Coincide

### Ver también

- locale_lookup() - Búsqueda en la lista de la mejor lengua

# Locale::getAllVariants

# locale_get_all_variants

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getAllVariants -- locale_get_all_variants — Lista todas las variantes de una configuración local

### Descripción

Estilo orientado a objetos

public static function Locale::getAllVariants(string `$locale`): ?array

Estilo procedimental

function locale_get_all_variants(string `$locale`): ?array

Lista todas las variantes de una configuración local

### Parámetros

`locale`

  La configuración local de la que se deben extraer las variantes

### Valores devueltos

Un array que contiene la lista de todas las variantes de una configuración local, o bien `null` si no existen.

Devuelve `null` cuando la longitud de `locale` excede `INTL_MAX_LOCALE_LEN`.

### Ejemplos

Ejemplo #1 Ejemplo con locale_get_all_variants(), procedimental

    <?php
    $arr = locale_get_all_variants('sl_IT_NEDIS_ROJAZ_1901');
    var_export( $arr );
    ?>

Ejemplo #2 Ejemplo con locale_get_all_variants(), POO

    <?php
    $arr = Locale::getAllVariants('sl_IT_NEDIS_ROJAZ_1901');
    var_export( $arr );
    ?>

El ejemplo anterior mostrará:

    array (
        0 => 'NEDIS',
        1 => 'ROJAZ',
        2 => '1901',
    )

### Ver también

- locale_get_primary_language() - Lee el idioma principal de la configuración local
- locale_get_script() - Devuelve un código para el script de la configuración local
- locale_get_region() - Devuelve un código para la región de la configuración local

# Locale::getDefault

# locale_get_default

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDefault -- locale_get_default — Lee el valor por defecto de una configuración local para la variable global 'default_locale'

### Descripción

Estilo orientado a objetos

public static function Locale::getDefault(): string

Estilo procedimental

function locale_get_default(): string

Lee el valor por defecto de una configuración local para la variable global 'default_locale'. Al momento de la inicialización de PHP, este valor se extrae de la directiva 'intl.default_locale' en php.ini, si este valor existe, y de la función ICU uloc_getDefault() de otro modo.

### Parámetros

### Valores devueltos

La configuración local por defecto para la ejecución.

### Ejemplos

Ejemplo #1 Ejemplo con locale_get_default(), procedimental

    <?php
    ini_set('intl.default_locale', 'de-DE');
    echo locale_get_default();
    echo '; ';
    locale_set_default('fr');
    echo locale_get_default();
    ?>

Ejemplo #2 Ejemplo con locale_get_default(), POO

    <?php
    ini_set('intl.default_locale', 'de-DE');
    echo Locale::getDefault();
    echo '; ';
    Locale::setDefault('fr');
    echo Locale::getDefault();
    ?>

El ejemplo anterior mostrará:

    de-DE; fr

### Ver también

- locale_set_default() - Configura la configuración local por defecto

# Locale::getDisplayLanguage

# locale_get_display_language

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayLanguage -- locale_get_display_language — Devuelve un nombre adecuado para mostrar un nombre de idioma

### Descripción

Estilo orientado a objetos

public static function Locale::getDisplayLanguage(string `$locale`, ?string `$displayLocale` = `null`): string|false

Estilo procedimental

function locale_get_display_language(string `$locale`, ?string `$displayLocale` = `null`): string|false

Devuelve un nombre adecuado para mostrar un nombre de idioma. Si se pasa el valor `null` como argumento, se utiliza la configuración local por omisión.

### Parámetros

`locale`

  La configuración local de la cual se debe devolver el nombre del idioma

`displayLocale`

  Un formato opcional para mostrar el nombre del idioma.

### Valores devueltos

El nombre del idioma a mostrar para la `locale`, en el formato definido por `displayLocale`, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `displayLocale` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con locale_get_display_language(), procedimental

    <?php
    echo locale_get_display_language('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_language('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_language('sl-Latn-IT-nedis', 'de');
    ?>

Ejemplo #2 Ejemplo con locale_get_display_language(), POO

    <?php
    echo Locale::getDisplayLanguage('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayLanguage('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayLanguage('sl-Latn-IT-nedis', 'de');
    ?>

El ejemplo anterior mostrará:

    Slovenian;
    slov\xc3\xa8ne;
    Slowenisch

### Ver también

- locale_get_display_name() - Devuelve un nombre de visualización correcto para una configuración local
- locale_get_display_script() - Devuelve el nombre del script de la configuración local
- locale_get_display_region() - Devuelve un nombre para la región de la configuración local
- locale_get_display_variant() - Devuelve un nombre para la variante de la configuración local

# Locale::getDisplayName

# locale_get_display_name

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayName -- locale_get_display_name — Devuelve un nombre de visualización correcto para una configuración local

### Descripción

Estilo orientado a objetos

public static function Locale::getDisplayName(string `$locale`, ?string `$displayLocale` = `null`): string|false

Estilo procedimental

function locale_get_display_name(string `$locale`, ?string `$displayLocale` = `null`): string|false

Devuelve un nombre de visualización correcto para una configuración local. Si `locale` es `null`, se utiliza la configuración local por omisión.

### Parámetros

`locale`

  La configuración local de la que se debe devolver un nombre de visualización.

`displayLocale`

  Un formato de visualización opcional

### Valores devueltos

El nombre de visualización de la configuración local, en el formato dado por `displayLocale`, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `displayLocale` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con locale_get_display_name(), procedimental

    <?php
    echo locale_get_display_name('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_name('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_name('sl-Latn-IT-nedis', 'de');
    ?>

Ejemplo #2 Ejemplo con locale_get_display_name(), POO

    <?php
    echo Locale::getDisplayName('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayName('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayName('sl-Latn-IT-nedis', 'de');
    ?>

El ejemplo anterior mostrará:

    Slovenian (Latin, Italy, Natisone dialect);
    slov\xc3\xa8ne (latin, Italie, dialecte de Natisone);
    Slowenisch (Lateinisch, Italien, NEDIS)

### Ver también

- locale_get_display_language() - Devuelve un nombre adecuado para mostrar un nombre de idioma
- locale_get_display_script() - Devuelve el nombre del script de la configuración local
- locale_get_display_region() - Devuelve un nombre para la región de la configuración local
- locale_get_display_variant() - Devuelve un nombre para la variante de la configuración local

# Locale::getDisplayRegion

# locale_get_display_region

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayRegion -- locale_get_display_region — Devuelve un nombre para la región de la configuración local

### Descripción

Estilo orientado a objetos

public static function Locale::getDisplayRegion(string `$locale`, ?string `$displayLocale` = `null`): string|false

Estilo procedimental

function locale_get_display_region(string `$locale`, ?string `$displayLocale` = `null`): string|false

Devuelve un nombre para la región de la configuración local. Si `null` es pasado, se utiliza la configuración local por defecto.

### Parámetros

`locale`

  La configuración local de la cual se debe extraer el nombre de la región.

`displayLocale`

  Un formato opcional para mostrar el nombre de la región.

### Valores devueltos

El nombre de la región de la `locale`, en el formato `displayLocale`, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `displayLocale` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con locale_get_display_region(), procedimental

    <?php
    echo locale_get_display_region('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_region('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_region('sl-Latn-IT-nedis', 'de');
    ?>

Ejemplo #2 Ejemplo con locale_get_display_region(), POO

    <?php
    echo Locale::getDisplayRegion('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayRegion('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayRegion('sl-Latn-IT-nedis', 'de');
    ?>

El ejemplo anterior mostrará:

    Italy;
    Italie;
    Italien

### Ver también

- locale_get_display_name() - Devuelve un nombre de visualización correcto para una configuración local
- locale_get_display_language() - Devuelve un nombre adecuado para mostrar un nombre de idioma
- locale_get_display_script() - Devuelve el nombre del script de la configuración local
- locale_get_display_variant() - Devuelve un nombre para la variante de la configuración local

# Locale::getDisplayScript

# locale_get_display_script

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayScript -- locale_get_display_script — Devuelve el nombre del script de la configuración local

### Descripción

Estilo orientado a objetos

public static function Locale::getDisplayScript(string `$locale`, ?string `$displayLocale` = `null`): string|false

Estilo procedimental

function locale_get_display_script(string `$locale`, ?string `$displayLocale` = `null`): string|false

Devuelve el nombre del script de la configuración local. Si `null` es pasado, se utiliza la configuración local por omisión.

### Parámetros

`locale`

  La configuración local de la cual se debe devolver el script.

`displayLocale`

  Un formato opcional para mostrar el nombre del script.

### Valores devueltos

Muestra el nombre del script de la `locale` en el formato indicado por `displayLocale`, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `displayLocale` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con locale_get_display_script(), procedimental

    <?php
    echo locale_get_display_script('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_script('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_script('sl-Latn-IT-nedis', 'de');
    ?>

Ejemplo #2 Ejemplo con locale_get_display_script(), POO

    <?php
    echo Locale::getDisplayScript('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayScript('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayScript('sl-Latn-IT-nedis', 'de');
    ?>

El ejemplo anterior mostrará:

    Latin;
    latin;
    Lateinisch

### Ver también

- locale_get_display_name() - Devuelve un nombre de visualización correcto para una configuración local
- locale_get_display_language() - Devuelve un nombre adecuado para mostrar un nombre de idioma
- locale_get_display_region() - Devuelve un nombre para la región de la configuración local
- locale_get_display_variant() - Devuelve un nombre para la variante de la configuración local

# Locale::getDisplayVariant

# locale_get_display_variant

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayVariant -- locale_get_display_variant — Devuelve un nombre para la variante de la configuración local

### Descripción

Estilo orientado a objetos

public static function Locale::getDisplayVariant(string `$locale`, ?string `$displayLocale` = `null`): string|false

Estilo procedimental

function locale_get_display_variant(string `$locale`, ?string `$displayLocale` = `null`): string|false

Devuelve un nombre para la variante de la configuración local. Si `null` es pasado, se utiliza la configuración local por defecto.

### Parámetros

`locale`

  La configuración local de la cual extraer el nombre de la región.

`displayLocale`

  Un formato opcional para mostrar el nombre de la región.

### Valores devueltos

El nombre de la variante de la `locale`, en el formato `displayLocale`, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `displayLocale` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con locale_get_display_variant(), procedimental

    <?php
    echo locale_get_display_variant('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_variant('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_variant('sl-Latn-IT-nedis', 'de');
    ?>

Ejemplo #2 Ejemplo con locale_get_display_variant(), POO

    <?php
    echo Locale::getDisplayVariant('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayVariant('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayVariant('sl-Latn-IT-nedis', 'de');
    ?>

El ejemplo anterior mostrará:

    Natisone dialect;
    dialecte de Natisone;
    NEDIS

### Ver también

- locale_get_display_name() - Devuelve un nombre de visualización correcto para una configuración local
- locale_get_display_language() - Devuelve un nombre adecuado para mostrar un nombre de idioma
- locale_get_display_script() - Devuelve el nombre del script de la configuración local
- locale_get_display_region() - Devuelve un nombre para la región de la configuración local

# Locale::getKeywords

# locale_get_keywords

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getKeywords -- locale_get_keywords — Lee las palabras clave de la configuración local

### Descripción

Estilo orientado a objetos

public static function Locale::getKeywords(string `$locale`): array|false|null

Estilo procedimental

function locale_get_keywords(string `$locale`): array|false|null

Lee las palabras clave de la configuración local.

### Parámetros

`locale`

  La configuración local de la cual extraer las palabras clave.

### Valores devueltos

Un array asociativo que contiene los pares clave-valor para esta configuración local.

Devuelve `null` cuando la longitud de `locale` excede `INTL_MAX_LOCALE_LEN`.

### Ejemplos

Ejemplo #1 Ejemplo con locale_get_keywords(), procedimental

    <?php
    $keywords_arr = locale_get_keywords('de_DE@currency=EUR;collation=PHONEBOOK');
    if ($keywords_arr) {
        foreach ($keywords_arr as $key => $value) {
            echo "$key = $value\n";
        }
    }
    ?>

Ejemplo #2 Ejemplo con locale_get_keywords(), POO

    <?php
    $keywords_arr = Locale::getKeywords('de_DE@currency=EUR;collation=PHONEBOOK');
    if ($keywords_arr) {
        foreach ($keywords_arr as $key => $value) {
            echo "$key = $value\n";
        }
    }
    ?>

El ejemplo anterior mostrará:

    collation = PHONEBOOK
    currency = EUR

### Ver también

- locale_get_all_variants() - Lista todas las variantes de una configuración local

# Locale::getPrimaryLanguage

# locale_get_primary_language

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getPrimaryLanguage -- locale_get_primary_language — Lee el idioma principal de la configuración local

### Descripción

Estilo orientado a objetos

public static function Locale::getPrimaryLanguage(string `$locale`): ?string

Estilo procedimental

function locale_get_primary_language(string `$locale`): ?string

Lee el idioma principal de la configuración local.

### Parámetros

`locale`

  La configuración local de la cual se debe extraer el idioma principal.

### Valores devueltos

El código de idioma asociado al idioma.

Devuelve `null` cuando la longitud de `locale` excede `INTL_MAX_LOCALE_LEN`.

### Ejemplos

Ejemplo #1 Ejemplo con locale_get_primary_language(), procedimental

    <?php
    echo locale_get_primary_language('zh-Hant');
    ?>

Ejemplo #2 Ejemplo con locale_get_primary_language(), POO

    <?php
    echo Locale::getPrimaryLanguage('zh-Hant');
    ?>

El ejemplo anterior mostrará:

    zh

### Ver también

- locale_get_script() - Devuelve un código para el script de la configuración local
- locale_get_region() - Devuelve un código para la región de la configuración local
- locale_get_all_variants() - Lista todas las variantes de una configuración local

# Locale::getRegion

# locale_get_region

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getRegion -- locale_get_region — Devuelve un código para la región de la configuración local

### Descripción

Estilo orientado a objetos

public static function Locale::getRegion(string `$locale`): ?string

Estilo procedimental

function locale_get_region(string `$locale`): ?string

Devuelve un código para la región de la configuración local.

### Parámetros

`locale`

  La configuración local de la que se debe extraer el código de región.

### Valores devueltos

El código de región para la configuración local, o bien `null` en caso de error.

Devuelve `null` cuando la longitud de `locale` excede `INTL_MAX_LOCALE_LEN`.

### Ejemplos

Ejemplo #1 Ejemplo con locale_get_region(), procedimental

    <?php
    echo locale_get_region('de-CH-1901');
    ?>

Ejemplo #2 Ejemplo con locale_get_region(), POO

    <?php
    echo Locale::getRegion('de-CH-1901');
    ?>

El ejemplo anterior mostrará:

    CH

### Ver también

- locale_get_primary_language() - Lee el idioma principal de la configuración local
- locale_get_script() - Devuelve un código para el script de la configuración local
- locale_get_all_variants() - Lista todas las variantes de una configuración local

# Locale::getScript

# locale_get_script

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getScript -- locale_get_script — Devuelve un código para el script de la configuración local

### Descripción

Estilo orientado a objetos

public static function Locale::getScript(string `$locale`): ?string

Estilo procedimental

function locale_get_script(string `$locale`): ?string

Devuelve un código para el script de la configuración local

### Parámetros

`locale`

  La configuración local de la cual extraer el código del script.

### Valores devueltos

El código de script para la configuración local o `null` si está ausente.

### Ejemplos

Ejemplo #1 Ejemplo con locale_get_script(), procedimental

    <?php
    echo locale_get_script('sr-Cyrl');
    ?>

Ejemplo #2 Ejemplo con locale_get_script(), POO

    <?php
    echo Locale::getScript('sr-Cyrl');
    ?>

El ejemplo anterior mostrará:

    Cyrl

### Ver también

- locale_get_primary_language() - Lee el idioma principal de la configuración local
- locale_get_region() - Devuelve un código para la región de la configuración local
- locale_get_all_variants() - Lista todas las variantes de una configuración local

# Locale::isRightToLeft

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

Locale::isRightToLeft — Comprueba si una configuración regional usa un sistema de escritura de derecha a izquierda

### Descripción

public static function Locale::isRightToLeft( string `$locale` = "" ): bool

Determina si una configuración regional usa un sistema de escritura de derecha a izquierda.

Este método se basa en la biblioteca ICU y evalúa el script dominante asociado a la configuración regional.

Si se proporciona una cadena vacía, se usa la configuración regional predeterminada.

### Parámetros

`locale`
  El identificador de configuración regional. Si está vacío, se usa la configuración regional predeterminada.

### Valores devueltos

Devuelve `true` si la configuración regional usa un sistema de escritura de derecha a izquierda, o `false` en caso contrario.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | Se ha añadido Locale::isRightToLeft().

### Ejemplos

Ejemplo #1 Comprobar la dirección del texto para una configuración regional

    <?php

    var_dump(Locale::isRightToLeft('en-US'));
    var_dump(Locale::isRightToLeft('ar'));

El ejemplo anterior mostrará:

    bool(false)
    bool(true)

# Locale::lookup

# locale_lookup

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::lookup -- locale_lookup — Búsqueda en la lista de la mejor lengua

### Descripción

Estilo orientado a objetos

public static function Locale::lookup(
array `$languageTag`,
string `$locale`,
bool `$canonicalize` = `false`,
?string `$defaultLocale` = `null`
): ?string

Estilo procedimental

function locale_lookup(
array `$languageTag`,
string `$locale`,
bool `$canonicalize` = `false`,
?string `$defaultLocale` = `null`
): ?string

Búsqueda en la lista `languageTag` de la mejor lengua, para la configuración local especificada por `locale`, según el algoritmo de la RFC 4647.

### Parámetros

`languageTag`

  Un array que contiene una lista de lenguas a comparar con la configuración local `locale`. Se permite un máximo de 100 elementos.

`locale`

  La configuración local a utilizar para realizar la búsqueda.

`canonicalize`

  Si `true` los argumentos serán convertidos a su forma canónica antes de su búsqueda.

`defaultLocale`

  La configuración local a utilizar si no se encuentra ninguna solución.

### Valores devueltos

La lengua más cercana que haya sido encontrada en la lista, o bien el valor por defecto.

Devuelve `null` cuando la longitud de `locale` excede `INTL_MAX_LOCALE_LEN`.

### Historial de cambios

Versión | Descripción
--- | ---
7.4.0 | `defaultLocale` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con locale_lookup(), procedimental

    <?php
    $arr = array(
        'de-DEVA',
        'de-DE-1996',
        'de',
        'de-De'
    );
    echo locale_lookup($arr, 'de-DE-1996-x-prv1-prv2', true, 'en_US');
    ?>

Ejemplo #2 Ejemplo con Locale::lookup(), POO

    <?php
    $arr = array(
        'de-DEVA',
        'de-DE-1996',
        'de',
        'de-De'
    );
    echo Locale::lookup($arr, 'de-DE-1996-x-prv1-prv2', true, 'en_US');
    ?>

El ejemplo anterior mostrará:

    de_de_1996

### Ver también

- locale_filter_matches() - Verifica si el tag de idioma coincide con una configuración local

# Locale::parseLocale

# locale_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::parseLocale -- locale_parse — Devuelve los subelementos de la configuración regional

### Descripción

Estilo orientado a objetos

public static function Locale::parseLocale(string `$locale`): ?array

Estilo procedimental

function locale_parse(string `$locale`): ?array

Devuelve un array de pares clave-valor para los elementos del subtag de la configuración regional.

### Parámetros

`locale`

  La configuración regional de la cual extraer el array. Tenga en cuenta que 'variant' y 'private' pueden tomar hasta 15 valores como máximo, mientras que 'extlang' puede tomar hasta 3 valores.

### Valores devueltos

Devuelve un array que contiene la lista de pares clave-valor, donde las claves son los nombres de los elementos, y los valores son su valor asociado. El array está ordenado de la misma manera que los elementos en la configuración regional, por ejemplo, si las variantes son '-varX-varY-varZ' entonces el array devuelto contendrá variant0=>varX, variant1=>varY, variant2=>varZ, etc.

Devuelve `null` cuando el tamaño de `locale` excede `INTL_MAX_LOCALE_LEN`.

### Ejemplos

Ejemplo #1 Ejemplo con locale_parse(), procedimental

    <?php
    $arr = locale_parse('sl-Latn-IT-nedis');
    if ($arr) {
        foreach ($arr as $key => $value) {
            echo "$key : $value , ";
        }
    }
    ?>

Ejemplo #2 Ejemplo con locale_parse(), POO

    <?php
    $arr = Locale::parseLocale('sl-Latn-IT-nedis');
    if ($arr) {
        foreach ($arr as $key => $value) {
            echo "$key : $value , ";
        }
    }
    ?>

El ejemplo anterior mostrará:

    language : sl , script : Latn , region : IT , variant0 : NEDIS ,

### Ver también

- locale_compose() - Retorna un identificador de configuración regional correcto

# Locale::setDefault

# locale_set_default

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::setDefault -- locale_set_default — Configura la configuración local por defecto

### Descripción

Estilo orientado a objetos

public static function Locale::setDefault(string `$locale`): true

Estilo procedimental

function locale_set_default(string `$locale`): true

Configura la configuración local por defecto a `locale`. Esto cambia el valor de la global INTL 'default_locale'. Las extensiones UAX #35 son también admitidas.

### Parámetros

`locale`

  Un idioma en formato BCP 47.

### Valores devueltos

Retorna `true`.

### Ejemplos

Ejemplo #1 Ejemplo con locale_set_default(), procedimental

    <?php
    locale_set_default('de-DE');
    echo locale_get_default();
    ?>

Ejemplo #2 Ejemplo con locale_set_default(), POO

    <?php
    Locale::setDefault('de-DE');
    echo Locale::getDefault();
    ?>

El ejemplo anterior mostrará:

    de-DE

### Ver también

- locale_get_default() - Lee el valor por defecto de una configuración local para la variable global 'default_locale'

## Tabla de contenidos

- Locale::acceptFromHttp — Determina la mejor configuración local a partir del encabezado HTTP "Accept-Language"
- Locale::canonicalize — Canoniza la cadena que representa la configuración local
- Locale::composeLocale — Retorna un identificador de configuración regional correcto
- Locale::filterMatches — Verifica si el tag de idioma coincide con una configuración local
- Locale::getAllVariants — Lista todas las variantes de una configuración local
- Locale::getDefault — Lee el valor por defecto de una configuración local para la variable global 'default_locale'
- Locale::getDisplayLanguage — Devuelve un nombre adecuado para mostrar un nombre de idioma
- Locale::getDisplayName — Devuelve un nombre de visualización correcto para una configuración local
- Locale::getDisplayRegion — Devuelve un nombre para la región de la configuración local
- Locale::getDisplayScript — Devuelve el nombre del script de la configuración local
- Locale::getDisplayVariant — Devuelve un nombre para la variante de la configuración local
- Locale::getKeywords — Lee las palabras clave de la configuración local
- Locale::getPrimaryLanguage — Lee el idioma principal de la configuración local
- Locale::getRegion — Devuelve un código para la región de la configuración local
- Locale::getScript — Devuelve un código para el script de la configuración local
- Locale::isRightToLeft — Comprueba si una configuración regional usa un sistema de escritura de derecha a izquierda
- Locale::lookup — Búsqueda en la lista de la mejor lengua
- Locale::parseLocale — Devuelve los subelementos de la configuración regional
- Locale::setDefault — Configura la configuración local por defecto

# La clase Normalizer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Introducción

La normalización es un proceso que implica la transformación de caracteres y de secuencias de caracteres en una representación formal. Este proceso es importante cuando los textos deben ser comparados con fines de ordenación y búsqueda, pero también es importante para el almacenamiento de datos, a fin de que los documentos sean coherentes.

El consorcio Unicode Consortium ha definido un número de formas de normalización para reflejar las diferentes necesidades de las aplicaciones:

- Forma de normalización D (NFD): descomposición canónica
- Forma de normalización C (NFC): descomposición canónica, seguida de una composición canónica
- Forma de normalización KD (NFKD): descomposición compatible
- Forma de normalización KC (NFKC): descomposición compatible seguida de una composición canónica

Las diferentes formas se definen en términos de transformaciones de texto, transformaciones que se expresan con algoritmos y archivos de datos.

## Sinopsis de la Clase

class Normalizer {
/* Constantes */
public const int FORM_D;
public const int NFD;
public const int FORM_KD;
public const int NFKD;
public const int FORM_C;
public const int NFC;
public const int FORM_KC;
public const int NFKC;
public const int FORM_KC_CF;
public const int NFKC_CF;
/* Métodos */
public static function getRawDecomposition(string `$string`, int `$form` = `Normalizer::FORM_C`): ?string
public static function isNormalized(string `$string`, int `$form` = `Normalizer::FORM_C`): bool
public static function normalize(string `$string`, int `$form` = `Normalizer::FORM_C`): string|false
}

## Constantes predefinidas

Las constantes siguientes definen las formas de normalización a aplicar por el normalizador :

`Normalizer::FORM_C` int
  Forma de normalización C (NFC) : descomposición canónica seguida de una composición canónica
`Normalizer::FORM_D` int
  Forma de normalización D (NFD) : descomposición canónica
`Normalizer::NFD` int

`Normalizer::FORM_KC` int
  Forma de normalización KC (NFKC) : descomposición compatible, seguida de una composición canónica
`Normalizer::NFKC` int

`Normalizer::FORM_KC_CF` int

`Normalizer::FORM_KD` int
  Forma de normalización KD (NFKD) : descomposición compatible
`Normalizer::NFKD` int

`Normalizer::NFC` int

`Normalizer::NFKC_CF` int

## Ver también

- » Normalización Unicode
- » Preguntas frecuentes sobre la normalización Unicode
- » Guía del usuario de ICU: Normalización
- » Referencia de la API de ICU: Normalización

## Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Las constantes de clase ahora están tipadas.
8.0.0 | `Normalizer::NONE` ha sido eliminado.

# Normalizer::getRawDecomposition

# normalizer_get_raw_decomposition

(PHP 7 >= 7.3, PHP 8)

Normalizer::getRawDecomposition -- normalizer_get_raw_decomposition — Devuelve la propiedad Decomposition_Mapping para el punto de código UTF-8 dado

### Descripción

Estilo orientado a objetos

public static function Normalizer::getRawDecomposition(string `$string`, int `$form` = `Normalizer::FORM_C`): ?string

Estilo procedimental

function normalizer_get_raw_decomposition(string `$string`, int `$form` = `Normalizer::FORM_C`): ?string

Devuelve la propiedad Decomposition_Mapping, tal como se especifica en la base de datos de caracteres Unicode (UCD), para el punto de código UTF-8 dado.

### Parámetros

`string`

  La cadena de entrada, que debe ser un solo punto de código UTF-8.

### Valores devueltos

Devuelve un string que contiene la propiedad Decomposition_Mapping, si está presente en el UCD.

Devuelve `null` si no hay propiedad Decomposition_Mapping para el carácter.

### Ejemplos

Ejemplo #1 Ejemplo de Normalizer::getRawDecomposition()

    <?php

    $result = "";
    $strings = [
        "a",
        "\u{FFDA}",
        "\u{FDFA}",
        "",
        "aa",
        "\xF5",
    ];

    foreach ($strings as $string) {
        $decomposition = Normalizer::getRawDecomposition($string);
        // $decomposition = normalizer_get_raw_decomposition($string); Enfoque procedimental

        $error_code = intl_get_error_code();
        $error_message = intl_get_error_message();

        $string_hex = bin2hex($string);
        $result .= "---------------------\n";

        if ($decomposition === null) {
            $result .= "'$string_hex' no tiene mapeo de descomposición\n";
        } else {
            $result .= "'$string_hex' tiene el mapeo de descomposición '" . bin2hex($decomposition) . "'\n";
        }

        $result .= "información de error: '$error_message' ($error_code)\n";
    }

    echo $result;
    ?>

El ejemplo anterior mostrará:

    ---------------------
    '61' no tiene mapeo de descomposición
    información de error: 'U_ZERO_ERROR' (0)
    ---------------------
    'efbf9a' tiene el mapeo de descomposición 'e385a1'
    información de error: 'U_ZERO_ERROR' (0)
    ---------------------
    'efb7ba' tiene el mapeo de descomposición 'd8b5d984d98920d8a7d984d984d98720d8b9d984d98ad98720d988d8b3d984d985'
    información de error: 'U_ZERO_ERROR' (0)
    ---------------------
    '' no tiene mapeo de descomposición
    información de error: 'La cadena de entrada debe tener exactamente un punto de código UTF-8: U_ILLEGAL_ARGUMENT_ERROR' (1)
    ---------------------
    '6161' no tiene mapeo de descomposición
    información de error: 'La cadena de entrada debe tener exactamente un punto de código UTF-8: U_ILLEGAL_ARGUMENT_ERROR' (1)
    ---------------------
    'f5' no tiene mapeo de descomposición
    información de error: 'Punto de código fuera de rango: U_ILLEGAL_ARGUMENT_ERROR' (1)

### Ver también

- Normalizer::normalize() - Normaliza una cadena en entrada
- Normalizer::isNormalized() - Comprueba si el string proporcionado ya está en el formato de normalización especificado

# Normalizer::isNormalized

# normalizer_is_normalized

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Normalizer::isNormalized -- normalizer_is_normalized — Comprueba si el string proporcionado ya está en el formato de normalización especificado

### Descripción

Estilo orientado a objetos

public static function Normalizer::isNormalized(string `$string`, int `$form` = `Normalizer::FORM_C`): bool

Estilo procedimental

function normalizer_is_normalized(string `$string`, int `$form` = `Normalizer::FORM_C`): bool

Verifica si una cadena está normalizada.

### Parámetros

`string`

  La cadena a normalizar.

`form`

  Una de las formas de normalización.

### Valores devueltos

`true` si la cadena está normalizada, y `false` en caso contrario o si hay un error.

### Ejemplos

Ejemplo #1 Ejemplo con normalizer_is_normalized(), en estilo procedimental

    <?php
    $char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
    $char_combining_ring_above = "\xCC\x8A";  // 'COMBINING RING ABOVE' (U+030A)

    $char_orig = 'A' . $char_combining_ring_above;
    $char_norm = normalizer_normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

    echo ( normalizer_is_normalized($char_orig, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
    echo '; ';
    echo ( normalizer_is_normalized($char_norm, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
    ?>

Ejemplo #2 Ejemplo con normalizer_is_normalized(), en estilo orientado a objetos

    <?php
    $char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
    $char_combining_ring_above = "\xCC\x8A";  // 'COMBINING RING ABOVE' (U+030A)

    $char_orig = 'A' . $char_combining_ring_above;
    $char_norm = Normalizer::normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

    echo ( Normalizer::isNormalized($char_orig, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
    echo '; ';
    echo ( Normalizer::isNormalized($char_norm, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
    ?>

El ejemplo anterior mostrará:

    not normalized; normalized

### Ver también

- normalizer_normalize() - Normaliza una cadena en entrada

# Normalizer::normalize

# normalizer_normalize

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Normalizer::normalize -- normalizer_normalize — Normaliza una cadena en entrada

### Descripción

Estilo orientado a objetos

public static function Normalizer::normalize(string `$string`, int `$form` = `Normalizer::FORM_C`): string|false

Estilo procedimental

function normalizer_normalize(string `$string`, int `$form` = `Normalizer::FORM_C`): string|false

Normaliza la cadena en entrada y devuelve una cadena normalizada.

### Parámetros

`string`

  La cadena a normalizar

`form`

  Una de las formas de normalización.

### Valores devueltos

La cadena normalizada, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con normalizer_normalize(), procedimental

    <?php
    $char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
    $char_combining_ring_above = "\xCC\x8A";  // 'COMBINING RING ABOVE' (U+030A)

    $char_1 = normalizer_normalize( $char_A_ring, Normalizer::FORM_C );
    $char_2 = normalizer_normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

    echo urlencode($char_1);
    echo ' ';
    echo urlencode($char_2);
    ?>

Ejemplo #2 Ejemplo con normalizer_normalize(), POO

    <?php
    $char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
    $char_combining_ring_above = "\xCC\x8A";  // 'COMBINING RING ABOVE' (U+030A)

    $char_1 = Normalizer::normalize( $char_A_ring, Normalizer::FORM_C );
    $char_2 = Normalizer::normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

    echo urlencode($char_1);
    echo ' ';
    echo urlencode($char_2);
    ?>

El ejemplo anterior mostrará:

    %C3%85 %C3%85

### Ver también

- normalizer_is_normalized() - Comprueba si el string proporcionado ya está en el formato de normalización especificado

## Tabla de contenidos

- Normalizer::getRawDecomposition — Devuelve la propiedad Decomposition_Mapping para el punto de código UTF-8 dado
- Normalizer::isNormalized — Comprueba si el string proporcionado ya está en el formato de normalización especificado
- Normalizer::normalize — Normaliza una cadena en entrada

# La clase MessageFormatter

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Introducción

MessageFormatter es una clase concreta que permite producir mensajes concatenados, independientes del idioma. Las métodos proporcionadas en esta clase se utilizan para construir mensajes que están destinados a los usuarios finales.

La clase MessageFormatter ensambla los mensajes a partir de diferentes fragmentos (textos, números y fechas), proporcionados por el programa. Gracias a la clase MessageFormatter, el programa no necesita conocer el orden de los fragmentos. La clase utiliza especificaciones de formato para ensamblar los fragmentos en un solo mensaje. Por ejemplo, MessageFormatter permite mostrar la frase `"Finalizado de imprimir x fichero sobre y..."` de una manera que permanece flexible para la traducción.

Anteriormente, un mensaje se creaba en forma de frase, y se gestionaba como un string. Este procedimiento generaba problemas para las traducciones, ya que la estructura de la frase, el orden de las palabras, el formato de los números, etc. era muy diferente de un idioma a otro. El enfoque de creación de mensajes, independiente del idioma, permite separar el mensaje y las variables. Con estas variables, MessageFormatter puede concatenar las diferentes partes del mensaje, formatearlas según las convenciones correctas, y proporcionar un mensaje bien formado.

MessageFormatter toma una serie de objetos, formatea los textos, y los inserta en los strings formateados en los emplazamientos correctos. Una amplia variedad de formatos puede ser utilizada en conjunción con MessageFormatter para gestionar el plural, los números, etc. Típicamente, el mensaje es proporcionado por un recurso, y los argumentos son preparados dinámicamente.

## Sinopsis de la Clase

class MessageFormatter {
/* Métodos */
public function __construct(string `$locale`, string `$pattern`)
public static function create(string `$locale`, string `$pattern`): ?MessageFormatter
public function format(array `$values`): string|false
public static function formatMessage(string `$locale`, string `$pattern`, array `$values`): string|false
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(): string
public function getPattern(): string|false
public function parse(string `$string`): array|false
public static function parseMessage(string `$locale`, string `$pattern`, string `$message`): array|false
public function setPattern(string `$pattern`): bool
}

## Ver también

- » Documentación de formato ICU
- » Descripción del formato de mensajes ICU
- » Formateadores de mensajes ICU
- » Formateadores de elección ICU

# MessageFormatter::create

# MessageFormatter::__construct

# msgfmt_create

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::create -- MessageFormatter::__construct -- msgfmt_create — Construye un nuevo formateador de mensajes

### Descripción

Estilo orientado a objetos (método)

public static function MessageFormatter::create(string `$locale`, string `$pattern`): ?MessageFormatter

Estilo orientado a objetos (constructor)

public function MessageFormatter::__construct(string `$locale`, string `$pattern`)

Estilo procedimental

function msgfmt_create(string `$locale`, string `$pattern`): ?MessageFormatter

Construye un nuevo formateador de mensajes.

### Parámetros

`locale`

  La configuración local a utilizar para el formato de los argumentos

`pattern`

  La cadena en la que se deben insertar los datos. El modelo utiliza una sintaxis que acepta comillas simples. Ver » Quoting/Escaping para más detalles.

### Valores devueltos

Un objeto de formateador de mensajes MessageFormatter, o `null` en caso de fallo.

### Errores/Excepciones

Cuando se invoca como constructor, IntlException es lanzado en caso de fallo.

### Ejemplos

Ejemplo #1 Ejemplo con msgfmt_create(), estilo procedimental

    <?php
    $fmt = msgfmt_create("en_US", "{0,number,integer} singes sur {1,number,integer} arbres font {2,number} singes par arbre");
    echo msgfmt_format($fmt, array(4560, 123, 4560/123));
    $fmt = msgfmt_create("de", "{0,number,integer} Affen über {1,number,integer} Bäume um {2,number} Affen pro Baum");
    echo msgfmt_format($fmt, array(4560, 123, 4560/123));
    ?>

Ejemplo #2 Ejemplo con msgfmt_create(), estilo procedimental

    <?php
    $fmt = new MessageFormatter("en_US", "{0,number,integer} singes sur {1,number,integer} arbres font {2,number} singes par arbre");
    echo $fmt->format(array(4560, 123, 4560/123));
    $fmt = new MessageFormatter("de", "{0,number,integer} Affen über {1,number,integer} Bäume um {2,number} Affen pro Baum");
    echo $fmt->format(array(4560, 123, 4560/123));
    ?>

El ejemplo anterior mostrará:

    4,560 singes sur 123 arbres font 37.073 singes par arbre
    4.560 Affen über 123 Bäume um 37,073 Affen pro Baum

### Ver también

- msgfmt_format() - Formatea un mensaje
- msgfmt_parse() - Analiza una cadena según el modelo
- msgfmt_get_error_code() - Lee el último código de error de la última operación
- msgfmt_get_error_message() - Lee el mensaje de error de la última operación

# MessageFormatter::format

# msgfmt_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::format -- msgfmt_format — Formatea un mensaje

### Descripción

Estilo orientado a objetos

public function MessageFormatter::format(array `$values`): string|false

Estilo procedimental

function msgfmt_format(MessageFormatter `$formatter`, array `$values`): string|false

Formatea un mensaje sustituyendo los datos en las cadenas de modelo, según las convenciones locales.

### Parámetros

`formatter`

  Un objeto de formateador de mensajes MessageFormatter

`values`

  Los argumentos a insertar en las cadenas

### Valores devueltos

La cadena formateada, `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con msgfmt_format(), estilo procedimental

    <?php
    $fmt = msgfmt_create("en_US", "{0,number,integer} singes sur {1,number,integer} arbres font {2,number} singes par arbre");
    echo msgfmt_format($fmt, array(4560, 123, 4560/123));
    $fmt = msgfmt_create("de", "{0,number,integer} Affen über {1,number,integer} Bäume um {2,number} Affen pro Baum");
    echo msgfmt_format($fmt, array(4560, 123, 4560/123));
    ?>

Ejemplo #2 Ejemplo con msgfmt_format(), estilo POO

    <?php
    $fmt = new MessageFormatter("en_US", "{0,number,integer} singes sur {1,number,integer} arbres font {2,number} singes par arbre");
    echo $fmt->format(array(4560, 123, 4560/123));
    $fmt = new MessageFormatter("de", "{0,number,integer} Affen über {1,number,integer} Bäume um {2,number} Affen pro Baum");
    echo $fmt->format(array(4560, 123, 4560/123));
    ?>

El ejemplo anterior mostrará:

    4,560 singes sur 123 arbres font 37.073 singes par arbre
    4.560 Affen über 123 Bäume um 37,073 Affen pro Baum

### Ver también

- msgfmt_create() - Construye un nuevo formateador de mensajes
- msgfmt_parse() - Analiza una cadena según el modelo
- msgfmt_format_message() - Formatea rápidamente un mensaje
- msgfmt_get_error_code() - Lee el último código de error de la última operación
- msgfmt_get_error_message() - Lee el mensaje de error de la última operación

# MessageFormatter::formatMessage

# msgfmt_format_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::formatMessage -- msgfmt_format_message — Formatea rápidamente un mensaje

### Descripción

Estilo orientado a objetos

public static function MessageFormatter::formatMessage(string `$locale`, string `$pattern`, array `$values`): string|false

Estilo procedimental

function msgfmt_format_message(string `$locale`, string `$pattern`, array `$values`): string|false

Función de formato rápido que formatea una cadena sin necesidad de crear explícitamente un objeto de formato. Utilice esta función cuando la operación de formato se realiza una sola vez y no es necesario conservar parámetros o estados, o cuando se desea personalizar la salida proporcionando directamente un contexto adicional a ICU.

### Parámetros

`locale`

  La configuración local a utilizar para el formato

`pattern`

  El string en el cual se deben insertar los datos. El patrón utiliza una sintaxis que acepta comillas; Ver » Quoting/Escaping para más detalles.

`values`

  El array de valores a insertar en la cadena de formato.

### Valores devueltos

La cadena formateada, o bien `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con msgfmt_format_message(), estilo procedimental

    <?php
    echo msgfmt_format_message("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree\n", array(4560, 123, 4560/123));
    echo msgfmt_format_message("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum\n", array(4560, 123, 4560/123));
    echo msgfmt_format_message("en", 'You finished {place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}!', ['place' => 3]), "\n";
    echo msgfmt_format_message("en",
            "There {apple, plural,
                =0 {are no apples}
                =1 {is one apple...}
                other {are # apples!}
            }",
        ['apple' => 0]
    ), "\n";

Ejemplo #2 Ejemplo con msgfmt_format_message(), estilo procedimental

    <?php
    echo MessageFormatter::formatMessage("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree\n", array(4560, 123, 4560/123));
    echo MessageFormatter::formatMessage("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum\n", array(4560, 123, 4560/123));
    echo MessageFormatter::formatMessage("en", 'You finished {place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}!', ['place' => 3]), "\n";
    echo MessageFormatter::formatMessage("en",
            "There {apple, plural,
                =0 {are no apples}
                =1 {is one apple...}
                other {are # apples!}
            }",
        ['apple' => 0]
    ), "\n";

El ejemplo anterior mostrará:

    4,560 monkeys on 123 trees make 37.073 monkeys per tree
    4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum
    You finished 3rd!
    There are no apples

Ejemplo #3 Solicitar a ICU que formatee la moneda con el símbolo monetario común y con el símbolo monetario corto.

Requiere ICU ≥ 67.

    <?php
    echo msgfmt_format_message("cs_CZ", "{0, number, :: currency/CAD}", array(123.45));
    echo msgfmt_format_message("cs_CZ", "{0, number, :: currency/CAD unit-width-narrow}", array(123.45));

El ejemplo anterior mostrará:

    123,45 CA$
    123,45 $

### Ver también

- msgfmt_create() - Construye un nuevo formateador de mensajes
- msgfmt_parse() - Analiza una cadena según el modelo
- msgfmt_get_error_code() - Lee el último código de error de la última operación
- msgfmt_get_error_message() - Lee el mensaje de error de la última operación

# MessageFormatter::getErrorCode

# msgfmt_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getErrorCode -- msgfmt_get_error_code — Lee el último código de error de la última operación

### Descripción

Estilo orientado a objetos

public function MessageFormatter::getErrorCode(): int

Estilo procedimental

function msgfmt_get_error_code(MessageFormatter `$formatter`): int

Lee el último código de error de la última operación.

### Parámetros

`formatter`

  Un objeto de formateador de mensajes MessageFormatter

### Valores devueltos

El código de error, una de las valores UErrorCode. El valor inicial es U_ZERO_ERROR.

### Ver también

- msgfmt_get_error_message() - Lee el mensaje de error de la última operación
- intl_get_error_code() - Lee el último código de error
- intl_is_failure() - Verifica si un código de error indica un fallo

# MessageFormatter::getErrorMessage

# msgfmt_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getErrorMessage -- msgfmt_get_error_message — Lee el mensaje de error de la última operación

### Descripción

Estilo orientado a objetos

public function MessageFormatter::getErrorMessage(): string

Estilo procedimental

function msgfmt_get_error_message(MessageFormatter `$formatter`): string

Lee el mensaje de error de la última operación del formateador de mensajes.

### Parámetros

`formatter`

  Un objeto de formateador de mensajes MessageFormatter

### Valores devueltos

La descripción del último error.

### Ejemplos

Ejemplo #1 Ejemplo con msgfmt_get_error_message(), estilo procedimental

    <?php
    $fmt = msgfmt_create("en_US", "{0, number} singes sur {1, number} arbres");
    $str = msgfmt_format($fmt, array());
    if(!$str) {
        echo "Error: ".msgfmt_get_error_message($fmt) . " (" . msgfmt_get_error_code($fmt) . ")\n";
    }
    ?>

Ejemplo #2 Ejemplo con msgfmt_get_error_message(), estilo POO

    <?php
    $fmt = new MessageFormatter("en_US", "{0, number} singes sur {1, number} arbres");
    $str = $fmt->format(array());
    if(!$str) {
        echo "Error: ".$fmt->getErrorMessage() . " (" . $fmt->getErrorCode() . ")\n";
    }
    ?>

El ejemplo anterior mostrará:

    Error: msgfmt_format: not enough parameters: U_ILLEGAL_ARGUMENT_ERROR (1)

### Ver también

- msgfmt_get_error_code() - Lee el último código de error de la última operación
- intl_get_error_code() - Lee el último código de error
- intl_is_failure() - Verifica si un código de error indica un fallo

# MessageFormatter::getLocale

# msgfmt_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getLocale -- msgfmt_get_locale — Lee la configuración local con la que el formateador fue creado

### Descripción

Estilo orientado a objetos

public function MessageFormatter::getLocale(): string

Estilo procedimental

function msgfmt_get_locale(MessageFormatter `$formatter`): string

Lee la configuración local con la que el formateador fue creado.

### Parámetros

`formatter`

  Un objeto de formateador de mensajes MessageFormatter

### Valores devueltos

El nombre de la configuración local

### Ejemplos

Ejemplo #1 Ejemplo con msgfmt_get_locale(), estilo procedimental

    <?php
    $fmt = msgfmt_create('en_US', "Nombre {0,number}");
    echo msgfmt_get_locale($fmt);
    ?>

Ejemplo #2 Ejemplo con msgfmt_get_locale(), estilo POO

    <?php
    $fmt = new MessageFormatter('en_US', "Nombre {0,number}");
    echo $fmt->getLocale();
    ?>

El ejemplo anterior mostrará:

    en_US

### Ver también

- msgfmt_create() - Construye un nuevo formateador de mensajes

# MessageFormatter::getPattern

# msgfmt_get_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getPattern -- msgfmt_get_pattern — Lee el modelo utilizado por el formateador de mensajes

### Descripción

Estilo orientado a objetos

public function MessageFormatter::getPattern(): string|false

Estilo procedimental

function msgfmt_get_pattern(MessageFormatter `$formatter`): string|false

Lee el modelo utilizado por el formateador de mensajes.

### Parámetros

`formatter`

  Un objeto de formateador de mensajes MessageFormatter

### Valores devueltos

La string de modelo del formateador de mensajes, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con msgfmt_get_pattern(), estilo procedimental

    <?php
    $fmt = msgfmt_create( "en_US", "{0, number} singes sur {1, number} arbres" );
    echo "Modelo por omisión : '" . msgfmt_get_pattern( $fmt ) . "'\n";
    echo "Resultado de formato :  " . msgfmt_format( $fmt, array(123, 456) ) . "\n";

    msgfmt_set_pattern( $fmt, "{0, number} arbres hosting {1, number} singes" );
    echo "Nuevo modelo :  '" . msgfmt_get_pattern( $fmt ) . "'\n";
    echo "Resultado de formato : " . msgfmt_format( $fmt, array(123, 456) ) . "\n";
    ?>

Ejemplo #2 Ejemplo con msgfmt_get_pattern(), estilo POO

    <?php
    $fmt = new MessageFormatter( "en_US", "{0, number} singes sur {1, number} arbres" );
    echo "Modelo por omisión : '" . $fmt->getPattern() . "'\n";
    echo "Resultado de formato :  " . $fmt->format(array(123, 456)) . "\n";

    $fmt->setPattern("{0, number} arbres hosting {1, number} singes" );
    echo "Nuevo modelo :  '" . $fmt->getPattern() . "'\n";
    echo "Resultado de formato : " . $fmt->format(array(123, 456)) . "\n";
    ?>

El ejemplo anterior mostrará:

    Modelo por omisión : '{0,number} singes sur {1,number} arbres'
    Resultado de formato :  123 singes sur 456 arbres
    Nuevo modelo :  '{0,number} arbres hosting {1,number} singes'
    Resultado de formato : 123 arbres hosting 456 singes

### Ver también

- msgfmt_create() - Construye un nuevo formateador de mensajes
- msgfmt_set_pattern() - Configura el patrón utilizado por el formateador

# MessageFormatter::parse

# msgfmt_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::parse -- msgfmt_parse — Analiza una cadena según el modelo

### Descripción

Estilo orientado a objetos

public function MessageFormatter::parse(string `$string`): array|false

Estilo procedimental

function msgfmt_parse(MessageFormatter `$formatter`, string `$string`): array|false

Analiza la cadena `value` y devuelve los elementos extraídos en forma de array.

### Parámetros

`formatter`

  Un objeto de formateador de mensajes MessageFormatter

`string`

  La string a analizar.

### Valores devueltos

Un array que contiene los elementos extraídos, o `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con msgfmt_parse(), estilo procedimental

    <?php
    $fmt = msgfmt_create('en_US', "{0,number,integer} singes sur {1,number,integer} arbres font {2,number} signes par arbre");
    $res = msgfmt_parse($fmt, "4,560 singes sur 123 arbres font 37.073 singes par arbre");
    var_export($res);

    $fmt = msgfmt_create('de', "{0,number,integer} Affen über {1,number,integer} Bäume um {2,number} Affen pro Baum");
    $res = msgfmt_parse($fmt, "4.560 Affen über 123 Bäume um 37,073 Affen pro Baum");
    var_export($res);
    ?>

Ejemplo #2 Ejemplo con msgfmt_parse(), estilo POO

    <?php
    $fmt = new MessageFormatter('en_US', "{0,number,integer} singes sur {1,number,integer} arbres font {2,number} signes par arbre");
    $res = $fmt->parse("4,560 singes sur 123 arbres font 37.073 singes par arbre");
    var_export($res);

    $fmt = new MessageFormatter('de', "{0,number,integer} Affen über {1,number,integer} Bäume um {2,number} Affen pro Baum");
    $res = $fmt->parse("4.560 Affen über 123 Bäume um 37,073 Affen pro Baum");
    var_export($res);
    ?>

El ejemplo anterior mostrará:

    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )
    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )

### Ver también

- msgfmt_create() - Construye un nuevo formateador de mensajes
- msgfmt_format() - Formatea un mensaje
- msgfmt_parse_message() - Analiza rápidamente una cadena

# MessageFormatter::parseMessage

# msgfmt_parse_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::parseMessage -- msgfmt_parse_message — Analiza rápidamente una cadena

### Descripción

Estilo orientado a objetos

public static function MessageFormatter::parseMessage(string `$locale`, string `$pattern`, string `$message`): array|false

Estilo procedimental

function msgfmt_parse_message(string `$locale`, string `$pattern`, string `$message`): array|false

Analiza la cadena de entrada sin crear explícitamente un objeto formateador. Utilice esta función cuando la operación de formato se realiza una sola vez, y no requiere parámetros ni estado.

### Parámetros

`locale`

  La configuración local a utilizar para analizar las partes de la cadena

`pattern`

  El patrón a utilizar para analizar `message`.

`message`

  La string a analizar, conforme a `pattern`.

### Valores devueltos

Un array que contiene los elementos extraídos, o `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con msgfmt_parse_message(), estilo procedimental

    <?php
    $fmt = msgfmt_parse_message('en_US', "{0,number,integer} singes sur {1,number,integer} arbres font {2,number} signes par arbre",
                                "4,560 singes sur 123 arbres font 37.073 signes par arbre");
    var_export($fmt);

    $fmt = msgfmt_parse_message('de', "{0,number,integer} Affen über {1,number,integer} Bäume um {2,number} Affen pro Baum",
                                "4.560 Affen über 123 Bäume um 37,073 Affen pro Baum");
    var_export($fmt);
    ?>

Ejemplo #2 Ejemplo con msgfmt_parse_message(), estilo POO

    <?php
    $fmt = MessageFormatter::parseMessage('en_US', "{0,number,integer} singes sur {1,number,integer} arbres font {2,number} signes par arbre",
                                "4,560 singes sur 123 arbres font 37.073 signes par arbre");
    var_export($fmt);

    $fmt = MessageFormatter::parseMessage('de', "{0,number,integer} Affen über {1,number,integer} Bäume um {2,number} Affen pro Baum",
                                "4.560 Affen über 123 Bäume um 37,073 Affen pro Baum");
    var_export($fmt);
    ?>

El ejemplo anterior mostrará:

    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )
    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )

### Ver también

- msgfmt_create() - Construye un nuevo formateador de mensajes
- msgfmt_format_message() - Formatea rápidamente un mensaje
- msgfmt_parse() - Analiza una cadena según el modelo

# MessageFormatter::setPattern

# msgfmt_set_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::setPattern -- msgfmt_set_pattern — Configura el patrón utilizado por el formateador

### Descripción

Estilo orientado a objetos

public function MessageFormatter::setPattern(string `$pattern`): bool

Estilo procedimental

function msgfmt_set_pattern(MessageFormatter `$formatter`, string `$pattern`): bool

Configura el patrón utilizado por el formateador.

### Parámetros

`formatter`

  Un objeto de formateador de mensajes MessageFormatter

`pattern`

  La cadena de patrón utilizada por el formateador de mensajes. El patrón utiliza una sintaxis que acepta comillas; Ver » Quoting/Escaping para más detalles.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con msgfmt_set_pattern(), estilo procedimental

    <?php
    $fmt = msgfmt_create( "en_US", "{0, number} singes sur {1, number} arbres" );
    echo "Patrón por omisión : '" . msgfmt_get_pattern( $fmt ) . "'\n";
    echo "Resultado formateado : " . msgfmt_format( $fmt, array(123, 456) ) . "\n";

    msgfmt_set_pattern( $fmt, "{0, number} arbres accueillant {1, number} singes" );
    echo "Nuevo patrón :'" . msgfmt_get_pattern( $fmt ) . "'\n";
    echo "Número formateado : " . msgfmt_format( $fmt, array(123, 456) ) . "\n";
    ?>

Ejemplo #2 Ejemplo con msgfmt_set_pattern(), estilo POO

    <?php
    $fmt = new MessageFormatter( "en_US", "{0, number} singes sur {1, number} arbres" );
    echo "Patrón por omisión : '" . $fmt->getPattern() . "'\n";
    echo "Resultado formateado : " . $fmt->format(array(123, 456)) . "\n";

    $fmt->setPattern("{0, number} arbres accueillant {1, number} singes" );
    echo "Nuevo patrón :'" . $fmt->getPattern() . "'\n";
    echo "Número formateado : " . $fmt->format(array(123, 456)) . "\n";
    ?>

El ejemplo anterior mostrará:

    Patrón por omisión : '{0,number} singes sur {1,number} arbres'
    Resultado formateado : 123 singes sur 456 arbres
    Nuevo patrón :'{0,number} arbres accueillant {1,number} singes'
    Número formateado : 123 arbres accueillant 456 singes

### Ver también

- msgfmt_create() - Construye un nuevo formateador de mensajes
- msgfmt_get_pattern() - Lee el modelo utilizado por el formateador de mensajes

## Tabla de contenidos

- MessageFormatter::create — Construye un nuevo formateador de mensajes
- MessageFormatter::format — Formatea un mensaje
- MessageFormatter::formatMessage — Formatea rápidamente un mensaje
- MessageFormatter::getErrorCode — Lee el último código de error de la última operación
- MessageFormatter::getErrorMessage — Lee el mensaje de error de la última operación
- MessageFormatter::getLocale — Lee la configuración local con la que el formateador fue creado
- MessageFormatter::getPattern — Lee el modelo utilizado por el formateador de mensajes
- MessageFormatter::parse — Analiza una cadena según el modelo
- MessageFormatter::parseMessage — Analiza rápidamente una cadena
- MessageFormatter::setPattern — Configura el patrón utilizado por el formateador

# La classe IntlCalendar

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

## Introducción

## Sinopsis de la Clase

class IntlCalendar {
/* Constantes */
public const int FIELD_ERA;
public const int FIELD_YEAR;
public const int FIELD_MONTH;
public const int FIELD_WEEK_OF_YEAR;
public const int FIELD_WEEK_OF_MONTH;
public const int FIELD_DATE;
public const int FIELD_DAY_OF_YEAR;
public const int FIELD_DAY_OF_WEEK;
public const int FIELD_DAY_OF_WEEK_IN_MONTH;
public const int FIELD_AM_PM;
public const int FIELD_HOUR;
public const int FIELD_HOUR_OF_DAY;
public const int FIELD_MINUTE;
public const int FIELD_SECOND;
public const int FIELD_MILLISECOND;
public const int FIELD_ZONE_OFFSET;
public const int FIELD_DST_OFFSET;
public const int FIELD_YEAR_WOY;
public const int FIELD_DOW_LOCAL;
public const int FIELD_EXTENDED_YEAR;
public const int FIELD_JULIAN_DAY;
public const int FIELD_MILLISECONDS_IN_DAY;
public const int FIELD_IS_LEAP_MONTH;
public const int FIELD_FIELD_COUNT;
public const int FIELD_DAY_OF_MONTH;
public const int DOW_SUNDAY;
public const int DOW_MONDAY;
public const int DOW_TUESDAY;
public const int DOW_WEDNESDAY;
public const int DOW_THURSDAY;
public const int DOW_FRIDAY;
public const int DOW_SATURDAY;
public const int DOW_TYPE_WEEKDAY;
public const int DOW_TYPE_WEEKEND;
public const int DOW_TYPE_WEEKEND_OFFSET;
public const int DOW_TYPE_WEEKEND_CEASE;
public const int WALLTIME_FIRST;
public const int WALLTIME_LAST;
public const int WALLTIME_NEXT_VALID;
/* Métodos */
private function __construct()
public function add(int `$field`, int `$value`): bool
public function after(IntlCalendar `$other`): bool
public function before(IntlCalendar `$other`): bool
public function clear(?int `$field` = `null`): true
public static function createInstance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar
public function equals(IntlCalendar `$other`): bool
public function fieldDifference(float `$timestamp`, int `$field`): int|false
public static function fromDateTime(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar
public function get(int `$field`): int|false
public function getActualMaximum(int `$field`): int|false
public function getActualMinimum(int `$field`): int|false
public static function getAvailableLocales(): array
public function getDayOfWeekType(int `$dayOfWeek`): int|false
public function getErrorCode(): int|false
public function getErrorMessage(): string|false
public function getFirstDayOfWeek(): int|false
public function getGreatestMinimum(int `$field`): int|false
public static function getKeywordValuesForLocale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false
public function getLeastMaximum(int `$field`): int|false
public function getLocale(int `$type`): string|false
public function getMaximum(int `$field`): int|false
public function getMinimalDaysInFirstWeek(): int|false
public function getMinimum(int `$field`): int|false
public static function getNow(): float
public function getRepeatedWallTimeOption(): int
public function getSkippedWallTimeOption(): int
public function getTime(): float|false
public function getTimeZone(): IntlTimeZone|false
public function getType(): string
public function getWeekendTransition(int `$dayOfWeek`): int|false
public function inDaylightTime(): bool
public function isEquivalentTo(IntlCalendar `$other`): bool
public function isLenient(): bool
public function isSet(int `$field`): bool
public function isWeekend(?float `$timestamp` = `null`): bool
public function roll(int `$field`, int|bool `$value`): bool
public function set(int `$field`, int `$value`): true
public function set(
int `$year`,
int `$month`,
int `$dayOfMonth` = NULL,
int `$hour` = NULL,
int `$minute` = NULL,
int `$second` = NULL
): true
public function setDate(int `$year`, int `$month`, int `$dayOfMonth`): void
public function setDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): void
public function setFirstDayOfWeek(int `$dayOfWeek`): true
public function setLenient(bool `$lenient`): true
public function setMinimalDaysInFirstWeek(int `$days`): true
public function setRepeatedWallTimeOption(int `$option`): true
public function setSkippedWallTimeOption(int `$option`): true
public function setTime(float `$timestamp`): bool
public function setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool
public function toDateTime(): DateTime|false
}

## Constantes predefinidas

`IntlCalendar::FIELD_ERA` int

  El campo de calendario que representa numéricamente una era, por ejemplo `1` para AD y `0` para BC en los calendarios gregoriano/juliano y `235` para la era Heisei (平成) en el calendario japonés. No todos los calendarios tienen más de una era.

`IntlCalendar::FIELD_YEAR` int

  El campo de calendario para el año. Esto no es único a través de las eras. Si el tipo de calendario tiene más de una era, generalmente el valor mínimo para este campo será `1`.

`IntlCalendar::FIELD_MONTH` int

  El campo de calendario para el mes. La secuencia de los meses comienza en cero, por lo que enero (aquí utilizado para significar el primer mes del calendario; esto puede tener otro nombre, como Muharram en el calendario islámico) está representado por `0`, febrero por `1`, …, diciembre por `11` y, para los calendarios que lo tienen, el 13º o mes bis por `12`.

`IntlCalendar::FIELD_WEEK_OF_YEAR` int

  El campo de calendario para el número de la semana del año. Esto depende del día de la semana que se considere como el inicio de la semana y del número mínimo de días en una semana.

`IntlCalendar::FIELD_WEEK_OF_MONTH` int

  El campo de calendario para el número de la semana del mes. Esto depende del día de la semana que se considere como el inicio de la semana y del número mínimo de días en una semana.

`IntlCalendar::FIELD_DATE` int

  El campo de calendario para el día del mes. Idéntico a `IntlCalendar::FIELD_DAY_OF_MONTH`, que tiene un nombre más claro.

`IntlCalendar::FIELD_DAY_OF_YEAR` int

  El campo de calendario para el día del año. Para el calendario gregoriano, comienza en `1` y termina en `365` o `366`.

`IntlCalendar::FIELD_DAY_OF_WEEK` int

  El campo de calendario para el día de la semana. Sus valores comienzan en `1` (domingo, ver `IntlCalendar::DOW_SUNDAY` y las constantes siguientes) y el último valor válido es `7` (sábado).

`IntlCalendar::FIELD_DAY_OF_WEEK_IN_MONTH` int

  Dado un día de la semana (domingo, lunes, …), este campo de calendario asigna un ordinal a tal día de la semana en un mes específico. Por lo tanto, si el valor de este campo es `1` y el valor del día de la semana es `2` (lunes), entonces el día definido del mes es el primer lunes del mes; el valor máximo es `5`.

  Además de esto, el valor `0` y los valores negativos también están permitidos. El valor `0` abarca los siete días que ocurren inmediatamente antes de los siete primeros días de un mes (que por lo tanto tienen un « día de la semana en el mes » con el valor `1`). Los valores negativos comienzan a contar desde el final del mes - `-1` apunta a la última ocurrencia de un día de la semana en un mes, `-2` a la penúltima, y así sucesivamente.

  A diferencia de `IntlCalendar::FIELD_WEEK_OF_MONTH` y `IntlCalendar::FIELD_WEEK_OF_YEAR`, este valor no depende de IntlCalendar::getFirstDayOfWeek() o de IntlCalendar::getMinimalDaysInFirstWeek(). El primer lunes es el primer lunes, incluso si se encuentra en una semana que pertenece al mes anterior.

`IntlCalendar::FIELD_AM_PM` int

  El campo de calendario que indica si una hora es antes del mediodía (valor `0`, AM) o después (`1`, PM). La medianoche es AM, el mediodía es PM.

`IntlCalendar::FIELD_HOUR` int

  El campo de calendario para la hora, sin especificar si es por la mañana o por la tarde. Los valores válidos son de `0` a `11`.

`IntlCalendar::FIELD_HOUR_OF_DAY` int

  El campo de calendario para la hora completa (24h) del día. Los valores válidos son de `0` a `23`.

`IntlCalendar::FIELD_MINUTE` int

  El campo de calendario para la componente minutos de la hora.

`IntlCalendar::FIELD_SECOND` int

  El campo de calendario para la componente segundos de la hora.

`IntlCalendar::FIELD_MILLISECOND` int

  El campo de calendario para la componente milisegundos de la hora.

`IntlCalendar::FIELD_ZONE_OFFSET` int

  El campo de calendario que indica el desplazamiento bruto del huso horario, en milisegundos. El desplazamiento bruto es el desplazamiento del huso horario, excluyendo cualquier desplazamiento debido al horario de verano.

`IntlCalendar::FIELD_DST_OFFSET` int

  El campo de calendario para el desplazamiento del horario de verano del huso horario del calendario, en milisegundos, si está activo para el huso horario

`IntlCalendar::FIELD_YEAR_WOY` int

  El campo de calendario que representa el año para los fines de la semana del año.

`IntlCalendar::FIELD_DOW_LOCAL` int

  El campo de calendario para el día localizado de la semana. Esto es un valor entre `1` y `7`, `1` siendo utilizado para el día de la semana que corresponde al valor devuelto por IntlCalendar::getFirstDayOfWeek().

`IntlCalendar::FIELD_EXTENDED_YEAR` int

  El campo de calendario para una representación numérica del año que es continua a través de las eras. Para el calendario gregoriano, el valor de este campo corresponde al de `IntlCalendar::FIELD_YEAR` para los años AD; un año BC `y` es representado por `-y + 1`.

`IntlCalendar::FIELD_JULIAN_DAY` int

  El campo de calendario para un número de días julianos modificado. Es diferente de un número convencional de días julianos en que sus transiciones ocurren a medianoche del huso horario local en lugar de a mediodía UTC. Identifica de manera única una fecha.

`IntlCalendar::FIELD_MILLISECONDS_IN_DAY` int

  El campo de calendario que engloba la información en `IntlCalendar::FIELD_HOUR_OF_DAY`, `IntlCalendar::FIELD_MINUTE`, `IntlCalendar::FIELD_SECOND` y `IntlCalendar::FIELD_MILLISECOND`. El rango es de `0` a `24 * 3600 * 1000 - 1`. Esto no es el número de milisegundos transcurridos en el día, ya que durante las transiciones DST tendrá discontinuidades análogas a las de la hora local.

`IntlCalendar::FIELD_IS_LEAP_MONTH` int

  El campo de calendario cuyo valor es `1` para indicar un mes bisiesto y `0` en caso contrario.

`IntlCalendar::FIELD_FIELD_COUNT` int

  El número total de campos.

`IntlCalendar::FIELD_DAY_OF_MONTH` int

  Un alias de `IntlCalendar::FIELD_DATE`.

`IntlCalendar::DOW_SUNDAY` int

  Domingo.

`IntlCalendar::DOW_MONDAY` int

  Lunes.

`IntlCalendar::DOW_TUESDAY` int

  Martes.

`IntlCalendar::DOW_WEDNESDAY` int

  Miércoles.

`IntlCalendar::DOW_THURSDAY` int

  Jueves.

`IntlCalendar::DOW_FRIDAY` int

  Viernes.

`IntlCalendar::DOW_SATURDAY` int

  Sábado.

`IntlCalendar::DOW_TYPE_WEEKDAY` int

  La salida de IntlCalendar::getDayOfWeekType() indicando que un día de la semana pertenece a la semana.

`IntlCalendar::DOW_TYPE_WEEKEND` int

  La salida de IntlCalendar::getDayOfWeekType() indicando que un día de la semana pertenece al fin de semana.

`IntlCalendar::DOW_TYPE_WEEKEND_OFFSET` int

  La salida de IntlCalendar::getDayOfWeekType() indicando que el fin de semana comienza durante el día de la semana dado.

`IntlCalendar::DOW_TYPE_WEEKEND_CEASE` int

  La salida de IntlCalendar::getDayOfWeekType() indicando que el fin de semana termina durante el día de la semana dado.

`IntlCalendar::WALLTIME_FIRST` int

  La salida de IntlCalendar::getSkippedWallTimeOption() indicando que las horas murales en el rango saltado deberían referirse al mismo instante que las horas murales con una hora menos y de IntlCalendar::getRepeatedWallTimeOption() indicando que las horas murales en el rango repetido deberían referirse al instante de la primera ocurrencia de esta hora murale.

`IntlCalendar::WALLTIME_LAST` int

  La salida de IntlCalendar::getSkippedWallTimeOption() indicando que las horas murales en el rango saltado deberían referirse al mismo instante que las horas murales con una hora más y de IntlCalendar::getRepeatedWallTimeOption() indicando que las horas murales en el rango repetido deberían referirse al instante de la segunda ocurrencia de esta hora murale.

`IntlCalendar::WALLTIME_NEXT_VALID` int

  La salida de IntlCalendar::getRepeatedWallTimeOption() indicando que las horas murales en el rango repetido deberían referirse al instante cuando la transición del horario de verano llega (comienza).

## Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Las constantes de clase ahora están tipadas.

# IntlCalendar::add

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::add — Añade una duración (con signo) a un campo

### Descripción

Estilo orientado a objetos

public function IntlCalendar::add(int `$field`, int `$value`): bool

Estilo procedimental

function intlcal_add(IntlCalendar `$calendar`, int `$field`, int `$value`): bool

Añade una duración con signo a un campo. La adición de una duración positiva permite avanzar en el tiempo, incluso si el valor numérico del campo disminuye (por ejemplo, cuando se trabaja con años en fechas BC).

Los otros campos deben ajustarse; por ejemplo, añadir un mes a la fecha del 31 de Enero devolverá el 28 (o 29) de Febrero. A diferencia de la función IntlCalendar::roll(), cuando un valor abarca varios valores, varios campos pueden cambiar significativamente. Por ejemplo, añadir un día al 31 de Enero devolverá el 1 de Febrero, y no el 1 de Enero.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`field`

  Una de las constantes del campo fecha/hora de IntlCalendar. Son valores de tipo integer entre `0` y `IntlCalendar::FIELD_COUNT`.

`value`

  La duración con signo a añadir al campo actual. Si la duración es positiva, el instante se moverá hacia adelante; si es negativa, el instante se moverá hacia el pasado. La unidad es implícita según el tipo de campo. Por ejemplo, será en horas para la constante `IntlCalendar::FIELD_HOUR_OF_DAY`.

### Valores devueltos

Devuelve `true` en caso de éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con IntlCalendar::add()

    <?php
    ini_set('intl.default_locale', 'fr_FR');
    ini_set('date.timezone', 'UTC');

    $cal = new IntlGregorianCalendar(2012, 0 /* January */, 31);
    echo IntlDateFormatter::formatObject($cal), "\n";

    $cal->add(IntlCalendar::FIELD_MONTH, 1);
    echo IntlDateFormatter::formatObject($cal), "\n";

    $cal->add(IntlCalendar::FIELD_DAY_OF_MONTH, 1);
    echo IntlDateFormatter::formatObject($cal), "\n";

El ejemplo anterior mostrará:

    31 janv. 2012 00:00:00
    29 févr. 2012 00:00:00
    1 mars 2012 00:00:00

# IntlCalendar::after

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::after — Verifica si el objeto tiempo actual está en el futuro respecto al objeto tiempo pasado

### Descripción

Estilo orientado a objetos

public function IntlCalendar::after(IntlCalendar `$other`): bool

Estilo procedimental

function intlcal_after(IntlCalendar `$calendar`, IntlCalendar `$other`): bool

Verifica si el objeto tiempo actual está en el futuro respecto al objeto tiempo pasado.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`other`

  El calendario para el cual el tiempo será verificado respecto al tiempo del objeto primario.

### Valores devueltos

Retorna `true` si el objeto tiempo actual está en el futuro respecto al tiempo del argumento `calendar`. Retorna `false` en caso contrario.

En caso de fallo, también se devuelve `false`. Para detectar condiciones de error, utilice intl_get_error_code(), o configure Intl para lanzar excepciones.

### Ejemplos

Ejemplo #1 Ejemplo con IntlCalendar::after()

    <?php
    $cal1 = IntlCalendar::createInstance();
    $cal2 = clone $cal1;

    var_dump($cal1->after($cal2), //false
            $cal2->after($cal1)); //false

    $cal1->roll(IntlCalendar::FIELD_MILLISECOND, true);

    var_dump($cal1->after($cal2), //true
            $cal2->after($cal1)); //false

# IntlCalendar::before

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::before — Verifica si el objeto tiempo está en el pasado en relación con el objeto proporcionado

### Descripción

Estilo orientado a objetos

public function IntlCalendar::before(IntlCalendar `$other`): bool

Estilo procedimental

function intlcal_before(IntlCalendar `$calendar`, IntlCalendar `$other`): bool

Verifica si el objeto tiempo está en el pasado en relación con el objeto proporcionado.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`other`

  El calendario para el cual el tiempo será verificado en relación con el tiempo del objeto principal.

### Valores devueltos

Devuelve `true` si el objeto tiempo actual está en el pasado en relación con el tiempo del argumento `calendar`. Devuelve `false` en caso contrario.

En caso de fallo, también se devuelve `false`. Para detectar condiciones de error, utilice intl_get_error_code(), o configure Intl para lanzar excepciones.

# IntlCalendar::clear

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::clear — Vacía un campo o todos los campos

### Descripción

Estilo orientado a objetos

public function IntlCalendar::clear(?int `$field` = `null`): true

Estilo procedimental

function intlcal_clear(IntlCalendar `$calendar`, ?int `$field` = `null`): true

Vacía un campo específico o todos los campos. Un campo vacío se marca como no utilizado, lo que le otorga la menor prioridad en comparación con los campos sobrescritos o incluso los valores por defecto durante el cálculo del tiempo. Además, este valor se establece a `0`, lo que otorga al campo una prioridad baja; este valor pudo haber sido establecido a otro valor por la duración que el campo tardó en completar su solicitud.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`field`

  Una de las constantes del campo fecha/hora de IntlCalendar. Son valores de tipo integer entre `0` y `IntlCalendar::FIELD_COUNT`.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.2.0 | El tipo de retorno es ahora `true`, anteriormente era bool.

### Ejemplos

Ejemplo #1 Ejemplo con IntlCalendar::clear()

    <?php
    ini_set('intl.default_locale', 'es_ES');
    ini_set('date.timezone', 'UTC');

    $fields = array(
        'FIELD_ERA'                  => 0,
        'FIELD_YEAR'                 => 1,
        'FIELD_MONTH'                => 2,
        'FIELD_WEEK_OF_YEAR'         => 3,
        'FIELD_WEEK_OF_MONTH'        => 4,
        'FIELD_DATE'                 => 5,
        'FIELD_DAY_OF_YEAR'          => 6,
        'FIELD_DAY_OF_WEEK'          => 7,
        'FIELD_DAY_OF_WEEK_IN_MONTH' => 8,
        'FIELD_AM_PM'                => 9,
        'FIELD_HOUR'                 => 10,
        'FIELD_HOUR_OF_DAY'          => 11,
        'FIELD_MINUTE'               => 12,
        'FIELD_SECOND'               => 13,
        'FIELD_MILLISECOND'          => 14,
        'FIELD_ZONE_OFFSET'          => 15,
        'FIELD_DST_OFFSET'           => 16,
        'FIELD_YEAR_WOY'             => 17,
        'FIELD_DOW_LOCAL'            => 18,
        'FIELD_EXTENDED_YEAR'        => 19,
        'FIELD_JULIAN_DAY'           => 20,
        'FIELD_MILLISECONDS_IN_DAY'  => 21,
        'FIELD_IS_LEAP_MONTH'        => 22,
        'FIELD_FIELD_COUNT'          => 23,
    );
    function getSetFields(IntlCalendar $cal) {
        global $fields;
        $ret = array();
        foreach ($fields as $name => $value) {
            if ($cal->isSet($value)) {
                $ret[] = $name;
            }
        }
        return $ret;
    }

    $cal = new IntlGregorianCalendar(2013, 2 /* Marzo */, 15);
    echo "Después de crear un GregorianCalendar\n";
    print_r(getSetFields($cal));
    echo "\n";

    echo IntlDateFormatter::formatObject($cal), "\n";
    echo "Después de que el formateador solicite el año extendido\n";
    print_r(getSetFields($cal));
    echo "\n";

    $cal->clear(IntlCalendar::FIELD_YEAR);
    echo "Después de vaciar el año, la fecha permanece igual\n";
    echo IntlDateFormatter::formatObject($cal), "\n";
    echo "ya que FIELD_EXTENDED_YEAR sigue definido\n";
    print_r(getSetFields($cal));
    echo "\n";

    var_dump($cal->clear(IntlCalendar::FIELD_EXTENDED_YEAR));
    echo "Después de vaciar el año extendido\n";
    print_r(getSetFields($cal));
    echo IntlDateFormatter::formatObject($cal), "\n";
    echo "\n";

    echo "Después de recalcular los campos,\n"
            . " el año extendido está definido de nuevo (a 1970)\n";
    print_r(getSetFields($cal));
    echo "\n";

    $cal->clear();
    echo "Después de llamar a la variante sin argumentos\n";
    print_r(getSetFields($cal));
    echo IntlDateFormatter::formatObject($cal), "\n";

El ejemplo anterior mostrará:

    Después de crear un GregorianCalendar
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_YEAR
        [2] => FIELD_MONTH
        [3] => FIELD_DATE
    )

    15/03/2013 00:00:00
    Después de que el formateador solicite el año extendido
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_YEAR
        [2] => FIELD_MONTH
        [3] => FIELD_DATE
        [4] => FIELD_EXTENDED_YEAR
    )

    Después de vaciar el año, la fecha permanece igual
    15/03/2013 00:00:00
    ya que FIELD_EXTENDED_YEAR sigue definido
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_MONTH
        [2] => FIELD_DATE
        [3] => FIELD_EXTENDED_YEAR
    )

    bool(true)
    Después de vaciar el año extendido
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_MONTH
        [2] => FIELD_DATE
    )
    15/03/1970 00:00:00

    Después de recalcular los campos,
     el año extendido está definido de nuevo (a 1970)
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_MONTH
        [2] => FIELD_DATE
        [3] => FIELD_EXTENDED_YEAR
    )

    Después de llamar a la variante sin argumentos
    Array
    (
    )
    01/01/1970 00:00:00

# IntlCalendar::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::__construct — Constructor privado para la desactivación de la instanciación

### Descripción

private function IntlCalendar::__construct()

Un constructor privado para desactivar la instanciación con el operador new.

Se recomienda llamar al método IntlCalendar::createInstance().

### Parámetros

Esta función no contiene ningún parámetro.

# IntlCalendar::createInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::createInstance — Crea un nuevo objeto IntlCalendar

### Descripción

Estilo orientado a objetos

public static function IntlCalendar::createInstance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar

Estilo procedimental

function intlcal_create_instance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar

Al proporcionar una zona horaria y una configuración local, este método crea un objeto IntlCalendar. Este método factoriel puede devolver una subclase de la clase IntlCalendar.

El calendario creado representará la instancia del tiempo en el momento en que fue creado, basado en el tiempo del sistema. Los campos pueden ser vaciados con el método IntCalendar::clear() sin argumentos. Ver también el método IntlGregorianCalendar::__construct().

### Parámetros

`timezone`

  La zona horaria a utilizar.

  - `null`, en cuyo caso se usará la zona horaria predeterminada, tal como está especificada en el ajuste ini date.timezone o a través de la función date_default_timezone_set() y como es devuelto por date_default_timezone_get().

  - Un IntlTimeZone, que se usará directamente.

  - Un DateTimeZone. Su identificador será extraido y se creará un objeto de zona horaria de ICU; la zona horaria será proporcionada por la base de datos de ICU, no por la de PHP.

  - Un string, que debería ser un identificador de zona horaria de ICU válido. Véase IntlTimeZone::createTimeZoneIDEnumeration(). Los índices puros como `"GMT+08:30"` también se aceptan.

`locale`

  Una configuración local a utilizar, o `null` para utilizar la configuración local por defecto.

### Valores devueltos

La instancia del objeto IntlCalendar creado, o `null` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con IntlCalendar::createInstance()

    <?php
    ini_set('intl.default_locale', 'es_ES');
    ini_set('date.timezone', 'Europe/Madrid');

    $cal = IntlCalendar::createInstance();
    echo "Sin argumentos\n";
    var_dump(get_class($cal),
            IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL));
    echo "\n";

    echo "Zona horaria explícita\n";
    $cal = IntlCalendar::createInstance(IntlTimeZone::getGMT());
    var_dump(get_class($cal),
            IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL));
    echo "\n";

    echo "Configuración local explícita (con el calendario)\n";
    $cal = IntlCalendar::createInstance(NULL, 'es_ES@calendar=persian');
    var_dump(get_class($cal),
            IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL));

El ejemplo anterior mostrará:

    Sin argumentos
    string(21) "IntlGregorianCalendar"
    string(68) "martes 18 de junio de 2013 14:11:02 Hora de verano de Europa Central"

    Zona horaria explícita
    string(21) "IntlGregorianCalendar"
    string(45) "martes 18 de junio de 2013 12:11:02 GMT+00:00"

    Configuración local explícita (con el calendario)
    string(12) "IntlCalendar"
    string(70) "martes 28 de Khordad de 1392 14:11:02 Hora de verano de Europa Central"

### Ver también

- IntlGregorianCalendar::__construct() - Crear la clase del calendario gregoriano

# IntlCalendar::equals

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::equals — Verifica si dos objetos IntlCalendar son iguales

### Descripción

Estilo orientado a objetos

public function IntlCalendar::equals(IntlCalendar `$other`): bool

Estilo procedimental

function intlcal_equals(IntlCalendar `$calendar`, IntlCalendar `$other`): bool

Devuelve `true` si este calendario y el proporcionado tienen el mismo tiempo. La configuración, el tipo de calendario, y los estados de los campos no deben ser necesariamente los mismos.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`other`

  El calendario a comparar con el objeto principal.

### Valores devueltos

Devuelve `true` si el tiempo actual es idéntico al del objeto IntlCalendar o `false` en caso contrario.

En caso de fallo, también se devuelve `false`. Para detectar condiciones de error, utilice intl_get_error_code(), o configure Intl para lanzar excepciones.

### Ejemplos

Ejemplo #1 Ejemplo con IntlCalendar::equals()

    <?php
    ini_set('date.timezone', 'UTC');

    $cal1 = IntlCalendar::createInstance(NULL, 'es_ES');
    $cal2 = clone $cal1;

    var_dump($cal1->equals($cal2)); //TRUE

    //La configuración local no está incluida en la comparación
    $cal2 = IntlCalendar::createInstance(NULL, 'pt_PT');
    $cal2->setTime($cal1->getTime());
    var_dump($cal1->equals($cal2)); //TRUE

    //Tampoco lo están los estados de los campos
    $cal2->clear(IntlCalendar::FIELD_YEAR);
    var_dump($cal1->isSet(IntlCalendar::FIELD_YEAR) ==
            $cal2->isSet(IntlCalendar::FIELD_YEAR)); //FALSE
    var_dump($cal1->equals($cal2)); //TRUE

    //Ni el tipo de calendario
    $cal2 = IntlCalendar::createInstance(NULL, 'es_ES@calendar=islamic');
    $cal2->setTime($cal1->getTime());
    var_dump($cal1->equals($cal2)); //TRUE

    //Solo el tiempo lo es
    $cal2 = clone $cal1;
    $cal2->setTime($cal1->getTime() + 1.);
    var_dump($cal1->equals($cal2)); //FALSE

# IntlCalendar::fieldDifference

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::fieldDifference — Calcula la diferencia entre el tiempo dado y el tiempo del objeto

### Descripción

Estilo orientado a objetos

public function IntlCalendar::fieldDifference(float `$timestamp`, int `$field`): int|false

Estilo procedimental

function intlcal_field_difference(IntlCalendar `$calendar`, float `$timestamp`, int `$field`): int|false

Devuelve la diferencia entre el tiempo dado y el tiempo de este objeto, respetando la cantidad especificada por el argumento `field`.

Este método está previsto para ser llamado sucesivamente, primero con el campo de interés más significativo, luego con el campo menos significativo. Al final, como efecto secundario, el valor del calendario para el campo especificado será avanzado por la duración devuelta.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`timestamp`

  El tiempo utilizado para la comparación con la cantidad representada por el campo `field`. Para que el resultado sea positivo, el tiempo proporcionado en este argumento debe estar en el futuro con respecto al tiempo del objeto del método.

`field`

  El campo que representa la cantidad a comparar.

  Una de las constantes del campo fecha/hora de IntlCalendar. Son valores de tipo integer entre `0` y `IntlCalendar::FIELD_COUNT`.

### Valores devueltos

Devuelve una diferencia (con signo) de tiempo, utilizando la unidad asociada con el campo especificado o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con IntlCalendar::fieldDifference()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'fr_FR');

    $cal1 = IntlCalendar::fromDateTime('2012-02-29 09:00:11');
    $cal2 = IntlCalendar::fromDateTime('2013-03-01 09:19:29');
    $time = $cal2->getTime();

    echo "Tiempo, antes de la operación: ", IntlDateFormatter::formatObject($cal1), "\n";

    printf(
        "La diferencia de tiempo es de %d año(s), %d mes(es), "
      . "%d día(s), %d hora(s) y %d minuto(s)\n",
        $cal1->fieldDifference($time, IntlCalendar::FIELD_YEAR),
        $cal1->fieldDifference($time, IntlCalendar::FIELD_MONTH),
        $cal1->fieldDifference($time, IntlCalendar::FIELD_DAY_OF_MONTH),
        $cal1->fieldDifference($time, IntlCalendar::FIELD_HOUR_OF_DAY),
        $cal1->fieldDifference($time, IntlCalendar::FIELD_MINUTE)
    );

    // ahora, el tiempo objetivo ha sido avanzado, excepto para los segundos,
    // para los cuales no medimos la diferencia
    echo "Tiempo, después de la operación: ", IntlDateFormatter::formatObject($cal1), "\n";

El ejemplo anterior mostrará:

    Tiempo, antes de la operación: 29 feb. 2012 09:00:11
    La diferencia de tiempo es de 1 año(s), 0 mes(es), 1 día(s), 0 hora(s) y 19 minuto(s)
    Tiempo, después de la operación: 1 mar. 2013 09:19:11

# IntlCalendar::fromDateTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a2)

IntlCalendar::fromDateTime — Crea un IntlCalendar a partir de un objeto DateTime o string

### Descripción

Estilo orientado a objetos

public static function IntlCalendar::fromDateTime(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar

Estilo procedimental

function intlcal_from_date_time(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar

Crea un objeto IntlCalendar ya sea a partir de un objeto DateTime o a partir de un string del cual se puede construir un objeto DateTime.

El nuevo calendario representará no solo el mismo instante que el DateTime dado (sujeto a pérdida de precisión para fechas muy lejanas en el pasado o futuro), sino también la misma zona horaria (sujeto a la salvedad de que se usarán diferentes bases de datos de zonas horarias, y por lo tanto los resultados pueden diferir).

### Parámetros

`datetime`

  Un objeto DateTime o un string que puede pasarse a DateTime::__construct().

### Valores devueltos

El objeto IntlCalendar creado o `null` en caso de error. Si se pasa un string, cualquier excepción que ocurra dentro del constructor de DateTime se propaga.

### Ejemplos

Ejemplo #1 IntlCalendar::fromDateTime()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');

    //igual que IntlCalendar::fromDateTime(new DateTime(...))
    $cal1 = IntlCalendar::fromDateTime('2013-02-28 00:01:02 Europe/Berlin', 'de_DE');

    //Nota: la zona horaria es Europe/Berlin, no la predeterminada Europe/Lisbon
    echo IntlDateFormatter::formatObject($cal1, 'yyyy MMMM d HH:mm:ss VVVV', 'de_DE'), "\n";

El ejemplo anterior mostrará:

    2013 Februar 28 00:01:02 Deutschland Zeit

# IntlCalendar::get

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::get — Recupera el valor de una propiedad

### Descripción

Estilo orientado a objetos

public function IntlCalendar::get(int `$field`): int|false

Estilo procedimental

function intlcal_get(IntlCalendar `$calendar`, int `$field`): int|false

Recupera el valor de una propiedad específica.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`field`

  Una de las constantes del campo fecha/hora de IntlCalendar. Son valores de tipo integer entre `0` y `IntlCalendar::FIELD_COUNT`.

### Valores devueltos

Un entero que contiene el valor de la propiedad.

### Ejemplos

Ejemplo #1 IntlCalendar::get()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');

    $class = new ReflectionClass('IntlCalendar');
    $fields = array();
    foreach ($class->getConstants() as $name => $val) {
        if (strpos($name, 'FIELD_') !== 0 || $val > 22)
            continue;
        $fields[$val] = $name;
    }

    $cal = IntlCalendar::createInstance(); // current time
    var_dump(IntlDateFormatter::formatObject($cal));
    foreach ($fields as $val => $name) {
        echo "$val ($name)", "\n    ", $cal->get($val), "\n";
    }

El ejemplo anterior mostrará:

    string(23) "Jul 1, 2013, 4:44:44 AM"
    0 (FIELD_ERA)
        1
    1 (FIELD_YEAR)
        2013
    2 (FIELD_MONTH)
        6
    3 (FIELD_WEEK_OF_YEAR)
        27
    4 (FIELD_WEEK_OF_MONTH)
        1
    5 (FIELD_DAY_OF_MONTH)
        1
    6 (FIELD_DAY_OF_YEAR)
        182
    7 (FIELD_DAY_OF_WEEK)
        2
    8 (FIELD_DAY_OF_WEEK_IN_MONTH)
        1
    9 (FIELD_AM_PM)
        0
    10 (FIELD_HOUR)
        4
    11 (FIELD_HOUR_OF_DAY)
        4
    12 (FIELD_MINUTE)
        44
    13 (FIELD_SECOND)
        44
    14 (FIELD_MILLISECOND)
        551
    15 (FIELD_ZONE_OFFSET)
        0
    16 (FIELD_DST_OFFSET)
        3600000
    17 (FIELD_YEAR_WOY)
        2013
    18 (FIELD_DOW_LOCAL)
        2
    19 (FIELD_EXTENDED_YEAR)
        2013
    20 (FIELD_JULIAN_DAY)
        2456475
    21 (FIELD_MILLISECONDS_IN_DAY)
        17084551
    22 (FIELD_IS_LEAP_MONTH)
        0

# IntlCalendar::getActualMaximum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getActualMaximum — El valor máximo para un campo, considerando el tiempo actual del objeto

### Descripción

Estilo orientado a objetos

public function IntlCalendar::getActualMaximum(int `$field`): int|false

Estilo procedimental

function intlcal_get_actual_maximum(IntlCalendar `$calendar`, int `$field`): int|false

Devuelve el valor máximo para un campo, considerando el tiempo actual del objeto. La semántica exacta varía según el campo, pero en el caso general, es el valor que se obtendría si se fijara el valor del campo al mínimo máximo relativo para el campo y se incrementara hasta alcanzar el máximo global o que el valor del campo se reinicie, en cuyo caso el valor devuelto sería el máximo global o el valor antes del reinicio, respectivamente.

Por ejemplo, en el calendario gregoriano, el valor máximo real para el día del mes variaría entre `28` y `31`, según el mes y el año del tiempo actual.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`field`

  Una de las constantes del campo fecha/hora de IntlCalendar. Son valores de tipo integer entre `0` y `IntlCalendar::FIELD_COUNT`.

### Valores devueltos

Un int que representa el valor máximo en las unidades asociadas al `field` dado o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 IntlCalendar::getActualMaximum()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');

    $cal = IntlCalendar::fromDateTime('2013-02-15');
    var_dump($cal->getActualMaximum(IntlCalendar::FIELD_DAY_OF_MONTH)); //28

    $cal->add(IntlCalendar::FIELD_EXTENDED_YEAR, -1);
    var_dump($cal->getActualMaximum(IntlCalendar::FIELD_DAY_OF_MONTH)); //29

El ejemplo anterior mostrará:

    int(28)
    int(29)

### Ver también

- IntlCalendar::getMaximum() - Obtiene el valor máximo global para un campo
- IntlCalendar::getLeastMaximum() - Obtiene el mínimo máximo local para un campo
- IntlCalendar::getActualMinimum() - El valor mínimo para un campo, considerando el tiempo actual del objeto

# IntlCalendar::getActualMinimum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getActualMinimum — El valor mínimo para un campo, considerando el tiempo actual del objeto

### Descripción

Estilo orientado a objetos

public function IntlCalendar::getActualMinimum(int `$field`): int|false

Estilo procedimental

function intlcal_get_actual_minimum(IntlCalendar `$calendar`, int `$field`): int|false

Devuelve el valor mínimo para un campo, considerando el tiempo actual del objeto. La semántica exacta varía según el campo, pero en el caso general, es el valor que se obtendría si se fijara el valor del campo al mínimo relativo más grande para el campo y se decrementara hasta alcanzar el mínimo global o que el valor del campo se reinicie, en cuyo caso el valor devuelto sería el mínimo global o el valor antes del reinicio, respectivamente.

Para el calendario gregoriano, es siempre el mismo valor que IntlCalendar::getMinimum().

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`field`

  Una de las constantes del campo fecha/hora de IntlCalendar. Son valores de tipo integer entre `0` y `IntlCalendar::FIELD_COUNT`.

### Valores devueltos

Un int que representa el valor mínimo en la unidad del campo o `false` si ocurre un error.

### Ver también

- IntlCalendar::getMinimum() - Obtiene el valor mínimo global para un campo
- IntlCalendar::getGreatestMinimum() - Devuelve el valor mínimo local más grande para un campo
- IntlCalendar::getActualMaximum() - El valor máximo para un campo, considerando el tiempo actual del objeto

# IntlCalendar::getAvailableLocales

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getAvailableLocales — Devuelve un array de locales para los cuales hay datos disponibles

### Descripción

Estilo orientado a objetos

public static function IntlCalendar::getAvailableLocales(): array

Estilo procedimental

function intlcal_get_available_locales(): array

Proporciona la lista de locales para los cuales están instalados los calendarios. A partir de ICU 51, es la lista de todos los locales ICU instalados.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array de string, uno para cada locale.

### Ejemplos

Ejemplo #1 IntlCalendar::getAvailableLocales()

    <?php
    print_r(IntlCalendar::getAvailableLocales());

El ejemplo anterior mostrará:

    Array
    (
        [0] => af
        [1] => af_NA
        [2] => af_ZA
        [3] => agq
        [4] => agq_CM
        [5] => ak
        [6] => ak_GH
        [7] => am
        [8] => am_ET
        [9] => ar
        [10] => ar_001
        [11] => ar_AE
        [12] => ar_BH
        [13] => ar_DJ
        … output abbreviated …
        [595] => zh_Hant_HK
        [596] => zh_Hant_MO
        [597] => zh_Hant_TW
        [598] => zu
        [599] => zu_ZA
    )

# IntlCalendar::getDayOfWeekType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getDayOfWeekType — Indica si un día es un día de la semana, un fin de semana o un día de transición entre ambos

### Descripción

Estilo orientado a objetos

public function IntlCalendar::getDayOfWeekType(int `$dayOfWeek`): int|false

Estilo procedimental

function intlcal_get_day_of_week_type(IntlCalendar `$calendar`, int `$dayOfWeek`): int|false

Devuelve si el día pasado es un día de semana (`IntlCalendar::DOW_TYPE_WEEKDAY`), un día de fin de semana (`IntlCalendar::DOW_TYPE_WEEKEND`), un día de transición hacia el fin de semana (`IntlCalendar::DOW_TYPE_WEEKEND_OFFSET`) o un día de transición fuera del fin de semana (`IntlCalendar::DOW_TYPE_WEEKEND_CEASE`).

Si el retorno es `IntlCalendar::DOW_TYPE_WEEKEND_OFFSET` o `IntlCalendar::DOW_TYPE_WEEKEND_CEASE`, entonces IntlCalendar::getWeekendTransition() puede ser llamada para obtener el tiempo de la transición.

Esta función requiere ICU 4.4 o más reciente.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`dayOfWeek`

  Una de las constantes `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, …, `IntlCalendar::DOW_SATURDAY`.

### Valores devueltos

Una de las constantes `IntlCalendar::DOW_TYPE_WEEKDAY`, `IntlCalendar::DOW_TYPE_WEEKEND`, `IntlCalendar::DOW_TYPE_WEEKEND_OFFSET` o `IntlCalendar::DOW_TYPE_WEEKEND_CEASE` o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 IntlCalendar::getDayOfWeekType()

    <?php
    foreach (array('en_US', 'ar_SA') as $locale) {
        echo "Locale: ", Locale::getDisplayName($locale, "en_US"), "\n";

        $cal = IntlCalendar::createInstance('UTC', $locale);

        for ($i = IntlCalendar::DOW_SUNDAY; $i <= IntlCalendar::DOW_SATURDAY; $i++) {
            $type = $cal->getDayOfWeekType($i);
            $transition = ($type !== IntlCalendar::DOW_TYPE_WEEKDAY)
                ? $cal->getWeekendTransition($i)
                : '';
            echo $i, " ", $type, " ", $transition, "\n";
        }
        echo "\n";
    }
    ?>

El ejemplo anterior mostrará:

    Locale: English (United States)
    1 1 86400000
    2 0
    3 0
    4 0
    5 0
    6 0
    7 1 0

    Locale: Arabic (Saudi Arabia)
    1 0
    2 0
    3 0
    4 0
    5 0
    6 1 0
    7 1 86400000

# IntlCalendar::getErrorCode

# intlcal_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getErrorCode -- intlcal_get_error_code — Devuelve el último código de error en el objeto

### Descripción

Estilo orientado a objetos (método):

public function IntlCalendar::getErrorCode(): int|false

Estilo procedimental:

function intlcal_get_error_code(IntlCalendar `$calendar`): int|false

Devuelve el código de error numérico ICU para la última llamada en este objeto (incluyendo el clonado) o el objeto IntlCalendar dado para el argumento `calendar` (en la versión procedimental). Esto puede indicar solamente una advertencia (código de error negativo) o ninguna error en absoluto (`U_ZERO_ERROR`). La presencia real de un error puede ser probada con intl_is_failure().

Los argumentos inválidos detectados del lado PHP (antes de la invocación de las funciones de la biblioteca ICU) no son registrados para los propósitos de esta función.

El último código de error que ocurrió en cualquier llamada a una función de la extensión intl, incluyendo los errores de argumentos tempranos, puede ser obtenido con intl_get_error_code(). Esta función reinicia el código de error global, pero no el código de error del objeto.

### Parámetros

`calendar`

  El objeto calendario, en la interfaz de estilo procedimental.

### Valores devueltos

Un código de error ICU indicando éxito, fallo o advertencia. Devuelve `false` en caso de fallo.

### Ejemplos

Ejemplo #1 IntlCalendar::getErrorCode() y IntlCalendar::getErrorMessage()

    <?php
    ini_set("intl.error_level", E_WARNING);
    ini_set("intl.default_locale", "nl");

    $intlcal = new IntlGregorianCalendar(2012, 1, 29);
    var_dump(
        $intlcal->getErrorCode(),
        $intlcal->getErrorMessage()
    );
    $intlcal->fieldDifference(-1e100, IntlCalendar::FIELD_SECOND);

    var_dump(
        $intlcal->getErrorCode(),
        $intlcal->getErrorMessage()
    );

El ejemplo anterior mostrará:

    int(0)
    string(12) "U_ZERO_ERROR"

    Warning: IntlCalendar::fieldDifference(): intlcal_field_difference: Call to ICU method has failed in /home/glopes/php/ws/example.php on line 10
    int(1)
    string(81) "intlcal_field_difference: Call to ICU method has failed: U_ILLEGAL_ARGUMENT_ERROR"

### Ver también

- IntlCalendar::getErrorMessage() - Devuelve el último mensaje de error en el objeto
- intl_is_failure() - Verifica si un código de error indica un fallo
- intl_error_name() - Lee el nombre simbólico de un código de error dado
- intl_get_error_code() - Lee el último código de error
- intl_get_error_message() - Lee la descripción del último error

# IntlCalendar::getErrorMessage

# intlcal_get_error_message

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getErrorMessage -- intlcal_get_error_message — Devuelve el último mensaje de error en el objeto

### Descripción

Estilo orientado a objetos (método):

public function IntlCalendar::getErrorMessage(): string|false

Estilo procedimental:

function intlcal_get_error_message(IntlCalendar `$calendar`): string|false

Devuelve (si existe) el mensaje de error asociado al error reportado por IntlCalendar::getErrorCode() o intlcal_get_error_code(). Si no existe un mensaje de error asociado, solo se devuelve la representación de string del nombre de la constante de error. De lo contrario, el mensaje incluye también un mensaje definido del lado de la ligadura PHP.

### Parámetros

`calendar`

  El objeto calendario, en la interfaz de estilo procedimental.

### Valores devueltos

El mensaje de error asociado al último error ocurrido en una llamada de función sobre este objeto, o un string indicando la inexistencia de un error. Devuelve `false` en caso de fallo.

### Ejemplos

Ejemplo #1 IntlCalendar::getErrorMessage()

    <?php
    $cal = IntlCalendar::createInstance('UTC', 'en_US');
    var_dump($cal->getErrorMessage());

    $cal->getWeekendTransition(IntlCalendar::DOW_WEDNESDAY);
    var_dump($cal->getErrorMessage());

El ejemplo anterior mostrará:

    string(12) "U_ZERO_ERROR"
    string(82) "intlcal_get_weekend_transition: Error calling ICU method: U_ILLEGAL_ARGUMENT_ERROR"

# IntlCalendar::getFirstDayOfWeek

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getFirstDayOfWeek — Devuelve el primer día de la semana para la configuración local del calendario

### Descripción

Estilo orientado a objetos

public function IntlCalendar::getFirstDayOfWeek(): int|false

Estilo procedimental

function intlcal_get_first_day_of_week(IntlCalendar `$calendar`): int|false

Devuelve el día de la semana considerado como primer día de la semana, ya sea el valor por omisión para esta configuración local, o el valor definido con IntlCalendar::setFirstDayOfWeek().

### Parámetros

`calendar`
  Una instancia de IntlCalendar.

### Valores devueltos

Una de las constantes `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, …, `IntlCalendar::DOW_SATURDAY` o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 IntlCalendar::getFirstDayOfWeek()

    <?php
    ini_set('date.timezone', 'UTC');

    $cal1 = IntlCalendar::createInstance(NULL, 'es_ES');
    var_dump($cal1->getFirstDayOfWeek()); // Lunes
    $cal1->set(2013, 1 /* February */, 3); // un domingo
    var_dump($cal1->get(IntlCalendar::FIELD_WEEK_OF_YEAR)); // 5

    $cal2 = IntlCalendar::createInstance(NULL, 'en_US');
    var_dump($cal2->getFirstDayOfWeek()); // Domingo
    $cal2->set(2013, 1 /* February */, 3); // un domingo
    var_dump($cal2->get(IntlCalendar::FIELD_WEEK_OF_YEAR)); // 6

El ejemplo anterior mostrará:

    int(2)
    int(5)
    int(1)
    int(6)

### Ver también

- IntlCalendar::setFirstDayOfWeek() - Define el día de inicio de la semana

# IntlCalendar::getGreatestMinimum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getGreatestMinimum — Devuelve el valor mínimo local más grande para un campo

### Descripción

Estilo orientado a objetos

public function IntlCalendar::getGreatestMinimum(int `$field`): int|false

Estilo procedimental

function intlcal_get_greatest_minimum(IntlCalendar `$calendar`, int `$field`): int|false

Devuelve el valor mínimo local más grande para un campo. Este valor debe ser mayor o igual al devuelto por IntlCalendar::getActualMinimum(), que a su vez debe ser mayor o igual al devuelto por IntlCalendar::getMinimum(). Estas tres funciones devuelven el mismo valor para el calendario gregoriano.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`field`

  Una de las constantes del campo fecha/hora de IntlCalendar. Son valores de tipo integer entre `0` y `IntlCalendar::FIELD_COUNT`.

### Valores devueltos

Un int que representa un valor de campo, en la unidad del campo, o `false` si ocurre un error.

# IntlCalendar::getKeywordValuesForLocale

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getKeywordValuesForLocale — Devuelve el conjunto de valores de palabras clave de configuración regional

### Descripción

Estilo orientado a objetos

public static function IntlCalendar::getKeywordValuesForLocale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false

Estilo procedimental

function intlcal_get_keyword_values_for_locale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false

Para una clave de configuración regional dada, devuelve el conjunto de valores para esta clave que producirían un comportamiento diferente. Por el momento, solo la palabra clave `'calendar'` es soportada.

Esta función requiere ICU 4.2 o posterior.

### Parámetros

`keyword`

  La palabra clave de configuración regional para la cual deben consultarse los valores pertinentes. Solo `'calendar'` es soportado.

`locale`

  La configuración regional sobre la cual debe añadirse el par palabra clave/valor.

`onlyCommon`

  Indica si deben mostrarse únicamente los valores comúnmente utilizados para la configuración regional especificada.

### Valores devueltos

Un iterador que devuelve strings con los valores de palabra clave de configuración regional o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 IntlCalendar::getKeywordValuesForLocale()

    <?php
    print_r(
            iterator_to_array(
                    IntlCalendar::getKeywordValuesForLocale(
                            'calendar', 'fa_IR', true)));
    print_r(
            iterator_to_array(
                    IntlCalendar::getKeywordValuesForLocale(
                            'calendar', 'fa_IR', false)));

El ejemplo anterior mostrará:

    Array
    (
        [0] => persian
        [1] => gregorian
        [2] => islamic
        [3] => islamic-civil
    )
    Array
    (
        [0] => persian
        [1] => gregorian
        [2] => islamic
        [3] => islamic-civil
        [4] => japanese
        [5] => buddhist
        [6] => roc
        [7] => hebrew
        [8] => chinese
        [9] => indian
        [10] => coptic
        [11] => ethiopic
        [12] => ethiopic-amete-alem
    )

# IntlCalendar::getLeastMaximum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getLeastMaximum — Obtiene el mínimo máximo local para un campo

### Descripción

Estilo orientado a objetos

public function IntlCalendar::getLeastMaximum(int `$field`): int|false

Estilo procedimental

function intlcal_get_least_maximum(IntlCalendar `$calendar`, int `$field`): int|false

Devuelve el mínimo máximo local para un campo. Esto debería ser un valor menor o igual al devuelto por IntlCalendar::getActualMaximum(), que a su vez es menor o igual al devuelto por IntlCalendar::getMaximum().

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`field`

  Una de las constantes del campo fecha/hora de IntlCalendar. Son valores de tipo integer entre `0` y `IntlCalendar::FIELD_COUNT`.

### Valores devueltos

Un int que representa un valor de campo, en la unidad del campo, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de máximo

    <?php
    ini_set('date.timezone', 'UTC');
    ini_set('intl.default_locale', 'it_IT');

    $cal = new IntlGregorianCalendar(2013, 3 /* April */, 6);
    var_dump(
        $cal->getLeastMaximum(IntlCalendar::FIELD_DAY_OF_MONTH),  // 28
        $cal->getActualMaximum(IntlCalendar::FIELD_DAY_OF_MONTH), // 30
        $cal->getMaximum(IntlCalendar::FIELD_DAY_OF_MONTH)        // 31
    );

El ejemplo anterior mostrará:

    int(28)
    int(30)
    int(31)

### Ver también

- IntlCalendar::getActualMaximum() - El valor máximo para un campo, considerando el tiempo actual del objeto
- IntlCalendar::getMaximum() - Obtiene el valor máximo global para un campo
- IntlCalendar::getGreatestMinimum() - Devuelve el valor mínimo local más grande para un campo

# IntlCalendar::getLocale

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getLocale — Devuelve la configuración local asociada al objeto

### Descripción

Estilo orientado a objetos

public function IntlCalendar::getLocale(int `$type`): string|false

Estilo procedimental

function intlcal_get_locale(IntlCalendar `$calendar`, int `$type`): string|false

Devuelve la configuración local utilizada por este objeto calendario.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`type`

  Indica si la configuración local actual (la configuración local a partir de la cual provienen los datos del calendario, con `Locale::ACTUAL_LOCALE`) o la configuración local válida, es decir, la configuración local más específica soportada por ICU en relación con la configuración local solicitada – ver `Locale::VALID_LOCALE`. De la más general a la más específica, las configuraciones locales se ordenan de esta forma – configuración local actual, configuración local válida, configuración local solicitada.

### Valores devueltos

Un string que representa la configuración local o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 IntlCalendar::getLocale()

    <?php
    $cal = IntlCalendar::createInstance(IntlTimeZone::getGMT(), 'en_US_CALIFORNIA');
    var_dump(
        $cal->getLocale(Locale::ACTUAL_LOCALE),
        $cal->getLocale(Locale::VALID_LOCALE)
    );

El ejemplo anterior mostrará:

    string(2) "en"
    string(5) "en_US"

# IntlCalendar::getMaximum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getMaximum — Obtiene el valor máximo global para un campo

### Descripción

Estilo orientado a objetos

public function IntlCalendar::getMaximum(int `$field`): int|false

Estilo procedimental

function intlcal_get_maximum(IntlCalendar `$calendar`, int `$field`): int|false

Devuelve el máximo global para un campo, en este calendario específico. Este valor es mayor o igual al devuelto por IntlCalendar::getActualMaximum(), que a su vez es mayor o igual al devuelto por IntlCalendar::getLeastMaximum().

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`field`

  Una de las constantes del campo fecha/hora de IntlCalendar. Son valores de tipo integer entre `0` y `IntlCalendar::FIELD_COUNT`.

### Valores devueltos

Un int que representa un valor de campo, en la unidad del campo, o `false` si ocurre un error.

### Ver también

- IntlCalendar::getActualMaximum() - El valor máximo para un campo, considerando el tiempo actual del objeto
- IntlCalendar::getLeastMaximum() - Obtiene el mínimo máximo local para un campo
- IntlCalendar::getMinimum() - Obtiene el valor mínimo global para un campo

# IntlCalendar::getMinimalDaysInFirstWeek

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getMinimalDaysInFirstWeek — Obtiene el número mínimo de días que la primera semana de un año o mes puede tener

### Descripción

Estilo orientado a objetos

public function IntlCalendar::getMinimalDaysInFirstWeek(): int|false

Estilo procedimental

function intlcal_get_minimal_days_in_first_week(IntlCalendar `$calendar`): int|false

Devuelve el número más pequeño de días que la primera semana de un año o mes debe tener en el nuevo año o mes. Por ejemplo, en el calendario gregoriano, si este valor es 1, entonces la primera semana del año incluirá necesariamente el 1 de enero, mientras que si este valor es 7, entonces la semana con el 1 de enero será la primera semana del año solo si el día de la semana para el 1 de enero coincide con el día de la semana devuelto por IntlCalendar::getFirstDayOfWeek(); de lo contrario, será la última semana del año anterior.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.

### Valores devueltos

Un int que representa un número de día o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 IntlCalendar::getMinimalDaysInFirstWeek()

    <?php
    ini_set('date.timezone', 'UTC');
    ini_set('intl.default_locale', 'en_US');

    $cal = new IntlGregorianCalendar(2013, 0 /* January */, 2);
    var_dump(IntlDateFormatter::formatObject($cal, 'cccc')); // Miércoles

    var_dump($cal->getMinimalDaysInFirstWeek(), // 1
    $cal->getFirstDayofWeek()); // 1 (Domingo)

    // Semana 1 de 2013
    var_dump(IntlDateFormatter::formatObject($cal, "'Week 'w' of 'Y"));

    $cal->setMinimalDaysInFirstWeek(4);
    // Siempre semana 1 de 2013 (La 1ª semana tiene 5 días en el nuevo año)
    var_dump(IntlDateFormatter::formatObject($cal, "'Week 'w' of 'Y"));

    $cal->setMinimalDaysInFirstWeek(6);
    // Semana 53 de 2012
    var_dump(IntlDateFormatter::formatObject($cal, "'Week 'w' of 'Y"));

El ejemplo anterior mostrará:

    string(9) "Wednesday"
    int(1)
    int(1)
    string(14) "Week 1 of 2013"
    string(14) "Week 1 of 2013"
    string(15) "Week 53 of 2012"

# IntlCalendar::getMinimum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getMinimum — Obtiene el valor mínimo global para un campo

### Descripción

Estilo orientado a objetos

public function IntlCalendar::getMinimum(int `$field`): int|false

Estilo procedimental

function intlcal_get_minimum(IntlCalendar `$calendar`, int `$field`): int|false

Devuelve el valor mínimo global para un campo, en este calendario específico. Este valor es menor o igual al devuelto por IntlCalendar::getActualMinimum(), que a su vez es menor o igual al devuelto por IntlCalendar::getGreatestMinimum(). Para el calendario gregoriano, estas tres funciones siempre devuelven el mismo valor (para cada campo).

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`field`

  Una de las constantes del campo fecha/hora de IntlCalendar. Son valores de tipo integer entre `0` y `IntlCalendar::FIELD_COUNT`.

### Valores devueltos

Un int que representa un valor de campo, en la unidad del campo, o `false` si ocurre un error.

# IntlCalendar::getNow

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getNow — Obtiene el número que representa la fecha actual

### Descripción

Estilo orientado a objetos

public static function IntlCalendar::getNow(): float

Estilo procedimental

function intlcal_get_now(): float

El número de milisegundos transcurridos desde la fecha de referencia. Este número se deriva del tiempo del sistema.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un número de coma flotante que representa un número de milisegundos desde la época, sin contar los segundos intercalares.

### Ejemplos

Ejemplo #1 Ejemplo con IntlCalendar::getNow()

    <?php
    $formatter = IntlDateFormatter::create('es_ES',
            IntlDateFormatter::FULL,
            IntlDateFormatter::FULL,
            'Europe/Madrid');

    $val = IntlCalendar::getNow();

    var_dump($val);
    echo $formatter->format(IntlCalendar::getNow() / 1000.), "\n";

El ejemplo anterior mostrará:

    float(1371425814666)
    lunes, 17 de junio de 2013 01:36:54 Hora de verano de Europa central

# IntlCalendar::getRepeatedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getRepeatedWallTimeOption — Obtiene el comportamiento para la gestión de las horas murales repetidas

### Descripción

Estilo orientado a objetos

public function IntlCalendar::getRepeatedWallTimeOption(): int

Estilo procedimental

function intlcal_get_repeated_wall_time_option(IntlCalendar `$calendar`): int

Devuelve la estrategia actual para la gestión de las horas murales repetidas cuando el reloj se atrasa durante las transiciones de fin de hora de verano. El valor por omisión es `IntlCalendar::WALLTIME_LAST`.

Esta función requiere ICU 4.9 o más reciente.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.

### Valores devueltos

Una de las constantes `IntlCalendar::WALLTIME_FIRST` o `IntlCalendar::WALLTIME_LAST`.

### Ejemplos

Ejemplo #1 IntlCalendar::getRepeatedWallTimeOption()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');
    ini_set('intl.error_level', E_WARNING);

    //El 27 de Octubre a las 0200, la hora retrocederá de GMT+01 a GMT+00
    $cal = new IntlGregorianCalendar(2013, 9 /* October */, 27, 1, 30);

    var_dump($cal->getRepeatedWalltimeOption()); // 0 WALLTIME_LAST

    $formatter = IntlDateFormatter::create(
        NULL,
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'UTC'
    );
    var_dump($formatter->format($cal->getTime() / 1000.));

    $cal->setRepeatedWalltimeOption(IntlCalendar::WALLTIME_FIRST);
    var_dump($cal->getRepeatedWalltimeOption()); // 1 WALLTIME_FIRST
    $cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1);

    var_dump($formatter->format($cal->getTime() / 1000.));

El ejemplo anterior mostrará:

    int(0)
    string(42) "Sunday, October 27, 2013 at 1:30:00 AM GMT"
    int(1)
    string(43) "Sunday, October 27, 2013 at 12:30:00 AM GMT"

### Ver también

- IntlCalendar::getSkippedWallTimeOption() - Obtiene el comportamiento para la gestión de las horas murales omitidas
- IntlCalendar::setSkippedWallTimeOption() - Define el comportamiento para la gestión de las horas murales saltadas durante las transiciones de desplazamiento horario positivo
- IntlCalendar::setRepeatedWallTimeOption() - Define el comportamiento para la gestión de las horas murales repetidas durante las transiciones de cambio de huso horario negativo

# IntlCalendar::getSkippedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getSkippedWallTimeOption — Obtiene el comportamiento para la gestión de las horas murales omitidas

### Descripción

Estilo orientado a objetos

public function IntlCalendar::getSkippedWallTimeOption(): int

Estilo procedimental

function intlcal_get_skipped_wall_time_option(IntlCalendar `$calendar`): int

Devuelve la estrategia actual para la gestión de las horas murales omitidas cuando el reloj se adelanta durante las transiciones de inicio de hora de verano. El valor por omisión es `IntlCalendar::WALLTIME_LAST`.

El calendario debe ser tolerante para que esta opción tenga efecto, de lo contrario intentar definir una hora inexistente provocará una error.

Esta función requiere ICU 4.9 o más reciente.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.

### Valores devueltos

Una de las constantes `IntlCalendar::WALLTIME_FIRST`, `IntlCalendar::WALLTIME_LAST` o `IntlCalendar::WALLTIME_NEXT_VALID`.

### Ejemplos

Ejemplo #1 IntlCalendar::getSkippedWallTimeOption()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');
    ini_set('intl.error_level', E_WARNING);

    //El 31 de Marzo a las 0100, el reloj avanzará una hora de GMT+00 a GMT+01
    $cal = new IntlGregorianCalendar(2013, 2 /* March */, 31, 1, 30);

    var_dump(
        $cal->isLenient(),               // true
        $cal->getSkippedWalltimeOption() // 0 WALLTIME_LAST
    );

    $formatter = IntlDateFormatter::create(
        NULL,
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'UTC'
    );
    var_dump($formatter->format($cal->getTime() / 1000));

    $cal->setSkippedWallTimeOption(IntlCalendar::WALLTIME_FIRST);
    var_dump($cal->getSkippedWalltimeOption()); // 1 WALLTIME_FIRST
    $cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1);

    var_dump($formatter->format($cal->getTime() / 1000));

    $cal->setSkippedWallTimeOption(IntlCalendar::WALLTIME_NEXT_VALID);
    var_dump($cal->getSkippedWalltimeOption()); // 2 WALLTIME_NEXT_VALID
    $cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1);

    var_dump($formatter->format($cal->getTime() / 1000));

El ejemplo anterior mostrará:

    bool(true)
    int(0)
    string(40) "Sunday, March 31, 2013 at 1:30:00 AM GMT"
    int(1)
    string(41) "Sunday, March 31, 2013 at 12:30:00 AM GMT"
    int(2)
    string(40) "Sunday, March 31, 2013 at 1:00:00 AM GMT"

### Ver también

- IntlCalendar::getRepeatedWallTimeOption() - Obtiene el comportamiento para la gestión de las horas murales repetidas
- IntlCalendar::setSkippedWallTimeOption() - Define el comportamiento para la gestión de las horas murales saltadas durante las transiciones de desplazamiento horario positivo
- IntlCalendar::setRepeatedWallTimeOption() - Define el comportamiento para la gestión de las horas murales repetidas durante las transiciones de cambio de huso horario negativo

# IntlCalendar::getTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getTime — Obtiene el tiempo actualmente representado por el objeto

### Descripción

Estilo orientado a objetos

public function IntlCalendar::getTime(): float|false

Estilo procedimental

function intlcal_get_time(IntlCalendar `$calendar`): float|false

Devuelve el tiempo asociado a este objeto, expresado como número de milisegundos transcurridos desde la época.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.

### Valores devueltos

Un float que representa el número de milisegundos transcurridos desde el tiempo de referencia (1 Ene 1970 00:00:00 UTC), o `false` si ocurre un error

### Ejemplos

Ejemplo #1 IntlCalendar::getTime()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');

    $cal = new IntlGregorianCalendar(2013, 4 /* May */, 1, 0, 0, 0);
    $time = $cal->getTime();
    var_dump($time, $time / 1000 == strtotime('2013-05-01 00:00:00')); //true

El ejemplo anterior mostrará:

    float(1367362800000)
    bool(true)

### Ver también

- IntlCalendar::getNow() - Obtiene el número que representa la fecha actual

# IntlCalendar::getTimeZone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getTimeZone — Recupera la zona horaria del objeto

### Descripción

Estilo orientado a objetos

public function IntlCalendar::getTimeZone(): IntlTimeZone|false

Estilo procedimental

function intlcal_get_time_zone(IntlCalendar `$calendar`): IntlTimeZone|false

Devuelve el objeto IntlTimeZone asociado con este calendario.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.

### Valores devueltos

Un objeto IntlTimeZone correspondiente al utilizado internamente por este objeto. Devuelve `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con IntlCalendar::getTimeZone()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');

    $cal = IntlCalendar::createInstance();
    print_r($cal->getTimeZone());

    $cal->setTimeZone('UTC');
    print_r($cal->getTimeZone());

    $cal = IntlCalendar::fromDateTime('2012-01-01 00:00:00 GMT+03:33');
    print_r($cal->getTimeZone());

El ejemplo anterior mostrará:

    IntlTimeZone Object
    (
        [valid] => 1
        [id] => Europe/Lisbon
        [rawOffset] => 0
        [currentOffset] => 3600000
    )
    IntlTimeZone Object
    (
        [valid] => 1
        [id] => UTC
        [rawOffset] => 0
        [currentOffset] => 0
    )
    IntlTimeZone Object
    (
        [valid] => 1
        [id] => GMT+03:33
        [rawOffset] => 12780000
        [currentOffset] => 12780000
    )

### Ver también

- IntlCalendar::setTimeZone() - Define el huso horario utilizado por este calendario
- IntlCalendar::createInstance() - Crea un nuevo objeto IntlCalendar
- IntlGregorianCalendar::__construct() - Crear la clase del calendario gregoriano

# IntlCalendar::getType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getType — Obtiene el tipo de calendario

### Descripción

Estilo orientado a objetos

public function IntlCalendar::getType(): string

Estilo procedimental

function intlcal_get_type(IntlCalendar `$calendar`): string

Una cadena de caracteres que describe el tipo de este calendario. Esta cadena será una de las valores válidos de la palabra clave `'calendar'` del calendario.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.

### Valores devueltos

Una cadena de caracteres string que representa el tipo de calendario, por ejemplo, `'gregorian'`, `'islamic'`, etc.

### Ejemplos

Ejemplo #1 Ejemplo con IntlCalendar::getType()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');

    $cal = IntlCalendar::createInstance(NULL, '@calendar=ethiopic-amete-alem');
    var_dump($cal->getType());

    $cal = new IntlGregorianCalendar();
    var_dump($cal->getType());

El ejemplo anterior mostrará:

    string(19) "ethiopic-amete-alem"
    string(9) "gregorian"

# IntlCalendar::getWeekendTransition

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getWeekendTransition — Obtiene la hora del día en la que comienza o termina el fin de semana

### Descripción

Estilo orientado a objetos

public function IntlCalendar::getWeekendTransition(int `$dayOfWeek`): int|false

Estilo procedimental

function intlcal_get_weekend_transition(IntlCalendar `$calendar`, int `$dayOfWeek`): int|false

Devuelve el número de milisegundos transcurridos desde la medianoche en la hora en la que comienza o termina el fin de semana.

Esto es aplicable únicamente para los días de la semana para los cuales IntlCalendar::getDayOfWeekType() devuelve `IntlCalendar::DOW_TYPE_WEEKEND_OFFSET` o `IntlCalendar::DOW_TYPE_WEEKEND_CEASE`. Llamar a esta función para otros días de la semana es una condición de error.

Esta función requiere ICU 4.4 o superior.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`dayOfWeek`

  Una de las constantes `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, …, `IntlCalendar::DOW_SATURDAY`.

### Valores devueltos

El número de milisegundos transcurridos desde la medianoche en la hora en la que el fin de semana comienza o termina o `false` si ocurre un error.

### Ejemplos

Ver un ejemplo en IntlCalendar::getDayOfWeekType().

# IntlCalendar::inDaylightTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::inDaylightTime — Indica si el objeto está en horario de verano

### Descripción

Estilo orientado a objetos

public function IntlCalendar::inDaylightTime(): bool

Estilo procedimental

function intlcal_in_daylight_time(IntlCalendar `$calendar`): bool

Si, para el instante representado por este objeto y para la zona horaria de este objeto, el horario de verano está en vigor.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.

### Valores devueltos

Devuelve `true` si la fecha está en horario de verano, de lo contrario `false`.

En caso de fallo, también se devuelve `false`. Para detectar condiciones de error, utilice intl_get_error_code(), o configure Intl para lanzar excepciones.

### Ejemplos

Ejemplo #1 IntlCalendar::inDaylightTime()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_PT');

    $cal = new IntlGregorianCalendar(2013, 6 /* July */, 1, 4, 56, 31);
    var_dump($cal->inDaylightTime()); // true
    $cal->set(IntlCalendar::FIELD_MONTH, 11 /* December */);
    var_dump($cal->inDaylightTime()); // false

    //Fin del horario de verano el 2013-10-27 a 0200 (retraso de una hora)
    $cal = new IntlGregorianCalendar(2013, 9 /* October */, 27, 1, 30, 0);

    var_dump($cal->inDaylightTime()); // false (default WALLTIME_LAST)

    $cal->setRepeatedWallTimeOption(IntlCalendar::WALLTIME_FIRST);
    $cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1); // fuerza el recálculo de la hora
    var_dump($cal->inDaylightTime()); // true

# IntlCalendar::isEquivalentTo

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isEquivalentTo — Indica si otro calendario es equivalente, pero para otro momento

### Descripción

Estilo orientado a objetos

public function IntlCalendar::isEquivalentTo(IntlCalendar `$other`): bool

Estilo procedimental

function intlcal_is_equivalent_to(IntlCalendar `$calendar`, IntlCalendar `$other`): bool

Devuelve si este objeto y el proporcionado son equivalentes para todos los usos, excepto por el momento que han definido. Las zonas horarias no necesitan coincidir, siempre que no resulte ningún cambio de comportamiento. Esto incluye la zona horaria, si el modo laxista está definido, los parámetros de tiempo de pared repetido y saltado, los días de la semana donde comienza y termina el fin de semana y las horas donde ocurren tales transiciones. Esto puede incluir también otros parámetros específicos del calendario, como el instante de transición gregoriano/juliano.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`other`

  El otro calendario con respecto al cual se debe realizar la comparación.

### Valores devueltos

Suponiendo que no hay errores de argumento, devuelve `true` si los calendarios son equivalentes, excepto quizás por su momento definido.

### Ejemplos

Ejemplo #1 IntlCalendar::isEquivalentTo()

    <?php
    $cal1 = IntlCalendar::createInstance('Europe/Lisbon', 'pt_PT');
    $cal2 = IntlCalendar::createInstance('Europe/Lisbon', 'es_ES');
    $cal2->clear();

    var_dump($cal1->isEquivalentTo($cal2)); // true

    $cal3 = IntlCalendar::createInstance('Europe/Lisbon', 'en_US');
    var_dump($cal1->isEquivalentTo($cal3)); // false
    var_dump($cal1->getFirstDayOfWeek(),    // 2 (Monday)
    $cal3->getFirstDayOfWeek());            // 1 (Sunday)

El ejemplo anterior mostrará:

    bool(true)
    bool(false)
    int(2)
    int(1)

### Ver también

- IntlCalendar::equals() - Verifica si dos objetos IntlCalendar son iguales

# IntlCalendar::isLenient

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isLenient — Indica si la interpretación de la fecha/hora está en modo tolerante

### Descripción

Estilo orientado a objetos

public function IntlCalendar::isLenient(): bool

Estilo procedimental

function intlcal_is_lenient(IntlCalendar `$calendar`): bool

Devuelve si la interpretación de la fecha/hora está en modo tolerante (el modo por omisión). Si es así, ciertos valores fuera de límites para los campos serán aceptados en lugar de generar un error.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.

### Valores devueltos

Un bool que representa si el calendario está en modo tolerante.

### Ejemplos

Ejemplo #1 IntlCalendar::isLenient()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_PT');
    ini_set('intl.use_exceptions', '1');

    $cal = new IntlGregorianCalendar(2013, 6 /* July */, 1);
    var_dump(IntlDateFormatter::formatObject($cal), // 01/07/2013, 00:00:00
    $cal->isLenient()); // true

    $cal->set(IntlCalendar::FIELD_DAY_OF_MONTH, 33);
    var_dump(IntlDateFormatter::formatObject($cal)); // 02/08/2013, 00:00:00

    $cal->setLenient(false);
    var_dump($cal->isLenient()); // false
    $cal->set(IntlCalendar::FIELD_DAY_OF_MONTH, 33);
    var_dump(IntlDateFormatter::formatObject($cal)); // error

El ejemplo anterior mostrará:

    string(20) "01/07/2013, 00:00:00"
    bool(true)
    string(20) "02/08/2013, 00:00:00"
    bool(false)

    Fatal error: Uncaught exception 'IntlException' with message 'datefmt_format_object: error obtaining instant from IntlCalendar' in /home/foobar/example.php:16
    Stack trace:
    #0 /home/foobar/example.php(16): IntlDateFormatter::formatObject(Object(IntlGregorianCalendar))
    #1 {main}
      thrown in /home/foobar/example.php on line 16

# IntlCalendar::isSet

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isSet — Indica si un campo está definido

### Descripción

Estilo orientado a objetos

public function IntlCalendar::isSet(int `$field`): bool

Estilo procedimental

function intlcal_is_set(IntlCalendar `$calendar`, int `$field`): bool

Indica si un campo está definido (en oposición a borrado). Los campos definidos tienen prioridad sobre los campos no definidos y sus valores por defecto durante el cálculo de la fecha/hora. Los campos definidos más tarde tienen prioridad sobre los campos definidos antes.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`field`

  Una de las constantes del campo fecha/hora de IntlCalendar. Son valores de tipo integer entre `0` y `IntlCalendar::FIELD_COUNT`.

### Valores devueltos

Suponiendo que no hay errores de argumentos, devuelve `true` si el campo está definido.

### Ejemplos

Ver un ejemplo en IntlCalendar::clear().

### Ver también

- IntlCalendar::clear() - Vacía un campo o todos los campos
- IntlCalendar::set() - Define un campo de tiempo o varios campos comunes a la vez

# IntlCalendar::isWeekend

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isWeekend — Indica si una fecha/hora es un fin de semana

### Descripción

Estilo orientado a objetos

public function IntlCalendar::isWeekend(?float `$timestamp` = `null`): bool

Estilo procedimental

function intlcal_is_weekend(IntlCalendar `$calendar`, ?float `$timestamp` = `null`): bool

Devuelve si la hora actual del objeto o el timestamp proporcionado ocurre durante un fin de semana en el sistema de calendario de este objeto.

Esta función requiere ICU 4.4 o más reciente.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`timestamp`

  Un timestamp opcional que representa el número de milisegundos transcurridos desde el epoch, excluyendo los segundos intercalares. Si es `null`, se utiliza el tiempo actual de este objeto en su lugar.

### Valores devueltos

Un bool que indica si el tiempo dado o el de este objeto ocurre durante un fin de semana.

En caso de fallo, también se devuelve `false`. Para detectar condiciones de error, utilice intl_get_error_code(), o configure Intl para lanzar excepciones.

### Ejemplos

Ejemplo #1 IntlCalendar::isWeekend()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');

    $cal = new IntlGregorianCalendar(NULL, 'en_US');
    $cal->set(2013, 6 /* July */, 7); // un domingo

    var_dump($cal->isWeekend()); // true
    var_dump($cal->isWeekend(strtotime('2013-07-01 00:00:00'))); // false, Monday

    $cal = new IntlGregorianCalendar(NULL, 'ar_SA');
    $cal->set(2013, 6 /* July */, 7); // un domingo
    var_dump($cal->isWeekend()); // false, domingo no es fin de semana en este calendario

### Ver también

- IntlCalendar::getDayOfWeekType() - Indica si un día es un día de la semana, un fin de semana o un día de transición entre ambos
- IntlCalendar::getWeekendTransition() - Obtiene la hora del día en la que comienza o termina el fin de semana

# IntlCalendar::roll

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::roll — Añade un valor a un campo sin reportarlo a los campos más significativos

### Descripción

Estilo orientado a objetos

public function IntlCalendar::roll(int `$field`, int|bool `$value`): bool

Estilo procedimental

function intlcal_roll(IntlCalendar `$calendar`, int `$field`, int|bool `$value`): bool

Añade un valor (signado) a un campo. La diferencia con IntlCalendar::add() es que cuando el valor del campo desborda, no se reporta a los campos más significativos.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`field`

  Una de las constantes del campo fecha/hora de IntlCalendar. Son valores de tipo integer entre `0` y `IntlCalendar::FIELD_COUNT`.

`value`

  El valor (signado) a añadir al campo, `true` para ir hacia arriba (añadiendo `1`), o `false` para ir hacia abajo (restando `1`).

### Valores devueltos

Devuelve `true` en caso de éxito o `false` en caso de fallo.

### Ejemplos

Ejemplo #1 IntlCalendar::roll()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_PT');

    $cal = new IntlGregorianCalendar(2013, 5 /* June */, 30);

    $cal->add(IntlCalendar::FIELD_DAY_OF_MONTH, 1);
    var_dump(IntlDateFormatter::formatObject($cal)); // "01/07/2013, 00:00:00"

    $cal->set(2013, 5 /* June */, 30);
    $cal->roll(IntlCalendar::FIELD_DAY_OF_MONTH, true); // ir hacia arriba, como rodar +1
    var_dump(IntlDateFormatter::formatObject($cal)); // "01/06/2013, 00:00:00"

El ejemplo anterior mostrará:

    string(20) "01/07/2013, 00:00:00"
    string(20) "01/06/2013, 00:00:00"

### Ver también

- IntlCalendar::add() - Añade una duración (con signo) a un campo
- IntlCalendar::set() - Define un campo de tiempo o varios campos comunes a la vez

# IntlCalendar::set

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::set — Define un campo de tiempo o varios campos comunes a la vez

### Descripción

Estilo orientado a objetos

public function IntlCalendar::set(int `$field`, int `$value`): true
public function IntlCalendar::set(
int `$year`,
int `$month`,
int `$dayOfMonth` = NULL,
int `$hour` = NULL,
int `$minute` = NULL,
int `$second` = NULL
): true

Estilo procedimental

function intlcal_set(IntlCalendar `$cal`, int `$field`, int `$value`): true
function intlcal_set(
IntlCalendar `$cal`,
int `$year`,
int `$month`,
int `$dayOfMonth` = NULL,
int `$hour` = NULL,
int `$minute` = NULL,
int `$second` = NULL
): bool

Define ya sea un campo específico con el valor dado, o define varios campos comunes a la vez. El rango de valores aceptables depende de si el calendario utiliza el modo tolerante.

Para los campos que entran en conflicto, los campos definidos más tarde tienen prioridad.

Este método no puede ser llamado con exactamente cuatro argumentos.

### Parámetros

`cal`
  Una instancia de IntlCalendar.
`field`

  Una de las constantes del campo fecha/hora de IntlCalendar. Son valores de tipo integer entre `0` y `IntlCalendar::FIELD_COUNT`.

`value`

  El nuevo valor del campo dado.

`year`

  El nuevo valor para `IntlCalendar::FIELD_YEAR`.

`month`

  El nuevo valor para `IntlCalendar::FIELD_MONTH`. La secuencia de los meses comienza en cero, es decir que enero es representado por 0, febrero por 1, ..., diciembre por 11 y Undecember (si el calendario lo soporta) por 12.

`dayOfMonth`

  El nuevo valor para `IntlCalendar::FIELD_DAY_OF_MONTH`.

`hour`

  El nuevo valor para `IntlCalendar::FIELD_HOUR_OF_DAY`.

`minute`

  El nuevo valor para `IntlCalendar::FIELD_MINUTE`.

`second`

  El nuevo valor para `IntlCalendar::FIELD_SECOND`.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.2.0 | El tipo de retorno es ahora `true`, anteriormente era bool.
8.4.0 | Esto ha sido deprecado en favor de los métodos IntlCalendar::setDate() y IntlCalendar::setDateTime().

### Ejemplos

Ejemplo #1 IntlCalendar::set()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_PT');

    //Las últimas llamadas tienen prioridad
    $cal = new IntlGregorianCalendar(2013, 6 /* July */, 1);
    $cal->set(IntlCalendar::FIELD_YEAR, 2012);
    $cal->set(IntlCalendar::FIELD_EXTENDED_YEAR, 2011);
    var_dump(IntlDateFormatter::formatObject($cal));

    $cal = new IntlGregorianCalendar(2013, 6 /* July */, 1);
    $cal->set(IntlCalendar::FIELD_YEAR, 2012);
    $cal->set(IntlCalendar::FIELD_EXTENDED_YEAR, 2011);
    //el tiempo no ha sido recalculado. Si borramos el año extendido,
    //el año definido antes será utilizado
    $cal->clear(IntlCalendar::FIELD_EXTENDED_YEAR);
    var_dump(IntlDateFormatter::formatObject($cal));

El ejemplo anterior mostrará:

    string(20) "01/07/2011, 00:00:00"
    string(20) "01/07/2012, 00:00:00"

### Ver también

- IntlCalendar::get() - Recupera el valor de una propiedad
- IntlCalendar::add() - Añade una duración (con signo) a un campo
- IntlCalendar::roll() - Añade un valor a un campo sin reportarlo a los campos más significativos

# IntlCalendar::setDate

(PHP 8 >= 8.3.0)

IntlCalendar::setDate — Establece un campo de fecha

### Descripción

public function IntlCalendar::setDate(int `$year`, int `$month`, int `$dayOfMonth`): void

Establece un campo de fecha al valor dado.

### Parámetros

`year`

  El nuevo valor para `IntlCalendar::FIELD_YEAR`.

`month`

  El nuevo valor para `IntlCalendar::FIELD_MONTH`. La secuencia de meses comienza en cero, es decir, que enero está representado por 0, febrero por 1, ..., diciembre por 11 y Undecember (si el calendario lo soporta) por 12.

`dayOfMonth`

  El nuevo valor para `IntlCalendar::FIELD_DAY_OF_MONTH`.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo de IntlCalendar::setDate()

    <?php
    $intlCal = IntlCalendar::createInstance('UTC');

    $intlCal->setDate(2012, 1, 29);
    ?>

# IntlCalendar::setDateTime

(PHP 8 >= 8.3.0)

IntlCalendar::setDateTime — Establece un campo de fecha y hora

### Descripción

public function IntlCalendar::setDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): void

Establece un campo de fecha y hora al valor dado.

### Parámetros

`year`

  El nuevo valor para `IntlCalendar::FIELD_YEAR`.

`month`

  El nuevo valor para `IntlCalendar::FIELD_MONTH`. La secuencia de los meses comienza en cero, es decir, enero está representado por 0, febrero por 1, ..., diciembre por 11 y Undecember (si el calendario lo soporta) por 12.

`dayOfMonth`

  El nuevo valor para `IntlCalendar::FIELD_DAY_OF_MONTH`.

`hour`

  El nuevo valor para `IntlCalendar::FIELD_HOUR_OF_DAY`.

`minute`

  El nuevo valor para `IntlCalendar::FIELD_MINUTE`.

`second`

  El nuevo valor para `IntlCalendar::FIELD_SECOND`.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo de IntlCalendar::setDateTime()

    <?php
    $intlCal = IntlCalendar::createInstance('UTC');

    $intlCal->setDateTime(2012, 1, 29, 23, 58);
    ?>

# IntlCalendar::setFirstDayOfWeek

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setFirstDayOfWeek — Define el día de inicio de la semana

### Descripción

Estilo orientado a objetos

public function IntlCalendar::setFirstDayOfWeek(int `$dayOfWeek`): true

Estilo procedimental

function intlcal_set_first_day_of_week(IntlCalendar `$calendar`, int `$dayOfWeek`): true

Define el día de inicio de la semana. Esto afecta al comportamiento de los campos que dependen del concepto de inicio y fin de semana, como `IntlCalendar::FIELD_WEEK_OF_YEAR` y `IntlCalendar::FIELD_YEAR_WOY`.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`dayOfWeek`

  Una constante entre `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, …, `IntlCalendar::DOW_SATURDAY`.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.2.0 | El tipo de retorno es ahora `true`, anteriormente era bool.

### Ejemplos

Ejemplo #1 Ejemplo con IntlCalendar::setFirstDayOfWeek()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'es_ES');

    $cal = IntlCalendar::createInstance();
    $cal->set(2013, 5 /* Junio */, 30); // Un domingo

    var_dump($cal->getFirstDayOfWeek()); // 2 (Lunes)

    echo IntlDateFormatter::formatObject($cal, <<<EOD
    'día local de la semana : 'cc'
    semana del mes           : 'W'
    semana del año           : 'ww
    EOD
    ), "\n";

    $cal->setFirstDayOfWeek(IntlCalendar::DOW_SUNDAY);

    echo IntlDateFormatter::formatObject($cal, <<<EOD
    'día local de la semana : 'cc'
    semana del mes           : 'W'
    semana del año           : 'ww
    EOD
    ), "\n";

El ejemplo anterior mostrará:

    int(2)
    día local de la semana  : 7
    semana del mes           : 4
    semana del año           : 26
    día local de la semana  : 1
    semana del mes           : 5
    semana del año           : 27

# IntlCalendar::setLenient

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setLenient — Define si la interpretación de la fecha/hora es tolerante

### Descripción

Estilo orientado a objetos

public function IntlCalendar::setLenient(bool `$lenient`): true

Estilo procedimental

function intlcal_set_lenient(IntlCalendar `$calendar`, bool `$lenient`): true

Define si la interpretación de la fecha/hora es tolerante. En tal modo, ciertos valores fuera de límites para algunos campos son aceptados, el comportamiento siendo similar a aquel de IntlCalendar::add() (es decir, el valor rebobina, reportándose en campos más significativos cada vez). Si el modo tolerante es desactivado, entonces tales valores generarán un error.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`lenient`

  Utilizar `true` para activar el modo tolerante; `false` en caso contrario.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.2.0 | El tipo de retorno es ahora `true`, anteriormente era bool.

### Ejemplos

Ver un ejemplo en IntlCalendar::isLenient().

# IntlCalendar::setMinimalDaysInFirstWeek

(PHP 5 >= 5.5.1, PHP 7, PHP 8)

IntlCalendar::setMinimalDaysInFirstWeek — Define el número mínimo de días que la primera semana de un año o mes puede tener

### Descripción

Estilo orientado a objetos

public function IntlCalendar::setMinimalDaysInFirstWeek(int `$days`): true

Estilo procedimental

function intlcal_set_minimal_days_in_first_week(IntlCalendar `$calendar`, int `$days`): true

Define el número mínimo de días que la primera semana de un año o mes puede tener en el nuevo año o mes. Por ejemplo, en el calendario gregoriano, si este valor es 1, entonces la primera semana del año incluirá necesariamente el 1 de enero, mientras que si este valor es 7, entonces la semana con el 1 de enero será la primera semana del año únicamente si el día de la semana para el 1 de enero corresponde al día de la semana devuelto por IntlCalendar::getFirstDayOfWeek(); de lo contrario, será la última semana del año anterior.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`days`

  El número de días mínimo a definir.

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

ValueError si `days` está fuera de rango (menos que `1` o más que `7`).

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Se lanza una ValueError ante una entrada inválida. Anteriormente, se devolvía `false`.

# IntlCalendar::setRepeatedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setRepeatedWallTimeOption — Define el comportamiento para la gestión de las horas murales repetidas durante las transiciones de cambio de huso horario negativo

### Descripción

Estilo orientado a objetos

public function IntlCalendar::setRepeatedWallTimeOption(int `$option`): true

Estilo procedimental

function intlcal_set_repeated_wall_time_option(IntlCalendar `$calendar`, int `$option`): true

Define la estrategia actual para la gestión de las horas murales repetidas cada vez que el reloj se retrasa durante las transiciones de fin del horario de verano. El valor por omisión es `IntlCalendar::WALLTIME_LAST` (tomar el instante post-DST). El otro valor posible es `IntlCalendar::WALLTIME_FIRST` (tomar el instante que ocurre durante el horario de verano).

Esta función requiere ICU 4.9 o superior.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`option`

  Una de las constantes `IntlCalendar::WALLTIME_FIRST` o `IntlCalendar::WALLTIME_LAST`.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.2.0 | El tipo de retorno es ahora `true`, anteriormente era bool.

### Ejemplos

Ver un ejemplo en IntlCalendar::getRepeatedWallTimeOption().

### Ver también

- intlCalendar::getRepeatedWallTimeOption() - Obtiene el comportamiento para la gestión de las horas murales repetidas
- intlCalendar::setSkippedWallTimeOption() - Define el comportamiento para la gestión de las horas murales saltadas durante las transiciones de desplazamiento horario positivo
- intlCalendar::getSkippedWallTimeOption() - Obtiene el comportamiento para la gestión de las horas murales omitidas

# IntlCalendar::setSkippedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setSkippedWallTimeOption — Define el comportamiento para la gestión de las horas murales saltadas durante las transiciones de desplazamiento horario positivo

### Descripción

Estilo orientado a objetos

public function IntlCalendar::setSkippedWallTimeOption(int `$option`): true

Estilo procedimental

function intlcal_set_skipped_wall_time_option(IntlCalendar `$calendar`, int `$option`): true

Define la estrategia actual para la gestión de las horas murales saltadas cada vez que el reloj se adelanta durante las transiciones de inicio del horario de verano. El valor por omisión es `IntlCalendar::WALLTIME_LAST` (tomar el instante post-DST). Los otros valores posibles son `IntlCalendar::WALLTIME_FIRST` (tomar el instante que ocurre durante el horario de verano) y `IntlCalendar::WALLTIME_NEXT_VALID` (tomar el instante cuando comienza el horario de verano).

Esto afecta únicamente al instante representado por el calendario (tal como se informa por IntlCalendar::getTime()), los valores de los campos no serán sobrescritos en consecuencia.

El calendario debe ser tolerante para que esta opción tenga efecto, de lo contrario intentar definir un tiempo inexistente provocará una error.

Esta función requiere ICU 4.9 o superior.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`option`

  Una de las constantes `IntlCalendar::WALLTIME_FIRST`, `IntlCalendar::WALLTIME_LAST` o `IntlCalendar::WALLTIME_NEXT_VALID`.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.2.0 | El tipo de retorno es ahora `true`, anteriormente era bool.

### Ejemplos

Ver un ejemplo en IntlCalendar::getSkippedWallTimeOption().

### Ver también

- intlCalendar::getSkippedWallTimeOption() - Obtiene el comportamiento para la gestión de las horas murales omitidas
- intlCalendar::setRepeatedWallTimeOption() - Define el comportamiento para la gestión de las horas murales repetidas durante las transiciones de cambio de huso horario negativo
- intlCalendar::getRepeatedWallTimeOption() - Obtiene el comportamiento para la gestión de las horas murales repetidas

# IntlCalendar::setTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setTime — Define el tiempo del calendario en milisegundos desde la época

### Descripción

Estilo orientado a objetos

public function IntlCalendar::setTime(float `$timestamp`): bool

Estilo procedimental

function intlcal_set_time(IntlCalendar `$calendar`, float `$timestamp`): bool

Define el instante representado por este objeto. El instante se representa mediante un float cuyo valor es un número entero de milisegundos desde la época Unix (1 de enero de 1970 00:00:00.000 UTC), ignorando el último segundo. Todos los valores de los campos serán recalculados en consecuencia.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`timestamp`

  Un instante, representado por el número de milisegundos entre el instante y la época Unix, ignorando el último segundo.

### Valores devueltos

Devuelve `true` en caso de éxito, `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con IntlCalendar::setTime()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'fr_FR');

    $cal = new IntlGregorianCalendar(2013, 5 /* May */, 1, 12, 0, 0);

    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";

    /* En Europe/Lisbon, el 2013-10-27 a las 0200, el reloj pierde una hora
       y la zona horaria pasa de UTC+01 a UTC+00 */

    $cal->setTime(strtotime('2013-10-27 00:30:00 UTC') * 1000.);

    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";

    $cal->setTime(strtotime('2013-10-27 01:30:00 UTC') * 1000.);

    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";

El ejemplo anterior mostrará:

    sábado 1 de junio de 2013 12:00:00 hora de verano de Europa Occidental
    domingo 27 de octubre de 2013 01:30:00 hora de verano de Europa Occidental
    domingo 27 de octubre de 2013 01:30:00 hora estándar de Europa Occidental

# IntlCalendar::setTimeZone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setTimeZone — Define el huso horario utilizado por este calendario

### Descripción

Estilo orientado a objetos

public function IntlCalendar::setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

Estilo procedimental

function intlcal_set_time_zone(IntlCalendar `$calendar`, IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

Define un nuevo huso horario para este calendario. El momento representado por este objeto es preservado a expensas de los valores de los campos.

### Parámetros

`calendar`
  Una instancia de IntlCalendar.
`timezone`

  El nuevo huso horario a utilizar por este calendario. Puede ser especificado de la siguiente manera:

  - `null`, en cuyo caso se usará la zona horaria predeterminada, tal como está especificada en el ajuste ini date.timezone o a través de la función date_default_timezone_set() y como es devuelto por date_default_timezone_get().

  - Un IntlTimeZone, que se usará directamente.

  - Un DateTimeZone. Su identificador será extraido y se creará un objeto de zona horaria de ICU; la zona horaria será proporcionada por la base de datos de ICU, no por la de PHP.

  - Un string, que debería ser un identificador de zona horaria de ICU válido. Véase IntlTimeZone::createTimeZoneIDEnumeration(). Los índices puros como `"GMT+08:30"` también se aceptan.

### Valores devueltos

Retorna `true` en caso de éxito, `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con IntlCalendar::setTimeZone()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'es_ES');

    $cal = new IntlGregorianCalendar(2013, 5 /* May */, 1, 12, 0, 0);

    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";
    echo "(instant {$cal->getTime()})\n";

    $cal->setTimeZone(IntlTimeZone::getGMT());
    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";
    echo "(instant {$cal->getTime()})\n";

    $cal->setTimeZone('GMT+03:33');
    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";
    echo "(instant {$cal->getTime()})\n";

El ejemplo anterior mostrará:

    sábado, 1 de junio de 2013 12:00:00 Hora de verano de Europa occidental
    (instant 1370084400000)
    sábado, 1 de junio de 2013 11:00:00 GMT
    (instant 1370084400000)
    sábado, 1 de junio de 2013 14:33:00 GMT+03:33
    (instant 1370084400000)

# IntlCalendar::toDateTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a2)

IntlCalendar::toDateTime — Convierte un objeto IntlCalendar en un objeto DateTime

### Descripción

Estilo orientado a objetos

public function IntlCalendar::toDateTime(): DateTime|false

Estilo procedimental

function intlcal_to_date_time(IntlCalendar `$calendar`): DateTime|false

Crea un objeto DateTime que representa el mismo instante (con una precisión de segundo) y con un huso horario similar al objeto inicial (la única diferencia es que el huso horario del objeto DateTime será comprendido por PHP, mientras que el huso horario del objeto IntlCalendar será comprendido por ICU).

### Parámetros

`calendar`
  Una instancia de IntlCalendar.

### Valores devueltos

Un objeto DateTime con el mismo huso horario que el objeto original (utilizando la base de datos de PHP en lugar de la de ICU) y que representa el mismo momento, salvo por la precisión (precisión de segundo en lugar de milisegundo). Devuelve `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con IntlCalendar::toDateTime()

    <?php
    ini_set('date.timezone', 'UTC');
    ini_set('intl.default_locale', 'pt_PT');

    $cal = IntlCalendar::createInstance('Europe/Lisbon'); //tiempo actual

    $dt = $cal->toDateTime();
    print_r($dt);

El ejemplo anterior mostrará:

    DateTime Object
    (
        [date] => 2013-07-02 00:29:13
        [timezone_type] => 3
        [timezone] => Europe/Lisbon
    )

### Ver también

- IntlCalendar::fromDateTime() - Crea un IntlCalendar a partir de un objeto DateTime o string
- IntlCalendar::getTime() - Obtiene el tiempo actualmente representado por el objeto
- IntlCalendar::createInstance() - Crea un nuevo objeto IntlCalendar
- DateTime::__construct() - Devuelve un nuevo objeto DateTime

## Tabla de contenidos

- IntlCalendar::add — Añade una duración (con signo) a un campo
- IntlCalendar::after — Verifica si el objeto tiempo actual está en el futuro respecto al objeto tiempo pasado
- IntlCalendar::before — Verifica si el objeto tiempo está en el pasado en relación con el objeto proporcionado
- IntlCalendar::clear — Vacía un campo o todos los campos
- IntlCalendar::__construct — Constructor privado para la desactivación de la instanciación
- IntlCalendar::createInstance — Crea un nuevo objeto IntlCalendar
- IntlCalendar::equals — Verifica si dos objetos IntlCalendar son iguales
- IntlCalendar::fieldDifference — Calcula la diferencia entre el tiempo dado y el tiempo del objeto
- IntlCalendar::fromDateTime — Crea un IntlCalendar a partir de un objeto DateTime o string
- IntlCalendar::get — Recupera el valor de una propiedad
- IntlCalendar::getActualMaximum — El valor máximo para un campo, considerando el tiempo actual del objeto
- IntlCalendar::getActualMinimum — El valor mínimo para un campo, considerando el tiempo actual del objeto
- IntlCalendar::getAvailableLocales — Devuelve un array de locales para los cuales hay datos disponibles
- IntlCalendar::getDayOfWeekType — Indica si un día es un día de la semana, un fin de semana o un día de transición entre ambos
- IntlCalendar::getErrorCode — Devuelve el último código de error en el objeto
- IntlCalendar::getErrorMessage — Devuelve el último mensaje de error en el objeto
- IntlCalendar::getFirstDayOfWeek — Devuelve el primer día de la semana para la configuración local del calendario
- IntlCalendar::getGreatestMinimum — Devuelve el valor mínimo local más grande para un campo
- IntlCalendar::getKeywordValuesForLocale — Devuelve el conjunto de valores de palabras clave de configuración regional
- IntlCalendar::getLeastMaximum — Obtiene el mínimo máximo local para un campo
- IntlCalendar::getLocale — Devuelve la configuración local asociada al objeto
- IntlCalendar::getMaximum — Obtiene el valor máximo global para un campo
- IntlCalendar::getMinimalDaysInFirstWeek — Obtiene el número mínimo de días que la primera semana de un año o mes puede tener
- IntlCalendar::getMinimum — Obtiene el valor mínimo global para un campo
- IntlCalendar::getNow — Obtiene el número que representa la fecha actual
- IntlCalendar::getRepeatedWallTimeOption — Obtiene el comportamiento para la gestión de las horas murales repetidas
- IntlCalendar::getSkippedWallTimeOption — Obtiene el comportamiento para la gestión de las horas murales omitidas
- IntlCalendar::getTime — Obtiene el tiempo actualmente representado por el objeto
- IntlCalendar::getTimeZone — Recupera la zona horaria del objeto
- IntlCalendar::getType — Obtiene el tipo de calendario
- IntlCalendar::getWeekendTransition — Obtiene la hora del día en la que comienza o termina el fin de semana
- IntlCalendar::inDaylightTime — Indica si el objeto está en horario de verano
- IntlCalendar::isEquivalentTo — Indica si otro calendario es equivalente, pero para otro momento
- IntlCalendar::isLenient — Indica si la interpretación de la fecha/hora está en modo tolerante
- IntlCalendar::isSet — Indica si un campo está definido
- IntlCalendar::isWeekend — Indica si una fecha/hora es un fin de semana
- IntlCalendar::roll — Añade un valor a un campo sin reportarlo a los campos más significativos
- IntlCalendar::set — Define un campo de tiempo o varios campos comunes a la vez
- IntlCalendar::setDate — Establece un campo de fecha
- IntlCalendar::setDateTime — Establece un campo de fecha y hora
- IntlCalendar::setFirstDayOfWeek — Define el día de inicio de la semana
- IntlCalendar::setLenient — Define si la interpretación de la fecha/hora es tolerante
- IntlCalendar::setMinimalDaysInFirstWeek — Define el número mínimo de días que la primera semana de un año o mes puede tener
- IntlCalendar::setRepeatedWallTimeOption — Define el comportamiento para la gestión de las horas murales repetidas durante las transiciones de cambio de huso horario negativo
- IntlCalendar::setSkippedWallTimeOption — Define el comportamiento para la gestión de las horas murales saltadas durante las transiciones de desplazamiento horario positivo
- IntlCalendar::setTime — Define el tiempo del calendario en milisegundos desde la época
- IntlCalendar::setTimeZone — Define el huso horario utilizado por este calendario
- IntlCalendar::toDateTime — Convierte un objeto IntlCalendar en un objeto DateTime

# La clase IntlGregorianCalendar

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introducción

## Sinopsis de la Clase

class IntlGregorianCalendar extends IntlCalendar {
/* Constantes heredadas */
public const int IntlCalendar::FIELD_ERA;
public const int IntlCalendar::FIELD_YEAR;
public const int IntlCalendar::FIELD_MONTH;
public const int IntlCalendar::FIELD_WEEK_OF_YEAR;
public const int IntlCalendar::FIELD_WEEK_OF_MONTH;
public const int IntlCalendar::FIELD_DATE;
public const int IntlCalendar::FIELD_DAY_OF_YEAR;
public const int IntlCalendar::FIELD_DAY_OF_WEEK;
public const int IntlCalendar::FIELD_DAY_OF_WEEK_IN_MONTH;
public const int IntlCalendar::FIELD_AM_PM;
public const int IntlCalendar::FIELD_HOUR;
public const int IntlCalendar::FIELD_HOUR_OF_DAY;
public const int IntlCalendar::FIELD_MINUTE;
public const int IntlCalendar::FIELD_SECOND;
public const int IntlCalendar::FIELD_MILLISECOND;
public const int IntlCalendar::FIELD_ZONE_OFFSET;
public const int IntlCalendar::FIELD_DST_OFFSET;
public const int IntlCalendar::FIELD_YEAR_WOY;
public const int IntlCalendar::FIELD_DOW_LOCAL;
public const int IntlCalendar::FIELD_EXTENDED_YEAR;
public const int IntlCalendar::FIELD_JULIAN_DAY;
public const int IntlCalendar::FIELD_MILLISECONDS_IN_DAY;
public const int IntlCalendar::FIELD_IS_LEAP_MONTH;
public const int IntlCalendar::FIELD_FIELD_COUNT;
public const int IntlCalendar::FIELD_DAY_OF_MONTH;
public const int IntlCalendar::DOW_SUNDAY;
public const int IntlCalendar::DOW_MONDAY;
public const int IntlCalendar::DOW_TUESDAY;
public const int IntlCalendar::DOW_WEDNESDAY;
public const int IntlCalendar::DOW_THURSDAY;
public const int IntlCalendar::DOW_FRIDAY;
public const int IntlCalendar::DOW_SATURDAY;
public const int IntlCalendar::DOW_TYPE_WEEKDAY;
public const int IntlCalendar::DOW_TYPE_WEEKEND;
public const int IntlCalendar::DOW_TYPE_WEEKEND_OFFSET;
public const int IntlCalendar::DOW_TYPE_WEEKEND_CEASE;
public const int IntlCalendar::WALLTIME_FIRST;
public const int IntlCalendar::WALLTIME_LAST;
public const int IntlCalendar::WALLTIME_NEXT_VALID;
/* Métodos */
public function __construct(IntlTimeZone `$tz` = ?, string `$locale` = ?)
public function __construct(int `$timeZoneOrYear`, int `$localeOrMonth`, int `$dayOfMonth`)
public function __construct(
int `$timeZoneOrYear`,
int `$localeOrMonth`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
int `$second` = ?
)
public static function createFromDate(int `$year`, int `$month`, int `$dayOfMonth`): static
public static function createFromDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): static
public function getGregorianChange(): float
public function isLeapYear(int `$year`): bool
public function setGregorianChange(float `$timestamp`): bool
/* Métodos heredados */
public function IntlCalendar::add(int `$field`, int `$value`): bool
public function IntlCalendar::after(IntlCalendar `$other`): bool
public function IntlCalendar::before(IntlCalendar `$other`): bool
public function IntlCalendar::clear(?int `$field` = `null`): true
public static function IntlCalendar::createInstance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar
public function IntlCalendar::equals(IntlCalendar `$other`): bool
public function IntlCalendar::fieldDifference(float `$timestamp`, int `$field`): int|false
public static function IntlCalendar::fromDateTime(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar
public function IntlCalendar::get(int `$field`): int|false
public function IntlCalendar::getActualMaximum(int `$field`): int|false
public function IntlCalendar::getActualMinimum(int `$field`): int|false
public static function IntlCalendar::getAvailableLocales(): array
public function IntlCalendar::getDayOfWeekType(int `$dayOfWeek`): int|false
public function IntlCalendar::getErrorCode(): int|false
public function IntlCalendar::getErrorMessage(): string|false
public function IntlCalendar::getFirstDayOfWeek(): int|false
public function IntlCalendar::getGreatestMinimum(int `$field`): int|false
public static function IntlCalendar::getKeywordValuesForLocale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false
public function IntlCalendar::getLeastMaximum(int `$field`): int|false
public function IntlCalendar::getLocale(int `$type`): string|false
public function IntlCalendar::getMaximum(int `$field`): int|false
public function IntlCalendar::getMinimalDaysInFirstWeek(): int|false
public function IntlCalendar::getMinimum(int `$field`): int|false
public static function IntlCalendar::getNow(): float
public function IntlCalendar::getRepeatedWallTimeOption(): int
public function IntlCalendar::getSkippedWallTimeOption(): int
public function IntlCalendar::getTime(): float|false
public function IntlCalendar::getTimeZone(): IntlTimeZone|false
public function IntlCalendar::getType(): string
public function IntlCalendar::getWeekendTransition(int `$dayOfWeek`): int|false
public function IntlCalendar::inDaylightTime(): bool
public function IntlCalendar::isEquivalentTo(IntlCalendar `$other`): bool
public function IntlCalendar::isLenient(): bool
public function IntlCalendar::isSet(int `$field`): bool
public function IntlCalendar::isWeekend(?float `$timestamp` = `null`): bool
public function IntlCalendar::roll(int `$field`, int|bool `$value`): bool
public function IntlCalendar::set(int `$field`, int `$value`): true
public function IntlCalendar::set(
int `$year`,
int `$month`,
int `$dayOfMonth` = NULL,
int `$hour` = NULL,
int `$minute` = NULL,
int `$second` = NULL
): true
public function IntlCalendar::setDate(int `$year`, int `$month`, int `$dayOfMonth`): void
public function IntlCalendar::setDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): void
public function IntlCalendar::setFirstDayOfWeek(int `$dayOfWeek`): true
public function IntlCalendar::setLenient(bool `$lenient`): true
public function IntlCalendar::setMinimalDaysInFirstWeek(int `$days`): true
public function IntlCalendar::setRepeatedWallTimeOption(int `$option`): true
public function IntlCalendar::setSkippedWallTimeOption(int `$option`): true
public function IntlCalendar::setTime(float `$timestamp`): bool
public function IntlCalendar::setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool
public function IntlCalendar::toDateTime(): DateTime|false
}

# IntlGregorianCalendar::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::__construct — Crear la clase del calendario gregoriano

### Descripción

public function IntlGregorianCalendar::__construct(IntlTimeZone `$tz` = ?, string `$locale` = ?)
public function IntlGregorianCalendar::__construct(int `$timeZoneOrYear`, int `$localeOrMonth`, int `$dayOfMonth`)
public function IntlGregorianCalendar::__construct(
int `$timeZoneOrYear`,
int `$localeOrMonth`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
int `$second` = ?
)

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`tz`

`locale`

`timeZoneOrYear`

`localeOrMonth`

`dayOfMonth`

`hour`

`minute`

`second`

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Esto ha sido deprecado en favor de los métodos IntlGregorianCalendar::createFromDate() y IntlGregorianCalendar::createFromDateTime().

# IntlGregorianCalendar::createFromDate

(PHP 8 >= 8.3.0)

IntlGregorianCalendar::createFromDate — Crear una nueva instancia de IntlGregorianCalendar a partir de una fecha

### Descripción

public static function IntlGregorianCalendar::createFromDate(int `$year`, int `$month`, int `$dayOfMonth`): static

Crear una nueva instancia de IntlGregorianCalendar a partir de una fecha.

### Parámetros

`year`

  El nuevo valor para `IntlGregorianCalendar::FIELD_YEAR`.

`month`

  El nuevo valor para `IntlGregorianCalendar::FIELD_MONTH`. La secuencia de los meses comienza en cero, es decir, que enero está representado por 0, febrero por 1, ..., diciembre es 11 y Undécembre (si el calendario lo permite) es 12.

`dayOfMonth`

  El nuevo valor para `IntlGregorianCalendar::FIELD_DAY_OF_MONTH`.

### Valores devueltos

Devuelve una nueva instancia de IntlGregorianCalendar.

### Ejemplos

Ejemplo #1 Ejemplo de IntlGregorianCalendar::createFromDate()

    <?php

    $intlCalendar = IntlGregorianCalendar::createFromDate(2023, 11, 23);
    var_dump($intlCalendar);
    ?>

Resultado del ejemplo anterior es similar a:

    object(IntlGregorianCalendar)#1 (5) {
      ["valid"]=>
      bool(true)
      ["type"]=>
      string(9) "gregorian"
      ["timeZone"]=>
      array(4) {
        ["valid"]=>
        bool(true)
        ["id"]=>
        string(16) "Europe/Amsterdam"
        ["rawOffset"]=>
        int(3600000)
        ["currentOffset"]=>
        int(3600000)
      }
      ["locale"]=>
      string(11) "en_US_POSIX"
      ["fields"]=>
      array(23) {
        ["era"]=>
        int(1)
        ["year"]=>
        int(2023)
        ["month"]=>
        int(11)
        ["week of year"]=>
        int(51)
        ["week of month"]=>
        int(4)
        ["day of year"]=>
        int(357)
        ["day of month"]=>
        int(23)
        ["day of week"]=>
        int(7)
        ["day of week in month"]=>
        int(4)
        ["AM/PM"]=>
        int(0)
        ["hour"]=>
        int(0)
        ["hour of day"]=>
        int(0)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
        ["millisecond"]=>
        int(0)
        ["zone offset"]=>
        int(3600000)
        ["DST offset"]=>
        int(0)
        ["year for week of year"]=>
        int(2023)
        ["localized day of week"]=>
        int(7)
        ["extended year"]=>
        int(2023)
        ["julian day"]=>
        int(2460302)
        ["milliseconds in day"]=>
        int(0)
        ["is leap month"]=>
        int(0)
      }
    }

### Ver también

- IntlGregorianCalendar::createFromDateTime() - Crear una nueva instancia de IntlGregorianCalendar a partir de una fecha y hora

# IntlGregorianCalendar::createFromDateTime

(PHP 8 >= 8.3.0)

IntlGregorianCalendar::createFromDateTime — Crear una nueva instancia de IntlGregorianCalendar a partir de una fecha y hora

### Descripción

public static function IntlGregorianCalendar::createFromDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): static

Crear una nueva instancia de IntlGregorianCalendar a partir de una fecha y hora.

### Parámetros

`year`

  El nuevo valor para `IntlGregorianCalendar::FIELD_YEAR`.

`month`

  El nuevo valor para `IntlGregorianCalendar::FIELD_MONTH`. La secuencia de los meses comienza en cero, es decir, enero está representado por 0, febrero por 1, ..., diciembre es 11 y Undécembre (si el calendario lo permite) es 12.

`dayOfMonth`

  El nuevo valor para `IntlGregorianCalendar::FIELD_DAY_OF_MONTH`.

`hour`

  El nuevo valor para `IntlGregorianCalendar::FIELD_HOUR_OF_DAY`.

`minute`

  El nuevo valor para `IntlGregorianCalendar::FIELD_MINUTE`.

`second`

  El nuevo valor para `IntlGregorianCalendar::FIELD_SECOND`.

### Valores devueltos

Devuelve una nueva instancia de IntlGregorianCalendar.

### Ejemplos

Ejemplo #1 Ejemplo de IntlGregorianCalendar::createFromDateTime()

    <?php

    $intlCalendar = IntlGregorianCalendar::createFromDateTime(2023, 11, 23, 12, 00);
    var_dump($intlCalendar);
    ?>

Resultado del ejemplo anterior es similar a:

    object(IntlGregorianCalendar)#1 (5) {
      ["valid"]=>
      bool(true)
      ["type"]=>
      string(9) "gregorian"
      ["timeZone"]=>
      array(4) {
        ["valid"]=>
        bool(true)
        ["id"]=>
        string(16) "Europe/Amsterdam"
        ["rawOffset"]=>
        int(3600000)
        ["currentOffset"]=>
        int(3600000)
      }
      ["locale"]=>
      string(11) "en_US_POSIX"
      ["fields"]=>
      array(23) {
        ["era"]=>
        int(1)
        ["year"]=>
        int(2023)
        ["month"]=>
        int(11)
        ["week of year"]=>
        int(51)
        ["week of month"]=>
        int(4)
        ["day of year"]=>
        int(357)
        ["day of month"]=>
        int(23)
        ["day of week"]=>
        int(7)
        ["day of week in month"]=>
        int(4)
        ["AM/PM"]=>
        int(1)
        ["hour"]=>
        int(0)
        ["hour of day"]=>
        int(12)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
        ["millisecond"]=>
        int(0)
        ["zone offset"]=>
        int(3600000)
        ["DST offset"]=>
        int(0)
        ["year for week of year"]=>
        int(2023)
        ["localized day of week"]=>
        int(7)
        ["extended year"]=>
        int(2023)
        ["julian day"]=>
        int(2460302)
        ["milliseconds in day"]=>
        int(43200000)
        ["is leap month"]=>
        int(0)
      }
    }

### Ver también

- IntlGregorianCalendar::createFromDate() - Crear una nueva instancia de IntlGregorianCalendar a partir de una fecha

# IntlGregorianCalendar::getGregorianChange

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::getGregorianChange — Devuelve la fecha de cambio del calendario gregoriano

### Descripción

public function IntlGregorianCalendar::getGregorianChange(): float

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la fecha de cambio.

# IntlGregorianCalendar::isLeapYear

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::isLeapYear — Determina si el año dado es un año bisiesto

### Descripción

public function IntlGregorianCalendar::isLeapYear(int `$year`): bool

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`year`

### Valores devueltos

Devuelve `true` para los años bisiestos, `false` en caso contrario y en caso de error.

# IntlGregorianCalendar::setGregorianChange

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::setGregorianChange — Establece la fecha de cambio del calendario gregoriano

### Descripción

public function IntlGregorianCalendar::setGregorianChange(float `$timestamp`): bool

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`timestamp`

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

## Tabla de contenidos

- IntlGregorianCalendar::__construct — Crear la clase del calendario gregoriano
- IntlGregorianCalendar::createFromDate — Crear una nueva instancia de IntlGregorianCalendar a partir de una fecha
- IntlGregorianCalendar::createFromDateTime — Crear una nueva instancia de IntlGregorianCalendar a partir de una fecha y hora
- IntlGregorianCalendar::getGregorianChange — Devuelve la fecha de cambio del calendario gregoriano
- IntlGregorianCalendar::isLeapYear — Determina si el año dado es un año bisiesto
- IntlGregorianCalendar::setGregorianChange — Establece la fecha de cambio del calendario gregoriano

# La clase IntlTimeZone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

## Introducción

## Sinopsis de la Clase

class IntlTimeZone {
/* Constantes */
public const int DISPLAY_SHORT;
public const int DISPLAY_LONG;
public const int DISPLAY_SHORT_GENERIC;
public const int DISPLAY_LONG_GENERIC;
public const int DISPLAY_SHORT_GMT;
public const int DISPLAY_LONG_GMT;
public const int DISPLAY_SHORT_COMMONLY_USED;
public const int DISPLAY_GENERIC_LOCATION;
public const int TYPE_ANY;
public const int TYPE_CANONICAL;
public const int TYPE_CANONICAL_LOCATION;
/* Métodos */
private function __construct()
public static function countEquivalentIDs(string `$timezoneId`): int|false
public static function createDefault(): IntlTimeZone
public static function createEnumeration(string|int|null `$countryOrRawOffset` = `null`): IntlIterator|false
public static function createTimeZone(string `$timezoneId`): ?IntlTimeZone
public static function createTimeZoneIDEnumeration(int `$type`, ?string `$region` = `null`, ?int `$rawOffset` = `null`): IntlIterator|false
public static function fromDateTimeZone(DateTimeZone `$timezone`): ?IntlTimeZone
public static function getCanonicalID(string `$timezoneId`, bool `&$isSystemId` = `null`): string|false
public function getDisplayName(bool `$dst` = `false`, int `$style` = `IntlTimeZone::DISPLAY_LONG`, ?string `$locale` = `null`): string|false
public function getDSTSavings(): int
public static function getEquivalentID(string `$timezoneId`, int `$offset`): string|false
public function getErrorCode(): int|false
public function getErrorMessage(): string|false
public static function getGMT(): IntlTimeZone
public static function getIanaID(string `$timezoneId`): string|false
public function getID(): string|false
public static function getIDForWindowsID(string `$timezoneId`, ?string `$region` = `null`): string|false
public function getOffset(
float `$timestamp`,
bool `$local`,
int `&$rawOffset`,
int `&$dstOffset`
): bool
public function getRawOffset(): int
public static function getRegion(string `$timezoneId`): string|false
public static function getTZDataVersion(): string|false
public static function getUnknown(): IntlTimeZone
public static function getWindowsID(string `$timezoneId`): string|false
public function hasSameRules(IntlTimeZone `$other`): bool
public function toDateTimeZone(): DateTimeZone|false
public function useDaylightTime(): bool
}

## Constantes predefinidas

`IntlTimeZone::DISPLAY_SHORT` int

`IntlTimeZone::DISPLAY_LONG` int

`IntlTimeZone::DISPLAY_SHORT_GENERIC` int

`IntlTimeZone::DISPLAY_LONG_GENERIC` int

`IntlTimeZone::DISPLAY_SHORT_GMT` int

`IntlTimeZone::DISPLAY_LONG_GMT` int

`IntlTimeZone::DISPLAY_SHORT_COMMONLY_USED` int

`IntlTimeZone::DISPLAY_GENERIC_LOCATION` int

`IntlTimeZone::TYPE_ANY` int

`IntlTimeZone::TYPE_CANONICAL` int

`IntlTimeZone::TYPE_CANONICAL_LOCATION` int

## Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Las constantes de clase ahora están tipadas.

# IntlTimeZone::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::__construct — Constructor privado para evitar la instanciación directa

### Descripción

private function IntlTimeZone::__construct()

### Parámetros

Esta función no contiene ningún parámetro.

# IntlTimeZone::countEquivalentIDs

# intltz_count_equivalent_ids

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::countEquivalentIDs -- intltz_count_equivalent_ids — Obtiene el número de IDs en el grupo de equivalencia que incluye el ID proporcionado

### Descripción

Estilo orientado a objetos (método):

public static function IntlTimeZone::countEquivalentIDs(string `$timezoneId`): int|false

Estilo procedimental:

function intltz_count_equivalent_ids(string `$timezoneId`): int|false

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`timezoneId`

### Valores devueltos

# IntlTimeZone::createDefault

# intltz_create_default

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::createDefault -- intltz_create_default — Crea una nueva copia del huso horario por defecto para este host

### Descripción

Estilo orientado a objetos (método):

public static function IntlTimeZone::createDefault(): IntlTimeZone

Estilo procedimental:

function intltz_create_default(): IntlTimeZone

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlTimeZone::createEnumeration

# intltz_create_enumeration

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::createEnumeration -- intltz_create_enumeration — Obtiene una enumeración de IDs de zonas horarias asociadas con el país proporcionado

### Descripción

Estilo orientado a objetos (método):

public static function IntlTimeZone::createEnumeration(string|int|null `$countryOrRawOffset` = `null`): IntlIterator|false

Estilo procedimental:

function intltz_create_enumeration(string|int|null `$countryOrRawOffset` = `null`): IntlIterator|false

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`countryOrRawOffset`

### Valores devueltos

# IntlTimeZone::createTimeZone

# intltz_create_time_zone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::createTimeZone -- intltz_create_time_zone — Crea un objeto de zona horaria para el ID proporcionado

### Descripción

Estilo orientado a objetos (método):

public static function IntlTimeZone::createTimeZone(string `$timezoneId`): ?IntlTimeZone

Estilo procedimental:

function intltz_create_time_zone(string `$timezoneId`): ?IntlTimeZone

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`timezoneId`

### Valores devueltos

# IntlTimeZone::createTimeZoneIDEnumeration

# intltz_create_time_zone_id_enumeration

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlTimeZone::createTimeZoneIDEnumeration -- intltz_create_time_zone_id_enumeration — Devuelve una enumeración de los identificadores de zona horaria del sistema con las condiciones de filtro dadas

### Descripción

Estilo orientado a objetos (método):

public static function IntlTimeZone::createTimeZoneIDEnumeration(int `$type`, ?string `$region` = `null`, ?int `$rawOffset` = `null`): IntlIterator|false

Estilo procedimental:

function intltz_create_time_zone_id_enumeration(int `$type`, ?string `$region` = `null`, ?int `$rawOffset` = `null`): IntlIterator|false

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`type`

`region`

`rawOffset`

### Valores devueltos

Devuelve IntlIterator o `false` si ocurre un error.

# IntlTimeZone::fromDateTimeZone

# intltz_from_date_time_zone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::fromDateTimeZone -- intltz_from_date_time_zone — Crea un objeto de zona horaria a partir de DateTimeZone

### Descripción

Estilo orientado a objetos (método):

public static function IntlTimeZone::fromDateTimeZone(DateTimeZone `$timezone`): ?IntlTimeZone

Estilo procedimental:

function intltz_from_date_time_zone(DateTimeZone `$timezone`): ?IntlTimeZone

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`timezone`

### Valores devueltos

# IntlTimeZone::getCanonicalID

# intltz_get_canonical_id

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getCanonicalID -- intltz_get_canonical_id — Obtiene el identificador del huso horario del sistema o el identificador normalizado del huso horario personalizado para el ID del huso horario proporcionado

### Descripción

Estilo orientado a objetos (método):

public static function IntlTimeZone::getCanonicalID(string `$timezoneId`, bool `&$isSystemId` = `null`): string|false

Estilo procedimental:

function intltz_get_canonical_id(string `$timezoneId`, bool `&$isSystemId` = `null`): string|false

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`timezoneId`

`isSystemId`

### Valores devueltos

# IntlTimeZone::getDisplayName

# intltz_get_display_name

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getDisplayName -- intltz_get_display_name — Obtiene un nombre de zona horaria para su presentación al usuario

### Descripción

Estilo orientado a objetos (método):

public function IntlTimeZone::getDisplayName(bool `$dst` = `false`, int `$style` = `IntlTimeZone::DISPLAY_LONG`, ?string `$locale` = `null`): string|false

Estilo procedimental:

function intltz_get_display_name(
IntlTimeZone `$timezone`,
bool `$dst` = `false`,
int `$style` = `IntlTimeZone::DISPLAY_LONG`,
?string `$locale` = `null`
): string|false

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`dst`

`style`

`locale`

### Valores devueltos

# IntlTimeZone::getDSTSavings

# intltz_get_dst_savings

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getDSTSavings -- intltz_get_dst_savings — Obtiene la duración a añadir a la hora local para recuperar la hora local estándar

### Descripción

Estilo orientado a objetos (método):

public function IntlTimeZone::getDSTSavings(): int

Estilo procedimental:

function intltz_get_dst_savings(IntlTimeZone `$timezone`): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlTimeZone::getEquivalentID

# intltz_get_equivalent_id

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getEquivalentID -- intltz_get_equivalent_id — Obtiene un identificador de un grupo de equivalencia que incluye el identificador proporcionado

### Descripción

Estilo orientado a objetos (método):

public static function IntlTimeZone::getEquivalentID(string `$timezoneId`, int `$offset`): string|false

Estilo procedimental:

function intltz_get_equivalent_id(string `$timezoneId`, int `$offset`): string|false

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`timezoneId`

`offset`

### Valores devueltos

# IntlTimeZone::getErrorCode

# intltz_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getErrorCode -- intltz_get_error_code — Recupera el código del último error ocurrido en el objeto

### Descripción

Estilo orientado a objetos (método):

public function IntlTimeZone::getErrorCode(): int|false

Estilo procedimental:

function intltz_get_error_code(IntlTimeZone `$timezone`): int|false

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlTimeZone::getErrorMessage

# intltz_get_error_message

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getErrorMessage -- intltz_get_error_message — Recupera el mensaje del último error ocurrido en el objeto

### Descripción

Estilo orientado a objetos (método):

public function IntlTimeZone::getErrorMessage(): string|false

Estilo procedimental:

function intltz_get_error_message(IntlTimeZone `$timezone`): string|false

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlTimeZone::getGMT

# intltz_get_gmt

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getGMT -- intltz_get_gmt — Crea un huso horario GMT (UTC)

### Descripción

Estilo orientado a objetos (método):

public static function IntlTimeZone::getGMT(): IntlTimeZone

Estilo procedimental:

function intltz_get_gmt(): IntlTimeZone

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlTimeZone::getIanaID

# intltz_get_iana_id

(PHP 8 >= 8.4.0)

IntlTimeZone::getIanaID -- intltz_get_iana_id — Traduce un identificador de zona horaria a su equivalente IANA

### Descripción

Estilo orientado a objetos (método):

public static function IntlTimeZone::getIanaID(string `$timezoneId`): string|false

Estilo procedimental:

function intltz_get_iana_id(string `$timezoneId`): string|false

Traduce un identificador de zona horaria a su equivalente IANA. Por ejemplo, `"GMT"` devuelve `"Etc/GMT"`, y `"US/Eastern"` devuelve `"America/New_York"`.

> Nota: Esta función requiere ICU versión >= 74.

### Parámetros

`timezoneId`
  El identificador de la zona horaria a traducir.

### Valores devueltos

Devuelve el identificador de zona horaria IANA como string, o `false` en caso de fallo.

### Ver también

- intltz_get_id_for_windows_id() - Traduce una zona horaria de Windows a una zona horaria del sistema
- intltz_get_windows_id() - Traduce una zona horaria del sistema a una zona horaria de Windows
- intltz_create_time_zone() - Crea un objeto de zona horaria para el ID proporcionado

# IntlTimeZone::getID

# intltz_get_id

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getID -- intltz_get_id — Obtiene el ID de una zona horaria

### Descripción

Estilo orientado a objetos (método):

public function IntlTimeZone::getID(): string|false

Estilo procedimental:

function intltz_get_id(IntlTimeZone `$timezone`): string|false

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlTimeZone::getIDForWindowsID

# intltz_get_id_for_windows_id

(PHP 7 >= 7.1.0, PHP 8)

IntlTimeZone::getIDForWindowsID -- intltz_get_id_for_windows_id — Traduce una zona horaria de Windows a una zona horaria del sistema

### Descripción

Estilo orientado a objetos (método):

public static function IntlTimeZone::getIDForWindowsID(string `$timezoneId`, ?string `$region` = `null`): string|false

Estilo procedimental:

function intltz_get_id_for_windows_id(string `$timezoneId`, ?string `$region` = `null`): string|false

Traduce una zona horaria de Windows (por ejemplo "Pacific Standard Time") a una zona horaria del sistema (por ejemplo "America/Los_Angeles").

> Nota: Esta función requiere ICU versión ≥ 52.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`timezoneId`

`region`

### Valores devueltos

Devuelve la zona horaria del sistema o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `region` ahora puede ser nullable.

### Ver también

- IntlTimeZone::getWindowsID() - Traduce una zona horaria del sistema a una zona horaria de Windows

# IntlTimeZone::getOffset

# intltz_get_offset

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getOffset -- intltz_get_offset — Obtiene el desplazamiento bruto de la zona horaria y la posición GMT para un momento dado

### Descripción

Estilo orientado a objetos (método):

public function IntlTimeZone::getOffset(
float `$timestamp`,
bool `$local`,
int `&$rawOffset`,
int `&$dstOffset`
): bool

Estilo procedimental:

function intltz_get_offset(
IntlTimeZone `$timezone`,
float `$timestamp`,
bool `$local`,
int `&$rawOffset`,
int `&$dstOffset`
): bool

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`timestamp`

`local`

`rawOffset`

`dstOffset`

### Valores devueltos

# IntlTimeZone::getRawOffset

# intltz_get_raw_offset

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getRawOffset -- intltz_get_raw_offset — Obtiene la posición bruta GMT (antes de considerar el horario de verano)

### Descripción

Estilo orientado a objetos (método):

public function IntlTimeZone::getRawOffset(): int

Estilo procedimental:

function intltz_get_raw_offset(IntlTimeZone `$timezone`): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlTimeZone::getRegion

# intltz_get_region

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlTimeZone::getRegion -- intltz_get_region — Devuelve el código de región asociado al identificador de zona horaria del sistema dado

### Descripción

Estilo orientado a objetos (método):

public static function IntlTimeZone::getRegion(string `$timezoneId`): string|false

Estilo procedimental:

function intltz_get_region(string `$timezoneId`): string|false

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`timezoneId`

  El identificador de zona horaria del sistema.

### Valores devueltos

Devuelve la región o o `false` si ocurre un error.

# IntlTimeZone::getTZDataVersion

# intltz_get_tz_data_version

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getTZDataVersion -- intltz_get_tz_data_version — Recupera la versión de la zona horaria actualmente utilizada por ICU

### Descripción

Estilo orientado a objetos (método):

public static function IntlTimeZone::getTZDataVersion(): string|false

Estilo procedimental:

function intltz_get_tz_data_version(): string|false

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlTimeZone::getUnknown

# intltz_get_unknown

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlTimeZone::getUnknown -- intltz_get_unknown — Devuelve la zona horaria "desconocida"

### Descripción

Estilo orientado a objetos (método):

public static function IntlTimeZone::getUnknown(): IntlTimeZone

Estilo procedimental:

function intltz_get_unknown(): IntlTimeZone

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve IntlTimeZone o `null` en caso de error.

# IntlTimeZone::getWindowsID

# intltz_get_windows_id

(PHP 7 >= 7.1.0, PHP 8)

IntlTimeZone::getWindowsID -- intltz_get_windows_id — Traduce una zona horaria del sistema a una zona horaria de Windows

### Descripción

Estilo orientado a objetos (método):

public static function IntlTimeZone::getWindowsID(string `$timezoneId`): string|false

Estilo procedimental:

function intltz_get_windows_id(string `$timezoneId`): string|false

Traduce una zona horaria del sistema (por ejemplo "America/Los_Angeles") a una zona horaria de Windows (por ejemplo "Pacific Standard Time").

> Nota: Esta función requiere ICU versión ≥ 52.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`timezoneId`

  El identificador de la zona horaria.

### Valores devueltos

Devuelve la zona horaria de Windows o `false` si ocurre un error.

### Ver también

- IntlTimeZone::getIDForWindowsID() - Traduce una zona horaria de Windows a una zona horaria del sistema

# IntlTimeZone::hasSameRules

# intltz_has_same_rules

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::hasSameRules -- intltz_has_same_rules — Verifica si esta zona tiene las mismas reglas que otra

### Descripción

Estilo orientado a objetos (método):

public function IntlTimeZone::hasSameRules(IntlTimeZone `$other`): bool

Estilo procedimental:

function intltz_has_same_rules(IntlTimeZone `$timezone`, IntlTimeZone `$other`): bool

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`other`

### Valores devueltos

# IntlTimeZone::toDateTimeZone

# intltz_to_date_time_zone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::toDateTimeZone -- intltz_to_date_time_zone — Convierte un objeto DateTimeZone

### Descripción

Estilo orientado a objetos (método):

public function IntlTimeZone::toDateTimeZone(): DateTimeZone|false

Estilo procedimental:

function intltz_to_date_time_zone(IntlTimeZone `$timezone`): DateTimeZone|false

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlTimeZone::useDaylightTime

# intltz_use_daylight_time

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::useDaylightTime -- intltz_use_daylight_time — Verifica si este huso horario utiliza la hora de verano

### Descripción

Estilo orientado a objetos (método):

public function IntlTimeZone::useDaylightTime(): bool

Estilo procedimental:

function intltz_use_daylight_time(IntlTimeZone `$timezone`): bool

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

## Tabla de contenidos

- IntlTimeZone::__construct — Constructor privado para evitar la instanciación directa
- IntlTimeZone::countEquivalentIDs — Obtiene el número de IDs en el grupo de equivalencia que incluye el ID proporcionado
- IntlTimeZone::createDefault — Crea una nueva copia del huso horario por defecto para este host
- IntlTimeZone::createEnumeration — Obtiene una enumeración de IDs de zonas horarias asociadas con el país proporcionado
- IntlTimeZone::createTimeZone — Crea un objeto de zona horaria para el ID proporcionado
- IntlTimeZone::createTimeZoneIDEnumeration — Devuelve una enumeración de los identificadores de zona horaria del sistema con las condiciones de filtro dadas
- IntlTimeZone::fromDateTimeZone — Crea un objeto de zona horaria a partir de DateTimeZone
- IntlTimeZone::getCanonicalID — Obtiene el identificador del huso horario del sistema o el identificador normalizado del huso horario personalizado para el ID del huso horario proporcionado
- IntlTimeZone::getDisplayName — Obtiene un nombre de zona horaria para su presentación al usuario
- IntlTimeZone::getDSTSavings — Obtiene la duración a añadir a la hora local para recuperar la hora local estándar
- IntlTimeZone::getEquivalentID — Obtiene un identificador de un grupo de equivalencia que incluye el identificador proporcionado
- IntlTimeZone::getErrorCode — Recupera el código del último error ocurrido en el objeto
- IntlTimeZone::getErrorMessage — Recupera el mensaje del último error ocurrido en el objeto
- IntlTimeZone::getGMT — Crea un huso horario GMT (UTC)
- IntlTimeZone::getIanaID — Traduce un identificador de zona horaria a su equivalente IANA
- IntlTimeZone::getID — Obtiene el ID de una zona horaria
- IntlTimeZone::getIDForWindowsID — Traduce una zona horaria de Windows a una zona horaria del sistema
- IntlTimeZone::getOffset — Obtiene el desplazamiento bruto de la zona horaria y la posición GMT para un momento dado
- IntlTimeZone::getRawOffset — Obtiene la posición bruta GMT (antes de considerar el horario de verano)
- IntlTimeZone::getRegion — Devuelve el código de región asociado al identificador de zona horaria del sistema dado
- IntlTimeZone::getTZDataVersion — Recupera la versión de la zona horaria actualmente utilizada por ICU
- IntlTimeZone::getUnknown — Devuelve la zona horaria "desconocida"
- IntlTimeZone::getWindowsID — Traduce una zona horaria del sistema a una zona horaria de Windows
- IntlTimeZone::hasSameRules — Verifica si esta zona tiene las mismas reglas que otra
- IntlTimeZone::toDateTimeZone — Convierte un objeto DateTimeZone
- IntlTimeZone::useDaylightTime — Verifica si este huso horario utiliza la hora de verano

# La clase IntlDateFormatter

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Introducción

La clase DateFormatter es una clase concreta, que activa el análisis y el formato de fechas, basado en cadenas modelo, o reglas.

Esta clase representa las funcionalidades de formato de fechas ICU. Permite a los usuarios mostrar fechas en un formato localizado, o analizar cadenas PHP para extraer fechas.

## Sinopsis de la clase

class IntlDateFormatter {
/* Constantes */
public const int FULL;
public const int LONG;
public const int MEDIUM;
public const int SHORT;
public const int NONE;
public const int RELATIVE_FULL;
public const int RELATIVE_LONG;
public const int RELATIVE_MEDIUM;
public const int RELATIVE_SHORT;
public const int PATTERN;
public const int GREGORIAN;
public const int TRADITIONAL;
/* Métodos */
public function __construct(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
)
public static function create(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
): ?IntlDateFormatter
public function format(IntlCalendar|DateTimeInterface|array|string|int|float `$datetime`): string|false
public static function formatObject(IntlCalendar|DateTimeInterface `$datetime`, array|int|string|null `$format` = `null`, ?string `$locale` = `null`): string|false
public function getCalendar(): int|false
public function getDateType(): int|false
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false
public function getPattern(): string|false
public function getTimeType(): int|false
public function getTimeZoneId(): string|false
public function getCalendarObject(): IntlCalendar|false|null
public function getTimeZone(): IntlTimeZone|false
public function isLenient(): bool
public function localtime(string `$string`, int `&$offset` = `null`): array|false
public function parse(string `$string`, int `&$offset` = `null`): int|float|false
public function parseToCalendar(string `$string`, int `&$offset` = `null`): int|float|false
public function setCalendar(IntlCalendar|int|null `$calendar`): bool
public function setLenient(bool `$lenient`): void
public function setPattern(string `$pattern`): bool
public function setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool
}

## Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Se añadió `IntlDateFormatter::PATTERN`.

## Ver también

- » Formateador de fechas ICU

- » Formatos de fechas ICU

## Constantes predefinidas

Estas constantes se utilizan para especificar diferentes formatos en el constructor de las clases DateType y TimeType.

`IntlDateFormatter::NONE` int
  No incluye este elemento
`IntlDateFormatter::FULL` int
  Estilo completamente especificado (`Tuesday, April 12, 1952 AD or 3:30:42pm PST`)
`IntlDateFormatter::LONG` int
  Estilo largo (`January 12, 1952 or 3:30:32pm`)
`IntlDateFormatter::MEDIUM` int
  Estilo intermedio (`Jan 12, 1952`)
`IntlDateFormatter::SHORT` int
  Estilo abreviado, solo la información esencial (`12/13/52` o `3:30pm`)
`IntlDateFormatter::RELATIVE_FULL` int
  Idéntico a `IntlDateFormatter::FULL`, pero ayer, hoy, y mañana se muestran como `yesterday`, `today`, y `tomorrow`, respectivamente. Disponible a partir de PHP 8.0.0, para `dateType` únicamente.
`IntlDateFormatter::RELATIVE_LONG` int
  Idéntico a `IntlDateFormatter::LONG`, pero ayer, hoy, y mañana se muestran como `yesterday`, `today`, y `tomorrow`, respectivamente. Disponible a partir de PHP 8.0.0, para `dateType` únicamente.
`IntlDateFormatter::RELATIVE_MEDIUM` int
  Idéntico a `IntlDateFormatter::MEDIUM`, pero ayer, hoy, y mañana se muestran como `yesterday`, `today`, y `tomorrow`, respectivamente. Disponible a partir de PHP 8.0.0, para `dateType` únicamente.
`IntlDateFormatter::RELATIVE_SHORT` int
  Idéntico a `IntlDateFormatter::SHORT`, pero ayer, hoy, y mañana se muestran como `yesterday`, `today`, y `tomorrow`, respectivamente. Disponible a partir de PHP 8.0.0, para `dateType` únicamente.
`IntlDateFormatter::PATTERN` int
  Utiliza el patrón dado en `pattern`. Disponible a partir de PHP 8.4.0.

Las constantes enteras siguientes se utilizan para especificar calendarios. Estos calendarios se basan directamente en el calendario gregoriano. Los calendarios no gregorianos deben especificarse en una configuración local. Los ejemplos pueden incluir `locale="hi@calendar=BUDDHIST"`.

`IntlDateFormatter::TRADITIONAL` int
  Calendario no gregoriano
`IntlDateFormatter::GREGORIAN` int
  Calendario gregoriano

## Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Las constantes de clase ahora están tipadas.

# IntlDateFormatter::create

# datefmt_create

# IntlDateFormatter::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::create -- datefmt_create -- IntlDateFormatter::__construct — Crea un formateador de fecha

### Descripción

Estilo orientado a objetos

public static function IntlDateFormatter::create(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
): ?IntlDateFormatter

Estilo orientado a objetos (constructor)

public function IntlDateFormatter::__construct(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
)

Estilo procedimental

function datefmt_create(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
): ?IntlDateFormatter

Crea un formateador de fecha.

### Parámetros

`locale`

  La configuración local a utilizar para formatear y analizar o `null` para utilizar el valor especificado en la configuración ini intl.default_locale.

`dateType`

  El tipo de fecha a utilizar (`none`, `short`, `medium`, `long`, `full`). Es una de las constantes IntlDateFormatter.

`timeType`

  Formato de hora determinado por una de las constantes de IntlDateFormatter. El valor por omisión es `IntlDateFormatter::FULL`.

`timezone`

  El identificador de la zona horaria. Por omisión, (esto también será el valor por omisión que se utilizará si se proporciona `null`) será el devuelto por la función date_default_timezone_get() o, si es aplicable, el de objeto IntlCalendar pasado al argumento `calendar`. Este identificador debe ser un identificador válido en la base de datos ICU, o un identificador que represente una zona horaria explícita, como `GMT-05:30`.

  Este argumento también puede ser un objeto IntlTimeZone o un objeto DateTimeZone.

`calendar`

  Calendario a utilizar para el formato o el análisis. El valor por omisión es `null`, lo que corresponde a la constante `IntlDateFormatter::GREGORIAN`. Puede ser una de las constantes de calendario IntlDateFormatter o un IntlCalendar. Cualquier objeto IntlCalendar pasado será clonado; no será modificado por IntlDateFormatter. Determinará el tipo de calendario utilizado (gregoriano, islámico, persa, etc.) y si `null` es proporcionado en el argumento `timezone`, la zona horaria también será utilizada.

`pattern`

  El patrón a utilizar para el formato o el análisis. Los patrones disponibles están documentados en » https://unicode-org.github.io/icu/userguide/format_parse/datetime/.

### Valores devueltos

El objeto IntlDateFormatter creado, o `null` si ocurre un error.

### Errores/Excepciones

Se lanza una ValueError si `locale` es inválido.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Se lanza una ValueError si `locale` es inválido.
8.1.0 | Los argumentos `dateType` y `timeType` ahora son opcionales.

### Ejemplos

Ejemplo #1 Ejemplo con datefmt_create(), procedimental

    <?php
    $fmt = datefmt_create( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
        'America/Los_Angeles', IntlDateFormatter::GREGORIAN  );
    echo "El primer formato mostrado es ".datefmt_format( $fmt , 0);
    $fmt = datefmt_create( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
        'America/Los_Angeles',IntlDateFormatter::GREGORIAN  );
    echo "El segundo formato mostrado es  ".datefmt_format( $fmt , 0);

    $fmt = datefmt_create( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
         'America/Los_Angeles',IntlDateFormatter::GREGORIAN  ,"MM/dd/yyyy");
    echo "El primer formato se muestra con el patrón: ".datefmt_format( $fmt , 0);
    $fmt = datefmt_create( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
         'America/Los_Angeles',IntlDateFormatter::GREGORIAN  ,"MM/dd/yyyy");
    echo "El segundo formato se muestra con el patrón: ".datefmt_format( $fmt , 0);
    ?>

Ejemplo #2 Ejemplo con datefmt_create(), POO

    <?php
    $fmt = new IntlDateFormatter( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
        'America/Los_Angeles',IntlDateFormatter::GREGORIAN  );
    echo "El primer formato mostrado es ".$fmt->format(0);
    $fmt = new IntlDateFormatter( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
        'America/Los_Angeles',IntlDateFormatter::GREGORIAN  );
    echo "El segundo formato mostrado es ".$fmt->format(0);

    $fmt = new IntlDateFormatter( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
         'America/Los_Angeles',IntlDateFormatter::GREGORIAN  ,"MM/dd/yyyy");
    echo "El primer formato se muestra con el patrón: ".$fmt->format(0);
    $fmt = new IntlDateFormatter( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
          'America/Los_Angeles',IntlDateFormatter::GREGORIAN , "MM/dd/yyyy");
    echo "El segundo formato se muestra con el patrón: ".$fmt->format(0);
    ?>

Ejemplo #3 Ejemplo de manejo de configuración local inválida

    <?php
    try {
        $fmt = new IntlDateFormatter(
            'locale_invalido',
            IntlDateFormatter::FULL,
            IntlDateFormatter::FULL,
            'je_ne_sais_pas',
            IntlDateFormatter::GREGORIAN,
        );
    } catch (\Error $e) {
        // ...
    }
    ?>

El ejemplo anterior mostrará:

    El primer formato mostrado es Wednesday, December 31, 1969 4:00:00 PM PT
    El segundo formato mostrado es Mittwoch, 31. Dezember 1969 16:00 Uhr GMT-08:00
    El primer formato se muestra con el patrón: 12/31/1969
    El segundo formato se muestra con el patrón: 12/31/1969

### Ver también

- datefmt_format() - Formatea la fecha y la hora como string
- datefmt_parse() - Analiza una cadena hacia un timestamp
- datefmt_get_error_code() - Lee el código de error de la última operación
- datefmt_get_error_message() - Lee el último mensaje de error

# IntlDateFormatter::format

# datefmt_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::format -- datefmt_format — Formatea la fecha y la hora como string

### Descripción

Estilo orientado a objetos

public function IntlDateFormatter::format(IntlCalendar|DateTimeInterface|array|string|int|float `$datetime`): string|false

Estilo procedimental

function datefmt_format(IntlDateFormatter `$formatter`, IntlCalendar|DateTimeInterface|array|string|int|float `$datetime`): string|false

Formatea la hora como string.

### Parámetros

`formatter`

  El recurso de formateador IntlDateFormatter.

`datetime`

  El valor a formatear. Puede ser un objeto DateTimeInterface, un objeto IntlCalendar, un tipo numeric representando un (puede ser fraccionado) número de segundos desde la época o un array en el formato de salida de la función localtime().

  Si se pasa un objeto DateTime o un objeto IntlCalendar, su zona horaria no será considerada. El objeto deberá ser formateado utilizando la zona horaria configurada para este formateador. Si se desea utilizar la zona horaria del objeto a formatear, el método IntlDateFormatter::setTimeZone() deberá ser llamado antes de la zona horaria del objeto. También puede utilizarse el método IntlDateFormatter::formatObject() para obtener el mismo resultado.

### Valores devueltos

El string formateado, o, si ocurre un error, `false`.

### Historial de cambios

Versión | Descripción
--- | ---
7.1.5 | Se añadió el soporte para proporcionar un objeto genérico DateTimeInterface para el argumento `datetime`. Anteriormente, solo los objetos válidos DateTime eran soportados.
PECL intl 3.0.0 | Ahora es posible pasar un objeto IntlCalendar como valor del argumento `datetime`.

### Ejemplos

Ejemplo #1 Ejemplo con datefmt_format()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'El primer formato mostrado es ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'El segundo formato mostrado es ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'El primer formato es mostrado con el patrón ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo "El segundo formato es mostrado con el patrón " . datefmt_format($fmt, 0);
    ?>

Ejemplo #2 Ejemplo orientado a objetos

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'El primer formato mostrado es ' . $fmt->format(0);

    $fmt = new IntlDateFormatter(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'El segundo formato mostrado es ' . $fmt->format(0);

    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'El primer formato es mostrado con el patrón ' . $fmt->format(0);

    $fmt = new IntlDateFormatter(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'El segundo formato es mostrado con el patrón ' . $fmt->format(0);
    ?>

El ejemplo anterior mostrará:

    El primer formato mostrado es Wednesday, December 31, 1969 4:00:00 PM PT
    El segundo formato mostrado es Mittwoch, 31. Dezember 1969 16:00 Uhr GMT-08:00
    El primer formato es mostrado con el patrón : 12/31/1969
    El segundo formato es mostrado con el patrón : 12/31/1969

Ejemplo #3 Ejemplo con un objeto IntlCalendar

    <?php
    $tz = reset(iterator_to_array(IntlTimeZone::createEnumeration('FR')));
    $formatter = IntlDateFormatter::create(
        'fr_FR',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        $tz,
        IntlDateFormatter::GREGORIAN
    );

    $cal = IntlCalendar::createInstance($tz, '@calendar=islamic-civil');
    $cal->set(IntlCalendar::FIELD_MONTH, 8); //9º mes, Ramadán
    $cal->set(IntlCalendar::FIELD_DAY_OF_MONTH, 1); //1º día
    $cal->clear(IntlCalendar::FIELD_HOUR_OF_DAY);
    $cal->clear(IntlCalendar::FIELD_MINUTE);
    $cal->clear(IntlCalendar::FIELD_SECOND);
    $cal->clear(IntlCalendar::FIELD_MILLISECOND);

    echo "En el año Islámico, el Ramadán comienza el :\n\t",
            $formatter->format($cal), "\n";

    //Es la zona horaria del formateador la que se utiliza aquí :
    $formatter->setTimeZone('Asia/Tokyo');
    echo "Después de modificar la zona horaria :\n\t",
            $formatter->format($cal), "\n";

El ejemplo anterior mostrará:

    En el año Islámico, el Ramadán comienza el :
        martes 9 julio 2013 19:00:00 hora avanzada de Europa central
    Después de modificar la zona horaria :
        miércoles 10 julio 2013 02:00:00 hora normal de Japón

### Ver también

- datefmt_create() - Crea un formateador de fecha
- datefmt_parse() - Analiza una cadena hacia un timestamp
- datefmt_get_error_code() - Lee el código de error de la última operación
- datefmt_get_error_message() - Lee el último mensaje de error
- datefmt_format_object() - Formatea un objeto

# IntlDateFormatter::formatObject

# datefmt_format_object

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::formatObject -- datefmt_format_object — Formatea un objeto

### Descripción

Estilo orientado a objetos

public static function IntlDateFormatter::formatObject(IntlCalendar|DateTimeInterface `$datetime`, array|int|string|null `$format` = `null`, ?string `$locale` = `null`): string|false

Estilo procedimental

function datefmt_format_object(IntlCalendar|DateTimeInterface `$datetime`, array|int|string|null `$format` = `null`, ?string `$locale` = `null`): string|false

Esta función permite el formato de un objeto IntlCalendar o de un objeto DateTime sin haber creado previamente un objeto IntlDateFormatter.

El objeto IntlDateFormatter temporal creado tomará el desplazamiento horario desde el objeto pasado. La base de datos de desplazamientos horarios interna a PHP no será utilizada - ICU será utilizado en su lugar. El identificador de desplazamiento horario utilizado en los objetos DateTime debe existir también en la base de datos ICU.

### Parámetros

`datetime`

  Un objeto de tipo IntlCalendar o de tipo DateTime. La información de desplazamiento horario en el objeto será utilizada.

`format`

  Formato de la fecha/hora. Puede ser un array con dos elementos (primero el estilo de la fecha, luego el estilo de la hora, utilizando una de las constantes siguientes: `IntlDateFormatter::NONE`, `IntlDateFormatter::SHORT`, `IntlDateFormatter::MEDIUM`, `IntlDateFormatter::LONG`, `IntlDateFormatter::FULL`), un tipo int con el valor de una de estas constantes (en cuyo caso, será utilizado tanto para la fecha como para la hora), o un tipo string con el formato descrito en la » documentación ICU. Si `null` es proporcionado, el estilo por defecto será utilizado.

`locale`

  La configuración local a utilizar, o `null` para utilizar la configuración local por defecto.

### Valores devueltos

Una cadena de caracteres que contiene el resultado o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con IntlDateFormatter::formatObject()

    <?php
    /* El desplazamiento horario por defecto no es significativo;
       se toma desde el objeto */
    ini_set('date.timezone', 'UTC');

    /* La configuración local por defecto se toma desde la configuración ini */
    ini_set('intl.default_locale', 'fr_FR');

    $cal = IntlCalendar::fromDateTime("2013-06-06 17:05:06 Europe/Dublin");
    echo "défault :\n\t",
            IntlDateFormatter::formatObject($cal),
            "\n";

    echo "long \$format (complet) :\n\t",
            IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL),
            "\n";

    echo "array \$format (ninguno, complet) :\n\t",
            IntlDateFormatter::formatObject($cal, array(
                    IntlDateFormatter::NONE,
                    IntlDateFormatter::FULL)),
            "\n";

    echo "string \$format (d 'de' MMMM y):\n\t",
            IntlDateFormatter::formatObject($cal, "d 'de' MMMM y", 'en_US'),
            "\n";

    echo "con DateTime :\n\t",
            IntlDateFormatter::formatObject(
                    new DateTime("2013-09-09 09:09:09 Europe/Madrid"),
                    IntlDateFormatter::FULL,
                    'es_ES'),
            "\n";

El ejemplo anterior mostrará:

    défault :
        6 junio 2013 17:05:06
    long $format (complet):
        jueves 6 junio 2013 17:05:06 hora de verano irlandesa
    array $format (ninguno, complet):
        17:05:06 hora de verano irlandesa
    string $format (d 'de' MMMM y):
        6 de June 2013
    con DateTime :
        lunes, 9 de septiembre de 2013 09:09:09 Hora de verano de Europa central

# IntlDateFormatter::getCalendar

# datefmt_get_calendar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getCalendar -- datefmt_get_calendar — Lee el calendario utilizado por el objeto IntlDateFormatter

### Descripción

Estilo orientado a objetos

public function IntlDateFormatter::getCalendar(): int|false

Estilo procedimental

function datefmt_get_calendar(IntlDateFormatter `$formatter`): int|false

### Parámetros

`formatter`

  El recurso de formateador IntlDateFormatter.

### Valores devueltos

El tipo de calendario utilizado por el formateador. Puede ser ya sea la constante `IntlDateFormatter::TRADITIONAL`, ya sea la constante `IntlDateFormatter::GREGORIAN`. Devuelve `false` en caso de fallo.

### Ejemplos

Ejemplo #1 Ejemplo con datefmt_get_calendar()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'El calendario del formateador es : ' . datefmt_get_calendar($fmt);
    datefmt_set_calendar($fmt, IntlDateFormatter::TRADITIONAL);
    echo 'El calendario es ahora : ' . datefmt_get_calendar($fmt);
    ?>

Ejemplo #2 Ejemplo orientado a objetos

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'El calendario del formateador es : ' . $fmt->getCalendar();
    $fmt->setCalendar(IntlDateFormatter::TRADITIONAL);
    echo 'El calendario es ahora : ' . $fmt->getCalendar();

    ?>

Ejemplo #3 Ejemplo de manejo de configuración local inválida

    <?php
    try {
        $fmt = new IntlDateFormatter(
            'locale_invalide',
            IntlDateFormatter::FULL,
            IntlDateFormatter::FULL,
            'je_ne_sais_pas',
            IntlDateFormatter::GREGORIAN,
        );
        $cal = $fmt->getCalendar();
    } catch (\Error $e) {
        // ...
    }
    ?>

El ejemplo anterior mostrará:

    El calendario del formateador es : 1
    El calendario es ahora : 0

### Ver también

- datefmt_get_calendar_object() - Obtiene una copia del objeto formateador de calendario
- datefmt_set_calendar() - Define el tipo de calendario utilizado por el formateador
- datefmt_create() - Crea un formateador de fecha

# IntlDateFormatter::getDateType

# datefmt_get_datetype

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getDateType -- datefmt_get_datetype — Lee el tipo de fecha utilizado por IntlDateFormatter

### Descripción

Estilo orientado a objetos

public function IntlDateFormatter::getDateType(): int|false

Estilo procedimental

function datefmt_get_datetype(IntlDateFormatter `$formatter`): int|false

Devuelve el tipo de fecha utilizado por el formateador IntlDateFormatter.

### Parámetros

`formatter`

  El recurso del formateador IntlDateFormatter.

### Valores devueltos

El tipo de fecha actual del formateador, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con datefmt_get_datetype()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'El tipo de fecha del formateador es : ' . datefmt_get_datetype($fmt);
    echo 'La visualización con el primer tipo de fecha es ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::SHORT,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Ahora, el tipo de fecha del formateador es : ' . datefmt_get_datetype($fmt);
    echo 'La visualización con el segundo tipo de fecha es ' . datefmt_format($fmt, 0);

    ?>

Ejemplo #2 Ejemplo orientado a objetos

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'El tipo de fecha del formateador es : ' . $fmt->getDateType();
    echo 'La visualización con el primer tipo de fecha es ' . $fmt->format(0);
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::SHORT,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Ahora, el tipo de fecha del formateador es : ' . $fmt->getDateType();
    echo 'La visualización con el segundo tipo de fecha es ' . $fmt->format(0);

    ?>

El ejemplo anterior mostrará:

    El tipo de fecha del formateador es : 0
    La visualización con el primer tipo de fecha es Wednesday, December 31, 1969 4:00:00 PM PT
    Ahora, el tipo de fecha del formateador es : 2
    La visualización con el primer tipo de fecha es 12/31/69 4:00:00 PM PT

### Ver también

- datefmt_get_timetype() - Lee el tipo de tiempo para IntlDateFormatter
- datefmt_create() - Crea un formateador de fecha

# IntlDateFormatter::getErrorCode

# datefmt_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getErrorCode -- datefmt_get_error_code — Lee el código de error de la última operación

### Descripción

Estilo orientado a objetos

public function IntlDateFormatter::getErrorCode(): int

Estilo procedimental

function datefmt_get_error_code(IntlDateFormatter `$formatter`): int

Devuelve el código de error de la última operación de formato.

### Parámetros

`formatter`

  El recurso de formateador IntlDateFormatter.

### Valores devueltos

El código de error, uno de los valores UErrorCode. El valor inicial es U_ZERO_ERROR.

### Ejemplos

Ejemplo #1 Ejemplo con datefmt_get_error_code()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $str = datefmt_format($fmt);

    printf(
        "Error : %s (%d)\n",
        datefmt_get_error_message($fmt),
        datefmt_get_error_code($fmt)
    );
    ?>

Ejemplo #2 Ejemplo orientado a objetos

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $str = $fmt->format(0);

    printf(
        "Error : %s (%d)\n",
        $fmt->getErrorMessage(),
        $fmt->getErrorCode()
    );
    ?>

El ejemplo anterior mostrará:

    Error : U_ZERO_ERROR (0)

### Ver también

- datefmt_get_error_message() - Lee el último mensaje de error
- intl_get_error_code() - Lee el último código de error
- intl_is_failure() - Verifica si un código de error indica un fallo

# IntlDateFormatter::getErrorMessage

# datefmt_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getErrorMessage -- datefmt_get_error_message — Lee el último mensaje de error

### Descripción

Estilo orientado a objetos

public function IntlDateFormatter::getErrorMessage(): string

Estilo procedimental

function datefmt_get_error_message(IntlDateFormatter `$formatter`): string

Lee el mensaje de error de la última operación.

### Parámetros

`formatter`

  El recurso de formateador IntlDateFormatter.

### Valores devueltos

La descripción del último error.

### Ejemplos

Ejemplo #1 Ejemplo con datefmt_get_error_message()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $str = datefmt_format($fmt);

    printf(
        "Error : %s (%d)\n",
        datefmt_get_error_message($fmt),
        datefmt_get_error_code($fmt)
    );
    ?>

Ejemplo #2 Ejemplo orientado a objetos

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $str = $fmt->format(0);

    printf(
        "Error : %s (%d)\n",
        $fmt->getErrorMessage(),
        $fmt->getErrorCode()
    );

    ?>

El ejemplo anterior mostrará:

    Error : U_ZERO_ERROR (0)

### Ver también

- datefmt_get_error_code() - Lee el código de error de la última operación
- intl_get_error_code() - Lee el último código de error
- intl_is_failure() - Verifica si un código de error indica un fallo

# IntlDateFormatter::getLocale

# datefmt_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getLocale -- datefmt_get_locale — Lee la configuración local utilizada por el formateador

### Descripción

Estilo orientado a objetos

public function IntlDateFormatter::getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

Estilo procedimental

function datefmt_get_locale(IntlDateFormatter `$formatter`, int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

Lee la configuración local utilizada por el formateador.

### Parámetros

`formatter`

  El recurso de formateador IntlDateFormatter.

`type`

  Puede elegirse entre un valor válido o un valor literal de la configuración local (mediante las constantes `Locale::VALID_LOCALE` y `Locale::ACTUAL_LOCALE`, respectivamente). El valor por omisión es el valor literal.

### Valores devueltos

La configuración local de este formateador, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con datefmt_get_locale()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'La configuración local del formateador es : ' . datefmt_get_locale($fmt);
    echo 'El primer formato utilizado es ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'La configuración local del formateador es : ' . datefmt_get_locale($fmt);
    echo 'El segundo formato utilizado es ' . datefmt_format($fmt, 0);

    ?>

Ejemplo #2 Ejemplo orientado a objetos

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'La configuración local del formateador es : ' . $fmt->getLocale();
    echo 'El primer formato utilizado es ' . $fmt->format(0);

    $fmt = new IntlDateFormatter(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'La configuración local del formateador es : ' . $fmt->getLocale();
    echo 'El segundo formato utilizado es ' . $fmt->format(0);

    ?>

El ejemplo anterior mostrará:

    La configuración local del formateador es : en
    El primer formato utilizado es Wednesday, December 31, 1969 4:00:00 PM PT
    La configuración local del formateador es : de
    El segundo formato utilizado es Mittwoch, 31. Dezember 1969 16:00 Uhr GMT-08:00

### Ver también

- datefmt_create() - Crea un formateador de fecha

# IntlDateFormatter::getPattern

# datefmt_get_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getPattern -- datefmt_get_pattern — Lee el patrón utilizado por IntlDateFormatter

### Descripción

Estilo orientado a objetos

public function IntlDateFormatter::getPattern(): string|false

Estilo procedimental

function datefmt_get_pattern(IntlDateFormatter `$formatter`): string|false

Lee el patrón utilizado por el formateador.

### Parámetros

`formatter`

  El recurso de formateador IntlDateFormatter.

### Valores devueltos

El patrón utilizado para analizar y formar, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con datefmt_get_pattern()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'El patrón del formateador es: ' . datefmt_get_pattern($fmt);
    echo 'El primer resultado con el patrón es ' . datefmt_format($fmt, 0);
    datefmt_set_pattern($fmt,'yyyymmdd hh:mm:ss z');
    echo 'Ahora el patrón del formateador es: ' . datefmt_get_pattern($fmt);
    echo 'El segundo resultado con el patrón es ' . datefmt_format($fmt, 0);

    ?>

Ejemplo #2 Ejemplo orientado a objetos

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'El patrón del formateador es: ' . $fmt->getPattern();
    echo 'El primer resultado con el patrón es ' . $fmt->format(0);
    $fmt->setPattern('yyyymmdd hh:mm:ss z');
    echo 'Ahora el patrón del formateador es: ' . $fmt->getPattern();
    echo 'El segundo resultado con el patrón es ' . $fmt->format(0);
    ?>

El ejemplo anterior mostrará:

    El patrón del formateador es: MM/dd/yyyy
    El primer resultado con el patrón es 12/31/1969
    Ahora el patrón del formateador es: yyyymmdd hh:mm:ss z
    El segundo resultado con el patrón es 19690031 04:00:00 PST

### Ver también

- datefmt_set_pattern() - Configura el patrón utilizado por IntlDateFormatter
- datefmt_create() - Crea un formateador de fecha

# IntlDateFormatter::getTimeType

# datefmt_get_timetype

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getTimeType -- datefmt_get_timetype — Lee el tipo de tiempo para IntlDateFormatter

### Descripción

Estilo orientado a objetos

public function IntlDateFormatter::getTimeType(): int|false

Estilo procedimental

function datefmt_get_timetype(IntlDateFormatter `$formatter`): int|false

Devuelve el tipo de tiempo utilizado por el formateador.

### Parámetros

`formatter`

  El recurso del formateador IntlDateFormatter.

### Valores devueltos

El valor actual de tipo de fecha utilizado por el formateador, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con datefmt_get_timetype()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'El tipo de tiempo del formateador es : ' . datefmt_get_timetype($fmt);
    echo 'El primer resultado con timetype es ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::SHORT,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Ahora, el timetype del formateador es : ' . datefmt_get_timetype($fmt);
    echo 'El segundo resultado con timetype es ' . datefmt_format($fmt, 0);

    ?>

Ejemplo #2 Ejemplo orientado a objetos

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'El tipo de tiempo del formateador es : ' . $fmt->getTimeType();
    echo 'El primer resultado con timetype es ' . $fmt->format(0);

    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::SHORT,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Ahora, el timetype del formateador es : ' . $fmt->getTimeType();
    echo 'El segundo resultado con timetype es ' . $fmt->format(0);

    ?>

El ejemplo anterior mostrará:

    El tipo de tiempo del formateador es : 0
    El primer resultado con timetype es Wednesday, December 31, 1969 4:00:00 PM PT
    Ahora, el timetype del formateador es : 3
    El segundo resultado con timetype es Wednesday, December 31, 1969 4:00 PM

### Ver también

- datefmt_get_datetype() - Lee el tipo de fecha utilizado por IntlDateFormatter
- datefmt_create() - Crea un formateador de fecha

# IntlDateFormatter::getTimeZoneId

# datefmt_get_timezone_id

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getTimeZoneId -- datefmt_get_timezone_id — Lee el huso horario de IntlDateFormatter

### Descripción

Estilo orientado a objetos

public function IntlDateFormatter::getTimeZoneId(): string|false

Estilo procedimental

function datefmt_get_timezone_id(IntlDateFormatter `$formatter`): string|false

Lee el huso horario utilizado por IntlDateFormatter.

### Parámetros

`formatter`

  El recurso de formateador IntlDateFormatter.

### Valores devueltos

El identificador del huso horario utilizado por este formateador, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con datefmt_get_timezone_id()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'El timezone_id del formateador es:' . datefmt_get_timezone_id($fmt) . "\n";
    datefmt_set_timezone($fmt, 'Europe/Madrid');
    echo 'Ahora el timezone_id del formateador es:' . datefmt_get_timezone_id($fmt);

    ?>

Ejemplo #2 Ejemplo orientado a objetos

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'El timezone_id del formateador es:' . $fmt->getTimezoneId() . "\n";
    $fmt->setTimezone('Europe/Madrid');
    echo 'Ahora el timezone_id del formateador es:' . $fmt->getTimezoneId();

    ?>

El ejemplo anterior mostrará:

    El timezone_id del formateador es:America/Los_Angeles
    Ahora el timezone_id del formateador es:Europe/Madrid

### Ver también

- datefmt_set_timezone() - Define el formateador para el desplazamiento horario
- datefmt_create() - Crea un formateador de fecha

# IntlDateFormatter::getCalendarObject

# datefmt_get_calendar_object

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::getCalendarObject -- datefmt_get_calendar_object — Obtiene una copia del objeto formateador de calendario

### Descripción

Estilo orientado a objetos

public function IntlDateFormatter::getCalendarObject(): IntlCalendar|false|null

Estilo procedimental

function datefmt_get_calendar_object(IntlDateFormatter `$formatter`): IntlCalendar|false|null

Obtiene una copia del objeto calendario utilizado internamente por este formateador. Este calendario tendrá un tipo (como gregoriano, japonés, budista, islámico, etc.) y un desplazamiento horario que correspondan al tipo y al desplazamiento horario utilizados por el formateador. La fecha/hora del objeto no está especificada.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Una copia del objeto calendario interno utilizado por este formateador, o `null` si ninguno ha sido definido, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con IntlDateFormatter::getCalendarObject()

    <?php
    $formatter = IntlDateFormatter::create(
        "fr_FR@calendar=islamic",
        NULL,
        NULL,
        "GMT-01:00",
        IntlDateFormatter::TRADITIONAL
    );

    $cal = $formatter->getCalendarObject();

    var_dump(
        $cal->getType(),
        $cal->getTimeZone(),
        $cal->getLocale(Locale::VALID_LOCALE)
    );
    ?>

El ejemplo anterior mostrará:

    string(7) "islamic"
    object(IntlTimeZone)#3 (4) {
      ["valid"]=>
      bool(true)
      ["id"]=>
      string(9) "GMT-01:00"
      ["rawOffset"]=>
      int(-3600000)
      ["currentOffset"]=>
      int(-3600000)
    }
    string(5) "fr_FR"

### Ver también

- IntlDateFormatter::getCalendar() - Lee el calendario utilizado por el objeto IntlDateFormatter
- IntlDateFormatter::setCalendar() - Define el tipo de calendario utilizado por el formateador
- IntlCalendar

# IntlDateFormatter::getTimeZone

# datefmt_get_timezone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::getTimeZone -- datefmt_get_timezone — Obtiene el formateador del huso horario

### Descripción

Estilo orientado a objetos

public function IntlDateFormatter::getTimeZone(): IntlTimeZone|false

Estilo procedimental

function datefmt_get_timezone(IntlDateFormatter `$formatter`): IntlTimeZone|false

Devuelve un objeto IntlTimeZone que representa el huso horario utilizado por este objeto para formatear fechas y horas. Al formatear objetos IntlCalendar y DateTime con este IntlDateFormatter, el huso horario utilizado será devuelto por este método, y no aquel asociado con los objetos formateados.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El objeto IntlTimeZone asociado o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con IntlDateFormatter::getTimeZone()

    <?php

    $madrid = IntlDateFormatter::create(NULL, NULL, NULL, 'Europe/Madrid');
    $lisbon = IntlDateFormatter::create(NULL, NULL, NULL, 'Europe/Lisbon');

    var_dump($madrid->getTimezone());
    echo $madrid->getTimezone()->getDisplayName(
            false, IntlTimeZone::DISPLAY_GENERIC_LOCATION, "en_US"), "\n";
    echo $lisbon->getTimeZone()->getId(), "\n";
    // El identificador también puede ser obtenido con ->getTimezoneId()
    echo $lisbon->getTimeZoneId(), "\n";

El ejemplo anterior mostrará:

    object(IntlTimeZone)#4 (4) {
      ["valid"]=>
      bool(true)
      ["id"]=>
      string(13) "Europe/Madrid"
      ["rawOffset"]=>
      int(3600000)
      ["currentOffset"]=>
      int(7200000)
    }
    Spain Time
    Europe/Lisbon
    Europe/Lisbon

### Ver también

- IntlDateFormatter::getTimeZoneId() - Lee el huso horario de IntlDateFormatter
- IntlDateFormatter::setTimeZone() - Define el formateador para el desplazamiento horario
- IntlTimeZone

# IntlDateFormatter::isLenient

# datefmt_is_lenient

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::isLenient -- datefmt_is_lenient — Devuelve la severidad utilizada para IntlDateFormatter

### Descripción

Estilo orientado a objetos

public function IntlDateFormatter::isLenient(): bool

Estilo procedimental

function datefmt_is_lenient(IntlDateFormatter `$formatter`): bool

Verifica si el analizador es estricto o flexible al interpretar strings que no coinciden exactamente con el patrón buscado.

### Parámetros

`formatter`

  El recurso de formateador IntlDateFormatter.

### Valores devueltos

`true` si el analizador es flexible, `false` si el analizador es estricto. Por omisión, el analizador es flexible.

### Ejemplos

Ejemplo #1 Ejemplo con datefmt_is_lenient()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'dd/mm/yyyy'
    );
    echo 'El formateador es estricto : ';
    if ($fmt->isLenient()) {
        echo 'Sí';
    } else {
        echo 'No';
    }
    datefmt_parse($fmt, '35/13/1971');
    echo "\n Intento de análisis de la fecha '35/13/1971'.\nEl resultado es : " . datefmt_parse($fmt, '35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nError_msg es : " . intl_get_error_message();
        echo "\nError_code es : " . intl_get_error_code();
    }
    datefmt_set_lenient($fmt,false);
    echo 'Ahora, el formateador es estricto : ';
    if ($fmt->isLenient()) {
        echo 'Sí';
    } else {
        echo 'No';
    }
    datefmt_parse($fmt, '35/13/1971');
    echo "\n Intento de análisis de la fecha '35/13/1971'.\nEl resultado es : " . datefmt_parse($fmt, '35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nError_msg es : " . intl_get_error_message();
        echo "\nError_code es : " . intl_get_error_code();
    }

    ?>

Ejemplo #2 Ejemplo orientado a objetos

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        "dd/mm/yyyy"
    );
    echo "El formateador es estricto : ";
    if ($fmt->isLenient()) {
        echo 'Sí';
    } else {
        echo 'No';
    }
    $fmt->parse('35/13/1971');
    echo "\n Intento de análisis de la fecha '35/13/1971'.\nEl resultado es : " . $fmt->parse('35/13/1971');
    if (intl_get_error_code() != 0){
        echo "\nError_msg es : " . intl_get_error_message();
        echo "\nError_code es : " . intl_get_error_code();
    }

    $fmt->setLenient(FALSE);
    echo 'Ahora el formateador es estricto : ';
    if ($fmt->isLenient()) {
        echo 'Sí';
    } else {
        echo 'No';
    }
    $fmt->parse('35/13/1971');
    echo "\n Intento de análisis de la fecha '35/13/1971'.\nEl resultado es : " . $fmt->parse('35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nError_msg es : " . intl_get_error_message();
        echo "\nError_code es : " . intl_get_error_code();
    }

    ?>

El ejemplo anterior mostrará:

    El formateador es estricto : Sí
    Intento de análisis de la fecha '35/13/1971'.
    El resultado es : 34503180
    Ahora, el formateador es estricto : No
    Intento de análisis de la fecha '35/13/1971'.
    El resultado es :
    Error_msg es : Date parsing failed: U_PARSE_ERROR
    Error_code es : 9

### Ver también

- datefmt_set_lenient() - Configura la flexibilidad del analizador
- datefmt_create() - Crea un formateador de fecha

# IntlDateFormatter::localtime

# datefmt_localtime

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::localtime -- datefmt_localtime — Analiza una cadena y la convierte en tiempo

### Descripción

Estilo orientado a objetos

public function IntlDateFormatter::localtime(string `$string`, int `&$offset` = `null`): array|false

Estilo procedimental

function datefmt_localtime(IntlDateFormatter `$formatter`, string `$string`, int `&$offset` = `null`): array|false

Convierte la cadena $value en una fecha descompuesta (un array de campos), comenzando en la posición $parse_pos y consumiendo tantos caracteres como sea posible.

### Parámetros

`formatter`

  El recurso de formateador IntlDateFormatter.

`string`

  La cadena a convertir.

`offset`

  La posición desde la cual comenzar el análisis en el valor $value. Las posiciones comienzan en 0. Si no ocurre ningún error durante el análisis de $value, $parse_pos contendrá -1, y de lo contrario, contendrá la posición en la cual terminó el análisis (y ocurrió el error). Esta variable contendrá la posición de fin si el análisis falla. Si $parse_pos > strlen($value), el análisis falla inmediatamente.

### Valores devueltos

Un array de enteros compatible con localtime: contiene la hora en formato de 24 horas en el campo tm_hour, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con datefmt_localtime()

    <?php

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $arr = datefmt_localtime($fmt, 'Wednesday, December 31, 1969 at 4:00:00 PM Pacific Standard Time', $offset);
    echo 'Resultado del análisis ';
    if ($arr) {
        foreach ($arr as $key => $value) {
            echo "$key : $value , ";
        }
    }

    ?>

Ejemplo #2 Ejemplo orientado a objetos

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $arr = $fmt->localtime('Wednesday, December 31, 1969 at 4:00:00 PM Pacific Standard Time', $offset);
    echo 'Resultado del análisis ';
    if ($arr) {
        foreach ($arr as $key => $value) {
            echo "$key : $value , ";
        }
    }

    ?>

El ejemplo anterior mostrará:

    Resultado del análisis tm_sec : 0 , tm_min : 0 , tm_hour : 16 , tm_year : 69 ,
    tm_mday : 31 , tm_wday : 3 , tm_yday : 365 , tm_mon : 11 , tm_isdst : 0 ,

### Ver también

- datefmt_create() - Crea un formateador de fecha
- datefmt_format() - Formatea la fecha y la hora como string
- datefmt_parse() - Analiza una cadena hacia un timestamp
- datefmt_get_error_code() - Lee el código de error de la última operación
- datefmt_get_error_message() - Lee el último mensaje de error

# IntlDateFormatter::parse

# datefmt_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::parse -- datefmt_parse — Analiza una cadena hacia un timestamp

### Descripción

Estilo orientado a objetos

public function IntlDateFormatter::parse(string `$string`, int `&$offset` = `null`): int|float|false

Estilo procedimental

function datefmt_parse(IntlDateFormatter `$formatter`, string `$string`, int `&$offset` = `null`): int|float|false

Convierte `string` en un valor de tiempo, comenzando en `offset` y leyendo tantos caracteres como sea posible.

### Parámetros

`formatter`

  El recurso de formateador IntlDateFormatter.

`string`

  La cadena a convertir en tiempo.

`offset`

  La posición desde la cual comenzar el análisis en el valor `string`. Las posiciones comienzan en 0. Si no ocurre ningún error durante el análisis de `string`, `offset` contendrá -1, y de lo contrario, contendrá la posición en la cual el análisis terminó (y el error ocurrió). Esta variable contendrá la posición de fin si el análisis falla. Si `offset` > `strlen($string)`, el análisis falla inmediatamente.

### Valores devueltos

El valor del timestamp analizado o `false` si el valor no pudo ser analizado.

### Ejemplos

Ejemplo #1 Ejemplo orientado a objetos

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'El primer formato analizado es ' . $fmt->parse('Wednesday, December 20, 1989 4:00:00 PM PT');
    $fmt = new IntlDateFormatter(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    ?>

Ejemplo #2 Ejemplo con datefmt_parse()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'El primer formato analizado es ' . datefmt_parse($fmt, 'Wednesday, December 20, 1989 4:00:00 PM PT');
    $fmt = datefmt_create(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'El segundo formato analizado es ' . datefmt_parse($fmt, 'Mittwoch, 20. Dezember 1989 16:00 Uhr GMT-08:00');
    ?>

El ejemplo anterior mostrará:

    El primer formato analizado es 630201600
    El segundo formato analizado es 630201600

### Ver también

- datefmt_create() - Crea un formateador de fecha
- datefmt_format() - Formatea la fecha y la hora como string
- datefmt_localtime() - Analiza una cadena y la convierte en tiempo
- datefmt_get_error_code() - Lee el código de error de la última operación
- datefmt_get_error_message() - Lee el último mensaje de error

# IntlDateFormatter::parseToCalendar

(PHP 8 >= 8.4.0)

IntlDateFormatter::parseToCalendar — Analiza una cadena hacia un timestamp, actualizando un calendario abierto

### Descripción

public function IntlDateFormatter::parseToCalendar(string `$string`, int `&$offset` = `null`): int|float|false

Convierte `string` en un valor de tiempo incremental, comenzando en `offset` y leyendo tantos caracteres del valor de entrada como sea posible.

Este método se comporta como IntlDateFormatter::parse(), salvo que la zona horaria del formateador se actualiza según la información de zona horaria contenida en la cadena `string` analizada.

### Parámetros

`string`
  La cadena a convertir en un tiempo.
`offset`
  Posición en la que comenzar el análisis en `string` (basada en cero). Si no ocurre ningún error antes de que `string` sea consumida, `offset` contendrá -1; de lo contrario contendrá la posición en la que el análisis terminó (y se produjo el error). Esta variable contendrá la posición final si el análisis falla. Si `offset` > `strlen($string)`, el análisis falla inmediatamente.

### Valores devueltos

El timestamp del valor analizado, o `false` si el valor no se puede analizar.

### Ejemplos

Ejemplo #1 Ejemplo de IntlDateFormatter::parseToCalendar()

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo $fmt->parseToCalendar('Wednesday, December 20, 1989 at 4:00:00 PM Pacific Standard Time');
    ?>

El ejemplo anterior mostrará:

    630201600

### Ver también

- IntlDateFormatter::parse() - Analiza una cadena hacia un timestamp
- IntlDateFormatter::format() - Formatea la fecha y la hora como string
- IntlDateFormatter::getErrorCode() - Lee el código de error de la última operación
- IntlDateFormatter::getErrorMessage() - Lee el último mensaje de error

# IntlDateFormatter::setCalendar

# datefmt_set_calendar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::setCalendar -- datefmt_set_calendar — Define el tipo de calendario utilizado por el formateador

### Descripción

Estilo orientado a objetos

public function IntlDateFormatter::setCalendar(IntlCalendar|int|null `$calendar`): bool

Estilo procedimental

function datefmt_set_calendar(IntlDateFormatter `$formatter`, IntlCalendar|int|null `$calendar`): bool

Configura el calendario o el tipo de calendario a utilizar por el formateador.

### Parámetros

`formatter`

  El recurso de formateador IntlDateFormatter.

`calendar`

  Puede ser: el tipo de calendario a utilizar (por omisión, `IntlDateFormatter::GREGORIAN`, que también es utilizado si `null` es especificado) o un objeto IntlCalendar.

  Cualquier objeto IntlCalendar pasado será clonado; ninguna modificación será realizada sobre el objeto en argumento.

  El desplazamiento horario del formateador solo será conservado si un objeto IntlCalendar no es pasado, de lo contrario, el nuevo desplazamiento horario será el del objeto pasado.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL intl 3.0.0 | Se hace posible pasar un objeto IntlCalendar.

### Ejemplos

Ejemplo #1 Ejemplo con datefmt_set_calendar()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'El calendario del formateador es: ' . datefmt_get_calendar($fmt);
    datefmt_set_calendar($fmt, IntlDateFormatter::TRADITIONAL);
    echo 'El calendario es ahora: ' . datefmt_get_calendar($fmt);
    ?>

Ejemplo #2 Ejemplo orientado a objetos

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'El calendario del formateador es: ' . $fmt->getCalendar();
    $fmt->setCalendar(IntlDateFormatter::TRADITIONAL);
    echo 'El calendario es ahora: ' . $fmt->getCalendar();
    ?>

El ejemplo anterior mostrará:

    El calendario del formateador es: 1
    El calendario es ahora: 0

Ejemplo #3 Ejemplo con argumentos a IntlCalendar

    <?php
    $time = strtotime("2013-03-03 00:00:00 UTC");
    $formatter = IntlDateFormatter::create("en_US", NULL, NULL, "Europe/Amsterdam");

    echo "antes: ", $formatter->format($time), "\n";

    /* note que la configuración local del calendario no es utilizada! */
    $formatter->setCalendar(IntlCalendar::createInstance(
                   "America/New_York", "pt_PT@calendar=islamic"));

    echo "después:  ", $formatter->format($time), "\n";

El ejemplo anterior mostrará:

    antes: Sunday, March 3, 2013 at 1:00:00 AM Central European Standard Time
    después:  Saturday, Rabiʻ II 20, 1434 at 7:00:00 PM Eastern Standard Time

### Ver también

- datefmt_get_calendar() - Lee el calendario utilizado por el objeto IntlDateFormatter
- datefmt_get_calendar_object() - Obtiene una copia del objeto formateador de calendario
- datefmt_create() - Crea un formateador de fecha

# IntlDateFormatter::setLenient

# datefmt_set_lenient

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::setLenient -- datefmt_set_lenient — Configura la flexibilidad del analizador

### Descripción

Estilo orientado a objetos

public function IntlDateFormatter::setLenient(bool `$lenient`): void

Estilo procedimental

function datefmt_set_lenient(IntlDateFormatter `$formatter`, bool `$lenient`): void

Define si el analizador es estricto o flexible al interpretar strings que no coinciden exactamente con el patrón buscado. Activar la flexibilidad del analizador permite aceptar valores que podrían ser considerados erróneos por el analizador estricto. Los espacios, los caracteres desconocidos o las fechas inválidas no son aceptados.

### Parámetros

`formatter`

  El recurso de formateador IntlDateFormatter.

`lenient`

  Si el analizador es flexible o no, por defecto, vale `true` (flexible).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con datefmt_set_lenient()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'dd/MM/yyyy'
    );
    echo 'El formateador es flexible : ';
    if ($fmt->isLenient()) {
        echo 'Sí';
    } else {
        echo 'No';
    }
    datefmt_parse($fmt, '35/13/1971');
    echo "\nIntento de análisis de la fecha '35/13/1971'.\nEl resultado es : " . datefmt_parse($fmt, '35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nError_msg es : " . intl_get_error_message();
        echo "\nError_code es : " . intl_get_error_code();
    }
    datefmt_set_lenient($fmt, false);
    echo "\nAhora, el formateador es estricto : ";
    if ($fmt->isLenient()) {
        echo 'Sí';
    } else {
        echo 'No';
    }
    datefmt_parse($fmt, '35/13/1971');
    echo "\nIntento de análisis de la fecha '35/13/1971'.\nEl resultado es : " . datefmt_parse($fmt, '35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nError_msg es : ".intl_get_error_message();
        echo "\nError_code es : ".intl_get_error_code();
    }

    ?>

Ejemplo #2 Ejemplo orientado a objetos

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'dd/MM/yyyy'
    );
    echo 'El formateador es flexible : ';
    if ($fmt->isLenient()) {
        echo 'Sí';
    } else {
        echo 'No';
    }
    $fmt->parse('35/13/1971');
    echo "\n Intento de análisis de la fecha '35/13/1971'.\nEl resultado es : " . $fmt->parse('35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nError_msg es : " . intl_get_error_message();
        echo "\nError_code es : " . intl_get_error_code();
    }

    $fmt->setLenient(FALSE);
    echo "\nAhora, el formateador es estricto : ";
    if ($fmt->isLenient()) {
        echo 'Sí';
    } else {
        echo 'No';
    }
    $fmt->parse('35/13/1971');
    echo "\n Intento de análisis de la fecha '35/13/1971'.\nEl resultado es : " . $fmt->parse('35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nError_msg es : " . intl_get_error_message();
        echo "\nError_code es : " . intl_get_error_code();
    }

    ?>

El ejemplo anterior mostrará:

    El formateador es flexible : No
    Intento de análisis de la fecha '35/13/1971'.
    El resultado es : 66038400
    Ahora, el formateador es estricto : Sí
    Intento de análisis de la fecha '35/13/1971'.
    El resultado es : Error_msg es : Date parsing failed: U_PARSE_ERROR Error_code es : 9

### Ver también

- datefmt_is_lenient() - Devuelve la severidad utilizada para IntlDateFormatter
- datefmt_create() - Crea un formateador de fecha

# IntlDateFormatter::setPattern

# datefmt_set_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::setPattern -- datefmt_set_pattern — Configura el patrón utilizado por IntlDateFormatter

### Descripción

Estilo orientado a objetos

public function IntlDateFormatter::setPattern(string `$pattern`): bool

Estilo procedimental

function datefmt_set_pattern(IntlDateFormatter `$formatter`, string `$pattern`): bool

Configura el patrón utilizado por IntlDateFormatter.

### Parámetros

`formatter`

  El recurso de formateador IntlDateFormatter.

`pattern`

  El nuevo patrón a utilizar. Los patrones posibles están documentados en » https://unicode-org.github.io/icu/userguide/format_parse/datetime/.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error. Un formato incorrecto de la cadena es generalmente la causa del fallo de esta función.

### Ejemplos

Ejemplo #1 Ejemplo con datefmt_get_pattern()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'El patrón del formateador es: ', datefmt_get_pattern($fmt), PHP_EOL;
    echo 'La primera salida formateada con el patrón es ', datefmt_format($fmt, 0), PHP_EOL;
    datefmt_set_pattern($fmt, 'yyyyMMdd hh:mm:ss z');
    echo 'Ahora el patrón del formateador es: ', datefmt_get_pattern($fmt), PHP_EOL;
    echo 'La segunda salida formateada con el patrón es ', datefmt_format($fmt, 0), PHP_EOL;
    ?>

Ejemplo #2 Ejemplo orientado a objetos

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'El patrón del formateador es: ', $fmt->getPattern(), PHP_EOL;
    echo 'La primera salida formateada es ', $fmt->format(0), PHP_EOL;
    $fmt->setPattern('yyyyMMdd hh:mm:ss z');
    echo 'Ahora el patrón del formateador es: ', $fmt->getPattern(), PHP_EOL;
    echo 'La segunda salida formateada es ', $fmt->format(0), PHP_EOL;
    ?>

El ejemplo anterior mostrará:

    El patrón del formateador es: MM/dd/yyyy
    La primera salida formateada es 12/31/1969
    Ahora el patrón del formateador es: yyyyMMdd hh:mm:ss z
    La segunda salida formateada es 19691231 04:00:00 PST

### Ver también

- datefmt_get_pattern() - Lee el patrón utilizado por IntlDateFormatter
- datefmt_create() - Crea un formateador de fecha

# IntlDateFormatter::setTimeZone

# datefmt_set_timezone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::setTimeZone -- datefmt_set_timezone — Define el formateador para el desplazamiento horario

### Descripción

Estilo orientado a objetos

public function IntlDateFormatter::setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

Estilo procedimental

function datefmt_set_timezone(IntlDateFormatter `$formatter`, IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

Define el desplazamiento horario utilizado por el objeto IntlDateFormatter.

### Parámetros

`formatter`

  El formateador de recursos.

`timezone`

  El desplazamiento horario a utilizar con este formateador. Puede ser especificado mediante los siguientes formatos:

  - `null`, en cuyo caso se usará la zona horaria predeterminada, tal como está especificada en el ajuste ini date.timezone o a través de la función date_default_timezone_set() y como es devuelto por date_default_timezone_get().

  - Un IntlTimeZone, que se usará directamente.

  - Un DateTimeZone. Su identificador será extraido y se creará un objeto de zona horaria de ICU; la zona horaria será proporcionada por la base de datos de ICU, no por la de PHP.

  - Un string, que debería ser un identificador de zona horaria de ICU válido. Véase IntlTimeZone::createTimeZoneIDEnumeration(). Los índices puros como `"GMT+08:30"` también se aceptan.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Esta función devuelve ahora `true` en caso de éxito; previamente devolvía `null`.

### Ejemplos

Ejemplo #1 Ejemplo con IntlDateFormatter::setTimeZone()

    <?php
    ini_set('date.timezone', 'Europe/Amsterdam');

    $formatter = IntlDateFormatter::create(NULL, NULL, NULL, "UTC");

    $formatter->setTimeZone(NULL);
    echo "NULL\n    ", $formatter->getTimeZone()->getId(), "\n";

    $formatter->setTimeZone(IntlTimeZone::createTimeZone('Europe/Lisbon'));
    echo "IntlTimeZone\n    ", $formatter->getTimeZone()->getId(), "\n";

    $formatter->setTimeZone(new DateTimeZone('Europe/Paris'));
    echo "DateTimeZone\n    ", $formatter->getTimeZone()->getId(), "\n";

    $formatter->setTimeZone('Europe/Rome');
    echo "String\n    ", $formatter->getTimeZone()->getId(), "\n";

    $formatter->setTimeZone('GMT+00:30');
    print_r($formatter->getTimeZone());

El ejemplo anterior mostrará:

    NULL
        Europe/Amsterdam
    IntlTimeZone
        Europe/Lisbon
    DateTimeZone
        Europe/Paris
    String
        Europe/Rome
    IntlTimeZone Object
    (
        [valid] => 1
        [id] => GMT+00:30
        [rawOffset] => 1800000
        [currentOffset] => 1800000
    )

### Ver también

- IntlDateFormatter::getTimeZone() - Obtiene el formateador del huso horario

## Tabla de contenidos

- IntlDateFormatter::create — Crea un formateador de fecha
- IntlDateFormatter::format — Formatea la fecha y la hora como string
- IntlDateFormatter::formatObject — Formatea un objeto
- IntlDateFormatter::getCalendar — Lee el calendario utilizado por el objeto IntlDateFormatter
- IntlDateFormatter::getDateType — Lee el tipo de fecha utilizado por IntlDateFormatter
- IntlDateFormatter::getErrorCode — Lee el código de error de la última operación
- IntlDateFormatter::getErrorMessage — Lee el último mensaje de error
- IntlDateFormatter::getLocale — Lee la configuración local utilizada por el formateador
- IntlDateFormatter::getPattern — Lee el patrón utilizado por IntlDateFormatter
- IntlDateFormatter::getTimeType — Lee el tipo de tiempo para IntlDateFormatter
- IntlDateFormatter::getTimeZoneId — Lee el huso horario de IntlDateFormatter
- IntlDateFormatter::getCalendarObject — Obtiene una copia del objeto formateador de calendario
- IntlDateFormatter::getTimeZone — Obtiene el formateador del huso horario
- IntlDateFormatter::isLenient — Devuelve la severidad utilizada para IntlDateFormatter
- IntlDateFormatter::localtime — Analiza una cadena y la convierte en tiempo
- IntlDateFormatter::parse — Analiza una cadena hacia un timestamp
- IntlDateFormatter::parseToCalendar — Analiza una cadena hacia un timestamp, actualizando un calendario abierto
- IntlDateFormatter::setCalendar — Define el tipo de calendario utilizado por el formateador
- IntlDateFormatter::setLenient — Configura la flexibilidad del analizador
- IntlDateFormatter::setPattern — Configura el patrón utilizado por IntlDateFormatter
- IntlDateFormatter::setTimeZone — Define el formateador para el desplazamiento horario

# La clase ResourceBundle

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

## Introducción

Las aplicaciones localizadas suelen necesitar manipular datos que deben ser personalizados según una configuración local específica, por ejemplo: mensajes, etiquetas, strings de formato. ICU permite definir recursos que la aplicación podrá cargar con una configuración local una vez para todas: todos los accesos posteriores se realizarán mediante una interfaz única no dependiente de la configuración local considerada.

Esta clase permite el acceso a los archivos de datos de ICU. Estos archivos representan arrays binarios que ICU utiliza para almacenar los datos localizados.

Los bundles de recursos ICU soportan recursos simples y complejos. Los recursos complejos son contenedores que pueden ser indexados numéricamente o literalmente (como los arrays PHP). Los recursos simples, en cambio, pueden ser de tipo string, integer, binario o array numérico.

ResourceBundle soporta el acceso directo a los datos mediante la sintaxis de arrays así como la iteración gracias a foreach. Estas posibilidades también existen mediante los métodos. El resultado será un valor PHP para los recursos simples, o un objeto ResourceBundle para los recursos complejos. Los recursos son de solo lectura.

## Sinopsis de la Clase

class ResourceBundle implements IteratorAggregate, Countable {
/* Métodos */
public function __construct(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`)
public function count(): int
public static function create(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`): ?ResourceBundle
public function get(string|int `$index`, bool `$fallback` = `true`): ResourceBundle|array|string|int|null
public function getErrorCode(): int
public function getErrorMessage(): string
public static function getLocales(string `$bundle`): array|false
}

## Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | La clase ResourceBundle ahora implementa IteratorAggregate. Anteriormente, solo Traversable estaba implementada.
7.4.0 | La clase ResourceBundle ahora implementa Countable.

## Ver también

- » Configuración de recursos ICU
- » ICU Data

# ResourceBundle::count

# resourcebundle_count

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::count -- resourcebundle_count — Obtiene el número de elementos en el paquete

### Descripción

Estilo orientado a objetos

public function ResourceBundle::count(): int

Estilo procedimental

function resourcebundle_count(ResourceBundle `$bundle`): int

Obtiene el número de elementos en el paquete.

### Parámetros

`bundle`

  Un objeto ResourceBundle.

### Valores devueltos

Devuelve el número de elementos del paquete.

### Ejemplos

Ejemplo #1 Ejemplo con resourcebundle_count()

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo resourcebundle_count($r);
    ?>

Ejemplo #2 Ejemplo orientado a objetos

    <?php
    $r = new ResourceBundle( 'es', "/usr/share/data/myapp");
    echo $r->count();
    ?>

El ejemplo anterior mostrará:

    42

### Ver también

- resourcebundle_get() - Recupera los datos desde el haz

# ResourceBundle::create

# resourcebundle_create

# ResourceBundle::__construct

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::create -- resourcebundle_create -- ResourceBundle::__construct — Crea un recurso que representa un haz

### Descripción

Estilo orientado a objetos (método)

public static function ResourceBundle::create(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`): ?ResourceBundle

Estilo procedimental

function resourcebundle_create(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`): ?ResourceBundle

Estilo orientado a objetos (constructor) :

public function ResourceBundle::__construct(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`)

Crea un recurso que representa un haz.

### Parámetros

`locale`

  Configuración local desde la cual deben cargarse los recursos (nombre de la configuración local, es decir, en_CA).

`bundle`

  El directorio donde se almacenan los datos o el nombre del archivo .dat.

`fallback`

  Si la configuración local debe coincidir exactamente o si se permite el fallback a la configuración local padre.

### Valores devueltos

Devuelve un objeto ResourceBundle o `null` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con resourcebundle_create()

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo $r['teststring'];
    ?>

Ejemplo #2 Ejemplo con ResourceBundle::create()

    <?php
    $r = ResourceBundle::create( 'es', "/usr/share/data/myapp");
    echo $r['teststring'];
    ?>

El ejemplo anterior mostrará:

    ¡Hola, mundo!

### Ver también

- resourcebundle_get() - Recupera los datos desde el haz

# ResourceBundle::get

# resourcebundle_get

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::get -- resourcebundle_get — Recupera los datos desde el haz

### Descripción

Estilo orientado a objetos

public function ResourceBundle::get(string|int `$index`, bool `$fallback` = `true`): ResourceBundle|array|string|int|null

Estilo procedimental

function resourcebundle_get(ResourceBundle `$bundle`, string|int `$index`, bool `$fallback` = `true`): ResourceBundle|array|string|int|null

Recupera los datos desde el haz mediante el índice o la clave.

### Parámetros

`bundle`

  Un objeto ResourceBundle.

`index`

  El índice de los datos; puede ser un string o un integer.

`fallback`

  Las configuraciones regionales deben coincidir exactamente o se permite el retorno a las configuraciones regionales padres.

### Valores devueltos

Devuelve los datos situados en un índice dado o `null` si ocurre un error. Las cadenas de caracteres, los enteros y los datos binarios son devueltos en sus formas correspondientes en tipos PHP; los arrays de enteros son devueltos en forma de array PHP. Los tipos complejos son devueltos en forma de objeto ResourceBundle.

### Errores/Excepciones

Se lanza una TypeError si el tipo del desplazamiento es inválido.

Se lanza una ValueError si `index` es un string y está vacío o es un int y no puede ser contenido en un entero de 32 bits.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Se lanza una TypeError si el tipo del desplazamiento es inválido. Se lanza una ValueError si `index` es un string y está vacío o es un int y no puede ser contenido en un entero de 32 bits.

### Ejemplos

Ejemplo #1 Ejemplo con resourcebundle_get()

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo resourcebundle_get($r, 'somestring');
    ?>

Ejemplo #2 Ejemplo orientado a objetos

    <?php
    $r = new ResourceBundle( 'es', "/usr/share/data/myapp");
    echo $r->get('somestring');
    ?>

El ejemplo anterior mostrará:

    ?Hola, mundo!

### Ver también

- resourcebundle_count() - Obtiene el número de elementos en el paquete

# ResourceBundle::getErrorCode

# resourcebundle_get_error_code

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::getErrorCode -- resourcebundle_get_error_code — Recupera el último código de error del haz

### Descripción

Estilo orientado a objetos

public function ResourceBundle::getErrorCode(): int

Estilo procedimental

function resourcebundle_get_error_code(ResourceBundle `$bundle`): int

Recupera el último código de error desde la última función ejecutada sobre el objeto que representa el haz.

### Parámetros

`bundle`

  Un objeto ResourceBundle.

### Valores devueltos

Devuelve el código de error desde la última llamada al objeto que representa el haz.

### Ejemplos

Ejemplo #1 Ejemplo con resourcebundle_get_error_code()

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo $r['somestring'];
    if(intl_is_failure(resourcebundle_get_error_code($r))) {
        report_error("Error en el haz");
    }
    ?>

Ejemplo #2 Ejemplo orientado a objetos

    <?php
    $r = new ResourceBundle( 'es', "/usr/share/data/myapp");
    echo $r['somestring'];
    if(intl_is_failure(ResourceBundle::getErrorCode($r))) {
        report_error("Error en el haz");
    }
    ?>

### Ver también

- resourcebundle_get_error_message() - Recupera el último mensaje de error desde el haz
- intl_get_error_code() - Lee el último código de error
- intl_is_failure() - Verifica si un código de error indica un fallo

# ResourceBundle::getErrorMessage

# resourcebundle_get_error_message

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::getErrorMessage -- resourcebundle_get_error_message — Recupera el último mensaje de error desde el haz

### Descripción

Estilo orientado a objetos

public function ResourceBundle::getErrorMessage(): string

Estilo procedimental

function resourcebundle_get_error_message(ResourceBundle `$bundle`): string

Recupera el mensaje de error desde la última función ejecutada sobre el objeto del haz.

### Parámetros

`bundle`

  Un objeto ResourceBundle.

### Valores devueltos

Devuelve el mensaje de error desde la última llamada sobre el objeto del haz.

### Ejemplos

Ejemplo #1 Ejemplo con resourcebundle_get_error_message()

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo $r['somestring'];
    if(intl_is_failure(resourcebundle_get_error_code($r))) {
        report_error("Error en el haz : ".resourcebundle_get_error_message($r));
    }
    ?>

Ejemplo #2 Ejemplo orientado a objetos

    <?php
    $r = new ResourceBundle( 'es', "/usr/share/data/myapp");
    echo $r['somestring'];
    if(intl_is_failure(ResourceBundle::getErrorCode($r))) {
        report_error("Error en el haz : ".ResourceBundle::getErrorMessage($r));
    }
    ?>

### Ver también

- resourcebundle_get_error_code() - Recupera el último código de error del haz
- intl_get_error_code() - Lee el último código de error
- intl_is_failure() - Verifica si un código de error indica un fallo

# ResourceBundle::getLocales

# resourcebundle_locales

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::getLocales -- resourcebundle_locales — Obtiene las configuraciones locales admitidas

### Descripción

Estilo orientado a objetos

public static function ResourceBundle::getLocales(string `$bundle`): array|false

Estilo procedimental

function resourcebundle_locales(string `$bundle`): array|false

Obtiene la lista de configuraciones locales desde el nombre ResourceBundle.

### Parámetros

`bundle`

  Ruta para ResourceBundle desde la cual se obtienen las configuraciones locales disponibles, o una cadena vacía para la lista de configuraciones locales por omisión.

### Valores devueltos

Devuelve la lista de configuraciones locales admitidas por este paquete, o `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con resourcebundle_locales()

    <?php
    $bundle = "/user/share/data/myapp";
    echo join(PHP_EOL, resourcebundle_locales($bundle));
    ?>

Resultado del ejemplo anterior es similar a:

    es
    root

Ejemplo #2 Ejemplo orientado a objetos

    <?php
    $bundle = "/usr/share/data/myapp";
    $r = new ResourceBundle( 'es', $bundle);
    echo join("\n", $r->getLocales($bundle));
    ?>

Resultado del ejemplo anterior es similar a:

    es
    root

### Ver también

- resourcebundle_get() - Recupera los datos desde el haz

## Tabla de contenidos

- ResourceBundle::count — Obtiene el número de elementos en el paquete
- ResourceBundle::create — Crea un recurso que representa un haz
- ResourceBundle::get — Recupera los datos desde el haz
- ResourceBundle::getErrorCode — Recupera el último código de error del haz
- ResourceBundle::getErrorMessage — Recupera el último mensaje de error desde el haz
- ResourceBundle::getLocales — Obtiene las configuraciones locales admitidas

# La clase Spoofchecker

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

## Introducción

Esta clase se proporciona porque Unicode contiene un gran número de caracteres y incorpora los diversos sistemas de escritura del mundo, y su uso incorrecto puede exponer programas o sistemas a posibles ataques de seguridad mediante la similitud de caracteres.

Los métodos proporcionados permiten verificar si un string individual es susceptible de ser una tentativa de engaño al lector (`detección de engaño`), como en "pаypаl" escrito con un carácter 'а' cirílico.

## Sinopsis de la Clase

class Spoofchecker {
/* Constantes */
public const int SINGLE_SCRIPT_CONFUSABLE;
public const int MIXED_SCRIPT_CONFUSABLE;
public const int WHOLE_SCRIPT_CONFUSABLE;
public const int ANY_CASE;
public const int SINGLE_SCRIPT;
public const int INVISIBLE;
public const int CHAR_LIMIT;
public const int ASCII;
public const int HIGHLY_RESTRICTIVE;
public const int MODERATELY_RESTRICTIVE;
public const int MINIMALLY_RESTRICTIVE;
public const int UNRESTRICTIVE;
public const int SINGLE_SCRIPT_RESTRICTIVE;
public const int MIXED_NUMBERS;
public const int HIDDEN_OVERLAY;
public const int IGNORE_SPACE;
public const int CASE_INSENSITIVE;
public const int ADD_CASE_MAPPINGS;
public const int SIMPLE_CASE_INSENSITIVE;
/* Métodos */
public function __construct()
public function areConfusable(string `$string1`, string `$string2`, int `&$errorCode` = `null`): bool
public function isSuspicious(string `$string`, int `&$errorCode` = `null`): bool
public function setAllowedChars(string `$pattern`, int `$patternOptions` = 0): void
public function setAllowedLocales(string `$locales`): void
public function setChecks(int `$checks`): void
public function setRestrictionLevel(int `$level`): void
}

## Constantes predefinidas

`Spoofchecker::SINGLE_SCRIPT_CONFUSABLE` int

`Spoofchecker::MIXED_SCRIPT_CONFUSABLE` int

`Spoofchecker::WHOLE_SCRIPT_CONFUSABLE` int

`Spoofchecker::ANY_CASE` int

`Spoofchecker::SINGLE_SCRIPT` int

`Spoofchecker::INVISIBLE` int

`Spoofchecker::CHAR_LIMIT` int

`Spoofchecker::ASCII` int

`Spoofchecker::HIGHLY_RESTRICTIVE` int

`Spoofchecker::MODERATELY_RESTRICTIVE` int

`Spoofchecker::MINIMALLY_RESTRICTIVE` int

`Spoofchecker::UNRESTRICTIVE` int

`Spoofchecker::SINGLE_SCRIPT_RESTRICTIVE` int

`Spoofchecker::MIXED_NUMBERS` int

`Spoofchecker::HIDDEN_OVERLAY` int

`Spoofchecker::IGNORE_SPACE` int

`Spoofchecker::CASE_INSENSITIVE` int
  Activa la correspondencia insensible a mayúsculas/minúsculas
`Spoofchecker::ADD_CASE_MAPPINGS` int

  Añade todas las correspondencias de mayúsculas/minúsculas para cada elemento del conjunto

`Spoofchecker::SIMPLE_CASE_INSENSITIVE` int
  Activa la correspondencia insensible a mayúsculas/minúsculas

## Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Se añadieron `Spoofchecker::IGNORE_SPACE`, `Spoofchecker::CASE_INSENSITIVE`, `Spoofchecker::ADD_CASE_MAPPINGS`, `Spoofchecker::SIMPLE_CASE_INSENSITIVE`.
8.4.0 | Las constantes de clase ahora están tipadas.
7.3.0 | Las constantes de clase utilizadas por Spoofchecker::setRestrictionLevel() como `Spoofchecker::ASCII`, `Spoofchecker::HIGHLY_RESTRICTIVE`, `Spoofchecker::MODERATELY_RESTRICTIVE`, `Spoofchecker::MINIMALLY_RESTRICTIVE`, `Spoofchecker::UNRESTRICTIVE`, `Spoofchecker::SINGLE_SCRIPT_RESTRICTIVE` han sido añadidas.

# Spoofchecker::areConfusable

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::areConfusable — Verifica si los strings dados pueden ser confundidos

### Descripción

public function Spoofchecker::areConfusable(string `$string1`, string `$string2`, int `&$errorCode` = `null`): bool

Se verifica si dos strings dados pueden ser fácilmente confundidos.

### Parámetros

`string1`

  Primer string a verificar.

`string2`

  Segundo string a verificar.

`errorCode`

  Esta variable es definida por referencia a un int que contiene un error, si es que hubo alguno.

### Valores devueltos

Retorna `true` si los dos strings dados pueden ser confundidos, y `false` en caso contrario.

### Ejemplos

Ejemplo #1 Ejemplo Spoofchecker::areConfusable()

    <?php
    $checker = new Spoofchecker();

    $checker->areConfusable('google.com', 'goog1e.com'); // true
    // La "l" minúscula puede ser confundida con el número uno

    $checker->areConfusable('google.com', 'g00g1e.com'); // false
    // Cero (0) no puede ser fácilmente confundido con la letra "o"

# Spoofchecker::__construct

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

Spoofchecker::__construct — Constructor

### Descripción

public function Spoofchecker::__construct()

Se crea una nueva instancia de Spoofchecker.

### Parámetros

Esta función no contiene ningún parámetro.

# Spoofchecker::isSuspicious

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::isSuspicious — Verifica si un texto contiene caracteres sospechosos

### Descripción

public function Spoofchecker::isSuspicious(string `$string`, int `&$errorCode` = `null`): bool

Verifica si el string dado contiene caracteres sospechosos como letras que son casi idénticas visualmente, pero son caracteres Unicode de diferentes conjuntos.

### Parámetros

`string`

  String a probar.

`errorCode`

  Esta variable se define por referencia a un int que contiene un error, si lo hubiera.

### Valores devueltos

Devuelve `true` si hay caracteres sospechosos, y `false` en caso contrario.

### Ejemplos

Ejemplo #1 Ejemplo Spoofchecker::isSuspicious()

    <?php
    $checker = new Spoofchecker();

    $checker->isSuspicious('google.com'); // FALSE: solo caracteres ASCII

    $checker->isSuspicious('Рaypal.com'); // TRUE
    // La primera letra es Cirílico, no una "P" latina

# Spoofchecker::setAllowedChars

(PHP 8 >= 8.4.0)

Spoofchecker::setAllowedChars — Define el conjunto de caracteres permitidos al ejecutar las comprobaciones

### Descripción

public function Spoofchecker::setAllowedChars(string `$pattern`, int `$patternOptions` = 0): void

Restringe los caracteres que las comprobaciones posteriores consideran aceptables al conjunto descrito por `pattern`. Cualquier carácter fuera de este conjunto provoca que Spoofchecker::isSuspicious() reporte un resultado.

### Parámetros

`pattern`
  Un conjunto de caracteres descrito como un patrón `UnicodeSet`, es decir, una clase de caracteres al estilo de las expresiones regulares. Debe comenzar con `[` y terminar con `]`, por ejemplo `[a-z0-9]`.
`patternOptions`
  Una máscara de bits que controla cómo se interpreta `pattern`. Debe ser `0`, o `Spoofchecker::IGNORE_SPACE` por sí solo o combinado con exactamente uno de `Spoofchecker::CASE_INSENSITIVE`, `Spoofchecker::ADD_CASE_MAPPINGS` o `Spoofchecker::SIMPLE_CASE_INSENSITIVE`.

### Valores devueltos

No se devuelve ningún valor.

### Errores/Excepciones

Lanza un ValueError si `pattern` no es un patrón de conjunto de caracteres válido, o si `patternOptions` no es una combinación de opciones válida.

### Ejemplos

Ejemplo #1 Ejemplo de Spoofchecker::setAllowedChars()

    <?php
    $checker = new Spoofchecker();
    $checker->setAllowedChars('[a-z0-9]');

    var_dump($checker->isSuspicious('hello'));
    var_dump($checker->isSuspicious('héllo'));
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(true)

### Ver también

- Spoofchecker::setAllowedLocales() - Locales a utilizar durante la verificación
- Spoofchecker::isSuspicious() - Verifica si un texto contiene caracteres sospechosos

# Spoofchecker::setAllowedLocales

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::setAllowedLocales — Locales a utilizar durante la verificación

### Descripción

public function Spoofchecker::setAllowedLocales(string `$locales`): void

Este método permite especificar las locales que deben ser consideradas válidas durante la verificación.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`locales`

  Un string que contiene las locales permitidas, separadas por comas.

### Valores devueltos

Este método no devuelve ningún valor.

# Spoofchecker::setChecks

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::setChecks — Especifica las verificaciones a realizar

### Descripción

public function Spoofchecker::setChecks(int `$checks`): void

Define los controles que serán realizados por SpoofChecker::isSuspicious().

### Parámetros

`checks`

  Los controles que serán realizados por SpoofChecker::isSuspicious(). Una máscara de bits de `Spoofchecker::SINGLE_SCRIPT_CONFUSABLE`, `Spoofchecker::MIXED_SCRIPT_CONFUSABLE`, `Spoofchecker::WHOLE_SCRIPT_CONFUSABLE`, `Spoofchecker::ANY_CASE`, `Spoofchecker::SINGLE_SCRIPT`, `Spoofchecker::INVISIBLE` o `Spoofchecker::CHAR_LIMIT`. Por omisión, todas las verificaciones a partir de ICU 58; antes de esta versión, `Spoofchecker::SINGLE_SCRIPT` estaba excluido.

### Valores devueltos

No se retorna ningún valor.

# Spoofchecker::setRestrictionLevel

(PHP 7 >= 7.3.0, PHP 8)

Spoofchecker::setRestrictionLevel — Establece el nivel de restricción

### Descripción

public function Spoofchecker::setRestrictionLevel(int `$level`): void

Establece el nivel de restricción de SpoofChecker::isSuspicious().

### Parámetros

`level`

  El nivel de restricción de SpoofChecker::isSuspicious(). Uno de los siguientes: `Spoofchecker::ASCII`, `Spoofchecker::SINGLE_SCRIPT_RESTRICTIVE`, `Spoofchecker::HIGHLY_RESTRICTIVE`, `Spoofchecker::MODERATELY_RESTRICTIVE`, `Spoofchecker::MINIMALLY_RESTRICTIVE`, o `Spoofchecker::UNRESTRICTIVE`. Por omisión `Spoofchecker::HIGHLY_RESTRICTIVE`.

### Valores devueltos

No se retorna ningún valor.

## Tabla de contenidos

- Spoofchecker::areConfusable — Verifica si los strings dados pueden ser confundidos
- Spoofchecker::__construct — Constructor
- Spoofchecker::isSuspicious — Verifica si un texto contiene caracteres sospechosos
- Spoofchecker::setAllowedChars — Define el conjunto de caracteres permitidos al ejecutar las comprobaciones
- Spoofchecker::setAllowedLocales — Locales a utilizar durante la verificación
- Spoofchecker::setChecks — Especifica las verificaciones a realizar
- Spoofchecker::setRestrictionLevel — Establece el nivel de restricción

# La clase Transliterator

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

## Introducción

La clase Transliterator proporciona la transliteración de los strings.

## Sinopsis de la Clase

class Transliterator {
/* Constantes */
public const int FORWARD;
public const int REVERSE;
/* Propiedades */
public readonly string $id;
/* Métodos */
final private function __construct()
public static function create(string `$id`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator
public static function createFromRules(string `$rules`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator
public function createInverse(): ?Transliterator
public function getErrorCode(): int
public function getErrorMessage(): string
public static function listIDs(): array|false
public function transliterate(string `$string`, int `$start` = 0, int `$end` = -1): string|false
}

## Propiedades

id

## Constantes predefinidas

`Transliterator::FORWARD` int

`Transliterator::REVERSE` int

## Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Las constantes de clase ahora están tipadas.
8.2.0 | La propiedad id ahora es readonly.

# Transliterator::__construct

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::__construct — Constructor privado para prohibir la instanciación

### Descripción

final private function Transliterator::__construct()

Este método no debe ser llamado. Su único propósito es prohibir la instanciación con el operador new.

Utilícense los métodos factorizados Transliterator::create() y Transliterator::createFromRules() en su lugar.

### Parámetros

Esta función no contiene ningún parámetro.

### Ver también

- Transliterator::create() - Crea un Transliterator
- Transliterator::createFromRules() - Crea un transliterador desde reglas

# Transliterator::create

# transliterator_create

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::create -- transliterator_create — Crea un Transliterator

### Descripción

Estilo orientado a objetos

public static function Transliterator::create(string `$id`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

Estilo procedimental

function transliterator_create(string `$id`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

Abre un Transliterator por su identificador.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`id`

  El identificador. Una lista de todos los identificadores transliterator registrados puede ser encontrada utilizando el método Transliterator::listIDs().

`direction`

  La dirección, por omisión Transliterator::FORWARD. Puede ser igualmente definido como Transliterator::REVERSE.

### Valores devueltos

Devuelve un objeto Transliterator en caso de éxito, o `null` si ocurre un error.

### Ver también

- Transliterator::getErrorMessage() - Obtiene el último mensaje de error
- Transliterator::__construct() - Constructor privado para prohibir la instanciación

# Transliterator::createFromRules

# transliterator_create_from_rules

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::createFromRules -- transliterator_create_from_rules — Crea un transliterador desde reglas

### Descripción

Estilo orientado a objetos

public static function Transliterator::createFromRules(string `$rules`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

Estilo procedimental

function transliterator_create_from_rules(string `$rules`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

Crea un transliterador desde reglas.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`rules`

  Las reglas como se definen en Transform Rules Syntax de UTS #35 : Unicode LDML.

`direction`

  La dirección, por omisión Transliterator::FORWARD. Puede ser también definido como Transliterator::REVERSE.

### Valores devueltos

Devuelve un objeto Transliterator en caso de éxito, o `null` si ocurre un error.

### Ver también

- Transliterator::getErrorMessage() - Obtiene el último mensaje de error
- Transliterator::create() - Crea un Transliterator

# Transliterator::createInverse

# transliterator_create_inverse

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::createInverse -- transliterator_create_inverse — Crea un transliterador inverso

### Descripción

Estilo orientado a objetos

public function Transliterator::createInverse(): ?Transliterator

Estilo procedimental

function transliterator_create_inverse(Transliterator `$transliterator`): ?Transliterator

Crea un transliterador inverso.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un objeto Transliterator en caso de éxito, o `null` si ocurre un error.

### Ver también

- Transliterator::getErrorMessage() - Obtiene el último mensaje de error
- Transliterator::create() - Crea un Transliterator

# Transliterator::getErrorCode

# transliterator_get_error_code

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::getErrorCode -- transliterator_get_error_code — Obtiene el último código de error

### Descripción

Estilo orientado a objetos

public function Transliterator::getErrorCode(): int

Estilo procedimental

function transliterator_get_error_code(Transliterator `$transliterator`): int

Obtiene el último código de error desde este transliterador.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`transliterator`

### Valores devueltos

El código de error en caso de éxito, o `false` si no existe o si ocurre un error.

### Ver también

- Transliterator::getErrorMessage() - Obtiene el último mensaje de error
- Transliterator::listIDs() - Obtiene los identificadores de este transliterador

# Transliterator::getErrorMessage

# transliterator_get_error_message

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::getErrorMessage -- transliterator_get_error_message — Obtiene el último mensaje de error

### Descripción

Estilo orientado a objetos

public function Transliterator::getErrorMessage(): string

Estilo procedimental

function transliterator_get_error_message(Transliterator `$transliterator`): string

Obtiene el último mensaje de error desde este transliterador.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`transliterator`

### Valores devueltos

El mensaje de error en caso de éxito, o `false` si no existe ningún error, o si ocurre un error.

### Ver también

- Transliterator::getErrorCode() - Obtiene el último código de error
- Transliterator::listIDs() - Obtiene los identificadores de este transliterador

# Transliterator::listIDs

# transliterator_list_ids

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::listIDs -- transliterator_list_ids — Obtiene los identificadores de este transliterador

### Descripción

Estilo orientado a objetos

public static function Transliterator::listIDs(): array|false

Estilo procedimental

function transliterator_list_ids(): array|false

Devuelve un array que contiene todos los identificadores registrados para este transliterador.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array que contiene todos los identificadores registrados para este transliterador en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Obtención de los identificadores transliterador registrados

    <?php
    print_r(Transliterator::listIDs());
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => ASCII-Latin
        [1] => Accents-Any
        [2] => Amharic-Latin/BGN
        [3] => Any-Accents
        [4] => Any-Publishing
    ...
        [650] => Any-ps_Latn/BGN
        [651] => Any-tk/BGN
        [652] => Any-ch_FONIPA
        [653] => Any-cs_FONIPA
        [654] => Any-cy_FONIPA
    )

### Ver también

- Transliterator::getErrorMessage() - Obtiene el último mensaje de error
- Transliterator::transliterate() - Translittera un string

# Transliterator::transliterate

# transliterator_transliterate

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::transliterate -- transliterator_transliterate — Translittera un string

### Descripción

Estilo orientado a objetos

public function Transliterator::transliterate(string `$string`, int `$start` = 0, int `$end` = -1): string|false

Estilo procedimental

function transliterator_transliterate(
Transliterator|string `$transliterator`,
string `$string`,
int `$start` = 0,
int `$end` = -1
): string|false

Transforma un string o solo una parte utilizando un translitterador ICU.

### Parámetros

`transliterator`

  En la versión procedimental, un Transliterator o un string desde el cual puede construirse un Transliterator.

`string`

  El string a transformar.

`start`

  El índice de inicio (en unidades UTF-16) desde el cual la cadena comenzará a transformarse, inclusivo. Los índices comienzan en 0. El texto antes de este índice permanecerá sin cambios.

`end`

  El índice de fin (en unidades UTF-16) que indica el final de la transformación, exclusivo. Los índices comienzan en 0. El texto después de este índice permanecerá sin cambios.

### Valores devueltos

El string transformado en caso de éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Conversión de escapamientos en unidades UTF-16

    <?php
    $s = "\u304A\u65E9\u3046\u3054\u3056\u3044\u307E\u3059";
    echo transliterator_transliterate("Hex-Any/Java", $s), "\n";

    //ahora, la operación inversa con un carácter adicional
    $supplChar = html_entity_decode('&#x1D11E;');
    echo mb_strlen($supplChar, "UTF-8"), "\n";
    $encSupplChar = transliterator_transliterate("Any-Hex/Java", $supplChar);
    //muestra 2 unidades UTF-16 codificadas
    echo $encSupplChar, "\n";
    //y el retorno...
    echo transliterator_transliterate("Hex-Any/Java", $encSupplChar), "\n";
    ?>

Resultado del ejemplo anterior es similar a:

    お早うございます
    1
    \uD834\uDD1E
    𝄞

### Ver también

- Transliterator::getErrorMessage() - Obtiene el último mensaje de error
- Transliterator::__construct() - Constructor privado para prohibir la instanciación

## Tabla de contenidos

- Transliterator::__construct — Constructor privado para prohibir la instanciación
- Transliterator::create — Crea un Transliterator
- Transliterator::createFromRules — Crea un transliterador desde reglas
- Transliterator::createInverse — Crea un transliterador inverso
- Transliterator::getErrorCode — Obtiene el último código de error
- Transliterator::getErrorMessage — Obtiene el último mensaje de error
- Transliterator::listIDs — Obtiene los identificadores de este transliterador
- Transliterator::transliterate — Translittera un string

# La clase IntlBreakIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introducción

Un "delimitador de ruptura" es un objeto ICU que expone métodos para localizar delimitaciones en texto (por ejemplo, delimitaciones de palabras o frases). La clase IntlBreakIterator de PHP sirve como clase base para todos los tipos de delimitadores de ruptura ICU. Cuando una funcionalidad adicional está disponible, la extensión intl puede exponer el delimitador de ruptura ICU con subclases apropiadas, tales como IntlRuleBasedBreakIterator o IntlCodePointBreakIterator.

Esta clase implementa IteratorAggregate. Recorrer un IntlBreakIterator produce valores enteros no negativos que representan las posiciones sucesivas de las delimitaciones de texto, expresadas como conteos de unidades de código UTF-8 (octetos), tomados desde el inicio del texto (que tiene la posición `0`). Las claves producidas por el iterador forman simplemente la secuencia de números naturales `{0, 1, 2, …}`.

## Sinopsis de la Clase

class IntlBreakIterator implements IteratorAggregate {
/* Constantes */
public const int DONE;
public const int WORD_NONE;
public const int WORD_NONE_LIMIT;
public const int WORD_NUMBER;
public const int WORD_NUMBER_LIMIT;
public const int WORD_LETTER;
public const int WORD_LETTER_LIMIT;
public const int WORD_KANA;
public const int WORD_KANA_LIMIT;
public const int WORD_IDEO;
public const int WORD_IDEO_LIMIT;
public const int LINE_SOFT;
public const int LINE_SOFT_LIMIT;
public const int LINE_HARD;
public const int LINE_HARD_LIMIT;
public const int SENTENCE_TERM;
public const int SENTENCE_TERM_LIMIT;
public const int SENTENCE_SEP;
public const int SENTENCE_SEP_LIMIT;
/* Métodos */
private function __construct()
public static function createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createCodePointInstance(): IntlCodePointBreakIterator
public static function createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator
public function current(): int
public function first(): int
public function following(int `$offset`): int
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(int `$type`): string|false
public function getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator
public function getText(): ?string
public function isBoundary(int `$offset`): bool
public function last(): int
public function next(?int `$offset` = `null`): int
public function preceding(int `$offset`): int
public function previous(): int
public function setText(string `$text`): bool
}

## Constantes predefinidas

`IntlBreakIterator::DONE` int

`IntlBreakIterator::WORD_NONE` int

`IntlBreakIterator::WORD_NONE_LIMIT` int

`IntlBreakIterator::WORD_NUMBER` int

`IntlBreakIterator::WORD_NUMBER_LIMIT` int

`IntlBreakIterator::WORD_LETTER` int

`IntlBreakIterator::WORD_LETTER_LIMIT` int

`IntlBreakIterator::WORD_KANA` int

`IntlBreakIterator::WORD_KANA_LIMIT` int

`IntlBreakIterator::WORD_IDEO` int

`IntlBreakIterator::WORD_IDEO_LIMIT` int

`IntlBreakIterator::LINE_SOFT` int

`IntlBreakIterator::LINE_SOFT_LIMIT` int

`IntlBreakIterator::LINE_HARD` int

`IntlBreakIterator::LINE_HARD_LIMIT` int

`IntlBreakIterator::SENTENCE_TERM` int

`IntlBreakIterator::SENTENCE_TERM_LIMIT` int

`IntlBreakIterator::SENTENCE_SEP` int

`IntlBreakIterator::SENTENCE_SEP_LIMIT` int

## Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Las constantes de clase ahora están tipadas.
8.0.0 | IntlBreakIterator ahora implementa IteratorAggregate. Antes, Traversable era implementada en su lugar.

# IntlBreakIterator::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::__construct — Constructor privado para deshabilitar la instanciación

### Descripción

private function IntlBreakIterator::__construct()

Las instancias de IntlBreakIterator deben ser creadas utilizando uno de los métodos de fábrica estáticos.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

### Ver también

- IntlBreakIterator::createCharacterInstance() - Crea un iterador para los límites de las secuencias de caracteres combinados
- IntlBreakIterator::createCodePointInstance() - Crea un iterador para los límites de puntos de código
- IntlBreakIterator::createLineInstance() - Crea un iterador para las divisiones de líneas
- IntlBreakIterator::createSentenceInstance() - Crea un iterador para las divisiones de oración
- IntlBreakIterator::createTitleInstance() - Crea un iterador
- IntlBreakIterator::createWordInstance() - Crea un iterador para las divisiones de palabras

# IntlBreakIterator::createCharacterInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createCharacterInstance — Crea un iterador para los límites de las secuencias de caracteres combinados

### Descripción

public static function IntlBreakIterator::createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`locale`

### Valores devueltos

# IntlBreakIterator::createCodePointInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createCodePointInstance — Crea un iterador para los límites de puntos de código

### Descripción

public static function IntlBreakIterator::createCodePointInstance(): IntlCodePointBreakIterator

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlBreakIterator::createLineInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createLineInstance — Crea un iterador para las divisiones de líneas

### Descripción

public static function IntlBreakIterator::createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`locale`

### Valores devueltos

# IntlBreakIterator::createSentenceInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createSentenceInstance — Crea un iterador para las divisiones de oración

### Descripción

public static function IntlBreakIterator::createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`locale`

### Valores devueltos

# IntlBreakIterator::createTitleInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createTitleInstance — Crea un iterador

### Descripción

public static function IntlBreakIterator::createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`locale`

### Valores devueltos

# IntlBreakIterator::createWordInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createWordInstance — Crea un iterador para las divisiones de palabras

### Descripción

public static function IntlBreakIterator::createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`locale`

### Valores devueltos

# IntlBreakIterator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::current — Obtiene el índice de la posición actual

### Descripción

public function IntlBreakIterator::current(): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlBreakIterator::first

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::first — Define la posición en el primer carácter del texto

### Descripción

public function IntlBreakIterator::first(): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlBreakIterator::following

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::following — Avance el iterador a la primera frontera siguiente a la posición especificada

### Descripción

public function IntlBreakIterator::following(int `$offset`): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`offset`

### Valores devueltos

# IntlBreakIterator::getErrorCode

# intl_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getErrorCode -- intl_get_error_code — Recupera el código del último error ocurrido en el objeto

### Descripción

Estilo orientado a objetos (método):

public function IntlBreakIterator::getErrorCode(): int

Estilo procedimental:

function intl_get_error_code(): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlBreakIterator::getErrorMessage

# intl_get_error_message

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getErrorMessage -- intl_get_error_message — Recupera el mensaje del último error ocurrido en el objeto

### Descripción

Estilo orientado a objetos (método):

public function IntlBreakIterator::getErrorMessage(): string

Estilo procedimental:

function intl_get_error_message(): string

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlBreakIterator::getLocale

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getLocale — Obtiene la configuración local asociada con el objeto

### Descripción

public function IntlBreakIterator::getLocale(int `$type`): string|false

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`type`

### Valores devueltos

# IntlBreakIterator::getPartsIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getPartsIterator — Crea un iterador para navegar en los fragmentos entre los límites

### Descripción

public function IntlBreakIterator::getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`type`

  Tipo de clave (opcional). Los valores posibles son :

  - `IntlPartsIterator::KEY_SEQUENTIAL` - El valor por omisión. Enteros secuencialmente crecientes utilizados como claves.
  - `IntlPartsIterator::KEY_LEFT` - Desplazamiento de octeto a la izquierda de la parte actual utilizada como clave.
  - `IntlPartsIterator::KEY_RIGHT` - Desplazamiento de octeto a la derecha de la parte actual utilizada como clave.

### Valores devueltos

# IntlBreakIterator::getText

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getText — Recupera el texto analizado

### Descripción

public function IntlBreakIterator::getText(): ?string

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlBreakIterator::isBoundary

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::isBoundary — Indica si una posición es una posición límite

### Descripción

public function IntlBreakIterator::isBoundary(int `$offset`): bool

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`offset`

### Valores devueltos

# IntlBreakIterator::last

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::last — Define la posición del iterador al índice después del último carácter

### Descripción

public function IntlBreakIterator::last(): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlBreakIterator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::next — Avance el iterador a la siguiente frontera

### Descripción

public function IntlBreakIterator::next(?int `$offset` = `null`): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`offset`

### Valores devueltos

# IntlBreakIterator::preceding

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::preceding — Define la posición del iterador en el primer límite antes de la posición

### Descripción

public function IntlBreakIterator::preceding(int `$offset`): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`offset`

### Valores devueltos

# IntlBreakIterator::previous

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::previous — Define la posición del iterador en el límite inmediato anterior al actual

### Descripción

public function IntlBreakIterator::previous(): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlBreakIterator::setText

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::setText — Define el texto a analizar

### Descripción

public function IntlBreakIterator::setText(string `$text`): bool

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`text`

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Este método devuelve ahora `false` en caso de error; previamente devolvía `null`.

## Tabla de contenidos

- IntlBreakIterator::__construct — Constructor privado para deshabilitar la instanciación
- IntlBreakIterator::createCharacterInstance — Crea un iterador para los límites de las secuencias de caracteres combinados
- IntlBreakIterator::createCodePointInstance — Crea un iterador para los límites de puntos de código
- IntlBreakIterator::createLineInstance — Crea un iterador para las divisiones de líneas
- IntlBreakIterator::createSentenceInstance — Crea un iterador para las divisiones de oración
- IntlBreakIterator::createTitleInstance — Crea un iterador
- IntlBreakIterator::createWordInstance — Crea un iterador para las divisiones de palabras
- IntlBreakIterator::current — Obtiene el índice de la posición actual
- IntlBreakIterator::first — Define la posición en el primer carácter del texto
- IntlBreakIterator::following — Avance el iterador a la primera frontera siguiente a la posición especificada
- IntlBreakIterator::getErrorCode — Recupera el código del último error ocurrido en el objeto
- IntlBreakIterator::getErrorMessage — Recupera el mensaje del último error ocurrido en el objeto
- IntlBreakIterator::getLocale — Obtiene la configuración local asociada con el objeto
- IntlBreakIterator::getPartsIterator — Crea un iterador para navegar en los fragmentos entre los límites
- IntlBreakIterator::getText — Recupera el texto analizado
- IntlBreakIterator::isBoundary — Indica si una posición es una posición límite
- IntlBreakIterator::last — Define la posición del iterador al índice después del último carácter
- IntlBreakIterator::next — Avance el iterador a la siguiente frontera
- IntlBreakIterator::preceding — Define la posición del iterador en el primer límite antes de la posición
- IntlBreakIterator::previous — Define la posición del iterador en el límite inmediato anterior al actual
- IntlBreakIterator::setText — Define el texto a analizar

# La clase IntlRuleBasedBreakIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introducción

Una subclase de IntlBreakIterator que encapsula los iteradores de ruptura ICU cuyo comportamiento es especificado mediante un conjunto de reglas. Este es el tipo de iterador de ruptura más común.

Estas reglas se describen en el » Guía del usuario de análisis de límites ICU.

## Sinopsis de la Clase

class IntlRuleBasedBreakIterator extends IntlBreakIterator {
/* Constantes heredadas */
public const int IntlBreakIterator::DONE;
public const int IntlBreakIterator::WORD_NONE;
public const int IntlBreakIterator::WORD_NONE_LIMIT;
public const int IntlBreakIterator::WORD_NUMBER;
public const int IntlBreakIterator::WORD_NUMBER_LIMIT;
public const int IntlBreakIterator::WORD_LETTER;
public const int IntlBreakIterator::WORD_LETTER_LIMIT;
public const int IntlBreakIterator::WORD_KANA;
public const int IntlBreakIterator::WORD_KANA_LIMIT;
public const int IntlBreakIterator::WORD_IDEO;
public const int IntlBreakIterator::WORD_IDEO_LIMIT;
public const int IntlBreakIterator::LINE_SOFT;
public const int IntlBreakIterator::LINE_SOFT_LIMIT;
public const int IntlBreakIterator::LINE_HARD;
public const int IntlBreakIterator::LINE_HARD_LIMIT;
public const int IntlBreakIterator::SENTENCE_TERM;
public const int IntlBreakIterator::SENTENCE_TERM_LIMIT;
public const int IntlBreakIterator::SENTENCE_SEP;
public const int IntlBreakIterator::SENTENCE_SEP_LIMIT;
/* Métodos */
public function __construct(string `$rules`, bool `$compiled` = `false`)
public function getBinaryRules(): string|false
public function getRules(): string|false
public function getRuleStatus(): int
public function getRuleStatusVec(): array|false
/* Métodos heredados */
public static function IntlBreakIterator::createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createCodePointInstance(): IntlCodePointBreakIterator
public static function IntlBreakIterator::createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator
public function IntlBreakIterator::current(): int
public function IntlBreakIterator::first(): int
public function IntlBreakIterator::following(int `$offset`): int
public function IntlBreakIterator::getErrorCode(): int
public function IntlBreakIterator::getErrorMessage(): string
public function IntlBreakIterator::getLocale(int `$type`): string|false
public function IntlBreakIterator::getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator
public function IntlBreakIterator::getText(): ?string
public function IntlBreakIterator::isBoundary(int `$offset`): bool
public function IntlBreakIterator::last(): int
public function IntlBreakIterator::next(?int `$offset` = `null`): int
public function IntlBreakIterator::preceding(int `$offset`): int
public function IntlBreakIterator::previous(): int
public function IntlBreakIterator::setText(string `$text`): bool
}

# IntlRuleBasedBreakIterator::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::__construct — Crea un iterador desde un conjunto de reglas

### Descripción

public function IntlRuleBasedBreakIterator::__construct(string `$rules`, bool `$compiled` = `false`)

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`rules`

`compiled`

### Valores devueltos

# IntlRuleBasedBreakIterator::getBinaryRules

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getBinaryRules — Obtiene la forma binaria de las reglas compiladas

### Descripción

public function IntlRuleBasedBreakIterator::getBinaryRules(): string|false

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlRuleBasedBreakIterator::getRules

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getRules — Recupera el conjunto de reglas utilizado para crear este objeto

### Descripción

public function IntlRuleBasedBreakIterator::getRules(): string|false

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlRuleBasedBreakIterator::getRuleStatus

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getRuleStatus — Obtiene el valor de estado más grande desde las reglas que determinan la posición actual de interrupción

### Descripción

public function IntlRuleBasedBreakIterator::getRuleStatus(): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlRuleBasedBreakIterator::getRuleStatusVec

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getRuleStatusVec — Obtiene los valores de estado desde las reglas de interrupción que determinan la posición de interrupción actual

### Descripción

public function IntlRuleBasedBreakIterator::getRuleStatusVec(): array|false

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

## Tabla de contenidos

- IntlRuleBasedBreakIterator::__construct — Crea un iterador desde un conjunto de reglas
- IntlRuleBasedBreakIterator::getBinaryRules — Obtiene la forma binaria de las reglas compiladas
- IntlRuleBasedBreakIterator::getRules — Recupera el conjunto de reglas utilizado para crear este objeto
- IntlRuleBasedBreakIterator::getRuleStatus — Obtiene el valor de estado más grande desde las reglas que determinan la posición actual de interrupción
- IntlRuleBasedBreakIterator::getRuleStatusVec — Obtiene los valores de estado desde las reglas de interrupción que determinan la posición de interrupción actual

# La clase IntlCodePointBreakIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introducción

Este iterador de ruptura identifica los límites entre los puntos de código UTF-8.

## Sinopsis de la Clase

class IntlCodePointBreakIterator extends IntlBreakIterator {
/* Constantes heredadas */
public const int IntlBreakIterator::DONE;
public const int IntlBreakIterator::WORD_NONE;
public const int IntlBreakIterator::WORD_NONE_LIMIT;
public const int IntlBreakIterator::WORD_NUMBER;
public const int IntlBreakIterator::WORD_NUMBER_LIMIT;
public const int IntlBreakIterator::WORD_LETTER;
public const int IntlBreakIterator::WORD_LETTER_LIMIT;
public const int IntlBreakIterator::WORD_KANA;
public const int IntlBreakIterator::WORD_KANA_LIMIT;
public const int IntlBreakIterator::WORD_IDEO;
public const int IntlBreakIterator::WORD_IDEO_LIMIT;
public const int IntlBreakIterator::LINE_SOFT;
public const int IntlBreakIterator::LINE_SOFT_LIMIT;
public const int IntlBreakIterator::LINE_HARD;
public const int IntlBreakIterator::LINE_HARD_LIMIT;
public const int IntlBreakIterator::SENTENCE_TERM;
public const int IntlBreakIterator::SENTENCE_TERM_LIMIT;
public const int IntlBreakIterator::SENTENCE_SEP;
public const int IntlBreakIterator::SENTENCE_SEP_LIMIT;
/* Métodos */
public function getLastCodePoint(): int
/* Métodos heredados */
public static function IntlBreakIterator::createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createCodePointInstance(): IntlCodePointBreakIterator
public static function IntlBreakIterator::createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator
public function IntlBreakIterator::current(): int
public function IntlBreakIterator::first(): int
public function IntlBreakIterator::following(int `$offset`): int
public function IntlBreakIterator::getErrorCode(): int
public function IntlBreakIterator::getErrorMessage(): string
public function IntlBreakIterator::getLocale(int `$type`): string|false
public function IntlBreakIterator::getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator
public function IntlBreakIterator::getText(): ?string
public function IntlBreakIterator::isBoundary(int `$offset`): bool
public function IntlBreakIterator::last(): int
public function IntlBreakIterator::next(?int `$offset` = `null`): int
public function IntlBreakIterator::preceding(int `$offset`): int
public function IntlBreakIterator::previous(): int
public function IntlBreakIterator::setText(string `$text`): bool
}

# IntlCodePointBreakIterator::getLastCodePoint

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlCodePointBreakIterator::getLastCodePoint — Recupera el último punto de código después de avanzar o retroceder en el iterador

### Descripción

public function IntlCodePointBreakIterator::getLastCodePoint(): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

## Tabla de contenidos

- IntlCodePointBreakIterator::getLastCodePoint — Recupera el último punto de código después de avanzar o retroceder en el iterador

# La clase IntlDatePatternGenerator

(PHP 8 >= 8.1.0)

## Introducción

Genera strings de formato de fecha y/o hora localizados adecuados para su uso en IntlDateFormatter.

## Sinopsis de la Clase

class IntlDatePatternGenerator {
/* Métodos */
public function __construct(?string `$locale` = `null`)
public static function create(?string `$locale` = `null`): ?IntlDatePatternGenerator
public function getBestPattern(string `$skeleton`): string|false
}

# IntlDatePatternGenerator::create

# IntlDatePatternGenerator::__construct

(PHP 8 >= 8.1.0)

IntlDatePatternGenerator::create -- IntlDatePatternGenerator::__construct — Crear una nueva instancia de IntlDatePatternGenerator

### Descripción

public static function IntlDatePatternGenerator::create(?string `$locale` = `null`): ?IntlDatePatternGenerator
public function IntlDatePatternGenerator::__construct(?string `$locale` = `null`)

Crea una nueva instancia de IntlDatePatternGenerator.

### Parámetros

`locale`

  La configuración local/regional. Si se pasa `null`, se utiliza el parámetro ini intl.default_locale.

### Valores devueltos

Devuelve una instancia de IntlDatePatternGenerator en caso de éxito, o `null` en caso de error.

# IntlDatePatternGenerator::getBestPattern

(PHP 8 >= 8.1.0)

IntlDatePatternGenerator::getBestPattern — Determina el formato de fecha/hora más adecuado

### Descripción

public function IntlDatePatternGenerator::getBestPattern(string `$skeleton`): string|false

Determina qué formato de fecha/hora es el más adecuado para una configuración local dada.

### Parámetros

`skeleton`

  El esqueleto.

### Valores devueltos

Devuelve un patrón de fecha/hora ICU aceptado por IntlDateFormatter en caso de éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de IntlDatePatternGenerator::getBestPattern()

    <?php

    $skeleton = 'YYYYMMdd';
    $today = \DateTimeImmutable::createFromFormat('Y-m-d', '2021-04-24');

    $patternGenerator = new \IntlDatePatternGenerator('de_DE');
    $pattern = $patternGenerator->getBestPattern($skeleton);
    echo 'de: ', \IntlDateFormatter::formatObject($today, $pattern, 'de_DE'), "\n";

    $patternGenerator = new \IntlDatePatternGenerator('en_US');
    $pattern = $patternGenerator->getBestPattern($skeleton);
    echo 'en: ', \IntlDateFormatter::formatObject($today, $pattern, 'en_US');
    ?>

El ejemplo anterior mostrará:

    de: 24.04.2021
    en: 04/24/2021

## Tabla de contenidos

- IntlDatePatternGenerator::create — Crear una nueva instancia de IntlDatePatternGenerator
- IntlDatePatternGenerator::getBestPattern — Determina el formato de fecha/hora más adecuado

# La clase IntlPartsIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introducción

Los objetos de esta clase pueden ser obtenidos a partir de objetos IntlBreakIterator. Mientras que los iteradores de ruptura proporcionan una secuencia de posiciones de límites cuando son iterados, los objetos IntlPartsIterator proporcionan, por conveniencia, los fragmentos de texto comprendidos entre dos límites sucesivos.

Las claves pueden representar el desplazamiento del límite izquierdo, del límite derecho, o pueden ser simplemente la secuencia de enteros no negativos. Ver IntlBreakIterator::getPartsIterator().

## Sinopsis de la Clase

class IntlPartsIterator extends IntlIterator {
/* Constantes */
public const int KEY_SEQUENTIAL;
public const int KEY_LEFT;
public const int KEY_RIGHT;
/* Métodos */
public function getBreakIterator(): IntlBreakIterator
/* Métodos heredados */
public function IntlIterator::current(): mixed
public function IntlIterator::key(): mixed
public function IntlIterator::next(): void
public function IntlIterator::rewind(): void
public function IntlIterator::valid(): bool
}

## Constantes predefinidas

`IntlPartsIterator::KEY_SEQUENTIAL` int

`IntlPartsIterator::KEY_LEFT` int

`IntlPartsIterator::KEY_RIGHT` int

## Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Las constantes de clase ahora están tipadas.

# IntlPartsIterator::getBreakIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlPartsIterator::getBreakIterator — Obtiene IntlBreakIterator, preservando así esta parte del iterador

### Descripción

public function IntlPartsIterator::getBreakIterator(): IntlBreakIterator

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

## Tabla de contenidos

- IntlPartsIterator::getBreakIterator — Obtiene IntlBreakIterator, preservando así esta parte del iterador

# La clase UConverter

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

## Introducción

## Sinopsis de la Clase

class UConverter {
/* Constantes */
public const int REASON_UNASSIGNED;
public const int REASON_ILLEGAL;
public const int REASON_IRREGULAR;
public const int REASON_RESET;
public const int REASON_CLOSE;
public const int REASON_CLONE;
public const int UNSUPPORTED_CONVERTER;
public const int SBCS;
public const int DBCS;
public const int MBCS;
public const int LATIN_1;
public const int UTF8;
public const int UTF16_BigEndian;
public const int UTF16_LittleEndian;
public const int UTF32_BigEndian;
public const int UTF32_LittleEndian;
public const int EBCDIC_STATEFUL;
public const int ISO_2022;
public const int LMBCS_1;
public const int LMBCS_2;
public const int LMBCS_3;
public const int LMBCS_4;
public const int LMBCS_5;
public const int LMBCS_6;
public const int LMBCS_8;
public const int LMBCS_11;
public const int LMBCS_16;
public const int LMBCS_17;
public const int LMBCS_18;
public const int LMBCS_19;
public const int LMBCS_LAST;
public const int HZ;
public const int SCSU;
public const int ISCII;
public const int US_ASCII;
public const int UTF7;
public const int BOCU1;
public const int UTF16;
public const int UTF32;
public const int CESU8;
public const int IMAP_MAILBOX;
/* Métodos */
public function __construct(?string `$destination_encoding` = `null`, ?string `$source_encoding` = `null`)
public function convert(string `$str`, bool `$reverse` = `false`): string|false
public function fromUCallback(
int `$reason`,
array `$source`,
int `$codePoint`,
int `&$error`
): string|int|array|null
public static function getAliases(string `$name`): array|false|null
public static function getAvailable(): array
public function getDestinationEncoding(): string|false|null
public function getDestinationType(): int|false|null
public function getErrorCode(): int
public function getErrorMessage(): ?string
public function getSourceEncoding(): string|false|null
public function getSourceType(): int|false|null
public static function getStandards(): ?array
public function getSubstChars(): string|false|null
public static function reasonText(int `$reason`): string
public function setDestinationEncoding(string `$encoding`): bool
public function setSourceEncoding(string `$encoding`): bool
public function setSubstChars(string `$chars`): bool
public function toUCallback(
int `$reason`,
string `$source`,
string `$codeUnits`,
int `&$error`
): string|int|array|null
public static function transcode(
string `$str`,
string `$toEncoding`,
string `$fromEncoding`,
?array `$options` = `null`
): string|false
}

## Constantes predefinidas

`UConverter::REASON_UNASSIGNED` int

`UConverter::REASON_ILLEGAL` int

`UConverter::REASON_IRREGULAR` int

`UConverter::REASON_RESET` int

`UConverter::REASON_CLOSE` int

`UConverter::REASON_CLONE` int

`UConverter::UNSUPPORTED_CONVERTER` int

`UConverter::SBCS` int

`UConverter::DBCS` int

`UConverter::MBCS` int

`UConverter::LATIN_1` int

`UConverter::UTF8` int

`UConverter::UTF16_BigEndian` int

`UConverter::UTF16_LittleEndian` int

`UConverter::UTF32_BigEndian` int

`UConverter::UTF32_LittleEndian` int

`UConverter::EBCDIC_STATEFUL` int

`UConverter::ISO_2022` int

`UConverter::LMBCS_1` int

`UConverter::LMBCS_2` int

`UConverter::LMBCS_3` int

`UConverter::LMBCS_4` int

`UConverter::LMBCS_5` int

`UConverter::LMBCS_6` int

`UConverter::LMBCS_8` int

`UConverter::LMBCS_11` int

`UConverter::LMBCS_16` int

`UConverter::LMBCS_17` int

`UConverter::LMBCS_18` int

`UConverter::LMBCS_19` int

`UConverter::LMBCS_LAST` int

`UConverter::HZ` int

`UConverter::SCSU` int

`UConverter::ISCII` int

`UConverter::US_ASCII` int

`UConverter::UTF7` int

`UConverter::BOCU1` int

`UConverter::UTF16` int

`UConverter::UTF32` int

`UConverter::CESU8` int

`UConverter::IMAP_MAILBOX` int

## Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Las constantes de clase ahora están tipadas.

# UConverter::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::__construct — Crea un objeto UConverter

### Descripción

public function UConverter::__construct(?string `$destination_encoding` = `null`, ?string `$source_encoding` = `null`)

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`destination_encoding`

`source_encoding`

### Valores devueltos

# UConverter::convert

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::convert — Convierte una cadena de un juego de caracteres a otro juego de caracteres

### Descripción

public function UConverter::convert(string `$str`, bool `$reverse` = `false`): string|false

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`str`

`reverse`

### Valores devueltos

# UConverter::fromUCallback

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::fromUCallback — Función de retrollamada "from"

### Descripción

public function UConverter::fromUCallback(
int `$reason`,
array `$source`,
int `$codePoint`,
int `&$error`
): string|int|array|null

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`reason`

`source`

`codePoint`

`error`

### Valores devueltos

# UConverter::getAliases

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getAliases — Obtiene los alias del nombre proporcionado

### Descripción

public static function UConverter::getAliases(string `$name`): array|false|null

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`name`

### Valores devueltos

# UConverter::getAvailable

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getAvailable — Obtiene el nombre canónico de los convertidores disponibles

### Descripción

public static function UConverter::getAvailable(): array

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# UConverter::getDestinationEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getDestinationEncoding — Obtiene la codificación de destino

### Descripción

public function UConverter::getDestinationEncoding(): string|false|null

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# UConverter::getDestinationType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getDestinationType — Obtiene el tipo de destino del convertidor

### Descripción

public function UConverter::getDestinationType(): int|false|null

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# UConverter::getErrorCode

# intl_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getErrorCode -- intl_get_error_code — Obtiene el código del último error ocurrido en el objeto

### Descripción

public function UConverter::getErrorCode(): int

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# UConverter::getErrorMessage

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getErrorMessage — Recupera el mensaje del último error ocurrido en el objeto

### Descripción

public function UConverter::getErrorMessage(): ?string

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# UConverter::getSourceEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSourceEncoding — Obtiene la codificación de la fuente

### Descripción

public function UConverter::getSourceEncoding(): string|false|null

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# UConverter::getSourceType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSourceType — Obtiene el tipo de fuente del convertidor

### Descripción

public function UConverter::getSourceType(): int|false|null

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# UConverter::getStandards

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getStandards — Obtiene las normas asociadas a los nombres de conversión

### Descripción

public static function UConverter::getStandards(): ?array

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# UConverter::getSubstChars

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSubstChars — Obtiene los caracteres de sustitución

### Descripción

public function UConverter::getSubstChars(): string|false|null

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# UConverter::reasonText

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::reasonText — Obtiene la cadena que representa la razón de la función de retorno

### Descripción

public static function UConverter::reasonText(int `$reason`): string

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`reason`

### Valores devueltos

# UConverter::setDestinationEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setDestinationEncoding — Define el codificación de destino

### Descripción

public function UConverter::setDestinationEncoding(string `$encoding`): bool

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`encoding`

### Valores devueltos

# UConverter::setSourceEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setSourceEncoding — Define el conjunto de caracteres de la fuente

### Descripción

public function UConverter::setSourceEncoding(string `$encoding`): bool

Este método permite establecer el conjunto de caracteres para la fuente de datos.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`encoding`

  El `encoding` especifica el conjunto de caracteres a utilizar.

### Valores devueltos

Este método devuelve un valor booleano que indica si la operación fue exitosa.

# UConverter::setSubstChars

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setSubstChars — Define los caracteres de sustitución

### Descripción

public function UConverter::setSubstChars(string `$chars`): bool

Este método permite establecer los caracteres de sustitución que serán utilizados cuando no sea posible representar un carácter en el conjunto de caracteres de destino.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`chars`

  El argumento `chars` debe ser un string que contenga los caracteres de sustitución.

### Valores devueltos

Este método devuelve `TRUE` en caso de éxito y `FALSE` en caso de error.

# UConverter::toUCallback

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::toUCallback — Función de retrollamada "to"

### Descripción

public function UConverter::toUCallback(
int `$reason`,
string `$source`,
string `$codeUnits`,
int `&$error`
): string|int|array|null

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`reason`

`source`

`codeUnits`

`error`

### Valores devueltos

# UConverter::transcode

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::transcode — Convierte una cadena de un juego de caracteres a otro

### Descripción

public static function UConverter::transcode(
string `$str`,
string `$toEncoding`,
string `$fromEncoding`,
?array `$options` = `null`
): string|false

Convierte `str` de `fromEncoding` a `toEncoding`.

### Parámetros

`str`

  El string a convertir.

`toEncoding`

  El juego de caracteres deseado para el resultado.

`fromEncoding`

  El juego de caracteres actual utilizado para interpretar `str`.

`options`

  Un array opcional, que puede contener las siguientes claves:

  - `'to_subst'` - el carácter de sustitución a utilizar en lugar de cualquier carácter de `str` que no pueda ser codificado en `toEncoding`. Si se especifica, debe representar un solo carácter en el codificación objetivo.

### Valores devueltos

Devuelve la cadena convertida, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Conversión de UTF-8 a UTF-16 y viceversa

    <?php
    $utf8_string = "\x5A\x6F\xC3\xAB"; // 'Zoë' en UTF-8
    $utf16_string = UConverter::transcode($utf8_string, 'UTF-16BE', 'UTF-8');
    echo bin2hex($utf16_string), "\n";

    $new_utf8_string = UConverter::transcode($utf16_string, 'UTF-8', 'UTF-16BE');
    echo bin2hex($new_utf8_string), "\n";
    ?>

El ejemplo anterior mostrará:

    005a006f00eb
    5a6fc3ab

Ejemplo #2 Caracteres no válidos en la entrada

Si la cadena de entrada contiene una secuencia de octetos que no es válida en el codificación especificado por `fromEncoding`, son reemplazados por el punto de código Unicode U+FFFD (Carácter de reemplazo) antes de ser convertidos a `toEncoding`.

    <?php
    $invalid_utf8_string = "\xC3"; // secuencia multi-octetos UTF-8 incompleta
    $utf16_string = UConverter::transcode($invalid_utf8_string, 'UTF-16BE', 'UTF-8');
    echo bin2hex($utf16_string), "\n";
    ?>

El ejemplo anterior mostrará:

    fffd

Ejemplo #3 Caracteres que no pueden ser codificados

Si la cadena de entrada contiene caracteres que no pueden ser representados en `toEncoding`, son reemplazados por un solo carácter. El carácter por defecto a utilizar depende del codificación y puede ser controlado mediante la opción `'to_subst'`.

    <?php
    $utf8_string = "\xE2\x82\xAC"; // € (símbolo euro) no existe en el ISO 8859-1

    // El reemplazo por defecto en ISO 8859-1 es "\x1A" (Sustituto)
    $iso8859_1_string = UConverter::transcode($utf8_string, 'ISO-8859-1', 'UTF-8');
    echo bin2hex($iso8859_1_string), "\n";

    // Especifica un reemplazo de '?' ("\x3F") en su lugar
    $iso8859_1_string = UConverter::transcode(
        $utf8_string, 'ISO-8859-1', 'UTF-8', ['to_subst' => '?']
    );
    echo bin2hex($iso8859_1_string), "\n";

    // Dado que el ISO 8859-1 no puede mapear U+FFFD, la entrada inválida también es reemplazada por to_subst.
    $invalid_utf8_string = "\xC3"; // secuencia multi-octetos UTF-8 incompleta
    $iso8859_1_string = UConverter::transcode(
        $invalid_utf8_string, 'ISO-8859-1', 'UTF-8', ['to_subst' => '?']
    );
    echo bin2hex($iso8859_1_string), "\n";
    ?>

El ejemplo anterior mostrará:

    1a
    3f
    3f

### Ver también

- mb_convert_encoding() - Convertir una cadena de un codificación de caracteres a otra
- iconv() - Convierte una cadena de caracteres de un encodaje a otro

## Tabla de contenidos

- UConverter::__construct — Crea un objeto UConverter
- UConverter::convert — Convierte una cadena de un juego de caracteres a otro juego de caracteres
- UConverter::fromUCallback — Función de retrollamada "from"
- UConverter::getAliases — Obtiene los alias del nombre proporcionado
- UConverter::getAvailable — Obtiene el nombre canónico de los convertidores disponibles
- UConverter::getDestinationEncoding — Obtiene la codificación de destino
- UConverter::getDestinationType — Obtiene el tipo de destino del convertidor
- UConverter::getErrorCode — Obtiene el código del último error ocurrido en el objeto
- UConverter::getErrorMessage — Recupera el mensaje del último error ocurrido en el objeto
- UConverter::getSourceEncoding — Obtiene la codificación de la fuente
- UConverter::getSourceType — Obtiene el tipo de fuente del convertidor
- UConverter::getStandards — Obtiene las normas asociadas a los nombres de conversión
- UConverter::getSubstChars — Obtiene los caracteres de sustitución
- UConverter::reasonText — Obtiene la cadena que representa la razón de la función de retorno
- UConverter::setDestinationEncoding — Define el codificación de destino
- UConverter::setSourceEncoding — Define el conjunto de caracteres de la fuente
- UConverter::setSubstChars — Define los caracteres de sustitución
- UConverter::toUCallback — Función de retrollamada "to"
- UConverter::transcode — Convierte una cadena de un juego de caracteres a otro

# Funciones de Grapheme

# grapheme_extract

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_extract — Extrae un grupo de grafemas de una cadena UTF-8

### Descripción

Estilo procedimental

function grapheme_extract(
string `$haystack`,
int `$size`,
int `$type` = `GRAPHEME_EXTR_COUNT`,
int `$offset` = 0,
int `&$next` = `null`
): string|false

Esta función extrae una secuencia de grupos de grafemas por defecto de un texto en UTF-8.

### Parámetros

`haystack`

  La cadena a estudiar.

`size`

  El número máximo de elementos, en función de `type`, a devolver.

`type`

  Define el tipo de unidades indicadas por el parámetro `size`:

  - GRAPHEME_EXTR_COUNT (por defecto): `size` es el número de grupos de grafemas a extraer.
  - GRAPHEME_EXTR_MAXBYTES: `size` es el número de bytes a devolver.
  - GRAPHEME_EXTR_MAXCHARS: `size` es el número de caracteres UTF-8 a devolver.
`offset`

  La posición de inicio en `haystack`, expresada en bytes. Debe ser positiva, nula o inferior al tamaño de `haystack` en bytes, o un valor negativo, que contaría desde el final de `haystack`. Si `offset` no corresponde al primer byte de un carácter UTF-8 válido, la posición de inicio será desplazada al siguiente byte válido.

`next`

  Referencia a una variable que recibirá la próxima posición de inicio válida. Cuando la función termina, esto puede ser una posición que está más allá del tamaño de la cadena.

### Valores devueltos

Una cadena que comienza en la posición `offset` y termina en el límite válido de un grafema, y que se ajusta a las condiciones `size` y `type` especificadas, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
7.1.0 | Se añadió el soporte para valores negativos en `offset`.

### Ejemplos

Ejemplo #1 Ejemplo con grapheme_extract()

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"

    print urlencode(grapheme_extract( $char_a_ring_nfd . $char_o_diaeresis_nfd, 1, GRAPHEME_EXTR_COUNT, 2));

    ?>

El ejemplo anterior mostrará:

    o%CC%88

### Ver también

- grapheme_substr() - Devuelve una parte de un string
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_str_split

(PHP 8 >= 8.4.0)

grapheme_str_split — Divide una string en un array

### Descripción

function grapheme_str_split(string `$string`, int `$length` = 1): array|false

Esta función devuelve un array de strings, es una versión de str_split() con soporte para caracteres de cluster de grafemas. Si el argumento `length` es especificado, la string es dividida en trozos de la longitud especificada en clusters de grafemas (no en bytes).

### Parámetros

`string`

  La string a dividir en clusters de grafemas o en trozos. `string` debe ser un UTF-8 válido.

`length`

  Cada elemento del array devuelto estará compuesto por `length` clusters de grafemas.

### Valores devueltos

grapheme_str_split() devuelve un array de strings, o `false` si ocurre un error.

### Errores/Excepciones

Si `string` no es una string válida, se lanzará una ValueError.

### Ver también

- str_split() - Convierte un string en un array
- mb_str_split() - Para una cadena multibyte dada, devuelve un array de sus caracteres
- » Segmentación de texto Unicode: Límites de Clusters de Grafemas

# grapheme_stripos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_stripos — Encuentra la posición en grafema de la primera ocurrencia en una cadena, insensible a mayúsculas/minúsculas

### Descripción

Estilo procedimental

function grapheme_stripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

Encuentra la posición en grafema de la primera ocurrencia en una cadena, realizando una búsqueda insensible a mayúsculas/minúsculas.

### Parámetros

`haystack`

  La cadena a examinar. Debe estar en formato UTF-8 válido.

`needle`

  La cadena a buscar. Debe estar en formato UTF-8 válido.

`offset`

  El parámetro `offset` permite especificar la posición en la `haystack` donde comienza la búsqueda, expresada en grafemas (y no en bytes o caracteres). Si el offset es negativo, se trata con respecto al final de la cadena de caracteres. La posición devuelta siempre se da con respecto al inicio de `haystack`, independientemente del valor de `offset`.

`locale`
  La configuración regional a utilizar.

### Valores devueltos

Devuelve la posición, en forma de entero. Si `needle` no es encontrado, grapheme_stripos() devuelve `false`.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | Se ha añadido el parámetro opcional `locale`.
7.1.0 | Se añadió el soporte para `offset`s negativos.

### Ejemplos

Ejemplo #1 Ejemplo con grapheme_stripos()

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) forma normalizada "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) forma normalizada "D"
    $char_O_diaeresis_nfd = "O\xCC\x88"; // 'LATIN CAPITAL LETTER O WITH DIAERESIS' (U+00D6) forma normalizada "D"

    print grapheme_stripos( $char_a_ring_nfd . $char_a_ring_nfd . $char_o_diaeresis_nfd, $char_O_diaeresis_nfd);

    ?>

El ejemplo anterior mostrará:

    2

### Ver también

- grapheme_stristr() - Devuelve la parte de una cadena a partir de una ocurrencia
- grapheme_strpos() - Encuentra la posición del primer grafema
- grapheme_strripos() - Encuentra la posición del último grafema, insensible a mayúsculas/minúsculas
- grapheme_strrpos() - Encuentra la posición del último grafema
- grapheme_strstr() - Retorna la parte de una cadena a partir de una ocurrencia, insensible a mayúsculas/minúsculas
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_stristr

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_stristr — Devuelve la parte de una cadena a partir de una ocurrencia

### Descripción

Estilo procedimental

function grapheme_stristr(
string `$haystack`,
string `$needle`,
bool `$beforeNeedle` = `false`,
string `$locale` = ""
): string|false

Devuelve la parte de `haystack` a partir de la primera ocurrencia de `needle` (`needle` incluido) (insensible a mayúsculas/minúsculas), y hasta el final de la `haystack`.

### Parámetros

`haystack`

  La cadena a estudiar. Debe ser válida UTF-8.

`needle`

  La cadena a buscar. Debe ser válida UTF-8.

`beforeNeedle`

  Si `true`, grapheme_stristr() devuelve la parte de `haystack` antes de la primera ocurrencia (`needle` excluido).

`locale`
  La configuración regional a utilizar.

### Valores devueltos

Devuelve una porción de `haystack`, o `false` si `needle` no es encontrado.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | Se ha añadido el parámetro opcional `locale`.

### Ejemplos

Ejemplo #1 Ejemplo con grapheme_stristr()

    <?php

    $char_a_ring_nfd  = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5)  forma normalizada "D"
    $char_o_diaeresis_nfd  = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) forma  normalizada "D"
    $char_O_diaeresis_nfd =  "O\xCC\x88"; // 'LATIN CAPITAL LETTER O WITH DIAERESIS' (U+00D6) forma  normalizada "D"

    print  urlencode(grapheme_stristr( $char_a_ring_nfd . $char_o_diaeresis_nfd .  $char_a_ring_nfd, $char_O_diaeresis_nfd));

    ?>

El ejemplo anterior mostrará:

    o%CC%88a%CC%8A

### Ver también

- grapheme_stripos() - Encuentra la posición en grafema de la primera ocurrencia en una cadena, insensible a mayúsculas/minúsculas
- grapheme_strpos() - Encuentra la posición del primer grafema
- grapheme_strripos() - Encuentra la posición del último grafema, insensible a mayúsculas/minúsculas
- grapheme_strrpos() - Encuentra la posición del último grafema
- grapheme_strstr() - Retorna la parte de una cadena a partir de una ocurrencia, insensible a mayúsculas/minúsculas
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_strlen

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strlen — Lee la longitud de una cadena en número de grafemas

### Descripción

Estilo procedimental

function grapheme_strlen(string `$string`): int|false|null

Lee la longitud de una cadena en número de grafemas (y no en bytes o caracteres).

### Parámetros

`string`

  La cadena a medir. Debe ser una cadena UTF-8 válida.

### Valores devueltos

La longitud de la cadena en caso de éxito, `null` o `false` en caso de fallo.

### Ejemplos

Ejemplo #1 Ejemplo con grapheme_strlen()

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) forma normalizada "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) forma normalizada "D"

    print grapheme_strlen( 'abc' . $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_a_ring_nfd);

    ?>

El ejemplo anterior mostrará:

    6

### Ver también

- » Unicode Text Segmentation: Grapheme Cluster Boundaries
- iconv_strlen() - Devuelve el número de caracteres de una cadena
- mb_strlen() - Devuelve la longitud de una cadena
- strlen() - Calcula el tamaño de un string

# grapheme_strpos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strpos — Encuentra la posición del primer grafema

### Descripción

Estilo procedimental

function grapheme_strpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

Encuentra la posición del primer grafema en una cadena.

### Parámetros

`haystack`

  La cadena a estudiar. Debe estar en formato UTF-8 válido.

`needle`

  La cadena a estudiar. Debe estar en formato UTF-8 válido.

`offset`

  El parámetro `offset` permite especificar la posición en la `haystack` donde comienza la búsqueda, expresada en grafemas (y no en bytes o caracteres). Si el offset es negativo, se trata con respecto al final de la cadena de caracteres. La posición devuelta siempre se da con respecto al inicio de `haystack`, independientemente del valor de `offset`.

`locale`
  La configuración regional a utilizar.

### Valores devueltos

Devuelve la posición en forma de entero. Si `needle` no es encontrado, grapheme_strpos() devuelve `false`.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | Se ha añadido el parámetro opcional `locale`.
7.1.0 | Se añade el soporte para `offset`s negativos.

### Ejemplos

Ejemplo #1 Ejemplo con grapheme_strpos()

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) forma normalizada "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) forma normalizada "D"

    print grapheme_strpos( $char_a_ring_nfd . $char_a_ring_nfd . $char_o_diaeresis_nfd, $char_o_diaeresis_nfd);

    ?>

El ejemplo anterior mostrará:

    2

### Ver también

- grapheme_stripos() - Encuentra la posición en grafema de la primera ocurrencia en una cadena, insensible a mayúsculas/minúsculas
- grapheme_stristr() - Devuelve la parte de una cadena a partir de una ocurrencia
- grapheme_strripos() - Encuentra la posición del último grafema, insensible a mayúsculas/minúsculas
- grapheme_strrpos() - Encuentra la posición del último grafema
- grapheme_strstr() - Retorna la parte de una cadena a partir de una ocurrencia, insensible a mayúsculas/minúsculas
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_strripos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strripos — Encuentra la posición del último grafema, insensible a mayúsculas/minúsculas

### Descripción

Estilo procedimental

function grapheme_strripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

Encuentra la posición del último grafema, realizando una búsqueda insensible a mayúsculas/minúsculas.

### Parámetros

`haystack`

  La cadena a estudiar. Debe estar en formato UTF-8 válido.

`needle`

  La cadena a buscar. Debe estar en formato UTF-8 válido.

`offset`

  El argumento `offset` permite especificar la posición en `haystack` donde comienza la búsqueda, expresada en grafemas (y no en bytes o caracteres). La posición devuelta siempre se da con respecto al inicio de `haystack`, independientemente del valor de `offset`.

`locale`
  La configuración regional a utilizar.

### Valores devueltos

Devuelve la posición en forma de entero. Si `needle` no es encontrado, grapheme_strripos() devuelve `false`.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | Se ha añadido el parámetro opcional `locale`.

### Ejemplos

Ejemplo #1 Ejemplo con grapheme_strripos()

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) forma normalizada "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) forma normalizada "D"
    $char_O_diaeresis_nfd = "O\xCC\x88"; // 'LATIN CAPITAL LETTER O WITH DIAERESIS' (U+00D6) forma normalizada "D"

    print grapheme_strripos( $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_o_diaeresis_nfd, $char_O_diaeresis_nfd);

    ?>

El ejemplo anterior mostrará:

    2

### Ver también

- grapheme_stripos() - Encuentra la posición en grafema de la primera ocurrencia en una cadena, insensible a mayúsculas/minúsculas
- grapheme_stristr() - Devuelve la parte de una cadena a partir de una ocurrencia
- grapheme_strpos() - Encuentra la posición del primer grafema
- grapheme_strrpos() - Encuentra la posición del último grafema
- grapheme_strstr() - Retorna la parte de una cadena a partir de una ocurrencia, insensible a mayúsculas/minúsculas
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_strrpos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strrpos — Encuentra la posición del último grafema

### Descripción

Estilo procedimental

function grapheme_strrpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

Encuentra la posición del último grafema, realizando una búsqueda sensible a mayúsculas y minúsculas.

### Parámetros

`haystack`

  La cadena a estudiar. Debe estar en formato UTF-8 válido.

`needle`

  La cadena a buscar. Debe estar en formato UTF-8 válido.

`offset`

  El argumento `offset` permite especificar la posición en la `haystack` donde comienza la búsqueda, expresada en grafemas (y no en octetos o caracteres). La posición devuelta siempre se da con respecto al inicio de `haystack`, independientemente del valor de `offset`.

`locale`
  La configuración regional a utilizar.

### Valores devueltos

Devuelve la posición en forma de entero. Si `needle` no es encontrado, grapheme_strrpos() devuelve `false`.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | Se ha añadido el parámetro opcional `locale`.

### Ejemplos

Ejemplo #1 Ejemplo con grapheme_strrpos()

    <?php
    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) forma normalizada "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) forma normalizada "D"

    print grapheme_strrpos( $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_o_diaeresis_nfd, $char_o_diaeresis_nfd);
    ?>

El ejemplo anterior mostrará:

    2

### Ver también

- grapheme_stripos() - Encuentra la posición en grafema de la primera ocurrencia en una cadena, insensible a mayúsculas/minúsculas
- grapheme_stristr() - Devuelve la parte de una cadena a partir de una ocurrencia
- grapheme_strpos() - Encuentra la posición del primer grafema
- grapheme_strripos() - Encuentra la posición del último grafema, insensible a mayúsculas/minúsculas
- grapheme_strstr() - Retorna la parte de una cadena a partir de una ocurrencia, insensible a mayúsculas/minúsculas
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_strstr

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strstr — Retorna la parte de una cadena a partir de una ocurrencia, insensible a mayúsculas/minúsculas

### Descripción

Estilo procedimental

function grapheme_strstr(
string `$haystack`,
string `$needle`,
bool `$beforeNeedle` = `false`,
string `$locale` = ""
): string|false

Retorna la parte de una cadena a partir de la primera ocurrencia de `needle` (sensible a mayúsculas/minúsculas), y hasta el final de la cadena (`needle` incluido).

### Parámetros

`haystack`

  La cadena a estudiar. Debe ser válida UTF-8.

`needle`

  La cadena a buscar. Debe ser válida UTF-8.

`beforeNeedle`

  Si `true`, grapheme_strstr() retorna la parte de la `haystack` antes de la primera ocurrencia de la `needle` (excluyendo el `needle`).

`locale`
  La configuración regional a utilizar.

### Valores devueltos

Retorna la porción de la `haystack` o `false` si `needle` no es encontrado.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | Se ha añadido el parámetro opcional `locale`.

### Ejemplos

Ejemplo #1 Ejemplo con grapheme_strstr()

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) forma de normalización "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) forma de normalización "D"

    print urlencode(grapheme_stristr( $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_a_ring_nfd, $char_o_diaeresis_nfd));

    ?>

El ejemplo anterior mostrará:

    o%CC%88a%CC%8A

### Ver también

- grapheme_stristr() - Devuelve la parte de una cadena a partir de una ocurrencia
- grapheme_stripos() - Encuentra la posición en grafema de la primera ocurrencia en una cadena, insensible a mayúsculas/minúsculas
- grapheme_strpos() - Encuentra la posición del primer grafema
- grapheme_strripos() - Encuentra la posición del último grafema, insensible a mayúsculas/minúsculas
- grapheme_strrpos() - Encuentra la posición del último grafema
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_substr

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_substr — Devuelve una parte de un string

### Descripción

Estilo procedimental

function grapheme_substr(
string `$string`,
int `$offset`,
?int `$length` = `null`,
string `$locale` = ""
): string|false

Devuelve una parte de un string.

### Parámetros

`string`

  El string a cortar. Debe ser UTF-8 y válido.

`offset`

  Posición de inicio en unidades de grafema por defecto. Si `offset` es estrictamente positivo, el string devuelto comenzará en la `offset` ésima posición en `string`, contando desde cero. Si `offset` es negativo, el string devuelto comenzará en la `offset` ésima unidad de grafema desde el final del string.

`length`

  El tamaño del sub-string a extraer, en unidades de grafema. Si `length` es dado y positivo, el string devuelto contendrá como máximo `length` grafemas, comenzando en `offset` (dependiendo del tamaño del string). Si `length` es proporcionado y es negativo, entonces se omitirán tantos grafemas desde el final del string (después de que la posición de inicio haya sido calculada, cuando `offset` también es negativo). Si `offset` denota una posición más allá del final del string, se devuelve un string vacío.

`locale`
  La configuración regional a utilizar.

### Valores devueltos

Devuelve la parte del string extraída de `string`, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | Se ha añadido el parámetro opcional `locale`.
8.0.0 | La función ahora corrige sistemáticamente los desplazamientos fuera de límites a los límites del string. Anteriormente, `false` era devuelto en lugar de un string vacío en algunos casos.

### Ejemplos

Ejemplo #1 Ejemplo con grapheme_substr()

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"

    print urlencode(grapheme_substr( "ao" . $char_a_ring_nfd . "bc" . $char_o_diaeresis_nfd . "O", 2, -1 ));
    ?>

El ejemplo anterior mostrará:

    a%CC%8Abco%CC%88

### Ver también

- grapheme_extract() - Extrae un grupo de grafemas de una cadena UTF-8
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

## Tabla de contenidos

- grapheme_extract — Extrae un grupo de grafemas de una cadena UTF-8
- grapheme_str_split — Divide una string en un array
- grapheme_stripos — Encuentra la posición en grafema de la primera ocurrencia en una cadena, insensible a mayúsculas/minúsculas
- grapheme_stristr — Devuelve la parte de una cadena a partir de una ocurrencia
- grapheme_strlen — Lee la longitud de una cadena en número de grafemas
- grapheme_strpos — Encuentra la posición del primer grafema
- grapheme_strripos — Encuentra la posición del último grafema, insensible a mayúsculas/minúsculas
- grapheme_strrpos — Encuentra la posición del último grafema
- grapheme_strstr — Retorna la parte de una cadena a partir de una ocurrencia, insensible a mayúsculas/minúsculas
- grapheme_substr — Devuelve una parte de un string

# Funciones de IDN

# idn_to_ascii

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.2, PECL idn >= 0.1)

idn_to_ascii — Convierte un nombre de dominio al formato IDNA ASCII

### Descripción

Estilo procedimental

function idn_to_ascii(
string `$domain`,
int `$flags` = `IDNA_DEFAULT`,
int `$variant` = `INTL_IDNA_VARIANT_UTS46`,
array `&$idna_info` = `null`
): string|false

Esta función convierte un nombre de dominio Unicode a un formato ASCII compatible con IDNA, en minúsculas.

### Parámetros

`domain`

  El dominio a convertir, que debe estar codificado en UTF-8.

`flags`

  Opciones de conversión - combinación de constantes IDNA_*. (excepto las constantes IDNA_ERROR_*).

`variant`

  Puede ser `INTL_IDNA_VARIANT_2003` (obsoleto a partir de PHP 7.2.0) para IDNA 2003, o `INTL_IDNA_VARIANT_UTS46` (solo disponible a partir de ICU 4.6) para UTS #46.

`idna_info`

  Este parámetro solo puede ser utilizado si la constante `INTL_IDNA_VARIANT_UTS46` ha sido utilizada en el parámetro `variant`. En este caso, será un array con la clave `'result'` conteniendo el resultado de la transformación, la clave `'isTransitionalDifferent'` conteniendo un booleano indicando si se ha utilizado el mecanismo transicional UTS #46 que ha alterado o no el resultado, y la clave `'errors'` conteniendo un int representando un conjunto de bits de las constantes de error IDNA_ERROR_*.

### Valores devueltos

El nombre de dominio codificado en formato ASCII-compatible. o `false` si ocurre un error

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Ahora lanza un ValueError si el parámetro `domain` está vacío.
8.4.0 | Ahora lanza un ValueError si el parámetro `variant` no es `INTL_IDNA_VARIANT_UTS46`.
7.4.0 | El valor por defecto del parámetro `variant` es ahora `INTL_IDNA_VARIANT_UTS46` en lugar de la constante `INTL_IDNA_VARIANT_2003` depreciada.
7.2.0 | `INTL_IDNA_VARIANT_2003` ha sido depreciado; utilizar `INTL_IDNA_VARIANT_UTS46` en su lugar.

### Ejemplos

Ejemplo #1 Ejemplo con idn_to_ascii()

    <?php

    echo idn_to_ascii('täst.de');
    ?>

El ejemplo anterior mostrará:

    xn--tst-qla.de

Ejemplo #2 Los nombres de dominio completamente ASCII son simplemente convertidos a minúsculas

    <?php

    var_dump(idn_to_ascii('Example.com'));

    ?>

El ejemplo anterior mostrará:

    string(11) "example.com"

### Ver también

- idn_to_utf8() - Convierte el nombre de dominio IDNA ASCII a Unicode

# idn_to_utf8

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.2, PECL idn >= 0.1)

idn_to_utf8 — Convierte el nombre de dominio IDNA ASCII a Unicode

### Descripción

Estilo procedimental

function idn_to_utf8(
string `$domain`,
int `$flags` = `IDNA_DEFAULT`,
int `$variant` = `INTL_IDNA_VARIANT_UTS46`,
array `&$idna_info` = `null`
): string|false

Esta función convierte el nombre de dominio en formato IDNA ASCII-compatible a Unicode, codificado en UTF-8.

### Parámetros

`domain`

  Dominio a convertir desde el formato IDNA ASCII-compatible.

`flags`

  Opciones de conversión - una combinación de las constantes IDNA_* (excepto las constantes IDNA_ERROR_*).

`variant`

  Puede ser `INTL_IDNA_VARIANT_2003` (obsoleto a partir de PHP 7.2.0) para IDNA 2003, o `INTL_IDNA_VARIANT_UTS46` (solo disponible a partir de ICU 4.6) para UTS #46.

`idna_info`

  Este parámetro solo puede ser utilizado si la constante `INTL_IDNA_VARIANT_UTS46` ha sido utilizada como parámetro para `variant`. En este caso, este parámetro será rellenado por un array donde la clave `'result'` contendrá el resultado de la transformación, la clave `'isTransitionalDifferent'` contendrá un booleano indicando si el uso del mecanismo transicional UTS #46 ha alterado o no el resultado, y la clave `'errors'` contendrá un int representando un juego de bits de constantes IDNA_ERROR_*.

### Valores devueltos

Nombre de dominio en Unicode, codificado UTF-8. o `false` si ocurre un error

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Ahora lanza un ValueError si el parámetro `domain` está vacío.
8.4.0 | Ahora lanza un ValueError si el parámetro `variant` no es `INTL_IDNA_VARIANT_UTS46`.
7.4.0 | El valor por defecto del parámetro `variant` es ahora `INTL_IDNA_VARIANT_UTS46` en lugar de la constante `INTL_IDNA_VARIANT_2003` deprecada.
7.2.0 | `INTL_IDNA_VARIANT_2003` ha sido deprecado; utilizar `INTL_IDNA_VARIANT_UTS46` en su lugar.

### Ejemplos

Ejemplo #1 Ejemplo con idn_to_utf8()

    <?php

    echo idn_to_utf8('xn--tst-qla.de');

    ?>

El ejemplo anterior mostrará:

    täst.de

### Ver también

- idn_to_ascii() - Convierte un nombre de dominio al formato IDNA ASCII

## Tabla de contenidos

- idn_to_ascii — Convierte un nombre de dominio al formato IDNA ASCII
- idn_to_utf8 — Convierte el nombre de dominio IDNA ASCII a Unicode

# IntlChar

(PHP 7, PHP 8)

## Introducción

IntlChar proporciona acceso a un conjunto de métodos utilitarios que pueden ser utilizados para acceder a información sobre los caracteres Unicode.

Los métodos y las constantes respetan estrictamente los nombres y el comportamiento utilizados por la biblioteca ICU subyacente.

## Sinopsis de la Clase

class IntlChar {
/* Constantes */
public const string UNICODE_VERSION;
public const int CODEPOINT_MIN;
public const int CODEPOINT_MAX;
public const float NO_NUMERIC_VALUE;
public const int PROPERTY_ALPHABETIC;
public const int PROPERTY_BINARY_START;
public const int PROPERTY_ASCII_HEX_DIGIT;
public const int PROPERTY_BIDI_CONTROL;
public const int PROPERTY_BIDI_MIRRORED;
public const int PROPERTY_DASH;
public const int PROPERTY_DEFAULT_IGNORABLE_CODE_POINT;
public const int PROPERTY_DEPRECATED;
public const int PROPERTY_DIACRITIC;
public const int PROPERTY_EXTENDER;
public const int PROPERTY_FULL_COMPOSITION_EXCLUSION;
public const int PROPERTY_GRAPHEME_BASE;
public const int PROPERTY_GRAPHEME_EXTEND;
public const int PROPERTY_GRAPHEME_LINK;
public const int PROPERTY_HEX_DIGIT;
public const int PROPERTY_HYPHEN;
public const int PROPERTY_ID_CONTINUE;
public const int PROPERTY_ID_START;
public const int PROPERTY_IDEOGRAPHIC;
public const int PROPERTY_IDS_BINARY_OPERATOR;
public const int PROPERTY_IDS_TRINARY_OPERATOR;
public const int PROPERTY_IDS_UNARY_OPERATOR;
public const int PROPERTY_ID_COMPAT_MATH_START;
public const int PROPERTY_ID_COMPAT_MATH_CONTINUE;
public const int PROPERTY_JOIN_CONTROL;
public const int PROPERTY_LOGICAL_ORDER_EXCEPTION;
public const int PROPERTY_LOWERCASE;
public const int PROPERTY_MATH;
public const int PROPERTY_NONCHARACTER_CODE_POINT;
public const int PROPERTY_QUOTATION_MARK;
public const int PROPERTY_RADICAL;
public const int PROPERTY_SOFT_DOTTED;
public const int PROPERTY_TERMINAL_PUNCTUATION;
public const int PROPERTY_UNIFIED_IDEOGRAPH;
public const int PROPERTY_UPPERCASE;
public const int PROPERTY_WHITE_SPACE;
public const int PROPERTY_XID_CONTINUE;
public const int PROPERTY_XID_START;
public const int PROPERTY_CASE_SENSITIVE;
public const int PROPERTY_S_TERM;
public const int PROPERTY_VARIATION_SELECTOR;
public const int PROPERTY_NFD_INERT;
public const int PROPERTY_NFKD_INERT;
public const int PROPERTY_NFC_INERT;
public const int PROPERTY_NFKC_INERT;
public const int PROPERTY_SEGMENT_STARTER;
public const int PROPERTY_PATTERN_SYNTAX;
public const int PROPERTY_PATTERN_WHITE_SPACE;
public const int PROPERTY_POSIX_ALNUM;
public const int PROPERTY_POSIX_BLANK;
public const int PROPERTY_POSIX_GRAPH;
public const int PROPERTY_POSIX_PRINT;
public const int PROPERTY_POSIX_XDIGIT;
public const int PROPERTY_CASED;
public const int PROPERTY_CASE_IGNORABLE;
public const int PROPERTY_CHANGES_WHEN_LOWERCASED;
public const int PROPERTY_CHANGES_WHEN_UPPERCASED;
public const int PROPERTY_CHANGES_WHEN_TITLECASED;
public const int PROPERTY_CHANGES_WHEN_CASEFOLDED;
public const int PROPERTY_CHANGES_WHEN_CASEMAPPED;
public const int PROPERTY_CHANGES_WHEN_NFKC_CASEFOLDED;
public const int PROPERTY_BINARY_LIMIT;
public const int PROPERTY_BIDI_CLASS;
public const int PROPERTY_INT_START;
public const int PROPERTY_BLOCK;
public const int PROPERTY_CANONICAL_COMBINING_CLASS;
public const int PROPERTY_DECOMPOSITION_TYPE;
public const int PROPERTY_EAST_ASIAN_WIDTH;
public const int PROPERTY_GENERAL_CATEGORY;
public const int PROPERTY_JOINING_GROUP;
public const int PROPERTY_JOINING_TYPE;
public const int PROPERTY_LINE_BREAK;
public const int PROPERTY_NUMERIC_TYPE;
public const int PROPERTY_SCRIPT;
public const int PROPERTY_HANGUL_SYLLABLE_TYPE;
public const int PROPERTY_NFD_QUICK_CHECK;
public const int PROPERTY_NFKD_QUICK_CHECK;
public const int PROPERTY_NFC_QUICK_CHECK;
public const int PROPERTY_NFKC_QUICK_CHECK;
public const int PROPERTY_LEAD_CANONICAL_COMBINING_CLASS;
public const int PROPERTY_TRAIL_CANONICAL_COMBINING_CLASS;
public const int PROPERTY_GRAPHEME_CLUSTER_BREAK;
public const int PROPERTY_SENTENCE_BREAK;
public const int PROPERTY_WORD_BREAK;
public const int PROPERTY_BIDI_PAIRED_BRACKET_TYPE;
public const int PROPERTY_INT_LIMIT;
public const int PROPERTY_GENERAL_CATEGORY_MASK;
public const int PROPERTY_MASK_START;
public const int PROPERTY_MASK_LIMIT;
public const int PROPERTY_NUMERIC_VALUE;
public const int PROPERTY_DOUBLE_START;
public const int PROPERTY_DOUBLE_LIMIT;
public const int PROPERTY_AGE;
public const int PROPERTY_STRING_START;
public const int PROPERTY_BIDI_MIRRORING_GLYPH;
public const int PROPERTY_CASE_FOLDING;
public const int PROPERTY_ISO_COMMENT;
public const int PROPERTY_LOWERCASE_MAPPING;
public const int PROPERTY_NAME;
public const int PROPERTY_SIMPLE_CASE_FOLDING;
public const int PROPERTY_SIMPLE_LOWERCASE_MAPPING;
public const int PROPERTY_SIMPLE_TITLECASE_MAPPING;
public const int PROPERTY_SIMPLE_UPPERCASE_MAPPING;
public const int PROPERTY_TITLECASE_MAPPING;
public const int PROPERTY_UNICODE_1_NAME;
public const int PROPERTY_UPPERCASE_MAPPING;
public const int PROPERTY_BIDI_PAIRED_BRACKET;
public const int PROPERTY_STRING_LIMIT;
public const int PROPERTY_SCRIPT_EXTENSIONS;
public const int PROPERTY_OTHER_PROPERTY_START;
public const int PROPERTY_OTHER_PROPERTY_LIMIT;
public const int PROPERTY_INVALID_CODE;
public const int CHAR_CATEGORY_UNASSIGNED;
public const int CHAR_CATEGORY_GENERAL_OTHER_TYPES;
public const int CHAR_CATEGORY_UPPERCASE_LETTER;
public const int CHAR_CATEGORY_LOWERCASE_LETTER;
public const int CHAR_CATEGORY_TITLECASE_LETTER;
public const int CHAR_CATEGORY_MODIFIER_LETTER;
public const int CHAR_CATEGORY_OTHER_LETTER;
public const int CHAR_CATEGORY_NON_SPACING_MARK;
public const int CHAR_CATEGORY_ENCLOSING_MARK;
public const int CHAR_CATEGORY_COMBINING_SPACING_MARK;
public const int CHAR_CATEGORY_DECIMAL_DIGIT_NUMBER;
public const int CHAR_CATEGORY_LETTER_NUMBER;
public const int CHAR_CATEGORY_OTHER_NUMBER;
public const int CHAR_CATEGORY_SPACE_SEPARATOR;
public const int CHAR_CATEGORY_LINE_SEPARATOR;
public const int CHAR_CATEGORY_PARAGRAPH_SEPARATOR;
public const int CHAR_CATEGORY_CONTROL_CHAR;
public const int CHAR_CATEGORY_FORMAT_CHAR;
public const int CHAR_CATEGORY_PRIVATE_USE_CHAR;
public const int CHAR_CATEGORY_SURROGATE;
public const int CHAR_CATEGORY_DASH_PUNCTUATION;
public const int CHAR_CATEGORY_START_PUNCTUATION;
public const int CHAR_CATEGORY_END_PUNCTUATION;
public const int CHAR_CATEGORY_CONNECTOR_PUNCTUATION;
public const int CHAR_CATEGORY_OTHER_PUNCTUATION;
public const int CHAR_CATEGORY_MATH_SYMBOL;
public const int CHAR_CATEGORY_CURRENCY_SYMBOL;
public const int CHAR_CATEGORY_MODIFIER_SYMBOL;
public const int CHAR_CATEGORY_OTHER_SYMBOL;
public const int CHAR_CATEGORY_INITIAL_PUNCTUATION;
public const int CHAR_CATEGORY_FINAL_PUNCTUATION;
public const int CHAR_CATEGORY_CHAR_CATEGORY_COUNT;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT;
public const int CHAR_DIRECTION_EUROPEAN_NUMBER;
public const int CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR;
public const int CHAR_DIRECTION_EUROPEAN_NUMBER_TERMINATOR;
public const int CHAR_DIRECTION_ARABIC_NUMBER;
public const int CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR;
public const int CHAR_DIRECTION_BLOCK_SEPARATOR;
public const int CHAR_DIRECTION_SEGMENT_SEPARATOR;
public const int CHAR_DIRECTION_WHITE_SPACE_NEUTRAL;
public const int CHAR_DIRECTION_OTHER_NEUTRAL;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT_EMBEDDING;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT_OVERRIDE;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_ARABIC;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_EMBEDDING;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_OVERRIDE;
public const int CHAR_DIRECTION_POP_DIRECTIONAL_FORMAT;
public const int CHAR_DIRECTION_DIR_NON_SPACING_MARK;
public const int CHAR_DIRECTION_BOUNDARY_NEUTRAL;
public const int CHAR_DIRECTION_FIRST_STRONG_ISOLATE;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT_ISOLATE;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_ISOLATE;
public const int CHAR_DIRECTION_POP_DIRECTIONAL_ISOLATE;
public const int CHAR_DIRECTION_CHAR_DIRECTION_COUNT;
public const int BLOCK_CODE_NO_BLOCK;
public const int BLOCK_CODE_BASIC_LATIN;
public const int BLOCK_CODE_LATIN_1_SUPPLEMENT;
public const int BLOCK_CODE_LATIN_EXTENDED_A;
public const int BLOCK_CODE_LATIN_EXTENDED_B;
public const int BLOCK_CODE_IPA_EXTENSIONS;
public const int BLOCK_CODE_SPACING_MODIFIER_LETTERS;
public const int BLOCK_CODE_COMBINING_DIACRITICAL_MARKS;
public const int BLOCK_CODE_GREEK;
public const int BLOCK_CODE_CYRILLIC;
public const int BLOCK_CODE_ARMENIAN;
public const int BLOCK_CODE_HEBREW;
public const int BLOCK_CODE_ARABIC;
public const int BLOCK_CODE_SYRIAC;
public const int BLOCK_CODE_THAANA;
public const int BLOCK_CODE_DEVANAGARI;
public const int BLOCK_CODE_BENGALI;
public const int BLOCK_CODE_GURMUKHI;
public const int BLOCK_CODE_GUJARATI;
public const int BLOCK_CODE_ORIYA;
public const int BLOCK_CODE_TAMIL;
public const int BLOCK_CODE_TELUGU;
public const int BLOCK_CODE_KANNADA;
public const int BLOCK_CODE_MALAYALAM;
public const int BLOCK_CODE_SINHALA;
public const int BLOCK_CODE_THAI;
public const int BLOCK_CODE_LAO;
public const int BLOCK_CODE_TIBETAN;
public const int BLOCK_CODE_MYANMAR;
public const int BLOCK_CODE_GEORGIAN;
public const int BLOCK_CODE_HANGUL_JAMO;
public const int BLOCK_CODE_ETHIOPIC;
public const int BLOCK_CODE_CHEROKEE;
public const int BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS;
public const int BLOCK_CODE_OGHAM;
public const int BLOCK_CODE_RUNIC;
public const int BLOCK_CODE_KHMER;
public const int BLOCK_CODE_MONGOLIAN;
public const int BLOCK_CODE_LATIN_EXTENDED_ADDITIONAL;
public const int BLOCK_CODE_GREEK_EXTENDED;
public const int BLOCK_CODE_GENERAL_PUNCTUATION;
public const int BLOCK_CODE_SUPERSCRIPTS_AND_SUBSCRIPTS;
public const int BLOCK_CODE_CURRENCY_SYMBOLS;
public const int BLOCK_CODE_COMBINING_MARKS_FOR_SYMBOLS;
public const int BLOCK_CODE_LETTERLIKE_SYMBOLS;
public const int BLOCK_CODE_NUMBER_FORMS;
public const int BLOCK_CODE_ARROWS;
public const int BLOCK_CODE_MATHEMATICAL_OPERATORS;
public const int BLOCK_CODE_MISCELLANEOUS_TECHNICAL;
public const int BLOCK_CODE_CONTROL_PICTURES;
public const int BLOCK_CODE_OPTICAL_CHARACTER_RECOGNITION;
public const int BLOCK_CODE_ENCLOSED_ALPHANUMERICS;
public const int BLOCK_CODE_BOX_DRAWING;
public const int BLOCK_CODE_BLOCK_ELEMENTS;
public const int BLOCK_CODE_GEOMETRIC_SHAPES;
public const int BLOCK_CODE_MISCELLANEOUS_SYMBOLS;
public const int BLOCK_CODE_DINGBATS;
public const int BLOCK_CODE_BRAILLE_PATTERNS;
public const int BLOCK_CODE_CJK_RADICALS_SUPPLEMENT;
public const int BLOCK_CODE_KANGXI_RADICALS;
public const int BLOCK_CODE_IDEOGRAPHIC_DESCRIPTION_CHARACTERS;
public const int BLOCK_CODE_CJK_SYMBOLS_AND_PUNCTUATION;
public const int BLOCK_CODE_HIRAGANA;
public const int BLOCK_CODE_KATAKANA;
public const int BLOCK_CODE_BOPOMOFO;
public const int BLOCK_CODE_HANGUL_COMPATIBILITY_JAMO;
public const int BLOCK_CODE_KANBUN;
public const int BLOCK_CODE_BOPOMOFO_EXTENDED;
public const int BLOCK_CODE_ENCLOSED_CJK_LETTERS_AND_MONTHS;
public const int BLOCK_CODE_CJK_COMPATIBILITY;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_A;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS;
public const int BLOCK_CODE_YI_SYLLABLES;
public const int BLOCK_CODE_YI_RADICALS;
public const int BLOCK_CODE_HANGUL_SYLLABLES;
public const int BLOCK_CODE_HIGH_SURROGATES;
public const int BLOCK_CODE_HIGH_PRIVATE_USE_SURROGATES;
public const int BLOCK_CODE_LOW_SURROGATES;
public const int BLOCK_CODE_PRIVATE_USE_AREA;
public const int BLOCK_CODE_PRIVATE_USE;
public const int BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS;
public const int BLOCK_CODE_ALPHABETIC_PRESENTATION_FORMS;
public const int BLOCK_CODE_ARABIC_PRESENTATION_FORMS_A;
public const int BLOCK_CODE_COMBINING_HALF_MARKS;
public const int BLOCK_CODE_CJK_COMPATIBILITY_FORMS;
public const int BLOCK_CODE_SMALL_FORM_VARIANTS;
public const int BLOCK_CODE_ARABIC_PRESENTATION_FORMS_B;
public const int BLOCK_CODE_SPECIALS;
public const int BLOCK_CODE_HALFWIDTH_AND_FULLWIDTH_FORMS;
public const int BLOCK_CODE_OLD_ITALIC;
public const int BLOCK_CODE_GOTHIC;
public const int BLOCK_CODE_DESERET;
public const int BLOCK_CODE_BYZANTINE_MUSICAL_SYMBOLS;
public const int BLOCK_CODE_MUSICAL_SYMBOLS;
public const int BLOCK_CODE_MATHEMATICAL_ALPHANUMERIC_SYMBOLS;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_B;
public const int BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS_SUPPLEMENT;
public const int BLOCK_CODE_TAGS;
public const int BLOCK_CODE_CYRILLIC_SUPPLEMENT;
public const int BLOCK_CODE_CYRILLIC_SUPPLEMENTARY;
public const int BLOCK_CODE_TAGALOG;
public const int BLOCK_CODE_HANUNOO;
public const int BLOCK_CODE_BUHID;
public const int BLOCK_CODE_TAGBANWA;
public const int BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_A;
public const int BLOCK_CODE_SUPPLEMENTAL_ARROWS_A;
public const int BLOCK_CODE_SUPPLEMENTAL_ARROWS_B;
public const int BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_B;
public const int BLOCK_CODE_SUPPLEMENTAL_MATHEMATICAL_OPERATORS;
public const int BLOCK_CODE_KATAKANA_PHONETIC_EXTENSIONS;
public const int BLOCK_CODE_VARIATION_SELECTORS;
public const int BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_A;
public const int BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_B;
public const int BLOCK_CODE_LIMBU;
public const int BLOCK_CODE_TAI_LE;
public const int BLOCK_CODE_KHMER_SYMBOLS;
public const int BLOCK_CODE_PHONETIC_EXTENSIONS;
public const int BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_ARROWS;
public const int BLOCK_CODE_YIJING_HEXAGRAM_SYMBOLS;
public const int BLOCK_CODE_LINEAR_B_SYLLABARY;
public const int BLOCK_CODE_LINEAR_B_IDEOGRAMS;
public const int BLOCK_CODE_AEGEAN_NUMBERS;
public const int BLOCK_CODE_UGARITIC;
public const int BLOCK_CODE_SHAVIAN;
public const int BLOCK_CODE_OSMANYA;
public const int BLOCK_CODE_CYPRIOT_SYLLABARY;
public const int BLOCK_CODE_TAI_XUAN_JING_SYMBOLS;
public const int BLOCK_CODE_VARIATION_SELECTORS_SUPPLEMENT;
public const int BLOCK_CODE_ANCIENT_GREEK_MUSICAL_NOTATION;
public const int BLOCK_CODE_ANCIENT_GREEK_NUMBERS;
public const int BLOCK_CODE_ARABIC_SUPPLEMENT;
public const int BLOCK_CODE_BUGINESE;
public const int BLOCK_CODE_CJK_STROKES;
public const int BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_SUPPLEMENT;
public const int BLOCK_CODE_COPTIC;
public const int BLOCK_CODE_ETHIOPIC_EXTENDED;
public const int BLOCK_CODE_ETHIOPIC_SUPPLEMENT;
public const int BLOCK_CODE_GEORGIAN_SUPPLEMENT;
public const int BLOCK_CODE_GLAGOLITIC;
public const int BLOCK_CODE_KHAROSHTHI;
public const int BLOCK_CODE_MODIFIER_TONE_LETTERS;
public const int BLOCK_CODE_NEW_TAI_LUE;
public const int BLOCK_CODE_OLD_PERSIAN;
public const int BLOCK_CODE_PHONETIC_EXTENSIONS_SUPPLEMENT;
public const int BLOCK_CODE_SUPPLEMENTAL_PUNCTUATION;
public const int BLOCK_CODE_SYLOTI_NAGRI;
public const int BLOCK_CODE_TIFINAGH;
public const int BLOCK_CODE_VERTICAL_FORMS;
public const int BLOCK_CODE_NKO;
public const int BLOCK_CODE_BALINESE;
public const int BLOCK_CODE_LATIN_EXTENDED_C;
public const int BLOCK_CODE_LATIN_EXTENDED_D;
public const int BLOCK_CODE_PHAGS_PA;
public const int BLOCK_CODE_PHOENICIAN;
public const int BLOCK_CODE_CUNEIFORM;
public const int BLOCK_CODE_CUNEIFORM_NUMBERS_AND_PUNCTUATION;
public const int BLOCK_CODE_COUNTING_ROD_NUMERALS;
public const int BLOCK_CODE_SUNDANESE;
public const int BLOCK_CODE_LEPCHA;
public const int BLOCK_CODE_OL_CHIKI;
public const int BLOCK_CODE_CYRILLIC_EXTENDED_A;
public const int BLOCK_CODE_VAI;
public const int BLOCK_CODE_CYRILLIC_EXTENDED_B;
public const int BLOCK_CODE_SAURASHTRA;
public const int BLOCK_CODE_KAYAH_LI;
public const int BLOCK_CODE_REJANG;
public const int BLOCK_CODE_CHAM;
public const int BLOCK_CODE_ANCIENT_SYMBOLS;
public const int BLOCK_CODE_PHAISTOS_DISC;
public const int BLOCK_CODE_LYCIAN;
public const int BLOCK_CODE_CARIAN;
public const int BLOCK_CODE_LYDIAN;
public const int BLOCK_CODE_MAHJONG_TILES;
public const int BLOCK_CODE_DOMINO_TILES;
public const int BLOCK_CODE_SAMARITAN;
public const int BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS_EXTENDED;
public const int BLOCK_CODE_TAI_THAM;
public const int BLOCK_CODE_VEDIC_EXTENSIONS;
public const int BLOCK_CODE_LISU;
public const int BLOCK_CODE_BAMUM;
public const int BLOCK_CODE_COMMON_INDIC_NUMBER_FORMS;
public const int BLOCK_CODE_DEVANAGARI_EXTENDED;
public const int BLOCK_CODE_HANGUL_JAMO_EXTENDED_A;
public const int BLOCK_CODE_JAVANESE;
public const int BLOCK_CODE_MYANMAR_EXTENDED_A;
public const int BLOCK_CODE_TAI_VIET;
public const int BLOCK_CODE_MEETEI_MAYEK;
public const int BLOCK_CODE_HANGUL_JAMO_EXTENDED_B;
public const int BLOCK_CODE_IMPERIAL_ARAMAIC;
public const int BLOCK_CODE_OLD_SOUTH_ARABIAN;
public const int BLOCK_CODE_AVESTAN;
public const int BLOCK_CODE_INSCRIPTIONAL_PARTHIAN;
public const int BLOCK_CODE_INSCRIPTIONAL_PAHLAVI;
public const int BLOCK_CODE_OLD_TURKIC;
public const int BLOCK_CODE_RUMI_NUMERAL_SYMBOLS;
public const int BLOCK_CODE_KAITHI;
public const int BLOCK_CODE_EGYPTIAN_HIEROGLYPHS;
public const int BLOCK_CODE_ENCLOSED_ALPHANUMERIC_SUPPLEMENT;
public const int BLOCK_CODE_ENCLOSED_IDEOGRAPHIC_SUPPLEMENT;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_C;
public const int BLOCK_CODE_MANDAIC;
public const int BLOCK_CODE_BATAK;
public const int BLOCK_CODE_ETHIOPIC_EXTENDED_A;
public const int BLOCK_CODE_BRAHMI;
public const int BLOCK_CODE_BAMUM_SUPPLEMENT;
public const int BLOCK_CODE_KANA_SUPPLEMENT;
public const int BLOCK_CODE_PLAYING_CARDS;
public const int BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_PICTOGRAPHS;
public const int BLOCK_CODE_EMOTICONS;
public const int BLOCK_CODE_TRANSPORT_AND_MAP_SYMBOLS;
public const int BLOCK_CODE_ALCHEMICAL_SYMBOLS;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_D;
public const int BLOCK_CODE_ARABIC_EXTENDED_A;
public const int BLOCK_CODE_ARABIC_MATHEMATICAL_ALPHABETIC_SYMBOLS;
public const int BLOCK_CODE_CHAKMA;
public const int BLOCK_CODE_MEETEI_MAYEK_EXTENSIONS;
public const int BLOCK_CODE_MEROITIC_CURSIVE;
public const int BLOCK_CODE_MEROITIC_HIEROGLYPHS;
public const int BLOCK_CODE_MIAO;
public const int BLOCK_CODE_SHARADA;
public const int BLOCK_CODE_SORA_SOMPENG;
public const int BLOCK_CODE_SUNDANESE_SUPPLEMENT;
public const int BLOCK_CODE_TAKRI;
public const int BLOCK_CODE_BASSA_VAH;
public const int BLOCK_CODE_CAUCASIAN_ALBANIAN;
public const int BLOCK_CODE_COPTIC_EPACT_NUMBERS;
public const int BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_EXTENDED;
public const int BLOCK_CODE_DUPLOYAN;
public const int BLOCK_CODE_ELBASAN;
public const int BLOCK_CODE_GEOMETRIC_SHAPES_EXTENDED;
public const int BLOCK_CODE_GRANTHA;
public const int BLOCK_CODE_KHOJKI;
public const int BLOCK_CODE_KHUDAWADI;
public const int BLOCK_CODE_LATIN_EXTENDED_E;
public const int BLOCK_CODE_LINEAR_A;
public const int BLOCK_CODE_MAHAJANI;
public const int BLOCK_CODE_MANICHAEAN;
public const int BLOCK_CODE_MENDE_KIKAKUI;
public const int BLOCK_CODE_MODI;
public const int BLOCK_CODE_MRO;
public const int BLOCK_CODE_MYANMAR_EXTENDED_B;
public const int BLOCK_CODE_NABATAEAN;
public const int BLOCK_CODE_OLD_NORTH_ARABIAN;
public const int BLOCK_CODE_OLD_PERMIC;
public const int BLOCK_CODE_ORNAMENTAL_DINGBATS;
public const int BLOCK_CODE_PAHAWH_HMONG;
public const int BLOCK_CODE_PALMYRENE;
public const int BLOCK_CODE_PAU_CIN_HAU;
public const int BLOCK_CODE_PSALTER_PAHLAVI;
public const int BLOCK_CODE_SHORTHAND_FORMAT_CONTROLS;
public const int BLOCK_CODE_SIDDHAM;
public const int BLOCK_CODE_SINHALA_ARCHAIC_NUMBERS;
public const int BLOCK_CODE_SUPPLEMENTAL_ARROWS_C;
public const int BLOCK_CODE_TIRHUTA;
public const int BLOCK_CODE_WARANG_CITI;
public const int BLOCK_CODE_COUNT;
public const int BLOCK_CODE_INVALID_CODE;
public const int BPT_NONE;
public const int BPT_OPEN;
public const int BPT_CLOSE;
public const int BPT_COUNT;
public const int EA_NEUTRAL;
public const int EA_AMBIGUOUS;
public const int EA_HALFWIDTH;
public const int EA_FULLWIDTH;
public const int EA_NARROW;
public const int EA_WIDE;
public const int EA_COUNT;
public const int UNICODE_CHAR_NAME;
public const int UNICODE_10_CHAR_NAME;
public const int EXTENDED_CHAR_NAME;
public const int CHAR_NAME_ALIAS;
public const int CHAR_NAME_CHOICE_COUNT;
public const int SHORT_PROPERTY_NAME;
public const int LONG_PROPERTY_NAME;
public const int PROPERTY_NAME_CHOICE_COUNT;
public const int DT_NONE;
public const int DT_CANONICAL;
public const int DT_COMPAT;
public const int DT_CIRCLE;
public const int DT_FINAL;
public const int DT_FONT;
public const int DT_FRACTION;
public const int DT_INITIAL;
public const int DT_ISOLATED;
public const int DT_MEDIAL;
public const int DT_NARROW;
public const int DT_NOBREAK;
public const int DT_SMALL;
public const int DT_SQUARE;
public const int DT_SUB;
public const int DT_SUPER;
public const int DT_VERTICAL;
public const int DT_WIDE;
public const int DT_COUNT;
public const int JT_NON_JOINING;
public const int JT_JOIN_CAUSING;
public const int JT_DUAL_JOINING;
public const int JT_LEFT_JOINING;
public const int JT_RIGHT_JOINING;
public const int JT_TRANSPARENT;
public const int JT_COUNT;
public const int JG_NO_JOINING_GROUP;
public const int JG_AIN;
public const int JG_ALAPH;
public const int JG_ALEF;
public const int JG_BEH;
public const int JG_BETH;
public const int JG_DAL;
public const int JG_DALATH_RISH;
public const int JG_E;
public const int JG_FEH;
public const int JG_FINAL_SEMKATH;
public const int JG_GAF;
public const int JG_GAMAL;
public const int JG_HAH;
public const int JG_TEH_MARBUTA_GOAL;
public const int JG_HAMZA_ON_HEH_GOAL;
public const int JG_HE;
public const int JG_HEH;
public const int JG_HEH_GOAL;
public const int JG_HETH;
public const int JG_KAF;
public const int JG_KAPH;
public const int JG_KNOTTED_HEH;
public const int JG_LAM;
public const int JG_LAMADH;
public const int JG_MEEM;
public const int JG_MIM;
public const int JG_NOON;
public const int JG_NUN;
public const int JG_PE;
public const int JG_QAF;
public const int JG_QAPH;
public const int JG_REH;
public const int JG_REVERSED_PE;
public const int JG_SAD;
public const int JG_SADHE;
public const int JG_SEEN;
public const int JG_SEMKATH;
public const int JG_SHIN;
public const int JG_SWASH_KAF;
public const int JG_SYRIAC_WAW;
public const int JG_TAH;
public const int JG_TAW;
public const int JG_TEH_MARBUTA;
public const int JG_TETH;
public const int JG_WAW;
public const int JG_YEH;
public const int JG_YEH_BARREE;
public const int JG_YEH_WITH_TAIL;
public const int JG_YUDH;
public const int JG_YUDH_HE;
public const int JG_ZAIN;
public const int JG_FE;
public const int JG_KHAPH;
public const int JG_ZHAIN;
public const int JG_BURUSHASKI_YEH_BARREE;
public const int JG_FARSI_YEH;
public const int JG_NYA;
public const int JG_ROHINGYA_YEH;
public const int JG_MANICHAEAN_ALEPH;
public const int JG_MANICHAEAN_AYIN;
public const int JG_MANICHAEAN_BETH;
public const int JG_MANICHAEAN_DALETH;
public const int JG_MANICHAEAN_DHAMEDH;
public const int JG_MANICHAEAN_FIVE;
public const int JG_MANICHAEAN_GIMEL;
public const int JG_MANICHAEAN_HETH;
public const int JG_MANICHAEAN_HUNDRED;
public const int JG_MANICHAEAN_KAPH;
public const int JG_MANICHAEAN_LAMEDH;
public const int JG_MANICHAEAN_MEM;
public const int JG_MANICHAEAN_NUN;
public const int JG_MANICHAEAN_ONE;
public const int JG_MANICHAEAN_PE;
public const int JG_MANICHAEAN_QOPH;
public const int JG_MANICHAEAN_RESH;
public const int JG_MANICHAEAN_SADHE;
public const int JG_MANICHAEAN_SAMEKH;
public const int JG_MANICHAEAN_TAW;
public const int JG_MANICHAEAN_TEN;
public const int JG_MANICHAEAN_TETH;
public const int JG_MANICHAEAN_THAMEDH;
public const int JG_MANICHAEAN_TWENTY;
public const int JG_MANICHAEAN_WAW;
public const int JG_MANICHAEAN_YODH;
public const int JG_MANICHAEAN_ZAYIN;
public const int JG_STRAIGHT_WAW;
public const int JG_COUNT;
public const int GCB_OTHER;
public const int GCB_CONTROL;
public const int GCB_CR;
public const int GCB_EXTEND;
public const int GCB_L;
public const int GCB_LF;
public const int GCB_LV;
public const int GCB_LVT;
public const int GCB_T;
public const int GCB_V;
public const int GCB_SPACING_MARK;
public const int GCB_PREPEND;
public const int GCB_REGIONAL_INDICATOR;
public const int GCB_COUNT;
public const int WB_OTHER;
public const int WB_ALETTER;
public const int WB_FORMAT;
public const int WB_KATAKANA;
public const int WB_MIDLETTER;
public const int WB_MIDNUM;
public const int WB_NUMERIC;
public const int WB_EXTENDNUMLET;
public const int WB_CR;
public const int WB_EXTEND;
public const int WB_LF;
public const int WB_MIDNUMLET;
public const int WB_NEWLINE;
public const int WB_REGIONAL_INDICATOR;
public const int WB_HEBREW_LETTER;
public const int WB_SINGLE_QUOTE;
public const int WB_DOUBLE_QUOTE;
public const int WB_COUNT;
public const int SB_OTHER;
public const int SB_ATERM;
public const int SB_CLOSE;
public const int SB_FORMAT;
public const int SB_LOWER;
public const int SB_NUMERIC;
public const int SB_OLETTER;
public const int SB_SEP;
public const int SB_SP;
public const int SB_STERM;
public const int SB_UPPER;
public const int SB_CR;
public const int SB_EXTEND;
public const int SB_LF;
public const int SB_SCONTINUE;
public const int SB_COUNT;
public const int LB_UNKNOWN;
public const int LB_AMBIGUOUS;
public const int LB_ALPHABETIC;
public const int LB_BREAK_BOTH;
public const int LB_BREAK_AFTER;
public const int LB_BREAK_BEFORE;
public const int LB_MANDATORY_BREAK;
public const int LB_CONTINGENT_BREAK;
public const int LB_CLOSE_PUNCTUATION;
public const int LB_COMBINING_MARK;
public const int LB_CARRIAGE_RETURN;
public const int LB_EXCLAMATION;
public const int LB_GLUE;
public const int LB_HYPHEN;
public const int LB_IDEOGRAPHIC;
public const int LB_INSEPARABLE;
public const int LB_INSEPERABLE;
public const int LB_INFIX_NUMERIC;
public const int LB_LINE_FEED;
public const int LB_NONSTARTER;
public const int LB_NUMERIC;
public const int LB_OPEN_PUNCTUATION;
public const int LB_POSTFIX_NUMERIC;
public const int LB_PREFIX_NUMERIC;
public const int LB_QUOTATION;
public const int LB_COMPLEX_CONTEXT;
public const int LB_SURROGATE;
public const int LB_SPACE;
public const int LB_BREAK_SYMBOLS;
public const int LB_ZWSPACE;
public const int LB_NEXT_LINE;
public const int LB_WORD_JOINER;
public const int LB_H2;
public const int LB_H3;
public const int LB_JL;
public const int LB_JT;
public const int LB_JV;
public const int LB_CLOSE_PARENTHESIS;
public const int LB_CONDITIONAL_JAPANESE_STARTER;
public const int LB_HEBREW_LETTER;
public const int LB_REGIONAL_INDICATOR;
public const int LB_COUNT;
public const int NT_NONE;
public const int NT_DECIMAL;
public const int NT_DIGIT;
public const int NT_NUMERIC;
public const int NT_COUNT;
public const int HST_NOT_APPLICABLE;
public const int HST_LEADING_JAMO;
public const int HST_VOWEL_JAMO;
public const int HST_TRAILING_JAMO;
public const int HST_LV_SYLLABLE;
public const int HST_LVT_SYLLABLE;
public const int HST_COUNT;
public const int FOLD_CASE_DEFAULT;
public const int FOLD_CASE_EXCLUDE_SPECIAL_I;
/* Métodos */
public static function charAge(int|string `$codepoint`): ?array
public static function charDigitValue(int|string `$codepoint`): ?int
public static function charDirection(int|string `$codepoint`): ?int
public static function charFromName(string `$name`, int `$type` = `IntlChar::UNICODE_CHAR_NAME`): ?int
public static function charMirror(int|string `$codepoint`): int|string|null
public static function charName(int|string `$codepoint`, int `$type` = `IntlChar::UNICODE_CHAR_NAME`): ?string
public static function charType(int|string `$codepoint`): ?int
public static function chr(int|string `$codepoint`): ?string
public static function digit(int|string `$codepoint`, int `$base` = 10): int|false|null
public static function enumCharNames(
int|string `$start`,
int|string `$end`,
callable `$callback`,
int `$type` = `IntlChar::UNICODE_CHAR_NAME`
): bool
public static function enumCharTypes(callable `$callback`): void
public static function foldCase(int|string `$codepoint`, int `$options` = `IntlChar::FOLD_CASE_DEFAULT`): int|string|null
public static function forDigit(int `$digit`, int `$base` = 10): int
public static function getBidiPairedBracket(int|string `$codepoint`): int|string|null
public static function getBlockCode(int|string `$codepoint`): ?int
public static function getCombiningClass(int|string `$codepoint`): ?int
public static function getFC_NFKC_Closure(int|string `$codepoint`): string|false|null
public static function getIntPropertyMaxValue(int `$property`): int
public static function getIntPropertyMinValue(int `$property`): int
public static function getIntPropertyValue(int|string `$codepoint`, int `$property`): ?int
public static function getNumericValue(int|string `$codepoint`): ?float
public static function getPropertyEnum(string `$alias`): int
public static function getPropertyName(int `$property`, int `$type` = `IntlChar::LONG_PROPERTY_NAME`): string|false
public static function getPropertyValueEnum(int `$property`, string `$name`): int
public static function getPropertyValueName(int `$property`, int `$value`, int `$type` = `IntlChar::LONG_PROPERTY_NAME`): string|false
public static function getUnicodeVersion(): array
public static function hasBinaryProperty(int|string `$codepoint`, int `$property`): ?bool
public static function isalnum(int|string `$codepoint`): ?bool
public static function isalpha(int|string `$codepoint`): ?bool
public static function isbase(int|string `$codepoint`): ?bool
public static function isblank(int|string `$codepoint`): ?bool
public static function iscntrl(int|string `$codepoint`): ?bool
public static function isdefined(int|string `$codepoint`): ?bool
public static function isdigit(int|string `$codepoint`): ?bool
public static function isgraph(int|string `$codepoint`): ?bool
public static function isIDIgnorable(int|string `$codepoint`): ?bool
public static function isIDPart(int|string `$codepoint`): ?bool
public static function isIDStart(int|string `$codepoint`): ?bool
public static function isISOControl(int|string `$codepoint`): ?bool
public static function isJavaIDPart(int|string `$codepoint`): ?bool
public static function isJavaIDStart(int|string `$codepoint`): ?bool
public static function isJavaSpaceChar(int|string `$codepoint`): ?bool
public static function islower(int|string `$codepoint`): ?bool
public static function isMirrored(int|string `$codepoint`): ?bool
public static function isprint(int|string `$codepoint`): ?bool
public static function ispunct(int|string `$codepoint`): ?bool
public static function isspace(int|string `$codepoint`): ?bool
public static function istitle(int|string `$codepoint`): ?bool
public static function isUAlphabetic(int|string `$codepoint`): ?bool
public static function isULowercase(int|string `$codepoint`): ?bool
public static function isupper(int|string `$codepoint`): ?bool
public static function isUUppercase(int|string `$codepoint`): ?bool
public static function isUWhiteSpace(int|string `$codepoint`): ?bool
public static function isWhitespace(int|string `$codepoint`): ?bool
public static function isxdigit(int|string `$codepoint`): ?bool
public static function ord(int|string `$character`): ?int
public static function tolower(int|string `$codepoint`): int|string|null
public static function totitle(int|string `$codepoint`): int|string|null
public static function toupper(int|string `$codepoint`): int|string|null
}

## Constantes predefinidas

`IntlChar::UNICODE_VERSION` string

`IntlChar::CODEPOINT_MIN` int

`IntlChar::CODEPOINT_MAX` int

`IntlChar::NO_NUMERIC_VALUE` int

  Valor especial que es devuelto por IntlChar::getNumericValue() cuando no se define un valor numérico para un punto de código.

`IntlChar::PROPERTY_ALPHABETIC` int

`IntlChar::PROPERTY_BINARY_START` int

`IntlChar::PROPERTY_ASCII_HEX_DIGIT` int

`IntlChar::PROPERTY_BIDI_CONTROL` int

`IntlChar::PROPERTY_BIDI_MIRRORED` int

`IntlChar::PROPERTY_DASH` int

`IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT` int

`IntlChar::PROPERTY_DEPRECATED` int

`IntlChar::PROPERTY_DIACRITIC` int

`IntlChar::PROPERTY_EXTENDER` int

`IntlChar::PROPERTY_FULL_COMPOSITION_EXCLUSION` int

`IntlChar::PROPERTY_GRAPHEME_BASE` int

`IntlChar::PROPERTY_GRAPHEME_EXTEND` int

`IntlChar::PROPERTY_GRAPHEME_LINK` int

`IntlChar::PROPERTY_HEX_DIGIT` int

`IntlChar::PROPERTY_HYPHEN` int

`IntlChar::PROPERTY_ID_CONTINUE` int

`IntlChar::PROPERTY_ID_START` int

`IntlChar::PROPERTY_IDEOGRAPHIC` int

`IntlChar::PROPERTY_IDS_BINARY_OPERATOR` int

`IntlChar::PROPERTY_IDS_TRINARY_OPERATOR` int

`IntlChar::PROPERTY_IDS_UNARY_OPERATOR` int
  Para la determinación programática de secuencias de descripción ideográfica. Disponible a partir de PHP 8.4.0.
`IntlChar::PROPERTY_ID_COMPAT_MATH_START` int
  Utilizado en el perfil de identificador matemático en UAX 31. Disponible a partir de PHP 8.4.0.
`IntlChar::PROPERTY_ID_COMPAT_MATH_CONTINUE` int
  Utilizado en el perfil de identificador matemático en UAX 31. Disponible a partir de PHP 8.4.0.
`IntlChar::PROPERTY_JOIN_CONTROL` int

`IntlChar::PROPERTY_LOGICAL_ORDER_EXCEPTION` int

`IntlChar::PROPERTY_LOWERCASE` int

`IntlChar::PROPERTY_MATH` int

`IntlChar::PROPERTY_NONCHARACTER_CODE_POINT` int

`IntlChar::PROPERTY_QUOTATION_MARK` int

`IntlChar::PROPERTY_RADICAL` int

`IntlChar::PROPERTY_SOFT_DOTTED` int

`IntlChar::PROPERTY_TERMINAL_PUNCTUATION` int

`IntlChar::PROPERTY_UNIFIED_IDEOGRAPH` int

`IntlChar::PROPERTY_UPPERCASE` int

`IntlChar::PROPERTY_WHITE_SPACE` int

`IntlChar::PROPERTY_XID_CONTINUE` int

`IntlChar::PROPERTY_XID_START` int

`IntlChar::PROPERTY_CASE_SENSITIVE` int

`IntlChar::PROPERTY_S_TERM` int

`IntlChar::PROPERTY_VARIATION_SELECTOR` int

`IntlChar::PROPERTY_NFD_INERT` int

`IntlChar::PROPERTY_NFKD_INERT` int

`IntlChar::PROPERTY_NFC_INERT` int

`IntlChar::PROPERTY_NFKC_INERT` int

`IntlChar::PROPERTY_SEGMENT_STARTER` int

`IntlChar::PROPERTY_PATTERN_SYNTAX` int

`IntlChar::PROPERTY_PATTERN_WHITE_SPACE` int

`IntlChar::PROPERTY_POSIX_ALNUM` int

`IntlChar::PROPERTY_POSIX_BLANK` int

`IntlChar::PROPERTY_POSIX_GRAPH` int

`IntlChar::PROPERTY_POSIX_PRINT` int

`IntlChar::PROPERTY_POSIX_XDIGIT` int

`IntlChar::PROPERTY_CASED` int

`IntlChar::PROPERTY_CASE_IGNORABLE` int

`IntlChar::PROPERTY_CHANGES_WHEN_LOWERCASED` int

`IntlChar::PROPERTY_CHANGES_WHEN_UPPERCASED` int

`IntlChar::PROPERTY_CHANGES_WHEN_TITLECASED` int

`IntlChar::PROPERTY_CHANGES_WHEN_CASEFOLDED` int

`IntlChar::PROPERTY_CHANGES_WHEN_CASEMAPPED` int

`IntlChar::PROPERTY_CHANGES_WHEN_NFKC_CASEFOLDED` int

`IntlChar::PROPERTY_BINARY_LIMIT` int

`IntlChar::PROPERTY_BIDI_CLASS` int

`IntlChar::PROPERTY_INT_START` int

`IntlChar::PROPERTY_BLOCK` int

`IntlChar::PROPERTY_CANONICAL_COMBINING_CLASS` int

`IntlChar::PROPERTY_DECOMPOSITION_TYPE` int

`IntlChar::PROPERTY_EAST_ASIAN_WIDTH` int

`IntlChar::PROPERTY_GENERAL_CATEGORY` int

`IntlChar::PROPERTY_JOINING_GROUP` int

`IntlChar::PROPERTY_JOINING_TYPE` int

`IntlChar::PROPERTY_LINE_BREAK` int

`IntlChar::PROPERTY_NUMERIC_TYPE` int

`IntlChar::PROPERTY_SCRIPT` int

`IntlChar::PROPERTY_HANGUL_SYLLABLE_TYPE` int

`IntlChar::PROPERTY_NFD_QUICK_CHECK` int

`IntlChar::PROPERTY_NFKD_QUICK_CHECK` int

`IntlChar::PROPERTY_NFC_QUICK_CHECK` int

`IntlChar::PROPERTY_NFKC_QUICK_CHECK` int

`IntlChar::PROPERTY_LEAD_CANONICAL_COMBINING_CLASS` int

`IntlChar::PROPERTY_TRAIL_CANONICAL_COMBINING_CLASS` int

`IntlChar::PROPERTY_GRAPHEME_CLUSTER_BREAK` int

`IntlChar::PROPERTY_SENTENCE_BREAK` int

`IntlChar::PROPERTY_WORD_BREAK` int

`IntlChar::PROPERTY_BIDI_PAIRED_BRACKET_TYPE` int

`IntlChar::PROPERTY_INT_LIMIT` int

`IntlChar::PROPERTY_GENERAL_CATEGORY_MASK` int

`IntlChar::PROPERTY_MASK_START` int

`IntlChar::PROPERTY_MASK_LIMIT` int

`IntlChar::PROPERTY_NUMERIC_VALUE` int

`IntlChar::PROPERTY_DOUBLE_START` int

`IntlChar::PROPERTY_DOUBLE_LIMIT` int

`IntlChar::PROPERTY_AGE` int

`IntlChar::PROPERTY_STRING_START` int

`IntlChar::PROPERTY_BIDI_MIRRORING_GLYPH` int

`IntlChar::PROPERTY_CASE_FOLDING` int

`IntlChar::PROPERTY_ISO_COMMENT` int

`IntlChar::PROPERTY_LOWERCASE_MAPPING` int

`IntlChar::PROPERTY_NAME` int

`IntlChar::PROPERTY_SIMPLE_CASE_FOLDING` int

`IntlChar::PROPERTY_SIMPLE_LOWERCASE_MAPPING` int

`IntlChar::PROPERTY_SIMPLE_TITLECASE_MAPPING` int

`IntlChar::PROPERTY_SIMPLE_UPPERCASE_MAPPING` int

`IntlChar::PROPERTY_TITLECASE_MAPPING` int

`IntlChar::PROPERTY_UNICODE_1_NAME` int

`IntlChar::PROPERTY_UPPERCASE_MAPPING` int

`IntlChar::PROPERTY_BIDI_PAIRED_BRACKET` int

`IntlChar::PROPERTY_STRING_LIMIT` int

`IntlChar::PROPERTY_SCRIPT_EXTENSIONS` int

`IntlChar::PROPERTY_OTHER_PROPERTY_START` int

`IntlChar::PROPERTY_OTHER_PROPERTY_LIMIT` int

`IntlChar::PROPERTY_INVALID_CODE` int

`IntlChar::CHAR_CATEGORY_UNASSIGNED` int

`IntlChar::CHAR_CATEGORY_GENERAL_OTHER_TYPES` int

`IntlChar::CHAR_CATEGORY_UPPERCASE_LETTER` int

`IntlChar::CHAR_CATEGORY_LOWERCASE_LETTER` int

`IntlChar::CHAR_CATEGORY_TITLECASE_LETTER` int

`IntlChar::CHAR_CATEGORY_MODIFIER_LETTER` int

`IntlChar::CHAR_CATEGORY_OTHER_LETTER` int

`IntlChar::CHAR_CATEGORY_NON_SPACING_MARK` int

`IntlChar::CHAR_CATEGORY_ENCLOSING_MARK` int

`IntlChar::CHAR_CATEGORY_COMBINING_SPACING_MARK` int

`IntlChar::CHAR_CATEGORY_DECIMAL_DIGIT_NUMBER` int

`IntlChar::CHAR_CATEGORY_LETTER_NUMBER` int

`IntlChar::CHAR_CATEGORY_OTHER_NUMBER` int

`IntlChar::CHAR_CATEGORY_SPACE_SEPARATOR` int

`IntlChar::CHAR_CATEGORY_LINE_SEPARATOR` int

`IntlChar::CHAR_CATEGORY_PARAGRAPH_SEPARATOR` int

`IntlChar::CHAR_CATEGORY_CONTROL_CHAR` int

`IntlChar::CHAR_CATEGORY_FORMAT_CHAR` int

`IntlChar::CHAR_CATEGORY_PRIVATE_USE_CHAR` int

`IntlChar::CHAR_CATEGORY_SURROGATE` int

`IntlChar::CHAR_CATEGORY_DASH_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_START_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_END_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_CONNECTOR_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_OTHER_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_MATH_SYMBOL` int

`IntlChar::CHAR_CATEGORY_CURRENCY_SYMBOL` int

`IntlChar::CHAR_CATEGORY_MODIFIER_SYMBOL` int

`IntlChar::CHAR_CATEGORY_OTHER_SYMBOL` int

`IntlChar::CHAR_CATEGORY_INITIAL_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_FINAL_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_CHAR_CATEGORY_COUNT` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT` int

`IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER` int

`IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_TERMINATOR` int

`IntlChar::CHAR_DIRECTION_ARABIC_NUMBER` int

`IntlChar::CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_BLOCK_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_SEGMENT_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_WHITE_SPACE_NEUTRAL` int

`IntlChar::CHAR_DIRECTION_OTHER_NEUTRAL` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_EMBEDDING` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_OVERRIDE` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ARABIC` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_EMBEDDING` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_OVERRIDE` int

`IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_FORMAT` int

`IntlChar::CHAR_DIRECTION_DIR_NON_SPACING_MARK` int

`IntlChar::CHAR_DIRECTION_BOUNDARY_NEUTRAL` int

`IntlChar::CHAR_DIRECTION_FIRST_STRONG_ISOLATE` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_ISOLATE` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ISOLATE` int

`IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_ISOLATE` int

`IntlChar::CHAR_DIRECTION_CHAR_DIRECTION_COUNT` int

`IntlChar::BLOCK_CODE_NO_BLOCK` int

`IntlChar::BLOCK_CODE_BASIC_LATIN` int

`IntlChar::BLOCK_CODE_LATIN_1_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_A` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_B` int

`IntlChar::BLOCK_CODE_IPA_EXTENSIONS` int

`IntlChar::BLOCK_CODE_SPACING_MODIFIER_LETTERS` int

`IntlChar::BLOCK_CODE_COMBINING_DIACRITICAL_MARKS` int

`IntlChar::BLOCK_CODE_GREEK` int

`IntlChar::BLOCK_CODE_CYRILLIC` int

`IntlChar::BLOCK_CODE_ARMENIAN` int

`IntlChar::BLOCK_CODE_HEBREW` int

`IntlChar::BLOCK_CODE_ARABIC` int

`IntlChar::BLOCK_CODE_SYRIAC` int

`IntlChar::BLOCK_CODE_THAANA` int

`IntlChar::BLOCK_CODE_DEVANAGARI` int

`IntlChar::BLOCK_CODE_BENGALI` int

`IntlChar::BLOCK_CODE_GURMUKHI` int

`IntlChar::BLOCK_CODE_GUJARATI` int

`IntlChar::BLOCK_CODE_ORIYA` int

`IntlChar::BLOCK_CODE_TAMIL` int

`IntlChar::BLOCK_CODE_TELUGU` int

`IntlChar::BLOCK_CODE_KANNADA` int

`IntlChar::BLOCK_CODE_MALAYALAM` int

`IntlChar::BLOCK_CODE_SINHALA` int

`IntlChar::BLOCK_CODE_THAI` int

`IntlChar::BLOCK_CODE_LAO` int

`IntlChar::BLOCK_CODE_TIBETAN` int

`IntlChar::BLOCK_CODE_MYANMAR` int

`IntlChar::BLOCK_CODE_GEORGIAN` int

`IntlChar::BLOCK_CODE_HANGUL_JAMO` int

`IntlChar::BLOCK_CODE_ETHIOPIC` int

`IntlChar::BLOCK_CODE_CHEROKEE` int

`IntlChar::BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS` int

`IntlChar::BLOCK_CODE_OGHAM` int

`IntlChar::BLOCK_CODE_RUNIC` int

`IntlChar::BLOCK_CODE_KHMER` int

`IntlChar::BLOCK_CODE_MONGOLIAN` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_ADDITIONAL` int

`IntlChar::BLOCK_CODE_GREEK_EXTENDED` int

`IntlChar::BLOCK_CODE_GENERAL_PUNCTUATION` int

`IntlChar::BLOCK_CODE_SUPERSCRIPTS_AND_SUBSCRIPTS` int

`IntlChar::BLOCK_CODE_CURRENCY_SYMBOLS` int

`IntlChar::BLOCK_CODE_COMBINING_MARKS_FOR_SYMBOLS` int

`IntlChar::BLOCK_CODE_LETTERLIKE_SYMBOLS` int

`IntlChar::BLOCK_CODE_NUMBER_FORMS` int

`IntlChar::BLOCK_CODE_ARROWS` int

`IntlChar::BLOCK_CODE_MATHEMATICAL_OPERATORS` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_TECHNICAL` int

`IntlChar::BLOCK_CODE_CONTROL_PICTURES` int

`IntlChar::BLOCK_CODE_OPTICAL_CHARACTER_RECOGNITION` int

`IntlChar::BLOCK_CODE_ENCLOSED_ALPHANUMERICS` int

`IntlChar::BLOCK_CODE_BOX_DRAWING` int

`IntlChar::BLOCK_CODE_BLOCK_ELEMENTS` int

`IntlChar::BLOCK_CODE_GEOMETRIC_SHAPES` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS` int

`IntlChar::BLOCK_CODE_DINGBATS` int

`IntlChar::BLOCK_CODE_BRAILLE_PATTERNS` int

`IntlChar::BLOCK_CODE_CJK_RADICALS_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_KANGXI_RADICALS` int

`IntlChar::BLOCK_CODE_IDEOGRAPHIC_DESCRIPTION_CHARACTERS` int

`IntlChar::BLOCK_CODE_CJK_SYMBOLS_AND_PUNCTUATION` int

`IntlChar::BLOCK_CODE_HIRAGANA` int

`IntlChar::BLOCK_CODE_KATAKANA` int

`IntlChar::BLOCK_CODE_BOPOMOFO` int

`IntlChar::BLOCK_CODE_HANGUL_COMPATIBILITY_JAMO` int

`IntlChar::BLOCK_CODE_KANBUN` int

`IntlChar::BLOCK_CODE_BOPOMOFO_EXTENDED` int

`IntlChar::BLOCK_CODE_ENCLOSED_CJK_LETTERS_AND_MONTHS` int

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_A` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS` int

`IntlChar::BLOCK_CODE_YI_SYLLABLES` int

`IntlChar::BLOCK_CODE_YI_RADICALS` int

`IntlChar::BLOCK_CODE_HANGUL_SYLLABLES` int

`IntlChar::BLOCK_CODE_HIGH_SURROGATES` int

`IntlChar::BLOCK_CODE_HIGH_PRIVATE_USE_SURROGATES` int

`IntlChar::BLOCK_CODE_LOW_SURROGATES` int

`IntlChar::BLOCK_CODE_PRIVATE_USE_AREA` int

`IntlChar::BLOCK_CODE_PRIVATE_USE` int

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS` int

`IntlChar::BLOCK_CODE_ALPHABETIC_PRESENTATION_FORMS` int

`IntlChar::BLOCK_CODE_ARABIC_PRESENTATION_FORMS_A` int

`IntlChar::BLOCK_CODE_COMBINING_HALF_MARKS` int

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_FORMS` int

`IntlChar::BLOCK_CODE_SMALL_FORM_VARIANTS` int

`IntlChar::BLOCK_CODE_ARABIC_PRESENTATION_FORMS_B` int

  Bloque de las formas de presentación árabes B, incluyendo ligaduras adicionales y formas contextuales.

`IntlChar::BLOCK_CODE_SPECIALS` int

  Bloque reservado para caracteres especiales y no estandarizados.

`IntlChar::BLOCK_CODE_HALFWIDTH_AND_FULLWIDTH_FORMS` int

  Bloque de las formas de media anchura y anchura completa utilizadas principalmente en escrituras asiáticas.

`IntlChar::BLOCK_CODE_OLD_ITALIC` int

  Bloque de caracteres del antiguo alfabeto italiano utilizado en inscripciones italianas antiguas.

`IntlChar::BLOCK_CODE_GOTHIC` int

  Bloque de caracteres góticos utilizados en ciertas escrituras históricas.

`IntlChar::BLOCK_CODE_DESERET` int

  Bloque de caracteres Deseret utilizados en el alfabeto Deseret creado por la Iglesia de Jesucristo de los Santos de los Últimos Días.

`IntlChar::BLOCK_CODE_BYZANTINE_MUSICAL_SYMBOLS` int

  Bloque de símbolos musicales bizantinos utilizados en la notación musical histórica.

`IntlChar::BLOCK_CODE_MUSICAL_SYMBOLS` int

  Bloque de símbolos musicales utilizados en la notación musical moderna.

`IntlChar::BLOCK_CODE_MATHEMATICAL_ALPHANUMERIC_SYMBOLS` int

  Bloque de símbolos alfanuméricos matemáticos utilizados en expresiones y notaciones matemáticas.

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_B` int

  Bloque de ideogramas unificados CJK, extensión B, añadiendo un gran número de caracteres adicionales.

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS_SUPPLEMENT` int

  Bloque de ideogramas de compatibilidad CJK suplementario para caracteres adicionales.

`IntlChar::BLOCK_CODE_TAGS` int

  Bloque de caracteres de etiquetado utilizados para anotaciones textuales.

`IntlChar::BLOCK_CODE_CYRILLIC_SUPPLEMENT` int

  Bloque de caracteres cirílicos suplementarios añadiendo letras utilizadas en otras lenguas eslavas.

`IntlChar::BLOCK_CODE_CYRILLIC_SUPPLEMENTARY` int

  Bloque de caracteres cirílicos suplementarios utilizados para necesidades lingüísticas específicas.

`IntlChar::BLOCK_CODE_TAGALOG` int

  Bloque de caracteres Tagalog utilizados en la escritura Tagalog.

`IntlChar::BLOCK_CODE_HANUNOO` int

  Bloque de caracteres Hanunoo utilizados en la escritura Hanunoo.

`IntlChar::BLOCK_CODE_BUHID` int

  Bloque de caracteres Buhid utilizados en la escritura Buhid.

`IntlChar::BLOCK_CODE_TAGBANWA` int

  Bloque de caracteres Tagbanwa utilizados en la escritura Tagbanwa.

`IntlChar::BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_A` int

  Bloque de símbolos matemáticos diversos A utilizados en diversos contextos matemáticos.

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_ARROWS_A` int

  Bloque de flechas suplementarias A ofreciendo variantes adicionales de flechas.

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_ARROWS_B` int

  Bloque de flechas suplementarias B proporcionando aún más variantes de flechas.

`IntlChar::BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_B` int

  Bloque de símbolos matemáticos diversos B utilizados en dominios especializados de las matemáticas.

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_MATHEMATICAL_OPERATORS` int

  Bloque de operadores matemáticos suplementarios para operaciones avanzadas.

`IntlChar::BLOCK_CODE_KATAKANA_PHONETIC_EXTENSIONS` int

  Bloque de extensiones fonéticas Katakana para representar sonidos adicionales.

`IntlChar::BLOCK_CODE_VARIATION_SELECTORS` int

  Bloque de selectores de variación utilizados para especificar variantes de presentación de caracteres.

`IntlChar::BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_A` int

  Bloque suplementario de uso privado A para caracteres definidos por el usuario.

`IntlChar::BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_B` int

  Bloque suplementario de uso privado B para caracteres definidos por el usuario.

`IntlChar::BLOCK_CODE_LIMBU` int

  Bloque de caracteres Limbu utilizados en la escritura Limbu.

`IntlChar::BLOCK_CODE_TAI_LE` int

  Bloque de caracteres Tai Le utilizados en la escritura Tai Le.

`IntlChar::BLOCK_CODE_KHMER_SYMBOLS` int

  Bloque de símbolos Khmers utilizados en la escritura khmer.

`IntlChar::BLOCK_CODE_PHONETIC_EXTENSIONS` int

  Bloque de extensiones fonéticas que añaden caracteres para representar sonidos específicos.

`IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_ARROWS` int

  Bloque de símbolos diversos y flechas utilizadas en diversos contextos.

`IntlChar::BLOCK_CODE_YIJING_HEXAGRAM_SYMBOLS` int

  Bloque de símbolos de hexagramas del Yi Jing utilizados en textos tradicionales chinos.

`IntlChar::BLOCK_CODE_LINEAR_B_SYLLABARY` int

  Bloque de silabarios Linear B utilizados en la escritura minoica.

`IntlChar::BLOCK_CODE_LINEAR_B_IDEOGRAMS` int

  Bloque de ideogramas Linear B utilizados en la escritura minoica.

`IntlChar::BLOCK_CODE_AEGEAN_NUMBERS` int

`IntlChar::BLOCK_CODE_UGARITIC` int

`IntlChar::BLOCK_CODE_SHAVIAN` int

`IntlChar::BLOCK_CODE_OSMANYA` int

`IntlChar::BLOCK_CODE_CYPRIOT_SYLLABARY` int

  Bloque de silabarios cypriotas utilizados en la escritura chipriota antigua.

`IntlChar::BLOCK_CODE_TAI_XUAN_JING_SYMBOLS` int

  Bloque de símbolos Tai Xuan Jing utilizados en el manuscrito clásico chino Tai Xuan Jing.

`IntlChar::BLOCK_CODE_VARIATION_SELECTORS_SUPPLEMENT` int

  Bloque de selectores de variación adicionales utilizados para especificar variantes de presentación de caracteres.

`IntlChar::BLOCK_CODE_ANCIENT_GREEK_MUSICAL_NOTATION` int

  Bloque de notaciones musicales griegas antiguas utilizadas en las notaciones musicales de la antigua Grecia.

`IntlChar::BLOCK_CODE_ANCIENT_GREEK_NUMBERS` int

  Bloque de números griegos antiguos utilizados en inscripciones y documentos históricos griegos.

`IntlChar::BLOCK_CODE_ARABIC_SUPPLEMENT` int

  Bloque de suplementos árabes que añaden caracteres adicionales para escrituras árabes extendidas.

`IntlChar::BLOCK_CODE_BUGINESE` int

  Bloque de caracteres Buginese utilizados en la escritura Buginese de la isla de Sulawesi en Indonesia.

`IntlChar::BLOCK_CODE_CJK_STROKES` int

  Bloque de trazos CJK utilizados para la composición y descomposición de ideogramas chinos, japoneses y coreanos.

`IntlChar::BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_SUPPLEMENT` int

  Bloque de marcas diacríticas combinantes adicionales utilizadas para modificar caracteres base.

`IntlChar::BLOCK_CODE_COPTIC` int

  Bloque de caracteres coptos utilizados en la escritura copta de Egipto.

`IntlChar::BLOCK_CODE_ETHIOPIC_EXTENDED` int

  Bloque extendido de caracteres etíopes que añade letras adicionales para lenguas etíopes específicas.

`IntlChar::BLOCK_CODE_ETHIOPIC_SUPPLEMENT` int

  Bloque de suplementos etíopes que añaden caracteres adicionales para necesidades lingüísticas específicas.

`IntlChar::BLOCK_CODE_GEORGIAN_SUPPLEMENT` int

  Bloque de suplementos georgianos que añaden caracteres adicionales para la escritura georgiana.

`IntlChar::BLOCK_CODE_GLAGOLITIC` int

  Bloque de caracteres glagolíticos utilizados en el alfabeto glagolítico, uno de los primeros alfabetos eslavos.

`IntlChar::BLOCK_CODE_KHAROSHTHI` int

  Bloque de caracteres Kharoshthi utilizados en la escritura antigua del noroeste de la India.

`IntlChar::BLOCK_CODE_MODIFIER_TONE_LETTERS` int

  Bloque de letras modificadoras de tono utilizadas en ciertos idiomas para indicar variaciones tonales.

`IntlChar::BLOCK_CODE_NEW_TAI_LUE` int

  Bloque de caracteres New Tai Lue utilizados en la escritura Tai Lue para ciertos idiomas del sudeste asiático.

`IntlChar::BLOCK_CODE_OLD_PERSIAN` int

  Bloque de caracteres persas antiguos utilizados en la escritura del Imperio persa antiguo.

`IntlChar::BLOCK_CODE_PHONETIC_EXTENSIONS_SUPPLEMENT` int

  Bloque de extensiones fonéticas adicionales que añaden caracteres para representar sonidos específicos.

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_PUNCTUATION` int

  Bloque de puntuaciones adicionales utilizadas para diversos requisitos tipográficos.

`IntlChar::BLOCK_CODE_SYLOTI_NAGRI` int

  Bloque de caracteres Syloti Nagri utilizados en la escritura Syloti Nagri para ciertos idiomas de la India.

`IntlChar::BLOCK_CODE_TIFINAGH` int

  Bloque de caracteres Tifinagh utilizados en la escritura de las lenguas bereberes.

`IntlChar::BLOCK_CODE_VERTICAL_FORMS` int

  Bloque de formas verticales utilizadas en ciertas escrituras para la presentación vertical de caracteres.

`IntlChar::BLOCK_CODE_NKO` int

  Bloque de caracteres Nko utilizados en la escritura Nko para ciertos idiomas de África Occidental.

`IntlChar::BLOCK_CODE_BALINESE` int

  Bloque de caracteres balineses utilizados en la escritura balinesa de Indonesia.

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_C` int

  Bloque de extensiones latinas adicionales C que añaden caracteres adicionales para la escritura de idiomas que utilizan el alfabeto latino.

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_D` int

  Bloque de extensiones latinas adicionales D que añaden caracteres adicionales para la escritura de idiomas que utilizan el alfabeto latino.

`IntlChar::BLOCK_CODE_PHAGS_PA` int

  Bloque de caracteres Phags-pa utilizados en la escritura Phags-pa, un script histórico del Imperio mongol.

`IntlChar::BLOCK_CODE_PHOENICIAN` int

  Bloque de caracteres fenicios utilizados en la escritura fenicia de la antigüedad.

`IntlChar::BLOCK_CODE_CUNEIFORM` int

  Bloque de caracteres cuneiformes utilizados en la escritura cuneiforme de la antigua Mesopotamia.

`IntlChar::BLOCK_CODE_CUNEIFORM_NUMBERS_AND_PUNCTUATION` int

  Bloque de números y puntuaciones cuneiformes utilizados en la escritura cuneiforme.

`IntlChar::BLOCK_CODE_COUNTING_ROD_NUMERALS` int

  Bloque de cifras en varilla utilizadas en sistemas de numeración antiguos.

`IntlChar::BLOCK_CODE_SUNDANESE` int

  Bloque de caracteres sundaneses utilizados en la escritura sundanesa de Indonesia.

`IntlChar::BLOCK_CODE_LEPCHA` int

  Bloque de caracteres Lepcha utilizados en la escritura Lepcha del Himalaya.

`IntlChar::BLOCK_CODE_OL_CHIKI` int

  Bloque de caracteres Ol Chiki utilizados en la escritura Ol Chiki para el idioma Santali.

`IntlChar::BLOCK_CODE_CYRILLIC_EXTENDED_A` int

  Bloque de extensiones cirílicas A añadiendo caracteres adicionales para la escritura de lenguas eslavas y no eslavas.

`IntlChar::BLOCK_CODE_VAI` int

  Bloque de caracteres Vai utilizados en la escritura Vai de Sierra Leona.

`IntlChar::BLOCK_CODE_CYRILLIC_EXTENDED_B` int

  Bloque de extensiones cirílicas B añadiendo caracteres adicionales para la escritura de lenguas eslavas y no eslavas.

`IntlChar::BLOCK_CODE_SAURASHTRA` int

  Bloque de caracteres Saurashtra utilizados en la escritura Saurashtra de la India.

`IntlChar::BLOCK_CODE_KAYAH_LI` int

  Bloque de caracteres Kayah Li utilizados en la escritura Kayah Li para los idiomas Kayah en Birmania.

`IntlChar::BLOCK_CODE_REJANG` int

  Bloque de caracteres Rejang utilizados en la escritura Rejang de Indonesia.

`IntlChar::BLOCK_CODE_CHAM` int

  Bloque de caracteres Cham utilizados en la escritura Cham del Sudeste Asiático.

`IntlChar::BLOCK_CODE_ANCIENT_SYMBOLS` int

  Bloque de símbolos antiguos utilizados en diversos contextos históricos y culturales.

`IntlChar::BLOCK_CODE_PHAISTOS_DISC` int

  Bloque de caracteres del disco de Phaistos utilizados en la inscripción del disco de Phaistos, un artefacto minoico.

`IntlChar::BLOCK_CODE_LYCIAN` int

  Bloque de caracteres licios utilizados en la escritura licia de la antigua Licia.

`IntlChar::BLOCK_CODE_CARIAN` int

  Bloque de caracteres carios utilizados en la escritura caria de la antigua Caria.

`IntlChar::BLOCK_CODE_LYDIAN` int

  Bloque de caracteres lidios utilizados en la escritura lidia de la antigua Lidia.

`IntlChar::BLOCK_CODE_MAHJONG_TILES` int

  Bloque de fichas de Mahjong utilizadas en los juegos de Mahjong.

`IntlChar::BLOCK_CODE_DOMINO_TILES` int

  Bloque de fichas de dominó utilizadas en los juegos de dominó.

`IntlChar::BLOCK_CODE_SAMARITAN` int

  Bloque de caracteres samaritanos utilizados en la escritura samaritana.

`IntlChar::BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS_EXTENDED` int

  Bloque extendido de silabarios aborígenes canadienses unificados añadiendo caracteres adicionales para ciertos idiomas indígenas.

`IntlChar::BLOCK_CODE_TAI_THAM` int

  Bloque de caracteres Tai Tham utilizados en la escritura Tai Tham para ciertos idiomas del sudeste asiático.

`IntlChar::BLOCK_CODE_VEDIC_EXTENSIONS` int

  Bloque de extensiones védicas que añaden caracteres adicionales para textos védicos.

`IntlChar::BLOCK_CODE_LISU` int

  Bloque de caracteres Lisu utilizados en la escritura Lisu de ciertas regiones de Asia.

`IntlChar::BLOCK_CODE_BAMUM` int

  Bloque de caracteres Bamum utilizados en la escritura Bamum de Camerún.

`IntlChar::BLOCK_CODE_COMMON_INDIC_NUMBER_FORMS` int

  Bloque de formas numéricas indic comunes utilizadas en sistemas de numeración de idiomas indoarios.

`IntlChar::BLOCK_CODE_DEVANAGARI_EXTENDED` int

  Bloque extendido de caracteres Devanagari que añade caracteres adicionales para la escritura de idiomas que utilizan Devanagari.

`IntlChar::BLOCK_CODE_HANGUL_JAMO_EXTENDED_A` int

  Bloque extendido A de Jamo Hangul que añade caracteres adicionales para la escritura coreana.

`IntlChar::BLOCK_CODE_JAVANESE` int

  Bloque de caracteres javaneses utilizados en la escritura javanesa de Indonesia.

`IntlChar::BLOCK_CODE_MYANMAR_EXTENDED_A` int

  Bloque extendido A de caracteres Myanmar que añade caracteres adicionales para la escritura Myanmar.

`IntlChar::BLOCK_CODE_TAI_VIET` int

  Bloque de caracteres Tai Viet utilizados en la escritura Tai Viet para ciertos idiomas del sudeste asiático.

`IntlChar::BLOCK_CODE_MEETEI_MAYEK` int

  Bloque de caracteres Meetei Mayek utilizados en la escritura Meetei Mayek para el idioma Meitei.

`IntlChar::BLOCK_CODE_HANGUL_JAMO_EXTENDED_B` int

  Bloque extendido B de Jamo Hangul que añade caracteres adicionales para la escritura coreana.

`IntlChar::BLOCK_CODE_IMPERIAL_ARAMAIC` int

  Bloque de caracteres arameos imperiales utilizados en la escritura aramea antigua.

`IntlChar::BLOCK_CODE_OLD_SOUTH_ARABIAN` int

  Bloque de caracteres árabes del sur antiguos utilizados en la escritura árabe del sur antigua.

`IntlChar::BLOCK_CODE_AVESTAN` int

  Bloque de caracteres avestánicos utilizados en la escritura avestánica de textos zoroastrianos.

`IntlChar::BLOCK_CODE_INSCRIPTIONAL_PARTHIAN` int

  Bloque de caracteres partos inscriptionales utilizados en la escritura parta antigua.

`IntlChar::BLOCK_CODE_INSCRIPTIONAL_PAHLAVI` int

  Bloque de caracteres pahlavi inscriptionales utilizados en la escritura pahlavi de la antigua Persia.

`IntlChar::BLOCK_CODE_OLD_TURKIC` int

  Bloque de caracteres turcos antiguos utilizados en la escritura turca antigua.

`IntlChar::BLOCK_CODE_RUMI_NUMERAL_SYMBOLS` int

  Bloque de símbolos numéricos Rumi utilizados en el sistema de numeración Rumi.

`IntlChar::BLOCK_CODE_KAITHI` int

  Bloque de caracteres Kaithi utilizados en la escritura Kaithi de la India del Norte.

`IntlChar::BLOCK_CODE_EGYPTIAN_HIEROGLYPHS` int

  Bloque de jeroglíficos egipcios utilizados en la escritura egipcia antigua.

`IntlChar::BLOCK_CODE_ENCLOSED_ALPHANUMERIC_SUPPLEMENT` int

  Bloque de suplementos alfanuméricos encerrados añadiendo caracteres alfanuméricos en círculos u otras formas.

`IntlChar::BLOCK_CODE_ENCLOSED_IDEOGRAPHIC_SUPPLEMENT` int

  Bloque de suplementos ideográficos encerrados añadiendo ideogramas en círculos u otras formas.

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_C` int

  Bloque de ideogramas unificados CJK, extensión C, añadiendo aún más caracteres.

`IntlChar::BLOCK_CODE_MANDAIC` int

  Bloque de caracteres mandeos utilizados en la escritura mandea.

`IntlChar::BLOCK_CODE_BATAK` int

  Bloque de caracteres Batak utilizados en la escritura Batak de Indonesia.

`IntlChar::BLOCK_CODE_ETHIOPIC_EXTENDED_A` int

  Bloque extendido A de caracteres etíopes añadiendo caracteres adicionales para la escritura etíope.

`IntlChar::BLOCK_CODE_BRAHMI` int

  Bloque de caracteres Brahmi utilizados en la escritura Brahmi antigua de la India.

`IntlChar::BLOCK_CODE_BAMUM_SUPPLEMENT` int

  Bloque de suplementos Bamum añadiendo caracteres adicionales para la escritura Bamum.

`IntlChar::BLOCK_CODE_KANA_SUPPLEMENT` int

  Bloque de suplementos Kana añadiendo caracteres adicionales para la escritura japonesa Kana.

`IntlChar::BLOCK_CODE_PLAYING_CARDS` int

  Bloque de caracteres de cartas de juego utilizados en los símbolos de juegos de cartas.

`IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_PICTOGRAPHS` int

  Bloque de símbolos y pictogramas diversos utilizados en diversos contextos visuales.

`IntlChar::BLOCK_CODE_EMOTICONS` int

  Bloque de emoticones utilizados para representar expresiones faciales y emociones en el texto.

`IntlChar::BLOCK_CODE_TRANSPORT_AND_MAP_SYMBOLS` int

  Bloque de símbolos de transporte y mapas utilizados en las representaciones gráficas de sistemas de transporte y mapas.

`IntlChar::BLOCK_CODE_ALCHEMICAL_SYMBOLS` int

  Bloque de los símbolos alquímicos utilizados en la representación de los conceptos alquímicos históricos.

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_D` int

  Bloque de los ideogramas unificados CJK, extensión D, añadiendo aún más caracteres.

`IntlChar::BLOCK_CODE_ARABIC_EXTENDED_A` int

  Bloque extendido A de caracteres árabes añadiendo caracteres adicionales para la escritura árabe.

`IntlChar::BLOCK_CODE_ARABIC_MATHEMATICAL_ALPHABETIC_SYMBOLS` int

  Bloque de los símbolos alfabéticos matemáticos árabes utilizados en las expresiones matemáticas.

`IntlChar::BLOCK_CODE_CHAKMA` int

  Bloque de los caracteres Chakma utilizados en la escritura Chakma de la India y Bangladesh.

`IntlChar::BLOCK_CODE_MEETEI_MAYEK_EXTENSIONS` int

  Bloque de las extensiones Meetei Mayek añadiendo caracteres adicionales para la escritura Meetei Mayek.

`IntlChar::BLOCK_CODE_MEROITIC_CURSIVE` int

  Bloque de los caracteres cursivos meroíticos utilizados en la escritura meroítica antigua.

`IntlChar::BLOCK_CODE_MEROITIC_HIEROGLYPHS` int

  Bloque de los jeroglíficos meroíticos utilizados en la escritura meroítica antigua.

`IntlChar::BLOCK_CODE_MIAO` int

  Bloque de los caracteres Miao utilizados en la escritura Miao de ciertas regiones de Asia.

`IntlChar::BLOCK_CODE_SHARADA` int

  Bloque de los caracteres Sharada utilizados en la escritura Sharada de la India.

`IntlChar::BLOCK_CODE_SORA_SOMPENG` int

  Bloque de los caracteres Sora Sompeng utilizados en la escritura Sora Sompeng de la India.

`IntlChar::BLOCK_CODE_SUNDANESE_SUPPLEMENT` int

  Bloque de los suplementos Sundaneses añadiendo caracteres adicionales para la escritura sundanesa.

`IntlChar::BLOCK_CODE_TAKRI` int

  Bloque de los caracteres Takri utilizados en la escritura Takri de la India.

`IntlChar::BLOCK_CODE_BASSA_VAH` int

  Bloque de los caracteres Bassa Vah utilizados en la escritura Bassa Vah de Guinea.

`IntlChar::BLOCK_CODE_CAUCASIAN_ALBANIAN` int

  Bloque de los caracteres albaneses caucásicos utilizados en la escritura albana caucásica antigua.

`IntlChar::BLOCK_CODE_COPTIC_EPACT_NUMBERS` int

  Bloque de los números epactales coptos utilizados en el cálculo de los epacts para el calendario copto.

`IntlChar::BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_EXTENDED` int

  Bloque de las marcas diacríticas combinantes extendidas añadiendo caracteres adicionales para modificar los caracteres de base.

`IntlChar::BLOCK_CODE_DUPLOYAN` int

  Bloque de caracteres Duployan utilizados en la escritura fonética de la estenografía Duployan.

`IntlChar::BLOCK_CODE_ELBASAN` int

  Bloque de caracteres Elbasan utilizados en la escritura Elbasan de la antigua Albania.

`IntlChar::BLOCK_CODE_GEOMETRIC_SHAPES_EXTENDED` int

  Bloque extendido de formas geométricas que añade formas adicionales para una variedad de símbolos gráficos.

`IntlChar::BLOCK_CODE_GRANTHA` int

  Bloque de caracteres Grantha utilizados en la escritura Grantha de la India.

`IntlChar::BLOCK_CODE_KHOJKI` int

  Bloque de caracteres Khojki utilizados en la escritura Khojki de la India.

`IntlChar::BLOCK_CODE_KHUDAWADI` int

  Bloque de caracteres Khudawadi utilizados en la escritura Khudawadi de la India.

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_E` int

  Bloque de extensiones Latinas adicionales E que añaden caracteres adicionales para la escritura de lenguas que utilizan el alfabeto latino.

`IntlChar::BLOCK_CODE_LINEAR_A` int

  Bloque de caracteres Linear A utilizados en la escritura Linear A de la antigua Creta.

`IntlChar::BLOCK_CODE_MAHAJANI` int

  Bloque de caracteres Mahajani utilizados en la escritura Mahajani de la India.

`IntlChar::BLOCK_CODE_MANICHAEAN` int

  Bloque de caracteres maniqueos utilizados en la antigua escritura maniquea.

`IntlChar::BLOCK_CODE_MENDE_KIKAKUI` int

  Bloque de caracteres Mende Kikakui utilizados en la escritura Mende Kikakui de Sierra Leona.

`IntlChar::BLOCK_CODE_MODI` int

  Bloque de caracteres Modi utilizados en la escritura Modi de la India.

`IntlChar::BLOCK_CODE_MRO` int

  Bloque de caracteres Mro utilizados en la escritura Mro de ciertos pueblos del Sudeste Asiático.

`IntlChar::BLOCK_CODE_MYANMAR_EXTENDED_B` int

  Bloque extendido B de caracteres Myanmar que añade caracteres adicionales para la escritura Myanmar.

`IntlChar::BLOCK_CODE_NABATAEAN` int

  Bloque de caracteres Nabateos utilizados en la antigua escritura Nabatea.

`IntlChar::BLOCK_CODE_OLD_NORTH_ARABIAN` int

  Bloque de caracteres árabes del Norte antiguos utilizados en la antigua escritura norteárabe.

`IntlChar::BLOCK_CODE_OLD_PERMIC` int

  Bloque de caracteres permic antiguos utilizados en la escritura permic de la antigua Persia.

`IntlChar::BLOCK_CODE_ORNAMENTAL_DINGBATS` int

  Bloque de dingbats ornamentales utilizados para añadir elementos decorativos en el texto.

`IntlChar::BLOCK_CODE_PAHAWH_HMONG` int

  Bloque de caracteres Pahawh Hmong utilizados en la escritura Pahawh Hmong para el idioma Hmong.

`IntlChar::BLOCK_CODE_PALMYRENE` int

  Bloque de caracteres palmirenos utilizados en la escritura palmirena de la antigüedad.

`IntlChar::BLOCK_CODE_PAU_CIN_HAU` int

  Bloque de caracteres Pau Cin Hau utilizados en la escritura Pau Cin Hau de ciertas comunidades en Asia.

`IntlChar::BLOCK_CODE_PSALTER_PAHLAVI` int

  Bloque de caracteres pahlavi de los salmos utilizados en la escritura pahlavi para textos religiosos.

`IntlChar::BLOCK_CODE_SHORTHAND_FORMAT_CONTROLS` int

  Bloque de controles de formato taquigráfico utilizados para la taquigrafía y la transcripción rápida.

`IntlChar::BLOCK_CODE_SIDDHAM` int

  Bloque de caracteres Siddham utilizados en la escritura Siddham de la antigua India.

`IntlChar::BLOCK_CODE_SINHALA_ARCHAIC_NUMBERS` int

  Bloque de números arcaicos Sinhala utilizados en la escritura Sinhala antigua.

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_ARROWS_C` int

  Bloque de flechas suplementarias C que añaden aún más variantes de flechas para diversas representaciones gráficas.

`IntlChar::BLOCK_CODE_TIRHUTA` int

  Bloque de caracteres Tirhuta utilizados en la escritura Tirhuta del noreste de la India.

`IntlChar::BLOCK_CODE_WARANG_CITI` int

  Bloque de caracteres Warang Citi utilizados en la escritura Warang Citi para el idioma Ho.

`IntlChar::BLOCK_CODE_COUNT` int

  Bloque code-count que define el número total de bloques disponibles.

`IntlChar::BLOCK_CODE_INVALID_CODE` int

  Bloque code-invalid-code que representa un código de bloque inválido o no definido.

`IntlChar::BPT_NONE` int

  Tipo de puntuación bidireccional: Ninguno.

`IntlChar::BPT_OPEN` int

  Tipo de puntuación bidireccional: Apertura.

`IntlChar::BPT_CLOSE` int

  Tipo de puntuación bidireccional: Cierre.

`IntlChar::BPT_COUNT` int

  Número total de tipos de puntuaciones bidireccionales.

`IntlChar::EA_NEUTRAL` int

  Ancho este-asiático: Neutro.

`IntlChar::EA_AMBIGUOUS` int

  Ancho este-asiático: Ambiguo.

`IntlChar::EA_HALFWIDTH` int

  Ancho este-asiático: Semi-ancho.

`IntlChar::EA_FULLWIDTH` int

  Ancho este-asiático: Ancho completo.

`IntlChar::EA_NARROW` int

  Ancho este-asiático: Estrecho.

`IntlChar::EA_WIDE` int

  Ancho este-asiático: Ancho.

`IntlChar::EA_COUNT` int

  Número total de categorías de ancho este-asiático.

`IntlChar::UNICODE_CHAR_NAME` int

  Nombre de carácter Unicode estándar.

`IntlChar::UNICODE_10_CHAR_NAME` int

  Nombre de carácter Unicode versión 10.

`IntlChar::EXTENDED_CHAR_NAME` int

  Nombre de carácter extendido Unicode.

`IntlChar::CHAR_NAME_ALIAS` int

  Alias de nombre de carácter Unicode.

`IntlChar::CHAR_NAME_CHOICE_COUNT` int

  Número de opciones para los alias de nombres de caracteres Unicode.

`IntlChar::SHORT_PROPERTY_NAME` int

  Nombre de propiedad corto.

`IntlChar::LONG_PROPERTY_NAME` int

  Nombre de propiedad largo.

`IntlChar::PROPERTY_NAME_CHOICE_COUNT` int

  Número de opciones para los nombres de propiedades.

`IntlChar::DT_NONE` int

  Tipo de descomposición: Ninguno.

`IntlChar::DT_CANONICAL` int

  Tipo de descomposición: Canónico.

`IntlChar::DT_COMPAT` int

  Tipo de descomposición: Compatibilidad.

`IntlChar::DT_CIRCLE` int

  Tipo de descomposición: Círculo.

`IntlChar::DT_FINAL` int

  Tipo de descomposición: Final.

`IntlChar::DT_FONT` int

  Tipo de descomposición: Fuente.

`IntlChar::DT_FRACTION` int

  Tipo de descomposición: Fracción.

`IntlChar::DT_INITIAL` int

  Tipo de descomposición: Inicial.

`IntlChar::DT_ISOLATED` int

  Tipo de descomposición: Aislado.

`IntlChar::DT_MEDIAL` int

  Tipo de descomposición: Medial.

`IntlChar::DT_NARROW` int

  Tipo de descomposición: Estrecho.

`IntlChar::DT_NOBREAK` int

  Tipo de descomposición: Sin ruptura.

`IntlChar::DT_SMALL` int

  Tipo de descomposición: Pequeño.

`IntlChar::DT_SQUARE` int

  Tipo de descomposición: Cuadrado.

`IntlChar::DT_SUB` int

  Tipo de descomposición: Sustitutivo.

`IntlChar::DT_SUPER` int

  Tipo de descomposición: Superíndice.

`IntlChar::DT_VERTICAL` int

  Tipo de descomposición: Vertical.

`IntlChar::DT_WIDE` int

  Tipo de descomposición: Ancho.

`IntlChar::DT_COUNT` int

  Número total de tipos de descomposición.

`IntlChar::JT_NON_JOINING` int

  Tipo de unión: No unido.

`IntlChar::JT_JOIN_CAUSING` int

  Tipo de unión: Causante de unión.

`IntlChar::JT_DUAL_JOINING` int

  Tipo de unión: Unión doble.

`IntlChar::JT_LEFT_JOINING` int

  Tipo de unión: Unión izquierda.

`IntlChar::JT_RIGHT_JOINING` int

  Tipo de unión: Unión derecha.

`IntlChar::JT_TRANSPARENT` int

  Tipo de unión: Transparente.

`IntlChar::JT_COUNT` int

  Número total de tipos de unión.

`IntlChar::JG_NO_JOINING_GROUP` int

  Grupo de unión: Sin grupo de unión.

`IntlChar::JG_AIN` int

  Grupo de unión: Ain.

`IntlChar::JG_ALAPH` int

  Grupo de unión: Alaph.

`IntlChar::JG_ALEF` int

  Grupo de unión: Alef.

`IntlChar::JG_BEH` int

  Grupo de unión: Beh.

`IntlChar::JG_BETH` int

  Grupo de unión: Beth.

`IntlChar::JG_DAL` int

  Grupo de unión: Dal.

`IntlChar::JG_DALATH_RISH` int

  Grupo de unión: Dalath Rish.

`IntlChar::JG_E` int

  Grupo de unión: E.

`IntlChar::JG_FEH` int

  Grupo de unión: Feh.

`IntlChar::JG_FINAL_SEMKATH` int

  Grupo de unión: Final Semkath.

`IntlChar::JG_GAF` int

  Grupo de unión: Gaf.

`IntlChar::JG_GAMAL` int

  Grupo de unión: Gamal.

`IntlChar::JG_HAH` int

  Grupo de unión: Hah.

`IntlChar::JG_TEH_MARBUTA_GOAL` int

  Grupo de unión: Teh Marbuta Goal.

`IntlChar::JG_HAMZA_ON_HEH_GOAL` int

  Grupo de unión: Hamza sobre Heh Goal.

`IntlChar::JG_HE` int

  Grupo de unión: He.

`IntlChar::JG_HEH` int

  Grupo de unión: Heh.

`IntlChar::JG_HEH_GOAL` int

  Grupo de unión: Heh Goal.

`IntlChar::JG_HETH` int

  Grupo de unión: Heth.

`IntlChar::JG_KAF` int

  Grupo de unión: Kaf.

`IntlChar::JG_KAPH` int

  Grupo de unión: Kaph.

`IntlChar::JG_KNOTTED_HEH` int

  Grupo de unión: Heh anudado.

`IntlChar::JG_LAM` int

  Grupo de unión: Lam.

`IntlChar::JG_LAMADH` int

  Grupo de unión: Lamadh.

`IntlChar::JG_MEEM` int

  Grupo de unión: Meem.

`IntlChar::JG_MIM` int

  Grupo de unión: Mim.

`IntlChar::JG_NOON` int

  Grupo de unión: Noon.

`IntlChar::JG_NUN` int

  Grupo de unión: Nun.

`IntlChar::JG_PE` int

  Grupo de unión: Pe.

`IntlChar::JG_QAF` int

  Grupo de unión: Qaf.

`IntlChar::JG_QAPH` int

  Grupo de unión: Qaph.

`IntlChar::JG_REH` int

  Grupo de unión: Reh.

`IntlChar::JG_REVERSED_PE` int

  Grupo de unión: Pe invertido.

`IntlChar::JG_SAD` int

  Grupo de unión: Sad.

`IntlChar::JG_SADHE` int

  Grupo de unión: Sadhe.

`IntlChar::JG_SEEN` int

  Grupo de unión: Seen.

`IntlChar::JG_SEMKATH` int

  Grupo de unión: Semkath.

`IntlChar::JG_SHIN` int

  Grupo de unión: Shin.

`IntlChar::JG_SWASH_KAF` int

  Grupo de unión: Swash Kaf.

`IntlChar::JG_SYRIAC_WAW` int

  Grupo de unión: Waw Syriac.

`IntlChar::JG_TAH` int

  Grupo de unión: Tah.

`IntlChar::JG_TAW` int

  Grupo de unión: Taw.

`IntlChar::JG_TEH_MARBUTA` int

  Grupo de unión: Teh Marbuta.

`IntlChar::JG_TETH` int

  Grupo de unión: Teth.

`IntlChar::JG_WAW` int

  Grupo de unión: Waw.

`IntlChar::JG_YEH` int

  Grupo de unión: Yeh.

`IntlChar::JG_YEH_BARREE` int

  Grupo de unión: Yeh Barree.

`IntlChar::JG_YEH_WITH_TAIL` int

  Grupo de unión: Yeh con cola.

`IntlChar::JG_YUDH` int

  Grupo de unión: Yudh.

`IntlChar::JG_YUDH_HE` int

  Grupo de unión: Yudh-He.

`IntlChar::JG_ZAIN` int

  Grupo de unión: Zain.

`IntlChar::JG_FE` int

  Grupo de unión: Fe.

`IntlChar::JG_KHAPH` int

  Grupo de unión: Khaph.

`IntlChar::JG_ZHAIN` int

  Grupo de unión: Zhain.

`IntlChar::JG_BURUSHASKI_YEH_BARREE` int

  Grupo de unión: Yeh Barree Burushaski.

`IntlChar::JG_FARSI_YEH` int

  Grupo de unión: Yeh Farsi.

`IntlChar::JG_NYA` int

  Grupo de unión: Nya.

`IntlChar::JG_ROHINGYA_YEH` int

  Grupo de unión: Yeh Rohingya.

`IntlChar::JG_MANICHAEAN_ALEPH` int

  Grupo de unión: Aleph Maniqueo.

`IntlChar::JG_MANICHAEAN_AYIN` int

  Grupo de unión: Ayin Maniqueo.

`IntlChar::JG_MANICHAEAN_BETH` int

  Grupo de unión: Beth Maniqueo.

`IntlChar::JG_MANICHAEAN_DALETH` int

  Grupo de unión: Daleth Maniqueo.

`IntlChar::JG_MANICHAEAN_DHAMEDH` int

  Grupo de unión: Dhamedh Maniqueo.

`IntlChar::JG_MANICHAEAN_FIVE` int

  Grupo de unión: Cinco Maniqueo.

`IntlChar::JG_MANICHAEAN_GIMEL` int

  Grupo de unión: Gimel Maniqueo.

`IntlChar::JG_MANICHAEAN_HETH` int

  Grupo de unión: Heth Maniqueo.

`IntlChar::JG_MANICHAEAN_HUNDRED` int

  Grupo de unión: Cien Maniqueo.

`IntlChar::JG_MANICHAEAN_KAPH` int

  Grupo de unión: Kaph Maniqueo.

`IntlChar::JG_MANICHAEAN_LAMEDH` int

  Grupo de unión: Lamedh Maniqueo.

`IntlChar::JG_MANICHAEAN_MEM` int

  Grupo de unión: Mem Maniqueo.

`IntlChar::JG_MANICHAEAN_NUN` int

  Grupo de unión: Nun Maniqueo.

`IntlChar::JG_MANICHAEAN_ONE` int

  Grupo de unión: Uno Maniqueo.

`IntlChar::JG_MANICHAEAN_PE` int

  Grupo de unión: Pe Maniqueo.

`IntlChar::JG_MANICHAEAN_QOPH` int

  Grupo de unión: Qoph Maniqueo.

`IntlChar::JG_MANICHAEAN_RESH` int

  Grupo de unión: Resh Maniqueo.

`IntlChar::JG_MANICHAEAN_SADHE` int

  Grupo de unión: Sadhe Maniqueo.

`IntlChar::JG_MANICHAEAN_SAMEKH` int

  Grupo de unión: Samekh Maniqueo.

`IntlChar::JG_MANICHAEAN_TAW` int

  Grupo de unión: Taw Maniqueo.

`IntlChar::JG_MANICHAEAN_TEN` int

  Grupo de unión: Diez Maniqueo.

`IntlChar::JG_MANICHAEAN_TETH` int

  Grupo de unión: Teth Maniqueo.

`IntlChar::JG_MANICHAEAN_THAMEDH` int

  Grupo de unión: Thamedh Maniqueo.

`IntlChar::JG_MANICHAEAN_TWENTY` int

  Grupo de unión: Veinte Maniqueo.

`IntlChar::JG_MANICHAEAN_WAW` int

  Grupo de unión: Waw Maniqueo.

`IntlChar::JG_MANICHAEAN_YODH` int

  Grupo de unión: Yodh Maniqueo.

`IntlChar::JG_MANICHAEAN_ZAYIN` int

  Grupo de unión: Zayin Maniqueo.

`IntlChar::JG_STRAIGHT_WAW` int

  Grupo de unión: Waw recto.

`IntlChar::JG_COUNT` int

  Número total de grupos de unión.

`IntlChar::GCB_OTHER` int

  Categoría de cluster de grafemas: Otro.

`IntlChar::GCB_CONTROL` int

  Categoría de cluster de grafemas: Control.

`IntlChar::GCB_CR` int

  Categoría de cluster de grafemas: Retorno de carro.

`IntlChar::GCB_EXTEND` int

  Categoría de cluster de grafemas: Extensión.

`IntlChar::GCB_L` int

  Categoría de cluster de grafemas: Letra L.

`IntlChar::GCB_LF` int

  Categoría de cluster de grafemas: Salto de línea.

`IntlChar::GCB_LV` int

  Categoría de cluster de grafemas: LV.

`IntlChar::GCB_LVT` int

  Categoría de cluster de grafemas: LVT.

`IntlChar::GCB_T` int

  Categoría de cluster de grafemas: T.

`IntlChar::GCB_V` int

  Categoría de cluster de grafemas: V.

`IntlChar::GCB_SPACING_MARK` int

  Categoría de cluster de graphemes: Marca de espaciado.

`IntlChar::GCB_PREPEND` int

  Categoría de cluster de graphemes: Prefijo.

`IntlChar::GCB_REGIONAL_INDICATOR` int

  Categoría de cluster de graphemes: Indicador regional.

`IntlChar::GCB_COUNT` int

  Número total de categorías de cluster de graphemes.

`IntlChar::WB_OTHER` int

  Categoría de separación de palabras: Otro.

`IntlChar::WB_ALETTER` int

  Categoría de separación de palabras: Letra A.

`IntlChar::WB_FORMAT` int

  Categoría de separación de palabras: Formato.

`IntlChar::WB_KATAKANA` int

  Categoría de separación de palabras: Katakana.

`IntlChar::WB_MIDLETTER` int

  Categoría de separación de palabras: Letra media.

`IntlChar::WB_MIDNUM` int

  Categoría de separación de palabras: Número medio.

`IntlChar::WB_NUMERIC` int

  Categoría de separación de palabras: Numérico.

`IntlChar::WB_EXTENDNUMLET` int

  Categoría de separación de palabras: Extensión numérica y letra.

`IntlChar::WB_CR` int

  Categoría de separación de palabras: Retorno de carro.

`IntlChar::WB_EXTEND` int

  Categoría de separación de palabras: Extensión.

`IntlChar::WB_LF` int

  Categoría de separación de palabras: Salto de línea.

`IntlChar::WB_MIDNUMLET` int

  Categoría de separación de palabras: Número y letra media.

`IntlChar::WB_NEWLINE` int

  Categoría de separación de palabras: Nueva línea.

`IntlChar::WB_REGIONAL_INDICATOR` int

  Categoría de separación de palabras: Indicador regional.

`IntlChar::WB_HEBREW_LETTER` int

  Categoría de separación de palabras: Letra hebrea.

`IntlChar::WB_SINGLE_QUOTE` int

  Categoría de separación de palabras: Comillas simples.

`IntlChar::WB_DOUBLE_QUOTE` int

  Categoría de separación de palabras: Comillas dobles.

`IntlChar::WB_COUNT` int

  Número total de categorías de separación de palabras.

`IntlChar::SB_OTHER` int

  Categoría de separación de frases: Otro.

`IntlChar::SB_ATERM` int

  Categoría de separación de frases: Aterm.

`IntlChar::SB_CLOSE` int

  Categoría de separación de frases: Cierre.

`IntlChar::SB_FORMAT` int

  Categoría de separación de frases: Formato.

`IntlChar::SB_LOWER` int

  Categoría de separación de frases: Minúsculas.

`IntlChar::SB_NUMERIC` int

  Categoría de separación de frases: Numérico.

`IntlChar::SB_OLETTER` int

  Categoría de separación de frases: Letra O.

`IntlChar::SB_SEP` int

  Categoría de separación de frases: Separador.

`IntlChar::SB_SP` int

  Categoría de separación de frases: Espaciado.

`IntlChar::SB_STERM` int

  Categoría de separación de frases: Sterm.

`IntlChar::SB_UPPER` int

  Categoría de separación de frases: Mayúsculas.

`IntlChar::SB_CR` int

  Categoría de separación de frases: Retorno de carro.

`IntlChar::SB_EXTEND` int

  Categoría de separación de frases: Extensión.

`IntlChar::SB_LF` int

  Categoría de separación de frases: Salto de línea.

`IntlChar::SB_SCONTINUE` int

  Categoría de separación de frases: Continuación.

`IntlChar::SB_COUNT` int

  Número total de categorías de separación de frases.

`IntlChar::LB_UNKNOWN` int

  Categoría de separación de líneas: Desconocida.

`IntlChar::LB_AMBIGUOUS` int

  Categoría de separación de líneas: Ambigua.

`IntlChar::LB_ALPHABETIC` int

  Categoría de separación de líneas: Alfabética.

`IntlChar::LB_BREAK_BOTH` int

  Categoría de separación de líneas: Separación en ambos lados.

`IntlChar::LB_BREAK_AFTER` int

  Categoría de separación de líneas: Separación después.

`IntlChar::LB_BREAK_BEFORE` int

  Categoría de separación de líneas: Separación antes.

`IntlChar::LB_MANDATORY_BREAK` int

  Categoría de separación de líneas: Separación obligatoria.

`IntlChar::LB_CONTINGENT_BREAK` int

  Categoría de separación de líneas: Separación contingente.

`IntlChar::LB_CLOSE_PUNCTUATION` int

  Categoría de separación de líneas: Puntuación cerrada.

`IntlChar::LB_COMBINING_MARK` int

  Categoría de separación de líneas: Marca combinante.

`IntlChar::LB_CARRIAGE_RETURN` int

  Categoría de separación de líneas: Retorno de carro.

`IntlChar::LB_EXCLAMATION` int

  Categoría de separación de líneas: Signo de exclamación.

`IntlChar::LB_GLUE` int

  Categoría de separación de líneas: Pegamento.

`IntlChar::LB_HYPHEN` int

  Categoría de separación de líneas: Guión.

`IntlChar::LB_IDEOGRAPHIC` int

  Categoría de separación de líneas: Ideográfico.

`IntlChar::LB_INSEPARABLE` int

  Categoría de separación de líneas: Inseparable.

`IntlChar::LB_INSEPERABLE` int

  Categoría de separación de líneas: Inseparable.

`IntlChar::LB_INFIX_NUMERIC` int

  Categoría de separación de líneas: Numérico intermedio.

`IntlChar::LB_LINE_FEED` int

  Categoría de separación de líneas: Salto de línea.

`IntlChar::LB_NONSTARTER` int

  Categoría de separación de líneas: No iniciador.

`IntlChar::LB_NUMERIC` int

  Categoría de separación de líneas: Numérico.

`IntlChar::LB_OPEN_PUNCTUATION` int

  Categoría de separación de líneas: Puntuación abierta.

`IntlChar::LB_POSTFIX_NUMERIC` int

  Categoría de separación de líneas: Numérico postfijo.

`IntlChar::LB_PREFIX_NUMERIC` int

  Categoría de separación de líneas: Numérico prefijo.

`IntlChar::LB_QUOTATION` int

  Categoría de separación de líneas: Cita.

`IntlChar::LB_COMPLEX_CONTEXT` int

  Categoría de separación de líneas: Contexto complejo.

`IntlChar::LB_SURROGATE` int

  Categoría de separación de líneas: Surrogate.

`IntlChar::LB_SPACE` int

  Categoría de separación de líneas: Espacio.

`IntlChar::LB_BREAK_SYMBOLS` int

  Categoría de separación de líneas: Símbolos de ruptura.

`IntlChar::LB_ZWSPACE` int

  Categoría de separación de líneas: Espacio cero ancho.

`IntlChar::LB_NEXT_LINE` int

  Categoría de separación de líneas: Línea siguiente.

`IntlChar::LB_WORD_JOINER` int

  Categoría de separación de líneas: Unificador de palabras.

`IntlChar::LB_H2` int

  Categoría de separación de líneas: H2.

`IntlChar::LB_H3` int

  Categoría de separación de líneas: H3.

`IntlChar::LB_JL` int

  Categoría de separación de líneas: JL.

`IntlChar::LB_JT` int

  Categoría de separación de líneas: JT.

`IntlChar::LB_JV` int

  Categoría de separación de líneas: JV.

`IntlChar::LB_CLOSE_PARENTHESIS` int

  Categoría de separación de líneas: Paréntesis cerrado.

`IntlChar::LB_CONDITIONAL_JAPANESE_STARTER` int

  Categoría de separación de líneas: Inicio condicional japonés.

`IntlChar::LB_HEBREW_LETTER` int

  Categoría de separación de líneas: Letra hebrea.

`IntlChar::LB_REGIONAL_INDICATOR` int

  Categoría de separación de líneas: Indicador regional.

`IntlChar::LB_COUNT` int

  Número total de categorías de separación de líneas.

`IntlChar::NT_NONE` int

  Tipo de número: Ninguno.

`IntlChar::NT_DECIMAL` int

  Tipo de número: Decimal.

`IntlChar::NT_DIGIT` int

  Tipo de número: Dígito.

`IntlChar::NT_NUMERIC` int

  Tipo de número: Numérico.

`IntlChar::NT_COUNT` int

  Número total de tipos de números.

`IntlChar::HST_NOT_APPLICABLE` int

  Tipo de sílaba Hangul: No aplicable.

`IntlChar::HST_LEADING_JAMO` int

  Tipo de sílaba Hangul: Jamo inicial.

`IntlChar::HST_VOWEL_JAMO` int

  Tipo de sílaba Hangul: Jamo vocal.

`IntlChar::HST_TRAILING_JAMO` int

  Tipo de sílaba Hangul: Jamo final.

`IntlChar::HST_LV_SYLLABLE` int

  Tipo de sílaba Hangul: Sílabas LV.

`IntlChar::HST_LVT_SYLLABLE` int

  Tipo de sílaba Hangul: Sílabas LVT.

`IntlChar::HST_COUNT` int

  Número total de tipos de sílabas Hangul.

`IntlChar::FOLD_CASE_DEFAULT` int

  Opción de plegado de mayúsculas: Por defecto.

`IntlChar::FOLD_CASE_EXCLUDE_SPECIAL_I` int

  Opción de plegado de mayúsculas: Excluir la I especial.

## Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Se añadieron `IntlChar::PROPERTY_IDS_UNARY_OPERATOR`, `IntlChar::PROPERTY_ID_COMPAT_MATH_START`, `IntlChar::PROPERTY_ID_COMPAT_MATH_CONTINUE`.
8.4.0 | Las constantes de clase ahora están tipadas.
7.0.6 | La constante `IntlChar::NO_NUMERIC_VALUE` ha sido añadida.

# IntlChar::charAge

(PHP 7, PHP 8)

IntlChar::charAge — Devuelve la "edad" del punto de código

### Descripción

public static function IntlChar::charAge(int|string `$codepoint`): ?array

Devuelve la "edad" del punto de código.

La "edad" es la versión Unicode cuando el punto de código fue designado por primera vez (como un no-carácter o para uso privado) o asignado a un carácter. Esto puede ser útil para evitar emitir puntos de código a procesos de recepción que no aceptan caracteres más recientes.

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

La versión Unicode, en forma de un array. Por ejemplo, la versión 1.3.31.2 sería representada por `[1, 3, 31, 2]`. Devuelve `null` en caso de fallo.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::charage("\u{2603}"));
    var_dump(IntlChar::charage("\u{1F576}"));
    ?>

El ejemplo anterior mostrará:

    array(4) {
      [0]=>
      int(1)
      [1]=>
      int(1)
      [2]=>
      int(0)
      [3]=>
      int(0)
    }
    array(4) {
      [0]=>
      int(7)
      [1]=>
      int(0)
      [2]=>
      int(0)
      [3]=>
      int(0)
    }

### Ver también

- IntlChar::getUnicodeVersion() - Devuelve la versión Unicode
- IntlChar::getIntPropertyMinValue() - Devuelve el valor mínimo para una propiedad Unicode
- IntlChar::getIntPropertyValue() - Devuelve el valor de una propiedad Unicode para un punto de código

# IntlChar::charDigitValue

(PHP 7, PHP 8)

IntlChar::charDigitValue — Devuelve el valor decimal del dígito decimal

### Descripción

public static function IntlChar::charDigitValue(int|string `$codepoint`): ?int

Devuelve el valor decimal del carácter dígito decimal.

Tales caracteres tienen la categoría general "Nd" (dígitos decimales) y un Numeric_Type de Decimal.

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

El valor decimal del carácter dígito decimal, o `-1` si no es un carácter decimal. Devuelve `null` en caso de fallo.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::charDigitValue("1"));
    var_dump(IntlChar::charDigitValue("\u{0662}"));
    var_dump(IntlChar::charDigitValue("\u{0E53}"));
    ?>

El ejemplo anterior mostrará:

    int(1)
    int(2)
    int(3)

### Ver también

- IntlChar::getNumericValue() - Devuelve el valor numérico de un punto de código Unicode

# IntlChar::charDirection

(PHP 7, PHP 8)

IntlChar::charDirection — Devuelve el valor de la categoría bidireccional para un punto de código

### Descripción

public static function IntlChar::charDirection(int|string `$codepoint`): ?int

Devuelve el valor de la categoría bidireccional para un punto de código, que se utiliza en el » algoritmo bidireccional Unicode (UAX #9).

> Nota:

> Algunos puntos de código no asignados tienen valores bidireccionales de R o AL ya que se encuentran en bloques reservados para scripts de derecha a izquierda.

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

El valor de la categoría bidireccional; una de las constantes siguientes:

- `IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT`
- `IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER`
- `IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR`
- `IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_TERMINATOR`
- `IntlChar::CHAR_DIRECTION_ARABIC_NUMBER`
- `IntlChar::CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR`
- `IntlChar::CHAR_DIRECTION_BLOCK_SEPARATOR`
- `IntlChar::CHAR_DIRECTION_SEGMENT_SEPARATOR`
- `IntlChar::CHAR_DIRECTION_WHITE_SPACE_NEUTRAL`
- `IntlChar::CHAR_DIRECTION_OTHER_NEUTRAL`
- `IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_EMBEDDING`
- `IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_OVERRIDE`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ARABIC`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_EMBEDDING`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_OVERRIDE`
- `IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_FORMAT`
- `IntlChar::CHAR_DIRECTION_DIR_NON_SPACING_MARK`
- `IntlChar::CHAR_DIRECTION_BOUNDARY_NEUTRAL`
- `IntlChar::CHAR_DIRECTION_FIRST_STRONG_ISOLATE`
- `IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_ISOLATE`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ISOLATE`
- `IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_ISOLATE`
- `IntlChar::CHAR_DIRECTION_CHAR_DIRECTION_COUNT`

Devuelve `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::charDirection("A") === IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT);
    var_dump(IntlChar::charDirection("\u{05E9}") === IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT);
    var_dump(IntlChar::charDirection("+") === IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR);
    var_dump(IntlChar::charDirection(".") === IntlChar::CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR);
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(true)
    bool(true)
    bool(true)

# IntlChar::charFromName

(PHP 7, PHP 8)

IntlChar::charFromName — Encuentra un carácter Unicode por su nombre y devuelve su valor de punto de código

### Descripción

public static function IntlChar::charFromName(string `$name`, int `$type` = `IntlChar::UNICODE_CHAR_NAME`): ?int

Encuentra un carácter Unicode por su nombre y devuelve su valor de punto de código.

El nombre es comparado exactamente y completamente. Si el nombre no corresponde a un punto de código, `null` es devuelto.

Un nombre Unicode 1.0 es encontrado únicamente si difiere del nombre moderno. Los nombres Unicode están todos en mayúsculas. Los nombres extendidos están en minúsculas seguidos de un número hexadecimal en mayúsculas, y entre chevrons.

### Parámetros

`name`

  El nombre completo del carácter Unicode.

`type`

  Qué nombres utilizar para la búsqueda. Puede ser una de las constantes siguientes:

  - `IntlChar::UNICODE_CHAR_NAME` (por omisión)
  - `IntlChar::UNICODE_10_CHAR_NAME`
  - `IntlChar::EXTENDED_CHAR_NAME`
  - `IntlChar::CHAR_NAME_ALIAS`
  - `IntlChar::CHAR_NAME_CHOICE_COUNT`

### Valores devueltos

El valor Unicode del punto de código con el nombre dado (como int), o `null` si no existe tal punto de código.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::charFromName("LATIN CAPITAL LETTER A"));
    var_dump(IntlChar::charFromName("SNOWMAN"));
    var_dump(IntlChar::charFromName("RECYCLING SYMBOL FOR TYPE-1 PLASTICS"));
    var_dump(IntlChar::charFromName("A RANDOM STRING WHICH DOESN'T CORRESPOND TO ANY UNICODE CHARACTER"));
    ?>

El ejemplo anterior mostrará:

    int(65)
    int(9731)
    int(9843)
    NULL

### Ver también

- IntlChar::charName() - Devuelve el nombre de un carácter Unicode
- IntlChar::enumCharNames() - Enumera todos los caracteres Unicode asignados en un rango

# IntlChar::charMirror

(PHP 7, PHP 8)

IntlChar::charMirror — Devuelve el carácter "imagen-espejo" para un punto de código

### Descripción

public static function IntlChar::charMirror(int|string `$codepoint`): int|string|null

Vincula el carácter especificado a un carácter "imagen-espejo".

Para los caracteres con la propiedad Bidi_Mirrored, las implementaciones a veces necesitan una correspondencia "pobre" hacia otro punto de código Unicode (code point) de tal manera que el glifo por defecto pueda servir como glifo espejo del glifo por defecto del carácter especificado. Esto es útil para la conversión de texto hacia y desde páginas de códigos con un orden visual, y para los displays sin capacidades de selección de glifo.

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve otro punto de código Unicode que puede servir como sustituto imagen-espejo, o `codepoint` mismo si no hay correspondencia o si `codepoint` no tiene la propiedad Bidi_Mirrored.

El tipo de retorno es int a menos que el punto de código haya sido pasado como un string UTF-8, en cuyo caso se devuelve un string. Devuelve `null` en caso de fallo.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::charMirror("A"));
    var_dump(IntlChar::charMirror("<"));
    var_dump(IntlChar::charMirror("("));
    ?>

El ejemplo anterior mostrará:

    string(1) "A"
    string(1) ">"
    string(2) ")"

### Ver también

- IntlChar::isMirrored() - Verifica si un punto de código tiene la propiedad Bidi_Mirrored
- `IntlChar::PROPERTY_BIDI_MIRRORED`

# IntlChar::charName

(PHP 7, PHP 8)

IntlChar::charName — Devuelve el nombre de un carácter Unicode

### Descripción

public static function IntlChar::charName(int|string `$codepoint`, int `$type` = `IntlChar::UNICODE_CHAR_NAME`): ?string

Devuelve el nombre de un carácter Unicode.

Según el `type`, el nombre del carácter es el nombre "moderno" o el nombre que fue definido en la versión Unicode 1.0. El nombre contiene solo caracteres "invariantes" como A-Z, 0-9, espacio y '-'. Los nombres Unicode 1.0 solo se recuperan si son diferentes de los nombres modernos y si ICU contiene los datos para ellos.

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)
`type`

  Qué nombres utilizar para la búsqueda. Puede ser una de las constantes siguientes:

  - `IntlChar::UNICODE_CHAR_NAME` (por omisión)
  - `IntlChar::UNICODE_10_CHAR_NAME`
  - `IntlChar::EXTENDED_CHAR_NAME`
  - `IntlChar::CHAR_NAME_ALIAS`
  - `IntlChar::CHAR_NAME_CHOICE_COUNT`

### Valores devueltos

El valor correspondiente, o una cadena vacía si no hay nombre para ese carácter, o `null` si no hay punto de código.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::charName("."));
    var_dump(IntlChar::charName(".", IntlChar::UNICODE_CHAR_NAME));
    var_dump(IntlChar::charName("\u{2603}"));
    var_dump(IntlChar::charName("\u{0000}"));
    ?>

El ejemplo anterior mostrará:

    string(9) "FULL STOP"
    string(9) "FULL STOP"
    string(7) "SNOWMAN"
    string(0) ""

### Ver también

- IntlChar::charFromName() - Encuentra un carácter Unicode por su nombre y devuelve su valor de punto de código
- IntlChar::enumCharNames() - Enumera todos los caracteres Unicode asignados en un rango

# IntlChar::charType

(PHP 7, PHP 8)

IntlChar::charType — Devuelve el valor de la categoría general para un punto de código

### Descripción

public static function IntlChar::charType(int|string `$codepoint`): ?int

Devuelve la categoría general para el punto de código.

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve la categoría general, que puede ser una de las constantes siguientes:

- `IntlChar::CHAR_CATEGORY_UNASSIGNED`
- `IntlChar::CHAR_CATEGORY_GENERAL_OTHER_TYPES`
- `IntlChar::CHAR_CATEGORY_UPPERCASE_LETTER`
- `IntlChar::CHAR_CATEGORY_LOWERCASE_LETTER`
- `IntlChar::CHAR_CATEGORY_TITLECASE_LETTER`
- `IntlChar::CHAR_CATEGORY_MODIFIER_LETTER`
- `IntlChar::CHAR_CATEGORY_OTHER_LETTER`
- `IntlChar::CHAR_CATEGORY_NON_SPACING_MARK`
- `IntlChar::CHAR_CATEGORY_ENCLOSING_MARK`
- `IntlChar::CHAR_CATEGORY_COMBINING_SPACING_MARK`
- `IntlChar::CHAR_CATEGORY_DECIMAL_DIGIT_NUMBER`
- `IntlChar::CHAR_CATEGORY_LETTER_NUMBER`
- `IntlChar::CHAR_CATEGORY_OTHER_NUMBER`
- `IntlChar::CHAR_CATEGORY_SPACE_SEPARATOR`
- `IntlChar::CHAR_CATEGORY_LINE_SEPARATOR`
- `IntlChar::CHAR_CATEGORY_PARAGRAPH_SEPARATOR`
- `IntlChar::CHAR_CATEGORY_CONTROL_CHAR`
- `IntlChar::CHAR_CATEGORY_FORMAT_CHAR`
- `IntlChar::CHAR_CATEGORY_PRIVATE_USE_CHAR`
- `IntlChar::CHAR_CATEGORY_SURROGATE`
- `IntlChar::CHAR_CATEGORY_DASH_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_START_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_END_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_CONNECTOR_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_OTHER_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_MATH_SYMBOL`
- `IntlChar::CHAR_CATEGORY_CURRENCY_SYMBOL`
- `IntlChar::CHAR_CATEGORY_MODIFIER_SYMBOL`
- `IntlChar::CHAR_CATEGORY_OTHER_SYMBOL`
- `IntlChar::CHAR_CATEGORY_INITIAL_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_FINAL_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_CHAR_CATEGORY_COUNT`

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::charType("A") === IntlChar::CHAR_CATEGORY_UPPERCASE_LETTER);
    var_dump(IntlChar::charType(".") === IntlChar::CHAR_CATEGORY_OTHER_PUNCTUATION);
    var_dump(IntlChar::charType("\t") === IntlChar::CHAR_CATEGORY_CONTROL_CHAR);
    var_dump(IntlChar::charType("\u{2603}") === IntlChar::CHAR_CATEGORY_OTHER_SYMBOL);
    var_dump(IntlChar::charType("multiple chars") === null);
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(true)
    bool(true)
    bool(true)
    bool(true)

# IntlChar::chr

(PHP 7, PHP 8)

IntlChar::chr — Devuelve el carácter Unicode por valor de punto de código

### Descripción

public static function IntlChar::chr(int|string `$codepoint`): ?string

Devuelve una cadena que contiene el carácter especificado por el valor de punto de código Unicode.

Este método complementa IntlChar::ord().

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Una cadena que contiene el carácter único especificado por el valor de punto de código Unicode, o `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    $values = ["A", 63, 123, 9731];
    foreach ($values as $value) {
        var_dump(IntlChar::chr($value));
    }
    ?>

El ejemplo anterior mostrará:

    string(1) "A"
    string(1) "?"
    string(1) "{"
    string(3) "☃"

### Ver también

- IntlChar::ord() - Devuelve el valor del punto de código Unicode de un carácter
- mb_chr() - Devuelve un carácter por su valor de punto de código Unicode
- chr() - Generar un string de un byte a partir de un número

# IntlChar::digit

(PHP 7, PHP 8)

IntlChar::digit — Devuelve el dígito decimal de un punto de código para una base de numeración dada

### Descripción

public static function IntlChar::digit(int|string `$codepoint`, int `$base` = 10): int|false|null

Devuelve el valor decimal del punto de código en la base de numeración especificada.

Si la base de numeración no está en el rango `2 <= radix <= 36` o si el valor de `codepoint` no es un dígito válido en la base especificada, `false` es devuelto. Un carácter es un dígito válido si al menos una de las condiciones siguientes es verdadera:

- El carácter tiene un valor de dígito decimal. Estos caracteres tienen la categoría general "Nd" (dígitos decimales) y un Numeric_Type de "Decimal". En este caso, el valor es el valor de dígito decimal del carácter.
- El carácter es una de las letras latinas mayúsculas `'A'` a `'Z'`. En este caso, el valor es `codepoint - 'A' + 10`.
- El carácter es una de las letras latinas minúsculas `'a'` a `'z'`. En este caso, el valor es `codepoint - 'a' + 10`.
- Las letras latinas del rango ASCII (`0061..007A`, `0041..005A`) así como del rango ASCII de ancho completo (`FF41..FF5A`, `FF21..FF3A`) son reconocidas.

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)
`base`

  La base de numeración (por omisión `10`).

### Valores devueltos

Devuelve el valor numérico representado por el carácter en la base de numeración especificada, o `false` si no hay valor o si el valor excede la base. Devuelve `null` en caso de fallo.

Advertencia

Esta función puede retornar `false`, pero también puede retornar un valor equivalente a `false`. Por favor, lea la sección sobre los booleanos para más información. Utilice el operador === para probar el valor de retorno exacto de esta función.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php

    var_dump(IntlChar::digit("0"));
    var_dump(IntlChar::digit("3"));

    var_dump(IntlChar::digit("A", 16));
    var_dump(IntlChar::digit("A"));

    ?>

El ejemplo anterior mostrará:

    int(0)
    int(3)
    int(10)
    bool(false)

### Ver también

- IntlChar::forDigit() - Devuelve la representación de carácter para un dígito dado y una base de numeración
- IntlChar::charDigitValue() - Devuelve el valor decimal del dígito decimal
- IntlChar::isdigit() - Verifica si un punto de código es un dígito
- `IntlChar::PROPERTY_NUMERIC_TYPE`

# IntlChar::enumCharNames

(PHP 7, PHP 8)

IntlChar::enumCharNames — Enumera todos los caracteres Unicode asignados en un rango

### Descripción

public static function IntlChar::enumCharNames(
int|string `$start`,
int|string `$end`,
callable `$callback`,
int `$type` = `IntlChar::UNICODE_CHAR_NAME`
): bool

Enumera todos los caracteres Unicode asignados entre los puntos de código de inicio y fin (inclusive el inicio, exclusivo el fin) y llama a una función para cada uno, pasando el valor del punto de código y el nombre del carácter.

Para los nombres Unicode 1.0, solo aquellos que difieren de los nombres modernos son enumerados.

### Parámetros

`start`

  El primer punto de código en el rango de enumeración.

`end`

  Un o más puntos de código adicionales al último punto de código en el rango de enumeración (el primero después del rango).

`callback`

  La función que debe ser llamada para cada nombre de carácter. Los tres argumentos siguientes le serán pasados:

  - int `$codepoint` - El valor numérico del punto de código
  - int `$nameChoice` - El mismo valor que el parámetro `type` a continuación
  - string `$name` - El nombre del carácter
`type`

  Un selector para el tipo de nombres a enumerar. Puede ser una de las constantes siguientes:

  - `IntlChar::UNICODE_CHAR_NAME` (por omisión)
  - `IntlChar::UNICODE_10_CHAR_NAME`
  - `IntlChar::EXTENDED_CHAR_NAME`
  - `IntlChar::CHAR_NAME_ALIAS`
  - `IntlChar::CHAR_NAME_CHOICE_COUNT`

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Este método devuelve ahora `false` en caso de fallo; previamente devolvía `null`.

### Ejemplos

Ejemplo #1 Enumera un rango de ejemplos de puntos de código

    <?php
    IntlChar::enumCharNames(0x2600, 0x2610, function($codepoint, $nameChoice, $name) {
        printf("U+%04x %s\n", $codepoint, $name);
    });
    ?>

El ejemplo anterior mostrará:

    U+2600 BLACK SUN WITH RAYS
    U+2601 CLOUD
    U+2602 UMBRELLA
    U+2603 SNOWMAN
    U+2604 COMET
    U+2605 BLACK STAR
    U+2606 WHITE STAR
    U+2607 LIGHTNING
    U+2608 THUNDERSTORM
    U+2609 SUN
    U+260a ASCENDING NODE
    U+260b DESCENDING NODE
    U+260c CONJUNCTION
    U+260d OPPOSITION
    U+260e BLACK TELEPHONE
    U+260f WHITE TELEPHONE

### Ver también

- IntlChar::charName() - Devuelve el nombre de un carácter Unicode
- IntlChar::charFromName() - Encuentra un carácter Unicode por su nombre y devuelve su valor de punto de código

# IntlChar::enumCharTypes

(PHP 7, PHP 8)

IntlChar::enumCharTypes — Enumera todos los puntos de código con sus categorías generales Unicode

### Descripción

public static function IntlChar::enumCharTypes(callable `$callback`): void

Enumera eficientemente todos los puntos de código con sus categorías generales Unicode. Esto es útil para construir estructuras de datos, para enumerar todos los puntos de código asignados, etc.

Para cada rango de puntos de código contiguos con una categoría general dada ("tipo de carácter"), se llama a la función `callback`. Los rangos adyacentes tienen tipos diferentes. La norma Unicode garantiza que el valor numérico del tipo es 0..31.

### Parámetros

`callback`

  La función que debe ser llamada para cada rango de puntos de código contiguos con la misma categoría general. Se le pasarán los tres argumentos siguientes:

  - int `$start` - El punto de código de inicio del rango
  - int `$end` - El punto de código de fin del rango
  - int `$name` - El tipo de carácter (una de las constantes `IntlChar::CHAR_CATEGORY_*`)

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Enumera un rango de ejemplo de puntos de código

    <?php
    IntlChar::enumCharTypes(function($start, $end, $type) {
        printf("U+%04x through U+%04x are in category %d\n", $start, $end, $type);
    });
    ?>

El ejemplo anterior mostrará:

    U+0000 through U+0020 are in category 15
    U+0020 through U+0021 are in category 12
    U+0021 through U+0024 are in category 23
    U+0024 through U+0025 are in category 25
    U+0025 through U+0028 are in category 23
    U+0028 through U+0029 are in category 20
    U+0029 through U+002a are in category 21
    U+002a through U+002b are in category 23
    U+002b through U+002c are in category 24
    U+002c through U+002d are in category 23
    U+002d through U+002e are in category 19
    U+002e through U+0030 are in category 23
    U+0030 through U+003a are in category 9
    ...

# IntlChar::foldCase

(PHP 7, PHP 8)

IntlChar::foldCase — Realiza el plegado de mayúsculas/minúsculas sobre un punto de código

### Descripción

public static function IntlChar::foldCase(int|string `$codepoint`, int `$options` = `IntlChar::FOLD_CASE_DEFAULT`): int|string|null

El carácter dado se mapea a su equivalente de plegado de mayúsculas/minúsculas; si el carácter no tiene equivalente de plegado de mayúsculas/minúsculas, se devuelve el carácter mismo.

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)
`options`

  Puede ser `IntlChar::FOLD_CASE_DEFAULT` (valor por omisión) o `IntlChar::FOLD_CASE_EXCLUDE_SPECIAL_I`.

### Valores devueltos

Devuelve el plegado de mayúsculas/minúsculas simple del punto de código, si está disponible; de lo contrario, el punto de código mismo en caso de éxito, o `null` en caso de fallo.

# IntlChar::forDigit

(PHP 7, PHP 8)

IntlChar::forDigit — Devuelve la representación de carácter para un dígito dado y una base de numeración

### Descripción

public static function IntlChar::forDigit(int `$digit`, int `$base` = 10): int

Determina la representación de carácter para un dígito específico en la base de numeración especificada.

Si el valor de la base de numeración no es una base de numeración válida, o si el valor del dígito no es un dígito válido en la base especificada, se devuelve el carácter nulo (`U+0000`).

La base de numeración es válida si es superior o igual a `2` e inferior o igual a `36`. El valor del dígito es válido si `0 <= dígito < base`.

Si el dígito es inferior a `10`, entonces '0' + dígito es devuelto. De lo contrario, se devuelve el valor 'a' + dígito - 10.

### Parámetros

`digit`

  El dígito a convertir en carácter.

`base`

  La base de numeración (por omisión `10`).

### Valores devueltos

El carácter representativo (en forma de int) del dígito especificado en la base de numeración especificada.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::forDigit(0));
    var_dump(IntlChar::forDigit(3));
    var_dump(IntlChar::forDigit(3, 10));
    var_dump(IntlChar::forDigit(10));
    var_dump(IntlChar::forDigit(10, 16));
    ?>

El ejemplo anterior mostrará:

    int(48)
    int(51)
    int(51)
    int(0)
    int(97)

### Ver también

- IntlChar::digit() - Devuelve el dígito decimal de un punto de código para una base de numeración dada
- IntlChar::charDigitValue() - Devuelve el valor decimal del dígito decimal
- IntlChar::isdigit() - Verifica si un punto de código es un dígito
- `IntlChar::PROPERTY_NUMERIC_TYPE`

# IntlChar::getBidiPairedBracket

(PHP 7, PHP 8)

IntlChar::getBidiPairedBracket — Devuelve el carácter de paréntesis emparejado para un punto de código

### Descripción

public static function IntlChar::getBidiPairedBracket(int|string `$codepoint`): int|string|null

Mapea el carácter especificado a su carácter de paréntesis emparejado.

Para `IntlChar::PROPERTY_BIDI_PAIRED_BRACKET_TYPE !== IntlChar::BPT_NONE`, esto equivale a IntlChar::charMirror().

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve el punto de código del paréntesis emparejado, o `codepoint` mismo si no hay mapeo. Devuelve `null` en caso de error.

El tipo de retorno es int a menos que el punto de código haya sido pasado como un string UTF-8, en cuyo caso se devuelve un string. Devuelve `null` en caso de fallo.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::getBidiPairedBracket(91));
    var_dump(IntlChar::getBidiPairedBracket('['));
    ?>

El ejemplo anterior mostrará:

    int(93)
    string(1) "]"

### Notas

> Nota:

> Este método está disponible desde la versión 52 de ICU.

### Ver también

- IntlChar::charMirror() - Devuelve el carácter "imagen-espejo" para un punto de código
- `IntlChar::PROPERTY_BIDI_PAIRED_BRACKET`
- `IntlChar::PROPERTY_BIDI_PAIRED_BRACKET_TYPE`

# IntlChar::getBlockCode

(PHP 7, PHP 8)

IntlChar::getBlockCode — Devuelve el bloque de asignación Unicode que contiene un punto de código

### Descripción

public static function IntlChar::getBlockCode(int|string `$codepoint`): ?int

Devuelve el bloque de asignación Unicode que contiene el carácter.

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve el valor del bloque para `codepoint`. Consulte las constantes `IntlChar::BLOCK_CODE_*` para los valores de retorno posibles. Devuelve `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::getBlockCode("A") === IntlChar::BLOCK_CODE_BASIC_LATIN);
    var_dump(IntlChar::getBlockCode("Φ") === IntlChar::BLOCK_CODE_GREEK);
    var_dump(IntlChar::getBlockCode("\u{2603}") === IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS);
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(true)
    bool(true)

# IntlChar::getCombiningClass

(PHP 7, PHP 8)

IntlChar::getCombiningClass — Devuelve la clase de combinación de un punto de código

### Descripción

public static function IntlChar::getCombiningClass(int|string `$codepoint`): ?int

Devuelve la clase de combinación del punto de código.

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve la clase de combinación del carácter. Devuelve `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::getCombiningClass("A"));
    var_dump(IntlChar::getCombiningClass("\u{0334}"));
    var_dump(IntlChar::getCombiningClass("\u{0358}"));
    ?>

El ejemplo anterior mostrará:

    int(0)
    int(1)
    int(232)

# IntlChar::getFC_NFKC_Closure

(PHP 7, PHP 8)

IntlChar::getFC_NFKC_Closure — Devuelve la propiedad FC_NFKC_Closure para un punto de código

### Descripción

public static function IntlChar::getFC_NFKC_Closure(int|string `$codepoint`): string|false|null

Devuelve la propiedad FC_NFKC_Closure para un carácter.

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve la propiedad FC_NFKC_Closure para el `codepoint`, o una cadena vacía si no existe. Devuelve `null` o `false` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::getFC_NFKC_Closure("\u{2121}"));
    var_dump(IntlChar::getFC_NFKC_Closure("\u{1D2D}"));
    ?>

El ejemplo anterior mostrará:

    string(3) "tel"
    string(2) "æ"

# IntlChar::getIntPropertyMaxValue

(PHP 7, PHP 8)

IntlChar::getIntPropertyMaxValue — Devuelve el valor máximo para una propiedad Unicode

### Descripción

public static function IntlChar::getIntPropertyMaxValue(int `$property`): int

Devuelve el valor máximo para una propiedad Unicode enumerada/entera/binaria.

### Parámetros

`property`
  La propiedad Unicode a buscar (véanse las constantes `IntlChar::PROPERTY_*`).

### Valores devueltos

El valor máximo devuelto por IntlChar::getIntPropertyValue() para una propiedad Unicode. `<=0` si el selector de propiedad está fuera de alcance.

### Ejemplos

Ejemplo #1 Probar diferentes propiedades

    <?php
    var_dump(IntlChar::getIntPropertyMaxValue(IntlChar::PROPERTY_BIDI_CLASS));
    var_dump(IntlChar::getIntPropertyMaxValue(IntlChar::PROPERTY_SCRIPT));
    var_dump(IntlChar::getIntPropertyMaxValue(IntlChar::PROPERTY_IDEOGRAPHIC));
    var_dump(IntlChar::getIntPropertyMaxValue(999999999)); // Un valor inventado
    ?>

El ejemplo anterior mostrará:

    int(22)
    int(166)
    int(1)
    int(-1)

### Ver también

- IntlChar::hasBinaryProperty() - Verifica una propiedad Unicode binaria para un punto de código
- IntlChar::getIntPropertyMinValue() - Devuelve el valor mínimo para una propiedad Unicode
- IntlChar::getIntPropertyValue() - Devuelve el valor de una propiedad Unicode para un punto de código
- IntlChar::getUnicodeVersion() - Devuelve la versión Unicode

# IntlChar::getIntPropertyMinValue

(PHP 7, PHP 8)

IntlChar::getIntPropertyMinValue — Devuelve el valor mínimo para una propiedad Unicode

### Descripción

public static function IntlChar::getIntPropertyMinValue(int `$property`): int

Devuelve el valor mínimo para una propiedad Unicode enumerada/entera/binaria.

### Parámetros

`property`
  La propiedad Unicode a buscar (véanse las constantes `IntlChar::PROPERTY_*`).

### Valores devueltos

El valor mínimo devuelto por IntlChar::getIntPropertyValue() para una propiedad Unicode. `0` si el selector de propiedad está fuera de alcance.

### Ejemplos

Ejemplo #1 Probar diferentes propiedades

    <?php
    var_dump(IntlChar::getIntPropertyMinValue(IntlChar::PROPERTY_BIDI_CLASS));
    var_dump(IntlChar::getIntPropertyMinValue(IntlChar::PROPERTY_SCRIPT));
    var_dump(IntlChar::getIntPropertyMinValue(IntlChar::PROPERTY_IDEOGRAPHIC));
    var_dump(IntlChar::getIntPropertyMinValue(999999999)); // Un valor inventado
    ?>

El ejemplo anterior mostrará:

    int(0)
    int(0)
    int(0)
    int(0)

### Ver también

- IntlChar::hasBinaryProperty() - Verifica una propiedad Unicode binaria para un punto de código
- IntlChar::getIntPropertyMaxValue() - Devuelve el valor máximo para una propiedad Unicode
- IntlChar::getIntPropertyValue() - Devuelve el valor de una propiedad Unicode para un punto de código
- IntlChar::getUnicodeVersion() - Devuelve la versión Unicode

# IntlChar::getIntPropertyValue

(PHP 7, PHP 8)

IntlChar::getIntPropertyValue — Devuelve el valor de una propiedad Unicode para un punto de código

### Descripción

public static function IntlChar::getIntPropertyValue(int|string `$codepoint`, int `$property`): ?int

Devuelve el valor de una propiedad Unicode enumerada o entera para un punto de código. Asimismo, devuelve los valores de propiedad binaria y de máscara.

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)
`property`
  La propiedad Unicode a buscar (véanse las constantes `IntlChar::PROPERTY_*`).

### Valores devueltos

Devuelve el valor numérico que es directamente el valor de la propiedad o, para las propiedades enumeradas, corresponde al valor numérico de la constante enumerada del tipo de enumeración de valor de propiedad respectiva. Devuelve `null` en caso de error.

Devuelve `0` o `1` (para `false`/`true`) para las propiedades binarias Unicode.

Devuelve una máscara de bits para las propiedades de máscara.

Devuelve `0` si `property` está fuera de alcance o si la versión Unicode no tiene datos para la propiedad, o no para este punto de código.

### Ejemplos

Ejemplo #1 Probar diferentes propiedades

    <?php
    var_dump(IntlChar::getIntPropertyValue("A", IntlChar::PROPERTY_ALPHABETIC) === 1);
    var_dump(IntlChar::getIntPropertyValue("[", IntlChar::PROPERTY_BIDI_MIRRORED) === 1);
    var_dump(IntlChar::getIntPropertyValue("Φ", IntlChar::PROPERTY_BLOCK) === IntlChar::BLOCK_CODE_GREEK);
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(true)
    bool(true)

### Ver también

- IntlChar::hasBinaryProperty() - Verifica una propiedad Unicode binaria para un punto de código
- IntlChar::getIntPropertyMinValue() - Devuelve el valor mínimo para una propiedad Unicode
- IntlChar::getIntPropertyMaxValue() - Devuelve el valor máximo para una propiedad Unicode
- IntlChar::getUnicodeVersion() - Devuelve la versión Unicode

# IntlChar::getNumericValue

(PHP 7, PHP 8)

IntlChar::getNumericValue — Devuelve el valor numérico de un punto de código Unicode

### Descripción

public static function IntlChar::getNumericValue(int|string `$codepoint`): ?float

Devuelve el valor numérico de un punto de código Unicode tal como se define en la base de datos de caracteres Unicode.

Para los caracteres sin valor numérico en la base de datos de caracteres Unicode, esta función devolverá `IntlChar::NO_NUMERIC_VALUE`.

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

El valor numérico del `codepoint`, o `IntlChar::NO_NUMERIC_VALUE` si no está definido. Esta constante fue añadida en PHP 7.0.6, antes de esta versión el valor literal (float)`-123456789` puede ser utilizado en su lugar. Devuelve `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::getNumericValue("4"));
    var_dump(IntlChar::getNumericValue("x"));
    var_dump(IntlChar::getNumericValue("\u{216C}"));
    ?>

El ejemplo anterior mostrará:

    float(4)
    float(-123456789)
    float(50)

# IntlChar::getPropertyEnum

(PHP 7, PHP 8)

IntlChar::getPropertyEnum — Devuelve el valor de la constante de propiedad para un nombre de propiedad dado

### Descripción

public static function IntlChar::getPropertyEnum(string `$alias`): int

Devuelve el valor de la constante de propiedad para un nombre de propiedad dado, tal como se especifica en el archivo de base de datos Unicode PropertyAliases.txt. Se reconocen las variantes cortas, largas y otras.

Además, esta función mapea los nombres sintéticos "gcm" / "General_Category_Mask" a la propiedad `IntlChar::PROPERTY_GENERAL_CATEGORY_MASK`. Estos nombres no están en PropertyAliases.txt.

Esta función complementa IntlChar::getPropertyName().

### Parámetros

`alias`

  El nombre de la propiedad a buscar. El nombre se compara utilizando una "coincidencia flexible" como se describe en PropertyAliases.txt.

### Valores devueltos

Devuelve un valor de constante `IntlChar::PROPERTY_`, o `IntlChar::PROPERTY_INVALID_CODE` si el nombre dado no coincide con ninguna propiedad.

### Ejemplos

Ejemplo #1 Probar diferentes propiedades

    <?php
    var_dump(IntlChar::getPropertyEnum('Bidi_Class') === IntlChar::PROPERTY_BIDI_CLASS);
    var_dump(IntlChar::getPropertyEnum('script') === IntlChar::PROPERTY_SCRIPT);
    var_dump(IntlChar::getPropertyEnum('IDEOGRAPHIC') === IntlChar::PROPERTY_IDEOGRAPHIC);
    var_dump(IntlChar::getPropertyEnum('Some made-up string') === IntlChar::PROPERTY_INVALID_CODE);
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(true)
    bool(true)
    bool(true)

### Ver también

- IntlChar::getPropertyName() - Devuelve el nombre Unicode de una propiedad

# IntlChar::getPropertyName

(PHP 7, PHP 8)

IntlChar::getPropertyName — Devuelve el nombre Unicode de una propiedad

### Descripción

public static function IntlChar::getPropertyName(int `$property`, int `$type` = `IntlChar::LONG_PROPERTY_NAME`): string|false

Devuelve el nombre Unicode de una propiedad dada, tal como se indica en el archivo de base de datos Unicode PropertyAliases.txt.

Además, esta función mapea la propiedad `IntlChar::PROPERTY_GENERAL_CATEGORY_MASK` a los nombres sintéticos "gcm" / "General_Category_Mask". Estos nombres no están en PropertyAliases.txt.

Esta función complementa IntlChar::getPropertyEnum().

### Parámetros

`property`
  La propiedad Unicode a buscar (véanse las constantes `IntlChar::PROPERTY_*`).

  `IntlChar::PROPERTY_INVALID_CODE` no debe ser utilizado. Además, si `property` está fuera de rango, `false` es devuelto.

`type`

  El selector para el nombre a obtener. Si está fuera de rango, `false` es devuelto.

  Todas las propiedades tienen un nombre largo. La mayoría tienen un nombre corto, pero algunas no lo tienen. Unicode permite nombres adicionales; si están presentes, serán devueltos añadiendo 1, 2, etc. a `IntlChar::LONG_PROPERTY_NAME`.

### Valores devueltos

Devuelve el nombre, o `false` si `property` o `type` están fuera de rango.

Si un `type` dado devuelve `false`, entonces todos los valores más grandes de `type` devolverán `false`, con una excepción: si `false` es devuelto para `IntlChar::SHORT_PROPERTY_NAME`, entonces `IntlChar::LONG_PROPERTY_NAME` (y más) puede aún devolver un valor no-`false`.

### Ejemplos

Ejemplo #1 Probar diferentes propiedades

    <?php
    var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS));
    var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS, IntlChar::SHORT_PROPERTY_NAME));
    var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS, IntlChar::LONG_PROPERTY_NAME));
    var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS, IntlChar::LONG_PROPERTY_NAME + 1));
    ?>

El ejemplo anterior mostrará:

    string(10) "Bidi_Class"
    string(2) "bc"
    string(10) "Bidi_Class"
    bool(false)

### Ver también

- IntlChar::getPropertyEnum() - Devuelve el valor de la constante de propiedad para un nombre de propiedad dado

# IntlChar::getPropertyValueEnum

(PHP 7, PHP 8)

IntlChar::getPropertyValueEnum — Devuelve el valor de propiedad para un nombre de valor dado

### Descripción

public static function IntlChar::getPropertyValueEnum(int `$property`, string `$name`): int

Devuelve el valor de propiedad entero para un nombre de valor dado, tal como se especifica en el archivo de base de datos Unicode PropertyValueAliases.txt. Las variantes cortas, largas y otras son reconocidas.

> Nota:

> Algunos nombres en PropertyValueAliases.txt solo serán reconocidos con `IntlChar::PROPERTY_GENERAL_CATEGORY_MASK`, no `IntlChar::PROPERTY_GENERAL_CATEGORY`. Estos incluyen:

> - "C" / "Otro"
> - "L" / "Letra"
> - "LC" / "Letra_Mayúscula"
> - "M" / "Marca"
> - "N" / "Número"
> - "P" / "Puntuación"
> - "S" / "Símbolo"
> - "Z" / "Separador"

### Parámetros

`property`
  La propiedad Unicode a buscar (véanse las constantes `IntlChar::PROPERTY_*`).

  Si está fuera de alcance, o si este método no funciona con el valor dado, `IntlChar::PROPERTY_INVALID_CODE` es devuelto.

`name`

  El valor de nombre a buscar. El nombre es comparado utilizando una "coincidencia floja" como se describe en PropertyValueAliases.txt.

### Valores devueltos

Devuelve el valor entero correspondiente, o `IntlChar::PROPERTY_INVALID_CODE` si el nombre dado no coincide con ningún valor de la propiedad dada, o si la propiedad es inválida.

### Ejemplos

Ejemplo #1 Probar diferentes propiedades

    <?php
    var_dump(IntlChar::getPropertyValueEnum(IntlChar::PROPERTY_BLOCK, 'greek') === IntlChar::BLOCK_CODE_GREEK);
    var_dump(IntlChar::getPropertyValueEnum(IntlChar::PROPERTY_BIDI_CLASS, 'RIGHT_TO_LEFT') === IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT);
    var_dump(IntlChar::getPropertyValueEnum(IntlChar::PROPERTY_BIDI_CLASS, 'some made-up string') === IntlChar::PROPERTY_INVALID_CODE);
    var_dump(IntlChar::getPropertyValueEnum(123456789, 'RIGHT_TO_LEFT') === IntlChar::PROPERTY_INVALID_CODE);
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(true)
    bool(true)
    bool(true)

# IntlChar::getPropertyValueName

(PHP 7, PHP 8)

IntlChar::getPropertyValueName — Devuelve el nombre Unicode para un valor de propiedad

### Descripción

public static function IntlChar::getPropertyValueName(int `$property`, int `$value`, int `$type` = `IntlChar::LONG_PROPERTY_NAME`): string|false

Devuelve el nombre Unicode para un valor de propiedad dado, tal como se indica en el archivo de base de datos Unicode PropertyValueAliases.txt.

> Nota:

> Algunos nombres en PropertyValueAliases.txt solo pueden obtenerse utilizando `IntlChar::PROPERTY_GENERAL_CATEGORY_MASK`, no `IntlChar::PROPERTY_GENERAL_CATEGORY`. Estos incluyen:

> - "C" / "Otro"
> - "L" / "Letra"
> - "LC" / "Letra_Mayúscula"
> - "M" / "Marca"
> - "N" / "Número"
> - "P" / "Puntuación"
> - "S" / "Símbolo"
> - "Z" / "Separador"

### Parámetros

`property`
  La propiedad Unicode a buscar (véanse las constantes `IntlChar::PROPERTY_*`).

  Si está fuera de alcance, o si este método no funciona con el valor dado, se devuelve `false`.

`value`

  El selector para un valor de la propiedad dada. Si está fuera de alcance, se devuelve `false`.

  En general, los valores válidos van desde `0` hasta un máximo. Hay algunas excepciones:

  - `IntlChar::PROPERTY_BLOCK` los valores comienzan con el valor no nulo `IntlChar::BLOCK_CODE_BASIC_LATIN`
  - `IntlChar::PROPERTY_CANONICAL_COMBINING_CLASS` los valores no son contiguos y van de 0 a 240.
`type`

  El selector para el nombre a obtener. Si está fuera de alcance, se devuelve `false`.

  Todos los valores tienen un nombre largo. La mayoría tienen un nombre corto, pero algunos no. Unicode permite nombres adicionales; si están presentes, se devolverán añadiendo 1, 2, etc. a `IntlChar::LONG_PROPERTY_NAME`.

### Valores devueltos

Devuelve el nombre, o `false` si `property` o `type` están fuera de alcance. Devuelve `null` en caso de error.

Si un `type` dado devuelve `false`, entonces todos los valores mayores de `type` devolverán `false`, con una excepción: si `false` se devuelve para `IntlChar::SHORT_PROPERTY_NAME`, entonces `IntlChar::LONG_PROPERTY_NAME` (y más) aún puede devolver un valor no-`false`.

### Ejemplos

Ejemplo #1 Probar diferentes propiedades

    <?php
    var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK));
    var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK, IntlChar::SHORT_PROPERTY_NAME));
    var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK, IntlChar::LONG_PROPERTY_NAME));
    var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK, IntlChar::LONG_PROPERTY_NAME + 1));
    ?>

El ejemplo anterior mostrará:

    string(16) "Greek_And_Coptic"
    string(5) "Greek"
    string(16) "Greek_And_Coptic"
    bool(false)

# IntlChar::getUnicodeVersion

(PHP 7, PHP 8)

IntlChar::getUnicodeVersion — Devuelve la versión Unicode

### Descripción

public static function IntlChar::getUnicodeVersion(): array

Devuelve las informaciones de versión Unicode.

El array de versión se rellena con las informaciones de versión para la norma Unicode actualmente utilizada por ICU. Por ejemplo, la versión Unicode 3.1.1 se representa mediante un array con los valores `[3, 1, 1, 0]`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array que contiene el número de versión Unicode.

### Ejemplos

Ejemplo #1 Probar diferentes propiedades

    <?php
    var_dump(IntlChar::getUnicodeVersion());
    ?>

El ejemplo anterior mostrará:

    array(4) {
      [0]=>
      int(7)
      [1]=>
      int(0)
      [2]=>
      int(0)
      [3]=>
      int(0)
    }

### Ver también

- IntlChar::charAge() - Devuelve la "edad" del punto de código

# IntlChar::hasBinaryProperty

(PHP 7, PHP 8)

IntlChar::hasBinaryProperty — Verifica una propiedad Unicode binaria para un punto de código

### Descripción

public static function IntlChar::hasBinaryProperty(int|string `$codepoint`, int `$property`): ?bool

Verifica una propiedad Unicode binaria para un punto de código.

Unicode, en particular en la versión 3.2, define muchas más propiedades que el conjunto original en UnicodeData.txt.

Las API de propiedades están destinadas a reflejar las propiedades Unicode tal como se definen en la base de datos de caracteres Unicode (UCD) y los informes técnicos Unicode (UTR). Para más detalles sobre las propiedades, ver » http://www.unicode.org/ucd/. Para los nombres de las propiedades Unicode, ver el archivo UCD PropertyAliases.txt.

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)
`property`
  La propiedad Unicode a buscar (véanse las constantes `IntlChar::PROPERTY_*`).

### Valores devueltos

Devuelve `true` o `false` según el valor de la propiedad Unicode binaria para `codepoint`. También devuelve `false` si `property` está fuera de alcance o si la versión Unicode no tiene datos para la propiedad en absoluto, o no para este punto de código. Devuelve `null` en caso de fallo.

### Ejemplos

Ejemplo #1 Probar diferentes propiedades

    <?php
    var_dump(IntlChar::hasBinaryProperty("A", IntlChar::PROPERTY_ALPHABETIC));
    var_dump(IntlChar::hasBinaryProperty("A", IntlChar::PROPERTY_CASE_SENSITIVE));
    var_dump(IntlChar::hasBinaryProperty("A", IntlChar::PROPERTY_BIDI_MIRRORED));
    var_dump(IntlChar::hasBinaryProperty("[", IntlChar::PROPERTY_ALPHABETIC));
    var_dump(IntlChar::hasBinaryProperty("[", IntlChar::PROPERTY_CASE_SENSITIVE));
    var_dump(IntlChar::hasBinaryProperty("[", IntlChar::PROPERTY_BIDI_MIRRORED));
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(true)
    bool(false)
    bool(false)
    bool(false)
    bool(true)

### Ver también

- IntlChar::getIntPropertyValue() - Devuelve el valor de una propiedad Unicode para un punto de código
- IntlChar::getUnicodeVersion() - Devuelve la versión Unicode

# IntlChar::isalnum

(PHP 7, PHP 8)

IntlChar::isalnum — Verifica si un punto de código es un carácter alfanumérico

### Descripción

public static function IntlChar::isalnum(int|string `$codepoint`): ?bool

Determina si el punto de código especificado es un carácter alfanumérico (letra o dígito). `true` para los caracteres con las categorías generales "L" (letras) y "Nd" (dígitos decimales).

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` es un carácter alfanumérico, `false` en caso contrario. Devuelve `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::isalnum("A"));
    var_dump(IntlChar::isalnum("1"));
    var_dump(IntlChar::isalnum("\u{2603}"));
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(true)
    bool(false)

### Ver también

- IntlChar::isalpha() - Verifica si un punto de código es un carácter alfabético
- IntlChar::isdigit() - Verifica si un punto de código es un dígito
- ctype_alnum() - Chequear posibles caracteres alfanuméricos

# IntlChar::isalpha

(PHP 7, PHP 8)

IntlChar::isalpha — Verifica si un punto de código es un carácter alfabético

### Descripción

public static function IntlChar::isalpha(int|string `$codepoint`): ?bool

Determina si el punto de código especificado es un carácter alfabético. `true` para las categorías generales "L" (letras).

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` es un carácter alfabético, `false` en caso contrario. Devuelve `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::isalpha("A"));
    var_dump(IntlChar::isalpha("1"));
    var_dump(IntlChar::isalpha("\u{2603}"));
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(false)
    bool(false)

### Ver también

- IntlChar::isalnum() - Verifica si un punto de código es un carácter alfanumérico
- IntlChar::isdigit() - Verifica si un punto de código es un dígito
- ctype_alpha() - Chequear posibles caracteres alfabéticos

# IntlChar::isbase

(PHP 7, PHP 8)

IntlChar::isbase — Verifica si un punto de código es un carácter de base

### Descripción

public static function IntlChar::isbase(int|string `$codepoint`): ?bool

Determina si el punto de código especificado es un carácter de base. `true` para las categorías generales "L" (letras), "N" (números), "Mc" (marcas de combinación de espaciado), y "Me" (marcas de encuadre).

> Nota:

> Esto difiere de la definición Unicode en el capítulo 3.5, cláusula de conformidad D13, que define los caracteres de base como todos los caracteres (no Cn) que no se combinan gráficamente con los caracteres anteriores (M) y que no son caracteres de control (Cc) ni caracteres de formato (Cf).

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` es un carácter de base, `false` en caso contrario. Devuelve `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::isbase("A"));
    var_dump(IntlChar::isbase("1"));
    var_dump(IntlChar::isbase("\u{2603}"));
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(true)
    bool(false)

### Ver también

- IntlChar::isalpha() - Verifica si un punto de código es un carácter alfabético
- IntlChar::isdigit() - Verifica si un punto de código es un dígito

# IntlChar::isblank

(PHP 7, PHP 8)

IntlChar::isblank — Verifica si un punto de código es un carácter "blanco" o "espacio horizontal"

### Descripción

public static function IntlChar::isblank(int|string `$codepoint`): ?bool

Determina si el punto de código especificado es un carácter "blanco" o "espacio horizontal", un carácter que separa visualmente las palabras en una línea.

Las definiciones siguientes son equivalentes:

- `true` para los caracteres Unicode White_Space con excepción de los "controles de espacio vertical" donde los "controles de espacio vertical" son los caracteres siguientes: U+000A (LF) U+000B (VT) U+000C (FF) U+000D (CR) U+0085 (NEL) U+2028 (LS) U+2029 (PS)
- `true` para U+0009 (TAB) y los caracteres de categoría general "Zs" (separadores de espacio) con excepción del espacio de ancho cero (ZWSP, U+200B).

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` es un carácter "blanco" o "espacio horizontal", `false` en caso contrario. Devuelve `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::isblank("A"));
    var_dump(IntlChar::isblank(" "));
    var_dump(IntlChar::isblank("\t"));
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(true)
    bool(true)

### Ver también

- IntlChar::isspace() - Verifica si un punto de código es un carácter de espacio
- IntlChar::isJavaSpaceChar() - Verifica si un punto de código es un carácter de espacio según Java
- IntlChar::isUWhiteSpace() - Verifica si un punto de código tiene la propiedad Unicode White_Space
- IntlChar::isWhitespace() - Verifica si un punto de código es un carácter de espacio según ICU

# IntlChar::iscntrl

(PHP 7, PHP 8)

IntlChar::iscntrl — Verifica si un punto de código es un carácter de control

### Descripción

public static function IntlChar::iscntrl(int|string `$codepoint`): ?bool

Determina si el punto de código especificado es un carácter de control.

Un carácter de control es uno de los siguientes:

- Carácter de control ISO de 8 bits (U+0000..U+001f y U+007f..U+009f)
- `IntlChar::CHAR_CATEGORY_CONTROL_CHAR` (Cc)
- `IntlChar::CHAR_CATEGORY_FORMAT_CHAR` (Cf)
- `IntlChar::CHAR_CATEGORY_LINE_SEPARATOR` (Zl)
- `IntlChar::CHAR_CATEGORY_PARAGRAPH_SEPARATOR` (Zp)

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` es un carácter de control, `false` en caso contrario. Devuelve `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::iscntrl("A"));
    var_dump(IntlChar::iscntrl(" "));
    var_dump(IntlChar::iscntrl("\n"));
    var_dump(IntlChar::iscntrl("\u{200e}"));
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(false)
    bool(true)
    bool(true)

### Ver también

- IntlChar::isprint() - Verifica si un punto de código es un carácter imprimible
- `IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT`
- ctype_cntrl() - Chequear posibles caracteres de control

# IntlChar::isdefined

(PHP 7, PHP 8)

IntlChar::isdefined — Verifica si un punto de código está definido

### Descripción

public static function IntlChar::isdefined(int|string `$codepoint`): ?bool

Determina si el punto de código especificado está "definido", lo cual generalmente significa que está asignado a un carácter.

`true` para las categorías generales distintas de "Cn" (otro, no asignado).

> Nota:

> Es importante señalar que los puntos de código no caracteres (por ejemplo, U+FDD0) no están "definidos" (son Cn), pero los puntos de código de sustitución sí están "definidos" (Cs).

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` es un carácter definido, `false` en caso contrario. Devuelve `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::isdefined("A"));
    var_dump(IntlChar::isdefined(" "));
    var_dump(IntlChar::isdefined("\u{FDD0}"));
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(true)
    bool(false)

### Ver también

- IntlChar::isdigit() - Verifica si un punto de código es un dígito
- IntlChar::isalpha() - Verifica si un punto de código es un carácter alfabético
- IntlChar::isalnum() - Verifica si un punto de código es un carácter alfanumérico
- IntlChar::isupper() - Verifica si un punto de código tiene la categoría general "Lu" (letra mayúscula)
- IntlChar::islower() - Verifica si un punto de código es una letra minúscula
- IntlChar::istitle() - Verifica si un punto de código es una letra en título

# IntlChar::isdigit

(PHP 7, PHP 8)

IntlChar::isdigit — Verifica si un punto de código es un dígito

### Descripción

public static function IntlChar::isdigit(int|string `$codepoint`): ?bool

Determina si el punto de código especificado es un dígito.

`true` para los caracteres de categoría general "Nd" (dígitos decimales). A partir de Unicode 4, esto es lo mismo que probar el Type_Numeric de Decimal.

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` es un dígito, `false` en caso contrario. Devuelve `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::isdigit("A"));
    var_dump(IntlChar::isdigit("1"));
    var_dump(IntlChar::isdigit("\t"));
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(true)
    bool(false)

### Ver también

- IntlChar::isalpha() - Verifica si un punto de código es un carácter alfabético
- IntlChar::isalnum() - Verifica si un punto de código es un carácter alfanumérico
- IntlChar::isxdigit() - Verifica si un punto de código es un dígito hexadecimal
- ctype_digit() - Chequear posibles caracteres numéricos

# IntlChar::isgraph

(PHP 7, PHP 8)

IntlChar::isgraph — Verifica si un punto de código es un carácter gráfico

### Descripción

public static function IntlChar::isgraph(int|string `$codepoint`): ?bool

Determina si el punto de código especificado es un carácter "gráfico" (mostrable, excluyendo los espacios).

`true` para todos los caracteres excepto aquellos con las categorías generales "Cc" (códigos de control), "Cf" (controles de formato), "Cs" (sustitutos), "Cn" (no asignados) y "Z" (separadores).

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` es un carácter "gráfico", `false` en caso contrario. Devuelve `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::isgraph("A"));
    var_dump(IntlChar::isgraph("1"));
    var_dump(IntlChar::isgraph("\u{2603}"));
    var_dump(IntlChar::isgraph("\n"));
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(true)
    bool(true)
    bool(false)

### Ver también

- ctype_graph() - Chequear posibles caracteres imprimibles, con excepción de los espacios

# IntlChar::isIDIgnorable

(PHP 7, PHP 8)

IntlChar::isIDIgnorable — Verifica si un punto de código es un carácter ignorable

### Descripción

public static function IntlChar::isIDIgnorable(int|string `$codepoint`): ?bool

Determina si el carácter especificado debe ser considerado como un carácter ignorable en un identificador.

`true` para los caracteres de categoría general "Cf" (controles de formato) así como los controles ISO no espacios (U+0000..U+0008, U+000E..U+001B, U+007F..U+009F).

> Nota:

> Cabe señalar que Unicode simplemente recomienda ignorar Cf (controles de formato).

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` es ignorable en los identificadores, `false` en caso contrario. Devuelve `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::isIDIgnorable("A"));
    var_dump(IntlChar::isIDIgnorable(" "));
    var_dump(IntlChar::isIDIgnorable("\u{007F}"));
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(false)
    bool(true)

### Ver también

- IntlChar::isIDStart() - Verifica si un punto de código es permitido como primer carácter en un identificador
- IntlChar::isIDPart() - Verifica si un punto de código es permitido en un identificador
- `IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT`

# IntlChar::isIDPart

(PHP 7, PHP 8)

IntlChar::isIDPart — Verifica si un punto de código es permitido en un identificador

### Descripción

public static function IntlChar::isIDPart(int|string `$codepoint`): ?bool

Determina si el carácter especificado es permitido en un identificador.

`true` para los caracteres de categorías generales "L" (letras), "Nl" (números letras), "Nd" (números decimales), "Mc" y "Mn" (marcas de combinación), "Pc" (signos de puntuación de conexión), y u_isIDIgnorable(c).

> Nota:

> Esto es casi lo mismo que ID_Continue de Unicode (`IntlChar::PROPERTY_ID_CONTINUE`) excepto que Unicode recomienda ignorar Cf que es inferior a IntlChar::isIDIgnorable().

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` puede aparecer en un identificador, `false` de lo contrario. Devuelve `null` en caso de fallo.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::isIDPart("A"));
    var_dump(IntlChar::isIDPart("$"));
    var_dump(IntlChar::isIDPart("\n"));
    var_dump(IntlChar::isIDPart("\u{2603}"));
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(false)
    bool(false)
    bool(false)

### Ver también

- IntlChar::isIDIgnorable() - Verifica si un punto de código es un carácter ignorable
- IntlChar::isIDStart() - Verifica si un punto de código es permitido como primer carácter en un identificador
- `IntlChar::PROPERTY_ID_CONTINUE`

# IntlChar::isIDStart

(PHP 7, PHP 8)

IntlChar::isIDStart — Verifica si un punto de código es permitido como primer carácter en un identificador

### Descripción

public static function IntlChar::isIDStart(int|string `$codepoint`): ?bool

Determina si el carácter especificado es permitido como primer carácter en un identificador según Unicode (The Unicode Standard, Version 3.0, capítulo 5.16 Identificadores).

`true` para los caracteres de categoría general "L" (letras) y "Nl" (números letras).

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` puede comenzar un identificador, `false` en caso contrario. Devuelve `null` en caso de fallo.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::isIDStart("A"));
    var_dump(IntlChar::isIDStart("$"));
    var_dump(IntlChar::isIDStart("\n"));
    var_dump(IntlChar::isIDStart("\u{2603}"));
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(false)
    bool(false)
    bool(false)

### Ver también

- IntlChar::isalpha() - Verifica si un punto de código es un carácter alfabético
- IntlChar::isIDPart() - Verifica si un punto de código es permitido en un identificador
- `IntlChar::PROPERTY_ID_START`

# IntlChar::isISOControl

(PHP 7, PHP 8)

IntlChar::isISOControl — Verifica si un punto de código es un carácter de control ISO

### Descripción

public static function IntlChar::isISOControl(int|string `$codepoint`): ?bool

Determina si el punto de código especificado es un código de control ISO.

`true` para U+0000..U+001f y U+007f..U+009f (categoría general "Cc").

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` es un código de control ISO, `false` en caso contrario. Devuelve `null` en caso de fallo.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::isISOControl(" "));
    var_dump(IntlChar::isISOControl("\n"));
    var_dump(IntlChar::isISOControl("\u{200e}"));
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(true)
    bool(false)

### Ver también

- IntlChar::iscntrl() - Verifica si un punto de código es un carácter de control

# IntlChar::isJavaIDPart

(PHP 7, PHP 8)

IntlChar::isJavaIDPart — Verifica si un punto de código es permitido en un identificador Java

### Descripción

public static function IntlChar::isJavaIDPart(int|string `$codepoint`): ?bool

Determina si el carácter especificado es permitido en un identificador Java.

Además de IntlChar::isIDPart(), `true` para los caracteres de categoría general "Sc" (símbolos de moneda).

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` puede aparecer en un identificador Java, `false` de lo contrario. Devuelve `null` en caso de fallo.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::isJavaIDPart("A"));
    var_dump(IntlChar::isJavaIDPart("$"));
    var_dump(IntlChar::isJavaIDPart("\n"));
    var_dump(IntlChar::isJavaIDPart("\u{2603}"));
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### Ver también

- IntlChar::isIDIgnorable() - Verifica si un punto de código es un carácter ignorable
- IntlChar::isIDPart() - Verifica si un punto de código es permitido en un identificador
- IntlChar::isJavaIDStart() - Verifica si un punto de código es permitido como primer carácter en un identificador Java
- IntlChar::isalpha() - Verifica si un punto de código es un carácter alfabético
- IntlChar::isdigit() - Verifica si un punto de código es un dígito

# IntlChar::isJavaIDStart

(PHP 7, PHP 8)

IntlChar::isJavaIDStart — Verifica si un punto de código es permitido como primer carácter en un identificador Java

### Descripción

public static function IntlChar::isJavaIDStart(int|string `$codepoint`): ?bool

Determina si el carácter especificado es permitido como primer carácter en un identificador Java.

Además de IntlChar::isIDStart(), `true` para los caracteres de categoría general "Sc" (símbolos de moneda) y "Pc" (signos de puntuación de conexión).

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` puede comenzar un identificador Java, `false` de lo contrario. Devuelve `null` en caso de fallo.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::isJavaIDStart("A"));
    var_dump(IntlChar::isJavaIDStart("$"));
    var_dump(IntlChar::isJavaIDStart("\n"));
    var_dump(IntlChar::isJavaIDStart("\u{2603}"));
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### Ver también

- IntlChar::isIDStart() - Verifica si un punto de código es permitido como primer carácter en un identificador
- IntlChar::isJavaIDPart() - Verifica si un punto de código es permitido en un identificador Java
- IntlChar::isalpha() - Verifica si un punto de código es un carácter alfabético

# IntlChar::isJavaSpaceChar

(PHP 7, PHP 8)

IntlChar::isJavaSpaceChar — Verifica si un punto de código es un carácter de espacio según Java

### Descripción

public static function IntlChar::isJavaSpaceChar(int|string `$codepoint`): ?bool

Determina si el punto de código especificado es un carácter de espacio según Java.

`true` para los caracteres de categoría general "Z" (separadores), lo que no incluye los códigos de control (por ejemplo, TAB o Line Feed).

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` es un carácter de espacio según Java, `false` en caso contrario. Devuelve `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::isJavaSpaceChar("A"));
    var_dump(IntlChar::isJavaSpaceChar(" "));
    var_dump(IntlChar::isJavaSpaceChar("\n"));
    var_dump(IntlChar::isJavaSpaceChar("\t"));
    var_dump(IntlChar::isJavaSpaceChar("\u{00A0}"));
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(true)
    bool(false)
    bool(false)
    bool(true)

### Ver también

- IntlChar::isspace() - Verifica si un punto de código es un carácter de espacio
- IntlChar::isWhitespace() - Verifica si un punto de código es un carácter de espacio según ICU
- IntlChar::isUWhiteSpace() - Verifica si un punto de código tiene la propiedad Unicode White_Space

# IntlChar::islower

(PHP 7, PHP 8)

IntlChar::islower — Verifica si un punto de código es una letra minúscula

### Descripción

public static function IntlChar::islower(int|string `$codepoint`): ?bool

Determina si el punto de código especificado tiene la categoría general "Ll" (letra minúscula).

> Nota:

> Esto no incluye algunos caracteres que también son minúsculas pero tienen un valor de categoría general diferente. Para incluirlos, utilice IntlChar::isULowercase().

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` es una letra minúscula, `false` en caso contrario. Devuelve `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::islower("A"));
    var_dump(IntlChar::islower("a"));
    var_dump(IntlChar::islower("Φ"));
    var_dump(IntlChar::islower("φ"));
    var_dump(IntlChar::islower("1"));
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(true)
    bool(false)
    bool(true)
    bool(false)

### Ver también

- IntlChar::isupper() - Verifica si un punto de código tiene la categoría general "Lu" (letra mayúscula)
- IntlChar::istitle() - Verifica si un punto de código es una letra en título
- IntlChar::tolower() - Convierte un carácter Unicode a minúscula
- IntlChar::toupper() - Convierte un carácter Unicode a mayúscula
- `IntlChar::PROPERTY_LOWERCASE`
- ctype_lower() - Chequear posibles caracteres en minúscula

# IntlChar::isMirrored

(PHP 7, PHP 8)

IntlChar::isMirrored — Verifica si un punto de código tiene la propiedad Bidi_Mirrored

### Descripción

public static function IntlChar::isMirrored(int|string `$codepoint`): ?bool

Determina si el punto de código tiene la propiedad Bidi_Mirrored.

Esta propiedad está definida para los caracteres que se utilizan comúnmente en contextos de derecha a izquierda y que deben mostrarse con un glifo "espejo".

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` tiene la propiedad Bidi_Mirrored, `false` en caso contrario. Devuelve `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::isMirrored("A"));
    var_dump(IntlChar::isMirrored("<"));
    var_dump(IntlChar::isMirrored("("));
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(true)
    bool(true)

### Ver también

- IntlChar::charMirror() - Devuelve el carácter "imagen-espejo" para un punto de código
- `IntlChar::PROPERTY_BIDI_MIRRORED`

# IntlChar::isprint

(PHP 7, PHP 8)

IntlChar::isprint — Verifica si un punto de código es un carácter imprimible

### Descripción

public static function IntlChar::isprint(int|string `$codepoint`): ?bool

Determina si el punto de código especificado es un carácter imprimible.

`true` para las categorías generales distintas de "C" (controles).

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` es un carácter imprimible, `false` en caso contrario. Devuelve `null` en caso de fallo.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::isprint("A"));
    var_dump(IntlChar::isprint(" "));
    var_dump(IntlChar::isprint("\n"));
    var_dump(IntlChar::isprint("\u{200e}"));
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### Ver también

- IntlChar::iscntrl() - Verifica si un punto de código es un carácter de control
- `IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT`
- ctype_print() - Chequear posibles caracteres imprimibles

# IntlChar::ispunct

(PHP 7, PHP 8)

IntlChar::ispunct — Verifica si un punto de código es un carácter de puntuación

### Descripción

public static function IntlChar::ispunct(int|string `$codepoint`): ?bool

Determina si el punto de código especificado es un carácter de puntuación.

`true` para los caracteres de categoría general "P" (puntuación).

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` es un carácter de puntuación, `false` en caso contrario. Devuelve `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::ispunct("."));
    var_dump(IntlChar::ispunct(","));
    var_dump(IntlChar::ispunct("\n"));
    var_dump(IntlChar::ispunct("$"));

El ejemplo anterior mostrará:

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### Ver también

- ctype_punct() - Chequear posibles caracteres imprimibles que no son ni espacios en blanco ni caracteres alfanuméricos

# IntlChar::isspace

(PHP 7, PHP 8)

IntlChar::isspace — Verifica si un punto de código es un carácter de espacio

### Descripción

public static function IntlChar::isspace(int|string `$codepoint`): ?bool

Determina si el punto de código especificado es un carácter de espacio.

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` es un carácter de espacio, `false` en caso contrario. Devuelve `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::isspace("A"));
    var_dump(IntlChar::isspace(" "));
    var_dump(IntlChar::isspace("\n"));
    var_dump(IntlChar::isspace("\t"));
    var_dump(IntlChar::isspace("\u{00A0}"));
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    bool(true)

### Ver también

- IntlChar::isJavaSpaceChar() - Verifica si un punto de código es un carácter de espacio según Java
- IntlChar::isWhitespace() - Verifica si un punto de código es un carácter de espacio según ICU
- IntlChar::isUWhiteSpace() - Verifica si un punto de código tiene la propiedad Unicode White_Space
- ctype_space() - Chequear posibles caracteres de espacio en blanco

# IntlChar::istitle

(PHP 7, PHP 8)

IntlChar::istitle — Verifica si un punto de código es una letra en título

### Descripción

public static function IntlChar::istitle(int|string `$codepoint`): ?bool

Determina si el punto de código especificado es una letra en título.

`true` para la categoría general "Lt" (letra en título).

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` es una letra en título, `false` en caso contrario. Devuelve `null` en caso de fallo.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    // Letra latina en mayúscula Dz con caron U+01C4
    var_dump(IntlChar::istitle("Ǆ"));
    // Letra latina en mayúscula D con letra pequeña Z con caron U+01C5
    var_dump(IntlChar::istitle("ǅ"));
    // Letra latina en minúscula Dz con caron U+01C6
    var_dump(IntlChar::istitle("ǆ"));

    // Letra griega en mayúscula Alpha con prosgegrammeni U+1FBC
    var_dump(IntlChar::istitle("ᾼ"));
    // Letra griega en minúscula Alpha con prosgegrammeni U+1FBE
    var_dump(IntlChar::istitle("ᾳ"));
    // Letra griega en mayúscula Alpha U+0391
    var_dump(IntlChar::istitle("Α"));
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(true)
    bool(false)
    bool(true)
    bool(false)
    bool(false)

### Ver también

- IntlChar::isupper() - Verifica si un punto de código tiene la categoría general "Lu" (letra mayúscula)
- IntlChar::islower() - Verifica si un punto de código es una letra minúscula
- IntlChar::totitle() - Convierte un carácter Unicode en letra de título

# IntlChar::isUAlphabetic

(PHP 7, PHP 8)

IntlChar::isUAlphabetic — Verifica si un punto de código tiene la propiedad Unicode Alphabetic

### Descripción

public static function IntlChar::isUAlphabetic(int|string `$codepoint`): ?bool

Verifica si un punto de código tiene la propiedad Unicode Alphabetic.

Esto es idéntico a `IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_ALPHABETIC)`

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` tiene la propiedad Unicode Alphabetic, `false` en caso contrario. Devuelve `null` en caso de fallo.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::isUAlphabetic("A"));
    var_dump(IntlChar::isUAlphabetic("1"));
    var_dump(IntlChar::isUAlphabetic("\u{2603}"));
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(false)
    bool(false)

### Ver también

- IntlChar::isalpha() - Verifica si un punto de código es un carácter alfabético
- IntlChar::hasBinaryProperty() - Verifica una propiedad Unicode binaria para un punto de código
- `IntlChar::PROPERTY_ALPHABETIC`

# IntlChar::isULowercase

(PHP 7, PHP 8)

IntlChar::isULowercase — Verifica si un punto de código tiene la propiedad Unicode Lowercase

### Descripción

public static function IntlChar::isULowercase(int|string `$codepoint`): ?bool

Verifica si un punto de código tiene la propiedad Unicode Lowercase.

Esto es idéntico a `IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_LOWERCASE)`

> Nota:

> Esto es diferente de IntlChar::islower() y devolverá `true` para más caracteres.

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` tiene la propiedad Unicode Lowercase, `false` en caso contrario. Devuelve `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::isULowercase("A"));
    var_dump(IntlChar::isULowercase("a"));
    var_dump(IntlChar::isULowercase("Φ"));
    var_dump(IntlChar::isULowercase("φ"));
    var_dump(IntlChar::isULowercase("1"));
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(true)
    bool(false)
    bool(true)
    bool(false)

### Ver también

- IntlChar::islower() - Verifica si un punto de código es una letra minúscula
- IntlChar::hasBinaryProperty() - Verifica una propiedad Unicode binaria para un punto de código
- `IntlChar::PROPERTY_LOWERCASE`

# IntlChar::isupper

(PHP 7, PHP 8)

IntlChar::isupper — Verifica si un punto de código tiene la categoría general "Lu" (letra mayúscula)

### Descripción

public static function IntlChar::isupper(int|string `$codepoint`): ?bool

Determina si el punto de código especificado tiene la categoría general "Lu" (letra mayúscula).

> Nota:

> Esto no incluye algunos caracteres que también son mayúsculas pero tienen un valor de categoría general diferente. Para incluirlos, utilice IntlChar::isUUppercase().

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` es una letra mayúscula, `false` en caso contrario. Devuelve `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::isupper("A"));
    var_dump(IntlChar::isupper("a"));
    var_dump(IntlChar::isupper("Φ"));
    var_dump(IntlChar::isupper("φ"));
    var_dump(IntlChar::isupper("1"));
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(false)
    bool(true)
    bool(false)
    bool(false)

### Ver también

- IntlChar::islower() - Verifica si un punto de código es una letra minúscula
- IntlChar::istitle() - Verifica si un punto de código es una letra en título
- IntlChar::tolower() - Convierte un carácter Unicode a minúscula
- IntlChar::toupper() - Convierte un carácter Unicode a mayúscula
- `IntlChar::PROPERTY_UPPERCASE`
- ctype_upper() - Chequear posibles caracteres en mayúscula

# IntlChar::isUUppercase

(PHP 7, PHP 8)

IntlChar::isUUppercase — Verifica si un punto de código tiene la propiedad Unicode Uppercase

### Descripción

public static function IntlChar::isUUppercase(int|string `$codepoint`): ?bool

Verifica si un punto de código tiene la propiedad Unicode Uppercase.

Esto es idéntico a `IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_UPPERCASE)`

> Nota:

> Esto es diferente de IntlChar::isupper() y devolverá `true` para más caracteres.

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` tiene la propiedad Unicode Uppercase, `false` en caso contrario. Devuelve `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::isUUppercase("A"));
    var_dump(IntlChar::isUUppercase("a"));
    var_dump(IntlChar::isUUppercase("Φ"));
    var_dump(IntlChar::isUUppercase("φ"));
    var_dump(IntlChar::isUUppercase("1"));
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(false)
    bool(true)
    bool(false)
    bool(false)

### Ver también

- IntlChar::isupper() - Verifica si un punto de código tiene la categoría general "Lu" (letra mayúscula)
- IntlChar::hasBinaryProperty() - Verifica una propiedad Unicode binaria para un punto de código
- `IntlChar::PROPERTY_UPPERCASE`

# IntlChar::isUWhiteSpace

(PHP 7, PHP 8)

IntlChar::isUWhiteSpace — Verifica si un punto de código tiene la propiedad Unicode White_Space

### Descripción

public static function IntlChar::isUWhiteSpace(int|string `$codepoint`): ?bool

Verifica si un punto de código tiene la propiedad Unicode White_Space.

Esto es idéntico a `IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_WHITE_SPACE)`

> Nota:

> Esto es diferente de IntlChar::isspace() y de IntlChar::isWhitespace().

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` tiene la propiedad Unicode White_Space, `false` en caso contrario. Devuelve `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::isUWhiteSpace("A"));
    var_dump(IntlChar::isUWhiteSpace(" "));
    var_dump(IntlChar::isUWhiteSpace("\n"));
    var_dump(IntlChar::isUWhiteSpace("\t"));
    var_dump(IntlChar::isUWhiteSpace("\u{00A0}"));
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    bool(true)

### Ver también

- IntlChar::isspace() - Verifica si un punto de código es un carácter de espacio
- IntlChar::isWhitespace() - Verifica si un punto de código es un carácter de espacio según ICU
- IntlChar::isJavaSpaceChar() - Verifica si un punto de código es un carácter de espacio según Java
- IntlChar::hasBinaryProperty() - Verifica una propiedad Unicode binaria para un punto de código
- `IntlChar::PROPERTY_WHITE_SPACE`

# IntlChar::isWhitespace

(PHP 7, PHP 8)

IntlChar::isWhitespace — Verifica si un punto de código es un carácter de espacio según ICU

### Descripción

public static function IntlChar::isWhitespace(int|string `$codepoint`): ?bool

Determina si el punto de código especificado es un carácter de espacio según ICU.

Un carácter se considera un carácter de espacio ICU si y solo si cumple uno de los siguientes criterios:

- Si es un carácter de espacio Unicode (categorías "Z" = "Zs" o "Zl" o "Zp"), pero no es un espacio insustituible (U+00A0 NBSP o U+2007 Figure Space o U+202F Narrow NBSP).
- Si es U+0009 HORIZONTAL TABULATION.
- Si es U+000A LINE FEED.
- Si es U+000B VERTICAL TABULATION.
- Si es U+000C FORM FEED.
- Si es U+000D CARRIAGE RETURN.
- Si es U+001C FILE SEPARATOR.
- Si es U+001D GROUP SEPARATOR.
- Si es U+001E RECORD SEPARATOR.
- Si es U+001F UNIT SEPARATOR.

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` es un carácter de espacio según ICU, `false` en caso contrario. Devuelve `null` en caso de fallo.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::iswhitespace("A"));
    var_dump(IntlChar::iswhitespace(" "));
    var_dump(IntlChar::iswhitespace("\n"));
    var_dump(IntlChar::iswhitespace("\t"));
    var_dump(IntlChar::iswhitespace("\u{00A0}"));
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    bool(false)

### Ver también

- IntlChar::isspace() - Verifica si un punto de código es un carácter de espacio
- IntlChar::isJavaSpaceChar() - Verifica si un punto de código es un carácter de espacio según Java
- IntlChar::isUWhiteSpace() - Verifica si un punto de código tiene la propiedad Unicode White_Space

# IntlChar::isxdigit

(PHP 7, PHP 8)

IntlChar::isxdigit — Verifica si un punto de código es un dígito hexadecimal

### Descripción

public static function IntlChar::isxdigit(int|string `$codepoint`): ?bool

Determina si el punto de código especificado es un dígito hexadecimal.

`true` para los caracteres de categoría general "Nd" (dígitos decimales) así como las letras latinas a-f y A-F en ASCII y ASCII completo. (Es decir, para las letras con puntos de código 0041..0046, 0061..0066, FF21..FF26, FF41..FF46.)

Esto es equivalente a `IntlChar::digit($codepoint, 16) >= 0`.

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve `true` si `codepoint` es un dígito hexadecimal, `false` en caso contrario. Devuelve `null` en caso de error.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::isxdigit("A"));
    var_dump(IntlChar::isxdigit("1"));
    var_dump(IntlChar::isxdigit("\u{2603}"));
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(true)
    bool(false)

### Notas

> Nota:

> Para restringir la definición de dígitos hexadecimales únicamente a los caracteres ASCII, utilice:

>     <?php
>     $isASCIIHexadecimal = IntlChar::ord($codepoint) <= 0x7F && IntlChar::isxdigit($codepoint);
>     ?>

### Ver también

- IntlChar::isdigit() - Verifica si un punto de código es un dígito
- ctype_xdigit() - Chequear posibles caracteres que representen un dígito hexadecimal

# IntlChar::ord

(PHP 7, PHP 8)

IntlChar::ord — Devuelve el valor del punto de código Unicode de un carácter

### Descripción

public static function IntlChar::ord(int|string `$character`): ?int

Devuelve el valor del punto de código Unicode del carácter dado.

Esta función complementa IntlChar::chr().

### Parámetros

`character`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve el valor del punto de código Unicode en forma de entero.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::ord("A"));
    var_dump(IntlChar::ord(" "));
    var_dump(IntlChar::ord("\u{2603}"));
    ?>

El ejemplo anterior mostrará:

    int(65)
    int(32)
    int(9731)

### Ver también

- IntlChar::chr() - Devuelve el carácter Unicode por valor de punto de código
- mb_ord() - Obtiene el punto de código Unicode de un carácter
- ord() - Convierte el primer byte de un string en un valor entre 0 y 255

# IntlChar::tolower

(PHP 7, PHP 8)

IntlChar::tolower — Convierte un carácter Unicode a minúscula

### Descripción

public static function IntlChar::tolower(int|string `$codepoint`): int|string|null

El carácter dado se mapea a su equivalente en minúscula. Si el carácter no tiene equivalente en minúscula, se devuelve el carácter original.

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve el Simple_Lowercase_Mapping del punto de código, si está disponible; de lo contrario, el punto de código mismo. Devuelve `null` en caso de error.

El tipo de retorno es int a menos que el punto de código haya sido pasado como un string UTF-8, en cuyo caso se devuelve un string. Devuelve `null` en caso de fallo.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::tolower("A"));
    var_dump(IntlChar::tolower("a"));
    var_dump(IntlChar::tolower("Φ"));
    var_dump(IntlChar::tolower("φ"));
    var_dump(IntlChar::tolower("1"));
    var_dump(IntlChar::tolower(ord("A")));
    var_dump(IntlChar::tolower(ord("a")));
    ?>

El ejemplo anterior mostrará:

    string(1) "a"
    string(1) "a"
    string(2) "φ"
    string(2) "φ"
    string(1) "1"
    int(97)
    int(97)

### Ver también

- IntlChar::totitle() - Convierte un carácter Unicode en letra de título
- IntlChar::toupper() - Convierte un carácter Unicode a mayúscula
- mb_strtolower() - Convierte todos los caracteres a minúsculas

# IntlChar::totitle

(PHP 7, PHP 8)

IntlChar::totitle — Convierte un carácter Unicode en letra de título

### Descripción

public static function IntlChar::totitle(int|string `$codepoint`): int|string|null

El carácter dado se mapea a su equivalente en letra de título. Si el carácter no tiene equivalente en letra de título, se devuelve el carácter original.

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve el Simple_Titlecase_Mapping del punto de código, si está disponible; de lo contrario, devuelve el punto de código mismo. Devuelve `null` en caso de error.

El tipo de retorno es int a menos que el punto de código haya sido pasado como un string UTF-8, en cuyo caso se devuelve un string. Devuelve `null` en caso de fallo.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::totitle("Ǆ"));
    var_dump(IntlChar::totitle("ǆ"));
    var_dump(IntlChar::totitle("Φ"));
    var_dump(IntlChar::totitle("φ"));
    var_dump(IntlChar::totitle("1"));
    var_dump(IntlChar::totitle("ᾳ"));
    var_dump(IntlChar::totitle(ord("A")));
    ?>

El ejemplo anterior mostrará:

    string(1) "ǅ"
    string(1) "ǅ"
    string(2) "Φ"
    string(2) "φ"
    string(1) "1"
    string(1) "ᾼ"
    int(65)

### Ver también

- IntlChar::tolower() - Convierte un carácter Unicode a minúscula
- IntlChar::toupper() - Convierte un carácter Unicode a mayúscula
- IntlChar::istitle() - Verifica si un punto de código es una letra en título
- mb_convert_case() - Realiza una conversión a mayúsculas/minúsculas de un string

# IntlChar::toupper

(PHP 7, PHP 8)

IntlChar::toupper — Convierte un carácter Unicode a mayúscula

### Descripción

public static function IntlChar::toupper(int|string `$codepoint`): int|string|null

El carácter dado se mapea a su equivalente en mayúscula. Si el carácter no tiene equivalente en mayúscula, se devuelve el carácter original.

### Parámetros

`codepoint`
  El valor int del punto de código (por ejemplo, `0x2603` para U+2603 SNOWMAN), o el carácter codificado como un string UTF-8 (por ejemplo, `"\u{2603}"`)

### Valores devueltos

Devuelve el Simple_Uppercase_Mapping del punto de código, si está disponible; de lo contrario, el punto de código mismo.

El tipo de retorno es int a menos que el punto de código haya sido pasado como un string UTF-8, en cuyo caso se devuelve un string. Devuelve `null` en caso de fallo.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    var_dump(IntlChar::toupper("A"));
    var_dump(IntlChar::toupper("a"));
    var_dump(IntlChar::toupper("Φ"));
    var_dump(IntlChar::toupper("φ"));
    var_dump(IntlChar::toupper("1"));
    var_dump(IntlChar::toupper(ord("A")));
    var_dump(IntlChar::toupper(ord("a")));
    ?>

El ejemplo anterior mostrará:

    string(1) "A"
    string(1) "A"
    string(2) "Φ"
    string(2) "Φ"
    string(1) "1"
    int(65)
    int(65)

### Ver también

- IntlChar::tolower() - Convierte un carácter Unicode a minúscula
- IntlChar::totitle() - Convierte un carácter Unicode en letra de título
- mb_strtoupper() - Convierte todos los caracteres a mayúsculas

## Tabla de contenidos

- IntlChar::charAge — Devuelve la "edad" del punto de código
- IntlChar::charDigitValue — Devuelve el valor decimal del dígito decimal
- IntlChar::charDirection — Devuelve el valor de la categoría bidireccional para un punto de código
- IntlChar::charFromName — Encuentra un carácter Unicode por su nombre y devuelve su valor de punto de código
- IntlChar::charMirror — Devuelve el carácter "imagen-espejo" para un punto de código
- IntlChar::charName — Devuelve el nombre de un carácter Unicode
- IntlChar::charType — Devuelve el valor de la categoría general para un punto de código
- IntlChar::chr — Devuelve el carácter Unicode por valor de punto de código
- IntlChar::digit — Devuelve el dígito decimal de un punto de código para una base de numeración dada
- IntlChar::enumCharNames — Enumera todos los caracteres Unicode asignados en un rango
- IntlChar::enumCharTypes — Enumera todos los puntos de código con sus categorías generales Unicode
- IntlChar::foldCase — Realiza el plegado de mayúsculas/minúsculas sobre un punto de código
- IntlChar::forDigit — Devuelve la representación de carácter para un dígito dado y una base de numeración
- IntlChar::getBidiPairedBracket — Devuelve el carácter de paréntesis emparejado para un punto de código
- IntlChar::getBlockCode — Devuelve el bloque de asignación Unicode que contiene un punto de código
- IntlChar::getCombiningClass — Devuelve la clase de combinación de un punto de código
- IntlChar::getFC_NFKC_Closure — Devuelve la propiedad FC_NFKC_Closure para un punto de código
- IntlChar::getIntPropertyMaxValue — Devuelve el valor máximo para una propiedad Unicode
- IntlChar::getIntPropertyMinValue — Devuelve el valor mínimo para una propiedad Unicode
- IntlChar::getIntPropertyValue — Devuelve el valor de una propiedad Unicode para un punto de código
- IntlChar::getNumericValue — Devuelve el valor numérico de un punto de código Unicode
- IntlChar::getPropertyEnum — Devuelve el valor de la constante de propiedad para un nombre de propiedad dado
- IntlChar::getPropertyName — Devuelve el nombre Unicode de una propiedad
- IntlChar::getPropertyValueEnum — Devuelve el valor de propiedad para un nombre de valor dado
- IntlChar::getPropertyValueName — Devuelve el nombre Unicode para un valor de propiedad
- IntlChar::getUnicodeVersion — Devuelve la versión Unicode
- IntlChar::hasBinaryProperty — Verifica una propiedad Unicode binaria para un punto de código
- IntlChar::isalnum — Verifica si un punto de código es un carácter alfanumérico
- IntlChar::isalpha — Verifica si un punto de código es un carácter alfabético
- IntlChar::isbase — Verifica si un punto de código es un carácter de base
- IntlChar::isblank — Verifica si un punto de código es un carácter "blanco" o "espacio horizontal"
- IntlChar::iscntrl — Verifica si un punto de código es un carácter de control
- IntlChar::isdefined — Verifica si un punto de código está definido
- IntlChar::isdigit — Verifica si un punto de código es un dígito
- IntlChar::isgraph — Verifica si un punto de código es un carácter gráfico
- IntlChar::isIDIgnorable — Verifica si un punto de código es un carácter ignorable
- IntlChar::isIDPart — Verifica si un punto de código es permitido en un identificador
- IntlChar::isIDStart — Verifica si un punto de código es permitido como primer carácter en un identificador
- IntlChar::isISOControl — Verifica si un punto de código es un carácter de control ISO
- IntlChar::isJavaIDPart — Verifica si un punto de código es permitido en un identificador Java
- IntlChar::isJavaIDStart — Verifica si un punto de código es permitido como primer carácter en un identificador Java
- IntlChar::isJavaSpaceChar — Verifica si un punto de código es un carácter de espacio según Java
- IntlChar::islower — Verifica si un punto de código es una letra minúscula
- IntlChar::isMirrored — Verifica si un punto de código tiene la propiedad Bidi_Mirrored
- IntlChar::isprint — Verifica si un punto de código es un carácter imprimible
- IntlChar::ispunct — Verifica si un punto de código es un carácter de puntuación
- IntlChar::isspace — Verifica si un punto de código es un carácter de espacio
- IntlChar::istitle — Verifica si un punto de código es una letra en título
- IntlChar::isUAlphabetic — Verifica si un punto de código tiene la propiedad Unicode Alphabetic
- IntlChar::isULowercase — Verifica si un punto de código tiene la propiedad Unicode Lowercase
- IntlChar::isupper — Verifica si un punto de código tiene la categoría general "Lu" (letra mayúscula)
- IntlChar::isUUppercase — Verifica si un punto de código tiene la propiedad Unicode Uppercase
- IntlChar::isUWhiteSpace — Verifica si un punto de código tiene la propiedad Unicode White_Space
- IntlChar::isWhitespace — Verifica si un punto de código es un carácter de espacio según ICU
- IntlChar::isxdigit — Verifica si un punto de código es un dígito hexadecimal
- IntlChar::ord — Devuelve el valor del punto de código Unicode de un carácter
- IntlChar::tolower — Convierte un carácter Unicode a minúscula
- IntlChar::totitle — Convierte un carácter Unicode en letra de título
- IntlChar::toupper — Convierte un carácter Unicode a mayúscula

# La clase de excepción para los errores intl

(PHP 5 > 5.5.0, PHP 7, PHP 8, PECL intl > 3.0.0a1)

## Introducción

Esta clase se utiliza para generar excepciones cuando ocurren errores dentro de las funciones intl. Tales excepciones solo se generan cuando intl.use_exceptions está activado.

## Sinopsis de la Clase

class IntlException extends Exception {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos heredados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La clase IntlIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introducción

Esta clase representa objetos iteradores a través de la extensión intl cada vez que el iterador no puede ser identificado con otro objeto proporcionado por la extensión. El objeto de iterador distinto utilizado en interno por la `foreach` solo puede ser obtenido (en la parte pertinente aquí) desde objetos, por lo que los objetos de esta clase sirven para proporcionar el gancho mediante el cual este objeto interno puede ser obtenido. Por conveniencia, esta clase también implementa la interfaz Iterator, permitiendo que la colección de valores sea recorridos utilizando los métodos definidos en esta interfaz. Estos métodos y los objetos de iterador internos proporcionados a `foreach` son soportados por el mismo estado (por ejemplo, la posición del iterador y su valor actual).

Las subclases pueden proporcionar una funcionalidad más rica.

## Sinopsis de la Clase

class IntlIterator implements Iterator {
/* Métodos */
public function current(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function valid(): bool
}

# IntlIterator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::current — Obtiene el elemento actual

### Descripción

public function IntlIterator::current(): mixed

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlIterator::key

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::key — Obtiene la clave actual

### Descripción

public function IntlIterator::key(): mixed

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlIterator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::next — Se desplaza al elemento siguiente

### Descripción

public function IntlIterator::next(): void

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlIterator::rewind

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::rewind — Reubica el iterador en el primer elemento

### Descripción

public function IntlIterator::rewind(): void

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# IntlIterator::valid

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::valid — Verifica si la posición actual es válida

### Descripción

public function IntlIterator::valid(): bool

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

## Tabla de contenidos

- IntlIterator::current — Obtiene el elemento actual
- IntlIterator::key — Obtiene la clave actual
- IntlIterator::next — Se desplaza al elemento siguiente
- IntlIterator::rewind — Reubica el iterador en el primer elemento
- IntlIterator::valid — Verifica si la posición actual es válida

# Funciones de intl

# intl_error_name

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_error_name — Lee el nombre simbólico de un código de error dado

### Descripción

function intl_error_name(int `$errorCode`): string

Devuelve el nombre del código de error ICU.

### Parámetros

`errorCode`

  El código de error ICU.

### Valores devueltos

La cadena devuelta será la del nombre de la constante equivalente.

### Ejemplos

Ejemplo #1 Ejemplo con intl_error_name()

    <?php
    $coll     = collator_create( 'en_RU' );
    $err_code = collator_get_error_code( $coll );

    printf( "El nombre simbólico de %d es %s\n.", $err_code, intl_error_name( $err_code ) );
    ?>

Resultado del ejemplo anterior es similar a:

    Symbolic name for -128 is U_USING_FALLBACK_WARNING.

### Ver también

- intl_is_failure() - Verifica si un código de error indica un fallo
- intl_get_error_code() - Lee el último código de error
- intl_get_error_message() - Lee la descripción del último error

# intl_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_get_error_code — Lee el último código de error

### Descripción

function intl_get_error_code(): int

Útil para gestionar los errores que ocurren en los métodos estáticos cuando no hay un objeto del cual obtener el mensaje de error.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El código de error devuelto por la última llamada a la API.

### Ejemplos

Ejemplo #1 Ejemplo con intl_get_error_code()

    <?php
    $coll = collator_create( '<bad_param>' );
    if( !$coll ) {
        handle_error( intl_get_error_code() );
    }
    ?>

### Ver también

- intl_is_failure() - Verifica si un código de error indica un fallo
- intl_error_name() - Lee el nombre simbólico de un código de error dado
- intl_get_error_message() - Lee la descripción del último error
- collator_get_error_code() - Lee el último error del collator
- numfmt_get_error_code() - Obtener el último código de error del formateador

# intl_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_get_error_message — Lee la descripción del último error

### Descripción

function intl_get_error_message(): string

Lee el mensaje de error de la última función de internacionalización llamada.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

La descripción del error que ocurrió durante la última llamada a la API.

### Ejemplos

Ejemplo #1 Ejemplo con intl_get_error_message()

    <?php
    if( Collator::getAvailableLocales() === false ) {
        show_error( intl_get_error_message() );
    }
    ?>

### Ver también

- intl_error_name() - Lee el nombre simbólico de un código de error dado
- intl_get_error_code() - Lee el último código de error
- intl_is_failure() - Verifica si un código de error indica un fallo
- collator_get_error_message() - Lee el último mensaje de error del collator
- numfmt_get_error_message() - Lee el último mensaje de error del formateador

# intl_is_failure

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_is_failure — Verifica si un código de error indica un fallo

### Descripción

function intl_is_failure(int `$errorCode`): bool

### Parámetros

`errorCode`

  un valor devuelto por una de las funciones intl_get_error_code(), collator_get_error_code().

### Valores devueltos

`true` si el código indica un fallo, y `false` en caso de éxito o advertencia.

### Ejemplos

Ejemplo #1 Ejemplo con intl_is_failure()

    <?php
    function check( $err_code )
    {
        var_export( intl_is_failure( $err_code ) );
        echo "\n";
    }

    check( U_ZERO_ERROR );
    check( U_USING_FALLBACK_WARNING );
    check( U_ILLEGAL_ARGUMENT_ERROR );
    ?>

Resultado del ejemplo anterior es similar a:

    false
    false
    true

### Ver también

- intl_get_error_code() - Lee el último código de error
- collator_get_error_code() - Lee el último error del collator
- Collator-getErrorCode()

## Tabla de contenidos

- intl_error_name — Lee el nombre simbólico de un código de error dado
- intl_get_error_code — Lee el último código de error
- intl_get_error_message — Lee la descripción del último error
- intl_is_failure — Verifica si un código de error indica un fallo

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
- Constantes predefinidas
- Ejemplos
  - Uso básico de esta extensión
- Collator — La clase Collator
  - Collator::asort — Ordena un array manteniendo la asociación de índices
  - Collator::compare — Comparar dos strings Unicode
  - Collator::__construct — Creación de un collator
  - Collator::create — Creación de un collator
  - Collator::getAttribute — Obtener el valor de un atributo de ordenación
  - Collator::getErrorCode — Lee el último error del collator
  - Collator::getErrorMessage — Lee el último mensaje de error del collator
  - Collator::getLocale — Lee el nombre de la configuración local de un collator
  - Collator::getSortKey — Obtiene la clave de ordenación para una cadena
  - Collator::getStrength — Obtener la fuerza de ordenación actual
  - Collator::setAttribute — Establece un atributo de ordenación
  - Collator::setStrength — Establecer la fuerza de la ordenación
  - Collator::sort — Ordena un array usando el comparador especificado
  - Collator::sortWithSortKeys — Ordenar un array usando el comparador especificado y claves de ordenación
- NumberFormatter — La clase NumberFormatter
  - NumberFormatter::create — Crea un formateador de números
  - NumberFormatter::format — Formatear un número
  - NumberFormatter::formatCurrency — Formatea un valor monetario
  - NumberFormatter::getAttribute — Lee un atributo
  - NumberFormatter::getErrorCode — Obtener el último código de error del formateador
  - NumberFormatter::getErrorMessage — Lee el último mensaje de error del formateador
  - NumberFormatter::getLocale — Lee la configuración local del formateador
  - NumberFormatter::getPattern — Lee el modelo del formateador
  - NumberFormatter::getSymbol — Lee el valor del símbolo
  - NumberFormatter::getTextAttribute — Lee un atributo textual
  - NumberFormatter::parse — Analiza un número
  - NumberFormatter::parseCurrency — Analiza un número monetario
  - NumberFormatter::setAttribute — Asigna un atributo al formateador
  - NumberFormatter::setPattern — Configura el patrón del formateador
  - NumberFormatter::setSymbol — Configura el símbolo del formateador
  - NumberFormatter::setTextAttribute — Modifica un atributo de texto
- Locale — La clase Locale
  - Locale::acceptFromHttp — Determina la mejor configuración local a partir del encabezado HTTP "Accept-Language"
  - Locale::canonicalize — Canoniza la cadena que representa la configuración local
  - Locale::composeLocale — Retorna un identificador de configuración regional correcto
  - Locale::filterMatches — Verifica si el tag de idioma coincide con una configuración local
  - Locale::getAllVariants — Lista todas las variantes de una configuración local
  - Locale::getDefault — Lee el valor por defecto de una configuración local para la variable global 'default_locale'
  - Locale::getDisplayLanguage — Devuelve un nombre adecuado para mostrar un nombre de idioma
  - Locale::getDisplayName — Devuelve un nombre de visualización correcto para una configuración local
  - Locale::getDisplayRegion — Devuelve un nombre para la región de la configuración local
  - Locale::getDisplayScript — Devuelve el nombre del script de la configuración local
  - Locale::getDisplayVariant — Devuelve un nombre para la variante de la configuración local
  - Locale::getKeywords — Lee las palabras clave de la configuración local
  - Locale::getPrimaryLanguage — Lee el idioma principal de la configuración local
  - Locale::getRegion — Devuelve un código para la región de la configuración local
  - Locale::getScript — Devuelve un código para el script de la configuración local
  - Locale::isRightToLeft — Comprueba si una configuración regional usa un sistema de escritura de derecha a izquierda
  - Locale::lookup — Búsqueda en la lista de la mejor lengua
  - Locale::parseLocale — Devuelve los subelementos de la configuración regional
  - Locale::setDefault — Configura la configuración local por defecto
- Normalizer — La clase Normalizer
  - Normalizer::getRawDecomposition — Devuelve la propiedad Decomposition_Mapping para el punto de código UTF-8 dado
  - Normalizer::isNormalized — Comprueba si el string proporcionado ya está en el formato de normalización especificado
  - Normalizer::normalize — Normaliza una cadena en entrada
- MessageFormatter — La clase MessageFormatter
  - MessageFormatter::create — Construye un nuevo formateador de mensajes
  - MessageFormatter::format — Formatea un mensaje
  - MessageFormatter::formatMessage — Formatea rápidamente un mensaje
  - MessageFormatter::getErrorCode — Lee el último código de error de la última operación
  - MessageFormatter::getErrorMessage — Lee el mensaje de error de la última operación
  - MessageFormatter::getLocale — Lee la configuración local con la que el formateador fue creado
  - MessageFormatter::getPattern — Lee el modelo utilizado por el formateador de mensajes
  - MessageFormatter::parse — Analiza una cadena según el modelo
  - MessageFormatter::parseMessage — Analiza rápidamente una cadena
  - MessageFormatter::setPattern — Configura el patrón utilizado por el formateador
- IntlCalendar — La classe IntlCalendar
  - IntlCalendar::add — Añade una duración (con signo) a un campo
  - IntlCalendar::after — Verifica si el objeto tiempo actual está en el futuro respecto al objeto tiempo pasado
  - IntlCalendar::before — Verifica si el objeto tiempo está en el pasado en relación con el objeto proporcionado
  - IntlCalendar::clear — Vacía un campo o todos los campos
  - IntlCalendar::__construct — Constructor privado para la desactivación de la instanciación
  - IntlCalendar::createInstance — Crea un nuevo objeto IntlCalendar
  - IntlCalendar::equals — Verifica si dos objetos IntlCalendar son iguales
  - IntlCalendar::fieldDifference — Calcula la diferencia entre el tiempo dado y el tiempo del objeto
  - IntlCalendar::fromDateTime — Crea un IntlCalendar a partir de un objeto DateTime o string
  - IntlCalendar::get — Recupera el valor de una propiedad
  - IntlCalendar::getActualMaximum — El valor máximo para un campo, considerando el tiempo actual del objeto
  - IntlCalendar::getActualMinimum — El valor mínimo para un campo, considerando el tiempo actual del objeto
  - IntlCalendar::getAvailableLocales — Devuelve un array de locales para los cuales hay datos disponibles
  - IntlCalendar::getDayOfWeekType — Indica si un día es un día de la semana, un fin de semana o un día de transición entre ambos
  - IntlCalendar::getErrorCode — Devuelve el último código de error en el objeto
  - IntlCalendar::getErrorMessage — Devuelve el último mensaje de error en el objeto
  - IntlCalendar::getFirstDayOfWeek — Devuelve el primer día de la semana para la configuración local del calendario
  - IntlCalendar::getGreatestMinimum — Devuelve el valor mínimo local más grande para un campo
  - IntlCalendar::getKeywordValuesForLocale — Devuelve el conjunto de valores de palabras clave de configuración regional
  - IntlCalendar::getLeastMaximum — Obtiene el mínimo máximo local para un campo
  - IntlCalendar::getLocale — Devuelve la configuración local asociada al objeto
  - IntlCalendar::getMaximum — Obtiene el valor máximo global para un campo
  - IntlCalendar::getMinimalDaysInFirstWeek — Obtiene el número mínimo de días que la primera semana de un año o mes puede tener
  - IntlCalendar::getMinimum — Obtiene el valor mínimo global para un campo
  - IntlCalendar::getNow — Obtiene el número que representa la fecha actual
  - IntlCalendar::getRepeatedWallTimeOption — Obtiene el comportamiento para la gestión de las horas murales repetidas
  - IntlCalendar::getSkippedWallTimeOption — Obtiene el comportamiento para la gestión de las horas murales omitidas
  - IntlCalendar::getTime — Obtiene el tiempo actualmente representado por el objeto
  - IntlCalendar::getTimeZone — Recupera la zona horaria del objeto
  - IntlCalendar::getType — Obtiene el tipo de calendario
  - IntlCalendar::getWeekendTransition — Obtiene la hora del día en la que comienza o termina el fin de semana
  - IntlCalendar::inDaylightTime — Indica si el objeto está en horario de verano
  - IntlCalendar::isEquivalentTo — Indica si otro calendario es equivalente, pero para otro momento
  - IntlCalendar::isLenient — Indica si la interpretación de la fecha/hora está en modo tolerante
  - IntlCalendar::isSet — Indica si un campo está definido
  - IntlCalendar::isWeekend — Indica si una fecha/hora es un fin de semana
  - IntlCalendar::roll — Añade un valor a un campo sin reportarlo a los campos más significativos
  - IntlCalendar::set — Define un campo de tiempo o varios campos comunes a la vez
  - IntlCalendar::setDate — Establece un campo de fecha
  - IntlCalendar::setDateTime — Establece un campo de fecha y hora
  - IntlCalendar::setFirstDayOfWeek — Define el día de inicio de la semana
  - IntlCalendar::setLenient — Define si la interpretación de la fecha/hora es tolerante
  - IntlCalendar::setMinimalDaysInFirstWeek — Define el número mínimo de días que la primera semana de un año o mes puede tener
  - IntlCalendar::setRepeatedWallTimeOption — Define el comportamiento para la gestión de las horas murales repetidas durante las transiciones de cambio de huso horario negativo
  - IntlCalendar::setSkippedWallTimeOption — Define el comportamiento para la gestión de las horas murales saltadas durante las transiciones de desplazamiento horario positivo
  - IntlCalendar::setTime — Define el tiempo del calendario en milisegundos desde la época
  - IntlCalendar::setTimeZone — Define el huso horario utilizado por este calendario
  - IntlCalendar::toDateTime — Convierte un objeto IntlCalendar en un objeto DateTime
- IntlGregorianCalendar — La clase IntlGregorianCalendar
  - IntlGregorianCalendar::__construct — Crear la clase del calendario gregoriano
  - IntlGregorianCalendar::createFromDate — Crear una nueva instancia de IntlGregorianCalendar a partir de una fecha
  - IntlGregorianCalendar::createFromDateTime — Crear una nueva instancia de IntlGregorianCalendar a partir de una fecha y hora
  - IntlGregorianCalendar::getGregorianChange — Devuelve la fecha de cambio del calendario gregoriano
  - IntlGregorianCalendar::isLeapYear — Determina si el año dado es un año bisiesto
  - IntlGregorianCalendar::setGregorianChange — Establece la fecha de cambio del calendario gregoriano
- IntlTimeZone — La clase IntlTimeZone
  - IntlTimeZone::__construct — Constructor privado para evitar la instanciación directa
  - IntlTimeZone::countEquivalentIDs — Obtiene el número de IDs en el grupo de equivalencia que incluye el ID proporcionado
  - IntlTimeZone::createDefault — Crea una nueva copia del huso horario por defecto para este host
  - IntlTimeZone::createEnumeration — Obtiene una enumeración de IDs de zonas horarias asociadas con el país proporcionado
  - IntlTimeZone::createTimeZone — Crea un objeto de zona horaria para el ID proporcionado
  - IntlTimeZone::createTimeZoneIDEnumeration — Devuelve una enumeración de los identificadores de zona horaria del sistema con las condiciones de filtro dadas
  - IntlTimeZone::fromDateTimeZone — Crea un objeto de zona horaria a partir de DateTimeZone
  - IntlTimeZone::getCanonicalID — Obtiene el identificador del huso horario del sistema o el identificador normalizado del huso horario personalizado para el ID del huso horario proporcionado
  - IntlTimeZone::getDisplayName — Obtiene un nombre de zona horaria para su presentación al usuario
  - IntlTimeZone::getDSTSavings — Obtiene la duración a añadir a la hora local para recuperar la hora local estándar
  - IntlTimeZone::getEquivalentID — Obtiene un identificador de un grupo de equivalencia que incluye el identificador proporcionado
  - IntlTimeZone::getErrorCode — Recupera el código del último error ocurrido en el objeto
  - IntlTimeZone::getErrorMessage — Recupera el mensaje del último error ocurrido en el objeto
  - IntlTimeZone::getGMT — Crea un huso horario GMT (UTC)
  - IntlTimeZone::getIanaID — Traduce un identificador de zona horaria a su equivalente IANA
  - IntlTimeZone::getID — Obtiene el ID de una zona horaria
  - IntlTimeZone::getIDForWindowsID — Traduce una zona horaria de Windows a una zona horaria del sistema
  - IntlTimeZone::getOffset — Obtiene el desplazamiento bruto de la zona horaria y la posición GMT para un momento dado
  - IntlTimeZone::getRawOffset — Obtiene la posición bruta GMT (antes de considerar el horario de verano)
  - IntlTimeZone::getRegion — Devuelve el código de región asociado al identificador de zona horaria del sistema dado
  - IntlTimeZone::getTZDataVersion — Recupera la versión de la zona horaria actualmente utilizada por ICU
  - IntlTimeZone::getUnknown — Devuelve la zona horaria "desconocida"
  - IntlTimeZone::getWindowsID — Traduce una zona horaria del sistema a una zona horaria de Windows
  - IntlTimeZone::hasSameRules — Verifica si esta zona tiene las mismas reglas que otra
  - IntlTimeZone::toDateTimeZone — Convierte un objeto DateTimeZone
  - IntlTimeZone::useDaylightTime — Verifica si este huso horario utiliza la hora de verano
- IntlDateFormatter — La clase IntlDateFormatter
  - IntlDateFormatter::create — Crea un formateador de fecha
  - IntlDateFormatter::format — Formatea la fecha y la hora como string
  - IntlDateFormatter::formatObject — Formatea un objeto
  - IntlDateFormatter::getCalendar — Lee el calendario utilizado por el objeto IntlDateFormatter
  - IntlDateFormatter::getDateType — Lee el tipo de fecha utilizado por IntlDateFormatter
  - IntlDateFormatter::getErrorCode — Lee el código de error de la última operación
  - IntlDateFormatter::getErrorMessage — Lee el último mensaje de error
  - IntlDateFormatter::getLocale — Lee la configuración local utilizada por el formateador
  - IntlDateFormatter::getPattern — Lee el patrón utilizado por IntlDateFormatter
  - IntlDateFormatter::getTimeType — Lee el tipo de tiempo para IntlDateFormatter
  - IntlDateFormatter::getTimeZoneId — Lee el huso horario de IntlDateFormatter
  - IntlDateFormatter::getCalendarObject — Obtiene una copia del objeto formateador de calendario
  - IntlDateFormatter::getTimeZone — Obtiene el formateador del huso horario
  - IntlDateFormatter::isLenient — Devuelve la severidad utilizada para IntlDateFormatter
  - IntlDateFormatter::localtime — Analiza una cadena y la convierte en tiempo
  - IntlDateFormatter::parse — Analiza una cadena hacia un timestamp
  - IntlDateFormatter::parseToCalendar — Analiza una cadena hacia un timestamp, actualizando un calendario abierto
  - IntlDateFormatter::setCalendar — Define el tipo de calendario utilizado por el formateador
  - IntlDateFormatter::setLenient — Configura la flexibilidad del analizador
  - IntlDateFormatter::setPattern — Configura el patrón utilizado por IntlDateFormatter
  - IntlDateFormatter::setTimeZone — Define el formateador para el desplazamiento horario
- ResourceBundle — La clase ResourceBundle
  - ResourceBundle::count — Obtiene el número de elementos en el paquete
  - ResourceBundle::create — Crea un recurso que representa un haz
  - ResourceBundle::get — Recupera los datos desde el haz
  - ResourceBundle::getErrorCode — Recupera el último código de error del haz
  - ResourceBundle::getErrorMessage — Recupera el último mensaje de error desde el haz
  - ResourceBundle::getLocales — Obtiene las configuraciones locales admitidas
- Spoofchecker — La clase Spoofchecker
  - Spoofchecker::areConfusable — Verifica si los strings dados pueden ser confundidos
  - Spoofchecker::__construct — Constructor
  - Spoofchecker::isSuspicious — Verifica si un texto contiene caracteres sospechosos
  - Spoofchecker::setAllowedChars — Define el conjunto de caracteres permitidos al ejecutar las comprobaciones
  - Spoofchecker::setAllowedLocales — Locales a utilizar durante la verificación
  - Spoofchecker::setChecks — Especifica las verificaciones a realizar
  - Spoofchecker::setRestrictionLevel — Establece el nivel de restricción
- Transliterator — La clase Transliterator
  - Transliterator::__construct — Constructor privado para prohibir la instanciación
  - Transliterator::create — Crea un Transliterator
  - Transliterator::createFromRules — Crea un transliterador desde reglas
  - Transliterator::createInverse — Crea un transliterador inverso
  - Transliterator::getErrorCode — Obtiene el último código de error
  - Transliterator::getErrorMessage — Obtiene el último mensaje de error
  - Transliterator::listIDs — Obtiene los identificadores de este transliterador
  - Transliterator::transliterate — Translittera un string
- IntlBreakIterator — La clase IntlBreakIterator
  - IntlBreakIterator::__construct — Constructor privado para deshabilitar la instanciación
  - IntlBreakIterator::createCharacterInstance — Crea un iterador para los límites de las secuencias de caracteres combinados
  - IntlBreakIterator::createCodePointInstance — Crea un iterador para los límites de puntos de código
  - IntlBreakIterator::createLineInstance — Crea un iterador para las divisiones de líneas
  - IntlBreakIterator::createSentenceInstance — Crea un iterador para las divisiones de oración
  - IntlBreakIterator::createTitleInstance — Crea un iterador
  - IntlBreakIterator::createWordInstance — Crea un iterador para las divisiones de palabras
  - IntlBreakIterator::current — Obtiene el índice de la posición actual
  - IntlBreakIterator::first — Define la posición en el primer carácter del texto
  - IntlBreakIterator::following — Avance el iterador a la primera frontera siguiente a la posición especificada
  - IntlBreakIterator::getErrorCode — Recupera el código del último error ocurrido en el objeto
  - IntlBreakIterator::getErrorMessage — Recupera el mensaje del último error ocurrido en el objeto
  - IntlBreakIterator::getLocale — Obtiene la configuración local asociada con el objeto
  - IntlBreakIterator::getPartsIterator — Crea un iterador para navegar en los fragmentos entre los límites
  - IntlBreakIterator::getText — Recupera el texto analizado
  - IntlBreakIterator::isBoundary — Indica si una posición es una posición límite
  - IntlBreakIterator::last — Define la posición del iterador al índice después del último carácter
  - IntlBreakIterator::next — Avance el iterador a la siguiente frontera
  - IntlBreakIterator::preceding — Define la posición del iterador en el primer límite antes de la posición
  - IntlBreakIterator::previous — Define la posición del iterador en el límite inmediato anterior al actual
  - IntlBreakIterator::setText — Define el texto a analizar
- IntlRuleBasedBreakIterator — La clase IntlRuleBasedBreakIterator
  - IntlRuleBasedBreakIterator::__construct — Crea un iterador desde un conjunto de reglas
  - IntlRuleBasedBreakIterator::getBinaryRules — Obtiene la forma binaria de las reglas compiladas
  - IntlRuleBasedBreakIterator::getRules — Recupera el conjunto de reglas utilizado para crear este objeto
  - IntlRuleBasedBreakIterator::getRuleStatus — Obtiene el valor de estado más grande desde las reglas que determinan la posición actual de interrupción
  - IntlRuleBasedBreakIterator::getRuleStatusVec — Obtiene los valores de estado desde las reglas de interrupción que determinan la posición de interrupción actual
- IntlCodePointBreakIterator — La clase IntlCodePointBreakIterator
  - IntlCodePointBreakIterator::getLastCodePoint — Recupera el último punto de código después de avanzar o retroceder en el iterador
- IntlDatePatternGenerator — La clase IntlDatePatternGenerator
  - IntlDatePatternGenerator::create — Crear una nueva instancia de IntlDatePatternGenerator
  - IntlDatePatternGenerator::getBestPattern — Determina el formato de fecha/hora más adecuado
- IntlPartsIterator — La clase IntlPartsIterator
  - IntlPartsIterator::getBreakIterator — Obtiene IntlBreakIterator, preservando así esta parte del iterador
- UConverter — La clase UConverter
  - UConverter::__construct — Crea un objeto UConverter
  - UConverter::convert — Convierte una cadena de un juego de caracteres a otro juego de caracteres
  - UConverter::fromUCallback — Función de retrollamada "from"
  - UConverter::getAliases — Obtiene los alias del nombre proporcionado
  - UConverter::getAvailable — Obtiene el nombre canónico de los convertidores disponibles
  - UConverter::getDestinationEncoding — Obtiene la codificación de destino
  - UConverter::getDestinationType — Obtiene el tipo de destino del convertidor
  - UConverter::getErrorCode — Obtiene el código del último error ocurrido en el objeto
  - UConverter::getErrorMessage — Recupera el mensaje del último error ocurrido en el objeto
  - UConverter::getSourceEncoding — Obtiene la codificación de la fuente
  - UConverter::getSourceType — Obtiene el tipo de fuente del convertidor
  - UConverter::getStandards — Obtiene las normas asociadas a los nombres de conversión
  - UConverter::getSubstChars — Obtiene los caracteres de sustitución
  - UConverter::reasonText — Obtiene la cadena que representa la razón de la función de retorno
  - UConverter::setDestinationEncoding — Define el codificación de destino
  - UConverter::setSourceEncoding — Define el conjunto de caracteres de la fuente
  - UConverter::setSubstChars — Define los caracteres de sustitución
  - UConverter::toUCallback — Función de retrollamada "to"
  - UConverter::transcode — Convierte una cadena de un juego de caracteres a otro
- Funciones de Grapheme
  - grapheme_extract — Extrae un grupo de grafemas de una cadena UTF-8
  - grapheme_str_split — Divide una string en un array
  - grapheme_stripos — Encuentra la posición en grafema de la primera ocurrencia en una cadena, insensible a mayúsculas/minúsculas
  - grapheme_stristr — Devuelve la parte de una cadena a partir de una ocurrencia
  - grapheme_strlen — Lee la longitud de una cadena en número de grafemas
  - grapheme_strpos — Encuentra la posición del primer grafema
  - grapheme_strripos — Encuentra la posición del último grafema, insensible a mayúsculas/minúsculas
  - grapheme_strrpos — Encuentra la posición del último grafema
  - grapheme_strstr — Retorna la parte de una cadena a partir de una ocurrencia, insensible a mayúsculas/minúsculas
  - grapheme_substr — Devuelve una parte de un string
- Funciones de IDN
  - idn_to_ascii — Convierte un nombre de dominio al formato IDNA ASCII
  - idn_to_utf8 — Convierte el nombre de dominio IDNA ASCII a Unicode
- IntlChar
  - IntlChar::charAge — Devuelve la "edad" del punto de código
  - IntlChar::charDigitValue — Devuelve el valor decimal del dígito decimal
  - IntlChar::charDirection — Devuelve el valor de la categoría bidireccional para un punto de código
  - IntlChar::charFromName — Encuentra un carácter Unicode por su nombre y devuelve su valor de punto de código
  - IntlChar::charMirror — Devuelve el carácter "imagen-espejo" para un punto de código
  - IntlChar::charName — Devuelve el nombre de un carácter Unicode
  - IntlChar::charType — Devuelve el valor de la categoría general para un punto de código
  - IntlChar::chr — Devuelve el carácter Unicode por valor de punto de código
  - IntlChar::digit — Devuelve el dígito decimal de un punto de código para una base de numeración dada
  - IntlChar::enumCharNames — Enumera todos los caracteres Unicode asignados en un rango
  - IntlChar::enumCharTypes — Enumera todos los puntos de código con sus categorías generales Unicode
  - IntlChar::foldCase — Realiza el plegado de mayúsculas/minúsculas sobre un punto de código
  - IntlChar::forDigit — Devuelve la representación de carácter para un dígito dado y una base de numeración
  - IntlChar::getBidiPairedBracket — Devuelve el carácter de paréntesis emparejado para un punto de código
  - IntlChar::getBlockCode — Devuelve el bloque de asignación Unicode que contiene un punto de código
  - IntlChar::getCombiningClass — Devuelve la clase de combinación de un punto de código
  - IntlChar::getFC_NFKC_Closure — Devuelve la propiedad FC_NFKC_Closure para un punto de código
  - IntlChar::getIntPropertyMaxValue — Devuelve el valor máximo para una propiedad Unicode
  - IntlChar::getIntPropertyMinValue — Devuelve el valor mínimo para una propiedad Unicode
  - IntlChar::getIntPropertyValue — Devuelve el valor de una propiedad Unicode para un punto de código
  - IntlChar::getNumericValue — Devuelve el valor numérico de un punto de código Unicode
  - IntlChar::getPropertyEnum — Devuelve el valor de la constante de propiedad para un nombre de propiedad dado
  - IntlChar::getPropertyName — Devuelve el nombre Unicode de una propiedad
  - IntlChar::getPropertyValueEnum — Devuelve el valor de propiedad para un nombre de valor dado
  - IntlChar::getPropertyValueName — Devuelve el nombre Unicode para un valor de propiedad
  - IntlChar::getUnicodeVersion — Devuelve la versión Unicode
  - IntlChar::hasBinaryProperty — Verifica una propiedad Unicode binaria para un punto de código
  - IntlChar::isalnum — Verifica si un punto de código es un carácter alfanumérico
  - IntlChar::isalpha — Verifica si un punto de código es un carácter alfabético
  - IntlChar::isbase — Verifica si un punto de código es un carácter de base
  - IntlChar::isblank — Verifica si un punto de código es un carácter "blanco" o "espacio horizontal"
  - IntlChar::iscntrl — Verifica si un punto de código es un carácter de control
  - IntlChar::isdefined — Verifica si un punto de código está definido
  - IntlChar::isdigit — Verifica si un punto de código es un dígito
  - IntlChar::isgraph — Verifica si un punto de código es un carácter gráfico
  - IntlChar::isIDIgnorable — Verifica si un punto de código es un carácter ignorable
  - IntlChar::isIDPart — Verifica si un punto de código es permitido en un identificador
  - IntlChar::isIDStart — Verifica si un punto de código es permitido como primer carácter en un identificador
  - IntlChar::isISOControl — Verifica si un punto de código es un carácter de control ISO
  - IntlChar::isJavaIDPart — Verifica si un punto de código es permitido en un identificador Java
  - IntlChar::isJavaIDStart — Verifica si un punto de código es permitido como primer carácter en un identificador Java
  - IntlChar::isJavaSpaceChar — Verifica si un punto de código es un carácter de espacio según Java
  - IntlChar::islower — Verifica si un punto de código es una letra minúscula
  - IntlChar::isMirrored — Verifica si un punto de código tiene la propiedad Bidi_Mirrored
  - IntlChar::isprint — Verifica si un punto de código es un carácter imprimible
  - IntlChar::ispunct — Verifica si un punto de código es un carácter de puntuación
  - IntlChar::isspace — Verifica si un punto de código es un carácter de espacio
  - IntlChar::istitle — Verifica si un punto de código es una letra en título
  - IntlChar::isUAlphabetic — Verifica si un punto de código tiene la propiedad Unicode Alphabetic
  - IntlChar::isULowercase — Verifica si un punto de código tiene la propiedad Unicode Lowercase
  - IntlChar::isupper — Verifica si un punto de código tiene la categoría general "Lu" (letra mayúscula)
  - IntlChar::isUUppercase — Verifica si un punto de código tiene la propiedad Unicode Uppercase
  - IntlChar::isUWhiteSpace — Verifica si un punto de código tiene la propiedad Unicode White_Space
  - IntlChar::isWhitespace — Verifica si un punto de código es un carácter de espacio según ICU
  - IntlChar::isxdigit — Verifica si un punto de código es un dígito hexadecimal
  - IntlChar::ord — Devuelve el valor del punto de código Unicode de un carácter
  - IntlChar::tolower — Convierte un carácter Unicode a minúscula
  - IntlChar::totitle — Convierte un carácter Unicode en letra de título
  - IntlChar::toupper — Convierte un carácter Unicode a mayúscula
- IntlException — La clase de excepción para los errores intl
- IntlIterator — La clase IntlIterator
  - IntlIterator::current — Obtiene el elemento actual
  - IntlIterator::key — Obtiene la clave actual
  - IntlIterator::next — Se desplaza al elemento siguiente
  - IntlIterator::rewind — Reubica el iterador en el primer elemento
  - IntlIterator::valid — Verifica si la posición actual es válida
- Funciones de intl
  - intl_error_name — Lee el nombre simbólico de un código de error dado
  - intl_get_error_code — Lee el último código de error
  - intl_get_error_message — Lee la descripción del último error
  - intl_is_failure — Verifica si un código de error indica un fallo

# Strings multibyte

# Introducción

Aunque exiten muchos idiomas en los cuales cada carácter necesario puede ser representado por una referencia uno a uno a un valor de 8 bits, existen también bastantes idiomas que requieren tantos caracteres para la comunicación escrita que no pueden ser representados dentro del rango que un mero byte puede codificar (un byte se compone de ocho bits. Cada bit puede contener solamente dos valores distintos, uno o cero. Debido a esto, con un byte solo se pueden representar 256 valores únicos (2 a la 8ª potencia)). Los esquemas de codificación multibyte fueron desarrollados precisamente para expresar más de 256 caracteres en el sistema de codificación regular a nivel de bits.

Cuando se manipulan strings (trim, split, splice, etc.) en una codificación multibyte, es neceario utilizar funciones especiales, ya que dos o más bytes consecutivos pueden representar un único carácter en tal esquema de codificación. Si, de lo contrario, se usa una función que no considera caracteres multibyte con la cadena de caracteres, es probable que falle al detectar el comienzo o el final del carácter multibyte, y que se termine con una cadena de caracteres corrupta que probablemente pierda su significado original.

`mbstring` proporciona funciones específicas para cadenas de texto multibyte que ayudan a tratar codificaciones multibyte en PHP. Además, `mbstring` controla la conversión de la codificación de caracteres entre los posibles esquemas de codificación. `mbstring` está diseñada para manejar codificaciones basadas en Unicode, tales como UTF-8 y UCS-2, y, por conveniencia, varias codificaciones de un solo byte (enumeradas en Codificaciones de caracteres soportadas).

# Instalación/Configuración

## Tabla de contenidos

- Instalación
- Configuración en tiempo de ejecución

## Instalación

`mbstring` es una extensión PHP. La extensión debe ser activada con la opción `configure`. Ver la sección instalación para más detalles.

Las siguientes opciones de configuración están relacionadas con la extensión `mbstring`.

- --enable-mbstring : Activa las funciones `mbstring`. Esta opción es necesaria para utilizar las funciones `mbstring`.

  libmbfl es necesario para `mbstring`. libmbfl está incluido con `mbstring`. Anterior a PHP 7.3.0, si libmbfl ya está instalado en el sistema, --with-libmbfl[=DIR] puede ser especificado para utilizar la biblioteca instalada.

- --disable-mbregex : Desactiva las funciones de expresión regular con soporte para caracteres multioctetos.

  Oniguruma es necesario para las funciones de expresión regular con soporte para caracteres multioctetos. A partir de PHP 7.4.0, pkg-config es utilizado para detectar la biblioteca libonig. Anterior a PHP 7.4.0, Oniguruma estaba incluido con `mbstring`, pero era posible compilar contra una versión de libonig ya instalada pasando --with-onig[=DIR].

  Es posible desactivar la verificación del backtrack (retroceso) de las regex multioctetos especificando --disable-mbregex-backtrack.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración de mbstring
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
mbstring.language | "neutral" | `INI_ALL` |
mbstring.detect_order | NULL | `INI_ALL` |
mbstring.http_input | "pass" | `INI_ALL` | Obsoleta
mbstring.http_output | "pass" | `INI_ALL` | Obsoleta
mbstring.internal_encoding | NULL | `INI_ALL` | Obsoleta
mbstring.substitute_character | NULL | `INI_ALL` |
mbstring.func_overload | "0" | `INI_SYSTEM` | Obsoleta desde PHP 7.2.0; eliminada desde PHP 8.0.0.
mbstring.encoding_translation | "0" | `INI_PERDIR` |
mbstring.http_output_conv_mimetypes | "^(text/|application/xhtml\+xml)" | `INI_ALL` |
mbstring.strict_detection | "0" | `INI_ALL` |
mbstring.regex_retry_limit | "1000000" | `INI_ALL` | Disponible a partir de PHP 7.4.0.
mbstring.regex_stack_limit | "100000" | `INI_ALL` | Disponible a partir de PHP 7.3.5.

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`mbstring.language` string

  El ajuste de lenguaje nacional predeterminado (NLS) usado en mbstring. Se ha de observar que esta opción define automágicamente `mbstring.internal_encoding`, por lo que se debe colocar `mbstring.internal_encoding` tras `mbstring.language` en php.ini

`mbstring.encoding_translation` bool

  Habilita el filtro de codificación de caracteres transparente para las consultas HTTP entrantes, la cual lleva a cabo la detección y la conversión de la codificación de entrada a la codificación de caracteres interna.

`mbstring.internal_encoding` string
  Advertencia

  Esta funcionalidad obsoleta será ciertamente eliminada en el futuro.

  Define la codificación de caracteres interna.

  Los usuarios deberían dejarla vacía y establecer `default_charset` en su lugar.

`mbstring.http_input` string
  Advertencia

  Esta funcionalidad obsoleta será ciertamente eliminada en el futuro.

  Define la codificación de caracteres predeterminada de entrada de HTTP.

  Los usuarios deberían dejarla vacía y establecer `default_charset` en su lugar.

`mbstring.http_output` string
  Advertencia

  Esta funcionalidad obsoleta será ciertamente eliminada en el futuro.

  Define la codificación de caracteres predeterminada de salida de HTTP (la salida será convertida de la codificación interna a la codificación de salida de HTTP).

  Los usuarios deberían dejarla vacía y establecer `default_charset` en su lugar.

`mbstring.detect_order` string

  Define el orden de detección de códigos de caracteres predeterminado. Véase también mb_detect_order().

`mbstring.substitute_character` string

  Define el caracter de sustitución para juegos de caracteres inválidos. Véase también mb_substitute_character() para valores compatibles.

`mbstring.func_overload` string
  Advertencia

  Esta funcionalidad está OBSOLETA a partir de PHP 7.2.0, y ELIMINADA a partir de PHP 8.0.0. Depender de esta funcionalidad está altamente desaconsejado.

  Reemplaza determinadas funciones de único byte por sus equivalentes en mbstring. Véase la sección Sobrecarga de funciones para más información.

  Este ajuste sólo puede ser cambiado en el fichero php.ini

`mbstring.http_output_conv_mimetypes` string

`mbstring.strict_detection` bool

  Habilita la detección estricta de codificaciones. Consulte mb_detect_encoding() para obtener una descripción y ejemplos.

`mbstring.regex_retry_limit` int

  Limita la cantidad de retroceso que se puede realizar durante una coincidencia de mbregex.

  Esta configuración solo tiene efecto al enlazar con oniguruma >= 6.8.0.

`mbstring.regex_stack_limit` int

  Limita la profundidad de la pila de las expresiones regulares de mbstring.

De acuerdo a la » especificación de HTML 4.01, se permite que los navegadores envíen un formulario con una codificación diferente a la utilizada por la página. Véase mb_http_input() para consultar los juegos de caracteres utilizados por los navegadores.

Pese a que la mayoría de navegadores son capaces de averiguar la codificación de un determinado documento HTML, es aconsejable utilizar el parámetro `charset` en la cabecera `Content-Type` de HTTP con un valor apropiado, mediante header() o mediante el ajuste ini default_charset.

Ejemplo #1 Ejemplos de ajustes de php.ini

    ; Establecer el lenguaje predeterminado
    mbstring.language        = Neutral; Establecer el lenguaje neutral(UTF-8) (predeterminado)
    mbstring.language        = English; Establecer como lenguaje el inglés
    mbstring.language        = Japanese; Establecer como lenguaje el japonés

    ;; Establecer la codificación interna predeterminada
    ;; Nota: Asegúrese de usar una codificación que funcione con PHP
    mbstring.internal_encoding    = UTF-8  ; Establecer la codificación interna a UTF-8

    ;; Traducción de codificación HTTP entrante habilitada
    mbstring.encoding_translation = On

    ;; Establecer la codificación de caracteres predeterminada de HTTP entrante
    ;; Nota: Un script no podrá cambiar el ajuste http_input.
    mbstring.http_input           = pass    ; Sin conversión.
    mbstring.http_input           = auto    ; Establecer la entrada HTTP en automático
                                    ; "auto" se expande de acuerdo a mbstring.language
    mbstring.http_input           = SJIS    ; Establecer la entrada HTTP a SJIS
    mbstring.http_input           = UTF-8,SJIS,EUC-JP ; Especificar el orden

    ;; Establecer la codificación de caracteres predeterminada de HTTP saliente
    mbstring.http_output          = pass    ; Sin conversión
    mbstring.http_output          = UTF-8   ; Establecer la codificación de salida HTTP a UTF-8

    ;; Establecer el orden predeterminado de la detección de juegos de caracteres
    mbstring.detect_order         = auto    ; Orden de detección automático
    mbstring.detect_order         = ASCII,JIS,UTF-8,SJIS,EUC-JP ; Especificar el orden

    ;; Establecer el carácter de sustitución predeterminado
    mbstring.substitute_character = 12307   ; Especificar un valor Unicode
    mbstring.substitute_character = none    ; No imprimir el carácter
    mbstring.substitute_character = long    ; Ejemplo de long: U+3000,JIS+7E7E

Ejemplo #2 Ajustes de php.ini para usuarios de `EUC-JP`

    ;; Deshabilitar el almacenamiento en el búfer de salida
    output_buffering      = Off

    ;; Establecer el juego de caracteres de las cabeceras HTTP
    default_charset       = EUC-JP

    ;; Establecer como lenguaje predeterminado el japonés
    mbstring.language = Japanese

    ;; Habilitar la traducción de la codificación del HTTP entrante.
    mbstring.encoding_translation = On

    ;; Establecer en automática la conversión de la codificación de HTTP entrante
    mbstring.http_input   = auto

    ;; Convertir la salida de HTTP a EUC-JP
    mbstring.http_output  = EUC-JP

    ;; Establecer EUC-JP como codificación interna
    mbstring.internal_encoding = EUC-JP

    ;; No imprimir caracteres inválidos
    mbstring.substitute_character = none

Ejemplo #3 Ajustes de php.ini para usuarios de `SJIS`

    ;; Habilitar el almacenamiento en el búfer de salida
    output_buffering     = On

    ;; Establecer mb_output_handler para habilitar la conversión de los datos de salida
    output_handler       = mb_output_handler

    ;; Establecer el juego de caracteres de las cabeceras HTTP
    default_charset      = Shift_JIS

    ;; Establecer como lenguaje predeterminado el japonés
    mbstring.language = Japanese

    ;; Establecer en automático la conversión del juego de caracteres http entrante
    mbstring.http_input  = auto

    ;; Convertir a SJIS
    mbstring.http_output = SJIS

    ;; Establecer EUC-JP como codificación interna
    mbstring.internal_encoding = EUC-JP

    ;; No imprimir caracteres inválidos
    mbstring.substitute_character = none

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`MB_OVERLOAD_MAIL` (int)
  Eliminado desde PHP 8.0.0.
`MB_OVERLOAD_STRING` (int)
  Eliminado desde PHP 8.0.0.
`MB_OVERLOAD_REGEX` (int)
  Eliminado desde PHP 8.0.0.
`MB_CASE_UPPER` (int)
  Realiza una conversión completa a mayúsculas. Esto puede cambiar la longitud del string. Este es el modo utilizado por mb_strtoupper().
`MB_CASE_LOWER` (int)
  Realiza una conversión completa a minúsculas. Esto puede cambiar la longitud del string. Este es el modo utilizado por mb_strtolower().
`MB_CASE_TITLE` (int)
  Realiza una conversión completa a title-case basada en las propiedades derivadas de Unicode Cased y CaseIgnorable. En particular, esto mejora el manejo de las comillas y los apóstrofes. Esto puede cambiar la longitud del string.
`MB_CASE_FOLD` (int)
  Realiza una conversión completa que elimina las distinciones de mayúsculas y minúsculas presentes en el string. Esto se utiliza para la comparación sin distinción entre mayúsculas y minúsculas. Esto puede cambiar la longitud del string. Disponible desde PHP 7.3.
`MB_CASE_LOWER_SIMPLE` (int)
  Realiza una conversión simple a minúsculas. Esto no cambia la longitud del string. Disponible desde PHP 7.3.
`MB_CASE_UPPER_SIMPLE` (int)
  Realiza una conversión simple a mayúsculas. Esto no cambia la longitud del string. Disponible desde PHP 7.3.
`MB_CASE_TITLE_SIMPLE` (int)
  Realiza una conversión simple a title-case. Esto no cambia la longitud de la cadena. Disponible desde PHP 7.3.
`MB_CASE_FOLD_SIMPLE` (int)
  Realiza una conversión simple que elimina las distinciones de mayúsculas y minúsculas presentes en el string. Esto se utiliza para la comparación sin distinción entre mayúsculas y minúsculas. Esto no cambia la longitud del string. Utilizado internamente por las operaciones sin distinción entre mayúsculas y minúsculas de la extensión MBString. Disponible desde PHP 7.3.
`MB_ONIGURUMA_VERSION` (string)
  La versión de Oniguruma, p. ej. `6.9.4`. Disponible desde PHP 7.4.

# Juegos de caracteres soportados

Juegos de caracteres soportados
Nombre en el registro IANA | Juegos de caracteres | Descripción | Notas
--- | --- | --- | ---
ISO-10646-UCS-4 | ISO 10646 | El juego de caracteres universal (`Universal Character Set`), con 31 bits por caracter, al estándar `UCS-4` por `ISO/IEC 10646`. Está sincronizado con la última versión de Unicode. | Si este nombre es utilizado en la herramienta de conversión, el convertidor intenta reconocer el texto a partir del último BOM (`byte order mark`), para conocer el orden de los bits.
ISO-10646-UCS-4 | UCS-4 | Ver arriba. | A diferencia de `UCS-4`, las cadenas se suponen estar en formato big endian.
ISO-10646-UCS-4 | UCS-4 | Ver arriba. | A diferencia de `UCS-2`, las cadenas se suponen estar en formato little endian.
ISO-10646-UCS-2 | UCS-2 | El juego de caracteres universal (`Universal Character Set`), con 16 bits por caracter, al estándar `UCS-2` por `ISO/IEC 10646`. Está sincronizado con la última versión de Unicode. | Si este nombre es utilizado en la herramienta de conversión, el convertidor intenta reconocer el texto a partir del último BOM (`byte order mark`), para conocer el orden de los bits.
ISO-10646-UCS-2 | UCS-2 | Ver arriba. | A diferencia de `UCS-4`, las cadenas se suponen estar en formato big endian.
UTF-32 | Unicode | Formato de transformación de Unicode, de 32 bits, cuyas cartas corresponden al juego estándar Unicode. Este juego no es idéntico a `UCS-4` porque los caracteres Unicode estaban limitados a valores de 21 bits. | Si este nombre es utilizado en la herramienta de conversión, el convertidor intenta reconocer el texto a partir del último BOM (`byte order mark`), para conocer el orden de los bits.
UTF-32BE | Unicode | Ver arriba. | A diferencia de `UTF-32`, las cadenas se suponen estar en formato big endian.
UTF-32LE | Unicode | Ver arriba. | A diferencia de `UTF-32`, las cadenas se suponen estar en formato little endian.
UTF-16 | Unicode | Formato de transformación de Unicode sobre 16 bits. Se debe notar que `UTF-16` ya no es idéntico a `UCS-2` porque un mecanismo fue introducido en Unicode 2.0 y `UTF-16` ahora hace referencia a un codificación de 21 bits. | Si este nombre es utilizado en la herramienta de conversión, el convertidor intenta reconocer el texto a partir del último BOM (`byte order mark`), para conocer el orden de los bits.
UTF-16BE | Unicode | Ver arriba. | A diferencia de `UTF-16`, las cadenas se suponen estar en formato big endian.
UTF-16LE | Unicode | Ver arriba. | A diferencia de `UTF-16`, las cadenas se suponen estar en formato little endian.
UTF-8 | Unicode / UCS | Formato de transformación Unicode de 8 bits. | ninguno
UTF-7 | Unicode | Un formato compatible con el correo electrónico de Unicode, especificado en » RFC2152. | ninguno
ninguno | Unicode | Una variante de `UTF-7` que es especialmente utilizada en el » protocolo IMAP. | ninguno
US-ASCII (recomendado) / iso-ir-6 / ANSI_X3.4-1986 / ISO_646.irv:1991 / ASCII / ISO646-US / us / IBM367 / CP367 / csASCII | ASCII / ISO 646 | ASCII, `American Standard Code for Information Interchange` es un formato clásico de 7 bits. También está normalizado internacionalmente, bajo el nombre `ISO 646`. | (ninguno)
EUC-JP (recomendado) / Extended_UNIX_Code_Packed_Format_for_Japanese / csEUCPkdFmtJapanese | Compuesto de US-ASCII / JIS X0201:1997 (hankaku kana) / JIS X0208:1990 / JIS X0212:1990 | Como se puede ver, el nombre deriva de la abreviatura de `Extended UNIX Code Packed Format for Japanese`, este juego es esencialmente utilizado en plataformas Unix. El juego original, `Extended UNIX Code`, está diseñado sobre la base de `ISO 2022`. | El juego identificado por `EUC-JP` es diferente de `IBM932 / CP932`, que es utilizado por `OS/2®` y Microsoft® Windows®. Para intercambiar información con estas plataformas, utilice `EUCJP-WIN`.
Shift_JIS (recomendado) / MS_Kanji / csShift_JIS | Compuesto de JIS X0201:1997 / JIS X0208:1997 | `Shift_JIS` fue desarrollado a principios de los años 80, y, al mismo tiempo, los primeros procesadores de texto estaban en el mercado. Fue hecho para conservar la compatibilidad con el juego `JIS X 0201:1976`. Según la definición de IANA, el juego de caracteres `Shift_JIS` es ligeramente diferente de `IBM932 / CP932`. Sin embargo, los nombres `"SJIS"` y `"Shift_JIS"` son a menudo utilizados erróneamente, para estos juegos. | Para `CP932`, utilice `SJIS-WIN`.
(ninguno) | Compuesto de JIS X0201:1997 / JIS X0208:1997 / IBM extensions / NEC extensions | Aunque este "juego de caracteres" utiliza el mismo juego que `EUC-JP`, en realidad es diferente. Solo tiene algunos caracteres de diferencia. | ninguno
Windows-31J / csWindows31J | Compuesto de JIS X0201:1997 / JIS X0208:1997 / IBM extensions / NEC extensions | Aunque este "juego de caracteres" utiliza el mismo juego que `Shift_JIS`, en realidad es diferente. Solo tiene algunos caracteres de diferencia. | (ninguno)
ISO-2022-JP (recomendado) / csISO2022JP | US-ASCII / JIS X0201:1976 / JIS X0208:1978 / JIS X0208:1983 | » RFC1468 | ninguno
JIS |  |  |
ISO-8859-1 |  |  |
ISO-8859-2 |  |  |
ISO-8859-3 |  |  |
ISO-8859-4 |  |  |
ISO-8859-5 |  |  |
ISO-8859-6 |  |  |
ISO-8859-7 |  |  |
ISO-8859-8 |  |  |
ISO-8859-9 |  |  |
ISO-8859-10 |  |  |
ISO-8859-13 |  |  |
ISO-8859-14 |  |  |
ISO-8859-15 |  |  |
ISO-8859-16 |  |  |
byte2be |  |  |
byte2le |  |  |
byte4be |  |  |
byte4le |  |  |
BASE64 |  |  |
HTML-ENTITIES |  |  |
7bit |  |  |
8bit |  |  |
EUC-CN |  |  |
CP936 |  |  |
HZ |  |  |
EUC-TW |  |  |
CP950 |  |  |
BIG-5 |  |  |
EUC-KR |  |  |
UHC (CP949) |  |  |
ISO-2022-KR |  |  |
Windows-1251 (CP1251) |  |  |
Windows-1252 (CP1252) |  |  |
CP866 (IBM866) |  |  |
KOI8-R |  |  |
KOI8-U |  |  |

# Casos de caracteres japoneses

Los caracteres japoneses solo pueden ser representados con encodings multiocteto y los estándares de encoding múltiple se utilizan según la plataforma y el texto de referencia. Para facilitar las cosas, estos estándares de encodings difieren ligeramente entre sí. Para desarrollar aplicaciones Web en entorno japonés, el desarrollador deberá tener en cuenta estas complejidades a fin de asegurarse de que se utilice el encoding de caracteres correcto.

- El tamaño necesario para un carácter puede llegar hasta 4 octetos.
- Un carácter japonés multiocteto ocupa generalmente dos octetos, en comparación con los caracteres mono-octeto tradicionalmente utilizados. Estos caracteres se denominan `"zen-kaku"`, lo que significa `"gran anchura"`. Los más pequeños se denominan `"han-kaku"`, lo que significa `"media anchura"`.
- Algunos encodings de caracteres utilizan secuencias `"shift"` (escape) definidas en la referencia ISO-2022 para cambiar a la tabla de encoding del código específico (`00h` a `7fh`).
- ISO-2022-JP debe ser utilizado para los protocolos SMTP/NNTP, y los encabezados así como las entidades deberían ser reencodificados de acuerdo con la RFC correspondiente. Aunque esto no es requerido, sigue siendo una buena idea ya que muchos user-agent (agentes de usuario) populares no pueden reconocer otro método de encoding.
- Las páginas Web creadas para teléfonos móviles como » i-mode, o » EZweb están supuestas a utilizar el encoding Shift_JIS.
- Los emojis utilizados para teléfonos móviles, tales como » i-mode o » EZweb son soportados.

# Entradas/Salidas HTTP

La conversión automática de las entradas/salidas HTTP puede también convertir datos binarios. Los usuarios deben controlar las conversiones, si los datos binarios deben ser utilizados mediante HTTP.

> Nota:

> Si el atributo `enctype` de la etiqueta `form` vale `multipart/form-data` y la directiva del php.ini está posicionada a On, las variables y los nombres de ficheros subidos mediante el método POST serán convertidos con la codificación interna. De lo contrario, la conversión no se realizará.

- Entrada HTTP

  No hay medios para controlar la conversión de caracteres HTTP en entrada, desde un script PHP. Para desactivar esta conversión, debe hacerse desde el fichero php.ini.

  Ejemplo #1 Desactiva la conversión HTTP en el php.ini

      ;; Desactivar la conversión de entrada HTTP
      mbstring.http_input = pass
      ;; Desactivar la conversión de entrada HTTP
      mbstring.encoding_translation = Off

  Cuando se utiliza PHP como módulo Apache, es posible anular la configuración del php.ini para cada Virtual Host en el fichero httpd.conf o por directorio con el fichero `.htaccess`. Consúltese la sección de configuración así como el manual de Apache.

- Salidas HTTP

  Existen varios medios para activar la conversión en salida de script PHP. Uno de ellos utiliza php.ini, otro utiliza ob_start() con la función mb_output_handler() como función de retrollamada.

Ejemplo #2 Ejemplo de configuración de mbstring en php.ini

    ;; Habilitar la conversión de codificación de caracteres en salida para todas las páginas PHP

    ;; Habilitar el búfer de salida
    output_buffering    = On

    ;; Establecer mb_output_handler para habilitar la conversión en salida
    output_handler      = mb_output_handler

Ejemplo #3 Ejemplo de script con mbstring

    <?php

    // Habilitar la conversión de codificación de caracteres en salida HTTP solo para esta página

    // Establecer la codificación de caracteres en salida HTTP a SJIS
    mb_http_output('SJIS');

    // Iniciar el búfer y especificar "mb_output_handler" como
    // función de retrollamada
    ob_start('mb_output_handler');

    ?>

# Juegos de caracteres soportados

Actualmente, los siguientes juegos de caracteres son soportados por `mbstring`. La codificación de caracteres puede ser especificada mediante los parámetros `encoding` en las funciones `mbstring`.

Los siguientes juegos de caracteres son soportados por `mbstring`:

- UCS-4*
- UCS-4BE
- UCS-4LE*
- UCS-2
- UCS-2BE
- UCS-2LE
- UTF-32*
- UTF-32BE*
- UTF-32LE*
- UTF-16*
- UTF-16BE*
- UTF-16LE*
- UTF-7
- UTF7-IMAP
- UTF-8*
- ASCII*
- EUC-JP*
- SJIS*
- eucJP-win*
- SJIS-win*
- ISO-2022-JP
- ISO-2022-JP-MS
- CP932
- CP51932
- SJIS-mac (alias: MacJapanese)
- SJIS-Mobile#DOCOMO (alias: SJIS-DOCOMO)
- SJIS-Mobile#KDDI (alias: SJIS-KDDI)
- SJIS-Mobile#SOFTBANK (alias: SJIS-SOFTBANK)
- UTF-8-Mobile#DOCOMO (alias: UTF-8-DOCOMO)
- UTF-8-Mobile#KDDI-A
- UTF-8-Mobile#KDDI-B (alias: UTF-8-KDDI)
- UTF-8-Mobile#SOFTBANK (alias: UTF-8-SOFTBANK)
- ISO-2022-JP-MOBILE#KDDI (alias: ISO-2022-JP-KDDI)
- JIS
- JIS-ms
- CP50220
- CP50220raw
- CP50221
- CP50222
- ISO-8859-1*
- ISO-8859-2*
- ISO-8859-3*
- ISO-8859-4*
- ISO-8859-5*
- ISO-8859-6*
- ISO-8859-7*
- ISO-8859-8*
- ISO-8859-9*
- ISO-8859-10*
- ISO-8859-13*
- ISO-8859-14*
- ISO-8859-15*
- ISO-8859-16*
- byte2be
- byte2le
- byte4be
- byte4le
- BASE64
- HTML-ENTITIES (alias: HTML)
- 7bit
- 8bit
- EUC-CN*
- CP936
- GB18030
- HZ
- EUC-TW*
- CP950
- BIG-5*
- EUC-KR*
- UHC (alias: CP949)
- ISO-2022-KR
- Windows-1251 (alias: CP1251)
- Windows-1252 (alias: CP1252)
- CP866 (alias: IBM866)
- KOI8-R*
- KOI8-U*
- ArmSCII-8 (alias: ArmSCII8)

* : codificaciones también utilizables en expresiones regulares.

Todas las entradas del php.ini que aceptan un nombre de codificación pueden también utilizar los valores "`auto`" y "`pass`". Las funciones `mbstring`, que aceptan nombres de juegos de caracteres, pueden también utilizar el valor "`auto`".

Si "`pass`" es utilizada, ninguna conversión se efectúa.

Si "`auto`" es definido, la lista será extendida a la lista de codificaciones definidas por NLS. Por ejemplo, si `NLS` vale `Japanese`, los valores serán "`ASCII,JIS,UTF-8,EUC-JP,SJIS`".

Ver también mb_detect_order().

# Función de sobrecarga

Advertencia

Esta funcionalidad está OBSOLETA a partir de PHP 7.2.0, y ELIMINADA a partir de PHP 8.0.0. Depender de esta funcionalidad está altamente desaconsejado.

Puede resultar difícil lograr que una aplicación PHP existente funcione en un entorno multibyte determinado. Esto se debe a que la mayoría de las aplicaciones PHP están escritas con funciones de string estándar como substr(), que es conocida por no manejar correctamente los strings codificados en multibyte.

mbstring admite la sobrecarga de funciones, lo que permite añadir compatibilidad con multibyte a este tipo de aplicaciones sin modificar el código, mediante la sobrecarga de las funciones equivalentes para multibyte en las funciones de string estándar. Por ejemplo, si la sobrecarga de funciones está habilitada, se llama a mb_substr() en lugar de a substr(). Esta característica facilita la migración de aplicaciones que solo admiten codificaciones de un solo byte a un entorno multibyte en muchos casos.

Para utilizar la sobrecarga de funciones, establezca `mbstring.func_overload`, en el php.ini, a un valor positivo que represente una combinación de máscaras de bits especificando las categorías de funciones a sobrecargar. Debe ser definido a 1 para sobrecargar la función mail(), 2 para las funciones de strings, 4 para las funciones de expresiones regulares. Por ejemplo, con el valor 7, todas las funciones anteriores serán sobrecargadas. A continuación se muestra la lista de funciones sobrecargadas.

Funciones de reemplazo
Valor de mbstring.func_overload | Función original | Función de reemplazo
--- | --- | ---
1 | mail() | mb_send_mail()
2 | strlen() | mb_strlen()
2 | strpos() | mb_strpos()
2 | strrpos() | mb_strrpos()
2 | substr() | mb_substr()
2 | strtolower() | mb_strtolower()
2 | strtoupper() | mb_strtoupper()
2 | stripos() | mb_stripos()
2 | strripos() | mb_strripos()
2 | strstr() | mb_strstr()
2 | stristr() | mb_stristr()
2 | strrchr() | mb_strrchr()
2 | substr_count() | mb_substr_count()

> Nota:

> No se recomienda utilizar la opción de sobrecarga de funciones en el contexto por directorio, ya que aún no se ha confirmado que sea lo suficientemente estable en un entorno de producción y puede provocar un comportamiento indefinido.

# Requerimientos para la codificación de caracteres en PHP

Las codificaciones de los siguientes tipos se pueden utilizar con PHP de forma segura.

- Codificaciones de un solo byte,

  - que tienen mapas de referencia compatibles con ASCII (ISO646) para los caracteres en el rango de `00h` a `7fh`.

- Codificación multibyte,

  - que tienen mapas de referencia compatibles con ASCII para los caracteres en el rango de `00h` a `7fh`.
  - que no utilizan secuencias de escape ISO2022.
  - que no utilizan un valor en el rango de `00h` a `7fh` en cualquiera de los bytes compuestos que representan un carácter sencillo.

Estos son ejemplos de codificaciones de caracteres que es poco probable que funcionen con PHP.

    JIS, SJIS, ISO-2022-JP, BIG-5

Aunque algunos scripts de PHP escritos en estas codificaciones podrían no funcionar, especialmente en el caso donde los strings codificados aparecen como identificadores o como literales en el propio script, se puede evitar el uso de estas codificaciones configurando la función de filtro de codificación transparente de `mbstring` para las consultas HTTP entrantes.

> Nota:

> Se desaconseja energicamente el uso de SJIS, BIG5, CP936, CP949 y GB18030 para la codificación interna, a menos que se esté familiarizado con el analizador, el explorador y la codificación de caracteres.

> Nota:

> Si se va a conectar a una base de datos con PHP, se recomienda utilizar la misma codificación de caracteres para la base de datos y la `codificación interna` para un uso más sencillo y un mejor rendimiento.

> Si se utiliza PostgreSQL, la codificación utilizada en la base de datos y la utilizada en PHP puede ser distinta debido a que se admite la conversión automática del conjunto de caracteres entre la parte final y la inicial del proceso.

# Funciones de strings multibyte

# Referencias

Los esquemas de codificación de caracteres multibyte y temas relacionados son muy complicados y están fuera del alcance de esta documentación. Se aconseja visitar los siguientes URLs y otros recursos para tener unos conocimientos más amplios que los escritos en estos temas.

- Documentación de Unicode

  » http://www.unicode.org/

- Información sobre los conjuntos de caracteres japonés/coreano/chino

  » https://resources.oreilly.com/examples/9781565922242/blob/master/doc/cjk.inf

# mb_check_encoding

(PHP 4 >= 4.4.3, PHP 5 >= 5.1.3, PHP 7, PHP 8)

mb_check_encoding — Verifica si las cadenas son válidas para el encodage especificado

### Descripción

function mb_check_encoding(array|string|null `$value` = `null`, ?string `$encoding` = `null`): bool

Verifica si el flujo de octetos es válido para el encodage específico. Si `value` es de tipo array, todas las claves y los valores son validados de manera recursiva. Es útil para prever lo que se conoce como « ataque por encodage inválido ».

### Parámetros

`value`

  El flujo de octetos o array a verificar. Si es omitido, esta función verifica todas las entradas desde el inicio de la petición.

  Advertencia

  A partir de PHP 8.1.0, la omisión de este argumento o el paso de `null` está obsoleto.

`encoding`

  Encodage esperado.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | La llamada a esta función con `null` como `value` o sin argumento está obsoleta.
8.0.0 | `value` y `encoding` ahora son nullable.
7.2.0 | Esta función ahora también acepta un array como valor de `value`. Anteriormente, solo las string eran soportadas.

# mb_chr

(PHP 7 >= 7.2.0, PHP 8)

mb_chr — Devuelve un carácter por su valor de punto de código Unicode

### Descripción

function mb_chr(int `$codepoint`, ?string `$encoding` = `null`): string|false

Devuelve una cadena que contiene el carácter especificado por el valor del punto de código Unicode, codificado en la codificación especificada.

Esta función complementa a mb_ord().

### Parámetros

`codepoint`

  Un valor de punto de código Unicode, p. ej. `128024` para U+1F418 ELEPHANT

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

Una cadena que contiene el carácter solicitado, si puede ser representado en la codificación especificada o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `encoding` ahora acepta `null`.

### Ejemplos

Ejemplo #1 Probar diferentes puntos de código

    <?php
    $values = [65, 63, 0x20AC, 128024];
    foreach ($values as $value) {
        var_dump(mb_chr($value, 'UTF-8'));
        var_dump(mb_chr($value, 'ISO-8859-1'));
    }
    ?>

El ejemplo anterior mostrará:

    string(1) "A"
    string(1) "A"
    string(1) "?"
    string(1) "?"
    string(3) "€"
    bool(false)
    string(4) "🐘"
    bool(false)

### Ver también

- mb_internal_encoding() - Lee/modifica la codificación interna
- mb_ord() - Obtiene el punto de código Unicode de un carácter
- IntlChar::ord() - Devuelve el valor del punto de código Unicode de un carácter
- chr() - Generar un string de un byte a partir de un número

# mb_convert_case

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_convert_case — Realiza una conversión a mayúsculas/minúsculas de un string

### Descripción

function mb_convert_case(string `$string`, int `$mode`, ?string `$encoding` = `null`): string

Realiza una conversión a mayúsculas/minúsculas de un string, de acuerdo al valor especificado en `mode`.

### Parámetros

`string`

  El string que se va a convertir.

`mode`

  El modo de conversión. Puede ser uno de `MB_CASE_UPPER`, `MB_CASE_LOWER`, `MB_CASE_TITLE`, `MB_CASE_FOLD`, `MB_CASE_UPPER_SIMPLE`, `MB_CASE_LOWER_SIMPLE`, `MB_CASE_TITLE_SIMPLE`, `MB_CASE_FOLD_SIMPLE`.

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

La versión convertida del `string` en función del valor especificado en `mode`.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Se implementaron reglas de mayúsculas y minúsculas condicionales para la letra griega sigma que solo se aplican a los modos `MB_CASE_LOWER` y `MB_CASE_TITLE`, no a `MB_CASE_LOWER_SIMPLE` y `MB_CASE_TITLE_SIMPLE`.
7.3.0 | Añadido soporte para `MB_CASE_FOLD`, `MB_CASE_UPPER_SIMPLE`, `MB_CASE_LOWER_SIMPLE`, `MB_CASE_TITLE_SIMPLE`, y `MB_CASE_FOLD_SIMPLE` como `mode`.

### Ejemplos

Ejemplo #1 Ejemplo de mb_convert_case()

    <?php
    $str = "mary had a Little lamb and she loved it so";
    $str = mb_convert_case($str, MB_CASE_UPPER, "UTF-8");
    echo $str, PHP_EOL;
    $str = mb_convert_case($str, MB_CASE_TITLE, "UTF-8");
    echo $str, PHP_EOL;
    ?>

Ejemplo #2 Ejemplo de mb_convert_case() con alfabeto no latino en UTF-8

    <?php
    $str = "Τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός";
    $str = mb_convert_case($str, MB_CASE_UPPER, "UTF-8");
    echo $str, PHP_EOL;
    $str = mb_convert_case($str, MB_CASE_TITLE, "UTF-8");
    echo $str, PHP_EOL;
    ?>

### Notas

A diferencia de las funciones estándar de mayúsculas/minúsculas, como strtolower() y strtoupper(), la conversión se lleva a cabo según los fundamentos de las propiedades de los caracteres Unicode. Por lo tanto, el comportamiento de esta función no se ve afectado por la configuración regional y puede convertir cualquier carácter que tenga propiedad 'alfabética', como la a con diéresis (ä).

Para más información sobre las propiedades Unicode, por favor, revise » http://www.unicode.org/reports/tr21/.

### Ver también

- mb_strtolower() - Convierte todos los caracteres a minúsculas
- mb_strtoupper() - Convierte todos los caracteres a mayúsculas
- strtolower() - Devuelve una string en minúsculas
- strtoupper() - Devuelve una string en mayúsculas
- ucfirst() - Pone en mayúscula el primer carácter
- ucwords() - Pone en mayúscula la primera letra de todas las palabras

# mb_convert_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_encoding — Convertir una cadena de un codificación de caracteres a otra

### Descripción

function mb_convert_encoding(array|string `$string`, string `$to_encoding`, array|string|null `$from_encoding` = `null`): array|string|false

Convierte la `string` desde `from_encoding`, o la codificación interna actual, a `to_encoding`. Opcionalmente desde `from_encoding`. Si `string` es un array, todos sus valores string serán convertidos recursivamente.

### Parámetros

`string`

  La string o array a convertir.

`to_encoding`

  La codificación deseada del resultado.

`from_encoding`

  La codificación actual utilizada para interpretar la `string`. Múltiples codificaciones pueden ser especificadas en forma de array (array) o lista separada por comas. En este caso, la codificación correcta será adivinada utilizando el mismo algoritmo que mb_detect_encoding().

  Si `from_encoding` es omitido o `null`, el parámetro mbstring.internal_encoding será utilizado si está definido, de lo contrario el parámetro default_charset será utilizado.

  Ver codificaciones soportadas para los valores válidos de `to_encoding` y `from_encoding`.

### Valores devueltos

La string o array codificado en caso de éxito, o `false` si ocurre un error.

### Errores/Excepciones

A partir de PHP 8.0.0, una ValueError es lanzada si la valor de `to_encoding` o `from_encoding` es una codificación inválida. Anterior a PHP 8.0.0, una `E_WARNING` era emitida en su lugar.

### Historial de cambios

Versión | Descripción
--- | ---
8.2.0 | mb_convert_encoding() ya no devolverá las siguientes codificaciones no textuales: `"Base64"`, `"QPrint"`, `"UUencode"`, `"HTML entities"`, `"7 bit"` y `"8 bit"`.
8.0.0 | mb_convert_encoding() lanzará ahora una ValueError cuando `to_encoding` es pasado una codificación inválida.
8.0.0 | mb_convert_encoding() lanzará ahora una ValueError cuando `from_encoding` es pasado una codificación inválida.
8.0.0 | `from_encoding` ahora es nullable.
7.2.0 | Esta función ahora acepta un array como `string`. Anteriormente, solo las string eran soportadas.

### Ejemplos

Ejemplo #1 Ejemplo con mb_convert_encoding()

    <?php
    /* Convierte la codificación interna a SJIS */
    $str = mb_convert_encoding($str, "SJIS");

    /* Convierte EUC-JP a UTF-7 */
    $str = mb_convert_encoding($str, "UTF-7", "EUC-JP");

    /* Detecta automáticamente una codificación entre JIS, eucjp-win o sjis-win,
       Luego convierte a UCS-2LE */
    $str = mb_convert_encoding($str, "UCS-2LE", "JIS, eucjp-win, sjis-win");

    /* Si mbstring.language es "Japanese", "auto" es extendido a "ASCII,JIS,UTF-8,EUC-JP,SJIS" */
    $str = mb_convert_encoding($str, "EUC-JP", "auto");
    ?>

### Ver también

- mb_detect_order() - Lee/modifica el orden de detección de codificaciones
- UConverter::transcode() - Convierte una cadena de un juego de caracteres a otro
- iconv() - Convierte una cadena de caracteres de un encodaje a otro

# mb_convert_kana

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_kana — Convierte un "kana" en otro ("zen-kaku", "han-kaku" y más)

### Descripción

function mb_convert_kana(string `$string`, string `$mode` = "KV", ?string `$encoding` = `null`): string

Realiza una conversión "han-kaku" - "zen-kaku" en la cadena `string`. Esta función es únicamente útil para los japoneses.

### Parámetros

`string`

  La cadena a convertir.

`mode`

  La opción de conversión.

  Especifique las conversiones combinando los siguientes valores.

  Opciones de conversión disponibles
  Opción | Significado
  --- | ---
  `r` | Convierte el alfabeto "zen-kaku" en "han-kaku"
  `R` | Convierte el alfabeto "han-kaku" en "zen-kaku"
  `n` | Convierte los números "zen-kaku" en "han-kaku"
  `N` | Convierte los números "han-kaku" en "zen-kaku"
  `a` | Convierte los números y alfabeto "zen-kaku" en "han-kaku"
  `A` | Convierte los números y alfabeto "zen-kaku" en "han-kaku". (Los caracteres incluidos en las opciones "a", "A" son U+0021 - U+007E excluyendo U+0022, U+0027, U+005C, U+007E)
  `s` | Convierte "zen-kaku" en "han-kaku" (U+3000 -> U+0020)
  `S` | Convierte "han-kaku" en "zen-kaku" (U+0020 -> U+3000)
  `k` | Convierte "zen-kaku kata-kana" en "han-kaku kata-kana"
  `K` | Convierte "han-kaku kata-kana" en "zen-kaku kata-kana"
  `h` | Convierte "zen-kaku hira-gana" en "han-kaku kata-kana"
  `H` | Convierte "han-kaku kata-kana" en "zen-kaku hira-gana"
  `c` | Convierte "zen-kaku kata-kana" en "zen-kaku hira-gana"
  `C` | Convierte "zen-kaku hira-gana" en "zen-kaku kata-kana"
  `V` | Elimina las notaciones vocales y las convierte en caracteres. Usar con "K","H"

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

La cadena convertida.

### Errores/Excepciones

Genera un ValueError si la combinación de diferentes `mode` no es válida. Por ejemplo `"sS"`.

### Historial de cambios

Versión | Descripción
--- | ---
8.2.0 | Ahora se genera un ValueError si la combinación de diferentes `mode`s no es válida.
8.0.0 | `encoding` ahora acepta `null`.

### Ejemplos

Ejemplo #1 Ejemplo con mb_convert_kana()

    <?php
    /* Convierte todos los "han-kaku" "kata-kana" en "zen-kaku" "hira-gana" */
    echo mb_convert_kana('ﾔﾏﾀﾞ ﾊﾅｺ', "HV") . "\n";

    /* Convierte "han-kaku" "kata-kana" en "zen-kaku" "kata-kana"
       y "zen-kaku" alfanumérico en "han-kaku" */
    echo mb_convert_kana('ｺｳｻﾞﾊﾞﾝｺﾞｳ ０１２３４５６', "KVa") . "\n";
    ?>

El ejemplo anterior mostrará:

    やまだ はなこ
    コウザバンゴウ 0123456

# mb_convert_variables

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_variables — Convierte la codificación de variables

### Descripción

function mb_convert_variables(
string `$to_encoding`,
array|string `$from_encoding`,
mixed `&$var`,
mixed `&...$vars`
): string|false

Convierte la codificación de las variables `var` y `vars` desde la codificación `from_encoding` hacia la codificación `to_encoding`

mb_convert_variables() coloca las strings en un array o un objeto para detectar la codificación, pero la detección tiende a fallar para strings de pequeño tamaño. Por lo tanto, no es posible mezclar codificaciones en un array o un objeto "simple".

### Parámetros

`to_encoding`

  La codificación a la cual la string debe ser convertida.

`from_encoding`

  `from-encoding` es una lista de codificaciones posibles para las variables `vars`, proporcionada en forma de un array o una lista de codificaciones, separadas por comas. Si `from_encoding` es omitido, las codificaciones proporcionadas en mb_detect_order() son utilizadas.

`var`

  `var` es una referencia a una variable a convertir. Las strings, arrays y objetos también son soportados. mb_convert_variables() toma todos estos parámetros con la misma codificación.

`vars`

  Variables adicionales.

### Valores devueltos

La codificación antes de la conversión en caso de éxito, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con mb_convert_variables()

    <?php
    /* Convierte las variables $post1, $post2 a la codificación interna */
    $interenc = mb_internal_encoding();
    $inputenc = mb_convert_variables($interenc, "ASCII,UTF-8,SJIS-win", $post1, $post2);
    ?>

# mb_decode_mimeheader

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_decode_mimeheader — Decodifica un encabezado MIME

### Descripción

function mb_decode_mimeheader(string `$string`): string

Decodifica la cadena codificada `string` en el encabezado MIME.

### Parámetros

`string`

  La cadena a decodificar.

### Valores devueltos

La cadena decodificada, con un codificación interna.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Los guiones bajos son convertidos en espacios como se especifica en » RFC 2047.

### Ver también

- mb_encode_mimeheader() - Codifica una cadena para un encabezado MIME

# mb_decode_numericentity

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_decode_numericentity — Decodificar referencia numérica de cadena HTML a carácter

### Descripción

function mb_decode_numericentity(string `$string`, array `$map`, ?string `$encoding` = `null`): string

Convierte la referencia numérica de cadena de string `string` en un bloque especificado a carácter.

### Parámetros

`string`

  La string que se está decodificando.

`map`

  `map` es un array que especifica el área de código a convertir.

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

La string convertida.

### Errores/Excepciones

Genera una excepción ValueError si `map` no es una lista de ints.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | mb_decode_numericentity() ahora genera una ValueError si `map` no es una lista de ints.
8.0.0 | `encoding` ahora acepta `null`.

### Ejemplos

Ejemplo #1 Ejemplo de `map`

    <?php
    $convmap = array (
       int start_code1, int end_code1, int offset1, int mask1,
       int start_code2, int end_code2, int offset2, int mask2,
       // ........
       int start_codeN, int end_codeN, int offsetN, int maskN );
    // Especificar valor Unicode para start_codeN y end_codeN
    // Añadir offsetN al valor y realizar 'AND' a nivel de bits con maskN,
    // luego convertir el valor a referencia numérica de cadena.
    ?>

Ejemplo #2 Ejemplo de `map` para escapar cadena JavaScript

    <?php
    function escape_javascript_string($str) {
      $map = [
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,0,0, // 49
              0,0,0,0,0,0,0,0,1,1,
              1,1,1,1,1,0,0,0,0,0,
              0,0,0,0,0,0,0,0,0,0,
              0,0,0,0,0,0,0,0,0,0,
              0,1,1,1,1,1,1,0,0,0, // 99
              0,0,0,0,0,0,0,0,0,0,
              0,0,0,0,0,0,0,0,0,0,
              0,0,0,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1, // 149
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1, // 199
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1, // 249
              1,1,1,1,1,1,1, // 255
              ];
      // Codificación de caracteres es UTF-8
      $mblen = mb_strlen($str, 'UTF-8');
      $utf32 = bin2hex(mb_convert_encoding($str, 'UTF-32', 'UTF-8'));
      for ($i=0, $encoded=''; $i < $mblen; $i++) {
          $u = substr($utf32, $i*8, 8);
          $v = base_convert($u, 16, 10);
          if ($v < 256 && $map[$v]) {
            $encoded .= '\\x'.substr($u, 6,2);
          } else if ($v == 2028) {
            $encoded .= '\\u2028';
          } else if ($v == 2029) {
            $encoded .= '\\u2029';
          } else {
            $encoded .= mb_convert_encoding(hex2bin($u), 'UTF-8', 'UTF-32');
          }
       }
       return $encoded;
    }

      // Datos de prueba
    $convmap = [ 0x0, 0xffff, 0, 0xffff ];
    $msg = '';
    for ($i=0; $i < 1000; $i++) {
      // chr() no puede generar datos UTF-8 correctos mayores que 128, usar mb_decode_numericentity().
      $msg .= mb_decode_numericentity('&#'.$i.';', $convmap, 'UTF-8');
    }

    // var_dump($msg);
    var_dump(escape_javascript_string($msg));

### Ver también

- mb_encode_numericentity() - Codifica caracteres a referencia numérica HTML

# mb_detect_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_detect_encoding — Detectar la codificación de caracteres

### Descripción

function mb_detect_encoding(string `$string`, array|string|null `$encodings` = `null`, bool `$strict` = `false`): string|false

Detectar la codificación de caracteres más probable para la string `string` desde una lista de candidatos.

A partir de PHP 8.1, esta función utiliza heurística para detectar cuál de las codificaciones de texto válidas en la lista especificada tiene más probabilidades de ser correcta y puede no estar en el orden de `encodings` proporcionado.

La detección automática del juego de caracteres previsto nunca es totalmente fiable; sin información adicional, es similar a descifrar una cadena cifrada sin la clave. Siempre es preferible utilizar una indicación del juego de caracteres almacenado o transmitido con los datos, como el encabezado HTTP "Content-Type".

Esta función se utiliza principalmente con codificaciones multibyte, donde no todas las secuencias de bytes forman una cadena válida. Si la cadena de entrada contiene una secuencia de este tipo, esta codificación será rechazada.

Advertencia

# El resultado no es fiable

El nombre de esta función es engañoso, realiza una «suposición» en lugar de una «detección».

Las suposiciones están lejos de ser precisas, y por lo tanto, esta función no permite detectar de manera fiable la codificación correcto de los caracteres.

### Parámetros

`string`

  El string que será inspeccionado.

`encodings`

  Una lista de codificaciones de caracteres a probar. Esta lista puede ser especificada como un array de string, o como un string único separado por comas.

  Si `encodings` es omitido o `null`, el será utilizado el detect_order actual (definido con la opción de configuración mbstring.detect_order, o la función mb_detect_order()).

`strict`

  Controla el comportamiento cuando `string` no es válido en ninguno de los `encodings` listados. Si `strict` está definido como `false`, se devolverá la codificación más coincidente; si `strict` está definido como `true`, devolverá `false`.

  El valor por omisión de `strict` puede ser definido con la opción de configuración mbstring.strict_detection.

### Valores devueltos

La codificación caracteres detectado, o `false` si la cadena no es válida en ninguna de las codificaciones listadas.

### Historial de cambios

Versión | Descripción
--- | ---
8.2.0 | mb_detect_encoding() ya no devolverá las siguientes codificaciones que no sean de texto: `"Base64"`, `"QPrint"`, `"UUencode"`, `"HTML entities"`, `"7 bit"` y `"8 bit"`.

### Ejemplos

Ejemplo #1 Ejemplo con mb_detect_encoding()

    <?php

    $str = "\x95\xB6\x8E\x9A\x83\x52\x81\x5B\x83\x68";

    // Detecta la codificación con el detect_order actual
    var_dump(mb_detect_encoding($str));

    // "auto" es modificado según mbstring.language
    var_dump(mb_detect_encoding($str, "auto"));

    // Especifica el parámetro "encodings" con una lista separada por comas
    var_dump(mb_detect_encoding($str, "JIS, eucjp-win, sjis-win"));

    // Uso de un array para especificar el parámetro "encodings"
    $encodings = [
      "ASCII",
      "JIS",
      "EUC-JP"
    ];
    var_dump(mb_detect_encoding($str, $encodings));
    ?>

El ejemplo anterior mostrará:

    string(5) "ASCII"
    string(5) "ASCII"
    string(8) "SJIS-win"
    string(5) "ASCII"

Ejemplo #2 Efecto del parámetro `strict`

    <?php
    // 'áéóú' codificado en ISO-8859-1
    $str = "\xE1\xE9\xF3\xFA";

    // La cadena no válica en ASCII ni UTF-8, pero UTF-8 se considera una coincidencia más cercana
    var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8'], false));
    var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8'], true));

    // Si se encuentra una codificación válida, el parámetro "strict" no cambia el resultado
    var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8', 'ISO-8859-1'], false));
    var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8', 'ISO-8859-1'], true));
    ?>

El ejemplo anterior mostrará:

    string(5) "UTF-8"
    bool(false)
    string(10) "ISO-8859-1"
    string(10) "ISO-8859-1"

En ciertos casos, la misma secuencia de bytes puede formar una cadena válida en diferentes codificaciones de caracteres, y es imposible determinar cuál interpretación era prevista. Un ejemplo, entre otros, la secuencia de bytes "\xC4\xA2" podría ser:

- "Ä¢" (U+00C4 LATIN CAPITAL LETTER A WITH DIAERESIS seguido de U+00A2 CENT SIGN) codificado en ISO-8859-1, ISO-8859-15, o Windows-1252
- "ФЂ" (U+0424 CYRILLIC CAPITAL LETTER EF seguido de U+0402 CYRILLIC CAPITAL LETTER DJE) codificado en ISO-8859-5
- "Ģ" (U+0122 LATIN CAPITAL LETTER G WITH CEDILLA) codificado en UTF-8

Ejemplo #3 Efecto del orden cuando coinciden múltiples codificaciones

    <?php
    $str = "\xC4\xA2";

    // La cadena es válida en las tres codificaciones, pero no siempre devolverá el primero de la lista
    var_dump(mb_detect_encoding($str, ['UTF-8']));
    var_dump(mb_detect_encoding($str, ['UTF-8', 'ISO-8859-1', 'ISO-8859-5'])); // A partir de PHP 8.1 esto devolverá ISO-8859-1 en vez de UTF-8
    var_dump(mb_detect_encoding($str, ['ISO-8859-1', 'ISO-8859-5', 'UTF-8']));
    var_dump(mb_detect_encoding($str, ['ISO-8859-5', 'UTF-8', 'ISO-8859-1']));
    ?>

El ejemplo anterior mostrará:

    string(5) "UTF-8"
    string(10) "ISO-8859-1"
    string(10) "ISO-8859-1"
    string(10) "ISO-8859-5"

### Ver también

- mb_detect_order() - Lee/modifica el orden de detección de codificaciones

# mb_detect_order

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_detect_order — Lee/modifica el orden de detección de codificaciones

### Descripción

function mb_detect_order(array|string|null `$encoding` = `null`): array|bool

Reemplaza el orden de detección de codificaciones actual por `encoding`.

### Parámetros

`encoding`

  `encoding` es un array, o una lista de codificaciones separadas por comas. Ver las codificaciones soportadas.

  Si `encoding` es omitido o `null`, mb_detect_order() devuelve el orden de detección de codificaciones actual en un array.

  Esta configuración afecta a las funciones mb_detect_encoding() y mb_send_mail().

  Actualmente, `mbstring` soporta los siguientes filtros de detección. Si una secuencia de bytes es inválida para uno de los siguientes filtros, la detección fallará.

  `UTF-8`, `UTF-7`, `ASCII`, `EUC-JP`,`SJIS`, `eucJP-win`, `SJIS-win`, `JIS`, `ISO-2022-JP`

  Para `ISO-8859-*`, `mbstring` siempre detecta `ISO-8859-*`.

  Para `UTF-16`, `UTF-32`, `UCS2` y `UCS4` la detección siempre fallará.

### Valores devueltos

Al definir el orden de detección de codificación, `true` es devuelto en caso de éxito o `false` en caso de fallo.

Al obtener el orden de detección de codificación, un array ordenado de codificaciones es devuelto.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `encoding` ahora acepta `null`.

### Ejemplos

Ejemplo #1 Ejemplo con mb_detect_order()

    <?php
    /* Reemplaza el orden de detección por una lista enumerada */
    mb_detect_order("eucjp-win,sjis-win,UTF-8");

    /* Reemplaza el orden de detección por un array */
    $ary[] = "ASCII";
    $ary[] = "JIS";
    $ary[] = "EUC-JP";
    mb_detect_order($ary);

    /* Muestra el orden de detección actual */
    echo implode(", ", mb_detect_order());
    ?>

Ejemplo #2 Ejemplo de orden de detección innecesario

    ; Siempre detectado como ISO-8859-1
    detect_order = ISO-8859-1, UTF-8

    ; Siempre detectado como UTF-8, desde que los valores ASCII/UTF-7
    ; son válidos para UTF-8
    detect_order = UTF-8, ASCII, UTF-7

### Ver también

- mb_internal_encoding() - Lee/modifica la codificación interna
- mb_http_input() - Detecta el tipo de codificación de caracteres HTTP
- mb_http_output() - Lee/modifica la codificación de visualización
- mb_send_mail() - Envía un correo electrónico codificado

# mb_encode_mimeheader

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_encode_mimeheader — Codifica una cadena para un encabezado MIME

### Descripción

function mb_encode_mimeheader(
string `$string`,
?string `$charset` = `null`,
?string `$transfer_encoding` = `null`,
string `$newline` = "\r\n",
int `$indent` = 0
): string

Codifica una string `string` dada en un encabezado MIME.

### Parámetros

`string`

  La string a codificar. Su codificación debería ser idéntica a mb_internal_encoding().

`charset`

  `charset` es el nombre de la codificación utilizada por la cadena `string`. El valor por omisión se determina mediante los parámetros actuales de NLS (`mbstring.language`).

`transfer_encoding`

  `transfer_encoding` es la codificación de transferencia. Puede ser `"B"` (Base64) o `"Q"` (Quoted-Printable). Por omisión, es `"B"`.

`newline`

  `newline` especifica los finales de línea (EOF: `end-of-line`) utilizados por mb_encode_mimeheader() para formatear la cadena (una » RFC define la longitud de una cadena a partir de la cual se debe añadir un final de línea. La longitud actual es 74 caracteres). El valor por omisión es `"\r\n"` (CRLF).

`indent`

  Indentación de la primera línea (número de caracteres en el encabezado antes de `string`).

### Valores devueltos

Una versión convertida de la string en ASCII.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Los octetos `NUL` (0) ya no se eliminan durante la codificación en Quoted-Printable, sino que se codifican como `=00`.
8.0.0 | `charset` y `transfer_encoding` ahora son nulos.

### Ejemplos

Ejemplo #1 Ejemplo con mb_encode_mimeheader()

    <?php
    $name = "太郎"; // kanji
    $mbox = "kru";
    $doma = "gtinn.mon";
    $addr = '"' . addcslashes(mb_encode_mimeheader($name, "UTF-7", "Q"), '"') . '" <' . $mbox . "@" . $doma . ">";
    echo $addr;
    ?>

El ejemplo anterior mostrará:

    "=?UTF-7?Q?+WSqQzg-?=" <kru@gtinn.mon>

### Notas

> Nota:

> Esta función no está diseñada para cortar líneas en medio de palabras. Este comportamiento puede añadir espacios no deseados en una palabra de la cadena original.

### Ver también

- mb_decode_mimeheader() - Decodifica un encabezado MIME

# mb_encode_numericentity

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_encode_numericentity — Codifica caracteres a referencia numérica HTML

### Descripción

function mb_encode_numericentity(
string `$string`,
array `$map`,
?string `$encoding` = `null`,
bool `$hex` = `false`
): string

Convierte los códigos de caracteres especificados en string `string` de código de caracteres a referencia numérica de caracteres HTML.

### Parámetros

`string`

  El string que se está codificando.

`map`

  `map` es un array que especifica el área de código a convertir.

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.
`hex`

  Si la referencia de entidad devuelta debe estar en notación hexadecimal (de lo contrario, está en notación decimal).

### Valores devueltos

El string convertido.

### Errores/Excepciones

Lanza una ValueError si `map` no es una lista de ints.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | mb_encode_numericentity() ahora lanza una ValueError si `map` no es una lista de ints.
8.0.0 | `encoding` ahora acepta `null`.

### Ejemplos

Ejemplo #1 `map` ejemplo

    <?php
    $convmap = array (
     int start_code1, int end_code1, int offset1, int mask1,
     int start_code2, int end_code2, int offset2, int mask2,
     ........
     int start_codeN, int end_codeN, int offsetN, int maskN );
    // Especificar valor Unicode para start_codeN y end_codeN
    // Añadir offsetN al valor y hacer un 'AND' a nivel de bits con maskN, luego
    // convierte el valor a referencia numérica de string.
    ?>

Ejemplo #2 mb_encode_numericentity() ejemplo

    <?php

    $str = "aAæÆあア𩸽";

    /* Convertir todos los caracteres UTF8 hasta 4 bytes a referencia numérica de caracteres HTML */
    $convmap = [0, 0x1FFFFF, 0, 0x10FFFF];
    var_dump(mb_encode_numericentity($str, $convmap, "utf8"));

    /* Convertir solo los caracteres UTF8 de 2 bytes y 4 bytes a referencia numérica de caracteres HTML */
    $convmap = [
        0x80, 0x7FF, 0, 0x10FFFF,
        0x10000, 0x1FFFFF, 0, 0x10FFFF,
    ];
    var_dump(mb_encode_numericentity($str, $convmap, "utf8"));
    ?>

El ejemplo anterior mostrará:

    string(46) "&#97;&#65;&#230;&#198;&#12354;&#12450;&#40509;"
    string(28) "aA&#230;&#198;あア&#40509;"

### Ver también

- mb_decode_numericentity() - Decodificar referencia numérica de cadena HTML a carácter

# mb_encoding_aliases

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mb_encoding_aliases — Obtiene los alias de un tipo de codificación conocido

### Descripción

function mb_encoding_aliases(string `$encoding`): array

Devuelve un array de alias para un tipo conocido de codificación.

### Parámetros

`encoding`

  El tipo de codificación a verificar, para los alias.

### Valores devueltos

Devuelve un array indexado numéricamente de alias de codificación. o `false` si ocurre un error

### Errores/Excepciones

Genera un ValueError si `encoding` es desconocido.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Si el argumento `encoding` es desconocido, ahora se genera un ValueError; previamente, se emitía un `E_WARNING` y la función devolvía `false`.

### Ejemplos

Ejemplo #1 Ejemplo con mb_encoding_aliases()

    <?php
    $encoding        = 'ASCII';
    $known_encodings = mb_list_encodings();

    if (in_array($encoding, $known_encodings)) {

        $aliases = mb_encoding_aliases($encoding);
        print_r($aliases);

    } else {

        echo "Codificación ($encoding) desconocida.\n";

    }
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => ANSI_X3.4-1968
        [1] => iso-ir-6
        [2] => ANSI_X3.4-1986
        [3] => ISO_646.irv:1991
        [4] => US-ASCII
        [5] => ISO646-US
        [6] => us
        [7] => IBM367
        [8] => cp367
        [9] => csASCII
    )

### Ver también

- mb_list_encodings() - Devuelve un array que contiene todos los encodings soportados

# mb_ereg

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg — Búsqueda por expresión regular con soporte para caracteres multibyte

### Descripción

function mb_ereg(string `$pattern`, string `$string`, array `&$matches` = `null`): bool

Búsqueda por expresión regular con soporte para caracteres multibyte.

### Parámetros

`pattern`

  El patrón de búsqueda.

`string`

  La cadena sobre la que se realiza la búsqueda.

`matches`

  Si se encuentran coincidencias para las subcadenas entre paréntesis de `pattern` y si la función es llamada con el tercer argumento `matches`, las coincidencias serán almacenadas en los elementos del array `matches`. Si no se encuentra ninguna coincidencia, `matches` tendrá como valor un array vacío.

  $matches[1] contendrá la subcadena que comienza en la primera paréntesis izquierdo; $matches[2] contendrá la subcadena que comienza en la segunda, y así sucesivamente. $matches[0] contendrá una copia de la cadena completa coincidente.

### Valores devueltos

Devuelve si se ha encontrado una coincidencia de `pattern` en `string`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función devuelve ahora `true` en caso de éxito. Anteriormente, devolvía la longitud en bytes de la cadena encontrada, si se encontraba una coincidencia para `pattern` en `string` y si se proporcionaba `matches`. Si el parámetro opcional `matches` no se proporcionaba o si la longitud de la cadena coincidente era `0`, esta función devolvía `1`.
7.1.0 | mb_ereg() ahora asignará `matches` a un array vacío, si no hay coincidencias. Anteriormente, los `matches` no se modificaban en este caso.

### Notas

> Nota: La codificación interna o la codificación de caracteres especificada por mb_regex_encoding() se utilizará como codificación de caracteres para esta función.

### Ver también

- mb_regex_encoding() - Define/Recupera la codificación de caracteres para las expresiones regulares multioctetos
- mb_eregi() - Expresión regular insensible a mayúsculas/minúsculas con soporte para caracteres multioctetos

# mb_ereg_match

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_match — Expresión regular POSIX para strings multibyte

### Descripción

function mb_ereg_match(string `$pattern`, string `$string`, ?string `$options` = `null`): bool

Ejecuta la expresión regular POSIX para strings multibyte.

> Nota: `pattern` se asocia únicamente al inicio de `string`.

### Parámetros

`pattern`

  La expresión regular.

`string`

  El string a evaluar.

`options`

  La opción de búsqueda. Para más explicaciones, consulte mb_regex_set_options().

### Valores devueltos

`string` retorna `true` si `string` verifica la expresión regular `pattern`, `false` en caso contrario.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `options` ahora es nullable.

### Notas

> Nota: La codificación interna o la codificación de caracteres especificada por mb_regex_encoding() se utilizará como codificación de caracteres para esta función.

### Ver también

- mb_regex_encoding() - Define/Recupera la codificación de caracteres para las expresiones regulares multioctetos
- mb_ereg() - Búsqueda por expresión regular con soporte para caracteres multibyte

# mb_ereg_replace

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_replace — Reemplaza segmentos de cadena mediante expresiones regulares

### Descripción

function mb_ereg_replace(
string `$pattern`,
string `$replacement`,
string `$string`,
?string `$options` = `null`
): string|false|null

Busca en la cadena `string` las ocurrencias que coinciden con el patrón `pattern`, y las reemplaza con el texto de reemplazo `replacement`.

### Parámetros

`pattern`

  La expresión regular.

  Los caracteres multi-octeto pueden ser utilizados en `pattern`.

`replacement`

  El texto de reemplazo.

`string`

  La cadena a analizar.

`options`
  La opción de búsqueda. Para más explicaciones, consulte mb_regex_set_options().

### Valores devueltos

La cadena resultante en caso de éxito, o `false` si ocurre un error. Si `string` no es válido para la codificación actual, `null` es devuelto.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `options` ahora es nullable.
7.1.0 | Esta función verifica si `string` es válido para la codificación actual.
7.1.0 | El modificador `e` ahora está obsoleto.

### Notas

> Nota: La codificación interna o la codificación de caracteres especificada por mb_regex_encoding() se utilizará como codificación de caracteres para esta función.

Advertencia

Nunca utilice el modificador `e` con datos de entrada no confiables. No se realizará ningún escape automático (como se conoce de preg_replace()). No tener esto en cuenta probablemente creará vulnerabilidades de ejecución remota de código en la aplicación.

### Ver también

- mb_regex_encoding() - Define/Recupera la codificación de caracteres para las expresiones regulares multioctetos
- mb_eregi_replace() - Expresión regular con soporte para caracteres multibyte, sin distinción de mayúsculas y minúsculas

# mb_ereg_replace_callback

(PHP 5 >= 5.4.1, PHP 7, PHP 8)

mb_ereg_replace_callback — Buscar y reemplazar mediante expresión regular con soporte multi byte utilizando una función de devolución de llamada

### Descripción

function mb_ereg_replace_callback(
string `$pattern`,
callable `$callback`,
string `$string`,
?string `$options` = `null`
): string|false|null

Busca los `string` que coinciden con el argumento `pattern`, luego reemplaza los textos que coinciden con el retorno de la función `callback`.

El comportamiento de esta función es casi idéntico a mb_ereg_replace(), a excepción de que el argumento `replacement` debe especificar una función de devolución de llamada `callback`.

### Parámetros

`pattern`

  La expresión regular.

  Los caracteres multi byte pueden ser utilizados en el `pattern`.

`callback`

  Un callback que será llamado y se le pasará un array de elementos coincidentes en la cadena de caracteres `string`. El callback debe retornar la cadena reemplazada.

  Con frecuencia será necesario utilizar la función `callback` para mb_ereg_replace_callback() solo una vez. En este caso se pueden utilizar las funciones anónimas para declarar una función de devolución de llamada al momento de llamar a la función mb_ereg_replace_callback(). Al hacerlo de esta manera se tiene toda la información necesaria para la llamada de la función en un solo lugar, lo que permite evitar saturar el espacio de nombres de las funciones con un callback de función que no se utiliza en otro lugar.

`string`

  El string que debe ser verificado.

`options`

  La opción de búsqueda. Para más explicaciones, consulte mb_regex_set_options().

### Valores devueltos

Retorna un string en caso de éxito, o `false` en caso de error. Si `string` no es válido para el codificación actual, `null` es retornado.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `options` ahora es nullable.
7.1.0 | Esta función verifica si `string` es válido para la codificación actual.

### Ejemplos

Ejemplo #1 Ejemplo con mb_ereg_replace_callback()

    <?php
    // este texto fue utilizado en 2002
    // se desea actualizarlo para 2003
    $text = "April fools day is 04/01/2002\n";
    $text.= "Last christmas was 12/24/2001\n";
    // la función de devolución de llamada
    function next_year($matches)
    {
      // como de costumbre: $matches[0] es la coincidencia completa
      // $matches[1] la coincidencia para el primer subpatrón
      // encerrado en '(...)' y así sucesivamente
      return $matches[1].($matches[2]+1);
    }
    echo mb_ereg_replace_callback(
                "(\d{2}/\d{2}/)(\d{4})",
                "next_year",
                $text);

    ?>

El ejemplo anterior mostrará:

    April fools day is 04/01/2003
    Last christmas was 12/24/2002

Ejemplo #2 mb_ereg_replace_callback() utilizando funciones anónimas

    <?php
    // este texto fue utilizado en 2002
    // se desea actualizarlo para 2003
    $text = "April fools day is 04/01/2002\n";
    $text.= "Last christmas was 12/24/2001\n";

    echo mb_ereg_replace_callback(
                "(\d{2}/\d{2}/)(\d{4})",
                function ($matches) {
                   return $matches[1].($matches[2]+1);
                },
                $text);
    ?>

### Notas

> Nota: La codificación interna o la codificación de caracteres especificada por mb_regex_encoding() se utilizará como codificación de caracteres para esta función.

### Ver también

- mb_regex_encoding() - Define/Recupera la codificación de caracteres para las expresiones regulares multioctetos
- mb_ereg_replace() - Reemplaza segmentos de cadena mediante expresiones regulares
- Funciones anónimas

# mb_ereg_search

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search — Búsqueda por expresión regular multioctets

### Descripción

function mb_ereg_search(?string `$pattern` = `null`, ?string `$options` = `null`): bool

Búsqueda por expresión regular multioctets.

### Parámetros

`pattern`

  El patrón de búsqueda.

`options`

  La opción de búsqueda. Para más explicaciones, consúltese mb_regex_set_options().

### Valores devueltos

mb_ereg_search() devuelve `true` si la cadena multioctets coincide con el patrón de expresión regular, o bien `false` en caso contrario. La cadena a estudiar ha sido configurada con la función mb_ereg_search_init(). Si el patrón `pattern` no está especificado, se utilizará el anterior.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `pattern` y `options` ahora son nulos.

### Notas

> Nota: La codificación interna o la codificación de caracteres especificada por mb_regex_encoding() se utilizará como codificación de caracteres para esta función.

### Ver también

- mb_regex_encoding() - Define/Recupera la codificación de caracteres para las expresiones regulares multioctetos
- mb_ereg_search_init() - Configura las cadenas y las expresiones regulares para el soporte de caracteres multioctetos

# mb_ereg_search_getpos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_getpos — Devuelve la posición de inicio para la siguiente comparación de una expresión regular

### Descripción

function mb_ereg_search_getpos(): int

Devuelve la posición de inicio para la siguiente coincidencia de una expresión regular.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

mb_ereg_search_getpos() devuelve el punto de inicio de la comparación de una expresión regular para mb_ereg_search(), mb_ereg_search_pos(), mb_ereg_search_regs(). La posición está representada mediante bytes desde la cabeza del string.

### Notas

> Nota: La codificación interna o la codificación de caracteres especificada por mb_regex_encoding() se utilizará como codificación de caracteres para esta función.

### Ver también

- mb_regex_encoding() - Define/Recupera la codificación de caracteres para las expresiones regulares multioctetos
- mb_ereg_search_setpos() - Selecciona el punto de partida para la búsqueda mediante expresión regular

# mb_ereg_search_getregs

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_getregs — Lee el último segmento de cadena multioctets que coincide con el patrón

### Descripción

function mb_ereg_search_getregs(): array|false

Lee el último segmento de cadena multioctets que coincide con el patrón.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array que incluye todas las sub-caenas que han sido encontradas por mb_ereg_search(), mb_ereg_search_pos() y mb_ereg_search_regs(). Si se ha encontrado una solución, el primer elemento será la sub-caena encontrada, el segundo representará la primera paréntesis capturante, el tercero representará la segunda paréntesis capturante, etc. Esta función devuelve `false` en caso de error.

### Notas

> Nota: La codificación interna o la codificación de caracteres especificada por mb_regex_encoding() se utilizará como codificación de caracteres para esta función.

### Ver también

- mb_regex_encoding() - Define/Recupera la codificación de caracteres para las expresiones regulares multioctetos
- mb_ereg_search_init() - Configura las cadenas y las expresiones regulares para el soporte de caracteres multioctetos

# mb_ereg_search_init

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_init — Configura las cadenas y las expresiones regulares para el soporte de caracteres multioctetos

### Descripción

function mb_ereg_search_init(string `$string`, ?string `$pattern` = `null`, ?string `$options` = `null`): bool

mb_ereg_search_init() configura `string` y `pattern` para soportar expresiones regulares multioctetos. Estos valores son utilizados por mb_ereg_search(), mb_ereg_search_pos() y mb_ereg_search_regs().

### Parámetros

`string`

  La cadena a buscar.

`pattern`

  La máscara de búsqueda.

`options`

  La opción de búsqueda. Para más explicaciones, consulte mb_regex_set_options().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `pattern` y `options` ahora son nulos.

### Notas

> Nota: La codificación interna o la codificación de caracteres especificada por mb_regex_encoding() se utilizará como codificación de caracteres para esta función.

### Ver también

- mb_regex_encoding() - Define/Recupera la codificación de caracteres para las expresiones regulares multioctetos
- mb_ereg_search_regs() - Retorna el segmento de cadena encontrado por una expresión regular multioctets

# mb_ereg_search_pos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_pos — Retorna la posición y la longitud del segmento de string que cumple con el patrón de expresión regular

### Descripción

function mb_ereg_search_pos(?string `$pattern` = `null`, ?string `$options` = `null`): array|false

Retorna la posición y la longitud del segmento de string que cumple con el patrón de expresión regular.

El string a utilizar es especificado por mb_ereg_search_init(). Si no es especificado, se utilizará el anterior.

### Parámetros

`pattern`

  El patrón de búsqueda.

`options`

  La opción de búsqueda. Para más explicaciones, consulte mb_regex_set_options().

### Valores devueltos

Un array que contiene dos elementos. El primer elemento es la posición, en bytes, donde comienza la coincidencia relativamente al inicio del string buscado, y el segundo elemento es la longitud, en bytes, de la coincidencia.

Si ocurre un error, `false` será retornado.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `pattern` y `options` ahora son nulos.

### Notas

> Nota: La codificación interna o la codificación de caracteres especificada por mb_regex_encoding() se utilizará como codificación de caracteres para esta función.

### Ver también

- mb_regex_encoding() - Define/Recupera la codificación de caracteres para las expresiones regulares multioctetos
- mb_ereg_search_init() - Configura las cadenas y las expresiones regulares para el soporte de caracteres multioctetos

# mb_ereg_search_regs

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_regs — Retorna el segmento de cadena encontrado por una expresión regular multioctets

### Descripción

function mb_ereg_search_regs(?string `$pattern` = `null`, ?string `$options` = `null`): array|false

Retorna el segmento de cadena encontrado por una expresión regular multioctets.

### Parámetros

`pattern`

  La máscara de búsqueda.

`options`

  La opción de búsqueda. Para más explicaciones, consulte mb_regex_set_options().

### Valores devueltos

mb_ereg_search_regs() ejecuta la expresión regular `pattern`, y, si un segmento de cadena coincide, lo retorna en un array, cuyo primer elemento es el segmento de cadena encontrado, el segundo el contenido de la primera paréntesis capturante, el tercero el contenido de la segunda paréntesis capturante, etc. La función retorna `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `pattern` y `options` ahora son nulos.

### Notas

> Nota: La codificación interna o la codificación de caracteres especificada por mb_regex_encoding() se utilizará como codificación de caracteres para esta función.

### Ver también

- mb_regex_encoding() - Define/Recupera la codificación de caracteres para las expresiones regulares multioctetos
- mb_ereg_search_init() - Configura las cadenas y las expresiones regulares para el soporte de caracteres multioctetos

# mb_ereg_search_setpos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_setpos — Selecciona el punto de partida para la búsqueda mediante expresión regular

### Descripción

function mb_ereg_search_setpos(int `$offset`): bool

mb_ereg_search_setpos() selecciona el punto de partida para la búsqueda que va a realizar la función mb_ereg_search().

### Parámetros

`offset`

  La posición a definir. Si es negativa, se cuenta desde el final de la cadena.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
7.1.0 | Se ha añadido el soporte para un `offset` negativo.

### Notas

> Nota: La codificación interna o la codificación de caracteres especificada por mb_regex_encoding() se utilizará como codificación de caracteres para esta función.

### Ver también

- mb_regex_encoding() - Define/Recupera la codificación de caracteres para las expresiones regulares multioctetos
- mb_ereg_search_init() - Configura las cadenas y las expresiones regulares para el soporte de caracteres multioctetos

# mb_eregi

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_eregi — Expresión regular insensible a mayúsculas/minúsculas con soporte para caracteres multioctetos

### Descripción

function mb_eregi(string `$pattern`, string `$string`, array `&$matches` = `null`): bool

Ejecuta la expresión regular insensible a mayúsculas/minúsculas con soporte para caracteres multioctetos.

### Parámetros

`pattern`

  La expresión regular.

`string`

  La cadena a buscar.

`matches`

  Si al menos una secuencia es encontrada (eventualmente en los paréntesis capturantes de `pattern`), y la función es llamada con un tercer argumento `matches`, los resultados serán almacenados en `matches`.

  $matches[1] contendrá el primer paréntesis capturante (aquel que comienza primero), $matches[2] contendrá el segundo paréntesis capturante (aquel que comienza después del primero), y así sucesivamente. $matches[0] contiene una copia de la cadena.

### Valores devueltos

Devuelve si una correspondencia de `pattern` ha sido encontrada en `string`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función devuelve ahora `true` en caso de éxito. Anteriormente, devolvía la longitud de octeto de la cadena encontrada, si una correspondencia para `pattern` era encontrada en `string` y que `matches` era proporcionado. Si el parámetro opcional `matches` no era proporcionado o que la longitud de la cadena correspondiente era `0`, esta función devolvía `1`.
7.1.0 | mb_eregi() definirá ahora `matches` como un array vacío, si no hay ninguna correspondencia. Anteriormente, `matches` no era modificado en este caso.

### Notas

> Nota: La codificación interna o la codificación de caracteres especificada por mb_regex_encoding() se utilizará como codificación de caracteres para esta función.

### Ver también

- mb_regex_encoding() - Define/Recupera la codificación de caracteres para las expresiones regulares multioctetos
- mb_ereg() - Búsqueda por expresión regular con soporte para caracteres multibyte

# mb_eregi_replace

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_eregi_replace — Expresión regular con soporte para caracteres multibyte, sin distinción de mayúsculas y minúsculas

### Descripción

function mb_eregi_replace(
string `$pattern`,
string `$replacement`,
string `$string`,
?string `$options` = `null`
): string|false|null

Analiza la cadena `string` con el patrón de expresión regular `pattern`, luego reemplaza el texto encontrado por `replacement`.

### Parámetros

`pattern`

  La expresión regular. Pueden utilizarse caracteres multibyte. La distinción de mayúsculas y minúsculas será ignorada.

`replacement`

  El texto de sustitución.

`string`

  La cadena a buscar.

`options`
  Las opciones de búsqueda. Ver mb_regex_set_options() para más detalles.

### Valores devueltos

La cadena resultante, o `false` si ocurre un error. Si `string` no es válido para la codificación actual, se devuelve `null`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `options` ahora es nullable.
7.1.0 | Esta función verifica si `string` es válido para la codificación actual.
7.1.0 | El modificador `e` ahora está obsoleto.

### Notas

> Nota: La codificación interna o la codificación de caracteres especificada por mb_regex_encoding() se utilizará como codificación de caracteres para esta función.

Advertencia

Nunca utilice el modificador `e` con datos de entrada no confiables. No se realizará ningún escape automático (como se conoce de preg_replace()). No tener esto en cuenta probablemente creará vulnerabilidades de ejecución remota de código en la aplicación.

### Ver también

- mb_regex_encoding() - Define/Recupera la codificación de caracteres para las expresiones regulares multioctetos
- mb_ereg_replace() - Reemplaza segmentos de cadena mediante expresiones regulares

# mb_get_info

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_get_info — Lee la configuración interna de la extensión mbstring

### Descripción

function mb_get_info(string `$type` = "all"): array|string|int|false|null

mb_get_info() lee la configuración interna de la extensión mbstring.

### Parámetros

`type`

  Si `type` no se solicita explícitamente, o si vale `"all"`, `"all"`, `"internal_encoding"`, `"http_input"`, `"http_output"`, `"http_output_conv_mimetypes"`, `"mail_charset"`, `"mail_header_encoding"`, `"mail_body_encoding"`, `"illegal_chars"`, `"encoding_translation"`, `"language"`, `"detect_order"`, `"substitute_character"` y `"strict_detection"` se devolverá.

  Si `type` se especifica como `"internal_encoding"`, `"http_input"`, `"http_output"`, `"http_output_conv_mimetypes"`, `"mail_charset"`, `"mail_header_encoding"`, `"mail_body_encoding"`, `"illegal_chars"`, `"encoding_translation"`, `"language"`, `"detect_order"`, `"substitute_character"` o `"strict_detection"` se devolverá el parámetro especificado.

### Valores devueltos

Un array de información si `type` no se especifica, de lo contrario, un `type` específico, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Los `type`s `"func_overload"` y `"func_overload_list"` ya no son soportados.

### Ver también

- mb_regex_encoding() - Define/Recupera la codificación de caracteres para las expresiones regulares multioctetos
- mb_http_output() - Lee/modifica la codificación de visualización

# mb_http_input

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_http_input — Detecta el tipo de codificación de caracteres HTTP

### Descripción

function mb_http_input(?string `$type` = `null`): array|string|false

Detecta el tipo de codificación de caracteres HTTP.

### Parámetros

`type`

  El argumento `type` especifica el tipo de entrada HTTP. Puede tomar uno de los siguientes valores: `"G"` para GET, `"P"` para POST, `"C"` para COOKIE, `"S"` para string, `"L"` para la lista, `"I"` para la lista completa (retornará array). Si `type` es omitido, tomará el valor del último tipo utilizado.

### Valores devueltos

El nombre de la codificación de caracteres según `type`, o un array de nombres de juegos de caracteres, si `type` es `"I"`. Si mb_http_input() no procesa la entrada HTTP especificada, retornará `false`.

### Errores/Excepciones

Levanta una excepción ValueError si `type` es inválido.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | mb_http_input() ahora levanta una excepción ValueError si `type` es inválido.
8.0.0 | `type` ahora es nullable.

### Ver también

- mb_internal_encoding() - Lee/modifica la codificación interna
- mb_http_output() - Lee/modifica la codificación de visualización
- mb_detect_order() - Lee/modifica el orden de detección de codificaciones

# mb_http_output

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_http_output — Lee/modifica la codificación de visualización

### Descripción

function mb_http_output(?string `$encoding` = `null`): string|bool

Lee/modifica la codificación de visualización. La visualización después de la llamada a esta función será convertida desde la codificación interna hacia la codificación proporcionada por el argumento `encoding`.

### Parámetros

`encoding`

  Si `encoding` es proporcionado, mb_http_output() utilizará la codificación `encoding` para las visualizaciones HTTP: los caracteres que serán enviados a los clientes web serán convertidos al juego de caracteres `encoding`.

  Si `encoding` es omitido, mb_http_output() devuelve la codificación de visualización actual.

### Valores devueltos

Si el argumento `encoding` es omitido, mb_http_output() devuelve la codificación HTTP actual. De lo contrario, Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Levanta una excepción ValueError si `encoding` contiene octetos nulos.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | mb_http_output() levanta ahora una excepción ValueError si `encoding` contiene octetos nulos.
8.0.0 | `encoding` ahora acepta `null`.

### Ver también

- mb_internal_encoding() - Lee/modifica la codificación interna
- mb_http_input() - Detecta el tipo de codificación de caracteres HTTP
- mb_detect_order() - Lee/modifica el orden de detección de codificaciones

# mb_internal_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_internal_encoding — Lee/modifica la codificación interna

### Descripción

function mb_internal_encoding(?string `$encoding` = `null`): string|bool

Lee/modifica la codificación interna.

### Parámetros

`encoding`

  `encoding` se utiliza durante las conversiones de strings provenientes y dirigidas hacia la web, así como durante la creación de strings con el módulo mbstring. Se debe tener en cuenta que la codificación interna es completamente diferente de la de las regex multioctetos.

### Valores devueltos

Si `encoding` es proporcionado, Esta función retorna `true` en caso de éxito o `false` si ocurre un error. En este caso, la codificación de caracteres para las regex multioctetos no se cambia. Si `encoding` es omitido, mb_internal_encoding() devuelve el nombre de la codificación actual.

### Errores/Excepciones

A partir de PHP 8.0.0, se lanza una ValueError si el valor de `encoding` es una codificación inválida. Anterior a PHP 8.0.0, se emitía una `E_WARNING` en su lugar.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `encoding` ahora acepta `null`.
8.0.0 | Ahora lanza una ValueError si `encoding` es una codificación inválida. Anteriormente, se emitía una `E_WARNING` en su lugar.

### Ejemplos

Ejemplo #1 Ejemplo con mb_internal_encoding()

    <?php
    /* Utiliza la codificación interna UTF-8 */
    mb_internal_encoding("UTF-8");

    /* Muestra la codificación interna actual */
    echo mb_internal_encoding();
    ?>

### Ver también

- mb_http_input() - Detecta el tipo de codificación de caracteres HTTP
- mb_http_output() - Lee/modifica la codificación de visualización
- mb_detect_order() - Lee/modifica el orden de detección de codificaciones
- mb_regex_encoding() - Define/Recupera la codificación de caracteres para las expresiones regulares multioctetos

# mb_language

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_language — Define/Recupera el lenguaje actual

### Descripción

function mb_language(?string `$language` = `null`): string|bool

Define/Recupera el lenguaje actual.

### Parámetros

`language`

  Utilizado para codificar los correos electrónicos. Los lenguajes válidos se enumeran en la siguiente tabla. mb_send_mail() utiliza esta opción para codificar los correos electrónicos.

  Idioma | Juego de caracteres | Codificación | Alias
  --- | --- | --- | ---
  German/de | ISO-8859-15 | Quoted-Printable | Deutsch
  English/en | ISO-8859-1 | Quoted-Printable |
  Armenian/hy | ArmSCII-8 | Quoted-Printable |
  Japanese/ja | ISO-2022-JP | BASE64 |
  Korean/ko | ISO-2022-KR | BASE64 |
  neutral | UTF-8 | BASE64 |
  Russian/ru | KOI8-R | Quoted-Printable |
  Turkish/tr | ISO-8859-9 | Quoted-Printable |
  Ukrainian/ua | KOI8-U | Quoted-Printable |
  uni | UTF-8 | BASE64 | universal
  Simplified Chinese/zh-cn | HZ | BASE64 |
  Traditional Chinese/zh-tw | BIG-5 | BASE64 |

### Valores devueltos

Si `language` es proporcionado y `language` es válido, devuelve `true`. De lo contrario, devuelve `false`. Cuando `language` es omitido o `null`, devuelve el nombre del lenguaje actual, como string.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `language` ahora es nullable.

### Ver también

- mb_send_mail() - Envía un correo electrónico codificado

# mb_lcfirst

(PHP 8 >= 8.4.0)

mb_lcfirst — Convierte la primera letra de un string a minúscula

### Descripción

function mb_lcfirst(string `$string`, ?string `$encoding` = `null`): string

Realiza una operación lcfirst() segura para multi-octetos, y devuelve un string con la primera letra de `string` en minúscula.

### Parámetros

`string`
  El string de entrada.
`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

Devuelve el string resultante.

### Ver también

- mb_ucfirst() - Convierte una string con la primera letra en mayúscula
- lcfirst() - Pone el primer carácter en minúscula

# mb_list_encodings

(PHP 5, PHP 7, PHP 8)

mb_list_encodings — Devuelve un array que contiene todos los encodings soportados

### Descripción

function mb_list_encodings(): array

Devuelve un array que contiene todos los encodings soportados.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array indexado numéricamente.

### Errores/Excepciones

Esta función no genera errores.

### Ejemplos

Ejemplo #1 Ejemplo con mb_list_encodings()

    <?php

    print_r(mb_list_encodings());

    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => pass
        [1] => auto
        [2] => wchar
        [3] => byte2be
        [4] => byte2le
        [5] => byte4be
        [6] => byte4le
        [7] => BASE64
        [8] => UUENCODE
        [9] => HTML-ENTITIES
        [10] => Quoted-Printable
        [11] => 7bit
        [12] => 8bit
        [13] => UCS-4
        [14] => UCS-4BE
        [15] => UCS-4LE
        [16] => UCS-2
        [17] => UCS-2BE
        [18] => UCS-2LE
        [19] => UTF-32
        [20] => UTF-32BE
        [21] => UTF-32LE
        [22] => UTF-16
        [23] => UTF-16BE
        [24] => UTF-16LE
        [25] => UTF-8
        [26] => UTF-7
        [27] => UTF7-IMAP
        [28] => ASCII
        [29] => EUC-JP
        [30] => SJIS
        [31] => eucJP-win
        [32] => SJIS-win
        [33] => JIS
        [34] => ISO-2022-JP
        [35] => Windows-1252
        [36] => ISO-8859-1
        [37] => ISO-8859-2
        [38] => ISO-8859-3
        [39] => ISO-8859-4
        [40] => ISO-8859-5
        [41] => ISO-8859-6
        [42] => ISO-8859-7
        [43] => ISO-8859-8
        [44] => ISO-8859-9
        [45] => ISO-8859-10
        [46] => ISO-8859-13
        [47] => ISO-8859-14
        [48] => ISO-8859-15
        [49] => EUC-CN
        [50] => CP936
        [51] => HZ
        [52] => EUC-TW
        [53] => BIG-5
        [54] => EUC-KR
        [55] => UHC
        [56] => ISO-2022-KR
        [57] => Windows-1251
        [58] => CP866
        [59] => KOI8-R
    )

### Ver también

- mb_encoding_aliases() - Obtiene los alias de un tipo de codificación conocido

# mb_ltrim

(PHP 8 >= 8.4.0)

mb_ltrim — Elimina los espacios (u otros caracteres) del inicio de un string

### Descripción

function mb_ltrim(string `$string`, ?string `$characters` = `null`, ?string `$encoding` = `null`): string

Realiza una operación ltrim() segura para datos multi-octetos. Elimina los espacios (u otros caracteres) del inicio de un string.

Sin el segundo argumento, mb_ltrim() eliminará los siguientes caracteres:

- `" "` (Unicode U+0020), un espacio ordinario.
- `"\t"` (Unicode U+0009), una tabulación.
- `"\n"` (Unicode U+000A), un salto de línea.
- `"\r"` (Unicode U+000D), un retorno de carro.
- `"\0"` (Unicode U+0000), el octeto NUL.
- `"\v"` (Unicode U+000B), una tabulación vertical.
- `"\f"` (Unicode U+000C), un avance de página.
- `"\u00A0"` (Unicode U+00A0), un ESPACIO INSÉCABLE.
- `"\u1680"` (Unicode U+1680), una MARCA DE ESPACIO OGHAM.
- `"\u2000"` (Unicode U+2000), un CUADRADO MEDIO.
- `"\u2001"` (Unicode U+2001), un CUADRADO.
- `"\u2002"` (Unicode U+2002), un ESPACIO MEDIO.
- `"\u2003"` (Unicode U+2003), un ESPACIO CUADRADO.
- `"\u2004"` (Unicode U+2004), un ESPACIO DE UN-TERCIO-DE-CUADRADO.
- `"\u2005"` (Unicode U+2005), un ESPACIO DE UN-CUARTO-DE-CUADRADO.
- `"\u2006"` (Unicode U+2006), un ESPACIO DE UN-SEXTO-DE-CUADRADO.
- `"\u2007"` (Unicode U+2007), un ESPACIO PARA DÍGITOS.
- `"\u2008"` (Unicode U+2008), un ESPACIO DE PUNTUACIÓN.
- `"\u2009"` (Unicode U+2009), un ESPACIO FINO.
- `"\u200A"` (Unicode U+200A), un ESPACIO PELUDO.
- `"\u2028"` (Unicode U+2028), un SEPARADOR DE LÍNEA.
- `"\u2029"` (Unicode U+2029), un SEPARADOR DE PÁRRAFO.
- `"\u202F"` (Unicode U+202F), un ESPACIO INSÉCABLE ESTRECHO.
- `"\u205F"` (Unicode U+205F), un ESPACIO MATEMÁTICO MEDIO.
- `"\u3000"` (Unicode U+3000), un ESPACIO IDEOGRÁFICO.
- `"\u0085"` (Unicode U+0085), una LÍNEA SIGUIENTE (NEL).
- `"\u180E"` (Unicode U+180E), un SEPARADOR DE VOCALES MONGOL.

### Parámetros

`string`
  El string de entrada.
`characters`
  Opcionalmente, los caracteres a eliminar también pueden ser especificados utilizando el parámetro `characters`. Basta con listar todos los caracteres a eliminar.
`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

Esta función devuelve un string con los espacios eliminados del inicio de `string`.

### Ver también

- mb_trim() - Elimina los espacios (u otros caracteres) del inicio y final de un string
- mb_rtrim() - Elimina los espacios (u otros caracteres) del final de un string
- ltrim() - Elimina los espacios (u otros caracteres) del inicio de un string

# mb_ord

(PHP 7 >= 7.2.0, PHP 8)

mb_ord — Obtiene el punto de código Unicode de un carácter

### Descripción

function mb_ord(string `$string`, ?string `$encoding` = `null`): int|false

Devuelve el punto de código Unicode para el carácter proporcionado.

Esta función complementa mb_chr().

### Parámetros

`string`

  Una cadena de caracteres

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

El punto de código Unicode para el primer carácter de `string` o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `encoding` ahora acepta `null`.

### Ejemplos

Ejemplo #1 Un ejemplo básico de mb_ord()

    <?php
    var_dump(mb_ord("A", "UTF-8"));
    var_dump(mb_ord("🐘", "UTF-8"));
    var_dump(mb_ord("\x80", "ISO-8859-1"));
    var_dump(mb_ord("\x80", "Windows-1252"));
    ?>

El ejemplo anterior mostrará:

int(65)
int(128024)
int(128)
int(8364)

### Ver también

- mb_internal_encoding() - Lee/modifica la codificación interna
- mb_chr() - Devuelve un carácter por su valor de punto de código Unicode
- IntlChar::ord() - Devuelve el valor del punto de código Unicode de un carácter
- ord() - Convierte el primer byte de un string en un valor entre 0 y 255

# mb_output_handler

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_output_handler — Función de tratamiento de los despliegues

### Descripción

function mb_output_handler(string `$string`, int `$status`): string

mb_output_handler() es la función a proporcionar a ob_start(). mb_output_handler() convierte los caracteres enviados al cliente en la codificación parametrizada con mb_http_output().

### Parámetros

`string`

  El contenido del búfer de salida.

`status`

  El estado del búfer de salida.

### Valores devueltos

La cadena convertida.

### Ejemplos

Ejemplo #1 Ejemplo con mb_output_handler()

    <?php
    mb_http_output("UTF-8");
    ob_start("mb_output_handler");
    ?>

### Notas

> Nota:

> Si se desea enviar datos binarios tales como imágenes, el encabezado `Content-Type: header` debe ser definido utilizando la función header() antes de enviar los datos binarios al cliente (por ejemplo, `header("Content-Type: image/png")`. Si `Content-Type: header` es enviado, la conversión de la codificación de salida no se realizará.

> Tenga en cuenta que si `Content-Type: text/*` es enviado, el contenido del cuerpo es visto como texto; la conversión será realizada.

### Ver también

- ob_start() - Activa el temporizador de salida

# mb_parse_str

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_parse_str — Analiza los datos HTTP GET/POST/COOKIE y asigna las variables globales

### Descripción

function mb_parse_str(string `$string`, array `&$result`): bool

Analiza los datos de entrada HTTP GET/POST/COOKIE y asigna las variables globales. Dado que PHP no proporciona valores brutos de POST/COOKIE, esta función solo es utilizable con los datos en método GET. mb_parse_str() toma los datos de la URL llamante, detecta el juego de caracteres, convierte los datos al juego de caracteres interno, y asigna los valores al array de variables globales.

### Parámetros

`string`

  Los datos codificados en URL.

`result`

  Un array que contiene los valores decodificados y los nombres de los juegos de caracteres.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | El segundo argumento ya no es opcional.
7.2.0 | Una llamada a la función mb_parse_str() sin el segundo argumento se ha vuelto obsoleta.

### Ver también

- mb_detect_order() - Lee/modifica el orden de detección de codificaciones
- mb_internal_encoding() - Lee/modifica la codificación interna

# mb_preferred_mime_name

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_preferred_mime_name — Detecta la codificación MIME

### Descripción

function mb_preferred_mime_name(string `$encoding`): string|false

Obtiene el nombre de la codificación MIME de una cadena.

### Parámetros

`encoding`

  La codificación a verificar.

### Valores devueltos

El nombre de la codificación MIME para la codificación `encoding`, o `false` si no se prevé ningún juego de caracteres para la `encoding` dada.

### Ejemplos

Ejemplo #1 Ejemplo con mb_preferred_mime_name()

    <?php
    $outputenc = "sjis-win";
    mb_http_output($outputenc);
    ob_start("mb_output_handler");
    header("Content-Type: text/html; charset=" . mb_preferred_mime_name($outputenc));
    ?>

# mb_regex_encoding

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_regex_encoding — Define/Recupera la codificación de caracteres para las expresiones regulares multioctetos

### Descripción

function mb_regex_encoding(?string `$encoding` = `null`): string|bool

Define/Recupera la codificación de caracteres para las expresiones regulares multioctetos.

### Parámetros

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

Si `encoding` está definido, entonces Esta función retorna `true` en caso de éxito o `false` si ocurre un error.. En este caso, la codificación de caracteres interna no es modificada. Si el argumento `encoding` es omitido, entonces el nombre de la codificación de caracteres actual para las expresiones regulares multioctetos será devuelto.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `encoding` ahora acepta `null`.

### Ver también

- mb_internal_encoding() - Lee/modifica la codificación interna
- mb_ereg() - Búsqueda por expresión regular con soporte para caracteres multibyte

# mb_regex_set_options

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_regex_set_options — Lee y modifica las opciones de las funciones de expresión regular con soporte para caracteres multibyte

### Descripción

function mb_regex_set_options(?string `$options` = `null`): string

Configura las opciones por omisión con los nuevos valores contenidos en `options`, para las funciones de expresión regular con soporte para caracteres multibyte.

### Parámetros

`options`

  Las opciones a definir, en forma de un string donde cada carácter es una opción. Para definir un modo, se debe colocar el carácter que representa este modo al final, el resto de los caracteres serán las opciones. Solo puede definirse un modo, mientras que pueden definirse múltiples opciones.

  Opciones para la expresión
  Opción | Significado | Historial de cambios
  --- | --- | ---
  i | Activa la ambigüedad |
  x | Activa los patrones extendidos |
  m | El carácter `'.'` también corresponde a nuevas líneas |
  s | `'^'` -> `'\A'`, `'$'` -> `'\Z'` |
  p | Idéntico a las opciones `m` y `s` |
  l | Encuentra la correspondencia más larga |
  n | Ignora las correspondencias vacías |
  e | Utiliza la función eval() sobre el resultado | Deprecado a partir de PHP 7.1.0 y eliminado a partir de PHP 8.0.0

  > Nota:

  > La opción `"e"` no tiene efecto cuando es definida por la mb_regex_set_options(). Úsese con mb_ereg_replace() o mb_eregi_replace().

  Modos de sintaxis de la expresión regular (solo uno puede ser definido)
  Modo | Significado
  --- | ---
  j | Java (Sun java.util.regex)
  u | GNU regex
  g | grep
  c | Emacs
  r | Ruby
  z | Perl
  b | POSIX Basic regex
  d | POSIX Extended regex

### Valores devueltos

Las opciones anteriores. Si el parámetro `options` es omitido o `null`, se retornará un string describiendo las opciones actuales.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Si el parámetro `options` es proporcionado y no `null`, se retornan las opciones anteriores. Anteriormente, se retornaban las opciones actuales.
8.0.0 | `options` ahora es nullable.
8.0.0 | La opción `"e"` ahora lanza una ValueError.
7.1.0 | La opción `"e"` ahora emite una `E_DEPRECATED`.

### Ver también

- mb_split() - Divide una string en un array utilizando una expresión regular multibyte
- mb_ereg() - Búsqueda por expresión regular con soporte para caracteres multibyte
- mb_eregi() - Expresión regular insensible a mayúsculas/minúsculas con soporte para caracteres multioctetos

# mb_rtrim

(PHP 8 >= 8.4.0)

mb_rtrim — Elimina los espacios (u otros caracteres) del final de un string

### Descripción

function mb_rtrim(string `$string`, ?string `$characters` = `null`, ?string `$encoding` = `null`): string

Realiza una operación rtrim() segura para multibyte, y devuelve un string con los espacios (u otros caracteres) del final de `string` eliminados.

Sin el segundo parámetro, mb_rtrim() eliminará los siguientes caracteres:

- `" "` (Unicode U+0020), un espacio ordinario.
- `"\t"` (Unicode U+0009), una tabulación.
- `"\n"` (Unicode U+000A), un salto de línea.
- `"\r"` (Unicode U+000D), un retorno de carro.
- `"\0"` (Unicode U+0000), el octeto NUL.
- `"\v"` (Unicode U+000B), una tabulación vertical.
- `"\f"` (Unicode U+000C), un avance de página.
- `"\u00A0"` (Unicode U+00A0), un ESPACIO INSÉCABLE.
- `"\u1680"` (Unicode U+1680), una MARCA DE ESPACIO OGHAM.
- `"\u2000"` (Unicode U+2000), un CUADRADO MEDIO.
- `"\u2001"` (Unicode U+2001), un CUADRADO.
- `"\u2002"` (Unicode U+2002), un ESPACIO MEDIO.
- `"\u2003"` (Unicode U+2003), un ESPACIO CUADRADO.
- `"\u2004"` (Unicode U+2004), un ESPACIO DE UN-TERCIO-DE-CUADRADO.
- `"\u2005"` (Unicode U+2005), un ESPACIO DE UN-CUARTO-DE-CUADRADO.
- `"\u2006"` (Unicode U+2006), un ESPACIO DE UN-SEXTO-DE-CUADRADO.
- `"\u2007"` (Unicode U+2007), un ESPACIO PARA DÍGITOS.
- `"\u2008"` (Unicode U+2008), un ESPACIO DE PUNTUACIÓN.
- `"\u2009"` (Unicode U+2009), un ESPACIO FINO.
- `"\u200A"` (Unicode U+200A), un ESPACIO PELUDO.
- `"\u2028"` (Unicode U+2028), un SEPARADOR DE LÍNEA.
- `"\u2029"` (Unicode U+2029), un SEPARADOR DE PÁRRAFO.
- `"\u202F"` (Unicode U+202F), un ESPACIO INSÉCABLE ESTRECHO.
- `"\u205F"` (Unicode U+205F), un ESPACIO MATEMÁTICO MEDIO.
- `"\u3000"` (Unicode U+3000), un ESPACIO IDEOGRÁFICO.
- `"\u0085"` (Unicode U+0085), una LÍNEA SIGUIENTE (NEL).
- `"\u180E"` (Unicode U+180E), un SEPARADOR DE VOCALES MONGOL.

### Parámetros

`string`
  El string de entrada.
`characters`
  Opcionalmente, los caracteres a eliminar también pueden ser especificados utilizando el parámetro `characters`. Basta con listar todos los caracteres que deben ser eliminados. Con `..`, es posible especificar un rango creciente de caracteres.
`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

Devuelve el string modificado.

### Ver también

- mb_trim() - Elimina los espacios (u otros caracteres) del inicio y final de un string
- mb_ltrim() - Elimina los espacios (u otros caracteres) del inicio de un string
- rtrim() - Elimina los espacios (u otros caracteres) al final de un string

# mb_scrub

(PHP 7 >= 7.2.0, PHP 8)

mb_scrub — Reemplaza las secuencias de bytes mal formadas por el carácter de sustitución.

### Descripción

function mb_scrub(string `$string`, ?string `$encoding` = `null`): string

Realiza una conversión de juego de caracteres desde la codificación especificada, o desde la codificación por omisión si no se ha especificado ninguna, hacia la misma codificación. Esto tiene como efecto reemplazar cualquier secuencia de bytes inválida por el carácter de sustitución.

### Parámetros

`string`

  La cadena de entrada.

`encoding`

  La codificación utilizada para interpretar `string`. Si se omite o es `null`, el parámetro mbstring.internal_encoding será utilizado si está definido, de lo contrario el parámetro default_charset será utilizado.

### Valores devueltos

El resultado string con las secuencias de bytes inválidas reemplazadas.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `encoding` ahora acepta `null`.

# mb_send_mail

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_send_mail — Envía un correo electrónico codificado

### Descripción

function mb_send_mail(
string `$to`,
string `$subject`,
string `$message`,
array|string `$additional_headers` = [],
?string `$additional_params` = `null`
): bool

Envía un correo electrónico. Los encabezados y el cuerpo del mensaje son convertidos y codificados de acuerdo con mb_language(). mb_send_mail() es una versión adaptada de mail(). Consulte la función mail() para más detalles.

### Parámetros

`to`

  `to` es la dirección de destino del correo. Las direcciones múltiples pueden especificarse separándolas con comas. Este parámetro no es codificado automáticamente.

`subject`

  El asunto del correo.

`message`

  El mensaje del correo.

`additional_headers` (opcional)

  string o array a insertar al final del encabezado del correo.

  Este parámetro se utiliza típicamente para añadir encabezados adicionales (From, Cc, y Bcc). Los diferentes añadidos deben separarse con un CRLF (\r\n). Este parámetro debe ser validado para evitar la inyección de encabezados no deseados por personas malintencionadas.

  Si se proporciona un array, sus claves son los nombres de los encabezados y sus valores son los valores respectivos de los encabezados.

  > Nota:

  > Al enviar un correo, debe contener un encabezado `From`. Puede ser definido mediante el parámetro `additional_headers` o como valor por defecto en el php.ini.

  > Si no se hace, se emitirá un error similar a: `Warning: mail(): "sendmail_from" not set in php.ini or custom "From:" header missing`. El encabezado `From` también define `Return-Path` en Windows.

  > Nota:

  > Si los mensajes no son recibidos, intente utilizar únicamente un LF (\n). Algunos agentes de transferencia de correos Unix (en particular » qmail) reemplazan un LF por un CRLF automáticamente (lo que resulta en un doble CR si se utiliza CRLF). Debe intentar esta corrección en último lugar, sabiendo que no cumple con la » RFC 2822.

`additional_params`

  `additional_params` es una línea de parámetros MTA. Es práctico cuando se quiere definir un `Return-Path` correcto cuando se utiliza `sendmail`.

  Este parámetro es escapado por la función escapeshellcmd() internamente para prevenir la ejecución de comandos. La función escapeshellcmd() previene la ejecución de comandos, pero permite parámetros adicionales. Por razones de seguridad, este parámetro debe ser validado.

  Dado que la función escapeshellcmd() se aplica automáticamente internamente, algunos caracteres permitidos en las direcciones de correo por los RFCs de Internet ya no pueden ser utilizados. Los programas que necesiten utilizar estos caracteres, la función mail() ya no puede ser utilizada.

  El usuario que ejecuta el servidor web debe ser añadido como usuario de confianza en la configuración de envío de correos para evitar la adición de un encabezado 'X-Warning' en el mensaje cuando el remitente de la envelope (-f) es definido utilizando este método. Para los usuarios de sendmail, este archivo se encuentra utilizando la ruta /etc/mail/trusted-users.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `additional_params` ahora es nullable.
7.2.0 | El parámetro `additional_headers` ahora acepta un array.

### Ver también

- mail() - Envío de correo
- mb_encode_mimeheader() - Codifica una cadena para un encabezado MIME
- mb_language() - Define/Recupera el lenguaje actual

# mb_split

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_split — Divide una string en un array utilizando una expresión regular multibyte

### Descripción

function mb_split(string `$pattern`, string `$string`, int `$limit` = -1): array|false

Divide la string multibyte `string` utilizando la expresión regular `pattern` y devuelve el resultado en forma de array.

### Parámetros

`pattern`

  La máscara de la expresión regular.

`string`

  La string a dividir.

`limit`
  Si el argumento opcional `limit` es especificado, la string será dividida en un máximo de `limit` elementos.

### Valores devueltos

El resultado, en forma de un array, o `false` si ocurre un error.

### Notas

> Nota: La codificación de caracteres especificada por mb_regex_encoding() se utilizará como codificación de caracteres para esta función de forma predeterminada.

### Ver también

- mb_regex_encoding() - Define/Recupera la codificación de caracteres para las expresiones regulares multioctetos
- mb_ereg() - Búsqueda por expresión regular con soporte para caracteres multibyte
- explode() - Divide una string en segmentos

# mb_str_pad

(PHP 8 >= PHP 8.3.0)

mb_str_pad — Rellena una cadena multibyte hasta una cierta longitud con otra cadena multibyte

### Descripción

function mb_str_pad(
string `$string`,
int `$length`,
string `$pad_string` = " ",
int `$pad_type` = `STR_PAD_RIGHT`,
?string `$encoding` = `null`
): string

Esta función devuelve el `string` rellenado por la izquierda, la derecha o ambos lados hasta la longitud de relleno especificada, donde la longitud se mide en puntos de código Unicode. Si el argumento opcional `pad_string` no se proporciona, el `string` se rellena con espacios, de lo contrario se rellena con caracteres de `pad_string` hasta el límite.

### Parámetros

`string`

  La cadena de entrada.

`length`

  Si el valor de `length` es negativo, inferior o igual a la longitud de la cadena de entrada, no se realiza ningún relleno y `string` será devuelto.

`pad_string`

  > Nota:

  > El `pad_string` puede ser truncado si el número requerido de caracteres de relleno no puede ser dividido equitativamente por la longitud del `pad_string`.

`pad_type`

  El argumento opcional `pad_type` puede ser `STR_PAD_RIGHT`, `STR_PAD_LEFT`, o `STR_PAD_BOTH`. Por omisión `STR_PAD_RIGHT`.

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

Devuelve la cadena rellenada.

### Ejemplos

Ejemplo #1 Ejemplo de mb_str_pad()

    <?php
    var_dump(mb_str_pad('▶▶', 6, '❤❓❇', STR_PAD_RIGHT)); // string(18) "▶▶❤❓❇❤"
    var_dump(mb_str_pad('▶▶', 6, '❤❓❇', STR_PAD_LEFT));  // string(18) "❤❓❇❤▶▶"
    var_dump(mb_str_pad('▶▶', 6, '❤❓❇', STR_PAD_BOTH));  // string(18) "❤❓▶▶❤❓"

    var_dump(mb_str_pad("🎉", 3, "祝", STR_PAD_LEFT));   // string(10) "祝祝🎉"
    ?>

# mb_str_split

(PHP 7 >= 7.4.0, PHP 8)

mb_str_split — Para una cadena multibyte dada, devuelve un array de sus caracteres

### Descripción

function mb_str_split(string `$string`, int `$length` = 1, ?string `$encoding` = `null`): array

Esta función devolverá un array de strings, es una versión de str_split() con soporte para codificaciones de tamaño de carácter variable así como para codificaciones de tamaño fijo de caracteres de 1, 2 o 4 bytes. Si el parámetro `length` es especificado, la cadena se divide en bloques de la longitud especificada en caracteres (y no en bytes). El parámetro `encoding` es opcional pero se recomienda proporcionarlo.

### Parámetros

`string`

  El string a dividir en caracteres o en trozos.

`length`

  Si se especifica, cada elemento del array devuelto estará compuesto por múltiples caracteres en lugar de un solo carácter.

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

  Una cadena de caracteres que especifica uno de los encodings soportados.

### Valores devueltos

mb_str_split() devuelve un array de strings.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `encoding` ahora acepta `null`.
8.0.0 | Esta función ya no devuelve `false` en caso de fallo.

### Ver también

- str_split() - Convierte un string en un array
- grapheme_str_split() - Divide una string en un array
- explode() - Divide una string en segmentos

# mb_strcut

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strcut — Corta una parte de string

### Descripción

function mb_strcut(
string `$string`,
int `$start`,
?int `$length` = `null`,
?string `$encoding` = `null`
): string

mb_strcut() extrae un substring desde un string, de manera similar a la función mb_substr(), pero opera sobre los bytes en lugar de los caracteres. Si el corte ocurre entre 2 bytes de un carácter multibyte, el corte se realizará al inicio del primer byte de ese carácter. Esta es también la diferencia con la función substr() que cortará el string en medio de los bytes, resultando en una secuencia de bytes mal formada.

### Parámetros

`string`

  El string a cortar.

`start`

  Si `start` es positivo, el string devuelto comenzará en el byte número `start`, en el string `string`. El primer carácter está numerado cero. En efecto, en el string '`abcdef`', el byte en la posición `0` es '`a`', el byte en la posición `2` es '`c`', y así sucesivamente.

  Si `start` es negativo, el string devuelto comenzará en el byte número `start` contando desde el final del string `string`. Sin embargo, si el número negativo pasado como argumento `start` es mayor que la longitud del string, la porción devuelta comenzará desde el inicio del string `string`.

`length`

  Longitud en bytes. Si este argumento es omitido, o vale `NULL`, todos los bytes hasta el final del string serán extraídos.

  Si `length` es negativo, el string devuelto terminará en la posición `length` contando desde el final del string `string`. Sin embargo, si el número negativo pasado al argumento `length` es mayor que el número de caracteres después de la posición `start`, un string vacío será devuelto.

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

mb_strcut() devuelve la porción del string `string` que comienza en el carácter `start` y tiene la longitud de `length` caracteres.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | El comportamiento ahora es más consistente con las cadenas `UTF-8` y `UTF-16` inválidas.
8.0.0 | `encoding` ahora acepta `null`.

### Ver también

- mb_substr() - Extrae una subcadena
- mb_internal_encoding() - Lee/modifica la codificación interna

# mb_strimwidth

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strimwidth — Trunca una cadena

### Descripción

function mb_strimwidth(
string `$string`,
int `$start`,
int `$width`,
string `$trim_marker` = "",
?string `$encoding` = `null`
): string

Trunca la cadena `string` a la longitud `width` especificada, donde los caracteres de media caja cuentan como `1`, y los caracteres de caja completa cuentan como `2`. Ver » http://www.unicode.org/reports/tr11/ para más detalles sobre las cajas de caracteres asiáticos del este.

### Parámetros

`string`

  La cadena a truncar.

`start`

  `start` es la posición de inicio, en número de caracteres desde el principio de la cadena (el primer carácter es 0), o si la posición es negativa, número de caracteres desde el final de la string.

`width`

  La anchura de la truncación deseada. Si se especifica una anchura negativa, debe contarse desde el final de la cadena.

  > Nota:

  > Proporcionar una anchura negativa está obsoleto a partir de PHP 8.3.0.

`trim_marker`

  `trim_marker` es la cadena añadida al final de la cadena truncada.

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

La cadena truncada. Si `trim_marker` está definido, `trim_marker` reemplaza los últimos caracteres para corresponder al tamaño `width`.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Proporcionar una `width` negativa a mb_strimwidth() ahora está obsoleto.
8.0.0 | `encoding` ahora acepta `null`.
7.1.0 | Se añadió soporte para `start`s y `width`s negativos.

### Ejemplos

Ejemplo #1 Ejemplo con mb_strimwidth()

    <?php
    echo mb_strimwidth("Hello World", 0, 10, "...");
    // Muestra: "Hello W..."
    ?>

### Ver también

- mb_strwidth() - Devuelve el tamaño de una cadena
- mb_internal_encoding() - Lee/modifica la codificación interna

# mb_stripos

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_stripos — Encuentra la primera ocurrencia de una cadena en otra, sin tener en cuenta la casilla

### Descripción

function mb_stripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

mb_stripos() devuelve la posición numérica de la primera ocurrencia de `needle` en la cadena `haystack`. A diferencia de mb_strpos(), mb_stripos() no distingue entre mayúsculas y minúsculas. Si `needle` no es encontrado, la función devolverá `false`.

### Parámetros

`haystack`

  La cadena desde la cual se obtiene la posición de la primera ocurrencia de `needle`

`needle`

  La cadena a buscar en `haystack`

`offset`

  La posición en `haystack` donde se debe comenzar a buscar. Una posición negativa cuenta desde el final de la string.

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

Devuelve la posición numérica de la primera ocurrencia de `needle` en la cadena `haystack` o `false` si `needle` no es encontrado.

### Errores/Excepciones

- Si `offset` es mayor que la longitud de `haystack`, se lanzará un ValueError.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `needle` ahora acepta una cadena vacía.
8.0.0 | `encoding` ahora acepta `null`.
7.1.0 | Se añadió soporte para `offset`s negativos.

### Ver también

- stripos() - Busca la posición de la primera ocurrencia en un string, sin distinguir mayúsculas de minúsculas
- strpos() - Busca la posición de la primera ocurrencia en un string
- mb_strpos() - Localiza la primera ocurrencia de un carácter en una cadena

# mb_stristr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_stristr — Encuentra la primera ocurrencia de una cadena en otra, sin tener en cuenta la casilla

### Descripción

function mb_stristr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

mb_stristr() encuentra la primera ocurrencia de `needle` en `haystack` y devuelve la porción de `haystack`. A diferencia de mb_strstr(), mb_stristr() no distingue entre mayúsculas y minúsculas. Si `needle` no se encuentra, la función devolverá `false`.

### Parámetros

`haystack`

  La cadena desde la cual se recupera la primera ocurrencia de `needle`

`needle`

  La cadena a buscar en `haystack`

`before_needle`

  Determina qué porción de `haystack` devuelve esta función. Si se establece en `true`, la función devolverá toda la cadena `haystack` desde el principio hasta la primera ocurrencia de `needle` (`needle` excluido). Si se establece en `false`, la función devolverá toda la cadena `haystack` desde la primera ocurrencia de `needle` hasta el final (`needle` incluido).

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

Devuelve la porción de `haystack`, o `false` si `needle` no se encuentra.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `needle` ahora acepta una cadena vacía.
8.0.0 | `encoding` ahora acepta `null`.

### Ver también

- stristr() - Versión insensible a mayúsculas y minúsculas de strstr
- strstr() - Encuentra la primera ocurrencia en un string
- mb_strstr() - Encuentra la primera ocurrencia de una cadena en otra

# mb_strlen

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strlen — Devuelve la longitud de una cadena

### Descripción

function mb_strlen(string `$string`, ?string `$encoding` = `null`): int

Obtiene la longitud de la cadena proporcionada.

### Parámetros

`string`

  La cadena a analizar.

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

Devuelve el número de caracteres en la cadena `string`, con la codificación `encoding`. Un carácter multiocteto es entonces contado como 1.

### Errores/Excepciones

Si la codificación es desconocida, se genera un error de nivel `E_WARNING`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `encoding` ahora acepta `null`.

### Ver también

- mb_internal_encoding() - Lee/modifica la codificación interna
- grapheme_strlen() - Lee la longitud de una cadena en número de grafemas
- iconv_strlen() - Devuelve el número de caracteres de una cadena
- strlen() - Calcula el tamaño de un string

# mb_strpos

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strpos — Localiza la primera ocurrencia de un carácter en una cadena

### Descripción

function mb_strpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

Localiza la posición de la primera ocurrencia de `needle` en el string `haystack`.

Realiza una búsqueda de tipo strpos(), teniendo en cuenta los caracteres multioctetos. La posición de `needle` se cuenta desde el inicio de la cadena `haystack`: las posiciones comienzan en 0.

### Parámetros

`haystack`

  El string a partir del cual se obtiene la posición de la primera aparición de `needle`.

`needle`

  La string a encontrar en el parámetro `haystack`. A diferencia de la función strpos(), los valores numéricos no se aplican como valor ordinal de un carácter.

`offset`

  La posición de inicio de la búsqueda. Si se omite, se utilizará cero. Una posición negativa se cuenta desde el final de la string.

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

Devuelve la posición numérica de la primera ocurrencia del carácter `needle` en la cadena `haystack`. Si `needle` no se encuentra, mb_strpos() devuelve `false`.

### Errores/Excepciones

- Si `offset` es mayor que la longitud de `haystack`, se lanzará un ValueError.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `needle` ahora acepta una cadena vacía.
8.0.0 | `encoding` ahora acepta `null`.
7.1.0 | Se añadió soporte para `offset`s negativos.

### Ver también

- mb_internal_encoding() - Lee/modifica la codificación interna
- strpos() - Busca la posición de la primera ocurrencia en un string

# mb_strrchr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strrchr — Encuentra la última ocurrencia de un carácter de una cadena en otra

### Descripción

function mb_strrchr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

mb_strrchr() encuentra la última ocurrencia de `needle` en `haystack` y devuelve la porción de `haystack`. Si `needle` no es encontrado, la función devolverá `false`.

### Parámetros

`haystack`

  La cadena desde la cual se debe recuperar la última ocurrencia de `needle`.

`needle`

  La cadena a encontrar en `haystack`.

`before_needle`

  Determina qué porción de `haystack` esta función devuelve. Si se define como `true`, la función devuelve toda la cadena `haystack` desde el inicio hasta la última ocurrencia de `needle`. Si se define como `false`, la función devuelve toda la cadena `haystack` desde la última ocurrencia de `needle` hasta el final.

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

Devuelve la porción de `haystack`. o `false` si `needle` no es encontrado.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `needle` ahora acepta una cadena vacía.
8.0.0 | `encoding` ahora acepta `null`.

### Ver también

- strrchr() - Encuentra la última ocurrencia de un carácter en un string
- mb_strstr() - Encuentra la primera ocurrencia de una cadena en otra
- mb_strrichr() - Encuentra la última ocurrencia de un carácter de una cadena en otra, sin distinción de mayúsculas y minúsculas

# mb_strrichr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strrichr — Encuentra la última ocurrencia de un carácter de una cadena en otra, sin distinción de mayúsculas y minúsculas

### Descripción

function mb_strrichr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

mb_strrichr() encuentra la última ocurrencia de `needle` en `haystack` y devuelve la porción de `haystack`. A diferencia de mb_strrchr(), mb_strrichr() no distingue entre mayúsculas y minúsculas. Si `needle` no se encuentra, la función devolverá `false`.

### Parámetros

`haystack`

  La cadena desde la cual se debe buscar la última ocurrencia de `needle`.

`needle`

  La cadena a buscar en `haystack`.

`before_needle`

  Determina qué porción de `haystack` devuelve esta función. Si se establece en `true`, la función devuelve toda la cadena `haystack` desde el principio hasta la última ocurrencia de `needle`. Si se establece en `false`, la función devuelve toda la cadena `haystack` desde la última ocurrencia de `needle` hasta el final.

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

Devuelve la porción de `haystack`. o `false` si `needle` no se encuentra.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `needle` ahora acepta una cadena vacía.
8.0.0 | `encoding` ahora acepta `null`.

### Ver también

- mb_stristr() - Encuentra la primera ocurrencia de una cadena en otra, sin tener en cuenta la casilla
- mb_strrchr() - Encuentra la última ocurrencia de un carácter de una cadena en otra

# mb_strripos

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strripos — Encuentra la posición de la última ocurrencia de una cadena en otra, sin tener en cuenta la casilla

### Descripción

function mb_strripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

mb_strripos() realiza una operación strripos() basada en el número de caracteres. La posición `needle` se cuenta desde el inicio de `haystack`. La posición del primer carácter es 0. El segundo tiene como posición 1, etc. A diferencia de mb_strrpos(), mb_strripos() no es sensible a la casilla.

### Parámetros

`haystack`

  La cadena desde la cual se recupera la posición de la última ocurrencia de `needle`.

`needle`

  La cadena a buscar en `haystack`.

`offset`

  Se puede especificar para comenzar la búsqueda en un número arbitrario de caracteres dentro de `haystack`. Los valores negativos detendrán la búsqueda en un punto arbitrario antes del final de `haystack`.

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

Devuelve la posición numérica de la última ocurrencia de `needle` en la cadena `haystack`, o `false` si `needle` no es encontrado.

### Errores/Excepciones

- Si `offset` es mayor que la longitud de `haystack`, se lanzará un ValueError.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `needle` ahora acepta una cadena vacía.
8.0.0 | `encoding` ahora acepta `null`.

### Ver también

- strripos() - Busca la posición de la última ocurrencia de un string contenido en otro, de forma insensible a mayúsculas y minúsculas
- strrpos() - Busca la posición de la última ocurrencia de una subcadena en una cadena
- mb_strrpos() - Localiza la última ocurrencia de un carácter en una cadena

# mb_strrpos

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strrpos — Localiza la última ocurrencia de un carácter en una cadena

### Descripción

function mb_strrpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

mb_strrpos() realiza una búsqueda de tipo strpos(), teniendo en cuenta los caracteres multioctetos. La posición de `needle` se cuenta a partir del inicio de la cadena `haystack`: las posiciones comienzan en 0.

### Parámetros

`haystack`

  El string donde se comprobará, para la última aparición de `needle`.

`needle`

  El string a buscar en `haystack`.

`offset`
  Se puede especificar para comenzar la búsqueda en un número arbitrario de caracteres dentro de `haystack`. Los valores negativos detendrán la búsqueda en un punto arbitrario antes del final de `haystack`.
`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

Devuelve la posición numérica de la última ocurrencia del carácter `needle` en la cadena `haystack`. Si `needle` no es encontrado, mb_strrpos() devuelve `false`.

### Errores/Excepciones

- Si `offset` es mayor que la longitud de `haystack`, se lanzará un ValueError.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `needle` ahora acepta una cadena vacía.
8.0.0 | Pasar `encoding` como tercer argumento en lugar de `offset` ha sido eliminado.
8.0.0 | `encoding` ahora acepta `null`.

### Ver también

- mb_strpos() - Localiza la primera ocurrencia de un carácter en una cadena
- mb_internal_encoding() - Lee/modifica la codificación interna
- strrpos() - Busca la posición de la última ocurrencia de una subcadena en una cadena

# mb_strstr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strstr — Encuentra la primera ocurrencia de una cadena en otra

### Descripción

function mb_strstr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

mb_strstr() encuentra la primera ocurrencia de `needle` en `haystack` y devuelve la porción de `haystack`. Si `needle` no es encontrado, la función devolverá `false`.

### Parámetros

`haystack`

  La cadena en la cual se debe buscar la primera ocurrencia de `needle`

`needle`

  La cadena a buscar en `haystack`

`before_needle`

  Determina qué porción de `haystack` esta función devuelve. Si se define como `true`, la función devolverá toda la cadena `haystack` desde el inicio hasta la primera ocurrencia de `needle` (`needle` excluido). Si se define como `false`, la función devolverá toda la cadena `haystack` desde la primera ocurrencia de `needle` hasta el final (`needle` incluido).

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

Devuelve la porción de `haystack`, o `false` si `needle` no es encontrado.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `needle` ahora acepta una cadena vacía.
8.0.0 | `encoding` ahora acepta `null`.

### Ver también

- stristr() - Versión insensible a mayúsculas y minúsculas de strstr
- strstr() - Encuentra la primera ocurrencia en un string
- mb_stristr() - Encuentra la primera ocurrencia de una cadena en otra, sin tener en cuenta la casilla

# mb_strtolower

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_strtolower — Convierte todos los caracteres a minúsculas

### Descripción

function mb_strtolower(string `$string`, ?string `$encoding` = `null`): string

Devuelve la cadena `string` después de convertir todos los caracteres alfabéticos a minúsculas.

### Parámetros

`string`

  La cadena a convertir a minúsculas.

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

Devuelve la cadena `string` con todos los caracteres alfabéticos convertidos a minúsculas.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | Implementación de reglas de conversión condicional a minúsculas para la letra griega sigma.

### Ejemplos

Ejemplo #1 Ejemplo con mb_strtolower()

    <?php
    $str = "Marie A Un Petit Agneau Et Elle L'Aime BEAUCOUP.";
    $str = mb_strtolower($str);
    echo $str; // marie a un petit agneau et elle l'aime beaucoup
    ?>

Ejemplo #2 Ejemplo con mb_strtolower() con texto UTF-8 no latino

    <?php
    $str = "Τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός";
    $str = mb_strtolower($str, 'UTF-8');
    echo $str; // Muestra τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός
    ?>

### Notas

A diferencia de strtolower(), el concepto de carácter 'alfabético' se determina mediante las propiedades Unicode. Por lo tanto, el comportamiento de esta función no se modifica por las configuraciones locales, y puede convertir todos los caracteres considerados alfabéticos como la c cédilla (ç).

Para más información sobre las propiedades de Unicode, véase » http://www.unicode.org/reports/tr21/.

### Ver también

- mb_strtoupper() - Convierte todos los caracteres a mayúsculas
- mb_convert_case() - Realiza una conversión a mayúsculas/minúsculas de un string
- strtolower() - Devuelve una string en minúsculas

# mb_strtoupper

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_strtoupper — Convierte todos los caracteres a mayúsculas

### Descripción

function mb_strtoupper(string `$string`, ?string `$encoding` = `null`): string

Devuelve el string `string` después de convertir todos los caracteres alfabéticos a mayúsculas.

### Parámetros

`string`

  El string a convertir a mayúsculas.

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

Devuelve el string `string` con todos los caracteres convertidos a mayúsculas.

### Ejemplos

Ejemplo #1 Ejemplo con mb_strtoupper()

    <?php
    $str = "Marie A Un Petit Agneau Et Elle L'Aime BEAUCOUP.";
    $str = mb_strtoupper($str);
    echo $str; // MARIE A UN PETIT AGNEAU ET ELLE L'AIME BEAUCOUP.
    ?>

Ejemplo #2 Ejemplo con mb_strtoupper() y texto UTF-8 no latino

    <?php
    $str = "Τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός";
    $str = mb_strtoupper($str, 'UTF-8');
    echo $str; // Muestra ΤΆΧΙΣΤΗ ΑΛΏΠΗΞ ΒΑΦΉΣ ΨΗΜΈΝΗ ΓΗ, ΔΡΑΣΚΕΛΊΖΕΙ ΥΠΈΡ ΝΩΘΡΟΎ ΚΥΝΌΣ
    ?>

### Notas

A diferencia de strtoupper(), el concepto de carácter 'alfabético' se determina por las propiedades Unicode. Por lo tanto, el comportamiento de esta función no se modifica por las configuraciones locales, y puede convertir todos los caracteres considerados alfabéticos como la c cedilla (ç).

Para más información sobre las propiedades de Unicode, véase » http://www.unicode.org/reports/tr21/.

### Ver también

- mb_strtolower() - Convierte todos los caracteres a minúsculas
- mb_convert_case() - Realiza una conversión a mayúsculas/minúsculas de un string
- strtoupper() - Devuelve una string en mayúsculas

# mb_strwidth

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strwidth — Devuelve el tamaño de una cadena

### Descripción

function mb_strwidth(string `$string`, ?string `$encoding` = `null`): int

Devuelve la anchura de string `string`, donde los caracteres de media anchura cuentan como `1`, y los caracteres de doble anchura cuentan como `2`. Ver » http://www.unicode.org/reports/tr11/ para más detalles sobre la anchura de caracteres asiáticos del este.

Los caracteres de doble anchura son: `U+1100`-`U+115F`, `U+11A3`-`U+11A7`, `U+11FA`-`U+11FF`, `U+2329`-`U+232A`, `U+2E80`-`U+2E99`, `U+2E9B`-`U+2EF3`, `U+2F00`-`U+2FD5`, `U+2FF0`-`U+2FFB`, `U+3000`-`U+303E`, `U+3041`-`U+3096`, `U+3099`-`U+30FF`, `U+3105`-`U+312D`, `U+3131`-`U+318E`, `U+3190`-`U+31BA`, `U+31C0`-`U+31E3`, `U+31F0`-`U+321E`, `U+3220`-`U+3247`, `U+3250`-`U+32FE`, `U+3300`-`U+4DBF`, `U+4E00`-`U+A48C`, `U+A490`-`U+A4C6`, `U+A960`-`U+A97C`, `U+AC00`-`U+D7A3`, `U+D7B0`-`U+D7C6`, `U+D7CB`-`U+D7FB`, `U+F900`-`U+FAFF`, `U+FE10`-`U+FE19`, `U+FE30`-`U+FE52`, `U+FE54`-`U+FE66`, `U+FE68`-`U+FE6B`, `U+FF01`-`U+FF60`, `U+FFE0`-`U+FFE6`, `U+1B000`-`U+1B001`, `U+1F200`-`U+1F202`, `U+1F210`-`U+1F23A`, `U+1F240`-`U+1F248`, `U+1F250`-`U+1F251`, `U+20000`-`U+2FFFD`, `U+30000`-`U+3FFFD`. Todos los demás caracteres son caracteres de media anchura.

### Parámetros

`string`

  La cadena a analizar.

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

El tamaño de la string `string`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `encoding` ahora acepta `null`.

### Ejemplos

Ejemplo #1 Ejemplo mb_strwidth()

    <?php
    var_dump(
        mb_strwidth('a'),       // LATIN SMALL LETTER A
        mb_strwidth("\u{ff41}") // FULLWIDTH LATIN SMALL LETTER A
    );
    ?>

El ejemplo anterior mostrará:

    int(1)
    int(2)

### Ver también

- mb_strimwidth() - Trunca una cadena
- mb_internal_encoding() - Lee/modifica la codificación interna

# mb_substitute_character

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_substitute_character — Define/Recupera los caracteres de sustitución

### Descripción

function mb_substitute_character(string|int|null `$substitute_character` = `null`): string|int|bool

Especifica el carácter de sustitución para caracteres inválidos o codificaciones inválidas. Los caracteres inválidos pueden ser reemplazados por `"none"` (no se muestra, se eliminan), una string o un valor int (valor de un código de carácter Unicode).

Esta configuración afecta a mb_convert_encoding(), mb_convert_variables(), mb_output_handler(), mb_scrub(), y mb_send_mail().

### Parámetros

`substitute_character`

  Especifica un valor Unicode en forma de int, o bien una string en las siguientes formas:

  - `"none"` : no se muestra
  - `"long"` : muestra el valor hexadecimal (Ejemplo: `U+3000`, `JIS+7E7E`)
  - `"entity"` : muestra la entidad del carácter (Ejemplo: `&#x200;`)

### Valores devueltos

Si `substitute_character` es proporcionado, mb_substitute_character() devuelve `true` en caso de éxito, y `false` en caso de error. Si `substitute_character` es omitido, mb_substitute_character() devuelve un valor Unicode, o bien "`none`"/"`long`".

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Pasar una cadena vacía a `substitute_character` ya no es soportado; `"none"` debería ser proporcionado en su lugar.
8.0.0 | `encoding` ahora acepta `null`.

### Ejemplos

Ejemplo #1 Ejemplo con mb_substitute_character()

    <?php
    /* Configura el carácter de sustitución con U+3013 (GETA MARK) */
    mb_substitute_character(0x3013);

    /* Configura el carácter de sustitución con un formato hexadecimal */
    mb_substitute_character("long");

    /* Muestra la configuración actual */
    echo mb_substitute_character();
    ?>

# mb_substr

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_substr — Extrae una subcadena

### Descripción

function mb_substr(
string `$string`,
int `$start`,
?int `$length` = `null`,
?string `$encoding` = `null`
): string

Realiza una operación similar a substr() basada en el número de caracteres. La posición se cuenta desde el inicio de la string `string`. La posición del primer carácter es `0`, el segundo, uno, etc...

### Parámetros

`string`

  La cadena desde la cual extraer la subcadena.

`start`

  Si `start` es positivo, la cadena devuelta comenzará en el carácter número `start`, dentro de la cadena `string`. El primer carácter está numerado cero. En efecto, en la cadena '`abcdef`', el carácter en la posición `0` es '`a`', el carácter en la posición `2` es '`c`', y así sucesivamente.

  Si `start` es negativo, la cadena devuelta comenzará en el carácter número `start` contando desde el final de la cadena `string`.

`length`

  Número máximo de caracteres a utilizar desde `string`. Si este parámetro es omitido, o vale `NULL`, todos los caracteres hasta el final de la cadena serán extraídos.

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

mb_substr() devuelve la porción de la cadena `string` que comienza en el carácter `start` y tiene una longitud de `length` caracteres.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | En cadenas inválidas (aquellas con errores de codificación), los índices de caracteres ahora se interpretan de la misma manera que la mayoría de las otras funciones de mbstring. Esto significa que los índices de caracteres devueltos por mb_strpos() pueden pasarse directamente.
8.0.0 | `encoding` ahora acepta `null`.

### Ver también

- mb_strcut() - Corta una parte de string
- mb_internal_encoding() - Lee/modifica la codificación interna

# mb_substr_count

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_substr_count — Cuenta el número de ocurrencias de una subcadena

### Descripción

function mb_substr_count(string `$haystack`, string `$needle`, ?string `$encoding` = `null`): int

Cuenta el número de ocurrencias de la cadena `needle` en la cadena `haystack`.

### Parámetros

`haystack`

  La cadena a analizar.

`needle`

  La cadena a buscar.

`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

Devuelve el número de veces que la cadena `needle` aparece en la cadena `haystack`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `encoding` ahora acepta `null`.

### Ejemplos

Ejemplo #1 Ejemplo con mb_substr_count()

    <?php
    echo mb_substr_count("Ceci est un test", "es"); // muestra 2
    ?>

### Ver también

- mb_strpos() - Localiza la primera ocurrencia de un carácter en una cadena
- mb_substr() - Extrae una subcadena
- substr_count() - Cuenta el número de ocurrencias de segmentos en un string

# mb_trim

(PHP 8 >= 8.4.0)

mb_trim — Elimina los espacios (u otros caracteres) del inicio y final de un string

### Descripción

function mb_trim(string `$string`, ?string `$characters` = `null`, ?string `$encoding` = `null`): string

Realiza una operación trim() segura para multi-octetos, y devuelve un string con los espacios eliminados del inicio y final de `string`. Sin el segundo parámetro, mb_trim() eliminará los siguientes caracteres:

- `" "` (Unicode U+0020), un espacio ordinario.
- `"\t"` (Unicode U+0009), una tabulación.
- `"\n"` (Unicode U+000A), un salto de línea.
- `"\r"` (Unicode U+000D), un retorno de carro.
- `"\0"` (Unicode U+0000), el octeto NUL.
- `"\v"` (Unicode U+000B), una tabulación vertical.
- `"\f"` (Unicode U+000C), un avance de página.
- `"\u00A0"` (Unicode U+00A0), un ESPACIO INSÉCABLE.
- `"\u1680"` (Unicode U+1680), una MARCA DE ESPACIO OGHAM.
- `"\u2000"` (Unicode U+2000), un CUADRADO MEDIO.
- `"\u2001"` (Unicode U+2001), un CUADRADO.
- `"\u2002"` (Unicode U+2002), un ESPACIO MEDIO.
- `"\u2003"` (Unicode U+2003), un ESPACIO CUADRADO.
- `"\u2004"` (Unicode U+2004), un ESPACIO DE UN-TERCIO-DE-CUADRADO.
- `"\u2005"` (Unicode U+2005), un ESPACIO DE UN-CUARTO-DE-CUADRADO.
- `"\u2006"` (Unicode U+2006), un ESPACIO DE UN-SEXTO-DE-CUADRADO.
- `"\u2007"` (Unicode U+2007), un ESPACIO PARA DÍGITOS.
- `"\u2008"` (Unicode U+2008), un ESPACIO DE PUNTUACIÓN.
- `"\u2009"` (Unicode U+2009), un ESPACIO FINO.
- `"\u200A"` (Unicode U+200A), un ESPACIO PELUDO.
- `"\u2028"` (Unicode U+2028), un SEPARADOR DE LÍNEA.
- `"\u2029"` (Unicode U+2029), un SEPARADOR DE PÁRRAFO.
- `"\u202F"` (Unicode U+202F), un ESPACIO INSÉCABLE ESTRECHO.
- `"\u205F"` (Unicode U+205F), un ESPACIO MATEMÁTICO MEDIO.
- `"\u3000"` (Unicode U+3000), un ESPACIO IDEOGRÁFICO.
- `"\u0085"` (Unicode U+0085), una LÍNEA SIGUIENTE (NEL).
- `"\u180E"` (Unicode U+180E), un SEPARADOR DE VOCALES MONGOL.

### Parámetros

`string`
  El string que será recortado.
`characters`
  Opcionalmente, los caracteres a eliminar también pueden ser especificados utilizando el parámetro `characters`. Basta con listar todos los caracteres a eliminar.
`encoding`
  El parámetro `encoding` es la codificación de caracteres. Si se omite o es `null`, se utilizará el valor de la codificación de caracteres interna.

### Valores devueltos

El string recortado.

### Ver también

- mb_ltrim() - Elimina los espacios (u otros caracteres) del inicio de un string
- mb_rtrim() - Elimina los espacios (u otros caracteres) del final de un string
- trim() - Elimina los espacios (u otros caracteres) al inicio y al final de un string

# mb_ucfirst

(PHP 8 >= 8.4.0)

mb_ucfirst — Convierte una string con la primera letra en mayúscula

### Descripción

function mb_ucfirst(string `$string`, ?string `$encoding` = `null`): string

Realiza una operación ucfirst() segura para multi-octetos, y devuelve una string con la primera letra de `string` en mayúscula.

### Parámetros

`string`
  La string de entrada.
`encoding`
  La codificación de caracteres.

### Valores devueltos

Devuelve la string resultante.

### Notas

> Nota:

> A diferencia de las funciones estándar de conversión de mayúsculas y minúsculas como strtolower() y strtoupper(), la conversión de mayúsculas y minúsculas se realiza en función de las propiedades de los caracteres Unicode. Por lo tanto, el comportamiento de esta función no se ve afectado por la configuración regional, y puede convertir todos los caracteres con la propiedad 'alfabético', como la diéresis sobre la "a" (ä).

Para obtener más información sobre las propiedades Unicode, consulte » http://www.unicode.org/reports/tr21/.

### Ver también

- mb_lcfirst() - Convierte la primera letra de un string a minúscula
- mb_convert_case() - Realiza una conversión a mayúsculas/minúsculas de un string
- ucfirst() - Pone en mayúscula el primer carácter

## Tabla de contenidos

- mb_check_encoding — Verifica si las cadenas son válidas para el encodage especificado
- mb_chr — Devuelve un carácter por su valor de punto de código Unicode
- mb_convert_case — Realiza una conversión a mayúsculas/minúsculas de un string
- mb_convert_encoding — Convertir una cadena de un codificación de caracteres a otra
- mb_convert_kana — Convierte un "kana" en otro ("zen-kaku", "han-kaku" y más)
- mb_convert_variables — Convierte la codificación de variables
- mb_decode_mimeheader — Decodifica un encabezado MIME
- mb_decode_numericentity — Decodificar referencia numérica de cadena HTML a carácter
- mb_detect_encoding — Detectar la codificación de caracteres
- mb_detect_order — Lee/modifica el orden de detección de codificaciones
- mb_encode_mimeheader — Codifica una cadena para un encabezado MIME
- mb_encode_numericentity — Codifica caracteres a referencia numérica HTML
- mb_encoding_aliases — Obtiene los alias de un tipo de codificación conocido
- mb_ereg — Búsqueda por expresión regular con soporte para caracteres multibyte
- mb_ereg_match — Expresión regular POSIX para strings multibyte
- mb_ereg_replace — Reemplaza segmentos de cadena mediante expresiones regulares
- mb_ereg_replace_callback — Buscar y reemplazar mediante expresión regular con soporte multi byte utilizando una función de devolución de llamada
- mb_ereg_search — Búsqueda por expresión regular multioctets
- mb_ereg_search_getpos — Devuelve la posición de inicio para la siguiente comparación de una expresión regular
- mb_ereg_search_getregs — Lee el último segmento de cadena multioctets que coincide con el patrón
- mb_ereg_search_init — Configura las cadenas y las expresiones regulares para el soporte de caracteres multioctetos
- mb_ereg_search_pos — Retorna la posición y la longitud del segmento de string que cumple con el patrón de expresión regular
- mb_ereg_search_regs — Retorna el segmento de cadena encontrado por una expresión regular multioctets
- mb_ereg_search_setpos — Selecciona el punto de partida para la búsqueda mediante expresión regular
- mb_eregi — Expresión regular insensible a mayúsculas/minúsculas con soporte para caracteres multioctetos
- mb_eregi_replace — Expresión regular con soporte para caracteres multibyte, sin distinción de mayúsculas y minúsculas
- mb_get_info — Lee la configuración interna de la extensión mbstring
- mb_http_input — Detecta el tipo de codificación de caracteres HTTP
- mb_http_output — Lee/modifica la codificación de visualización
- mb_internal_encoding — Lee/modifica la codificación interna
- mb_language — Define/Recupera el lenguaje actual
- mb_lcfirst — Convierte la primera letra de un string a minúscula
- mb_list_encodings — Devuelve un array que contiene todos los encodings soportados
- mb_ltrim — Elimina los espacios (u otros caracteres) del inicio de un string
- mb_ord — Obtiene el punto de código Unicode de un carácter
- mb_output_handler — Función de tratamiento de los despliegues
- mb_parse_str — Analiza los datos HTTP GET/POST/COOKIE y asigna las variables globales
- mb_preferred_mime_name — Detecta la codificación MIME
- mb_regex_encoding — Define/Recupera la codificación de caracteres para las expresiones regulares multioctetos
- mb_regex_set_options — Lee y modifica las opciones de las funciones de expresión regular con soporte para caracteres multibyte
- mb_rtrim — Elimina los espacios (u otros caracteres) del final de un string
- mb_scrub — Reemplaza las secuencias de bytes mal formadas por el carácter de sustitución.
- mb_send_mail — Envía un correo electrónico codificado
- mb_split — Divide una string en un array utilizando una expresión regular multibyte
- mb_str_pad — Rellena una cadena multibyte hasta una cierta longitud con otra cadena multibyte
- mb_str_split — Para una cadena multibyte dada, devuelve un array de sus caracteres
- mb_strcut — Corta una parte de string
- mb_strimwidth — Trunca una cadena
- mb_stripos — Encuentra la primera ocurrencia de una cadena en otra, sin tener en cuenta la casilla
- mb_stristr — Encuentra la primera ocurrencia de una cadena en otra, sin tener en cuenta la casilla
- mb_strlen — Devuelve la longitud de una cadena
- mb_strpos — Localiza la primera ocurrencia de un carácter en una cadena
- mb_strrchr — Encuentra la última ocurrencia de un carácter de una cadena en otra
- mb_strrichr — Encuentra la última ocurrencia de un carácter de una cadena en otra, sin distinción de mayúsculas y minúsculas
- mb_strripos — Encuentra la posición de la última ocurrencia de una cadena en otra, sin tener en cuenta la casilla
- mb_strrpos — Localiza la última ocurrencia de un carácter en una cadena
- mb_strstr — Encuentra la primera ocurrencia de una cadena en otra
- mb_strtolower — Convierte todos los caracteres a minúsculas
- mb_strtoupper — Convierte todos los caracteres a mayúsculas
- mb_strwidth — Devuelve el tamaño de una cadena
- mb_substitute_character — Define/Recupera los caracteres de sustitución
- mb_substr — Extrae una subcadena
- mb_substr_count — Cuenta el número de ocurrencias de una subcadena
- mb_trim — Elimina los espacios (u otros caracteres) del inicio y final de un string
- mb_ucfirst — Convierte una string con la primera letra en mayúscula

- Instalación/Configuración
  - Instalación
  - Configuración en tiempo de ejecución
- Constantes predefinidas
- Juegos de caracteres soportados
- Casos de caracteres japoneses
- Entradas/Salidas HTTP
- Juegos de caracteres soportados
- Función de sobrecarga
- Requerimientos para la codificación de caracteres en PHP
- Funciones de strings multibyte
  - mb_check_encoding — Verifica si las cadenas son válidas para el encodage especificado
  - mb_chr — Devuelve un carácter por su valor de punto de código Unicode
  - mb_convert_case — Realiza una conversión a mayúsculas/minúsculas de un string
  - mb_convert_encoding — Convertir una cadena de un codificación de caracteres a otra
  - mb_convert_kana — Convierte un "kana" en otro ("zen-kaku", "han-kaku" y más)
  - mb_convert_variables — Convierte la codificación de variables
  - mb_decode_mimeheader — Decodifica un encabezado MIME
  - mb_decode_numericentity — Decodificar referencia numérica de cadena HTML a carácter
  - mb_detect_encoding — Detectar la codificación de caracteres
  - mb_detect_order — Lee/modifica el orden de detección de codificaciones
  - mb_encode_mimeheader — Codifica una cadena para un encabezado MIME
  - mb_encode_numericentity — Codifica caracteres a referencia numérica HTML
  - mb_encoding_aliases — Obtiene los alias de un tipo de codificación conocido
  - mb_ereg — Búsqueda por expresión regular con soporte para caracteres multibyte
  - mb_ereg_match — Expresión regular POSIX para strings multibyte
  - mb_ereg_replace — Reemplaza segmentos de cadena mediante expresiones regulares
  - mb_ereg_replace_callback — Buscar y reemplazar mediante expresión regular con soporte multi byte utilizando una función de devolución de llamada
  - mb_ereg_search — Búsqueda por expresión regular multioctets
  - mb_ereg_search_getpos — Devuelve la posición de inicio para la siguiente comparación de una expresión regular
  - mb_ereg_search_getregs — Lee el último segmento de cadena multioctets que coincide con el patrón
  - mb_ereg_search_init — Configura las cadenas y las expresiones regulares para el soporte de caracteres multioctetos
  - mb_ereg_search_pos — Retorna la posición y la longitud del segmento de string que cumple con el patrón de expresión regular
  - mb_ereg_search_regs — Retorna el segmento de cadena encontrado por una expresión regular multioctets
  - mb_ereg_search_setpos — Selecciona el punto de partida para la búsqueda mediante expresión regular
  - mb_eregi — Expresión regular insensible a mayúsculas/minúsculas con soporte para caracteres multioctetos
  - mb_eregi_replace — Expresión regular con soporte para caracteres multibyte, sin distinción de mayúsculas y minúsculas
  - mb_get_info — Lee la configuración interna de la extensión mbstring
  - mb_http_input — Detecta el tipo de codificación de caracteres HTTP
  - mb_http_output — Lee/modifica la codificación de visualización
  - mb_internal_encoding — Lee/modifica la codificación interna
  - mb_language — Define/Recupera el lenguaje actual
  - mb_lcfirst — Convierte la primera letra de un string a minúscula
  - mb_list_encodings — Devuelve un array que contiene todos los encodings soportados
  - mb_ltrim — Elimina los espacios (u otros caracteres) del inicio de un string
  - mb_ord — Obtiene el punto de código Unicode de un carácter
  - mb_output_handler — Función de tratamiento de los despliegues
  - mb_parse_str — Analiza los datos HTTP GET/POST/COOKIE y asigna las variables globales
  - mb_preferred_mime_name — Detecta la codificación MIME
  - mb_regex_encoding — Define/Recupera la codificación de caracteres para las expresiones regulares multioctetos
  - mb_regex_set_options — Lee y modifica las opciones de las funciones de expresión regular con soporte para caracteres multibyte
  - mb_rtrim — Elimina los espacios (u otros caracteres) del final de un string
  - mb_scrub — Reemplaza las secuencias de bytes mal formadas por el carácter de sustitución.
  - mb_send_mail — Envía un correo electrónico codificado
  - mb_split — Divide una string en un array utilizando una expresión regular multibyte
  - mb_str_pad — Rellena una cadena multibyte hasta una cierta longitud con otra cadena multibyte
  - mb_str_split — Para una cadena multibyte dada, devuelve un array de sus caracteres
  - mb_strcut — Corta una parte de string
  - mb_strimwidth — Trunca una cadena
  - mb_stripos — Encuentra la primera ocurrencia de una cadena en otra, sin tener en cuenta la casilla
  - mb_stristr — Encuentra la primera ocurrencia de una cadena en otra, sin tener en cuenta la casilla
  - mb_strlen — Devuelve la longitud de una cadena
  - mb_strpos — Localiza la primera ocurrencia de un carácter en una cadena
  - mb_strrchr — Encuentra la última ocurrencia de un carácter de una cadena en otra
  - mb_strrichr — Encuentra la última ocurrencia de un carácter de una cadena en otra, sin distinción de mayúsculas y minúsculas
  - mb_strripos — Encuentra la posición de la última ocurrencia de una cadena en otra, sin tener en cuenta la casilla
  - mb_strrpos — Localiza la última ocurrencia de un carácter en una cadena
  - mb_strstr — Encuentra la primera ocurrencia de una cadena en otra
  - mb_strtolower — Convierte todos los caracteres a minúsculas
  - mb_strtoupper — Convierte todos los caracteres a mayúsculas
  - mb_strwidth — Devuelve el tamaño de una cadena
  - mb_substitute_character — Define/Recupera los caracteres de sustitución
  - mb_substr — Extrae una subcadena
  - mb_substr_count — Cuenta el número de ocurrencias de una subcadena
  - mb_trim — Elimina los espacios (u otros caracteres) del inicio y final de un string
  - mb_ucfirst — Convierte una string con la primera letra en mayúscula

# Pspell

# Introducción

Advertencia

Esta extensión está DEPRECADA y SEPARADA a partir de PHP 8.4.0.

La biblioteca pspell permite verificar la ortografía de una palabra, y sugerir correcciones.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Tipos de recursos

## Requerimientos

Para compilar PHP con el soporte pspell, será necesario contar con la biblioteca aspell, disponible en » http://aspell.net/.

## Instalación

## PHP 8.4

Esta extensión ha sido movida al módulo » PECL y no será integrada en PHP a partir de PHP 8.4.0

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/pspell.

## PHP < 8.4

Para activar esta extensión, compílese PHP con la opción --with-pspell[=dir].

> Nota: Nota para los usuarios Win32

> Para hacer funcionar esta extensión, algunas bibliotecas DLL deben estar disponibles a través del PATH del sistema Windows. Lea la F.A.Q titulada "Cómo agregar mi carpeta PHP a mi PATH de Windows" para más información. Copiar las bibliotecas DLL desde la carpeta PHP a la carpeta del sistema de Windows también funciona (ya que la carpeta del sistema está por defecto en el PATH del sistema), pero este método no es recomendado. Esta extensión requiere que los siguientes archivos estén en el PATH: aspell-15.dll desde la carpeta bin de la instalación de aspell.

> El soporte Win32 requiere al menos la versión 0.50 de aspell.

## Tipos de recursos

Antes de PHP 8.1.0, existían dos tipos de resource en esta extensión. El primero era el identificador de enlace al diccionario, el segundo es un recurso que contiene la configuración pspell.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`PSPELL_FAST` (int)
`PSPELL_NORMAL` (int)
`PSPELL_BAD_SPELLERS` (int)
`PSPELL_RUN_TOGETHER` (int)

# Funciones de Pspell

# pspell_add_to_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_add_to_personal — Añade la palabra al diccionario personal

### Descripción

function pspell_add_to_personal(PSpell\Dictionary `$dictionary`, string `$word`): bool

pspell_add_to_personal() añade una palabra al diccionario personal. Si se utiliza pspell_new_config() con pspell_config_personal() para abrir el diccionario, el diccionario personal podrá ser guardado posteriormente con pspell_save_wordlist().

### Parámetros

`dictionary`
  Una instancia de PSpell\Dictionary.
`word`

  La palabra añadida.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `dictionary` ahora espera una instancia de PSpell\Dictionary ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 pspell_add_to_personal()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    $pspell = pspell_new_config($pspell_config);

    pspell_add_to_personal($pspell, "Vlad");
    pspell_save_wordlist($pspell);
    ?>

### Notas

> Nota:

> Esta función solo funcionará si se dispone de pspell .11.2 y aspell .32.5 o versiones posteriores.

# pspell_add_to_session

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_add_to_session — Añade la palabra al diccionario personal de la sesión actual

### Descripción

function pspell_add_to_session(PSpell\Dictionary `$dictionary`, string `$word`): bool

pspell_add_to_session() añade una palabra al diccionario personal asociado a la versión actual. Es una función similar a pspell_add_to_personal().

### Parámetros

`dictionary`
  Una instancia de PSpell\Dictionary.
`word`

  La palabra añadida.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `dictionary` ahora espera una instancia de PSpell\Dictionary ; anteriormente, se esperaba un resource.

# pspell_check

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_check — Verifica un término

### Descripción

function pspell_check(PSpell\Dictionary `$dictionary`, string `$word`): bool

pspell_check() verifica la ortografía de un término.

### Parámetros

`dictionary`
  Una instancia de PSpell\Dictionary.
`word`

  El término a verificar.

### Valores devueltos

Devuelve `true` si la ortografía es correcta, `false` en caso contrario.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `dictionary` ahora espera una instancia de PSpell\Dictionary ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pspell_check()

    <?php
    $pspell = pspell_new ("fr");

    if (pspell_check($pspell, "testt")) {
        echo 'La ortografía es correcta';
    } else {
        echo 'Disculpe, ortografía incorrecta';
    }
    ?>

# pspell_clear_session

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_clear_session — Restablece la sesión actual

### Descripción

function pspell_clear_session(PSpell\Dictionary `$dictionary`): bool

pspell_clear_session() restablece la sesión actual. El diccionario personal se vacía y, por ejemplo, si se intenta guardarlo con pspell_save_wordlist(), no ocurrirá nada.

### Parámetros

`dictionary`
  Una instancia de PSpell\Dictionary.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `dictionary` ahora espera una instancia de PSpell\Dictionary ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pspell_add_to_personal()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    $pspell = pspell_new_config($pspell_config);

    pspell_add_to_personal($pspell, "Vlad");
    pspell_clear_session($pspell);
    pspell_save_wordlist($pspell);  //"Vlad" no será guardado
    ?>

# pspell_config_create

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_create — Crea una configuración utilizada para abrir un diccionario

### Descripción

function pspell_config_create(
string `$language`,
string `$spelling` = "",
string `$jargon` = "",
string `$encoding` = ""
): PSpell\Config

Crea una configuración utilizada para abrir un diccionario.

pspell_config_create() tiene una sintaxis similar a la de pspell_new(). De hecho, utilizar pspell_config_create() seguido inmediatamente por pspell_new_config() producirá exactamente el mismo resultado. Sin embargo, después de crear una nueva configuración, también pueden utilizarse las funciones pspell_config_*() antes de llamar a pspell_new_config() para aprovechar las funcionalidades avanzadas.

Para obtener más información y ejemplos, consúltese el manual en línea en el sitio de pspell : » http://aspell.net/.

### Parámetros

`language`

  El argumento de lenguaje `language` es el código de idioma en dos letras, definido en la norma ISO 639, y dos letras opcionales ISO 3166, después de un guión o un subrayado (_).

`spelling`

  El argumento de ortografía `spelling` es necesario para los idiomas que tienen más de una ortografía, como el inglés. Los valores reconocidos son entonces 'american' (americano), 'british' (inglés), y 'canadian' (canadiense).

`jargon`

  El argumento de jergas `jargon` contiene información adicional para distinguir dos diccionarios distintos para el mismo idioma y el mismo argumento de ortografía `spelling`.

`encoding`

  El argumento de codificación `encoding` indica la codificación esperada para la respuesta. Los valores válidos son : 'utf-8', 'iso8859-*', 'koi8-r', 'viscii', 'cp1252', 'machine unsigned 16', 'machine unsigned 32'. Este argumento no ha sido probado de manera exhaustiva, por lo que se recomienda precaución.

### Valores devueltos

Devuelve una instancia de PSpell\Config.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Ahora devuelve una instancia de PSpell\Config ; anteriormente, se devolvía un resource.

### Ejemplos

Ejemplo #1 pspell_config_create()

    <?php
    $pspell_config = pspell_config_create("fr");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
    $pspell = pspell_new_personal($pspell_config, "fr");
    ?>

# pspell_config_data_dir

(PHP 5, PHP 7, PHP 8)

pspell_config_data_dir — Directorio que contiene los archivos de datos lingüísticos

### Descripción

function pspell_config_data_dir(PSpell\Config `$config`, string `$directory`): bool

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `config` ahora espera una instancia de PSpell\Config ; anteriormente, se esperaba un resource.

# pspell_config_dict_dir

(PHP 5, PHP 7, PHP 8)

pspell_config_dict_dir — Ubicación del archivo global de palabras

### Descripción

function pspell_config_dict_dir(PSpell\Config `$config`, string `$directory`): bool

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `config` ahora espera una instancia de PSpell\Config ; anteriormente, se esperaba un resource.

# pspell_config_ignore

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_ignore — Ignora las palabras de menos de N caracteres

### Descripción

function pspell_config_ignore(PSpell\Config `$config`, int `$min_length`): bool

pspell_config_ignore() debe ser utilizada con una configuración antes de llamar a pspell_new_config(). Esta función permite al verificador ignorar las palabras cortas.

### Parámetros

`config`
  Una instancia de PSpell\Config.
`min_length`

  Las palabras de menos de `min_length` caracteres serán ignoradas.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `config` ahora espera una instancia de PSpell\Config ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 pspell_config_ignore()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_ignore($pspell_config, 5);
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "abcd");  // Esta palabra no provocará un error
    ?>

# pspell_config_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_mode — Cambia el modo de sugerencia

### Descripción

function pspell_config_mode(PSpell\Config `$config`, int `$mode`): bool

pspell_config_mode() debe ser llamada en una configuración antes de pspell_new_config(). Esta función determina el número de sugerencias que serán devueltas por pspell_suggest().

### Parámetros

`config`
  Una instancia de PSpell\Config.
`mode`

  El argumento de modo es el modo de trabajo del verificador ortográfico. Varios modos están disponibles:

  - `PSPELL_FAST` - Modo rápido (menos sugerencias)
  - `PSPELL_NORMAL` - Modo normal (más sugerencias)
  - `PSPELL_BAD_SPELLERS` - Modo lento (muchas más sugerencias)

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `config` ahora espera una instancia de PSpell\Config ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pspell_config_mode()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_mode($pspell_config, PSPELL_FAST);
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "thecat");
    ?>

# pspell_config_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_personal — Selecciona el fichero que contiene el diccionario personal

### Descripción

function pspell_config_personal(PSpell\Config `$config`, string `$filename`): bool

Selecciona el fichero que contiene el diccionario personal. El diccionario personal será cargado y utilizado además del diccionario estándar, una vez que se haya llamado a pspell_new_config(). El fichero es también donde pspell_save_wordlist() guardará el diccionario personal.

pspell_config_personal() debe ser llamada en una configuración antes de llamar a pspell_new_config().

### Parámetros

`config`
  Una instancia de PSpell\Config.
`filename`

  El diccionario personal. Si el fichero no existe, será creado. El fichero debe ser accesible en escritura para el usuario que invoca PHP (ej. nobody).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `config` ahora espera una instancia de PSpell\Config ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 pspell_config_personal()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "thecat");
    ?>

### Notas

> Nota:

> Esta función solo funcionará con pspell .11.2 y aspell .32.5 o versiones posteriores.

# pspell_config_repl

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_repl — Selecciona el archivo que contiene los pares de reemplazo

### Descripción

function pspell_config_repl(PSpell\Config `$config`, string `$filename`): bool

Selecciona el archivo que contiene los pares de reemplazo.

Los pares de reemplazo mejoran la calidad del verificador. Cuando una palabra está mal escrita y no se encuentra ninguna sugerencia válida en el diccionario, pspell_store_replacement() se utilizará para registrar un par de reemplazo y pspell_save_wordlist() para guardar el diccionario con los pares de reemplazo.

pspell_config_repl() debe ser utilizado con una configuración antes de llamar a pspell_new_config().

### Parámetros

`config`
  Una instancia de PSpell\Config.
`filename`

  El archivo debe ser accesible en escritura para el usuario que invoca PHP (ej. nobody).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `config` ahora espera una instancia de PSpell\Config ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 pspell_config_repl()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "thecat");
    ?>

### Notas

> Nota:

> Esta función solo funcionará con pspell .11.2 y aspell .32.5 o versiones posteriores.

# pspell_config_runtogether

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_runtogether — Considera dos palabras unidas como un compuesto

### Descripción

function pspell_config_runtogether(PSpell\Config `$config`, bool `$allow`): bool

Esta función indica si dos palabras unidas deben ser tratadas como un compuesto válido. Así "lechat" será tratado como un compuesto válido aunque debería haber un espacio entre estas dos palabras. Modificar esta configuración solo afecta a los resultados devueltos por pspell_check(); pspell_suggest() siempre devolverá sugerencias.

pspell_config_runtogether() debe ser llamada en una configuración antes de pspell_new_config().

### Parámetros

`config`
  Una instancia de PSpell\Config.
`allow`

  `true` si dos palabras unidas deben ser tratadas como un compuesto válido, `false` en caso contrario.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `config` ahora espera una instancia de PSpell\Config ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 pspell_config_runtogether()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_runtogether($pspell_config, true);
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "thecat");
    ?>

# pspell_config_save_repl

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_save_repl — Determina si se deben guardar los pares de reemplazo con el diccionario

### Descripción

function pspell_config_save_repl(PSpell\Config `$config`, bool `$save`): bool

pspell_config_save_repl() determina si pspell_save_wordlist() debe guardar los pares de reemplazo con el diccionario. Generalmente, no es necesario utilizar esta función ya que, si pspell_config_repl() se utiliza, los pares de reemplazo serán guardados de todas formas por pspell_save_wordlist(), y, si no es así, no lo serán.

pspell_config_save_repl() debe ser llamada en una configuración antes de llamar a pspell_new_config().

### Parámetros

`config`
  Una instancia de PSpell\Config.
`save`

  `true` si los pares de reemplazo deben ser guardados, `false` en caso contrario.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `config` ahora espera una instancia de PSpell\Config ; anteriormente, se esperaba un resource.

### Notas

> Nota:

> Esta función solo funcionará con pspell .11.2 y aspell .32.5 o versiones posteriores.

# pspell_new

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new — Carga un nuevo diccionario

### Descripción

function pspell_new(
string `$language`,
string `$spelling` = "",
string `$jargon` = "",
string `$encoding` = "",
int `$mode` = 0
): PSpell\Dictionary|false

pspell_new() abre un nuevo diccionario y devuelve una instancia de PSpell\Dictionary, para ser utilizada con otras funciones pspell.

Para más información y ejemplos, consúltese el sitio » http://aspell.net/.

### Parámetros

`language`

  El argumento de idioma `spelling` se compone de las dos letras del código de idioma ISO 639, y del código opcional de país ISO 3166, separados por un '_'.

`spelling`

  Este argumento es necesario para los idiomas que tienen más de una ortografía, como el inglés o el francés. Los valores reconocidos son 'american', 'british', y 'canadian'.

`jargon`

  El argumento `jargon` contiene información adicional para distinguir dos listas de palabras que tienen el mismo marcado de idioma y ortografía.

`encoding`

  El argumento `encoding` es el tipo de codificación de las palabras. Los valores válidos son 'utf-8', 'iso8859-*', 'koi8-r', 'viscii', 'cp1252', 'machine unsigned 16', 'machine unsigned 32'. Este argumento no ha sido probado de forma exhaustiva, por lo que se recomienda precaución al utilizarlo.

`mode`

  El argumento `mode` es el modo de funcionamiento del corrector ortográfico. Varios modos están disponibles :

  - `PSPELL_FAST` - Modo rápido (menos sugerencias)
  - `PSPELL_NORMAL` - Modo normal (más sugerencias)
  - `PSPELL_BAD_SPELLERS` - Modo lento (muchas más sugerencias)
  - `PSPELL_RUN_TOGETHER` - Considera que palabras unidas forman un compuesto válido. Así, "lechat" será un compuesto válido. Esta opción modifica únicamente los resultados devueltos por pspell_check(); pspell_suggest() siempre devolverá sugerencias.
  `mode` es una máscara construida a partir de las constantes listadas anteriormente. Sin embargo, `PSPELL_FAST`, `PSPELL_NORMAL` y `PSPELL_BAD_SPELLERS` son mutuamente excluyentes : no se deben utilizar a la vez.

### Valores devueltos

Devuelve una instancia de PSpell\Dictionary en caso de éxito, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Ahora devuelve una instancia de PSpell\Dictionary ; anteriormente se devolvía un resource.

### Ejemplos

Ejemplo #1 pspell_new()

    <?php
    $pspell = pspell_new("en", "", "", "",
                         (PSPELL_FAST|PSPELL_RUN_TOGETHER));
    ?>

# pspell_new_config

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new_config — Carga un nuevo diccionario con los parámetros especificados en una configuración

### Descripción

function pspell_new_config(PSpell\Config `$config`): PSpell\Dictionary|false

pspell_new_config() abre un nuevo diccionario con los ajustes de la configuración `config`, creada con pspell_config_create() y modificada con las funciones pspell_config_*(). Este método proporciona la máxima flexibilidad, y dispone de todas las funcionalidades ofrecidas por pspell_new() y pspell_new_personal().

### Parámetros

`config`

  La `config` es la que es devuelta por pspell_config_create() cuando la configuración es creada.

### Valores devueltos

Devuelve una instancia de PSpell\Dictionary en caso de éxito, o `false` si ocurre un error

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `config` ahora espera una instancia de PSpell\Config ; anteriormente, se esperaba un resource.
8.1.0 | Ahora devuelve una instancia de PSpell\Dictionary; anteriormente se devolvía un resource.

### Ejemplos

Ejemplo #1 pspell_new_config()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
    $pspell = pspell_new_config($pspell_config);
    ?>

# pspell_new_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new_personal — Carga un nuevo diccionario con un diccionario personal

### Descripción

function pspell_new_personal(
string `$filename`,
string `$language`,
string `$spelling` = "",
string `$jargon` = "",
string `$encoding` = "",
int `$mode` = 0
): PSpell\Dictionary|false

pspell_new_personal() carga un nuevo diccionario con un diccionario personal. Este último puede ser modificado y guardado con pspell_save_wordlist(). Sin embargo, las parejas de reemplazo no serán guardadas. Para ello, debe crearse una configuración que utilice pspell_config_create(), seleccionarse el archivo de destino del diccionario personal con pspell_config_personal(), seleccionarse el archivo de parejas de reemplazo con pspell_config_repl() y abrirse un nuevo diccionario con pspell_new_config().

Para obtener más información y ejemplos, consúltese el manual en línea en el sitio web de pspell : » http://aspell.net/.

### Parámetros

`filename`

  El archivo donde se añadirán las palabras del diccionario personal. Debe ser una ruta absoluta, que comience con '/' ya que, de lo contrario, será relativa a $HOME, que es "/root" en la mayoría de los sistemas, y probablemente no sea lo deseado.

`language`

  El parámetro de idioma `language` es el código de idioma ISO 639 de dos letras, seguido de dos letras opcionales ISO 3166, después de un guión o un subrayado (_).

`spelling`

  El parámetro de ortografía `spelling` es necesario para los idiomas que tienen más de una ortografía, como el inglés. Los valores reconocidos son entonces 'american' (americano), 'british' (británico), y 'canadian' (canadiense).

`jargon`

  Información adicional para distinguir dos diccionarios distintos para el mismo idioma y el mismo parámetro de ortografía `spelling`.

`encoding`

  La codificación esperada para la respuesta. Los valores válidos son : `utf-8`, `iso8859-*`, `koi8-r`, `viscii`, `cp1252`, `machine unsigned 16`, `machine unsigned 32`.

`mode`

  El modo de funcionamiento del corrector ortográfico. Varios modos están disponibles :

  - `PSPELL_FAST` - Modo rápido (menos sugerencias)
  - `PSPELL_NORMAL` - Modo normal (más sugerencias)
  - `PSPELL_BAD_SPELLERS` - Modo lento (muchas más sugerencias)
  - `PSPELL_RUN_TOGETHER` - Considera las palabras unidas como legales. De este modo, "lechat" será una palabra compuesta legal, aunque debería haber un espacio entre las dos palabras. Cambiar esta configuración solo afecta al resultado devuelto por pspell_check(); pspell_suggest() continuará devolviendo las sugerencias.
  El modo es una máscara construida desde las diferentes constantes listadas a continuación. Sin embargo, las constantes `PSPELL_FAST`, `PSPELL_NORMAL` y `PSPELL_BAD_SPELLERS` son mutuamente excluyentes, por lo que solo debe seleccionarse una de ellas.

### Valores devueltos

Devuelve una instancia de PSpell\Dictionary en caso de éxito, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Ahora devuelve una instancia de PSpell\Dictionary; anteriormente se devolvía un resource.

### Ejemplos

Ejemplo #1 pspell_new_personal()

    <?php
    $pspell = pspell_new_personal ("/var/dictionaries/custom.pws",
            "en", "", "", "", PSPELL_FAST|PSPELL_RUN_TOGETHER);
    ?>

# pspell_save_wordlist

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_save_wordlist — Guarda el diccionario personal en un archivo

### Descripción

function pspell_save_wordlist(PSpell\Dictionary `$dictionary`): bool

pspell_save_wordlist() guarda el diccionario personal de la sesión actual. La localización de los ficheros debe haber sido especificada con pspell_config_personal() y (eventualmente) pspell_config_repl().

### Parámetros

`dictionary`
  Una instancia de PSpell\Dictionary.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `dictionary` ahora espera una instancia de PSpell\Dictionary ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 pspell_add_to_personal()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/tmp/dicts/newdict");
    $pspell = pspell_new_config($pspell_config);

    pspell_add_to_personal($pspell, "Vlad");
    pspell_save_wordlist($pspell);
    ?>

### Notas

> Nota:

> Esta función solo funcionará con pspell .11.2 y aspell .32.5 o versiones posteriores.

# pspell_store_replacement

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_store_replacement — Registra un par de sustitución para una palabra

### Descripción

function pspell_store_replacement(PSpell\Dictionary `$dictionary`, string `$misspelled`, string `$correct`): bool

pspell_store_replacement() registra un par de sustitución para una palabra de forma que esta sugerencia sea devuelta por pspell_suggest() más tarde. Para poder utilizar esta función, se debe utilizar pspell_new_personal() para abrir el diccionario. Para poder guardar permanentemente los pares de sustitución, se debe utilizar pspell_config_personal() y pspell_config_repl() para indicar el lugar de guardado de los diccionarios personales, y pspell_save_wordlist() para registrar los cambios en el disco.

### Parámetros

`dictionary`
  Una instancia de PSpell\Dictionary.
`misspelled`

  La palabra mal escrita.

`correct`

  La ortografía correcta de la palabra `misspelled`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `dictionary` ahora espera una instancia de PSpell\Dictionary ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 pspell_store_replacement()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
    $pspell = pspell_new_config($pspell_config);

    pspell_store_replacement($pspell, $misspelled, $correct);
    pspell_save_wordlist($pspell);
    ?>

### Notas

> Nota:

> Esta función solo funcionará con pspell .11.2 y aspell .32.5 o versiones posteriores.

# pspell_suggest

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_suggest — Sugiere la ortografía de una palabra

### Descripción

function pspell_suggest(PSpell\Dictionary `$dictionary`, string `$word`): array|false

pspell_suggest() devuelve un array de sugerencias para la palabra `word`.

### Parámetros

`dictionary`
  Una instancia de PSpell\Dictionary.
`word`

  La palabra probada.

### Valores devueltos

Devuelve un array de sugerencias para la palabra `word`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `dictionary` ahora espera una instancia de PSpell\Dictionary ; anteriormente, se esperaba un resource.

### Ejemplos

Ejemplo #1 Ejemplo con pspell_suggest()

    <?php
    $pspell = pspell_new("en");

    if (!pspell_check($pspell, "testt")) {
        $suggestions = pspell_suggest($pspell, "testt");

        foreach ($suggestions as $suggestion) {
            echo "Ortografías sugeridas: $suggestion<br />";
        }
    }
    ?>

## Tabla de contenidos

- pspell_add_to_personal — Añade la palabra al diccionario personal
- pspell_add_to_session — Añade la palabra al diccionario personal de la sesión actual
- pspell_check — Verifica un término
- pspell_clear_session — Restablece la sesión actual
- pspell_config_create — Crea una configuración utilizada para abrir un diccionario
- pspell_config_data_dir — Directorio que contiene los archivos de datos lingüísticos
- pspell_config_dict_dir — Ubicación del archivo global de palabras
- pspell_config_ignore — Ignora las palabras de menos de N caracteres
- pspell_config_mode — Cambia el modo de sugerencia
- pspell_config_personal — Selecciona el fichero que contiene el diccionario personal
- pspell_config_repl — Selecciona el archivo que contiene los pares de reemplazo
- pspell_config_runtogether — Considera dos palabras unidas como un compuesto
- pspell_config_save_repl — Determina si se deben guardar los pares de reemplazo con el diccionario
- pspell_new — Carga un nuevo diccionario
- pspell_new_config — Carga un nuevo diccionario con los parámetros especificados en una configuración
- pspell_new_personal — Carga un nuevo diccionario con un diccionario personal
- pspell_save_wordlist — Guarda el diccionario personal en un archivo
- pspell_store_replacement — Registra un par de sustitución para una palabra
- pspell_suggest — Sugiere la ortografía de una palabra

# La clase PSpell\Dictionary

(PHP 8 >= 8.1.0)

## Introducción

Una clase completamente opaca que reemplaza el resource `pspell` a partir de PHP 8.1.0.

## Sinopsis de la Clase

final class PSpell\Dictionary {
}

# La clase PSpell\Config

(PHP 8 >= 8.1.0)

## Introducción

Una clase completamente opaca que reemplaza el resource `pspell config` a partir de PHP 8.1.0.

## Sinopsis de la Clase

final class PSpell\Config {
}

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Tipos de recursos
- Constantes predefinidas
- Funciones de Pspell
  - pspell_add_to_personal — Añade la palabra al diccionario personal
  - pspell_add_to_session — Añade la palabra al diccionario personal de la sesión actual
  - pspell_check — Verifica un término
  - pspell_clear_session — Restablece la sesión actual
  - pspell_config_create — Crea una configuración utilizada para abrir un diccionario
  - pspell_config_data_dir — Directorio que contiene los archivos de datos lingüísticos
  - pspell_config_dict_dir — Ubicación del archivo global de palabras
  - pspell_config_ignore — Ignora las palabras de menos de N caracteres
  - pspell_config_mode — Cambia el modo de sugerencia
  - pspell_config_personal — Selecciona el fichero que contiene el diccionario personal
  - pspell_config_repl — Selecciona el archivo que contiene los pares de reemplazo
  - pspell_config_runtogether — Considera dos palabras unidas como un compuesto
  - pspell_config_save_repl — Determina si se deben guardar los pares de reemplazo con el diccionario
  - pspell_new — Carga un nuevo diccionario
  - pspell_new_config — Carga un nuevo diccionario con los parámetros especificados en una configuración
  - pspell_new_personal — Carga un nuevo diccionario con un diccionario personal
  - pspell_save_wordlist — Guarda el diccionario personal en un archivo
  - pspell_store_replacement — Registra un par de sustitución para una palabra
  - pspell_suggest — Sugiere la ortografía de una palabra
- PSpell\Dictionary — La clase PSpell\Dictionary
- PSpell\Config — La clase PSpell\Config

# GNU Recode

# Introducción

Advertencia

Esta extensión es no mantenida.

Este módulo contiene una interfaz a la biblioteca GNU Recode. La biblioteca GNU Recode convierte los ficheros entre diversas codificaciones. Cuando esta conversión no ha podido ser efectuada de manera precisa, se realizan aproximaciones. La biblioteca reconoce alrededor de 150 juegos de caracteres diferentes y es capaz de convertir ficheros utilizándolos. La mayoría de los juegos de caracteres » RFC 1345 son soportados.

> Nota: Esta extensión ha sido desligada y movida a » PECL a partir de PHP 7.4.0. Considere el uso de las extensiones Cadenas Multioctetos o iconv en su lugar.

> Nota: Esta extensión no está disponible en las plataformas Windows.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación

## Requerimientos

Se debe tener GNU Recode 3.5 o superior instalado en el sistema. El paquete puede ser descargado desde » http://directory.fsf.org/All_GNU_Packages/recode.html.

Advertencia

La versión 3.6 de la biblioteca Recode añade caracteres extraños al final de las strings convertidas en ciertas circunstancias. Por lo tanto, es preferible utilizar Recode v3.5 o una biblioteca alternativa disponible, como la extensión iconv o la extensión mbstring.

## Instalación

## PHP 7.4

Esta extensión ha sido movida al módulo » PECL y no será integrada en PHP a partir de PHP 7.4.0

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/recode.

## PHP < 7.4

Para utilizar las funciones definidas en este módulo, PHP debe ser compilado con la opción--with-recode[=DIR].

Advertencia

Pueden encontrarse fallos y problemas de inicio de PHP cuando la extensión recode es cargada después de las extensiones MySQL o imap. Cargar la extensión recode antes de estas dos extensiones corrige el problema. Esto se debe a un problema técnico ya que la biblioteca c-client de IMAP y recode tienen ambas su propia función `hash_lookup()` y las extensiones mysql y recode tienen ambas su función `hash_insert`.

Advertencia

Las extensiones IMAP, recode y YAZ no pueden ser utilizadas simultáneamente ya que utilizan un símbolo interno común. Nota: Yaz 2.0 y superior ya no sufre de este problema.

# Recode Funciones

# recode

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode — Alias de recode_string()

### Descripción

Esta función es un alias de: recode_string().

# recode_file

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode_file — Recodificación de fichero a fichero, según la solicitud

### Descripción

function recode_file(string `$request`, resource `$input`, resource `$output`): bool

Recodifica el fichero identificado por `input` en el fichero identificado por `output` según la solicitud de recodificación `request`.

### Parámetros

`request`
  El tipo de solicitud de recodificación deseada
`input`
  Un gestor de fichero local para el argumento `input`
`output`
  Un gestor de fichero local para el argumento `output`

### Valores devueltos

Retorna `false` en caso de fallo, y `true` en caso contrario.

### Ejemplos

Ejemplo #1 Ejemplo con recode_file()

    <?php
    $input = fopen('input.txt', 'r');
    $output = fopen('output.txt', 'w');
    recode_file("us..flat", $input, $output);
    ?>

### Notas

Esta función aún no maneja ficheros remotos (URL). Ambos ficheros deben hacer referencia a ficheros locales.

### Ver también

- fopen() - Abre un fichero o un URL

# recode_string

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode_string — Recodifica una string según la petición

### Descripción

function recode_string(string `$request`, string `$string`): string

Recodifica la string `string` según la petición `request`.

### Parámetros

`request`
  El tipo de petición de recodificación deseado
`string`
  La string a recodificar

### Valores devueltos

Devuelve la string recodificada en caso de éxito y false en caso contrario.

### Ejemplos

Ejemplo #1 Ejemplo con recode_string()

    <?php
    echo recode_string("us..flat", "El carácter siguiente es diacrítico: á");
    ?>

### Notas

Una petición simple de recodificación puede ser "lat1..iso646-de".

### Ver también

- Consulte la documentación GNU Recode de su instalación para más detalles sobre las peticiones.
- mb_convert_encoding() - Convertir una cadena de un codificación de caracteres a otra
- UConverter::transcode() - Convierte una cadena de un juego de caracteres a otro
- iconv() - Convierte una cadena de caracteres de un encodaje a otro

## Tabla de contenidos

- recode — Alias de recode_string
- recode_file — Recodificación de fichero a fichero, según la solicitud
- recode_string — Recodifica una string según la petición

- Instalación/Configuración
  - Requerimientos
  - Instalación
- Recode Funciones
  - recode — Alias de recode_string
  - recode_file — Recodificación de fichero a fichero, según la solicitud
  - recode_string — Recodifica una string según la petición

- Enchant — Biblioteca de ortografía Enchant
  - Instalación/Configuración
  - Constantes predefinidas
  - Ejemplos
  - Funciones de Enchant
  - EnchantBroker — La clase EnchantBroker
  - EnchantDictionary — La clase EnchantDictionary
- Gender — Determina el género de un nombre
  - Instalación/Configuración
  - Ejemplos
  - Gender\Gender — La clase Gender\Gender
- Gettext
  - Instalación/Configuración
  - Funciones de Gettext
- iconv
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones de iconv
- intl — Funciones de internacionalización
  - Instalación/Configuración
  - Constantes predefinidas
  - Ejemplos
  - Collator — La clase Collator
  - NumberFormatter — La clase NumberFormatter
  - Locale — La clase Locale
  - Normalizer — La clase Normalizer
  - MessageFormatter — La clase MessageFormatter
  - IntlCalendar — La classe IntlCalendar
  - IntlGregorianCalendar — La clase IntlGregorianCalendar
  - IntlTimeZone — La clase IntlTimeZone
  - IntlDateFormatter — La clase IntlDateFormatter
  - ResourceBundle — La clase ResourceBundle
  - Spoofchecker — La clase Spoofchecker
  - Transliterator — La clase Transliterator
  - IntlBreakIterator — La clase IntlBreakIterator
  - IntlRuleBasedBreakIterator — La clase IntlRuleBasedBreakIterator
  - IntlCodePointBreakIterator — La clase IntlCodePointBreakIterator
  - IntlDatePatternGenerator — La clase IntlDatePatternGenerator
  - IntlPartsIterator — La clase IntlPartsIterator
  - UConverter — La clase UConverter
  - Funciones de Grapheme
  - Funciones de IDN
  - IntlChar
  - IntlException — La clase de excepción para los errores intl
  - IntlIterator — La clase IntlIterator
  - Funciones de intl
- Strings multibyte
  - Instalación/Configuración
  - Constantes predefinidas
  - Juegos de caracteres soportados
  - Casos de caracteres japoneses
  - Entradas/Salidas HTTP
  - Juegos de caracteres soportados
  - Función de sobrecarga
  - Requerimientos para la codificación de caracteres en PHP
  - Funciones de strings multibyte
- Pspell
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones de Pspell
  - PSpell\Dictionary — La clase PSpell\Dictionary
  - PSpell\Config — La clase PSpell\Config
- Recode — GNU Recode
  - Instalación/Configuración
  - Recode Funciones

# Procesamiento y generación de imágenes

# Información Exif

# Introducción

Con la extensión exif, se puede trabajar con los datos meta de las imágenes. Por ejemplo, las funciones exif deben ser utilizadas para leer los datos meta de las imágenes tomadas por cámaras digitales, almacenados en el encabezado. Estos datos están comúnmente presentes en las imágenes JPEG y TIFF.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución

## Requerimientos

PHP debe ser compilado con la opción `--enable-exif`. Para activar el soporte de etiquetas EXIF multibyte, la extensión mbstring debe ser activada durante la compilación con `--enable-mbstring`. PHP no requiere ninguna biblioteca adicional para el funcionamiento del módulo exif.

## Instalación

Para habilitar el soporte para exif configure PHP con --enable-exif

Los usuarios de Windows deben habilitar las DLL php_mbstring.dll y php_exif.dll en php.ini. La DLL php_mbstring.dll debe cargarse antes que la DLL php_exif.dll, así que ajuste su php.ini como corresponde.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Exif soporta automáticamente la conversión de codificaciones de caracteres Unicode y JIS de comentarios de usuario cuando el módulo mbstring está disponible. Ésto se realiza primero decodificando el comentario utilizando el conjunto de caracteres especificado. El resultado después es codificado con otro conjunto de caracteres que debería de coincidir con su salida `HTTP`.

Opciones de configuración de Exif
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
exif.encode_unicode | "ISO-8859-15" | `INI_ALL` |
exif.decode_unicode_motorola | "UCS-2BE" | `INI_ALL` |
exif.decode_unicode_intel | "UCS-2LE" | `INI_ALL` |
exif.encode_jis | "" | `INI_ALL` |
exif.decode_jis_motorola | "JIS" | `INI_ALL` |
exif.decode_jis_intel | "JIS" | `INI_ALL` |

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`exif.encode_unicode` string
  `exif.encode_unicode` define el conjunto de caracteres UNICODE de los comentarios de usuario que se están tratando. Por defecto es ISO-8859-15 lo que debería funcionar para la mayoría de los países no asiáticos. La configuración puede estar vacía o debe ser una codificacion soportada por mbstring. Si está vacía se usa la codificación interna actual de mbstring.
`exif.decode_unicode_motorola` string
  `exif.decode_unicode_motorola` define el conjunto de caracteres interno de la imagen para comentarios de usuario codificados con Unicode si la imagen está con el orden de byte de motorola (big-endian). Esta configuración no puede estar vacía pero puede especificar una lista de codificaciones soportadas por mbstring. El valor por defecto es UCS-2BE.
`exif.decode_unicode_intel` string
  `exif.decode_unicode_intel` define el conjunto de caracteres interno de la imagen para comentarios de usuario codificados con Unicode si la imagen está con el orden de byte de intel (little-endian). Esta configuración no puede estar vacía pero puede especificar una lista de codificaciones soportadas por mbstring. El valor por defecto es UCS-2LE.
`exif.encode_jis` string
  `exif.encode_jis` define el conjunto de caracteres JIS de los comentarios de usuario que se están tratando. Por defecto está vacía lo que fuerza a las funciones a usar la codificación interna actual de mbstring.
`exif.decode_jis_motorola` string
  `exif.decode_jis_motorola` define el conjunto de caracteres interno de la imagen para los comentarios de usuario codificados con JIS si la imagen está con el orden de byte de motorola (big-endian). Esta configuración no puede estar vacía pero puede especificar una lista de codificaciones soportadas por mbstring. El valor por defecto es JIS.
`exif.decode_jis_intel` string
  `exif.decode_jis_intel` define el conjunto de caracteres interno de la imagen para los comentarios de usuario codificados con JIS si la imagen está con el orden de byte de intel (little-endian). Esta configuración no puede estar vacía pero puede especificar una lista de codificaciones soportadas por mbstring. El valor por defecto es JIS.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`EXIF_USE_MBSTRING` (int)
  Esta constante tiene el valor `1` si mbstring está activado, de lo contrario su valor es `0`.

La función exif_imagetype() lista varias constantes relacionadas.

# Funciones de Exif

# exif_imagetype

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

exif_imagetype — Determinar el tipo de una imagen

### Descripción

function exif_imagetype(string `$filename`): int|false

exif_imagetype() lee los primeros bytes de una imagen y verifica su firma.

exif_imagetype() puede usarse para evitar llamadas a otras funciones exif con tipos de fichero no soportados o en conjunto con $_SERVER['HTTP_ACCEPT'] para verificar si el visor es capaz de mostrar una imagen específica en el navegador.

### Parámetros

`filename`
  La imagen que se está verificando.

### Valores devueltos

Cuando se encuentra una firma correcta, se devolverá el valor constante apropiado; de lo contrario, se devolverá `false`. El valor devuelto es el mismo que el que devuelve getimagesize() en el índice 2, pero exif_imagetype() es mucho más rápido.

Se definen las siguientes constantes, que representan los posibles valores de retorno de exif_imagetype():

Constantes de tipos de imagen
Valor | Constante
--- | ---
1 | `IMAGETYPE_GIF`
2 | `IMAGETYPE_JPEG`
3 | `IMAGETYPE_PNG`
4 | `IMAGETYPE_SWF`
5 | `IMAGETYPE_PSD`
6 | `IMAGETYPE_BMP`
7 | `IMAGETYPE_TIFF_II` (orden de bytes Intel)
8 | `IMAGETYPE_TIFF_MM` (orden de bytes Motorola)
9 | `IMAGETYPE_JPC`
10 | `IMAGETYPE_JP2`
11 | `IMAGETYPE_JPX`
12 | `IMAGETYPE_JB2`
13 | `IMAGETYPE_SWC`
14 | `IMAGETYPE_IFF`
15 | `IMAGETYPE_WBMP`
16 | `IMAGETYPE_XBM`
17 | `IMAGETYPE_ICO`
18 | `IMAGETYPE_WEBP`
19 | `IMAGETYPE_AVIF`
20 | `IMAGETYPE_HEIF`

> Nota: exif_imagetype() emitirá una `E_NOTICE` y devolverá `false` si no puede leer suficientes bytes del fichero para determinar el tipo de imagen.

### Historial de cambios

Versión | Descripción
--- | ---
7.1.0 | Se añadió soporte para WebP.
8.1.0 | Se añadió soporte para AVIF.
8.5.0 | Se añadió soporte para HEIF.

### Ejemplos

Ejemplo #1 Ejemplo de exif_imagetype()

    <?php
    if (exif_imagetype('image.gif') != IMAGETYPE_GIF) {
        echo 'La imagen no es un gif';
    }
    ?>

### Ver también

- image_type_to_mime_type() - Obtiene el tipo MIME para el tipo de imagen devuelto por getimagesize, exif_read_data, exif_thumbnail, exif_imagetype
- getimagesize() - Devuelve el tamaño de una imagen

# exif_read_data

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_read_data — Lee los encabezados EXIF en las imágenes

### Descripción

function exif_read_data(
resource|string `$file`,
?string `$required_sections` = `null`,
bool `$as_arrays` = `false`,
bool `$read_thumbnail` = `false`
): array|false

exif_read_data() lee los encabezados EXIF de las imágenes. Con esta función, se pueden leer los datos meta generados por las cámaras digitales.

Los encabezados EXIF tienden a estar presentes en las imágenes JPEG/TIFF generadas por las cámaras digitales, pero desafortunadamente, cada cámara digital tiene una idea diferente de cómo sus imágenes deben ser marcadas, por lo que no siempre se puede contar con un encabezado EXIF específico, aunque esté presente.

Los parámetros `Height` y `Width` se calculan de la misma manera que para la función getimagesize(), por lo que sus valores no formarán parte de ningún encabezado devuelto. De igual manera, el índice `html` es la representación textual de la altura/ancho utilizada en una etiqueta de imagen HTML clásica.

Cuando un encabezado EXIF contiene una nota de Copyright, este encabezado puede contener a su vez dos valores. Como esta solución es inconsistente con los estándares EXIF 2.10, la sección `COMPUTED` devolverá los dos encabezados, `Copyright.Photographer` y `Copyright.Editor`, mientras que las secciones `IFD0` contienen el array de bytes con caracteres NULL para separar las dos entradas; o bien, solo la primera entrada si el tipo de datos era incorrecto (comportamiento por defecto de EXIF). La sección `COMPUTED` también contendrá una entrada `Copyright`, que será ya sea la cadena original de copyright, o una lista de valores separados por comas de fotos y copyright del autor.

La etiqueta `UserComment` presenta el mismo problema que la etiqueta Copyright. Puede almacenar dos valores: primero, el juego de caracteres utilizado, luego el valor en sí. Si es así, la sección `IFD` contendrá solo el juego de caracteres, o un array de bytes. La sección `COMPUTED` almacenará las dos entradas `UserCommentEncoding` y `UserComment`. El índice `UserComment` está disponible en ambos casos, y es preferible usarlo, en lugar del valor de la sección `IFD0`.

exif_read_data() valida los datos de las etiquetas EXIF de acuerdo con la especificación EXIF (» http://exif.org/Exif2-2.PDF, página 20).

### Parámetros

`file`
  La ubicación del archivo de imagen. Puede ser ya sea una ruta de acceso al archivo (los wrappers de flujo también son soportados como de costumbre), o un flujo resource.
`required_sections`

  Lista de valores separados por comas de las secciones que deben presentarse en el array de resultado. Si ninguna de las secciones solicitadas se encuentra, el valor devuelto es `false`.

  FILE | FileName (nombre del archivo), FileSize (tamaño del archivo), FileDateTime (fecha de modificación del archivo), SectionsFound (secciones encontradas)
  COMPUTED | Atributo Html, ancho, altura, color o blanco y negro y más si está disponible. El ancho y la altura se calculan de la misma manera que la función getimagesize(), por lo que sus valores nunca deberían diferir. De igual manera, el índice `html` es la representación textual de la altura/ancho utilizada en una etiqueta de imagen HTML clásica.
  ANY_TAG | Toda la información concerniente a esta etiqueta, como `IFD0`, `EXIF`, ...
  IFD0 | Todas las etiquetas `IFD0`. En imágenes normales, contienen las dimensiones de la imagen, etc.
  THUMBNAIL | Un archivo que contiene una miniatura, si hay un segundo `IFD`. Toda la información etiquetada sobre esta miniatura será almacenada en esta sección.
  COMMENT | Encabezado de comentario de las imágenes JPEG.
  EXIF | La sección EXIF es una subsección de la sección `IFD0`. Ella contiene información más detallada sobre las imágenes. La mayoría de estos índices están relacionados con las cámaras digitales.

`as_arrays`
  Especifica si cada sección debe convertirse en un array o no. Las `required_sections` `COMPUTED`, `THUMBNAIL` y `COMMENT` siempre serán convertidas en arrays, ya que contienen nombres que podrían entrar en conflicto.
`read_thumbnail`
  Cuando se define como `true`, la miniatura misma es leída. De lo contrario, solo se leen los datos contenidos en el archivo.

### Valores devueltos

Devuelve un array asociativo donde los índices son los nombres de los encabezados y los valores son los valores asociados a estos encabezados. Si no se puede devolver ningún dato, exif_read_data() devolverá `false`.

### Errores/Excepciones

Pueden generarse errores de nivel `E_WARNING` y/o `E_NOTICE` para etiquetas no soportadas u otras condiciones de error potencial, pero la función intenta leer toda la información comprensible.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `required_sections` ahora es nullable.
7.2.0 | Se ha añadido el soporte para los siguientes formatos EXIF: Samsung DJI Panasonic Sony Pentax Minolta Sigma/Foveon AGFA Kyocera Ricoh Epson

### Ejemplos

Ejemplo #1 Ejemplo con exif_read_data()

    <?php
    echo "test1.jpg:<br />\n";
    $exif = exif_read_data('tests/test1.jpg', 'IFD0');
    echo $exif===false ? "No se encontraron encabezados de datos.<br />\n" : "La imagen contiene encabezados<br />\n";

    $exif = exif_read_data('tests/test2.jpg', 0, true);
    echo "test2.jpg:<br />\n";
    foreach ($exif as $key => $section) {
        foreach ($section as $name => $val) {
            echo "$key.$name: $val<br />\n";
        }
    }
    ?>

La primera llamada falla porque la imagen no tiene encabezado de información.

Resultado del ejemplo anterior es similar a:

    test1.jpg:
    No se encontraron encabezados de datos.
    test2.jpg:
    FILE.FileName: test2.jpg
    FILE.FileDateTime: 1017666176
    FILE.FileSize: 1240
    FILE.FileType: 2
    FILE.SectionsFound: ANY_TAG, IFD0, THUMBNAIL, COMMENT
    COMPUTED.html: width="1" height="1"
    COMPUTED.Height: 1
    COMPUTED.Width: 1
    COMPUTED.IsColor: 1
    COMPUTED.ByteOrderMotorola: 1
    COMPUTED.UserComment: Exif test image.
    COMPUTED.UserCommentEncoding: ASCII
    COMPUTED.Copyright: Photo (c) M.Boerger, Edited by M.Boerger.
    COMPUTED.Copyright.Photographer: Photo (c) M.Boerger
    COMPUTED.Copyright.Editor: Edited by M.Boerger.
    IFD0.Copyright: Photo (c) M.Boerger
    IFD0.UserComment: ASCII
    THUMBNAIL.JPEGInterchangeFormat: 134
    THUMBNAIL.JPEGInterchangeFormatLength: 523
    COMMENT.0: Comment #1.
    COMMENT.1: Comment #2.
    COMMENT.2: Comment #3end
    THUMBNAIL.JPEGInterchangeFormat: 134
    THUMBNAIL.Thumbnail.Height: 1
    THUMBNAIL.Thumbnail.Height: 1

Ejemplo #2 exif_read_data() con flujos disponibles desde PHP 7.2.0

    <?php
    // Abrir el archivo, esto debería ser en modo binario
    $fp = fopen('/path/to/image.jpg', 'rb');

    if (!$fp) {
        echo 'Error: No se pudo abrir la imagen para lectura';
        exit;
    }

    // Intentar leer los encabezados EXIF
    $headers = exif_read_data($fp);

    if (!$headers) {
        echo 'Error: No se pudieron leer los encabezados exif';
        exit;
    }

    // Mostrar los encabezados 'COMPUTED'
    echo 'EXIF Headers:' . PHP_EOL;

    foreach ($headers['COMPUTED'] as $header => $value) {
        printf(' %s => %s%s', $header, $value, PHP_EOL);
    }
    ?>

Resultado del ejemplo anterior es similar a:

    EXIF Headers:
     Height => 576
     Width => 1024
     IsColor => 1
     ByteOrderMotorola => 0
     ApertureFNumber => f/5.6
     UserComment =>
     UserCommentEncoding => UNDEFINED
     Copyright => Denis
     Thumbnail.FileType => 2
     Thumbnail.MimeType => image/jpeg

### Notas

> Nota: Si mbstring está activado, EXIF intentará tratar el Unicode y elegir un juego de caracteres como se especifica por exif.decode_unicode_motorola y exif.decode_unicode_intel. La extensión EXIF no intentará determinar el codificado por sí misma, y es responsabilidad del usuario especificar correctamente el codificado a usar para el decodificado definiendo una de las dos directivas INI antes de llamar a exif_read_data().

> Nota: Si el parámetro `file` se usa para pasar un flujo a la función, entonces el flujo debe ser reposicionable. Tenga en cuenta que la posición del puntero de un archivo no se modifica después del retorno de esta función.

### Ver también

- exif_thumbnail() - Recupera la miniatura de una imagen
- getimagesize() - Devuelve el tamaño de una imagen
- Protocolos y Envolturas soportados

# exif_tagname

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_tagname — Obtener el nombre de la cabecera de un índice

### Descripción

function exif_tagname(int `$index`): string|false

### Parámetros

`index`
  La etiqueta ID correspondiente a la etiqueta Name que examinará.

### Valores devueltos

Devuelve el nombre de la cabecera, o `false` si `index` no está definido con un identificador de etiqueta EXIF.

### Ejemplos

Ejemplo #1 Ejemplo exif_tagname()

    <?php
    echo "256: ".exif_tagname(256).PHP_EOL;
    echo "257: ".exif_tagname(257).PHP_EOL;
    ?>

El ejemplo anterior mostrará:

    256: ImageWidth
    257: ImageLength

### Ver también

- exif_imagetype() - Determinar el tipo de una imagen
- » Especificación EXIF
- » Etiquetas EXIF

# exif_thumbnail

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_thumbnail — Recupera la miniatura de una imagen

### Descripción

function exif_thumbnail(
resource|string `$file`,
int `&$width` = `null`,
int `&$height` = `null`,
int `&$image_type` = `null`
): string|false

exif_thumbnail() lee la miniatura de la imagen.

Si se desea mostrar miniaturas con esta función, debe enviarse el tipo MIME adecuado con la función header().

Es posible que la función exif_thumbnail() no logre crear la imagen pero pueda determinar su tamaño. En este caso, la función devuelve `false` pero los parámetros `width` y `height` están definidos.

### Parámetros

`file`
  Ubicación del fichero de imagen. Puede tratarse de una ruta de acceso al fichero o de un flujo resource.
`width`
  El ancho devuelto de la miniatura devuelta.
`height`
  La altura devuelta de la miniatura devuelta.
`image_type`
  El tipo de imagen devuelto de la miniatura devuelta. Puede ser TIFF o JPEG.

### Valores devueltos

Devuelve la miniatura integrada o `false` si la imagen no contiene miniatura.

### Historial de cambios

Versión | Descripción
--- | ---
7.2.0 | El parámetro `file` soporta ficheros locales o recursos de flujo.

### Ejemplos

Ejemplo #1 Ejemplo con exif_thumbnail()

    <?php
    if (array_key_exists('file', $_REQUEST)) {
        $image = exif_thumbnail($_REQUEST['file'], $width, $height, $type);
    } else {
        $image = false;
    }
    if ($image!==false) {
        header('Content-type: ' .image_type_to_mime_type($type));
        echo $image;
        exit;
    } else {
        // no hay miniatura disponible, tratamiento del error aquí
        echo 'No hay miniatura disponible';
    }
    ?>

### Notas

> Nota: Si el parámetro `file` se utiliza para pasar un flujo a la función, entonces el flujo debe ser reposicionable. Tenga en cuenta que la posición del puntero de un fichero no se modifica después del retorno de esta función.

### Ver también

- exif_read_data() - Lee los encabezados EXIF en las imágenes
- image_type_to_mime_type() - Obtiene el tipo MIME para el tipo de imagen devuelto por getimagesize, exif_read_data, exif_thumbnail, exif_imagetype

# read_exif_data

(PHP 4 >= 4.0.1, PHP 5, PHP 7)

read_exif_data — Alias de exif_read_data()

Advertencia

Este alias está OBSOLETO en PHP 7.2.0, y ELIMINADO a partir de PHP 8.0.0.

### Descripción

Esta función es un alias de: exif_read_data().

### Historial de cambios

Versión | Descripción
--- | ---
7.2.0 | Este alias de función ha sido deprecado.

## Tabla de contenidos

- exif_imagetype — Determinar el tipo de una imagen
- exif_read_data — Lee los encabezados EXIF en las imágenes
- exif_tagname — Obtener el nombre de la cabecera de un índice
- exif_thumbnail — Recupera la miniatura de una imagen
- read_exif_data — Alias de exif_read_data

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
- Constantes predefinidas
- Funciones de Exif
  - exif_imagetype — Determinar el tipo de una imagen
  - exif_read_data — Lee los encabezados EXIF en las imágenes
  - exif_tagname — Obtener el nombre de la cabecera de un índice
  - exif_thumbnail — Recupera la miniatura de una imagen
  - read_exif_data — Alias de exif_read_data

# Procesamiento de imágenes y GD

# Introducción

PHP no se limita a la generación de páginas HTML. También puede servir para crear y manipular imágenes, en una amplia variedad de formatos, como GIF, PNG, JPEG, WBMP y XPM. Además, PHP puede generar directamente imágenes para el navegador, con la biblioteca GD. GD y PHP también necesitarán otras bibliotecas, dependiendo de los formatos que se deseen utilizar.

Las funciones PHP pueden usarse para obtener las dimensiones de las imágenes en los formatos JPEG, GIF, PNG, SWF, TIFF y JPEG2000.

Con la extensión exif, se podrá trabajar con las informaciones almacenadas en los encabezados de las imágenes JPEG y TIFF. De esta manera, se podrán leer las metadatos generadas por los dispositivos digitales. Las funciones exif no requieren la biblioteca GD.

> Nota: Léase la sección sobre los requisitos para saber cómo extender las capacidades de las funciones sobre imágenes para leer, escribir y modificar imágenes. Para leer las metadatos de las fotos tomadas con dispositivos digitales, se debe utilizar la extensión exif mencionada anteriormente.

> Nota: La función getimagesize() no requiere la extensión GD.

Precaución

Mientras que la versión empaquetada de la biblioteca GD utiliza el gestor de memoria Zend para asignar memoria, las versiones del sistema no lo hacen, por lo que memory_limit no se aplica.

GD soporta un gran número de formatos; a continuación se presenta una lista de formatos soportados por GD junto con notas que especifican la disponibilidad del soporte en lectura/escritura.

Formatos soportados por GD
Formato | Soporte en lectura | Soporte en escritura | Notas
--- | --- | --- | ---
JPEG | `true` | `true` |
PNG | `true` | `true` |
GIF | `true` | `true` |
XBM | `true` | `true` |
XPM | `true` | `false` |
WBMP | `true` | `true` |
WebP | `true` | `true` |
BMP | `true` | `true` | Disponible a partir de PHP 7.2.0

Aunque la mayoría de los formatos estén disponibles con soporte en lectura y escritura en la tabla anterior, esto no significa que PHP haya sido compilado con el soporte adecuado. Para conocer los formatos soportados por GD durante la compilación, utilícese la función gd_info(); para más información sobre el soporte durante la compilación de uno o varios formatos, consúltese el capítulo sobre la instalación.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución
- Tipos de recursos

## Requerimientos

Si se dispone de la biblioteca GD (disponible en » http://www.libgd.org/) también se podrán crear y manipular imágenes.

Los formatos de imágenes que se podrán manipular dependen de la versión de GD que se instale, y de todas las demás bibliotecas que GD necesita para tratar estas imágenes.

> Nota: Se requiere libgd-2.1.0 o superior. Alternativamente, utilice la biblioteca GD proporcionada con PHP.

> Nota: La biblioteca GD requiere zlib >= 1.2.0.4.

También se puede mejorar GD añadiendo formatos de imágenes adicionales.

Formatos de imágenes soportados
Formato de imagen | Biblioteca a descargar | Notas
--- | --- | ---
`gif` |  |
`avif` |  |
`jpeg` | » http://www.ijg.org/ | Al compilar la biblioteca jpeg (antes de la de PHP), debe utilizarse la opción de configuración --enable-shared. De lo contrario, se recibirá un error indicando que `libjpeg.(a|so) not found` al intentar configurar PHP antes de compilarlo.
`png` | » http://www.libpng.org/pub/png/libpng.html |
`xpm` | » http://www.ibiblio.org/pub/Linux/libs/X/!INDEX.html | Es probable que ya disponga de esta biblioteca si su sistema tiene un entorno X.
`webp` |  |

Puede querer extender GD para hacerla funcionar con diferentes tipos de fuentes. La biblioteca » FreeType 2 es soportada.

## Instalación

Para activar el soporte de GD, es necesario compilar PHP con la opción --with-gd[=DIR], donde DIR es el directorio de instalación de GD. Se recomienda utilizar la versión de GD que se distribuye con PHP, utilizando simplemente la opción --with-gd. La biblioteca GD requiere libpng y libjpeg para compilar. A partir de PHP 7.4.0, --with-gd se convierte en --enable-gd (si es necesario activar la extensión completa) y --with-external-gd (para elegir utilizar una libgd externa, en lugar de la proporcionada).

En Windows, es necesario incluir la biblioteca php_gd.dll como extensión en el archivo php.ini. Anterior a PHP 8.0.0, la DLL se llamaba php_gd2.dll.

Se amplían las capacidades de GD para manejar otros formatos de imagen especificando las siguientes opciones de compilación `--with-XXXX`:

Formatos de imagen soportados
Formato de imagen | Opción de compilación
--- | ---
`avif` | Para activar el soporte de la biblioteca avif, añadir la opción --with-avif. Disponible a partir de PHP 8.1.0.
`jpeg` | Para activar el soporte de la biblioteca JPEG, añadir la opción --with-jpeg-dir=DIR. Jpeg 6b, 7 u 8 son soportados. A partir de PHP 7.4.0, utilizar en su lugar --with-jpeg
`png` | Para activar el soporte de la biblioteca PNG, añadir la opción --with-png-dir=DIR. Tenga en cuenta que libpng requiere la biblioteca zlib y, por lo tanto, será necesario añadir también --with-zlib-dir[=DIR] en su línea de compilación. A partir de PHP 7.4.0, --with-png-dir y --with-zlib-dir han sido eliminadas. libpng y zlib son necesarias.
`xpm` | Para activar el soporte de la biblioteca XPM, añadir la opción --with-xpm-dir=DIR. Si el script de compilación no es capaz de encontrar las bibliotecas necesarias, será necesario añadir la ruta hacia las bibliotecas X11. A partir de PHP 7.4.0, utilizar en su lugar --with-xpm
`webp` | Para activar el soporte de WebP, añadir --with-vpx-dir=DIR. A partir de PHP 7.4.0, utilizar en su lugar --with-webp

> Nota: Al compilar PHP con libpng, es necesario utilizar la misma versión que la vinculada a la biblioteca GD.

Se amplían las capacidades de GD para manejar diferentes tipos de fuentes de caracteres añadiendo las siguientes opciones `--with-XXXX` de compilación:

Bibliotecas de fuentes soportadas
Biblioteca | Opción de configuración
--- | ---
`FreeType 2` | Para activar el soporte de FreeType 2, añadir la opción --with-freetype-dir=DIR. A partir de PHP 7.4.0 utilizar --with-freetype en su lugar, que depende de pkg-config.
`cadenas TrueType` | Para activar el soporte de cadenas TrueType, añadir la opción --enable-gd-native-ttf. (Esta opción no tiene efecto y ha sido eliminada desde PHP 7.2.0.)

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración de Imagen
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
gd.jpeg_ignore_warning | "1" | `INI_ALL` |

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`gd.jpeg_ignore_warning` bool

  Ignora las advertencias (pero no los errores) creadas por libjpeg(-turbo).

Registro de cambios para `gd.jpeg_ignore_warning`
Versión | Descripción
--- | ---
7.1.0 | El valor predeterminado de gd.jpeg_ignore_warning ha cambiado de 0 a 1.

Véase también las directivas de configuración de exif.

Advertencia

Las funciones de imagen consumen mucha memoria. Asegúrese de establecer memory_limit con un valor bastante alto, si está utilizando la versión incluida de la biblioteca GD.

## Tipos de recursos

Esta extensión define los siguientes tipos de recursos :

Lista de recursos en GD
Nombre | Descripción | Notas
--- | --- | ---
`gd` | Recurso de imagen, utilizado por funciones como imagecreatefrompng() | Anterior a PHP 8.0.0
`gd font` | Recurso de fuente creado internamente por imageloadfont() | Anterior a PHP 8.1.0

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`GD_VERSION` (string)
  La versión de GD con la que se compiló PHP.
`GD_MAJOR_VERSION` (int)
  La versión principal de GD con la que se compiló PHP.
`GD_MINOR_VERSION` (int)
  La versión secundaria de GD con la que se compiló PHP.
`GD_RELEASE_VERSION` (int)
  La versión de lanzamiento de GD con la que se compiló PHP.
`GD_EXTRA_VERSION` (string)
  La versión "extra" de GD (beta/rc..) con la que se compiló PHP.
`GD_BUNDLED` (int)
  Cuando se usa la versión incluida de GD este valor es 1, de lo contrario se establece en 0.
`IMG_AVIF` (int)
  Utilizado como valor de retorno por imagetypes() (disponible a partir de PHP 8.1.0)
`IMG_BMP` (int)
  Utilizado como valor de retorno por imagetypes()
`IMG_GIF` (int)
  Utilizado como valor de retorno por imagetypes()
`IMG_JPG` (int)
  Utilizado como valor de retorno por imagetypes()
`IMG_JPEG` (int)
  Utilizado como valor de retorno por imagetypes()

  > Nota:

  > Esta constante tiene el mismo valor que `IMG_JPG`

`IMG_PNG` (int)
  Utilizado como valor de retorno por imagetypes()
`IMG_TGA` (int)
  Utilizado como valor de retorno por imagetypes() (disponible a partir de PHP 7.4.0)
`IMG_WBMP` (int)
  Utilizado como valor de retorno por imagetypes()
`IMG_XPM` (int)
  Utilizado como valor de retorno por imagetypes()
`IMG_WEBP` (int)
  Utilizado como valor de retorno por imagetypes() (disponible a partir de PHP 7.0.10)
`IMG_WEBP_LOSSLESS` (int)
  (disponible a partir de PHP 8.1.0)
`IMG_COLOR_TILED` (int)
  Opción de color especial que puede utilizarse en lugar de un color asignado con imagecolorallocate() o imagecolorallocatealpha().
`IMG_COLOR_STYLED` (int)
  Opción de color especial que puede utilizarse en lugar de un color asignado con imagecolorallocate() o imagecolorallocatealpha().
`IMG_COLOR_BRUSHED` (int)
  Opción de color especial que puede utilizarse en lugar de un color asignado con imagecolorallocate() o imagecolorallocatealpha().
`IMG_COLOR_STYLEDBRUSHED` (int)
  Opción de color especial que puede utilizarse en lugar de un color asignado con imagecolorallocate() o imagecolorallocatealpha().
`IMG_COLOR_TRANSPARENT` (int)
  Opción de color especial que puede utilizarse en lugar de un color asignado con imagecolorallocate() o imagecolorallocatealpha().
`IMG_AFFINE_TRANSLATE` (int)
  Constante de tipo de transformación afín utilizada por la función imageaffinematrixget().
`IMG_AFFINE_SCALE` (int)
  Constante de tipo de transformación afín utilizada por la función imageaffinematrixget().
`IMG_AFFINE_ROTATE` (int)
  Constante de tipo de transformación afín utilizada por la función imageaffinematrixget().
`IMG_AFFINE_SHEAR_HORIZONTAL` (int)
  Constante de tipo de transformación afín utilizada por la función imageaffinematrixget().
`IMG_AFFINE_SHEAR_VERTICAL` (int)
  Constante de tipo de transformación afín utilizada por la función imageaffinematrixget().
`IMG_ARC_ROUNDED` (int)
  Constante de estilo utilizada por la función imagefilledarc().

  > Nota:

  > Esta constante tiene el mismo valor que `IMG_ARC_PIE`

`IMG_ARC_PIE` (int)
  Constante de estilo utilizada por la función imagefilledarc().
`IMG_ARC_CHORD` (int)
  Constante de estilo utilizada por la función imagefilledarc().
`IMG_ARC_NOFILL` (int)
  Constante de estilo utilizada por la función imagefilledarc().
`IMG_ARC_EDGED` (int)
  Constante de estilo utilizada por la función imagefilledarc().
`IMG_GD2_RAW` (int)
  Constante de tipo utilizada por la función imagegd2().
`IMG_GD2_COMPRESSED` (int)
  Constante de tipo utilizada por la función imagegd2().
`IMG_EFFECT_REPLACE` (int)
  Efecto de mezcla alfa utilizado por la función imagelayereffect().
`IMG_EFFECT_ALPHABLEND` (int)
  Efecto de mezcla alfa utilizado por la función imagelayereffect().
`IMG_EFFECT_NORMAL` (int)
  Efecto de mezcla alfa utilizado por la función imagelayereffect().
`IMG_EFFECT_OVERLAY` (int)
  Efecto de mezcla alfa utilizado por la función imagelayereffect().
`IMG_EFFECT_MULTIPLY` (int)
  Efecto de mezcla alfa utilizado por la función imagelayereffect().
`IMG_FILTER_NEGATE` (int)
  Filtro GD especial utilizado por la función imagefilter().
`IMG_FILTER_GRAYSCALE` (int)
  Filtro GD especial utilizado por la función imagefilter().
`IMG_FILTER_BRIGHTNESS` (int)
  Filtro GD especial utilizado por la función imagefilter().
`IMG_FILTER_CONTRAST` (int)
  Filtro GD especial utilizado por la función imagefilter().
`IMG_FILTER_COLORIZE` (int)
  Filtro GD especial utilizado por la función imagefilter().
`IMG_FILTER_EDGEDETECT` (int)
  Filtro GD especial utilizado por la función imagefilter().
`IMG_FILTER_GAUSSIAN_BLUR` (int)
  Filtro GD especial utilizado por la función imagefilter().
`IMG_FILTER_SELECTIVE_BLUR` (int)
  Filtro GD especial utilizado por la función imagefilter().
`IMG_FILTER_EMBOSS` (int)
  Filtro GD especial utilizado por la función imagefilter().
`IMG_FILTER_MEAN_REMOVAL` (int)
  Filtro GD especial utilizado por la función imagefilter().
`IMG_FILTER_SMOOTH` (int)
  Filtro GD especial utilizado por la función imagefilter().
`IMG_FILTER_PIXELATE` (int)
  Filtro GD especial utilizado por la función imagefilter().
`IMG_FILTER_SCATTER` (int)
  Filtro GD especial utilizado por la función imagefilter(). (disponible a partir de PHP 7.4.0)
`IMAGETYPE_GIF` (int)
  Constante de tipo de imagen utilizada por las funciones image_type_to_mime_type() y image_type_to_extension().
`IMAGETYPE_JPEG` (int)
  Constante de tipo de imagen utilizada por las funciones image_type_to_mime_type() y image_type_to_extension().
`IMAGETYPE_JPEG2000` (int)
  Constante de tipo de imagen utilizada por las funciones image_type_to_mime_type() y image_type_to_extension().
`IMAGETYPE_PNG` (int)
  Constante de tipo de imagen utilizada por las funciones image_type_to_mime_type() y image_type_to_extension().
`IMAGETYPE_SWF` (int)
  Constante de tipo de imagen utilizada por las funciones image_type_to_mime_type() y image_type_to_extension().
`IMAGETYPE_PSD` (int)
  Constante de tipo de imagen utilizada por las funciones image_type_to_mime_type() y image_type_to_extension().
`IMAGETYPE_BMP` (int)
  Constante de tipo de imagen utilizada por las funciones image_type_to_mime_type() y image_type_to_extension().
`IMAGETYPE_WBMP` (int)
  Constante de tipo de imagen utilizada por las funciones image_type_to_mime_type() y image_type_to_extension().
`IMAGETYPE_XBM` (int)
  Constante de tipo de imagen utilizada por las funciones image_type_to_mime_type() y image_type_to_extension().
`IMAGETYPE_TIFF_II` (int)
  Constante de tipo de imagen utilizada por las funciones image_type_to_mime_type() y image_type_to_extension().
`IMAGETYPE_TIFF_MM` (int)
  Constante de tipo de imagen utilizada por las funciones image_type_to_mime_type() y image_type_to_extension().
`IMAGETYPE_IFF` (int)
  Constante de tipo de imagen utilizada por las funciones image_type_to_mime_type() y image_type_to_extension().
`IMAGETYPE_JB2` (int)
  Constante de tipo de imagen utilizada por las funciones image_type_to_mime_type() y image_type_to_extension().
`IMAGETYPE_JPC` (int)
  Constante de tipo de imagen utilizada por las funciones image_type_to_mime_type() y image_type_to_extension().
`IMAGETYPE_JP2` (int)
  Constante de tipo de imagen utilizada por las funciones image_type_to_mime_type() y image_type_to_extension().
`IMAGETYPE_JPX` (int)
  Constante de tipo de imagen utilizada por las funciones image_type_to_mime_type() y image_type_to_extension().
`IMAGETYPE_SWC` (int)
  Constante de tipo de imagen utilizada por las funciones image_type_to_mime_type() y image_type_to_extension().
`IMAGETYPE_ICO` (int)
  Constante de tipo de imagen utilizada por las funciones image_type_to_mime_type() y image_type_to_extension().
`IMAGETYPE_WEBP` (int)
  Constante de tipo de imagen utilizada por las funciones image_type_to_mime_type() y image_type_to_extension(). (disponible a partir de PHP 7.1.0)
`IMAGETYPE_AVIF` (int)
  Constante de tipo de imagen utilizada por las funciones image_type_to_mime_type() y image_type_to_extension(). (disponible a partir de PHP 8.1.0)
`IMAGETYPE_HEIF` (int)
  Constante de tipo de imagen utilizada por las funciones image_type_to_mime_type() y image_type_to_extension(). (disponible a partir de PHP 8.5.0)
`IMAGETYPE_UNKNOWN` (int)
  Constante de tipo de imagen utilizada por las funciones image_type_to_mime_type() y image_type_to_extension().
`IMAGETYPE_COUNT` (int)
  El número de constantes de tipo de imagen (incluyendo el tipo "desconocido") compatibles con las funciones image_type_to_mime_type() y image_type_to_extension()
`PNG_NO_FILTER` (int)
  Filtro PNG especial, utilizado por la función imagepng().
`PNG_FILTER_NONE` (int)
  Filtro PNG especial, utilizado por la función imagepng().
`PNG_FILTER_SUB` (int)
  Filtro PNG especial, utilizado por la función imagepng().
`PNG_FILTER_UP` (int)
  Filtro PNG especial, utilizado por la función imagepng().
`PNG_FILTER_AVG` (int)
  Filtro PNG especial, utilizado por la función imagepng().
`PNG_FILTER_PAETH` (int)
  Filtro PNG especial, utilizado por la función imagepng().
`PNG_ALL_FILTERS` (int)
  Filtro PNG especial, utilizado por la función imagepng().
`IMG_FLIP_VERTICAL` (int)
  Utilizado junto con imageflip(), disponible a partir de PHP 5.5.0.
`IMG_FLIP_HORIZONTAL` (int)
  Utilizado junto con imageflip(), disponible a partir de PHP 5.5.0.
`IMG_FLIP_BOTH` (int)
  Utilizado junto con imageflip(), disponible a partir de PHP 5.5.0.
`IMG_BELL` (int)
  Utilizado junto con imagesetinterpolation(), disponible a partir de PHP 5.5.0.
`IMG_BESSEL` (int)
  Utilizado junto con imagesetinterpolation(), disponible a partir de PHP 5.5.0.
`IMG_BILINEAR_FIXED` (int)
  Utilizado junto con imagesetinterpolation(), disponible a partir de PHP 5.5.0.
`IMG_BICUBIC` (int)
  Utilizado junto con imagesetinterpolation(), disponible a partir de PHP 5.5.0.
`IMG_BICUBIC_FIXED` (int)
  Utilizado junto con imagesetinterpolation(), disponible a partir de PHP 5.5.0.
`IMG_BLACKMAN` (int)
  Utilizado junto con imagesetinterpolation(), disponible a partir de PHP 5.5.0.
`IMG_BOX` (int)
  Utilizado junto con imagesetinterpolation(), disponible a partir de PHP 5.5.0.
`IMG_BSPLINE` (int)
  Utilizado junto con imagesetinterpolation(), disponible a partir de PHP 5.5.0.
`IMG_CATMULLROM` (int)
  Utilizado junto con imagesetinterpolation(), disponible a partir de PHP 5.5.0.
`IMG_GAUSSIAN` (int)
  Utilizado junto con imagesetinterpolation(), disponible a partir de PHP 5.5.0.
`IMG_GENERALIZED_CUBIC` (int)
  Utilizado junto con imagesetinterpolation(), disponible a partir de PHP 5.5.0.
`IMG_HERMITE` (int)
  Utilizado junto con imagesetinterpolation(), disponible a partir de PHP 5.5.0.
`IMG_HAMMING` (int)
  Utilizado junto con imagesetinterpolation(), disponible a partir de PHP 5.5.0.
`IMG_HANNING` (int)
  Utilizado junto con imagesetinterpolation(), disponible a partir de PHP 5.5.0.
`IMG_MITCHELL` (int)
  Utilizado junto con imagesetinterpolation(), disponible a partir de PHP 5.5.0.
`IMG_POWER` (int)
  Utilizado junto con imagesetinterpolation(), disponible a partir de PHP 5.5.0.
`IMG_QUADRATIC` (int)
  Utilizado junto con imagesetinterpolation(), disponible a partir de PHP 5.5.0.
`IMG_SINC` (int)
  Utilizado junto con imagesetinterpolation(), disponible a partir de PHP 5.5.0.
`IMG_NEAREST_NEIGHBOUR` (int)
  Utilizado junto con imagesetinterpolation(), disponible a partir de PHP 5.5.0.
`IMG_WEIGHTED4` (int)
  Utilizado junto con imagesetinterpolation(), disponible a partir de PHP 5.5.0.
`IMG_TRIANGLE` (int)
  Utilizado junto con imagesetinterpolation(), disponible a partir de PHP 5.5.0.
`IMG_CROP_BLACK` (int)
  Recorta el fondo negro.
`IMG_CROP_DEFAULT` (int)
  Igual que `IMG_CROP_TRANSPARENT`. Antes de PHP 7.4.0, la librería GD incluida recurría a `IMG_CROP_SIDES`, si la imagen no tenía color transparente.
`IMG_CROP_SIDES` (int)
  Usa las 4 esquinas de la imagen para intentar detectar el fondo a recortar.
`IMG_CROP_THRESHOLD` (int)
  Recorta una imagen usando el `umbral` y el `color` dados.
`IMG_CROP_TRANSPARENT` (int)
  Recorta el fondo transparente.
`IMG_CROP_WHITE` (int)
  Recorta el fondo blanco.

# Ejemplos

## Tabla de contenidos

- Creación de una imagen PNG con PHP
- Añadir un sello digital a imágenes utilizando un canal Alpha
- Ejemplo con imagecopymerge para crear un sello digital translúcido

## Creación de una imagen PNG con PHP

Ejemplo #1 Creación de una imagen PNG con PHP

    <?php

    header("Content-type: image/png");
    $string = $_GET['text'];
    $im     = imagecreatefrompng("images/button1.png");
    $orange = imagecolorallocate($im, 220, 210, 60);
    $px     = (imagesx($im) - 7.5 * strlen($string)) / 2;
    imagestring($im, 3, $px, 9, $string, $orange);
    imagepng($im);

    ?>

Este ejemplo debe ser llamado desde una página HTML con una etiqueta de imagen como: `<img src="button.php?text">`. El script anterior, button.php, toma el string `"texto"` y lo escribe sobre el fondo de imagen llamado `"images/button1.png"`, luego lo muestra. Este es un método muy práctico para evitar redibujar un nuevo botón cada vez que se cambia su texto. De esta manera, se generan dinámicamente.

## Añadir un sello digital a imágenes utilizando un canal Alpha

Ejemplo #1 Añadir un sello digital a imágenes utilizando un canal Alpha

    <?php
    // Carga el sello y la foto para aplicar el sello digital
    $stamp = imagecreatefrompng('stamp.png');
    $im = imagecreatefromjpeg('photo.jpeg');

    // Define los márgenes para el sello y obtiene la altura y anchura de este
    $marge_right = 10;
    $marge_bottom = 10;
    $sx = imagesx($stamp);
    $sy = imagesy($stamp);

    // Copia el sello sobre la foto utilizando los márgenes y la anchura de la
    // foto original para calcular la posición del sello
    imagecopy($im, $stamp, imagesx($im) - $sx - $marge_right, imagesy($im) - $sy - $marge_bottom, 0, 0, imagesx($stamp), imagesy($stamp));

    // Mostrar
    header('Content-type: image/png');
    imagepng($im);
    ?>

Este ejemplo muestra un método simple para aplicar un sello digital y un sello a sus fotos e imágenes con licencia. Observe la presencia de un canal Alpha en el sello así como texto anti-aliaseado. Estos dos elementos serán preservados durante la copia.

## Ejemplo con imagecopymerge() para crear un sello digital translúcido

Ejemplo #1 Ejemplo con imagecopymerge() para crear un sello digital translúcido

    <?php
    // Carga el sello y la foto para aplicar el sello digital
    $im = imagecreatefromjpeg('photo.jpeg');

    // Primero, creamos un sello manualmente usando GD
    $stamp = imagecreatetruecolor(100, 70);
    imagefilledrectangle($stamp, 0, 0, 99, 69, 0x0000FF);
    imagefilledrectangle($stamp, 9, 9, 90, 60, 0xFFFFFF);
    imagestring($stamp, 5, 20, 20, 'libGD', 0x0000FF);
    imagestring($stamp, 3, 20, 40, '(c) 2007-9', 0x0000FF);

    // Define los márgenes del sello y obtiene la anchura y altura del sello
    $marge_right = 10;
    $marge_bottom = 10;
    $sx = imagesx($stamp);
    $sy = imagesy($stamp);

    // Fusiona el sello en nuestra foto con una opacidad del 50%
    imagecopymerge($im, $stamp, imagesx($im) - $sx - $marge_right, imagesy($im) - $sy - $marge_bottom, 0, 0, imagesx($stamp), imagesy($stamp), 50);

    // Guarda la imagen en un archivo
    imagepng($im, 'photo_stamp.png');

    ?>

Este ejemplo utiliza la función imagecopymerge() para fusionar el sello con nuestra imagen original. Usando esta función, podemos definir la opacidad de nuestro sello - en nuestro ejemplo, lo hemos establecido en 50%. En la práctica, es más conveniente hacer nuestra protección semi-transparente, lo que la hace más difícil de eliminar pero también permite a los visores de imágenes leerla sin problemas.

# Funciones de GD e Imágenes

# gd_info

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

gd_info — Devuelve información sobre la biblioteca GD instalada

### Descripción

function gd_info(): array

Devuelve información sobre la biblioteca GD instalada.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array asociativo.

Elementos del array devueltos por gd_info()
Atributo | Significado
--- | ---
GD Version | string que describe la versión de `libgd` que está instalada.
FreeType Support | bool. `true` si el soporte FreeType está instalado.
FreeType Linkage | string que describe la forma en la que FreeType ha sido vinculado. Los valores esperados son: '`with freetype`', '`with TTF library`' y '`with unknown library`'. Este elemento solo estará definido si `FreeType Support` es evaluado `true`.
GIF Read Support | bool. `true` si el soporte para la lectura de imágenes `GIF` está incluido.
GIF Create Support | bool. `true` si el soporte para la creación de imágenes `GIF` está incluido.
JPEG Support | bool. `true` si el soporte de `JPEG` está incluido.
PNG Support | bool. `true` si el soporte de `PNG` está incluido.
WBMP Support | bool. `true` si el soporte de `WBMP` está incluido.
XBM Support | bool. `true` si el soporte de `XBM` está incluido.
WebP Support | Valor de tipo bool. `true` si el soporte `WebP` está incluido.
AVIF Support | Valor de tipo bool. `true` si el soporte `AVIF` está incluido. Disponible a partir de PHP 8.1.0.

### Ejemplos

Ejemplo #1 Ejemplo con gd_info()

    <?php
    var_dump(gd_info());
    ?>

Resultado del ejemplo anterior es similar a:

    array(9) {
      ["GD Version"]=>
      string(24) "bundled (2.1.0 compatible)"
      ["FreeType Support"]=>
      bool(false)
      ["GIF Read Support"]=>
      bool(true)
      ["GIF Create Support"]=>
      bool(false)
      ["JPEG Support"]=>
      bool(false)
      ["PNG Support"]=>
      bool(true)
      ["WBMP Support"]=>
      bool(true)
      ["XBM Support"]=>
      bool(false)
      ["WebP Support"]=>
      bool(false)
      ["AVIF Support"]=>
      bool(false)
    }

### Ver también

- imagepng() - Envía una imagen PNG a un navegador o a un fichero
- imagejpeg() - Enviar la imagen al navegador o a un archivo
- imagegif() - Enviar la imagen al navegador o a un archivo
- imagewbmp() - Enviar la imagen al navegador o a un archivo
- imagewebp() - Muestra una imagen WebP hacia un navegador o un fichero
- imageavif() - Enviar la imagen al navegador o a un archivo
- imagetypes() - Devuelve los tipos de imágenes soportados por la versión actual de PHP

# getimagesize

(PHP 4, PHP 5, PHP 7, PHP 8)

getimagesize — Devuelve el tamaño de una imagen

### Descripción

function getimagesize(string `$filename`, array `&$image_info` = `null`): array|false

getimagesize() determina el tamaño de cualquier imagen soportada proporcionada y devuelve las dimensiones, el tipo de imagen y una cadena tipo `height/width` para colocar en una etiqueta HTML `IMG` normal y el tipo de contenido HTTP correspondiente.

getimagesize() puede también devolver más información en el argumento `image_info`.

Precaución

Esta función espera que `filename` sea un fichero de imagen válido. Si se proporciona un fichero no imagen, puede ser detectado incorrectamente como imagen y la función devolverá con éxito, pero el array puede contener valores absurdos.

No se debe utilizar getimagesize() para verificar que un fichero dado es una imagen válida. En su lugar, debe utilizarse una solución diseñada para ello como la extensión FileInfo.

> Nota: Se debe tener en cuenta que JPC y JP2 pueden tener componentes con diferentes profundidades de bit. En este caso, el valor de "bits" es la mayor profundidad de bit encontrada. Asimismo, los ficheros JP2 disponen de soporte para `multiple JPEG 2000 codestreams`. En este caso, getimagesize() devuelve los valores para el primer codestream encontrado en la raíz del fichero.

> Nota: La información sobre iconos se recupera desde el icono con mayor resolución.

> Nota: Las imágenes GIF consistentes en uno o varios fotogramas, donde cada fotograma puede ocupar únicamente una parte de la imagen. El tamaño de la imagen que es reportado por getimagesize() es el tamaño global (leído desde el descriptor lógico de la pantalla).

### Parámetros

`filename`

  Este argumento especifica el fichero del cual se desean obtener las informaciones. Puede ser un fichero local o (dependiendo de la configuración), un fichero remoto utilizando uno de los flujos soportados.

`image_info`

  Este argumento opcional permite extraer información adicional del fichero de imagen. Actualmente, esta opción devuelve diferentes marcadores JPG APP en un array asociativo. Algunos programas utilizan estos marcadores APP para especificar información en las etiquetas HTML. Un marcador común es el marcador APP13, descrito en » IPTC. Puede utilizarse la función iptcparse() para analizar este marcador, y obtener información legible.

  > Nota:

  > `image_info` soporta únicamente los ficheros JFIF.

### Valores devueltos

Devuelve un array que contiene hasta 7 elementos. No todos los tipos de imágenes incluyen los elementos `channels` y `bits`.

El índice 0 contiene el ancho. El índice 1 contiene la altura.

> Nota:

> Algunos formatos pueden no contener ninguna imagen, o bien varias. En estos casos, getimagesize() puede no ser capaz de determinar correctamente el tamaño de la imagen. getimagesize() devuelve entonces cero como tamaño de altura y ancho.

> Nota: getimagesize() es independiente de las metadatos de la imagen. Por ejemplo, si la bandera Exif `Orientation` está definida en un valor que gira la imagen 90 o 270 grados, los índices 0 y 1 son intercambiados, es decir, contienen respectivamente la altura y el ancho.

El índice 2 es una constante entre `IMAGETYPE_*`, indicando el tipo de la imagen.

El índice 3 contiene la cadena para colocar en las etiquetas IMG: `height="xxx" width="yyy"`.

`mime` corresponde al tipo MIME de una imagen. Esta información puede ser utilizada para enviar el encabezado HTTP `Content-type` correcto:

Ejemplo #1 getimagesize() y tipos MIME

    <?php
    $size = getimagesize($filename);
    $fp = fopen($filename, "rb");
    if ($size && $fp) {
        header("Content-type: {$size['mime']}");
        fpassthru($fp);
        exit;
    } else {
        // error
    }
    ?>

`channels` será 3 para imágenes RGB y 4 para imágenes CMYK.

`bits` es el número de bytes para cada color.

Sin embargo, la presencia de los valores de `channels` y de `bits` puede llevar a la confusión. Por ejemplo, una imagen GIF utiliza siempre tres canales por píxel, pero el número de bits por píxel no puede ser calculado en el caso de una imagen animada GIF con una tabla de colores global.

Si ocurre un error, `false` es devuelto.

### Errores/Excepciones

Si el acceso a `filename` es imposible, getimagesize() generará un error de nivel `E_WARNING`. Si ocurre un error durante la lectura, getimagesize() generará un error de nivel `E_NOTICE`.

A partir de PHP 8.0.0, se lanza una excepción ValueError si `filename` está vacío.

### Historial de cambios

Versión | Descripción
--- | ---
8.2.0 | Devuelve las dimensiones actuales de la imagen, bits y canales de imágenes AVIF; previamente, las dimensiones eran reportadas como `0x0`, y bits y canales no eran reportados en absoluto.
8.0.0 | Ahora se lanza una excepción ValueError si `filename` está vacío; anteriormente se generaba un `E_WARNING` y la función devolvía `false`.
7.1.0 | Añadido el soporte para WebP.

### Ejemplos

Ejemplo #2 Ejemplo con getimagesize()

    <?php
    list($width, $height, $type, $attr) = getimagesize("img/flag.jpg");
    echo "<img src=\"img/flag.jpg\" $attr alt=\"Ejemplo con getimagesize()\" />";
    ?>

Ejemplo #3 getimagesize() con una URL

    <?php
    $size = getimagesize("http://www.example.com/gifs/logo.gif");

    // Si el nombre del fichero contiene espacios, codifíquelo!
    $size = getimagesize("http://www.example.com/gifs/lo%20go.gif");

    ?>

Ejemplo #4 getimagesize() que devuelve IPTC

    <?php
    $size = getimagesize("testimg.jpg", $info);
    if (isset($info["APP13"])) {
        $iptc = iptcparse($info["APP13"]);
        var_dump($iptc);
    }
    ?>

### Notas

> Nota: Esta función no requiere la biblioteca GD.

### Ver también

- image_type_to_mime_type() - Obtiene el tipo MIME para el tipo de imagen devuelto por getimagesize, exif_read_data, exif_thumbnail, exif_imagetype
- exif_imagetype() - Determinar el tipo de una imagen
- exif_read_data() - Lee los encabezados EXIF en las imágenes
- exif_thumbnail() - Recupera la miniatura de una imagen
- imagesx() - Devuelve el ancho de una imagen
- imagesy() - Devuelve la altura de la imagen

# getimagesizefromstring

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

getimagesizefromstring — Obtiene el tamaño de una imagen desde una cadena

### Descripción

function getimagesizefromstring(string `$string`, array `&$image_info` = `null`): array|false

Idéntico a la función getimagesize() excepto que la función getimagesizefromstring() acepta una cadena en lugar de un nombre de fichero como primer argumento.

Consulte la documentación de la función getimagesize() para obtener más detalles sobre cómo funciona esta función.

### Parámetros

`string`

  Los datos de la imagen, en forma de cadena.

`image_info`

  Consulte la función getimagesize().

### Valores devueltos

Consulte la función getimagesize().

### Ejemplos

Ejemplo #1 Ejemplo con getimagesizefromstring()

    <?php
    $img = '/path/to/test.png';

    // Apertura mediante un fichero
    $size_info1 = getimagesize($img);

    // Apertura mediante una cadena
    $data       = file_get_contents($img);
    $size_info2 = getimagesizefromstring($data);
    ?>

### Ver también

- getimagesize() - Devuelve el tamaño de una imagen

# image_type_to_extension

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

image_type_to_extension — Devuelve la extensión del fichero para el tipo de imagen

### Descripción

function image_type_to_extension(int `$image_type`, bool `$include_dot` = `true`): string|false

image_type_to_extension() devuelve la extensión para la constante `IMAGETYPE_*` proporcionada.

### Parámetros

`image_type`

  Una de las constantes `IMAGETYPE_*`.

`include_dot`

  Si se debe añadir un punto a la extensión o no. Por omisión, vale `true`.

### Valores devueltos

Un string con la extensión, correspondiente al tipo de la imagen proporcionada, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con image_type_to_extension()

    <?php
    // Creación de una instancia de imagen
    $im = imagecreatetruecolor(100, 100);

    // Guardado de la imagen
    imagepng($im, './test' . image_type_to_extension(IMAGETYPE_PNG));
    ?>

### Notas

> Nota: Esta función no requiere la biblioteca GD.

# image_type_to_mime_type

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

image_type_to_mime_type — Obtiene el tipo MIME para el tipo de imagen devuelto por getimagesize, exif_read_data, exif_thumbnail, exif_imagetype

### Descripción

function image_type_to_mime_type(int `$image_type`): string

La función image_type_to_mime_type() determina el tipo MIME para una constante IMAGETYPE.

### Parámetros

`image_type`

  Una de las constantes `IMAGETYPE_*`.

### Valores devueltos

Los valores devueltos son los siguientes:

Valores constantes devueltos
`image_type` | Valor devuelto
--- | ---
`IMAGETYPE_GIF` | `image/gif`
`IMAGETYPE_JPEG` | `image/jpeg`
`IMAGETYPE_PNG` | `image/png`
`IMAGETYPE_SWF` | `application/x-shockwave-flash`
`IMAGETYPE_PSD` | `image/psd`
`IMAGETYPE_BMP` | `image/bmp`
`IMAGETYPE_TIFF_II` (orden de bytes intel) | `image/tiff`
`IMAGETYPE_TIFF_MM` (orden de bytes motorola) | `image/tiff`
`IMAGETYPE_JPC` | `application/octet-stream`
`IMAGETYPE_JP2` | `image/jp2`
`IMAGETYPE_JPX` | `application/octet-stream`
`IMAGETYPE_JB2` | `application/octet-stream`
`IMAGETYPE_SWC` | `application/x-shockwave-flash`
`IMAGETYPE_IFF` | `image/iff`
`IMAGETYPE_WBMP` | `image/vnd.wap.wbmp`
`IMAGETYPE_XBM` | `image/xbm`
`IMAGETYPE_ICO` | `image/vnd.microsoft.icon`
`IMAGETYPE_WEBP` | `image/webp`
`IMAGETYPE_AVIF` | `image/avif`
`IMAGETYPE_HEIF` | `image/heif`

### Ejemplos

Ejemplo #1 Ejemplo de image_type_to_mime_type()

    <?php
    header("Content-type: " . image_type_to_mime_type(IMAGETYPE_PNG));
    ?>

### Notas

> Nota: Esta función no requiere la biblioteca GD.

### Ver también

- getimagesize() - Devuelve el tamaño de una imagen
- exif_imagetype() - Determinar el tipo de una imagen
- exif_read_data() - Lee los encabezados EXIF en las imágenes
- exif_thumbnail() - Recupera la miniatura de una imagen

# image2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

image2wbmp — Enviar la imagen al navegador o a un archivo

Advertencia

Esta función está OBSOLETA a partir de PHP 7.3.0, y ha sido ELIMINADA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

function image2wbmp(resource `$image`, string `$filename` = ?, int `$foreground` = ?): bool

image2wbmp() muestra o guarda una versión WBMP de la imagen `image` proporcionada.

### Parámetros

`image`

  Un recurso de imagen, devuelto por una de las funciones de creación de imágenes, como imagecreatetruecolor().

`filename`

  Ruta del fichero de guardado. Si no se proporciona, el flujo de la imagen se mostrará directamente.

`foreground`

  El color del primer plano puede ser definido con este argumento proporcionando un identificador obtenido con imagecolorallocate(). El color del primer plano por omisión es negro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

Precaución

Sin embargo, si libgd no logra producir la imagen, esta función devuelve `true`.

### Ejemplos

Ejemplo #1 Ejemplo con image2wbmp()

    <?php

    $file = 'php.png';
    $image = imagecreatefrompng($file);

    header('Content-Type: ' . image_type_to_mime_type(IMAGETYPE_WBMP));
    image2wbmp($image); // Mostrar directamente

    ?>

### Ver también

- imagewbmp() - Enviar la imagen al navegador o a un archivo

# imageaffine

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffine — Devuelve una imagen que contiene la imagen fuente transformada, utilizando opcionalmente una zona de recorte

### Descripción

function imageaffine(GdImage `$image`, array `$affine`, ?array `$clip` = `null`): GdImage|false

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`affine`

  Un array con las claves de 0 a 5.

`clip`

  Un array con las claves "x", "y", "width" y "height"; o `null`.

### Valores devueltos

Devuelve el objeto de imagen vinculado en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `clip` ahora es nullable.
8.0.0 | En caso de éxito, esta función ahora devuelve una instancia de GDImage; anteriormente se devolvía un resource.

# imageaffinematrixconcat

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffinematrixconcat — Concatena dos matrices de transformación afín

### Descripción

function imageaffinematrixconcat(array `$matrix1`, array `$matrix2`): array|false

Devuelve la concatenación de dos matrices de transformación afín, lo cual es útil si varias transformaciones deben aplicarse a la misma imagen en una sola vez.

### Parámetros

`matrix1`

  Una matriz de transformación afín (un array con claves de `0` a `5` y números decimales como valores).

`matrix2`

  Una matriz de transformación afín (un array con claves de `0` a `5` y números decimales como valores).

### Valores devueltos

Una matriz de transformación afín (un array con claves de `0` a `5` y números decimales como valores). o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo para imageaffinematrixconcat()

    <?php
    $m1 = imageaffinematrixget(IMG_AFFINE_TRANSLATE, array('x' => 2, 'y' => 3));
    $m2 = imageaffinematrixget(IMG_AFFINE_SCALE, array('x' => 4, 'y' => 5));
    $matrix = imageaffinematrixconcat($m1, $m2);
    print_r($matrix);
    ?>

El ejemplo anterior mostrará:

    Array
    (
        [0] => 4
        [1] => 0
        [2] => 0
        [3] => 5
        [4] => 8
        [5] => 15
    )

### Ver también

- imageaffine() - Devuelve una imagen que contiene la imagen fuente transformada, utilizando opcionalmente una zona de recorte
- imageaffinematrixget() - Obtener una matriz de transformación afín

# imageaffinematrixget

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffinematrixget — Obtener una matriz de transformación afín

### Descripción

function imageaffinematrixget(int `$type`, array|float `$options`): array|false

Devuelve una matriz de transformación afín.

### Parámetros

`type`

  Una constante entre `IMG_AFFINE_*`.

`options`

  Si `type` es `IMG_AFFINE_TRANSLATE` o `IMG_AFFINE_SCALE`, `options` debe ser un array con las claves `x` y `y`, ambas con valores float.

  Si `type` es `IMG_AFFINE_ROTATE`, `IMG_AFFINE_SHEAR_HORIZONTAL` o `IMG_AFFINE_SHEAR_VERTICAL`, `options` debe ser un valor float que especifique el ángulo.

### Valores devueltos

Una matriz de transformación afín (un array con claves de `0` a `5` y números decimales como valores). o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo para imageaffinematrixget()

    <?php
    $matrix = imageaffinematrixget(IMG_AFFINE_TRANSLATE, array('x' => 2, 'y' => 3));
    print_r($matrix);
    ?>

El ejemplo anterior mostrará:

    Array
    (
        [0] => 1
        [1] => 0
        [2] => 0
        [3] => 1
        [4] => 2
        [5] => 3
    )

### Ver también

- imageaffine() - Devuelve una imagen que contiene la imagen fuente transformada, utilizando opcionalmente una zona de recorte
- imageaffinematrixconcat() - Concatena dos matrices de transformación afín

# imagealphablending

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagealphablending — Modifica el modo de mezcla de una imagen

### Descripción

function imagealphablending(GdImage `$image`, bool `$enable`): true

imagealphablending() proporciona dos modos de dibujo para imágenes en colores verdaderos (truecolors). En modo "mezcla", el canal alpha de cada color es proporcionado a cada función de dibujo, de modo que imagesetpixel() pueda determinar su transparencia. GD mezcla entonces automáticamente el color en ese punto y almacena el resultado en la imagen. El píxel resultante es entonces opaco. En modo no mezclante, el color es copiado literalmente con sus informaciones de canal alpha, y reemplaza el píxel de destino. La mezcla no está disponible con imágenes de paleta.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`enable`

  Si se debe activar el modo de mezcla o no. En imágenes de colores verdaderos, el valor por omisión es `true`, de lo contrario, el valor por omisión es `false`.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagealphablending()

    <?php
    // Creación de una imagen
    $im = imagecreatetruecolor(100, 100);

    // Define el alphablending a on
    imagealphablending($im, true);

    // Dibuja un rectángulo
    imagefilledrectangle($im, 30, 30, 70, 70, imagecolorallocate($im, 255, 0, 0));

    // Mostrar
    header('Content-Type: image/png');

    imagepng($im);
    ?>

# imageantialias

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imageantialias — Activar o desactivar las funciones de antialias

### Descripción

function imageantialias(GdImage `$image`, bool `$enable`): true

Activa los métodos de dibujo rápido antialias para líneas y polígonos. Los componentes alpha no son soportados. Funciona utilizando una operación directa de mezcla, únicamente con imágenes truecolor.

El grosor y los estilos no son soportados.

El uso de primitivas antialias con fondos transparentes puede llevar a resultados inesperados. El método de mezcla utiliza el color de fondo como cualquier otra color. La falta de soporte del componente alpha impide el uso de antialias basado en alpha.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`enable`

  Si se debe activar el antialias o no.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.
7.2.0 | imageantialias() ahora está generalmente disponible. Anteriormente, solo estaba disponible si PHP fue compilado con la versión agrupada de la biblioteca GD.

### Ejemplos

Ejemplo #1 Comparación de 2 líneas, una con antialias y otra sin

    <?php
    // Define una imagen antialias y una normal
    $aa = imagecreatetruecolor(400, 100);
    $normal = imagecreatetruecolor(200, 100);

    // Activa el antialiasing para una imagen
    imageantialias($aa, true);

    // Asigna los colores
    $red = imagecolorallocate($normal, 255, 0, 0);
    $red_aa = imagecolorallocate($aa, 255, 0, 0);

    // Dibuja 2 líneas, una con antialiasing
    imageline($normal, 0, 0, 200, 100, $red);
    imageline($aa, 0, 0, 200, 100, $red_aa);

    // Fusiona las 2 imágenes, lado a lado para la visualización
    // (AA: izquierda, Normal: derecha)
    imagecopymerge($aa, $normal, 200, 0, 0, 0, 200, 100, 100);

    // Muestra la imagen
    header('Content-type: image/png');

    imagepng($aa);
    ?>

Resultado del ejemplo anterior es similar a:

### Ver también

- imagecreatetruecolor() - Crea una nueva imagen en colores verdaderos

# imagearc

(PHP 4, PHP 5, PHP 7, PHP 8)

imagearc — Dibuja una elipse parcial

### Descripción

function imagearc(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$start_angle`,
int `$end_angle`,
int `$color`
): true

imagearc() dibuja una elipse parcial, centrada en las coordenadas proporcionadas.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`center_x`

  X: coordenada del centro.

`center_y`

  Y: coordenada del centro.

`width`

  El ancho de la elipse.

`height`

  La altura de la elipse.

`start_angle`

  El ángulo de inicio de la elipse, en grados.

`end_angle`

  El ángulo de fin de la elipse, en grados. 0° corresponde a la posición "tres horas" y la elipse es dibujada en el sentido de las agujas de un reloj.

`color`

  Un identificador de color creado con imagecolorallocate().

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Dibujar un círculo con imagearc()

    <?php

    // Creación de una imagen 200*200
    $img = imagecreatetruecolor(200, 200);

    // Asignación de colores
    $white = imagecolorallocate($img, 255, 255, 255);
    $red   = imagecolorallocate($img, 255,   0,   0);
    $green = imagecolorallocate($img,   0, 255,   0);
    $blue  = imagecolorallocate($img,   0,   0, 255);

    // Dibujar la cabeza
    imagearc($img, 100, 100, 200, 200,  0, 360, $white);
    // La boca
    imagearc($img, 100, 100, 150, 150, 25, 155, $red);
    // Los ojos izquierdo y derecho
    imagearc($img,  60,  75,  50,  50,  0, 360, $green);
    imagearc($img, 140,  75,  50,  50,  0, 360, $blue);

    // Mostrar en el navegador
    header("Content-type: image/png");
    imagepng($img);

    ?>

Resultado del ejemplo anterior es similar a:

### Ver también

- imagefilledarc() - Dibuja un arco parcial y lo rellena
- imageellipse() - Dibuja una elipse
- imagefilledellipse() - Dibuja una elipse llena

# imageavif

(PHP 8 >= 8.1.0)

imageavif — Enviar la imagen al navegador o a un archivo

### Descripción

function imageavif(
GdImage `$image`,
resource|string|null `$file` = `null`,
int `$quality` = -1,
int `$speed` = -1
): bool

Muestra o guarda una imagen en formato AVIF utilizando la `image` proporcionada.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`file`

  La ruta o un recurso de flujo abierto (que se cierra automáticamente después de que esta función retorne) donde guardar el archivo. Si no se define o es `null`, el flujo de imagen sin procesar se enviará directamente.

`quality`

  `quality` es un argumento opcional cuyo rango varía de 0 (peor calidad, archivo más pequeño) a 100 (mejor calidad, archivo más grande). Si se pasa `-1` como argumento, se utilizará el valor por omisión `52`.

`speed`

  `speed` es un argumento opcional cuyo rango varía de 0 (codificación lenta, archivo más pequeño) a 10 (codificación rápida, archivo más grande). Si se pasa `-1` como argumento, se utilizará el valor por omisión `6`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

Precaución

Sin embargo, si libgd no logra producir la imagen, esta función devuelve `true`.

### Errores/Excepciones

Genera una ValueError si `quality` o `speed` no es válido.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Genera ahora una ValueError si `quality` o `speed` no es válido.

### Ver también

- imagepng() - Envía una imagen PNG a un navegador o a un fichero
- imagewbmp() - Enviar la imagen al navegador o a un archivo
- imagejpeg() - Enviar la imagen al navegador o a un archivo
- imagetypes() - Devuelve los tipos de imágenes soportados por la versión actual de PHP

# imagebmp

(PHP 7 >= 7.2.0, PHP 8)

imagebmp — Muestra o guarda una imagen BMP en el navegador o en un fichero

### Descripción

function imagebmp(GdImage `$image`, resource|string|null `$file` = `null`, bool `$compressed` = `true`): bool

Muestra o guarda una versión BMP de la `image` proporcionada.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`file`

  La ruta o un recurso de flujo abierto (que se cierra automáticamente después de que esta función retorne) donde guardar el archivo. Si no se define o es `null`, el flujo de imagen sin procesar se enviará directamente.

  > Nota:

  > `null` no es válido si el argumento `compressed` no se utiliza.

`compressed`

  Si el BMP debe ser comprimido con `run-length encoding` (RLE), o no.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

Precaución

Sin embargo, si libgd no logra producir la imagen, esta función devuelve `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.
8.0.0 | El tipo de `compressed` es ahora bool; anteriormente era int.

### Ejemplos

Ejemplo #1 Guardar un fichero BMP

    <?php
    // Crear una imagen en blanco y añadir texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);

    imagestring($im, 1, 5, 5,  'BMP con PHP', $text_color);

    // Guardar la imagen
    imagebmp($im, 'php.bmp');
    ?>

# imagechar

(PHP 4, PHP 5, PHP 7, PHP 8)

imagechar — Dibuja un carácter horizontalmente

### Descripción

function imagechar(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$char`,
int `$color`
): true

imagechar() dibuja el primer carácter de la cadena `char` en la imagen `image` con la esquina superior izquierda situada en la posición `x`,`y` (la esquina superior izquierda es el origen (0,0)) con el color `color`.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`font`
  Puede ser 1, 2, 3, 4, 5 para las fuentes internas de codificación Latin2 (donde los números más grandes corresponden a fuentes anchas) o una instancia de GdFont retornado por imageloadfont().
`x`

  X: coordenada de inicio.

`y`

  Y: coordenada de inicio.

`char`

  El carácter a dibujar.

`color`

  Un identificador de color creado con imagecolorallocate().

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `font` ahora acepta una instancia de GdFont y un int; anteriormente solo un int era aceptado.
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagechar()

    <?php

    $im = imagecreate(100, 100);

    $string = 'PHP';

    $bg = imagecolorallocate($im, 255, 255, 255);
    $black = imagecolorallocate($im, 0, 0, 0);

    // muestra un "P" negro en la esquina superior izquierda
    imagechar($im, 1, 0, 0, $string, $black);

    header('Content-type: image/png');
    imagepng($im);

    ?>

Resultado del ejemplo anterior es similar a:

### Ver también

- imagecharup() - Dibuja un carácter verticalmente
- imageloadfont() - Carga una nueva fuente

# imagecharup

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecharup — Dibuja un carácter verticalmente

### Descripción

function imagecharup(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$char`,
int `$color`
): true

Dibuja el primer carácter de la cadena `char` verticalmente en la imagen `image` proporcionada.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`font`
  Puede ser 1, 2, 3, 4, 5 para las fuentes internas de codificación Latin2 (donde los números más grandes corresponden a fuentes anchas) o una instancia de GdFont retornado por imageloadfont().
`x`

  X: coordenada de inicio.

`y`

  Y: coordenada de inicio.

`char`

  El carácter a dibujar.

`color`

  Un identificador de color creado con imagecolorallocate().

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `font` ahora acepta una instancia de GdFont y un int; anteriormente solo un int era aceptado.
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagecharup()

    <?php

    $im = imagecreate(100, 100);

    $string = 'Notez que la première lettre est un N';

    $bg = imagecolorallocate($im, 255, 255, 255);
    $black = imagecolorallocate($im, 0, 0, 0);

    // Muestra una "Z" negra sobre un fondo blanco
    imagecharup($im, 3, 10, 10, $string, $black);

    header('Content-type: image/png');
    imagepng($im);

    ?>

Resultado del ejemplo anterior es similar a:

### Ver también

- imagechar() - Dibuja un carácter horizontalmente
- imageloadfont() - Carga una nueva fuente

# imagecolorallocate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorallocate — Asigna una coloración para una imagen

### Descripción

function imagecolorallocate(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int|false

Devuelve un identificador de color, representando la coloración compuesta con los colores RGB.

imagecolorallocate() debe ser invocada para crear cada color que será representado por `image`.

> Nota:

> La primera llamada a imagecolorallocate() llena la coloración de fondo con la paleta de las imágenes - imágenes creadas utilizando imagecreate().

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`red`

  Valor del componente rojo.

`green`

  Valor del componente verde.

`blue`

  Valor del componente azul.

Estos argumentos son enteros comprendidos entre 0 y 255 o hexadecimales comprendidos entre 0x00 y 0xFF.

### Valores devueltos

Un identificador de color o `false` si la asignación falla.

Advertencia

Esta función puede retornar `false`, pero también puede retornar un valor equivalente a `false`. Por favor, lea la sección sobre los booleanos para más información. Utilice el operador === para probar el valor de retorno exacto de esta función.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagecolorallocate()

    <?php

    $im = imagecreate(100, 100);

    // El fondo de la imagen es rojo
    $background = imagecolorallocate($im, 255, 0, 0);

    // Se definen colores con enteros ..
    $white = imagecolorallocate($im, 255, 255, 255);
    $black = imagecolorallocate($im, 0, 0, 0);

    // .. o hexadecimales
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
    $black = imagecolorallocate($im, 0x00, 0x00, 0x00);

    ?>

### Ver también

- imagecolorallocatealpha() - Asigna un color a una imagen
- imagecolordeallocate() - Elimina un color de una imagen

# imagecolorallocatealpha

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imagecolorallocatealpha — Asigna un color a una imagen

### Descripción

function imagecolorallocatealpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int|false

imagecolorallocatealpha() se comporta como imagecolorallocate() con el parámetro adicional de transparencia `alpha`.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`red`

  Valor del componente rojo.

`green`

  Valor del componente verde.

`blue`

  Valor del componente azul.

`alpha`

  Un valor entre `0` y `127`. `0` indica opacidad completa mientras que `127` indica transparencia completa.

Los parámetros `red`, `green` y `blue` son enteros comprendidos entre 0 y 255, o hexadecimales comprendidos entre 0x00 y 0xFF.

### Valores devueltos

Un identificador de color o `false` si la asignación falla.

Advertencia

Esta función puede retornar `false`, pero también puede retornar un valor equivalente a `false`. Por favor, lea la sección sobre los booleanos para más información. Utilice el operador === para probar el valor de retorno exacto de esta función.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo de uso de imagecolorallocatealpha()

    <?php
    $size = 300;
    $image=imagecreatetruecolor($size, $size);

    // algo para obtener un fondo blanco con un borde negro
    $back = imagecolorallocate($image, 255, 255, 255);
    $border = imagecolorallocate($image, 0, 0, 0);
    imagefilledrectangle($image, 0, 0, $size - 1, $size - 1, $back);
    imagerectangle($image, 0, 0, $size - 1, $size - 1, $border);

    $yellow_x = 100;
    $yellow_y = 75;
    $red_x    = 120;
    $red_y    = 165;
    $blue_x   = 187;
    $blue_y   = 125;
    $radius   = 150;

    // asigna colores con valores alpha
    $yellow = imagecolorallocatealpha($image, 255, 255, 0, 75);
    $red    = imagecolorallocatealpha($image, 255, 0, 0, 75);
    $blue   = imagecolorallocatealpha($image, 0, 0, 255, 75);

    // Dibuja 3 elipses
    imagefilledellipse($image, $yellow_x, $yellow_y, $radius, $radius, $yellow);
    imagefilledellipse($image, $red_x, $red_y, $radius, $radius, $red);
    imagefilledellipse($image, $blue_x, $blue_y, $radius, $radius, $blue);

    // No olvidar enviar un header correcto
    header('Content-Type: image/png');

    // y finalmente, mostrar el resultado
    imagepng($image);
    ?>

Resultado del ejemplo anterior es similar a:

Ejemplo #2 Conversión de valor alpha típico para usarlo con imagecolorallocatealpha()

Generalmente los valores alpha `0` designan los píxeles completamente transparentes, y el canal alpha tiene 8 bits. Para convertir tales valores alpha para ser compatibles con imagecolorallocatealpha(), un poco de aritmética simple es suficiente:

    <?php
    $alpha8 = 0; // completamente transparente
    var_dump(127 - ($alpha8 >> 1));
    $alpha8 = 255; // completamente opaco
    var_dump(127 - ($alpha8 >> 1));
    ?>

El ejemplo anterior mostrará:

    int(127)
    int(0)

### Ver también

- imagecolorallocate() - Asigna una coloración para una imagen
- imagecolordeallocate() - Elimina un color de una imagen

# imagecolorat

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorat — Devuelve el índice del color de un píxel dado

### Descripción

function imagecolorat(GdImage `$image`, int `$x`, int `$y`): int|false

Devuelve el índice del color del píxel situado en las coordenadas especificadas, en la imagen `image`.

Si la imagen es una imagen en TrueColor, esta función devuelve el valor RGB del píxel, en forma de un entero. Utilizar los operadores a nivel de bits y los máscaras para distinguir el rojo, del verde y del azul :

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`x`

  X : coordenada del punto.

`y`

  Y : coordenada del punto.

### Valores devueltos

Devuelve el índice del color o `false` si ocurre un error.

Advertencia

Esta función puede retornar `false`, pero también puede retornar un valor equivalente a `false`. Por favor, lea la sección sobre los booleanos para más información. Utilice el operador === para probar el valor de retorno exacto de esta función.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Acceso a los valores RGB

    <?php
    $im = imagecreatefrompng("php.png");
    $rgb = imagecolorat($im, 10, 15);
    $r = ($rgb >> 16) & 0xFF;
    $g = ($rgb >> 8) & 0xFF;
    $b = $rgb & 0xFF;
    var_dump($r, $g, $b);
    ?>

Resultado del ejemplo anterior es similar a:

    int(119)
    int(123)
    int(180)

Ejemplo #2 Valores RVB legibles utilizando la función imagecolorsforindex()

    <?php
    $im = imagecreatefrompng("php.png");
    $rgb = imagecolorat($im, 10, 15);

    $colors = imagecolorsforindex($im, $rgb);

    var_dump($colors);
    ?>

Resultado del ejemplo anterior es similar a:

    array(4) {
      ["red"]=>
      int(119)
      ["green"]=>
      int(123)
      ["blue"]=>
      int(180)
      ["alpha"]=>
      int(127)
    }

### Ver también

- imagecolorset() - Cambia el color en una paleta en el índice dado
- imagecolorsforindex() - Retorna el color asociado a un índice
- imagesetpixel() - Dibuja un píxel

# imagecolorclosest

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorclosest — Devuelve el índice de la color más cercana a una color dada

### Descripción

function imagecolorclosest(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

Devuelve el índice de la color de la paleta que es la más cercana al valor RGB pasado.

La "distancia" entre la color deseada y las colores de la paleta se calcula considerando el espacio RGB como un espacio de 3 dimensiones.

Si la imagen fue creada a partir de un archivo, solo se resuelven los colores utilizados en la imagen. Los colores presentes únicamente en la paleta no se resuelven.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`red`

  Valor del componente rojo.

`green`

  Valor del componente verde.

`blue`

  Valor del componente azul.

Los argumentos sobre las colores son enteros comprendidos entre 0 y 255 o hexadecimales comprendidos entre 0x00 y 0xFF.

### Valores devueltos

Devuelve el índice de la color más cercana, en la paleta de la imagen, a la dada.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Búsqueda de un juego de colores en una imagen

    <?php
    // Se comienza con una imagen y se convierte en una imagen de paleta
    $im = imagecreatefrompng('figures/imagecolorclosest.png');
    imagetruecolortopalette($im, false, 255);

    // Colores buscados (RGB)
    $colors = array(
        array(254, 145, 154),
        array(153, 145, 188),
        array(153, 90, 145),
        array(255, 137, 92)
    );

    // Se itera sobre cada búsqueda y se encuentra la color de la paleta más cercana.
    // Devuelve el número de la búsqueda, el RGB buscado y la correspondencia en RGB
    foreach($colors as $id => $rgb)
    {
        $result = imagecolorclosest($im, $rgb[0], $rgb[1], $rgb[2]);
        $result = imagecolorsforindex($im, $result);
        $result = "({$result['red']}, {$result['green']}, {$result['blue']})";

        echo "#$id: Búsqueda ($rgb[0], $rgb[1], $rgb[2]); Correspondencia : $result.\n";
    }

    ?>

Resultado del ejemplo anterior es similar a:

    #0: Búsqueda (254, 145, 154); Correspondencia : (252, 150, 148).
    #1: Búsqueda (153, 145, 188); Correspondencia : (148, 150, 196).
    #2: Búsqueda (153, 90, 145); Correspondencia : (148, 90, 156).
    #3: Búsqueda (255, 137, 92); Correspondencia : (252, 150, 92).

### Ver también

- imagecolorexact() - Devuelve el índice del color especificado
- imagecolorclosestalpha() - Devuelve el color más cercano, teniendo en cuenta el canal alpha
- imagecolorclosesthwb() - Obtiene el índice de la color especificada con su tono, blanco y negro

# imagecolorclosestalpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorclosestalpha — Devuelve el color más cercano, teniendo en cuenta el canal alpha

### Descripción

function imagecolorclosestalpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int

Devuelve el índice del color, en la paleta de la imagen `image`, más cercano al color especificado por los demás parámetros, en formato RGB y con canal alpha `alpha`.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`red`

  Valor del componente rojo.

`green`

  Valor del componente verde.

`blue`

  Valor del componente azul.

`alpha`

  Un valor comprendido entre `0` y `127`. `0` indica una opacidad completa mientras que `127` indica una transparencia completa.

Los parámetros sobre los colores son enteros comprendidos entre 0 y 255 o hexadecimales comprendidos entre 0x00 y 0xFF.

### Valores devueltos

Devuelve el índice del color más cercano en la paleta.

### Ejemplos

Ejemplo #1 Busca un juego de colores en una imagen

    <?php
    // Se comienza con una imagen y se la convierte en paleta
    $im = imagecreatefrompng('figures/imagecolorclosest.png');
    imagetruecolortopalette($im, false, 255);

    // Búsqueda de colores (RGB)
    $colors = array(
        array(254, 145, 154, 50),
        array(153, 145, 188, 127),
        array(153, 90, 145, 0),
        array(255, 137, 92, 84)
    );

    // Se itera sobre cada búsqueda y se encuentra el color más cercano de la paleta.
    // Devuelve el número de la búsqueda, la búsqueda RGB y el resultado convertido en RGB
    foreach($colors as $id => $rgb)
    {
        $result = imagecolorclosestalpha($im, $rgb[0], $rgb[1], $rgb[2], $rgb[3]);
        $result = imagecolorsforindex($im, $result);
        $result = "({$result['red']}, {$result['green']}, {$result['blue']}, {$result['alpha']})";

        echo "#$id: Búsqueda ($rgb[0], $rgb[1], $rgb[2], $rgb[3]); Resultado más cercano: $result.\n";
    }

    ?>

Resultado del ejemplo anterior es similar a:

    #0: Búsqueda (254, 145, 154, 50); Resultado más cercano : (252, 150, 148, 0).
    #1: Búsqueda (153, 145, 188, 127); Resultado más cercano : (148, 150, 196, 0).
    #2: Búsqueda (153, 90, 145, 0); Resultado más cercano : (148, 90, 156, 0).
    #3: Búsqueda (255, 137, 92, 84); Resultado más cercano : (252, 150, 92, 0).

### Ver también

- imagecolorexactalpha() - Devuelve el índice de un color con su canal alfa
- imagecolorclosest() - Devuelve el índice de la color más cercana a una color dada
- imagecolorclosesthwb() - Obtiene el índice de la color especificada con su tono, blanco y negro

# imagecolorclosesthwb

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecolorclosesthwb — Obtiene el índice de la color especificada con su tono, blanco y negro

### Descripción

function imagecolorclosesthwb(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

Obtiene el índice de la color especificada con su tono, blanco y negro.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`red`

  Valor del componente rojo.

`green`

  Valor del componente verde.

`blue`

  Valor del componente azul.

### Valores devueltos

Devuelve un integer que representa el índice de la color.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagecolorclosesthwb()

    <?php
    $im = imagecreatefromgif('php.gif');

    echo 'HWB : ' . imagecolorclosesthwb($im, 116, 115, 152);
    ?>

Resultado del ejemplo anterior es similar a:

    HWB: 33

### Ver también

- imagecolorclosest() - Devuelve el índice de la color más cercana a una color dada

# imagecolordeallocate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolordeallocate — Elimina un color de una imagen

### Descripción

function imagecolordeallocate(GdImage `$image`, int `$color`): true

Elimina el color `color` previamente asignado con la función imagecolorallocate(), para la imagen `image`.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`color`

  El identificador del color.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagecolordeallocate()

    <?php
    $white = imagecolorallocate($im, 255, 255, 255);
    imagecolordeallocate($im, $white);
    ?>

### Ver también

- imagecolorallocate() - Asigna una coloración para una imagen
- imagecolorallocatealpha() - Asigna un color a una imagen

# imagecolorexact

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorexact — Devuelve el índice del color especificado

### Descripción

function imagecolorexact(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

Devuelve el índice del color especificado en la paleta de la imagen `image`.

Si la imagen fue creada a partir de un archivo, solo se resuelven los colores utilizados en la imagen. Los colores presentes únicamente en la paleta no se resuelven.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`red`

  Valor del componente rojo.

`green`

  Valor del componente verde.

`blue`

  Valor del componente azul.

### Valores devueltos

Devuelve el índice del color especificado en la paleta, o -1 si el color no existe.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Obtención de los colores que componen el logo GD

    <?php
    // Define la imagen
    $im = imagecreatefrompng('./gdlogo.png');

    $colors   = Array();
    $colors[] = imagecolorexact($im, 255, 0, 0);
    $colors[] = imagecolorexact($im, 0, 0, 0);
    $colors[] = imagecolorexact($im, 255, 255, 255);
    $colors[] = imagecolorexact($im, 100, 255, 52);

    print_r($colors);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => 16711680
        [1] => 0
        [2] => 16777215
        [3] => 6618932
    )

### Ver también

- imagecolorclosest() - Devuelve el índice de la color más cercana a una color dada

# imagecolorexactalpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorexactalpha — Devuelve el índice de un color con su canal alfa

### Descripción

function imagecolorexactalpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int

Devuelve el índice de un color con su canal alfa.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`red`

  Valor del componente rojo.

`green`

  Valor del componente verde.

`blue`

  Valor del componente azul.

`alpha`

  Un valor comprendido entre `0` y `127`. `0` indica una opacidad completa mientras que `127` indica una transparencia completa.

Los parámetros sobre los colores son enteros comprendidos entre 0 y 255 o hexadecimales comprendidos entre 0x00 y 0xFF.

### Valores devueltos

Devuelve el índice del color proporcionado y su canal alfa en la paleta de la imagen, o -1 si el color no existe en la paleta de la imagen.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Obtención de los colores que componen el logo GD

    <?php

    // Define la imagen
    $im = imagecreatefrompng('./gdlogo.png');

    $colors   = Array();
    $colors[] = imagecolorexactalpha($im, 255, 0, 0, 0);
    $colors[] = imagecolorexactalpha($im, 0, 0, 0, 127);
    $colors[] = imagecolorexactalpha($im, 255, 255, 255, 55);
    $colors[] = imagecolorexactalpha($im, 100, 255, 52, 20);

    print_r($colors);

    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => 16711680
        [1] => 2130706432
        [2] => 939524095
        [3] => 342163252
    )

### Ver también

- imagecolorclosestalpha() - Devuelve el color más cercano, teniendo en cuenta el canal alpha

# imagecolormatch

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagecolormatch — Hace que las colores de la versión palette de una imagen coincidan más con las de su versión truecolor

### Descripción

function imagecolormatch(GdImage `$image1`, GdImage `$image2`): true

Hace que las colores de la versión palette de una imagen coincidan más con las de su versión truecolor.

### Parámetros

`image1`

  Un objeto de imagen truecolor.

`image2`

  Un objeto de imagen palette que apunta a una imagen que tiene el mismo tamaño que `image1`.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image1` y `image2` ahora requieren instancias de GdImage; anteriormente se esperaban resources

### Ejemplos

Ejemplo #1 Ejemplo con imagecolormatch()

    <?php
    // Define la imagen true color y la palette
    $im1 = imagecreatefrompng('./gdlogo.png');
    $im2 = imagecreate(imagesx($im1), imagesy($im1));

    // Añade algunas colores a $im2
    $colors   = Array();
    $colors[] = imagecolorallocate($im2, 255, 36, 74);
    $colors[] = imagecolorallocate($im2, 40, 0, 240);
    $colors[] = imagecolorallocate($im2, 82, 100, 255);
    $colors[] = imagecolorallocate($im2, 84, 63, 44);

    // Hace que estas colores coincidan con la imagen true color
    imagecolormatch($im1, $im2);
    ?>

### Ver también

- imagecreatetruecolor() - Crea una nueva imagen en colores verdaderos

# imagecolorresolve

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorresolve — Devuelve el índice de la color dada, o la más cercana posible

### Descripción

function imagecolorresolve(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

imagecolorresolve() devuelve un índice de color en todos los casos. O bien encuentra la color solicitada en la paleta, o bien encuentra la color más cercana.

Si la imagen fue creada a partir de un archivo, solo se resuelven los colores utilizados en la imagen. Los colores presentes únicamente en la paleta no se resuelven.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`red`

  Valor del componente rojo.

`green`

  Valor del componente verde.

`blue`

  Valor del componente azul.

### Valores devueltos

Devuelve un índice de color.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagecoloresolve() para obtener las colores de una imagen

    <?php
    // Carga de una imagen
    $im = imagecreatefromgif('phplogo.gif');

    // Obtención de las colores más cercanas de la imagen
    $colors = array();
    $colors[] = imagecolorresolve($im, 255, 255, 255);
    $colors[] = imagecolorresolve($im, 0, 0, 200)

    // Mostrar
    print_r($colors);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => 89
        [1] => 85
    )

### Ver también

- imagecolorclosest() - Devuelve el índice de la color más cercana a una color dada

# imagecolorresolvealpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorresolvealpha — Devuelve un índice de color o su alternativa más cercana, incluyendo el canal alpha

### Descripción

function imagecolorresolvealpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int

imagecolorresolvealpha() siempre devuelve un índice de color, disponible en la paleta de la imagen `image`: ya sea el color exacto o la mejor aproximación.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`red`

  Valor del componente rojo.

`green`

  Valor del componente verde.

`blue`

  Valor del componente azul.

`alpha`

  Un valor comprendido entre `0` y `127`. `0` indica una opacidad completa mientras que `127` indica una transparencia completa.

Los parámetros sobre los colores son enteros entre 0 y 255 o hexadecimales comprendidos entre 0x00 y 0xFF.

### Valores devueltos

Devuelve un índice de color.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagecoloresolve() para recuperar los colores de una imagen

    <?php
    // Carga de la imagen
    $im = imagecreatefromgif('phplogo.gif');

    // Recuperación de los colores más cercanos de la imagen
    $colors = array();
    $colors[] = imagecolorresolvealpha($im, 255, 255, 255, 0);
    $colors[] = imagecolorresolvealpha($im, 0, 0, 200, 127);

    // Mostrar
    print_r($colors);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => 89
        [1] => 85
    )

### Ver también

- imagecolorclosestalpha() - Devuelve el color más cercano, teniendo en cuenta el canal alpha

# imagecolorset

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorset — Cambia el color en una paleta en el índice dado

### Descripción

function imagecolorset(
GdImage `$image`,
int `$color`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha` = 0
): ?false

Permite asignar a un índice de una paleta un color específico. Es una función muy práctica para realizar relleno de color sin hacerlo realmente.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`color`

  Un índice de la paleta.

`red`

  Valor del componente rojo.

`green`

  Valor del componente verde.

`blue`

  Valor del componente azul.

`alpha`

  Valor del componente alpha.

### Valores devueltos

La función devuelve `null` en caso de éxito, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagecolorset()

    <?php
    // Creación de una imagen de 300x100 píxeles
    $im = imagecreate(300, 100);

    // Define el color de fondo a rojo
    imagecolorallocate($im, 255, 0, 0);

    // Obtención del índice del color de fondo
    $bg = imagecolorat($im, 0, 0);

    // Define el color de fondo a azul
    imagecolorset($im, $bg, 0, 0, 255);

    // Muestra la imagen en el navegador
    header('Content-Type: image/png');

    imagepng($im);
    ?>

### Ver también

- imagecolorat() - Devuelve el índice del color de un píxel dado

# imagecolorsforindex

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorsforindex — Retorna el color asociado a un índice

### Descripción

function imagecolorsforindex(GdImage `$image`, int `$color`): array

Retorna el color asociado a un índice especificado.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`color`

  El índice del color.

### Valores devueltos

Retorna un array asociativo con las claves `"red"`, `"green"`, `"blue"` y `"alpha"` que contienen los valores para el índice del color especificado.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.
8.0.0 | La función imagecolorsforindex() ahora lanza una excepción ValueError si `color` está fuera de rango; anteriormente, se retornaba `false` en su lugar.

### Ejemplos

Ejemplo #1 Ejemplo con imagecolorsforindex()

    <?php

    // se abre una imagen
    $im = imagecreatefrompng('nexen.png');

    // se obtiene un color
    $start_x = 40;
    $start_y = 50;
    $color_index = imagecolorat($im, $start_x, $start_y);

    // se lo hace legible
    $color_tran = imagecolorsforindex($im, $color_index);

    // ¿Cuál es?
    print_r($color_tran);

    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
       [red] => 226
       [green] => 222
       [blue] => 252
       [alpha] => 0
    )

### Ver también

- imagecolorat() - Devuelve el índice del color de un píxel dado
- imagecolorexact() - Devuelve el índice del color especificado

# imagecolorstotal

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorstotal — Calcula el número de colores de una paleta

### Descripción

function imagecolorstotal(GdImage `$image`): int

Devuelve el número de colores de la paleta de la imagen.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().

### Valores devueltos

Devuelve el número de colores de la paleta para la imagen `image` o 0 para las imágenes truecolor.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Obtención del número total de colores en una imagen utilizando la función imagecolorstotal()

    <?php
    // Creación de una instancia de imagen
    $im = imagecreatefromgif('php.gif');

    echo 'Número total de colores en la imagen : ' . imagecolorstotal($im);
    ?>

Resultado del ejemplo anterior es similar a:

    Número total de colores en la imagen : 128

### Ver también

- imagecolorat() - Devuelve el índice del color de un píxel dado
- imagecolorsforindex() - Retorna el color asociado a un índice
- imageistruecolor() - Determina si una imagen es una imagen truecolor

# imagecolortransparent

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolortransparent — Define la color transparente

### Descripción

function imagecolortransparent(GdImage `$image`, ?int `$color` = `null`): int

Obtiene o define la color transparente para la `image` proporcionada.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`color`

  Un identificador de color creado con imagecolorallocate().

### Valores devueltos

Se devuelve el identificador de la nueva color transparente (o la actual, si no se especifica ninguna). Si el argumento `color` es `null` y la imagen no tiene color transparente, el identificador devuelto será `-1`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.
8.0.0 | `color` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con imagecolortransparent()

    <?php
    // Creación de una imagen de 55x30
    $im = imagecreatetruecolor(55, 30);
    $red = imagecolorallocate($im, 255, 0, 0);
    $black = imagecolorallocate($im, 0, 0, 0);

    // Se hace el fondo transparente
    imagecolortransparent($im, $black);

    // Se dibuja un rectángulo rojo
    imagefilledrectangle($im, 4, 4, 50, 25, $red);

    // Se guarda la imagen
    imagepng($im, './imagecolortransparent.png');
    ?>

Resultado del ejemplo anterior es similar a:

### Notas

> Nota: La transparencia se copia únicamente con la función imagecopymerge() y las imágenes en color verdadero, no con la función imagecopy() ni las imágenes de paleta.

> Nota:

> La color de transparencia es una propiedad de la imagen, no es una propiedad de la color. Una vez que se ha definido la color de transparencia, cada región de la imagen de esa color que se haya dibujado previamente será transparente.

# imageconvolution

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

imageconvolution — Aplica una matriz de convolución 3x3, utilizando el coeficiente y el desplazamiento

### Descripción

function imageconvolution(
GdImage `$image`,
array `$matrix`,
float `$divisor`,
float `$offset`
): bool

imageconvolution() aplica una matriz de convolución 3x3, utilizando el coeficiente `div` y el desplazamiento `offset`.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`matrix`

  Una matriz 3x3: un array que contiene tres arrays de tres números de punto flotante.

`divisor`

  El divisor del resultado de la convolución, utilizado para la normalización.

`offset`

  La posición del color.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Impresión del logo PHP.net con imageconvolution()

    <?php
    $image = imagecreatefromgif('http://www.php.net/images/php.gif');

    $emboss = array(array(2, 0, 0), array(0, -1, 0), array(0, 0, -1));
    imageconvolution($image, $emboss, 1, 127);

    header('Content-Type: image/png');
    imagepng($image, null, 9);
    ?>

El ejemplo anterior mostrará:

Ejemplo #2 Desenfoque gaussiano con imageconvolution()

    <?php
    $image = imagecreatetruecolor(180,40);

    // Escribe el texto y aplica un desenfoque gaussiano a la imagen
    imagestring($image, 5, 10, 8, 'Texto desenfocado gaussiano', 0x00ff00);
    $gaussian = array(array(1.0, 2.0, 1.0), array(2.0, 4.0, 2.0), array(1.0, 2.0, 1.0));
    imageconvolution($image, $gaussian, 16, 0);

    // Reescribe el texto para la comparación
    imagestring($image, 5, 10, 18, 'Texto desenfocado gaussiano', 0x00ff00);

    header('Content-Type: image/png');
    imagepng($image, null, 9);
    ?>

El ejemplo anterior mostrará:

### Ver también

- imagefilter() - Aplica un filtro a una imagen

# imagecopy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecopy — Copia una parte de una imagen

### Descripción

function imagecopy(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$src_width`,
int `$src_height`
): true

Copia una parte de la imagen `src_image` a la imagen de destino `dst_image`, comenzando en las coordenadas `src_x`, `src_y` y con un ancho de `src_width` y una altura de `src_height`. La porción así definida será copiada y colocada en las coordenadas `dst_x` y `dst_y`.

### Parámetros

`dst_image`

  Recurso de imagen de destino.

`src_image`

  Recurso de imagen de origen.

`dst_x`

  X: coordenadas del punto de destino.

`dst_y`

  Y: coordenadas del punto de destino.

`src_x`

  X: coordenadas del punto origen.

`src_y`

  Y: coordenadas del punto origen.

`src_width`

  Ancho de la fuente.

`src_height`

  Altura de la fuente.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `dst_image` y `src_image` ahora requieren instancias de GdImage; anteriormente se esperaban resources.

### Ejemplos

Ejemplo #1 Se recorta el logo PHP.net

    <?php
    // Creación de las instancias de imagen
    $src = imagecreatefromgif('php.gif');
    $dest = imagecreatetruecolor(80, 40);

    // Copia
    imagecopy($dest, $src, 0, 0, 20, 13, 80, 40);

    // Visualización y liberación de la memoria
    header('Content-Type: image/gif');
    imagegif($dest);
    ?>

Resultado del ejemplo anterior es similar a:

### Ver también

- imagecrop() - Recorta una imagen en el rectángulo dado

# imagecopymerge

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecopymerge — Copia y fusiona una parte de una imagen

### Descripción

function imagecopymerge(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$src_width`,
int `$src_height`,
int `$pct`
): true

Copia una parte de la imagen `src_image` en la imagen de destino `dst_image` comenzando en las coordenadas (`src_x`, `src_y`), con el ancho `src_width` y la altura `src_height`. La zona de la imagen así definida será copiada en las coordenadas (`dst_x`, `dst_y`), en la imagen de destino.

### Parámetros

`dst_image`

  Recurso de imagen de destino.

`src_image`

  Recurso de imagen de origen.

`dst_x`

  X: coordenada del punto de destino.

`dst_y`

  Y: coordenada del punto de destino.

`src_x`

  X: coordenada del punto origen.

`src_y`

  Y: coordenada del punto origen.

`src_width`

  Ancho de la fuente.

`src_height`

  Altura de la fuente.

`pct`
  Las dos imágenes serán fusionadas según el argumento `pct`, que puede valer de 0 a 100. Si `pct` = 0, no se realiza ninguna acción, mientras que si `pct` = 100, imagecopymerge() se comporta exactamente como imagecopy() para las imágenes de paleta, excepto por la ignorancia de los componentes alpha, mientras que implementa la transparencia alpha para las imágenes en color verdadero.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `dst_image` y `src_image` ahora esperan instancias de GdImage; anteriormente, se esperaban resources.

### Ejemplos

Ejemplo #1 Fusiona 2 copias del logo PHP.net con 75% de transparencia

    <?php
    // Creación de las instancias de imagen
    $dest = imagecreatefromgif('php.gif');
    $src = imagecreatefromgif('php.gif');

    // Copia y fusiona
    imagecopymerge($dest, $src, 10, 10, 0, 0, 100, 47, 75);

    // Mostrar y liberar la memoria
    header('Content-Type: image/gif');
    imagegif($dest);
    ?>

# imagecopymergegray

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecopymergegray — Copia y fusiona una parte de una imagen en niveles de gris

### Descripción

function imagecopymergegray(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$src_width`,
int `$src_height`,
int `$pct`
): true

imagecopymergegray() copia una parte de la imagen `src_image` en la imagen de destino `dst_image` comenzando en las coordenadas (`src_x`, `src_y`), con el ancho `src_width` y la altura `src_height`. La zona de la imagen así definida será copiada en las coordenadas (`dst_x`, `dst_y`), en la imagen de destino.

imagecopymergegray() es idéntica a la función imagecopymerge(), excepto que durante la fusión, el "hue" de la imagen será conservado mediante la conversión de la zona en la imagen de destino a gris, antes de la operación de copia.

### Parámetros

`dst_image`

  Recurso de imagen de destino.

`src_image`

  Recurso de imagen de origen.

`dst_x`

  X: coordenada del punto de destino.

`dst_y`

  Y: coordenada del punto de destino.

`src_x`

  X: coordenada del punto origen.

`src_y`

  Y: coordenada del punto origen.

`src_width`

  Ancho de la fuente.

`src_height`

  Altura de la fuente.

`pct`
  El parámetro `src_image` será convertido a niveles de gris de acuerdo con el parámetro `pct` donde 0 corresponde a una conversión total a niveles de gris y 100 no modifica nada. Cuando `pct` = 100, esta función se comporta de la misma manera que la función imagecopy() para las paletas, excepto por la ignorancia de los componentes alpha, mientras que implementa la transparencia alpha para las imágenes true colour.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `dst_image` y `src_image` ahora esperan instancias de GdImage; anteriormente, se esperaban resources.

### Ejemplos

Ejemplo #1 Ejemplo con imagecopymergegray()

    <?php
    // Creación de las instancias de imagen
    $dest = imagecreatefromgif('php.gif');
    $src = imagecreatefromgif('php.gif');

    // Copia y fusiona - Gris = 20%
    imagecopymergegray($dest, $src, 10, 10, 0, 0, 100, 47, 20);

    // Muestra y libera la memoria
    header('Content-Type: image/gif');
    imagegif($dest);
    ?>

# imagecopyresampled

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecopyresampled — Copia, redimensiona y reinterpolación de una imagen

### Descripción

function imagecopyresampled(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$dst_width`,
int `$dst_height`,
int `$src_width`,
int `$src_height`
): true

imagecopyresampled() copia una zona rectangular de la imagen `src_im` hacia la imagen `dst_im`. Durante la copia, la zona es reinterpolada para mantener la claridad de la imagen durante una reducción.

En otras palabras, imagecopyresampled() tomará una forma rectangular `src_image` de un ancho de `src_width` y una altura `src_height` en la posición (`src_x`,`src_y`) y la colocará en una zona rectangular `dst_image` de un ancho de `dst_width` y una altura de `dst_height` en la posición (`dst_x`,`dst_y`).

Si las alturas y anchos de origen y destino difieren, la imagen copiada será estirada de manera apropiada. Las coordenadas son las del ángulo superior izquierdo. imagecopyresampled() puede usarse para copiar zonas de una imagen hacia sí misma, (si `dst_image` es la misma que `src_image`) pero si las regiones se superponen, los resultados son impredecibles.

### Parámetros

`dst_image`

  Recurso de imagen de destino.

`src_image`

  Recurso de imagen de origen.

`dst_x`

  X: coordenadas del punto de destino.

`dst_y`

  Y: coordenadas del punto de destino.

`src_x`

  X: coordenadas del punto origen.

`src_y`

  Y: coordenadas del punto origen.

`dst_width`

  Ancho del destino.

`dst_height`

  Altura del destino.

`src_width`

  Ancho de la fuente.

`src_height`

  Altura de la fuente.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | El tipo de retorno es ahora `true`; anteriormente, era bool.
8.0.0 | `dst_image` y `src_image` ahora esperan instancias de GdImage; anteriormente, se esperaban resources.

### Ejemplos

Ejemplo #1 Ejemplo simple

Este ejemplo redimensiona una imagen a la mitad de su tamaño original.

    <?php
    // El archivo
    $filename = 'test.jpg';
    $percent = 0.5;

    // Tipo de contenido
    header('Content-Type: image/jpeg');

    // Cálculo de las nuevas dimensiones
    list($width, $height) = getimagesize($filename);
    $new_width = $width * $percent;
    $new_height = $height * $percent;

    // Redimensionamiento
    $image_p = imagecreatetruecolor($new_width, $new_height);
    $image = imagecreatefromjpeg($filename);
    imagecopyresampled($image_p, $image, 0, 0, 0, 0, $new_width, $new_height, $width, $height);

    // Mostrar
    imagejpeg($image_p, null, 100);
    ?>

Resultado del ejemplo anterior es similar a:

Ejemplo #2 Redimensionamiento proporcional de una imagen

Este ejemplo mostrará una imagen con un ancho o altura máxima de 200 píxeles.

    <?php
    // El archivo
    $filename = 'test.jpg';

    // Definición del ancho y altura máxima
    $width = 200;
    $height = 200;

    // Tipo de contenido
    header('Content-Type: image/jpeg');

    // Cálculo de las nuevas dimensiones
    list($width_orig, $height_orig) = getimagesize($filename);

    $ratio_orig = $width_orig/$height_orig;

    if ($width/$height > $ratio_orig) {
       $width = $height*$ratio_orig;
    } else {
       $height = $width/$ratio_orig;
    }

    // Redimensionamiento
    $image_p = imagecreatetruecolor($width, $height);
    $image = imagecreatefromjpeg($filename);
    imagecopyresampled($image_p, $image, 0, 0, 0, 0, $width, $height, $width_orig, $height_orig);

    // Mostrar
    imagejpeg($image_p, null, 100);
    ?>

Resultado del ejemplo anterior es similar a:

### Notas

> Nota:

> Existe un problema debido a las limitaciones del tamaño de la paleta (255 + 1 colores diferentes). Filtrar o reinterpolar una imagen requiere más de 255 colores, entonces se usa una aproximación para calcular el nuevo número de colores. Con una paleta, si un nuevo color no puede ser asignado, se usa el color más cercano (en teoría). Esto no siempre es el color más cercano visualmente. Esto puede generar problemas extraños, como imágenes blancas. Para evitar este problema, convierta la imagen a TrueColor, como la generada por la función imagecreatetruecolor().

### Ver también

- imagecopyresized() - Copia y redimensiona una parte de una imagen
- imagescale() - Redimensiona una imagen utilizando una altura y una anchura proporcionadas
- imagecrop() - Recorta una imagen en el rectángulo dado

# imagecopyresized

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecopyresized — Copia y redimensiona una parte de una imagen

### Descripción

function imagecopyresized(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$dst_width`,
int `$dst_height`,
int `$src_width`,
int `$src_height`
): true

imagecopyresized() copia una parte rectangular de una imagen en otra imagen de destino. `dst_image` es la imagen de destino, `src_image` es la imagen fuente.

En otras palabras, imagecopyresized() tomará una forma rectangular `src_image` de un ancho de `src_width` y una altura `src_height` en la posición (`src_x`,`src_y`) y la colocará en una zona rectangular `dst_image` de un ancho de `dst_width` y una altura de `dst_height` en la posición (`dst_x`,`dst_y`).

Si las dimensiones de la fuente y el destino no son iguales, se realiza un estiramiento adecuado para hacer coincidir las dos. Las coordenadas proporcionadas se definen en relación con la esquina superior izquierda. Esta función puede ser utilizada para copiar regiones dentro de una misma imagen (si `dst_image` y `src_image` son idénticas), pero si las regiones se superponen, el resultado podría ser inconsistente.

### Parámetros

`dst_image`

  Recurso de imagen de destino.

`src_image`

  Recurso de imagen de origen.

`dst_x`

  X: coordenada del punto de destino.

`dst_y`

  Y: coordenada del punto de destino.

`src_x`

  X: coordenada del punto fuente.

`src_y`

  Y: coordenada del punto fuente.

`dst_width`

  Ancho del destino.

`dst_height`

  Altura del destino.

`src_width`

  Ancho de la fuente.

`src_height`

  Altura de la fuente.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `dst_image` y `src_image` ahora esperan instancias de GdImage; anteriormente, se esperaban resources.

### Ejemplos

Ejemplo #1 Redimensionamiento de una imagen

Este ejemplo mostrará la imagen redimensionada a la mitad de su tamaño original.

    <?php
    // Archivo y nuevo tamaño
    $filename = 'test.jpg';
    $percent = 0.5;

    // Tipo de contenido
    header('Content-Type: image/jpeg');

    // Cálculo de las nuevas dimensiones
    list($width, $height) = getimagesize($filename);
    $newwidth = $width * $percent;
    $newheight = $height * $percent;

    // Carga
    $thumb = imagecreatetruecolor($newwidth, $newheight);
    $source = imagecreatefromjpeg($filename);

    // Redimensionamiento
    imagecopyresized($thumb, $source, 0, 0, 0, 0, $newwidth, $newheight, $width, $height);

    // Mostrar
    imagejpeg($thumb);
    ?>

Resultado del ejemplo anterior es similar a:

La imagen mostrada tendrá la mitad del tamaño de la imagen original, pero una mejor calidad puede obtenerse utilizando la función imagecopyresampled().

### Notas

> Nota:

> Existe un problema debido a las limitaciones del tamaño de la paleta (255 + 1 colores diferentes). Filtrar o reescalar una imagen requiere más de 255 colores, entonces se utiliza una aproximación para calcular el nuevo número de colores. Con una paleta, si un nuevo color no puede ser asignado, se utiliza el color más cercano (en teoría); esto no siempre es el más cercano visualmente. Esto puede generar problemas extraños, como imágenes blancas. Para evitar este problema, convierta a imágenes TrueColor, como las generadas por la función imagecreatetruecolor().

### Ver también

- imagecopyresampled() - Copia, redimensiona y reinterpolación de una imagen
- imagescale() - Redimensiona una imagen utilizando una altura y una anchura proporcionadas
- imagecrop() - Recorta una imagen en el rectángulo dado

# imagecreate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreate — Crea una nueva imagen con paleta

### Descripción

function imagecreate(int `$width`, int `$height`): GdImage|false

imagecreate() devuelve un identificador de imagen que representa una imagen vacía.

En general, se recomienda el uso de la función imagecreatetruecolor() en lugar de la función imagecreate() para que las operaciones sobre la imagen se realicen con la mayor calidad posible. Si se desea utilizar una paleta, entonces la función imagetruecolortopalette() debe ser llamada inmediatamente antes de guardar la imagen con la función imagepng() o la función imagegif().

### Parámetros

`width`

  El ancho de la imagen.

`height`

  La altura de la imagen.

### Valores devueltos

Devuelve un objeto de imagen en caso de éxito, `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de GDImage ; anteriormente, se devolvía un resource.

### Ejemplos

Ejemplo #1 Creación de una imagen GD y visualización de esta imagen

    <?php
    header("Content-Type: image/png");
    $im = @imagecreate(110, 20)
        or die("Imposible inicializar la biblioteca GD");
    $background_color = imagecolorallocate($im, 0, 0, 0);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "A Simple Text String", $text_color);
    imagepng($im);
    ?>

Resultado del ejemplo anterior es similar a:

### Ver también

- imagedestroy() - Destruye una imagen
- imagecreatetruecolor() - Crea una nueva imagen en colores verdaderos

# imagecreatefromavif

(PHP 8 >= 8.1.0)

imagecreatefromavif — Crear una nueva imagen a partir de un archivo o una URL

### Descripción

function imagecreatefromavif(string `$filename`): GdImage|false

imagecreatefromavif() devuelve un objeto imagen obtenido a partir del fichero `filename`.

### Parámetros

`filename`

  Ruta de acceso a la imagen AVIF.

### Valores devueltos

Devuelve un objeto de imagen en caso de éxito, `false` en caso de error.

# imagecreatefrombmp

(PHP 7 >= 7.2.0, PHP 8)

imagecreatefrombmp — Crear una nueva imagen a partir de un archivo o una URL

### Descripción

function imagecreatefrombmp(string `$filename`): GdImage|false

imagecreatefrombmp() devuelve un identificador de imagen que representa la imagen obtenida a partir del nombre de fichero proporcionado.

Sugerencia

Puede utilizar una URL como nombre de archivo con esta función, si el gestor fopen ha sido activado. Véase fopen() para más detalles sobre cómo especificar el nombre del archivo. Consulte Protocolos y Envolturas soportados para más información sobre las capacidades de los diferentes gestores, las notas sobre su uso, así como la información sobre las variables predefinidas que proporcionan.

### Parámetros

`filename`

  Ruta de acceso al fichero BMP.

### Valores devueltos

Devuelve un objeto de imagen en caso de éxito, `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de GDImage; anteriormente, se devolvía un resource.

### Ejemplos

Ejemplo #1 Convierte una imagen BMP en imagen PNG utilizando imagecreatefrombmp()

    <?php
    // Carga el fichero BMP
    $im = imagecreatefrombmp('./example.bmp');

    // Lo convierte en un fichero PNG con los parámetros por omisión
    imagepng($im, './example.png');
    ?>

# imagecreatefromgd

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd — Crea una nueva imagen a partir de un fichero GD o de una URL

### Descripción

function imagecreatefromgd(string `$filename`): GdImage|false

Crea una nueva imagen a partir de un fichero GD o de una URL.

Sugerencia

Puede utilizar una URL como nombre de archivo con esta función, si el gestor fopen ha sido activado. Véase fopen() para más detalles sobre cómo especificar el nombre del archivo. Consulte Protocolos y Envolturas soportados para más información sobre las capacidades de los diferentes gestores, las notas sobre su uso, así como la información sobre las variables predefinidas que proporcionan.

### Parámetros

`filename`

  Ruta de acceso a un fichero GD.

### Valores devueltos

Devuelve un objeto de imagen en caso de éxito, `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de GDImage ; anteriormente, se devolvía un resource.

### Ejemplos

Ejemplo #1 Ejemplo con imagecreatefromgd()

    <?php
    // Carga una imagen GD
    $im = @imagecreatefromgd('./test.gd');

    // Verifica si la imagen se ha cargado correctamente
    if(!$im)
    {
         die('No ha sido posible cargar la imagen GD');
    }

    // Operaciones sobre la imagen aquí

    // Guardado de la imagen
    imagegd($im, './test_updated.gd');
    ?>

### Notas

Advertencia

Los formatos de imagen GD y GD2 son formatos propietarios de libgd. Deben considerarse obsoletos, y solo deben utilizarse con fines de desarrollo y pruebas.

# imagecreatefromgd2

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd2 — Crea una nueva imagen a partir de un fichero GD2 o de una URL

### Descripción

function imagecreatefromgd2(string `$filename`): GdImage|false

Crea una nueva imagen desde un fichero GD2 o una URL.

Sugerencia

Puede utilizar una URL como nombre de archivo con esta función, si el gestor fopen ha sido activado. Véase fopen() para más detalles sobre cómo especificar el nombre del archivo. Consulte Protocolos y Envolturas soportados para más información sobre las capacidades de los diferentes gestores, las notas sobre su uso, así como la información sobre las variables predefinidas que proporcionan.

### Parámetros

`filename`

  Ruta de acceso a la imagen GD2.

### Valores devueltos

Devuelve un objeto de imagen en caso de éxito, `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de GDImage ; anteriormente, se devolvía un resource.

### Ejemplos

Ejemplo #1 Ejemplo con imagecreatefromgd2()

    <?php
    // Carga la imagen gd2
    $im = imagecreatefromgd2('./test.gd2');

    // Aplica un efecto a la imagen: se aplica aquí un filtro negativo si existe
    if(function_exists('imagefilter'))
    {
        imagefilter($im, IMG_FILTER_NEGATE);
    }

    // Guarda la imagen
    imagegd2($im, './test_updated.gd2');
    ?>

### Notas

Advertencia

Los formatos de imagen GD y GD2 son formatos propietarios de libgd. Deben considerarse obsoletos, y solo deben utilizarse con fines de desarrollo y pruebas.

# imagecreatefromgd2part

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd2part — Crea una nueva imagen a partir de una parte de un archivo GD2 o de una URL

### Descripción

function imagecreatefromgd2part(
string `$filename`,
int `$x`,
int `$y`,
int `$width`,
int `$height`
): GdImage|false

Crea una nueva imagen a partir de una parte de un archivo GD2 o de una URL.

Sugerencia

Puede utilizar una URL como nombre de archivo con esta función, si el gestor fopen ha sido activado. Véase fopen() para más detalles sobre cómo especificar el nombre del archivo. Consulte Protocolos y Envolturas soportados para más información sobre las capacidades de los diferentes gestores, las notas sobre su uso, así como la información sobre las variables predefinidas que proporcionan.

### Parámetros

`filename`

  Ruta hacia la imagen GD2.

`x`

  Coordenada en X del punto de origen.

`y`

  Coordenada en Y del punto de origen.

`width`

  Ancho de la fuente.

`height`

  Altura de la fuente.

### Valores devueltos

Devuelve un objeto de imagen en caso de éxito, `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de GDImage ; anteriormente, se devolvía un resource.

### Ejemplos

Ejemplo #1 Ejemplo con imagecreatefromgd2part()

    <?php
    // Para este ejemplo, primero se necesitan las dimensiones de la imagen
    $image = getimagesize('./test.gd2');

    // Creación de la instancia de imagen ahora que se tienen las dimensiones
    $im = imagecreatefromgd2part('./test.gd2', 4, 4, ($image[0] / 2) - 6, ($image[1] / 2) - 6);

    // Operación sobre la imagen: aquí se imprime la imagen
    if(function_exists('imagefilter'))
    {
        imagefilter($im, IMG_FILTER_EMBOSS);
    }

    // Guardado de la imagen optimizada
    imagegd2($im, './test_emboss.gd2');
    ?>

### Notas

Advertencia

Los formatos de imagen GD y GD2 son formatos propietarios de libgd. Deben considerarse obsoletos, y solo deben utilizarse con fines de desarrollo y pruebas.

# imagecreatefromgif

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefromgif — Crear una nueva imagen a partir de un archivo o una URL

### Descripción

function imagecreatefromgif(string `$filename`): GdImage|false

imagecreatefromgif() devuelve un identificador de imagen que representa la imagen obtenida a partir del fichero cuyo nombre es dado por `filename`.

Precaución

Al leer en memoria ficheros GIF animados, solo el primer frame es devuelto por el objeto de la imagen. El tamaño de la imagen no es necesariamente el que se reporta mediante getimagesize().

Sugerencia

Puede utilizar una URL como nombre de archivo con esta función, si el gestor fopen ha sido activado. Véase fopen() para más detalles sobre cómo especificar el nombre del archivo. Consulte Protocolos y Envolturas soportados para más información sobre las capacidades de los diferentes gestores, las notas sobre su uso, así como la información sobre las variables predefinidas que proporcionan.

### Parámetros

`filename`

  Ruta hacia la imagen GIF.

### Valores devueltos

Devuelve un objeto de imagen en caso de éxito, `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de GDImage ; anteriormente, se devolvía un resource.

### Ejemplos

Ejemplo #1 Ejemplo de manejo de errores al cargar una imagen GIF

    <?php
    function LoadGif($imgname)
    {
        /* Intenta abrir la imagen */
        $im = @imagecreatefromgif($imgname);

        /* Procesamiento si la apertura falló */
        if(!$im)
        {
            /* Creación de una imagen vacía */
            $im = imagecreatetruecolor (150, 30);
            $bgc = imagecolorallocate ($im, 255, 255, 255);
            $tc = imagecolorallocate ($im, 0, 0, 0);

            imagefilledrectangle ($im, 0, 0, 150, 30, $bgc);

            /* Muestra un mensaje de error en la imagen */
            imagestring ($im, 1, 5, 5, 'Error loading ' . $imgname, $tc);
        }

        return $im;
    }

    header('Content-Type: image/gif');

    $img = LoadGif('bogus.image');

    imagegif($img);
    ?>

Resultado del ejemplo anterior es similar a:

# imagecreatefromjpeg

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefromjpeg — Crear una nueva imagen a partir de un archivo o una URL

### Descripción

function imagecreatefromjpeg(string `$filename`): GdImage|false

imagecreatefromjpeg() devuelve un identificador de imagen que representa una imagen obtenida a partir del fichero `filename`.

Sugerencia

Puede utilizar una URL como nombre de archivo con esta función, si el gestor fopen ha sido activado. Véase fopen() para más detalles sobre cómo especificar el nombre del archivo. Consulte Protocolos y Envolturas soportados para más información sobre las capacidades de los diferentes gestores, las notas sobre su uso, así como la información sobre las variables predefinidas que proporcionan.

### Parámetros

`filename`

  Ruta hacia la imagen JPEG.

### Valores devueltos

Devuelve un objeto de imagen en caso de éxito, `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de GDImage ; anteriormente, se devolvía un resource.

### Ejemplos

Ejemplo #1 Ejemplo de gestión de un error durante la carga de una imagen JPEG

    <?php
    function LoadJpeg($imgname)
    {
        /* Intento de abrir la imagen */
        $im = @imagecreatefromjpeg($imgname);

        /* Procesamiento en caso de fallo */
        if(!$im)
        {
            /* Creación de una imagen vacía */
            $im  = imagecreatetruecolor(150, 30);
            $bgc = imagecolorallocate($im, 255, 255, 255);
            $tc  = imagecolorallocate($im, 0, 0, 0);

            imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

            /* Se muestra un mensaje de error */
            imagestring($im, 1, 5, 5, 'Error de carga ' . $imgname, $tc);
        }

        return $im;
    }

    header('Content-Type: image/jpeg');

    $img = LoadJpeg('bogus.image');

    imagejpeg($img);
    ?>

Resultado del ejemplo anterior es similar a:

# imagecreatefrompng

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefrompng — Crear una nueva imagen a partir de un archivo o una URL

### Descripción

function imagecreatefrompng(string `$filename`): GdImage|false

imagecreatefrompng() devuelve un identificador de imagen que representa una imagen obtenida a partir del fichero `filename`.

Sugerencia

Puede utilizar una URL como nombre de archivo con esta función, si el gestor fopen ha sido activado. Véase fopen() para más detalles sobre cómo especificar el nombre del archivo. Consulte Protocolos y Envolturas soportados para más información sobre las capacidades de los diferentes gestores, las notas sobre su uso, así como la información sobre las variables predefinidas que proporcionan.

### Parámetros

`filename`

  Ruta de acceso a la imagen PNG.

### Valores devueltos

Devuelve un objeto de imagen en caso de éxito, `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de GDImage ; anteriormente, se devolvía un resource.

### Ejemplos

Ejemplo #1 Ejemplo de gestión de un error al cargar una imagen PNG

    <?php
    function LoadPNG($imgname)
    {
        /* Intento de abrir la imagen */
        $im = @imagecreatefrompng($imgname);

        /* Procesamiento en caso de fallo */
        if(!$im)
        {
            /* Creación de una imagen vacía */
            $im  = imagecreatetruecolor(150, 30);
            $bgc = imagecolorallocate($im, 255, 255, 255);
            $tc  = imagecolorallocate($im, 0, 0, 0);

            imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

            /* Se muestra un mensaje de error */
            imagestring($im, 1, 5, 5, 'Error de carga ' . $imgname, $tc);
        }

        return $im;
    }

    header('Content-Type: image/png');

    $img = LoadPNG('bogus.image');

    imagepng($img);
    ?>

Resultado del ejemplo anterior es similar a:

# imagecreatefromstring

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

imagecreatefromstring — Crea una imagen a partir de una cadena

### Descripción

function imagecreatefromstring(string `$data`): GdImage|false

imagecreatefromstring() devuelve un identificador de imagen que representa la imagen obtenida desde la cadena `data`. El tipo de la imagen será detectado automáticamente si PHP ha sido compilado con soporte para: JPEG, PNG, GIF, BMP, WBMP, GD2, WEBP y AVIF.

### Parámetros

`data`

  Una cadena que contiene los datos de la imagen.

### Valores devueltos

Un objeto de imagen será devuelto en caso de éxito. `false` es devuelto si el tipo de la imagen no es soportado, si los datos no están en un formato reconocido o si la imagen está corrupta y por lo tanto no puede ser cargada.

### Errores/Excepciones

imagecreatefromstring() emite un error de nivel E_WARNING si los datos no están en un formato reconocido.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de GDImage; anteriormente, se devolvía un resource.
7.3.0 | WEBP es soportado ahora (si es soportado por la libgd utilizada).

### Ejemplos

Ejemplo #1 Ejemplo con imagecreatefromstring()

    <?php
    $data = 'iVBORw0KGgoAAAANSUhEUgAAABwAAAASCAMAAAB/2U7WAAAABl'
           . 'BMVEUAAAD///+l2Z/dAAAASUlEQVR4XqWQUQoAIAxC2/0vXZDr'
           . 'EX4IJTRkb7lobNUStXsB0jIXIAMSsQnWlsV+wULF4Avk9fLq2r'
           . '8a5HSE35Q3eO2XP1A1wQkZSgETvDtKdQAAAABJRU5ErkJggg==';
    $data = base64_decode($data);

    $im = imagecreatefromstring($data);
    if ($im !== false) {
        header('Content-Type: image/png');
        imagepng($im);
    }
    else {
        echo 'Ha ocurrido un error.';
    }
    ?>

Resultado del ejemplo anterior es similar a:

### Ver también

- imagecreatefromjpeg() - Crear una nueva imagen a partir de un archivo o una URL
- imagecreatefrompng() - Crear una nueva imagen a partir de un archivo o una URL
- imagecreatefromgif() - Crear una nueva imagen a partir de un archivo o una URL
- imagecreatetruecolor() - Crea una nueva imagen en colores verdaderos

# imagecreatefromtga

(PHP 7 >= 7.4.0, PHP 8)

imagecreatefromtga — Crear una nueva imagen a partir de un archivo o una URL

### Descripción

function imagecreatefromtga(string `$filename`): GdImage|false

imagecreatefromtga() devuelve un objeto imagen que representa la imagen obtenida a partir del nombre de fichero proporcionado.

### Parámetros

`filename`

  Ruta de acceso a la imagen TGA Truevision.

### Valores devueltos

Devuelve un objeto de imagen en caso de éxito, `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia GDImage; anteriormente, se devolvía un resource.

# imagecreatefromwbmp

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromwbmp — Crear una nueva imagen a partir de un archivo o una URL

### Descripción

function imagecreatefromwbmp(string `$filename`): GdImage|false

imagecreatefromwbmp() devuelve un recurso de imagen PHP, que representa la imagen `filename`.

> Nota: Las imágenes WBMP son Wireless Bitmaps, y no Windows Bitmaps. Estas últimas pueden cargarse mediante imagecreatefrombmp().

Sugerencia

Puede utilizar una URL como nombre de archivo con esta función, si el gestor fopen ha sido activado. Véase fopen() para más detalles sobre cómo especificar el nombre del archivo. Consulte Protocolos y Envolturas soportados para más información sobre las capacidades de los diferentes gestores, las notas sobre su uso, así como la información sobre las variables predefinidas que proporcionan.

### Parámetros

`filename`

  Ruta de acceso a la imagen WBMP.

### Valores devueltos

Devuelve un objeto de imagen en caso de éxito, `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de GDImage ; anteriormente, se devolvía un resource.

### Ejemplos

Ejemplo #1 Ejemplo de gestión de un error al cargar una imagen WBMP

    <?php
    function LoadWBMP($imgname)
    {
        /* Intento de abrir la imagen */
        $im = @imagecreatefromwbmp($imgname);

        /* Procesamiento en caso de fallo */
        if(!$im)
        {
            /* Creación de una imagen vacía */
            $im  = imagecreatetruecolor(150, 30);
            $bgc = imagecolorallocate($im, 255, 255, 255);
            $tc  = imagecolorallocate($im, 0, 0, 0);

            imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

            /* Se muestra un mensaje de error */
            imagestring($im, 1, 5, 5, 'Error de carga ' . $imgname, $tc);
        }

        return $im;
    }

    header('Content-Type: image/vnd.wap.wbmp');

    $img = LoadWBMP('bogus.image');

    imagewbmp($img);
    ?>

# imagecreatefromwebp

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

imagecreatefromwebp — Crear una nueva imagen a partir de un archivo o una URL

### Descripción

function imagecreatefromwebp(string `$filename`): GdImage|false

imagecreatefromwebp() devuelve un identificador de imagen que representa la imagen obtenida desde el fichero proporcionado. Tenga en cuenta que los ficheros WebP animados no pueden ser leídos.

Sugerencia

Puede utilizar una URL como nombre de archivo con esta función, si el gestor fopen ha sido activado. Véase fopen() para más detalles sobre cómo especificar el nombre del archivo. Consulte Protocolos y Envolturas soportados para más información sobre las capacidades de los diferentes gestores, las notas sobre su uso, así como la información sobre las variables predefinidas que proporcionan.

### Parámetros

`filename`

  Ruta hacia la imagen WebP.

### Valores devueltos

Devuelve un objeto de imagen en caso de éxito, `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de GDImage ; anteriormente, se devolvía un resource.

### Ejemplos

Ejemplo #1 Convierte una imagen WebP en una imagen jpeg utilizando la función imagecreatefromwebp()

    <?php
    // Carga el fichero WebP
    $im = imagecreatefromwebp('./example.webp');

    // Se convierte en un fichero jpeg con una calidad del 100%
    imagejpeg($im, './example.jpeg', 100);
    ?>

# imagecreatefromxbm

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromxbm — Crear una nueva imagen a partir de un archivo o una URL

### Descripción

function imagecreatefromxbm(string `$filename`): GdImage|false

imagecreatefromxbm() devuelve un identificador de imagen que representa la imagen obtenida a partir del fichero `filename`.

Sugerencia

Puede utilizar una URL como nombre de archivo con esta función, si el gestor fopen ha sido activado. Véase fopen() para más detalles sobre cómo especificar el nombre del archivo. Consulte Protocolos y Envolturas soportados para más información sobre las capacidades de los diferentes gestores, las notas sobre su uso, así como la información sobre las variables predefinidas que proporcionan.

### Parámetros

`filename`

  Ruta de acceso a la imagen XBM.

### Valores devueltos

Devuelve un objeto de imagen en caso de éxito, `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de GDImage ; anteriormente, se devolvía un resource.

### Ejemplos

Ejemplo #1 Convertir una imagen XBM a una imagen PNG utilizando la función imagecreatefromxbm()

    <?php
    // Carga del fichero XBM
    $xbm = imagecreatefromxbm('./example.xbm');

    // Se convierte en fichero PNG
    imagepng($xbm, './example.png');
    ?>

# imagecreatefromxpm

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromxpm — Crear una nueva imagen a partir de un archivo o una URL

### Descripción

function imagecreatefromxpm(string `$filename`): GdImage|false

imagecreatefromxpm() devuelve un identificador de imagen que representa la imagen obtenida a partir del archivo `filename`.

Sugerencia

Puede utilizar una URL como nombre de archivo con esta función, si el gestor fopen ha sido activado. Véase fopen() para más detalles sobre cómo especificar el nombre del archivo. Consulte Protocolos y Envolturas soportados para más información sobre las capacidades de los diferentes gestores, las notas sobre su uso, así como la información sobre las variables predefinidas que proporcionan.

### Parámetros

`filename`

  Ruta de acceso a la imagen XPM.

### Valores devueltos

Devuelve un objeto de imagen en caso de éxito, `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de GDImage ; anteriormente, se devolvía un resource.

### Ejemplos

Ejemplo #1 Creación de una instancia de imagen utilizando la función imagecreatefromxpm()

    <?php
    // Verifica el soporte XPM
    if(!(imagetypes() & IMG_XPM))
    {
        die('El soporte XPM no ha podido ser verificado !');
    }

    // Creación de la instancia de una imagen
    $xpm = imagecreatefromxpm('./example.xpm');

    // Algunas operaciones sobre la imagen aquí

    // PHP no tiene soporte para la escritura de imágenes XPM
    // por lo tanto, en este caso, se guarda la imagen en un archivo JPEG
    // con una calidad del 100%
    imagejpeg($xpm, './example.jpg', 100);
    ?>

# imagecreatetruecolor

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecreatetruecolor — Crea una nueva imagen en colores verdaderos

### Descripción

function imagecreatetruecolor(int `$width`, int `$height`): GdImage|false

imagecreatetruecolor() devuelve un objeto que representa una imagen negra.

### Parámetros

`width`

  Ancho de la imagen.

`height`

  Alto de la imagen.

### Valores devueltos

Devuelve un objeto de imagen en caso de éxito, `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de GDImage ; anteriormente, se devolvía un resource.

### Ejemplos

Ejemplo #1 Creación de un flujo de imagen GD y visualización

    <?php
    header ('Content-Type: image/png');
    $im = @imagecreatetruecolor(120, 20)
          or die('Imposible crear un flujo de imagen GD');
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'Una simple cadena de texto', $text_color);
    imagepng($im);
    ?>

Resultado del ejemplo anterior es similar a:

### Ver también

- imagedestroy() - Destruye una imagen
- imagecreate() - Crea una nueva imagen con paleta

# imagecrop

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagecrop — Recorta una imagen en el rectángulo dado

### Descripción

function imagecrop(GdImage `$image`, array `$rectangle`): GdImage|false

Recorta una imagen en la zona rectangular dada y devuelve la imagen resultante. La `image` no se modifica.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`rectangle`

  array que contiene las claves `x`, `y`, `width` y `height`.

### Valores devueltos

Devuelve el objeto de la imagen recortada en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de GDImage; anteriormente, se devolvía un resource.

### Ejemplos

Ejemplo #1 Ejemplo con imagecrop()

Este ejemplo muestra cómo recortar una imagen en una zona cuadrada.

    <?php
    $im = imagecreatefrompng('example.png');
    $size = min(imagesx($im), imagesy($im));
    $im2 = imagecrop($im, ['x' => 0, 'y' => 0, 'width' => $size, 'height' => $size]);
    if ($im2 !== FALSE) {
        imagepng($im2, 'example-cropped.png');
    }
    ?>

### Ver también

- imagecropauto() - Recorta una imagen automáticamente utilizando uno de los modos disponibles

# imagecropauto

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagecropauto — Recorta una imagen automáticamente utilizando uno de los modos disponibles

### Descripción

function imagecropauto(
GdImage `$image`,
int `$mode` = `IMG_CROP_DEFAULT`,
float `$threshold` = 0.5,
int `$color` = -1
): GdImage|false

Recorta automáticamente una imagen según el `mode`.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`mode`

  Una constante entre:

  `IMG_CROP_DEFAULT`
    Idéntico a `IMG_CROP_TRANSPARENT`. Anterior a PHP 7.4.0, la biblioteca libgd integrada utilizaba `IMG_CROP_SIDES` como solución de respaldo, si la imagen no tenía color de transparencia.
  `IMG_CROP_TRANSPARENT`
    Recorta el fondo transparente.
  `IMG_CROP_BLACK`
    Recorta el fondo negro.
  `IMG_CROP_WHITE`
    Recorta el fondo blanco.
  `IMG_CROP_SIDES`
    Utiliza las 4 esquinas de la imagen para intentar detectar el fondo a recortar.
  `IMG_CROP_THRESHOLD`
    Recorta la imagen utilizando el umbral `threshold` y `color`.
`threshold`

  Especifica la tolerancia en porcentaje a utilizar durante la comparación de la color de la imagen y la color a recortar. El método utilizado para calcular la diferencia de color se basa en la distancia de colores en el cubo RVB(a).

  Utilizado únicamente en modo `IMG_CROP_THRESHOLD`.

  > Nota: Anterior a PHP 7.4.0, la biblioteca libgd integrada utilizaba un algoritmo algo diferente, por lo que el mismo `threshold` producía resultados diferentes para libgd sistema e integrado.

`color`

  Puede ser un valor de color RVB o un índice de paleta.

  Utilizado únicamente en modo `IMG_CROP_THRESHOLD`.

### Valores devueltos

Devuelve el objeto de la imagen recortada en caso de éxito o `false` si ocurre un error. `false` también será devuelto si toda la imagen ha sido recortada.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de GDImage; anteriormente, se devolvía un resource.
7.4.0 | El comportamiento de imagecropauto de la biblioteca libgd integrada ha sido sincronizado con la de libgd sistema: `IMG_CROP_DEFAULT` ya no utiliza `IMG_CROP_SIDES` como solución de respaldo y la tolerancia de recorte utiliza ahora el mismo algoritmo que libgd sistema.
7.4.0 | El valor por omisión de `mode` ha sido modificado a `IMG_CROP_AUTO`. Anteriormente, el valor por omisión era `-1` que corresponde a `IMG_CROP_DEFAULT`, pero pasar `-1` está ahora obsoleto.

### Ejemplos

Ejemplo #1 Recorte automático correcto

Como se indica en la sección valor de retorno, imagecropauto() devuelve `false` si toda la imagen ha sido recortada. En este ejemplo, tenemos un objeto de imagen `$im` que solo debería ser automáticamente recortado si hay algo que recortar; de lo contrario, se desea conservar la imagen original.

    <?php
    $cropped = imagecropauto($im, IMG_CROP_DEFAULT);
    if ($cropped !== false) { // Si se ha devuelto un nuevo objeto de imagen
        $im = $cropped;       // y asigna la imagen recortada a $im
    }
    ?>

### Ver también

- imagecrop() - Recorta una imagen en el rectángulo dado

# imagedashedline

(PHP 4, PHP 5, PHP 7, PHP 8)

imagedashedline — Dibuja una línea punteada

### Descripción

function imagedashedline(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

imagedashedline() está obsoleto. Se recomienda utilizar una combinación de las funciones imagesetstyle() y imageline(). El punto 0, 0 es la esquina superior izquierda de la imagen.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`x1`

  Coordenada x del primer punto.

`y1`

  Coordenada y del primer punto.

`x2`

  Coordenada x del segundo punto.

`y2`

  Coordenada y del segundo punto.

`color`

  El color de relleno. Un identificador de color creado con imagecolorallocate().

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagedashedline()

    <?php
    // Crea una imagen de 100x100 píxeles
    $im = imagecreatetruecolor(100, 100);
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);

    // Dibuja una línea vertical punteada
    imagedashedline($im, 50, 25, 50, 75, $white);

    // Guarda la imagen
    imagepng($im, './dashedline.png');
    ?>

Resultado del ejemplo anterior es similar a:

Ejemplo #2 Alternativa a la función imagedashedline()

    <?php
    // Crea una imagen de 100x100 píxeles
    $im = imagecreatetruecolor(100, 100);
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);

    // Define el estilo: Los 4 primeros píxeles son blancos y los 4 siguientes
    // son transparentes. Esto va a crear el efecto de línea punteada
    $style = Array(
                    $white,
                    $white,
                    $white,
                    $white,
                    IMG_COLOR_TRANSPARENT,
                    IMG_COLOR_TRANSPARENT,
                    IMG_COLOR_TRANSPARENT,
                    IMG_COLOR_TRANSPARENT
                    );

    imagesetstyle($im, $style);

    // Dibuja la línea punteada
    imageline($im, 50, 25, 50, 75, IMG_COLOR_STYLED);

    // Guarda la imagen
    imagepng($im, './imageline.png');
    ?>

### Ver también

- imagesetstyle() - Configura el estilo para el dibujo de líneas
- imageline() - Dibuja una línea

# imagedestroy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagedestroy — Destruye una imagen

Advertencia

Esta función está OBSOLETA a partir de PHP 8.5.0. Depender de esta función está altamente desaconsejado.

### Descripción

#[\Deprecated]
function imagedestroy(GdImage `$image`): true

> Nota: Esta función no tiene ningún efecto. Anterior a PHP 8.0.0, esta función era utilizada para cerrar un recurso.

Anterior a PHP 8.0.0, imagedestroy() liberaba toda la memoria asociada a la recurso `image`. A partir de la versión 8.0.0, la extensión GD utiliza objetos en lugar de recursos, y los objetos no pueden ser cerrados explícitamente.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.5.0 | Esta función ha sido declarada obsoleta.
8.0.0 | Esta función es ahora un NOP.
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Uso de imagedestroy() anterior a PHP 8.0.0

    <?php
    // Crea una imagen de 100 x 100 píxeles
    $im = imagecreatetruecolor(100, 100);

    // Modificación y/o guardado de la imagen

    // Liberación de la memoria asociada
    imagedestroy($im);
    ?>

# imageellipse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imageellipse — Dibuja una elipse

### Descripción

function imageellipse(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$color`
): true

Dibuja una elipse centrada en el punto especificado.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`center_x`

  X: coordenada del centro.

`center_y`

  Y: coordenada del centro.

`width`

  El ancho de la elipse.

`height`

  La altura de la elipse.

`color`

  El color de la elipse. Un identificador de color creado con imagecolorallocate().

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imageellipse()

    <?php
    // Creación de una imagen vacía
    $image = imagecreatetruecolor(400, 300);

    // Selección del color de fondo
    $bg = imagecolorallocate($image, 0, 0, 0);

    // Rellena el fondo con el color seleccionado
    imagefill($image, 0, 0, $bg);

    // Selección del color de la elipse
    $col_ellipse = imagecolorallocate($image, 255, 255, 255);

    // Dibuja la elipse
    imageellipse($image, 200, 150, 300, 200, $col_ellipse);

    // Muestra la imagen
    header("Content-type: image/png");
    imagepng($image);

    ?>

Resultado del ejemplo anterior es similar a:

### Notas

> Nota:

> imageellipse() ignora imagesetthickness().

### Ver también

- imagefilledellipse() - Dibuja una elipse llena
- imagearc() - Dibuja una elipse parcial

# imagefill

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefill — Relleno

### Descripción

function imagefill(
GdImage `$image`,
int `$x`,
int `$y`,
int `$color`
): true

Realiza un relleno con el color `color`, en la imagen `image`, a partir del punto de coordenadas (`x`, `y`) (la esquina superior izquierda es el origen (0,0)).

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`x`

  X: coordenada del punto de inicio.

`y`

  Y: coordenada del punto de inicio.

`color`

  El color de relleno. Un identificador de color creado con imagecolorallocate().

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagefill()

    <?php

    $im = imagecreatetruecolor(100, 100);

    // Establece el fondo rojo
    $red = imagecolorallocate($im, 255, 0, 0);
    imagefill($im, 0, 0, $red);

    header('Content-type: image/png');
    imagepng($im);
    ?>

Resultado del ejemplo anterior es similar a:

### Ver también

- imagecolorallocate() - Asigna una coloración para una imagen

# imagefilledarc

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagefilledarc — Dibuja un arco parcial y lo rellena

### Descripción

function imagefilledarc(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$start_angle`,
int `$end_angle`,
int `$color`,
int `$style`
): true

Dibuja un arco parcial, centrado en las coordenadas especificadas en la imagen proporcionada.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`center_x`

  X: coordenada del centro.

`center_y`

  Y: coordenada del centro.

`width`

  El ancho del arco.

`height`

  La altura del arco.

`start_angle`

  El ángulo de inicio del arco, en grados.

`end_angle`

  El ángulo de fin del arco, en grados. 0° se encuentra en la posición de las 3 en punto en un reloj, y el arco se dibuja en el sentido de las agujas del reloj.

`color`

  Un identificador de color creado con imagecolorallocate().

`style`

  Un campo de bytes, combinado con el operador OR:

  1. `IMG_ARC_PIE`
  2. `IMG_ARC_CHORD`
  3. `IMG_ARC_NOFILL`
  4. `IMG_ARC_EDGED`
  `IMG_ARC_PIE` y `IMG_ARC_CHORD` son mutuamente excluyentes; `IMG_ARC_CHORD` solo conecta los ángulos de inicio y fin con una línea recta, mientras que `IMG_ARC_PIE` produce una línea curva. `IMG_ARC_NOFILL` indica que el arco (o cuerda) debe ser dibujado pero no rellenado. `IMG_ARC_EDGED`, usado junto con `IMG_ARC_NOFILL`, indica que los ángulos de inicio y fin deben ser conectados al centro. Esta función es recomendada para crear gráficos de tipo pastel.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Creación de un gráfico de pastel en 3D

    <?php

    // Creación de la imagen
    $image = imagecreatetruecolor(100, 100);

    // Asignación de algunas colores
    $white    = imagecolorallocate($image, 0xFF, 0xFF, 0xFF);
    $gray     = imagecolorallocate($image, 0xC0, 0xC0, 0xC0);
    $darkgray = imagecolorallocate($image, 0x90, 0x90, 0x90);
    $navy     = imagecolorallocate($image, 0x00, 0x00, 0x80);
    $darknavy = imagecolorallocate($image, 0x00, 0x00, 0x50);
    $red      = imagecolorallocate($image, 0xFF, 0x00, 0x00);
    $darkred  = imagecolorallocate($image, 0x90, 0x00, 0x00);

    // Creación del efecto 3D
    for ($i = 60; $i > 50; $i--) {
       imagefilledarc($image, 50, $i, 100, 50, 0, 45, $darknavy, IMG_ARC_PIE);
       imagefilledarc($image, 50, $i, 100, 50, 45, 75 , $darkgray, IMG_ARC_PIE);
       imagefilledarc($image, 50, $i, 100, 50, 75, 360 , $darkred, IMG_ARC_PIE);
    }

    imagefilledarc($image, 50, 50, 100, 50, 0, 45, $navy, IMG_ARC_PIE);
    imagefilledarc($image, 50, 50, 100, 50, 45, 75 , $gray, IMG_ARC_PIE);
    imagefilledarc($image, 50, 50, 100, 50, 75, 360 , $red, IMG_ARC_PIE);

    // Mostrar la imagen
    header('Content-type: image/png');
    imagepng($image);
    ?>

Resultado del ejemplo anterior es similar a:

# imagefilledellipse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagefilledellipse — Dibuja una elipse llena

### Descripción

function imagefilledellipse(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$color`
): true

Dibuja una elipse centrada en las coordenadas especificadas sobre la imagen proporcionada.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`center_x`

  X: coordenada del centro.

`center_y`

  Y: coordenada del centro.

`width`

  El ancho de la elipse.

`height`

  La altura de la elipse.

`color`

  El color de relleno. Un identificador de color creado con imagecolorallocate().

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagefilledellipse()

    <?php

    // Nueva imagen
    $image = imagecreatetruecolor(400, 300);

    // Color de fondo
    $bg = imagecolorallocate($image, 0, 0, 0);

    // Color de relleno de la elipse
    $col_ellipse = imagecolorallocate($image, 255, 255, 255);

    // Se dibuja la elipse blanca
    imagefilledellipse($image, 200, 150, 300, 200, $col_ellipse);

    // Se muestra la imagen
    header("Content-type: image/png");
    imagepng($image);

    ?>

Resultado del ejemplo anterior es similar a:

### Notas

> Nota:

> imagefilledellipse() ignora imagesetthickness().

### Ver también

- imageellipse() - Dibuja una elipse
- imagefilledarc() - Dibuja un arco parcial y lo rellena

# imagefilledpolygon

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilledpolygon — Dibuja un polígono relleno

### Descripción

Firma a partir de PHP 8.0.0 (no soportada con argumentos nombrados)

function imagefilledpolygon(GdImage `$image`, array `$points`, int `$color`): bool

Firma alternativa (obsoleta a partir de PHP 8.1.0)

function imagefilledpolygon(
GdImage `$image`,
array `$points`,
int `$num_points`,
int `$color`
): bool

imagefilledpolygon() dibuja un polígono relleno en la imagen `image`.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`points`

  Un array que contiene las coordenadas `x` y `y` del vértice de los polígonos.

`num_points`

  Número total de puntos (vértices), que deben ser al menos 3.

  Si este parámetro es omitido conforme a la segunda firma, `points` debe tener un número par de elementos, y `num_points` se asume como `count($points)/2`.
`color`

  Un identificador de color creado con imagecolorallocate().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `num_points` ha sido marcado como obsoleto.
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagefilledpolygon()

    <?php
    // Definición del array de puntos para el polígono
    $values = array(
                40,  50,  // Punto 1 (x, y)
                20,  240, // Punto 2 (x, y)
                60,  60,  // Punto 3 (x, y)
                240, 20,  // Punto 4 (x, y)
                50,  40,  // Punto 5 (x, y)
                10,  10   // Punto 6 (x, y)
                );

    // Creación de una imagen
    $image = imagecreatetruecolor(250, 250);

    // Asignación de algunos colores
    $bg   = imagecolorallocate($image, 0, 0, 0);
    $blue = imagecolorallocate($image, 0, 0, 255);

    // Relleno del fondo
    imagefilledrectangle($image, 0, 0, 249, 249, $bg);

    // Dibujo del polígono
    imagefilledpolygon($image, $values, $blue);

    // Visualización de la imagen
    header('Content-type: image/png');
    imagepng($image);
    ?>

Resultado del ejemplo anterior es similar a:

### Ver también

- imagepolygon() - Dibuja un polígono

# imagefilledrectangle

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilledrectangle — Dibuja un rectángulo relleno

### Descripción

function imagefilledrectangle(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

Dibuja un rectángulo de color `color` en la imagen `image`, comenzando por el vértice superior izquierdo (1) y finalizando en el vértice inferior derecho (2). La esquina superior izquierda es el origen (0, 0).

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`x1`

  X: coordenada del punto 1.

`y1`

  Y: coordenada del punto 1.

`x2`

  X: coordenada del punto 2.

`y2`

  Y: coordenada del punto 2.

`color`

  El color de relleno. Un identificador de color creado con imagecolorallocate().

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagefilledrectangle()

    <?php
    // Creación de una imagen de 55x30 píxeles
    $im = imagecreatetruecolor(55, 30);
    $white = imagecolorallocate($im, 255, 255, 255);

    // Dibuja un rectángulo blanco
    imagefilledrectangle($im, 4, 4, 50, 25, $white);

    // Guarda la imagen
    imagepng($im, './imagefilledrectangle.png');
    ?>

Resultado del ejemplo anterior es similar a:

# imagefilltoborder

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilltoborder — Rellena una región con un color específico

### Descripción

function imagefilltoborder(
GdImage `$image`,
int `$x`,
int `$y`,
int `$border_color`,
int `$color`
): true

imagefilltoborder() rellena con el color `color` toda la región dentro de la región limitada por el color `border_color`. El punto de partida es (`x`, `y`) (la esquina superior izquierda es el origen (0,0)) y el color de la región es `color`.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`x`

  X: coordenada de inicio.

`y`

  Y: coordenada de inicio.

`border_color`

  El color del borde. Un identificador de color creado con imagecolorallocate().

`color`

  El color de relleno. Un identificador de color creado con imagecolorallocate().

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Relleno de una elipse con un color

    <?php
    // Creación de un gestor de imagen, luego define el color de fondo
    // a blanco
    $im = imagecreatetruecolor(100, 100);
    imagefilledrectangle($im, 0, 0, 100, 100, imagecolorallocate($im, 255, 255, 255));

    // Dibuja una elipse cuyos bordes serán negros
    imageellipse($im, 50, 50, 50, 50, imagecolorallocate($im, 0, 0, 0));

    // Define el borde y rellena la elipse del color elegido
    $border = imagecolorallocate($im, 0, 0, 0);
    $fill = imagecolorallocate($im, 255, 0, 0);

    // Rellena la selección
    imagefilltoborder($im, 50, 50, $border, $fill);

    // Visualización y liberación de la memoria
    header('Content-type: image/png');
    imagepng($im);
    ?>

Resultado del ejemplo anterior es similar a:

### Notas

El algoritmo no recuerda explícitamente qué píxeles ya han sido definidos, sino que lo infiere a partir del color del píxel, por lo que no puede distinguir entre un píxel que acaba de ser definido y un píxel que ya estaba presente. Esto significa que elegir cualquier color de relleno que ya esté presente en la imagen puede producir resultados no deseados.

# imagefilter

(PHP 5, PHP 7, PHP 8)

imagefilter — Aplica un filtro a una imagen

### Descripción

function imagefilter(GdImage `$image`, int `$filter`, array|int|float|bool `...$args`): bool

imagefilter() aplica el filtro dado `filter` sobre la `image`.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`filter`

  `filter` puede ser uno de los siguientes:

  - `IMG_FILTER_NEGATE` : Invierte todos los colores de la imagen.
  - `IMG_FILTER_GRAYSCALE` : Convierte la imagen a niveles de gris cambiando las componentes roja, verde y azul a su suma ponderada utilizando los mismos coeficientes que el cálculo luma REC.601 (Y'). Las componentes alfa se conservan. Para imágenes de paleta, el resultado puede ser diferente debido a las limitaciones de la paleta.
  - `IMG_FILTER_BRIGHTNESS` : Modifica el brillo de la imagen. Utilice `args` para definir el nivel de brillo. El rango de brillo está entre -255 y 255.
  - `IMG_FILTER_CONTRAST` : Modifica el contraste de la imagen. Utilice `args` para definir el nivel de contraste.
  - `IMG_FILTER_COLORIZE` : similar a `IMG_FILTER_GRAYSCALE`, excepto que es posible especificar el color. Utilice `args`, `arg2` y `arg3` en forma de `red`, `green`, `blue` y `arg4` para el canal `alpha`. El rango de cada color está entre 0 y 255.
  - `IMG_FILTER_EDGEDETECT` : Utiliza la detección de bordes para resaltar los bordes de la imagen.
  - `IMG_FILTER_EMBOSS` : Permite embosar la imagen.
  - `IMG_FILTER_GAUSSIAN_BLUR` : Desenfoca la imagen utilizando el método gaussiano.
  - `IMG_FILTER_SELECTIVE_BLUR` : Desenfoca la imagen.
  - `IMG_FILTER_MEAN_REMOVAL` : Utiliza la supresión de la media para obtener un efecto "croquis".
  - `IMG_FILTER_SMOOTH` : Hace la imagen más suave. Utilice `args` para definir el nivel de suavizado.
  - `IMG_FILTER_PIXELATE` : Aplica un efecto de pixeles a la imagen, utilice `args` para definir el tamaño del bloque y `arg2` para definir el modo de efecto de pixeles.
  - `IMG_FILTER_SCATTER` : Aplica un efecto de dispersión a la imagen, utilice `args` y `arg2` para definir la intensidad del efecto y `arg3` para aplicar el efecto solo sobre ciertos colores de píxeles.
`args`

  - `IMG_FILTER_BRIGHTNESS` : Nivel de brillo.
  - `IMG_FILTER_CONTRAST` : Nivel de contraste.
  - `IMG_FILTER_COLORIZE` : Valor del componente rojo.
  - `IMG_FILTER_SMOOTH` : Nivel de suavizado.
  - `IMG_FILTER_PIXELATE` : Tamaño del bloque en píxeles.
  - `IMG_FILTER_SCATTER` : Nivel de sustracción del efecto. No debe ser superior o igual al nivel de adición definido con `arg2`.
`arg2`

  - `IMG_FILTER_COLORIZE` : Valor del componente verde.
  - `IMG_FILTER_PIXELATE` : Uso o no del efecto de pixeles avanzado (el valor por omisión es `false`).
  - `IMG_FILTER_SCATTER` : Nivel de adición del efecto.
`arg3`

  - `IMG_FILTER_COLORIZE` : Valor del componente azul.
  - `IMG_FILTER_SCATTER` : Array opcional de valores de color indexados para aplicar el efecto.
`arg4`

  - `IMG_FILTER_COLORIZE` canal Alpha, un valor entre 0 y 127. 0 indica opacidad total mientras que 127 indica transparencia total.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Genera un ValueError si `sub` o `plus` provoca un desbordamiento o un subdesbordamiento con el `IMG_FILTER_SCATTER` `filter`.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Genera ahora un ValueError si `sub` o `plus` provoca un desbordamiento o un subdesbordamiento con el `IMG_FILTER_SCATTER` `filter`.
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.
7.4.0 | Se añadió el soporte para la dispersión (`IMG_FILTER_SCATTER`).

### Ejemplos

Ejemplo #1 Ejemplo de niveles de gris con imagefilter()

    <?php
    $im = imagecreatefrompng('dave.png');

    if($im && imagefilter($im, IMG_FILTER_GRAYSCALE))
    {
        echo 'Imagen convertida a escala de grises.';

        imagepng($im, 'dave.png');
    }
    else
    {
        echo 'Conversión a escala de grises fallida.';
    }
    ?>

Ejemplo #2 Ejemplo de brillo con imagefilter()

    <?php
    $im = imagecreatefrompng('sean.png');

    if($im && imagefilter($im, IMG_FILTER_BRIGHTNESS, 20))
    {
        echo 'Brillo de la imagen cambiado.';

        imagepng($im, 'sean.png');
    }
    else
    {
        echo 'Cambio de brillo fallido.';
    }
    ?>

Ejemplo #3 Ejemplo de colorización con imagefilter()

    <?php
    $im = imagecreatefrompng('philip.png');

    /* R, G, B, así que 0, 255, 0 es verde */
    if($im && imagefilter($im, IMG_FILTER_COLORIZE, 0, 255, 0))
    {
        echo 'Imagen teñida de verde con éxito.';

        imagepng($im, 'philip.png');
    }
    else
    {
        echo 'Teñido de verde fallido.';
    }
    ?>

Ejemplo #4 Ejemplo de negativo con imagefilter()

    <?php
    // Define la función negate para que sea portable para
    // versiones de php sin imagefilter()
    function negate($im)
    {
        if(function_exists('imagefilter'))
        {
            return imagefilter($im, IMG_FILTER_NEGATE);
        }

        for($x = 0; $x < imagesx($im); ++$x)
        {
            for($y = 0; $y < imagesy($im); ++$y)
            {
                $index = imagecolorat($im, $x, $y);
                $rgb = imagecolorsforindex($index);
                $color = imagecolorallocate($im, 255 - $rgb['red'], 255 - $rgb['green'], 255 - $rgb['blue']);

                imagesetpixel($im, $x, $y, $color);
            }
        }

        return(true);
    }

    $im = imagecreatefromjpeg('kalle.jpg');

    if($im && negate($im))
    {
        echo 'Imagen convertida a colores negativos con éxito.';

        imagejpeg($im, 'kalle.jpg', 100);
    }
    else
    {
        echo 'Conversión a colores negativos fallida.';
    }
    ?>

Ejemplo #5 Ejemplo de pixeles con imagefilter()

    <?php
    // Carga el logo PHP, debemos crear dos instancias
    // para ver las diferencias
    $logo1 = imagecreatefrompng('./php.png');
    $logo2 = imagecreatefrompng('./php.png');

    // Creación de la instancia de imagen sobre la cual queremos
    // ver las diferencias
    $output = imagecreatetruecolor(imagesx($logo1) * 2, imagesy($logo1));

    // Aplica el efecto de pixeles a cada instancia con un
    // tamaño de bloque de 3
    imagefilter($logo1, IMG_FILTER_PIXELATE, 3);
    imagefilter($logo2, IMG_FILTER_PIXELATE, 3, true);

    // Fusiona las diferencias sobre la imagen de salida
    imagecopy($output, $logo1, 0, 0, 0, 0, imagesx($logo1) - 1, imagesy($logo1) - 1);
    imagecopy($output, $logo2, imagesx($logo2), 0, 0, 0, imagesx($logo2) - 1, imagesy($logo2) - 1);

    // Muestra las diferencias
    header('Content-Type: image/png');
    imagepng($output);
    ?>

Resultado del ejemplo anterior es similar a:

Ejemplo #6 Ejemplo de dispersión con imagefilter()

    <?php
    // Carga la imagen
    $logo = imagecreatefrompng('./php.png');

    // Aplica un efecto de dispersión muy suave a la imagen
    imagefilter($logo, IMG_FILTER_SCATTER, 3, 5);

    // Muestra la imagen con el efecto de dispersión
    header('Content-Type: image/png');
    imagepng($logo);
    ?>

Resultado del ejemplo anterior es similar a:

### Notas

> Nota: El resultado de `IMG_FILTER_SCATTER` siempre es aleatorio.

### Ver también

- imageconvolution() - Aplica una matriz de convolución 3x3, utilizando el coeficiente y el desplazamiento

# imageflip

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageflip — Devuelve una imagen utilizando el modo proporcionado

### Descripción

function imageflip(GdImage `$image`, int `$mode`): true

Devuelve la imagen `image` utilizando el `mode` proporcionado.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`mode`

  Modo de volteo; puede ser una de las constantes `IMG_FLIP_*`:

  Constante | Significado
  --- | ---
  `IMG_FLIP_HORIZONTAL` | Voltea la imagen horizontalmente.
  `IMG_FLIP_VERTICAL` | Voltea la imagen verticalmente.
  `IMG_FLIP_BOTH` | Voltea la imagen tanto horizontal como verticalmente.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Voltear una imagen verticalmente

Este ejemplo utiliza la constante `IMG_FLIP_VERTICAL`.

    <?php
    // Archivo
    $filename = 'phplogo.png';

    // Tipo de contenido
    header('Content-type: image/png');

    // Carga
    $im = imagecreatefrompng($filename);

    // Volteo vertical
    imageflip($im, IMG_FLIP_VERTICAL);

    // Mostrar
    imagejpeg($im);
    ?>

Resultado del ejemplo anterior es similar a:

Ejemplo #2 Voltear una imagen horizontalmente

Este ejemplo utiliza la constante `IMG_FLIP_HORIZONTAL`.

    <?php
    // Archivo
    $filename = 'phplogo.png';

    // Tipo de contenido
    header('Content-type: image/png');

    // Carga
    $im = imagecreatefrompng($filename);

    // Volteo horizontal
    imageflip($im, IMG_FLIP_HORIZONTAL);

    // Mostrar
    imagejpeg($im);
    ?>

Resultado del ejemplo anterior es similar a:

# imagefontheight

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefontheight — Devuelve la altura de la fuente

### Descripción

function imagefontheight(GdFont|int `$font`): int

Devuelve la altura de la fuente `font` en píxeles.

### Parámetros

`font`
  Puede ser 1, 2, 3, 4, 5 para las fuentes internas de codificación Latin2 (donde los números más grandes corresponden a fuentes anchas) o una instancia de GdFont retornado por imageloadfont().

### Valores devueltos

Devuelve la altura de la fuente, en píxeles.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `font` ahora acepta una instancia de GdFont y un int; anteriormente solo un int era aceptado.

### Ejemplos

Ejemplo #1 Ejemplo con imagefontheight() y fuentes internas

    <?php
    echo 'Altura de la fuente : ' . imagefontheight(4);
    ?>

Resultado del ejemplo anterior es similar a:

    Altura de la fuente : 16

Ejemplo #2 Ejemplo con imagefontheight() y imageloadfont()

    <?php
    // Carga de una fuente .gdf
    $font = imageloadfont('anonymous.gdf');

    echo 'Altura de la fuente : ' . imagefontheight($font);
    ?>

Resultado del ejemplo anterior es similar a:

    Altura de la fuente : 43

### Ver también

- imagefontwidth() - Devuelve el ancho de la fuente
- imageloadfont() - Carga una nueva fuente

# imagefontwidth

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefontwidth — Devuelve el ancho de la fuente

### Descripción

function imagefontwidth(GdFont|int `$font`): int

Devuelve el ancho de la fuente `font` en píxeles.

### Parámetros

`font`
  Puede ser 1, 2, 3, 4, 5 para las fuentes internas de codificación Latin2 (donde los números más grandes corresponden a fuentes anchas) o una instancia de GdFont retornado por imageloadfont().

### Valores devueltos

Devuelve el ancho de la fuente.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `font` ahora acepta una instancia de GdFont y un int; anteriormente solo un int era aceptado.

### Ejemplos

Ejemplo #1 Ejemplo con imagefontwidth() y las fuentes internas

    <?php
    echo 'Ancho de la fuente : ' . imagefontwidth(4);
    ?>

Resultado del ejemplo anterior es similar a:

    Ancho de la fuente : 8

Ejemplo #2 Ejemplo con imagefontwidth() y imageloadfont()

    <?php
    // Carga de una fuente .gdf
    $font = imageloadfont('anonymous.gdf');

    echo 'Ancho de la fuente : ' . imagefontwidth($font);
    ?>

Resultado del ejemplo anterior es similar a:

    Ancho de la fuente : 23

### Ver también

- imagefontheight() - Devuelve la altura de la fuente
- imageloadfont() - Carga una nueva fuente

# imageftbbox

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imageftbbox — Calcula el rectángulo de delimitación para un texto, utilizando la fuente actual y freetype2

### Descripción

function imageftbbox(
float `$size`,
float `$angle`,
string `$font_filename`,
string `$string`,
array `$options` = []
): array|false

imageftbbox() calcula el rectángulo de delimitación para el texto `text`, utilizando la fuente actual y freetype2.

> Nota:

> Anterior a PHP 8.0.0, imageftbbox() era una variante extendida de imagettfbbox() que además soporta `extrainfo`. A partir de PHP 8.0.0, imagettfbbox() es un alias de imageftbbox().

### Parámetros

`size`

  El tamaño de la fuente en puntos.

`angle`

  Ángulo, en grados, en el cual el parámetro `string` será medido.

`font_filename`

  El nombre del archivo de la fuente TrueType (puede ser una URL). Dependiendo de la versión de GD utilizada por PHP, se buscarán los archivos que no comiencen con un '/', añadiendo la extensión '.ttf', y siguiendo la ruta de fuentes definida por la biblioteca.

`string`

  La cadena a medir.

`options`

  Índices posibles para el array `options`
  Clave | Tipo | Significado
  --- | --- | ---
  `linespacing` | float | Representa el espaciado entre líneas al dibujar

### Valores devueltos

imageftbbox() devuelve un array que contiene 8 elementos representando los 4 puntos del rectángulo que rodea el texto:

0 | Esquina inferior izquierda, posición en X
1 | Esquina inferior izquierda, posición en Y
2 | Esquina inferior derecha, posición en X
3 | Esquina inferior derecha, posición en Y
4 | Esquina superior derecha, posición en X
5 | Esquina superior derecha, posición en Y
6 | Esquina superior izquierda, posición en X
7 | Esquina superior izquierda, posición en Y

Los puntos son relativos al texto según el parámetro `angle`, por lo que "arriba a la izquierda" significa la esquina en la parte superior izquierda cuando se mira el texto horizontalmente.

En caso de error, se devuelve `false`.

### Ejemplos

Ejemplo #1 Ejemplo con imageftbbox()

    <?php
    // Creación de una imagen de 300x150 píxeles
    $im = imagecreatetruecolor(300, 150);
    $black = imagecolorallocate($im, 0, 0, 0);
    $white = imagecolorallocate($im, 255, 255, 255);

    // Define el fondo en blanco
    imagefilledrectangle($im, 0, 0, 299, 299, $white);

    // Ruta hacia nuestro archivo de fuente
    $font = './arial.ttf';

    // Primero, creamos un rectángulo que contenga nuestro texto
    $bbox = imageftbbox(10, 0, $font, 'The PHP Documentation Group');

    // Nuestras coordenadas en X y en Y
    $x = $bbox[0] + (imagesx($im) / 2) - ($bbox[4] / 2) - 5;
    $y = $bbox[1] + (imagesy($im) / 2) - ($bbox[5] / 2) - 5;

    imagefttext($im, 10, 0, $x, $y, $black, $font, 'The PHP Documentation Group');

    // Muestra hacia el navegador
    header('Content-Type: image/png');

    imagepng($im);
    ?>

### Notas

> Nota: Esta función solo está disponible si si PHP es compilado con soporte Freetype (--with-freetype-dir=DIR)

### Ver también

- imagefttext() - Escribe texto en una imagen con la fuente actual FreeType 2
- imagettfbbox() - Devuelve el rectángulo que rodea un texto dibujado con una fuente TrueType

# imagefttext

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagefttext — Escribe texto en una imagen con la fuente actual FreeType 2

### Descripción

function imagefttext(
GdImage `$image`,
float `$size`,
float `$angle`,
int `$x`,
int `$y`,
int `$color`,
string `$font_filename`,
string `$text`,
array `$options` = []
): array|false

> Nota:

> Antes de PHP 8.0.0, imagefttext() era una variante extendida de imagettftext() que además soporta `extrainfo`. A partir de PHP 8.0.0, imagefttext() es un alias de imagettftext().

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`size`

  El tamaño de la fuente a utilizar, en número de puntos.

`angle`

  El ángulo, en grados; 0 grados para una lectura del texto de izquierda a derecha. Los grandes valores representan una rotación en el sentido de las agujas de un reloj. Por ejemplo, un valor de 90 tendrá como efecto leer el texto de abajo hacia arriba.

`x`

  Las coordenadas, proporcionadas por `x` y `y` definen el punto de inicio del primer carácter (y más precisamente, la esquina en la parte inferior izquierda del carácter). Este es un comportamiento diferente de la función imagestring(), donde `x` y `y` definen la esquina superior, a la izquierda del primer carácter. Por ejemplo, en la parte superior izquierda vale 0, 0.

`y`

  La ordenada `y-ordinate`. Este parámetro configura la posición base de la fuente, y no la parte inferior de esta última.

`color`

  El índice del color deseado para el texto, ver la función imagecolorexact().

`font_filename`

  La ruta hacia la fuente TrueType a utilizar.

  Dependiendo de la versión de GD utilizada por PHP, se buscarán los ficheros que no comienzan con un '`/`', añadiendo la extensión '`.ttf`', y siguiendo la ruta de las fuentes definida por la biblioteca.

  En la mayoría de los casos, cuando la fuente se encuentra en el mismo directorio que el script que intenta utilizarla, la siguiente solución permite evitar todos los problemas relativos a la inclusión.

      <?php
      // Define la variable de entorno para GD
      putenv('GDFONTPATH=' . realpath('.'));

      // Nombre de la fuente a utilizar (nota que no hay extensión .ttf)
      $font = 'SomeFont';
      ?>

`text`

  El texto a insertar en la imagen.

`options`

  Índices posibles para el array `options`
  Clave | Tipo | Significado
  --- | --- | ---
  `linespacing` | float | Define el espaciado entre líneas al dibujar

### Valores devueltos

Esta función devuelve un array que define los 4 puntos de una caja, comenzando por la esquina inferior, a la izquierda, luego, los siguientes, en el sentido de las agujas de un reloj:

0 | x : coordenada en la parte inferior, a la izquierda
1 | y : coordenada en la parte inferior, a la izquierda
2 | x : coordenada en la parte inferior, a la derecha
3 | y : coordenada en la parte inferior, a la derecha
4 | x : coordenada en la parte superior, a la derecha
5 | y : coordenada en la parte superior, a la derecha
6 | x : coordenada en la parte superior, a la izquierda
7 | y : coordenada en la parte superior, a la izquierda

En caso de error, `false` es devuelto.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagefttext()

    <?php
    // Creación de una imagen de 300x100 píxeles
    $im = imagecreatetruecolor(300, 100);
    $red = imagecolorallocate($im, 0xFF, 0x00, 0x00);
    $black = imagecolorallocate($im, 0x00, 0x00, 0x00);

    // Define el fondo en rojo
    imagefilledrectangle($im, 0, 0, 299, 99, $red);

    // Ruta hacia nuestro fichero de fuente ttf
    $font_file = './arial.ttf';

    // Dibuja el texto 'PHP Manual' utilizando una fuente de tamaño 13
    imagefttext($im, 13, 0, 105, 55, $black, $font_file, 'PHP Manual');

    // Muestra la imagen en el navegador
    header('Content-Type: image/png');

    imagepng($im);
    ?>

### Notas

> Nota: Esta función solo está disponible si si PHP es compilado con soporte Freetype (--with-freetype-dir=DIR)

### Ver también

- imageftbbox() - Calcula el rectángulo de delimitación para un texto, utilizando la fuente actual y freetype2
- imagettftext() - Dibuja un texto con una fuente TrueType

# imagegammacorrect

(PHP 4, PHP 5, PHP 7, PHP 8)

imagegammacorrect — Aplica una corrección gamma a la imagen GD

### Descripción

function imagegammacorrect(GdImage `$image`, float `$input_gamma`, float `$output_gamma`): true

Aplica una corrección gamma a la imagen GD `image`.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`input_gamma`

  El factor gamma de entrada.

`output_gamma`

  El factor gamma de salida.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagegammacorrect()

    <?php
    // Creación de una imagen
    $im = imagecreatefromgif('php.gif');

    // Corrección gamma, salida a 1.537
    imagegammacorrect($im, 1.0, 1.537);

    // Guardado y liberación de la memoria
    imagegif($im, './php_gamma_corrected.gif');
    ?>

# imagegd

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagegd — Genera una imagen en formato GD, hacia el navegador o un fichero

### Descripción

function imagegd(GdImage `$image`, ?string `$file` = `null`): bool

Genera o guarda el fichero `file` en formato GD.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`file`

  La ruta o un recurso de flujo abierto (que se cierra automáticamente después de que esta función retorne) donde guardar el archivo. Si no se define o es `null`, el flujo de imagen sin procesar se enviará directamente.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

Precaución

Sin embargo, si libgd no logra producir la imagen, esta función devuelve `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.3 | `file` ahora es nullable.
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.
7.2.0 | imagegd() ahora permite producir imágenes TrueColor. Anteriormente, eran convertidas implícitamente a paleta.

### Ejemplos

Ejemplo #1 Mostrar una imagen GD

    <?php
    // Creación de una imagen vacía y adición de texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "Un texto simple", $text_color);

    // Mostrar la imagen
    imagegd($im);

    ?>

Ejemplo #2 Guardar una imagen GD

    <?php
    // Creación de una imagen vacía y adición de texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "Un texto simple", $text_color);

    // Guardar la imagen GD
    // El formato de fichero para imágenes GD es .gd, ver http://www.libgd.org/GdFileFormats
    imagegd($im, 'simple.gd');

    ?>

### Notas

> Nota:

> El formato GD se utiliza comúnmente para permitir la carga rápida de partes de una imagen. Tenga en cuenta que el formato GD solo es utilizable en aplicaciones compatibles con GD.

Advertencia

Los formatos de imagen GD y GD2 son formatos propietarios de libgd. Deben considerarse obsoletos, y solo deben utilizarse con fines de desarrollo y pruebas.

### Ver también

- imagegd2() - Genera una imagen en formato GD2, hacia el navegador o un fichero

# imagegd2

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagegd2 — Genera una imagen en formato GD2, hacia el navegador o un fichero

### Descripción

function imagegd2(
GdImage `$image`,
?string `$file` = `null`,
int `$chunk_size` = 128,
int `$mode` = `IMG_GD2_RAW`
): bool

Genera o guarda el fichero `file` en formato GD2.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`file`

  La ruta o un recurso de flujo abierto (que se cierra automáticamente después de que esta función retorne) donde guardar el archivo. Si no se define o es `null`, el flujo de imagen sin procesar se enviará directamente.

`chunk_size`

  Tamaño del fragmento.

`mode`

  Puede ser `IMG_GD2_RAW` o `IMG_GD2_COMPRESSED`. Por omisión, vale `IMG_GD2_RAW`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

Precaución

Sin embargo, si libgd no logra producir la imagen, esta función devuelve `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.3 | `file` ahora es nulo.
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Mostrar una imagen GD2

    <?php
    // Creación de una imagen vacía y adición de texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "Un texto simple", $text_color);

    // Mostrar la imagen
    imagegd2($im);

    ?>

Ejemplo #2 Guardar una imagen GD2

    <?php
    // Creación de una imagen vacía y adición de texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "Un texto simple", $text_color);

    // Guardar la imagen GD2
    // El formato de fichero para imágenes GD2 es .gd2, ver http://www.libgd.org/GdFileFormats
    imagegd2($im, 'simple.gd2');

    ?>

### Notas

> Nota:

> El formato GD2 se utiliza comúnmente para cargar rápidamente las partes de una imagen. Tenga en cuenta que el formato GD2 solo es utilizable en aplicaciones compatibles con GD2.

Advertencia

Los formatos de imagen GD y GD2 son formatos propietarios de libgd. Deben considerarse obsoletos, y solo deben utilizarse con fines de desarrollo y pruebas.

### Ver también

- imagegd() - Genera una imagen en formato GD, hacia el navegador o un fichero

# imagegetclip

(PHP 7 >= 7.2.0, PHP 8)

imagegetclip — Obtiene el rectángulo de recorte

### Descripción

function imagegetclip(GdImage `$image`): array

imagegetclip() obtiene el rectángulo de recorte actual, es decir, el área más allá de la cual ningún píxel será dibujado.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().

### Valores devueltos

La función devuelve un array indexado con las coordenadas del rectángulo de recorte con las siguientes entradas:

- la coordenada x de la esquina superior izquierda
- la coordenada y de la esquina superior izquierda
- la coordenada x de la esquina inferior derecha
- la coordenada y de la esquina inferior derecha

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagegetclip()

Definir y obtener el rectángulo de recorte.

    <?php
    $im = imagecreate(100, 100);
    imagesetclip($im, 10,10, 89,89);
    print_r(imagegetclip($im));

El ejemplo anterior mostrará:

    Array
    (
        [0] => 10
        [1] => 10
        [2] => 89
        [3] => 89
    )

### Ver también

- imagesetclip() - Establece el rectángulo de recorte

# imagegetinterpolation

(PHP 8)

imagegetinterpolation — Obtiene el método de interpolación

### Descripción

function imagegetinterpolation(GdImage `$image`): int

Obtiene el método de interpolación actualmente definido para la `image`.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().

### Valores devueltos

Devuelve el método de interpolación.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ver también

- imagesetinterpolation() - Define el método de interpolación

# imagegif

(PHP 4, PHP 5, PHP 7, PHP 8)

imagegif — Enviar la imagen al navegador o a un archivo

### Descripción

function imagegif(GdImage `$image`, resource|string|null `$file` = `null`): bool

imagegif() crea un fichero de imagen GIF en `file` a partir de la imagen `image`. El argumento `image` es un identificador válido devuelto por la función imagecreate() o las funciones `imagecreatefrom*`.

El formato de la imagen será GIF87a, a menos que la imagen tenga un color transparente (establecido mediante la función imagecolortransparent()), lo que hará que sea en formato GIF89a.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`file`

  La ruta o un recurso de flujo abierto (que se cierra automáticamente después de que esta función retorne) donde guardar el archivo. Si no se define o es `null`, el flujo de imagen sin procesar se enviará directamente.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

Precaución

Sin embargo, si libgd no logra producir la imagen, esta función devuelve `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Visualización de una imagen utilizando imagegif()

    <?php
    // Creación de una imagen
    $im = imagecreatetruecolor(100, 100);

    // Define el fondo como blanco
    imagefilledrectangle($im, 0, 0, 99, 99, 0xFFFFFF);

    // Dibuja texto en la imagen
    imagestring($im, 3, 40, 20, 'GD Library', 0xFFBA00);

    // Muestra la imagen en el navegador
    header('Content-Type: image/gif');

    imagegif($im);
    ?>

Ejemplo #2 Conversión de una imagen PNG a GIF, utilizando imagegif()

    <?php
    // Carga de la imagen PNG
    $png = imagecreatefrompng('./php.png');

    // Guardado de la imagen como GIF
    imagegif($png, './php.gif');

    // ¡Listo!
    echo 'Conversión exitosa de la imagen PNG a GIF !';
    ?>

### Notas

> Nota:

> El siguiente código permite escribir scripts PHP más portables: el tipo de GD se detecta automáticamente. Reemplaza la secuencia `header ("Content-Type: image/gif"); ImageGif($im);` por un código más flexible:

>     <?php
>     // Creación de una imagen
>     $im = imagecreatetruecolor(100, 100);

>     // Se realizan algunas operaciones en la imagen aquí...

>     // Manejo de la visualización
>     if(function_exists('imagegif'))
>     {
>         // Para GIF
>         header('Content-Type: image/gif');

>         imagegif($im);
>     }
>     elseif(function_exists('imagejpeg'))
>     {
>         // Para JPEG
>         header('Content-Type: image/jpeg');

>         imagejpeg($im, NULL, 100);
>     }
>     elseif(function_exists('imagepng'))
>     {
>         // Para PNG
>         header('Content-Type: image/png');

>         imagepng($im);
>     }
>     elseif(function_exists('imagewbmp'))
>     {
>         // Para WBMP
>         header('Content-Type: image/vnd.wap.wbmp');

>         imagewbmp($im);
>     }
>     else
>     {
>         die('No se encontró soporte para ningún formato de imagen en este servidor PHP');
>     }

>     ?>

> Nota:

> Puede utilizarse la función imagetypes() en lugar de function_exists() para verificar la presencia de los diferentes formatos de imagen soportados:

>     <?php
>     if(imagetypes() & IMG_GIF)
>     {
>         header('Content-Type: image/gif');
>         imagegif($im);
>     }
>     elseif(imagetypes() & IMG_JPG)
>     {
>         /* ... etc. */
>     }
>     ?>

### Ver también

- imagepng() - Envía una imagen PNG a un navegador o a un fichero
- imagewbmp() - Enviar la imagen al navegador o a un archivo
- imagejpeg() - Enviar la imagen al navegador o a un archivo
- imagetypes() - Devuelve los tipos de imágenes soportados por la versión actual de PHP

# imagegrabscreen

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

imagegrabscreen — Captura la pantalla completa

### Descripción

function imagegrabscreen(): GdImage|false

imagegrabscreen() realiza una captura de toda la pantalla.

> Nota:

> Esta función solo está disponible en Windows.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un objeto imagen en caso de éxito, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de GDImage ; anteriormente, se devolvía un resource.

### Ejemplos

Ejemplo #1 Ejemplo con imagegrabscreen()

Este ejemplo muestra cómo realizar una captura de pantalla y guardarla en una imagen png.

    <?php
    $im = imagegrabscreen();
    imagepng($im, "myscreenshot.png");
    ?>

### Ver también

- imagegrabwindow() - Captura una ventana

# imagegrabwindow

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

imagegrabwindow — Captura una ventana

### Descripción

function imagegrabwindow(int `$handle`, bool `$client_area` = `false`): GdImage|false

Captura una ventana o el espacio de su cliente, utilizando un gestor de ventanas (propiedad HWND de la instancia COM).

> Nota:

> Esta función solo está disponible en Windows.

### Parámetros

`handle`

  El identificador HWND de la ventana.

`client_area`

  Incluir o no el espacio del cliente de la ventana de la aplicación.

### Valores devueltos

Devuelve un objeto imagen en caso de éxito, o `false` si ocurre un error.

### Errores/Excepciones

Se emite una alerta de tipo E_NOTICE si `window_handle` es un gestor de ventana no válido. Se emite una alerta de tipo E_WARNING si la API de Windows es demasiado antigua.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de GDImage ; anteriormente, se devolvía un resource.
8.0.0 | `client_area` ahora espera un bool ; anteriormente esperaba un int.

### Ejemplos

Ejemplo #1 Ejemplo con imagegrabwindow()

Captura una ventana (por ejemplo, IE).

    <?php
    $browser = new COM("InternetExplorer.Application");
    $handle = $browser->HWND;
    $browser->Visible = true;
    $im = imagegrabwindow($handle);
    $browser->Quit();
    imagepng($im, "iesnap.png");
    ?>

Captura una ventana (por ejemplo, IE) pero con su contenido.

    <?php
    $browser = new COM("InternetExplorer.Application");
    $handle = $browser->HWND;
    $browser->Visible = true;
    $browser->Navigate("http://www.libgd.org");

    /* ¿Funciona siempre? */
    while ($browser->Busy) {
        com_message_pump(4000);
    }
    $im = imagegrabwindow($handle, 0);
    $browser->Quit();
    imagepng($im, "iesnap.png");
    ?>

### Ver también

- imagegrabscreen() - Captura la pantalla completa

# imageinterlace

(PHP 4, PHP 5, PHP 7, PHP 8)

imageinterlace — Activa o desactiva el entrelazado

### Descripción

function imageinterlace(GdImage `$image`, ?bool `$enable` = `null`): bool

imageinterlace() activa o desactiva el bit de entrelazado.

Si el entrelazado es 1 y la imagen es JPEG, la imagen creada será un JPEG progresivo.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`enable`

  Si `true`, la imagen será entrelazada, si `false` el bit de entrelazado es desactivado. Pasar `null` hará que el comportamiento de entrelazado no sea cambiado.

### Valores devueltos

Retorna `true` si el entrelazado está activado para la imagen, `false` en caso contrario.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.5 | imageinterlace() ahora retorna un bool; anteriormente se retornaba un int (no-cero para imágenes entrelazadas, cero en caso contrario).
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.
8.0.0 | `enable` ahora espera un bool; anteriormente esperaba un int.

### Ejemplos

Ejemplo #1 Activación del entrelazado utilizando la función imageinterlace()

    <?php
    // Creación de una imagen
    $im = imagecreatefromgif('php.gif');

    // Activación del entrelazado
    imageinterlace($im, true);

    // Guardado de la imagen
    imagegif($im, './php_interlaced.gif');
    ?>

# imageistruecolor

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imageistruecolor — Determina si una imagen es una imagen truecolor

### Descripción

function imageistruecolor(GdImage `$image`): bool

imageistruecolor()determina si la imagen `image` es una imagen truecolor.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().

### Valores devueltos

Devuelve `true` si la imagen es truecolor, `false` en caso contrario.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Detección simple de una imagen en truecolor con imageistruecolor()

    <?php
    // $im es una instancia de imagen

    // Verifica si la imagen es truecolor o no
    if(!imageistruecolor($im))
    {
        // Creación de una nueva imagen en truecolor
        $tc = imagecreatetruecolor(imagesx($im), imagesy($im));

        // Copia de los píxeles
        imagecopy($tc, $im, 0, 0, 0, 0, imagesx($im), imagesy($im));

        $im = $tc;
        $tc = NULL;

        // O utilice imagepalettetotruecolor()
    }

    // Se continúa trabajando con la instancia de la imagen
    ?>

### Ver también

- imagecreatetruecolor() - Crea una nueva imagen en colores verdaderos
- imagepalettetotruecolor() - Convierte una imagen basada en una paleta a color verdadero

# imagejpeg

(PHP 4, PHP 5, PHP 7, PHP 8)

imagejpeg — Enviar la imagen al navegador o a un archivo

### Descripción

function imagejpeg(GdImage `$image`, resource|string|null `$file` = `null`, int `$quality` = -1): bool

imagejpeg() crea un fichero JPEG a partir de la imagen proporcionada.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`file`

  La ruta o un recurso de flujo abierto (que se cierra automáticamente después de que esta función retorne) donde guardar el archivo. Si no se define o es `null`, el flujo de imagen sin procesar se enviará directamente.

`quality`

  `quality` es opcional, y toma valores en el intervalo 0 (peor calidad, fichero pequeño) a 100 (mejor calidad, fichero grande). Por omisión (`-1`), se utiliza el valor de calidad IJG por defecto (aproximadamente 75).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

Precaución

Sin embargo, si libgd no logra producir la imagen, esta función devuelve `true`.

### Errores/Excepciones

Se genera una ValueError si `quality` es inválido.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Ahora se genera una ValueError si `quality` es inválido.
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Mostrar una imagen JPEG hacia el navegador

    <?php
    // Creación de una imagen vacía y adición de texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // Define el contenido del encabezado - en este caso, image/jpeg
    header('Content-Type: image/jpeg');

    // Mostrar la imagen
    imagejpeg($im);

    ?>

Resultado del ejemplo anterior es similar a:

Ejemplo #2 Guardar una imagen JPEG en un fichero

    <?php
    // Creación de una imagen vacía y adición de texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'Un texto simple', $text_color);

    // Guardar la imagen con el nombre 'simpletext.jpg'
    imagejpeg($im, 'simpletext.jpg');

    ?>

Ejemplo #3 Mostrar la imagen con una calidad del 75% hacia el navegador

    <?php
    // Creación de una imagen vacía y adición de texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'Un texto simple', $text_color);

    // Define el contenido del encabezado - en este caso, image/jpeg
    header('Content-Type: image/jpeg');

    // No se proporciona el nombre del fichero (se utiliza el valor NULL),
    // luego, se define la calidad a 75%
    imagejpeg($im, NULL, 75);

    ?>

### Notas

> Nota:

> Si se desea generar imágenes JPEG progresivas, es necesario activar el entrelazado utilizando la función imageinterlace().

### Ver también

- imagepng() - Envía una imagen PNG a un navegador o a un fichero
- imagegif() - Enviar la imagen al navegador o a un archivo
- imagewbmp() - Enviar la imagen al navegador o a un archivo
- imageinterlace() - Activa o desactiva el entrelazado
- imagetypes() - Devuelve los tipos de imágenes soportados por la versión actual de PHP

# imagelayereffect

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagelayereffect — Activa la opción de mezcla alfa para utilizar los efectos de libgd

### Descripción

function imagelayereffect(GdImage `$image`, int `$effect`): true

Activa la opción de mezcla alfa para utilizar los efectos de libgd.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`effect`

  Una de las constantes siguientes:

  `IMG_EFFECT_REPLACE`
    Utiliza el reemplazo de píxeles (equivalente a pasar `true` a la función imagealphablending())
  `IMG_EFFECT_ALPHABLEND`
    Utiliza la mezcla normal de píxeles (equivalente a pasar `false` a la función imagealphablending())
  `IMG_EFFECT_NORMAL`
    Idéntico a la constante `IMG_EFFECT_ALPHABLEND`.
  `IMG_EFFECT_OVERLAY`
    El overlay tiene como efecto que los píxeles negros del fondo permanecerán negros, los blancos del fondo permanecerán blancos, pero los grises del fondo tomarán el color del píxel del primer plano.
  `IMG_EFFECT_MULTIPLY`
    Overlay con un efecto de multiplicación.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.
7.2.0 | Añadida la constante `IMG_EFFECT_MULTIPLY` (requiere la libgd del sistema >= 2.1.1 o la libgd integrada).

### Ejemplos

Ejemplo #1 Ejemplo con imagelayereffect()

    <?php
    // Creación de una imagen
    $im = imagecreatetruecolor(100, 100);

    // Define el fondo
    imagefilledrectangle($im, 0, 0, 100, 100, imagecolorallocate($im, 220, 220, 220));

    // Aplica el overlay
    imagelayereffect($im, IMG_EFFECT_OVERLAY);

    // Dibuja 2 elipses grises
    imagefilledellipse($im, 50, 50, 40, 40, imagecolorallocate($im, 100, 255, 100));
    imagefilledellipse($im, 50, 50, 50, 80, imagecolorallocate($im, 100, 100, 255));
    imagefilledellipse($im, 50, 50, 80, 50, imagecolorallocate($im, 255, 100, 100));

    // Visualización
    header('Content-type: image/png');

    imagepng($im);
    ?>

Resultado del ejemplo anterior es similar a:

# imageline

(PHP 4, PHP 5, PHP 7, PHP 8)

imageline — Dibuja una línea

### Descripción

function imageline(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

Dibuja una línea entre dos puntos proporcionados.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`x1`

  X: coordenada del primer punto.

`y1`

  Y: coordenada del primer punto.

`x2`

  X: coordenada del segundo punto.

`y2`

  Y: coordenada del segundo punto.

`color`

  El color de relleno. Un identificador de color creado con imagecolorallocate().

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Dibuja una línea fina

    <?php

    function imagelinethick($image, $x1, $y1, $x2, $y2, $color, $thick = 1)
    {
        /* de esta manera, solo funciona bien para líneas ortogonales
        imagesetthickness($image, $thick);
        return imageline($image, $x1, $y1, $x2, $y2, $color);
        */
        if ($thick == 1) {
            return imageline($image, $x1, $y1, $x2, $y2, $color);
        }
        $t = $thick / 2 - 0.5;
        if ($x1 == $x2 || $y1 == $y2) {
            return imagefilledrectangle($image, round(min($x1, $x2) - $t), round(min($y1, $y2) - $t), round(max($x1, $x2) + $t), round(max($y1, $y2) + $t), $color);
        }
        $k = ($y2 - $y1) / ($x2 - $x1); //y = kx + q
        $a = $t / sqrt(1 + pow($k, 2));
        $points = array(
            round($x1 - (1+$k)*$a), round($y1 + (1-$k)*$a),
            round($x1 - (1-$k)*$a), round($y1 - (1+$k)*$a),
            round($x2 + (1+$k)*$a), round($y2 - (1-$k)*$a),
            round($x2 + (1-$k)*$a), round($y2 + (1+$k)*$a),
        );
        imagefilledpolygon($image, $points, 4, $color);
        return imagepolygon($image, $points, 4, $color);
    }

    ?>

### Ver también

- imagecreatetruecolor() - Crea una nueva imagen en colores verdaderos
- imagecolorallocate() - Asigna una coloración para una imagen

# imageloadfont

(PHP 4, PHP 5, PHP 7, PHP 8)

imageloadfont — Carga una nueva fuente

### Descripción

function imageloadfont(string `$filename`): GdFont|false

imageloadfont() carga una nueva fuente de usuario y devuelve su identificador.

### Parámetros

`filename`

  El formato de las fuentes depende actualmente del sistema operativo. Esto significa que es necesario generar archivos de fuentes para la máquina que ejecuta PHP.

  Formato de archivo de fuente
  Posición | Tipo de datos C | Descripción
  --- | --- | ---
  Octetos 0-3 | int | Número de caracteres de la fuente
  Octetos 4-7 | int | Valor del primer carácter de la fuente (generalmente 32 para espacio)
  Octetos 8-11 | int | Ancho en píxeles de los caracteres
  Octetos 12-15 | int | Altura en píxeles de los caracteres
  Octetos 16- | char | Tabla con los datos de los caracteres, un octeto por píxel para cada carácter, con un total de (número de caracteres * ancho * altura) octetos.

### Valores devueltos

Devuelve una instancia GdFont, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Ahora devuelve una instancia de GdFont; anteriormente se devolvía un int.

### Ejemplos

Ejemplo #1 Ejemplo con imageloadfont()

    <?php
    // Creación de una nueva imagen
    $im = imagecreatetruecolor(50, 20);
    $black = imagecolorallocate($im, 0, 0, 0);
    $white = imagecolorallocate($im, 255, 255, 255);

    // Define el fondo en blanco
    imagefilledrectangle($im, 0, 0, 49, 19, $white);

    // Carga la fuente GD y escribe '¡Hola!'
    $font = imageloadfont('./04b.gdf');
    imagestring($im, $font, 0, 0, '¡Hola!', $black);

    // Muestra en el navegador
    header('Content-type: image/png');

    imagepng($im);
    ?>

### Ver también

- imagefontwidth() - Devuelve el ancho de la fuente
- imagefontheight() - Devuelve la altura de la fuente
- imagestring() - Dibuja una cadena horizontal

# imageopenpolygon

(PHP 7 >= 7.2.0, PHP 8)

imageopenpolygon — Dibuja un polígono abierto

### Descripción

Firma disponible a partir de PHP 8.0.0 (no soportada con argumentos nombrados)

function imageopenpolygon(GdImage `$image`, array `$points`, int `$color`): bool

Firma alternativa (obsoleta a partir de PHP 8.1.0)

function imageopenpolygon(
GdImage `$image`,
array `$points`,
int `$num_points`,
int `$color`
): bool

imageopenpolygon() dibuja un polígono abierto en la `image`. A diferencia de imagepolygon(), no se dibuja ninguna línea entre el último y el primer punto.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`points`

  Un array que contiene los vértices del polígono, por ejemplo:

  points[0] | = x0
  points[1] | = y0
  points[2] | = x1
  points[3] | = y1

`num_points`

  Número total de puntos (vértices), que deben ser al menos 3.

  Si este parámetro se omite conforme a la segunda firma, `points` debe tener un número par de elementos, y `num_points` se asume que es `count($points)/2`.
`color`

  Un identificador de color creado con imagecolorallocate().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `num_points` ha sido declarado obsoleto.
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imageopenpolygon()

    <?php
    // Crear una imagen vacía
    $image = imagecreatetruecolor(400, 300);

    // Asignar un color para el polígono
    $col_poly = imagecolorallocate($image, 255, 255, 255);

    // Dibujar el polígono
    imageopenpolygon($image, array(
            0,   0,
            100, 200,
            300, 200
        ),
        $col_poly);

    // Mostrar la imagen en el navegador
    header('Content-type: image/png');

    imagepng($image);
    ?>

Resultado del ejemplo anterior es similar a:

### Ver también

- imagepolygon() - Dibuja un polígono

# imagepalettecopy

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagepalettecopy — Copia la paleta de una imagen a otra

### Descripción

function imagepalettecopy(GdImage `$dst`, GdImage `$src`): void

imagepalettecopy() copia la paleta de la imagen `src` a la imagen `dst`.

### Parámetros

`dst`

  El objeto de la imagen de destino.

`src`

  El objeto de la imagen fuente.

### Valores devueltos

No se retorna ningún valor.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `dst` y `src` ahora esperan instancias de GdImage ; anteriormente, se esperaban resources.

### Ejemplos

Ejemplo #1 Ejemplo con imagepalettecopy()

    <?php
    // Creación de 2 paletas
    $palette1 = imagecreate(100, 100);
    $palette2 = imagecreate(100, 100);

    // Define el fondo en verde
    // para la primera
    $green = imagecolorallocate($palette1, 0, 255, 0);

    // Copia la primera paleta a la segunda
    imagepalettecopy($palette2, $palette1);

    // Sabiendo que la paleta ahora está copiada, se puede
    // usar el color verde asignado a la primera paleta
    // sin necesidad de usar de nuevo la función imagecolorallocate()
    imagefilledrectangle($palette2, 0, 0, 99, 99, $green);

    // Muestra la imagen en el navegador
    header('Content-type: image/png');

    imagepng($palette2);
    ?>

# imagepalettetotruecolor

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagepalettetotruecolor — Convierte una imagen basada en una paleta a color verdadero

### Descripción

function imagepalettetotruecolor(GdImage `$image`): bool

Convierte una imagen basada en una paleta, creada por una función como imagecreate(), en una imagen en color verdadero, como imagecreatetruecolor().

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().

### Valores devueltos

Devuelve `true` si la conversión ha sido exitosa, o si la imagen de origen ya es de color verdadero, en caso contrario, devuelve `false`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Convierte cualquier objeto imagen a color verdadero

    <?php
    // Compatibilidad ascendente
    if(!function_exists('imagepalettetotruecolor'))
    {
        function imagepalettetotruecolor(&$src)
        {
            if(imageistruecolor($src))
            {
                return(true);
            }

            $dst = imagecreatetruecolor(imagesx($src), imagesy($src));

            imagecopy($dst, $src, 0, 0, 0, 0, imagesx($src), imagesy($src));

            $src = $dst;

            return(true);
        }
    }

    // Utilización de una Closure
    $typeof = function() use($im)
    {
        echo 'typeof($im) = ' . (imageistruecolor($im) ? 'true color' : 'palette'), PHP_EOL;
    };

    // Crea una imagen basada en una paleta
    $im = imagecreate(100, 100);
    $typeof();

    // La convierte a color verdadero
    imagepalettetotruecolor($im);
    $typeof();

    ?>

El ejemplo anterior mostrará:

    typeof($im) = palette
    typeof($im) = true color

### Ver también

- imagecreatetruecolor() - Crea una nueva imagen en colores verdaderos
- imageistruecolor() - Determina si una imagen es una imagen truecolor

# imagepng

(PHP 4, PHP 5, PHP 7, PHP 8)

imagepng — Envía una imagen PNG a un navegador o a un fichero

### Descripción

function imagepng(
GdImage `$image`,
resource|string|null `$file` = `null`,
int `$quality` = -1,
int `$filters` = -1
): bool

imagepng() muestra o guarda una imagen en formato PNG utilizando la imagen `image`.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`file`

  La ruta o un recurso de flujo abierto (que se cierra automáticamente después de que esta función retorne) donde guardar el archivo. Si no se define o es `null`, el flujo de imagen sin procesar se enviará directamente.

  > Nota:

  > El valor `null` es inválido si el argumento `quality` y el argumento `filters` no son utilizados.

`quality`

  Grado de compresión: desde 0 (ninguna compresión) hasta 9. El valor por omisión (`-1`) utiliza la compresión por omisión de zlib. Para más información ver el » manual zlib.

`filters`

  Permite la reducción del tamaño del fichero PNG. Es una máscara que puede ser definida por una combinación de las constantes `PNG_FILTER_*`. `PNG_NO_FILTER` o `PNG_ALL_FILTERS` pueden ser utilizados para, respectivamente, desactivar o activar todos los filtros. El valor por omisión (`-1`) desactiva el filtrado.

  Precaución

  El argumento `filters` es ignorado por la libgd del sistema.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

Precaución

Sin embargo, si libgd no logra producir la imagen, esta función devuelve `true`.

### Errores/Excepciones

Genera una ValueError si `quality` es inválido.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Genera ahora una ValueError si `quality` es inválido.
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

    <?php
    $im = imagecreatefrompng("test.png");

    header('Content-Type: image/png');

    imagepng($im);
    ?>

### Ver también

- imagegif() - Enviar la imagen al navegador o a un archivo
- imagewbmp() - Enviar la imagen al navegador o a un archivo
- imagejpeg() - Enviar la imagen al navegador o a un archivo
- imagetypes() - Devuelve los tipos de imágenes soportados por la versión actual de PHP
- imagesavealpha() - Determina si la información completa del canal alpha debe conservarse al guardar imágenes

# imagepolygon

(PHP 4, PHP 5, PHP 7, PHP 8)

imagepolygon — Dibuja un polígono

### Descripción

Firma disponible a partir de PHP 8.0.0 (no soportada con argumentos nombrados)

function imagepolygon(GdImage `$image`, array `$points`, int `$color`): bool

Firma alternativa (deprecada a partir de PHP 8.1.0)

function imagepolygon(
GdImage `$image`,
array `$points`,
int `$num_points`,
int `$color`
): bool

imagepolygon() dibuja un polígono en la imagen `image`.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`points`

  Un array que contiene los vértices del polígono, por ejemplo:

  points[0] | = x0
  points[1] | = y0
  points[2] | = x1
  points[3] | = y1

`num_points`

  Número total de puntos (vértices), que deben ser al menos 3.

  Si este argumento es omitido conforme a la segunda firma, `points` debe tener un número par de elementos, y `num_points` se asume como `count($points)/2`.
`color`

  Un identificador de color creado con imagecolorallocate().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El argumento `num_points` ha sido deprecado.
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagepolygon()

    <?php
    // Creación de una imagen vacía
    $image = imagecreatetruecolor(400, 300);

    // Asigna un color para el polígono
    $col_poly = imagecolorallocate($image, 255, 255, 255);

    // Dibuja el polígono
    imagepolygon($image, array(
            0,   0,
            100, 200,
            300, 200
        ),
        $col_poly);

    // Muestra la imagen en el navegador
    header('Content-type: image/png');

    imagepng($image);
    ?>

Resultado del ejemplo anterior es similar a:

### Ver también

- imagefilledpolygon() - Dibuja un polígono relleno
- imageopenpolygon() - Dibuja un polígono abierto
- imagecreate() - Crea una nueva imagen con paleta
- imagecreatetruecolor() - Crea una nueva imagen en colores verdaderos

# imagerectangle

(PHP 4, PHP 5, PHP 7, PHP 8)

imagerectangle — Dibuja un rectángulo

### Descripción

function imagerectangle(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

imagerectangle() dibuja un rectángulo en las coordenadas especificadas. El punto 0, 0 es la esquina superior izquierda de la imagen.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`x1`

  X: coordenada de la esquina superior izquierda.

`y1`

  Y: coordenada de la esquina superior izquierda.

`x2`

  X: coordenada del punto inferior derecho.

`y2`

  Y: coordenada del punto inferior derecho.

`color`

  Un identificador de color creado con imagecolorallocate().

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagerectangle()

    <?php
    // Creación de una imagen de 200 x 200 píxeles
    $canvas = imagecreatetruecolor(200, 200);

    // Asigna los colores
    $pink = imagecolorallocate($canvas, 255, 105, 180);
    $white = imagecolorallocate($canvas, 255, 255, 255);
    $green = imagecolorallocate($canvas, 132, 135, 28);

    // Dibuja 3 rectángulos, cada uno con su color
    imagerectangle($canvas, 50, 50, 150, 150, $pink);
    imagerectangle($canvas, 45, 60, 120, 100, $white);
    imagerectangle($canvas, 100, 120, 75, 160, $green);

    // Visualización
    header('Content-Type: image/jpeg');
    imagejpeg($canvas);
    ?>

Resultado del ejemplo anterior es similar a:

# imageresolution

(PHP 7 >= 7.2.0, PHP 8)

imageresolution — Recupera o define la resolución de la imagen

### Descripción

function imageresolution(GdImage `$image`, ?int `$resolution_x` = `null`, ?int `$resolution_y` = `null`): array|true

imageresolution() permite definir y recuperar la resolución de una imagen en DPI (puntos por pulgada). Si los parámetros opcionales son `null`, la resolución actual se devuelve en un array indexado. Si únicamente `resolution_x` no es `null`, la resolución horizontal y vertical se establece a este valor. Si ninguno de los parámetros opcionales es `null`, la resolución horizontal y vertical se establecen a estos valores respectivamente.

La resolución se utiliza únicamente como metadatos cuando las imágenes se leen y escriben en formatos que soportan este tipo de información (actualmente PNG y JPEG). Esto no afecta a las operaciones de dibujo. La resolución por defecto de las nuevas imágenes es de 96 DPI.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`resolution_x`

  La resolución horizontal en DPI/PPP.

`resolution_y`

  La resolución vertical en DPI/PPP.

### Valores devueltos

Cuando se utiliza como recuperador, esto devuelve un array indexado con las resoluciones horizontal y vertical en caso de éxito. Cuando se utiliza como definidor, siempre devuelve `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `resolution_x` y `resolution_y` son ahora nullable.

### Ejemplos

Ejemplo #1 Definir y recuperar la resolución de una imagen

    <?php
    $im = imagecreatetruecolor(100, 100);
    imageresolution($im, 200);
    print_r(imageresolution($im));
    imageresolution($im, 300, 72);
    print_r(imageresolution($im));
    ?>

El ejemplo anterior mostrará:

    Array
    (
        [0] => 200
        [1] => 200
    )
    Array
    (
        [0] => 300
        [1] => 72
    )

# imagerotate

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagerotate — Rota una imagen en un ángulo

### Descripción

function imagerotate(GdImage `$image`, float `$angle`, int `$background_color`): GdImage|false

imagerotate() rota la imagen `image` en un ángulo de `angle`, en grados.

El centro de rotación es el centro de la imagen, y la imagen rotada puede tener dimensiones diferentes de la imagen original.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`angle`

  El ángulo de rotación, en grados. El ángulo de rotación es interpretado como el número de grados para rotar la imagen en sentido contrario a las agujas del reloj.

`background_color`

  Especifica el color de las zonas que serán descubiertas después de la rotación.

### Valores devueltos

Devuelve un objeto de imagen correspondiente a la imagen después de la rotación, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.3.0 | El parámetro no utilizado `ignore_transparent` ha sido completamente eliminado.
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de GDImage ; anteriormente, se devolvía un resource.
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.
8.0.0 | El parámetro no utilizado `ignore_transparent` ahora espera un bool ; anteriormente esperaba un int.

### Ejemplos

Ejemplo #1 Rotación de una imagen de 180 grados

Este ejemplo rota una imagen de 180 grados - al revés.

    <?php
    // Archivo y grados de rotación
    $filename = 'test.jpg';
    $degrees = 180;

    // Tipo de contenido
    header('Content-type: image/jpeg');

    // Carga
    $source = imagecreatefromjpeg($filename);

    // Rotación
    $rotate = imagerotate($source, $degrees, 0);

    // Mostrar
    imagejpeg($rotate);

    ?>

Resultado del ejemplo anterior es similar a:

### Notas

> Nota: Esta función es afectada por el método de interpolación, definido por la función imagesetinterpolation().

### Ver también

- imagesetinterpolation() - Define el método de interpolación

# imagesavealpha

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imagesavealpha — Determina si la información completa del canal alpha debe conservarse al guardar imágenes

### Descripción

function imagesavealpha(GdImage `$image`, bool `$enable`): true

imagesavealpha() define el flag que determina si la información del canal alpha (en oposición a la transparencia de color único) debe conservarse al guardar imágenes. Esto es soportado solo para los formatos de imagen que soportan toda la información de strings alpha, por ejemplo `PNG`, `WebP` y `AVIF`.

> Nota: imagesavealpha() es solo significativo para las imágenes `PNG`, ya que los strings alpha completos siempre son guardados para `WebP` y `AVIF`. No se recomienda confiar en este comportamiento, ya que podría cambiar en el futuro. Por lo tanto, imagesavealpha() debe ser llamado intencionalmente también para las imágenes `WebP` y `AVIF`.

El alphablending debe ser desactivado (`imagealphablending($im, false)`) para conservar el canal alpha en primer lugar.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`enable`

  Si el canal alpha debe o no ser guardado. Por omisión `false`.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Uso simple de imagesavealpha()

    <?php
    // Carga una imagen PNG con un canal alpha
    $png = imagecreatefrompng('./alphachannel_example.png');

    // Desactivar el alpha blending
    imagealphablending($png, false);

    // Realizar las operaciones deseadas

    // Definir el flag alpha
    imagesavealpha($png, true);

    // Mostrar la imagen en el navegador
    header('Content-Type: image/png');

    imagepng($png);
    ?>

### Ver también

- imagealphablending() - Modifica el modo de mezcla de una imagen

# imagescale

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagescale — Redimensiona una imagen utilizando una altura y una anchura proporcionadas

### Descripción

function imagescale(
GdImage `$image`,
int `$width`,
int `$height` = -1,
int `$mode` = `IMG_BILINEAR_FIXED`
): GdImage|false

imagescale() redimensiona una imagen utilizando el algoritmo de interpolación dado.

> Nota:

> A diferencia de muchas otras funciones de imagen, imagescale() no modifica la `image` proporcionada; en su lugar, se devuelve una nueva imagen.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`width`

  La anchura a utilizar para el redimensionamiento de la imagen.

`height`

  La altura a utilizar para el redimensionamiento de la imagen. Si se omite o es negativa, se preservará la relación de aspecto de la imagen.

`mode`

  Una de las constantes `IMG_NEAREST_NEIGHBOUR`, `IMG_BILINEAR_FIXED`, `IMG_BICUBIC`, `IMG_BICUBIC_FIXED` o cualquier otra (utilizará dos pasadas).

  > Nota: `IMG_WEIGHTED4` aún no está soportado.

### Valores devueltos

Devuelve el objeto de la imagen redimensionada en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Genera una ValueError si `width` o `height` provoca un desbordamiento o un subdesbordamiento.

Genera una ValueError si `mode` es inválido.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Ahora genera una ValueError si `width` o `height` provoca un desbordamiento o un subdesbordamiento.
8.4.0 | Ahora genera una ValueError si `mode` es inválido.
8.0.0 | En caso de éxito, esta función devuelve ahora una instancia de GDImage; anteriormente, se devolvía un resource.
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ver también

- imagecopyresized() - Copia y redimensiona una parte de una imagen
- imagecopyresampled() - Copia, redimensiona y reinterpolación de una imagen

# imagesetbrush

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetbrush — Modifica el pincel para el dibujo de líneas

### Descripción

function imagesetbrush(GdImage `$image`, GdImage `$brush`): true

imagesetbrush() reemplaza el pincel actual para el dibujo de líneas por `brush`. Este pincel será entonces utilizado con funciones como imageline() o imagepolygon() y con los colores especiales `IMG_COLOR_BRUSHED` o `IMG_COLOR_STYLEDBRUSHED`.

Precaución

No es necesario realizar ninguna acción cuando se ha terminado con un pincel, pero si se destruye la imagen del pincel, NO DEBE utilizarse las opciones `IMG_COLOR_BRUSHED` y `IMG_COLOR_STYLEDBRUSHED` antes de crear un nuevo pincel.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`brush`

  Un objeto de imagen.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` y `brush` ahora requieren instancias de GdImage ; anteriormente, se esperaban resources.

### Ejemplos

Ejemplo #1 Ejemplo con imagesetbrush()

    <?php

    // Carga un mini-logo PHP
    $php = imagecreatefrompng('./php.png');

    // Creación de la imagen principal, 100x100
    $im = imagecreatetruecolor(100, 100);

    // Define el fondo en blanco
    $white = imagecolorallocate($im, 255, 255, 255);
    imagefilledrectangle($im, 0, 0, 99, 99, $white);

    // Define el pincel
    imagesetbrush($im, $php);

    // Dibuja algunas pinceladas
    imageline($im, 50, 50, 50, 60, IMG_COLOR_BRUSHED);

    // Muestra la imagen en el navegador
    header('Content-type: image/png');

    imagepng($im);
    ?>

Resultado del ejemplo anterior es similar a:

# imagesetclip

(PHP 7 >= 7.2.0, PHP 8)

imagesetclip — Establece el rectángulo de recorte

### Descripción

function imagesetclip(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`
): true

imagesetclip() establece el rectángulo de recorte actual, es decir, el área más allá de la cual ningún píxel será dibujado.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`x1`

  La coordenada x de la esquina superior izquierda.

`y1`

  La coordenada y de la esquina superior izquierda.

`x2`

  La coordenada x de la esquina inferior derecha.

`y2`

  La coordenada y de la esquina inferior derecha.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ver también

- imagegetclip() - Obtiene el rectángulo de recorte

# imagesetinterpolation

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagesetinterpolation — Define el método de interpolación

### Descripción

function imagesetinterpolation(GdImage `$image`, int `$method` = `IMG_BILINEAR_FIXED`): bool

Define el método de interpolación; el hecho de definir un método de interpolación afecta el rendimiento de varias funciones en GD, como por ejemplo la función imagerotate().

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`method`

  El método de interpolación, que puede ser uno de los siguientes:

  - `IMG_BELL`: filtro Bell.
  - `IMG_BESSEL`: filtro Bessel.
  - `IMG_BICUBIC`: interpolación bicúbica.
  - `IMG_BICUBIC_FIXED`: implementación de punto fijo de una interpolación bicúbica.
  - `IMG_BILINEAR_FIXED`: implementación de punto fijo de una interpolación bilineal (`por defecto (incluyendo para la creación de imágenes)`).
  - `IMG_BLACKMAN`: función de ventana Blackman.
  - `IMG_BOX`: filtro de desenfoque Box.
  - `IMG_BSPLINE`: interpolación Spline.
  - `IMG_CATMULLROM`: interpolación cubica Hermite spline.
  - `IMG_GAUSSIAN`: función Gaussiana.
  - `IMG_GENERALIZED_CUBIC`: interpolación fractal cubica generalizada spline.
  - `IMG_HERMITE`: interpolación Hermite.
  - `IMG_HAMMING`: filtro Hamming.
  - `IMG_HANNING`: filtro Hanning.
  - `IMG_MITCHELL`: filtro Mitchell.
  - `IMG_POWER`: interpolación Power.
  - `IMG_QUADRATIC`: interpolación cuadrática inversa.
  - `IMG_SINC`: función Sinc.
  - `IMG_NEAREST_NEIGHBOUR`: interpolación del vecino más cercano.
  - `IMG_WEIGHTED4`: filtro Weighting.
  - `IMG_TRIANGLE`: interpolación Triangle.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagesetinterpolation()

    <?php
    // Carga de la imagen
    $im = imagecreate(500, 500);

    // Por defecto, la interpolación es IMG_BILINEAR_FIXED; se utiliza en su lugar
    // el filtro 'Mitchell':
    imagesetinterpolation($im, IMG_MITCHELL);

    // Se continúa trabajando con $im...
    ?>

### Notas

La modificación del método de interpolación afecta a las siguientes funciones durante el rendimiento:

- imageaffine()
- imagerotate()

### Ver también

- imagegetinterpolation() - Obtiene el método de interpolación

# imagesetpixel

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesetpixel — Dibuja un píxel

### Descripción

function imagesetpixel(
GdImage `$image`,
int `$x`,
int `$y`,
int `$color`
): true

imagesetpixel() dibuja un píxel en las coordenadas especificadas.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`x`

  X: coordenada.

`y`

  Y: coordenada.

`color`

  Un identificador de color creado con imagecolorallocate().

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagesetpixel()

Un dibujo aleatorio que termina con una imagen regular.

    <?php

    $x = 200;
    $y = 200;

    $gd = imagecreatetruecolor($x, $y);

    $corners[0] = array('x' => 100, 'y' =>  10);
    $corners[1] = array('x' =>   0, 'y' => 190);
    $corners[2] = array('x' => 200, 'y' => 190);

    $red = imagecolorallocate($gd, 255, 0, 0);

    for ($i = 0; $i < 100000; $i++) {
      imagesetpixel($gd, round($x), round($y), $red);
      $a = rand(0, 2);
      $x = ($x + $corners[$a]['x']) / 2;
      $y = ($y + $corners[$a]['y']) / 2;
    }

    header('Content-Type: image/png');
    imagepng($gd);

    ?>

Resultado del ejemplo anterior es similar a:

### Ver también

- imagecreatetruecolor() - Crea una nueva imagen en colores verdaderos
- imagecolorallocate() - Asigna una coloración para una imagen
- imagecolorat() - Devuelve el índice del color de un píxel dado

# imagesetstyle

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetstyle — Configura el estilo para el dibujo de líneas

### Descripción

function imagesetstyle(GdImage `$image`, array `$style`): bool

imagesetstyle() permite seleccionar el estilo a utilizar al dibujar líneas (como con las funciones imageline() y imagepolygon()) al utilizar la color especial `IMG_COLOR_STYLED` o bien al dibujar líneas con la color `IMG_COLOR_STYLEDBRUSHED`.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`style`

  Un array de colores de píxeles. Puede utilizarse la constante `IMG_COLOR_TRANSPARENT` para añadir un píxel transparente. Tenga en cuenta que `style` no debe ser un array array vacío.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

El siguiente ejemplo dibuja una línea punteada desde la esquina superior izquierda hacia la esquina inferior derecha de la imagen:

Ejemplo #1 Ejemplo para imagesetstyle()

    <?php
    header("Content-type: image/jpeg");
    $im  = imagecreatetruecolor(100, 100);
    $w   = imagecolorallocate($im, 255, 255, 255);
    $red = imagecolorallocate($im, 255, 0, 0);

    /* Dibuja una línea punteada de 5 píxeles rojos, 5 píxeles blancos */
    $style = array($red, $red, $red, $red, $red, $w, $w, $w, $w, $w);
    imagesetstyle($im, $style);
    imageline($im, 0, 0, 100, 100, IMG_COLOR_STYLED);

    /* Dibuja una línea con smileys, utilizando imagesetbrush() y imagesetstyle */
    $style = array($w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $red);
    imagesetstyle($im, $style);

    $brush = imagecreatefrompng("http://www.libpng.org/pub/png/images/smile.happy.png");
    $w2 = imagecolorallocate($brush, 255, 255, 255);
    imagecolortransparent($brush, $w2);
    imagesetbrush($im, $brush);
    imageline($im, 100, 0, 0, 100, IMG_COLOR_STYLEDBRUSHED);

    imagejpeg($im);
    ?>

Resultado del ejemplo anterior es similar a:

### Ver también

- imagesetbrush() - Modifica el pincel para el dibujo de líneas
- imageline() - Dibuja una línea

# imagesetthickness

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetthickness — Modifica el grosor de una línea

### Descripción

function imagesetthickness(GdImage `$image`, int `$thickness`): true

imagesetthickness() modifica el grosor de las líneas en la imagen `image`. Este grosor se aplica en los dibujos de polígonos, círculos, rectángulos, etc. `thickness` se expresa en píxeles.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`thickness`

  El grosor, en píxeles.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagesetthickness()

    <?php

    // Creación de una imagen de 200x100
    $im = imagecreatetruecolor(200, 100);
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
    $black = imagecolorallocate($im, 0x00, 0x00, 0x00);

    // Establece el fondo en blanco
    imagefilledrectangle($im, 0, 0, 199, 99, $white);

    // Establece el grosor de la línea a 5
    imagesetthickness($im, 5);

    // Dibuja el rectángulo
    imagerectangle($im, 14, 14, 185, 85, $black);

    // Muestra la imagen en el navegador
    header('Content-Type: image/png');

    imagepng($im);
    ?>

Resultado del ejemplo anterior es similar a:

# imagesettile

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesettile — Modifica la imagen utilizada para el mosaico

### Descripción

function imagesettile(GdImage `$image`, GdImage `$tile`): true

imagesettile() reemplaza la imagen de pavimentación actual por la imagen `tile`, a utilizar en todos los rellenos (como con las funciones imagefill() y imagefilledpolygon()) durante los rellenos con la opción `IMG_COLOR_TILED`.

Una imagen de mosaico es una imagen utilizada para rellenar una zona, de manera repetitiva. Cualquier imagen GD puede servir como imagen de relleno. El uso de la transparencia (gestionada con la función imagecolortransparent()) permite que ciertas zonas aparezcan a través del mosaico.

Precaución

No hay nada que hacer cuando se ha terminado con un pincel, pero si se destruye la imagen del pincel (o se deja que PHP lo destruya), ya no DEBE utilizarse la opción `IMG_COLOR_TILED` de las funciones imagefill() y imagefilledpolygon(), antes de crear un nuevo pincel.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`tile`

  El objeto de la imagen a utilizar como mosaico.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` y `tile` ahora esperan instancias de GdImage ; anteriormente, se esperaban resources.

### Ejemplos

Ejemplo #1 Ejemplo con imagesettile()

    <?php
    // Carga de una imagen externa
    $zend = imagecreatefromgif('./zend.gif');

    // Creación de una imagen de 200x200 píxeles
    $im = imagecreatetruecolor(200, 200);

    // Definición del mosaico
    imagesettile($im, $zend);

    // Repetición de la imagen
    imagefilledrectangle($im, 0, 0, 199, 199, IMG_COLOR_TILED);

    // Visualización en el navegador
    header('Content-Type: image/png');

    imagepng($im);
    ?>

Resultado del ejemplo anterior es similar a:

# imagestring

(PHP 4, PHP 5, PHP 7, PHP 8)

imagestring — Dibuja una cadena horizontal

### Descripción

function imagestring(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$string`,
int `$color`
): true

Dibuja una cadena en las coordenadas especificadas.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`font`
  Puede ser 1, 2, 3, 4, 5 para las fuentes internas de codificación Latin2 (donde los números más grandes corresponden a fuentes anchas) o una instancia de GdFont retornado por imageloadfont().
`x`

  X: coordenada de la esquina superior izquierda.

`y`

  Y: coordenada de la esquina superior izquierda.

`string`

  La cadena a escribir.

`color`

  Un identificador de color creado con imagecolorallocate().

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `font` ahora acepta una instancia de GdFont y un int; anteriormente solo un int era aceptado.
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagestring()

    <?php
    // Nueva imagen 100*30
    $im = imagecreate(100, 30);

    // Fondo blanco y texto azul
    $bg = imagecolorallocate($im, 255, 255, 255);
    $textcolor = imagecolorallocate($im, 0, 0, 255);

    // Añadir la frase en la esquina superior izquierda
    imagestring($im, 5, 0, 0, 'Hello world!', $textcolor);

    // Mostrar la imagen
    header('Content-type: image/png');

    imagepng($im);
    ?>

Resultado del ejemplo anterior es similar a:

### Ver también

- imagestringup() - Dibuja una cadena vertical
- imageloadfont() - Carga una nueva fuente
- imagettftext() - Dibuja un texto con una fuente TrueType

# imagestringup

(PHP 4, PHP 5, PHP 7, PHP 8)

imagestringup — Dibuja una cadena vertical

### Descripción

function imagestringup(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$string`,
int `$color`
): true

Dibuja una cadena en una línea vertical en la imagen `image` en las coordenadas especificadas.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`font`
  Puede ser 1, 2, 3, 4, 5 para las fuentes internas de codificación Latin2 (donde los números más grandes corresponden a fuentes anchas) o una instancia de GdFont retornado por imageloadfont().
`x`

  Coordenada X del ángulo superior izquierdo.

`y`

  Coordenada Y del ángulo superior izquierdo.

`string`

  El string a escribir.

`color`

  Un identificador de color creado con imagecolorallocate().

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `font` ahora acepta una instancia de GdFont y un int; anteriormente solo un int era aceptado.
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagestringup()

    <?php
    // Creación de una imagen de 100*100 píxeles
    $im = imagecreatetruecolor(100, 100);

    // Dibuja un texto
    $textcolor = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
    imagestringup($im, 3, 40, 80, 'gd library', $textcolor);

    // Guarda la imagen
    imagepng($im, './stringup.png');
    ?>

Resultado del ejemplo anterior es similar a:

### Ver también

- imagestring() - Dibuja una cadena horizontal
- imageloadfont() - Carga una nueva fuente

# imagesx

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesx — Devuelve el ancho de una imagen

### Descripción

function imagesx(GdImage `$image`): int

Devuelve el ancho del objeto imagen `image`.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().

### Valores devueltos

Devuelve el ancho de la imagen `image`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagesx()

    <?php

    // Creación de una imagen de 300*200
    $img = imagecreatetruecolor(300, 200);

    echo imagesx($img); // 300

    ?>

### Ver también

- imagecreatetruecolor() - Crea una nueva imagen en colores verdaderos
- getimagesize() - Devuelve el tamaño de una imagen
- imagesy() - Devuelve la altura de la imagen

# imagesy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesy — Devuelve la altura de la imagen

### Descripción

function imagesy(GdImage `$image`): int

Devuelve la altura de la imagen `image`.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().

### Valores devueltos

Devuelve la altura de la imagen `image`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imagesy()

    <?php

    // Creación de una imagen 300*200
    $img = imagecreatetruecolor(300, 200);

    echo imagesy($img); // 200

    ?>

### Ver también

- imagecreatetruecolor() - Crea una nueva imagen en colores verdaderos
- getimagesize() - Devuelve el tamaño de una imagen
- imagesx() - Devuelve el ancho de una imagen

# imagetruecolortopalette

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagetruecolortopalette — Convierte una imagen en colores verdaderos a imagen con paleta

### Descripción

function imagetruecolortopalette(GdImage `$image`, bool `$dither`, int `$num_colors`): bool

imagetruecolortopalette() convierte la imagen en colores verdaderos `image` a imagen con paleta. El código de esta función es directamente tomado de la biblioteca del `Independent JPEG Group`, que es simplemente genial. El código ha sido modificado para preservar la mayor parte del canal alfa en la nueva paleta, además de conservar las colores lo mejor posible. Pero esto no siempre funciona como se desea. En ese caso, es preferible generar un resultado en colores verdaderos, lo que siempre proporciona el mejor rendimiento.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`dither`

  Indica si la imagen debe ser granulada - si se define como `true`, entonces la imagen será un poco más granulada pero la aproximación de los colores será mejor.

`num_colors`

  El número máximo de colores en la paleta final.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Conversión de una imagen truecolor a una paleta

    <?php
    // Creación de una imagen truecolor
    $im = imagecreatetruecolor(100, 100);

    // Conversión a paleta de 255 colores
    imagetruecolortopalette($im, false, 255);

    // Guardado de la imagen
    imagepng($im, './paletteimage.png');
    ?>

# imagettfbbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imagettfbbox — Devuelve el rectángulo que rodea un texto dibujado con una fuente TrueType

### Descripción

function imagettfbbox(
float `$size`,
float `$angle`,
string `$font_filename`,
string `$string`,
array `$options` = []
): array|false

Calcula y devuelve el rectángulo que rodea el texto `text`, escrito con una fuente TrueType.

> Nota:

> Antes de PHP 8.0.0, imageftbbox() era una variante extendida de imagettfbbox() que además soporta `extrainfo`. A partir de PHP 8.0.0, imagettfbbox() es un alias de imageftbbox().

### Parámetros

`size`

  El tamaño de la fuente en puntos.

`angle`

  El ángulo, en grados, en el que el parámetro `string` será medido.

`fontfile`

  La ruta de acceso al fichero de la fuente TrueType que desea utilizar.

  Dependiendo de qué versión de la biblioteca GD esté utilizando PHP, cuando `fontfile` no comienza con una barra diagonal inicial `/` entonces `.ttf` será añadido al nombre del fichero y la biblioteca intentará buscar ese nombre de fichero a lo largo de una ruta de acceso de fuentes definida por la biblioteca.

  Al utilizar versiones de la biblioteca GD inferiores a 2.0.18, un carácter `espacio`, en lugar de un punto y coma, se utilizaba como 'separador de rutas' para diferentes ficheros de fuentes. El uso no intencional de esta característica resultará en el mensaje de advertencia: `Advertencia: No se pudo encontrar/abrir la fuente`. Para estas versiones afectadas, la única solución es mover la fuente a una ruta que no contenga espacios.

  En muchos casos donde una fuente reside en el mismo directorio que el script que la utiliza, el siguiente truco aliviará cualquier problema de inclusión.

      <?php
      // Establecer la variable de entorno para GD
      putenv('GDFONTPATH=' . realpath('.'));
      // Nombre de la fuente a ser utilizada (note la falta de la extensión .ttf)
      $font = 'SomeFont';
      ?>

  > Nota:

  > Tenga en cuenta que open_basedir no aplica a `fontfile`.

`string`

  La cadena a medir.

`options`

  Similar a imagettftext().

### Valores devueltos

imagettfbbox() devuelve un array con 8 elementos representando los 4 vértices del rectángulo en caso de éxito, `false` si ocurre un error.

Clave | Significado
--- | ---
0 | Esquina inferior izquierda, abscisa
1 | Esquina inferior izquierda, ordenada
2 | Esquina inferior derecha, abscisa
3 | Esquina inferior derecha, ordenada
4 | Esquina superior derecha, abscisa
5 | Esquina superior derecha, ordenada
6 | Esquina superior izquierda, abscisa
7 | Esquina superior izquierda, ordenada

Las posiciones de los puntos son relativas al texto text, independientemente del ángulo: esquina superior izquierda hace referencia a la esquina superior izquierda del texto escrito horizontalmente.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | El parámetro `options` ha sido añadido.

### Ejemplos

Ejemplo #1 Ejemplo con imagettfbbox()

    <?php
    // Creación de una imagen de 300x150 píxeles
    $im = imagecreatetruecolor(300, 150);
    $black = imagecolorallocate($im, 0, 0, 0);
    $white = imagecolorallocate($im, 255, 255, 255);

    // Define el fondo en blanco
    imagefilledrectangle($im, 0, 0, 299, 299, $white);

    // Ruta al archivo de la fuente
    $font = './arial.ttf';

    // Primero, creamos nuestro rectángulo que rodea nuestro primer texto
    $bbox = imagettfbbox(10, 45, $font, 'Powered by PHP ' . phpversion());

    // Nuestras coordenadas en X y en Y
    $x = $bbox[0] + (imagesx($im) / 2) - ($bbox[4] / 2) - 25;
    $y = $bbox[1] + (imagesy($im) / 2) - ($bbox[5] / 2) - 5;

    // Dibujo del texto
    imagettftext($im, 10, 45, $x, $y, $black, $font, 'Powered by PHP ' . phpversion());

    // Creamos nuestro rectángulo que rodea nuestro segundo texto
    $bbox = imagettfbbox(10, 45, $font, 'and Zend Engine ' . zend_version());

    // Define las coordenadas para que el segundo texto siga al primero
    $x = $bbox[0] + (imagesx($im) / 2) - ($bbox[4] / 2) + 10;
    $y = $bbox[1] + (imagesy($im) / 2) - ($bbox[5] / 2) - 5;

    // Dibujo del texto
    imagettftext($im, 10, 45, $x, $y, $black, $font, 'and Zend Engine ' . zend_version());

    // Envío al navegador
    header('Content-Type: image/png');

    imagepng($im);
    ?>

### Notas

> Nota: Esta función solo está disponible si si PHP es compilado con soporte Freetype (--with-freetype-dir=DIR)

### Ver también

- imagettftext() - Dibuja un texto con una fuente TrueType
- imageftbbox() - Calcula el rectángulo de delimitación para un texto, utilizando la fuente actual y freetype2

# imagettftext

(PHP 4, PHP 5, PHP 7, PHP 8)

imagettftext — Dibuja un texto con una fuente TrueType

### Descripción

function imagettftext(
GdImage `$image`,
float `$size`,
float `$angle`,
int `$x`,
int `$y`,
int `$color`,
string `$font_filename`,
string `$text`,
array `$options` = []
): array|false

imagettftext() dibuja el texto `text` con la fuente TrueType `fontfile`.

> Nota:

> Antes de PHP 8.0.0, imagefttext() era una variante extendida de imagettftext() que además soporta `extrainfo`. A partir de PHP 8.0.0, imagefttext() es un alias de imagefttext().

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`size`

  El tamaño de la fuente en puntos.

`angle`

  El ángulo, en grados; 0 grados corresponde a la lectura del texto de izquierda a derecha. Los valores positivos representan una rotación en el sentido contrario a las agujas de un reloj. Por ejemplo, un valor de 90 corresponderá a una lectura del texto de abajo hacia arriba.

`x`

  Las coordenadas dadas por `x` y `y` definirán la posición del primer carácter (la esquina inferior izquierda del carácter). Esto es diferente de la función imagestring(), donde `x` y `y` definen la esquina superior izquierda del primer carácter. Por ejemplo, "superior izquierda" corresponde a 0, 0.

`y`

  La coordenada Y. Esto define la posición de la línea base de la fuente, y no el fondo de los caracteres.

`color`

  El índice del color. Utilizar un índice de color negativo desactivará el antialiasing. Ver la función imagecolorallocate().

`fontfile`

  La ruta de acceso al fichero de la fuente TrueType que desea utilizar.

  Dependiendo de qué versión de la biblioteca GD esté utilizando PHP, cuando `fontfile` no comienza con una barra diagonal inicial `/` entonces `.ttf` será añadido al nombre del fichero y la biblioteca intentará buscar ese nombre de fichero a lo largo de una ruta de acceso de fuentes definida por la biblioteca.

  Al utilizar versiones de la biblioteca GD inferiores a 2.0.18, un carácter `espacio`, en lugar de un punto y coma, se utilizaba como 'separador de rutas' para diferentes ficheros de fuentes. El uso no intencional de esta característica resultará en el mensaje de advertencia: `Advertencia: No se pudo encontrar/abrir la fuente`. Para estas versiones afectadas, la única solución es mover la fuente a una ruta que no contenga espacios.

  En muchos casos donde una fuente reside en el mismo directorio que el script que la utiliza, el siguiente truco aliviará cualquier problema de inclusión.

      <?php
      // Establecer la variable de entorno para GD
      putenv('GDFONTPATH=' . realpath('.'));
      // Nombre de la fuente a ser utilizada (note la falta de la extensión .ttf)
      $font = 'SomeFont';
      ?>

  > Nota:

  > Tenga en cuenta que open_basedir no aplica a `fontfile`.

`text`

  La cadena de texto, en UTF-8.

  Puede incluir referencias a caracteres numéricos, decimales (en la forma: `&#8364;`) para acceder a los caracteres de una fuente más allá del primer 127. El formato hexadecimal (como `&#xA9;`) es soportado. Las cadenas de caracteres codificadas en UTF-8 pueden ser pasadas directamente.

  Las entidades nombradas, como `&copy;`, no son soportadas. Utilice la función html_entity_decode() para codificar estas entidades nombradas en cadena UTF-8.

  Si un carácter es utilizado en una cadena que no es soportada por la fuente, un rectángulo hueco reemplazará el carácter.

`options`

  Un array con una clave `linespacing` que contiene un valor float.

### Valores devueltos

Devuelve un array de 8 elementos que representan cuatro puntos que marcan los límites del texto. El orden de los puntos es: inferior izquierdo, inferior derecho, superior derecho, superior izquierdo. Los puntos son relativos al texto con respecto al ángulo, por lo que, "superior izquierdo" significa en la esquina superior izquierda cuando se mira el texto horizontalmente. Devuelve `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | El parámetro `options` ha sido añadido.

### Ejemplos

Ejemplo #1 Ejemplo con imagettftext()

Este ejemplo producirá una imagen PNG blanca de 400x30 píxeles, con el texto `"Test..."` en negro, con una sombra gris, utilizando la fuente Arial.

    <?php

    // Definición del content-type
    header('Content-Type: image/png');

    // Creación de la imagen
    $im = imagecreatetruecolor(400, 30);

    // Creación de algunos colores
    $white = imagecolorallocate($im, 255, 255, 255);
    $grey = imagecolorallocate($im, 128, 128, 128);
    $black = imagecolorallocate($im, 0, 0, 0);
    imagefilledrectangle($im, 0, 0, 399, 29, $white);

    // El texto a dibujar
    $text = 'Test...';

    // Reemplazar la ruta por su propia ruta de fuente
    $font = 'arial.ttf';

    // Añadir sombras al texto
    imagettftext($im, 20, 0, 11, 21, $grey, $font, $text);

    // Añadir el texto
    imagettftext($im, 20, 0, 10, 20, $black, $font, $text);

    // Utilizar imagepng() dará un texto más claro,
    // comparado con el uso de la función imagejpeg()
    imagepng($im);

    ?>

Resultado del ejemplo anterior es similar a:

### Notas

> Nota: Esta función solo está disponible si si PHP es compilado con soporte Freetype (--with-freetype-dir=DIR)

### Ver también

- imagettfbbox() - Devuelve el rectángulo que rodea un texto dibujado con una fuente TrueType
- imagefttext() - Escribe texto en una imagen con la fuente actual FreeType 2
- imagestring() - Dibuja una cadena horizontal

# imagetypes

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

imagetypes — Devuelve los tipos de imágenes soportados por la versión actual de PHP

### Descripción

function imagetypes(): int

Devuelve un campo de octetos correspondiente a los formatos de imágenes soportados por la versión de PHP utilizada.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un campo de octetos correspondiente a los formatos de imágenes soportados por la versión de GD utilizada. Los valores siguientes son posibles: `IMG_AVIF` | `IMG_BMP` | `IMG_GIF` | `IMG_JPG` | `IMG_PNG` | `IMG_WBMP` | `IMG_XPM` | `IMG_WEBP`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Añadida la constante `IMG_AVIF`.
7.2.0 | Añadida la constante `IMG_BMP`.
7.0.10 | Añadida la constante `IMG_WEBP`.

### Ejemplos

Ejemplo #1 Ejemplo con imagetypes()

    <?php
    if (imagetypes() & IMG_PNG) {
        echo "El tipo PNG es soportado";
    }
    ?>

### Ver también

- gd_info() - Devuelve información sobre la biblioteca GD instalada

# imagewbmp

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagewbmp — Enviar la imagen al navegador o a un archivo

### Descripción

function imagewbmp(GdImage `$image`, resource|string|null `$file` = `null`, ?int `$foreground_color` = `null`): bool

imagewbmp() muestra o guarda una versión WBMP de la imagen `image`.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`file`

  La ruta o un recurso de flujo abierto (que se cierra automáticamente después de que esta función retorne) donde guardar el archivo. Si no se define o es `null`, el flujo de imagen sin procesar se enviará directamente.

`foreground_color`

  Puede seleccionarse el color de primer plano con este argumento. Utilice el identificador devuelto por imagecolorallocate() como valor de este argumento. El color de primer plano por omisión es negro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

Precaución

Sin embargo, si libgd no logra producir la imagen, esta función devuelve `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.
8.0.0 | `foreground_color` ahora es nullable.

### Ejemplos

Ejemplo #1 Mostrar una imagen WBMP

    <?php
    // Creación de una imagen vacía y adición de texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'Un texto simple', $text_color);

    // Define el contenido del encabezado - en este caso, image/vnd.wap.wbmp
    // Sugerencia: ver image_type_to_mime_type() para tipos de contenido
    header('Content-Type: image/vnd.wap.wbmp');

    // Mostrar la imagen
    imagewbmp($im);

    ?>

Ejemplo #2 Guardar la imagen WBMP

    <?php
    // Creación de una imagen vacía y adición de texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'Un texto simple', $text_color);

    // Guardar la imagen
    imagewbmp($im, 'simpletext.wbmp');

    ?>

Ejemplo #3 Mostrar la imagen con un primer plano diferente

    <?php
    // Creación de una imagen vacía y adición de texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'Un texto simple', $text_color);

    // Define el contenido del encabezado - en este caso, image/vnd.wap.wbmp
    // Sugerencia: ver la función image_type_to_mime_type() para tipos de contenido
    header('Content-type: image/vnd.wap.wbmp');

    // Define un primer plano
    $foreground_color = imagecolorallocate($im, 255, 0, 0);

    imagewbmp($im, NULL, $foreground_color);

    ?>

### Ver también

- image2wbmp() - Enviar la imagen al navegador o a un archivo
- imagepng() - Envía una imagen PNG a un navegador o a un fichero
- imagegif() - Enviar la imagen al navegador o a un archivo
- imagejpeg() - Enviar la imagen al navegador o a un archivo
- imagetypes() - Devuelve los tipos de imágenes soportados por la versión actual de PHP

# imagewebp

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

imagewebp — Muestra una imagen WebP hacia un navegador o un fichero

### Descripción

function imagewebp(GdImage `$image`, resource|string|null `$file` = `null`, int `$quality` = -1): bool

Muestra o guarda una versión WebP de la `image` proporcionada.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`file`

  La ruta o un recurso de flujo abierto (que se cierra automáticamente después de que esta función retorne) donde guardar el archivo. Si no se define o es `null`, el flujo de imagen sin procesar se enviará directamente.

`quality`

  `quality` rango de 0 (la peor calidad, fichero más pequeño) a 100 (mejor calidad, fichero más grande). Si se proporciona el valor `-1`, se utiliza el valor por omisión `80`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

Precaución

Sin embargo, si libgd no logra producir la imagen, esta función devuelve `true`.

### Errores/Excepciones

Genera una ValueError si `quality` es inválido.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Genera ahora una ValueError si `quality` es inválido.
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.

### Ejemplos

Ejemplo #1 Guardado de un fichero WebP

    <?php
    // Crea una imagen vacía y se añade texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);

    imagestring($im, 1, 5, 5,  'WebP con PHP', $text_color);

    // Guardado de la imagen
    imagewebp($im, 'php.webp');

    ?>

# imagexbm

(PHP 5, PHP 7, PHP 8)

imagexbm — Genera una imagen en formato XBM

### Descripción

function imagexbm(GdImage `$image`, ?string `$filename`, ?int `$foreground_color` = `null`): bool

Muestra o guarda una versión XBM de la imagen `image`.

> Nota: imagexbm() no aplica relleno, por lo que el ancho de la imagen debe ser un múltiplo de 8. Esta restricción ya no se aplica a partir de PHP 7.0.9, respectivamente.

### Parámetros

`image`
  Un objeto GdImage, retornado por una de las funciones de creación de imágenes, como imagecreatetruecolor().
`filename`

  Ruta de acceso donde se guardará el fichero, en forma de string. Si no está definido, el flujo de imágenes RAW se mostrará directamente en la salida estándar.

  El nombre de fichero `filename` (sin la extensión .xbm) también se utiliza para los identificadores C del XBM, en cuyo caso los caracteres no alfanuméricos de la configuración local actual son reemplazados por subrayados. Si `filename` tiene el valor null, `image` se utiliza para generar los identificadores C.

`foreground_color`

  Puede definirse el primer plano con este parámetro definiendo un identificador obtenido desde la función imagecolorallocate(). Por omisión, el color del primer plano es negro. Todas las demás colores se tratan como fondo.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

Precaución

Sin embargo, si libgd no logra producir la imagen, esta función devuelve `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `image` ahora espera una instancia de GdImage; anteriormente, se esperaba un resource `gd` válido.
8.0.0 | `foreground_color` ahora es nullable.
8.0.0 | El cuarto parámetro, que no se utilizaba, ha sido eliminado.

### Ejemplos

Ejemplo #1 Guardar un fichero XBM

    <?php
    // Creación de una imagen vacía y adición de texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'Un texto simple', $text_color);

    // Guardar la imagen
    imagexbm($im, 'simpletext.xbm');

    ?>

Ejemplo #2 Guardar un fichero XBM con un color de primer plano diferente

    <?php
    // Creación de una imagen vacía y adición de texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'Un texto simple', $text_color);

    // Definir el color de primer plano
    $foreground_color = imagecolorallocate($im, 255, 0, 0);

    // Guardar la imagen
    imagexbm($im, NULL, $foreground_color);

    ?>

# iptcembed

(PHP 4, PHP 5, PHP 7, PHP 8)

iptcembed — Incorpora datos binarios IPTC en una imagen JPEG

### Descripción

function iptcembed(string `$iptc_data`, string `$filename`, int `$spool` = 0): string|bool

iptcembed() incorpora datos binarios IPTC en una imagen JPEG.

### Parámetros

`iptc_data`

  Los datos a escribir.

`filename`

  Ruta hacia el fichero JPEG.

`spool`

  El flag de la bobina. Si la bobina es inferior a 2, entonces el fichero JPEG será devuelto en forma de string. De lo contrario el fichero JPEG será enviado a STDOUT.

### Valores devueltos

Si `spool` es inferior a 2, el fichero JPEG será devuelto, o `false` si ocurre un error. De lo contrario devuelve `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con iptcembed()

    <?php

    // Función iptc_make_tag() por Thies C. Arntzen
    function iptc_make_tag($rec, $data, $value)
    {
        $length = strlen($value);
        $retval = chr(0x1C) . chr($rec) . chr($data);

        if($length < 0x8000)
        {
            $retval .= chr($length >> 8) .  chr($length & 0xFF);
        }
        else
        {
            $retval .= chr(0x80) .
                       chr(0x04) .
                       chr(($length >> 24) & 0xFF) .
                       chr(($length >> 16) & 0xFF) .
                       chr(($length >> 8) & 0xFF) .
                       chr($length & 0xFF);
        }

        return $retval . $value;
    }

    // Ruta hacia el fichero JPEG
    $path = './phplogo.jpg';

    // Define las etiquetas IPTC
    $iptc = array(
        '2#120' => 'Test image',
        '2#116' => 'Copyright 2008-2009, The PHP Group'
    );

    // Conversión de las etiquetas IPTC a código binario
    $data = '';

    foreach($iptc as $tag => $string)
    {
        $tag = substr($tag, 2);
        $data .= iptc_make_tag(2, $tag, $string);
    }

    // Incorporación de los datos IPTC
    $content = iptcembed($data, $path);

    // Escribe los datos de la nueva imagen en un fichero.
    $fp = fopen($path, "wb");
    fwrite($fp, $content);
    fclose($fp);
    ?>

### Notas

> Nota: Esta función no requiere la biblioteca GD.

# iptcparse

(PHP 4, PHP 5, PHP 7, PHP 8)

iptcparse — Analiza un bloque binario IPTC y busca las etiquetas simples

### Descripción

function iptcparse(string `$iptc_block`): array|false

Analiza un bloque binario » IPTC y busca las etiquetas simples.

### Parámetros

`iptc_block`

  Un bloque binario IPTC.

### Valores devueltos

Retorna un array con las etiquetas como índices y los valores de estas etiquetas IPTC en los valores del array correspondientes. En caso de error, o si ninguna etiqueta IPTC ha sido encontrada, esta función retorna `false`.

### Ejemplos

Ejemplo #1 Ejemplo con iptcparse() y getimagesize()

    <?php
    $size = getimagesize('./test.jpg', $info);
    if(isset($info['APP13']))
    {
        $iptc = iptcparse($info['APP13']);
        var_dump($iptc);
    }
    ?>

### Notas

> Nota: Esta función no requiere la biblioteca GD.

# jpeg2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

jpeg2wbmp — Convierte una imagen JPEG en imagen WBMP

Advertencia

Esta funcionalidad está OBSOLETA a partir de PHP 7.2.0 y ha sido ELIMINADA a partir de PHP 8.0.0.

### Descripción

function jpeg2wbmp(
string `$jpegname`,
string `$wbmpname`,
int `$dest_height`,
int `$dest_width`,
int `$threshold`
): bool

Convierte una imagen JPEG en imagen WBMP.

### Parámetros

`jpegname`

  Ruta hacia el fichero JPEG.

`wbmpname`

  Ruta hacia el fichero final WBMP.

`dest_height`

  Altura de la imagen de destino.

`dest_width`

  Ancho de la imagen de destino.

`threshold`

  Valor del umbral, entre 0 y 8 inclusive.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

Precaución

Sin embargo, si libgd no logra producir la imagen, esta función devuelve `true`.

### Ejemplos

Ejemplo #1 Ejemplo con jpeg2wbmp()

    <?php
    // Ruta hacia el objetivo jpeg
    $path = './test.jpg';

    // Obtención del tamaño de la imagen
    $image = getimagesize($path);

    // Conversión de la imagen
    jpeg2wbmp($path, './test.wbmp', $image[1], $image[0], 5);
    ?>

### Ver también

- png2wbmp() - Convierte una imagen PNG en imagen WBMP

# png2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

png2wbmp — Convierte una imagen PNG en imagen WBMP

Advertencia

Esta funcionalidad está OBSOLETA a partir de PHP 7.2.0 y ha sido ELIMINADA a partir de PHP 8.0.0.

### Descripción

function png2wbmp(
string `$pngname`,
string `$wbmpname`,
int `$dest_height`,
int `$dest_width`,
int `$threshold`
): bool

Convierte una imagen PNG en imagen WBMP.

### Parámetros

`pngname`

  Ruta al fichero PNG.

`wbmpname`

  Ruta al fichero final WBMP.

`dest_height`

  Altura de la imagen de destino.

`dest_width`

  Ancho de la imagen de destino.

`threshold`

  Valor del umbral, entre 0 y 8 inclusive.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

Precaución

Sin embargo, si libgd no logra producir la imagen, esta función devuelve `true`.

### Ejemplos

Ejemplo #1 Ejemplo con png2wbmp()

    <?php
    // Ruta a la imagen PNG
    $path = './test.png';

    // Obtención del tamaño de la imagen
    $image = getimagesize($path);

    // Conversión de la imagen
    png2wbmp($path, './test.wbmp', $image[1], $image[0], 7);
    ?>

### Ver también

- jpeg2wbmp() - Convierte una imagen JPEG en imagen WBMP

## Tabla de contenidos

- gd_info — Devuelve información sobre la biblioteca GD instalada
- getimagesize — Devuelve el tamaño de una imagen
- getimagesizefromstring — Obtiene el tamaño de una imagen desde una cadena
- image_type_to_extension — Devuelve la extensión del fichero para el tipo de imagen
- image_type_to_mime_type — Obtiene el tipo MIME para el tipo de imagen devuelto por getimagesize, exif_read_data, exif_thumbnail, exif_imagetype
- image2wbmp — Enviar la imagen al navegador o a un archivo
- imageaffine — Devuelve una imagen que contiene la imagen fuente transformada, utilizando opcionalmente una zona de recorte
- imageaffinematrixconcat — Concatena dos matrices de transformación afín
- imageaffinematrixget — Obtener una matriz de transformación afín
- imagealphablending — Modifica el modo de mezcla de una imagen
- imageantialias — Activar o desactivar las funciones de antialias
- imagearc — Dibuja una elipse parcial
- imageavif — Enviar la imagen al navegador o a un archivo
- imagebmp — Muestra o guarda una imagen BMP en el navegador o en un fichero
- imagechar — Dibuja un carácter horizontalmente
- imagecharup — Dibuja un carácter verticalmente
- imagecolorallocate — Asigna una coloración para una imagen
- imagecolorallocatealpha — Asigna un color a una imagen
- imagecolorat — Devuelve el índice del color de un píxel dado
- imagecolorclosest — Devuelve el índice de la color más cercana a una color dada
- imagecolorclosestalpha — Devuelve el color más cercano, teniendo en cuenta el canal alpha
- imagecolorclosesthwb — Obtiene el índice de la color especificada con su tono, blanco y negro
- imagecolordeallocate — Elimina un color de una imagen
- imagecolorexact — Devuelve el índice del color especificado
- imagecolorexactalpha — Devuelve el índice de un color con su canal alfa
- imagecolormatch — Hace que las colores de la versión palette de una imagen coincidan más con las de su versión truecolor
- imagecolorresolve — Devuelve el índice de la color dada, o la más cercana posible
- imagecolorresolvealpha — Devuelve un índice de color o su alternativa más cercana, incluyendo el canal alpha
- imagecolorset — Cambia el color en una paleta en el índice dado
- imagecolorsforindex — Retorna el color asociado a un índice
- imagecolorstotal — Calcula el número de colores de una paleta
- imagecolortransparent — Define la color transparente
- imageconvolution — Aplica una matriz de convolución 3x3, utilizando el coeficiente y el desplazamiento
- imagecopy — Copia una parte de una imagen
- imagecopymerge — Copia y fusiona una parte de una imagen
- imagecopymergegray — Copia y fusiona una parte de una imagen en niveles de gris
- imagecopyresampled — Copia, redimensiona y reinterpolación de una imagen
- imagecopyresized — Copia y redimensiona una parte de una imagen
- imagecreate — Crea una nueva imagen con paleta
- imagecreatefromavif — Crear una nueva imagen a partir de un archivo o una URL
- imagecreatefrombmp — Crear una nueva imagen a partir de un archivo o una URL
- imagecreatefromgd — Crea una nueva imagen a partir de un fichero GD o de una URL
- imagecreatefromgd2 — Crea una nueva imagen a partir de un fichero GD2 o de una URL
- imagecreatefromgd2part — Crea una nueva imagen a partir de una parte de un archivo GD2 o de una URL
- imagecreatefromgif — Crear una nueva imagen a partir de un archivo o una URL
- imagecreatefromjpeg — Crear una nueva imagen a partir de un archivo o una URL
- imagecreatefrompng — Crear una nueva imagen a partir de un archivo o una URL
- imagecreatefromstring — Crea una imagen a partir de una cadena
- imagecreatefromtga — Crear una nueva imagen a partir de un archivo o una URL
- imagecreatefromwbmp — Crear una nueva imagen a partir de un archivo o una URL
- imagecreatefromwebp — Crear una nueva imagen a partir de un archivo o una URL
- imagecreatefromxbm — Crear una nueva imagen a partir de un archivo o una URL
- imagecreatefromxpm — Crear una nueva imagen a partir de un archivo o una URL
- imagecreatetruecolor — Crea una nueva imagen en colores verdaderos
- imagecrop — Recorta una imagen en el rectángulo dado
- imagecropauto — Recorta una imagen automáticamente utilizando uno de los modos disponibles
- imagedashedline — Dibuja una línea punteada
- imagedestroy — Destruye una imagen
- imageellipse — Dibuja una elipse
- imagefill — Relleno
- imagefilledarc — Dibuja un arco parcial y lo rellena
- imagefilledellipse — Dibuja una elipse llena
- imagefilledpolygon — Dibuja un polígono relleno
- imagefilledrectangle — Dibuja un rectángulo relleno
- imagefilltoborder — Rellena una región con un color específico
- imagefilter — Aplica un filtro a una imagen
- imageflip — Devuelve una imagen utilizando el modo proporcionado
- imagefontheight — Devuelve la altura de la fuente
- imagefontwidth — Devuelve el ancho de la fuente
- imageftbbox — Calcula el rectángulo de delimitación para un texto, utilizando la fuente actual y freetype2
- imagefttext — Escribe texto en una imagen con la fuente actual FreeType 2
- imagegammacorrect — Aplica una corrección gamma a la imagen GD
- imagegd — Genera una imagen en formato GD, hacia el navegador o un fichero
- imagegd2 — Genera una imagen en formato GD2, hacia el navegador o un fichero
- imagegetclip — Obtiene el rectángulo de recorte
- imagegetinterpolation — Obtiene el método de interpolación
- imagegif — Enviar la imagen al navegador o a un archivo
- imagegrabscreen — Captura la pantalla completa
- imagegrabwindow — Captura una ventana
- imageinterlace — Activa o desactiva el entrelazado
- imageistruecolor — Determina si una imagen es una imagen truecolor
- imagejpeg — Enviar la imagen al navegador o a un archivo
- imagelayereffect — Activa la opción de mezcla alfa para utilizar los efectos de libgd
- imageline — Dibuja una línea
- imageloadfont — Carga una nueva fuente
- imageopenpolygon — Dibuja un polígono abierto
- imagepalettecopy — Copia la paleta de una imagen a otra
- imagepalettetotruecolor — Convierte una imagen basada en una paleta a color verdadero
- imagepng — Envía una imagen PNG a un navegador o a un fichero
- imagepolygon — Dibuja un polígono
- imagerectangle — Dibuja un rectángulo
- imageresolution — Recupera o define la resolución de la imagen
- imagerotate — Rota una imagen en un ángulo
- imagesavealpha — Determina si la información completa del canal alpha debe conservarse al guardar imágenes
- imagescale — Redimensiona una imagen utilizando una altura y una anchura proporcionadas
- imagesetbrush — Modifica el pincel para el dibujo de líneas
- imagesetclip — Establece el rectángulo de recorte
- imagesetinterpolation — Define el método de interpolación
- imagesetpixel — Dibuja un píxel
- imagesetstyle — Configura el estilo para el dibujo de líneas
- imagesetthickness — Modifica el grosor de una línea
- imagesettile — Modifica la imagen utilizada para el mosaico
- imagestring — Dibuja una cadena horizontal
- imagestringup — Dibuja una cadena vertical
- imagesx — Devuelve el ancho de una imagen
- imagesy — Devuelve la altura de la imagen
- imagetruecolortopalette — Convierte una imagen en colores verdaderos a imagen con paleta
- imagettfbbox — Devuelve el rectángulo que rodea un texto dibujado con una fuente TrueType
- imagettftext — Dibuja un texto con una fuente TrueType
- imagetypes — Devuelve los tipos de imágenes soportados por la versión actual de PHP
- imagewbmp — Enviar la imagen al navegador o a un archivo
- imagewebp — Muestra una imagen WebP hacia un navegador o un fichero
- imagexbm — Genera una imagen en formato XBM
- iptcembed — Incorpora datos binarios IPTC en una imagen JPEG
- iptcparse — Analiza un bloque binario IPTC y busca las etiquetas simples
- jpeg2wbmp — Convierte una imagen JPEG en imagen WBMP
- png2wbmp — Convierte una imagen PNG en imagen WBMP

# La clase GdImage

(PHP 8)

## Introducción

Una clase totalmente opaca que reemplaza los recursos `gd` a partir de PHP 8.0.0.

## Sinopsis de la Clase

final class GdImage {
}

# La clase GdFont

(PHP 8 >= 8.1.0)

## Introducción

Una clase completamente opaca que reemplaza el resource `gd font` a partir de PHP 8.1.0.

## Sinopsis de la Clase

final class GdFont {
}

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
  - Tipos de recursos
- Constantes predefinidas
- Ejemplos
  - Creación de una imagen PNG con PHP
  - Añadir un sello digital a imágenes utilizando un canal Alpha
  - Ejemplo con imagecopymerge para crear un sello digital translúcido
- Funciones de GD e Imágenes
  - gd_info — Devuelve información sobre la biblioteca GD instalada
  - getimagesize — Devuelve el tamaño de una imagen
  - getimagesizefromstring — Obtiene el tamaño de una imagen desde una cadena
  - image_type_to_extension — Devuelve la extensión del fichero para el tipo de imagen
  - image_type_to_mime_type — Obtiene el tipo MIME para el tipo de imagen devuelto por getimagesize, exif_read_data, exif_thumbnail, exif_imagetype
  - image2wbmp — Enviar la imagen al navegador o a un archivo
  - imageaffine — Devuelve una imagen que contiene la imagen fuente transformada, utilizando opcionalmente una zona de recorte
  - imageaffinematrixconcat — Concatena dos matrices de transformación afín
  - imageaffinematrixget — Obtener una matriz de transformación afín
  - imagealphablending — Modifica el modo de mezcla de una imagen
  - imageantialias — Activar o desactivar las funciones de antialias
  - imagearc — Dibuja una elipse parcial
  - imageavif — Enviar la imagen al navegador o a un archivo
  - imagebmp — Muestra o guarda una imagen BMP en el navegador o en un fichero
  - imagechar — Dibuja un carácter horizontalmente
  - imagecharup — Dibuja un carácter verticalmente
  - imagecolorallocate — Asigna una coloración para una imagen
  - imagecolorallocatealpha — Asigna un color a una imagen
  - imagecolorat — Devuelve el índice del color de un píxel dado
  - imagecolorclosest — Devuelve el índice de la color más cercana a una color dada
  - imagecolorclosestalpha — Devuelve el color más cercano, teniendo en cuenta el canal alpha
  - imagecolorclosesthwb — Obtiene el índice de la color especificada con su tono, blanco y negro
  - imagecolordeallocate — Elimina un color de una imagen
  - imagecolorexact — Devuelve el índice del color especificado
  - imagecolorexactalpha — Devuelve el índice de un color con su canal alfa
  - imagecolormatch — Hace que las colores de la versión palette de una imagen coincidan más con las de su versión truecolor
  - imagecolorresolve — Devuelve el índice de la color dada, o la más cercana posible
  - imagecolorresolvealpha — Devuelve un índice de color o su alternativa más cercana, incluyendo el canal alpha
  - imagecolorset — Cambia el color en una paleta en el índice dado
  - imagecolorsforindex — Retorna el color asociado a un índice
  - imagecolorstotal — Calcula el número de colores de una paleta
  - imagecolortransparent — Define la color transparente
  - imageconvolution — Aplica una matriz de convolución 3x3, utilizando el coeficiente y el desplazamiento
  - imagecopy — Copia una parte de una imagen
  - imagecopymerge — Copia y fusiona una parte de una imagen
  - imagecopymergegray — Copia y fusiona una parte de una imagen en niveles de gris
  - imagecopyresampled — Copia, redimensiona y reinterpolación de una imagen
  - imagecopyresized — Copia y redimensiona una parte de una imagen
  - imagecreate — Crea una nueva imagen con paleta
  - imagecreatefromavif — Crear una nueva imagen a partir de un archivo o una URL
  - imagecreatefrombmp — Crear una nueva imagen a partir de un archivo o una URL
  - imagecreatefromgd — Crea una nueva imagen a partir de un fichero GD o de una URL
  - imagecreatefromgd2 — Crea una nueva imagen a partir de un fichero GD2 o de una URL
  - imagecreatefromgd2part — Crea una nueva imagen a partir de una parte de un archivo GD2 o de una URL
  - imagecreatefromgif — Crear una nueva imagen a partir de un archivo o una URL
  - imagecreatefromjpeg — Crear una nueva imagen a partir de un archivo o una URL
  - imagecreatefrompng — Crear una nueva imagen a partir de un archivo o una URL
  - imagecreatefromstring — Crea una imagen a partir de una cadena
  - imagecreatefromtga — Crear una nueva imagen a partir de un archivo o una URL
  - imagecreatefromwbmp — Crear una nueva imagen a partir de un archivo o una URL
  - imagecreatefromwebp — Crear una nueva imagen a partir de un archivo o una URL
  - imagecreatefromxbm — Crear una nueva imagen a partir de un archivo o una URL
  - imagecreatefromxpm — Crear una nueva imagen a partir de un archivo o una URL
  - imagecreatetruecolor — Crea una nueva imagen en colores verdaderos
  - imagecrop — Recorta una imagen en el rectángulo dado
  - imagecropauto — Recorta una imagen automáticamente utilizando uno de los modos disponibles
  - imagedashedline — Dibuja una línea punteada
  - imagedestroy — Destruye una imagen
  - imageellipse — Dibuja una elipse
  - imagefill — Relleno
  - imagefilledarc — Dibuja un arco parcial y lo rellena
  - imagefilledellipse — Dibuja una elipse llena
  - imagefilledpolygon — Dibuja un polígono relleno
  - imagefilledrectangle — Dibuja un rectángulo relleno
  - imagefilltoborder — Rellena una región con un color específico
  - imagefilter — Aplica un filtro a una imagen
  - imageflip — Devuelve una imagen utilizando el modo proporcionado
  - imagefontheight — Devuelve la altura de la fuente
  - imagefontwidth — Devuelve el ancho de la fuente
  - imageftbbox — Calcula el rectángulo de delimitación para un texto, utilizando la fuente actual y freetype2
  - imagefttext — Escribe texto en una imagen con la fuente actual FreeType 2
  - imagegammacorrect — Aplica una corrección gamma a la imagen GD
  - imagegd — Genera una imagen en formato GD, hacia el navegador o un fichero
  - imagegd2 — Genera una imagen en formato GD2, hacia el navegador o un fichero
  - imagegetclip — Obtiene el rectángulo de recorte
  - imagegetinterpolation — Obtiene el método de interpolación
  - imagegif — Enviar la imagen al navegador o a un archivo
  - imagegrabscreen — Captura la pantalla completa
  - imagegrabwindow — Captura una ventana
  - imageinterlace — Activa o desactiva el entrelazado
  - imageistruecolor — Determina si una imagen es una imagen truecolor
  - imagejpeg — Enviar la imagen al navegador o a un archivo
  - imagelayereffect — Activa la opción de mezcla alfa para utilizar los efectos de libgd
  - imageline — Dibuja una línea
  - imageloadfont — Carga una nueva fuente
  - imageopenpolygon — Dibuja un polígono abierto
  - imagepalettecopy — Copia la paleta de una imagen a otra
  - imagepalettetotruecolor — Convierte una imagen basada en una paleta a color verdadero
  - imagepng — Envía una imagen PNG a un navegador o a un fichero
  - imagepolygon — Dibuja un polígono
  - imagerectangle — Dibuja un rectángulo
  - imageresolution — Recupera o define la resolución de la imagen
  - imagerotate — Rota una imagen en un ángulo
  - imagesavealpha — Determina si la información completa del canal alpha debe conservarse al guardar imágenes
  - imagescale — Redimensiona una imagen utilizando una altura y una anchura proporcionadas
  - imagesetbrush — Modifica el pincel para el dibujo de líneas
  - imagesetclip — Establece el rectángulo de recorte
  - imagesetinterpolation — Define el método de interpolación
  - imagesetpixel — Dibuja un píxel
  - imagesetstyle — Configura el estilo para el dibujo de líneas
  - imagesetthickness — Modifica el grosor de una línea
  - imagesettile — Modifica la imagen utilizada para el mosaico
  - imagestring — Dibuja una cadena horizontal
  - imagestringup — Dibuja una cadena vertical
  - imagesx — Devuelve el ancho de una imagen
  - imagesy — Devuelve la altura de la imagen
  - imagetruecolortopalette — Convierte una imagen en colores verdaderos a imagen con paleta
  - imagettfbbox — Devuelve el rectángulo que rodea un texto dibujado con una fuente TrueType
  - imagettftext — Dibuja un texto con una fuente TrueType
  - imagetypes — Devuelve los tipos de imágenes soportados por la versión actual de PHP
  - imagewbmp — Enviar la imagen al navegador o a un archivo
  - imagewebp — Muestra una imagen WebP hacia un navegador o un fichero
  - imagexbm — Genera una imagen en formato XBM
  - iptcembed — Incorpora datos binarios IPTC en una imagen JPEG
  - iptcparse — Analiza un bloque binario IPTC y busca las etiquetas simples
  - jpeg2wbmp — Convierte una imagen JPEG en imagen WBMP
  - png2wbmp — Convierte una imagen PNG en imagen WBMP
- GdImage — La clase GdImage
- GdFont — La clase GdFont

# Gmagick

# Introducción

Advertencia

Esta extensión es EXPERIMENTAL. El comportamiento de esta extensión, los nombres de sus funciones, y toda la documentación alrededor de esta extensión puede cambiar sin previo aviso en una próxima versión de PHP. Esta extensión debe ser utilizada bajo su propio riesgo.

Gmagick es una extensión PHP para crear, modificar y obtener información méta sobre imágenes utilizando la API GraphicsMagick.

GraphicsMagick se enorgullece de ser el cuchillo suizo del tratamiento de imágenes. Funciona con aproximadamente 88 formatos principales, incluyendo formatos importantes como DPX, GIF, JPEG, JPEG-2000, PNG, PDF, PNM y TIFF.

Gmagick se compone de una clase principal Gmagick, una clase GmagickDraw que se encarga del dibujo y una clase GmagickPixel cuyas instancias representan un solo píxel de una imagen (color, opacidad).

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación

## Requerimientos

Esta extensión funciona perfectamente con GraphicsMagick versión 1.4+. Gmagick debería funcionar con versiones anteriores, desde la versión 1.2.6 de GraphicsMagick 1.2.6, pero algunas funcionalidades y formatos no están soportados. La versión Windows de GraphicsMagick está disponible desde el sitio web de GraphicsMagick. Para conocer las diferencias entre ImageMagick y GraphicsMagick, leer la : » FAQ .

## Instalación

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/gmagick.

> Nota: El nombre oficial de esta extensión es gmagick.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

Constantes relativas a los tipos de color
`Gmagick::COLOR_BLACK` (int)
  Negro
`Gmagick::COLOR_BLUE` (int)
  Azul
`Gmagick::COLOR_CYAN` (int)
  Cian
`Gmagick::COLOR_GREEN` (int)
  Verde
`Gmagick::COLOR_RED` (int)
  Rojo
`Gmagick::COLOR_YELLOW` (int)
  Amarillo
`Gmagick::COLOR_MAGENTA` (int)
  Magenta
`Gmagick::COLOR_OPACITY` (int)
  Opacidad
`Gmagick::COLOR_ALPHA` (int)
  Alpha
`Gmagick::COLOR_FUZZ` (int)
  Fuzz

Constantes relativas a los operadores compuestos
`Gmagick::COMPOSITE_DEFAULT` (int)
  El operador compuesto por defecto
`Gmagick::COMPOSITE_UNDEFINED` (int)
  Operador compuesto indefinido
`Gmagick::COMPOSITE_NO` (int)
  Ningún operador compuesto definido
`Gmagick::COMPOSITE_ADD` (int)
  El resultado de una imagen + una imagen
`Gmagick::COMPOSITE_ATOP` (int)
  El resultado es la misma forma que una imagen; donde la imagen compuesta oscurece la imagen, la imagen de la forma la superpone.
`Gmagick::COMPOSITE_BLEND` (int)
  Mezcla la imagen
`Gmagick::COMPOSITE_BUMPMAP` (int)
  Idéntico a COMPOSITE_MULTIPLY, excepto que la fuente se convierte primero a niveles de gris.
`Gmagick::COMPOSITE_CLEAR` (int)
  Hace que la imagen de destino sea transparente
`Gmagick::COMPOSITE_COLORBURN` (int)
  Oscurece la imagen de destino para reflejar la imagen fuente
`Gmagick::COMPOSITE_COLORDODGE` (int)
  Aclara la imagen de destino para reflejar la imagen fuente
`Gmagick::COMPOSITE_COLORIZE` (int)
  Colorea la imagen de destino utilizando la imagen compuesta
`Gmagick::COMPOSITE_COPYBLACK` (int)
  Copia los negros desde la fuente hacia la imagen de destino
`Gmagick::COMPOSITE_COPYBLUE` (int)
  Copia los azules desde la fuente hacia la imagen de destino
`Gmagick::COMPOSITE_COPY` (int)
  Copia la imagen fuente sobre la imagen de destino
`Gmagick::COMPOSITE_COPYCYAN` (int)
  Copia el cian desde la fuente hacia la imagen de destino
`Gmagick::COMPOSITE_COPYGREEN` (int)
  Copia el verde desde la fuente hacia la imagen de destino
`Gmagick::COMPOSITE_COPYMAGENTA` (int)
  Copia el magenta desde la fuente hacia la imagen de destino
`Gmagick::COMPOSITE_COPYOPACITY` (int)
  Copia la opacidad desde la fuente hacia la imagen de destino
`Gmagick::COMPOSITE_COPYRED` (int)
  Copia el rojo desde la fuente hacia la imagen de destino
`Gmagick::COMPOSITE_COPYYELLOW` (int)
  Copia el amarillo desde la fuente hacia la imagen de destino
`Gmagick::COMPOSITE_DARKEN` (int)
  Oscurece la imagen de destino
`Gmagick::COMPOSITE_DSTATOP` (int)
  La parte de la imagen de destino que está dentro de la fuente se compone sobre la fuente y reemplaza la imagen de destino
`Gmagick::COMPOSITE_DST` (int)
  La imagen de destino se conserva sin modificación
`Gmagick::COMPOSITE_DSTIN` (int)
  La parte de la fuente reemplaza la imagen de destino
`Gmagick::COMPOSITE_DSTOUT` (int)
  La parte fuera de la fuente reemplaza la imagen de destino
`Gmagick::COMPOSITE_DSTOVER` (int)
  La imagen de destino reemplaza la fuente
`Gmagick::COMPOSITE_DIFFERENCE` (int)
  Resta el color más oscuro de los dos colores elementales del más claro
`Gmagick::COMPOSITE_DISPLACE` (int)
  Desplaza los píxeles de la imagen de destino según lo definido por la fuente
`Gmagick::COMPOSITE_DISSOLVE` (int)
  Disuelve la fuente en la imagen de destino
`Gmagick::COMPOSITE_EXCLUSION` (int)
  Produce un efecto similar a Gmagick::COMPOSITE_DIFFERENCE, pero aparece con un contraste más bajo
`Gmagick::COMPOSITE_HARDLIGHT` (int)
  Multiplica o superpone los colores, dependiendo del valor de color de la fuente
`Gmagick::COMPOSITE_HUE` (int)
  Modifica el tono de la imagen de destino según lo definido por la fuente
`Gmagick::COMPOSITE_IN` (int)
  Realiza una composición de la fuente en la imagen de destino
`Gmagick::COMPOSITE_LIGHTEN` (int)
  Aclara la imagen de destino según lo definido por la fuente
`Gmagick::COMPOSITE_LUMINIZE` (int)
  Ilumina la imagen de destino según lo definido por la fuente
`Gmagick::COMPOSITE_MINUS` (int)
  Resta la fuente de la imagen de destino
`Gmagick::COMPOSITE_MODULATE` (int)
  Modula la luminosidad, saturación y tono de la imagen de destino según lo definido por la fuente
`Gmagick::COMPOSITE_MULTIPLY` (int)
  Multiplica la imagen de destino por la fuente
`Gmagick::COMPOSITE_OUT` (int)
  Realiza una composición de las partes exteriores de la fuente sobre la imagen de destino
`Gmagick::COMPOSITE_OVER` (int)
  Realiza una composición sobre la imagen de destino
`Gmagick::COMPOSITE_OVERLAY` (int)
  Superpone la fuente sobre la imagen de destino
`Gmagick::COMPOSITE_PLUS` (int)
  Añade la fuente a la imagen de destino
`Gmagick::COMPOSITE_REPLACE` (int)
  Reemplaza la imagen de destino por la fuente
`Gmagick::COMPOSITE_SATURATE` (int)
  Satura la imagen de destino según lo definido por la fuente
`Gmagick::COMPOSITE_SCREEN` (int)
  La fuente y la imagen de destino son complementadas, luego multiplicadas, luego reemplazan la imagen de destino
`Gmagick::COMPOSITE_SOFTLIGHT` (int)
  Oscurece o aclara los colores, siguiendo la fuente
`Gmagick::COMPOSITE_SRCATOP` (int)
  La parte de la fuente que se encuentra dentro de la imagen de destino se compone sobre la imagen de destino
`Gmagick::COMPOSITE_SRC` (int)
  La fuente se copia hacia la imagen de destino
`Gmagick::COMPOSITE_SRCIN` (int)
  La parte de la fuente que se encuentra dentro de la imagen de destino reemplaza la imagen de destino
`Gmagick::COMPOSITE_SRCOUT` (int)
  La parte de la fuente que se encuentra fuera de la imagen de destino reemplaza la imagen de destino
`Gmagick::COMPOSITE_SRCOVER` (int)
  La fuente reemplaza la imagen de destino
`Gmagick::COMPOSITE_SUBTRACT` (int)
  Resta los colores de la imagen fuente en la imagen de destino
`Gmagick::COMPOSITE_THRESHOLD` (int)
  La fuente se compone de la imagen de destino, según lo definido por la fuente
`Gmagick::COMPOSITE_XOR` (int)
  La parte de la fuente que se encuentra fuera de la imagen de destino se combina con la parte de la imagen de destino que se encuentra fuera de la fuente

Constantes de modo de montaje
`Gmagick::MONTAGEMODE_FRAME` (int)
`Gmagick::MONTAGEMODE_UNFRAME` (int)
`Gmagick::MONTAGEMODE_CONCATENATE` (int)

Constantes de estilo
`Gmagick::STYLE_NORMAL` (int)
`Gmagick::STYLE_ITALIC` (int)
`Gmagick::STYLE_OBLIQUE` (int)
`Gmagick::STYLE_ANY` (int)

Constantes de filtro
`Gmagick::FILTER_UNDEFINED` (int)
`Gmagick::FILTER_POINT` (int)
`Gmagick::FILTER_BOX` (int)
`Gmagick::FILTER_TRIANGLE` (int)
`Gmagick::FILTER_HERMITE` (int)
`Gmagick::FILTER_HANNING` (int)
`Gmagick::FILTER_HAMMING` (int)
`Gmagick::FILTER_BLACKMAN` (int)
`Gmagick::FILTER_GAUSSIAN` (int)
`Gmagick::FILTER_QUADRATIC` (int)
`Gmagick::FILTER_CUBIC` (int)
`Gmagick::FILTER_CATROM` (int)
`Gmagick::FILTER_MITCHELL` (int)
`Gmagick::FILTER_LANCZOS` (int)
`Gmagick::FILTER_BESSEL` (int)
`Gmagick::FILTER_SINC` (int)

Constantes de tipo de imagen
`Gmagick::IMGTYPE_UNDEFINED` (int)
`Gmagick::IMGTYPE_BILEVEL` (int)
`Gmagick::IMGTYPE_GRAYSCALE` (int)
`Gmagick::IMGTYPE_GRAYSCALEMATTE` (int)
`Gmagick::IMGTYPE_PALETTE` (int)
`Gmagick::IMGTYPE_PALETTEMATTE` (int)
`Gmagick::IMGTYPE_TRUECOLOR` (int)
`Gmagick::IMGTYPE_TRUECOLORMATTE` (int)
`Gmagick::IMGTYPE_COLORSEPARATION` (int)
`Gmagick::IMGTYPE_COLORSEPARATIONMATTE` (int)
`Gmagick::IMGTYPE_OPTIMIZE` (int)

Constantes de resolución
`Gmagick::RESOLUTION_UNDEFINED` (int)
`Gmagick::RESOLUTION_PIXELSPERINCH` (int)
`Gmagick::RESOLUTION_PIXELSPERCENTIMETER` (int)

Constantes de compresión
`Gmagick::COMPRESSION_UNDEFINED` (int)
`Gmagick::COMPRESSION_NO` (int)
`Gmagick::COMPRESSION_BZIP` (int)
`Gmagick::COMPRESSION_FAX` (int)
`Gmagick::COMPRESSION_GROUP4` (int)
`Gmagick::COMPRESSION_JPEG` (int)
`Gmagick::COMPRESSION_JPEG2000` (int)
`Gmagick::COMPRESSION_LOSSLESSJPEG` (int)
`Gmagick::COMPRESSION_LZW` (int)
`Gmagick::COMPRESSION_RLE` (int)
`Gmagick::COMPRESSION_ZIP` (int)

Constantes de dibujo
`Gmagick::PAINT_POINT` (int)
`Gmagick::PAINT_REPLACE` (int)
`Gmagick::PAINT_FLOODFILL` (int)
`Gmagick::PAINT_FILLTOBORDER` (int)
`Gmagick::PAINT_RESET` (int)

Constantes de gravedad
`Gmagick::GRAVITY_NORTHWEST` (int)
`Gmagick::GRAVITY_NORTH` (int)
`Gmagick::GRAVITY_NORTHEAST` (int)
`Gmagick::GRAVITY_WEST` (int)
`Gmagick::GRAVITY_CENTER` (int)
`Gmagick::GRAVITY_EAST` (int)
`Gmagick::GRAVITY_SOUTHWEST` (int)
`Gmagick::GRAVITY_SOUTH` (int)
`Gmagick::GRAVITY_SOUTHEAST` (int)

Constantes de estiramiento
`Gmagick::STRETCH_NORMAL` (int)
`Gmagick::STRETCH_ULTRACONDENSED` (int)
`Gmagick::STRETCH_CONDENSED` (int)
`Gmagick::STRETCH_SEMICONDENSED` (int)
`Gmagick::STRETCH_SEMIEXPANDED` (int)
`Gmagick::STRETCH_EXPANDED` (int)
`Gmagick::STRETCH_EXTRAEXPANDED` (int)
`Gmagick::STRETCH_ULTRAEXPANDED` (int)
`Gmagick::STRETCH_ANY` (int)

Constantes de alineación
`Gmagick::ALIGN_UNDEFINED` (int)
`Gmagick::ALIGN_LEFT` (int)
`Gmagick::ALIGN_CENTER` (int)
`Gmagick::ALIGN_RIGHT` (int)

Constantes de decoración
`Gmagick::DECORATION_NO` (int)
`Gmagick::DECORATION_UNDERLINE` (int)
`Gmagick::DECORATION_OVERLINE` (int)
`Gmagick::DECORATION_LINETROUGH` (int)

Constantes de ruido
`Gmagick::NOISE_UNIFORM` (int)
`Gmagick::NOISE_GAUSSIAN` (int)
`Gmagick::NOISE_MULTIPLICATIVEGAUSSIAN` (int)
`Gmagick::NOISE_IMPULSE` (int)
`Gmagick::NOISE_LAPLACIAN` (int)
`Gmagick::NOISE_POISSON` (int)

Constantes de canal
`Gmagick::CHANNEL_UNDEFINED` (int)
`Gmagick::CHANNEL_RED` (int)
`Gmagick::CHANNEL_GRAY` (int)
`Gmagick::CHANNEL_CYAN` (int)
`Gmagick::CHANNEL_GREEN` (int)
`Gmagick::CHANNEL_MAGENTA` (int)
`Gmagick::CHANNEL_BLUE` (int)
`Gmagick::CHANNEL_YELLOW` (int)
`Gmagick::CHANNEL_ALPHA` (int)
`Gmagick::CHANNEL_OPACITY` (int)
`Gmagick::CHANNEL_MATTE` (int)
`Gmagick::CHANNEL_BLACK` (int)
`Gmagick::CHANNEL_INDEX` (int)
`Gmagick::CHANNEL_ALL` (int)

Constantes de medida
`Gmagick::METRIC_UNDEFINED` (int)
`Gmagick::METRIC_MEANABSOLUTEERROR` (int)
`Gmagick::METRIC_MEANSQUAREERROR` (int)
`Gmagick::METRIC_PEAKABSOLUTEERROR` (int)
`Gmagick::METRIC_PEAKSIGNALTONOISERATIO` (int)
`Gmagick::METRIC_ROOTMEANSQUAREDERROR` (int)

Constantes de píxel
`Gmagick::PIXEL_CHAR` (int)
`Gmagick::PIXEL_DOUBLE` (int)
`Gmagick::PIXEL_FLOAT` (int)
`Gmagick::PIXEL_INTEGER` (int)
`Gmagick::PIXEL_LONG` (int)
`Gmagick::PIXEL_QUANTUM` (int)
`Gmagick::PIXEL_SHORT` (int)

Constantes de espacio de color
`Gmagick::COLORSPACE_UNDEFINED` (int)
`Gmagick::COLORSPACE_RGB` (int)
`Gmagick::COLORSPACE_GRAY` (int)
`Gmagick::COLORSPACE_TRANSPARENT` (int)
`Gmagick::COLORSPACE_OHTA` (int)
`Gmagick::COLORSPACE_LAB` (int)
`Gmagick::COLORSPACE_XYZ` (int)
`Gmagick::COLORSPACE_YCBCR` (int)
`Gmagick::COLORSPACE_YCC` (int)
`Gmagick::COLORSPACE_YIQ` (int)
`Gmagick::COLORSPACE_YPBPR` (int)
`Gmagick::COLORSPACE_YUV` (int)
`Gmagick::COLORSPACE_CMYK` (int)
`Gmagick::COLORSPACE_SRGB` (int)
`Gmagick::COLORSPACE_HSB` (int)
`Gmagick::COLORSPACE_HSL` (int)
`Gmagick::COLORSPACE_HWB` (int)
`Gmagick::COLORSPACE_REC601LUMA` (int)
`Gmagick::COLORSPACE_REC709LUMA` (int)
`Gmagick::COLORSPACE_LOG` (int)

Constantes de método para píxeles virtuales
`Gmagick::VIRTUALPIXELMETHOD_UNDEFINED` (int)
`Gmagick::VIRTUALPIXELMETHOD_BACKGROUND` (int)
`Gmagick::VIRTUALPIXELMETHOD_CONSTANT` (int)
`Gmagick::VIRTUALPIXELMETHOD_EDGE` (int)
`Gmagick::VIRTUALPIXELMETHOD_MIRROR` (int)
`Gmagick::VIRTUALPIXELMETHOD_TILE` (int)
`Gmagick::VIRTUALPIXELMETHOD_TRANSPARENT` (int)

Constantes de vista previa
`Gmagick::PREVIEW_UNDEFINED` (int)
`Gmagick::PREVIEW_ROTATE` (int)
`Gmagick::PREVIEW_SHEAR` (int)
`Gmagick::PREVIEW_ROLL` (int)
`Gmagick::PREVIEW_HUE` (int)
`Gmagick::PREVIEW_SATURATION` (int)
`Gmagick::PREVIEW_BRIGHTNESS` (int)
`Gmagick::PREVIEW_GAMMA` (int)
`Gmagick::PREVIEW_SPIFF` (int)
`Gmagick::PREVIEW_DULL` (int)
`Gmagick::PREVIEW_GRAYSCALE` (int)
`Gmagick::PREVIEW_QUANTIZE` (int)
`Gmagick::PREVIEW_DESPECKLE` (int)
`Gmagick::PREVIEW_REDUCENOISE` (int)
`Gmagick::PREVIEW_ADDNOISE` (int)
`Gmagick::PREVIEW_SHARPEN` (int)
`Gmagick::PREVIEW_BLUR` (int)
`Gmagick::PREVIEW_THRESHOLD` (int)
`Gmagick::PREVIEW_EDGEDETECT` (int)
`Gmagick::PREVIEW_SPREAD` (int)
`Gmagick::PREVIEW_SOLARIZE` (int)
`Gmagick::PREVIEW_SHADE` (int)
`Gmagick::PREVIEW_RAISE` (int)
`Gmagick::PREVIEW_SEGMENT` (int)
`Gmagick::PREVIEW_SWIRL` (int)
`Gmagick::PREVIEW_IMPLODE` (int)
`Gmagick::PREVIEW_WAVE` (int)
`Gmagick::PREVIEW_OILPAINT` (int)
`Gmagick::PREVIEW_CHARCOALDRAWING` (int)
`Gmagick::PREVIEW_JPEG` (int)

Constantes de renderizado
`Gmagick::RENDERINGINTENT_UNDEFINED` (int)
`Gmagick::RENDERINGINTENT_SATURATION` (int)
`Gmagick::RENDERINGINTENT_PERCEPTUAL` (int)
`Gmagick::RENDERINGINTENT_ABSOLUTE` (int)
`Gmagick::RENDERINGINTENT_RELATIVE` (int)

Constantes de regla de relleno
`Gmagick::FILLRULE_UNDEFINED` (int)
`Gmagick::FILLRULE_EVENODD` (int)
`Gmagick::FILLRULE_NONZERO` (int)

Constantes de unidad de ruta
`Gmagick::PATHUNITS_UNDEFINED` (int)
`Gmagick::PATHUNITS_USERSPACE` (int)
`Gmagick::PATHUNITS_USERSPACEONUSE` (int)
`Gmagick::PATHUNITS_OBJECTBOUNDINGBOX` (int)

Constantes de extremo de línea
`Gmagick::LINECAP_UNDEFINED` (int)
`Gmagick::LINECAP_BUTT` (int)
`Gmagick::LINECAP_ROUND` (int)
`Gmagick::LINECAP_SQUARE` (int)

Constantes de unión de líneas
`Gmagick::LINEJOIN_UNDEFINED` (int)
`Gmagick::LINEJOIN_MITER` (int)
`Gmagick::LINEJOIN_ROUND` (int)
`Gmagick::LINEJOIN_BEVEL` (int)

Constantes de tipo de recurso
`Gmagick::RESOURCETYPE_UNDEFINED` (int)
`Gmagick::RESOURCETYPE_AREA` (int)
`Gmagick::RESOURCETYPE_DISK` (int)
`Gmagick::RESOURCETYPE_FILE` (int)
`Gmagick::RESOURCETYPE_MAP` (int)
`Gmagick::RESOURCETYPE_MEMORY` (int)

Constantes de orientación
`Gmagick::ORIENTATION_UNDEFINED` (int)
`Gmagick::ORIENTATION_TOPLEFT` (int)
`Gmagick::ORIENTATION_TOPRIGHT` (int)
`Gmagick::ORIENTATION_BOTTOMRIGHT` (int)
`Gmagick::ORIENTATION_BOTTOMLEFT` (int)
`Gmagick::ORIENTATION_LEFTTOP` (int)
`Gmagick::ORIENTATION_RIGHTTOP` (int)
`Gmagick::ORIENTATION_RIGHTBOTTOM` (int)
`Gmagick::ORIENTATION_LEFTBOTTOM` (int)

Constantes de entrelazado
`Gmagick::INTERLACE_UNDEFINED` (int)
`Gmagick::INTERLACE_NO` (int)
`Gmagick::INTERLACE_NONE` (int)
`Gmagick::INTERLACE_LINE` (int)
`Gmagick::INTERLACE_PLANE` (int)
`Gmagick::INTERLACE_PARTITION` (int)

# Ejemplos

A continuación se muestran algunas operaciones comunes con Gmagick.

Ejemplo #1 Ejemplo de Gmagick

    <?php
    // Instanciación de un nuevo objeto Gmagick
    $image = new Gmagick('example.jpg');

    // Crea una miniatura a partir de la imagen cargada. 0 para uno de los ejes preservará la relación de aspecto
    $image->thumbnailimage(100, 0);

    // Crea un borde alrededor de la imagen, luego simula cómo se renderizará la imagen
    // después de un renderizado a pintura al óleo.
    // Observe el encadenamiento de métodos soportado por Gmagick
    $image->borderimage("yellow", 8, 8)->oilpaintimage(0.3);

    // Escribe la imagen actual en un fichero
    $image->write('example_thumbnail.jpg');
    ?>

# La clase Gmagick

(PECL gmagick >= Unknown)

## Introducción

## Sinopsis de la Clase

class Gmagick {
/* Métodos */
public function __construct(string `$filename` = ?)
public function addimage(Gmagick `$source`): Gmagick
public function addnoiseimage(int `$noise_type`): Gmagick
public function annotateimage(
GmagickDraw `$GmagickDraw`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): Gmagick
public function blurimage(float `$radius`, float `$sigma`, int `$channel` = ?): Gmagick
public function borderimage(GmagickPixel `$color`, int `$width`, int `$height`): Gmagick
public function charcoalimage(float `$radius`, float `$sigma`): Gmagick
public function chopimage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Gmagick
public function clear(): Gmagick
public function commentimage(string `$comment`): Gmagick
public function compositeimage(
Gmagick `$source`,
int `$COMPOSE`,
int `$x`,
int `$y`
): Gmagick
public function cropimage(
int `$width` ,
int `$height` ,
int `$x`,
int `$y`
): Gmagick
public function cropthumbnailimage(int `$width`, int `$height`): Gmagick
public function current(): Gmagick
public function cyclecolormapimage(int `$displace`): Gmagick
public function deconstructimages(): Gmagick
public function despeckleimage(): Gmagick
public function destroy(): bool
public function drawimage(GmagickDraw `$GmagickDraw`): Gmagick
public function edgeimage(float `$radius`): Gmagick
public function embossimage(float `$radius`, float `$sigma`): Gmagick
public function enhanceimage(): Gmagick
public function equalizeimage(): Gmagick
public function flipimage(): Gmagick
public function flopimage(): Gmagick
public function frameimage(
GmagickPixel `$color`,
int `$width`,
int `$height`,
int `$inner_bevel`,
int `$outer_bevel`
): Gmagick
public function gammaimage(float `$gamma`): Gmagick
public function getcopyright(): string
public function getfilename(): string
public function getimagebackgroundcolor(): GmagickPixel
public function getimageblueprimary(): array
public function getimagebordercolor(): GmagickPixel
public function getimagechanneldepth(int `$channel_type`): int
public function getimagecolors(): int
public function getimagecolorspace(): int
public function getimagecompose(): int
public function getimagedelay(): int
public function getimagedepth(): int
public function getimagedispose(): int
public function getimageextrema(): array
public function getimagefilename(): string
public function getimageformat(): string
public function getimagegamma(): float
public function getimagegreenprimary(): array
public function getimageheight(): int
public function getimagehistogram(): array
public function getimageindex(): int
public function getimageinterlacescheme(): int
public function getimageiterations(): int
public function getimagematte(): int
public function getimagemattecolor(): GmagickPixel
public function getimageprofile(string `$name`): string
public function getimageredprimary(): array
public function getimagerenderingintent(): int
public function getimageresolution(): array
public function getimagescene(): int
public function getimagesignature(): string
public function getimagetype(): int
public function getimageunits(): int
public function getimagewhitepoint(): array
public function getimagewidth(): int
public function getpackagename(): string
public function getquantumdepth(): array
public function getreleasedate(): string
public function getsamplingfactors(): array
public function getsize(): array
public function getversion(): array
public function hasnextimage(): mixed
public function haspreviousimage(): mixed
public function implodeimage(float `$radius`): mixed
public function labelimage(string `$label`): mixed
public function levelimage(
float `$blackPoint`,
float `$gamma`,
float `$whitePoint`,
int `$channel` = Gmagick::CHANNEL_DEFAULT
): mixed
public function magnifyimage(): mixed
public function mapimage(gmagick `$gmagick`, bool `$dither`): Gmagick
public function medianfilterimage(float `$radius`): void
public function minifyimage(): Gmagick
public function modulateimage(float `$brightness`, float `$saturation`, float `$hue`): Gmagick
public function motionblurimage(float `$radius`, float `$sigma`, float `$angle`): Gmagick
public function newimage(
int `$width`,
int `$height`,
string `$background`,
string `$format` = ?
): Gmagick
public function nextimage(): bool
public function normalizeimage(int `$channel` = ?): Gmagick
public function oilpaintimage( float `$radius` ): Gmagick
public function previousimage(): bool
public function profileimage(string `$name`, string `$profile`): Gmagick
public function quantizeimage(
int `$numColors`,
int `$colorspace`,
int `$treeDepth`,
bool `$dither`,
bool `$measureError`
): Gmagick
public function quantizeimages(
int `$numColors`,
int `$colorspace`,
int `$treeDepth`,
bool `$dither`,
bool `$measureError`
): Gmagick
public function queryfontmetrics(GmagickDraw `$draw`, string `$text`): array
public function queryfonts(string `$pattern` = "*"): array
public function queryformats(string `$pattern` = "*"): array
public function radialblurimage(float `$angle`, int `$channel` = Gmagick::CHANNEL_DEFAULT): Gmagick
public function raiseimage(
int `$width`,
int `$height`,
int `$x`,
int `$y`,
bool `$raise`
): Gmagick
public function read(string `$filename`): Gmagick
public function readimage(string `$filename`): Gmagick
public function readimageblob(string `$imageContents`, string `$filename` = ?): Gmagick
public function readimagefile(resource `$fp`, string `$filename` = ?): Gmagick
public function reducenoiseimage(float `$radius`): Gmagick
public function removeimage(): Gmagick
public function removeimageprofile(string `$name`): string
public function resampleimage(
float `$xResolution`,
float `$yResolution`,
int `$filter`,
float `$blur`
): Gmagick
public function resizeimage(
int `$width`,
int `$height`,
int `$filter`,
float `$blur`,
bool `$fit` = `false`
): Gmagick
public function rollimage(int `$x`, int `$y`): Gmagick
public function rotateimage(mixed `$color`, float `$degrees`): Gmagick
public function scaleimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick
public function separateimagechannel(int `$channel`): Gmagick
function setCompressionQuality( int `$quality` ): Gmagick
public function setfilename(string `$filename`): Gmagick
public function setimagebackgroundcolor(GmagickPixel `$color`): Gmagick
public function setimageblueprimary(float `$x`, float `$y`): Gmagick
public function setimagebordercolor(GmagickPixel `$color`): Gmagick
public function setimagechanneldepth(int `$channel`, int `$depth`): Gmagick
public function setimagecolorspace(int `$colorspace`): Gmagick
public function setimagecompose(int `$composite`): Gmagick
public function setimagedelay(int `$delay`): Gmagick
public function setimagedepth(int `$depth`): Gmagick
public function setimagedispose(int `$disposeType`): Gmagick
public function setimagefilename(string `$filename`): Gmagick
public function setimageformat(string `$imageFormat`): Gmagick
public function setimagegamma(float `$gamma`): Gmagick
public function setimagegreenprimary(float `$x`, float `$y`): Gmagick
public function setimageindex(int `$index`): Gmagick
public function setimageinterlacescheme(int `$interlace`): Gmagick
public function setimageiterations(int `$iterations`): Gmagick
public function setimageprofile(string `$name`, string `$profile`): Gmagick
public function setimageredprimary(float `$x`, float `$y`): Gmagick
public function setimagerenderingintent(int `$rendering_intent`): Gmagick
public function setimageresolution(float `$xResolution`, float `$yResolution`): Gmagick
public function setimagescene(int `$scene`): Gmagick
public function setimagetype(int `$imgType`): Gmagick
public function setimageunits(int `$resolution`): Gmagick
public function setimagewhitepoint(float `$x`, float `$y`): Gmagick
public function setsamplingfactors(array `$factors`): Gmagick
public function setsize(int `$columns`, int `$rows`): Gmagick
public function shearimage(mixed `$color`, float `$xShear`, float `$yShear`): Gmagick
public function solarizeimage(int `$threshold`): Gmagick
public function spreadimage(float `$radius`): Gmagick
public function stripimage(): Gmagick
public function swirlimage(float `$degrees`): Gmagick
public function thumbnailimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick
public function trimimage(float `$fuzz`): Gmagick
public function writeimage(string `$filename`, bool `$all_frames` = `false`): Gmagick
}

# Gmagick::addimage

(PECL gmagick >= Unknown)

Gmagick::addimage — Añade una nueva imagen a la lista de imágenes del objeto Gmagick

### Descripción

public function Gmagick::addimage(Gmagick `$source`): Gmagick

Añade una nueva imagen al objeto Gmagick desde la posición actual del objeto de origen. Después de la operación la posición del iterador se mueve al final de la lista.

### Parámetros

`source`
  El objeto Gmagick de origen

### Valores devueltos

El objeto Gmagick con la imagen añadida

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::addnoiseimage

(PECL gmagick >= Unknown)

Gmagick::addnoiseimage — Añade ruido aleatorio a la imagen

### Descripción

public function Gmagick::addnoiseimage(int `$noise_type`): Gmagick

Añade ruido aleatorio a la imagen.

### Parámetros

`noise_type`
  El tipo de ruido. Consulte esta lista de constantes de ruido.

### Valores devueltos

El objeto Gmagick con el ruido añadido.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::annotateimage

(PECL gmagick >= Unknown)

Gmagick::annotateimage — Anota una imagen con texto

### Descripción

public function Gmagick::annotateimage(
GmagickDraw `$GmagickDraw`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): Gmagick

Anota una imagen con texto.

### Parámetros

`GmagickDraw`
  El objeto GmagickDraw que contiene la configuración para dibujar el texto
`x`
  El índice horizontal en píxeles a la izquierda del texto.
`y`
  El índice vertical en píxeles a la línea base del texto.
`angle`
  El ángulo en el que escribir el texto.
`text`
  La cadena a dibujar.

### Valores devueltos

El objeto Gmagick con la anotación hecha.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::blurimage

(PECL gmagick >= Unknown)

Gmagick::blurimage — Añade un filtro de borrosidad a la imagen

### Descripción

public function Gmagick::blurimage(float `$radius`, float `$sigma`, int `$channel` = ?): Gmagick

Añade un filtro de borrosidad a la imagen.

### Parámetros

`radius`
  Radio de borrosidad
`sigma`
  Desviación estándar

### Valores devueltos

El objeto Gmagick borroso

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::borderimage

(PECL gmagick >= Unknown)

Gmagick::borderimage — Rodea la imagen con un borde

### Descripción

public function Gmagick::borderimage(GmagickPixel `$color`, int `$width`, int `$height`): Gmagick

Rodea la imagen con un borde del color definido por el objeto GmagickPixel de color de borde o por una cadena de color.

### Parámetros

`color`
  El objeto GmagickPixel o una cadena que contiene el color del borde
`width`
  Ancho del borode.
`height`
  Alto del borde.

### Valores devueltos

El objeto Gmagick con el borde definido

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::charcoalimage

(PECL gmagick >= Unknown)

Gmagick::charcoalimage — Simula un dibujo a carboncillo

### Descripción

public function Gmagick::charcoalimage(float `$radius`, float `$sigma`): Gmagick

Simula un dibujo a carboncillo.

### Parámetros

`radius`
  El radio gaussiano, en píxeles, sin contar el píxel central.
`sigma`
  La desviación estándar gaussiana, en píxeles.

### Valores devueltos

El objeto Gmagick con la simulación de carboncillo

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::chopimage

(PECL gmagick >= Unknown)

Gmagick::chopimage — Elimina una región de una imagen y la recorta

### Descripción

public function Gmagick::chopimage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Gmagick

Elimina una región de una imagen y colapsa la imagen para ocupar la porción eliminada.

### Parámetros

`width`
  Ancho del área recortada.
`height`
  Alto del área recortada.
`x`
  Origen X del área recortada.
`y`
  Origen Y del área recortada.

### Valores devueltos

El objeto Gmagick recortado.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::clear

(PECL gmagick >= Unknown)

Gmagick::clear — Limpia todos los recursos asociados con el objeto Gmagick

### Descripción

public function Gmagick::clear(): Gmagick

Limpia todos los recursos asociados al objeto Gmagick.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El objeto Gmagick limpiado.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::commentimage

(PECL gmagick >= Unknown)

Gmagick::commentimage — Añade un comentario a una imagen

### Descripción

public function Gmagick::commentimage(string `$comment`): Gmagick

Añade un comentario a una imagen.

### Parámetros

`comment`
  El comentario a añadir.

### Valores devueltos

El objeto Gmagick con el comentario añadido.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::compositeimage

(PECL gmagick >= Unknown)

Gmagick::compositeimage — Compone una imagen en otra

### Descripción

public function Gmagick::compositeimage(
Gmagick `$source`,
int `$COMPOSE`,
int `$x`,
int `$y`
): Gmagick

Compone una imagen en otra en el índice especificado.

### Parámetros

`source`
  Objeto Gmagick que contiene la imagen compuesta
`COMPOSE`
  Operador de composción.
`x`
  El índice de columna de la imagen compuesta.
`y`
  El índice de fila de la imagen compuesta.

### Valores devueltos

El objeto Gmagick con composiciones.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::__construct

(PECL gmagick >= Unknown)

Gmagick::__construct — El constructor Gmagick

### Descripción

public function Gmagick::__construct(string `$filename` = ?)

El constructor Gmagick

### Parámetros

`filename`
  La ruta a una imagen para cargar o una matriz de rutas.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::cropimage

(PECL gmagick >= Unknown)

Gmagick::cropimage — Extrae una región de la imagen

### Descripción

public function Gmagick::cropimage(
int `$width` ,
int `$height` ,
int `$x`,
int `$y`
): Gmagick

Extrae una región de la imagen.

### Parámetros

`width`
  El ancho del recorte.
`height`
  El alto del recorte.
`x`
  La coordenada X de la esquina superior izquierda de la región recortada.
`y`
  La coordenada Y de la esquina superior izquierda de la región recortada.

### Valores devueltos

El objeto Gmagick recortado

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::cropthumbnailimage

(PECL gmagick >= Unknown)

Gmagick::cropthumbnailimage — Crea una miniatura recortada

### Descripción

public function Gmagick::cropthumbnailimage(int `$width`, int `$height`): Gmagick

Crea una miniatura de tamaño fijo ampliando o reduciendo de escala la imagen y recortando un área específica desde el centro.

### Parámetros

`width`
  El ancho de la miniatura.
`height`
  El alto de la miniatura.

### Valores devueltos

El objeto Gmagick recortado.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::current

(PECL gmagick >= Unknown)

Gmagick::current — Devuelve la refencia al objeto Gmagick acutal

### Descripción

public function Gmagick::current(): Gmagick

Devuelve la refencia al objeto Gmagick acutal con el puntero de imagen apuntando a la secuencia correcta.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Se devuelve a sí mismo si se tuvo éxito.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::cyclecolormapimage

(PECL gmagick >= Unknown)

Gmagick::cyclecolormapimage — Desplaza un mapa de color de una imagen

### Descripción

public function Gmagick::cyclecolormapimage(int `$displace`): Gmagick

Desplaza un mapa de color de una imagen por el número de posiciones dado. Si se realiza un ciclo del mapa de colores varias veces se puede obtener un efecto psicodélico.

### Parámetros

`displace`
  La cantidad a desplazar el mapa de color.

### Valores devueltos

Se devuelve a sí mismo si se tuvo éxito.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::deconstructimages

(PECL gmagick >= Unknown)

Gmagick::deconstructimages — Devuelve ciertas diferencias de píxeles entre imágenes

### Descripción

public function Gmagick::deconstructimages(): Gmagick

Compara cada imagen con la siguiente en una secuencia y devuelve la región circundante máxima de cualquier diferencia de píxeles que se descubra.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un nuevo objeto Gmagick en caso de éxito.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::despeckleimage

(PECL gmagick >= Unknown)

Gmagick::despeckleimage — Reduce el ruido granular de una imagen

### Descripción

public function Gmagick::despeckleimage(): Gmagick

Reduce el ruido granular de una imagen mientras preserva los bordes de la imagen original.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El objeto Gmagick con el ruido granular reducido si se tuvo éxito.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo de Gmagick::despeckleimage()

    <?php
    /* ... */
    ?>

Resultado del ejemplo anterior es similar a:

    ...

# Gmagick::destroy

(PECL gmagick >= Unknown)

Gmagick::destroy — Destruye un objeto Gmagick

### Descripción

public function Gmagick::destroy(): bool

Destruye un objeto Gmagick y libera todos los recursos asociados con él

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::drawimage

(PECL gmagick >= Unknown)

Gmagick::drawimage — Renderiza el objeto GmagickDraw en la imagen actual

### Descripción

public function Gmagick::drawimage(GmagickDraw `$GmagickDraw`): Gmagick

Renderiza el objeto GmagickDraw en la imagen actual

### Parámetros

`GmagickDraw`
  Las operaciones de dibujo para renderizar sobre la imagen.

### Valores devueltos

El objeto Gmagick dibujado

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::edgeimage

(PECL gmagick >= Unknown)

Gmagick::edgeimage — Mejora los bordes dentro de una imagen

### Descripción

public function Gmagick::edgeimage(float `$radius`): Gmagick

Mejora los bordes dentro de una imagen con un filtro de convolución del radio dado. Use un radio de 0 y éste será seleccionado automáticamente.

### Parámetros

`radius`
  El radio de la operación.

### Valores devueltos

El objeto Gmagick con los bordes mejorados.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::embossimage

(PECL gmagick >= Unknown)

Gmagick::embossimage — Devuelve una imagen en escala de grises con un efecto tridimensional

### Descripción

public function Gmagick::embossimage(float `$radius`, float `$sigma`): Gmagick

Devuelve una imagen en escala de grises con un efecto tridimensional. Se convoluciona la imagen con un operador gaussiano del radio y desviación estándar (sigma) dados. Para obtener resultados razonables, el radio debería ser mayor que sigma. Use un radio de 0 y se elegirá un radio apropiado automáticamente.

### Parámetros

`radius`
  El radio del efecto.
`sigma`
  El valor sigma del efecto.

### Valores devueltos

El objeto Gmagick "repujado".

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::enhanceimage

(PECL gmagick >= Unknown)

Gmagick::enhanceimage — Mejora la calidad de una imagen con ruido

### Descripción

public function Gmagick::enhanceimage(): Gmagick

Aplica un filtro digital que mejora la calidad de una imagen con ruido.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El objeto Gmagick mejorado.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::equalizeimage

(PECL gmagick >= Unknown)

Gmagick::equalizeimage — Ecualiza el histograma de la imagen

### Descripción

public function Gmagick::equalizeimage(): Gmagick

Ecualiza el histograma de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El objeto Gmagick ecualizado.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::flipimage

(PECL gmagick >= Unknown)

Gmagick::flipimage — Crea una imagen espejo vertical

### Descripción

public function Gmagick::flipimage(): Gmagick

Crea una imagen espejo vertical reflejando los píxeles alrededor del eje x central.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El objeto Gmagick volteado.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

### Ver también

- Gmagick::flopimage() - Crea una imagen espejo horizontal

# Gmagick::flopimage

(PECL gmagick >= Unknown)

Gmagick::flopimage — Crea una imagen espejo horizontal

### Descripción

public function Gmagick::flopimage(): Gmagick

Crea una imagen espejo horizontal reflejando los píxeles alrededor del eje y central.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El objeto Gmagick volteado.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

### Ver también

- Gmagick::flipimage() - Crea una imagen espejo vertical

# Gmagick::frameimage

(PECL gmagick >= Unknown)

Gmagick::frameimage — Añade un borde tridimensional simulado

### Descripción

public function Gmagick::frameimage(
GmagickPixel `$color`,
int `$width`,
int `$height`,
int `$inner_bevel`,
int `$outer_bevel`
): Gmagick

Añade un borde tridimensional simulado alrededor de la imagen. El ancho y alto especifican el ancho del borde de las caras verticales y horizontales del marco. Los biseles interior y exterior indican el ancho de las sombras interiores y exteriores del marco.

### Parámetros

`color`
  Objeto GmagickPixel o un valor de tipo float que representa el color mate
`width`
  El ancho del borde.
`height`
  El alto del borde.
`inner_bevel`
  El ancho del bisel interior.
`outer_bevel`
  El ancho del bisel exterior.

### Valores devueltos

El objeto Gmagick enmarcado.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::gammaimage

(PECL gmagick >= Unknown)

Gmagick::gammaimage — Corrección gamma de una imagen

### Descripción

public function Gmagick::gammaimage(float `$gamma`): Gmagick

Corrección gamma de una imagen. La misma imagen vista en diferentes dispositivos tendrá diferencias perceptuales en la manera en que la intensidad de la imagen esté representada en la pantalla. Especifique niveles gamma indivuduales para los canales rojo, verde y azul, o ajústelos todos con el parámetro gamma. El rango de valores es típicamente desde 0.8 a 2.3.

### Parámetros

`gamma`
  La cantidad de corrección gamma.

### Valores devueltos

El objeto Gmagick con el valor gamma corregido.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getcopyright

(PECL gmagick >= Unknown)

Gmagick::getcopyright — Devuelve el copyright de la API GraphicsMagick como una cadena

### Descripción

public function Gmagick::getcopyright(): string

Devuelve el copyright de la API GraphicsMagick como una cadena.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una cadena que contiene el anuncio del copyright de la API GraphicsMagick y de la API de C Magickwand.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getfilename

(PECL gmagick >= Unknown)

Gmagick::getfilename — El nombre de archivo asociado a una secuencia de imágenes

### Descripción

public function Gmagick::getfilename(): string

Devuelve el nombre de archivo asociado a una secuencia de imágenes.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una cadena si se tuvo éxito.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimagebackgroundcolor

(PECL gmagick >= Unknown)

Gmagick::getimagebackgroundcolor — Devuelve el color de fondo de la imagen

### Descripción

public function Gmagick::getimagebackgroundcolor(): GmagickPixel

Devuelve el color de fondo de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un objeto GmagickPixel establecido al color de fondo de la imagen.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimageblueprimary

(PECL gmagick >= Unknown)

Gmagick::getimageblueprimary — Devuelve el punto primario azul de la cromaticidad

### Descripción

public function Gmagick::getimageblueprimary(): array

Devuelve el punto primario azul de la cromaticidad de una imagen.

### Parámetros

`x`
  El punto x primario azul de la cromaticidad.
`y`
  El punto y primario azul de la cromaticidad.

### Valores devueltos

Matriz consistente en las coordenadas "x" e "y" del punto.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimagebordercolor

(PECL gmagick >= Unknown)

Gmagick::getimagebordercolor — Devuelve el color del borde de la imagen

### Descripción

public function Gmagick::getimagebordercolor(): GmagickPixel

Devuelve el color del borde de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Objeto GmagickPixel que representa el color del borde

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimagechanneldepth

(PECL gmagick >= Unknown)

Gmagick::getimagechanneldepth — Obtiene la profundidad de un canal de imagen en particular

### Descripción

public function Gmagick::getimagechanneldepth(int `$channel_type`): int

Obtiene la profundidad de un canal de imagen en particular.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

La profundidad del canal de la imagen

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimagecolors

(PECL gmagick >= Unknown)

Gmagick::getimagecolors — Devuelve el color del índice del mapa de color especificado

### Descripción

public function Gmagick::getimagecolors(): int

Devuelve el color del índice del mapa de color especificado.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El número de colores en la imagen.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimagecolorspace

(PECL gmagick >= Unknown)

Gmagick::getimagecolorspace — Obtiene el espacio de colores de la imagen

### Descripción

public function Gmagick::getimagecolorspace(): int

Obtiene el espacio de colores de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El espacio de colores

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimagecompose

(PECL gmagick >= Unknown)

Gmagick::getimagecompose — Devuelve el operador de composición asociado a la imagen

### Descripción

public function Gmagick::getimagecompose(): int

Devuelve el operador de composición asociado a la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el operador de composición asociado a la imagen.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimagedelay

(PECL gmagick >= Unknown)

Gmagick::getimagedelay — Obetiene el retraso de la imagen

### Descripción

public function Gmagick::getimagedelay(): int

Obetiene el retraso de la imagen

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el operados de composción asociado con la imagen.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimagedepth

(PECL gmagick >= Unknown)

Gmagick::getimagedepth — Obtiene la profundidad de la imagen

### Descripción

public function Gmagick::getimagedepth(): int

Obtiene la profundidad de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

La profundidad de la imagen.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimagedispose

(PECL gmagick >= Unknown)

Gmagick::getimagedispose — Obtiene el método de disposición de la imagen

### Descripción

public function Gmagick::getimagedispose(): int

Obtiene el método de disposición de la imagen

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el método de disposición si se tuvo éxito.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimageextrema

(PECL gmagick >= Unknown)

Gmagick::getimageextrema — Obtiene los extremos de la imagen

### Descripción

public function Gmagick::getimageextrema(): array

Devuelve una matriz asociativa con las claves "min" y "max". Emite una excepción GmagickException en caso de error.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una matriz asociativa con las claves "min" y "max".

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimagefilename

(PECL gmagick >= Unknown)

Gmagick::getimagefilename — Devuelve el nombre de archivo de una imagen en particular de una secuencia

### Descripción

public function Gmagick::getimagefilename(): string

Devuelve el nombre de archivo de una imagen en particular de una secuencia

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una cadena con el nombre de archivo de la imagen

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimageformat

(PECL gmagick >= Unknown)

Gmagick::getimageformat — Devuelve el formato de una imagen en particular de una secuencia

### Descripción

public function Gmagick::getimageformat(): string

Devuelve el formato de una imagen en particular de una secuencia.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una cadena que contiene el formato de imagen si se tuvo éxito.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimagegamma

(PECL gmagick >= Unknown)

Gmagick::getimagegamma — Obtiene el valor gamma de la imagen

### Descripción

public function Gmagick::getimagegamma(): float

Obtiene el valor gamma de la imagen

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el valor gamma de la imagen si se tuvo éxito

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimagegreenprimary

(PECL gmagick >= Unknown)

Gmagick::getimagegreenprimary — Devuelve el punto primario verde de la cromaticidad

### Descripción

public function Gmagick::getimagegreenprimary(): array

Devuelve el punto primario verde de la cromaticidad. Devuelve una matriz con las claves "x" e "y".

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una matriz con las claves "x" e "y" si se tuvo éxito.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimageheight

(PECL gmagick >= Unknown)

Gmagick::getimageheight — Devuelve el alto de la imagen

### Descripción

public function Gmagick::getimageheight(): int

Devuelve el alto de la imagen

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el alto de la imagen en píxeles.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimagehistogram

(PECL gmagick >= Unknown)

Gmagick::getimagehistogram — Obtiene el histograma de la imagen

### Descripción

public function Gmagick::getimagehistogram(): array

Devuelve el histograma de la imagen como una matriz de objetos GmagickPixel. Lanza una excepción de tipo GmagickException si se produjo un error.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el histograma de la imagen como una matriz de objetos GmagickPixel.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimageindex

(PECL gmagick >= Unknown)

Gmagick::getimageindex — Obtiene el índice de la imagen activa actual

### Descripción

public function Gmagick::getimageindex(): int

Devuelve el índice de la imagen activa actual dentro del objeto Gmagick.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El índice de la imagen activa actual.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimageinterlacescheme

(PECL gmagick >= Unknown)

Gmagick::getimageinterlacescheme — Obtiene la combinación de entrelazado de la imagen

### Descripción

public function Gmagick::getimageinterlacescheme(): int

Obtiene la combinación de entrelazado de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la combinación de entrelazado como un integer si se tuvo éxito

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimageiterations

(PECL gmagick >= Unknown)

Gmagick::getimageiterations — Obtiene las iteraciones de la imagen

### Descripción

public function Gmagick::getimageiterations(): int

Obtiene las iteraciones de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve las iteraciones de la imagen como un valor integer.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimagematte

(PECL gmagick >= Unknown)

Gmagick::getimagematte — Comprobar si la imagen tiene un canal mate

### Descripción

public function Gmagick::getimagematte(): int

Devuelve `true` si la imagen tiene un canal mate, si no, devuelve `false`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si la imagen tiene un canal mate, si no, devuelve `false`.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimagemattecolor

(PECL gmagick >= Unknown)

Gmagick::getimagemattecolor — Devuelve el color mate de la imagen

### Descripción

public function Gmagick::getimagemattecolor(): GmagickPixel

Devuelve un objeto GmagickPixel si se tuvo éxtito. Lanza un excepción GmagickException si se produjo un error.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un objeto GmagickPixel si se tuvo éxito.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimageprofile

(PECL gmagick >= Unknown)

Gmagick::getimageprofile — Devuelve el perfil nominado de la imagen

### Descripción

public function Gmagick::getimageprofile(string `$name`): string

Devuelve el perfil nominado de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una cadena que contiene el perfil de la imagen.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimageredprimary

(PECL gmagick >= Unknown)

Gmagick::getimageredprimary — Devuelve el punto primario rojo de la cromaticidad

### Descripción

public function Gmagick::getimageredprimary(): array

Devuelve el punto primario rojo de la cromaticidad como una matriz con las claves "x" e "y".

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el punto primario rojo de la cromaticidad como una matriz con las claves "x" e "y".

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimagerenderingintent

(PECL gmagick >= Unknown)

Gmagick::getimagerenderingintent — Obtiene la propuesta de renderización de la imagen

### Descripción

public function Gmagick::getimagerenderingintent(): int

Obtiene la propuesta de renderización de la imagen

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Extrae una región de la imagen y la devuelve como una nueva varita

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimageresolution

(PECL gmagick >= Unknown)

Gmagick::getimageresolution — Obtiene la resolución X e Y de la imagen

### Descripción

public function Gmagick::getimageresolution(): array

Devuelve la resolución como una matriz.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la resolución como una matriz.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimagescene

(PECL gmagick >= Unknown)

Gmagick::getimagescene — Obtiene la escena de la imagen

### Descripción

public function Gmagick::getimagescene(): int

Obtiene la escena de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la escena de la imagen.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimagesignature

(PECL gmagick >= Unknown)

Gmagick::getimagesignature — Genera un resumen de un mensaje SHA-256

### Descripción

public function Gmagick::getimagesignature(): string

Genera un resumen de un mensaje SHA-256 para el flujo de píxeles de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una cadena que contiene el hash SHA-256 del archivo.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimagetype

(PECL gmagick >= Unknown)

Gmagick::getimagetype — Obtiene el tipo de imagen potencial

### Descripción

public function Gmagick::getimagetype(): int

Obtiene el tipo de imagen potencial.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el tipo de imagen potencial.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimageunits

(PECL gmagick >= Unknown)

Gmagick::getimageunits — Obtiene las unidades de resolución de la imagen

### Descripción

public function Gmagick::getimageunits(): int

Obtiene las unidades de resolución de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve las unidades de resolución de la imagen.

# Gmagick::getimagewhitepoint

(PECL gmagick >= Unknown)

Gmagick::getimagewhitepoint — Devuelve el punto blanco de la cromaticidad

### Descripción

public function Gmagick::getimagewhitepoint(): array

Devuelve el punto blanco de la cromaticidad como una matriz asociativa con las claves "x" e "y".

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el punto blanco de la cromaticidad como una matriz asociativa con las claves "x" e "y".

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getimagewidth

(PECL gmagick >= Unknown)

Gmagick::getimagewidth — Devuelve el ancho de la imagen

### Descripción

public function Gmagick::getimagewidth(): int

Devuelve el ancho de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el ancho de la imagen.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getpackagename

(PECL gmagick >= Unknown)

Gmagick::getpackagename — Devuelve el nombre del paquete de GraphicsMagick

### Descripción

public function Gmagick::getpackagename(): string

Devuelve el nombre del paquete de GraphicsMagick.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el nombre del paquete de GraphicsMagick como una cadena.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getquantumdepth

(PECL gmagick >= Unknown)

Gmagick::getquantumdepth — Obtiene la profundidad de la cuantía de Gmagick como una cadena

### Descripción

public function Gmagick::getquantumdepth(): array

Obtiene la profundidad de la cuantía de Gmagick como una cadena.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Obtiene la profundidad de la cuantía de Gmagick como una cadena.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getreleasedate

(PECL gmagick >= Unknown)

Gmagick::getreleasedate — Devuelve la fecha de distribución de GraphicsMagick como una cadena

### Descripción

public function Gmagick::getreleasedate(): string

Devuelve la fecha de distribución de GraphicsMagick como una cadena.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la fecha de distribución de GraphicsMagick como una cadena.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getsamplingfactors

(PECL gmagick >= Unknown)

Gmagick::getsamplingfactors — Obtiene el factor de muestreo horizontal y vertical

### Descripción

public function Gmagick::getsamplingfactors(): array

Obtiene el factor de muestreo horizontal y vertical.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una matriz asociativa con el factor de muestreo horizontal y vertical de la imagen.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getsize

(PECL gmagick >= Unknown)

Gmagick::getsize — Devuelve el tamaño asociado con el objeto Gmagick

### Descripción

public function Gmagick::getsize(): array

Devuelve el tamaño asociado con el objeto Gmagick como una matriz con las claves "columns" (columnas) y "rows" (filas).

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el tamaño asociado con el objeto Gmagick como una matriz con las claves "columns" (columnas) y "rows" (filas).

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::getversion

(PECL gmagick >= Unknown)

Gmagick::getversion — Devuelve la versión de la API GraphicsMagick

### Descripción

public function Gmagick::getversion(): array

Devuelve la versión de la API GraphicsMagick como una cadena y como un número.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la versión de la API GraphicsMagick como una cadena y como un número.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::hasnextimage

(PECL gmagick >= Unknown)

Gmagick::hasnextimage — Comprueba si el objeto tiene más imágenes

### Descripción

public function Gmagick::hasnextimage(): mixed

Devuelve `true` si el objeto tiene más imágenes cuando se atraviesa la lista en dirección hacia delante.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si el objeto tiene más imágenes cuando se atraviesa la lista en dirección hacia delante, devuelve `false` si no hay ninguna.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::haspreviousimage

(PECL gmagick >= Unknown)

Gmagick::haspreviousimage — Verifica si el objeto tiene una imagen previa

### Descripción

public function Gmagick::haspreviousimage(): mixed

Devuelve `true` si el objeto tiene más imágenes cuando se atraviesa la lista en la dirección opuesta

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si el objeto tiene más imágenes cuando se atraviesa la lista en la dirección opuesta, devuelve `false` si no hay ninguna.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::implodeimage

(PECL gmagick >= Unknown)

Gmagick::implodeimage — Crea una nueva imagen como una copia

### Descripción

public function Gmagick::implodeimage(float `$radius`): mixed

Crea una nueva imagen que es una copia de una existente con los píxeles de la imagen "implosionados" por el porcentaje especificado.

### Parámetros

`radius`
  El radio de la implosión.

### Valores devueltos

Devuelve el objeto Gmagick implosionado.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::labelimage

(PECL gmagick >= Unknown)

Gmagick::labelimage — Añade una etiqueta a una imagen

### Descripción

public function Gmagick::labelimage(string `$label`): mixed

Añade una etiqueta a una imagen.

### Parámetros

`label`
  La etiqueta a añadir

### Valores devueltos

Objeto Gmagick con etiqueta.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::levelimage

(PECL gmagick >= Unknown)

Gmagick::levelimage — Ajusta los niveles de la imagen

### Descripción

public function Gmagick::levelimage(
float `$blackPoint`,
float `$gamma`,
float `$whitePoint`,
int `$channel` = Gmagick::CHANNEL_DEFAULT
): mixed

Ajusta los niveles de una imagen escalando la caída de los colores entre los puntos blanco y negro especificados al rango completo de cuantía disponible. Los parámetros proporcionados representan los puntos negro, mitad, y blanco. El punto negro especifica el color más oscuro de la imagen. Los colores más oscuros que el punto negro se establecen a cero. El punto medio especifica una corrección gamma a aplicar a la imagen. Mientras que el punto blanco especifica el color más claro de la imagen. Los colores más claros que el punto blanco se establecen al valor de cuantía máximo.

### Parámetros

`blackPoint`
  El punto negro de la imagen.
`gamma`
  El valor gamma
`whitePoint`
  El punto blanco de la imagen.
`channel`
  Proporcione cualquier constante de canal que sea válida para su modo de canal. Para aplicar más de un canal, combine las constantes channeltype usando operadores a nivel de bits. Consulte esta lista de constantes de canal.

### Valores devueltos

Objeto Gmagick con la imagen nivelada.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::magnifyimage

(PECL gmagick >= Unknown)

Gmagick::magnifyimage — Redimensiona una imagen por 2 manteniendo las proporciones

### Descripción

public function Gmagick::magnifyimage(): mixed

Redimensiona una imagen por 2 manteniendo las proporciones.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El objeto Gmagick modificado.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::mapimage

(PECL gmagick >= Unknown)

Gmagick::mapimage — Sustituye los colores de una imagen por los colores más cercanos de una imagen de referencia

### Descripción

public function Gmagick::mapimage(gmagick `$gmagick`, bool `$dither`): Gmagick

Sustituye los colores de una imagen por los colores más cercanos de una imagen de referencia.

### Parámetros

`gmagick`
  La imagen de referencia.
`dither`
  Entero mayor que 0 para difuminar la imagen mapeada.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::medianfilterimage

(PECL gmagick >= Unknown)

Gmagick::medianfilterimage — Aplica un filtro digital

### Descripción

public function Gmagick::medianfilterimage(float `$radius`): void

Aplica un filtro digital que mejora la calidad del ruido de una imagen. Cada píxel es reemplazado por la mediana en un conjunto de píxeles vecinos tal como se define por el radio.

### Parámetros

`radius`
  El radio de los píxeles vecinos.

### Valores devueltos

El objeto Gmagick al cual se le aplicó el filtro.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::minifyimage

(PECL gmagick >= Unknown)

Gmagick::minifyimage — Reduce una imagen a la mitad manteniendo las proporciones

### Descripción

public function Gmagick::minifyimage(): Gmagick

Reduce una imagen a la mitad manteniendo las proporciones.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::modulateimage

(PECL gmagick >= Unknown)

Gmagick::modulateimage — Controla la luminosidad, la saturación y el tono

### Descripción

public function Gmagick::modulateimage(float `$brightness`, float `$saturation`, float `$hue`): Gmagick

Permite controlar la luminosidad, la saturación y el tono de una imagen. El tono es un porcentaje de una rotación absoluta desde la posición actual. Por ejemplo, 50 corresponde a una rotación de 90 grados en el sentido contrario a las agujas de un reloj, 150, una rotación de 90 grados en el sentido de las agujas de un reloj, o bien, 0 o 200 corresponde a una rotación de 180 grados.

### Parámetros

`brightness`
  El número de porcentaje a modificar para la luminosidad (-100 a +100).
`saturation`
  El número de porcentaje a modificar para la saturación (-100 a +100).
`hue`
  El número de porcentaje a modificar para el tono (-100 a +100).

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::motionblurimage

(PECL gmagick >= Unknown)

Gmagick::motionblurimage — Simula un desenfoque cinético

### Descripción

public function Gmagick::motionblurimage(float `$radius`, float `$sigma`, float `$angle`): Gmagick

Simula un desenfoque cinético. La imagen es procesada con un operador Gaussiano de un radio dado y una desviación estándar (sigma). Para obtener buenos resultados, el radio debe ser mayor que el sigma. Utilice un radio de 0 y el método Gmagick::motionblurimage() selecciona el mejor radio automáticamente. El argumento `angle` proporciona el ángulo del desenfoque cinético.

### Parámetros

`radius`
  El radio del Gaussiano, en píxeles, sin contar el píxel central.
`sigma`
  La desviación estándar del Gaussiano, en píxeles.
`angle`
  Aplica el efecto a lo largo del ángulo.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::newimage

(PECL gmagick >= Unknown)

Gmagick::newimage — Crea una nueva imagen

### Descripción

public function Gmagick::newimage(
int `$width`,
int `$height`,
string `$background`,
string `$format` = ?
): Gmagick

Crea una nueva imagen con el color de fondo especificado.

### Parámetros

`width`
  Ancho de la nueva imagen.
`height`
  Alto de la nueva imagen.
`background`
  El color de fondo a utilizar para la imagen (en forma de número de punto flotante).
`format`
  El formato de la imagen.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::nextimage

(PECL gmagick >= Unknown)

Gmagick::nextimage — Se desplaza a la imagen siguiente

### Descripción

public function Gmagick::nextimage(): bool

Asocia la imagen siguiente en la lista de imágenes con un objeto Gmagick.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::normalizeimage

(PECL gmagick >= Unknown)

Gmagick::normalizeimage — Mejora el contraste del color de la imagen

### Descripción

public function Gmagick::normalizeimage(int `$channel` = ?): Gmagick

Mejora el contraste del color de la imagen ajustando el color de los píxeles para que correspondan al intervalo de colores disponibles.

### Parámetros

`channel`
  Canal a normalizar.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::oilpaintimage

(PECL gmagick >= Unknown)

Gmagick::oilpaintimage — Simula una pintura al óleo

### Descripción

public function Gmagick::oilpaintimage( float `$radius` ): Gmagick

Aplica un filtro de efecto especial que simula una pintura al óleo. Cada píxel es reemplazado por el color más frecuente que suceda en una región circular definida por el radio.

### Parámetros

`radius`
  El radio de la zona inmediata circular.

### Valores devueltos

El objeto Gmagick si se tuvo éxito

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::previousimage

(PECL gmagick >= Unknown)

Gmagick::previousimage — Moverse a la imagen previa del objeto

### Descripción

public function Gmagick::previousimage(): bool

Asocia la imagen previa de una lista de imágenes con el objeto Gmagick.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::profileimage

(PECL gmagick >= Unknown)

Gmagick::profileimage — Añade o elimina un perfil de una imagen

### Descripción

public function Gmagick::profileimage(string `$name`, string `$profile`): Gmagick

Añade o elimina un perfil ICC, IPTC o genérico de una imagen. Si el perfil es `null`, será eliminado de la imagen, de lo contrario, será añadido. Utilice `*` como nombre y un perfil `null` para eliminar todos los perfiles de la imagen.

### Parámetros

`name`
  Nombre del perfil a añadir o eliminar: perfil ICC, IPTC o genérico.
`profile`
  El perfil.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::quantizeimage

(PECL gmagick >= Unknown)

Gmagick::quantizeimage — Analiza los colores dentro de una imagen de referencia

### Descripción

public function Gmagick::quantizeimage(
int `$numColors`,
int `$colorspace`,
int `$treeDepth`,
bool `$dither`,
bool `$measureError`
): Gmagick

Analiza los colores dentro de una imagen de referencia y elige un número fijo de colores que representan la imagen. El objetivo del algoritmo es minimizar la diferencia de colores entre la imagen de entrada y de salida mientras minimiza el tiempo de procesamiento.

### Parámetros

`numColors`
  El número de colores.
`colorspace`
  Lleva a cabo una reducción de color en este espacio de color, normalmaente RGBColorspace.
`treeDepth`
  Normalmente, este valor de tipo integer es cero o uno. Un cero o uno indica a Quantize que elija una profundidad de árbol óptima de Log4(número_colores).% Un árbol de esta profundidad generalmente permite la mejor representación de la imagen de referencia con la menor cantidad de memoria y la velocidad de computación más rápida. En algunos casos, como una imagen con dispersión de color baja (un número bajo de colores), se requiere un valor distinto de Log4(número_colores). Para expandir el árbol de colores completamente, use un valor de 8.
`dither`
  Un valor distinto de cero distribuye la diferencia entre una imagen original y el algoritmo de reducción de color correspondiente a los píxeles de la zona inmediata a lo largo de una curva de Hilbert.
`measureError`
  Un valor distinto de cero mide la diferencia entre la imagen original y la cuantificada. Esta diferencia es el error de cuantización total. El error se computa sumando, en todos los píxeles de una imagen, la distancia al cuadrado en el espacio RGB entre cada valor de píxel de referncia y su valor cuantizado.

### Valores devueltos

El objeto Gmagick si se tuvo éxito

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::quantizeimages

(PECL gmagick >= Unknown)

Gmagick::quantizeimages — Analiza los colores dentro de una secuencia de imágenes

### Descripción

public function Gmagick::quantizeimages(
int `$numColors`,
int `$colorspace`,
int `$treeDepth`,
bool `$dither`,
bool `$measureError`
): Gmagick

Analiza los colores dentro de una secuencia de imágenes y elige un número fijo de colores que representan la imagen. El objetivo del algoritmo es minimizar la diferencia de colores entre la imagen de entrada y de salida mientras minimiza el tiempo de procesamiento.

### Parámetros

`numColors`
  El número de colores.
`colorspace`
  Lleva a cabo una reducción de color en este espacio de color, normalmaente RGBColorspace.
`treeDepth`
  Normalmente, este valor de tipo integer es cero o uno. Un cero o uno indica a Quantize que elija una profundidad de árbol óptima de Log4(número_colores).% Un árbol de esta profundidad generalmente permite la mejor representación de la imagen de referencia con la menor cantidad de memoria y la velocidad de computación más rápida. En algunos casos, como una imagen con dispersión de color baja (un número bajo de colores), se requiere un valor distinto de Log4(número_colores). Para expandir el árbol de colores completamente, use un valor de 8.
`dither`
  Un valor distinto de cero distribuye la diferencia entre una imagen original y el algoritmo de reducción de color correspondiente a los píxeles de la zona inmediata a lo largo de una curva de Hilbert.
`measureError`
  Un valor distinto de cero mide la diferencia entre la imagen original y la cuantificada. Esta diferencia es el error de cuantización total. El error se computa sumando, en todos los píxeles de una imagen, la distancia al cuadrado en el espacio RGB entre cada valor de píxel de referncia y su valor cuantizado.

### Valores devueltos

El objeto Gmagick si se tuvo éxito

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::queryfontmetrics

(PECL gmagick >= Unknown)

Gmagick::queryfontmetrics — Devuelve una matriz que representa las métricas de la fuente

### Descripción

public function Gmagick::queryfontmetrics(GmagickDraw `$draw`, string `$text`): array

MagickQueryFontMetrics() devuelve una matriz que representa las métricas de la fuente.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El objeto Gmagick si se tuvo éxito

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::queryfonts

(PECL gmagick >= Unknown)

Gmagick::queryfonts — Devuelve las fuentes configuradas

### Descripción

public function Gmagick::queryfonts(string `$pattern` = "*"): array

Devuelve las fuentes soportadas por Gmagick.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El objeto Gmagick si se tuvo éxito

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::queryformats

(PECL gmagick >= Unknown)

Gmagick::queryformats — Devuelve los formatos soportados por Gmagick

### Descripción

public function Gmagick::queryformats(string `$pattern` = "*"): array

Devuelve los formatos soportados por Gmagick.

### Parámetros

`pattern`
  Especifica un string que contiene un patrón.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::radialblurimage

(PECL gmagick >= Unknown)

Gmagick::radialblurimage — Desenfoca una imagen siguiendo un radio

### Descripción

public function Gmagick::radialblurimage(float `$angle`, int `$channel` = Gmagick::CHANNEL_DEFAULT): Gmagick

Desenfoca una imagen siguiendo un radio.

### Parámetros

`angle`
  El ángulo de desenfoque, en grados.
`channel`
  Canal afectado.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::raiseimage

(PECL gmagick >= Unknown)

Gmagick::raiseimage — Crea un botón con un efecto 3D

### Descripción

public function Gmagick::raiseimage(
int `$width`,
int `$height`,
int `$x`,
int `$y`,
bool `$raise`
): Gmagick

Crea un botón con un efecto 3D aclarando y oscureciendo los ángulos de la imagen. La altura y el margen de los miembros de raise_info definen el ancho del borde vertical y horizontal del efecto.

### Parámetros

`width`
  Ancho de la zona a tratar.
`height`
  Altura de la zona a tratar.
`x`
  Coordenada en X.
`y`
  Coordenada en Y.
`raise`
  Un valor, distinto de 0, para crear el efecto 3D; de lo contrario, el efecto será atenuado.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::read

(PECL gmagick >= Unknown)

Gmagick::read — Lee una imagen desde un fichero

### Descripción

public function Gmagick::read(string `$filename`): Gmagick

Lee una imagen desde un fichero.

### Parámetros

`filename`
  El nombre del fichero de imagen.

### Valores devueltos

Un objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::readimage

(PECL gmagick >= Unknown)

Gmagick::readimage — Lee una imagen desde un fichero

### Descripción

public function Gmagick::readimage(string `$filename`): Gmagick

Lee una imagen desde un fichero.

### Parámetros

`filename`
  El nombre del fichero de imagen.

### Valores devueltos

Un objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::readimageblob

(PECL gmagick >= Unknown)

Gmagick::readimageblob — Lee una imagen desde una cadena binaria

### Descripción

public function Gmagick::readimageblob(string `$imageContents`, string `$filename` = ?): Gmagick

Lee una imagen desde una cadena binaria.

### Parámetros

`imageContents`
  Contenido de la imagen.
`filename`
  El nombre del fichero de imagen.

### Valores devueltos

Un objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::readimagefile

(PECL gmagick >= Unknown)

Gmagick::readimagefile — El propósito de readimagefile

### Descripción

public function Gmagick::readimagefile(resource `$fp`, string `$filename` = ?): Gmagick

Lee una imagen o una secuencia de imágenes desde un descriptor de fichero abierto.

### Parámetros

`fp`
  El descriptor de fichero.

### Valores devueltos

Un objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::reducenoiseimage

(PECL gmagick >= Unknown)

Gmagick::reducenoiseimage — Suaviza los contornos de la imagen

### Descripción

public function Gmagick::reducenoiseimage(float `$radius`): Gmagick

Suaviza los contornos de la imagen manteniendo la información de las esquinas. El algoritmo funciona reemplazando cada píxel con su vecino más cercano en valor. Un vecino se define por su radio. Utilizar un radio de 0 y el método Gmagick::reducenoiseimage() seleccionará un radio apropiado automáticamente.

### Parámetros

`radius`
  El radio del píxel vecino.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::removeimage

(PECL gmagick >= Unknown)

Gmagick::removeimage — Elimina una imagen de la lista de imágenes

### Descripción

public function Gmagick::removeimage(): Gmagick

Elimina una imagen de la lista de imágenes.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::removeimageprofile

(PECL gmagick >= Unknown)

Gmagick::removeimageprofile — Elimina el perfil nombrado de la imagen y lo devuelve

### Descripción

public function Gmagick::removeimageprofile(string `$name`): string

Elimina el perfil nombrado de la imagen y lo devuelve.

### Parámetros

`name`
  El nombre del perfil a devolver: ICC, IPTC, o perfil genérico.

### Valores devueltos

El perfil nombrado.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::resampleimage

(PECL gmagick >= Unknown)

Gmagick::resampleimage — Re-muestrea la imagen a la resolución deseada

### Descripción

public function Gmagick::resampleimage(
float `$xResolution`,
float `$yResolution`,
int `$filter`,
float `$blur`
): Gmagick

Re-muestrea la imagen a la resolución deseada.

### Parámetros

`xResolution`
  La nueva resolución x de la imagen.
`yResolution`
  La nueva resolución x de la imagen.
`filter`
  El filtro de imagen a usar.
`blur`
  El factor de borrosidad donde mayor que que es borroso, menor que uno es nítido.

### Valores devueltos

El objeto Gmagick si se tuvo éxito

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::resizeimage

(PECL gmagick >= Unknown)

Gmagick::resizeimage — Redimensiona una imagen

### Descripción

public function Gmagick::resizeimage(
int `$width`,
int `$height`,
int `$filter`,
float `$blur`,
bool `$fit` = `false`
): Gmagick

Redimensiona una imagen a las dimensiones deseadas, con un filtro.

### Parámetros

`width`
  El número de columnas en la imagen redimensionada.
`height`
  El número de líneas en la imagen redimensionada.
`filter`
  El filtro de la imagen a utilizar.
`blur`
  El factor de desenfoque, donde los valores superiores a 1 corresponden a completamente desenfocado, y los valores inferiores a 1, lo contrario.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::rollimage

(PECL gmagick >= Unknown)

Gmagick::rollimage — Compensa una imagen

### Descripción

public function Gmagick::rollimage(int `$x`, int `$y`): Gmagick

Compensa una imagen tal como está definido por x e y.

### Parámetros

`x`
  El índice x.
`y`
  El índice y.

### Valores devueltos

El objeto Gmagick si se tuvo éxito

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::rotateimage

(PECL gmagick >= Unknown)

Gmagick::rotateimage — Rota una imagen

### Descripción

public function Gmagick::rotateimage(mixed `$color`, float `$degrees`): Gmagick

Rota una imagen el número de grados especificado. Los triángulos vacíos sobrantes por la rotación de la imagen se rellenan con el color de fondo.

### Parámetros

`color`
  El píxel de color de fondo.
`degrees`
  El número de grados que se va a rotar la imagen.

### Valores devueltos

El objeto Gmagick si se tuvo éxito

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::scaleimage

(PECL gmagick >= Unknown)

Gmagick::scaleimage — Redimensiona una imagen

### Descripción

public function Gmagick::scaleimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick

Redimensiona una imagen a las dimensiones proporcionadas. Los otros parámetros serán calculados si 0 es pasado como argumento.

### Parámetros

`width`
  El número de columnas en la imagen redimensionada.
`height`
  El número de líneas en la imagen redimensionada.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::separateimagechannel

(PECL gmagick >= Unknown)

Gmagick::separateimagechannel — Separa un canal de una imagen

### Descripción

public function Gmagick::separateimagechannel(int `$channel`): Gmagick

Separa un canal de una imagen y devuelve una imagen en escala de grises. Un canal es un componente de un color particular de cada píxel de una imagen.

### Parámetros

`channel`
  Una de las constantes de canales (`Gmagick::CHANNEL_*`).

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setCompressionQuality

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

Gmagick::setCompressionQuality — Define la calidad de compresión por defecto del objeto

### Descripción

function Gmagick::setCompressionQuality( int `$quality` ): Gmagick

Define la calidad de compresión por defecto del objeto.

### Parámetros

`quality`
  El valor por defecto de GraphicsMagick es 75.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con Gmagick::setCompressionQuality()

    <?php
    $gm = new Gmagick();
    $gm->read("magick:rose");
    $gm->setCompressionQuality(2);
    ?>

# Gmagick::setfilename

(PECL gmagick >= Unknown)

Gmagick::setfilename — Define el nombre de archivo antes de leer o escribir una imagen

### Descripción

public function Gmagick::setfilename(string `$filename`): Gmagick

Define el nombre de archivo antes de leer o escribir una imagen.

### Parámetros

`filename`
  El nombre de archivo de la imagen.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimagebackgroundcolor

(PECL gmagick >= Unknown)

Gmagick::setimagebackgroundcolor — Define la color de fondo de la imagen

### Descripción

public function Gmagick::setimagebackgroundcolor(GmagickPixel `$color`): Gmagick

Define la color de fondo de la imagen.

### Parámetros

`color`
  La color de fondo.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimageblueprimary

(PECL gmagick >= Unknown)

Gmagick::setimageblueprimary — Define el punto azul primario de la imagen cromática

### Descripción

public function Gmagick::setimageblueprimary(float `$x`, float `$y`): Gmagick

Define el punto azul primario de la imagen cromática.

### Parámetros

`x`
  Coordenada en X del punto del azul primario.
`y`
  Coordenada en Y del punto del azul primario.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimagebordercolor

(PECL gmagick >= Unknown)

Gmagick::setimagebordercolor — Define la color de la frontera de la imagen

### Descripción

public function Gmagick::setimagebordercolor(GmagickPixel `$color`): Gmagick

Define la color de la frontera de la imagen.

### Parámetros

`color`
  La color de la frontera.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimagechanneldepth

(PECL gmagick >= Unknown)

Gmagick::setimagechanneldepth — Define la profundidad de un canal particular de la imagen

### Descripción

public function Gmagick::setimagechanneldepth(int `$channel`, int `$depth`): Gmagick

Define la profundidad de un canal particular de la imagen.

### Parámetros

`channel`
  Una de las constantes de canales (`Gmagick::CHANNEL_*`).
`depth`
  La profundidad de la imagen, en bytes.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimagecolorspace

(PECL gmagick >= Unknown)

Gmagick::setimagecolorspace — Define el espacio de colores de la imagen

### Descripción

public function Gmagick::setimagecolorspace(int `$colorspace`): Gmagick

Define el espacio de colores de la imagen.

### Parámetros

`colorspace`
  Una de las constantes de espacio de colores de la imagen (`Gmagick::COLORSPACE_*`).

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimagecompose

(PECL gmagick >= Unknown)

Gmagick::setimagecompose — Establece el operador de composción de una imagen

### Descripción

public function Gmagick::setimagecompose(int `$composite`): Gmagick

Establece el operador de composción de una imagen.

### Parámetros

`composite`
  El operador de composición de la imagen.

### Valores devueltos

El objeto Gmagick si se tuvo éxito

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimagedelay

(PECL gmagick >= Unknown)

Gmagick::setimagedelay — Define el retraso de la imagen

### Descripción

public function Gmagick::setimagedelay(int `$delay`): Gmagick

Define el retraso de la imagen.

### Parámetros

`delay`
  El retraso de la imagen, en centésimas de segundo.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimagedepth

(PECL gmagick >= Unknown)

Gmagick::setimagedepth — Define la profundidad de la imagen

### Descripción

public function Gmagick::setimagedepth(int `$depth`): Gmagick

Define la profundidad de la imagen.

### Parámetros

`depth`
  La profundidad de la imagen, en bytes: 8, 16, o 32.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimagedispose

(PECL gmagick >= Unknown)

Gmagick::setimagedispose — Define el método de disposición de la imagen

### Descripción

public function Gmagick::setimagedispose(int `$disposeType`): Gmagick

Define el método de disposición de la imagen.

### Parámetros

`disposeType`
  El tipo de disposición de la imagen.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimagefilename

(PECL gmagick >= Unknown)

Gmagick::setimagefilename — Define el nombre del fichero para una imagen particular de una secuencia

### Descripción

public function Gmagick::setimagefilename(string `$filename`): Gmagick

Define el nombre del fichero para una imagen particular de una secuencia.

### Parámetros

`filename`
  El nombre del fichero de la imagen.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimageformat

(PECL gmagick >= Unknown)

Gmagick::setimageformat — Define el formato de una imagen

### Descripción

public function Gmagick::setimageformat(string `$imageFormat`): Gmagick

Define el formato de una imagen particular de una secuencia.

### Parámetros

`imageFormat`
  El formato de la imagen.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimagegamma

(PECL gmagick >= Unknown)

Gmagick::setimagegamma — Define el gamma de la imagen

### Descripción

public function Gmagick::setimagegamma(float `$gamma`): Gmagick

Define el gamma de la imagen.

### Parámetros

`gamma`
  El gamma de la imagen.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimagegreenprimary

(PECL gmagick >= Unknown)

Gmagick::setimagegreenprimary — Define el punto verde en la imagen cromática primaria

### Descripción

public function Gmagick::setimagegreenprimary(float `$x`, float `$y`): Gmagick

Define el punto verde en la imagen cromática primaria.

### Parámetros

`x`
  Coordenada en X del punto verde de la imagen cromática.
`y`
  Coordenada en Y del punto verde de la imagen cromática.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimageindex

(PECL gmagick >= Unknown)

Gmagick::setimageindex — Establece el iterador en la posición especificada en la lista de imágenes apuntada por su índice

### Descripción

public function Gmagick::setimageindex(int `$index`): Gmagick

Establece el iterador en la posición especificada en la lista de imágenes apuntada por su índice.

### Parámetros

`index`
  El número de la escena.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimageinterlacescheme

(PECL gmagick >= Unknown)

Gmagick::setimageinterlacescheme — Define el esquema de entrelazado de la imagen

### Descripción

public function Gmagick::setimageinterlacescheme(int `$interlace`): Gmagick

Define el esquema de entrelazado de la imagen.

### Parámetros

`interlace`
  Una de las constantes de los esquemas de entrelazado de la imagen (`Gmagick::INTERLACE_*`).

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimageiterations

(PECL gmagick >= Unknown)

Gmagick::setimageiterations — Define las iteraciones de la imagen

### Descripción

public function Gmagick::setimageiterations(int `$iterations`): Gmagick

Define las iteraciones de la imagen.

### Parámetros

`iterations`
  El tiempo de la imagen en centésimas de segundo.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimageprofile

(PECL gmagick >= Unknown)

Gmagick::setimageprofile — Añade un perfil nombrado al objeto Gmagick

### Descripción

public function Gmagick::setimageprofile(string `$name`, string `$profile`): Gmagick

Añade un perfil nombrado al objeto Gmagick. Si un perfil con el mismo nobre ya existe, se reemplaza. Este método difiere del método Gmagick::ProfileImage() en que no aplica ningún perfil de color CMS.

### Parámetros

`name`
  El nombre del perfil a añadir o eliminar: ICC, IPTC, o perfil genérico.
`profile`
  El perfil.

### Valores devueltos

El objeto Gmagick si se tuvo éxito.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimageredprimary

(PECL gmagick >= Unknown)

Gmagick::setimageredprimary — Define el punto rojo en la imagen cromática primaria

### Descripción

public function Gmagick::setimageredprimary(float `$x`, float `$y`): Gmagick

Define el punto rojo en la imagen cromática primaria.

### Parámetros

`x`
  Coordenada en X del punto rojo de la imagen cromática.
`y`
  Coordenada en Y del punto rojo de la imagen cromática.

### Valores devueltos

El objeto Gmagick en caso de éxito.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimagerenderingintent

(PECL gmagick >= Unknown)

Gmagick::setimagerenderingintent — Define la imagen de renderizado

### Descripción

public function Gmagick::setimagerenderingintent(int `$rendering_intent`): Gmagick

Define la imagen de renderizado.

### Parámetros

`rendering_intent`
  Una de las constantes de renderizado de imagen (`Gmagick::RENDERINGINTENT_*`).

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimageresolution

(PECL gmagick >= Unknown)

Gmagick::setimageresolution — Establece la resolución de la imagen

### Descripción

public function Gmagick::setimageresolution(float `$xResolution`, float `$yResolution`): Gmagick

Establece la resolución de la imagen.

### Parámetros

`xResolution`
  La resolución x de la imagen.
`yResolution`
  La resolución y de la imagen.

### Valores devueltos

El objeto Gmagick si se tuvo éxito.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimagescene

(PECL gmagick >= Unknown)

Gmagick::setimagescene — Define la imagen de escena

### Descripción

public function Gmagick::setimagescene(int `$scene`): Gmagick

Define la imagen de escena.

### Parámetros

`scene`
  El número de la escena en la imagen.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimagetype

(PECL gmagick >= Unknown)

Gmagick::setimagetype — Define el tipo de la imagen

### Descripción

public function Gmagick::setimagetype(int `$imgType`): Gmagick

Define el tipo de la imagen.

### Parámetros

`imgType`
  Una de las constantes de tipo de imagen (`Gmagick::IMGTYPE_*`).

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimageunits

(PECL gmagick >= Unknown)

Gmagick::setimageunits — Define las unidades a utilizar para la resolución de la imagen

### Descripción

public function Gmagick::setimageunits(int `$resolution`): Gmagick

Define las unidades a utilizar para la resolución de la imagen.

### Parámetros

`resolution`
  Una de las constantes de resolución (`Gmagick::RESOLUTION_*`).

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setimagewhitepoint

(PECL gmagick >= Unknown)

Gmagick::setimagewhitepoint — Define el punto blanco en la imagen cromática primaria

### Descripción

public function Gmagick::setimagewhitepoint(float `$x`, float `$y`): Gmagick

Define el punto blanco en la imagen cromática primaria.

### Parámetros

`x`
  Coordenada en X del punto blanco de la imagen cromática.
`y`
  Coordenada en Y del punto blanco de la imagen cromática.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setsamplingfactors

(PECL gmagick >= Unknown)

Gmagick::setsamplingfactors — Define los factores de muestreo de la imagen

### Descripción

public function Gmagick::setsamplingfactors(array `$factors`): Gmagick

Define los factores de muestreo de la imagen.

### Parámetros

`factors`
  Un array de floats, representando el factor de muestreo para cada componente de color (en el orden RGB).

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::setsize

(PECL gmagick >= Unknown)

Gmagick::setsize — Define el tamaño del objeto Gmagick

### Descripción

public function Gmagick::setsize(int `$columns`, int `$rows`): Gmagick

Define el tamaño del objeto Gmagick. Defínase el tamaño antes de leer una imagen sin procesar en el formato `Gmagick::COLORSPACE_RGB`, `Gmagick::COLORSPACE_GRAY`, o `Gmagick::COLORSPACE_CMYK`.

### Parámetros

`columns`
  El ancho, en píxeles.
`rows`
  La altura, en píxeles.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::shearimage

(PECL gmagick >= Unknown)

Gmagick::shearimage — Crea un paralelogramo

### Descripción

public function Gmagick::shearimage(mixed `$color`, float `$xShear`, float `$yShear`): Gmagick

Mueve una esquina de la imagen a lo largo de los ejes X o Y para crear un paralelogramo. Una dirección en X mueve a lo largo del eje X, mientras que una dirección en Y mueve a lo largo del eje Y. La cantidad de corte se controla mediante un ángulo de corte. Para los cortes en dirección X, x_shear se mide relativamente al eje Y, e inversamente, para los cortes en dirección Y, y_shear se mide relativamente al eje X. Los triángulos vacíos así creados durante el corte de la imagen serán rellenados con el color de fondo.

### Parámetros

`color`
  El píxel de fondo.
`xShear`
  El grado de corte de la imagen.
`yShear`
  El grado de corte de la imagen.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::solarizeimage

(PECL gmagick >= Unknown)

Gmagick::solarizeimage — Aplica un efecto de solarización a la imagen

### Descripción

public function Gmagick::solarizeimage(int `$threshold`): Gmagick

Aplica un efecto de solarización a la imagen, similar al efecto creado en una foto en cámara oscura, exponiendo las zonas de una foto sobre papel sensible a la luz. El umbral varía de 0 a QuantumRange y es una medida de la extensión de la solarización.

### Parámetros

`threshold`
  Define la extensión de la solarización.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::spreadimage

(PECL gmagick >= Unknown)

Gmagick::spreadimage — Desplaza aleatoriamente cada píxel de un bloque

### Descripción

public function Gmagick::spreadimage(float `$radius`): Gmagick

Efecto especial que desplaza aleatoriamente cada píxel de un bloque definido por el argumento `radius`.

### Parámetros

`radius`
  Selecciona píxeles aleatoriamente en el vecindario de este alcance.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::stripimage

(PECL gmagick >= Unknown)

Gmagick::stripimage — Elimina de una imagen todos los perfiles y todos los comentarios

### Descripción

public function Gmagick::stripimage(): Gmagick

Elimina de una imagen todos los perfiles y todos los comentarios.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::swirlimage

(PECL gmagick >= Unknown)

Gmagick::swirlimage — Remue los píxeles del centro de la imagen

### Descripción

public function Gmagick::swirlimage(float `$degrees`): Gmagick

Remue los píxeles del centro de la imagen, donde los grados indican el arco de remolino alrededor del cual los píxeles son desplazados. Se puede obtener un efecto cada vez más pronunciado modificando los grados de 1 a 360.

### Parámetros

`degrees`
  Define la intensidad del efecto de remolino.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::thumbnailimage

(PECL gmagick >= Unknown)

Gmagick::thumbnailimage — Modifica el tamaño de una imagen

### Descripción

public function Gmagick::thumbnailimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick

Modifica el tamaño de una imagen a las dimensiones dadas y elimina los perfiles asociados. El objetivo es producir una imagen en miniatura, menos pesada, con fines de visualización en la Web. Si `true` se proporciona como valor del 3er argumento, entonces los argumentos `width` y `height` se utilizan como valores máximos para cada lado. Ambos lados serán escalados durante la operación.

### Parámetros

`width`
  Ancho de la imagen.
`height`
  Altura de la imagen.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::trimimage

(PECL gmagick >= Unknown)

Gmagick::trimimage — Elimina los bordes de la imagen

### Descripción

public function Gmagick::trimimage(float `$fuzz`): Gmagick

Elimina los bordes que son del color del fondo de la imagen.

### Parámetros

`fuzz`
  Por omisión, el objetivo debe coincidir exactamente con el color del píxel preciso. Sin embargo, en muchos casos, 2 colores pueden diferir ligeramente. Este parámetro indica la tolerancia admisible para considerar 2 colores como idénticos.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

# Gmagick::write

(PECL gmagick >= Unknown)

Gmagick::write — Alias de Gmagick::writeimage()

### Descripción

Este método es un alias de: Gmagick::writeimage().

# Gmagick::writeimage

(PECL gmagick >= Unknown)

Gmagick::writeimage — Escribe una imagen en un archivo

### Descripción

public function Gmagick::writeimage(string `$filename`, bool `$all_frames` = `false`): Gmagick

Escribe una imagen en un archivo específico. Si el argumento `filename` es `null`, la imagen será escrita en el archivo definido por el método Gmagick::readimage() o el método Gmagick::setimagefilename().

### Parámetros

`filename`
  El nombre del archivo.

### Valores devueltos

El objeto Gmagick.

### Errores/Excepciones

Emite una excepción GmagickException en caso de error.

## Tabla de contenidos

- Gmagick::addimage — Añade una nueva imagen a la lista de imágenes del objeto Gmagick
- Gmagick::addnoiseimage — Añade ruido aleatorio a la imagen
- Gmagick::annotateimage — Anota una imagen con texto
- Gmagick::blurimage — Añade un filtro de borrosidad a la imagen
- Gmagick::borderimage — Rodea la imagen con un borde
- Gmagick::charcoalimage — Simula un dibujo a carboncillo
- Gmagick::chopimage — Elimina una región de una imagen y la recorta
- Gmagick::clear — Limpia todos los recursos asociados con el objeto Gmagick
- Gmagick::commentimage — Añade un comentario a una imagen
- Gmagick::compositeimage — Compone una imagen en otra
- Gmagick::__construct — El constructor Gmagick
- Gmagick::cropimage — Extrae una región de la imagen
- Gmagick::cropthumbnailimage — Crea una miniatura recortada
- Gmagick::current — Devuelve la refencia al objeto Gmagick acutal
- Gmagick::cyclecolormapimage — Desplaza un mapa de color de una imagen
- Gmagick::deconstructimages — Devuelve ciertas diferencias de píxeles entre imágenes
- Gmagick::despeckleimage — Reduce el ruido granular de una imagen
- Gmagick::destroy — Destruye un objeto Gmagick
- Gmagick::drawimage — Renderiza el objeto GmagickDraw en la imagen actual
- Gmagick::edgeimage — Mejora los bordes dentro de una imagen
- Gmagick::embossimage — Devuelve una imagen en escala de grises con un efecto tridimensional
- Gmagick::enhanceimage — Mejora la calidad de una imagen con ruido
- Gmagick::equalizeimage — Ecualiza el histograma de la imagen
- Gmagick::flipimage — Crea una imagen espejo vertical
- Gmagick::flopimage — Crea una imagen espejo horizontal
- Gmagick::frameimage — Añade un borde tridimensional simulado
- Gmagick::gammaimage — Corrección gamma de una imagen
- Gmagick::getcopyright — Devuelve el copyright de la API GraphicsMagick como una cadena
- Gmagick::getfilename — El nombre de archivo asociado a una secuencia de imágenes
- Gmagick::getimagebackgroundcolor — Devuelve el color de fondo de la imagen
- Gmagick::getimageblueprimary — Devuelve el punto primario azul de la cromaticidad
- Gmagick::getimagebordercolor — Devuelve el color del borde de la imagen
- Gmagick::getimagechanneldepth — Obtiene la profundidad de un canal de imagen en particular
- Gmagick::getimagecolors — Devuelve el color del índice del mapa de color especificado
- Gmagick::getimagecolorspace — Obtiene el espacio de colores de la imagen
- Gmagick::getimagecompose — Devuelve el operador de composición asociado a la imagen
- Gmagick::getimagedelay — Obetiene el retraso de la imagen
- Gmagick::getimagedepth — Obtiene la profundidad de la imagen
- Gmagick::getimagedispose — Obtiene el método de disposición de la imagen
- Gmagick::getimageextrema — Obtiene los extremos de la imagen
- Gmagick::getimagefilename — Devuelve el nombre de archivo de una imagen en particular de una secuencia
- Gmagick::getimageformat — Devuelve el formato de una imagen en particular de una secuencia
- Gmagick::getimagegamma — Obtiene el valor gamma de la imagen
- Gmagick::getimagegreenprimary — Devuelve el punto primario verde de la cromaticidad
- Gmagick::getimageheight — Devuelve el alto de la imagen
- Gmagick::getimagehistogram — Obtiene el histograma de la imagen
- Gmagick::getimageindex — Obtiene el índice de la imagen activa actual
- Gmagick::getimageinterlacescheme — Obtiene la combinación de entrelazado de la imagen
- Gmagick::getimageiterations — Obtiene las iteraciones de la imagen
- Gmagick::getimagematte — Comprobar si la imagen tiene un canal mate
- Gmagick::getimagemattecolor — Devuelve el color mate de la imagen
- Gmagick::getimageprofile — Devuelve el perfil nominado de la imagen
- Gmagick::getimageredprimary — Devuelve el punto primario rojo de la cromaticidad
- Gmagick::getimagerenderingintent — Obtiene la propuesta de renderización de la imagen
- Gmagick::getimageresolution — Obtiene la resolución X e Y de la imagen
- Gmagick::getimagescene — Obtiene la escena de la imagen
- Gmagick::getimagesignature — Genera un resumen de un mensaje SHA-256
- Gmagick::getimagetype — Obtiene el tipo de imagen potencial
- Gmagick::getimageunits — Obtiene las unidades de resolución de la imagen
- Gmagick::getimagewhitepoint — Devuelve el punto blanco de la cromaticidad
- Gmagick::getimagewidth — Devuelve el ancho de la imagen
- Gmagick::getpackagename — Devuelve el nombre del paquete de GraphicsMagick
- Gmagick::getquantumdepth — Obtiene la profundidad de la cuantía de Gmagick como una cadena
- Gmagick::getreleasedate — Devuelve la fecha de distribución de GraphicsMagick como una cadena
- Gmagick::getsamplingfactors — Obtiene el factor de muestreo horizontal y vertical
- Gmagick::getsize — Devuelve el tamaño asociado con el objeto Gmagick
- Gmagick::getversion — Devuelve la versión de la API GraphicsMagick
- Gmagick::hasnextimage — Comprueba si el objeto tiene más imágenes
- Gmagick::haspreviousimage — Verifica si el objeto tiene una imagen previa
- Gmagick::implodeimage — Crea una nueva imagen como una copia
- Gmagick::labelimage — Añade una etiqueta a una imagen
- Gmagick::levelimage — Ajusta los niveles de la imagen
- Gmagick::magnifyimage — Redimensiona una imagen por 2 manteniendo las proporciones
- Gmagick::mapimage — Sustituye los colores de una imagen por los colores más cercanos de una imagen de referencia
- Gmagick::medianfilterimage — Aplica un filtro digital
- Gmagick::minifyimage — Reduce una imagen a la mitad manteniendo las proporciones
- Gmagick::modulateimage — Controla la luminosidad, la saturación y el tono
- Gmagick::motionblurimage — Simula un desenfoque cinético
- Gmagick::newimage — Crea una nueva imagen
- Gmagick::nextimage — Se desplaza a la imagen siguiente
- Gmagick::normalizeimage — Mejora el contraste del color de la imagen
- Gmagick::oilpaintimage — Simula una pintura al óleo
- Gmagick::previousimage — Moverse a la imagen previa del objeto
- Gmagick::profileimage — Añade o elimina un perfil de una imagen
- Gmagick::quantizeimage — Analiza los colores dentro de una imagen de referencia
- Gmagick::quantizeimages — Analiza los colores dentro de una secuencia de imágenes
- Gmagick::queryfontmetrics — Devuelve una matriz que representa las métricas de la fuente
- Gmagick::queryfonts — Devuelve las fuentes configuradas
- Gmagick::queryformats — Devuelve los formatos soportados por Gmagick
- Gmagick::radialblurimage — Desenfoca una imagen siguiendo un radio
- Gmagick::raiseimage — Crea un botón con un efecto 3D
- Gmagick::read — Lee una imagen desde un fichero
- Gmagick::readimage — Lee una imagen desde un fichero
- Gmagick::readimageblob — Lee una imagen desde una cadena binaria
- Gmagick::readimagefile — El propósito de readimagefile
- Gmagick::reducenoiseimage — Suaviza los contornos de la imagen
- Gmagick::removeimage — Elimina una imagen de la lista de imágenes
- Gmagick::removeimageprofile — Elimina el perfil nombrado de la imagen y lo devuelve
- Gmagick::resampleimage — Re-muestrea la imagen a la resolución deseada
- Gmagick::resizeimage — Redimensiona una imagen
- Gmagick::rollimage — Compensa una imagen
- Gmagick::rotateimage — Rota una imagen
- Gmagick::scaleimage — Redimensiona una imagen
- Gmagick::separateimagechannel — Separa un canal de una imagen
- Gmagick::setCompressionQuality — Define la calidad de compresión por defecto del objeto
- Gmagick::setfilename — Define el nombre de archivo antes de leer o escribir una imagen
- Gmagick::setimagebackgroundcolor — Define la color de fondo de la imagen
- Gmagick::setimageblueprimary — Define el punto azul primario de la imagen cromática
- Gmagick::setimagebordercolor — Define la color de la frontera de la imagen
- Gmagick::setimagechanneldepth — Define la profundidad de un canal particular de la imagen
- Gmagick::setimagecolorspace — Define el espacio de colores de la imagen
- Gmagick::setimagecompose — Establece el operador de composción de una imagen
- Gmagick::setimagedelay — Define el retraso de la imagen
- Gmagick::setimagedepth — Define la profundidad de la imagen
- Gmagick::setimagedispose — Define el método de disposición de la imagen
- Gmagick::setimagefilename — Define el nombre del fichero para una imagen particular de una secuencia
- Gmagick::setimageformat — Define el formato de una imagen
- Gmagick::setimagegamma — Define el gamma de la imagen
- Gmagick::setimagegreenprimary — Define el punto verde en la imagen cromática primaria
- Gmagick::setimageindex — Establece el iterador en la posición especificada en la lista de imágenes apuntada por su índice
- Gmagick::setimageinterlacescheme — Define el esquema de entrelazado de la imagen
- Gmagick::setimageiterations — Define las iteraciones de la imagen
- Gmagick::setimageprofile — Añade un perfil nombrado al objeto Gmagick
- Gmagick::setimageredprimary — Define el punto rojo en la imagen cromática primaria
- Gmagick::setimagerenderingintent — Define la imagen de renderizado
- Gmagick::setimageresolution — Establece la resolución de la imagen
- Gmagick::setimagescene — Define la imagen de escena
- Gmagick::setimagetype — Define el tipo de la imagen
- Gmagick::setimageunits — Define las unidades a utilizar para la resolución de la imagen
- Gmagick::setimagewhitepoint — Define el punto blanco en la imagen cromática primaria
- Gmagick::setsamplingfactors — Define los factores de muestreo de la imagen
- Gmagick::setsize — Define el tamaño del objeto Gmagick
- Gmagick::shearimage — Crea un paralelogramo
- Gmagick::solarizeimage — Aplica un efecto de solarización a la imagen
- Gmagick::spreadimage — Desplaza aleatoriamente cada píxel de un bloque
- Gmagick::stripimage — Elimina de una imagen todos los perfiles y todos los comentarios
- Gmagick::swirlimage — Remue los píxeles del centro de la imagen
- Gmagick::thumbnailimage — Modifica el tamaño de una imagen
- Gmagick::trimimage — Elimina los bordes de la imagen
- Gmagick::write — Alias de Gmagick::writeimage
- Gmagick::writeimage — Escribe una imagen en un archivo

# La clase GmagickDraw

(PECL gmagick >= Unknown)

## Introducción

## Sinopsis de la Clase

class GmagickDraw {
/* Métodos */
public function annotate(float `$x`, float `$y`, string `$text`): GmagickDraw
public function arc(
float `$sx`,
float `$sy`,
float `$ex`,
float `$ey`,
float `$sd`,
float `$ed`
): GmagickDraw
public function bezier(array `$coordinate_array`): GmagickDraw
public function ellipse(
float `$ox`,
float `$oy`,
float `$rx`,
float `$ry`,
float `$start`,
float `$end`
): GmagickDraw
public function getfillcolor(): GmagickPixel
public function getfillopacity(): float
public function getfont(): mixed
public function getfontsize(): float
public function getfontstyle(): int
public function getfontweight(): int
public function getstrokecolor(): GmagickPixel
public function getstrokeopacity(): float
public function getstrokewidth(): float
public function gettextdecoration(): int
public function gettextencoding(): mixed
public function line(
float `$sx`,
float `$sy`,
float `$ex`,
float `$ey`
): GmagickDraw
public function point(float `$x`, float `$y`): GmagickDraw
public function polygon(array `$coordinates`): GmagickDraw
public function polyline(array `$coordinate_array`): GmagickDraw
public function rectangle(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`
): GmagickDraw
public function rotate(float `$degrees`): GmagickDraw
public function roundrectangle(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$rx`,
float `$ry`
): GmagickDraw
public function scale(float `$x`, float `$y`): GmagickDraw
public function setfillcolor(mixed `$color`): GmagickDraw
public function setfillopacity(float `$fill_opacity`): GmagickDraw
public function setfont(string `$font`): GmagickDraw
public function setfontsize(float `$pointsize`): GmagickDraw
public function setfontstyle(int `$style`): GmagickDraw
public function setfontweight(int `$weight`): GmagickDraw
public function setstrokecolor(mixed `$color`): GmagickDraw
public function setstrokeopacity(float `$stroke_opacity`): GmagickDraw
public function setstrokewidth(float `$width`): GmagickDraw
public function settextdecoration(int `$decoration`): GmagickDraw
public function settextencoding(string `$encoding`): GmagickDraw
}

# GmagickDraw::annotate

(PECL gmagick >= Unknown)

GmagickDraw::annotate — Dibuja texto en la imagen

### Descripción

public function GmagickDraw::annotate(float `$x`, float `$y`, string `$text`): GmagickDraw

Dibuja texto en la imagen.

### Parámetros

`x`
  coordenada x a la izquierda del texto
`y`
  coordenada y a la línea base del texto
`text`
  texto a dibujar

### Valores devueltos

El objeto GmagickDraw si se tuvo éxito.

# GmagickDraw::arc

(PECL gmagick >= Unknown)

GmagickDraw::arc — Dibuja un arco

### Descripción

public function GmagickDraw::arc(
float `$sx`,
float `$sy`,
float `$ex`,
float `$ey`,
float `$sd`,
float `$ed`
): GmagickDraw

Dibuja un arco que cae dentro de un rectángulo circundante en la imagen.

### Parámetros

`sx`
  coordenada x del inicio del rectángulo circundante
`sy`
  coordenada y del inicio del rectángulo circundante
`ex`
  coordenada x del final del rectángulo circundante
`ey`
  coordenada y del final del rectángulo circundante
`sd`
  grados de inicio de rotación
`ed`
  grados finales de rotación

### Valores devueltos

El objeto GmagickDraw si se tuvo éxito.

# GmagickDraw::bezier

(PECL gmagick >= Unknown)

GmagickDraw::bezier — Dibuja una curva Bézier

### Descripción

public function GmagickDraw::bezier(array `$coordinate_array`): GmagickDraw

Dibuja una curva Bézier a través de un conjunto de puntos en la imagen.

### Parámetros

`coordinate_array`
  Matriz de coordenadas

### Valores devueltos

El objeto GmagickDraw si se tuvo éxito

# GmagickDraw::ellipse

(PECL gmagick >= Unknown)

GmagickDraw::ellipse — Dibuja una elipse en la imagen

### Descripción

public function GmagickDraw::ellipse(
float `$ox`,
float `$oy`,
float `$rx`,
float `$ry`,
float `$start`,
float `$end`
): GmagickDraw

Dibuja una elipse en la imagen.

### Parámetros

`ox`
  coordenada x del origen
`oy`
  coordenada y del origen
`rx`
  radio en x
`ry`
  radio en y
`start`
  inicio de rotación en grados
`end`
  final de rotación en grados

### Valores devueltos

El objeto GmagickDraw si se tuvo éxito

# GmagickDraw::getfillcolor

(PECL gmagick >= Unknown)

GmagickDraw::getfillcolor — Devuelve el color de relleno

### Descripción

public function GmagickDraw::getfillcolor(): GmagickPixel

Devuelve el color de relleno usado cuando se dibujan objetos rellenos.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El color de relleno de GmagickPixel usado para dibujar objetos rellenos.

# GmagickDraw::getfillopacity

(PECL gmagick >= Unknown)

GmagickDraw::getfillopacity — Devuelve la opacidad usada cuando se dibuja

### Descripción

public function GmagickDraw::getfillopacity(): float

Devuelve la opacidad usada cuando se dibuja

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la opacidad usada cuando se dibuja utilizando el color de relleno o la textura de relleno. Completamente opaco es 1.0.

# GmagickDraw::getfont

(PECL gmagick >= Unknown)

GmagickDraw::getfont — Devuelve el tipo de letra

### Descripción

public function GmagickDraw::getfont(): mixed

Devuelve una cadena que especifica el tipo de letra usado cuando se anota texto.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una cadena si se tuvo éxito y `false` si no está establecido ningún tipo de letra.

# GmagickDraw::getfontsize

(PECL gmagick >= Unknown)

GmagickDraw::getfontsize — Devuelve el tamaño de punto de la fuente

### Descripción

public function GmagickDraw::getfontsize(): float

Devuelve el tamaño de punto de la fuente usado cuando se anota texto.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el tamaño de la fuente asociada con el objeto GmagickDraw actual.

# GmagickDraw::getfontstyle

(PECL gmagick >= Unknown)

GmagickDraw::getfontstyle — Devuelve el estilo de fuente

### Descripción

public function GmagickDraw::getfontstyle(): int

Devuelve el estilo de fuente usado cuando se anota texto.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la constante de estilo de fuente (STYLE_) asociada con el objeto GmagickDraw o `0` si no está establecido ningún estilo.

# GmagickDraw::getfontweight

(PECL gmagick >= Unknown)

GmagickDraw::getfontweight — Devuelve el peso de la fuente

### Descripción

public function GmagickDraw::getfontweight(): int

Devuelve el peso de la fuente usada cuando se anota texto.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un valor de tipo int si se tuvo éxito y 0 si no está establecido el peso.

# GmagickDraw::getstrokecolor

(PECL gmagick >= Unknown)

GmagickDraw::getstrokecolor — Devuelve el color usado para contornear perfiles de objetos

### Descripción

public function GmagickDraw::getstrokecolor(): GmagickPixel

Devuelve el color usado para contornear perfiles de objetos.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un objeto GmagickPixel que describe el color.

# GmagickDraw::getstrokeopacity

(PECL gmagick >= Unknown)

GmagickDraw::getstrokeopacity — Devuelve la opacidad de los perfiles del objeto contorneado

### Descripción

public function GmagickDraw::getstrokeopacity(): float

Devuelve la opacidad de los perfiles del objeto contorneado.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un valor de float que describe la opacidad.

# GmagickDraw::getstrokewidth

(PECL gmagick >= Unknown)

GmagickDraw::getstrokewidth — Devuelve el ancho del contorno usado para dibular perfiles del objeto

### Descripción

public function GmagickDraw::getstrokewidth(): float

Devuelve el ancho del contorno usado para dibular perfiles del objeto.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un valor de float que describe el ancho del contorno.

# GmagickDraw::gettextdecoration

(PECL gmagick >= Unknown)

GmagickDraw::gettextdecoration — Devuelve la decoración del texto

### Descripción

public function GmagickDraw::gettextdecoration(): int

Devuelve la decoración aplicada cuando se anota texto.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una de las constantes DECORATION_ y 0 si no está establecida la decoración.

# GmagickDraw::gettextencoding

(PECL gmagick >= Unknown)

GmagickDraw::gettextencoding — Devuelve el conjunto de codificación usado para anotaciones de texto

### Descripción

public function GmagickDraw::gettextencoding(): mixed

Devuelve una cadena que especifica el conjunto de codificación usado para anotaciones de texto.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una cadena que especifica el conjunto de codificación o `false` si no está establecida ningúna codificación.

# GmagickDraw::line

(PECL gmagick >= Unknown)

GmagickDraw::line — Dibuja una línea

### Descripción

public function GmagickDraw::line(
float `$sx`,
float `$sy`,
float `$ex`,
float `$ey`
): GmagickDraw

Dibuja una línea en la imagen usando el color del contorno, la opacidad del contorno, y el ancho del contorno acutales.

### Parámetros

`sx`
  coordenada x de inicio
`sy`
  coordenada y de inicio
`ex`
  coordenada x final
`ey`
  coordenada y final

### Valores devueltos

El objeto GmagickDraw si se tuvo éxito

# GmagickDraw::point

(PECL gmagick >= Unknown)

GmagickDraw::point — Dibuja un punto

### Descripción

public function GmagickDraw::point(float `$x`, float `$y`): GmagickDraw

Dibuja un punto usando el color de contorno y el grosor de contorno actuales en las coordenadas especificadas.

### Parámetros

`x`
  coordenada x del objetivo
`y`
  coordenada y del objetivo

### Valores devueltos

El objeto GmagickDraw si se tuvo éxito

# GmagickDraw::polygon

(PECL gmagick >= Unknown)

GmagickDraw::polygon — Dibuja un polígono

### Descripción

public function GmagickDraw::polygon(array `$coordinates`): GmagickDraw

Dibuja un polígono usando el contorno, el ancho del contorno, y el color o textura de relleno actuales, usando la matriz de coordenadas especificadas.

### Parámetros

`coordinates`
  matriz de coordenadas

### Valores devueltos

El objeto GmagickDraw si se tuvo éxito

# GmagickDraw::polyline

(PECL gmagick >= Unknown)

GmagickDraw::polyline — Dibuja una polilínea

### Descripción

public function GmagickDraw::polyline(array `$coordinate_array`): GmagickDraw

Dibuja una polilínea usando el contorno, el ancho del contorno, y el color o textura de relleno actuales, usando la matriz de coordenadas especificadas.

### Parámetros

`coordinate_array`
  La matriz de coordenadas.

### Valores devueltos

El objeto GmagickDraw si se tuvo éxito

# GmagickDraw::rectangle

(PECL gmagick >= Unknown)

GmagickDraw::rectangle — Dibuja un rectángulo

### Descripción

public function GmagickDraw::rectangle(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`
): GmagickDraw

Dibuja un rectángulo dadas dos coordenadas y usando el contorno, el ancho del contorno, y la configuración de relleno actuales.

### Parámetros

`x1`
  primera coordenada x
`y1`
  primera coordenada y
`x2`
  segunda coordenada x
`y2`
  primera coordenada y

### Valores devueltos

El objeto GmagickDraw si se tuvo éxito

# GmagickDraw::rotate

(PECL gmagick >= Unknown)

GmagickDraw::rotate — Aplica la rotación especificada al espacio de coordenadas actual

### Descripción

public function GmagickDraw::rotate(float `$degrees`): GmagickDraw

Aplica la rotación especificada al espacio de coordenadas actual.

### Parámetros

`degrees`
  grados de rotación

### Valores devueltos

El objeto GmagickDraw si se tuvo éxito

# GmagickDraw::roundrectangle

(PECL gmagick >= Unknown)

GmagickDraw::roundrectangle — Dibuja un rectángulo redondeado

### Descripción

public function GmagickDraw::roundrectangle(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$rx`,
float `$ry`
): GmagickDraw

Dibuja aun rectángulo redondeado dadas dos coordenadas, los radios de las esquinas x e y, y usando el contorno, el ancho del contorno, y la configuración de relleno actuales.

### Parámetros

`x1`
  primera coordenada x
`y1`
  primera coordenada y
`x2`
  segunda coordenada x
`y2`
  segunda coordenada y
`rx`
  radio de la esquina en dirección horizontal
`ry`
  radio de la esquina en dirección vertical

### Valores devueltos

El objeto GmagickDraw si se tuvo éxito

# GmagickDraw::scale

(PECL gmagick >= Unknown)

GmagickDraw::scale — Ajusta el factor de escala

### Descripción

public function GmagickDraw::scale(float `$x`, float `$y`): GmagickDraw

Ajusta el factor de escala a aplicar en las direcciones horizontal y vertical al espacio de coordenadas actual.

### Parámetros

`x`
  Factor de escala horizontal
`y`
  Factor de escala vertical

### Valores devueltos

El objeto GmagickDraw si se tuvo éxito

# GmagickDraw::setfillcolor

(PECL gmagick >= Unknown)

GmagickDraw::setfillcolor — Establece el color de relleno a usar cuando se dibujan objetos rellenos

### Descripción

public function GmagickDraw::setfillcolor(mixed `$color`): GmagickDraw

Establece el color de relleno a usar cuando se dibujan objetos rellenos.

### Parámetros

`color`
  Un objeto GmagickPixel o un string que indica el color a usar para el relleno.

### Valores devueltos

El objeto GmagickDraw si se tuvo éxito

# GmagickDraw::setfillopacity

(PECL gmagick >= Unknown)

GmagickDraw::setfillopacity — Establece la opacidad del relleno

### Descripción

public function GmagickDraw::setfillopacity(float `$fill_opacity`): GmagickDraw

Establece la opacidad a usar cuando de dibuja untilizando el color de relleno o la textura de relleno. Establecerlo a 1.0 hará al relleno completamente opaco.

### Parámetros

`fill_opacity`
  La opacidad del relleno

### Valores devueltos

El objeto GmagickDraw si se tuvo éxito

# GmagickDraw::setfont

(PECL gmagick >= Unknown)

GmagickDraw::setfont — Establece la fuente especificada completamente a usar cuando se anota texto

### Descripción

public function GmagickDraw::setfont(string `$font`): GmagickDraw

Establece la fuente especificada completamente a usar cuando se anota texto.

### Parámetros

`font`
  El nombre de la fuente

### Valores devueltos

El objeto GmagickDraw si se tuvo éxito

# GmagickDraw::setfontsize

(PECL gmagick >= Unknown)

GmagickDraw::setfontsize — Establece el tamaño de punto de la fuente a usar cuando se anota texto

### Descripción

public function GmagickDraw::setfontsize(float `$pointsize`): GmagickDraw

Establece el tamaño de punto de la fuente a usar cuando se anota texto.

### Parámetros

`pointsize`
  El tamaño de punto del texto

### Valores devueltos

El objeto GmagickDraw si se tuvo éxito

# GmagickDraw::setfontstyle

(PECL gmagick >= Unknown)

GmagickDraw::setfontstyle — Establece el estilo de fuente a usar cuando se anota texto

### Descripción

public function GmagickDraw::setfontstyle(int `$style`): GmagickDraw

Establece el estilo de fuente a usar cuando se anota texto. La enumeración AnyStyle actúa como una opción comodín para "no tener cuidado".

### Parámetros

`style`
  El estilo de la fuente (NormalStyle, ItalicStyle, ObliqueStyle, AnyStyle)

### Valores devueltos

El objeto GmagickDraw si se tuvo éxito

# GmagickDraw::setfontweight

(PECL gmagick >= Unknown)

GmagickDraw::setfontweight — Establece el peso de la fuente

### Descripción

public function GmagickDraw::setfontweight(int `$weight`): GmagickDraw

Establece el peso de la fuente a usar cuando se anota texto.

### Parámetros

`weight`
  El peso de la fuente (rango válido 100-900)

### Valores devueltos

El objeto GmagickDraw si se tuvo éxito

# GmagickDraw::setstrokecolor

(PECL gmagick >= Unknown)

GmagickDraw::setstrokecolor — Establece el color usado para contornear los perfiles del objeto

### Descripción

public function GmagickDraw::setstrokecolor(mixed `$color`): GmagickDraw

Establece el color usado para contornear los perfiles del objeto.

### Parámetros

`color`
  Un objeto GmagickPixel o un string que representa el color del contorno.

### Valores devueltos

El objeto GmagickDraw si se tuvo éxito

# GmagickDraw::setstrokeopacity

(PECL gmagick >= Unknown)

GmagickDraw::setstrokeopacity — Especifica la opacidad del los perfiles del objeto contorneado

### Descripción

public function GmagickDraw::setstrokeopacity(float `$stroke_opacity`): GmagickDraw

Especifica la opacidad del los perfiles del objeto contorneado.

### Parámetros

`stroke_opacity`
  La opacidad del contorno. El valor 1.0 es opaco.

### Valores devueltos

El objeto GmagickDraw si se tuvo éxito

# GmagickDraw::setstrokewidth

(PECL gmagick >= Unknown)

GmagickDraw::setstrokewidth — Establece el ancho del contorno usado para dibujar los perfiles del objeto.

### Descripción

public function GmagickDraw::setstrokewidth(float `$width`): GmagickDraw

Establece el ancho del contorno usado para dibujar los perfiles del objeto

### Parámetros

`width`
  El ancho del contorno

### Valores devueltos

El objeto GmagickDraw si se tuvo éxito

# GmagickDraw::settextdecoration

(PECL gmagick >= Unknown)

GmagickDraw::settextdecoration — Especifica una decoración

### Descripción

public function GmagickDraw::settextdecoration(int `$decoration`): GmagickDraw

Especifica una decoración que va a ser aplicada cuando se anota texto.

### Parámetros

`int`
  Decoración del texto. Una de estas: NoDecoration, UnderlineDecoration, OverlineDecoration, o LineThroughDecoration

### Valores devueltos

El objeto GmagickDraw si se tuvo éxito

# GmagickDraw::settextencoding

(PECL gmagick >= Unknown)

GmagickDraw::settextencoding — Especifica el conjunto de codificación del texto

### Descripción

public function GmagickDraw::settextencoding(string `$encoding`): GmagickDraw

Especifica el conjunto de codificación usado para anotaciones el texto. La única codificación de caracteres que se puede especificar por ahora es "UTF-8" para representar Unicode como una secuencia de bytes. Especifique un string vacío para establecer la codificación de texto a la predeterminada por el sistema. El éxito con la anotación de texto usando Unicode puede requerir fuentes diseñadas para soportar Unicode.

### Parámetros

`encoding`
  Cadena de caracteres que especifica la codificación de texto

### Valores devueltos

El objeto GmagickDraw en caso de éxito

## Tabla de contenidos

- GmagickDraw::annotate — Dibuja texto en la imagen
- GmagickDraw::arc — Dibuja un arco
- GmagickDraw::bezier — Dibuja una curva Bézier
- GmagickDraw::ellipse — Dibuja una elipse en la imagen
- GmagickDraw::getfillcolor — Devuelve el color de relleno
- GmagickDraw::getfillopacity — Devuelve la opacidad usada cuando se dibuja
- GmagickDraw::getfont — Devuelve el tipo de letra
- GmagickDraw::getfontsize — Devuelve el tamaño de punto de la fuente
- GmagickDraw::getfontstyle — Devuelve el estilo de fuente
- GmagickDraw::getfontweight — Devuelve el peso de la fuente
- GmagickDraw::getstrokecolor — Devuelve el color usado para contornear perfiles de objetos
- GmagickDraw::getstrokeopacity — Devuelve la opacidad de los perfiles del objeto contorneado
- GmagickDraw::getstrokewidth — Devuelve el ancho del contorno usado para dibular perfiles del objeto
- GmagickDraw::gettextdecoration — Devuelve la decoración del texto
- GmagickDraw::gettextencoding — Devuelve el conjunto de codificación usado para anotaciones de texto
- GmagickDraw::line — Dibuja una línea
- GmagickDraw::point — Dibuja un punto
- GmagickDraw::polygon — Dibuja un polígono
- GmagickDraw::polyline — Dibuja una polilínea
- GmagickDraw::rectangle — Dibuja un rectángulo
- GmagickDraw::rotate — Aplica la rotación especificada al espacio de coordenadas actual
- GmagickDraw::roundrectangle — Dibuja un rectángulo redondeado
- GmagickDraw::scale — Ajusta el factor de escala
- GmagickDraw::setfillcolor — Establece el color de relleno a usar cuando se dibujan objetos rellenos
- GmagickDraw::setfillopacity — Establece la opacidad del relleno
- GmagickDraw::setfont — Establece la fuente especificada completamente a usar cuando se anota texto
- GmagickDraw::setfontsize — Establece el tamaño de punto de la fuente a usar cuando se anota texto
- GmagickDraw::setfontstyle — Establece el estilo de fuente a usar cuando se anota texto
- GmagickDraw::setfontweight — Establece el peso de la fuente
- GmagickDraw::setstrokecolor — Establece el color usado para contornear los perfiles del objeto
- GmagickDraw::setstrokeopacity — Especifica la opacidad del los perfiles del objeto contorneado
- GmagickDraw::setstrokewidth — Establece el ancho del contorno usado para dibujar los perfiles del objeto.
- GmagickDraw::settextdecoration — Especifica una decoración
- GmagickDraw::settextencoding — Especifica el conjunto de codificación del texto

# La clase GmagickPixel

(PECL gmagick >= Unknown)

## Introducción

## Sinopsis de la Clase

class GmagickPixel {
/* Métodos */
public function __construct(string `$color` = ?)
public function getcolor(bool `$as_array` = `false`, bool `$normalize_array` = `false`): mixed
public function getcolorcount(): int
public function getcolorvalue(int `$color`): float
public function setcolor(string `$color`): GmagickPixel
public function setcolorvalue(int `$color`, float `$value`): GmagickPixel
}

# GmagickPixel::__construct

(PECL gmagick >= Unknown)

GmagickPixel::__construct — El constructor GmagickPixel

### Descripción

public function GmagickPixel::__construct(string `$color` = ?)

Construye un nuevo objeto GmagickPixel. Si se especifica un color, el objeto es construido y luego inicializado utilizando este color antes de ser devuelto.

### Parámetros

`color`
  El color a utilizar como valor inicial de este objeto (opcional).

# GmagickPixel::getcolor

(PECL gmagick >= Unknown)

GmagickPixel::getcolor — Devuelve el color

### Descripción

public function GmagickPixel::getcolor(bool `$as_array` = `false`, bool `$normalize_array` = `false`): mixed

Devuelve el color descrito por el objeto GmagickPixel, en forma de string o un array. Si el color tiene un canal de opacidad definido, este será especificado como cuarto valor de la lista.

### Parámetros

`as_array`
  `true` para indicar que el valor devuelto debe ser un array en lugar de una string.
`normalize_array`
  `true` para normalizar los valores de color.

### Valores devueltos

Una string o un array de valores de canales, cada uno normalizado si `true` es proporcionado para `normalize_array`. Emite una excepción GmagickPixelException en caso de error.

# GmagickPixel::getcolorcount

(PECL gmagick >= Unknown)

GmagickPixel::getcolorcount — Devuelve el número de colores asociados con este color

### Descripción

public function GmagickPixel::getcolorcount(): int

Devuelve el número de colores asociados con este color.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de colores, en forma de un integer en caso de éxito, y lanza una excepción GmagickPixelException si ocurre un error.

# GmagickPixel::getcolorvalue

(PECL gmagick >= Unknown)

GmagickPixel::getcolorvalue — Obtiene el valor normalizado del canal de color proporcionado

### Descripción

public function GmagickPixel::getcolorvalue(int `$color`): float

Obtiene el valor normalizado del canal de color proporcionado, en forma de número de punto flotante comprendido entre 0 y 1.

### Parámetros

`color`
  El canal a verificar, especificado en forma de una de las constantes de canal Gmagick.

### Valores devueltos

El valor del canal, en forma de número de punto flotante normalizado, y emite una excepción GmagickPixelException en caso de error.

# GmagickPixel::setcolor

(PECL gmagick >= Unknown)

GmagickPixel::setcolor — Define la color

### Descripción

public function GmagickPixel::setcolor(string `$color`): GmagickPixel

Define la color descrita por el objeto GmagickPixel, con una string (i.e. "blue", "#0000ff", "rgb(0,0,255)", "cmyk(100,100,100,10)", etc.).

### Parámetros

`color`
  La definición de la color a utilizar para inicializar el objeto GmagickPixel.

### Valores devueltos

El objeto GmagickPixel en caso de éxito.

# GmagickPixel::setcolorvalue

(PECL gmagick >= Unknown)

GmagickPixel::setcolorvalue — Establece el valor normalizado de uno de los canales

### Descripción

public function GmagickPixel::setcolorvalue(int `$color`, float `$value`): GmagickPixel

Establece el valor del canal especificado de este objeto al valor proporcionado, el cuál debería estar entre 0 y 1. Esta función se puede usar para proporcionar un canal de opacidad al objeto GmagickPixel.

### Parámetros

`color`
  Una de las constantes de color de canal de Gmagick.
`value`
  El valor para establecer este canal tiene un rango desde 0 a 1.

### Valores devueltos

El objeto GmagickPixel si se tuvo éxtio.

## Tabla de contenidos

- GmagickPixel::__construct — El constructor GmagickPixel
- GmagickPixel::getcolor — Devuelve el color
- GmagickPixel::getcolorcount — Devuelve el número de colores asociados con este color
- GmagickPixel::getcolorvalue — Obtiene el valor normalizado del canal de color proporcionado
- GmagickPixel::setcolor — Define la color
- GmagickPixel::setcolorvalue — Establece el valor normalizado de uno de los canales

- Instalación/Configuración
  - Requerimientos
  - Instalación
- Constantes predefinidas
- Ejemplos
- Gmagick — La clase Gmagick
  - Gmagick::addimage — Añade una nueva imagen a la lista de imágenes del objeto Gmagick
  - Gmagick::addnoiseimage — Añade ruido aleatorio a la imagen
  - Gmagick::annotateimage — Anota una imagen con texto
  - Gmagick::blurimage — Añade un filtro de borrosidad a la imagen
  - Gmagick::borderimage — Rodea la imagen con un borde
  - Gmagick::charcoalimage — Simula un dibujo a carboncillo
  - Gmagick::chopimage — Elimina una región de una imagen y la recorta
  - Gmagick::clear — Limpia todos los recursos asociados con el objeto Gmagick
  - Gmagick::commentimage — Añade un comentario a una imagen
  - Gmagick::compositeimage — Compone una imagen en otra
  - Gmagick::__construct — El constructor Gmagick
  - Gmagick::cropimage — Extrae una región de la imagen
  - Gmagick::cropthumbnailimage — Crea una miniatura recortada
  - Gmagick::current — Devuelve la refencia al objeto Gmagick acutal
  - Gmagick::cyclecolormapimage — Desplaza un mapa de color de una imagen
  - Gmagick::deconstructimages — Devuelve ciertas diferencias de píxeles entre imágenes
  - Gmagick::despeckleimage — Reduce el ruido granular de una imagen
  - Gmagick::destroy — Destruye un objeto Gmagick
  - Gmagick::drawimage — Renderiza el objeto GmagickDraw en la imagen actual
  - Gmagick::edgeimage — Mejora los bordes dentro de una imagen
  - Gmagick::embossimage — Devuelve una imagen en escala de grises con un efecto tridimensional
  - Gmagick::enhanceimage — Mejora la calidad de una imagen con ruido
  - Gmagick::equalizeimage — Ecualiza el histograma de la imagen
  - Gmagick::flipimage — Crea una imagen espejo vertical
  - Gmagick::flopimage — Crea una imagen espejo horizontal
  - Gmagick::frameimage — Añade un borde tridimensional simulado
  - Gmagick::gammaimage — Corrección gamma de una imagen
  - Gmagick::getcopyright — Devuelve el copyright de la API GraphicsMagick como una cadena
  - Gmagick::getfilename — El nombre de archivo asociado a una secuencia de imágenes
  - Gmagick::getimagebackgroundcolor — Devuelve el color de fondo de la imagen
  - Gmagick::getimageblueprimary — Devuelve el punto primario azul de la cromaticidad
  - Gmagick::getimagebordercolor — Devuelve el color del borde de la imagen
  - Gmagick::getimagechanneldepth — Obtiene la profundidad de un canal de imagen en particular
  - Gmagick::getimagecolors — Devuelve el color del índice del mapa de color especificado
  - Gmagick::getimagecolorspace — Obtiene el espacio de colores de la imagen
  - Gmagick::getimagecompose — Devuelve el operador de composición asociado a la imagen
  - Gmagick::getimagedelay — Obetiene el retraso de la imagen
  - Gmagick::getimagedepth — Obtiene la profundidad de la imagen
  - Gmagick::getimagedispose — Obtiene el método de disposición de la imagen
  - Gmagick::getimageextrema — Obtiene los extremos de la imagen
  - Gmagick::getimagefilename — Devuelve el nombre de archivo de una imagen en particular de una secuencia
  - Gmagick::getimageformat — Devuelve el formato de una imagen en particular de una secuencia
  - Gmagick::getimagegamma — Obtiene el valor gamma de la imagen
  - Gmagick::getimagegreenprimary — Devuelve el punto primario verde de la cromaticidad
  - Gmagick::getimageheight — Devuelve el alto de la imagen
  - Gmagick::getimagehistogram — Obtiene el histograma de la imagen
  - Gmagick::getimageindex — Obtiene el índice de la imagen activa actual
  - Gmagick::getimageinterlacescheme — Obtiene la combinación de entrelazado de la imagen
  - Gmagick::getimageiterations — Obtiene las iteraciones de la imagen
  - Gmagick::getimagematte — Comprobar si la imagen tiene un canal mate
  - Gmagick::getimagemattecolor — Devuelve el color mate de la imagen
  - Gmagick::getimageprofile — Devuelve el perfil nominado de la imagen
  - Gmagick::getimageredprimary — Devuelve el punto primario rojo de la cromaticidad
  - Gmagick::getimagerenderingintent — Obtiene la propuesta de renderización de la imagen
  - Gmagick::getimageresolution — Obtiene la resolución X e Y de la imagen
  - Gmagick::getimagescene — Obtiene la escena de la imagen
  - Gmagick::getimagesignature — Genera un resumen de un mensaje SHA-256
  - Gmagick::getimagetype — Obtiene el tipo de imagen potencial
  - Gmagick::getimageunits — Obtiene las unidades de resolución de la imagen
  - Gmagick::getimagewhitepoint — Devuelve el punto blanco de la cromaticidad
  - Gmagick::getimagewidth — Devuelve el ancho de la imagen
  - Gmagick::getpackagename — Devuelve el nombre del paquete de GraphicsMagick
  - Gmagick::getquantumdepth — Obtiene la profundidad de la cuantía de Gmagick como una cadena
  - Gmagick::getreleasedate — Devuelve la fecha de distribución de GraphicsMagick como una cadena
  - Gmagick::getsamplingfactors — Obtiene el factor de muestreo horizontal y vertical
  - Gmagick::getsize — Devuelve el tamaño asociado con el objeto Gmagick
  - Gmagick::getversion — Devuelve la versión de la API GraphicsMagick
  - Gmagick::hasnextimage — Comprueba si el objeto tiene más imágenes
  - Gmagick::haspreviousimage — Verifica si el objeto tiene una imagen previa
  - Gmagick::implodeimage — Crea una nueva imagen como una copia
  - Gmagick::labelimage — Añade una etiqueta a una imagen
  - Gmagick::levelimage — Ajusta los niveles de la imagen
  - Gmagick::magnifyimage — Redimensiona una imagen por 2 manteniendo las proporciones
  - Gmagick::mapimage — Sustituye los colores de una imagen por los colores más cercanos de una imagen de referencia
  - Gmagick::medianfilterimage — Aplica un filtro digital
  - Gmagick::minifyimage — Reduce una imagen a la mitad manteniendo las proporciones
  - Gmagick::modulateimage — Controla la luminosidad, la saturación y el tono
  - Gmagick::motionblurimage — Simula un desenfoque cinético
  - Gmagick::newimage — Crea una nueva imagen
  - Gmagick::nextimage — Se desplaza a la imagen siguiente
  - Gmagick::normalizeimage — Mejora el contraste del color de la imagen
  - Gmagick::oilpaintimage — Simula una pintura al óleo
  - Gmagick::previousimage — Moverse a la imagen previa del objeto
  - Gmagick::profileimage — Añade o elimina un perfil de una imagen
  - Gmagick::quantizeimage — Analiza los colores dentro de una imagen de referencia
  - Gmagick::quantizeimages — Analiza los colores dentro de una secuencia de imágenes
  - Gmagick::queryfontmetrics — Devuelve una matriz que representa las métricas de la fuente
  - Gmagick::queryfonts — Devuelve las fuentes configuradas
  - Gmagick::queryformats — Devuelve los formatos soportados por Gmagick
  - Gmagick::radialblurimage — Desenfoca una imagen siguiendo un radio
  - Gmagick::raiseimage — Crea un botón con un efecto 3D
  - Gmagick::read — Lee una imagen desde un fichero
  - Gmagick::readimage — Lee una imagen desde un fichero
  - Gmagick::readimageblob — Lee una imagen desde una cadena binaria
  - Gmagick::readimagefile — El propósito de readimagefile
  - Gmagick::reducenoiseimage — Suaviza los contornos de la imagen
  - Gmagick::removeimage — Elimina una imagen de la lista de imágenes
  - Gmagick::removeimageprofile — Elimina el perfil nombrado de la imagen y lo devuelve
  - Gmagick::resampleimage — Re-muestrea la imagen a la resolución deseada
  - Gmagick::resizeimage — Redimensiona una imagen
  - Gmagick::rollimage — Compensa una imagen
  - Gmagick::rotateimage — Rota una imagen
  - Gmagick::scaleimage — Redimensiona una imagen
  - Gmagick::separateimagechannel — Separa un canal de una imagen
  - Gmagick::setCompressionQuality — Define la calidad de compresión por defecto del objeto
  - Gmagick::setfilename — Define el nombre de archivo antes de leer o escribir una imagen
  - Gmagick::setimagebackgroundcolor — Define la color de fondo de la imagen
  - Gmagick::setimageblueprimary — Define el punto azul primario de la imagen cromática
  - Gmagick::setimagebordercolor — Define la color de la frontera de la imagen
  - Gmagick::setimagechanneldepth — Define la profundidad de un canal particular de la imagen
  - Gmagick::setimagecolorspace — Define el espacio de colores de la imagen
  - Gmagick::setimagecompose — Establece el operador de composción de una imagen
  - Gmagick::setimagedelay — Define el retraso de la imagen
  - Gmagick::setimagedepth — Define la profundidad de la imagen
  - Gmagick::setimagedispose — Define el método de disposición de la imagen
  - Gmagick::setimagefilename — Define el nombre del fichero para una imagen particular de una secuencia
  - Gmagick::setimageformat — Define el formato de una imagen
  - Gmagick::setimagegamma — Define el gamma de la imagen
  - Gmagick::setimagegreenprimary — Define el punto verde en la imagen cromática primaria
  - Gmagick::setimageindex — Establece el iterador en la posición especificada en la lista de imágenes apuntada por su índice
  - Gmagick::setimageinterlacescheme — Define el esquema de entrelazado de la imagen
  - Gmagick::setimageiterations — Define las iteraciones de la imagen
  - Gmagick::setimageprofile — Añade un perfil nombrado al objeto Gmagick
  - Gmagick::setimageredprimary — Define el punto rojo en la imagen cromática primaria
  - Gmagick::setimagerenderingintent — Define la imagen de renderizado
  - Gmagick::setimageresolution — Establece la resolución de la imagen
  - Gmagick::setimagescene — Define la imagen de escena
  - Gmagick::setimagetype — Define el tipo de la imagen
  - Gmagick::setimageunits — Define las unidades a utilizar para la resolución de la imagen
  - Gmagick::setimagewhitepoint — Define el punto blanco en la imagen cromática primaria
  - Gmagick::setsamplingfactors — Define los factores de muestreo de la imagen
  - Gmagick::setsize — Define el tamaño del objeto Gmagick
  - Gmagick::shearimage — Crea un paralelogramo
  - Gmagick::solarizeimage — Aplica un efecto de solarización a la imagen
  - Gmagick::spreadimage — Desplaza aleatoriamente cada píxel de un bloque
  - Gmagick::stripimage — Elimina de una imagen todos los perfiles y todos los comentarios
  - Gmagick::swirlimage — Remue los píxeles del centro de la imagen
  - Gmagick::thumbnailimage — Modifica el tamaño de una imagen
  - Gmagick::trimimage — Elimina los bordes de la imagen
  - Gmagick::write — Alias de Gmagick::writeimage
  - Gmagick::writeimage — Escribe una imagen en un archivo
- GmagickDraw — La clase GmagickDraw
  - GmagickDraw::annotate — Dibuja texto en la imagen
  - GmagickDraw::arc — Dibuja un arco
  - GmagickDraw::bezier — Dibuja una curva Bézier
  - GmagickDraw::ellipse — Dibuja una elipse en la imagen
  - GmagickDraw::getfillcolor — Devuelve el color de relleno
  - GmagickDraw::getfillopacity — Devuelve la opacidad usada cuando se dibuja
  - GmagickDraw::getfont — Devuelve el tipo de letra
  - GmagickDraw::getfontsize — Devuelve el tamaño de punto de la fuente
  - GmagickDraw::getfontstyle — Devuelve el estilo de fuente
  - GmagickDraw::getfontweight — Devuelve el peso de la fuente
  - GmagickDraw::getstrokecolor — Devuelve el color usado para contornear perfiles de objetos
  - GmagickDraw::getstrokeopacity — Devuelve la opacidad de los perfiles del objeto contorneado
  - GmagickDraw::getstrokewidth — Devuelve el ancho del contorno usado para dibular perfiles del objeto
  - GmagickDraw::gettextdecoration — Devuelve la decoración del texto
  - GmagickDraw::gettextencoding — Devuelve el conjunto de codificación usado para anotaciones de texto
  - GmagickDraw::line — Dibuja una línea
  - GmagickDraw::point — Dibuja un punto
  - GmagickDraw::polygon — Dibuja un polígono
  - GmagickDraw::polyline — Dibuja una polilínea
  - GmagickDraw::rectangle — Dibuja un rectángulo
  - GmagickDraw::rotate — Aplica la rotación especificada al espacio de coordenadas actual
  - GmagickDraw::roundrectangle — Dibuja un rectángulo redondeado
  - GmagickDraw::scale — Ajusta el factor de escala
  - GmagickDraw::setfillcolor — Establece el color de relleno a usar cuando se dibujan objetos rellenos
  - GmagickDraw::setfillopacity — Establece la opacidad del relleno
  - GmagickDraw::setfont — Establece la fuente especificada completamente a usar cuando se anota texto
  - GmagickDraw::setfontsize — Establece el tamaño de punto de la fuente a usar cuando se anota texto
  - GmagickDraw::setfontstyle — Establece el estilo de fuente a usar cuando se anota texto
  - GmagickDraw::setfontweight — Establece el peso de la fuente
  - GmagickDraw::setstrokecolor — Establece el color usado para contornear los perfiles del objeto
  - GmagickDraw::setstrokeopacity — Especifica la opacidad del los perfiles del objeto contorneado
  - GmagickDraw::setstrokewidth — Establece el ancho del contorno usado para dibujar los perfiles del objeto.
  - GmagickDraw::settextdecoration — Especifica una decoración
  - GmagickDraw::settextencoding — Especifica el conjunto de codificación del texto
- GmagickPixel — La clase GmagickPixel
  - GmagickPixel::__construct — El constructor GmagickPixel
  - GmagickPixel::getcolor — Devuelve el color
  - GmagickPixel::getcolorcount — Devuelve el número de colores asociados con este color
  - GmagickPixel::getcolorvalue — Obtiene el valor normalizado del canal de color proporcionado
  - GmagickPixel::setcolor — Define la color
  - GmagickPixel::setcolorvalue — Establece el valor normalizado de uno de los canales

# Tratamiento de imágenes (ImageMagick)

# Introducción

Imagick es una extensión PHP nativa para crear y modificar imágenes, utilizando la API ImageMagick.

## Acerca de ImageMagick

Advertencia

Esta extensión es EXPERIMENTAL. El comportamiento de esta extensión, los nombres de sus funciones, y toda la documentación alrededor de esta extensión puede cambiar sin previo aviso en una próxima versión de PHP. Esta extensión debe ser utilizada bajo su propio riesgo.

ImageMagick es una suite de software que permite la creación, edición y composición de imágenes bitmap. Puede leer, convertir y escribir imágenes en diversos formatos (más de 100) entre los que se incluyen DPX, EXR, GIF, JPEG, JPEG-2000, PDF, PhotoCD, PNG, Postscript, SVG y TIFF.

ImageMagick Studio LLC, una organización sin fines de lucro cuyo objetivo es hacer disponible libremente el software relativo a la manipulación de imágenes.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución

## Requerimientos

## Configuración necesaria para la instalación en plataformas distintas de Windows

Se requiere ImageMagick >= 6.2.4. El número de formatos soportados por Imagick depende totalmente de los soportados por la instalación de ImageMagick. Por ejemplo, Imagemagick necesita ghostscript para realizar las operaciones relativas a los PDF.

## Instalación

Esta extensión » PECL no está integrada en PHP.

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/imagick.

> Nota: El nombre oficial de esta extensión es imagick.

Los usuarios de Windows pueden descargar una DLL preconstruida desde el sitio de PECL : » PECL. Estos paquetes contienen ya la DLL de extensión (php_imagick.dll) que debe ser colocada en el extension_dir. Contienen también las DLL de ImageMagick, que deben ser colocadas en algún lugar del PATH. A partir de Imagick 3.6.0, contienen también archivos de configuración XML en config; para usarlos en lugar de los valores por omisión integrados, deben ser colocados en `%USERPROFILE%/.config/ImageMagick`, o alternativamente en el camino dado por la variable de entorno MAGICK_CONFIGURE_PATH. Consúltense la » Documentación sobre los archivos de configuración de ImageMagick para más detalles.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración de Imagick
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
imagick.locale_fix | `false` | `INI_ALL` | Disponible a partir de 2.1.0
imagick.progress_monitor | `false` | `INI_SYSTEM` | Disponible a partir de Imagick 2.2.2
imagick.skip_version_check | `false` | `INI_SYSTEM` | Disponible a partir de Imagick 3.3.0

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`imagick.locale_fix` bool

  Corrige un error en el dibujo cuando las configuraciones locales utilizan el carácter '`,`' como separadores.

`imagick.progress_monitor` bool

  Se utiliza para activar la supervisión de la progresión de la imagen.

`imagick.skip_version_check` bool

  Cuando Imagick se carga, se verifica el número de versión de ImageMagick utilizado durante la compilación, y se compara con el número de versión actualmente utilizado; se emite una alerta si las dos versiones no coinciden. Esta alerta puede ser eliminada activando esta opción de configuración.

  El uso de una versión de Imagick diferente a la versión de ImageMagick no es recomendado. Aunque esto puede funcionar, puede resultar en errores aleatorios o comportamientos no definidos.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

Constantes `COLOR_*`

Constantes sobre los tipos de color. Estas constantes se utilizan principalmente con la clase ImagickPixel.

`imagick::COLOR_BLACK` (int)
  Color negro
`imagick::COLOR_BLUE` (int)
  Color azul
`imagick::COLOR_CYAN` (int)
  Color cian
`imagick::COLOR_GREEN` (int)
  Color verde
`imagick::COLOR_RED` (int)
  Color rojo
`imagick::COLOR_YELLOW` (int)
  Color amarillo
`imagick::COLOR_MAGENTA` (int)
  Color magenta
`imagick::COLOR_OPACITY` (int)
  Color de la opacidad
`imagick::COLOR_ALPHA` (int)
  Color del alpha
`imagick::COLOR_FUZZ` (int)
  Color del fuzz

Constantes `DISPOSE_*`

Constantes relativas a los tipos de disposición

`imagick::DISPOSE_UNRECOGNIZED` (int)
  Tipo de disposición no reconocido
`imagick::DISPOSE_UNDEFINED` (int)
  Tipo de disposición no definido
`imagick::DISPOSE_NONE` (int)
  Ningún tipo de disposición
`imagick::DISPOSE_BACKGROUND` (int)
  Disposición del fondo
`imagick::DISPOSE_PREVIOUS` (int)
  Disposición previa

Constantes `COMPOSITE_*`
`imagick::COMPOSITE_DEFAULT` (int)
  El operador de composición por defecto.
`imagick::COMPOSITE_UNDEFINED` (int)
  Operador de composición indefinido
`imagick::COMPOSITE_NO` (int)
  No hay operador de composición definido
`imagick::COMPOSITE_ADD` (int)
  El resultado de imagen + imagen
`imagick::COMPOSITE_ATOP` (int)
  El resultado tiene la misma forma que la imagen, con la imagen compuesta que llena la imagen donde la forma de la imagen se superpone a la imagen
`imagick::COMPOSITE_BLEND` (int)
  Combina las imágenes imagen (mezcla)
`imagick::COMPOSITE_BUMPMAP` (int)
  Lo mismo que COMPOSITE_MULTIPLY, excepto que la fuente se convierte primero a niveles de gris
`imagick::COMPOSITE_CLEAR` (int)
  Hace que la imagen de destino sea transparente
`imagick::COMPOSITE_COLORBURN` (int)
  Oscurece la imagen de destino para reflejar la imagen fuente
`imagick::COMPOSITE_COLORDODGE` (int)
  Aclara la imagen de destino para reflejar la imagen fuente
`imagick::COMPOSITE_COLORIZE` (int)
  Colorea la imagen de destino con la imagen compuesta
`imagick::COMPOSITE_COPYBLACK` (int)
  Copia el negro de la fuente al destino
`imagick::COMPOSITE_COPYBLUE` (int)
  Copia el azul de la fuente al destino
`imagick::COMPOSITE_COPY` (int)
  Copia la fuente al destino
`imagick::COMPOSITE_COPYCYAN` (int)
  Copia el cian de la fuente al destino
`imagick::COMPOSITE_COPYGREEN` (int)
  Copia el verde de la fuente al destino
`imagick::COMPOSITE_COPYMAGENTA` (int)
  Copia el magenta de la fuente al destino
`imagick::COMPOSITE_COPYOPACITY` (int)
  Copia la opacidad de la fuente al destino
`imagick::COMPOSITE_COPYRED` (int)
  Copia el rojo de la fuente al destino
`imagick::COMPOSITE_COPYYELLOW` (int)
  Copia el amarillo de la fuente al destino
`imagick::COMPOSITE_DARKEN` (int)
  Oscurece la imagen de destino
`imagick::COMPOSITE_DSTATOP` (int)
  La parte de la imagen de destino que está dentro de la fuente se compone con la fuente y se coloca en el destino.
`imagick::COMPOSITE_DST` (int)
  El destino se deja intacto
`imagick::COMPOSITE_DSTIN` (int)
  La parte dentro de la fuente reemplaza el destino
`imagick::COMPOSITE_DSTOUT` (int)
  La parte fuera de la fuente reemplaza el destino
`imagick::COMPOSITE_DSTOVER` (int)
  El destino reemplaza la fuente
`imagick::COMPOSITE_DIFFERENCE` (int)
  Resta el color oscuro del color claro
`imagick::COMPOSITE_DISPLACE` (int)
  Desplaza los píxeles del destino según lo definido por la fuente
`imagick::COMPOSITE_DISSOLVE` (int)
  Disuelve la fuente en el destino
`imagick::COMPOSITE_EXCLUSION` (int)
  Produce un efecto similar a imagick::COMPOSITE_DIFFERENCE, pero con un contraste más bajo
`imagick::COMPOSITE_HARDLIGHT` (int)
  Multiplica o proyecta los colores, dependiendo del valor del color fuente
`imagick::COMPOSITE_HUE` (int)
  Modifica el matiz del destino, según lo definido por la fuente
`imagick::COMPOSITE_IN` (int)
  Compone la fuente en el destino
`imagick::COMPOSITE_LIGHTEN` (int)
  Aclara el destino, según lo definido por la fuente
`imagick::COMPOSITE_LUMINIZE` (int)
  Ilumina el destino según lo definido por la fuente
`imagick::COMPOSITE_MINUS` (int)
  Resta la fuente del destino
`imagick::COMPOSITE_MODULATE` (int)
  Modula la claridad del destino, su saturación y su matiz según lo definido por el destino
`imagick::COMPOSITE_MULTIPLY` (int)
  Multiplica el destino con la fuente
`imagick::COMPOSITE_OUT` (int)
  Compone el exterior de la fuente en el destino
`imagick::COMPOSITE_OVER` (int)
  Compone la fuente sobre el destino
`imagick::COMPOSITE_OVERLAY` (int)
  Superpone la fuente sobre el destino
`imagick::COMPOSITE_PLUS` (int)
  Añade la fuente sobre el destino
`imagick::COMPOSITE_REPLACE` (int)
  Reemplaza el destino con la fuente
`imagick::COMPOSITE_SATURATE` (int)
  Satura el destino según lo definido por la fuente
`imagick::COMPOSITE_SCREEN` (int)
  La fuente y el destino se complementan, luego se multiplican y finalmente reemplazan el destino
`imagick::COMPOSITE_SOFTLIGHT` (int)
  Oscurece o aclara los colores, según la fuente
`imagick::COMPOSITE_SRCATOP` (int)
  La parte de la fuente que está en el destino y compuesta sobre el destino
`imagick::COMPOSITE_SRC` (int)
  La fuente se copia sobre el destino
`imagick::COMPOSITE_SRCIN` (int)
  La parte de la fuente que está en el destino, reemplaza el destino.
`imagick::COMPOSITE_SRCOUT` (int)
  La parte de la fuente que está fuera del destino reemplaza el destino
`imagick::COMPOSITE_SRCOVER` (int)
  La fuente reemplaza el destino
`imagick::COMPOSITE_SUBTRACT` (int)
  Resta los colores en la fuente en el destino
`imagick::COMPOSITE_THRESHOLD` (int)
  La fuente se compone sobre el destino, según lo definido por los umbrales de la fuente
`imagick::COMPOSITE_XOR` (int)
  La parte de la fuente que está fuera del destino y combinada con la parte del destino que está fuera de la fuente

Constantes `MONTAGEMODE_*`

`imagick::MONTAGEMODE_FRAME` (int)
`imagick::MONTAGEMODE_UNFRAME` (int)
`imagick::MONTAGEMODE_CONCATENATE` (int)

Constantes `STYLE_*`

`imagick::STYLE_NORMAL` (int)
`imagick::STYLE_ITALIC` (int)
`imagick::STYLE_OBLIQUE` (int)
`imagick::STYLE_ANY` (int)

Constantes `FILTER_*`

`imagick::FILTER_UNDEFINED` (int)
`imagick::FILTER_POINT` (int)
`imagick::FILTER_BOX` (int)
`imagick::FILTER_TRIANGLE` (int)
`imagick::FILTER_HERMITE` (int)
`imagick::FILTER_HANNING` (int)
`imagick::FILTER_HAMMING` (int)
`imagick::FILTER_BLACKMAN` (int)
`imagick::FILTER_GAUSSIAN` (int)
`imagick::FILTER_QUADRATIC` (int)
`imagick::FILTER_CUBIC` (int)
`imagick::FILTER_CATROM` (int)
`imagick::FILTER_MITCHELL` (int)
`imagick::FILTER_LANCZOS` (int)
`imagick::FILTER_BESSEL` (int)
`imagick::FILTER_SINC` (int)

Constantes `IMGTYPE_*`

`imagick::IMGTYPE_UNDEFINED` (int)
`imagick::IMGTYPE_BILEVEL` (int)
`imagick::IMGTYPE_GRAYSCALE` (int)
`imagick::IMGTYPE_GRAYSCALEMATTE` (int)
`imagick::IMGTYPE_PALETTE` (int)
`imagick::IMGTYPE_PALETTEMATTE` (int)
`imagick::IMGTYPE_TRUECOLOR` (int)
`imagick::IMGTYPE_TRUECOLORMATTE` (int)
`imagick::IMGTYPE_COLORSEPARATION` (int)
`imagick::IMGTYPE_COLORSEPARATIONMATTE` (int)
`imagick::IMGTYPE_OPTIMIZE` (int)

Constantes `RESOLUTION_*`

`imagick::RESOLUTION_UNDEFINED` (int)
`imagick::RESOLUTION_PIXELSPERINCH` (int)
`imagick::RESOLUTION_PIXELSPERCENTIMETER` (int)

Constantes `COMPRESSION_*`

`imagick::COMPRESSION_UNDEFINED` (int)
`imagick::COMPRESSION_NO` (int)
`imagick::COMPRESSION_BZIP` (int)
`imagick::COMPRESSION_FAX` (int)
`imagick::COMPRESSION_GROUP4` (int)
`imagick::COMPRESSION_JPEG` (int)
`imagick::COMPRESSION_JPEG2000` (int)
`imagick::COMPRESSION_LOSSLESSJPEG` (int)
`imagick::COMPRESSION_LZW` (int)
`imagick::COMPRESSION_RLE` (int)
`imagick::COMPRESSION_ZIP` (int)
`imagick::COMPRESSION_DXT1` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.0 o superior.
`imagick::COMPRESSION_DXT3` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.0 o superior.
`imagick::COMPRESSION_DXT5` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.0 o superior.

Constantes `PAINT_*`

`imagick::PAINT_POINT` (int)
`imagick::PAINT_REPLACE` (int)
`imagick::PAINT_FLOODFILL` (int)
`imagick::PAINT_FILLTOBORDER` (int)
`imagick::PAINT_RESET` (int)

Constantes `GRAVITY_*`

`imagick::GRAVITY_NORTHWEST` (int)
`imagick::GRAVITY_NORTH` (int)
`imagick::GRAVITY_NORTHEAST` (int)
`imagick::GRAVITY_WEST` (int)
`imagick::GRAVITY_CENTER` (int)
`imagick::GRAVITY_EAST` (int)
`imagick::GRAVITY_SOUTHWEST` (int)
`imagick::GRAVITY_SOUTH` (int)
`imagick::GRAVITY_SOUTHEAST` (int)

Constantes `STRETCH_*`

`imagick::STRETCH_NORMAL` (int)
`imagick::STRETCH_ULTRACONDENSED` (int)
`imagick::STRETCH_CONDENSED` (int)
`imagick::STRETCH_SEMICONDENSED` (int)
`imagick::STRETCH_SEMIEXPANDED` (int)
`imagick::STRETCH_EXPANDED` (int)
`imagick::STRETCH_EXTRAEXPANDED` (int)
`imagick::STRETCH_ULTRAEXPANDED` (int)
`imagick::STRETCH_ANY` (int)

Constantes `ALIGN_*`

`imagick::ALIGN_UNDEFINED` (int)
`imagick::ALIGN_LEFT` (int)
`imagick::ALIGN_CENTER` (int)
`imagick::ALIGN_RIGHT` (int)

Constantes `DECORATION_*`

`imagick::DECORATION_NO` (int)
`imagick::DECORATION_UNDERLINE` (int)
`imagick::DECORATION_OVERLINE` (int)
`imagick::DECORATION_LINETROUGH` (int)

Constantes `NOISE_*`

`imagick::NOISE_UNIFORM` (int)
`imagick::NOISE_GAUSSIAN` (int)
`imagick::NOISE_MULTIPLICATIVEGAUSSIAN` (int)
`imagick::NOISE_IMPULSE` (int)
`imagick::NOISE_LAPLACIAN` (int)
`imagick::NOISE_POISSON` (int)
`imagick::NOISE_RANDOM` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.6 o superior.

Constantes `CHANNEL_*`

`imagick::CHANNEL_UNDEFINED` (int)
`imagick::CHANNEL_RED` (int)
`imagick::CHANNEL_GRAY` (int)
`imagick::CHANNEL_CYAN` (int)
`imagick::CHANNEL_GREEN` (int)
`imagick::CHANNEL_MAGENTA` (int)
`imagick::CHANNEL_BLUE` (int)
`imagick::CHANNEL_YELLOW` (int)
`imagick::CHANNEL_ALPHA` (int)
`imagick::CHANNEL_OPACITY` (int)
`imagick::CHANNEL_MATTE` (int)
`imagick::CHANNEL_BLACK` (int)
`imagick::CHANNEL_INDEX` (int)
`imagick::CHANNEL_ALL` (int)
`imagick::CHANNEL_DEFAULT` (int)

Constantes `METRIC_*`

`imagick::METRIC_UNDEFINED` (int)
`imagick::METRIC_MEANABSOLUTEERROR` (int)
`imagick::METRIC_MEANSQUAREERROR` (int)
`imagick::METRIC_PEAKABSOLUTEERROR` (int)
`imagick::METRIC_PEAKSIGNALTONOISERATIO` (int)
`imagick::METRIC_ROOTMEANSQUAREDERROR` (int)

Constantes `PIXEL_*`

`imagick::PIXEL_CHAR` (int)
`imagick::PIXEL_DOUBLE` (int)
`imagick::PIXEL_FLOAT` (int)
`imagick::PIXEL_INTEGER` (int)
  Solo disponible con ImageMagick < 7.
`imagick::PIXEL_LONG` (int)
`imagick::PIXEL_QUANTUM` (int)
`imagick::PIXEL_SHORT` (int)

Constantes `EVALUATE_*`

`imagick::EVALUATE_UNDEFINED` (int)
`imagick::EVALUATE_ADD` (int)
`imagick::EVALUATE_AND` (int)
`imagick::EVALUATE_DIVIDE` (int)
`imagick::EVALUATE_LEFTSHIFT` (int)
`imagick::EVALUATE_MAX` (int)
`imagick::EVALUATE_MIN` (int)
`imagick::EVALUATE_MULTIPLY` (int)
`imagick::EVALUATE_OR` (int)
`imagick::EVALUATE_RIGHTSHIFT` (int)
`imagick::EVALUATE_SET` (int)
`imagick::EVALUATE_SUBTRACT` (int)
`imagick::EVALUATE_XOR` (int)
`imagick::EVALUATE_POW` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.4 o superior.
`imagick::EVALUATE_LOG` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.4 o superior.
`imagick::EVALUATE_THRESHOLD` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.4 o superior.
`imagick::EVALUATE_THRESHOLDBLACK` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.4 o superior.
`imagick::EVALUATE_THRESHOLDWHITE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.4 o superior.
`imagick::EVALUATE_GAUSSIANNOISE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.4 o superior.
`imagick::EVALUATE_IMPULSENOISE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.4 o superior.
`imagick::EVALUATE_LAPLACIANNOISE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.4 o superior.
`imagick::EVALUATE_MULTIPLICATIVENOISE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.4 o superior.
`imagick::EVALUATE_POISSONNOISE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.4 o superior.
`imagick::EVALUATE_UNIFORMNOISE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.4 o superior.
`imagick::EVALUATE_COSINE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.4 o superior.
`imagick::EVALUATE_SINE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.4 o superior.
`imagick::EVALUATE_ADDMODULUS` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.4 o superior.

Constantes `COLORSPACE_*`

`imagick::COLORSPACE_UNDEFINED` (int)
`imagick::COLORSPACE_RGB` (int)
`imagick::COLORSPACE_GRAY` (int)
`imagick::COLORSPACE_TRANSPARENT` (int)
`imagick::COLORSPACE_OHTA` (int)
`imagick::COLORSPACE_LAB` (int)
`imagick::COLORSPACE_XYZ` (int)
`imagick::COLORSPACE_YCBCR` (int)
`imagick::COLORSPACE_YCC` (int)
`imagick::COLORSPACE_YIQ` (int)
`imagick::COLORSPACE_YPBPR` (int)
`imagick::COLORSPACE_YUV` (int)
`imagick::COLORSPACE_CMYK` (int)
`imagick::COLORSPACE_SRGB` (int)
`imagick::COLORSPACE_HSB` (int)
`imagick::COLORSPACE_HSL` (int)
`imagick::COLORSPACE_HWB` (int)
`imagick::COLORSPACE_REC601LUMA` (int)
`imagick::COLORSPACE_REC709LUMA` (int)
`imagick::COLORSPACE_LOG` (int)
`imagick::COLORSPACE_CMY` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.2 o superior.

Constantes `VIRTUALPIXELMETHOD_*`

`imagick::VIRTUALPIXELMETHOD_UNDEFINED` (int)
`imagick::VIRTUALPIXELMETHOD_BACKGROUND` (int)
`imagick::VIRTUALPIXELMETHOD_CONSTANT` (int)
`imagick::VIRTUALPIXELMETHOD_EDGE` (int)
`imagick::VIRTUALPIXELMETHOD_MIRROR` (int)
`imagick::VIRTUALPIXELMETHOD_TILE` (int)
`imagick::VIRTUALPIXELMETHOD_TRANSPARENT` (int)
`imagick::VIRTUALPIXELMETHOD_MASK` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.2 o superior.
`imagick::VIRTUALPIXELMETHOD_BLACK` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.2 o superior.
`imagick::VIRTUALPIXELMETHOD_GRAY` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.2 o superior.
`imagick::VIRTUALPIXELMETHOD_WHITE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.2 o superior.
`imagick::VIRTUALPIXELMETHOD_HORIZONTALTILE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.3 o superior.
`imagick::VIRTUALPIXELMETHOD_VERTICALTILE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.3 o superior.

Constantes `PREVIEW_*`

`imagick::PREVIEW_UNDEFINED` (int)
`imagick::PREVIEW_ROTATE` (int)
`imagick::PREVIEW_SHEAR` (int)
`imagick::PREVIEW_ROLL` (int)
`imagick::PREVIEW_HUE` (int)
`imagick::PREVIEW_SATURATION` (int)
`imagick::PREVIEW_BRIGHTNESS` (int)
`imagick::PREVIEW_GAMMA` (int)
`imagick::PREVIEW_SPIFF` (int)
`imagick::PREVIEW_DULL` (int)
`imagick::PREVIEW_GRAYSCALE` (int)
`imagick::PREVIEW_QUANTIZE` (int)
`imagick::PREVIEW_DESPECKLE` (int)
`imagick::PREVIEW_REDUCENOISE` (int)
`imagick::PREVIEW_ADDNOISE` (int)
`imagick::PREVIEW_SHARPEN` (int)
`imagick::PREVIEW_BLUR` (int)
`imagick::PREVIEW_THRESHOLD` (int)
`imagick::PREVIEW_EDGEDETECT` (int)
`imagick::PREVIEW_SPREAD` (int)
`imagick::PREVIEW_SOLARIZE` (int)
`imagick::PREVIEW_SHADE` (int)
`imagick::PREVIEW_RAISE` (int)
`imagick::PREVIEW_SEGMENT` (int)
`imagick::PREVIEW_SWIRL` (int)
`imagick::PREVIEW_IMPLODE` (int)
`imagick::PREVIEW_WAVE` (int)
`imagick::PREVIEW_OILPAINT` (int)
`imagick::PREVIEW_CHARCOALDRAWING` (int)
`imagick::PREVIEW_JPEG` (int)

Constantes `RENDERINGINTENT_*`

`imagick::RENDERINGINTENT_UNDEFINED` (int)
`imagick::RENDERINGINTENT_SATURATION` (int)
`imagick::RENDERINGINTENT_PERCEPTUAL` (int)
`imagick::RENDERINGINTENT_ABSOLUTE` (int)
`imagick::RENDERINGINTENT_RELATIVE` (int)

Constantes `INTERLACE_*`

`imagick::INTERLACE_UNDEFINED` (int)
`imagick::INTERLACE_NO` (int)
`imagick::INTERLACE_LINE` (int)
`imagick::INTERLACE_PLANE` (int)
`imagick::INTERLACE_PARTITION` (int)
`imagick::INTERLACE_GIF` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.4 o superior.
`imagick::INTERLACE_JPEG` (int)
`imagick::INTERLACE_PNG` (int)

Constantes `FILLRULE_*`

`imagick::FILLRULE_UNDEFINED` (int)
`imagick::FILLRULE_EVENODD` (int)
`imagick::FILLRULE_NONZERO` (int)

Constantes `PATHUNITS_*`

`imagick::PATHUNITS_UNDEFINED` (int)
`imagick::PATHUNITS_USERSPACE` (int)
`imagick::PATHUNITS_USERSPACEONUSE` (int)
`imagick::PATHUNITS_OBJECTBOUNDINGBOX` (int)

Constantes `LINECAP_*`

`imagick::LINECAP_UNDEFINED` (int)
`imagick::LINECAP_BUTT` (int)
`imagick::LINECAP_ROUND` (int)
`imagick::LINECAP_SQUARE` (int)

Constantes `LINEJOIN_*`

`imagick::LINEJOIN_UNDEFINED` (int)
`imagick::LINEJOIN_MITER` (int)
`imagick::LINEJOIN_ROUND` (int)
`imagick::LINEJOIN_BEVEL` (int)

Constantes `RESOURCETYPE_*`

`imagick::RESOURCETYPE_UNDEFINED` (int)
`imagick::RESOURCETYPE_AREA` (int)
  Define el ancho y la altura máximos de una imagen que puede almacenarse en la caché de píxeles.
`imagick::RESOURCETYPE_DISK` (int)
  Define el tamaño máximo de espacio en disco permitido para almacenar la caché de píxeles.
`imagick::RESOURCETYPE_FILE` (int)
  Define el número máximo de archivos de caché de píxeles abiertos.
`imagick::RESOURCETYPE_MAP` (int)
  Define el tamaño máximo de memoria en bytes a asignar a la caché de píxeles.
`imagick::RESOURCETYPE_MEMORY` (int)
  Define el tamaño máximo de la memoria, en bytes, a asignar a la caché de píxeles.
`imagick::RESOURCETYPE_THREAD` (int)
  Define el número máximo de hilos paralelos. Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.7.8 o superior.

Constantes `LAYERMETHOD_*`

`imagick::LAYERMETHOD_UNDEFINED` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.
`imagick::LAYERMETHOD_COALESCE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.
`imagick::LAYERMETHOD_COMPAREANY` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.
`imagick::LAYERMETHOD_COMPARECLEAR` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.
`imagick::LAYERMETHOD_COMPAREOVERLAY` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.
`imagick::LAYERMETHOD_DISPOSE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.
`imagick::LAYERMETHOD_OPTIMIZE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.
`imagick::LAYERMETHOD_OPTIMIZEPLUS` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.
`imagick::LAYERMETHOD_OPTIMIZEIMAGE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.0 o superior.
`imagick::LAYERMETHOD_OPTIMIZETRANS` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.0 o superior.
`imagick::LAYERMETHOD_REMOVEDUPS` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.0 o superior.
`imagick::LAYERMETHOD_REMOVEZERO` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.0 o superior.
`imagick::LAYERMETHOD_COMPOSITE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.0 o superior.
`imagick::LAYERMETHOD_MERGE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.7 o superior.
`imagick::LAYERMETHOD_FLATTEN` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.7 o superior.
`imagick::LAYERMETHOD_MOSAIC` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.7 o superior.

Constantes `ORIENTATION_*`

`imagick::ORIENTATION_UNDEFINED` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.0 o superior.
`imagick::ORIENTATION_TOPLEFT` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.0 o superior.
`imagick::ORIENTATION_TOPRIGHT` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.0 o superior.
`imagick::ORIENTATION_BOTTOMRIGHT` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.0 o superior.
`imagick::ORIENTATION_BOTTOMLEFT` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.0 o superior.
`imagick::ORIENTATION_LEFTTOP` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.0 o superior.
`imagick::ORIENTATION_RIGHTTOP` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.0 o superior.
`imagick::ORIENTATION_RIGHTBOTTOM` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.0 o superior.
`imagick::ORIENTATION_LEFTBOTTOM` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.0 o superior.

Constantes `DISTORTION_*`

`imagick::DISTORTION_UNDEFINED` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.6 o superior.
`imagick::DISTORTION_AFFINE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.6 o superior.
`imagick::DISTORTION_AFFINEPROJECTION` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.6 o superior.
`imagick::DISTORTION_ARC` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.6 o superior.
`imagick::DISTORTION_BILINEAR` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.6 o superior.
`imagick::DISTORTION_PERSPECTIVE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.6 o superior.
`imagick::DISTORTION_PERSPECTIVEPROJECTION` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.6 o superior.
`imagick::DISTORTION_SCALEROTATETRANSLATE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.6 o superior.
`imagick::DISTORTION_POLYNOMIAL` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.6 o superior.
`imagick::DISTORTION_POLAR` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.6 o superior.
`imagick::DISTORTION_DEPOLAR` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.6 o superior.
`imagick::DISTORTION_BARREL` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.6 o superior.
`imagick::DISTORTION_BARRELINVERSE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.6 o superior.
`imagick::DISTORTION_SHEPARDS` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.6 o superior.
`imagick::DISTORTION_SENTINEL` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.6 o superior.

Constantes `ALPHACHANNEL_*`

`imagick::ALPHACHANNEL_ACTIVATE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.8 o superior.
`imagick::ALPHACHANNEL_DEACTIVATE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.8 o superior.
`imagick::ALPHACHANNEL_RESET` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.8 o superior.
`imagick::ALPHACHANNEL_SET` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.8 o superior.
`imagick::ALPHACHANNEL_UNDEFINED` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.6 o superior.
`imagick::ALPHACHANNEL_COPY` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.6 o superior.
`imagick::ALPHACHANNEL_EXTRACT` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.6 o superior.
`imagick::ALPHACHANNEL_OPAQUE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.6 o superior.
`imagick::ALPHACHANNEL_SHAPE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.6 o superior.
`imagick::ALPHACHANNEL_TRANSPARENT` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.6 o superior.
`imagick::ALPHACHANNEL_BACKGROUND` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.5.3 o superior.
`imagick::ALPHACHANNEL_REMOVE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.7.8 o superior.
`imagick::ALPHACHANNEL_ASSOCIATE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.9.0 o superior.
`imagick::ALPHACHANNEL_DISSOCIATE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.9.0 o superior.
`imagick::ALPHACHANNEL_ON` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 7.0.0 o superior.
`imagick::ALPHACHANNEL_OFF` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 7.0.0 o superior.
`imagick::ALPHACHANNEL_DISCRETE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 7.0.0 o superior.

Constantes `SPARSECOLORMETHOD_*`

`imagick::SPARSECOLORMETHOD_UNDEFINED` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.6 o superior.
`imagick::SPARSECOLORMETHOD_BARYCENTRIC` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.6 o superior.
`imagick::SPARSECOLORMETHOD_BILINEAR` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.6 o superior.
`imagick::SPARSECOLORMETHOD_POLYNOMIAL` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.6 o superior.
`imagick::SPARSECOLORMETHOD_SPEPARDS` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.6 o superior.
`imagick::SPARSECOLORMETHOD_VORONOI` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.6 o superior.

Constantes `FUNCTION_*`

`imagick::FUNCTION_UNDEFINED` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.9 o superior.
`imagick::FUNCTION_POLYNOMIAL` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.9 o superior.
`imagick::FUNCTION_SINUSOID` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.9 o superior.

Constantes `INTERPOLATE_*`

`imagick::INTERPOLATE_UNDEFINED` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.2 o superior.
`imagick::INTERPOLATE_AVERAGE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.2 o superior.
`imagick::INTERPOLATE_BICUBIC` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.2 o superior.
`imagick::INTERPOLATE_BILINEAR` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.2 o superior.
`imagick::INTERPOLATE_FILTER` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.2 o superior.
`imagick::INTERPOLATE_INTEGER` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.2 o superior.
`imagick::INTERPOLATE_MESH` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.2 o superior.
`imagick::INTERPOLATE_NEARESTNEIGHBOR` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.2 o superior.
`imagick::INTERPOLATE_SPLINE` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.4 o superior.

Constantes `DITHERMETHOD_*`

`imagick::DITHERMETHOD_UNDEFINED` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.6 o superior.
`imagick::DITHERMETHOD_NO` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.6 o superior.
`imagick::DITHERMETHOD_RIEMERSMA` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.6 o superior.
`imagick::DITHERMETHOD_FLOYDSTEINBERG` (int)
  Esta constante solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.6 o superior.

# Ejemplos

## Tabla de contenidos

- Uso básico

## Uso básico

Imagick hace que la manipulación de imágenes en PHP sea extremadamente sencilla a través de una interfaz OO. Aquí está un ejemplo breve de cómo hacer una miniatura:

Ejemplo #1 Crear una miniatura con Imagick

    <?php

    header('Content-type: image/jpeg');

    $imagen = new Imagick('imagen.jpg');

    // Si se proporciona 0 como parámetro de ancho o alto,
    // se mantiene la proporción de aspecto
    $imagen->thumbnailImage(100, 0);

    echo $imagen;

    ?>

Al usar SPL y otras características OO soportadas en Imagick, puede ser sencillo redimensionar todos los archivos de un directorio (útil para la redimensión por lotes de muchas imágenes de cámara digital para que sean visibles desde una web). Aquí usamos redimensión, ya que queremos mantener cierta meta-información:

Ejemplo #2 Hacer una miniatura de todos los archivos JPG de un directorio

    <?php

    $imágenes = new Imagick(glob('imagenes/*.JPG'));

    foreach($imágenes as $imagen) {

        // Proporcionar 0 fuerza a thumbnailImage a mantener la proporción de aspecto
        $imagen->thumbnailImage(1024,0);

    }

    $imágenes->writeImages();

    ?>

Este es un ejemplo de crear un reflejo de una imagen. El reflejo se crea volteando la imagen y poniendo una capa de gradiente sobre ella. Ambas, la imagen original y el reflejo, están sobrepuestas en un lienzo.

Ejemplo #3 Crear un reflejo de una imagen

    <?php
    /* Leer la imagen */
    $im = new Imagick("test.png");

    /* Miniaturizar la imagen */
    $im->thumbnailImage(200, null);

    /* Crear un borde para la imagen */
    $im->borderImage(new ImagickPixel("white"), 5, 5);

    /* Clonar la imagen y voltearla */
    $reflejo = $im->clone();
    $reflejo->flipImage();

    /* Crear un gradiente. Será sobrepuesto en el reflejo */
    $gradiente = new Imagick();

    /* El gradiente necesita ser más grande que la imagen y los bordes */
    $gradiente->newPseudoImage($reflejo->getImageWidth() + 10, $reflejo->getImageHeight() + 10, "gradient:transparent-black");

    /* Componer el gradiente con el reflejo */
    $reflejo->compositeImage($gradiente, imagick::COMPOSITE_OVER, 0, 0);

    /* Añadir algo de opacidad. Requiere ImageMagick 6.2.9 o superior */
    $reflejo->setImageOpacity( 0.3 );

    /* Crear un lienzo vacío */
    $lienzo = new Imagick();

    /* El lienzo necesita ser más grande para mantener ambas imágenes */
    $ancho = $im->getImageWidth() + 40;
    $alto = ($im->getImageHeight() * 2) + 30;
    $lienzo->newImage($ancho, $alto, new ImagickPixel("black"));
    $lienzo->setImageFormat("png");

    /* Componer la imagen original y el reflejo sobre el lienzo */
    $lienzo->compositeImage($im, imagick::COMPOSITE_OVER, 20, 10);
    $lienzo->compositeImage($reflejo, imagick::COMPOSITE_OVER, 20, $im->getImageHeight() + 10);

    /* Imprimir la imagen */
    header("Content-Type: image/png");
    echo $lienzo;
    ?>

Resultado del ejemplo anterior es similar a:

Este ejemplo ilustra cómo usar patrones de relleno durante el dibujo.

Ejemplo #4 Rellenar un texto con un gradiente

    <?php

    /* Crear un nuevo objeto imagick */
    $im = new Imagick();

    /* Crear una nueva imagen. Será usada como patrón de relleno */
    $im->newPseudoImage(50, 50, "gradient:red-black");

    /* Crear un objeto imagickdraw */
    $dibujo = new ImagickDraw();

    /* Iniciar un nuevo patrón llamado "gradient" */
    $dibujo->pushPattern('gradient', 0, 0, 50, 50);

    /* Componer el gradiente con el patrón */
    $dibujo->composite(Imagick::COMPOSITE_OVER, 0, 0, 50, 50, $im);

    /* Cerrar el patrón */
    $dibujo->popPattern();

    /* Usar el patrón llamado "gradient" como el relleno */
    $dibujo->setFillPatternURL('#gradient');

    /* Establecer el tamaño de fuente a 52 */
    $dibujo->setFontSize(52);

    /* Anotar algo de texto */
    $dibujo->annotation(20, 50, "Hello World!");

    /* Crear un nuevo lienzo y una imagen blanca */
    $lienzo = new Imagick();
    $lienzo->newImage(350, 70, "white");

    /* Dibujar el objeto ImagickDraw sobre el lienzo */
    $lienzo->drawImage($dibujo);

    /* Borde negro de 1px alrededor de la imagen */
    $lienzo->borderImage('black', 1, 1);

    /* Establecer el formato a PNG */
    $lienzo->setImageFormat('png');

    /* Imprimir la imagen */
    header("Content-Type: image/png");
    echo $lienzo;
    ?>

Resultado del ejemplo anterior es similar a:

Trabajar con imágenes GIF animadas

Ejemplo #5 Leer una imágen GIF y redimensionar todos los fotogramas

    <?php

    /* Crear un nuevo objeto imagick y leer el GIF */
    $im = new Imagick("ejemplo.gif");

    /* Redimensionar todos los fotogramas */
    foreach ($im as $fotograma) {
     /* Fotogramas de 50x50 */
     $fotograma->thumbnailImage(50, 50);

     /* Establecer el lienzo virtual para corregir el tamaño */
     $fotograma->setImagePage(50, 50, 0, 0);
    }

    /* Observe: writeImages en vez de writeImage */
    $im->writeImages("example_small.gif", true);
    ?>

Trabajar con primitivas de elipse y tipos de letra personalizados

Ejemplo #6 Crear un logo de PHP

    <?php
    /* Establecer el ancho y alto en proporción al logo genuino de PHP */
    $ancho = 400;
    $alto = 210;

    /* Crear un objeto Imagick con lienzo transparente */
    $img = new Imagick();
    $img->newImage($ancho, $alto, new ImagickPixel('transparent'));

    /* Nueva instancia de ImagickDraw para dibujar la elipse */
    $dibujo = new ImagickDraw();
    /* Establecer el color de relleno púrpura para la elipse */
    $dibujo->setFillColor('#777bb4');
    /* Establecer las dimensiones de la elipse */
    $dibujo->ellipse($ancho / 2, $alto / 2, $ancho / 2, $alto / 2, 0, 360);
    /* Dibujar la elipse en el lienzo */
    $img->drawImage($dibujo);

    /* Restablecer el color de relleno de púrpura a negro para el texto (nota: estamos reutilizando el objeto ImagickDraw) */
    $dibujo->setFillColor('black');
    /* Establecer el borde del contorno al color blanco */
    $dibujo->setStrokeColor('white');
    /* Establecer el grosor del borde del contorno */
    $dibujo->setStrokeWidth(2);
    /* Establecer el interletraje («kerning») del tipo de letra (un valor negativo significa que las letras están más juntas entre ellas) */
    $dibujo->setTextKerning(-8);
    /* Establecer el tamaño del tipo de letra usado para el logo de PHP */
    $dibujo->setFont('Handel Gothic.ttf');
    $dibujo->setFontSize(150);
    /* Centrar el texto horizontal y verticalmente */
    $dibujo->setGravity(Imagick::GRAVITY_CENTER);

    /* Añadir en el centro "php" con el índice Y de -10 al lienzo (dentro de la elipse) */
    $img->annotateImage($dibujo, 0, -10, 0, 'php');
    $img->setImageFormat('png');

    /* Establecer la cabecera apropiada para PNG y generar la imagen */
    header('Content-Type: image/png');
    echo $img;
    ?>

Resultado del ejemplo anterior es similar a:

# La clase Imagick

(PECL imagick 2, PECL imagick 3)

## Sinopsis de la Clase

class Imagick implements Iterator {
public function __construct(mixed `$files` = ?)
public function adaptiveBlurImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function adaptiveResizeImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool
public function adaptiveSharpenImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function adaptiveThresholdImage(int `$width`, int `$height`, int `$offset`): bool
public function addImage(Imagick `$source`): bool
public function addNoiseImage(int `$noise_type`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function affineTransformImage(ImagickDraw `$matrix`): bool
public function animateImages(string `$x_server`): bool
public function annotateImage(
ImagickDraw `$draw_settings`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): bool
public function appendImages(bool `$stack`): Imagick
public function autoLevelImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function averageImages(): Imagick
public function blackThresholdImage(mixed `$threshold`): bool
public function blueShiftImage(float `$factor` = 1.5): bool
public function blurImage(float `$radius`, float `$sigma`, int `$channel` = ?): bool
public function borderImage(mixed `$bordercolor`, int `$width`, int `$height`): bool
public function brightnessContrastImage(float `$brightness`, float `$contrast`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function charcoalImage(float `$radius`, float `$sigma`): bool
public function chopImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function clampImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function clear(): bool
public function clipImage(): bool
public function clipImagePath(string `$pathname`, string `$inside`): void
public function clipPathImage(string `$pathname`, bool `$inside`): bool
public function clone(): Imagick
public function clutImage(Imagick `$lookup_table`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function coalesceImages(): Imagick
public function colorFloodfillImage(
mixed `$fill`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`
): bool
public function colorizeImage(mixed `$colorize`, mixed `$opacity`, bool `$legacy` = `false`): bool
public function colorMatrixImage(array `$color_matrix`): bool
public function combineImages(int `$channelType`): Imagick
public function commentImage(string `$comment`): bool
public function compareImageChannels(Imagick `$image`, int `$channelType`, int `$metricType`): array
public function compareImageLayers(int `$method`): Imagick
public function compareImages(Imagick `$compare`, int `$metric`): array
public function compositeImage(
Imagick `$composite_object`,
int `$composite`,
int `$x`,
int `$y`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function contrastImage(bool `$sharpen`): bool
public function contrastStretchImage(float `$black_point`, float `$white_point`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function convolveImage(array `$kernel`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function count(int `$mode` = 0): int
public function cropImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function cropThumbnailImage(int `$width`, int `$height`, bool `$legacy` = `false`): bool
public function current(): Imagick
public function cycleColormapImage(int `$displace`): bool
public function decipherImage(string `$passphrase`): bool
public function deconstructImages(): Imagick
public function deleteImageArtifact(string `$artifact`): bool
public function deleteImageProperty(string `$name`): bool
public function deskewImage(float `$threshold`): bool
public function despeckleImage(): bool
public function destroy(): bool
public function displayImage(string `$servername`): bool
public function displayImages(string `$servername`): bool
public function distortImage(int `$method`, array `$arguments`, bool `$bestfit`): bool
public function drawImage(ImagickDraw `$draw`): bool
public function edgeImage(float `$radius`): bool
public function embossImage(float `$radius`, float `$sigma`): bool
public function encipherImage(string `$passphrase`): bool
public function enhanceImage(): bool
public function equalizeImage(): bool
public function evaluateImage(int `$op`, float `$constant`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function exportImagePixels(
int `$x`,
int `$y`,
int `$width`,
int `$height`,
string `$map`,
int `$STORAGE`
): array
public function extentImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function filter(ImagickKernel `$ImagickKernel`, int `$channel` = Imagick::CHANNEL_UNDEFINED): bool
public function flattenImages(): Imagick
public function flipImage(): bool
public function floodFillPaintImage(
mixed `$fill`,
float `$fuzz`,
mixed `$target`,
int `$x`,
int `$y`,
bool `$invert`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function flopImage(): bool
public function forwardFourierTransformimage(bool `$magnitude`): bool
public function frameImage(
mixed `$matte_color`,
int `$width`,
int `$height`,
int `$inner_bevel`,
int `$outer_bevel`
): bool
public function functionImage(int `$function`, array `$arguments`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function fxImage(string `$expression`, int `$channel` = Imagick::CHANNEL_DEFAULT): Imagick
public function gammaImage(float `$gamma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function gaussianBlurImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function getColorspace(): int
public function getCompression(): int
public function getCompressionQuality(): int
public static function getCopyright(): string
public function getFilename(): string
public function getFont(): string
public function getFormat(): string
public function getGravity(): int
public static function getHomeURL(): string
public function getImage(): Imagick
public function getImageAlphaChannel(): bool
public function getImageArtifact(string `$artifact`): string
public function getImageAttribute(string `$key`): string
public function getImageBackgroundColor(): ImagickPixel
public function getImageBlob(): string
public function getImageBluePrimary(): array
public function getImageBorderColor(): ImagickPixel
public function getImageChannelDepth(int `$channel`): int
public function getImageChannelDistortion(Imagick `$reference`, int `$channel`, int `$metric`): float
public function getImageChannelDistortions(Imagick `$reference`, int `$metric`, int `$channel` = Imagick::CHANNEL_DEFAULT): float
public function getImageChannelExtrema(int `$channel`): array
public function getImageChannelKurtosis(int `$channel` = Imagick::CHANNEL_DEFAULT): array
public function getImageChannelMean(int `$channel`): array
public function getImageChannelRange(int `$channel`): array
public function getImageChannelStatistics(): array
public function getImageClipMask(): Imagick
public function getImageColormapColor(int `$index`): ImagickPixel
public function getImageColors(): int
public function getImageColorspace(): int
public function getImageCompose(): int
public function getImageCompression(): int
public function getImageCompressionQuality(): int
public function getImageDelay(): int
public function getImageDepth(): int
public function getImageDispose(): int
public function getImageDistortion(MagickWand `$reference`, int `$metric`): float
public function getImageExtrema(): array
public function getImageFilename(): string
public function getImageFormat(): string
public function getImageGamma(): float
public function getImageGeometry(): array
public function getImageGravity(): int
public function getImageGreenPrimary(): array
public function getImageHeight(): int
public function getImageHistogram(): array
public function getImageIndex(): int
public function getImageInterlaceScheme(): int
public function getImageInterpolateMethod(): int
public function getImageIterations(): int
public function getImageLength(): int
public function getImageMatte(): bool
public function getImageMatteColor(): ImagickPixel
public function getImageMimeType(): string
public function getImageOrientation(): int
public function getImagePage(): array
public function getImagePixelColor(int `$x`, int `$y`): ImagickPixel
public function getImageProfile(string `$name`): string
public function getImageProfiles(string `$pattern` = "*", bool `$include_values` = `true`): array
public function getImageProperties(string `$pattern` = "*", bool `$include_values` = `true`): array
public function getImageProperty(string `$name`): string
public function getImageRedPrimary(): array
public function getImageRegion(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Imagick
public function getImageRenderingIntent(): int
public function getImageResolution(): array
public function getImagesBlob(): string
public function getImageScene(): int
public function getImageSignature(): string
public function getImageSize(): int
public function getImageTicksPerSecond(): int
public function getImageTotalInkDensity(): float
public function getImageType(): int
public function getImageUnits(): int
public function getImageVirtualPixelMethod(): int
public function getImageWhitePoint(): array
public function getImageWidth(): int
public function getInterlaceScheme(): int
public function getIteratorIndex(): int
public function getNumberImages(): int
public function getOption(string `$key`): string
public static function getPackageName(): string
public function getPage(): array
public function getPixelIterator(): ImagickPixelIterator
public function getPixelRegionIterator(
int `$x`,
int `$y`,
int `$columns`,
int `$rows`
): ImagickPixelIterator
public function getPointSize(): float
public static function getQuantum(): int
public static function getQuantumDepth(): array
public static function getQuantumRange(): array
public static function getRegistry(string `$key`): string
public static function getReleaseDate(): string
public static function getResource(int `$type`): int
public static function getResourceLimit(int `$type`): int
public function getSamplingFactors(): array
public function getSize(): array
public function getSizeOffset(): int
public static function getVersion(): array
public function haldClutImage(Imagick `$clut`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function hasNextImage(): bool
public function hasPreviousImage(): bool
public function identifyFormat(string `$embedText`): string|false
public function identifyImage(bool `$appendRawOutput` = `false`): array
public function implodeImage(float `$radius`): bool
public function importImagePixels(
int `$x`,
int `$y`,
int `$width`,
int `$height`,
string `$map`,
int `$storage`,
array `$pixels`
): bool
public function inverseFourierTransformImage(Imagick `$complement`, bool `$magnitude`): bool
public function labelImage(string `$label`): bool
public function levelImage(
float `$blackPoint`,
float `$gamma`,
float `$whitePoint`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function linearStretchImage(float `$blackPoint`, float `$whitePoint`): bool
public function liquidRescaleImage(
int `$width`,
int `$height`,
float `$delta_x`,
float `$rigidity`
): bool
public static function listRegistry(): array
public function magnifyImage(): bool
public function mapImage(Imagick `$map`, bool `$dither`): bool
public function matteFloodfillImage(
float `$alpha`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`
): bool
public function medianFilterImage(float `$radius`): bool
public function mergeImageLayers(int `$layer_method`): Imagick
public function minifyImage(): bool
public function modulateImage(float `$brightness`, float `$saturation`, float `$hue`): bool
public function montageImage(
ImagickDraw `$draw`,
string `$tile_geometry`,
string `$thumbnail_geometry`,
int `$mode`,
string `$frame`
): Imagick
public function morphImages(int `$number_frames`): Imagick
public function morphology(
int `$morphologyMethod`,
int `$iterations`,
ImagickKernel `$ImagickKernel`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function mosaicImages(): Imagick
public function motionBlurImage(
float `$radius`,
float `$sigma`,
float `$angle`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function negateImage(bool `$gray`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function newImage(
int `$cols`,
int `$rows`,
mixed `$background`,
string `$format` = ?
): bool
public function newPseudoImage(int `$columns`, int `$rows`, string `$pseudoString`): bool
public function nextImage(): bool
public function normalizeImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function oilPaintImage(float `$radius`): bool
public function opaquePaintImage(
mixed `$target`,
mixed `$fill`,
float `$fuzz`,
bool `$invert`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function optimizeImageLayers(): bool
public function orderedPosterizeImage(string `$threshold_map`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function paintFloodfillImage(
mixed `$fill`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function paintOpaqueImage(
mixed `$target`,
mixed `$fill`,
float `$fuzz`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function paintTransparentImage(mixed `$target`, float `$alpha`, float `$fuzz`): bool
public function pingImage(string `$filename`): bool
public function pingImageBlob(string `$image`): bool
public function pingImageFile(resource `$filehandle`, string `$fileName` = ?): bool
public function polaroidImage(ImagickDraw `$properties`, float `$angle`): bool
public function posterizeImage(int `$levels`, bool `$dither`): bool
public function previewImages(int `$preview`): bool
public function previousImage(): bool
public function profileImage(string `$name`, string `$profile` = ?): bool
public function quantizeImage(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool
public function quantizeImages(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool
public function queryFontMetrics(ImagickDraw `$properties`, string `$text`, bool `$multiline` = ?): array
public static function queryFonts(string `$pattern` = "*"): array
public static function queryFormats(string `$pattern` = "*"): array
public function radialBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function raiseImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`,
bool `$raise`
): bool
public function randomThresholdImage(float `$low`, float `$high`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function readImage(string `$filename`): bool
public function readImageBlob(string `$image`, string `$filename` = ?): bool
public function readImageFile(resource `$filehandle`, string `$fileName` = `null`): bool
public function readImages(array `$filenames`): bool
public function recolorImage(array `$matrix`): bool
public function reduceNoiseImage(float `$radius`): bool
public function remapImage(Imagick `$replacement`, int `$DITHER`): bool
public function removeImage(): bool
public function removeImageProfile(string `$name`): string
public function render(): bool
public function resampleImage(
float `$x_resolution`,
float `$y_resolution`,
int `$filter`,
float `$blur`
): bool
public function resetImagePage(string `$page`): bool
public function resizeImage(
int `$columns`,
int `$rows`,
int `$filter`,
float `$blur`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool
public function rollImage(int `$x`, int `$y`): bool
public function rotateImage(mixed `$background`, float `$degrees`): bool
public function rotationalBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function roundCorners(
float `$x_rounding`,
float `$y_rounding`,
float `$stroke_width` = 10,
float `$displace` = 5,
float `$size_correction` = -6
): bool
public function sampleImage(int `$columns`, int `$rows`): bool
public function scaleImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool
public function segmentImage(
int `$COLORSPACE`,
float `$cluster_threshold`,
float `$smooth_threshold`,
bool `$verbose` = `false`
): bool
public function selectiveBlurImage(
float `$radius`,
float `$sigma`,
float `$threshold`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function separateImageChannel(int `$channel`): bool
public function sepiaToneImage(float `$threshold`): bool
public function setBackgroundColor(mixed `$background`): bool
public function setColorspace(int `$COLORSPACE`): bool
public function setCompression(int `$compression`): bool
public function setCompressionQuality(int `$quality`): bool
public function setFilename(string `$filename`): bool
public function setFirstIterator(): bool
public function setFont(string `$font`): bool
public function setFormat(string `$format`): bool
public function setGravity(int `$gravity`): bool
public function setImage(Imagick `$replace`): bool
public function setImageAlphaChannel(int `$mode`): bool
public function setImageArtifact(string `$artifact`, string `$value`): bool
public function setImageAttribute(string `$key`, string `$value`): bool
public function setImageBackgroundColor(mixed `$background`): bool
public function setImageBias(float `$bias`): bool
public function setImageBiasQuantum(float `$bias`): void
public function setImageBluePrimary(float `$x`, float `$y`): bool
public function setImageBorderColor(mixed `$border`): bool
public function setImageChannelDepth(int `$channel`, int `$depth`): bool
public function setImageClipMask(Imagick `$clip_mask`): bool
public function setImageColormapColor(int `$index`, ImagickPixel `$color`): bool
public function setImageColorspace(int `$colorspace`): bool
public function setImageCompose(int `$compose`): bool
public function setImageCompression(int `$compression`): bool
public function setImageCompressionQuality(int `$quality`): bool
public function setImageDelay(int `$delay`): bool
public function setImageDepth(int `$depth`): bool
public function setImageDispose(int `$dispose`): bool
public function setImageExtent(int `$columns`, int `$rows`): bool
public function setImageFilename(string `$filename`): bool
public function setImageFormat(string `$format`): bool
public function setImageGamma(float `$gamma`): bool
public function setImageGravity(int `$gravity`): bool
public function setImageGreenPrimary(float `$x`, float `$y`): bool
public function setImageIndex(int `$index`): bool
public function setImageInterlaceScheme(int `$interlace_scheme`): bool
public function setImageInterpolateMethod(int `$method`): bool
public function setImageIterations(int `$iterations`): bool
public function setImageMatte(bool `$matte`): bool
public function setImageMatteColor(mixed `$matte`): bool
public function setImageOpacity(float `$opacity`): bool
public function setImageOrientation(int `$orientation`): bool
public function setImagePage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function setImageProfile(string `$name`, string `$profile`): bool
public function setImageProperty(string `$name`, string `$value`): bool
public function setImageRedPrimary(float `$x`, float `$y`): bool
public function setImageRenderingIntent(int `$rendering_intent`): bool
public function setImageResolution(float `$x_resolution`, float `$y_resolution`): bool
public function setImageScene(int `$scene`): bool
public function setImageTicksPerSecond(int `$ticks_per_second`): bool
public function setImageType(int `$image_type`): bool
public function setImageUnits(int `$units`): bool
public function setImageVirtualPixelMethod(int `$method`): bool
public function setImageWhitePoint(float `$x`, float `$y`): bool
public function setInterlaceScheme(int `$interlace_scheme`): bool
public function setIteratorIndex(int `$index`): bool
public function setLastIterator(): bool
public function setOption(string `$key`, string `$value`): bool
public function setPage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function setPointSize(float `$point_size`): bool
public function setProgressMonitor(callable `$callback`): bool
public static function setRegistry(string `$key`, string `$value`): bool
public function setResolution(float `$x_resolution`, float `$y_resolution`): bool
public static function setResourceLimit(int `$type`, int `$limit`): bool
public function setSamplingFactors(array `$factors`): bool
public function setSize(int `$columns`, int `$rows`): bool
public function setSizeOffset(int `$columns`, int `$rows`, int `$offset`): bool
public function setType(int `$image_type`): bool
public function shadeImage(bool `$gray`, float `$azimuth`, float `$elevation`): bool
public function shadowImage(
float `$opacity`,
float `$sigma`,
int `$x`,
int `$y`
): bool
public function sharpenImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function shaveImage(int `$columns`, int `$rows`): bool
public function shearImage(mixed `$background`, float `$x_shear`, float `$y_shear`): bool
public function sigmoidalContrastImage(
bool `$sharpen`,
float `$alpha`,
float `$beta`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function sketchImage(float `$radius`, float `$sigma`, float `$angle`): bool
public function smushImages(bool `$stack`, int `$offset`): Imagick
public function solarizeImage(int `$threshold`): bool
public function sparseColorImage(int `$SPARSE_METHOD`, array `$arguments`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function spliceImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function spreadImage(float `$radius`): bool
public function statisticImage(
int `$type`,
int `$width`,
int `$height`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function steganoImage(Imagick `$watermark_wand`, int `$offset`): Imagick
public function stereoImage(Imagick `$offset_wand`): bool
public function stripImage(): bool
public function subImageMatch(Imagick `$Imagick`, array `&$offset` = ?, float `&$similarity` = ?): Imagick
function swirlImage(float `$degrees`): bool
function textureImage(Imagick `$texture_wand`): Imagick
public function thresholdImage(float `$threshold`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function thumbnailImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$fill` = `false`,
bool `$legacy` = `false`
): bool
public function tintImage(mixed `$tint`, mixed `$opacity`, bool `$legacy` = `false`): bool
public function __toString(): string
public function transformImage(string `$crop`, string `$geometry`): Imagick
public function transformImageColorspace(int `$colorspace`): bool
public function transparentPaintImage(
mixed `$target`,
float `$alpha`,
float `$fuzz`,
bool `$invert`
): bool
public function transposeImage(): bool
public function transverseImage(): bool
public function trimImage(float `$fuzz`): bool
public function uniqueImageColors(): bool
public function unsharpMaskImage(
float `$radius`,
float `$sigma`,
float `$amount`,
float `$threshold`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function valid(): bool
public function vignetteImage(
float `$blackPoint`,
float `$whitePoint`,
int `$x`,
int `$y`
): bool
public function waveImage(float `$amplitude`, float `$length`): bool
public function whiteThresholdImage(mixed `$threshold`): bool
public function writeImage(string `$filename` = NULL): bool
public function writeImageFile(resource `$filehandle`, string `$format` = ?): bool
public function writeImages(string `$filename`, bool `$adjoin`): bool
public function writeImagesFile(resource `$filehandle`, string `$format` = ?): bool
}

## Métodos de imagen y métodos globales

La clase Imagick permite actuar sobre varias imágenes simultáneamente y esto, gracias a una pila interna. Siempre hay un puntero interno, apuntando a la imagen actual. Algunas funciones actúan sobre todas las imágenes de una clase Imagick, pero la mayoría únicamente sobre la imagen actual en relación con esta pila. Al igual que las conversiones, los nombres de los métodos pueden contener el nombre de la imagen, relatando únicamente el efecto sobre la imagen de la pila.

## Métodos de la clase

Dado el número de métodos, aquí se presenta una lista que los muestra de forma general:

Métodos de la clase
Efectos sobre la imagen | Métodos de recuperación | Métodos de definición | Lectura/escritura de la imagen | Otros
--- | --- | --- | --- | ---
Imagick::adaptiveBlurImage() | Imagick::getCompression() | Imagick::setBackgroundColor() | Imagick::__construct() | Imagick::clear()
Imagick::adaptiveResizeImage() | Imagick::getFilename() | Imagick::setCompressionQuality() | Imagick::addImage() | Imagick::clone()
Imagick::adaptiveSharpenImage() | Imagick::getFormat() | Imagick::setCompression() | Imagick::appendImages() | Imagick::current()
Imagick::adaptiveThresholdImage() | Imagick::getImageBackgroundColor() | Imagick::setFilename() | Imagick::getFilename() | Imagick::destroy()
Imagick::addNoiseImage() | Imagick::getImageBlob() | Imagick::getImagesBlob() | Imagick::setFormat() | Imagick::getFormat()
Imagick::affinetransformimage() | Imagick::getImageBluePrimary() | Imagick::setImageBackgroundColor() | Imagick::getImageFilename() | Imagick::getHomeURL()
Imagick::annotateImage() | Imagick::getImageBorderColor() | Imagick::setFirstIterator() | Imagick::getImageFormat() | Imagick::commentImage()
Imagick::averageImages() | Imagick::getImageChannelDepth() | Imagick::setImageBias() | Imagick::getImage() | Imagick::getNumberImages()
Imagick::blackThresholdImage() | Imagick::getImageChannelDistortion() | Imagick::setImageBluePrimary() | Imagick::setImageFilename() | Imagick::getReleaseDate()
Imagick::blurImage() | Imagick::getImageChannelExtrema() | Imagick::setImageBorderColor() | Imagick::setImageFormat() | Imagick::getVersion()
Imagick::borderImage() | Imagick::getImageChannelMean() | Imagick::setImageChannelDepth() | Imagick::readImageFile() | Imagick::hasNextImage()
Imagick::charcoalImage() | Imagick::getImageChannelStatistics() | Imagick::setImageColormapColor() | Imagick::readImage() | Imagick::hasPreviousImage()
Imagick::chopImage() | Imagick::getImageColormapColor() | Imagick::setImageColorSpace() | Imagick::writeImages() | Imagick::labelImage()
Imagick::clipImage() | Imagick::getImageColorspace() | Imagick::setImageCompose() | Imagick::writeImage() | Imagick::newImage()
Imagick::clipPathImage() | Imagick::getImageColors() | Imagick::setImageCompression() |  | Imagick::newPseudoImage()
Imagick::coalesceImages() | Imagick::getImageCompose() | Imagick::setImageDelay() |  | Imagick::nextImage()
Imagick::colorFloodFillImage() | Imagick::getImageDelay() | Imagick::setImageDepth() |  | Imagick::pingImageBlob()
Imagick::colorizeImage() | Imagick::getImageDepth() | Imagick::setImageDispose() |  | Imagick::pingImageFile()
Imagick::combineImages() | Imagick::getImageDispose() | Imagick::setImageDispose() |  | Imagick::pingImage()
Imagick::compareImageChannels() | Imagick::getImageDistortion() | Imagick::setImageExtent() |  | Imagick::previousImage()
Imagick::compareImageLayers() | Imagick::getImageExtrema() | Imagick::setImageFilename() |  | Imagick::profileImage()
Imagick::compositeImage() | Imagick::getImageFilename() | Imagick::setImageFormat() |  | Imagick::queryFormats()
Imagick::contrastImage() | Imagick::getImageFormat() | Imagick::setImageGamma() |  | Imagick::removeImageProfile()
Imagick::contrastStretchImage() | Imagick::getImageGamma() | Imagick::setImageGreenPrimary() |  | Imagick::removeImage()
Imagick::convolveImage() | Imagick::getImageGeometry() | Imagick::setImageIndex() |  | Imagick::setFirstIterator()
Imagick::cropImage() | Imagick::getImageGreenPrimary() | Imagick::setImageInterpolateMethod() |  | Imagick::setImageIndex()
Imagick::cycleColormapImage() | Imagick::getImageHeight() | Imagick::setImageIterations() |  | Imagick::valid()
Imagick::deconstructImages() | Imagick::getImageHistogram() | Imagick::setImageMatteColor() |  | Imagick::getCopyright()
Imagick::drawImage() | Imagick::getImageIndex() | Imagick::setImageMatte() |  |
Imagick::edgeImage() | Imagick::getImageInterlaceScheme() | Imagick::setImagePage() |  |
Imagick::embossImage() | Imagick::getImageInterpolateMethod() | Imagick::setImageProfile() |  |
Imagick::enhanceImage() | Imagick::getImageIterations() | Imagick::setImageProperty() |  |
Imagick::equalizeImage() | Imagick::getImageMatteColor() | Imagick::setImageRedPrimary() |  |
Imagick::evaluateImage() | Imagick::getImageMatte() | Imagick::setImageRenderingIntent() |  |
Imagick::flattenImages() | Imagick::getImagePage() | Imagick::setImageResolution() |  |
Imagick::flipImage() | Imagick::getImagePixelColor() | Imagick::setImageScene() |  |
Imagick::flopImage() | Imagick::getImageProfile() | Imagick::setImageTicksPerSecond() |  |
| Imagick::getImageProperty() | Imagick::setImageType() |  |
Imagick::fxImage() | Imagick::getImageRedPrimary() | Imagick::setImageUnits() |  |
Imagick::gammaImage() | Imagick::getImageRegion() | Imagick::setImageVirtualPixelMethod() |  |
Imagick::gaussianBlurImage() | Imagick::getImageRenderingIntent() | Imagick::setImageWhitepoint() |  |
Imagick::implodeImage() | Imagick::getImageResolution() | Imagick::setInterlaceScheme() |  |
Imagick::levelImage() | Imagick::getImageScene() | Imagick::setOption() |  |
Imagick::linearStretchImage() | Imagick::getImageSignature() | Imagick::setPage() |  |
Imagick::magnifyImage() | Imagick::getImageTicksPerSecond() | Imagick::setResolution() |  |
Imagick::matteFloodFillImage() | Imagick::getImageTotalInkDensity() | Imagick::setResourceLimit() |  |
Imagick::medianFilterImage() | Imagick::getImageType() | Imagick::setSamplingFactors() |  |
Imagick::minifyImage() | Imagick::getImageUnits() | Imagick::setSizeOffset() |  |
Imagick::modulateImage() | Imagick::getImageVirtualPixelMethod() | Imagick::setSize() |  |
Imagick::montageImage() | Imagick::getImageWhitepoint() | Imagick::setType() |  |
Imagick::morphImages() | Imagick::getImageWidth() |  |  |
Imagick::mosaicImages() | Imagick::getImage() |  |  |
Imagick::motionBlurImage() | Imagick::getInterlaceScheme() |  |  |
Imagick::negateImage() | Imagick::getNumberImages() |  |  |
Imagick::normalizeImage() | Imagick::getOption() |  |  |
Imagick::oilPaintImage() | Imagick::getPackageName() |  |  |
Imagick::optimizeImageLayers() | Imagick::getPage() |  |  |
Imagick::paintOpaqueImage() | Imagick::getPixelIterator() |  |  |
Imagick::paintTransparentImage() | Imagick::getPixelRegionIterator() |  |  |
Imagick::posterizeImage() | Imagick::getQuantumDepth() |  |  |
Imagick::radialBlurImage() | Imagick::getQuantumRange() |  |  |
Imagick::raiseImage() | Imagick::getResourceLimit() |  |  |
Imagick::randomThresholdImage() | Imagick::getResource() |  |  |
Imagick::reduceNoiseImage() | Imagick::getSamplingFactors() |  |  |
Imagick::render() | Imagick::getSizeOffset() |  |  |
Imagick::resampleImage() | Imagick::getSize() |  |  |
Imagick::resizeImage() | Imagick::identifyImage() |  |  |
Imagick::rollImage() | Imagick::getImageSize() |  |  |
Imagick::rotateImage() |  |  |  |
Imagick::sampleImage() |  |  |  |
Imagick::scaleImage() |  |  |  |
Imagick::separateImageChannel() |  |  |  |
Imagick::sepiaToneImage() |  |  |  |
Imagick::shadeImage() |  |  |  |
Imagick::shadowImage() |  |  |  |
Imagick::sharpenImage() |  |  |  |
Imagick::shaveImage() |  |  |  |
Imagick::shearImage() |  |  |  |
Imagick::sigmoidalContrastImage() |  |  |  |
Imagick::sketchImage() |  |  |  |
Imagick::solarizeImage() |  |  |  |
Imagick::spliceImage() |  |  |  |
Imagick::spreadImage() |  |  |  |
Imagick::steganoImage() |  |  |  |
Imagick::stereoImage() |  |  |  |
Imagick::stripImage() |  |  |  |
Imagick::swirlImage() |  |  |  |
Imagick::textureImage() |  |  |  |
Imagick::thresholdImage() |  |  |  |
Imagick::thumbnailImage() |  |  |  |
Imagick::tintImage() |  |  |  |
Imagick::transverseImage() |  |  |  |
Imagick::trimImage() |  |  |  |
Imagick::uniqueImageColors() |  |  |  |
Imagick::unsharpMaskImage() |  |  |  |
Imagick::vignetteImage() |  |  |  |
Imagick::waveImage() |  |  |  |
Imagick::whiteThresholdImage() |  |  |  |

# Imagick::adaptiveBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveBlurImage — Añade un filtro de borrosidad adaptativo a la imagen

### Descripción

public function Imagick::adaptiveBlurImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Añade un filtro de borrosidad adaptativo a la imagen. La intensidad de una borrosidad adaptativa depende de si se disminuye dramáticamente en el borde de la imagen, mientras que una borrodidad estándar es uniforme en toda la imagen. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

### Parámetros

`radius`

  El radio gaussiano, en píxeles, sin contar el píxel central. Proporcione un valor de 0 y el radio será elegido auto-mágicaente.

`sigma`

  La desviación estándar gaussiana, en píxeles.

`channel`

  Proporciona una constante de canal válida para su modo de canal. Para aplicarlo a más de un canal, combínense las constantes de canales utilizando un operador a nivel de bits. Por omisión, vale `Imagick::CHANNEL_DEFAULT`. Consúltese la lista de constantes de canales

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Usar Imagick::adaptiveBlurImage():

Aplicar borrosidad adaptativa a una imagen, después mostrarla en el navegador.

    <?php

    header('Content-type: image/jpeg');

    $imagen = new Imagick('test.jpg');

    $imagen->adaptiveBlurImage(5,3);
    echo $imagen;

    ?>

Resultado del ejemplo anterior es similar a:

### Ver también

- Imagick::blurImage() - Añade un filtro de borrosidad a la imagen
- Imagick::motionBlurImage() - Simula borrosidad en movimiento
- Imagick::radialBlurImage() - Hace borrosa de forma radial una imagen

# Imagick::adaptiveResizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveResizeImage — Redimensiona una imagen adaptativamente con información dependiente de la triangulación

### Descripción

public function Imagick::adaptiveResizeImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool

Redimensiona una imagen adaptativamente con información dependiente de la triangulación. Evita la borrosidad a través de cambios de color bruscos. Muy útil cuando se usa para encoger ligeramente imágenes a un "tamaño web" ligeramente más pequeño; puede que no tenga una buena apariencia cuando una imagen a tamaño completo se redimensiona adaptativamente a una miniatura. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

> Nota: El comportamiento del parámetro `bestfit` cambió con Imagick 3.0.0. Antes de esta versión, proporcionar las dimensiones 400x400 a una imagen de dimensiones 200x150 hacía que la parte izquierda permaneciera sin cambios. Con Imagick 3.0.0 y posteriores, la imagen se reduce al tamaño 400x300, siendo este el mejor resultado para esas dimensiones. Si el parámetro `bestfit` es utilizado, la anchura y la altura deben ser proporcionadas.

### Parámetros

`columns`

  El número de columnas en la imagen escalada.

`rows`

  El número de filas en la imagen escalada.

`bestfit`

  Si ajustar la imagen dentro de una caja limitada.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL imagick 2.1.0 | Añadido el parámetro opcional de ajuste.
PECL imagick 2.1.0 | Este método ahora soporta escalas proporcionales. Pase cero como parámetro para escalar proporcionalmente.

### Ejemplos

Ejemplo #1 Usar Imagick::adaptiveResizeImage()

Redimensiona una imagen al tamaño estándar para la web. Este método trabaja mejor cuando se redimensiona a un tamaño sólo ligeramente menor que el tamaño de la imagen previa.

    <?php
    header('Content-type: image/jpeg');

    $imagen = new Imagick('image.jpg');
    $image->adaptiveResizeImage(1024,768);

    echo $imagen;
    ?>

### Ver también

- Imagick::chopImage() - Borra una región de una imagen y la recorta
- Imagick::cropImage() - Extrae una región de la imagen
- Imagick::magnifyImage() - Duplica el tamaño de una imagen, proporcionalmente
- Imagick::minifyImage() - Redimensiona una imagen proporcionalmente para reducirla a la mitad de tamaño
- Imagick::resizeImage() - Escala una imagen
- Imagick::scaleImage() - Redimensiona la imagen a una escala específica
- Imagick::shaveImage() - Recorta píxeles de los extremos de la imagen
- Imagick::thumbnailImage() - Modifica el tamaño de una imagen
- Imagick::trimImage() - Elimina los extremos de la imagen

# Imagick::adaptiveSharpenImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveSharpenImage — Afila la imagen adaptativamente

### Descripción

public function Imagick::adaptiveSharpenImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Afila la imagen adaptativamente afilando con más intensidad cerca de los bordes de la imagen y con menos intensidad lejos de los bordes. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

### Parámetros

`radius`

  El radio gaussiano, en píxeles, sin contar el píxel central. Use 0 para autoseleccionar.

`sigma`

  La desviación estándar gaussiana, en píxeles.

`channel`

  Proporciona una constante de canal válida para su modo de canal. Para aplicarlo a más de un canal, combínense las constantes de canales utilizando un operador a nivel de bits. Por omisión, vale `Imagick::CHANNEL_DEFAULT`. Consúltese la lista de constantes de canales

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Un ejemplo de Imagick::adaptiveSharpenImage()

Afilar la imagen adaptativamente con radio 2 y sigma 1.

    <?php
    try {
        $imagen = new Imagick('image.png');
        $imagen->adaptiveSharpenImage(2,1);
    } catch(ImagickException $e) {
        echo 'Error: ' , $e->getMessage();
        die();
    }
    header('Content-type: image/png');
    echo $imagen;
    ?>

### Ver también

- Imagick::sharpenImage() - Afila una imagen

# Imagick::adaptiveThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveThresholdImage — Selecciona un umbral para cada píxel basado en un rango de intensidad

### Descripción

public function Imagick::adaptiveThresholdImage(int `$width`, int `$height`, int `$offset`): bool

Selecciona un umbral individual para cada píxel basado en un rango de valores de intensidad en su zona local. Esto permite establecer el umbral de una imagen cuyo histograma de intensidad global no contiene picos distintivos.

### Parámetros

`width`

  Ancho de la zona local.

`height`

  Alto de la zona local.

`offset`

  El índice medio

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::adaptiveThresholdImage()

    <?php
    function adaptiveThresholdImage($imagePath, $width, $height, $adaptiveOffset) {
        $imagick = new \Imagick(realpath($imagePath));
        $adaptiveOffsetQuantum = intval($adaptiveOffset * \Imagick::getQuantum());
        $imagick->adaptiveThresholdImage($width, $height, $adaptiveOffsetQuantum);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::addImage

(PECL imagick 2, PECL imagick 3)

Imagick::addImage — Añade una nueva imagen a la lista de imágenes del objeto Imagick

### Descripción

public function Imagick::addImage(Imagick `$source`): bool

Añade una nueva imagen al objeto Imagick desde la posición actual del objeto de origen. Después de la operación la posición del iterador se mueve al final de la lista.

### Parámetros

`source`

  El objeto Imagick de origen

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::addNoiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::addNoiseImage — Añade ruido aleatorio a la imagen

### Descripción

public function Imagick::addNoiseImage(int `$noise_type`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Añade ruido aleatorio a la imagen.

### Parámetros

`noise_type`

  El tipo de ruido. Consulte esta lista de constantes de ruido.

`channel`

  Proporciona una constante de canal válida para su modo de canal. Para aplicarlo a más de un canal, combínense las constantes de canales utilizando un operador a nivel de bits. Por omisión, vale `Imagick::CHANNEL_DEFAULT`. Consúltese la lista de constantes de canales

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::addNoiseImage()

    <?php
    function addNoiseImage($noiseType, $imagePath, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->addNoiseImage($noiseType, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::affineTransformImage

(PECL imagick 2, PECL imagick 3)

Imagick::affineTransformImage — Transforma una imagen

### Descripción

public function Imagick::affineTransformImage(ImagickDraw `$matrix`): bool

Transforma una imagen como está establecido en la matriz afín.

### Parámetros

`matrix`

  La matriz afín

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::affineTransformImage()

    <?php
    function affineTransformImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $draw = new \ImagickDraw();

        $angle = deg2rad(40);

        $affineRotate = array(
            "sx" => cos($angle), "sy" => cos($angle),
            "rx" => sin($angle), "ry" => -sin($angle),
            "tx" => 0, "ty" => 0,
        );

        $draw->affine($affineRotate);

        $imagick->affineTransformImage($draw);

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::animateImages

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::animateImages — Anima una imagen o imágenes

### Descripción

public function Imagick::animateImages(string `$x_server`): bool

Este método anima la imagen en un servidor X local o remoto. Este método no está disponible en Windows. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.6 o superior.

### Parámetros

`x_server`

  La dirección del servidor X

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ver también

- Imagick::displayImage() - Muestra una imagen

# Imagick::annotateImage

(PECL imagick 2, PECL imagick 3)

Imagick::annotateImage — Anota una imagen con texto

### Descripción

public function Imagick::annotateImage(
ImagickDraw `$draw_settings`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): bool

Anota una imagen con texto.

### Parámetros

`draw_settings`

  El objeto ImagickDraw que contiene la configuración para el dibujo de texto

`x`

  El índice horizontal en píxeles a la izquierda del texto

`y`

  El índice vertical en píxeles de la línea base del texto

`angle`

  El ángulo en el que se escribe el texto

`text`

  La cadena a dibujar

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Usar Imagick::annotateImage():

Anotar texto en una imagen vacía

    <?php
    /* Crear algunos objetos */
    $imagen = new Imagick();
    $dibujo = new ImagickDraw();
    $píxel = new ImagickPixel( 'gray' );

    /* Nueva imagen */
    $imagen->newImage(800, 75, $píxel);

    /* Texto negro */
    $dibujo->setColor('black');

    /* Propiedades de la fuente */
    $dibujo->setFont('Bookman-DemiItalic');
    $dibujo->setFontSize( 30 );

    /* Crear texto */
    $imagen->annotateImage($dibujo, 10, 45, 0, 'The quick brown fox jumps over the lazy dog');

    /* Dar a la imagen un formato */
    $imagen->setImageFormat('png');

    /* Imprimir la imagen con cabeceras */
    header('Content-type: image/png');
    echo $imagen;

    ?>

### Ver también

- ImagickDraw::annotation() - Dibuja un texto sobre una imagen
- ImagickDraw::setFont() - Establece la fuente especificada completamente para usarla cuando se escribe texto

# Imagick::appendImages

(PECL imagick 2, PECL imagick 3)

Imagick::appendImages — Añade un conjunto de imágenes

### Descripción

public function Imagick::appendImages(bool `$stack`): Imagick

Añade un conjunto de imágenes en una imagen más grande.

### Parámetros

`stack`

  Para apilar las imágenes verticalmente. Por defecto (o si `false` se especifica) las imágenes se apilan de izquierda a derecha. Si `stack` es `true`, las imágenes se apilan de arriba hacia abajo.

### Valores devueltos

Devuelve una instancia Imagick si se tuvo éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de Imagick::appendImages()

    <?php

    /* Crear un nuevo objeto Imagick */
    $im = new Imagick();

    /* Crear imágenes de color rojo, verde y azul */
    $im->newImage(100, 50, "red");
    $im->newImage(100, 50, "green");
    $im->newImage(100, 50, "blue");

    /* Añadir las imágenes en una sola */
    $im->resetIterator();
    $combined = $im->appendImages(true);

    /* Imprimir la imagen */
    $combined->setImageFormat("png");
    header("Content-Type: image/png");
    echo $combined;
    ?>

Resultado del ejemplo anterior es similar a:

# Imagick::autoLevelImage

(PECL imagick 3 >= 3.3.0)

Imagick::autoLevelImage — Ajusta el nivel de un canal de una imagen particular

### Descripción

public function Imagick::autoLevelImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Ajusta el nivel de un canal de una imagen particular escalando los valores mínimos y máximos al rango cuántico completo.

### Parámetros

`channel`

  Qué canal debe ser utilizado para el auto-nivelado.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::autoLevelImage()

    <?php
    function autoLevelImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->autoLevelImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::averageImages

(PECL imagick 2, PECL imagick 3)

Imagick::averageImages — Promedio de un conjunto de imágenes

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::averageImages(): Imagick

Realiza el promedio de un conjunto de imágenes.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un nuevo objeto Imagick en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::blackThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::blackThresholdImage — Fuerza a todos los píxeles bajo un umbral a ser negros

### Descripción

public function Imagick::blackThresholdImage(mixed `$threshold`): bool

Es como Imagick::thresholdImage() pero fuerza a todos los píxeles bajo un umbral a ser negros mientras deja todos los píxeles por encima del umbral sin cambios.

### Parámetros

`threshold`

  El umbral por debajo del cual todo se vuelve de color negro

### Valores devueltos

Devuelve `true` en caso de éxito.

### Historial de cambios

Versión | Descripción
--- | ---
PECL imagick 2.1.0 | Ahora se permite que una cadena represente el color como un parámetro. Versiones anteriores sólo permitían un objeto ImagickPixel.

### Ejemplos

Ejemplo #1 Imagick::blackThresholdImage()

    <?php
    function blackThresholdImage($imagePath, $thresholdColor) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->blackthresholdimage($thresholdColor);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::blueShiftImage

(PECL imagick 3 >= 3.3.0)

Imagick::blueShiftImage — Atenúa los colores de la imagen

### Descripción

public function Imagick::blueShiftImage(float `$factor` = 1.5): bool

Atenúa los colores de la imagen para simular una escena nocturna a la luz de la luna.

### Parámetros

`factor`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::blueShiftImage()

    <?php
    function blueShiftImage($imagePath, $blueShift) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->blueShiftImage($blueShift);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::blurImage

(PECL imagick 2, PECL imagick 3)

Imagick::blurImage — Añade un filtro de borrosidad a la imagen

### Descripción

public function Imagick::blurImage(float `$radius`, float `$sigma`, int `$channel` = ?): bool

Añade un filtro de borrosidad a la imagen. El tercer parámetro opcional es para hacer borroso un canal específico.

### Parámetros

`radius`

  Radio de la borrosidad

`sigma`

  Desviación estándar

`channel`

  La constante Channeltype. Cuando no es proporciona, todos los canales se hacen borrosos.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Usar Imagick::blurImage():

Hacer borrosa una imagen, después mostrarla en el navegador.

    <?php

    header('Content-type: image/jpeg');

    $imagen = new Imagick('prueba.jpg');

    $imagen->blurImage(5,3);
    echo $imagen;

    ?>

### Ver también

- Imagick::adaptiveBlurImage() - Añade un filtro de borrosidad adaptativo a la imagen
- Imagick::motionBlurImage() - Simula borrosidad en movimiento
- Imagick::radialBlurImage() - Hace borrosa de forma radial una imagen

# Imagick::borderImage

(PECL imagick 2, PECL imagick 3)

Imagick::borderImage — Rodea la imagen con un borde

### Descripción

public function Imagick::borderImage(mixed `$bordercolor`, int `$width`, int `$height`): bool

Rodea la imagen con un borde del color definido por el objeto ImagickPixel de color de borde.

### Parámetros

`bordercolor`

  Objeto ImagickPixel o una cadena que contiene el color del borde

`width`

  Ancho del borde

`height`

  Alto del borde

### Valores devueltos

Devuelve `true` en caso de éxito.

### Historial de cambios

Versión | Descripción
--- | ---
PECL imagick 2.1.0 | Ahora se permite que una cadena represente el color como el primer parámetro. Versiones anteriores sólo permitían un objeto ImagickPixel.

### Ejemplos

Ejemplo #1 Imagick::borderImage()

    <?php
    function borderImage($imagePath, $color, $width, $height) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->borderImage($color, $width, $height);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::brightnessContrastImage

(PECL imagick 3 >= 3.3.0)

Imagick::brightnessContrastImage — Cambia el brillo y/o el contraste de una imagen

### Descripción

public function Imagick::brightnessContrastImage(float `$brightness`, float `$contrast`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Cambia el brillo y/o el contraste de una imagen. Convierte los parámetros de brillo y contraste en pendiente e intercepción y llama a una función polinómica para aplicarla a la imagen.

### Parámetros

`brightness`

`contrast`

`channel`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::brightnessContrastImage()

    <?php
    function brightnessContrastImage($imagePath, $brightness, $contrast, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->brightnessContrastImage($brightness, $contrast, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::charcoalImage

(PECL imagick 2, PECL imagick 3)

Imagick::charcoalImage — Simula un dibujo a carboncillo

### Descripción

public function Imagick::charcoalImage(float `$radius`, float `$sigma`): bool

Simula un dibujo a carboncillo.

### Parámetros

`radius`

  El radio gaussiano, en píxeles, sin contar el píxel central

`sigma`

  La desviación estándar gaussiana, en píxeles

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::charcoalImage()

    <?php
    function charcoalImage($imagePath, $radius, $sigma) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->charcoalImage($radius, $sigma);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::chopImage

(PECL imagick 2, PECL imagick 3)

Imagick::chopImage — Borra una región de una imagen y la recorta

### Descripción

public function Imagick::chopImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Borra una región de una imagen y colapsa la imagen para ocupar la porción borrada.

### Parámetros

`width`

  Ancho del área cortada

`height`

  Alto del área cortada

`x`

  El punto de referencia X del área cortada

`y`

  El punto de referencia Y del área cortada

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Usar Imagick::chopImage():

Ejemplo de uso de Imagick::chopImage

    <?php
    /* Crear algunos objetos */
    $imagen = new Imagick();
    $píxel = new ImagickPixel( 'gray' );

    /* Nueva imagen */
    $imagen->newImage(400, 200, $píxel);

    /* Cortar imagen */
    $imagen->chopImage(200, 200, 0, 0);

    /* Dar un formato a la imagen */
    $imagen->setImageFormat('png');

    /* Imprimir la imagen con cabeceras */
    header('Content-type: image/png');
    echo $imagen;

    ?>

### Ver también

- Imagick::cropImage() - Extrae una región de la imagen

# Imagick::clampImage

(PECL imagick 3 >= 3.3.0)

Imagick::clampImage — Restringe el rango de colores de 0 a la profundidad cuántica

### Descripción

public function Imagick::clampImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Restringe el rango de colores de 0 a la profundidad cuántica.

### Parámetros

`channel`

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# Imagick::clear

(PECL imagick 2, PECL imagick 3)

Imagick::clear — Libera todos los recursos asociados a un objeto Imagick

### Descripción

public function Imagick::clear(): bool

Libera todos los recursos asociados a un objeto Imagick.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::clipImage

(PECL imagick 2, PECL imagick 3)

Imagick::clipImage — Se alinea con el primer camino de un perfil 8BIM

### Descripción

public function Imagick::clipImage(): bool

Se alinea con el primer camino de un perfil 8BIM, si está presente.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::clipImagePath

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::clipImagePath — Recorta a lo largo de las rutas nombradas del perfil 8BIM, si está presente

### Descripción

public function Imagick::clipImagePath(string `$pathname`, string `$inside`): void

Recorta a lo largo de las rutas nombradas del perfil 8BIM, si está presente. Las operaciones posteriores surten efecto dentro de la ruta. Id puede ser un número si va precedido de #, para trabajar en una ruta numerada, por ejemplo, "#1" para utilizar la primera ruta.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`pathname`

`inside`

### Valores devueltos

# Imagick::clipPathImage

(PECL imagick 2, PECL imagick 3)

Imagick::clipPathImage — Recorta a lo largo de trazados nominados desde un perfil 8BIM

### Descripción

public function Imagick::clipPathImage(string `$pathname`, bool `$inside`): bool

Recorta a lo largo de trazados nominados desde un perfil 8BIM, si está presente. Las operaiones posteriores toman efecto dentro del trazado. Puede ser un número si está precedido de #, para trabajar con un trazado numerado, p.ej., "#1" para usar el primer trazado.

### Parámetros

`pathname`

  El nombre del trazado

`inside`

  Si es `true` las operaciones posteriores toman efecto dentro del patrón de recorte. De otro modo, las operaciones toman efecto fuera del patrón de recorte.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::clone

(PECL imagick 2, PECL imagick 3)

Imagick::clone — Realiza una copia exacta de un objeto Imagick

### Descripción

public function Imagick::clone(): Imagick

Realiza una copia exacta de un objeto Imagick.

Advertencia

Esta función se ha vuelto OBSOLETA a partir de imagick 3.1.0. Ahora debe utilizarse la palabra clave clone.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Una copia del objeto Imagick.

### Historial de cambios

Versión | Descripción
--- | ---
PECL imagick 3.1.0 | Este método se ha vuelto obsoleto en favor de la palabra clave clone.

### Ejemplos

Ejemplo #1 Clonación de objeto Imagick con diferentes versiones de Imagick

    <?php
    // Clonación de un objeto Imagick utilizando la versión 2.x y 3.0:
    $newImage = $image->clone();

    // Clonación de un objeto Imagick a partir de la versión 3.1.0:
    $newImage = clone $image;
    ?>

# Imagick::clutImage

(PECL imagick 2, PECL imagick 3)

Imagick::clutImage — Reemplaza los colores de una imagen

### Descripción

public function Imagick::clutImage(Imagick `$lookup_table`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Reemplaza los colores en una imagen con una paleta de colores. El segundo parámetro opcional reemplaza los colores de un canal específico. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.6 o superior.

### Parámetros

`lookup_table`

  Objeto Imagick que contiene la paleta de colores

`channel`

  La constante Channeltype. Cuando no se proporciona, los canales predeterminados se reemplazan.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Usar Imagick::clutImage():

Reemplazar los colores de una imagen desde una paleta de colores.

    <?php
    $imagen = new Imagick('test.jpg');
    $clut = new Imagick();
    $clut->newImage(1, 1, new ImagickPixel('black'));
    $imagen->clutImage($clut);
    $imagen->writeImage('test_out.jpg');
    ?>

### Ver también

- Imagick::adaptiveBlurImage() - Añade un filtro de borrosidad adaptativo a la imagen
- Imagick::motionBlurImage() - Simula borrosidad en movimiento
- Imagick::radialBlurImage() - Hace borrosa de forma radial una imagen

# Imagick::coalesceImages

(PECL imagick 2, PECL imagick 3)

Imagick::coalesceImages — Componer un conjunto de imágenes

### Descripción

public function Imagick::coalesceImages(): Imagick

Componer un conjunto de imágenes respetando todas las posiciones y los métodos de disposición. Las secuencias de animaciones GIF, MIFF y MNG, comienzan típicamente con una imagen de fondo, seguida de todas las imágenes siguientes que varían en tamaño y posición. Retorna un nuevo objeto Imagick donde cada imagen de la secuencia tiene el mismo tamaño que la primera, y compuesta con la siguiente en la secuencia.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Retorna un nuevo objeto Imagick en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::colorFloodfillImage

(PECL imagick 2, PECL imagick 3)

Imagick::colorFloodfillImage — Cambia el valor del color de cualquier píxel que coincida con el objetivo

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::colorFloodfillImage(
mixed `$fill`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`
): bool

Cambia el valor del color de cualquier píxel que coincida con el objetivo y esté en el área inmediata.

### Parámetros

`fill`

  Objeto ImagickPixel que contiene el color de relleno

`fuzz`

  La cantidad de enfoque. Por ejemplo, establecer el enfoque a 10 y el color a rojo con una intensidad de 100 y 102 respectivamente ahora se interpreta como el mismo color para los propósitos del relleno.

`bordercolor`

  Objeto ImagickPixel que contiene el color de borde

`x`

  Posición X del inicio del relleno

`y`

  Posición Y del inicio del relleno

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL imagick 2.1.0 | Ahora se permite que una cadena represente el color como el primer y tercer parámetros. Versiones anteriores sólo permitían un objeto ImagickPixel.

# Imagick::colorizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::colorizeImage — Mezcla el color de relleno con la imagen

### Descripción

public function Imagick::colorizeImage(mixed `$colorize`, mixed `$opacity`, bool `$legacy` = `false`): bool

Mezcla el color de relleno de cada píxel con la imagen.

### Parámetros

`colorize`

  Objeto ImagickPixel o una cadena que contiene el color

`opacity`

  Objeto ImagickPixel o un valor float que contiene el valor de la opacidad. 1.0 es completamente opaco y 0.0 es completamente transparente.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL imagick 2.1.0 | Ahora se permite que una cadena represente el color como el primer parámetro y que un valor float represente el valor de la opacidad como el segundo parámetro. Versiones anteriores sólo permitían objetos ImagickPixel.

### Ejemplos

Ejemplo #1 Imagick::colorizeImage()

    <?php
    function colorizeImage($imagePath, $color, $opacity) {
        $imagick = new \Imagick(realpath($imagePath));
        $opacity = $opacity / 255.0;
        $opacityColor = new \ImagickPixel("rgba(0, 0, 0, $opacity)");
        $imagick->colorizeImage($color, $opacityColor);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::colorMatrixImage

(PECL imagick 3 >= 3.3.0)

Imagick::colorMatrixImage — Aplica una transformación de color a una imagen

### Descripción

public function Imagick::colorMatrixImage(array `$color_matrix`): bool

Aplica una transformación de color a una imagen. El método permite cambios de saturación, rotación de tono, luminancia en alfa y diversos otros efectos. Aunque se pueden utilizar matrices de transformación de tamaño variable, generalmente se usa una matriz 5x5 para una imagen RGBA y una 6x6 para CMYKA (o RGBA con desplazamientos). La matriz es similar a las utilizadas por Adobe Flash, excepto que los desplazamientos están en la columna 6 en lugar de la 5 (para soportar imágenes CMYKA) y los desplazamientos están normalizados (divida el desplazamiento Flash por 255).

### Parámetros

`color_matrix`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::colorMatrixImage()

    <?php
    function colorMatrixImage($imagePath, $colorMatrix) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageOpacity(1);

        //Una matriz de color debería ser similar a:
        //    $colorMatrix = [
        //        1.5, 0.0, 0.0, 0.0, 0.0, -0.157,
        //        0.0, 1.0, 0.5, 0.0, 0.0, -0.157,
        //        0.0, 0.0, 1.5, 0.0, 0.0, -0.157,
        //        0.0, 0.0, 0.0, 1.0, 0.0,  0.0,
        //        0.0, 0.0, 0.0, 0.0, 1.0,  0.0,
        //        0.0, 0.0, 0.0, 0.0, 0.0,  1.0
        //    ];

        $background = new \Imagick();
        $background->newPseudoImage($imagick->getImageWidth(), $imagick->getImageHeight(),  "pattern:checkerboard");

        $background->setImageFormat('png');

        $imagick->setImageFormat('png');
        $imagick->colorMatrixImage($colorMatrix);

        $background->compositeImage($imagick, \Imagick::COMPOSITE_ATOP, 0, 0);

        header("Content-Type: image/png");
        echo $background->getImageBlob();
    }

    ?>

# Imagick::combineImages

(PECL imagick 2, PECL imagick 3)

Imagick::combineImages — Combina una o más imágenes en una sóla imagen

### Descripción

public function Imagick::combineImages(int `$channelType`): Imagick

Combina una o más imágenes en una sóla imagen. El valor de la escala de grises de los píxeles de cada imagen en la secuencia se asigna para especificar los canales de la imagen combinada. El orden típico sería imagen 1 => Red, 2 => Green, 3 => Blue, etc.

### Parámetros

`channelType`

  Proporcione cualquier constante de canal que sea válida para su modo de canal. Para aplicar más de un canal, combine las constantes channeltype usando operadores a nivel de bits. Consulte esta lista de constantes de canal.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::commentImage

(PECL imagick 2, PECL imagick 3)

Imagick::commentImage — Añade un comentario a la imagen

### Descripción

public function Imagick::commentImage(string `$comment`): bool

Añade un comentario a la imagen.

### Parámetros

`comment`

  El comentario a añadir

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Usar Imagick::commentImage():

Comentar una imagen y recuperar el comentario:

    <?php

    /* Crear un nuevo objeto Imagick */
    $im = new imagick();

    /* Crear una imagen vacía */
    $im->newImage(100, 100, new ImagickPixel("red"));

    /* Añadir el comentario a la imagen */
    $im->commentImage("¡Hola Mundo!");

    /* Mostrar el comentario */
    echo $im->getImageProperty("comment");

    ?>

# Imagick::compareImageChannels

(PECL imagick 2, PECL imagick 3)

Imagick::compareImageChannels — Devuelve la diferencia entre una o más imágenes

### Descripción

public function Imagick::compareImageChannels(Imagick `$image`, int `$channelType`, int `$metricType`): array

Compara una o más imágenes y devuelve la imagen de diferencia.

### Parámetros

`image`

  Un objeto Imagick que contiene la imagen a comparar.

`channelType`

  Proporcione cualquier constante de canal que sea válida para el modo de canal. Para aplicar más de un canal, combine las constantes channeltype usando operadores a nivel de bits. Consulte esta lista de constantes de canal.

`metricType`

  Una de las constantes de tipos de métrica.

### Valores devueltos

Array que consiste en `new_wand` y `distortion`.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::compareImageLayers

(PECL imagick 2, PECL imagick 3)

Imagick::compareImageLayers — Devuelve la región circundante máxima entre imágenes

### Descripción

public function Imagick::compareImageLayers(int `$method`): Imagick

Compara cada imagen con la siguiente en una secuencia y devuelve la región circundante máxima de cualesquiera deferencias de píxeles que se descubra. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

### Parámetros

`method`

  Una de las constantes de método de capas.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Usar Imagick::compareImageLayers()

Comparar las capas de la imagen

    <?php
    /* crear un nuevo objeto imagick */
    $im = new Imagick("test.gif");

    /* optimizar las capas de la imagen */
    $resultado = $im->compareImageLayers(imagick::LAYERMETHOD_COALESCE);

    /* trabajar sobre el $resultado */
    ?>

### Ver también

- Imagick::optimizeImageLayers() - Elimina las porciones recurrentes de imágenes a optimizar
- Imagick::writeImages() - Escribe una imagen o secuencia de imágenes
- Imagick::writeImage() - Escribe una imagen al nombre de fichero especificado

# Imagick::compareImages

(PECL imagick 2, PECL imagick 3)

Imagick::compareImages — Compara una imagen con otra reconstruida

### Descripción

public function Imagick::compareImages(Imagick `$compare`, int `$metric`): array

Devuelve un array que contiene una imagen reconstruida y las diferencias entre las imágenes.

### Parámetros

`compare`

  Una imagen a comparar.

`metric`

  Proporcione una constante de tipo de métrica válida. Consulte esta lista de constantes métricas.

### Valores devueltos

Devuelve un array que contiene una imagen reconstruida y las diferencias entre imágenes.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Uso de Imagick::compareImages():

Comparar imágenes y mostrar la imagen reconstruida

    <?php

    $imagen1 = new imagick("imagen1.png");
    $imagen1 = new imagick("imagen1.png");

    $resultado = $imagen1->compareImages($imagen1, Imagick::METRIC_MEANSQUAREERROR);
    $resultado[0]->setImageFormat("png");

    header("Content-Type: image/png");
    echo $resultado[0];

    ?>

# Imagick::compositeImage

(PECL imagick 2, PECL imagick 3)

Imagick::compositeImage — Compone una imagen en otra

### Descripción

public function Imagick::compositeImage(
Imagick `$composite_object`,
int `$composite`,
int `$x`,
int `$y`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Compone una imagen en otra en el índice especificado. Debería proporcionarse cualquier argumento necesario para el algoritmo de composición a setImageArtifact con 'compose:args' como el primer parámetro y los datos como el segundo.

### Parámetros

`composite_object`

  Objeto Imagick que guarda la imagen compuesta

`compose`

  Operador de composición. Véase Constantes de Operadores de Composición

`x`

  El índice de la columna de la imagen compuesta

`y`

  El índice de la fila de la imagen compuesta

`channel`

  Proporcione cualquier constante de canal que sea válida para su modo de canal. Para aplicar más de un canal, combine las constantes channeltype usando operadores a nivel de bits. Consulte esta lista de constantes de canal.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Empleo de Imagick::compositeImage():

Componer dos imágenes con el método de composición 'mathematics'

    <?php

    // Equivalente a ejecutar el comando
    // convert src1.png src2.png -compose mathematics -define compose:args="1,0,-0.5,0.5" -composite output.png

    $src1 = new \Imagick("./src1.png");
    $src2 = new \Imagick("./src2.png");

    $src1->setImageVirtualPixelMethod(Imagick::VIRTUALPIXELMETHOD_TRANSPARENT);
    $src1->setImageArtifact('compose:args', "1,0,-0.5,0.5");
    $src1->compositeImage($src2, Imagick::COMPOSITE_MATHEMATICS, 0, 0);
    $src1->writeImage("./output.png");

    ?>

### Ver también

- Imagick::setImageArtifact() - Define el artefacto de la imagen

# Imagick::__construct

(PECL imagick 2, PECL imagick 3)

Imagick::__construct — El constructor Imagick

### Descripción

public function Imagick::__construct(mixed `$files` = ?)

Crea una instancia Imagick para una imagen específica o para un conjunto de imágenes.

### Parámetros

`files`

  La ruta hasta la imagen a cargar, o un array de rutas. Pueden incluir comodines en los nombres de los ficheros, o pueden ser URLs.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::contrastImage

(PECL imagick 2, PECL imagick 3)

Imagick::contrastImage — Cambia el contraste de una imagen

### Descripción

public function Imagick::contrastImage(bool `$sharpen`): bool

Mejora la diferencias de intensidad entre elementos claros y oscuros de la imagen. Establezca la agudización a un valor que no sea 0 para aumentar el contraste de la imagen, de otro modo el contraste se reduce.

### Parámetros

`sharpen`

  El valor de la agudización

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::contrastImage()

    <?php
    function contrastImage($imagePath, $contrastType) {
        $imagick = new \Imagick(realpath($imagePath));
        if ($contrastType != 2) {
            $imagick->contrastImage($contrastType);
        }

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::contrastStretchImage

(PECL imagick 2, PECL imagick 3)

Imagick::contrastStretchImage — Mejora el contraste de una imagen en color

### Descripción

public function Imagick::contrastStretchImage(float `$black_point`, float `$white_point`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Mejora el contraste de una imagen en color ajustando los colores de los píxeles de color para abarcar el rango completo de los colores disponibles. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

### Parámetros

`black_point`

  El punto blanco.

`white_point`

  El punto negro.

`channel`

  Proporcione cualquier constante de canal que sea válida para su modo de canal. Para aplicar más de un canal, combine las constantes channeltype usando operadores a nivel de bits. `Imagick::CHANNEL_ALL`. Consulte esta lista de constantes de canal.

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::convolveImage

(PECL imagick 2, PECL imagick 3)

Imagick::convolveImage — Aplica una semilla de convolución a medida a la imagen

### Descripción

public function Imagick::convolveImage(array `$kernel`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Aplica una semilla de convolución a medida a la imagen.

### Parámetros

`kernel`

  La semilla de convolución

`channel`

  Proporcione cualquier constante de canal que sea válida para su modo de canal. Para aplicar más de un canal, combine las constantes channeltype usando operadores a nivel de bits. Consulte esta lista de constantes de canal.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::convolveImage()

    <?php
    function convolveImage($imagePath, $bias, $kernelMatrix) {
        $imagick = new \Imagick(realpath($imagePath));
        //$edgeFindingKernel = [-1, -1, -1, -1, 8, -1, -1, -1, -1,];
        $imagick->setImageBias($bias * \Imagick::getQuantum());
        $imagick->convolveImage($kernelMatrix);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::count

(PECL imagick 3 >= 3.3.0)

Imagick::count — Devuelve el número de imágenes

### Descripción

public function Imagick::count(int `$mode` = 0): int

Devuelve el número de imágenes.

### Parámetros

`mode`

  Un argumento no utilizado. Actualmente, existe una funcionalidad no particularmente bien definida en PHP donde la llamada a count() sobre un objeto contable podría (o no) requerir que este método acepte un parámetro. Este parámetro está aquí para ser conforme a la interfaz de countable, incluso si el parámetro no es utilizado.

### Valores devueltos

Devuelve el número de imágenes.

# Imagick::cropImage

(PECL imagick 2, PECL imagick 3)

Imagick::cropImage — Extrae una región de la imagen

### Descripción

public function Imagick::cropImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Extrae una región de la imagen.

### Parámetros

`width`

  El ancho del recorte

`height`

  El alto del recorte

`x`

  La coordenada X de la esquina superior izquierda de la región recortada

`y`

  La coordenada Y de la esquina superior izquierda de la región recortada

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::cropImage()

    <?php
    function cropImage($imagePath, $startX, $startY, $width, $height) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->cropImage($width, $height, $startX, $startY);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::cropThumbnailImage

(PECL imagick 2, PECL imagick 3)

Imagick::cropThumbnailImage — Crea una miniatura recortada

### Descripción

public function Imagick::cropThumbnailImage(int `$width`, int `$height`, bool `$legacy` = `false`): bool

Crea una miniatura de tamaño fijo ampliando o reduciendo de escala la imagen y recortando un área específica desde el centro.

### Parámetros

`width`

  El ancho de la miniatura

`height`

  El alto de la miniatura

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::current

(PECL imagick 2, PECL imagick 3)

Imagick::current — Devuelve una referencia al objeto Imagick actual

### Descripción

public function Imagick::current(): Imagick

Devuelve una referencia al objeto actual, a partir de una referencia de secuencia.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve self en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::cycleColormapImage

(PECL imagick 2, PECL imagick 3)

Imagick::cycleColormapImage — Desplaza el mapa de colores de una imagen

### Descripción

public function Imagick::cycleColormapImage(int `$displace`): bool

Desplaza el mapa de colores de una imagen por el número de posiciones dados. Si se realiza un ciclo del mapa de colores varias veces se puede obtener un efecto psicodélico.

### Parámetros

`displace`

  La cantidad de desplazamiento del mapa de colores.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::decipherImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::decipherImage — Descifra una imagen

### Descripción

public function Imagick::decipherImage(string `$passphrase`): bool

Descifra una imagen que ha sido cifrada anteriormente. La iamgen debe ser cifrada usando Imagick::encipherImage(). Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.9 o superior.

### Parámetros

`passphrase`

  La frase de contraseña

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ver también

- Imagick::encipherImage() - Cifra una imagen

# Imagick::deconstructImages

(PECL imagick 2, PECL imagick 3)

Imagick::deconstructImages — Devuelve las diferencias de ciertos píxeles entre dos imágenes

### Descripción

public function Imagick::deconstructImages(): Imagick

Compara cada imagen con la siguiente en la secuencia, y devuelve la región máxima de encuadre de los píxeles diferentes que descubre.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un nuevo objeto Imagick en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::deleteImageArtifact

(PECL imagick 3)

Imagick::deleteImageArtifact — Borra un artefacto de imagen

### Descripción

public function Imagick::deleteImageArtifact(string `$artifact`): bool

Borra un artefacto asociado con la imagen. La diferencia entre las propiedades de imagen y los artefactos de imagen es que las propiedades son públicas y los artefactos son privados. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.5.7 o superior.

### Parámetros

`artifact`

  El nombre del artefacto a borrar.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ver también

- Imagick::setImageArtifact() - Define el artefacto de la imagen
- Imagick::getImageArtifact() - Obtener el artefacto de imagen

# Imagick::deleteImageProperty

(PECL imagick 3 >= 3.3.0)

Imagick::deleteImageProperty — Elimina una propiedad de imagen

### Descripción

public function Imagick::deleteImageProperty(string `$name`): bool

Elimina una propiedad de imagen.

### Parámetros

`name`

  El nombre de la propiedad a eliminar.

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::deskewImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.3.0)

Imagick::deskewImage — Elimina la torción de la imagen

### Descripción

public function Imagick::deskewImage(float `$threshold`): bool

Eeste método se puede usar para eliminar la torción de, por ejemplo, imágenes escaneadas donde el papel no estaba debidamente colocado en la superfice del escáner. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.5 o superior.

### Parámetros

`threshold`

  Umbral de detorción

### Valores devueltos

### Ejemplos

Ejemplo #1 Imagick::deskewImage()

    <?php
    function deskewImage($threshold) {
        $imagick = new \Imagick(realpath("images/NYTimes-Page1-11-11-1918.jpg"));
        $deskewImagick = clone $imagick;

        //Esto es lo único que se requiere para eliminar la torción.
        $deskewImagick->deskewImage($threshold);

        //El resto de este ejemplo es para hacer el resultado obvio, ya que
        //de lo contrario no sería obvio.
        $trim = 9;

        $deskewImagick->cropImage($deskewImagick->getImageWidth() - $trim, $deskewImagick->getImageHeight(), $trim, 0);
        $imagick->cropImage($imagick->getImageWidth() - $trim, $imagick->getImageHeight(), $trim, 0);
        $deskewImagick->resizeimage($deskewImagick->getImageWidth() / 2, $deskewImagick->getImageHeight() / 2, \Imagick::FILTER_LANCZOS, 1);
        $imagick->resizeimage($imagick->getImageWidth() / 2, $imagick->getImageHeight() / 2, \Imagick::FILTER_LANCZOS, 1);
        $newCanvas = new \Imagick();
        $newCanvas->newimage($imagick->getImageWidth() + $deskewImagick->getImageWidth() + 20, $imagick->getImageHeight(), 'red', 'jpg');
        $newCanvas->compositeimage($imagick, \Imagick::COMPOSITE_COPY, 5, 0);
        $newCanvas->compositeimage($deskewImagick, \Imagick::COMPOSITE_COPY, $imagick->getImageWidth() + 10, 0);

        header("Content-Type: image/jpg");
        echo $newCanvas->getImageBlob();
    }

    ?>

# Imagick::despeckleImage

(PECL imagick 2, PECL imagick 3)

Imagick::despeckleImage — Reduce el ruido speckle de una imagen

### Descripción

public function Imagick::despeckleImage(): bool

Reduce el ruido speckle de una imagen, preservando los bordes de la imagen original.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::despeckleImage()

    <?php
    function despeckleImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->despeckleImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::destroy

(PECL imagick 2, PECL imagick 3)

Imagick::destroy — Destruye un objeto Imagick

### Descripción

public function Imagick::destroy(): bool

Destruye el objeto Imagick y libera todos los recursos asociados. Este método está deprecado, en favor del método Imagick::clear.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::displayImage

(PECL imagick 2, PECL imagick 3)

Imagick::displayImage — Muestra una imagen

### Descripción

public function Imagick::displayImage(string `$servername`): bool

Este método muestra una imagen en un servidor X.

### Parámetros

`servername`

  El nombre del servidor X

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::displayImages

(PECL imagick 2, PECL imagick 3)

Imagick::displayImages — Muestra una imagen o una secuencia de imágenes

### Descripción

public function Imagick::displayImages(string `$servername`): bool

Muestra una imagen o una secuencia de imágenes en un servidor X.

### Parámetros

`servername`

  El nombre del servidor X

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::distortImage

(PECL imagick 2 >= 2.0.1, PECL imagick 3)

Imagick::distortImage — Deforma una imagen utilizando varios métodos de distorsión

### Descripción

public function Imagick::distortImage(int `$method`, array `$arguments`, bool `$bestfit`): bool

Deforma una imagen utilizando varios métodos de distorsión, mapeando la paleta de colores de la imagen de origen a una nueva imagen destino normalmente del mismo tamaño que la imagen de origen, a menos que 'bestfit' esté establecido a `true`.

Si 'bestfit' está habilitado, y la distorsión lo permite, la imagen destino se ajusta para asegurarse de que la 'imagen' de origen entera se ajustará dentro de la imagen destino final, la cuál será redimensionada e compensada acordemente. También, en la mayoría de los casos el índice virtual de la imagen de origen será tomado en cuenta en el mapeado.

Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.6 o superior.

### Parámetros

`method`

  El método de distorsión de la imagen. Véase constantes de distorsión

`arguments`

  Los argumentos para este método de distorsión

`bestfit`

  Intenta redimensionar la imagen destino para ajustarse a la imagen de origen deformada

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Usar Imagick::distortImage():

Deformar una imagen y mostrarla en el navegador.

    <?php
    /* Crear un nuevo objeto */
    $im = new Imagick();

    /* Crear un nuevo patrón de tablero de ajedrez */
    $im->newPseudoImage(100, 100, "pattern:checkerboard");

    /* Establecer el formato de la imagen a png */
    $im->setImageFormat('png');

    /* Rellenar las nuevas áreas visibles con transparente */
    $im->setImageVirtualPixelMethod(Imagick::VIRTUALPIXELMETHOD_TRANSPARENT);

    /* Activar el mate */
    $im->setImageMatte(true);

    /* Puntos de control para la distorsión */
    $puntosControl = array( 10, 10,
                            10, 5,

                            10, $im->getImageHeight() - 20,
                            10, $im->getImageHeight() - 5,

                            $im->getImageWidth() - 10, 10,
                            $im->getImageWidth() - 10, 20,

                            $im->getImageWidth() - 10, $im->getImageHeight() - 10,
                            $im->getImageWidth() - 10, $im->getImageHeight() - 30);

    /* Realizar la distorsión */
    $im->distortImage(Imagick::DISTORTION_PERSPECTIVE, $puntosControl, true);

    /* Imprimir la imagen */
    header("Content-Type: image/png");
    echo $im;
    ?>

Resultado del ejemplo anterior es similar a:

### Ver también

- Imagick::blurImage() - Añade un filtro de borrosidad a la imagen
- Imagick::motionBlurImage() - Simula borrosidad en movimiento
- Imagick::radialBlurImage() - Hace borrosa de forma radial una imagen

# Imagick::drawImage

(PECL imagick 2, PECL imagick 3)

Imagick::drawImage — Renderiza el objeto ImagickDraw a la imagen actual

### Descripción

public function Imagick::drawImage(ImagickDraw `$draw`): bool

Renderiza el objeto ImagickDraw a la imagen actual.

### Parámetros

`draw`

  Las operaciones de dibujo para renderizar a la imagen.

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::edgeImage

(PECL imagick 2, PECL imagick 3)

Imagick::edgeImage — Mejora los bordes de la imagen

### Descripción

public function Imagick::edgeImage(float `$radius`): bool

Mejora los bordes de la imagen con un filtro de convolución del radio dado. Use un radio de 0 y éste será autoseleccionado.

### Parámetros

`radius`

  El radio de la operación.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::edgeImage()

    <?php
    function edgeImage($imagePath, $radius) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->edgeImage($radius);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::embossImage

(PECL imagick 2, PECL imagick 3)

Imagick::embossImage — Devuelve una imagen en escala de grises con un efecto tridimensional

### Descripción

public function Imagick::embossImage(float `$radius`, float `$sigma`): bool

Devuelve una imagen en escala de grises con un efecto tridimensional. Se convoluciona la imagen con un operador gaussiano del radio y desviación estándar (sigma) dados. Para obtener resultados razonables, el radio debería ser mayor que sigma. Use un radio de 0 y se elegirá un radio apropiado automáticamente.

### Parámetros

`radius`

  El radio de el efecto

`sigma`

  El valor sigma del efecto

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::embossImage()

    <?php
    function embossImage($imagePath, $radius, $sigma) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->embossImage($radius, $sigma);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::encipherImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::encipherImage — Cifra una imagen

### Descripción

public function Imagick::encipherImage(string `$passphrase`): bool

Covierte los píxeles planos en píxeles cifrados. La imagen no es legible hasta que haya sido descifrada usando Imagick::decipherImage() Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.9 o superior.

### Parámetros

`passphrase`

  La frase de contraseña

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ver también

- Imagick::decipherImage() - Descifra una imagen

# Imagick::enhanceImage

(PECL imagick 2, PECL imagick 3)

Imagick::enhanceImage — Mejora la calidad de una imagen ruidosa

### Descripción

public function Imagick::enhanceImage(): bool

Mejora la calidad de una imagen ruidosa con un filtro digital.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::enhanceImage()

    <?php
    function enhanceImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->enhanceImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::equalizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::equalizeImage — Iguala el histograma de una imagen

### Descripción

public function Imagick::equalizeImage(): bool

Iguala el histograma de una imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::equalizeImage()

    <?php
    function equalizeImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->equalizeImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::evaluateImage

(PECL imagick 2, PECL imagick 3)

Imagick::evaluateImage — Aplica una expresión a una imagen

### Descripción

public function Imagick::evaluateImage(int `$op`, float `$constant`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Aplica una expresión aritmética, relacional o lógica a una imagen. Utilice estos operadores para aclarar u oscurecer una imagen, para aumentar o reducir el contraste, o para producir una imagen invertida.

### Parámetros

`op`

  El operador de evaluación

`constant`

  El valor del operador

`channel`

  Proporciona una constante de canal válida para su modo de canal. Para utilizar más de un canal, combine las constantes de tipo de canal utilizando los operadores a nivel de bits. Consulte la lista de constantes de canal.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::evaluateImage()

Uso de evaluateImage para reducir la opacidad de una imagen.

    <?php
    // Creación de un nuevo objeto con la imagen
    $im = new Imagick('example-alpha.png');

    // Reducción del alpha en un 50%
    $im->evaluateImage(Imagick::EVALUATE_DIVIDE, 2, Imagick::CHANNEL_ALPHA);

    // Mostrar la imagen
    header("Content-Type: image/png");
    echo $im;
    ?>

# Imagick::exportImagePixels

(PECL imagick 2 >=2.3.0, PECL imagick 3)

Imagick::exportImagePixels — Exporta los píxeles brutos de la imagen

### Descripción

public function Imagick::exportImagePixels(
int `$x`,
int `$y`,
int `$width`,
int `$height`,
string `$map`,
int `$STORAGE`
): array

Exporta los píxeles de la imagen a un array. El mapa define el orden de exportación de los píxeles. El tamaño del array devuelto corresponde a `width * height * strlen(map)`. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.7 o superior.

### Parámetros

`x`

  Coordenada en X del espacio exportado.

`y`

  Coordenada en Y del espacio exportado.

`width`

  Ancho del espacio exportado.

`height`

  Alto del espacio exportado.

`map`

  Orden de los píxeles exportados. Por ejemplo, `"RGB"`. Los caracteres válidos para el mapa son R, G, B, A, O, C, Y, M, K, I y P.

`STORAGE`

  Consulte la lista de constantes de tipo pixel

### Valores devueltos

Devuelve un array que contiene los valores de los píxeles.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::exportImagePixels()

Exportación de los píxeles de la imagen a un array.

    <?php

    /* Crea un nuevo objeto */
    $im = new Imagick();

    /* Crea una nueva imagen */
    $im->newPseudoImage(0, 0, "magick:rose");

    /* Exporta los píxeles de la imagen */
    $pixels = $im->exportImagePixels(10, 10, 2, 2, "RGB", Imagick::PIXEL_CHAR);

    /* Visualización */
    var_dump($pixels);
    ?>

El ejemplo anterior mostrará:

    array(12) {
      [0]=>
      int(72)
      [1]=>
      int(64)
      [2]=>
      int(57)
      [3]=>
      int(69)
      [4]=>
      int(59)
      [5]=>
      int(43)
      [6]=>
      int(124)
      [7]=>
      int(120)
      [8]=>
      int(-96)
      [9]=>
      int(91)
      [10]=>
      int(84)
      [11]=>
      int(111)
    }

# Imagick::extentImage

(PECL imagick 2, PECL imagick 3)

Imagick::extentImage — Establecer el tamaño de la imagen

### Descripción

public function Imagick::extentImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Método cómodo para establecer el tamaño de una imagen. El método establece el tamaño de la imagen y permite ajustar las coordenadas x,y donde comienza el nuevo área. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.1 o superior.

Precaución

Antes de ImageMagick 6.5.7-8 (1623), $x era positivo cuando se desplazaba hacia la izquierda y negativo cuando se desplazaba hacia la derecha, e $y era positivo cuando se desplazaba una imagen hacia arriba y negativo cuando se desplazaba hacia abajo. Entre ImageMagick 6.3.7 (1591) e ImageMagick 6.5.7-8 (1623), los ejes de $x e $y se voltearon, por lo que $x era negativo cuando se desplazaba hacia la izquierda y positivo cuando se desplazaba hacia la derecha, e $y era negativo cuando se desplazaba una imagen hacia arriba y positivo cuando se desplazaba hacia abajo. Entre ImageMagick 6.5.7-8 (1623) e ImageMagick 6.6.9-7 (1641), los ejes de $x e $y se volvieron a voltear a la funcionalidad anterior de ImageMagick 6.5.7-8 (1623).

### Parámetros

`width`

  El nuevo ancho

`height`

  El nuevo alto

`x`

  Posición X para el nuevo tamaño

`y`

  Posición Y para el nuevo tamaño

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ver también

- Imagick::resizeImage() - Escala una imagen
- Imagick::thumbnailImage() - Modifica el tamaño de una imagen
- Imagick::cropImage() - Extrae una región de la imagen

# Imagick::filter

(PECL imagick 3 >= 3.3.0)

Imagick::filter — Aplica un núcleo de convolución personalizado a la imagen

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::filter(ImagickKernel `$ImagickKernel`, int `$channel` = Imagick::CHANNEL_UNDEFINED): bool

Aplica un núcleo de convolución personalizado a la imagen.

### Parámetros

`ImagickKernel`

  Una instancia de ImagickKernel que representa un solo núcleo o una serie de núcleos vinculados.

`channel`

  Proporciona una constante de canal válida para su modo de canal. Para aplicarlo a más de un canal, combínense las constantes de canales utilizando un operador a nivel de bits. Por omisión, vale `Imagick::CHANNEL_DEFAULT`. Consúltese la lista de constantes de canales

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::filter()

    <?php
    function filter($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $matrix = [
            [-1, 0, -1],
            [0,  5,  0],
            [-1, 0, -1],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix);
        $strength = 0.5;
        $kernel->scale($strength, \Imagick::NORMALIZE_KERNEL_VALUE);
        $kernel->addUnityKernel(1 - $strength);

        $imagick->filter($kernel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::flattenImages

(PECL imagick 2, PECL imagick 3)

Imagick::flattenImages — Fusiona una secuencia de imágenes

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::flattenImages(): Imagick

Fusiona una secuencia de imágenes. Esto es práctico para combinar una serie de capas de Photoshop en una sola imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::flipImage

(PECL imagick 2, PECL imagick 3)

Imagick::flipImage — Crea una imagen por espejo vertical

### Descripción

public function Imagick::flipImage(): bool

Crea una imagen por espejo vertical, utilizando una simetría alrededor del eje de las abscisas.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::flipImage()

    <?php
    function flipImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->flipImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Ver también

- Imagick::flopimage() - Crea una imagen por espejo horizontal

# Imagick::floodFillPaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::floodFillPaintImage — Cambia el valor del color de cualquier píxel que coincida con el objetivo

### Descripción

public function Imagick::floodFillPaintImage(
mixed `$fill`,
float `$fuzz`,
mixed `$target`,
int `$x`,
int `$y`,
bool `$invert`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Cambia el valor del color de cualquier píxel que coincida con el objetivo y esté en el área inmediata. Este método es un sustituto del método obsoleto Imagick::paintFloodFillImage(). Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.8 o superior.

### Parámetros

`fill`

  Objeto ImagickPixel o una cadena que contiene el color de relleno

`fuzz`

  La cantidad de polvo de papel. Por ejemplo, definir el polvo de papel a 10 y el color rojo a una intensidad de 100 y 102 no será interpretado como el mismo color.

`target`

  Objeto ImagickPixel o una cadena que contiene el color objetivo a dibujar

`x`

  Posición X del inicio del relleno

`y`

  Posición Y del inicio del relleno

`invert`

  Si es `true` se pinta cualquier píxel que no coincida con el color objetivo.

`channel`

  Proporciona una constante de canal válida para su modo de canal. Para aplicarlo a más de un canal, combínense las constantes de canales utilizando un operador a nivel de bits. Por omisión, vale `Imagick::CHANNEL_DEFAULT`. Consúltese la lista de constantes de canales

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo de Imagick::floodfillPaintImage()

    <?php

    /* Crear un nuevo objeto imagick */
    $im = new Imagick();

    /* Crear imágenes de color rojo, verde y azul */
    $im->newImage(100, 50, "red");
    $im->newImage(100, 50, "green");
    $im->newImage(100, 50, "blue");

    /* Añadir las imágenes para que sean una */
    $im->resetIterator();
    $combinado = $im->appendImages(true);

    /* Guardar la imagen intermedia para la comparación */
    $combinado->writeImage("floodfillpaint_intermedia.png");

    /* El píxel objetivo a pintar */
    $x = 1;
    $y = 1;

    /* Obtener el color con el que vamos a pintar */
    $objetivo = $combinado->getImagePixelColor($x, $y);

    /* Pinta el píxel en la posición 1,1 negro y todos los píxeles
       cercanos que coincidan con el color objetivo */
    $combinado->floodfillPaintImage("black", 1, $objetivo, $x, $y, false);

    /* Guardar el resultado */
    $combinado->writeImage("floodfillpaint_resultado.png");
    ?>

Resultado del ejemplo anterior es similar a:

# Imagick::flopImage

(PECL imagick 2, PECL imagick 3)

Imagick::flopImage — Crea una imagen por espejo horizontal

### Descripción

public function Imagick::flopImage(): bool

Crea una imagen por espejo horizontal, utilizando una simetría alrededor del eje de las ordenadas.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::flopImage()

    <?php
    function flopImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->flopImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Ver también

- Imagick::flipimage() - Crea una imagen por espejo vertical

# Imagick::forwardFourierTransformImage

(PECL imagick 3 >= 3.3.0)

Imagick::forwardFourierTransformImage — Implementa la transformada discreta de Fourier (Discrete Fourier Transform - DFT)

### Descripción

public function Imagick::forwardFourierTransformimage(bool `$magnitude`): bool

Implementa la transformada discreta de Fourier (DFT) de la imagen ya sea como un par de imágenes magnitud/fase o como un par de imágenes reales/imaginarias.

### Parámetros

`magnitude`

  Si es verdadero, devuelve como un par magnitud/fase, de lo contrario un par de imágenes reales/imaginarias.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::forwardFourierTransformImage()

    <?php
    //Función de utilidad para forwardTransformImage
    function createMask() {
        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(0);
        $draw->setStrokeColor('rgb(255, 255, 255)');
        $draw->setFillColor('rgb(255, 255, 255)');

        // Dibuja un círculo en el eje y, con su centro
        // en x, y que toca el origen
        $draw->circle(250, 250, 220, 250);

        $imagick = new \Imagick();
        $imagick->newImage(512, 512, "black");
        $imagick->drawImage($draw);
        $imagick->gaussianBlurImage(20, 20);
        $imagick->autoLevelImage();

        return $imagick;
    }

    function forwardFourierTransformImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->resizeimage(512, 512, \Imagick::FILTER_LANCZOS, 1);

        $mask = createMask();
        $imagick->forwardFourierTransformImage(true);

        @$imagick->setimageindex(0);
        $magnitude = $imagick->getimage();

        @$imagick->setimageindex(1);
        $imagickPhase = $imagick->getimage();

        if (true) {
            $imagickPhase->compositeImage($mask, \Imagick::COMPOSITE_MULTIPLY, 0, 0);
        }

        if (false) {
            $output = clone $imagickPhase;
            $output->setimageformat('png');
            header("Content-Type: image/png");
            echo $output->getImageBlob();
        }

        $magnitude->inverseFourierTransformImage($imagickPhase, true);

        $magnitude->setimageformat('png');
        header("Content-Type: image/png");
        echo $magnitude->getImageBlob();
    }

    ?>

# Imagick::frameImage

(PECL imagick 2, PECL imagick 3)

Imagick::frameImage — Añade un borde tridimensional simulado

### Descripción

public function Imagick::frameImage(
mixed `$matte_color`,
int `$width`,
int `$height`,
int `$inner_bevel`,
int `$outer_bevel`
): bool

Añade un borde tridimensional simulado alrededor de la imagen. El ancho y alto especifican el ancho del borde de las caras verticales y horizontales del marco. Los biseles interior y exterior indican el ancho de las sombras interiores y exteriores del marco.

### Parámetros

`matte_color`

  Objeto ImagickPixel o una cadena que representa el color mate

`width`

  El ancho del borde

`height`

  El alto del borde

`inner_bevel`

  El ancho del bisel interior

`outer_bevel`

  El ancho del bisel exterior

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL imagick 2.1.0 | Ahora se permite que una cadena represente el color como el primer parámetro. Versiones anteriores sólo permitían un objeto ImagickPixel.

### Ejemplos

Ejemplo #1 Imagick::frameImage()

    <?php
    function frameImage($imagePath, $color, $width, $height, $innerBevel, $outerBevel) {
        $imagick = new \Imagick(realpath($imagePath));

        $width = $width + $innerBevel + $outerBevel;
        $height = $height + $innerBevel + $outerBevel;

        $imagick->frameimage(
            $color,
            $width,
            $height,
            $innerBevel,
            $outerBevel
        );
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::functionImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::functionImage — Aplica una función sobre la imagen

### Descripción

public function Imagick::functionImage(int `$function`, array `$arguments`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Aplica una expresión aritmética, relacional o lógica a una pseudo-imagen.

Consulte también los » ejemplos de ImageMagick v6 - Transformaciones de imágenes — Función, evaluación de varios argumentos.

Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.9 o superior.

### Parámetros

`function`

  Consulte la lista de constantes de función.

`arguments`

  Array de argumentos a pasar a la función.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Crea un gradiente sinusoidal

    <?php
    $imagick = new Imagick();
    $imagick->newPseudoImage(200, 200, 'gradient:black-white');
    $arguments = array(3, -90);
    $imagick->functionImage(Imagick::FUNCTION_SINUSOID, $arguments);

    header("Content-Type: image/png");
    $imagick->setImageFormat("png");
    echo $imagick->getImageBlob();
    ?>

Resultado del ejemplo anterior es similar a:

Ejemplo #2 Crea un gradiente desde el polinomio (4x^2 - 4x + 1)

    <?php
    $imagick = new Imagick();
    $imagick->newPseudoImage(200, 200, 'gradient:black-white');
    $arguments = array(4, -4, 1);
    $imagick->functionImage(Imagick::FUNCTION_POLYNOMIAL, $arguments);

    header("Content-Type: image/png");
    $imagick->setimageformat("png");
    echo $imagick->getImageBlob();
    ?>

Resultado del ejemplo anterior es similar a:

Ejemplo #3 Crea un gradiente complejo desde el polinomio (4x^2 - 4x^2 + 1) modulado por un gradiente sinusoidal

    <?php
    $imagick1 = new Imagick();
    $imagick1->newPseudoImage(200, 200, 'gradient:black-white');
    $arguments = array(9, -90);
    $imagick1->functionImage(Imagick::FUNCTION_SINUSOID, $arguments);

    $imagick2 = new Imagick();
    $imagick2->newPseudoImage(200, 200, 'gradient:black-white');
    $arguments = array(0.5, 0);
    $imagick2->functionImage(Imagick::FUNCTION_SINUSOID, $arguments);
    $imagick1->compositeimage($imagick2, Imagick::COMPOSITE_MULTIPLY, 0, 0);

    header("Content-Type: image/png");
    $imagick1->setImageFormat("png");
    echo $imagick1->getImageBlob();
    ?>

Resultado del ejemplo anterior es similar a:

# Imagick::fxImage

(PECL imagick 2, PECL imagick 3)

Imagick::fxImage — Evalúa una expresión por cada píxel de la imagen

### Descripción

public function Imagick::fxImage(string `$expression`, int `$channel` = Imagick::CHANNEL_DEFAULT): Imagick

Evalúa una expresión por cada píxel de la imagen. Consulte » El Operador de Imagen de Efectos Especiales Fx para más información.

### Parámetros

`expression`

  La expresión.

`channel`

  Proporcione cualquier constante de canal que sea válida para su modo de canal. Para aplicar más de un canal, combine las constantes channeltype usando operadores a nivel de bits. Consulte esta lista de constantes de canal.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::fxImage()

    <?php
    function fxImage() {
        $imagick = new \Imagick();
        $imagick->newPseudoImage(200, 200, "xc:white");

        $fx = 'xx=i-w/2; yy=j-h/2; rr=hypot(xx,yy); (.5-rr/140)*1.2+.5';
        $fxImage = $imagick->fxImage($fx);

        header("Content-Type: image/png");
        $fxImage->setimageformat('png');
        echo $fxImage->getImageBlob();
    }

    ?>

# Imagick::gammaImage

(PECL imagick 2, PECL imagick 3)

Imagick::gammaImage — Corrección gamma de una imagen

### Descripción

public function Imagick::gammaImage(float `$gamma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Corrección gamma de una imagen. La misma imagen vista en diferentes dispositivos tendrá diferencias perceptuales en la manera en que la intensidad de la imagen esté representada en la pantalla. Especifique niveles gamma indivuduales para los canales rojo, verde y azul, o ajústelos todos con el parámetro gamma. El rango de valores es típicamente desde 0.8 a 2.3.

### Parámetros

`gamma`

  La cantidad de corrección gamma.

`channel`

  Proporcione cualquier constante de canal que sea válida para su modo de canal. Para aplicar más de un canal, combine las constantes channeltype usando operadores a nivel de bits. Consulte esta lista de constantes de canal.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::gammaImage()

    <?php
    function gammaImage($imagePath, $gamma, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->gammaImage($gamma, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::gaussianBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::gaussianBlurImage — Hace borrosa una imagen

### Descripción

public function Imagick::gaussianBlurImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Hace borrosa una imagen. Se convoluciona la imagen con un operador gaussiano del radio y la desviación estándar (sigma) dados. Para obtener resultados razonables, el radio debería ser mayor que sigma. Use un radio de 0 y se seleccionará un radio adecuado automáticamente.

### Parámetros

`radius`

  El radio gaussiano, en píxeles, sin contar el píxel central.

`sigma`

  La desviación estándar gaussiana, en píxeles.

`channel`

  Proporcione cualquier constante de canal que sea válida para su modo de canal. Para aplicar más de un canal, combine las constantes channeltype usando operadores a nivel de bits. Consulte esta lista de constantes de canal.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::gaussianBlurImage()

    <?php
    function gaussianBlurImage($imagePath, $radius, $sigma, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->gaussianBlurImage($radius, $sigma, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::getColorspace

(PECL imagick 3)

Imagick::getColorspace — Obtiene el espacio de colores

### Descripción

public function Imagick::getColorspace(): int

Obtiene el valor global del espacio de colores. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.5.7 o superior.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un entero que puede ser comparado con las constantes COLORSPACE.

# Imagick::getCompression

(PECL imagick 2, PECL imagick 3)

Imagick::getCompression — Lee el tipo de compresión

### Descripción

public function Imagick::getCompression(): int

Lee el tipo de compresión.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la constante de compresión.

# Imagick::getCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::getCompressionQuality — Lee la calidad de la compresión

### Descripción

public function Imagick::getCompressionQuality(): int

Lee la calidad de la compresión.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un integer que describe la calidad de la compresión.

# Imagick::getCopyright

(PECL imagick 2, PECL imagick 3)

Imagick::getCopyright — Devuelve el copyright de la API ImageMagick

### Descripción

public static function Imagick::getCopyright(): string

Devuelve el copyright de la API ImageMagick.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un string, en caso de éxito.

# Imagick::getFilename

(PECL imagick 2, PECL imagick 3)

Imagick::getFilename — Lee el nombre del fichero asociado a una secuencia

### Descripción

public function Imagick::getFilename(): string

Lee el nombre del fichero asociado a una secuencia.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una cadena en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getFont

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::getFont — Obtiene la fuente de caracteres

### Descripción

public function Imagick::getFont(): string

Devuelve la propiedad de la fuente de caracteres del objeto. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.7 o superior.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un string que contiene el nombre de la fuente de caracteres o `false` si la fuente no está definida.

### Ver también

- Imagick::setFont() - Configura la fuente
- ImagickDraw::setFont() - Establece la fuente especificada completamente para usarla cuando se escribe texto
- ImagickDraw::getFont() - Devuelve la fuente

# Imagick::getFormat

(PECL imagick 2, PECL imagick 3)

Imagick::getFormat — Devuelve el formato de la imagen Imagick

### Descripción

public function Imagick::getFormat(): string

Devuelve el formato de la imagen Imagick.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el formato de la imagen Imagick.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getGravity

(PECL imagick 2, PECL imagick 3)

Imagick::getGravity — Obtiene la gravedad

### Descripción

public function Imagick::getGravity(): int

Obtiene la propiedad global de gravedad para el objeto Imagick. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.0 o superior.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la propiedad de gravedad. Consúltese la lista de constantes de gravedad.

# Imagick::getHomeURL

(PECL imagick 2, PECL imagick 3)

Imagick::getHomeURL — Devuelve la URL de ImageMagick

### Descripción

public static function Imagick::getHomeURL(): string

Devuelve la URL de ImageMagick.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la URL de ImageMagick.

# Imagick::getImage

(PECL imagick 2, PECL imagick 3)

Imagick::getImage — Devuelve un nuevo objeto Imagick

### Descripción

public function Imagick::getImage(): Imagick

Devuelve un nuevo objeto Imagick.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un nuevo objeto Imagick.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageAlphaChannel

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageAlphaChannel — Verifica si la imagen tiene un canal alfa

### Descripción

public function Imagick::getImageAlphaChannel(): bool

Devuelve si la imagen tiene un canal alfa.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si la imagen tiene un valor de canal alfa y `false` en caso contrario, es decir, que la imagen es RGB en lugar de RGBA o CMYK en lugar de CMYKA.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL imagick 3.6.0 | Ahora devuelve un bool ; anteriormente se devolvía un int.

# Imagick::getImageArtifact

(PECL imagick 3)

Imagick::getImageArtifact — Obtener el artefacto de imagen

### Descripción

public function Imagick::getImageArtifact(string `$artifact`): string

Obtiene un artefacto asociado con la imagen. La diferencia entre las propiedades de imagen y los artefactos de imagen es que las propiedades son públicas y los artefactos son privados. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.5.7 o superior.

### Parámetros

`artifact`

  El nombre del artefacto

### Valores devueltos

Devuelve el valor del artefacto si se tuvo éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ver también

- Imagick::setImageArtifact() - Define el artefacto de la imagen
- Imagick::deleteImageArtifact() - Borra un artefacto de imagen

# Imagick::getImageAttribute

(PECL imagick 2, PECL imagick 3)

Imagick::getImageAttribute — Obtiene un atributo nombrado

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::getImageAttribute(string `$key`): string

Obtiene un atributo nombrado.

### Parámetros

`key`

  La clave del atributo a obtener.

### Valores devueltos

# Imagick::getImageBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBackgroundColor — Devuelve el color de fondo

### Descripción

public function Imagick::getImageBackgroundColor(): ImagickPixel

Devuelve el color de fondo.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el color de fondo en forma de objeto ImagickPixel.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBlob — Devuelve la secuencia de imágenes como un blob

### Descripción

public function Imagick::getImageBlob(): string

Implementa un formato directo en memoria. Devuelve la secuencia de imágenes en forma de string. El formato de la imagen determina el formato del BLOB devuelto (GIF, JPEG, PNG, etc.). Para devolver un formato diferente, utilice la función Imagick::setImageFormat().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un string que contiene las imágenes.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageBluePrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBluePrimary — Devuelve el punto primario azul de la cromaticidad

### Descripción

public function Imagick::getImageBluePrimary(): array

Devuelve el punto primario azul de la cromaticidad de una imagen.

### Parámetros

`x`

  El punto x primario azul de la cromaticidad.

`y`

  El punto y primario azul de la cromaticidad.

### Valores devueltos

Matriz consistente en las coordenadas "x" e "y" del punto.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageBorderColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBorderColor — Devuelve el color del borde de la imagen

### Descripción

public function Imagick::getImageBorderColor(): ImagickPixel

Devuelve el color del borde de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageChannelDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelDepth — Obtiene la profundidad de un canal de imagen en particular

### Descripción

public function Imagick::getImageChannelDepth(int `$channel`): int

Obtiene la profundidad de un canal de imagen en particular.

### Parámetros

`channel`

  Proporciona una constante de canal válida para su modo de canal. Para aplicarlo a más de un canal, combínense las constantes de canales utilizando un operador a nivel de bits. Por omisión, vale `Imagick::CHANNEL_DEFAULT`. Consúltese la lista de constantes de canales

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::getImageChannelDistortion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelDistortion — Compara los canales de imagen de una imagen con una imagen reconstruida

### Descripción

public function Imagick::getImageChannelDistortion(Imagick `$reference`, int `$channel`, int `$metric`): float

Compara uno o más canales de imagen de una imagen con una imagen reconstruida y devuelve la métrica de distorsión especificada.

### Parámetros

`reference`

  Objeto Imagick que se va a comparar.

`channel`

  Proporcione cualquier constante de canal que sea válida para su modo de canal. Para aplicar más de un canal, combine las constantes channeltype usando operadores a nivel de bits. Consulte esta lista de constantes de canal.

`metric`

  Una de las constantes de tipo de métrica.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageChannelDistortions

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageChannelDistortions — Obtiene las distorsiones de un canal

### Descripción

public function Imagick::getImageChannelDistortions(Imagick `$reference`, int `$metric`, int `$channel` = Imagick::CHANNEL_DEFAULT): float

Compara uno o varios canales de una imagen con una imagen reconstruida, y devuelve las medidas de la distorsión especificada. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.4 o superior.

### Parámetros

`reference`

  Objeto Imagick que contiene la referencia de la imagen.

`metric`

  Consúltese la lista de constantes de tipo de medidas.

`channel`

  Proporciona una constante de canal válida para su modo de canal. Para aplicarlo a más de un canal, combínense las constantes de canales utilizando un operador a nivel de bits. Por omisión, vale `Imagick::CHANNEL_DEFAULT`. Consúltese la lista de constantes de canales

### Valores devueltos

Devuelve un float, que describe la distorsión del canal.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageChannelExtrema

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelExtrema — Obtiene los extremos de uno o más canales de imagen

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::getImageChannelExtrema(int `$channel`): array

Obtiene los extremos (mínimo y máximo) de uno o más canales de imagen. El valor devuelto es una matriz asociativa con las claves "minima" (mínimo) y "maxima" (máximo).

### Parámetros

`channel`

  Proporcione cualquier constante de canal que sea válida para su modo de canal. Para aplicar más de un canal, combine las constantes channeltype usando operadores a nivel de bits. Consulte esta lista de constantes de canal.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageChannelKurtosis

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageChannelKurtosis — Obtiene la curtosis y la asimetría estadística de un canal específico

### Descripción

public function Imagick::getImageChannelKurtosis(int `$channel` = Imagick::CHANNEL_DEFAULT): array

Obtiene la curtosis y la asimetría estadística de un canal específico. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.9 o superior.

### Parámetros

`channel`

  Proporciona una constante de canal válida para su modo de canal. Para aplicarlo a más de un canal, combínense las constantes de canales utilizando un operador a nivel de bits. Por omisión, vale `Imagick::CHANNEL_DEFAULT`. Consúltese la lista de constantes de canales

### Valores devueltos

Devuelve una matriz con los miembros `kurtosis` (curtosis) y `skewness` (asimetría estadística).

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageChannelMean

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelMean — Obtiene la media y la desviación estándar

### Descripción

public function Imagick::getImageChannelMean(int `$channel`): array

Obtiene la media y la desviación estándar de uno o más canales de imagen.

### Parámetros

`channel`

  Proporcione cualquier constante de canal que sea válida para su modo de canal. Para aplicar más de un canal, combine las constantes channeltype usando operadores a nivel de bits. Consulte esta lista de constantes de canal.

### Valores devueltos

Devuelve una matriz con miembros `"mean"` y `"standardDeviation"`.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageChannelRange

(PECL imagick 2 >= 2.2.1, PECL imagick 3)

Imagick::getImageChannelRange — Obtiene el rango del canal

### Descripción

public function Imagick::getImageChannelRange(int `$channel`): array

Obtiene el rango de uno o más canales de imagen. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.0 o superior.

### Parámetros

`channel`

  Proporciona una constante de canal válida para su modo de canal. Para aplicarlo a más de un canal, combínense las constantes de canales utilizando un operador a nivel de bits. Por omisión, vale `Imagick::CHANNEL_DEFAULT`. Consúltese la lista de constantes de canales

### Valores devueltos

Devuelve una matriz que contiene los valores mínimo y máximo de el/los canal/es.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageChannelStatistics

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelStatistics — Devuelve estadísticas sobre cada canal de la imagen

### Descripción

public function Imagick::getImageChannelStatistics(): array

Devuelve estadísticas sobre cada canal de la imagen. Las estadísticas incluyen la profundidad del canal, sus mínimos y máximos, la media, y la desviación estándar.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::getImageClipMask

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageClipMask — Obtiene la máscara de recorte de la imagen

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::getImageClipMask(): Imagick

Devuelve la máscara de recorte de la imagen. La máscara de recorte es un objeto Imagick que contiene la máscara de recorte. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.6 o superior.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un objeto Imagick que contiene la máscara de recorte.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageColormapColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColormapColor — Devuelve el color del índice del mapa de colores especficado

### Descripción

public function Imagick::getImageColormapColor(int `$index`): ImagickPixel

Devuelve el color del índice del mapa de colores especficado.

### Parámetros

`index`

  El índice en el mapa de colores de la imagen.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageColors

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColors — Lee el número de colores únicos de la imagen

### Descripción

public function Imagick::getImageColors(): int

Lee el número de colores únicos de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un int, el número de colores únicos en la imagen.

# Imagick::getImageColorspace

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColorspace — Obtiene el espacio de colores de la imagen

### Descripción

public function Imagick::getImageColorspace(): int

Obtiene el espacio de colores de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un entero que puede ser comparado con las constantes COLORSPACE.

# Imagick::getImageCompose

(PECL imagick 2, PECL imagick 3)

Imagick::getImageCompose — Devuelve el operador de composición asociado a una imagen

### Descripción

public function Imagick::getImageCompose(): int

Devuelve el operador de composición asociado a una imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::getImageCompression

(PECL imagick 3 >= 3.3.0)

Imagick::getImageCompression — Lee el tipo de compresión de la imagen

### Descripción

public function Imagick::getImageCompression(): int

Lee el tipo de compresión de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una constante de compresión.

# Imagick::getImageCompressionQuality

(PECL imagick 2 >= 2.2.2, PECL imagick 3)

Imagick::getImageCompressionQuality — Lee la calidad de compresión de la imagen

### Descripción

public function Imagick::getImageCompressionQuality(): int

Lee la calidad de compresión de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un entero que describe la calidad de la compresión de la imagen.

# Imagick::getImageDelay

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDelay — Lee el retraso de la imagen

### Descripción

public function Imagick::getImageDelay(): int

Lee el retraso de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el retraso de la imagen. Emite una excepción ImagickException en caso de fallo.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDepth — Se lee la profundidad de la imagen

### Descripción

public function Imagick::getImageDepth(): int

Se lee la profundidad de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

La profundidad de la imagen.

# Imagick::getImageDispose

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDispose — Lee el método de recuperación

### Descripción

public function Imagick::getImageDispose(): int

Lee el método de recuperación.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el método de recuperación en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageDistortion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDistortion — Compara una imagen con una imagen reconstruida

### Descripción

public function Imagick::getImageDistortion(MagickWand `$reference`, int `$metric`): float

Compara una imagen con una imagen reconstruida y devuelve la métrica de distorisión especificada.

### Parámetros

`reference`

  Objeto Imagick que se va a comparar.

`metric`

  Una de las constantes de tipo de métrica.

### Valores devueltos

Devuelve la métrica de distorsión usada en la imagen (o la mejor deducción de la misma).

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageExtrema

(PECL imagick 2, PECL imagick 3)

Imagick::getImageExtrema — Lee los extremos de una imagen

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::getImageExtrema(): array

Lee los extremos de una imagen. Devuelve un array asociativo, con las claves "min" y "max".

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array asociativo, con las claves "min" y "max".

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageFilename

(PECL imagick 2, PECL imagick 3)

Imagick::getImageFilename — Devuelve el nombre de un fichero para una imagen en una secuencia

### Descripción

public function Imagick::getImageFilename(): string

Devuelve el nombre de un fichero para una imagen en una secuencia.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un string con el nombre del fichero de la imagen.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageFormat

(PECL imagick 2, PECL imagick 3)

Imagick::getImageFormat — Devuelve el formato de una imagen en una secuencia

### Descripción

public function Imagick::getImageFormat(): string

Devuelve el formato de una imagen en una secuencia.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el formato de una imagen en una secuencia.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageGamma

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGamma — Obtiene el gamma de la imagen

### Descripción

public function Imagick::getImageGamma(): float

Obtiene el gamma de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el gamma de la imagen en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageGeometry

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGeometry — Lee las dimensiones de la imagen en un array

### Descripción

public function Imagick::getImageGeometry(): array

Devuelve el ancho y la altura de la imagen en forma de array asociativo.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array con las dimensiones de la imagen.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Uso de Imagick::getImageGeometry()

    <?php
    $imagick = new Imagick();
    $imagick->newImage(100, 200, "black");
    print_r($imagick->getImageGeometry());
    ?>

El ejemplo anterior mostrará:

    Array
    (
        [width] => 100
        [height] => 200
    )

# Imagick::getImageGravity

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageGravity — Obtiene la gravedad de la imagen

### Descripción

public function Imagick::getImageGravity(): int

Obtiene el valor de la gravedad actual de la imagen. A diferencia del método Imagick::getGravity(), este método devuelve la gravedad definida para la secuencia actual de la imagen. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.4 o superior.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la propiedad de gravedad de la imagen. Consúltese la lista de constantes de gravedad.

# Imagick::getImageGreenPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGreenPrimary — Devuelve la cromaticidad del color verde

### Descripción

public function Imagick::getImageGreenPrimary(): array

Devuelve la cromaticidad del color verde. Devuelve un array con las claves "x" y "y".

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array con las claves "x" y "y" en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageHeight

(PECL imagick 2, PECL imagick 3)

Imagick::getImageHeight — Devuelve la altura de la imagen

### Descripción

public function Imagick::getImageHeight(): int

Devuelve la altura de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la altura de la imagen en píxeles.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageHistogram

(PECL imagick 2, PECL imagick 3)

Imagick::getImageHistogram — Devuelve el histograma de la imagen

### Descripción

public function Imagick::getImageHistogram(): array

Devuelve el histograma de la imagen, en forma de un array de objetos ImagickPixel.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array de objetos ImagickPixel.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::getImageHistogram()

    <?php
    function getColorStatistics($histogramElements, $colorChannel) {
        $colorStatistics = [];

        foreach ($histogramElements as $histogramElement) {
            $color = $histogramElement->getColorValue($colorChannel);
            $color = intval($color * 255);
            $count = $histogramElement->getColorCount();

            if (array_key_exists($color, $colorStatistics)) {
                $colorStatistics[$color] += $count;
            }
            else {
                $colorStatistics[$color] = $count;
            }
        }

        ksort($colorStatistics);

        return $colorStatistics;
    }

    function getImageHistogram($imagePath) {

        $backgroundColor = 'black';

        $draw = new \ImagickDraw();
        $draw->setStrokeWidth(0); // hace las líneas lo más finas posible

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        $histogramWidth = 256;
        $histogramHeight = 100; // la altura de cada segmento RGB

        $imagick = new \Imagick(realpath($imagePath));
        //Redimensionar la imagen para que sea pequeña, de lo contrario PHP tiende a quedarse sin memoria
        //Esto podría llevar a resultados incorrectos para imágenes que son patológicamente 'pixeladas'
        $imagick->adaptiveResizeImage(200, 200, true);
        $histogramElements = $imagick->getImageHistogram();

        $histogram = new \Imagick();
        $histogram->newpseudoimage($histogramWidth, $histogramHeight * 3, 'xc:black');
        $histogram->setImageFormat('png');

        $getMax = function ($carry, $item)  {
            if ($item > $carry) {
                return $item;
            }
            return $carry;
        };

        $colorValues = [
            'red' => getColorStatistics($histogramElements, \Imagick::COLOR_RED),
            'lime' => getColorStatistics($histogramElements, \Imagick::COLOR_GREEN),
            'blue' => getColorStatistics($histogramElements, \Imagick::COLOR_BLUE),
        ];

        $max = array_reduce($colorValues['red'] , $getMax, 0);
        $max = array_reduce($colorValues['lime'] , $getMax, $max);
        $max = array_reduce($colorValues['blue'] , $getMax, $max);

        $scale =  $histogramHeight / $max;

        $count = 0;
        foreach ($colorValues as $color => $values) {
            $draw->setstrokecolor($color);

            $offset = ($count + 1) * $histogramHeight;

            foreach ($values as $index => $value) {
                $draw->line($index, $offset, $index, $offset - ($value * $scale));
            }
            $count++;
        }

        $histogram->drawImage($draw);

        header( "Content-Type: image/png" );
        echo $histogram;
    }

    ?>

# Imagick::getImageIndex

(PECL imagick 2, PECL imagick 3)

Imagick::getImageIndex — Obtiene el índice de la imagen actual

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::getImageIndex(): int

Devuelve el índice de la imagen actual en la secuencia Imagick. Este método está obsoleto. Consúltese la función Imagick::getIteratorIndex().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un integer en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::getImageInterlaceScheme — Se lee el esquema de entrelazado de la imagen

### Descripción

public function Imagick::getImageInterlaceScheme(): int

Se lee el esquema de entrelazado de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Se devuelve el esquema de entrelazado de la imagen en caso de éxito. Emite una excepción ImagickException en caso de fallo.

# Imagick::getImageInterpolateMethod

(PECL imagick 2, PECL imagick 3)

Imagick::getImageInterpolateMethod — Devuelve el método de interpolación

### Descripción

public function Imagick::getImageInterpolateMethod(): int

Devuelve el método de interpolación de la imagen especificada. El método es una de las constantes `Imagick::INTERPOLATE_*`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el método de interpolación en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageIterations

(PECL imagick 2, PECL imagick 3)

Imagick::getImageIterations — Obtiene las iteraciones de la imagen

### Descripción

public function Imagick::getImageIterations(): int

Obtiene las iteraciones de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve las iteraciones de la imagen.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageLength

(PECL imagick 2, PECL imagick 3)

Imagick::getImageLength — Devuelve el tamaño de la imagen en bytes

### Descripción

public function Imagick::getImageLength(): int

Devuelve el tamaño de la imagen en bytes.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un integer.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::getImageLength():

Obtiene el tamaño de la imagen, en bytes

    <?php
    $image = new Imagick('test.jpg');
    echo $image->getImageLength() . ' bytes';
    ?>

# Imagick::getImageMatte

(PECL imagick 2, PECL imagick 3)

Imagick::getImageMatte — Indica si la imagen tiene un canal mat

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::getImageMatte(): bool

Devuelve `true` si la imagen tiene un canal mat, y `false` en caso contrario. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::getImageMatteColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageMatteColor — Devuelve el color mate de la imagen

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::getImageMatteColor(): ImagickPixel

Devuelve el color mate de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un objeto ImagickPixel en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageMimeType

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageMimeType — Devuelve el tipo MIME de la imagen

### Descripción

public function Imagick::getImageMimeType(): string

Devuelve el tipo MIME de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# Imagick::getImageOrientation

(PECL imagick 2, PECL imagick 3)

Imagick::getImageOrientation — Lee la orientación de la imagen

### Descripción

public function Imagick::getImageOrientation(): int

Lee la orientación de la imagen. El valor devuelto es una de las constantes de orientación.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un integer en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImagePage

(PECL imagick 2, PECL imagick 3)

Imagick::getImagePage — Devuelve la geometría de la página

### Descripción

public function Imagick::getImagePage(): array

Devuelve la geometría de la página de una imagen, en forma de un array con las claves `"width"`, `"height"`, `"x"` y `"y"`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la geometría de la página de una imagen, en forma de un array con las claves `"width"`, `"height"`, `"x"` y `"y"`.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImagePixelColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImagePixelColor — Devuelve el color del píxel especificado

### Descripción

public function Imagick::getImagePixelColor(int `$x`, int `$y`): ImagickPixel

Devuelve el color del píxel especificado.

### Parámetros

`x`

  La coordenada x del píxel

`y`

  La coordenada y del píxel

### Valores devueltos

Devuelve una instancia de ImagickPixel para el color en las coordenadas dadas.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProfile — Devuelve el perfil nominado de la imagen

### Descripción

public function Imagick::getImageProfile(string `$name`): string

Devuelve el perfil nominado de la imagen.

### Parámetros

`name`

  El nombre del perfil que se va a devolver.

### Valores devueltos

Devuelve un string que contiene el perfil de la imagen.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageProfiles

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProfiles — Devuelve los perfiles de la imagen

### Descripción

public function Imagick::getImageProfiles(string `$pattern` = "*", bool `$include_values` = `true`): array

Devuelve los perfiles de la imagen que coinciden con un patrón. Si `false` se pasa como segundo argumento, solo se devuelven los nombres de los perfiles. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.6 o superior.

### Parámetros

`pattern`

  El patrón de perfil a leer.

`include_values`

  Si se deben devolver solo los nombres de los perfiles. Si `false` se proporciona, solo se devolverán los nombres de las propiedades.

### Valores devueltos

Devuelve un array con los perfiles de la imagen, o bien solo los nombres de los perfiles.

# Imagick::getImageProperties

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProperties — Devuelve las propiedades EXIF de la imagen

### Descripción

public function Imagick::getImageProperties(string `$pattern` = "*", bool `$include_values` = `true`): array

Devuelve todas las propiedades de la imagen que cumplen con un patrón. Si se pasa `false` como segundo argumento, solo se devuelven los nombres de las propiedades. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.6 o superior.

### Parámetros

`pattern`

  El patrón para los nombres de propiedades.

`include_values`

  Si se deben devolver únicamente los nombres de las propiedades. Si se proporciona `false`, entonces solo se devolverán los nombres de las propiedades.

### Valores devueltos

Devuelve un array que contiene las propiedades de la imagen, o sus nombres.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::getImageProperties()

Ejemplo de extracción de información EXIF.

    <?php

    /* Crea un objeto */
    $im = new imagick("/path/to/example.jpg");

    /* Lee las informaciones EXIF */
    $exifArray = $im->getImageProperties("exif:*");

    /* Recorre las propiedades EXIF */
    foreach ($exifArray as $name => $property)
    {
        echo "{$name} => {$property}<br />\n";
    }

    ?>

# Imagick::getImageProperty

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProperty — Devuelve una propiedad de una imagen

### Descripción

public function Imagick::getImageProperty(string `$name`): string

Devuelve una propiedad de una imagen. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.2 o superior.

### Parámetros

`name`

  El nombre de la propiedad (por ejemplo, `Exif:DateTime`)

### Valores devueltos

Devuelve una propiedad de una imagen, o `false` si el nombre solicitado no existe.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::getImageProperty()

Definición y recuperación de las propiedades de la imagen.

    <?php
    $image = new Imagick();
    $image->newImage(300, 200, "black");

    $image->setImageProperty('Exif:Make', 'Imagick');
    echo $image->getImageProperty('Exif:Make');
    ?>

### Ver también

- Imagick::setImageProperty() - Configura una propiedad de imagen

# Imagick::getImageRedPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRedPrimary — Devuelve la cromaticidad del punto rojo

### Descripción

public function Imagick::getImageRedPrimary(): array

Devuelve la cromaticidad del punto rojo en forma de un array con las claves "x" y "y".

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la cromaticidad del punto rojo en forma de un array con las claves "x" y "y". Emite una excepción ImagickException en caso de fallo.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageRegion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRegion — Extrae una región de la imagen

### Descripción

public function Imagick::getImageRegion(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Imagick

Extrae una región de la imagen y la devuelve como un nuevo objeto Imagick.

### Parámetros

`width`

  El ancho de la región extraída.

`height`

  El alto de la región extraída.

`x`

  Coordenada X de la esquina superior izquierda de la región extraída.

`y`

  Coordenada Y de la esquina superior izquierda de la región extraída.

### Valores devueltos

Extrae una región de la imagen y la devuleve como una nueva varita mágica.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageRenderingIntent

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRenderingIntent — Lee el método de renderizado de la imagen

### Descripción

public function Imagick::getImageRenderingIntent(): int

Lee el método de renderizado de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la constante de renderizado.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageResolution

(PECL imagick 2, PECL imagick 3)

Imagick::getImageResolution — Lee las resoluciones en X y Y de una imagen

### Descripción

public function Imagick::getImageResolution(): array

Lee las resoluciones en X y Y de una imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Lee las resoluciones en X y Y de una imagen.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImagesBlob

(PECL imagick 2, PECL imagick 3)

Imagick::getImagesBlob — Devuelve todas las imágenes de la secuencia en un BLOB

### Descripción

public function Imagick::getImagesBlob(): string

Implementa el formato directo en memoria. Devuelve todas las imágenes de la secuencia en forma de cadena. El formato de la imagen determina el formato del BLOB devuelto (GIF, JPEG, PNG, etc.). Para devolver un formato de imagen diferente, utilice Imagick::setImageFormat().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una cadena que contiene todas las imágenes. Emite una excepción ImagickException en caso de fallo.

# Imagick::getImageScene

(PECL imagick 2, PECL imagick 3)

Imagick::getImageScene — Devuelve la escena de la imagen

### Descripción

public function Imagick::getImageScene(): int

Devuelve la escena de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la escena de la imagen.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageSignature

(PECL imagick 2, PECL imagick 3)

Imagick::getImageSignature — Genera una firma SHA-256

### Descripción

public function Imagick::getImageSignature(): string

Genera una firma SHA-256 de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve una cadena que contiene la firma SHA-256 de la imagen.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageSize

(PECL imagick 2, PECL imagick 3)

Imagick::getImageSize — Devuelve el tamaño de la imagen en bytes

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::getImageSize(): int

Devuelve el tamaño de la imagen en bytes. Este método está deprecado en favor del método Imagick::getImageLength()

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un entero que representa el tamaño de la imagen en bytes.

# Imagick::getImageTicksPerSecond

(PECL imagick 2, PECL imagick 3)

Imagick::getImageTicksPerSecond — Se leen los ticks-por-segundo de la imagen

### Descripción

public function Imagick::getImageTicksPerSecond(): int

Se leen los ticks-por-segundo de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Se leen los ticks-por-segundo de la imagen.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageTotalInkDensity

(PECL imagick 2, PECL imagick 3)

Imagick::getImageTotalInkDensity — Lee la densidad total de tinta de la imagen

### Descripción

public function Imagick::getImageTotalInkDensity(): float

Lee la densidad total de tinta de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Lee la densidad total de tinta de la imagen. Emite una excepción ImagickException en caso de fallo.

# Imagick::getImageType

(PECL imagick 2, PECL imagick 3)

Imagick::getImageType — Obtiene el tipo posible de imagen

### Descripción

public function Imagick::getImageType(): int

Devuelve el tipo posible de imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Obtiene el tipo posible de imagen.

- `imagick::IMGTYPE_UNDEFINED`
- `imagick::IMGTYPE_BILEVEL`
- `imagick::IMGTYPE_GRAYSCALE`
- `imagick::IMGTYPE_GRAYSCALEMATTE`
- `imagick::IMGTYPE_PALETTE`
- `imagick::IMGTYPE_PALETTEMATTE`
- `imagick::IMGTYPE_TRUECOLOR`
- `imagick::IMGTYPE_TRUECOLORMATTE`
- `imagick::IMGTYPE_COLORSEPARATION`
- `imagick::IMGTYPE_COLORSEPARATIONMATTE`
- `imagick::IMGTYPE_OPTIMIZE`

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageUnits

(PECL imagick 2, PECL imagick 3)

Imagick::getImageUnits — Devuelve las unidades de resolución de la imagen

### Descripción

public function Imagick::getImageUnits(): int

Devuelve las unidades de resolución de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve las unidades de resolución de la imagen.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageVirtualPixelMethod

(PECL imagick 2, PECL imagick 3)

Imagick::getImageVirtualPixelMethod — Devuelve el método del píxel virtual

### Descripción

public function Imagick::getImageVirtualPixelMethod(): int

Devuelve el método del píxel virtual para la imagen especificada.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el método del píxel virtual para la imagen especificada.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageWhitePoint

(PECL imagick 2, PECL imagick 3)

Imagick::getImageWhitePoint — Devuelve la cromaticidad del punto blanco

### Descripción

public function Imagick::getImageWhitePoint(): array

Devuelve la cromaticidad del punto blanco, en forma de un array asociativo con las claves "x" y "y".

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la cromaticidad del punto blanco, en forma de un array asociativo con las claves "x" y "y".

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getImageWidth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageWidth — Devuelve el ancho de la imagen

### Descripción

public function Imagick::getImageWidth(): int

Devuelve el ancho de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el ancho de la imagen.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::getInterlaceScheme — Lee el esquema de entrelazado del objeto

### Descripción

public function Imagick::getInterlaceScheme(): int

Lee el esquema de entrelazado del objeto.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Lee la constante de entrelazado.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getIteratorIndex

(PECL imagick 2, PECL imagick 3)

Imagick::getIteratorIndex — Lee el índice de la imagen activa actual

### Descripción

public function Imagick::getIteratorIndex(): int

Lee el índice de la imagen activa actual en el objeto Imagick. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un entero que representa el índice de la imagen en la cola.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::getIteratorIndex()

Crea imágenes, define y recupera el índice del iterador.

    <?php
    $im = new Imagick();
    $im->newImage(100, 100, new ImagickPixel("red"));
    $im->newImage(100, 100, new ImagickPixel("green"));
    $im->newImage(100, 100, new ImagickPixel("blue"));

    $im->setIteratorIndex(1);
    echo $im->getIteratorIndex();
    ?>

### Ver también

- Imagick::setIteratorIndex() - Establece la posición del iterador
- Imagick::getImageIndex() - Obtiene el índice de la imagen actual
- Imagick::setImageIndex() - Establece la posición del iterador

# Imagick::getNumberImages

(PECL imagick 2, PECL imagick 3)

Imagick::getNumberImages — Devuelve el número de imágenes de un objeto

### Descripción

public function Imagick::getNumberImages(): int

Devuelve el número de imágenes de un objeto Imagick.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de imágenes de un objeto Imagick.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getOption

(PECL imagick 2, PECL imagick 3)

Imagick::getOption — Devuelve un valor asociado con la clave especificada

### Descripción

public function Imagick::getOption(string `$key`): string

Devuelve un valor asociado dentro del objeto para una clave especificada.

### Parámetros

`key`

  El nombre de la opción

### Valores devueltos

Devuelve un valor asociado con una varita mágica y la clave especificada.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getPackageName

(PECL imagick 2, PECL imagick 3)

Imagick::getPackageName — Devuelve el nombre del paquete ImageMagick

### Descripción

public static function Imagick::getPackageName(): string

Devuelve el nombre del paquete ImageMagick.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el nombre del paquete ImageMagick.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getPage

(PECL imagick 2, PECL imagick 3)

Imagick::getPage — Devuelve la geometría de la página

### Descripción

public function Imagick::getPage(): array

Devuelve la geometría del objeto Imagick, en forma de un array asociativo, con las claves `"width"`, `"height"`, `"x"` y `"y"`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la geometría del objeto Imagick, en forma de un array asociativo, con las claves `"width"`, `"height"`, `"x"` y `"y"`. Emite una excepción ImagickException en caso de fallo.

# Imagick::getPixelIterator

(PECL imagick 2, PECL imagick 3)

Imagick::getPixelIterator — Devuelve un MagickPixelIterator

### Descripción

public function Imagick::getPixelIterator(): ImagickPixelIterator

Devuelve un MagickPixelIterator.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un objeto ImagickPixelIterator.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::getPixelIterator()

    <?php
    function getPixelIterator($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imageIterator = $imagick->getPixelIterator();

        foreach ($imageIterator as $row => $pixels) { /* Se recorren las líneas de píxeles */
            foreach ($pixels as $column => $pixel) { /* Se recorren los píxeles en la línea (columna) */
                /** @var $pixel \ImagickPixel */
                if ($column % 2) {
                    $pixel->setColor("rgba(0, 0, 0, 0)"); /* Se pintan todos los segundos píxeles en negro */
                }
            }
            $imageIterator->syncIterator(); /* Se sincroniza el iterador, es importante hacerlo en cada iteración */
        }

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# Imagick::getPixelRegionIterator

(PECL imagick 2, PECL imagick 3)

Imagick::getPixelRegionIterator — Obtiene un objeto ImagickPixelIterator de una sección de imagen

### Descripción

public function Imagick::getPixelRegionIterator(
int `$x`,
int `$y`,
int `$columns`,
int `$rows`
): ImagickPixelIterator

Obtiene un objeto ImagickPixelIterator de una sección de imagen.

### Parámetros

`x`

  La coordenada x de la región.

`y`

  La coordenada y de la región.

`columns`

  El ancho de la región.

`rows`

  El alto de la región.

### Valores devueltos

Devuelve un objeto ImagickPixelIterator de una sección de imagen.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de Imagick::getPixelRegionIterator()

Recorrer los píxeles de la parte alta izquierda de la imagen, cambiándolos a negro.

    <?php
    $im = new Imagick(realpath("./testImage.png"));
    $areaIterator = $im->getPixelRegionIterator(0, 0, 10, 10);

    foreach ($areaIterator as $rowIterator) {
        foreach ($rowIterator as $píxel) {
            // Pintar cada píxel de negro
            $píxel->setColor("rgba(0, 0, 0, 0)");
        }
        $areaIterator->syncIterator();
    }
    $im->writeImage("./output.png");
    ?>

# Imagick::getPointSize

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::getPointSize — Obtiene el tamaño del punto

### Descripción

public function Imagick::getPointSize(): float

Devuelve la propiedad del tamaño del punto del objeto. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.7 o superior.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un float que contiene el tamaño del punto.

### Ver también

- Imagick::setPointSize() - Define la medida del punto

# Imagick::getQuantum

(PECL imagick 3 >= 3.3.0)

Imagick::getQuantum — Devuelve el espacio cuántico de ImageMagick

### Descripción

public static function Imagick::getQuantum(): int

Devuelve el espacio cuántico de ImageMagick. Si HDRI está activado, el tipo es un float, de lo contrario es un integer.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# Imagick::getQuantumDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getQuantumDepth — Lee la profundidad cuántica

### Descripción

public static function Imagick::getQuantumDepth(): array

Devuelve la profundidad cuántica.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array con los miembros `"quantumDepthLong"` y `"quantumDepthString"`.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getQuantumRange

(PECL imagick 2, PECL imagick 3)

Imagick::getQuantumRange — Devuelve el intervalo cuántico de Imagick

### Descripción

public static function Imagick::getQuantumRange(): array

Devuelve el intervalo cuántico de la instancia Imagick.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array asociativo que contiene el intervalo cuántico en forma de int (`"quantumRangeLong"`) y en forma de string (`"quantumRangeString"`).

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::getRegistry — Obtiene un elemento de StringRegistry

### Descripción

public static function Imagick::getRegistry(string `$key`): string

Obtiene la entrada StringRegistry para la clave nombrada o false si no está definida.

### Parámetros

`key`

  La entrada a obtener.

### Valores devueltos

# Imagick::getReleaseDate

(PECL imagick 2, PECL imagick 3)

Imagick::getReleaseDate — Devuelve la fecha de publicación de ImageMagick

### Descripción

public static function Imagick::getReleaseDate(): string

Devuelve la fecha de publicación de ImageMagick, en forma de string.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la fecha de publicación de ImageMagick, en forma de string.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getResource

(PECL imagick 2, PECL imagick 3)

Imagick::getResource — Devuelve el consumo de memoria de la recurso

### Descripción

public static function Imagick::getResource(int `$type`): int

Devuelve el consumo de memoria de la recurso, en megabytes.

### Parámetros

`type`

  Véase la lista de constantes de tipo de recursos.

### Valores devueltos

Devuelve el consumo de memoria de la recurso, en megabytes.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getResourceLimit

(PECL imagick 2, PECL imagick 3)

Imagick::getResourceLimit — Devuelve el límite de la recurso

### Descripción

public static function Imagick::getResourceLimit(int `$type`): int

Devuelve el límite de la recurso.

### Parámetros

`type`

  Una de las constantes de tipo de recursos.

### Valores devueltos

Devuelve el límite de recurso especificado. La unidad depende del tipo de recurso que está limitado.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ver también

- Imagick::setResourceLimit() - Define la limitación para una recurso particular

# Imagick::getSamplingFactors

(PECL imagick 2, PECL imagick 3)

Imagick::getSamplingFactors — Lee el factor de muestreo horizontal y vertical

### Descripción

public function Imagick::getSamplingFactors(): array

Lee el factor de muestreo horizontal y vertical.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array asociativo con los factores de muestreo horizontal y vertical de la imagen.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getSize

(PECL imagick 2, PECL imagick 3)

Imagick::getSize — Retorna el tamaño asociado con un objeto Imagick

### Descripción

public function Imagick::getSize(): array

Obtener el tamaño asociado con un objeto Imagick, previamente definido por Imagick::setSize().

> Nota:

> Este método retorna simplemente el tamaño que ha sido definido utilizando Imagick::setSize(). Si se desea obtener la anchura/altura real de la imagen, utilícense Imagick::getImageWidth() y Imagick::getImageHeight().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Retorna el tamaño asociado con un objeto Imagick, en forma de array, con las claves "`columns`" (columnas) y "`rows`" (filas).

### Ejemplos

Ejemplo #1 Obtención del tamaño de una imagen RGB cruda definida a 200x400, tras escalado a 400x800 (en relación a la anchura/altura)

    <?php
    //Establecer el tamaño primero y luego cargar la imagen cruda
    $img = new Imagick();
    $img->setSize(200, 400);
    $img->readImage("image.rgb");

    $img->scaleImage(400, 800);

    $size = $img->getSize();
    print_r($size);

    echo $img->getImageWidth()."x".$img->getImageHeight();
    ?>

El ejemplo anterior mostrará:

    Array
    (
        [columns] => 200
        [rows] => 400
    )
    400x800

# Imagick::getSizeOffset

(PECL imagick 2, PECL imagick 3)

Imagick::getSizeOffset — Devuelve el tamaño de la posición

### Descripción

public function Imagick::getSizeOffset(): int

Devuelve el tamaño de la posición asociada con el objeto Imagick. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el tamaño de la posición asociada con el objeto Imagick.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::getVersion

(PECL imagick 2, PECL imagick 3)

Imagick::getVersion — Devuelve la API de ImageMagick

### Descripción

public static function Imagick::getVersion(): array

Devuelve la versión de la API de ImageMagick, en forma de string y de número.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve la versión de la API de ImageMagick, en forma de string y de número.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::haldClutImage

(PECL imagick 3)

Imagick::haldClutImage — Reemplaza los colores de la imagen

### Descripción

public function Imagick::haldClutImage(Imagick `$clut`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Reemplaza los colores de la imagen usando una paleta Hald. Las imágenes Hald se pueden crear usando un codificador de color HALD.

### Parámetros

`clut`

  Objeto Imagick que contiene la paleta Hald.

`channel`

  Proporciona una constante de canal válida para su modo de canal. Para aplicarlo a más de un canal, combínense las constantes de canales utilizando un operador a nivel de bits. Por omisión, vale `Imagick::CHANNEL_DEFAULT`. Consúltese la lista de constantes de canales

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::haldClutImage()

    <?php
    function haldClutImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagickPalette = new \Imagick(realpath("images/hald/hald_8.png"));
        $imagickPalette->sepiatoneImage(55);
        $imagick->haldClutImage($imagickPalette);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::hasNextImage

(PECL imagick 2, PECL imagick 3)

Imagick::hasNextImage — Verifica si un objeto tiene una imagen siguiente

### Descripción

public function Imagick::hasNextImage(): bool

Devuelve `true` si el objeto tiene más imágenes para revisar la lista.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si el objeto tiene una imagen siguiente, y `false` en caso contrario.

# Imagick::hasPreviousImage

(PECL imagick 2, PECL imagick 3)

Imagick::hasPreviousImage — Verifica si un objeto tiene una imagen anterior

### Descripción

public function Imagick::hasPreviousImage(): bool

Devuelve `true` si el objeto tiene una imagen anterior, para poder revisar la lista en orden inverso.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` si el objeto tiene una imagen anterior, y `false` en caso contrario.

# Imagick::identifyFormat

(PECL imagick 3 >= 3.3.0)

Imagick::identifyFormat — Formatea un string con los detalles de la imagen

### Descripción

public function Imagick::identifyFormat(string `$embedText`): string|false

Reemplaza todos los caracteres de formato integrados por la propiedad de imagen apropiada y devuelve el texto interpretado. Consulte http://www.imagemagick.org/script/escape.php para las secuencias de escape.

### Parámetros

`embedText`

  Un string que contiene secuencias de formato, por ejemplo "Caja de recorte: %@ número de colores únicos: %k".

### Valores devueltos

Devuelve el formato o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::identifyFormat()

    <?php
            $output = "La salida de 'Caja de recorte: %@ número de colores únicos: %k' es: <br/>";
            $imagick = new \Imagick(realpath("./images/artifact/mask.png"));
            $output .= $imagick->identifyFormat("Caja de recorte: %@ número de colores únicos: %k");

    ?>

# Imagick::identifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::identifyImage — Identifica una imagen y obtiene sus atributos

### Descripción

public function Imagick::identifyImage(bool `$appendRawOutput` = `false`): array

Identifica una imagen y devuelve los atributos. Los atributos incluyen el ancho, alto, tamaño de la imagen, entre otros.

### Parámetros

`appendRawOutput`

  Si es `true`, la salida bruta se agrega al array.

### Valores devueltos

Identifica una imagen y devuelve los atributos. Los atributos incluyen el ancho, alto, tamaño de la imagen, entre otros.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de formato resultante

    Array
    (
        [imageName] => /some/path/image.jpg
        [format] => JPEG (Joint Photographic Experts Group JFIF format)
        [geometry] => Array
            (
                [width] => 90
                [height] => 90
            )

        [type] => TrueColor
        [colorSpace] => RGB
        [resolution] => Array
            (
                [x] => 300
                [y] => 300
            )

        [units] => PixelsPerInch
        [fileSize] => 1.88672kb
        [compression] => JPEG
        [signature] => 9a6dc8f604f97d0d691c0286176ddf992e188f0bebba98494b2146ee2d7118da
    )

# Imagick::implodeImage

(PECL imagick 2, PECL imagick 3)

Imagick::implodeImage — Crea una nueva imagen como una copia

### Descripción

public function Imagick::implodeImage(float `$radius`): bool

Crea una nueva imagen que es una copia de una existente con los píxeles de la imagen "implosionados" por el porcentaje especificado.

### Parámetros

`radius`

  El radio de la implosión

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::implodeImage()

    <?php
    function implodeImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->implodeImage(0.0001);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();

    }

    ?>

# Imagick::importImagePixels

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::importImagePixels — Importa los píxeles de una imagen

### Descripción

public function Imagick::importImagePixels(
int `$x`,
int `$y`,
int `$width`,
int `$height`,
string `$map`,
int `$storage`,
array `$pixels`
): bool

Importa los píxeles desde una matriz a un imagen. El mapa `map` normalmete es 'RGB'. Este método impone las siguientes limitaciones para los parámetros: la cantidad de píxeles en la matriz debe coincidir con `width` x `height` x longitud del mapa. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.5 o superior.

### Parámetros

`x`

  La posición x de la imagen

`y`

  La posición y de la imagen

`width`

  El ancho de la imagen

`height`

  El alto de la imagen

`map`

  Mapa de píxeles ordenados, como una cadena. Esto puede ser por ejemplo `RGB`. El valor puede ser cualquier combinación u orden de R = rojo, G = verde, B = azul, A = alfa (0 es transparente), O = opacidad (0 es opaco), C = cian, Y = amarillo, M = magenta, K = negro, I = intensidad (para escala de grises), P = relleno.

`storage`

  El método de almacenamiento de los píxeles. Consulte esta lista de constantes de píxel.

`pixels`

  La matriz de píxeles

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo deImagick::importImagePixels()

    <?php

    /* Generar una matriz de píxeles. 2000 píxeles por raya de color */
    $cuenta = 2000 * 3;

    $píxeles =
       array_merge(array_pad(array(), $cuenta, 0),
                   array_pad(array(), $cuenta, 255),
                   array_pad(array(), $cuenta, 0),
                   array_pad(array(), $cuenta, 255),
                   array_pad(array(), $cuenta, 0));

    /* Ancho y alto. El área es la cantidad de píxeles dividido
       por tres. Tres viene de 'RGB', tres valores por píxel */
    $ancho = $alto = pow((count($píxeles) / 3), 0.5);

    /* Crear una imagen vacía */
    $im = new Imagick();
    $im->newImage($ancho, $alto, 'gray');

    /* Importar los píxeles a la imagen.
       ancho * alto * strlen("RGB") debe coincidir con count($píxeles) */
    $im->importImagePixels(0, 0, $ancho, $alto, "RGB", Imagick::PIXEL_CHAR, $píxeles);

    /* Imprimir como una imagen jpeg */
    $im->setImageFormat('jpg');
    header("Content-Type: image/jpg");
    echo $im;

    ?>

Resultado del ejemplo anterior es similar a:

# Imagick::inverseFourierTransformImage

(PECL imagick 3 >= 3.3.0)

Imagick::inverseFourierTransformImage — Implementa la transformada inversa de Fourier discreta (Discrete Fourier Transform - DFT)

### Descripción

public function Imagick::inverseFourierTransformImage(Imagick `$complement`, bool `$magnitude`): bool

Implementa la transformada inversa de Fourier discreta (DFT) de la imagen, ya sea como un par de imágenes magnitud/fase o como un par de imágenes reales/imaginarias.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`complement`

  La segunda imagen a combinar con esta para formar ya sea el par de imágenes magnitud/fase o el par de imágenes reales/imaginarias.

`magnitude`

  Si es verdadero, combina como un par magnitud/fase, de lo contrario, un par de imágenes reales/imaginarias.

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::labelImage

(PECL imagick 2, PECL imagick 3)

Imagick::labelImage — Añade una etiqueta a una imagen

### Descripción

public function Imagick::labelImage(string `$label`): bool

Añade una etiqueta a una imagen.

### Parámetros

`label`

  La etiqueta a añadir

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::levelImage

(PECL imagick 2, PECL imagick 3)

Imagick::levelImage — Ajusta los niveles de la imagen

### Descripción

public function Imagick::levelImage(
float `$blackPoint`,
float `$gamma`,
float `$whitePoint`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Ajusta los niveles de una imagen escalando la caída de los colores entre los puntos blanco y negro especificados al rango completo de cuantía disponible. Los parámetros proporcionados representan los puntos negro, mitad, y blanco. El punto negro especifica el color más oscuro de la imagen. Los colores más oscuros que el punto negro se establecen a cero. El punto medio especifica una corrección gamma a aplicar a la imagen. Mientras que el punto blanco especifica el color más claro de la imagen. Los colores más claros que el punto blanco se establecen al valor de cuantía máximo.

### Parámetros

`blackPoint`

  El punto negro de la imagen

`gamma`

  El valor gamma

`whitePoint`

  El punto blanco de la imagen

`channel`

  Proporcione cualquier constante de canal que sea válida para su modo de canal. Para aplicar más de un canal, combine las constantes channeltype usando operadores a nivel de bits. Consulte esta lista de constantes de canal.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::levelImage()

    <?php
    function levelImage($blackPoint, $gamma, $whitePoint) {
        $imagick = new \Imagick();
        $imagick->newPseudoimage(500, 500, 'gradient:black-white');

        $imagick->setFormat('png');
        $quantum = $imagick->getQuantum();
        $imagick->levelImage($blackPoint / 100 , $gamma, $quantum * $whitePoint / 100);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::linearStretchImage

(PECL imagick 2, PECL imagick 3)

Imagick::linearStretchImage — Estrecha con saturación la intensidad de la imagen

### Descripción

public function Imagick::linearStretchImage(float `$blackPoint`, float `$whitePoint`): bool

Estrecha con saturación la intensidad de la imagen.

### Parámetros

`blackPoint`

  El punto negro de la imagen

`whitePoint`

  El punto blanco de la imagen

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::linearStretchImage()

    <?php
    function linearStretchImage($imagePath, $blackThreshold, $whiteThreshold) {
        $imagick = new \Imagick(realpath($imagePath));
        $pixels = $imagick->getImageWidth() * $imagick->getImageHeight();
        $imagick->linearStretchImage($blackThreshold * $pixels, $whiteThreshold * $pixels);

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::liquidRescaleImage

(PECL imagick 2 >= 2.2.0, PECL imagick 3)

Imagick::liquidRescaleImage — Anima una imagen o imágenes

### Descripción

public function Imagick::liquidRescaleImage(
int `$width`,
int `$height`,
float `$delta_x`,
float `$rigidity`
): bool

Este método escala las imágenes usando un método de re-escalada líquido. Este método es una implementación de una técnica llamada "seam carving" (talla de costura). Para que este método funcione como es debido, ImageMagick se debe compilar con el soporte para la biblioteca liblqr. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.9 o superior.

### Parámetros

`width`

  El ancho del tamaño objetivo

`height`

  El alto del tamaño objetivo

`delta_x`

  Cuánto puede atravesar la costura el eje x. Pasar 0 causa que las costuras sean rectas.

`rigidity`

  Introduce un sesgo para costuras no rectas. Este parámetro normalmente es 0.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ver también

- Imagick::resizeImage() - Escala una imagen

# Imagick::listRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::listRegistry — Lista todos los parámetros del registro

### Descripción

public static function Imagick::listRegistry(): array

Lista todos los parámetros del registro. Devuelve un array de todas las parejas clave/valor del registro.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un array que contiene las claves/valores del registro.

# Imagick::magnifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::magnifyImage — Duplica el tamaño de una imagen, proporcionalmente

### Descripción

public function Imagick::magnifyImage(): bool

Este método es un atajo para duplicar el tamaño de una imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::magnifyImage()

    <?php
    function magnifyImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->magnifyImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::mapImage

(PECL imagick 2, PECL imagick 3)

Imagick::mapImage — Reemplaza los colores de una imagen con el color más cercano de una imagen de referencia

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::mapImage(Imagick `$map`, bool `$dither`): bool

### Parámetros

`map`

`dither`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::matteFloodfillImage

(PECL imagick 2, PECL imagick 3)

Imagick::matteFloodfillImage — Cambia el valor de transparencia de un color

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::matteFloodfillImage(
float `$alpha`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`
): bool

Cambia el valor de transparencia de un píxel que coincide con el objetivo y esté en la zona inmediata. Si el método `FillToBorderMethod` se especifica, el valor de transparencia se cambia por cualquier píxel inmediato que no coincida con el miembro color del borde de la imagen.

### Parámetros

`alpha`

  El nivel de transparencia: 1.0 es completamente opaco y 0.0 es completamente transparente.

`fuzz`

  El miembro enfoque de la imagen define cuánta tolerancia se acepta para considerar que dos colores son el mismo.

`bordercolor`

  Un objeto ImagickPixel o una cadena que representa el color del borde.

`x`

  La coordenada x de inicio de la operación.

`y`

  La coordenada y de inicio de la operación.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL imagick 2.1.0 | Ahora se permite que una cadena represente el color como tercer parámetro. Versiones anteriores sólo permitían un objeto ImagickPixel.

# Imagick::medianFilterImage

(PECL imagick 2, PECL imagick 3)

Imagick::medianFilterImage — Aplica un filtro digital

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::medianFilterImage(float `$radius`): bool

Aplica un filtro digital que mejora la calidad de una imagen con ruido. Cada píxel es reemplazado por la media en un conjunto de píxeles inmediatos como está definido por el radio.

### Parámetros

`radius`

  El radio de la zona inmediata de los píxeles.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::medianFilterImage()

    <?php
    function medianFilterImage($radius, $imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        @$imagick->medianFilterImage($radius);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::mergeImageLayers

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::mergeImageLayers — Fusiona las capas de la imagen

### Descripción

public function Imagick::mergeImageLayers(int `$layer_method`): Imagick

Fusiona las capas de la imagen en una sola. Este método es útil al utilizar formatos de imagen que emplean múltiples capas, como los PSD. La fusión se controla mediante el argumento `layer_method` que define la forma en que las capas deben fusionarse. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.7 o superior.

### Parámetros

`layer_method`

  Una constante entre las constantes `Imagick::LAYERMETHOD_*`.

### Valores devueltos

Devuelve un objeto Imagick que contiene la imagen fusionada.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::mergeImageLayers()

    <?php
    function mergeImageLayers($layerMethodType, $imagePath1, $imagePath2) {

        $imagick = new \Imagick(realpath($imagePath1));

        $imagick2 = new \Imagick(realpath($imagePath2));
        $imagick->addImage($imagick2);
        $imagick->setImageFormat('png');

        $result = $imagick->mergeImageLayers($layerMethodType);
        header("Content-Type: image/png");
        echo $result->getImageBlob();
    }

    ?>

### Ver también

- Imagick::flattenImages() - Fusiona una secuencia de imágenes

# Imagick::minifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::minifyImage — Redimensiona una imagen proporcionalmente para reducirla a la mitad de tamaño

### Descripción

public function Imagick::minifyImage(): bool

Esta función es un atajo práctico para redimensionar una imagen proporcionalmente para reducirla a la mitad de tamaño.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::modulateImage

(PECL imagick 2, PECL imagick 3)

Imagick::modulateImage — Controla el brillo, la saturación y el tono

### Descripción

public function Imagick::modulateImage(float `$brightness`, float `$saturation`, float `$hue`): bool

Permite controlar el brillo, la saturación y el tono de una imagen. El tono es el porcentaje de la rotación absoluta desde la posición actual. Por ejemplo, 50 resulta en una rotación en el sentido contrario a las agujas del reloj de 90 grados, 150 resulta en una rotación en el sentido de las agujas del reloj de 90 grados, con 0 y 200 resultando en una rotación de 180 grados.

### Parámetros

`brightness`

`saturation`

`hue`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::modulateImage()

    <?php
    function modulateImage($imagePath, $hue, $brightness, $saturation) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->modulateImage($brightness, $saturation, $hue);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::montageImage

(PECL imagick 2, PECL imagick 3)

Imagick::montageImage — Crea una imagen compuesta

### Descripción

public function Imagick::montageImage(
ImagickDraw `$draw`,
string `$tile_geometry`,
string `$thumbnail_geometry`,
int `$mode`,
string `$frame`
): Imagick

Crea una imagen compuesta combinando varias imágenes. Las imágenes se utilizan como baldosas en la imagen compuesta, con su nombre opcionalmente debajo.

### Parámetros

`draw`

  El nombre de la fuente, el tamaño y el color se solicitan a este objeto.

`tile_geometry`

  El número de baldosas por filas y por página (ej. `6x4+0+0`).

`thumbnail_geometry`

  El tamaño solicitado para la imagen y su borde para cada miniatura (ej. 120x120+4+3).

`mode`

  El modo de encuadre de las miniaturas. Consulte la lista de constantes de modo de montaje.

`frame`

  Encuadra la imagen con un borde decorativo (ej. 15x15+3+3). La color del borde es el color mate de la miniatura.

### Valores devueltos

Crea una imagen compuesta y la devuelve como un nuevo objeto Imagick.

# Imagick::morphImages

(PECL imagick 2, PECL imagick 3)

Imagick::morphImages — Metamorfosea un conjunto de imágenes

### Descripción

public function Imagick::morphImages(int `$number_frames`): Imagick

Metamorfosea un conjunto de imágenes. Los píxeles de la imagen y el tamaño son interpolados linealmente para dar la apariencia de una metamorfosis desde una imagen a la siguiente.

### Parámetros

`number_frames`

  El número de imágenes intermedias a generar.

### Valores devueltos

Este método devuelve un nuevo objeto Imagick si se tuvo éxito. Emite una excepción ImagickException en caso de fallo.

# Imagick::morphology

(PECL imagick 3 >= 3.3.0)

Imagick::morphology — Aplica un núcleo personalizado a la imagen según el método de morfología dado

### Descripción

public function Imagick::morphology(
int `$morphologyMethod`,
int `$iterations`,
ImagickKernel `$ImagickKernel`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Aplica un núcleo personalizado a la imagen según el método de morfología dado.

### Parámetros

`morphologyMethod`

  Qué método de morfología utilizar entre las constantes \Imagick::MORPHOLOGY_*.

`iterations`

  El número de iteraciones a aplicar a la función de morfología. Un valor de -1 significa iterar hasta que no se encuentren más cambios. Cómo se aplica esto puede depender del método de morfología. Típicamente, se trata de un valor de 1.

`ImagickKernel`

`channel`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Convolución Imagick::morphology()

    <?php
            $imagick = $this->getCharacter();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_GAUSSIAN, "5,1");
            $imagick->morphology(\Imagick::MORPHOLOGY_CONVOLVE, 2, $kernel);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
    ?>

Ejemplo #2 Correlación Imagick::morphology()

    <?php
            // El píxel en la esquina superior izquierda debe ser negro
            // El píxel en la esquina inferior derecha debe ser blanco
            // El resto no importa.

            $imagick = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromMatrix(self::$correlateMatrix, [2, 2]);
            $imagick->morphology(\Imagick::MORPHOLOGY_CORRELATE, 1, $kernel);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
    ?>

Ejemplo #3 Erosión Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_ERODE, 2, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();
    ?>

Ejemplo #4 Erosión de intensidad Imagick::morphology()

    <?php
            $canvas = $this->getCharacter();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "1");
            $canvas->morphology(\Imagick::MORPHOLOGY_ERODE_INTENSITY, 2, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();
    ?>

Ejemplo #5 Dilatación Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_DILATE, 4, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();
    ?>

Ejemplo #6 Dilatación de intensidad Imagick::morphology()

    <?php
            $canvas = $this->getCharacter();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "1");
            $canvas->morphology(\Imagick::MORPHOLOGY_DILATE_INTENSITY, 4, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();
    ?>

Ejemplo #7 Distancia con núcleo de Chebyshev Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_CHEBYSHEV, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
            $canvas->autoLevelImage();
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();
    ?>

Ejemplo #8 Distancia con núcleo de Manhattan Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_MANHATTAN, "5");
            $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
            $canvas->autoLevelImage();
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();
    ?>

Ejemplo #9 Distancia con núcleo octagonal Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGONAL, "5");
            $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
            $canvas->autoLevelImage();
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();
    ?>

Ejemplo #10 Distancia con núcleo euclidiano Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_EUCLIDEAN, "4");
            $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
            $canvas->autoLevelImage();
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();
    ?>

Ejemplo #11 Borde Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_EDGE, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();
    ?>

Ejemplo #12 Apertura Imagick::morphology()

    <?php
            // Como consecuencia, se verá que 'Apertura' ha suavizado el contorno, redondeando los puntos salientes y eliminando las partes más pequeñas que la forma utilizada. También desconectará o 'abrirá' los puentes delgados.
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
            $canvas->morphology(\Imagick::MORPHOLOGY_OPEN, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();
    ?>

Ejemplo #13 Apertura de intensidad Imagick::morphology()

    <?php
            // Como consecuencia, se verá que 'Apertura' ha suavizado el contorno, redondeando los puntos salientes y eliminando las partes más pequeñas que la forma utilizada. También desconectará o 'abrirá' los puentes delgados.
            $canvas = $this->getCharacter();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
            $canvas->morphology(\Imagick::MORPHOLOGY_OPEN_INTENSITY, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();
    ?>

Ejemplo #14 Cierre Imagick::morphology()

    <?php
            //El uso básico del método 'Cierre' es reducir o eliminar los 'huecos' o 'lagunas' aproximadamente del tamaño del elemento de estructura del núcleo. Es decir, 'cerrar' las partes del fondo que son aproximadamente de ese tamaño.
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
            $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();
    ?>

Ejemplo #15 Cierre de intensidad Imagick::morphology()

    <?php
            //El uso básico del método 'Cierre' es reducir o eliminar los 'huecos' o 'lagunas' aproximadamente del tamaño del elemento de estructura del núcleo. Es decir, 'cerrar' las partes del fondo que son aproximadamente de ese tamaño.
            $canvas = $this->getCharacter();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
            $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE_INTENSITY, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();
    ?>

Ejemplo #16 Suavizado Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_SMOOTH, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();
    ?>

Ejemplo #17 Borde interior Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_EDGE_IN, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();
    ?>

Ejemplo #18 Borde exterior Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_EDGE_OUT, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();
    ?>

Ejemplo #19 El método 'TopHat', o más específicamente 'White Top Hat', devuelve los píxeles que han sido eliminados por una Apertura de la forma, es decir, los píxeles que han sido eliminados para redondear los puntos y los puentes de conexión entre las formas. Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "5");
            $canvas->morphology(\Imagick::MORPHOLOGY_TOP_HAT, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();
    ?>

Ejemplo #20 El método 'BottomHat', también conocido como 'Black TopHat', son los píxeles que un Cierre de la forma añade a la imagen. Es decir, los píxeles que han sido utilizados para rellenar los 'huecos', las 'lagunas' y los 'puentes'. Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "5");
            $canvas->morphology(\Imagick::MORPHOLOGY_BOTTOM_HAT, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();
    ?>

Ejemplo #21 Golpe y fallo Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            //Esto encuentra todos los píxeles con 3 píxeles del borde derecho
            $matrix = [[1, false, false, 0]];
            $kernel = \ImagickKernel::fromMatrix(
                $matrix,
                [0, 0]
            );
            $canvas->morphology(\Imagick::MORPHOLOGY_HIT_AND_MISS, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();
    ?>

Ejemplo #22 Afinamiento Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $leftEdgeKernel = \ImagickKernel::fromMatrix([[0, 1]], [1, 0]);
            $rightEdgeKernel = \ImagickKernel::fromMatrix([[1, 0]], [0, 0]);
            $leftEdgeKernel->addKernel($rightEdgeKernel);

            $canvas->morphology(\Imagick::MORPHOLOGY_THINNING, 3, $leftEdgeKernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();
    ?>

Ejemplo #23 Engrosamiento Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $leftEdgeKernel = \ImagickKernel::fromMatrix([[0, 1]], [1, 0]);
            $rightEdgeKernel = \ImagickKernel::fromMatrix([[1, 0]], [0, 0]);
            $leftEdgeKernel->addKernel($rightEdgeKernel);

            $canvas->morphology(\Imagick::MORPHOLOGY_THICKEN, 3, $leftEdgeKernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();
    ?>

Ejemplo #24 Afinamiento para generar una cáscara convexa Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $diamondKernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DIAMOND, "1");
            $convexKernel =  \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_CONVEX_HULL, "");

            // La morfología de afinamiento no maneja los pequeños espacios. Los cerramos
            // con la morfología de cierre.
            $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE, 1, $diamondKernel);
            $canvas->morphology(\Imagick::MORPHOLOGY_THICKEN, -1, $convexKernel);
            $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE, 1, $diamondKernel);

            header("Content-Type: image/png");
            echo $canvas->getImageBlob();
    ?>

Ejemplo #25 Morfología iterativa Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "2");
            $canvas->morphology(\Imagick::MORPHOLOGY_ITERATIVE, 3, $kernel);
            $canvas->autoLevelImage();
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();
    ?>

Ejemplo #26 Función de ayuda para obtener un contorno de imagen Imagick::morphology()

    <?php
    function getCharacterOutline() {
        $imagick = new \Imagick(realpath("./images/character.png"));
        $character = new \Imagick();
        $character->newPseudoImage(
            $imagick->getImageWidth(),
            $imagick->getImageHeight(),
            "canvas:white"
        );
        $canvas = new \Imagick();
        $canvas->newPseudoImage(
            $imagick->getImageWidth(),
            $imagick->getImageHeight(),
            "canvas:black"
        );

        $character->compositeimage(
            $imagick,
            \Imagick::COMPOSITE_COPYOPACITY,
            0, 0
        );
        $canvas->compositeimage(
            $character,
            \Imagick::COMPOSITE_ATOP,
            0, 0
        );
        $canvas->setFormat('png');

        return $canvas;
    }
    ?>

# Imagick::mosaicImages

(PECL imagick 2, PECL imagick 3)

Imagick::mosaicImages — Forma una mosaico de imágenes

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::mosaicImages(): Imagick

Alinea las imágenes de una secuencia para formar una sola imagen coherente. La función devuelve una baguette con cada imagen de la secuencia, en el lugar del desplazamiento de la imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::motionBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::motionBlurImage — Simula borrosidad en movimiento

### Descripción

public function Imagick::motionBlurImage(
float `$radius`,
float `$sigma`,
float `$angle`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Simula borrosidad en movimiento. Se convoluciona la imagen con un operador gaussiano del radio y la desviación estándar (sigma) dados. Para obtener resultados razonables, el radio debe ser mayor que sigma. Use un radio de 0 y MotionBlurImage() seleccionará un radio apropiado automáticamente. El ángulo da el ángulo del movimiento borroso.

### Parámetros

`radius`

  El radio gaussiano, en píxeles, sin contar el píxel central.

`sigma`

  La desviación estándar gaussiana, en píxeles.

`angle`

  Aplica el efecto a lo largo de este ángulo.

`channel`

  Proporcione cualquier constante de canal que sea válida para su modo de canal. Para aplicar más de un canal, combine las constantes channeltype usando operadores a nivel de bits. Consulte esta lista de constantes de canal. El argumento channel afecta sólo si Imagick es compilado con la versión 6.4.4 o superior de ImageMagick.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::motionBlurImage()

    <?php
    function motionBlurImage($imagePath, $radius, $sigma, $angle, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->motionBlurImage($radius, $sigma, $angle, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::negateImage

(PECL imagick 2, PECL imagick 3)

Imagick::negateImage — Invierte los colores en la imagen de referencia

### Descripción

public function Imagick::negateImage(bool `$gray`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Invierte los colores en la imagen de referencia. La opción de escala de grises significa que sólo los valores de la escala de grises dentro de la imagen se inverten.

### Parámetros

`gray`

  Si sólo se invierten los píxeles de la escala de grises dentro de la imagen.

`channel`

  Proporcione cualquier constante de canal que sea válida para su modo de canal. Para aplicar más de un canal, combine las constantes channeltype usando operadores a nivel de bits. Consulte esta lista de constantes de canal.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::negateImage()

    <?php
    function negateImage($imagePath, $grayOnly, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->negateImage($grayOnly, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::newImage

(PECL imagick 2, PECL imagick 3)

Imagick::newImage — Crea una nueva imagen

### Descripción

public function Imagick::newImage(
int `$cols`,
int `$rows`,
mixed `$background`,
string `$format` = ?
): bool

Crea una nueva imagen y asocia el valor de ImagickPixel al color de fondo

### Parámetros

`cols`

  Columnas en la nueva imagen

`rows`

  Filas en la nueva imagen

`background`

  El color de fondo usado para esta imagen

`format`

  El formato de la imagen. Este parámetro se añadió en la versión 2.0.1 de Imagick.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL imagick 2.1.0 | Ahora se permite que una cadena represente el color como tercer parámetro Versiones anteriores sólo permitían un objeto ImagickPixel.

### Ejemplos

Ejemplo #1 Usar Imagick::newImage():

Crear una nueva imagen y mostrarla.

    <?php

    $imagen = new Imagick();
    $imagen->newImage(100, 100, new ImagickPixel('red'));
    $imagen->setImageFormat('png');

    header('Content-type: image/png');
    echo $imagen;

    ?>

# Imagick::newPseudoImage

(PECL imagick 2, PECL imagick 3)

Imagick::newPseudoImage — Crea una nueva imagen

### Descripción

public function Imagick::newPseudoImage(int `$columns`, int `$rows`, string `$pseudoString`): bool

Crea una nueva imagen usando pseudo-formatos de ImageMagick.

### Parámetros

`columns`

  columnas en la nueva imagen

`rows`

  filas en la nueva imagen

`pseudoString`

  string que contiene la definición de la pseudo-imagen.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::newPseudoImage()

    <?php
    function newPseudoImage($canvasType) {
        $imagick = new \Imagick();
        $imagick->newPseudoImage(300, 300, $canvasType);
        $imagick->setImageFormat("png");
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    //newPseudoImage('gradient:red-rgba(64, 255, 255, 0.5)');
    //newPseudoImage("radial-gradient:red-blue");
    newPseudoImage("plasma:fractal");

    ?>

# Imagick::nextImage

(PECL imagick 2, PECL imagick 3)

Imagick::nextImage — Pasa a la siguiente imagen

### Descripción

public function Imagick::nextImage(): bool

Pasa a la siguiente imagen en la lista del objeto Imagick.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::normalizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::normalizeImage — Mejora el contraste de una imagen a color

### Descripción

public function Imagick::normalizeImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Mejora el contraste de una imagen a color ajustando los colores de los píxeles para abarcar el rango completo de colores disponibles.

### Parámetros

`channel`

  Proporcione cualquier constante de canal que sea válida para su modo de canal. Para aplicar más de un canal, combine las constantes channeltype usando operadores a nivel de bits. Consulte esta lista de constantes de canal.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::normalizeImage()

    <?php
    function normalizeImage($imagePath, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $original = clone $imagick;
        $original->cropimage($original->getImageWidth() / 2, $original->getImageHeight(), 0, 0);
        $imagick->normalizeImage($channel);
        $imagick->compositeimage($original, \Imagick::COMPOSITE_ATOP, 0, 0);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::oilPaintImage

(PECL imagick 2, PECL imagick 3)

Imagick::oilPaintImage — Simula una pintura al óleo

### Descripción

public function Imagick::oilPaintImage(float `$radius`): bool

Aplica un filtro de efecto especial que simula una pintura al óleo. Cada píxel es reemplazado por el color más frecuente que suceda en una región circular definida por el radio.

### Parámetros

`radius`

  El radio de la zona circular inmediata.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::oilPaintImage()

    <?php
    function oilPaintImage($imagePath, $radius) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->oilPaintImage($radius);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::opaquePaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::opaquePaintImage — Cambia el color de cualquier píxel que coincida con el objetivo

### Descripción

public function Imagick::opaquePaintImage(
mixed `$target`,
mixed `$fill`,
float `$fuzz`,
bool `$invert`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Cambia cualquier píxel que coincida con el color definido para el relleno. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.8 o superior.

### Parámetros

`target`

  Objeto ImagickPixel o una cadena que contiene el color a cambiar

`fill`

  El color sustituto

`fuzz`

  La cantidad de polvo de papel. Por ejemplo, definir el polvo de papel a 10 y el color rojo a una intensidad de 100 y 102 no será interpretado como el mismo color.

`invert`

  Si es `true` pinta cualquier píxel que no coincida con el color objetivo.

`channel`

  Proporciona una constante de canal válida para su modo de canal. Para aplicarlo a más de un canal, combínense las constantes de canales utilizando un operador a nivel de bits. Por omisión, vale `Imagick::CHANNEL_DEFAULT`. Consúltese la lista de constantes de canales

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::optimizeImageLayers

(PECL imagick 2, PECL imagick 3)

Imagick::optimizeImageLayers — Elimina las porciones recurrentes de imágenes a optimizar

### Descripción

public function Imagick::optimizeImageLayers(): bool

Compara cada imagen GIF con la anterior en la secuencia. A partir de ahí, el método intenta seleccionar la parte más pequeña de la imagen a reemplazar en cada imagen, manteniendo los resultados de la animación. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::optimizeImageLayers()

Lectura, optimización y escritura de una imagen GIF

    <?php
    /* creación de un nuevo objeto imagick */
    $im = new Imagick("test.gif");

    /* optimización de las capas */
    $im->optimizeImageLayers();

    /* escritura de la imagen */
    $im->writeImages("test_optimized.gif", true);
    ?>

### Ver también

- Imagick::compareImageLayers() - Devuelve la región circundante máxima entre imágenes
- Imagick::writeImages() - Escribe una imagen o secuencia de imágenes
- Imagick::writeImage() - Escribe una imagen al nombre de fichero especificado

# Imagick::orderedPosterizeImage

(PECL imagick 2 >= 2.2.2, PECL imagick 3)

Imagick::orderedPosterizeImage — Realiza un entramado ordenado

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::orderedPosterizeImage(string `$threshold_map`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Realiza un entramado ordenado basado en varios mapas de umbral de entramado predefinidos, pero sobre múltiples niveles de intensidad, lo que puede ser diferente para distintos canales, según los argumentos de entrada. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.1 o superior.

### Parámetros

`threshold_map`

  Un string que contiene el nombre del mapa de umbral de entramado que se va a usar

`channel`

  Proporcione cualquier constante de canal que sea válida para su modo de canal. Para aplicar más de un canal, combine las constantes channeltype usando operadores a nivel de bits. Consulte esta lista de constantes de canal.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::orderedPosterizeImage()

    <?php
    function orderedPosterizeImage($imagePath, $orderedPosterizeType) {
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->orderedPosterizeImage($orderedPosterizeType);
        $imagick->setImageFormat('png');

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    //orderedPosterizeImage($imagePath, 'o4x4,3,3');
    //orderedPosterizeImage($imagePath, 'o8x8,6,6');
    orderedPosterizeImage($imagePath, 'h8x8a');

    ?>

# Imagick::paintFloodfillImage

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::paintFloodfillImage — Cambia el valor del color de cualquier píxel que coincida con el objetivo

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::paintFloodfillImage(
mixed `$fill`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Cambia el valor del color de cualquier píxel que coincida con el objetivo y esté en la zona inmediata. A partir de ImageMagick 6.3.8 este método está obsoleto y se debería usar Imagick::floodfillPaintImage() en su lugar.

### Parámetros

`fill`

  Objeto ImagickPixel o un string que contiene el color de relleno

`fuzz`

  La cantidad de enfoque. Por ejemplo, establecer el enfoque a 10 y el color a rojo con una intensidad de 100 y 102 respectivamente ahora se interpreta como el mismo color para los propósitos del relleno.

`bordercolor`

  Objeto ImagickPixel que contiene el color de borde

`x`

  Posición X del inicio del relleno

`y`

  Posición Y del inicio del relleno

`channel`

  Proporciona una constante de canal válida para su modo de canal. Para aplicarlo a más de un canal, combínense las constantes de canales utilizando un operador a nivel de bits. Por omisión, vale `Imagick::CHANNEL_DEFAULT`. Consúltese la lista de constantes de canales

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::paintOpaqueImage

(PECL imagick 2, PECL imagick 3)

Imagick::paintOpaqueImage — Cambia cualquier píxel que coincida con el color

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::paintOpaqueImage(
mixed `$target`,
mixed `$fill`,
float `$fuzz`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Cambia cualquier píxel que coincida con el color definido por el relleno.

### Parámetros

`target`

  Cambia este color objetivo por el color de relleno de la imagen. Un objeto ImagickPixel o una cadena que representa el color objetivo.

`fill`

  Un objeto ImagickPixel o un string que representa el color de relleno.

`fuzz`

  El miembro enfoque de la imagen define cúanta tolerancia es aceptable para considerar que dos colores son el mismo.

`channel`

  Proporcione cualquier constante de canal que sea válida para su modo de canal. Para aplicar más de un canal, combine las constantes channeltype usando operadores a nivel de bits. Consulte esta lista de constantes de canal.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL imagick 2.1.0 | Ahora se permite que una cadena represente el color como primer y segundo parámetros. Versiones anteriores sólo permitían un objeto ImagickPixel.

# Imagick::paintTransparentImage

(PECL imagick 2, PECL imagick 3)

Imagick::paintTransparentImage — Cambia cualquier píxel que coincida con el color definido para el relleno

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::paintTransparentImage(mixed `$target`, float `$alpha`, float `$fuzz`): bool

Cambia cualquier píxel que coincida con el color definido para el relleno.

### Parámetros

`target`

  Cambia este color objetivo por el valor de opacidad especificado dentro de la imagen.

`alpha`

  El nivel de transparencia: 1.0 es completamente opaco y 0.0 es completamente transparente.

`fuzz`

  El miembro enfoque de la imagen define cuánta tolerancia es aceptable para considerar que dos colores son el mismo.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL imagick 2.1.0 | Ahora se permite que una cadena represente el color como primer parámetro. Versiones anteriores sólo permitían un objeto ImagickPixel.

# Imagick::pingImage

(PECL imagick 2, PECL imagick 3)

Imagick::pingImage — Trae los atributos básicos de una imagen

### Descripción

public function Imagick::pingImage(string `$filename`): bool

Este método se puede usar para preguntar por el ancho, alto, tamaño y formato de la imagen sin leer toda la imagen de la memoria.

### Parámetros

`filename`

  El nombre de fichero de donde se va a leer la información.

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::pingImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::pingImageBlob — Traer los atributos rápidamente

### Descripción

public function Imagick::pingImageBlob(string `$image`): bool

Este método se puede usar para preguntar por el ancho, alto, tamaño y formato de la imagen sin leer toda la imagen de la memoria. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

### Parámetros

`image`

  Un string que contiene la imagen.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Usar Imagick::pingImageBlob()

Hacer ping a una imagen desde un string

    <?php
    /* leer el contenido de la imagen */
    $imagen = file_get_contents("prueba.jpg");

    /* crear un nuevo objeto imagick */
    $im = new Imagick();

    /* pasar el string al objeto imagick */
    $im->pingImageBlob($imagen);

    /* imprimir el ancho y alto de la image */
    echo $im->getImageWidth() . 'x' . $im->getImageHeight();
    ?>

### Ver también

- Imagick::pingImage() - Trae los atributos básicos de una imagen
- Imagick::pingImageFile() - Obtener los atrbutos básicos de la imagen de una manera liviana
- Imagick::readImage() - Lee una imagen desde un nombre de fichero
- Imagick::readImageBlob() - Lee una imagen desde un string binario
- Imagick::readImageFile() - Lee una imagen desde un gestor de fichero abierto

# Imagick::pingImageFile

(PECL imagick 2, PECL imagick 3)

Imagick::pingImageFile — Obtener los atrbutos básicos de la imagen de una manera liviana

### Descripción

public function Imagick::pingImageFile(resource `$filehandle`, string `$fileName` = ?): bool

Este método se puede usar para preguntar por el ancho, alto, tamaño y formato de la imagen sin leer toda la imagen de la memoria. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

### Parámetros

`filehandle`

  Un gestor de archivo abierto a la imagen.

`fileName`

  Nombre de archivo opcional para esta imagen.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Usar Imagick::pingImageFile()

Abrir una ubicación remota

    <?php
    /* usar fopen para abrir una ubicación remota */
    $fp = fopen("http://example.com/test.jpg");

    /* crear un nuevo objeto imagick */
    $im = new Imagick();

    /* pasar el gestor a imagick */
    $im->pingImageFile($fp);
    ?>

### Ver también

- Imagick::pingImage() - Trae los atributos básicos de una imagen
- Imagick::pingImageBlob() - Traer los atributos rápidamente
- Imagick::readImage() - Lee una imagen desde un nombre de fichero
- Imagick::readImageBlob() - Lee una imagen desde un string binario
- Imagick::readImageFile() - Lee una imagen desde un gestor de fichero abierto

# Imagick::polaroidImage

(PECL imagick 2, PECL imagick 3)

Imagick::polaroidImage — Simula una fotografía Polaroid

### Descripción

public function Imagick::polaroidImage(ImagickDraw `$properties`, float `$angle`): bool

Simula una fotografía Polaroid. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.2 o superior.

### Parámetros

`properties`

  Las propiedades de polaroid

`angle`

  El ángulo de polaroid

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Un ejemplo de Imagick::polaroidImage()

Un ejemplo usando Imagick::polaroidImage()

    <?php
    /* Crear el objeto */
    $imagen = new Imagick('fuente.png');

    /* Establecer la opacidad */
    $imagen->polaroidImage(new ImagickDraw(), 25);

    /* Imprimir la imagen */
    header('Content-type: image/png');
    echo $imagen;

    ?>

# Imagick::posterizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::posterizeImage — Reduce la imagen a un número limitado de niveles de color

### Descripción

public function Imagick::posterizeImage(int `$levels`, bool `$dither`): bool

Reduce la imagen a un número limitado de niveles de color.

### Parámetros

`levels`

`dither`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::posterizeImage()

    <?php
    function posterizeImage($imagePath, $posterizeType, $numberLevels) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->posterizeImage($numberLevels, $posterizeType);
        $imagick->setImageFormat('png');
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    posterizeImage($imagePath, \Imagick::DITHERMETHOD_RIEMERSMA, 8);

    ?>

# Imagick::previewImages

(PECL imagick 2, PECL imagick 3)

Imagick::previewImages — Precisa rápidamente los parámetros apropiados para el procesamiento de la imagen

### Descripción

public function Imagick::previewImages(int `$preview`): bool

Crea un mosaico de 9 miniaturas de la imagen especificada con la operación de proceso de imágenes aplicada en varias intensidades. Esto es de útil para precisar rápidamente un parámetro apropiado para una operación de proceso de imágenes.

### Parámetros

`preview`

  Tipo de previsualización. Véase constantes de tipos de previsualización

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::previousImage

(PECL imagick 2, PECL imagick 3)

Imagick::previousImage — Pasa a la imagen anterior en una secuencia de imágenes

### Descripción

public function Imagick::previousImage(): bool

Pasa a la imagen anterior en una secuencia de imágenes Imagick.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::profileImage

(PECL imagick 2, PECL imagick 3)

Imagick::profileImage — Añade o elimina un perfil de una imagen

### Descripción

public function Imagick::profileImage(string `$name`, string `$profile` = ?): bool

Añade o elimina un perfil ICC, IPTC, o genérico de una imagen. Si el `profile` es `null`, se elimina de la imagen en lugar de añadirse.

Para eliminar todos los perfiles de la imagen, use `'*'` como `name` y `null` para el `profile`.

### Parámetros

`name`
  El nombre del perfil.
`profile`
  Datos del perfil. Si es `null`, el perfil especificado será eliminado.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::quantizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::quantizeImage — Analiza los colores dentro de una imagen de referencia

### Descripción

public function Imagick::quantizeImage(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool

### Parámetros

`numberColors`

`colorspace`

`treedepth`

`dither`

`measureError`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::quantizeImage()

    <?php
    function quantizeImage($imagePath, $numberColors, $colorSpace, $treeDepth, $dither) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->quantizeImage($numberColors, $colorSpace, $treeDepth, $dither, false);
        $imagick->setImageFormat('png');
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::quantizeImages

(PECL imagick 2, PECL imagick 3)

Imagick::quantizeImages — Analiza los colores dentro de una secuencia de imágenes

### Descripción

public function Imagick::quantizeImages(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool

### Parámetros

`numberColors`

`colorspace`

`treedepth`

`dither`

`measureError`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::queryFontMetrics

(PECL imagick 2, PECL imagick 3)

Imagick::queryFontMetrics — Devuelve una matriz que representa las métricas de la fuente

### Descripción

public function Imagick::queryFontMetrics(ImagickDraw `$properties`, string `$text`, bool `$multiline` = ?): array

Devuelve un array multidimensional que representa las métricas de la fuente.

### Parámetros

`properties`

  Objeto ImagickDraw que contiene las propiedades de la fuente

`text`

  El texto

`multiline`

  Parámetro multilínea. Si se deja vacío se autodetecta

### Valores devueltos

Devuelve un array multidimensional que representa las métricas de la fuente.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Usar Imagick::queryFontMetrics():

Preguntar por las métricas del texto y verter los resultados en la pantalla.

    <?php
    /* Crear un nuevo objeto Imagick */
    $im = new Imagick();

    /* Crear un objeto ImagickDraw */
    $draw = new ImagickDraw();

    /* Establecer la fuente */
    $draw->setFont('/path/to/font.ttf');

    /* Verter las métricas de la fuente, autodetectado multilínea */
    var_dump($im->queryFontMetrics($draw, "¡Hola Mundo!"));
    ?>

# Imagick::queryFonts

(PECL imagick 2, PECL imagick 3)

Imagick::queryFonts — Devuelve la lista de fuentes configuradas

### Descripción

public static function Imagick::queryFonts(string `$pattern` = "*"): array

Devuelve la lista de fuentes configuradas para Imagick.

### Parámetros

`pattern`

  El patrón de búsqueda

### Valores devueltos

Devuelve un array que contiene las fuentes configuradas.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::queryFonts()

    <?php
            $output = '';
            $output .= "Las fuentes que coinciden con 'Helvetica*' son:<br/>";

            $fontList = \Imagick::queryFonts("Helvetica*");

            foreach ($fontList as $fontName) {
                $output .= '<li>'. $fontName."</li>";
            }

            return $output;

    ?>

# Imagick::queryFormats

(PECL imagick 2, PECL imagick 3)

Imagick::queryFormats — Devuelve los formatos soportados por Imagick

### Descripción

public static function Imagick::queryFormats(string `$pattern` = "*"): array

Devuelve los formatos soportados por Imagick.

### Parámetros

`pattern`

### Valores devueltos

Devuelve un array que contiene los formatos soportados por Imagick.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::queryFormats()

    <?php
        function render() {
            $output = "";
            $input = \Imagick::queryformats();
            $columns = 6;

            $output .= "<table border='2'>";

            for ($i=0; $i < count($input); $i += $columns) {
                $output .= "<tr>";
                for ($c=0; $c<$columns; $c++) {
                    $output .= "<td>";
                    if (($i + $c) <  count($input)) {
                        $output .= $input[$i + $c];
                    }
                    $output .= "</td>";
                }
                $output .= "</tr>";
            }

            $output .= "</table>";

            return $output;
        }

    ?>

# Imagick::radialBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::radialBlurImage — Hace borrosa de forma radial una imagen

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::radialBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Hace borrosa de forma radial una imagen.

### Parámetros

`angle`

`channel`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::radialBlurImage()

    <?php
    function radialBlurImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        //Blur 3 times with different radii
        $imagick->radialBlurImage(3);
        $imagick->radialBlurImage(5);
        $imagick->radialBlurImage(7);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::raiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::raiseImage — Crea un efecto de botón en 3D simulado

### Descripción

public function Imagick::raiseImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`,
bool `$raise`
): bool

Crea un efecto de botón tridimensional simulado aclarando y oscureciendo los bordes de la imagen. Los miembros ancho y alto de la información de elevación definen el ancho del borde vertical y horizontal del efecto.

### Parámetros

`width`

`height`

`x`

`y`

`raise`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::raiseImage()

    <?php
    function raiseImage($imagePath, $width, $height, $x, $y, $raise) {
        $imagick = new \Imagick(realpath($imagePath));

        //x and y do nothing?
        $imagick->raiseImage($width, $height, $x, $y, $raise);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::randomThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::randomThresholdImage — Crea una imagen de alto contraste y dos colores

### Descripción

public function Imagick::randomThresholdImage(float `$low`, float `$high`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Cambia el valor de píxeles individuales basados en la instensidad de cada píxel comparado con el umbral. El resultado es una imagen de alto contraste y dos colores. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

### Parámetros

`low`

  El punto bajo

`high`

  El punto alto

`channel`

  Proporcione cualquier constante de canal que sea válida para su modo de canal. Para aplicar más de un canal, combine las constantes channeltype usando operadores a nivel de bits. Consulte esta lista de constantes de canal.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::randomThresholdImage()

    <?php
    function randomThresholdimage($imagePath, $lowThreshold, $highThreshold, $channel) {
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->randomThresholdimage(
            $lowThreshold * \Imagick::getQuantum(),
            $highThreshold * \Imagick::getQuantum(),
            $channel
        );
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::readImage

(PECL imagick 2, PECL imagick 3)

Imagick::readImage — Lee una imagen desde un nombre de fichero

### Descripción

public function Imagick::readImage(string `$filename`): bool

Lee una imagen desde un nombre de fichero

### Parámetros

`filename`

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::readImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::readImageBlob — Lee una imagen desde un string binario

### Descripción

public function Imagick::readImageBlob(string `$image`, string `$filename` = ?): bool

Lee una imagen desde un string binario

### Parámetros

`image`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::readImageBlob()

    <?php
    function readImageBlob() {
        $base64 = "iVBORw0KGgoAAAANSUhEUgAAAM0AAAD
     NCAMAAAAsYgRbAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5c
     cllPAAAABJQTFRF3NSmzMewPxIG//ncJEJsldTou1jHgAAAARBJREFUeNrs2EEK
     gCAQBVDLuv+V20dENbMY831wKz4Y/VHb/5RGQ0NDQ0NDQ0NDQ0NDQ0NDQ
     0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0PzMWtyaGhoaGhoaGhoaGhoaGhoxtb0QGho
     aGhoaGhoaGhoaGhoaMbRLEvv50VTQ9OTQ5OpyZ01GpM2g0bfmDQaL7S+ofFC6x
     v3ZpxJiywakzbvd9r3RWPS9I2+MWk0+kbf0Hih9Y17U0nTHibrDDQ0NDQ0NDQ0
     NDQ0NDQ0NTXbRSL/AK72o6GhoaGhoRlL8951vwsNDQ0NDQ1NDc0WyHtDTEhD
     Q0NDQ0NTS5MdGhoaGhoaGhoaGhoaGhoaGhoaGhoaGposzSHAAErMwwQ2HwRQ
     AAAAAElFTkSuQmCC";

        $imageBlob = base64_decode($base64);

        $imagick = new Imagick();
        $imagick->readImageBlob($imageBlob);

        header("Content-Type: image/png");
        echo $imagick;
    }

    ?>

# Imagick::readImageFile

(PECL imagick 2, PECL imagick 3)

Imagick::readImageFile — Lee una imagen desde un gestor de fichero abierto

### Descripción

public function Imagick::readImageFile(resource `$filehandle`, string `$fileName` = `null`): bool

Lee una imagen desde un gestor de fichero abierto

### Parámetros

`filehandle`

`fileName`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::readImages

(PECL imagick 2, PECL imagick 3)

Imagick::readImages — Lee una imagen a partir de un array de nombres de ficheros

### Descripción

public function Imagick::readImages(array `$filenames`): bool

Lee una imagen a partir de un array de nombres de ficheros. Todas las imágenes se almacenan en un solo objeto Imagick.

### Parámetros

`filenames`

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::recolorImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::recolorImage — Recolorear la imagen

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::recolorImage(array `$matrix`): bool

Traduce, escala, recorta y rota los colores de la imagen. Este método soporta matrices variables de escalado, pero normalmente, se utiliza una matriz 5x5 para RGBA y una matriz 6x6 para CMYK. La última línea debe contener los valores normalizados. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.6 o superior.

### Parámetros

`matrix`

  La matriz que contiene los valores de los colores.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::recolorImage()

    <?php
    function recolorImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $remapColor = [ 1, 0, 0,
            0, 0, 1,
            0, 1, 0,];

    //$remapColor = [
    //    1.438, -0.122, -0.016,  0, 0, -0.03,
    //    -0.062,  1.378, -0.016,  0, 0,  0.05,
    //    -0.062, -0.122, 1.483,   0, 0, -0.02,
    //];

        @$imagick->recolorImage($remapColor);

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Ver también

- Imagick::displayImage() - Muestra una imagen

# Imagick::reduceNoiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::reduceNoiseImage — Suaviza los contornos de una imagen

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::reduceNoiseImage(float `$radius`): bool

Suaviza los contornos de una imagen mientras que se preserva todavía la información del borde. El algoritmo funciona reemplazando cada píxel con su más cercano inmediato en valor. La zona inmediata está definida por el radio. Use un radio de 0 y Imagick::reduceNoiseImage() seleccionará una radio apropiado automáticamente.

### Parámetros

`radius`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::reduceNoiseImage()

    <?php
    function reduceNoiseImage($imagePath, $reduceNoise) {
        $imagick = new \Imagick(realpath($imagePath));
        @$imagick->reduceNoiseImage($reduceNoise);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::remapImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::remapImage — Re-mapea los colores de una imagen

### Descripción

public function Imagick::remapImage(Imagick `$replacement`, int `$DITHER`): bool

Reemplaza los colores de una imagen con los definidos por el parámetro `replacement`. Los colores son reemplazados con el color más cercano posible. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.5 o superior.

### Parámetros

`replacement`

  Un objeto Imagick que contiene los colores sustitutos

`DITHER`

  Consulte esta lista de constantes de métodos de entramado

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::removeImage

(PECL imagick 2, PECL imagick 3)

Imagick::removeImage — Elimina una imagen de la lista

### Descripción

public function Imagick::removeImage(): bool

Elimina una imagen de la lista.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::removeImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::removeImageProfile — Elimina el perfil nominado de la imagen y lo devuelve

### Descripción

public function Imagick::removeImageProfile(string `$name`): string

Elimina el perfil con nombre de la imagen y lo devuelve.

### Parámetros

`name`

### Valores devueltos

Devuelve un string que contiene el perfil de la imagen.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::render

(PECL imagick 2, PECL imagick 3)

Imagick::render — Muestra todas las comandos de dibujo previas

### Descripción

public function Imagick::render(): bool

Muestra todas las comandos de dibujo previas.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::resampleImage

(PECL imagick 2, PECL imagick 3)

Imagick::resampleImage — Remuestrea la imagen a la resolución deseada

### Descripción

public function Imagick::resampleImage(
float `$x_resolution`,
float `$y_resolution`,
int `$filter`,
float `$blur`
): bool

Remuestrea la imagen a la resolución deseada.

### Parámetros

`x_resolution`

`y_resolution`

`filter`

`blur`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::resampleImage()

    <?php
    function resampleImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->resampleImage(200, 200, \Imagick::FILTER_LANCZOS, 1);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::resetImagePage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::resetImagePage — Reinicia una página de imagen

### Descripción

public function Imagick::resetImagePage(string `$page`): bool

La definición de página como un string. El string está en formato WxH+x+y (Ancho+Alto+x+y). Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.6 o superior.

### Parámetros

`page`

  La definición de página. Por ejemplo `7168x5147+0+0`

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::resizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::resizeImage — Escala una imagen

### Descripción

public function Imagick::resizeImage(
int `$columns`,
int `$rows`,
int `$filter`,
float `$blur`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool

Escala una imagen a las dimensiones deseadas con un filtro.

> Nota: El comportamiento del parámetro `bestfit` cambió con Imagick 3.0.0. Antes de esta versión, proporcionar las dimensiones 400x400 a una imagen de dimensiones 200x150 hacía que la parte izquierda permaneciera sin cambios. Con Imagick 3.0.0 y posteriores, la imagen se reduce al tamaño 400x300, siendo este el mejor resultado para esas dimensiones. Si el parámetro `bestfit` es utilizado, la anchura y la altura deben ser proporcionadas.

### Parámetros

`columns`

  Ancho de la imagen

`rows`

  Alto de la imagen

`filter`

  Consulte la lista de constantes de filtro.

`blur`

  El factor de borrosidad donde > 1 es borroso, < 1 es nítido.

`bestfit`

  Parámetro de ajuste opcional.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Historial de cambios

Versión | Descripción
--- | ---
PECL imagick 2.1.0 | Añadido el parámetro opcional de ajuste. Este método ahora soporta escalas proporcionales. Pase cero como parámetro para escalar proporcionalmente.

### Ejemplos

Ejemplo #1 Imagick::resizeImage()

    <?php
    function resizeImage($imagePath, $width, $height, $filterType, $blur, $bestFit, $cropZoom) {
        //The blur factor where > 1 is blurry, < 1 is sharp.
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->resizeImage($width, $height, $filterType, $blur, $bestFit);

        $cropWidth = $imagick->getImageWidth();
        $cropHeight = $imagick->getImageHeight();

        if ($cropZoom) {
            $newWidth = $cropWidth / 2;
            $newHeight = $cropHeight / 2;

            $imagick->cropimage(
                $newWidth,
                $newHeight,
                ($cropWidth - $newWidth) / 2,
                ($cropHeight - $newHeight) / 2
            );

            $imagick->scaleimage(
                $imagick->getImageWidth() * 4,
                $imagick->getImageHeight() * 4
            );
        }

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::rollImage

(PECL imagick 2, PECL imagick 3)

Imagick::rollImage — Compensa una imagen

### Descripción

public function Imagick::rollImage(int `$x`, int `$y`): bool

Compensa una imagen como está definido por x e y.

### Parámetros

`x`

  El índice X.

`y`

  El índice Y.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::rollImage()

    <?php
    function rollImage($imagePath, $rollX, $rollY) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->rollimage($rollX, $rollY);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::rotateImage

(PECL imagick 2, PECL imagick 3)

Imagick::rotateImage — Rota una imagen

### Descripción

public function Imagick::rotateImage(mixed `$background`, float `$degrees`): bool

Rota una imagen el número de grados especificado. Los triángulos vacíos sobrantes por la rotación de la imagen se rellenan con el color de fondo.

### Parámetros

`background`

  El color de fondo

`degrees`

  Ángulo de rotación, en grados. El ángulo de rotación se interpreta como el número de grados a rotar la imagen en sentido de las agujas del reloj.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Historial de cambios

Versión | Descripción
--- | ---
PECL imagick 2.1.0 | Ahora se permite que una string represente el color como primer parámetro. Versiones anteriores sólo permitían un objeto ImagickPixel.

### Ejemplos

Ejemplo #1 Imagick::rotateImage()

    <?php
    function rotateImage($imagePath, $angle, $color) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->rotateimage($color, $angle);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::rotationalBlurImage

(PECL imagick 3 >= 3.3.0)

Imagick::rotationalBlurImage — Aplica un desenfoque rotacional a una imagen

### Descripción

public function Imagick::rotationalBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Aplica un desenfoque rotacional a una imagen.

### Parámetros

`angle`

  El ángulo sobre el cual aplicar el desenfoque.

`channel`

  Proporciona una constante de canal válida para su modo de canal. Para aplicarlo a más de un canal, combínense las constantes de canales utilizando un operador a nivel de bits. Por omisión, vale `Imagick::CHANNEL_DEFAULT`. Consúltese la lista de constantes de canales

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::rotationalBlurImage()

    <?php
    function rotationalBlurImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->rotationalBlurImage(3);
        $imagick->rotationalBlurImage(5);
        $imagick->rotationalBlurImage(7);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::roundCorners

(PECL imagick 2, PECL imagick 3)

Imagick::roundCorners — Redondea las esquinas de una imagen

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::roundCorners(
float `$x_rounding`,
float `$y_rounding`,
float `$stroke_width` = 10,
float `$displace` = 5,
float `$size_correction` = -6
): bool

Redondea las esquinas de una imagen. Los dos primeros argumentos controlan el nivel de redondeo, y el tercero puede ser utilizado para afinar este proceso. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior. Este método no está disponible si Imagick ha sido compilado con ImageMagick versión 7.0.0 o superior.

### Parámetros

`x_rounding`

  Redondeo en x

`y_rounding`

  Redondeo en y

`stroke_width`

  Ancho del trazo

`displace`

  Desplazamiento de la imagen

`size_correction`

  Corrección de tamaño

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::roundCorners():

Redondea las esquinas de una imagen.

    <?php

    $image = new Imagick();
    $image->newPseudoImage(100, 100, "magick:rose");
    $image->setImageFormat("png");

    $image->roundCorners(5,3);
    $image->writeImage("rounded.png");
    ?>

# Imagick::sampleImage

(PECL imagick 2, PECL imagick 3)

Imagick::sampleImage — Escala una imagen con un muestreo de píxeles

### Descripción

public function Imagick::sampleImage(int `$columns`, int `$rows`): bool

Escala una imagen a las dimensiones deseadas con un muestreo de píxeles. A diferencia de otros métodos de escala, este método no introduce colores adicionales en la imagen escalada.

### Parámetros

`columns`

`rows`

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::scaleImage

(PECL imagick 2, PECL imagick 3)

Imagick::scaleImage — Redimensiona la imagen a una escala específica

### Descripción

public function Imagick::scaleImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool

Redimensiona la imagen a las dimensiones especificadas. En caso de que alguno de los parámetros sea igual a 0, este será calculado automáticamente.

> Nota: El comportamiento del parámetro `bestfit` cambió con Imagick 3.0.0. Antes de esta versión, proporcionar las dimensiones 400x400 a una imagen de dimensiones 200x150 hacía que la parte izquierda permaneciera sin cambios. Con Imagick 3.0.0 y posteriores, la imagen se reduce al tamaño 400x300, siendo este el mejor resultado para esas dimensiones. Si el parámetro `bestfit` es utilizado, la anchura y la altura deben ser proporcionadas.

### Parámetros

`columns`

`rows`

`bestfit`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL imagick 2.1.0 | Se añadió un parámetro opcional de ajuste. Este método soporta ahora el redimensionamiento proporcional. Pase cero en uno de los parámetros para activar esta opción.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::scaleImage()

    <?php
    function scaleImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->scaleImage(150, 150, true);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::segmentImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::segmentImage — Segmenta una imagen

### Descripción

public function Imagick::segmentImage(
int `$COLORSPACE`,
float `$cluster_threshold`,
float `$smooth_threshold`,
bool `$verbose` = `false`
): bool

Analiza la imagen e identifica las unidades similares. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.5 o superior.

### Parámetros

`COLORSPACE`

  Una constante entre las constantes COLORSPACE.

`cluster_threshold`

  Un porcentaje que describe el número mínimo de píxeles contenidos en el hexedro antes de que sea considerado válido.

`smooth_threshold`

  Elimina el ruido del histograma.

`verbose`

  Si se deben o no mostrar las informaciones detalladas sobre el reconocimiento de las clases.

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::segmentImage()

    <?php
    function segmentImage($imagePath, $colorSpace, $clusterThreshold, $smoothThreshold) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->segmentImage($colorSpace, $clusterThreshold, $smoothThreshold);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    segmentImage($imagePath, \Imagick::COLORSPACE_RGB, 5, 5);

    ?>

# Imagick::selectiveBlurImage

(PECL imagick 3 >= 3.3.0)

Imagick::selectiveBlurImage — Desenfoca selectivamente una imagen dentro de un umbral de contraste

### Descripción

public function Imagick::selectiveBlurImage(
float `$radius`,
float `$sigma`,
float `$threshold`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Desenfoca selectivamente una imagen dentro de un umbral de contraste. Es similar al filtro de desenfoque que acentúa todo con un contraste superior a un cierto umbral.

### Parámetros

`radius`

`sigma`

`threshold`

`channel`

  Proporciona una constante de canal válida para su modo de canal. Para aplicarlo a más de un canal, combínense las constantes de canales utilizando un operador a nivel de bits. Por omisión, vale `Imagick::CHANNEL_DEFAULT`. Consúltese la lista de constantes de canales

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::selectiveBlurImage()

    <?php
    function selectiveBlurImage($imagePath, $radius, $sigma, $threshold, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->selectiveBlurImage($radius, $sigma, $threshold, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::separateImageChannel

(PECL imagick 2, PECL imagick 3)

Imagick::separateImageChannel — Separa un canal de la imagen

### Descripción

public function Imagick::separateImageChannel(int `$channel`): bool

Separa un canal de la imagen y devuelve una imagen en escala de grises. Un canal es un componente de color en particular de cada píxel de la imagen.

### Parámetros

`channel`

  Qué 'canal' devolver. Para espacios de color distintos del RGB, aún se pueden utilizar las constantes CHANNEL_RED, CHANNEL_GREEN, CHANNEL_BLUE para indicar el primer, segundo y tercer canal.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::separateImageChannel()

    <?php
    function separateImageChannel($imagePath, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->separateimagechannel($channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    separateImageChannel($imagePath, \Imagick::CHANNEL_GREEN);

    ?>

# Imagick::sepiaToneImage

(PECL imagick 2, PECL imagick 3)

Imagick::sepiaToneImage — Pone una imagen en tono sepia

### Descripción

public function Imagick::sepiaToneImage(float `$threshold`): bool

Aplica un efecto especial a la imagen, similar al efecto logrado en un cuarto oscuro fotográfico aplicando un tono sepia. El umbral tiene un rango desde 0 hasta el de QuantumRange y es una medida de la extensión del tono sepia. Un umbral de 80 es un buen punto de partida para un tono razonable.

### Parámetros

`threshold`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::sepiaToneImage()

    <?php
    function sepiaToneImage($imagePath, $sepia) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->sepiaToneImage($sepia);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::setBackgroundColor — Establece el color de fondo por omisión del objeto

### Descripción

public function Imagick::setBackgroundColor(mixed `$background`): bool

Establece el color de fondo por omisión del objeto.

### Parámetros

`background`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Historial de cambios

Versión | Descripción
--- | ---
PECL imagick 2.1.0 | Ahora se permite que un string represente el color como un parámetro. Las versiones anteriores sólo permiten un objeto ImagickPixel.

# Imagick::setColorspace

(PECL imagick 3)

Imagick::setColorspace — Establecer el espacio de color

### Descripción

public function Imagick::setColorspace(int `$COLORSPACE`): bool

Establece el valor del espacio de color global para el objeto. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.5.7 o superior.

### Parámetros

`COLORSPACE`

  Una de las constantes COLORSPACE

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::setCompression

(PECL imagick 2, PECL imagick 3)

Imagick::setCompression — Configura el tipo de compresión del objeto

### Descripción

public function Imagick::setCompression(int `$compression`): bool

Configura el tipo de compresión del objeto.

### Parámetros

`compression`

  El tipo de compresión. Ver las constantes Imagick::COMPRESSION_*.

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::setCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::setCompressionQuality — Configura la compresión por defecto del objeto

### Descripción

public function Imagick::setCompressionQuality(int `$quality`): bool

Configura la compresión por defecto del objeto.

Precaución

Este método solo funciona con nuevas imágenes, es decir, aquellas creadas con el método Imagick::newPseudoImage. Para imágenes existentes, debería utilizarse el método Imagick::setImageCompressionQuality().

### Parámetros

`quality`

  Un int entre 1 y 100, 1 = compresión alta, 100 compresión baja.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::setCompressionQuality()

    <?php
    function setCompressionQuality($imagePath, $quality) {

        $backgroundImagick = new \Imagick(realpath($imagePath));
        $imagick = new \Imagick();
        $imagick->setCompressionQuality($quality);
        $imagick->newPseudoImage(
            $backgroundImagick->getImageWidth(),
            $backgroundImagick->getImageHeight(),
            'canvas:white'
        );

        $imagick->compositeImage(
            $backgroundImagick,
            \Imagick::COMPOSITE_ATOP,
            0,
            0
        );

        $imagick->setFormat("jpg");
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setFilename

(PECL imagick 2, PECL imagick 3)

Imagick::setFilename — Establece el nombre de archivo antes de que se lea o escriba una imagen

### Descripción

public function Imagick::setFilename(string `$filename`): bool

Establece el nombre de fichero antes de que se lea o escriba un fichero de imagen.

### Parámetros

`filename`

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::setFirstIterator

(PECL imagick 2, PECL imagick 3)

Imagick::setFirstIterator — Coloca el iterador de Imagick en la primera imagen

### Descripción

public function Imagick::setFirstIterator(): bool

Coloca el iterador de Imagick en la primera imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::setFont

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setFont — Configura la fuente

### Descripción

public function Imagick::setFont(string `$font`): bool

Configura la fuente de la imagen. Este método se utiliza para configurar la fuente utilizada por el pseudoformato : `caption`. La fuente debe estar configurada en la configuración de ImageMagick o bien, un fichero con el nombre de la fuente `font` debe existir. Este método no debe confundirse con el método ImagickDraw::setFont() que define la fuente para un objeto ImagickDraw específico. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.7 o superior.

### Parámetros

`font`

  El nombre de la fuente o el nombre del fichero

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::setFont()

Ejemplo de utilización de Imagick::setFont().

    <?php
    /* Crea un nuevo objeto Imagick */
    $im = new Imagick();

    /* Configura la fuente del objeto */
    $im->setFont("example.ttf");

    /* Crea un nuevo mensaje */
    $im->newPseudoImage(100, 100, "caption:Hello");

    /* Continuación del procesamiento de la imagen */
    ?>

### Ver también

- Imagick::getFont() - Obtiene la fuente de caracteres
- ImagickDraw::setFont() - Establece la fuente especificada completamente para usarla cuando se escribe texto
- ImagickDraw::getFont() - Devuelve la fuente

# Imagick::setFormat

(PECL imagick 2, PECL imagick 3)

Imagick::setFormat — Establece el formato del objeto Imagick

### Descripción

public function Imagick::setFormat(string `$format`): bool

Establece el formato del objeto Imagick.

### Parámetros

`format`

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::setGravity

(PECL imagick 2 >= 2.2.0, PECL imagick 3)

Imagick::setGravity — Establece la gravedad

### Descripción

public function Imagick::setGravity(int `$gravity`): bool

Establece la propiedad gravedad global para el objeto Imagick. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.0 o superior.

### Parámetros

`gravity`

  La propiedad gravedad. Consulte esta lista de constantes de gravedad.

### Valores devueltos

No se retorna ningún valor.

# Imagick::setImage

(PECL imagick 2, PECL imagick 3)

Imagick::setImage — Reemplaza una imagen en el objeto

### Descripción

public function Imagick::setImage(Imagick `$replace`): bool

Reemplaza la secuencia de imágenes actual por la imagen del objeto sustituto.

### Parámetros

`replace`

  El objeto Imagick sustituto.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Un ejemplo de Imagick::setImage()

Un ejemplo usando Imagick::setImage()

    <?php
    /* Crear los objetos */
    $imagen = new Imagick('origen.jpg');
    $sustituto = new Imagick('sustituto.jpg');

    /* origen.jpg es reemplazado por sustituto.jpg */
    $imagen->setImage($sustituto);

    /* imprimir la imagen */
    header('Content-type: image/jpeg');
    echo $imagen;

    ?>

# Imagick::setImageAlphaChannel

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setImageAlphaChannel — Define el canal alfa de la imagen

### Descripción

public function Imagick::setImageAlphaChannel(int `$mode`): bool

Activa o desactiva el canal alfa de la imagen. El `mode` es una de las constantes `Imagick::ALPHACHANNEL_*`. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.8 o superior.

### Parámetros

`mode`

  Una constante entre las constantes `Imagick::ALPHACHANNEL_*`.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ver también

- Imagick::setImageMatte() - Establece el canal mate de la imagen
- Las constantes del canal Alfa Imagick

# Imagick::setImageArtifact

(PECL imagick 3)

Imagick::setImageArtifact — Define el artefacto de la imagen

### Descripción

public function Imagick::setImageArtifact(string `$artifact`, string `$value`): bool

Asocia un artefacto con la imagen. La diferencia entre las propiedades de la imagen y el artefacto de la imagen es que las propiedades son públicas mientras que los artefactos son privados. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.5.7 o superior.

### Parámetros

`artifact`

  El nombre del artefacto.

`value`

  El valor del artefacto.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::setImageArtifact()

    <?php
    function setImageArtifact() {

        $src1 = new \Imagick(realpath("./images/artifact/source1.png"));
        $src2 = new \Imagick(realpath("./images/artifact/source2.png"));

        $src2->setImageVirtualPixelMethod(\Imagick::VIRTUALPIXELMETHOD_TRANSPARENT);
        $src2->setImageArtifact('compose:args', "1,0,-0.5,0.5");
        $src1->compositeImage($src2, Imagick::COMPOSITE_MATHEMATICS, 0, 0);

        $src1->setImageFormat('png');
        header("Content-Type: image/png");
        echo $src1->getImagesBlob();
    }

    ?>

### Ver también

- Imagick::getImageArtifact() - Obtener el artefacto de imagen
- Imagick::deleteImageArtifact() - Borra un artefacto de imagen

# Imagick::setImageAttribute

(PECL imagick 2, PECL imagick 3)

Imagick::setImageAttribute — Define un atributo de imagen

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::setImageAttribute(string `$key`, string `$value`): bool

Define un atributo de imagen.

### Parámetros

`key`

`value`

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::setImageBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBackgroundColor — Establece el color de fondo de la imagen

### Descripción

public function Imagick::setImageBackgroundColor(mixed `$background`): bool

Establece el color de fondo de la imagen.

### Parámetros

`background`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL imagick 2.1.0 | Ahora se permite que un string represente el color como un parámetro. Versiones anteriores sólo permitían un objeto ImagickPixel.

# Imagick::setImageBias

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBias — Establece el sesgo de la imagen para cualquier método que convolucione una imagen

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::setImageBias(float `$bias`): bool

Establece el sesgo de la imagen para cualquier método que convolucione una imagen (p.ej. Imagick::ConvolveImage()).

### Parámetros

`bias`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::setImageBias()

    <?php
    //requires ImageMagick version 6.9.0-1 to have an effect on convolveImage
    function setImageBias($bias) {
        $imagick = new \Imagick(realpath("images/stack.jpg"));

        $xKernel = array(
            -0.70, 0, 0.70,
            -0.70, 0, 0.70,
            -0.70, 0, 0.70
        );

        $imagick->setImageBias($bias * \Imagick::getQuantum());
        $imagick->convolveImage($xKernel, \Imagick::CHANNEL_ALL);

        $imagick->setImageFormat('png');

        header('Content-type: image/png');
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setImageBiasQuantum

(PECL imagick 3 >= 3.3.0)

Imagick::setImageBiasQuantum — Establece el sesgo de la imagen

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::setImageBiasQuantum(float `$bias`): void

Establece el sesgo de la imagen. El sesgo debe ser escalado con `0` (sin ajuste) a `1` (valor cuántico).

### Parámetros

`bias`

### Valores devueltos

# Imagick::setImageBluePrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBluePrimary — Establece el punto primario azul de la cromaticidad de la imagen

### Descripción

public function Imagick::setImageBluePrimary(float `$x`, float `$y`): bool

Establece el punto primario azul de la cromaticidad de la imagen.

### Parámetros

`x`

`y`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::setImageBorderColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBorderColor — Establece el color de borde de la imagen

### Descripción

public function Imagick::setImageBorderColor(mixed `$border`): bool

Establece el color de borde de la imagen.

### Parámetros

`border`

  El color de borde

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL imagick 2.1.0 | Ahora se permite que un string represente el color como parámetro. Versiones anteriores sólo permitían un objeto ImagickPixel.

# Imagick::setImageChannelDepth

(PECL imagick 2, PECL imagick 3)

Imagick::setImageChannelDepth — Establece la profundidad de una canal de imagen en particular

### Descripción

public function Imagick::setImageChannelDepth(int `$channel`, int `$depth`): bool

Establece la profundidad de una canal de imagen en particular.

### Parámetros

`channel`

`depth`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::setImageClipMask

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::setImageClipMask — Establece la máscara de recorte de una imagen

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::setImageClipMask(Imagick `$clip_mask`): bool

Establece la máscara de recorte de una imagen desde otro objeto Imagick. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.6 o superior.

### Parámetros

`clip_mask`

  El objeto Imagick que contiene la máscara de recorte

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::setImageClipMask()

    <?php
    function setImageClipMask($imagePath) {
        $imagick = new \Imagick();
        $imagick->readImage(realpath($imagePath));

        $width = $imagick->getImageWidth();
        $height = $imagick->getImageHeight();

        $clipMask = new \Imagick();
        $clipMask->newPseudoImage(
            $width,
            $height,
            "canvas:transparent"
        );

        $draw = new \ImagickDraw();
        $draw->setFillColor('white');
        $draw->circle(
            $width / 2,
            $height / 2,
            ($width / 2) + ($width / 4),
            $height / 2
        );
        $clipMask->drawImage($draw);
        $imagick->setImageClipMask($clipMask);

        $imagick->negateImage(false);
        $imagick->setFormat("png");

        header("Content-Type: image/png");
        echo $imagick->getImagesBlob();

    }

    ?>

# Imagick::setImageColormapColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageColormapColor — Establece el color de un índice de mapa de color especificado

### Descripción

public function Imagick::setImageColormapColor(int `$index`, ImagickPixel `$color`): bool

Establece el color de un índice de mapa de color especificado.

### Parámetros

`index`

`color`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::setImageColorspace

(PECL imagick 2, PECL imagick 3)

Imagick::setImageColorspace — Establece el espacio de color de una imagen

### Descripción

public function Imagick::setImageColorspace(int `$colorspace`): bool

Establece el espacio de color de una imagen. Este método debería emplearse al crear imágenes nuevas. Para cambiar el espacio de color de una imagen existente se debería utilizar Imagick::transformImageColorspace().

### Parámetros

`colorspace`

  Una de las constantes COLORSPACE

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::setImageCompose

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompose — Establece el operador de composción de una imagen

### Descripción

public function Imagick::setImageCompose(int `$compose`): bool

Establece el operador de composción de una imagen, útil para especificar cómo componer la miniatura de la imagen cuando se usa el método Imagick::montageImage().

### Parámetros

`compose`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::setImageCompression

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompression — Establece la compresión de una imagen

### Descripción

public function Imagick::setImageCompression(int `$compression`): bool

### Parámetros

`compression`

  Una de las constantes `COMPRESSION`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::setImageCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompressionQuality — Establece la calidad de compresión de una imagen

### Descripción

public function Imagick::setImageCompressionQuality(int `$quality`): bool

Establece la calidad de compresión de una imagen.

### Parámetros

`quality`

  La calidad de compresión de la imagen como un integer

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::setImageCompressionQuality()

    <?php
    function setImageCompressionQuality($imagePath, $quality) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageCompressionQuality($quality);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setImageDelay

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDelay — Establece el retardo de una imagen

### Descripción

public function Imagick::setImageDelay(int `$delay`): bool

Establece el retardo de una imagen. Para una imagen animada, esto es la cantidad de tiempo que debería mostrarse este marco de la imagen, antes de mostrar el siguiente marco.

El retardo se puede establecer individualmente para cada marco de una imagen.

### Parámetros

`delay`

  La cantidad de tiempo expresado en 'ticks' que debería mostrarse la imagen. Para GIFs animados son 100 ticks por segundo, por lo que un valor de 20 sería 20/100 de un segundo, es decir 1/5 de un segundo.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Modificar un GIF animado con Imagick::setImageDelay()

    <?php

    // Modificar un GIF animado, y así sus marcos se reproduzcan a una velocidad variable,
    // variando entre que se muestre para 50ms hasta 0ms, que causará que el marco
    // sea saltado en la mayoría de los navegadores.
    $imagick = new Imagick(realpath("Test.gif"));
    $imagick = $imagick->coalesceImages();

    $numMarcos = 0;

    foreach ($imagick as $marco) {
        $imagick->setImageDelay((($numMarcos % 11) * 5));
        $numMarcos++;
    }

    $imagick = $imagick->deconstructImages();

    $imagick->writeImages("/ruta/donde/guardar/output.gif", true);

    ?>

# Imagick::setImageDepth

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDepth — Establece la profundidad de una imagen

### Descripción

public function Imagick::setImageDepth(int `$depth`): bool

Establece la profundidad de una imagen.

### Parámetros

`depth`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::setImageDispose

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDispose — Establece el método de disposición de una imagen

### Descripción

public function Imagick::setImageDispose(int `$dispose`): bool

Establece el método de disposición de una imagen.

### Parámetros

`dispose`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::setImageExtent

(PECL imagick 2, PECL imagick 3)

Imagick::setImageExtent — Establece el tamaño de una imagen

### Descripción

public function Imagick::setImageExtent(int `$columns`, int `$rows`): bool

Establece el tamaño de una imagen (p.ej. columnas y filas).

### Parámetros

`columns`

`rows`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::setImageFilename

(PECL imagick 2, PECL imagick 3)

Imagick::setImageFilename — Establece el nombre de archivo de una imagen en particular

### Descripción

public function Imagick::setImageFilename(string `$filename`): bool

Establece el nombre de fichero de una imagen en particular en una secuencia.

### Parámetros

`filename`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::setImageFormat

(PECL imagick 2, PECL imagick 3)

Imagick::setImageFormat — Establece el formato de una imagen en particular

### Descripción

public function Imagick::setImageFormat(string `$format`): bool

Establece el formato de una imagen en particular en una secuencia.

### Parámetros

`format`

  La representación string de un formato de imagen. Los formatos soportados dependen de la instalación de ImageMagick.

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::setImageGamma

(PECL imagick 2, PECL imagick 3)

Imagick::setImageGamma — Establece el valor gamma de la imagen

### Descripción

public function Imagick::setImageGamma(float `$gamma`): bool

Establece el valor gamma de la imagen.

### Parámetros

`gamma`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::setImageGravity

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::setImageGravity — Establece la gravedad de la imagen

### Descripción

public function Imagick::setImageGravity(int `$gravity`): bool

Establece la propiedad gravedad de la imagen actual. Este método se puede usar para establecer la propiedad gravedad de una sóla secuencia de imágenes. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.4 o superior.

### Parámetros

`gravity`

  La propiedad gravedad. Consulte esta lista de constantes de gravedad.

### Valores devueltos

No se retorna ningún valor.

# Imagick::setImageGreenPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageGreenPrimary — Establece el punto primario verde de la cromaticidad de la imagen

### Descripción

public function Imagick::setImageGreenPrimary(float `$x`, float `$y`): bool

Establece el punto primario verde de la cromaticidad de la imagen.

### Parámetros

`x`

`y`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::setImageIndex

(PECL imagick 2, PECL imagick 3)

Imagick::setImageIndex — Establece la posición del iterador

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::setImageIndex(int `$index`): bool

Establece la posición del iterador en la lista de imágenes especificada con el parámetro index.

Este método ha quedado obsoleto. Véase Imagick::setIteratorIndex().

### Parámetros

`index`

  La posición donde se va a establecer el iterador

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::setImageInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::setImageInterlaceScheme — Establece la compresión de la imagen

### Descripción

public function Imagick::setImageInterlaceScheme(int `$interlace_scheme`): bool

Establece la compresión de la imagen.

### Parámetros

`interlace_scheme`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::setImageInterpolateMethod

(PECL imagick 2, PECL imagick 3)

Imagick::setImageInterpolateMethod — Configura el método de interpolación de la imagen

### Descripción

public function Imagick::setImageInterpolateMethod(int `$method`): bool

Configura el método de interpolación de la imagen.

### Parámetros

`method`

  Una constante `Imagick::INTERPOLATE_*`.

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::setImageIterations

(PECL imagick 2, PECL imagick 3)

Imagick::setImageIterations — Establece las iteraciones de una imagen

### Descripción

public function Imagick::setImageIterations(int `$iterations`): bool

Establece el número de veces que una imagen animada se repite.

### Parámetros

`iterations`

  El número de veces que la imagen debería mostrarse en bucle. Establecer a '0' para un bucle infinito.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Uso básico de Imagick::setImageIterations()

    <?php

    $imagick = new Imagick(realpath("Test.gif"));

    $imagick = $imagick->coalesceImages();
    $imagick->setImageIterations(1);
    $imagick = $imagick->deconstructImages();

    $imagick->writeImages('/ruta/donde/guardar/UnaVez.gif', true);

    ?>

# Imagick::setImageMatte

(PECL imagick 2, PECL imagick 3)

Imagick::setImageMatte — Establece el canal mate de la imagen

### Descripción

public function Imagick::setImageMatte(bool `$matte`): bool

Establece el canal mate de la imagen. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

### Parámetros

`matte`

  Si es true activa el canal mate y si es false lo deshabilita.

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::setImageMatteColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageMatteColor — Establece el color mate de la imagen

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::setImageMatteColor(mixed `$matte`): bool

Establece el color mate de la imagen.

### Parámetros

`matte`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL imagick 2.1.0 | Ahora se permite que un string represente el color como parámetro. Versiones anteriores sólo permitían un objeto ImagickPixel.

# Imagick::setImageOpacity

(PECL imagick 2, PECL imagick 3)

Imagick::setImageOpacity — Establece el nivel de opacidad de la imagen

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::setImageOpacity(float `$opacity`): bool

Establece el nivel de opacidad de la imagen. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.1 o superior. Este método opera en todos los canales, lo que significa que, por ejemplo, un valor de la opacidad de 0.5 establecerá todas las áreas transparentes a parcialmente opacas. Para añadir transparencia a áreas que no lo son ya, use Imagick::evaluateImage()

### Parámetros

`opacity`

  El nivel de transpariencia: 1.0 es completamente opaco y 0.0 es completamente transparente.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Un ejemplo de Imagick::setImageOpacity()

Un ejemplo usando Imagick::setImageOpacity()

    <?php
    /* Crear el objeto */
    $imagen = new Imagick('origen.png');

    /* Establecer la opacidad */
    $imagen->setImageOpacity(0.7);

    /* Mostrar la imagen */
    header('Content-type: image/png');
    echo $imagen;

    ?>

# Imagick::setImageOrientation

(PECL imagick 2, PECL imagick 3)

Imagick::setImageOrientation — Establece la orientación de la imagen

### Descripción

public function Imagick::setImageOrientation(int `$orientation`): bool

Establece la orientación de la imagen.

### Parámetros

`orientation`

  Una de las constantes de orientación

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::setImageOrientation()

    <?php
    //Doesn't appear to do anything
    function setImageOrientation($imagePath, $orientationType) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageOrientation($orientationType);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setImagePage

(PECL imagick 2, PECL imagick 3)

Imagick::setImagePage — Establece la geometría de la página de la imagen

### Descripción

public function Imagick::setImagePage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Establece la geometría de la página de la imagen.

### Parámetros

`width`

`height`

`x`

`y`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::setImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::setImageProfile — Añade un perfil nominado al objeto Imagick

### Descripción

public function Imagick::setImageProfile(string `$name`, string `$profile`): bool

Añade un perfil nominado al objeto Imagick. Si un perfil con el mismo nobre ya existe, se reemplaza. Este método difiere del método Imagick::ProfileImage() en que no aplica ningún perfil de color CMS.

### Parámetros

`name`

`profile`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::setImageProperty

(PECL imagick 2, PECL imagick 3)

Imagick::setImageProperty — Configura una propiedad de imagen

### Descripción

public function Imagick::setImageProperty(string `$name`, string `$value`): bool

Configura la propiedad de imagen `name` al valor `value`. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.2 o superior.

### Parámetros

`name`

`value`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::setImageProperty()

Define y recupera las propiedades de una imagen.

    <?php
    $image = new Imagick();
    $image->newImage(300, 200, "black");

    $image->setImageProperty('Exif:Make', 'Imagick');
    echo $image->getImageProperty('Exif:Make');
    ?>

### Ver también

- Imagick::getImageProperty() - Devuelve una propiedad de una imagen

# Imagick::setImageRedPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageRedPrimary — Establece el punto primario rojo de la cromaticidad de la imagen

### Descripción

public function Imagick::setImageRedPrimary(float `$x`, float `$y`): bool

Establece el punto primario rojo de la cromaticidad de la imagen.

### Parámetros

`x`

`y`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::setImageRenderingIntent

(PECL imagick 2, PECL imagick 3)

Imagick::setImageRenderingIntent — Establece el propósito de renderización de la imagen

### Descripción

public function Imagick::setImageRenderingIntent(int `$rendering_intent`): bool

Establece el propósito de renderización de la imagen.

### Parámetros

`rendering_intent`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::setImageResolution

(PECL imagick 2, PECL imagick 3)

Imagick::setImageResolution — Establece la resolución de la imagen

### Descripción

public function Imagick::setImageResolution(float `$x_resolution`, float `$y_resolution`): bool

Establece la resolución de la imagen.

### Parámetros

`x_resolution`

`y_resolution`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::setImageResolution()

    <?php
    function setImageResolution($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageResolution(50, 50);

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setImageScene

(PECL imagick 2, PECL imagick 3)

Imagick::setImageScene — Establece la escena de la imagen

### Descripción

public function Imagick::setImageScene(int `$scene`): bool

Establece la escena de la imagen.

### Parámetros

`scene`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::setImageTicksPerSecond

(PECL imagick 2, PECL imagick 3)

Imagick::setImageTicksPerSecond — Establece los ticks por segundo de la imagen

### Descripción

public function Imagick::setImageTicksPerSecond(int `$ticks_per_second`): bool

Ajusta la cantidad de tiempo que se muestra un marco de una imagen animada.

> Nota:

> Para GIFs animados, esta función no cambia el número de 'ticks de imagen' por segundo, el cual está siempre definido como 100. En su lugar, ajusta la cantidad de tiempo que se muestra un marco para simular el cambio de 'ticks por segundo'.

> Por ejemplo, para un GIF animado donde cada marco se muestra para 20 ticks (1/5 de un segundo), al llamar a este método en cada marco de esa imagen con un argumento de `50`, los marcos se ajustan para que se muestren por 40 ticks (2/5 de un segundo) y así, la animación se reproducirá a la mitad de la velocidad original.

### Parámetros

`ticks_per_second`

  La duración por la que imagen debería mostrarse expresada en ticks por segundo.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Modificar un GIF animado con Imagick::setImageTicksPerSecond()

    <?php

    // Modificar un GIF animado para que la primera mitad del GIF se reproduzca a
    // la mitad de su velocidad, y la segunda mitad se reproduzca al doble de su
    // velocidad actual

    $imagick = new Imagick(realpath("Test.gif"));
    $imagick = $imagick->coalesceImages();

    $totalFrames = $imagick->getNumberImages();

    $frameCount = 0;

    foreach ($imagick as $frame) {
        $imagick->setImageTicksPerSecond(50);

        if ($frameCount < ($totalFrames / 2)) {
            // Modificar el marco para que se muestre al doble de lo actual
            $imagick->setImageTicksPerSecond(50);
        } else {
            // Modificar el marco para que se muestre a la mitad de lo actual
            $imagick->setImageTicksPerSecond(200);
        }

        $frameCount++;
    }

    $imagick = $imagick->deconstructImages();

    $imagick->writeImages("/ruta/donde/guardar/salida.gif", true);

    ?>

# Imagick::setImageType

(PECL imagick 2, PECL imagick 3)

Imagick::setImageType — Establece el tipo de imagen

### Descripción

public function Imagick::setImageType(int `$image_type`): bool

Establece el tipo de imagen.

### Parámetros

`image_type`

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::setImageUnits

(PECL imagick 2, PECL imagick 3)

Imagick::setImageUnits — Establece las unidades de resolución de la imagen

### Descripción

public function Imagick::setImageUnits(int `$units`): bool

Establece las unidades de resolución de la imagen.

### Parámetros

`units`

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::setImageVirtualPixelMethod

(PECL imagick 2, PECL imagick 3)

Imagick::setImageVirtualPixelMethod — Establece el método de píxel virtual de la imagen

### Descripción

public function Imagick::setImageVirtualPixelMethod(int `$method`): bool

Establece el método de píxel virtual de la imagen.

### Parámetros

`method`

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::setImageWhitePoint

(PECL imagick 2, PECL imagick 3)

Imagick::setImageWhitePoint — Establece el punto blanco de cromaticidad de la imagen

### Descripción

public function Imagick::setImageWhitePoint(float `$x`, float `$y`): bool

Establece el punto blanco de cromaticidad de la imagen.

### Parámetros

`x`

`y`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::setInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::setInterlaceScheme — Establece la compresión de la imagen

### Descripción

public function Imagick::setInterlaceScheme(int `$interlace_scheme`): bool

Establece la compresión de la imagen.

### Parámetros

`interlace_scheme`

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::setIteratorIndex

(PECL imagick 2, PECL imagick 3)

Imagick::setIteratorIndex — Establece la posición del iterador

### Descripción

public function Imagick::setIteratorIndex(int `$index`): bool

Establece el iterador a la posición en la lista de imágenes definida por el parámtro index. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

### Parámetros

`index`

  La posición donde se va a establecer el iterador

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Usar Imagick::setIteratorIndex():

Crear imágenes, establecer y obtener el índice del iterador

    <?php
    $im = new Imagick();
    $im->newImage(100, 100, new ImagickPixel("red"));
    $im->newImage(100, 100, new ImagickPixel("green"));
    $im->newImage(100, 100, new ImagickPixel("blue"));

    $im->setIteratorIndex(1);
    echo $im->getIteratorIndex();
    ?>

### Ver también

- Imagick::getIteratorIndex() - Lee el índice de la imagen activa actual
- Imagick::getImageIndex() - Obtiene el índice de la imagen actual
- Imagick::setImageIndex() - Establece la posición del iterador

# Imagick::setLastIterator

(PECL imagick 2 >= 2.0.1, PECL imagick 3)

Imagick::setLastIterator — Posiciona el iterador Imagick en la última imagen

### Descripción

public function Imagick::setLastIterator(): bool

Posiciona el iterador Imagick en la última imagen.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::setOption

(PECL imagick 2, PECL imagick 3)

Imagick::setOption — Configura una opción de un objeto Imagick

### Descripción

public function Imagick::setOption(string `$key`, string `$value`): bool

Configura una o varias opciones del objeto Imagick.

### Parámetros

`key`

`value`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Intento de alcanzar el tamaño '$extent' con Imagick::setOption()

    <?php
        function renderJPG($extent) {
            $imagePath = $this->control->getImagePath();
            $imagick = new \Imagick(realpath($imagePath));
            $imagick->setImageFormat('jpg');
            $imagick->setOption('jpeg:extent', $extent);
            header("Content-Type: image/jpg");
            echo $imagick->getImageBlob();
        }

    ?>

Ejemplo #2 Ejemplo con Imagick::setOption()

    <?php
        function renderPNG($imagePath, $format) {

            $imagick = new \Imagick(realpath($imagePath));
            $imagick->setImageFormat('png');
            $imagick->setOption('png:format', $format);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

        //Guardar como PNG de 64 bits.
        renderPNG($imagePath, 'png64');

    ?>

Ejemplo #3 Ejemplo con Imagick::setOption()

    <?php
        function renderCustomBitDepthPNG() {
            $imagePath = $this->control->getImagePath();
            $imagick = new \Imagick(realpath($imagePath));
            $imagick->setImageFormat('png');

            $imagick->setOption('png:bit-depth', '16');
            $imagick->setOption('png:color-type', 6);
            header("Content-Type: image/png");
            $crash = true;
            if ($crash) {
                echo $imagick->getImageBlob();
            }
            else {
                $tempFilename = tempnam('./', 'imagick');
                $imagick->writeimage(realpath($tempFilename));
                echo file_get_contents($tempFilename);
            }
        }

    ?>

# Imagick::setPage

(PECL imagick 2, PECL imagick 3)

Imagick::setPage — Establece la geometría de página del objeto Imagick

### Descripción

public function Imagick::setPage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Establece la geometría de página del objeto Imagick.

### Parámetros

`width`

`height`

`x`

`y`

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::setPointSize

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setPointSize — Define la medida del punto

### Descripción

public function Imagick::setPointSize(float `$point_size`): bool

Define la propiedad de la medida del punto del objeto. Este método puede ser utilizado para, por ejemplo, definir la medida de la fuente para la leyenda: pseudo-formato. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.7 o superior.

### Parámetros

`point_size`

  La medida del punto.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::setPointSize()

Ejemplo de uso del método Imagick::setPointSize

    <?php
    /* Crea un nuevo objeto imagick */
    $im = new Imagick();

    /* Define la fuente para el objeto */
    $im->setFont("example.ttf");

    /* Define la medida del punto */
    $im->setPointSize(12);

    /* Crea una nueva leyenda */
    $im->newPseudoImage(100, 100, "caption:Hello");

    /* Realiza algunas operaciones con la nueva imagen */
    ?>

### Ver también

- Imagick::getPointSize() - Obtiene el tamaño del punto

# Imagick::setProgressMonitor

(PECL imagick 3 >= 3.3.0)

Imagick::setProgressMonitor — Define una función de retrollamada a ser llamada durante el procesamiento

### Descripción

public function Imagick::setProgressMonitor(callable `$callback`): bool

Define una función de retrollamada que será llamada durante el procesamiento de la imagen Imagick.

### Parámetros

`callback`

  La función de progreso a llamar. Debe retornar true si el procesamiento de la imagen debe continuar, o false si debe ser cancelado. El argumento offset indica la progresión y el argumento span indica la cantidad total de trabajo a realizar.

  function callback ( mixed `$offset` , mixed `$span` ): bool
  Precaución

  Los valores pasados a la función de retrollamada no son consistentes. En particular, el argumento span puede aumentar durante el procesamiento de la imagen. Debido a esto, el cálculo del porcentaje completo de una operación de imagen no es trivial.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::setProgressMonitor()

    <?php
            $abortReason = null;

            try {
                $imagick = new \Imagick(realpath($this->control->getImagePath()));
                $startTime = time();

                $callback = function ($offset, $span)  use ($startTime, &$abortReason) {
                    if (((100 * $offset) / $span)  > 20) {
                        $abortReason = "Processing reached 20%";
                        return false;
                    }

                    $nowTime = time();

                    if ($nowTime - $startTime > 5) {
                        $abortReason = "Image processing took more than 5 seconds";
                        return false;
                    }
                    if (($offset % 5) == 0) {
                        echo "Progress: $offset / $span <br/>";
                    }
                    return true;
                };

                $imagick->setProgressMonitor($callback);

                $imagick->waveImage(2, 15);

                echo "Data len is: ".strlen($imagick->getImageBlob());
            }
            catch(\ImagickException $e) {
                if ($abortReason != null) {
                    echo "Image processing was aborted: ".$abortReason."<br/>";
                }
                else {
                    echo "ImagickException caught: ".$e->getMessage()." Exception type is ".get_class($e);
                }
            }

    ?>

# Imagick::setRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::setRegistry — Define la entrada del registro ImageMagick nombrada clave para valor

### Descripción

public static function Imagick::setRegistry(string `$key`, string `$value`): bool

Define la entrada del registro ImageMagick nombrada clave para valor. Esto es lo más útil para definir "temporary-path" que controla dónde ImageMagick crea imágenes temporales, por ejemplo durante el procesamiento de PDF.

### Parámetros

`key`

`value`

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::setResolution

(PECL imagick 2, PECL imagick 3)

Imagick::setResolution — Establece la resolución de la imagen

### Descripción

public function Imagick::setResolution(float `$x_resolution`, float `$y_resolution`): bool

Establece la resolución de la imagen.

### Parámetros

`x_resolution`

  La resolución horizontal.

`y_resolution`

  La resolución vertical.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Notas

Imagick::setResolution() se debe invocar antes de cargar o crear una imagen.

### Ver también

- Imagick::setImageResolution() - Establece la resolución de la imagen
- Imagick::getImageResolution() - Lee las resoluciones en X y Y de una imagen

# Imagick::setResourceLimit

(PECL imagick 2, PECL imagick 3)

Imagick::setResourceLimit — Define la limitación para una recurso particular

### Descripción

public static function Imagick::setResourceLimit(int `$type`, int `$limit`): bool

Este método se utiliza para modificar las limitaciones de la recurso de la biblioteca subyacente ImageMagick.

### Parámetros

`type`

  Consulte la lista de constantes de tipo de recursos.

`limit`

  Una de las constantes de tipo de recursos. La unidad depende del tipo de la recurso a limitar.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ver también

- Imagick::getResourceLimit() - Devuelve el límite de la recurso

# Imagick::setSamplingFactors

(PECL imagick 2, PECL imagick 3)

Imagick::setSamplingFactors — Establece los factores de muestreo de la imagen

### Descripción

public function Imagick::setSamplingFactors(array `$factors`): bool

Establece los factores de muestreo de la imagen.

### Parámetros

`factors`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::setSamplingFactors()

    <?php
    function setSamplingFactors($imagePath) {

        $imagePath = "../imagick/images/FineDetail.png";
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageFormat('jpg');
        $imagick->setSamplingFactors(array('2x2', '1x1', '1x1'));

        $compressed = $imagick->getImageBlob();

        $reopen = new \Imagick();
        $reopen->readImageBlob($compressed);

        $reopen->resizeImage(
            $reopen->getImageWidth() * 4,
            $reopen->getImageHeight() * 4,
            \Imagick::FILTER_POINT,
            1
        );

        header("Content-Type: image/jpg");
        echo $reopen->getImageBlob();
    }

    ?>

# Imagick::setSize

(PECL imagick 2, PECL imagick 3)

Imagick::setSize — Establece el tamaño del objeto Imagick

### Descripción

public function Imagick::setSize(int `$columns`, int `$rows`): bool

Establece el tamaño del Imagick. Se debe establecer antes de leer un formato de imagen en bruto como RGB, GRAY, o CMYK.

### Parámetros

`columns`

`rows`

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::setSizeOffset

(PECL imagick 2, PECL imagick 3)

Imagick::setSizeOffset — Establece el tamaño y el índice del objeto Imagick

### Descripción

public function Imagick::setSizeOffset(int `$columns`, int `$rows`, int `$offset`): bool

Establece el tamaño y el índice del objeto Imagick. Se debe establecer antes de leer un formato de imagen en bruto como RGB, GRAY, o CMYK. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

### Parámetros

`columns`

  El ancho en píxeles.

`rows`

  El alto en píxeles.

`offset`

  El índice de la imagen.

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::setType

(PECL imagick 2, PECL imagick 3)

Imagick::setType — Establece el atributo tipo de imagen

### Descripción

public function Imagick::setType(int `$image_type`): bool

Establece el atributo tipo de imagen.

### Parámetros

`image_type`

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::shadeImage

(PECL imagick 2, PECL imagick 3)

Imagick::shadeImage — Crea un efecto en 3D

### Descripción

public function Imagick::shadeImage(bool `$gray`, float `$azimuth`, float `$elevation`): bool

Hace brillar una luz distante sobre una imagen para crear un efecto tridimensional. Se controla la posición de la luz con los parámetros azimuth (acimut) y elevation (elevación); el acimut se mide en grados desde el eje X y la elevación se mide en píxeles por encima del eje Z. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

### Parámetros

`gray`

  Un valor distinto de cero sombrea la intensidad de cada píxel.

`azimuth`

  Define la dirección de la fuente de luz.

`elevation`

  Define la dirección de la fuente de luz.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción de tipo ImagickException en caso de error.

### Ejemplos

Ejemplo #1 Imagick::shadeImage()

    <?php
    function shadeImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->shadeImage(true, 45, 20);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::shadowImage

(PECL imagick 2, PECL imagick 3)

Imagick::shadowImage — Simula una sombra de imagen

### Descripción

public function Imagick::shadowImage(
float `$opacity`,
float `$sigma`,
int `$x`,
int `$y`
): bool

Simula una sombra de imagen.

### Parámetros

`opacity`

`sigma`

`x`

`y`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::shadowImage()

    <?php
    function shadowImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->shadowImage(0.4, 10, 50, 5);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::sharpenImage

(PECL imagick 2, PECL imagick 3)

Imagick::sharpenImage — Afila una imagen

### Descripción

public function Imagick::sharpenImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Afila una imagen. Se convoluciona la imagen con un operador gaussiano del radio y la desviación estándar (sigma) dados. Para obtener resultados razonables, el radio debería ser mayor que sigma. Use un radio de 0 y Imagick::sketchImage()() seleccionará un radio apropiado automáticamente.

### Parámetros

`radius`

`sigma`

`channel`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::sharpenImage()

    <?php
    function sharpenImage($imagePath, $radius, $sigma, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->sharpenimage($radius, $sigma, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::shaveImage

(PECL imagick 2, PECL imagick 3)

Imagick::shaveImage — Recorta píxeles de los extremos de la imagen

### Descripción

public function Imagick::shaveImage(int `$columns`, int `$rows`): bool

Recorta píxeles de los extremos de la imagen. Asigna la memoria necesaria para la estructura de la nueva imagen y devuelve un puntero a la nueva imagen.

### Parámetros

`columns`

`rows`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::shaveImage()

    <?php
    function shaveImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->shaveImage(100, 50);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::shearImage

(PECL imagick 2, PECL imagick 3)

Imagick::shearImage — Crea un paralelogramo

### Descripción

public function Imagick::shearImage(mixed `$background`, float `$x_shear`, float `$y_shear`): bool

Desliza un extremo de una imagen a lo largo del eje X o Y, creando un paralelogramo. Un recorte en la dirección X desliza un extremo a lo largo del eje X, mientras que un recorte en la dirección Y desliza un extremo a lo largo del eje Y. La cantidad del recorte se controla por un ángulo de recorte. Para recortes en la dirección X, x_shear se mide relativo al eje Y, y de forma similar, para recortes en la dirección Y, y_shear se mide relativo al eje X. Los triángulos vacíos sobrantes del recorte de la imagen se rellenan con el color de fondo.

### Parámetros

`background`

  El color de fondo

`x_shear`

  El número de grados a recortar sobre el eje x

`y_shear`

  El número de grados a recortar sobre el eje y

### Valores devueltos

Devuelve `true` en caso de éxito.

### Historial de cambios

Versión | Descripción
--- | ---
PECL imagick 2.1.0 | Ahora se permite que un string represente el color como primer parámetro. Versiones previas sólo permitían un objeto ImagickPixel.

### Ejemplos

Ejemplo #1 Imagick::shearImage()

    <?php
    function shearImage($imagePath, $color, $shearX, $shearY) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->shearimage($color, $shearX, $shearY);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::sigmoidalContrastImage

(PECL imagick 2, PECL imagick 3)

Imagick::sigmoidalContrastImage — Ajusta el contraste de la imagen

### Descripción

public function Imagick::sigmoidalContrastImage(
bool `$sharpen`,
float `$alpha`,
float `$beta`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Ajusta el contraste de la imagen con un algoritmo de contraste sigmoide no lineal. Aumenta el contraste de la imagen utilizando una función de transferencia sigmoide sin saturar las luces altas y las sombras. El contraste indica cuánto debe aumentarse (0 para no hacer nada, 3 es un valor típico, 20 es un valor alto); el punto medio indica dónde estarán los tonos medios en la imagen resultante (0 corresponde a blanco, 50 a gris y 100 a negro). Establezca el parámetro `sharpen` en `true` para aumentar el contraste de la imagen; de lo contrario, el contraste se reducirá.

Consulte también los » ejemplos de ImageMagick V6 - Transformaciones de imágenes - Contraste no lineal

### Parámetros

`sharpen`

  Si es `true`, el contraste aumentará; de lo contrario, el contraste disminuirá.

`alpha`

  La cantidad de contraste a aplicar. -1 representa una cantidad muy pequeña, 5 una cantidad significativa y 20 el máximo.

`beta`

  Dónde debe situarse el punto medio del gradiente. Este valor debe estar en el intervalo 0-1, multiplicado por el valor del quantum para ImageMagick.

`channel`

  Canales de color sobre los cuales debe aplicarse el contraste.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Crea un degradado de imagen utilizando el método Imagick::sigmoidalContrastImage() para mezclar dos imágenes suavemente, donde la mezcla está definida por las variables $contrast y $midpoint.

    <?php

    function generateBlendImage($width, $height, $contrast = 10, $midpoint = 0.5) {
        $imagick = new Imagick();
        $imagick->newPseudoImage($width, $height, 'gradient:black-white');
        $quanta = $imagick->getQuantumRange();
        $imagick->sigmoidalContrastImage(true, $contrast, $midpoint * $quanta["quantumRangeLong"]);

        return $imagick;
    }

    ?>

# Imagick::sketchImage

(PECL imagick 2, PECL imagick 3)

Imagick::sketchImage — Simula el bosquejo de un lapiz

### Descripción

public function Imagick::sketchImage(float `$radius`, float `$sigma`, float `$angle`): bool

Simula el bosquejo de un lapiz. Se convoluciona la imagen con un operador gaussiano del radio y la desviación estándar (sigma) dados. Para obtener resultados razonables, el radio debería ser mayor que sigma. Use un radio de 0 y Imagick::sketchImage() seleccionará un radio apropiado automáticamente. El ángulo da el ángulo del movimiento borroso. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

### Parámetros

`radius`

  El radio gaussiano, en píxeles, sin contar el píxel central.

`sigma`

  La desviación estándar gaussiana, en píxeles.

`angle`

  Aplica el efecto a lo largo de este ángulo.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::sketchImage()

    <?php
    function sketchImage($imagePath, $radius, $sigma, $angle) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->sketchimage($radius, $sigma, $angle);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::smushImages

(PECL imagick 3 >= 3.3.0)

Imagick::smushImages — Toma todas las imágenes del puntero de imagen actual hasta el final de la lista de imágenes y las comprime

### Descripción

public function Imagick::smushImages(bool `$stack`, int `$offset`): Imagick

Toma todas las imágenes del puntero de imagen actual hasta el final de la lista de imágenes y las comprime unas sobre otras de arriba hacia abajo si el argumento stack es verdadero, de lo contrario de izquierda a derecha.

### Parámetros

`stack`

`offset`

### Valores devueltos

La nueva imagen comprimida.

### Ejemplos

Ejemplo #1 Imagick::smushImages()

    <?php
    function smushImages($imagePath, $imagePath2) {

        $imagick = new \Imagick(realpath($imagePath));
        $imagick2 = new \Imagick(realpath($imagePath2));

        $imagick->addimage($imagick2);
        $smushed = $imagick->smushImages(false, 50);
        $smushed->setImageFormat('jpg');
        header("Content-Type: image/jpg");
        echo $smushed->getImageBlob();
    }

    ?>

# Imagick::solarizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::solarizeImage — Aplica un efecto de solarización a la imagen

### Descripción

public function Imagick::solarizeImage(int `$threshold`): bool

Aplica un efecto especial a la imagen, similar al efecto conseguido en un cuarto oscuro fotográfico exponiendo selectivamente áreas del papel sensible fotográfico a la luz. Los rangos de umbral van desde 0 al de QuantumRange y es una medida de la extensión de la solarización.

### Parámetros

`threshold`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::solarizeImage()

    <?php
    function solarizeImage($imagePath, $solarizeThreshold) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->solarizeImage($solarizeThreshold * \Imagick::getQuantum());
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::sparseColorImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::sparseColorImage — Interpola colores

### Descripción

public function Imagick::sparseColorImage(int `$SPARSE_METHOD`, array `$arguments`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Dada la matriz de argumentos que contiene valores númericos, este método interpola los colores encontrados en esas coordenadas a través de la imagen completa usando `sparse_method`. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.4.5 o superior.

### Parámetros

`SPARSE_METHOD`

  Consulte esta lista de constantes de métodos de escasez

`arguments`

  Una matriz que contiene las coordenadas. El formato de la matriz es `array(1,1, 2,45)`

`channel`

  Proporciona una constante de canal válida para su modo de canal. Para aplicarlo a más de un canal, combínense las constantes de canales utilizando un operador a nivel de bits. Por omisión, vale `Imagick::CHANNEL_DEFAULT`. Consúltese la lista de constantes de canales

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 SPARSECOLORMETHOD_BARYCENTRIC Imagick::sparseColorImage()

    <?php
        function renderImageBarycentric2() {
            $points = [
                [0.30, 0.10, 'red'],
                [0.10, 0.80, 'blue'],
                [0.70, 0.60, 'lime'],
                [0.80, 0.20, 'yellow'],
            ];
            $imagick = createGradientImage(
                400, 400,
                $points,
                \Imagick::SPARSECOLORMETHOD_BARYCENTRIC
            );
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Ejemplo #2 SPARSECOLORMETHOD_BILINEAR Imagick::sparseColorImage()

    <?php
        function renderImageBilinear() {
            $points = [[0.30, 0.10, 'red'], [0.10, 0.80, 'blue'], [0.70, 0.60, 'lime'], [0.80, 0.20, 'yellow'],];
            $imagick = createGradientImage(500, 500, $points, \Imagick::SPARSECOLORMETHOD_BILINEAR);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Ejemplo #3 SPARSECOLORMETHOD_SPEPARDS Imagick::sparseColorImage()

    <?php
        function renderImageShepards() {
            $points = [
                [0.30, 0.10, 'red'],
                [0.10, 0.80, 'blue'],
                [0.70, 0.60, 'lime'],
                [0.80, 0.20, 'yellow'],
            ];
            $imagick = createGradientImage(600, 600, $points, \Imagick::SPARSECOLORMETHOD_SPEPARDS);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Ejemplo #4 SPARSECOLORMETHOD_VORONOI Imagick::sparseColorImage()

    <?php
        function renderImageVoronoi() {
            $points = [
                [0.30, 0.10, 'red'],
                [0.10, 0.80, 'blue'],
                [0.70, 0.60, 'lime'],
                [0.80, 0.20, 'yellow'],
            ];
            $imagick = createGradientImage(500, 500, $points, \Imagick::SPARSECOLORMETHOD_VORONOI);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Ejemplo #5 SPARSECOLORMETHOD_BARYCENTRIC Imagick::sparseColorImage()

    <?php
        function renderImageBarycentric() {
            $points = [
                [0, 0, 'skyblue'],
                [-1, 1, 'skyblue'],
                [1, 1, 'black'],
            ];
            $imagick = createGradientImage(600, 200, $points, \Imagick::SPARSECOLORMETHOD_BARYCENTRIC);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Ejemplo #6 createGradientImage is used by other examples. Imagick::sparseColorImage()

    <?php
    function createGradientImage($width, $height, $colorPoints, $sparseMethod, $absolute = false) {

        $imagick = new \Imagick();
        $imagick->newImage($width, $height, "white");
        $imagick->setImageFormat("png");

        $barycentricPoints = array();

        foreach ($colorPoints as $colorPoint) {

            if ($absolute == true) {
                $barycentricPoints[] = $colorPoint[0];
                $barycentricPoints[] = $colorPoint[1];
            }
            else {
                $barycentricPoints[] = $colorPoint[0] * $width;
                $barycentricPoints[] = $colorPoint[1] * $height;
            }

            if (is_string($colorPoint[2])) {
                $imagickPixel = new \ImagickPixel($colorPoint[2]);
            }
            else if ($colorPoint[2] instanceof \ImagickPixel) {
                $imagickPixel = $colorPoint[2];
            }
            else{
                $errorMessage = sprintf(
                    "Value %s is neither a string nor an ImagickPixel class. Cannot use as a color.",
                    $colorPoint[2]
                );

                throw new \InvalidArgumentException(
                    $errorMessage
                );
            }

            $red = $imagickPixel->getColorValue(\Imagick::COLOR_RED);
            $green = $imagickPixel->getColorValue(\Imagick::COLOR_GREEN);
            $blue = $imagickPixel->getColorValue(\Imagick::COLOR_BLUE);
            $alpha = $imagickPixel->getColorValue(\Imagick::COLOR_ALPHA);

            $barycentricPoints[] = $red;
            $barycentricPoints[] = $green;
            $barycentricPoints[] = $blue;
            $barycentricPoints[] = $alpha;
        }

        $imagick->sparseColorImage($sparseMethod, $barycentricPoints);

        return $imagick;
    }

    ?>

# Imagick::spliceImage

(PECL imagick 2, PECL imagick 3)

Imagick::spliceImage — Une un color sólido en la imagen

### Descripción

public function Imagick::spliceImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Une un color sólido en la imagen.

### Parámetros

`width`

`height`

`x`

`y`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::spliceImage()

    <?php
    function spliceImage($imagePath, $startX, $startY, $width, $height) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->spliceImage($width, $height, $startX, $startY);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::spreadImage

(PECL imagick 2, PECL imagick 3)

Imagick::spreadImage — Despalza aleatoriamente cada píxel en un bloque

### Descripción

public function Imagick::spreadImage(float `$radius`): bool

Método de efecto especial que desplaza aleatoriamente cada píxel en un bloque definido por el parámetro radius (radio).

### Parámetros

`radius`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::spreadImage()

    <?php
    function spreadImage($imagePath, $radius) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->spreadImage($radius);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::statisticImage

(PECL imagick 3 >= 3.3.0)

Imagick::statisticImage — Modifica una imagen utilizando una función estadística

### Descripción

public function Imagick::statisticImage(
int `$type`,
int `$width`,
int `$height`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Cada píxel es reemplazado por la estadística correspondiente del vecindario de la anchura y altura especificadas.

### Parámetros

`type`

`width`

`height`

`channel`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::statisticImage()

    <?php
    function statisticImage($imagePath, $statisticType, $width, $height, $channel) {
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->statisticImage(
            $statisticType,
            $width,
            $height,
            $channel
        );

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    statisticImage($imagePath, \Imagick::STATISTIC_MEDIAN, 5, 5, \Imagick::CHANNEL_DEFAULT);

    ?>

# Imagick::steganoImage

(PECL imagick 2, PECL imagick 3)

Imagick::steganoImage — Oculta una marca de agua digital dentro de la imagen

### Descripción

public function Imagick::steganoImage(Imagick `$watermark_wand`, int `$offset`): Imagick

Oculta una marca de agua digital dentro de la imagen. Recupere la marca de agua oculta después para demostrar la autenticidad de la imagen. El parámetro offset define la posición inicial dentro de la imagen para ocultar la marca de agua.

### Parámetros

`watermark_wand`

`offset`

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::stereoImage

(PECL imagick 2, PECL imagick 3)

Imagick::stereoImage — Compone dos imágenes

### Descripción

public function Imagick::stereoImage(Imagick `$offset_wand`): bool

Compone dos imágenes y produce una sóla imagen que es la composición de una imagen izquierda y derecha de una pareja estéreo.

### Parámetros

`offset_wand`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::stripImage

(PECL imagick 2, PECL imagick 3)

Imagick::stripImage — Elimina de una imagen todos los perfiles y los comentarios

### Descripción

public function Imagick::stripImage(): bool

Elimina de una imagen todos los perfiles y los comentarios.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

# Imagick::subImageMatch

(PECL imagick 3 >= 3.3.0)

Imagick::subImageMatch — Busca una subimagen en la imagen actual y devuelve una imagen de similitud

### Descripción

public function Imagick::subImageMatch(Imagick `$Imagick`, array `&$offset` = ?, float `&$similarity` = ?): Imagick

Busca una subimagen en la imagen actual y devuelve una imagen de similitud de tal manera que una posición de coincidencia exacta es completamente blanca y si ningún píxel coincide, negro, de lo contrario un cierto nivel de gris entre ambos. Asimismo, pueden pasarse los argumentos opcionales bestMatch y similarity. Tras llamar a la función, similarity será definido en el 'puntuación' de similitud entre la subimagen y la posición correspondiente en la imagen más grande, bestMatch contendrá un array asociativo con los elementos x, y, width, height que describen la región correspondiente.

### Parámetros

`Imagick`

`offset`

`similarity`

  Una nueva imagen que muestra la cantidad de similitud en cada píxel.

### Valores devueltos

### Ejemplos

Ejemplo #1 Imagick::subImageMatch()

    <?php
    function subImageMatch($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick2 = clone $imagick;
        $imagick2->cropimage(40, 40, 250, 110);
        $imagick2->vignetteimage(0, 1, 3, 3);

        $similarity = null;
        $bestMatch = null;
        $comparison = $imagick->subImageMatch($imagick2, $bestMatch, $similarity);

        $comparison->setImageFormat('png');
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::swirlImage

(PECL imagick 2, PECL imagick 3)

Imagick::swirlImage — Arremolina los píxeles desde el centro de la imagen

### Descripción

function Imagick::swirlImage(float `$degrees`): bool

Arremolina los píxeles desde el centro de la imagen, donde los grados indican el alcance del arco a través del cuál cada píxel es movido. Se puede obtener un efecto más dramático moviendo los grados desde 1 a 360.

### Parámetros

`degrees`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::swirlImage()

    <?php
    function swirlImage($imagePath, $swirl) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->swirlImage($swirl);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::textureImage

(PECL imagick 2, PECL imagick 3)

Imagick::textureImage — Repite los mosaicos de la textura de una imagen

### Descripción

function Imagick::textureImage(Imagick `$texture_wand`): Imagick

Repite los mosaicos de la textura de una imagen mediante el lienzo de la imagen.

### Parámetros

`texture_wand`

  Objeto Imagick a utilizar como imagen de textura

### Valores devueltos

Devuelve un nuevo objeto Imagick, al que se le ha aplicado la textura repetida.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::textureImage()

    <?php
    function textureImage($imagePath) {
        $image = new \Imagick();
        $image->newImage(640, 480, new \ImagickPixel('pink'));
        $image->setImageFormat("jpg");
        $texture = new \Imagick(realpath($imagePath));
        $texture->scaleimage($image->getimagewidth() / 4, $image->getimageheight() / 4);
        $image = $image->textureImage($texture);
        header("Content-Type: image/jpg");
        echo $image;
    }

    ?>

# Imagick::thresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::thresholdImage — Cambia el valor de píexeles individuales basdos en un umbral

### Descripción

public function Imagick::thresholdImage(float `$threshold`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Cambia el valor de píxeles individuales basados en la inatensidad de cada píxel comparado con el umbral. El resultado es una imagen de alto contraste de dos colores.

### Parámetros

`threshold`

`channel`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::thresholdImage()

    <?php
    function thresholdimage($imagePath, $threshold, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->thresholdimage($threshold * \Imagick::getQuantum(), $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::thumbnailImage

(PECL imagick 2, PECL imagick 3)

Imagick::thumbnailImage — Modifica el tamaño de una imagen

### Descripción

public function Imagick::thumbnailImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$fill` = `false`,
bool `$legacy` = `false`
): bool

Modifica el tamaño de una imagen a las dimensiones dadas y elimina todos los perfiles asociados. El objetivo es producir una miniatura de bajo costo para su visualización en la web. Si `true` se proporciona como tercer argumento, entonces los argumentos `columns` y `rows` se utilizarán como máximo para cada lado. Cada lado se reducirá hasta que se alcance el tamaño deseado.

> Nota: El comportamiento del parámetro `bestfit` cambió con Imagick 3.0.0. Antes de esta versión, proporcionar las dimensiones 400x400 a una imagen de dimensiones 200x150 hacía que la parte izquierda permaneciera sin cambios. Con Imagick 3.0.0 y posteriores, la imagen se reduce al tamaño 400x300, siendo este el mejor resultado para esas dimensiones. Si el parámetro `bestfit` es utilizado, la anchura y la altura deben ser proporcionadas.

### Parámetros

`columns`

  Ancho de la imagen

`rows`

  Alto de la imagen

`bestfit`

  Si se deben forzar los valores máximos

`fill`

  Si la imagen no llena completamente el área, entonces esta se rellena con el color de fondo de la imagen.

`legacy`

  Redondea la dimensión más pequeña al entero inferior más cercano.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::thumbnailImage()

    <?php
    function thumbnailImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setbackgroundcolor('rgb(64, 64, 64)');
        $imagick->thumbnailImage(100, 100, true, true);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::tintImage

(PECL imagick 2, PECL imagick 3)

Imagick::tintImage — Aplica un vector de color a cada píxel en la imagen

### Descripción

public function Imagick::tintImage(mixed `$tint`, mixed `$opacity`, bool `$legacy` = `false`): bool

Aplica un vector de color a cada píxel en la imagen. La longitud del vector es 0 para blanco y negro y su máximo para los medios-tonos. La función de precisión del vector es f(x)=(1-(4.0*((x-0.5)*(x-0.5)))).

### Parámetros

`tint`

`opacity`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
PECL imagick 2.1.0 | Ahora se permite que una string represente el color como primer parámetro y que un valor de tipo float represente la opacidad como segundo parámetro. Versiones previas sólo permitían un objeto ImagickPixel.

### Ejemplos

Ejemplo #1 Imagick::tintImage()

    <?php
    function tintImage($r, $g, $b, $a) {
        $a = $a / 100;

        $imagick = new \Imagick();
        $imagick->newPseudoImage(400, 400, 'gradient:black-white');

        $tint = new \ImagickPixel("rgb($r, $g, $b)");
        $opacity = new \ImagickPixel("rgb(128, 128, 128, $a)");
        $imagick->tintImage($tint, $opacity);
        $imagick->setImageFormat('png');
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::__toString

(PECL imagick 2, PECL imagick 3)

Imagick::__toString — Devuelve la imagen como un string

### Descripción

public function Imagick::__toString(): string

Devuelve la imagen actual como un string. Solamente devolverá una única imagen; no debería usarse con objetos Imagick que contengan varias imágenges, p.ej., un GIF animado o un PDF con varias páginas.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el contenido del string en caso de éxito o un string vacío en caso de fallo.

### Ver también

- Imagick::getImageBlob() - Devuelve la secuencia de imágenes como un blob
- Imagick::getImagesBlob() - Devuelve todas las imágenes de la secuencia en un BLOB

# Imagick::transformImage

(PECL imagick 2, PECL imagick 3)

Imagick::transformImage — Método conveniente para establecer el tamaño del recorte y la geometría de la imagen

Advertencia

Esta función está DEPRECADA a partir de Imagick 3.4.4. Depender de esta funcionalidad está fuertemente desaconsejado.

### Descripción

public function Imagick::transformImage(string `$crop`, string `$geometry`): Imagick

Método conveniente para establecer el tamaño del recorte y la geometría de la imagen desde cadenas. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

### Parámetros

`crop`

  Un string de geometría de recorte. Esta geometría define una sub-región de la imagen a recortar.

`geometry`

  Un string de geometría de imagen. Esta geometría define el tamaño final de la imagen.

### Valores devueltos

Devuelve un objeto Imagick que contiene la imagen transformada.

### Ejemplos

Ejemplo #1 Usar Imagick::transformImage():

El ejemplo crea una imagen negra de 100x100 black.

    <?php
    $imagen = new Imagick();
    $imagen->newImage(300, 200, "black");
    $imagen_nueva = $imagen->transformImage("100x100", "100x100");
    $imagen_nueva->writeImage('test_out.jpg');
    ?>

### Ver también

- Imagick::cropImage() - Extrae una región de la imagen
- Imagick::resizeImage() - Escala una imagen
- Imagick::thumbnailImage() - Modifica el tamaño de una imagen

# Imagick::transformImageColorspace

(PECL imagick 3)

Imagick::transformImageColorspace — Transforma una imagen en un nuevo espacio de color

### Descripción

public function Imagick::transformImageColorspace(int `$colorspace`): bool

Transforma una imagen en un nuevo espacio de color.

### Parámetros

`colorspace`

  El espacio de color al que debe transformarse la imagen, una de las constantes COLORSPACE, por ejemplo Imagick::COLORSPACE_CMYK.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::transformImageColorspace() ejemplo

Transforma una imagen en un nuevo espacio de color, luego extrae un solo canal para que los valores individuales de canal puedan visualizarse.

    <?php
    function transformImageColorspace($imagePath, $colorSpace, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->transformimagecolorspace($colorSpace);
        //channel debe ser una de las constantes de canal, por ejemplo \Imagick::CHANNEL_BLUE
        $imagick->separateImageChannel($channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }
    ?>

### Ver también

- Imagick::setColorSpace() - Establecer el espacio de color

# Imagick::transparentPaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::transparentPaintImage — Pinta píxeles transparentes

### Descripción

public function Imagick::transparentPaintImage(
mixed `$target`,
float `$alpha`,
float `$fuzz`,
bool `$invert`
): bool

Pinta píxeles transparente que coincidan con el color objetivo. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.8 o superior.

### Parámetros

`target`

  El color objetivo a pintar

`alpha`

  El grado de transparencia: 1.0 corresponde a totalmente opaco y 0.0 a totalmente transparente.

`fuzz`

  La cantidad de polvo de papel. Por ejemplo, definir el polvo de papel a 10 y el color rojo a una intensidad de 100 y 102 no será interpretado como el mismo color.

`invert`

  Si es `true` pinta cualquier píxel que no coincida con el color objetivo.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Imagick::transparentPaintImage()

    <?php
    function transparentPaintImage($color, $alpha, $fuzz) {
        $imagick = new \Imagick(realpath("images/BlueScreen.jpg"));

        //Need to be in a format that supports transparency
        $imagick->setimageformat('png');

        $imagick->transparentPaintImage(
            $color, $alpha, $fuzz * \Imagick::getQuantum(), false
        );

        //Not required, but helps tidy up left over pixels
        $imagick->despeckleimage();

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::transposeImage

(PECL imagick 2, PECL imagick 3)

Imagick::transposeImage — Aplica una simetría vertical

### Descripción

public function Imagick::transposeImage(): bool

Aplica una simetría vertical, creando la reflexión de cada píxel alrededor de un eje horizontal, con una rotación de 90 grados. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::transposeImage()

    <?php
    function transposeImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->transposeImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Ver también

- Imagick::transverseImage() - Crea un espejo horizontal de la imagen

# Imagick::transverseImage

(PECL imagick 2, PECL imagick 3)

Imagick::transverseImage — Crea un espejo horizontal de la imagen

### Descripción

public function Imagick::transverseImage(): bool

Crea un espejo horizontal de la imagen reflejando los píxeles alrededor de un eje Y central, y realizando una rotación de 270 grados. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::transverseImage()

    <?php
    function transverseImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->transverseImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Ver también

- Imagick::transposeImage() - Aplica una simetría vertical

# Imagick::trimImage

(PECL imagick 2, PECL imagick 3)

Imagick::trimImage — Elimina los extremos de la imagen

### Descripción

public function Imagick::trimImage(float `$fuzz`): bool

Elimina los extremos que son el color de fondo de la imagen. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

### Parámetros

`fuzz`

  Por defecto, el objetivo debe coincidir exactamente con un color de píxel en particular. Sin embargo, en la mayoría de los casos dos colores pueden diferir por una cantidad pequeña. El miembro enfoque de la imagen define cuánta tolerancia es aceptable para considerar que dos colores son el mismo. Este parámetro represenata la variación del rango de cuantía.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Usar Imagick::trimImage():

Recortar una imagen, después mostrarla en el navegador.

    <?php
    /* Crear el objeto y leer la imagen */
    $im = new Imagick("imagen.jpg");

    /* Recortar la imagen. */
    $im->trimImage(0);

    /* Imprimir la imagen */
    header("Content-Type: image/" . $im->getImageFormat());
    echo $im;
    ?>

### Ver también

- Imagick::getQuantumDepth() - Lee la profundidad cuántica
- Imagick::getQuantumRange() - Devuelve el intervalo cuántico de Imagick
- imagecropauto() - Recorta una imagen automáticamente utilizando uno de los modos disponibles

# Imagick::uniqueImageColors

(PECL imagick 2,PECL imagick 3)

Imagick::uniqueImageColors — Se conserva únicamente un color de píxel

### Descripción

public function Imagick::uniqueImageColors(): bool

Se conserva únicamente un color de píxel y se eliminan los demás. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::uniqueImageColors()

    <?php
    function uniqueImageColors($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        //Reduce la imagen a 256 colores de forma agradable.
        $imagick->quantizeImage(256, \Imagick::COLORSPACE_YIQ, 0, false, false);
        $imagick->uniqueImageColors();
        $imagick->scaleimage($imagick->getImageWidth(), $imagick->getImageHeight() * 20);
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::unsharpMaskImage

(PECL imagick 2, PECL imagick 3)

Imagick::unsharpMaskImage — Afila una imagen

### Descripción

public function Imagick::unsharpMaskImage(
float `$radius`,
float `$sigma`,
float `$amount`,
float `$threshold`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Afila una imagen. Se convoluciona la imagen con un operador gaussiano del radio y la desviación estándar (sigma) dados. Para obtener resultados razonables, el radio debería ser mayor que sigma. Use un radio de 0 y Imagick::sketchImage() seleccionará un radio apropiado automáticamente.

### Parámetros

`radius`

`sigma`

`amount`

`threshold`

`channel`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 Imagick::unsharpMaskImage()

    <?php
    function unsharpMaskImage($imagePath, $radius, $sigma, $amount, $unsharpThreshold) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->unsharpMaskImage($radius, $sigma, $amount, $unsharpThreshold);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::valid

(PECL imagick 2, PECL imagick 3)

Imagick::valid — Verifica si el elemento actual es válido

### Descripción

public function Imagick::valid(): bool

Verifica si el elemento actual es válido.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::vignetteImage

(PECL imagick 2, PECL imagick 3)

Imagick::vignetteImage — Añade un filtro de viñeta a la imagen

### Descripción

public function Imagick::vignetteImage(
float `$blackPoint`,
float `$whitePoint`,
int `$x`,
int `$y`
): bool

Suaviza los contornos de la imagen, al estilo de las viñetas. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

### Parámetros

`blackPoint`

  El radio del desenfoque

`whitePoint`

  La desviación estándar

`x`

  La abscisa de la elipse.

`y`

  La ordenada de la elipse.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::vignetteImage()

    <?php
    function vignetteImage($imagePath, $blackPoint, $whitePoint, $x, $y) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->vignetteImage($blackPoint, $whitePoint, $x, $y);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Ver también

- Imagick::waveImage() - Añade un filtro de ondas a la imagen
- Imagick::swirlImage() - Arremolina los píxeles desde el centro de la imagen

# Imagick::waveImage

(PECL imagick 2, PECL imagick 3)

Imagick::waveImage — Añade un filtro de ondas a la imagen

### Descripción

public function Imagick::waveImage(float `$amplitude`, float `$length`): bool

Añade un filtro de ondas a la imagen. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.2.9 o superior.

### Parámetros

`amplitude`

  Amplitud de la onda.

`length`

  Longitud de la onda.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Errores/Excepciones

Lanza una excepción ImagickException si ocurre un error.

### Ejemplos

Ejemplo #1 WaveImage puede ser muy lento: Imagick::waveImage()

    <?php
    function waveImage($imagePath, $amplitude, $length) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->waveImage($amplitude, $length);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Ver también

- Imagick::solarizeImage() - Aplica un efecto de solarización a la imagen
- Imagick::oilpaintImage() - Simula una pintura al óleo
- Imagick::embossImage() - Devuelve una imagen en escala de grises con un efecto tridimensional
- Imagick::addNoiseImage() - Añade ruido aleatorio a la imagen
- Imagick::swirlImage() - Arremolina los píxeles desde el centro de la imagen

# Imagick::whiteThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::whiteThresholdImage — Fuerza a todos los píxeles por encima del umbral a ser blancos

### Descripción

public function Imagick::whiteThresholdImage(mixed `$threshold`): bool

Es como Imagick::ThresholdImage() excepto que fuerza a todos los píxeles por encima del umbral a ser blancos dejando todos los píxeles por debajo del umbral sin cambios.

### Parámetros

`threshold`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Historial de cambios

Versión | Descripción
--- | ---
PECL imagick 2.1.0 | Ahora se permite que una cadena represente el color como parámetro. Versiones previas sólo permitían un objeto ImagickPixel.

### Ejemplos

Ejemplo #1 Imagick::whiteThresholdImage()

    <?php
    function whiteThresholdImage($imagePath, $color) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->whiteThresholdImage($color);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::writeImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImage — Escribe una imagen al nombre de fichero especificado

### Descripción

public function Imagick::writeImage(string `$filename` = NULL): bool

Escribe una imagen al nombre de fichero especificado. Si el parámetro 'filename' es NULL, la imagen se escribe en el nombre de fichero establecido por Imagick::readImage() o Imagick::setImageFilename().

### Parámetros

`filename`

  Nombre del fichero donde escribir la imagen. La extensión del nombre de fichero define el tipo del fichero. El formato puede ser forzado independientemente del formato que use la extensión del fichero: usando un prefijo, por ejemplo "jpg:test.png".

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::writeImageFile

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImageFile — Escribe una imagen en un descriptor de archivo

### Descripción

public function Imagick::writeImageFile(resource `$filehandle`, string `$format` = ?): bool

Escribe la secuencia de la imagen en un descriptor de archivo abierto. El descriptor debe haber sido abierto con, por ejemplo, la función fopen. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.6 o superior.

### Parámetros

`filehandle`

  Descriptor de archivo en el cual la imagen será escrita.

`format`

  El formato de la imagen. La lista de especificadores de formato válidos depende del conjunto de funcionalidades compilado de ImageMagick, y puede ser consultada en tiempo de ejecución mediante Imagick::queryFormats().

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ver también

- Imagick::queryFormats() - Devuelve los formatos soportados por Imagick

# Imagick::writeImages

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImages — Escribe una imagen o secuencia de imágenes

### Descripción

public function Imagick::writeImages(string `$filename`, bool `$adjoin`): bool

Escribe una imagen o secuencia de imágenes.

### Parámetros

`filename`

`adjoin`

### Valores devueltos

Devuelve `true` en caso de éxito.

# Imagick::writeImagesFile

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImagesFile — Escribe los frames en un descriptor de ficheros

### Descripción

public function Imagick::writeImagesFile(resource `$filehandle`, string `$format` = ?): bool

Escribe todas las frames de una imagen en un descriptor de fichero. Este método puede ser utilizado para escribir gifs animados u otras imágenes compuestas por múltiples frames en un descriptor de fichero abierto. Este método solo está disponible si Imagick ha sido compilado con ImageMagick versión 6.3.6 o superior.

### Parámetros

`filehandle`

  Descriptor de fichero en el que se escribirán las frames.

`format`

  El formato de la imagen. La lista de especificadores de formato válidos depende del conjunto de características compiladas de ImageMagick, y puede ser consultada en tiempo de ejecución mediante Imagick::queryFormats().

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ver también

- Imagick::queryFormats() - Devuelve los formatos soportados por Imagick

## Tabla de contenidos

- Imagick::adaptiveBlurImage — Añade un filtro de borrosidad adaptativo a la imagen
- Imagick::adaptiveResizeImage — Redimensiona una imagen adaptativamente con información dependiente de la triangulación
- Imagick::adaptiveSharpenImage — Afila la imagen adaptativamente
- Imagick::adaptiveThresholdImage — Selecciona un umbral para cada píxel basado en un rango de intensidad
- Imagick::addImage — Añade una nueva imagen a la lista de imágenes del objeto Imagick
- Imagick::addNoiseImage — Añade ruido aleatorio a la imagen
- Imagick::affineTransformImage — Transforma una imagen
- Imagick::animateImages — Anima una imagen o imágenes
- Imagick::annotateImage — Anota una imagen con texto
- Imagick::appendImages — Añade un conjunto de imágenes
- Imagick::autoLevelImage — Ajusta el nivel de un canal de una imagen particular
- Imagick::averageImages — Promedio de un conjunto de imágenes
- Imagick::blackThresholdImage — Fuerza a todos los píxeles bajo un umbral a ser negros
- Imagick::blueShiftImage — Atenúa los colores de la imagen
- Imagick::blurImage — Añade un filtro de borrosidad a la imagen
- Imagick::borderImage — Rodea la imagen con un borde
- Imagick::brightnessContrastImage — Cambia el brillo y/o el contraste de una imagen
- Imagick::charcoalImage — Simula un dibujo a carboncillo
- Imagick::chopImage — Borra una región de una imagen y la recorta
- Imagick::clampImage — Restringe el rango de colores de 0 a la profundidad cuántica
- Imagick::clear — Libera todos los recursos asociados a un objeto Imagick
- Imagick::clipImage — Se alinea con el primer camino de un perfil 8BIM
- Imagick::clipImagePath — Recorta a lo largo de las rutas nombradas del perfil 8BIM, si está presente
- Imagick::clipPathImage — Recorta a lo largo de trazados nominados desde un perfil 8BIM
- Imagick::clone — Realiza una copia exacta de un objeto Imagick
- Imagick::clutImage — Reemplaza los colores de una imagen
- Imagick::coalesceImages — Componer un conjunto de imágenes
- Imagick::colorFloodfillImage — Cambia el valor del color de cualquier píxel que coincida con el objetivo
- Imagick::colorizeImage — Mezcla el color de relleno con la imagen
- Imagick::colorMatrixImage — Aplica una transformación de color a una imagen
- Imagick::combineImages — Combina una o más imágenes en una sóla imagen
- Imagick::commentImage — Añade un comentario a la imagen
- Imagick::compareImageChannels — Devuelve la diferencia entre una o más imágenes
- Imagick::compareImageLayers — Devuelve la región circundante máxima entre imágenes
- Imagick::compareImages — Compara una imagen con otra reconstruida
- Imagick::compositeImage — Compone una imagen en otra
- Imagick::__construct — El constructor Imagick
- Imagick::contrastImage — Cambia el contraste de una imagen
- Imagick::contrastStretchImage — Mejora el contraste de una imagen en color
- Imagick::convolveImage — Aplica una semilla de convolución a medida a la imagen
- Imagick::count — Devuelve el número de imágenes
- Imagick::cropImage — Extrae una región de la imagen
- Imagick::cropThumbnailImage — Crea una miniatura recortada
- Imagick::current — Devuelve una referencia al objeto Imagick actual
- Imagick::cycleColormapImage — Desplaza el mapa de colores de una imagen
- Imagick::decipherImage — Descifra una imagen
- Imagick::deconstructImages — Devuelve las diferencias de ciertos píxeles entre dos imágenes
- Imagick::deleteImageArtifact — Borra un artefacto de imagen
- Imagick::deleteImageProperty — Elimina una propiedad de imagen
- Imagick::deskewImage — Elimina la torción de la imagen
- Imagick::despeckleImage — Reduce el ruido speckle de una imagen
- Imagick::destroy — Destruye un objeto Imagick
- Imagick::displayImage — Muestra una imagen
- Imagick::displayImages — Muestra una imagen o una secuencia de imágenes
- Imagick::distortImage — Deforma una imagen utilizando varios métodos de distorsión
- Imagick::drawImage — Renderiza el objeto ImagickDraw a la imagen actual
- Imagick::edgeImage — Mejora los bordes de la imagen
- Imagick::embossImage — Devuelve una imagen en escala de grises con un efecto tridimensional
- Imagick::encipherImage — Cifra una imagen
- Imagick::enhanceImage — Mejora la calidad de una imagen ruidosa
- Imagick::equalizeImage — Iguala el histograma de una imagen
- Imagick::evaluateImage — Aplica una expresión a una imagen
- Imagick::exportImagePixels — Exporta los píxeles brutos de la imagen
- Imagick::extentImage — Establecer el tamaño de la imagen
- Imagick::filter — Aplica un núcleo de convolución personalizado a la imagen
- Imagick::flattenImages — Fusiona una secuencia de imágenes
- Imagick::flipImage — Crea una imagen por espejo vertical
- Imagick::floodFillPaintImage — Cambia el valor del color de cualquier píxel que coincida con el objetivo
- Imagick::flopImage — Crea una imagen por espejo horizontal
- Imagick::forwardFourierTransformImage — Implementa la transformada discreta de Fourier (Discrete Fourier Transform - DFT)
- Imagick::frameImage — Añade un borde tridimensional simulado
- Imagick::functionImage — Aplica una función sobre la imagen
- Imagick::fxImage — Evalúa una expresión por cada píxel de la imagen
- Imagick::gammaImage — Corrección gamma de una imagen
- Imagick::gaussianBlurImage — Hace borrosa una imagen
- Imagick::getColorspace — Obtiene el espacio de colores
- Imagick::getCompression — Lee el tipo de compresión
- Imagick::getCompressionQuality — Lee la calidad de la compresión
- Imagick::getCopyright — Devuelve el copyright de la API ImageMagick
- Imagick::getFilename — Lee el nombre del fichero asociado a una secuencia
- Imagick::getFont — Obtiene la fuente de caracteres
- Imagick::getFormat — Devuelve el formato de la imagen Imagick
- Imagick::getGravity — Obtiene la gravedad
- Imagick::getHomeURL — Devuelve la URL de ImageMagick
- Imagick::getImage — Devuelve un nuevo objeto Imagick
- Imagick::getImageAlphaChannel — Verifica si la imagen tiene un canal alfa
- Imagick::getImageArtifact — Obtener el artefacto de imagen
- Imagick::getImageAttribute — Obtiene un atributo nombrado
- Imagick::getImageBackgroundColor — Devuelve el color de fondo
- Imagick::getImageBlob — Devuelve la secuencia de imágenes como un blob
- Imagick::getImageBluePrimary — Devuelve el punto primario azul de la cromaticidad
- Imagick::getImageBorderColor — Devuelve el color del borde de la imagen
- Imagick::getImageChannelDepth — Obtiene la profundidad de un canal de imagen en particular
- Imagick::getImageChannelDistortion — Compara los canales de imagen de una imagen con una imagen reconstruida
- Imagick::getImageChannelDistortions — Obtiene las distorsiones de un canal
- Imagick::getImageChannelExtrema — Obtiene los extremos de uno o más canales de imagen
- Imagick::getImageChannelKurtosis — Obtiene la curtosis y la asimetría estadística de un canal específico
- Imagick::getImageChannelMean — Obtiene la media y la desviación estándar
- Imagick::getImageChannelRange — Obtiene el rango del canal
- Imagick::getImageChannelStatistics — Devuelve estadísticas sobre cada canal de la imagen
- Imagick::getImageClipMask — Obtiene la máscara de recorte de la imagen
- Imagick::getImageColormapColor — Devuelve el color del índice del mapa de colores especficado
- Imagick::getImageColors — Lee el número de colores únicos de la imagen
- Imagick::getImageColorspace — Obtiene el espacio de colores de la imagen
- Imagick::getImageCompose — Devuelve el operador de composición asociado a una imagen
- Imagick::getImageCompression — Lee el tipo de compresión de la imagen
- Imagick::getImageCompressionQuality — Lee la calidad de compresión de la imagen
- Imagick::getImageDelay — Lee el retraso de la imagen
- Imagick::getImageDepth — Se lee la profundidad de la imagen
- Imagick::getImageDispose — Lee el método de recuperación
- Imagick::getImageDistortion — Compara una imagen con una imagen reconstruida
- Imagick::getImageExtrema — Lee los extremos de una imagen
- Imagick::getImageFilename — Devuelve el nombre de un fichero para una imagen en una secuencia
- Imagick::getImageFormat — Devuelve el formato de una imagen en una secuencia
- Imagick::getImageGamma — Obtiene el gamma de la imagen
- Imagick::getImageGeometry — Lee las dimensiones de la imagen en un array
- Imagick::getImageGravity — Obtiene la gravedad de la imagen
- Imagick::getImageGreenPrimary — Devuelve la cromaticidad del color verde
- Imagick::getImageHeight — Devuelve la altura de la imagen
- Imagick::getImageHistogram — Devuelve el histograma de la imagen
- Imagick::getImageIndex — Obtiene el índice de la imagen actual
- Imagick::getImageInterlaceScheme — Se lee el esquema de entrelazado de la imagen
- Imagick::getImageInterpolateMethod — Devuelve el método de interpolación
- Imagick::getImageIterations — Obtiene las iteraciones de la imagen
- Imagick::getImageLength — Devuelve el tamaño de la imagen en bytes
- Imagick::getImageMatte — Indica si la imagen tiene un canal mat
- Imagick::getImageMatteColor — Devuelve el color mate de la imagen
- Imagick::getImageMimeType — Devuelve el tipo MIME de la imagen
- Imagick::getImageOrientation — Lee la orientación de la imagen
- Imagick::getImagePage — Devuelve la geometría de la página
- Imagick::getImagePixelColor — Devuelve el color del píxel especificado
- Imagick::getImageProfile — Devuelve el perfil nominado de la imagen
- Imagick::getImageProfiles — Devuelve los perfiles de la imagen
- Imagick::getImageProperties — Devuelve las propiedades EXIF de la imagen
- Imagick::getImageProperty — Devuelve una propiedad de una imagen
- Imagick::getImageRedPrimary — Devuelve la cromaticidad del punto rojo
- Imagick::getImageRegion — Extrae una región de la imagen
- Imagick::getImageRenderingIntent — Lee el método de renderizado de la imagen
- Imagick::getImageResolution — Lee las resoluciones en X y Y de una imagen
- Imagick::getImagesBlob — Devuelve todas las imágenes de la secuencia en un BLOB
- Imagick::getImageScene — Devuelve la escena de la imagen
- Imagick::getImageSignature — Genera una firma SHA-256
- Imagick::getImageSize — Devuelve el tamaño de la imagen en bytes
- Imagick::getImageTicksPerSecond — Se leen los ticks-por-segundo de la imagen
- Imagick::getImageTotalInkDensity — Lee la densidad total de tinta de la imagen
- Imagick::getImageType — Obtiene el tipo posible de imagen
- Imagick::getImageUnits — Devuelve las unidades de resolución de la imagen
- Imagick::getImageVirtualPixelMethod — Devuelve el método del píxel virtual
- Imagick::getImageWhitePoint — Devuelve la cromaticidad del punto blanco
- Imagick::getImageWidth — Devuelve el ancho de la imagen
- Imagick::getInterlaceScheme — Lee el esquema de entrelazado del objeto
- Imagick::getIteratorIndex — Lee el índice de la imagen activa actual
- Imagick::getNumberImages — Devuelve el número de imágenes de un objeto
- Imagick::getOption — Devuelve un valor asociado con la clave especificada
- Imagick::getPackageName — Devuelve el nombre del paquete ImageMagick
- Imagick::getPage — Devuelve la geometría de la página
- Imagick::getPixelIterator — Devuelve un MagickPixelIterator
- Imagick::getPixelRegionIterator — Obtiene un objeto ImagickPixelIterator de una sección de imagen
- Imagick::getPointSize — Obtiene el tamaño del punto
- Imagick::getQuantum — Devuelve el espacio cuántico de ImageMagick
- Imagick::getQuantumDepth — Lee la profundidad cuántica
- Imagick::getQuantumRange — Devuelve el intervalo cuántico de Imagick
- Imagick::getRegistry — Obtiene un elemento de StringRegistry
- Imagick::getReleaseDate — Devuelve la fecha de publicación de ImageMagick
- Imagick::getResource — Devuelve el consumo de memoria de la recurso
- Imagick::getResourceLimit — Devuelve el límite de la recurso
- Imagick::getSamplingFactors — Lee el factor de muestreo horizontal y vertical
- Imagick::getSize — Retorna el tamaño asociado con un objeto Imagick
- Imagick::getSizeOffset — Devuelve el tamaño de la posición
- Imagick::getVersion — Devuelve la API de ImageMagick
- Imagick::haldClutImage — Reemplaza los colores de la imagen
- Imagick::hasNextImage — Verifica si un objeto tiene una imagen siguiente
- Imagick::hasPreviousImage — Verifica si un objeto tiene una imagen anterior
- Imagick::identifyFormat — Formatea un string con los detalles de la imagen
- Imagick::identifyImage — Identifica una imagen y obtiene sus atributos
- Imagick::implodeImage — Crea una nueva imagen como una copia
- Imagick::importImagePixels — Importa los píxeles de una imagen
- Imagick::inverseFourierTransformImage — Implementa la transformada inversa de Fourier discreta (Discrete Fourier Transform - DFT)
- Imagick::labelImage — Añade una etiqueta a una imagen
- Imagick::levelImage — Ajusta los niveles de la imagen
- Imagick::linearStretchImage — Estrecha con saturación la intensidad de la imagen
- Imagick::liquidRescaleImage — Anima una imagen o imágenes
- Imagick::listRegistry — Lista todos los parámetros del registro
- Imagick::magnifyImage — Duplica el tamaño de una imagen, proporcionalmente
- Imagick::mapImage — Reemplaza los colores de una imagen con el color más cercano de una imagen de referencia
- Imagick::matteFloodfillImage — Cambia el valor de transparencia de un color
- Imagick::medianFilterImage — Aplica un filtro digital
- Imagick::mergeImageLayers — Fusiona las capas de la imagen
- Imagick::minifyImage — Redimensiona una imagen proporcionalmente para reducirla a la mitad de tamaño
- Imagick::modulateImage — Controla el brillo, la saturación y el tono
- Imagick::montageImage — Crea una imagen compuesta
- Imagick::morphImages — Metamorfosea un conjunto de imágenes
- Imagick::morphology — Aplica un núcleo personalizado a la imagen según el método de morfología dado
- Imagick::mosaicImages — Forma una mosaico de imágenes
- Imagick::motionBlurImage — Simula borrosidad en movimiento
- Imagick::negateImage — Invierte los colores en la imagen de referencia
- Imagick::newImage — Crea una nueva imagen
- Imagick::newPseudoImage — Crea una nueva imagen
- Imagick::nextImage — Pasa a la siguiente imagen
- Imagick::normalizeImage — Mejora el contraste de una imagen a color
- Imagick::oilPaintImage — Simula una pintura al óleo
- Imagick::opaquePaintImage — Cambia el color de cualquier píxel que coincida con el objetivo
- Imagick::optimizeImageLayers — Elimina las porciones recurrentes de imágenes a optimizar
- Imagick::orderedPosterizeImage — Realiza un entramado ordenado
- Imagick::paintFloodfillImage — Cambia el valor del color de cualquier píxel que coincida con el objetivo
- Imagick::paintOpaqueImage — Cambia cualquier píxel que coincida con el color
- Imagick::paintTransparentImage — Cambia cualquier píxel que coincida con el color definido para el relleno
- Imagick::pingImage — Trae los atributos básicos de una imagen
- Imagick::pingImageBlob — Traer los atributos rápidamente
- Imagick::pingImageFile — Obtener los atrbutos básicos de la imagen de una manera liviana
- Imagick::polaroidImage — Simula una fotografía Polaroid
- Imagick::posterizeImage — Reduce la imagen a un número limitado de niveles de color
- Imagick::previewImages — Precisa rápidamente los parámetros apropiados para el procesamiento de la imagen
- Imagick::previousImage — Pasa a la imagen anterior en una secuencia de imágenes
- Imagick::profileImage — Añade o elimina un perfil de una imagen
- Imagick::quantizeImage — Analiza los colores dentro de una imagen de referencia
- Imagick::quantizeImages — Analiza los colores dentro de una secuencia de imágenes
- Imagick::queryFontMetrics — Devuelve una matriz que representa las métricas de la fuente
- Imagick::queryFonts — Devuelve la lista de fuentes configuradas
- Imagick::queryFormats — Devuelve los formatos soportados por Imagick
- Imagick::radialBlurImage — Hace borrosa de forma radial una imagen
- Imagick::raiseImage — Crea un efecto de botón en 3D simulado
- Imagick::randomThresholdImage — Crea una imagen de alto contraste y dos colores
- Imagick::readImage — Lee una imagen desde un nombre de fichero
- Imagick::readImageBlob — Lee una imagen desde un string binario
- Imagick::readImageFile — Lee una imagen desde un gestor de fichero abierto
- Imagick::readImages — Lee una imagen a partir de un array de nombres de ficheros
- Imagick::recolorImage — Recolorear la imagen
- Imagick::reduceNoiseImage — Suaviza los contornos de una imagen
- Imagick::remapImage — Re-mapea los colores de una imagen
- Imagick::removeImage — Elimina una imagen de la lista
- Imagick::removeImageProfile — Elimina el perfil nominado de la imagen y lo devuelve
- Imagick::render — Muestra todas las comandos de dibujo previas
- Imagick::resampleImage — Remuestrea la imagen a la resolución deseada
- Imagick::resetImagePage — Reinicia una página de imagen
- Imagick::resizeImage — Escala una imagen
- Imagick::rollImage — Compensa una imagen
- Imagick::rotateImage — Rota una imagen
- Imagick::rotationalBlurImage — Aplica un desenfoque rotacional a una imagen
- Imagick::roundCorners — Redondea las esquinas de una imagen
- Imagick::sampleImage — Escala una imagen con un muestreo de píxeles
- Imagick::scaleImage — Redimensiona la imagen a una escala específica
- Imagick::segmentImage — Segmenta una imagen
- Imagick::selectiveBlurImage — Desenfoca selectivamente una imagen dentro de un umbral de contraste
- Imagick::separateImageChannel — Separa un canal de la imagen
- Imagick::sepiaToneImage — Pone una imagen en tono sepia
- Imagick::setBackgroundColor — Establece el color de fondo por omisión del objeto
- Imagick::setColorspace — Establecer el espacio de color
- Imagick::setCompression — Configura el tipo de compresión del objeto
- Imagick::setCompressionQuality — Configura la compresión por defecto del objeto
- Imagick::setFilename — Establece el nombre de archivo antes de que se lea o escriba una imagen
- Imagick::setFirstIterator — Coloca el iterador de Imagick en la primera imagen
- Imagick::setFont — Configura la fuente
- Imagick::setFormat — Establece el formato del objeto Imagick
- Imagick::setGravity — Establece la gravedad
- Imagick::setImage — Reemplaza una imagen en el objeto
- Imagick::setImageAlphaChannel — Define el canal alfa de la imagen
- Imagick::setImageArtifact — Define el artefacto de la imagen
- Imagick::setImageAttribute — Define un atributo de imagen
- Imagick::setImageBackgroundColor — Establece el color de fondo de la imagen
- Imagick::setImageBias — Establece el sesgo de la imagen para cualquier método que convolucione una imagen
- Imagick::setImageBiasQuantum — Establece el sesgo de la imagen
- Imagick::setImageBluePrimary — Establece el punto primario azul de la cromaticidad de la imagen
- Imagick::setImageBorderColor — Establece el color de borde de la imagen
- Imagick::setImageChannelDepth — Establece la profundidad de una canal de imagen en particular
- Imagick::setImageClipMask — Establece la máscara de recorte de una imagen
- Imagick::setImageColormapColor — Establece el color de un índice de mapa de color especificado
- Imagick::setImageColorspace — Establece el espacio de color de una imagen
- Imagick::setImageCompose — Establece el operador de composción de una imagen
- Imagick::setImageCompression — Establece la compresión de una imagen
- Imagick::setImageCompressionQuality — Establece la calidad de compresión de una imagen
- Imagick::setImageDelay — Establece el retardo de una imagen
- Imagick::setImageDepth — Establece la profundidad de una imagen
- Imagick::setImageDispose — Establece el método de disposición de una imagen
- Imagick::setImageExtent — Establece el tamaño de una imagen
- Imagick::setImageFilename — Establece el nombre de archivo de una imagen en particular
- Imagick::setImageFormat — Establece el formato de una imagen en particular
- Imagick::setImageGamma — Establece el valor gamma de la imagen
- Imagick::setImageGravity — Establece la gravedad de la imagen
- Imagick::setImageGreenPrimary — Establece el punto primario verde de la cromaticidad de la imagen
- Imagick::setImageIndex — Establece la posición del iterador
- Imagick::setImageInterlaceScheme — Establece la compresión de la imagen
- Imagick::setImageInterpolateMethod — Configura el método de interpolación de la imagen
- Imagick::setImageIterations — Establece las iteraciones de una imagen
- Imagick::setImageMatte — Establece el canal mate de la imagen
- Imagick::setImageMatteColor — Establece el color mate de la imagen
- Imagick::setImageOpacity — Establece el nivel de opacidad de la imagen
- Imagick::setImageOrientation — Establece la orientación de la imagen
- Imagick::setImagePage — Establece la geometría de la página de la imagen
- Imagick::setImageProfile — Añade un perfil nominado al objeto Imagick
- Imagick::setImageProperty — Configura una propiedad de imagen
- Imagick::setImageRedPrimary — Establece el punto primario rojo de la cromaticidad de la imagen
- Imagick::setImageRenderingIntent — Establece el propósito de renderización de la imagen
- Imagick::setImageResolution — Establece la resolución de la imagen
- Imagick::setImageScene — Establece la escena de la imagen
- Imagick::setImageTicksPerSecond — Establece los ticks por segundo de la imagen
- Imagick::setImageType — Establece el tipo de imagen
- Imagick::setImageUnits — Establece las unidades de resolución de la imagen
- Imagick::setImageVirtualPixelMethod — Establece el método de píxel virtual de la imagen
- Imagick::setImageWhitePoint — Establece el punto blanco de cromaticidad de la imagen
- Imagick::setInterlaceScheme — Establece la compresión de la imagen
- Imagick::setIteratorIndex — Establece la posición del iterador
- Imagick::setLastIterator — Posiciona el iterador Imagick en la última imagen
- Imagick::setOption — Configura una opción de un objeto Imagick
- Imagick::setPage — Establece la geometría de página del objeto Imagick
- Imagick::setPointSize — Define la medida del punto
- Imagick::setProgressMonitor — Define una función de retrollamada a ser llamada durante el procesamiento
- Imagick::setRegistry — Define la entrada del registro ImageMagick nombrada clave para valor
- Imagick::setResolution — Establece la resolución de la imagen
- Imagick::setResourceLimit — Define la limitación para una recurso particular
- Imagick::setSamplingFactors — Establece los factores de muestreo de la imagen
- Imagick::setSize — Establece el tamaño del objeto Imagick
- Imagick::setSizeOffset — Establece el tamaño y el índice del objeto Imagick
- Imagick::setType — Establece el atributo tipo de imagen
- Imagick::shadeImage — Crea un efecto en 3D
- Imagick::shadowImage — Simula una sombra de imagen
- Imagick::sharpenImage — Afila una imagen
- Imagick::shaveImage — Recorta píxeles de los extremos de la imagen
- Imagick::shearImage — Crea un paralelogramo
- Imagick::sigmoidalContrastImage — Ajusta el contraste de la imagen
- Imagick::sketchImage — Simula el bosquejo de un lapiz
- Imagick::smushImages — Toma todas las imágenes del puntero de imagen actual hasta el final de la lista de imágenes y las comprime
- Imagick::solarizeImage — Aplica un efecto de solarización a la imagen
- Imagick::sparseColorImage — Interpola colores
- Imagick::spliceImage — Une un color sólido en la imagen
- Imagick::spreadImage — Despalza aleatoriamente cada píxel en un bloque
- Imagick::statisticImage — Modifica una imagen utilizando una función estadística
- Imagick::steganoImage — Oculta una marca de agua digital dentro de la imagen
- Imagick::stereoImage — Compone dos imágenes
- Imagick::stripImage — Elimina de una imagen todos los perfiles y los comentarios
- Imagick::subImageMatch — Busca una subimagen en la imagen actual y devuelve una imagen de similitud
- Imagick::swirlImage — Arremolina los píxeles desde el centro de la imagen
- Imagick::textureImage — Repite los mosaicos de la textura de una imagen
- Imagick::thresholdImage — Cambia el valor de píexeles individuales basdos en un umbral
- Imagick::thumbnailImage — Modifica el tamaño de una imagen
- Imagick::tintImage — Aplica un vector de color a cada píxel en la imagen
- Imagick::__toString — Devuelve la imagen como un string
- Imagick::transformImage — Método conveniente para establecer el tamaño del recorte y la geometría de la imagen
- Imagick::transformImageColorspace — Transforma una imagen en un nuevo espacio de color
- Imagick::transparentPaintImage — Pinta píxeles transparentes
- Imagick::transposeImage — Aplica una simetría vertical
- Imagick::transverseImage — Crea un espejo horizontal de la imagen
- Imagick::trimImage — Elimina los extremos de la imagen
- Imagick::uniqueImageColors — Se conserva únicamente un color de píxel
- Imagick::unsharpMaskImage — Afila una imagen
- Imagick::valid — Verifica si el elemento actual es válido
- Imagick::vignetteImage — Añade un filtro de viñeta a la imagen
- Imagick::waveImage — Añade un filtro de ondas a la imagen
- Imagick::whiteThresholdImage — Fuerza a todos los píxeles por encima del umbral a ser blancos
- Imagick::writeImage — Escribe una imagen al nombre de fichero especificado
- Imagick::writeImageFile — Escribe una imagen en un descriptor de archivo
- Imagick::writeImages — Escribe una imagen o secuencia de imágenes
- Imagick::writeImagesFile — Escribe los frames en un descriptor de ficheros

# La clase ImagickDraw

(PECL imagick 2, PECL imagick 3)

## Sinopsis de la Clase

class ImagickDraw {
public function affine(array `$affine`): bool
public function annotation(float `$x`, float `$y`, string `$text`): bool
public function arc(
float `$start_x`,
float `$start_y`,
float `$end_x`,
float `$end_y`,
float `$start_angle`,
float `$end_angle`
): bool
public function bezier(array `$coordinates`): bool
public function circle(
float `$origin_x`,
float `$origin_y`,
float `$perimeter_x`,
float `$perimeter_y`
): bool
public function clear(): bool
public function clone(): ImagickDraw
public function color(float `$x`, float `$y`, int `$paint`): bool
public function comment(string `$comment`): bool
public function composite(
int `$composite`,
float `$x`,
float `$y`,
float `$width`,
float `$height`,
Imagick `$image`
): bool
public function destroy(): bool
public function ellipse(
float `$origin_x`,
float `$origin_y`,
float `$radius_x`,
float `$radius_y`,
float `$angle_start`,
float `$angle_end`
): bool
public function getClipPath(): false|string
public function getClipRule(): int
public function getClipUnits(): int
public function getFillColor(): ImagickPixel
public function getFillOpacity(): float
public function getFillRule(): int
public function getFont(): string
public function getFontFamily(): string
public function getFontSize(): float
public function getFontStretch(): int
public function getFontStyle(): int
public function getFontWeight(): int
public function getGravity(): int
public function getStrokeAntialias(): bool
public function getStrokeColor(): ImagickPixel
public function getStrokeDashArray(): array
public function getStrokeDashOffset(): float
public function getStrokeLineCap(): int
public function getStrokeLineJoin(): int
public function getStrokeMiterLimit(): int
public function getStrokeOpacity(): float
public function getStrokeWidth(): float
public function getTextAlignment(): int
public function getTextAntialias(): bool
public function getTextDecoration(): int
public function getTextEncoding(): false|string
public function getTextInterlineSpacing(): float
public function getTextInterwordSpacing(): float
public function getTextKerning(): float
public function getTextUnderColor(): ImagickPixel
public function getVectorGraphics(): string
public function line(
float `$start_x`,
float `$start_y`,
float `$end_x`,
float `$end_y`
): bool
public function matte(float `$x`, float `$y`, int `$paint`): bool
public function pathClose(): bool
public function pathCurveToAbsolute(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
public function pathCurveToQuadraticBezierAbsolute(
float `$x1`,
float `$y1`,
float `$x_end`,
float `$y`
): bool
public function pathCurveToQuadraticBezierRelative(
float `$x1`,
float `$y1`,
float `$x_end`,
float `$y`
): bool
public function pathCurveToQuadraticBezierSmoothAbsolute(float `$x`, float `$y`): bool
public function pathCurveToQuadraticBezierSmoothRelative(float `$x`, float `$y`): bool
public function pathCurveToRelative(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
public function pathCurveToSmoothAbsolute(
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
public function pathCurveToSmoothRelative(
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
public function pathEllipticArcAbsolute(
float `$rx`,
float `$ry`,
float `$x_axis_rotation`,
bool `$large_arc`,
bool `$sweep`,
float `$x`,
float `$y`
): bool
public function pathEllipticArcRelative(
float `$rx`,
float `$ry`,
float `$x_axis_rotation`,
bool `$large_arc`,
bool `$sweep`,
float `$x`,
float `$y`
): bool
public function pathFinish(): bool
public function pathLineToAbsolute(float `$x`, float `$y`): bool
public function pathLineToHorizontalAbsolute(float `$x`): bool
public function pathLineToHorizontalRelative(float `$x`): bool
public function pathLineToRelative(float `$x`, float `$y`): bool
public function pathLineToVerticalAbsolute(float `$y`): bool
public function pathLineToVerticalRelative(float `$y`): bool
public function pathMoveToAbsolute(float `$x`, float `$y`): bool
public function pathMoveToRelative(float `$x`, float `$y`): bool
public function pathStart(): bool
public function point(float `$x`, float `$y`): bool
public function polygon(array `$coordinates`): bool
public function polyline(array `$coordinates`): bool
public function pop(): bool
public function popClipPath(): bool
public function popDefs(): bool
public function popPattern(): bool
public function push(): bool
public function pushClipPath(string `$clip_mask_id`): bool
public function pushDefs(): bool
public function pushPattern(
string `$pattern_id`,
float `$x`,
float `$y`,
float `$width`,
float `$height`
): bool
public function rectangle(
float `$top_left_x`,
float `$top_left_y`,
float `$bottom_right_x`,
float `$bottom_right_y`
): bool
public function render(): bool
public function resetVectorGraphics(): bool
public function rotate(float `$degrees`): bool
public function roundRectangle(
float `$top_left_x`,
float `$top_left_y`,
float `$bottom_right_x`,
float `$bottom_right_y`,
float `$rounding_x`,
float `$rounding_y`
): bool
public function scale(float `$x`, float `$y`): bool
public function setClipPath(string `$clip_mask`): bool
public function setClipRule(int `$fillrule`): bool
public function setClipUnits(int `$pathunits`): bool
public function setFillAlpha(float `$alpha`): bool
public function setFillColor(ImagickPixel|string `$fill_color`): bool
public function setFillOpacity(float `$opacity`): bool
public function setFillPatternURL(string `$fill_url`): bool
public function setFillRule(int `$fillrule`): bool
public function setFont(string `$font_name`): bool
public function setFontFamily(string `$font_family`): bool
public function setFontSize(float `$point_size`): bool
public function setFontStretch(int `$stretch`): bool
public function setFontStyle(int `$style`): bool
public function setFontWeight(int `$weight`): bool
public function setGravity(int `$gravity`): bool
public function setResolution(float `$resolution_x`, float `$resolution_y`): bool
public function setStrokeAlpha(float `$alpha`): bool
public function setStrokeAntialias(bool `$enabled`): bool
public function setStrokeColor(ImagickPixel|string `$color`): bool
public function setStrokeDashArray(?array `$dashes`): bool
public function setStrokeDashOffset(float `$dash_offset`): bool
public function setStrokeLineCap(int `$linecap`): bool
public function setStrokeLineJoin(int `$linejoin`): bool
public function setStrokeMiterLimit(int `$miterlimit`): bool
public function setStrokeOpacity(float `$opacity`): bool
public function setStrokePatternURL(string `$stroke_url`): bool
public function setStrokeWidth(float `$width`): bool
public function setTextAlignment(int `$align`): bool
public function setTextAntialias(bool `$antialias`): bool
public function setTextDecoration(int `$decoration`): bool
public function setTextEncoding(string `$encoding`): bool
public function setTextInterlineSpacing(float `$spacing`): bool
public function setTextInterwordSpacing(float `$spacing`): bool
public function setTextKerning(float `$kerning`): bool
public function setTextUnderColor(ImagickPixel|string `$under_color`): bool
public function setVectorGraphics(string `$xml`): bool
public function setViewbox(
int `$left_x`,
int `$top_y`,
int `$right_x`,
int `$bottom_y`
): bool
public function skewX(float `$degrees`): bool
public function skewY(float `$degrees`): bool
public function translate(float `$x`, float `$y`): bool
}

# ImagickDraw::affine

(PECL imagick 2, PECL imagick 3)

ImagickDraw::affine — Ajusta la matriz de transformación afín actual

### Descripción

public function ImagickDraw::affine(array `$affine`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Ajusta la matriz de transformación afín actual con la matriz de transformación afín especificada.

### Parámetros

`affine`

  Los parámetros de la matriz afín

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo de ImagickDraw::affine()

    <?php
    function affine($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeWidth(1);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);

        $PI = 3.141592653589794;
        $angle = 60 * $PI / 360;

        //Scale the drawing co-ordinates.
        $affineScale = array("sx" => 1.75, "sy" => 1.75, "rx" => 0, "ry" => 0, "tx" => 0, "ty" => 0);

        //Shear the drawing co-ordinates.
        $affineShear = array("sx" => 1, "sy" => 1, "rx" => sin($angle), "ry" => -sin($angle), "tx" => 0, "ty" => 0);

        //Rotate the drawing co-ordinates. The shear affine matrix
        //produces incorrectly scaled drawings.
        $affineRotate = array("sx" => cos($angle), "sy" => cos($angle), "rx" => sin($angle), "ry" => -sin($angle), "tx" => 0, "ty" => 0,);

        //Translate (offset) the drawing
        $affineTranslate = array("sx" => 1, "sy" => 1, "rx" => 0, "ry" => 0, "tx" => 30, "ty" => 30);

        //The identiy affine matrix
        $affineIdentity = array("sx" => 1, "sy" => 1, "rx" => 0, "ry" => 0, "tx" => 0, "ty" => 0);

        $examples = [$affineScale, $affineShear, $affineRotate, $affineTranslate, $affineIdentity,];

        $count = 0;

        foreach ($examples as $example) {
            $draw->push();
            $draw->translate(($count % 2) * 250, intval($count / 2) * 250);
            $draw->translate(100, 100);
            $draw->affine($example);
            $draw->rectangle(-50, -50, 50, 50);
            $draw->pop();
            $count++;
        }

        //Create an image object which the draw commands can be rendered into
        $image = new \Imagick();
        $image->newImage(500, 750, $backgroundColor);
        $image->setImageFormat("png");

        //Render the draw commands in the ImagickDraw object
        //into the image.
        $image->drawImage($draw);

        //Send the image to the browser
        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::annotation

(PECL imagick 2, PECL imagick 3)

ImagickDraw::annotation — Dibuja un texto sobre una imagen

### Descripción

public function ImagickDraw::annotation(float `$x`, float `$y`, string `$text`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja un texto sobre una imagen.

### Parámetros

`x`

  La abscisa del texto a dibujar.

`y`

  La ordenada del texto a dibujar.

`text`

  El texto a dibujar.

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::arc

(PECL imagick 2, PECL imagick 3)

ImagickDraw::arc — Dibuja un arco

### Descripción

public function ImagickDraw::arc(
float `$start_x`,
float `$start_y`,
float `$end_x`,
float `$end_y`,
float `$start_angle`,
float `$end_angle`
): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja un arco, situado dentro de un rectángulo.

### Parámetros

`start_x`

  Abscisa del punto de inicio del arco en el rectángulo de contorno

`start_y`

  Ordenada del punto de inicio del arco en el rectángulo de contorno

`end_x`

  Abscisa del punto final del arco en el rectángulo de contorno

`end_y`

  Ordenada del punto final del arco en el rectángulo de contorno

`start_angle`

  Grado de rotación inicial

`end_angle`

  Grado de rotación final

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::arc()

    <?php
    function arc($strokeColor, $fillColor, $backgroundColor, $startX, $startY, $endX, $endY, $startAngle, $endAngle) {

        //Create a ImagickDraw object to draw into.
        $draw = new \ImagickDraw();
        $draw->setStrokeWidth(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);

        $draw->arc($startX, $startY, $endX, $endY, $startAngle, $endAngle);

        //Create an image object which the draw commands can be rendered into
        $image = new \Imagick();
        $image->newImage(IMAGE_WIDTH, IMAGE_HEIGHT, $backgroundColor);
        $image->setImageFormat("png");

        //Render the draw commands in the ImagickDraw object
        //into the image.
        $image->drawImage($draw);

        //Send the image to the browser
        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::bezier

(PECL imagick 2, PECL imagick 3)

ImagickDraw::bezier — Dibuja una curva de Bézier

### Descripción

public function ImagickDraw::bezier(array `$coordinates`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja una curva de Bézier a través de un conjunto de puntos en la imagen.

### Parámetros

`coordinates`

  Array multidimensional como array( array( 'x' => 1, 'y' => 2 ), array( 'x' => 3, 'y' => 4 ) )

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo de ImagickDraw::bezier()

    <?php
    function bezier($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $strokeColor = new \ImagickPixel($strokeColor);
        $fillColor = new \ImagickPixel($fillColor);

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);

        $smoothPointsSet = [
            [
                ['x' => 10.0 * 5, 'y' => 10.0 * 5],
                ['x' => 30.0 * 5, 'y' => 90.0 * 5],
                ['x' => 25.0 * 5, 'y' => 10.0 * 5],
                ['x' => 50.0 * 5, 'y' => 50.0 * 5],
            ],
            [
                ['x' => 50.0 * 5, 'y' => 50.0 * 5],
                ['x' => 75.0 * 5, 'y' => 90.0 * 5],
                ['x' => 70.0 * 5, 'y' => 10.0 * 5],
                ['x' => 90.0 * 5, 'y' => 40.0 * 5],
            ],
        ];

        foreach ($smoothPointsSet as $points) {
            $draw->bezier($points);
        }

        $disjointPoints = [
            [
                ['x' => 10 * 5, 'y' => 10 * 5],
                ['x' => 30 * 5, 'y' => 90 * 5],
                ['x' => 25 * 5, 'y' => 10 * 5],
                ['x' => 50 * 5, 'y' => 50 * 5],
            ],
            [
                ['x' => 50 * 5, 'y' => 50 * 5],
                ['x' => 80 * 5, 'y' => 50 * 5],
                ['x' => 70 * 5, 'y' => 10 * 5],
                ['x' => 90 * 5, 'y' => 40 * 5],
             ]
        ];
        $draw->translate(0, 200);

        foreach ($disjointPoints as $points) {
            $draw->bezier($points);
        }

        //Create an image object which the draw commands can be rendered into
        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        //Render the draw commands in the ImagickDraw object
        //into the image.
        $imagick->drawImage($draw);

        //Send the image to the browser
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::circle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::circle — Dibuja un círculo

### Descripción

public function ImagickDraw::circle(
float `$origin_x`,
float `$origin_y`,
float `$perimeter_x`,
float `$perimeter_y`
): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja un círculo.

### Parámetros

`origin_x`

  Abscisa del origen

`origin_y`

  Ordenada del origen

`perimeter_x`

  Abscisa del perímetro

`perimeter_y`

  Ordenada del perímetro

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::circle()

    <?php
    function circle($strokeColor, $fillColor, $backgroundColor, $originX, $originY, $endX, $endY) {

        //Creación de un objeto ImagickDraw.
        $draw = new \ImagickDraw();

        $strokeColor = new \ImagickPixel($strokeColor);
        $fillColor = new \ImagickPixel($fillColor);

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->circle($originX, $originY, $endX, $endY);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::clear

(PECL imagick 2, PECL imagick 3)

ImagickDraw::clear — Borra el objeto ImagickDraw

### Descripción

public function ImagickDraw::clear(): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Borra el objeto ImagickDraw de cualquier comando acumulado, y reinicia la configuración que contiene a sus valores predeterminados.

### Valores devueltos

Devuelve un objeto ImagickDraw.

# ImagickDraw::clone

(PECL imagick 2, PECL imagick 3)

ImagickDraw::clone — Realiza una copia exacta del objeto ImagickDraw

### Descripción

public function ImagickDraw::clone(): ImagickDraw
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Realiza una copia exacta del objeto ImagickDraw.

### Valores devueltos

Devuelve una copia exacta del objeto ImagickDraw.

# ImagickDraw::color

(PECL imagick 2, PECL imagick 3)

ImagickDraw::color — Dibuja un color sobre una imagen

### Descripción

public function ImagickDraw::color(float `$x`, float `$y`, int `$paint`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja un color sobre una imagen, con el color de relleno actual, comenzando en una posición dada, y utilizando el método de coloración indicado.

### Parámetros

`x`

  Abscisa del punto de pintura

`y`

  Ordenada del punto de pintura

`paint`

  Una de las constantes PAINT (`imagick::PAINT_*`).

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::comment

(PECL imagick 2, PECL imagick 3)

ImagickDraw::comment — Añade un comentario

### Descripción

public function ImagickDraw::comment(string `$comment`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Añade un comentario al flujo de salida.

### Parámetros

`comment`

  La cadena de comentario

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::composite

(PECL imagick 2, PECL imagick 3)

ImagickDraw::composite — Componer una imagen con otra

### Descripción

public function ImagickDraw::composite(
int `$composite`,
float `$x`,
float `$y`,
float `$width`,
float `$height`,
Imagick `$image`
): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Componer una imagen con otra, utilizando el operador de composición, en la posición y tamaño indicados.

### Parámetros

`composite`

  El operador de composición. Una de las constantes de operador de composición (`imagick::COMPOSITE_*`).

`x`

  Abscisa del ángulo superior izquierdo.

`y`

  Ordenada del ángulo superior izquierdo.

`width`

  Ancho de la imagen de composición.

`height`

  Alto de la imagen de composición.

`image`

  El objeto Imagick donde se toma la composición.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::composite()

    <?php
    function composite($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setFillOpacity(1);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeWidth(2);
        $draw->setFont("../fonts/CANDY.TTF");
        $draw->setFontSize(140);
        $draw->rectangle(0, 0, 1000, 300);
        $draw->setFillColor('white');
        $draw->setfillopacity(1);
        $draw->annotation(50, 180, "Lorem Ipsum!");

        //Crea un objeto imagen que sirve de base
        $imagick = new \Imagick();
        $imagick->newImage(1000, 302, $backgroundColor);
        $imagick->setImageFormat("png");

        //Se aplican las órdenes de dibujo en el objeto ImagickDraw
        //y en la imagen.
        $imagick->drawImage($draw);

        //Se envía la imagen al navegador
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::__construct

(PECL imagick 2, PECL imagick 3)

ImagickDraw::__construct — El constructor ImagickDraw

### Descripción

public function ImagickDraw::__construct()
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

El constructor de la clase ImagickDraw.

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::destroy

(PECL imagick 2, PECL imagick 3)

ImagickDraw::destroy — Libera todos los recursos asociados

### Descripción

public function ImagickDraw::destroy(): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Libera todos los recursos asociados con el objeto ImagickDraw.

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::ellipse

(PECL imagick 2, PECL imagick 3)

ImagickDraw::ellipse — Dibuja una elipse sobre una imagen

### Descripción

public function ImagickDraw::ellipse(
float `$origin_x`,
float `$origin_y`,
float `$radius_x`,
float `$radius_y`,
float `$angle_start`,
float `$angle_end`
): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja una elipse sobre una imagen.

### Parámetros

`origin_x`

`origin_y`

`radius_x`

`radius_y`

`angle_start`

`angle_end`

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::ellipse()

    <?php
    function ellipse($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->ellipse(125, 70, 100, 50, 0, 360);
        $draw->ellipse(350, 70, 100, 50, 0, 315);

        $draw->push();
        $draw->translate(125, 250);
        $draw->rotate(30);
        $draw->ellipse(0, 0, 100, 50, 0, 360);
        $draw->pop();

        $draw->push();
        $draw->translate(350, 250);
        $draw->rotate(30);
        $draw->ellipse(0, 0, 100, 50, 0, 315);
        $draw->pop();

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::getClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getClipPath — Devuelve el identificador del camino actual

### Descripción

public function ImagickDraw::getClipPath(): false|string
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve el identificador del camino actual.

### Valores devueltos

Devuelve un string, o `false` si no existe ningún camino.

# ImagickDraw::getClipRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getClipRule — Devuelve la regla de relleno de un polígono actual

### Descripción

public function ImagickDraw::getClipRule(): int
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve la regla de relleno de un polígono actual usada por el trazado de recorte.

### Valores devueltos

Devuelve una constante FILLRULE (`imagick::FILLRULE_*`).

# ImagickDraw::getClipUnits

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getClipUnits — Devuelve la interpretación de unidades del trazado de recorte

### Descripción

public function ImagickDraw::getClipUnits(): int
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve la interpretación de unidades del trazado de recorte.

### Valores devueltos

Devuelve un int si se tuvo éxito.

# ImagickDraw::getFillColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillColor — Devuelve el color de relleno

### Descripción

public function ImagickDraw::getFillColor(): ImagickPixel
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve el color de relleno usado cuando se dibujan objetos rellenos.

### Valores devueltos

Devuelve un objeto ImagickPixel.

# ImagickDraw::getFillOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillOpacity — Devuelve la opacidad de dibujo

### Descripción

public function ImagickDraw::getFillOpacity(): float
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve la opacidad de dibujo. 1.0 representa la opacidad total.

### Valores devueltos

La opacidad.

# ImagickDraw::getFillRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillRule — Devuelve la regla de relleno

### Descripción

public function ImagickDraw::getFillRule(): int
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve la regla de relleno usada mientras se dibujan polígonos.

### Valores devueltos

Devuelve una constante FILLRULE (`imagick::FILLRULE_*`).

# ImagickDraw::getFont

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFont — Devuelve la fuente

### Descripción

public function ImagickDraw::getFont(): string
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve un string que especifica la fuente utilizada para las anotaciones.

### Valores devueltos

Devuelve un string en caso de éxito, y `false` en caso contrario.

# ImagickDraw::getFontFamily

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontFamily — Devuelve la familia de fuentes

### Descripción

public function ImagickDraw::getFontFamily(): string
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve la familia de fuentes de las anotaciones.

### Valores devueltos

Devuelve la familia de fuentes de las anotaciones, o `false` si la familia de fuentes no está configurada.

# ImagickDraw::getFontSize

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontSize — Devuelve el tamaño de punto de la fuente

### Descripción

public function ImagickDraw::getFontSize(): float
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve el tamaño de punto de la fuente usado cuando se escribe texto.

### Valores devueltos

Devuelve el tamaño de punto de la fuente asociada al objeto ImagickDraw actual.

# ImagickDraw::getFontStretch

(PECL imagick 2 >=2.3.0, PECL imagick 3)

ImagickDraw::getFontStretch — Devuelve el estiramiento de la fuente a utilizar durante la anotación con texto

### Descripción

public function ImagickDraw::getFontStretch(): int

Devuelve el estiramiento de la fuente a utilizar durante la anotación con texto. Devuelve un StretchType.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# ImagickDraw::getFontStyle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontStyle — Devuelve el estilo de la fuente

### Descripción

public function ImagickDraw::getFontStyle(): int
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve el estilo de la fuente.

### Valores devueltos

Devuelve una constante STYLE (`imagick::STYLE_*`), asociada al objeto ImagickDraw, o 0 si el estilo no está definido.

# ImagickDraw::getFontWeight

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontWeight — Devuelve el peso de la fuente

### Descripción

public function ImagickDraw::getFontWeight(): int
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve el peso de la fuente usada cuando se escribe texto.

### Valores devueltos

Devuelve un int si se tuvo éxito o 0 si no está estabecido ningún peso.

# ImagickDraw::getGravity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getGravity — Devuelve la gravedad de colocación de texto

### Descripción

public function ImagickDraw::getGravity(): int
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve la gravedad de colocación de texto, utilizada durante la anotación.

### Valores devueltos

Devuelve una constante GRAVITY (`imagick::GRAVITY_*`) en caso de éxito, o 0 si la gravedad no está configurada.

# ImagickDraw::getStrokeAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeAntialias — Devuelve la configuración de antialias de contorno actual

### Descripción

public function ImagickDraw::getStrokeAntialias(): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve la configuración antialias de contorno actual. Los perfiles contorneados tienen antialias por defecto. Cuando se deshabilita el antialias, los píxeles contorneados son puestos en el umbral para determinar si se debería usar el color de contorno o el color del lienzo subyacente.

### Valores devueltos

Devuelve `true` si el antialias está on y `false` si está off.

# ImagickDraw::getStrokeColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeColor — Devuelve el color usado por los perfiles de objetos contorneados

### Descripción

public function ImagickDraw::getStrokeColor(): ImagickPixel
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve el color usado por los perfiles de objetos contorneados.

### Parámetros

`stroke_color`

### Valores devueltos

Devuelve un objeto ImagickPixel que describe el color.

# ImagickDraw::getStrokeDashArray

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeDashArray — Devuelve un array que representa el patrón de trazos

### Descripción

public function ImagickDraw::getStrokeDashArray(): array
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve un array que representa el patrón de trazos, los espacios y los trazos.

### Valores devueltos

Devuelve un array en caso de éxito, y un array vacío en caso contrario.

# ImagickDraw::getStrokeDashOffset

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeDashOffset — Devuelve el desplazamiento del punto en el patrón

### Descripción

public function ImagickDraw::getStrokeDashOffset(): float
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve el desplazamiento del punto en el patrón.

### Valores devueltos

Devuelve un número decimal que representa el inicio del punto en el patrón.

# ImagickDraw::getStrokeLineCap

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeLineCap — Devuelve la forma a utilizar para dibujar los extremos de subrutas

### Descripción

public function ImagickDraw::getStrokeLineCap(): int
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve la forma a utilizar para dibujar los extremos de subrutas.

### Valores devueltos

Devuelve una constante LINECAP (`imagick::LINECAP_*`), o 0 si los extremos de líneas no están configurados.

# ImagickDraw::getStrokeLineJoin

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeLineJoin — Devuelve la forma a utilizar para dibujar las esquinas de un camino

### Descripción

public function ImagickDraw::getStrokeLineJoin(): int
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve la forma a utilizar para dibujar las esquinas de un camino (u otras formas vectoriales), cuando son dibujadas.

### Valores devueltos

Devuelve una constante LINEJOIN (`imagick::LINEJOIN_*`), o 0 si las esquinas no están configuradas.

# ImagickDraw::getStrokeMiterLimit

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeMiterLimit — Devuelve el valor de 'miterLimit'

### Descripción

public function ImagickDraw::getStrokeMiterLimit(): int
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve el valor de 'miterLimit'. Cuando dos segmentos se encuentran en ángulo agudo y se ha especificado que las uniones miter para `'lineJoin'`, es posible que el miter exceda el grosor del trazo del camino. La 'miterLimit' establece un límite al ratio entre la longitud del miter y `'lineWidth'`.

### Valores devueltos

Devuelve un entero que describe el valor de 'miterLimit', y 0 si la 'miterLimit' no está configurada.

# ImagickDraw::getStrokeOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeOpacity — Devuelve la opacidad de los contornos de un objeto

### Descripción

public function ImagickDraw::getStrokeOpacity(): float
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve la opacidad de los contornos de un objeto.

### Valores devueltos

Devuelve un float que describe la opacidad de los contornos de un objeto.

# ImagickDraw::getStrokeWidth

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeWidth — Devuelve el ancho de trazo utilizado

### Descripción

public function ImagickDraw::getStrokeWidth(): float
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve el ancho de trazo utilizado.

### Valores devueltos

Devuelve un float que describe el ancho de trazo.

# ImagickDraw::getTextAlignment

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextAlignment — Devuelve la alineación del texto

### Descripción

public function ImagickDraw::getTextAlignment(): int
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve la alineación del texto.

### Valores devueltos

Devuelve una constante ALIGN (`imagick::ALIGN_*`), o 0 si la alineación no está configurada.

# ImagickDraw::getTextAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextAntialias — Devuelve la configuración de antialias del texto actual

### Descripción

public function ImagickDraw::getTextAntialias(): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve la configuración de antialias del texto actual, que determina si el texto tiene antialias o no. El texto tiene antialias por defecto.

### Valores devueltos

Devuelve `true` si el texto tiene antialias y `false` si no.

# ImagickDraw::getTextDecoration

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextDecoration — Devuelve la decoración del texto

### Descripción

public function ImagickDraw::getTextDecoration(): int
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve la decoración del texto de anotación.

### Valores devueltos

Devuelve una constante DECORATION (`imagick::DECORATION_*`), o bien 0 si no se ha configurado ninguna decoración.

# ImagickDraw::getTextEncoding

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextEncoding — Devuelve el juego de caracteres utilizado para las anotaciones de texto

### Descripción

public function ImagickDraw::getTextEncoding(): false|string
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve el juego de caracteres utilizado para las anotaciones de texto.

### Valores devueltos

Devuelve una cadena que especifica el juego de caracteres, o bien `false` si el juego de caracteres no está configurado.

# ImagickDraw::getTextInterlineSpacing

(PECL imagick 3 >= 3.1.0)

ImagickDraw::getTextInterlineSpacing — Obtiene el espacio entre líneas de un texto.

### Descripción

public function ImagickDraw::getTextInterlineSpacing(): float

Obtiene el espacio entre líneas de un texto.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# ImagickDraw::getTextInterwordSpacing

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.1.0)

ImagickDraw::getTextInterwordSpacing — Obtiene el espacio entre palabras de un texto.

### Descripción

public function ImagickDraw::getTextInterwordSpacing(): float

Obtiene el espacio entre palabras de un texto.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# ImagickDraw::getTextKerning

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.1.0)

ImagickDraw::getTextKerning — Obtiene el interletraje de un texto.

### Descripción

public function ImagickDraw::getTextKerning(): float

Obtiene el interletraje de un texto.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# ImagickDraw::getTextUnderColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextUnderColor — Devuelve el color debajo del texto

### Descripción

public function ImagickDraw::getTextUnderColor(): ImagickPixel
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve el color de un rectángulo de fondo para colocar bajo anotaciones de texto.

### Valores devueltos

Devuelve un objeto ImagickPixel que describe el color.

# ImagickDraw::getVectorGraphics

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getVectorGraphics — Devuelve una cadena que contiene gráficos vectoriales

### Descripción

public function ImagickDraw::getVectorGraphics(): string
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve un string que especifica los gráficos vectoriales generados por cualquier llamada a gráficos hecha desde que el objeto ImagickDraw fue instanciado.

### Valores devueltos

Devuelve un string que contiene los gráficos vectoriales.

# ImagickDraw::line

(PECL imagick 2, PECL imagick 3)

ImagickDraw::line — Dibuja una línea

### Descripción

public function ImagickDraw::line(
float `$start_x`,
float `$start_y`,
float `$end_x`,
float `$end_y`
): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja una línea utilizando el color de trazo actual, su opacidad y su grosor.

### Parámetros

`start_x`

  La coordenada X de inicio

`start_y`

  La coordenada Y de inicio

`end_x`

  La coordenada X de fin

`end_y`

  La coordenada Y de fin

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::line()

    <?php
    function line($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->line(125, 70, 100, 50);
        $draw->line(350, 170, 100, 150);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::matte

(PECL imagick 2, PECL imagick 3)

ImagickDraw::matte — Dibuja sobre el canal de opacidad de la imagen

### Descripción

public function ImagickDraw::matte(float `$x`, float `$y`, int `$paint`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja sobre el canal de opacidad de la imagen, con el fin de hacer transparentes los píxeles indicados.

### Parámetros

`x`

  Abscisa del mate

`y`

  Ordenada del mate

`paint`

  Una de las constantes PAINT (`imagick::PAINT_*`).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::matte()

    <?php
    function matte($strokeColor, $fillColor, $backgroundColor, $paintType) {
        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->matte(120, 120, $paintType);
        $draw->rectangle(100, 100, 300, 200);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::pathClose

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathClose — Añade un elemento de camino al camino actual

### Descripción

public function ImagickDraw::pathClose(): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Añade un elemento de camino al camino actual, que cerrará el subcamino dibujando una línea recta desde el punto actual hasta el punto de inicio más reciente (generalmente, el último punto de desplazamiento).

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::pathCurveToAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToAbsolute — Dibuja una curva de Bézier cúbica, en coordenadas absolutas

### Descripción

public function ImagickDraw::pathCurveToAbsolute(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja una curva de Bézier cúbica, a partir del punto actual (`x`,`y`) utilizando el punto (`x1`,`y1`) como punto de control al inicio de la curva y (`x2`,`y2`) como punto de control al final de la curva, utilizando coordenadas absolutas. Al final de la orden, el nuevo punto actual es el punto final (`x`,`y`), utilizado por el polybezier.

### Parámetros

`x1`

  Abscisa del primer punto de control

`y1`

  Ordenada del primer punto de control

`x2`

  Abscisa del segundo punto de control

`y2`

  Ordenada del segundo punto de control

`x`

  Abscisa del final de la curva

`y`

  Ordenada del final de la curva

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::pathCurveToQuadraticBezierAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierAbsolute — Dibuja una curva de Bézier cuadrática, en coordenadas absolutas

### Descripción

public function ImagickDraw::pathCurveToQuadraticBezierAbsolute(
float `$x1`,
float `$y1`,
float `$x_end`,
float `$y`
): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja una curva de Bézier cuadrática, en coordenadas relativas, con respecto al punto actual (`x`,`y`), utilizando el punto (`x1`,`y1`) como punto de control. Al finalizar el dibujo, el nuevo punto actual se convierte en el punto final (`x`,`y`) utilizado por el polybezier.

### Parámetros

`x1`

  Abscisa del punto de control

`y1`

  Ordenada del punto de control

`x_end`

  Abscisa del punto final

`y`

  Ordenada del punto final

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::pathCurveToQuadraticBezierAbsolute()

    <?php
    function pathCurveToQuadraticBezierAbsolute($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->pathStart();
        $draw->pathMoveToAbsolute(50,250);

        // This specifies a quadratic bezier curve with the current position as the start
        // point, the control point is the first two params, and the end point is the last two params.
        $draw->pathCurveToQuadraticBezierAbsolute(
            150,50,
            250,250
        );

        // This specifies a quadratic bezier curve with the current position as the start
        // point, the control point is mirrored from the previous curves control point
        // and the end point is defined by the x, y values.
        $draw->pathCurveToQuadraticBezierSmoothAbsolute(
            450,250
        );

        // This specifies a quadratic bezier curve with the current position as the start
        // point, the control point is mirrored from the previous curves control point
        // and the end point is defined relative from the current position by the x, y values.
        $draw->pathCurveToQuadraticBezierSmoothRelative(
            200,-100
        );

        $draw->pathFinish();

        $imagick = new \Imagick();
        $imagick->newImage(700, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();

    }

    ?>

# ImagickDraw::pathCurveToQuadraticBezierRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierRelative — Dibuja una curva de Bézier cuadrática, en coordenadas relativas

### Descripción

public function ImagickDraw::pathCurveToQuadraticBezierRelative(
float `$x1`,
float `$y1`,
float `$x_end`,
float `$y`
): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja una curva de Bézier cuadrática, en coordenadas relativas, respecto al punto actual (`x`,`y`), utilizando el punto (`x1`,`y1`) como punto de control. Al finalizar el dibujo, el nuevo punto actual se convierte en el punto final (`x`,`y`) utilizado por el polybezier.

### Parámetros

`x1`

  coordenada x de inicio

`y1`

  coordenada y de inicio

`x_end`

  coordenada x de fin

`y`

  coordenada y de fin

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute — Dibuja una curva Bézier cuadrática

### Descripción

public function ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute(float `$x`, float `$y`): bool

Dibuja una curva Bézier cuadrática (usando coordenadas absolutas) desde el punto actual a (x, y). Se asume que el punto de control es la refelxión del punto de control del comando previo relativo al punto actual. (Si no hay comando previo o el comando previo no es DrawPathCurveToQuadraticBezierAbsolute, DrawPathCurveToQuadraticBezierRelative, DrawPathCurveToQuadraticBezierSmoothAbsolute DrawPathCurveToQuadraticBezierSmoothRelative, se asume que el punto de control coincide con el punto actual). Al final del comando, el nuevo punto actual se convierte en el par de coordenadas final (x, y) usado en el Bezígono.

Esta función no se puede utilizar para continuar de forma suave una curva Bézier cúbica. Solamente puede continuarse suavemente desde una curva cuadrática.

### Parámetros

`x`

  coordenada x final

`y`

  coordenada y final

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo de ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute()

    <?php
    $draw = new \ImagickDraw();

    $draw->setStrokeOpacity(1);
    $draw->setStrokeColor("black");
    $draw->setFillColor("blue");

    $draw->setStrokeWidth(2);
    $draw->setFontSize(72);

    $draw->pathStart();
    $draw->pathMoveToAbsolute(50,250);

    // This specifies a quadratic bezier curve with the current position as the start
    // point, the control point is the first two params, and the end point is the last two params.
    $draw->pathCurveToQuadraticBezierAbsolute(
        150,50,
        250,250
    );

    // This specifies a quadratic bezier curve with the current position as the start
    // point, the control point is mirrored from the previous curves control point
    // and the end point is defined by the x, y values.
    $draw->pathCurveToQuadraticBezierSmoothAbsolute(
        450,250
    );

    // This specifies a quadratic bezier curve with the current position as the start
    // point, the control point is mirrored from the previous curves control point
    // and the end point is defined relative from the current position by the x, y values.
    $draw->pathCurveToQuadraticBezierSmoothRelative(
        200,-100
    );

    $draw->pathFinish();

    $imagick = new \Imagick();
    $imagick->newImage(700, 500, $backgroundColor);
    $imagick->setImageFormat("png");

    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
    ?>

# ImagickDraw::pathCurveToQuadraticBezierSmoothRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierSmoothRelative — Dibuja una curva Bézier cuadrática

### Descripción

public function ImagickDraw::pathCurveToQuadraticBezierSmoothRelative(float `$x`, float `$y`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja una curva Bézier cuadrática (usando coordenadas relativas) desde el punto actual a (x, y). Se asume que el punto de control es la refelxión del punto de control del comando previo relativo al punto actual. (Si no hay comando previo o el comando previo no es DrawPathCurveToQuadraticBezierAbsolute, DrawPathCurveToQuadraticBezierRelative, DrawPathCurveToQuadraticBezierSmoothAbsolute DrawPathCurveToQuadraticBezierSmoothRelative, se asume que el punto de control coincide con el punto actual). Al final del comando, el nuevo punto actual se convierte en el par de coordenadas final (x, y) usado en el Bezígono.

Esta función no se puede utilizar para continuar de forma suave una curva Bézier cúbica. Solamente puede continuarse suavemente desde una curva cuadrática.

### Parámetros

`x`

  coordenada x final

`y`

  coordenada y final

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo de ImagickDraw::pathCurveToQuadraticBezierSmoothRelative()

    <?php
    $draw = new \ImagickDraw();

    $draw->setStrokeOpacity(1);
    $draw->setStrokeColor("black");
    $draw->setFillColor("blue");

    $draw->setStrokeWidth(2);
    $draw->setFontSize(72);

    $draw->pathStart();
    $draw->pathMoveToAbsolute(50,250);

    // This specifies a quadratic bezier curve with the current position as the start
    // point, the control point is the first two params, and the end point is the last two params.
    $draw->pathCurveToQuadraticBezierAbsolute(
        150,50,
        250,250
    );

    // This specifies a quadratic bezier curve with the current position as the start
    // point, the control point is mirrored from the previous curves control point
    // and the end point is defined by the x, y values.
    $draw->pathCurveToQuadraticBezierSmoothAbsolute(
        450,250
    );

    // This specifies a quadratic bezier curve with the current position as the start
    // point, the control point is mirrored from the previous curves control point
    // and the end point is defined relative from the current position by the x, y values.
    $draw->pathCurveToQuadraticBezierSmoothRelative(
        200,-100
    );

    $draw->pathFinish();

    $imagick = new \Imagick();
    $imagick->newImage(700, 500, $backgroundColor);
    $imagick->setImageFormat("png");

    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
    ?>

# ImagickDraw::pathCurveToRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToRelative — Dibuja una curva de Bézier cúbica, en coordenadas relativas

### Descripción

public function ImagickDraw::pathCurveToRelative(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja una curva de Bézier cúbica, a partir del punto actual (`x`,`y`) utilizando el punto (`x1`,`y1`) como punto de control al inicio de la curva y (`x2`,`y2`) como punto de control al final de la curva, utilizando coordenadas relativas. Al finalizar la orden, el nuevo punto actual es el punto final (`x`,`y`), utilizado por el polybezier.

### Parámetros

`x1`

  Abscisa del punto de inicio

`y1`

  Ordenada del punto de inicio

`x2`

  Abscisa del punto de control final

`y2`

  Ordenada del punto de control final

`x`

  Abscisa del punto final

`y`

  Ordenada del punto final

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::pathCurveToSmoothAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToSmoothAbsolute — Dibuja una curva de Bézier, en coordenadas absolutas

### Descripción

public function ImagickDraw::pathCurveToSmoothAbsolute(
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja una curva de Bézier, en coordenadas absolutas, a partir del punto actual (`x`,`y`). El primer punto de control es la reflexión del segundo punto de control del comando anterior, relativo al punto actual. Si no ha habido un comando anterior, o si el comando anterior no era DrawPathCurveToAbsolute, DrawPathCurveToRelative, DrawPathCurveToSmoothAbsolute o DrawPathCurveToSmoothRelative, se asume entonces que el primer punto de control coincide con el punto actual. (`x2`,`y2`) es el segundo punto de control (es decir, el punto de control al final de la línea. Al final del comando, el nuevo punto actual es el punto final, de coordenadas (`x`,`y`), en el polybezier.

### Parámetros

`x2`

  abscisa del segundo punto de control

`y2`

  ordenada del segundo punto de control

`x`

  abscisa del punto de control final

`y`

  ordenada del punto de control final

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::pathCurveToSmoothRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToSmoothRelative — Dibuja una curva de Bézier, en coordenadas relativas

### Descripción

public function ImagickDraw::pathCurveToSmoothRelative(
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja una curva de Bézier, en coordenadas relativas, a partir del punto actual (`x`,`y`). El primer punto de control es la reflexión del segundo punto de control del comando anterior, relativo al punto actual. Si no ha habido un comando anterior, o si el comando anterior no era DrawPathCurveToAbsolute, DrawPathCurveToRelative, DrawPathCurveToSmoothAbsolute o DrawPathCurveToSmoothRelative, se asume entonces que el primer punto de control coincide con el punto actual. (`x2`,`y2`) es el segundo punto de control (i.e., el punto de control al final de la línea. Al final del comando, el nuevo punto actual es el punto final, de coordenadas (`x`,`y`), en el polybezier.

### Parámetros

`x2`

  Abscisa del segundo punto de control

`y2`

  Ordenada del segundo punto de control

`x`

  Abscisa del punto de control final

`y`

  Ordenada del punto de control final

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::pathEllipticArcAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathEllipticArcAbsolute — Dibuja un arco de elipse, en coordenadas absolutas

### Descripción

public function ImagickDraw::pathEllipticArcAbsolute(
float `$rx`,
float `$ry`,
float `$x_axis_rotation`,
bool `$large_arc`,
bool `$sweep`,
float `$x`,
float `$y`
): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja un arco de elipse a partir del punto actual (`x`, `y`), utilizando coordenadas relativas. El tamaño y la orientación de la elipse se definen mediante dos radios, (`rx`, `ry`) y una rotación xAxisRotation, que indica cómo la elipse, en su conjunto, está situada en el sistema de coordenadas. El centro (`cx`, `cy`) de la elipse se calcula automáticamente para satisfacer las restricciones de los demás parámetros. Si `large_arc` es `true`, entonces se dibuja el arco más grande. Si `sweep` es `true`, entonces el dibujo del arco se realiza en sentido horario.

### Parámetros

`rx`

  Radio X

`ry`

  Radio Y

`x_axis_rotation`

  Rotación sobre el eje X

`large_arc`

  Opción de `large_arc_flag`

`sweep`

  Opción `sweep_flag`

`x`

  La abscisa

`y`

  La ordenada

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::pathEllipticArcRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathEllipticArcRelative — Dibuja un arco de elipse, en coordenadas relativas

### Descripción

public function ImagickDraw::pathEllipticArcRelative(
float `$rx`,
float `$ry`,
float `$x_axis_rotation`,
bool `$large_arc`,
bool `$sweep`,
float `$x`,
float `$y`
): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja un arco de elipse a partir del punto actual (`x`, `y`), utilizando coordenadas relativas. El tamaño y la orientación de la elipse se definen mediante dos radios, (`rx`, `ry`) y una rotación xAxisRotation, que indica cómo la elipse, en su conjunto, está situada en el sistema de coordenadas. El centro (`cx`, `cy`) de la elipse se calcula automáticamente para satisfacer las restricciones de los demás parámetros. Si `large_arc` es `true`, entonces se dibuja el arco más grande. Si `sweep` es `true`, entonces el dibujo del arco se realiza en sentido horario.

### Parámetros

`rx`

  Radio X

`ry`

  Radio Y

`x_axis_rotation`

  Rotación sobre el eje X

`large_arc`

  La opción de `large_arc_flag`

`sweep`

  La opción de `sweep_flag`

`x`

  La abscisa

`y`

  La ordenada

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::pathFinish

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathFinish — Finaliza el camino actual

### Descripción

public function ImagickDraw::pathFinish(): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Finaliza el camino actual.

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::pathLineToAbsolute

(PECL imagick 2)

ImagickDraw::pathLineToAbsolute — Dibuja una línea de camino, en coordenadas absolutas

### Descripción

public function ImagickDraw::pathLineToAbsolute(float `$x`, float `$y`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja una línea desde el punto actual hasta el punto objetivo, utilizando coordenadas absolutas. El punto objetivo se convierte entonces en el punto actual.

### Parámetros

`x`

  La abscisa de inicio

`y`

  La abscisa de fin

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::pathLineToHorizontalAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToHorizontalAbsolute — Dibuja una línea de camino horizontal, en coordenadas absolutas

### Descripción

public function ImagickDraw::pathLineToHorizontalAbsolute(float `$x`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja una línea vertical desde el punto actual hasta el punto objetivo, utilizando coordenadas relativas. El punto objetivo se convierte entonces en el punto actual.

### Parámetros

`x`

  La abscisa

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::pathLineToHorizontalRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToHorizontalRelative — Dibuja una línea de camino horizontal, en coordenadas relativas

### Descripción

public function ImagickDraw::pathLineToHorizontalRelative(float `$x`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja una línea horizontal desde el punto actual hasta el punto objetivo, utilizando coordenadas relativas. El punto objetivo se convierte entonces en el punto actual.

### Parámetros

`x`

  La abscisa

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::pathLineToRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToRelative — Dibuja una línea de camino, en coordenadas relativas

### Descripción

public function ImagickDraw::pathLineToRelative(float `$x`, float `$y`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja una línea a partir del punto actual, hasta el punto objetivo, utilizando coordenadas relativas. El punto objetivo se convierte entonces en el punto actual.

### Parámetros

`x`

  abscisa de inicio

`y`

  ordenada de inicio

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::pathLineToVerticalAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToVerticalAbsolute — Dibuja una línea de camino vertical, en coordenadas absolutas

### Descripción

public function ImagickDraw::pathLineToVerticalAbsolute(float `$y`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja una línea vertical desde el punto actual hasta el punto objetivo, utilizando coordenadas absolutas. El punto objetivo se convierte entonces en el punto actual.

### Parámetros

`y`

  Ordenada

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::pathLineToVerticalRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToVerticalRelative — Dibuja una línea de camino vertical, en coordenadas relativas

### Descripción

public function ImagickDraw::pathLineToVerticalRelative(float `$y`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja una línea vertical desde el punto actual hasta el punto objetivo, utilizando coordenadas relativas. El punto objetivo se convierte entonces en el punto actual.

### Parámetros

`y`

  ordenada objetivo

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::pathMoveToAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathMoveToAbsolute — Inicia un nuevo subcamino, en coordenadas absolutas

### Descripción

public function ImagickDraw::pathMoveToAbsolute(float `$x`, float `$y`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Inicia un nuevo subcamino a partir de las coordenadas indicadas, utilizando coordenadas absolutas. El punto actual se convierte entonces en las coordenadas especificadas.

### Parámetros

`x`

  La abscisa objetivo

`y`

  La ordenada objetivo

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::pathMoveToRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathMoveToRelative — Inicia un nuevo subcamino, en coordenadas relativas

### Descripción

public function ImagickDraw::pathMoveToRelative(float `$x`, float `$y`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Inicia un nuevo subcamino a partir de las coordenadas indicadas, utilizando coordenadas relativas. El punto actual se convierte entonces en las coordenadas especificadas.

### Parámetros

`x`

  La abscisa objetivo

`y`

  La ordenada objetivo

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::pathStart

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathStart — Declara el inicio de una lista de dibujo de trazados

### Descripción

public function ImagickDraw::pathStart(): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Declara el inicio de una lista de dibujo de trazados que finaliza con un comando DrawPathFinish() coincidente. Todos los demás comandos DrawPath deben estar encerrados entre comandos DrawPathFinish(). Ésto es debido a que los comandos de dibujo de trazados son comandos subordinados y no funcionan por sí mismos.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo de ImagickDraw::pathStart()

    <?php
    function pathStart($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->pathStart();
        $draw->pathMoveToAbsolute(50, 50);
        $draw->pathLineToAbsolute(100, 50);
        $draw->pathLineToRelative(0, 50);
        $draw->pathLineToHorizontalRelative(-50);
        $draw->pathFinish();

        $draw->pathStart();
        $draw->pathMoveToAbsolute(50, 50);
        $draw->pathMoveToRelative(300, 0);
        $draw->pathLineToRelative(50, 0);
        $draw->pathLineToVerticalRelative(50);
        $draw->pathLineToHorizontalAbsolute(350);
        $draw->pathclose();
        $draw->pathFinish();

        $draw->pathStart();
        $draw->pathMoveToAbsolute(50, 300);
        $draw->pathCurveToAbsolute(50, 300, 100, 200, 300, 300);
        $draw->pathLineToVerticalAbsolute(350);
        $draw->pathFinish();

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::point

(PECL imagick 2, PECL imagick 3)

ImagickDraw::point — Dibuja un punto

### Descripción

public function ImagickDraw::point(float `$x`, float `$y`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja un punto usando el color del contorno y el grosor del contorno en las coordenadas especificadas.

### Parámetros

`x`

  coordenada x del punto

`y`

  coordenada y del punto

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo de ImagickDraw::point()

    <?php
    function point($fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setFillColor($fillColor);

        for ($x = 0; $x < 10000; $x++) {
            $draw->point(rand(0, 500), rand(0, 500));
        }

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::polygon

(PECL imagick 2, PECL imagick 3)

ImagickDraw::polygon — Dibuja un polígono

### Descripción

public function ImagickDraw::polygon(array `$coordinates`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja un polígono usando el contorno, el ancho del contorno, y el color de relleno o de la textura actuales, usando el array de coordenadas especificado.

### Parámetros

`coordinates`

  array multidimensional como array( array( 'x' => 3, 'y' => 4 ), array( 'x' => 2, 'y' => 6 ) );

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo de ImagickDraw::polygon()

    <?php
    function polygon($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeWidth(4);

        $draw->setFillColor($fillColor);

        $points = [
            ['x' => 40 * 5, 'y' => 10 * 5],
            ['x' => 20 * 5, 'y' => 20 * 5],
            ['x' => 70 * 5, 'y' => 50 * 5],
            ['x' => 60 * 5, 'y' => 15 * 5],
        ];

        $draw->polygon($points);

        $image = new \Imagick();
        $image->newImage(500, 300, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::polyline

(PECL imagick 2, PECL imagick 3)

ImagickDraw::polyline — Dibuja una poli-línea

### Descripción

public function ImagickDraw::polyline(array `$coordinates`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja una poli-línea usando el contorno, el ancho del contorno, y el color de relleno o de la textura actuales, usando el array de coordenadas especificado.

### Parámetros

`coordinates`

  array de coordenadas x e y: array( array( 'x' => 4, 'y' => 6 ), array( 'x' => 8, 'y' => 10 ) )

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo de ImagickDraw::polyline()

    <?php
    function polyline($strokeColor, $fillColor, $backgroundColor) {
        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(5);

        $points = [
            ['x' => 40 * 5, 'y' => 10 * 5],
            ['x' => 20 * 5, 'y' => 20 * 5],
            ['x' => 70 * 5, 'y' => 50 * 5],
            ['x' => 60 * 5, 'y' => 15 * 5]
        ];

        $draw->polyline($points);

        $image = new \Imagick();
        $image->newImage(500, 300, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::pop

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pop — Destruye el objeto ImagickDraw actual de la pila, y lo devuelve al objeto ImagickDraw previamente metido

### Descripción

public function ImagickDraw::pop(): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Destruye el objeto ImagickDraw actual de la pila, y lo devuelve al objeto ImagickDraw previamente metido. Pueden existir mútiples objetos ImagickDraw. Es un error intentar sacar más objetos ImagickDraw de los que se han metido, y es una forma apropiada sacar todos los objetos ImagickDraw que han sido metidos.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# ImagickDraw::popClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::popClipPath — Finaliza la definición de un camino

### Descripción

public function ImagickDraw::popClipPath(): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Finaliza la definición de un camino.

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::popDefs

(PECL imagick 2, PECL imagick 3)

ImagickDraw::popDefs — Finaliza una lista de definiciones

### Descripción

public function ImagickDraw::popDefs(): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Finaliza una lista de definiciones.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo de ImagickDraw::popDefs()

    <?php
    function popDefs($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setstrokeOpacity(1);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);
        $draw->pushDefs();
        $draw->setStrokeColor('white');
        $draw->rectangle(50, 50, 200, 200);
        $draw->popDefs();

        $draw->rectangle(300, 50, 450, 200);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::popPattern

(PECL imagick 2, PECL imagick 3)

ImagickDraw::popPattern — Finaliza una definición de patrón

### Descripción

public function ImagickDraw::popPattern(): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Finaliza una definición de patrón.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# ImagickDraw::push

(PECL imagick 2, PECL imagick 3)

ImagickDraw::push — Clona el objeto ImagickDraw actual y lo mete en la pila

### Descripción

public function ImagickDraw::push(): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Clona el objeto ImagickDraw actual para crear un nuevo objeto ImagickDraw, que es añadido a la pila de ImagickDraw. Los objetos de dibujo ImagickDraw originales pueden ser devueltos invocando a ImagickDraw::pop(). Los objetos ImagickDraw son almacenados en una pila ImagickDraw. Por cada Pop debe haber habido un Push equivalente.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de ImagickDraw::push()

    <?php
    function push($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillModifiedColor);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);
        $draw->push();
        $draw->translate(50, 50);
        $draw->rectangle(200, 200, 300, 300);
        $draw->pop();
        $draw->setFillColor($fillColor);
        $draw->rectangle(200, 200, 300, 300);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::pushClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pushClipPath — Inicia la definición de un trazado de recorte

### Descripción

public function ImagickDraw::pushClipPath(string `$clip_mask_id`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Inicia la definición de un trazado de recorte el cuál está compuesto por cualquier número de comandos de dibujo y finalizado por un comando ImagickDraw::popClipPath().

### Parámetros

`clip_mask_id`

  Id de la máscara de recorte

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::pushDefs

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pushDefs — Indica que los siguientes comandos crean elementos con nombre para un procesamiento previo

### Descripción

public function ImagickDraw::pushDefs(): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Indica que los comandos hasta un comando ImagickDraw::popDefs() finalizador crean elementos nominados (p.ej. trazados de recorte, texturas, etc.) los cuales pueden ser procesados previamente de forma segura para la eficiencia.

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::pushPattern

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pushPattern — Indica que los comandos subsiguientes hasta un comando ImagickDraw::opPattern() comprenden la definición de un patrón nominado

### Descripción

public function ImagickDraw::pushPattern(
string `$pattern_id`,
float `$x`,
float `$y`,
float `$width`,
float `$height`
): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Indica que los comandos subsiguientes hasta un comando DrawPopPattern() comprenden la definición de un patrón nominado. Al espacio del patrón se le asigna las coordenadas de la esquina superior izquierda, un ancho y alto, y se convierte en su propio espacio de dibujo. Cualquier cosa que se pueda dibujar se puede usar en una definición de patrón. Los patrones nominados se pueden usar como definiciones de contorno o pincel.

### Parámetros

`pattern_id`

  el id del patrón

`x`

  coordenada x de la esquina superior izquierda

`y`

  coordenada y de la esquina superior izquierda

`width`

  ancho del patrón

`height`

  alto del patrón

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de ImagickDraw::pushPattern()

    <?php
    function pushPattern($strokeColor, $fillColor, $backgroundColor) {
        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(1);

        $draw->pushPattern("MyFirstPattern", 0, 0, 50, 50);
        for ($x = 0; $x < 50; $x += 10) {
            for ($y = 0; $y < 50; $y += 5) {
                $positionX = $x + (($y / 5) % 5);
                $draw->rectangle($positionX, $y, $positionX + 5, $y + 5);
            }
        }
        $draw->popPattern();

        $draw->setFillOpacity(0);
        $draw->rectangle(100, 100, 400, 400);
        $draw->setFillOpacity(1);

        $draw->setFillOpacity(1);

        $draw->push();
        $draw->setFillPatternURL('#MyFirstPattern');
        $draw->setFillColor('yellow');
        $draw->rectangle(100, 100, 400, 400);
        $draw->pop();

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::rectangle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::rectangle — Dibuja un rectángulo

### Descripción

public function ImagickDraw::rectangle(
float `$top_left_x`,
float `$top_left_y`,
float `$bottom_right_x`,
float `$bottom_right_y`
): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja un rectángulo a partir de sus coordenadas y utilizando el trazo actual, su ancho y su patrón.

### Parámetros

`top_left_x`

`top_left_y`

  ordenada del ángulo superior izquierdo

`bottom_right_x`

  abscisa del ángulo inferior derecho

`bottom_right_y`

  ordenada del ángulo inferior derecho

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::rectangle()

    <?php
    function rectangle($strokeColor, $fillColor, $backgroundColor) {
        $draw = new \ImagickDraw();
        $strokeColor = new \ImagickPixel($strokeColor);
        $fillColor = new \ImagickPixel($fillColor);

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);

        $draw->rectangle(200, 200, 300, 300);
        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::render

(PECL imagick 2, PECL imagick 3)

ImagickDraw::render — Realiza el renderizado de todos los dibujos en la imagen

### Descripción

public function ImagickDraw::render(): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Realiza el renderizado de todos los dibujos en la imagen.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# ImagickDraw::resetVectorGraphics

(PECL imagick 2, PECL imagick 3)

ImagickDraw::resetVectorGraphics — Restablece los gráficos vectoriales

### Descripción

public function ImagickDraw::resetVectorGraphics(): bool

Restablece los gráficos vectoriales.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve `true` en caso de éxito.

# ImagickDraw::rotate

(PECL imagick 2, PECL imagick 3)

ImagickDraw::rotate — Aplica la rotación especificada al espacio de coordenadas actual

### Descripción

public function ImagickDraw::rotate(float `$degrees`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Aplica la rotación especificada al espacio de coordenadas actual.

### Parámetros

`degrees`

  grados a rotar.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo de ImagickDraw::rotate()

    <?php
    function rotate($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor) {
        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeOpacity(1);
        $draw->setFillColor($fillColor);
        $draw->rectangle(200, 200, 300, 300);
        $draw->setFillColor($fillModifiedColor);
        $draw->rotate(15);
        $draw->rectangle(200, 200, 300, 300);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::roundRectangle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::roundRectangle — Dibuja un rectángulo con esquinas redondeadas

### Descripción

public function ImagickDraw::roundRectangle(
float `$top_left_x`,
float `$top_left_y`,
float `$bottom_right_x`,
float `$bottom_right_y`,
float `$rounding_x`,
float `$rounding_y`
): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Dibuja un rectángulo con esquinas redondeadas, a partir de dos coordenadas, x & y, el radio de esquina y utilizando el trazo actual, su grosor y su color de relleno.

### Parámetros

`top_left_x`

  La abscisa de la esquina superior izquierda

`top_left_y`

  La ordenada de la esquina superior izquierda

`bottom_right_x`

  La abscisa de la esquina inferior derecha

`bottom_right_y`

  La ordenada de la esquina inferior derecha

`rounding_x`

  El radio en x

`rounding_y`

  El radio en y

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::roundRectangle()

    <?php
    function roundRectangle($strokeColor, $fillColor, $backgroundColor, $startX, $startY, $endX, $endY, $roundX, $roundY) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);

        $draw->roundRectangle($startX, $startY, $endX, $endY, $roundX, $roundY);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::scale

(PECL imagick 2, PECL imagick 3)

ImagickDraw::scale — Ajusta el factor de escala

### Descripción

public function ImagickDraw::scale(float `$x`, float `$y`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Ajusta el factor de escala a aplicar en las direcciones horizontal y vertical al espacio de coordenadas actual.

### Parámetros

`x`

  factor horizontal

`y`

  factor vertical

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo de ImagickDraw::scale()

    <?php
    function scale($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeWidth(4);
        $draw->setFillColor($fillColor);
        $draw->rectangle(200, 200, 300, 300);
        $draw->setFillColor($fillModifiedColor);
        $draw->scale(1.4, 1.4);
        $draw->rectangle(200, 200, 300, 300);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setClipPath — Asocia un trazado de recorte nominado con la imagen

### Descripción

public function ImagickDraw::setClipPath(string `$clip_mask`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Asocia un trazado de recorte nominado con la imagen. Sólo las áreas dibujadas por el trazado de recorte serán modificadas mientras permanezca el efecto.

### Parámetros

`clip_mask`

  el nombre del trazado de recorte

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo de ImagickDraw::setClipPath()

    <?php
    function setClipPath($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);

        $clipPathName = 'testClipPath';

        $draw->pushClipPath($clipPathName);
        $draw->rectangle(0, 0, 250, 250);
        $draw->popClipPath();
        $draw->setClipPath($clipPathName);
        $draw->rectangle(100, 100, 400, 400);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setClipRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setClipRule — Configura la regla de relleno del polígono a utilizar con los caminos

### Descripción

public function ImagickDraw::setClipRule(int `$fillrule`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Configura la regla de relleno del polígono a utilizar con los caminos.

### Parámetros

`fillrule`

  Una de las constantes FILLRULE (`imagick::FILLRULE_*`).

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setClipRule()

    <?php
    function setClipRule($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);
        //\Imagick::FILLRULE_EVENODD
        //\Imagick::FILLRULE_NONZERO

        $clipPathName = 'testClipPath';
        $draw->pushClipPath($clipPathName);
        $draw->setClipRule(\Imagick::FILLRULE_EVENODD);
        $draw->rectangle(0, 0, 300, 500);
        $draw->rectangle(200, 0, 500, 500);
        $draw->popClipPath();
        $draw->setClipPath($clipPathName);
        $draw->rectangle(200, 200, 300, 300);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setClipUnits

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setClipUnits — Configura el modo de interpretación de las unidades de ruta

### Descripción

public function ImagickDraw::setClipUnits(int `$pathunits`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Configura el modo de interpretación de las unidades de ruta.

### Parámetros

`pathunits`

  El número de unidades de clip

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setClipUnits()

    <?php
    function setClipUnits($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);
        $clipPathName = 'testClipPath';
        $draw->setClipUnits(\Imagick::RESOLUTION_PIXELSPERINCH);
        $draw->pushClipPath($clipPathName);
        $draw->rectangle(0, 0, 250, 250);
        $draw->popClipPath();
        $draw->setClipPath($clipPathName);

        //RESOLUTION_PIXELSPERINCH
        //RESOLUTION_PIXELSPERCENTIMETER

        $draw->rectangle(200, 200, 300, 300);
        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFillAlpha

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillAlpha — Configura la opacidad del color de relleno

### Descripción

public function ImagickDraw::setFillAlpha(float `$alpha`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Configura la opacidad a utilizar cuando el color de relleno es usado. 1.0 es completamente opaco.

### Parámetros

`alpha`

  Canal alpha del color de relleno

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setFillAlpha()

    <?php
    function setFillAlpha($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);
        $draw->rectangle(100, 200, 200, 300);
        @$draw->setFillAlpha(0.4);
        $draw->rectangle(300, 200, 400, 300);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFillColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillColor — Configura el color de relleno de los objetos dibujados

### Descripción

public function ImagickDraw::setFillColor(ImagickPixel|string `$fill_color`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Configura el color de relleno de los objetos dibujados.

### Parámetros

`fill_color`

  El objeto ImagickPixel a utilizar para el color.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setFillColor()

    <?php
    function setFillColor($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(1.5);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->rectangle(50, 50, 150, 150);

        $draw->setFillColor("rgb(200, 32, 32)");
        $draw->rectangle(200, 50, 300, 150);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setFillOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillOpacity — Configura la opacidad a utilizar para el relleno

### Descripción

public function ImagickDraw::setFillOpacity(float `$opacity`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Configura la opacidad a utilizar para el relleno. Totalmente opaco es 1.0.

### Parámetros

`opacity`

  La opacidad de relleno.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setFillOpacity()

    <?php
    function setFillOpacity($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);

        $draw->rectangle(100, 200, 200, 300);

        $draw->setFillOpacity(0.4);
        $draw->rectangle(300, 200, 400, 300);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFillPatternURL

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillPatternURL — Configura la URL del patrón de relleno de superficies

### Descripción

public function ImagickDraw::setFillPatternURL(string `$fill_url`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Configura la URL del patrón de relleno de superficies. Actualmente, solo se soportan las URL locales (`"#identifier"`). Estas URL se crean normalmente al definir un nombre de patrón de relleno con DrawPushPattern/DrawPopPattern.

### Parámetros

`fill_url`

  La URL a utilizar para acceder al patrón.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# ImagickDraw::setFillRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillRule — Configura la regla de relleno de los polígonos

### Descripción

public function ImagickDraw::setFillRule(int `$fillrule`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Configura la regla de relleno de los polígonos.

### Parámetros

`fillrule`

  Una de las constantes FILLRULE (`imagick::FILLRULE_*`).

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setFillRule()

    <?php
    function setFillRule($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeWidth(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $fillRules = [\Imagick::FILLRULE_NONZERO, \Imagick::FILLRULE_EVENODD];

        $points = 11;
        $size = 150;

        $draw->translate(175, 160);

        for ($x = 0; $x < 2; $x++) {
            $draw->setFillRule($fillRules[$x]);
            $draw->pathStart();
            for ($n = 0; $n < $points * 2; $n++) {

                if ($n >= $points) {
                    $angle = fmod($n * 360 * 4 / $points, 360) * pi() / 180;
                }
                else {
                    $angle = fmod($n * 360 * 3 / $points, 360) * pi() / 180;
                }

                $positionX = $size * sin($angle);
                $positionY = $size * cos($angle);

                if ($n == 0) {
                    $draw->pathMoveToAbsolute($positionX, $positionY);
                }
                else {
                    $draw->pathLineToAbsolute($positionX, $positionY);
                }
            }

            $draw->pathClose();
            $draw->pathFinish();

            $draw->translate(325, 0);
        }

        $image = new \Imagick();
        $image->newImage(700, 320, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setFont

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFont — Establece la fuente especificada completamente para usarla cuando se escribe texto

### Descripción

public function ImagickDraw::setFont(string `$font_name`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Establece la fuente especificada completamente para usarla cuando se escribe texto.

### Parámetros

`font_name`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo de ImagickDraw::setFont()

    <?php
    function setFont($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(36);

        $draw->setFont("../fonts/Arial.ttf");
        $draw->annotation(50, 50, "Lorem Ipsum!");

        $draw->setFont("../fonts/Consolas.ttf");
        $draw->annotation(50, 100, "Lorem Ipsum!");

        $draw->setFont("../fonts/CANDY.TTF");
        $draw->annotation(50, 150, "Lorem Ipsum!");

        $draw->setFont("../fonts/Inconsolata-dz.otf");
        $draw->annotation(50, 200, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(500, 300, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFontFamily

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontFamily — Establece la familia de fuentes para usarla cuando se escribe texto

### Descripción

public function ImagickDraw::setFontFamily(string `$font_family`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Establece la familia de fuentes para usarla cuando se escribe texto.

### Parámetros

`font_family`

  la familia de fuentes

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo de ImagickDraw::setFontFamily()

    <?php
    function setFontFamily($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $strokeColor = new \ImagickPixel($strokeColor);
        $fillColor = new \ImagickPixel($fillColor);

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);

        $draw->setFontSize(48);

        $draw->setFontFamily("Times");
        $draw->annotation(50, 50, "Lorem Ipsum!");

        $draw->setFontFamily("AvantGarde");
        $draw->annotation(50, 100, "Lorem Ipsum!");

        $draw->setFontFamily("NewCenturySchlbk");
        $draw->annotation(50, 150, "Lorem Ipsum!");

        $draw->setFontFamily("Palatino");
        $draw->annotation(50, 200, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(450, 250, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFontSize

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontSize — Configura el tamaño de punto para los textos

### Descripción

public function ImagickDraw::setFontSize(float `$point_size`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Configura el tamaño de punto para los textos.

### Parámetros

`point_size`

  El tamaño de punto.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setFontSize()

    <?php
    function setFontSize($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);
        $draw->setFont("../fonts/Arial.ttf");

        $sizes = [24, 36, 48, 60, 72];

        foreach ($sizes as $size) {
            $draw->setFontSize($size);
            $draw->annotation(50, ($size * $size / 16), "Lorem Ipsum!");
        }

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFontStretch

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontStretch — Configura el estiramiento del texto

### Descripción

public function ImagickDraw::setFontStretch(int `$stretch`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Configura el estiramiento del texto para el dibujo de anotaciones. La enumeración `AnyStretch` sirve como comodín y significa "no importa".

### Parámetros

`stretch`

  Una de las constantes STRETCH (`imagick::STRETCH_*`).

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setFontStretch()

    <?php
    function setFontStretch($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(36);

        $fontStretchTypes = [
            \Imagick::STRETCH_ULTRACONDENSED,
            \Imagick::STRETCH_CONDENSED,
            \Imagick::STRETCH_SEMICONDENSED,
            \Imagick::STRETCH_SEMIEXPANDED,
            \Imagick::STRETCH_EXPANDED,
            \Imagick::STRETCH_EXTRAEXPANDED,
            \Imagick::STRETCH_ULTRAEXPANDED,
            \Imagick::STRETCH_ANY
        ];

        $offset = 0;
        foreach ($fontStretchTypes as $fontStretch) {
            $draw->setFontStretch($fontStretch);
            $draw->annotation(50, 75 + $offset, "Lorem Ipsum!");
            $offset += 50;
        }

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFontStyle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontStyle — Configura el estilo de la fuente

### Descripción

public function ImagickDraw::setFontStyle(int `$style`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Configura el estilo de la fuente utilizada para dibujar anotaciones. La enumeración `AnyStyle` actúa como comodín, y significa "no importa".

### Parámetros

`style`

  Una de las constantes STYLE (`imagick::STYLE_*`).

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setFontStyle()

    <?php
    function setFontStyle($fillColor, $strokeColor, $backgroundColor) {
        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setFontSize(36);
        $draw->setFontStyle(\Imagick::STYLE_NORMAL);
        $draw->annotation(50, 50, "Lorem Ipsum!");

        $draw->setFontStyle(\Imagick::STYLE_ITALIC);
        $draw->annotation(50, 100, "Lorem Ipsum!");

        $draw->setFontStyle(\Imagick::STYLE_OBLIQUE);
        $draw->annotation(50, 150, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(350, 300, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFontWeight

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontWeight — Configura el peso de la fuente

### Descripción

public function ImagickDraw::setFontWeight(int `$weight`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Configura el peso de la fuente para dibujar anotaciones.

### Parámetros

`weight`

### Valores devueltos

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setFontWeight()

    <?php
    function setFontWeight($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(1);

        $draw->setFontSize(36);

        $draw->setFontWeight(100);
        $draw->annotation(50, 50, "Lorem Ipsum!");

        $draw->setFontWeight(200);
        $draw->annotation(50, 100, "Lorem Ipsum!");

        $draw->setFontWeight(400);
        $draw->annotation(50, 150, "Lorem Ipsum!");

        $draw->setFontWeight(800);
        $draw->annotation(50, 200, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setGravity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setGravity — Configura la gravedad de colocación de texto

### Descripción

public function ImagickDraw::setGravity(int `$gravity`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Configura la gravedad de colocación de texto, a utilizar para dibujar las anotaciones.

### Parámetros

`gravity`

  Una de las constantes GRAVITY (`imagick::GRAVITY_*`).

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setGravity()

    <?php
    function setGravity($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setFontSize(24);

        $gravitySettings = array(
            \Imagick::GRAVITY_NORTHWEST => 'NorthWest',
            \Imagick::GRAVITY_NORTH => 'North',
            \Imagick::GRAVITY_NORTHEAST => 'NorthEast',
            \Imagick::GRAVITY_WEST => 'West',
            \Imagick::GRAVITY_CENTER => 'Centro',
            \Imagick::GRAVITY_SOUTHWEST => 'SouthWest',
            \Imagick::GRAVITY_SOUTH => 'South',
            \Imagick::GRAVITY_SOUTHEAST => 'SouthEast',
            \Imagick::GRAVITY_EAST => 'East'
        );

        $draw->setFont("../fonts/Arial.ttf");

        foreach ($gravitySettings as $type => $description) {
            $draw->setGravity($type);
            $draw->annotation(50, 50, '"' . $description . '"');
        }

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setResolution

(PECL imagick 3 >= 3.1.0)

ImagickDraw::setResolution — Define la resolución

### Descripción

public function ImagickDraw::setResolution(float `$resolution_x`, float `$resolution_y`): bool

Define la resolución.

### Parámetros

`resolution_x`

`resolution_y`

### Valores devueltos

Devuelve `true` en caso de éxito.

# ImagickDraw::setStrokeAlpha

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeAlpha — Especifica la opacidad de los contornos de los objetos

### Descripción

public function ImagickDraw::setStrokeAlpha(float `$alpha`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Especifica la opacidad de los contornos de los objetos.

### Parámetros

`alpha`

  La opacidad

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setStrokeAlpha()

    <?php
    function setStrokeAlpha($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(4);
        $draw->line(100, 100, 400, 145);
        $draw->rectangle(100, 200, 225, 350);
        $draw->setStrokeOpacity(0.1);
        $draw->line(100, 120, 400, 165);
        $draw->rectangle(275, 200, 400, 350);

        $image = new \Imagick();
        $image->newImage(500, 400, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeAntialias — Controla el anti-aliasing de los trazos

### Descripción

public function ImagickDraw::setStrokeAntialias(bool `$enabled`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Controla el anti-aliasing de los trazos. Los contornos a trazos están anti-aliaseados por omisión. Cuando el anti-aliasing está desactivado, los trazos utilizan un valor de umbral para definir si el píxel subyacente debe ser coloreado o no.

### Parámetros

`enabled`

  La configuración de uso del anti-aliasing

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setStrokeAntialias()

    <?php
    function setStrokeAntialias($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setStrokeAntialias(false);
        $draw->line(100, 100, 400, 105);

        $draw->line(100, 140, 400, 185);

        $draw->setStrokeAntialias(true);
        $draw->line(100, 110, 400, 115);
        $draw->line(100, 150, 400, 195);

        $image = new \Imagick();
        $image->newImage(500, 250, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeColor — Configura el color utilizado para dibujar objetos

### Descripción

public function ImagickDraw::setStrokeColor(ImagickPixel|string `$color`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Configura el color utilizado para dibujar objetos.

### Parámetros

`color`

  El color del trazo.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setStrokeColor()

    <?php
    function setStrokeColor($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(5);

        $draw->line(100, 100, 400, 145);
        $draw->rectangle(100, 200, 225, 350);

        $draw->setStrokeOpacity(0.1);
        $draw->line(100, 120, 400, 165);
        $draw->rectangle(275, 200, 400, 350);

        $image = new \Imagick();
        $image->newImage(500, 400, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeDashArray

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeDashArray — Especifica el patrón de trazo discontinuo

### Descripción

public function ImagickDraw::setStrokeDashArray(?array `$dashes`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Especifica el patrón de trazo discontinuo, los segmentos de línea continua y los espacios. El objeto strokeDashArray representa un array de números que especifican las longitudes de los segmentos de línea continua y los espacios, en píxeles. Si se proporciona un número impar de valores, entonces la lista se repite para obtener un número par de valores. Para eliminar un array de patrón existente, se debe pasar un array con cero elementos, y `null` como segundo valor. Un array strokeDashArray típico contiene los miembros 5 3 2.

### Parámetros

`dashes`

  Un array de números decimales

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setStrokeDashArray()

    <?php
    function setStrokeDashArray($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(4);

        $draw->setStrokeDashArray([10, 10]);
        $draw->rectangle(100, 50, 225, 175);

        $draw->setStrokeDashArray([20, 5, 20, 5, 5, 5,]);
        $draw->rectangle(275, 50, 400, 175);

        $draw->setStrokeDashArray([20, 5, 20, 5, 5]);
        $draw->rectangle(100, 200, 225, 350);

        $draw->setStrokeDashArray([1, 1, 1, 1, 2, 2, 3, 3, 5, 5, 8, 8, 13, 13, 21, 21, 34, 34, 55, 55, 89, 89, 144, 144, 233, 233, 377, 377, 610, 610, 987, 987, 1597, 1597, 2584, 2584, 4181, 4181,]);

        $draw->rectangle(275, 200, 400, 350);

        $image = new \Imagick();
        $image->newImage(500, 400, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeDashOffset

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeDashOffset — Especifica el índice dentro del patrón de discontinuidad para iniciar la discontinuidad

### Descripción

public function ImagickDraw::setStrokeDashOffset(float `$dash_offset`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Especifica el índice dentro del patrón de discontinuidad para iniciar la discontinuidad.

### Parámetros

`dash_offset`

  índice de discontinuidad

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo de ImagickDraw::setStrokeDashOffset()

    <?php
    function setStrokeDashOffset($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(4);
        $draw->setStrokeDashArray([20, 20]);
        $draw->setStrokeDashOffset(0);
        $draw->rectangle(100, 50, 225, 175);

        //Start the dash effect halfway through the solid portion
        $draw->setStrokeDashOffset(10);
        $draw->rectangle(275, 50, 400, 175);

        //Start the dash effect on the space portion
        $draw->setStrokeDashOffset(20);
        $draw->rectangle(100, 200, 225, 350);
        $draw->setStrokeDashOffset(5);
        $draw->rectangle(275, 200, 400, 350);

        $image = new \Imagick();
        $image->newImage(500, 400, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeLineCap

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeLineCap — Especifica la forma a utilizar al final de los subcampos

### Descripción

public function ImagickDraw::setStrokeLineCap(int `$linecap`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Especifica la forma a utilizar al final de los subcaminos.

### Parámetros

`linecap`

  Una de las constantes LINECAP (`imagick::LINECAP_*`).

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setStrokeLineCap()

    <?php
    function setStrokeLineCap($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(25);

        $lineTypes = [\Imagick::LINECAP_BUTT, \Imagick::LINECAP_ROUND, \Imagick::LINECAP_SQUARE,];

        $offset = 0;

        foreach ($lineTypes as $lineType) {
            $draw->setStrokeLineCap($lineType);
            $draw->line(50 + $offset, 50, 50 + $offset, 250);
            $offset += 50;
        }

        $imagick = new \Imagick();
        $imagick->newImage(300, 300, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeLineJoin

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeLineJoin — Especifica la forma a utilizar para dibujar los extremos de las líneas

### Descripción

public function ImagickDraw::setStrokeLineJoin(int `$linejoin`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Especifica la forma a utilizar para dibujar los extremos de las líneas y otras formas vectoriales cuando utilizan un trazo.

### Parámetros

`linejoin`

  Una de las constantes LINEJOIN (`imagick::LINEJOIN_*`).

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setStrokeLineJoin()

    <?php
    function setStrokeLineJoin($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeWidth(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(20);

        $offset = 220;

        $lineJoinStyle = [
            \Imagick::LINEJOIN_MITER,
            \Imagick::LINEJOIN_ROUND,
            \Imagick::LINEJOIN_BEVEL,
            ];

        for ($x = 0; $x < count($lineJoinStyle); $x++) {
            $draw->setStrokeLineJoin($lineJoinStyle[$x]);
            $points = [
                ['x' => 40 * 5, 'y' => 10 * 5 + $x * $offset],
                ['x' => 20 * 5, 'y' => 20 * 5 + $x * $offset],
                ['x' => 70 * 5, 'y' => 50 * 5 + $x * $offset],
                ['x' => 40 * 5, 'y' => 10 * 5 + $x * $offset],
            ];

            $draw->polyline($points);
        }

        $image = new \Imagick();
        $image->newImage(500, 700, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeMiterLimit

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeMiterLimit — Especifica el límite del inglete

### Descripción

public function ImagickDraw::setStrokeMiterLimit(int `$miterlimit`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Especifica el límite del inglete. Cuando dos segmentos de línea se encuentran en un águlo agudo y la unión del inglete ha sido especificada para 'lineJoin', es posible que el inglete se extienda más allá del grosor de la línea que contornea el trazado. 'miterLimit' impone un límite en la proporción de la longitud del inglete a 'lineWidth'.

### Parámetros

`miterlimit`

  el límite del inglete

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo de ImagickDraw::setStrokeMiterLimit()

    <?php
    function setStrokeMiterLimit($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeOpacity(0.6);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(10);

        $yOffset = 100;

        $draw->setStrokeLineJoin(\Imagick::LINEJOIN_MITER);

        for ($y = 0; $y < 3; $y++) {

            $draw->setStrokeMiterLimit(40 * $y);

            $points = [
                ['x' => 22 * 3, 'y' => 15 * 4 + $y * $yOffset],
                ['x' => 20 * 3, 'y' => 20 * 4 + $y * $yOffset],
                ['x' => 70 * 5, 'y' => 45 * 4 + $y * $yOffset],
            ];

            $draw->polygon($points);
        }

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        $image->setImageType(\Imagick::IMGTYPE_PALETTE);
        $image->setImageCompressionQuality(100);
        $image->stripImage();

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeOpacity — Especifica la opacidad para dibujar los contornos

### Descripción

public function ImagickDraw::setStrokeOpacity(float `$opacity`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Especifica la opacidad para dibujar los contornos.

### Parámetros

`opacity`

  La opacidad del trazo. 1.0 es completamente opaco.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setStrokeOpacity()

    <?php
    function setStrokeOpacity($strokeColor, $fillColor, $backgroundColor) {
        $draw = new \ImagickDraw();

        $draw->setStrokeWidth(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(10);
        $draw->setStrokeOpacity(1);
        $draw->line(100, 80, 400, 125);
        $draw->rectangle(25, 200, 150, 350);
        $draw->setStrokeOpacity(0.5);
        $draw->line(100, 100, 400, 145);
        $draw->rectangle(200, 200, 325, 350);
        $draw->setStrokeOpacity(0.2);
        $draw->line(100, 120, 400, 165);
        $draw->rectangle(375, 200, 500, 350);

        $image = new \Imagick();
        $image->newImage(550, 400, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokePatternURL

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokePatternURL — Establece el patrón usado para los perfiles de objetos contorneados

### Descripción

public function ImagickDraw::setStrokePatternURL(string `$stroke_url`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Establece el patrón usado para los perfiles de objetos contorneados.

### Parámetros

`stroke_url`

  URL contorneada

### Valores devueltos

Devuelve `true` en caso de éxito.

# ImagickDraw::setStrokeWidth

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeWidth — Configura el ancho del trazo para dibujar contornos

### Descripción

public function ImagickDraw::setStrokeWidth(float `$width`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Configura el ancho del trazo para dibujar contornos.

### Parámetros

`width`

  El ancho del trazo

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setStrokeWidth()

    <?php
    function setStrokeWidth($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeWidth(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->line(100, 100, 400, 145);
        $draw->rectangle(100, 200, 225, 350);
        $draw->setStrokeWidth(5);
        $draw->line(100, 120, 400, 165);
        $draw->rectangle(275, 200, 400, 350);

        $image = new \Imagick();
        $image->newImage(500, 400, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setTextAlignment

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextAlignment — Especifica la alineación del texto

### Descripción

public function ImagickDraw::setTextAlignment(int `$align`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Especifica la alineación del texto a aplicar al texto de una anotación.

### Parámetros

`align`

  Una de las constantes ALIGN (`imagick::ALIGN_*`).

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setTextAlignment()

    <?php
    function setTextAlignment($strokeColor, $fillColor, $backgroundColor) {
        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setFontSize(36);

        $draw->setTextAlignment(\Imagick::ALIGN_LEFT);
        $draw->annotation(250, 75, "Lorem Ipsum!");
        $draw->setTextAlignment(\Imagick::ALIGN_CENTER);
        $draw->annotation(250, 150, "Lorem Ipsum!");
        $draw->setTextAlignment(\Imagick::ALIGN_RIGHT);
        $draw->annotation(250, 225, "Lorem Ipsum!");
        $draw->line(250, 0, 250, 500);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setTextAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextAntialias — Controla el anti-aliaseo del texto

### Descripción

public function ImagickDraw::setTextAntialias(bool `$antialias`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Controla el anti-aliaseo del texto. El texto es anti-aliaseado por omisión.

### Parámetros

`antialias`

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setTextAntialias()

    <?php
    function setTextAntialias($fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor('none');
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setFontSize(32);
        $draw->setTextAntialias(false);
        $draw->annotation(5, 30, "Lorem Ipsum!");
        $draw->setTextAntialias(true);
        $draw->annotation(5, 65, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(220, 80, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        //Scale the image so that people can see the aliasing.
        $imagick->scaleImage(220 * 6, 80 * 6);
        $imagick->cropImage(640, 480, 0, 0);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setTextDecoration

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextDecoration — Especifica los ornamentos de texto

### Descripción

public function ImagickDraw::setTextDecoration(int `$decoration`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Especifica los ornamentos de texto utilizados para las anotaciones.

### Parámetros

`decoration`

  Una de las constantes DECORATION (`imagick::DECORATION_*`).

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setTextDecoration()

    <?php
    function setTextDecoration($strokeColor, $fillColor, $backgroundColor, $textDecoration) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);
        $draw->setTextDecoration($textDecoration);
        $draw->annotation(50, 75, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(500, 200, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setTextEncoding

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextEncoding — Especifica el juego de caracteres

### Descripción

public function ImagickDraw::setTextEncoding(string `$encoding`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Especifica el juego de caracteres a utilizar para las anotaciones de texto. El único juego de caracteres que puede ser especificado actualmente es "UTF-8", que representa el Unicode bajo la forma de una secuencia de octetos. Especifique una cadena vacía para utilizar el juego de caracteres del sistema. El dibujo de textos puede requerir una fuente que soporte Unicode.

### Parámetros

`encoding`

  El juego de caracteres

### Valores devueltos

No se retorna ningún valor.

# ImagickDraw::setTextInterlineSpacing

(PECL imagick 3 >= 3.1.0)

ImagickDraw::setTextInterlineSpacing — Define el espacio entre las líneas de un texto

### Descripción

public function ImagickDraw::setTextInterlineSpacing(float `$spacing`): bool

Define el espacio entre las líneas de un texto.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`spacing`

### Valores devueltos

Devuelve `true` en caso de éxito.

# ImagickDraw::setTextInterwordSpacing

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickDraw::setTextInterwordSpacing — Define el espacio entre las palabras de un texto

### Descripción

public function ImagickDraw::setTextInterwordSpacing(float `$spacing`): bool

Define el espacio entre las palabras de un texto.

### Parámetros

`spacing`

### Valores devueltos

Devuelve `true` en caso de éxito.

# ImagickDraw::setTextKerning

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickDraw::setTextKerning — Define el interletraje de un texto

### Descripción

public function ImagickDraw::setTextKerning(float `$kerning`): bool

Define el interletraje de un texto.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`kerning`

### Valores devueltos

Devuelve `true` en caso de éxito.

# ImagickDraw::setTextUnderColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextUnderColor — Especifica el color de fondo de un rectángulo

### Descripción

public function ImagickDraw::setTextUnderColor(ImagickPixel|string `$under_color`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Especifica el color de fondo de un rectángulo a colocar bajo los textos.

### Parámetros

`under_color`

  El color de fondo

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setTextUnderColor()

    <?php
    function setTextUnderColor($strokeColor, $fillColor, $backgroundColor, $textUnderColor) {
        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);
        $draw->annotation(50, 75, "Lorem Ipsum!");
        $draw->setTextUnderColor($textUnderColor);
        $draw->annotation(50, 175, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setVectorGraphics

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setVectorGraphics — Establece los gráficos vectoriales

### Descripción

public function ImagickDraw::setVectorGraphics(string `$xml`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Establece los gráficos vectoriales asociados al objeto ImagickDraw especificado. Use este método con ImagickDraw::getVectorGraphics() como un método de persistencia del estado de los gráficos vectoriales.

### Parámetros

`xml`

  archivo xml que contiene los gráficos vectoriales

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de ImagickDraw::setVectorGraphics()

    <?php
    function setVectorGraphics() {
        //Setup a draw object with some drawing in it.
        $draw = new \ImagickDraw();
        $draw->setFillColor("red");
        $draw->circle(20, 20, 50, 50);
        $draw->setFillColor("blue");
        $draw->circle(50, 70, 50, 50);
        $draw->rectangle(50, 120, 80, 150);

        //Get the drawing as a string
        $SVG = $draw->getVectorGraphics();

        //$svg is a string, and could be saved anywhere a string can be saved

        //Use the saved drawing to generate a new draw object
        $draw2 = new \ImagickDraw();
        //Apparently the SVG text is missing the root element.
        $draw2->setVectorGraphics("<root>".$SVG."</root>");

        $imagick = new \Imagick();
        $imagick->newImage(200, 200, 'white');
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw2);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setViewbox

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setViewbox — Configura el tamaño del lienzo

### Descripción

public function ImagickDraw::setViewbox(
int `$left_x`,
int `$top_y`,
int `$right_x`,
int `$bottom_y`
): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Configura el tamaño general del lienzo, a registrar con los datos vectoriales. Generalmente, este valor se configura con el mismo tamaño que la imagen. Cuando los datos vectoriales se guardan en SVG o MVG, la caja de vista se utiliza para especificar el tamaño de la imagen en la que el visualizador dibujará los datos.

### Parámetros

`left_x`

  Abscisa izquierda

`top_y`

  Ordenada superior

`right_x`

  Abscisa derecha

`bottom_y`

  Ordenada inferior

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickDraw::setViewBox()

    <?php
    function setViewBox($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        /*
          Configura el tamaño general del lienzo a registrar con los datos vectoriales. Generalmente, este valor se configura con el mismo tamaño que la imagen. Cuando los datos vectoriales se guardan en SVG o MVG, la caja de vista se utiliza para especificar el tamaño de la imagen en la que el visualizador dibujará los datos.
         */

        $draw->circle(250, 250, 250, 0);
        $draw->setviewbox(0, 0, 200, 200);
        $draw->circle(125, 250, 250, 250);
        $draw->translate(250, 125);
        $draw->circle(0, 0, 125, 0);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::skewX

(PECL imagick 2, PECL imagick 3)

ImagickDraw::skewX — Tuerce el sistema de coordenadas actual en la dirección horizontal

### Descripción

public function ImagickDraw::skewX(float `$degrees`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Tuerce el sistema de coordenadas actual en la dirección horizontal.

### Parámetros

`degrees`

  grados de torción

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo de ImagickDraw::skewX()

    <?php
    function skewX($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor,
                   $startX, $startY, $endX, $endY, $skew) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeWidth(2);
        $draw->setFillColor($fillColor);
        $draw->rectangle($startX, $startY, $endX, $endY);
        $draw->setFillColor($fillModifiedColor);
        $draw->skewX($skew);
        $draw->rectangle($startX, $startY, $endX, $endY);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::skewY

(PECL imagick 2, PECL imagick 3)

ImagickDraw::skewY — Tuerce el sistema de coordenadas actual en la dirección vertical

### Descripción

public function ImagickDraw::skewY(float `$degrees`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Tuerce el sistema de coordenadas actual en la dirección vertical.

### Parámetros

`degrees`

  grados de torción

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo de ImagickDraw::skewY()

    <?php
    function skewY($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor,
                   $startX, $startY, $endX, $endY, $skew) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeWidth(2);
        $draw->setFillColor($fillColor);
        $draw->rectangle($startX, $startY, $endX, $endY);
        $draw->setFillColor($fillModifiedColor);
        $draw->skewY($skew);
        $draw->rectangle($startX, $startY, $endX, $endY);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::translate

(PECL imagick 2, PECL imagick 3)

ImagickDraw::translate — Aplica una traslación del sistema de coordenadas actual

### Descripción

public function ImagickDraw::translate(float `$x`, float `$y`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Aplica una traslación del sistema de coordenadas actual el cuál mueve el origen del sistema de coordenadas a las coordenadas especifiacadas.

### Parámetros

`x`

  traslación horizontal

`y`

  traslación vertical

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo de ImagickDraw::translate()

    <?php
    function translate($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor,
                       $startX, $startY, $endX, $endY, $translateX, $translateY) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->rectangle($startX, $startY, $endX, $endY);

        $draw->setFillColor($fillModifiedColor);
        $draw->translate($translateX, $translateY);
        $draw->rectangle($startX, $startY, $endX, $endY);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

## Tabla de contenidos

- ImagickDraw::affine — Ajusta la matriz de transformación afín actual
- ImagickDraw::annotation — Dibuja un texto sobre una imagen
- ImagickDraw::arc — Dibuja un arco
- ImagickDraw::bezier — Dibuja una curva de Bézier
- ImagickDraw::circle — Dibuja un círculo
- ImagickDraw::clear — Borra el objeto ImagickDraw
- ImagickDraw::clone — Realiza una copia exacta del objeto ImagickDraw
- ImagickDraw::color — Dibuja un color sobre una imagen
- ImagickDraw::comment — Añade un comentario
- ImagickDraw::composite — Componer una imagen con otra
- ImagickDraw::__construct — El constructor ImagickDraw
- ImagickDraw::destroy — Libera todos los recursos asociados
- ImagickDraw::ellipse — Dibuja una elipse sobre una imagen
- ImagickDraw::getClipPath — Devuelve el identificador del camino actual
- ImagickDraw::getClipRule — Devuelve la regla de relleno de un polígono actual
- ImagickDraw::getClipUnits — Devuelve la interpretación de unidades del trazado de recorte
- ImagickDraw::getFillColor — Devuelve el color de relleno
- ImagickDraw::getFillOpacity — Devuelve la opacidad de dibujo
- ImagickDraw::getFillRule — Devuelve la regla de relleno
- ImagickDraw::getFont — Devuelve la fuente
- ImagickDraw::getFontFamily — Devuelve la familia de fuentes
- ImagickDraw::getFontSize — Devuelve el tamaño de punto de la fuente
- ImagickDraw::getFontStretch — Devuelve el estiramiento de la fuente a utilizar durante la anotación con texto
- ImagickDraw::getFontStyle — Devuelve el estilo de la fuente
- ImagickDraw::getFontWeight — Devuelve el peso de la fuente
- ImagickDraw::getGravity — Devuelve la gravedad de colocación de texto
- ImagickDraw::getStrokeAntialias — Devuelve la configuración de antialias de contorno actual
- ImagickDraw::getStrokeColor — Devuelve el color usado por los perfiles de objetos contorneados
- ImagickDraw::getStrokeDashArray — Devuelve un array que representa el patrón de trazos
- ImagickDraw::getStrokeDashOffset — Devuelve el desplazamiento del punto en el patrón
- ImagickDraw::getStrokeLineCap — Devuelve la forma a utilizar para dibujar los extremos de subrutas
- ImagickDraw::getStrokeLineJoin — Devuelve la forma a utilizar para dibujar las esquinas de un camino
- ImagickDraw::getStrokeMiterLimit — Devuelve el valor de 'miterLimit'
- ImagickDraw::getStrokeOpacity — Devuelve la opacidad de los contornos de un objeto
- ImagickDraw::getStrokeWidth — Devuelve el ancho de trazo utilizado
- ImagickDraw::getTextAlignment — Devuelve la alineación del texto
- ImagickDraw::getTextAntialias — Devuelve la configuración de antialias del texto actual
- ImagickDraw::getTextDecoration — Devuelve la decoración del texto
- ImagickDraw::getTextEncoding — Devuelve el juego de caracteres utilizado para las anotaciones de texto
- ImagickDraw::getTextInterlineSpacing — Obtiene el espacio entre líneas de un texto.
- ImagickDraw::getTextInterwordSpacing — Obtiene el espacio entre palabras de un texto.
- ImagickDraw::getTextKerning — Obtiene el interletraje de un texto.
- ImagickDraw::getTextUnderColor — Devuelve el color debajo del texto
- ImagickDraw::getVectorGraphics — Devuelve una cadena que contiene gráficos vectoriales
- ImagickDraw::line — Dibuja una línea
- ImagickDraw::matte — Dibuja sobre el canal de opacidad de la imagen
- ImagickDraw::pathClose — Añade un elemento de camino al camino actual
- ImagickDraw::pathCurveToAbsolute — Dibuja una curva de Bézier cúbica, en coordenadas absolutas
- ImagickDraw::pathCurveToQuadraticBezierAbsolute — Dibuja una curva de Bézier cuadrática, en coordenadas absolutas
- ImagickDraw::pathCurveToQuadraticBezierRelative — Dibuja una curva de Bézier cuadrática, en coordenadas relativas
- ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute — Dibuja una curva Bézier cuadrática
- ImagickDraw::pathCurveToQuadraticBezierSmoothRelative — Dibuja una curva Bézier cuadrática
- ImagickDraw::pathCurveToRelative — Dibuja una curva de Bézier cúbica, en coordenadas relativas
- ImagickDraw::pathCurveToSmoothAbsolute — Dibuja una curva de Bézier, en coordenadas absolutas
- ImagickDraw::pathCurveToSmoothRelative — Dibuja una curva de Bézier, en coordenadas relativas
- ImagickDraw::pathEllipticArcAbsolute — Dibuja un arco de elipse, en coordenadas absolutas
- ImagickDraw::pathEllipticArcRelative — Dibuja un arco de elipse, en coordenadas relativas
- ImagickDraw::pathFinish — Finaliza el camino actual
- ImagickDraw::pathLineToAbsolute — Dibuja una línea de camino, en coordenadas absolutas
- ImagickDraw::pathLineToHorizontalAbsolute — Dibuja una línea de camino horizontal, en coordenadas absolutas
- ImagickDraw::pathLineToHorizontalRelative — Dibuja una línea de camino horizontal, en coordenadas relativas
- ImagickDraw::pathLineToRelative — Dibuja una línea de camino, en coordenadas relativas
- ImagickDraw::pathLineToVerticalAbsolute — Dibuja una línea de camino vertical, en coordenadas absolutas
- ImagickDraw::pathLineToVerticalRelative — Dibuja una línea de camino vertical, en coordenadas relativas
- ImagickDraw::pathMoveToAbsolute — Inicia un nuevo subcamino, en coordenadas absolutas
- ImagickDraw::pathMoveToRelative — Inicia un nuevo subcamino, en coordenadas relativas
- ImagickDraw::pathStart — Declara el inicio de una lista de dibujo de trazados
- ImagickDraw::point — Dibuja un punto
- ImagickDraw::polygon — Dibuja un polígono
- ImagickDraw::polyline — Dibuja una poli-línea
- ImagickDraw::pop — Destruye el objeto ImagickDraw actual de la pila, y lo devuelve al objeto ImagickDraw previamente metido
- ImagickDraw::popClipPath — Finaliza la definición de un camino
- ImagickDraw::popDefs — Finaliza una lista de definiciones
- ImagickDraw::popPattern — Finaliza una definición de patrón
- ImagickDraw::push — Clona el objeto ImagickDraw actual y lo mete en la pila
- ImagickDraw::pushClipPath — Inicia la definición de un trazado de recorte
- ImagickDraw::pushDefs — Indica que los siguientes comandos crean elementos con nombre para un procesamiento previo
- ImagickDraw::pushPattern — Indica que los comandos subsiguientes hasta un comando ImagickDraw::opPattern() comprenden la definición de un patrón nominado
- ImagickDraw::rectangle — Dibuja un rectángulo
- ImagickDraw::render — Realiza el renderizado de todos los dibujos en la imagen
- ImagickDraw::resetVectorGraphics — Restablece los gráficos vectoriales
- ImagickDraw::rotate — Aplica la rotación especificada al espacio de coordenadas actual
- ImagickDraw::roundRectangle — Dibuja un rectángulo con esquinas redondeadas
- ImagickDraw::scale — Ajusta el factor de escala
- ImagickDraw::setClipPath — Asocia un trazado de recorte nominado con la imagen
- ImagickDraw::setClipRule — Configura la regla de relleno del polígono a utilizar con los caminos
- ImagickDraw::setClipUnits — Configura el modo de interpretación de las unidades de ruta
- ImagickDraw::setFillAlpha — Configura la opacidad del color de relleno
- ImagickDraw::setFillColor — Configura el color de relleno de los objetos dibujados
- ImagickDraw::setFillOpacity — Configura la opacidad a utilizar para el relleno
- ImagickDraw::setFillPatternURL — Configura la URL del patrón de relleno de superficies
- ImagickDraw::setFillRule — Configura la regla de relleno de los polígonos
- ImagickDraw::setFont — Establece la fuente especificada completamente para usarla cuando se escribe texto
- ImagickDraw::setFontFamily — Establece la familia de fuentes para usarla cuando se escribe texto
- ImagickDraw::setFontSize — Configura el tamaño de punto para los textos
- ImagickDraw::setFontStretch — Configura el estiramiento del texto
- ImagickDraw::setFontStyle — Configura el estilo de la fuente
- ImagickDraw::setFontWeight — Configura el peso de la fuente
- ImagickDraw::setGravity — Configura la gravedad de colocación de texto
- ImagickDraw::setResolution — Define la resolución
- ImagickDraw::setStrokeAlpha — Especifica la opacidad de los contornos de los objetos
- ImagickDraw::setStrokeAntialias — Controla el anti-aliasing de los trazos
- ImagickDraw::setStrokeColor — Configura el color utilizado para dibujar objetos
- ImagickDraw::setStrokeDashArray — Especifica el patrón de trazo discontinuo
- ImagickDraw::setStrokeDashOffset — Especifica el índice dentro del patrón de discontinuidad para iniciar la discontinuidad
- ImagickDraw::setStrokeLineCap — Especifica la forma a utilizar al final de los subcampos
- ImagickDraw::setStrokeLineJoin — Especifica la forma a utilizar para dibujar los extremos de las líneas
- ImagickDraw::setStrokeMiterLimit — Especifica el límite del inglete
- ImagickDraw::setStrokeOpacity — Especifica la opacidad para dibujar los contornos
- ImagickDraw::setStrokePatternURL — Establece el patrón usado para los perfiles de objetos contorneados
- ImagickDraw::setStrokeWidth — Configura el ancho del trazo para dibujar contornos
- ImagickDraw::setTextAlignment — Especifica la alineación del texto
- ImagickDraw::setTextAntialias — Controla el anti-aliaseo del texto
- ImagickDraw::setTextDecoration — Especifica los ornamentos de texto
- ImagickDraw::setTextEncoding — Especifica el juego de caracteres
- ImagickDraw::setTextInterlineSpacing — Define el espacio entre las líneas de un texto
- ImagickDraw::setTextInterwordSpacing — Define el espacio entre las palabras de un texto
- ImagickDraw::setTextKerning — Define el interletraje de un texto
- ImagickDraw::setTextUnderColor — Especifica el color de fondo de un rectángulo
- ImagickDraw::setVectorGraphics — Establece los gráficos vectoriales
- ImagickDraw::setViewbox — Configura el tamaño del lienzo
- ImagickDraw::skewX — Tuerce el sistema de coordenadas actual en la dirección horizontal
- ImagickDraw::skewY — Tuerce el sistema de coordenadas actual en la dirección vertical
- ImagickDraw::translate — Aplica una traslación del sistema de coordenadas actual

# La clase ImagickDrawException

(PECL imagick 3)

## Introducción

## Sinopsis de la Clase

class ImagickDrawException extends Exception implements Throwable {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
/* Métodos heredados */
}

# La clase ImagickException

(PECL imagick 3)

## Introducción

## Sinopsis de la Clase

class ImagickException extends Exception implements Throwable {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
/* Métodos heredados */
}

# La clase ImagickKernel

(PECL imagick >= 3.3.0)

## Introducción

## Sinopsis de la Clase

class ImagickKernel {
/* Métodos */
public function addKernel(ImagickKernel `$ImagickKernel`): void
public function addUnityKernel(float `$scale`): void
public static function fromBuiltin(int `$kernelType`, string `$kernelString`): ImagickKernel
public static function fromMatrix(array `$matrix`, array `$origin` = ?): ImagickKernel
public function getMatrix(): array
public function scale(float `$scale`, int `$normalizeFlag` = ?): void
public function separate(): array
}

# ImagickKernel::addKernel

(PECL imagick >= 3.3.0)

ImagickKernel::addKernel — Adjunta otro núcleo a una lista de núcleos

### Descripción

public function ImagickKernel::addKernel(ImagickKernel `$ImagickKernel`): void

Adjunta otro núcleo a este núcleo para permitir que ambos sean aplicados en una sola función de morfología o filtro. Devuelve el nuevo núcleo combinado.

### Parámetros

`ImagickKernel`

### Valores devueltos

### Ejemplos

Ejemplo #1 ImagickKernel::addKernel()

    <?php
    function addKernel($imagePath) {
        $matrix1 = [
            [-1, -1, -1],
            [ 0,  0,  0],
            [ 1,  1,  1],
        ];

        $matrix2 = [
            [-1,  0,  1],
            [-1,  0,  1],
            [-1,  0,  1],
        ];

        $kernel1 = ImagickKernel::fromMatrix($matrix1);
        $kernel2 = ImagickKernel::fromMatrix($matrix2);
        $kernel1->addKernel($kernel2);

        $imagick = new \Imagick(realpath($imagePath));
        $imagick->filter($kernel1);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();

    }

    ?>

# ImagickKernel::addUnityKernel

(PECL imagick >= 3.3.0)

ImagickKernel::addUnityKernel — Añade un núcleo Unity a la lista de núcleos

### Descripción

public function ImagickKernel::addUnityKernel(float `$scale`): void

Añade una cantidad dada del núcleo de convolución 'Unity' al núcleo de convolución pre-escalado y normalizado dado. Esto tiene como efecto añadir esta cantidad de la imagen original en el núcleo de convolución resultante. El efecto resultante es convertir los núcleos definidos en desenfoques suaves mezclados, en núcleos no afilados o en núcleos de nitidez.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

### Ejemplos

Ejemplo #1 ImagickKernel::addUnityKernel()

    <?php

        function renderKernelTable($matrix) {
            $output = "<table class='infoTable'>";

            foreach ($matrix as $row) {
                $output .= "<tr>";
                foreach ($row as $cell) {
                    $output .= "<td style='text-align:left'>";
                    if ($cell === false) {
                        $output .= "false";
                    }
                    else {
                        $output .= round($cell, 3);
                    }
                    $output .= "</td>";
                }
                $output .= "</tr>";
            }

            $output .= "</table>";

            return $output;
        }

        $matrix = [
            [-1, 0, -1],
            [ 0, 4,  0],
            [-1, 0, -1],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix);
        $kernel->scale(1, \Imagick::NORMALIZE_KERNEL_VALUE);
        $output = "Before adding unity kernel: <br/>";
        $output .= renderKernelTable($kernel->getMatrix());
        $kernel->addUnityKernel(0.5);
        $output .= "After adding unity kernel: <br/>";
        $output .= renderKernelTable($kernel->getMatrix());

        $kernel->scale(1, \Imagick::NORMALIZE_KERNEL_VALUE);
        $output .= "After renormalizing kernel: <br/>";
        $output .= renderKernelTable($kernel->getMatrix());

        echo $output;

    ?>

Ejemplo #2 ImagickKernel::addUnityKernel()

    <?php
    function addUnityKernel($imagePath) {

        $matrix = [
            [-1, 0, -1],
            [ 0, 4,  0],
            [-1, 0, -1],
        ];

        $kernel = ImagickKernel::fromMatrix($matrix);

        $kernel->scale(4, \Imagick::NORMALIZE_KERNEL_VALUE);
        $kernel->addUnityKernel(0.5);

        $imagick = new \Imagick(realpath($imagePath));
        $imagick->filter($kernel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();

    }

    ?>

# ImagickKernel::fromBuiltIn

(PECL imagick >= 3.3.0)

ImagickKernel::fromBuiltIn — Crear un núcleo a partir de un núcleo integrado

### Descripción

public static function ImagickKernel::fromBuiltin(int `$kernelType`, string `$kernelString`): ImagickKernel

Crear un núcleo a partir de un núcleo integrado. Ver http://www.imagemagick.org/Usage/morphology/#kernel para ejemplos. Actualmente, los símbolos de 'rotación' no son soportados. Ejemplo: $diamondKernel = ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DIAMOND, "2");

### Parámetros

`kerneltype`

  El tipo de núcleo a construir, por ejemplo \Imagick::KERNEL_DIAMOND

`kernelString`

  Una cadena que describe los parámetros, por ejemplo "4,2.5"

### Valores devueltos

### Ejemplos

Ejemplo #1 ImagickKernel::fromBuiltin()

    <?php

    function renderKernel(ImagickKernel $imagickKernel) {
        $matrix = $imagickKernel->getMatrix();

        $imageMargin = 20;

        $tileSize = 20;
        $tileSpace = 4;
        $shadowSigma = 4;
        $shadowDropX = 20;
        $shadowDropY = 0;

        $radius = ($tileSize / 2) * 0.9;

        $rows = count($matrix);
        $columns = count($matrix[0]);

        $imagickDraw = new \ImagickDraw();

        $imagickDraw->setFillColor('#afafaf');
        $imagickDraw->setStrokeColor('none');

        $imagickDraw->translate($imageMargin, $imageMargin);
        $imagickDraw->push();

        ksort($matrix);

        foreach ($matrix as $row) {
            ksort($row);
            $imagickDraw->push();
            foreach ($row as $cell) {
                if ($cell !== false) {
                    $color = intval(255 * $cell);
                    $colorString = sprintf("rgb(%f, %f, %f)", $color, $color, $color);
                    $imagickDraw->setFillColor($colorString);
                    $imagickDraw->rectangle(0, 0, $tileSize, $tileSize);
                }
                $imagickDraw->translate(($tileSize + $tileSpace), 0);
            }
            $imagickDraw->pop();
            $imagickDraw->translate(0, ($tileSize + $tileSpace));
        }

        $imagickDraw->pop();

        $width = ($columns * $tileSize) + (($columns - 1) * $tileSpace);
        $height = ($rows * $tileSize) + (($rows - 1) * $tileSpace);

        $imagickDraw->push();
        $imagickDraw->translate($width/2 , $height/2);
        $imagickDraw->setFillColor('rgba(0, 0, 0, 0)');
        $imagickDraw->setStrokeColor('white');
        $imagickDraw->circle(0, 0, $radius - 1, 0);
        $imagickDraw->setStrokeColor('black');
        $imagickDraw->circle(0, 0, $radius, 0);
        $imagickDraw->pop();

        $canvasWidth = $width + (2 * $imageMargin);
        $canvasHeight = $height + (2 * $imageMargin);

        $kernel = new \Imagick();
        $kernel->newPseudoImage(
            $canvasWidth,
            $canvasHeight,
            'canvas:none'
        );

        $kernel->setImageFormat('png');
        $kernel->drawImage($imagickDraw);

        /* crear una sombra paralela en su propia capa */
        $canvas = $kernel->clone();
        $canvas->setImageBackgroundColor(new \ImagickPixel('rgb(0, 0, 0)'));
        $canvas->shadowImage(100, $shadowSigma, $shadowDropX, $shadowDropY);

        $canvas->setImagePage($canvasWidth, $canvasHeight, -5, -5);
        $canvas->cropImage($canvasWidth, $canvasHeight, 0, 0);

        /* composite original text_layer onto shadow_layer */
        $canvas->compositeImage($kernel, \Imagick::COMPOSITE_OVER, 0, 0);
        $canvas->setImageFormat('png');

        return $canvas;
    }

    function createFromBuiltin($kernelType, $kernelFirstTerm, $kernelSecondTerm, $kernelThirdTerm) {
        $string = '';

        if ($kernelFirstTerm != false && strlen(trim($kernelFirstTerm)) != 0) {
            $string .= $kernelFirstTerm;

            if ($kernelSecondTerm != false && strlen(trim($kernelSecondTerm)) != 0) {
                $string .= ','.$kernelSecondTerm;
                if ($kernelThirdTerm != false && strlen(trim($kernelThirdTerm)) != 0) {
                    $string .= ','.$kernelThirdTerm;
                }
            }
        }

        $kernel = ImagickKernel::fromBuiltIn(
            $kernelType,
            $string
        );

        return $kernel;
    }

    function fromBuiltin($kernelType, $kernelFirstTerm, $kernelSecondTerm, $kernelThirdTerm) {
        $diamondKernel = createFromBuiltin($kernelType, $kernelFirstTerm, $kernelSecondTerm, $kernelThirdTerm);
        $imagick = renderKernel($diamondKernel);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    fromBuiltin(\Imagick::KERNEL_DIAMOND, 2, false, false);

    ?>

# ImagickKernel::fromMatrix

(PECL imagick >= 3.3.0)

ImagickKernel::fromMatrix — Crear un núcleo a partir de una matriz 2D de valores

### Descripción

public static function ImagickKernel::fromMatrix(array `$matrix`, array `$origin` = ?): ImagickKernel

Crear un núcleo a partir de una matriz 2D de valores. Cada valor debe ser un float (si el elemento debe ser utilizado) o 'false' si el elemento debe ser ignorado. Para las matrices que tienen tamaños impares en ambas dimensiones, el píxel de origen será por defecto en el centro del núcleo. Para todas las demás dimensiones de núcleo, el píxel de origen debe ser especificado.

### Parámetros

`array`

  Una matriz (es decir, un array 2D) de valores que definen el núcleo. Cada elemento debe ser un valor float, o FALSE si este elemento no debe ser utilizado por el núcleo.

`array`

  Cuál elemento del núcleo debe ser utilizado como píxel de origen. Por ejemplo, para una matriz 3x3 especificando el origen como [2, 2] especificaría que el elemento en la parte inferior derecha debería ser el píxel de origen.

### Valores devueltos

El objeto ImagickKernel generado.

### Ejemplos

Ejemplo #1 ImagickKernel::fromMatrix()

    <?php

    function renderKernel(ImagickKernel $imagickKernel) {
        $matrix = $imagickKernel->getMatrix();

        $imageMargin = 20;

        $tileSize = 20;
        $tileSpace = 4;
        $shadowSigma = 4;
        $shadowDropX = 20;
        $shadowDropY = 0;

        $radius = ($tileSize / 2) * 0.9;

        $rows = count($matrix);
        $columns = count($matrix[0]);

        $imagickDraw = new \ImagickDraw();

        $imagickDraw->setFillColor('#afafaf');
        $imagickDraw->setStrokeColor('none');

        $imagickDraw->translate($imageMargin, $imageMargin);
        $imagickDraw->push();

        ksort($matrix);

        foreach ($matrix as $row) {
            ksort($row);
            $imagickDraw->push();
            foreach ($row as $cell) {
                if ($cell !== false) {
                    $color = intval(255 * $cell);
                    $colorString = sprintf("rgb(%f, %f, %f)", $color, $color, $color);
                    $imagickDraw->setFillColor($colorString);
                    $imagickDraw->rectangle(0, 0, $tileSize, $tileSize);
                }
                $imagickDraw->translate(($tileSize + $tileSpace), 0);
            }
            $imagickDraw->pop();
            $imagickDraw->translate(0, ($tileSize + $tileSpace));
        }

        $imagickDraw->pop();

        $width = ($columns * $tileSize) + (($columns - 1) * $tileSpace);
        $height = ($rows * $tileSize) + (($rows - 1) * $tileSpace);

        $imagickDraw->push();
        $imagickDraw->translate($width/2 , $height/2);
        $imagickDraw->setFillColor('rgba(0, 0, 0, 0)');
        $imagickDraw->setStrokeColor('white');
        $imagickDraw->circle(0, 0, $radius - 1, 0);
        $imagickDraw->setStrokeColor('black');
        $imagickDraw->circle(0, 0, $radius, 0);
        $imagickDraw->pop();

        $canvasWidth = $width + (2 * $imageMargin);
        $canvasHeight = $height + (2 * $imageMargin);

        $kernel = new \Imagick();
        $kernel->newPseudoImage(
            $canvasWidth,
            $canvasHeight,
            'canvas:none'
        );

        $kernel->setImageFormat('png');
        $kernel->drawImage($imagickDraw);

        /* crear una sombra paralela en su propia capa */
        $canvas = $kernel->clone();
        $canvas->setImageBackgroundColor(new \ImagickPixel('rgb(0, 0, 0)'));
        $canvas->shadowImage(100, $shadowSigma, $shadowDropX, $shadowDropY);

        $canvas->setImagePage($canvasWidth, $canvasHeight, -5, -5);
        $canvas->cropImage($canvasWidth, $canvasHeight, 0, 0);

        /* composite original text_layer onto shadow_layer */
        $canvas->compositeImage($kernel, \Imagick::COMPOSITE_OVER, 0, 0);
        $canvas->setImageFormat('png');

        return $canvas;
    }

    function createFromMatrix() {
        $matrix = [
            [0.5, 0, 0.2],
            [0, 1, 0],
            [0.9, 0, false],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix);

        return $kernel;
    }

    function fromMatrix() {
        $kernel = createFromMatrix();
        $imagick = renderKernel($kernel);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickKernel::getMatrix

(PECL imagick >= 3.3.0)

ImagickKernel::getMatrix — Devuelve la matriz 2D de los valores utilizados en este núcleo

### Descripción

public function ImagickKernel::getMatrix(): array

Devuelve la matriz 2D de los valores utilizados en este núcleo. Los elementos son flotantes para los elementos que son utilizados, o 'false' si el elemento debe ser ignorado.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Una matriz (array 2D) de los valores que representan el núcleo.

### Ejemplos

Ejemplo #1 ImagickKernel::getMatrix()

    <?php

    function renderKernelTable($matrix) {
        $output = "<table class='infoTable'>";

        foreach ($matrix as $row) {
            $output .= "<tr>";
            foreach ($row as $cell) {
                $output .= "<td style='text-align:left'>";
                if ($cell === false) {
                    $output .= "false";
                }
                else {
                    $output .= round($cell, 3);
                }
                $output .= "</td>";
            }
            $output .= "</tr>";
        }

        $output .= "</table>";

        return $output;
    }

        $output = "El nombre de núcleo interno 'ring' con parámetros de '2,3.5':<br/>";
        $kernel = \ImagickKernel::fromBuiltIn(
            \Imagick::KERNEL_RING,
            "2,3.5"
        );
        $matrix = $kernel->getMatrix();
        $output .= renderKernelTable($matrix);

        echo $output;

    ?>

# ImagickKernel::scale

(PECL imagick >= 3.3.0)

ImagickKernel::scale — Redimensiona una lista de núcleos por la cantidad dada

### Descripción

public function ImagickKernel::scale(float `$scale`, int `$normalizeFlag` = ?): void

Redimensiona la lista de núcleos dada por la cantidad dada, con o sin normalización de la suma de los valores del núcleo (según los indicadores dados). El comportamiento exacto de esta función depende del tipo de normalización utilizado consúltense http://www.imagemagick.org/api/morphology.php#ScaleKernelInfo para más detalles.

### Parámetros

`scale`

`normalizeFlag`

  - Imagick::NORMALIZE_KERNEL_NONE
  - Imagick::NORMALIZE_KERNEL_VALUE
  - Imagick::NORMALIZE_KERNEL_CORRELATE
  - Imagick::NORMALIZE_KERNEL_PERCENT

### Valores devueltos

### Ejemplos

Ejemplo #1 ImagickKernel::scale()

    <?php

        function renderKernelTable($matrix) {
            $output = "<table class='infoTable'>";

            foreach ($matrix as $row) {
                $output .= "<tr>";
                foreach ($row as $cell) {
                    $output .= "<td style='text-align:left'>";
                    if ($cell === false) {
                        $output .= "false";
                    }
                    else {
                        $output .= round($cell, 3);
                    }
                    $output .= "</td>";
                }
                $output .= "</tr>";
            }

            $output .= "</table>";

            return $output;
        }

        $output = "";

        $matrix = [
            [-1, 0, -1],
            [ 0, 4,  0],
            [-1, 0, -1],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix);
        $kernelClone = clone $kernel;

        $output .= "Núcleo inicial<br/>";
        $output .= renderKernelTable($kernel->getMatrix());

        $output .= "Redimensionamiento con NORMALIZE_KERNEL_VALUE. El  <br/>";
        $kernel->scale(2, \Imagick::NORMALIZE_KERNEL_VALUE);
        $output .= renderKernelTable($kernel->getMatrix());

        $kernel = clone $kernelClone;
        $output .= "Redimensionamiento por porcentaje<br/>";
        $kernel->scale(2, \Imagick::NORMALIZE_KERNEL_PERCENT);
        $output .= renderKernelTable($kernel->getMatrix());

        $matrix2 = [
            [-1, -1, 1],
            [ -1, false,  1],
            [1, 1, 1],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix2);
        $output .= "Redimensionamiento por correlación<br/>";
        $kernel->scale(1, \Imagick::NORMALIZE_KERNEL_CORRELATE);
        $output .= renderKernelTable($kernel->getMatrix());

        return $output;
    ?>

# ImagickKernel::separate

(PECL imagick >= 3.3.0)

ImagickKernel::separate — Separa un conjunto de núcleos vinculados y devuelve un array de ImagickKernels

### Descripción

public function ImagickKernel::separate(): array

Separa un conjunto de núcleos vinculados y devuelve un array de ImagickKernels.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

### Ejemplos

Ejemplo #1 ImagickKernel::separate()

    <?php

        function renderKernelTable($matrix) {

            $output = "<table class='infoTable'>";
            foreach ($matrix as $row) {
                $output .= "<tr>";
                foreach ($row as $cell) {
                    $output .= "<td style='text-align:left'>";
                    if ($cell === false) {
                        $output .= "false";
                    }
                    else {
                        $output .= round($cell, 3);
                    }
                    $output .= "</td>";
                }
                $output .= "</tr>";
            }

            $output .= "</table>";

            return $output;
        }

        $matrix = [
            [-1, 0, -1],
            [ 0, 4,  0],
            [-1, 0, -1],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix);
        $kernel->scale(4, \Imagick::NORMALIZE_KERNEL_VALUE);
        $diamondKernel = \ImagickKernel::fromBuiltIn(
            \Imagick::KERNEL_DIAMOND,
            "2"
        );

        $kernel->addKernel($diamondKernel);

        $kernelList = $kernel->separate();

        $output = '';
        $count = 0;
        foreach ($kernelList as $kernel) {
            $output .= "<br/>Kernel $count<br/>";
            $output .= renderKernelTable($kernel->getMatrix());
            $count++;
        }

        return $output;

    ?>

## Tabla de contenidos

- ImagickKernel::addKernel — Adjunta otro núcleo a una lista de núcleos
- ImagickKernel::addUnityKernel — Añade un núcleo Unity a la lista de núcleos
- ImagickKernel::fromBuiltIn — Crear un núcleo a partir de un núcleo integrado
- ImagickKernel::fromMatrix — Crear un núcleo a partir de una matriz 2D de valores
- ImagickKernel::getMatrix — Devuelve la matriz 2D de los valores utilizados en este núcleo
- ImagickKernel::scale — Redimensiona una lista de núcleos por la cantidad dada
- ImagickKernel::separate — Separa un conjunto de núcleos vinculados y devuelve un array de ImagickKernels

# La clase ImagickKernelException

(PECL imagick 3)

## Introducción

## Sinopsis de la Clase

class ImagickKernelException extends Exception {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
/* Métodos heredados */
}

# La clase ImagickPixel

(PECL imagick 2, PECL imagick 3)

## Sinopsis de la Clase

class ImagickPixel {
public function clear(): bool
public function __construct(string `$color` = ?)
public function destroy(): bool
public function getColor(int `$normalized` = 0): array
public function getColorAsString(): string
public function getColorCount(): int
public function getColorQuantum(): array
public function getColorValue(int `$color`): float
public function getColorValueQuantum(int `$color`): int|float
public function getHSL(): array
public function getIndex(): int
public function isPixelSimilar(ImagickPixel `$color`, float `$fuzz`): bool
public function isPixelSimilarQuantum(string `$color`, string `$fuzz` = ?): bool
public function isSimilar(ImagickPixel `$color`, float `$fuzz`): bool
public function setColor(string `$color`): bool
public function setcolorcount(int `$colorCount`): bool
public function setColorValue(int `$color`, float `$value`): bool
public function setColorValueQuantum(int `$color`, int|float `$value`): bool
public function setHSL(float `$hue`, float `$saturation`, float `$luminosity`): bool
public function setIndex(int `$index`): bool
}

# ImagickPixel::clear

(PECL imagick 2, PECL imagick 3)

ImagickPixel::clear — Elimina todos los recursos asociados con el objeto

### Descripción

public function ImagickPixel::clear(): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Elimina el objeto ImagickPixel, dejándolo en un estado inicial. Asimismo, elimina todos los colores asociados con el objeto.

### Valores devueltos

Devuelve `true` en caso de éxito.

# ImagickPixel::__construct

(PECL imagick 2, PECL imagick 3)

ImagickPixel::__construct — El constructor ImagickPixel

### Descripción

public function ImagickPixel::__construct(string `$color` = ?)
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Construye un objeto ImagickPixel. Si se especifica un color, el objeto se construye, luego se inicializa con ese color antes de ser devuelto.

### Parámetros

`color`

  Una cadena que representa el color opcional a utilizar como valor inicial del objeto.

### Valores devueltos

Devuelve un objeto ImagickPixel en caso de éxito o lanza una excepción ImagickPixelException si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickPixel::construct()

    <?php
    function construct() {

        $columns = 4;

        $exampleColors = array(
            "rgba(100%, 0%, 0%, 0.5)",
            "hsb(33.3333%, 100%,  75%)", // verde medio
            "hsl(120, 255,   191.25)", //verde medio
            "graya(50%, 0.5)", // gris medio, semi-transparente
            "LightCoral", "none", //"cmyk(0.9, 0.48, 0.83, 0.50)",
            "#f00", //  #rgb
            "#ff0000", //  #rrggbb
            "#ff0000ff", //  #rrggbbaa
            "#ffff00000000", //  #rrrrggggbbbb
            "#ffff00000000ffff", //  #rrrrggggbbbbaaaa
            "rgb(255, 0, 0)", //  un entero en el rango 0—255 para cada componente
            "rgb(100.0%, 0.0%, 0.0%)", //  un valor de punto flotante, en el rango 0—100% para cada componente
            "rgb(255, 0, 0)", //  rango 0 - 255
            "rgba(255, 0, 0, 1.0)", //  lo mismo, pero con un valor alpha explícito
            "rgb(100%, 0%, 0%)", //  rango 0.0% - 100.0%
            "rgba(100%, 0%, 0%, 1.0)", //  lo mismo, pero con un valor alpha explícito
        );

        $draw = new \ImagickDraw();
        $count = 0;
        $black = new \ImagickPixel('rgb(0, 0, 0)');

        foreach ($exampleColors as $exampleColor) {
            $color = new \ImagickPixel($exampleColor);

            $draw->setstrokewidth(1.0);
            $draw->setStrokeColor($black);
            $draw->setFillColor($color);
            $offsetX = ($count % $columns) * 50 + 5;
            $offsetY = intval($count / $columns) * 50 + 5;
            $draw->rectangle(0 + $offsetX, 0 + $offsetY, 40 + $offsetX, 40 + $offsetY);
            $count++;
        }

        $image = new \Imagick();
        $image->newImage(350, 350, "blue");
        $image->setImageFormat("png");
        $image->drawImage($draw);
        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickPixel::destroy

(PECL imagick 2, PECL imagick 3)

ImagickPixel::destroy — Libera los recursos asociados con el objeto

### Descripción

public function ImagickPixel::destroy(): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Libera todos los recursos utilizados por el objeto ImagickPixel y elimina todos los colores asociados. El objeto no debe ser utilizado tras la llamada a esta función.

### Valores devueltos

Devuelve `true` en caso de éxito.

# ImagickPixel::getColor

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getColor — Devuelve el color

### Descripción

public function ImagickPixel::getColor(int `$normalized` = 0): array

Devuelve el color descrito por el objeto ImagickPixel, en forma de un array. Si el color contiene un canal de opacidad, este será proporcionado como cuarta valor de la lista.

### Parámetros

`normalized`

  Normaliza los valores de color. Los valores posibles son `0`, `1` o `2`.

  Lista de valores posibles para `normalized`
  `normalized` | Descripción
  --- | ---
  `0` | Los valores RGB son devueltos como ints en el intervalo (inclusivo) `0` a `255`. El valor alpha es devuelto como int y es `0` o `1`.
  `1` | Los valores RGBA son devueltos como floats en el intervalo (inclusivo) `0` a `1`.
  `2` | Los valores RGBA son devueltos como ints en el intervalo (inclusivo) `0` a `255`.

### Valores devueltos

Un array de los valores de los canales. Genera ImagickPixelException en caso de error.

### Ejemplos

Ejemplo #1 Uso simple del método Imagick::getColor()

    <?php

    // Crea un objeto ImagickPixel con el color predeterminado 'marron'
    $color = new ImagickPixel('brown');

    // Define el color para tener un canal alpha del 25%
    $color->setColorValue(Imagick::COLOR_ALPHA, 64 / 256.0);

    $colorInfo = $color->getColor();

    echo "Valores estándar :".PHP_EOL;
    print_r($colorInfo);

    $colorInfo = $color->getColor(1);

    echo "Valores normalizados :".PHP_EOL;
    print_r($colorInfo);

    ?>

El ejemplo anterior mostrará:

    Valores estándar :
    Array
    (
        [r] => 165
        [g] => 42
        [b] => 42
        [a] => 0
    )
    Valores normalizados :
    Array
    (
        [r] => 0.64705882352941
        [g] => 0.16470588235294
        [b] => 0.16470588235294
        [a] => 0.25000381475547
    )

# ImagickPixel::getColorAsString

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

ImagickPixel::getColorAsString — Devuelve un color

### Descripción

public function ImagickPixel::getColorAsString(): string

Devuelve el color del objeto ImagickPixel, en forma de string.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el color del objeto ImagickPixel, en forma de string.

### Ejemplos

Ejemplo #1 Uso básico del método Imagick::getColorAsString()

    <?php

    //Crea un objeto ImagickPixel con el color predefinido 'marron'
    $color = new ImagickPixel('brown');

    $color->setColorValue(Imagick::COLOR_ALPHA, 64 / 256.0);

    $colorInfo = $color->getColorAsString();

    print_r($colorInfo);
    ?>

El ejemplo anterior mostrará:

    rgb(165,42,42)

### Notas

> Nota: Alpha no devuelto

> Este método no devuelve el valor del alpha del color en la cadena.

# ImagickPixel::getColorCount

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getColorCount — Devuelve el número de colores asociados con un color

### Descripción

public function ImagickPixel::getColorCount(): int

Devuelve el número de colores asociados con el color.

El número de píxeles de la imagen que tienen el mismo color que este ImagickPixel.

ImagickPixel::getColorCount parece funcionar únicamente para los objetos ImagickPixel creados mediante Imagick::getImageHistogram()

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el número de colores, en forma de int en caso de éxito o lanza una excepción ImagickPixelException si ocurre un error.

### Ejemplos

Ejemplo #1 ImagickPixel getColorCount()

    <?php
        $imagick = new \Imagick();
        $imagick->newPseudoImage(640, 480, "magick:logo");
        $histogramElements = $imagick->getImageHistogram();
        $lastColor = array_pop($histogramElements);
        echo "Last pixel color count is: ".$lastColor->getColorCount();
    ?>

La salida para esto será similar a:

    Last pixel color count is: 256244

# ImagickPixel::getColorQuantum

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

ImagickPixel::getColorQuantum — Devuelve el color del píxel en un array como valores cuánticos

### Descripción

public function ImagickPixel::getColorQuantum(): array

Devuelve el color del píxel en un array como valores cuánticos. Si ImageMagick ha sido compilado como HDRI, estos valores serán floats, de lo contrario serán integers.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array con las claves `"r"`, `"g"`, `"b"`, `"a"`.

# ImagickPixel::getColorValue

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getColorValue — Obtiene el valor normalizado del canal de color proporcionado

### Descripción

public function ImagickPixel::getColorValue(int `$color`): float

Obtiene el valor del canal de color especificado, en forma de número de punto flotante comprendido entre 0 y 1.

### Parámetros

`color`

  El color para el cual se obtendrá el valor, especificado en forma de constante de colores Imagick. Puede ser colores RGB, colores CMYK, alpha y opacidad, i.e. Imagick::COLOR_BLUE o Imagick::COLOR_MAGENTA.

### Valores devueltos

El valor del canal, en forma de número de punto flotante normalizado, o lanza una excepción ImagickPixelException si ocurre un error.

### Ejemplos

Ejemplo #1 Uso básico del método Imagick::getColorValue()

    <?php

    $color = new ImagickPixel('rgba(90%, 20%, 20%, 0.75)');

    echo "El valor alpha es ".$color->getColorValue(Imagick::COLOR_ALPHA).PHP_EOL;
    echo "".PHP_EOL;
    echo "El valor rojo es ".$color->getColorValue(Imagick::COLOR_RED).PHP_EOL;
    echo "El valor verde es ".$color->getColorValue(Imagick::COLOR_GREEN).PHP_EOL;
    echo "El valor azul es ".$color->getColorValue(Imagick::COLOR_BLUE).PHP_EOL;
    echo "".PHP_EOL;
    echo "El valor Cian es ".$color->getColorValue(Imagick::COLOR_CYAN).PHP_EOL;
    echo "El valor Magenta es ".$color->getColorValue(Imagick::COLOR_MAGENTA).PHP_EOL;
    echo "El valor amarillo es ".$color->getColorValue(Imagick::COLOR_YELLOW).PHP_EOL;
    echo "El valor negro es ".$color->getColorValue(Imagick::COLOR_BLACK).PHP_EOL;

    ?>

El ejemplo anterior mostrará:

    El valor alpha es 0.74999618524453

    El valor rojo es 0.90000762951095
    El valor verde es 0.2
    El valor azul es 0.2

    El valor Cian es 0.90000762951095
    El valor Magenta es 0.2
    El valor amarillo es 0.2
    El valor negro es 0

# ImagickPixel::getColorValueQuantum

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickPixel::getColorValueQuantum — Devuelve el valor cuántico de un color en ImagickPixel

### Descripción

public function ImagickPixel::getColorValueQuantum(int `$color`): int|float

Devuelve el valor cuántico de un color en ImagickPixel. El valor de retorno es un float si ImageMagick ha sido compilado con HDRI, de lo contrario un integer.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El valor cuántico del elemento de color. Float si ImageMagick ha sido compilado con HDRI, de lo contrario un integer.

### Ejemplos

Ejemplo #1 ImagickPixel::getColorValueQuantum()

    <?php
            $color = new \ImagickPixel('rgb(128, 5, 255)');
            $colorRed = $color->getColorValueQuantum(\Imagick::COLOR_RED);
            $colorGreen = $color->getColorValueQuantum(\Imagick::COLOR_GREEN);
            $colorBlue = $color->getColorValueQuantum(\Imagick::COLOR_BLUE);
            $colorAlpha = $color->getColorValueQuantum(\Imagick::COLOR_ALPHA);

            printf(
                "Red: %s Green: %s  Blue %s Alpha: %s",
                $colorRed,
                $colorGreen,
                $colorBlue,
                $colorAlpha
            );

    ?>

# ImagickPixel::getHSL

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getHSL — Retorna el color HSL normalizado del objeto ImagickPixel

### Descripción

public function ImagickPixel::getHSL(): array

Retorna el color HSL normalizado, descrito por el objeto ImagickPixel, donde cada una de las tres valores será un número decimal, comprendido entre 0.0 y 1.0.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Retorna el valor HSL en un array que contiene las claves `"hue"`, `"saturation"` y `"luminosity"`. Genera una excepción ImagickPixelException en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::getHSL()

    <?php

    $color = new ImagickPixel('rgb(90%, 10%, 10%)');

    $colorInfo = $color->getHSL();

    print_r($colorInfo);

    ?>

El ejemplo anterior mostrará:

    Array
    (
        [hue] => 0
        [saturation] => 0.80001220740379
        [luminosity] => 0.50000762951095
    )

### Notas

> Nota:

> Disponible a partir de la versión 6.2.9 y superior de la biblioteca ImageMagick.

# ImagickPixel::getIndex

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickPixel::getIndex — Devuelve el índice de la tabla de colores del píxel

### Descripción

public function ImagickPixel::getIndex(): int

Devuelve el índice de la tabla de colores del píxel.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

# ImagickPixel::isPixelSimilar

(PECL imagick 3 >= 3.3.0)

ImagickPixel::isPixelSimilar — Verifica la distancia entre este color y otro

### Descripción

public function ImagickPixel::isPixelSimilar(ImagickPixel `$color`, float `$fuzz`): bool

Verifica la distancia entre el color descrito por este objeto ImagickPixel y el del objeto proporcionado. Si la distancia entre los dos puntos es inferior al valor del argumento fuzz proporcionado, el color es similar. Este método reemplaza al método ImagickPixel::isSimilar() y normaliza correctamente el valor fuzz de ImageMagick QuantumRange.

### Parámetros

`color`

  El objeto ImagickPixel a utilizar para la comparación.

`fuzz`

  La distancia máxima para la cual se consideran los colores como similares. El valor máximo teórico para este argumento es la raíz cuadrada de tres (1.732).

### Valores devueltos

Devuelve `true` en caso de éxito.

# ImagickPixel::isPixelSimilarQuantum

(PECL imagick 3 >= 3.3.0)

ImagickPixel::isPixelSimilarQuantum — Indica si dos colores difieren en menos de la distancia especificada

### Descripción

public function ImagickPixel::isPixelSimilarQuantum(string `$color`, string `$fuzz` = ?): bool

Indica si dos colores difieren en menos de la distancia especificada. El valor de flou debe estar comprendido entre 0 y QuantumRange. El valor máximo representa la distancia más larga posible en el espacio colorimétrico. Por ejemplo, de RGB(0, 0, 0) a RGB(255, 255, 255) para el espacio colorimétrico RGB

### Parámetros

`color`

`fuzz`

### Valores devueltos

# ImagickPixel::isSimilar

(PECL imagick 2, PECL imagick 3)

ImagickPixel::isSimilar — Verifica la distancia entre 2 colores

### Descripción

public function ImagickPixel::isSimilar(ImagickPixel `$color`, float `$fuzz`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Verifica la distancia entre la color descrita por el objeto ImagickPixel y la del objeto proporcionado, colocando sus valores RGB en el cubo de color. Si la distancia entre los 2 puntos es inferior al valor del argumento `fuzz`, la color es similar. Obsoleto en favor del método ImagickPixel::isPixelSimilar().

### Parámetros

`color`

  El objeto ImagickPixel utilizado para la comparación.

`fuzz`

  La distancia máxima utilizada para considerar que los colores son similares. El valor máximo teórico es la raíz cuadrada de 3 (1.732).

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickPixel::isSimilar()

    <?php
            // La prueba a continuación fue escrita con una distancia máxima de 255,
            // por lo tanto, debemos escalarla con una raíz cuadrada de 3 -
            // la longitud de la diagonal de un cubo.
            $root3 = 1.732050807568877;

            $tests = array(
                ['rgb(245, 0, 0)',      'rgb(255, 0, 0)',   9 / $root3,         false,],
                ['rgb(245, 0, 0)',      'rgb(255, 0, 0)',  10 / $root3,         true,],
                ['rgb(0, 0, 0)',        'rgb(7, 7, 0)',     9 / $root3,         false,],
                ['rgb(0, 0, 0)',        'rgb(7, 7, 0)',    10 / $root3,         true,],
                ['rgba(0, 0, 0, 1)',    'rgba(7, 7, 0, 1)', 9 / $root3,         false,],
                ['rgba(0, 0, 0, 1)',    'rgba(7, 7, 0, 1)',    10 / $root3,     true,],
                ['rgb(128, 128, 128)',  'rgb(128, 128, 120)',   7 / $root3,     false,],
                ['rgb(128, 128, 128)',  'rgb(128, 128, 120)',   8 / $root3,     true,],
                ['rgb(0, 0, 0)',        'rgb(255, 255, 255)',   254.9,          false,],
                ['rgb(0, 0, 0)',        'rgb(255, 255, 255)',   255,            true,],
                ['rgb(255, 0, 0)',      'rgb(0, 255, 255)',     254.9,          false,],
                ['rgb(255, 0, 0)',      'rgb(0, 255, 255)',     255,            true,],
                ['black',               'rgba(0, 0, 0)',        0.0,            true],
                ['black',               'rgba(10, 0, 0, 1.0)',  10.0 / $root3,  true],);

            $output = "<table width='100%' class='infoTable'><thead>
                    <tr>
                    <th>
                    Color 1
                    </th>
                    <th>
                    Color 2
                    </th>
                    <th>
                        Test distance * 255
                    </th>
                    <th>
                        Is within distance
                    </th>
                    </tr>
            </thead>";

            $output .= "<tbody>";

            foreach ($tests as $testInfo) {
                $color1 = $testInfo[0];
                $color2 = $testInfo[1];
                $distance = $testInfo[2];
                $expectation = $testInfo[3];
                $testDistance = ($distance / 255.0);

                $color1Pixel = new \ImagickPixel($color1);
                $color2Pixel = new \ImagickPixel($color2);

                $isSimilar = $color1Pixel->isPixelSimilar($color2Pixel, $testDistance);

                if ($isSimilar !== $expectation) {
                    echo "Test distance failed. Color [$color1] compared to color [$color2] is not within distance $testDistance FAILED.".NL;
                }

                $layout = "<tr>
                    <td>%s</td>
                    <td>%s</td>
                    <td>%s</td>
                    <td style='text-align: center;'>%s</td>
                </tr>";

                $output .= sprintf(
                    $layout,
                    $color1,
                    $color2,
                    $distance,
                    $isSimilar ? 'yes' : 'no'
                );
            }

            $output .= "</tbody></table>";

            return $output;

    ?>

# ImagickPixel::setColor

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setColor — Define la color

### Descripción

public function ImagickPixel::setColor(string `$color`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Define la color, descrita por el objeto ImagickPixel, con un string (por ejemplo, `"blue"`, `"#0000ff"`, `"rgb(0,0,255)"`, `"cmyk(100,100,100,10)"`, etc.).

### Parámetros

`color`

  La definición de la color a utilizar para inicializar el objeto ImagickPixel.

### Valores devueltos

Retorna `true` si la color especificada ha sido definida o `false` en caso contrario.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickPixel::setColor()

    <?php
    function setColor() {
        $draw = new \ImagickDraw();

        $strokeColor = new \ImagickPixel('green');
        $fillColor = new \ImagickPixel();
        $fillColor->setColor('rgba(100%, 75%, 0%, 1.0)');

        $draw->setstrokewidth(3.0);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->rectangle(200, 200, 300, 300);

        $image = new \Imagick();
        $image->newImage(500, 500, "SteelBlue2");
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickPixel::setColorCount

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setColorCount — Define la cantidad de colores asociada a este píxel

### Descripción

public function ImagickPixel::setcolorcount(int `$colorCount`): bool

Define la cantidad de colores asociada a este píxel.

### Parámetros

`colorCount`

### Valores devueltos

Devuelve `true` en caso de éxito.

# ImagickPixel::setColorValue

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setColorValue — Define el valor normalizado de uno de los canales

### Descripción

public function ImagickPixel::setColorValue(int `$color`, float `$value`): bool

Define el valor del canal especificado del objeto al valor especificado, que debe estar comprendido entre 0 y 1. Esta función puede ser utilizada para proporcionar un canal de opacidad al objeto ImagickPixel.

### Parámetros

`color`

  Una constante de color Imagick, i.e. \Imagick::COLOR_GREEN o \Imagick::COLOR_ALPHA.

`value`

  El valor a definir para este canal, comprendido entre 0 y 1.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo con Imagick::setColorValue()

    <?php

    $color  = new \ImagickPixel('firebrick');

    $color->setColorValue(Imagick::COLOR_ALPHA, 0.5);

    print_r($color->getcolor(true));
    ?>

El ejemplo anterior mostrará:

    Array
    (
        [r] => 0.69803921568627
        [g] => 0.13333333333333
        [b] => 0.13333333333333
        [a] => 0.50000762951095
    )

# ImagickPixel::setColorValueQuantum

(PECL imagick 2 >=2.3.0, PECL imagick 3)

ImagickPixel::setColorValueQuantum — Define la valor cuántica de un elemento de color de ImagickPixel

### Descripción

public function ImagickPixel::setColorValueQuantum(int `$color`, int|float `$value`): bool

Define la valor cuántica de un elemento de color de ImagickPixel.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`color`

  Color a definir, por ejemplo \Imagick::COLOR_GREEN.

`value`

  Valor cuántica a definir para el elemento de color. Debería ser un float si ImageMagick ha sido compilado con HDRI, de lo contrario un integer en el rango 0 a Imagick::getQuantum().

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 ImagickPixel::setColorValueQuantum()

    <?php
    function setColorValueQuantum() {
        $image = new \Imagick();

        $quantumRange = $image->getQuantumRange();

        $draw = new \ImagickDraw();
        $color = new \ImagickPixel('blue');
        $color->setcolorValueQuantum(\Imagick::COLOR_RED, 128 * $quantumRange['quantumRangeLong'] / 256);

        $draw->setstrokewidth(1.0);
        $draw->setStrokeColor($color);
        $draw->setFillColor($color);
        $draw->rectangle(200, 200, 300, 300);

        $image->newImage(500, 500, "SteelBlue2");
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickPixel::setHSL

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setHSL — Define el color HSL normalizado

### Descripción

public function ImagickPixel::setHSL(float `$hue`, float `$saturation`, float `$luminosity`): bool

Define el color descrito por el objeto ImagickPixel utilizando los valores normalizados para la densidad, la saturación y la luminosidad.

### Parámetros

`hue`

  El valor normalizado para la densidad, descrito por un arco fraccionario (entre 0 y 1) del círculo de densidad, cuyo valor cero corresponde a rojo.

`saturation`

  El valor normalizado para la saturación, donde 1 corresponde a una saturación completa.

`luminosity`

  El valor normalizado para la luminosidad, comprendido entre 0 (negro) y 1 (blanco), con el valor HS completo a 0.5 de luminosidad.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickPixel::setHSL() para modificar un color

    <?php

    // Crea un rojo puro
    $color = new ImagickPixel('rgb(90%, 10%, 10%)');

    // Obtiene sus valores HSL
    $colorInfo = $color->getHSL();

    // Realiza una rotación del tono de 180 grados
    $newHue = $colorInfo['hue'] + 0.5;
    if ($newHue > 1) {
        $newHue = $newHue - 1;
    }

    // Define el objeto ImagickPixel al nuevo color
    $colorInfo = $color->setHSL($newHue, $colorInfo['saturation'], $colorInfo['luminosity']);

    // Verifica que el nuevo color sea azul/verde
    $colorInfo = $color->getcolor();
    print_r($colorInfo);

    ?>

El ejemplo anterior mostrará:

    Array
    (
        [r] => 26
        [g] => 230
        [b] => 230
        [a] => 255
    )

### Notas

> Nota:

> Disponible a partir de la versión 6.2.9 de la biblioteca ImageMagick.

# ImagickPixel::setIndex

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickPixel::setIndex — Define el índice de la tabla de colores del píxel

### Descripción

public function ImagickPixel::setIndex(int `$index`): bool

Define el índice de la tabla de colores del píxel.

### Parámetros

`index`

### Valores devueltos

Devuelve `true` en caso de éxito.

## Tabla de contenidos

- ImagickPixel::clear — Elimina todos los recursos asociados con el objeto
- ImagickPixel::__construct — El constructor ImagickPixel
- ImagickPixel::destroy — Libera los recursos asociados con el objeto
- ImagickPixel::getColor — Devuelve el color
- ImagickPixel::getColorAsString — Devuelve un color
- ImagickPixel::getColorCount — Devuelve el número de colores asociados con un color
- ImagickPixel::getColorQuantum — Devuelve el color del píxel en un array como valores cuánticos
- ImagickPixel::getColorValue — Obtiene el valor normalizado del canal de color proporcionado
- ImagickPixel::getColorValueQuantum — Devuelve el valor cuántico de un color en ImagickPixel
- ImagickPixel::getHSL — Retorna el color HSL normalizado del objeto ImagickPixel
- ImagickPixel::getIndex — Devuelve el índice de la tabla de colores del píxel
- ImagickPixel::isPixelSimilar — Verifica la distancia entre este color y otro
- ImagickPixel::isPixelSimilarQuantum — Indica si dos colores difieren en menos de la distancia especificada
- ImagickPixel::isSimilar — Verifica la distancia entre 2 colores
- ImagickPixel::setColor — Define la color
- ImagickPixel::setColorCount — Define la cantidad de colores asociada a este píxel
- ImagickPixel::setColorValue — Define el valor normalizado de uno de los canales
- ImagickPixel::setColorValueQuantum — Define la valor cuántica de un elemento de color de ImagickPixel
- ImagickPixel::setHSL — Define el color HSL normalizado
- ImagickPixel::setIndex — Define el índice de la tabla de colores del píxel

# La clase ImagickPixelException

(PECL imagick 3)

## Introducción

## Sinopsis de la Clase

class ImagickPixelException extends Exception implements Throwable {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
/* Métodos heredados */
}

# La clase ImagickPixelIterator

(PECL imagick 2, PECL imagick 3)

## Sinopsis de la Clase

class ImagickPixelIterator {
public function clear(): bool
public function __construct(Imagick `$wand`)
public function destroy(): bool
public function getCurrentIteratorRow(): array
public function getIteratorRow(): int
public function getNextIteratorRow(): array
public function getPreviousIteratorRow(): array
public function newPixelIterator(Imagick `$wand`): bool
public function newPixelRegionIterator(
Imagick `$wand`,
int `$x`,
int `$y`,
int `$columns`,
int `$rows`
): bool
public function resetIterator(): bool
public function setIteratorFirstRow(): bool
public function setIteratorLastRow(): bool
public function setIteratorRow(int `$row`): bool
public function syncIterator(): bool
}

# ImagickPixelIterator::clear

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::clear — Elimina todos los recursos asociados a PixelIterator

### Descripción

public function ImagickPixelIterator::clear(): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Elimina todos los recursos asociados a PixelIterator.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickPixelIterator::clear()

    <?php
    function clear($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));

        $imageIterator = $imagick->getPixelRegionIterator(100, 100, 250, 200);

        /* Se recorren las líneas de píxeles */
        foreach ($imageIterator as $pixels) {
            /** @var $pixel \ImagickPixel */
            /* Se recorren los píxeles de la línea (columna) */
            foreach ($pixels as $column => $pixel) {
                if ($column % 2) {
                    /* Pintar cada segundo píxel de negro */
                    $pixel->setColor("rgba(0, 0, 0, 0)");
                }
            }
            /* Se sincroniza el iterador, esto es importante en cada iteración */
            $imageIterator->syncIterator();
        }

        $imageIterator->clear();

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# ImagickPixelIterator::__construct

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::__construct — El constructor de la clase ImagickPixelIterator

### Descripción

public function ImagickPixelIterator::__construct(Imagick `$wand`)
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

El constructor de la clase ImagickPixelIterator.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickPixelIterator::construct()

    <?php
    function construct($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imageIterator = new \ImagickPixelIterator($imagick);

        /* Se recorren las líneas de píxeles */
        foreach ($imageIterator as $pixels) {
            /* Se recorren los píxeles de la línea (columna) */
            foreach ($pixels as $column => $pixel) {
                /** @var $pixel \ImagickPixel */
                if ($column % 2) {
                    /* Se tiñen todos los dos píxeles en negro */
                    $pixel->setColor("rgba(0, 0, 0, 0)");
                }
            }
            /* Se sincroniza el iterador, esto es importante en cada iteración */
            $imageIterator->syncIterator();
        }

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# ImagickPixelIterator::destroy

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::destroy — Libera los recursos asociados a PixelIterator

### Descripción

public function ImagickPixelIterator::destroy(): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Libera los recursos asociados a PixelIterator.

### Valores devueltos

Devuelve `true` en caso de éxito.

# ImagickPixelIterator::getCurrentIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getCurrentIteratorRow — Devuelve la fila actual de los objetos ImagickPixel

### Descripción

public function ImagickPixelIterator::getCurrentIteratorRow(): array
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve la fila actual, en forma de array, de los objetos ImagickPixel desde el iterador de píxeles.

### Valores devueltos

Devuelve una fila, en forma de array, de los objetos ImagickPixel, que puede ser iterada a su vez.

# ImagickPixelIterator::getIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getIteratorRow — Devuelve la fila actual del iterador de píxeles

### Descripción

public function ImagickPixelIterator::getIteratorRow(): int
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve la fila actual del iterador de píxeles.

### Valores devueltos

Devuelve la posición, en forma de int de la fila o lanza una excepción ImagickPixelIteratorException en caso de error.

# ImagickPixelIterator::getNextIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getNextIteratorRow — Devuelve la siguiente línea del iterador de píxeles

### Descripción

public function ImagickPixelIterator::getNextIteratorRow(): array
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve la siguiente línea, en forma de array, desde el iterador de píxeles.

### Valores devueltos

Devuelve la siguiente línea, en forma de array de objetos ImagickPixel, o lanza una excepción ImagickPixelIteratorException en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickPixelIterator::getNextIteratorRow()

    <?php
    function getNextIteratorRow($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imageIterator = $imagick->getPixelIterator();

        $count = 0;
        while ($pixels = $imageIterator->getNextIteratorRow()) {
            if (($count % 3) == 0) {
                /* Se recorren los píxeles de la línea (columna) */
                foreach ($pixels as $column => $pixel) {
                    /** @var $pixel \ImagickPixel */
                    if ($column % 2) {
                        /* Se tiñen todos los dos píxeles en negro */
                        $pixel->setColor("rgba(0, 0, 0, 0)");
                    }
                }
                /* Se sincroniza el iterador, esto es importante en cada iteración */
                $imageIterator->syncIterator();
            }

            $count += 1;
        }

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# ImagickPixelIterator::getPreviousIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getPreviousIteratorRow — Devuelve la línea anterior

### Descripción

public function ImagickPixelIterator::getPreviousIteratorRow(): array
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve la línea anterior, en forma de array, desde el iterador de píxeles.

### Valores devueltos

Devuelve la línea anterior, en forma de array de objetos ImagickPixelWand, o lanza una excepción ImagickPixelIteratorException en caso de error.

# ImagickPixelIterator::newPixelIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::newPixelIterator — Devuelve un nuevo píxel del iterador

### Descripción

public function ImagickPixelIterator::newPixelIterator(Imagick `$wand`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve un nuevo píxel del iterador.

### Valores devueltos

Devuelve `true` en caso de éxito.. Se lanza una excepción ImagickPixelIteratorException en caso de error.

# ImagickPixelIterator::newPixelRegionIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::newPixelRegionIterator — Devuelve un nuevo iterador de píxeles

### Descripción

public function ImagickPixelIterator::newPixelRegionIterator(
Imagick `$wand`,
int `$x`,
int `$y`,
int `$columns`,
int `$rows`
): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Devuelve un nuevo iterador de píxeles.

### Parámetros

`wand`

`x`

`y`

`columns`

`rows`

### Valores devueltos

Devuelve un nuevo ImagickPixelIterator en caso de éxito o lanza una excepción ImagickPixelIteratorException si ocurre un error.

# ImagickPixelIterator::resetIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::resetIterator — Reinicia el iterador de píxeles

### Descripción

public function ImagickPixelIterator::resetIterator(): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Reinicia el iterador de píxeles. Utilice este método con ImagickPixelIterator::getNextIteratorRow() para iterar sobre todos los píxeles de un contenedor de píxeles.

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickPixelIterator::resetIterator()

    <?php
    function resetIterator($imagePath) {

        $imagick = new \Imagick(realpath($imagePath));

        $imageIterator = $imagick->getPixelIterator();

        /* Se recorren las líneas de píxeles */
        foreach ($imageIterator as $pixels) {
            /* Se recorren los píxeles de la línea (columna) */
            foreach ($pixels as $column => $pixel) {
                /** @var $pixel \ImagickPixel */
                if ($column % 2) {

                    /* Cada dos píxeles, se añade un 25% de rojo */
                    $pixel->setColorValue(\Imagick::COLOR_RED, 64);
                }
            }
            /* Se sincroniza el iterador, esto es importante en cada iteración */
            $imageIterator->syncIterator();
        }

        $imageIterator->resetiterator();

        /* Se recorren las líneas de píxeles */
        foreach ($imageIterator as $pixels) {
            /* Se recorren los píxeles de la línea (columna) */
            foreach ($pixels as $column => $pixel) {
                /** @var $pixel \ImagickPixel */
                if ($column % 3) {
                    $pixel->setColorValue(\Imagick::COLOR_BLUE, 64); /* Cada dos píxeles, se los hace un poco más azules */
                    //$pixel->setColor("rgba(0, 0, 128, 0)"); /* Se tiñen todos los dos píxeles en negro */
                }
            }
            $imageIterator->syncIterator(); /* Se sincroniza el iterador, esto es importante en cada iteración */
        }

        $imageIterator->clear();

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# ImagickPixelIterator::setIteratorFirstRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::setIteratorFirstRow — Establece el iterador de píxeles en la primera línea de píxeles

### Descripción

public function ImagickPixelIterator::setIteratorFirstRow(): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Establece el iterador de píxeles en la primera línea de píxeles.

### Valores devueltos

Devuelve `true` en caso de éxito.

# ImagickPixelIterator::setIteratorLastRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::setIteratorLastRow — Define el iterador de píxeles en la última línea de píxeles

### Descripción

public function ImagickPixelIterator::setIteratorLastRow(): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Define el iterador de píxeles en la última línea de píxeles.

### Valores devueltos

Devuelve `true` en caso de éxito.

# ImagickPixelIterator::setIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::setIteratorRow — Define la línea del iterador de píxeles

### Descripción

public function ImagickPixelIterator::setIteratorRow(int `$row`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Define la línea del iterador de píxeles.

### Parámetros

`row`

### Valores devueltos

Devuelve `true` en caso de éxito.

### Ejemplos

Ejemplo #1 Ejemplo con ImagickPixelIterator::setIteratorRow()

    <?php
    function setIteratorRow($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imageIterator = $imagick->getPixelRegionIterator(200, 100, 200, 200);

        for ($x = 0; $x < 20; $x++) {
            $imageIterator->setIteratorRow($x * 5);
            $pixels = $imageIterator->getCurrentIteratorRow();
            /* Se recorren los píxeles de la línea (columna) */
            foreach ($pixels as $pixel) {
                /** @var $pixel \ImagickPixel */
                /* Se tiñen todos los píxeles en negro */
                $pixel->setColor("rgba(0, 0, 0, 0)");
            }

            /* Se sincroniza el iterador; esto es importante en cada iteración */
            $imageIterator->syncIterator();
        }

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# ImagickPixelIterator::syncIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::syncIterator — Sincroniza el iterador de píxeles

### Descripción

public function ImagickPixelIterator::syncIterator(): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

Sincroniza el iterador de píxeles.

### Valores devueltos

Devuelve `true` en caso de éxito.

## Tabla de contenidos

- ImagickPixelIterator::clear — Elimina todos los recursos asociados a PixelIterator
- ImagickPixelIterator::__construct — El constructor de la clase ImagickPixelIterator
- ImagickPixelIterator::destroy — Libera los recursos asociados a PixelIterator
- ImagickPixelIterator::getCurrentIteratorRow — Devuelve la fila actual de los objetos ImagickPixel
- ImagickPixelIterator::getIteratorRow — Devuelve la fila actual del iterador de píxeles
- ImagickPixelIterator::getNextIteratorRow — Devuelve la siguiente línea del iterador de píxeles
- ImagickPixelIterator::getPreviousIteratorRow — Devuelve la línea anterior
- ImagickPixelIterator::newPixelIterator — Devuelve un nuevo píxel del iterador
- ImagickPixelIterator::newPixelRegionIterator — Devuelve un nuevo iterador de píxeles
- ImagickPixelIterator::resetIterator — Reinicia el iterador de píxeles
- ImagickPixelIterator::setIteratorFirstRow — Establece el iterador de píxeles en la primera línea de píxeles
- ImagickPixelIterator::setIteratorLastRow — Define el iterador de píxeles en la última línea de píxeles
- ImagickPixelIterator::setIteratorRow — Define la línea del iterador de píxeles
- ImagickPixelIterator::syncIterator — Sincroniza el iterador de píxeles

# La clase ImagickPixelIteratorException

(PECL imagick 3)

## Introducción

## Sinopsis de la Clase

class ImagickPixelIteratorException extends Exception implements Throwable {
/* Propiedades heredadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
/* Métodos heredados */
}

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
- Constantes predefinidas
- Ejemplos
  - Uso básico
- Imagick — La clase Imagick
  - Imagick::adaptiveBlurImage — Añade un filtro de borrosidad adaptativo a la imagen
  - Imagick::adaptiveResizeImage — Redimensiona una imagen adaptativamente con información dependiente de la triangulación
  - Imagick::adaptiveSharpenImage — Afila la imagen adaptativamente
  - Imagick::adaptiveThresholdImage — Selecciona un umbral para cada píxel basado en un rango de intensidad
  - Imagick::addImage — Añade una nueva imagen a la lista de imágenes del objeto Imagick
  - Imagick::addNoiseImage — Añade ruido aleatorio a la imagen
  - Imagick::affineTransformImage — Transforma una imagen
  - Imagick::animateImages — Anima una imagen o imágenes
  - Imagick::annotateImage — Anota una imagen con texto
  - Imagick::appendImages — Añade un conjunto de imágenes
  - Imagick::autoLevelImage — Ajusta el nivel de un canal de una imagen particular
  - Imagick::averageImages — Promedio de un conjunto de imágenes
  - Imagick::blackThresholdImage — Fuerza a todos los píxeles bajo un umbral a ser negros
  - Imagick::blueShiftImage — Atenúa los colores de la imagen
  - Imagick::blurImage — Añade un filtro de borrosidad a la imagen
  - Imagick::borderImage — Rodea la imagen con un borde
  - Imagick::brightnessContrastImage — Cambia el brillo y/o el contraste de una imagen
  - Imagick::charcoalImage — Simula un dibujo a carboncillo
  - Imagick::chopImage — Borra una región de una imagen y la recorta
  - Imagick::clampImage — Restringe el rango de colores de 0 a la profundidad cuántica
  - Imagick::clear — Libera todos los recursos asociados a un objeto Imagick
  - Imagick::clipImage — Se alinea con el primer camino de un perfil 8BIM
  - Imagick::clipImagePath — Recorta a lo largo de las rutas nombradas del perfil 8BIM, si está presente
  - Imagick::clipPathImage — Recorta a lo largo de trazados nominados desde un perfil 8BIM
  - Imagick::clone — Realiza una copia exacta de un objeto Imagick
  - Imagick::clutImage — Reemplaza los colores de una imagen
  - Imagick::coalesceImages — Componer un conjunto de imágenes
  - Imagick::colorFloodfillImage — Cambia el valor del color de cualquier píxel que coincida con el objetivo
  - Imagick::colorizeImage — Mezcla el color de relleno con la imagen
  - Imagick::colorMatrixImage — Aplica una transformación de color a una imagen
  - Imagick::combineImages — Combina una o más imágenes en una sóla imagen
  - Imagick::commentImage — Añade un comentario a la imagen
  - Imagick::compareImageChannels — Devuelve la diferencia entre una o más imágenes
  - Imagick::compareImageLayers — Devuelve la región circundante máxima entre imágenes
  - Imagick::compareImages — Compara una imagen con otra reconstruida
  - Imagick::compositeImage — Compone una imagen en otra
  - Imagick::__construct — El constructor Imagick
  - Imagick::contrastImage — Cambia el contraste de una imagen
  - Imagick::contrastStretchImage — Mejora el contraste de una imagen en color
  - Imagick::convolveImage — Aplica una semilla de convolución a medida a la imagen
  - Imagick::count — Devuelve el número de imágenes
  - Imagick::cropImage — Extrae una región de la imagen
  - Imagick::cropThumbnailImage — Crea una miniatura recortada
  - Imagick::current — Devuelve una referencia al objeto Imagick actual
  - Imagick::cycleColormapImage — Desplaza el mapa de colores de una imagen
  - Imagick::decipherImage — Descifra una imagen
  - Imagick::deconstructImages — Devuelve las diferencias de ciertos píxeles entre dos imágenes
  - Imagick::deleteImageArtifact — Borra un artefacto de imagen
  - Imagick::deleteImageProperty — Elimina una propiedad de imagen
  - Imagick::deskewImage — Elimina la torción de la imagen
  - Imagick::despeckleImage — Reduce el ruido speckle de una imagen
  - Imagick::destroy — Destruye un objeto Imagick
  - Imagick::displayImage — Muestra una imagen
  - Imagick::displayImages — Muestra una imagen o una secuencia de imágenes
  - Imagick::distortImage — Deforma una imagen utilizando varios métodos de distorsión
  - Imagick::drawImage — Renderiza el objeto ImagickDraw a la imagen actual
  - Imagick::edgeImage — Mejora los bordes de la imagen
  - Imagick::embossImage — Devuelve una imagen en escala de grises con un efecto tridimensional
  - Imagick::encipherImage — Cifra una imagen
  - Imagick::enhanceImage — Mejora la calidad de una imagen ruidosa
  - Imagick::equalizeImage — Iguala el histograma de una imagen
  - Imagick::evaluateImage — Aplica una expresión a una imagen
  - Imagick::exportImagePixels — Exporta los píxeles brutos de la imagen
  - Imagick::extentImage — Establecer el tamaño de la imagen
  - Imagick::filter — Aplica un núcleo de convolución personalizado a la imagen
  - Imagick::flattenImages — Fusiona una secuencia de imágenes
  - Imagick::flipImage — Crea una imagen por espejo vertical
  - Imagick::floodFillPaintImage — Cambia el valor del color de cualquier píxel que coincida con el objetivo
  - Imagick::flopImage — Crea una imagen por espejo horizontal
  - Imagick::forwardFourierTransformImage — Implementa la transformada discreta de Fourier (Discrete Fourier Transform - DFT)
  - Imagick::frameImage — Añade un borde tridimensional simulado
  - Imagick::functionImage — Aplica una función sobre la imagen
  - Imagick::fxImage — Evalúa una expresión por cada píxel de la imagen
  - Imagick::gammaImage — Corrección gamma de una imagen
  - Imagick::gaussianBlurImage — Hace borrosa una imagen
  - Imagick::getColorspace — Obtiene el espacio de colores
  - Imagick::getCompression — Lee el tipo de compresión
  - Imagick::getCompressionQuality — Lee la calidad de la compresión
  - Imagick::getCopyright — Devuelve el copyright de la API ImageMagick
  - Imagick::getFilename — Lee el nombre del fichero asociado a una secuencia
  - Imagick::getFont — Obtiene la fuente de caracteres
  - Imagick::getFormat — Devuelve el formato de la imagen Imagick
  - Imagick::getGravity — Obtiene la gravedad
  - Imagick::getHomeURL — Devuelve la URL de ImageMagick
  - Imagick::getImage — Devuelve un nuevo objeto Imagick
  - Imagick::getImageAlphaChannel — Verifica si la imagen tiene un canal alfa
  - Imagick::getImageArtifact — Obtener el artefacto de imagen
  - Imagick::getImageAttribute — Obtiene un atributo nombrado
  - Imagick::getImageBackgroundColor — Devuelve el color de fondo
  - Imagick::getImageBlob — Devuelve la secuencia de imágenes como un blob
  - Imagick::getImageBluePrimary — Devuelve el punto primario azul de la cromaticidad
  - Imagick::getImageBorderColor — Devuelve el color del borde de la imagen
  - Imagick::getImageChannelDepth — Obtiene la profundidad de un canal de imagen en particular
  - Imagick::getImageChannelDistortion — Compara los canales de imagen de una imagen con una imagen reconstruida
  - Imagick::getImageChannelDistortions — Obtiene las distorsiones de un canal
  - Imagick::getImageChannelExtrema — Obtiene los extremos de uno o más canales de imagen
  - Imagick::getImageChannelKurtosis — Obtiene la curtosis y la asimetría estadística de un canal específico
  - Imagick::getImageChannelMean — Obtiene la media y la desviación estándar
  - Imagick::getImageChannelRange — Obtiene el rango del canal
  - Imagick::getImageChannelStatistics — Devuelve estadísticas sobre cada canal de la imagen
  - Imagick::getImageClipMask — Obtiene la máscara de recorte de la imagen
  - Imagick::getImageColormapColor — Devuelve el color del índice del mapa de colores especficado
  - Imagick::getImageColors — Lee el número de colores únicos de la imagen
  - Imagick::getImageColorspace — Obtiene el espacio de colores de la imagen
  - Imagick::getImageCompose — Devuelve el operador de composición asociado a una imagen
  - Imagick::getImageCompression — Lee el tipo de compresión de la imagen
  - Imagick::getImageCompressionQuality — Lee la calidad de compresión de la imagen
  - Imagick::getImageDelay — Lee el retraso de la imagen
  - Imagick::getImageDepth — Se lee la profundidad de la imagen
  - Imagick::getImageDispose — Lee el método de recuperación
  - Imagick::getImageDistortion — Compara una imagen con una imagen reconstruida
  - Imagick::getImageExtrema — Lee los extremos de una imagen
  - Imagick::getImageFilename — Devuelve el nombre de un fichero para una imagen en una secuencia
  - Imagick::getImageFormat — Devuelve el formato de una imagen en una secuencia
  - Imagick::getImageGamma — Obtiene el gamma de la imagen
  - Imagick::getImageGeometry — Lee las dimensiones de la imagen en un array
  - Imagick::getImageGravity — Obtiene la gravedad de la imagen
  - Imagick::getImageGreenPrimary — Devuelve la cromaticidad del color verde
  - Imagick::getImageHeight — Devuelve la altura de la imagen
  - Imagick::getImageHistogram — Devuelve el histograma de la imagen
  - Imagick::getImageIndex — Obtiene el índice de la imagen actual
  - Imagick::getImageInterlaceScheme — Se lee el esquema de entrelazado de la imagen
  - Imagick::getImageInterpolateMethod — Devuelve el método de interpolación
  - Imagick::getImageIterations — Obtiene las iteraciones de la imagen
  - Imagick::getImageLength — Devuelve el tamaño de la imagen en bytes
  - Imagick::getImageMatte — Indica si la imagen tiene un canal mat
  - Imagick::getImageMatteColor — Devuelve el color mate de la imagen
  - Imagick::getImageMimeType — Devuelve el tipo MIME de la imagen
  - Imagick::getImageOrientation — Lee la orientación de la imagen
  - Imagick::getImagePage — Devuelve la geometría de la página
  - Imagick::getImagePixelColor — Devuelve el color del píxel especificado
  - Imagick::getImageProfile — Devuelve el perfil nominado de la imagen
  - Imagick::getImageProfiles — Devuelve los perfiles de la imagen
  - Imagick::getImageProperties — Devuelve las propiedades EXIF de la imagen
  - Imagick::getImageProperty — Devuelve una propiedad de una imagen
  - Imagick::getImageRedPrimary — Devuelve la cromaticidad del punto rojo
  - Imagick::getImageRegion — Extrae una región de la imagen
  - Imagick::getImageRenderingIntent — Lee el método de renderizado de la imagen
  - Imagick::getImageResolution — Lee las resoluciones en X y Y de una imagen
  - Imagick::getImagesBlob — Devuelve todas las imágenes de la secuencia en un BLOB
  - Imagick::getImageScene — Devuelve la escena de la imagen
  - Imagick::getImageSignature — Genera una firma SHA-256
  - Imagick::getImageSize — Devuelve el tamaño de la imagen en bytes
  - Imagick::getImageTicksPerSecond — Se leen los ticks-por-segundo de la imagen
  - Imagick::getImageTotalInkDensity — Lee la densidad total de tinta de la imagen
  - Imagick::getImageType — Obtiene el tipo posible de imagen
  - Imagick::getImageUnits — Devuelve las unidades de resolución de la imagen
  - Imagick::getImageVirtualPixelMethod — Devuelve el método del píxel virtual
  - Imagick::getImageWhitePoint — Devuelve la cromaticidad del punto blanco
  - Imagick::getImageWidth — Devuelve el ancho de la imagen
  - Imagick::getInterlaceScheme — Lee el esquema de entrelazado del objeto
  - Imagick::getIteratorIndex — Lee el índice de la imagen activa actual
  - Imagick::getNumberImages — Devuelve el número de imágenes de un objeto
  - Imagick::getOption — Devuelve un valor asociado con la clave especificada
  - Imagick::getPackageName — Devuelve el nombre del paquete ImageMagick
  - Imagick::getPage — Devuelve la geometría de la página
  - Imagick::getPixelIterator — Devuelve un MagickPixelIterator
  - Imagick::getPixelRegionIterator — Obtiene un objeto ImagickPixelIterator de una sección de imagen
  - Imagick::getPointSize — Obtiene el tamaño del punto
  - Imagick::getQuantum — Devuelve el espacio cuántico de ImageMagick
  - Imagick::getQuantumDepth — Lee la profundidad cuántica
  - Imagick::getQuantumRange — Devuelve el intervalo cuántico de Imagick
  - Imagick::getRegistry — Obtiene un elemento de StringRegistry
  - Imagick::getReleaseDate — Devuelve la fecha de publicación de ImageMagick
  - Imagick::getResource — Devuelve el consumo de memoria de la recurso
  - Imagick::getResourceLimit — Devuelve el límite de la recurso
  - Imagick::getSamplingFactors — Lee el factor de muestreo horizontal y vertical
  - Imagick::getSize — Retorna el tamaño asociado con un objeto Imagick
  - Imagick::getSizeOffset — Devuelve el tamaño de la posición
  - Imagick::getVersion — Devuelve la API de ImageMagick
  - Imagick::haldClutImage — Reemplaza los colores de la imagen
  - Imagick::hasNextImage — Verifica si un objeto tiene una imagen siguiente
  - Imagick::hasPreviousImage — Verifica si un objeto tiene una imagen anterior
  - Imagick::identifyFormat — Formatea un string con los detalles de la imagen
  - Imagick::identifyImage — Identifica una imagen y obtiene sus atributos
  - Imagick::implodeImage — Crea una nueva imagen como una copia
  - Imagick::importImagePixels — Importa los píxeles de una imagen
  - Imagick::inverseFourierTransformImage — Implementa la transformada inversa de Fourier discreta (Discrete Fourier Transform - DFT)
  - Imagick::labelImage — Añade una etiqueta a una imagen
  - Imagick::levelImage — Ajusta los niveles de la imagen
  - Imagick::linearStretchImage — Estrecha con saturación la intensidad de la imagen
  - Imagick::liquidRescaleImage — Anima una imagen o imágenes
  - Imagick::listRegistry — Lista todos los parámetros del registro
  - Imagick::magnifyImage — Duplica el tamaño de una imagen, proporcionalmente
  - Imagick::mapImage — Reemplaza los colores de una imagen con el color más cercano de una imagen de referencia
  - Imagick::matteFloodfillImage — Cambia el valor de transparencia de un color
  - Imagick::medianFilterImage — Aplica un filtro digital
  - Imagick::mergeImageLayers — Fusiona las capas de la imagen
  - Imagick::minifyImage — Redimensiona una imagen proporcionalmente para reducirla a la mitad de tamaño
  - Imagick::modulateImage — Controla el brillo, la saturación y el tono
  - Imagick::montageImage — Crea una imagen compuesta
  - Imagick::morphImages — Metamorfosea un conjunto de imágenes
  - Imagick::morphology — Aplica un núcleo personalizado a la imagen según el método de morfología dado
  - Imagick::mosaicImages — Forma una mosaico de imágenes
  - Imagick::motionBlurImage — Simula borrosidad en movimiento
  - Imagick::negateImage — Invierte los colores en la imagen de referencia
  - Imagick::newImage — Crea una nueva imagen
  - Imagick::newPseudoImage — Crea una nueva imagen
  - Imagick::nextImage — Pasa a la siguiente imagen
  - Imagick::normalizeImage — Mejora el contraste de una imagen a color
  - Imagick::oilPaintImage — Simula una pintura al óleo
  - Imagick::opaquePaintImage — Cambia el color de cualquier píxel que coincida con el objetivo
  - Imagick::optimizeImageLayers — Elimina las porciones recurrentes de imágenes a optimizar
  - Imagick::orderedPosterizeImage — Realiza un entramado ordenado
  - Imagick::paintFloodfillImage — Cambia el valor del color de cualquier píxel que coincida con el objetivo
  - Imagick::paintOpaqueImage — Cambia cualquier píxel que coincida con el color
  - Imagick::paintTransparentImage — Cambia cualquier píxel que coincida con el color definido para el relleno
  - Imagick::pingImage — Trae los atributos básicos de una imagen
  - Imagick::pingImageBlob — Traer los atributos rápidamente
  - Imagick::pingImageFile — Obtener los atrbutos básicos de la imagen de una manera liviana
  - Imagick::polaroidImage — Simula una fotografía Polaroid
  - Imagick::posterizeImage — Reduce la imagen a un número limitado de niveles de color
  - Imagick::previewImages — Precisa rápidamente los parámetros apropiados para el procesamiento de la imagen
  - Imagick::previousImage — Pasa a la imagen anterior en una secuencia de imágenes
  - Imagick::profileImage — Añade o elimina un perfil de una imagen
  - Imagick::quantizeImage — Analiza los colores dentro de una imagen de referencia
  - Imagick::quantizeImages — Analiza los colores dentro de una secuencia de imágenes
  - Imagick::queryFontMetrics — Devuelve una matriz que representa las métricas de la fuente
  - Imagick::queryFonts — Devuelve la lista de fuentes configuradas
  - Imagick::queryFormats — Devuelve los formatos soportados por Imagick
  - Imagick::radialBlurImage — Hace borrosa de forma radial una imagen
  - Imagick::raiseImage — Crea un efecto de botón en 3D simulado
  - Imagick::randomThresholdImage — Crea una imagen de alto contraste y dos colores
  - Imagick::readImage — Lee una imagen desde un nombre de fichero
  - Imagick::readImageBlob — Lee una imagen desde un string binario
  - Imagick::readImageFile — Lee una imagen desde un gestor de fichero abierto
  - Imagick::readImages — Lee una imagen a partir de un array de nombres de ficheros
  - Imagick::recolorImage — Recolorear la imagen
  - Imagick::reduceNoiseImage — Suaviza los contornos de una imagen
  - Imagick::remapImage — Re-mapea los colores de una imagen
  - Imagick::removeImage — Elimina una imagen de la lista
  - Imagick::removeImageProfile — Elimina el perfil nominado de la imagen y lo devuelve
  - Imagick::render — Muestra todas las comandos de dibujo previas
  - Imagick::resampleImage — Remuestrea la imagen a la resolución deseada
  - Imagick::resetImagePage — Reinicia una página de imagen
  - Imagick::resizeImage — Escala una imagen
  - Imagick::rollImage — Compensa una imagen
  - Imagick::rotateImage — Rota una imagen
  - Imagick::rotationalBlurImage — Aplica un desenfoque rotacional a una imagen
  - Imagick::roundCorners — Redondea las esquinas de una imagen
  - Imagick::sampleImage — Escala una imagen con un muestreo de píxeles
  - Imagick::scaleImage — Redimensiona la imagen a una escala específica
  - Imagick::segmentImage — Segmenta una imagen
  - Imagick::selectiveBlurImage — Desenfoca selectivamente una imagen dentro de un umbral de contraste
  - Imagick::separateImageChannel — Separa un canal de la imagen
  - Imagick::sepiaToneImage — Pone una imagen en tono sepia
  - Imagick::setBackgroundColor — Establece el color de fondo por omisión del objeto
  - Imagick::setColorspace — Establecer el espacio de color
  - Imagick::setCompression — Configura el tipo de compresión del objeto
  - Imagick::setCompressionQuality — Configura la compresión por defecto del objeto
  - Imagick::setFilename — Establece el nombre de archivo antes de que se lea o escriba una imagen
  - Imagick::setFirstIterator — Coloca el iterador de Imagick en la primera imagen
  - Imagick::setFont — Configura la fuente
  - Imagick::setFormat — Establece el formato del objeto Imagick
  - Imagick::setGravity — Establece la gravedad
  - Imagick::setImage — Reemplaza una imagen en el objeto
  - Imagick::setImageAlphaChannel — Define el canal alfa de la imagen
  - Imagick::setImageArtifact — Define el artefacto de la imagen
  - Imagick::setImageAttribute — Define un atributo de imagen
  - Imagick::setImageBackgroundColor — Establece el color de fondo de la imagen
  - Imagick::setImageBias — Establece el sesgo de la imagen para cualquier método que convolucione una imagen
  - Imagick::setImageBiasQuantum — Establece el sesgo de la imagen
  - Imagick::setImageBluePrimary — Establece el punto primario azul de la cromaticidad de la imagen
  - Imagick::setImageBorderColor — Establece el color de borde de la imagen
  - Imagick::setImageChannelDepth — Establece la profundidad de una canal de imagen en particular
  - Imagick::setImageClipMask — Establece la máscara de recorte de una imagen
  - Imagick::setImageColormapColor — Establece el color de un índice de mapa de color especificado
  - Imagick::setImageColorspace — Establece el espacio de color de una imagen
  - Imagick::setImageCompose — Establece el operador de composción de una imagen
  - Imagick::setImageCompression — Establece la compresión de una imagen
  - Imagick::setImageCompressionQuality — Establece la calidad de compresión de una imagen
  - Imagick::setImageDelay — Establece el retardo de una imagen
  - Imagick::setImageDepth — Establece la profundidad de una imagen
  - Imagick::setImageDispose — Establece el método de disposición de una imagen
  - Imagick::setImageExtent — Establece el tamaño de una imagen
  - Imagick::setImageFilename — Establece el nombre de archivo de una imagen en particular
  - Imagick::setImageFormat — Establece el formato de una imagen en particular
  - Imagick::setImageGamma — Establece el valor gamma de la imagen
  - Imagick::setImageGravity — Establece la gravedad de la imagen
  - Imagick::setImageGreenPrimary — Establece el punto primario verde de la cromaticidad de la imagen
  - Imagick::setImageIndex — Establece la posición del iterador
  - Imagick::setImageInterlaceScheme — Establece la compresión de la imagen
  - Imagick::setImageInterpolateMethod — Configura el método de interpolación de la imagen
  - Imagick::setImageIterations — Establece las iteraciones de una imagen
  - Imagick::setImageMatte — Establece el canal mate de la imagen
  - Imagick::setImageMatteColor — Establece el color mate de la imagen
  - Imagick::setImageOpacity — Establece el nivel de opacidad de la imagen
  - Imagick::setImageOrientation — Establece la orientación de la imagen
  - Imagick::setImagePage — Establece la geometría de la página de la imagen
  - Imagick::setImageProfile — Añade un perfil nominado al objeto Imagick
  - Imagick::setImageProperty — Configura una propiedad de imagen
  - Imagick::setImageRedPrimary — Establece el punto primario rojo de la cromaticidad de la imagen
  - Imagick::setImageRenderingIntent — Establece el propósito de renderización de la imagen
  - Imagick::setImageResolution — Establece la resolución de la imagen
  - Imagick::setImageScene — Establece la escena de la imagen
  - Imagick::setImageTicksPerSecond — Establece los ticks por segundo de la imagen
  - Imagick::setImageType — Establece el tipo de imagen
  - Imagick::setImageUnits — Establece las unidades de resolución de la imagen
  - Imagick::setImageVirtualPixelMethod — Establece el método de píxel virtual de la imagen
  - Imagick::setImageWhitePoint — Establece el punto blanco de cromaticidad de la imagen
  - Imagick::setInterlaceScheme — Establece la compresión de la imagen
  - Imagick::setIteratorIndex — Establece la posición del iterador
  - Imagick::setLastIterator — Posiciona el iterador Imagick en la última imagen
  - Imagick::setOption — Configura una opción de un objeto Imagick
  - Imagick::setPage — Establece la geometría de página del objeto Imagick
  - Imagick::setPointSize — Define la medida del punto
  - Imagick::setProgressMonitor — Define una función de retrollamada a ser llamada durante el procesamiento
  - Imagick::setRegistry — Define la entrada del registro ImageMagick nombrada clave para valor
  - Imagick::setResolution — Establece la resolución de la imagen
  - Imagick::setResourceLimit — Define la limitación para una recurso particular
  - Imagick::setSamplingFactors — Establece los factores de muestreo de la imagen
  - Imagick::setSize — Establece el tamaño del objeto Imagick
  - Imagick::setSizeOffset — Establece el tamaño y el índice del objeto Imagick
  - Imagick::setType — Establece el atributo tipo de imagen
  - Imagick::shadeImage — Crea un efecto en 3D
  - Imagick::shadowImage — Simula una sombra de imagen
  - Imagick::sharpenImage — Afila una imagen
  - Imagick::shaveImage — Recorta píxeles de los extremos de la imagen
  - Imagick::shearImage — Crea un paralelogramo
  - Imagick::sigmoidalContrastImage — Ajusta el contraste de la imagen
  - Imagick::sketchImage — Simula el bosquejo de un lapiz
  - Imagick::smushImages — Toma todas las imágenes del puntero de imagen actual hasta el final de la lista de imágenes y las comprime
  - Imagick::solarizeImage — Aplica un efecto de solarización a la imagen
  - Imagick::sparseColorImage — Interpola colores
  - Imagick::spliceImage — Une un color sólido en la imagen
  - Imagick::spreadImage — Despalza aleatoriamente cada píxel en un bloque
  - Imagick::statisticImage — Modifica una imagen utilizando una función estadística
  - Imagick::steganoImage — Oculta una marca de agua digital dentro de la imagen
  - Imagick::stereoImage — Compone dos imágenes
  - Imagick::stripImage — Elimina de una imagen todos los perfiles y los comentarios
  - Imagick::subImageMatch — Busca una subimagen en la imagen actual y devuelve una imagen de similitud
  - Imagick::swirlImage — Arremolina los píxeles desde el centro de la imagen
  - Imagick::textureImage — Repite los mosaicos de la textura de una imagen
  - Imagick::thresholdImage — Cambia el valor de píexeles individuales basdos en un umbral
  - Imagick::thumbnailImage — Modifica el tamaño de una imagen
  - Imagick::tintImage — Aplica un vector de color a cada píxel en la imagen
  - Imagick::__toString — Devuelve la imagen como un string
  - Imagick::transformImage — Método conveniente para establecer el tamaño del recorte y la geometría de la imagen
  - Imagick::transformImageColorspace — Transforma una imagen en un nuevo espacio de color
  - Imagick::transparentPaintImage — Pinta píxeles transparentes
  - Imagick::transposeImage — Aplica una simetría vertical
  - Imagick::transverseImage — Crea un espejo horizontal de la imagen
  - Imagick::trimImage — Elimina los extremos de la imagen
  - Imagick::uniqueImageColors — Se conserva únicamente un color de píxel
  - Imagick::unsharpMaskImage — Afila una imagen
  - Imagick::valid — Verifica si el elemento actual es válido
  - Imagick::vignetteImage — Añade un filtro de viñeta a la imagen
  - Imagick::waveImage — Añade un filtro de ondas a la imagen
  - Imagick::whiteThresholdImage — Fuerza a todos los píxeles por encima del umbral a ser blancos
  - Imagick::writeImage — Escribe una imagen al nombre de fichero especificado
  - Imagick::writeImageFile — Escribe una imagen en un descriptor de archivo
  - Imagick::writeImages — Escribe una imagen o secuencia de imágenes
  - Imagick::writeImagesFile — Escribe los frames en un descriptor de ficheros
- ImagickDraw — La clase ImagickDraw
  - ImagickDraw::affine — Ajusta la matriz de transformación afín actual
  - ImagickDraw::annotation — Dibuja un texto sobre una imagen
  - ImagickDraw::arc — Dibuja un arco
  - ImagickDraw::bezier — Dibuja una curva de Bézier
  - ImagickDraw::circle — Dibuja un círculo
  - ImagickDraw::clear — Borra el objeto ImagickDraw
  - ImagickDraw::clone — Realiza una copia exacta del objeto ImagickDraw
  - ImagickDraw::color — Dibuja un color sobre una imagen
  - ImagickDraw::comment — Añade un comentario
  - ImagickDraw::composite — Componer una imagen con otra
  - ImagickDraw::__construct — El constructor ImagickDraw
  - ImagickDraw::destroy — Libera todos los recursos asociados
  - ImagickDraw::ellipse — Dibuja una elipse sobre una imagen
  - ImagickDraw::getClipPath — Devuelve el identificador del camino actual
  - ImagickDraw::getClipRule — Devuelve la regla de relleno de un polígono actual
  - ImagickDraw::getClipUnits — Devuelve la interpretación de unidades del trazado de recorte
  - ImagickDraw::getFillColor — Devuelve el color de relleno
  - ImagickDraw::getFillOpacity — Devuelve la opacidad de dibujo
  - ImagickDraw::getFillRule — Devuelve la regla de relleno
  - ImagickDraw::getFont — Devuelve la fuente
  - ImagickDraw::getFontFamily — Devuelve la familia de fuentes
  - ImagickDraw::getFontSize — Devuelve el tamaño de punto de la fuente
  - ImagickDraw::getFontStretch — Devuelve el estiramiento de la fuente a utilizar durante la anotación con texto
  - ImagickDraw::getFontStyle — Devuelve el estilo de la fuente
  - ImagickDraw::getFontWeight — Devuelve el peso de la fuente
  - ImagickDraw::getGravity — Devuelve la gravedad de colocación de texto
  - ImagickDraw::getStrokeAntialias — Devuelve la configuración de antialias de contorno actual
  - ImagickDraw::getStrokeColor — Devuelve el color usado por los perfiles de objetos contorneados
  - ImagickDraw::getStrokeDashArray — Devuelve un array que representa el patrón de trazos
  - ImagickDraw::getStrokeDashOffset — Devuelve el desplazamiento del punto en el patrón
  - ImagickDraw::getStrokeLineCap — Devuelve la forma a utilizar para dibujar los extremos de subrutas
  - ImagickDraw::getStrokeLineJoin — Devuelve la forma a utilizar para dibujar las esquinas de un camino
  - ImagickDraw::getStrokeMiterLimit — Devuelve el valor de 'miterLimit'
  - ImagickDraw::getStrokeOpacity — Devuelve la opacidad de los contornos de un objeto
  - ImagickDraw::getStrokeWidth — Devuelve el ancho de trazo utilizado
  - ImagickDraw::getTextAlignment — Devuelve la alineación del texto
  - ImagickDraw::getTextAntialias — Devuelve la configuración de antialias del texto actual
  - ImagickDraw::getTextDecoration — Devuelve la decoración del texto
  - ImagickDraw::getTextEncoding — Devuelve el juego de caracteres utilizado para las anotaciones de texto
  - ImagickDraw::getTextInterlineSpacing — Obtiene el espacio entre líneas de un texto.
  - ImagickDraw::getTextInterwordSpacing — Obtiene el espacio entre palabras de un texto.
  - ImagickDraw::getTextKerning — Obtiene el interletraje de un texto.
  - ImagickDraw::getTextUnderColor — Devuelve el color debajo del texto
  - ImagickDraw::getVectorGraphics — Devuelve una cadena que contiene gráficos vectoriales
  - ImagickDraw::line — Dibuja una línea
  - ImagickDraw::matte — Dibuja sobre el canal de opacidad de la imagen
  - ImagickDraw::pathClose — Añade un elemento de camino al camino actual
  - ImagickDraw::pathCurveToAbsolute — Dibuja una curva de Bézier cúbica, en coordenadas absolutas
  - ImagickDraw::pathCurveToQuadraticBezierAbsolute — Dibuja una curva de Bézier cuadrática, en coordenadas absolutas
  - ImagickDraw::pathCurveToQuadraticBezierRelative — Dibuja una curva de Bézier cuadrática, en coordenadas relativas
  - ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute — Dibuja una curva Bézier cuadrática
  - ImagickDraw::pathCurveToQuadraticBezierSmoothRelative — Dibuja una curva Bézier cuadrática
  - ImagickDraw::pathCurveToRelative — Dibuja una curva de Bézier cúbica, en coordenadas relativas
  - ImagickDraw::pathCurveToSmoothAbsolute — Dibuja una curva de Bézier, en coordenadas absolutas
  - ImagickDraw::pathCurveToSmoothRelative — Dibuja una curva de Bézier, en coordenadas relativas
  - ImagickDraw::pathEllipticArcAbsolute — Dibuja un arco de elipse, en coordenadas absolutas
  - ImagickDraw::pathEllipticArcRelative — Dibuja un arco de elipse, en coordenadas relativas
  - ImagickDraw::pathFinish — Finaliza el camino actual
  - ImagickDraw::pathLineToAbsolute — Dibuja una línea de camino, en coordenadas absolutas
  - ImagickDraw::pathLineToHorizontalAbsolute — Dibuja una línea de camino horizontal, en coordenadas absolutas
  - ImagickDraw::pathLineToHorizontalRelative — Dibuja una línea de camino horizontal, en coordenadas relativas
  - ImagickDraw::pathLineToRelative — Dibuja una línea de camino, en coordenadas relativas
  - ImagickDraw::pathLineToVerticalAbsolute — Dibuja una línea de camino vertical, en coordenadas absolutas
  - ImagickDraw::pathLineToVerticalRelative — Dibuja una línea de camino vertical, en coordenadas relativas
  - ImagickDraw::pathMoveToAbsolute — Inicia un nuevo subcamino, en coordenadas absolutas
  - ImagickDraw::pathMoveToRelative — Inicia un nuevo subcamino, en coordenadas relativas
  - ImagickDraw::pathStart — Declara el inicio de una lista de dibujo de trazados
  - ImagickDraw::point — Dibuja un punto
  - ImagickDraw::polygon — Dibuja un polígono
  - ImagickDraw::polyline — Dibuja una poli-línea
  - ImagickDraw::pop — Destruye el objeto ImagickDraw actual de la pila, y lo devuelve al objeto ImagickDraw previamente metido
  - ImagickDraw::popClipPath — Finaliza la definición de un camino
  - ImagickDraw::popDefs — Finaliza una lista de definiciones
  - ImagickDraw::popPattern — Finaliza una definición de patrón
  - ImagickDraw::push — Clona el objeto ImagickDraw actual y lo mete en la pila
  - ImagickDraw::pushClipPath — Inicia la definición de un trazado de recorte
  - ImagickDraw::pushDefs — Indica que los siguientes comandos crean elementos con nombre para un procesamiento previo
  - ImagickDraw::pushPattern — Indica que los comandos subsiguientes hasta un comando ImagickDraw::opPattern() comprenden la definición de un patrón nominado
  - ImagickDraw::rectangle — Dibuja un rectángulo
  - ImagickDraw::render — Realiza el renderizado de todos los dibujos en la imagen
  - ImagickDraw::resetVectorGraphics — Restablece los gráficos vectoriales
  - ImagickDraw::rotate — Aplica la rotación especificada al espacio de coordenadas actual
  - ImagickDraw::roundRectangle — Dibuja un rectángulo con esquinas redondeadas
  - ImagickDraw::scale — Ajusta el factor de escala
  - ImagickDraw::setClipPath — Asocia un trazado de recorte nominado con la imagen
  - ImagickDraw::setClipRule — Configura la regla de relleno del polígono a utilizar con los caminos
  - ImagickDraw::setClipUnits — Configura el modo de interpretación de las unidades de ruta
  - ImagickDraw::setFillAlpha — Configura la opacidad del color de relleno
  - ImagickDraw::setFillColor — Configura el color de relleno de los objetos dibujados
  - ImagickDraw::setFillOpacity — Configura la opacidad a utilizar para el relleno
  - ImagickDraw::setFillPatternURL — Configura la URL del patrón de relleno de superficies
  - ImagickDraw::setFillRule — Configura la regla de relleno de los polígonos
  - ImagickDraw::setFont — Establece la fuente especificada completamente para usarla cuando se escribe texto
  - ImagickDraw::setFontFamily — Establece la familia de fuentes para usarla cuando se escribe texto
  - ImagickDraw::setFontSize — Configura el tamaño de punto para los textos
  - ImagickDraw::setFontStretch — Configura el estiramiento del texto
  - ImagickDraw::setFontStyle — Configura el estilo de la fuente
  - ImagickDraw::setFontWeight — Configura el peso de la fuente
  - ImagickDraw::setGravity — Configura la gravedad de colocación de texto
  - ImagickDraw::setResolution — Define la resolución
  - ImagickDraw::setStrokeAlpha — Especifica la opacidad de los contornos de los objetos
  - ImagickDraw::setStrokeAntialias — Controla el anti-aliasing de los trazos
  - ImagickDraw::setStrokeColor — Configura el color utilizado para dibujar objetos
  - ImagickDraw::setStrokeDashArray — Especifica el patrón de trazo discontinuo
  - ImagickDraw::setStrokeDashOffset — Especifica el índice dentro del patrón de discontinuidad para iniciar la discontinuidad
  - ImagickDraw::setStrokeLineCap — Especifica la forma a utilizar al final de los subcampos
  - ImagickDraw::setStrokeLineJoin — Especifica la forma a utilizar para dibujar los extremos de las líneas
  - ImagickDraw::setStrokeMiterLimit — Especifica el límite del inglete
  - ImagickDraw::setStrokeOpacity — Especifica la opacidad para dibujar los contornos
  - ImagickDraw::setStrokePatternURL — Establece el patrón usado para los perfiles de objetos contorneados
  - ImagickDraw::setStrokeWidth — Configura el ancho del trazo para dibujar contornos
  - ImagickDraw::setTextAlignment — Especifica la alineación del texto
  - ImagickDraw::setTextAntialias — Controla el anti-aliaseo del texto
  - ImagickDraw::setTextDecoration — Especifica los ornamentos de texto
  - ImagickDraw::setTextEncoding — Especifica el juego de caracteres
  - ImagickDraw::setTextInterlineSpacing — Define el espacio entre las líneas de un texto
  - ImagickDraw::setTextInterwordSpacing — Define el espacio entre las palabras de un texto
  - ImagickDraw::setTextKerning — Define el interletraje de un texto
  - ImagickDraw::setTextUnderColor — Especifica el color de fondo de un rectángulo
  - ImagickDraw::setVectorGraphics — Establece los gráficos vectoriales
  - ImagickDraw::setViewbox — Configura el tamaño del lienzo
  - ImagickDraw::skewX — Tuerce el sistema de coordenadas actual en la dirección horizontal
  - ImagickDraw::skewY — Tuerce el sistema de coordenadas actual en la dirección vertical
  - ImagickDraw::translate — Aplica una traslación del sistema de coordenadas actual
- ImagickDrawException — La clase ImagickDrawException
- ImagickException — La clase ImagickException
- ImagickKernel — La clase ImagickKernel
  - ImagickKernel::addKernel — Adjunta otro núcleo a una lista de núcleos
  - ImagickKernel::addUnityKernel — Añade un núcleo Unity a la lista de núcleos
  - ImagickKernel::fromBuiltIn — Crear un núcleo a partir de un núcleo integrado
  - ImagickKernel::fromMatrix — Crear un núcleo a partir de una matriz 2D de valores
  - ImagickKernel::getMatrix — Devuelve la matriz 2D de los valores utilizados en este núcleo
  - ImagickKernel::scale — Redimensiona una lista de núcleos por la cantidad dada
  - ImagickKernel::separate — Separa un conjunto de núcleos vinculados y devuelve un array de ImagickKernels
- ImagickKernelException — La clase ImagickKernelException
- ImagickPixel — La clase ImagickPixel
  - ImagickPixel::clear — Elimina todos los recursos asociados con el objeto
  - ImagickPixel::__construct — El constructor ImagickPixel
  - ImagickPixel::destroy — Libera los recursos asociados con el objeto
  - ImagickPixel::getColor — Devuelve el color
  - ImagickPixel::getColorAsString — Devuelve un color
  - ImagickPixel::getColorCount — Devuelve el número de colores asociados con un color
  - ImagickPixel::getColorQuantum — Devuelve el color del píxel en un array como valores cuánticos
  - ImagickPixel::getColorValue — Obtiene el valor normalizado del canal de color proporcionado
  - ImagickPixel::getColorValueQuantum — Devuelve el valor cuántico de un color en ImagickPixel
  - ImagickPixel::getHSL — Retorna el color HSL normalizado del objeto ImagickPixel
  - ImagickPixel::getIndex — Devuelve el índice de la tabla de colores del píxel
  - ImagickPixel::isPixelSimilar — Verifica la distancia entre este color y otro
  - ImagickPixel::isPixelSimilarQuantum — Indica si dos colores difieren en menos de la distancia especificada
  - ImagickPixel::isSimilar — Verifica la distancia entre 2 colores
  - ImagickPixel::setColor — Define la color
  - ImagickPixel::setColorCount — Define la cantidad de colores asociada a este píxel
  - ImagickPixel::setColorValue — Define el valor normalizado de uno de los canales
  - ImagickPixel::setColorValueQuantum — Define la valor cuántica de un elemento de color de ImagickPixel
  - ImagickPixel::setHSL — Define el color HSL normalizado
  - ImagickPixel::setIndex — Define el índice de la tabla de colores del píxel
- ImagickPixelException — La clase ImagickPixelException
- ImagickPixelIterator — La clase ImagickPixelIterator
  - ImagickPixelIterator::clear — Elimina todos los recursos asociados a PixelIterator
  - ImagickPixelIterator::__construct — El constructor de la clase ImagickPixelIterator
  - ImagickPixelIterator::destroy — Libera los recursos asociados a PixelIterator
  - ImagickPixelIterator::getCurrentIteratorRow — Devuelve la fila actual de los objetos ImagickPixel
  - ImagickPixelIterator::getIteratorRow — Devuelve la fila actual del iterador de píxeles
  - ImagickPixelIterator::getNextIteratorRow — Devuelve la siguiente línea del iterador de píxeles
  - ImagickPixelIterator::getPreviousIteratorRow — Devuelve la línea anterior
  - ImagickPixelIterator::newPixelIterator — Devuelve un nuevo píxel del iterador
  - ImagickPixelIterator::newPixelRegionIterator — Devuelve un nuevo iterador de píxeles
  - ImagickPixelIterator::resetIterator — Reinicia el iterador de píxeles
  - ImagickPixelIterator::setIteratorFirstRow — Establece el iterador de píxeles en la primera línea de píxeles
  - ImagickPixelIterator::setIteratorLastRow — Define el iterador de píxeles en la última línea de píxeles
  - ImagickPixelIterator::setIteratorRow — Define la línea del iterador de píxeles
  - ImagickPixelIterator::syncIterator — Sincroniza el iterador de píxeles
- ImagickPixelIteratorException — La clase ImagickPixelIteratorException

- Exif — Información Exif
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones de Exif
- GD — Procesamiento de imágenes y GD
  - Instalación/Configuración
  - Constantes predefinidas
  - Ejemplos
  - Funciones de GD e Imágenes
  - GdImage — La clase GdImage
  - GdFont — La clase GdFont
- Gmagick
  - Instalación/Configuración
  - Constantes predefinidas
  - Ejemplos
  - Gmagick — La clase Gmagick
  - GmagickDraw — La clase GmagickDraw
  - GmagickPixel — La clase GmagickPixel
- ImageMagick — Tratamiento de imágenes (ImageMagick)
  - Instalación/Configuración
  - Constantes predefinidas
  - Ejemplos
  - Imagick — La clase Imagick
  - ImagickDraw — La clase ImagickDraw
  - ImagickDrawException — La clase ImagickDrawException
  - ImagickException — La clase ImagickException
  - ImagickKernel — La clase ImagickKernel
  - ImagickKernelException — La clase ImagickKernelException
  - ImagickPixel — La clase ImagickPixel
  - ImagickPixelException — La clase ImagickPixelException
  - ImagickPixelIterator — La clase ImagickPixelIterator
  - ImagickPixelIteratorException — La clase ImagickPixelIteratorException

# Extensiones relacionadas con Email

# IMAP, POP3 y NNTP

# Introducción

Advertencia

Esta extensión está OBSOLETA y SEPARADA a partir de PHP 8.4.0.

Estas funciones permiten utilizar el protocolo IMAP, así como los protocolos NNTP, POP3 y los buzones de correo locales.

Sin embargo, se debe tener cuidado, ya que algunas funciones IMAP no funcionan correctamente con el protocolo POP.

Advertencia

La extensión IMAP no es segura a nivel de hilos; no debe ser utilizada con ZTS.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución
- Tipos de recursos

## Requerimientos

Esta extensión requiere la biblioteca C cliente. Descargue la última versión en » https://github.com/uw-imap/imap y compílela.

Es importante no copiar los ficheros fuente IMAP directamente en el directorio de inclusión del sistema para evitar conflictos. En lugar de esto, cree un nuevo directorio en el directorio de inclusión del sistema, como /usr/local/imap-2000b/ (la ruta y el nombre dependen de su configuración y de su versión de IMAP) y en este nuevo directorio, cree los directorios nombrados lib/ y include/. Desde el directorio c-client de las fuentes IMAP, copie todos los ficheros *.h en el directorio include/ y todos los ficheros *.c en el directorio lib/. Adicionalmente, cuando se compila IMAP, se crea un fichero nombrado c-client.a. Póngalo también en el directorio lib/ pero renómbrelo a libc-client.a.

> Nota:

> Para compilar la biblioteca C cliente con SSL y/o con soporte Kerberos, lea la documentación proporcionada en la distribución.

> Nota: En Mandrake Linux, la biblioteca IMAP (libc-client.a) se compila sin soporte Kerberos. Una versión separada con SSL (client-PHP4.a) se instala. La biblioteca debe ser recompilada para añadir soporte Kerberos.

## Instalación

## PHP 8.4

Esta extensión ha sido movida al módulo » PECL y no será integrada en PHP a partir de PHP 8.4.0

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/imap.

## PHP < 8.4

Para que estas funciones operen, es necesario compilar PHP con --with-imap[=DIR], donde DIR es el prefijo de instalación de c-client. En el ejemplo anterior, se utilizaría --with-imap=/usr/local/imap-2000b. Esta ubicación depende de dónde se haya creado este directorio, como se indica en la descripción anterior. Los usuarios de Windows pueden incluir la DLL php_imap.dll en php.ini.

> Nota: Dependiendo de cómo se haya configurado c-client, es posible que también sea necesario añadir --with-imap-ssl=/path/to/openssl/ y/o --with-kerberos=/path/to/kerberos a la línea de configuración de PHP.

Advertencia

La extensión IMAP no es thread-safe; no debe ser utilizada con builds ZTS.

Advertencia

Las extensiones IMAP, recode y YAZ no pueden ser utilizadas simultáneamente ya que utilizan un símbolo interno común. Nota: Yaz 2.0 y superior ya no sufre de este problema.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

IMAP Opciones de configuración
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
imap.enable_insecure_rsh | "0" | `INI_SYSTEM` | Disponible a partir de PHP 7.1.25, 7.2.13 y 7.3.0. Anteriormente, estaba activado implícitamente.

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`imap.enable_insecure_rsh` bool

  Establecer una conexión a un servidor puede invocar comandos rsh o ssh, a menos que esta opción php.ini esté desactivada.

  Advertencia

  Ni PHP ni la biblioteca IMAP filtran los nombres de los buzones antes de pasarlos a los comandos rsh o ssh, por lo tanto, pasar datos no fiables a esta función sin desactivar esta opción php.ini es peligroso.

## Tipos de recursos

Anterior a PHP 8.1.0, esta extensión utilizaba un tipo de recurso `imap` devuelto por imap_open() que hace referencia a un flujo IMAP abierto.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`NIL` (int)
  Obsoleto a partir de PHP 8.1.0.
`OP_DEBUG` (int)
`OP_READONLY` (int)
  Abre un buzón de correo en modo de solo lectura.
`OP_ANONYMOUS` (int)
  No utilizar, o modificar el fichero .newsrc para las noticias, (NNTP únicamente).
`OP_SHORTCACHE` (int)
`OP_SILENT` (int)
`OP_PROTOTYPE` (int)
`OP_HALFOPEN` (int)
  Para los nombres IMAP y NNTP, abre una conexión pero no abre un buzón de correo.
`OP_EXPUNGE` (int)
`OP_SECURE` (int)
`CL_EXPUNGE` (int)
  purgar automáticamente el buzón de correo al llamar a imap_close()
`FT_UID` (int)
  El argumento es un UID.
`FT_PEEK` (int)
  No levantar el flag \Seen (Mensaje leído) si no está ya levantado.
`FT_NOT` (int)
`FT_INTERNAL` (int)
  La cadena devuelta está en formato interno, y no va a canonizar los CRLF.
`FT_PREFETCHTEXT` (int)
`ST_UID` (int)
  la secuencia contiene UID en lugar de números de secuencia
`ST_SILENT` (int)
`ST_SET` (int)
`CP_UID` (int)
  La secuencia de números contiene UID
`CP_MOVE` (int)
  Borra los mensajes después de copiar con imap_mail_copy()
`SE_UID` (int)
  Devuelve UID en lugar de números
`SE_FREE` (int)
`SE_NOPREFETCH` (int)
  No pretelecargar los mensajes encontrados
`SO_FREE` (int)
`SO_NOSERVER` (int)
`SA_MESSAGES` (int)
`SA_RECENT` (int)
`SA_UNSEEN` (int)
`SA_UIDNEXT` (int)
`SA_UIDVALIDITY` (int)
`SA_ALL` (int)
`LATT_NOINFERIORS` (int)
  Este buzón de correo no tiene "hijos" (no hay más buzones de correo debajo de este).
`LATT_NOSELECT` (int)
  Esto es solo un contenedor, no un buzón de correo (no se puede abrir).
`LATT_MARKED` (int)
  Este buzón de correo está marcado. Utilizado únicamente con UW-IMAPD.
`LATT_UNMARKED` (int)
  Este buzón de correo no está marcado. Utilizado únicamente con UW-IMAPD.
`LATT_REFERRAL` (int)
  Este contenedor tiene una referencia a un buzón de correo remoto.
`LATT_HASCHILDREN` (int)
  Este buzón de correo tiene inferiores seleccionables.
`LATT_HASNOCHILDREN` (int)
  Este buzón de correo no tiene inferiores seleccionables.
`SORTDATE` (int)
  Criterio de ordenación para imap_sort() : Fecha del mensaje
`SORTARRIVAL` (int)
  Criterio de ordenación para imap_sort() : Fecha de llegada
`SORTFROM` (int)
  Criterio de ordenación para imap_sort() : Nombre de la primera caja de correo de la dirección de origen (From address)
`SORTSUBJECT` (int)
  Criterio de ordenación para imap_sort() : Asunto del mensaje
`SORTTO` (int)
  Criterio de ordenación para imap_sort() : Nombre de la primera caja de correo de destino (To address)
`SORTCC` (int)
  Criterio de ordenación para imap_sort() : Nombre de la caja de correo de copia oculta (cc address)
`SORTSIZE` (int)
  Criterio de ordenación para imap_sort() : Tamaño del mensaje en bytes
`TYPETEXT` (int)
  Tipo de cuerpo primario : texto no formateado
`TYPEMULTIPART` (int)
  Tipo de cuerpo primario : varias partes
`TYPEMESSAGE` (int)
  Tipo de cuerpo primario : mensaje encapsulado
`TYPEAPPLICATION` (int)
  Tipo de cuerpo primario : datos de aplicación
`TYPEAUDIO` (int)
  Tipo de cuerpo primario : audio
`TYPEIMAGE` (int)
  Tipo de cuerpo primario : imagen estática
`TYPEVIDEO` (int)
  Tipo de cuerpo primario : video
`TYPEMODEL` (int)
  Tipo de cuerpo primario : modelo
`TYPEOTHER` (int)
  Tipo de cuerpo primario : desconocido
`ENC7BIT` (int)
  Codificación del cuerpo : datos semánticos SMTP 7 bit
`ENC8BIT` (int)
  Codificación del cuerpo : datos semánticos SMTP 8 bit
`ENCBINARY` (int)
  Codificación del cuerpo : datos binarios 8 bit
`ENCBASE64` (int)
  Codificación del cuerpo : datos codificados en base-64
`ENCQUOTEDPRINTABLE` (int)
  Codificación del cuerpo : datos 8-7-bit legibles por el ser humano
`ENCOTHER` (int)
  Codificación del cuerpo : desconocido
`IMAP_OPENTIMEOUT` (int)
`IMAP_READTIMEOUT` (int)
`IMAP_WRITETIMEOUT` (int)
`IMAP_CLOSETIMEOUT` (int)
`IMAP_GC_ELT` (int)
  Recolección de la memoria, eliminación de las cachés de elementos de mensaje.
`IMAP_GC_ENV` (int)
  Recolección de la memoria, eliminación de las envolturas y cuerpos.
`IMAP_GC_TEXTS` (int)
  Recolección de la memoria, eliminación de los textos.

# Funciones IMAP

# Ver también

Este documento no puede entrar en detalles de todos los temas abordados. Más información está disponible con la documentación de la biblioteca C (docs/internal.txt) así como los RFC siguientes :

- » RFC2821 : `Simple Mail Transfer Protocol` (SMTP).
- » RFC2822 : `Standard for ARPA internet text messages`.
- » RFC2060 : `Internet Message Access Protocol` (IMAP) Version 4rev1.
- » RFC1939 : `Post Office Protocol Version 3` (POP3).
- » RFC977 : `Network News Transfer Protocol` (NNTP).
- » RFC2076 : `Common Internet Message Headers`.
- » RFC2045 , » RFC2046 , » RFC2047 , » RFC2048 y » RFC2049: `Multipurpose Internet Mail Extensions` (MIME).

Un estudio en profundidad también está disponible en los siguientes libros (en inglés) : » `Programming Internet Email` por David Wood y » Managing IMAP por Dianna Mullet & Kevin Mullet.

# imap_8bit

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_8bit — Convierte un string de 8 bits en un string codificado en Quoted-Printable

### Descripción

function imap_8bit(string `$string`): string|false

Convierte el string de 8 bits en un string codificado en Quoted-Printable (según la » RFC 2045, Sección 6.7).

### Parámetros

`string`

  El string de 8 bits a convertir

### Valores devueltos

Devuelve un string codificado en Quoted-Printable, o `false` si ocurre un error.

### Ver también

- imap_qprint() - Convierte una string con comillas en una string de 8 bits

# imap_alerts

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_alerts — Devuelve todas las alertas

### Descripción

function imap_alerts(): array|false

Devuelve un array de todos los mensajes de alerta IMAP generados desde la última llamada a imap_alerts() o desde el inicio de la página.

Cuando imap_alerts() es llamada, la pila de alertas es vaciada. Las especificaciones IMAP requieren que estos mensajes sean pasados al usuario.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array que contiene todos los mensajes de alerta IMAP generados o `false` si no hay mensajes de alerta disponibles.

### Ver también

- imap_errors() - Devuelve todos los errores IMAP ocurridos

# imap_append

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_append — Añade un mensaje en un buzón de correo

### Descripción

function imap_append(
IMAP\Connection `$imap`,
string `$folder`,
string `$message`,
?string `$options` = `null`,
?string `$internal_date` = `null`
): bool

Añade un `message` al `folder` especificado.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`folder`

  El nombre del buzón de correo, ver la documentación de la función imap_open() para más información

  Advertencia

  Pasar datos no confiables a este parámetro es inseguro, a menos que imap.enable_insecure_rsh esté desactivado.

`message`

  El mensaje a añadir, en forma de string

  Al intercambiar con el servidor Cyrus IMAP, se debe utilizar "\r\n" como terminación de línea, en lugar de "\n" o la operación fallará.

`options`

  Si se proporciona, el parámetro `options` será también escrito en el buzón `folder`

`internal_date`

  Si se define este parámetro, establecerá los INTERNALDATE en el mensaje adjunto. El parámetro debe ser una cadena de fecha que cumpla con las especificaciones del rfc2060 para un valor date_time.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.
8.0.0 | `options` y `internal_date` ahora son nullables.

### Ejemplos

Ejemplo #1 Ejemplo con imap_append()

    <?php
    $imap = imap_open("{imap.example.org}INBOX.Drafts", "username", "password");

    $check = imap_check($imap);
    echo "Msg Count before append: ". $check->Nmsgs . "\n";

    imap_append($imap, "{imap.example.org}INBOX.Drafts"
                       , "From: me@example.com\r\n"
                       . "To: you@example.com\r\n"
                       . "Subject: test\r\n"
                       . "\r\n"
                       . "Este es un mensaje de prueba. Ignórelo.\r\n"
                       );

    $check = imap_check($imap);
    echo "Número de mensajes después de añadir : ". $check->Nmsgs . "\n";

    imap_close($imap);
    ?>

# imap_base64

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_base64 — Decodifica un texto codificado en BASE64

### Descripción

function imap_base64(string `$string`): string|false

Decodifica el texto `string` codificado en BASE64.

### Parámetros

`string`

  El texto codificado.

### Valores devueltos

Devuelve el texto decodificado, en forma de string, o `false` si ocurre un error.

### Ver también

- imap_binary() - Convierte una string de 8 bits en una string en base64
- base64_encode() - Codifica datos con MIME base64
- base64_decode() - Decodifica datos codificados con MIME base64
- » RFC2045, Sección 6.8

# imap_binary

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_binary — Convierte una string de 8 bits en una string en base64

### Descripción

function imap_binary(string `$string`): string|false

Convierte la string de 8 bits `string` en una string en base64 (según la » RFC2045, Sección 6.8).

### Parámetros

`string`

  La string de 8 bits

### Valores devueltos

Devuelve la string codificada en base64, o `false` si ocurre un error.

### Ver también

- imap_base64() - Decodifica un texto codificado en BASE64

# imap_body

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_body — Lee el cuerpo de un mensaje

### Descripción

function imap_body(IMAP\Connection `$imap`, int `$message_num`, int `$flags` = 0): string|false

imap_body() devuelve el cuerpo del mensaje número `message_num` del buzón actual.

imap_body() devolverá una copia sin tratar del cuerpo del mensaje. Para extraer las subpartes MIME del mensaje, utilice imap_fetchstructure() para analizar la estructura, y imap_fetchbody() para extraer una copia de una de las subpartes.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`message_num`

  El número del mensaje

`flags`

  El parámetro `flags` opcional es una máscara que puede contener los siguientes valores:

  - `FT_UID` - `message_num` es un UID
  - `FT_PEEK` - No levantar el flag \Seen (Mensaje leído) si no está ya levantado.
  - `FT_INTERNAL` - La string devuelta está en formato interno, y no va a canonizar los CRLF.

### Valores devueltos

Devuelve el cuerpo del mensaje especificado, en forma de string, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

# imap_bodystruct

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_bodystruct — Lee la estructura de una sección del cuerpo de un correo electrónico

### Descripción

function imap_bodystruct(IMAP\Connection `$imap`, int `$message_num`, string `$section`): stdClass|false

Lee la estructura de una sección especificada del cuerpo de un correo electrónico.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`message_num`

  El número del mensaje

`section`

  La sección del cuerpo a leer

### Valores devueltos

Devuelve la información en un objeto, o `false` si ocurre un error. Para una descripción detallada de la estructura del objeto así como de sus propiedades, consulte la función imap_fetchstructure().

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ver también

- imap_fetchstructure() - Lee la estructura de un mensaje

# imap_check

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_check — Verifica el buzón de correo actual

### Descripción

function imap_check(IMAP\Connection `$imap`): stdClass|false

Verifica la información del buzón de correo actual.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.

### Valores devueltos

Devuelve la información en un objeto que contiene las siguientes propiedades:

- `Date` - Fecha de la última modificación del contenido del buzón de correo de acuerdo con la » RFC2822
- `Driver` - protocolo utilizado para acceder al buzón de correo: POP3, IMAP, NNTP.
- `Mailbox` - nombre del buzón de correo
- `Nmsgs` - número de mensajes en el buzón de correo
- `Recent` - número de mensajes recientes en el buzón de correo

Devuelve `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imap_check()

    <?php

    $imap = imap_check($imap_stream);
    var_dump($imap);

    ?>

Resultado del ejemplo anterior es similar a:

    object(stdClass)(5) {
      ["Date"]=>
      string(37) "Wed, 10 Dec 2003 17:56:54 +0100 (CET)"
      ["Driver"]=>
      string(4) "imap"
      ["Mailbox"]=>
      string(54)
      "{www.example.com:143/imap/user="foo@example.com"}INBOX"
      ["Nmsgs"]=>
      int(1)
      ["Recent"]=>
      int(0)
    }

# imap_clearflag_full

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_clearflag_full — Elimina un flag en un mensaje

### Descripción

function imap_clearflag_full(
IMAP\Connection `$imap`,
string `$sequence`,
string `$flag`,
int `$options` = 0
): true

imap_clearflag_full() borra el flag `flag` en los mensajes de la secuencia `sequence`, del flujo imap `stream`.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`sequence`

  Una secuencia de números de mensajes. Se pueden enumerar los mensajes deseados con la sintaxis `X,Y`, o recuperar todos los mensajes contenidos en un intervalo, con la sintaxis `X:Y`

`flag`

  Los flags `flag` que se pueden borrar son "\\Seen", "\\Answered", "\\Flagged", "\\Deleted" y "\\Draft" (tal como se definen en la » RFC2060)

`options`

  `options` es una máscara de bits, que acepta únicamente el siguiente valor:

  - `ST_UID` - la secuencia contiene UID en lugar de números de secuencia

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

Lanza una excepción ValueError si el argumento `options` es inválido.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.
8.0.0 | Una excepción ValueError es ahora lanzada para valores inválidos del argumento `options`. Anteriormente, se emitía una advertencia y la función devolvía `false`.

### Ver también

- imap_setflag_full() - Establece un flag en un mensaje

# imap_close

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_close — Termina un flujo IMAP

### Descripción

function imap_close(IMAP\Connection `$imap`, int `$flags` = 0): true

Termina un flujo IMAP.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`flags`

  Si se establece en `CL_EXPUNGE`, la función realizará una purga automática del buzón antes de cerrarlo, eliminando todos los mensajes marcados para su eliminación. Se puede lograr lo mismo con la función imap_expunge()

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

Lanza una excepción ValueError si el argumento `flags` es inválido.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.
8.0.0 | Ahora se lanza una excepción ValueError para valores de argumento `flags` inválidos. Anteriormente, se emitía una advertencia y la función devolvía `false`.

### Ver también

- imap_open() - Abre un flujo IMAP hacia un buzón de correo

# imap_create

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_create — Alias de imap_createmailbox()

### Descripción

Esta función es un alias de: imap_createmailbox().

# imap_createmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_createmailbox — Crea un nuevo buzón de correo

### Descripción

function imap_createmailbox(IMAP\Connection `$imap`, string `$mailbox`): bool

Crea un nuevo buzón de correo llamado `mailbox`.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`mailbox`

  El nombre del buzón de correo, ver la documentación de la función imap_open() para más información. Los nombres que contienen caracteres internacionales deben ser codificados por la función imap_utf7_encode()

  Advertencia

  Pasar datos no confiables a este parámetro es inseguro, a menos que imap.enable_insecure_rsh esté desactivado.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imap_createmailbox()

    <?php
    $mbox = imap_open("{imap.example.org}", "username", "password", OP_HALFOPEN)
         or die("conexión imposible : " . imap_last_error());

    $name1 = "phpnewbox";
    $name2 = imap_utf7_encode("phpnewböx"); // phpnewb&w7Y-x

    $newname = $name1;

    echo "El nuevo nombre será '$name1'<br />\n";

    // Vamos a crear ahora un nuevo buzón de correo "phptestbox"
    // en su carpeta inbox, verificar su estado y, finalmente, eliminarlo
    // para devolver su inbox a su estado inicial.

    if (@imap_createmailbox($mbox, imap_utf7_encode("{imap.example.org}INBOX.$newname"))) {
        $status = @imap_status($mbox, "{imap.example.org}INBOX.$newname", SA_ALL);
        if ($status) {
            echo "Su nuevo buzón '$name1' está en el siguiente estado :<br />\n";
            echo "Mensajes :   " . $status->messages    . "<br />\n";
            echo "Recientes :     " . $status->recent      . "<br />\n";
            echo "No leídos :     " . $status->unseen      . "<br />\n";
            echo "UIDnext :    " . $status->uidnext     . "<br />\n";
            echo "UIDvalidity :" . $status->uidvalidity . "<br />\n";

            if (imap_renamemailbox($mbox, "{imap.example.org}INBOX.$newname", "{imap.example.org}INBOX.$name2")) {
                echo "renombrando el buzón de correo '$name1' a '$name2'<br />\n";
                $newname = $name2;
            } else {
                echo "imap_renamemailbox en el nuevo buzón de correo falló : " . imap_last_error() . "<br />\n";
            }
        } else {
            echo "imap_status en el nuevo buzón de correo falló : " . imap_last_error() . "<br />\n";
        }

        if (@imap_deletemailbox($mbox, "{imap.example.org}INBOX.$newname")) {
            echo "nuevo buzón de correo eliminado para devolver todo a su estado<br />\n";
        } else {
            echo "imap_deletemailbox en el nuevo buzón de correo falló : " . implode("<br />\n", imap_errors()) . "<br />\n";
        }

    } else {
        echo "Imposible crear un nuevo buzón de correo : " . implode("<br />\n", imap_errors()) . "<br />\n";
    }

    imap_close($mbox);
    ?>

### Ver también

- imap_renamemailbox() - Renombra un buzón de correo
- imap_deletemailbox() - Borra una boîte aux lettres

# imap_delete

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_delete — Marca el fichero para el borrado, en el buzón de correo actual

### Descripción

function imap_delete(IMAP\Connection `$imap`, string `$message_nums`, int `$flags` = 0): true

Marca los mensajes `message_nums` para el borrado. El borrado real no intervendrá hasta la llamada de la función imap_expunge() o de imap_close() con el parámetro opcional `CL_EXPUNGE`.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`message_nums`

  Un string representando uno o varios mensajes en un estilo de formato de una secuencia IMAP4 (`"n"`, `"n:m"`, o una combinación de esto, delimitado por comas).

`flags`

  Puede ser definido a `FT_UID` que solicita a la función tratar el argumento `message_nums` como un `UID`.

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

Lanza una excepción ValueError si el parámetro `flags` es inválido.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.
8.0.0 | Una excepción ValueError es ahora lanzada para valores de parámetro `flags` inválidos. Anteriormente, una advertencia era emitida y la función retornaba `false`.

### Ejemplos

Ejemplo #1 Ejemplo con imap_delete()

    <?php

    $mbox = imap_open("{imap.example.org}INBOX", "username", "password")
        or die("Conexión imposible : " . imap_last_error());

    $check = imap_mailboxmsginfo($mbox);
    echo "Número de mensajes antes del borrado : " . $check->Nmsgs . "<br />\n";

    imap_delete($mbox, 1);

    $check = imap_mailboxmsginfo($mbox);
    echo "Número de mensajes después del borrado : " . $check->Nmsgs . "<br />\n";

    imap_expunge($mbox);

    $check = imap_mailboxmsginfo($mbox);
    echo "Número de mensajes después de imap_expunge : " . $check->Nmsgs . "<br />\n";

    imap_close($mbox);
    ?>

### Notas

> Nota:

> Los buzones de correo IMAP no tienen los flags de sus mensajes guardados entre las conexiones, por lo que la función imap_expunge() debe ser llamada durante la misma conexión para que los mensajes marcados para el borrado sean realmente purgados.

### Ver también

- imap_undelete() - Elimina la marca de eliminación de un mensaje
- imap_expunge() - Elimina todos los mensajes marcados para su eliminación
- imap_close() - Termina un flujo IMAP

# imap_deletemailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_deletemailbox — Borra una boîte aux lettres

### Descripción

function imap_deletemailbox(IMAP\Connection `$imap`, string `$mailbox`): bool

Borra la boîte aux lettres especificada.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`mailbox`

  El nombre de la boîte aux lettres, ver la documentación sobre la función imap_open() para más detalles

  Advertencia

  Pasar datos no confiables a este parámetro es inseguro, a menos que imap.enable_insecure_rsh esté desactivado.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ver también

- imap_createmailbox() - Crea un nuevo buzón de correo
- imap_renamemailbox() - Renombra un buzón de correo
- imap_open() - Abre un flujo IMAP hacia un buzón de correo para el formato `mbox`

# imap_errors

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_errors — Devuelve todos los errores IMAP ocurridos

### Descripción

function imap_errors(): array|false

Esta función devuelve un array de todos los mensajes de error IMAP generados desde la última llamada a imap_errors() o desde el inicio de la página.

Cuando imap_errors() es llamada, la pila de errores es vaciada.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Esta función devuelve un array que contiene todos los mensajes de error IMAP generados desde la última llamada a la función imap_errors() o desde el inicio de la página. Devuelve `false` si no hay mensajes de error disponibles.

### Ver también

- imap_last_error() - Devuelve el último error ocurrido
- imap_alerts() - Devuelve todas las alertas

# imap_expunge

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_expunge — Elimina todos los mensajes marcados para su eliminación

### Descripción

function imap_expunge(IMAP\Connection `$imap`): true

Elimina todos los mensajes marcados para su eliminación por imap_delete(), imap_mail_move(), o imap_setflag_full().

### Parámetros

`imap`
  Una instancia de IMAP\Connection.

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

# imap_fetch_overview

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetch_overview — Lee el resumen de los encabezados de los mensajes

### Descripción

function imap_fetch_overview(IMAP\Connection `$imap`, string `$sequence`, int `$flags` = 0): array|false

Lee los encabezados de los correos electrónicos de la secuencia `sequence` y devuelve un resumen de su contenido.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`sequence`

  Una descripción de la secuencia del mensaje. Se pueden enumerar los mensajes deseados con la sintaxis `X,Y`, o recuperar todos los mensajes de un intervalo, con la sintaxis `X:Y`

`flags`

  `sequence` contendrá una secuencia de índice de mensaje o de UID, si `flags` contiene `FT_UID`.

### Valores devueltos

Devuelve un array de objetos que describen el encabezado de cada mensaje. El objeto solo definirá una propiedad si existe. Las propiedades posibles son:

- `subject` : el asunto del mensaje
- `from` : el remitente
- `to` : el destinatario
- `date` : la fecha de envío
- `message_id` : la identificación del mensaje
- `references` : la referencia sobre el id de este mensaje
- `in_reply_to` : la respuesta a este identificador de mensaje
- `size` : el tamaño en bytes
- `uid` : UID del mensaje en el buzón
- `msgno` : el número de secuencia del mensaje en el buzón
- `recent` : este mensaje es reciente
- `flagged` : este mensaje está marcado
- `answered` : este mensaje ha dado lugar a una respuesta
- `deleted` : este mensaje está marcado para el borrado
- `seen` : este mensaje ya ha sido leído
- `draft` : este mensaje es un borrador
- `udate` : el horario UNIX de la hora de llegada

La función devuelve `false` en caso de fallo.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imap_fetch_overview()

    <?php
    $mbox = imap_open("{imap.example.org:143}INBOX", "username", "password")
         or die("Conexión imposible: " . imap_last_error());

    $MC = imap_check($mbox);

    // Recupera el resumen para todos los mensajes contenidos en INBOX
    $result = imap_fetch_overview($mbox,"1:{$MC->Nmsgs}",0);
    foreach ($result as $overview) {
        echo "#{$overview->msgno} ({$overview->date}) - From: {$overview->from}
        {$overview->subject}\n";
    }
    imap_close($mbox);
    ?>

### Ver también

- imap_fetchheader() - Devuelve el encabezado de un mensaje

# imap_fetchbody

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchbody — Devuelve una sección extraída del cuerpo de un mensaje

### Descripción

function imap_fetchbody(
IMAP\Connection `$imap`,
int `$message_num`,
string `$section`,
int `$flags` = 0
): string|false

Recupera una sección particular del cuerpo de los mensajes especificados. Las partes del cuerpo no son decodificadas por esta función.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`message_num`

  El número del mensaje

`section`

  El número de la sección. Es una cadena de enteros, delimitados por una coma que corresponden a los índices en la lista de las secciones del mensaje, tal como se prevé en la especificación IMAP4.

`flags`

  La opción imap_fetchbody() es una máscara que puede contener los siguientes valores:

  - `FT_UID` - `message_num` es un UID
  - `FT_PEEK` - No levantar el flag \Seen (Mensaje leído) si no está ya levantado.
  - `FT_INTERNAL` - La cadena devuelta está en formato interno, y no va a canonizar los CRLF.

### Valores devueltos

Devuelve una sección particular del cuerpo de los mensajes especificados, en forma de una string, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ver también

- imap_savebody() - Guarda una parte específica del cuerpo en un fichero
- imap_fetchstructure() - Lee la estructura de un mensaje

# imap_fetchheader

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchheader — Devuelve el encabezado de un mensaje

### Descripción

function imap_fetchheader(IMAP\Connection `$imap`, int `$message_num`, int `$flags` = 0): string|false

imap_fetchheader() devuelve el encabezado RFC2822 crudo y completo del mensaje `msgno`, en forma de string.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`message_num`

  El número del mensaje

`flags`

  Las opciones posibles son:

  - `FT_UID` - `message_num` es un UID
  - `FT_INTERNAL` - La string devuelta está en formato "internal", es decir, sin canonización de los CRLF
  - `FT_PREFETCHTEXT` - RFC822.TEXT debe ser pre descargado junto con el encabezado. Esto reduce el RTT en una conexión IMAP, si se desea el mensaje completo. (e.g. en una operación de guardado en un fichero).

### Valores devueltos

Devuelve el encabezado del mensaje especificado, en forma de string, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ver también

- imap_fetch_overview() - Lee el resumen de los encabezados de los mensajes

# imap_fetchmime

(PHP 5 >= 5.3.6, PHP 7, PHP 8)

imap_fetchmime — Recupera los encabezados MIME para una sección particular del mensaje

### Descripción

function imap_fetchmime(
IMAP\Connection `$imap`,
int `$message_num`,
string `$section`,
int `$flags` = 0
): string|false

Recupera los encabezados MIME para una sección particular del cuerpo de un mensaje específico.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`message_num`

  El número del mensaje.

`section`

  El número de la sección. Es una cadena de enteros delimitados por una coma que representa el índice de la lista de secciones del cuerpo del mensaje, tal como se especifica en IMAP4.

`flags`

  Una máscara de una o varias opciones siguientes:

  - `FT_UID` - El parámetro `message_num` es un UID.
  - `FT_PEEK` - No colocar la bandera \Seen si no está ya definida.
  - `FT_INTERNAL` - La cadena devuelta está en un formato interno, y no será canonizada en CRLF.

### Valores devueltos

Devuelve los encabezados MIME de una sección particular del cuerpo del mensaje especificado, en forma de un string, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ver también

- imap_fetchbody() - Devuelve una sección extraída del cuerpo de un mensaje
- imap_fetchstructure() - Lee la estructura de un mensaje
- imap_fetchheader() - Devuelve el encabezado de un mensaje

# imap_fetchstructure

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchstructure — Lee la estructura de un mensaje

### Descripción

function imap_fetchstructure(IMAP\Connection `$imap`, int `$message_num`, int `$flags` = 0): stdClass|false

imap_fetchstructure() lee la estructura del mensaje `msg_number`.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`message_num`

  El número del mensaje

`flags`

  Este parámetro opcional tiene una sola opción, `FT_UID`, que solicita a la función tratar el argumento `message_num` como un `UID`.

### Valores devueltos

Devuelve un objeto cuyas propiedades se listan en la tabla siguiente, o `false` si ocurre un error.

Objeto devuelto por imap_fetchstructure()
type | Tipo primario de cuerpo
encoding | Codificación de transferencia del cuerpo
ifsubtype | `true` si hay una cadena de subtipo
subtype | subtipo MIME
ifdescription | `true` si hay una cadena de descripción
description | Cadena de descripción del contenido
ifid | `true` si hay una cadena de identificación
id | Cadena de identificación
lines | Número de líneas
bytes | Número de bytes
ifdisposition | `true` si hay una cadena de disposición
disposition | Cadena de disposición
ifdparameters | `true` si hay un array de parámetros dparameters
dparameters | array de objetos donde cada objeto tiene una propiedad `"attribute"` y una propiedad `"value"` correspondiente a los parámetros de encabezado `Content-disposition` MIME.
ifparameters | `true` si el array de parámetros existe
parameters | Array de objetos donde cada uno tiene una propiedad `"attribute"` y una propiedad `"value"`.
parts | Array de objetos que describen cada parte MIME del mensaje

Tipo primario de cuerpo (puede variar según la biblioteca utilizada)
Valor | Tipo | Constante
--- | --- | ---
0 | texto | TYPETEXT
1 | multipart | TYPEMULTIPART
2 | mensaje | TYPEMESSAGE
3 | aplicación | TYPEAPPLICATION
4 | audio | TYPEAUDIO
5 | imagen | TYPEIMAGE
6 | video | TYPEVIDEO
7 | modelo | TYPEMODEL
8 | otro | TYPEOTHER

Codificación de transferencia (puede variar según la biblioteca utilizada)
Valor | Tipo | Constante
--- | --- | ---
0 | 7 bit | ENC7BIT
1 | 8 bit | ENC8BIT
2 | Binario | ENCBINARY
3 | Base 64 | ENCBASE64
4 | Citado imprimible | ENCQUOTEDPRINTABLE
5 | Otro | ENCOTHER

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ver también

- imap_fetchbody() - Devuelve una sección extraída del cuerpo de un mensaje
- imap_bodystruct() - Lee la estructura de una sección del cuerpo de un correo electrónico

# imap_fetchtext

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchtext — Alias de imap_body()

### Descripción

Esta función es un alias de: imap_body().

# imap_gc

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

imap_gc — Borra la caché IMAP

### Descripción

function imap_gc(IMAP\Connection `$imap`, int `$flags`): true

Elimina todas las entradas de un tipo dado en la caché IMAP.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`flags`

  Indica el tipo de caché a purgar. Puede ser una combinación de las siguientes constantes: `IMAP_GC_ELT` (caché de los elementos de mensaje), `IMAP_GC_ENV` (sobre y cuerpo), `IMAP_GC_TEXTS` (textos).

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

Lanza una excepción ValueError si el argumento `flags` es inválido.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.
8.0.0 | Una excepción ValueError es ahora lanzada para valores de argumento `flags` inválidos. Anteriormente, se emitía una advertencia y la función devolvía `false`.

### Ejemplos

Ejemplo #1 Ejemplo conimap_gc()

    <?php

    $mbox = imap_open("{imap.example.org:143}", "username", "password");

    imap_gc($mbox, IMAP_GC_ELT);

    ?>

# imap_get_quota

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

imap_get_quota — Lee los cuotas de los buzones de correo así como las estadísticas sobre cada uno de ellos

### Descripción

function imap_get_quota(IMAP\Connection `$imap`, string `$quota_root`): array|false

Lee los cuotas de los buzones de correo así como las estadísticas sobre cada uno de ellos.

Para una versión de usuario, no administrador, de esta función, refiérase a la función imap_get_quotaroot().

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`quota_root`

  `quota_root` debe ser de la forma : "`user.nom`", donde "nom" es el nombre del buzón de correo que se desea analizar.

### Valores devueltos

Devuelve un array que contiene los valores de cuota y actuales del buzón de correo `quota_root`. La cuota representa el tamaño máximo del buzón de correo. El valor actual es el espacio actualmente utilizado por el buzón de correo. imap_get_quota() devolverá `false` en caso de fallo.

Desde PHP 4.3, la función refleja más fielmente las funcionalidades dictadas por la » RFC2087. El array devuelto ha cambiado para soportar un número ilimitado de recursos devueltos (i.e. mensajes o subcarpetas) con cada recurso nombrado que es identificado por una clave. Cada clave contiene entonces otro array con el uso y la cuota. El ejemplo a continuación muestra cómo utilizarlo.

Por razones de compatibilidad, el método de acceso original sigue estando disponible, pero se recomienda abandonarlo.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imap_get_quota()

    <?php
    $mbox = imap_open("{imap.example.org}", "mailadmin", "password", OP_HALFOPEN)
          or die("Imposible conectarse : " . imap_last_error());

    $quota_value = imap_get_quota($mbox, "user.kalowsky");
    if (is_array($quota_value)) {
        echo "Nivel de uso : " . $quota_value['usage'];
        echo "Cuota : " . $quota_value['limit'];
    }

    imap_close($mbox);
    ?>

Ejemplo #2 Ejemplo con imap_get_quota() 4.3 o superior

    <?php
    $mbox = imap_open("{imap.example.org}", "mailadmin", "password", OP_HALFOPEN)
          or die("Imposible conectarse : " . imap_last_error());

    $quota_values = imap_get_quota($mbox, "user.kalowsky");
    if (is_array($quota_values)) {
       $storage = $quota_values['STORAGE'];
       echo "Uso actual de la capacidad de almacenamiento : " .  $storage['usage'];
       echo "Cuota actual de almacenamiento  : " .  $storage['limit'];

       $message = $quota_values['MESSAGE'];
       echo "Nivel de uso de MESSAGE  : " .  $message['usage'];
       echo "Cuota de MESSAGE : " .  $message['limit'];

       /* ...  */
    }

    imap_close($mbox);
    ?>

### Notas

imap_get_quota() funciona actualmente solo con las bibliotecas c-client2000.

El `imap` dado debe estar abierto como administrador de correo, de lo contrario esta función falla.

### Ver también

- imap_open() - Abre un flujo IMAP hacia un buzón de correo
- imap_set_quota() - Modifica el cupo de un buzón de correo
- imap_get_quotaroot() - Lee los cuotas de cada usuario

# imap_get_quotaroot

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imap_get_quotaroot — Lee los cuotas de cada usuario

### Descripción

function imap_get_quotaroot(IMAP\Connection `$imap`, string `$mailbox`): array|false

Recupera los cuotas de cada usuario. El valor límite representa el espacio límite asignado para este usuario para el uso de su buzón de correo. El valor de uso representa el tamaño actual del buzón de correo.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`mailbox`

  `mailbox` debe ser un nombre de buzón de correo (i.e. INBOX).

### Valores devueltos

Devuelve un array de enteros, conteniendo los cuotas del buzón de correo del usuario. Todos los valores son representados por una clave basada en el nombre del buzón, y por un array representando el nivel de uso y los límites.

Esta función devolverá `false` si ocurre un error, y un array de datos si la respuesta del servidor no pudo ser comprendida.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imap_get_quotaroot()

    <?php
    $mbox = imap_open("{imap.example.org}", "kalowsky", "password", OP_HALFOPEN)
          or die("Conexión imposible : " . imap_last_error());

    $quota = imap_get_quotaroot($mbox, "INBOX");
    if (is_array($quota)) {
       $storage = $quota['STORAGE'];
       echo "STORAGE nivel de uso : " .  $storage['usage'];
       echo "STORAGE tamaño límite : " .  $storage['limit'];

       $message = $quota['MESSAGE'];
       echo "MESSAGE nivel de uso : " .  $message['usage'];
       echo "MESSAGE tamaño límite : " .  $message['limit'];

       /* ...  */

    }

    imap_close($mbox);
    ?>

### Notas

Esta función es accesible únicamente a los usuarios de la biblioteca c-client2000 o más reciente.

`imap` debería ser abierto como el usuario cuyo buzón de correo se desea verificar.

### Ver también

- imap_open() - Abre un flujo IMAP hacia un buzón de correo
- imap_set_quota() - Modifica el cupo de un buzón de correo
- imap_get_quota() - Lee los cuotas de los buzones de correo así como las estadísticas sobre cada uno de ellos

# imap_getacl

(PHP 5, PHP 7, PHP 8)

imap_getacl — Devuelve el ACL para el buzón

### Descripción

function imap_getacl(IMAP\Connection `$imap`, string `$mailbox`): array|false

Recupera el ACL para el buzón dado.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`mailbox`

  El nombre del buzón, ver la documentación de la función imap_open() para más detalles.

  Advertencia

  Pasar datos no confiables a este parámetro es inseguro, a menos que imap.enable_insecure_rsh esté desactivado.

### Valores devueltos

Devuelve un array asociativo en la forma "folder" => "acl", o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imap_getacl()

    <?php

    print_r(imap_getacl($imap, 'user.joecool'));

    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [asubfolder] => lrswipcda
        [anothersubfolder] => lrswipcda
    )

### Notas

Esta función está actualmente disponible solo para los usuarios de la biblioteca `c-client2000` o superior.

### Ver también

- imap_setacl() - Modifica el ACL de la bandeja de entrada

# imap_getmailboxes

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_getmailboxes — Lista los buzones de correo y devuelve los detalles de cada uno

### Descripción

function imap_getmailboxes(IMAP\Connection `$imap`, string `$reference`, string `$pattern`): array|false

Lista los buzones de correo.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`reference`

  `reference` debería ser solo el servidor en la forma descrita en imap_open()

  Advertencia

  Pasar datos no confiables a este parámetro es inseguro, a menos que imap.enable_insecure_rsh esté desactivado.

`pattern`
  Especifica en qué parte de la jerarquía del buzón comenzar la búsqueda.Hay dos caracteres especiales que se pueden pasar como parte del `pattern`: '`*`' y '`%`'. '`*`' significa devolver todos los buzones. Si se pasa `pattern` como '`*`', se obtendrá una lista de toda la jerarquía del buzón. '`%`' significa devolver solo el nivel actual. '`%`' como parámetro `pattern` devolverá solo los buzones de nivel superior; '`~/mail/%`' en `UW_IMAPD` devolverá cada buzón en el directorio ~/mail, pero ninguno en las subcarpetas de ese directorio.

### Valores devueltos

Devuelve un array de objetos que contienen información sobre los buzones de correo. Cada objeto posee un atributo de `name`, que contiene el nombre completo del buzón de correo, `delimiter` que es el delimitador jerárquico y `attributes`. `attributes` es una máscara de bits, que contiene :

- `LATT_NOINFERIORS` - Este buzón de correo no tiene "hijos" (no hay más buzones de correo debajo de este) y no puede contener ninguno. Una llamada a la función imap_createmailbox() no funcionará en este buzón.

- `LATT_NOSELECT` - Esto es solo un contenedor, no un buzón de correo (no se puede abrir).

- `LATT_MARKED` - Este buzón de correo está marcado. Esto significa que puede contener nuevos mensajes desde la última vez que fue verificado. Este marcador no se proporciona con todos los servidores IMAP.

- `LATT_UNMARKED` - Este buzón de correo no está marcado y no contiene nuevos mensajes. Si `MARKED` o `UNMARKED` se proporciona, se puede asumir que el servidor IMAP soporta esta funcionalidad para este buzón de correo.

- `LATT_REFERRAL` - Este contenedor tiene una referencia a un buzón de correo remoto.

- `LATT_HASCHILDREN` - Este buzón de correo tiene inferiores seleccionables.

- `LATT_HASNOCHILDREN` - Este buzón de correo no tiene inferiores seleccionables.

Devuelve `false` en caso de fallo.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imap_getmailboxes()

    <?php
    $mbox = imap_open("{imap.example.org}", "username", "password", OP_HALFOPEN)
          or die("Conexión imposible: " . imap_last_error());

    $list = imap_getmailboxes($mbox, "{imap.example.org}", "*");
    if (is_array($list)) {
        foreach ($list as $key => $val) {
            echo "($key) ";
            echo imap_utf7_decode($val->name) . ",";
            echo "'" . $val->delimiter . "',";
            echo $val->attributes . "<br />\n";
        }
    } else {
        echo "imap_getmailboxes ha fallado: " . imap_last_error() . "\n";
    }

    imap_close($mbox);
    ?>

### Ver también

- imap_getsubscribed() - Lista todas las carpetas de correo suscritas

# imap_getsubscribed

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_getsubscribed — Lista todas las carpetas de correo suscritas

### Descripción

function imap_getsubscribed(IMAP\Connection `$imap`, string `$reference`, string `$pattern`): array|false

Lista todas las carpetas de correo suscritas.

imap_getsubscribed() es idéntico a imap_getmailboxes(), pero solo devuelve las carpetas de correo a las que el usuario está suscrito.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`reference`

  `reference` debe ser solo el servidor en la forma descrita en imap_open()

  Advertencia

  Pasar datos no confiables a este parámetro es inseguro, a menos que imap.enable_insecure_rsh esté desactivado.

`pattern`
  Especifica en qué parte de la jerarquía del buzón comenzar la búsqueda.Hay dos caracteres especiales que se pueden pasar como parte del `pattern`: '`*`' y '`%`'. '`*`' significa devolver todos los buzones. Si se pasa `pattern` como '`*`', se obtendrá una lista de toda la jerarquía del buzón. '`%`' significa devolver solo el nivel actual. '`%`' como parámetro `pattern` devolverá solo los buzones de nivel superior; '`~/mail/%`' en `UW_IMAPD` devolverá cada buzón en el directorio ~/mail, pero ninguno en las subcarpetas de ese directorio.

### Valores devueltos

Devuelve un array de objetos que contienen información sobre las carpetas de correo. Cada objeto posee un atributo de `name`, que contiene el nombre completo de la carpeta de correo, `delimiter` que es el delimitador jerárquico y `attributes`. `attributes` es una máscara de bits, que contiene :

- `LATT_NOINFERIORS` - Esta carpeta de correo no tiene "hijos" (no hay más carpetas de correo debajo de esta).
- `LATT_NOSELECT` - Esto es solo un contenedor, no una carpeta de correo (no se puede abrir).
- `LATT_MARKED` - Esta carpeta de correo está marcada. Utilizado únicamente con UW-IMAPD.
- `LATT_UNMARKED` - Esta carpeta de correo no está marcada. Utilizado únicamente con UW-IMAPD.
- `LATT_REFERRAL` - Este contenedor tiene una referencia a una carpeta de correo remota.
- `LATT_HASCHILDREN` - Esta carpeta de correo tiene inferiores seleccionables.
- `LATT_HASNOCHILDREN` - Esta carpeta de correo no tiene inferiores seleccionables.

La función devuelve `false` en caso de fallo.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

# imap_header

(PHP 4, PHP 5, PHP 7)

imap_header — Alias de imap_headerinfo()

Advertencia

Este alias está ELIMINADO a partir de PHP 8.0.0.

### Descripción

Esta función es un alias de: imap_headerinfo().

# imap_headerinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_headerinfo — Lee la cabecera del mensaje

### Descripción

function imap_headerinfo(
IMAP\Connection `$imap`,
int `$message_num`,
int `$from_length` = 0,
int `$subject_length` = 0
): stdClass|false

Recupera la información sobre un número de mensaje dado leyendo sus cabeceras.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`message_num`

  El número del mensaje

`from_length`

  Número de caracteres para la propiedad `fetchfrom`. Debe ser mayor o igual a `0`.

`subject_length`

  Número de caracteres para la propiedad `fetchsubject`. Debe ser mayor o igual a `0`.

### Valores devueltos

Devuelve `false` en caso de errores o, en caso de éxito, la información en un objeto que contiene las siguientes propiedades:

- `"toaddress"` : toda la línea de cabecera to: hasta 1024 caracteres
- `"to"` : un array de objetos de la línea to: con las siguientes propiedades: `personal`, `adl`, `mailbox`, y `host`
- `"fromaddress"` : toda la línea de cabecera from: hasta 1024 caracteres
- `"from"` : un array de objetos de la línea From: con las siguientes propiedades: `personal`, `adl`, `mailbox`, y `host`
- `"ccaddress"` : toda la línea de cabecera cc: hasta 1024 caracteres
- `"cc"` : un array de objetos de la línea cc: con las siguientes propiedades: `personal`, `adl`, `mailbox`, y `host`
- `"bccaddress"` : toda la línea de cabecera bcc: hasta 1024 caracteres
- `"bcc"` : un array de objetos de la línea Bcc: con las siguientes propiedades: `personal`, `adl`, `mailbox`, y `host`
- `"reply_toaddress"` : toda la línea de cabecera Reply_to: hasta 1024 caracteres
- `"reply_to"` : un array de objetos de la línea Reply_to: con las siguientes propiedades: `personal`, `adl`, `mailbox`, y `host`
- `"senderaddress"` : toda la línea de cabecera Sender: hasta 1024 caracteres
- `"sender"` : un array de objetos de la línea Sender: con las siguientes propiedades: `personal`, `adl`, `mailbox`, y `host`
- `"return_pathaddress"` : toda la línea de cabecera Return-path: hasta 1024 caracteres
- `"return_path"` : un array de objetos de la línea Return-path: con las siguientes propiedades: `personal`, `adl`, `mailbox`, y `host`
- remail -
- `"date"` : La fecha del mensaje, tal como se encuentra en las cabeceras
- `"Date"` : Idéntico a `"date"`
- `"subject"` : El asunto del mensaje
- `"Subject"` : Idéntico a `"subject"`
- `"in_reply_to"` :
- `"message_id"` :
- `"newsgroups"` :
- `"followup_to"` :
- `"references"` :
- `"Recent"` : `R` si el mensaje es reciente y leído, `N` si el mensaje es reciente y no leído, `" "` si el mensaje no es reciente.
- `"Unseen"` : `U` si el mensaje es no leído Y no reciente, `" "` si el mensaje es no leído y reciente
- `"Flagged"` : `F` si el mensaje contiene un flag, `" "` en caso contrario
- `"Answered"` : `A` si se ha respondido a este mensaje, `" "` en caso contrario
- `"Deleted"` : `D` si el mensaje está eliminado, `" "` en caso contrario
- `"Draft"` : `X` si el mensaje es un borrador, `" "` en caso contrario
- `"Msgno"` : El número del mensaje
- `"MailDate"` :
- `"Size"` : El tamaño del mensaje
- `"udate"` : Fecha de envío del mensaje, en forma de fecha Unix
- `"fetchfrom"` : Línea `"from"` formateada para caber en `from_length` caracteres
- `"fetchsubject"` : Línea `"subject"` formateada para caber en `subject_length` caracteres

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.
8.0.0 | El parámetro `defaulthost` sin uso ha sido eliminado.

### Ver también

- imap_fetch_overview() - Lee el resumen de los encabezados de los mensajes

# imap_headers

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_headers — Devuelve los encabezados de todos los mensajes de un buzón de correo

### Descripción

function imap_headers(IMAP\Connection `$imap`): array|false

Devuelve los encabezados de todos los mensajes de un buzón de correo.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.

### Valores devueltos

Devuelve un array de strings que contienen los encabezados de los mensajes: un string por mensaje. Devuelve `false` en caso de fallo.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

# imap_is_open

(PHP 8 >= 8.2.1)

imap_is_open — Verificar si el flujo IMAP sigue siendo válido

### Descripción

function imap_is_open(IMAP\Connection `$imap`): bool

Verifica si el flujo IMAP sigue siendo válido.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.

### Valores devueltos

Devuelve `true` si el flujo sigue siendo válido, `false` en caso contrario.

### Ejemplos

Ejemplo #1 Ejemplo de imap_is_open()

    <?php
    $mbox = imap_open("{imap.example.org:143}INBOX", "username", "password") or die(implode(", ", imap_errors()));
    imap_is_open($mbox);
    // ...
    ?>

# imap_last_error

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_last_error — Devuelve el último error ocurrido

### Descripción

function imap_last_error(): string|false

imap_last_error() devuelve el texto completo del último error IMAP (si existe) que ocurrió durante la última petición. La pila de errores no se ve afectada. Llamar a imap_last_error() sucesivamente, sin nuevos errores, devolverá el mismo error.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el texto completo del último mensaje de error IMAP ocurrido en la página actual. Devuelve `false` si no hay ningún mensaje disponible.

### Ver también

- imap_errors() - Devuelve todos los errores IMAP ocurridos

# imap_list

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_list — Lee la lista de buzones de correo

### Descripción

function imap_list(IMAP\Connection `$imap`, string `$reference`, string `$pattern`): array|false

Lee la lista de buzones de correo.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`reference`

  `reference` debería ser solo el servidor en la forma descrita en imap_open()

  Advertencia

  Pasar datos no confiables a este parámetro es inseguro, a menos que imap.enable_insecure_rsh esté desactivado.

`pattern`
  Especifica en qué parte de la jerarquía del buzón comenzar la búsqueda.Hay dos caracteres especiales que se pueden pasar como parte del `pattern`: '`*`' y '`%`'. '`*`' significa devolver todos los buzones. Si se pasa `pattern` como '`*`', se obtendrá una lista de toda la jerarquía del buzón. '`%`' significa devolver solo el nivel actual. '`%`' como parámetro `pattern` devolverá solo los buzones de nivel superior; '`~/mail/%`' en `UW_IMAPD` devolverá cada buzón en el directorio ~/mail, pero ninguno en las subcarpetas de ese directorio.

### Valores devueltos

Devuelve un array que contiene los nombres de los buzones de correo, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imap_list()

    <?php
    $mbox = imap_open("{imap.example.org}", "username", "password", OP_HALFOPEN)
          or die("Conexión imposible: " . imap_last_error());

    $list = imap_list($mbox, "{imap.example.org}", "*");
    if (is_array($list)) {
        foreach ($list as $val) {
            echo imap_utf7_decode($val) . "\n";
        }
    } else {
        echo "imap_list ha fallado: " . imap_last_error() . "\n";
    }

    imap_close($mbox);
    ?>

### Ver también

- imap_getmailboxes() - Lista los buzones de correo y devuelve los detalles de cada uno
- imap_lsub() - Lista todas las carpetas de correo registradas

# imap_listmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listmailbox — Alias de imap_list()

### Descripción

Esta función es un alias de: imap_list().

# imap_listscan

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listscan — Lee la lista de buzones de correo y busca una cadena

### Descripción

function imap_listscan(
IMAP\Connection `$imap`,
string `$reference`,
string `$pattern`,
string `$content`
): array|false

Devuelve un array que contiene los nombres de los buzones de correo que contienen el string `content` en su nombre.

Esta función es similar a imap_listmailbox(), pero también verifica la presencia del string `content` en los mensajes del buzón de correo.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`reference`

  `reference` debe ser solo el servidor en la forma descrita en imap_open()

  Advertencia

  Pasar datos no confiables a este parámetro es inseguro, a menos que imap.enable_insecure_rsh esté desactivado.

`pattern`
  Especifica en qué parte de la jerarquía del buzón comenzar la búsqueda.Hay dos caracteres especiales que se pueden pasar como parte del `pattern`: '`*`' y '`%`'. '`*`' significa devolver todos los buzones. Si se pasa `pattern` como '`*`', se obtendrá una lista de toda la jerarquía del buzón. '`%`' significa devolver solo el nivel actual. '`%`' como parámetro `pattern` devolverá solo los buzones de nivel superior; '`~/mail/%`' en `UW_IMAPD` devolverá cada buzón en el directorio ~/mail, pero ninguno en las subcarpetas de ese directorio.
`content`

  El string buscado

### Valores devueltos

Devuelve un array que contiene los nombres de los buzones de correo que contienen el string `content` en el nombre del buzón de correo, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ver también

- imap_listmailbox() - Alias de imap_list
- imap_search() - Devuelve un array de mensajes después de la búsqueda

# imap_listsubscribed

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listsubscribed — Alias de imap_lsub()

### Descripción

Esta función es un alias de: imap_lsub().

# imap_lsub

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_lsub — Lista todas las carpetas de correo registradas

### Descripción

function imap_lsub(IMAP\Connection `$imap`, string `$reference`, string `$pattern`): array|false

Recupera un array que contiene todas las carpetas de correo a las que se ha suscrito.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`reference`

  `reference` debería ser solo el servidor en la forma descrita en imap_open()

  Advertencia

  Pasar datos no confiables a este parámetro es inseguro, a menos que imap.enable_insecure_rsh esté desactivado.

`pattern`
  Especifica en qué parte de la jerarquía del buzón comenzar la búsqueda.Hay dos caracteres especiales que se pueden pasar como parte del `pattern`: '`*`' y '`%`'. '`*`' significa devolver todos los buzones. Si se pasa `pattern` como '`*`', se obtendrá una lista de toda la jerarquía del buzón. '`%`' significa devolver solo el nivel actual. '`%`' como parámetro `pattern` devolverá solo los buzones de nivel superior; '`~/mail/%`' en `UW_IMAPD` devolverá cada buzón en el directorio ~/mail, pero ninguno en las subcarpetas de ese directorio.

### Valores devueltos

Devuelve un array que contiene todas las carpetas de correo suscritas, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ver también

- imap_list() - Lee la lista de buzones de correo
- imap_getmailboxes() - Lista los buzones de correo y devuelve los detalles de cada uno

# imap_mail

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail — Envía un mensaje de correo electrónico

### Descripción

function imap_mail(
string `$to`,
string `$subject`,
string `$message`,
?string `$additional_headers` = `null`,
?string `$cc` = `null`,
?string `$bcc` = `null`,
?string `$return_path` = `null`
): bool

imap_mail() permite enviar correos electrónicos con una gestión correcta de los destinatarios Cc y Bcc.

Los parámetros `to`, `cc` y `bcc` son todos strings y son analizados como listas de direcciones » RFC822.

### Parámetros

`to`

  El destinatario

`subject`

  El asunto del correo

`message`

  El cuerpo del correo; ver la función imap_mail_compose().

`additional_headers`

  Un string conteniendo los encabezados adicionales a enviar con el correo

`cc`

`bcc`

  Los destinatarios especificados en el `bcc` recibirán el correo pero son excluidos de los encabezados.

`return_path`

  Utilizar este parámetro para especificar el camino de retorno en caso de fallo en la entrega del correo. Es útil cuando se utiliza PHP como cliente de correo para varios usuarios.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `additional_headers`, `cc`, `bcc`, y `return_path` son ahora nullable.

### Ver también

- mail() - Envío de correo
- imap_mail_compose() - Crea un mensaje MIME

# imap_mail_compose

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail_compose — Crea un mensaje MIME

### Descripción

function imap_mail_compose(array `$envelope`, array `$bodies`): string|false

Crea un mensaje MIME basado en el sobre `envelope` y las secciones `bodies`.

### Parámetros

`envelope`

  Un array asociativo que contiene los campos de los encabezados. Las claves válidas son: `"remail"`, `"return_path"`, `"date"`, `"from"`, `"reply_to"`, `"in_reply_to"`, `"subject"`, `"to"`, `"cc"`, `"bcc"` y `"message_id"`, que definen los encabezados respectivos al string dado. Para definir encabezados adicionales, la clave `"custom_headers"` es soportada, que espera un array de estos encabezados, por ejemplo `["User-Agent: My Mail Client"]`.

`bodies`

  Un array indexado de los cuerpos. El primer cuerpo es el cuerpo principal del mensaje; solo si es del tipo `TYPEMULTIPART`, los cuerpos siguientes serán tratados; estos cuerpos constituyen los cuerpos de las partes.

  Estructura de un Array de un Cuerpo
  Clave | Tipo | Descripción
  --- | --- | ---
  `type` | int | El tipo MIME. Uno de `TYPETEXT` (por omisión), `TYPEMULTIPART`, `TYPEMESSAGE`, `TYPEAPPLICATION`, `TYPEAUDIO`, `TYPEIMAGE`, `TYPEMODEL` o `TYPEOTHER`.
  `encoding` | int | El `Content-Transfer-Encoding`. Uno de `ENC7BIT` (por omisión), `ENC8BIT`, `ENCBINARY`, `ENCBASE64`, `ENCQUOTEDPRINTABLE` o `ENCOTHER`.
  `charset` | string | El juego de caracteres del parámetro del tipo MIME.
  `type.parameters` | array | Un array asociativo de nombre de parámetro `Content-Type` y sus valores.
  `subtype` | string | El subtipo MIME, e.g. `'jpeg'` para `TYPEIMAGE`.
  `id` | string | El `Content-ID`.
  `description` | string | El `Content-Description`.
  `disposition.type` | string | El `Content-Disposition`, e.g. `'attachment'`.
  `disposition` | array | Un array asociativo de nombre de parámetro `Content-Disposition` y sus valores.
  `contents.data` | string | La carga útil.
  `lines` | int | El tamaño de la carga útil en líneas.
  `bytes` | int | El tamaño de la carga útil en bytes.
  `md5` | string | La checksum MD5 de la carga útil.

### Valores devueltos

Devuelve el mensaje MIME como un string, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con imap_mail_compose()

    <?php

    $envelope["from"]= "joe@example.com";
    $envelope["to"]  = "foo@example.com";
    $envelope["cc"]  = "bar@example.com";

    $part1["type"] = TYPEMULTIPART;
    $part1["subtype"] = "mixed";

    $filename = "/tmp/imap.c.gz";
    $fp = fopen($filename, "r");
    $contents = fread($fp, filesize($filename));
    fclose($fp);

    $part2["type"] = TYPEAPPLICATION;
    $part2["encoding"] = ENCBINARY;
    $part2["subtype"] = "octet-stream";
    $part2["description"] = basename($filename);
    $part2["contents.data"] = $contents;

    $part3["type"] = TYPETEXT;
    $part3["subtype"] = "plain";
    $part3["description"] = "description3";
    $part3["contents.data"] = "contents.data3\n\n\n\t";

    $body[1] = $part1;
    $body[2] = $part2;
    $body[3] = $part3;

    echo nl2br(imap_mail_compose($envelope, $body));

    ?>

# imap_mail_copy

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail_copy — Copia los mensajes especificados en un buzón de correo

### Descripción

function imap_mail_copy(
IMAP\Connection `$imap`,
string `$message_nums`,
string `$mailbox`,
int `$flags` = 0
): bool

Copia los mensajes de correo electrónico especificados por `message_nums` en el buzón de correo especificado.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`message_nums`

  `message_nums` es un intervalo, y no solo una lista de números de mensaje (como se describe en la » RFC2060).

`mailbox`

  El nombre del buzón de correo, ver la documentación de la función imap_open() para más detalles

  Advertencia

  Pasar datos no confiables a este parámetro es inseguro, a menos que imap.enable_insecure_rsh esté desactivado.

`flags`

  `flags` es una máscara, que puede contener uno o varios de los siguientes valores:

  - `CP_UID` - la secuencia de números contiene UIDS
  - `CP_MOVE` - Borra los mensajes después de la copia. Si este flag está definido, la función se comporta de manera idéntica a imap_mail_move().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ver también

- imap_mail_move() - Mueve mensajes a una caja de correo

# imap_mail_move

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail_move — Mueve mensajes a una caja de correo

### Descripción

function imap_mail_move(
IMAP\Connection `$imap`,
string `$message_nums`,
string `$mailbox`,
int `$flags` = 0
): bool

imap_mail_move() mueve los mensajes especificados por `message_nums` a la caja de correo `mailbox`. Es importante destacar que los mensajes son en realidad copiados a la caja de correo `mailbox`, y los mensajes originales son marcados para ser eliminados. Esto implica que los mensajes en `mailbox` son asignados nuevos UIDs.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`message_nums`

  `message_nums` es un intervalo, y no solo una lista de mensajes (como se describe en la » RFC2060).

`mailbox`

  El nombre de la caja de correo, ver la documentación de la función imap_open() para más detalles

  Advertencia

  Pasar datos no confiables a este parámetro es inseguro, a menos que imap.enable_insecure_rsh esté desactivado.

`flags`

  `flags` es un campo de bits y puede contener un solo valor:

  - `CP_UID` - La secuencia de números contiene UIDs

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Notas

> Nota:

> imap_mail_move() marcará el correo electrónico original con un marcador de eliminación, para eliminarlo efectivamente, se requiere una llamada a imap_expunge().

### Ver también

- imap_mail_copy() - Copia los mensajes especificados en un buzón de correo

# imap_mailboxmsginfo

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mailboxmsginfo — Lee la información sobre el buzón de correo actual

### Descripción

function imap_mailboxmsginfo(IMAP\Connection `$imap`): stdClass

imap_mailboxmsginfo() verifica el estado actual del buzón de correo en el servidor. Es similar al uso de la función imap_status(), pero también proporciona el tamaño total de los mensajes del buzón de correo, lo que requiere un poco más de tiempo de ejecución.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.

### Valores devueltos

Devuelve un objeto con las siguientes propiedades:

Propiedades del buzón de correo
Date | Fecha de la última modificación del contenido del buzón de correo (fecha y hora actuales)
Driver | Controlador
Mailbox | Nombre del buzón de correo
Nmsgs | Número de mensajes
Recent | Número de mensajes recientes
Unread | Número de mensajes no leídos
Deleted | Número de mensajes eliminados
Size | Tamaño del buzón de correo

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imap_mailboxmsginfo()

    <?php

    $mbox = imap_open("{imap.example.org}INBOX", "username", "password")
          or die("Conexión imposible: " . imap_last_error());

    $check = imap_mailboxmsginfo($mbox);

    if ($check) {
        echo "Fecha : "     . $check->Date    . "<br />\n" ;
        echo "Controlador : "   . $check->Driver  . "<br />\n" ;
        echo "Buzón de correo : "  . $check->Mailbox . "<br />\n" ;
        echo "Mensajes : " . $check->Nmsgs   . "<br />\n" ;
        echo "Reciente : "   . $check->Recent  . "<br />\n" ;
        echo "No leído : "   . $check->Unread  . "<br />\n" ;
        echo "Eliminado : "  . $check->Deleted . "<br />\n" ;
        echo "Tamaño : "     . $check->Size    . "<br />\n" ;
    } else {
        echo "imap_mailboxmsginfo() ha fallado: " . imap_last_error() . "<br />\n";
    }

    imap_close($mbox);

    ?>

# imap_mime_header_decode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mime_header_decode — Decodifica los elementos MIME de un encabezado

### Descripción

function imap_mime_header_decode(string `$string`): array|false

Decodifica un mensaje MIME que contiene datos no ASCII (ver » RFC2047).

### Parámetros

`string`

  El texto MIME

### Valores devueltos

Los elementos decodificados se devuelven en un array de objetos. Cada uno de estos objetos tiene dos propiedades: `charset` y `text`.

Si el elemento no ha sido codificado, o, en otras palabras, si está en claro (plain US_ASCII), la propiedad `charset` se establece en `default`.

Esta función devuelve `false` en caso de fallo.

### Ejemplos

Ejemplo #1 Ejemplo con imap_mime_header_decode()

    <?php
    $text = "=?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@example.com>";

    $elements = imap_mime_header_decode($text);
    for ($i=0; $i<count($elements); $i++) {
        echo "Charset : {$elements[$i]->charset}\n";
        echo "Texto : {$elements[$i]->text}\n\n";
    }
    ?>

El ejemplo anterior mostrará:

    Charset: ISO-8859-1
    Texto: Keld Jørn Simonsen

    Charset: default
    Texto:  <keld@example.com>

En el ejemplo anterior, se encuentran dos elementos: el primero ha sido codificado en ISO-8859-1, y el segundo está en claro.

### Ver también

- imap_utf8() - Convierte texto en formato MIME a UTF-8

# imap_msgno

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_msgno — Devuelve el número de secuencia del mensaje para un UID dado

### Descripción

function imap_msgno(IMAP\Connection `$imap`, int `$message_uid`): int

Devuelve el número de secuencia del mensaje para el UID `message_uid`.

Esta función es el inverso de la función imap_uid().

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`message_uid`

  El UID del mensaje

### Valores devueltos

Devuelve el número de secuencia del mensaje para el UID `message_uid`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ver también

- imap_uid() - Devuelve el UID de un mensaje

# imap_mutf7_to_utf8

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

imap_mutf7_to_utf8 — Decodifica una string UTF-7 modificado en UTF-8

### Descripción

function imap_mutf7_to_utf8(string `$string`): string|false

Decodifica una string UTF-7 modificado (como se especifica en la RFC 2060, sección 5.1.3) en UTF-8.

> Nota:

> Esta función solo está disponible si libcclient exporta utf8_to_mutf7().

### Parámetros

`string`

  Una string codificada en UTF-7 modificado.

### Valores devueltos

Devuelve `string` convertida en UTF-8, o `false` si ocurre un error.

### Ver también

- imap_utf8_to_mutf7() - Codifica una string UTF-8 en UTF-7 modificado

# imap_num_msg

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_num_msg — Devuelve el número de mensajes en el buzón de correo actual

### Descripción

function imap_num_msg(IMAP\Connection `$imap`): int|false

Devuelve el número de mensajes en el buzón de correo actual.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.

### Valores devueltos

Devuelve el número de mensajes en el buzón de correo actual, en forma de un int, o `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ver también

- imap_num_recent() - Devuelve el número de mensajes recientes en el buzón de correo actual
- imap_status() - Devuelve la información de estado sobre un buzón de correo

# imap_num_recent

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_num_recent — Devuelve el número de mensajes recientes en el buzón de correo actual

### Descripción

function imap_num_recent(IMAP\Connection `$imap`): int

Devuelve el número de mensajes recientes en el buzón de correo actual.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.

### Valores devueltos

Devuelve el número de mensajes recientes en el buzón de correo actual, en forma de un int.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ver también

- imap_num_msg() - Devuelve el número de mensajes en el buzón de correo actual
- imap_status() - Devuelve la información de estado sobre un buzón de correo

# imap_open

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_open — Abre un flujo IMAP hacia un buzón de correo

### Descripción

function imap_open(
string `$mailbox`,
string `$user`,
string `$password`,
int `$flags` = 0,
int `$retries` = 0,
array `$options` = []
): IMAP\Connection|false

Abre un flujo IMAP hacia el buzón de correo `mailbox`.

Esta función también puede ser utilizada para abrir flujos en servidores POP3 y NNTP, pero algunas funciones y características solo están disponibles con servidores IMAP.

### Parámetros

`mailbox`

  Un nombre de buzón de correo está compuesto por una dirección de servidor y una dirección de buzón en ese servidor. La palabra reservada `INBOX` representa el buzón de correo del usuario actual. Los nombres de buzones de correo que contienen caracteres especiales (fuera del espacio ASCII) deben ser codificados con imap_utf7_encode().

  Advertencia

  Pasar datos no confiables a este parámetro es inseguro, a menos que imap.enable_insecure_rsh esté desactivado.

  La dirección del servidor, entre llaves '{' y '}', está compuesta por el nombre del servidor o su dirección IP, una especificación de protocolo (comenzando por '/') y un puerto opcional (especificado con ':').

  Esta parte es obligatoria en los parámetros del buzón de correo.

  Todos los nombres que comienzan con `{` son nombres remotos y tienen la forma `"{" nombre_sistema_remoto [":" puerto] [flags] "}" [nombre_buzon]` donde :

  - `remote_system_name` : Nombre de dominio de Internet o una dirección IP de servidor entre comillas.
  - `puerto` : número de puerto TCP (opcional), el valor por defecto es el valor del puerto para este servicio.
  - `flags` : opciones, ver la tabla siguiente.
  - `mailbox_name` : nombre del buzón remoto, por defecto : INBOX

  Flags opcionales para los nombres
  Flag | Descripción
  --- | ---
  `/service=`service | servicio para el acceso al buzón, por defecto : "imap"
  `/user=`user | nombre del usuario remoto para la identificación en el servidor
  `/authuser=`user | usuario remoto de identificación; si se especifica, este será el nombre del usuario cuya contraseña se utiliza (e.g. administrador)
  `/anonymous` | acceso remoto anónimo
  `/debug` | la telemetría de registro del protocolo en los logs de depuración de la aplicación
  `/secure` | no transmite una contraseña en claro a través de la red
  `/imap`, `/imap2`, `/imap2bis`, `/imap4`, `/imap4rev1` | equivalente a `/service=imap`
  `/pop3` | equivalente a `/service=pop3`
  `/nntp` | equivalente a `/service=nntp`
  `/norsh` | no utilizar rsh o ssh para establecer una sesión de pre identificación IMAP
  `/ssl` | utiliza `Secure Socket Layer` para cifrar la sesión
  `/validate-cert` | valida los certificados desde el servidor TLS/SSL (es el comportamiento por defecto)
  `/novalidate-cert` | no valida los certificados desde el servidor TLS/SSL, necesario si el servidor utiliza certificados autofirmados
  `/tls` | fuerza el uso de `start-TLS` para cifrar la sesión y rechaza las conexiones a los servidores que no lo soportan
  `/notls` | no utiliza `start-TLS` para cifrar la sesión, incluso con los servidores que lo soportan
  `/readonly` | solicita acceso de solo lectura en el buzón (solo IMAP; ignorado en NNTP, y un error con SMTP y POP3)

`user`

  El nombre de usuario

`password`

  La contraseña asociada con el usuario `user`

`flags`

  `flags` es una máscara de bits, que puede tomar uno o varios de los siguientes valores :

  - `OP_READONLY` : Abre un buzón de correo en modo de solo lectura
  - `OP_ANONYMOUS` : No utilizar, o modificar el fichero .newsrc para las noticias (solo NNTP)
  - `OP_HALFOPEN` : Para los nombres IMAP y NNTP, abre una conexión pero no abre un buzón de correo.
  - `CL_EXPUNGE` : Elimina automáticamente el buzón de correo de la lista, al finalizar el flujo (ver también imap_delete() y imap_expunge())
  - `OP_DEBUG` : negociaciones de depuración del protocolo
  - `OP_SHORTCACHE` : Caché corta (`elt` solamente)
  - `OP_SILENT` : No transmitir los eventos (uso interno)
  - `OP_PROTOTYPE` : Devuelve el prototipo del controlador
  - `OP_SECURE` : No realizar identificaciones no seguras
`retries`

  El número máximo de intentos de conexión.

`options`

  Parámetros de conexión; las claves pueden ser utilizadas para definir uno o varios parámetros de conexión :

  - `DISABLE_AUTHENTICATOR` - Desactiva las propiedades de autenticación

### Valores devueltos

Devuelve una instancia de IMAP\Connection en caso de éxito, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | Ahora devuelve una instancia de IMAP\Connection ; anteriormente, un resource era devuelto.

### Ejemplos

Ejemplo #1 Diferentes usos de imap_open()

    <?php
    // Para conectarse a un servidor IMAP funcionando en el puerto 143 de la
    // máquina local, haga esto :
    $mbox = imap_open("{localhost:143}INBOX", "user_id", "password");

    // Para conectarse a un servidor POP3 funcionando en el puerto 110 del
    // servidor local, haga esto :
    $mbox = imap_open ("{localhost:110/pop3}INBOX", "user_id", "password");

    // Para conectarse a un servidor SSL IMAP o POP3, añada /ssl
    // después de la especificación del protocolo :
    $mbox = imap_open ("{localhost:993/imap/ssl}INBOX", "user_id", "password");

    // Para conectarse a un servidor SSL IMAP o POP3 con un certificado autofirmado
    // añada /ssl/novalidate-cert después del protocolo :
    $mbox = imap_open ("{localhost:995/pop3/ssl/novalidate-cert}", "user_id", "password");

    // Para conectarse a un servidor NNTP que funciona en
    // el puerto 119 de la máquina local se puede utilizar el comando:
    $nntp = imap_open ("{localhost:119/nntp}comp.test", "", "");

    // Para conectarse a un servidor remoto, reemplace "localhost" por
    // el nombre o la dirección IP de la máquina.
    ?>

Ejemplo #2 Ejemplo con imap_open()

    <?php
    $mbox = imap_open("{imap.example.org:143}", "username", "password");

    echo "<h1>Buzones de correo</h1>\n";
    $folders = imap_listmailbox($mbox, "{imap.example.org:143}", "*");

    if ($folders == false) {
        echo "Llamada fallida<br />\n";
    } else {
        foreach ($folders as $val) {
            echo $val . "<br />\n";
        </foreach>
    }

    echo "<h1>Encabezados en INBOX</h1>\n";
    $headers = imap_headers($mbox);

    if ($headers == false) {
        echo "Llamada fallida<br />\n";
    } else {
        foreach ($headers as $val) {
            echo $val . "<br />\n";
        }
    }

    imap_close($mbox);
    ?>

### Ver también

- imap_close() - Termina un flujo IMAP

# imap_ping

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_ping — Verifica que el flujo IMAP sigue activo

### Descripción

function imap_ping(IMAP\Connection `$imap`): bool

Verifica que el flujo sigue activo, enviándole un ping. Esta función permite darse cuenta de que ha llegado un correo electrónico: es incluso el método recomendado para pruebas periódicas de verificación del correo. Esta función también puede servir para mantener una conexión abierta, con los servidores que tienen un tiempo de expiración.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.

### Valores devueltos

Devuelve `true` si el flujo sigue activo, `false` en caso contrario.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imap_ping()

    <?php

    $imap = imap_open("{imap.example.org}", "mailadmin", "password");

    // después de una pausa
    if (!imap_ping($imap)) {
        // realice un proceso para reconectar
    }

    ?>

# imap_qprint

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_qprint — Convierte una string con comillas en una string de 8 bits

### Descripción

function imap_qprint(string `$string`): string|false

Convierte la string con comillas `string` en una string de 8 bits (según la » RFC2045, sección 6.7).

### Parámetros

`string`

  Una string con comillas

### Valores devueltos

Devuelve una string de 8 bits, o `false` si ocurre un error.

### Ver también

- imap_8bit() - Convierte un string de 8 bits en un string codificado en Quoted-Printable

# imap_rename

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rename — Alias de imap_renamemailbox()

### Descripción

Esta función es un alias de: imap_renamemailbox().

# imap_renamemailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_renamemailbox — Renombra un buzón de correo

### Descripción

function imap_renamemailbox(IMAP\Connection `$imap`, string `$from`, string `$to`): bool

imap_renamemailbox() renombra el buzón de correo `from` a `to` (ver la función imap_open() para el formato de los nombres `mbox`).

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`from`

  El antiguo nombre del buzón de correo, ver la documentación de la función imap_open() para más detalles

  Advertencia

  Pasar datos no confiables a este parámetro es inseguro, a menos que imap.enable_insecure_rsh esté desactivado.

`to`

  El nuevo nombre del buzón de correo, ver la documentación de la función imap_open() para más detalles

  Advertencia

  Pasar datos no confiables a este parámetro es inseguro, a menos que imap.enable_insecure_rsh esté desactivado.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ver también

- imap_createmailbox() - Crea un nuevo buzón de correo
- imap_deletemailbox() - Borra una boîte aux lettres

# imap_reopen

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_reopen — Reabre un flujo IMAP hacia una nueva caja de correo

### Descripción

function imap_reopen(
IMAP\Connection `$imap`,
string `$mailbox`,
int `$flags` = 0,
int `$retries` = 0
): bool

Reabre la conexión especificada al servidor IMAP o NNTP, con una nueva caja de correo.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`mailbox`

  El nombre de la caja de correo, ver la documentación de la función imap_open() para más detalles

  Advertencia

  Pasar datos no confiables a este parámetro es inseguro, a menos que imap.enable_insecure_rsh esté desactivado.

`flags`

  `flags` es una máscara de bits, que puede contener los siguientes valores:

  - `OP_READONLY` - Abre una caja de correo en modo de solo lectura
  - `OP_ANONYMOUS` - No utilizar, o modificar el fichero .newsrc para las noticias (NNTP únicamente)
  - `OP_HALFOPEN` - Para los nombres IMAP y NNTP, abre una conexión pero no abre una caja de correo.
  - `OP_EXPUNGE` - Elimina silenciosamente el flujo reciclado
  - `CL_EXPUNGE` - Elimina automáticamente la caja de correo de la lista, al finalizar el flujo. (ver imap_delete() y imap_expunge()).
`retries`

  El número máximo de intentos de conexión

### Valores devueltos

Devuelve `true` si el flujo es reabierto, `false` en caso contrario.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imap_reopen()

    <?php
    $mbox = imap_open("{imap.example.org:143}INBOX", "username", "password") or die(implode(", ", imap_errors()));
    // ...
    imap_reopen($mbox, "{imap.example.org:143}INBOX.Sent") or die(implode(", ", imap_errors()));
    // ..
    ?>

# imap_rfc822_parse_adrlist

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rfc822_parse_adrlist — Analiza una dirección de correo electrónico

### Descripción

function imap_rfc822_parse_adrlist(string `$string`, string `$default_hostname`): array

Analiza la cadena `address`, tal como se define en la » RFC2822.

### Parámetros

`string`

  Un string que contiene las direcciones

`default_hostname`

  El nombre del host por omisión

### Valores devueltos

Devuelve un array de objetos. Las propiedades de los objetos son:

- `"mailbox"` : El nombre del buzón de correo (nombre de usuario)
- `"host"` : El nombre del host
- `"personal"` : El nombre personal
- `"adl"` : ruta de origen «at-domain»

### Ejemplos

Ejemplo #1 Ejemplo con imap_rfc822_parse_adrlist()

    <?php

    $address_string = "Joe Doe <doe@example.com>, postmaster@example.com, root";
    $address_array  = imap_rfc822_parse_adrlist($address_string, "example.com");
    if (!is_array($address_array) || count($address_array) < 1) {
        die("¡Error!\n");
    }

    foreach ($address_array as $id => $val) {
        echo "# $id\n";
        echo "  Buzón   : " . $val->mailbox . "\n";
        echo "  Host    : " . $val->host . "\n";
        echo "  Nombre  : " . $val->personal . "\n";
        echo "  adl     : " . $val->adl . "\n";
    }
    ?>

El ejemplo anterior mostrará:

    # 0
      Buzón   : doe
      Host    : example.com
      Nombre  : Joe Doe
      adl     :
    # 1
      Buzón   : postmaster
      Host    : example.com
      Nombre  :
      adl     :
    # 2
      Buzón   : root
      Host    : example.com
      Nombre  :
      adl     :

### Ver también

- imap_rfc822_parse_headers() - Analiza un encabezado de correo electrónico

# imap_rfc822_parse_headers

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rfc822_parse_headers — Analiza un encabezado de correo electrónico

### Descripción

function imap_rfc822_parse_headers(string `$headers`, string `$default_hostname` = "UNKNOWN"): stdClass

Analiza la cadena `headers` y devuelve un objeto que contiene diferentes elementos, similares a la función imap_header().

### Parámetros

`headers`

  Los datos a analizar

`default_hostname`

  El nombre del host por defecto

### Valores devueltos

Devuelve un objeto similar al devuelto por la función imap_header(), excepto por los flags y otras propiedades que provienen del servidor IMAP.

### Ver también

- imap_rfc822_parse_adrlist() - Analiza una dirección de correo electrónico

# imap_rfc822_write_address

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rfc822_write_address — Devuelve una dirección de correo electrónico formateada correctamente

### Descripción

function imap_rfc822_write_address(string `$mailbox`, string `$hostname`, string `$personal`): string|false

Devuelve una dirección de correo electrónico formateada correctamente según la » RFC2822.

### Parámetros

`mailbox`

  El nombre del buzón de correo, consulte la documentación de la función imap_open() para más detalles

  Advertencia

  Pasar datos no confiables a este parámetro es inseguro, a menos que imap.enable_insecure_rsh esté desactivado.

`hostname`

  La parte del host del correo electrónico

`personal`

  El nombre del propietario de la cuenta

### Valores devueltos

Devuelve una dirección de correo electrónico formateada correctamente según la » RFC2822, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con imap_rfc822_write_address()

    <?php
    echo imap_rfc822_write_address("hartmut", "example.com", "Hartmut Holzgraefe");
    ?>

El ejemplo anterior mostrará:

    Hartmut Holzgraefe <hartmut@example.com>

# imap_savebody

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

imap_savebody — Guarda una parte específica del cuerpo en un fichero

### Descripción

function imap_savebody(
IMAP\Connection `$imap`,
resource|string|int `$file`,
int `$message_num`,
string `$section` = "",
int `$flags` = 0
): bool

Guarda una parte del cuerpo del mensaje especificado.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`file`

  La ruta hacia el fichero de guardado, en forma de una string o un descriptor de fichero válido devuelto por la función fopen().

`message_num`

  El número del mensaje

`section`

  El número de la sección. Es una string de enteros, delimitados por una coma que corresponden al índice en la lista de secciones del cuerpo, tal como se prevé en la especificación IMAP4.

`flags`

  Una máscara que contiene una o más de las siguientes valores:

  - `FT_UID` - El número `message_num` es un UID
  - `FT_PEEK` - No definir el flag \Seen si no está ya definido
  - `FT_INTERNAL` - La string devuelta está en un formato interno, que no corresponde a CRLF.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ver también

- imap_fetchbody() - Devuelve una sección extraída del cuerpo de un mensaje

# imap_scan

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_scan — Alias de imap_listscan()

### Descripción

Esta función es un alias de: imap_listscan().

# imap_scanmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_scanmailbox — Alias de imap_listscan()

### Descripción

Esta función es un alias de: imap_listscan().

# imap_search

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_search — Devuelve un array de mensajes después de la búsqueda

### Descripción

function imap_search(
IMAP\Connection `$imap`,
string `$criteria`,
int `$flags` = `SE_FREE`,
string `$charset` = ""
): array|false

Realiza una búsqueda en el buzón de correo actual, en el flujo IMAP actual.

Por ejemplo, para buscar los mensajes no respondidos, enviados por mamá, se puede utilizar: "UNANSWERED FROM mamá". Las búsquedas parecen no distinguir entre mayúsculas y minúsculas. Esta lista de criterios proviene del código de un cliente C UW y puede ser incompleta o imprecisa. (ver también la » RFC1176, y en particular, la sección "tag SEARCH search_criteria").

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`criteria`

  Un string, delimitado por espacios, en el que se aceptan los siguientes palabras clave. Todos los argumentos de varias palabras (e.g. `FROM "joey smith"`) deben colocarse entre comillas. Los resultados deben coincidir con todas las entradas `criteria`.

  - ALL - devuelve todos los mensajes que cumplen con el resto del criterio.
  - ANSWERED - todos los mensajes con el flag \\ANSWERED
  - BCC "string" - todos los mensajes con la cadena "string" en el campo Bcc
  - BEFORE "date" - todos los mensajes con Date: antes de "date"
  - BODY "string" - todos los mensajes con "string" en el cuerpo
  - CC "string" - todos los mensajes con "string" en el campo Cc
  - DELETED - todos los mensajes borrados
  - FLAGGED - todos los mensajes con el flag \\FLAGGED (a veces interpretado como Importante o Urgente)
  - FROM "string" - todos los mensajes con la cadena "string" en el campo From
  - KEYWORD "string" - todos los mensajes con la cadena "string" como palabra clave
  - NEW - todos los mensajes nuevos
  - OLD - todos los mensajes antiguos
  - ON "date" - todos los mensajes con la fecha "date" como campo Date
  - RECENT - todos los mensajes con el flag \\RECENT
  - SEEN - todos los mensajes leídos (con el flag\\SEEN flag)
  - SINCE "date" - todos los mensajes con la fecha Date: después de "date"
  - SUBJECT "string" - todos los mensajes con la cadena "string" en el campo Subject
  - TEXT "string" - todos los mensajes con el texto "string"
  - TO "string" - todos los mensajes con la cadena "string" en el campo To
  - UNANSWERED - todos los mensajes no respondidos
  - UNDELETED - todos los mensajes no borrados
  - UNFLAGGED - todos los mensajes no marcados
  - UNKEYWORD "string" - todos los mensajes que no contienen la palabra clave "string"
  - UNSEEN - todos los mensajes no leídos
`flags`

  Los valores para `flags` son `SE_UID`, que hace que el array de respuesta contenga los UID en lugar de los números de secuencia.

`charset`

  Conjunto de caracteres MIME a utilizar durante la búsqueda de string.

### Valores devueltos

Devuelve un array de números de mensajes o de UID.

Devuelve `false` si la búsqueda no es comprendida, o bien si ningún mensaje ha sido encontrado.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imap_search()

    <?php
    $imap   = imap_open('{imap.example.com:993/imap/ssl}INBOX', 'foo@example.com', 'pass123', OP_READONLY);

    $some   = imap_search($imap, 'SUBJECT "HOWTO be Awesome" SINCE "8 August 2008"', SE_UID);
    $msgnos = imap_search($imap, 'ALL');
    $uids   = imap_search($imap, 'ALL', SE_UID);

    print_r($some);
    print_r($msgnos);
    print_r($uids);
    ?>

Resultado del ejemplo anterior es similar a:

    Array
    (
        [0] => 4
        [1] => 6
        [2] => 11
    )
    Array
    (
        [0] => 1
        [1] => 2
        [2] => 3
        [3] => 4
        [4] => 5
        [5] => 6
    )
    Array
    (
        [0] => 1
        [1] => 4
        [2] => 6
        [3] => 8
        [4] => 11
        [5] => 12
    )

### Ver también

- imap_listscan() - Lee la lista de buzones de correo y busca una cadena

# imap_set_quota

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

imap_set_quota — Modifica el cupo de un buzón de correo

### Descripción

function imap_set_quota(IMAP\Connection `$imap`, string `$quota_root`, int `$mailbox_size`): bool

Modifica el cupo del buzón de correo `quota_root`.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`quota_root`

  El buzón de correo cuyo cupo debe ser modificado. Debe seguir el formato estándar IMAP para un buzón de correo: `user.name`.

`mailbox_size`

  El tamaño máximo (en KB) para el buzón `quota_root`

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imap_set_quota()

    <?php
    $mbox = imap_open("{imap.example.org:143}", "mailadmin", "password");

    if (!imap_set_quota($mbox, "user.kalowsky", 3000)) {
        echo "Fallo al definir el cupo\n";
        return;
    }

    imap_close($mbox);
    ?>

### Notas

imap_get_quota() actualmente solo funciona con las bibliotecas c-client2000.

imap_set_quota() requiere que `imap` haya sido abierto con una cuenta de administrador, para tener los derechos necesarios: no funcionará con ningún otro usuario.

### Ver también

- imap_open() - Abre un flujo IMAP hacia un buzón de correo
- imap_get_quota() - Lee los cuotas de los buzones de correo así como las estadísticas sobre cada uno de ellos

# imap_setacl

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imap_setacl — Modifica el ACL de la bandeja de entrada

### Descripción

function imap_setacl(
IMAP\Connection `$imap`,
string `$mailbox`,
string `$user_id`,
string `$rights`
): bool

Define el ACL para la bandeja de entrada dada.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`mailbox`

  El nombre de la bandeja de entrada, ver la documentación de la función imap_open() para más detalles

  Advertencia

  Pasar datos no confiables a este parámetro es inseguro, a menos que imap.enable_insecure_rsh esté desactivado.

`user_id`

  El identificador del usuario cuyos derechos se desean definir.

`rights`

  Los derechos a otorgar al usuario. Pasar una cadena vacía borrará el ACL.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Notas

Esta función está actualmente disponible solo para los usuarios de la biblioteca `c-client2000` o superior.

### Ver también

- imap_getacl() - Devuelve el ACL para el buzón

# imap_setflag_full

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_setflag_full — Establece un flag en un mensaje

### Descripción

function imap_setflag_full(
IMAP\Connection `$imap`,
string `$sequence`,
string `$flag`,
int `$options` = 0
): true

imap_setflag_full() asigna el `flag` especificado a los mensajes de la `sequence` dada.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`sequence`

  Una secuencia de números de mensajes. Los mensajes deseados pueden ser enumerados con la sintaxis `X,Y`, o recuperar todos los mensajes de un intervalo con la sintaxis `X:Y`

`flag`

  Los flags que pueden ser modificados son `\Seen`, `\Answered`, `\Flagged`, `\Deleted`, y `\Draft` (como se define en la » RFC2060).

`options`

  `options` es una máscara de bits, que acepta únicamente el siguiente valor:

  - `ST_UID` - la secuencia contiene UID en lugar de números de secuencia.

### Valores devueltos

Retorna siempre `true`.

### Errores/Excepciones

Lanza una excepción ValueError si el argumento `options` es inválido.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.
8.0.0 | Una excepción ValueError es ahora lanzada para valores de argumento `options` inválidos. Anteriormente, se emitía una advertencia y la función devolvía `false`.

### Ejemplos

Ejemplo #1 Ejemplo con imap_setflag_full()

    <?php
    $mbox = imap_open("{imap.example.org:143}", "username", "password")
         or die("Conexión imposible: " . imap_last_error());

    $status = imap_setflag_full($mbox, "2,5", "\\Seen \\Flagged");

    echo gettype($status) . "\n";
    echo $status . "\n";

    imap_close($mbox);
    ?>

### Ver también

- imap_clearflag_full() - Elimina un flag en un mensaje

# imap_sort

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_sort — Ordena mensajes

### Descripción

function imap_sort(
IMAP\Connection `$imap`,
int `$criteria`,
bool `$reverse`,
int `$flags` = 0,
?string `$search_criteria` = `null`,
?string `$charset` = `null`
): array|false

Recupera y ordena los números de mensajes en función de los parámetros dados.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`criteria`

  Los criterios `criteria` pueden ser uno (y solo uno) de los siguientes:

  - `SORTDATE` : fecha del mensaje
  - `SORTARRIVAL` : fecha de llegada
  - `SORTFROM` : nombre del primer buzón de la dirección de origen (From address)
  - `SORTSUBJECT` : asunto del mensaje
  - `SORTTO` : nombre del primer buzón de destino (To address)
  - `SORTCC` : nombre del buzón de copia oculta (cc address)
  - `SORTSIZE` : tamaño del mensaje en bytes
`reverse`

  Si se debe ordenar en orden inverso.

`flags`

  Los `flags` son máscaras de bits, de uno o más de los siguientes elementos:

  - `SE_UID` : devuelve UID en lugar de números
  - `SE_NOPREFETCH` : no predescargar los mensajes encontrados
`search_criteria`

  Criterios de búsqueda en formato IMAP2. Para más detalles ver imap_search().

`charset`

  Conjunto de caracteres MIME a utilizar durante la búsqueda de string.

### Valores devueltos

Devuelve un array de números de mensajes ordenados en función de los parámetros proporcionados, o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.
8.0.0 | `reverse` es un bool en lugar de int.
8.0.0 | `search_criteria` y `charset` son ahora nullable.

# imap_status

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_status — Devuelve la información de estado sobre un buzón de correo

### Descripción

function imap_status(IMAP\Connection `$imap`, string `$mailbox`, int `$flags`): stdClass|false

Devuelve la información de estado sobre el buzón de correo `mailbox`.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`mailbox`

  El nombre del buzón de correo, ver la documentación de la función imap_open() para más detalles

  Advertencia

  Pasar datos no confiables a este parámetro es inseguro, a menos que imap.enable_insecure_rsh esté desactivado.

`flags`

  Los flags válidos son:

  - `SA_MESSAGES` - establece el valor de $status->messages al número de mensajes en el buzón de correo.
  - `SA_RECENT` - establece el valor de $status->recent al número de mensajes recientes en el buzón de correo.
  - `SA_UNSEEN` - establece el valor de $status->unseen al número de mensajes no leídos en el buzón de correo.
  - `SA_UIDNEXT` - establece el valor de $status->uidnext al siguiente valor de uid que será utilizado.
  - `SA_UIDVALIDITY` - establece el valor de $status->uidvalidity a una constante, que cambia cuando el uid del buzón de correo ya no es válido.
  - `SA_ALL` - establece todos los valores anteriores.

### Valores devueltos

Esta función devuelve un objeto que contiene la información de estado, o `false` si ocurre un error. El objeto tiene las siguientes propiedades: `messages`, `recent`, `unseen`, `uidnext`, y `uidvalidity`.

`flags` también está definido, que contiene una máscara con una de las constantes anteriores.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imap_status()

    <?php
    $mbox = imap_open("{imap.example.com}", "username", "password", OP_HALFOPEN)
          or die("Conexión imposible : " . imap_last_error());

    $status = imap_status($mbox, "{imap.example.org}INBOX", SA_ALL);
    if ($status) {
      echo "Mensajes :   " . $status->messages    . "<br />\n";
      echo "Reciente :   " . $status->recent      . "<br />\n";
      echo "No leído :   " . $status->unseen      . "<br />\n";
      echo "Próximo UID: " . $status->uidnext     . "<br />\n";
      echo "Validez del UID: " . $status->uidvalidity . "<br />\n";
    } else {
      echo "imap_status ha fallado : " . imap_last_error() . "\n";
    }

    imap_close($mbox);
    ?>

# imap_subscribe

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_subscribe — Suscribe a un buzón de correo

### Descripción

function imap_subscribe(IMAP\Connection `$imap`, string `$mailbox`): bool

Suscribe a un buzón de correo.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`mailbox`

  El nombre del buzón de correo, ver la documentación de la función imap_open() para más detalles

  Advertencia

  Pasar datos no confiables a este parámetro es inseguro, a menos que imap.enable_insecure_rsh esté desactivado.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ver también

- imap_unsubscribe() - Termina la suscripción a un buzón de correo

# imap_thread

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imap_thread — Devuelve el árbol de mensajes organizados por hilo

### Descripción

function imap_thread(IMAP\Connection `$imap`, int `$flags` = `SE_FREE`): array|false

Devuelve el árbol de mensajes organizados por hilo.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`flags`

### Valores devueltos

imap_thread() devuelve un array asociativo que contiene un árbol de mensajes organizados por hilo por `REFERENCES` o `false` en caso de error.

Cada mensaje en el buzón actual será representado por entradas en forma de árbol en el array resultante:

- $thread["XX.num"] - número del mensaje actual

- $thread["XX.next"]

- $thread["XX.branch"]

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ejemplos

Ejemplo #1 Ejemplo con imap_thread()

    <?php

    // Aquí, se muestran los hilos de un newsgroup en HTML

    $nntp = imap_open('{news.example.com:119/nntp}some.newsgroup', '', '');
    $threads = imap_thread($nntp);

    foreach ($threads as $key => $val) {
      $tree = explode('.', $key);
      if ($tree[1] == 'num') {
        $header = imap_headerinfo($nntp, $val);
        echo "<ul>\n\t<li>" . $header->fromaddress . "\n";
      } elseif ($tree[1] == 'branch') {
        echo "\t</li>\n</ul>\n";
      }
    }

    imap_close($nntp);

    ?>

# imap_timeout

(PHP 4 >= 4.3.3, PHP 5, PHP 7, PHP 8)

imap_timeout — Configura o devuelve el timeout

### Descripción

function imap_timeout(int `$timeout_type`, int `$timeout` = -1): int|bool

Define o devuelve el timeout imap.

### Parámetros

`timeout_type`

  Un valor entre los siguientes: `IMAP_OPENTIMEOUT`, `IMAP_READTIMEOUT`, `IMAP_WRITETIMEOUT`, o `IMAP_CLOSETIMEOUT`.

`timeout`

  El timeout, en segundos.

### Valores devueltos

Si el argumento `timeout` está definido, esta función devuelve `true` en caso de éxito y `false` si ocurre un error.

Si `timeout` no se proporciona o si se evalúa a -1, el timeout actual será devuelto como un int.

### Ejemplos

Ejemplo #1 Ejemplo con imap_timeout()

    <?php

    echo "El timeout actual es " . imap_timeout(IMAP_READTIMEOUT) . "\n";

    ?>

# imap_uid

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_uid — Devuelve el UID de un mensaje

### Descripción

function imap_uid(IMAP\Connection `$imap`, int `$message_num`): int|false

imap_uid() devuelve el UID para el mensaje `msgno`. Un UID es un identificador único que nunca cambia, mientras que el número del mensaje en la lista de mensajes puede cambiar con cualquier modificación del buzón de correo.

Es la función inversa de imap_msgno().

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`message_num`

  El número del mensaje.

### Valores devueltos

El UID de un mensaje dado.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Notas

> Nota:

> Esta funcionalidad no es soportada por los buzones de correo POP3.

### Ver también

- imap_msgno() - Devuelve el número de secuencia del mensaje para un UID dado

# imap_undelete

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_undelete — Elimina la marca de eliminación de un mensaje

### Descripción

function imap_undelete(IMAP\Connection `$imap`, string `$message_nums`, int `$flags` = 0): true

Elimina la marca de eliminación del mensaje `message_nums`, colocada con imap_delete() o imap_mail_move().

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`message_nums`

  Un string que representa uno o más mensajes en un formato de secuencia IMAP4 (`"n"`, `"n:m"`, o una combinación de estos, delimitados por comas).

`flags`

### Valores devueltos

Retorna siempre `true`.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ver también

- imap_delete() - Marca el fichero para el borrado, en el buzón de correo actual
- imap_mail_move() - Mueve mensajes a una caja de correo

# imap_unsubscribe

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_unsubscribe — Termina la suscripción a un buzón de correo

### Descripción

function imap_unsubscribe(IMAP\Connection `$imap`, string `$mailbox`): bool

Termina la suscripción al buzón de correo `mailbox`.

### Parámetros

`imap`
  Una instancia de IMAP\Connection.
`mailbox`

  El nombre del buzón de correo, ver la documentación de la función imap_open() para más detalles.

  Advertencia

  Pasar datos no confiables a este parámetro es inseguro, a menos que imap.enable_insecure_rsh esté desactivado.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El parámetro `imap` ahora espera una instancia de IMAP\Connection; anteriormente, se esperaba un resource `imap` válido.

### Ver también

- imap_subscribe() - Suscribe a un buzón de correo

# imap_utf7_decode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf7_decode — Decodifica una cadena codificada en UTF-7 modificado

### Descripción

function imap_utf7_decode(string `$string`): string|false

imap_utf7_decode() decodifica la cadena UTF-7 `string` en ISO-8859-1.

Esta función se utiliza para codificar los nombres de los buzones de correo que contienen caracteres internacionales fuera del espacio ASCII.

### Parámetros

`string`

  La codificación UTF-7 modificada está definida en la » RFC 2060, sección 5.1.3.

### Valores devueltos

Devuelve una string codificada en ISO-8859-1 y que contiene la misma secuencia de caracteres que en el parámetro `string`, o `false` si `string` contiene una secuencia UTF-7 modificada inválida o si `string` contiene un carácter que no forma parte del juego de caracteres ISO-8859-1.

### Ver también

- imap_utf7_encode() - Convierte una cadena ISO-8859-1 en texto UTF-7 modificado

# imap_utf7_encode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf7_encode — Convierte una cadena ISO-8859-1 en texto UTF-7 modificado

### Descripción

function imap_utf7_encode(string `$string`): string

Convierte una cadena `string` ISO-8859-1 en texto UTF-7 modificado.

Esta función se utiliza para codificar los nombres de las carpetas de correo que contienen caracteres internacionales fuera del espacio ASCII.

### Parámetros

`string`

  Una string ISO-8859-1.

### Valores devueltos

Devuelve los datos `string` codificados con la codificación UTF-7 modificada tal como se define en la » RFC 2060, sección 5.1.3.

### Ver también

- imap_utf7_decode() - Decodifica una cadena codificada en UTF-7 modificado

# imap_utf8

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf8 — Convierte texto en formato MIME a UTF-8

### Descripción

function imap_utf8(string `$mime_encoded_text`): string

Convierte el texto `mime_encoded_text` a UTF-8, si el conjunto de caracteres declarado es conocido por libc-client. De lo contrario, el texto proporcionado será decodificado, pero no convertido a UTF-8.

### Parámetros

`mime_encoded_text`

  Un string codificado en MIME. Las especificaciones de MIME y UTF8 están descritas en los » RFC2047 y » RFC2044.

### Valores devueltos

Devuelve el string decodificado y, si es posible, convertido a UTF-8.

### Ejemplos

Ejemplo #1 Uso básico de la función imap_utf8()

    <?php
    echo imap_utf8("Johannes =?ISO-8859-1?Q?Schl=FCter?=");
    ?>

Resultado del ejemplo anterior es similar a:

    Johannes Schlüter

### Ver también

- imap_mime_header_decode() - Decodifica los elementos MIME de un encabezado

# imap_utf8_to_mutf7

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

imap_utf8_to_mutf7 — Codifica una string UTF-8 en UTF-7 modificado

### Descripción

function imap_utf8_to_mutf7(string `$string`): string|false

Codifica una string UTF-8 en UTF-7 modificado (como se especifica en la RFC 2060, sección 5.1.3).

> Nota:

> Esta función solo está disponible si libcclient exporta utf8_to_mutf7().

### Parámetros

`string`

  Una string codificada en UTF-8.

### Valores devueltos

Devuelve `string` convertida en UTF-7 modificado, o `false` si ocurre un error.

### Ver también

- imap_mutf7_to_utf8() - Decodifica una string UTF-7 modificado en UTF-8

## Tabla de contenidos

- imap_8bit — Convierte un string de 8 bits en un string codificado en Quoted-Printable
- imap_alerts — Devuelve todas las alertas
- imap_append — Añade un mensaje en un buzón de correo
- imap_base64 — Decodifica un texto codificado en BASE64
- imap_binary — Convierte una string de 8 bits en una string en base64
- imap_body — Lee el cuerpo de un mensaje
- imap_bodystruct — Lee la estructura de una sección del cuerpo de un correo electrónico
- imap_check — Verifica el buzón de correo actual
- imap_clearflag_full — Elimina un flag en un mensaje
- imap_close — Termina un flujo IMAP
- imap_create — Alias de imap_createmailbox
- imap_createmailbox — Crea un nuevo buzón de correo
- imap_delete — Marca el fichero para el borrado, en el buzón de correo actual
- imap_deletemailbox — Borra una boîte aux lettres
- imap_errors — Devuelve todos los errores IMAP ocurridos
- imap_expunge — Elimina todos los mensajes marcados para su eliminación
- imap_fetch_overview — Lee el resumen de los encabezados de los mensajes
- imap_fetchbody — Devuelve una sección extraída del cuerpo de un mensaje
- imap_fetchheader — Devuelve el encabezado de un mensaje
- imap_fetchmime — Recupera los encabezados MIME para una sección particular del mensaje
- imap_fetchstructure — Lee la estructura de un mensaje
- imap_fetchtext — Alias de imap_body
- imap_gc — Borra la caché IMAP
- imap_get_quota — Lee los cuotas de los buzones de correo así como las estadísticas sobre cada uno de ellos
- imap_get_quotaroot — Lee los cuotas de cada usuario
- imap_getacl — Devuelve el ACL para el buzón
- imap_getmailboxes — Lista los buzones de correo y devuelve los detalles de cada uno
- imap_getsubscribed — Lista todas las carpetas de correo suscritas
- imap_header — Alias de imap_headerinfo
- imap_headerinfo — Lee la cabecera del mensaje
- imap_headers — Devuelve los encabezados de todos los mensajes de un buzón de correo
- imap_is_open — Verificar si el flujo IMAP sigue siendo válido
- imap_last_error — Devuelve el último error ocurrido
- imap_list — Lee la lista de buzones de correo
- imap_listmailbox — Alias de imap_list
- imap_listscan — Lee la lista de buzones de correo y busca una cadena
- imap_listsubscribed — Alias de imap_lsub
- imap_lsub — Lista todas las carpetas de correo registradas
- imap_mail — Envía un mensaje de correo electrónico
- imap_mail_compose — Crea un mensaje MIME
- imap_mail_copy — Copia los mensajes especificados en un buzón de correo
- imap_mail_move — Mueve mensajes a una caja de correo
- imap_mailboxmsginfo — Lee la información sobre el buzón de correo actual
- imap_mime_header_decode — Decodifica los elementos MIME de un encabezado
- imap_msgno — Devuelve el número de secuencia del mensaje para un UID dado
- imap_mutf7_to_utf8 — Decodifica una string UTF-7 modificado en UTF-8
- imap_num_msg — Devuelve el número de mensajes en el buzón de correo actual
- imap_num_recent — Devuelve el número de mensajes recientes en el buzón de correo actual
- imap_open — Abre un flujo IMAP hacia un buzón de correo
- imap_ping — Verifica que el flujo IMAP sigue activo
- imap_qprint — Convierte una string con comillas en una string de 8 bits
- imap_rename — Alias de imap_renamemailbox
- imap_renamemailbox — Renombra un buzón de correo
- imap_reopen — Reabre un flujo IMAP hacia una nueva caja de correo
- imap_rfc822_parse_adrlist — Analiza una dirección de correo electrónico
- imap_rfc822_parse_headers — Analiza un encabezado de correo electrónico
- imap_rfc822_write_address — Devuelve una dirección de correo electrónico formateada correctamente
- imap_savebody — Guarda una parte específica del cuerpo en un fichero
- imap_scan — Alias de imap_listscan
- imap_scanmailbox — Alias de imap_listscan
- imap_search — Devuelve un array de mensajes después de la búsqueda
- imap_set_quota — Modifica el cupo de un buzón de correo
- imap_setacl — Modifica el ACL de la bandeja de entrada
- imap_setflag_full — Establece un flag en un mensaje
- imap_sort — Ordena mensajes
- imap_status — Devuelve la información de estado sobre un buzón de correo
- imap_subscribe — Suscribe a un buzón de correo
- imap_thread — Devuelve el árbol de mensajes organizados por hilo
- imap_timeout — Configura o devuelve el timeout
- imap_uid — Devuelve el UID de un mensaje
- imap_undelete — Elimina la marca de eliminación de un mensaje
- imap_unsubscribe — Termina la suscripción a un buzón de correo
- imap_utf7_decode — Decodifica una cadena codificada en UTF-7 modificado
- imap_utf7_encode — Convierte una cadena ISO-8859-1 en texto UTF-7 modificado
- imap_utf8 — Convierte texto en formato MIME a UTF-8
- imap_utf8_to_mutf7 — Codifica una string UTF-8 en UTF-7 modificado

# La clase IMAP\Connection

(PHP 8 >= 8.1.0)

## Introducción

Una clase completamente opaca que reemplaza el resource `imap` a partir de PHP 8.1.0.

## Sinopsis de la Clase

final class IMAP\Connection {
}

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
  - Tipos de recursos
- Constantes predefinidas
- Funciones IMAP
  - imap_8bit — Convierte un string de 8 bits en un string codificado en Quoted-Printable
  - imap_alerts — Devuelve todas las alertas
  - imap_append — Añade un mensaje en un buzón de correo
  - imap_base64 — Decodifica un texto codificado en BASE64
  - imap_binary — Convierte una string de 8 bits en una string en base64
  - imap_body — Lee el cuerpo de un mensaje
  - imap_bodystruct — Lee la estructura de una sección del cuerpo de un correo electrónico
  - imap_check — Verifica el buzón de correo actual
  - imap_clearflag_full — Elimina un flag en un mensaje
  - imap_close — Termina un flujo IMAP
  - imap_create — Alias de imap_createmailbox
  - imap_createmailbox — Crea un nuevo buzón de correo
  - imap_delete — Marca el fichero para el borrado, en el buzón de correo actual
  - imap_deletemailbox — Borra una boîte aux lettres
  - imap_errors — Devuelve todos los errores IMAP ocurridos
  - imap_expunge — Elimina todos los mensajes marcados para su eliminación
  - imap_fetch_overview — Lee el resumen de los encabezados de los mensajes
  - imap_fetchbody — Devuelve una sección extraída del cuerpo de un mensaje
  - imap_fetchheader — Devuelve el encabezado de un mensaje
  - imap_fetchmime — Recupera los encabezados MIME para una sección particular del mensaje
  - imap_fetchstructure — Lee la estructura de un mensaje
  - imap_fetchtext — Alias de imap_body
  - imap_gc — Borra la caché IMAP
  - imap_get_quota — Lee los cuotas de los buzones de correo así como las estadísticas sobre cada uno de ellos
  - imap_get_quotaroot — Lee los cuotas de cada usuario
  - imap_getacl — Devuelve el ACL para el buzón
  - imap_getmailboxes — Lista los buzones de correo y devuelve los detalles de cada uno
  - imap_getsubscribed — Lista todas las carpetas de correo suscritas
  - imap_header — Alias de imap_headerinfo
  - imap_headerinfo — Lee la cabecera del mensaje
  - imap_headers — Devuelve los encabezados de todos los mensajes de un buzón de correo
  - imap_is_open — Verificar si el flujo IMAP sigue siendo válido
  - imap_last_error — Devuelve el último error ocurrido
  - imap_list — Lee la lista de buzones de correo
  - imap_listmailbox — Alias de imap_list
  - imap_listscan — Lee la lista de buzones de correo y busca una cadena
  - imap_listsubscribed — Alias de imap_lsub
  - imap_lsub — Lista todas las carpetas de correo registradas
  - imap_mail — Envía un mensaje de correo electrónico
  - imap_mail_compose — Crea un mensaje MIME
  - imap_mail_copy — Copia los mensajes especificados en un buzón de correo
  - imap_mail_move — Mueve mensajes a una caja de correo
  - imap_mailboxmsginfo — Lee la información sobre el buzón de correo actual
  - imap_mime_header_decode — Decodifica los elementos MIME de un encabezado
  - imap_msgno — Devuelve el número de secuencia del mensaje para un UID dado
  - imap_mutf7_to_utf8 — Decodifica una string UTF-7 modificado en UTF-8
  - imap_num_msg — Devuelve el número de mensajes en el buzón de correo actual
  - imap_num_recent — Devuelve el número de mensajes recientes en el buzón de correo actual
  - imap_open — Abre un flujo IMAP hacia un buzón de correo
  - imap_ping — Verifica que el flujo IMAP sigue activo
  - imap_qprint — Convierte una string con comillas en una string de 8 bits
  - imap_rename — Alias de imap_renamemailbox
  - imap_renamemailbox — Renombra un buzón de correo
  - imap_reopen — Reabre un flujo IMAP hacia una nueva caja de correo
  - imap_rfc822_parse_adrlist — Analiza una dirección de correo electrónico
  - imap_rfc822_parse_headers — Analiza un encabezado de correo electrónico
  - imap_rfc822_write_address — Devuelve una dirección de correo electrónico formateada correctamente
  - imap_savebody — Guarda una parte específica del cuerpo en un fichero
  - imap_scan — Alias de imap_listscan
  - imap_scanmailbox — Alias de imap_listscan
  - imap_search — Devuelve un array de mensajes después de la búsqueda
  - imap_set_quota — Modifica el cupo de un buzón de correo
  - imap_setacl — Modifica el ACL de la bandeja de entrada
  - imap_setflag_full — Establece un flag en un mensaje
  - imap_sort — Ordena mensajes
  - imap_status — Devuelve la información de estado sobre un buzón de correo
  - imap_subscribe — Suscribe a un buzón de correo
  - imap_thread — Devuelve el árbol de mensajes organizados por hilo
  - imap_timeout — Configura o devuelve el timeout
  - imap_uid — Devuelve el UID de un mensaje
  - imap_undelete — Elimina la marca de eliminación de un mensaje
  - imap_unsubscribe — Termina la suscripción a un buzón de correo
  - imap_utf7_decode — Decodifica una cadena codificada en UTF-7 modificado
  - imap_utf7_encode — Convierte una cadena ISO-8859-1 en texto UTF-7 modificado
  - imap_utf8 — Convierte texto en formato MIME a UTF-8
  - imap_utf8_to_mutf7 — Codifica una string UTF-8 en UTF-7 modificado
- IMAP\Connection — La clase IMAP\Connection

# Mail

# Introducción

La función mail() permite enviar correos.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Configuración en tiempo de ejecución

## Requerimientos

Para que las funciones Mail estén disponibles, es necesario que PHP tenga acceso al binario `sendmail` en el servidor durante la compilación. Si se utiliza otro programa de correo, como qmail o postfix, asegúrese de utilizar las API correctas. PHP comenzará a buscar sendmail en el PATH, y luego, en los siguientes directorios: `/usr/bin:/usr/sbin:/usr/etc:/etc:/usr/ucblib:/usr/lib`. Se recomienda encarecidamente tener sendmail disponible en el PATH. Además, el usuario que compile PHP debe tener los permisos necesarios para acceder al ejecutable sendmail.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Opciones de configuración para el correo
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
mail.add_x_header | "0" | `INI_PERDIR` |
mail.mixed_lf_and_crlf | "0" | `INI_SYSTEM`|`INI_PERDIR` | Disponible a partir de PHP 8.2.4
mail.log | NULL | `INI_SYSTEM`|`INI_PERDIR` |
mail.force_extra_parameters | NULL | `INI_SYSTEM`|`INI_PERDIR` |
SMTP | "localhost" | `INI_ALL` |
smtp_port | "25" | `INI_ALL` |
sendmail_from | NULL | `INI_ALL` |
sendmail_path | "/usr/sbin/sendmail -t -i" | `INI_SYSTEM` |

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`mail.add_x_header` bool

  Se añade un encabezado `X-PHP-Originating-Script` que incluye el UID del script, seguido por el nombre del fichero.

`mail.log` string

  La ruta del registro de todos los llamados a la función mail(). Las entradas del registro incluyen la ruta completa hacia el script, el número de la línea, las direcciones `To` así como los encabezados.

`mail.mixed_lf_and_crlf` bool

  Permite volver al indicador de fin de línea para los encabezados de correo electrónico y los cuerpos de mensaje en LF (Line Feed), imitando el comportamiento no conforme de PHP 7. Se proporciona como medida de compatibilidad para ciertos Agentes de Transferencia de Correo (MTA) no conformes que fallan al tratar correctamente CRLF (Retorno de carro + Line Feed) como indicador de fin de línea en los encabezados de correo electrónico y el contenido de los mensajes.

`mail.force_extra_parameters` string

  Permite forzar la adición del parámetro especificado como parámetro adicional para sendmail. Estos parámetros reemplazarán al quinto parámetro de la función mail().

  Además del comportamiento predeterminado para `INI_SYSTEM`, este valor también se puede establecer con `php_value` en httpd.conf (aunque no se recomienda).
`smtp` string

  Solo en Windows: nombre del host o dirección IP del SMTP que PHP debe utilizar para enviar un correo con la función mail().

`smtp_port` int

  Solo en Windows: número de puerto a utilizar para conectarse al servidor `SMTP` al enviar correo con la función mail(); por omisión, es 25.

`sendmail_from` string

  Solo en Windows: valor del campo `"From:"` que debe ser utilizado al enviar correo vía SMTP (solo en Windows). Esta directiva definirá también el encabezado `"Return-Path:"`.

`sendmail_path` string

  Localización del programa sendmail: habitualmente /usr/sbin/sendmail o /usr/lib/sendmail. configure intenta detectar la presencia de sendmail por sí mismo, y asigna este resultado por omisión. En caso de problemas de localización, puede establecerse un nuevo valor por omisión aquí.

  Todo sistema que no utilice sendmail debe establecer esta directiva al camino del programa de sustitución que reemplaza al servidor de correo, si aquel existe. Por ejemplo, los usuarios de » Qmail pueden definirla a /var/qmail/bin/sendmail o /var/qmail/bin/qmail-inject.

  qmail-inject no requiere opciones para tratar correctamente el correo.

  Esta directiva funciona también en Windows. Si está definida, smtp, smtp_port y sendmail_from son ignorados y se ejecuta el comando especificado.

# Funciones de mail

# ezmlm_hash

(PHP 4 >= 4.0.2, PHP 5, PHP 7)

ezmlm_hash — Calcula el hash solicitado por EZMLM

Advertencia

Esta función está OBSOLETA a partir de PHP 7.4.0, y ha sido ELIMINADA a partir de PHP 8.0.0. Depender de esta función está altamente desaconsejado.

### Descripción

function ezmlm_hash(string `$addr`): int

ezmlm_hash() calcula el hash necesario durante la gestión de listas de difusión EZMLM con una base de datos MySQL.

### Parámetros

`addr`

  La dirección de correo electrónico que debe ser hasheada.

### Valores devueltos

El valor del hash de `addr`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función ha sido eliminada.
7.2.0 | Esta función está obsoleta.

### Ejemplos

Ejemplo #1 Cálculo del hash y registro de un usuario de lista de difusión

    <?php

         $user = "joecool@example.com";
         $hash = ezmlm_hash($user);
         $query = sprintf("INSERT INTO sample VALUES (%s, '%s')", $hash, $user);
         $db->query($query); // utilización de la interfaz PHPLIB

    ?>

# mail

(PHP 4, PHP 5, PHP 7, PHP 8)

mail — Envío de correo

### Descripción

function mail(
string `$to`,
string `$subject`,
string `$message`,
array|string `$additional_headers` = [],
string `$additional_params` = ""
): bool

Envía un correo.

### Parámetros

`to`

  El o los destinatarios del correo.

  El formato de esta cadena debe corresponder con la » RFC 2822. A continuación se muestran algunos ejemplos:

  - destinatario@example.com
  - destinatario@example.com, otro_destinatario@example.com
  - Destinatario
  - Destinatario , Otro destinatario
`subject`

  Asunto del correo a enviar.

  Precaución

  El asunto debe cumplir con la » RFC 2047.

`message`

  Mensaje a enviar.

  Cada línea debe estar separada por un carácter `CRLF` (`\r\n`). Las líneas no deben contener más de 70 caracteres.

  Precaución

  (Solo Windows) Cuando PHP se comunica directamente con un servidor SMTP, si se encuentra un punto al inicio de una línea, será eliminado. Para evitar este comportamiento, reemplace estas ocurrencias con dos puntos.

      <?php
           $text = str_replace("\n.", "\n..", $text);
      ?>

`additional_headers` (opcional)

  String o array a insertar al final de los encabezados del correo.

  Este parámetro se utiliza típicamente para añadir encabezados adicionales (From, Cc y Bcc). Los encabezados adicionales deben estar separados por un carácter `CRLF` (`\r\n`). Si se utilizan datos externos para componer este encabezado, deben ser limpiados primero para evitar la inyección de datos no deseados en los encabezados.

  Si se pasa un array, sus claves son los nombres de los encabezados y sus valores son los valores de los encabezados respectivos.

  > Nota:

  > Al enviar un correo, el correo debe contener un encabezado `From`. Puede ser definido por el parámetro `additional_headers`, o puede ser un valor predeterminado definido en el php.ini.

  > No hacerlo causará un mensaje de error similar a `Warning: mail(): "sendmail_from" not set in php.ini or custom "From:" header missing`. El encabezado `From` también define el encabezado `Return-Path` al enviar directamente vía SMTP (solo Windows).

  > Nota:

  > Si el mensaje no es recibido, intente utilizar únicamente un carácter `LF` (`\n`). Algunos agentes de transferencia de correo Unix (por ejemplo » qmail) reemplazan automáticamente el carácter `LF` por el carácter `CRLF` (lo que equivale a duplicar el carácter `CR` si se utiliza el carácter `CRLF`). Esto debe ser un último recurso ya que no cumple con la » RFC 2822.

`additional_params` (opcional)

  El parámetro `additional_params` puede ser utilizado para pasar banderas adicionales como opciones a la línea de comandos configurada para ser utilizada para enviar los correos utilizando el parámetro de configuración `sendmail_path`. Por ejemplo, esto puede ser utilizado para definir la dirección del remitente del sobre al utilizar sendmail con la opción `-f`.

  Este parámetro es escapado por la función escapeshellcmd() internamente para prevenir la ejecución de un comando. La función escapeshellcmd() previene la ejecución de un comando, pero permite añadir parámetros adicionales. Por razones de seguridad, se recomienda al usuario limpiar este parámetro para evitar añadir parámetros no deseados al comando shell.

  Dado que la función escapeshellcmd() se aplica automáticamente, algunos caracteres permitidos en las direcciones de correo por las RFCs de internet ya no pueden ser utilizados. La función mail() no puede permitir estos caracteres, por lo tanto, en los programas donde su utilización es necesaria, debería utilizarse un método alternativo para el envío de correos (como el uso de un framework o una biblioteca.

  El usuario bajo el cual se ejecuta el servidor web debe ser añadido como usuario de confianza en la configuración de sendmail para que el encabezado `X-Warning` no sea añadido al mensaje cuando el remitente del sobre (-f) es definido utilizando este método. Para los usuarios de sendmail, este archivo es /etc/mail/trusted-users.

### Valores devueltos

Devuelve `true` si el correo ha sido aceptado para su entrega, `false` en caso contrario.

Es importante tener en cuenta que el hecho de que el correo haya sido aceptado para su entrega no garantiza que llegue a su destino.

### Historial de cambios

Versión | Descripción
--- | ---
7.2.0 | El parámetro `additional_headers` ahora acepta array.

### Ejemplos

Ejemplo #1 Envío de un correo

Uso de la función mail() para enviar un correo simple:

    <?php
    // El mensaje
    $message = "Línea 1\r\nLínea 2\r\nLínea 3";

    // En caso de que nuestras líneas contengan más de 70 caracteres, las cortamos utilizando wordwrap()
    $message = wordwrap($message, 70, "\r\n");

    // Envío del correo
    mail('caffeinated@example.com', 'Mi Asunto', $message);
    ?>

Ejemplo #2 Envío de un correo con encabezados adicionales

Añadir encabezados simples, especificando al MUA las direcciones `"From"` y `"Reply-To"`:

    <?php
         $to      = 'persona@example.com';
         $subject = 'el asunto';
         $message = '¡Hola!';
         $headers = 'From: webmaster@example.com' . "\r\n" .
         'Reply-To: webmaster@example.com' . "\r\n" .
         'X-Mailer: PHP/' . phpversion();

         mail($to, $subject, $message, $headers);
     ?>

Ejemplo #3 Envío de un correo con un array de encabezados adicionales

Este ejemplo envía el mismo correo que el ejemplo anterior, pero pasa los encabezados adicionales como un array (disponible desde PHP 7.2.0).

    <?php
    $to      = 'nadie@example.com';
    $subject = 'el asunto';
    $message = 'hola';
    $headers = array(
        'From' => 'webmaster@example.com',
        'Reply-To' => 'webmaster@example.com',
        'X-Mailer' => 'PHP/' . phpversion()
    );

    mail($to, $subject, $message, $headers);
    ?>

Ejemplo #4 Envío de un correo con un parámetro adicional de línea de comandos

El parámetro `additional_params` puede ser utilizado para pasar un parámetro adicional al programa configurado para ser utilizado para enviar los correos utilizando `sendmail_path`.

    <?php
         mail('persona@example.com', 'el asunto', 'el mensaje', null,
         '-fwebmaster@example.com');
    ?>

Ejemplo #5 Envío de correo HTML

También es posible enviar correos HTML con la función mail().

    <?php
         // Varios destinatarios
         $to  = 'johny@example.com, sally@example.com'; // note la coma

         // Asunto
         $subject = 'Calendario de cumpleaños para Agosto';

         // mensaje
         $message = '
         <html>
          <head>
           <title>Calendario de cumpleaños para Agosto</title>
          </head>
          <body>
           <p>¡Aquí están los cumpleaños que se avecinan en el mes de Agosto!</p>
           <table>
            <tr>
             <th>Persona</th><th>Día</th><th>Mes</th><th>Año</th>
            </tr>
            <tr>
             <td>Josiane</td><td>3</td><td>Agosto</td><td>1970</td>
            </tr>
            <tr>
             <td>Emma</td><td>26</td><td>Agosto</td><td>1973</td>
            </tr>
           </table>
          </body>
         </html>
         ';

         // Para enviar un correo HTML, el encabezado Content-type debe ser definido
         $headers[] = 'MIME-Version: 1.0';
         $headers[] = 'Content-type: text/html; charset=iso-8859-1';

         // Encabezados adicionales
         $headers[] = 'To: Mary <mary@example.com>, Kelly <kelly@example.com>';
         $headers[] = 'From: Cumpleaños <cumpleanos@example.com>';
         $headers[] = 'Cc: cumpleanos_archivo@example.com';
         $headers[] = 'Bcc: cumpleanos_verif@example.com';

         // Envío
         mail($to, $subject, $message, implode("\r\n", $headers));
    ?>

> Nota:

> Si se planea enviar correos HTML u otros más complejos, se recomienda utilizar el paquete PEAR » PEAR::Mail_Mime.

### Notas

> Nota:

> La implementación SMTP (solo en Windows) de la función mail() difiere significativamente de la implementación de sendmail. En primer lugar, no utiliza un programa local para componer los mensajes, sino que opera únicamente y directamente sobre los sockets, lo que significa que un `MTA` está necesariamente escuchando en un socket de red (que puede estar en la red local o en una máquina remota).

> En segundo lugar, los encabezados personalizados como `From:`, `Cc:`, `Bcc:` y `Date:` no son interpretados por el `MTA` en primer lugar, sino que son analizados por PHP.

> Además, el parámetro `to` no debe ser una dirección en el formato `"Algo <alguien@example.com>"`. El comando mail no analizará correctamente esto al comunicarse con el MTA.

> Nota:

> Es importante tener en cuenta que la función mail() no está recomendada para manejar grandes volúmenes de correos en un bucle. Esta función abre y cierra un socket SMTP para cada correo, lo que no es muy eficiente.

> Para enviar grandes volúmenes de correos, consulte los paquetes » PEAR::Mail y » PEAR::Mail_Queue.

> Nota:

> Las siguientes RFC pueden ser útiles: » RFC 1896, » RFC 2045, » RFC 2046, » RFC 2047, » RFC 2048, » RFC 2049 y » RFC 2822.

### Ver también

- mb_send_mail() - Envía un correo electrónico codificado
- imap_mail() - Envía un mensaje de correo electrónico
- » PEAR::Mail
- » PEAR::Mail_Mime

## Tabla de contenidos

- ezmlm_hash — Calcula el hash solicitado por EZMLM
- mail — Envío de correo

- Instalación/Configuración
  - Requerimientos
  - Configuración en tiempo de ejecución
- Funciones de mail
  - ezmlm_hash — Calcula el hash solicitado por EZMLM
  - mail — Envío de correo

# Mailparse

# Introducción

Mailparse es una extensión para analizar y trabajar con los mensajes de correo electrónico. Esto puede tratarse con los mensajes compatibles » RFC 822 y » RFC 2045 (`MIME`).

Mailparse está basado en flujo, lo que significa que no guarda en memoria las copias de los archivos que procesa - lo que es muy eficiente para recursos cuando se trata de mensajes de gran tamaño.

> Nota: Mailparse requiere la extensión mbstring, y mbstring debe cargarse antes de mailparse.

# Instalación/Configuración

## Tabla de contenidos

- Instalación
- Configuración en tiempo de ejecución
- Tipos de recursos

## Instalación

Esta extensión » PECL no está integrada en PHP. Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/mailparse.

Para poder utilizar estas funciones se debe compilar PHP con soporte para mailparse mediante la opción de configuración --enable-mailparse.

Los usuarios de windows deben habilitar php_mailparse.dll en el fichero php.ini con el fin de usar estas funciones. Los binarios Windows (los archivos DLL) para esta extensión PECL están disponibles en el sitio web PECL.

Es necesario que la extensión mbstring esté cargada antes que mailparse.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Mailparse Opciones de configuración
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
mailparse.def_charset | "us-ascii" | `INI_SYSTEM` |

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`mailparse.def_charset` string
  El juego de caracteres por omisión.

## Tipos de recursos

Mailparse define el tipo de recurso `mailparse_mail_structure`, que es devuelto por mailparse_msg_create() y mailparse_msg_parse_file().

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`MAILPARSE_EXTRACT_OUTPUT` (int)
`MAILPARSE_EXTRACT_STREAM` (int)
`MAILPARSE_EXTRACT_RETURN` (int)

# Funciones Mailparse

# mailparse_determine_best_xfer_encoding

(PECL mailparse >= 0.9.0)

mailparse_determine_best_xfer_encoding — Obtiene la mejor forma de codificar

### Descripción

function mailparse_determine_best_xfer_encoding(resource `$fp`): string

Encuentra la mejor forma de codificar el contenido leído del apuntador de archivo dado.

### Parámetros

`fp`
  Un apuntador de archivo válido, que reciba operaciones de búsqueda.

### Valores devueltos

Devuelve una de las codificaciones de caracteres soportadas por el módulo mbstring.

### Ejemplos

Ejemplo #1 Ejemplo de mailparse_determine_best_xfer_encoding()

    <?php

    $aa = fopen('alguncorreo.eml', 'r');
    echo 'Mejor codificación: ' . mailparse_determine_best_xfer_encoding($aa);

    ?>

Resultado del ejemplo anterior es similar a:

    Mejor codificación: 7bit

# mailparse_msg_create

(PECL mailparse >= 0.9.0)

mailparse_msg_create — Crea un recurso de correo mime

### Descripción

function mailparse_msg_create(): resource

Crea un recurso tipo correo `MIME`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un recurso que puede ser usado para interpretar un mensaje.

### Notas

> Nota: Se recomienda llamar a mailparse_msg_free() en el resultado de esta función, cuando ya no sea necesaria, para evitar fugas de memoria

### Ver también

- mailparse_msg_free() - Libera un recurso MIME
- mailparse_msg_parse_file() - Procesa un archivo

# mailparse_msg_extract_part

(PECL mailparse >= 0.9.0)

mailparse_msg_extract_part — Extrae/decodifica una sección de mensaje

### Descripción

function mailparse_msg_extract_part(resource `$mimemail`, string `$msgbody`, callable `$callbackfunc` = ?): void
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`mimemail`
  Un recurso `MIME` válido.
`msgbody`
`callbackfunc`

### Valores devueltos

No se retorna ningún valor.

### Ver también

- mailparse_msg_extract_part_file() - Extrae/decodifica una sección de mensaje
- mailparse_msg_extract_whole_part_file() - Extrae una sección del mensaje incluyendo cabeceras sin descodificar la transferencia codificada

# mailparse_msg_extract_part_file

(PECL mailparse >= 0.9.0)

mailparse_msg_extract_part_file — Extrae/decodifica una sección de mensaje

### Descripción

function mailparse_msg_extract_part_file(resource `$mimemail`, mixed `$filename`, callable `$callbackfunc` = ?): string

Extrae/decodifica una sección de mensaje del archivo indicado.

Los contenidos de la sección serán decodificados de acuerdo a su codificación de transferencia - se soportan base64, imprimible-con-comillas y texto uuencode.

### Parámetros

`mimemail`
  Un recurso `MIME` válido, creado con mailparse_msg_create().
`filename`
  Puede ser un nombre de archivo o un recurso de secuencia válido.
`callbackfunc`
  Si se define, este parámetro debe ser una llamada de retorno válida, a la cual le será pasada la sección extraída, o `null` para asegurarse de que esta función devuelva la sección extraída. Si no se especifica, los contenidos serán enviados a "stdout".

### Valores devueltos

Si `callbackfunc` es diferente de `null` devuelve `true` en caso de éxito.

Si `callbackfunc` es `null`, devuelve la sección extraída como una cadena.

Devuelve `false` en caso de fallo.

### Ver también

- mailparse_msg_extract_part() - Extrae/decodifica una sección de mensaje
- mailparse_msg_extract_whole_part_file() - Extrae una sección del mensaje incluyendo cabeceras sin descodificar la transferencia codificada

# mailparse_msg_extract_whole_part_file

(PECL mailparse >= 0.9.0)

mailparse_msg_extract_whole_part_file — Extrae una sección del mensaje incluyendo cabeceras sin descodificar la transferencia codificada

### Descripción

function mailparse_msg_extract_whole_part_file(resource `$mimemail`, string `$filename`, callable `$callbackfunc` = ?): string
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`mimemail`
  Un recurso `MIME` válido.
`filename`
`callbackfunc`

### Valores devueltos

### Ver también

- mailparse_msg_extract_part() - Extrae/decodifica una sección de mensaje
- mailparse_msg_extract_part_file() - Extrae/decodifica una sección de mensaje

# mailparse_msg_free

(PECL mailparse >= 0.9.0)

mailparse_msg_free — Libera un recurso MIME

### Descripción

function mailparse_msg_free(resource `$mimemail`): bool

Libera un recurso `MIME`.

### Parámetros

`mimemail`
  Un recurso `MIME` válido reservado por mailparse_msg_create() o mailparse_msg_parse_file().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- mailparse_msg_create() - Crea un recurso de correo mime
- mailparse_msg_parse_file() - Procesa un archivo

# mailparse_msg_get_part

(PECL mailparse >= 0.9.0)

mailparse_msg_get_part — Devuelve un gestor sobre una sección dada en un mensaje mime

### Descripción

function mailparse_msg_get_part(resource `$mimemail`, string `$mimesection`): resource
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`mimemail`
  Un recurso `MIME` válido.
`mimesection`

# mailparse_msg_get_part_data

(PECL mailparse >= 0.9.0)

mailparse_msg_get_part_data — Devuelve una matriz asociativa de información sobre el mensaje

### Descripción

function mailparse_msg_get_part_data(resource `$mimemail`): array
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`mimemail`
  Un recurso `MIME` válido.

# mailparse_msg_get_structure

(PECL mailparse >= 0.9.0)

mailparse_msg_get_structure — Devuelve una matriz de nombres de sección mime en el mensaje dado

### Descripción

function mailparse_msg_get_structure(resource `$mimemail`): array
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`mimemail`
  Un recurso `MIME` válido.

# mailparse_msg_parse

(PECL mailparse >= 0.9.0)

mailparse_msg_parse — Procesar datos incrementalmente sobre un búfer

### Descripción

function mailparse_msg_parse(resource `$mimemail`, string `$data`): bool

Procesa datos incrementalmente al interior del recurso de correo mime entregado.

Esta función le permite secuenciar porciones de un archivo en pedazos, en lugar de leer y procesarlo en su totalidad.

### Parámetros

`mimemail`
  Un recurso `MIME` válido.
`data`

  > Nota: El último trozo de `data` debe terminar con una nueva línea (`CRLF`); de lo contrario, no se analizará la última línea del mensaje.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# mailparse_msg_parse_file

(PECL mailparse >= 0.9.0)

mailparse_msg_parse_file — Procesa un archivo

### Descripción

function mailparse_msg_parse_file(string `$filename`): resource

Procesa un archivo. Este es el modo óptimo de interpretar un archivo que tenga en disco.

### Parámetros

`filename`
  Ruta al archivo que contiene el mensaje. El archivo es abierto y secuenciado a través del analizador sintáctico.

  > Nota: El mensaje contenido en `filename` debe terminar con una nueva línea (`CRLF`); de lo contrario, no se analizará la última línea del mensaje.

### Valores devueltos

Devuelve un recurso `MIME` que representa la estructura, o `false` en caso de error.

### Notas

> Nota: Se recomienda llamar a mailparse_msg_free() en el resultado de esta función, cuando ya no sea necesaria, para evitar fugas de memoria

### Ver también

- mailparse_msg_free() - Libera un recurso MIME
- mailparse_msg_create() - Crea un recurso de correo mime

# mailparse_rfc822_parse_addresses

(PECL mailparse >= 0.9.0)

mailparse_rfc822_parse_addresses — Procesa direcciones compatibles con RFC 822

### Descripción

function mailparse_rfc822_parse_addresses(string `$addresses`): array

Procesa una lista de recipientes compatible con » RFC 822, tal como la que es encontrada en una cabecera `To:`.

### Parámetros

`addresses`
  Una cadena que contiene direcciones, como: `Wez Furlong <wez@example.com>, pepe@example.com`

  > Nota: Esta cadena no debe contener el nombre de la cabecera.

### Valores devueltos

Devuelve una matriz de matrices asociativas con las siguientes claves para cada recipiente:

`display` | El nombre del recipiente, para propósitos de muestra. Si esta parte no es definida para un recipiente, esta clave contendrá el mismo valor que `address`.
`address` | La dirección de correo electrónico
`is_group` | `true` si el recipiente es un grupo de noticias, `false` de lo contrario.

### Ejemplos

Ejemplo #1 Ejemplo de mailparse_rfc822_parse_addresses()

    <?php

    $to = 'Wez Furlong <wez@example.com>, pepe@example.com';
    var_dump(mailparse_rfc822_parse_addresses($to));

    ?>

El ejemplo anterior mostrará:

    array(2) {
      [0]=>
      array(3) {
        ["display"]=>
        string(11) "Wez Furlong"
        ["address"]=>
        string(15) "wez@example.com"
        ["is_group"]=>
        bool(false)
      }
      [1]=>
      array(3) {
        ["display"]=>
        string(16) "pepe@example.com"
        ["address"]=>
        string(16) "pepe@example.com"
        ["is_group"]=>
        bool(false)
      }
    }

# mailparse_stream_encode

(PECL mailparse >= 0.9.0)

mailparse_stream_encode — Secuencia datos desde un apuntador de archivo, codifica y escribe a fp_destino

### Descripción

function mailparse_stream_encode(resource `$sourcefp`, resource `$destfp`, string `$encoding`): bool

Secuencia datos del apuntador de archivo fuente, aplica la `codificacion` y escribe al apuntador de archivo de destino.

### Parámetros

`sourcefp`
  Un gestor de archivo válido. El archivo es secuenciado a través del procesador.
`destfp`
  El gestor de archivo de destino, en el cual los datos codificados serán escritos.
`encoding`
  Una de las codificaciones de caracteres soportadas por el módulo mbstring.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo de mailparse_stream_encode()

    <?php

    // Contenido de email.eml: hola, este es un trozo de texto=hola.
    $aa = fopen('email.eml', 'r');

    $dest = tmpfile();

    mailparse_stream_encode($aa, $dest, "quoted-printable");

    rewind($dest);

    // Mostrar el contenido del nuevo archivo
    fpassthru($dest);

    ?>

El ejemplo anterior mostrará:

    hola, este es un trozo de texto=3Dhola.

# mailparse_uudecode_all

(PECL mailparse >= 0.9.0)

mailparse_uudecode_all — Procesa los datos desde un apuntador a archivo y extrae cada archivo embebido con codificación uu

### Descripción

function mailparse_uudecode_all(resource `$fp`): array

Lee los datos del apuntador de archivo dado y extrae cada archivo codificado mediante uuencode embebido en un archivo temporal.

### Parámetros

`fp`
  Un apuntador de archivo válido.

### Valores devueltos

Devuelve una matriz de matrices asociativas, listando la información de cada archivo.

`filename` | Ruta al nombre de archivo temporal creado
`origfilename` | El nombre de archivo original, solo para partes codificadas mediante uuencode

La primera entrada es el cuerpo del mensaje. Las siguientes son los archivos uuencode decodificados.

### Ejemplos

Ejemplo #1 Ejemplo de mailparse_uudecode_all()

    <?php

    $texto = <<<EOD
    To: fred@example.com

    hola, esto es un texto cualquiera.
    bla bla bla.

    begin 644 test.txt
    /=&AI<R!I<R!A('1E<W0*
    `
    end

    EOD;

    $aa = tmpfile();
    fwrite($aa, $texto);

    $datos = mailparse_uudecode_all($aa);

    echo "CUERPO\n";
    readfile($datos[0]["filename"]);
    echo "UUE ({$datos[1]['origfilename']})\n";
    readfile($datos[1]["filename"]);

    // Limpiar
    unlink($datos[0]["filename"]);
    unlink($datos[1]["filename"]);

    ?>

El ejemplo anterior mostrará:

    CUERPO
    To: fred@example.com

    hola, esto es un texto cualquiera.
    bla bla bla.

    UUE (test.txt)
    this is a test

## Tabla de contenidos

- mailparse_determine_best_xfer_encoding — Obtiene la mejor forma de codificar
- mailparse_msg_create — Crea un recurso de correo mime
- mailparse_msg_extract_part — Extrae/decodifica una sección de mensaje
- mailparse_msg_extract_part_file — Extrae/decodifica una sección de mensaje
- mailparse_msg_extract_whole_part_file — Extrae una sección del mensaje incluyendo cabeceras sin descodificar la transferencia codificada
- mailparse_msg_free — Libera un recurso MIME
- mailparse_msg_get_part — Devuelve un gestor sobre una sección dada en un mensaje mime
- mailparse_msg_get_part_data — Devuelve una matriz asociativa de información sobre el mensaje
- mailparse_msg_get_structure — Devuelve una matriz de nombres de sección mime en el mensaje dado
- mailparse_msg_parse — Procesar datos incrementalmente sobre un búfer
- mailparse_msg_parse_file — Procesa un archivo
- mailparse_rfc822_parse_addresses — Procesa direcciones compatibles con RFC 822
- mailparse_stream_encode — Secuencia datos desde un apuntador de archivo, codifica y escribe a fp_destino
- mailparse_uudecode_all — Procesa los datos desde un apuntador a archivo y extrae cada archivo embebido con codificación uu

- Instalación/Configuración
  - Instalación
  - Configuración en tiempo de ejecución
  - Tipos de recursos
- Constantes predefinidas
- Funciones Mailparse
  - mailparse_determine_best_xfer_encoding — Obtiene la mejor forma de codificar
  - mailparse_msg_create — Crea un recurso de correo mime
  - mailparse_msg_extract_part — Extrae/decodifica una sección de mensaje
  - mailparse_msg_extract_part_file — Extrae/decodifica una sección de mensaje
  - mailparse_msg_extract_whole_part_file — Extrae una sección del mensaje incluyendo cabeceras sin descodificar la transferencia codificada
  - mailparse_msg_free — Libera un recurso MIME
  - mailparse_msg_get_part — Devuelve un gestor sobre una sección dada en un mensaje mime
  - mailparse_msg_get_part_data — Devuelve una matriz asociativa de información sobre el mensaje
  - mailparse_msg_get_structure — Devuelve una matriz de nombres de sección mime en el mensaje dado
  - mailparse_msg_parse — Procesar datos incrementalmente sobre un búfer
  - mailparse_msg_parse_file — Procesa un archivo
  - mailparse_rfc822_parse_addresses — Procesa direcciones compatibles con RFC 822
  - mailparse_stream_encode — Secuencia datos desde un apuntador de archivo, codifica y escribe a fp_destino
  - mailparse_uudecode_all — Procesa los datos desde un apuntador a archivo y extrae cada archivo embebido con codificación uu

- IMAP — IMAP, POP3 y NNTP
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones IMAP
  - IMAP\Connection — La clase IMAP\Connection
- Mail
  - Instalación/Configuración
  - Funciones de mail
- Mailparse
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones Mailparse

# Extensiones matemáticas

# Matemáticas de precisión arbitraria BCMath

# Introducción

Para matemáticas de precisión arbitraria, PHP ofrece BCMath, que admite números de cualquier tamaño y precisión de hasta `2147483647` (o `0x7FFFFFFF`) dígitos decimales, si hay suficiente memoria, representados como cadenas.

Números válidos (también conocidos como bien formados) en BCMath son cadenas que coinciden con la expresión regular `/^[+-]?[0-9]*(\.[0-9]*)?$/`.

Precaución

Pasar valores de tipo float a una función de BCMath que espera un string como operando puede no tener el efecto deseado debido a la forma en que PHP convierte valores de tipo float a string, es decir, que el string puede estar en notación exponencial (que no es compatible con BCMath), y que, antes de PHP 8.0.0, el separador decimal dependía de la configuración regional (mientras que BCMath siempre espera un punto decimal).

    <?php
    $num1 = 0; // (string) 0 => '0'
    $num2 = -0.000005; // (string) -0.000005 => '-5.05E-6'
    echo bcadd($num1, $num2, 6); // => '0.000000'

    setlocale(LC_NUMERIC, 'de_DE'); // Utiliza una coma decimal
    $num2 = 1.2; // (string) 1.2 => '1,2'
    echo bcsub($num1, $num2, 1); // => '0.0'
    ?>

# Instalación/Configuración

## Tabla de contenidos

- Instalación
- Configuración en tiempo de ejecución

## Instalación

Esta función solamente está disponible si PHP está configurado con --enable-bcmath.

La versión Windows de PHP dispone del soporte automático de esta extensión. No es necesario añadir ninguna biblioteca adicional para disponer de estas funciones.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

BCmath Opciones de Configuración
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
bcmath.scale | "0" | `INI_ALL` |

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`bcmath.scale` integer

  Número de dígitos decimales para todas las funciones bcmath. Ver también bcscale().

  > Nota: BcMath\Number no se ve afectado por esta configuración.

# Funciones de BC Math

# bcadd

(PHP 4, PHP 5, PHP 7, PHP 8)

bcadd — Suma dos números de precisión arbitrária

### Descripción

function bcadd(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

Suma `num1` y `num2`.

### Parámetros

`num1`

  El operador izquierdo, como una cadena.

`num2`

  El operador derecho, como una cadena

`scale`
  Este parámetro se utiliza para establecer el número de dígitos después del punto decimal en el resultado. Si es `null`, se establecerá por defecto en la escala predeterminada establecida con bcscale(), o se utilizará el valor de la directiva INI `bcmath.scale`.

### Valores devueltos

La suma de dos operandos, como una cadena.

### Errores/Excepciones

Esta función lanza una excepción ValueError en los siguientes casos:

- `num1` o `num2` no es una cadena numérica bien formada de BCMath.
- `scale` está fuera del rango válido.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `scale` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo bcadd()

    <?php

    $a = '1.234';
    $b = '5';

    echo bcadd($a, $b);     // 6
    echo bcadd($a, $b, 4);  // 6.2340

    ?>

### Ver también

- bcsub() - Resta un número de precisión arbitraria de otro
- BcMath\Number::add() - Añadir un número de precisión arbitraria

# bcceil

(PHP 8 >= 8.4.0)

bcceil — Redondea al alza un número de precisión arbitraria

### Descripción

function bcceil(string `$num`): string

Devuelve el valor entero superior redondeando `num` si es necesario.

### Parámetros

`num`
  El valor a redondear.

### Valores devueltos

Devuelve un string numérico representando `num` redondeado al alza al entero más cercano.

### Errores/Excepciones

Esta función lanza una ValueError si `num` no es un string numérico BCMath bien formado.

### Ejemplos

Ejemplo #1 Ejemplo de bcceil()

    <?php
    var_dump(bcceil('4.3'));
    var_dump(bcceil('9.999'));
    var_dump(bcceil('-3.14'));
    ?>

El ejemplo anterior mostrará:

    string(1) "5"
    string(2) "10"
    string(2) "-3"

### Ver también

- bcfloor() - Redondea hacia abajo un número de precisión arbitraria
- bcround() - Redondea un número de precisión arbitraria
- BcMath\Number::ceil() - Redondea al alza un número de precisión arbitraria

# bccomp

(PHP 4, PHP 5, PHP 7, PHP 8)

bccomp — Comparar dos números de gran tamaño

### Descripción

function bccomp(string `$num1`, string `$num2`, ?int `$scale` = `null`): int

Compara el operando `num1` con `num2` y devuelve el resultado en forma de un int.

### Parámetros

`num1`

  El operador izquierdo, como una cadena.

`num2`

  El operador derecho, como una cadena

`scale`
  Este parámetro se utiliza para establecer el número de dígitos después del punto decimal en el resultado. Si es `null`, se establecerá por defecto en la escala predeterminada establecida con bcscale(), o se utilizará el valor de la directiva INI `bcmath.scale`.

### Valores devueltos

Devuelve `0` si los dos operandos son iguales, `1` si `num1` es superior a `num2`, o `-1` en caso contrario.

### Errores/Excepciones

Esta función lanza una excepción ValueError en los siguientes casos:

- `num1` o `num2` no es una cadena numérica bien formada de BCMath.
- `scale` está fuera del rango válido.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `scale` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo con bccomp()

    <?php

    echo bccomp('1', '2') . "\n";   // -1
    echo bccomp('1.00001', '1', 3); // 0
    echo bccomp('1.00001', '1', 5); // 1

    ?>

### Ver también

- BcMath\Number::compare() - Comparar dos números de precisión arbitraria

# bcdiv

(PHP 4, PHP 5, PHP 7, PHP 8)

bcdiv — Divide dos números de precisión arbitraria

### Descripción

function bcdiv(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

Divide el `num1` entre el `num2`.

### Parámetros

`num1`

  El dividendo, como una cadena.

`num2`

  El divisor, como una cadena.

`scale`
  Este parámetro se utiliza para establecer el número de dígitos después del punto decimal en el resultado. Si es `null`, se establecerá por defecto en la escala predeterminada establecida con bcscale(), o se utilizará el valor de la directiva INI `bcmath.scale`.

### Valores devueltos

Devuelve el resultado de la división como una cadena.

### Errores/Excepciones

Esta función lanza una excepción ValueError en los siguientes casos:

- `num1` o `num2` no es una cadena numérica bien formada de BCMath.
- `scale` está fuera del rango válido.

Esta función lanza una excepción DivisionByZeroError si `num2` es `0`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `scale` ahora es nullable.
8.0.0 | Dividir entre `0` ahora lanza una excepción DivisionByZeroError en vez de devolver `null`.

### Ejemplos

Ejemplo #1 Ejemplo de bcdiv()

    <?php

    echo bcdiv('105', '6.55957', 3);  // 16.007

    ?>

### Ver también

- bcdivmod() - Devuelve el cociente y el resto de un número de precisión arbitraria
- bcmod() - Devuelve el resto de una división entre números de gran tamaño
- bcmul() - Multiplica dos números de precisión arbitraria
- BcMath\Number::div() - Divide por un número de precisión arbitraria

# bcdivmod

(PHP 8 >= 8.4.0)

bcdivmod — Devuelve el cociente y el resto de un número de precisión arbitraria

### Descripción

function bcdivmod(string `$num1`, string `$num2`, ?int `$scale` = `null`): array

Devuelve el cociente y el resto de la división de `num1` por `num2`.

### Parámetros

`num1`

  El dividendo, como una cadena.

`num2`

  El divisor, como una cadena.

`scale`
  Este parámetro se utiliza para establecer el número de dígitos después del punto decimal en el resultado. Si es `null`, se establecerá por defecto en la escala predeterminada establecida con bcscale(), o se utilizará el valor de la directiva INI `bcmath.scale`.

### Valores devueltos

Devuelve un array indexado donde el primer elemento es el cociente en forma de string y el segundo elemento es el resto en forma de string.

### Errores/Excepciones

Esta función lanza una excepción ValueError en los siguientes casos:

- `num1` o `num2` no es una cadena numérica bien formada de BCMath.
- `scale` está fuera del rango válido.

Esta función lanza una excepción DivisionByZeroError si `num2` es `0`.

### Ejemplos

Ejemplo #1 Ejemplo de bcdivmod()

    <?php
    bcscale(0);

    [$quot, $rem] = bcdivmod('5',  '3');
    echo $quot; // 1
    echo $rem;  // 2

    [$quot, $rem] = bcdivmod('5',  '-3');
    echo $quot; // -1
    echo $rem;  // 2

    [$quot, $rem] = bcdivmod('-5',  '3');
    echo $quot; // -1
    echo $rem;  // -2

    [$quot, $rem] = bcdivmod('-5',  '-3');
    echo $quot; // 1
    echo $rem;  // -2
    ?>

Ejemplo #2 bcdivmod() con decimales

    <?php
    [$quot, $rem] = bcdivmod('5.7', '1.3', 1);
    echo $quot; // 4
    echo $rem;  // 0.5
    ?>

### Ver también

- bcdiv() - Divide dos números de precisión arbitraria
- bcmod() - Devuelve el resto de una división entre números de gran tamaño
- BcMath\Number::divmod() - Devuelve el cociente y el módulo de un número de precisión arbitraria

# bcfloor

(PHP 8 >= 8.4.0)

bcfloor — Redondea hacia abajo un número de precisión arbitraria

### Descripción

function bcfloor(string `$num`): string

Devuelve el valor entero inferior siguiente redondeando `num` si es necesario.

### Parámetros

`num`
  El valor a redondear.

### Valores devueltos

Devuelve una cadena numérica representando `num` redondeado hacia abajo al entero más cercano.

### Errores/Excepciones

Esta función lanza una ValueError si `num` no es un string numérico BCMath bien formado.

### Ejemplos

Ejemplo #1 Ejemplo de bcfloor()

    <?php
    var_dump(bcfloor('4.3'));
    var_dump(bcfloor('9.999'));
    var_dump(bcfloor('-3.14'));
    ?>

El ejemplo anterior mostrará:

    string(1) "4"
    string(1) "9"
    string(2) "-4"

### Ver también

- bcceil() - Redondea al alza un número de precisión arbitraria
- bcround() - Redondea un número de precisión arbitraria
- BcMath\Number::floor() - Redondea hacia abajo un número de precisión arbitraria

# bcmod

(PHP 4, PHP 5, PHP 7, PHP 8)

bcmod — Devuelve el resto de una división entre números de gran tamaño

### Descripción

function bcmod(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

Devuelve el resto de la división entre `num1` utilizando `num2`. El resultado tiene el mismo signo que `num1`.

### Parámetros

`num1`

  El operador izquierdo, como una cadena.

`num2`

  El operador derecho, como una cadena

`scale`
  Este parámetro se utiliza para establecer el número de dígitos después del punto decimal en el resultado. Si es `null`, se establecerá por defecto en la escala predeterminada establecida con bcscale(), o se utilizará el valor de la directiva INI `bcmath.scale`.

### Valores devueltos

Devuelve el módulo, en forma de string.

### Errores/Excepciones

Esta función lanza una excepción ValueError en los siguientes casos:

- `num1` o `num2` no es una cadena numérica bien formada de BCMath.
- `scale` está fuera del rango válido.

Esta función lanza una excepción DivisionByZeroError si `num2` es `0`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `scale` ahora es nullable.
8.0.0 | La división por `0` ahora lanza una excepción DivisionByZeroError en lugar de devolver null.
7.2.0 | `num1` y `num2` ya no se truncan a enteros. El comportamiento de bcmod() sigue a fmod() en lugar del operador `%`.
7.2.0 | Se ha añadido el parámetro `scale`.

### Ejemplos

Ejemplo #1 Ejemplo con bcmod()

    <?php
    bcscale(0);
    echo bcmod( '5',  '3'); //  2
    echo bcmod( '5', '-3'); //  2
    echo bcmod('-5',  '3'); // -2
    echo bcmod('-5', '-3'); // -2
    ?>

Ejemplo #2 bcmod() con decimales

    <?php
    bcscale(1);
    echo bcmod('5.7', '1.3'); // 0.5 desde PHP 7.2.0; 0 anteriormente
    ?>

### Ver también

- bcdiv() - Divide dos números de precisión arbitraria
- bcdivmod() - Devuelve el cociente y el resto de un número de precisión arbitraria
- BcMath\Number::mod() - Devuelve el módulo de un número de precisión arbitraria

# bcmul

(PHP 4, PHP 5, PHP 7, PHP 8)

bcmul — Multiplica dos números de precisión arbitraria

### Descripción

function bcmul(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

Multiplica `num1` por `num2`.

### Parámetros

`num1`

  El operador izquierdo, como una cadena.

`num2`

  El operador derecho, como una cadena

`scale`
  Este parámetro se utiliza para establecer el número de dígitos después del punto decimal en el resultado. Si es `null`, se establecerá por defecto en la escala predeterminada establecida con bcscale(), o se utilizará el valor de la directiva INI `bcmath.scale`.

### Valores devueltos

Devuelve el resultado como un string.

### Errores/Excepciones

Esta función lanza una excepción ValueError en los siguientes casos:

- `num1` o `num2` no es una cadena numérica bien formada de BCMath.
- `scale` está fuera del rango válido.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `scale` ahora es nullable.
7.3.0 | bcmul() ahora devuelve números con la escala solicitada. Anteriormente, los números devueltos podían omitir los ceros decimales finales.

### Ejemplos

Ejemplo #1 Ejemplo de bcmul()

    <?php
    echo bcmul('1.34747474747', '35', 3); // 47.161
    echo bcmul('2', '4'); // 8
    ?>

### Notas

> Nota:

> Antes de PHP 7.3.0, bcmul() podría devolver un resultado con menos dígitos después del punto decimal que el parámetro `scale` indicaría. Esto solo ocurre cuando el resultado no requiere toda la precisión permitida por `scale`. Por ejemplo:

> Ejemplo #2 Ejemplo de scale en bcmul()

>     <?php
>     echo bcmul('5', '2', 2);     // Imprime "10", no "10.00"
>     ?>

### Ver también

- bcdiv() - Divide dos números de precisión arbitraria
- BcMath\Number::mul() - Multiplica un número de precisión arbitraria

# bcpow

(PHP 4, PHP 5, PHP 7, PHP 8)

bcpow — Elevar un número de precisión arbitraria a otro

### Descripción

function bcpow(string `$num`, string `$exponent`, ?int `$scale` = `null`): string

Eleva `num` a la potencia `exponent`.

### Parámetros

`num`

  La base, como un string.

`exponent`

  El exponente, como un string. Debe ser un valor sin parte fraccionaria. El rango válido del exponente es específico de la plataforma, pero es al menos de `-2147483648` a `2147483647`.

`scale`
  Este parámetro se utiliza para establecer el número de dígitos después del punto decimal en el resultado. Si es `null`, se establecerá por defecto en la escala predeterminada establecida con bcscale(), o se utilizará el valor de la directiva INI `bcmath.scale`.

### Valores devueltos

Devuelve el resultado como un string.

### Errores/Excepciones

Esta función lanza una ValueError en los siguientes casos:

- `num` o `exponent` no es un string numérico con formato válido de BCMath
- `exponent` tiene una parte fraccionaria
- `exponent` o `scale` están fuera del rango válido

Esta función lanza una DivisionByZeroError si `num` es `0` y `exponent` es un valor negativo.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Las potencias negativas de `0` anteriormente devolvían `0`, pero ahora lanzan una excepción DivisionByZeroError.
8.0.0 | Cuando `exponent` tiene una parte fraccionaria, ahora lanza un ValueError en lugar de truncar.
7.3.0 | bcpow() ahora devuelve números con la escala solicitada. Anteriormente, los números devueltos podían omitir los ceros decimales finales.

### Ejemplos

Ejemplo #1 Ejemplo de bcpow()

    <?php

    echo bcpow('4.2', '3', 2); // 74.08

    ?>

### Notas

> Nota:

> Antes de PHP 7.3.0, bcpow() podría devolver un resultado con menos dígitos después del punto decimal que los indicados en el parámetro `scale`. Esto sucede únicamente cuando el resultado no necesita toda la precisión disponible por `scale`. Por ejemplo:

> Ejemplo #2 Ejemplo de escalado de bcpow()

>     <?php
>     echo bcpow('5', '2', 2);     // Imprime "25", no "25.00"
>     ?>

### Ver también

- bcpowmod() - Eleva un número de precisión arbitraria a otro, reducido por un módulo especificado
- bcsqrt() - Obtiene la raiz cuadrada de un número de precisión arbitraria
- BcMath\Number::pow() - Eleva un número de precisión arbitraria

# bcpowmod

(PHP 5, PHP 7, PHP 8)

bcpowmod — Eleva un número de precisión arbitraria a otro, reducido por un módulo especificado

### Descripción

function bcpowmod(
string `$num`,
string `$exponent`,
string `$modulus`,
?int `$scale` = `null`
): string

Usa el método de exponenciación rápida para aumentar `num` a la potencia `exponent` con respecto al módulo `modulus`.

### Parámetros

`num`

  La base, como un string integral (es decir, la escala tiene que ser cero).

`exponent`

  El exponente, como un string integral no negativo (es decir, la escala tiene que ser cero).

`modulus`

  El módulo, como un string integral (es decir, la escala tiene que ser cero).

`scale`
  Este parámetro se utiliza para establecer el número de dígitos después del punto decimal en el resultado. Si es `null`, se establecerá por defecto en la escala predeterminada establecida con bcscale(), o se utilizará el valor de la directiva INI `bcmath.scale`.

### Valores devueltos

Devuelve el resultado como un string.

### Errores/Excepciones

Esta función lanza un ValueError en los siguientes casos:

- `num`, `exponent` o `modulus` no es un string numérico con formato válido de BCMath
- `num`, `exponent` o `modulus` tiene una parte fraccionaria
- `exponent` es un valor negativo
- `scale` está fuera del rango válido

Esta función lanza una excepción DivisionByZeroError si `modulus` es `0`.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `scale` ahora es nullable.
8.0.0 | Ahora lanza un ValueError en vez de devolver `false` si `exponent` es un valor negativo.
8.0.0 | Dividiendo por `0` ahora lanza una excepción DivisionByZeroError en vez de devolver `false`.

### Ejemplos

Los siguientes dos comandos son funcionalmente idénticos. La version bcpowmod() sin embargo, se ejecuta en menos tiempo y admite mas parametros.

    <?php
    $a = bcpowmod($x, $y, $mod);

    $b = bcmod(bcpow($x, $y), $mod);

    // $a y $b son iguales el uno al otro.

    ?>

### Notas

> Nota:

> Debido a que este método utiliza la operación módulo, podrían obtenerse resultados inesperados en números enteros no positivos.

### Ver también

- bcpow() - Elevar un número de precisión arbitraria a otro
- bcmod() - Devuelve el resto de una división entre números de gran tamaño
- BcMath\Number::powmod() - Eleva un número de precisión arbitraria, reducido por un módulo especificado

# bcround

(PHP 8 >= 8.4.0)

bcround — Redondea un número de precisión arbitraria

### Descripción

function bcround(string `$num`, int `$precision` = 0, RoundingMode `$mode` = `RoundingMode::HalfAwayFromZero`): string

Devuelve el valor redondeado de `num` a la precisión especificada `precision` (número de dígitos después del punto decimal). `precision` puede ser también negativo o nulo (por omisión).

### Parámetros

`num`

  El valor a redondear.

`precision`

  El número opcional de decimales a redondear.

  Si el argumento `precision` es positivo, `num` será redondeado utilizando el argumento `precision` para definir el número significativo de dígitos después del punto decimal.

  Si el argumento `precision` es negativo, `num` será redondeado utilizando el argumento `precision` para definir el número significativo de dígitos antes del punto decimal, i.e. el múltiplo más cercano de `pow(10, -$precision)`, i.e. para una `precision` de -1, `num` será redondeado a 10, para una `precision` de -2 a 100, etc.

`mode`
  Especifica el método de redondeo. Para más información sobre los métodos, ver RoundingMode.

### Valores devueltos

Devuelve una cadena numérica representando `num` redondeado a la precisión dada.

### Errores/Excepciones

Esta función lanza una ValueError en los siguientes casos:

- `num` no es una cadena numérica BCMath bien formada.
- Un `mode` inválido es especificado.

### Ejemplos

Ejemplo #1 Ejemplos de bcround()

    <?php
    var_dump(bcround('3.4'));
    var_dump(bcround('3.5'));
    var_dump(bcround('3.6'));
    var_dump(bcround('3.6', 0));
    var_dump(bcround('5.045', 2));
    var_dump(bcround('5.055', 2));
    var_dump(bcround('345', -2));
    var_dump(bcround('345', -3));
    var_dump(bcround('678', -2));
    var_dump(bcround('678', -3));
    ?>

El ejemplo anterior mostrará:

    string(1) "3"
    string(1) "4"
    string(1) "4"
    string(1) "4"
    string(4) "5.05"
    string(4) "5.06"
    string(3) "300"
    string(1) "0"
    string(3) "700"
    string(4) "1000"

Ejemplo #2 Ejemplo de la utilización de bcround() con diferentes valores de `precision`

    <?php
    $number = '123.45';

    var_dump(bcround($number, 3));
    var_dump(bcround($number, 2));
    var_dump(bcround($number, 1));
    var_dump(bcround($number, 0));
    var_dump(bcround($number, -1));
    var_dump(bcround($number, -2));
    var_dump(bcround($number, -3));
    ?>

El ejemplo anterior mostrará:

    string(7) "123.450"
    string(6) "123.45"
    string(5) "123.5"
    string(3) "123"
    string(3) "120"
    string(3) "100"
    string(1) "0"

Ejemplo #3 Ejemplo de la utilización de bcround() con diferentes valores de `mode`

    <?php
    echo 'Modos de redondeo con 9.5' . PHP_EOL;
    var_dump(bcround('9.5', 0, RoundingMode::HalfAwayFromZero));
    var_dump(bcround('9.5', 0, RoundingMode::HalfTowardsZero));
    var_dump(bcround('9.5', 0, RoundingMode::HalfEven));
    var_dump(bcround('9.5', 0, RoundingMode::HalfOdd));
    var_dump(bcround('9.5', 0, RoundingMode::TowardsZero));
    var_dump(bcround('9.5', 0, RoundingMode::AwayFromZero));
    var_dump(bcround('9.5', 0, RoundingMode::NegativeInfinity));
    var_dump(bcround('9.5', 0, RoundingMode::PositiveInfinity));

    echo PHP_EOL;
    echo 'Modos de redondeo con 8.5' . PHP_EOL;
    var_dump(bcround('8.5', 0, RoundingMode::HalfAwayFromZero));
    var_dump(bcround('8.5', 0, RoundingMode::HalfTowardsZero));
    var_dump(bcround('8.5', 0, RoundingMode::HalfEven));
    var_dump(bcround('8.5', 0, RoundingMode::HalfOdd));
    var_dump(bcround('8.5', 0, RoundingMode::TowardsZero));
    var_dump(bcround('8.5', 0, RoundingMode::AwayFromZero));
    var_dump(bcround('8.5', 0, RoundingMode::NegativeInfinity));
    var_dump(bcround('8.5', 0, RoundingMode::PositiveInfinity));
    ?>

El ejemplo anterior mostrará:

    Modos de redondeo con 9.5
    string(2) "10"
    string(1) "9"
    string(2) "10"
    string(1) "9"
    string(1) "9"
    string(2) "10"
    string(1) "9"
    string(2) "10"

    Modos de redondeo con 8.5
    string(1) "9"
    string(1) "8"
    string(1) "8"
    string(1) "9"
    string(1) "8"
    string(1) "9"
    string(1) "8"
    string(1) "9"

Ejemplo #4 Ejemplo de la utilización de bcround() con diferentes valores de `mode` al especificar `precision`

    <?php
    echo 'Utilización de RoundingMode::HalfAwayFromZero con una precisión decimal de 1' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::HalfAwayFromZero));
    var_dump(bcround(-1.55, 1, RoundingMode::HalfAwayFromZero));

    echo PHP_EOL;
    echo 'Utilización de RoundingMode::HalfTowardsZero con una precisión decimal de 1' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::HalfTowardsZero));
    var_dump(bcround(-1.55, 1, RoundingMode::HalfTowardsZero));

    echo PHP_EOL;
    echo 'Utilización de RoundingMode::HalfEven con una precisión decimal de 1' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::HalfEven));
    var_dump(bcround(-1.55, 1, RoundingMode::HalfEven));

    echo PHP_EOL;
    echo 'Utilización de RoundingMode::HalfOdd con una precisión decimal de 1' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::HalfOdd));
    var_dump(bcround(-1.55, 1, RoundingMode::HalfOdd));

    echo PHP_EOL;
    echo 'Utilización de RoundingMode::TowardsZero con una precisión decimal de 1' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::TowardsZero));
    var_dump(bcround(-1.55, 1, RoundingMode::TowardsZero));

    echo PHP_EOL;
    echo 'Utilización de RoundingMode::AwayFromZero con una precisión decimal de 1' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::AwayFromZero));
    var_dump(bcround(-1.55, 1, RoundingMode::AwayFromZero));

    echo PHP_EOL;
    echo 'Utilización de RoundingMode::NegativeInfinity con una precisión decimal de 1' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::NegativeInfinity));
    var_dump(bcround(-1.55, 1, RoundingMode::NegativeInfinity));

    echo PHP_EOL;
    echo 'Utilización de RoundingMode::PositiveInfinity con una precisión decimal de 1' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::PositiveInfinity));
    var_dump(bcround(-1.55, 1, RoundingMode::PositiveInfinity));
    ?>

El ejemplo anterior mostrará:

    Utilización de RoundingMode::HalfAwayFromZero con una precisión decimal de 1
    string(3) "1.6"
    string(4) "-1.6"

    Utilización de RoundingMode::HalfTowardsZero con una precisión decimal de 1
    string(3) "1.5"
    string(4) "-1.5"

    Utilización de RoundingMode::HalfEven con una precisión decimal de 1
    string(3) "1.6"
    string(4) "-1.6"

    Utilización de RoundingMode::HalfOdd con una precisión decimal de 1
    string(3) "1.5"
    string(4) "-1.5"

    Utilización de RoundingMode::TowardsZero con una precisión decimal de 1
    string(3) "1.5"
    string(4) "-1.5"

    Utilización de RoundingMode::AwayFromZero con una precisión decimal de 1
    string(3) "1.6"
    string(4) "-1.6"

    Utilización de RoundingMode::NegativeInfinity con una precisión decimal de 1
    string(3) "1.5"
    string(4) "-1.6"

    Utilización de RoundingMode::PositiveInfinity con una precisión decimal de 1
    string(3) "1.6"
    string(4) "-1.5"

### Ver también

- bcceil() - Redondea al alza un número de precisión arbitraria
- bcfloor() - Redondea hacia abajo un número de precisión arbitraria
- BcMath\Number::round() - Redondea un número de precisión arbitraria

# bcscale

(PHP 4, PHP 5, PHP 7, PHP 8)

bcscale — Define o recupera la precisión por defecto para todas las funciones bc math

### Descripción

function bcscale(int `$scale`): int

Define la precisión por defecto para todas las llamadas posteriores a las funciones bc math que omiten el argumento de precisión.

function bcscale(null `$scale` = `null`): int

Recupera el factor de precisión actual.

### Parámetros

`scale`

  El factor de precisión.

### Valores devueltos

Retorna la precisión anterior cuando se utiliza como definidor. De lo contrario, se retorna la precisión actual.

### Errores/Excepciones

Esta función levanta una excepción ValueError si `scale` está fuera del rango válido.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `scale` ahora es nullable.
7.3.0 | bcscale() ahora puede ser utilizada para recuperar la precisión actual; cuando se utiliza para definir una nueva precisión, ahora retorna la precisión anterior. Anteriormente, `scale` era obligatorio, y bcscale() siempre retornaba `true`.

### Ejemplos

Ejemplo #1 Ejemplo con bcscale()

    <?php

    // precisión por defecto: 3
    bcscale(3);
    echo bcdiv('105', '6.55957'); // 16.007

    // lo mismo sin utilizar bcscale()
    echo bcdiv('105', '6.55957', 3); // 16.007

    ?>

# bcsqrt

(PHP 4, PHP 5, PHP 7, PHP 8)

bcsqrt — Obtiene la raiz cuadrada de un número de precisión arbitraria

### Descripción

function bcsqrt(string `$num`, ?int `$scale` = `null`): string

Devuelve la raiz cudrada de `num`.

### Parámetros

`num`

  El operando, como un string numérico con formato válido de BCMath.

`scale`
  Este parámetro se utiliza para establecer el número de dígitos después del punto decimal en el resultado. Si es `null`, se establecerá por defecto en la escala predeterminada establecida con bcscale(), o se utilizará el valor de la directiva INI `bcmath.scale`.

### Valores devueltos

Devuelve la raiz cuadrada como un string numérico con formato válido de BCMath.

### Errores/Excepciones

Esta función lanza un ValueError en los siguientes casos:

- `num` no es un string numérico con formato válido de BCMath
- `num` es menor que `0`
- `scale` está fuera del rango válido

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Si `num` no es un string numérico con formato válido de BCMath, o es menor que `0`, se lanza un ValueError. Anteriormente, se emitía `E_WARNING` en su lugar.
8.0.0 | `scale` ahora necesita ser entre `0` y `2147483647`; anteriormente, las escalas negativas se trataban silenciosamente como `0`.
8.0.0 | `scale` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo de bcsqrt()

    <?php

    echo bcsqrt('2', 3); // 1.414

    ?>

### Ver también

- bcpow() - Elevar un número de precisión arbitraria a otro
- BcMath\Number::sqrt() - Devuelve la raíz cuadrada de un número de precisión arbitraria

# bcsub

(PHP 4, PHP 5, PHP 7, PHP 8)

bcsub — Resta un número de precisión arbitraria de otro

### Descripción

function bcsub(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

Resta `num2` de `num1`.

### Parámetros

`num1`

  El operador izquierdo, como una cadena.

`num2`

  El operador derecho, como una cadena

`scale`
  Este parámetro se utiliza para establecer el número de dígitos después del punto decimal en el resultado. Si es `null`, se establecerá por defecto en la escala predeterminada establecida con bcscale(), o se utilizará el valor de la directiva INI `bcmath.scale`.

### Valores devueltos

El resultado de la resta, como un string.

### Errores/Excepciones

Esta función lanza una excepción ValueError en los siguientes casos:

- `num1` o `num2` no es una cadena numérica bien formada de BCMath.
- `scale` está fuera del rango válido.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `scale` ahora es nullable.

### Ejemplos

Ejemplo #1 Ejemplo de bcsub()

    <?php

    $a = '1.234';
    $b = '5';

    echo bcsub($a, $b);     // -3
    echo bcsub($a, $b, 4);  // -3.7660

    ?>

### Ver también

- bcadd() - Suma dos números de precisión arbitrária
- BcMath\Number::sub() - Sustrae un número de precisión arbitraria

## Tabla de contenidos

- bcadd — Suma dos números de precisión arbitrária
- bcceil — Redondea al alza un número de precisión arbitraria
- bccomp — Comparar dos números de gran tamaño
- bcdiv — Divide dos números de precisión arbitraria
- bcdivmod — Devuelve el cociente y el resto de un número de precisión arbitraria
- bcfloor — Redondea hacia abajo un número de precisión arbitraria
- bcmod — Devuelve el resto de una división entre números de gran tamaño
- bcmul — Multiplica dos números de precisión arbitraria
- bcpow — Elevar 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
- bcround — Redondea un número de precisión arbitraria
- bcscale — Define o recupera la precisión por defecto para todas las funciones bc math
- bcsqrt — Obtiene la raiz cuadrada de un número de precisión arbitraria
- bcsub — Resta un número de precisión arbitraria de otro

# La clase BcMath\Number

(PHP 8 >= 8.4.0)

## Introducción

Una clase para un número de precisión arbitraria. Estos objetos soportan los operadores aritméticos y de comparación.

> Nota: Esta clase no se ve afectada por la directiva INI bcmath.scale definida en el php.ini.

> Nota: El comportamiento de un operador sobrecargado es el mismo que especificar `null` para el argumento `scale` en el método correspondiente.

## Sinopsis de la Clase

namespace BcMath;
final readonly class Number implements Stringable {
/* Propiedades */
public string $value;
public int $scale;
/* Métodos */
public function __construct(string|int `$num`)
public function add(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function ceil(): BcMath\Number
public function compare(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): int
public function div(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function divmod(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): array
public function floor(): BcMath\Number
public function mod(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function mul(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function pow(BcMath\Number|string|int `$exponent`, ?int `$scale` = `null`): BcMath\Number
public function powmod(BcMath\Number|string|int `$exponent`, BcMath\Number|string|int `$modulus`, ?int `$scale` = `null`): BcMath\Number
public function round(int `$precision` = 0, RoundingMode `$mode` = `RoundingMode::HalfAwayFromZero`): BcMath\Number
public function __serialize(): array
public function sqrt(?int `$scale` = `null`): BcMath\Number
public function sub(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function __toString(): string
public function __unserialize(array `$data`): void
}

## Propiedades

value
  Una representación en string de un número de precisión arbitraria.
scale
  El valor de la escala actualmente definida en el objeto. Para los objetos resultantes de cálculos, este valor se calcula y define automáticamente, a menos que el argumento `scale` haya sido definido en el método de cálculo.

# BcMath\Number::add

(PHP 8 >= 8.4.0)

BcMath\Number::add — Añadir un número de precisión arbitraria

### Descripción

public function BcMath\Number::add(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Añade $this y `num`.

### Parámetros

`num`
  El valor a añadir.
`scale`
  BcMath\Number::scale especificado explícitamente para los resultados del cálculo. Si `null`, el BcMath\Number::scale del resultado del cálculo será definido automáticamente.

### Valores devueltos

Devuelve el resultado de la adición en forma de un nuevo objeto BcMath\Number.

Cuando el BcMath\Number::scale del resultado es definido automáticamente, el mayor BcMath\Number::scale de los dos números utilizados para la adición es utilizado.

Es decir, si los BcMath\Number::scale de dos valores son `2` y `5` respectivamente, el BcMath\Number::scale del resultado será `5`.

### Errores/Excepciones

Este método lanza una ValueError en los siguientes casos:

- `num` es un string y no es una cadena numérica BCMath bien formada
- `scale` está fuera del rango válido

### Ejemplos

Ejemplo #1 Ejemplo de BcMath\Number::add() cuando `scale` no está especificado

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->add(new BcMath\Number('2.34567'));
    $ret2 = $number->add('-3.456');
    $ret3 = $number->add(7);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

El ejemplo anterior mostrará:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(7) "3.57967"
      ["scale"]=>
      int(5)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(6) "-2.222"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "8.234"
      ["scale"]=>
      int(3)
    }

Ejemplo #2 Ejemplo de BcMath\Number::add() especificando `scale` explícitamente

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->add(new BcMath\Number('2.34567'), 1);
    $ret2 = $number->add('-3.456', 10);
    $ret3 = $number->add(7, 0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

El ejemplo anterior mostrará:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "3.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(13) "-2.2220000000"
      ["scale"]=>
      int(10)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }

### Ver también

- bcadd() - Suma dos números de precisión arbitrária
- BcMath\Number::sub() - Sustrae un número de precisión arbitraria

# BcMath\Number::ceil

(PHP 8 >= 8.4.0)

BcMath\Number::ceil — Redondea al alza un número de precisión arbitraria

### Descripción

public function BcMath\Number::ceil(): BcMath\Number

Devuelve el valor entero superior redondeando al alza $this si es necesario.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el resultado como un nuevo objeto BcMath\Number. La BcMath\Number::scale del resultado es siempre `0`.

### Ejemplos

Ejemplo #1 Ejemplo de BcMath\Number::ceil()

    <?php
    $num1 = new BcMath\Number('4.3')->ceil();
    $num2 = new BcMath\Number('9.999')->ceil();
    $num3 = new BcMath\Number('-3.14')->ceil();

    var_dump($num1, $num2, $num3);
    ?>

El ejemplo anterior mostrará:

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "5"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(2) "-3"
      ["scale"]=>
      int(0)
    }

### Ver también

- bcceil() - Redondea al alza un número de precisión arbitraria
- BcMath\Number::floor() - Redondea hacia abajo un número de precisión arbitraria
- BcMath\Number::round() - Redondea un número de precisión arbitraria

# BcMath\Number::compare

(PHP 8 >= 8.4.0)

BcMath\Number::compare — Comparar dos números de precisión arbitraria

### Descripción

public function BcMath\Number::compare(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): int

Comparar dos números de precisión arbitraria. Este método se comporta de manera similar al operador spaceship.

### Parámetros

`num`
  El valor al que comparar.
`scale`
  Especifica el `scale` a utilizar para la comparación. Si `null`, todos los dígitos son utilizados en la comparación.

### Valores devueltos

Devuelve `0` si los dos números son iguales, `1` si $this es mayor que `num`, de lo contrario `-1`.

### Errores/Excepciones

Este método lanza una ValueError en los siguientes casos:

- `num` es un string y no es una cadena numérica BCMath bien formada
- `scale` está fuera del rango válido

### Ejemplos

Ejemplo #1 Ejemplo de BcMath\Number::compare() cuando `scale` no está especificado

    <?php
    $number = new BcMath\Number('1.234');

    var_dump(
        $number->compare(new BcMath\Number('1.234')),
        $number->compare('1.23400'),
        $number->compare('1.23401'),
        $number->compare(1),
    );
    ?>

El ejemplo anterior mostrará:

    int(0)
    int(0)
    int(-1)
    int(1)

Ejemplo #2 Ejemplo de BcMath\Number::compare() especificando `scale` explícitamente

    <?php
    $number = new BcMath\Number('1.234');

    var_dump(
        $number->compare(new BcMath\Number('1.299'), 1),
        $number->compare('1.24', 2),
        $number->compare('1.22', 2),
        $number->compare(1, 0),
    );
    ?>

El ejemplo anterior mostrará:

    int(0)
    int(-1)
    int(1)
    int(0)

### Ver también

- bccomp() - Comparar dos números de gran tamaño

# BcMath\Number::__construct

(PHP 8 >= 8.4.0)

BcMath\Number::__construct — Crear un objeto BcMath\Number

### Descripción

public function BcMath\Number::__construct(string|int `$num`)

Crear un objeto BcMath\Number a partir de un valor int o string.

### Parámetros

`num`
  Un valor int o string. Si `num` es un int, la BcMath\Number::scale se define siempre a `0`. Si `num` es un string, debe ser un número válido, y la BcMath\Number::scale se define automáticamente analizando el string.

### Errores/Excepciones

Este método lanza una ValueError si `num` es un string y no es un string numérico BCMath bien formado.

### Ejemplos

Ejemplo #1 Ejemplo de BcMath\Number::__construct()

    <?php
    $num1 = new BcMath\Number(100);
    $num2 = new BcMath\Number('-200');
    $num3 = new BcMath\Number('300.00');

    var_dump($num1, $num2, $num3);
    ?>

El ejemplo anterior mostrará:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "100"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(4) "-200"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(6) "300.00"
      ["scale"]=>
      int(2)
    }

### Ver también

- BcMath\Number::__serialize() - Serializa un objeto BcMath\Number
- BcMath\Number::__unserialize() - Deserializa un argumento de datos en un objeto BcMath\Number

# BcMath\Number::div

(PHP 8 >= 8.4.0)

BcMath\Number::div — Divide por un número de precisión arbitraria

### Descripción

public function BcMath\Number::div(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Divide $this por `num`.

### Parámetros

`num`
  El divisor.
`scale`
  BcMath\Number::scale especificado explícitamente para los resultados del cálculo. Si `null`, el BcMath\Number::scale del resultado del cálculo será definido automáticamente.

### Valores devueltos

Devuelve el resultado de una división en forma de un nuevo objeto BcMath\Number.

Cuando el BcMath\Number::scale del resultado se define automáticamente, se utiliza el BcMath\Number::scale del dividendo. Sin embargo, en casos como la división indivisible, el BcMath\Number::scale del resultado se extiende. La extensión se realiza solo si es necesario, hasta un máximo de `+10`.

Es decir, si el BcMath\Number::scale del dividendo es `5`, el BcMath\Number::scale del resultado está entre `5` y `15`.

Incluso en cálculos indivisibles, el BcMath\Number::scale no siempre será `+10`. Un `0` al final del resultado se considera que no necesita extensión, por lo que el BcMath\Number::scale se reduce en esa cantidad. El BcMath\Number::scale nunca será inferior al BcMath\Number::scale antes de la extensión. Véase también los ejemplos de código.

### Errores/Excepciones

Este método lanza una ValueError en los siguientes casos:

- `num` es un string y no es una cadena numérica BCMath bien formada
- `scale` está fuera del rango válido
- BcMath\Number::scale del resultado está fuera del rango válido

Este método lanza una DivisionByZeroError si `num` es `0`.

### Ejemplos

Ejemplo #1 Ejemplo BcMath\Number::div() cuando `scale` no está especificado

    <?php
    $number = new BcMath\Number('0.002');

    $ret1 = $number->div(new BcMath\Number('2.000'));
    $ret2 = $number->div('-3');
    $ret3 = $number->div(32);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

El ejemplo anterior mostrará:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "0.002"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(5) "0.001"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(16) "-0.0006666666666"
      ["scale"]=>
      int(13)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(9) "0.0000625"
      ["scale"]=>
      int(7)
    }

Ejemplo #2 Ejemplo de BcMath\Number::div() especificando `scale` explícitamente

    <?php
    $number = new BcMath\Number('0.002');

    $ret1 = $number->div(new BcMath\Number('2.000'), 15);
    $ret2 = $number->div('-3', 5);
    $ret3 = $number->div(32, 2);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

El ejemplo anterior mostrará:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "0.002"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(17) "0.001000000000000"
      ["scale"]=>
      int(15)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(8) "-0.00066"
      ["scale"]=>
      int(5)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(4) "0.00"
      ["scale"]=>
      int(2)
    }

Ejemplo #3 Ejemplo de BcMath\Number::div() expandiendo BcMath\Number::scale del objeto resultado

    <?php
    var_dump(
        new BcMath\Number('0.001')->div('10001'),
        new BcMath\Number('0.001')->div('10001', 13),
        new BcMath\Number('0.001')->div('100000000000001'),
    );
    ?>

El ejemplo anterior mostrará:

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(13) "0.00000009999"
      ["scale"]=>
      int(11)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(15) "0.0000000999900"
      ["scale"]=>
      int(13)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "0.000"
      ["scale"]=>
      int(3)
    }

### Ver también

- bcdiv() - Divide dos números de precisión arbitraria
- BcMath\Number::divmod() - Devuelve el cociente y el módulo de un número de precisión arbitraria
- BcMath\Number::mod() - Devuelve el módulo de un número de precisión arbitraria
- BcMath\Number::sqrt() - Devuelve la raíz cuadrada de un número de precisión arbitraria
- BcMath\Number::pow() - Eleva un número de precisión arbitraria
- BcMath\Number::mul() - Multiplica un número de precisión arbitraria

# BcMath\Number::divmod

(PHP 8 >= 8.4.0)

BcMath\Number::divmod — Devuelve el cociente y el módulo de un número de precisión arbitraria

### Descripción

public function BcMath\Number::divmod(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): array

Devuelve el cociente y el módulo de la división de $this por `num`.

### Parámetros

`num`
  El divisor.
`scale`
  BcMath\Number::scale especificado explícitamente para los resultados del cálculo. Si `null`, el BcMath\Number::scale del resultado del cálculo será definido automáticamente.

### Valores devueltos

Devuelve un array indexado donde el primer elemento es el cociente en forma de un nuevo objeto BcMath\Number y el segundo elemento es el módulo en forma de un nuevo objeto BcMath\Number.

El cociente es siempre un valor entero, por lo que BcMath\Number::scale del cociente será siempre `0`, independientemente de si `scale` es explícitamente especificado.

Si `scale` es explícitamente especificado, BcMath\Number::scale del módulo será el valor especificado. Cuando el BcMath\Number::scale del objeto de módulo del resultado es definido automáticamente, el mayor BcMath\Number::scale de los dos números utilizados para la operación de módulo es utilizado.

Es decir, si los BcMath\Number::scales de dos valores son `2` y `5` respectivamente, el BcMath\Number::scale del módulo será `5`.

### Errores/Excepciones

Este método lanza una ValueError en los siguientes casos:

- `num` es un string y no es una cadena numérica BCMath bien formada
- `scale` está fuera del rango válido

Este método lanza una DivisionByZeroError si `num` es `0`.

### Ejemplos

Ejemplo #1 Ejemplo de BcMath\Number::divmod() cuando `scale` no es especificado

    <?php
    echo '8.3 / 2.22' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('8')->divmod(new BcMath\Number('2.22'));
    var_dump($quot, $rem);

    echo PHP_EOL . '8.3 / 8.3' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('8.3')->divmod('8.3');
    var_dump($quot, $rem);

    echo PHP_EOL . '10 / -3' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('10')->divmod(-3);
    var_dump($quot, $rem);
    ?>

El ejemplo anterior mostrará:

    8.3 / 2.22
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(4) "1.34"
      ["scale"]=>
      int(2)
    }

    8.3 / 8.3
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(3) "0.0"
      ["scale"]=>
      int(1)
    }

    10 / -3
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(2) "-3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }

Ejemplo #2 Ejemplo de BcMath\Number::divmod() especificando `scale` explícitamente

    <?php
    echo '8.3 / 2.22' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('8')->divmod(new BcMath\Number('2.22'), 1);
    var_dump($quot, $rem);

    echo PHP_EOL . '8.3 / 8.3' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('8.3')->divmod('8.3', 4);
    var_dump($quot, $rem);

    echo PHP_EOL . '10 / -3' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('10')->divmod(-3, 5);
    var_dump($quot, $rem);
    ?>

El ejemplo anterior mostrará:

    8.3 / 2.22
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.3"
      ["scale"]=>
      int(1)
    }

    8.3 / 8.3
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(6) "0.0000"
      ["scale"]=>
      int(4)
    }

    10 / -3
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(2) "-3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(7) "1.00000"
      ["scale"]=>
      int(5)
    }

### Ver también

- bcdivmod() - Devuelve el cociente y el resto de un número de precisión arbitraria
- BcMath\Number::div() - Divide por un número de precisión arbitraria
- BcMath\Number::mod() - Devuelve el módulo de un número de precisión arbitraria

# BcMath\Number::floor

(PHP 8 >= 8.4.0)

BcMath\Number::floor — Redondea hacia abajo un número de precisión arbitraria

### Descripción

public function BcMath\Number::floor(): BcMath\Number

Devuelve el valor entero inferior siguiente redondeando hacia abajo $this si es necesario.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el resultado como un nuevo objeto BcMath\Number. La BcMath\Number::scale del resultado es siempre `0`.

### Ejemplos

Ejemplo #1 Ejemplo de BcMath\Number::floor()

    <?php
    $num1 = new BcMath\Number('4.3')->floor();
    $num2 = new BcMath\Number('9.999')->floor();
    $num3 = new BcMath\Number('-3.14')->floor();

    var_dump($num1, $num2, $num3);
    ?>

El ejemplo anterior mostrará:

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "4"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(2) "-4"
      ["scale"]=>
      int(0)
    }

### Ver también

- bcfloor() - Redondea hacia abajo un número de precisión arbitraria
- BcMath\Number::ceil() - Redondea al alza un número de precisión arbitraria
- BcMath\Number::round() - Redondea un número de precisión arbitraria

# BcMath\Number::mod

(PHP 8 >= 8.4.0)

BcMath\Number::mod — Devuelve el módulo de un número de precisión arbitraria

### Descripción

public function BcMath\Number::mod(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Devuelve el resto de la división de $this por `num`. Excepto si `num` es `0`, el resultado tiene el mismo signo que $this.

### Parámetros

`num`
  El divisor.
`scale`
  BcMath\Number::scale especificado explícitamente para los resultados del cálculo. Si `null`, el BcMath\Number::scale del resultado del cálculo será definido automáticamente.

### Valores devueltos

Devuelve el módulo en forma de un nuevo objeto BcMath\Number.

Cuando el BcMath\Number::scale del resultado se define automáticamente, se utiliza el mayor BcMath\Number::scale de los dos números utilizados para la operación de módulo.

Es decir, si los BcMath\Number::scale de dos valores son `2` y `5` respectivamente, el BcMath\Number::scale del resultado será `5`.

### Errores/Excepciones

Este método lanza una ValueError en los siguientes casos:

- `num` es un string y no es una cadena numérica BCMath bien formada
- `scale` está fuera del rango válido

Este método lanza una DivisionByZeroError si `num` es `0`.

### Ejemplos

Ejemplo #1 Ejemplo de BcMath\Number::mod() cuando `scale` no está especificado

    <?php
    $number = new BcMath\Number('8.3');

    $ret1 = $number->mod(new BcMath\Number('2.22'));
    $ret2 = $number->mod('8.3');
    $ret3 = $number->mod(-5);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

El ejemplo anterior mostrará:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "8.3"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(4) "1.64"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(3) "0.0"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "3.3"
      ["scale"]=>
      int(1)
    }

Ejemplo #2 Ejemplo de BcMath\Number::mod() definiendo `scale` explícitamente

    <?php
    $number = new BcMath\Number('8.3');

    $ret1 = $number->mod(new BcMath\Number('2.22'), 1);
    $ret2 = $number->mod('8.3', 3);
    $ret3 = $number->mod(-5, 0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

El ejemplo anterior mostrará:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "8.3"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(5) "0.000"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "3"
      ["scale"]=>
      int(0)
    }

### Ver también

- bcmod() - Devuelve el resto de una división entre números de gran tamaño
- BcMath\Number::div() - Divide por un número de precisión arbitraria
- BcMath\Number::divmod() - Devuelve el cociente y el módulo de un número de precisión arbitraria
- BcMath\Number::powmod() - Eleva un número de precisión arbitraria, reducido por un módulo especificado

# BcMath\Number::mul

(PHP 8 >= 8.4.0)

BcMath\Number::mul — Multiplica un número de precisión arbitraria

### Descripción

public function BcMath\Number::mul(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Multiplica $this por `num`.

### Parámetros

`num`
  El multiplicador.
`scale`
  BcMath\Number::scale especificado explícitamente para los resultados del cálculo. Si `null`, el BcMath\Number::scale del resultado del cálculo será definido automáticamente.

### Valores devueltos

Devuelve el resultado de la multiplicación como un nuevo objeto BcMath\Number.

Cuando la BcMath\Number::scale del resultado se establece automáticamente, se utiliza la suma de las BcMath\Number::scales de los dos valores utilizados para la multiplicación.

Es decir, si las BcMath\Number::scales de dos valores son `2` y `5` respectivamente, la BcMath\Number::scale del resultado será `7`.

### Errores/Excepciones

Este método lanza una ValueError en los siguientes casos:

- `num` es un string y no es una cadena numérica BCMath bien formada
- `scale` está fuera del rango válido
- BcMath\Number::scale del resultado está fuera del rango válido

### Ejemplos

Ejemplo #1 Ejemplo de BcMath\Number::mul() cuando `scale` no está especificado

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->mul(new BcMath\Number('2.3456'));
    $ret2 = $number->mul('-3.4');
    $ret3 = $number->mul(7);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

El ejemplo anterior mostrará:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(9) "2.8944704"
      ["scale"]=>
      int(7)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(7) "-4.1956"
      ["scale"]=>
      int(4)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "8.638"
      ["scale"]=>
      int(3)
    }

Ejemplo #2 Ejemplo de BcMath\Number::mul() especificando `scale` explícitamente

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->mul(new BcMath\Number('2.3456'), 1);
    $ret2 = $number->mul('-3.4', 10);
    $ret3 = $number->mul(7, 0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

El ejemplo anterior mostrará:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "2.8"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(13) "-4.1956000000"
      ["scale"]=>
      int(10)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }

### Ver también

- bcmul() - Multiplica dos números de precisión arbitraria
- BcMath\Number::div() - Divide por un número de precisión arbitraria
- BcMath\Number::pow() - Eleva un número de precisión arbitraria
- BcMath\Number::powmod() - Eleva un número de precisión arbitraria, reducido por un módulo especificado

# BcMath\Number::pow

(PHP 8 >= 8.4.0)

BcMath\Number::pow — Eleva un número de precisión arbitraria

### Descripción

public function BcMath\Number::pow(BcMath\Number|string|int `$exponent`, ?int `$scale` = `null`): BcMath\Number

Eleva $this a la potencia `exponent`.

### Parámetros

`exponent`
  El exponente. Debe ser un valor sin parte fraccionaria. El rango válido del `exponent` es específico de la plataforma, pero es al menos de `-2147483648` a `2147483647`.
`scale`
  BcMath\Number::scale especificado explícitamente para los resultados del cálculo. Si `null`, el BcMath\Number::scale del resultado del cálculo será definido automáticamente.

### Valores devueltos

Devuelve el valor de la potencia como un nuevo objeto BcMath\Number.

Cuando el BcMath\Number::scale del resultado se establece automáticamente, según el valor de `exponent`, el BcMath\Number::scale del resultado será como sigue:

`exponent` | BcMath\Number::scale del resultado
--- | ---
positivo | (BcMath\Number::scale de la potencia base) * (el valor del `exponent`)
`0` | `0`
negativo | Entre (BcMath\Number::scale de la potencia base) y (BcMath\Number::scale de la potencia base + `10`)

Si se produce una división indivisible debido a un `exponent` negativo, el BcMath\Number::scale del resultado se extiende. La extensión se realiza solo si es necesario, hasta un máximo de `+10`. Este comportamiento es el mismo que BcMath\Number::div(), por lo que se debe consultar esto para más detalles.

### Errores/Excepciones

Este método lanza una ValueError en los siguientes casos:

- `exponent` es un string no es una cadena BCMath bien formada
- `exponent` tiene una parte fraccionaria
- `exponent` o `scale` está fuera del rango válido
- El BcMath\Number::scale del resultado está fuera del rango válido

Este método lanza una excepción DivisionByZeroError si el valor de $this es `0` y `exponent` es un valor negativo.

### Ejemplos

Ejemplo #1 Ejemplo de BcMath\Number::pow() cuando `scale` no está especificado

    <?php
    $number = new BcMath\Number('3.0');

    $ret1 = $number->pow(new BcMath\Number('5'));
    $ret2 = $number->pow('-1');
    $ret3 = $number->pow(0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

El ejemplo anterior mostrará:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "3.0"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(9) "243.00000"
      ["scale"]=>
      int(5)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(13) "0.33333333333"
      ["scale"]=>
      int(11)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }

Ejemplo #2 Ejemplo de BcMath\Number::pow() especificando `scale` explícitamente

    <?php
    $number = new BcMath\Number('3.0');

    $ret1 = $number->pow(new BcMath\Number('5'), 0);
    $ret2 = $number->pow('-1', 2);
    $ret3 = $number->pow(0, 10);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

El ejemplo anterior mostrará:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "3.0"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "243"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(4) "0.33"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(12) "1.0000000000"
      ["scale"]=>
      int(10)
    }

### Ver también

- bcpow() - Elevar un número de precisión arbitraria a otro
- BcMath\Number::powmod() - Eleva un número de precisión arbitraria, reducido por un módulo especificado
- BcMath\Number::mul() - Multiplica un número de precisión arbitraria
- BcMath\Number::sqrt() - Devuelve la raíz cuadrada de un número de precisión arbitraria
- BcMath\Number::div() - Divide por un número de precisión arbitraria

# BcMath\Number::powmod

(PHP 8 >= 8.4.0)

BcMath\Number::powmod — Eleva un número de precisión arbitraria, reducido por un módulo especificado

### Descripción

public function BcMath\Number::powmod(BcMath\Number|string|int `$exponent`, BcMath\Number|string|int `$modulus`, ?int `$scale` = `null`): BcMath\Number

Utiliza el método rápido de exponentiación para elevar $this a la potencia `exponent` en relación con el módulo `modulus`.

### Parámetros

`exponent`
  El exponente, como no negativo e integral (es decir, la escala debe ser cero).
`modulus`
  El módulo, como integral (es decir, la escala debe ser cero).
`scale`
  BcMath\Number::scale especificado explícitamente para los resultados del cálculo. Si `null`, el BcMath\Number::scale del resultado del cálculo será definido automáticamente.

### Valores devueltos

Devuelve el resultado en forma de un nuevo objeto BcMath\Number.

Cuando la propiedad BcMath\Number::scale del resultado se establece automáticamente, se utiliza la mayor BcMath\Number::scale de los tres números utilizados para la operación de módulo.

### Errores/Excepciones

Este método lanza una ValueError en los siguientes casos:

- `exponent` o `modulus` es un string y no es una cadena numérica BCMath bien formada
- $this, `exponent` o `modulus` tiene una parte fraccionaria
- `exponent` es un valor negativo
- `scale` está fuera del rango válido

Este método lanza una excepción DivisionByZeroError si `modulus` es `0`.

### Ejemplos

Ejemplo #1 Ejemplo de BcMath\Number::powmod() cuando `scale` no está especificado

    <?php
    var_dump(
        new BcMath\Number('8')->powmod(new BcMath\Number('3'), 5),
        new BcMath\Number('-8')->powmod(new BcMath\Number('3'), 5),
        new BcMath\Number('8')->powmod('2', -3),
        new BcMath\Number('-8')->powmod(5, 7),
    );
    ?>

El ejemplo anterior mostrará:

    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "2"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(2) "-2"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(2) "-1"
      ["scale"]=>
      int(0)
    }

Ejemplo #2 Ejemplo de BcMath\Number::powmod() especificando `scale` explícitamente

    <?php
    var_dump(
        new BcMath\Number('8')->powmod(new BcMath\Number('3'), 5, 1),
        new BcMath\Number('-8')->powmod(new BcMath\Number('3'), 5, 2),
        new BcMath\Number('8')->powmod('2', -3, 3),
        new BcMath\Number('-8')->powmod(5, 7, 4),
    );
    ?>

El ejemplo anterior mostrará:

    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "2.0"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "-2.00"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(5) "1.000"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(7) "-1.0000"
      ["scale"]=>
      int(4)
    }

### Ver también

- bcpowmod() - Eleva un número de precisión arbitraria a otro, reducido por un módulo especificado
- BcMath\Number::pow() - Eleva un número de precisión arbitraria
- BcMath\Number::mod() - Devuelve el módulo de un número de precisión arbitraria

# BcMath\Number::round

(PHP 8 >= 8.4.0)

BcMath\Number::round — Redondea un número de precisión arbitraria

### Descripción

public function BcMath\Number::round(int `$precision` = 0, RoundingMode `$mode` = `RoundingMode::HalfAwayFromZero`): BcMath\Number

Devuelve el valor redondeado de $this a la `precisión` especificada (el número de dígitos después del punto decimal). `precisión` puede ser también negativo o nulo (por omisión).

### Parámetros

`precision`

  El número opcional de decimales a redondear.

  Si el argumento `precision` es positivo, `num` será redondeado utilizando el argumento `precision` para definir el número significativo de dígitos después del punto decimal.

  Si el argumento `precision` es negativo, `num` será redondeado utilizando el argumento `precision` para definir el número significativo de dígitos antes del punto decimal, i.e. el múltiplo más cercano de `pow(10, -$precision)`, i.e. para una `precision` de -1, `num` será redondeado a 10, para una `precision` de -2 a 100, etc.

`mode`
  Especifica el método de redondeo. Para más información sobre los métodos, ver RoundingMode.

### Valores devueltos

Devuelve el resultado en forma de un nuevo objeto BcMath\Number.

### Errores/Excepciones

Este método lanza una ValueError si se especifica un `mode` inválido.

### Ejemplos

Ejemplo #1 Ejemplo de BcMath\Number::round()

    <?php
    var_dump(
        new BcMath\Number('3.4')->round(),
        new BcMath\Number('3.5')->round(),
        new BcMath\Number('3.6')->round(),
        new BcMath\Number('3.6')->round(0),
        new BcMath\Number('5.045')->round(2),
        new BcMath\Number('5.055')->round(2),
        new BcMath\Number('345')->round(-2),
        new BcMath\Number('345')->round(-3),
        new BcMath\Number('678')->round(-2),
        new BcMath\Number('678')->round(-3),
    );
    ?>

El ejemplo anterior mostrará:

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "4"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "4"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(1) "4"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#6 (2) {
      ["value"]=>
      string(4) "5.05"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(4) "5.06"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#8 (2) {
      ["value"]=>
      string(3) "300"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#9 (2) {
      ["value"]=>
      string(1) "0"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#10 (2) {
      ["value"]=>
      string(3) "700"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#11 (2) {
      ["value"]=>
      string(4) "1000"
      ["scale"]=>
      int(0)
    }

Ejemplo #2 Ejemplo de uso de BcMath\Number::round() con diferentes valores de `precisión`

    <?php
    $number = new BcMath\Number('123.45');

    var_dump(
        $number->round(3),
        $number->round(2),
        $number->round(1),
        $number->round(0),
        $number->round(-1),
        $number->round(-2),
        $number->round(-3),
    );
    ?>

El ejemplo anterior mostrará:

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(7) "123.450"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(6) "123.45"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "123.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(3) "123"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#6 (2) {
      ["value"]=>
      string(3) "120"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(3) "100"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#8 (2) {
      ["value"]=>
      string(1) "0"
      ["scale"]=>
      int(0)
    }

Ejemplo #3 Ejemplo de uso de BcMath\Number::round() con diferentes valores de `mode`

    <?php
    echo 'Modos de redondeo con 9.5' . PHP_EOL;
    $number = new BcMath\Number('9.5');
    var_dump(
        $number->round(0, RoundingMode::HalfAwayFromZero),
        $number->round(0, RoundingMode::HalfTowardsZero),
        $number->round(0, RoundingMode::HalfEven),
        $number->round(0, RoundingMode::HalfOdd),
        $number->round(0, RoundingMode::TowardsZero),
        $number->round(0, RoundingMode::AwayFromZero),
        $number->round(0, RoundingMode::NegativeInfinity),
        $number->round(0, RoundingMode::PositiveInfinity),
    );

    echo PHP_EOL;
    echo 'Modos de redondeo con 8.5' . PHP_EOL;
    $number = new BcMath\Number('8.5');
    var_dump(
        $number->round(0, RoundingMode::HalfAwayFromZero),
        $number->round(0, RoundingMode::HalfTowardsZero),
        $number->round(0, RoundingMode::HalfEven),
        $number->round(0, RoundingMode::HalfOdd),
        $number->round(0, RoundingMode::TowardsZero),
        $number->round(0, RoundingMode::AwayFromZero),
        $number->round(0, RoundingMode::NegativeInfinity),
        $number->round(0, RoundingMode::PositiveInfinity),
    );
    ?>

El ejemplo anterior mostrará:

    Modos de redondeo con 9.5
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#9 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#11 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#13 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#15 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#17 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }

    Modos de redondeo con 8.5
    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#15 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#13 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#11 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#9 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }

Ejemplo #4 Ejemplo de uso de BcMath\Number::round() con diferentes valores de `mode` especificando `precisión`

    <?php
    $positive = new BcMath\Number('1.55');
    $negative = new BcMath\Number('-1.55');

    echo 'Uso de RoundingMode::HalfAwayFromZero con precisión de 1 dígito decimal' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::HalfAwayFromZero),
        $negative->round(1, RoundingMode::HalfAwayFromZero),
    );

    echo PHP_EOL;
    echo 'Uso de RoundingMode::HalfTowardsZero con precisión de 1 dígito decimal' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::HalfTowardsZero),
        $negative->round(1, RoundingMode::HalfTowardsZero),
    );

    echo PHP_EOL;
    echo 'Uso de RoundingMode::HalfEven con precisión de 1 dígito decimal' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::HalfEven),
        $negative->round(1, RoundingMode::HalfEven),
    );

    echo PHP_EOL;
    echo 'Uso de RoundingMode::HalfOdd con precisión de 1 dígito decimal' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::HalfOdd),
        $negative->round(1, RoundingMode::HalfOdd),
    );

    echo PHP_EOL;
    echo 'Uso de RoundingMode::TowardsZero con precisión de 1 dígito decimal' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::TowardsZero),
        $negative->round(1, RoundingMode::TowardsZero),
    );

    echo PHP_EOL;
    echo 'Uso de RoundingMode::AwayFromZero con precisión de 1 dígito decimal' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::AwayFromZero),
        $negative->round(1, RoundingMode::AwayFromZero),
    );

    echo PHP_EOL;
    echo 'Uso de RoundingMode::NegativeInfinity con precisión de 1 dígito decimal' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::NegativeInfinity),
        $negative->round(1, RoundingMode::NegativeInfinity),
    );

    echo PHP_EOL;
    echo 'Uso de RoundingMode::PositiveInfinity con precisión de 1 dígito decimal' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::PositiveInfinity),
        $negative->round(1, RoundingMode::PositiveInfinity),
    );
    ?>

El ejemplo anterior mostrará:

    Uso de RoundingMode::HalfAwayFromZero con precisión de 1 dígito decimal
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(4) "-1.6"
      ["scale"]=>
      int(1)
    }

    Uso de RoundingMode::HalfTowardsZero con precisión de 1 dígito decimal
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#6 (2) {
      ["value"]=>
      string(4) "-1.5"
      ["scale"]=>
      int(1)
    }

    Uso de RoundingMode::HalfEven con precisión de 1 dígito decimal
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(4) "-1.6"
      ["scale"]=>
      int(1)
    }

    Uso de RoundingMode::HalfOdd con precisión de 1 dígito decimal
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#8 (2) {
      ["value"]=>
      string(4) "-1.5"
      ["scale"]=>
      int(1)
    }

    Uso de RoundingMode::TowardsZero con precisión de 1 dígito decimal
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#9 (2) {
      ["value"]=>
      string(4) "-1.5"
      ["scale"]=>
      int(1)
    }

    Uso de RoundingMode::AwayFromZero con precisión de 1 dígito decimal
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#10 (2) {
      ["value"]=>
      string(4) "-1.6"
      ["scale"]=>
      int(1)
    }

    Uso de RoundingMode::NegativeInfinity con precisión de 1 dígito decimal
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#11 (2) {
      ["value"]=>
      string(4) "-1.6"
      ["scale"]=>
      int(1)
    }

    Uso de RoundingMode::PositiveInfinity con precisión de 1 dígito decimal
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#12 (2) {
      ["value"]=>
      string(4) "-1.5"
      ["scale"]=>
      int(1)
    }

### Ver también

- bcround() - Redondea un número de precisión arbitraria
- BcMath\Number::ceil() - Redondea al alza un número de precisión arbitraria
- BcMath\Number::floor() - Redondea hacia abajo un número de precisión arbitraria

# BcMath\Number::__serialize

(PHP 8 >= 8.4.0)

BcMath\Number::__serialize — Serializa un objeto BcMath\Number

### Descripción

public function BcMath\Number::__serialize(): array

Serializa $this.

### Parámetros

Esta función no contiene ningún parámetro.

### Ver también

- BcMath\Number::__construct() - Crear un objeto BcMath\Number
- BcMath\Number::__unserialize() - Deserializa un argumento de datos en un objeto BcMath\Number

# BcMath\Number::sqrt

(PHP 8 >= 8.4.0)

BcMath\Number::sqrt — Devuelve la raíz cuadrada de un número de precisión arbitraria

### Descripción

public function BcMath\Number::sqrt(?int `$scale` = `null`): BcMath\Number

Devuelve la raíz cuadrada de $this.

### Parámetros

`scale`
  BcMath\Number::scale especificado explícitamente para los resultados del cálculo. Si `null`, el BcMath\Number::scale del resultado del cálculo será definido automáticamente.

### Valores devueltos

Devuelve la raíz cuadrada en forma de un nuevo objeto BcMath\Number.

Cuando el BcMath\Number::scale del resultado se define automáticamente, el BcMath\Number::scale de $this es utilizado. Sin embargo, en casos tales como la división indivisible, el BcMath\Number::scale del resultado se extiende. La expansión se realiza únicamente si es necesario, hasta un máximo de `+10`. Este comportamiento es similar al de BcMath\Number::div(), consulte esto para más detalles.

Es decir, si el BcMath\Number::scale de este objeto es `5`, el BcMath\Number::scale del resultado está entre `5` y `15`.

### Errores/Excepciones

Este método lanza una ValueError en los siguientes casos:

- $this es un valor negativo
- `scale` está fuera del rango válido
- El BcMath\Number::scale del resultado está fuera del rango válido

### Ejemplos

Ejemplo #1 Ejemplo de BcMath\Number::sqrt()

    <?php
    var_dump(
        new BcMath\Number('2')->sqrt(),
        new BcMath\Number('2')->sqrt(3),
        new BcMath\Number('4')->sqrt(),
        new BcMath\Number('4')->sqrt(3),
    );
    ?>

El ejemplo anterior mostrará:

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(12) "1.4142135623"
      ["scale"]=>
      int(10)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(5) "1.414"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "2"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(5) "2.000"
      ["scale"]=>
      int(3)
    }

### Ver también

- bcsqrt() - Obtiene la raiz cuadrada de un número de precisión arbitraria
- BcMath\Number::div() - Divide por un número de precisión arbitraria
- BcMath\Number::pow() - Eleva un número de precisión arbitraria

# BcMath\Number::sub

(PHP 8 >= 8.4.0)

BcMath\Number::sub — Sustrae un número de precisión arbitraria

### Descripción

public function BcMath\Number::sub(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Sustrae `num` de $this.

### Parámetros

`num`
  El valor a sustraer.
`scale`
  BcMath\Number::scale especificado explícitamente para los resultados del cálculo. Si `null`, el BcMath\Number::scale del resultado del cálculo será definido automáticamente.

### Valores devueltos

Devuelve el resultado de la sustracción como un nuevo objeto BcMath\Number.

Cuando el BcMath\Number::scale del resultado se define automáticamente, se utiliza el mayor BcMath\Number::scale de los dos números utilizados para la sustracción.

Es decir, si los BcMath\Number::scale de dos valores son `2` y `5` respectivamente, el BcMath\Number::scale del resultado será `5`.

### Errores/Excepciones

Este método lanza una ValueError en los siguientes casos:

- `num` es un string y no es una cadena numérica BCMath bien formada
- `scale` está fuera del rango válido

### Ejemplos

Ejemplo #1 Ejemplo de BcMath\Number::sub() cuando `scale` no está especificado

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->sub(new BcMath\Number('2.34567'));
    $ret2 = $number->sub('-3.456');
    $ret3 = $number->sub(7);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

El ejemplo anterior mostrará:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(8) "-1.11167"
      ["scale"]=>
      int(5)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(5) "4.690"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(6) "-5.766"
      ["scale"]=>
      int(3)
    }

Ejemplo #2 Ejemplo de BcMath\Number::sub() especificando `scale` explícitamente

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->sub(new BcMath\Number('2.34567'), 1);
    $ret2 = $number->sub('-3.456', 10);
    $ret3 = $number->sub(7, 0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

El ejemplo anterior mostrará:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(4) "-1.1"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(12) "4.6900000000"
      ["scale"]=>
      int(10)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(2) "-5"
      ["scale"]=>
      int(0)
    }

### Ver también

- bcsub() - Resta un número de precisión arbitraria de otro
- BcMath\Number::add() - Añadir un número de precisión arbitraria

# BcMath\Number::__toString

(PHP 8 >= 8.4.0)

BcMath\Number::__toString — Convierte un BcMath\Number en string

### Descripción

public function BcMath\Number::__toString(): string

Convierte un BcMath\Number en string.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve BcMath\Number::value en forma de string.

# BcMath\Number::__unserialize

(PHP 8 >= 8.4.0)

BcMath\Number::__unserialize — Deserializa un argumento de datos en un objeto BcMath\Number

### Descripción

public function BcMath\Number::__unserialize(array `$data`): void

Deserializa un argumento de datos en un objeto BcMath\Number.

### Parámetros

`data`
  El argumento de datos serializado como un array asociativo.

### Errores/Excepciones

Este método lanza una ValueError si se pasan datos serializados inválidos.

### Ver también

- BcMath\Number::__construct() - Crear un objeto BcMath\Number
- BcMath\Number::serialize()

## Tabla de contenidos

- BcMath\Number::add — Añadir un número de precisión arbitraria
- BcMath\Number::ceil — Redondea al alza un número de precisión arbitraria
- BcMath\Number::compare — Comparar dos números de precisión arbitraria
- BcMath\Number::__construct — Crear un objeto BcMath\Number
- BcMath\Number::div — Divide por un número de precisión arbitraria
- BcMath\Number::divmod — Devuelve el cociente y el módulo de un número de precisión arbitraria
- BcMath\Number::floor — Redondea hacia abajo un número de precisión arbitraria
- BcMath\Number::mod — Devuelve el módulo de un número de precisión arbitraria
- BcMath\Number::mul — Multiplica un número de precisión arbitraria
- BcMath\Number::pow — Eleva un número de precisión arbitraria
- BcMath\Number::powmod — Eleva un número de precisión arbitraria, reducido por un módulo especificado
- BcMath\Number::round — Redondea un número de precisión arbitraria
- BcMath\Number::__serialize — Serializa un objeto BcMath\Number
- BcMath\Number::sqrt — Devuelve la raíz cuadrada de un número de precisión arbitraria
- BcMath\Number::sub — Sustrae un número de precisión arbitraria
- BcMath\Number::__toString — Convierte un BcMath\Number en string
- BcMath\Number::__unserialize — Deserializa un argumento de datos en un objeto BcMath\Number

- Instalación/Configuración
  - Instalación
  - Configuración en tiempo de ejecución
- Funciones de BC Math
  - bcadd — Suma dos números de precisión arbitrária
  - bcceil — Redondea al alza un número de precisión arbitraria
  - bccomp — Comparar dos números de gran tamaño
  - bcdiv — Divide dos números de precisión arbitraria
  - bcdivmod — Devuelve el cociente y el resto de un número de precisión arbitraria
  - bcfloor — Redondea hacia abajo un número de precisión arbitraria
  - bcmod — Devuelve el resto de una división entre números de gran tamaño
  - bcmul — Multiplica dos números de precisión arbitraria
  - bcpow — Elevar 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
  - bcround — Redondea un número de precisión arbitraria
  - bcscale — Define o recupera la precisión por defecto para todas las funciones bc math
  - bcsqrt — Obtiene la raiz cuadrada de un número de precisión arbitraria
  - bcsub — Resta un número de precisión arbitraria de otro
- BcMath\Number — La clase BcMath\Number
  - BcMath\Number::add — Añadir un número de precisión arbitraria
  - BcMath\Number::ceil — Redondea al alza un número de precisión arbitraria
  - BcMath\Number::compare — Comparar dos números de precisión arbitraria
  - BcMath\Number::__construct — Crear un objeto BcMath\Number
  - BcMath\Number::div — Divide por un número de precisión arbitraria
  - BcMath\Number::divmod — Devuelve el cociente y el módulo de un número de precisión arbitraria
  - BcMath\Number::floor — Redondea hacia abajo un número de precisión arbitraria
  - BcMath\Number::mod — Devuelve el módulo de un número de precisión arbitraria
  - BcMath\Number::mul — Multiplica un número de precisión arbitraria
  - BcMath\Number::pow — Eleva un número de precisión arbitraria
  - BcMath\Number::powmod — Eleva un número de precisión arbitraria, reducido por un módulo especificado
  - BcMath\Number::round — Redondea un número de precisión arbitraria
  - BcMath\Number::__serialize — Serializa un objeto BcMath\Number
  - BcMath\Number::sqrt — Devuelve la raíz cuadrada de un número de precisión arbitraria
  - BcMath\Number::sub — Sustrae un número de precisión arbitraria
  - BcMath\Number::__toString — Convierte un BcMath\Number en string
  - BcMath\Number::__unserialize — Deserializa un argumento de datos en un objeto BcMath\Number

# GNU Multiple Precision

# Introducción

Estas funciones permiten trabajar con números de tamaño arbitrario, utilizando la biblioteca GNU MP.

> Nota:

> La mayoría de las funciones GMP aceptan números GMP como argumentos. Estos son mostrados en la documentación como objetos GMP. La mayoría de estas funciones aceptan también argumentos en forma numérica y de string, siempre que sea posible convertirlos posteriormente a número. Así, si existe una función más performante que pueda funcionar sobre los argumentos (enteros solamente), entonces será utilizada en su lugar (esto se hace de manera transparente). Ver también la función gmp_init().

> Nota:

> Operadores aritméticos, a nivel de bits, y de comparación pueden ser utilizados con los objetos GMP devueltos desde gmp_init() y las otras funciones GMP.

Advertencia

Si se desea especificar explícitamente un entero de gran tamaño, debe especificarse en forma de string. Si no se hace, PHP interpretará el entero y lo transformará en una representación interna, lo que seguramente hará perder precisión, antes de que `GMP` entre en juego. Los enteros voluminosos deben especificarse como strings - de lo contrario, PHP los fuerza a float, lo que provoca una pérdida de precisión.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación

## Requerimientos

La biblioteca GMP puede ser descargada desde el sitio web de » http://gmplib.org/#DOWNLOAD. Este sitio web también proporciona un manual GMP.

Al menos la versión 4.2 de GMP es requerida, con ciertas funciones que necesitan una versión más reciente de la biblioteca GMP.

En Windows, MPIR es requerido en lugar de GMP.

## Instalación

Para poder utilizar estas funciones, es necesario compilar PHP con GMP utilizando la opción --with-gmp.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`GMP_ROUND_ZERO` (int)
`GMP_ROUND_PLUSINF` (int)
`GMP_ROUND_MINUSINF` (int)
`GMP_MSW_FIRST` (int)
`GMP_LSW_FIRST` (int)
`GMP_LITTLE_ENDIAN` (int)
`GMP_BIG_ENDIAN` (int)
`GMP_NATIVE_ENDIAN` (int)
`GMP_VERSION` (string)
  La versión de la biblioteca GMP
`GMP_MPIR_VERSION` (string)
  La versión de la biblioteca MPIR.

# Ejemplos

Ejemplo #1 Función factorial usando GMP

    <?php
    function fact($x)
    {
        $return = 1;
        for ($i=2; $i <= $x; $i++) {
            $return = gmp_mul($return, $i);
        }
        return $return;
    }

    echo gmp_strval(fact(1000)) . "\n";
    ?>

Esto va a calcular el factorial de 1000 (Un bonito gran número) muy rápido.

# Funciones de GMP

## Ver también

Más funciones matemáticas pueden ser encontradas en la Extensiones matemáticas sección

# gmp_abs

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_abs — Valor absoluto

### Descripción

function gmp_abs(GMP|int|string `$num`): GMP

Obtiene el valor absoluto de un número.

### Parámetros

`num`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Devuelve el valor absoluto `num`, como un número GMP.

### Ejemplos

Ejemplo #1 Ejemplo de gmp_abs()

    <?php
    $abs1 = gmp_abs("274982683358");
    $abs2 = gmp_abs("-274982683358");

    echo gmp_strval($abs1) . "\n";
    echo gmp_strval($abs2) . "\n";
    ?>

El ejemplo anterior mostrará:

    274982683358
    274982683358

# gmp_add

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_add — Adición de 2 números GMP

### Descripción

function gmp_add(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Adición de 2 números GMP.

### Parámetros

`num1`
  El primer operando (augend). Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`num2`

  El segundo operando (augend).

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Un número GMP que representa la suma de los argumentos.

### Ejemplos

Ejemplo #1 Ejemplo con gmp_add()

    <?php
    $sum = gmp_add("123456789012345", "76543210987655");
    echo gmp_strval($sum) . "\n";
    ?>

El ejemplo anterior mostrará:

    200000000000000

# gmp_and

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_and — AND a nivel de bit

### Descripción

function gmp_and(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Calcula el AND a nivel de bit de dos números GMP.

### Parámetros

`num1`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`num2`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Un número representando la comparación del nivel de bit `AND`.

### Ejemplos

Ejemplo #1 Ejemplo de gmp_and()

    <?php
    $and1 = gmp_and("0xfffffffff4", "0x4");
    $and2 = gmp_and("0xfffffffff4", "0x8");
    echo gmp_strval($and1) . "\n";
    echo gmp_strval($and2) . "\n";
    ?>

El ejemplo anterior mostrará:

    4
    0

# gmp_binomial

(PHP 7 >= 7.3.0, PHP 8)

gmp_binomial — Calcula el coeficiente binomial

### Descripción

function gmp_binomial(GMP|int|string `$n`, int `$k`): GMP

Calcula el coeficiente binomial C(n, k).

### Parámetros

`n`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`k`

### Valores devueltos

Retorna el coeficiente binomial C(n, k).

### Errores/Excepciones

Lanza una ValueError si `k` es negativo. Anterior a PHP 8.0.0, se emitía `E_WARNING` en su lugar.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función ya no retorna `false` en caso de fallo.

# gmp_clrbit

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_clrbit — Anula un byte

### Descripción

function gmp_clrbit(GMP `$num`, int `$index`): void

Establece a 0 el byte `index` en el número GMP `num`. El índice comienza en cero.

### Parámetros

`num`

  Un objeto GMP

`index`

  El índice del byte a anular. El índice 0 representa el último byte significativo.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con gmp_clrbit()

    <?php
    $a = gmp_init("0xff");
    gmp_clrbit($a, 0); // el índice comienza en cero
    echo gmp_strval($a) . "\n";
    ?>

El ejemplo anterior mostrará:

    254

### Notas

> Nota:

> A diferencia de la mayoría de las otras funciones GMP, gmp_clrbit() debe ser llamada con un objeto GMP ya existente (usando gmp_init() por ejemplo). No será creada automáticamente.

### Ver también

- gmp_setbit() - Modifica un bit
- gmp_testbit() - Prueba si un bit está definido

# gmp_cmp

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_cmp — Compara los números

### Descripción

function gmp_cmp(GMP|int|string `$num1`, GMP|int|string `$num2`): int

Compara dos números.

### Parámetros

`num1`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`num2`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Devuelve un valor positivo si `a > b`, el cero si `a = b` y el valor negativo de a si `a < b`.

### Ejemplos

Ejemplo #1 Ejemplo de gmp_cmp()

    <?php
    $cmp1 = gmp_cmp("1234", "1000"); // mayor que
    $cmp2 = gmp_cmp("1000", "1234"); // menor que
    $cmp3 = gmp_cmp("1234", "1234"); // igual a

    echo "$cmp1 $cmp2 $cmp3\n";
    ?>

El ejemplo anterior mostrará:

    1 -1 0

# gmp_com

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_com — Calcula uno de los complementos

### Descripción

function gmp_com(GMP|int|string `$num`): GMP

Devuelve uno de los complementos de `num`.

### Parámetros

`num`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Devuelve uno de los complementos de `num`, como un número GMP.

### Ejemplos

Ejemplo #1 Ejemplo de gmp_com()

    <?php
    $com = gmp_com("1234");
    echo gmp_strval($com) . "\n";
    ?>

El ejemplo anterior mostrará:

    -1235

# gmp_div

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div — Alias de gmp_div_q()

### Descripción

Esta función es un alias de: gmp_div_q().

# gmp_div_q

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div_q — Divide los números

### Descripción

function gmp_div_q(GMP|int|string `$num1`, GMP|int|string `$num2`, int `$rounding_mode` = `GMP_ROUND_ZERO`): GMP

Divide `num1` con `num2` y devuelve el entero resultante.

### Parámetros

`num1`

  El número que sera dividido.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`num2`

  El número que `num1` esta siendo dividido.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`rounding_mode`

  El redondeo resultante es definido por el `rounding_mode`, el cual puede tener uno de los siguientes valores:

  - `GMP_ROUND_ZERO`: El resultante es truncado hacia 0.
  - `GMP_ROUND_PLUSINF`:El resultado es redondeado hacia `+infinity`.
  - `GMP_ROUND_MINUSINF`: El resultado es redondeado hacia `-infinity`.
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Un objeto GMP.

### Ejemplos

Ejemplo #1 Ejemplo de gmp_div_q()

    <?php
    $div1 = gmp_div_q("100", "5");
    echo gmp_strval($div1) . "\n";

    $div2 = gmp_div_q("1", "3");
    echo gmp_strval($div2) . "\n";

    $div3 = gmp_div_q("1", "3", GMP_ROUND_PLUSINF);
    echo gmp_strval($div3) . "\n";

    $div4 = gmp_div_q("-1", "4", GMP_ROUND_PLUSINF);
    echo gmp_strval($div4) . "\n";

    $div5 = gmp_div_q("-1", "4", GMP_ROUND_MINUSINF);
    echo gmp_strval($div5) . "\n";
    ?>

El ejemplo anterior mostrará:

    20
    0
    1
    0
    -1

### Notas

> Nota:

> Esta función también puede ser llamada como gmp_div().

### Ver también

- gmp_div_r() - El resto de la división de los números
- gmp_div_qr() - Divide los números y obtiene el cociente y resto

# gmp_div_qr

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div_qr — Divide los números y obtiene el cociente y resto

### Descripción

function gmp_div_qr(GMP|int|string `$num1`, GMP|int|string `$num2`, int `$rounding_mode` = `GMP_ROUND_ZERO`): array

La función divide a `num1` por `num2`.

### Parámetros

`num1`

  El número que es dividido.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`num2`

  El número que es dividido por `num1`.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`rounding_mode`

  Ver la función gmp_div_q() para la descripción del argumento `rounding_mode`.

### Valores devueltos

Devuelve un array, con el primer elemento siendo `[n/d]` (el entero resultante de la división) y el segundo siendo `(n - [n/d] * d)` (el resto de la división).

### Ejemplos

Ejemplo #1 División de números GMP

    <?php
    $a = gmp_init("0x41682179fbf5");
    $res = gmp_div_qr($a, "0xDEFE75");
    printf("El resultado es: q - %s, r - %s",
           gmp_strval($res[0]), gmp_strval($res[1]));
    ?>

### Ver también

- gmp_div_q() - Divide los números
- gmp_div_r() - El resto de la división de los números

# gmp_div_r

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div_r — El resto de la división de los números

### Descripción

function gmp_div_r(GMP|int|string `$num1`, GMP|int|string `$num2`, int `$rounding_mode` = `GMP_ROUND_ZERO`): GMP

Calcula el resto de la división entera de `num1` por `num2`. El tiene el signo del argumento `num1`, si no es cero.

### Parámetros

`num1`

  El número que es dividido.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`num2`

  El número que es dividido por `num1`.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`rounding_mode`

  Ver la función gmp_div_q() para la descripción del argumento `rounding_mode`.

### Valores devueltos

El resto, como número GMP.

### Ejemplos

Ejemplo #1 Ejemplo de gmp_div_r()

    <?php
    $div = gmp_div_r("105", "20");
    echo gmp_strval($div) . "\n";
    ?>

El ejemplo anterior mostrará:

    5

### Ver también

- gmp_div_q() - Divide los números
- gmp_div_qr() - Divide los números y obtiene el cociente y resto

# gmp_divexact

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_divexact — División exacta de números GMP

### Descripción

function gmp_divexact(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Divide `num1` entre `num2`, utilizando los algoritmos de "división exacta". Esta función solo proporciona resultados coherentes cuando se sabe de antemano que `num2` divide `num1`.

### Parámetros

`num1`

  El número a dividir.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`num2`

  El divisor.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Un objeto GMP.

### Ejemplos

Ejemplo #1 Ejemplo con gmp_divexact()

    <?php
    $div1 = gmp_divexact("10", "2");
    echo gmp_strval($div1) . "\n";

    $div2 = gmp_divexact("10", "3"); // resultado incoherente
    echo gmp_strval($div2) . "\n";
    ?>

El ejemplo anterior mostrará:

    5
    2863311534

# gmp_export

(PHP 5 >= 5.6.1, PHP 7, PHP 8)

gmp_export — Exportación hacia un string binario

### Descripción

function gmp_export(GMP|int|string `$num`, int `$word_size` = 1, int `$flags` = GMP_MSW_FIRST | GMP_NATIVE_ENDIAN): string

Exporta un número GMP hacia un string binario.

### Parámetros

`num`

  El número GMP a exportar.

`word_size`

  El valor por omisión es 1. El número de bytes en cada parte de datos binarios. Principalmente utilizado con el argumento options.

`flags`

  El valor por omisión es `GMP_MSW_FIRST` | `GMP_NATIVE_ENDIAN`.

### Valores devueltos

Retorna un string.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función ya no retorna `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con gmp_export()

    <?php
    $number = gmp_init(16705);
    echo gmp_export($number) . "\n";
    ?>

El ejemplo anterior mostrará:

    AA

### Ver también

- gmp_import() - Importación desde una cadena binaria

# gmp_fact

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_fact — Factorielle GMP

### Descripción

function gmp_fact(GMP|int|string `$num`): GMP

Calcula la factorielle (`num!`) de `num`.

### Parámetros

`num`

  El número factoriel.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Un objeto GMP.

### Ejemplos

Ejemplo #1 Ejemplo con gmp_fact()

    <?php
    $fact1 = gmp_fact(5); // 5 * 4 * 3 * 2 * 1
    echo gmp_strval($fact1) . "\n";

    $fact2 = gmp_fact(50); // 50 * 49 * 48, ... etc
    echo gmp_strval($fact2) . "\n";
    ?>

El ejemplo anterior mostrará:

    120
    30414093201713378043612608166064768844377641568960512000000000000

# gmp_gcd

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_gcd — Calcula el máximo común divisor

### Descripción

function gmp_gcd(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Calcula el máximo común divisor de `num1` y `num2`. El resultado es siempre positivo aun si cualquiera de, o ambos, operadores fueran negativos.

### Parámetros

`num1`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`num2`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Un número positivo GMP que divide dentro a ambos `num1` y `num2`.

### Ejemplos

Ejemplo #1 Ejemplo degmp_gcd()

    <?php
    $gcd = gmp_gcd("12", "21");
    echo gmp_strval($gcd) . "\n";
    ?>

El ejemplo anterior mostrará:

    3

### Ver también

- gmp_lcm() - Calcula el Mínimo Común Múltiplo (MCM)

# gmp_gcdext

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_gcdext — Calcula el máximo común divisor y multiplicadores

### Descripción

function gmp_gcdext(GMP|int|string `$num1`, GMP|int|string `$num2`): array

Calcula g, s, y t, tal que `a*s + b*t = g = gcd(a,b)`, donde gcd es el máximo común divisor. Devuelve un arreglo con los elementos respectivos g, s y t.

Esta función puede ser usada para resolver ecuaciones diofánticas lineales en dos variables. Son ecuaciones que solo admiten soluciones enteras y tienen la forma: `a*x + b*y = c`. Para más información, vaya a » "Ecuación diofántica" en la página MathWorld

### Parámetros

`num1`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`num2`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Un array de números GMP.

### Ejemplos

Ejemplo #1 Resolver ecuaciones de diofántica lineal

    <?php
    // Resolver la ecuación a*s + b*t = g
    // donde a = 12, b = 21, g = gcd(12, 21) = 3
    $a = gmp_init(12);
    $b = gmp_init(21);
    $g = gmp_gcd($a, $b);
    $r = gmp_gcdext($a, $b);

    $check_gcd = (gmp_strval($g) == gmp_strval($r['g']));
    $eq_res = gmp_add(gmp_mul($a, $r['s']), gmp_mul($b, $r['t']));
    $check_res = (gmp_strval($g) == gmp_strval($eq_res));

    if ($check_gcd && $check_res) {
        $fmt = "Solución: %d*%d + %d*%d = %d\n";
        printf($fmt, gmp_strval($a), gmp_strval($r['s']), gmp_strval($b),
        gmp_strval($r['t']), gmp_strval($r['g']));
    } else {
        echo "Error mientras se resolvia la ecuación\n";
    }

    // output: Solución: 12*2 + 21*-1 = 3
    ?>

# gmp_hamdist

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_hamdist — Distancia Hamming

### Descripción

function gmp_hamdist(GMP|int|string `$num1`, GMP|int|string `$num2`): int

Devuelve la distancia hamming entre `num1` y `num2`. Ambos operadores deberían ser no negativos.

### Parámetros

`num1`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

  Debería ser positivo.

`num2`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

  Debería ser positivo.

### Valores devueltos

La distancia de Hamming entre `num1` y `num2`, como un int.

### Ejemplos

Ejemplo #1 Ejemplo degmp_hamdist()

    <?php
    $ham1 = gmp_init("1001010011", 2);
    $ham2 = gmp_init("1011111100", 2);
    echo gmp_hamdist($ham1, $ham2) . "\n";

    /* la distancia hamming es equivalente a: */
    echo gmp_popcount(gmp_xor($ham1, $ham2)) . "\n";
    ?>

El ejemplo anterior mostrará:

    6
    6

### Ver también

- gmp_popcount() - Cuenta la población
- gmp_xor() - Nivel de bit XOR

# gmp_import

(PHP 5 >= 5.6.1, PHP 7, PHP 8)

gmp_import — Importación desde una cadena binaria

### Descripción

function gmp_import(string `$data`, int `$word_size` = 1, int `$flags` = GMP_MSW_FIRST | GMP_NATIVE_ENDIAN): GMP

Importa un número GMP desde una cadena binaria.

### Parámetros

`data`

  La cadena binaria a importar.

`word_size`

  El valor por omisión es 1. El número de bytes en cada parte de datos binarios. Principalmente utilizado con el argumento options.

`flags`

  El valor por omisión es `GMP_MSW_FIRST` | `GMP_NATIVE_ENDIAN`.

### Valores devueltos

Devuelve un número GMP.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Esta función ya no devuelve `false` en caso de error.

### Ejemplos

Ejemplo #1 Ejemplo con gmp_import()

    <?php
    $number = gmp_import("\0");
    echo gmp_strval($number) . "\n";

    $number = gmp_import("\0\1\2");
    echo gmp_strval($number) . "\n";
    ?>

El ejemplo anterior mostrará:

    0
    258

### Ver también

- gmp_export() - Exportación hacia un string binario

# gmp_init

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_init — Crea un número GMP

### Descripción

function gmp_init(int|string `$num`, int `$base` = 0): GMP

Crea un número GMP, a partir de un entero o de un string.

### Parámetros

`num`
  Un entero o un string. El string puede ser una representación decimal, hexadecimal, octal o binaria.
`base`
  La base a utilizar para convertir una representación en forma de string. Una base explícita puede estar comprendida entre `2` y `62`. Para las bases hasta `36`, la casilla es ignorada: las letras mayúsculas y minúsculas tienen el mismo valor. Para las bases de `37` a `62`, las letras mayúsculas representan los valores de `10` a `35` y las letras minúsculas representan los valores de `36` a `61`. Si `base` vale `0`, entonces la base real es determinada a partir de los caracteres iniciales de `num`. Si los dos primeros caracteres son `0x` o `0X`, el string es interpretado como un entero hexadecimal. Si los dos primeros caracteres son `0b` o `0B`, el string es interpretado como un entero binario. Si los dos primeros caracteres son `0o` o `0O`, el string es interpretado como un entero octal. Además, si el primer carácter es `0`, el string es igualmente interpretado como un entero octal. En todos los demás casos, el string es interpretado como un entero decimal.

### Valores devueltos

Un objeto GMP.

### Historial de cambios

Versión | Descripción
--- | ---
8.1.0 | El soporte para los prefijos octales explícitos `0o` y `0O` ha sido añadido para los strings `num`. La interpretación de estos prefijos cuando `base` vale `0` ha sido igualmente añadida.

### Ejemplos

Ejemplo #1 Creación de un número GMP

    <?php
    $a = gmp_init(123456);
    $b = gmp_init("0xFFFFDEBACDFEDF7200");
    ?>

### Notas

> Nota:

> No es necesario llamar a esta función para utilizar enteros o strings en lugar de números GMP en las funciones GMP, como gmp_add(). Los argumentos de estas funciones son automáticamente convertidos en números GMP, si esta conversión es posible y necesaria, utilizando las mismas reglas que gmp_init().

### Ver también

- GMP::__construct() - Crea un número GMP

# gmp_intval

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_intval — Convertir un número GMP a entero

### Descripción

function gmp_intval(GMP|int|string `$num`): int

Esta función convierte un número GMP an un int nativo de PHP.

### Parámetros

`num`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

El valor int de `num`.

### Ejemplos

Ejemplo #1 Ejemplo de gmp_intval()

    <?php
    // muestra el valor correcto
    echo gmp_intval("2147483647") . "\n";

    //muestra el valor correcto
    echo gmp_intval("2147483648") . "\n";

    // muestra el valor correcto
    echo gmp_strval("2147483648") . "\n";
    ?>

El ejemplo anterior mostrará:

    2147483647
    2147483647
    2147483648

### Notas

Advertencia

Ésta función retorna un resultado satisfactorio solo si el numero actualmente encaja con el PHP entero (ej., símbolo de tipo largo). Para imprimir simplemente el número GMP, use gmp_strval().

# gmp_invert

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_invert — Inverso del modulo

### Descripción

function gmp_invert(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP|false

Computa el inverso del modulo de `num1` `num2`.

### Parámetros

`num1`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`num2`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Un número GMO en éxito o `false` Si el inverso.

### Ejemplos

Ejemplo #1 Ejemplo de gmp_invert()

    <?php
    echo gmp_invert("5", "10"); // sin inverso, ninguna salida, el resultado es falso
    $invert = gmp_invert("5", "11");
    echo gmp_strval($invert) . "\n";
    ?>

El ejemplo anterior mostrará:

    9

# gmp_jacobi

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_jacobi — Símbolo Jacobi

### Descripción

function gmp_jacobi(GMP|int|string `$num1`, GMP|int|string `$num2`): int

Computa el » símbolo Jacobi de `num1` y `num2`. `num2` debería ser impar y tiene que ser positivo.

### Parámetros

`num1`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`num2`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

  Debería ser impar y tiene que ser positivo.

### Valores devueltos

Un objeto GMP.

### Ejemplos

Ejemplo #1 Ejemplo de gmp_jacobi()

    <?php
    echo gmp_jacobi("1", "3") . "\n";
    echo gmp_jacobi("2", "3") . "\n";
    ?>

El ejemplo anterior mostrará:

    1
    0

### Ver también

- gmp_kronecker() - Símbolo Kronecker
- gmp_legendre() - Símbolo Legendre

# gmp_kronecker

(PHP 7 >= 7.3.0, PHP 8)

gmp_kronecker — Símbolo Kronecker

### Descripción

function gmp_kronecker(GMP|int|string `$num1`, GMP|int|string `$num2`): int

Esta función calcula el símbolo Kronecker de `num1` y `num2`.

### Parámetros

`num1`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`num2`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Devuelve el símbolo Kronecker de `num1` y `num2`.

### Ver también

- gmp_jacobi() - Símbolo Jacobi
- gmp_legendre() - Símbolo Legendre

# gmp_lcm

(PHP 7 >= 7.3.0, PHP 8)

gmp_lcm — Calcula el Mínimo Común Múltiplo (MCM)

### Descripción

function gmp_lcm(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Esta función calcula el mínimo común múltiplo (MCM) de `num1` y `num2`.

### Parámetros

`num1`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`num2`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Un objeto GMP.

### Ver también

- gmp_gcd() - Calcula el máximo común divisor

# gmp_legendre

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_legendre — Símbolo Legendre

### Descripción

function gmp_legendre(GMP|int|string `$num1`, GMP|int|string `$num2`): int

Computa el » Símbolo Legendre de `num1` y `num2`. `num2` debería ser impar y tiene que ser positivo.

### Parámetros

`num1`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`num2`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

  debería ser impar y tiene que ser positivo.

### Valores devueltos

Un objeto GMP.

### Ejemplos

Ejemplo #1 Ejemplo de gmp_legendre()

    <?php
    echo gmp_legendre("1", "3") . "\n";
    echo gmp_legendre("2", "3") . "\n";
    ?>

El ejemplo anterior mostrará:

    1
    0

### Ver también

- gmp_jacobi() - Símbolo Jacobi
- gmp_kronecker() - Símbolo Kronecker

# gmp_mod

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_mod — Modulo de operación

### Descripción

function gmp_mod(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Calcula el modulo de `num1` `num2`. El resultado es siempre no negativo, el símbolo de `num2` es ignorado.

### Parámetros

`num1`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`num2`

  El modulo que es evaluado.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Un objeto GMP.

### Ejemplos

Ejemplo #1 Ejemplo de gmp_mod()

    <?php
    $mod = gmp_mod("8", "3");
    echo gmp_strval($mod) . "\n";
    ?>

El ejemplo anterior mostrará:

    2

# gmp_mul

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_mul — Multiplicación de números

### Descripción

function gmp_mul(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Multiplicación de `num1` por `num2` y devuelve el resultado.

### Parámetros

`num1`

  Un número que va a ser multiplicado por `num2`.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`num2`

  Un número que va a ser multiplicado por `num1`.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Un objeto GMP.

### Ejemplos

Ejemplo #1 Ejemplo degmp_mul()

    <?php
    $mul = gmp_mul("12345678", "2000");
    echo gmp_strval($mul) . "\n";
    ?>

El ejemplo anterior mostrará:

    24691356000

# gmp_neg

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_neg — Número negativo

### Descripción

function gmp_neg(GMP|int|string `$num`): GMP

Devuelve el valor negativo de un número.

### Parámetros

`num`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Devuelve -`num`, como un número GMP.

### Ejemplos

Ejemplo #1 Ejemplo degmp_neg()

    <?php
    $neg1 = gmp_neg("1");
    echo gmp_strval($neg1) . "\n";
    $neg2 = gmp_neg("-1");
    echo gmp_strval($neg2) . "\n";
    ?>

El ejemplo anterior mostrará:

    -1
    1

# gmp_nextprime

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

gmp_nextprime — Encuentra el siguiente número primo

### Descripción

function gmp_nextprime(GMP|int|string `$num`): GMP

Encuentra el siguiente número primo

### Parámetros

`num`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Devuelve el siguiente número primo o mayor `num`, como un número GMP.

### Ejemplos

Ejemplo #1 Ejemplo de gmp_nextprime()

    <?php
    $prime1 = gmp_nextprime(10); // el siguiente número primo o superior que 10
    $prime2 = gmp_nextprime(-1000); // el siguiente número primo o superior que -1000

    echo gmp_strval($prime1) . "\n";
    echo gmp_strval($prime2) . "\n";
    ?>

El ejemplo anterior mostrará:

    11
    2

### Notas

> Nota:

> Ésta función usa un algoritmo probabilístico para identificar el número primo y posibilita la obtención de un número compuesto que sea extremadamente pequeño.

# gmp_or

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_or — Nivel de bit OR

### Descripción

function gmp_or(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Calcula el nivel de bit OR de dos números GMP.

### Parámetros

`num1`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`num2`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Un objeto GMP.

### Ejemplos

Ejemplo #1 Ejemplo de gmp_or()

    <?php
    $or1 = gmp_or("0xfffffff2", "4");
    echo gmp_strval($or1, 16) . "\n";
    $or2 = gmp_or("0xfffffff2", "2");
    echo gmp_strval($or2, 16) . "\n";
    ?>

El ejemplo anterior mostrará:

    fffffff6
    fffffff2

# gmp_perfect_power

(PHP 7 >= 7.3.0, PHP 8)

gmp_perfect_power — Verifica si un número es una potencia perfecta

### Descripción

function gmp_perfect_power(GMP|int|string `$num`): bool

Verifica si `num` es una potencia perfecta.

### Parámetros

`num`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Devuelve `true` si `num` es una potencia perfecta, `false` en caso contrario.

### Ver también

- gmp_perfect_square() - Comprueba el cuadrado perfecto

# gmp_perfect_square

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_perfect_square — Comprueba el cuadrado perfecto

### Descripción

function gmp_perfect_square(GMP|int|string `$num`): bool

Revisa si un número es cuadrado perfecto.

### Parámetros

`num`

  El número a ser revisado como un cuadrado perfecto.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Devielve `true` si `num` es un cuadrado perfecto, sino `false`.

### Ejemplos

Ejemplo #1 Ejemplo de gmp_perfect_square()

    <?php
    // 3 * 3, cuadrado perfecto
    var_dump(gmp_perfect_square("9"));

    // no es un cuadrado perfecto
    var_dump(gmp_perfect_square("7"));

    // 1234567890 * 1234567890, cuadrado perfecto
    var_dump(gmp_perfect_square("1524157875019052100"));
    ?>

El ejemplo anterior mostrará:

    bool(true)
    bool(false)
    bool(true)

### Ver también

- gmp_perfect_power() - Verifica si un número es una potencia perfecta
- gmp_sqrt() - Calcula la raíz cuadrada
- gmp_sqrtrem() - Raíz cuadrada con resto

# gmp_popcount

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_popcount — Cuenta la población

### Descripción

function gmp_popcount(GMP|int|string `$num`): int

Obtiene el conteo de la población.

### Parámetros

`num`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

El conteo de la población de `num`, como un int.

### Ejemplos

Ejemplo #1 Ejemplo de gmp_popcount()

    <?php
    $pop1 = gmp_init("10000101", 2); // tres 1
    echo gmp_popcount($pop1) . "\n";
    $pop2 = gmp_init("11111110", 2); // siete 1
    echo gmp_popcount($pop2) . "\n";
    ?>

El ejemplo anterior mostrará:

    3
    7

# gmp_pow

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_pow — Aumenta el número a la potencia

### Descripción

function gmp_pow(GMP|int|string `$num`, int `$exponent`): GMP

Aumenta la `num` a la potencia `exponent`.

### Parámetros

`num`

  La base del número.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`exponent`

  La potencia positiva a elevar la `num`.

### Valores devueltos

El nuevo (elevado) número, como un número GMP. El caso de `0^0` produce 1.

### Ejemplos

Ejemplo #1 Ejemplo de gmp_pow()

    <?php
    $pow1 = gmp_pow("2", 31);
    echo gmp_strval($pow1) . "\n";
    $pow2 = gmp_pow("0", 0);
    echo gmp_strval($pow2) . "\n";
    $pow3 = gmp_pow("2", -1); // exponente negativo, genera peligro
    echo gmp_strval($pow3) . "\n";
    ?>

El ejemplo anterior mostrará:

    2147483648
    1

# gmp_powm

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_powm — Eleva un número a la potencia con modulo

### Descripción

function gmp_powm(GMP|int|string `$num`, GMP|int|string `$exponent`, GMP|int|string `$modulus`): GMP

Calcula la (`num` elevada a la potencia `exponent`) con modulo `modulus`. Si `exponent` es negativo, el resultado es indefinido.

### Parámetros

`num`

  La base del número.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`exponent`

  La potencia positiva a elevar la `num`.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`modulus`

  El modulo.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

El nuevo (elevado) número, como un número GMP.

### Ejemplos

Ejemplo #1 Ejemplo de gmp_powm()

    <?php
    $pow1 = gmp_powm("2", "31", "2147483649");
    echo gmp_strval($pow1) . "\n";
    ?>

El ejemplo anterior mostrará:

    2147483648

# gmp_prob_prime

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_prob_prime — Revisa si el número es "probablemente primo"

### Descripción

function gmp_prob_prime(GMP|int|string `$num`, int `$repetitions` = 10): int

La función usa la prueba probabilística de Miller-Rabin para revisar si un número es primo.

### Parámetros

`num`

  El número a ser revisado como primo.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`repetitions`

  Valores rasonables de `repetitions` varían de 5 a 10 (por defecto siendo 10); un valor superior disminuye la probabilidad para un número no primo a pasar como un "probable" primo.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Si ésta función devolvier 0, `num` es definitivamente no primo. Si devuelve 1, entonces `num` es "probablemente" primo. si devolviera 2, entonces `num` es seguramente primo.

### Ejemplos

Ejemplo #1 Ejemplo de gmp_prob_prime()

    <?php
    // definitivamente no primo
    echo gmp_prob_prime("6") . "\n";

    // probablemente primo
    echo gmp_prob_prime("1111111111111111111") . "\n";

    // definitivamente primo
    echo gmp_prob_prime("11") . "\n";
    ?>

El ejemplo anterior mostrará:

    0
    1
    2

# gmp_random

(PHP 4 >= 4.0.4, PHP 5, PHP 7)

gmp_random — Número GMP aleatorio

Advertencia

Esta funcionalidad está OBSOLETA a partir de PHP 7.2.0 y ha sido ELIMINADA a partir de PHP 8.0.0.

### Descripción

function gmp_random(int `$limiter` = 20): GMP

Genera un número aleatorio. Este número estará comprendido entre cero y (2 ** n) -1, donde n es el número de bits por limb multiplicado por `limiter`. Si `limiter` es negativo, se genera un número negativo.

Un limb es un mecanismo interno de GMP. El número de bits en un limb no es estático, y puede variar entre los sistemas. En general, el número de bits por limb es 32 o 64, pero esto no está garantizado.

Precaución

Esta función no genera valores criptográficamente seguros, y no debe ser utilizada con fines criptográficos, o con fines que requieran que los valores devueltos sean indescifrables.

Si se requiere aleatoriedad criptográficamente segura, el Random\Randomizer puede ser utilizado con el motor Random\Engine\Secure. Para casos de uso simples, las funciones random_int() y random_bytes() proporcionan una API práctica y segura que es soportada por el CSPRNG del sistema operativo.

### Parámetros

`limiter`

  El limitador.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Un número GMP aleatorio.

### Ejemplos

Ejemplo #1 Ejemplo con gmp_random()

    <?php
    $rand1 = gmp_random(1); // número aleatorio de 0 a 1 * bits por limb
    $rand2 = gmp_random(2); // número aleatorio de 0 a 2 * bits por limb

    echo gmp_strval($rand1) . "\n";
    echo gmp_strval($rand2) . "\n";
    ?>

El ejemplo anterior mostrará:

    1915834968
    8642564075890328087

# gmp_random_bits

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

gmp_random_bits — Genera un número aleatorio

### Descripción

function gmp_random_bits(int `$bits`): GMP

Genera un número aleatorio. El número estará en el intervalo `0` y `2$bits - 1`.

El argumento `bits` debe ser mayor que 0, y el valor máximo estará restringido por la memoria disponible.

Precaución

Esta función no genera valores criptográficamente seguros, y no debe ser utilizada con fines criptográficos, o con fines que requieran que los valores devueltos sean indescifrables.

Si se requiere aleatoriedad criptográficamente segura, el Random\Randomizer puede ser utilizado con el motor Random\Engine\Secure. Para casos de uso simples, las funciones random_int() y random_bytes() proporcionan una API práctica y segura que es soportada por el CSPRNG del sistema operativo.

### Parámetros

`bits`

  El número de bits a generar.

### Valores devueltos

Un número GMP aleatorio.

### Errores/Excepciones

Si `bits` es menor que `1`, se lanzará una ValueError.

### Ejemplos

Ejemplo #1 Ejemplo con gmp_random_bits()

    <?php
    $rand1 = gmp_random_bits(3); // número aleatorio entre 0 y 7
    $rand2 = gmp_random_bits(5); // número aleatorio entre 0 y 31

    echo gmp_strval($rand1) . "\n";
    echo gmp_strval($rand2) . "\n";
    ?>

El ejemplo anterior mostrará:

    3
    15

# gmp_random_range

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

gmp_random_range — Obtener un entero seleccionado uniformemente

### Descripción

function gmp_random_range(GMP|int|string `$min`, GMP|int|string `$max`): GMP

Genera un número aleatorio. El número estará en el intervalo `min` y `max`.

`min` y `max` pueden ser ambos negativos, pero `min` debe ser siempre inferior a `max`.

Precaución

Esta función no genera valores criptográficamente seguros, y no debe ser utilizada con fines criptográficos, o con fines que requieran que los valores devueltos sean indescifrables.

Si se requiere aleatoriedad criptográficamente segura, el Random\Randomizer puede ser utilizado con el motor Random\Engine\Secure. Para casos de uso simples, las funciones random_int() y random_bytes() proporcionan una API práctica y segura que es soportada por el CSPRNG del sistema operativo.

### Parámetros

`min`

  Un número GMP que representa el límite inferior para el número aleatorio.

`max`

  Un número GMP que representa el límite superior para el número aleatorio.

### Valores devueltos

Devuelve un objeto GMP que contiene un entero seleccionado uniformemente en el intervalo cerrado [`min`, `max`]. `min` y `max` son ambos valores de retorno posibles.

### Errores/Excepciones

Si `max` es inferior a `min`, se lanzará una ValueError.

### Ejemplos

Ejemplo #1 Ejemplo con gmp_random_range()

    <?php
    $rand1 = gmp_random_range(0, 100);    // número aleatorio entre 0 y 100
    $rand2 = gmp_random_range(-100, -10); // número aleatorio entre -100 y -10

    echo gmp_strval($rand1) . "\n";
    echo gmp_strval($rand2) . "\n";
    ?>

El ejemplo anterior mostrará:

    42
    -67

# gmp_random_seed

(PHP 7, PHP 8)

gmp_random_seed — Define la semilla RNG (Generador de Números Aleatorios)

### Descripción

function gmp_random_seed(GMP|int|string `$seed`): void

### Parámetros

`seed`

  La semilla a definir para las funciones gmp_random(), gmp_random_bits(), y gmp_random_range().

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

No se retorna ningún valor.

### Errores/Excepciones

Levanta una excepción ValueError si el argumento `seed` es inválido.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | Si el argumento `seed` es inválido, gmp_random_seed() levanta una excepción ValueError a partir de ahora. Anteriormente se emitía una advertencia `E_WARNING`.

### Ejemplos

Ejemplo #1 Ejemplo con gmp_random_seed()

    <?php
    // definir la semilla
    gmp_random_seed(100);

    var_dump(gmp_strval(gmp_random(1)));

    // definir la semilla a otro valor
    gmp_random_seed(gmp_init(-100));

    var_dump(gmp_strval(gmp_random_bits(10)));

    // definir una semilla con un valor inválido
    var_dump(gmp_random_seed('not a number'));

El ejemplo anterior mostrará:

    string(20) "15370156633245019617"
    string(3) "683"

    Warning: gmp_random_seed(): Unable to convert variable to GMP - string is not an integer in %s on line %d
    bool(false)

### Ver también

- gmp_init() - Crea un número GMP
- gmp_random() - Número GMP aleatorio
- gmp_random_bits() - Genera un número aleatorio
- gmp_random_range() - Obtener un entero seleccionado uniformemente

# gmp_root

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

gmp_root — Tomar la parte entera de una raíz enésima

### Descripción

function gmp_root(GMP|int|string `$num`, int `$nth`): GMP

Toma la raíz enésima dada por `nth` de `num` y devuelve el componente entero del resultado.

### Parámetros

`num`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`nth`

  La raíz positiva a tomar de `num`.

### Valores devueltos

El componente entero de la raíz resultante, como número GMP.

# gmp_rootrem

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

gmp_rootrem — Tomar la parte entera y el resto de una raíz enésima

### Descripción

function gmp_rootrem(GMP|int|string `$num`, int `$nth`): array

Toma la raíz enésima dada por `nth` de `num` y devuelve el componente entero y el resto del resultado.

### Parámetros

`num`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`nth`

  La raíz positiva a tomar de `num`.

### Valores devueltos

Un array de dos elementos, donde el primero es el componente entero de la raíz, y el segundo es el resto, ambos representados como números GMP.

# gmp_scan0

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_scan0 — Escanear para 0

### Descripción

function gmp_scan0(GMP|int|string `$num1`, int `$start`): int

Escanea `num1`, empezando con el bit de `start`, hacia los bits mas significantes, hasta que el primero bit borrado es encontrado.

### Parámetros

`num1`

  El número a escanear.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`start`

  El inicio del bit.

### Valores devueltos

Devuelve el índice del bit encontrado, como un int. El índice inicia desde 0.

### Ejemplos

Ejemplo #1 Ejemplo de gmp_scan0()

    <?php
    // "0" el bit se encuentra en la posición 3. El índice inicia en 0
    $s1 = gmp_init("10111", 2);
    echo gmp_scan0($s1, 0) . "\n";

    // "0" el bit se encuentra en la posición 7. El índice inicia en 5
    $s2 = gmp_init("101110000", 2);
    echo gmp_scan0($s2, 5) . "\n";
    ?>

El ejemplo anterior mostrará:

    3
    7

# gmp_scan1

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_scan1 — Escanear para 1

### Descripción

function gmp_scan1(GMP|int|string `$num1`, int `$start`): int

Escanea `num1`, empezando con el bit de `start`, hacia los bits mas significantes, hasta que el primero bit establecido es encontrado.

### Parámetros

`num1`

  El número a escanear.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`start`

  El inicio del bit.

### Valores devueltos

Devuelve el índice del bit encontrado, como un int. Si el bit establecido no es encontrado, -1 se devuelto.

### Ejemplos

Ejemplo #1 Ejemplo de gmp_scan1()

    <?php
    // "1" el bit se encuentra en la posición 3. El índice inica en 0
    $s1 = gmp_init("01000", 2);
    echo gmp_scan1($s1, 0) . "\n";

    // "1" el bit se encuentra en la posición 9. El índice inica en 5
    $s2 = gmp_init("01000001111", 2);
    echo gmp_scan1($s2, 5) . "\n";
    ?>

El ejemplo anterior mostrará:

    3
    9

# gmp_setbit

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_setbit — Modifica un bit

### Descripción

function gmp_setbit(GMP `$num`, int `$index`, bool `$value` = `true`): void

Modifica el bit `index` en `num`.

### Parámetros

`num`

  Un objeto GMP

`index`

  El índice del byte a definir. El índice 0 representa el byte menos significativo.

`value`

  `true` para definir el byte (definido a 1/on); `false` para reinicializarlo (definido a 0/off).

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con gmp_setbit() - índice 0

    <?php
    $a = gmp_init("2"); //
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    gmp_setbit($a, 0); // 0b10 ahora es 0b11
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    ?>

El ejemplo anterior mostrará:

    2 -> 0b10
    3 -> 0b11

Ejemplo #2 Ejemplo con gmp_setbit() - índice 1

    <?php
    $a = gmp_init("0xfd");
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    gmp_setbit($a, 1); // el índice comienza en 0
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    ?>

El ejemplo anterior mostrará:

    253 -> 0b11111101
    255 -> 0b11111111

Ejemplo #3 Ejemplo con gmp_setbit() - borra un byte

    <?php
    $a = gmp_init("0xff");
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    gmp_setbit($a, 0, false); // limpia el bit en el índice 0
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    ?>

El ejemplo anterior mostrará:

    255 -> 0b11111111
    254 -> 0b11111110

### Notas

> Nota:

> A diferencia de la mayoría de las otras funciones GMP, gmp_setbit() debe ser llamada con un objeto GMP ya existente (utilizando gmp_init() por ejemplo). No será creada automáticamente.

### Ver también

- gmp_clrbit() - Anula un byte
- gmp_testbit() - Prueba si un bit está definido

# gmp_sign

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sign — Signo del número GMP

### Descripción

function gmp_sign(GMP|int|string `$num`): int

Verifica el signo de un número.

### Parámetros

`num`

  Puede ser un objeto GMP o una cadena numérica, siempre que sea posible convertir esta última en un int.

### Valores devueltos

Devuelve el signo de `num`: 1 si `num` es positivo, -1 si es negativo y 0 si `num` es igual a cero.

### Ejemplos

Ejemplo #1 Ejemplo con gmp_sign()

    <?php
    // positivo
    echo gmp_sign("500") . "\n";

    // negativo
    echo gmp_sign("-500") . "\n";

    // cero
    echo gmp_sign("0") . "\n";
    ?>

El ejemplo anterior mostrará:

    1
    -1
    0

### Ver también

- gmp_abs() - Valor absoluto
- abs() - Valor absoluto

# gmp_sqrt

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sqrt — Calcula la raíz cuadrada

### Descripción

function gmp_sqrt(GMP|int|string `$num`): GMP

Calcula la raíz cuadrada de `num`.

### Parámetros

`num`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

La porción entera de la raíz cuadrada, como un número GMP.

### Ejemplos

Ejemplo #1 Ejemplo de gmp_sqrt()

    <?php
    $sqrt1 = gmp_sqrt("9");
    $sqrt2 = gmp_sqrt("7");
    $sqrt3 = gmp_sqrt("1524157875019052100");

    echo gmp_strval($sqrt1) . "\n";
    echo gmp_strval($sqrt2) . "\n";
    echo gmp_strval($sqrt3) . "\n";
    ?>

El ejemplo anterior mostrará:

    3
    2
    1234567890

# gmp_sqrtrem

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sqrtrem — Raíz cuadrada con resto

### Descripción

function gmp_sqrtrem(GMP|int|string `$num`): array

Calcula la raíz cuadrada de un número, con resto.

### Parámetros

`num`

  El número a ser la raíz cuadrada.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Devuelve un arreglo donde el primer elemento es el entero de la raíz cuadrada de `num` y el segundo es el resto (ej., La diferencia entre `num` y el primer elemento de la raíz cuadrada).

### Ejemplos

Ejemplo #1 Ejemplo degmp_sqrtrem()

    <?php
    list($sqrt1, $sqrt1rem) = gmp_sqrtrem("9");
    list($sqrt2, $sqrt2rem) = gmp_sqrtrem("7");
    list($sqrt3, $sqrt3rem) = gmp_sqrtrem("1048576");

    echo gmp_strval($sqrt1) . ", " . gmp_strval($sqrt1rem) . "\n";
    echo gmp_strval($sqrt2) . ", " . gmp_strval($sqrt2rem) . "\n";
    echo gmp_strval($sqrt3) . ", " . gmp_strval($sqrt3rem) . "\n";
    ?>

El ejemplo anterior mostrará:

    3, 0
    2, 3
    1024, 0

# gmp_strval

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_strval — Convierte un número GMP en string

### Descripción

function gmp_strval(GMP|int|string `$num`, int `$base` = 10): string

Convierte un número GMP en string, en la base `base`. La base por omisión es 10.

### Parámetros

`num`

  El número GMP que debe ser convertido.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`base`

  La base del número devuelto. Por omisión, vale 10. Los valores posibles van de 2 a 62 y de -2 a -36.

### Valores devueltos

El número, en forma de string.

### Ejemplos

Ejemplo #1 Convertir un número GMP en string

    <?php
    $a = gmp_init("0x41682179fbf5");
    printf("Decimal : %s, 36-based : %s", gmp_strval($a), gmp_strval($a,36));
    ?>

# gmp_sub

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sub — Resta los números

### Descripción

function gmp_sub(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Resta `num2` con `num1` y devuelve el resultado.

### Parámetros

`num1`

  El número a ser restado.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`num2`

  El número restado con `num1`.

  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Un objeto GMP.

### Ejemplos

Ejemplo #1 Ejemplo de gmp_sub()

    <?php
    $sub = gmp_sub("281474976710656", "4294967296"); // 2^48 - 2^32
    echo gmp_strval($sub) . "\n";
    ?>

El ejemplo anterior mostrará:

    281470681743360

# gmp_testbit

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gmp_testbit — Prueba si un bit está definido

### Descripción

function gmp_testbit(GMP|int|string `$num`, int `$index`): bool

Prueba si un bit está definido.

### Parámetros

`num`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`index`

  El bit a probar

### Valores devueltos

Devuelve `true` si el bit está definido en el recurso `num`, `false` en caso contrario.

### Errores/Excepciones

Se emite una advertencia de nivel `E_WARNING` cuando el argumento `index` es menor que `0` ; `false` será devuelto en este caso.

### Ejemplos

Ejemplo #1 Ejemplo con gmp_testbit()

    <?php
    $n = gmp_init("1000000");
    var_dump(gmp_testbit($n, 1));
    gmp_setbit($n, 1);
    var_dump(gmp_testbit($n, 1));
    ?>

El ejemplo anterior mostrará:

    bool(false)
    bool(true)

### Ver también

- gmp_setbit() - Modifica un bit
- gmp_clrbit() - Anula un byte

# gmp_xor

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_xor — Nivel de bit XOR

### Descripción

function gmp_xor(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Calcula el nivel de bit exclusivo OR (XOR) de dos números GMP.

### Parámetros

`num1`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).
`num2`
  Un objeto GMP, un int, o un string que puede ser interpretado como un número siguiendo la misma lógica que si la cadena fuera usada en gmp_init() con detección automática de la base (es decir cuando `base` es igual a 0).

### Valores devueltos

Un objeto GMP.

### Ejemplos

Ejemplo #1 Ejemplo degmp_xor()

    <?php
    $xor1 = gmp_init("1101101110011101", 2);
    $xor2 = gmp_init("0110011001011001", 2);

    $xor3 = gmp_xor($xor1, $xor2);

    echo gmp_strval($xor3, 2) . "\n";
    ?>

El ejemplo anterior mostrará:

    1011110111000100

## Tabla de contenidos

- gmp_abs — Valor absoluto
- gmp_add — Adición de 2 números GMP
- gmp_and — AND a nivel de bit
- gmp_binomial — Calcula el coeficiente binomial
- gmp_clrbit — Anula un byte
- gmp_cmp — Compara los números
- gmp_com — Calcula uno de los complementos
- gmp_div — Alias de gmp_div_q
- gmp_div_q — Divide los números
- gmp_div_qr — Divide los números y obtiene el cociente y resto
- gmp_div_r — El resto de la división de los números
- gmp_divexact — División exacta de números GMP
- gmp_export — Exportación hacia un string binario
- gmp_fact — Factorielle GMP
- gmp_gcd — Calcula el máximo común divisor
- gmp_gcdext — Calcula el máximo común divisor y multiplicadores
- gmp_hamdist — Distancia Hamming
- gmp_import — Importación desde una cadena binaria
- gmp_init — Crea un número GMP
- gmp_intval — Convertir un número GMP a entero
- gmp_invert — Inverso del modulo
- gmp_jacobi — Símbolo Jacobi
- gmp_kronecker — Símbolo Kronecker
- gmp_lcm — Calcula el Mínimo Común Múltiplo (MCM)
- gmp_legendre — Símbolo Legendre
- gmp_mod — Modulo de operación
- gmp_mul — Multiplicación de números
- gmp_neg — Número negativo
- gmp_nextprime — Encuentra el siguiente número primo
- gmp_or — Nivel de bit OR
- gmp_perfect_power — Verifica si un número es una potencia perfecta
- gmp_perfect_square — Comprueba el cuadrado perfecto
- gmp_popcount — Cuenta la población
- gmp_pow — Aumenta el número a la potencia
- gmp_powm — Eleva un número a la potencia con modulo
- gmp_prob_prime — Revisa si el número es "probablemente primo"
- gmp_random — Número GMP aleatorio
- gmp_random_bits — Genera un número aleatorio
- gmp_random_range — Obtener un entero seleccionado uniformemente
- gmp_random_seed — Define la semilla RNG (Generador de Números Aleatorios)
- gmp_root — Tomar la parte entera de una raíz enésima
- gmp_rootrem — Tomar la parte entera y el resto de una raíz enésima
- gmp_scan0 — Escanear para 0
- gmp_scan1 — Escanear para 1
- gmp_setbit — Modifica un bit
- gmp_sign — Signo del número GMP
- gmp_sqrt — Calcula la raíz cuadrada
- gmp_sqrtrem — Raíz cuadrada con resto
- gmp_strval — Convierte un número GMP en string
- gmp_sub — Resta los números
- gmp_testbit — Prueba si un bit está definido
- gmp_xor — Nivel de bit XOR

# La clase GMP

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

## Introducción

Un número GMP. Estos objetos admiten los operadores aritméticos, a nivel de bit y de comparación sobrecargados.

> Nota:

> No se proporciona ninguna interfaz orientada a objetos para manipular objetos GMP. Use la API de GMP procedimental.

## Sinopsis de la Clase

final class GMP {
/* Métodos */
public function __construct(int|string `$num` = 0, int `$base` = 0)
public function __serialize(): array
public function __unserialize(array `$data`): void
}

## Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | GMP ahora está marcado como final.

# GMP::__construct

(PHP 8 >= 8.2.4)

GMP::__construct — Crea un número GMP

### Descripción

public function GMP::__construct(int|string `$num` = 0, int `$base` = 0)

Crea un número GMP, a partir de un integer o de un string.

### Parámetros

`num`
  Un entero o un string. El string puede ser una representación decimal, hexadecimal, octal o binaria.
`base`
  La base a utilizar para convertir una representación en forma de string. Una base explícita puede estar comprendida entre `2` y `62`. Para las bases hasta `36`, la casilla es ignorada: las letras mayúsculas y minúsculas tienen el mismo valor. Para las bases de `37` a `62`, las letras mayúsculas representan los valores de `10` a `35` y las letras minúsculas representan los valores de `36` a `61`. Si `base` vale `0`, entonces la base real es determinada a partir de los caracteres iniciales de `num`. Si los dos primeros caracteres son `0x` o `0X`, el string es interpretado como un entero hexadecimal. Si los dos primeros caracteres son `0b` o `0B`, el string es interpretado como un entero binario. Si los dos primeros caracteres son `0o` o `0O`, el string es interpretado como un entero octal. Además, si el primer carácter es `0`, el string es igualmente interpretado como un entero octal. En todos los demás casos, el string es interpretado como un entero decimal.

### Ver también

- gmp_init() - Crea un número GMP

# GMP::__serialize

(PHP 8 >= 8.1.0)

GMP::__serialize — Serializa el objeto GMP

### Descripción

public function GMP::__serialize(): array

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

# GMP::__unserialize

(PHP 8 >= 8.1.0)

GMP::__unserialize — Deserializa el argumento `data` en un objeto GMP

### Descripción

public function GMP::__unserialize(array `$data`): void

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`data`

  El valor en curso de deserialización.

### Valores devueltos

No se retorna ningún valor.

## Tabla de contenidos

- GMP::__construct — Crea un número GMP
- GMP::__serialize — Serializa el objeto GMP
- GMP::__unserialize — Deserializa el argumento data en un objeto GMP

- Instalación/Configuración
  - Requerimientos
  - Instalación
- Constantes predefinidas
- Ejemplos
- Funciones de GMP
  - gmp_abs — Valor absoluto
  - gmp_add — Adición de 2 números GMP
  - gmp_and — AND a nivel de bit
  - gmp_binomial — Calcula el coeficiente binomial
  - gmp_clrbit — Anula un byte
  - gmp_cmp — Compara los números
  - gmp_com — Calcula uno de los complementos
  - gmp_div — Alias de gmp_div_q
  - gmp_div_q — Divide los números
  - gmp_div_qr — Divide los números y obtiene el cociente y resto
  - gmp_div_r — El resto de la división de los números
  - gmp_divexact — División exacta de números GMP
  - gmp_export — Exportación hacia un string binario
  - gmp_fact — Factorielle GMP
  - gmp_gcd — Calcula el máximo común divisor
  - gmp_gcdext — Calcula el máximo común divisor y multiplicadores
  - gmp_hamdist — Distancia Hamming
  - gmp_import — Importación desde una cadena binaria
  - gmp_init — Crea un número GMP
  - gmp_intval — Convertir un número GMP a entero
  - gmp_invert — Inverso del modulo
  - gmp_jacobi — Símbolo Jacobi
  - gmp_kronecker — Símbolo Kronecker
  - gmp_lcm — Calcula el Mínimo Común Múltiplo (MCM)
  - gmp_legendre — Símbolo Legendre
  - gmp_mod — Modulo de operación
  - gmp_mul — Multiplicación de números
  - gmp_neg — Número negativo
  - gmp_nextprime — Encuentra el siguiente número primo
  - gmp_or — Nivel de bit OR
  - gmp_perfect_power — Verifica si un número es una potencia perfecta
  - gmp_perfect_square — Comprueba el cuadrado perfecto
  - gmp_popcount — Cuenta la población
  - gmp_pow — Aumenta el número a la potencia
  - gmp_powm — Eleva un número a la potencia con modulo
  - gmp_prob_prime — Revisa si el número es "probablemente primo"
  - gmp_random — Número GMP aleatorio
  - gmp_random_bits — Genera un número aleatorio
  - gmp_random_range — Obtener un entero seleccionado uniformemente
  - gmp_random_seed — Define la semilla RNG (Generador de Números Aleatorios)
  - gmp_root — Tomar la parte entera de una raíz enésima
  - gmp_rootrem — Tomar la parte entera y el resto de una raíz enésima
  - gmp_scan0 — Escanear para 0
  - gmp_scan1 — Escanear para 1
  - gmp_setbit — Modifica un bit
  - gmp_sign — Signo del número GMP
  - gmp_sqrt — Calcula la raíz cuadrada
  - gmp_sqrtrem — Raíz cuadrada con resto
  - gmp_strval — Convierte un número GMP en string
  - gmp_sub — Resta los números
  - gmp_testbit — Prueba si un bit está definido
  - gmp_xor — Nivel de bit XOR
- GMP — La clase GMP
  - GMP::__construct — Crea un número GMP
  - GMP::__serialize — Serializa el objeto GMP
  - GMP::__unserialize — Deserializa el argumento data en un objeto GMP

# Funciones matemáticas

# Introducción

Estas funciones matemáticas son únicamente capaces de manipular valores que se encuentran dentro del rango de los tipos int y float. Para manipular números más grandes, véase las funciones precisión matemática arbitraria o funciones de precisión múltiple de GNU.

## Ver también

- operadores aritméticos
- Funciones de precisión matemática arbitraria
- Funciones de precisión múltiple de GNU

# Constantes predefinidas

Las constantes listadas aquí están siempre disponibles en PHP.

Constantes Matemáticas
`M_PI` (float)
  Aproximación del número π (pi). (`3.14159265358979323846`).
`M_E` (float)
  Aproximación del número de Euler `e` (`2.7182818284590452354`).
`M_LOG2E` (float)
  Aproximación de `log2(e)` (`1.4426950408889634074`).
`M_LOG10E` (float)
  Aproximación de `log10(e)` (`0.43429448190325182765`).
`M_LN2` (float)
  Aproximación de `ln(2)` (`0.69314718055994530942`).
`M_LN10` (float)
  Aproximación de `ln(10)` (`2.30258509299404568402`).
`M_PI_2` (float)
  Aproximación de `π/2` (`1.57079632679489661923`).
`M_PI_4` (float)
  Aproximación de `π/4` (`0.78539816339744830962`).
`M_1_PI` (float)
  Aproximación de `1/π` (`0.31830988618379067154`).
`M_2_PI` (float)
  Aproximación de `2/π` (`0.63661977236758134308`).
`M_SQRTPI` (float)
  Aproximación de `sqrt(π)` (`1.77245385090551602729`).
`M_2_SQRTPI` (float)
  Aproximación de `2/sqrt(π)` (`1.12837916709551257390`).
`M_SQRT2` (float)
  Aproximación de `sqrt(2)` (`1.41421356237309504880`).
`M_SQRT3` (float)
  Aproximación de `sqrt(3)` (`1.73205080756887729352`).
`M_SQRT1_2` (float)
  Aproximación de `1/sqrt(2)` (`0.70710678118654752440`).
`M_LNPI` (float)
  Aproximación de `ln(π)` (`1.14472988584940017414`).
`M_EULER` (float)
  Aproximación de la constante de Euler γ (`0.57721566490153286061`).

Constantes IEEE 754 de punto flotante
`NAN` (float)
  No es un número
`INF` (float)
  Infinitud

Constantes de redondeo

> Nota: A partir de PHP 8.4.0, se recomienda utilizar la enumeración RoundingMode en su lugar.

`PHP_ROUND_HALF_UP` (int)
  Redondear a la mitad hacia el infinito.
`PHP_ROUND_HALF_DOWN` (int)
  Redondear a la mitad hacia cero.
`PHP_ROUND_HALF_EVEN` (int)
  Redondear a la mitad al par.
`PHP_ROUND_HALF_ODD` (int)
  Redondear a la mitad al impar.

# La enumeración RoundingMode

(PHP 8 >= 8.4.0)

## Introducción

La enumeración RoundingMode se utiliza para especificar cómo debe realizarse el redondeo para round(), bcround() y BCMath\Number::round().

## Sinopsis del Enum

enum RoundingMode
{
case HalfAwayFromZero ; // Redondear al integer más cercano. Si la parte decimal es `5`, redondea al integer con el valor absoluto más grande.
case HalfTowardsZero ; // Redondear al integer más cercano. Si la parte decimal es `5`, redondea al integer con el valor absoluto más pequeño.
case HalfEven ; // Redondear al integer más cercano. Si la parte decimal es `5`, redondea al integer par.
case HalfOdd ; // Redondear al integer más cercano. Si la parte decimal es `5`, redondea al integer impar.
case TowardsZero ; // Redondear al integer más cercano con un valor absoluto más pequeño o igual.
case AwayFromZero ; // Redondear al integer más cercano con un valor absoluto más grande o igual.
case NegativeInfinity ; // Redondear al integer más grande más pequeño o igual.
case PositiveInfinity ; // Redondear al integer más pequeño más grande o igual.
}

# Funciones Matemáticas

# abs

(PHP 4, PHP 5, PHP 7, PHP 8)

abs — Valor absoluto

### Descripción

function abs(int|float `$num`): int|float

Devuelve el valor absoluto del número `num`.

### Parámetros

`num`

  El valor numérico a tratar

### Valores devueltos

El valor absoluto del número `num`. Si el número es un float, entonces el tipo de retorno es también float, de lo contrario es int (ya que float generalmente tiene un intervalo de valores más amplio que int).

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `num` ya no acepta objetos internos que soportan conversiones numéricas.

### Ejemplos

Ejemplo #1 Ejemplo con abs()

    <?php
    var_dump(abs(-4.2));
    var_dump(abs(5));
    var_dump(abs(-5));
    ?>

El ejemplo anterior mostrará:

    float(4.2)
    int(5)
    int(5)

### Ver también

- gmp_abs() - Valor absoluto
- gmp_sign() - Signo del número GMP

# acos

(PHP 4, PHP 5, PHP 7, PHP 8)

acos — Arc coseno

### Descripción

function acos(float `$num`): float

Devuelve el arc coseno de `num`. acos() es la función inversa de cos(), lo que significa que `$num == cos(acos($num))` para cada valor de `num` que se encuentra en el dominio de la función acos().

### Parámetros

`num`

  El argumento a tratar

### Valores devueltos

El arc coseno de `num`, en radianes.

### Ver también

- cos() - Coseno
- acosh() - Arco coseno hiperbólico
- asin() - Arco seno
- atan() - Arc tangente

# acosh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

acosh — Arco coseno hiperbólico

### Descripción

function acosh(float `$num`): float

Devuelve el arco coseno hiperbólico de `num`, es decir, el valor cuyo coseno hiperbólico es `num`.

### Parámetros

`num`

  El argumento a procesar

### Valores devueltos

El arco coseno hiperbólico de `num`

### Ver también

- cosh() - Coseno hiperbólico
- acos() - Arc coseno
- asinh() - Arco seno hiperbólico
- atanh() - Arco tangente hiperbólica

# asin

(PHP 4, PHP 5, PHP 7, PHP 8)

asin — Arco seno

### Descripción

function asin(float `$num`): float

Se devuelve el arco seno de `num` (`num` en radianes). asin() es la función inversa de sin(), lo que significa que `$num == sin(asin($num))` para cada valor de `num` que se encuentra en el dominio de la función asin().

### Parámetros

`num`

  El argumento a tratar

### Valores devueltos

El arco seno de `num`, en radianes.

### Ver también

- sin() - Seno
- asinh() - Arco seno hiperbólico
- acos() - Arc coseno
- atan() - Arc tangente

# asinh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

asinh — Arco seno hiperbólico

### Descripción

function asinh(float `$num`): float

Devuelve el arco seno hiperbólico de `num`, es decir, el valor cuyo seno hiperbólico es `num`.

### Parámetros

`num`

  El argumento a procesar

### Valores devueltos

El arco seno hiperbólico de `num`

### Ver también

- sinh() - Seno hiperbólico
- asin() - Arco seno
- acosh() - Arco coseno hiperbólico
- atanh() - Arco tangente hiperbólica

# atan

(PHP 4, PHP 5, PHP 7, PHP 8)

atan — Arc tangente

### Descripción

function atan(float `$num`): float

Se devuelve el arcotangente de `num`, en radianes. atan() es la función inversa de tan(), lo que significa que `$num == tan(atan($num))` para cada valor de `num` que se encuentra en el dominio de la función atan().

### Parámetros

`num`

  El argumento a tratar

### Valores devueltos

El arcotangente de `num`, en radianes.

### Ver también

- tan() - Tangente
- atanh() - Arco tangente hiperbólica
- asin() - Arco seno
- acos() - Arc coseno

# atan2

(PHP 4, PHP 5, PHP 7, PHP 8)

atan2 — Arco tangente de dos variables

### Descripción

function atan2(float `$y`, float `$x`): float

Esta función calcula el arco tangente de las dos variables `x` y `y`. Es similar a calcular el arco tangente de `y` / `x`, excepto que los signos de ambos argumentos son usados para determinar el cuadrante del resultado.

La función devuelve el resultado en radianes, que se encuentra entre -PI y PI (inclusive).

### Parámetros

`y`

  Parámetro dividendo

`x`

  Parámetro divisor

### Valores devueltos

El arco tangente de `y`/`x` en radianes.

### Ver también

- atan() - Arc tangente

# atanh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

atanh — Arco tangente hiperbólica

### Descripción

function atanh(float `$num`): float

Devuelve el arco tangente hiperbólico de `num`, es decir, el valor cuya tangente hiperbólica es `num`.

### Parámetros

`num`

  El argumento a procesar

### Valores devueltos

El arco tangente hiperbólico de `num`

### Ver también

- tanh() - Tangente hiperbólica
- atan() - Arc tangente
- asinh() - Arco seno hiperbólico
- acosh() - Arco coseno hiperbólico

# base_convert

(PHP 4, PHP 5, PHP 7, PHP 8)

base_convert — Convierte un número entre bases arbitrarias

### Descripción

function base_convert(string `$num`, int `$from_base`, int `$to_base`): string

Devuelve un string que contiene el argumento `num` representado en la base `to_base`. La base de representación de `number` es dada por `from_base`. `from_base` y `to_base` deben estar comprendidos entre 2 y 36 inclusive. Los dígitos superiores a 10 de las bases superiores a 10 serán representados por las letras de A a Z, con A = 10 y Z = 35. El caso de las letras no tiene importancia, es decir `num` es interpretado de forma insensible al caso.

Advertencia

base_convert() perderá la precisión sobre los grandes números, debido a las propiedades internas del tipo float utilizado. Leer la sección sobre los números decimales de este manual para más información.

### Parámetros

`num`

  El número a convertir. Cualquier carácter inválido en `num` es ignorado silenciosamente. A partir de PHP 7.4.0 proporcionar caracteres inválidos es obsoleto.

`from_base`

  La base `num` en la que está

`to_base`

  La base en la que se debe convertir el número `num`

### Valores devueltos

El número `num` convertido en la base `to_base`

### Historial de cambios

Versión | Descripción
--- | ---
7.4.0 | Pasar caracteres inválidos generará ahora una advertencia obsoleta. El resultado siempre será calculado como si los caracteres inválidos no existieran.

### Ejemplos

Ejemplo #1 Ejemplo con base_convert()

    <?php
    $hexadecimal = 'a37334';
    echo base_convert($hexadecimal, 16, 2);
    ?>

El ejemplo anterior mostrará:

    101000110111001100110100

### Ver también

- intval() - Devuelve el valor entero equivalente de una variable

# bindec

(PHP 4, PHP 5, PHP 7, PHP 8)

bindec — Convierte de binario a decimal

### Descripción

function bindec(string `$binary_string`): int|float

Devuelve la conversión de un número binario representado por la cadena `binary_string` a decimal.

bindec() convierte un número binario en un int, o, si es necesario por razones de tamaño, en un float.

bindec() interpreta todos los valores `binary_string` como enteros no firmados. Esto se debe a que la función bindec() ve el primer bit como otro orden de magnitud en lugar de como el bit de signo.

### Parámetros

`binary_string`

  La cadena binaria a convertir. Cualquier carácter inválido en `binary_string` es ignorado silenciosamente. A partir de PHP 7.4.0, proporcionar caracteres inválidos está deprecado.

Advertencia

Este parámetro debe ser un string. El uso de otro tipo de datos produce resultados inesperados.

### Valores devueltos

El valor decimal de `binary_string`

### Historial de cambios

Versión | Descripción
--- | ---
7.4.0 | Proporcionar caracteres inválidos generará ahora una advertencia deprecada. El resultado se calculará siempre como si los caracteres inválidos no existieran.

### Ejemplos

Ejemplo #1 Ejemplo con bindec()

    <?php
    echo bindec('110011') . "\n";
    echo bindec('000110011') . "\n";

    echo bindec('111');
    ?>

El ejemplo anterior mostrará:

    51
    51
    7

Ejemplo #2 bindec() interpreta la entrada como un entero no firmado

    <?php
    /*
     * Lo más importante en este ejemplo está en la salida
     * más que en el código PHP en sí.
     */

    $magnitude_lower = pow(2, (PHP_INT_SIZE * 8) - 2);
    p($magnitude_lower - 1);
    p($magnitude_lower, '¿Ha visto el cambio? Esté atento la próxima vez...');

    p(PHP_INT_MAX, 'PHP_INT_MAX');
    p(~PHP_INT_MAX, 'interpretado como superior a PHP_INT_MAX');

    if (PHP_INT_SIZE == 4) {
        $note = 'interpretado como el mayor entero no firmado';
    } else {
        $note = 'interpretado como el mayor entero no firmado
                  (18446744073709551615) pero distorsionado por la precisión de los flotantes';
    }
    p(-1, $note);

    function p($input, $note = '') {
        echo "entrada :        $input\n";

        $format = '%0' . (PHP_INT_SIZE * 8) . 'b';
        $bin = sprintf($format, $input);
        echo "binario :       $bin\n";

        ini_set('precision', 20);  // Para mayor legibilidad en PC de 64 bits.
        $dec = bindec($bin);
        echo 'bindec() :     ' . $dec . "\n";

        if ($note) {
            echo "Nota :         $note\n";
        }

        echo "\n";
    }
    ?>

Resultado del ejemplo anterior en una máquina de 32 bits:

    entrada :        1073741823
    binario :       00111111111111111111111111111111
    bindec() :     1073741823

    entrada :        1073741824
    binario :       01000000000000000000000000000000
    bindec():     1073741824
    Nota :         ¿Ha visto el cambio? Esté atento la próxima vez...

    entrada :        2147483647
    binario :       01111111111111111111111111111111
    bindec():     2147483647
    Nota :         PHP_INT_MAX

    entrada :        -2147483648
    binario :       10000000000000000000000000000000
    bindec():     2147483648
    Nota :         interpretado como superior a PHP_INT_MAX

    entrada :        -1
    binario :       11111111111111111111111111111111
    bindec():     4294967295
    Nota :         interpretado como el mayor entero no firmado

Resultado del ejemplo anterior en una máquina de 64 bits:

    entrada :        4611686018427387903
    binario :       0011111111111111111111111111111111111111111111111111111111111111
    bindec() :     4611686018427387903

    entrada :        4611686018427387904
    binario :       0100000000000000000000000000000000000000000000000000000000000000
    bindec() :     4611686018427387904
    Nota :         ¿Ha visto el cambio? Esté atento la próxima vez...

    entrada :        9223372036854775807
    binario :       0111111111111111111111111111111111111111111111111111111111111111
    bindec() :     9223372036854775807
    Nota :         PHP_INT_MAX

    entrada :        -9223372036854775808
    binario :       1000000000000000000000000000000000000000000000000000000000000000
    bindec() :     9223372036854775808
    Nota :         interpretado como superior a PHP_INT_MAX

    entrada :        -1
    binario :       1111111111111111111111111111111111111111111111111111111111111111
    bindec() :     18446744073709551616
    Nota :         interpretado como el mayor entero no firmado
                  (18446744073709551615) pero distorsionado por la precisión de los flotantes

### Notas

> Nota:

> La función puede convertir números que son demasiado grandes para caber en un tipo int, en cuyo caso estos valores se devuelven como float.

### Ver también

- decbin() - Convierte de decimal a binario
- octdec() - Conversión de octal a decimal
- hexdec() - Convierte de hexadecimal a decimal
- base_convert() - Convierte un número entre bases arbitrarias

# ceil

(PHP 4, PHP 5, PHP 7, PHP 8)

ceil — Redondea al número superior

### Descripción

function ceil(int|float `$num`): float

Devuelve el entero superior del número `num`.

### Parámetros

`num`

  El valor a redondear

### Valores devueltos

El valor `num` redondeado al entero superior. El valor devuelto es un número de punto flotante (float), ya que el intervalo de valores de un float es generalmente más amplio que el de un int.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `num` ya no acepta objetos internos que soportan las conversiones numéricas.

### Ejemplos

Ejemplo #1 Ejemplo con ceil()

    <?php
    echo ceil(4.3), PHP_EOL;    // 5
    echo ceil(9.999), PHP_EOL;  // 10
    echo ceil(-3.14), PHP_EOL;  // -3
    ?>

### Ver también

- floor() - Redondea hacia el entero inferior
- round() - Redondea un número de punto flotante

# cos

(PHP 4, PHP 5, PHP 7, PHP 8)

cos — Coseno

### Descripción

function cos(float `$num`): float

cos() devuelve el coseno de `num` (`num` en radianes).

### Parámetros

`num`

  El ángulo, en radianes

### Valores devueltos

El coseno de `num`.

### Ejemplos

Ejemplo #1 Ejemplo con cos()

    <?php

    echo cos(M_PI); // -1

    ?>

### Ver también

- acos() - Arc coseno
- sin() - Seno
- tan() - Tangente
- deg2rad() - Convierte un número de grados en radianes

# cosh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cosh — Coseno hiperbólico

### Descripción

function cosh(float `$num`): float

Se devuelve el coseno hiperbólico de `num`, definido como `(exp($num) + exp(-$num))/2`.

### Parámetros

`num`

  El argumento a tratar

### Valores devueltos

El coseno hiperbólico de `num`.

### Ver también

- cos() - Coseno
- acosh() - Arco coseno hiperbólico
- sinh() - Seno hiperbólico
- tanh() - Tangente hiperbólica

# decbin

(PHP 4, PHP 5, PHP 7, PHP 8)

decbin — Convierte de decimal a binario

### Descripción

function decbin(int `$num`): string

Devuelve un string que contiene la representación binaria del entero `num` proporcionado como argumento.

### Parámetros

`num`

  Valor decimal a convertir

  Intervalo de entrada en máquinas de 32-bit
  Parámetro `num` positivo | Parámetro `num` negativo | Valor devuelto
  --- | --- | ---
  0 |  | 0
  1 |  | 1
  2 |  | 10
  ... progresión normal ...
  2147483646 |  | 1111111111111111111111111111110
  2147483647 (mayor entero firmado) |  | 1111111111111111111111111111111 (31 unos)
  2147483648 | -2147483648 | 10000000000000000000000000000000
  ... progresión normal ...
  4294967294 | -2 | 11111111111111111111111111111110
  4294967295 (mayor entero no firmado) | -1 | 11111111111111111111111111111111 (32 unos)

  Intervalo de entrada en máquinas de 64-bit
  Parámetro `num` positivo | Parámetro `num` negativo | Valor devuelto
  --- | --- | ---
  0 |  | 0
  1 |  | 1
  2 |  | 10
  ... progresión normal ...
  9223372036854775806 |  | 111111111111111111111111111111111111111111111111111111111111110
  9223372036854775807 (mayor entero firmado) |  | 111111111111111111111111111111111111111111111111111111111111111 (63 unos)
  | -9223372036854775808 | 1000000000000000000000000000000000000000000000000000000000000000
  ... progresión normal ...
  | -2 | 1111111111111111111111111111111111111111111111111111111111111110
  | -1 | 1111111111111111111111111111111111111111111111111111111111111111 (64 unos)

### Valores devueltos

Una representación binaria de `num`.

### Ejemplos

Ejemplo #1 Ejemplo con decbin()

    <?php
    echo decbin(12) . "\n";
    echo decbin(26);
    ?>

El ejemplo anterior mostrará:

    1100
    11010

### Ver también

- bindec() - Convierte de binario a decimal
- decoct() - Convierte de decimal a octal
- dechex() - Convierte de decimal a hexadecimal
- base_convert() - Convierte un número entre bases arbitrarias
- printf() - Muestra una string formateada, utilizando `%b`, `%032b` o `%064b` como formato
- sprintf() - Devuelve una string formateada, utilizando `%b`, `%032b` o `%064b` como formato

# dechex

(PHP 4, PHP 5, PHP 7, PHP 8)

dechex — Convierte de decimal a hexadecimal

### Descripción

function dechex(int `$num`): string

Retorna un string que contiene la representación hexadecimal del argumento `num` sin signo.

El número más grande que puede ser convertido es `PHP_INT_MAX``* 2 + 1` (o `-1`) : en plataformas de 32-bit, será `4294967295` en decimal, lo que hará que la función dechex() retorne `ffffffff`.

### Parámetros

`num`

  El valor decimal a convertir.

  Dado que el tipo int de PHP es firmado, pero que la función dechex() solo funciona con enteros sin signo, los enteros negativos serán tratados como si fueran sin signo.

### Valores devueltos

Una representación hexadecimal de `num`.

### Ejemplos

Ejemplo #1 Ejemplo con dechex()

    <?php
    echo dechex(10) . "\n";
    echo dechex(47);
    ?>

El ejemplo anterior mostrará:

    a
    2f

Ejemplo #2 Ejemplo con la función dechex() con enteros grandes

    <?php
    // La salida a continuación asume que estamos en una plataforma de 32-bit.
    // Note que la salida es idéntica para todos los valores.
    echo dechex(-1)."\n";
    echo dechex(PHP_INT_MAX * 2 + 1)."\n";
    echo dechex(pow(2, 32) - 1)."\n";
    ?>

El ejemplo anterior mostrará:

    ffffffff
    ffffffff
    ffffffff

### Ver también

- hexdec() - Convierte de hexadecimal a decimal
- decbin() - Convierte de decimal a binario
- decoct() - Convierte de decimal a octal
- base_convert() - Convierte un número entre bases arbitrarias

# decoct

(PHP 4, PHP 5, PHP 7, PHP 8)

decoct — Convierte de decimal a octal

### Descripción

function decoct(int `$num`): string

Devuelve una cadena que contiene la representación octal del número dado `num`. El número más grande que puede ser convertido es `4294967295` en decimal, lo que dará `37777777777`. Para las plataformas de 64 bits, se trata generalmente de `9223372036854775807` en decimal resultando en `777777777777777777777`.

### Parámetros

`num`

  Valor decimal a convertir

### Valores devueltos

Una representación octal de `num`.

### Ejemplos

Ejemplo #1 Ejemplo con decoct()

    <?php
    echo decoct(15) . "\n";
    echo decoct(264);
    ?>

El ejemplo anterior mostrará:

    17
    410

### Ver también

- octdec() - Conversión de octal a decimal
- decbin() - Convierte de decimal a binario
- dechex() - Convierte de decimal a hexadecimal
- base_convert() - Convierte un número entre bases arbitrarias

# deg2rad

(PHP 4, PHP 5, PHP 7, PHP 8)

deg2rad — Convierte un número de grados en radianes

### Descripción

function deg2rad(float `$num`): float

deg2rad() convierte `num` de grados a radianes.

### Parámetros

`num`

  El ángulo, en grados

### Valores devueltos

El equivalente, en radianes, de `num`.

### Ejemplos

Ejemplo #1 Ejemplo con deg2rad()

    <?php

    echo deg2rad(45), PHP_EOL; // 0.785398163397
    var_dump(deg2rad(45) === M_PI_4); // bool(true)

    ?>

### Ver también

- rad2deg() - Conversión de radianes a grados

# exp

(PHP 4, PHP 5, PHP 7, PHP 8)

exp — Calcula la exponencial de `e`

### Descripción

function exp(float `$num`): float

Devuelve `e`, elevado a la potencia `num`.

> Nota:

> '`e`' es el logaritmo natural, o aproximadamente 2.718282.

### Parámetros

`num`

  El argumento a tratar

### Valores devueltos

'e', elevado a la potencia `num`.

### Ejemplos

Ejemplo #1 Ejemplo con exp()

    <?php
    echo exp(12), PHP_EOL;
    echo exp(5.7);
    ?>

El ejemplo anterior mostrará:

    162754.791419
    298.86740096706

### Ver también

- log() - Logaritmo natural (neperiano)
- pow() - Expresión exponencial

# expm1

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

expm1 — Devuelve `exp($num) - 1`, calculado de manera precisa incluso cuando el valor del número es cercano a cero

### Descripción

function expm1(float `$num`): float

expm1() devuelve el equivalente de `exp($`num`) - 1` calculado de tal manera que será preciso, incluso si el valor del argumento `num` es cercano a `0`, un caso donde la expresión `exp($`num`) - 1` no es precisa, debido a la sustracción de dos números casi iguales.

### Parámetros

`num`

  El argumento a tratar

### Valores devueltos

`e` elevado a la potencia `num`, menos uno.

### Ver también

- log1p() - Calcula con precisión log(1 + número)
- exp() - Calcula la exponencial de e

# fdiv

(PHP 8)

fdiv — Divide dos números, según la norma IEEE 754

### Descripción

function fdiv(float `$num1`, float `$num2`): float

Devuelve el resultado en coma flotante de la división de `num1` por `num2`. Si `num2` es cero, entonces uno de los valores `INF`, -`INF`, o `NAN` será devuelto.

Cabe señalar que en las comparaciones, `NAN` nunca será igual (`==`) o idéntico (`===`) a ningún valor, incluyendo a sí mismo.

### Parámetros

`num1`

  El dividendo (numerador)

`num2`

  El divisor

### Valores devueltos

El resultado en coma flotante de `num1`/`num2`

### Ejemplos

Ejemplo #1 Uso de fdiv()

    <?php
    var_dump(fdiv(5.7, 1.3)); // float(4.384615384615385)
    var_dump(fdiv(4, 2)); // float(2)
    var_dump(fdiv(1.0, 0.0)); // float(INF)
    var_dump(fdiv(-1.0, 0.0)); // float(-INF)
    var_dump(fdiv(0.0, 0.0)); // float(NAN)
    ?>

### Ver también

- Operador de división `/`
- fmod() - Devuelve el resto de la división
- fpow() - Eleva un número a la potencia de otro, según la norma IEEE 754

# floor

(PHP 4, PHP 5, PHP 7, PHP 8)

floor — Redondea hacia el entero inferior

### Descripción

function floor(int|float `$num`): float

Devuelve el valor entero siguiente más bajo (como float) al redondear el valor `num` si es necesario.

### Parámetros

`num`

  El valor numérico a redondear

### Valores devueltos

floor() devuelve el entero inferior del número `num`. El valor devuelto es un número de punto flotante (float).

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | `num` ya no acepta objetos internos que soportan conversiones numéricas.

### Ejemplos

Ejemplo #1 Ejemplo con floor()

    <?php
    echo floor(4.3), PHP_EOL;   // 4
    echo floor(9.999), PHP_EOL; // 9
    echo floor(-3.14), PHP_EOL; // -4
    ?>

### Ver también

- ceil() - Redondea al número superior
- round() - Redondea un número de punto flotante

# fmod

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

fmod — Devuelve el resto de la división

### Descripción

function fmod(float `$num1`, float `$num2`): float

Devuelve el resto de la división de `num1` por `num2`. Este resto es un número de punto flotante. El resto (r) se define por: num1 = i * num2 + r, para un entero i. Si `num2` no es nulo, r tiene el mismo signo que `num1` y un valor absoluto menor que `num2`.

### Parámetros

`num1`

  El dividendo

`num2`

  El divisor

### Valores devueltos

El resto de la división de `num1` por `num2`. `NAN` (float) si el segundo argumento es 0.

### Ejemplos

Ejemplo #1 Ejemplo con fmod()

    <?php
    $x = 5.7;
    $y = 1.3;
    $r = fmod($x, $y);
    // $r vale 0.5, porque 4 * 1.3 + 0.5 = 5.7

    var_dump($x, $y, $r);
    ?>

### Ver también

- `/` - División de punto flotante
- `%` - Módulo de enteros
- intdiv() - División de Enteros - División de enteros

# fpow

(PHP 8 >= 8.4.0)

fpow — Eleva un número a la potencia de otro, según la norma IEEE 754

### Descripción

function fpow(float `$num`, float `$exponent`): float

Devuelve el resultado en coma flotante de la elevación de `num` a la potencia `exponent`. Si `num` es cero y `exponent` es menor que cero, entonces `INF` es devuelto.

### Parámetros

`num`
  La base a utilizar.
`exponent`
  El exponente.

### Valores devueltos

Devuelve un float correspondiente a `$num$exponent`.

### Ejemplos

Ejemplo #1 Ejemplo de fpow()

    <?php
    var_dump(fpow(10, 2));
    var_dump(fpow(0, -3));
    var_dump(fpow(-1, 5.5));
    ?>

El ejemplo anterior mostrará:

    float(100)
    float(INF)
    float(NAN)

### Ver también

- El operador de exponenciación `**`
- pow() - Expresión exponencial
- fdiv() - Divide dos números, según la norma IEEE 754
- fmod() - Devuelve el resto de la división

# hexdec

(PHP 4, PHP 5, PHP 7, PHP 8)

hexdec — Convierte de hexadecimal a decimal

### Descripción

function hexdec(string `$hex_string`): int|float

Devuelve el valor decimal equivalente a la string hexadecimal representada por el argumento `hex_string`. hexdec() convierte una string hexadecimal en un número decimal.

hexdec() ignorará cualquier carácter no hexadecimal que encuentre. A partir de PHP 7.4.0, proporcionar caracteres inválidos está deprecado.

### Parámetros

`hex_string`

  La cadena hexadecimal a convertir

### Valores devueltos

La representación decimal de `hex_string`

### Historial de cambios

Versión | Descripción
--- | ---
7.4.0 | Pasar caracteres inválidos generará ahora una advertencia deprecada. El resultado siempre será calculado como si los caracteres inválidos no existieran.

### Ejemplos

Ejemplo #1 Ejemplo con hexdec()

    <?php

    var_dump(hexdec("ee")); // muestra "int(238)"
    var_dump(hexdec("a0")); // muestra "int(160)"
    ?>

Ejemplo #2 hexdec() con caracteres inválidos

    <?php
    var_dump(hexdec("See"));  // muestra "int(238)"
    var_dump(hexdec("that")); // muestra "int(10)"
    ?>

### Notas

> Nota:

> La función puede convertir números que son demasiado grandes para caber en un tipo int, en cuyo caso estos valores son devueltos como float.

### Ver también

- dechex() - Convierte de decimal a hexadecimal
- bindec() - Convierte de binario a decimal
- octdec() - Conversión de octal a decimal
- base_convert() - Convierte un número entre bases arbitrarias

# hypot

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

hypot — Calcula la longitud de la hipotenusa de un triángulo rectángulo

### Descripción

function hypot(float `$x`, float `$y`): float

hypot() devuelve la longitud de la hipotenusa de un triángulo rectángulo que tiene lados de longitud `x` y `y` o bien la distancia del punto (`x`, `y`) desde el origen. Esto es equivalente a `sqrt($x*$x + $y*$y)`.

### Parámetros

`x`

  Longitud del primer lado

`y`

  Longitud del segundo lado

### Valores devueltos

La longitud calculada de la hipotenusa

# intdiv

(PHP 7, PHP 8)

intdiv — División de Enteros

### Descripción

function intdiv(int `$num1`, int `$num2`): int

Devuelve el cociente entero de la división de `num1` por `num2`.

### Parámetros

`num1`

  Número a dividir.

`num2`

  Número que divide `num1`.

### Valores devueltos

El cociente entero de la división de `num1` por `num2`.

### Errores/Excepciones

Si `num2` es `0`, se emitirá una excepción DivisionByZeroError. Si `num1` es `PHP_INT_MIN` y `num2` es `-1`, en este caso se emite una excepción ArithmeticError.

### Ejemplos

Ejemplo #1 Ejemplo de intdiv()

    <?php
    var_dump(intdiv(3, 2));
    var_dump(intdiv(-3, 2));
    var_dump(intdiv(3, -2));
    var_dump(intdiv(-3, -2));
    var_dump(intdiv(PHP_INT_MAX, PHP_INT_MAX));
    var_dump(intdiv(PHP_INT_MIN, PHP_INT_MIN));
    ?>

El ejemplo anterior mostrará:

    int(1)
    int(-1)
    int(-1)
    int(1)
    int(1)
    int(1)

Ejemplo #2 Ejemplo de intdiv() con un divisor inválido

    <?php
    try {
        intdiv(PHP_INT_MIN, -1);
    } catch (Error $e) {
        echo get_class($e), ': ', $e->getMessage(), PHP_EOL;
    }

    try {
        intdiv(1, 0);
    } catch (Error $e) {
        echo get_class($e), ': ', $e->getMessage(), PHP_EOL;
    }
    ?>

El ejemplo anterior mostrará:

    ArithmeticError: Division of PHP_INT_MIN by -1 is not an integer
    DivisionByZeroError: Division by zero

### Ver también

- `/` - División de número flotante
- `%` - Módulo entero
- fmod() - Devuelve el resto de la división - Módulo de número flotante

# is_finite

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_finite — Verifica si un número flotante es finito

### Descripción

function is_finite(float `$num`): bool

Retorna si el `num` dado es un número flotante finito.

Un número flotante finito no es ni `NAN` (is_nan()), ni infinito (is_infinite()).

### Parámetros

`num`

  El float a verificar

### Valores devueltos

`true` si `num` no es ninguno de `NAN`, `INF`, -`INF`, de lo contrario `false`.

### Ejemplos

Ejemplo #1 Ejemplo de is_finite()

    <?php
    $float = 1.2345;
    var_dump($float, is_finite($float));

    $nan = sqrt(-1);
    var_dump($nan, is_finite($nan));

    $inf = 1e308 * 2;
    var_dump($inf, is_finite($inf));
    ?>

El ejemplo anterior mostrará:

    float(1.2345)
    bool(true)
    float(NAN)
    bool(false)
    float(INF)
    bool(false)

### Ver también

- is_infinite() - Verifica si un número de tipo float es infinito
- is_nan() - Verifica si un número flotante es NAN

# is_infinite

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_infinite — Verifica si un número de tipo float es infinito

### Descripción

function is_infinite(float `$num`): bool

Indica si el `num` proporcionado es `INF` o -`INF`.

### Parámetros

`num`

  El float a verificar

### Valores devueltos

Indica si el `num` proporcionado es `INF` o -`INF`, en caso contrario, `false`.

### Ejemplos

Ejemplo #1 Ejemplo de is_infinite()

    <?php
    $inf = 1e308 * 2;

    var_dump($inf, is_infinite($inf));

    $negative_inf = -$inf;

    var_dump($negative_inf, is_infinite($negative_inf));
    ?>

El ejemplo anterior mostrará:

    float(INF)
    bool(true)
    float(-INF)
    bool(true)

### Ver también

- is_finite() - Verifica si un número flotante es finito
- is_nan() - Verifica si un número flotante es NAN

# is_nan

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_nan — Verifica si un número flotante es NAN

### Descripción

function is_nan(float `$num`): bool

Devuelve si el `num` dado es `NAN` (Not A Number).

`NAN` es devuelto por las operaciones matemáticas que no están definidas, por ejemplo al pasar argumentos fuera del dominio de entrada de la función. La raíz cuadrada (sqrt()) solo está definida para números positivos, el paso de un número negativo resultará en un `NAN`. Otros ejemplos de operaciones que devuelven `NAN` son la división de `INF` por `INF` y cualquier operación que involucre un valor `NAN` existente.

> Nota:

> A pesar de su nombre Not A Number, `NAN` es un valor válido de tipo float.

Precaución

`NAN` no se compara igual a `NAN`. Para verificar si un número flotante es `NAN`, is_nan() debe ser utilizado. La verificación de `$float === NAN` no funcionará.

### Parámetros

`num`

  El float a verificar

### Valores devueltos

`true` si `num` es `NAN`, de lo contrario `false`.

### Ejemplos

Ejemplo #1 Ejemplo con is_nan()

    <?php
    $nan = sqrt(-1);

    var_dump($nan, is_nan($nan));
    ?>

El ejemplo anterior mostrará:

    float(NAN)
    bool(true)

### Ver también

- is_finite() - Verifica si un número flotante es finito
- is_infinite() - Verifica si un número de tipo float es infinito

# log

(PHP 4, PHP 5, PHP 7, PHP 8)

log — Logaritmo natural (neperiano)

### Descripción

function log(float `$num`, float `$base` = `M_E`): float

Si el argumento opcional `base` es especificado, log() devuelve entonces logbase `num`, de lo contrario log() devuelve el logaritmo natural (o neperiano) de `num`.

### Parámetros

`num`

  El valor para el cual se calcula el logaritmo

`base`

  La base logarítmica opcional a utilizar (por omisión, 'e' y por lo tanto, el logaritmo natural).

### Valores devueltos

El logaritmo de `num` en base `base`, si se proporciona, o el logaritmo natural.

### Ver también

- log10() - Logaritmo en base 10
- exp() - Calcula la exponencial de e
- pow() - Expresión exponencial
- error_log() - Envía un mensaje de error al gestor de errores definido

# log10

(PHP 4, PHP 5, PHP 7, PHP 8)

log10 — Logaritmo en base 10

### Descripción

function log10(float `$num`): float

Se devuelve el logaritmo en base 10 de `num`.

### Parámetros

`num`

  El argumento a tratar

### Valores devueltos

El logaritmo en base 10 de `num`.

### Ver también

- log() - Logaritmo natural (neperiano)

# log1p

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

log1p — Calcula con precisión log(1 + número)

### Descripción

function log1p(float `$num`): float

log1p() devuelve log(1 + `num`) calculado de tal manera que será preciso incluso si el valor de `num` está próximo a `0`. log() solo puede devolver log(1) en este caso por falta de precisión.

### Parámetros

`num`

  El argumento a tratar

### Valores devueltos

log(1 + `num`)

### Ver también

- expm1() - Devuelve exp($num) - 1, calculado de manera precisa incluso cuando el valor del número es cercano a cero
- log() - Logaritmo natural (neperiano)
- log10() - Logaritmo en base 10

# max

(PHP 4, PHP 5, PHP 7, PHP 8)

max — El valor más grande

### Descripción

function max(mixed `$value`, mixed `...$values`): mixed

Firma alternativa (no soportada con argumentos nombrados):

function max(array `$value_array`): mixed

Si el primer y único parámetro es un array, max() devuelve el valor más alto del array. Si se proporcionan al menos dos parámetros, max() devuelve el más grande de estos valores.

> Nota:

> Los valores de diferentes tipos serán comparados utilizando las reglas de comparación estándar. Actualmente, un string no numérico será comparado con un int como si fuera el valor `0`, pero varios string no numéricos serán comparados de forma alfanumérica. El valor actual devuelto será del mismo tipo que el original y no se aplicará ninguna conversión de tipo.

Precaución

Tenga cuidado al pasar argumentos con tipos diferentes, ya que max() puede producir resultados impredecibles.

### Parámetros

`value`

  Cualquier valor comparable.

`values`

  Cualquier valor comparable.

`value_array`

  Un array que contiene los valores.

### Valores devueltos

La función max() devuelve el valor del parámetro considerado como "superior" según la comparación estándar. Si varias valores de tipos diferentes son evaluados como iguales (i.e. `0` y `'abc'`), el primero proporcionado a la función será devuelto.

### Errores/Excepciones

Si se pasa un array vacío, la función max() lanza una ValueError.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | max() ahora lanza una ValueError en caso de fallo; previamente, `false` era devuelto y se emitía un error `E_WARNING`.
8.0.0 | Como las comparaciones entre strings y números han sido cambiadas, max() ya no devuelve un valor diferente basado en el orden de los argumentos en estos casos.

### Ejemplos

Ejemplo #1 Ejemplo con max()

    <?php
    echo max(2, 3, 1, 6, 7), PHP_EOL;  // 7
    echo max(array(2, 4, 5)), PHP_EOL; // 5

    // Aquí, comparamos -1 < 0, por lo que 'hello' es el valor más grande
    echo max('hello', -1), PHP_EOL;    // hello

    // Con varios arrays de diferentes tamaños, max devuelve
    // el más largo
    $val = max(array(2, 2, 2), array(1, 1, 1, 1)); // array(1, 1, 1, 1)
    var_dump($val);

    // Varios arrays de la misma longitud son comparados de izquierda a derecha
    // también, en nuestro ejemplo: 2 == 2, pero 5 > 4
    $val = max(array(2, 4, 8), array(2, 5, 1)); // array(2, 5, 1)
    var_dump($val);

    // Si se proporciona un array y un no-array, el array será siempre
    // devuelto, sabiendo que las comparaciones tratan los arrays como
    // más grandes que cualquier valor
    $val = max('string', array(2, 5, 7), 42);   // array(2, 5, 7)
    var_dump($val);

    // Si un argumento es NULL o un booleano, será comparado con otros
    // valores utilizando la regla FALSE < TRUE según los otros tipos concernidos
    // En el ejemplo de abajo, -10 es tratado como TRUE en la comparación
    $val = max(-10, FALSE); // -10
    var_dump($val);

    // Por otro lado, 0 es tratado como FALSE, por lo que es "más pequeño que" TRUE
    $val = max(0, TRUE); // TRUE
    var_dump($val);
    ?>

### Ver también

- min() - El valor más pequeño
- count() - Cuenta todos los elementos de un array o en un objeto Countable

# min

(PHP 4, PHP 5, PHP 7, PHP 8)

min — El valor más pequeño

### Descripción

function min(mixed `$value`, mixed `...$values`): mixed

Firma alternativa (no soportada con argumentos nombrados):

function min(array `$value_array`): mixed

Si el primer y único parámetro es un array, min() retornará el valor más pequeño contenido en el array. Si el primer parámetro es un entero, una cadena o un número decimal, deben proporcionarse al menos dos parámetros y min() retornará el más pequeño de estos valores.

> Nota:

> Los valores de diferentes tipos serán comparados utilizando las reglas de comparación estándar. Actualmente, una cadena no numérica será comparada con un int, como si fuera la valor `0`, pero varias string no numéricas serán comparadas de forma alfanumérica. El valor actual retornado será del mismo tipo que el original y ninguna conversión de tipo será aplicada.

Precaución

Tenga cuidado al pasar argumentos con tipos diferentes, ya que min() puede producir resultados impredecibles.

### Parámetros

`value`

  Cualquier valor comparable.

`values`

  Cualquier valor comparable.

`value_array`

  Un array que contiene los valores.

### Valores devueltos

La función min() retorna el valor del parámetro considerado como "inferior" según la comparación estándar. Si varios valores de tipos diferentes son evaluados como iguales (i.e. `0` y `'abc'`), el primero proporcionado a la función será retornado.

### Errores/Excepciones

Si se pasa un array vacío, la función min() lanza una ValueError.

### Historial de cambios

Versión | Descripción
--- | ---
8.0.0 | min() ahora lanza una ValueError en caso de fallo; previamente, `false` era retornado y un error `E_WARNING` era emitido.
8.0.0 | Como las comparaciones entre las cadenas y los números han sido cambiadas, min() ya no retorna un valor diferente basado en el orden de los argumentos en estos casos.

### Ejemplos

Ejemplo #1 Ejemplo con min()

    <?php
    echo min(2, 3, 1, 6, 7), PHP_EOL;  // 1
    echo min(array(2, 4, 5)), PHP_EOL; // 2

    // Aquí, comparamos -1 < 0, por lo tanto, -1 es el valor más bajo
    echo min('hello', -1), PHP_EOL;    // -1

    // Con varios arrays de diferentes tamaños, min retorna el más corto
    $val = min(array(2, 2, 2), array(1, 1, 1, 1)); // array(2, 2, 2)
    var_dump($val);

    // Varios arrays del mismo tamaño son comparados desde la izquierda hacia la derecha,
    // por lo tanto, en nuestro ejemplo: 2 == 2, pero 4 < 5
    $val = min(array(2, 4, 8), array(2, 5, 1)); // array(2, 4, 8)
    var_dump($val);

    // Si se proporciona un array y un no-array, el array nunca será retornado
    // ya que las comparaciones tratan los arrays como mayores que cualquier valor
    $val = min('string', array(2, 5, 7), 42);   // string
    var_dump($val);

    // Si un argumento es NULL o un booleano, será comparado con
    // otras valores utilizando la regla FALSE < TRUE según los otros
    // tipos proporcionados. En el ejemplo de abajo, tanto -10 como 10 son tratados
    // como valiendo TRUE en la comparación
    $val = min(-10, FALSE, 10); // FALSE
    var_dump($val);

    $val = min(-10, NULL, 10);  // NULL
    var_dump($val);

    // Por otro lado, 0 es tratado como valiendo FALSE, por lo tanto, es "más pequeño que" TRUE
    $val = min(0, TRUE); // 0
    var_dump($val);
    ?>

### Ver también

- max() - El valor más grande
- count() - Cuenta todos los elementos de un array o en un objeto Countable

# octdec

(PHP 4, PHP 5, PHP 7, PHP 8)

octdec — Conversión de octal a decimal

### Descripción

function octdec(string `$octal_string`): int|float

Devuelve un string que contiene la representación decimal del número `octal_string`.

### Parámetros

`octal_string`

  El string octal a convertir. Cualquier carácter inválido en `octal_string` es ignorado silenciosamente. A partir de PHP 7.4.0, proporcionar caracteres inválidos está deprecado. El número a convertir.

### Valores devueltos

La representación decimal de `octal_string`

### Historial de cambios

Versión | Descripción
--- | ---
7.4.0 | Proporcionar caracteres inválidos generará ahora una advertencia deprecada. El resultado siempre será calculado como si los caracteres inválidos no existieran.

### Ejemplos

Ejemplo #1 Ejemplo con octdec()

    <?php
    echo octdec('77') . "\n";
    echo octdec(decoct(45));
    ?>

El ejemplo anterior mostrará:

    63
    45

### Notas

> Nota:

> La función puede convertir números que son demasiado grandes para caber en un tipo int, en cuyo caso, estos valores son devueltos como float.

### Ver también

- decoct() - Convierte de decimal a octal
- bindec() - Convierte de binario a decimal
- hexdec() - Convierte de hexadecimal a decimal
- base_convert() - Convierte un número entre bases arbitrarias

# pi

(PHP 4, PHP 5, PHP 7, PHP 8)

pi — Devuelve el valor de pi

### Descripción

function pi(): float

Devuelve una aproximación de pi. Asimismo, puede utilizarse la constante `M_PI`, que devuelve un resultado idéntico a la función pi().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

El valor de pi como float.

### Ejemplos

Ejemplo #1 Ejemplo con pi()

    <?php
    echo pi(), PHP_EOL; // 3.1415926535898
    echo M_PI, PHP_EOL; // 3.1415926535898
    ?>

# pow

(PHP 4, PHP 5, PHP 7, PHP 8)

pow — Expresión exponencial

### Descripción

function pow(mixed `$num`, mixed `$exponent`): int|float|object

Devuelve `num` elevado a la potencia `exponent`.

> Nota:

> Es posible utilizar el operador ** en su lugar.

### Parámetros

`num`

  La base a utilizar

`exponent`

  El exponente

### Valores devueltos

`num` elevado a la potencia `exponent`. Si los argumentos no son enteros negativos, y el resultado puede ser representado como un entero, el resultado será int, de lo contrario será devuelto como float.

Las extensiones PHP pueden reemplazar el comportamiento de esta operación y hacer que devuelva un objeto.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Elevar `0` a un `exponente` negativo es ahora obsoleto.

### Ejemplos

Ejemplo #1 Ejemplo con pow()

    <?php

    var_dump(pow(2, 8)); // int(256)
    echo pow(-1, 20), PHP_EOL; // 1
    echo pow(0, 0), PHP_EOL; // 1
    echo pow(10, -1), PHP_EOL; // 0.1

    echo pow(-1, 5.5), PHP_EOL; // NAN
    ?>

Ejemplo #2 Ejemplos de pow() con un objeto de la extensión GMP

    <?php
    var_dump(pow(new GMP("3"), new GMP("2"))); // object(GMP)
    ?>

### Notas

> Nota:

> Esta función convertirá todas las entradas en un número, incluyendo valores no escalares, lo que puede llevar a resultados impredecibles.

### Ver también

- Operador de exponenciación `**`
- fpow() - Eleva un número a la potencia de otro, según la norma IEEE 754
- exp() - Calcula la exponencial de e
- sqrt() - Raíz cuadrada
- bcpow() - Elevar un número de precisión arbitraria a otro
- gmp_pow() - Aumenta el número a la potencia

# rad2deg

(PHP 4, PHP 5, PHP 7, PHP 8)

rad2deg — Conversión de radianes a grados

### Descripción

function rad2deg(float `$num`): float

Convierte `num` (supuesto en radianes) a grados.

### Parámetros

`num`

  Un valor, en radianes

### Valores devueltos

El equivalente de `num`, en grados.

### Ejemplos

Ejemplo #1 Ejemplo con rad2deg()

    <?php

    echo rad2deg(M_PI_4); // 45

    ?>

### Ver también

- deg2rad() - Convierte un número de grados en radianes

# round

(PHP 4, PHP 5, PHP 7, PHP 8)

round — Redondea un número de punto flotante

### Descripción

function round(int|float `$num`, int `$precision` = 0, int|RoundingMode `$mode` = `RoundingMode::HalfAwayFromZero`): float

Devuelve el valor redondeado de `num` a la precisión `precision` (número de dígitos después del punto decimal). El argumento `precision` puede ser negativo o `null` : es su valor por omisión.

### Parámetros

`num`

  El valor a redondear.

`precision`

  El número opcional de decimales a redondear.

  Si el argumento `precision` es positivo, `num` será redondeado utilizando el argumento `precision` para definir el número significativo de dígitos después del punto decimal.

  Si el argumento `precision` es negativo, `num` será redondeado utilizando el argumento `precision` para definir el número significativo de dígitos antes del punto decimal, i.e. el múltiplo más cercano de `pow(10, -$precision)`, i.e. para una `precision` de -1, `num` será redondeado a 10, para una `precision` de -2 a 100, etc.

`mode`

  Utilice RoundingMode o una de las constantes siguientes para especificar el método de redondeo.

  Constantes | Descripción
  --- | ---
  `PHP_ROUND_HALF_UP` | Redondea `num` alejándose de cero cuando está a mitad de camino, redondeando así 1.5 a 2, y -1.5 a -2.
  `PHP_ROUND_HALF_DOWN` | Redondea `num` acercándose a cero cuando está a mitad de camino, redondeando así 1.5 a 1, y -1.5 a -1.
  `PHP_ROUND_HALF_EVEN` | Redondea `num` al valor par más cercano cuando está a mitad de camino, redondeando así 1.5 y 2.5 a 2.
  `PHP_ROUND_HALF_ODD` | Redondea `num` al valor impar más cercano cuando está a mitad de camino, redondeando así 1.5 a 1 y 2.5 a 3.

  Sin embargo, tenga en cuenta que algunos métodos recién añadidos solo existen en RoundingMode.

### Valores devueltos

El valor redondeado a la `precision` dada como float.

### Errores/Excepciones

La función lanza una ValueError si `mode` es inválido. Anterior a PHP 8.4.0, un modo inválido era silenciosamente convertido en `PHP_ROUND_HALF_UP`.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Cuatro nuevos métodos de redondeo han sido añadidos.
8.4.0 | Ahora lanza una ValueError si `mode` es inválido.
8.0.0 | `num` ya no acepta objetos internos que soporten las conversiones numéricas.

### Ejemplos

Ejemplo #1 Ejemplo con round()

    <?php
    var_dump(round(3.4));
    var_dump(round(3.5));
    var_dump(round(3.6));
    var_dump(round(3.6, 0));
    var_dump(round(5.045, 2));
    var_dump(round(5.055, 2));
    var_dump(round(345, -2));
    var_dump(round(345, -3));
    var_dump(round(678, -2));
    var_dump(round(678, -3));
    ?>

El ejemplo anterior mostrará:

    float(3)
    float(4)
    float(4)
    float(4)
    float(5.05)
    float(5.06)
    float(300)
    float(0)
    float(700)
    float(1000)

Ejemplo #2 Cómo `precision` afecta un flotante

    <?php
    $number = 135.79;

    var_dump(round($number, 3));
    var_dump(round($number, 2));
    var_dump(round($number, 1));
    var_dump(round($number, 0));
    var_dump(round($number, -1));
    var_dump(round($number, -2));
    var_dump(round($number, -3));
    ?>

El ejemplo anterior mostrará:

    float(135.79)
    float(135.79)
    float(135.8)
    float(136)
    float(140)
    float(100)
    float(0)

Ejemplo #3 Ejemplo con `mode`

    <?php
    echo "Método de redondeo con 9.5" . PHP_EOL;
    var_dump(round(9.5, 0, PHP_ROUND_HALF_UP));
    var_dump(round(9.5, 0, PHP_ROUND_HALF_DOWN));
    var_dump(round(9.5, 0, PHP_ROUND_HALF_EVEN));
    var_dump(round(9.5, 0, PHP_ROUND_HALF_ODD));

    echo PHP_EOL;
    echo "Método de redondeo con 8.5" . PHP_EOL;
    var_dump(round(8.5, 0, PHP_ROUND_HALF_UP));
    var_dump(round(8.5, 0, PHP_ROUND_HALF_DOWN));
    var_dump(round(8.5, 0, PHP_ROUND_HALF_EVEN));
    var_dump(round(8.5, 0, PHP_ROUND_HALF_ODD));
    ?>

El ejemplo anterior mostrará:

    Método de redondeo con 9.5
    float(10)
    float(9)
    float(10)
    float(9)

    Método de redondeo con 8.5
    float(9)
    float(8)
    float(8)
    float(9)

Ejemplo #4 Ejemplo con `mode` y `precision`

    <?php
    echo "Uso de PHP_ROUND_HALF_UP con una precisión de una decimal" . PHP_EOL;
    var_dump(round( 1.55, 1, PHP_ROUND_HALF_UP));
    var_dump(round(-1.55, 1, PHP_ROUND_HALF_UP));

    echo PHP_EOL;
    echo "Uso de PHP_ROUND_HALF_DOWN con una precisión de una decimal" . PHP_EOL;
    var_dump(round( 1.55, 1, PHP_ROUND_HALF_DOWN));
    var_dump(round(-1.55, 1, PHP_ROUND_HALF_DOWN));

    echo PHP_EOL;
    echo "Uso de PHP_ROUND_HALF_EVEN con una precisión de una decimal" . PHP_EOL;
    var_dump(round( 1.55, 1, PHP_ROUND_HALF_EVEN));
    var_dump(round(-1.55, 1, PHP_ROUND_HALF_EVEN));

    echo PHP_EOL;
    echo "Uso de PHP_ROUND_HALF_ODD con una precisión de una decimal" . PHP_EOL;
    var_dump(round( 1.55, 1, PHP_ROUND_HALF_ODD));
    var_dump(round(-1.55, 1, PHP_ROUND_HALF_ODD));
    ?>

El ejemplo anterior mostrará:

    Uso de PHP_ROUND_HALF_UP con una precisión de una decimal
    float(1.6)
    float(-1.6)

    Uso de PHP_ROUND_HALF_DOWN con una precisión de una decimal
    float(1.5)
    float(-1.5)

    Uso de PHP_ROUND_HALF_EVEN con una precisión de una decimal
    float(1.6)
    float(-1.6)

    Uso de PHP_ROUND_HALF_ODD con una precisión de una decimal
    float(1.5)
    float(-1.5)

Ejemplo #5 Ejemplo de uso de RoundingMode

    <?php
    foreach (RoundingMode::cases() as $mode) {
        foreach ([
            8.5,
            9.5,
            -3.5,
        ] as $number) {
            printf("%-17s: %+.17g -> %+.17g\n", $mode->name, $number, round($number, 0, $mode));
        }
        echo "\n";
    }
    ?>

El ejemplo anterior mostrará:

    HalfAwayFromZero : +8.5 -> +9
    HalfAwayFromZero : +9.5 -> +10
    HalfAwayFromZero : -3.5 -> -4

    HalfTowardsZero  : +8.5 -> +8
    HalfTowardsZero  : +9.5 -> +9
    HalfTowardsZero  : -3.5 -> -3

    HalfEven         : +8.5 -> +8
    HalfEven         : +9.5 -> +10
    HalfEven         : -3.5 -> -4

    HalfOdd          : +8.5 -> +9
    HalfOdd          : +9.5 -> +9
    HalfOdd          : -3.5 -> -3

    TowardsZero      : +8.5 -> +8
    TowardsZero      : +9.5 -> +9
    TowardsZero      : -3.5 -> -3

    AwayFromZero     : +8.5 -> +9
    AwayFromZero     : +9.5 -> +10
    AwayFromZero     : -3.5 -> -4

    NegativeInfinity : +8.5 -> +8
    NegativeInfinity : +9.5 -> +9
    NegativeInfinity : -3.5 -> -4

    PositiveInfinity : +8.5 -> +9
    PositiveInfinity : +9.5 -> +10
    PositiveInfinity : -3.5 -> -3

### Ver también

- ceil() - Redondea al número superior
- floor() - Redondea hacia el entero inferior
- number_format() - Formatea un número para su visualización

# sin

(PHP 4, PHP 5, PHP 7, PHP 8)

sin — Seno

### Descripción

function sin(float `$num`): float

sin() devuelve el seno de `num` (`num` en radianes).

### Parámetros

`num`

  Un valor, en radianes

### Valores devueltos

El seno de `num`.

### Ejemplos

Ejemplo #1 Ejemplo con sin()

    <?php
    // La precisión depende de la directiva precision
    echo sin(deg2rad(60)), PHP_EOL;  //  0.866025403 ...
    echo sin(60), PHP_EOL;           // -0.304810621 ...
    ?>

### Ver también

- asin() - Arco seno
- sinh() - Seno hiperbólico
- cos() - Coseno
- tan() - Tangente
- deg2rad() - Convierte un número de grados en radianes

# sinh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

sinh — Seno hiperbólico

### Descripción

function sinh(float `$num`): float

Devuelve el seno hiperbólico de `num`, definido como `(exp($num) - exp(-$num))/2`.

### Parámetros

`num`

  El argumento a tratar

### Valores devueltos

El seno hiperbólico de `num`.

### Ver también

- sin() - Seno
- asinh() - Arco seno hiperbólico
- cosh() - Coseno hiperbólico
- tanh() - Tangente hiperbólica

# sqrt

(PHP 4, PHP 5, PHP 7, PHP 8)

sqrt — Raíz cuadrada

### Descripción

function sqrt(float `$num`): float

Devuelve la raíz cuadrada de `num`.

### Parámetros

`num`

  El argumento a tratar

### Valores devueltos

La raíz cuadrada de `num` o el valor especial `NAN` para los números negativos.

### Ejemplos

Ejemplo #1 Ejemplo con sqrt()

    <?php
    // La precisión depende de su directiva precision
    echo sqrt(9), PHP_EOL; // 3
    echo sqrt(10), PHP_EOL; // 3.16227766 ...
    ?>

### Ver también

- pow() - Expresión exponencial
- `M_SQRTPI` - `sqrt(pi)`
- `M_2_SQRTPI` - `2/sqrt(pi)`
- `M_SQRT2` - `sqrt(2)`
- `M_SQRT3` - `sqrt(3)`
- `M_SQRT1_2` - `1/sqrt(2)`

# tan

(PHP 4, PHP 5, PHP 7, PHP 8)

tan — Tangente

### Descripción

function tan(float `$num`): float

Devuelve la tangente de `num` (`num` en radianes).

### Parámetros

`num`

  El argumento a tratar, en radianes

### Valores devueltos

La tangente de `num`

### Ejemplos

Ejemplo #1 Ejemplo con tan()

    <?php

    echo tan(M_PI_4); // 1

    ?>

### Ver también

- atan() - Arc tangente
- atan2() - Arco tangente de dos variables
- sin() - Seno
- cos() - Coseno
- tanh() - Tangente hiperbólica
- deg2rad() - Convierte un número de grados en radianes

# tanh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

tanh — Tangente hiperbólica

### Descripción

function tanh(float `$num`): float

Se devuelve la tangente hiperbólica de `num`, definida como `sinh($num)/cosh($num)`.

### Parámetros

`num`

  El argumento a tratar

### Valores devueltos

La tangente hiperbólica de `num`.

### Ver también

- tan() - Tangente
- atanh() - Arco tangente hiperbólica
- sinh() - Seno hiperbólico
- cosh() - Coseno hiperbólico

## Tabla de contenidos

- abs — Valor absoluto
- acos — Arc coseno
- acosh — Arco coseno hiperbólico
- asin — Arco seno
- asinh — Arco seno hiperbólico
- atan — Arc tangente
- atan2 — Arco tangente de dos variables
- atanh — Arco tangente hiperbólica
- base_convert — Convierte un número entre bases arbitrarias
- bindec — Convierte de binario a decimal
- ceil — Redondea al número superior
- cos — Coseno
- cosh — Coseno hiperbólico
- decbin — Convierte de decimal a binario
- dechex — Convierte de decimal a hexadecimal
- decoct — Convierte de decimal a octal
- deg2rad — Convierte un número de grados en radianes
- exp — Calcula la exponencial de e
- expm1 — Devuelve exp($num) - 1, calculado de manera precisa incluso cuando el valor del número es cercano a cero
- fdiv — Divide dos números, según la norma IEEE 754
- floor — Redondea hacia el entero inferior
- fmod — Devuelve el resto de la división
- fpow — Eleva un número a la potencia de otro, según la norma IEEE 754
- hexdec — Convierte de hexadecimal a decimal
- hypot — Calcula la longitud de la hipotenusa de un triángulo rectángulo
- intdiv — División de Enteros
- is_finite — Verifica si un número flotante es finito
- is_infinite — Verifica si un número de tipo float es infinito
- is_nan — Verifica si un número flotante es NAN
- log — Logaritmo natural (neperiano)
- log10 — Logaritmo en base 10
- log1p — Calcula con precisión log(1 + número)
- max — El valor más grande
- min — El valor más pequeño
- octdec — Conversión de octal a decimal
- pi — Devuelve el valor de pi
- pow — Expresión exponencial
- rad2deg — Conversión de radianes a grados
- round — Redondea un número de punto flotante
- sin — Seno
- sinh — Seno hiperbólico
- sqrt — Raíz cuadrada
- tan — Tangente
- tanh — Tangente hiperbólica

- Constantes predefinidas
- RoundingMode — La enumeración RoundingMode
- Funciones Matemáticas
  - abs — Valor absoluto
  - acos — Arc coseno
  - acosh — Arco coseno hiperbólico
  - asin — Arco seno
  - asinh — Arco seno hiperbólico
  - atan — Arc tangente
  - atan2 — Arco tangente de dos variables
  - atanh — Arco tangente hiperbólica
  - base_convert — Convierte un número entre bases arbitrarias
  - bindec — Convierte de binario a decimal
  - ceil — Redondea al número superior
  - cos — Coseno
  - cosh — Coseno hiperbólico
  - decbin — Convierte de decimal a binario
  - dechex — Convierte de decimal a hexadecimal
  - decoct — Convierte de decimal a octal
  - deg2rad — Convierte un número de grados en radianes
  - exp — Calcula la exponencial de e
  - expm1 — Devuelve exp($num) - 1, calculado de manera precisa incluso cuando el valor del número es cercano a cero
  - fdiv — Divide dos números, según la norma IEEE 754
  - floor — Redondea hacia el entero inferior
  - fmod — Devuelve el resto de la división
  - fpow — Eleva un número a la potencia de otro, según la norma IEEE 754
  - hexdec — Convierte de hexadecimal a decimal
  - hypot — Calcula la longitud de la hipotenusa de un triángulo rectángulo
  - intdiv — División de Enteros
  - is_finite — Verifica si un número flotante es finito
  - is_infinite — Verifica si un número de tipo float es infinito
  - is_nan — Verifica si un número flotante es NAN
  - log — Logaritmo natural (neperiano)
  - log10 — Logaritmo en base 10
  - log1p — Calcula con precisión log(1 + número)
  - max — El valor más grande
  - min — El valor más pequeño
  - octdec — Conversión de octal a decimal
  - pi — Devuelve el valor de pi
  - pow — Expresión exponencial
  - rad2deg — Conversión de radianes a grados
  - round — Redondea un número de punto flotante
  - sin — Seno
  - sinh — Seno hiperbólico
  - sqrt — Raíz cuadrada
  - tan — Tangente
  - tanh — Tangente hiperbólica

# Estadísticas

# Introducción

Advertencia

Esta extensión es no mantenida.

Esta es la extensión estadística. Contiene algunas decenas de funciones útiles para los cálculos estadísticos. Es una envoltura alrededor de 2 bibliotecas científicas, a saber, DCDFLIB (Library of C routines for Cumulative Distributions Functions, Inverses, and Other parameters) por B. Brown & J. Lavato y RANDLIB por Barry Brown, James Lavato & Kathy Russell. Incluye las funciones CD y PD.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación

## Requerimientos

No se requiere ninguna biblioteca externa. La extensión se entrega con las bibliotecas utilizadas.

## Instalación

Esta extensión » PECL no está integrada en PHP.

Esta extensión es considerada no mantenida y muerta. Sin embargo, el código fuente sigue disponible desde el SVN de PECL aquí: » https://pecl.php.net/package/stats.

Los binarios Windows (los archivos DLL) para esta extensión PECL están disponibles en el sitio web PECL.

# Funciones estadísticas

# stats_absolute_deviation

(PECL stats >= 1.0.0)

stats_absolute_deviation — Devuelve la desviación absoluta de un array de valores

### Descripción

function stats_absolute_deviation(array `$a`): float

Devuelve la desviación absoluta de los valores en `a`.

### Parámetros

`a`

  El array de entrada

### Valores devueltos

Devuelve la desviación absoluta de los valores en `a`, o `false` si `a` está vacío o no es un array.

# stats_cdf_beta

(PECL stats >= 1.0.0)

stats_cdf_beta — Calcula un parámetro de la distribución beta en función de otros valores

### Descripción

function stats_cdf_beta(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Devuelve la función de distribución acumulativa, su inversa, o uno de los parámetros, de la distribución beta. El tipo del valor de retorno y los parámetros (`par1`, `par2`, y `par3`) son determinados por `which`.

La siguiente tabla lista el valor de retorno y los parámetros por `which`. CDF, x, alpha, y beta designan la función de distribución acumulativa, el valor de la variable aleatoria, y los parámetros de forma de la distribución beta, respectivamente.

Valor de retorno y parámetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | alpha | beta
2 | x | CDF | alpha | beta
3 | alpha | x | CDF | beta
4 | beta | x | CDF | alpha

### Parámetros

`par1`

  El primer parámetro

`par2`

  El segundo parámetro

`par3`

  El tercer parámetro

`which`

  El flag para determinar qué debe ser calculado

### Valores devueltos

Devuelve CDF, x, alpha, o beta, determinado por `which`.

# stats_cdf_binomial

(PECL stats >= 1.0.0)

stats_cdf_binomial — Calcula un argumento de la distribución binomial en función de los otros valores

### Descripción

function stats_cdf_binomial(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Devuelve la función de distribución acumulativa, su inversa, o uno de los argumentos, de la distribución binomial. El tipo del valor de retorno y los parámetros (`par1`, `par2`, y `par3`) son determinados por `which`.

La siguiente tabla lista el valor de retorno y los parámetros por `which`. CDF, x, n, y p designan la función de distribución acumulativa, el número de éxitos, el número de intentos, y la tasa de éxito para cada intento, respectivamente.

Valor de retorno y parámetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | n | p
2 | x | CDF | n | p
3 | n | x | CDF | p
4 | p | x | CDF | n

### Parámetros

`par1`

  El primer parámetro

`par2`

  El segundo parámetro

`par3`

  El tercer parámetro

`which`

  El flag para determinar qué debe ser calculado

### Valores devueltos

Devuelve CDF, x, n, o p, determinado por `which`.

# stats_cdf_cauchy

(PECL stats >= 1.0.0)

stats_cdf_cauchy — Calcula un parámetro de la distribución de Cauchy en función de otros valores

### Descripción

function stats_cdf_cauchy(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Devuelve la función de distribución acumulativa, su inversa, o uno de los parámetros, de la distribución de Cauchy. El tipo del valor de retorno y los parámetros (`par1`, `par2`, y `par3`) son determinados por `which`.

La tabla siguiente lista el valor de retorno y los parámetros por `which`. CDF, x, x0, y gamma designan la función de distribución acumulativa, el valor de la variable aleatoria, el parámetro de localización y el parámetro de escala de la distribución de Cauchy, respectivamente.

Valor de retorno y parámetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | x0 | gamma
2 | x | CDF | x0 | gamma
3 | x0 | x | CDF | gamma
4 | gamma | x | CDF | x0

### Parámetros

`par1`

  El primer parámetro

`par2`

  El segundo parámetro

`par3`

  El tercer parámetro

`which`

  El flag para determinar qué debe ser calculado

### Valores devueltos

Devuelve CDF, x, x0, o gamma, determinado por `which`.

# stats_cdf_chisquare

(PECL stats >= 1.0.0)

stats_cdf_chisquare — Calcula un parámetro de la distribución del chi-cuadrado en función de los otros valores

### Descripción

function stats_cdf_chisquare(float `$par1`, float `$par2`, int `$which`): float

Devuelve la función de distribución acumulativa, su inversa, o uno de los parámetros, de la distribución del chi-cuadrado. El tipo del valor de retorno y los parámetros (`par1` y `par2`) son determinados por `which`.

La tabla siguiente lista el valor de retorno y los parámetros por `which`. CDF, x, y k designan la función de distribución acumulativa, el valor de la variable aleatoria, y el grado de libertad de la distribución del chi-cuadrado, respectivamente.

Valor de retorno y parámetros
`which` | Valor de retorno | `par1` | `par2`
--- | --- | --- | ---
1 | CDF | x | k
2 | x | CDF | k
3 | k | x | CDF

### Parámetros

`par1`

  El primer parámetro

`par2`

  El segundo parámetro

`which`

  El flag para determinar qué debe ser calculado

### Valores devueltos

Devuelve CDF, x, o k, determinado por `which`.

# stats_cdf_exponential

(PECL stats >= 1.0.0)

stats_cdf_exponential — Calcula un parámetro de la distribución exponencial en función de otros valores

### Descripción

function stats_cdf_exponential(float `$par1`, float `$par2`, int `$which`): float

Devuelve la función de distribución acumulativa, su inversa, o uno de los parámetros, de la distribución exponencial. El tipo del valor de retorno y los parámetros (`par1` y `par2`) son determinados por `which`.

La siguiente tabla lista el valor de retorno y los parámetros por `which`. CDF, x, y lambda designan la función de distribución acumulativa, el valor de la variable aleatoria, y el parámetro de tasa de la distribución exponencial, respectivamente.

Valor de retorno y parámetros
`which` | Valor de retorno | `par1` | `par2`
--- | --- | --- | ---
1 | CDF | x | lambda
2 | x | CDF | lambda
3 | lambda | x | CDF

### Parámetros

`par1`

  El primer parámetro

`par2`

  El segundo parámetro

`which`

  El flag para determinar qué debe ser calculado

### Valores devueltos

Devuelve CDF, x, o lambda, determinado por `which`.

# stats_cdf_f

(PECL stats >= 1.0.0)

stats_cdf_f — Calcula un parámetro de la distribución F en función de otros valores

### Descripción

function stats_cdf_f(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Devuelve la función de distribución acumulativa, su inversa, o uno de los parámetros, de la distribución F. El tipo de la valor de retorno y los parámetros (`par1`, `par2`, y `par3`) son determinados por `which`.

La tabla siguiente lista el valor de retorno y los parámetros por `which`. CDF, x, d1, y d2 designan la función de distribución acumulativa, el valor de la variable aleatoria, y los grados de libertad de la distribución F, respectivamente.

Valor de retorno y parámetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | d1 | d2
2 | x | CDF | d1 | d2
3 | d1 | x | CDF | d2
4 | d2 | x | CDF | d1

### Parámetros

`par1`

  El primer parámetro

`par2`

  El segundo parámetro

`par3`

  El tercer parámetro

`which`

  El flag para determinar qué debe ser calculado

### Valores devueltos

Devuelve CDF, x, d1, o d2, determinado por `which`.

# stats_cdf_gamma

(PECL stats >= 1.0.0)

stats_cdf_gamma — Calcula un parámetro de la distribución gamma en función de los otros valores

### Descripción

function stats_cdf_gamma(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Devuelve la función de distribución acumulativa, su inversa, o uno de los parámetros, de la distribución gamma. El tipo del valor de retorno y los parámetros (`par1`, `par2`, y `par3`) son determinados por `which`.

La tabla siguiente lista el valor de retorno y los parámetros por `which`. CDF, x, k, y theta designan la función de distribución acumulativa, el valor de la variable aleatoria, y los parámetros de forma y escala de la distribución gamma, respectivamente.

Valor de retorno y parámetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | k | theta
2 | x | CDF | k | theta
3 | k | x | CDF | theta
4 | theta | x | CDF | k

### Parámetros

`par1`

  El primer parámetro

`par2`

  El segundo parámetro

`par3`

  El tercer parámetro

`which`

  El flag para determinar qué debe ser calculado

### Valores devueltos

Devuelve CDF, x, k, o theta, determinado por `which`.

# stats_cdf_laplace

(PECL stats >= 1.0.0)

stats_cdf_laplace — Calcula un parámetro de la distribución de Laplace en función de los otros valores

### Descripción

function stats_cdf_laplace(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Devuelve la función de distribución acumulativa, su inversa, o uno de los parámetros, de la distribución de Laplace. El tipo del valor de retorno y los parámetros (`par1`, `par2`, y `par3`) son determinados por `which`.

La tabla siguiente lista el valor de retorno y los parámetros por `which`. CDF, x, mu, y b designan la función de distribución acumulativa, el valor de la variable aleatoria, y los parámetros de localización y escala de la distribución de Laplace, respectivamente.

Valor de retorno y parámetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | mu | b
2 | x | CDF | mu | b
3 | mu | x | CDF | b
4 | b | x | CDF | mu

### Parámetros

`par1`

  El primer parámetro

`par2`

  El segundo parámetro

`par3`

  El tercer parámetro

`which`

  El flag para determinar qué debe ser calculado

### Valores devueltos

Devuelve CDF, x, mu, o b, determinado por `which`.

# stats_cdf_logistic

(PECL stats >= 1.0.0)

stats_cdf_logistic — Calcula un parámetro de la distribución logística en función de otros valores

### Descripción

function stats_cdf_logistic(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Devuelve la función de distribución acumulativa, su inversa, o uno de los parámetros, de la distribución logística. El tipo del valor de retorno y los parámetros (`par1`, `par2`, y `par3`) son determinados por `which`.

La siguiente tabla lista el valor de retorno y los parámetros por `which`. CDF, x, mu, y s designan la función de distribución acumulativa, el valor de la variable aleatoria, y los parámetros de localización y escala de la distribución logística, respectivamente.

Valor de retorno y parámetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | mu | s
2 | x | CDF | mu | s
3 | mu | x | CDF | s
4 | s | x | CDF | mu

### Parámetros

`par1`

  El primer parámetro

`par2`

  El segundo parámetro

`par3`

  El tercer parámetro

`which`

  El flag para determinar qué debe ser calculado

### Valores devueltos

Devuelve CDF, x, mu, o s, determinado por `which`.

# stats_cdf_negative_binomial

(PECL stats >= 1.0.0)

stats_cdf_negative_binomial — Calcula un parámetro de la distribución binomial negativa en función de los otros valores

### Descripción

function stats_cdf_negative_binomial(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Devuelve la función de distribución acumulativa, su inversa, o uno de los parámetros, de la distribución binomial negativa. El tipo del valor de retorno y los parámetros (`par1`, `par2`, y `par3`) son determinados por `which`.

La tabla siguiente lista el valor de retorno y los parámetros por `which`. CDF, x, r, y p designan la función de distribución acumulativa, el número de fallos, el número de éxitos, y la tasa de éxito para cada intento, respectivamente.

Valor de retorno y parámetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | r | p
2 | x | CDF | r | p
3 | r | x | CDF | p
4 | p | x | CDF | r

### Parámetros

`par1`

  El primer parámetro

`par2`

  El segundo parámetro

`par3`

  El tercer parámetro

`which`

  El flag para determinar qué debe ser calculado

### Valores devueltos

Devuelve CDF, x, r, o p, determinado por `which`.

# stats_cdf_noncentral_chisquare

(PECL stats >= 1.0.0)

stats_cdf_noncentral_chisquare — Calcula un argumento de la distribución del chi-cuadrado no central en función de otros valores

### Descripción

function stats_cdf_noncentral_chisquare(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Devuelve la función de distribución acumulativa, su inversa, o uno de los parámetros, de la distribución binomial. El tipo del valor de retorno y los parámetros (`par1`, `par2`, y `par3`) son determinados por `which`.

La tabla siguiente lista el valor de retorno y los parámetros por `which`. CDF, x, k, y lambda designan la función de distribución acumulativa, el valor de la variable aleatoria, el grado de libertad y el argumento de no centralidad de la distribución del chi-cuadrado no central, respectivamente.

Valor de retorno y parámetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | k | lambda
2 | x | CDF | k | lambda
3 | k | x | CDF | lambda
4 | lambda | x | CDF | k

### Parámetros

`par1`

  El primer parámetro

`par2`

  El segundo parámetro

`par3`

  El tercer parámetro

`which`

  El flag para determinar qué debe ser calculado

### Valores devueltos

Devuelve CDF, x, k, o lambda, determinado por `which`.

# stats_cdf_noncentral_f

(PECL stats >= 1.0.0)

stats_cdf_noncentral_f — Calcula un parámetro de la distribución F no central en función de los otros valores

### Descripción

function stats_cdf_noncentral_f(
float `$par1`,
float `$par2`,
float `$par3`,
float `$par4`,
int `$which`
): float

Devuelve la función de distribución acumulativa, su inversa, o uno de los parámetros, de la distribución F no central. El tipo de la valor de retorno y los parámetros (`par1`, `par2`, `par3`, y `par4`) son determinados por `which`.

La tabla siguiente lista el valor de retorno y los parámetros por `which`. CDF, x, nu1, nu2, y lambda designan la función de distribución acumulativa, el valor de la variable aleatoria, los grados de libertad y el parámetro de no centralidad de la distribución F no central, respectivamente.

Valor de retorno y parámetros
`which` | Valor de retorno | `par1` | `par2` | `par3` | `par4`
--- | --- | --- | --- | --- | ---
1 | CDF | x | nu1 | nu2 | lambda
2 | x | CDF | nu1 | nu2 | lambda
3 | nu1 | x | CDF | nu2 | lambda
4 | nu2 | x | CDF | nu1 | lambda
5 | lambda | x | CDF | nu1 | nu2

### Parámetros

`par1`

  El primer parámetro

`par2`

  El segundo parámetro

`par3`

  El tercer parámetro

`par4`

  El cuarto parámetro

`which`

  El flag para determinar qué debe ser calculado

### Valores devueltos

Devuelve CDF, x, nu1, nu2, o lambda, determinado por `which`.

# stats_cdf_noncentral_t

(PECL stats >= 1.0.0)

stats_cdf_noncentral_t — Calcula un parámetro de la distribución t no central en función de los otros valores

### Descripción

function stats_cdf_noncentral_t(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Devuelve la función de distribución acumulativa, su inversa, o uno de los parámetros, de la distribución t no central. El tipo del valor de retorno y los parámetros (`par1`, `par2`, y `par3`) son determinados por `which`.

La siguiente tabla lista el valor de retorno y los parámetros por `which`. CDF, x, nu, y mu designan la función de distribución acumulativa, el valor de la variable aleatoria, los grados de libertad y el parámetro de no centralidad de la distribución, respectivamente.

Valor de retorno y parámetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | nu | mu
2 | x | CDF | nu | mu
3 | nu | x | CDF | mu
4 | mu | x | CDF | nu

### Parámetros

`par1`

  El primer parámetro

`par2`

  El segundo parámetro

`par3`

  El tercer parámetro

`which`

  El flag para determinar qué debe ser calculado

### Valores devueltos

Devuelve CDF, x, nu, o mu, determinado por `which`.

# stats_cdf_normal

(PECL stats >= 1.0.0)

stats_cdf_normal — Calcule un parámetro de la distribución normal en función de los otros valores

### Descripción

function stats_cdf_normal(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Devuelve la función de distribución acumulativa, su inversa, o uno de los parámetros, de la distribución normal. El tipo del valor de retorno y los parámetros (`par1`, `par2`, y `par3`) son determinados por `which`.

La tabla siguiente lista el valor de retorno y los parámetros por `which`. CDF, x, mu, y sigma designan la función de distribución acumulativa, el valor de la variable aleatoria, la media y la desviación estándar de la distribución normal, respectivamente.

Valor de retorno y parámetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | mu | sigma
2 | x | CDF | mu | sigma
3 | mu | x | CDF | sigma
4 | sigma | x | CDF | mu

### Parámetros

`par1`

  El primer parámetro

`par2`

  El segundo parámetro

`par3`

  El tercer parámetro

`which`

  El flag para determinar qué debe ser calculado

### Valores devueltos

Devuelve CDF, x, mu, o sigma, determinado por `which`.

# stats_cdf_poisson

(PECL stats >= 1.0.0)

stats_cdf_poisson — Calcula un parámetro de la distribución de Poisson en función de los otros valores

### Descripción

function stats_cdf_poisson(float `$par1`, float `$par2`, int `$which`): float

Devuelve la función de distribución acumulativa, su inversa, o uno de los parámetros, de la distribución de Poisson. El tipo del valor de retorno y los parámetros (`par1` y `par2`) son determinados por `which`.

La tabla siguiente lista el valor de retorno y los parámetros por `which`. CDF, x, y lambda designan la función de distribución acumulativa, el valor de la variable aleatoria, y el parámetro de la distribución de Poisson, respectivamente.

Valor de retorno y parámetros
`which` | Valor de retorno | `par1` | `par2`
--- | --- | --- | ---
1 | CDF | x | lambda
2 | x | CDF | lambda
3 | lambda | x | CDF

### Parámetros

`par1`

  El primer parámetro

`par2`

  El segundo parámetro

`which`

  El flag para determinar qué debe ser calculado

### Valores devueltos

Devuelve CDF, x, o lambda, determinado por `which`.

# stats_cdf_t

(PECL stats >= 1.0.0)

stats_cdf_t — Calcula un parámetro de la distribución t en función de los otros valores

### Descripción

function stats_cdf_t(float `$par1`, float `$par2`, int `$which`): float

Devuelve la función de distribución acumulativa, su inversa, o uno de los parámetros, de la distribución t. El tipo del valor de retorno y los parámetros (`par1` y `par2`) son determinados por `which`.

La siguiente tabla lista el valor de retorno y los parámetros por `which`. CDF, x, y nu designan la función de distribución acumulativa, el valor de la variable aleatoria, y los grados de libertad de la distribución t, respectivamente.

Valor de retorno y parámetros
`which` | Valor de retorno | `par1` | `par2`
--- | --- | --- | ---
1 | CDF | x | nu
2 | x | CDF | nu
3 | nu | x | CDF

### Parámetros

`par1`

  El primer parámetro

`par2`

  El segundo parámetro

`which`

  El flag para determinar qué debe ser calculado

### Valores devueltos

Devuelve CDF, x, o nu, determinado por `which`.

# stats_cdf_uniform

(PECL stats >= 1.0.0)

stats_cdf_uniform — Calcula un parámetro de la distribución uniforme en función de otros valores

### Descripción

function stats_cdf_uniform(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Devuelve la función de distribución acumulativa, su inversa, o uno de los parámetros, de la distribución uniforme. El tipo del valor de retorno y los parámetros (`par1`, `par2`, y `par3`) son determinados por `which`.

La tabla siguiente lista el valor de retorno y los parámetros por `which`. CDF, x, a, y b designan la función de distribución acumulativa, el valor de la variable aleatoria, y los límites inferior y superior de la distribución uniforme, respectivamente.

Valor de retorno y parámetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | a | b
2 | x | CDF | a | b
3 | a | x | CDF | b
4 | b | x | CDF | a

### Parámetros

`par1`

  El primer parámetro

`par2`

  El segundo parámetro

`par3`

  El tercer parámetro

`which`

  El flag para determinar qué debe ser calculado

### Valores devueltos

Devuelve CDF, x, a, o b, determinado por `which`.

# stats_cdf_weibull

(PECL stats >= 1.0.0)

stats_cdf_weibull — Calcula un parámetro de la distribución de Weibull en función de otros valores

### Descripción

function stats_cdf_weibull(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Devuelve la función de distribución acumulativa, su inversa, o uno de los parámetros, de la distribución de Weibull. El tipo de la valor de retorno y los parámetros (`par1`, `par2`, y `par3`) son determinados por `which`.

La siguiente tabla lista el valor de retorno y los parámetros por `which`. CDF, x, k, y lambda designan la función de distribución acumulativa, el valor de la variable aleatoria, y los parámetros de forma y escala de la distribución de Weibull, respectivamente.

Valor de retorno y parámetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | k | lambda
2 | x | CDF | k | lambda
3 | k | x | CDF | lambda
4 | lambda | x | CDF | k

### Parámetros

`par1`

  El primer parámetro

`par2`

  El segundo parámetro

`par3`

  El tercer parámetro

`which`

  El flag para determinar qué debe ser calculado

### Valores devueltos

Devuelve CDF, x, k, o lambda, determinado por `which`.

# stats_covariance

(PECL stats >= 1.0.0)

stats_covariance — Calcula la covarianza de dos conjuntos de datos

### Descripción

function stats_covariance(array `$a`, array `$b`): float

Devuelve la covarianza de `a` y `b`.

### Parámetros

`a`

  El primer array

`b`

  El segundo array

### Valores devueltos

Devuelve la covarianza de `a` y `b`, o `false` en caso de fallo.

# stats_dens_beta

(PECL stats >= 1.0.0)

stats_dens_beta — La función de densidad de probabilidad de la distribución beta

### Descripción

function stats_dens_beta(float `$x`, float `$a`, float `$b`): float

Devuelve la densidad de probabilidad en `x`, donde la variable aleatoria sigue la distribución beta cuyos parámetros de forma son `a` y `b`.

### Parámetros

`x`

  El valor en el cual se calcula la densidad de probabilidad

`a`

  El parámetro de forma de la distribución

`b`

  El parámetro de forma de la distribución

### Valores devueltos

La densidad de probabilidad en `x` o `false` en caso de error.

# stats_dens_cauchy

(PECL stats >= 1.0.0)

stats_dens_cauchy — La función de densidad de probabilidad de la distribución de Cauchy

### Descripción

function stats_dens_cauchy(float `$x`, float `$ave`, float `$stdev`): float

Devuelve la densidad de probabilidad en `x`, donde la variable aleatoria sigue la distribución de Cauchy cuyos parámetros de ubicación y escala son `ave` y `stdev`.

### Parámetros

`x`

  El valor en el cual se calcula la densidad de probabilidad

`ave`

  El parámetro de ubicación de la distribución

`stdev`

  El parámetro de escala de la distribución

### Valores devueltos

La densidad de probabilidad en `x` o `false` en caso de error.

# stats_dens_chisquare

(PECL stats >= 1.0.0)

stats_dens_chisquare — La función de densidad de probabilidad de la distribución chi-cuadrado

### Descripción

function stats_dens_chisquare(float `$x`, float `$dfr`): float

Devuelve la densidad de probabilidad en `x`, donde la variable aleatoria sigue la distribución chi-cuadrado con grados de libertad `dfr`.

### Parámetros

`x`

  El valor en el cual se calcula la densidad de probabilidad

`dfr`

  Los grados de libertad de la distribución

### Valores devueltos

La densidad de probabilidad en `x` o `false` en caso de error.

# stats_dens_exponential

(PECL stats >= 1.0.0)

stats_dens_exponential — La función de densidad de probabilidad de la distribución exponencial

### Descripción

function stats_dens_exponential(float `$x`, float `$scale`): float

Devuelve la densidad de probabilidad en `x`, donde la variable aleatoria sigue la distribución exponencial cuya escala es `scale`.

### Parámetros

`x`

  El valor en el cual se calcula la densidad de probabilidad

`scale`

  La escala de la distribución

### Valores devueltos

La densidad de probabilidad en `x` o `false` en caso de error.

# stats_dens_f

(PECL stats >= 1.0.0)

stats_dens_f — La función de densidad de probabilidad de la distribución F

### Descripción

function stats_dens_f(float `$x`, float `$dfr1`, float `$dfr2`): float

Devuelve la densidad de probabilidad en `x`, donde la variable aleatoria sigue la distribución F cuyos grados de libertad son `dfr1` y `dfr2`.

### Parámetros

`x`

  El valor en el cual se calcula la densidad de probabilidad

`dfr1`

  El grado de libertad de la distribución

`dfr2`

  El grado de libertad de la distribución

### Valores devueltos

La densidad de probabilidad en `x` o `false` en caso de error.

# stats_dens_gamma

(PECL stats >= 1.0.0)

stats_dens_gamma — La función de densidad de probabilidad de la distribución gamma

### Descripción

function stats_dens_gamma(float `$x`, float `$shape`, float `$scale`): float

Devuelve la densidad de probabilidad en `x`, donde la variable aleatoria sigue la distribución gamma cuyo parámetro de forma es `shape` y el parámetro de escala es `scale`.

### Parámetros

`x`

  El valor en el cual se calcula la densidad de probabilidad

`shape`

  El parámetro de forma de la distribución

`scale`

  El parámetro de escala de la distribución

### Valores devueltos

La densidad de probabilidad en `x` o `false` en caso de error.

# stats_dens_laplace

(PECL stats >= 1.0.0)

stats_dens_laplace — La función de densidad de probabilidad de la distribución de Laplace

### Descripción

function stats_dens_laplace(float `$x`, float `$ave`, float `$stdev`): float

Devuelve la densidad de probabilidad en `x`, donde la variable aleatoria sigue la distribución de Laplace cuyo parámetro de localización es `ave` y el parámetro de escala es `stdev`.

### Parámetros

`x`

  El valor en el cual se calcula la densidad de probabilidad

`ave`

  El parámetro de localización de la distribución

`stdev`

  El parámetro de escala de la distribución

### Valores devueltos

La densidad de probabilidad en `x` o `false` en caso de fallo.

# stats_dens_logistic

(PECL stats >= 1.0.0)

stats_dens_logistic — La función de densidad de probabilidad de la distribución logística

### Descripción

function stats_dens_logistic(float `$x`, float `$ave`, float `$stdev`): float

Devuelve la densidad de probabilidad en `x`, donde la variable aleatoria sigue la distribución logística cuyo parámetro de localización es `ave` y el parámetro de escala es `stdev`.

### Parámetros

`x`

  El valor en el cual se calcula la densidad de probabilidad

`ave`

  El parámetro de localización de la distribución

`stdev`

  El parámetro de escala de la distribución

### Valores devueltos

La densidad de probabilidad en `x` o `false` en caso de error.

# stats_dens_normal

(PECL stats >= 1.0.0)

stats_dens_normal — La función de densidad de probabilidad de la distribución normal

### Descripción

function stats_dens_normal(float `$x`, float `$ave`, float `$stdev`): float

Devuelve la densidad de probabilidad en `x`, donde la variable aleatoria sigue la distribución normal con media `ave` y desviación estándar `stdev`.

### Parámetros

`x`

  El valor en el que se calcula la densidad de probabilidad

`ave`

  La media de la distribución

`stdev`

  La desviación estándar de la distribución

### Valores devueltos

La densidad de probabilidad en `x` o `false` en caso de error.

# stats_dens_pmf_binomial

(PECL stats >= 1.0.0)

stats_dens_pmf_binomial — La función de masa de probabilidad de la distribución binomial

### Descripción

function stats_dens_pmf_binomial(float `$x`, float `$n`, float `$pi`): float

Devuelve la masa de probabilidad en `x`, donde la variable aleatoria sigue la distribución binomial cuyo número de ensayos es `n` y la tasa de éxito es `pi`.

### Parámetros

`x`

  El valor en el cual se calcula la masa de probabilidad

`n`

  El número de ensayos de la distribución

`pi`

  La tasa de éxito de la distribución

### Valores devueltos

La masa de probabilidad en `x` o `false` en caso de fallo.

# stats_dens_pmf_hypergeometric

(PECL stats >= 1.0.0)

stats_dens_pmf_hypergeometric — La función de masa de probabilidad de la distribución hipergeométrica

### Descripción

function stats_dens_pmf_hypergeometric(
float `$n1`,
float `$n2`,
float `$N1`,
float `$N2`
): float

Devuelve la masa de probabilidad en `n1`, donde la variable aleatoria sigue la distribución hipergeométrica cuyo número de fallos es `n2`, el número de muestras de éxito es `N1`, y el número de muestras de fallos es `N2`.

### Parámetros

`n1`

  El número de éxitos, a partir del cual se calcula la masa de probabilidad

`n2`

  El número de fallos de la distribución

`N1`

  El número de muestras de éxito de la distribución

`N2`

  El número de muestras de fallos de la distribución

### Valores devueltos

La masa de probabilidad en `n1` o `false` en caso de error.

# stats_dens_pmf_negative_binomial

(PECL stats >= 1.0.0)

stats_dens_pmf_negative_binomial — La función de masa de probabilidad de la distribución binomial negativa

### Descripción

function stats_dens_pmf_negative_binomial(float `$x`, float `$n`, float `$pi`): float

Devuelve la masa de probabilidad en `x`, donde la variable aleatoria sigue la distribución binomial negativa cuyo número de éxitos es `n` y la tasa de éxito es `pi`.

### Parámetros

`x`

  El valor en el cual se calcula la masa de probabilidad

`n`

  El número de éxitos de la distribución

`pi`

  La tasa de éxito de la distribución

### Valores devueltos

La masa de probabilidad en `x` o `false` en caso de error.

# stats_dens_pmf_poisson

(PECL stats >= 1.0.0)

stats_dens_pmf_poisson — La función de masa de probabilidad de la distribución de Poisson

### Descripción

function stats_dens_pmf_poisson(float `$x`, float `$lb`): float

Devuelve la masa de probabilidad en `x`, donde la variable aleatoria sigue la distribución de Poisson cuyo parámetro es `lb`.

### Parámetros

`x`

  El valor en el cual se calcula la masa de probabilidad

`lb`

  El parámetro de la distribución de Poisson

### Valores devueltos

La masa de probabilidad en `x` o `false` en caso de error.

# stats_dens_t

(PECL stats >= 1.0.0)

stats_dens_t — La función de densidad de probabilidad de la distribución t

### Descripción

function stats_dens_t(float `$x`, float `$dfr`): float

Devuelve la densidad de probabilidad en `x`, donde la variable aleatoria sigue la distribución t cuyo grado de libertad es `dfr`.

### Parámetros

`x`

  El valor en el cual se calcula la densidad de probabilidad

`dfr`

  El grado de libertad de la distribución

### Valores devueltos

La densidad de probabilidad en `x` o `false` en caso de error.

# stats_dens_uniform

(PECL stats >= 1.0.0)

stats_dens_uniform — La función de densidad de probabilidad de la distribución uniforme

### Descripción

function stats_dens_uniform(float `$x`, float `$a`, float `$b`): float

Devuelve la densidad de probabilidad en `x`, donde la variable aleatoria sigue la distribución uniforme cuyo límite inferior es `a` y el límite superior es `b`.

### Parámetros

`x`

  El valor en el cual se calcula la densidad de probabilidad

`a`

  El límite inferior de la distribución

`b`

  El límite superior de la distribución

### Valores devueltos

La densidad de probabilidad en `x` o `false` en caso de error.

# stats_dens_weibull

(PECL stats >= 1.0.0)

stats_dens_weibull — La función de densidad de probabilidad de la distribución de Weibull

### Descripción

function stats_dens_weibull(float `$x`, float `$a`, float `$b`): float

Devuelve la densidad de probabilidad en `x`, donde la variable aleatoria sigue la distribución de Weibull cuyo parámetro de forma es `a` y el parámetro de escala es `b`.

### Parámetros

`x`

  El valor en el cual se calcula la densidad de probabilidad

`a`

  El parámetro de forma de la distribución

`b`

  El parámetro de escala de la distribución

### Valores devueltos

La densidad de probabilidad en `x` o `false` en caso de error.

# stats_harmonic_mean

(PECL stats >= 1.0.0)

stats_harmonic_mean — Devuelve la media armónica de un array de valores

### Descripción

function stats_harmonic_mean(array `$a`): number

Devuelve la media armónica de los valores de `a`.

### Parámetros

`a`

  El array de entrada

### Valores devueltos

Devuelve la media armónica de los valores de `a`, o `false` si `a` está vacío o no es un array.

# stats_kurtosis

(PECL stats >= 1.0.0)

stats_kurtosis — Calcula el kurtosis de los datos en el array

### Descripción

function stats_kurtosis(array `$a`): float

Devuelve el kurtosis de los valores en `a`.

### Parámetros

`a`

  El array de entrada

### Valores devueltos

Devuelve el kurtosis de los valores en `a`, o `false` si `a` está vacío o no es un array.

# stats_rand_gen_beta

(PECL stats >= 1.0.0)

stats_rand_gen_beta — Genera una desviación aleatoria de la distribución beta

### Descripción

function stats_rand_gen_beta(float `$a`, float `$b`): float

Devuelve una desviación aleatoria de la distribución beta con los parámetros A y B. La densidad de la beta es x^(a-1) * (1-x)^(b-1) / B(a, b) para 0 < x <. Método R. C. H. Cheng.

### Parámetros

`a`

  El parámetro de forma de la distribución beta

`b`

  El parámetro de forma de la distribución beta

### Valores devueltos

Una desviación aleatoria

# stats_rand_gen_chisquare

(PECL stats >= 1.0.0)

stats_rand_gen_chisquare — Genera una desviación aleatoria de la distribución chi-cuadrado

### Descripción

function stats_rand_gen_chisquare(float `$df`): float

Devuelve una desviación aleatoria de la distribución chi-cuadrado donde los grados de libertad son `df`.

### Parámetros

`df`

  Los grados de libertad

### Valores devueltos

Una desviación aleatoria

# stats_rand_gen_exponential

(PECL stats >= 1.0.0)

stats_rand_gen_exponential — Genera una desviación aleatoria de la distribución exponencial

### Descripción

function stats_rand_gen_exponential(float `$av`): float

Devuelve una desviación aleatoria de la distribución exponencial cuya escala es `av`.

### Parámetros

`av`

  El parámetro de escala

### Valores devueltos

Una desviación aleatoria

# stats_rand_gen_f

(PECL stats >= 1.0.0)

stats_rand_gen_f — Genera una desviación aleatoria de la distribución F

### Descripción

function stats_rand_gen_f(float `$dfn`, float `$dfd`): float

Genera una desviación aleatoria de la distribución F (ratio de varianza) con "dfn" grados de libertad en el numerador y "dfd" grados de libertad en el denominador. Método: genera directamente el ratio de variables chi-cuadrado.

### Parámetros

`dfn`

  El grado de libertad en el numerador

`dfd`

  El grado de libertad en el denominador

### Valores devueltos

Una desviación aleatoria

# stats_rand_gen_funiform

(PECL stats >= 1.0.0)

stats_rand_gen_funiform — Genera un flotante uniforme entre low (exclusivo) y high (exclusivo)

### Descripción

function stats_rand_gen_funiform(float `$low`, float `$high`): float

Devuelve una desviación aleatoria de la distribución uniforme entre `low` y `high`.

### Parámetros

`low`

  El umbral inferior (exclusivo)

`high`

  El umbral superior (exclusivo)

### Valores devueltos

Una desviación aleatoria

# stats_rand_gen_gamma

(PECL stats >= 1.0.0)

stats_rand_gen_gamma — Genera una desviación aleatoria de la distribución gamma

### Descripción

function stats_rand_gen_gamma(float `$a`, float `$r`): float

Genera una desviación aleatoria de la distribución gamma cuya densidad es (A**R)/Gamma(R) * X**(R-1) * Exp(-A*X).

### Parámetros

`a`

  El parámetro de localización de la distribución gamma (`a` > 0).

`r`

  El parámetro de forma de la distribución gamma (`r` > 0).

### Valores devueltos

Una desviación aleatoria

# stats_rand_gen_ibinomial

(PECL stats >= 1.0.0)

stats_rand_gen_ibinomial — Genera una desviación aleatoria de la distribución binomial

### Descripción

function stats_rand_gen_ibinomial(int `$n`, float `$pp`): int

Devuelve una desviación aleatoria de la distribución binomial donde el número de ensayos es `n` y la probabilidad de evento en cada ensayo es `pp`.

### Parámetros

`n`

  El número de ensayos

`pp`

  La probabilidad de un evento en cada ensayo

### Valores devueltos

Una desviación aleatoria

# stats_rand_gen_ibinomial_negative

(PECL stats >= 1.0.0)

stats_rand_gen_ibinomial_negative — Genera una desviación aleatoria de la distribución binomial negativa

### Descripción

function stats_rand_gen_ibinomial_negative(int `$n`, float `$p`): int

Devuelve una desviación aleatoria de la distribución binomial negativa donde el número de éxitos es `n` y la tasa de éxito es `p`.

### Parámetros

`n`

  El número de éxitos.

`p`

  La tasa de éxito.

### Valores devueltos

Una desviación aleatoria, que es el número de fracasos.

# stats_rand_gen_int

(PECL stats >= 1.0.0)

stats_rand_gen_int — Genera un integer aleatorio entre 1 y 2147483562

### Descripción

function stats_rand_gen_int(): int

Devuelve un integer aleatorio entre 1 y 2147483562

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un integer aleatorio

# stats_rand_gen_ipoisson

(PECL stats >= 1.0.0)

stats_rand_gen_ipoisson — Genera una sola desviación aleatoria de la distribución de Poisson

### Descripción

function stats_rand_gen_ipoisson(float `$mu`): int

Devuelve una desviación aleatoria de la distribución de Poisson con el argumento `mu`.

### Parámetros

`mu`

  El argumento de la distribución de Poisson

### Valores devueltos

Una desviación aleatoria

# stats_rand_gen_iuniform

(PECL stats >= 1.0.0)

stats_rand_gen_iuniform — Devuelve un integer aleatorio uniformemente distribuido entre LOW (incluido) y HIGH (incluido)

### Descripción

function stats_rand_gen_iuniform(int `$low`, int `$high`): int

Devuelve un integer aleatorio uniformemente distribuido entre `low` (incluido) y `high` (incluido).

### Parámetros

`low`

  El umbral inferior

`high`

  El umbral superior

### Valores devueltos

Un integer aleatorio

# stats_rand_gen_noncentral_chisquare

(PECL stats >= 1.0.0)

stats_rand_gen_noncentral_chisquare — Genera una desviación aleatoria de la distribución chi-cuadrado no central

### Descripción

function stats_rand_gen_noncentral_chisquare(float `$df`, float `$xnonc`): float

Devuelve una desviación aleatoria de la distribución chi-cuadrado no central con los grados de libertad, `df`, y el parámetro de no centralidad, `xnonc`.

### Parámetros

`df`

  Los grados de libertad

`xnonc`

  El parámetro de no centralidad

### Valores devueltos

Un valor aleatorio

# stats_rand_gen_noncentral_f

(PECL stats >= 1.0.0)

stats_rand_gen_noncentral_f — Genera una desviación aleatoria de la distribución F no central

### Descripción

function stats_rand_gen_noncentral_f(float `$dfn`, float `$dfd`, float `$xnonc`): float

Devuelve una desviación aleatoria de la distribución F no central con los grados de libertad, `dfn` (numerador) y `dfd` (denominador), y el parámetro de no centralidad, `xnonc`.

### Parámetros

`dfn`

  Los grados de libertad del numerador

`dfd`

  Los grados de libertad del denominador

`xnonc`

  El parámetro de no centralidad

### Valores devueltos

Una desviación aleatoria

# stats_rand_gen_noncentral_t

(PECL stats >= 1.0.0)

stats_rand_gen_noncentral_t — Genera una única desviación aleatoria de la distribución t no central

### Descripción

function stats_rand_gen_noncentral_t(float `$df`, float `$xnonc`): float

Devuelve una desviación aleatoria de la distribución t no central con los grados de libertad, `df`, y el parámetro de no centralidad, `xnonc`.

### Parámetros

`df`

  Los grados de libertad

`xnonc`

  El parámetro de no centralidad

### Valores devueltos

Una desviación aleatoria

# stats_rand_gen_normal

(PECL stats >= 1.0.0)

stats_rand_gen_normal — Genera una desviación aleatoria de la distribución normal

### Descripción

function stats_rand_gen_normal(float `$av`, float `$sd`): float

Devuelve una desviación aleatoria de la distribución normal con la media, `av`, y la desviación estándar, `sd`.

### Parámetros

`av`

  La media de la distribución normal

`sd`

  La desviación estándar de la distribución normal

### Valores devueltos

Una desviación aleatoria

# stats_rand_gen_t

(PECL stats >= 1.0.0)

stats_rand_gen_t — Genera una sola desviación aleatoria de la distribución t

### Descripción

function stats_rand_gen_t(float `$df`): float

Devuelve una desviación aleatoria de la distribución t con los grados de libertad, `df`.

### Parámetros

`df`

  Los grados de libertad

### Valores devueltos

Una desviación aleatoria

# stats_rand_get_seeds

(PECL stats >= 1.0.0)

stats_rand_get_seeds — Devuelve los valores de la semilla del generador de números aleatorios

### Descripción

function stats_rand_get_seeds(): array

Devuelve las semillas actuales del generador de números aleatorios

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un array de dos enteros.

# stats_rand_phrase_to_seeds

(PECL stats >= 1.0.0)

stats_rand_phrase_to_seeds — Genera dos semillas para el generador de números aleatorios RGN

### Descripción

function stats_rand_phrase_to_seeds(string `$phrase`): array

Genera dos semillas para el generador de números aleatorios a partir de una `phrase`.

### Parámetros

`phrase`

  La frase de entrada

### Valores devueltos

Devuelve un array de dos enteros.

# stats_rand_ranf

(PECL stats >= 1.0.0)

stats_rand_ranf — Genera un número flotante aleatorio entre 0 y 1

### Descripción

function stats_rand_ranf(): float

Devuelve un número flotante aleatorio de una distribución uniforme entre 0 (exclusivo) y 1 (exclusivo).

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Un número flotante aleatorio

# stats_rand_setall

(PECL stats >= 1.0.0)

stats_rand_setall — Define los valores de la semilla para el generador aleatorio

### Descripción

function stats_rand_setall(int `$iseed1`, int `$iseed2`): void

Define `iseed1` y `iseed2` como valores de la semilla para el generador aleatorio utilizado en las funciones estadísticas.

### Parámetros

`iseed1`

  El valor utilizado como semilla aleatoria

`iseed2`

  El valor utilizado como semilla aleatoria

### Valores devueltos

No se devuelve ningún valor.

# stats_skew

(PECL stats >= 1.0.0)

stats_skew — Calcula la asimetría de los datos en una tabla

### Descripción

function stats_skew(array `$a`): float

Devuelve la asimetría de los valores en `a`.

### Parámetros

`a`

  El array de entradas

### Valores devueltos

Devuelve la asimetría de los valores en `a`, o `false` si `a` está vacío o no es un array.

# stats_standard_deviation

(PECL stats >= 1.0.0)

stats_standard_deviation — Devuelve la desviación estándar

### Descripción

function stats_standard_deviation(array `$a`, bool `$sample` = `false`): float

Devuelve la desviación estándar de los valores en `a`.

### Parámetros

`a`

  El array de datos para el cual se calcula la desviación estándar. Es de notar que todos los valores del array serán convertidos en float.

`sample`

  Indica si `a` representa una muestra de la población; por omisión es `false`.

### Valores devueltos

Devuelve la desviación estándar en caso de éxito; `false` en caso de fallo.

### Errores/Excepciones

Lanza una `E_WARNING` cuando hay menos de 2 valores en `a`.

# stats_stat_binomial_coef

(PECL stats >= 1.0.0)

stats_stat_binomial_coef — Devuelve un coeficiente binomial

### Descripción

function stats_stat_binomial_coef(int `$x`, int `$n`): float

Devuelve el coeficiente binomial de `n` elegido `x`.

### Parámetros

`x`

  El número de elecciones en el conjunto

`n`

  El número de elementos en el conjunto

### Valores devueltos

Devuelve el coeficiente binomial

# stats_stat_correlation

(PECL stats >= 1.0.0)

stats_stat_correlation — Devuelve el coeficiente de correlación de Pearson de dos conjuntos de datos

### Descripción

function stats_stat_correlation(array `$arr1`, array `$arr2`): float

Devuelve el coeficiente de correlación de Pearson entre `arr1` y `arr2`.

### Parámetros

`arr1`

  El primer array

`arr2`

  El segundo array

### Valores devueltos

Devuelve el coeficiente de correlación de Pearson entre `arr1` y `arr2`, o `false` en caso de fallo.

# stats_stat_factorial

(PECL stats >= 1.0.0)

stats_stat_factorial — Devuelve el factorial de un entero

### Descripción

function stats_stat_factorial(int `$n`): float

Devuelve el factorial de un entero, `n`.

### Parámetros

`n`

  Un entero

### Valores devueltos

El factorial de `n`.

# stats_stat_independent_t

(PECL stats >= 1.0.0)

stats_stat_independent_t — Devuelve el valor t de la prueba t para dos muestras independientes

### Descripción

function stats_stat_independent_t(array `$arr1`, array `$arr2`): float

Devuelve el valor t de la prueba t para dos muestras independientes entre `arr1` y `arr2`.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`arr1`

  El primer conjunto de valores

`arr2`

  El segundo conjunto de valores

### Valores devueltos

Devuelve el valor t, o `false` en caso de fallo.

# stats_stat_innerproduct

(PECL stats >= 1.0.0)

stats_stat_innerproduct — Devuelve el producto interno de dos vectores

### Descripción

function stats_stat_innerproduct(array `$arr1`, array `$arr2`): float

Devuelve el producto interno de `arr1` y `arr2`.

### Parámetros

`arr1`

  El primer array

`arr2`

  El segundo array

### Valores devueltos

Devuelve el producto interno de `arr1` y `arr2`, o `false` en caso de error.

# stats_stat_paired_t

(PECL stats >= 1.0.0)

stats_stat_paired_t — Devuelve el valor t de la prueba t dependiente de dos muestras emparejadas

### Descripción

function stats_stat_paired_t(array `$arr1`, array `$arr2`): float

Devuelve el valor t de la prueba t dependiente de dos muestras emparejadas para las muestras `arr1` y `arr2`.

### Parámetros

`arr1`

  La primera muestra

`arr2`

  La segunda muestra

### Valores devueltos

Devuelve el valor t, o `false` en caso de fallo.

# stats_stat_percentile

(PECL stats >= 1.0.0)

stats_stat_percentile — Devuelve el valor del percentil

### Descripción

function stats_stat_percentile(array `$arr`, float `$perc`): float

Devuelve el valor del `perc`-ésimo percentil del conjunto de datos `arr`.

### Parámetros

`arr`

  El array de entrada

`perc`

  El percentil

### Valores devueltos

Devuelve el percentil del conjunto de datos.

# stats_stat_powersum

(PECL stats >= 1.0.0)

stats_stat_powersum — Devuelve la suma de las potencias de un vector

### Descripción

function stats_stat_powersum(array `$arr`, float `$power`): float

Devuelve la suma de la `power`-ésima potencia de un vector representado como un array `arr`.

### Parámetros

`arr`

  El array de entrada

`power`

  La potencia

### Valores devueltos

Devuelve la suma de las potencias del conjunto de datos.

# stats_variance

(PECL stats >= 1.0.0)

stats_variance — Devuelve la varianza

### Descripción

function stats_variance(array `$a`, bool `$sample` = `false`): float

Devuelve la varianza de los valores en `a`.

### Parámetros

`a`

  El array de datos para el cual se calcula la varianza. Se debe tener en cuenta que todos los valores del array serán convertidos en float.

`sample`

  Indica si `a` representa una muestra de la población; por omisión es `false`.

### Valores devueltos

Devuelve la varianza en caso de éxito; `false` en caso de fallo.

## Tabla de contenidos

- stats_absolute_deviation — Devuelve la desviación absoluta de un array de valores
- stats_cdf_beta — Calcula un parámetro de la distribución beta en función de otros valores
- stats_cdf_binomial — Calcula un argumento de la distribución binomial en función de los otros valores
- stats_cdf_cauchy — Calcula un parámetro de la distribución de Cauchy en función de otros valores
- stats_cdf_chisquare — Calcula un parámetro de la distribución del chi-cuadrado en función de los otros valores
- stats_cdf_exponential — Calcula un parámetro de la distribución exponencial en función de otros valores
- stats_cdf_f — Calcula un parámetro de la distribución F en función de otros valores
- stats_cdf_gamma — Calcula un parámetro de la distribución gamma en función de los otros valores
- stats_cdf_laplace — Calcula un parámetro de la distribución de Laplace en función de los otros valores
- stats_cdf_logistic — Calcula un parámetro de la distribución logística en función de otros valores
- stats_cdf_negative_binomial — Calcula un parámetro de la distribución binomial negativa en función de los otros valores
- stats_cdf_noncentral_chisquare — Calcula un argumento de la distribución del chi-cuadrado no central en función de otros valores
- stats_cdf_noncentral_f — Calcula un parámetro de la distribución F no central en función de los otros valores
- stats_cdf_noncentral_t — Calcula un parámetro de la distribución t no central en función de los otros valores
- stats_cdf_normal — Calcule un parámetro de la distribución normal en función de los otros valores
- stats_cdf_poisson — Calcula un parámetro de la distribución de Poisson en función de los otros valores
- stats_cdf_t — Calcula un parámetro de la distribución t en función de los otros valores
- stats_cdf_uniform — Calcula un parámetro de la distribución uniforme en función de otros valores
- stats_cdf_weibull — Calcula un parámetro de la distribución de Weibull en función de otros valores
- stats_covariance — Calcula la covarianza de dos conjuntos de datos
- stats_dens_beta — La función de densidad de probabilidad de la distribución beta
- stats_dens_cauchy — La función de densidad de probabilidad de la distribución de Cauchy
- stats_dens_chisquare — La función de densidad de probabilidad de la distribución chi-cuadrado
- stats_dens_exponential — La función de densidad de probabilidad de la distribución exponencial
- stats_dens_f — La función de densidad de probabilidad de la distribución F
- stats_dens_gamma — La función de densidad de probabilidad de la distribución gamma
- stats_dens_laplace — La función de densidad de probabilidad de la distribución de Laplace
- stats_dens_logistic — La función de densidad de probabilidad de la distribución logística
- stats_dens_normal — La función de densidad de probabilidad de la distribución normal
- stats_dens_pmf_binomial — La función de masa de probabilidad de la distribución binomial
- stats_dens_pmf_hypergeometric — La función de masa de probabilidad de la distribución hipergeométrica
- stats_dens_pmf_negative_binomial — La función de masa de probabilidad de la distribución binomial negativa
- stats_dens_pmf_poisson — La función de masa de probabilidad de la distribución de Poisson
- stats_dens_t — La función de densidad de probabilidad de la distribución t
- stats_dens_uniform — La función de densidad de probabilidad de la distribución uniforme
- stats_dens_weibull — La función de densidad de probabilidad de la distribución de Weibull
- stats_harmonic_mean — Devuelve la media armónica de un array de valores
- stats_kurtosis — Calcula el kurtosis de los datos en el array
- stats_rand_gen_beta — Genera una desviación aleatoria de la distribución beta
- stats_rand_gen_chisquare — Genera una desviación aleatoria de la distribución chi-cuadrado
- stats_rand_gen_exponential — Genera una desviación aleatoria de la distribución exponencial
- stats_rand_gen_f — Genera una desviación aleatoria de la distribución F
- stats_rand_gen_funiform — Genera un flotante uniforme entre low (exclusivo) y high (exclusivo)
- stats_rand_gen_gamma — Genera una desviación aleatoria de la distribución gamma
- stats_rand_gen_ibinomial — Genera una desviación aleatoria de la distribución binomial
- stats_rand_gen_ibinomial_negative — Genera una desviación aleatoria de la distribución binomial negativa
- stats_rand_gen_int — Genera un integer aleatorio entre 1 y 2147483562
- stats_rand_gen_ipoisson — Genera una sola desviación aleatoria de la distribución de Poisson
- stats_rand_gen_iuniform — Devuelve un integer aleatorio uniformemente distribuido entre LOW (incluido) y HIGH (incluido)
- stats_rand_gen_noncentral_chisquare — Genera una desviación aleatoria de la distribución chi-cuadrado no central
- stats_rand_gen_noncentral_f — Genera una desviación aleatoria de la distribución F no central
- stats_rand_gen_noncentral_t — Genera una única desviación aleatoria de la distribución t no central
- stats_rand_gen_normal — Genera una desviación aleatoria de la distribución normal
- stats_rand_gen_t — Genera una sola desviación aleatoria de la distribución t
- stats_rand_get_seeds — Devuelve los valores de la semilla del generador de números aleatorios
- stats_rand_phrase_to_seeds — Genera dos semillas para el generador de números aleatorios RGN
- stats_rand_ranf — Genera un número flotante aleatorio entre 0 y 1
- stats_rand_setall — Define los valores de la semilla para el generador aleatorio
- stats_skew — Calcula la asimetría de los datos en una tabla
- stats_standard_deviation — Devuelve la desviación estándar
- stats_stat_binomial_coef — Devuelve un coeficiente binomial
- stats_stat_correlation — Devuelve el coeficiente de correlación de Pearson de dos conjuntos de datos
- stats_stat_factorial — Devuelve el factorial de un entero
- stats_stat_independent_t — Devuelve el valor t de la prueba t para dos muestras independientes
- stats_stat_innerproduct — Devuelve el producto interno de dos vectores
- stats_stat_paired_t — Devuelve el valor t de la prueba t dependiente de dos muestras emparejadas
- stats_stat_percentile — Devuelve el valor del percentil
- stats_stat_powersum — Devuelve la suma de las potencias de un vector
- stats_variance — Devuelve la varianza

- Instalación/Configuración
  - Requerimientos
  - Instalación
- Funciones estadísticas
  - stats_absolute_deviation — Devuelve la desviación absoluta de un array de valores
  - stats_cdf_beta — Calcula un parámetro de la distribución beta en función de otros valores
  - stats_cdf_binomial — Calcula un argumento de la distribución binomial en función de los otros valores
  - stats_cdf_cauchy — Calcula un parámetro de la distribución de Cauchy en función de otros valores
  - stats_cdf_chisquare — Calcula un parámetro de la distribución del chi-cuadrado en función de los otros valores
  - stats_cdf_exponential — Calcula un parámetro de la distribución exponencial en función de otros valores
  - stats_cdf_f — Calcula un parámetro de la distribución F en función de otros valores
  - stats_cdf_gamma — Calcula un parámetro de la distribución gamma en función de los otros valores
  - stats_cdf_laplace — Calcula un parámetro de la distribución de Laplace en función de los otros valores
  - stats_cdf_logistic — Calcula un parámetro de la distribución logística en función de otros valores
  - stats_cdf_negative_binomial — Calcula un parámetro de la distribución binomial negativa en función de los otros valores
  - stats_cdf_noncentral_chisquare — Calcula un argumento de la distribución del chi-cuadrado no central en función de otros valores
  - stats_cdf_noncentral_f — Calcula un parámetro de la distribución F no central en función de los otros valores
  - stats_cdf_noncentral_t — Calcula un parámetro de la distribución t no central en función de los otros valores
  - stats_cdf_normal — Calcule un parámetro de la distribución normal en función de los otros valores
  - stats_cdf_poisson — Calcula un parámetro de la distribución de Poisson en función de los otros valores
  - stats_cdf_t — Calcula un parámetro de la distribución t en función de los otros valores
  - stats_cdf_uniform — Calcula un parámetro de la distribución uniforme en función de otros valores
  - stats_cdf_weibull — Calcula un parámetro de la distribución de Weibull en función de otros valores
  - stats_covariance — Calcula la covarianza de dos conjuntos de datos
  - stats_dens_beta — La función de densidad de probabilidad de la distribución beta
  - stats_dens_cauchy — La función de densidad de probabilidad de la distribución de Cauchy
  - stats_dens_chisquare — La función de densidad de probabilidad de la distribución chi-cuadrado
  - stats_dens_exponential — La función de densidad de probabilidad de la distribución exponencial
  - stats_dens_f — La función de densidad de probabilidad de la distribución F
  - stats_dens_gamma — La función de densidad de probabilidad de la distribución gamma
  - stats_dens_laplace — La función de densidad de probabilidad de la distribución de Laplace
  - stats_dens_logistic — La función de densidad de probabilidad de la distribución logística
  - stats_dens_normal — La función de densidad de probabilidad de la distribución normal
  - stats_dens_pmf_binomial — La función de masa de probabilidad de la distribución binomial
  - stats_dens_pmf_hypergeometric — La función de masa de probabilidad de la distribución hipergeométrica
  - stats_dens_pmf_negative_binomial — La función de masa de probabilidad de la distribución binomial negativa
  - stats_dens_pmf_poisson — La función de masa de probabilidad de la distribución de Poisson
  - stats_dens_t — La función de densidad de probabilidad de la distribución t
  - stats_dens_uniform — La función de densidad de probabilidad de la distribución uniforme
  - stats_dens_weibull — La función de densidad de probabilidad de la distribución de Weibull
  - stats_harmonic_mean — Devuelve la media armónica de un array de valores
  - stats_kurtosis — Calcula el kurtosis de los datos en el array
  - stats_rand_gen_beta — Genera una desviación aleatoria de la distribución beta
  - stats_rand_gen_chisquare — Genera una desviación aleatoria de la distribución chi-cuadrado
  - stats_rand_gen_exponential — Genera una desviación aleatoria de la distribución exponencial
  - stats_rand_gen_f — Genera una desviación aleatoria de la distribución F
  - stats_rand_gen_funiform — Genera un flotante uniforme entre low (exclusivo) y high (exclusivo)
  - stats_rand_gen_gamma — Genera una desviación aleatoria de la distribución gamma
  - stats_rand_gen_ibinomial — Genera una desviación aleatoria de la distribución binomial
  - stats_rand_gen_ibinomial_negative — Genera una desviación aleatoria de la distribución binomial negativa
  - stats_rand_gen_int — Genera un integer aleatorio entre 1 y 2147483562
  - stats_rand_gen_ipoisson — Genera una sola desviación aleatoria de la distribución de Poisson
  - stats_rand_gen_iuniform — Devuelve un integer aleatorio uniformemente distribuido entre LOW (incluido) y HIGH (incluido)
  - stats_rand_gen_noncentral_chisquare — Genera una desviación aleatoria de la distribución chi-cuadrado no central
  - stats_rand_gen_noncentral_f — Genera una desviación aleatoria de la distribución F no central
  - stats_rand_gen_noncentral_t — Genera una única desviación aleatoria de la distribución t no central
  - stats_rand_gen_normal — Genera una desviación aleatoria de la distribución normal
  - stats_rand_gen_t — Genera una sola desviación aleatoria de la distribución t
  - stats_rand_get_seeds — Devuelve los valores de la semilla del generador de números aleatorios
  - stats_rand_phrase_to_seeds — Genera dos semillas para el generador de números aleatorios RGN
  - stats_rand_ranf — Genera un número flotante aleatorio entre 0 y 1
  - stats_rand_setall — Define los valores de la semilla para el generador aleatorio
  - stats_skew — Calcula la asimetría de los datos en una tabla
  - stats_standard_deviation — Devuelve la desviación estándar
  - stats_stat_binomial_coef — Devuelve un coeficiente binomial
  - stats_stat_correlation — Devuelve el coeficiente de correlación de Pearson de dos conjuntos de datos
  - stats_stat_factorial — Devuelve el factorial de un entero
  - stats_stat_independent_t — Devuelve el valor t de la prueba t para dos muestras independientes
  - stats_stat_innerproduct — Devuelve el producto interno de dos vectores
  - stats_stat_paired_t — Devuelve el valor t de la prueba t dependiente de dos muestras emparejadas
  - stats_stat_percentile — Devuelve el valor del percentil
  - stats_stat_powersum — Devuelve la suma de las potencias de un vector
  - stats_variance — Devuelve la varianza

# Análisis técnico para comerciantes

# Introducción

La extensión trader es una biblioteca de código abierto gratuita basada en TA-Lib. Está dedicada a los desarrolladores de software de actividad comercial que requieren realizar análisis técnicos de datos de mercado financiero. Al lado de muchos indicadores como ADX, MACD, RSI, Estocástico, TRIX, están presentes el reconocimiento de patrones de velas y varias funciones de vectores aritméticas y algebraicas.

Los cálculos se pueden realizar en dos modos: TA-Lib y Metastock. Cambiándolo usando trader_set_compat() afectará la manera en que funcionan algunas funciones de trader.

Algunas funciones de trader proporcionan diferentes resultados dependiendo del "punto de inicio" de los datos involucrados. Esto se refiere a menudo como que una función posee memoria. Un ejemplo de tales funciones es la Media móvil exponencial. Es posible controlar el perido inestable (la cantidad de datos a quitar) usando la función trader_set_unstable_period().

Se puede encontrar documentación ampliada sobre indicadores, fórmulas e implementaciones en otros lenguajes de programación en » https://ta-lib.org/.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución

## Requerimientos

La extensión trader se basa en » TA-Lib. TA-Lib está totalmente integrado en la extensión, por lo que no es necesaria ninguna biblioteca externa.

## Instalación

Esta extensión » PECL no está integrada en PHP.

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/trader.

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

Trader Opciones de configuración
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
trader.real_precision | 3 | `INI_ALL` | Desde trader 0.2.1
trader.real_round_mode | HALF_DOWN | `INI_ALL` | Desde trader 0.3.0

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`trader.real_precision` int

  Todos los valores de los arrays devueltos serán redondeados a esta precisión. Sin enbargo, los cálculos dentro de TA-Lib se realizarán con valores no redondeados.

`trader.real_round_mode` string

  Controla la política de redondeo de números reales de trader. Los valores válidos son `HALF_UP`, `HALF_DOWN`, `HALF_EVEN` y `HALF_ODD`. El comportamiento es idéntico al de la función round() usada con el argumento de modo.

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`TRADER_MA_TYPE_SMA` (int)
`TRADER_MA_TYPE_EMA` (int)
`TRADER_MA_TYPE_WMA` (int)
`TRADER_MA_TYPE_DEMA` (int)
`TRADER_MA_TYPE_TEMA` (int)
`TRADER_MA_TYPE_TRIMA` (int)
`TRADER_MA_TYPE_KAMA` (int)
`TRADER_MA_TYPE_MAMA` (int)
`TRADER_MA_TYPE_T3` (int)
`TRADER_REAL_MIN` (float)
`TRADER_REAL_MAX` (float)
`TRADER_FUNC_UNST_ADX` (int)
`TRADER_FUNC_UNST_ADXR` (int)
`TRADER_FUNC_UNST_ATR` (int)
`TRADER_FUNC_UNST_CMO` (int)
`TRADER_FUNC_UNST_DX` (int)
`TRADER_FUNC_UNST_EMA` (int)
`TRADER_FUNC_UNST_HT_DCPERIOD` (int)
`TRADER_FUNC_UNST_HT_DCPHASE` (int)
`TRADER_FUNC_UNST_HT_PHASOR` (int)
`TRADER_FUNC_UNST_HT_SINE` (int)
`TRADER_FUNC_UNST_HT_TRENDLINE` (int)
`TRADER_FUNC_UNST_HT_TRENDMODE` (int)
`TRADER_FUNC_UNST_KAMA` (int)
`TRADER_FUNC_UNST_MAMA` (int)
`TRADER_FUNC_UNST_MFI` (int)
`TRADER_FUNC_UNST_MINUS_DI` (int)
`TRADER_FUNC_UNST_MINUS_DM` (int)
`TRADER_FUNC_UNST_NATR` (int)
`TRADER_FUNC_UNST_PLUS_DI` (int)
`TRADER_FUNC_UNST_PLUS_DM` (int)
`TRADER_FUNC_UNST_RSI` (int)
`TRADER_FUNC_UNST_STOCHRSI` (int)
`TRADER_FUNC_UNST_T3` (int)
`TRADER_FUNC_UNST_ALL` (int)
`TRADER_FUNC_UNST_NONE` (int)
`TRADER_COMPATIBILITY_DEFAULT` (int)
`TRADER_COMPATIBILITY_METASTOCK` (int)
`TRADER_ERR_SUCCESS` (int)
`TRADER_ERR_LIB_NOT_INITIALIZE` (int)
`TRADER_ERR_BAD_PARAM` (int)
`TRADER_ERR_ALLOC_ERR` (int)
`TRADER_ERR_GROUP_NOT_FOUND` (int)
`TRADER_ERR_FUNC_NOT_FOUND` (int)
`TRADER_ERR_INVALID_HANDLE` (int)
`TRADER_ERR_INVALID_PARAM_HOLDER` (int)
`TRADER_ERR_INVALID_PARAM_HOLDER_TYPE` (int)
`TRADER_ERR_INVALID_PARAM_FUNCTION` (int)
`TRADER_ERR_INPUT_NOT_ALL_INITIALIZE` (int)
`TRADER_ERR_OUTPUT_NOT_ALL_INITIALIZE` (int)
`TRADER_ERR_OUT_OF_RANGE_START_INDEX` (int)
`TRADER_ERR_OUT_OF_RANGE_END_INDEX` (int)
`TRADER_ERR_INVALID_LIST_TYPE` (int)
`TRADER_ERR_BAD_OBJECT` (int)
`TRADER_ERR_NOT_SUPPORTED` (int)
`TRADER_ERR_INTERNAL_ERROR` (int)
`TRADER_ERR_UNKNOWN_ERROR` (int)

# Funciones de Trader

# trader_acos

(PECL trader >= 0.2.0)

trader_acos — Arcocoseno trigonométrico de vectores

### Descripción

function trader_acos(array `$real`): array

Calcula el arcocoseno para cada valor de `real` y devuelve el array resultante.

### Parámetros

`real`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_ad

(PECL trader >= 0.2.0)

trader_ad — Línea A/D Chaikin

### Descripción

function trader_ad(
array `$high`,
array `$low`,
array `$close`,
array `$volume`
): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

`volume`

  Volumen intercambiado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_add

(PECL trader >= 0.2.0)

trader_add — Suma aritmética de vectores

### Descripción

function trader_add(array `$real0`, array `$real1`): array

Calcula la suma de vectores de `real0` a `real1` y devuelve el vector resultante.

### Parámetros

`real0`

  Array de valores reales.

`real1`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_adosc

(PECL trader >= 0.2.0)

trader_adosc — Oscilador A/D Chaikin

### Descripción

function trader_adosc(
array `$high`,
array `$low`,
array `$close`,
array `$volume`,
int `$fastPeriod` = ?,
int `$slowPeriod` = ?
): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

`volume`

  Volumen intercambiado, array de valores reales.

`fastPeriod`

  Número de período para el MA rápido. Intervalo válido: 2 a 100000.

`slowPeriod`

  Número de período para el MA. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_adx

(PECL trader >= 0.2.0)

trader_adx — Índice de movimiento direccional medio

### Descripción

function trader_adx(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_adxr

(PECL trader >= 0.2.0)

trader_adxr — Tasación del índice de movimiento direccional medio

### Descripción

function trader_adxr(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_apo

(PECL trader >= 0.2.0)

trader_apo — Oscilador de precio absoluto

### Descripción

function trader_apo(
array `$real`,
int `$fastPeriod` = ?,
int `$slowPeriod` = ?,
int `$mAType` = ?
): array

### Parámetros

`real`

  Array de valores reales.

`fastPeriod`

  Número de período para el MA rápido. Intervalo válido: 2 a 100000.

`slowPeriod`

  Número de período para el MA. Intervalo válido: 2 a 100000.

`mAType`

  Tipo de media móvil. Una constante de la serie TRADER_MA_TYPE_* debe ser utilizada.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_aroon

(PECL trader >= 0.2.0)

trader_aroon — Aroon

### Descripción

function trader_aroon(array `$high`, array `$low`, int `$timePeriod` = ?): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_aroonosc

(PECL trader >= 0.2.0)

trader_aroonosc — Oscilador Aroon

### Descripción

function trader_aroonosc(array `$high`, array `$low`, int `$timePeriod` = ?): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_asin

(PECL trader >= 0.2.0)

trader_asin — Arcoseno trigonométrico de vectores

### Descripción

function trader_asin(array `$real`): array

Calcula el seno para cada valor de `real` y devuelve el array resultante.

### Parámetros

`real`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_atan

(PECL trader >= 0.2.0)

trader_atan — Arcotangente trigonométrica de vectores

### Descripción

function trader_atan(array `$real`): array

Calcula la arcotangente para cada valor de `real` y devuelve el array resultante.

### Parámetros

`real`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_atr

(PECL trader >= 0.2.0)

trader_atr — Rango verdadero medio

### Descripción

function trader_atr(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_avgprice

(PECL trader >= 0.2.0)

trader_avgprice — Precio medio

### Descripción

function trader_avgprice(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_bbands

(PECL trader >= 0.2.0)

trader_bbands — Bandas de Bollinger

### Descripción

function trader_bbands(
array `$real`,
int `$timePeriod` = ?,
float `$nbDevUp` = ?,
float `$nbDevDn` = ?,
int `$mAType` = ?
): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

`nbDevUp`

  Multiplicador de desviación para la banda superior. Intervalo válido: TRADER_REAL_MIN a TRADER_REAL_MAX.

`nbDevDn`

  Multiplicador de desviación para la banda inferior. Intervalo válido: TRADER_REAL_MIN a TRADER_REAL_MAX.

`mAType`

  Tipo de media móvil. Una constante de la serie TRADER_MA_TYPE_* debe ser utilizada.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_beta

(PECL trader >= 0.2.0)

trader_beta — Beta

### Descripción

function trader_beta(array `$real0`, array `$real1`, int `$timePeriod` = ?): array

### Parámetros

`real0`

  Array de valores reales.

`real1`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_bop

(PECL trader >= 0.2.0)

trader_bop — Equilibrio de poder

### Descripción

function trader_bop(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cci

(PECL trader >= 0.2.0)

trader_cci — Índice de Canal de Comodidad

### Descripción

function trader_cci(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdl2crows

(PECL trader >= 0.2.0)

trader_cdl2crows — Dos Cuervos

### Descripción

function trader_cdl2crows(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdl3blackcrows

(PECL trader >= 0.2.0)

trader_cdl3blackcrows — Tres Cuervos Negros

### Descripción

function trader_cdl3blackcrows(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdl3inside

(PECL trader >= 0.2.0)

trader_cdl3inside — Tres Velas Interiores Alcistas/Bajistas

### Descripción

function trader_cdl3inside(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdl3linestrike

(PECL trader >= 0.2.0)

trader_cdl3linestrike — Triple Golpe

### Descripción

function trader_cdl3linestrike(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdl3outside

(PECL trader >= 0.2.0)

trader_cdl3outside — Tres Velas Exteriores Alcistas/Bajistas

### Descripción

function trader_cdl3outside(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdl3starsinsouth

(PECL trader >= 0.2.0)

trader_cdl3starsinsouth — Tres Estrellas en el Sur

### Descripción

function trader_cdl3starsinsouth(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdl3whitesoldiers

(PECL trader >= 0.2.0)

trader_cdl3whitesoldiers — Tres Soldados Blancos Avanzando

### Descripción

function trader_cdl3whitesoldiers(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlabandonedbaby

(PECL trader >= 0.2.0)

trader_cdlabandonedbaby — Bebé Abandonado

### Descripción

function trader_cdlabandonedbaby(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

`penetration`

  Porcentaje de penetración de una vela en otra vela.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdladvanceblock

(PECL trader >= 0.2.0)

trader_cdladvanceblock — Avance en Bloque

### Descripción

function trader_cdladvanceblock(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlbelthold

(PECL trader >= 0.2.0)

trader_cdlbelthold — Belt-hold

### Descripción

function trader_cdlbelthold(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlbreakaway

(PECL trader >= 0.2.0)

trader_cdlbreakaway — Escape

### Descripción

function trader_cdlbreakaway(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlclosingmarubozu

(PECL trader >= 0.2.0)

trader_cdlclosingmarubozu — Vela Cerrada Marubozu

### Descripción

function trader_cdlclosingmarubozu(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlconcealbabyswall

(PECL trader >= 0.2.0)

trader_cdlconcealbabyswall — Pequeña Golondrina Escondida

### Descripción

function trader_cdlconcealbabyswall(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlcounterattack

(PECL trader >= 0.2.0)

trader_cdlcounterattack — Contraataque

### Descripción

function trader_cdlcounterattack(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdldarkcloudcover

(PECL trader >= 0.2.0)

trader_cdldarkcloudcover — Cubierta de Nube Oscura

### Descripción

function trader_cdldarkcloudcover(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

`penetration`

  Porcentaje de penetración de una vela en otra vela.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdldoji

(PECL trader >= 0.2.0)

trader_cdldoji — Doji

### Descripción

function trader_cdldoji(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdldojistar

(PECL trader >= 0.2.0)

trader_cdldojistar — Estrella Doji

### Descripción

function trader_cdldojistar(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdldragonflydoji

(PECL trader >= 0.2.0)

trader_cdldragonflydoji — Doji Libélula

### Descripción

function trader_cdldragonflydoji(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlengulfing

(PECL trader >= 0.2.0)

trader_cdlengulfing — Patrón envolvente

### Descripción

function trader_cdlengulfing(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdleveningdojistar

(PECL trader >= 0.2.0)

trader_cdleveningdojistar — Estrella Vespertina Doji

### Descripción

function trader_cdleveningdojistar(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

`penetration`

  Porcentaje de penetración de una vela en otra vela.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdleveningstar

(PECL trader >= 0.2.0)

trader_cdleveningstar — Estrella de Atardecer

### Descripción

function trader_cdleveningstar(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

`penetration`

  Porcentaje de penetración de una vela en otra vela.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlgapsidesidewhite

(PECL trader >= 0.2.0)

trader_cdlgapsidesidewhite — Velas blancas paralelas de hueco alcista/bajista

### Descripción

function trader_cdlgapsidesidewhite(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlgravestonedoji

(PECL trader >= 0.2.0)

trader_cdlgravestonedoji — Doji Lápida

### Descripción

function trader_cdlgravestonedoji(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlhammer

(PECL trader >= 0.2.0)

trader_cdlhammer — Martillo

### Descripción

function trader_cdlhammer(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlhangingman

(PECL trader >= 0.2.0)

trader_cdlhangingman — Hombre Colgado

### Descripción

function trader_cdlhangingman(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlharami

(PECL trader >= 0.2.0)

trader_cdlharami — Patrón Harami

### Descripción

function trader_cdlharami(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlharamicross

(PECL trader >= 0.2.0)

trader_cdlharamicross — Patrón Cruz Harami

### Descripción

function trader_cdlharamicross(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlhighwave

(PECL trader >= 0.2.0)

trader_cdlhighwave — Vela de Onda Alta

### Descripción

function trader_cdlhighwave(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlhikkake

(PECL trader >= 0.2.0)

trader_cdlhikkake — Patrón Hikkake

### Descripción

function trader_cdlhikkake(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlhikkakemod

(PECL trader >= 0.2.0)

trader_cdlhikkakemod — Patrón Hikkake Modificado

### Descripción

function trader_cdlhikkakemod(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlhomingpigeon

(PECL trader >= 0.2.0)

trader_cdlhomingpigeon — Paloma Mensajera

### Descripción

function trader_cdlhomingpigeon(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlidentical3crows

(PECL trader >= 0.2.0)

trader_cdlidentical3crows — Tres Cuervos Idénticos

### Descripción

function trader_cdlidentical3crows(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlinneck

(PECL trader >= 0.2.0)

trader_cdlinneck — Patrón Formación en el cuello

### Descripción

function trader_cdlinneck(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlinvertedhammer

(PECL trader >= 0.2.0)

trader_cdlinvertedhammer — Martilllo Invertido

### Descripción

function trader_cdlinvertedhammer(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlkicking

(PECL trader >= 0.2.0)

trader_cdlkicking — Patada

### Descripción

function trader_cdlkicking(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlkickingbylength

(PECL trader >= 0.2.0)

trader_cdlkickingbylength — Patada - alza/baja determinada por el marubozu más largo

### Descripción

function trader_cdlkickingbylength(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlladderbottom

(PECL trader >= 0.2.0)

trader_cdlladderbottom — Suelo de escalera

### Descripción

function trader_cdlladderbottom(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdllongleggeddoji

(PECL trader >= 0.2.0)

trader_cdllongleggeddoji — Doji Zancudo

### Descripción

function trader_cdllongleggeddoji(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdllongline

(PECL trader >= 0.2.0)

trader_cdllongline — Vela de Línea Larga

### Descripción

function trader_cdllongline(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlmarubozu

(PECL trader >= 0.2.0)

trader_cdlmarubozu — Marubozu

### Descripción

function trader_cdlmarubozu(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlmatchinglow

(PECL trader >= 0.2.0)

trader_cdlmatchinglow — Mínimos coincidentes

### Descripción

function trader_cdlmatchinglow(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlmathold

(PECL trader >= 0.2.0)

trader_cdlmathold — Mat Hold

### Descripción

function trader_cdlmathold(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

`penetration`

  Porcentaje de penetración de una vela en otra vela.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlmorningdojistar

(PECL trader >= 0.2.0)

trader_cdlmorningdojistar — Lucero del Alba Doji

### Descripción

function trader_cdlmorningdojistar(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

`penetration`

  Porcentaje de penetración de una vela en otra vela.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlmorningstar

(PECL trader >= 0.2.0)

trader_cdlmorningstar — Lucero del Alba

### Descripción

function trader_cdlmorningstar(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

`penetration`

  Porcentaje de penetración de una vela en otra vela.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlonneck

(PECL trader >= 0.2.0)

trader_cdlonneck — Patrón Sobre el cuello

### Descripción

function trader_cdlonneck(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlpiercing

(PECL trader >= 0.2.0)

trader_cdlpiercing — Patrón penetrante

### Descripción

function trader_cdlpiercing(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlrickshawman

(PECL trader >= 0.2.0)

trader_cdlrickshawman — Calesero

### Descripción

function trader_cdlrickshawman(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlrisefall3methods

(PECL trader >= 0.2.0)

trader_cdlrisefall3methods — Triple Formación Alcista/Bajista

### Descripción

function trader_cdlrisefall3methods(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlseparatinglines

(PECL trader >= 0.2.0)

trader_cdlseparatinglines — Lineas Separadas

### Descripción

function trader_cdlseparatinglines(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlshootingstar

(PECL trader >= 0.2.0)

trader_cdlshootingstar — Estrella Fugaz

### Descripción

function trader_cdlshootingstar(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlshortline

(PECL trader >= 0.2.0)

trader_cdlshortline — Vela de Línea Corta

### Descripción

function trader_cdlshortline(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlspinningtop

(PECL trader >= 0.2.0)

trader_cdlspinningtop — Peonza

### Descripción

function trader_cdlspinningtop(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlstalledpattern

(PECL trader >= 0.2.0)

trader_cdlstalledpattern — Patrón Añejo

### Descripción

function trader_cdlstalledpattern(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlsticksandwich

(PECL trader >= 0.2.0)

trader_cdlsticksandwich — Bocadillo

### Descripción

function trader_cdlsticksandwich(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdltakuri

(PECL trader >= 0.2.0)

trader_cdltakuri — Takuri (Libélula Doji con sombra muy larga)

### Descripción

function trader_cdltakuri(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdltasukigap

(PECL trader >= 0.2.0)

trader_cdltasukigap — Hueco Tasuki

### Descripción

function trader_cdltasukigap(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlthrusting

(PECL trader >= 0.2.0)

trader_cdlthrusting — Patrón de empuje

### Descripción

function trader_cdlthrusting(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdltristar

(PECL trader >= 0.2.0)

trader_cdltristar — Patrón de tres estrellas

### Descripción

function trader_cdltristar(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlunique3river

(PECL trader >= 0.2.0)

trader_cdlunique3river — Tres ríos únicos

### Descripción

function trader_cdlunique3river(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlupsidegap2crows

(PECL trader >= 0.2.0)

trader_cdlupsidegap2crows — Dos Cuervos tras un Huevo al Alza

### Descripción

function trader_cdlupsidegap2crows(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cdlxsidegap3methods

(PECL trader >= 0.2.0)

trader_cdlxsidegap3methods — Métodos de Tres Huevos al Alza/Baja

### Descripción

function trader_cdlxsidegap3methods(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parámetros

`open`

  Precio abierto, array de valores reales.

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_ceil

(PECL trader >= 0.2.0)

trader_ceil — Redondeo hacia arriba de vectores

### Descripción

function trader_ceil(array `$real`): array

Calcula el siguiente entero mayor para cada valor de `real` y devuelve el array resultante.

### Parámetros

`real`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cmo

(PECL trader >= 0.2.0)

trader_cmo — Oscilador de momento de Chande

### Descripción

function trader_cmo(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_correl

(PECL trader >= 0.2.0)

trader_correl — Coeficiente de correlación de Pearson (r)

### Descripción

function trader_correl(array `$real0`, array `$real1`, int `$timePeriod` = ?): array

### Parámetros

`real0`

  Array de valores reales.

`real1`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cos

(PECL trader >= 0.2.0)

trader_cos — Coseno trigonométrico de vectores

### Descripción

function trader_cos(array `$real`): array

Calcula el coseno para cada valor de `real` y devuelve el array resultante.

### Parámetros

`real`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_cosh

(PECL trader >= 0.2.0)

trader_cosh — Coseno hiperbólico de un vector

### Descripción

function trader_cosh(array `$real`): array

Calcula el coseno hiperbólico para cada valor de `real` y devuelve el array resultante.

### Parámetros

`real`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_dema

(PECL trader >= 0.2.0)

trader_dema — Media móvil exponencial doble

### Descripción

function trader_dema(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_div

(PECL trader >= 0.2.0)

trader_div — División aritmética de vectores

### Descripción

function trader_div(array `$real0`, array `$real1`): array

Divide cada valor de `real0` por el valor correspondiente de `real1` y devuelve el array resultante.

### Parámetros

`real0`

  Array de valores reales.

`real1`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de fallo.

# trader_dx

(PECL trader >= 0.2.0)

trader_dx — Índice de movimiento direccional

### Descripción

function trader_dx(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_ema

(PECL trader >= 0.2.0)

trader_ema — Media móvil exponencial

### Descripción

function trader_ema(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_errno

(PECL trader >= 0.3.0)

trader_errno — Obtener el código de error

### Descripción

function trader_errno(): int

Obtener el código de error de la última operación.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el código de error identificado por una de las constantes TRADER_ERR_*.

# trader_exp

(PECL trader >= 0.2.0)

trader_exp — Exponencial aritmética de vectores

### Descripción

function trader_exp(array `$real`): array

Calcula `e` elevado a la potencia de cada valor de `real`. Devuelve un array con los datos calculados.

### Parámetros

`real`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_floor

(PECL trader >= 0.2.0)

trader_floor — Redondeo hacia abajo de vectores

### Descripción

function trader_floor(array `$real`): array

Calcula el siguiente entero menor para cada valor de `real` y devuelve el array resultante.

### Parámetros

`real`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_get_compat

(PECL trader >= 0.2.2)

trader_get_compat — Obtiene el modo de compatibilidad

### Descripción

function trader_get_compat(): int

Obtiene el modo de compatibilidad que afecta a la forma de realizar los cálculos de todas las funciones de la extensión.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el id del modo de compatibilidad que puede ser identificado por la serie de constantes de TRADER_COMPATIBILITY_*.

# trader_get_unstable_period

(PECL trader >= 0.2.2)

trader_get_unstable_period — Obtiene el periodo inestable

### Descripción

function trader_get_unstable_period(int `$functionId`): int

Obtiene el factor de periodo inestable para una función en particular.

### Parámetros

`functionId`

  El ID de la función por la que leer el factor. Se debería usar la serie de constantes TRADER_FUNC_UNST_*.

### Valores devueltos

Devuelve el factor del periodo inestable para la función correspondiente.

# trader_ht_dcperiod

(PECL trader >= 0.2.0)

trader_ht_dcperiod — Transformación de Hilbert - Período de ciclo dominante

### Descripción

function trader_ht_dcperiod(array `$real`): array

### Parámetros

`real`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_ht_dcphase

(PECL trader >= 0.2.0)

trader_ht_dcphase — Transformación de Hilbert - Fase de ciclo dominante

### Descripción

function trader_ht_dcphase(array `$real`): array

### Parámetros

`real`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_ht_phasor

(PECL trader >= 0.2.0)

trader_ht_phasor — Transformación de Hilbert - Componentes de un fasor

### Descripción

function trader_ht_phasor(array `$real`): array

### Parámetros

`real`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_ht_sine

(PECL trader >= 0.2.0)

trader_ht_sine — Transformación de Hilbert - Sinusoide

### Descripción

function trader_ht_sine(array `$real`): array

### Parámetros

`real`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_ht_trendline

(PECL trader >= 0.2.0)

trader_ht_trendline — Transformación de Hilbert - Línea de tendencia instantánea

### Descripción

function trader_ht_trendline(array `$real`): array

### Parámetros

`real`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_ht_trendmode

(PECL trader >= 0.2.0)

trader_ht_trendmode — Transformación de Hilbert - Tendencia vs Modo de ciclo

### Descripción

function trader_ht_trendmode(array `$real`): array

### Parámetros

`real`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_kama

(PECL trader >= 0.2.0)

trader_kama — Media móvil adaptativa de Kaufman

### Descripción

function trader_kama(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_linearreg

(PECL trader >= 0.2.0)

trader_linearreg — Regresión lineal

### Descripción

function trader_linearreg(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_linearreg_angle

(PECL trader >= 0.2.0)

trader_linearreg_angle — Ángulo de regresión lineal

### Descripción

function trader_linearreg_angle(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_linearreg_intercept

(PECL trader >= 0.2.0)

trader_linearreg_intercept — Intercepción de regresión lineal

### Descripción

function trader_linearreg_intercept(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_linearreg_slope

(PECL trader >= 0.2.0)

trader_linearreg_slope — Pendiente de regresión lineal

### Descripción

function trader_linearreg_slope(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_ln

(PECL trader >= 0.2.0)

trader_ln — Logaritmo natural de vectores

### Descripción

function trader_ln(array `$real`): array

Calcula el logaritmo natural para cada valor de `real` y devuelve el array resultante.

### Parámetros

`real`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_log10

(PECL trader >= 0.2.0)

trader_log10 — Logaritmo en base 10 de vectores

### Descripción

function trader_log10(array `$real`): array

Calcula el logaritmo en base 10 para cada valor de `real` y devuelve el array resultante.

### Parámetros

`real`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_ma

(PECL trader >= 0.2.0)

trader_ma — Media móvil

### Descripción

function trader_ma(array `$real`, int `$timePeriod` = ?, int `$mAType` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

`mAType`

  Tipo de media móvil. Una constante de la serie TRADER_MA_TYPE_* debe ser utilizada.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_macd

(PECL trader >= 0.2.0)

trader_macd — Convergencia/divergencia de la media móvil

### Descripción

function trader_macd(
array `$real`,
int `$fastPeriod` = ?,
int `$slowPeriod` = ?,
int `$signalPeriod` = ?
): array

### Parámetros

`real`

  Array de valores reales.

`fastPeriod`

  Número de período para el MA rápido. Intervalo válido: 2 a 100000.

`slowPeriod`

  Número de período para el MA. Intervalo válido: 2 a 100000.

`signalPeriod`

  Suavizado de la línea de señal (número de período). Intervalo válido: 1 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_macdext

(PECL trader >= 0.2.0)

trader_macdext — MACD con tipo MA controlable

### Descripción

function trader_macdext(
array `$real`,
int `$fastPeriod` = ?,
int `$fastMAType` = ?,
int `$slowPeriod` = ?,
int `$slowMAType` = ?,
int `$signalPeriod` = ?,
int `$signalMAType` = ?
): array

### Parámetros

`real`

  Array de valores reales.

`fastPeriod`

  Número de período para el MA rápido. Intervalo válido: 2 a 100000.

`fastMAType`

  Tipo de media móvil para MA rápido. Una constante de la serie TRADER_MA_TYPE_* debe ser utilizada.

`slowPeriod`

  Número de período para el MA. Intervalo válido: 2 a 100000.

`slowMAType`

  Tipo de media móvil para MA lento. Una constante de la serie TRADER_MA_TYPE_* debe ser utilizada.

`signalPeriod`

  Suavizado de la línea de señal (número de período). Intervalo válido: 1 a 100000.

`signalMAType`

  Tipo de media móvil para la línea de señal. Una constante de la serie TRADER_MA_TYPE_* debe ser utilizada.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_macdfix

(PECL trader >= 0.2.0)

trader_macdfix — Convergencia/divergencia fija 12/26 de la media móvil

### Descripción

function trader_macdfix(array `$real`, int `$signalPeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`signalPeriod`

  Suavizado de la línea de señal (número de período). Intervalo válido: 1 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_mama

(PECL trader >= 0.2.0)

trader_mama — Media móvil adaptativa MESA

### Descripción

function trader_mama(array `$real`, float `$fastLimit` = ?, float `$slowLimit` = ?): array

### Parámetros

`real`

  Array de valores reales.

`fastLimit`

  Límite superior del algoritmo adaptativo. Intervalo válido: 0.01 a 0.99.

`slowLimit`

  Límite inferior del algoritmo adaptativo. Intervalo válido: 0.01 a 0.99.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_mavp

(PECL trader >= 0.2.0)

trader_mavp — Media móvil con periodo variable

### Descripción

function trader_mavp(
array `$real`,
array `$periods`,
int `$minPeriod` = ?,
int `$maxPeriod` = ?,
int `$mAType` = ?
): array

### Parámetros

`real`

  Array de valores reales.

`periods`

  Array de valores reales.

`minPeriod`

  Un valor inferior al mínimo será modificado a la período mínimo. Intervalo válido: 2 a 100000

`maxPeriod`

  Un valor superior al mínimo será modificado a la período máximo. Intervalo válido: 2 a 100000

`mAType`

  Tipo de media móvil. Una constante de la serie TRADER_MA_TYPE_* debe ser utilizada.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_max

(PECL trader >= 0.2.0)

trader_max — Valor mayor sobre un periodo especificado

### Descripción

function trader_max(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_maxindex

(PECL trader >= 0.2.0)

trader_maxindex — Índice del valor mayor sobre un periodo especificado

### Descripción

function trader_maxindex(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_medprice

(PECL trader >= 0.2.0)

trader_medprice — Precio medio

### Descripción

function trader_medprice(array `$high`, array `$low`): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_mfi

(PECL trader >= 0.2.0)

trader_mfi — Índice de flujo de dinero

### Descripción

function trader_mfi(
array `$high`,
array `$low`,
array `$close`,
array `$volume`,
int `$timePeriod` = ?
): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

`volume`

  Volumen intercambiado, array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_midpoint

(PECL trader >= 0.2.0)

trader_midpoint — Punto medio sobre un periodo

### Descripción

function trader_midpoint(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_midprice

(PECL trader >= 0.2.0)

trader_midprice — Precio de punto medio sobre un periodo

### Descripción

function trader_midprice(array `$high`, array `$low`, int `$timePeriod` = ?): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_min

(PECL trader >= 0.2.0)

trader_min — Valor más bajo sobre un periodo especificado

### Descripción

function trader_min(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_minindex

(PECL trader >= 0.2.0)

trader_minindex — Índice del valor más bajo sobre un periodo especificado

### Descripción

function trader_minindex(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_minmax

(PECL trader >= 0.2.0)

trader_minmax — Valores más altos y bajos sobre un periodo especificado

### Descripción

function trader_minmax(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_minmaxindex

(PECL trader >= 0.2.0)

trader_minmaxindex — Índices de los valores más bajos y altos sobre un periodo especificado

### Descripción

function trader_minmaxindex(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_minus_di

(PECL trader >= 0.2.0)

trader_minus_di — Indicador direccional menos

### Descripción

function trader_minus_di(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_minus_dm

(PECL trader >= 0.2.0)

trader_minus_dm — Movimiento direccional menos

### Descripción

function trader_minus_dm(array `$high`, array `$low`, int `$timePeriod` = ?): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_mom

(PECL trader >= 0.2.0)

trader_mom — Momentum

### Descripción

function trader_mom(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_mult

(PECL trader >= 0.2.0)

trader_mult — Multiplicación aritmética de vectores

### Descripción

function trader_mult(array `$real0`, array `$real1`): array

Calcula el producto escalar de `real0` con `real1` y devuelve el vector resultante.

### Parámetros

`real0`

  Array de valores reales.

`real1`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_natr

(PECL trader >= 0.2.0)

trader_natr — Rango verdadero de la media normalizada

### Descripción

function trader_natr(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_obv

(PECL trader >= 0.2.0)

trader_obv — Volumen sobre balance

### Descripción

function trader_obv(array `$real`, array `$volume`): array

### Parámetros

`real`

  Array de valores reales.

`volume`

  Volumen intercambiado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_plus_di

(PECL trader >= 0.2.0)

trader_plus_di — Indicador direccional más

### Descripción

function trader_plus_di(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_plus_dm

(PECL trader >= 0.2.0)

trader_plus_dm — Movimiento direccional más

### Descripción

function trader_plus_dm(array `$high`, array `$low`, int `$timePeriod` = ?): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_ppo

(PECL trader >= 0.2.0)

trader_ppo — Oscilador de precio porcentual

### Descripción

function trader_ppo(
array `$real`,
int `$fastPeriod` = ?,
int `$slowPeriod` = ?,
int `$mAType` = ?
): array

### Parámetros

`real`

  Array de valores reales.

`fastPeriod`

  Número de período para el MA rápido. Intervalo válido: 2 a 100000.

`slowPeriod`

  Número de período para el MA. Intervalo válido: 2 a 100000.

`mAType`

  Tipo de media móvil. Una constante de la serie TRADER_MA_TYPE_* debe ser utilizada.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_roc

(PECL trader >= 0.2.0)

trader_roc — Ritmo de cambio : ((precio/precioAnterior)-1)*100

### Descripción

function trader_roc(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_rocp

(PECL trader >= 0.2.0)

trader_rocp — Porcentaje del ritmo de cabio: (precio-precioAnterior)/precioAnterior

### Descripción

function trader_rocp(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_rocr

(PECL trader >= 0.2.0)

trader_rocr — Ratio del ritmo de cambio: (precio/precioAnterior)

### Descripción

function trader_rocr(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_rocr100

(PECL trader >= 0.2.0)

trader_rocr100 — Ratio del ritmo de cambio en escala 100: (precio/precioAnterior)*100

### Descripción

function trader_rocr100(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_rsi

(PECL trader >= 0.2.0)

trader_rsi — Índice de fuerza relativa

### Descripción

function trader_rsi(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_sar

(PECL trader >= 0.2.0)

trader_sar — Sistema parabólico

### Descripción

function trader_sar(
array `$high`,
array `$low`,
float `$acceleration` = ?,
float `$maximum` = ?
): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`acceleration`

  Factor de aceleración usado hasta el valor máximo. Rango válido de 0 hasta TRADER_REAL_MAX.

`maximum`

  Valor máximo del factor de aceleración. Rango válido de 0 hasta TRADER_REAL_MAX.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_sarext

(PECL trader >= 0.2.0)

trader_sarext — Sistema parabólico - Extendido

### Descripción

function trader_sarext(
array `$high`,
array `$low`,
float `$startValue` = ?,
float `$offsetOnReverse` = ?,
float `$accelerationInitLong` = ?,
float `$accelerationLong` = ?,
float `$accelerationMaxLong` = ?,
float `$accelerationInitShort` = ?,
float `$accelerationShort` = ?,
float `$accelerationMaxShort` = ?
): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`startValue`

  Valor inicial y dirección. 0 para Auto, >0 para Long, <0 para Short. Rango válido de TRADER_REAL_MIN hasta TRADER_REAL_MAX.

`offsetOnReverse`

  Índice de porcentaje añadido/eliminado a la parada inicial sobre el reverso short/long reversal. Rango válido de 0 hasta TRADER_REAL_MAX.

`accelerationInitLong`

  Valor inicial del factor de aceleración para la dirección Long. Rango válido de 0 hasta TRADER_REAL_MAX.

`accelerationLong`

  Factor de acelereción para la dirección Long. Rango válido de 0 hasta TRADER_REAL_MAX.

`accelerationMaxLong`

  Valor máximo del factor de aceleración para la dirección Long. Rango válido de 0 hasta TRADER_REAL_MAX.

`accelerationInitShort`

  Valor inicial del factor de aceleración para la dirección Short. Rango válido de 0 hasta TRADER_REAL_MAX.

`accelerationShort`

  Factor de aceleración para la dirección Short. Rango válido de 0 hasta TRADER_REAL_MAX.

`accelerationMaxShort`

  Valor máximo del factor de aceleración para la dirección Short. Rango válido de 0 hasta TRADER_REAL_MAX.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_set_compat

(PECL trader >= 0.2.2)

trader_set_compat — Establece el modo de compatibilidad

### Descripción

function trader_set_compat(int `$compatId`): void

Establece el modo de compatibilidad que afectará a la forma de realizar los cálculos de todas las funciones de la extensión.

### Parámetros

`compatId`

  El ID de compatibilidad. Debería usarse la serie de constantes TRADER_COMPATIBILITY_*.

### Valores devueltos

No se retorna ningún valor.

# trader_set_unstable_period

(PECL trader >= 0.2.2)

trader_set_unstable_period — Establece el periodo inestable

### Descripción

function trader_set_unstable_period(int `$functionId`, int `$timePeriod`): void

Factor de periodos inestables de influencia para funciones, las cuales son sensibles a él. Se puede encontrar más información sobre periodos inestables en la página de la documentación de la API » TA-Lib.

### Parámetros

`functionId`

  El ID de la función para la cual debería establecerse el factor. Se pueden usar la serie de constantes TRADER_FUNC_UNST_* para afectar a la función correspondiente.

`timePeriod`

  El valor de periodo inestable.

### Valores devueltos

No se retorna ningún valor.

# trader_sin

(PECL trader >= 0.2.0)

trader_sin — Seno trigonométrico de vectores

### Descripción

function trader_sin(array `$real`): array

Calcula el seno para cada valor de `real` y devuelve el array resultante.

### Parámetros

`real`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_sinh

(PECL trader >= 0.2.0)

trader_sinh — Seno hiperbólico de vectores

### Descripción

function trader_sinh(array `$real`): array

Calcula el seno hiperbólico para cada valor de `real` y devuelve el array resultante.

### Parámetros

`real`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_sma

(PECL trader >= 0.2.0)

trader_sma — Media móvil simple

### Descripción

function trader_sma(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_sqrt

(PECL trader >= 0.2.0)

trader_sqrt — Raíz cuadrada de vectores

### Descripción

function trader_sqrt(array `$real`): array

Calcula la raíz cuadrada de cada valor de `real` y devuelve el array resultante.

### Parámetros

`real`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_stddev

(PECL trader >= 0.2.0)

trader_stddev — Desviación estándar

### Descripción

function trader_stddev(array `$real`, int `$timePeriod` = ?, float `$nbDev` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

`nbDev`

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_stoch

(PECL trader >= 0.2.0)

trader_stoch — Estocástico

### Descripción

function trader_stoch(
array `$high`,
array `$low`,
array `$close`,
int `$fastK_Period` = ?,
int `$slowK_Period` = ?,
int `$slowK_MAType` = ?,
int `$slowD_Period` = ?,
int `$slowD_MAType` = ?
): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

`fastK_Period`

  Período de tiempo para construir la línea Fast-K. Intervalo válido: 1 a 100000.

`slowK_Period`

  Suavizado para realizar la línea Slow-K. Intervalo válido: 1 a 100000, habitualmente definido a 3.

`slowK_MAType`

  Tipo de media móvil para Slow-K. Una constante de la serie TRADER_MA_TYPE_* debe ser utilizada.

`slowD_Period`

  Suavizado para realizar la línea Slow-D. Intervalo válido: 1 a 100000.

`slowD_MAType`

  Tipo de media móvil para Slow-D. Una constante de la serie TRADER_MA_TYPE_* debe ser utilizada.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_stochf

(PECL trader >= 0.2.0)

trader_stochf — Estocástico rápido

### Descripción

function trader_stochf(
array `$high`,
array `$low`,
array `$close`,
int `$fastK_Period` = ?,
int `$fastD_Period` = ?,
int `$fastD_MAType` = ?
): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

`fastK_Period`

  Período de tiempo para construir la línea Fast-K. Intervalo válido: 1 a 100000.

`fastD_Period`

  Suavizado para realizar la línea Fast-D. Intervalo válido: 1 a 100000, habitualmente definido a 3.

`fastD_MAType`

  Tipo de media móvil para Fast-D. Una constante de la serie TRADER_MA_TYPE_* debe ser utilizada.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_stochrsi

(PECL trader >= 0.2.0)

trader_stochrsi — Índice de fuerza relativa estocástica

### Descripción

function trader_stochrsi(
array `$real`,
int `$timePeriod` = ?,
int `$fastK_Period` = ?,
int `$fastD_Period` = ?,
int `$fastD_MAType` = ?
): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

`fastK_Period`

  Período de tiempo para construir la línea Fast-K. Intervalo válido: 1 a 100000.

`fastD_Period`

  Suavizado para realizar la línea Fast-D. Intervalo válido: 1 a 100000, habitualmente definido a 3.

`fastD_MAType`

  Tipo de media móvil para Fast-D. Una constante de la serie TRADER_MA_TYPE_* debe ser utilizada.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_sub

(PECL trader >= 0.2.0)

trader_sub — Sustracción artimética de vectores

### Descripción

function trader_sub(array `$real0`, array `$real1`): array

Calcula la suma de vectores de `real1` desde `real0` y devuelve el vector resultante.

### Parámetros

`real0`

  Array de valores reales.

`real1`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_sum

(PECL trader >= 0.2.0)

trader_sum — Sumatorio

### Descripción

function trader_sum(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_t3

(PECL trader >= 0.2.0)

trader_t3 — Media móvil exponencial triple (T3)

### Descripción

function trader_t3(array `$real`, int `$timePeriod` = ?, float `$vFactor` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

`vFactor`

  Factor de volumen. Intervalo válido: 1 a 0.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_tan

(PECL trader >= 0.2.0)

trader_tan — Tangente trigonométrica de vectores

### Descripción

function trader_tan(array `$real`): array

Calcula la tangente para cada valor de `real` y devuelve el array resultante.

### Parámetros

`real`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_tanh

(PECL trader >= 0.2.0)

trader_tanh — Tangente hiperbólica trigonométrica de vectores

### Descripción

function trader_tanh(array `$real`): array

Calcula la tangente hiperbólica para cada valor de `real` y devuelve el array resultante.

### Parámetros

`real`

  Array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_tema

(PECL trader >= 0.2.0)

trader_tema — Media móvil exponencial triple

### Descripción

function trader_tema(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_trange

(PECL trader >= 0.2.0)

trader_trange — Rango verdadero

### Descripción

function trader_trange(array `$high`, array `$low`, array `$close`): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_trima

(PECL trader >= 0.2.0)

trader_trima — Media móvil triangular

### Descripción

function trader_trima(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_trix

(PECL trader >= 0.2.0)

trader_trix — Ritmo de cambio de 1 día (RDC) de una MME suave triple

### Descripción

function trader_trix(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_tsf

(PECL trader >= 0.2.0)

trader_tsf — Previsión de series de tiempo

### Descripción

function trader_tsf(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_typprice

(PECL trader >= 0.2.0)

trader_typprice — Precio típico

### Descripción

function trader_typprice(array `$high`, array `$low`, array `$close`): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_ultosc

(PECL trader >= 0.2.0)

trader_ultosc — Oscilador final

### Descripción

function trader_ultosc(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod1` = ?,
int `$timePeriod2` = ?,
int `$timePeriod3` = ?
): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

`timePeriod1`

  Número de barras para el primer periodo. Rango válido de 1 hasta 100000.

`timePeriod2`

  Número de barras para el segundo periodo. Rango válido de 1 hasta 100000.

`timePeriod3`

  Número de barras para el tercer periodo. Rango válido de 1 hasta 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_var

(PECL trader >= 0.2.0)

trader_var — Varianza

### Descripción

function trader_var(array `$real`, int `$timePeriod` = ?, float `$nbDev` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

`nbDev`

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_wclprice

(PECL trader >= 0.2.0)

trader_wclprice — Precio de cierre ponderado

### Descripción

function trader_wclprice(array `$high`, array `$low`, array `$close`): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_willr

(PECL trader >= 0.2.0)

trader_willr — %R de Williams

### Descripción

function trader_willr(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parámetros

`high`

  Precio alto, array de valores reales.

`low`

  Precio bajo, array de valores reales.

`close`

  Precio cerrado, array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

# trader_wma

(PECL trader >= 0.2.0)

trader_wma — Media móvil ponderada

### Descripción

function trader_wma(array `$real`, int `$timePeriod` = ?): array

### Parámetros

`real`

  Array de valores reales.

`timePeriod`

  Número de período. Intervalo válido: 2 a 100000.

### Valores devueltos

Devuelve un array con los datos calculados o false en caso de error.

## Tabla de contenidos

- trader_acos — Arcocoseno trigonométrico de vectores
- trader_ad — Línea A/D Chaikin
- trader_add — Suma aritmética de vectores
- trader_adosc — Oscilador A/D Chaikin
- trader_adx — Índice de movimiento direccional medio
- trader_adxr — Tasación del índice de movimiento direccional medio
- trader_apo — Oscilador de precio absoluto
- trader_aroon — Aroon
- trader_aroonosc — Oscilador Aroon
- trader_asin — Arcoseno trigonométrico de vectores
- trader_atan — Arcotangente trigonométrica de vectores
- trader_atr — Rango verdadero medio
- trader_avgprice — Precio medio
- trader_bbands — Bandas de Bollinger
- trader_beta — Beta
- trader_bop — Equilibrio de poder
- trader_cci — Índice de Canal de Comodidad
- trader_cdl2crows — Dos Cuervos
- trader_cdl3blackcrows — Tres Cuervos Negros
- trader_cdl3inside — Tres Velas Interiores Alcistas/Bajistas
- trader_cdl3linestrike — Triple Golpe
- trader_cdl3outside — Tres Velas Exteriores Alcistas/Bajistas
- trader_cdl3starsinsouth — Tres Estrellas en el Sur
- trader_cdl3whitesoldiers — Tres Soldados Blancos Avanzando
- trader_cdlabandonedbaby — Bebé Abandonado
- trader_cdladvanceblock — Avance en Bloque
- trader_cdlbelthold — Belt-hold
- trader_cdlbreakaway — Escape
- trader_cdlclosingmarubozu — Vela Cerrada Marubozu
- trader_cdlconcealbabyswall — Pequeña Golondrina Escondida
- trader_cdlcounterattack — Contraataque
- trader_cdldarkcloudcover — Cubierta de Nube Oscura
- trader_cdldoji — Doji
- trader_cdldojistar — Estrella Doji
- trader_cdldragonflydoji — Doji Libélula
- trader_cdlengulfing — Patrón envolvente
- trader_cdleveningdojistar — Estrella Vespertina Doji
- trader_cdleveningstar — Estrella de Atardecer
- trader_cdlgapsidesidewhite — Velas blancas paralelas de hueco alcista/bajista
- trader_cdlgravestonedoji — Doji Lápida
- trader_cdlhammer — Martillo
- trader_cdlhangingman — Hombre Colgado
- trader_cdlharami — Patrón Harami
- trader_cdlharamicross — Patrón Cruz Harami
- trader_cdlhighwave — Vela de Onda Alta
- trader_cdlhikkake — Patrón Hikkake
- trader_cdlhikkakemod — Patrón Hikkake Modificado
- trader_cdlhomingpigeon — Paloma Mensajera
- trader_cdlidentical3crows — Tres Cuervos Idénticos
- trader_cdlinneck — Patrón Formación en el cuello
- trader_cdlinvertedhammer — Martilllo Invertido
- trader_cdlkicking — Patada
- trader_cdlkickingbylength — Patada - alza/baja determinada por el marubozu más largo
- trader_cdlladderbottom — Suelo de escalera
- trader_cdllongleggeddoji — Doji Zancudo
- trader_cdllongline — Vela de Línea Larga
- trader_cdlmarubozu — Marubozu
- trader_cdlmatchinglow — Mínimos coincidentes
- trader_cdlmathold — Mat Hold
- trader_cdlmorningdojistar — Lucero del Alba Doji
- trader_cdlmorningstar — Lucero del Alba
- trader_cdlonneck — Patrón Sobre el cuello
- trader_cdlpiercing — Patrón penetrante
- trader_cdlrickshawman — Calesero
- trader_cdlrisefall3methods — Triple Formación Alcista/Bajista
- trader_cdlseparatinglines — Lineas Separadas
- trader_cdlshootingstar — Estrella Fugaz
- trader_cdlshortline — Vela de Línea Corta
- trader_cdlspinningtop — Peonza
- trader_cdlstalledpattern — Patrón Añejo
- trader_cdlsticksandwich — Bocadillo
- trader_cdltakuri — Takuri (Libélula Doji con sombra muy larga)
- trader_cdltasukigap — Hueco Tasuki
- trader_cdlthrusting — Patrón de empuje
- trader_cdltristar — Patrón de tres estrellas
- trader_cdlunique3river — Tres ríos únicos
- trader_cdlupsidegap2crows — Dos Cuervos tras un Huevo al Alza
- trader_cdlxsidegap3methods — Métodos de Tres Huevos al Alza/Baja
- trader_ceil — Redondeo hacia arriba de vectores
- trader_cmo — Oscilador de momento de Chande
- trader_correl — Coeficiente de correlación de Pearson (r)
- trader_cos — Coseno trigonométrico de vectores
- trader_cosh — Coseno hiperbólico de un vector
- trader_dema — Media móvil exponencial doble
- trader_div — División aritmética de vectores
- trader_dx — Índice de movimiento direccional
- trader_ema — Media móvil exponencial
- trader_errno — Obtener el código de error
- trader_exp — Exponencial aritmética de vectores
- trader_floor — Redondeo hacia abajo de vectores
- trader_get_compat — Obtiene el modo de compatibilidad
- trader_get_unstable_period — Obtiene el periodo inestable
- trader_ht_dcperiod — Transformación de Hilbert - Período de ciclo dominante
- trader_ht_dcphase — Transformación de Hilbert - Fase de ciclo dominante
- trader_ht_phasor — Transformación de Hilbert - Componentes de un fasor
- trader_ht_sine — Transformación de Hilbert - Sinusoide
- trader_ht_trendline — Transformación de Hilbert - Línea de tendencia instantánea
- trader_ht_trendmode — Transformación de Hilbert - Tendencia vs Modo de ciclo
- trader_kama — Media móvil adaptativa de Kaufman
- trader_linearreg — Regresión lineal
- trader_linearreg_angle — Ángulo de regresión lineal
- trader_linearreg_intercept — Intercepción de regresión lineal
- trader_linearreg_slope — Pendiente de regresión lineal
- trader_ln — Logaritmo natural de vectores
- trader_log10 — Logaritmo en base 10 de vectores
- trader_ma — Media móvil
- trader_macd — Convergencia/divergencia de la media móvil
- trader_macdext — MACD con tipo MA controlable
- trader_macdfix — Convergencia/divergencia fija 12/26 de la media móvil
- trader_mama — Media móvil adaptativa MESA
- trader_mavp — Media móvil con periodo variable
- trader_max — Valor mayor sobre un periodo especificado
- trader_maxindex — Índice del valor mayor sobre un periodo especificado
- trader_medprice — Precio medio
- trader_mfi — Índice de flujo de dinero
- trader_midpoint — Punto medio sobre un periodo
- trader_midprice — Precio de punto medio sobre un periodo
- trader_min — Valor más bajo sobre un periodo especificado
- trader_minindex — Índice del valor más bajo sobre un periodo especificado
- trader_minmax — Valores más altos y bajos sobre un periodo especificado
- trader_minmaxindex — Índices de los valores más bajos y altos sobre un periodo especificado
- trader_minus_di — Indicador direccional menos
- trader_minus_dm — Movimiento direccional menos
- trader_mom — Momentum
- trader_mult — Multiplicación aritmética de vectores
- trader_natr — Rango verdadero de la media normalizada
- trader_obv — Volumen sobre balance
- trader_plus_di — Indicador direccional más
- trader_plus_dm — Movimiento direccional más
- trader_ppo — Oscilador de precio porcentual
- trader_roc — Ritmo de cambio : ((precio/precioAnterior)-1)*100
- trader_rocp — Porcentaje del ritmo de cabio: (precio-precioAnterior)/precioAnterior
- trader_rocr — Ratio del ritmo de cambio: (precio/precioAnterior)
- trader_rocr100 — Ratio del ritmo de cambio en escala 100: (precio/precioAnterior)*100
- trader_rsi — Índice de fuerza relativa
- trader_sar — Sistema parabólico
- trader_sarext — Sistema parabólico - Extendido
- trader_set_compat — Establece el modo de compatibilidad
- trader_set_unstable_period — Establece el periodo inestable
- trader_sin — Seno trigonométrico de vectores
- trader_sinh — Seno hiperbólico de vectores
- trader_sma — Media móvil simple
- trader_sqrt — Raíz cuadrada de vectores
- trader_stddev — Desviación estándar
- trader_stoch — Estocástico
- trader_stochf — Estocástico rápido
- trader_stochrsi — Índice de fuerza relativa estocástica
- trader_sub — Sustracción artimética de vectores
- trader_sum — Sumatorio
- trader_t3 — Media móvil exponencial triple (T3)
- trader_tan — Tangente trigonométrica de vectores
- trader_tanh — Tangente hiperbólica trigonométrica de vectores
- trader_tema — Media móvil exponencial triple
- trader_trange — Rango verdadero
- trader_trima — Media móvil triangular
- trader_trix — Ritmo de cambio de 1 día (RDC) de una MME suave triple
- trader_tsf — Previsión de series de tiempo
- trader_typprice — Precio típico
- trader_ultosc — Oscilador final
- trader_var — Varianza
- trader_wclprice — Precio de cierre ponderado
- trader_willr — %R de Williams
- trader_wma — Media móvil ponderada

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
- Constantes predefinidas
- Funciones de Trader
  - trader_acos — Arcocoseno trigonométrico de vectores
  - trader_ad — Línea A/D Chaikin
  - trader_add — Suma aritmética de vectores
  - trader_adosc — Oscilador A/D Chaikin
  - trader_adx — Índice de movimiento direccional medio
  - trader_adxr — Tasación del índice de movimiento direccional medio
  - trader_apo — Oscilador de precio absoluto
  - trader_aroon — Aroon
  - trader_aroonosc — Oscilador Aroon
  - trader_asin — Arcoseno trigonométrico de vectores
  - trader_atan — Arcotangente trigonométrica de vectores
  - trader_atr — Rango verdadero medio
  - trader_avgprice — Precio medio
  - trader_bbands — Bandas de Bollinger
  - trader_beta — Beta
  - trader_bop — Equilibrio de poder
  - trader_cci — Índice de Canal de Comodidad
  - trader_cdl2crows — Dos Cuervos
  - trader_cdl3blackcrows — Tres Cuervos Negros
  - trader_cdl3inside — Tres Velas Interiores Alcistas/Bajistas
  - trader_cdl3linestrike — Triple Golpe
  - trader_cdl3outside — Tres Velas Exteriores Alcistas/Bajistas
  - trader_cdl3starsinsouth — Tres Estrellas en el Sur
  - trader_cdl3whitesoldiers — Tres Soldados Blancos Avanzando
  - trader_cdlabandonedbaby — Bebé Abandonado
  - trader_cdladvanceblock — Avance en Bloque
  - trader_cdlbelthold — Belt-hold
  - trader_cdlbreakaway — Escape
  - trader_cdlclosingmarubozu — Vela Cerrada Marubozu
  - trader_cdlconcealbabyswall — Pequeña Golondrina Escondida
  - trader_cdlcounterattack — Contraataque
  - trader_cdldarkcloudcover — Cubierta de Nube Oscura
  - trader_cdldoji — Doji
  - trader_cdldojistar — Estrella Doji
  - trader_cdldragonflydoji — Doji Libélula
  - trader_cdlengulfing — Patrón envolvente
  - trader_cdleveningdojistar — Estrella Vespertina Doji
  - trader_cdleveningstar — Estrella de Atardecer
  - trader_cdlgapsidesidewhite — Velas blancas paralelas de hueco alcista/bajista
  - trader_cdlgravestonedoji — Doji Lápida
  - trader_cdlhammer — Martillo
  - trader_cdlhangingman — Hombre Colgado
  - trader_cdlharami — Patrón Harami
  - trader_cdlharamicross — Patrón Cruz Harami
  - trader_cdlhighwave — Vela de Onda Alta
  - trader_cdlhikkake — Patrón Hikkake
  - trader_cdlhikkakemod — Patrón Hikkake Modificado
  - trader_cdlhomingpigeon — Paloma Mensajera
  - trader_cdlidentical3crows — Tres Cuervos Idénticos
  - trader_cdlinneck — Patrón Formación en el cuello
  - trader_cdlinvertedhammer — Martilllo Invertido
  - trader_cdlkicking — Patada
  - trader_cdlkickingbylength — Patada - alza/baja determinada por el marubozu más largo
  - trader_cdlladderbottom — Suelo de escalera
  - trader_cdllongleggeddoji — Doji Zancudo
  - trader_cdllongline — Vela de Línea Larga
  - trader_cdlmarubozu — Marubozu
  - trader_cdlmatchinglow — Mínimos coincidentes
  - trader_cdlmathold — Mat Hold
  - trader_cdlmorningdojistar — Lucero del Alba Doji
  - trader_cdlmorningstar — Lucero del Alba
  - trader_cdlonneck — Patrón Sobre el cuello
  - trader_cdlpiercing — Patrón penetrante
  - trader_cdlrickshawman — Calesero
  - trader_cdlrisefall3methods — Triple Formación Alcista/Bajista
  - trader_cdlseparatinglines — Lineas Separadas
  - trader_cdlshootingstar — Estrella Fugaz
  - trader_cdlshortline — Vela de Línea Corta
  - trader_cdlspinningtop — Peonza
  - trader_cdlstalledpattern — Patrón Añejo
  - trader_cdlsticksandwich — Bocadillo
  - trader_cdltakuri — Takuri (Libélula Doji con sombra muy larga)
  - trader_cdltasukigap — Hueco Tasuki
  - trader_cdlthrusting — Patrón de empuje
  - trader_cdltristar — Patrón de tres estrellas
  - trader_cdlunique3river — Tres ríos únicos
  - trader_cdlupsidegap2crows — Dos Cuervos tras un Huevo al Alza
  - trader_cdlxsidegap3methods — Métodos de Tres Huevos al Alza/Baja
  - trader_ceil — Redondeo hacia arriba de vectores
  - trader_cmo — Oscilador de momento de Chande
  - trader_correl — Coeficiente de correlación de Pearson (r)
  - trader_cos — Coseno trigonométrico de vectores
  - trader_cosh — Coseno hiperbólico de un vector
  - trader_dema — Media móvil exponencial doble
  - trader_div — División aritmética de vectores
  - trader_dx — Índice de movimiento direccional
  - trader_ema — Media móvil exponencial
  - trader_errno — Obtener el código de error
  - trader_exp — Exponencial aritmética de vectores
  - trader_floor — Redondeo hacia abajo de vectores
  - trader_get_compat — Obtiene el modo de compatibilidad
  - trader_get_unstable_period — Obtiene el periodo inestable
  - trader_ht_dcperiod — Transformación de Hilbert - Período de ciclo dominante
  - trader_ht_dcphase — Transformación de Hilbert - Fase de ciclo dominante
  - trader_ht_phasor — Transformación de Hilbert - Componentes de un fasor
  - trader_ht_sine — Transformación de Hilbert - Sinusoide
  - trader_ht_trendline — Transformación de Hilbert - Línea de tendencia instantánea
  - trader_ht_trendmode — Transformación de Hilbert - Tendencia vs Modo de ciclo
  - trader_kama — Media móvil adaptativa de Kaufman
  - trader_linearreg — Regresión lineal
  - trader_linearreg_angle — Ángulo de regresión lineal
  - trader_linearreg_intercept — Intercepción de regresión lineal
  - trader_linearreg_slope — Pendiente de regresión lineal
  - trader_ln — Logaritmo natural de vectores
  - trader_log10 — Logaritmo en base 10 de vectores
  - trader_ma — Media móvil
  - trader_macd — Convergencia/divergencia de la media móvil
  - trader_macdext — MACD con tipo MA controlable
  - trader_macdfix — Convergencia/divergencia fija 12/26 de la media móvil
  - trader_mama — Media móvil adaptativa MESA
  - trader_mavp — Media móvil con periodo variable
  - trader_max — Valor mayor sobre un periodo especificado
  - trader_maxindex — Índice del valor mayor sobre un periodo especificado
  - trader_medprice — Precio medio
  - trader_mfi — Índice de flujo de dinero
  - trader_midpoint — Punto medio sobre un periodo
  - trader_midprice — Precio de punto medio sobre un periodo
  - trader_min — Valor más bajo sobre un periodo especificado
  - trader_minindex — Índice del valor más bajo sobre un periodo especificado
  - trader_minmax — Valores más altos y bajos sobre un periodo especificado
  - trader_minmaxindex — Índices de los valores más bajos y altos sobre un periodo especificado
  - trader_minus_di — Indicador direccional menos
  - trader_minus_dm — Movimiento direccional menos
  - trader_mom — Momentum
  - trader_mult — Multiplicación aritmética de vectores
  - trader_natr — Rango verdadero de la media normalizada
  - trader_obv — Volumen sobre balance
  - trader_plus_di — Indicador direccional más
  - trader_plus_dm — Movimiento direccional más
  - trader_ppo — Oscilador de precio porcentual
  - trader_roc — Ritmo de cambio : ((precio/precioAnterior)-1)*100
  - trader_rocp — Porcentaje del ritmo de cabio: (precio-precioAnterior)/precioAnterior
  - trader_rocr — Ratio del ritmo de cambio: (precio/precioAnterior)
  - trader_rocr100 — Ratio del ritmo de cambio en escala 100: (precio/precioAnterior)*100
  - trader_rsi — Índice de fuerza relativa
  - trader_sar — Sistema parabólico
  - trader_sarext — Sistema parabólico - Extendido
  - trader_set_compat — Establece el modo de compatibilidad
  - trader_set_unstable_period — Establece el periodo inestable
  - trader_sin — Seno trigonométrico de vectores
  - trader_sinh — Seno hiperbólico de vectores
  - trader_sma — Media móvil simple
  - trader_sqrt — Raíz cuadrada de vectores
  - trader_stddev — Desviación estándar
  - trader_stoch — Estocástico
  - trader_stochf — Estocástico rápido
  - trader_stochrsi — Índice de fuerza relativa estocástica
  - trader_sub — Sustracción artimética de vectores
  - trader_sum — Sumatorio
  - trader_t3 — Media móvil exponencial triple (T3)
  - trader_tan — Tangente trigonométrica de vectores
  - trader_tanh — Tangente hiperbólica trigonométrica de vectores
  - trader_tema — Media móvil exponencial triple
  - trader_trange — Rango verdadero
  - trader_trima — Media móvil triangular
  - trader_trix — Ritmo de cambio de 1 día (RDC) de una MME suave triple
  - trader_tsf — Previsión de series de tiempo
  - trader_typprice — Precio típico
  - trader_ultosc — Oscilador final
  - trader_var — Varianza
  - trader_wclprice — Precio de cierre ponderado
  - trader_willr — %R de Williams
  - trader_wma — Media móvil ponderada

- BC Math — Matemáticas de precisión arbitraria BCMath
  - Instalación/Configuración
  - Funciones de BC Math
  - BcMath\Number — La clase BcMath\Number
- GMP — GNU Multiple Precision
  - Instalación/Configuración
  - Constantes predefinidas
  - Ejemplos
  - Funciones de GMP
  - GMP — La clase GMP
- Math — Funciones matemáticas
  - Constantes predefinidas
  - RoundingMode — La enumeración RoundingMode
  - Funciones Matemáticas
- Estadísticas
  - Instalación/Configuración
  - Funciones estadísticas
- Trader — Análisis técnico para comerciantes
  - Instalación/Configuración
  - Constantes predefinidas
  - Funciones de Trader

# Salida MIME que no es texto

# Formato de formulario

# Introducción

`Forms Data Format` (FDF) es un formato de formulario para documentos PDF. La documentación (en inglés) puede ser leída en » http://www.adobe.com/devnet/acrobat/fdftoolkit.html para más detalles sobre los pormenores.

El espíritu de FDF es similar al de los formularios HTML. Las diferencias radican en los medios de transmisión de los datos al servidor, cuando el botón `"submit"` (enviar) es presionado (lo cual es del ámbito de Form Data Format) y el formato de formulario en sí mismo (que es más bien del ámbito de Portable Document Format, PDF). Gestionar datos FDF es uno de los objetivos de las funciones FDF. Pero hay otros. También es posible tomar un formulario PDF y prellenar los campos sin modificar el formulario en sí. En este caso, se creará un documento FDF (fdf_create()), se llenarán los campos (fdf_set_value()) y se asociará a un fichero PDF (fdf_set_file()). Finalmente, todo será enviado al cliente, con el tipo MIME `application/vnd.fdf`. El módulo `"Acrobat reader"` del navegador reconocerá este tipo MIME y leerá el fichero PDF, luego lo llenará con FDF.

Si se edita un fichero FDF con un editor de texto, se encontrará un catálogo de objetos con el nombre de `FDF`. Este objeto puede contener entradas tales como `Fields`, `F`, `Status` etc. Las entradas más comúnmente utilizadas son `Fields`, que indica una lista de campos de control, y `F` que contiene el nombre del fichero PDF al que pertenecen estos datos. Estas entradas son designadas en la documentación PDF bajo el nombre de /F-Key o /Status-Key. La modificación de estas entradas es posible con las funciones fdf_set_file() y fdf_set_status(). Los campos son modificables con las funciones fdf_set_value(), fdf_set_opt() etc.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Tipos de recursos

## Requerimientos

Se necesitará el SDK de FDF toolkit, disponible en el sitio » http://www.adobe.com/devnet/acrobat/fdftoolkit.html. Desde PHP 4.3.0, se necesitará la versión 5.0 del SDK. La biblioteca FDF toolkit está disponible como una biblioteca compilada, editada por Adobe, en los sistemas operativos Win32, Linux, Solaris y AIX.

## Instalación

Esta extensión es considerada no mantenida y muerta. Sin embargo, el código fuente sigue disponible desde el SVN de PECL aquí: » https://svn.php.net/viewvc/pecl/fdf.

Esta extensión ya no se proporciona con PHP.

> Nota: Si se encuentran problemas durante la configuración de FDF con soporte fdftk, verifique que el fichero de encabezado fdftk.h y la biblioteca libfdftk.so estén en su lugar. El script configure soporta la jerarquía de directorios de la distribución FDF SDK y la organización clásica DIR/include y DIR/lib: por lo tanto, se puede utilizar uno u otro directamente con la distribución descomprimida, o bien incluyendo el fichero de encabezado y la biblioteca apropiada en su sistema, es decir, en /usr/local/include y /usr/local/lib. Solo queda configurar con --with-fdftk=/usr/local.

> Nota: Nota para usuarios Win32
> Para hacer funcionar esta extensión, algunas bibliotecas DLL deben estar disponibles a través del PATH del sistema Windows. Lea la F.A.Q titulada "Cómo agregar mi carpeta PHP a mi PATH de Windows" para más información. Copiar las bibliotecas DLL desde la carpeta PHP a la carpeta del sistema de Windows también funciona (ya que la carpeta del sistema está por defecto en el PATH del sistema), pero este método no es recomendado. Esta extensión requiere que los siguientes archivos estén en el PATH: fdftk.dll

## Tipos de recursos

La mayoría de las funciones FDF requieren un recurso de tipo `fdf` como primer argumento. Un recurso `fdf` es una estructura que representa un fichero FDF abierto. Se pueden crear recursos `fdf` con las funciones fdf_create(), fdf_open() y fdf_open_string().

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

`FDFValue` (int)
`FDFStatus` (int)
`FDFFile` (int)
`FDFID` (int)
`FDFFf` (int)
`FDFSetFf` (int)
`FDFClearFf` (int)
`FDFFlags` (int)
`FDFSetF` (int)
`FDFClrF` (int)
`FDFAP` (int)
`FDFAS` (int)
`FDFAction` (int)
`FDFAA` (int)
`FDFAPRef` (int)
`FDFIF` (int)
`FDFEnter` (int)
`FDFExit` (int)
`FDFDown` (int)
`FDFUp` (int)
`FDFFormat` (int)
`FDFValidate` (int)
`FDFKeystroke` (int)
`FDFCalculate` (int)
`FDFNormalAP` (int)
`FDFRolloverAP` (int)
`FDFDownAP` (int)

# Ejemplos

Los siguientes ejemplos muestran cómo evaluar los datos del formulario.

Ejemplo #1 Evaluar un documento FDF

    <?php
    // Abrir un fichero FDF desde una string proporcionada por la extensión PDF
    // El formulario PDF contiene varios campos de texto con los nombres
    // volume, date, comment, publisher, preparer y dos casillas de verificación
    // show_publisher y show_preparer.
    $fdf = fdf_open_string($HTTP_FDF_DATA);
    $volume = fdf_get_value($fdf, "volume");
    echo 'El campo Volume contiene el valor: "<strong>' . $volume . '</strong>"<br />';

    $date = fdf_get_value($fdf, "date");
    echo 'El valor del campo date era "<strong>' . $date . '</strong>"<br />';

    $comment = fdf_get_value($fdf, "comment");
    echo 'El valor del campo comment era "<strong>' . $comment . '</strong>"<br />';

    if (fdf_get_value($fdf, "show_publisher") == "On") {
      $publisher = fdf_get_value($fdf, "publisher");
      echo "El valor del campo Publisher era: '<strong>" . $publisher . "</strong><br />";
    } else
      echo 'El valor del campo Publisher no debe ser mostrado.<br />';

    if (fdf_get_value($fdf, "show_preparer") == "On") {
      $preparer = fdf_get_value($fdf, "preparer");
      echo 'El valor del campo Preparer era "<strong>' . $preparer . '</strong>"<br />';
    } else
      echo 'El valor del campo Preparer no debe ser mostrado.<br />';
    fdf_close($fdf);
    ?>

# Funciones FDF

# fdf_add_doc_javascript

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_add_doc_javascript — Añade código javascript a un documento FDF

### Descripción

function fdf_add_doc_javascript(resource `$fdf_document`, string `$script_name`, string `$script_code`): bool

Añade el código javascript `script_code` al documento `fdfdoc`, que Acrobat añadirá a los scripts de nivel de documento, una vez importado el FDF.

### Parámetros

`fdf_document`
  El gestor de documento FDF, devuelto por la función fdf_create(), la función fdf_open() o la función fdf_open_string().
`script_name`
  El nombre del script.
`script_code`
  El código del script. Se recomienda encarecidamente utilizar '\r' como separador de líneas en el código `script_code`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Adición de código JavaScript a un documento FDF

    <?php
    $fdf = fdf_create();
    fdf_add_doc_javascript($fdf, "PlusOne", "function PlusOne(x)\r{\r  return x+1;\r}\r");
    fdf_save($fdf);
    ?>

Este ejemplo creará un documento FDF como el siguiente:

    %FDF-1.2
    %âãÏÓ
    1 0 obj
    <<
    /FDF << /JavaScript << /Doc [ (PlusOne)(function PlusOne\(x\)\r{\r  return x+1;\r}\r)] >> >>
    >>
    endobj
    trailer
    <<
    /Root 1 0 R

    >>
    %%EOF

# fdf_add_template

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_add_template — Añade una plantilla en el documento FDF

### Descripción

function fdf_add_template(
resource `$fdf_document`,
int `$newpage`,
string `$filename`,
string `$template`,
int `$rename`
): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

# fdf_close

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_close — Cierra un documento FDF

### Descripción

function fdf_close(resource `$fdf_document`): void

Cierra el documento FDF.

### Parámetros

`fdf_document`
  El gestor de documento FDF, devuelto por la función fdf_create(), la función fdf_open() o la función fdf_open_string().

### Valores devueltos

No se retorna ningún valor.

### Ver también

- fdf_open() - Abre un documento FDF

# fdf_create

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_create — Crea un nuevo documento FDF

### Descripción

function fdf_create(): resource

Crea un nuevo documento FDF.

Esta función es necesaria para aquellos que desean prellenar los campos de un formulario en un fichero PDF.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un gestor de documento FDF, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Prellemar un formulario PDF

    <?php
    $outfdf = fdf_create();
    fdf_set_value($outfdf, "volume", $volume, 0);

    fdf_set_file($outfdf, "http:/testfdf/resultlabel.pdf");
    fdf_save($outfdf, "outtest.fdf");
    fdf_close($outfdf);
    Header("Content-type: application/vnd.fdf");
    $fp = fopen("outtest.fdf", "r");
    fpassthru($fp);
    unlink("outtest.fdf");
    ?>

### Ver también

- fdf_close() - Cierra un documento FDF
- fdf_save() - Guarda un documento FDF
- fdf_open() - Abre un documento FDF

# fdf_enum_values

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_enum_values — Llama a una función de usuario para cada valor FDF

### Descripción

function fdf_enum_values(resource `$fdf_document`, callable `$function`, mixed `$userdata` = ?): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

# fdf_errno

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_errno — Devuelve el código de error de la última operación FDF

### Descripción

function fdf_errno(): int

Recupera el código de error de la última operación FDF.

Un mensaje de error es accesible a través de la función fdf_error().

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve el código de error en forma de int o `0` si no ha ocurrido ningún error.

### Ver también

- fdf_error() - Devuelve el mensaje de error FDF

# fdf_error

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_error — Devuelve el mensaje de error FDF

### Descripción

function fdf_error(int `$error_code` = -1): string

Devuelve el mensaje de error FDF.

### Parámetros

`error_code`
  Un código de error obtenido con la función fdf_errno(). Si no se proporciona, esta función utiliza el código de error interno definido por la última operación.

### Valores devueltos

Devuelve el mensaje de error en forma de un string o la cadena `no error` si no hay ninguno.

### Ver también

- fdf_errno() - Devuelve el código de error de la última operación FDF

# fdf_get_ap

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_ap — Lee la apariencia de un campo

### Descripción

function fdf_get_ap(
resource `$fdf_document`,
string `$field`,
int `$face`,
string `$filename`
): bool

Lee la apariencia del campo `field` (es decir, el valor de la clave /AP) y la almacena en el fichero `filename`.

### Parámetros

`fdf_document`
  El gestor de documento FDF, devuelto por la función fdf_create(), la función fdf_open() o la función fdf_open_string().
`field`
`face`
  Los valores posibles son `FDFNormalAP`, `FDFRolloverAP` y `FDFDownAP`.
`filename`
  La apariencia será almacenada en este parámetro.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# fdf_get_attachment

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_attachment — Extrae un fichero integrado en un documento FDF

### Descripción

function fdf_get_attachment(resource `$fdf_document`, string `$fieldname`, string `$savepath`): array

Extrae el fichero `fieldname` subido a través del campo `"file selection"`, luego lo almacena en el fichero `savepath`.

### Parámetros

`fdf_document`
  El gestor de documento FDF, devuelto por la función fdf_create(), la función fdf_open() o la función fdf_open_string().
`fieldname`
`savepath`
  Puede ser el nombre de un fichero o bien un directorio en el cual el fichero subido será creado bajo su nombre original. Cualquier fichero ya existente con el mismo nombre será sobrescrito.

  > Nota: Parece que no hay otra manera de conocer el nombre del fichero subido que almacenarlo en un directorio con `savepath` y luego leer su nombre en el directorio.

### Valores devueltos

El array devuelto contiene los siguientes campos:

- `path` - ruta de almacenamiento del directorio
- `size` - tamaño del fichero almacenado en bytes
- `type` - Tipo MIME del fichero, si fue proporcionado en el documento FDF

### Ejemplos

Ejemplo #1 Almacenamiento de un fichero subido

    <?php
    $fdf = fdf_open_string($HTTP_FDF_DATA);
    $data = fdf_get_attachment($fdf, "filename", "/tmpdir");
    echo "El fichero subido es almacenado en $data[path]";
    ?>

# fdf_get_encoding

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_encoding — Lee el valor de la clave /Encoding

### Descripción

function fdf_get_encoding(resource `$fdf_document`): string

Recupera el valor de la clave `/Encoding`.

### Parámetros

`fdf_document`
  El gestor de documento FDF, devuelto por la función fdf_create(), la función fdf_open() o la función fdf_open_string().

### Valores devueltos

Devuelve la codificación, en forma de un string. Una cadena vacía es devuelta si el esquema `PDFDocEncoding/Unicode` es utilizado.

### Ver también

- fdf_set_encoding() - Modifica la codificación de caracteres

# fdf_get_file

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_file — Lee el valor de la clave /F

### Descripción

function fdf_get_file(resource `$fdf_document`): string

Lee el valor de la clave `/F`.

### Parámetros

`fdf_document`
  El gestor de documento FDF, devuelto por la función fdf_create(), la función fdf_open() o la función fdf_open_string().

### Valores devueltos

Devuelve el valor de la clave, en forma de string.

### Ver también

- fdf_set_file() - Crea un documento PDF para mostrar datos FDF

# fdf_get_flags

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_flags — Lee los atributos de un campo FDF

### Descripción

function fdf_get_flags(resource `$fdf_document`, string `$fieldname`, int `$whichflags`): int
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

# fdf_get_opt

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECLv)

fdf_get_opt — Lee un valor en un array de valores de un campo FDF

### Descripción

function fdf_get_opt(resource `$fdf_document`, string `$fieldname`, int `$element` = -1): mixed
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

# fdf_get_status

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_status — Lee el valor de la clave /STATUS

### Descripción

function fdf_get_status(resource `$fdf_document`): string

Lee el valor de la clave `/STATUS`.

### Parámetros

`fdf_document`
  El gestor de documento FDF, devuelto por la función fdf_create(), la función fdf_open() o la función fdf_open_string().

### Valores devueltos

Devuelve el valor de la clave, en forma de string.

### Ver también

- fdf_set_status() - Establece el valor de la clave /STATUS

# fdf_get_value

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_value — Devuelve el valor de un campo FDF

### Descripción

function fdf_get_value(resource `$fdf_document`, string `$fieldname`, int `$which` = -1): mixed

Devuelve el valor de un campo FDF.

### Parámetros

`fdf_document`
  El gestor de documento FDF, devuelto por la función fdf_create(), la función fdf_open() o la función fdf_open_string().
`fieldname`
  Nombre del campo FDF, en forma de string.
`which`
  Los elementos de un campo array pueden ser leídos proporcionando este argumento opcional, en forma de un entero cuyo valor mínimo será `0`. Para los campos que no son arrays, este argumento opcional será ignorado.

### Valores devueltos

Devuelve el valor del campo.

### Ver también

- fdf_set_value() - Modifica el valor de un campo FDF

# fdf_get_version

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_version — Lee el número de versión de la API FDF

### Descripción

function fdf_get_version(resource `$fdf_document` = ?): string

Devuelve el número de versión FDF para el documento `fdf_document`, para la API si no se proporciona ningún argumento.

### Parámetros

`fdf_document`
  El gestor de documento, devuelto por la función fdf_create(), la función fdf_open() o la función fdf_open_string().

### Valores devueltos

Devuelve la versión, en forma de string. Para la versión actual del FDF toolkit 5.0, el número de versión es `5.0` y el número de versión del documento es `1.2`, `1.3` o `1.4`.

### Ver también

- fdf_set_version() - Modifica el número de versión del fichero FDF

# fdf_header

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVNf)

fdf_header — Emite las cabeceras HTTP específicas de FDF

### Descripción

function fdf_header(): void

fdf_header() es una función de conveniencia, para emitir las cabeceras HTTP específicas de FDF. Permite enviar el tipo `Content-type:` con el valor `application/vnd.fdf`.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

No se retorna ningún valor.

# fdf_next_field_name

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_next_field_name — Lee el nombre del siguiente campo FDF

### Descripción

function fdf_next_field_name(resource `$fdf_document`, string `$fieldname` = ?): string

Lee el nombre del siguiente campo FDF. Este nombre podrá ser utilizado en varias funciones.

### Parámetros

`fdf_document`
  El gestor de documento FDF, devuelto por la función fdf_create(), la función fdf_open() o la función fdf_open_string().
`fieldname`
  Nombre del campo FDF, en forma de string. Si no se proporciona, se devolverá el primer campo.

### Valores devueltos

Devuelve el nombre del campo, en forma de string.

### Ejemplos

Ejemplo #1 Detectar todos los nombres de un formulario FDF

    <?php
    $fdf = fdf_open($HTTP_FDF_DATA);
    for ($field = fdf_next_field_name($fdf);
        $field != "";
        $field = fdf_next_field_name($fdf, $field)) {
        echo "campo: $field\n";
    }
    ?>

### Ver también

- fdf_get_value() - Devuelve el valor de un campo FDF

# fdf_open

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_open — Abre un documento FDF

### Descripción

function fdf_open(string `$filename`): resource

Abre un documento FDF.

Asimismo, se puede utilizar la función fdf_open_string() para procesar el resultado de un formulario PDF enviado mediante un método POST.

### Parámetros

`filename`
  Ruta hacia el fichero FDF. Este fichero debe contener los datos tal como son devueltos por un formulario PDF o creados utilizando las funciones fdf_create() y fdf_save().

### Valores devueltos

Devuelve un gestor de documento FDF, o `false` en caso de error.

### Ejemplos

Ejemplo #1 Acceder a los datos del formulario

    <?php
    // Guarda el fichero FDF en un fichero temporal.
    $fdffp = fopen("test.fdf", "w");
    fwrite($fdffp, $HTTP_FDF_DATA, strlen($HTTP_FDF_DATA));
    fclose($fdffp);

    // Abre el fichero temporal y utiliza los datos.
    $fdf = fdf_open("test.fdf");
    /* ... */
    fdf_close($fdf);
    ?>

### Ver también

- fdf_open_string() - Lee un documento FDF a partir de un string
- fdf_close() - Cierra un documento FDF
- fdf_create() - Crea un nuevo documento FDF
- fdf_save() - Guarda un documento FDF

# fdf_open_string

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_open_string — Lee un documento FDF a partir de un string

### Descripción

function fdf_open_string(string `$fdf_data`): resource

Lee un documento FDF a partir de un string.

Se puede utilizar fdf_open_string() con la variable $HTTP_FDF_DATA para procesar datos de formularios provenientes de clientes remotos.

### Parámetros

`fdf_data`
  Los datos, como devueltos desde un formulario PDF o creados utilizando las funciones fdf_create() y fdf_save_string().

### Valores devueltos

Devuelve un gestor de documento FDF, o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Acceso a los datos de formulario FDF

    <?php
    $fdf = fdf_open_string($HTTP_FDF_DATA);
    /* ... */
    fdf_close($fdf);
    ?>

### Ver también

- fdf_open() - Abre un documento FDF
- fdf_close() - Cierra un documento FDF
- fdf_create() - Crea un nuevo documento FDF
- fdf_save_string() - Devuelve un documento FDF en forma de string

# fdf_remove_item

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_remove_item — Configura el marco FDF de destino para el formulario

### Descripción

function fdf_remove_item(resource `$fdf_document`, string `$fieldname`, int `$item`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

# fdf_save

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_save — Guarda un documento FDF

### Descripción

function fdf_save(resource `$fdf_document`, string `$filename` = ?): bool

Guarda un documento FDF.

### Parámetros

`fdf_document`
  El gestor de documento FDF, devuelto por la función fdf_create(), la función fdf_open() o la función fdf_open_string().
`filename`
  Si se proporciona, el FDF resultante será escrito en este parámetro. De lo contrario, esta función escribirá el FDF en la salida estándar de PHP.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- fdf_close() - Cierra un documento FDF
- fdf_create() - Crea un nuevo documento FDF
- fdf_save_string() - Devuelve un documento FDF en forma de string

# fdf_save_string

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_save_string — Devuelve un documento FDF en forma de string

### Descripción

function fdf_save_string(resource `$fdf_document`): string

Devuelve un documento FDF en forma de string.

### Parámetros

`fdf_document`
  El gestor de documento FDF, devuelto por la función fdf_create(), la función fdf_open() o la función fdf_open_string().

### Valores devueltos

Devuelve el documento, en forma de string, o `false` en caso de error.

### Ejemplos

Ejemplo #1 Leer un documento FDF en forma de string

    <?php
    $fdf = fdf_create();
    fdf_set_value($fdf, "foo", "bar");
    $str = fdf_save_string($fdf);
    fdf_close($fdf);
    echo $str;
    ?>

El ejemplo anterior mostrará:

    %FDF-1.2
    %âãÏÓ
    1 0 obj
    <<
    /FDF << /Fields 2 0 R >>
    >>
    endobj
    2 0 obj
    [
    << /T (foo)/V (bar)>>
    ]
    endobj
    trailer
    <<
    /Root 1 0 R

    >>
    %%EOF

### Ver también

- fdf_open_string() - Lee un documento FDF a partir de un string
- fdf_close() - Cierra un documento FDF
- fdf_create() - Crea un nuevo documento FDF
- fdf_save() - Guarda un documento FDF

# fdf_set_ap

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_ap — Fija la apariencia de un campo FDF

### Descripción

function fdf_set_ap(
resource `$fdf_document`,
string `$field_name`,
int `$face`,
string `$filename`,
int `$page_number`
): bool

Fija la apariencia de un campo FDF (es decir, el valor de la clave `/AP`).

### Parámetros

`fdf_document`
  El gestor de documento FDF, devuelto por la función fdf_create(), la función fdf_open() o la función fdf_open_string().
`field_name`
`face`
  Los valores posibles son: `FDFNormalAP`, `FDFRolloverAP` y `FDFDownAP`.
`filename`
`page_number`

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# fdf_set_encoding

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_encoding — Modifica la codificación de caracteres

### Descripción

function fdf_set_encoding(resource `$fdf_document`, string `$encoding`): bool

Modifica la codificación de caracteres del documento FDF.

### Parámetros

`fdf_document`
  El gestor de documento FDF, devuelto por la función fdf_create(), la función fdf_open() o la función fdf_open_string().
`encoding`
  El nombre de la codificación. Los siguientes valores son soportados: "`Shift-JIS`", "`UHC`", "`GBK`" y "`BigFive`". Un string vacío reemplaza el valor por omisión de la codificación al esquema `PDFDocEncoding/Unicode`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# fdf_set_file

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_file — Crea un documento PDF para mostrar datos FDF

### Descripción

function fdf_set_file(resource `$fdf_document`, string `$url`, string `$target_frame` = ?): bool

Crea un documento PDF para mostrar datos FDF.

### Parámetros

`fdf_document`
  El gestor de documento FDF, devuelto por la función fdf_create(), la función fdf_open() o la función fdf_open_string().
`url`
  Debe ser proporcionado en forma de URL absoluta.
`target_frame`
  Utilice este parámetro para especificar la frame en la que se mostrará el documento. También es posible definir el valor por omisión de este parámetro utilizando la función fdf_set_target_frame().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Pasar datos FDF a un segundo formulario

    <?php
    /* Configura el encabezado para Adobe FDF */
    fdf_header();

    /* Inicia un nuevo fichero FDF */
    $fdf = fdf_create();

    /* Asigna al campo "foo" el valor de "bar" */
    fdf_set_value($fdf, "foo", "bar");

    /* Indica al cliente que muestre los datos FDF con "fdf_form.pdf" */
    fdf_set_file($fdf, "http://www.example.com/fdf_form.pdf");

    /* Muestra el FDF */
    fdf_save($fdf);

    /* Limpia */
    fdf_close($fdf);
    ?>

### Ver también

- fdf_get_file() - Lee el valor de la clave /F
- fdf_set_target_frame() - Configura el marco de destino para la visualización del formulario

# fdf_set_flags

(PHP 4 >= 4.0.2, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_flags — Modifica una opción de un campo

### Descripción

function fdf_set_flags(
resource `$fdf_document`,
string `$fieldname`,
int `$whichFlags`,
int `$newFlags`
): bool

Modifica una opción de un campo.

### Parámetros

`fdf_document`
  El gestor de documento FDF, devuelto por la función fdf_create(), la función fdf_open() o la función fdf_open_string().
`fieldname`
  Nombre del campo FDF, en forma de string.
`whichFlags`
`newFlags`

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- fdf_set_opt() - Modifica una opción de un campo

# fdf_set_javascript_action

(PHP 4 >= 4.0.2, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_javascript_action — Modifica la acción javascript de un campo

### Descripción

function fdf_set_javascript_action(
resource `$fdf_document`,
string `$fieldname`,
int `$trigger`,
string `$script`
): bool

Modifica la acción javascript de un campo dado.

### Parámetros

`fdf_document`
  El gestor de documento FDF, devuelto por la función fdf_create(), la función fdf_open() o la función fdf_open_string().
`fieldname`
  Nombre del campo FDF, en forma de string.
`trigger`
`script`

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- fdf_set_submit_form_action() - Modifica la acción de un formulario

# fdf_set_on_import_javascript

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_on_import_javascript — Añade código Javascript para ser ejecutado cuando Acrobat abre un FDF

### Descripción

function fdf_set_on_import_javascript(resource `$fdf_document`, string `$script`, bool `$before_data_import`): bool
Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Ver también

- fdf_add_doc_javascript() - Añade código javascript a un documento FDF
- fdf_set_javascript_action() - Modifica la acción javascript de un campo

# fdf_set_opt

(PHP 4 >= 4.0.2, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_opt — Modifica una opción de un campo

### Descripción

function fdf_set_opt(
resource `$fdf_document`,
string `$fieldname`,
int `$element`,
string `$str1`,
string `$str2`
): bool

Modifica una opción de un campo dado.

### Parámetros

`fdf_document`
  El gestor de documento FDF, devuelto por la función fdf_create(), la función fdf_open() o la función fdf_open_string().
`fieldname`
  Nombre del campo FDF, en forma de string.
`element`
`str1`
`str2`

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- fdf_set_flags() - Modifica una opción de un campo

# fdf_set_status

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_status — Establece el valor de la clave /STATUS

### Descripción

function fdf_set_status(resource `$fdf_document`, string `$status`): bool

Establece el valor de la clave `/STATUS`. Cuando un cliente recibe un FDF con un estado establecido, su valor se presentará en una caja de alerta.

### Parámetros

`fdf_document`
  El gestor de documento FDF, devuelto por la función fdf_create(), la función fdf_open() o la función fdf_open_string().
`status`

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- fdf_get_status() - Lee el valor de la clave /STATUS

# fdf_set_submit_form_action

(PHP 4 >= 4.0.2, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_submit_form_action — Modifica la acción de un formulario

### Descripción

function fdf_set_submit_form_action(
resource `$fdf_document`,
string `$fieldname`,
int `$trigger`,
string `$script`,
int `$flags`
): bool

Modifica la acción de un formulario.

### Parámetros

`fdf_document`
  El gestor de documento, devuelto por la función fdf_create(), la función fdf_open() o la función fdf_open_string().
`fieldname`
  Nombre del campo FDF, en forma de string.
`trigger`
`script`
`flags`

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- fdf_set_javascript_action() - Modifica la acción javascript de un campo

# fdf_set_target_frame

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_target_frame — Configura el marco de destino para la visualización del formulario

### Descripción

function fdf_set_target_frame(resource `$fdf_document`, string `$frame_name`): bool

Configura el marco de destino para la visualización del resultado PDF definido por fdf_save_file().

### Parámetros

`fdf_document`
  El gestor de documento FDF, devuelto por la función fdf_create(), la función fdf_open() o la función fdf_open_string().
`frame_name`
  El nombre del marco, en forma de string.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- fdf_save_file()

# fdf_set_value

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_value — Modifica el valor de un campo FDF

### Descripción

function fdf_set_value(
resource `$fdf_document`,
string `$fieldname`,
mixed `$value`,
int `$isName` = ?
): bool

Modifica el valor de un campo FDF.

### Parámetros

`fdf_document`
  El gestor de documento FDF, devuelto por la función fdf_create(), la función fdf_open() o la función fdf_open_string().
`fieldname`
  Nombre del campo FDF, en forma de string.
`value`
  Este parámetro debe ser almacenado como un string incluso si es un array. En este caso, todos los elementos del array serán almacenados como un array de valores.
`isName`

  > Nota: En versiones anteriores de la suite FDF, el último parámetro determinaba si el valor del campo debía ser convertido en un nombre PDF (`isname` = 1) o posicionado como un string (`isname` = 0). El valor ya no está en la suite actual, versión 5.0. Por razones de compatibilidad, esto sigue siendo soportado como un parámetro opcional, pero ignorado internamente.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- fdf_get_value() - Devuelve el valor de un campo FDF
- fdf_remove_item() - Configura el marco FDF de destino para el formulario

# fdf_set_version

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_version — Modifica el número de versión del fichero FDF

### Descripción

function fdf_set_version(resource `$fdf_document`, string `$version`): bool

Modifica el número de versión del documento FDF actual.

Algunas funcionalidades soportadas por esta extensión solo están disponibles para las nuevas versiones de FDF.

### Parámetros

`fdf_document`
  El gestor de documento FDF, devuelto por la función fdf_create(), la función fdf_open() o la función fdf_open_string().
`version`
  El número de versión. Para el toolkit FDF actual, puede ser `1.2`, `1.3` o `1.4`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- fdf_get_version() - Lee el número de versión de la API FDF

## Tabla de contenidos

- fdf_add_doc_javascript — Añade código javascript a un documento FDF
- fdf_add_template — Añade una plantilla en el documento FDF
- fdf_close — Cierra un documento FDF
- fdf_create — Crea un nuevo documento FDF
- fdf_enum_values — Llama a una función de usuario para cada valor FDF
- fdf_errno — Devuelve el código de error de la última operación FDF
- fdf_error — Devuelve el mensaje de error FDF
- fdf_get_ap — Lee la apariencia de un campo
- fdf_get_attachment — Extrae un fichero integrado en un documento FDF
- fdf_get_encoding — Lee el valor de la clave /Encoding
- fdf_get_file — Lee el valor de la clave /F
- fdf_get_flags — Lee los atributos de un campo FDF
- fdf_get_opt — Lee un valor en un array de valores de un campo FDF
- fdf_get_status — Lee el valor de la clave /STATUS
- fdf_get_value — Devuelve el valor de un campo FDF
- fdf_get_version — Lee el número de versión de la API FDF
- fdf_header — Emite las cabeceras HTTP específicas de FDF
- fdf_next_field_name — Lee el nombre del siguiente campo FDF
- fdf_open — Abre un documento FDF
- fdf_open_string — Lee un documento FDF a partir de un string
- fdf_remove_item — Configura el marco FDF de destino para el formulario
- fdf_save — Guarda un documento FDF
- fdf_save_string — Devuelve un documento FDF en forma de string
- fdf_set_ap — Fija la apariencia de un campo FDF
- fdf_set_encoding — Modifica la codificación de caracteres
- fdf_set_file — Crea un documento PDF para mostrar datos FDF
- fdf_set_flags — Modifica una opción de un campo
- fdf_set_javascript_action — Modifica la acción javascript de un campo
- fdf_set_on_import_javascript — Añade código Javascript para ser ejecutado cuando Acrobat abre un FDF
- fdf_set_opt — Modifica una opción de un campo
- fdf_set_status — Establece el valor de la clave /STATUS
- fdf_set_submit_form_action — Modifica la acción de un formulario
- fdf_set_target_frame — Configura el marco de destino para la visualización del formulario
- fdf_set_value — Modifica el valor de un campo FDF
- fdf_set_version — Modifica el número de versión del fichero FDF

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Tipos de recursos
- Constantes predefinidas
- Ejemplos
- Funciones FDF
  - fdf_add_doc_javascript — Añade código javascript a un documento FDF
  - fdf_add_template — Añade una plantilla en el documento FDF
  - fdf_close — Cierra un documento FDF
  - fdf_create — Crea un nuevo documento FDF
  - fdf_enum_values — Llama a una función de usuario para cada valor FDF
  - fdf_errno — Devuelve el código de error de la última operación FDF
  - fdf_error — Devuelve el mensaje de error FDF
  - fdf_get_ap — Lee la apariencia de un campo
  - fdf_get_attachment — Extrae un fichero integrado en un documento FDF
  - fdf_get_encoding — Lee el valor de la clave /Encoding
  - fdf_get_file — Lee el valor de la clave /F
  - fdf_get_flags — Lee los atributos de un campo FDF
  - fdf_get_opt — Lee un valor en un array de valores de un campo FDF
  - fdf_get_status — Lee el valor de la clave /STATUS
  - fdf_get_value — Devuelve el valor de un campo FDF
  - fdf_get_version — Lee el número de versión de la API FDF
  - fdf_header — Emite las cabeceras HTTP específicas de FDF
  - fdf_next_field_name — Lee el nombre del siguiente campo FDF
  - fdf_open — Abre un documento FDF
  - fdf_open_string — Lee un documento FDF a partir de un string
  - fdf_remove_item — Configura el marco FDF de destino para el formulario
  - fdf_save — Guarda un documento FDF
  - fdf_save_string — Devuelve un documento FDF en forma de string
  - fdf_set_ap — Fija la apariencia de un campo FDF
  - fdf_set_encoding — Modifica la codificación de caracteres
  - fdf_set_file — Crea un documento PDF para mostrar datos FDF
  - fdf_set_flags — Modifica una opción de un campo
  - fdf_set_javascript_action — Modifica la acción javascript de un campo
  - fdf_set_on_import_javascript — Añade código Javascript para ser ejecutado cuando Acrobat abre un FDF
  - fdf_set_opt — Modifica una opción de un campo
  - fdf_set_status — Establece el valor de la clave /STATUS
  - fdf_set_submit_form_action — Modifica la acción de un formulario
  - fdf_set_target_frame — Configura el marco de destino para la visualización del formulario
  - fdf_set_value — Modifica el valor de un campo FDF
  - fdf_set_version — Modifica el número de versión del fichero FDF

# GNU PG

# Introducción

Este módulo permite interactuar con » gnupg.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación

## Requerimientos

Esta extensión requiere la » biblioteca gpgme.

## Instalación

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/gnupg.

# Constantes predefinidas

`GNUPG_SIG_MODE_NORMAL` (int)
`GNUPG_SIG_MODE_DETACH` (int)
`GNUPG_SIG_MODE_CLEAR` (int)
`GNUPG_VALIDITY_UNKNOWN` (int)
`GNUPG_VALIDITY_UNDEFINED` (int)
`GNUPG_VALIDITY_NEVER` (int)
`GNUPG_VALIDITY_MARGINAL` (int)
`GNUPG_VALIDITY_FULL` (int)
`GNUPG_VALIDITY_ULTIMATE` (int)
`GNUPG_PROTOCOL_OpenPGP` (int)
`GNUPG_PROTOCOL_CMS` (int)
`GNUPG_SIGSUM_VALID` (int)
`GNUPG_SIGSUM_GREEN` (int)
`GNUPG_SIGSUM_RED` (int)
`GNUPG_SIGSUM_KEY_REVOKED` (int)
`GNUPG_SIGSUM_KEY_EXPIRED` (int)
`GNUPG_SIGSUM_KEY_MISSING` (int)
`GNUPG_SIGSUM_SIG_EXPIRED` (int)
`GNUPG_SIGSUM_CRL_MISSING` (int)
`GNUPG_SIGSUM_CRL_TOO_OLD` (int)
`GNUPG_SIGSUM_BAD_POLICY` (int)
`GNUPG_SIGSUM_SYS_ERROR` (int)
`GNUPG_ERROR_WARNING` (int)
`GNUPG_ERROR_EXCEPTION` (int)
`GNUPG_ERROR_SILENT` (int)

# Ejemplos

## Tabla de contenidos

- Firma de texto (clearsign)

## Firma de texto (clearsign)

Ejemplo que firma un texto dado.

Ejemplo #1 Ejemplo de firma (clearsign) gnupg mediante funciones

    <?php
    // Inicializamos gnupg
    $res = gnupg_init();
    // Esto realmente no es necesario, clearsign es el valor por defecto
    gnupg_setsignmode($res,GNUPG_SIG_MODE_CLEAR);
    // Añade clave con la contraseña 'test' para firmar
    gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    // Firma
    $signed = gnupg_sign($res,"just a test");
    echo $signed;
    ?>

Ejemplo #2 Ejemplo de firma gnupg (clearsign) mediante orientación a objetos

    <?php
    // Instanciamos la clase
    $gnupg = new gnupg();
    // Esto realmente no es necesario, clearsign es el valor por defecto
    $gnupg->setsignmode(gnupg::SIG_MODE_CLEAR);
    // Añade clave con la contraseña 'test' para firmar
    $gnupg->addsignkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    // Firma
    $signed = $gnupg->sign("just a test");
    echo $signed;
    ?>

Ejemplo #3 keylistiterator

Esta extensión trae también un Iterator para un juego de claves

    <?php
    // Crea un nuevo Iterator para listar todas las claves públicas que coinciden
    // con 'example'
    $iterator = new gnupg_keylistiterator("example");
    foreach($iterator as $fingerprint => $userid){
        echo $fingerprint." -> ".$userid."\n";
    }
    ?>

# Funciones GnuPG

# Notas

Esta extensión utiliza el trousseau del usuario actual. Este trousseau se encuentra normalmente en ~/.gnupg/. Para especificar una ubicación diferente, registrar la ruta del trousseau en la variable de entorno GNUPGHOME. Ver putenv para más información sobre cómo realizar esto.

Algunas funciones requieren la especificación de una clave. Esta especificación puede ser algo que haga referencia a una clave única (userid, key-id, fingerprint, ...). Esta documentación utiliza los fingerprint en todos los ejemplos.

> Nota: Como alternativa a las funciones que utilizan explícitamente los resource, también puede utilizarse un estilo orientado a objetos mediante objetos gnupg.

# gnupg_adddecryptkey

(PECL gnupg >= 0.5)

gnupg_adddecryptkey — Añade una clave para descifrado

### Descripción

function gnupg_adddecryptkey(resource `$identifier`, string `$fingerprint`, string `$passphrase`): bool

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.
`fingerprint`
  La huella de la clave.
`passphrase`
  La frase de contraseña (similar a la contraseña, pero más larga).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con gnupg_adddecryptkey() (Estilo procedimental)

    <?php
    $res = gnupg_init();
    gnupg_adddecryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    ?>

Ejemplo #2 Ejemplo con gnupg_adddecryptkey() (Estilo orientado a objetos)

    <?php
    $gpg = new gnupg();
    $gpg->adddecryptkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    ?>

# gnupg_addencryptkey

(PECL gnupg >= 0.5)

gnupg_addencryptkey — Añade una clave para cifrado

### Descripción

function gnupg_addencryptkey(resource `$identifier`, string `$fingerprint`): bool

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.
`fingerprint`
  La huella de la clave.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con gnupg_addencryptkey() (Estilo procedimental)

    <?php
    $res = gnupg_init();
    gnupg_addencryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC");
    ?>

Ejemplo #2 Ejemplo con gnupg_addencryptkey() (Estilo orientado a objetos)

    <?php
    $gpg = new gnupg();
    $gpg->addencryptkey("8660281B6051D071D94B5B230549F9DC851566DC");
    ?>

# gnupg_addsignkey

(PECL gnupg >= 0.5)

gnupg_addsignkey — Añade una clave para firmar

### Descripción

function gnupg_addsignkey(resource `$identifier`, string `$fingerprint`, string `$passphrase` = ?): bool

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.
`fingerprint`
  La huella de la clave.
`passphrase`
  La frase de contraseña (similar a la contraseña, pero más larga).

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con gnupg_addsignkey() (Estilo procedimental)

    <?php
    $res = gnupg_init();
    gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    ?>

Ejemplo #2 Ejemplo con gnupg_addsignkey() (Estilo orientado a objetos)

    <?php
    $gpg = new gnupg();
    $gpg->addsignkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    ?>

# gnupg_cleardecryptkeys

(PECL gnupg >= 0.5)

gnupg_cleardecryptkeys — Elimina todas las claves que fueron fijadas para el descifrado anteriormente

### Descripción

function gnupg_cleardecryptkeys(resource `$identifier`): bool

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con gnupg_cleardecryptkeys() (Estilo procedimental)

    <?php
    $res = gnupg_init();
    gnupg_cleardecryptkeys($res);
    ?>

Ejemplo #2 Ejemplo con gnupg_cleardecryptkeys() (Estilo orientado a objetos)

    <?php
    $gpg = new gnupg();
    $gpg->cleardecryptkeys();
    ?>

# gnupg_clearencryptkeys

(PECL gnupg >= 0.5)

gnupg_clearencryptkeys — Elimina todas las claves que fueron establecidas para cifrado con anterioridad

### Descripción

function gnupg_clearencryptkeys(resource `$identifier`): bool

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con gnupg_clearencryptkeys() (Estilo procedimental)

    <?php
    $res = gnupg_init();
    gnupg_clearencryptkeys($res);
    ?>

Ejemplo #2 Ejemplo con gnupg_clearencryptkeys() (Estilo orientado a objetos)

    <?php
    $gpg = new gnupg();
    $gpg->clearencryptkeys();
    ?>

# gnupg_clearsignkeys

(PECL gnupg >= 0.5)

gnupg_clearsignkeys — Elimina todas las claves que fueron fijadas para firma previamente

### Descripción

function gnupg_clearsignkeys(resource `$identifier`): bool

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con gnupg_clearsignkeys() (Estilo procedimental)

    <?php
    $res = gnupg_init();
    gnupg_clearsignkeys($res);
    ?>

Ejemplo #2 Ejemplo con gnupg_clearsignkeys() (Estilo orientado a objetos)

    <?php
    $gpg = new gnupg();
    $gpg->clearsignkeys();
    ?>

# gnupg_decrypt

(PECL gnupg >= 0.1)

gnupg_decrypt — Descifra un texto dado

### Descripción

function gnupg_decrypt(resource `$identifier`, string `$text`): string|false

Descifra un texto dado con las claves que se han establecido con gnupg_adddecryptkey previamente.

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.
`text`
  El texto a descifrar.

### Valores devueltos

En caso de éxito, esta función devuelve el texto descifrado. En caso de error, esta función devuelve `false`.

### Ejemplos

Ejemplo #1 Ejemplo con gnupg_decrypt() (Estilo procedimental)

    <?php
    $res = gnupg_init();
    gnupg_adddecryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    $plain = gnupg_decrypt($res,$encrypted_text);
    echo $plain;
    ?>

Ejemplo #2 Ejemplo con gnupg_decrypt() (Estilo orientado a objetos)

    <?php
    $gpg = new gnupg();
    $gpg->adddecryptkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    $plain = $gpg->decrypt($encrypted_text);
    echo $plain;
    ?>

# gnupg_decryptverify

(PECL gnupg >= 0.2)

gnupg_decryptverify — Descifra y verifica un texto dado

### Descripción

function gnupg_decryptverify(resource `$identifier`, string `$text`, string `&$plaintext`): array|false

Descifra y verifica un texto dado y devuelve las informaciones sobre la firma.

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.
`text`
  El texto a descifrar.
`plaintext`
  El argumento `plaintext` se rellena con el texto descifrado.

### Valores devueltos

En caso de éxito, esta función devuelve las informaciones sobre la firma y rellena el argumento `plaintext` con el texto descifrado. En caso de fallo, esta función devuelve `false`.

### Ejemplos

Ejemplo #1 Ejemplo con gnupg_decryptverify() (Estilo procedimental)

    <?php
    $plaintext = "";
    $res = gnupg_init();
    gnupg_adddecryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    $info = gnupg_decryptverify($res,$text,$plaintext);
    print_r($info);
    ?>

Ejemplo #2 Ejemplo con gnupg_decryptverify() (Estilo orientado a objetos)

    <?php
    $plaintext = "";
    $gpg = new gnupg();
    $gpg->adddecryptkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    $info = $gpg->decryptverify($text,$plaintext);
    print_r($info);
    ?>

# gnupg_deletekey

(PECL gnupg >= 0.5)

gnupg_deletekey — Elimina una clave del llavero

### Descripción

function gnupg_deletekey(resource `$identifier`, string `$key`, bool `$allow_secret`): bool

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.
`key`
  La clave a eliminar.
`allow_secret`
  Especifica si se deben eliminar las claves secretas.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo procedimental gnupg_deletekey()

    <?php
    $res = gnupg_init();
    gnupg_deletekey($res, "8660281B6051D071D94B5B230549F9DC851566DC");
    ?>

Ejemplo #2 Ejemplo orientado a objetos gnupg_deletekey()

    <?php
    $gpg = new gnupg();
    $gpg->deletekey("8660281B6051D071D94B5B230549F9DC851566DC");
    ?>

# gnupg_encrypt

(PECL gnupg >= 0.1)

gnupg_encrypt — Cifra un texto dado

### Descripción

function gnupg_encrypt(resource `$identifier`, string `$plaintext`): string|false

Cifra el argumento `plaintext` con las claves que han sido establecidas con gnupg_addencryptkey previamente y devuelve el texto cifrado.

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.
`plaintext`
  El texto a cifrar.

### Valores devueltos

En caso de éxito, esta función devuelve el texto cifrado. En caso de error, esta función devuelve `false`.

### Ejemplos

Ejemplo #1 Ejemplo con gnupg_encrypt() (Estilo procedimental)

    <?php
    $res = gnupg_init();
    gnupg_addencryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC");
    $enc = gnupg_encrypt($res, "sólo una prueba");
    echo $enc;
    ?>

Ejemplo #2 Ejemplo con gnupg_encrypt() (Estilo orientado a objetos)

    <?php
    $gpg = new gnupg();
    $gpg->addencryptkey("8660281B6051D071D94B5B230549F9DC851566DC");
    $enc = $gpg->encrypt("sólo una prueba");
    echo $enc;
    ?>

# gnupg_encryptsign

(PECL gnupg >= 0.2)

gnupg_encryptsign — Cifra y firma un texto dado

### Descripción

function gnupg_encryptsign(resource `$identifier`, string `$plaintext`): string|false

Cifra y firma el parámetro `plaintext` con las claves que han sido establecidas con gnupg_addsignkey y gnupg_addencryptkey previamente y devuelve el texto cifrado y firmado.

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.
`plaintext`
  El texto a cifrar.

### Valores devueltos

En caso de éxito, esta función devuelve el texto firmado y cifrado. En caso de fallo, esta función devuelve `false`.

### Ejemplos

Ejemplo #1 Ejemplo con gnupg_encryptsign() (Estilo procedimental)

    <?php
    $res = gnupg_init();
    gnupg_addencryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC");
    gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    $enc = gnupg_encryptsign($res, "sólo una prueba");
    echo $enc;
    ?>

Ejemplo #2 Ejemplo con gnupg_encryptsign() (Estilo orientado a objetos)

    <?php
    $gpg = new gnupg();
    $gpg->addencryptkey("8660281B6051D071D94B5B230549F9DC851566DC");
    $gpg->addsignkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    $enc = $gpg->encryptsign("sólo una prueba");
    echo $enc;
    ?>

# gnupg_export

(PECL gnupg >= 0.1)

gnupg_export — Exporta una clave

### Descripción

function gnupg_export(resource `$identifier`, string `$fingerprint`): string|false

Exporta la clave `fingerprint`.

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.
`fingerprint`
  La huella de la clave.

### Valores devueltos

En caso de éxito, esta función devuelve los datos de la clave. En caso de fallo, esta función devuelve `false`.

### Ejemplos

Ejemplo #1 Ejemplo con gnupg_export() (Estilo procedimental)

    <?php
    $res = gnupg_init();
    $export = gnupg_export($res,"8660281B6051D071D94B5B230549F9DC851566DC");
    echo $export;
    ?>

Ejemplo #2 Ejemplo con gnupg_export() (Estilo orientado a objetos)

    <?php
    $gpg = new gnupg();
    $export = $gpg->export("8660281B6051D071D94B5B230549F9DC851566DC");
    ?>

# gnupg_getengineinfo

(PECL gnupg >= 1.5)

gnupg_getengineinfo — Devuelve la información del motor

### Descripción

function gnupg_getengineinfo(resource `$identifier`): array

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.

### Valores devueltos

Devuelve un array que contiene la información del motor compuesto por `protocol`, `file_name` y `home_dir`.

### Ejemplos

Ejemplo #1 Ejemplo procedimental gnupg_getengineinfo()

    <?php
    $res = gnupg_init();
    print_r(gnupg_getengineinfo($res));
    ?>

El ejemplo anterior mostrará:

    array(3) {
      ["protocol"]=>
      int(0)
      ["file_name"]=>
      string(12) "/usr/bin/gpg"
      ["home_dir"]=>
      string(0) ""
    }

Ejemplo #2 Ejemplo orientado a objetos gnupg_getengineinfo()

    <?php
    $gpg = new gnupg(["file_name" => "/usr/bin/gpg2", "home_dir" => "/var/www/.gnupg"]);
    print_r($gpg->getengineinfo());
    ?>

El ejemplo anterior mostrará:

    array(3) {
      ["protocol"]=>
      int(0)
      ["file_name"]=>
      string(13) "/usr/bin/gpg2"
      ["home_dir"]=>
      string(15) "/var/www/.gnupg"
    }

# gnupg_geterror

(PECL gnupg >= 0.1)

gnupg_geterror — Devuelve el texto de error, si una función falla

### Descripción

function gnupg_geterror(resource `$identifier`): string|false

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.

### Valores devueltos

Devuelve el texto de error si se ha producido un error, en caso contrario devuelve `false`.

### Ejemplos

Ejemplo #1 Ejemplo con gnupg_geterror() (Estilo procedimental)

    <?php
    $res = gnupg_init();
    echo gnupg_geterror($res);
    ?>

Ejemplo #2 Ejemplo con gnupg_geterror() (Estilo orientado a objetos)

    <?php
    $gpg = new gnupg();
    echo $gpg->geterror();
    ?>

# gnupg_geterrorinfo

(PECL gnupg >= 1.5)

gnupg_geterrorinfo — Devuelve la información de error

### Descripción

function gnupg_geterrorinfo(resource `$identifier`): array

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.

### Valores devueltos

Devuelve un array con la información de error.

### Ejemplos

Ejemplo #1 Ejemplo procedimental gnupg_geterrorinfo()

    <?php
    $res = gnupg_init();
    // esto es llamado sin error
    print_r(gnupg_geterrorinfo($res));
    ?>

El ejemplo anterior mostrará:

    array(4) {
      ["generic_message"]=>
      bool(false)
      ["gpgme_code"]=>
      int(0)
      ["gpgme_source"]=>
      string(18) "Unspecified source"
      ["gpgme_message"]=>
      string(7) "Success"
    }

Ejemplo #2 Ejemplo orientado a objetos gnupg_geterrorinfo()

    <?php
    $gpg = new gnupg();
    // llamada con error
    $gpg->decrypt('abc');
    // la información de error debe ser mostrada
    print_r($gpg->geterrorinfo());
    ?>

El ejemplo anterior mostrará:

    array(4) {
      ["generic_message"]=>
      string(14) "decrypt failed"
      ["gpgme_code"]=>
      int(117440570)
      ["gpgme_source"]=>
      string(5) "GPGME"
      ["gpgme_message"]=>
      string(7) "No data"
    }

# gnupg_getprotocol

(PECL gnupg >= 0.1)

gnupg_getprotocol — Devuelve el protocolo activo actual para todas las operaciones

### Descripción

function gnupg_getprotocol(resource `$identifier`): int

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.

### Valores devueltos

Devuelve el protocolo activo actual, que puede ser uno de estos: `GNUPG_PROTOCOL_OpenPGP` o `GNUPG_PROTOCOL_CMS`.

### Ejemplos

Ejemplo #1 Ejemplo con gnupg_getprotocol() (Estilo procedimental)

    <?php
    $res = gnupg_init();
    echo gnupg_getprotocol($res);
    ?>

Ejemplo #2 Ejemplo con gnupg_getprotocol() (Estilo orientado a objetos)

    <?php
    $gpg = new gnupg();
    echo $gpg->getprotocol();
    ?>

# gnupg_gettrustlist

(PECL gnupg >= 0.5)

gnupg_gettrustlist — Busca los elementos de confianza

### Descripción

function gnupg_gettrustlist(resource `$identifier`, string `$pattern`): ?array

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.
`pattern`
  Una expresión para limitar la lista de elementos de confianza a los elementos que coinciden con el patrón.

### Valores devueltos

En caso de éxito, esta función devuelve un array de elementos de confianza. En caso de error, esta función devuelve `null`.

### Ejemplos

Ejemplo #1 Ejemplo procedimental gnupg_gettrustlist()

    <?php
    $res = gnupg_init();
    $items = gnupg_gettrustlist($res);
    print_r($items);
    ?>

Ejemplo #2 Ejemplo orientado a objetos gnupg_gettrustlist()

    <?php
    $gpg = new gnupg();
    $items = $gpg->gettrustlist();
    print_r($items);
    ?>

# gnupg_import

(PECL gnupg >= 0.3)

gnupg_import — Importa una clave

### Descripción

function gnupg_import(resource `$identifier`, string `$keydata`): array|false

Importa la clave `keydata` y devuelve un array con la información sobre el proceso de importación.

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.
`keydata`
  La clave a importar.

### Valores devueltos

En caso de éxito, esta función devuelve un array de información sobre el proceso de importación. En caso de fallo, esta función devuelve `false`.

### Ejemplos

Ejemplo #1 Ejemplo con gnupg_import() (Estilo procedimental)

    <?php
    $res = gnupg_init();
    $info = gnupg_import($res,$keydata);
    print_r($info);
    ?>

Ejemplo #2 Ejemplo con gnupg_import() (Estilo orientado a objetos)

    <?php
    $gpg = new gnupg();
    $info = $gpg->import($keydata);
    print_r($info);
    ?>

# gnupg_init

(PECL gnupg >= 0.4)

gnupg_init — Inicializa una conexión

### Descripción

function gnupg_init(?array `$options` = `null`): resource

### Parámetros

`options`

  Debe ser un array asociativo. Se utiliza para modificar la configuración por omisión del motor criptográfico.

  Sustitución de la configuración
  Clave | Tipo | Descripción
  --- | --- | ---
  file_name | string | Es el nombre de fichero del programa ejecutable que implementa este protocolo, que generalmente es la ruta del ejecutable `gpg`.
  home_dir | string | Es el nombre del directorio de configuración. También sustituye a la variable de entorno `GNUPGHOME` que se utiliza con el mismo propósito.

### Valores devueltos

Un recurso de conexión GnuPG, utilizado por otras funciones GnuPG.

### Historial de cambios

Versión | Descripción
--- | ---
PECL gnupg 1.5.0 | Se ha añadido el argumento `options`.

### Ejemplos

Ejemplo #1 Ejemplo con gnupg_init() con configuración por omisión (Estilo procedimental)

    <?php
    $res = gnupg_init();
    ?>

Ejemplo #2 Ejemplo con gnupg_init() con nombre de fichero y directorio de origen sobrescritos (Estilo procedimental)

    <?php
    $res = gnupg_init(["file_name" => "/usr/bin/gpg2", "home_dir" => "/var/www/.gnupg"]);
    ?>

Ejemplo #3 Ejemplo con gnupg_init() con configuración por omisión (Estilo orientado a objetos)

    <?php
    $gpg = new gnupg();
    ?>

Ejemplo #4 Ejemplo con gnupg_init() con nombre de fichero y directorio de origen sobrescritos (Estilo orientado a objetos)

    <?php
    $gpg = new gnupg(["file_name" => "/usr/bin/gpg2", "home_dir" => "/var/www/.gnupg"]);
    ?>

# gnupg_keyinfo

(PECL gnupg >= 0.1)

gnupg_keyinfo — Retorna un array con las informaciones acerca de todas las claves que coinciden con el patrón dado

### Descripción

function gnupg_keyinfo(resource `$identifier`, string `$pattern`): array|false

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.
`pattern`
  La máscara a utilizar sobre las claves.

### Valores devueltos

Retorna un array con las informaciones acerca de todas las claves que coinciden con el patrón dado o retorna `false` si ha ocurrido un error.

### Ejemplos

Ejemplo #1 Ejemplo con gnupg_keyinfo() (Estilo procedimental)

    <?php
    $res = gnupg_init();
    $info = gnupg_keyinfo($res, 'test');
    print_r($info);
    ?>

Ejemplo #2 Ejemplo con gnupg_keyinfo() (Estilo orientado a objetos)

    <?php
    $gpg = new gnupg();
    $info = $gpg->keyinfo("test");
    print_r($info);
    ?>

# gnupg_listsignatures

(PECL gnupg >= 0.5)

gnupg_listsignatures — Lista las firmas de clave

### Descripción

function gnupg_listsignatures(resource `$identifier`, string `$keyid`): ?array

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.
`keyid`
  El identificador de clave para listar las firmas.

### Valores devueltos

En caso de éxito, esta función devuelve un array de firmas de clave. En caso de error, esta función devuelve `null`.

### Ejemplos

Ejemplo #1 Ejemplo procedimental gnupg_listsignatures()

    <?php
    $res = gnupg_init();
    $signatures = gnupg_listsignatures($res, "8660281B6051D071D94B5B230549F9DC851566DC");
    print_r($signatures);
    ?>

Ejemplo #2 Ejemplo orientado a objetos gnupg_listsignatures()

    <?php
    $gpg = new gnupg();
    $signatures = $gpg->listsignatures("8660281B6051D071D94B5B230549F9DC851566DC");
    print_r($signatures);
    ?>

# gnupg_setarmor

(PECL gnupg >= 0.1)

gnupg_setarmor — Cambia la salida blindada

### Descripción

function gnupg_setarmor(resource `$identifier`, int `$armor`): bool

Cambia la salida blindada.

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.
`armor`
  Pase un valor entero diferente de cero a esta función para activar la salida blindada (valor por omisión). Pase 0 para desactivar la salida blindada.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con gnupg_setarmor() (Estilo procedimental)

    <?php
    $res = gnupg_init();
    gnupg_setarmor($res,1); // Activa la salida blindada;
    gnupg_setarmor($res,0); // Desactiva la salida blindada;
    ?>

Ejemplo #2 Ejemplo con gnupg_setarmor() (Estilo orientado a objetos)

    <?php
    $gpg = new gnupg();
    $gpg->setarmor(1); // Activa la salida blindada;
    $gpg->setarmor(0); // Desactiva la salida blindada;
    ?>

# gnupg_seterrormode

(PECL gnupg >= 0.6)

gnupg_seterrormode — Establece el modo para error_reporting

### Descripción

function gnupg_seterrormode(resource `$identifier`, int `$errormode`): void

Establece el modo para error_reporting.

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.
`errormode`
  El modo de error. `errormode` acepta una constante que indica qué tipo de error_reporting debe ser utilizado. Los valores posibles son `GNUPG_ERROR_WARNING`, `GNUPG_ERROR_EXCEPTION` y `GNUPG_ERROR_SILENT`. Por omisión `GNUPG_ERROR_SILENT`.

### Valores devueltos

No se retorna ningún valor.

### Ejemplos

Ejemplo #1 Ejemplo con gnupg_seterrormode() (Estilo procedimental)

    <?php
    $res = gnupg_init();
    gnupg_seterrormode($res, GNUPG_ERROR_WARNING); // emite un PHP-Warning en caso de error
    ?>

Ejemplo #2 Ejemplo con gnupg_seterrormode() (Estilo orientado a objetos)

    <?php
    $gpg = new gnupg();
    $gpg->seterrormode(gnupg::ERROR_EXCEPTION); // lanza una excepción en caso de error
    ?>

# gnupg_setsignmode

(PECL gnupg >= 0.1)

gnupg_setsignmode — Establece el modo para firmar

### Descripción

function gnupg_setsignmode(resource `$identifier`, int `$signmode`): bool

Establece el modo para firmar.

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.
`sigmode`
  El modo de firma. `signmode` acepta una constante que indica qué tipo de firma debe ser producida. Los valores posibles son: `GNUPG_SIG_MODE_NORMAL`, `GNUPG_SIG_MODE_DETACH` y `GNUPG_SIG_MODE_CLEAR`. Por omisión, se utiliza `GNUPG_SIG_MODE_CLEAR`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Ejemplo con gnupg_setsignmode() (Estilo procedimental)

    <?php
    $res = gnupg_init();
    gnupg_setsignmode($res, GNUPG_SIG_MODE_DETACH); // produce una firma desvinculada
    ?>

Ejemplo #2 Ejemplo con gnupg_setsignmode() (Estilo orientado a objetos)

    <?php
    $gpg = new gnupg();
    $gpg->setsignmode(gnupg::SIG_MODE_DETACH); // produce una firma desvinculada
    ?>

# gnupg_sign

(PECL gnupg >= 0.1)

gnupg_sign — Firma un texto dado

### Descripción

function gnupg_sign(resource `$identifier`, string `$plaintext`): string|false

Firma el argumento `plaintext` con las claves que fueron establecidas con gnupg_addsignkey previamente y devuelve el texto firmado o la firma, dependiendo de lo que fue establecido con gnupg_setsignmode.

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.
`plaintext`
  El texto a firmar.

### Valores devueltos

En caso de éxito, esta función devuelve el texto firmado o la firma. En caso de fallo, esta función devuelve `false`.

### Ejemplos

Ejemplo #1 Ejemplo con gnupg_sign() (Estilo procedimental)

    <?php
    $res = gnupg_init();
    gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    $signed = gnupg_sign($res, "sólo una prueba");
    echo $signed;
    ?>

Ejemplo #2 Ejemplo con gnupg_sign() (Estilo orientado a objetos)

    <?php
    $gpg = new gnupg();
    $gpg->addsignkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    $signed = $gpg->sign("just a test");
    echo $signed;
    ?>

# gnupg_verify

(PECL gnupg >= 0.1)

gnupg_verify — Verifica un texto firmado

### Descripción

function gnupg_verify(
resource `$identifier`,
string `$signed_text`,
string `$signature`,
string `&$plaintext` = ?
): array|false

Verifica el argumento `signed_text` y devuelve las informaciones acerca de la firma.

### Parámetros

`identifier`
  El identificador gnupg, generado por una llamada a la función gnupg_init() o a la función gnupg.
`signed_text`
  El texto firmado.
`signature`
  La firma. Para verificar un texto firmado en claro, se establece la firma a `false`.
`plaintext`
  El texto. Si este argumento opcional es pasado, se rellena con el `plaintext`.

### Valores devueltos

En caso de éxito, esta función devuelve informaciones acerca de la firma. En caso de fallo, esta función devuelve `false`.

### Ejemplos

Ejemplo #1 Ejemplo con gnupg_verify() (Estilo procedimental)

    <?php
    $plaintext = "";
    $res = gnupg_init();
    // firmado en claro
    $info = gnupg_verify($res,$signed_text,false,$plaintext);
    print_r($info);
    // firma separada
    $info = gnupg_verify($res,$signed_text,$signature);
    print_r($info);
    ?>

Ejemplo #2 Ejemplo con gnupg_verify() (Estilo orientado a objetos)

    <?php
    $plaintext = "";
    $gpg = new gnupg();
    // firmado en claro
    $info = $gpg->verify($signed_text,false,$plaintext);
    print_r($info);
    // firma separada
    $info = $gpg->verify($signed_text,$signature);
    print_r($info);
    ?>

## Tabla de contenidos

- gnupg_adddecryptkey — Añade una clave para descifrado
- gnupg_addencryptkey — Añade una clave para cifrado
- gnupg_addsignkey — Añade una clave para firmar
- gnupg_cleardecryptkeys — Elimina todas las claves que fueron fijadas para el descifrado anteriormente
- gnupg_clearencryptkeys — Elimina todas las claves que fueron establecidas para cifrado con anterioridad
- gnupg_clearsignkeys — Elimina todas las claves que fueron fijadas para firma previamente
- gnupg_decrypt — Descifra un texto dado
- gnupg_decryptverify — Descifra y verifica un texto dado
- gnupg_deletekey — Elimina una clave del llavero
- gnupg_encrypt — Cifra un texto dado
- gnupg_encryptsign — Cifra y firma un texto dado
- gnupg_export — Exporta una clave
- gnupg_getengineinfo — Devuelve la información del motor
- gnupg_geterror — Devuelve el texto de error, si una función falla
- gnupg_geterrorinfo — Devuelve la información de error
- gnupg_getprotocol — Devuelve el protocolo activo actual para todas las operaciones
- gnupg_gettrustlist — Busca los elementos de confianza
- gnupg_import — Importa una clave
- gnupg_init — Inicializa una conexión
- gnupg_keyinfo — Retorna un array con las informaciones acerca de todas las claves que coinciden con el patrón dado
- gnupg_listsignatures — Lista las firmas de clave
- gnupg_setarmor — Cambia la salida blindada
- gnupg_seterrormode — Establece el modo para error_reporting
- gnupg_setsignmode — Establece el modo para firmar
- gnupg_sign — Firma un texto dado
- gnupg_verify — Verifica un texto firmado

- Instalación/Configuración
  - Requerimientos
  - Instalación
- Constantes predefinidas
- Ejemplos
  - Firma de texto (clearsign)
- Funciones GnuPG
  - gnupg_adddecryptkey — Añade una clave para descifrado
  - gnupg_addencryptkey — Añade una clave para cifrado
  - gnupg_addsignkey — Añade una clave para firmar
  - gnupg_cleardecryptkeys — Elimina todas las claves que fueron fijadas para el descifrado anteriormente
  - gnupg_clearencryptkeys — Elimina todas las claves que fueron establecidas para cifrado con anterioridad
  - gnupg_clearsignkeys — Elimina todas las claves que fueron fijadas para firma previamente
  - gnupg_decrypt — Descifra un texto dado
  - gnupg_decryptverify — Descifra y verifica un texto dado
  - gnupg_deletekey — Elimina una clave del llavero
  - gnupg_encrypt — Cifra un texto dado
  - gnupg_encryptsign — Cifra y firma un texto dado
  - gnupg_export — Exporta una clave
  - gnupg_getengineinfo — Devuelve la información del motor
  - gnupg_geterror — Devuelve el texto de error, si una función falla
  - gnupg_geterrorinfo — Devuelve la información de error
  - gnupg_getprotocol — Devuelve el protocolo activo actual para todas las operaciones
  - gnupg_gettrustlist — Busca los elementos de confianza
  - gnupg_import — Importa una clave
  - gnupg_init — Inicializa una conexión
  - gnupg_keyinfo — Retorna un array con las informaciones acerca de todas las claves que coinciden con el patrón dado
  - gnupg_listsignatures — Lista las firmas de clave
  - gnupg_setarmor — Cambia la salida blindada
  - gnupg_seterrormode — Establece el modo para error_reporting
  - gnupg_setsignmode — Establece el modo para firmar
  - gnupg_sign — Firma un texto dado
  - gnupg_verify — Verifica un texto firmado

# wkhtmltox

# Introducción

libwkhtmltox es una librería LGPLv3 de código abierto para renderizar HTML en PDF y varios formatos de imagen usando el motor de renderización QtWebKit.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Configuración en tiempo de ejecución

## Requerimientos

La fuente de libwkhtmltox y las liberaciones binarias se distribuyen en » wkhtmltopdf.org.

Precaución

Los usuarios de Windows necesitan dar el paso adicional de añadir wkhtmltox.dll a su PATH.

## Instalación

El código fuente de esta extensión, y los binarios para Windows están alojados en » github,

Buscando el código fuente y construyendo la extensión:

    git clone https://github.com/krakjoe/wkhtmltox
    cd wkhtmltox
    phpize
    ./configure --with-wkhtmltox=/path/to/wkhtmltox/installation
    make
    sudo make install

Buscando actualizaciones y reconstruyendo la extensión:

    cd wkhtmltox
    phpize --clean
    git pull origin master
    phpize
    ./configure --with-wkhtmltox=/path/to/wkhtmltox/installation
    make
    sudo make install

## Configuración en tiempo de ejecución

El comportamiento de estas funciones es afectado por la configuración en el archivo php.ini.

wkhtmltox Opciones de configuración
Nombre | Por defecto | Cambiable | Historial de cambios
--- | --- | --- | ---
wkhtmltox.graphics | Off | `INI_SYSTEM`|`INI_PERDIR` | >= 0.3.2

Para más detalles sobre los modos INI_*, refiérase a Dónde una directiva de configuración puede ser modificada.

Aquí hay una aclaración sobre el uso de las directivas de configuración.

`wkhtmltox.graphics` bool

  Permite que libwkhtmltox utilice gráficos.

# La clase wkhtmltox\PDF\Converter

(wkhtmltox >= 0.1.0)

## Introducción

Convierte una entrada HTML, o un conjunto de entradas HTML, en una salida PDF

## Sinopsis de la Clase

class wkhtmltox\PDF\Converter {
/* Constructor */
public function __construct(array `$settings` = ?)
/* Métodos */
public function add(wkhtmltox\PDF\Object `$object`): void
public function convert(): ?string
public function getVersion(): string
}

# wkhtmltox\PDF\Converter::add

(wkhtmltox >= 0.1.0)

wkhtmltox\PDF\Converter::add — Añade un objeto para su conversión

### Descripción

public function wkhtmltox\PDF\Converter::add(wkhtmltox\PDF\Object `$object`): void

Añade el objeto dado a la conversión

### Parámetros

`object`

  El objeto a añadir

# wkhtmltox\PDF\Converter::__construct

(wkhtmltox >= 0.1.0)

wkhtmltox\PDF\Converter::__construct — Crea un nuevo conversor de PDF

### Descripción

public function wkhtmltox\PDF\Converter::__construct(array `$settings` = ?)

Crea un nuevo conversor de PDF, utilizando opcionalmente una configuración.

### Parámetros

`settings`

  Nombre | Descripción | Valores | Registro de cambios
  --- | --- | --- | ---
  size.pageSize | Tamaño del papel del documento final | A4 | >= 0.1.0
  size.width | Ancho del documento final | 210mm | >= 0.1.0
  size.height | Altura del documento final | 297mm | >= 0.1.0
  orientation | Orientación del documento final |
  Landscape
  Portrait
  | >= 0.1.0
  colorMode | Modo de color del documento final |
  Color
  Greyscale
  | >= 0.1.0
  resolution | Resolución del documento final | La mayoría de las veces, no tiene ningún efecto | >= 0.1.0
  dpi | DPI a usar al imprimir | 80 | >= 0.1.0
  pageOffset | Entero a añadir a los números de página generados para el encabezado, el pie de página y el índice |  | >= 0.1.0
  copies |  |  | >= 0.1.0
  collate | Si se deben intercalar las copias | booleano | >= 0.1.0
  outline | Genera un índice PDF | booleano | >= 0.1.0
  outlineDepth | Profundidad máxima del índice |  | >= 0.1.0
  dumpOutline | Ruta del archivo para extraer el índice XML |  | >= 0.1.0
  out | Ruta para el archivo final, si es "-" se usa stdout |  | >= 0.1.0
  documentTitle | Título del documento final |  | >= 0.1.0
  useCompression | Activa o desactiva la compresión sin pérdida | booleano | >= 0.1.0
  margin.top | Tamaño del margen superior | 2cm | >= 0.1.0
  margin.bottom | Tamaño del margen inferior | 2cm | >= 0.1.0
  margin.left | Tamaño del margen izquierdo | 2cm | >= 0.1.0
  margin.right | Tamaño del margen derecho | 2cm | >= 0.1.0
  imageDPI | DPI máximo para las imágenes en el documento final |  | >= 0.1.0
  imageQuality | El factor de compresión jpeg para las imágenes en el documento final | 94 | >= 0.1.0
  load.cookieJar | Ruta hacia el archivo utilizado para cargar y almacenar las cookies | /tmp/cookies.txt | >= 0.1.0

# wkhtmltox\PDF\Converter::convert

(wkhtmltox >= 0.1.0)

wkhtmltox\PDF\Converter::convert — Realiza la conversión a PDF

### Descripción

public function wkhtmltox\PDF\Converter::convert(): ?string

Realiza la conversión de todos los objetos añadidos anteriormente

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Donde se utiliza el valor de retorno, se llenará con el contenido del buffer de conversión

# wkhtmltox\PDF\Converter::getVersion

(wkhtmltox >= 0.3.2)

wkhtmltox\PDF\Converter::getVersion — Determina la versión del convertidor

### Descripción

public function wkhtmltox\PDF\Converter::getVersion(): string

Determina la versión del convertidor según lo informado por libwkhtmltox

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un string de versión

## Tabla de contenidos

- wkhtmltox\PDF\Converter::add — Añade un objeto para su conversión
- wkhtmltox\PDF\Converter::__construct — Crea un nuevo conversor de PDF
- wkhtmltox\PDF\Converter::convert — Realiza la conversión a PDF
- wkhtmltox\PDF\Converter::getVersion — Determina la versión del convertidor

# La clase wkhtmltox\PDF\Object

(wkhtmltox >= 0.1.0)

## Introducción

Representa un documento HTML, convertidor de entrada a PDF

## Sinopsis de la Clase

class wkhtmltox\PDF\Object {
/* Constructor */
public function __construct(string `$buffer`, array `$settings` = ?)
}

# wkhtmltox\PDF\Object::__construct

(wkhtmltox >= 0.1.0)

wkhtmltox\PDF\Object::__construct — Crea un nuevo objeto PDF

### Descripción

public function wkhtmltox\PDF\Object::__construct(string `$buffer`, array `$settings` = ?)

Crea un nuevo objeto PDF desde el buffer proporcionado, y las configuraciones opcionales.

### Parámetros

`buffer`

  HTML

`settings`

  Nombre | Descripción | Valor | Registro de cambios
  --- | --- | --- | ---
  page | URL o ruta del archivo HTML a convertir |  | >= 0.1.0
  useExternalLinks | Establecer en `true` para convertir los enlaces externos enlaces PDF en la salida | booleano | >= 0.1.0
  useLocalLinks | Establecer en `true` para convertir los enlaces internos en los datos de entrada en enlaces PDF en la salida | booleano | >= 0.1.0
  produceForms | Establecer en `true` para convertir los formularios HTML en formularios PDF | booleano | >= 0.1.0
  replacements | no documentado |  | >= 0.1.0
  includeInOutline | Establecer en `true` para incluir las secciones de este objeto en el contorno y la tabla de contenidos | booleano | >= 0.1.0
  pagesCount | Establecer en `true` para incluir en la tabla de contenidos el número de páginas de este objeto | booleano | >= 0.1.0
  tocXsl | Establecer en hoja de estilo para convertir este objeto en un objeto de tabla de contenidos |  | >= 0.1.0
  toc.useDottedLines | Establecer en `true` para usar líneas de puntos en la tabla de contenidos | booleano | >= 0.1.0
  toc.captionText | El pie de ilustración para la tabla de contenidos |  | >= 0.1.0
  toc.forwardLinks | Establecer en `true` para crear enlaces desde la tabla de contenidos hacia el contenido | booleano | >= 0.1.0
  toc.backLinks | Establecer en `true` para crear enlaces desde el contenido hacia la tabla de contenidos | booleano | >= 0.1.0
  toc.indentation | La indentación para la tabla de contenidos | 2em | >= 0.1.0
  toc.fontScale | El factor para reducir la fuente de caracteres en todos los niveles de la tabla de contenidos | 0.8 | >= 0.1.0
  header.fontSize | El tamaño de la fuente de caracteres a usar en el encabezado | 13 | >= 0.1.0
  header.fontName | El nombre de la fuente de caracteres a usar en el encabezado | times | >= 0.1.0
  header.left | El texto para el lado izquierdo del encabezado |  | >= 0.1.0
  header.center | El texto para el centro del encabezado |  | >= 0.1.0
  header.right | El texto para el lado derecho del encabezado |  | >= 0.1.0
  header.line | Activa o desactiva la regla horizontal bajo el encabezado | booleano | >= 0.1.0
  header.spacing | El espacio entre el encabezado y el contenido | 1.8 | >= 0.1.0
  header.htmlUrl | URL o la ruta hacia el archivo HTML a usar en el encabezado |  | >= 0.1.0
  footer.fontSize | El tamaño de la fuente de caracteres a usar en el pie de página | 13 | >= 0.1.0
  footer.fontName | El nombre de la fuente de caracteres a usar en el pie de página | times | >= 0.1.0
  footer.left | El texto para el lado izquierdo del pie de página |  | >= 0.1.0
  footer.center | El texto para el centro del pie de página |  | >= 0.1.0
  footer.right | El texto para el lado derecho del pie de página |  | >= 0.1.0
  footer.line | Activa o desactiva la regla horizontal bajo el pie de página | booleano | >= 0.1.0
  footer.spacing | El espacio entre el pie de página y el contenido | 1.8 | >= 0.1.0
  footer.htmlUrl | URL o la ruta del archivo HTML a usar en el pie de página |  | >= 0.1.0
  load.username | nombre de usuario a utilizar al conectarse a un sitio web | bart | >= 0.1.0
  load.password | contraseña a utilizar al conectarse a un sitio web | elbarto | >= 0.1.0
  load.jsdelay | el tiempo en milisegundos a esperar después de cargar una página antes de capturarla | 1200 | >= 0.1.0
  load.zoomFactor | cuánto zoom debe aplicarse al contenido | 2.2 | >= 0.1.0
  load.customHeaders | encabezados personalizados a enviar al solicitar la página web principal |  | >= 0.1.0
  load.repertCustomHeaders | establecer en true para enviar con todas las solicitudes | booleano | >= 0.1.0
  load.cookies | cookie a enviar al solicitar la página web principal |  | >= 0.1.0
  load.post | string a enviar al realizar una solicitud post a la página web principal |  | >= 0.1.0
  load.blockLocalFileAccess | impide que los archivos locales y los archivos de tubería accedan a otros archivos locales | booleano | >= 0.1.0
  load.stopSlowScript | detiene los scripts lentos de javascript | booleano |
  load.debugJavascript | permite que javascript lance advertencias | booleano | >= 0.1.0
  load.loadErrorHandling | define la estrategia de manejo de errores |
  abort | aborta el proceso de conversión
  skip | no añade el objeto a la salida final
  ignore | intenta añadir el objeto a la salida final
  | >= 0.1.0
  load.proxy |  |  | >= 0.1.0
  web.background | incluye una imagen de fondo en la salida | booleano | >= 0.1.0
  web.loadImages | incluye imágenes en la salida | booleano | >= 0.1.0
  web.enableJavascript | activa o desactiva javascript | booleano | >= 0.1.0
  web.enableIntelligentShrinking | activa el intento de poner más contenido en la página, se aplica solo a la salida PDF | booleano | >= 0.1.0
  web.minimumFontSize | el tamaño de fuente mínimo permitido | 9 | >= 0.1.0
  web.printMediaType | muestra el contenido usando el tipo de medio de impresión en lugar del tipo de medio de pantalla | booleano | >= 0.1.0
  web.defaultEncoding | el contenido a usar cuando no se especifica ninguna codificación | utf-8 | >= 0.1.0
  web.userStyleSheet | URL o ruta hacia una hoja de estilo de usuario especificada | /ruta/hacia/estilo.css | >= 0.1.0
  web.enablePlugins | activa o desactiva los plugins NS | booleano | >= 0.1.0

## Tabla de contenidos

- wkhtmltox\PDF\Object::__construct — Crea un nuevo objeto PDF

# La clase wkhtmltox\Image\Converter

(wkhtmltox >= 0.1.0)

## Introducción

Convierte una entrada HTML en varios formatos de imagen

## Sinopsis de la Clase

class wkhtmltox\Image\Converter {
/* Constructor */
public function __construct(string `$buffer` = ?, array `$settings` = ?)
/* Métodos */
public function convert(): ?string
public function getVersion(): string
}

# wkhtmltox\Image\Converter::__construct

(wkhtmltox >= 0.1.0)

wkhtmltox\Image\Converter::__construct — Crea un nuevo convertidor de imágenes

### Descripción

public function wkhtmltox\Image\Converter::__construct(string `$buffer` = ?, array `$settings` = ?)

Crea un convertidor de imágenes, utilizando opcionalmente un buffer de entrada así como una configuración

### Parámetros

`buffer`

  HTML

`settings`

  Nombre | Descripción | Valor | Registro de cambios
  --- | --- | --- | ---
  in | URL o ruta del archivo de entrada, si se usa la salida "-" | /ruta/hacia/marcado.html | >= 0.1.0
  out | Ruta del archivo de salida, si es "-" se usa stdout; por omisión, se usa un buffer interno | /ruta/hacia/salida.png | >= 0.1.0
  fmt | Formato de salida a usar |
  "" | predeterminado
  jpg | salida como JPEG
  png | salida como PNG
  bmp | salida como mapa de bits
  svg | salida como SVG
  | >= 0.1.0
  transparent | En la salida PNG o SVG, hace el fondo transparente | booleano | >= 0.1.0
  screenWidth | El ancho de pantalla a usar para el renderizado en píxeles | 800 | >= 0.1.0
  smartWidth | Cuando es `true`, el ancho de la pantalla se extiende al ancho del contenido | booleano | >= 0.1.0
  quality | Factor de compresión a usar cuando la salida es una imagen JPEG | 94 | >= 0.1.0
  crop.left | Izquierda/coordenada X de la ventana a capturar, en píxeles | 200 | >= 0.1.0
  crop.top | Arriba/coordenada Y de la ventana a capturar, en píxeles | 200 | >= 0.1.0
  crop.width | Ancho de la ventana a capturar, en píxeles | 200 | >= 0.1.0
  crop.height | Altura de la ventana a capturar, en píxeles | 200 | >= 0.1.0
  load.cookieJar | Ruta del archivo utilizado para cargar y almacenar las cookies. | /tmp/cookies.txt | >= 0.1.0
  load.username | nombre de usuario a utilizar al conectarse a un sitio web | bart | >= 0.1.0
  load.password | contraseña a utilizar al conectarse a un sitio web | elbarto | >= 0.1.0
  load.jsdelay | el tiempo en milisegundos a esperar después de cargar una página antes de capturarla | 1200 | >= 0.1.0
  load.zoomFactor | cuánto zoom debe aplicarse al contenido | 2.2 | >= 0.1.0
  load.customHeaders | encabezados personalizados a enviar al solicitar la página web principal |  | >= 0.1.0
  load.repertCustomHeaders | establecer en true para enviar con todas las solicitudes | booleano | >= 0.1.0
  load.cookies | cookie a enviar al solicitar la página web principal |  | >= 0.1.0
  load.post | string a enviar al realizar una solicitud post a la página web principal |  | >= 0.1.0
  load.blockLocalFileAccess | impide que los archivos locales y los archivos de tubería accedan a otros archivos locales | booleano | >= 0.1.0
  load.stopSlowScript | detiene los scripts lentos de javascript | booleano |
  load.debugJavascript | permite que javascript lance advertencias | booleano | >= 0.1.0
  load.loadErrorHandling | define la estrategia de manejo de errores |
  abort | aborta el proceso de conversión
  skip | no añade el objeto a la salida final
  ignore | intenta añadir el objeto a la salida final
  | >= 0.1.0
  load.proxy |  |  | >= 0.1.0
  web.background | incluye una imagen de fondo en la salida | booleano | >= 0.1.0
  web.loadImages | incluye imágenes en la salida | booleano | >= 0.1.0
  web.enableJavascript | activa o desactiva javascript | booleano | >= 0.1.0
  web.enableIntelligentShrinking | activa el intento de poner más contenido en la página, se aplica solo a la salida PDF | booleano | >= 0.1.0
  web.minimumFontSize | el tamaño de fuente mínimo permitido | 9 | >= 0.1.0
  web.printMediaType | muestra el contenido usando el tipo de medio de impresión en lugar del tipo de medio de pantalla | booleano | >= 0.1.0
  web.defaultEncoding | el contenido a usar cuando no se especifica ninguna codificación | utf-8 | >= 0.1.0
  web.userStyleSheet | URL o ruta hacia una hoja de estilo de usuario especificada | /ruta/hacia/estilo.css | >= 0.1.0
  web.enablePlugins | activa o desactiva los plugins NS | booleano | >= 0.1.0

# wkhtmltox\Image\Converter::convert

(wkhtmltox >= 0.1.0)

wkhtmltox\Image\Converter::convert — Realiza la conversión de la imagen

### Descripción

public function wkhtmltox\Image\Converter::convert(): ?string

Realiza la conversión de la memoria intermedia de entrada

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Cuando se utilice el valor de retorno, se rellenará con el contenido de la memoria intermedia de conversión

# wkhtmltox\Image\Converter::getVersion

(wkhtmltox >= 0.3.2)

wkhtmltox\Image\Converter::getVersion — Determina la versión del convertidor

### Descripción

public function wkhtmltox\Image\Converter::getVersion(): string

Determina la versión del convertidor según lo informado por libwkhtmltox

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Devuelve un string de versión

Advertencia

Esto todavía no se ha implementado por libwkhtmltox

## Tabla de contenidos

- wkhtmltox\Image\Converter::__construct — Crea un nuevo convertidor de imágenes
- wkhtmltox\Image\Converter::convert — Realiza la conversión de la imagen
- wkhtmltox\Image\Converter::getVersion — Determina la versión del convertidor

- Instalación/Configuración
  - Requerimientos
  - Instalación
  - Configuración en tiempo de ejecución
- wkhtmltox\PDF\Converter — La clase wkhtmltox\PDF\Converter
  - wkhtmltox\PDF\Converter::add — Añade un objeto para su conversión
  - wkhtmltox\PDF\Converter::__construct — Crea un nuevo conversor de PDF
  - wkhtmltox\PDF\Converter::convert — Realiza la conversión a PDF
  - wkhtmltox\PDF\Converter::getVersion — Determina la versión del convertidor
- wkhtmltox\PDF\Object — La clase wkhtmltox\PDF\Object
  - wkhtmltox\PDF\Object::__construct — Crea un nuevo objeto PDF
- wkhtmltox\Image\Converter — La clase wkhtmltox\Image\Converter
  - wkhtmltox\Image\Converter::__construct — Crea un nuevo convertidor de imágenes
  - wkhtmltox\Image\Converter::convert — Realiza la conversión de la imagen
  - wkhtmltox\Image\Converter::getVersion — Determina la versión del convertidor

# Creación de documentos PostScript

# Introducción

Este módulo permite crear documentos PostScript. Tiene muchas similitudes con la extensión pdf. Actualmente, esta API es prácticamente idéntica y en la mayoría de los casos, solo se reemplazan los prefijos de cada función de pdf_ por ps_. Esto también funciona para las funciones que no tienen significado en el documento PostScript (por ejemplo, la adición de hipervínculos) pero tendrá un efecto si el documento se convierte en PDF.

Los documentos creados por esta extensión son a veces incluso superiores a los documentos creados con la extensión pdf, porque las funciones de rendimiento de texto de pslib pueden manejar el crénage, la división de palabras y las ligaduras que resultan en una mejor visualización de la caja de texto.

# Instalación/Configuración

## Tabla de contenidos

- Requerimientos
- Instalación
- Tipos de recursos

## Requerimientos

Se requiere al menos pslib >= 0.1.12. La biblioteca ps (pslib) está disponible en » http://pslib.sourceforge.net/.

## Instalación

Información sobre la instalación de estas extensiones PECL puede ser encontrada en el capítulo del manual titulado Instalación de extensiones PECL. Otra información como notas sobre nuevas versiones, descargas, fuentes de archivos, información sobre los mantenedores así como un CHANGELOG, pueden ser encontradas aquí: » https://pecl.php.net/package/ps.

## Tipos de recursos

Esta extensión define un recurso de documento PostScript, devuelto por la función ps_new().

# Constantes predefinidas

Estas constantes son definidas por esta extensión, y solo están disponibles si esta extensión ha sido compilada con PHP, o bien cargada en tiempo de ejecución.

Las dos tablas siguientes listan todas las constantes definidas por la extensión ps.

Constantes para line caps
Nombre | Descripción
--- | ---
`ps_LINECAP_BUTT` |
`ps_LINECAP_ROUND` |
`ps_LINECAP_SQUARED` |

Constantes para line joins
Nombre | Descripción
--- | ---
`ps_LINEJOIN_MITER` |
`ps_LINEJOIN_ROUND` |
`ps_LINEJOIN_BEVEL` |

# Funciones de PS

## Información de contacto

Si tiene comentarios, correcciones de errores, mejoras para esta extensión o para pslib, por favor envíeme un correo » steinm@php.net. Cualquier ayuda es bienvenida.

# ps_add_bookmark

(PECL ps >= 1.1.0)

ps_add_bookmark — Añadir un marcapáginas a la página actual

### Descripción

function ps_add_bookmark(
resource `$psdoc`,
string `$text`,
int `$parent` = 0,
int `$open` = 0
): int

Añade un marcapáginas a la página actual. Los marcapáginas normalmente aparecen en los visualizadores de PDF a la izquierda de la página como un árbol jerárquico. Al hacer clic en un marcapáginas saltará a la página en cuestión.

La nota no será visible si el documento es impreso o mostrado, pero será visible si el documento es convertido a PDF, ya sea por Acrobat Distiller™, o por Ghostview.

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

`text`

  El texto usado para mostrar el marcapáginas.

`parent`

  Un marcapáginas previamente creado por esta función que se usa como padre del nuevo marcapáginas.

`open`

  Si `open` es distinto de cero, el visualizador de PDF mostrará el marcapáginas abierto.

### Valores devueltos

El valor devuelto es una referencia al marcapáginas. Sólo se utiliza si el marcapáginas se usa como padre. El valor es mayor que cero si la función tiene éxito. En caso de error se devolverá cero.

### Ver también

- ps_add_launchlink() - Añadir un vínculo que lance un fichero
- ps_add_pdflink() - Añadir un vínculo hacia una página de un segundo documento PDF
- ps_add_weblink() - Añadir un vínculo hacia una ubicación web

# ps_add_launchlink

(PECL ps >= 1.1.0)

ps_add_launchlink — Añadir un vínculo que lance un fichero

### Descripción

function ps_add_launchlink(
resource `$psdoc`,
float `$llx`,
float `$lly`,
float `$urx`,
float `$ury`,
string `$filename`
): bool

Coloca un hipervínculo, en la posición dada, que apunta a un fichero de un programa, el cual se iniciará al hacer clic sobre él. La posición origen del hipervículo es un rectángulo que tiene su esquina inferior izquierda en (llx, lly) y su esquina superior derecha en (urx, ury). El rectángulo tiene por defecto un borde fino azul.

La nota no será visible si el documento es impreso o mostrado, pero será visible si el documento es convertido a PDF, ya sea por Acrobat Distiller™, o por Ghostview.

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

`llx`

  La coordenada x de la esquina inferior izquierda.

`lly`

  La coordenada y de la esquina inferior izquierda.

`urx`

  La coordenada x de la esquina superior derecha.

`ury`

  La coordenada y de la esquina superior derecha.

`filename`

  La ruta del programa a iniciar cuando se haga clic sobre el vínculo.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_add_locallink() - Añadir un vínculo hacia una página del mismo documento
- ps_add_pdflink() - Añadir un vínculo hacia una página de un segundo documento PDF
- ps_add_weblink() - Añadir un vínculo hacia una ubicación web

# ps_add_locallink

(PECL ps >= 1.1.0)

ps_add_locallink — Añadir un vínculo hacia una página del mismo documento

### Descripción

function ps_add_locallink(
resource `$psdoc`,
float `$llx`,
float `$lly`,
float `$urx`,
float `$ury`,
int `$page`,
string `$dest`
): bool

Coloca un hipervínculo, en la posición dada, que apunta a una página del mismo documento. Al hacer clic sobre el vínculo se irá a la página en cuestión. La primera página de un documento tiene el número 1.

La posición origen del hipervículo es un rectángulo que tiene su esquina inferior izquierda en (`llx`, `lly`) y su esquina superior derecha en (`urx`, `ury`). El rectángulo tiene por defecto un borde fino azul.

La nota no será visible si el documento es impreso o mostrado, pero será visible si el documento es convertido a PDF, ya sea por Acrobat Distiller™, o por Ghostview.

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

`llx`

  La coordenada x de la esquina inferior izquierda.

`lly`

  La coordenada y de la esquina inferior izquierda.

`urx`

  La coordenada x de la esquina superior derecha.

`ury`

  La coordenada y de la esquina superior derecha.

`page`

  El número de la página mostrada al hacer clic en el vínculo.

`dest`

  El parámetro `dest` determina cómo visualizar el documento. Puede ser `fitpage`, `fitwidth`, `fitheight`, o `fitbbox`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_add_launchlink() - Añadir un vínculo que lance un fichero
- ps_add_pdflink() - Añadir un vínculo hacia una página de un segundo documento PDF
- ps_add_weblink() - Añadir un vínculo hacia una ubicación web

# ps_add_note

(PECL ps >= 1.1.0)

ps_add_note — Añadir una nota a la página actual

### Descripción

function ps_add_note(
resource `$psdoc`,
float `$llx`,
float `$lly`,
float `$urx`,
float `$ury`,
string `$contents`,
string `$title`,
string `$icon`,
int `$open`
): bool

Añade una nota en una cierta posición del página. Las notas son como pequeñas hojas rectangulares con texto dentro que pueden ser colocadas en cualquer lugar de una página. Se muestran tanto plegadas como desplegadas. Si están desplegadas se utiliza el icono especificado como marcador de posición.

La nota no será visible si el documento es impreso o mostrado, pero será visible si el documento es convertido a PDF, ya sea por Acrobat Distiller™, o por Ghostview.

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

`llx`

  La coordenada x de la esquina inferior izquierda.

`lly`

  La coordenada y de la esquina inferior izquierda.

`urx`

  La coordenada x de la esquina superior derecha.

`ury`

  La coordenada y de la esquina superior derecha.

`contents`

  El texto de la nota.

`title`

  El título de la nota a mostrar en la cabecera de la nota.

`icon`

  El icono mostrado si la nota está plegada. Este parámetro puede ser establecido a `comment`, `insert`, `note`, `paragraph`, `newparagraph`, `key`, o `help`.

`open`

  Si `open` es distinto de cero, la nota se mostrará desplegada después de abrir el documento con un visualizador de pdf.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_add_pdflink() - Añadir un vínculo hacia una página de un segundo documento PDF
- ps_add_launchlink() - Añadir un vínculo que lance un fichero
- ps_add_locallink() - Añadir un vínculo hacia una página del mismo documento
- ps_add_weblink() - Añadir un vínculo hacia una ubicación web

# ps_add_pdflink

(PECL ps >= 1.1.0)

ps_add_pdflink — Añadir un vínculo hacia una página de un segundo documento PDF

### Descripción

function ps_add_pdflink(
resource `$psdoc`,
float `$llx`,
float `$lly`,
float `$urx`,
float `$ury`,
string `$filename`,
int `$page`,
string `$dest`
): bool

Coloca un hipervínculo, en la posición dada, que apunta a un segundo documento pdf. Al hacer clic sobre el vínculo se irá a la página dada del segundo documento. La primera página de un documento tiene el número 1.

La posición origen del hipervículo es un rectángulo que tiene su esquina inferior izquierda en (`llx`, `lly`) y su esquina superior derecha en (`urx`, `ury`). El rectángulo tiene por defecto un borde fino azul.

La nota no será visible si el documento es impreso o mostrado, pero será visible si el documento es convertido a PDF, ya sea por Acrobat Distiller™, o por Ghostview.

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

`llx`

  La coordenada x de la esquina inferior izquierda.

`lly`

  La coordenada y de la esquina inferior izquierda.

`urx`

  La coordenada x de la esquina superior derecha.

`ury`

  La coordenada y de la esquina superior derecha.

`filename`

  El nombre del documento pdf a abrir cuando se haga clic en este vínculo.

`page`

  El número de página del documento pdf destino

`dest`

  El parámetro `dest` determina cómo visualizar el documento. Puede ser `fitpage`, `fitwidth`, `fitheight`, o `fitbbox`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_add_launchlink() - Añadir un vínculo que lance un fichero
- ps_add_locallink() - Añadir un vínculo hacia una página del mismo documento
- ps_add_weblink() - Añadir un vínculo hacia una ubicación web

# ps_add_weblink

(PECL ps >= 1.1.0)

ps_add_weblink — Añadir un vínculo hacia una ubicación web

### Descripción

function ps_add_weblink(
resource `$psdoc`,
float `$llx`,
float `$lly`,
float `$urx`,
float `$ury`,
string `$url`
): bool

Coloca un hipervínculo, en la posición dada, que apunta a una página web. La posición origen del hipervículo es un rectángulo que tiene su esquina inferior izquierda en (`llx`, `lly`) y su esquina superior derecha en (`urx`, `ury`). El rectángulo tiene por defecto un borde fino azul.

La nota no será visible si el documento es impreso o mostrado, pero será visible si el documento es convertido a PDF, ya sea por Acrobat Distiller™, o por Ghostview.

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

`llx`

  La coordenada x de la esquina inferior izquierda.

`lly`

  La coordenada y de la esquina inferior izquierda.

`urx`

  La coordenada x de la esquina superior derecha.

`ury`

  La coordenada y de la esquina superior derecha.

`url`

  El URL del hipervínculo a abrir cuando se haga clic en este vínculo, p.ej. `http://www.php.net`.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_add_launchlink() - Añadir un vínculo que lance un fichero
- ps_add_locallink() - Añadir un vínculo hacia una página del mismo documento
- ps_add_pdflink() - Añadir un vínculo hacia una página de un segundo documento PDF

# ps_arc

(PECL ps >= 1.1.0)

ps_arc — Dibujar un arco en el sentido contrario a las agujas del reloj

### Descripción

function ps_arc(
resource `$psdoc`,
float `$x`,
float `$y`,
float `$radius`,
float `$alpha`,
float `$beta`
): bool

Dibuja una porción de un círculo con su punto medio en (`x`, `y`). El arco comienza en un ángulo dado por `alpha` y termina en un ángulo dado por `beta`. Se dibuja en el sentido contrario al de las agujas del reloj (use la función ps_arcn() para dibujarlo en el sentido de las agujas del reloj). El trazado añadido al trazado actual comienza en el arco con el ángulo `alpha` y termina en el arco con el ángulo `beta`.

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

`x`

  La coordenada x del punto medio del círculo.

`y`

  La coordenada y del punto medio del círculo.

`radius`

  El radio del círculo

`alpha`

  El ángulo de inicio dado en grados.

`beta`

  El ángulo final dado en grados.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_arcn() - Dibujar un arco en el sentido de las agujas del reloj

# ps_arcn

(PECL ps >= 1.1.0)

ps_arcn — Dibujar un arco en el sentido de las agujas del reloj

### Descripción

function ps_arcn(
resource `$psdoc`,
float `$x`,
float `$y`,
float `$radius`,
float `$alpha`,
float `$beta`
): bool

Dibuja una porción de un círculo con su punto medio en (`x`, `y`). El arco comienza en un ángulo dado por `alpha` y termina en un ángulo dado por `beta`. Se dibuja en el sentido de las agujas del reloj (use la función ps_arc() para dibujarlo en sentido contrario al de las agujas del reloj). El trazado añadido al trazado actual comienza en el arco con el ángulo `beta` y termina en el arco con el ángulo `alpha`.

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

`x`

  La coordenada x del punto medio del círculo.

`y`

  La coordenada y del punto medio del círculo.

`radius`

  El radio del círculo

`alpha`

  El ángulo de inicio dado en grados.

`beta`

  El ángulo final dado en grados.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_arc() - Dibujar un arco en el sentido contrario a las agujas del reloj

# ps_begin_page

(PECL ps >= 1.1.0)

ps_begin_page — Empezar una nueva página

### Descripción

function ps_begin_page(resource `$psdoc`, float `$width`, float `$height`): bool

Empiza una nueva página. Aunque los parámetros `width` y `height` implican un tamaño de página diferente para cada página, esto no es posible en PostScript. La primera llamada a la función ps_begin_page() establecerá el tamaño de página para el documento entero. Las llamadas consecutivas no tendrán efecto, excepto para crear una nueva página. La situación es diferente si se intenta convertir el documento PostScript a PDF. Esta función coloca marcas pdf dentro del documento, con lo que se puede establecer el tamaño de cada página individualmente. El documento PDF resultante tendrá diferentes tamaños de página.

Aunque PostScript no conoce diferentes tamaños de página, pslib coloca una caja circundante para cada página dentro del documento. Este tamaño es evaluado por algunos visualizadores de PostScript y tendrá precedencia sobre el campo BoundingBox de la cabecera (Header) del documento. Esto puede llevar a resultados inesperados cuando se establece BoundingBox con su esquina inferior izquierda diferente de (0, 0), ya que la caja circundante de la página siempre tendrá una esquina inferior izquierda (0, 0) y sobrescribirá la configuración global.

Cada página está encapsulada en la forma guardar/restaurar. Esto significa que la mayoría de los ajustes hechos en una página no se conservarán para la siguiente página.

Si hasta la primera llamada a la función ps_begin_page() no existen llamadas a la función ps_findfont(), la cabecera del documento PostScript se imprimirá y la caja circundante será establecida al tamaño de la primera página. La esquina inferior izquierda de la caja circundante se establecerá a (0, 0). Si si llamó antes a la función ps_findfont(), la cabecera ya ha sido impresa, y el documento no tendrá una caja circundante válida. Para prevenir esto, se debería llamar a la función ps_set_info() para establecer el campo de información `BoundingBox` y posiblemente `Orientation` antes de cualquier llamada a las funciones ps_findfont() o ps_begin_page().

> Nota:

> Hasta la versión 0.2.6 de pslib, esta función siempre sobrescribía los campos BoundingBox y Orientation si antes habían sido establecidos con la función ps_set_info() y no se había llamado antes a la función ps_findfont().

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

`width`

  El ancho de la página en píxeles, p.ej. 596 para el formato A4

`height`

  El alto de la página en píxeles, p.ej. 842 para el formato A4

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_end_page() - Finaliza una página
- ps_findfont() - Carga una fuente
- ps_set_info() - Establecer los campos de información del documento

# ps_begin_pattern

(PECL ps >= 1.2.0)

ps_begin_pattern — Inicia un nuevo patrón

### Descripción

function ps_begin_pattern(
resource `$psdoc`,
float `$width`,
float `$height`,
float `$xstep`,
float `$ystep`,
int `$painttype`
): int|false

Inicia un nuevo patrón. Un patrón es como una página que contiene, por ejemplo, un dibujo que puede ser utilizado para rellenar sectores. Se utiliza como un color al llamar a ps_setcolor() y configurando la posición del color en el `patrón`.

### Parámetros

`psdoc`

  Identificador de un archivo postscript devuelto por ps_new().

`width`

  El ancho del patrón en píxeles.

`height`

  La altura del patrón en píxeles.

`xstep`

  La distancia en píxeles de la posición del patrón en la dirección horizontal.

`ystep`

  La distancia en píxeles de la posición del patrón en la dirección vertical.

`painttype`

  Debe ser 1 o 2.

### Valores devueltos

El identificador del patrón o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Creación y utilización de un patrón

    <?php
    $ps = ps_new();

    if (!ps_open_file($ps, "pattern.ps")) {
      print "Imposible abrir el archivo PostScript\n";
      exit;
    }

    ps_set_parameter($ps, "warning", "true");
    ps_set_info($ps, "Creator", "pattern.php");
    ps_set_info($ps, "Author", "Uwe Steinmann");
    ps_set_info($ps, "Title", "Ejemplo de Patrón");

    $pspattern = ps_begin_pattern($ps, 10.0, 10.0, 10.0, 10.0, 1);
    ps_setlinewidth($ps, 0.2);
    ps_setcolor($ps, "stroke", "rgb", 0.0, 0.0, 1.0, 0.0);
    ps_moveto($ps, 0, 0);
    ps_lineto($ps, 7, 7);
    ps_stroke($ps);
    ps_moveto($ps, 0, 7);
    ps_lineto($ps, 7, 0);
    ps_stroke($ps);
    ps_end_pattern($ps);

    ps_begin_page($ps, 596, 842);
    ps_setcolor($ps, "both", "pattern", $pspattern, 0.0, 0.0, 0.0);
    ps_rect($ps, 50, 400, 200, 200);
    ps_fill($ps);
    ps_end_page($ps);

    ps_close($ps);
    ps_delete($ps);
    ?>

### Ver también

- ps_end_pattern() - Finalizar un patrón
- ps_setcolor() - Establece el color actual
- ps_shading_pattern() - Crea un patrón basado en el tono

# ps_begin_template

(PECL ps >= 1.2.0)

ps_begin_template — Iniciar una nueva plantilla

### Descripción

function ps_begin_template(resource `$psdoc`, float `$width`, float `$height`): int

Inicia una nueva plantilla. A una plantilla se le conoce como forma en el lenguaje postscript. Se crea de forma similar a un patrón pero se utiliza como una imagen. Las plantilla a menudo se usan para dibujar algo que se coloca varias veces a lo largo de un documento, p.ej. el logotipo de una compañía. Se puede usar todas las funciones de dibujo dentro de una plantilla. La plantilla no será dibujada hasta que sea colocada mediante la función ps_place_image().

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

`width`

  El ancho de la plantilla en píxeles.

`height`

  El alto de la plantilla en píxeles.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Crear y utilizar una plantilla

    <?php
    $ps = ps_new();

    if (!ps_open_file($ps, "plantilla.ps")) {
      print "No se puede abrir el fichero PostScript\n";
      exit;
    }

    ps_set_parameter($ps, "warning", "true");
    ps_set_info($ps, "Creator", "plantilla.php");
    ps_set_info($ps, "Author", "Uwe Steinmann");
    ps_set_info($ps, "Title", "Ejemplo de plantilla");

    $plantilla_ps = ps_begin_template($ps, 30.0, 30.0);
    ps_moveto($ps, 0, 0);
    ps_lineto($ps, 30, 30);
    ps_moveto($ps, 0, 30);
    ps_lineto($ps, 30, 0);
    ps_stroke($ps);
    ps_end_template($ps);

    ps_begin_page($ps, 596, 842);
    ps_place_image($ps, $plantilla_ps, 20.0, 20.0, 1.0);
    ps_place_image($ps, $plantilla_ps, 50.0, 30.0, 0.5);
    ps_place_image($ps, $plantilla_ps, 70.0, 70.0, 0.6);
    ps_place_image($ps, $plantilla_ps, 30.0, 50.0, 1.3);
    ps_end_page($ps);

    ps_close($ps);
    ps_delete($ps);
    ?>

### Ver también

- ps_end_template() - Finalizar una plantilla

# ps_circle

(PECL ps >= 1.1.0)

ps_circle — Dibujar un círculo

### Descripción

function ps_circle(
resource `$psdoc`,
float `$x`,
float `$y`,
float `$radius`
): bool

Dibuja un círculo con su punto medio en (`x`, `y`). El círculo comienza y termina en la posición (`x`+`radius`, `y`). Si esta función es llamada fuera de un trazado se iniciará un nuevo trazado. Si es llamada dentro de un trazado añadirá el círculo como un subtrazado. Si la última operación de dibujo no finaliza en el punto (`x`+`radius`, `y`) habrá un hueco en el trazado.

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

`x`

  La coordenada x del punto medio del círculo.

`y`

  La coordenada y del punto medio del círculo.

`radius`

  El radio del círculo

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_arc() - Dibujar un arco en el sentido contrario a las agujas del reloj
- ps_arcn() - Dibujar un arco en el sentido de las agujas del reloj

# ps_clip

(PECL ps >= 1.1.0)

ps_clip — Realizar un recorte utilizando el trazado actual

### Descripción

function ps_clip(resource `$psdoc`): bool

Toma el trazado actual y lo usa para definir el borde de un área de recorte. Todo lo dibujado fuera de ese área no será visible.

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_closepath() - Cerrar un trazado

# ps_close

(PECL ps >= 1.1.0)

ps_close — Cerrar un documento PostScript

### Descripción

function ps_close(resource `$psdoc`): bool

Cierra el documento PostScript.

Esta función escribe el tráiler del documento PostScript. También escribe el árbol de marcapáginas. ps_close() no libera ningún recurso, lo que se realiza mediante la función ps_delete().

Esta función también es llamda por la función ps_delete() si no ha sido llamada antes.

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_open_file() - Abrir un fichero para su impresión
- ps_delete() - Borrar todos los recursos de un documento PostScript

# ps_close_image

(PECL ps >= 1.1.0)

ps_close_image — Cierra la imagen y libera la memoria

### Descripción

function ps_close_image(resource `$psdoc`, int `$imageid`): void|false

Cierra una imagen y libera sus recursos. Una vez cerrada la imagen, ya no puede ser utilizada.

### Parámetros

`psdoc`

  Identificador de un fichero postscript devuelto por ps_new().

`imageid`

  Identificador de una imagen devuelto por ps_open_image() o ps_open_image_file().

### Valores devueltos

Devuelve `null` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_open_image() - Leer una imagen para su colocación posterior
- ps_open_image_file() - Abre una imagen desde un fichero

# ps_closepath

(PECL ps >= 1.1.0)

ps_closepath — Cerrar un trazado

### Descripción

function ps_closepath(resource `$psdoc`): bool

Conecta el último punto con el primer punto de un trazado. El trazado resultante puede usarse para contornear, rellenar, recortar, etc...

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_clip() - Realizar un recorte utilizando el trazado actual
- ps_closepath_stroke() - Cerrar y contornear un trazado

# ps_closepath_stroke

(PECL ps >= 1.1.0)

ps_closepath_stroke — Cerrar y contornear un trazado

### Descripción

function ps_closepath_stroke(resource `$psdoc`): bool

Conecta el último punto con el primer punto de un trazado y dibuja la línea cerrada resultante.

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_closepath() - Cerrar un trazado

# ps_continue_text

(PECL ps >= 1.1.0)

ps_continue_text — Continuar el texto en la siguiente línea

### Descripción

function ps_continue_text(resource `$psdoc`, string `$text`): bool

Imprime un texto una línea por debajo de la última línea. La interlínea se toma del valor "leading", el cual debe establecerse con la función ps_set_value(). La posición actual del texto se determina por los valores "textx" y "texty", los cuales pueden solicitarse con la función ps_get_value().

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

`text`

  El texto a imprimir.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_show() - Imprimir texto
- ps_show_xy() - Imprimir texto en una posición dada
- ps_show_boxed() - Escritura de texto en una caja

# ps_curveto

(PECL ps >= 1.1.0)

ps_curveto — Dibujar una curva

### Descripción

function ps_curveto(
resource `$psdoc`,
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$x3`,
float `$y3`
): bool

Añade una sección de una curva cúbica de Bézier al trazado actual descrita por los tres puntos de control dados.

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

`x1`

  La coordenada x del primer punto de control.

`y1`

  La coordenada y del primer punto de control.

`x2`

  La coordenada x del segundo punto de control.

`y2`

  La coordenada y del segundo punto de control.

`x3`

  La coordenada x del tercer punto de control.

`y3`

  La coordenada y del tercer punto de control.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_lineto() - Dibujar una línea

# ps_delete

(PECL ps >= 1.1.0)

ps_delete — Borrar todos los recursos de un documento PostScript

### Descripción

function ps_delete(resource `$psdoc`): bool

Principalmente libera la memoria usada por el documento. También cierra un fichero, si no fue cerrado antes con la función ps_close(). En cualquier caso, antes se debería cerrar el fichero con la función ps_close(), ya que ps_close() no sólo cierra el fichero, sino que también imprime un tráiler que contiene comentarios de PostScript, como el número de páginas del documento, y añade la jerarquía de marcapáginas.

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_close() - Cerrar un documento PostScript

# ps_end_page

(PECL ps >= 1.1.0)

ps_end_page — Finaliza una página

### Descripción

function ps_end_page(resource `$psdoc`): bool

Finaliza una página que ha sido iniciada con ps_begin_page(). Finalizar una página deja el contexto de dibujo actual, lo que por ejemplo requiere recargar las fuentes si fueron cargadas con la página y fija varios otros parámetros de dibujo como el grosor de las líneas, el color.

### Parámetros

`psdoc`

  Identificador de un archivo postscript devuelto por ps_new().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_begin_page() - Empezar una nueva página

# ps_end_pattern

(PECL ps >= 1.2.0)

ps_end_pattern — Finalizar un patrón

### Descripción

function ps_end_pattern(resource `$psdoc`): bool

Finaliza un patrón que fue creado con la función ps_begin_pattern(). Una vez que el patrón ha sido finalizado se puede usar como un color para rellenar áreas.

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_begin_pattern() - Inicia un nuevo patrón

# ps_end_template

(PECL ps >= 1.2.0)

ps_end_template — Finalizar una plantilla

### Descripción

function ps_end_template(resource `$psdoc`): bool

Finaliza una plantilla que fue creada con la función ps_begin_template(). Una vez que la plantilla ha sido finalizada se puede usar como una imagen.

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_begin_template() - Iniciar una nueva plantilla

# ps_fill

(PECL ps >= 1.1.0)

ps_fill — Rellenar el trazado actual

### Descripción

function ps_fill(resource `$psdoc`): bool

Rellena el trazaco construido previamente con llamdas a las funciones de dibujo, como ps_lineto().

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_fill_stroke() - Rellenar y contornear el trazado actual
- ps_stroke() - Dibujar el trazado actual

# ps_fill_stroke

(PECL ps >= 1.1.0)

ps_fill_stroke — Rellenar y contornear el trazado actual

### Descripción

function ps_fill_stroke(resource `$psdoc`): bool

Rellena y dibuja el trazado construido previamente con llamadas a funciones de dibujo, como ps_lineto().

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_fill() - Rellenar el trazado actual
- ps_stroke() - Dibujar el trazado actual

# ps_findfont

(PECL ps >= 1.1.0)

ps_findfont — Carga una fuente

### Descripción

function ps_findfont(
resource `$psdoc`,
string `$fontname`,
string `$encoding`,
bool `$embed` = `false`
): int

ps_findfont() carga una fuente para su uso posterior. Antes de que el texto sea escrito con la fuente cargada, debe ser fijada con ps_setfont(). Esta función debe tener el archivo de métricas de la fuente "adobe" para calcular el espacio utilizado por los caracteres. Una fuente que se carga en una página solo estará disponible en esa página. Las fuentes que se utilizarán en todo el documento deben ser cargadas antes de la primera llamada a ps_begin_page(). La llamada a ps_findfont() entre páginas hará que esta fuente esté disponible para todas las páginas siguientes.

El nombre del archivo afm debe ser `fontname``.afm`. Si la fuente debe ser incorporada, el archivo `fontname``.pfb` que contiene el dibujo de la fuente también debe estar presente.

La llamada a ps_findfont() antes de la primera página requiere mostrar el encabezado del postscript que incluye el BoundingBox para el documento completo. Normalmente, el BoundingBox se fija con la primera llamada a ps_begin_page() que ahora viene después de ps_findfont(). En consecuencia, el BoundingBox no ha sido fijado y se lanzará un error cuando ps_findfont() sea llamada. Para prever esta situación, debe llamarse a la función ps_set_parameter() para fijar el BoundingBox antes de que ps_findfont() sea llamada.

### Parámetros

`psdoc`

  Identificador de un archivo postscript devuelto por ps_new().

`fontname`

  El nombre de la fuente.

`encoding`

  ps_findfont() intentará cargar el archivo pasado en el argumento `encoding`. Los archivos de codificación tienen la misma sintaxis que los utilizados por dvips(1). Contienen un vector de codificación de fuente (que actualmente no se utiliza, pero que debe estar presente) y una lista de ligaduras adicionales para extender la lista de ligaduras derivadas del archivo AFM.

  `encoding` puede ser `null` o una string vacía si se desea utilizar la codificación por omisión (TeXBase1).

  Si la codificación se establece en `builtin` entonces no habrá codificación adicional y se utilizará la codificación específica de la fuente. Esto es muy útil para fuentes con símbolos.

`embed`

  Si se establece en un valor >0, la fuente será incorporada en el documento. Esto requiere la presencia del archivo de dibujo (.pfb).

### Valores devueltos

Devuelve un identificador de la fuente o cero en caso de error. El identificador es un número positivo.

### Ver también

- ps_begin_page() - Empezar una nueva página
- ps_setfont() - Establecer la fuente a usar para la siguiente impresión

# ps_get_buffer

(PECL ps >= 1.1.0)

ps_get_buffer — Obtener el buffer completo que contiene la información generada de PS

### Descripción

function ps_get_buffer(resource `$psdoc`): string

Esta función aún no está implementada. Siempre devolverá una cadena vacía. La idea para una implementación posterior es escribir el contenido del fichero postscript en un buffer interno si se solicita la creación en memoria, y recuperar el contenifo del buffer con esta función. Actualmente, los documentos creados en memoria son enviados al visualizador sin la participación de un buffer.

Advertencia

Esta función está actualmente no documentada; solo la lista de sus argumentos está disponible.

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

### Ver también

- ps_open_file() - Abrir un fichero para su impresión

# ps_get_parameter

(PECL ps >= 1.1.0)

ps_get_parameter — Recupera ciertos parámetros

### Descripción

function ps_get_parameter(resource `$psdoc`, string `$name`, float `$modifier` = ?): string|false

Recupera varios parámetros que han sido establecidos directamente por ps_set_parameter() o indirectamente por una o más funciones. Los parámetros son, por definición, valores de string. Esta función no puede ser utilizada para recuperar los recursos que también han sido establecidos por ps_set_parameter().

El parámetro `name` puede tener una de las siguientes valores.

`fontname`

  El nombre de la fuente actualmente activa o la fuente cuyo identificador es pasado en el parámetro `modifier`.

`fontencoding`

  La codificación de la fuente actualmente activa.

`dottedversion`

  La versión de la biblioteca subyacente pslib en el formato <mayor>.<menor>.<submenor>

`scope`

  El ámbito actual del dibujo. Puede ser un objeto, un documento, `null`, una página, un patrón, un camino, un modelo, un prólogo, una fuente, un glifo.

`ligaturedisolvechar`

  El carácter que descompone una ligadura. Si se utiliza una fuente que contiene una ligadura `ff' y `|` es el carácter para descomponer la ligadura, entonces `f|f' dará dos `f' en lugar de la ligadura `ff'.

`imageencoding`

  La codificación utilizada para codificar las imágenes. Puede ser `hex` o `85`. La codificación hex utiliza dos octetos en el archivo PostScript, cada octeto en una imagen. 85 representa la codificación Ascii85.

`linenumbermode`

  Se establece en `paragraph` si las líneas son numeradas dentro de un párrafo o `box` si son numeradas en una caja que las rodea.

`linebreak`

  Solo utilizado si el texto es mostrado con ps_show_boxed(). Si se establece en `true`, un retorno de carro añadirá un salto de línea.

`parbreak`

  Solo utilizado si el texto es mostrado con ps_show_boxed(). Si se establece en `true`, un retorno de carro iniciará un nuevo párrafo.

`hyphenation`

  Solo utilizado si el texto es mostrado con ps_show_boxed(). Si se establece en `true`, el párrafo será dividido si un diccionario de guiones es establecido y existe.

`hyphendict`

  Nombre del archivo del diccionario utilizado para el patrón de guiones.

### Parámetros

`psdoc`

  Identificador de un archivo postscript devuelto por ps_new().

`name`

  Nombre del parámetro.

`modifier`

  Un identificador requerido si el parámetro de un recurso es requerido, por ejemplo, el tamaño de una imagen. En este caso, el identificador del recurso es pasado.

### Valores devueltos

Devuelve el valor del parámetro o `false` si ocurre un error.

### Ver también

- ps_set_parameter() - Establecer ciertos parámetros

# ps_get_value

(PECL ps >= 1.1.0)

ps_get_value — Recupera ciertos valores

### Descripción

function ps_get_value(resource `$psdoc`, string `$name`, float `$modifier` = ?): float

Recupera varios valores que han sido establecidos por ps_set_value(). Los valores son, por definición, valores de float.

El argumento `name` puede tener uno de los siguientes valores.

`fontsize`

  El tamaño de la fuente actualmente activa o la fuente cuyo identificador se pasa en el argumento `modifier`.

`font`

  La fuente actualmente activa en sí misma.

`imagewidth`

  La anchura de la imagen cuyo identificador se pasa en el argumento `modifier`.

`imageheight`

  La altura de la imagen cuyo identificador se pasa en el argumento `modifier`.

`capheight`

  La altura de una letra mayúscula M en la fuente actualmente activa o la fuente cuyo identificador se pasa en el argumento `modifier`.

`ascender`

  La hampe de la fuente actualmente activa o la fuente cuyo identificador se pasa en el argumento `modifier`.

`descender`

  El jambage de la fuente actualmente activa o la fuente cuyo identificador se pasa en el argumento `modifier`.

`italicangle`

  El parámetro italicangle de la fuente actualmente activa o la fuente cuyo identificador se pasa en el argumento `modifier`.

`underlineposition`

  El parámetro underlineposition de la fuente actualmente activa o la fuente cuyo identificador se pasa en el argumento `modifier`.

`underlinethickness`

  El parámetro underlinethickness de la fuente actualmente activa o la fuente cuyo identificador se pasa en el argumento `modifier`.

`textx`

  La posición x actual de visualización del texto.

`texty`

  La posición y actual de visualización del texto.

`textrendering`

  El modo actual para el renderizado del texto.

`textrise`

  El espacio por el cual el texto es aumentado por encima de la línea de base.

`leading`

  La distancia entre las líneas de texto en puntos.

`wordspacing`

  El espacio entre las palabras como múltiplo de la anchura de un carácter de espacio.

`charspacing`

  El espacio entre los caracteres. Si charspacing es != 0.0, las ligaduras siempre estarán desactivadas.

`hyphenminchars`

  Número mínimo de caracteres antes de un guion al final de una palabra.

`parindent`

  La indentación de las primeras n líneas en un párrafo.

`numindentlines`

  Número de líneas en un párrafo a indentar si paraindent != 0.0.

`parskip`

  Distancia entre los párrafos.

`linenumberspace`

  Espacio general frente a cada línea para el número de línea.

`linenumbersep`

  Espacio entre las líneas y los números de línea.

`major`

  El número de versión mayor de pslib.

`minor`

  El número de versión menor de pslib.

`subminor`, `revision`

  El número de versión submenor de pslib.

### Parámetros

`psdoc`

  Identificador de un archivo postscript devuelto por ps_new().

`name`

  Nombre del valor.

`modifier`

  El argumento `modifier` especifica el recurso para el cual se recuperará el valor. Esto puede ser el ID de la fuente o una imagen.

### Valores devueltos

Devuelve el valor del parámetro o `false`.

### Ver también

- ps_set_value() - Establecer ciertos valores

# ps_hyphenate

(PECL ps >= 1.1.1)

ps_hyphenate — Une palabras

### Descripción

function ps_hyphenate(resource `$psdoc`, string `$text`): array|false

Une la palabra pasada. ps_hyphenate() evalúa la valor hyphenminchars (establecido por ps_set_value()) y el argumento hyphendic (establecido por ps_set_parameter()). hyphendict debe ser establecido antes de llamar a esta función.

Esta función requiere que la configuración local `LC_CTYPE` esté correctamente hecha. Esto se realiza cuando la extensión es inicializada utilizando las variables de entorno. En sistemas Unix, consulte las páginas de manual de locale para más información.

### Parámetros

`psdoc`

  Identificador de un archivo postscript devuelto por ps_new().

`text`
  `text` no debería contener caracteres no alfabéticos. Las posiciones posibles para los cortes son devueltas en un array de números enteros. Cada número es la posición del carácter en `text` después de que la unión pueda tener lugar.

### Valores devueltos

Un array de enteros que indica la posición de los cortes posibles en el texto o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Corta un texto

    <?php
    $word = "Koordinatensystem";
    $psdoc = ps_new();
    ps_set_parameter($psdoc, "hyphendict", "hyph_de.dic");
    $hyphens = ps_hyphenate($psdoc, $word);
    for($i=0; $i<strlen($word); $i++) {
      echo $word[$i];
      if(in_array($i, $hyphens))
        echo "-";
    }
    ps_delete($psdoc);
    ?>

El ejemplo anterior mostrará:

    Ko-ordi-na-ten-sys-tem

### Ver también

- ps_show_boxed() - Escritura de texto en una caja
- locale(1)

# ps_include_file

(PECL ps >= 1.3.4)

ps_include_file — Leer un fichero externo con código PostScript sin tratar

### Descripción

function ps_include_file(resource `$psdoc`, string `$file`): bool

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

`file`

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

# ps_lineto

(PECL ps >= 1.1.0)

ps_lineto — Dibujar una línea

### Descripción

function ps_lineto(resource `$psdoc`, float `$x`, float `$y`): bool

Añade una línea recta al trazado actual desde el punto actual hasta las coordenadas dadas. Use la función ps_moveto() para establecer el punto de inicio de la línea.

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

`x`

  La coordenada x del punto final de la línea.

`y`

  La coordenada y del punto final de la línea.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ejemplos

Ejemplo #1 Dibujar un rectángulo

    <?php
    $ps = ps_new();
    if (!ps_open_file($ps, "rectángulo.ps")) {
      print "No se puede abrir el fichero PostScript\n";
      exit;
    }

    ps_set_info($ps, "Creator", "rectángulo.php");
    ps_set_info($ps, "Author", "Uwe Steinmann");
    ps_set_info($ps, "Title", "Ejemplo de lineto");

    ps_begin_page($ps, 596, 842);
    ps_moveto($ps, 100, 100);
    ps_lineto($ps, 100, 200);
    ps_lineto($ps, 200, 200);
    ps_lineto($ps, 200, 100);
    ps_lineto($ps, 100, 100);
    ps_stroke($ps);
    ps_end_page($ps);

    ps_delete($ps);
    ?>

### Ver también

- ps_moveto() - Establecer el punto actual

# ps_makespotcolor

(PECL ps >= 1.1.0)

ps_makespotcolor — Crear un color directo

### Descripción

function ps_makespotcolor(resource `$psdoc`, string `$name`, int `$reserved` = 0): int

Crea un color directo desde el color de relleno actual. El color de relleno debe ser definido en los espacios de color RGB, CMYK o gris. El nombre del color directo puede ser un nombre arbitrario. Un color directo se puede establecer como cualquier otro color con la función ps_setcolor(). Cuando el documento no se imprime, sino que se muestra con un visualizador de postscript, se utiliza el color dado en el espacio de color especificado.

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

`name`

  El nombre del color directo, p.ej. Pantone 5565.

### Valores devueltos

El ID del nuevo color directo o 0 en caso de error.

### Ejemplos

Ejemplo #1 Crear y utilizar un color directo

    <?php
    $ps = ps_new();
    if (!ps_open_file($ps, "color_directo.ps")) {
      print "No se puede abrir el fichero PostScript\n";
      exit;
    }

    ps_set_info($ps, "Creator", "color_directo.php");
    ps_set_info($ps, "Author", "Uwe Steinmann");
    ps_set_info($ps, "Title", "Ejemplo de color directo");

    ps_begin_page($ps, 596, 842);
    ps_setcolor($ps, "fill", "cmyk", 0.37, 0.0, 0.34, 0.34);
    $color_directo = ps_makespotcolor($ps, "PANTONE 5565 C", 0);
    ps_setcolor($ps, "fill", "spot", $color_directo, 0.5, 0.0, 0.0);
    ps_moveto($ps, 100, 100);
    ps_lineto($ps, 100, 200);
    ps_lineto($ps, 200, 200);
    ps_lineto($ps, 200, 100);
    ps_lineto($ps, 100, 100);
    ps_fill($ps);
    ps_end_page($ps);

    ps_delete($ps);
    ?>

Este ejemplo crea el color directo "PANTONE 5565 C" que es un verde oscuro (oliva) y rellena un rectángulo con el 50% de intensidad.

### Ver también

- ps_setcolor() - Establece el color actual

# ps_moveto

(PECL ps >= 1.1.0)

ps_moveto — Establecer el punto actual

### Descripción

function ps_moveto(resource `$psdoc`, float `$x`, float `$y`): bool

Establece el punto actual a unas coordenadas nuevas. Si esta es la primera llamada a la función ps_moveto() después de haber finalizado un trazado previo, se iniciará un nuevo trazado. Si esta función es llamada en mitad de un trazado establecerá el punto actual e iniciará un subtrazado.

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

`x`

  La coordenada x del punto al que moverse.

`y`

  La coordenada y del punto al que moverse.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_lineto() - Dibujar una línea

# ps_new

(PECL ps >= 1.1.0)

ps_new — Crea un nuevo objeto de documento PostScript

### Descripción

function ps_new(): resource|false

Crea una nueva instancia de documento. No crea el fichero en el disco ni en la memoria. Simplemente prepara todo. ps_new() es normalmente seguida por una llamada a ps_open_file() para crear el documento PostScript.

### Parámetros

Esta función no contiene ningún parámetro.

### Valores devueltos

Recurso de un documento PostScript o `false` si ocurre un error. El valor de retorno es pasado a todas las demás funciones como primer argumento.

### Ver también

- ps_delete() - Borrar todos los recursos de un documento PostScript

# ps_open_file

(PECL ps >= 1.1.0)

ps_open_file — Abrir un fichero para su impresión

### Descripción

function ps_open_file(resource `$psdoc`, string `$filename` = ?): bool

Crea un fichero en disco y escribe el documento PostScript en él. El fichero será cerrado cuando se llame a la función ps_close().

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

`filename`

  El nombre del fichero postscript. Si no se proporciona `filename` el documento será creado en memoria y todas las salidas irán directas al visualizador.

### Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

### Ver también

- ps_close() - Cerrar un documento PostScript

# ps_open_image

(PECL ps >= 1.1.0)

ps_open_image — Leer una imagen para su colocación posterior

### Descripción

function ps_open_image(
resource `$psdoc`,
string `$type`,
string `$source`,
string `$data`,
int `$length`,
int `$width`,
int `$height`,
int `$components`,
int `$bpc`,
string `$params`
): int

Lee una imagen que ya está disponible en memoria. El parámetro `source` actualmente no se evalua y se asume que es `memory`. La información de la imagen es una secuencia de píxeles que comienza en la esquina superior izquierda y termina en la esquina inferior derecha. Cada píxel consiste en componentes de color dados por `components`, y cada componente tiene `bpc` bits.

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

`type`

  El tipo de la imagen. Los posibles valores son `png`, `jpeg`, o `eps`.

`source`

  No se utiliza.

`data`

  La información de la imagen.

`length`

  La longitud de la información de la imagen.

`width`

  El ancho de la imagen.

`height`

  El alto de la imagen.

`components`

  El número de componentes de cada píxel. Puede ser 1 (imágenes en escala de grises), 3 (imágenes rgb), o 4 (imágenes cmyk, rgba).

`bpc`

  Número de bits por componente (normalmente 8).

`params`

### Valores devueltos

Devuelve el identificador de la imagen, o cero en caso de error. El identificador es un número positivo mayor que 0.

### Ver también

- ps_open_image_file() - Abre una imagen desde un fichero
- ps_place_image() - Colocar una imágen en la página
- ps_close_image() - Cierra la imagen y libera la memoria

# ps_open_image_file

(PECL ps >= 1.1.0)

ps_open_image_file — Abre una imagen desde un fichero

### Descripción

function ps_open_image_file(
resource `$psdoc`,
string `$type`,
string `$filename`,
string `$stringparam` = ?,
int `$intparam` = 0
): int

Carga una imagen para su uso posterior.

### Parámetros

`psdoc`

  El identificador de recursos del fichero postscript, como el devuelto por la función ps_new().

`type`

  El tipo de la imagen. Los posibles valores son `png`, `jpeg`, o `eps`.

`filename`

  El nombre del fichero que contiene la información de la imagen.

`stringparam`

  No se utiliza.

`intparam`

  No se utiliza.

### Valores devueltos

Devuelve el identificador de la imagen, o cero en caso de error. El identificador es un número positivo mayor que 0.

### Ver también

- ps_open_image() - Leer una imagen para su colocación posterior
- ps_place_image() - Colocar una imágen en la página
- ps_close_image() - Cierra la imagen y libera la memoria

# ps_open_memory_image

(PECL ps >= 1.1.0)

ps_open_memory_image — Tomar una imagen de GD y devolverla como una imagen para colcarla en un documento PS

### Descripción

function ps_open_memory_image(resource `$psdoc`,
[file cut: first 33554432 bytes kept]
